snice 4.28.0 → 4.29.0

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

package/docs/ai/components/slider.md

@@ -15,6 +15,7 @@ disabled: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 readonly: boolean = false;
+loading: boolean = false;
 label: string = '';
 helperText: string = '';       // attr: helper-text
 errorText: string = '';        // attr: error-text
@@ -22,37 +23,42 @@ name: string = '';
 showValue: boolean = false;    // attr: show-value
 showTicks: boolean = false;    // attr: show-ticks
 vertical: boolean = false;
-loading: boolean = false;
-// form-align: CSS-only attribute (no JS property). Gives the slider track area
-// min-height: 2.5rem (40px) so it aligns with input/select fields in form rows.
+// form-align: CSS-only attribute, aligns with inputs in form rows
 ```
 
+## Methods
+
+- `focus()` / `blur()` - Focus/blur thumb
+- `checkValidity()` - Returns boolean
+- `reportValidity()` - Returns boolean
+- `setCustomValidity(message)` - Set validation message
+
 ## Events
 
-- `slider-input` → `{ value, slider }` - During drag
-- `slider-change` → `{ value, slider }` - After drag complete
+- `slider-input` → `{ value: number, slider }` - During drag
+- `slider-change` → `{ value: number, slider }` - After commit
 
-## Methods
+## CSS Parts
 
-- `focus()` - Focus slider thumb
-- `blur()` - Blur slider thumb
-- `checkValidity()` - Check validation, returns `boolean`
-- `reportValidity()` - Report validation to user, returns `boolean`
-- `setCustomValidity(message)` - Set custom validation message
+- `track`, `fill`, `thumb`, `spinner`, `error-text`, `helper-text`
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-slider label="Volume" min="0" max="100"></snice-slider>
-<snice-slider show-value value="50"></snice-slider>
+<snice-slider label="Volume" min="0" max="100" value="50" show-value></snice-slider>
 <snice-slider show-ticks min="0" max="10" step="1"></snice-slider>
-<snice-slider variant="primary"></snice-slider>
-<snice-slider size="small"></snice-slider>
+<snice-slider variant="primary" size="large"></snice-slider>
 <snice-slider vertical></snice-slider>
-<snice-slider label="Qty" form-align></snice-slider> <!-- aligns with inputs in form rows -->
-<snice-slider min="0" max="100" step="5" value="50"></snice-slider>
+<snice-slider label="Qty" form-align></snice-slider>
 ```
 
-## CSS Parts
+## Keyboard Navigation
+
+- Arrow keys: adjust by step
+- Home/End: min/max
+
+## Accessibility
 
-`track`, `fill`, `thumb`, `spinner`, `error-text`, `helper-text`
+- Form-associated via ElementInternals
+- `role="slider"` with aria-valuenow/min/max
+- Validation via checkValidity/reportValidity/setCustomValidity

package/docs/ai/components/sortable.md

@@ -4,42 +4,30 @@ Drag-and-drop sortable container for reordering child elements.
 
 ## Properties
 
