snice 4.8.0 → 4.10.0

package/docs/ai/components/rating.md

@@ -0,0 +1,56 @@
+# snice-rating
+
+Star rating input with full/half precision, custom icons, and keyboard navigation.
+
+## Properties
+
+```ts
+value: number                            // Current rating value (default: 0)
+max: number                              // Maximum stars (default: 5)
+icon: string                             // Star character (default: '\u2605')
+size: 'small' | 'medium' | 'large'      // Display size (default: 'medium')
+readonly: boolean                        // Disable interaction (default: false)
+precision: 'full' | 'half'              // Click precision (default: 'full')
+```
+
+## Events
+
+- `rating-change` -> `{ value: number }` -- Rating value changed
+
+## Keyboard
+
+- `ArrowRight` / `ArrowUp` -- Increase value
+- `ArrowLeft` / `ArrowDown` -- Decrease value
+- Step size: 1 (full) or 0.5 (half precision)
+
+## CSS Custom Properties
+
+```css
+--rating-color             /* Filled star color (default: --snice-color-warning) */
+--rating-color-empty       /* Empty star color (default: --snice-color-border) */
+--rating-size              /* Star size: small=1rem, medium=1.5rem, large=2rem */
+--snice-font-family
+--snice-transition-fast
+--snice-focus-ring-width
+--snice-focus-ring-color
+--snice-focus-ring-offset
+```
+
+## Accessibility
+
+Uses `role="radiogroup"` with individual `role="radio"` stars. Keyboard accessible when not readonly.
+
+## Usage
+
+```html
+<snice-rating value="3.5" max="5" precision="half" size="large"></snice-rating>
+<snice-rating value="4" readonly></snice-rating>
+<snice-rating icon="&#x2764;" max="10"></snice-rating>
+```
+
+```js
+const rating = document.querySelector('snice-rating');
+rating.addEventListener('rating-change', (e) => {
+  console.log('New rating:', e.detail.value);
+});
+```

package/docs/ai/components/recipe.md

@@ -0,0 +1,90 @@
+# snice-recipe
+
+Interactive recipe card with ingredient scaling, step-by-step mode, per-step timers, and nutrition facts.
+
+## Properties
+
+```ts
+title: string                            // Recipe title
+description: string                      // Short description
+image: string                            // Hero image URL
+author: string                           // Author name
+prepTime: number                         // Prep time in minutes (attr: prep-time)
+cookTime: number                         // Cook time in minutes (attr: cook-time)
+servings: number                         // Base serving count (default: 4)
+difficulty: 'easy' | 'medium' | 'hard'  // Difficulty level (default: 'medium')
+cuisine: string                          // Cuisine type (shown as tag)
+variant: 'card' | 'full'                // Display variant (default: 'full')
+ingredients: RecipeIngredient[]          // Ingredient list
+steps: RecipeStep[]                      // Instruction steps
+nutrition: RecipeNutrition | null        // Nutrition facts per serving
+tags: string[]                           // Recipe tags
+```
+
+### Types
+
+```ts
+interface RecipeIngredient {
+  name: string;
+  amount: number;
+  unit: string;
+  group?: string;                        // Group header for ingredient sections
+}
+
+interface RecipeStep {
+  text: string;
+  image?: string;                        // Step photo URL
+  tip?: string;                          // Pro tip text
+  time?: number;                         // Timer duration in minutes
+}
+
+interface RecipeNutrition {
+  calories: number;
+  protein: number;
+  carbs: number;
+  fat: number;
+  fiber?: number;
+  sodium?: number;                       // in mg
+}
+```
+
+## Methods
+
+- `setServings(count: number)` -- Adjust serving count (scales ingredients)
+- `print()` -- Print the recipe
+- `reset()` -- Reset checked ingredients, completed steps, timers, and servings
+
+## Events
+
+- `recipe-serving-change` -> `{ servings: number; previousServings: number }` -- Serving count changed
+- `recipe-step-complete` -> `{ stepIndex: number; completed: boolean }` -- Step toggled
+- `recipe-ingredient-check` -> `{ ingredientIndex: number; checked: boolean; ingredient: RecipeIngredient }` -- Ingredient checked/unchecked
+
+## CSS Parts
+
+`container`, `hero`, `header`, `meta`, `content`, `ingredients`, `steps`, `nutrition`, `controls`
+
+## Usage
+
+```js
+const recipe = document.querySelector('snice-recipe');
+recipe.title = 'Pasta Carbonara';
+recipe.prepTime = 10;
+recipe.cookTime = 20;
+recipe.servings = 4;
+recipe.difficulty = 'medium';
+recipe.cuisine = 'Italian';
+recipe.ingredients = [
+  { name: 'Spaghetti', amount: 400, unit: 'g' },
+  { name: 'Pancetta', amount: 200, unit: 'g' },
+  { name: 'Eggs', amount: 4, unit: '', group: 'Sauce' },
+  { name: 'Parmesan', amount: 100, unit: 'g', group: 'Sauce' }
+];
+recipe.steps = [
+  { text: 'Boil pasta in salted water.', time: 10 },
+  { text: 'Fry pancetta until crispy.', tip: 'Use medium heat to render fat slowly.' },
+  { text: 'Mix eggs and parmesan.' },
+  { text: 'Combine all ingredients off heat.' }
+];
+recipe.nutrition = { calories: 650, protein: 28, carbs: 72, fat: 24 };
+```

