@iyulab/u-board-designer 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @iyulab/u-board-designer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The authoring tool for [U-Board](https://github.com/iyulab/U-Board) boards — `BoardAuthoring`, a board edited in place —
+and the board check and the rulebook an assistant writes by. It builds on
+[`@iyulab/u-board`](https://www.npmjs.com/package/@iyulab/u-board), which holds the board language and the viewer.
+
+## Install
+
+```sh
+npm install @iyulab/u-board-designer @iyulab/u-board react react-dom
+```
+
+`react` and `react-dom` (19.2 or later) are peer dependencies. The package is ESM-only and needs Node 22.12 or later.
+
+## Entry points
+
+| Import | Contents | Depends on React / canvas |
+|---|---|---|
+| `@iyulab/u-board-designer` | `BoardAuthoring`, `DesignerLabels`, `KO_DESIGNER_LABELS` | Yes |
+| `@iyulab/u-board-designer/check` | `checkBoard`, `emptyBoard`, `sourceAdvice`, `boardRulebook`, `RULEBOOK_EXAMPLE` | No |
+
+## Authoring a board
+
+```tsx
+import { BoardAuthoring } from '@iyulab/u-board-designer';
+
+<div style={{ height: '80vh' }}>
+  <BoardAuthoring initialBoard={board} adapters={adapters} onSave={next => save(next)} />
+</div>;
+```
+
+`BoardAuthoring` sizes the same way: without `width`/`height` the board fills the parent's width beside the panel, and
+its height. The board opens fitted into view and is shown in one of two modes, switched from the toolbar with pan and
+zoom kept. **Edit**: the board drawn as its viewers see it, each part's widget in place over its footprint, its kind
+named above it; drag a part to move it, its handles to size it; drag across empty space to select several; select two
+parts (Shift + click the second) to join them with a link; Delete removes the selection; on a grid, drag an item onto
+another to move it there, and lay the grid out at a wide, medium or narrow width. **View**: the board exactly as a
+shared link shows it, where a drag pans. The wheel zooms in both.
+
+The panel edits what is selected — a part's title, kind, what it reads (a data read, and one item of it by key), the
+fields it shows and its kind's options, with the controls the widget library describes; a link; a shape; a grid item's
+span and height — and, with nothing selected, the board: its background, theme and accent, its data reads (reading a
+source to offer the fields its items have), its statuses, its elements and its triggers. What the board's check finds is
+listed where it applies, and a setting the board cannot be drawn with keeps the last picture it could, saying why. A
+grid's cell — a canvas, or a grid of its own — opens in its own editor. Undo and Redo walk the edits; Save calls
+`onSave` with the board (without it there is no Save), and Export downloads the board as a file. `sourceLabels` names
+each adapter's source in the data panel.
+
+### Text in another language
+
+The tool shows English text by default. Pass `labels` — any subset of `DesignerLabels`, the rest stays English — to
+show your own; `DEFAULT_DESIGNER_LABELS` lists every key with its English text. `DesignerLabels` is the viewer's
+`UBoardLabels` plus the authoring texts, and `labels.locale` is the language of both: the panel names part kinds, data
+fields and options in it, as the widget library names them. Korean ships as `KO_DESIGNER_LABELS`:
+
+```tsx
+import { BoardAuthoring, KO_DESIGNER_LABELS } from '@iyulab/u-board-designer';
+
+<BoardAuthoring initialBoard={board} adapters={adapters} labels={KO_DESIGNER_LABELS} />;
+```
+
+## Checking a board
+
+`checkBoard` is what a board meets before it is stored: the language, and then that it draws. `sourceAdvice` and the
+rulebook (`boardRulebook`) are what an assistant reads to write a board well. They load without React, so a server or an
+MCP process imports them from the `check` entry point:
+
+```ts
+import { checkBoard, emptyBoard } from '@iyulab/u-board-designer/check';
+
+const { issues } = checkBoard(emptyBoard());
+```
+
+### Styling
+
+The components carry only the layout they need to work. Import the default stylesheet once, after the viewer's:
+
+```ts
+import '@iyulab/u-board/styles.css';
+import '@iyulab/u-board-designer/styles.css';
+```
+
+It reads the same `--ub-*` custom properties as `@iyulab/u-board/styles.css` (listed in that package's README) and falls
+back to its own values for any you leave out. These are the ones only the authoring view reads:
+
+| Token | Used for |
+|---|---|
+| `--ub-panel-width` | Width of the authoring view's panel (320 px by default) |
+| `--ub-space-4` | A gap of 16 px by default |
+
+The sheet's rules select these class names, mostly one class each: they hold against a host's element styles, and a host
+rule on the same class, loaded after the sheet, overrides them.
+
+| Class | Element |
+|---|---|
+| `ub-action--primary` | The primary button (Save); with `ub-action`, which the viewer package styles |
+| `ub-authoring` | The authoring view |
+| `ub-authoring__toolbar`, `ub-authoring__group` | Its toolbar, and each group of related actions in it |
+| `ub-authoring__appearance` | The board tone picker (light or dark board), with the board's settings in the panel |
+| `ub-authoring__mode` | The Edit / View switch in the toolbar (the chosen button has `aria-pressed="true"`) |
+| `ub-authoring__panes`, `ub-authoring__pane` | The row holding the board and the panel; the board's column |
+| `ub-authoring__surface` | The frame the board draws in — the editor, or the board in view mode |
+| `ub-authoring__node`, `ub-authoring__node-tag` | A part's widget drawn in place on the editor; its kind named above it |
+| `ub-authoring__pick`, `ub-authoring__layout-width` | On a grid view's editor: the button over each item that selects it (`aria-pressed` when selected); the Wide / Medium / Narrow layout width switch |
+| `ub-authoring__panel` | The column holding the panel |
+| `ub-authoring__error`, `ub-authoring__status` | A setting the board cannot be drawn with; "resolving" |
+| `ub-panel` (`--board`, `--item`, `--elements`, `--part`, `--link`, `--shape`, `--data`, `--statuses`) | The board's settings (while nothing is selected), a grid item's layout (its widths, height and place in the order), the board's elements, a part, a link or a shape, or the board's data or statuses |
+| `ub-panel__heading`, `ub-panel__subheading`, `ub-panel__field`, `ub-panel__hint`, `ub-panel__error` | Its heading, section heading, a labelled field, hint text and an error |
+| `ub-panel__findings` | What a board's check finds at the selected part, listed under its settings |
+| `ub-panel__widget-form`, `ub-panel__group` | The widget's own fields, and each group of them (data, display options) |
+| `ub-panel__details` | A fold for the finer settings of a data read (which items, their time, the request time) |
+| `ub-panel__field-name`, `ub-panel__field--check` | A field's name (with its key); a checkbox field |
+| `ub-panel__binding-tag` | A field's "mapped" tag |
+| `ub-panel__value-map`, `ub-panel__map-row`, `ub-panel__actions` | A value map, a row of the map, and its buttons |
+| `ub-panel__section` | A section of a panel under its own subheading — a part’s states, its triggers |
+| `ub-panel__state-looks`, `ub-panel__state-look` | How each state is shown, and one state’s row |
+| `ub-panel__trigger`, `ub-panel__trigger-action` | One trigger, and one of its actions |
+
+## Versioning
+
+Pre-1.0: a minor version may change the public API.
+
+## License
+
+Copyright (c) 2026 iyulab.
+
+AGPL-3.0-or-later. A commercial license is available for organizations that cannot adopt AGPL-3.0
+terms.

package/dist/lib/authoring/AnchorFields.d.ts

@@ -0,0 +1,12 @@
+import { type DesignerLabels } from '../labels.js';
+import type { ReferencePoint } from '@iyulab/u-board/picture';
+/**
+ * The background image's reference points (`BackgroundImage.referencePoints`): two points of the image, in
+ * the board's units, and the coordinate each stands for. Saved once all eight numbers are in and the points
+ * are apart on both axes; cleared together.
+ */
+export declare function ReferencePointsFields({ points, onChange, labels, }: {
+    points: readonly ReferencePoint[] | undefined;
+    onChange: (points: [ReferencePoint, ReferencePoint] | undefined) => void;
+    labels: DesignerLabels;
+}): import("react").JSX.Element;

package/dist/lib/authoring/AnchorFields.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { ERROR_STYLE } from '@iyulab/u-board/toolkit';
+const FIELD_STYLE = { display: 'flex', flexDirection: 'column' };
+const ROW_STYLE = { display: 'flex', gap: 'var(--ub-space-2, 8px)', alignItems: 'end', flexWrap: 'wrap' };
+const NUMBER_STYLE = { width: '6.5em', minWidth: 0 };
+/** A number as typed, or `null` when it is not one. */
+function parsed(text) {
+    const value = Number(text);
+    return text.trim() !== '' && Number.isFinite(value) ? value : null;
+}
+/** A coordinate as the field shows it — enough digits for a longitude to a metre, without a float's tail. */
+const shown = (value) => String(Number(value.toPrecision(10)));
+const draftOf = (points) => [0, 1].map(i => {
+    const point = points?.[i];
+    return point ? [shown(point.x), shown(point.y), shown(point.coordinate.x), shown(point.coordinate.y)] : ['', '', '', ''];
+});
+/** The two points typed in, when every field is a number and the points are apart on both axes in the image
+ *  and in their coordinates — or `null` with why not: `incomplete` or `degenerate`. */
+function pointsOf(draft) {
+    const values = draft.map(row => row.map(parsed));
+    if (values.some(row => row.some(v => v === null)))
+        return 'incomplete';
+    const [a, b] = values.map(([x, y, cx, cy]) => ({ x: x, y: y, coordinate: { x: cx, y: cy } }));
+    if (a.x === b.x || a.y === b.y || a.coordinate.x === b.coordinate.x || a.coordinate.y === b.coordinate.y)
+        return 'degenerate';
+    return [a, b];
+}
+/**
+ * The background image's reference points (`BackgroundImage.referencePoints`): two points of the image, in
+ * the board's units, and the coordinate each stands for. Saved once all eight numbers are in and the points
+ * are apart on both axes; cleared together.
+ */
+export function ReferencePointsFields({ points, onChange, labels, }) {
+    const [draft, setDraft] = useState(() => draftOf(points));
+    // The points this form last saved. When they come back as `points`, the fields already say them, as the
+    // author typed them — rewriting them in normal form would turn "35.0" into "35" mid-keystroke. Points
+    // from elsewhere (another background, an undo) replace the fields.
+    const saved = useRef(points);
+    useEffect(() => {
+        if (points === saved.current)
+            return;
+        saved.current = points;
+        setDraft(draftOf(points));
+    }, [points]);
+    const result = pointsOf(draft);
+    const blank = draft.every(row => row.every(field => field.trim() === ''));
+    const set = (i, j, text) => {
+        const next = draft.map((row, r) => (r === i ? row.map((field, f) => (f === j ? text : field)) : row));
+        setDraft(next);
+        const changed = pointsOf(next);
+        if (typeof changed !== 'string') {
+            saved.current = changed;
+            onChange(changed);
+        }
+    };
+    const clear = () => {
+        saved.current = undefined;
+        setDraft(draftOf(undefined));
+        onChange(undefined);
+    };
+    const names = [labels.imageX, labels.imageY, labels.coordinateX, labels.coordinateY];
+    return (_jsxs("fieldset", { className: "ub-panel__value-map", style: { minWidth: 0 }, children: [_jsx("legend", { children: labels.referencePoints }), _jsx("p", { className: "ub-panel__hint", children: labels.referencePointsHint }), draft.map((row, i) => (_jsx("div", { className: "ub-panel__map-row", style: ROW_STYLE, role: "group", "aria-label": labels.referencePoint.replace('{n}', String(i + 1)), children: row.map((field, j) => (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [names[j], _jsx("input", { type: "number", step: "any", style: NUMBER_STYLE, value: field, onChange: e => set(i, j, e.target.value) })] }, j))) }, i))), result === 'degenerate' && (_jsx("p", { role: "alert", className: "ub-panel__error", style: ERROR_STYLE, children: labels.referencePointsApart })), !blank && result === 'incomplete' && _jsx("p", { className: "ub-panel__hint", children: labels.referencePointsIncomplete }), points && (_jsx("button", { type: "button", className: "ub-action", onClick: clear, children: labels.clearReferencePoints }))] }));
+}

package/dist/lib/authoring/BackgroundField.d.ts

@@ -0,0 +1,13 @@
+import { type DesignerLabels } from '../labels.js';
+import type { CanvasLayout } from '@iyulab/u-board/toolkit';
+export interface BackgroundFieldProps {
+    layout: CanvasLayout;
+    /** The canvas with its background as chosen — or taken away. */
+    onChange: (layout: CanvasLayout) => void;
+    labels?: DesignerLabels;
+}
+/**
+ * The background of a canvas board: an image file chosen, which the canvas takes the
+ * size of — its parts keep their places in the canvas's units — or taken away, the canvas keeping its size.
+ */
+export declare function BackgroundField({ layout, onChange, labels }: BackgroundFieldProps): import("react").JSX.Element;

package/dist/lib/authoring/BackgroundField.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_DESIGNER_LABELS } from '../labels.js';
+import { useRef, useState } from 'react';
+import { GROUP_STYLE } from '@iyulab/u-board/toolkit';
+import { readBackgroundImage, BackgroundImageError, BACKGROUND_IMAGE_TYPES, MAX_BACKGROUND_BYTES } from './background-image.js';
+/**
+ * The background of a canvas board: an image file chosen, which the canvas takes the
+ * size of — its parts keep their places in the canvas's units — or taken away, the canvas keeping its size.
+ */
+export function BackgroundField({ layout, onChange, labels = DEFAULT_DESIGNER_LABELS }) {
+    const input = useRef(null);
+    const [error, setError] = useState(null);
+    const choose = async (e) => {
+        const file = e.target.files?.[0];
+        e.target.value = '';
+        if (!file)
+            return;
+        try {
+            const image = await readBackgroundImage(file);
+            const size = image.width > 0 && image.height > 0 ? [image.width, image.height] : layout.size;
+            onChange({ ...layout, background: image.src, size });
+            setError(null);
+        }
+        catch (err) {
+            const problem = err instanceof BackgroundImageError ? err.problem : 'unreadable';
+            setError(problem === 'type'
+                ? labels.backgroundType
+                : problem === 'size'
+                    ? labels.backgroundTooLarge.replace('{max}', `${MAX_BACKGROUND_BYTES / (1024 * 1024)} MB`)
+                    : labels.backgroundUnreadable);
+        }
+    };
+    const remove = () => {
+        const { background: _gone, ...rest } = layout;
+        onChange(rest);
+    };
+    return (_jsxs("div", { className: "ub-panel__actions", style: GROUP_STYLE, children: [_jsx("button", { type: "button", className: "ub-action", onClick: () => input.current?.click(), children: labels.setBackground }), layout.background !== undefined && (_jsx("button", { type: "button", className: "ub-action", onClick: remove, children: labels.removeBackground })), _jsx("input", { ref: input, type: "file", accept: BACKGROUND_IMAGE_TYPES.join(','), onChange: choose, style: { display: 'none' }, "data-testid": "background-file-input" }), error && (_jsx("p", { className: "ub-panel__error", role: "alert", children: error }))] }));
+}

