snice 4.28.0 → 4.30.0

package/docs/components/select.md

@@ -1,25 +1,29 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/select.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/select.md -->
 
 # Select
-`<snice-select>`
 
-A customizable dropdown selection with single/multiple selection, search filtering, and composable options.
+A customizable dropdown selection with single/multiple selection, search filtering, editable input mode, and composable options.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/select/snice-select';
-import 'snice/components/select/snice-option';
-```
+- [Components](#components)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-select.min.js"></script>
-```
+## Components
 
-## Select Properties
+- `<snice-select>` - The select container with trigger, dropdown, and form integration
+- `<snice-option>` - Individual option elements (declarative API)
+
+## Properties
+
+### Select Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -30,7 +34,7 @@ import 'snice/components/select/snice-option';
 | `readonly` | `boolean` | `false` | Readonly state |
 | `loading` | `boolean` | `false` | Shows loading spinner |
 | `multiple` | `boolean` | `false` | Allow multiple selection |
-| `searchable` | `boolean` | `false` | Show search input |
+| `searchable` | `boolean` | `false` | Show search input in dropdown |
 | `clearable` | `boolean` | `false` | Show clear button |
 | `editable` | `boolean` | `false` | Render editable text input instead of button trigger |
 | `allowFreeText` (attr: `allow-free-text`) | `boolean` | `false` | Allow values not in the options list |
@@ -42,9 +46,9 @@ import 'snice/components/select/snice-option';
 | `label` | `string` | `''` | Label text |
 | `placeholder` | `string` | `'Select an option'` | Placeholder text |
 | `maxHeight` (attr: `max-height`) | `string` | `'200px'` | Maximum dropdown height |
-| `options` | `SelectOption[]` | `[]` | Programmatic options array |
+| `options` | `SelectOption[]` | `[]` | Programmatic options array (JS only) |
 
-## Option Properties
+### Option Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -58,22 +62,38 @@ import 'snice/components/select/snice-option';
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
+| `focus()` | — | Focus the select trigger |
+| `blur()` | — | Remove focus and close dropdown |
+| `clear()` | — | Clear the selection |
+| `openDropdown()` | — | Open the dropdown |
+| `closeDropdown()` | — | Close the dropdown |
+| `toggleDropdown()` | — | Toggle the dropdown |
 | `selectOption()` | `value: string` | Select an option by value |
-| `clear()` | -- | Clear the selection |
-| `openDropdown()` | -- | Open the dropdown |
-| `closeDropdown()` | -- | Close the dropdown |
-| `toggleDropdown()` | -- | Toggle the dropdown |
-| `focus()` | -- | Focus the select trigger |
-| `blur()` | -- | Remove focus and close dropdown |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `select-change` | `{ value, option, select }` | Selection changed |
+| `select-change` | `{ value: string \| string[], option?: SelectOption, select }` | Selection changed |
 | `select-open` | `{ select }` | Dropdown opened |
 | `select-close` | `{ select }` | Dropdown closed |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `label` | The label text |
+| `trigger` | The trigger button or input container |
+| `value` | The displayed value text |
+| `input` | The hidden native select for form submission |
+| `arrow` | The dropdown arrow icon |
+| `spinner` | The loading spinner |
+| `dropdown` | The dropdown container |
+| `search` | The search wrapper |
+| `search-input` | The search text input |
+| `options` | The options list container |
+| `option` | Individual option items |
+
 ## Basic Usage
 
 ```typescript
@@ -91,76 +111,84 @@ import 'snice/components/select/snice-option';
 
 ## Examples
 
-### Sizes
-
-Use the `size` attribute to change the select size.
-
-```html
-<snice-select size="small" label="Small">
-  <snice-option value="a">Option A</snice-option>
-  <snice-option value="b">Option B</snice-option>
-</snice-select>
-
-<snice-select size="large" label="Large">
-  <snice-option value="a">Option A</snice-option>
-  <snice-option value="b">Option B</snice-option>
-</snice-select>
-```
-
 ### Multiple Selection
 
-Set the `multiple` attribute to allow selecting more than one option.
+Set `multiple` to allow selecting more than one option.
 
 ```html
