snice 4.28.0 → 4.30.0

package/docs/components/spreadsheet.md

@@ -1,26 +1,20 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/spreadsheet.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/spreadsheet.md -->
 
-# Spreadsheet Component
+# Spreadsheet
 
-The spreadsheet component provides an Excel-like editable grid with formula support, multi-cell range selection, undo/redo, column resizing, context menus, copy/paste, and an auto-expanding grid. It supports both reading and editing tabular data with full keyboard-driven navigation.
+An Excel-like editable grid with formula support, multi-cell range selection, undo/redo, column resizing, context menus, copy/paste, and auto-expanding rows and columns.
 
 ## Table of Contents
+
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
-- [CSS Custom Properties](#css-custom-properties)
 - [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
 - [Basic Usage](#basic-usage)
-- [Formula Support](#formula-support)
 - [Examples](#examples)
-- [Multi-Cell Selection](#multi-cell-selection)
-- [Column Resizing](#column-resizing)
-- [Context Menu](#context-menu)
-- [Undo/Redo](#undoredo)
-- [Auto-Expanding Grid](#auto-expanding-grid)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
@@ -28,119 +22,45 @@ The spreadsheet component provides an Excel-like editable grid with formula supp
 |----------|------|---------|-------------|
 | `data` | `any[][]` | `[]` | Two-dimensional array of cell values |
 | `columns` | `SpreadsheetColumn[]` | `[]` | Column definitions with header, type, and width |
-| `readonly` | `boolean` | `false` | Prevents cell editing when true |
+| `readonly` | `boolean` | `false` | Prevents cell editing |
 
 ### SpreadsheetColumn
 
 ```typescript
 interface SpreadsheetColumn {
   header: string;               // Column header text
-  type?: 'text' | 'number' | 'date' | 'boolean' | 'select';  // Cell type
+  type?: 'text' | 'number' | 'date' | 'boolean' | 'select';
   width?: number;               // Column width in pixels
-  options?: string[];           // Available options for 'select' type cells
-}
-```
-
-### CellPosition
-
-```typescript
-interface CellPosition {
-  row: number;
-  col: number;
-}
-```
-
-### CellRange
-
-```typescript
-interface CellRange {
-  start: CellPosition;
-  end: CellPosition;
+  options?: string[];           // Options for 'select' type cells
 }
 ```
 
 ## Methods
 
-#### `getCell(row: number, col: number): any`
-Get the resolved value of a cell. For formula cells, returns the computed result.
-
-```typescript
-const value = spreadsheet.getCell(0, 1); // Get value at row 0, column 1
-```
-
-#### `setCell(row: number, col: number, value: any): void`
-Set a cell value. Auto-expands the data grid if the position is beyond current bounds. The change is added to the undo stack.
-
-```typescript
-spreadsheet.setCell(0, 1, 250);
-spreadsheet.setCell(2, 0, '=SUM(B1:B2)');
-```
-
-#### `getData(): any[][]`
-Get a copy of all current data.
-
-```typescript
-const allData = spreadsheet.getData();
-console.log(allData);
-```
-
-#### `setData(data: any[][]): void`
-Replace all data in the spreadsheet.
-
-```typescript
-spreadsheet.setData([
-  ['Alice', 100],
-  ['Bob', 200],
-  ['Total', '=SUM(B1:B2)']
-]);
-```
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getCell()` | `row: number, col: number` | `any` | Get resolved cell value (formulas return computed result) |
+| `setCell()` | `row: number, col: number, value: any` | `void` | Set cell value (auto-expands grid, adds to undo stack) |
+| `getData()` | -- | `any[][]` | Get a copy of all current data |
+| `setData()` | `data: any[][]` | `void` | Replace all data |
 
 ## Events
 
-### `cell-change`
-Fired when a cell value is modified.
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `cell-change` | `{ row: number, col: number, value: any, oldValue: any }` | A cell value was modified |
+| `cell-select` | `{ row: number, col: number }` | A cell was selected |
+| `row-select` | `{ row: number }` | A row was selected (clicked row number) |
+| `column-sort` | `{ col: number, direction: 'asc' \| 'desc' }` | A column header was clicked to sort |
 
-**Event Detail:**
-```typescript
-{
-  row: number;
-  col: number;
-  value: any;
-  oldValue: any;
-}
-```
-
-### `cell-select`
-Fired when a cell is selected.
-
-**Event Detail:**
-```typescript
-{
-  row: number;
-  col: number;
-}
-```
-
-### `row-select`
-Fired when a row is selected (by clicking the row number).
-
-**Event Detail:**
-```typescript
-{
-  row: number;
-}
-```
+## CSS Parts
 
-### `column-sort`
-Fired when a column header is clicked to sort.
-
-**Event Detail:**
-```typescript
-{
-  col: number;
-  direction: 'asc' | 'desc';
-}
-```
+| Part | Description |
+|------|-------------|
+| `formula-bar` | The formula bar with cell reference and input field |
+| `base` | The main spreadsheet grid area |
+| `status-bar` | The bottom status bar showing selection statistics |
+| `context-menu` | The right-click context menu |
 
 ## CSS Custom Properties
 
@@ -156,66 +76,17 @@ Fired when a column header is clicked to sort.
 | `--snice-color-text-secondary` | Formula bar cell reference text | _(theme default)_ |
 | `--snice-color-text-tertiary` | Row numbers, status bar labels, add buttons | _(theme default)_ |
 
-## CSS Parts
-
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `formula-bar` | `<div>` | The formula bar with cell reference and input field |
-| `base` | `<div>` | The main spreadsheet grid area |
-| `status-bar` | `<div>` | The bottom status bar showing selection statistics |
-| `context-menu` | `<div>` | The right-click context menu |
-
-```css
-snice-spreadsheet::part(formula-bar) {
-  background: #f9fafb;
-  border-bottom: 1px solid #e5e7eb;
-}
-
-snice-spreadsheet::part(status-bar) {
-  font-size: 0.75rem;
-  background: #f9fafb;
-}
-```
-
 ## Basic Usage
 
-```html
-<snice-spreadsheet></snice-spreadsheet>
-```
-
 ```typescript
 import 'snice/components/spreadsheet/snice-spreadsheet';
 ```
 
-## Formula Support
-
-Cells starting with `=` are evaluated as formulas. Supported functions:
-
-| Function | Description | Example |
-|----------|-------------|---------|
-| `SUM` | Sum of values in range | `=SUM(A1:A5)` |
-| `AVG` / `AVERAGE` | Average of values in range | `=AVG(B1:B10)` |
-| `COUNT` | Count of non-empty cells in range | `=COUNT(A1:A10)` |
-| `MIN` | Minimum value in range | `=MIN(C1:C5)` |
-| `MAX` | Maximum value in range | `=MAX(C1:C5)` |
-
-Cell references use spreadsheet-style notation (A1, B2, etc.) where letters are columns and numbers are rows.
-
-## Examples
-
-### Basic Spreadsheet with Column Types
-
-Define columns with different cell types and populate with data.
-
 ```html
-<snice-spreadsheet id="basic-sheet"></snice-spreadsheet>
+<snice-spreadsheet id="sheet"></snice-spreadsheet>
 
-<script type="module">
-  import 'snice/components/spreadsheet/snice-spreadsheet';
-
-  const sheet = document.getElementById('basic-sheet');
+<script>
+  const sheet = document.getElementById('sheet');
   sheet.columns = [
     { header: 'Name', type: 'text' },
     { header: 'Amount', type: 'number', width: 100 },
@@ -229,166 +100,77 @@ Define columns with different cell types and populate with data.
 </script>
 ```
 
-### Spreadsheet with Formulas
+## Examples
 
-Use formula cells to calculate totals and summaries.
+### Formula Support
 
-```html
-<snice-spreadsheet id="formula-sheet"></snice-spreadsheet>
+Cells starting with `=` are evaluated as formulas. Supported functions: `SUM`, `AVG`/`AVERAGE`, `COUNT`, `MIN`, `MAX`. Cell references use spreadsheet-style notation (A1, B2).
 
-<script type="module">
-  const sheet = document.getElementById('formula-sheet');
-  sheet.columns = [
-    { header: 'Item', type: 'text', width: 150 },
-    { header: 'Q1', type: 'number', width: 80 },
-    { header: 'Q2', type: 'number', width: 80 },
-    { header: 'Q3', type: 'number', width: 80 },
-    { header: 'Q4', type: 'number', width: 80 }
-  ];
-  sheet.data = [
-    ['Revenue', 1200, 1400, 1100, 1600],
-    ['Expenses', 800, 900, 750, 1000],
-    ['Profit', '=SUM(B1:B1)-SUM(B2:B2)', '=SUM(C1:C1)-SUM(C2:C2)', '=SUM(D1:D1)-SUM(D2:D2)', '=SUM(E1:E1)-SUM(E2:E2)'],
-    ['Average', '=AVG(B1:B2)', '=AVG(C1:C2)', '=AVG(D1:D2)', '=AVG(E1:E2)']
-  ];
-</script>
+```typescript
+sheet.data = [
+  ['Revenue', 1200, 1400, 1100],
+  ['Expenses', 800, 900, 750],
+  ['Profit', '=B1-B2', '=C1-C2', '=D1-D2'],
+  ['Total', '=SUM(B1:B2)', '=AVG(C1:C2)', '=MAX(D1:D2)']
+];
 ```
 
-### Read-Only Spreadsheet
+### Read-Only
 
-Display tabular data in a non-editable spreadsheet.
+Set `readonly` to display data without editing.
 
 ```html
-<snice-spreadsheet id="readonly-sheet" readonly></snice-spreadsheet>
-
-<script type="module">
-  const sheet = document.getElementById('readonly-sheet');
-  sheet.columns = [
-    { header: 'Employee', type: 'text', width: 150 },
-    { header: 'Department', type: 'text', width: 120 },
-    { header: 'Salary', type: 'number', width: 100 }
-  ];
-  sheet.data = [
-    ['Jane Doe', 'Engineering', 95000],
-    ['John Smith', 'Marketing', 78000],
-    ['Lisa Chen', 'Engineering', 102000],
-    ['Total', '', '=SUM(C1:C3)']
-  ];
-</script>
-```
-
-### Listening for Cell Changes
-
-Track edits by listening for the `cell-change` event.
-
-```html
-<snice-spreadsheet id="tracked-sheet"></snice-spreadsheet>
-<p id="change-log">Edit a cell to see changes here.</p>
-
-<script type="module">
-  import type { SniceSpreadsheetElement } from 'snice/components/spreadsheet/snice-spreadsheet.types';
-
-  const sheet = document.getElementById('tracked-sheet') as SniceSpreadsheetElement;
-  const log = document.getElementById('change-log');
-
-  sheet.columns = [
-    { header: 'Product', type: 'text' },
-    { header: 'Price', type: 'number', width: 80 },
-    { header: 'In Stock', type: 'boolean' }
-  ];
-  sheet.data = [
-    ['Widget', 9.99, true],
-    ['Gadget', 24.99, false],
-    ['Gizmo', 14.99, true]
-  ];
-
-  sheet.addEventListener('cell-change', (e) => {
-    log.textContent = `Cell [${e.detail.row}, ${e.detail.col}] changed from "${e.detail.oldValue}" to "${e.detail.value}"`;
-  });
-</script>
+<snice-spreadsheet readonly></snice-spreadsheet>
 ```
 
 ### Date and Boolean Columns
 
 Use specialized cell types for dates and checkboxes.
 
-```html
-<snice-spreadsheet id="typed-sheet"></snice-spreadsheet>
-
-<script type="module">
-  const sheet = document.getElementById('typed-sheet');
-  sheet.columns = [
-    { header: 'Task', type: 'text', width: 200 },
-    { header: 'Due Date', type: 'date', width: 120 },
-    { header: 'Complete', type: 'boolean', width: 80 }
-  ];
-  sheet.data = [
-    ['Design mockups', '2026-03-01', false],
-    ['Write tests', '2026-03-05', true],
-    ['Deploy to staging', '2026-03-10', false]
-  ];
-</script>
+```typescript
+sheet.columns = [
+  { header: 'Task', type: 'text', width: 200 },
+  { header: 'Due Date', type: 'date', width: 120 },
+  { header: 'Complete', type: 'boolean', width: 80 }
+];
+sheet.data = [
+  ['Design mockups', '2026-03-01', false],
+  ['Write tests', '2026-03-05', true],
+];
 ```
 
-## Multi-Cell Selection
+### Event Handling
 
-The spreadsheet supports selecting a range of cells, similar to Excel or Google Sheets.
-
-- **Click and drag**: Click a cell and drag to select a range
-- **Shift+Click**: Click a cell, then Shift+Click another to select the range between them
-- **Shift+Arrow keys**: Extend the selection one cell at a time in the arrow direction
-
-When a range is selected:
-- The anchor cell (where selection started) has a thick blue border
-- Other cells in the range have a light blue fill
-- The **status bar** at the bottom shows COUNT, SUM, and AVG of numeric cells in the selection
-
-## Column Resizing
-
-Drag the right edge of any column header to resize it. A blue highlight appears on hover to indicate the resize handle. The minimum column width is 40px.
-
-## Context Menu
-
-Right-click any cell to open the context menu with these options:
-
-| Action | Description |
-|--------|-------------|
-| Cut | Copy selected cell(s) and clear |
-| Copy | Copy selected cell(s) to clipboard |
-| Paste | Paste from clipboard |
-| Insert Row Above | Add empty row above current |
-| Insert Row Below | Add empty row below current |
-| Delete Row | Remove current row |
-| Insert Column Left | Add empty column to the left |
-| Insert Column Right | Add empty column to the right |
-| Delete Column | Remove current column |
-| Clear Cell(s) | Clear selected cell(s) contents |
-
-The context menu closes when clicking outside, pressing Escape, or selecting an action.
-
-## Undo/Redo
-
-The spreadsheet maintains an undo/redo history stack (up to 100 entries) for cell value changes.
+```typescript
+sheet.addEventListener('cell-change', (e) => {
+  console.log(`Cell [${e.detail.row}, ${e.detail.col}]: ${e.detail.oldValue} -> ${e.detail.value}`);
+});
 
-- **Ctrl+Z**: Undo the last change
-- **Ctrl+Y** or **Ctrl+Shift+Z**: Redo the last undone change
+sheet.addEventListener('column-sort', (e) => {
+  console.log(`Column ${e.detail.col} sorted ${e.detail.direction}`);
+});
+```
 
-The undo history tracks the row, column, old value, and new value for each change.
+### Multi-Cell Selection
 
-## Auto-Expanding Grid
+- Click and drag to select a range
+- Shift+Click to extend selection from the anchor cell
+- Shift+Arrow keys to grow selection one cell at a time
+- Status bar shows COUNT, SUM, and AVG of numeric cells in the selection
 
-The grid auto-expands to create an infinite spreadsheet feel:
+### Context Menu
 
-- **"+" row**: A "+" button row at the bottom appends a new empty row when clicked
-- **"+" column**: A "+" button at the right end of the header appends a new empty column
-- **Tab at last column**: When editing the last column and pressing Tab, a new column is added automatically
-- **Enter at last row**: When editing the last row and pressing Enter, a new row is added automatically
+Right-click any cell for options: Cut, Copy, Paste, Insert Row Above/Below, Delete Row, Insert Column Left/Right, Delete Column, Clear Cell(s).
 
-### Empty State
+### Auto-Expanding Grid
 
-When the data array is empty, the spreadsheet displays a centered message: "Double-click or start typing to add data". Double-clicking the empty state creates the first cell and enters edit mode.
+- "+" button row at bottom appends a new empty row
+- "+" button at right of header appends a new empty column
+- Tab at the last column auto-adds a new column
+- Enter at the last row auto-adds a new row
+- Empty state shows "Double-click or start typing to add data"
 
-## Keyboard Shortcuts
+## Keyboard Navigation
 
 | Shortcut | Action |
 |----------|--------|
@@ -403,18 +185,13 @@ When the data array is empty, the spreadsheet displays a centered message: "Doub
 | Ctrl+V | Paste (supports tab-separated multi-cell paste) |
 | Ctrl+Z | Undo |
 | Ctrl+Y / Ctrl+Shift+Z | Redo |
-| Any printable key | Start editing with that character (type-to-edit) |
+| Any printable key | Start editing with that character |
 
 ## Accessibility
 
-- **Keyboard navigation**: Full keyboard support for navigating, editing, and selecting cells
-- **Focus management**: Selected cell receives visible focus indicator with 2px blue border
-- **Column sorting**: Sort buttons in headers are keyboard accessible
-- **Edit mode**: Enter/F2 activates cell editing, Escape cancels
-- **Type-to-edit**: Simply start typing to begin editing the selected cell
-- **Undo/Redo**: Ctrl+Z and Ctrl+Y provide full change history navigation
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+- Full keyboard navigation for cells, editing, and selection
+- Visible focus indicator (2px blue border) on selected cell
+- Column sort buttons are keyboard accessible
+- Enter/F2 activates editing, Escape cancels
+- Undo/redo history (up to 100 entries) via Ctrl+Z and Ctrl+Y
+- Frozen row numbers (sticky left) and column headers (sticky top)

package/docs/components/stat-group.md

@@ -1,47 +1,34 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/stat-group.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/stat-group.md -->
 
 # Stat Group
 
-`<snice-stat-group>`
-
 A coordinated row of KPI cards with consistent sizing, trend indicators, and responsive grid layout.
 
 ## Table of Contents
+
 - [Properties](#properties)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/stat-group/snice-stat-group';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-stat-group.min.js"></script>
-```
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `stats` | `StatItem[]` | `[]` | Array of stat objects to display |
-| `columns` | `number` | `0` | Number of columns (0 = auto-fit) |
+| `columns` | `number` | `0` | Number of columns (0 = auto-fit based on width) |
 | `variant` | `'card' \| 'minimal' \| 'bordered'` | `'card'` | Visual style variant |
 
-### StatItem Interface
+### StatItem
 
 ```typescript
 interface StatItem {
   label: string;              // Stat label text
   value: string | number;     // Display value
   trend?: 'up' | 'down' | 'neutral';  // Trend direction
-  trendValue?: string;        // Trend comparison text
+  trendValue?: string;        // Trend comparison text (e.g. "+12.5%")
   icon?: string;              // Icon text or emoji
   color?: string;             // Accent color for icon and value
 }
@@ -51,7 +38,7 @@ interface StatItem {
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `stat-click` | `{ stat: StatItem, index: number }` | Fired when a stat card is clicked |
+| `stat-click` | `{ stat: StatItem, index: number }` | A stat card was clicked |
 
 ## CSS Parts
 
@@ -60,16 +47,6 @@ interface StatItem {
 | `base` | The grid container element |
 | `stat` | Individual stat card element |
 
-```css
-snice-stat-group::part(stat) {
-  border-radius: 1rem;
-}
-
-snice-stat-group::part(base) {
-  gap: 2rem;
-}
-```
-
 ## Basic Usage
 
 ```typescript
@@ -82,7 +59,7 @@ import 'snice/components/stat-group/snice-stat-group';
 <script>
   document.getElementById('stats').stats = [
     { label: 'Revenue', value: '$45,231', trend: 'up', trendValue: '+12.5%' },
-    { label: 'Users', value: '2,338', trend: 'up', trendValue: '+8.2%' }
+    { label: 'Users', value: '2,338', trend: 'up', trendValue: '+8.2%' },
   ];
 </script>
 ```
@@ -91,7 +68,7 @@ import 'snice/components/stat-group/snice-stat-group';
 
 ### Variants
 
-Use the `variant` attribute to change the visual style of the stat cards.
+Use `variant` to change the visual style of the stat cards.
 
 ```html
 <!-- Card (default) - bordered cards with hover effects -->
@@ -106,7 +83,7 @@ Use the `variant` attribute to change the visual style of the stat cards.
 
 ### Fixed Column Count
 
-Use the `columns` attribute to set a specific number of columns. When set to `0` (default), columns auto-fit based on available width.
+Use `columns` to set a specific number of columns. Default `0` auto-fits based on width.
 
 ```html
 <snice-stat-group columns="2"></snice-stat-group>
@@ -115,44 +92,33 @@ Use the `columns` attribute to set a specific number of columns. When set to `0`
 
 ### Trend Indicators
 
-Each stat can display a trend direction and value showing comparison data.
+Each stat can display a trend direction with comparison text.
 
-```html
-<script>
-  el.stats = [
-    { label: 'Revenue', value: '$45K', trend: 'up', trendValue: '+12.5% vs last month' },
-    { label: 'Churn', value: '2.3%', trend: 'down', trendValue: '-0.5%' },
-    { label: 'Conversion', value: '3.2%', trend: 'neutral', trendValue: '0.0%' }
-  ];
-</script>
+```typescript
+el.stats = [
+  { label: 'Revenue', value: '$45K', trend: 'up', trendValue: '+12.5% vs last month' },
+  { label: 'Churn', value: '2.3%', trend: 'down', trendValue: '-0.5%' },
+  { label: 'Conversion', value: '3.2%', trend: 'neutral', trendValue: '0.0%' }
+];
 ```
 
 ### With Icons and Colors
 
 Customize each stat with an icon and accent color.
 
-```html
-<script>
-  el.stats = [
-    { label: 'Revenue', value: '$45,231', icon: '$', color: 'rgb(22 163 74)', trend: 'up', trendValue: '+12.5%' },
-    { label: 'Orders', value: '1,245', icon: '\u{1F4E6}', trend: 'down', trendValue: '-3.1%' }
-  ];
-</script>
+```typescript
+el.stats = [
+  { label: 'Revenue', value: '$45,231', icon: '$', color: 'rgb(22 163 74)', trend: 'up', trendValue: '+12.5%' },
+  { label: 'Orders', value: '1,245', icon: '\u{1F4E6}', trend: 'down', trendValue: '-3.1%' }
+];
 ```
 
-### Handling Clicks
-
-Listen for the `stat-click` event to respond when a user clicks a stat card.
-
-```html
-<snice-stat-group id="clickable-stats"></snice-stat-group>
+### Event Handling
 
-<script>
-  document.getElementById('clickable-stats').addEventListener('stat-click', e => {
-    console.log('Clicked stat:', e.detail.stat.label);
-    console.log('Index:', e.detail.index);
-  });
-</script>
+```typescript
+el.addEventListener('stat-click', (e) => {
+  console.log('Clicked:', e.detail.stat.label, 'at index', e.detail.index);
+});
 ```
 
 ## Accessibility