-```ts
-direction: 'vertical' | 'horizontal' = 'vertical'
-handle: string = ''           // CSS selector for drag handle within items
-disabled: boolean = false
-group: string = ''            // group name for cross-container sorting
+```typescript
+direction: 'vertical'|'horizontal' = 'vertical';
+handle: string = '';         // CSS selector for drag handle
+disabled: boolean = false;
+group: string = '';          // Group name for cross-container sorting
 ```
 
-## Slots
-
-- `default` - Items to be sortable (automatically set to `draggable`)
-
 ## Events
 
-- `sort-start` -> `{ index: number; item: HTMLElement }`
-- `sort-end` -> `{ oldIndex: number; newIndex: number; item: HTMLElement }`
-- `sort-change` -> `{ oldIndex: number; newIndex: number; item: HTMLElement }`
-
-## CSS Parts
-
-- `base` - The outer sortable container
+- `sort-start` → `{ index: number, item: HTMLElement }`
+- `sort-end` → `{ oldIndex: number, newIndex: number, item: HTMLElement }`
+- `sort-change` → `{ oldIndex: number, newIndex: number, item: HTMLElement }`
 
-## CSS Custom Properties
+## Slots
 
-- `--snice-spacing-xs` - Gap between items (default: `0.5rem`)
-- `--snice-transition-fast` - Drag transition speed (default: `150ms`)
-- `--snice-color-primary` - Ghost outline color (default: `rgb(37 99 235)`)
+- `(default)` - Items to be sortable (auto set `draggable`)
 
-## CSS Classes on Items
+## CSS Parts
 
-- `.sortable-dragging` - Added to item being dragged (opacity: 0.4)
-- `.sortable-ghost` - Dashed outline placeholder
+- `base` - Outer sortable container
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Vertical sortable list -->
 <snice-sortable>
   <div>Item 1</div>
   <div>Item 2</div>
@@ -48,9 +36,13 @@ group: string = ''            // group name for cross-container sorting
 
 <!-- Horizontal with drag handle -->
 <snice-sortable direction="horizontal" handle=".drag-handle">
-  <div><span class="drag-handle">&#9776;</span> Item A</div>
-  <div><span class="drag-handle">&#9776;</span> Item B</div>
+  <div><span class="drag-handle">☰</span> Item A</div>
+  <div><span class="drag-handle">☰</span> Item B</div>
 </snice-sortable>
+
+<!-- Cross-container sorting -->
+<snice-sortable group="tasks">...</snice-sortable>
+<snice-sortable group="tasks">...</snice-sortable>
 ```
 
 ```typescript
@@ -58,3 +50,9 @@ sortable.addEventListener('sort-change', (e) => {
   console.log(`Moved from ${e.detail.oldIndex} to ${e.detail.newIndex}`);
 });
 ```
+
+## Accessibility
+
+- Items auto `draggable="true"`
+- Ghost placeholder with dashed outline
+- `.sortable-dragging` / `.sortable-ghost` classes during drag

package/docs/ai/components/sparkline.md

@@ -8,34 +8,33 @@ Compact inline chart for visualizing trends and patterns.
 data: number[] = [];
 type: 'line'|'bar'|'area' = 'line';
 color: 'primary'|'success'|'warning'|'danger'|'muted' = 'primary';
-customColor: string = '';          // attr: custom-color, overrides color
+customColor?: string;              // attr: custom-color, overrides color
 width: number = 100;
 height: number = 30;
-strokeWidth: number = 2;          // attr: stroke-width
-showDots: boolean = false;        // attr: show-dots
-showArea: boolean = false;        // attr: show-area
+strokeWidth: number = 2;           // attr: stroke-width
+showDots: boolean = false;         // attr: show-dots
+showArea: boolean = false;         // attr: show-area
 smooth: boolean = false;
-min?: number;
-max?: number;
+min?: number;                      // auto-calculated if unset
+max?: number;                      // auto-calculated if unset
 ```
 
 ## CSS Parts
 
-- `container` - Container div
+- `container` - Outer container
 - `svg` - SVG element
-- `line` - Line/path element
-- `area` - Area polygon/path
-- `bar` - Bar rect
-- `dot` - Dot circle
+- `line` - Line path
+- `area` - Area fill path
+- `dot` - Data point circle
+- `bar` - Bar rectangle
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-sparkline></snice-sparkline>
-```
-
-```typescript
-sparkline.data = [10, 20, 15, 25, 30];
+<snice-sparkline id="chart"></snice-sparkline>
+<script>
+  document.getElementById('chart').data = [10, 20, 15, 25, 30];
+</script>
 ```
 
 ```html
@@ -45,3 +44,8 @@ sparkline.data = [10, 20, 15, 25, 30];
 <snice-sparkline custom-color="#9333ea"></snice-sparkline>
 <snice-sparkline min="0" max="100"></snice-sparkline>
 ```
+
+## Accessibility
+
+- Decorative; use `aria-busy="true"` on container while loading
+- Add `aria-label` to describe the trend for screen readers

package/docs/ai/components/spinner.md

@@ -13,11 +13,11 @@ thickness: number = 4;
 
 ## CSS Parts
 
