snice 4.28.0 → 4.30.0

package/docs/ai/components/recipe.md

@@ -4,67 +4,63 @@ Interactive recipe card with ingredient scaling, step-by-step mode, per-step tim
 
 ## Properties
 
-```ts
-title: string                            // Recipe title
-description: string                      // Short description
-image: string                            // Hero image URL
-author: string                           // Author name
-prepTime: number                         // Prep time in minutes (attr: prep-time)
-cookTime: number                         // Cook time in minutes (attr: cook-time)
-servings: number                         // Base serving count (default: 4)
-difficulty: 'easy' | 'medium' | 'hard'  // Difficulty level (default: 'medium')
-cuisine: string                          // Cuisine type (shown as tag)
-variant: 'card' | 'full'                // Display variant (default: 'full')
-ingredients: RecipeIngredient[]          // Ingredient list
-steps: RecipeStep[]                      // Instruction steps
-nutrition: RecipeNutrition | null        // Nutrition facts per serving
-tags: string[]                           // Recipe tags
+```typescript
+title: string = '';
+description: string = '';
+image: string = '';                          // Hero image URL
+author: string = '';
+prepTime: number = 0;                       // attr: prep-time, minutes
+cookTime: number = 0;                       // attr: cook-time, minutes
+servings: number = 4;
+difficulty: 'easy'|'medium'|'hard' = 'medium';
+cuisine: string = '';                        // Shown as tag
+variant: 'card'|'full' = 'full';
+ingredients: RecipeIngredient[] = [];        // JS only
+steps: RecipeStep[] = [];                    // JS only
+nutrition: RecipeNutrition | null = null;    // JS only
+tags: string[] = [];                         // JS only
 ```
 
-### Types
+## Types
 
-```ts
+```typescript
 interface RecipeIngredient {
-  name: string;
-  amount: number;
-  unit: string;
-  group?: string;                        // Group header for ingredient sections
+  name: string; amount: number; unit: string; group?: string;
 }
-
 interface RecipeStep {
-  text: string;
-  image?: string;                        // Step photo URL
-  tip?: string;                          // Pro tip text
-  time?: number;                         // Timer duration in minutes
+  text: string; image?: string; tip?: string; time?: number; // minutes
 }
-
 interface RecipeNutrition {
-  calories: number;
-  protein: number;
-  carbs: number;
-  fat: number;
-  fiber?: number;
-  sodium?: number;                       // in mg
+  calories: number; protein: number; carbs: number; fat: number;
+  fiber?: number; sodium?: number;
 }
 ```
 
 ## Methods
 
-- `setServings(count: number)` -- Adjust serving count (scales ingredients)
-- `print()` -- Print the recipe
-- `reset()` -- Reset checked ingredients, completed steps, timers, and servings
+- `setServings(count)` - Adjust serving count (scales ingredients)
+- `print()` - Print the recipe
+- `reset()` - Reset checked ingredients, completed steps, timers, servings
 
 ## Events
 
-- `recipe-serving-change` -> `{ servings: number; previousServings: number }` -- Serving count changed
-- `recipe-step-complete` -> `{ stepIndex: number; completed: boolean }` -- Step toggled
-- `recipe-ingredient-check` -> `{ ingredientIndex: number; checked: boolean; ingredient: RecipeIngredient }` -- Ingredient checked/unchecked
+- `recipe-serving-change` → `{ servings: number, previousServings: number }`
+- `recipe-step-complete` → `{ stepIndex: number, completed: boolean }`
+- `recipe-ingredient-check` → `{ ingredientIndex: number, checked: boolean, ingredient: RecipeIngredient }`
 
 ## CSS Parts
 
-`container`, `hero`, `header`, `meta`, `content`, `ingredients`, `steps`, `nutrition`, `controls`
+- `container` - Outer recipe container
+- `hero` - Hero image area
+- `header` - Title/description/author
+- `meta` - Metadata bar (times, servings, difficulty)
+- `content` - Main content (ingredients + steps)
+- `ingredients` - Ingredients section
+- `steps` - Instructions section
+- `nutrition` - Nutrition facts panel
+- `controls` - Bottom control buttons
 
