snice 4.9.0 → 4.10.0

package/docs/components/switch.md

@@ -1,354 +1,130 @@
-# Switch Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/switch.md instead)
 
-The `<snice-switch>` component provides a toggle switch input for boolean selections, similar to iOS-style switches.
+# Switch
+`<snice-switch>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Styling](#styling)
-- [Examples](#examples)
+A toggle switch input for boolean selections.
 
 ## Basic Usage
 
-```html
-<snice-switch label="Enable notifications"></snice-switch>
-```
-
 ```typescript
 import 'snice/components/switch/snice-switch';
-
-const switchEl = document.querySelector('snice-switch');
-switchEl.addEventListener('switch-change', (e) => {
-  console.log('Switch is now:', e.detail.checked);
-});
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `checked` | `boolean` | `false` | Whether the switch is in the on position |
-| `disabled` | `boolean` | `false` | Whether the switch is disabled |
-| `required` | `boolean` | `false` | Whether the switch is required in a form |
-| `invalid` | `boolean` | `false` | Whether to show invalid state styling |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant of the switch |
-| `name` | `string` | `''` | Form field name |
-| `value` | `string` | `'on'` | Form field value when checked |
-| `label` | `string` | `''` | Label text displayed next to the switch |
-| `labelOn` | `string` | `''` | Label shown on the switch when in on position |
-| `labelOff` | `string` | `''` | Label shown on the switch when in off position |
-
-## Methods
-
-### `toggle(): void`
-Toggle the switch state between on and off.
-
-```typescript
-switchEl.toggle();
-```
-
-### `focus(): void`
-Give focus to the switch input.
-
-```typescript
-switchEl.focus();
 ```
 
-### `blur(): void`
-Remove focus from the switch input.
-
-```typescript
-switchEl.blur();
+```html
+<snice-switch label="Enable notifications"></snice-switch>
 ```
 
-### `click(): void`
-Programmatically click the switch.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-switchEl.click();
+import 'snice/components/switch/snice-switch';
 ```
 
-## Events
-
-### `switch-change`
-Fired when the switch state changes.
-
-**Event Detail:**
-```typescript
-{
-  checked: boolean;           // New checked state
-  switch: SniceSwitchElement; // Reference to the switch element
-}
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-switch.min.js"></script>
 ```
 
-**Usage:**
-```typescript
-switchEl.addEventListener('switch-change', (e) => {
-  const { checked } = e.detail;
-  console.log(`Switch is ${checked ? 'on' : 'off'}`);
-});
-```
+## Examples
 
-## Styling
+### Sizes
 
-### Size Variants
+Use the `size` attribute to change the switch size.
 
 ```html
-<!-- Small -->
 <snice-switch size="small" label="Small switch"></snice-switch>
-
-<!-- Medium (default) -->
 <snice-switch size="medium" label="Medium switch"></snice-switch>
-
-<!-- Large -->
 <snice-switch size="large" label="Large switch"></snice-switch>
 ```
 
-### State Variants
+### States
 
 ```html
-<!-- Checked -->
 <snice-switch checked label="Enabled"></snice-switch>
-
-<!-- Disabled -->
 <snice-switch disabled label="Disabled"></snice-switch>
-
-<!-- Invalid -->
 <snice-switch invalid label="Invalid input"></snice-switch>
-
-<!-- Required -->
-<snice-switch required label="Required *"></snice-switch>
 ```
 
-## Examples
+### With On/Off Labels
 
-### Basic Switch
+Use the `label-on` and `label-off` attributes for text inside the switch track.
 
 ```html
-<snice-switch label="Enable feature"></snice-switch>
+<snice-switch label="Dark mode" label-on="ON" label-off="OFF"></snice-switch>
 ```
 
-### With On/Off Labels
-
-```html
-<snice-switch
-  label="Dark mode"
-  label-on="ON"
-  label-off="OFF">
-</snice-switch>
-```
+### In a Form
 
-### Form Integration
+The switch is form-associated and participates in form submission.
 
 ```html
-<form id="settingsForm">
-  <snice-switch
-    name="notifications"
-    value="enabled"
-    label="Email notifications"
-    required>
-  </snice-switch>
-
-  <snice-switch
-    name="newsletter"
-    value="subscribed"
-    label="Subscribe to newsletter">
-  </snice-switch>
-
+<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>
 </form>
 
-<script type="module">
-  import 'snice/components/switch/snice-switch';
-
-  const form = document.querySelector('#settingsForm');
-
-  form.addEventListener('submit', (e) => {
+<script>
+  document.getElementById('settings-form').addEventListener('submit', (e) => {
     e.preventDefault();
-
-    const formData = new FormData(form);
-    const settings = Object.fromEntries(formData);
-
-    console.log('Settings:', settings);
-    // { notifications: 'enabled' } if checked
+    const formData = new FormData(e.target);
+    console.log('Settings:', Object.fromEntries(formData));
   });
 </script>
 ```
 
