snice 4.28.0 → 4.30.0

package/docs/components/step-input.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/step-input.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/step-input.md -->
 
 # Step Input
-`<snice-step-input>`
 
-A numeric stepper control with visible increment and decrement buttons flanking an input field.
+A numeric stepper control with visible increment and decrement buttons flanking an input field. Supports value constraints, wrapping, and keyboard input.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/step-input/snice-step-input';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-step-input.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -27,18 +24,18 @@ import 'snice/components/step-input/snice-step-input';
 | `max` | `number` | `Infinity` | Maximum allowed value |
 | `step` | `number` | `1` | Increment/decrement amount |
 | `disabled` | `boolean` | `false` | Disables all interaction |
-| `readonly` | `boolean` | `false` | Prevents value changes |
+| `readonly` | `boolean` | `false` | Prevents value changes (input remains focusable) |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Control size |
 | `wrap` | `boolean` | `false` | Wrap around at min/max boundaries |
 
 ## Methods
 
-| Method | Arguments | Description |
-|--------|-----------|-------------|
-| `increment()` | -- | Increase value by step |
-| `decrement()` | -- | Decrease value by step |
-| `focus()` | `options?: FocusOptions` | Focus the input field |
-| `blur()` | -- | Remove focus |
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `increment()` | -- | `void` | Increase value by step |
+| `decrement()` | -- | `void` | Decrease value by step |
+| `focus()` | `options?: FocusOptions` | `void` | Focus the input field |
+| `blur()` | -- | `void` | Remove focus |
 
 ## Events
 
@@ -69,7 +66,7 @@ import 'snice/components/step-input/snice-step-input';
 
 ### Sizes
 
-Use the `size` attribute to change the stepper's size.
+Use `size` to change the stepper's dimensions.
 
 ```html
 <snice-step-input size="small" value="3"></snice-step-input>
@@ -79,7 +76,7 @@ Use the `size` attribute to change the stepper's size.
 
 ### Min, Max, and Step
 
-Use the `min`, `max`, and `step` attributes to constrain and control the value range.
+Use `min`, `max`, and `step` to constrain and control the value range.
 
 ```html
 <snice-step-input min="0" max="10" step="1" value="5"></snice-step-input>
@@ -88,38 +85,44 @@ Use the `min`, `max`, and `step` attributes to constrain and control the value r
 
 ### Wrap Around
 
-Set the `wrap` attribute to cycle through values when reaching the min or max boundary.
+Set `wrap` to cycle through values when reaching the min or max boundary.
 
 ```html
 <snice-step-input min="1" max="12" value="12" wrap></snice-step-input>
 ```
 
-### Disabled
-
-Set the `disabled` attribute to prevent user interaction.
+### Disabled and Read Only
 
 ```html
 <snice-step-input value="3" disabled></snice-step-input>
+<snice-step-input value="42" readonly></snice-step-input>
 ```
 
-### Read Only
+### Programmatic Control
+
+```typescript
+const stepper = document.querySelector('snice-step-input');
+stepper.increment(); // value becomes 6
+stepper.decrement(); // value becomes 5
+```
 
-Set the `readonly` attribute to prevent value changes while keeping the input focusable.
+### Event Handling
 
-```html
-<snice-step-input value="42" readonly></snice-step-input>
+```typescript
+stepper.addEventListener('value-change', (e) => {
+  console.log(`Changed from ${e.detail.oldValue} to ${e.detail.value}`);
+});
 ```
 
-### Programmatic Control
+## Keyboard Navigation
 
-Use the `increment()` and `decrement()` methods for programmatic control.
+| Key | Action |
+|-----|--------|
+| `ArrowUp` | Increment by step |
+| `ArrowDown` | Decrement by step |
 
-```html
-<snice-step-input id="qty" min="1" max="99" value="1"></snice-step-input>
+## Accessibility
 
