snice 4.8.0 → 4.10.0

package/docs/components/rating.md

@@ -0,0 +1,154 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/rating.md instead)
+
+# Rating Component
+
+The rating component provides an interactive star rating input with configurable precision (full or half stars), custom icons, multiple sizes, and full keyboard navigation.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-rating value="3" max="5"></snice-rating>
+```
+
+```typescript
+import 'snice/components/rating/snice-rating';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `number` | `0` | Current rating value |
+| `max` | `number` | `5` | Maximum number of stars |
+| `icon` | `string` | `'\u2605'` (filled star) | Character used for each rating item |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Display size |
+| `readonly` | `boolean` | `false` | Disable user interaction |
+| `precision` | `'full' \| 'half'` | `'full'` | Click precision (full star or half star increments) |
+
+## Events
+
+#### `rating-change`
+Fired when the rating value changes.
+
+**Event Detail:**
+```typescript
+{
+  value: number;  // The new rating value
+}
+```
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--rating-color` | Filled star color | `var(--snice-color-warning)` |
+| `--rating-color-empty` | Empty star color | `var(--snice-color-border)` |
+| `--rating-size` | Star size (set automatically by `size` property) | `1.5rem` (medium) |
+
+## Examples
+
+### Basic Rating
+
+```html
+<snice-rating value="3"></snice-rating>
+<snice-rating value="4" max="5"></snice-rating>
+<snice-rating value="0"></snice-rating>
+```
+
+### Half-Star Precision
+
+Use the `precision="half"` attribute to allow half-star selections.
+
+```html
+<snice-rating value="3.5" precision="half"></snice-rating>
+<snice-rating value="2.5" precision="half" max="5"></snice-rating>
+```
+
+### Sizes
+
+Use the `size` attribute to adjust the display size.
+
+```html
+<snice-rating value="4" size="small"></snice-rating>
+<snice-rating value="4" size="medium"></snice-rating>
+<snice-rating value="4" size="large"></snice-rating>
+```
+
+### Custom Icons
+
+Use the `icon` attribute to replace the default star with any character or emoji.
+
+```html
+<!-- Heart rating -->
+<snice-rating value="3" icon="&#x2764;" max="5"></snice-rating>
+
+<!-- Thumbs up rating -->
+<snice-rating value="7" icon="&#x1F44D;" max="10"></snice-rating>
+
+<!-- Circle rating -->
+<snice-rating value="2" icon="&#x25CF;" max="4"></snice-rating>
+```
+
+### Readonly Display
+
+Use the `readonly` attribute to display a rating without allowing interaction.
+
+```html
+<snice-rating value="4.5" precision="half" readonly></snice-rating>
+<snice-rating value="3" readonly></snice-rating>
+```
+
+### Handling Rating Changes
+
+```html
+<snice-rating id="product-rating" value="0" max="5"></snice-rating>
+<p id="rating-label">No rating selected</p>
+
+<script type="module">
+  import 'snice/components/rating/snice-rating';
+
+  const rating = document.getElementById('product-rating');
+  const label = document.getElementById('rating-label');
+
+  rating.addEventListener('rating-change', (e) => {
+    label.textContent = `You rated: ${e.detail.value} out of 5`;
+  });
+</script>
+```
+
+### Custom Styled Rating
+
+```html
+<style>
+  .custom-rating {
+    --rating-color: #e91e63;
+    --rating-color-empty: #f8bbd0;
+  }
+</style>
+
+<snice-rating class="custom-rating" value="3" icon="&#x2764;" max="5"></snice-rating>
+```
+
+## Accessibility
+
+- **ARIA role**: Uses `role="radiogroup"` for the container with individual `role="radio"` per star
+- **Keyboard support**: Arrow keys (Left/Down to decrease, Right/Up to increase) navigate the rating; step size matches precision (1 for full, 0.5 for half)
+- **Focus indicators**: Clear focus ring on the active star
+- **Readonly mode**: When `readonly` is set, the component is not focusable or interactive
+- **Screen readers**: Current value and maximum are announced
+
+## Best Practices
+
+1. **Use half precision for review systems**: Half-star ratings give users more granularity
+2. **Display readonly ratings for averages**: Show aggregate scores as readonly
+3. **Keep max reasonable**: 5 or 10 stars are conventional; more becomes unwieldy
+4. **Provide context**: Pair ratings with labels explaining what is being rated
+5. **Use custom icons sparingly**: Stars are universally understood; custom icons may need additional context

package/docs/components/recipe.md

@@ -0,0 +1,323 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/recipe.md instead)
+
+# Recipe Component
+
+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.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```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';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | `''` | Recipe title |
+| `description` | `string` | `''` | Short description |
+| `image` | `string` | `''` | Hero image URL |
+| `author` | `string` | `''` | Recipe author name |
+| `prepTime` (attr: `prep-time`) | `number` | `0` | Prep time in minutes |
+| `cookTime` (attr: `cook-time`) | `number` | `0` | Cook time in minutes |
+| `servings` | `number` | `4` | Base serving count |
+| `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 |
+
+### RecipeIngredient Interface
+
+```typescript
+interface RecipeIngredient {
+  name: string;
+  amount: number;
+  unit: string;
+  group?: string;   // Group header for ingredient sections (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)
+}
+```
+
+### 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
+}
+```
+
+## 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();
+```
+
+## 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
+}
+```
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | The outer recipe container |
+| `hero` | The hero image area |
+| `header` | Title and description 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 |
+
+## 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>
+```
+
+### Card Variant
+
+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
+
+```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>
+```
+
+### Recipe with Grouped Ingredients
+
+```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>
+```
+
+### Print a Recipe
+
+```html
+<snice-recipe id="printable-recipe"></snice-recipe>
+<button onclick="document.getElementById('printable-recipe').print()">Print Recipe</button>
+```
+
+## 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
+
+## Best Practices
+
+1. **Include all metadata**: Prep time, cook time, difficulty, and cuisine help users plan
+2. **Group related ingredients**: Use the `group` property to organize ingredients into logical sections
+3. **Add tips to tricky steps**: Use `step.tip` for pro tips that help less experienced cooks
+4. **Use timers on timed steps**: Steps with a `time` value show inline timer buttons for convenience
+5. **Provide nutrition facts**: Include nutrition data when available for health-conscious users
+6. **Use the card variant for lists**: When displaying multiple recipes in a grid, use `variant="card"`

package/docs/components/sankey.md

@@ -0,0 +1,178 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/sankey.md instead)
+
+# Sankey
+`<snice-sankey>`
+
+An SVG-based Sankey diagram for visualizing flow between categories.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/sankey/snice-sankey';
+```
+
+```html
+<snice-sankey id="diagram" show-labels show-values style="height: 300px;"></snice-sankey>
+
+<script type="module">
+  document.getElementById('diagram').data = {
+    nodes: [
+      { id: 'source', label: 'Source', color: '#2196f3' },
+      { id: 'target', label: 'Target', color: '#4caf50' }
+    ],
+    links: [
+      { source: 'source', target: 'target', value: 100 }
+    ]
+  };
+</script>
+```
+
+## Importing
+
+**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>
+```
+
+## Examples
+
+### Energy Flow
+
+```html
+<snice-sankey id="energy" show-labels show-values animation style="height: 400px;"></snice-sankey>
+
+<script type="module">
+  document.getElementById('energy').data = {
+    nodes: [
+      { id: 'solar', label: 'Solar', color: '#f59e0b' },
+      { id: 'wind', label: 'Wind', color: '#3b82f6' },
+      { id: 'electric', label: 'Electricity', color: '#8b5cf6' },
+      { id: 'residential', label: 'Residential', color: '#10b981' },
+      { id: 'commercial', label: 'Commercial', color: '#06b6d4' }
+    ],
+    links: [
+      { source: 'solar', target: 'electric', value: 120 },
+      { source: 'wind', target: 'electric', value: 90 },
+      { source: 'electric', target: 'residential', value: 130 },
+      { source: 'electric', target: 'commercial', value: 80 }
+    ]
+  };
+</script>
+```
+
+### Budget Breakdown
+
+```html
+<snice-sankey id="budget" show-labels show-values style="height: 300px;"></snice-sankey>
+
+<script type="module">
+  document.getElementById('budget').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 }
+    ]
+  };
+</script>
+```
+
+### Alignment Options
+
+Use the `alignment` attribute 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>
+```
+
+### Custom Node Width and Padding
+
+Use `node-width` and `node-padding` to adjust the layout.
+
+```html
+<snice-sankey node-width="30" node-padding="20" show-labels style="height: 300px;"></snice-sankey>
+```
+
+### Animation
+
+Set the `animation` attribute for animated rendering.
+
+```html
+<snice-sankey animation show-labels show-values></snice-sankey>
+```
+
+### Event Handling
+
+```typescript
+const sankey = document.querySelector('snice-sankey');
+
+sankey.addEventListener('@snice/sankey-node-click', (e) => {
+  console.log('Node:', e.detail.node.label);
+});
+
+sankey.addEventListener('@snice/sankey-link-click', (e) => {
+  console.log('Link:', e.detail.link.source, '->', e.detail.link.target);
+});
+
+sankey.addEventListener('@snice/sankey-hover', (e) => {
+  if (e.detail) {
+    console.log('Hovering:', e.detail.type, e.detail.item);
+  }
+});
+```
+
+## Data Types
+
+```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 width)
+  color?: string;    // Defaults to source color
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `SankeyData` | `{ nodes: [], links: [] }` | Nodes and links data (set via JS) |
+| `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 |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Show node labels |
+| `showValues` (attr: `show-values`) | `boolean` | `true` | Show node values |
+| `animation` | `boolean` | `false` | Animate on initial render |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/sankey-node-click` | `{ node: SankeyNode }` | Node clicked |
+| `@snice/sankey-link-click` | `{ link: SankeyLink }` | Link clicked |
+| `@snice/sankey-hover` | `{ type: 'node' \| 'link', item } \| null` | Hover state changed |