snice 4.27.0 → 4.29.0

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