snice 4.28.0 → 4.30.0

package/docs/ai/react-integration.md

@@ -0,0 +1,97 @@
+# React Integration
+
+Source: `src/react/` → Build: `dist/react/` → Published: `adapters/react/`
+Import: `import { SniceRouter, Route, useSniceContext } from 'snice/react'`
+Deep import: `import { useRequestHandler } from 'snice/react/useRequestHandler'`
+
+## Components
+
+| Export | Type | Purpose |
+|---|---|---|
+| `<SniceRouter>` | Component | Root provider. URL state, route matching, guards, layouts, context. |
+| `<Route>` | Component | Route definition. Child of `<SniceRouter>`. |
+| `<SniceProvider>` | Component | Context provider (standalone, no router needed). |
+
+## Hooks
+
+| Export | Returns | Purpose |
+|---|---|---|
+| `useSniceContext()` | `SniceReactContext` | Full merged context: `{ application, navigation: {route, params, placards}, navigate, fetch? }` |
+| `useNavigate()` | `(path) => void` | Programmatic navigation |
+| `useParams()` | `Record<string, string>` | Current route params (shortcut for `ctx.navigation.params`) |
+| `useRoute()` | `string` | Current matched route pattern (shortcut for `ctx.navigation.route`) |
+| `useRequestHandler(ref, routes, options?)` | `void` | Handle @request channels from Snice elements |
+
+## SniceRouter Props
+
+- `mode`: `"hash"` | `"history"` — URL strategy (required)
+- `context`: `object` — App context passed to guards, available via `useSniceContext()` (default `{}`)
+- `layout`: `Component | string` — Default layout wrapping all pages
+- `loading`: `Component | string | JSX` — Shown during async guards (default: centered spinner)
+- `fallback`: `Component | string | JSX` — No route match (default: "404" text)
+
+## Route Props
+
+- `path`: Route pattern (e.g., `/users/:id`)
+- `page`: React component (receives params as props) OR Snice tag name string (params set as attributes)
+- `guard`: `(ctx, params) => boolean | Promise<boolean>`
+- `guards`: Array of guard functions (AND logic, sequential, short-circuit)
+- `guardRedirect`: Redirect path on guard failure (without it: renders nothing)
+- `layout`: Override layout. `false` = no layout
+- `placard`: `Placard` — page metadata for layouts
+
+## Guards
+
+Same signature for both Snice and React:
+`(context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>`
+
+- Sync guards resolve immediately
+- Async guards show `loading` component until resolved
+- Guard error (throw) treated as rejection
+- Guards run on navigation only, NOT on context change
+
+## useRequestHandler
+
+```tsx
+useRequestHandler(ref, routes, options?)
+```
+
+- `ref`: React ref to DOM element, or `null` for document-level
+- `routes`: `Record<string, (payload) => any | Promise<any>>`
+- `options.passive`: `boolean` (default false) — don't stop propagation
+- Callbacks are ref-stable — no `useCallback` needed
+- Re-subscribes only when channel names change
+- Auto-cleanup on unmount
+
+## Context Shape
+
+```typescript
+interface SniceReactContext {
+  application: Record<string, any>;  // your context object
+  navigation: { route: string; params: Record<string, string>; placards: Placard[] };
+  navigate: (path: string) => void;
+  fetch?: typeof globalThis.fetch;   // if provided to SniceProvider
+}
+```
+
+## SniceProvider Props (standalone use)
+
+- `context`, `navigate`, `route`, `params`, `placards`, `fetch` — all optional
+- When inside `<SniceRouter>`, these are set automatically
+
+## Mixed Pages
+
+`page` accepts React component OR string (Snice tag name).
+Same for `layout`, `loading`, `fallback`.
+
+```tsx
+<SniceRouter mode="hash" context={{ user }}>
+  <Route path="/" page={HomePage} />
+  <Route path="/legacy" page="legacy-dashboard" />
+</SniceRouter>
+```
+
+## Type Exports
+
+`SniceReactContext`, `SniceRouterProps`, `RouteProps`, `SniceProviderProps`, `Placard`,
+`UseRequestRoute`, `UseRequestRouteMap`, `UseRequestHandlerOptions`