-## Usage
+## Basic Usage
 
 ```typescript
 recipe.title = 'Pasta Carbonara';
@@ -81,9 +77,15 @@ recipe.ingredients = [
 ];
 recipe.steps = [
   { text: 'Boil pasta in salted water.', time: 10 },
-  { text: 'Fry pancetta until crispy.', tip: 'Use medium heat to render fat slowly.' },
+  { text: 'Fry pancetta until crispy.', tip: 'Use medium heat.' },
   { text: 'Mix eggs and parmesan.' },
   { text: 'Combine all ingredients off heat.' }
 ];
 recipe.nutrition = { calories: 650, protein: 28, carbs: 72, fat: 24 };
 ```
+
+## Accessibility
+
+- Keyboard accessible checkboxes, step toggles, and timer buttons
+- Serving adjuster buttons have aria-labels
+- Print-friendly layout via `print()`

package/docs/ai/components/sankey.md

@@ -5,36 +5,39 @@ SVG-based Sankey diagram for flow visualization between categories.
 ## Properties
 
 ```typescript
-data: SankeyData = { nodes: [], links: [] };
-nodeWidth: number = 20;
-nodePadding: number = 10;
+data: SankeyData = { nodes: [], links: [] }; // JS only
+nodeWidth: number = 20;              // attr: node-width
+nodePadding: number = 10;            // attr: node-padding
 alignment: 'left'|'right'|'center'|'justify' = 'justify';
-showLabels: boolean = true;
-showValues: boolean = true;
+showLabels: boolean = true;          // attr: show-labels
+showValues: boolean = true;          // attr: show-values
 animation: boolean = false;
 ```
 
 ## Types
 
 ```typescript
-interface SankeyData {
-  nodes: SankeyNode[];
-  links: SankeyLink[];
-}
+interface SankeyData { nodes: SankeyNode[]; links: SankeyLink[]; }
 interface SankeyNode { id: string; label?: string; color?: string; }
 interface SankeyLink { source: string; target: string; value: number; color?: string; }
 ```
 
 ## Events
 
-- `sankey-node-click` → `{ node: SankeyNode }` — node clicked
-- `sankey-link-click` → `{ link: SankeyLink }` — link clicked
-- `sankey-hover` → `{ type: 'node'|'link', item: SankeyNode|SankeyLink } | null` — hover change
+- `sankey-node-click` → `{ node: SankeyNode }`
+- `sankey-link-click` → `{ link: SankeyLink }`
+- `sankey-hover` → `{ type: 'node'|'link', item } | null`
 
-## Usage
+## CSS Parts
+
+- `base` - Outer container
+- `chart` - SVG chart area
+- `tooltip` - Hover tooltip
+
+## Basic Usage
 
 ```html
-<snice-sankey show-labels show-values animation></snice-sankey>
+<snice-sankey show-labels show-values animation style="height: 300px;"></snice-sankey>
 ```
 
 ```typescript
@@ -49,20 +52,8 @@ sankey.data = {
 };
 ```
 
-**CSS Parts:**
-- `base` - The outer Sankey container
-- `chart` - The SVG chart area
-- `tooltip` - The hover tooltip element
-
-## Features
+## Accessibility
 
-- SVG rendering with curved bezier link paths
-- Sankey layout algorithm with iterative node relaxation
-- Link width proportional to flow value
-- Hover highlighting (dims non-connected nodes/links)
-- Tooltips on hover for nodes and links
-- Responsive sizing via ResizeObserver
-- Animation on initial render
-- 4 alignment modes
-- Custom node/link colors
-- Accessible: role="img" with aria-label
+- SVG `role="img"` with `aria-label`
+- Hover highlighting dims non-connected elements
+- Responsive via ResizeObserver

