snice 4.28.0 → 4.29.0

package/docs/components/kpi.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/kpi.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/kpi.md -->
 
 # KPI Component
 
@@ -12,6 +12,7 @@ A key performance indicator display component for showing metrics with optional
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -19,12 +20,12 @@ A key performance indicator display component for showing metrics with optional
 |----------|------|---------|-------------|
 | `label` | `string` | `''` | Label text (metric name) |
 | `value` | `string \| number` | `''` | Main metric value to display |
-| `trend-value` | `string \| number` | `undefined` | Optional trend value (e.g., "+12.5%") |
-| `trend-data` | `number[]` | `undefined` | Data for sparkline chart |
-| `sentiment` | `KpiSentiment` | `undefined` | Trend sentiment ('up', 'down', 'neutral') |
-| `size` | `KpiSize` | `'medium'` | Component size ('small', 'medium', 'large') |
-| `show-sparkline` | `boolean` | `true` | Whether to show sparkline when data is provided |
-| `color-value` | `boolean` | `false` | Apply sentiment color to main value |
+| `trendValue` (attr: `trend-value`) | `string \| number` | `undefined` | Optional trend value (e.g., "+12.5%") |
+| `trendData` | `number[]` | `undefined` | Data for sparkline chart (set via JavaScript) |
+| `sentiment` | `'up' \| 'down' \| 'neutral'` | `undefined` | Trend sentiment |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Component size |
+| `showSparkline` (attr: `show-sparkline`) | `boolean` | `true` | Whether to show sparkline when data is provided |
+| `colorValue` (attr: `color-value`) | `boolean` | `false` | Apply sentiment color to main value |
 
 ## Slots
 
@@ -33,22 +34,6 @@ A key performance indicator display component for showing metrics with optional
 | `before` | Content displayed before the label/value (e.g., icons) |
 | `after` | Content displayed after sparkline (e.g., additional actions) |
 
-## With Icon (Before Slot)
-
-```html
-<snice-kpi
-  label="Total Revenue"
-  value="$45,231"
-  trend-value="+12%"
-  sentiment="up">
-  <div slot="before" style="display: flex; align-items: center; justify-content: center; width: 2.5rem; height: 2.5rem; background: var(--snice-color-primary-subtle); border-radius: var(--snice-border-radius-md); margin-bottom: var(--snice-spacing-xs);">
-    <svg style="width: 1.5rem; height: 1.5rem; color: var(--snice-color-primary); fill: currentColor;" viewBox="0 0 24 24">
-      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"/>
-    </svg>
-  </div>
-</snice-kpi>
-```
-
 ## CSS Parts
 
 | Part | Description |
@@ -83,6 +68,10 @@ snice-kpi::part(trend) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/kpi/snice-kpi';
+```
+
 ```html
 <snice-kpi
   label="Total Revenue"