-<snice-select label="Select languages" multiple>
+<snice-select label="Languages" multiple>
   <snice-option value="js">JavaScript</snice-option>
   <snice-option value="ts">TypeScript</snice-option>
   <snice-option value="py">Python</snice-option>
-  <snice-option value="rs">Rust</snice-option>
 </snice-select>
 ```
 
 ### Searchable
 
-Set the `searchable` attribute to show a search input for filtering options.
+Set `searchable` to show a search input for filtering options.
 
 ```html
-<snice-select label="Choose a country" searchable>
+<snice-select label="Country" searchable>
   <snice-option value="us">United States</snice-option>
   <snice-option value="uk">United Kingdom</snice-option>
   <snice-option value="ca">Canada</snice-option>
-  <snice-option value="au">Australia</snice-option>
-  <snice-option value="de">Germany</snice-option>
 </snice-select>
 ```
 
-### Clearable
+### Editable Mode
 
-Set the `clearable` attribute to show a clear button.
+Set `editable` to render a text input instead of a button. Typing filters options.
 
 ```html
-<snice-select label="Clearable select" clearable>
-  <snice-option value="1">Option 1</snice-option>
-  <snice-option value="2">Option 2</snice-option>
-</snice-select>
+<snice-select editable label="Fruit" placeholder="Type or select..."></snice-select>
 ```
 
-### Disabled Options
+```typescript
+select.options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'banana', label: 'Banana' },
+  { value: 'cherry', label: 'Cherry' }
+];
+```
+
+### Allow Free Text
+
+Set `allow-free-text` with `editable` to accept values not in the options list.
+
+```html
+<snice-select editable allow-free-text label="Tag" placeholder="Type a tag..."></snice-select>
+```
+
+### Remote Search
+
+Set `remote` with `searchable` or `editable` for async search via `@request/@respond`.
+
+```typescript
+// Controller
+@respond('select/search')
+async handleSearch(req, respond) {
+  const results = await fetch(`/api/users?q=${req.query}`).then(r => r.json());
+  respond(results.map(u => ({ value: u.id, label: u.name })));
+}
+```
+
+### Clearable
+
+Set `clearable` to show a clear button.
 
 ```html
-<snice-select label="With disabled option">
-  <snice-option value="active">Active</snice-option>
-  <snice-option value="unavailable" disabled>Unavailable</snice-option>
-  <snice-option value="other">Other</snice-option>
+<snice-select label="Clearable" clearable>
+  <snice-option value="1">Option 1</snice-option>
+  <snice-option value="2">Option 2</snice-option>
 </snice-select>
 ```
 
 ### With Icons
 
-Use the `icon` attribute on options to display an image.
+Use the `icon` attribute on options to display images.
 
 ```html
-<snice-select label="Select role">
+<snice-select label="Role">
   <snice-option value="user" icon="/icons/user.svg">User</snice-option>
   <snice-option value="admin" icon="/icons/admin.svg">Admin</snice-option>
 </snice-select>
@@ -168,92 +196,42 @@ Use the `icon` attribute on options to display an image.
 
 ### Form Integration
 
+The select participates in forms via a hidden native select element.
+
 ```html
 <form>
   <snice-select name="role" label="User role" required>
     <snice-option value="user">User</snice-option>
     <snice-option value="admin">Admin</snice-option>
-    <snice-option value="moderator">Moderator</snice-option>
   </snice-select>
   <button type="submit">Submit</button>
 </form>
 ```
 
-```typescript
-form.addEventListener('submit', (e) => {
-  e.preventDefault();
-  console.log(Object.fromEntries(new FormData(e.target)));
-});
-```
-
-### Programmatic Control
-
-```typescript
-select.selectOption('apple');
-select.clear();
-select.openDropdown();
-select.closeDropdown();
-select.toggleDropdown();
-```
-
 ### Event Handling
 
+Listen to `select-change` for selection changes.
+
 ```typescript
 select.addEventListener('select-change', (e) => {
   console.log('Selected:', e.detail.value);
 });
-
-select.addEventListener('select-open', () => console.log('Opened'));
-select.addEventListener('select-close', () => console.log('Closed'));
 ```
 
