snice 4.9.0 → 4.10.0

package/docs/ai/components/sortable.md

@@ -0,0 +1,57 @@
+# snice-sortable
+
+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
+```
+
+## 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 Custom Properties
+
+- `--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)`)
+
+## CSS Classes on Items
+
+- `.sortable-dragging` - Added to item being dragged (opacity: 0.4)
+- `.sortable-ghost` - Dashed outline placeholder
+
+## Usage
+
+```html
+<!-- Vertical sortable list -->
+<snice-sortable>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</snice-sortable>
+
+<!-- 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>
+</snice-sortable>
+```
+
+```js
+const sortable = document.querySelector('snice-sortable');
+sortable.addEventListener('sort-change', (e) => {
+  console.log(`Moved from ${e.detail.oldIndex} to ${e.detail.newIndex}`);
+});
+```

package/docs/ai/components/sparkline.md

@@ -1,168 +1,42 @@
 # snice-sparkline
 
-Compact inline chart for visualizing trends and patterns. For dashboards, tables, data-dense interfaces.
+Compact inline chart for visualizing trends and patterns.
 
 ## Properties
 
 ```typescript
-data: number[] = []                     // Values to visualize
-type: SparklineType = 'line'            // 'line' | 'bar' | 'area'
-color: SparklineColor = 'primary'       // 'primary' | 'success' | 'warning' | 'danger' | 'muted'
-customColor?: string                    // Any CSS color (overrides color)
-width: number = 100                     // Chart width in pixels
-height: number = 30                     // Chart height in pixels
-strokeWidth: number = 2                 // Line/dot stroke width
-showDots: boolean = false               // Show dots on data points (line charts)
-showArea: boolean = false               // Show area fill (line charts)
-smooth: boolean = false                 // Use smooth bezier curves
-min?: number                            // Min value for scaling (auto if unset)
-max?: number                            // Max value for scaling (auto if unset)
+data: number[] = [];
+type: 'line'|'bar'|'area' = 'line';
+color: 'primary'|'success'|'warning'|'danger'|'muted' = 'primary';
+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
+smooth: boolean = false;
+min?: number;
+max?: number;
 ```
 
+## CSS Parts
+
+- `container` - Container div
+- `svg` - SVG element
+- `line` - Line/path element
+- `area` - Area polygon/path
+- `bar` - Bar rect
+- `dot` - Dot circle
+
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-sparkline id="chart"></snice-sparkline>
-<script>
-  document.getElementById('chart').data = [10, 20, 15, 25, 30];
-</script>
-
-<!-- Line chart -->
-<snice-sparkline id="line" type="line"></snice-sparkline>
-
-<!-- Bar chart -->
-<snice-sparkline id="bar" type="bar"></snice-sparkline>
-
-<!-- Area chart -->
-<snice-sparkline id="area" type="area"></snice-sparkline>
-
-<!-- Smooth curves -->
-<snice-sparkline id="smooth" smooth></snice-sparkline>
-
-<!-- With dots -->
-<snice-sparkline id="dots" show-dots></snice-sparkline>
+<script>document.getElementById('chart').data = [10, 20, 15, 25, 30];</script>
 
-<!-- With area fill -->
-<snice-sparkline id="fill" show-area></snice-sparkline>
-
-<!-- Colors -->
-<snice-sparkline color="primary"></snice-sparkline>
-<snice-sparkline color="success"></snice-sparkline>
-<snice-sparkline color="warning"></snice-sparkline>
-<snice-sparkline color="danger"></snice-sparkline>
-<snice-sparkline color="muted"></snice-sparkline>
-
-<!-- Custom colors -->
+<snice-sparkline type="bar" color="success"></snice-sparkline>
+<snice-sparkline type="area" color="danger" min="0"></snice-sparkline>
+<snice-sparkline smooth show-area show-dots width="150" height="40"></snice-sparkline>
 <snice-sparkline custom-color="#9333ea"></snice-sparkline>
-<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
-<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
-
-<!-- Sizing -->
-<snice-sparkline width="200" height="50"></snice-sparkline>
-
-<!-- Custom scale -->
 <snice-sparkline min="0" max="100"></snice-sparkline>
-
-<!-- Combined features -->
-<snice-sparkline
-  id="advanced"
-  type="line"
-  color="primary"
-  width="150"
-  height="40"
-  smooth
-  show-area
-  min="0">
-</snice-sparkline>
-```
-
-## CSS Parts
-
-```css
-::part(container)  /* Container div */
-::part(svg)        /* SVG element */
-::part(line)       /* Line/path element */
-::part(area)       /* Area polygon/path */
-::part(bar)        /* Bar rect */
-::part(dot)        /* Dot circle */
-```
-
-## Styling
-
-```css
---snice-color-primary
---snice-color-success
---snice-color-warning
---snice-color-danger
---snice-color-text-secondary
-```
-
-## In Tables
-
-```html
-<snice-table id="table"></snice-table>
-<script>
-  document.getElementById('table').data = [
-    {
-      product: 'A',
-      trend: [10, 15, 12, 18, 22, 25]
-    }
-  ];
-
-  document.getElementById('table').columns = [
-    { key: 'product', label: 'Product' },
-    {
-      key: 'trend',
-      label: 'Trend',
-      render: (value) => {
-        const sparkline = document.createElement('snice-sparkline');
-        sparkline.data = value;
-        sparkline.width = 80;
-        sparkline.height = 25;
-        sparkline.color = 'primary';
-        return sparkline;
-      }
-    }
-  ];
-</script>
-```
-
-## Common Patterns
-
-```html
-<!-- Website traffic -->
-<snice-sparkline
-  id="traffic"
-  color="primary"
-  width="150"
-  height="40"
-  smooth
-  show-area>
-</snice-sparkline>
-
-<!-- Sales bars -->
-<snice-sparkline
-  id="sales"
-  type="bar"
-  color="success"
-  width="150"
-  height="40">
-</snice-sparkline>
-
-<!-- Response time with dots -->
-<snice-sparkline
-  id="response"
-  color="warning"
-  smooth
-  show-dots>
-</snice-sparkline>
-
-<!-- Error rate -->
-<snice-sparkline
-  id="errors"
-  type="area"
-  color="danger"
-  min="0">
-</snice-sparkline>
 ```