package/docs/ai/components/sankey.md

@@ -0,0 +1,63 @@
+# snice-sankey
+
+SVG-based Sankey diagram for flow visualization between categories.
+
+## Properties
+
+```typescript
+data: SankeyData = { nodes: [], links: [] };
+nodeWidth: number = 20;
+nodePadding: number = 10;
+alignment: 'left'|'right'|'center'|'justify' = 'justify';
+showLabels: boolean = true;
+showValues: boolean = true;
+animation: boolean = false;
+```
+
+## Types
+
+```typescript
+interface SankeyData {
+  nodes: SankeyNode[];
+  links: SankeyLink[];
+}
+interface SankeyNode { id: string; label?: string; color?: string; }
+interface SankeyLink { source: string; target: string; value: number; color?: string; }
+```
+
+## Events
+
+- `@snice/sankey-node-click` - `{ node: SankeyNode }` - Node clicked
+- `@snice/sankey-link-click` - `{ link: SankeyLink }` - Link clicked
+- `@snice/sankey-hover` - `{ type: 'node'|'link', item: SankeyNode|SankeyLink } | null` - Hover change
+
+## Usage
+
+```html
+<snice-sankey id="my-sankey" show-labels show-values animation></snice-sankey>
+
+<script>
+  document.getElementById('my-sankey').data = {
+    nodes: [
+      { id: 'a', label: 'Source', color: '#2196f3' },
+      { id: 'b', label: 'Target', color: '#4caf50' }
+    ],
+    links: [
+      { source: 'a', target: 'b', value: 100 }
+    ]
+  };
+</script>
+```
+
+## Features
+
+- SVG rendering with curved bezier link paths
+- Sankey layout algorithm with iterative node relaxation
+- Link width proportional to flow value
+- Hover highlighting (dims non-connected nodes/links)
+- Tooltips on hover for nodes and links
+- Responsive sizing via ResizeObserver
+- Animation on initial render
+- 4 alignment modes
+- Custom node/link colors
+- Accessible: role="img" with aria-label

package/docs/ai/components/skeleton.md

@@ -47,11 +47,3 @@ spacing: string = '8px';
   </div>
 </div>
 ```
-
-## Features
-
-- 4 shape variants (text/circular/rectangular/rounded)
-- 3 animation styles (pulse/wave/none)
-- Custom dimensions
-- Multiple skeleton elements with spacing
-- Mimics loading content shapes

package/docs/ai/components/slider.md

@@ -1,6 +1,6 @@
 # snice-slider
 
-Range slider for numeric value selection.
+Range slider for numeric value selection. Form-associated.
 
 ## Properties
 
@@ -16,73 +16,33 @@ required: boolean = false;
 invalid: boolean = false;
 readonly: boolean = false;
 label: string = '';
-helperText: string = '';
-errorText: string = '';
+helperText: string = '';       // attr: helper-text
+errorText: string = '';        // attr: error-text
 name: string = '';
-showValue: boolean = false;
-showTicks: boolean = false;
+showValue: boolean = false;    // attr: show-value
+showTicks: boolean = false;    // attr: show-ticks
 vertical: boolean = false;
 loading: boolean = false;
 ```
 
