snice 4.8.0 → 4.10.0

package/docs/components/sortable.md

@@ -0,0 +1,267 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/sortable.md instead)
+
+# Sortable Component
+
+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.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Classes on Items](#css-classes-on-items)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-sortable>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</snice-sortable>
+```
+
+```typescript
+import 'snice/components/sortable/snice-sortable';
+```
+
+## Properties
+
+| 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. |
+| `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. |
+
+## Slots
+
+| Slot Name | Description |
+|-----------|-------------|
+| (default) | The child elements to be sortable. Each direct child becomes a draggable item. |
+
+## 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
+}
+```
+
+## 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)` |
+
+## 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) |
+
+## Examples
+
+### Vertical Sortable List
+
+```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.
+
+```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.
+
+```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>
+    <span>Review pull request</span>
+  </div>
+  <div class="task-item">
+    <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.
+
+```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>
+
+<script type="module">
+  import 'snice/components/sortable/snice-sortable';
+
+  const sortable = document.getElementById('priority-list');
+
+  sortable.addEventListener('sort-change', (e) => {
+    console.log(`Moved from index ${e.detail.oldIndex} to ${e.detail.newIndex}`);
+  });
+
+  sortable.addEventListener('sort-start', (e) => {
+    console.log(`Started dragging item at index ${e.detail.index}`);
+  });
+
+  sortable.addEventListener('sort-end', (e) => {
+    console.log(`Dropped item at index ${e.detail.newIndex}`);
+  });
+</script>
+```
+
+### Disabled State
+
+Use the `disabled` attribute to prevent reordering.
+
+```html
+<snice-sortable disabled>
+  <div>Locked item 1</div>
+  <div>Locked item 2</div>
+  <div>Locked item 3</div>
+</snice-sortable>
+```
+
+## 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
+
+## Best Practices
+
+1. **Use drag handles for complex items**: When items contain interactive elements (buttons, links), use a `handle` to avoid accidental drags
+2. **Provide visual feedback**: Style `.sortable-dragging` and `.sortable-ghost` classes for clear drag state indication
+3. **Keep item count reasonable**: Very long sortable lists can be hard to reorder; consider pagination or virtual scrolling
+4. **Use groups for kanban-style layouts**: The `group` property enables cross-container drag-and-drop
+5. **Listen to `sort-change` for persistence**: Use the `sort-change` event (not `sort-end`) to persist order changes, since it only fires when the order actually changed

package/docs/components/sparkline.md

@@ -1,19 +1,16 @@
-# Sparkline Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/sparkline.md instead)
 
-A lightweight inline chart component for visualizing trends and patterns in compact spaces. Perfect for dashboards, tables, and data-dense interfaces.
+# Sparkline
+`<snice-sparkline>`
 
-## Features
-
-- **Multiple Chart Types**: line, bar, area
-- **Semantic Colors**: primary, success, warning, danger, muted
-- **Custom Colors**: Use any color with the `custom-color` attribute
-- **Smooth Curves**: Optional smooth bezier curve interpolation
-- **Customizable Size**: Configurable width and height
-- **Optional Enhancements**: Dots, area fill, custom stroke width
-- **Flexible Data Range**: Optional min/max values for scaling
+A lightweight inline chart for visualizing trends in compact spaces.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/sparkline/snice-sparkline';
+```
+
 ```html
 <snice-sparkline id="chart"></snice-sparkline>
 
@@ -22,272 +19,129 @@ A lightweight inline chart component for visualizing trends and patterns in comp
 </script>
 ```
 
-## Properties
+## Importing
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `data` | `number[]` | `[]` | Array of numeric values to visualize |
-| `type` | `SparklineType` | `'line'` | Chart type ('line', 'bar', 'area') |
-| `color` | `SparklineColor` | `'primary'` | Color variant ('primary', 'success', 'warning', 'danger', 'muted') |
-| `custom-color` | `string` | `undefined` | Custom color (overrides `color`) - any valid CSS color |
-| `width` | `number` | `100` | Chart width in pixels |
-| `height` | `number` | `30` | Chart height in pixels |
-| `strokeWidth` | `number` | `2` | Line/dot stroke width |
-| `showDots` | `boolean` | `false` | Show dots on data points (line charts) |
-| `showArea` | `boolean` | `false` | Show area fill (line charts) |
-| `smooth` | `boolean` | `false` | Use smooth bezier curves instead of sharp lines |
-| `min` | `number` | `undefined` | Minimum value for scaling (auto if not set) |
-| `max` | `number` | `undefined` | Maximum value for scaling (auto if not set) |
-
-## Chart Types
-
-### Line Chart
-```html
-<snice-sparkline type="line"></snice-sparkline>
+**ESM (bundler)**
+```typescript
+import 'snice/components/sparkline/snice-sparkline';
 ```
 
-### Bar Chart
+**CDN**
 ```html