-### Validation
+## Keyboard Navigation
 
-```html
-<snice-select name="category" label="Category" required>
-  <snice-option value="tech">Technology</snice-option>
-  <snice-option value="health">Health</snice-option>
-</snice-select>
-```
+| Key | Action |
+|-----|--------|
+| `ArrowDown` | Move to next option / open dropdown |
+| `ArrowUp` | Move to previous option |
+| `Enter` | Select focused option / open dropdown |
+| `Escape` | Close dropdown |
+| `Tab` | Close dropdown and move focus |
 
-```typescript
-function validate() {
-  select.invalid = !select.value;
-  return !!select.value;
-}
-```
-
-### Editable Mode
+## Accessibility
 
-Set the `editable` attribute to render a text input instead of a button. Users can type to filter or enter custom values (with `allow-free-text`). This replaces the need for a separate combobox component.
-
-```html
-<snice-select editable label="Choose a fruit" placeholder="Type or select..."></snice-select>
-```
-
-```typescript
-select.options = [
-  { value: 'apple', label: 'Apple' },
-  { value: 'banana', label: 'Banana' },
-  { value: 'cherry', label: 'Cherry' },
-];
-```
-
-#### Allow Custom Values
-
-Set `allow-free-text` alongside `editable` to let users enter values not in the options list.
-
-```html
-<snice-select editable allow-free-text label="Tag" placeholder="Type a tag..."></snice-select>
-```
-
-#### Programmatic Options
-
-Use the `options` property to set options via JavaScript. Works alongside child `<snice-option>` elements (merged at render time, children take precedence).
-
-```typescript
-select.options = [
-  { value: 'us', label: 'United States', icon: '/flags/us.png' },
-  { value: 'uk', label: 'United Kingdom', icon: '/flags/uk.png' },
-];
-```
+- Hidden native `<select>` for form submission
+- Keyboard navigable with arrow keys, Enter, and Escape
+- Dropdown closes on outside click
+- Multiple selection values are comma-separated
+- Child `<snice-option>` elements take precedence over `options` array when both provided

package/docs/components/skeleton.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/skeleton.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/skeleton.md -->
 
 # Skeleton
-`<snice-skeleton>`
 
 Displays placeholder loading animations to indicate content is being loaded.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/skeleton/snice-skeleton';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-skeleton.min.js"></script>