+## Events
+
+- `slider-input` → `{ value, slider }` - During drag
+- `slider-change` → `{ value, slider }` - After drag complete
+
 ## Methods
 
 - `focus()` - Focus slider thumb
 - `blur()` - Blur slider thumb
 
-## Events
-
-- `slider-input` - {value, slider} - During drag
-- `slider-change` - {value, slider} - After drag complete
-
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-slider label="Volume" min="0" max="100"></snice-slider>
-
-<!-- With value display -->
 <snice-slider show-value value="50"></snice-slider>
-
-<!-- With ticks -->
 <snice-slider show-ticks min="0" max="10" step="1"></snice-slider>
-
-<!-- Variants -->
 <snice-slider variant="primary"></snice-slider>
-<snice-slider variant="success"></snice-slider>
-<snice-slider variant="warning"></snice-slider>
-<snice-slider variant="danger"></snice-slider>
-
-<!-- Sizes -->
 <snice-slider size="small"></snice-slider>
-<snice-slider size="medium"></snice-slider>
-<snice-slider size="large"></snice-slider>
-
-<!-- Vertical -->
 <snice-slider vertical></snice-slider>
-
-<!-- Step increments -->
 <snice-slider min="0" max="100" step="5" value="50"></snice-slider>
-
-<!-- Events -->
-<snice-slider id="slider"></snice-slider>
-<script>
-const slider = document.querySelector('#slider');
-slider.addEventListener('slider-change', (e) => {
-  console.log('Value:', e.detail.value);
-});
-</script>
 ```
-
-## Features
-
-- Form-associated custom element
-- Mouse and touch support
-- Keyboard navigation (arrows, home/end, page up/down)
-- 5 color variants
-- 3 sizes
-- Vertical orientation
-- Optional value display
-- Optional tick marks
-- Step increments
-- Accessible

package/docs/ai/components/sortable.md

@@ -0,0 +1,57 @@
+# snice-sortable
+
+Drag-and-drop sortable container for reordering child elements.
+
+## Properties
+
+```ts
+direction: 'vertical' | 'horizontal' = 'vertical'
+handle: string = ''           // CSS selector for drag handle within items
+disabled: boolean = false
+group: string = ''            // group name for cross-container sorting
+```
+
+## Slots
+
+- `default` - Items to be sortable (automatically set to `draggable`)
+
+## Events
+
+- `sort-start` -> `{ index: number; item: HTMLElement }`
+- `sort-end` -> `{ oldIndex: number; newIndex: number; item: HTMLElement }`
+- `sort-change` -> `{ oldIndex: number; newIndex: number; item: HTMLElement }`
+
+## CSS Custom Properties
+
+- `--snice-spacing-xs` - Gap between items (default: `0.5rem`)
+- `--snice-transition-fast` - Drag transition speed (default: `150ms`)
+- `--snice-color-primary` - Ghost outline color (default: `rgb(37 99 235)`)
+
+## CSS Classes on Items
+
+- `.sortable-dragging` - Added to item being dragged (opacity: 0.4)
+- `.sortable-ghost` - Dashed outline placeholder
+
+## Usage
+
+```html
+<!-- Vertical sortable list -->
+<snice-sortable>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</snice-sortable>
+
+<!-- Horizontal with drag handle -->
+<snice-sortable direction="horizontal" handle=".drag-handle">
+  <div><span class="drag-handle">&#9776;</span> Item A</div>
+  <div><span class="drag-handle">&#9776;</span> Item B</div>
+</snice-sortable>
+```
+
+```js
+const sortable = document.querySelector('snice-sortable');
+sortable.addEventListener('sort-change', (e) => {
+  console.log(`Moved from ${e.detail.oldIndex} to ${e.detail.newIndex}`);
+});
+```

package/docs/ai/components/sparkline.md

@@ -1,168 +1,42 @@
 # snice-sparkline
 
-Compact inline chart for visualizing trends and patterns. For dashboards, tables, data-dense interfaces.
+Compact inline chart for visualizing trends and patterns.
 
 ## Properties
 
 ```typescript