-<script>
-  const stepper = document.getElementById('qty');
-  stepper.increment(); // value becomes 2
-  stepper.decrement(); // value becomes 1
-</script>
-```
+- Buttons are keyboard accessible with visible focus indicators
+- Input field accepts direct keyboard entry
+- Disabled buttons at min/max boundaries (unless `wrap` is set)

package/docs/components/stepper.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/stepper.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/stepper.md -->
 
 # Stepper
-`<snice-stepper>`
 
-A step indicator for visualizing multi-step processes, wizards, and workflows.
+A step indicator for visualizing multi-step processes, wizards, and workflows. Supports horizontal and vertical layouts, clickable navigation, step descriptions, and error states.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/stepper/snice-stepper';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-stepper.min.js"></script>
-```
+- [Properties](#properties)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -27,13 +23,13 @@ import 'snice/components/stepper/snice-stepper';
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
 | `clickable` | `boolean` | `false` | Allow clicking steps for navigation |
 
-### Step Object
+### Step
 
 ```typescript
 interface Step {
   label: string;
   description?: string;
-  status?: 'pending' | 'active' | 'completed' | 'error';
+  status?: 'pending' | 'active' | 'completed' | 'error';  // auto-computed if not set
 }
 ```
 
@@ -41,39 +37,26 @@ interface Step {
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `step-change` | `{ previousStep: number, currentStep: number, step: Step }` | A step was clicked (clickable mode only) |
+| `step-change` | `{ previousStep: number, currentStep: number, step: Step }` | A step was clicked (clickable mode only). Cancelable via `preventDefault()`. |
 
 ## Slots
 
 | Name | Description |
 |------|-------------|
-| (default) | `<snice-stepper-panel>` elements for step content |
+| (default) | `<snice-stepper-panel>` elements for step content (auto show/hide based on `currentStep`) |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `container` | `<div>` | Main stepper container |
-| `step` | `<div>` | Individual step wrapper |
-| `step-indicator` | `<div>` | Circular step number/checkmark |
-| `step-content` | `<div>` | Label + description wrapper |
-| `step-label` | `<div>` | Step label text |
-| `step-description` | `<div>` | Step description text |
-| `step-connector` | `<div>` | Line connecting steps |
-| `panels` | `<div>` | Container wrapping slotted panel content |
-
-```css
-snice-stepper::part(step-indicator) {
-  width: 40px;
-  height: 40px;
-}
-
-snice-stepper::part(step-connector) {
-  background: #3b82f6;
-}
-```
+| Part | Description |
+|------|-------------|
+| `container` | Main stepper container |
+| `step` | Individual step wrapper |
+| `step-indicator` | Circular step number/checkmark |
+| `step-content` | Label and description wrapper |
+| `step-label` | Step label text |
+| `step-description` | Step description text |
+| `step-connector` | Line connecting steps |
+| `panels` | Container wrapping slotted panel content |
 
 ## Basic Usage
 
@@ -100,79 +83,55 @@ import 'snice/components/stepper/snice-stepper';
 
 ### Vertical
 
-Use the `orientation` attribute for a vertical layout.
+Use `orientation="vertical"` for a vertical layout.
 
 ```html
-<snice-stepper id="onboarding" orientation="vertical"></snice-stepper>
-
-<script>
-  document.getElementById('onboarding').steps = [
-    { label: 'Create Account' },
-    { label: 'Profile Setup' },
-    { label: 'Preferences' },
-    { label: 'Complete' }
-  ];
-  document.getElementById('onboarding').currentStep = 2;
-</script>
+<snice-stepper orientation="vertical"></snice-stepper>
 ```
 
 ### With Descriptions
 
 Add optional `description` text to each step.
 
-```html
-<snice-stepper id="detailed"></snice-stepper>
-
-<script>
-  document.getElementById('detailed').steps = [
-    { label: 'Order Details', description: 'Review your items' },
-    { label: 'Shipping', description: 'Enter delivery address' },
-    { label: 'Payment', description: 'Secure checkout' }
-  ];
-</script>
+```typescript
+stepper.steps = [
+  { label: 'Order Details', description: 'Review your items' },
+  { label: 'Shipping', description: 'Enter delivery address' },
+  { label: 'Payment', description: 'Secure checkout' }
+];
 ```
 
 ### Interactive Navigation
 
-Set the `clickable` attribute to allow clicking between steps.
+Set `clickable` to allow clicking between steps. Use `preventDefault()` to block navigation.
 
 ```html
-<snice-stepper id="wizard" clickable></snice-stepper>
-
-<script>
-  const wizard = document.getElementById('wizard');
-  wizard.steps = [
-    { label: 'Account' },
-    { label: 'Profile' },
-    { label: 'Complete' }
-  ];
+<snice-stepper clickable></snice-stepper>
+```
 
-  wizard.addEventListener('step-change', (e) => {
-    console.log('Moved to step:', e.detail.currentStep);
-  });
-</script>
+```typescript
+stepper.addEventListener('step-change', (e) => {
+  console.log(`Moving from step ${e.detail.previousStep} to ${e.detail.currentStep}`);
+  // e.preventDefault(); // block navigation if needed
+});
 ```
 
 ### Error State
 
 Set `status: 'error'` on a step to highlight failures.
 
-```html
-<snice-stepper id="validation"></snice-stepper>
-
-<script>
-  document.getElementById('validation').steps = [
-    { label: 'Upload', status: 'completed' },
-    { label: 'Validate', status: 'error' },
-    { label: 'Process', status: 'pending' }
-  ];
-  document.getElementById('validation').currentStep = 1;
-</script>
+```typescript
+stepper.steps = [
+  { label: 'Upload', status: 'completed' },
+  { label: 'Validate', status: 'error' },
+  { label: 'Process', status: 'pending' }
+];
+stepper.currentStep = 1;
 ```
 
 ### With Panels
 
-Use `<snice-stepper-panel>` children for content that auto-shows based on the active step.
+Use `<snice-stepper-panel>` children for content that auto-shows/hides based on the active step.
 
 ```html
 <snice-stepper id="signup" clickable></snice-stepper>
@@ -200,3 +159,10 @@ Use `<snice-stepper-panel>` children for content that auto-shows based on the ac
   ];
 </script>
 ```
+
+## Accessibility
+
+- Steps with `clickable` are keyboard accessible (Enter/Space to activate)
+- Completed steps show a checkmark indicator
+- Error steps use semantic color coding
+- Navigate via `currentStep` property (increment/decrement/set)

package/docs/components/switch.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/switch.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/switch.md -->
 
 # Switch
-`<snice-switch>`
 
-A toggle switch input for boolean selections.
+A toggle switch input for boolean selections. Supports on/off labels, form integration, and loading state.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/switch/snice-switch';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-switch.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -24,7 +20,7 @@ import 'snice/components/switch/snice-switch';
 |----------|------|---------|-------------|
 | `checked` | `boolean` | `false` | Whether the switch is on |
 | `disabled` | `boolean` | `false` | Disables the switch |
-| `loading` | `boolean` | `false` | Shows loading spinner |
+| `loading` | `boolean` | `false` | Shows loading spinner and disables the switch |
 | `required` | `boolean` | `false` | Makes the switch required |
 | `invalid` | `boolean` | `false` | Shows invalid state |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
@@ -36,12 +32,12 @@ import 'snice/components/switch/snice-switch';
 
 ## Methods
 
-| Method | Arguments | Description |
-|--------|-----------|-------------|
-| `toggle()` | -- | Toggle the switch state |
-| `focus()` | `options?: FocusOptions` | Focus the switch |
-| `blur()` | -- | Remove focus |
-| `click()` | -- | Programmatically click the switch |
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `toggle()` | -- | `void` | Toggle the switch state |
+| `focus()` | `options?: FocusOptions` | `void` | Focus the switch |
+| `blur()` | -- | `void` | Remove focus |
+| `click()` | -- | `void` | Programmatically click the switch |
 
 ## Events
 
@@ -73,12 +69,12 @@ import 'snice/components/switch/snice-switch';
 
 ### Sizes
 
-Use the `size` attribute to change the switch size.
+Use `size` to change the switch dimensions.
 
 ```html
-<snice-switch size="small" label="Small switch"></snice-switch>
-<snice-switch size="medium" label="Medium switch"></snice-switch>
-<snice-switch size="large" label="Large switch"></snice-switch>
+<snice-switch size="small" label="Small"></snice-switch>
+<snice-switch size="medium" label="Medium"></snice-switch>
+<snice-switch size="large" label="Large"></snice-switch>
 ```
 
 ### States
@@ -86,26 +82,27 @@ Use the `size` attribute to change the switch size.
 ```html
 <snice-switch checked label="Enabled"></snice-switch>
 <snice-switch disabled label="Disabled"></snice-switch>
-<snice-switch invalid label="Invalid input"></snice-switch>
+<snice-switch invalid label="Invalid"></snice-switch>
+<snice-switch loading label="Saving..."></snice-switch>
 ```
 
 ### With On/Off Labels
 
-Use the `label-on` and `label-off` attributes for text inside the switch track.
+Use `label-on` and `label-off` for text inside the switch track.
 
 ```html
 <snice-switch label="Dark mode" label-on="ON" label-off="OFF"></snice-switch>
 ```
 
-### In a Form
+### Form Integration
 
-The switch contains a native `<input type="checkbox">` internally, which participates in form submission when `name` is set.
+The switch contains an internal `<input type="checkbox">` that participates in form submission when `name` is set.
 
 ```html
 <form id="settings-form">
   <snice-switch name="notifications" value="enabled" label="Email notifications" required></snice-switch>
-  <snice-switch name="newsletter" value="subscribed" label="Subscribe to newsletter"></snice-switch>
-  <button type="submit">Save Settings</button>
+  <snice-switch name="newsletter" value="subscribed" label="Newsletter"></snice-switch>
+  <button type="submit">Save</button>
 </form>
 
 <script>
@@ -119,12 +116,15 @@ The switch contains a native `<input type="checkbox">` internally, which partici
 
 ### Event Handling
 
-```html
-<snice-switch id="feature-switch" label="Enable feature"></snice-switch>
-
-<script>
-  document.getElementById('feature-switch').addEventListener('switch-change', (e) => {
-    console.log('Switch is', e.detail.checked ? 'on' : 'off');
-  });
-</script>
+```typescript
+el.addEventListener('switch-change', (e) => {
+  console.log('Switch is', e.detail.checked ? 'on' : 'off');
+});
 ```
+
+## Accessibility
+
+- Keyboard toggle with Space key
+- Visible focus ring on keyboard navigation
+- `role="switch"` with `aria-checked` state
+- Loading state disables interaction and shows a spinner

package/docs/components/table.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/table.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/table.md -->
 
 # Table
 `<snice-table>`
 
 Displays tabular data with sorting, filtering, search, selection, pagination, column resize, column menu, tree data, master-detail, toolbar, and 20+ specialized column types.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/table/snice-table';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-table.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Column Definition](#column-definition)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -45,6 +41,8 @@ import 'snice/components/table/snice-table';
 | `currentPage` (attr: `current-page`) | `number` | `1` | Current page number |
 | `totalItems` (attr: `total-items`) | `number` | `0` | Total item count (server mode) |
 | `pageSizes` | `number[]` | `[10, 25, 50, 100]` | Available page size options (JS only) |
+| `columns` | `any[]` | `[]` | Column definitions (JS only) |
+| `data` | `any[]` | `[]` | Row data (JS only) |
 
 ## Column Definition
 
@@ -59,10 +57,13 @@ interface ColumnDefinition {
   align?: 'left' | 'center' | 'right';
   width?: string;
   sortable?: boolean;
-  resizable?: boolean;       // default: true (when column-resize enabled)
-  reorderable?: boolean;     // default: true
-  hideable?: boolean;        // default: true
-  pinnable?: boolean;        // default: true
+  resizable?: boolean;
+  reorderable?: boolean;
+  hideable?: boolean;
+  pinnable?: boolean;
+  pinned?: 'left' | 'right' | false;
+  editable?: boolean;
+  exportable?: boolean;
   formatter?: (value: any, row?: any) => string;
   numberFormat?: { decimals?, thousandsSeparator?, prefix?, suffix?, negativeStyle? };
   ratingFormat?: { max?, color? };
@@ -133,6 +134,10 @@ interface ColumnDefinition {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/table/snice-table';
+```
+
 ```javascript
 table.setColumns([
   { key: 'name', label: 'Name', sortable: true },
@@ -184,7 +189,7 @@ Sparklines and progress bars support per-row color via object values:
 ```
 
 Set `colorize: true` on `progressFormat` to auto-color based on value:
-- Green (≥70%), Yellow (≥40%), Red (<40%)
+- Green (>=70%), Yellow (>=40%), Red (<40%)
 
 ### Toolbar
 
@@ -197,8 +202,6 @@ table.setToolbar({
 });
 ```
 
-The sort and filter buttons open modal dialogs using `snice-modal` with `snice-select` and `snice-input` components.
-
 ### Column Menu (Right-Click)
 
 Enable with `column-menu` attribute. Right-click any column header for:
@@ -210,12 +213,11 @@ Enable with `column-menu` attribute. Right-click any column header for:
 
 ### Column Resize
 
-Enable with `column-resize` attribute. Drag the right edge of any column header to resize. Double-click the resize handle to auto-size to content. Uses `table-layout: fixed` for precise width control.
+Enable with `column-resize` attribute. Drag the right edge of any column header to resize. Double-click the resize handle to auto-size to content.
 
 ### Filter Model (MUI X Pro Compatible)
 
 ```javascript
-// Set filters programmatically
 table.setFilterModel({
   filters: [
     { column: 'name', operator: 'contains', value: 'john' },
@@ -234,9 +236,9 @@ table.setFilterModel({
 
 ```javascript
 table.setTreeData({
-  getPath: (row) => row.path,      // Returns path array e.g. ['US', 'CA']
-  groupColumn: 'name',             // Column with expand/collapse toggle
-  defaultExpansionDepth: 1          // Auto-expand to depth 1
+  getPath: (row) => row.path,
+  groupColumn: 'name',
+  defaultExpansionDepth: 1
 });
 
 table.setData([
@@ -246,12 +248,6 @@ table.setData([
 ]);
 ```
 
-Clicking either the caret icon or the parent node text will expand/collapse.
-
-### Select-All with Filters
-
-When filters are active, the select-all checkbox only selects the visible/filtered rows — not all data. This matches MUI X Pro behavior.
-
 ### Declarative Columns and Rows
 
 ```html
@@ -296,7 +292,6 @@ class UserTableController implements IController {
 
   @respond('table/data')
   async getTableData(params) {
-    // params includes: search, sort, filter, selector, page, pageSize
     const response = await fetch(`/api/users?search=${params.search}`);
     const json = await response.json();
     return { data: json.users, total: json.total };