snice 2.5.4 → 3.2.0

package/docs/ai/components/kpi.md

@@ -0,0 +1,158 @@
+# snice-kpi
+
+Key performance indicator display with value, label, trend, sparkline, and sentiment.
+
+## Properties
+
+```typescript
+label: string = ''                      // Metric label/name
+value: string | number = ''             // Main metric value
+trendValue?: string | number            // Trend value (e.g., "+12.5%")
+trendData?: number[]                    // Sparkline data array
+sentiment?: KpiSentiment                // 'up' | 'down' | 'neutral'
+size: KpiSize = 'medium'                // 'small' | 'medium' | 'large'
+showSparkline: boolean = true           // Show sparkline when data provided
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-kpi label="Revenue" value="$45,231"></snice-kpi>
+
+<!-- With trend -->
+<snice-kpi
+  label="Monthly Revenue"
+  value="$54,239"
+  trend-value="+12.5%"
+  sentiment="up">
+</snice-kpi>
+
+<!-- With sparkline -->
+<snice-kpi
+  id="sales"
+  label="Weekly Sales"
+  value="$28,450"
+  trend-value="+15.3%"
+  sentiment="up">
+</snice-kpi>
+<script>
+  document.getElementById('sales').trendData = [20, 25, 22, 30, 28, 35, 32];
+</script>
+
+<!-- Sentiments -->
+<snice-kpi sentiment="up"></snice-kpi>     <!-- Green, ↑ -->
+<snice-kpi sentiment="down"></snice-kpi>   <!-- Red, ↓ -->
+<snice-kpi sentiment="neutral"></snice-kpi> <!-- Gray, → -->
+
+<!-- Sizes -->
+<snice-kpi size="small"></snice-kpi>
+<snice-kpi size="medium"></snice-kpi>
+<snice-kpi size="large"></snice-kpi>
+
+<!-- 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>
+<script>
+  document.getElementById('mrr').trendData = [100, 110, 105, 120, 115, 130, 127];
+  document.getElementById('users').trendData = [2000, 2100, 2200, 2250, 2300, 2345];
+  document.getElementById('churn').trendData = [1.5, 1.8, 2.0, 2.2, 2.1, 2.3];
+</script>
+```
+
+## 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 */
+```
+
+## Styling
+
+```css
+--snice-color-background
+--snice-color-border
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-success        /* Up sentiment */
+--snice-color-danger         /* Down sentiment */
+--snice-spacing-xs
+--snice-spacing-sm
+--snice-spacing-md
+--snice-spacing-lg
+--snice-font-size-xs
+--snice-font-size-sm
+--snice-font-size-md
+--snice-font-size-2xl
+--snice-font-size-3xl
+--snice-font-size-4xl
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-font-weight-bold
+--snice-border-radius-md
+```
+
+## Common Patterns
+
+```html
+<!-- Financial metrics -->
+<snice-kpi label="Revenue" value="$127K" trend-value="+22%" sentiment="up"></snice-kpi>
+<snice-kpi label="Costs" value="$45K" trend-value="-5%" sentiment="down"></snice-kpi>
+<snice-kpi label="Profit" value="$82K" trend-value="+35%" sentiment="up"></snice-kpi>
+
+<!-- User metrics -->
+<snice-kpi label="Total Users" value="12,345" trend-value="+234" sentiment="up"></snice-kpi>
+<snice-kpi label="Active Users" value="8,901" trend-value="+156" sentiment="up"></snice-kpi>
+<snice-kpi label="Churn Rate" value="2.3%" trend-value="+0.2%" sentiment="down"></snice-kpi>
+
+<!-- Performance metrics -->
+<snice-kpi label="Response Time" value="245ms" trend-value="-23ms" sentiment="down"></snice-kpi>
+<snice-kpi label="Uptime" value="99.9%" trend-value="±0%" sentiment="neutral"></snice-kpi>
+<snice-kpi label="Error Rate" value="0.12%" trend-value="-0.03%" sentiment="down"></snice-kpi>
+
+<!-- Marketing metrics -->
+<snice-kpi label="Conversion Rate" value="3.24%" trend-value="+0.5%" sentiment="up"></snice-kpi>
+<snice-kpi label="CAC" value="$156" trend-value="-$12" sentiment="down"></snice-kpi>
+<snice-kpi label="LTV" value="$1,245" trend-value="+$87" sentiment="up"></snice-kpi>
+```
+
+## Notes
+
+- 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

package/docs/ai/components/link.md

@@ -0,0 +1,77 @@
+# snice-link
+
+Link component with variants and external link handling.
+
+## Properties
+
+```typescript
+href: string = ''                      // Link URL
+target: LinkTarget = '_self'           // '_self' | '_blank' | '_parent' | '_top'
+variant: LinkVariant = 'default'       // 'default' | 'primary' | 'secondary' | 'muted'
+disabled: boolean = false              // Disable link
+external: boolean = false              // Auto _blank + noopener
+underline: boolean = false             // Show underline
+hash: boolean = false                  // Auto prepend # to href (for hash routing)
+```
+
+## Events
+
+```typescript
+@dispatch('click')     // Emitted on click (prevented if disabled)
+@dispatch('navigate')  // Emitted on hash link click (for router integration)
+                       // detail: { href: string }
+                       // cancelable: true
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-link href="/page">Link text</snice-link>
+
+<!-- External -->
+<snice-link href="https://example.com" external>External</snice-link>
+
+<!-- Variants -->
+<snice-link href="/page" variant="primary">Primary</snice-link>
+<snice-link href="/page" variant="secondary">Secondary</snice-link>
+<snice-link href="/page" variant="muted">Muted</snice-link>
+
+<!-- Underlined -->
+<snice-link href="/page" underline>Underlined link</snice-link>
+
+<!-- Disabled -->
+<snice-link href="/page" disabled>Disabled</snice-link>
+
+<!-- Hash links (for routing) -->
+<snice-link href="home" hash>Home</snice-link>
+<snice-link href="about" hash>About</snice-link>
+<!-- Renders as: <a href="#home">Home</a> -->
+
+<!-- Router integration -->
+<snice-link href="profile" hash @navigate="${handleNavigate}">Profile</snice-link>
+<script>
+  function handleNavigate(e) {
+    console.log('Navigate to:', e.detail.href);
+    // e.preventDefault() in the handler will cancel navigation
+  }
+</script>
+```
+
+## CSS Parts
+
+```css
+::part(link)          /* Anchor element */
+::part(external-icon) /* External icon */
+```
+
+## Styling
+
+```css
+--snice-color-primary
+--snice-color-primary-dark
+--snice-color-text-secondary
+--snice-color-text
+--snice-color-text-muted
+--snice-color-text-disabled
+```

package/docs/ai/components/login.md

@@ -0,0 +1,109 @@
+# snice-login
+
+Login form component with username, password, and optional features.
+
+## Properties
+
+```typescript
+variant: 'default'|'card'|'minimal' = 'default';
+size: 'small'|'medium'|'large' = 'medium';
+title: string = '';
+disabled: boolean = false;
+loading: boolean = false;
+showRememberMe: boolean = false;
+showForgotPassword: boolean = false;
+actionText: string = 'Login';
+```
+
+## Methods
+
+- `login(credentials)` - Programmatic login, returns {success, error?, data?}
+- `reset()` - Clear form
+- `setError(message)` - Display error message
+- `clearError()` - Clear error message
+
+## Events
+
+- `submit` - {username, password, remember}
+- `forgot-password` - User clicked forgot password link
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-login title="Sign In"></snice-login>
+
+<!-- Variants -->
+<snice-login variant="card"></snice-login>
+<snice-login variant="minimal"></snice-login>
+
+<!-- With remember me and forgot password -->
+<snice-login show-remember-me show-forgot-password></snice-login>
+
+<!-- Custom action text -->
+<snice-login action-text="Sign In"></snice-login>
+
+<!-- Loading state -->
+<snice-login loading></snice-login>
+
+<!-- Disabled -->
+<snice-login disabled></snice-login>
+
+<!-- Sizes -->
+<snice-login size="small"></snice-login>
+<snice-login size="medium"></snice-login>
+<snice-login size="large"></snice-login>
+
+<!-- Event handling -->
+<snice-login id="login"></snice-login>
+<script>
+const login = document.querySelector('#login');
+
+login.addEventListener('submit', async (e) => {
+  const {username, password, remember} = e.detail;
+
+  login.loading = true;
+  const result = await fetch('/api/login', {
+    method: 'POST',
+    body: JSON.stringify({username, password})
+  });
+
+  if (!result.ok) {
+    login.setError('Invalid credentials');
+    login.loading = false;
+  } else {
+    window.location = '/dashboard';
+  }
+});
+
+login.addEventListener('forgot-password', () => {
+  window.location = '/forgot-password';
+});
+</script>
+
+<!-- Programmatic login -->
+<script>
+const result = await login.login({
+  username: 'user@example.com',
+  password: 'password123',
+  remember: true
+});
+
+if (result.success) {
+  console.log('Logged in:', result.data);
+} else {
+  console.error('Login failed:', result.error);
+}
+</script>
+```
+
+## Features
+
+- 3 visual variants (default/card/minimal)
+- 3 sizes
+- Optional remember me checkbox
+- Optional forgot password link
+- Loading and disabled states
+- Error message display
+- Programmatic and event-based submission
+- Keyboard accessible (Enter to submit)

