snice 4.28.0 → 4.30.0

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

package/docs/ai/components/banner.md

@@ -9,16 +9,11 @@ variant: 'info'|'success'|'warning'|'error' = 'info';
 position: 'top'|'bottom' = 'top';
 message: string = '';
 dismissible: boolean = true;
-icon: string = '';
-actionText: string = '';
+icon: string = '';                    // emoji, URL, image file
+actionText: string = '';              // attr: action-text
 open: boolean = false;
 ```
 
-## Slots
-
-- `(default)` - Additional content after the message
-- `icon` - Custom icon content (overrides `icon` property and default variant icons)
-
 ## Methods
 
 - `show()` - Show banner
@@ -27,9 +22,14 @@ open: boolean = false;
 
 ## Events
 
-- `banner-open` → `{ banner }`
-- `banner-close` → `{ banner }`
-- `banner-action` → `{ banner }`
+- `banner-open` -> `{ banner }`
+- `banner-close` -> `{ banner }`
+- `banner-action` -> `{ banner }`
+
+## Slots
+
+- `(default)` - Additional content after the message
+- `icon` - Custom icon content (overrides `icon` property and default variant icons)
 
 ## CSS Parts
 
@@ -39,49 +39,32 @@ open: boolean = false;
 - `action` - Action button
 - `close` - Close/dismiss button
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-banner message="This is an info message" open></snice-banner>
 
 <!-- Variants -->
-<snice-banner variant="info" message="Info"></snice-banner>
-<snice-banner variant="success" message="Success"></snice-banner>
-<snice-banner variant="warning" message="Warning"></snice-banner>
-<snice-banner variant="error" message="Error"></snice-banner>
+<snice-banner variant="success" message="Success" open></snice-banner>
+<snice-banner variant="warning" message="Warning" open></snice-banner>
+<snice-banner variant="error" message="Error" open></snice-banner>
 
 <!-- Position -->
-<snice-banner position="top" message="Top banner" open></snice-banner>
 <snice-banner position="bottom" message="Bottom banner" open></snice-banner>
 
 <!-- With action -->
-<snice-banner
-  message="Update available"
-  action-text="Update Now"
-  open
-></snice-banner>
+<snice-banner message="Update available" action-text="Update Now" open></snice-banner>
 
 <!-- Not dismissible -->
-<snice-banner
-  message="Important notice"
-  dismissible="false"
-  open
-></snice-banner>
-
-<!-- ⚠️ icon="update" renders as PLAIN TEXT. Use the icon slot for icon fonts. -->
+<snice-banner message="Important" dismissible="false" open></snice-banner>
 
-<!-- Icon SLOT — for Material Symbols, Font Awesome, SVGs -->
+<!-- Icon SLOT for icon fonts -->
 <snice-banner message="Update available" open>
   <span slot="icon" class="material-symbols-outlined">update</span>
 </snice-banner>
 
-<!-- Icon PROPERTY — for emoji, URLs, image files only -->
+<!-- Icon PROPERTY for emoji/URLs -->
 <snice-banner icon="🎉" message="Celebration!" open></snice-banner>
-<snice-banner icon="/icons/update.svg" message="Update" open></snice-banner>
-
-<!-- API -->
-<snice-banner message="Hello"></snice-banner>
 ```
 
 ```typescript
@@ -90,12 +73,7 @@ banner.hide();
 banner.toggle();
 ```
 
-## Features
+## Accessibility
 
-- 4 variants (info, success, warning, error)
-- Top or bottom positioning
-- Dismissible with close button
-- Optional action button
-- Smooth slide animation
-- Fixed positioning
-- Accessible (role=alert)
+- `role="alert"` on banner container
+- `aria-label="Close"` on dismiss button

package/docs/ai/components/binpack.md

@@ -0,0 +1,89 @@
+# snice-binpack
+
+JS-driven bin-packing layout using the maximal rectangles algorithm. Absolute positioning with transform-based transitions.
+
+## Properties
+
+```typescript
+gap: string = '1rem';                           // spacing between items
+columnWidth: number = 0;                        // grid snap width (0 = no grid) -- attr: column-width
+rowHeight: number = 0;                          // grid snap height (0 = no grid) -- attr: row-height
+horizontal: boolean = false;                    // pack horizontally instead of vertically
+originLeft: boolean = true;                     // false = right-to-left -- attr: origin-left
+originTop: boolean = true;                      // false = bottom-to-top -- attr: origin-top
+transitionDuration: string = '0.4s';            // CSS transition duration -- attr: transition-duration
+stagger: number = 0;                            // ms delay between each item transition
+resize: boolean = true;                         // auto re-layout on container resize
+draggable: boolean = false;                     // enable drag-to-reorder
+dragThrottle: number = 120;                     // ms throttle for drag layout updates -- attr: drag-throttle
+```
+
+## Methods
+
+- `layout()` - Full re-layout
+- `fit(element, x?, y?)` - Position specific item at coordinates, reflow others
+- `reloadItems()` - Re-collect items from DOM
+- `stamp(elements)` - Layout around fixed elements
+- `unstamp(elements)` - Remove stamp constraint
+- `getItemElements()` - Get all layout items
+- `getLayout()` - Returns `BinpackLayout` with item positions/order
+- `setLayout(layout)` - Apply saved layout (reorder, hide/show)
+
+## Events
+
+- `binpack-layout-complete` -> `{ items: HTMLElement[] }`
+- `binpack-fit-complete` -> `{ item: HTMLElement, x: number, y: number }`
+- `binpack-drag-item-positioned` -> `{ item: HTMLElement, x: number, y: number }`
+
+## Slots
+
+- `(default)` - Items to pack (any elements with explicit width/height)
+
+## CSS Custom Properties
+
+- `--binpack-gap` - Gap between items (set via `gap` property)
+- `--binpack-transition-duration` - Transition duration (set via `transition-duration` property)
+
+## CSS Parts
+
+- `base` - The inner container element
+
+## Basic Usage
+
+```html
+<snice-binpack gap="0.5rem">
+  <div style="width:100px;height:100px">A</div>
+  <div style="width:150px;height:80px">B</div>
+  <div style="width:80px;height:120px">C</div>
+</snice-binpack>
+
+<!-- Horizontal mode -->
+<snice-binpack horizontal style="height:300px">
+  <div style="width:100px;height:100px">A</div>
+</snice-binpack>
+
+<!-- Grid-snapped -->
+<snice-binpack column-width="100" row-height="100">
+  <div style="width:80px;height:80px">A</div>
+</snice-binpack>
+
+<!-- Draggable dashboard -->
+<snice-binpack draggable gap="8px" column-width="80" row-height="80">
+  <div style="width:160px;height:160px">Revenue</div>
+  <div style="width:80px;height:80px">CPU</div>
+  <div style="width:160px;height:80px">Orders</div>
+</snice-binpack>
+```
+
+## Drag CSS Classes
+
+- `.binpack-dragging` -- applied during drag (no transition, z-index: 100)
+- `.binpack-positioning` -- applied while animating to final position after drop
+
+## Notes
+
+- Items must have explicit width/height (not auto-sized)
+- Container uses `position: relative`, items get `position: absolute` + `transform`
+- Uses ResizeObserver on container and items for auto re-layout
+- FOUC prevented via `[ready]` attribute gating transitions
+- `contain: layout style` on `:host` (NOT paint -- items use absolute positioning)