-<snice-sparkline type="bar"></snice-sparkline>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-sparkline.min.js"></script>
 ```
 
-### Area Chart
+## Examples
+
+### Chart Types
+
+Use the `type` attribute to switch between chart styles.
+
 ```html
+<snice-sparkline type="line"></snice-sparkline>
+<snice-sparkline type="bar"></snice-sparkline>
 <snice-sparkline type="area"></snice-sparkline>
 ```
 
-## Colors
+### Colors
 
-### Primary
-```html
-<snice-sparkline color="primary"></snice-sparkline>
-```
+Use the `color` attribute for semantic color variants.
 
-### Success
 ```html
+<snice-sparkline color="primary"></snice-sparkline>
 <snice-sparkline color="success"></snice-sparkline>
-```
-
-### Warning
-```html
 <snice-sparkline color="warning"></snice-sparkline>
-```
-
-### Danger
-```html
 <snice-sparkline color="danger"></snice-sparkline>
-```
-
-### Muted
-```html
 <snice-sparkline color="muted"></snice-sparkline>
 ```
 
-## Customization
-
-### With Dots
-```html
-<snice-sparkline show-dots></snice-sparkline>
-```
+### Custom Color
 
-### With Area Fill
-```html
-<snice-sparkline show-area></snice-sparkline>
-```
+Use the `custom-color` attribute to apply any CSS color.
 
-### Custom Size
 ```html
-<snice-sparkline width="200" height="50"></snice-sparkline>
+<snice-sparkline custom-color="#9333ea"></snice-sparkline>
+<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
 ```
 
-### Thick Stroke
-```html
-<snice-sparkline stroke-width="3"></snice-sparkline>
-```
+### With Dots
 
-### Custom Scale
-```html
-<snice-sparkline min="0" max="100"></snice-sparkline>
-```
+Set the `show-dots` attribute to display data point markers on line charts.
 
-### Smooth Curves
 ```html
-<snice-sparkline smooth></snice-sparkline>
+<snice-sparkline show-dots></snice-sparkline>
 ```
 
-### Custom Colors
-```html
-<!-- Hex color -->
-<snice-sparkline custom-color="#9333ea"></snice-sparkline>
+### With Area Fill
 
-<!-- RGB color -->
-<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
+Set the `show-area` attribute to fill the area below the line.
 
-<!-- Any valid CSS color -->
-<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
+```html
+<snice-sparkline show-area></snice-sparkline>
 ```
 
-## CSS Parts
-
-Use `::part()` to style internal elements:
-
-```css
-snice-sparkline::part(container) {
-  padding: 4px;
-}
-
-snice-sparkline::part(svg) {
-  filter: drop-shadow(0 2px 4px rgba(0,0,0,0.1));
-}
-
-snice-sparkline::part(line) {
-  stroke-dasharray: 4;
-}
-
-snice-sparkline::part(bar) {
-  rx: 2;
-}
+### Smooth Curves
 
-snice-sparkline::part(area) {
-  opacity: 0.3;
-}
+Set the `smooth` attribute for bezier curve interpolation.
 
-snice-sparkline::part(dot) {
-  fill: white;
-}
+```html
+<snice-sparkline smooth></snice-sparkline>
 ```
 
-## Theming
-
-The component uses these CSS custom properties:
+### Custom Size
 
-```css
---snice-color-primary
---snice-color-success
---snice-color-warning
---snice-color-danger
---snice-color-text-secondary
-```
+Use the `width` and `height` attributes to set pixel dimensions.
 
-## Examples
-
-### Website Traffic Trend
 ```html