package/dist/lib/authoring/BoardAuthoring.d.ts

@@ -0,0 +1,37 @@
+import { type DesignerLabels } from '../labels.js';
+import type { Adapter } from '@iyulab/u-board/toolkit';
+import { type ViewerPageProps } from '@iyulab/u-board/toolkit';
+import type { Board } from '@iyulab/u-board/toolkit';
+import type { AuthoringMode } from './editor-parts.js';
+export interface BoardAuthoringProps {
+    /** The board to edit. */
+    initialBoard: Board;
+    /** Where the board's values are read — also which items a grid laying out a part per item of a list lays out, read
+     *  when the board opens and whenever what the board reads them by changes. */
+    adapters: readonly Adapter[];
+    /** What each adapter's source is called, by adapter id — the names the data panel offers sources by. Omitted, an id. */
+    sourceLabels?: Readonly<Record<string, string>>;
+    width?: number;
+    height?: number;
+    /** What Save does. Omitted, there is no Save — Export downloads the board. */
+    onSave?: (board: Board) => void | Promise<void>;
+    onDirtyChange?: (isDirty: boolean) => void;
+    labels?: Partial<DesignerLabels>;
+    clock?: () => number;
+    elementOrigins?: readonly string[];
+    elementFrames?: string;
+    boardId?: string;
+    onTrigger?: ViewerPageProps['onTrigger'];
+    onNavigate?: ViewerPageProps['onNavigate'];
+    linkOrigins?: readonly string[];
+    initialMode?: AuthoringMode;
+    onModeChange?: (mode: AuthoringMode) => void;
+}
+/**
+ * The authoring surface of a board: the board drawn from its picture, where its parts
+ * are moved, sized, ordered and deleted — each edit said again in the board's layout (`withPictureLayout`) — and a
+ * selected part's title, kind, data and fields set in its panel, with what the board's check finds there. A setting the
+ * board cannot be drawn with keeps the last picture it could, and says why. Undo, Redo, Save and Export are the
+ * board's. A grid's cell — a canvas, or a grid of its own — opens in its own editor, what changes there written back.
+ */
+export declare function BoardAuthoring({ initialBoard, adapters, sourceLabels, width, height, onSave, onDirtyChange, labels: labelsProp, clock, elementOrigins, elementFrames, boardId, onTrigger, onNavigate, linkOrigins, initialMode, onModeChange }: BoardAuthoringProps): import("react").JSX.Element;