package/docs/ai/components/modal.md

@@ -0,0 +1,67 @@
+# snice-modal
+
+Dialog overlay with focus trap, backdrop dismiss, and accessibility.
+
+## Properties
+
+```typescript
+open: boolean = false;                        // Visibility state
+size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
+noBackdropDismiss: boolean = false;           // Prevent backdrop click close
+noEscapeDismiss: boolean = false;             // Prevent Escape key close
+noFocusTrap: boolean = false;                 // Disable focus trapping
+noCloseButton: boolean = false;               // Hide close button
+label: string = '';                           // Accessible label
+```
+
+## Methods
+
+```typescript
+show()   // Open modal
+close()  // Close modal
+```
+
+## Events
+
+```typescript
+'@snice/modal-open'   // { modal }
+'@snice/modal-close'  // { modal }
+```
+
+## Slots
+
+```html
+<snice-modal>
+  <div slot="header">Title</div>
+  <div>Body content</div>
+  <div slot="footer">Actions</div>
+</snice-modal>
+```
+
+## Usage
+
+```html
+<snice-modal id="myModal" label="Confirm">
+  <div slot="header"><h2>Confirm</h2></div>
+  <p>Are you sure?</p>
+  <div slot="footer">
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button onclick="this.closest('snice-modal').close()">OK</button>
+  </div>
+</snice-modal>
+```
+
+```typescript
+const modal = document.querySelector('snice-modal');
+modal.show();
+modal.close();
+```
+
+## Features
+
+- Body scroll lock when open
+- Focus trap with Tab navigation
+- Focus restoration on close
+- Backdrop click to close
+- Escape key to close
+- ARIA attributes (role, aria-modal, aria-label, aria-hidden)