package/docs/components/accordion.md

@@ -1,4 +1,4 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/accordion.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/accordion.md -->
 
 # Accordion Components
 
@@ -15,8 +15,6 @@ The accordion components provide collapsible sections of content. An `<snice-acc
 - [Examples](#examples)
 - [Keyboard Navigation](#keyboard-navigation)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
-- [Common Patterns](#common-patterns)
 
 ## Components
 
@@ -39,7 +37,7 @@ Individual collapsible section within an accordion.
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `itemId` | `string` | auto-generated | Unique identifier for the item |
+| `itemId` (attr: `item-id`) | `string` | auto-generated | Unique identifier for the item |
 | `open` | `boolean` | `false` | Whether the item is expanded |
 | `disabled` | `boolean` | `false` | Disable interaction with the item |
 
@@ -155,25 +153,23 @@ Fired when an item is toggled.
 
 ## Slots
 
-### Accordion Item Slots
+### Accordion Container
 
-#### `header` (named slot)
-Content for the clickable header/trigger.
+| Name | Description |
+|------|-------------|
+| (default) | `<snice-accordion-item>` elements |
 
-```html
-<snice-accordion-item>
-  <span slot="header">Click to expand</span>
-  <div>Panel content</div>
-</snice-accordion-item>
-```
+### Accordion Item
 
-#### Default slot
-Content that appears when the item is expanded.
+| Name | Description |
+|------|-------------|
+| `header` | Content for the clickable header/trigger |
+| (default) | Content that appears when the item is expanded |
 
 ```html
 <snice-accordion-item>
-  <span slot="header">Header</span>
-  <div>This content is collapsible</div>
+  <span slot="header">Click to expand</span>
+  <div>Panel content</div>
 </snice-accordion-item>
 ```
 
@@ -210,6 +206,11 @@ snice-accordion-item::part(icon) {
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/accordion/snice-accordion';
+import 'snice/components/accordion/snice-accordion-item';
+```
+
 ```html
 <snice-accordion>
   <snice-accordion-item item-id="item-1">
@@ -229,11 +230,6 @@ snice-accordion-item::part(icon) {
 </snice-accordion>
 ```
 
-```typescript
-import 'snice/components/accordion/snice-accordion';
-import 'snice/components/accordion/snice-accordion-item';
-```
-
 ## Examples
 
 ### Basic Accordion
@@ -282,51 +278,36 @@ import 'snice/components/accordion/snice-accordion-item';
 </snice-accordion>
 ```
 
-### With Disabled Items
+### Elevated Variant
+
+Use the `variant` attribute to change the visual style.
 
 ```html
-<snice-accordion>
-  <snice-accordion-item item-id="active">
-    <span slot="header">Active Item</span>
-    <p>This item can be clicked.</p>
+<snice-accordion variant="elevated">
+  <snice-accordion-item item-id="item-1">
+    <span slot="header">Elevated Section 1</span>
+    <p>Content with card-like appearance and shadow.</p>
   </snice-accordion-item>
 
-  <snice-accordion-item item-id="disabled" disabled>
-    <span slot="header">Disabled Item</span>
-    <p>This item cannot be opened.</p>
+  <snice-accordion-item item-id="item-2">
+    <span slot="header">Elevated Section 2</span>
+    <p>Each item appears as a separate card.</p>
   </snice-accordion-item>
 </snice-accordion>
 ```
 
-### FAQ Accordion
+### With Disabled Items
 
 ```html
