snice 4.28.0 → 4.29.0

package/docs/components/recipe.md

@@ -1,10 +1,11 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/recipe.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/recipe.md -->
 
-# Recipe Component
+# Recipe
 
-The recipe component displays an interactive recipe card with a hero image, ingredient scaling based on serving size, step-by-step mode with per-step timers, ingredient checkboxes, and optional nutrition facts.
+An interactive recipe card with ingredient scaling, step-by-step mode with per-step timers, ingredient checkboxes, and optional nutrition facts.
 
 ## Table of Contents
+
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -27,104 +28,53 @@ The recipe component displays an interactive recipe card with a hero image, ingr
 | `difficulty` | `'easy' \| 'medium' \| 'hard'` | `'medium'` | Difficulty level |
 | `cuisine` | `string` | `''` | Cuisine type (displayed as a tag) |
 | `variant` | `'card' \| 'full'` | `'full'` | Display variant |
-| `ingredients` | `RecipeIngredient[]` | `[]` | Ingredient list |
-| `steps` | `RecipeStep[]` | `[]` | Instruction steps |
-| `nutrition` | `RecipeNutrition \| null` | `null` | Nutrition facts per serving |
-| `tags` | `string[]` | `[]` | Recipe tags |
+| `ingredients` | `RecipeIngredient[]` | `[]` | Ingredient list (JS only) |
+| `steps` | `RecipeStep[]` | `[]` | Instruction steps (JS only) |
+| `nutrition` | `RecipeNutrition \| null` | `null` | Nutrition facts per serving (JS only) |
+| `tags` | `string[]` | `[]` | Recipe tags (JS only) |
 
-### RecipeIngredient Interface
+### Type Interfaces
 
 ```typescript
 interface RecipeIngredient {
   name: string;
   amount: number;
   unit: string;
-  group?: string;   // Group header for ingredient sections (e.g. 'Sauce', 'Dough')
+  group?: string;   // Group header (e.g. 'Sauce', 'Dough')
 }
-```
 
-### RecipeStep Interface
-
-```typescript
 interface RecipeStep {
   text: string;
   image?: string;   // Step photo URL
   tip?: string;     // Pro tip text
-  time?: number;    // Timer duration in minutes (shows inline timer button)
+  time?: number;    // Timer duration in minutes
 }
-```
-
-### RecipeNutrition Interface
 
-```typescript
 interface RecipeNutrition {
   calories: number;
-  protein: number;   // in grams
-  carbs: number;     // in grams
-  fat: number;       // in grams
-  fiber?: number;    // in grams
-  sodium?: number;   // in mg
+  protein: number;   // grams
+  carbs: number;     // grams
+  fat: number;       // grams
+  fiber?: number;    // grams
+  sodium?: number;   // mg
 }
 ```
 
 ## Methods
 
-#### `setServings(count: number): void`
-Adjust the serving count. All ingredient quantities scale proportionally.
-
-```typescript
-recipe.setServings(8); // Doubles ingredients for a 4-serving base recipe
-```
-
-#### `print(): void`
-Open a print-friendly view of the recipe.
-
-```typescript
-recipe.print();
-```
-
-#### `reset(): void`
-Reset all checked ingredients, completed steps, running timers, and serving count back to defaults.
-
-```typescript
-recipe.reset();
-```
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `setServings()` | `count: number` | Adjust serving count; all ingredient quantities scale proportionally |
+| `print()` | — | Open a print-friendly view |
+| `reset()` | — | Reset checked ingredients, completed steps, timers, and serving count |
 
 ## Events
 
