snice 4.8.0 → 4.10.0

package/docs/ai/components/spotlight.md

@@ -0,0 +1,61 @@
+# snice-spotlight
+
+Guided tour / onboarding spotlight that highlights elements with step-by-step popover instructions.
+
+## Properties
+
+```ts
+steps: SpotlightStep[] = []
+
+interface SpotlightStep {
+  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
+- `next()` - Advance to next step (ends tour if on last step)
+- `prev()` - Go back to previous step
+- `goToStep(index: number)` - 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 }`
+
+## 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-shadow-lg` - Popover shadow
+- `--snice-border-radius-lg` - Popover border radius (default: `0.5rem`)
+
+## Usage
+
+```html
+<snice-spotlight></snice-spotlight>
+```
+
+```js
+const spotlight = document.querySelector('snice-spotlight');
+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' }
+];
+spotlight.start();
+
+spotlight.addEventListener('spotlight-end', () => {
+  console.log('Tour completed');
+});
+```

package/docs/ai/components/spreadsheet.md

@@ -0,0 +1,138 @@
+# snice-spreadsheet
+
+Excel-like spreadsheet with formulas, multi-cell selection, undo/redo, column resize, context menu, and auto-expanding grid.
+
+## Properties
+
+```ts
+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
+}
+```
+
+## 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
+
+## 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
+
+- Drag right edge of column header to resize
+- Min width: 40px
+- Widths stored in internal map
+
+## 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 Custom Properties
+
+- `--snice-color-border` - Grid lines (default: `rgb(226 226 226)`)
+- `--snice-color-background` - Cell background (default: `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-text-secondary` - Formula bar cell ref
+- `--snice-color-text-tertiary` - Row numbers, status bar labels
+
+## Usage
+
+```html
+<snice-spreadsheet></snice-spreadsheet>
+```
+
+```js
+const sheet = document.querySelector('snice-spreadsheet');
+sheet.columns = [
+  { header: 'Name', type: 'text' },
+  { header: 'Amount', type: 'number', width: 100 },
+  { header: 'Status', type: 'select', options: ['Active', 'Pending', 'Done'] }
+];
+sheet.data = [
+  ['Alice', 100, 'Active'],
+  ['Bob', 200, 'Pending'],
+  ['Total', '=SUM(B1:B2)', '']
+];
+
+sheet.addEventListener('cell-change', (e) => {
+  console.log(`Cell [${e.detail.row},${e.detail.col}] changed to ${e.detail.value}`);
+});
+```

package/docs/ai/components/stepper.md

@@ -1,216 +1,70 @@
 # snice-stepper
 
-Step indicator for multi-step processes, wizards, workflows. Shows progress with pending/active/completed/error states.
+Step indicator for multi-step processes with pending/active/completed/error states.
 
 ## Properties
 
 ```typescript
-steps: Step[] = []                          // Array of step objects
-currentStep: number = 0                     // Current active step index
-orientation: StepperOrientation = 'horizontal' // 'horizontal' | 'vertical'
-clickable: boolean = false                  // Enable click navigation
+steps: Step[] = [];
+currentStep: number = 0;          // attr: current-step
+orientation: 'horizontal'|'vertical' = 'horizontal';
+clickable: boolean = false;
 
 // Step object:
-{
-  label: string;           // Step label (required)
-  description?: string;    // Optional description
-  status?: StepStatus;     // Override auto status: 'pending' | 'active' | 'completed' | 'error'
+interface Step {
+  label: string;
+  description?: string;
+  status?: 'pending'|'active'|'completed'|'error'; // auto-computed if not set
 }
 ```
 
+## Events
+
+- `step-change` → `{ previousStep, currentStep, step }` - Cancelable via preventDefault()
+
+## Methods
+
+- Navigate via `currentStep` property (increment/decrement/set)
+
+## CSS Parts
+
+- `container` - Main container
+- `step` - Individual step
+- `step-indicator` - Circular indicator
+- `step-content` - Label + description wrapper
+- `step-label` - Step label text
+- `step-description` - Description text
+- `step-connector` - Line between steps
+
 ## Usage
 
 ```html
-<!-- Basic horizontal -->
-<snice-stepper id="basic"></snice-stepper>
+<!-- Basic -->
+<snice-stepper id="stepper"></snice-stepper>
 <script>
-  document.getElementById('basic').steps = [
-    { label: 'Step 1' },
-    { label: 'Step 2' },
-    { label: 'Step 3' }
+  document.getElementById('stepper').steps = [
+    { label: 'Account' },
+    { label: 'Profile' },
+    { label: 'Complete' }
   ];
-  document.getElementById('basic').currentStep = 1;
+  document.getElementById('stepper').currentStep = 1;
 </script>
 
-<!-- With panels (auto show/hide) -->
+<!-- With panels (auto show/hide based on currentStep) -->
 <snice-stepper id="wizard" clickable></snice-stepper>
 <snice-stepper-panel>Step 1 content</snice-stepper-panel>
 <snice-stepper-panel>Step 2 content</snice-stepper-panel>
 <snice-stepper-panel>Step 3 content</snice-stepper-panel>
-<script>
-  document.getElementById('wizard').steps = [
-    { label: 'Account' },
-    { label: 'Profile' },
-    { label: 'Complete' }
-  ];
-</script>
 
 <!-- Vertical with descriptions -->
-<snice-stepper id="vertical" orientation="vertical"></snice-stepper>
-<script>
-  document.getElementById('vertical').steps = [
-    { label: 'Account', description: 'Create your account' },
-    { label: 'Profile', description: 'Personal info' },
-    { label: 'Complete', description: 'Finish setup' }
-  ];
-</script>
-
-<!-- Clickable navigation -->
-<snice-stepper id="wizard" clickable></snice-stepper>
-<script>
-  const wizard = document.getElementById('wizard');
-  wizard.steps = [
-    { label: 'Cart' },
-    { label: 'Delivery' },
-    { label: 'Payment' },
-    { label: 'Confirm' }
-  ];
-
-  wizard.addEventListener('step-change', (e) => {
-    console.log(e.detail.previousStep); // Previous step index
-    console.log(e.detail.currentStep);  // New step index
-    console.log(e.detail.step);         // Step object
-    // e.preventDefault(); to cancel navigation
-  });
-</script>
+<snice-stepper orientation="vertical"></snice-stepper>
 
 <!-- Error state -->
-<snice-stepper id="validation"></snice-stepper>
 <script>
-  document.getElementById('validation').steps = [
+  stepper.steps = [
     { label: 'Upload', status: 'completed' },
     { label: 'Validate', status: 'error' },
     { label: 'Process', status: 'pending' }
   ];
 </script>
-
-<!-- Programmatic navigation -->
-<script>
-  const stepper = document.getElementById('my-stepper');
-  stepper.currentStep++; // Next
-  stepper.currentStep--; // Previous
-  stepper.currentStep = 2; // Go to step 3
-</script>
-```
-
-## Events
-
-```javascript
-// step-change (only in clickable mode)
-stepper.addEventListener('step-change', (e) => {
-  const { previousStep, currentStep, step } = e.detail;
-  e.preventDefault(); // Cancel navigation if needed
-});
 ```
-
-## CSS Parts
-
-```css
-::part(container)       /* Main container */
-::part(step)            /* Individual step */
-::part(step-indicator)  /* Circular indicator */
-::part(step-content)    /* Label + description wrapper */
-::part(step-label)      /* Step label text */
-::part(step-description) /* Description text */
-::part(step-connector)  /* Line between steps */
-```
-
-## Styling
-
-```css
---snice-color-primary       /* Active state */
---snice-color-success       /* Completed state */
---snice-color-danger        /* Error state */
---snice-color-text
---snice-color-text-secondary /* Pending state */
---snice-color-text-inverse  /* Indicator text */
---snice-color-background
---snice-color-border
---snice-spacing-xs
---snice-spacing-sm
---snice-spacing-md
---snice-spacing-lg
---snice-font-size-xs
---snice-font-size-sm
---snice-font-weight-medium
---snice-font-weight-semibold
---snice-transition-fast
-```
-
-## Common Patterns
-
-```html
-<!-- Checkout flow -->
-<snice-stepper id="checkout" clickable></snice-stepper>
-<button onclick="document.getElementById('checkout').currentStep--">Back</button>
-<button onclick="document.getElementById('checkout').currentStep++">Next</button>
-<script>
-  document.getElementById('checkout').steps = [
-    { label: 'Cart', description: 'Review items' },
-    { label: 'Delivery', description: 'Shipping address' },
-    { label: 'Payment', description: 'Billing info' },
-    { label: 'Confirm', description: 'Place order' }
-  ];
-</script>
-
-<!-- Onboarding wizard (vertical) -->
-<snice-stepper id="onboarding" orientation="vertical" clickable></snice-stepper>
-<script>
-  document.getElementById('onboarding').steps = [
-    { label: 'Welcome' },
-    { label: 'Profile Setup' },
-    { label: 'Preferences' },
-    { label: 'Get Started' }
-  ];
-</script>
-
-<!-- Form validation -->
-<snice-stepper id="form"></snice-stepper>
-<script>
-  document.getElementById('form').steps = [
-    { label: 'Personal Info', status: 'completed' },
-    { label: 'Address', status: 'error' },  // Has validation error
-    { label: 'Review', status: 'pending' }
-  ];
-</script>
-
-<!-- Progress tracker -->
-<snice-stepper id="upload"></snice-stepper>
-<script>
-  const upload = document.getElementById('upload');
-  upload.steps = [
-    { label: 'Upload', status: 'completed' },
-    { label: 'Process', status: 'active' },
-    { label: 'Complete', status: 'pending' }
-  ];
-  upload.currentStep = 1;
-</script>
-```
-
-## Stepper Panels
-
-```html
-<!-- Panels auto show/hide based on currentStep -->
-<snice-stepper id="wizard"></snice-stepper>
-<snice-stepper-panel>Content for step 0</snice-stepper-panel>
-<snice-stepper-panel>Content for step 1</snice-stepper-panel>
-<snice-stepper-panel>Content for step 2</snice-stepper-panel>
-```
-
-- Panels must be direct children of stepper
-- Panel index matches order (first panel = step 0, etc.)
-- Automatically activated when stepper.currentStep changes
-- Only active panel is visible (display: block), others hidden
-
-## Notes
-
-- Status auto-computed from currentStep if not explicitly set:
-  - Steps before currentStep: 'completed' (shows ✓)
-  - Step at currentStep: 'active'
-  - Steps after currentStep: 'pending'
-- Completed steps show checkmark (✓) instead of number
-- Connector lines auto-hidden on last step
-- Click events only work when clickable=true
-- step-change event is cancelable via preventDefault()
-- Orientation affects layout but not behavior
-- Panels sync automatically via @watch decorator on currentStep

package/docs/ai/components/switch.md

@@ -1,54 +1,47 @@
 # snice-switch
 
-Toggle switch input for boolean selections.
+Toggle switch input for boolean selections. Form-associated.
 
 ## Properties
 
 ```typescript
-checked: boolean = false;        // Switch state
-disabled: boolean = false;       // Disabled state
-required: boolean = false;       // Form required
-invalid: boolean = false;        // Invalid state styling
+checked: boolean = false;
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
 size: 'small'|'medium'|'large' = 'medium';
-name: string = '';              // Form field name
-value: string = 'on';           // Form field value when checked
-label: string = '';             // Label text
-labelOn: string = '';           // Label shown when on
-labelOff: string = '';          // Label shown when off
-loading: boolean = false;        // Loading state (shows spinner)
+name: string = '';
+value: string = 'on';
+label: string = '';
+labelOn: string = '';           // attr: label-on
+labelOff: string = '';          // attr: label-off
+loading: boolean = false;
 ```
 
+## Events
+
+- `switch-change` → `{ checked, switch }`
+
 ## Methods
 
-```typescript
-toggle()      // Toggle switch state
-focus()       // Focus the switch
-blur()        // Remove focus
-click()       // Programmatic click
-```
+- `toggle()` - Toggle switch state
+- `focus()` - Focus the switch
+- `blur()` - Remove focus
+- `click()` - Programmatic click
 
-## Events
+## CSS Parts
 
-```typescript
-'switch-change' // { checked, switch }
-```
+- `track` - Switch track
+- `thumb` - Switch thumb
+- `label` - Label text
 
 ## Usage
 
 ```html
 <snice-switch label="Enable notifications"></snice-switch>
-```
-
-```typescript
-switchEl.addEventListener('switch-change', (e) => {
-  console.log(e.detail.checked);
-});
-```
-
-## CSS Parts
-
-```css
-::part(track)   // Switch track
-::part(thumb)   // Switch thumb
-::part(label)   // Label text
+<snice-switch checked label="Dark mode"></snice-switch>
+<snice-switch size="small" label="Compact"></snice-switch>
+<snice-switch label-on="On" label-off="Off"></snice-switch>
+<snice-switch loading label="Saving..."></snice-switch>
+<snice-switch disabled></snice-switch>
 ```