-- `base` - The outer spinner container
-- `circle` - The SVG spinner circle
-- `label` - The label text element
+- `base` - Outer spinner container
+- `circle` - SVG spinner circle
+- `label` - Label text element
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-spinner></snice-spinner>
@@ -25,8 +25,12 @@ thickness: number = 4;
 <snice-spinner size="large"></snice-spinner>
 <snice-spinner size="xl"></snice-spinner>
 <snice-spinner color="success"></snice-spinner>
-<snice-spinner color="warning"></snice-spinner>
 <snice-spinner color="error"></snice-spinner>
 <snice-spinner label="Loading..."></snice-spinner>
 <snice-spinner thickness="6"></snice-spinner>
 ```
+
+## Accessibility
+
+- `role="status"` with `aria-label`
+- `label` property provides visible descriptive text

package/docs/ai/components/split-button.md

@@ -13,10 +13,15 @@ disabled: boolean = false;
 loading: boolean = false;
 outline: boolean = false;
 pill: boolean = false;
-icon: string = '';                  // Icon (URL, image file, emoji)
-iconPlacement: 'start'|'end' = 'start';
+icon: string = '';                  // URL, image file, or emoji
+iconPlacement: 'start'|'end' = 'start';  // attr: icon-placement
 ```
 
+## Events
+
+- `primary-click` → `{ button }`
+- `action-click` → `{ value, action, button }`
+
 ## CSS Parts
 
 - `base` - Root container
@@ -27,12 +32,7 @@ iconPlacement: 'start'|'end' = 'start';
 - `menu-items` - Menu items wrapper
 - `action` - Individual action button
 
-## Events
-
-- `primary-click` → `{ button }`
-- `action-click` → `{ value, action, button }`
-
-## Usage
+## Basic Usage
 
 ```html
 <snice-split-button label="Save" variant="primary"></snice-split-button>
@@ -49,10 +49,7 @@ btn.addEventListener('primary-click', () => console.log('Save clicked'));
 btn.addEventListener('action-click', (e) => console.log(e.detail.value));
 ```
 
-## Notes
+## Accessibility
 
-- Main button triggers `primary-click`
-- Chevron dropdown triggers menu of alternative actions
-- Menu closes after action click or outside click
-- Escape key closes menu
+- Menu closes on action click, outside click, or Escape key
 - Actions set via JS property (array), not child elements

package/docs/ai/components/split-pane.md

@@ -1,6 +1,6 @@
 # snice-split-pane
 
-Resizable split pane layout.
+Resizable split pane layout with draggable divider.
 
 ## Properties
 
@@ -13,30 +13,30 @@ snapSize: number = 0;             // attr: snap-size, percentage, 0 = no snap
 disabled: boolean = false;
 ```
 
-## Slots
+## Methods
 
-- `primary` - Primary pane content
-- `secondary` - Secondary pane content
+- `getPrimarySize()` → `number` - Get primary pane percentage
+- `getSecondarySize()` → `number` - Get secondary pane percentage
+- `setPrimarySize(size)` - Set primary pane percentage
+- `reset()` - Reset to 50/50
 
 ## Events
 
 - `pane-resize` → `{ primarySize, secondarySize, splitPane }`
 
-## Methods
+## Slots
 
-- `getPrimarySize()` - Get primary pane percentage
-- `getSecondarySize()` - Get secondary pane percentage
-- `setPrimarySize(size)` - Set primary pane percentage
-- `reset()` - Reset to 50/50
+- `primary` - Primary pane content (left or top)
+- `secondary` - Secondary pane content (right or bottom)
 
 ## CSS Parts
 
-- `primary` - The primary pane container
-- `divider` - The draggable divider bar
-- `handle` - The visual handle inside the divider
-- `secondary` - The secondary pane container
+- `primary` - Primary pane container
+- `divider` - Draggable divider bar
+- `handle` - Visual handle inside divider
+- `secondary` - Secondary pane container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-split-pane style="height: 400px;">
@@ -54,3 +54,8 @@ disabled: boolean = false;
   <div slot="secondary">70%</div>
 </snice-split-pane>
 ```
+
+## Accessibility
+
+- Divider keyboard-accessible with arrow keys
+- Mouse, touch, and keyboard input supported