-#### `recipe-serving-change`
-Fired when the serving count changes.
-
-**Event Detail:**
-```typescript
-{
-  servings: number;          // New serving count
-  previousServings: number;  // Previous serving count
-}
-```
-
-#### `recipe-step-complete`
-Fired when a step is marked as complete or incomplete.
-
-**Event Detail:**
-```typescript
-{
-  stepIndex: number;    // Zero-based step index
-  completed: boolean;   // Whether the step is now completed
-}
-```
-
-#### `recipe-ingredient-check`
-Fired when an ingredient checkbox is toggled.
-
-**Event Detail:**
-```typescript
-{
-  ingredientIndex: number;         // Zero-based ingredient index
-  checked: boolean;                // Whether the ingredient is now checked
-  ingredient: RecipeIngredient;    // The ingredient object
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `recipe-serving-change` | `{ servings: number, previousServings: number }` | Serving count changed |
+| `recipe-step-complete` | `{ stepIndex: number, completed: boolean }` | Step marked complete or incomplete |
+| `recipe-ingredient-check` | `{ ingredientIndex: number, checked: boolean, ingredient: RecipeIngredient }` | Ingredient checkbox toggled |
 
 ## CSS Parts
 
@@ -132,76 +82,71 @@ Fired when an ingredient checkbox is toggled.
 |------|-------------|
 | `container` | The outer recipe container |
 | `hero` | The hero image area |
-| `header` | Title and description section |
+| `header` | Title, description, and author section |
 | `meta` | Metadata bar (prep time, cook time, servings, difficulty) |
 | `content` | Main content area (ingredients + steps) |
 | `ingredients` | Ingredients section |
 | `steps` | Steps/instructions section |
 | `nutrition` | Nutrition facts panel |
-| `controls` | Serving size controls |
+| `controls` | Bottom control buttons (step-by-step, print, reset) |
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/recipe/snice-recipe';
+```
+
 ```html
 <snice-recipe id="my-recipe"></snice-recipe>
-
-<script type="module">
-  import 'snice/components/recipe/snice-recipe';
-
-  const recipe = document.getElementById('my-recipe');
-  recipe.title = 'Pasta Carbonara';
-  recipe.prepTime = 10;
-  recipe.cookTime = 20;
-  recipe.servings = 4;
-  recipe.ingredients = [
-    { name: 'Spaghetti', amount: 400, unit: 'g' },
-    { name: 'Pancetta', amount: 200, unit: 'g' }
-  ];
-  recipe.steps = [
-    { text: 'Boil pasta in salted water.', time: 10 },
-    { text: 'Fry pancetta until crispy.' }
-  ];
-</script>
 ```
 
 ```typescript
-import 'snice/components/recipe/snice-recipe';
+const recipe = document.getElementById('my-recipe');
+recipe.title = 'Pasta Carbonara';
+recipe.prepTime = 10;
+recipe.cookTime = 20;
+recipe.servings = 4;
+recipe.ingredients = [
+  { name: 'Spaghetti', amount: 400, unit: 'g' },
+  { name: 'Pancetta', amount: 200, unit: 'g' }
+];
+recipe.steps = [
+  { text: 'Boil pasta in salted water.', time: 10 },
+  { text: 'Fry pancetta until crispy.' }
+];
 ```
 
 ## Examples
 
 ### Full Recipe with All Features
 
-```html
-<snice-recipe id="carbonara"></snice-recipe>
-
-<script type="module">
-  const recipe = document.getElementById('carbonara');
-  recipe.title = 'Pasta Carbonara';
-  recipe.description = 'Classic Italian pasta with a creamy egg and cheese sauce.';
-  recipe.image = '/images/carbonara.jpg';
-  recipe.author = 'Chef Maria';
-  recipe.prepTime = 10;
-  recipe.cookTime = 20;
-  recipe.servings = 4;
-  recipe.difficulty = 'medium';
-  recipe.cuisine = 'Italian';
-  recipe.tags = ['pasta', 'italian', 'quick'];
-  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' },
-    { name: 'Black pepper', amount: 2, unit: 'tsp', 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 in a bowl.' },
-    { text: 'Combine all ingredients off heat.', tip: 'The residual heat cooks the egg without scrambling.' }
-  ];
-  recipe.nutrition = { calories: 650, protein: 28, carbs: 72, fat: 24, fiber: 3 };
-</script>
+Set all properties for a complete recipe with grouped ingredients, step tips, timers, and nutrition.
+
+```typescript
+recipe.title = 'Pasta Carbonara';
+recipe.description = 'Classic Italian pasta with a creamy egg and cheese sauce.';
+recipe.image = '/images/carbonara.jpg';
+recipe.author = 'Chef Maria';
+recipe.prepTime = 10;
+recipe.cookTime = 20;
+recipe.servings = 4;
+recipe.difficulty = 'medium';
+recipe.cuisine = 'Italian';
+recipe.tags = ['pasta', 'italian', 'quick'];
+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' },
+  { name: 'Black pepper', amount: 2, unit: 'tsp', 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 in a bowl.' },
+  { text: 'Combine all ingredients off heat.', tip: 'The residual heat cooks the egg without scrambling.' }
+];
+recipe.nutrition = { calories: 650, protein: 28, carbs: 72, fat: 24, fiber: 3 };
 ```
 
 ### Card Variant
@@ -210,105 +155,51 @@ Use `variant="card"` for a compact card display.
 
 ```html
 <snice-recipe id="salad" variant="card"></snice-recipe>
