snice 4.28.0 → 4.30.0

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

package/docs/ai/components/spotlight.md

@@ -1,46 +1,46 @@
 # snice-spotlight
 
-Guided tour / onboarding spotlight that highlights elements with step-by-step popover instructions.
+Guided tour / onboarding spotlight with cutout overlay and step-by-step popovers.
 
 ## Properties
 
-```ts
-steps: SpotlightStep[] = []
+```typescript
+steps: SpotlightStep[] = [];
 
 interface SpotlightStep {
-  target: string              // CSS selector for target element
-  title: string
-  description: string
-  position?: 'top' | 'bottom' | 'left' | 'right' | 'auto'
+  target: string;              // CSS selector for target element
+  title: string;
+  description: string;
+  position?: 'top'|'bottom'|'left'|'right'|'auto';
 }
 ```
 
 ## Methods
 
-- `start()` - Begin the spotlight tour from step 0
+- `start()` - Begin tour from step 0
 - `next()` - Advance to next step (ends tour if on last step)
 - `prev()` - Go back to previous step
-- `goToStep(index: number)` - Jump to specific step
+- `goToStep(index)` - Jump to specific step
 - `end()` - End the tour
 
 ## Events
 
-- `spotlight-start` -> `void`
-- `spotlight-step` -> `{ index: number; step: SpotlightStep }`
-- `spotlight-end` -> `void`
-- `spotlight-skip` -> `{ index: number }`
+- `spotlight-start` → `void`
+- `spotlight-step` → `{ index, step }`
+- `spotlight-end` → `void`
+- `spotlight-skip` → `{ index }`
 
 ## CSS Custom Properties
 
-- `--snice-transition-medium` - Cutout transition speed (default: `250ms`)
-- `--snice-color-background` - Popover background (default: `rgb(255 255 255)`)
-- `--snice-color-border` - Popover border (default: `rgb(226 226 226)`)
-- `--snice-color-text` - Popover text color (default: `rgb(23 23 23)`)
-- `--snice-color-primary` - Primary button color (default: `rgb(37 99 235)`)
+- `--snice-transition-medium` - Cutout transition speed (`250ms`)
+- `--snice-color-background` - Popover background (`rgb(255 255 255)`)
+- `--snice-color-border` - Popover border (`rgb(226 226 226)`)
+- `--snice-color-text` - Popover text (`rgb(23 23 23)`)
+- `--snice-color-primary` - Primary button (`rgb(37 99 235)`)
 - `--snice-shadow-lg` - Popover shadow
-- `--snice-border-radius-lg` - Popover border radius (default: `0.5rem`)
+- `--snice-border-radius-lg` - Popover border radius (`0.5rem`)
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-spotlight></snice-spotlight>
@@ -48,13 +48,18 @@ interface SpotlightStep {
 
 ```typescript
 spotlight.steps = [
-  { target: '#step1', title: 'Welcome', description: 'This is the first step', position: 'bottom' },
-  { target: '#step2', title: 'Next', description: 'Click here to continue', position: 'right' },
-  { target: '#step3', title: 'Done', description: 'All set!', position: 'top' }
+  { target: '#step1', title: 'Welcome', description: 'First step', position: 'bottom' },
+  { target: '#step2', title: 'Next', description: 'Continue here', position: 'right' },
 ];
 spotlight.start();
 
-spotlight.addEventListener('spotlight-end', () => {
-  console.log('Tour completed');
-});
+spotlight.addEventListener('spotlight-end', () => console.log('Tour completed'));
+spotlight.addEventListener('spotlight-skip', (e) => console.log(`Skipped at ${e.detail.index}`));
 ```
+
+## Accessibility
+
+- Keyboard-accessible navigation buttons
+- Focus moves to popover on each step
+- Escape key ends tour
+- Respects `prefers-reduced-motion`

package/docs/ai/components/spreadsheet.md

@@ -4,122 +4,57 @@ Excel-like spreadsheet with formulas, multi-cell selection, undo/redo, column re
 
 ## Properties
 
-```ts
-data: any[][] = []
-columns: SpreadsheetColumn[] = []
-readonly: boolean = false
+```typescript
+data: any[][] = [];
+columns: SpreadsheetColumn[] = [];
+readonly: boolean = false;
 
 interface SpreadsheetColumn {
-  header: string
-  type?: 'text' | 'number' | 'date' | 'boolean' | 'select'
-  width?: number
-  options?: string[]           // for 'select' type
-}
-
-interface CellPosition {
-  row: number
-  col: number
-}
-
-interface CellRange {
-  start: CellPosition
-  end: CellPosition
-}
-
-interface UndoEntry {
-  row: number
-  col: number
-  oldValue: any
-  newValue: any
+  header: string;
+  type?: 'text'|'number'|'date'|'boolean'|'select';
+  width?: number;
+  options?: string[];           // for 'select' type
 }
 ```
 
 ## Methods
 
-- `getCell(row: number, col: number)` - Get resolved cell value
-- `setCell(row: number, col: number, value: any)` - Set cell value (auto-expands data, adds to undo stack)
-- `getData()` - Get copy of all data
-- `setData(data: any[][])` - Replace all data
+- `getCell(row, col)` → `any` - Get resolved cell value (formulas return computed result)
+- `setCell(row, col, value)` - Set cell value (auto-expands, adds to undo stack)
+- `getData()` → `any[][]` - Get copy of all data
+- `setData(data)` - Replace all data
 
 ## Events
 