-<style>
-  snice-accordion-item::part(header) {
-    font-weight: 600;
-    padding: 1rem;
-  }
-
-  snice-accordion-item::part(content) {
-    padding: 1rem;
-    background: #f9fafb;
-  }
-</style>
-
-<snice-accordion id="faq">
-  <snice-accordion-item item-id="shipping">
-    <span slot="header">What are the shipping options?</span>
-    <p>We offer standard (5-7 days) and express (2-3 days) shipping options.</p>
-  </snice-accordion-item>
-
-  <snice-accordion-item item-id="returns">
-    <span slot="header">What is your return policy?</span>
-    <p>Items can be returned within 30 days of purchase for a full refund.</p>
+<snice-accordion>
+  <snice-accordion-item item-id="active">
+    <span slot="header">Active Item</span>
+    <p>This item can be clicked.</p>
   </snice-accordion-item>
 
-  <snice-accordion-item item-id="warranty">
-    <span slot="header">Do products come with a warranty?</span>
-    <p>All products include a 1-year manufacturer warranty.</p>
+  <snice-accordion-item item-id="disabled" disabled>
+    <span slot="header">Disabled Item</span>
+    <p>This item cannot be opened.</p>
   </snice-accordion-item>
 </snice-accordion>
 ```
@@ -334,7 +315,7 @@ import 'snice/components/accordion/snice-accordion-item';
 ### Programmatic Control
 
 ```html
-<snice-accordion id="controlled">
+<snice-accordion id="controlled" multiple>
   <snice-accordion-item item-id="item-1">
     <span slot="header">Item 1</span>
     <p>Content 1</p>
@@ -382,6 +363,39 @@ accordion.closeItem('item-2');
 accordion.toggleItem('item-3');
 ```
 
+### FAQ Accordion
+
+```html
+<style>
+  snice-accordion-item::part(header) {
+    font-weight: 600;
+    padding: 1rem;
+  }
+
+  snice-accordion-item::part(content) {
+    padding: 1rem;
+    background: #f9fafb;
+  }
+</style>
+
+<snice-accordion id="faq">
+  <snice-accordion-item item-id="shipping">
+    <span slot="header">What are the shipping options?</span>
+    <p>We offer standard (5-7 days) and express (2-3 days) shipping options.</p>
+  </snice-accordion-item>
+
+  <snice-accordion-item item-id="returns">
+    <span slot="header">What is your return policy?</span>
+    <p>Items can be returned within 30 days of purchase for a full refund.</p>
+  </snice-accordion-item>
+
+  <snice-accordion-item item-id="warranty">
+    <span slot="header">Do products come with a warranty?</span>
+    <p>All products include a 1-year manufacturer warranty.</p>
+  </snice-accordion-item>
+</snice-accordion>
+```
+
 ### Dynamic Content Loading
 
 ```html
@@ -396,7 +410,6 @@ accordion.toggleItem('item-3');
     <div id="content-2">Loading...</div>
   </snice-accordion-item>
 </snice-accordion>
-
 ```
 
 ```typescript
