snice 4.27.0 → 4.29.0

package/docs/ai/components/key-value.md

@@ -2,7 +2,7 @@
 
 Key-value pair editor for HTTP headers, env vars, config entries. Dual API: declarative `<snice-kv-pair>` children or imperative `setItems()`.
 
-## Elements
+## Components
 
 - `snice-key-value` — Container/editor
 - `snice-kv-pair` — Data container child (no shadow DOM)
@@ -22,7 +22,7 @@ readonly: boolean = false;
 name: string = '';
 variant: 'default'|'compact' = 'default';
 mode: 'edit'|'view' = 'edit';              // view = read-only display
-showCopy: boolean = false;                  // attr: show-copy — copy button in header
+showCopy: boolean = false;                  // attr: show-copy
 value: string;                              // readonly getter — JSON string of items
 ```
 
@@ -34,13 +34,6 @@ value: string = '';
 description: string = '';
 ```
 
-## Events
-
-- `kv-add` → `{ item: KeyValueItem, index: number }`
-- `kv-remove` → `{ item: KeyValueItem, index: number }`
-- `kv-change` → `{ items: KeyValueItem[] }`
-- `kv-copy` → `{ items: KeyValueItem[] }`
-
 ## Methods
 
 - `setItems(items)` - Set items imperatively (ignored in slot mode)
@@ -50,7 +43,26 @@ description: string = '';
 - `getItems()` - Returns non-empty items
 - `focus()` - Focus first key input
 
-## Usage
+## Events
+
+- `kv-add` → `{ item: KeyValueItem, index: number }`
+- `kv-remove` → `{ item: KeyValueItem, index: number }`
+- `kv-change` → `{ items: KeyValueItem[] }`
+- `kv-copy` → `{ items: KeyValueItem[] }`
+
+## Slots
+
+- `(default)` - `<snice-kv-pair>` child elements
+
+## CSS Parts
+
+`base`, `title`, `copy-button`, `rows`, `row`, `key-input`, `value-input`, `description-input`, `delete-button`, `view-row`, `view-key`, `view-value`, `view-desc`, `empty`
+
+## Basic Usage
+
+```typescript
+import 'snice/components/key-value/snice-key-value';
+```
 
 ```html
 <!-- Declarative -->
@@ -77,14 +89,18 @@ kv.addEventListener('kv-change', e => console.log(e.detail.items));
 
 <!-- Compact with descriptions -->
 <snice-key-value variant="compact" show-description></snice-key-value>
+
+<!-- View mode -->
+<snice-key-value mode="view" label="Response Headers">
+  <snice-kv-pair key="Content-Type" value="application/json"></snice-kv-pair>
+</snice-key-value>
 ```
 
 ## Behavior
 
-- **Auto-expand** (default): last row non-empty → new empty row appended
-- **Fixed rows**: `rows="5"` → exactly 5, no delete buttons, no auto-expand
+- **Auto-expand** (default): last row non-empty -> new empty row appended
+- **Fixed rows**: `rows="5"` -> exactly 5, no delete buttons, no auto-expand
 - **Slot precedence**: `<snice-kv-pair>` children override `setItems()`
-- **View mode**: `mode="view"` renders as read-only text (no inputs), empty items hidden
-- **Copy button**: `show-copy` adds clipboard button in header, copies JSON
-- **Form associated**: `value` getter returns `JSON.stringify({key:value,...})`, `setFormValue()` called on every change
-- Delete all rows → one empty row remains
+- **View mode**: `mode="view"` renders as read-only text, empty items hidden
+- **Copy button**: `show-copy` adds clipboard button, copies JSON
+- **Form associated**: `value` getter returns JSON string, `setFormValue()` on every change

package/docs/ai/components/kpi.md

@@ -2,39 +2,48 @@
 
 Key performance indicator display with value, label, trend, sparkline, and sentiment.
 
-> **Note**: `snice-stat` component has been merged into `snice-kpi`.
+> `snice-stat` has been merged into `snice-kpi`.
 
 ## Properties
 
 ```typescript
-label: string = ''                      // Metric label/name
-value: string | number = ''             // Main metric value
-trendValue?: string | number            // attribute: trend-value
-trendData?: number[]                    // Sparkline data array (JS only)
-sentiment?: KpiSentiment                // 'up' | 'down' | 'neutral'
-size: KpiSize = 'medium'                // 'small' | 'medium' | 'large'
-showSparkline: boolean = true           // attribute: show-sparkline
-colorValue: boolean = false             // attribute: color-value
+label: string = '';
+value: string | number = '';
+trendValue?: string | number;          // attr: trend-value
+trendData?: number[];                  // Sparkline data array (JS only, attribute: false)
+sentiment?: KpiSentiment;              // 'up' | 'down' | 'neutral'
+size: KpiSize = 'medium';             // 'small' | 'medium' | 'large'
+showSparkline: boolean = true;         // attr: show-sparkline
+colorValue: boolean = false;           // attr: color-value — apply sentiment color to value
 ```
 
 ## Slots
 
+- `before` - Content before label/value (e.g., icons)
+- `after` - Content after sparkline (e.g., actions)
+
+## CSS Parts
+
+- `container` - Main container
+- `header` - Header section
+- `main` - Main content (label + value)
+- `label` - Label text
+- `value` - Value text
+- `trend` - Trend container
+- `trend-icon` - Trend icon (up/down/neutral arrow)
+- `trend-value` - Trend value text
+- `sparkline` - Sparkline container
+
+## Basic Usage
+
 ```typescript
-before  // Content before label/value (e.g., icons)
-after   // Content after sparkline (e.g., actions)
+import 'snice/components/kpi/snice-kpi';
 ```
 
-## Usage
-
 ```html
 <!-- Basic -->
 <snice-kpi label="Revenue" value="$45,231"></snice-kpi>
 
-<!-- With icon (before slot) -->
-<snice-kpi label="Revenue" value="$45,231">
-  <div slot="before">🏆</div>
-</snice-kpi>
-
 <!-- With trend -->
 <snice-kpi
   label="Monthly Revenue"
@@ -59,9 +68,9 @@ sales.trendData = [20, 25, 22, 30, 28, 35, 32];
 
 ```html
 <!-- Sentiments -->
-<snice-kpi sentiment="up"></snice-kpi>     <!-- Green, ↑ -->
-<snice-kpi sentiment="down"></snice-kpi>   <!-- Red, ↓ -->
-<snice-kpi sentiment="neutral"></snice-kpi> <!-- Gray, → -->
+<snice-kpi sentiment="up"></snice-kpi>     <!-- Green, arrow up -->
+<snice-kpi sentiment="down"></snice-kpi>   <!-- Red, arrow down -->
+<snice-kpi sentiment="neutral"></snice-kpi> <!-- Gray, arrow right -->
 
 <!-- Sizes -->
 <snice-kpi size="small"></snice-kpi>
@@ -71,58 +80,14 @@ sales.trendData = [20, 25, 22, 30, 28, 35, 32];
 <!-- Without sparkline -->
 <snice-kpi show-sparkline="false"></snice-kpi>
 
-<!-- Dashboard grid -->
-<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
-  <snice-kpi
-    id="mrr"
-    label="MRR"
-    value="$127K"
-    trend-value="+22%"
-    sentiment="up">
-  </snice-kpi>
-
-  <snice-kpi
-    id="users"
-    label="Active Users"
-    value="2,345"
-    trend-value="+8.7%"
-    sentiment="up">
-  </snice-kpi>
-
-  <snice-kpi
-    id="churn"
-    label="Churn"
-    value="2.3%"
-    trend-value="+0.8%"
-    sentiment="down">
-  </snice-kpi>
-</div>
-```
-
-```typescript
-mrr.trendData = [100, 110, 105, 120, 115, 130, 127];
-users.trendData = [2000, 2100, 2200, 2250, 2300, 2345];
-churn.trendData = [1.5, 1.8, 2.0, 2.2, 2.1, 2.3];
-```
-
-## CSS Parts
-
-```css
-::part(container)   /* Main container */
-::part(header)      /* Header section */
-::part(main)        /* Main content (label + value) */
-::part(label)       /* Label text */
-::part(value)       /* Value text */
-::part(trend)       /* Trend container */
-::part(trend-icon)  /* Trend icon (↑↓→) */
-::part(trend-value) /* Trend value text */
-::part(sparkline)   /* Sparkline container */
+<!-- With icon slot -->
+<snice-kpi label="Revenue" value="$45,231">
+  <div slot="before">icon here</div>
+</snice-kpi>
 ```
 
-## Notes
+## Accessibility
 
-- Sparkline automatically uses sentiment color (success/danger/muted)
-- Sentiment icons: up=↑, down=↓, neutral=→
-- trendData array automatically renders sparkline
-- Value can be string or number for formatting flexibility
-- showSparkline=false hides sparkline even if data provided
+- Labels provide context for values
+- Sentiment: color + icon differentiation
+- Sufficient color contrast

package/docs/ai/components/layout.md

@@ -2,42 +2,48 @@
 
 Application layout with header navigation, main content area, and footer.
 
+## Methods
+
+- `update(appContext, placards, currentRoute, routeParams)` - Update layout navigation from router state
+
 ## Slots
 
 - `brand` - Logo/brand in header
 - `page` - Main page content
 - `footer` - Footer content
 
-## Methods
+## CSS Parts
 
-- `update(appContext, placards, currentRoute, routeParams)` - Update layout navigation from router state
+- `base` - Outer layout container div
+- `header` - Header element with navigation
+- `brand` - Brand/logo area within header
+- `main` - Main content area
+- `footer` - Footer element
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/layout/snice-layout';
+```
 
 ```html
 <snice-layout>
-  <div slot="brand">
-    <h1>My App</h1>
-  </div>
-  <div slot="page">
-    <!-- Page content -->
-  </div>
-  <div slot="footer">
-    <p>&copy; 2025 My Company</p>
-  </div>
+  <div slot="brand"><h1>My App</h1></div>
+  <div slot="page">Page content</div>
+  <div slot="footer"><p>&copy; 2025 My Company</p></div>
 </snice-layout>
 ```
 
-**CSS Parts:**
-- `base` - Outer layout container div
-- `header` - Header element with navigation
-- `brand` - Brand/logo area within header
-- `main` - Main content area
-- `footer` - Footer element
+## Examples
 
-## Features
+```html
+<!-- Router integration -->
+<snice-layout id="app-layout">
+  <img slot="brand" src="/logo.svg" alt="Logo" />
+  <div slot="page"></div>
+</snice-layout>
+```
 
-- Grid layout: header, main, footer
-- Integrated `snice-nav` in header
-- Router integration via `update()` method
-- Slotted brand, page, and footer areas
+```typescript
+layout.update(appContext, placards, currentRoute, routeParams);
+```

package/docs/ai/components/leaderboard.md

@@ -2,21 +2,22 @@
 
 Ranked list with podium variant, avatars, change indicators. Dual API: declarative children or imperative setter.
 
+## Components
+
+- `<snice-leaderboard>` - Container
+- `<snice-leaderboard-entry>` - Data container child (attrs: `rank`, `name`, `score`, `avatar`, `change`, `highlighted`)
+
 ## Properties
 
 ```ts
-variant: 'default' | 'podium' | 'compact'  // Display variant (default: 'default')
-size: 'small' | 'medium' | 'large'         // Size (default: 'medium')
-title: string                               // Optional header title (default: '')
+variant: 'default'|'podium'|'compact' = 'default';
+size: 'small'|'medium'|'large' = 'medium';
+title: string = '';
 ```
 
 ## Methods
 
-```ts
-setEntries(entries: LeaderboardEntry[]): void  // Set entries imperatively
-```
-
-### LeaderboardEntry
+- `setEntries(entries: LeaderboardEntry[]): void` - Set entries imperatively (slot children take precedence)
 
 ```ts
 interface LeaderboardEntry {
@@ -29,48 +30,38 @@ interface LeaderboardEntry {
 }
 ```
 
-## Slots
-
-- `(default)` - `<snice-leaderboard-entry>` child elements for declarative API
-
-## Child Elements
-
-### `<snice-leaderboard-entry>`
-
-Data container element. Attributes: `rank` (Number), `name` (String), `score` (String), `avatar` (String, optional), `change` (Number, optional), `highlighted` (Boolean).
-
-**Slot children take precedence over `setEntries()`.** When all children removed, falls back to imperative mode.
-
 ## Events
 
-- `entry-click` -> `{ entry: LeaderboardEntry, index: number }` -- Entry clicked
+- `entry-click` → `{ entry: LeaderboardEntry, index: number }`
 
-## Variants
+## Slots
 
-- `default` -- Flat list
-- `podium` -- Top 3 shown as podium, rest as list
-- `compact` -- Tighter spacing, smaller avatars
+- `(default)` - `<snice-leaderboard-entry>` child elements for declarative API
 
 ## CSS Custom Properties
 
 ```css
---leaderboard-bg              /* Background (default: --snice-color-background) */
---leaderboard-text            /* Text color (default: --snice-color-text) */
---leaderboard-text-secondary  /* Secondary text (default: --snice-color-text-secondary) */
---leaderboard-border          /* Border color (default: --snice-color-border) */
---leaderboard-primary         /* Primary accent (default: --snice-color-primary) */
---leaderboard-success         /* Up change color (default: --snice-color-success) */
---leaderboard-danger          /* Down change color (default: --snice-color-danger) */
---leaderboard-bg-element      /* Element background (default: --snice-color-background-element) */
---leaderboard-radius          /* Border radius (default: --snice-border-radius-lg) */
+--leaderboard-bg              /* var(--snice-color-background) */
+--leaderboard-text            /* var(--snice-color-text) */
+--leaderboard-text-secondary  /* var(--snice-color-text-secondary) */
+--leaderboard-border          /* var(--snice-color-border) */
+--leaderboard-primary         /* var(--snice-color-primary) */
+--leaderboard-success         /* var(--snice-color-success) */
+--leaderboard-danger          /* var(--snice-color-danger) */
+--leaderboard-bg-element      /* var(--snice-color-background-element) */
+--leaderboard-radius          /* var(--snice-border-radius-lg) */
 ```
 
-**CSS Parts:** `base`, `title`, `list`, `empty`
+## CSS Parts
+
+- `base` - Outer container
+- `title` - Title heading
+- `list` - Entries list
+- `empty` - Empty state
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Declarative -->
 <snice-leaderboard variant="podium" title="Top Players">
   <snice-leaderboard-entry rank="1" name="Alice" score="2500" change="3" highlighted></snice-leaderboard-entry>
   <snice-leaderboard-entry rank="2" name="Bob" score="2100" change="-1"></snice-leaderboard-entry>

package/docs/ai/components/link-preview.md

@@ -4,7 +4,7 @@ Rich URL preview card with image, title, description, and site info.
 
 ## Properties
 
-```typescript
+```ts
 url: string = '';
 title: string = '';
 description: string = '';
@@ -19,7 +19,17 @@ size: 'small'|'medium'|'large' = 'medium';
 
 - `link-click` → `{ url: string }`
 
-## Usage
+## CSS Parts
+
+- `base` - Outer preview card container
+- `content` - Text content area (title, description, footer)
+- `title` - Title text element
+
+## Basic Usage
+
+```typescript
+import 'snice/components/link-preview/snice-link-preview';
+```
 
 ```html
 <!-- Vertical (default) -->
@@ -37,19 +47,3 @@ size: 'small'|'medium'|'large' = 'medium';
   url="https://example.com" title="Quick Link" description="Short.">
 </snice-link-preview>
 ```
-
-## CSS Parts
-
-- `base` - The outer preview card container
-- `content` - The text content area (title, description, footer)
-- `title` - The title text element
-
-## Features
-
-- Vertical (image top) and horizontal (image left) layouts
-- 3 sizes: small, medium, large
-- Placeholder icon when no image
-- Title clamped to 2 lines, description to 3
-- Domain extracted from URL
-- Click opens URL in new tab (noopener, noreferrer)
-- Keyboard accessible (Enter/Space)

package/docs/ai/components/link.md

@@ -4,7 +4,7 @@ Hyperlink component with variants, external link handling, and hash routing.
 
 ## Properties
 
-```typescript
+```ts
 href: string = '';
 target: '_self'|'_blank'|'_parent'|'_top' = '_self';
 variant: 'default'|'primary'|'secondary'|'muted' = 'default';
@@ -14,24 +14,27 @@ underline: boolean = false;
 hash: boolean = false;        // auto-prepend # to href
 ```
 
-## Slots
-
-- `(default)` - Link text content
-
 ## Events
 
 - `click` → `MouseEvent` (prevented when disabled)
 - `navigate` → `{ href: string }` (hash links only, cancelable)
 
+## Slots
+
+- `(default)` - Link text content
+
 ## CSS Parts
 
 - `link` - Anchor element
 - `external-icon` - External arrow icon
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/link/snice-link';
+```
 
 ```html
-<!-- Basic -->
 <snice-link href="/about">About</snice-link>
 
 <!-- Variants -->

package/docs/ai/components/list.md

@@ -2,9 +2,14 @@
 
 List container with search, infinite scroll, and composable list items.
 
+## Components
+
+- `<snice-list>` - Container with search, infinite scroll, loading
+- `<snice-list-item>` - Individual item with heading, description, slots
+
 ## Properties
 
-```typescript
+```ts
 // snice-list
 dividers: boolean = false;
 searchable: boolean = false;
@@ -22,6 +27,11 @@ selected: boolean = false;
 disabled: boolean = false;
 ```
 
+## Requests
+
+- `list/search` → `{ query, list }` - Handle search (debounced 300ms)
+- `list/load-more` → `{ page, list }` - Infinite scroll pagination
+
 ## Slots (snice-list)
 
 - `(default)` - List items
@@ -36,12 +46,18 @@ disabled: boolean = false;
 - `before` - Icon/avatar area
 - `after` - Badge/metadata area
 
-## Requests
+## CSS Parts (snice-list)
+
+- `container` - Outer list container
+- `search` - Search input wrapper
+- `loading` - Loading skeletons wrapper
+- `sentinel` - Infinite scroll sentinel
 
-- `list/search` → `{ query, list }` - Handle search
-- `list/load-more` → `{ page, list }` - Infinite scroll
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/list/snice-list';
+```
 
 ```html
 <!-- Basic with dividers -->

package/docs/ai/components/location.md

@@ -4,7 +4,7 @@ Display location information with addresses, coordinates, and maps.
 
 ## Properties
 
-```typescript
+```ts
 mode: 'full'|'compact'|'coordinates'|'address' = 'full';
 name: string = '';
 address: string = '';
@@ -22,22 +22,33 @@ mapUrl: string = '';             // attr: map-url
 clickable: boolean = false;
 ```
 
+## Methods
+
+- `getData()` → `LocationData`
+- `getCoordinates()` → `{ latitude, longitude } | null`
+- `getFullAddress()` → `string`
+- `openMap()` → Opens location in maps (new tab)
+
+## Events
+
+- `location-click` → `LocationData` (when clickable)
+
 ## Slots
 
 - `icon` - Custom icon content (overrides `icon`/`iconImage` properties)
 
-## Methods
+## CSS Parts
 
-- `getData()` - Returns LocationData object
-- `getCoordinates()` - Returns `{ latitude, longitude }` or null
-- `getFullAddress()` - Returns formatted address string
-- `openMap()` - Opens location in maps app (new tab)
+- `base` - Outer location container
+- `icon` - Icon container
+- `content` - Content area (name, address, coordinates)
+- `map` - Embedded map container
 
-## Events
-
-- `location-click` → `LocationData` - Clicked (when clickable)
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/location/snice-location';
+```
 
 ```html
 <snice-location
@@ -61,18 +72,3 @@ clickable: boolean = false;
   <span slot="icon" class="material-symbols-outlined">business</span>
 </snice-location>
 ```
-
-**CSS Parts:**
-- `base` - The outer location container
-- `icon` - The icon container
-- `content` - The content area with name, address, coordinates
-- `map` - The embedded map container
-
-## Features
-
-- 4 display modes (full/compact/coordinates/address)
-- Embedded Google Maps support
-- Custom icons (emoji, URL, image). Use slot for icon fonts.
-- Clickable to open in maps app
-- Custom map URL support
-- Complete address formatting

package/docs/ai/components/login.md

@@ -4,7 +4,7 @@ Login form with username/password using @request/@respond pattern.
 
 ## Properties
 
-```typescript
+```ts
 variant: 'default'|'card'|'minimal' = 'default';
 size: 'small'|'medium'|'large' = 'medium';
 title: string = 'Sign In';
@@ -17,11 +17,11 @@ actionText: string = 'Sign In';      // attr: action-text
 
 ## Methods
 
-- `login(credentials?)` - Trigger login via @request (async)
-- `setCredentials({username?, password?, remember?})` - Set form values
-- `reset()` - Clear form, alert, loading
-- `setError(message)` - Show error alert
-- `clearError()` - Clear alert
+- `login(credentials?)` → Trigger login via @request (async)
+- `setCredentials({username?, password?, remember?})` → Set form values
+- `reset()` → Clear form, alert, loading
+- `setError(message)` → Show error alert
+- `clearError()` → Clear alert
 
 ## Requests
 
@@ -29,7 +29,7 @@ actionText: string = 'Sign In';      // attr: action-text
 
 ## Types
 
-```typescript
+```ts
 interface LoginCredentials {
   username: string;
   password: string;
@@ -60,14 +60,19 @@ interface LoginResult {
 - `before-submit`, `after-submit` - Around button
 - `footer` - Footer content
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer login container
 - `header` - Header section
 - `title` - H1 title element
 - `form` - The login form
 - `footer` - Footer section
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/login/snice-login';
+```
 
 ```html
 <!-- With controller -->