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