-### Programmatic Control
-
-```typescript
-import type { SniceSwitchElement } from 'snice/components/switch/snice-switch.types';
-
-const switchEl = document.querySelector<SniceSwitchElement>('snice-switch');
-
-// Toggle programmatically
-switchEl.toggle();
-
-// Set specific state
-switchEl.checked = true;
-
-// Enable/disable
-switchEl.disabled = true;
-```
-
-### With Event Handling
-
-```typescript
-const switchEl = document.querySelector('snice-switch');
-
-switchEl.addEventListener('switch-change', (e) => {
-  const { checked, switch: sw } = e.detail;
-
-  if (checked) {
-    console.log('Feature enabled');
-    enableFeature();
-  } else {
-    console.log('Feature disabled');
-    disableFeature();
-  }
-});
-
-function enableFeature() {
-  // Enable feature logic
-}
-
-function disableFeature() {
-  // Disable feature logic
-}
-```
-
-### Validation Example
+### Event Handling
 
 ```html
-<form id="termsForm">
-  <snice-switch
-    id="termsSwitch"
-    name="terms"
-    label="I agree to the terms and conditions"
-    required>
-  </snice-switch>
-
-  <button type="submit">Continue</button>
-</form>
+<snice-switch id="feature-switch" label="Enable feature"></snice-switch>
 
-<script type="module">
-  import 'snice/components/switch/snice-switch';
-
-  const form = document.querySelector('#termsForm');
-  const termsSwitch = document.querySelector('#termsSwitch');
-
-  form.addEventListener('submit', (e) => {
-    e.preventDefault();
-
-    if (!termsSwitch.checked) {
-      termsSwitch.invalid = true;
-      alert('You must agree to the terms');
-      return;
-    }
-
-    termsSwitch.invalid = false;
-    // Continue with form submission
+<script>
+  document.getElementById('feature-switch').addEventListener('switch-change', (e) => {
+    console.log('Switch is', e.detail.checked ? 'on' : 'off');
   });
 </script>
 ```
 
-### Multiple Switches
-
-```html
-<div class="settings-group">
-  <h3>Privacy Settings</h3>
-
-  <snice-switch
-    label="Public profile"
-    name="public_profile"
-    checked>
-  </snice-switch>
-
-  <snice-switch
-    label="Show email"
-    name="show_email">
-  </snice-switch>
-
-  <snice-switch
-    label="Show phone number"
-    name="show_phone">
-  </snice-switch>
-
-  <snice-switch
-    label="Allow messages from anyone"
-    name="allow_messages">
-  </snice-switch>
-</div>
-
-<style>
-  .settings-group {
-    display: flex;
-    flex-direction: column;
-    gap: 16px;
-    max-width: 400px;
-  }
-
-  .settings-group snice-switch {
-    padding: 8px 0;
-    border-bottom: 1px solid #e5e7eb;
-  }
-
-  .settings-group snice-switch:last-child {
-    border-bottom: none;
-  }
-</style>
-```
-
-### Custom Styling with CSS Parts
-
-```html
-<style>
-  snice-switch::part(track) {
-    background: linear-gradient(to right, #667eea, #764ba2);
-  }
-
-  snice-switch[checked]::part(track) {
-    background: linear-gradient(to right, #f093fb, #f5576c);
-  }
-
-  snice-switch::part(thumb) {
-    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
-  }
-
-  snice-switch::part(label) {
-    font-weight: 600;
-    color: #1f2937;
-  }
-</style>
-
-<snice-switch label="Custom styled switch" checked></snice-switch>
-```
-
-## Accessibility
-
-The switch component includes proper ARIA attributes:
-
-- `role="switch"` on the input element
-- `aria-checked` reflects the current state
-- `aria-invalid` when invalid state is set
-- Native `<input type="checkbox">` for form compatibility
-- Keyboard accessible (Space/Enter to toggle)
-- Focus visible state
+## Properties
 