-data: number[] = []                     // Values to visualize
-type: SparklineType = 'line'            // 'line' | 'bar' | 'area'
-color: SparklineColor = 'primary'       // 'primary' | 'success' | 'warning' | 'danger' | 'muted'
-customColor?: string                    // Any CSS color (overrides 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
-min?: number                            // Min value for scaling (auto if unset)
-max?: number                            // Max value for scaling (auto if unset)
+data: number[] = [];
+type: 'line'|'bar'|'area' = 'line';
+color: 'primary'|'success'|'warning'|'danger'|'muted' = 'primary';
+customColor: string = '';          // attr: custom-color, overrides color
+width: number = 100;
+height: number = 30;
+strokeWidth: number = 2;          // attr: stroke-width
+showDots: boolean = false;        // attr: show-dots
+showArea: boolean = false;        // attr: show-area
+smooth: boolean = false;
+min?: number;
+max?: number;
 ```
 
+## CSS Parts
+
+- `container` - Container div
+- `svg` - SVG element
+- `line` - Line/path element
+- `area` - Area polygon/path
+- `bar` - Bar rect
+- `dot` - Dot circle
+
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-sparkline id="chart"></snice-sparkline>
-<script>
-  document.getElementById('chart').data = [10, 20, 15, 25, 30];
-</script>
-
-<!-- Line chart -->
-<snice-sparkline id="line" type="line"></snice-sparkline>
-
-<!-- Bar chart -->
-<snice-sparkline id="bar" type="bar"></snice-sparkline>
-
-<!-- Area chart -->
-<snice-sparkline id="area" type="area"></snice-sparkline>
-
-<!-- Smooth curves -->
-<snice-sparkline id="smooth" smooth></snice-sparkline>
-
-<!-- With dots -->
-<snice-sparkline id="dots" show-dots></snice-sparkline>
+<script>document.getElementById('chart').data = [10, 20, 15, 25, 30];</script>
 
-<!-- With area fill -->
-<snice-sparkline id="fill" show-area></snice-sparkline>
-
-<!-- Colors -->
-<snice-sparkline color="primary"></snice-sparkline>
-<snice-sparkline color="success"></snice-sparkline>
-<snice-sparkline color="warning"></snice-sparkline>
-<snice-sparkline color="danger"></snice-sparkline>
-<snice-sparkline color="muted"></snice-sparkline>
-
-<!-- Custom colors -->
+<snice-sparkline type="bar" color="success"></snice-sparkline>
+<snice-sparkline type="area" color="danger" min="0"></snice-sparkline>
+<snice-sparkline smooth show-area show-dots width="150" height="40"></snice-sparkline>
 <snice-sparkline custom-color="#9333ea"></snice-sparkline>
-<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
-<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
-
-<!-- Sizing -->
-<snice-sparkline width="200" height="50"></snice-sparkline>
-
-<!-- Custom scale -->
 <snice-sparkline min="0" max="100"></snice-sparkline>
-
-<!-- Combined features -->
-<snice-sparkline
-  id="advanced"
-  type="line"
-  color="primary"
-  width="150"
-  height="40"
-  smooth
-  show-area
-  min="0">
-</snice-sparkline>
-```
-
-## CSS Parts
-
-```css
-::part(container)  /* Container div */
-::part(svg)        /* SVG element */
-::part(line)       /* Line/path element */
-::part(area)       /* Area polygon/path */
-::part(bar)        /* Bar rect */
-::part(dot)        /* Dot circle */
-```
-
-## Styling
-
-```css
---snice-color-primary
---snice-color-success
---snice-color-warning
---snice-color-danger
---snice-color-text-secondary
-```
-
-## In Tables
-
-```html
-<snice-table id="table"></snice-table>
-<script>
-  document.getElementById('table').data = [
-    {
-      product: 'A',
-      trend: [10, 15, 12, 18, 22, 25]
-    }
-  ];
-
-  document.getElementById('table').columns = [
-    { key: 'product', label: 'Product' },
-    {
-      key: 'trend',
-      label: 'Trend',
-      render: (value) => {
-        const sparkline = document.createElement('snice-sparkline');
-        sparkline.data = value;
-        sparkline.width = 80;
-        sparkline.height = 25;
-        sparkline.color = 'primary';
-        return sparkline;
-      }
-    }
-  ];
-</script>
-```
-
-## Common Patterns
-
-```html
-<!-- Website traffic -->
-<snice-sparkline
-  id="traffic"
-  color="primary"
-  width="150"
-  height="40"
-  smooth
-  show-area>
-</snice-sparkline>
-
-<!-- Sales bars -->
-<snice-sparkline
-  id="sales"
-  type="bar"
-  color="success"
-  width="150"
-  height="40">
-</snice-sparkline>
-
-<!-- Response time with dots -->
-<snice-sparkline
-  id="response"
-  color="warning"
-  smooth
-  show-dots>
-</snice-sparkline>
-
-<!-- Error rate -->
-<snice-sparkline
-  id="errors"
-  type="area"
-  color="danger"
-  min="0">
-</snice-sparkline>
 ```

