snice 4.28.0 → 4.30.0

package/docs/ai/components/video-player.md

@@ -4,18 +4,18 @@ Full-featured video player with custom controls, keyboard shortcuts, PiP, and fu
 
 ## Properties
 
-```ts
-src: string = ''
-poster: string = ''
-autoplay: boolean = false
-muted: boolean = false
-loop: boolean = false
-controls: boolean = true
-playbackRate: number = 1       // attribute: playback-rate
-currentTime: number = 0        // attribute: current-time
-volume: number = 1             // 0-1
-variant: 'default' | 'minimal' | 'cinema' = 'default'
-readonly duration: number      // read-only, set from video metadata
+```typescript
+src: string = '';
+poster: string = '';
+autoplay: boolean = false;
+muted: boolean = false;
+loop: boolean = false;
+controls: boolean = true;
+playbackRate: number = 1;       // attr: playback-rate
+currentTime: number = 0;        // attr: current-time
+volume: number = 1;             // 0-1
+variant: 'default'|'minimal'|'cinema' = 'default';
+duration: number;               // read-only
 ```
 
 ## Methods
@@ -23,42 +23,28 @@ readonly duration: number      // read-only, set from video metadata
 - `play()` - Start playback (async)
 - `pause()` - Pause playback
 - `toggle()` - Toggle play/pause
-- `seekTo(time: number)` - Seek to time in seconds
+- `seekTo(time)` - Seek to time in seconds
 - `requestFullscreen()` - Enter fullscreen (async)
 - `exitFullscreen()` - Exit fullscreen (async)
 - `requestPictureInPicture()` - Toggle picture-in-picture (async)
-- `setPlaybackRate(rate: number)` - Set playback speed
-
-## Slots
-
-- `default` - `<source>` elements for multiple formats
+- `setPlaybackRate(rate)` - Set playback speed
 
 ## Events
 
-- `video-play` -> `{ player: SniceVideoPlayerElement }`
-- `video-pause` -> `{ player: SniceVideoPlayerElement }`
-- `video-ended` -> `{ player: SniceVideoPlayerElement }`
-- `video-time-update` -> `{ player: SniceVideoPlayerElement; currentTime: number; duration: number }`
-- `video-fullscreen-change` -> `{ player: SniceVideoPlayerElement; fullscreen: boolean }`
-- `video-volume-change` -> `{ player: SniceVideoPlayerElement; volume: number; muted: boolean }`
-
-## Keyboard Shortcuts
-
-- Space/K: Toggle play/pause
-- F: Toggle fullscreen
-- M: Toggle mute
-- ArrowRight/ArrowLeft: Seek forward/backward 5s
-- ArrowUp/ArrowDown: Volume up/down 10%
+- `video-play` -> `{ player }`
+- `video-pause` -> `{ player }`
+- `video-ended` -> `{ player }`
+- `video-time-update` -> `{ player, currentTime, duration }`
+- `video-fullscreen-change` -> `{ player, fullscreen }`
+- `video-volume-change` -> `{ player, volume, muted }`
 
-## Variants
+## Slots
 
-- `default` - Full controls, progress bar, PiP, rate selector
-- `minimal` - Simplified controls, no rate/PiP buttons
-- `cinema` - Larger controls, no border radius, box shadow
+- `(default)` - `<source>` elements for multiple formats
 
 ## CSS Custom Properties
 
-- `--snice-video-overlay-bg` - Video background color (default: `rgb(0 0 0)`)
+- `--snice-video-overlay-bg` - Video background (default: `rgb(0 0 0)`)
 - `--snice-video-overlay-alpha` - Overlay with alpha (default: `rgb(0 0 0 / 0.5)`)
 - `--snice-video-controls-color` - Controls text/icon color (default: `rgb(255 255 255)`)
 - `--snice-video-controls-hover-bg` - Button hover background (default: `rgb(255 255 255 / 0.15)`)
@@ -77,31 +63,28 @@ readonly duration: number      // read-only, set from video metadata
 - `--snice-focus-ring-width` - Button focus ring width
 - `--snice-focus-ring-color` - Button focus ring color
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer container element
 - `video` - The `<video>` element
 - `controls` - Control bar container
 - `progress` - Progress track element
 
-## Usage
+## Keyboard Navigation
+
+- Space/K: Toggle play/pause
+- F: Toggle fullscreen
+- M: Toggle mute
+- ArrowRight/ArrowLeft: Seek forward/backward 5s
+- ArrowUp/ArrowDown: Volume up/down 10%
+
+## Basic Usage
 
 ```html
