snice 4.28.0 → 4.30.0

package/docs/components/sortable.md

@@ -1,18 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/sortable.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/sortable.md -->
 
-# Sortable Component
+# Sortable
 
-The sortable component provides a drag-and-drop container that allows users to reorder child elements. It supports vertical and horizontal layouts, drag handles, cross-container sorting via groups, and animated reordering with a ghost placeholder.
+A drag-and-drop container that allows users to reorder child elements. Supports vertical and horizontal layouts, drag handles, and cross-container sorting via groups.
 
 ## Table of Contents
+
 - [Properties](#properties)
 - [Events](#events)
 - [Slots](#slots)
-- [CSS Custom Properties](#css-custom-properties)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [CSS Classes on Items](#css-classes-on-items)
 - [Accessibility](#accessibility)
 
 ## Properties
@@ -20,78 +19,36 @@ The sortable component provides a drag-and-drop container that allows users to r
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `direction` | `'vertical' \| 'horizontal'` | `'vertical'` | Sort direction (layout axis) |
-| `handle` | `string` | `''` | CSS selector for the drag handle within each item. If empty, the entire item is draggable. |
+| `handle` | `string` | `''` | CSS selector for drag handle within each item. If empty, the entire item is draggable. |
 | `disabled` | `boolean` | `false` | Disable drag-and-drop |
-| `group` | `string` | `''` | Group name for cross-container sorting. Items can be dragged between sortable containers that share the same group name. |
+| `group` | `string` | `''` | Group name for cross-container sorting |
 
 ## Events
 
-#### `sort-start`
-Fired when a drag operation begins.
-
-**Event Detail:**
-```typescript
-{
-  index: number;       // Starting index of the dragged item
-  item: HTMLElement;   // The dragged element
-}
-```
-
-#### `sort-end`
-Fired when a drag operation ends (regardless of whether the order changed).
-
-**Event Detail:**
-```typescript
-{
-  oldIndex: number;    // Original index of the item
-  newIndex: number;    // New index of the item
-  item: HTMLElement;   // The dragged element
-}
-```
-
-#### `sort-change`
-Fired when the order of items actually changes (item dropped in a new position).
-
-**Event Detail:**
-```typescript
-{
-  oldIndex: number;    // Original index of the item
-  newIndex: number;    // New index of the item
-  item: HTMLElement;   // The dragged element
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `sort-start` | `{ index: number, item: HTMLElement }` | Drag operation began |
+| `sort-end` | `{ oldIndex: number, newIndex: number, item: HTMLElement }` | Drag operation ended (regardless of change) |
+| `sort-change` | `{ oldIndex: number, newIndex: number, item: HTMLElement }` | Item dropped in a new position |
 
 ## Slots
 
-| Slot Name | Description |
-|-----------|-------------|
-| (default) | The child elements to be sortable. Each direct child becomes a draggable item. |
-
-## CSS Custom Properties
-
-| Property | Description | Default |
-|----------|-------------|---------|
-| `--snice-spacing-xs` | Gap between items | `0.5rem` |
-| `--snice-transition-fast` | Drag transition speed | `150ms` |
-| `--snice-color-primary` | Ghost placeholder outline color | `rgb(37 99 235)` |
+| Name | Description |
+|------|-------------|
+| (default) | Child elements to be sortable. Each direct child becomes a draggable item. |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
+| Part | Description |
+|------|-------------|
+| `base` | The outer sortable container |
 
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer sortable container |
+## Basic Usage
 
-```css
-snice-sortable::part(base) {
-  gap: 0.5rem;
-  padding: 0.5rem;
-}
+```typescript
+import 'snice/components/sortable/snice-sortable';
 ```
 
-## Basic Usage
-
 ```html
 <snice-sortable>
   <div>Item 1</div>
@@ -100,61 +57,25 @@ snice-sortable::part(base) {
 </snice-sortable>
 ```
 
-```typescript
-import 'snice/components/sortable/snice-sortable';
-```
-
 ## Examples
 
-### Vertical Sortable List
+### Horizontal
 
-```html
-<snice-sortable>
-  <div>Apples</div>
-  <div>Bananas</div>
-  <div>Cherries</div>
-  <div>Dates</div>
-</snice-sortable>
-```
-
-### Horizontal Sortable List
-
-Use `direction="horizontal"` to arrange items in a row.
+Use `direction="horizontal"` for row layout.
 
 ```html
 <snice-sortable direction="horizontal">
   <div>Tab 1</div>
   <div>Tab 2</div>
   <div>Tab 3</div>
-  <div>Tab 4</div>
 </snice-sortable>
 ```
 
 ### Drag Handle
 
-Use the `handle` attribute to restrict dragging to a specific element within each item.
+Use the `handle` attribute to restrict dragging to a specific element.
 
 ```html
-<style>
-  .task-item {
-    display: flex;
-    align-items: center;
-    gap: 0.75rem;
-    padding: 0.75rem;
-    background: white;
-    border: 1px solid #e2e2e2;
-    border-radius: 0.25rem;
-  }
-  .drag-handle {
-    cursor: grab;
-    color: #999;
-    user-select: none;
-  }
-  .drag-handle:active {
-    cursor: grabbing;
-  }
-</style>
-
 <snice-sortable handle=".drag-handle">
   <div class="task-item">
     <span class="drag-handle">&#9776;</span>
@@ -164,112 +85,48 @@ Use the `handle` attribute to restrict dragging to a specific element within eac
     <span class="drag-handle">&#9776;</span>
     <span>Update documentation</span>
   </div>
-  <div class="task-item">
-    <span class="drag-handle">&#9776;</span>
-    <span>Fix login bug</span>
-  </div>
 </snice-sortable>
 ```
 
 ### Cross-Container Sorting
 
-Use the `group` attribute to allow dragging items between multiple sortable containers.
+Use the `group` attribute to drag items between containers.
 
 ```html
-<style>
-  .columns {
-    display: flex;
-    gap: 1rem;
-  }
-  .column {
-    flex: 1;
-  }
-  .column h3 {
-    margin-bottom: 0.5rem;
-  }
-  .card {
-    padding: 0.75rem;
-    background: white;
-    border: 1px solid #e2e2e2;
-    border-radius: 0.25rem;
-  }
-</style>
-
-<div class="columns">
-  <div class="column">
-    <h3>To Do</h3>
-    <snice-sortable group="tasks">
-      <div class="card">Design mockups</div>
-      <div class="card">Write tests</div>
-    </snice-sortable>
-  </div>
-  <div class="column">
-    <h3>In Progress</h3>
-    <snice-sortable group="tasks">
-      <div class="card">Implement API</div>
-    </snice-sortable>
-  </div>
-  <div class="column">
-    <h3>Done</h3>
-    <snice-sortable group="tasks">
-      <div class="card">Setup project</div>
-    </snice-sortable>
-  </div>
-</div>
-```
-
-### Listening for Order Changes
-
-```html
-<snice-sortable id="priority-list">
-  <div>High priority</div>
-  <div>Medium priority</div>
-  <div>Low priority</div>
+<snice-sortable group="tasks">
+  <div>Design mockups</div>
+  <div>Write tests</div>
 </snice-sortable>
 
-<script type="module">
-  import 'snice/components/sortable/snice-sortable';
-
-  const sortable = document.getElementById('priority-list');
+<snice-sortable group="tasks">
+  <div>Implement API</div>
+</snice-sortable>
+```
 
-  sortable.addEventListener('sort-change', (e) => {
-    console.log(`Moved from index ${e.detail.oldIndex} to ${e.detail.newIndex}`);
-  });
+### Event Handling
 
-  sortable.addEventListener('sort-start', (e) => {
-    console.log(`Started dragging item at index ${e.detail.index}`);
-  });
+Listen for `sort-change` to track reorder operations.
 
-  sortable.addEventListener('sort-end', (e) => {
-    console.log(`Dropped item at index ${e.detail.newIndex}`);
-  });
-</script>
+```typescript
+sortable.addEventListener('sort-change', (e) => {
+  console.log(`Moved from index ${e.detail.oldIndex} to ${e.detail.newIndex}`);
+});
 ```
 
-### Disabled State
+### Disabled
 
-Use the `disabled` attribute to prevent reordering.
+Set `disabled` to prevent reordering.
 
 ```html
 <snice-sortable disabled>
   <div>Locked item 1</div>
   <div>Locked item 2</div>
-  <div>Locked item 3</div>
 </snice-sortable>
 ```
 
-## CSS Classes on Items
-
-The component automatically adds CSS classes to items during drag operations:
-
-| Class | Description |
-|-------|-------------|
-| `.sortable-dragging` | Applied to the item being dragged (opacity: 0.4) |
-| `.sortable-ghost` | Applied to the placeholder element (dashed outline) |
-
 ## Accessibility
 
-- **Drag operation**: Items receive `draggable="true"` automatically
-- **Ghost placeholder**: A dashed-outline placeholder shows where the item will be dropped
-- **Visual feedback**: The dragged item has reduced opacity (0.4) during drag
-- **Disabled state**: When `disabled` is set, items are not draggable
+- Items receive `draggable="true"` automatically
+- Ghost placeholder with dashed outline shows drop position
+- Dragged item has reduced opacity (0.4)
+- `.sortable-dragging` class on dragged item, `.sortable-ghost` on placeholder

package/docs/components/sparkline.md

@@ -1,22 +1,16 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/sparkline.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/sparkline.md -->
 
 # Sparkline
-`<snice-sparkline>`
 
-A lightweight inline chart for visualizing trends in compact spaces.
+A lightweight inline chart for visualizing trends and patterns in compact spaces. Supports line, bar, and area chart types.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/sparkline/snice-sparkline';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-sparkline.min.js"></script>
-```
+- [Properties](#properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -32,19 +26,19 @@ import 'snice/components/sparkline/snice-sparkline';
 | `showDots` (attr: `show-dots`) | `boolean` | `false` | Show dots on data points |
 | `showArea` (attr: `show-area`) | `boolean` | `false` | Show area fill below line |
 | `smooth` | `boolean` | `false` | Use smooth bezier curves |
-| `min` | `number` | `undefined` | Minimum scale value (auto if unset) |
-| `max` | `number` | `undefined` | Maximum scale value (auto if unset) |
+| `min` | `number` | `undefined` | Minimum scale value (auto-calculated if unset) |
+| `max` | `number` | `undefined` | Maximum scale value (auto-calculated if unset) |
 
 ## CSS Parts
 
 | Part | Description |
 |------|-------------|
-| `container` | Outer container |
-| `svg` | SVG element |
-| `line` | Line path |
-| `area` | Area fill path |
-| `dot` | Data point dot |
-| `bar` | Bar rectangle |
+| `container` | Outer container element |
+| `svg` | The SVG element |
+| `line` | Line path element |
+| `area` | Area fill path element |
+| `dot` | Data point dot circle |
+| `bar` | Bar rectangle element |
 
 ## Basic Usage
 
@@ -86,7 +80,7 @@ Use the `color` attribute for semantic color variants.
 
 ### Custom Color
 
-Use the `custom-color` attribute to apply any CSS color.
+Use the `custom-color` attribute to apply any CSS color, overriding the `color` variant.
 
 ```html
 <snice-sparkline custom-color="#9333ea"></snice-sparkline>
@@ -127,7 +121,7 @@ Use the `width` and `height` attributes to set pixel dimensions.
 
 ### Custom Scale
 
-Use `min` and `max` to set fixed data bounds for consistent comparison.
+Use `min` and `max` to set fixed data bounds for consistent comparison across multiple charts.
 
 ```html
 <snice-sparkline min="0" max="100"></snice-sparkline>
@@ -135,13 +129,20 @@ Use `min` and `max` to set fixed data bounds for consistent comparison.
 
 ### Dashboard Trend
 
+Combine options for a compact dashboard widget.
+
 ```html
 <div>
   <label>Daily Visitors</label>
-  <snice-sparkline id="traffic" color="primary" width="150" height="40" show-area></snice-sparkline>
+  <snice-sparkline id="traffic" color="primary" width="150" height="40" show-area smooth></snice-sparkline>
 </div>
 
 <script>
   document.getElementById('traffic').data = [1200, 1350, 1100, 1450, 1600, 1550, 1700];
 </script>
 ```
+
+## Accessibility
+
+- Decorative element; use `aria-busy="true"` on the container while data is loading
+- Set an `aria-label` on the element to describe the trend for screen readers

package/docs/components/spinner.md

@@ -1,22 +1,16 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/spinner.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/spinner.md -->
 
 # Spinner
-`<snice-spinner>`
 
-An animated loading indicator.
+An animated loading indicator with configurable size, color, and optional label.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/spinner/snice-spinner';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-spinner.min.js"></script>
-```
+- [Properties](#properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -24,29 +18,16 @@ import 'snice/components/spinner/snice-spinner';
 |----------|------|---------|-------------|
 | `size` | `'small' \| 'medium' \| 'large' \| 'xl'` | `'medium'` | Spinner size |
 | `color` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Color variant |
-| `label` | `string` | `''` | Accessible label |
-| `thickness` | `number` | `4` | Stroke thickness |
+| `label` | `string` | `''` | Accessible label text displayed below the spinner |
+| `thickness` | `number` | `4` | Stroke thickness in pixels |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer spinner container |
-| `circle` | `<svg>` | The SVG spinner circle |
-| `label` | `<span>` | The label text element |
-
-```css
-snice-spinner::part(base) {
-  gap: 0.75rem;
-}
-
-snice-spinner::part(label) {
-  font-size: 0.875rem;
-  color: #64748b;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | The outer spinner container |
+| `circle` | The SVG spinner circle |
+| `label` | The label text element |
 
 ## Basic Usage
 
@@ -62,7 +43,7 @@ import 'snice/components/spinner/snice-spinner';
 
 ### Sizes
 
-Use the `size` attribute to change the spinner's size.
+Use the `size` attribute to change the spinner's dimensions.
 
 ```html
 <snice-spinner size="small"></snice-spinner>
@@ -85,15 +66,24 @@ Use the `color` attribute to change the spinner's color.
 
 ### With Label
 
-Set the `label` attribute for an accessible description.
+Set the `label` attribute to display descriptive text below the spinner.
 
 ```html
 <snice-spinner label="Loading data..."></snice-spinner>
 ```
 
+### Custom Thickness
+
+Use the `thickness` attribute to adjust the stroke width.
+
+```html
+<snice-spinner thickness="2"></snice-spinner>
+<snice-spinner thickness="6"></snice-spinner>
+```
+
 ### Inline
 
-Use a small spinner inline with text.
+Use a small spinner inline with text for button loading states.
 
 ```html
 <button disabled>
@@ -101,3 +91,8 @@ Use a small spinner inline with text.
   Processing...
 </button>
 ```
+
+## Accessibility
+
+- Uses `role="status"` with `aria-label` for screen readers
+- The `label` property provides visible and accessible descriptive text

package/docs/components/split-button.md

@@ -1,44 +1,50 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/split-button.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/split-button.md -->
 
 # Split Button
-`<snice-split-button>`
 
-A primary action button with a dropdown menu of alternative actions. Click the main button for the primary action, or click the chevron dropdown for alternatives.
+A primary action button with a dropdown menu of alternative actions. Click the main button for the primary action, or click the chevron to reveal alternatives.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/split-button/snice-split-button';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-split-button.min.js"></script>
-```
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `label` | `string` | `''` | Primary button text |
-| `actions` | `SplitButtonAction[]` | `[]` | Array of `{ label, value, icon?, disabled? }` for dropdown |
+| `actions` | `SplitButtonAction[]` | `[]` | Array of `{ label, value, icon?, disabled? }` for the dropdown menu |
 | `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Visual style |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
 | `disabled` | `boolean` | `false` | Disables the entire button |
 | `loading` | `boolean` | `false` | Shows loading spinner and disables button |
 | `outline` | `boolean` | `false` | Use outline style (transparent background) |
 | `pill` | `boolean` | `false` | Use pill (fully rounded) shape |
-| `icon` | `string` | `''` | Icon (URL, image file, emoji) |
+| `icon` | `string` | `''` | Icon (URL, image file, or emoji) |
 | `iconPlacement` (attr: `icon-placement`) | `'start' \| 'end'` | `'start'` | Icon position relative to label |
 
+The `actions` property is set via JavaScript (not HTML attributes):
+
+```typescript
+interface SplitButtonAction {
+  label: string;
+  value: string;
+  icon?: string;
+  disabled?: boolean;
+}
+```
+
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `primary-click` | `{ button }` | Primary button clicked |
-| `action-click` | `{ value, action, button }` | A dropdown action was selected |
+| `primary-click` | `{ button: SniceSplitButtonElement }` | Primary button was clicked |
+| `action-click` | `{ value: string, action: SplitButtonAction, button: SniceSplitButtonElement }` | A dropdown action was selected |
 
 ## CSS Parts
 
@@ -46,11 +52,11 @@ import 'snice/components/split-button/snice-split-button';
 |------|-------------|
 | `base` | The button container |
 | `primary` | The primary button |
-| `divider` | The divider between buttons |
-| `toggle` | The dropdown toggle button |
+| `divider` | The divider between primary and toggle buttons |
+| `toggle` | The dropdown toggle button (chevron) |
 | `menu` | The dropdown menu container |
 | `menu-items` | The menu items wrapper |
-| `action` | Each menu action button |
+| `action` | Each individual menu action button |
 
 ## Basic Usage
 
@@ -63,6 +69,7 @@ import 'snice/components/split-button/snice-split-button';
 ```
 
 ```typescript
+const btn = document.querySelector('snice-split-button');
 btn.actions = [
   { value: 'save-draft', label: 'Save as Draft' },
   { value: 'save-template', label: 'Save as Template' },
@@ -92,9 +99,16 @@ Use the `size` attribute to change the button size.
 <snice-split-button label="Large" size="large"></snice-split-button>
 ```
 
+### Outline and Pill
+
+```html
+<snice-split-button label="Outline" variant="primary" outline></snice-split-button>
+<snice-split-button label="Pill" variant="primary" pill></snice-split-button>
+```
+
 ### Disabled
 
-Disable both the primary button and dropdown with the `disabled` attribute.
+Disable both the primary button and dropdown.
 
 ```html
 <snice-split-button label="Disabled" disabled></snice-split-button>
@@ -102,7 +116,7 @@ Disable both the primary button and dropdown with the `disabled` attribute.
 
 ### Disabled Actions
 
-Individual actions can be disabled.
+Individual dropdown actions can be disabled.
 
 ```typescript
 btn.actions = [
@@ -134,3 +148,9 @@ btn.addEventListener('action-click', (e) => {
   console.log('Action object:', e.detail.action);
 });
 ```
+
+## Accessibility
+
+- Dropdown menu closes on action click, outside click, or Escape key
+- Actions are set via the `actions` JavaScript property (not child elements)
+- Loading state disables the button and shows a spinner