-
-<script type="module">
-  const recipe = document.getElementById('salad');
-  recipe.title = 'Caesar Salad';
-  recipe.image = '/images/caesar-salad.jpg';
-  recipe.prepTime = 15;
-  recipe.cookTime = 0;
-  recipe.servings = 2;
-  recipe.difficulty = 'easy';
-  recipe.cuisine = 'American';
-  recipe.ingredients = [
-    { name: 'Romaine lettuce', amount: 1, unit: 'head' },
-    { name: 'Croutons', amount: 100, unit: 'g' },
-    { name: 'Parmesan', amount: 50, unit: 'g' },
-    { name: 'Caesar dressing', amount: 60, unit: 'ml' }
-  ];
-  recipe.steps = [
-    { text: 'Wash and chop the romaine lettuce.' },
-    { text: 'Toss with dressing, croutons, and shaved parmesan.' }
-  ];
-</script>
 ```
 
-### Handling Serving Size Changes
+### Grouped Ingredients
 
-```html
-<snice-recipe id="recipe-interactive"></snice-recipe>
-
-<script type="module">
-  const recipe = document.getElementById('recipe-interactive');
-  recipe.title = 'Chocolate Chip Cookies';
-  recipe.servings = 24;
-  recipe.difficulty = 'easy';
-  recipe.ingredients = [
-    { name: 'All-purpose flour', amount: 280, unit: 'g' },
-    { name: 'Butter', amount: 230, unit: 'g' },
-    { name: 'Sugar', amount: 200, unit: 'g' },
-    { name: 'Chocolate chips', amount: 340, unit: 'g' },
-    { name: 'Eggs', amount: 2, unit: '' }
-  ];
-  recipe.steps = [
-    { text: 'Cream butter and sugar together.' },
-    { text: 'Add eggs and mix until combined.' },
-    { text: 'Fold in flour and chocolate chips.' },
-    { text: 'Scoop onto baking sheet and bake.', time: 12 }
-  ];
-
-  recipe.addEventListener('recipe-serving-change', (e) => {
-    console.log(`Servings changed: ${e.detail.previousServings} -> ${e.detail.servings}`);
-  });
-
-  recipe.addEventListener('recipe-ingredient-check', (e) => {
-    console.log(`${e.detail.ingredient.name}: ${e.detail.checked ? 'checked' : 'unchecked'}`);
-  });
-</script>
+Use the `group` property on ingredients to create sections.
+
+```typescript
+recipe.ingredients = [
+  { name: 'Bread flour', amount: 300, unit: 'g', group: 'Dough' },
+  { name: 'Yeast', amount: 7, unit: 'g', group: 'Dough' },
+  { name: 'Tomatoes', amount: 400, unit: 'g', group: 'Topping' },
+  { name: 'Mozzarella', amount: 200, unit: 'g', group: 'Topping' }
+];
 ```
 
-### Recipe with Grouped Ingredients
+### Event Handling
 