package/docs/ai/components/nav.md

@@ -0,0 +1,76 @@
+# snice-nav
+
+Navigation menu from placard configurations, integrates with Snice routing.
+
+## Properties
+
+```typescript
+variant: 'flat'|'hierarchical'|'grouped' = 'flat';
+orientation: 'horizontal'|'vertical' = 'horizontal';
+isTopLevel: boolean = false;              // Receive context updates
+```
+
+## Methods
+
+```typescript
+update(placards, appContext?, currentRoute?, routeParams?)  // Update nav with placard data
+```
+
+## Placard Structure
+
+```typescript
+interface Placard {
+  name: string;                    // Route identifier
+  title: string;                   // Display text
+  icon?: string;                   // Icon character
+  order?: number;                  // Sort order
+  parent?: string;                 // Parent name (hierarchical)
+  group?: string;                  // Group name (grouped)
+  show?: boolean;                  // Visibility
+  description?: string;            // Accessible label/tooltip
+  tooltip?: string;                // Hover tooltip
+  hotkeys?: string[];              // Keyboard shortcuts
+  helpUrl?: string;                // Help URL
+  searchTerms?: string[];          // Search keywords
+  attributes?: Record<string, any>; // Custom data attributes
+  visibleOn?: Function | Function[]; // Visibility guards
+}
+```
+
+## Usage
+
+```html
+<snice-nav id="nav" variant="flat" orientation="horizontal"></snice-nav>
+```
+
+```typescript
+const nav = document.querySelector('snice-nav');
+const placards = [
+  { name: 'home', title: 'Home', icon: '🏠', order: 0 },
+  { name: 'products', title: 'Products', icon: '📦', order: 1 },
+];
+nav.update(placards, undefined, 'home');
+```
+
+## Variants
+
+- **flat**: Simple list (default)
+- **hierarchical**: Nested with parent-child relationships
+- **grouped**: Organized into labeled groups
+
+## Context Integration
+
+```html
+<snice-nav is-top-level></snice-nav>
+```
+
+Auto-receives placards, routes, and app context from Snice context system.
+
+## Features
+
+- Active route tracking with `.nav__link--active` class
+- `aria-current="page"` on active links
+- `role="navigation"` on container
+- Hotkeys via `data-hotkeys` attribute
+- Custom attributes via placard `attributes` property
+- Conditional visibility via `visibleOn` guards