-<snice-video-player
-  src="video.mp4"
-  poster="poster.jpg"
-  controls
-></snice-video-player>
+<snice-video-player src="video.mp4" poster="poster.jpg"></snice-video-player>
 
-<!-- Multiple sources -->
 <snice-video-player poster="poster.jpg">
   <source src="video.webm" type="video/webm">
   <source src="video.mp4" type="video/mp4">
 </snice-video-player>
 ```
-
-```typescript
-player.addEventListener('video-ended', () => {
-  console.log('Video finished');
-});
-player.play();
-```

package/docs/ai/components/virtual-scroller.md

@@ -29,7 +29,7 @@ interface VirtualScrollerItem {
 
 - `base` - The outer scroller container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-virtual-scroller style="height: 400px;" item-height="60"></snice-virtual-scroller>

package/docs/ai/components/waterfall.md

@@ -4,24 +4,24 @@ Waterfall chart (bridge chart) showing cumulative effect of sequential positive/
 
 ## Properties
 
-```ts
-data: WaterfallDataPoint[] = []
-orientation: 'vertical' | 'horizontal' = 'vertical'
-showValues: boolean = true     // attribute: show-values
-showConnectors: boolean = true // attribute: show-connectors
-animated: boolean = false
+```typescript
+data: WaterfallDataPoint[] = [];
+orientation: 'vertical'|'horizontal' = 'vertical';
+showValues: boolean = true;     // attr: show-values
+showConnectors: boolean = true; // attr: show-connectors
+animated: boolean = false;
 
 interface WaterfallDataPoint {
-  label: string
-  value: number
-  type?: 'increase' | 'decrease' | 'total'  // auto-detected from value sign if omitted
+  label: string;
+  value: number;
+  type?: 'increase'|'decrease'|'total';  // auto-detected from value sign if omitted
 }
 ```
 
 ## Events
 
-- `bar-click` → `{ item: WaterfallDataPoint; index: number }` — bar clicked
-- `bar-hover` → `{ item: WaterfallDataPoint; index: number }` — bar hovered
+- `bar-click` -> `{ item: WaterfallDataPoint, index: number }`
+- `bar-hover` -> `{ item: WaterfallDataPoint, index: number }`
 
 ## CSS Custom Properties
 