package/docs/ai/components/scheduler.md

@@ -5,33 +5,25 @@ Multi-resource week/day/month scheduler with drag-to-create, move, and resize ev
 ## Properties
 
 ```typescript
-resources: SchedulerResource[] = []      // Resource list (JS only)
-events: SchedulerEvent[] = []            // Event list (JS only)
-view: SchedulerView = 'week'             // 'day' | 'week' | 'month'
-date: Date | string = new Date()         // Current date
-granularity: number = 60                 // Slot size in minutes (15, 30, 60)
-startHour: number = 0                    // attribute: start-hour
-endHour: number = 24                     // attribute: end-hour
+resources: SchedulerResource[] = [];    // JS only
+events: SchedulerEvent[] = [];          // JS only
+view: 'day'|'week'|'month' = 'week';
+date: Date | string = new Date();
+granularity: number = 60;               // Slot size in minutes (15, 30, 60)
+startHour: number = 0;                  // attr: start-hour
+endHour: number = 24;                   // attr: end-hour
 ```
 
 ## Types
 
 ```typescript
 interface SchedulerResource {
-  id: string | number;
-  name: string;
-  avatar?: string;    // Avatar image URL
-  color?: string;     // Accent color
+  id: string | number; name: string; avatar?: string; color?: string;
 }
-
 interface SchedulerEvent {
-  id: string | number;
-  resourceId: string | number;
-  start: Date | string;
-  end: Date | string;
-  title: string;
-  color?: string;
-  data?: any;
+  id: string | number; resourceId: string | number;
+  start: Date | string; end: Date | string;
+  title: string; color?: string; data?: any;
 }
 ```
 