@@ -90,7 +79,9 @@ snice-kpi::part(trend) {
 </snice-kpi>
 ```
 
-## With Trend Indicator
+## Examples
+
+### With Trend Indicator
 
 ```html
 <snice-kpi
@@ -101,7 +92,7 @@ snice-kpi::part(trend) {
 </snice-kpi>
 ```
 
-## With Sparkline
+### With Sparkline
 
 ```html
 <snice-kpi
@@ -119,9 +110,24 @@ snice-kpi::part(trend) {
 </script>
 ```
 
-## Examples
+### With Icon (Before Slot)
+
+```html
+<snice-kpi
+  label="Total Revenue"
+  value="$45,231"
+  trend-value="+12%"
+  sentiment="up">
+  <div slot="before" style="display: flex; align-items: center; justify-content: center; width: 2.5rem; height: 2.5rem; background: var(--snice-color-primary-subtle); border-radius: var(--snice-border-radius-md); margin-bottom: var(--snice-spacing-xs);">
+    <svg style="width: 1.5rem; height: 1.5rem; color: var(--snice-color-primary); fill: currentColor;" viewBox="0 0 24 24">
+      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"/>
+    </svg>
+  </div>
+</snice-kpi>
+```
 
 ### Dashboard Metrics
+
 ```html
 <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
   <snice-kpi
@@ -157,6 +163,7 @@ snice-kpi::part(trend) {
 ```
 
 ### Without Sparkline
+
 ```html
 <snice-kpi
   label="Customer Satisfaction"
@@ -167,59 +174,26 @@ snice-kpi::part(trend) {
 </snice-kpi>
 ```
 
-### Complex Metrics
-```html
-<snice-kpi
-  id="nps"
-  label="Net Promoter Score"
-  value="72"
-  trend-value="+4 pts"
-  sentiment="up">
-</snice-kpi>
-
-<snice-kpi
-  id="cac"
-  label="Customer Acquisition Cost"
-  value="$156"
-  trend-value="-5.2%"
-  sentiment="down">
-</snice-kpi>
-```
+### Sentiment Variants
 
-## Features
-
-- **Clear Value Display**: Large, prominent metric value
-- **Icon Support**: Optional icon slot for visual branding
-- **Trend Indicators**: Optional trend value with sentiment icons
-- **Sparkline Integration**: Built-in sparkline chart support
-- **Sentiment Colors**: Visual feedback with up/down/neutral states
-- **Multiple Sizes**: Small, medium, and large variants
-- **Flexible Layout**: Responsive and adaptable to different layouts
-
-## Sentiment Variants
-
-### Up (Positive)
 ```html
+<!-- Up (Positive) -->
 <snice-kpi
   label="Profit Margin"
   value="34.2%"
   trend-value="+3.5%"
   sentiment="up">
 </snice-kpi>
-```
 
-### Down (Attention Needed)
-```html
+<!-- Down (Attention Needed) -->
 <snice-kpi
   label="Churn Rate"
   value="2.3%"
   trend-value="+0.8%"
   sentiment="down">
 </snice-kpi>
-```
 
-### Neutral (Stable)
-```html
+<!-- Neutral (Stable) -->
 <snice-kpi
   label="Market Share"
   value="28.5%"
@@ -228,50 +202,12 @@ snice-kpi::part(trend) {
 </snice-kpi>
 ```
 
-## Sizes
+### Sizes
 
-### Small
 ```html
-<snice-kpi
-  label="Active Users"
-  value="1,234"
-  size="small">
-</snice-kpi>
-```
-
-### Medium (Default)
-```html
-<snice-kpi
-  label="Active Users"
-  value="1,234"
-  size="medium">
-</snice-kpi>
-```
-
-### Large
-```html
-<snice-kpi
-  label="Active Users"
-  value="1,234"
-  size="large">
-</snice-kpi>
-```
-
-## Theming
-
-The component uses these CSS custom properties:
-
-```css
---snice-color-background
---snice-color-border
---snice-color-text
---snice-color-text-secondary
---snice-color-success
---snice-color-danger
---snice-spacing-*
---snice-font-size-*
---snice-font-weight-*
---snice-border-radius-md
+<snice-kpi label="Active Users" value="1,234" size="small"></snice-kpi>
+<snice-kpi label="Active Users" value="1,234" size="medium"></snice-kpi>
+<snice-kpi label="Active Users" value="1,234" size="large"></snice-kpi>
 ```
 
 ## Accessibility
@@ -279,10 +215,3 @@ The component uses these CSS custom properties:
 - Labels provide context for displayed values
 - Sentiment indicators have clear visual differentiation (color + icon)
 - Sufficient color contrast for all text elements
-
-## Performance
-
-- Lightweight component with minimal DOM
-- Efficient sparkline rendering via SVG
-- CSS containment for optimized rendering
-- No external dependencies beyond sparkline component

package/docs/components/layout.md

@@ -1,22 +1,16 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/layout.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/layout.md -->
 
 # Layout
 `<snice-layout>`
 
 Application layout with header navigation, main content area, and footer.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/layout/snice-layout';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-layout.min.js"></script>
-```
+## Table of Contents
+- [Methods](#methods)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Methods
 

package/docs/components/leaderboard.md

@@ -1,10 +1,12 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/leaderboard.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/leaderboard.md -->
 
-# Leaderboard Component
+# Leaderboard
+`<snice-leaderboard>`
 
-The leaderboard component displays a ranked list of entries with optional avatars, change indicators, and podium highlighting. It supports a **dual API**: declarative child elements (`<snice-leaderboard-entry>`) and an imperative `setEntries()` method.
+A ranked list of entries with optional avatars, change indicators, and podium highlighting. Supports a dual API: declarative child elements (`<snice-leaderboard-entry>`) and an imperative `setEntries()` method.
 
 ## Table of Contents
+- [Components](#components)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -12,11 +14,25 @@ The leaderboard component displays a ranked list of entries with optional avatar
 - [CSS Custom Properties](#css-custom-properties)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
-- [Declarative API (Child Elements)](#declarative-api-child-elements)
-- [Imperative API (setEntries)](#imperative-api-setentries)
-- [Variants](#variants)
+- [Examples](#examples)
 - [Accessibility](#accessibility)
 
+## Components
+
+- `<snice-leaderboard>` - The container component
+- `<snice-leaderboard-entry>` - Data container child element (does not render its own shadow DOM)
+
+### Entry Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `rank` | `number` | `0` | Position/rank number |
+| `name` | `string` | `''` | Display name |
+| `score` | `string` | `''` | Score to display |
+| `avatar` | `string` | `''` | URL to avatar image (optional) |
+| `change` | `number` | `0` | Rank change indicator (positive = up, negative = down) |
+| `highlighted` | `boolean` | `false` | Highlight this entry |
+
 ## Properties
 
 | Property | Type | Default | Description |
@@ -27,36 +43,29 @@ The leaderboard component displays a ranked list of entries with optional avatar
 
 ## Methods
 
-### `setEntries(entries: LeaderboardEntry[]): void`
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `setEntries()` | `entries: LeaderboardEntry[]` | Set entries imperatively. Slot children take precedence. |
 
-Set leaderboard entries imperatively. Each entry is an object with these fields:
+### LeaderboardEntry Interface
 
 ```typescript
 interface LeaderboardEntry {
-  rank: number;         // Position number
-  name: string;         // Display name
-  score: number | string; // Score value
-  avatar?: string;      // Avatar image URL
-  change?: number;      // Rank change (positive = up, negative = down)
-  highlighted?: boolean; // Highlight this entry
+  rank: number;
+  name: string;
+  score: number | string;
+  avatar?: string;
+  change?: number;
+  highlighted?: boolean;
 }
 ```
 
 ## Events
 
-### `entry-click`
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `entry-click` | `{ entry: LeaderboardEntry, index: number }` | Fired when a leaderboard entry is clicked |
 
-Fired when a leaderboard entry is clicked.
-
-**Event Detail:**
-```typescript
-{
-  entry: LeaderboardEntry; // The clicked entry data
-  index: number;           // Index of the entry
-}
-```
-
-**Example:**
 ```typescript
 leaderboard.addEventListener('entry-click', (e) => {
   console.log('Clicked:', e.detail.entry.name);
@@ -83,7 +92,7 @@ leaderboard.addEventListener('entry-click', (e) => {
 | `--leaderboard-bg-element` | Element background | `var(--snice-color-background-element)` |
 | `--leaderboard-radius` | Border radius | `var(--snice-border-radius-lg)` |
 
-### CSS Parts
+## CSS Parts
 
 | Part | Description |
 |------|-------------|
@@ -94,6 +103,10 @@ leaderboard.addEventListener('entry-click', (e) => {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/leaderboard/snice-leaderboard';
+```
+
 ```html
 <snice-leaderboard title="Top Players">
   <snice-leaderboard-entry rank="1" name="Alice" score="2500"></snice-leaderboard-entry>
@@ -101,53 +114,23 @@ leaderboard.addEventListener('entry-click', (e) => {
 </snice-leaderboard>
 ```
 
-```typescript
-import 'snice/components/leaderboard/snice-leaderboard';
-```
+## Examples
 
-## Declarative API (Child Elements)
+### Declarative API (Child Elements)
 
-Use `<snice-leaderboard-entry>` elements as children of `<snice-leaderboard>`. Each entry is a data container that the parent reads and renders.
+Use `<snice-leaderboard-entry>` elements as children. The parent reads attributes and renders the full UI.
 
 ```html
 <snice-leaderboard variant="podium" title="Season Rankings">
-  <snice-leaderboard-entry
-    rank="1"
-    name="Alice"
-    score="2,500"
-    avatar="alice.jpg"
-    change="3"
-    highlighted>
-  </snice-leaderboard-entry>
-  <snice-leaderboard-entry
-    rank="2"
-    name="Bob"
-    score="2,100"
-    change="-1">
-  </snice-leaderboard-entry>
-  <snice-leaderboard-entry
-    rank="3"
-    name="Charlie"
-    score="1,800"
-    change="2">
-  </snice-leaderboard-entry>
+  <snice-leaderboard-entry rank="1" name="Alice" score="2,500" avatar="alice.jpg" change="3" highlighted></snice-leaderboard-entry>
+  <snice-leaderboard-entry rank="2" name="Bob" score="2,100" change="-1"></snice-leaderboard-entry>
+  <snice-leaderboard-entry rank="3" name="Charlie" score="1,800" change="2"></snice-leaderboard-entry>
 </snice-leaderboard>
 ```
 
-### Entry Attributes
+### Imperative API (setEntries)
 
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `rank` | `number` | `0` | Position/rank number |
-| `name` | `string` | `''` | Display name |
-| `score` | `string` | `''` | Score to display |
-| `avatar` | `string` | `''` | URL to avatar image (optional) |
-| `change` | `number` | `0` | Rank change indicator (positive = up, negative = down) |
-| `highlighted` | `boolean` | `false` | Highlight this entry |
-
-## Imperative API (setEntries)
-
-For dynamic data (e.g., fetched from an API), use the `setEntries()` method.
+For dynamic data, use the `setEntries()` method. Slot children take precedence when both are used.
 
 ```typescript
 leaderboard.setEntries([
@@ -158,30 +141,23 @@ leaderboard.setEntries([
 ]);
 ```
 
-### Dual API Precedence
-
-When **both** child elements and `setEntries()` are used:
-- Child elements (`<snice-leaderboard-entry>`) take precedence
-- `setEntries()` calls are ignored while child elements are present
-- When all children are removed, `setEntries()` becomes active again
-
-## Variants
+### Variants
 
-### Default
+#### Default
 A flat list of ranked entries.
 
 ```html
 <snice-leaderboard>...</snice-leaderboard>
 ```
 
-### Podium
+#### Podium
 The top 3 entries are displayed in a podium layout (2nd, 1st, 3rd). Remaining entries appear as a regular list below.
 
 ```html
 <snice-leaderboard variant="podium">...</snice-leaderboard>
 ```
 
-### Compact
+#### Compact
 Tighter spacing with smaller avatars, suitable for sidebars or smaller containers.
 
 ```html

package/docs/components/link-preview.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/link-preview.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/link-preview.md -->
 
 # Link Preview
 `<snice-link-preview>`
 
-Displays a rich preview card for a URL with image, title, description, and site info.
+Displays a rich preview card for a URL with image, title, description, and site info. Clicking the card opens the URL in a new tab.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/link-preview/snice-link-preview';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-link-preview.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -26,8 +21,8 @@ import 'snice/components/link-preview/snice-link-preview';
 | `title` | `string` | `''` | Preview title (clamped to 2 lines) |
 | `description` | `string` | `''` | Preview description (clamped to 3 lines) |
 | `image` | `string` | `''` | Preview image URL |
-| `siteName` (attr: `site-name`) | `string` | `''` | Site name in footer |
-| `favicon` | `string` | `''` | Favicon URL in footer |
+| `siteName` (attr: `site-name`) | `string` | `''` | Site name shown in footer |
+| `favicon` | `string` | `''` | Favicon URL shown in footer |
 | `variant` | `'vertical' \| 'horizontal'` | `'vertical'` | Card layout direction |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Card size |
 
@@ -155,3 +150,12 @@ When no image is provided, a placeholder link icon is shown.
   });
 </script>
 ```
+
+## Accessibility
+
+- The card has `role="article"` and `tabindex="0"` for keyboard focus
+- Keyboard activation via Enter or Space keys
+- Images use `loading="lazy"` and empty `alt` attributes (decorative)
+- Title is clamped to 2 lines, description to 3 lines with CSS overflow
+- Focus ring is visible via `:focus-visible` styling
+- Click opens URL in new tab with `noopener,noreferrer`

package/docs/components/link.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/link.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/link.md -->
 
 # Link
 `<snice-link>`
 
 A customizable hyperlink component with variants, external link handling, and hash routing support.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/link/snice-link';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-link.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -26,9 +22,9 @@ import 'snice/components/link/snice-link';
 | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | `'_self'` | Link target |
 | `variant` | `'default' \| 'primary' \| 'secondary' \| 'muted'` | `'default'` | Visual style |
 | `disabled` | `boolean` | `false` | Disables the link |
-| `external` | `boolean` | `false` | Opens in new tab with `noopener noreferrer` |
+| `external` | `boolean` | `false` | Opens in new tab with `noopener noreferrer` and shows arrow icon |
 | `underline` | `boolean` | `false` | Shows text underline |
-| `hash` | `boolean` | `false` | Auto-prepends `#` to href |
+| `hash` | `boolean` | `false` | Auto-prepends `#` to href for SPA routing |
 
 ## Events
 
@@ -45,10 +41,10 @@ import 'snice/components/link/snice-link';
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `link` | The anchor element |
-| `external-icon` | The external link arrow icon |
+| Part | Element | Description |
+|------|---------|-------------|
+| `link` | `<a>` | The anchor element |
+| `external-icon` | `<span>` | The external link arrow icon (visible when `external` is set) |
 
 ## Basic Usage
 
@@ -143,3 +139,10 @@ Links display inline and work naturally within text.
   <snice-link href="https://github.com" external variant="muted">GitHub</snice-link>
 </footer>
 ```
+
+## Accessibility
+
+- Renders a standard `<a>` element inside shadow DOM
+- External links automatically get `rel="noopener noreferrer"` and `target="_blank"`
+- Disabled links prevent click events and use `pointer-events: none` with a `not-allowed` cursor
+- The `navigate` event is cancelable, allowing routers to prevent default browser navigation