diff --git a/.rules/architecture/constraints.md b/.rules/architecture/constraints.md index c983e25d7..5a6c42c37 100644 --- a/.rules/architecture/constraints.md +++ b/.rules/architecture/constraints.md @@ -5,18 +5,21 @@ ### Framework Dependencies #### Svelte 5 Requirements + - **Minimum Version**: Svelte ^5.0.0 - **Reasoning**: Runes system is fundamental to our reactive architecture - **Impact**: Cannot support Svelte 4 components without major API changes - **Migration Path**: Wrapper components for legacy support #### Node.js Compatibility + - **Minimum Version**: Node.js >= 18.0.0 - **Reasoning**: ESM support, modern JavaScript features - **Build Targets**: ES2022+ for optimal performance - **Legacy Support**: Transpilation for older browsers via build tools #### TypeScript Integration + - **Requirement**: Full TypeScript support for all public APIs - **Generic Support**: Components must support generic type parameters - **Type Safety**: Runtime validation only in development mode @@ -25,12 +28,14 @@ ### Bundle Size Constraints #### Core Package Limits + - **@rokkit/core**: < 15KB gzipped - **@rokkit/ui**: < 50KB gzipped (full bundle) - **Individual Components**: < 5KB gzipped each - **Tree Shaking**: All exports must be tree-shakeable #### Performance Budgets + - **Initial Load**: < 100KB total for basic usage - **Component Import**: < 10KB additional per component - **Runtime Overhead**: < 5% compared to vanilla implementation @@ -38,17 +43,20 @@ ### Browser Support #### Modern Browsers (Primary Support) + - Chrome >= 90 - Firefox >= 88 - Safari >= 14 - Edge >= 90 #### Legacy Support (Best Effort) + - IE: Not supported - Chrome < 90: Via build tool transpilation - Safari < 14: Limited feature support #### Required Features + - ES Modules - CSS Custom Properties - ResizeObserver @@ -59,7 +67,9 @@ ### API Consistency Requirements #### Component Interface Pattern + All selection components MUST follow: + ```typescript interface SelectionComponent { items: T[] @@ -70,6 +80,7 @@ interface SelectionComponent { ``` #### Event Pattern Consistency + ```typescript interface ComponentEvents { select: CustomEvent<{ value: T }> @@ -78,6 +89,7 @@ interface ComponentEvents { ``` #### Field Mapping System + - MUST support nested field access - MUST provide default field mappings - MUST be runtime configurable @@ -86,12 +98,14 @@ interface ComponentEvents { ### Component Composability Rules #### Snippet System Requirements + - All components MUST support snippet-based customization - Default snippets MUST be provided for all render points - Snippet parameters MUST be consistently typed - No component should require external styling #### Using System Constraints + - Component override system MUST work with any Svelte component - Default components MUST be replaceable - Type system MUST understand component swapping @@ -100,18 +114,21 @@ interface ComponentEvents { ### Accessibility Constraints #### WCAG 2.1 AA Compliance + - All interactive components MUST meet AA standards - Keyboard navigation MUST be complete and intuitive - Screen reader support MUST be comprehensive - Focus management MUST be proper #### Required ARIA Support + - All components MUST have appropriate roles - Dynamic content MUST announce changes - Complex widgets MUST have proper relationships - Error states MUST be announced #### Keyboard Navigation Standards + - Arrow keys for list navigation - Enter/Space for activation - Escape for dismissal @@ -122,18 +139,21 @@ interface ComponentEvents { ### Svelte-Specific Constraints #### Reactivity System Limitations + - Cannot break reactivity chains with intermediate functions - Derived values must be pure computations - Effects must handle cleanup properly - State mutations must be direct for reactivity #### Component System Limits + - Circular component references not supported - Dynamic component imports require specific patterns - Context API has performance implications at scale - SSR requires careful hydration handling #### Bundle Strategy Constraints + - Components cannot share complex internal state - Tree shaking requires careful export structure - Code splitting boundaries must be component-level @@ -142,12 +162,14 @@ interface ComponentEvents { ### Data Flow Constraints #### Field Mapping Limitations + - Deep nesting has performance implications (>5 levels) - Circular references in data cause infinite loops - Function-based mappings break SSR - Dynamic field changes trigger full re-renders #### Performance Boundaries + - Lists >1000 items require virtual scrolling - Deep object comparison is O(n) complexity - Frequent field mapping changes cause thrashing @@ -156,12 +178,14 @@ interface ComponentEvents { ### bits-ui Integration Constraints #### Wrapper Layer Requirements + - Cannot modify bits-ui component internals - Must maintain API compatibility layer - Event handling must be proxied - Styling must work through CSS variables #### Feature Gaps + - Some Rokkit features have no bits-ui equivalent - Custom behaviors require workaround implementations - Performance characteristics may differ @@ -172,12 +196,14 @@ interface ComponentEvents { ### Package Distribution #### NPM Publishing Requirements + - All packages MUST use same versioning scheme - Dependencies MUST be explicitly declared - Peer dependencies MUST be minimal - Breaking changes MUST follow semver #### CDN Delivery Constraints + - UMD builds for script tag usage - ES modules for modern bundlers - CSS must be separately loadable @@ -186,12 +212,14 @@ interface ComponentEvents { ### Framework Integration Limits #### SvelteKit Compatibility + - Must work with both SSR and SPA modes - Cannot rely on browser-only APIs during SSR - Hydration must be seamless - App directory structure must be respected #### Build Tool Requirements + - Vite: Primary support with official plugin - Webpack: Community support only - Rollup: Basic compatibility @@ -200,18 +228,21 @@ interface ComponentEvents { ## Security Constraints ### XSS Prevention + - No innerHTML usage without sanitization - User content must be escaped by default - Dynamic script execution prohibited - Event handlers must be properly scoped ### Content Security Policy + - No inline styles in components (CSP compliance) - No eval() or Function() constructor usage - External resource loading must be explicit - Script sources must be whitelisted ### Dependency Security + - Regular security audits required - No dependencies with known vulnerabilities - Minimal dependency tree to reduce attack surface @@ -220,18 +251,21 @@ interface ComponentEvents { ## Data Processing Constraints ### Memory Management + - Components must not leak memory - Event listeners must be properly cleaned up - Large datasets must use streaming approaches - Circular references must be avoided ### Performance Limits + - Initial render: < 16ms for 60fps - Update operations: < 5ms for smooth interaction - Memory usage: < 10MB for typical applications - CPU usage: < 10% for idle state ### Scalability Boundaries + - Maximum recommended items per component: 10,000 - Maximum nesting depth: 10 levels - Maximum concurrent components: 1,000 @@ -240,18 +274,21 @@ interface ComponentEvents { ## Future Constraint Considerations ### Svelte Evolution + - Must be adaptable to future Svelte versions - Cannot rely on unstable internal APIs - Must follow Svelte ecosystem best practices - Should leverage new features when stable ### Web Standards Evolution + - Must work with evolving browser standards - Should adopt new web APIs when beneficial - Must maintain backwards compatibility - Should progressive enhance with new features ### Ecosystem Changes + - Must adapt to CSS framework evolution - Should integrate with new accessibility tools - Must work with evolving build tools @@ -260,18 +297,21 @@ interface ComponentEvents { ## Breaking Change Policy ### Allowed Breaking Changes + - Major version bumps only - 6-month minimum notice period - Clear migration path provided - Deprecated API support for 2 versions ### Protected APIs + - Core component props (items, value, fields) - Event emission patterns - Basic accessibility features - Field mapping system fundamentals ### Change Management + - RFC process for major changes - Community feedback period - Beta releases for validation @@ -280,19 +320,22 @@ interface ComponentEvents { ## Exception Handling ### Constraint Violations + - Document all exceptions with rationale - Time-bound exceptions with review dates - Alternative solutions must be provided - Impact assessment required ### Emergency Overrides + - Critical security issues - Major browser breaking changes - Ecosystem-wide migrations - Performance critical optimizations ### Review Process + - Quarterly constraint review - Exception audit and cleanup - Performance budget adjustments -- Technology update assessments \ No newline at end of file +- Technology update assessments diff --git a/.rules/architecture/patterns.md b/.rules/architecture/patterns.md index e3e3ecd48..c79fb0b3a 100644 --- a/.rules/architecture/patterns.md +++ b/.rules/architecture/patterns.md @@ -10,7 +10,7 @@ Every Rokkit component follows this structural pattern: