snice 4.27.0 → 4.29.0

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

package/docs/ai/components/stat-group.md

@@ -6,17 +6,13 @@ Coordinated row of KPI cards with trend indicators and responsive grid layout.
 
 ```typescript
 stats: StatItem[] = [];
-columns: number = 0;  // 0 = auto-fit
+columns: number = 0;             // 0 = auto-fit
 variant: 'card'|'minimal'|'bordered' = 'card';
-```
-
-## Types
 
-```typescript
 interface StatItem {
   label: string;
   value: string | number;
-  trend?: 'up' | 'down' | 'neutral';
+  trend?: 'up'|'down'|'neutral';
   trendValue?: string;
   icon?: string;
   color?: string;
@@ -25,14 +21,14 @@ interface StatItem {
 
 ## Events
 
-- `stat-click` -> `{ stat: StatItem, index: number }`
+- `stat-click` → `{ stat, index }`
 
 ## CSS Parts
 
 - `base` - Grid container
 - `stat` - Individual stat card
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-stat-group></snice-stat-group>
@@ -43,16 +39,12 @@ el.stats = [
   { label: 'Revenue', value: '$45,231', trend: 'up', trendValue: '+12.5%' },
   { label: 'Users', value: '2,338', trend: 'up', trendValue: '+8.2%' },
   { label: 'Orders', value: '1,245', trend: 'down', trendValue: '-3.1%' },
-  { label: 'Bounce', value: '3.24%', trend: 'neutral', trendValue: '0.0%' }
 ];
 ```
 
 ```html
-<!-- Variants -->
 <snice-stat-group variant="minimal"></snice-stat-group>
 <snice-stat-group variant="bordered"></snice-stat-group>
-
-<!-- Fixed columns -->
 <snice-stat-group columns="2"></snice-stat-group>
 ```
 
@@ -61,13 +53,11 @@ el.stats = [
 el.stats = [
   { label: 'Revenue', value: '$45K', icon: '$', color: 'rgb(22 163 74)', trend: 'up', trendValue: '+12%' }
 ];
+
+el.addEventListener('stat-click', (e) => console.log(e.detail.stat.label));
 ```
 
-## Features
+## Accessibility
 
-- 3 visual variants: card, minimal, bordered
-- Auto-fit responsive grid (wraps on narrow viewports)
-- Fixed column count option
-- Trend indicators (up/down/neutral) with color coding
-- Icon and color customization per stat
-- Keyboard accessible (Enter/Space to click)
+- Stat cards have `role="button"`, keyboard accessible (Enter/Space)
+- Trend indicators use semantic color coding

package/docs/ai/components/step-input.md

@@ -15,10 +15,6 @@ size: 'small'|'medium'|'large' = 'medium';
 wrap: boolean = false;              // wrap around at min/max boundaries
 ```
 
-## Events
-
-- `value-change` -> `{ value: number, oldValue: number, component: SniceStepInputElement }`
-
 ## Methods
 
 - `increment()` - Increase value by step
@@ -26,29 +22,35 @@ wrap: boolean = false;              // wrap around at min/max boundaries
 - `focus()` - Focus the input
 - `blur()` - Remove focus
 
+## Events
+
+- `value-change` → `{ value, oldValue, component }`
+
 ## CSS Parts
 
 - `base` - Outer container
 - `decrement-button` - Minus button
 - `increment-button` - Plus button
-- `input` - The number input
+- `input` - Number input field
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-step-input value="5"></snice-step-input>
-
-<!-- With min/max -->
 <snice-step-input min="0" max="10" value="5" step="1"></snice-step-input>
-
-<!-- Wrap around -->
 <snice-step-input min="1" max="12" value="1" wrap></snice-step-input>
-
-<!-- Sizes -->
 <snice-step-input size="small"></snice-step-input>
 <snice-step-input size="large"></snice-step-input>
-
-<!-- Disabled -->
 <snice-step-input value="3" disabled></snice-step-input>
 ```
+
+## Keyboard Navigation
+
+- ArrowUp: increment by step
+- ArrowDown: decrement by step
+
+## Accessibility
+
+- Buttons keyboard accessible with focus indicators
+- Direct keyboard entry in input field
+- Buttons disabled at min/max (unless `wrap` is set)

package/docs/ai/components/stepper.md

@@ -10,41 +10,35 @@ currentStep: number = 0;          // attr: current-step
 orientation: 'horizontal'|'vertical' = 'horizontal';
 clickable: boolean = false;
 
-// Step object:
 interface Step {
   label: string;
   description?: string;
-  status?: 'pending'|'active'|'completed'|'error'; // auto-computed if not set
+  status?: 'pending'|'active'|'completed'|'error';  // auto-computed if not set
 }
 ```
 
-## Slots
-
-- `(default)` - `<snice-stepper-panel>` elements (auto show/hide based on currentStep)
-
 ## Events
 
-- `step-change` → `{ previousStep, currentStep, step }` - Cancelable via preventDefault()
+- `step-change` → `{ previousStep, currentStep, step }` - Cancelable via `preventDefault()`
 
-## Methods
+## Slots
 
-- Navigate via `currentStep` property (increment/decrement/set)
+- `(default)` - `<snice-stepper-panel>` elements (auto show/hide based on `currentStep`)
 
 ## CSS Parts
 
 - `container` - Main container
-- `step` - Individual step
-- `step-indicator` - Circular indicator
+- `step` - Individual step wrapper
+- `step-indicator` - Circular indicator (number/checkmark)
 - `step-content` - Label + description wrapper
 - `step-label` - Step label text
 - `step-description` - Description text
 - `step-connector` - Line between steps
 - `panels` - Panels container (wraps slotted content)
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-stepper></snice-stepper>
 ```
 
@@ -66,14 +60,19 @@ stepper.currentStep = 1;
 
 <!-- Vertical with descriptions -->
 <snice-stepper orientation="vertical"></snice-stepper>
-
-<!-- Error state -->
 ```
 
 ```typescript
+// Error state
 stepper.steps = [
   { label: 'Upload', status: 'completed' },
   { label: 'Validate', status: 'error' },
   { label: 'Process', status: 'pending' }
 ];
 ```
+
+## Accessibility
+
+- Clickable steps are keyboard accessible (Enter/Space)
+- Completed steps show checkmark; error steps use semantic color
+- Navigate via `currentStep` property

package/docs/ai/components/switch.md

@@ -1,27 +1,23 @@
 # snice-switch
 
-Toggle switch input for boolean selections. Form-associated.
+Toggle switch input for boolean selections.
 
 ## Properties
 
 ```typescript
 checked: boolean = false;
 disabled: boolean = false;
+loading: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 size: 'small'|'medium'|'large' = 'medium';
 name: string = '';
 value: string = 'on';
 label: string = '';
-labelOn: string = '';           // attr: label-on
-labelOff: string = '';          // attr: label-off
-loading: boolean = false;
+labelOn: string = '';              // attr: label-on
+labelOff: string = '';             // attr: label-off
 ```
 
-## Events
-
-- `switch-change` → `{ checked, switch }`
-
 ## Methods
 
 - `toggle()` - Toggle switch state
@@ -29,6 +25,10 @@ loading: boolean = false;
 - `blur()` - Remove focus
 - `click()` - Programmatic click
 
+## Events
+
+- `switch-change` → `{ checked, switch }`
+
 ## CSS Parts
 
 - `input` - Hidden input element
@@ -37,7 +37,7 @@ loading: boolean = false;
 - `spinner` - Loading spinner
 - `label` - Label text
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-switch label="Enable notifications"></snice-switch>
@@ -47,3 +47,9 @@ loading: boolean = false;
 <snice-switch loading label="Saving..."></snice-switch>
 <snice-switch disabled></snice-switch>
 ```
+
+## Accessibility
+
+- `role="switch"` with `aria-checked`
+- Space key to toggle
+- Visible focus ring on keyboard navigation