-<div>
-  <label>Daily Visitors</label>
-  <snice-sparkline
-    id="traffic"
-    color="primary"
-    width="150"
-    height="40"
-    show-area>
-  </snice-sparkline>
-</div>
-
-<script>
-  document.getElementById('traffic').data = [
-    1200, 1350, 1100, 1450, 1600, 1550, 1700,
-    1800, 1650, 1900, 2100, 2000, 2200, 2400
-  ];
-</script>
+<snice-sparkline width="200" height="50"></snice-sparkline>
 ```
 
-### Sales Performance
-```html
-<div>
-  <label>Weekly Sales</label>
-  <snice-sparkline
-    id="sales"
-    type="bar"
-    color="success"
-    width="150"
-    height="40">
-  </snice-sparkline>
-</div>
+### Custom Scale
 
-<script>
-  document.getElementById('sales').data = [45, 52, 48, 61, 55, 70, 68];
-</script>
-```
+Use `min` and `max` to set fixed data bounds for consistent comparison.
 
-### Server Response Time
 ```html
-<div>
-  <label>Response Time (ms)</label>
-  <snice-sparkline
-    id="response"
-    color="warning"
-    width="150"
-    height="40"
-    show-dots>
-  </snice-sparkline>
-</div>
-
-<script>
-  document.getElementById('response').data = [
-    120, 135, 115, 145, 160, 155, 140, 130, 125, 120
-  ];
-</script>
+<snice-sparkline min="0" max="100"></snice-sparkline>
 ```
 
-### Error Rate
+### Dashboard Trend
+
 ```html
 <div>
-  <label>Error Rate</label>
-  <snice-sparkline
-    id="errors"
-    type="area"
-    color="danger"
-    width="150"
-    height="40"
-    min="0">
-  </snice-sparkline>
+  <label>Daily Visitors</label>
+  <snice-sparkline id="traffic" color="primary" width="150" height="40" show-area></snice-sparkline>
 </div>
 
 <script>
-  document.getElementById('errors').data = [
-    5, 3, 7, 12, 8, 15, 25, 20, 18, 22, 15, 10, 5, 3, 1, 0
-  ];
-</script>
-```
-
-### In Table Cells
-```html
-<table>
-  <tr>
-    <td>Product A</td>
-    <td><snice-sparkline id="product-a" width="80" height="25"></snice-sparkline></td>
-  </tr>
-  <tr>
-    <td>Product B</td>
-    <td><snice-sparkline id="product-b" width="80" height="25"></snice-sparkline></td>
-  </tr>
-</table>
-
-<script>
-  document.getElementById('product-a').data = [10, 12, 15, 14, 18, 22, 25];
-  document.getElementById('product-b').data = [30, 28, 25, 27, 24, 22, 20];
+  document.getElementById('traffic').data = [1200, 1350, 1100, 1450, 1600, 1550, 1700];
 </script>
 ```
 
-## Best Practices
-
-1. **Keep it Simple**: Sparklines are meant to show trends, not detailed analysis
-2. **Consistent Sizing**: Use the same dimensions for sparklines in a group
-3. **Appropriate Scale**: Set `min`/`max` when comparing multiple charts
-4. **Semantic Colors**: Use colors that match the data meaning (success=good, danger=bad)
-5. **Add Context**: Always label sparklines so users understand what they represent
-
-## Accessibility
+## Properties
 
-- Sparklines are decorative visualizations
-- Always provide text labels or tooltips for the data
-- Consider adding `aria-label` to describe the trend
-- Ensure sufficient color contrast for visibility
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `number[]` | `[]` | Array of numeric values to visualize |
+| `type` | `'line' \| 'bar' \| 'area'` | `'line'` | Chart type |
+| `color` | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'muted'` | `'primary'` | Color variant |
+| `customColor` (attr: `custom-color`) | `string` | `undefined` | Custom CSS color (overrides `color`) |
+| `width` | `number` | `100` | Chart width in pixels |
+| `height` | `number` | `30` | Chart height in pixels |
+| `strokeWidth` (attr: `stroke-width`) | `number` | `2` | Line stroke width |
+| `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) |
 
-## Performance
+## CSS Parts
 
-- Lightweight SVG rendering
-- No external dependencies
-- Efficiently handles data updates
-- Suitable for rendering many sparklines simultaneously
+| Part | Description |
+|------|-------------|
+| `container` | Outer container |
+| `svg` | SVG element |
+| `line` | Line path |
+| `area` | Area fill path |
+| `dot` | Data point dot |
+| `bar` | Bar rectangle |