package/docs/ai/components/pagination.md

@@ -0,0 +1,55 @@
+# snice-pagination
+
+Pagination navigation component.
+
+## Properties
+
+```typescript
+current: number = 1;         // Active page
+total: number = 1;           // Total pages
+siblings: number = 1;        // Pages shown each side of current
+showFirst: boolean = true;   // Show first button
+showLast: boolean = true;    // Show last button
+showPrev: boolean = true;    // Show previous button
+showNext: boolean = true;    // Show next button
+size: 'small'|'medium'|'large' = 'medium';
+variant: 'default'|'rounded'|'text' = 'default';
+```
+
+## Methods
+
+```typescript
+goToPage(page: number)   // Navigate to page
+nextPage()               // Next page
+previousPage()           // Previous page
+firstPage()              // First page
+lastPage()               // Last page
+```
+
+## Events
+
+```typescript
+'@snice/pagination-change' // { page, previousPage }
+```
+
+## Usage
+
+```html
+<snice-pagination current="1" total="10"></snice-pagination>
+```
+
+```typescript
+pagination.addEventListener('@snice/pagination-change', (e) => {
+  console.log(e.detail.page);
+});
+```
+
+## CSS Variables
+
+```css
+--pagination-gap: 4px;
+--pagination-button-size: 32px;
+--pagination-button-padding: 8px;
+--pagination-font-size: 14px;
+--pagination-border-radius: 4px;
+```

package/docs/ai/components/progress.md