package/docs/ai/components/spinner.md

@@ -14,34 +14,13 @@ thickness: number = 4;
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-spinner></snice-spinner>
-
-<!-- Sizes -->
 <snice-spinner size="small"></snice-spinner>
-<snice-spinner size="medium"></snice-spinner>
 <snice-spinner size="large"></snice-spinner>
 <snice-spinner size="xl"></snice-spinner>
-
-<!-- Colors -->
-<snice-spinner color="primary"></snice-spinner>
 <snice-spinner color="success"></snice-spinner>
 <snice-spinner color="warning"></snice-spinner>
 <snice-spinner color="error"></snice-spinner>
-<snice-spinner color="info"></snice-spinner>
-
-<!-- With label -->
 <snice-spinner label="Loading..."></snice-spinner>
-
-<!-- Custom thickness -->
 <snice-spinner thickness="6"></snice-spinner>
 ```
-
-## Features
-
-- Smooth circular animation
-- 4 sizes
-- 5 color variants
-- Optional label
-- Accessible (role=status, aria-label)
-- Lightweight SVG-based

package/docs/ai/components/split-pane.md

@@ -6,25 +6,28 @@ Resizable split pane layout.
 
 ```typescript
 direction: 'horizontal'|'vertical' = 'horizontal';
-primarySize: number = 50; // percentage
-minPrimarySize: number = 10; // percentage
-minSecondarySize: number = 10; // percentage
-snapSize: number = 0; // percentage, 0 = no snap
+primarySize: number = 50;         // attr: primary-size, percentage
+minPrimarySize: number = 10;      // attr: min-primary-size, percentage
+minSecondarySize: number = 10;    // attr: min-secondary-size, percentage
+snapSize: number = 0;             // attr: snap-size, percentage, 0 = no snap
 disabled: boolean = false;
 ```
 
-## Methods
+## Slots
 
-```typescript
-getPrimarySize(): number
-getSecondarySize(): number
-setPrimarySize(size: number): void
-reset(): void
-```
+- `primary` - Primary pane content
+- `secondary` - Secondary pane content
 
 ## Events
 
-- `pane-resize` - Dispatched on resize (detail: { primarySize, secondarySize, splitPane })
+- `pane-resize` → `{ primarySize, secondarySize, splitPane }`
+
+## Methods
+
+- `getPrimarySize()` - Get primary pane percentage
+- `getSecondarySize()` - Get secondary pane percentage
+- `setPrimarySize(size)` - Set primary pane percentage
+- `reset()` - Reset to 50/50
 
 ## Usage
 
@@ -34,38 +37,13 @@ reset(): void
   <div slot="secondary">Right pane</div>
 </snice-split-pane>
 
-<!-- Vertical -->
 <snice-split-pane direction="vertical">
   <div slot="primary">Top</div>
   <div slot="secondary">Bottom</div>
 </snice-split-pane>
 
-<!-- Custom size -->
-<snice-split-pane primary-size="30">
+<snice-split-pane primary-size="30" snap-size="10">
   <div slot="primary">30%</div>
   <div slot="secondary">70%</div>
 </snice-split-pane>
-
-<!-- With snap -->
-<snice-split-pane snap-size="10">
-  <div slot="primary">Snaps to 10%</div>
-  <div slot="secondary">Right</div>
-</snice-split-pane>
-
-<!-- Programmatic -->
-<script>
-  splitPane.setPrimarySize(40);
-  splitPane.reset(); // 50/50
-</script>
 ```
-
-## Features
-
-- Horizontal and vertical orientation
-- Drag to resize
-- Minimum sizes for both panes
-- Snap to grid
-- Programmatic control
-- Nested layouts supported
-- Disabled state
-- Event dispatching