package/docs/ai/components/spinner.md

@@ -14,34 +14,13 @@ thickness: number = 4;
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-spinner></snice-spinner>
-
-<!-- Sizes -->
 <snice-spinner size="small"></snice-spinner>
-<snice-spinner size="medium"></snice-spinner>
 <snice-spinner size="large"></snice-spinner>
 <snice-spinner size="xl"></snice-spinner>
-
-<!-- Colors -->
-<snice-spinner color="primary"></snice-spinner>
 <snice-spinner color="success"></snice-spinner>
 <snice-spinner color="warning"></snice-spinner>
 <snice-spinner color="error"></snice-spinner>
-<snice-spinner color="info"></snice-spinner>
-
-<!-- With label -->
 <snice-spinner label="Loading..."></snice-spinner>
-
-<!-- Custom thickness -->
 <snice-spinner thickness="6"></snice-spinner>
 ```
-
-## Features
-
-- Smooth circular animation
-- 4 sizes
-- 5 color variants
-- Optional label
-- Accessible (role=status, aria-label)
-- Lightweight SVG-based

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

@@ -6,25 +6,28 @@ Resizable split pane layout.
 
 ```typescript
 direction: 'horizontal'|'vertical' = 'horizontal';
-primarySize: number = 50; // percentage
-minPrimarySize: number = 10; // percentage
-minSecondarySize: number = 10; // percentage
-snapSize: number = 0; // percentage, 0 = no snap
+primarySize: number = 50;         // attr: primary-size, percentage
+minPrimarySize: number = 10;      // attr: min-primary-size, percentage
+minSecondarySize: number = 10;    // attr: min-secondary-size, percentage
+snapSize: number = 0;             // attr: snap-size, percentage, 0 = no snap
 disabled: boolean = false;
 ```
 
-## Methods
+## Slots
 
-```typescript
-getPrimarySize(): number
-getSecondarySize(): number
-setPrimarySize(size: number): void
-reset(): void
-```
+- `primary` - Primary pane content
+- `secondary` - Secondary pane content
 
 ## Events
 
-- `pane-resize` - Dispatched on resize (detail: { primarySize, secondarySize, splitPane })
+- `pane-resize` → `{ primarySize, secondarySize, splitPane }`
+
+## Methods
+
+- `getPrimarySize()` - Get primary pane percentage
+- `getSecondarySize()` - Get secondary pane percentage
+- `setPrimarySize(size)` - Set primary pane percentage
+- `reset()` - Reset to 50/50
 
 ## Usage
 
@@ -34,38 +37,13 @@ reset(): void
   <div slot="secondary">Right pane</div>
 </snice-split-pane>
 
-<!-- Vertical -->
 <snice-split-pane direction="vertical">
   <div slot="primary">Top</div>
   <div slot="secondary">Bottom</div>
 </snice-split-pane>
 
-<!-- Custom size -->
-<snice-split-pane primary-size="30">
+<snice-split-pane primary-size="30" snap-size="10">
   <div slot="primary">30%</div>
   <div slot="secondary">70%</div>
 </snice-split-pane>
-
-<!-- With snap -->
-<snice-split-pane snap-size="10">
-  <div slot="primary">Snaps to 10%</div>
-  <div slot="secondary">Right</div>
-</snice-split-pane>
-
-<!-- Programmatic -->
-<script>
-  splitPane.setPrimarySize(40);
-  splitPane.reset(); // 50/50
-</script>
 ```
-
-## Features
-
-- Horizontal and vertical orientation
-- Drag to resize
-- Minimum sizes for both panes
-- Snap to grid
-- Programmatic control
-- Nested layouts supported
-- Disabled state
-- Event dispatching

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}`);
+});
+```