-## Form Behavior
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `checked` | `boolean` | `false` | Whether the switch is on |
+| `disabled` | `boolean` | `false` | Disables the switch |
+| `loading` | `boolean` | `false` | Shows loading spinner |
+| `required` | `boolean` | `false` | Makes the switch required |
+| `invalid` | `boolean` | `false` | Shows invalid state |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `name` | `string` | `''` | Form field name |
+| `value` | `string` | `'on'` | Form value when checked |
+| `label` | `string` | `''` | Label text |
+| `labelOn` (attr: `label-on`) | `string` | `''` | Text on switch track when on |
+| `labelOff` (attr: `label-off`) | `string` | `''` | Text on switch track when off |
 
-The switch component works seamlessly with HTML forms:
+## Events
 
-- Acts like a checkbox input
-- Only included in form data when checked
-- Supports `name` and `value` attributes
-- Supports `required` attribute for validation
-- Compatible with FormData API
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `switch-change` | `{ checked: boolean, switch: SniceSwitchElement }` | Switch state changed |
 
-## Browser Support
+## Methods
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `toggle()` | -- | Toggle the switch state |
+| `focus()` | `options?: FocusOptions` | Focus the switch |
+| `blur()` | -- | Remove focus |
+| `click()` | -- | Programmatically click the switch |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | Hidden input element |
+| `track` | Switch track |
+| `thumb` | Switch thumb |
+| `spinner` | Loading spinner |
+| `label` | Label text |

package/docs/components/table.md

