@rinzai/zen 0.13.0 → 0.15.0

package/dist/docs/calendar.md

@@ -0,0 +1,101 @@
+# Calendar
+
+A month grid to pick a date or a range, fully keyboard-driven, with limits, blocked days and a year view to jump far.
+
+```tsx
+import { Calendar } from '@rinzai/zen';
+```
+
+## Examples
+
+### Default
+
+```tsx
+import { Calendar, formatDate } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Click a day, or use the keyboard: arrows, Home/End, Page Up/Down (Shift for years). The title jumps to any month and year. */
+export default function Default() {
+    const [date, setDate] = useState<string | null>('2026-09-30');
+    return (
+        <div className="flex flex-col items-center gap-3">
+            <Calendar value={date} onValueChange={setDate} locale="en-US" />
+            <p className="text-muted-foreground mt-0! text-xs">
+                {date ? formatDate(date, 'en-US', 'full') : 'No date'}
+            </p>
+        </div>
+    );
+}
+```
+
+### Range
+
+```tsx
+import { Calendar, type DateRange, daysBetween, formatDateRange } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Two months side by side: pick a start, then an end. The days between are previewed as you point. */
+export default function Range() {
+    const [range, setRange] = useState<DateRange | null>({ start: '2026-10-05', end: '2026-10-12' });
+    return (
+        <div className="flex flex-col items-center gap-3">
+            <Calendar mode="range" months={2} value={range} onValueChange={setRange} locale="en-GB" />
+            <p className="text-muted-foreground mt-0! text-xs">
+                {range?.end
+                    ? `${formatDateRange(range.start, range.end, 'en-GB')} · ${daysBetween(range.start, range.end) + 1} days`
+                    : 'Pick the last day'}
+            </p>
+        </div>
+    );
+}
+```
+
+### Limits
+
+```tsx
+import { addDays, Calendar, dayOfWeek, today } from '@rinzai/zen';
+import { useState } from 'react';
+
+/** Only the next 60 days, and no weekends: min, max and isDisabled. Weeks start on Monday here, whatever the locale. */
+export default function Limits() {
+    const start = today();
+    const [date, setDate] = useState<string | null>(null);
+    return (
+        <Calendar
+            value={date}
+            onValueChange={setDate}
+            locale="en-US"
+            weekStartsOn={1}
+            min={start}
+            max={addDays(start, 60)}
+            isDisabled={(d) => dayOfWeek(d) === 0 || dayOfWeek(d) === 6}
+        />
+    );
+}
+```
+
+## API reference
+
+### Calendar
+
+A month grid to pick a date, or a range of dates, fully keyboard-driven:
+arrows move by day and week, Home and End to the week's ends, Page Up and
+Down by month (with Shift, by year). The title opens a year and month grid
+to jump far. Dates are "YYYY-MM-DD" strings, so they never shift a day with
+time zones. Inline on a page, or in a popup with DatePicker.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoFocus` | `boolean` |  | Focus the chosen date (or today) when shown, e.g. in a popup. |
+| `className` | `string` |  |  |
+| `defaultMonth` | `string` |  | Month shown first ("YYYY-MM"). Defaults to the chosen date's, or this month. |
+| `defaultValue` | `DateRange \| string \| null` |  | The first date, when the calendar keeps its own. The first range, when the calendar keeps its own. |
+| `isDisabled` | `((date: string) => boolean)` |  | Dates that can't be picked, e.g. weekends or booked days. |
+| `locale` | `string` |  | Decides month and weekday names, and the first day of the week, e.g. "en-IN". Defaults to the LocaleProvider's. |
+| `max` | `string` |  | Latest date that can be picked. |
+| `min` | `string` |  | Earliest date that can be picked ("YYYY-MM-DD"). |
+| `mode` | `"range" \| "single"` |  | Pick a start and then an end; the days between are highlighted, previewed while pointing. |
+| `months` | `number` |  | Months shown side by side (e.g. 2 for ranges). |
+| `onValueChange` | `((date: string) => void) \| ((range: DateRange) => void)` |  |  |
+| `value` | `DateRange \| string \| null` |  | "YYYY-MM-DD", or null for none, when you keep it. The range when you keep it; `end` is null while only the start is picked. |
+| `weekStartsOn` | `number` |  | 0 for Sunday … 6 for Saturday. Defaults to the locale's. |

package/dist/docs/canvas.md

@@ -0,0 +1,584 @@
+# Canvas
+
+A fixed-size surface where items sit anywhere, like the cards of a stream overlay: drag, resize and select several, by pointer, touch or keyboard, with snapping, a grid, undo and a fit-to-width scale.
+
+```tsx
+import { Canvas, CanvasItem } from '@rinzai/zen';
+```
+
+## Examples
+
+### Designer
+
+```tsx
+import {
+    Button,
+    Canvas,
+    CanvasItem,
+    type CanvasItemRect,
+    ColorPicker,
+    InputGroup,
+    InputGroupAddon,
+    InputGroupInput,
+    Kbd,
+    SortableHandle,
+    SortableItem,
+    SortableList,
+    cx,
+} from '@rinzai/zen';
+import { KeyboardEvent, useRef, useState } from 'react';
+
+interface Layer extends CanvasItemRect {
+    kind: 'text' | 'bar' | 'image';
+    name: string;
+    color: string;
+}
+
+const W = 640;
+const H = 360;
+
+const START: Layer[] = [
+    { id: 'scene', kind: 'image', name: 'Backdrop', color: '#1b1630', x: 0, y: 0, w: W, h: H, locked: true },
+    { id: 'cam', kind: 'image', name: 'Camera', color: '#7c5cff', x: 404, y: 20, w: 216, h: 122 },
+    { id: 'title', kind: 'text', name: 'Title', color: '#ffffff', x: 24, y: 252, w: 300, h: 40 },
+    { id: 'goal', kind: 'bar', name: 'Sub goal', color: '#2bb3a3', x: 24, y: 304, w: 300, h: 16 },
+];
+
+const NEW: Record<Layer['kind'], Omit<Layer, 'id' | 'x' | 'y'>> = {
+    text: { kind: 'text', name: 'Text', color: '#ffffff', w: 200, h: 32 },
+    bar: { kind: 'bar', name: 'Bar', color: '#f0a83a', w: 220, h: 14 },
+    image: { kind: 'image', name: 'Image', color: '#ef5a7a', w: 120, h: 120 },
+};
+
+/**
+ * A small overlay designer: a 640×360 scene that fits its width, a layers list whose order is the
+ * stacking (drag to reorder), and an inspector for the selected card. `onItemsChangeEnd` gives each change
+ * with the items before it, which is all Undo needs. Try `⌘Z`, `⇧⌘Z` and `Delete`.
+ */
+export default function Designer() {
+    const [items, setItems] = useState(START);
+    const [selected, setSelected] = useState<string[]>(['title']);
+    const [past, setPast] = useState<Layer[][]>([]);
+    const [future, setFuture] = useState<Layer[][]>([]);
+    const editing = useRef<Layer[] | null>(null);
+    const count = useRef(0);
+
+    const remember = (before: Layer[]) => {
+        setPast((p) => [...p, before]);
+        setFuture([]);
+    };
+    const commit = (next: Layer[]) => {
+        remember(items);
+        setItems(next);
+    };
+    // Live edits (a colour being dragged) become one step of history when they end.
+    const live = (next: Layer[]) => {
+        editing.current ??= items;
+        setItems(next);
+    };
+    const settle = () => {
+        if (editing.current) remember(editing.current);
+        editing.current = null;
+    };
+    const undo = () => {
+        if (!past.length) return;
+        setFuture((f) => [items, ...f]);
+        setItems(past[past.length - 1]);
+        setPast((p) => p.slice(0, -1));
+    };
+    const redo = () => {
+        if (!future.length) return;
+        setPast((p) => [...p, items]);
+        setItems(future[0]);
+        setFuture((f) => f.slice(1));
+    };
+    const add = (kind: Layer['kind']) => {
+        const id = `${kind}-${++count.current}`;
+        const base = NEW[kind];
+        commit([
+            ...items,
+            { ...base, id, name: `${base.name} ${count.current}`, x: (W - base.w) / 2, y: (H - base.h) / 2 },
+        ]);
+        setSelected([id]);
+    };
+    const remove = () => {
+        const gone = new Set(selected.filter((id) => !items.find((i) => i.id === id)?.locked));
+        if (!gone.size) return;
+        commit(items.filter((i) => !gone.has(i.id)));
+        setSelected([]);
+    };
+    const onKeyDown = (e: KeyboardEvent) => {
+        const mod = e.metaKey || e.ctrlKey;
+        if (mod && e.key.toLowerCase() === 'z') {
+            e.preventDefault();
+            if (e.shiftKey) redo();
+            else undo();
+        } else if ((e.key === 'Delete' || e.key === 'Backspace') && (e.target as Element).closest('[data-canvas-id]')) {
+            e.preventDefault();
+            remove();
+        }
+    };
+
+    // Top of the stack first; the locked backdrop stays at the bottom.
+    const layers = items.filter((i) => !i.locked).reverse();
+    const one = selected.length === 1 ? items.find((i) => i.id === selected[0]) : undefined;
+    const update = (patch: Partial<Layer>) =>
+        one && commit(items.map((i) => (i.id === one.id ? { ...i, ...patch } : i)));
+    const field = (key: 'x' | 'y' | 'w' | 'h', max: number) => (
+        <InputGroup className="h-9">
+            <InputGroupAddon className="w-3 uppercase">{key}</InputGroupAddon>
+            <InputGroupInput
+                type="number"
+                aria-label={{ x: 'X', y: 'Y', w: 'Width', h: 'Height' }[key]}
+                value={one?.[key] ?? ''}
+                disabled={!one || one.locked}
+                min={0}
+                max={max}
+                onChange={(e) => {
+                    const v = Math.round(Number(e.target.value));
+                    if (one && Number.isFinite(v))
+                        update({ [key]: Math.min(max, Math.max(key === 'w' || key === 'h' ? 8 : 0, v)) });
+                }}
+                className="tabular-nums"
+            />
+        </InputGroup>
+    );
+
+    return (
+        <div className="flex w-full max-w-3xl flex-col gap-4" onKeyDown={onKeyDown}>
+            <div className="flex flex-wrap items-center gap-2">
+                <Button size="sm" variant="secondary" onClick={() => add('text')}>
+                    Text
+                </Button>
+                <Button size="sm" variant="secondary" onClick={() => add('bar')}>
+                    Bar
+                </Button>
+                <Button size="sm" variant="secondary" onClick={() => add('image')}>
+                    Image
+                </Button>
+                <span className="flex-1" />
+                <Button size="sm" variant="ghost" onClick={undo} disabled={!past.length}>
+                    Undo
+                </Button>
+                <Button size="sm" variant="ghost" onClick={redo} disabled={!future.length}>
+                    Redo
+                </Button>
+                <Button size="sm" variant="ghost" tone="negative" onClick={remove} disabled={!selected.length}>
+                    Delete
+                </Button>
+            </div>
+
+            <Canvas
+                aria-label="Scene"
+                width={W}
+                height={H}
+                scale="fit"
+                snap
+                items={items}
+                onItemsChange={setItems}
+                onItemsChangeEnd={(_, before) => remember([...before])}
+                selected={selected}
+                onSelectedChange={setSelected}
+            >
+                {items.map((layer) => (
+                    <CanvasItem key={layer.id} id={layer.id} label={layer.name} className="flex items-center">
+                        {layer.kind === 'text' && (
+                            <span
+                                className="truncate font-semibold tracking-tight"
+                                style={{ color: layer.color, fontSize: layer.h * 0.72, lineHeight: 1 }}
+                            >
+                                Live in 5 minutes
+                            </span>
+                        )}
+                        {layer.kind === 'bar' && (
+                            <div className="size-full overflow-hidden rounded-full bg-white/10">
+                                <div className="h-full w-3/5 rounded-full" style={{ background: layer.color }} />
+                            </div>
+                        )}
+                        {layer.kind === 'image' && (
+                            <div
+                                className={cx('size-full', !layer.locked && 'rounded-xl')}
+                                style={{
+                                    background: layer.locked
+                                        ? `radial-gradient(ellipse at 20% 0%, ${layer.color}, #0b0a12 70%)`
+                                        : `radial-gradient(circle at 30% 25%, color-mix(in oklch, ${layer.color} 70%, white), ${layer.color})`,
+                                }}
+                            />
+                        )}
+                    </CanvasItem>
+                ))}
+            </Canvas>
+
+            <div className="grid gap-4 sm:grid-cols-2">
+                <section className="flex flex-col gap-2">
+                    <h4 className="text-muted-foreground m-0! text-xs font-medium tracking-widest uppercase">Layers</h4>
+                    <SortableList
+                        aria-label="Layers"
+                        value={layers.map((i) => i.id)}
+                        onValueChange={(order) =>
+                            commit([
+                                ...items.filter((i) => i.locked),
+                                ...[...order].reverse().map((id) => items.find((i) => i.id === id)!),
+                            ])
+                        }
+                    >
+                        {layers.map((layer) => (
+                            <SortableItem
+                                key={layer.id}
+                                id={layer.id}
+                                className={cx(
+                                    'flex items-center gap-1 rounded-lg pr-2',
+                                    selected.includes(layer.id) && 'bg-primary/10',
+                                )}
+                            >
+                                <SortableHandle id={layer.id} label={layer.name} />
+                                <button
+                                    type="button"
+                                    onClick={() => setSelected([layer.id])}
+                                    className="flex min-w-0 flex-1 cursor-pointer items-center gap-2 py-1.5 text-left text-sm outline-hidden"
+                                >
+                                    <span
+                                        aria-hidden
+                                        className="size-3 shrink-0 rounded-sm"
+                                        style={{ background: layer.color }}
+                                    />
+                                    <span className="truncate">{layer.name}</span>
+                                </button>
+                            </SortableItem>
+                        ))}
+                    </SortableList>
+                    {items
+                        .filter((i) => i.locked)
+                        .map((layer) => (
+                            <p
+                                key={layer.id}
+                                className="text-muted-foreground mt-0! flex items-center gap-2 py-1.5 pl-9 text-sm"
+                            >
+                                <span
+                                    aria-hidden
+                                    className="size-3 shrink-0 rounded-sm"
+                                    style={{ background: layer.color }}
+                                />
+                                {layer.name}
+                                <span className="ml-auto pr-2 text-xs">Locked</span>
+                            </p>
+                        ))}
+                </section>
+                <section className="flex flex-col gap-2">
+                    <h4 className="text-muted-foreground m-0! text-xs font-medium tracking-widest uppercase">
+                        {one ? one.name : selected.length ? `${selected.length} selected` : 'Nothing selected'}
+                    </h4>
+                    <div className="grid grid-cols-2 gap-2">
+                        {field('x', W)}
+                        {field('y', H)}
+                        {field('w', W)}
+                        {field('h', H)}
+                    </div>
+                    <ColorPicker
+                        aria-label="Colour"
+                        value={one?.color ?? '#000000'}
+                        disabled={!one}
+                        onValueChange={(color) =>
+                            one && live(items.map((i) => (i.id === one.id ? { ...i, color } : i)))
+                        }
+                        onValueCommit={settle}
+                    />
+                    <p className="text-muted-foreground mt-0! text-xs">
+                        <Kbd>Shift</Kbd> keeps a card's shape as you resize; draw a box to select several.
+                    </p>
+                </section>
+            </div>
+        </div>
+    );
+}
+```
+
+### Dashboard
+
+```tsx
+import { Canvas, CanvasItem, type CanvasItemRect, Meter, Sparkline, Stat, StatusPill } from '@rinzai/zen';
+import { ReactNode, useState } from 'react';
+
+const WIDGETS: Record<string, { label: string; render: () => ReactNode }> = {
+    spent: {
+        label: 'Spent',
+        render: () => (
+            <Stat label="Spent" value="$2,742" tone="negative" className="size-full">
+                <Sparkline
+                    values={[40, 52, 48, 61, 58, 66, 72, 69, 80]}
+                    tone="negative"
+                    area
+                    className="mt-2 h-auto min-h-0 w-full flex-1"
+                />
+            </Stat>
+        ),
+    },
+    left: {
+        label: 'Left to spend',
+        render: () => <Stat label="Left to spend" value="$1,258" tone="positive" className="size-full" />,
+    },
+    budgets: {
+        label: 'Budgets',
+        render: () => (
+            <div className="glass glow-edge flex size-full flex-col gap-4 rounded-xl p-3.5 md:p-4">
+                <span className="text-muted-foreground text-2xs tracking-widest uppercase sm:text-xs">Budgets</span>
+                <Meter label="Groceries" value={207} max={600} detail="$207 / $600" />
+                <Meter label="Dining out" value={170} max={150} detail="$170 / $150" />
+                <Meter label="Transport" value={64} max={120} detail="$64 / $120" />
+                <Meter label="Bills" value={310} max={340} detail="$310 / $340" />
+            </div>
+        ),
+    },
+    balance: {
+        label: 'Balance',
+        render: () => (
+            <Stat label="Balance" value="$18,400" className="size-full">
+                <Sparkline
+                    values={[12, 13, 13.5, 14, 15.2, 15, 16.4, 17.1, 18.4]}
+                    area
+                    className="mt-2 h-auto min-h-0 w-full flex-1"
+                />
+            </Stat>
+        ),
+    },
+};
+
+/**
+ * A dashboard you lay out yourself: widgets on a 20-unit `grid`, lining up with each other as you drag
+ * (`snap`), with `minSize` so none gets too small. Widgets are any content; here Stat, Meter and
+ * Sparkline. `onItemsChangeEnd` is the moment to save the layout.
+ */
+export default function Dashboard() {
+    const [items, setItems] = useState<CanvasItemRect[]>([
+        { id: 'spent', x: 0, y: 0, w: 220, h: 140 },
+        { id: 'left', x: 240, y: 0, w: 220, h: 140 },
+        { id: 'budgets', x: 480, y: 0, w: 240, h: 300 },
+        { id: 'balance', x: 0, y: 160, w: 460, h: 140 },
+    ]);
+    const [selected, setSelected] = useState<string[]>([]);
+    const [saves, setSaves] = useState(0);
+    return (
+        <div className="flex w-full max-w-3xl flex-col gap-3">
+            <Canvas
+                aria-label="Dashboard"
+                width={720}
+                height={300}
+                scale="fit"
+                snap
+                grid={20}
+                minSize={100}
+                items={items}
+                onItemsChange={setItems}
+                onItemsChangeEnd={() => setSaves((n) => n + 1)}
+                selected={selected}
+                onSelectedChange={setSelected}
+                className="bg-transparent shadow-none"
+            >
+                {items.map((item) => (
+                    <CanvasItem key={item.id} id={item.id} label={WIDGETS[item.id].label} className="rounded-xl">
+                        {WIDGETS[item.id].render()}
+                    </CanvasItem>
+                ))}
+            </Canvas>
+            <div className="flex justify-end">
+                <StatusPill tone={saves ? 'positive' : 'default'} quiet={!saves}>
+                    {saves ? `Layout saved (${saves})` : 'Drag a widget, or a handle to resize it'}
+                </StatusPill>
+            </div>
+        </div>
+    );
+}
+```
+
+### Notes
+
+```tsx
+import { Button, Canvas, CanvasItem, type CanvasItemRect, Textarea } from '@rinzai/zen';
+import { useRef, useState } from 'react';
+
+interface Note extends CanvasItemRect {
+    text: string;
+    color: string;
+}
+
+const COLORS = ['var(--chart-4)', 'var(--chart-3)', 'var(--chart-5)', 'var(--chart-1)'];
+
+/**
+ * Sticky notes with a field in each: typing, selecting text and the × button work as usual, because
+ * presses on fields and buttons inside an item go to them. Drag a note by its edge or top strip.
+ */
+export default function Notes() {
+    const [notes, setNotes] = useState<Note[]>([
+        { id: 'n1', x: 24, y: 24, w: 170, h: 150, color: COLORS[0], text: 'Rent goes out on the 1st' },
+        { id: 'n2', x: 220, y: 60, w: 170, h: 150, color: COLORS[1], text: 'Move $400 to the holiday fund' },
+        { id: 'n3', x: 420, y: 30, w: 170, h: 150, color: COLORS[2], text: 'Cancel the old phone plan' },
+    ]);
+    const [selected, setSelected] = useState<string[]>([]);
+    const count = useRef(notes.length);
+    const edit = (id: string, patch: Partial<Note>) =>
+        setNotes((all) => all.map((n) => (n.id === id ? { ...n, ...patch } : n)));
+
+    return (
+        <div className="flex w-full max-w-3xl flex-col gap-3">
+            <Canvas
+                aria-label="Notes"
+                width={620}
+                height={260}
+                scale="fit"
+                minSize={120}
+                items={notes}
+                onItemsChange={setNotes}
+                selected={selected}
+                onSelectedChange={setSelected}
+            >
+                {notes.map((note, i) => (
+                    <CanvasItem
+                        key={note.id}
+                        id={note.id}
+                        label={`Note ${i + 1}`}
+                        style={{ background: `color-mix(in oklch, ${note.color} 22%, oklch(var(--card)))` }}
+                        className="flex flex-col overflow-hidden rounded-xl shadow-[0_10px_30px_-12px_oklch(0_0_0/0.6)]"
+                    >
+                        <div className="flex h-7 shrink-0 items-center justify-between pr-1 pl-3">
+                            <span aria-hidden className="h-1 w-8 rounded-full" style={{ background: note.color }} />
+                            <button
+                                type="button"
+                                aria-label={`Remove note ${i + 1}`}
+                                onClick={() => setNotes((all) => all.filter((n) => n.id !== note.id))}
+                                className="text-muted-foreground hover:text-foreground grid size-6 cursor-pointer place-items-center rounded-md"
+                            >
+                                ×
+                            </button>
+                        </div>
+                        <Textarea
+                            aria-label={`Note ${i + 1}`}
+                            value={note.text}
+                            onChange={(e) => edit(note.id, { text: e.target.value })}
+                            className="min-h-0 flex-1 resize-none rounded-none border-0 bg-transparent px-3 pt-0 shadow-none"
+                        />
+                    </CanvasItem>
+                ))}
+            </Canvas>
+            <div>
+                <Button
+                    size="sm"
+                    variant="secondary"
+                    onClick={() => {
+                        const id = `n${++count.current}`;
+                        setNotes((all) => [
+                            ...all,
+                            {
+                                id,
+                                x: 225,
+                                y: 55,
+                                w: 170,
+                                h: 150,
+                                color: COLORS[count.current % COLORS.length],
+                                text: '',
+                            },
+                        ]);
+                        setSelected([id]);
+                    }}
+                >
+                    Add a note
+                </Button>
+            </div>
+        </div>
+    );
+}
+```
+
+### Snapping
+
+```tsx
+import { Canvas, CanvasItem, type CanvasItemRect, Segmented, SegmentedItem } from '@rinzai/zen';
+import { useState } from 'react';
+
+type Mode = 'off' | 'guides' | 'grid';
+
+/** Off: items go where you drop them. Guides (`snap`): edges and centres line up with the surface and each other. Grid (`grid`, here with `snap`): they keep to a 20-unit grid, its dots showing while you drag. */
+export default function Snapping() {
+    const [mode, setMode] = useState<Mode>('guides');
+    const [items, setItems] = useState<CanvasItemRect[]>([
+        { id: 'a', x: 20, y: 20, w: 120, h: 70 },
+        { id: 'b', x: 210, y: 70, w: 100, h: 100 },
+        { id: 'c', x: 330, y: 30, w: 100, h: 40 },
+    ]);
+    const [selected, setSelected] = useState<string[]>([]);
+    return (
+        <div className="flex flex-col items-start gap-3">
+            <Segmented label="Snapping" value={mode} onValueChange={setMode}>
+                <SegmentedItem value="off">Off</SegmentedItem>
+                <SegmentedItem value="guides">Guides</SegmentedItem>
+                <SegmentedItem value="grid">Grid</SegmentedItem>
+            </Segmented>
+            <Canvas
+                aria-label="Layout"
+                width={460}
+                height={220}
+                snap={mode !== 'off'}
+                grid={mode === 'grid' ? 20 : undefined}
+                items={items}
+                onItemsChange={setItems}
+                selected={selected}
+                onSelectedChange={setSelected}
+            >
+                {items.map((item, n) => (
+                    <CanvasItem
+                        key={item.id}
+                        id={item.id}
+                        label={`Card ${n + 1}`}
+                        className="glass text-muted-foreground grid place-items-center rounded-lg text-sm tabular-nums"
+                    >
+                        {item.x}, {item.y}
+                    </CanvasItem>
+                ))}
+            </Canvas>
+        </div>
+    );
+}
+```
+
+## API reference
+
+### Canvas
+
+A fixed-size surface where items sit anywhere, such as the cards of a
+stream overlay or a slide. Drag an item to move it, and the handles of the
+selected one to resize it (Shift keeps its shape); Escape mid-drag puts it
+back. Shift- or Cmd-click, or drag a box on empty space, to select several
+and move them together. From the keyboard, Tab reaches each item, the arrow
+keys move the selection (Shift by 10), Alt and the arrow keys resize, Cmd or
+Ctrl+A selects all, and Escape deselects; each change is announced.
+
+Items stay on the surface; with `snap` they line up with its edges and
+centre and with each other, and with `grid` they keep to a grid. `scale`
+shows the design larger or smaller, or `"fit"` fills the width it's given.
+`onItemsChange` gets the items with every step of a change; `onItemsChangeEnd`, once
+it's made, with the items before it, for undo or saving.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `height` (required) | `number` |  |  |
+| `items` (required) | `readonly T[]` |  | Where each item is (other fields are kept); render a CanvasItem for each. |
+| `onItemsChange` (required) | `(items: T[]) => void` |  | The items, with every step of a move or resize. |
+| `width` (required) | `number` |  | The surface's size, in your design's units (px at scale 1). |
+| `grid` | `number` |  | Keep positions and sizes to multiples of this (design units) when no line is in reach. |
+| `minSize` | `number` | `8` | Smallest width and height an item can be resized to. |
+| `onItemsChangeEnd` | `((items: T[], before: readonly T[]) => void)` |  | The items once a change is made (a drag let go, a key pressed), and as they were before: for undo or saving. |
+| `onSelectedChange` | `((ids: string[]) => void)` |  |  |
+| `scale` | `"fit" \| number` | `1` | How large to show it: 2 shows a 400×120 design 800×240; "fit" fills the width it's given. Positions stay in design units. |
+| `selected` | `readonly string[]` | `[]` | The selected items' ids. |
+| `snap` | `boolean \| number` | `false` | Line items up with the surface and each other: true, or how close counts, in screen px (true is 6). |
+
+### CanvasItem
+
+One item on a Canvas, placed where the canvas's `items` say for its `id`;
+later items sit on top of earlier ones. `label` names it ("Title") in what's
+announced. Its content is yours: fields and buttons in it work as usual,
+and pressing them doesn't drag it (nor anything with data-canvas-no-drag).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` (required) | `string` |  |  |
+| `label` (required) | `string` |  | The item's name, e.g. "Title", for what's announced. |