diff --git a/.rules/colors.md b/.rules/colors.md index 77add7bb..2679e856 100644 --- a/.rules/colors.md +++ b/.rules/colors.md @@ -1,4 +1,3 @@ - `getVariableMap(colors.orange)` generates the css variables below. ```json @@ -17,7 +16,9 @@ "--color-primary-950": "#172554"; } ``` + and `getColorMap('primary')` generates the following object + ```js { "500": 'var(--color-primary-500)', @@ -33,32 +34,29 @@ and `getColorMap('primary')` generates the following object Using `shorcuts` configuration in unocss.config.js I am able to change the colors using `bg-primary-500` styles. Unocss config. + ```js -shortcuts= [ - ['skin-orange', getVariableMap(colors.orange)], - ['skin-green', getVariableMap(colors.green)] -], -colors = { - primary: getColorMap('primary') -} +;((shortcuts = [ + ['skin-orange', getVariableMap(colors.orange)], + ['skin-green', getVariableMap(colors.green)] +]), + (colors = { + primary: getColorMap('primary') + })) ``` The html and css are below. ```html
-
- This is an orange section. -
+
This is an orange section.
This is an orange section with opacity.
-
- This is an orange section. -
+
This is an orange section.
This is an orange section with opacity.
@@ -66,10 +64,10 @@ The html and css are below. ``` ```css -[data-skin="orange"]{ +[data-skin='orange'] { @apply skin-orange; } -[data-skin="green"]{ +[data-skin='green'] { @apply skin-green; } ``` @@ -78,11 +76,7 @@ I am able to get the `bg-primary-500` style to work with the css variables as co I needed to use the variables to switch the primary and secondary colors in the system, and I want to continue using the `bg-primary-500` or `bg-primary-500/20` css styles. - - - - ['theme-colors', theme.getPalette(mapping)], - ['vibrant', theme.getPalette({ primary: 'blue', secondary: 'purple' })], +['vibrant', theme.getPalette({ primary: 'blue', secondary: 'purple' })], I was able to generate custom rules using the approach below diff --git a/.rules/guidelines/styles.md b/.rules/guidelines/styles.md index 6ea400a2..85a8a95b 100644 --- a/.rules/guidelines/styles.md +++ b/.rules/guidelines/styles.md @@ -12,7 +12,7 @@ This document defines the conventions for separating theme and layout styles, an - **Purpose:** Control colors, gradients, shadows, border colors, and other visual tokens that define the "look and feel" of a theme. - **Location:** `packages/themes/src/rokkit/` -- **Examples:** +- **Examples:** - Background and text colors - Gradients - Border colors @@ -135,4 +135,4 @@ This document defines the conventions for separating theme and layout styles, an - See `rokkit/input.css` and `base/input.css` for implementation patterns. - For further questions, consult the project maintainers or open a discussion in the repo. ---- \ No newline at end of file +--- diff --git a/.rules/project/progress.md b/.rules/project/progress.md index 580c3129..9b970356 100644 --- a/.rules/project/progress.md +++ b/.rules/project/progress.md @@ -5,6 +5,7 @@ **Status**: Active Development - Forms system architecture implemented, progressive tutorial creation in progress, input styles migration for InputField complete (see guidelines/styles.md, input.css) ## Foundation Status (✅ Completed) + - [x] Svelte 5 migration with runes system - [x] Core package architecture established - [x] Build system operational @@ -16,6 +17,7 @@ ## Forms System Status ### Core Architecture (✅ Completed) + - [x] FormBuilder class with reactive state management - [x] Separate validation state with dedicated methods - [x] Property composition system (schema + layout + validation → props) @@ -25,70 +27,79 @@ - [x] Flexible arbitrary property support from layout ### Components Implementation -| Component | Status | Implementation Notes | -|-----------|--------|---------------------| -| FormBuilder | ✅ Complete | Three-parameter constructor, separate validation state | -| Input.svelte | ✅ Complete | Universal wrapper with type-aware layouts | -| FormRenderer | ✅ Complete | Snippet-based rendering with defaultInput and child | -| Validation Utility | ✅ Complete | Schema-based validation with message objects | + +| Component | Status | Implementation Notes | +| ------------------ | ----------- | ------------------------------------------------------ | +| FormBuilder | ✅ Complete | Three-parameter constructor, separate validation state | +| Input.svelte | ✅ Complete | Universal wrapper with type-aware layouts | +| FormRenderer | ✅ Complete | Snippet-based rendering with defaultInput and child | +| Validation Utility | ✅ Complete | Schema-based validation with message objects | ### Tutorial Implementation -| Section | Status | Description | URL | -|---------|--------|-------------|-----| -| Main Tutorial Page | ✅ Complete | Progressive navigation with sidebar | `/forms` | -| 1. Input Components | ✅ Complete | Universal Input examples and properties | `/forms/inputs` | -| 2. FormBuilder | ✅ Complete | Data-driven form creation with schema/layout | `/forms/builder` | -| 3. FormRenderer | 🔄 In Progress | Snippet-based rendering and customization | `/forms/renderer` | -| 4. Validation | 📋 Planned | Real-time validation and message handling | `/forms/validation` | -| 5. Advanced Features | 📋 Planned | Custom snippets and complex layouts | `/forms/advanced` | + +| Section | Status | Description | URL | +| -------------------- | -------------- | -------------------------------------------- | ------------------- | +| Main Tutorial Page | ✅ Complete | Progressive navigation with sidebar | `/forms` | +| 1. Input Components | ✅ Complete | Universal Input examples and properties | `/forms/inputs` | +| 2. FormBuilder | ✅ Complete | Data-driven form creation with schema/layout | `/forms/builder` | +| 3. FormRenderer | 🔄 In Progress | Snippet-based rendering and customization | `/forms/renderer` | +| 4. Validation | 📋 Planned | Real-time validation and message handling | `/forms/validation` | +| 5. Advanced Features | 📋 Planned | Custom snippets and complex layouts | `/forms/advanced` | ### Shared Components -| Component | Status | Description | Location | -|-----------|--------|-------------|----------| -| CodeViewer | ✅ Complete | Demo component with source code display and copy functionality | `tutorial/CodeViewer.svelte` | -| Demo Loader | ✅ Complete | Utility for loading demo components and source code | `tutorial/demo-loader.js` | -| Source Code API | ✅ Complete | API endpoint for serving demo source files securely | `/api/source-code` | -| Syntax Highlighting | ✅ Complete | Shiki.js integration for code highlighting | `$lib/shiki.js` | + +| Component | Status | Description | Location | +| ------------------- | ----------- | -------------------------------------------------------------- | ---------------------------- | +| CodeViewer | ✅ Complete | Demo component with source code display and copy functionality | `tutorial/CodeViewer.svelte` | +| Demo Loader | ✅ Complete | Utility for loading demo components and source code | `tutorial/demo-loader.js` | +| Source Code API | ✅ Complete | API endpoint for serving demo source files securely | `/api/source-code` | +| Syntax Highlighting | ✅ Complete | Shiki.js integration for code highlighting | `$lib/shiki.js` | ### Component Migration Status (Background Task) ### Selection Components -| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | -|-----------|-----------------|-------------------|---------------------| -| List | ✅ Complete | 🔄 Custom approach | Core pattern - field mapping priority | -| Tabs | ✅ Complete | 📋 bits-ui/tabs | Direct migration candidate | -| Select | ✅ Complete | 📋 bits-ui/select | Complex - requires field mapping preservation | -| MultiSelect | ✅ Complete | 📋 bits-ui/listbox | Custom behavior needed for multi-selection | -| Switch | ✅ Complete | 📋 bits-ui/toggle-group | Simple migration | -| DropDown | ✅ Complete | 📋 bits-ui/dropdown-menu | Architecture decision needed | - -### Hierarchical Components -| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | -|-----------|-----------------|-------------------|---------------------| -| Tree | ✅ Complete | ❌ No equivalent | Full custom implementation required | -| Accordion | ✅ Complete | 📋 bits-ui/accordion | Direct migration with field mapping | + +| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | +| ----------- | --------------- | ------------------------ | --------------------------------------------- | +| List | ✅ Complete | 🔄 Custom approach | Core pattern - field mapping priority | +| Tabs | ✅ Complete | 📋 bits-ui/tabs | Direct migration candidate | +| Select | ✅ Complete | 📋 bits-ui/select | Complex - requires field mapping preservation | +| MultiSelect | ✅ Complete | 📋 bits-ui/listbox | Custom behavior needed for multi-selection | +| Switch | ✅ Complete | 📋 bits-ui/toggle-group | Simple migration | +| DropDown | ✅ Complete | 📋 bits-ui/dropdown-menu | Architecture decision needed | + +### Hierarchical Components + +| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | +| --------- | --------------- | -------------------- | ----------------------------------- | +| Tree | ✅ Complete | ❌ No equivalent | Full custom implementation required | +| Accordion | ✅ Complete | 📋 bits-ui/accordion | Direct migration with field mapping | ### Data Components -| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | -|-----------|-----------------|-------------------|---------------------| -| Table | ✅ Complete | ❌ No equivalent | Complex data handling - custom required | + +| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | +| --------- | --------------- | ------------------- | --------------------------------------- | +| Table | ✅ Complete | ❌ No equivalent | Complex data handling - custom required | ### Input Components -| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | -|-----------|-----------------|-------------------|---------------------| -| Rating | ✅ Complete | ❌ No equivalent | Custom input component | -| Range | ✅ Complete | 📋 bits-ui/slider | Feature gap analysis needed | + +| Component | Svelte 5 Status | bits-ui Integration | Implementation Notes | +| --------- | --------------- | ------------------- | --------------------------- | +| Rating | ✅ Complete | ❌ No equivalent | Custom input component | +| Range | ✅ Complete | 📋 bits-ui/slider | Feature gap analysis needed | ### Primitive Components (Complete) -| Component | Status | Notes | -|-----------|--------|-------| -| Icon | ✅ Complete | No migration needed | -| Item | ✅ Complete | Core rendering primitive | -| Pill | ✅ Complete | Wrapper component | + +| Component | Status | Notes | +| --------- | ----------- | ------------------------ | +| Icon | ✅ Complete | No migration needed | +| Item | ✅ Complete | Core rendering primitive | +| Pill | ✅ Complete | Wrapper component | ## Implementation Priorities ### Tutorial System (Recently Completed) + 1. **CodeViewer Component** - ✅ Complete - Reusable component for demo display with source code viewing 2. **Demo Structure** - ✅ Complete - Standardized src/App.svelte pattern for maintainable demos 3. **Source Code Loading** - ✅ Complete - API endpoint and fallback strategies for code display @@ -97,21 +108,25 @@ 6. **Code Highlighting** - ✅ Complete - Shiki.js integration for syntax highlighting ### Forms System (Active) + 1. **FormRenderer Tutorial** (`/forms/renderer`) - Complete snippet-based rendering examples 2. **Validation Tutorial** (`/forms/validation`) - Real-time validation and user-action triggers 3. **Advanced Features Tutorial** (`/forms/advanced`) - Custom snippets, nested forms, complex layouts ### Critical Path Components (Background) + 1. **List** - Establishes core data-driven patterns for all other components 2. **Select** - Tests field mapping complexity with bits-ui integration 3. **Tree** - Custom implementation reference for components without bits-ui equivalents ### Input Styles Migration (In Progress) -| Task | Status | Notes | -|------|--------|-------| + +| Task | Status | Notes | +| -------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- | | Input styles migration to theme/layout split | ✅ Complete | InputField styles refactored: theme/layout split, data-attribute selectors, guidelines added | ### Integration Strategy + - **bits-ui Components**: Wrap with Rokkit API layer maintaining field mapping - **Custom Components**: Build with accessibility patterns inspired by bits-ui - **API Preservation**: Maintain existing component interfaces during transition @@ -119,16 +134,19 @@ ## Technical Requirements ### Field Mapping System Preservation + - All components must maintain current field mapping capabilities - `fields` prop must work identically across bits-ui and custom components - Dynamic component selection via `using` prop must be preserved ### Accessibility Standards + - WCAG 2.1 AA compliance for all components - Keyboard navigation patterns consistent with bits-ui standards - Screen reader compatibility maintained or improved ### Performance Constraints + - Bundle size impact from bits-ui must be justified by accessibility gains - Component rendering performance must not degrade - Tree-shaking must work effectively with wrapper approach @@ -136,6 +154,7 @@ ## Implementation Guidelines ### Component Migration Checklist + When working on any component: - [ ] Preserve existing API surface (items, value, fields, using props) @@ -148,6 +167,7 @@ When working on any component: - [ ] Update documentation examples ### Quality Requirements + All components must meet: - [ ] Field mapping system preserved and working @@ -162,6 +182,7 @@ All components must meet: ### Technical Decisions Made ### InputField Styles Migration (May 2024) + - Migrated all InputField component styles to new theme/layout split: - Theme styles (colors, gradients, border colors, error/disabled states) moved to `packages/themes/src/rokkit/input.css` - Layout styles (spacing, flex, structure, sizing) moved to `packages/themes/src/base/input.css` @@ -170,6 +191,7 @@ All components must meet: - Updated this progress file to track and document the migration ### Forms System Decisions + - **Separate Validation State**: Independent validation management from data/schema/layout - **Element Structure**: `{ scope, type, value, override, props }` pattern with JSON Pointer scopes - **Property Composition**: Schema + layout + validation merged into single props object @@ -180,6 +202,7 @@ All components must meet: - **Browser Compatibility**: Fixed URL constructor issues for cross-environment compatibility ### Tutorial System Decisions + - **Demo Structure**: Standardized `src/App.svelte` pattern for maintainable tutorial demos - **Source Code Loading**: Multi-strategy approach (API endpoint, raw imports, error on failure) - **Component Separation**: CodeViewer as shared component, demo-loader as utility module @@ -190,12 +213,14 @@ All components must meet: - **Code Safety**: Proper HTML escaping and error boundaries ### Architecture Decisions (Background) + - **Field Mapping Priority**: Preserve existing field mapping system over bits-ui native patterns - **Wrapper Strategy**: Use bits-ui as foundation but wrap with Rokkit API layer - **Custom Components**: Build without bits-ui for components with no equivalent - **Backward Compatibility**: Maintain existing APIs during transition ### Component-Specific Decisions + - **Forms**: Complete custom implementation with accessibility patterns - **List**: Custom implementation with bits-ui accessibility patterns as reference - **Tree/Table**: Full custom implementation due to complexity and no bits-ui equivalent @@ -205,6 +230,7 @@ All components must meet: ## LLM Development Notes ### When Working on Tutorial System + 1. **Use CodeViewer for demos** - Replace hardcoded examples with CodeViewer components 2. **Follow demo structure** - Create `src/App.svelte` files for reusable, testable demos 3. **Show errors clearly** - Display error messages instead of hardcoded fallback code @@ -213,6 +239,7 @@ All components must meet: 6. **Proper error handling** - Use try/catch blocks and show meaningful error messages ### When Working on Forms System + 1. **Maintain separate validation state** - validation should be user-action triggered, not automatic 2. **Preserve element structure** - scope, type, value, override, props pattern is critical 3. **Support arbitrary properties** - layout can contain any custom properties for components @@ -220,6 +247,7 @@ All components must meet: 5. **Use UnoCSS conventions** - neutral colors, semantic colors, dark mode support ### When Working on Components (Background) + 1. **Always check existing patterns** in `sites/learn/src/lib/stories/` for current API expectations 2. **Field mapping is critical** - any component handling data must support the `fields` prop 3. **Snippet support required** - users expect to customize rendering via snippets @@ -227,6 +255,7 @@ All components must meet: 5. **Performance matters** - test with realistic datasets (100-1000+ items) ### Tutorial System Patterns + - Demo structure: `tutorial/{section}/{topic}/src/App.svelte` - CodeViewer usage: `` - Demo loading: `const demo = await loadDemo('section/topic')` @@ -236,6 +265,7 @@ All components must meet: - Error boundaries: Proper try/catch blocks and HTML escaping ### Forms System Patterns + - FormBuilder constructor: `new FormBuilder(data, schema?, layout?)` - Element structure: `{ scope, type, value, override, props }` - JSON Pointer scopes: `#/fieldPath` format @@ -244,15 +274,17 @@ All components must meet: - Snippet selection: defaultInput vs child based on override flag ### Common Patterns to Maintain (Background) + - `items` prop for data arrays -- `value` prop with `$bindable()` for selections +- `value` prop with `$bindable()` for selections - `fields` prop for data mapping configuration - `using` prop for component overrides - Standard event patterns (select, change, move) - Snippet support for customization ### Integration Strategy Notes + - bits-ui provides accessibility foundation but may not support our data-driven patterns - Custom wrapper layer needed to preserve field mapping - Some components will remain fully custom (Tree, Table, Rating) -- Bundle size impact must be measured and justified \ No newline at end of file +- Bundle size impact must be measured and justified diff --git a/docs/CODEVIEWER_USAGE.md b/docs/CODEVIEWER_USAGE.md index cd87f3d6..a525ecec 100644 --- a/docs/CODEVIEWER_USAGE.md +++ b/docs/CODEVIEWER_USAGE.md @@ -19,6 +19,7 @@ tutorial/ ``` **Example `src/App.svelte`:** + ```svelte