package/dist/lib/authoring/BoardAuthoring.js

@@ -0,0 +1,288 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useDesignerLabels } from '../use-labels.js';
+import { useEffect, useMemo, useState } from 'react';
+import { TONES } from '@iyulab/u-board/toolkit';
+import { GROUP_STYLE } from '@iyulab/u-board/toolkit';
+import { placedIn } from '@iyulab/u-board/picture';
+import { ElementHost } from '@iyulab/u-board/toolkit';
+import { ViewerPage } from '@iyulab/u-board/toolkit';
+import { PictureError, dataReadOf, keyReadsOf, keysIn, toViewDocument } from '@iyulab/u-board/toolkit';
+import { readLists, readerOf } from '@iyulab/u-board/toolkit';
+import { checkBoard } from '../board/check.js';
+import { CanvasAuthoring } from './CanvasAuthoring.js';
+import { PartPanel } from './PartPanel.js';
+import { StatusesPanel } from './StatusesPanel.js';
+import { DataPanel } from './DataPanel.js';
+import { LinkPanel } from './LinkPanel.js';
+import { ShapePanel } from './ShapePanel.js';
+import { BackgroundField } from './BackgroundField.js';
+import { BoardElementsPanel } from './BoardElementsPanel.js';
+import { BoardPanel } from './BoardPanel.js';
+import { TriggersEditor } from './TriggersEditor.js';
+import { boardTriggerEditing } from './board-triggers.js';
+import { GridAuthoring } from './GridAuthoring.js';
+import { LINK, cellBoard, cellIndex, gridCellOf, layoutEditable, linkOf, placesItself, shapeOf, withCell, withNewLink, withNewShape, withPictureLayout } from './board-layout.js';
+import { recordEdit, redo, startHistory, undo } from './document-history.js';
+import { useEditKeys } from './use-edit-keys.js';
+/**
+ * The authoring surface of a board: the board drawn from its picture, where its parts
+ * are moved, sized, ordered and deleted — each edit said again in the board's layout (`withPictureLayout`) — and a
+ * selected part's title, kind, data and fields set in its panel, with what the board's check finds there. A setting the
+ * board cannot be drawn with keeps the last picture it could, and says why. Undo, Redo, Save and Export are the
+ * board's. A grid's cell — a canvas, or a grid of its own — opens in its own editor, what changes there written back.
+ */
+export function BoardAuthoring({ initialBoard, adapters, sourceLabels, width, height, onSave, onDirtyChange, labels: labelsProp, clock = Date.now, elementOrigins, elementFrames, boardId, onTrigger, onNavigate, linkOrigins, initialMode = 'edit', onModeChange }) {
+    const labels = useDesignerLabels(labelsProp);
+    const [history, setHistory] = useState(() => startHistory(initialBoard));
+    const board = history.present;
+    // A grid's cell open in its own editor — its entry — and the board as that editor sees it: the cell (a canvas, or a
+    // grid) as the layout, what it changes written back into the cell.
+    const [cell, setCell] = useState(undefined);
+    const inCell = cell !== undefined && cellBoard(board, cell) !== undefined ? cell : undefined;
+    const scope = (b) => (inCell !== undefined ? (cellBoard(b, inCell) ?? b) : b);
+    const unscope = (b, scoped) => (inCell !== undefined ? withCell(b, inCell, scoped) : scoped);
+    const scoped = scope(board);
+    /** Where the layout the canvas editor edits sits in the board — for the findings about it. */
+    const layoutAt = inCell !== undefined ? `/layout/items/${inCell}/${scoped.layout.kind}` : '/layout';
+    const [lastSaved, setLastSaved] = useState(initialBoard);
+    const isDirty = board !== lastSaved;
+    const [mode, setModeState] = useState(initialMode);
+    const setMode = (next) => {
+        setModeState(next);
+        onModeChange?.(next);
+    };
+    // A view shows the board as it is: the edits are walked back and forth only while editing — by the buttons, or the
+    // keys heard anywhere in the editor.
+    const canUndo = mode === 'edit' && history.past.length > 0;
+    const canRedo = mode === 'edit' && history.future.length > 0;
+    const { rootRef, typing } = useEditKeys(setHistory, canUndo, canRedo);
+    /** An edit — one with what was typed in the same field before it while it answers typing there (document-history.ts),
+     *  until focus moves on. Which field is read when the edit is made, before its update runs. */
+    const setEdit = (update) => {
+        const typingIn = typing.current;
+        setHistory(h => update(h, typingIn));
+    };
+    useEffect(() => {
+        if (!isDirty)
+            return;
+        const handler = (e) => {
+            e.preventDefault();
+            e.returnValue = '';
+        };
+        window.addEventListener('beforeunload', handler);
+        return () => window.removeEventListener('beforeunload', handler);
+    }, [isDirty]);
+    useEffect(() => {
+        onDirtyChange?.(isDirty);
+    }, [isDirty, onDirtyChange]);
+    const items = useItemLists(board, adapters);
+    const drawOptions = useMemo(() => ({ keysOf: data => keysIn(items.board, data, items.lists[data] ?? []), rowsOf: data => items.lists[data] ?? [] }), [items]);
+    // What is drawn: the board, or — while a setting leaves it one that cannot be drawn — the newest board before it that
+    // could be, with why the board is not.
+    const pictureOf = (h) => drawnOf(h, drawOptions);
+    const drawing = useMemo(() => drawnOf(history, drawOptions), [history, drawOptions]);
+    const picture = drawing.picture;
+    /** What the editor shows: the board, or the cell open — drawn as a board of its own. */
+    const shown = inCell !== undefined ? drawCell(scoped, drawOptions) : picture;
+    /** What was drawn before an edit, as the editor shows it. */
+    const shownOf = (h) => (inCell !== undefined ? drawCell(scope(h.present), drawOptions) : pictureOf(h).picture);
+    const movable = (id) => placesItself(scoped, id);
+    const ownPiece = (id) => linkOf(scoped, id) !== undefined || shapeOf(scoped, id) !== undefined;
+    const findings = useMemo(() => {
+        const check = checkBoard(board);
+        return [...check.issues, ...check.advice];
+    }, [board]);
+    // What a trigger may name: a part — one made per item, by item — as the board is drawn now.
+    const targets = useMemo(() => placedIn(picture).map(placed => placed.id.slice(placed.id.lastIndexOf(':') + 1)).filter(id => {
+        const [part, key, ...rest] = id.split('/');
+        const each = board.parts[part]?.each !== undefined;
+        return rest.length === 0 && (key === undefined ? !each && part in board.parts : each);
+    }), [picture, board]);
+    const sources = useMemo(() => adapters.map(a => ({ id: a.id, ...(sourceLabels?.[a.id] !== undefined ? { label: sourceLabels[a.id] } : {}) })), [adapters, sourceLabels]);
+    const read = useMemo(() => readerOf(adapters), [adapters]);
+    /** The board's own settings (`board` — its title, theme, accent and look) changed — one left empty goes, and so does
+     *  `board` when nothing is left in it. */
+    const setBoardHead = (change) => setEdit((h, typingIn) => {
+        const { board: head, ...rest } = h.present;
+        const next = { ...head, ...change };
+        for (const [key, value] of Object.entries(change))
+            if (value === undefined)
+                delete next[key];
+        return recordEdit(h, Object.keys(next).length > 0 ? { ...rest, board: next } : rest, typingIn);
+    });
+    /** One of the board's data read now, whole, as the board reads it. */
+    const look = async (name) => {
+        const { adapter, ref } = dataReadOf(board, name);
+        return (await read(adapter, ref)).value;
+    };
+    const triggerEditing = boardTriggerEditing(board, targets, update => setEdit((h, typingIn) => recordEdit(h, update(h.present), typingIn)));
+    /** The panel of the part a selected node or item draws — a part made per item, or one inside a group, is its part;
+     *  with nothing selected, the board's own triggers (those that run when it opens). */
+    const panel = (selected) => {
+        if (selected === null) {
+            return (_jsxs(_Fragment, { children: [_jsx(BoardPanel, { appearance: board.board?.theme ?? 'light', onAppearanceChange: theme => setBoardHead({ theme }), accent: board.board?.accent, onAccentChange: accent => setBoardHead({ accent }), hint: labels.layoutOnlyHint, labels: labels }), scoped.layout.kind === 'canvas' && (_jsx(BackgroundField, { layout: scoped.layout, onChange: layout => setEdit((h, typingIn) => recordEdit(h, unscope(h.present, { ...scope(h.present), layout }), typingIn)), labels: labels })), _jsx(DataPanel, { data: board.data, sources: sources, look: look, statuses: [...new Set([...Object.keys(board.statuses ?? {}), ...TONES])], onChange: data => setEdit((h, typingIn) => {
+                            const { data: _gone, ...rest } = h.present;
+                            return recordEdit(h, data ? { ...rest, data } : rest, typingIn);
+                        }), labels: labels }), _jsx(StatusesPanel, { statuses: board.statuses, onChange: statuses => setEdit((h, typingIn) => {
+                            const { statuses: _gone, ...rest } = h.present;
+                            return recordEdit(h, statuses ? { ...rest, statuses } : rest, typingIn);
+                        }), labels: labels }), _jsx(TriggersEditor, { ...triggerEditing, labels: labels }), _jsx(BoardElementsPanel, { board: board, onChange: elements => setEdit((h, typingIn) => {
+                            const { elements: _gone, ...rest } = h.present;
+                            return recordEdit(h, elements ? { ...rest, elements } : rest, typingIn);
+                        }), labels: labels })] }));
+        }
+        const shape = shapeOf(scoped, selected);
+        if (shape !== undefined) {
+            return (_jsx(ShapePanel, { id: shape, board: scoped, onChange: next => setEdit((h, typingIn) => {
+                    const own = scope(h.present);
+                    if (own.layout.kind !== 'canvas')
+                        return h;
+                    return recordEdit(h, unscope(h.present, { ...own, layout: { ...own.layout, shapes: { ...own.layout.shapes, [shape]: next } } }), typingIn);
+                }), findings: findings.filter(f => f.path === `${layoutAt}/shapes/${shape}` || f.path.startsWith(`${layoutAt}/shapes/${shape}/`)), labels: labels }, shape));
+        }
+        const link = linkOf(scoped, selected);
+        if (link !== undefined) {
+            return (_jsx(LinkPanel, { id: link, board: scoped, onChange: next => setEdit((h, typingIn) => {
+                    const own = scope(h.present);
+                    if (own.layout.kind !== 'canvas')
+                        return h;
+                    return recordEdit(h, unscope(h.present, { ...own, layout: { ...own.layout, links: { ...own.layout.links, [link]: next } } }), typingIn);
+                }), findings: findings.filter(f => f.path === `${layoutAt}/links/${link}` || f.path.startsWith(`${layoutAt}/links/${link}/`)), labels: labels }, link));
+        }
+        // An item drawn from a grid in a cell is laid out in that grid: it opens from here.
+        const gridCell = inCell === undefined ? gridCellOf(board, selected) : undefined;
+        const openGrid = gridCell === undefined ? null : (_jsx("button", { type: "button", className: "ub-action ub-action--primary", onClick: () => setCell(gridCell), children: labels.editGridCell }));
+        const id = selected.split('/')[0];
+        if (id === undefined || !(id in board.parts))
+            return openGrid;
+        return (_jsxs(_Fragment, { children: [openGrid, _jsx(PartPanel, { id: id, board: board, onChange: part => setEdit((h, typingIn) => recordEdit(h, { ...h.present, parts: { ...h.present.parts, [id]: part } }, typingIn)), findings: findings.filter(f => f.path === `/parts/${id}` || f.path.startsWith(`/parts/${id}/`)), triggers: targets.includes(selected) ? _jsx(TriggersEditor, { node: selected, ...triggerEditing, labels: labels }, `triggers:${selected}`) : undefined, labels: labels }, id)] }));
+    };
+    const handleSave = async () => {
+        if (!onSave)
+            return handleExport();
+        try {
+            await onSave(board);
+            setLastSaved(board);
+        }
+        catch {
+            // The host says why it failed; the board stays unsaved.
+        }
+    };
+    const handleExport = () => {
+        const blob = new Blob([JSON.stringify(board, null, 2)], { type: 'application/json' });
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement('a');
+        link.href = url;
+        link.download = 'board.json';
+        link.click();
+        URL.revokeObjectURL(url);
+        if (!onSave)
+            setLastSaved(board);
+    };
+    /** A new part, titled and of a kind that reads no data until its panel sets one — placed where a canvas (or the canvas
+     *  cell open) has room at its top left, or last in a grid. */
+    const addPart = () => setEdit((h, typingIn) => {
+        const present = h.present;
+        let n = Object.keys(present.parts).length + 1;
+        while (`part-${n}` in present.parts)
+            n++;
+        const id = `part-${n}`;
+        const own = scope(present);
+        if (own.layout.kind === 'canvas') {
+            const layout = own.layout;
+            const step = 24 * (n - 1);
+            const x = Math.min(40 + step, Math.max(0, layout.size[0] - 160));
+            const y = Math.min(40 + step, Math.max(0, layout.size[1] - 60));
+            return recordEdit(h, unscope(present, { ...own, parts: { ...own.parts, [id]: { as: 'label', title: labels.newPartTitle } }, layout: { ...layout, place: { ...layout.place, [id]: [x, y, 160, 60] } } }), typingIn);
+        }
+        const layout = present.layout;
+        if (layout.kind !== 'grid')
+            return h;
+        return recordEdit(h, { ...present, parts: { ...present.parts, [id]: { as: 'header', title: labels.newPartTitle } }, layout: { ...layout, items: [...layout.items, id] } }, typingIn);
+    });
+    /** A frame or a text on a canvas board, at its top left. */
+    const addShape = (kind) => setEdit((h, typingIn) => recordEdit(h, unscope(h.present, withNewShape(scope(h.present), kind, labels.shapeNewText).board), typingIn));
+    const documentActions = (_jsxs(_Fragment, { children: [inCell !== undefined && (_jsx("div", { className: "ub-authoring__group", style: GROUP_STYLE, children: _jsx("button", { type: "button", className: "ub-action", onClick: () => setCell(undefined), children: labels.backToGrid }) })), mode === 'edit' && layoutEditable(board) && (_jsxs("div", { className: "ub-authoring__group", style: GROUP_STYLE, children: [_jsx("button", { type: "button", className: "ub-action", onClick: addPart, children: labels.partAdd }), scoped.layout.kind === 'canvas' && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "ub-action", onClick: () => addShape('box'), children: labels.shapeAddBox }), _jsx("button", { type: "button", className: "ub-action", onClick: () => addShape('text'), children: labels.shapeAddText }), _jsx("button", { type: "button", className: "ub-action", onClick: () => addShape('line'), children: labels.shapeAddLine })] }))] })), _jsxs("div", { className: "ub-authoring__group", style: GROUP_STYLE, children: [_jsx("button", { type: "button", className: "ub-action", onClick: () => setHistory(undo), disabled: !canUndo, "aria-keyshortcuts": "Control+Z Meta+Z", children: labels.undo }), _jsx("button", { type: "button", className: "ub-action", onClick: () => setHistory(redo), disabled: !canRedo, "aria-keyshortcuts": "Control+Shift+Z Meta+Shift+Z Control+Y", children: labels.redo })] }), _jsxs("div", { className: "ub-authoring__group", style: GROUP_STYLE, children: [onSave && (_jsx("button", { type: "button", className: "ub-action ub-action--primary", onClick: handleSave, children: labels.save })), _jsx("button", { type: "button", className: "ub-action", onClick: handleExport, children: labels.export })] })] }));
+    return (_jsx(ElementHost, { origins: elementOrigins, frames: elementFrames, children: _jsxs("div", { className: "ub-authoring", style: { display: 'flex', flexDirection: 'column', height: '100%' }, ref: rootRef, children: [drawing.error && (_jsx("p", { role: "alert", className: "ub-authoring__error", children: labels.boardNotDrawn.replace('{reason}', drawing.error) })), shown?.kind === 'canvas' && layoutEditable(board) ? (_jsx(CanvasAuthoring, { doc: shown, updateDoc: update => setEdit((h, typingIn) => {
+                        const before = shownOf(h);
+                        if (before?.kind !== 'canvas')
+                            return h;
+                        return recordEdit(h, unscope(h.present, withPictureLayout(scope(h.present), before, update(before))), typingIn);
+                    }), mode: mode, onModeChange: setMode, documentActions: documentActions, adapters: adapters, width: width, height: height, labels: labels, clock: clock, triggerHosting: { boardId, onTrigger, onNavigate, linkOrigins }, parts: {
+                        movable,
+                        panel,
+                        connect: (from, to) => {
+                            const made = withNewLink(scoped, from, to);
+                            setEdit((h, typingIn) => recordEdit(h, unscope(h.present, withNewLink(scope(h.present), from, to).board), typingIn));
+                            return `${LINK}${made.id}`;
+                        },
+                        deletable: ownPiece,
+                    } }, inCell === undefined ? 'board' : `cell-${inCell}`)) : shown?.kind === 'grid' && layoutEditable(board) ? (_jsx(GridAuthoring, { doc: shown, updateDoc: update => setEdit((h, typingIn) => {
+                        const before = shownOf(h);
+                        if (before?.kind !== 'grid')
+                            return h;
+                        return recordEdit(h, unscope(h.present, withPictureLayout(scope(h.present), before, update(before))), typingIn);
+                    }), mode: mode, onModeChange: setMode, documentActions: documentActions, adapters: adapters, width: width, height: height, labels: labels, clock: clock, triggerHosting: { boardId, onTrigger, onNavigate, linkOrigins }, parts: { movable, panel }, onEditCanvas: inCell === undefined ? id => setCell(cellIndex(board, id)) : undefined }, inCell === undefined ? 'board' : `cell-${inCell}`)) : (_jsx(ViewerPage, { document: picture, adapters: adapters, width: width, height: height, labels: labels, clock: clock, boardId: boardId, onTrigger: onTrigger, onNavigate: onNavigate, linkOrigins: linkOrigins, elementOrigins: elementOrigins, elementFrames: elementFrames }))] }) }));
+}
+/** A board drawn — when its language takes it and it draws — or why not. */
+function draw(board, options) {
+    const issue = checkBoard(board).issues[0];
+    if (issue)
+        return { picture: null, error: `${issue.path}: ${issue.message}` };
+    try {
+        return { picture: toViewDocument(board, options), error: null };
+    }
+    catch (error) {
+        if (error instanceof PictureError)
+            return { picture: null, error: error.message };
+        throw error;
+    }
+}
+/** A grid's cell as `cellBoard` gives it, drawn for its editor: without the board's triggers — they name parts all over
+ *  the board, most of them not in the cell — and without the board's check, which would find those parts placed nowhere
+ *  in it. Null when it cannot be drawn. */
+function drawCell(cell, options) {
+    const { triggers: _triggers, ...drawn } = cell;
+    try {
+        return toViewDocument(drawn, options);
+    }
+    catch (error) {
+        if (error instanceof PictureError)
+            return null;
+        throw error;
+    }
+}
+/** The keys of the items each data list a part is made per item of has now, read through `adapters` — again only when
+ *  what they are read by changes (an edit elsewhere in the board reads nothing). While a setting leaves the board one
+ *  that cannot be drawn, the keys read last stay. */
+function useItemLists(board, adapters) {
+    const [items, setItems] = useState({ board, lists: {} });
+    const read = useMemo(() => readerOf(adapters), [adapters]);
+    const by = useMemo(() => (draw(board, { keysOf: () => [], rowsOf: () => [] }).picture === null ? null : JSON.stringify(keyReadsOf(board).map(r => [r, board.data?.[r.data]?.key]))), [board]);
+    // The board the items are read from: the newest one that draws whose reads differ from the last.
+    const [source, setSource] = useState({ by: '[]', board });
+    if (by !== null && by !== source.by)
+        setSource({ by, board });
+    useEffect(() => {
+        if (source.by === '[]')
+            return;
+        let current = true;
+        void readLists(source.board, read).then(lists => current && setItems({ board: source.board, lists }));
+        return () => {
+            current = false;
+        };
+    }, [source, read]);
+    return items;
+}
+/** What the editor draws for a history: its board, or the newest one before it that draws, and why the board does not. */
+function drawnOf(history, options) {
+    const now = draw(history.present, options);
+    if (now.picture)
+        return now;
+    for (const before of [...history.past].reverse()) {
+        const drawn = draw(before, options).picture;
+        if (drawn)
+            return { picture: drawn, error: now.error };
+    }
+    return { picture: toViewDocument(history.present, options), error: now.error };
+}

package/dist/lib/authoring/BoardElementsPanel.d.ts

@@ -0,0 +1,14 @@
+import { type DesignerLabels } from '../labels.js';
+import type { Board, ElementDefinition } from '@iyulab/u-board/toolkit';
+export interface BoardElementsPanelProps {
+    board: Board;
+    /** The board's elements as the panel made them — none left: `undefined`. */
+    onChange: (elements: Record<string, ElementDefinition> | undefined) => void;
+    labels?: DesignerLabels;
+}
+/**
+ * The board's elements — drawings no built-in makes, each a template of markup with `{{prop}}` holes (or a script run in a
+ * sandboxed frame), its CSS, and the props it takes by name and type. An element is added by name — a template — and
+ * removed when no part draws it.
+ */
+export declare function BoardElementsPanel({ board, onChange, labels }: BoardElementsPanelProps): import("react").JSX.Element;