-- `cell-change` -> `{ row: number; col: number; value: any; oldValue: any }`
-- `cell-select` -> `{ row: number; col: number }`
-- `row-select` -> `{ row: number }`
-- `column-sort` -> `{ col: number; direction: 'asc' | 'desc' }`
-
-## Formula Support
-
-Cells starting with `=` are evaluated. Supported functions:
-- `=SUM(A1:B3)`, `=AVG(A1:A5)`, `=AVERAGE(A1:A5)`
-- `=COUNT(A1:A10)`, `=MIN(A1:A5)`, `=MAX(A1:A5)`
-
-## Keyboard Shortcuts
-
-- Arrow keys: Navigate cells
-- Shift+Arrow: Extend selection range
-- Shift+Click: Extend selection to clicked cell
-- Enter/F2: Edit selected cell
-- Tab/Shift+Tab: Move to next/previous cell (commits edit, auto-expands grid)
-- Escape: Cancel edit
-- Delete/Backspace: Clear selected cell(s)
-- Ctrl+C/Ctrl+V: Copy/paste (supports tab-separated multi-cell)
-- Ctrl+Z: Undo (up to 100 entries)
-- Ctrl+Y / Ctrl+Shift+Z: Redo
-- Any printable key: Start editing with that character (type-to-edit)
-
-## Multi-Cell Selection
-
-- Click+drag to select range
-- Shift+click extends from anchor
-- Shift+arrow keys grow selection
-- Selected range: light blue fill; anchor cell: 2px blue border
-- Status bar shows COUNT, SUM, AVG of numeric cells in selection
-
-## Column Resizing
+- `cell-change` → `{ row, col, value, oldValue }`
+- `cell-select` → `{ row, col }`
+- `row-select` → `{ row }`
+- `column-sort` → `{ col, direction: 'asc'|'desc' }`
 
-- Drag right edge of column header to resize
-- Min width: 40px
-- Widths stored in internal map
+## CSS Parts
 
-## Context Menu (Right-Click)
-
-Items: Cut, Copy, Paste, Insert Row Above/Below, Delete Row, Insert Column Left/Right, Delete Column, Clear Cell(s)
-
-## Row/Column Add Buttons
-
-- "+" row at bottom: appends empty row
-- "+" column at right: appends empty column
-- Auto-expand on Tab (last col) or Enter (last row)
-
-## Empty State
-
-When data is empty, shows "Double-click or start typing to add data"
-
-## Frozen Headers
-
-- Row numbers: sticky left (visible during horizontal scroll)
-- Column headers: sticky top
-- Corner cell (top-left): sticky both directions
-
-**CSS Parts:**
-- `formula-bar` - The formula bar with cell reference and input
-- `base` - The main spreadsheet grid area
-- `status-bar` - The bottom status bar showing selection stats
-- `context-menu` - The right-click context menu
+- `formula-bar` - Formula bar with cell reference and input
+- `base` - Main spreadsheet grid area
+- `status-bar` - Bottom status bar (selection stats)
+- `context-menu` - Right-click context menu
 
 ## CSS Custom Properties
 
-- `--snice-color-border` - Grid lines (default: `rgb(226 226 226)`)
-- `--snice-color-background` - Cell background (default: `rgb(255 255 255)`)
+- `--snice-color-border` - Grid lines (`rgb(226 226 226)`)
+- `--snice-color-background` - Cell background (`rgb(255 255 255)`)
 - `--snice-color-background-element` - Header/row-number background
-- `--snice-color-primary` - Selected cell border (default: `rgb(37 99 235)`)
-- `--snice-color-primary-subtle` - Range selection fill / header highlight
-- `--snice-color-text` - Cell text color
+- `--snice-color-background-hover` - Row/header hover
+- `--snice-color-primary` - Selected cell border (`rgb(37 99 235)`)
+- `--snice-color-primary-subtle` - Range selection fill
+- `--snice-color-text` - Cell text
 - `--snice-color-text-secondary` - Formula bar cell ref
 - `--snice-color-text-tertiary` - Row numbers, status bar labels
 
-## Usage
+## Formula Support
+
+Cells starting with `=` are evaluated: `SUM`, `AVG`/`AVERAGE`, `COUNT`, `MIN`, `MAX`. Cell refs use A1 notation.
+
+## Basic Usage
 
 ```html
 <snice-spreadsheet></snice-spreadsheet>
@@ -141,3 +76,22 @@ sheet.addEventListener('cell-change', (e) => {
   console.log(`Cell [${e.detail.row},${e.detail.col}] changed to ${e.detail.value}`);
 });
 ```
+
+## Keyboard Navigation
+
+- Arrow keys: navigate cells
+- Shift+Arrow: extend selection range
+- Enter/F2: edit cell; Escape: cancel
+- Tab/Shift+Tab: next/prev cell (commits edit, auto-expands)
+- Delete/Backspace: clear cell(s)
+- Ctrl+C/V: copy/paste (tab-separated multi-cell)
+- Ctrl+Z: undo; Ctrl+Y: redo (up to 100 entries)
+- Any printable key: type-to-edit
+
+## Accessibility
+
+- Full keyboard navigation and editing
+- Visible focus indicator on selected cell
+- Frozen row numbers (sticky left) and column headers (sticky top)
+- Context menu: Cut, Copy, Paste, Insert/Delete Row/Column, Clear
+- Auto-expanding grid via "+" buttons and Tab/Enter at edges