@@ -435,7 +448,7 @@ accordion.addEventListener('accordion-open', async (e) => {
 
 <snice-accordion>
   <snice-accordion-item item-id="general-settings">
-    <span slot="header">⚙️ General Settings</span>
+    <span slot="header">General Settings</span>
     <div class="setting-group">
       <div class="setting-item">
         <label>Language</label>
@@ -457,7 +470,7 @@ accordion.addEventListener('accordion-open', async (e) => {
   </snice-accordion-item>
 
   <snice-accordion-item item-id="notification-settings">
-    <span slot="header">🔔 Notifications</span>
+    <span slot="header">Notifications</span>
     <div class="setting-group">
       <div class="setting-item">
         <label>Email notifications</label>
@@ -469,61 +482,6 @@ accordion.addEventListener('accordion-open', async (e) => {
       </div>
     </div>
   </snice-accordion-item>
-
-  <snice-accordion-item item-id="privacy-settings">
-    <span slot="header">🔒 Privacy</span>
-    <div class="setting-group">
-      <div class="setting-item">
-        <label>Profile visibility</label>
-        <select>
-          <option>Public</option>
-          <option>Friends</option>
-          <option>Private</option>
-        </select>
-      </div>
-    </div>
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-### Nested Content
-
-```html
-<snice-accordion>
-  <snice-accordion-item item-id="products">
-    <span slot="header">Products</span>
-    <div style="padding: 1rem;">
-      <ul>
-        <li>Product A - $29.99</li>
-        <li>Product B - $39.99</li>
-        <li>Product C - $49.99</li>
-      </ul>
-    </div>
-  </snice-accordion-item>
-
-  <snice-accordion-item item-id="services">
-    <span slot="header">Services</span>
-    <div style="padding: 1rem;">
-      <table>
-        <thead>
-          <tr>
-            <th>Service</th>
-            <th>Price</th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr>
-            <td>Consultation</td>
-            <td>$99/hr</td>
-          </tr>
-          <tr>
-            <td>Implementation</td>
-            <td>$149/hr</td>
-          </tr>
-        </tbody>
-      </table>
-    </div>
-  </snice-accordion-item>
 </snice-accordion>
 ```
 
@@ -544,40 +502,3 @@ The accordion supports comprehensive keyboard navigation:
 - **Screen reader friendly**: Announces state changes
 - **Focus management**: Visible focus indicators
 - **Semantic HTML**: Uses button elements for interactivity
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
-
-## Common Patterns
-
-### FAQ Pattern
-```html
-<snice-accordion>
-  <snice-accordion-item item-id="q1">
-    <span slot="header">Question 1?</span>
-    <p>Answer to question 1.</p>
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-### Settings Pattern
-```html
-<snice-accordion multiple>
-  <snice-accordion-item item-id="general">
-    <span slot="header">General</span>
-    <!-- Settings form -->
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-### Table of Contents Pattern
-```html
-<snice-accordion>
-  <snice-accordion-item item-id="intro" open>
-    <span slot="header">Introduction</span>
-    <p>Content overview...</p>
-  </snice-accordion-item>
-</snice-accordion>
-```

package/docs/components/action-bar.md

@@ -0,0 +1,185 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/action-bar.md -->
+
+# Action Bar
+`<snice-action-bar>`
+
+A positioned, animated container for contextual actions that appears on hover, focus, or programmatic trigger.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `open` | `boolean` | `false` | Whether the action bar is visible |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Position relative to parent |
+| `size` | `'small' \| 'medium'` | `'medium'` | Bar size |
+| `variant` | `'default' \| 'pill'` | `'default'` | Visual style |
+| `noAnimation` (attr: `no-animation`) | `boolean` | `false` | Always visible, no transitions |
+| `noEscapeDismiss` (attr: `no-escape-dismiss`) | `boolean` | `false` | Prevent Escape key from closing |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `show()` | -- | Opens the action bar |
+| `hide()` | -- | Closes the action bar |
+| `toggle()` | -- | Toggles the open state |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `action-bar-open` | `{ actionBar: SniceActionBarElement }` | Fired when the bar opens |
+| `action-bar-close` | `{ actionBar: SniceActionBarElement }` | Fired when the bar closes |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Action content (buttons, icons, etc.) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The inner toolbar container |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--action-bar-background` | Background color | `var(--snice-color-background-element)` |
+| `--action-bar-border` | Border style | `1px solid var(--snice-color-border)` |
+| `--action-bar-border-radius` | Border radius | `var(--snice-border-radius-lg)` |
+| `--action-bar-padding` | Inner padding | `var(--snice-spacing-xs)` |
+| `--action-bar-gap` | Gap between items | `var(--snice-spacing-2xs)` |
+| `--action-bar-shadow` | Box shadow | `var(--snice-shadow-md)` |
+| `--action-bar-z-index` | Z-index | `10` |
+
+## Basic Usage
+
+```typescript
+import 'snice/components/action-bar/snice-action-bar';
+```
+
+```html
+<div style="position: relative">
+  <p>Card content</p>
+  <snice-action-bar position="bottom">
+    <button>Edit</button>
+    <button>Delete</button>
+  </snice-action-bar>
+</div>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the bar's visual style.
+
+```html
+<snice-action-bar variant="default">
+  <button>Edit</button>
+  <button>Delete</button>
+</snice-action-bar>
+
+<snice-action-bar variant="pill">
+  <button>Save</button>
+  <button>Share</button>
+</snice-action-bar>
+```
+
+### Sizes
+
+Use the `size` attribute to change the bar's padding and gap.
+
+```html
+<snice-action-bar size="small">
+  <button>A</button>
+  <button>B</button>
+</snice-action-bar>
+
+<snice-action-bar size="medium">
+  <button>A</button>
+  <button>B</button>
+</snice-action-bar>
+```
+
+### Positions
+
+Use the `position` attribute to place the bar relative to its positioned parent.
+
+```html
+<snice-action-bar position="top">...</snice-action-bar>
+<snice-action-bar position="bottom">...</snice-action-bar>
+<snice-action-bar position="left">...</snice-action-bar>
+<snice-action-bar position="right">...</snice-action-bar>
+<snice-action-bar position="top-left">...</snice-action-bar>
+<snice-action-bar position="top-right">...</snice-action-bar>
+<snice-action-bar position="bottom-left">...</snice-action-bar>
+<snice-action-bar position="bottom-right">...</snice-action-bar>
+```
+
+### Animated Show/Hide
+
+Show and hide the action bar programmatically or via hover. The bar animates with a fade + slide from its anchored edge.
+
+```html
+<div class="card"
+     onmouseenter="this.querySelector('snice-action-bar').show()"
+     onmouseleave="this.querySelector('snice-action-bar').hide()">
+  <p>Hover me</p>
+  <snice-action-bar position="bottom" variant="pill">
+    <button>Save</button>
+    <button>Share</button>
+  </snice-action-bar>
+</div>
+```
+
+### Always Visible
+
+Set `no-animation` to make the bar always visible with no transitions.
+
+```html
+<snice-action-bar no-animation position="top-right" size="small">
+  <button>Edit</button>
+  <button>Delete</button>
+</snice-action-bar>
+```
+
+## Keyboard Navigation
+
+The action bar uses `role="toolbar"` and supports roving keyboard navigation:
+
+- **Arrow Right / Arrow Down**: Move focus to the next item
+- **Arrow Left / Arrow Up**: Move focus to the previous item
+- **Home**: Move focus to the first item
+- **End**: Move focus to the last item
+- **Escape**: Close the bar (unless `no-escape-dismiss` is set)
+
+```html
+<snice-action-bar open no-escape-dismiss>
+  <button>First</button>
+  <button>Second</button>
+  <button>Third</button>
+</snice-action-bar>
+```
+
+## Accessibility
+
+- **ARIA role**: `role="toolbar"` with `aria-label="Actions"`
+- **Keyboard support**: Full roving keyboard navigation
+- **Focus management**: Arrow keys move focus between slotted children
+- **Escape dismiss**: Configurable via `no-escape-dismiss`

package/docs/components/activity-feed.md

@@ -1,28 +1,23 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/activity-feed.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/activity-feed.md -->
 
 # Activity Feed
 `<snice-activity-feed>`
 
 A vertical timeline of activity entries for displaying audit logs, user activity streams, and event histories.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/activity-feed/snice-activity-feed';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-activity-feed.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `activities` | `Activity[]` | `[]` | Array of activity objects |
+| `activities` | `Activity[]` | `[]` | Array of activity objects (set via JavaScript) |
 | `filter` | `string` | `''` | Active filter by activity type |
 | `groupBy` (attr: `group-by`) | `'none' \| 'date'` | `'none'` | Grouping mode |