-```html
-<snice-recipe id="pizza"></snice-recipe>
-
-<script type="module">
-  const recipe = document.getElementById('pizza');
-  recipe.title = 'Margherita Pizza';
-  recipe.prepTime = 30;
-  recipe.cookTime = 15;
-  recipe.servings = 2;
-  recipe.difficulty = 'medium';
-  recipe.ingredients = [
-    { name: 'Bread flour', amount: 300, unit: 'g', group: 'Dough' },
-    { name: 'Yeast', amount: 7, unit: 'g', group: 'Dough' },
-    { name: 'Water', amount: 200, unit: 'ml', group: 'Dough' },
-    { name: 'Olive oil', amount: 2, unit: 'tbsp', group: 'Dough' },
-    { name: 'San Marzano tomatoes', amount: 400, unit: 'g', group: 'Topping' },
-    { name: 'Fresh mozzarella', amount: 200, unit: 'g', group: 'Topping' },
-    { name: 'Fresh basil', amount: 10, unit: 'leaves', group: 'Topping' }
-  ];
-  recipe.steps = [
-    { text: 'Mix flour, yeast, water, and olive oil. Knead for 10 minutes.', time: 10 },
-    { text: 'Let dough rise for 1 hour.', time: 60, tip: 'Cover with a damp cloth in a warm spot.' },
-    { text: 'Crush tomatoes and spread on stretched dough.' },
-    { text: 'Add torn mozzarella and bake at 250C.', time: 15 },
-    { text: 'Add fresh basil after baking.' }
-  ];
-</script>
+Listen for events to track user interaction with the recipe.
+
+```typescript
+recipe.addEventListener('recipe-serving-change', (e) => {
+  console.log(`Servings: ${e.detail.previousServings} -> ${e.detail.servings}`);
+});
+
+recipe.addEventListener('recipe-ingredient-check', (e) => {
+  console.log(`${e.detail.ingredient.name}: ${e.detail.checked ? 'checked' : 'unchecked'}`);
+});
+
+recipe.addEventListener('recipe-step-complete', (e) => {
+  console.log(`Step ${e.detail.stepIndex}: ${e.detail.completed ? 'done' : 'undone'}`);
+});
 ```
 
-### Print a Recipe
+### Print
 
-```html
-<snice-recipe id="printable-recipe"></snice-recipe>
-<button onclick="document.getElementById('printable-recipe').print()">Print Recipe</button>
+Use `print()` to open a print-friendly view.
+
+```typescript
+recipe.print();
 ```
 
 ## Accessibility
 
-- **Keyboard support**: Ingredient checkboxes and step toggles are keyboard accessible
-- **Serving adjuster**: The serving size controls are operable via keyboard
-- **Screen readers**: Step numbers, ingredient amounts, and completion states are announced
-- **Timer buttons**: Inline timer buttons on steps with a `time` value are keyboard focusable
-- **Print view**: The `print()` method produces a clean layout for printing
+- Ingredient checkboxes and step toggles are keyboard accessible
+- Serving size +/- buttons have `aria-label` attributes
+- Step numbers announce completion state
+- Timer buttons are keyboard focusable
+- Print view produces a clean layout

package/docs/components/sankey.md

@@ -1,28 +1,23 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/sankey.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/sankey.md -->
 
 # Sankey
-`<snice-sankey>`
 
 An SVG-based Sankey diagram for visualizing flow between categories.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/sankey/snice-sankey';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-sankey.min.js"></script>
