snice 4.8.0 → 4.10.0

package/docs/components/skeleton.md

@@ -0,0 +1,96 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/skeleton.md instead)
+
+# Skeleton
+`<snice-skeleton>`
+
+Displays placeholder loading animations to indicate content is being loaded.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/skeleton/snice-skeleton';
+```
+
+```html
+<snice-skeleton></snice-skeleton>
+```
+
+## Importing
+
+**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>
+```
+
+## Examples
+
+### Variants
+
+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>
+```
+
+### Paragraph
+
+Set the `count` attribute 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.
+
+```html
+<snice-skeleton animation="wave"></snice-skeleton>
+<snice-skeleton animation="pulse"></snice-skeleton>
+<snice-skeleton animation="none"></snice-skeleton>
+```
+
+### Spacing
+
+Use the `spacing` attribute to control the gap between multiple skeleton lines.
+
+```html
+<snice-skeleton variant="text" count="3" spacing="12px"></snice-skeleton>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'text' \| 'circular' \| 'rectangular' \| 'rounded'` | `'text'` | Shape of the skeleton |
+| `width` | `string` | `''` | Custom width (CSS value) |
+| `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 |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--skeleton-bg` | Background color | `var(--snice-color-background-tertiary)` |
+| `--skeleton-highlight` | Wave highlight color | `var(--snice-color-background-secondary)` |
+| `--skeleton-duration` | Animation duration | `1.5s` |

package/docs/components/slider.md

@@ -1,297 +1,154 @@
-# Slider Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/slider.md instead)
 
-The `<snice-slider>` component provides an interactive range slider for selecting numeric values with mouse, touch, and keyboard support.
+# Slider
+`<snice-slider>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Keyboard Navigation](#keyboard-navigation)
-- [Features](#features)
-- [Examples](#examples)
+An interactive range slider for selecting numeric values with mouse, touch, and keyboard support.
 
 ## Basic Usage
 
-```html
-<snice-slider
-  label="Volume"
-  min="0"
-  max="100"
-  value="50"
-  show-value
-></snice-slider>
-```
-
 ```typescript
 import 'snice/components/slider/snice-slider';
-
-const slider = document.querySelector('snice-slider');
-slider.addEventListener('slider-change', (e) => {
-  console.log('Value:', e.detail.value);
-});
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `value` | `number` | `0` | Current slider value |
-| `min` | `number` | `0` | Minimum value |
-| `max` | `number` | `100` | Maximum value |
-| `step` | `number` | `1` | Step increment |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
-| `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant |
-| `label` | `string` | `''` | Label text |
-| `helperText` | `string` | `''` | Helper text below slider |
-| `errorText` | `string` | `''` | Error message (shown when invalid) |
-| `disabled` | `boolean` | `false` | Whether slider is disabled |
-| `readonly` | `boolean` | `false` | Whether slider is readonly |
-| `required` | `boolean` | `false` | Whether slider is required |
-| `invalid` | `boolean` | `false` | Whether to show invalid state |
-| `name` | `string` | `''` | Form field name |
-| `showValue` | `boolean` | `false` | Display current value |
-| `showTicks` | `boolean` | `false` | Show tick marks |
-| `vertical` | `boolean` | `false` | Vertical orientation |
-
-## Methods
-
-### `focus(): void`
-Give focus to the slider thumb.
-
-```typescript
-slider.focus();
 ```
 
-### `blur(): void`
-Remove focus from the slider thumb.
-
-```typescript
-slider.blur();
-```
-
-### `checkValidity(): boolean`
-Check if the slider passes validation.
-
-```typescript
-const isValid = slider.checkValidity();
+```html
+<snice-slider label="Volume" min="0" max="100" value="50"></snice-slider>
 ```
 
-### `reportValidity(): boolean`
-Report validation status to the user.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-slider.reportValidity();
+import 'snice/components/slider/snice-slider';
 ```
 
-### `setCustomValidity(message: string): void`
-Set a custom validation message.
-
-```typescript
-slider.setCustomValidity('Value must be between 10 and 90');
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-slider.min.js"></script>
 ```
 
-## Events
-
-### `slider-input`
-Fired continuously while dragging the slider.
-
-**Detail**: `{ value: number, slider: SniceSliderElement }`
-
-```typescript
-slider.addEventListener('slider-input', (e) => {
-  console.log('Current value:', e.detail.value);
-});
-```
+## Examples
 
-### `slider-change`
-Fired when the slider value is committed (after drag ends or keyboard input).
+### Variants
 
-**Detail**: `{ value: number, slider: SniceSliderElement }`
+Use the `variant` attribute to change the slider's color.
 
-```typescript
-slider.addEventListener('slider-change', (e) => {
-  console.log('Final value:', e.detail.value);
-});
+```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>
 ```
 
-## Keyboard Navigation
-
-The slider supports full keyboard navigation:
-
-| Key | Action |
-|-----|--------|
-| `←` / `↓` | Decrease by step |
-| `→` / `↑` | Increase by step |
-| `Home` | Jump to minimum |
-| `End` | Jump to maximum |
-| `Page Down` | Decrease by 10× step |
-| `Page Up` | Increase by 10× step |
-
-## Features
-
-- **Input Devices**: Full mouse, touch, and keyboard support
-- **Form Integration**: Form-associated custom element with validation
-- **Visual Variants**: Five color options (default, primary, success, warning, danger)
-- **Orientations**: Horizontal (default) or vertical layout
-- **Value Display**: Optional current value indicator
-- **Tick Marks**: Optional visual step indicators
-- **Step Control**: Configure increment size
-- **Accessibility**: Full ARIA support with keyboard navigation
-
-## Examples
+### Sizes
 
-### Basic Slider
+Use the `size` attribute to change the slider's size.
 
 ```html
-<snice-slider
-  label="Volume"
-  min="0"
-  max="100"
-  value="50"
-></snice-slider>
+<snice-slider size="small" label="Small"></snice-slider>
+<snice-slider size="medium" label="Medium"></snice-slider>
+<snice-slider size="large" label="Large"></snice-slider>
 ```
 
-### With Value Display
-
-```html
-<snice-slider
-  label="Brightness"
-  min="0"
-  max="100"
-  value="75"
-  show-value
-></snice-slider>
-```
+### Value Display
 
-### With Tick Marks
+Set the `show-value` attribute to display the current value.
 
 ```html
-<snice-slider
-  label="Rating"
-  min="0"
-  max="10"
-  step="1"
-  show-ticks
-  show-value
-></snice-slider>
+<snice-slider label="Brightness" min="0" max="100" value="75" show-value></snice-slider>
 ```
 
-### Different Variants
-
-```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>
-```
+### Tick Marks
 
-### Different Sizes
+Set the `show-ticks` attribute to display step indicators along the track.
 
 ```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>
+<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
-<!-- Temperature: 60-80°F in 0.5° increments -->
-<snice-slider
-  label="Temperature"
-  min="60"
-  max="80"
-  step="0.5"
-  value="72"
-  show-value
-></snice-slider>
-
-<!-- Percentage: 0-100 in 5% increments -->
-<snice-slider
-  label="Discount"
-  min="0"
-  max="100"
-  step="5"
-  value="20"
-  show-value
-  show-ticks
-></snice-slider>
+<snice-slider label="Temperature" min="60" max="80" step="0.5" value="72" show-value></snice-slider>
 ```
 
-### Vertical Slider
+### Vertical
+
+Set the `vertical` attribute for a vertical orientation.
 
 ```html
-<snice-slider
-  label="Volume"
-  min="0"
-  max="100"
-  value="60"
-  vertical
-  show-value
-></snice-slider>
+<snice-slider label="Volume" min="0" max="100" value="60" vertical show-value></snice-slider>
 ```
 
 ### Error State
 
+Set the `invalid` attribute 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" min="0" max="120" value="150" invalid error-text="Value must be between 0 and 120"></snice-slider>
 ```
 
 ### In a Form
 
+The slider is form-associated and participates in form submission.
+
 ```html
 <form id="settings-form">
-  <snice-slider
-    name="volume"
-    label="Volume"
-    min="0"
-    max="100"
-    value="50"
-    required
-  ></snice-slider>
-
-  <snice-slider
-    name="brightness"
-    label="Brightness"
-    min="0"
-    max="100"
-    value="75"
-  ></snice-slider>
-
+  <snice-slider name="volume" label="Volume" min="0" max="100" value="50" required></snice-slider>
   <button type="submit">Save Settings</button>
 </form>
-
-<script>
-document.getElementById('settings-form').addEventListener('submit', (e) => {
-  e.preventDefault();
-  const formData = new FormData(e.target);
-  console.log('Volume:', formData.get('volume'));
-  console.log('Brightness:', formData.get('brightness'));
-});
-</script>
 ```
 
-### Real-time Value Display
+## Properties
 
-```html
-<snice-slider id="volume-slider" min="0" max="100" value="50"></snice-slider>
-<div id="volume-display">Volume: 50</div>
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `number` | `0` | Current slider value |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Color variant |
+| `label` | `string` | `''` | Label text |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text below slider |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Disables the slider |
+| `readonly` | `boolean` | `false` | Makes the slider read-only |
+| `required` | `boolean` | `false` | Makes the slider required |
+| `invalid` | `boolean` | `false` | Shows invalid state |
+| `name` | `string` | `''` | Form field name |
+| `showValue` (attr: `show-value`) | `boolean` | `false` | Display current value |
+| `showTicks` (attr: `show-ticks`) | `boolean` | `false` | Show tick marks |
+| `vertical` | `boolean` | `false` | Vertical orientation |
 
-<script>
-const slider = document.getElementById('volume-slider');
-const display = document.getElementById('volume-display');
+## Events
 
-slider.addEventListener('slider-input', (e) => {
-  display.textContent = `Volume: ${e.detail.value}`;
-});
-</script>
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `slider-input` | `{ value: number, slider: SniceSliderElement }` | Fired continuously while dragging |
+| `slider-change` | `{ value: number, slider: SniceSliderElement }` | Fired when value is committed |
+
+## 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` |
+| `setCustomValidity()` | `message: string` | Set custom validation message |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `track` | The slider track |
+| `fill` | The filled portion of the track |
+| `thumb` | The draggable thumb |
+| `spinner` | Loading spinner (when loading) |
+| `error-text` | Error message container |
+| `helper-text` | Helper text container |