snice 4.28.0 → 4.30.0

package/docs/ai/components/testimonial.md

@@ -4,22 +4,16 @@ Testimonial/quote card with author info, avatar, star rating, and variant styles
 
 ## Properties
 
-```ts
-quote: string = ''
-author: string = ''
-avatar: string = ''            // URL for author avatar image
-role: string = ''              // e.g. "CEO"
-company: string = ''           // e.g. "Acme Inc" (renders as "role at company")
-rating: number = 0             // 0-5 star rating (0 = hidden)
-variant: 'card' | 'minimal' | 'featured' = 'card'
+```typescript
+quote: string = '';
+author: string = '';
+avatar: string = '';            // URL for author avatar image
+role: string = '';              // e.g. "CEO"
+company: string = '';           // e.g. "Acme Inc" (renders as "role at company")
+rating: number = 0;             // 0-5 star rating (0 = hidden)
+variant: 'card'|'minimal'|'featured' = 'card';
 ```
 
-## Variants
-
-- `card` - Default. Background, border, and shadow
-- `minimal` - Left border accent, no background
-- `featured` - Primary-colored background with inverse text
-
 ## CSS Custom Properties
 
 - `--snice-color-background-element` - Card background (default: `rgb(252 251 249)`)
@@ -29,9 +23,6 @@ variant: 'card' | 'minimal' | 'featured' = 'card'
 - `--snice-color-text-secondary` - Author role color
 - `--snice-color-text-inverse` - Featured variant text (default: `rgb(250 250 250)`)
 - `--snice-color-warning` - Star rating color (default: `rgb(234 179 8)`)
-- `--snice-shadow-sm` - Card shadow
-- `--snice-spacing-lg` - Card padding (default: `1.5rem`)
-- `--snice-border-radius-lg` - Card border radius (default: `0.5rem`)
 
 ## CSS Parts
 
@@ -40,7 +31,7 @@ variant: 'card' | 'minimal' | 'featured' = 'card'
 - `author` - The author info container (avatar, name, role)
 - `stars` - The star rating element
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-testimonial
@@ -53,7 +44,6 @@ variant: 'card' | 'minimal' | 'featured' = 'card'
   variant="card"
 ></snice-testimonial>
 
-<!-- Featured style -->
 <snice-testimonial
   quote="Outstanding experience from start to finish."
   author="John Smith"

package/docs/ai/components/textarea.md

@@ -27,13 +27,6 @@ autoGrow: boolean = false;    // attr: auto-grow
 loading: boolean = false;
 ```
 
-## Events
-
-- `textarea-input` → `{ value, textarea }` - On input
-- `textarea-change` → `{ value, textarea }` - On change
-- `textarea-focus` → `{ textarea }` - On focus
-- `textarea-blur` → `{ textarea }` - On blur
-
 ## Methods
 
 - `focus()` - Focus textarea
@@ -43,21 +36,27 @@ loading: boolean = false;
 - `reportValidity()` - Report validation to user, returns `boolean`
 - `setCustomValidity(message)` - Set custom validation message
 
-## Usage
+## Events
+
+- `textarea-input` -> `{ value, textarea }` - On input
+- `textarea-change` -> `{ value, textarea }` - On change
+- `textarea-focus` -> `{ textarea }` - On focus
+- `textarea-blur` -> `{ textarea }` - On blur
+
+## CSS Parts
+
+- `textarea` - The native textarea element
+- `spinner` - Loading spinner
+- `error-text` - Error message container
+- `helper-text` - Helper text container
+
+## Basic Usage
 
 ```html
 <snice-textarea label="Comments" placeholder="Enter comments"></snice-textarea>
 <snice-textarea variant="filled"></snice-textarea>
-<snice-textarea variant="underlined"></snice-textarea>
-<snice-textarea rows="5"></snice-textarea>
 <snice-textarea auto-grow></snice-textarea>
 <snice-textarea maxlength="500"></snice-textarea>
 <snice-textarea resize="both"></snice-textarea>
-<snice-textarea size="small"></snice-textarea>
-<snice-textarea helper-text="Max 500 characters"></snice-textarea>
 <snice-textarea invalid error-text="Required field"></snice-textarea>
 ```
-
-## CSS Parts
-
-`textarea`, `spinner`, `error-text`, `helper-text`

package/docs/ai/components/theme.md

@@ -1,8 +1,8 @@
 # theme.css
 
-CSS-only design token system. No component — just import the stylesheet.
+CSS-only design token system. No component -- just import the stylesheet.
 
-## Usage
+## Basic Usage
 
 ```html
 <link rel="stylesheet" href="snice/components/theme/theme.css">
@@ -19,7 +19,7 @@ CSS-only design token system. No component — just import the stylesheet.
 <html data-theme="dark">...</html>
 ```
 
-## Tokens
+## CSS Custom Properties
 
 ### Colors
 

package/docs/ai/components/time-picker.md

@@ -1,25 +1,25 @@
 # snice-time-picker
 
-Single time selection with hour/minute/second selectors and AM/PM toggle.
+Single time selection with hour/minute/second selectors and AM/PM toggle. Form-associated.
 
 ## Properties
 
 ```typescript
-value: string = '';                                   // Time string (HH:MM or HH:MM:SS)
+value: string = '';                    // Time string (HH:MM or HH:MM:SS)
 format: '12h'|'24h' = '24h';
 size: 'small'|'medium'|'large' = 'medium';
-step: 1|5|10|15|30 = 15;                             // Minute step
-minTime: string = '';                                 // attribute: min-time
-maxTime: string = '';                                 // attribute: max-time
-showSeconds: boolean = false;                         // attribute: show-seconds
+step: 1|5|10|15|30 = 15;              // Minute step
+minTime: string = '';                  // attr: min-time
+maxTime: string = '';                  // attr: max-time
+showSeconds: boolean = false;          // attr: show-seconds
 disabled: boolean = false;
 readonly: boolean = false;
 loading: boolean = false;
 clearable: boolean = false;
 placeholder: string = '';
 label: string = '';
-helperText: string = '';                              // attribute: helper-text
-errorText: string = '';                               // attribute: error-text
+helperText: string = '';               // attr: helper-text
+errorText: string = '';                // attr: error-text
 required: boolean = false;
 invalid: boolean = false;
 name: string = '';
@@ -33,7 +33,9 @@ variant: 'dropdown'|'inline' = 'dropdown';
 - `clear()` - Clear value
 - `focus()` - Focus input
 - `blur()` - Blur input
-- `checkValidity()` / `reportValidity()` / `setCustomValidity(msg)`
+- `checkValidity()` - Check validation, returns `boolean`
+- `reportValidity()` - Report validation to user, returns `boolean`
+- `setCustomValidity(message)` - Set custom validation message
 
 ## Events
 
@@ -44,33 +46,30 @@ variant: 'dropdown'|'inline' = 'dropdown';
 - `timepicker-close` -> `{ timePicker }`
 - `timepicker-clear` -> `{ timePicker }`
 
-## Usage
+## CSS Parts
 
-```html
-<!-- Basic 24h -->
-<snice-time-picker label="Time"></snice-time-picker>
+- `base` - Wrapper container
+- `label` - Label element
+- `input` - Text input
+- `toggle` - Clock icon button
+- `dropdown` - Dropdown/inline container
+- `hours` - Hours selector column
+- `minutes` - Minutes selector column
+- `seconds` - Seconds selector column
+- `period` - AM/PM selector column
+- `clear` - Clear button
+- `spinner` - Loading spinner
+- `helper-text` - Helper text element
+- `error-text` - Error text element
+
+## Basic Usage
 
-<!-- 12h format -->
+```html
+<snice-time-picker label="Select time"></snice-time-picker>
 <snice-time-picker format="12h" value="14:30"></snice-time-picker>
-
-<!-- With seconds -->
 <snice-time-picker show-seconds value="09:15:30"></snice-time-picker>
-
-<!-- 5-minute steps -->
-<snice-time-picker step="5"></snice-time-picker>
-
-<!-- Min/max constraints -->
-<snice-time-picker min-time="09:00" max-time="17:00"></snice-time-picker>
-
-<!-- Inline (always visible) -->
+<snice-time-picker step="5" min-time="09:00" max-time="17:00"></snice-time-picker>
 <snice-time-picker variant="inline" value="10:00"></snice-time-picker>
-
-<!-- Disabled/readonly -->
-<snice-time-picker disabled value="12:00"></snice-time-picker>
-<snice-time-picker readonly value="15:30"></snice-time-picker>
-
-<!-- Event handling -->
-<snice-time-picker></snice-time-picker>
 ```
 
 ```typescript
@@ -78,21 +77,3 @@ picker.addEventListener('time-change', (e) => {
   console.log('Time:', e.detail.value, e.detail.formatted);
 });
 ```
-
-## CSS Parts
-
-`base`, `label`, `input`, `toggle`, `dropdown`, `hours`, `minutes`, `seconds`, `period`, `clear`, `spinner`, `helper-text`, `error-text`
-
-## Features
-
-- Form-associated custom element
-- Hour/minute/second scrollable columns
-- AM/PM toggle for 12h format
-- Dropdown or inline variant
-- 3 sizes (small, medium, large)
-- Loading state with spinner
-- Clearable with clear button
-- Min/max time constraints
-- Configurable minute step (1, 5, 10, 15, 30)
-- Constraint Validation API (checkValidity, reportValidity, setCustomValidity)
-- Keyboard accessible

package/docs/ai/components/time-range-picker.md

@@ -18,12 +18,6 @@ disabled: boolean = false;
 interface TimeRange { start: string; end: string; }
 ```
 
-## Events
-
-- `time-range-change` → `{ ranges, component }`
-- `time-range-select` → `{ start, component }` - Drag begins
-- `time-range-complete` → `{ range, ranges, component }` - Drag ends
-
 ## Methods
 
 - `getSelectedRanges()` - Returns TimeRange[]
@@ -31,22 +25,29 @@ interface TimeRange { start: string; end: string; }
 - `clearSelection()` - Clear all selections
 - `isSlotDisabled(time)` - Check if time slot is disabled
 
+## Events
+
+- `time-range-change` -> `{ ranges, component }`
+- `time-range-select` -> `{ start, component }` - Drag begins
+- `time-range-complete` -> `{ range, ranges, component }` - Drag ends
+
 ## CSS Parts
 
 - `base` - The outer wrapper container
 - `header` - The header with label and selected value display
 - `slots` - The time slots container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-time-range-picker start-time="08:00" end-time="18:00"></snice-time-range-picker>
-<snice-time-range-picker granularity="30" format="12h"></snice-time-range-picker>
-<snice-time-range-picker multiple></snice-time-range-picker>
-<snice-time-range-picker
-  disabled-ranges='[{"start":"12:00","end":"13:00"}]'>
-</snice-time-range-picker>
-<snice-time-range-picker
-  value='[{"start":"09:00","end":"11:00"}]'>
-</snice-time-range-picker>
+<snice-time-range-picker granularity="30" format="12h" multiple></snice-time-range-picker>
+<snice-time-range-picker disabled-ranges='[{"start":"12:00","end":"13:00"}]'></snice-time-range-picker>
+<snice-time-range-picker value='[{"start":"09:00","end":"11:00"}]'></snice-time-range-picker>
+```
+
+```typescript
+picker.setSelectedRanges([{ start: '09:00', end: '11:00' }]);
+const ranges = picker.getSelectedRanges();
+picker.clearSelection();
 ```

package/docs/ai/components/timeline.md

@@ -1,6 +1,6 @@
 # snice-timeline
 
-Displays chronological events with markers.
+Displays chronological events with markers, timestamps, and descriptions.
 
 ## Properties
 
@@ -30,7 +30,7 @@ interface TimelineItem {
 - `title` - Title text
 - `description` - Description text
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-timeline></snice-timeline>
@@ -39,11 +39,12 @@ interface TimelineItem {
 ```typescript
 timeline.items = [
   { timestamp: '2024-01-15', title: 'Created', description: 'Project started', variant: 'success' },
-  { timestamp: '2024-02-01', title: 'Review', description: 'In review', variant: 'warning', icon: '📋' },
-  { timestamp: '2024-03-01', title: 'Launch', description: 'Deployed', variant: 'info', icon: '🚀' }
+  { timestamp: '2024-02-01', title: 'Review', description: 'In review', variant: 'warning', icon: '!' },
+  { timestamp: '2024-03-01', title: 'Launch', description: 'Deployed', variant: 'info' }
 ];
 ```
 
+```html
 <snice-timeline position="alternate"></snice-timeline>
 <snice-timeline position="right"></snice-timeline>
 <snice-timeline orientation="horizontal"></snice-timeline>

package/docs/ai/components/timer.md

@@ -10,13 +10,6 @@ initialTime: number = 0;   // attr: initial-time, seconds (for timer mode)
 running: boolean;           // read-only
 ```
 
-## Events
-
-- `timer-start` → `{ timer, time }`
-- `timer-stop` → `{ timer, time }`
-- `timer-reset` → `{ timer, time }`
-- `timer-complete` → `{ timer }` - Countdown reached 0
-
 ## Methods
 
 - `start()` - Start timer
@@ -24,13 +17,20 @@ running: boolean;           // read-only
 - `reset()` - Reset to initial state
 - `getTime()` - Get current time in seconds
 
+## Events
+
+- `timer-start` -> `{ timer, time }`
+- `timer-stop` -> `{ timer, time }`
+- `timer-reset` -> `{ timer, time }`
+- `timer-complete` -> `{ timer }` - Countdown reached 0
+
 ## CSS Parts
 
 - `base` - The outer timer container
 - `display` - The time display element
 - `controls` - The start/stop/reset button container
 
-## Usage
+## Basic Usage
 
 ```html
 <!-- Stopwatch (counts up) -->

package/docs/ai/components/toast.md

@@ -2,6 +2,17 @@
 
 Temporary notification system with static API.
 
+## Components
+
+- `<snice-toast-container>` - Positions and manages toasts
+- `<snice-toast>` - Individual toast notification
+
+## snice-toast-container
+
+```typescript
+position: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' = 'bottom-center';
+```
+
 ## snice-toast
 
 ```typescript
@@ -11,17 +22,6 @@ closable: boolean = true;
 icon: boolean = true;
 ```
 
-**CSS Parts (snice-toast):**
-- `base` - Outer toast div (has type modifier class)
-- `icon` - Icon span wrapper
-- `content` - Message text span
-
-## snice-toast-container
-
-```typescript
-position: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' = 'bottom-center';
-```
-
 ## Static API
 
 ```typescript
@@ -49,17 +49,23 @@ interface ToastOptions {
 }
 ```
 
-## Events (snice-toast)
-
-- `close-toast` → `{ id: string }` - Close button clicked
-
-## Container Methods
+## Methods (container instance)
 
 - `show(message, options?)` - Show toast, returns ID
 - `hide(id)` - Hide specific toast
 - `clear()` - Remove all toasts
 
-## Usage
+## Events (snice-toast)
+
+- `close-toast` -> `{ id: string }` - Close button clicked
+
+## CSS Parts (snice-toast)
+
+- `base` - Outer toast div (has type modifier class)
+- `icon` - Icon span wrapper
+- `content` - Message text span
+
+## Basic Usage
 
 ```typescript
 Toast.success('Saved successfully');
@@ -68,7 +74,7 @@ Toast.warning('Low disk space');
 
 Toast.show('Custom', { type: 'success', duration: 5000, position: 'top-right' });
 
-const id = Toast.info('Loading...', { duration: 0 });
+const id = await Toast.info('Loading...', { duration: 0 });
 await operation();
 Toast.hide(id);
 ```

package/docs/ai/components/tooltip.md

@@ -18,24 +18,25 @@ zIndex: number = 10000;          // attr: z-index
 strictPositioning: boolean = false; // attr: strict-positioning
 ```
 
+## Methods
+
+- `show()` - Show tooltip
+- `hide()` - Hide tooltip
+- `toggle()` - Toggle visibility
+- `updatePosition()` - Recalculate position
+
 ## Slots
 
 - `(default)` - Trigger element the tooltip attaches to
 
-**CSS Parts:**
+## CSS Parts
+
 - `trigger` - Wrapper around the slot/trigger content
 - `tooltip` - The tooltip popup div
 - `content` - Text content inside tooltip
 - `arrow` - Arrow element
 
-## Methods
-
-- `show()` - Show tooltip
-- `hide()` - Hide tooltip
-- `toggle()` - Toggle visibility
-- `updatePosition()` - Recalculate position
-
-## Usage
+## Basic Usage
 
 ```html
 <snice-tooltip content="Tooltip text">
@@ -63,17 +64,9 @@ strictPositioning: boolean = false; // attr: strict-positioning
 tip.open = true;
 ```
 
-```html
-<snice-tooltip content="Delayed" delay="500" hide-delay="200">
-  <button>Wait</button>
-</snice-tooltip>
-```
-
 ## Attribute-Based Tooltips
 
-Observer for `tooltip` attribute on any element. No wrapper element — safe inside strict-children components (tabs, accordion, etc.). Auto-activates when the tooltip component is loaded.
-
-### Usage
+Observer for `tooltip` attribute on any element. No wrapper element -- safe inside strict-children components (tabs, accordion, etc.). Auto-activates when the tooltip component is loaded.
 
 ```html
 <button tooltip="Save changes">Save</button>
@@ -108,7 +101,3 @@ Observer for `tooltip` attribute on any element. No wrapper element — safe ins
 | `--tooltip-padding` | `8px 12px` | Content padding |
 | `--tooltip-radius` | `6px` | Border radius |
 | `--tooltip-font-size` | `14px` | Font size |
-
-### Cleanup
-
-The tooltip observer is managed automatically by the tooltip component. It activates as a side effect when any `<snice-tooltip>` component is loaded and cleans up when no longer needed.

package/docs/ai/components/tree.md

@@ -30,14 +30,6 @@ interface TreeNode {
 }
 ```
 
-## Events
-
-- `tree-node-expand` → `{ nodeId, node, tree }`
-- `tree-node-collapse` → `{ nodeId, node, tree }`
-- `tree-node-select` → `{ nodeId, node, selectedNodes, tree }`
-- `tree-node-check` → `{ nodeId, node, checked, checkedNodes, tree }`
-- `tree-node-lazy-load` → `{ nodeId, node, tree }`
-
 ## Methods
 
 - `expandNode(id)` / `collapseNode(id)` / `toggleNode(id)`
@@ -49,6 +41,14 @@ interface TreeNode {
 - `getCheckedNodes()` - Get checked nodes
 - `updateNode(id, updates)` - Update node properties
 
+## Events
+
+- `tree-node-expand` -> `{ nodeId, node, tree }`
+- `tree-node-collapse` -> `{ nodeId, node, tree }`
+- `tree-node-select` -> `{ nodeId, node, selectedNodes, tree }`
+- `tree-node-check` -> `{ nodeId, node, checked, checkedNodes, tree }`
+- `tree-node-lazy-load` -> `{ nodeId, node, tree }`
+
 ## CSS Parts
 
 - `container` - Main tree container
@@ -58,7 +58,7 @@ interface TreeNode {
 
 - `--tree-max-height` - Maximum height of tree (default: `100%`)
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-tree selection-mode="single"></snice-tree>

package/docs/ai/components/treemap.md

@@ -21,19 +21,26 @@ interface TreemapNode {
 }
 ```
 
-## Events
-
-- `treemap-click` → `{ node, depth }`
-- `treemap-hover` → `{ node, depth } | null`
-- `treemap-drill` → `{ node, path }`
-
 ## Methods
 
 - `drillDown(node)` - Drill into node's children
 - `drillUp()` - Go back one level
 - `drillToRoot()` - Reset to root
 
-## Usage
+## Events
+
+- `treemap-click` -> `{ node, depth }`
+- `treemap-hover` -> `{ node, depth } | null`
+- `treemap-drill` -> `{ node, path }`
+
+## CSS Parts
+
+- `breadcrumbs` - Breadcrumb navigation for drill-down
+- `base` - Main treemap container
+- `chart` - Chart rendering area
+- `tooltip` - Hover tooltip element
+
+## Basic Usage
 
 ```html
 <snice-treemap show-labels show-values style="height: 400px;"></snice-treemap>
@@ -55,9 +62,3 @@ treemap.data = {
   ]
 };
 ```
-
-**CSS Parts:**
-- `breadcrumbs` - Breadcrumb navigation for drill-down
-- `base` - Main treemap container
-- `chart` - Chart rendering area
-- `tooltip` - Hover tooltip element

package/docs/ai/components/user-card.md

@@ -17,23 +17,33 @@ status: 'online'|'away'|'offline'|'busy' = 'offline';
 variant: 'card'|'horizontal'|'compact' = 'card';
 ```
 
-## Slots
+## Methods
 
-- `(default)` - Action buttons (e.g. Follow, Message)
+- `emitActionClick(action: string)` - Dispatch action-click event programmatically
 
 ## Events
 
 - `social-click` -> `{ platform: string, url: string }`
 - `action-click` -> `{ action: string }`
 
-## Methods
+## Slots
 
-- `emitActionClick(action: string)` - Dispatch action-click event programmatically
+- `(default)` - Action buttons (e.g. Follow, Message)
+
+## CSS Parts
+
+- `base` - Outer container
+- `avatar` - Avatar wrapper
+- `status` - Status indicator dot
+- `name` - Name heading
+- `role` - Role/company text
+- `contact` - Contact info section
+- `social` - Social links row
+- `actions` - Actions slot wrapper
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic card -->
 <snice-user-card
   name="Sarah Johnson"
   role="Engineer"
@@ -44,17 +54,14 @@ variant: 'card'|'horizontal'|'compact' = 'card';
   status="online"
 ></snice-user-card>
 
-<!-- Horizontal layout -->
 <snice-user-card variant="horizontal" name="Alex" role="CTO" status="online">
   <button>Message</button>
 </snice-user-card>
 
-<!-- Compact (list item) -->
 <snice-user-card variant="compact" name="Lisa" role="Dev" status="away"></snice-user-card>
 ```
 
 ```javascript
-// Set social links (array property)
 card.social = [
   { platform: 'github', url: 'https://github.com/user' },
   { platform: 'twitter', url: 'https://twitter.com/user' },
@@ -62,22 +69,9 @@ card.social = [
 ];
 ```
 
-## CSS Parts
-
-- `base` - Outer container
-- `avatar` - Avatar wrapper
-- `status` - Status indicator dot
-- `name` - Name heading
-- `role` - Role/company text
-- `contact` - Contact info section
-- `social` - Social links row
-- `actions` - Actions slot wrapper
-
-## Features
+## Accessibility
 
-- 3 layout variants (card/horizontal/compact)
-- Avatar with initials fallback
-- Status indicator (online/away/offline/busy)
-- Contact info with icons (email, phone, location)
-- Social link icons (github, twitter, linkedin, facebook, instagram, youtube, website)
-- Slotted action buttons
+- Avatar fallback uses initials from name
+- Status indicator has `role="img"` and `aria-label`
+- Social links have `aria-label` and `title`
+- Email/phone rendered as accessible links