{"id":48076801,"url":"https://github.com/inqwise-opinion/opinion-front-ui","last_synced_at":"2026-04-04T14:50:24.439Z","repository":{"id":314781670,"uuid":"1056610775","full_name":"inqwise-opinion/opinion-front-ui","owner":"inqwise-opinion","description":"A modern TypeScript SPA for the Opinion survey system—migrated from a servlet-based Java app. Built with micro-kernel architecture, event-driven communication, reactive data binding, and hotkey support for efficient form building and analysis.","archived":false,"fork":false,"pushed_at":"2026-03-31T09:02:24.000Z","size":4875,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T10:26:22.489Z","etag":null,"topics":["event-driven-architecture","frontend","hotkeys","inqwise","microkernel","reactive-programming","spa","survey","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inqwise-opinion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T13:04:39.000Z","updated_at":"2026-03-31T09:01:11.000Z","dependencies_parsed_at":"2025-09-14T19:38:36.350Z","dependency_job_id":"782c3208-7f0e-4476-949c-46371aa9aaa4","html_url":"https://github.com/inqwise-opinion/opinion-front-ui","commit_stats":null,"previous_names":["inqwise-opinion/opinion-front-ui"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/inqwise-opinion/opinion-front-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise-opinion%2Fopinion-front-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise-opinion%2Fopinion-front-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise-opinion%2Fopinion-front-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise-opinion%2Fopinion-front-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inqwise-opinion","download_url":"https://codeload.github.com/inqwise-opinion/opinion-front-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise-opinion%2Fopinion-front-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-driven-architecture","frontend","hotkeys","inqwise","microkernel","reactive-programming","spa","survey","typescript"],"created_at":"2026-04-04T14:50:23.612Z","updated_at":"2026-04-04T14:50:24.433Z","avatar_url":"https://github.com/inqwise-opinion.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Opinion Front UI\n\n[![CI Pipeline](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/codeql.yml/badge.svg)](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/codeql.yml)\n[![Release](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/release.yml/badge.svg)](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/release.yml)\n[![GitHub release](https://img.shields.io/github/v/release/inqwise-opinion/opinion-front-ui?include_prereleases\u0026sort=semver)](https://github.com/inqwise-opinion/opinion-front-ui/releases)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.2.2-blue.svg)](https://www.typescriptlang.org/)\n[![Vite](https://img.shields.io/badge/Vite-7.1.3-646CFF.svg)](https://vitejs.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**A modern TypeScript front-end application** for the Opinion survey management platform, featuring a sophisticated **micro-kernel architecture** with **event-driven communication**, **reactive data binding**, and comprehensive **chain-based hotkey system**. Successfully migrated from a servlet-based Java system to a cutting-edge single-page application.\n\n## 📊 Project Status\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/inqwise-opinion/opinion-front-ui/ci.yml?branch=main\u0026label=build)](https://github.com/inqwise-opinion/opinion-front-ui/actions/workflows/ci.yml)\n[![Test Coverage](https://img.shields.io/badge/coverage-43%25-yellow)](https://github.com/inqwise-opinion/opinion-front-ui)\n[![Dependencies](https://img.shields.io/librariesio/github/inqwise-opinion/opinion-front-ui?label=dependencies)](https://libraries.io/github/inqwise-opinion/opinion-front-ui)\n[![Package Dependencies](https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen)](https://shields.io/category/dependencies)\n[![Security](https://img.shields.io/github/actions/workflow/status/inqwise-opinion/opinion-front-ui/codeql.yml?branch=main\u0026label=security)](https://github.com/inqwise-opinion/opinion-front-ui/security)\n[![Known Vulnerabilities](https://snyk.io/test/github/inqwise-opinion/opinion-front-ui/badge.svg)](https://snyk.io/test/github/inqwise-opinion/opinion-front-ui)\n[![Issues](https://img.shields.io/github/issues/inqwise-opinion/opinion-front-ui)](https://github.com/inqwise-opinion/opinion-front-ui/issues)\n[![Pull Requests](https://img.shields.io/github/issues-pr/inqwise-opinion/opinion-front-ui)](https://github.com/inqwise-opinion/opinion-front-ui/pulls)\n[![Last Commit](https://img.shields.io/github/last-commit/inqwise-opinion/opinion-front-ui)](https://github.com/inqwise-opinion/opinion-front-ui/commits/main)\n[![Stars](https://img.shields.io/github/stars/inqwise-opinion/opinion-front-ui)](https://github.com/inqwise-opinion/opinion-front-ui/stargazers)\n\n## Project Overview\n\nThis project represents a **complete architectural migration** from a traditional servlet-based Java application to a modern TypeScript SPA. The application features a **micro-kernel architecture** with component-based design, **event-driven communication**, **reactive data binding**, **chain-based hotkey system**, and advanced layout management with comprehensive test coverage.\n\n## Architecture\n\n### Core Technologies\n- **TypeScript**: Modern JavaScript with strict typing and ES2020 target\n- **Vite**: Lightning-fast development server and build tool\n- **SCSS + CSS**: Hybrid styling with CSS Grid + Flexbox layout system\n- **Jest**: Comprehensive testing framework with JSDOM environment\n\n### Design Patterns\n- **Micro-kernel Architecture**: Central `LayoutContext` kernel with pluggable components and services\n- **Event-Driven Communication**: Global EventBus with publish/subscribe/request patterns\n- **Reactive Data Binding**: Observable pattern with validators and transformers\n- **Chain-Based Hotkey System**: Priority-based hotkey handling with conflict resolution\n- **Component Lifecycle Management**: Abstract `PageComponent` base class with init/destroy patterns\n- **Service-Oriented Architecture**: Dependency injection with service registry\n- **Hierarchical Breadcrumbs**: Scoped breadcrumb management with page-level control\n\n## Getting Started\n\n### Prerequisites\n\n- **Node.js** \u003e= 20.0.0 (as specified in package.json engines)\n- **npm** \u003e= 10.0.0\n- Modern browser with CSS Grid and ES2020 support\n- **Material Icons** font (loaded via Google Fonts)\n\n### Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Run tests\nnpm test\n```\n\n### Development Scripts\n\n- `npm run dev` - Start development server\n- `npm run build` - Build for production\n- `npm run preview` - Preview production build\n- `npm run test` - Run tests\n- `npm run test:watch` - Run tests in watch mode\n- `npm run lint` - Run ESLint\n- `npm run lint:fix` - Fix linting issues\n\n**Note**: Development server runs on port 3000 with `SASS_SILENCE_DEPRECATIONS=legacy-js-api` to suppress SASS warnings.\n\n## Current Status\n\n**Development Phase**: Active development with core architecture complete\n\n### ✅ Completed Features\n- **Micro-Kernel Architecture**: LayoutContext as application kernel with service registry\n- **Event-Driven Communication**: Comprehensive EventBus with publish/subscribe/request patterns\n- **Reactive Data Binding**: Observable pattern with ComputedObservables, validators, and transformers\n- **Chain-Based Hotkey System**: Priority-based hotkey handling with conflict resolution (ESC key chains)\n- **Component Architecture**: Abstract `PageComponent` with lifecycle management and event handling\n- **Service Architecture**: Dependency injection, service registration, and interface contracts\n- **Layout System**: CSS Grid + Flexbox responsive design with breakpoint management\n- **Hierarchical Breadcrumbs**: Page-scoped breadcrumb management with safe operations\n- **Comprehensive Test Coverage**: 564 tests with 43% overall coverage, 97% config coverage, 93% utilities coverage\n- **Global Layout Components**: Header, Sidebar, Footer with responsive coordination\n- **Navigation Synchronization**: Active page tracking with automatic menu highlighting\n- **Error Handling**: Global error boundary with user-friendly messages and recovery\n- **Development Dashboard**: Enhanced dashboard with mock API integration and statistics\n\n### 🚧 In Progress\n- **Real API Integration**: Replace MockApiService with actual backend APIs\n- **Survey Builder**: Advanced survey creation and editing interface\n- **Data Visualization**: Enhanced charts and analytics for dashboard\n- **Mobile Optimization**: Touch interactions and mobile-specific UX improvements\n\n## Test Coverage\n\nThe project maintains comprehensive test coverage across all system components:\n\n### Overall Coverage: **43%** (564 tests)\n\n```\n File                              | % Stmts | % Branch | % Funcs | % Lines\n-----------------------------------|---------|----------|---------|--------\n All files                         |   43.06 |    34.39 |   40.71 |   43.89\n  src                              |   38.66 |    28.88 |   39.53 |   39.53\n  src/api                          |      30 |        0 |   33.33 |      30\n  src/components                   |   45.36 |    34.78 |   44.07 |   46.53\n  src/contexts                     |   65.78 |    45.45 |   56.25 |   68.42\n  src/events                       |   90.32 |       75 |   83.33 |   90.32\n  src/hotkeys                      |   86.36 |    77.27 |   85.18 |   86.36\n  src/observables                  |   87.50 |    75.00 |   80.00 |   87.50\n  src/pages                        |   28.94 |    21.21 |   33.33 |   29.72\n  src/services                     |   62.50 |       25 |   57.14 |   62.50\n  src/utils                        |   93.33 |    83.33 |      100 |   93.33\n  src/utils/config                 |      100 |      100 |      100 |      100\n```\n\n### Key Testing Achievements\n- **🔥 Hotkey System**: 86% coverage with comprehensive chain execution tests\n- **📡 Event System**: 90% coverage with EventBus integration tests\n- **📊 Observables**: 87% coverage with reactive data binding tests\n- **⚙️ Configuration**: 100% coverage with environment config tests\n- **🛠️ Utilities**: 93% coverage with helper function tests\n- **🏗️ Context System**: 66% coverage with LayoutContext integration tests\n\n### Test Categories\n- **Unit Tests**: Component lifecycle, service logic, utility functions\n- **Integration Tests**: EventBus communication, hotkey chains, breadcrumb scoping\n- **DOM Tests**: Component rendering, event handling, responsive behavior\n- **Architecture Tests**: Service registration, dependency injection, error handling\n\n## 📚 Comprehensive Documentation\n\n### Core Documentation\n- **[DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md)** - Complete developer guide with code examples and patterns\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed system architecture and component design\n- **[STATUS_REPORT.md](STATUS_REPORT.md)** - Current project status and achievements\n- **[WARP.md](WARP.md)** - AI agent guidance with MCP integration and development workflows\n\n### System Architecture Documentation\n\n#### **🏗️ Layout \u0026 UI Systems**\n- **[layout-architecture.md](docs/layout-architecture.md)** - CSS Grid + Flexbox layout system design\n- **[layout-mode-system.md](docs/layout-mode-system.md)** - Responsive breakpoint management\n- **[component-hierarchy.md](docs/component-hierarchy.md)** - UI component organization and relationships\n- **[layout-context-access-patterns.md](docs/layout-context-access-patterns.md)** - LayoutContext usage patterns\n\n#### **📡 Event \u0026 Communication Systems**\n- **[event-system.md](docs/event-system.md)** - EventBus architecture with publish/subscribe/request patterns\n- **[eventbus-integration.md](docs/eventbus-integration.md)** - EventBus integration guidelines and best practices\n- **[active-page-eventbus-system.md](docs/active-page-eventbus-system.md)** - Page-level event coordination\n\n#### **⌨️ Hotkey \u0026 Input Management**\n- **[hotkey-chain-architecture.md](docs/hotkey-chain-architecture.md)** - Priority-based chain execution system\n- **[hotkey-system-components.md](docs/hotkey-system-components.md)** - Hotkey provider implementation details\n- **[hotkey-system-migration.md](docs/hotkey-system-migration.md)** - Migration from legacy to chain-based system\n- **[src/hotkeys/README.md](src/hotkeys/README.md)** - Implementation code documentation\n\n#### **🍞 Navigation \u0026 Breadcrumbs**\n- **[breadcrumbs-architecture.md](docs/breadcrumbs-architecture.md)** - Hierarchical breadcrumb system with page scoping\n- **[layout-navigation.md](docs/layout-navigation.md)** - Navigation patterns and routing integration\n\n#### **🏢 Service Architecture**\n- **[service-architecture-progress.md](docs/service-architecture-progress.md)** - Service implementation progress and roadmap\n- **[service-interfaces.md](docs/service-interfaces.md)** - Service interface specifications and contracts\n- **[unified-handler-system.md](docs/unified-handler-system.md)** - Handler pattern implementation\n\n#### **🛠️ Implementation \u0026 Development**\n- **[implementation-summary.md](docs/implementation-summary.md)** - Overall implementation overview\n- **[initialization-flow.md](docs/initialization-flow.md)** - Application startup sequence and lifecycle\n\n#### **🧪 Testing \u0026 Quality**\n- **[error-message-tests.md](docs/error-message-tests.md)** - Error handling test patterns and examples\n- **[error-messages.md](docs/error-messages.md)** - Global error message system documentation\n- **[browser-warning-fixes.md](docs/browser-warning-fixes.md)** - Browser compatibility fixes and solutions\n\n## 🤖 MCP Integration\n\n### Model Context Protocol Support\n\nThis project integrates with MCP (Model Context Protocol) tools for enhanced development workflows:\n\n#### **Available MCP Tools**\n\n**🌐 Browser Automation \u0026 Testing:**\n- `execute_browser_action` - Smart browser automation with chrome-devtools integration\n- `take_screenshot` - Visual verification and regression testing\n- `take_snapshot` - DOM state inspection and component analysis\n- `navigate_page` - URL navigation and page state management\n- `click`, `fill`, `hover` - Interactive element testing and automation\n- `evaluate_script` - JavaScript execution in browser context\n- `list_console_messages` - Console monitoring for errors and warnings\n- `list_network_requests` - API request analysis and debugging\n\n**🔍 Performance \u0026 Debug Analysis:**\n- `performance_start_trace` - Performance profiling with Core Web Vitals\n- `performance_analyze_insight` - Detailed bottleneck analysis and optimization\n- `analyze_visual_diff` - Visual regression detection between UI states\n- `fix_my_app` - Comprehensive error detection with fix recommendations\n- `fix_my_jank` - Layout shift and performance issue identification\n- `find_component_source` - Map DOM elements to source code locations\n\n**📚 Documentation \u0026 Code Analysis:**\n- `search_generic_code` - GitHub repository code pattern search\n- `fetch_generic_documentation` - Complete repository documentation retrieval\n- `get-library-docs` - Library-specific documentation with version support\n- `resolve-library-id` - Library identification for documentation lookup\n\n#### **MCP Development Workflows**\n\n**Performance Testing Workflow:**\n```typescript\n// 1. Start performance trace for Core Web Vitals analysis\n// 2. Navigate to http://localhost:3000 for page testing  \n// 3. Take screenshots for visual verification\n// 4. Stop trace and analyze performance bottlenecks\n// 5. Use fix_my_jank for layout shift detection\n```\n\n**Component Debugging Workflow:**\n```typescript\n// 1. Take DOM snapshot to inspect component state\n// 2. Use find_component_source to locate element source files\n// 3. Execute browser actions for interaction testing\n// 4. Monitor console messages for runtime errors\n// 5. Analyze network requests for API integration issues\n```\n\n**Visual Testing Workflow:**\n```typescript\n// 1. Take before/after screenshots during development\n// 2. Use analyze_visual_diff to detect layout changes\n// 3. Verify responsive behavior across breakpoints\n// 4. Test component interactions with browser automation\n```\n\n### MCP Integration Benefits\n- **Enhanced Development**: Real-time performance monitoring and optimization\n- **Visual Testing**: Automated screenshot comparison and regression detection\n- **Debug Assistance**: Component source mapping and error analysis\n- **Documentation**: Automated library documentation and code pattern discovery\n- **Performance**: Core Web Vitals monitoring and layout shift detection\n\n### 📋 Planned Features\n- **Survey Management**: Create, edit, manage surveys\n- **Data Visualization**: Charts and analytics dashboard\n- **User Authentication**: Token-based authentication system\n- **Real API Integration**: Replace mock service with actual backend\n\n## Migration Context\n\nThis project represents a **complete architectural migration** from a servlet-based Java application:\n\n### Migration Approach\n1. **Preserved Structure**: Maintains familiar DOM structure from original application\n2. **Modernized Patterns**: Replaced server-side rendering with SPA architecture\n3. **Enhanced UX**: Added responsive design and modern UI patterns\n4. **Type Safety**: Full TypeScript implementation with strict typing\n5. **Component Lifecycle**: Systematic component initialization and cleanup\n\n## Troubleshooting\n\n### Development Issues\n\n#### **FOUC (Flash of Unstyled Content)**\nThe application prevents FOUC through:\n- Direct CSS preloading in index.html\n- Smart script timing with CSS ready checks\n- Material Icons with `font-display: swap`\n\n#### **Browser Warnings**\n- **H1 styling warnings**: Fixed with explicit `.brand-title` styling\n- **Layout forced warnings**: Prevented with proper CSS loading sequence\n- **InstallTrigger warnings** (Firefox dev only): Safe to ignore - from Vite dev server\n\n#### **Layout Issues**\n- **Content not scrolling**: Check `.app-content-scroll` has `overflow-y: auto`\n- **Footer positioning**: Verify `min-height: 0` on scroll containers\n- **Sidebar overlapping**: Confirm CSS Grid variables match sidebar width\n\n#### **Console Debugging**\nThe application uses emoji-prefixed console logging:\n- 🚀 Main application lifecycle\n- 🎯 Routing and navigation\n- 🏗️ Component initialization\n- ✅ Success states / ❌ Error states\n\n### Performance\n- **CSS Grid + Flexbox**: Hardware-accelerated layout\n- **Viewport constraints**: 100vh grid prevents body overflow\n- **Component lifecycle**: Proper cleanup prevents memory leaks\n\n## 🚀 Preview Deployments\n\n**GitHub Pages Integration**: Every pull request automatically gets a preview deployment!\n\n### How it works\n- **Automatic**: When you create or update a PR, GitHub Actions builds and deploys a preview\n- **Unique URLs**: Each PR gets its own subdirectory: `https://inqwise-opinion.github.io/opinion-front-ui/pr-123/`\n- **PR Comments**: A bot comments on your PR with the preview link and deployment details\n- **Auto Cleanup**: Previews are automatically removed when PRs are closed/merged\n\n### Preview URLs\n- **Preview Index**: [https://inqwise-opinion.github.io/opinion-front-ui/](https://inqwise-opinion.github.io/opinion-front-ui/) - Lists all active previews\n- **PR Preview Example**: `https://inqwise-opinion.github.io/opinion-front-ui/pr-42/` - Individual PR preview\n\n### For Reviewers\n1. Check the PR comment for the preview link\n2. Test the preview deployment before approving\n3. Verify responsive behavior and functionality\n4. Check browser console for any errors\n\n### For Contributors\n- Preview deployments happen automatically - no action needed\n- Preview is updated every time you push to your PR branch\n- Use the preview to validate your changes before requesting review\n\n## 🔍 Dependencies \u0026 Security Monitoring\n\n### Dependency Tracking\n- **[Libraries.io](https://libraries.io/github/inqwise-opinion/opinion-front-ui)**: Comprehensive dependency monitoring and alerts\n- **[Shields.io Dependencies](https://shields.io/category/dependencies)**: Real-time dependency status badges\n- **[Snyk](https://snyk.io/test/github/inqwise-opinion/opinion-front-ui)**: Security vulnerability scanning\n\n### Security Monitoring\n- **CodeQL Analysis**: Automated security scanning via GitHub Security tab\n- **Dependabot**: Automated dependency updates and security alerts\n- **npm audit**: Regular security audits in CI pipeline\n\n### Dependency Management\n```bash\n# Check for outdated dependencies\nnpm outdated\n\n# Check for security vulnerabilities\nnpm audit\n\n# Fix security issues automatically\nnpm audit fix\n\n# Update dependencies (be careful with major version changes)\nnpm update\n```\n\n## Contributing\n\n1. Follow TypeScript best practices\n2. Maintain consistent code formatting with ESLint\n3. Write tests for new features\n4. Update documentation as needed\n5. Use semantic commit messages\n6. Test responsive behavior across breakpoints\n7. **Check the preview deployment** before requesting review\n8. **Run `npm audit`** before submitting PRs to check for security issues\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finqwise-opinion%2Fopinion-front-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finqwise-opinion%2Fopinion-front-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finqwise-opinion%2Fopinion-front-ui/lists"}