-```
+- [Properties](#properties)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -27,7 +22,7 @@ import 'snice/components/skeleton/snice-skeleton';
 | `height` | `string` | `''` | Custom height (CSS value) |
 | `animation` | `'pulse' \| 'wave' \| 'none'` | `'wave'` | Animation style |
 | `count` | `number` | `1` | Number of skeleton lines to render |
-| `spacing` | `string` | `'8px'` | Gap between multiple skeleton lines |
+| `spacing` | `string` | `'8px'` | Gap between multiple lines |
 
 ## CSS Custom Properties
 
@@ -39,22 +34,10 @@ import 'snice/components/skeleton/snice-skeleton';
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer skeleton container |
-| `bone` | `<div>` | Individual skeleton placeholder element |
-
-```css
-snice-skeleton::part(bone) {
-  border-radius: 0.5rem;
-}
-
-snice-skeleton::part(base) {
-  padding: 0.5rem;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | Outer skeleton container |
+| `bone` | Individual skeleton placeholder element |
 
 ## Basic Usage
 
@@ -74,31 +57,22 @@ Use the `variant` attribute to change the skeleton shape.
 
 ```html
 <snice-skeleton variant="text"></snice-skeleton>
-<snice-skeleton variant="circular"></snice-skeleton>
-<snice-skeleton variant="rectangular"></snice-skeleton>
-<snice-skeleton variant="rounded"></snice-skeleton>
+<snice-skeleton variant="circular" width="64px" height="64px"></snice-skeleton>
+<snice-skeleton variant="rectangular" width="200px" height="150px"></snice-skeleton>
+<snice-skeleton variant="rounded" width="300px" height="150px"></snice-skeleton>
 ```
 
 ### Paragraph
 
-Set the `count` attribute to render multiple skeleton lines, simulating a paragraph.
+Set `count` to render multiple skeleton lines simulating a paragraph.
 
 ```html
 <snice-skeleton variant="text" count="4"></snice-skeleton>
 ```
 
-### Custom Dimensions
-
-Use the `width` and `height` attributes to set custom sizes.
-
-```html
-<snice-skeleton variant="rectangular" width="200px" height="150px"></snice-skeleton>
-<snice-skeleton variant="circular" width="64px" height="64px"></snice-skeleton>
-```
-
 ### Animation Styles
 
-Use the `animation` attribute to change the loading animation.
+Use `animation` to change the loading animation.
 
 ```html
 <snice-skeleton animation="wave"></snice-skeleton>
@@ -106,10 +80,22 @@ Use the `animation` attribute to change the loading animation.
 <snice-skeleton animation="none"></snice-skeleton>
 ```
 
-### Spacing
+### Complex Layout
 
-Use the `spacing` attribute to control the gap between multiple skeleton lines.
+Combine variants to create loading placeholders for cards or profiles.
 
 ```html
-<snice-skeleton variant="text" count="3" spacing="12px"></snice-skeleton>
+<div style="display: flex; gap: 16px;">
+  <snice-skeleton variant="circular" width="48px" height="48px"></snice-skeleton>
+  <div style="flex: 1;">
+    <snice-skeleton variant="text" width="40%"></snice-skeleton>
+    <snice-skeleton variant="text" width="60%"></snice-skeleton>
+  </div>
+</div>
 ```
+
+## Accessibility
+
+- Purely decorative placeholder; does not convey content to screen readers
+- Use `aria-busy="true"` on the container element while loading
+- Replace with actual content once loaded

package/docs/components/slider.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/slider.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/slider.md -->
 
 # Slider
-`<snice-slider>`
 
-An interactive range slider for selecting numeric values with mouse, touch, and keyboard support.
+An interactive range slider for selecting numeric values with mouse, touch, and keyboard support. Form-associated.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/slider/snice-slider';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-slider.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
 
@@ -35,21 +32,22 @@ import 'snice/components/slider/snice-slider';
 | `readonly` | `boolean` | `false` | Makes the slider read-only |
 | `required` | `boolean` | `false` | Makes the slider required |
 | `invalid` | `boolean` | `false` | Shows invalid state |
+| `loading` | `boolean` | `false` | Shows loading spinner |
 | `name` | `string` | `''` | Form field name |
 | `showValue` (attr: `show-value`) | `boolean` | `false` | Display current value |
-| `showTicks` (attr: `show-ticks`) | `boolean` | `false` | Show tick marks |
+| `showTicks` (attr: `show-ticks`) | `boolean` | `false` | Show tick marks along the track |
 | `vertical` | `boolean` | `false` | Vertical orientation |
-| `loading` | `boolean` | `false` | Show loading spinner |
-| `form-align` | (CSS-only attribute) | -- | Gives the track area `min-height: 2.5rem` to align with input/select fields in form rows |
+
+The `form-align` HTML attribute (CSS-only, no JS property) gives the track area `min-height: 2.5rem` to align with input/select fields in form rows.
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
 | `focus()` | `options?: FocusOptions` | Focus the slider thumb |
-| `blur()` | -- | Remove focus |
-| `checkValidity()` | -- | Check validation, returns `boolean` |
-| `reportValidity()` | -- | Report validation to user, returns `boolean` |
+| `blur()` | — | Remove focus |
+| `checkValidity()` | — | Check validation, returns `boolean` |
+| `reportValidity()` | — | Report validation to user, returns `boolean` |
 | `setCustomValidity()` | `message: string` | Set custom validation message |
 
 ## Events
@@ -66,7 +64,7 @@ import 'snice/components/slider/snice-slider';
 | `track` | The slider track |
 | `fill` | The filled portion of the track |
 | `thumb` | The draggable thumb |
-| `spinner` | Loading spinner (when loading) |
+| `spinner` | Loading spinner |
 | `error-text` | Error message container |
 | `helper-text` | Helper text container |
 
@@ -84,53 +82,34 @@ import 'snice/components/slider/snice-slider';
 
 ### Variants
 
-Use the `variant` attribute to change the slider's color.
+Use `variant` to change the slider color.
 
 ```html
-<snice-slider variant="default" label="Default"></snice-slider>
 <snice-slider variant="primary" label="Primary"></snice-slider>
 <snice-slider variant="success" label="Success"></snice-slider>
-<snice-slider variant="warning" label="Warning"></snice-slider>
 <snice-slider variant="danger" label="Danger"></snice-slider>
 ```
 
 ### Sizes
 
-Use the `size` attribute to change the slider's size.
+Use `size` to change the slider size.
 
 ```html
 <snice-slider size="small" label="Small"></snice-slider>
-<snice-slider size="medium" label="Medium"></snice-slider>
 <snice-slider size="large" label="Large"></snice-slider>
 ```
 
-### Value Display
+### Value Display and Tick Marks
 
-Set the `show-value` attribute to display the current value.
-
-```html
-<snice-slider label="Brightness" min="0" max="100" value="75" show-value></snice-slider>
-```
-
-### Tick Marks
-
-Set the `show-ticks` attribute to display step indicators along the track.
+Set `show-value` and `show-ticks` to display additional visual information.
 
 ```html
 <snice-slider label="Rating" min="0" max="10" step="1" show-ticks show-value></snice-slider>
 ```
 
-### Custom Range and Step
-
-Use the `min`, `max`, and `step` attributes to define the slider range.
-
-```html
-<snice-slider label="Temperature" min="60" max="80" step="0.5" value="72" show-value></snice-slider>
-```
-
 ### Vertical
 
-Set the `vertical` attribute for a vertical orientation.
+Set `vertical` for vertical orientation.
 
 ```html
 <snice-slider label="Volume" min="0" max="100" value="60" vertical show-value></snice-slider>
@@ -138,30 +117,47 @@ Set the `vertical` attribute for a vertical orientation.
 
 ### Error State
 
-Set the `invalid` attribute with `error-text` to show validation errors.
+Set `invalid` with `error-text` to show validation errors.
 
 ```html
-<snice-slider label="Age" min="0" max="120" value="150" invalid error-text="Value must be between 0 and 120"></snice-slider>
+<snice-slider label="Age" invalid error-text="Value out of range"></snice-slider>
 ```
 
 ### Form Alignment
 
-When placing a slider alongside text inputs or selects in a form row, add the `form-align` attribute. This gives the slider track area the same height as a standard form field (40px), so the track vertically centers at the same level as adjacent input fields.
+Use the `form-align` attribute to align the slider with adjacent form fields.
 
 ```html
 <div style="display: flex; gap: 1rem; align-items: flex-start;">
-  <snice-input label="Price" placeholder="0.00"></snice-input>
-  <snice-slider label="Quantity" min="0" max="100" value="50" form-align></snice-slider>
+  <snice-input label="Price"></snice-input>
+  <snice-slider label="Quantity" min="0" max="100" form-align></snice-slider>
 </div>
 ```
 
-### In a Form
+### Form Integration
 
 The slider is form-associated and participates in form submission.
 
 ```html
-<form id="settings-form">
+<form>
   <snice-slider name="volume" label="Volume" min="0" max="100" value="50" required></snice-slider>
-  <button type="submit">Save Settings</button>
+  <button type="submit">Save</button>
 </form>
 ```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `ArrowLeft` / `ArrowDown` | Decrease by one step |
+| `ArrowRight` / `ArrowUp` | Increase by one step |
+| `Home` | Set to minimum |
+| `End` | Set to maximum |
+
+## Accessibility
+
+- Form-associated via `ElementInternals`
+- `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Focus ring on keyboard navigation
+- Supports mouse, touch, and keyboard input
+- Validation with `checkValidity()`, `reportValidity()`, and `setCustomValidity()`