snice 4.27.0 → 4.29.0

package/docs/components/menu.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/menu.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/menu.md -->
 
 # Menu
 `<snice-menu>`
@@ -6,33 +6,25 @@
 A dropdown menu with composable items, dividers, icons, and keyboard shortcut hints.
 
 ## Table of Contents
-- [Menu Properties](#menu-properties)
-- [Menu Item Properties](#menu-item-properties)
+- [Components](#components)
+- [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
-- [Menu Slots](#menu-slots)
-- [Menu Item Slots](#menu-item-slots)
+- [Slots](#slots)
 - [CSS Parts](#css-parts)
 - [CSS Custom Properties](#css-custom-properties)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 
-## Importing
+## Components
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/menu/snice-menu';
-import 'snice/components/menu/snice-menu-item';
-import 'snice/components/menu/snice-menu-divider';
-```
+- `<snice-menu>` - The dropdown menu container with trigger and panel
+- `<snice-menu-item>` - Individual selectable menu item with icon and shortcut slots
+- `<snice-menu-divider>` - Visual separator between items
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-menu.min.js"></script>
-```
+## Properties
 
-## Menu Properties
+### snice-menu
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -42,7 +34,7 @@ import 'snice/components/menu/snice-menu-divider';
 | `closeOnSelect` (attr: `close-on-select`) | `boolean` | `true` | Close on item selection |
 | `distance` | `number` | `4` | Distance from trigger to panel (px) |
 
-## Menu Item Properties
+### snice-menu-item
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -64,9 +56,11 @@ import 'snice/components/menu/snice-menu-divider';
 |-------|--------|-------------|
 | `menu-open` | `{ menu: SniceMenuElement }` | Menu opened |
 | `menu-close` | `{ menu: SniceMenuElement }` | Menu closed |
-| `menu-item-select` | `{ item: SniceMenuItemElement, value: string }` | Item selected |
+| `menu-item-select` | `{ item: SniceMenuItemElement, value: string }` | Item selected (bubbles from menu-item) |
+
+## Slots
 
-## Menu Slots
+### snice-menu
 
 | Name | Description |
 |------|-------------|
@@ -75,7 +69,7 @@ import 'snice/components/menu/snice-menu-divider';
 | `image-right` | Image/icon after the trigger |
 | (default) | Menu items and dividers |
 
-## Menu Item Slots
+### snice-menu-item
 
 | Name | Description |
 |------|-------------|
@@ -85,24 +79,30 @@ import 'snice/components/menu/snice-menu-divider';
 
 ## CSS Parts
 
-### Menu Parts
+### snice-menu
 
-| Part | Description |
-|------|-------------|
-| `trigger` | The trigger wrapper element |
-| `image-left` | Left image container |
-| `image-right` | Right image container |
-| `panel` | The dropdown panel |
-| `content` | Panel content wrapper |
+| Part | Element | Description |
+|------|---------|-------------|
+| `trigger` | `<div>` | The trigger wrapper element |
+| `image-left` | `<span>` | Left image container |
+| `image-right` | `<span>` | Right image container |
+| `panel` | `<div>` | The dropdown panel |
+| `content` | `<div>` | Panel content wrapper |
 
-### Menu Item Parts
+### snice-menu-item
 
-| Part | Description |
-|------|-------------|
-| `item` | The menu item container |
-| `icon` | Icon wrapper |
-| `label` | Label wrapper |
-| `shortcut` | Keyboard shortcut wrapper |
+| Part | Element | Description |
+|------|---------|-------------|
+| `item` | `<div>` | The menu item container |
+| `icon` | `<span>` | Icon wrapper |
+| `label` | `<span>` | Label wrapper |
+| `shortcut` | `<span>` | Keyboard shortcut wrapper |
+
+### snice-menu-divider
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `divider` | `<div>` | The separator line |
 
 ## CSS Custom Properties
 
@@ -165,11 +165,6 @@ Use the `icon` and `shortcut` slots on menu items to add visual cues.
 Use the `placement` attribute to position the menu relative to its trigger.
 
 ```html
-<snice-menu placement="bottom-start">
-  <button slot="trigger">Bottom Start</button>
-  <snice-menu-item value="1">Option 1</snice-menu-item>
-</snice-menu>
-
 <snice-menu placement="bottom-end">
   <button slot="trigger">Bottom End</button>
   <snice-menu-item value="1">Option 1</snice-menu-item>
@@ -198,20 +193,18 @@ Set `trigger="hover"` to open the menu on mouse hover.
 Set `trigger="manual"` and use methods to control the menu programmatically.
 
 ```html
-<snice-menu trigger="manual">
+<snice-menu trigger="manual" id="my-menu">
   <button slot="trigger">Manual</button>
   <snice-menu-item value="1">Option 1</snice-menu-item>
 </snice-menu>
 ```
 
 ```typescript
-menu.openMenu();
+document.getElementById('my-menu').openMenu();
 ```
 
 ### Disabled Items
 
-Set the `disabled` attribute on individual menu items.
-
 ```html
 <snice-menu>
   <button slot="trigger">Actions</button>

package/docs/components/message-strip.md

@@ -1,6 +1,6 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/message-strip.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/message-strip.md -->
 
-# Message Strip Component
+# Message Strip
 `<snice-message-strip>`
 
 An inline contextual message bar for displaying status messages within content flow. Unlike alerts (dismissable card), banners (full-width top), and toasts (floating), message strips are designed to sit inline within your content.
@@ -13,19 +13,7 @@ An inline contextual message bar for displaying status messages within content f
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/message-strip/snice-message-strip';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-message-strip.min.js"></script>
-```
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -33,15 +21,14 @@ import 'snice/components/message-strip/snice-message-strip';
 |----------|------|---------|-------------|
 | `variant` | `'info' \| 'success' \| 'warning' \| 'danger'` | `'info'` | Message type / color |
 | `dismissable` | `boolean` | `false` | Show dismiss button |
-| `icon` | `string` | `''` | Custom icon (set "none" to hide) |
+| `icon` | `string` | `''` | Custom icon (set "none" to hide default icon) |
 
 ## Methods
 
-#### `show(): void`
-Show the message strip after it has been hidden.
-
-#### `hide(): void`
-Hide the message strip with a slide-out animation.
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | -- | Show the message strip after it has been hidden |
+| `hide()` | -- | Hide the message strip with a slide-out animation |
 
 ## Events
 
@@ -58,11 +45,13 @@ Hide the message strip with a slide-out animation.
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `icon` | The icon container |
-| `content` | The message content area |
-| `dismiss` | The dismiss button |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `icon` | `<div>` | The icon container |
+| `content` | `<div>` | The message content area |
+| `dismiss` | `<button>` | The dismiss button |
 
 ```css
 snice-message-strip::part(content) {
@@ -144,12 +133,6 @@ Use the `icon` slot for custom icon elements.
 
 ### Programmatic Show/Hide
 
-```html
-<snice-message-strip variant="success">
-  Your changes have been saved.
-</snice-message-strip>
-```
-
 ```typescript
 messageStrip.hide();
 messageStrip.show();
@@ -168,16 +151,6 @@ messageStrip.show();
 </form>
 ```
 
-```typescript
-form.addEventListener('submit', (e) => {
-  if (!form.checkValidity()) {
-    e.preventDefault();
-    errorStrip.style.display = '';
-    errorStrip.show();
-  }
-});
-```
-
 ### Stacked Messages
 
 ```html
@@ -200,12 +173,3 @@ form.addEventListener('submit', (e) => {
 - Dismiss button has `aria-label="Dismiss"`
 - Default variant icons provide visual context clues
 - Supports both light and dark color schemes
-
-## When to Use Which
-
-| Component | Use Case |
-|-----------|----------|
-| **Message Strip** | Inline contextual feedback within content |
-| **Alert** | Prominent dismissable card-style notification |
-| **Banner** | Full-width message at the top of the page |
-| **Toast** | Floating temporary notification |

package/docs/components/metric-table.md

@@ -1,7 +1,6 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/metric-table.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/metric-table.md -->
 
 # Metric Table
-
 `<snice-metric-table>`
 
 A compact data table optimized for numeric and metric data with inline sparklines, color-coded values, and built-in sorting.
@@ -12,28 +11,16 @@ A compact data table optimized for numeric and metric data with inline sparkline
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/metric-table/snice-metric-table';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-metric-table.min.js"></script>
-```
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `columns` | `MetricColumn[]` | `[]` | Column definitions |
-| `data` | `Record<string, any>[]` | `[]` | Row data objects |
-| `sortBy` (attr: `sort-by`) | `string` | `''` | Column key to sort by |
-| `sortDirection` (attr: `sort-direction`) | `'asc' \| 'desc'` | `'desc'` | Sort direction |
+| `columns` | `MetricColumn[]` | `[]` | Column definitions (set via JavaScript) |
+| `data` | `Record<string, any>[]` | `[]` | Row data objects (set via JavaScript) |
+| `sortBy` | `string` | `''` | Column key to sort by |
+| `sortDirection` | `'asc' \| 'desc'` | `'desc'` | Sort direction |
 
 ### MetricColumn Interface
 
@@ -56,11 +43,13 @@ interface MetricColumn {
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | Root container |
-| `table` | The table element |
-| `row` | Individual table row |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | Root container |
+| `table` | `<table>` | The table element |
+| `row` | `<tr>` | Individual table row |
 
 ```css
 snice-metric-table::part(row) {
@@ -100,55 +89,49 @@ import 'snice/components/metric-table/snice-metric-table';
 
 Define column types to control formatting. Numeric types (`number`, `percent`, `currency`) are right-aligned and color-coded.
 
-```html
-<script>
-  el.columns = [
-    { key: 'name', label: 'Metric', type: 'text' },
-    { key: 'value', label: 'Value', type: 'number' },
-    { key: 'change', label: 'Change', type: 'percent' },
-    { key: 'revenue', label: 'Revenue', type: 'currency' }
-  ];
-</script>
+```javascript
+el.columns = [
+  { key: 'name', label: 'Metric', type: 'text' },
+  { key: 'value', label: 'Value', type: 'number' },
+  { key: 'change', label: 'Change', type: 'percent' },
+  { key: 'revenue', label: 'Revenue', type: 'currency' }
+];
 ```
 
 ### Sparklines
 
 Set `sparkline: true` on a column to render array data as inline SVG sparklines. Sparklines are green when trending up and red when trending down.
 
-```html
-<script>
-  el.columns = [
-    { key: 'name', label: 'Metric', type: 'text' },
-    { key: 'trend', label: 'Trend (7d)', sparkline: true }
-  ];
-  el.data = [
-    { name: 'Revenue', trend: [100, 120, 115, 130, 125, 140, 150] },
-    { name: 'Churn', trend: [5, 6, 7, 8, 7, 8, 9] }
-  ];
-</script>
+```javascript
+el.columns = [
+  { key: 'name', label: 'Metric', type: 'text' },
+  { key: 'trend', label: 'Trend (7d)', sparkline: true }
+];
+el.data = [
+  { name: 'Revenue', trend: [100, 120, 115, 130, 125, 140, 150] },
+  { name: 'Churn', trend: [5, 6, 7, 8, 7, 8, 9] }
+];
 ```
 
 ### Color-Coded Values
 
 Positive numeric values are displayed in green, negative values in red. This applies automatically to `number`, `percent`, and `currency` column types.
 
-```html
-<script>
-  el.columns = [
-    { key: 'metric', label: 'Metric', type: 'text' },
-    { key: 'change', label: 'Change', type: 'percent' }
-  ];
-  el.data = [
-    { metric: 'Revenue', change: 12.3 },    // Green
-    { metric: 'Churn', change: -2.5 },       // Red
-    { metric: 'Retention', change: 0 }       // Default color
-  ];
-</script>
+```javascript
+el.columns = [
+  { key: 'metric', label: 'Metric', type: 'text' },
+  { key: 'change', label: 'Change', type: 'percent' }
+];
+el.data = [
+  { metric: 'Revenue', change: 12.3 },    // Green
+  { metric: 'Churn', change: -2.5 },       // Red
+  { metric: 'Retention', change: 0 }       // Default color
+];
 ```
 
 ### Sorting
 
-Click column headers to sort. The first click sorts descending, subsequent clicks toggle direction. The active sort column shows a directional indicator.
+Click column headers to sort. The first click sorts descending, subsequent clicks toggle direction.
 
 ```html
 <snice-metric-table id="sorted" sort-by="value" sort-direction="desc"></snice-metric-table>
@@ -164,27 +147,21 @@ Click column headers to sort. The first click sorts descending, subsequent click
 
 Use the `format` property on currency columns to specify the currency code (default: `USD`).
 
-```html
-<script>
-  el.columns = [
-    { key: 'name', label: 'Product', type: 'text' },
-    { key: 'price', label: 'Price (EUR)', type: 'currency', format: 'EUR' }
-  ];
-</script>
+```javascript
+el.columns = [
+  { key: 'name', label: 'Product', type: 'text' },
+  { key: 'price', label: 'Price (EUR)', type: 'currency', format: 'EUR' }
+];
 ```
 
 ### Row Clicks
 
 Listen for `row-click` events to handle row interactions.
 
-```html
-<snice-metric-table id="clickable"></snice-metric-table>
-
-<script>
-  document.getElementById('clickable').addEventListener('row-click', e => {
-    console.log('Row:', e.detail.row, 'Index:', e.detail.index);
-  });
-</script>
+```javascript
+document.getElementById('clickable').addEventListener('row-click', e => {
+  console.log('Row:', e.detail.row, 'Index:', e.detail.index);
+});
 ```
 
 ## Accessibility
@@ -193,3 +170,4 @@ Listen for `row-click` events to handle row interactions.
 - Rows are keyboard accessible with `tabindex="0"`
 - Press Enter or Space to activate a row
 - Sort icons provide visual indication of sort state
+- Null/undefined values are shown as an em-dash

package/docs/components/modal.md

@@ -1,22 +1,20 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/modal.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/modal.md -->
 
 # Modal
 `<snice-modal>`
 
 A dialog overlay with focus trapping, backdrop dismiss, and keyboard navigation.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/modal/snice-modal';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-modal.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -136,38 +134,23 @@ Set `no-backdrop-dismiss` to prevent closing when clicking outside.
 </snice-modal>
 ```
 
-### Prevent Escape Dismiss
-
-Set `no-escape-dismiss` to prevent closing with the Escape key.
-
-```html
-<snice-modal no-escape-dismiss label="Confirmation Required">
-  <div slot="header"><h2>Confirm Action</h2></div>
-  <p>Pressing Escape won't close this modal.</p>
-  <div slot="footer">
-    <button onclick="this.closest('snice-modal').close()">Confirm</button>
-  </div>
-</snice-modal>
-```
-
 ### Confirmation Dialog
 
 ```html
-<button>Delete Item</button>
+<button id="deleteBtn">Delete Item</button>
 
-<snice-modal size="small" label="Confirm Delete">
+<snice-modal id="confirmModal" size="small" label="Confirm Delete">
   <div slot="header"><h2>Confirm Delete</h2></div>
   <p>Are you sure? This action cannot be undone.</p>
   <div slot="footer">
-    <button>Cancel</button>
-    <button>Delete</button>
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button id="confirmBtn">Delete</button>
   </div>
 </snice-modal>
 ```
 
 ```typescript
 deleteBtn.addEventListener('click', () => modal.show());
-cancelBtn.addEventListener('click', () => modal.close());
 confirmBtn.addEventListener('click', () => {
   console.log('Item deleted');
   modal.close();
@@ -177,8 +160,6 @@ confirmBtn.addEventListener('click', () => {
 ### Form in Modal
 
 ```html
-<button>Edit Profile</button>
-
 <snice-modal label="Edit Profile">
   <div slot="header"><h2>Edit Profile</h2></div>
   <form style="display:flex;flex-direction:column;gap:1rem;">
@@ -192,15 +173,6 @@ confirmBtn.addEventListener('click', () => {
 </snice-modal>
 ```
 
-```typescript
-editBtn.addEventListener('click', () => modal.show());
-profileForm.addEventListener('submit', (e) => {
-  e.preventDefault();
-  console.log('Saved:', Object.fromEntries(new FormData(e.target)));
-  modal.close();
-});
-```
-
 ### Programmatic Control
 
 ```typescript
@@ -210,3 +182,20 @@ modal.close(); // Close
 modal.addEventListener('modal-open', () => console.log('Opened'));
 modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Escape | Close the modal (unless `no-escape-dismiss` is set) |
+| Tab | Cycle through focusable elements within the modal |
+| Shift+Tab | Cycle backwards through focusable elements |
+
+## Accessibility
+
+- Uses `role="dialog"` with `aria-modal="true"` and `aria-label`
+- Focus is trapped within the modal by default (disable with `no-focus-trap`)
+- First focusable element receives focus on open
+- Previous focus is restored on close
+- Body scroll is locked while modal is open
+- Close button has `aria-label="Close modal"`