snice 4.27.0 → 4.29.0

package/docs/ai/components/app-tiles.md

@@ -1,17 +1,24 @@
-# snice-app-tiles
+# snice-app-tiles & snice-app-tile
 
 App launcher grid like Google's app drawer or a phone home screen.
 
+## Components
+
+### snice-app-tiles
+Container rendering a grid of tiles.
+
+### snice-app-tile
+Declarative child element. Attributes: `name`, `icon`, `color`, `href`, `badge`.
+
 ## Properties
 
 ```typescript
 // snice-app-tiles
-tiles: AppTile[] = [];           // Programmatic tile data
+tiles: AppTile[] = [];           // Programmatic tile data (set via JS)
 columns: number = 4;             // Grid columns
-size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' = 'md'; // Tile size
-variant: 'grid' | 'list' | 'compact' = 'grid'; // Layout variant
+size: 'sm'|'md'|'lg'|'xl'|'2xl' = 'md';
+variant: 'grid'|'list'|'compact' = 'grid';
 
-// AppTile interface
 interface AppTile {
   id: string;
   name: string;
@@ -22,34 +29,23 @@ interface AppTile {
 }
 ```
 
-## Child Element
-
-`<snice-app-tile>` — declarative child for defining tiles in HTML.
-
-- `name` - Tile label
-- `icon` - URL, emoji, or Material Symbols ligature
-- `color` - Background color
-- `href` - Navigation URL
-- `badge` - Badge content
-
 ## Events
 
-- `tile-click` -> `{ tile: AppTile, index: number }`
+- `tile-click` → `{ tile: AppTile, index: number }`
 
-## Icon Resolution
+## Slots
 
-1. No icon -> letter fallback (first char of name, colored circle)
-2. `img://` prefix or URL/path -> `<img>` element
-3. Emoji (no ASCII letters) -> emoji display
-4. ASCII text -> Material Symbols ligature
+- `(default)` - `<snice-app-tile>` child elements for declarative mode
 
 ## CSS Custom Properties
 
-| Variable | Description |
-|----------|-------------|
-| `--snice-app-tile-icon-size` | Override icon container size (e.g. `7rem`) |
+- `--snice-app-tile-icon-size` - Override icon container size (e.g. `7rem`)
+
+## CSS Parts
 
-## Usage
+- `icon` - Material Symbols ligature icon span
+
+## Basic Usage
 
 ```html
 <!-- Declarative -->
@@ -69,20 +65,19 @@ tiles.tiles = [
   { id: '2', name: 'Slack', icon: 'https://example.com/slack.svg' },
 ];
 
-<!-- Letter fallback (no icon) -->
-<snice-app-tiles columns="3">
-  <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
-  <snice-app-tile name="GitHub" color="rgb(82 82 82)"></snice-app-tile>
-</snice-app-tiles>
+// Letter fallback (no icon)
+// <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
 
-<!-- Custom icon size via CSS variable -->
-<snice-app-tiles columns="3" style="--snice-app-tile-icon-size: 7rem">
-  <snice-app-tile name="Gallery" icon="collections" color="rgb(37 99 235)"></snice-app-tile>
-</snice-app-tiles>
+// List variant
+// <snice-app-tiles columns="1" variant="list">
 
-<!-- List variant -->
-<snice-app-tiles columns="1" variant="list">
-  <snice-app-tile name="Dashboard" icon="dashboard"></snice-app-tile>
-  <snice-app-tile name="Settings" icon="settings"></snice-app-tile>
-</snice-app-tiles>
+// Custom icon size
+// <snice-app-tiles style="--snice-app-tile-icon-size: 7rem">
 ```
+
+## Icon Resolution
+
+1. No icon -> letter fallback (first char of name, colored circle)
+2. `img://` prefix or URL/path -> `<img>` element
+3. Emoji (no ASCII letters) -> emoji display
+4. ASCII text -> Material Symbols ligature

package/docs/ai/components/approval-flow.md