@@ -41,23 +33,23 @@ interface SchedulerEvent {
 - `removeEvent(id: string | number)` - Remove event by ID
 - `scrollToDate(date: Date | string)` - Navigate to date
 - `scrollToResource(id: string | number)` - Scroll resource into view
-- `navigatePrev()` - Go to previous period
-- `navigateNext()` - Go to next period
-- `navigateToday()` - Go to today
 
 ## Events
 
-- `event-create` → `{ event: SchedulerEvent }` - Drag-created event
-- `event-move` → `{ event: SchedulerEvent; oldResourceId: string | number; oldStart: Date | string; oldEnd: Date | string }`
-- `event-resize` → `{ event: SchedulerEvent; oldStart: Date | string; oldEnd: Date | string }`
+- `event-create` → `{ event: SchedulerEvent }`
+- `event-move` → `{ event, oldResourceId, oldStart, oldEnd }`
+- `event-resize` → `{ event, oldStart, oldEnd }`
 - `event-click` → `{ event: SchedulerEvent }`
-- `slot-click` → `{ resourceId: string | number; start: Date; end: Date }`
+- `slot-click` → `{ resourceId, start: Date, end: Date }`
 
-## Slots
+## CSS Parts
 
-None
+- `base` - Main container
+- `header` - Navigation header with view toggle
+- `resources` - Resource sidebar
+- `grid` - Time grid area
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-scheduler start-hour="8" end-hour="18" granularity="30"></snice-scheduler>
@@ -66,23 +58,19 @@ None
 ```typescript
 scheduler.resources = [
   { id: '1', name: 'Dr. Smith', color: '#2196f3' },
-  { id: '2', name: 'Room A', color: '#ff9800' },
+  { id: '2', name: 'Room A', color: '#ff9800' }
 ];
 scheduler.events = [
-  { id: '1', resourceId: '1', start: new Date(2025,5,15,9,0), end: new Date(2025,5,15,10,30), title: 'Consultation' },
+  { id: '1', resourceId: '1', start: new Date(2025,5,15,9,0), end: new Date(2025,5,15,10,30), title: 'Consultation' }
 ];
 
-scheduler.addEventListener('event-click', e => console.log(e.detail.event));
-scheduler.addEventListener('slot-click', e => console.log(e.detail.resourceId, e.detail.start));
+scheduler.addEventListener('slot-click', e => {
+  scheduler.addEvent({ id: Date.now(), resourceId: e.detail.resourceId, start: e.detail.start, end: e.detail.end, title: 'New' });
+});
 ```
 
-## Features
+## Accessibility
 
-- Day/week/month view toggle
-- Resource sidebar with avatars and colors
-- Drag to move events between resources
-- Resize events via edge handles
-- Click empty slots to trigger slot-click
-- Drag on grid to create events
+- Keyboard navigation with arrow keys
+- ARIA labels on resources and time slots
 - Current time indicator
-- Today/prev/next navigation

package/docs/ai/components/segmented-control.md

@@ -6,42 +6,38 @@ Multi-option switcher with sliding indicator. One selected at a time.
 
 ```typescript
 value: string = '';
-options: SegmentedControlOption[] = [];  // { value, label, icon?, disabled? }
+options: SegmentedControlOption[] = [];  // JS only: { value, label, icon?, disabled? }
 size: 'small'|'medium'|'large' = 'medium';
 disabled: boolean = false;
 ```
 
+## Events
+
+- `value-change` → `{ value: string, previousValue: string, option: SegmentedControlOption, control }`
+
 ## CSS Parts
 
 - `base` - Root container
 - `indicator` - Sliding selection indicator
 - `segment` - Individual option button
 
-## Events
-
-- `value-change` → `{ value, previousValue, option, control }`
-
-## Usage
+## Basic Usage
 
 ```html
-<snice-segmented-control></snice-segmented-control>
+<snice-segmented-control value="week"></snice-segmented-control>
 ```
 
 ```typescript
 control.options = [
   { value: 'day', label: 'Day' },
   { value: 'week', label: 'Week' },
-  { value: 'month', label: 'Month' },
+  { value: 'month', label: 'Month' }
 ];
-control.value = 'week';
 control.addEventListener('value-change', (e) => console.log(e.detail.value));
 ```
 
-## Notes
+## Accessibility
 
-- Options set via JS property (array), not child elements
+- ARIA radiogroup/radio roles
 - Sliding indicator animates between selections
-- If no value set, first non-disabled option is selected
-- ARIA radiogroup/radio roles for accessibility
-- Diff from tabs: no content panes, just a value selector
-- Diff from switch: more than two options
+- First non-disabled option selected if no value set

package/docs/ai/components/select.md

@@ -1,142 +1,98 @@
 # snice-select
 
-Customizable dropdown selection with single/multiple selection, search, editable input, and icons.
+Customizable dropdown selection with single/multiple, search, editable input, and icons.
 
 ## Components
 
-### snice-select (Container)
+- `snice-select` - Container with trigger, dropdown, form integration
+- `snice-option` - Declarative option elements
+
+## Properties
+
+### snice-select
 
 ```typescript
-value: string = '';                 // Selected value (comma-separated for multiple)
-disabled: boolean = false;          // Disabled state
-required: boolean = false;          // Required for form validation
-invalid: boolean = false;           // Invalid state styling
-readonly: boolean = false;          // Readonly state
-multiple: boolean = false;          // Allow multiple selection
-searchable: boolean = false;        // Show search input in dropdown
-clearable: boolean = false;         // Show clear button
-editable: boolean = false;          // Editable text input trigger (replaces button)
-allowFreeText: boolean = false;     // attr: allow-free-text — allow values not in options
+value: string = '';                 // Comma-separated for multiple
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+loading: boolean = false;
+multiple: boolean = false;
+searchable: boolean = false;
+clearable: boolean = false;
+editable: boolean = false;          // Text input trigger instead of button
+allowFreeText: boolean = false;     // attr: allow-free-text
 remote: boolean = false;            // Remote search via @request('select/search')
-searchDebounce: number = 300;       // attr: search-debounce — debounce ms for remote search
-open: boolean = false;              // Dropdown open state
-loading: boolean = false;           // Loading state (shows spinner)
+searchDebounce: number = 300;       // attr: search-debounce
+open: boolean = false;
 size: 'small'|'medium'|'large' = 'medium';
-name: string = '';                  // Form field name
-label: string = '';                 // Label text
+name: string = '';
+label: string = '';
 placeholder: string = 'Select an option';
-maxHeight: string = '200px';        // Max dropdown height
-options: SelectOption[] = [];       // Programmatic options (works alongside <snice-option> children)
+maxHeight: string = '200px';        // attr: max-height
+options: SelectOption[] = [];       // JS only, works alongside <snice-option> children
 ```
 
-**Methods:**
-```typescript
-selectOption(value: string)  // Select option by value
-clear()                      // Clear selection
-openDropdown()               // Open dropdown
-closeDropdown()              // Close dropdown
-toggleDropdown()             // Toggle dropdown
-focus()                      // Focus trigger (or input in editable mode)
-blur()                       // Blur and close
-```
+### snice-option
 
-**Events:**
 ```typescript
-'select-change'  // { value, option, select }
-'select-open'    // { select }
-'select-close'   // { select }
+value: string = '';       // Falls back to label
+label: string = '';       // Falls back to textContent
+disabled: boolean = false;
+selected: boolean = false;
+icon: string = '';        // Icon URL
 ```
 
-### snice-option (Option Item)
+## Methods
 
-```typescript
-value: string = '';           // Option value (defaults to label)
-label: string = '';           // Option label (defaults to textContent)
-disabled: boolean = false;    // Disabled state
-selected: boolean = false;    // Initially selected
-icon: string = '';            // Icon URL
-```
+- `focus()` / `blur()` - Focus/blur trigger
+- `clear()` - Clear selection
+- `openDropdown()` / `closeDropdown()` / `toggleDropdown()` - Dropdown control
+- `selectOption(value)` - Select by value
 
-**Getter:**
-```typescript
-optionData  // { value, label, disabled, selected, icon }
-```
+## Events
+
+- `select-change` → `{ value: string | string[], option?, select }`
+- `select-open` → `{ select }`
+- `select-close` → `{ select }`
+
+## CSS Parts
 
-## Usage
+- `label`, `trigger`, `value`, `input`, `arrow`, `spinner`
+- `dropdown`, `search`, `search-input`, `options`, `option`
+
+## Basic Usage
 
 ```html
-<!-- Standard button-trigger select -->
+<!-- Declarative options -->
 <snice-select label="Choose" name="choice">
   <snice-option value="1">Option 1</snice-option>
   <snice-option value="2">Option 2</snice-option>
 </snice-select>
 
-<!-- Editable input-trigger select -->
+<!-- Editable input mode -->
 <snice-select editable label="Fruit" placeholder="Type or select..."></snice-select>
 ```
 
 ```typescript
-// Programmatic options (required for editable mode or in addition to children)
 select.options = [
   { value: 'apple', label: 'Apple' },
-  { value: 'banana', label: 'Banana', icon: '/icons/banana.svg' },
-  { value: 'cherry', label: 'Cherry', disabled: true },
+  { value: 'banana', label: 'Banana', icon: '/icons/banana.svg' }
 ];
-
-select.addEventListener('select-change', (e) => {
-  console.log(e.detail.value);
-});
-
-select.selectOption('1');
+select.addEventListener('select-change', (e) => console.log(e.detail.value));
 ```
 
 ## Editable Mode
 
-When `editable` is set:
-- Renders a text `<input>` instead of a `<button>` trigger
-- Typing filters options in the dropdown
-- Focus opens the dropdown
-- Blur commits the value and closes
-- If no match and `allow-free-text` is set, accepts custom value
-- If no match and no `allow-free-text`, reverts to last valid value
-- Options set via JS `options` property (array), child `<snice-option>` elements, or both (merged)
-
-## Remote Search (@request/@respond)
-
-When `remote` is set with `searchable` or `editable`:
-- Typing fires `@request('select/search')` with `{ query, select }` after debounce
-- Controller `@respond('select/search')` returns `SelectOption[]`
-- Dropdown shows spinner while waiting, then refreshes with results
-- Opening dropdown triggers initial search with current query
-- `loading` property no longer closes dropdown when `remote` is true
-
-```typescript
-// Controller
-@respond('select/search')
-async handleSearch(req, respond) {
-  const results = await fetch(`/api/users?q=${req.query}`).then(r => r.json());
-  respond(results.map(u => ({ value: u.id, label: u.name })));
-}
-```
-
-## Features
-
-- Single and multiple selection
-- Search filtering (in-dropdown or editable input)
-- Remote async search via @request/@respond
-- Editable text input mode (replaces combobox)
-- Keyboard navigation
-- Form integration
-- Icons in options
-- Clearable selection
-- Disabled options
-- Programmatic options array (works alongside child elements)
+- `editable` renders text input instead of button
+- Typing filters options; blur commits value
+- `allow-free-text` accepts values not in options list
+- `remote` + `editable` enables async search via @request/@respond
 
-## Notes
+## Accessibility
 
-- Options can be nested (uses querySelectorAll, not just direct children)
-- Multiple selection values are comma-separated
-- Hidden native select for form submission
+- Hidden native `<select>` for form submission
+- Arrow keys, Enter, Escape for keyboard navigation
 - Dropdown closes on outside click
-- Search shows in dropdown when open (non-editable mode)
-- Child `<snice-option>` elements take precedence when both children and programmatic options are provided
+- Children take precedence over `options` array

package/docs/ai/components/skeleton.md

@@ -13,41 +13,27 @@ count: number = 1;
 spacing: string = '8px';
 ```
 
-**CSS Parts:**
-- `base` - Outer skeleton container
-- `bone` - Individual skeleton placeholder element
+## CSS Custom Properties
 
-## Usage
+- `--skeleton-bg` - Background color
+- `--skeleton-highlight` - Wave highlight color
+- `--skeleton-duration` - Animation duration (`1.5s`)
 
-```html
-<!-- Text placeholder -->
-<snice-skeleton variant="text"></snice-skeleton>
-<snice-skeleton variant="text" width="200px"></snice-skeleton>
+## CSS Parts
 
-<!-- Circular (avatar) -->
-<snice-skeleton variant="circular" width="40px" height="40px"></snice-skeleton>
+- `base` - Outer container
+- `bone` - Individual placeholder element
 
-<!-- Rectangular -->
-<snice-skeleton variant="rectangular" width="100%" height="200px"></snice-skeleton>
+## Basic Usage
 
-<!-- Rounded (card) -->
-<snice-skeleton variant="rounded" width="300px" height="150px"></snice-skeleton>
-
-<!-- Multiple lines -->
+```html
 <snice-skeleton variant="text" count="3"></snice-skeleton>
-<snice-skeleton variant="text" count="5" spacing="12px"></snice-skeleton>
-
-<!-- Animation types -->
+<snice-skeleton variant="circular" width="48px" height="48px"></snice-skeleton>
+<snice-skeleton variant="rectangular" width="100%" height="200px"></snice-skeleton>
+<snice-skeleton variant="rounded" width="300px" height="150px"></snice-skeleton>
 <snice-skeleton animation="pulse"></snice-skeleton>
-<snice-skeleton animation="wave"></snice-skeleton>
-<snice-skeleton animation="none"></snice-skeleton>
-
-<!-- Complex layout -->
-<div style="display: flex; gap: 16px;">
-  <snice-skeleton variant="circular" width="48px" height="48px"></snice-skeleton>
-  <div style="flex: 1;">
-    <snice-skeleton variant="text" width="40%"></snice-skeleton>
-    <snice-skeleton variant="text" width="60%"></snice-skeleton>
-  </div>
-</div>
 ```
+
+## Accessibility
+
+- Decorative only; use `aria-busy="true"` on container while loading