-```
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `data` | `SankeyData` | `{ nodes: [], links: [] }` | Nodes and links data (set via JS) |
+| `data` | `SankeyData` | `{ nodes: [], links: [] }` | Nodes and links data (JS only) |
 | `nodeWidth` (attr: `node-width`) | `number` | `20` | Width of node rectangles |
 | `nodePadding` (attr: `node-padding`) | `number` | `10` | Vertical padding between nodes |
 | `alignment` | `'left' \| 'right' \| 'center' \| 'justify'` | `'justify'` | Leaf node alignment |
@@ -30,35 +25,43 @@ import 'snice/components/sankey/snice-sankey';
 | `showValues` (attr: `show-values`) | `boolean` | `true` | Show node values |
 | `animation` | `boolean` | `false` | Animate on initial render |
 
+### Type Interfaces
+
+```typescript
+interface SankeyData {
+  nodes: SankeyNode[];
+  links: SankeyLink[];
+}
+
+interface SankeyNode {
+  id: string;
+  label?: string;   // Defaults to id
+  color?: string;    // Auto-assigned if omitted
+}
+
+interface SankeyLink {
+  source: string;    // Source node id
+  target: string;    // Target node id
+  value: number;     // Flow value (determines link width)
+  color?: string;    // Defaults to source node color
+}
+```
+
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
 | `sankey-node-click` | `{ node: SankeyNode }` | Node clicked |
 | `sankey-link-click` | `{ link: SankeyLink }` | Link clicked |
-| `sankey-hover` | `{ type: 'node' \| 'link', item } \| null` | Hover state changed |
+| `sankey-hover` | `{ type: 'node' \| 'link', item } \| null` | Hover state changed (null on mouse leave) |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer Sankey container |
-| `chart` | `<div>` | The SVG chart area |
-| `tooltip` | `<div>` | The hover tooltip showing node/link details |
-
-```css
-snice-sankey::part(base) {
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
-}
-
-snice-sankey::part(tooltip) {
-  font-size: 0.875rem;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | The outer Sankey container |
+| `chart` | The SVG chart area |
+| `tooltip` | The hover tooltip |
 
 ## Basic Usage
 
@@ -86,9 +89,7 @@ sankey.data = {
 
 ### Energy Flow
 
-```html
-<snice-sankey show-labels show-values animation style="height: 400px;"></snice-sankey>
-```
+A multi-level Sankey diagram showing energy sources flowing to consumers.
 
 ```typescript
 sankey.data = {
@@ -108,36 +109,12 @@ sankey.data = {
 };
 ```
 
-### Budget Breakdown
-
-```html
-<snice-sankey show-labels show-values style="height: 300px;"></snice-sankey>
-```
-
-```typescript
-sankey.data = {
-  nodes: [
-    { id: 'salary', label: 'Salary', color: '#10b981' },
-    { id: 'housing', label: 'Housing', color: '#ef4444' },
-    { id: 'food', label: 'Food', color: '#f59e0b' },
-    { id: 'savings', label: 'Savings', color: '#06b6d4' }
-  ],
-  links: [
-    { source: 'salary', target: 'housing', value: 1500 },
-    { source: 'salary', target: 'food', value: 600 },
-    { source: 'salary', target: 'savings', value: 900 }
-  ]
-};
-```
-
 ### Alignment Options
 
-Use the `alignment` attribute to control how leaf nodes are positioned.
+Use `alignment` to control how leaf nodes are positioned.
 
 ```html
 <snice-sankey alignment="left" show-labels></snice-sankey>
-<snice-sankey alignment="right" show-labels></snice-sankey>
-<snice-sankey alignment="center" show-labels></snice-sankey>
 <snice-sankey alignment="justify" show-labels></snice-sankey>
 ```
 
@@ -151,7 +128,7 @@ Use `node-width` and `node-padding` to adjust the layout.
 
 ### Animation
 
-Set the `animation` attribute for animated rendering.
+Set `animation` for animated rendering on initial load.
 
 ```html
 <snice-sankey animation show-labels show-values></snice-sankey>
@@ -159,6 +136,8 @@ Set the `animation` attribute for animated rendering.
 
 ### Event Handling
 
+Listen for click and hover events on nodes and links.
+
 ```typescript
 sankey.addEventListener('sankey-node-click', (e) => {
   console.log('Node:', e.detail.node.label);
@@ -175,24 +154,9 @@ sankey.addEventListener('sankey-hover', (e) => {
 });
 ```
 
-## Data Types
-
-```typescript
-interface SankeyData {
-  nodes: SankeyNode[];
-  links: SankeyLink[];
-}
-
-interface SankeyNode {
-  id: string;
-  label?: string;   // Defaults to id
-  color?: string;    // Auto-assigned if omitted
-}
+## Accessibility
 
-interface SankeyLink {
-  source: string;    // Source node id
-  target: string;    // Target node id
-  value: number;     // Flow value (determines width)
-  color?: string;    // Defaults to source color
-}
-```
+- SVG rendered with `role="img"` and `aria-label`
+- Hover highlights connected nodes/links and dims others
+- Tooltips show node/link details on hover
+- Responsive sizing via `ResizeObserver`