snice 4.28.0 → 4.30.0

package/dist/types/guard.d.ts

@@ -1,19 +1,12 @@
 import { RouteParams } from './route-params';
 /**
  * Guard function type for route protection and visibility control.
- * Guards determine if navigation to a route should proceed or if a page should be visible.
+ * Guards determine if navigation to a route should proceed.
+ * Can return a boolean synchronously or a Promise<boolean> for async checks.
  *
  * @template T - The context type passed to the guard function
  * @param context - The application context object
  * @param params - Route parameters extracted from the URL
- * @returns boolean - true to allow access, false to deny
- *
- * @example
- * ```typescript
- * const isAuthenticated: Guard<AppContext> = (ctx, params) => ctx.getUser() !== null;
- * const canEditUser: Guard<AppContext> = (ctx, params) => {
- *   return ctx.hasPermission('users.edit', params.id);
- * };
- * ```
+ * @returns boolean or Promise<boolean> - true to allow, false to deny
  */
-export type Guard<T = any> = (context: T, params: RouteParams) => boolean;
+export type Guard<T = any> = (context: T, params: RouteParams) => boolean | Promise<boolean>;

package/docs/ai/DEVELOPMENT.md

@@ -98,7 +98,7 @@ All CDN builds use the shared runtime (external `snice` imports). Load `snice-ru
 - IIFE: `.js` + `.min.js`
 - Sourcemaps + README
 
-**Size:** Runtime ~17KB gzip, components ~1-93KB each
+**Size:** Runtime ~18KB gzip, components ~1-93KB each
 
 **Features:**
 - Shared runtime (external snice imports)

package/docs/ai/README.md

@@ -12,6 +12,7 @@ Token-efficient reference docs for AI assistants. Same content as human docs, mi
 - `api.md` - Complete API reference
 - `decorators.md` - Quick decorator reference
 - `patterns.md` - Common usage patterns
+- `react-integration.md` - React router, hooks, guards, context
 - `architecture.md` - System design
 - `components/*.md` - Component reference (DO NOT read all upfront - read only as needed)
 
@@ -22,16 +23,14 @@ Read these instead of `/docs/*.md` for faster context loading.
 ## CLI
 
 ```bash
-# Create project from template
-npx snice create-app my-app --template=base
-npx snice create-app my-app --template=pwa
+# Create project
+npx snice create-app my-app
+npx snice create-app my-app --template=react
 
 # Run MCP server
 npx snice mcp
 ```
 
-**Note:** Use `--template=base` (equals), not `--template base` (space).
-
 ## MCP Server
 
 Snice includes an MCP server for AI-assisted development.
@@ -141,10 +140,11 @@ class MyCounter extends HTMLElement {
 - `@context()` receives Context on navigation
 
 **Guards:**
-- Signature: `(context: AppContext, params: RouteParams) => boolean`
+- Signature: `(context: AppContext, params: RouteParams) => boolean | Promise<boolean>`
 - TWO params: context (raw AppContext) and route params
 - Return `true` to allow, `false` renders 403 page
-- NO async guards, NO string redirects (boolean only)
+- Sync or async — async guards are awaited; React router shows `loading` component during async resolution
+- NO string redirects (boolean/Promise<boolean> only)
 - Multiple guards use AND logic, short-circuit on first false
 - Example: `(ctx, params) => ctx.user !== null`
 - Factory: `const hasRole = (role) => (ctx, params) => ctx.user?.role === role`

package/docs/ai/components/accordion.md

@@ -8,61 +8,75 @@ Collapsible sections with single or multiple open mode and keyboard navigation.
 
 Container managing accordion items.
 
+### snice-accordion-item
+
+Individual collapsible section.
+
+## Properties
+
+### snice-accordion
+
 ```typescript
 multiple: boolean = false;                         // Allow multiple items open
 variant: 'bordered' | 'elevated' = 'bordered';    // Visual style variant
 ```
 
-**Methods:**
+### snice-accordion-item
+
+```typescript
+itemId: string = '';             // attr: item-id, auto-generated if not provided
+open: boolean = false;
+disabled: boolean = false;
+```
+
+## Methods
+
+### snice-accordion
+
 - `openItem(id)` - Open specific item
 - `closeItem(id)` - Close specific item
 - `toggleItem(id)` - Toggle specific item
 - `openAll()` - Open all (multiple mode only)
 - `closeAll()` - Close all
 
-**Events:**
-- `accordion-open` - {itemId, item}
-- `accordion-close` - {itemId, item}
-
 ### snice-accordion-item
 
-Individual collapsible section.
-
-```typescript
-itemId: string;              // Auto-generated if not provided
-open: boolean = false;
-disabled: boolean = false;
-```
-
-**Methods:**
 - `toggle()` - Toggle open/closed
 - `expand(animate = true)` - Open
 - `collapse(animate = true)` - Close
 
-**Events:**
-- `accordion-item-toggle` - {itemId, open}
+## Events
+
+- `accordion-open` → `{ itemId, item }` - Item opened (on container)
+- `accordion-close` → `{ itemId, item }` - Item closed (on container)
+- `accordion-item-toggle` → `{ itemId, open }` - Item toggled (on item)
+
+## Slots
+
+### snice-accordion
+- `(default)` - `<snice-accordion-item>` elements
 
-**Slots:**
+### snice-accordion-item
 - `header` - Clickable trigger content
-- default - Collapsible content
+- `(default)` - Collapsible content
+
+## CSS Parts
 
-**CSS Parts:**
+(on snice-accordion-item)
 - `header` - The clickable button trigger
 - `title` - Span wrapping the header slot
 - `icon` - The chevron SVG icon
 - `content` - The collapsible content wrapper
 - `content-inner` - Inner div containing the default slot
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-accordion>
   <snice-accordion-item item-id="item-1">
     <span slot="header">Section 1</span>
     <div>Content 1</div>
   </snice-accordion-item>
-
   <snice-accordion-item item-id="item-2">
     <span slot="header">Section 2</span>
     <div>Content 2</div>
@@ -75,71 +89,23 @@ disabled: boolean = false;
     <span slot="header">A</span>
     <p>Content A</p>
   </snice-accordion-item>
-
-  <snice-accordion-item item-id="b" open>
-    <span slot="header">B</span>
-    <p>Content B</p>
-  </snice-accordion-item>
 </snice-accordion>
 
-<!-- Disabled item -->
-<snice-accordion>
-  <snice-accordion-item item-id="active">
-    <span slot="header">Active</span>
-    <p>Can open</p>
-  </snice-accordion-item>
-
-  <snice-accordion-item item-id="disabled" disabled>
-    <span slot="header">Disabled</span>
-    <p>Cannot open</p>
-  </snice-accordion-item>
-</snice-accordion>
-```
+<!-- Elevated variant -->
+<snice-accordion variant="elevated">...</snice-accordion>
 
-## Programmatic Control
-
-```typescript
-// Control items
-accordion.openItem('item-1');
-accordion.closeItem('item-2');
-accordion.toggleItem('item-3');
-accordion.openAll();  // Multiple mode only
-accordion.closeAll();
-
-// Listen for events
-accordion.addEventListener('accordion-open', (e) => {
-  console.log('Opened:', e.detail.itemId);
-});
-
-// Control individual item
-item.toggle();
-item.expand();
-item.collapse();
+<!-- Disabled item -->
+<snice-accordion-item item-id="disabled" disabled>...</snice-accordion-item>
 ```
 
 ## Keyboard Navigation
 
-- **↓** - Next item
-- **↑** - Previous item
-- **Home** - First item
-- **End** - Last item
+- **Arrow Down/Up** - Next/previous item
+- **Home/End** - First/last item
 - **Enter/Space** - Toggle focused item
 
-## Features
-
-- Single or multiple open mode
-- Keyboard navigation
-- Click or keyboard to toggle
-- Auto-generated item IDs
-- Disabled state
-- Open/close events
-- Accessibility: aria-expanded, button roles
-- Smooth animations
-
-## Notes
+## Accessibility
 
-- Items are light DOM children (not slotted)
-- Without `multiple`, opening one closes others
-- Item IDs auto-generated if not provided
-- Disabled items cannot be toggled
-- Header slot required for trigger content
+- `aria-expanded` on headers, `button` role
+- Full keyboard navigation
+- Visible focus indicators

package/docs/ai/components/action-bar.md

@@ -0,0 +1,75 @@
+# snice-action-bar
+
+Positioned, animated container for contextual actions within a relative parent.
+
+## Properties
+
+```typescript
+open: boolean = false;                          // attr: open
+position: 'top'|'bottom'|'left'|'right'|'top-left'|'top-right'|'bottom-left'|'bottom-right' = 'bottom';
+size: 'small'|'medium' = 'medium';
+variant: 'default'|'pill' = 'default';
+noAnimation: boolean = false;                   // attr: no-animation — always visible, no transitions
+noEscapeDismiss: boolean = false;               // attr: no-escape-dismiss
+```
+
+## Methods
+
+- `show()` - Open
+- `hide()` - Close
+- `toggle()` - Toggle open state
+
+## Events
+
+- `action-bar-open` → `{ actionBar: SniceActionBarElement }`
+- `action-bar-close` → `{ actionBar: SniceActionBarElement }`
+
+## Slots
+
+- `(default)` - Action content (buttons, icons, etc.)
+
+## CSS Parts
+
+- `base` - The inner toolbar container
+
+## CSS Custom Properties
+
+- `--action-bar-background` - Background color
+- `--action-bar-border` - Border style
+- `--action-bar-border-radius` - Border radius
+- `--action-bar-padding` - Inner padding
+- `--action-bar-gap` - Gap between items
+- `--action-bar-shadow` - Box shadow
+- `--action-bar-z-index` - Z-index
+
+## Basic Usage
+
+```html
+<div style="position:relative"
+     onmouseenter="this.querySelector('snice-action-bar').show()"
+     onmouseleave="this.querySelector('snice-action-bar').hide()">
+  <p>Content</p>
+  <snice-action-bar position="bottom" variant="pill">
+    <button>Edit</button>
+    <button>Delete</button>
+  </snice-action-bar>
+</div>
+
+<!-- Always visible -->
+<snice-action-bar no-animation position="top-right" size="small">
+  <button>Edit</button>
+</snice-action-bar>
+```
+
+## Keyboard Navigation
+
+- Arrow keys navigate focusable children (roving tabindex)
+- `Escape` closes unless `no-escape-dismiss`
+- `Home`/`End` jump to first/last
+- `role="toolbar"`
+
+## Accessibility
+
+- `role="toolbar"` with `aria-label="Actions"`
+- Roving keyboard navigation
+- Escape dismiss (configurable)

package/docs/ai/components/activity-feed.md

@@ -26,16 +26,16 @@ interface Activity {
 }
 ```
 
-## Events
-
-- `activity-click` -> `{ activity: Activity }`
-- `load-more` -> `{ count: number }`
-
 ## Methods
 
 - `addActivity(activity)` - Prepend activity to feed
 - `clearFilter()` - Reset filter to show all
 
+## Events
+
+- `activity-click` → `{ activity: Activity }`
+- `load-more` → `{ count: number }`
+
 ## CSS Parts
 
 - `base` - Feed container
@@ -47,7 +47,7 @@ interface Activity {
 - `timestamp` - Timestamp text
 - `group-header` - Date group header
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-activity-feed group-by="date"></snice-activity-feed>
@@ -57,8 +57,8 @@ interface Activity {
 feed.activities = [
   { id: '1', actor: { name: 'Alice', avatar: 'alice.jpg' }, action: 'created', target: 'Project Alpha', timestamp: '2024-01-15T10:30:00Z', type: 'create', icon: '+' },
   { id: '2', actor: { name: 'Bob' }, action: 'commented on', target: 'Issue #42', timestamp: '2024-01-15T11:00:00Z', type: 'comment' },
-  { id: '3', actor: { name: 'Charlie' }, action: 'deployed', target: 'v2.0.0', timestamp: '2024-01-14T09:00:00Z', type: 'deploy' }
 ];
 feed.addEventListener('activity-click', e => console.log(e.detail.activity));
 feed.addEventListener('load-more', e => console.log('Load more, current:', e.detail.count));
+feed.addActivity({ id: '3', actor: { name: 'System' }, action: 'deployed', target: 'v3.0', timestamp: new Date().toISOString(), type: 'deploy' });
 ```

package/docs/ai/components/alert.md

@@ -9,18 +9,13 @@ variant: 'info'|'success'|'warning'|'error' = 'info';
 size: 'small'|'medium'|'large' = 'medium';
 title: string = '';
 dismissible: boolean = false;
-icon: string = '';
+icon: string = '';   // URL, emoji, or 'none'. Use icon slot for icon fonts.
 ```
 
-## Slots
-
-- `(default)` - Alert message content
-- `icon` - Custom icon content (overrides `icon` property and default icons)
-
 ## Methods
 
 - `show()` - Show alert
-- `hide()` - Hide alert
+- `hide()` - Hide alert with animation
 
 ## Events
 
@@ -28,30 +23,29 @@ icon: string = '';
 - `alert-shown` → `{ variant, title }` - Alert shown
 - `alert-hidden` → `{ variant, title }` - Alert hidden after animation
 
-## Usage
+## Slots
+
+- `(default)` - Alert message content
+- `icon` - Custom icon content (overrides `icon` property and default icons)
+
+## CSS Parts
+
+- `icon` - The icon container
+
+## Basic Usage
 
 ```html
 <!-- Basic -->
 <snice-alert>Alert message</snice-alert>
 
-<!-- Success -->
-<snice-alert variant="success">
-  Operation completed successfully!
-</snice-alert>
-
-<!-- Error -->
-<snice-alert variant="error">
-  An error occurred
-</snice-alert>
-
-<!-- Warning -->
-<snice-alert variant="warning">
-  Please review your input
-</snice-alert>
+<!-- Variants -->
+<snice-alert variant="success">Operation completed!</snice-alert>
+<snice-alert variant="error">An error occurred</snice-alert>
+<snice-alert variant="warning">Please review your input</snice-alert>
 
 <!-- With title -->
 <snice-alert variant="info" title="Information">
-  Additional details about the information.
+  Additional details.
 </snice-alert>
 
 <!-- Dismissible -->
@@ -59,37 +53,25 @@ icon: string = '';
   Can be closed by user
 </snice-alert>
 
-<!-- ⚠️ icon="info" renders as PLAIN TEXT. Use the icon slot for icon fonts. -->
-
-<!-- Icon SLOT — for Material Symbols, Font Awesome, SVGs -->
+<!-- Icon SLOT for Material Symbols, Font Awesome, SVGs -->
 <snice-alert variant="info">
   <span slot="icon" class="material-symbols-outlined">info</span>
   Information message
 </snice-alert>
 
-<!-- Icon PROPERTY — for emoji, URLs, image files only -->
-<snice-alert icon="🎉">Custom icon alert</snice-alert>
+<!-- Icon PROPERTY for emoji, URLs, image files only -->
 <snice-alert icon="/icons/info.svg">With image icon</snice-alert>
 
+<!-- No icon -->
+<snice-alert icon="none">No icon alert</snice-alert>
+
 <!-- Sizes -->
 <snice-alert size="small">Small</snice-alert>
-<snice-alert size="medium">Medium</snice-alert>
 <snice-alert size="large">Large</snice-alert>
 ```
 
-## Features
-
-- 4 variants with semantic colors
-- 3 size options
-- Optional title
-- Optional dismiss button
-- Custom icon support (URL, image files, emoji). Use slot for icon fonts.
-- Show/hide methods
-- Accessibility: role="alert"
-
-## Variants
+## Accessibility
 
-- `info` - Blue, informational
-- `success` - Green, positive feedback
-- `warning` - Orange, caution
-- `error` - Red, errors/problems
+- `role="alert"` with `aria-live="polite"`
+- Dismiss button is keyboard accessible
+- WCAG AA color contrast

package/docs/ai/components/app-tiles.md

@@ -1,17 +1,24 @@
-# snice-app-tiles
+# snice-app-tiles & snice-app-tile
 
 App launcher grid like Google's app drawer or a phone home screen.
 
+## Components
+
+### snice-app-tiles
+Container rendering a grid of tiles.
+
+### snice-app-tile
+Declarative child element. Attributes: `name`, `icon`, `color`, `href`, `badge`.
+
 ## Properties
 
 ```typescript
 // snice-app-tiles
-tiles: AppTile[] = [];           // Programmatic tile data
+tiles: AppTile[] = [];           // Programmatic tile data (set via JS)
 columns: number = 4;             // Grid columns
-size: 'sm' | 'md' | 'lg' | 'xl' | '2xl' = 'md'; // Tile size
-variant: 'grid' | 'list' | 'compact' = 'grid'; // Layout variant
+size: 'sm'|'md'|'lg'|'xl'|'2xl' = 'md';
+variant: 'grid'|'list'|'compact' = 'grid';
 
-// AppTile interface
 interface AppTile {
   id: string;
   name: string;
@@ -22,34 +29,23 @@ interface AppTile {
 }
 ```
 
-## Child Element
-
-`<snice-app-tile>` — declarative child for defining tiles in HTML.
-
-- `name` - Tile label
-- `icon` - URL, emoji, or Material Symbols ligature
-- `color` - Background color
-- `href` - Navigation URL
-- `badge` - Badge content
-
 ## Events
 
-- `tile-click` -> `{ tile: AppTile, index: number }`
+- `tile-click` → `{ tile: AppTile, index: number }`
 
-## Icon Resolution
+## Slots
 
-1. No icon -> letter fallback (first char of name, colored circle)
-2. `img://` prefix or URL/path -> `<img>` element
-3. Emoji (no ASCII letters) -> emoji display
-4. ASCII text -> Material Symbols ligature
+- `(default)` - `<snice-app-tile>` child elements for declarative mode
 
 ## CSS Custom Properties
 
-| Variable | Description |
-|----------|-------------|
-| `--snice-app-tile-icon-size` | Override icon container size (e.g. `7rem`) |
+- `--snice-app-tile-icon-size` - Override icon container size (e.g. `7rem`)
+
+## CSS Parts
 
-## Usage
+- `icon` - Material Symbols ligature icon span
+
+## Basic Usage
 
 ```html
 <!-- Declarative -->
@@ -69,20 +65,19 @@ tiles.tiles = [
   { id: '2', name: 'Slack', icon: 'https://example.com/slack.svg' },
 ];
 
-<!-- Letter fallback (no icon) -->
-<snice-app-tiles columns="3">
-  <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
-  <snice-app-tile name="GitHub" color="rgb(82 82 82)"></snice-app-tile>
-</snice-app-tiles>
+// Letter fallback (no icon)
+// <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
 
-<!-- Custom icon size via CSS variable -->
-<snice-app-tiles columns="3" style="--snice-app-tile-icon-size: 7rem">
-  <snice-app-tile name="Gallery" icon="collections" color="rgb(37 99 235)"></snice-app-tile>
-</snice-app-tiles>
+// List variant
+// <snice-app-tiles columns="1" variant="list">
 
-<!-- List variant -->
-<snice-app-tiles columns="1" variant="list">
-  <snice-app-tile name="Dashboard" icon="dashboard"></snice-app-tile>
-  <snice-app-tile name="Settings" icon="settings"></snice-app-tile>
-</snice-app-tiles>
+// Custom icon size
+// <snice-app-tiles style="--snice-app-tile-icon-size: 7rem">
 ```
+
+## Icon Resolution
+
+1. No icon -> letter fallback (first char of name, colored circle)
+2. `img://` prefix or URL/path -> `<img>` element
+3. Emoji (no ASCII letters) -> emoji display
+4. ASCII text -> Material Symbols ligature

package/docs/ai/components/approval-flow.md

@@ -40,7 +40,7 @@ interface ApprovalStep {
 - `actions` - Approve/reject button row
 - `connector` - Line between steps
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-approval-flow current-step="2" orientation="vertical"></snice-approval-flow>