@@ -34,7 +34,12 @@ interface WaterfallDataPoint {
 - `--snice-transition-fast` - Bar hover transition (default: `150ms`)
 - `--snice-font-weight-medium` - Value text weight
 
-## Usage
+## CSS Parts
+
+- `base` - Main waterfall container
+- `chart` - Chart rendering area
+
+## Basic Usage
 
 ```html
 <snice-waterfall show-values show-connectors></snice-waterfall>
@@ -53,7 +58,3 @@ chart.addEventListener('bar-click', (e) => {
   console.log(`Clicked: ${e.detail.item.label} (${e.detail.item.value})`);
 });
 ```
-
-**CSS Parts:**
-- `base` - Main waterfall container
-- `chart` - Chart rendering area

package/docs/ai/components/weather.md

@@ -4,46 +4,29 @@ Weather display card with current conditions, humidity, wind, and multi-day fore
 
 ## Properties
 
-```ts
-data: WeatherData | null = null
-unit: 'celsius' | 'fahrenheit' = 'celsius'
-variant: 'compact' | 'full' = 'full'
+```typescript
+data: WeatherData | null = null;
+unit: 'celsius'|'fahrenheit' = 'celsius';
+variant: 'compact'|'full' = 'full';
 
 interface WeatherData {
-  temp: number
-  condition: string           // e.g. "Sunny", "Partly Cloudy", "Rain"
-  icon?: string               // emoji or custom icon (auto-detected from condition if omitted)
-  humidity?: number            // percentage
-  wind?: number               // km/h
-  forecast?: WeatherForecastDay[]
+  temp: number;
+  condition: string;           // e.g. "Sunny", "Partly Cloudy", "Rain"
+  icon?: string;               // emoji or custom icon (auto-detected from condition if omitted)
+  humidity?: number;           // percentage
+  wind?: number;               // km/h
+  forecast?: WeatherForecastDay[];
 }
 
 interface WeatherForecastDay {
-  day: string                 // e.g. "Mon", "Tue"
-  high: number
-  low: number
-  condition: string
-  icon?: string
+  day: string;                 // e.g. "Mon", "Tue"
+  high: number;
+  low: number;
+  condition: string;
+  icon?: string;
 }
 ```
 
-## Variants
-
-- `full` - Shows current weather, details (humidity/wind), and forecast
-- `compact` - Current temp and icon only; hides details and forecast
-
-## Auto-detected Icons
-
-When `icon` is omitted, mapped from `condition` string:
-- sun/clear -> sun emoji
-- partly cloud -> partly cloudy emoji
-- cloud -> cloud emoji
-- rain -> rain emoji
-- snow -> snow emoji
-- thunder/storm -> thunderstorm emoji
-- fog/mist -> fog emoji
-- wind -> wind emoji
-
 ## CSS Custom Properties
 
 - `--snice-color-background-element` - Card background (default: `rgb(252 251 249)`)
@@ -56,16 +39,18 @@ When `icon` is omitted, mapped from `condition` string:
 - `--snice-border-radius-lg` - Card border radius (default: `0.5rem`)
 - `--snice-spacing-lg` - Card padding (default: `1.5rem`)
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer weather card div
 - `current` - Current conditions section (icon + temp + condition)
 - `details` - Details row (humidity and wind)
 - `forecast` - Multi-day forecast section
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-weather unit="celsius" variant="full"></snice-weather>
+<snice-weather unit="fahrenheit" variant="compact"></snice-weather>
 ```
 
 ```typescript

package/docs/ai/components/work-order.md

@@ -5,37 +5,24 @@ Service/maintenance work order with tasks, parts, labor, asset tracking, QR code
 ## Properties
 
 ```typescript
-woNumber: string = ''                              // attribute: wo-number
-date: string = ''                                  // Date string
-dueDate: string = ''                               // attribute: due-date
-priority: WorkOrderPriority = 'medium'             // 'low' | 'medium' | 'high' | 'urgent'
-status: WorkOrderStatus = 'open'                   // 'open' | 'in-progress' | 'completed' | 'cancelled'
-customer: WorkOrderCustomer | null = null           // { name, address?, phone?, email? }
-description: string = ''                            // Scope of work text
-tasks: WorkOrderTask[] = []                         // { description, assignee?, completed?, hours? }
-parts: WorkOrderPart[] = []                         // { name, partNumber?, quantity, unitCost }
-asset: WorkOrderAsset | null = null                 // { id, name, location?, serial?, lastService? }
-laborRate: number = 0                               // attribute: labor-rate; $/hr
-notes: string = ''                                  // Additional notes
-variant: WorkOrderVariant = 'standard'              // 'standard' | 'compact' | 'field-service' | 'maintenance' | 'detailed'
-showQr: boolean = false                             // attribute: show-qr; show QR code slot
-qrData: string = ''                                 // attribute: qr-data; data for QR code
-qrPosition: QrPosition = 'top-right'               // attribute: qr-position; 'top-right' | 'header' | 'footer'
+woNumber: string = '';                    // attr: wo-number
+date: string = '';
+dueDate: string = '';                     // attr: due-date
+priority: 'low'|'medium'|'high'|'urgent' = 'medium';
+status: 'open'|'in-progress'|'completed'|'cancelled' = 'open';
+customer: WorkOrderCustomer | null = null; // { name, address?, phone?, email? }
+description: string = '';
+tasks: WorkOrderTask[] = [];              // { description, assignee?, completed?, hours? }
+parts: WorkOrderPart[] = [];              // { name, partNumber?, quantity, unitCost }
+asset: WorkOrderAsset | null = null;      // { id, name, location?, serial?, lastService? }
+laborRate: number = 0;                    // attr: labor-rate; $/hr
+notes: string = '';
+variant: 'standard'|'compact'|'field-service'|'maintenance'|'detailed' = 'standard';
+showQr: boolean = false;                  // attr: show-qr
+qrData: string = '';                      // attr: qr-data
+qrPosition: 'top-right'|'header'|'footer' = 'top-right'; // attr: qr-position
 ```
 
-## Slots
-
-- `(default)` - Additional content after main sections
-- `signature` - Custom signature content (e.g., canvas, image)
-- `qr` - Custom QR code content (rendered at qr-position)
-- `footer` - Custom footer content
-
-## Events
-
-- `task-toggle` -> `{ index: number, task: WorkOrderTask, completed: boolean }`
-- `status-change` -> `{ previousStatus: WorkOrderStatus, status: WorkOrderStatus }`
-- `wo-sign` -> `{ woNumber: string, timestamp: string }`
-
 ## Methods
 
 - `getTotalPartsCost()` - Sum of part quantities * unit costs
@@ -45,15 +32,48 @@ qrPosition: QrPosition = 'top-right'               // attribute: qr-position; 't
 - `print()` - Trigger browser print
 - `toJSON()` - Returns WorkOrderJSON with all data + computed totals
 
-## Variants
+## Events
+
+- `task-toggle` -> `{ index, task, completed }`
+- `status-change` -> `{ previousStatus, status }`
+- `wo-sign` -> `{ woNumber, timestamp }`
+
+## Slots
+
+- `(default)` - Additional content after main sections
+- `signature` - Custom signature content (e.g., canvas, image)
+- `qr` - Custom QR code content (rendered at qr-position)
+- `footer` - Custom footer content
+
+## CSS Parts
 
-- `standard` - Clean, structured service work order
-- `compact` - Dense layout, reduced spacing, smaller typography
-- `field-service` - Big checkboxes (1.75rem), bordered tasks, large signature area
-- `maintenance` - Equipment-focused with highlighted asset section
-- `detailed` - Full accounting: monospace part numbers, wider cost summary
+- `base` - Root container
+- `header` - Header section
+- `title` / `wo-number` / `date` / `due-date` - Header fields
+- `priority` / `status` - Badge elements
+- `customer` / `customer-name` / `customer-address` / `customer-contact`
+- `asset` / `asset-id` / `asset-name`
+- `description` / `description-label` / `description-content`
+- `tasks` / `task` / `task-checkbox` / `task-description` / `task-assignee`
+- `parts` / `parts-table` / `parts-row` / `part-name` / `part-number` / `part-qty` / `part-cost` / `parts-total`
+- `labor` / `labor-hours` / `labor-rate` / `labor-total`
+- `costs` / `grand-total`
+- `notes` / `notes-label` / `notes-content`
+- `signature` / `signature-line` / `signature-date` / `sign-button`
+- `qr-container` / `footer`
 
-## Usage
+## CSS Custom Properties
+
+- `--wo-max-width` - Max container width (default: `50rem`)
+- `--wo-bg` / `--wo-bg-element` - Background colors
+- `--wo-text` / `--wo-text-secondary` - Text colors
+- `--wo-border` / `--wo-accent` - Border and accent colors
+- `--wo-priority-{low,medium,high,urgent}-{bg,text}` - Priority badge colors
+- `--wo-task-checkbox-size` - Checkbox size (default: `1.25rem`)
+- `--wo-signature-line-color` - Signature line color
+- `--wo-qr-size` - QR code size (default: `5rem`)
+
+## Basic Usage
 
 ```html
 <snice-work-order
@@ -62,11 +82,10 @@ qrPosition: QrPosition = 'top-right'               // attribute: qr-position; 't
   due-date="2024-03-20"
   priority="high"
   status="in-progress"
+  labor-rate="75"
   variant="field-service"
   show-qr
-  qr-data="https://app.example.com/wo/2024-001"
   qr-position="top-right">
-  <img slot="qr" src="qr.png" alt="QR" />
 </snice-work-order>
 ```
 
@@ -83,103 +102,8 @@ wo.parts = [
   { name: 'Compressor', partNumber: 'CP-200', quantity: 1, unitCost: 450 }
 ];
 wo.laborRate = 75;
-wo.notes = 'Customer prefers morning appointments';
 
 wo.addEventListener('task-toggle', e => console.log(e.detail));
 wo.addEventListener('wo-sign', e => console.log('Signed:', e.detail));
+console.log('Total:', wo.getTotalCost());
 ```
-
-## CSS Parts
-
-```css
-::part(base)              /* Main container */
-::part(header)            /* Header section */
-::part(title)             /* "Work Order" label */
-::part(wo-number)         /* WO number heading */
-::part(date)              /* Date value */
-::part(due-date)          /* Due date value */
-::part(priority)          /* Priority badge */
-::part(status)            /* Status badge */
-::part(customer)          /* Customer section */
-::part(customer-name)     /* Customer name value */
-::part(customer-address)  /* Customer address value */
-::part(customer-contact)  /* Customer phone value */
-::part(asset)             /* Asset section (maintenance) */
-::part(asset-id)          /* Asset ID value */
-::part(asset-name)        /* Asset name value */
-::part(description)       /* Description section */
-::part(description-label) /* Description heading */
-::part(description-content) /* Description text */
-::part(tasks)             /* Tasks section */
-::part(task)              /* Individual task row */
-::part(task-checkbox)     /* Task checkbox button */
-::part(task-description)  /* Task description text */
-::part(task-assignee)     /* Task assignee name */
-::part(parts)             /* Parts section */
-::part(parts-table)       /* Parts table */
-::part(parts-row)         /* Parts table row */
-::part(part-name)         /* Part name cell */
-::part(part-number)       /* Part number cell */
-::part(part-qty)          /* Part quantity cell */
-::part(part-cost)         /* Part unit cost cell */
-::part(parts-total)       /* Parts subtotal */
-::part(labor)             /* Labor section */
-::part(labor-hours)       /* Total labor hours */
-::part(labor-rate)        /* Labor rate display */
-::part(labor-total)       /* Labor cost total */
-::part(notes)             /* Notes section */
-::part(notes-label)       /* Notes heading */
-::part(notes-content)     /* Notes text */
-::part(costs)             /* Cost summary section */
-::part(grand-total)       /* Grand total amount */
-::part(signature)         /* Signature section */
-::part(signature-line)    /* Signature line */
-::part(signature-date)    /* Signature date line */
-::part(sign-button)       /* Sign work order button */
-::part(qr-container)      /* QR code container */
-::part(footer)            /* Footer */
-```
-
-## CSS Custom Properties
-
-```css
---wo-max-width            /* Max container width (default: 50rem) */
---wo-bg                   /* Background color */
---wo-bg-element           /* Element background */
---wo-text                 /* Primary text color */
---wo-text-secondary       /* Secondary text color */
---wo-text-tertiary        /* Tertiary text color */
---wo-border               /* Border color */
---wo-accent               /* Accent/primary color */
---wo-success              /* Success color */
---wo-danger               /* Danger color */
---wo-priority-low-bg      /* Low priority badge bg */
---wo-priority-low-text    /* Low priority badge text */
---wo-priority-medium-bg   /* Medium priority badge bg */
---wo-priority-medium-text /* Medium priority badge text */
---wo-priority-high-bg     /* High priority badge bg */
---wo-priority-high-text   /* High priority badge text */
---wo-priority-urgent-bg   /* Urgent priority badge bg */
---wo-priority-urgent-text /* Urgent priority badge text */
---wo-status-open-bg       /* Open status badge bg */
---wo-status-open-text     /* Open status badge text */
---wo-status-in-progress-bg /* In-progress status bg */
---wo-status-in-progress-text /* In-progress status text */
---wo-status-completed-bg  /* Completed status bg */
---wo-status-completed-text /* Completed status text */
---wo-status-cancelled-bg  /* Cancelled status bg */
---wo-status-cancelled-text /* Cancelled status text */
---wo-task-checkbox-size   /* Checkbox dimensions (default: 1.25rem) */
---wo-task-completed-text  /* Completed task text color */
---wo-signature-line-color /* Signature line color */
---wo-qr-size              /* QR code container size (default: 5rem) */
-```
-
-## Notes
-
-- Totals auto-compute from parts costs + (labor hours * labor rate)
-- Task checkboxes toggle completed state and emit `task-toggle`
-- Status changes emit `status-change` event
-- `asset` property is for equipment/maintenance tracking (prominent in `maintenance` variant)
-- QR slot renders at configurable position; use with any QR library
-- Print-friendly: badges use borders, checkboxes use B&W, signature lines darken, page breaks managed

package/docs/ai/patterns.md

@@ -163,6 +163,69 @@ class UserProfile extends HTMLElement {
 // Wiring: <user-profile controller="api"></user-profile>
 ```
 
+### Vanilla JS: createRequestHandler
+
+Handle `@request` channels without decorators. Useful for non-Snice code,
+third-party integrations, or vanilla JS apps.
+
+```typescript
+import { createRequestHandler } from 'snice';
+
+// Scoped to an ancestor element (catches bubbling requests)
+const cleanup = createRequestHandler(containerEl, {
+  'fetch-user': async (payload) => {
+    const res = await fetch(`/api/users/${payload.id}`);
+    return res.json();
+  },
+  'save-settings': async (payload) => {
+    await fetch('/api/settings', { method: 'POST', body: JSON.stringify(payload) });
+    return { ok: true };
+  }
+});
+
+// Global handler (listens on document)
+const cleanup2 = createRequestHandler(document, {
+  'fetch-user': async (payload) => ({ name: 'Jane', id: payload.id }),
+});
+
+// Remove all listeners
+cleanup();
+```
+
+### React: useRequestHandler
+
+React hook equivalent. Lives in `src/react/`, built to `adapters/react/`.
+
+```tsx
+import { useRequestHandler } from 'snice/react/useRequestHandler';
+
+function App() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useRequestHandler(containerRef, {
+    'fetch-user': async (payload) => {
+      const res = await fetch(`/api/users/${payload.id}`);
+      return res.json();
+    },
+  });
+
+  return (
+    <div ref={containerRef}>
+      <snice-user-card />
+    </div>
+  );
+}
+
+// Global handler (null ref = document)
+useRequestHandler(null, {
+  'fetch-user': async (payload) => ({ name: 'Jane' }),
+});
+```
+
+Route map callbacks always use the latest version (ref-stable) — no need
+for `useCallback` or stable references. Re-subscribes only when channel
+names change.
+
 ## Fetch with Middleware
 
 ```typescript
@@ -404,3 +467,27 @@ class SearchBox extends HTMLElement {
   }
 }
 ```
+
+## React Router
+
+```tsx
+import { SniceRouter, Route, useSniceContext } from 'snice/react';
+
+function App() {
+  return (
+    <SniceRouter mode="hash" context={{ user, theme: 'dark' }} layout={AppShell}>
+      <Route path="/" page={HomePage} />
+      <Route path="/settings" page={SettingsPage} guard={authGuard} guardRedirect="/login" />
+      <Route path="/legacy" page="legacy-dashboard" />
+      <Route path="/login" page={LoginPage} layout={false} />
+    </SniceRouter>
+  );
+}
+
+function AppShell({ children }) {
+  const ctx = useSniceContext();
+  return <div className="shell"><nav>...</nav><main>{children}</main></div>;
+}
+
+const authGuard = (ctx, params) => !!ctx.user;
+```