snice 4.27.0 → 4.29.0

package/docs/components/alert.md

@@ -1,20 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/alert.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/alert.md -->
 
-# Alert Component
+# Alert
+`<snice-alert>`
 
-The alert component displays notification messages to provide user feedback for informational, success, warning, or error states. It supports customizable variants, sizes, titles, icons, and optional dismissal.
+Displays notification messages to provide user feedback for informational, success, warning, or error states. Supports customizable variants, sizes, titles, icons, and optional dismissal.
 
 ## Table of Contents
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
 - [Slots](#slots)
+- [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
-- [Common Patterns](#common-patterns)
-- [Variant Colors](#variant-colors)
 
 ## Properties
 
@@ -107,18 +106,24 @@ Use the `icon` slot for external CSS-based icon fonts (Material Symbols, Font Aw
 </snice-alert>
 ```
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `icon` | The icon container |
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/alert/snice-alert';
+```
+
 ```html
 <snice-alert>
   This is a basic alert message.
 </snice-alert>
 ```
 
-```typescript
-import 'snice/components/alert/snice-alert';
-```
-
 ## Examples
 
 ### Basic Alerts
@@ -197,10 +202,10 @@ import 'snice/components/alert/snice-alert';
 
 The `icon` property supports multiple formats:
 - **URLs**: Image files (`/icons/info.svg`)
-- **Emoji**: `🎉`, `💡`
+- **Emoji**: icons like a lightbulb or star
 - **Scheme overrides**: `img://filename` forces `<img>`, `text://content` forces text
 
-> **⚠️ Common mistake:** `icon="lightbulb"` or `icon="info"` renders as **plain text**, not a Material icon. Snice does not bundle Material Symbols. Use the `icon` slot instead.
+> **Common mistake:** `icon="lightbulb"` or `icon="info"` renders as **plain text**, not a Material icon. Snice does not bundle Material Symbols. Use the `icon` slot instead.
 
 ```html
 <!-- Emoji icons -->
@@ -208,9 +213,6 @@ The `icon` property supports multiple formats:
   Congratulations! You've unlocked a new achievement!
 </snice-alert>
 
-<snice-alert variant="info" icon="💡">
-</snice-alert>
-
 <!-- Image URL -->
 <snice-alert variant="info" icon="/icons/info-circle.svg">
   Custom image icon alert.
@@ -248,7 +250,6 @@ The `icon` property supports multiple formats:
 
   <button type="submit">Sign Up</button>
 </form>
-
 ```
 
 ```typescript
@@ -275,7 +276,6 @@ form.addEventListener('submit', (e) => {
     errorAlert.show();
   } else {
     errorAlert.style.display = 'none';
-    // Submit form
   }
 });
 ```
@@ -287,7 +287,6 @@ form.addEventListener('submit', (e) => {
 
 <button onclick="showSuccessAlert()">Show Success</button>
 <button onclick="showErrorAlert()">Show Error</button>
-
 ```
 
 ```typescript
@@ -385,7 +384,6 @@ alert.addEventListener('alert-hidden', () => {
 <button onclick="notify('success', 'File uploaded successfully')">Success</button>
 <button onclick="notify('warning', 'Low disk space')">Warning</button>
 <button onclick="notify('error', 'Connection lost')">Error</button>
-
 ```
 
 ```typescript
@@ -444,7 +442,6 @@ window.notify = (variant, message) => {
 ```typescript
 alert.addEventListener('alert-dismiss', (e) => {
   console.log('User dismissed alert:', e.detail);
-  // Track analytics
   analytics.track('alert_dismissed', {
     variant: e.detail.variant,
     title: e.detail.title
@@ -457,48 +454,10 @@ alert.addEventListener('alert-shown', () => {
 
 alert.addEventListener('alert-hidden', () => {
   console.log('Alert is now hidden');
-  // Clean up or remove from DOM
   alert.remove();
 });
 ```
 
-### API Response Alerts
-
-```html
-<snice-alert style="display: none;"></snice-alert>
-
-<button onclick="makeApiCall()">Make API Call</button>
-```
-
-```typescript
-window.makeApiCall = async () => {
-  try {
-    const response = await fetch('/api/data');
-
-    if (!response.ok) {
-      throw new Error(`HTTP error! status: ${response.status}`);
-    }
-
-    const data = await response.json();
-
-    alert.variant = 'success';
-    alert.title = 'Success!';
-    alert.textContent = 'Data loaded successfully.';
-    alert.dismissible = true;
-    alert.style.display = 'block';
-    alert.show();
-
-  } catch (error) {
-    alert.variant = 'error';
-    alert.title = 'Error';
-    alert.textContent = `Failed to load data: ${error.message}`;
-    alert.dismissible = true;
-    alert.style.display = 'block';
-    alert.show();
-  }
-};
-```
-
 ## Accessibility
 
 - **ARIA role**: `alert` role with `aria-live="polite"` for screen reader announcements
@@ -506,54 +465,3 @@ window.makeApiCall = async () => {
 - **Color contrast**: All variants meet WCAG AA standards
 - **Screen reader friendly**: Content is properly announced
 - **Focus management**: Dismiss button receives proper focus
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
-
-## Common Patterns
-
-### Success Pattern
-```html
-<snice-alert variant="success" title="Success!" dismissible>
-  Your changes have been saved.
-</snice-alert>
-```
-
-### Error Pattern
-```html
-<snice-alert variant="error" title="Error" dismissible>
-  Unable to save changes. Please try again.
-</snice-alert>
-```
-
-### Warning Pattern
-```html
-<snice-alert variant="warning" title="Warning">
-  This action cannot be undone.
-</snice-alert>
-```
-
-### Info Pattern
-```html
-<snice-alert variant="info" title="Information">
-  New features are available in this update.
-</snice-alert>
-```
-
-### Inline Form Validation
-```html
-<snice-alert variant="error" size="small">
-  Please enter a valid email address.
-</snice-alert>
-```
-
-## Variant Colors
-
-| Variant | Color Scheme | Use Case |
-|---------|-------------|----------|
-| `info` | Blue | General information, tips, updates |
-| `success` | Green | Successful operations, confirmations |
-| `warning` | Orange | Cautions, important notices |
-| `error` | Red | Errors, failed operations, critical issues |

package/docs/components/app-tiles.md

@@ -1,59 +1,53 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/app-tiles.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/app-tiles.md -->
 
-# App Tiles Component
+# App Tiles
+`<snice-app-tiles>` & `<snice-app-tile>`
+
+An app launcher grid like Google's app drawer or a phone home screen. Supports material icons, image URLs, emoji, and letter fallbacks with optional badges.
 
 ## Table of Contents
-- [Importing](#importing)
+- [Components](#components)
 - [Properties](#properties)
 - [Events](#events)
+- [Slots](#slots)
 - [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [App Tiles Component](#app-tiles-component)
-- [Icon Resolution Order](#icon-resolution-order)
 
-## Importing
+## Components
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/app-tiles/snice-app-tiles';
-```
+### `<snice-app-tiles>`
+Container element that renders a grid of tiles.
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-app-tiles.min.js"></script>
-```
+### `<snice-app-tile>`
+Declarative child element for defining tiles in HTML.
+
+**Attributes:** `name`, `icon` (URL, emoji, or Material Symbols ligature), `color`, `href`, `badge`
 
 ## Properties
 
+### App Tiles Container
+
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `tiles` | `AppTile[]` | `[]` | Array of tile data objects (programmatic mode) |
+| `tiles` | `AppTile[]` | `[]` | Array of tile data objects (programmatic mode, set via JavaScript) |
 | `columns` | `number` | `4` | Number of grid columns |
 | `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | `'md'` | Tile size |
 | `variant` | `'grid' \| 'list' \| 'compact'` | `'grid'` | Layout variant |
 
 ### AppTile Interface
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Unique identifier |
-| `name` | `string` | Tile label |
-| `icon` | `string` | URL, emoji, or Material Symbols ligature name |
-| `color` | `string?` | Background color for letter/ligature fallback |
-| `href` | `string?` | Navigation URL on click |
-| `badge` | `string?` | Badge content |
-
-### snice-app-tile Attributes
-
-| Attribute | Description |
-|-----------|-------------|
-| `name` | Tile label |
-| `icon` | URL, emoji, or Material Symbols ligature |
-| `color` | Background color |
-| `href` | Navigation URL |
-| `badge` | Badge content |
+```typescript
+interface AppTile {
+  id: string;
+  name: string;
+  icon: string;       // URL, emoji, or Material Symbols ligature name
+  color?: string;     // Background color for letter/ligature fallback
+  href?: string;      // Navigation URL on click
+  badge?: string;     // Badge content
+}
+```
 
 ## Events
 
@@ -61,14 +55,32 @@ import 'snice/components/app-tiles/snice-app-tiles';
 |-------|--------|-------------|
 | `tile-click` | `{ tile: AppTile, index: number }` | Fired when a tile is clicked |
 
+## Slots
+
+### App Tiles Container
+
+| Name | Description |
+|------|-------------|
+| (default) | `<snice-app-tile>` child elements for declarative mode |
+
 ## CSS Custom Properties
 
 | Variable | Description |
 |----------|-------------|
 | `--snice-app-tile-icon-size` | Override icon container width/height. Takes precedence over the `size` attribute. |
 
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `icon` | Material Symbols ligature icon span (inside rendered tiles) |
+
 ## Basic Usage
 
+```typescript
+import 'snice/components/app-tiles/snice-app-tiles';
+```
+
 ```html
 <snice-app-tiles columns="3">
   <snice-app-tile name="Mail" icon="mail" color="rgb(220 38 38)"></snice-app-tile>
@@ -77,10 +89,6 @@ import 'snice/components/app-tiles/snice-app-tiles';
 </snice-app-tiles>
 ```
 
-```typescript
-import 'snice/components/app-tiles/snice-app-tiles';
-```
-
 ## Examples
 
 ### Material Icons
@@ -131,6 +139,17 @@ Use `variant="list"` with `columns="1"` for a vertical list layout.
 </snice-app-tiles>
 ```
 
+### Compact Variant
+
+Use `variant="compact"` for a denser layout with icon and name side by side.
+
+```html
+<snice-app-tiles columns="2" variant="compact">
+  <snice-app-tile name="Dashboard" icon="dashboard" color="rgb(37 99 235)"></snice-app-tile>
+  <snice-app-tile name="Settings" icon="settings" color="rgb(82 82 82)"></snice-app-tile>
+</snice-app-tiles>
+```
+
 ### Sizes
 
 Use the `size` attribute to change tile size. Available sizes: `sm`, `md` (default), `lg`, `xl`, `2xl`.
@@ -166,11 +185,7 @@ Use the `badge` attribute to display a notification badge on a tile.
 <snice-app-tile name="AWS" color="rgb(255 153 0)" badge="!"></snice-app-tile>
 ```
 
-## App Tiles Component
-
-An app launcher grid like Google's app drawer or a phone home screen. Supports material icons, image URLs, emoji, and letter fallbacks with optional badges.
-
-## Icon Resolution Order
+### Icon Resolution Order
 
 1. No icon provided: displays first letter of name on a colored circle
 2. `img://` prefix or URL/path: renders as `<img>` element

package/docs/components/approval-flow.md

@@ -1,28 +1,22 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/approval-flow.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/approval-flow.md -->
 
 # Approval Flow
 `<snice-approval-flow>`
 
 A visual approval chain showing a sequence of approver nodes with avatar, name, role, and status.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/approval-flow/snice-approval-flow';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-approval-flow.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `steps` | `ApprovalStep[]` | `[]` | Array of approver step objects |
+| `steps` | `ApprovalStep[]` | `[]` | Array of approver step objects (set via JavaScript) |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
 | `currentStep` (attr: `current-step`) | `string` | `''` | ID of the active step |
 

package/docs/components/audio-recorder.md

@@ -1,21 +1,30 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/audio-recorder.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/audio-recorder.md -->
 
-# Audio Recorder Component
+# Audio Recorder
+`<snice-audio-recorder>`
 
 Record audio with visualization, pause/resume, and playback.
 
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `autoStart` | `boolean` | `false` | Auto-start recording |
-| `format` | `AudioFormat` | `'audio/webm'` | Output format |
+| `autoStart` (attr: `auto-start`) | `boolean` | `false` | Auto-start recording |
+| `format` | `AudioFormat` | `'audio/webm'` | Output format (`'audio/webm'`, `'audio/ogg'`, `'audio/mp4'`, `'audio/wav'`) |
 | `bitrate` | `number` | `128000` | Audio bitrate (bps) |
-| `showControls` | `boolean` | `true` | Show control buttons |
-| `showVisualizer` | `boolean` | `true` | Show frequency visualizer |
-| `maxDuration` | `number` | `0` | Max duration (seconds, 0=unlimited) |
-| `showTimer` | `boolean` | `true` | Show recording timer |
-| `showPlayback` | `boolean` | `true` | Show playback controls after recording |
+| `showControls` (attr: `show-controls`) | `boolean` | `true` | Show control buttons |
+| `showVisualizer` (attr: `show-visualizer`) | `boolean` | `true` | Show frequency visualizer |
+| `maxDuration` (attr: `max-duration`) | `number` | `0` | Max duration (seconds, 0=unlimited) |
+| `showTimer` (attr: `show-timer`) | `boolean` | `true` | Show recording timer |
+| `showPlayback` (attr: `show-playback`) | `boolean` | `true` | Show playback controls after recording |
 | `recordedUrl` | `string` | `''` | URL of recorded audio (set automatically after stop) |
 
 ## Methods
@@ -36,7 +45,7 @@ Resume paused recording.
 Cancel and discard recording.
 
 ### `getState(): RecorderState`
-Get current state ('inactive', 'recording', 'paused').
+Get current state (`'inactive'`, `'recording'`, `'paused'`).
 
 ### `getDuration(): number`
 Get recording duration in seconds.
@@ -44,25 +53,38 @@ Get recording duration in seconds.
 ### `isRecording(): boolean`
 Check if currently recording.
 
-### `download(filename?): void`
+### `download(filename?: string): void`
 Download recorded audio.
 
 ### `reset(): void`
 Reset recorder state and discard playback.
 
+### AudioRecording Interface
+
+```typescript
+interface AudioRecording {
+  blob: Blob;
+  url: string;
+  duration: number;
+  size: number;
+  format: string;
+  timestamp: number;
+}
+```
+
 ## Events
 
-- `recorder-start` - Recording started
-- `recorder-stop` - Recording stopped
-- `recorder-pause` - Recording paused
-- `recorder-resume` - Recording resumed
-- `recorder-cancel` - Recording cancelled
-- `recorder-error` - Error occurred
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `recorder-start` | `{ recorder }` | Recording started |
+| `recorder-stop` | `{ recorder }` | Recording stopped |
+| `recorder-pause` | `{ recorder }` | Recording paused |
+| `recorder-resume` | `{ recorder }` | Recording resumed |
+| `recorder-cancel` | `{ recorder }` | Recording cancelled |
+| `recorder-error` | `{ recorder, error }` | Error occurred |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
 | Part | Element | Description |
 |------|---------|-------------|
 | `base` | `<div>` | Outer recorder container |
@@ -84,26 +106,22 @@ snice-audio-recorder::part(visualizer) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/audio-recorder/snice-audio-recorder';
+```
+
 ```html
 <snice-audio-recorder id="recorder"></snice-audio-recorder>
 
 <script>
   const recorder = document.getElementById('recorder');
 
-  // Listen for stop event
   recorder.addEventListener('recorder-stop', async () => {
     // Recording complete
   });
 </script>
 ```
 
-## Audio Formats
-
-- `'audio/webm'` - WebM (default)
-- `'audio/ogg'` - Ogg Vorbis
-- `'audio/mp4'` - MP4/AAC
-- `'audio/wav'` - WAV (uncompressed)
-
 ## Examples
 
 ### Basic Recording
@@ -156,27 +174,3 @@ const formData = new FormData();
 formData.append('audio', recording.blob, 'recording.webm');
 await fetch('/upload', { method: 'POST', body: formData });
 ```
-
-## AudioRecording Interface
-
-```typescript
-interface AudioRecording {
-  blob: Blob;
-  url: string;
-  duration: number;
-  size: number;
-  format: string;
-  timestamp: number;
-}
-```
-
-## Security
-
-- Requires HTTPS (or localhost)
-- Requires user permission
-- Permission prompts are browser-controlled
-
-## Browser Support
-
-- Modern browsers with MediaRecorder API
-- Requires microphone hardware

package/docs/components/availability.md

@@ -1,34 +1,40 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/availability.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/availability.md -->
 
-# Availability Component
+# Availability
 `<snice-availability>`
 
 A weekly availability grid for setting recurring time ranges. Users can click or drag to toggle time slots on and off.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/availability/snice-availability';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-availability.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Attribute | Type | Default | Description |
 |----------|-----------|------|---------|-------------|
-| `value` | — | `AvailabilityRange[]` | `[]` | Current availability ranges |
+| `value` | -- | `AvailabilityRange[]` | `[]` | Current availability ranges (set via JavaScript) |
 | `granularity` | `granularity` | `number` | `60` | Slot size in minutes (15, 30, 60) |
 | `startHour` | `start-hour` | `number` | `0` | First hour displayed |
 | `endHour` | `end-hour` | `number` | `24` | Last hour displayed |
 | `format` | `format` | `'12h' \| '24h'` | `'12h'` | Time format for labels |
 | `readonly` | `readonly` | `boolean` | `false` | Prevents editing |
 
+### AvailabilityRange Interface
+
+```typescript
+interface AvailabilityRange {
+  day: number;    // 0=Mon, 1=Tue, 2=Wed, 3=Thu, 4=Fri, 5=Sat, 6=Sun
+  start: string;  // "HH:MM" (24h format)
+  end: string;    // "HH:MM" (24h format)
+}
+```
+
 ## Methods
 
 ### `getAvailability(): AvailabilityRange[]`
@@ -66,14 +72,14 @@ availability.clear();
 ### `availability-change`
 Dispatched when availability changes (after mouse up from drag, or preset/clear action).
 
+**Detail:** `{ value: AvailabilityRange[] }`
+
 ```javascript
 availability.addEventListener('availability-change', (e) => {
   saveToServer(e.detail.value);
 });
 ```
 
-**Detail:** `{ value: AvailabilityRange[] }`
-
 ## CSS Parts
 
 | Part | Element | Description |
@@ -94,6 +100,10 @@ snice-availability::part(header) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/availability/snice-availability';
+```
+
 ```html
 <snice-availability start-hour="8" end-hour="18"></snice-availability>
 ```
@@ -197,33 +207,8 @@ availability.setAvailability(ranges);
 availability.readonly = true; // Display only
 ```
 
-## Interfaces
-
-### AvailabilityRange
-
-```typescript
-interface AvailabilityRange {
-  day: number;    // 0=Mon, 1=Tue, 2=Wed, 3=Thu, 4=Fri, 5=Sat, 6=Sun
-  start: string;  // "HH:MM" (24h format)
-  end: string;    // "HH:MM" (24h format)
-}
-```
-
-## Interaction
-
-- **Click** a cell to toggle it on or off
-- **Click and drag** to paint multiple cells (adds or removes based on first cell's state)
-- **Presets** for quick selection of common patterns
-- Changes emit `availability-change` after mouse release
-
 ## Accessibility
 
-- Keyboard navigation with arrow keys
-- ARIA labels for days and time slots
-- Visual legend for available/unavailable
-- Hours counter in footer
-
-## Browser Support
-
-- Modern browsers with Custom Elements v1 support
-- Mouse interaction for click and drag
+- **Interaction**: Click a cell to toggle, click and drag to paint multiple cells
+- **Visual legend**: Available/unavailable indicator in footer
+- **Hours counter**: Total selected hours displayed in footer