@@ -0,0 +1,72 @@
+# snice-progress
+
+Progress indicator with linear or circular display.
+
+## Properties
+
+```typescript
+value: number = 0;
+max: number = 100;
+variant: 'linear'|'circular' = 'linear';
+indeterminate: boolean = false;
+size: 'small'|'medium'|'large' = 'medium';
+color: string = '';
+showLabel: boolean = false;
+label: string = '';
+striped: boolean = false;
+animated: boolean = false;
+```
+
+## Usage
+
+```html
+<!-- Basic linear -->
+<snice-progress value="50"></snice-progress>
+
+<!-- Circular -->
+<snice-progress variant="circular" value="75"></snice-progress>
+
+<!-- Indeterminate (loading) -->
+<snice-progress indeterminate></snice-progress>
+<snice-progress variant="circular" indeterminate></snice-progress>
+
+<!-- With label -->
+<snice-progress value="60" show-label></snice-progress>
+<snice-progress value="60" label="Uploading..."></snice-progress>
+
+<!-- Custom max -->
+<snice-progress value="3" max="10"></snice-progress>
+
+<!-- Striped and animated -->
+<snice-progress value="70" striped></snice-progress>
+<snice-progress value="70" striped animated></snice-progress>
+
+<!-- Custom color -->
+<snice-progress value="80" color="#3b82f6"></snice-progress>
+
+<!-- Sizes -->
+<snice-progress value="50" size="small"></snice-progress>
+<snice-progress value="50" size="medium"></snice-progress>
+<snice-progress value="50" size="large"></snice-progress>
+
+<!-- Dynamic updates -->
+<snice-progress id="prog" value="0"></snice-progress>
+<script>
+const prog = document.querySelector('#prog');
+let val = 0;
+setInterval(() => {
+  val = (val + 10) % 100;
+  prog.value = val;
+}, 500);
+</script>
+```
+
+## Features
+
+- Linear or circular variant
+- Indeterminate mode for unknown progress
+- Optional percentage label or custom text
+- Striped and animated styles
+- Custom color
+- 3 sizes
+- Reactive value updates

package/docs/ai/components/radio.md

@@ -0,0 +1,79 @@
+# snice-radio
+
+Form radio button input with grouping.
+
+## Properties
+
+```typescript
+checked: boolean = false;
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+size: 'small'|'medium'|'large' = 'medium';
+name: string = '';
+value: string = '';
+label: string = '';
+```
+
+## Methods
+
+- `focus()` - Focus radio
+- `blur()` - Blur radio
+- `click()` - Programmatic click
+
+## Events
+
+- `change` - {checked, value, radio}
+
+## Usage
+
+```html
+<!-- Basic radio group -->
+<snice-radio name="color" value="red" label="Red"></snice-radio>
+<snice-radio name="color" value="green" label="Green"></snice-radio>
+<snice-radio name="color" value="blue" label="Blue"></snice-radio>
+
+<!-- Pre-selected -->
+<snice-radio name="size" value="s" label="Small"></snice-radio>
+<snice-radio name="size" value="m" label="Medium" checked></snice-radio>
+<snice-radio name="size" value="l" label="Large"></snice-radio>
+
+<!-- Disabled -->
+<snice-radio label="Unavailable" disabled></snice-radio>
+<snice-radio label="Selected but disabled" checked disabled></snice-radio>
+
+<!-- Required -->
+<snice-radio name="accept" value="yes" label="Accept" required></snice-radio>
+
+<!-- Invalid -->
+<snice-radio label="Invalid option" invalid></snice-radio>
+
+<!-- Sizes -->
+<snice-radio label="Small" size="small"></snice-radio>
+<snice-radio label="Medium" size="medium"></snice-radio>
+<snice-radio label="Large" size="large"></snice-radio>
+
+<!-- Form integration -->
+<form>
+  <snice-radio name="plan" value="free" label="Free"></snice-radio>
+  <snice-radio name="plan" value="pro" label="Pro"></snice-radio>
+  <snice-radio name="plan" value="enterprise" label="Enterprise"></snice-radio>
+</form>
+
+<!-- Event handling -->
+<snice-radio id="rb" name="opt" value="a"></snice-radio>
+<script>
+document.querySelector('#rb').addEventListener('change', (e) => {
+  console.log('Selected:', e.detail.value);
+});
+</script>
+```
+
+## Features
+
+- Form-associated custom element
+- Automatic radio group management by name
+- 3 sizes
+- Keyboard accessible (arrow keys navigate group)
+- Change events
+- Invalid state styling