@@ -40,7 +40,7 @@ interface ApprovalStep {
 - `actions` - Approve/reject button row
 - `connector` - Line between steps
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-approval-flow current-step="2" orientation="vertical"></snice-approval-flow>

package/docs/ai/components/audio-recorder.md

@@ -5,33 +5,29 @@ Audio recording with visualization and playback.
 ## Properties
 
 ```typescript
-autoStart: boolean = false;
+autoStart: boolean = false;       // attr: auto-start
 format: 'audio/webm'|'audio/ogg'|'audio/mp4'|'audio/wav' = 'audio/webm';
 bitrate: number = 128000;
-showControls: boolean = true;
-showVisualizer: boolean = true;
-maxDuration: number = 0;
-showTimer: boolean = true;
-showPlayback: boolean = true;
-recordedUrl: string = '';          // URL of recorded audio (set after stop)
+showControls: boolean = true;     // attr: show-controls
+showVisualizer: boolean = true;   // attr: show-visualizer
+maxDuration: number = 0;          // attr: max-duration, 0=unlimited
+showTimer: boolean = true;        // attr: show-timer
+showPlayback: boolean = true;     // attr: show-playback
+recordedUrl: string = '';         // URL of recorded audio (set after stop)
 ```
 
 ## Methods
 
-```typescript
-start(): Promise<void>
-stop(): Promise<AudioRecording>
-pause(): void
-resume(): void
-cancel(): void
-getState(): 'inactive'|'recording'|'paused'
-getDuration(): number
-isRecording(): boolean
-download(filename?: string): void
-reset(): void
-```
-
-## AudioRecording
+- `start(): Promise<void>` - Start recording
+- `stop(): Promise<AudioRecording>` - Stop and return recording
+- `pause()` - Pause recording
+- `resume()` - Resume recording
+- `cancel()` - Cancel and discard
+- `getState(): 'inactive'|'recording'|'paused'`
+- `getDuration(): number` - Duration in seconds
+- `isRecording(): boolean`
+- `download(filename?)` - Download recorded audio
+- `reset()` - Reset state and discard playback
 
 ```typescript
 interface AudioRecording {
@@ -46,31 +42,29 @@ interface AudioRecording {
 
 ## Events
 
-- `recorder-start` - Recording started
-- `recorder-stop` - Recording stopped
-- `recorder-pause` - Paused
-- `recorder-resume` - Resumed
-- `recorder-cancel` - Cancelled
-- `recorder-error` - Error
+- `recorder-start` → `{ recorder }` - Recording started
+- `recorder-stop` → `{ recorder }` - Recording stopped
+- `recorder-pause` → `{ recorder }` - Paused
+- `recorder-resume` → `{ recorder }` - Resumed
+- `recorder-cancel` → `{ recorder }` - Cancelled
+- `recorder-error` → `{ recorder, error }` - Error
 
-## Usage
-
-```javascript
-// Start
-await recorder.start();
+## CSS Parts
 
-// Stop and get recording
-const recording = await recorder.stop();
-// { blob, url, duration, size, format, timestamp }
+- `base` - Outer recorder container
+- `controls` - Recording and playback control buttons
+- `visualizer` - Audio frequency visualizer bar container
+- `progress` - Playback progress bar
 
-// Pause/resume
-recorder.pause();
-recorder.resume();
+## Basic Usage
 
-// Cancel
-recorder.cancel();
+```html
+<snice-audio-recorder auto-start format="audio/mp4" bitrate="256000" max-duration="60"></snice-audio-recorder>
+```
 
-// Download
+```javascript
+await recorder.start();
+const recording = await recorder.stop();
 recorder.download('recording.webm');
 
 // Upload
@@ -78,29 +72,3 @@ const formData = new FormData();
 formData.append('audio', recording.blob);
 await fetch('/upload', { method: 'POST', body: formData });
 ```
-
-```html
-<snice-audio-recorder
-  auto-start
-  format="audio/mp4"
-  bitrate="256000"
-  max-duration="60">
-</snice-audio-recorder>
-```
-
-**CSS Parts:**
-- `base` - Outer recorder container div
-- `controls` - Recording and playback control buttons
-- `visualizer` - Audio frequency visualizer bar container
-- `progress` - Playback progress bar
-
-## Features
-
-- MediaRecorder API
-- Real-time visualizer
-- Pause/resume
-- Timer
-- Multiple formats
-- Playback
-- Download
-- Requires HTTPS

package/docs/ai/components/availability.md

@@ -11,11 +11,7 @@ startHour: number = 0;          // attr: start-hour
 endHour: number = 24;           // attr: end-hour
 format: '12h'|'24h' = '12h';
 readonly: boolean = false;
-```
-
-## Interfaces
 
-```typescript
 interface AvailabilityRange {
   day: number;    // 0=Mon, 1=Tue, ..., 6=Sun
   start: string;  // "HH:MM"
@@ -31,51 +27,34 @@ interface AvailabilityRange {
 
 ## Events
 
-- `availability-change` -> `{ value: AvailabilityRange[] }`
+- `availability-change` → `{ value: AvailabilityRange[] }`
 
-## Usage
+## CSS Parts
+
+- `base` - Main container
+- `header` - Header with title and presets
+- `grid` - Availability grid
+
+## Basic Usage
 
 ```html
 <snice-availability start-hour="8" end-hour="18" granularity="30"></snice-availability>
+<snice-availability format="24h"></snice-availability>
+<snice-availability readonly></snice-availability>
 ```
 
 ```typescript
-// Pre-fill
 availability.setAvailability([
   { day: 0, start: '09:00', end: '17:00' },
   { day: 1, start: '09:00', end: '17:00' },
 ]);
-
-// Listen for changes
-availability.addEventListener('availability-change', e => {
-  console.log(e.detail.value);
-});
-
-// Read current state
+availability.addEventListener('availability-change', e => console.log(e.detail.value));
 const ranges = availability.getAvailability();
-
-// Clear all
 availability.clear();
-
-<!-- Readonly display -->
-<snice-availability readonly></snice-availability>
-
-<!-- 24h format -->
-<snice-availability format="24h"></snice-availability>
 ```
 
-**CSS Parts:**
-- `base` - Main container
-- `header` - Header with title and presets
-- `grid` - Availability grid
-
-## Features
+## Accessibility
 
 - Click or drag to toggle cells
 - Presets: Business Hours, Weekdays Only, Clear All
-- Readonly mode
-- 12h/24h time format
-- Configurable granularity (15/30/60 min)
-- Configurable hour range
-- Legend and total hours counter
-- Drag painting (add/remove mode)
+- Visual legend and total hours counter

package/docs/ai/components/avatar-group.md

@@ -5,13 +5,11 @@ Row of overlapping avatars with "+N" overflow indicator.
 ## Properties
 
 ```typescript
-avatars: AvatarGroupItem[] = [];  // Array of avatar data (set via JS property)
-max: number = 5;                   // Max visible before "+N"
+avatars: AvatarGroupItem[] = [];   // Array of avatar data (set via JS)
+max: number = 5;                    // Max visible before "+N"
 size: 'small'|'medium'|'large' = 'medium';
-overlap: number = 8;               // Overlap in px
-```
+overlap: number = 8;                // Overlap in px
 
-```typescript
 interface AvatarGroupItem {
   src?: string;      // Image URL
   initials?: string; // Fallback initials
@@ -20,18 +18,32 @@ interface AvatarGroupItem {
 }
 ```
 
+## Events
+
+- `avatar-click` → `{ avatar: AvatarGroupItem, index: number }`
+- `overflow-click` → `{ remaining: number, avatars: AvatarGroupItem[] }`
+
 ## Slots
 
 - `(default)` - `<snice-avatar>` elements for declarative mode
 
-## Events
+## CSS Parts
 
-- `avatar-click` → `{ avatar: AvatarGroupItem, index: number }`
-- `overflow-click` → `{ remaining: number, avatars: AvatarGroupItem[] }`
+- `base` - The avatar group container
+- `avatar` - Individual avatar buttons
+- `overflow` - The "+N" overflow button
 
-## Usage
+## Basic Usage
 
 ```html
+<!-- Declarative -->
+<snice-avatar-group max="3" size="medium">
+  <snice-avatar name="Alice Johnson"></snice-avatar>
+  <snice-avatar name="Bob Smith" src="/avatars/bob.jpg"></snice-avatar>
+  <snice-avatar name="Carol Williams"></snice-avatar>
+</snice-avatar-group>
+
+<!-- Programmatic -->
 <snice-avatar-group id="group" max="3" size="medium"></snice-avatar-group>
 ```
 
@@ -51,7 +63,8 @@ group.addEventListener('overflow-click', (e) => {
 });
 ```
 
-**CSS Parts:**
-- `base` - The avatar group container
-- `avatar` - Individual avatar buttons
-- `overflow` - The "+N" overflow button
+## Accessibility
+
+- `role="group"` with `aria-label="Avatar group"`
+- Each avatar is a `<button>` with title and aria-label
+- Focus styles on all interactive elements

package/docs/ai/components/avatar.md

@@ -1,42 +1,61 @@
 # snice-avatar
 
-User profile images with fallback initials.
+User profile image with automatic fallback to name-based initials or default person icon.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
 ```typescript
-src: string = '';
-alt: string = '';
-name: string = '';
+src: string = '';                    // Image URL
+alt: string = '';                    // Alt text (falls back to `name`)
+name: string = '';                   // User's name (initials + color generation)
 size: 'xs'|'small'|'medium'|'large'|'xl'|'xxl' = 'medium';
 shape: 'circle'|'square'|'rounded' = 'circle';
-fallbackColor: string = '#ffffff';
-fallbackBackground: string = '';
+fallbackColor: string = '#ffffff';   // attr: fallback-color — text color for initials
+fallbackBackground: string = '';     // attr: fallback-background — overrides auto-color
 ```
 
 ## Methods
 
-- `getInitials(name)` - Extract initials from name
+- `getInitials(name: string): string` - Extract initials from a name string
+
+## CSS Custom Properties
+
+- `--avatar-size` - Avatar dimensions (varies by `size`)
+- `--avatar-bg` - Background color (auto-generated from name)
+- `--avatar-color` - Text/icon color (default: `rgb(255 255 255)`)
+
+## CSS Parts
+
+- `base` - Outer avatar container
+- `image` - The `<img>` element (when loaded)
+- `fallback` - Initials or default icon container
+
+## Basic Usage
 
-## Usage
+```html
+<snice-avatar src="/user.jpg" name="John Doe"></snice-avatar>
+```
+
+## Examples
 
 ```html
-<!-- With image -->
-<snice-avatar
-  src="/user.jpg"
-  alt="John Doe"
-  name="John Doe">
-</snice-avatar>
-
-<!-- Fallback to initials -->
+<!-- Initials fallback (no image) -->
 <snice-avatar name="John Doe"></snice-avatar>
 
+<!-- Default icon (no name or image) -->
+<snice-avatar></snice-avatar>
+
 <!-- Sizes -->
 <snice-avatar name="JD" size="xs"></snice-avatar>
-<snice-avatar name="JD" size="small"></snice-avatar>
-<snice-avatar name="JD" size="medium"></snice-avatar>
 <snice-avatar name="JD" size="large"></snice-avatar>
-<snice-avatar name="JD" size="xl"></snice-avatar>
 <snice-avatar name="JD" size="xxl"></snice-avatar>
 
 <!-- Shapes -->
@@ -44,23 +63,20 @@ fallbackBackground: string = '';
 <snice-avatar name="JD" shape="square"></snice-avatar>
 <snice-avatar name="JD" shape="rounded"></snice-avatar>
 
-<!-- Custom colors -->
-<snice-avatar
-  name="JD"
-  fallback-color="#fff"
-  fallback-background="#3b82f6">
-</snice-avatar>
-```
+<!-- Custom fallback colors -->
+<snice-avatar name="Custom" fallback-color="#fff" fallback-background="#3b82f6"></snice-avatar>
 
-**CSS Parts:**
-- `base` - Outer avatar container
-- `image` - The `<img>` element (when image is loaded)
-- `fallback` - Initials or default icon container
+<!-- Broken image falls back to initials -->
+<snice-avatar src="https://broken-url.com/404.jpg" name="Fallback User"></snice-avatar>
+```
 
-## Features
+### Size Reference
 
-- 6 size options (xs to xxl)
-- 3 shape options
-- Image with fallback to initials
-- Custom fallback colors
-- Auto-extracts initials from name
+| Size | Dimensions | Font Size |
+|------|-----------|-----------|
+| `xs` | 1.5rem (24px) | 0.625rem |
+| `small` | 2rem (32px) | 0.75rem |
+| `medium` | 2.5rem (40px) | 0.875rem |
+| `large` | 3rem (48px) | 1rem |
+| `xl` | 4rem (64px) | 1.25rem |
+| `xxl` | 6rem (96px) | 2rem |

package/docs/ai/components/badge.md

@@ -17,10 +17,6 @@ pulse: boolean = false;
 offset: number = 0;
 ```
 
-## Slots
-
-- `(default)` - Content the badge overlays
-
 ## Methods
 
 - `setBadgeContent(content)` - Set text content
@@ -28,57 +24,50 @@ offset: number = 0;
 - `showDot()` - Switch to dot mode
 - `hide()` - Clear all content
 
-## Usage
+## Slots
+
+- `(default)` - Content the badge overlays
+
+## CSS Parts
+
+- `base` - Outer wrapper element
+- `badge` - The badge indicator element
+
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-badge content="New"></snice-badge>
-
-<!-- Count badge -->
 <snice-badge count="5"></snice-badge>
-
-<!-- Max count (99+) -->
 <snice-badge count="150" max="99"></snice-badge>
-
-<!-- Dot indicator -->
 <snice-badge dot></snice-badge>
 
 <!-- On element -->
-<div style="position: relative; display: inline-block;">
+<snice-badge count="3" variant="error">
   <button>Messages</button>
-  <snice-badge count="3" variant="error"></snice-badge>
-</div>
+</snice-badge>
 
 <!-- Variants -->
 <snice-badge content="New" variant="primary"></snice-badge>
-<snice-badge content="✓" variant="success"></snice-badge>
+<snice-badge content="OK" variant="success"></snice-badge>
 <snice-badge content="!" variant="warning"></snice-badge>
-<snice-badge content="×" variant="error"></snice-badge>
+<snice-badge content="x" variant="error"></snice-badge>
 <snice-badge content="i" variant="info"></snice-badge>
 
 <!-- Positions -->
-<snice-badge count="5" position="top-right"></snice-badge>
 <snice-badge count="5" position="top-left"></snice-badge>
 <snice-badge count="5" position="bottom-right"></snice-badge>
-<snice-badge count="5" position="bottom-left"></snice-badge>
 
 <!-- Inline -->
-<p>Status <snice-badge inline content="Active"></snice-badge></p>
+<p>Status <snice-badge inline content="Active" variant="success"></snice-badge></p>
 
 <!-- Pulse animation -->
 <snice-badge dot pulse variant="error"></snice-badge>
-```
 
-**CSS Parts:**
-- `base` - Outer wrapper element
-- `badge` - The badge indicator element
+<!-- Custom offset -->
+<snice-badge count="5" offset="5">...</snice-badge>
+```
 
-## Features
+## Accessibility
 
-- 6 color variants
-- Count with max limit (shows 99+ style)
-- Dot mode for indicators
-- 4 positioning options
-- Inline or positioned
-- Pulse animation
-- Custom offset
+- `role="status"` for screen reader announcements
+- Descriptive `aria-label` on badge element