snice 4.29.0 → 4.30.1

package/docs/ai/components/grid.md

@@ -0,0 +1,116 @@
+# snice-grid
+
+Grid-coordinate layout component. Items placed at explicit (col, row) positions with optional spanning. Collision resolution: swap-first, fallback push-right-then-down. Animated transitions, drag-and-drop with snap-to-grid.
+
+## Properties
+
+```typescript
+gap: string = '1rem';                           // spacing between cells
+columnWidth: number = 80;                       // column width in px -- attr: column-width
+rowHeight: number = 80;                         // row height in px -- attr: row-height
+columns: number = 0;                            // fixed column count (0 = auto) -- attr: columns
+rows: number = 0;                               // fixed row count (0 = auto) -- attr: rows
+originLeft: boolean = true;                     // false = right-to-left -- attr: origin-left
+originTop: boolean = true;                      // false = bottom-to-top -- attr: origin-top
+transitionDuration: string = '0.4s';            // CSS transition duration -- attr: transition-duration
+stagger: number = 0;                            // ms delay between each item transition
+resize: boolean = true;                         // auto re-layout on container resize
+draggable: boolean = false;                     // enable drag-to-reorder with snap-to-grid
+dragThrottle: number = 120;                     // ms throttle for drag layout updates -- attr: drag-throttle
+```
+
+## Item Attributes
+
+Set on child elements:
+
+- `grid-col` (number, default 0) -- column position (0-based)
+- `grid-row` (number, default 0) -- row position (0-based)
+- `grid-colspan` (number, default 1) -- columns to span
+- `grid-rowspan` (number, default 1) -- rows to span
+- `name` (string) -- identifier for getLayout/setLayout persistence
+- `hidden` -- hides item from layout
+
+## Methods
+
+- `layout()` - Full re-layout
+- `fit(element, col?, row?)` - Position specific item at grid coordinates, reflow others
+- `reloadItems()` - Re-collect items from DOM
+- `getItemElements()` - Get all layout items
+- `getLayout()` - Returns `GridLayout` (Record<string, GridLayoutEntry>) with positions/spans/order
+- `setLayout(layout)` - Apply saved layout (reorder, reposition, hide/show)
+
+## Events
+
+- `grid-layout-complete` -> `{ items: HTMLElement[] }`
+- `grid-drag-item-positioned` -> `{ item: HTMLElement, col: number, row: number }`
+
+## Slots
+
+- `(default)` - Items to place on grid (use grid-col/grid-row/grid-colspan/grid-rowspan attributes)
+
+## CSS Custom Properties
+
+- `--grid-gap` - Gap between cells (set via `gap` property)
+- `--grid-transition-duration` - Transition duration (set via `transition-duration` property)
+
+## CSS Parts
+
+- `base` - The inner container element
+
+## Types
+
+```typescript
+interface GridLayoutEntry {
+  col: number;
+  row: number;
+  colspan?: number;
+  rowspan?: number;
+  order: number;
+  hidden?: boolean;
+}
+
+type GridLayout = Record<string, GridLayoutEntry>;
+```
+
+## Basic Usage
+
+```html
+<snice-grid column-width="100" row-height="100" gap="8px">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="1" grid-row="0">B</div>
+  <div grid-col="0" grid-row="1" grid-colspan="2">Wide</div>
+</snice-grid>
+
+<!-- Draggable dashboard -->
+<snice-grid draggable column-width="80" row-height="80" gap="8px" columns="4">
+  <div grid-col="0" grid-row="0" name="a">A</div>
+  <div grid-col="1" grid-row="0" name="b">B</div>
+  <div grid-col="0" grid-row="1" name="c" grid-colspan="2">C</div>
+</snice-grid>
+
+<!-- Fixed grid -->
+<snice-grid column-width="80" row-height="80" columns="4" rows="3">
+  <div grid-col="0" grid-row="0">A</div>
+</snice-grid>
+```
+
+## Collision Resolution
+
+1. **Swap** -- single occupant in target area swaps positions with incoming item
+2. **Push-right-then-down** -- fallback if swap fails (multiple occupants or occupant doesn't fit at swap position)
+3. Column clamping: if `col + colspan > columns`, col is clamped to `columns - colspan`
+
+## Drag CSS Classes
+
+- `.grid-dragging` -- during drag (no transition, z-index: 100, opacity: 0.9, cursor: grabbing)
+- `.grid-positioning` -- animating to final position after drop (z-index: 99)
+
+## Notes
+
+- Items sized automatically from columnWidth/rowHeight + colspan/rowspan
+- Container uses `position: relative`, items get `position: absolute` + `transform`
+- Uses ResizeObserver on container for auto re-layout
+- FOUC prevented via `[ready]` attribute gating transitions
+- `contain: layout style` on `:host`
+- Inner container has `role="list"`
+- Dashed drop-placeholder shown during drag

package/docs/ai/patterns.md

@@ -467,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;
+```

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/grid.md

@@ -0,0 +1,249 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/grid.md -->
+
+# Grid Component
+`<snice-grid>`
+
+A grid-coordinate layout component. Items are placed at explicit grid positions using `grid-col` and `grid-row` attributes, and can span multiple cells with `grid-colspan` and `grid-rowspan`. Collision resolution uses swap-first with push-right-then-down fallback. Supports animated transitions and drag-and-drop with snap-to-grid.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `gap` | `gap` | `string` | `'1rem'` | Spacing between cells |
+| `columnWidth` | `column-width` | `number` | `80` | Width of each grid column in pixels |
+| `rowHeight` | `row-height` | `number` | `80` | Height of each grid row in pixels |
+| `columns` | `columns` | `number` | `0` | Fixed number of columns (0 = auto from content) |
+| `rows` | `rows` | `number` | `0` | Fixed number of rows (0 = auto from content) |
+| `originLeft` | `origin-left` | `boolean` | `true` | `false` = right-to-left |
+| `originTop` | `origin-top` | `boolean` | `true` | `false` = bottom-to-top |
+| `transitionDuration` | `transition-duration` | `string` | `'0.4s'` | CSS transition duration for item movement |
+| `stagger` | `stagger` | `number` | `0` | Delay in ms between each item's transition |
+| `resize` | `resize` | `boolean` | `true` | Auto re-layout on container resize |
+| `draggable` | `draggable` | `boolean` | `false` | Enable drag-to-reorder with snap-to-grid |
+| `dragThrottle` | `drag-throttle` | `number` | `120` | Throttle interval (ms) for drag layout updates |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `layout()` | -- | Perform a full re-layout |
+| `fit()` | `element: HTMLElement, col?: number, row?: number` | Position specific item at grid coordinates, reflow others |
+| `reloadItems()` | -- | Re-collect items from DOM |
+| `getItemElements()` | -- | Returns array of all layout items |
+| `getLayout()` | -- | Returns `GridLayout` object with item positions, spans, and order |
+| `setLayout()` | `layout: GridLayout` | Apply a saved layout (reorder, reposition, hide/show items) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `grid-layout-complete` | `{ items: HTMLElement[] }` | Fired after layout completes |
+| `grid-drag-item-positioned` | `{ item: HTMLElement, col: number, row: number }` | Fired after a dragged item settles into its new grid position |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Items to place on the grid. Use `grid-col`, `grid-row`, `grid-colspan`, `grid-rowspan` attributes on each item to control placement. |
+
+### Item Attributes
+
+These attributes are set on child elements (not on `<snice-grid>` itself):
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `grid-col` | `number` | `0` | Column position (0-based) |
+| `grid-row` | `number` | `0` | Row position (0-based) |
+| `grid-colspan` | `number` | `1` | Number of columns to span |
+| `grid-rowspan` | `number` | `1` | Number of rows to span |
+| `name` | `string` | -- | Identifier used by `getLayout()`/`setLayout()` for persistence |
+| `hidden` | `boolean` | -- | Hides the item from layout |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--grid-gap` | Gap between cells (set via `gap` property) | `1rem` |
+| `--grid-transition-duration` | Transition duration for item movement (set via `transition-duration` property) | `0.4s` |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The inner container element |
+
+## Basic Usage
+
+```typescript
+import 'snice/components/grid/snice-grid';
+```
+
+```html
+<snice-grid column-width="100" row-height="100" gap="8px">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="1" grid-row="0">B</div>
+  <div grid-col="0" grid-row="1">C</div>
+</snice-grid>
+```
+
+Items are sized automatically based on `columnWidth`, `rowHeight`, and their `grid-colspan`/`grid-rowspan` values.
+
+## Examples
+
+### Spanning Multiple Cells
+
+Use `grid-colspan` and `grid-rowspan` to make items span multiple columns or rows.
+
+```html
+<snice-grid column-width="80" row-height="80" gap="8px">
+  <div grid-col="0" grid-row="0" grid-colspan="2" grid-rowspan="2">Large</div>
+  <div grid-col="2" grid-row="0">Small A</div>
+  <div grid-col="2" grid-row="1">Small B</div>
+  <div grid-col="0" grid-row="2" grid-colspan="3">Wide</div>
+</snice-grid>
+```
+
+### Collision Resolution
+
+When two items request the same grid position, the component resolves collisions automatically:
+
+1. **Swap** -- If the target cell has a single occupant, the two items swap positions.
+2. **Push-right-then-down** -- If swap fails (multiple occupants or the swapped item doesn't fit), the incoming item is pushed to the next free cell scanning right, then down.
+
+```html
+<snice-grid column-width="80" row-height="80" gap="8px">
+  <!-- Both request (0,0): the second item will be pushed to (1,0) -->
+  <div grid-col="0" grid-row="0">First</div>
+  <div grid-col="0" grid-row="0">Second</div>
+</snice-grid>
+```
+
+### Fixed Grid Size
+
+Set `columns` and/or `rows` to constrain the grid. Items that exceed the column limit are wrapped to the next row.
+
+```html
+<snice-grid column-width="100" row-height="100" gap="8px" columns="4" rows="3">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="3" grid-row="0" grid-colspan="2">B (clamped to fit)</div>
+</snice-grid>
+```
+
+When an item's `col + colspan` exceeds the column count, its column position is clamped to `columns - colspan`.
+
+### Draggable with Snap-to-Grid
+
+Enable `draggable` to let users drag items. Items snap to the nearest grid cell during and after drag.
+
+```html
+<snice-grid draggable column-width="80" row-height="80" gap="8px" columns="4">
+  <div grid-col="0" grid-row="0" name="widget-a">Widget A</div>
+  <div grid-col="1" grid-row="0" name="widget-b">Widget B</div>
+  <div grid-col="0" grid-row="1" name="widget-c" grid-colspan="2">Widget C</div>
+</snice-grid>
+```
+
+A dashed drop-placeholder shows the target cell during drag. CSS classes applied during drag:
+
+- `.grid-dragging` -- applied during drag (no transition, z-index: 100, opacity: 0.9, cursor: grabbing)
+- `.grid-positioning` -- applied while animating to final position after drop (z-index: 99)
+
+```javascript
+const grid = document.querySelector('snice-grid');
+grid.addEventListener('grid-drag-item-positioned', (e) => {
+  const { item, col, row } = e.detail;
+  console.log(`${item.getAttribute('name')} dropped at col=${col} row=${row}`);
+});
+```
+
+### Staggered Transitions
+
+Use `stagger` to add incremental delay between each item's transition.
+
+```html
+<snice-grid column-width="80" row-height="80" transition-duration="0.6s" stagger="40">
+  <div grid-col="0" grid-row="0">A</div>
+  <div grid-col="1" grid-row="0">B</div>
+  <div grid-col="2" grid-row="0">C</div>
+</snice-grid>
+```
+
+### Right-to-Left / Bottom-to-Top
+
+Set `origin-left="false"` or `origin-top="false"` to change the coordinate origin.
+
+```html
+<snice-grid column-width="80" row-height="80" origin-left="false">
+  <div grid-col="0" grid-row="0">Aligned right</div>
+</snice-grid>
+```
+
+### Save and Restore Layout
+
+Use `getLayout()` and `setLayout()` to persist item arrangement. Items must have a `name` attribute.
+
+```javascript
+const grid = document.querySelector('snice-grid');
+
+// Save
+const layout = grid.getLayout();
+localStorage.setItem('dashboard', JSON.stringify(layout));
+
+// Restore
+const saved = JSON.parse(localStorage.getItem('dashboard'));
+grid.setLayout(saved);
+```
+
+The `GridLayout` object is a `Record<string, GridLayoutEntry>` keyed by item name:
+
+```typescript
+interface GridLayoutEntry {
+  col: number;
+  row: number;
+  colspan?: number;
+  rowspan?: number;
+  order: number;
+  hidden?: boolean;
+}
+```
+
+### Dynamic Items
+
+Items can be added or removed dynamically. The layout automatically updates via slot change detection.
+
+```javascript
+const grid = document.querySelector('snice-grid');
+
+// Add an item
+const item = document.createElement('div');
+item.setAttribute('grid-col', '2');
+item.setAttribute('grid-row', '0');
+grid.appendChild(item);
+
+// Remove an item
+grid.lastElementChild.remove();
+```
+
+## Accessibility
+
+- The inner container has `role="list"` for screen reader navigation.
+- When `draggable` is enabled, items show `cursor: grab` (and `cursor: grabbing` during drag).
+
+### Notes
+
+- Items are absolutely positioned using `transform` for smooth transitions.
+- Item width/height is computed automatically from `columnWidth`, `rowHeight`, `colspan`, and `rowspan`.
+- Uses `ResizeObserver` on the container for automatic re-layout when `resize` is `true`.
+- FOUC is prevented by gating transitions behind the `[ready]` attribute.
+- Uses `contain: layout style` on `:host`.

package/docs/plans/2026-03-10-grid-component-design.md

@@ -0,0 +1,138 @@
+# snice-grid Component Design
+
+## Concept
+Explicit grid-coordinate placement with animated transitions and drag-and-drop. Items declare their position in grid units (col, row); the component translates to pixel positions. Collision resolution via push-right-then-down.
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `gap` | string | `"1rem"` | Gap between cells (CSS value) |
+| `column-width` | number | `80` | Cell width in px |
+| `row-height` | number | `80` | Cell height in px |
+| `columns` | number | `0` | Max columns (0 = auto-grow) |
+| `rows` | number | `0` | Max rows (0 = auto-grow) |
+| `origin-left` | boolean | `true` | RTL support |
+| `origin-top` | boolean | `true` | Bottom-origin support |
+| `transition-duration` | string | `"0.4s"` | Animation speed |
+| `stagger` | number | `0` | Cascade delay (ms) per item |
+| `resize` | boolean | `true` | ResizeObserver relayout |
+| `draggable` | boolean | `false` | Enable drag-and-drop |
+| `drag-throttle` | number | `100` | Drag relayout throttle (ms) |
+
+## Item Attributes (on slotted children)
+
+| Attribute | Default | Description |
+|---|---|---|
+| `name` | required | Unique item identifier |
+| `grid-col` | `0` | Column position |
+| `grid-row` | `0` | Row position |
+| `grid-colspan` | `1` | Columns spanned |
+| `grid-rowspan` | `1` | Rows spanned |
+| `hidden` | — | Hides item from layout |
+
+## Pixel Calculation
+
+```
+x = col × (columnWidth + gap)
+y = row × (rowHeight + gap)
+width = colspan × columnWidth + (colspan - 1) × gap
+height = rowspan × rowHeight + (rowspan - 1) × gap
+```
+
+Items are auto-sized to their grid cell dimensions.
+
+## Collision Resolution
+
+**Push-right-then-down**: When item A is placed at an occupied cell, the existing item shifts right to the next open cell that fits it (accounting for colspan/rowspan). If no room remains in that row, wraps to column 0 of the next row. Cascading — if the displaced item lands on another occupied area, that item pushes too.
+
+When `columns` is set, "no room in row" means hitting the column limit. When `rows` is also set and the grid is completely full, the last displaced item goes out of bounds (clipped by `overflow: hidden`).
+
+## Drag Behavior
+
+Same as binpack: free drag during gesture, on release snap to nearest grid cell. If that cell is occupied, push-right-then-down resolution kicks in. Dashed placeholder outline shows target cell during drag.
+
+## Container Sizing
+
+- `columns`/`rows` unset (0): container grows to fit furthest item edge
+- `columns` and/or `rows` set: fixed size with `overflow: hidden`
+- Individual items can be hidden via `hidden` attribute (same as binpack)
+
+## Public API
+
+```ts
+interface SniceGridElement extends HTMLElement {
+  gap: string;
+  columnWidth: number;
+  rowHeight: number;
+  columns: number;
+  rows: number;
+  horizontal: boolean;
+  originLeft: boolean;
+  originTop: boolean;
+  transitionDuration: string;
+  stagger: number;
+  resize: boolean;
+  draggable: boolean;
+  dragThrottle: number;
+
+  layout(): void;
+  fit(element: HTMLElement, col?: number, row?: number): void;
+  reloadItems(): void;
+  getItemElements(): HTMLElement[];
+  getLayout(): GridLayout;
+  setLayout(layout: GridLayout): void;
+}
+```
+
+## Types
+
+```ts
+interface GridLayoutEntry {
+  col: number;
+  row: number;
+  colspan?: number;  // default 1
+  rowspan?: number;  // default 1
+  order: number;
+  hidden?: boolean;
+}
+
+type GridLayout = Record<string, GridLayoutEntry>;
+
+interface GridLayoutCompleteDetail {
+  items: HTMLElement[];
+}
+
+interface GridDragItemPositionedDetail {
+  item: HTMLElement;
+  col: number;
+  row: number;
+}
+
+interface GridEventMap {
+  'grid-layout-complete': CustomEvent<GridLayoutCompleteDetail>;
+  'grid-drag-item-positioned': CustomEvent<GridDragItemPositionedDetail>;
+}
+```
+
+## CSS Custom Properties
+
+- `--grid-gap` (maps to gap property)
+- `--grid-transition-duration` (maps to transitionDuration property)
+
+## CSS Structure
+
+- `:host` — `display: block; position: relative; overflow: hidden` (when columns/rows set)
+- `::slotted(*)` — `position: absolute; box-sizing: border-box`
+- `:host([ready]) ::slotted(*)` — transition on transform (FOUC gate)
+- Dragging/placeholder styles identical to binpack pattern
+
+## Shared Patterns with Binpack
+
+- `[ready]` attribute for FOUC prevention
+- `name` attribute for item identification
+- `getLayout()`/`setLayout()` for persistence
+- Stagger animation delay
+- ResizeObserver relayout
+- Drag placeholder with dashed outline
+- Same event naming convention