@@ -0,0 +1,250 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/table.md instead)
+
+# Table
+`<snice-table>`
+
+Displays tabular data with sorting, searching, filtering, row selection, and specialized column types.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/table/snice-table';
+```
+
+```html
+<snice-table id="users"></snice-table>
+
+<script>
+  const table = document.querySelector('#users');
+  table.setColumns([
+    { key: 'name', label: 'Name' },
+    { key: 'email', label: 'Email' },
+    { key: 'age', label: 'Age', type: 'number', align: 'right' }
+  ]);
+  table.setData([
+    { name: 'Alice Johnson', email: 'alice@example.com', age: 32 },
+    { name: 'Bob Smith', email: 'bob@example.com', age: 28 }
+  ]);
+</script>
+```
+
+## 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>
+```
+
+## Examples
+
+### Striped and Hoverable
+
+Use the `striped` attribute for alternating row colors and `hoverable` for row highlight on hover.
+
+```html
+<snice-table striped hoverable></snice-table>
+```
+
+### List Mode
+
+Use the `list` attribute to hide vertical cell borders for a cleaner list appearance.
+
+```html
+<snice-table list></snice-table>
+```
+
+### Sortable Columns
+
+Set the `sortable` attribute to enable column sorting. Clicking a column header cycles through ascending, descending, and unsorted states. Multi-column sort is supported.
+
+```html
+<snice-table sortable></snice-table>
+
+<script>
+  const table = document.querySelector('snice-table');
+  table.setColumns([
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'age', label: 'Age', type: 'number', sortable: true },
+    { key: 'role', label: 'Role', sortable: false }
+  ]);
+</script>
+```
+
+### Searchable
+
+Set the `searchable` attribute to show a search input above the table.
+
+```html
+<snice-table searchable search-debounce="300"></snice-table>
+```
+
+### Row Selection
+
+Set the `selectable` attribute to enable row selection with checkboxes and a select-all header checkbox.
+
+```html
+<snice-table selectable></snice-table>
+
+<script>
+  const table = document.querySelector('snice-table');
+  table.addEventListener('table-row-selection-changed', (e) => {
+    console.log('Selected rows:', e.detail.selectedRows);
+  });
+</script>
+```
+
+### Clickable Rows
+
+Set the `clickable` attribute to emit events when rows are clicked.
+
+```html
+<snice-table clickable></snice-table>
+
+<script>
+  const table = document.querySelector('snice-table');
+  table.addEventListener('row-clicked', (e) => {
+    console.log('Clicked row:', e.detail.rowData);
+  });
+</script>
+```
+
+### Column Types
+
+Use the `type` property on column definitions to apply specialized formatting.
+
+```javascript
+table.setColumns([
+  { key: 'name', label: 'Name', type: 'text' },
+  { key: 'price', label: 'Price', type: 'number', decimals: 2, prefix: '$' },
+  { key: 'created', label: 'Created', type: 'date', dateFormat: 'medium' },
+  { key: 'active', label: 'Active', type: 'boolean', useSymbols: true },
+  { key: 'rating', label: 'Rating', type: 'rating' },
+  { key: 'progress', label: 'Progress', type: 'progress' },
+  { key: 'trend', label: 'Trend', type: 'sparkline' },
+  { key: 'elapsed', label: 'Elapsed', type: 'duration' },
+  { key: 'size', label: 'Size', type: 'filesize' }
+]);
+```
+
+### Loading State
+
+Set the `loading` attribute to dim the table body and show a loading indicator.
+
+```html
+<snice-table loading></snice-table>
+```
+
+### Declarative Columns and Rows
+
+Use `<snice-column>` and `<snice-row>` elements for a declarative table structure.
+
+```html
+<snice-table striped hoverable>
+  <snice-column slot="columns" key="name" label="Name"></snice-column>
+  <snice-column slot="columns" key="email" label="Email"></snice-column>
+
+  <snice-row slot="rows" data='{"name":"Alice","email":"alice@example.com"}'></snice-row>
+  <snice-row slot="rows" data='{"name":"Bob","email":"bob@example.com"}'></snice-row>
+</snice-table>
+```
+
+### With Controller (Request/Respond)
+
+Use the `@request`/`@respond` pattern to load data from an external source.
+
+```html
+<my-table-controller></my-table-controller>
+<snice-table searchable sortable></snice-table>
+
+<script type="module">
+  import { element, respond } from 'snice';
+
+  @element('my-table-controller')
+  class MyTableController extends HTMLElement {
+    @respond('@snice/table/config')
+    getConfig() {
+      return {
+        columns: [
+          { key: 'name', label: 'Name' },
+          { key: 'status', label: 'Status', type: 'boolean' }
+        ]
+      };
+    }
+
+    @respond('@snice/table/data')
+    async getData(params) {
+      const response = await fetch(`/api/users?search=${params.search}`);
+      const data = await response.json();
+      return { data };
+    }
+  }
+</script>
+```
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `columns` | `<snice-column>` elements for declarative column definitions |
+| `rows` | `<snice-row>` elements for declarative row data |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `striped` | `boolean` | `false` | Alternating row background colors |
+| `searchable` | `boolean` | `false` | Show search input |
+| `filterable` | `boolean` | `false` | Show filter dropdown |
+| `sortable` | `boolean` | `false` | Enable column sorting |
+| `selectable` | `boolean` | `false` | Enable row selection with checkboxes |
+| `hoverable` | `boolean` | `true` | Highlight rows on hover |
+| `clickable` | `boolean` | `false` | Emit events on row click |
+| `list` | `boolean` | `false` | Hide vertical cell borders |
+| `searchDebounce` (attr: `search-debounce`) | `number` | `500` | Search input debounce in milliseconds |
+| `currentSort` (attr: `current-sort`) | `Array<{ column: string, direction: 'asc' \| 'desc' }>` | `[]` | Current sort state |
+| `selector` | `string` | `''` | Current selector filter value |
+| `selectorOptions` (attr: `selector-options`) | `Array<{ value: string, label: string }>` | `[]` | Dropdown filter options |
+| `loading` | `boolean` | `false` | Show loading state |
+| `selectedRows` (attr: `selected-rows`) | `number[]` | `[]` | Indices of selected rows |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `table-row-selection-changed` | `{ selectedRows: number[], rowIndex: number, selected: boolean }` | A row's selection state changed |
+| `table-select-all-changed` | `{ selectedRows: number[], allSelected: boolean }` | Select-all checkbox toggled |
+| `row-clicked` | `{ rowData: any, rowIndex: number }` | A row was clicked (requires `clickable`) |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `setData()` | `data: any[]` | Set table row data |
+| `setColumns()` | `columns: ColumnDefinition[]` | Set column definitions |
+| `renderHeader()` | -- | Re-render the table header |
+| `renderBody()` | -- | Re-render the table body |
+| `toggleSort()` | `columnKey: string, multiSort?: boolean` | Toggle sort on a column |
+
+## Column Definition
+
+```typescript
+interface ColumnDefinition {
+  key: string;
+  label: string;
+  type?: 'text' | 'number' | 'date' | 'boolean' | 'currency' | 'percent' |
+         'rating' | 'progress' | 'sparkline' | 'accounting' | 'scientific' |
+         'fraction' | 'duration' | 'filesize' | 'custom';
+  align?: 'left' | 'center' | 'right';
+  width?: string;
+  sortable?: boolean;
+  filterable?: boolean;
+  formatter?: (value: any, row?: any) => string;
+  conditionalFormats?: ConditionalFormat[];
+}
+```