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

package/dist/lib/authoring/TriggersEditor.js

@@ -0,0 +1,137 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { FIELD_STYLE } from './field-style.js';
+import { useId, useState } from 'react';
+import { isTriggerLink, placedIn } from '@iyulab/u-board/picture';
+import { partNamer } from './part-names.js';
+import { stateNames } from './StatesEditor.js';
+import { removeTrigger, replaceTrigger, withTrigger } from '../editing/trigger-editing.js';
+import { ERROR_STYLE, GROUP_STYLE } from '@iyulab/u-board/toolkit';
+const ACTION_FIELD = { 'open-link': 'url', focus: 'node', emit: 'name', 'go-to-board': 'board' };
+function draftOf(trigger, group) {
+    const on = trigger.on;
+    return {
+        ...(group !== undefined && 'node' in on && on.node === group ? { every: true } : {}),
+        on: { event: on.event, name: on.event === 'element' ? on.name : '', state: on.event === 'enter' || on.event === 'leave' ? on.state : '' },
+        ...(trigger.when && { when: { node: trigger.when.node, state: [].concat(trigger.when.state).join(', ') } }),
+        do: trigger.do.map(action => ({ action: action.action, value: action[ACTION_FIELD[action.action]] })),
+    };
+}
+/** What is wrong with a draft — `incomplete` (a field left empty or too long), `link` (a link a board may not open) —
+ *  or the trigger it describes. The same rules saving checks, so the editor never writes what would be refused. */
+function triggerOf(draft, node) {
+    const name = (text) => text.length >= 1 && text.length <= 64;
+    const { event, name: eventName, state } = draft.on;
+    let on;
+    if (event === 'open' || node === undefined)
+        on = { event: 'open' };
+    else if (event === 'click')
+        on = { event, node };
+    else if (event === 'element') {
+        if (!name(eventName.trim()))
+            return { problem: 'incomplete' };
+        on = { event, node, name: eventName.trim() };
+    }
+    else {
+        if (state.trim() === '')
+            return { problem: 'incomplete' };
+        on = { event, node, state: state.trim() };
+    }
+    let when;
+    if (draft.when) {
+        const states = draft.when.state.split(',').map(s => s.trim()).filter(Boolean);
+        if (draft.when.node === '' || states.length === 0)
+            return { problem: 'incomplete' };
+        when = { node: draft.when.node, state: states.length === 1 ? states[0] : states };
+    }
+    if (draft.do.length === 0)
+        return { problem: 'incomplete' };
+    const actions = [];
+    for (const { action, value } of draft.do) {
+        const text = value.trim();
+        if (text === '')
+            return { problem: 'incomplete' };
+        if (action === 'open-link') {
+            if (!isTriggerLink(text))
+                return { problem: 'link' };
+            actions.push({ action, url: text });
+        }
+        else if (action === 'emit') {
+            if (!name(text))
+                return { problem: 'incomplete' };
+            actions.push({ action, name: text });
+        }
+        else if (action === 'focus')
+            actions.push({ action, node: text });
+        else {
+            if (text.length > 100)
+                return { problem: 'incomplete' };
+            actions.push({ action, board: text });
+        }
+    }
+    return { trigger: { on, ...(when && { when }), do: actions } };
+}
+/**
+ * A board's triggers, edited where an author thinks of them: on a part — clicked, an event of its element, a state
+ * entered or left — or, without a part, when the board opens. Each trigger is written as soon as it is complete and
+ * one a board may hold; until then the form says what is missing, and the document keeps what it had.
+ */
+export function TriggersEditor({ node, triggers, parts, stateNamesOf, nameOf, eachOf, onAdd, onReplace, onRemove, labels }) {
+    const group = node === undefined ? undefined : eachOf?.(node);
+    const shown = (triggers ?? []).flatMap((trigger, index) => node === undefined
+        ? (trigger.on.event === 'open' ? [{ trigger, index }] : [])
+        : 'node' in trigger.on && (trigger.on.node === node || (group !== undefined && trigger.on.node === group)) ? [{ trigger, index }] : []);
+    const [adding, setAdding] = useState(false);
+    const fresh = { on: { event: node === undefined ? 'open' : 'click', name: '', state: '' }, do: [{ action: 'emit', value: '' }] };
+    return (_jsxs("section", { className: "ub-panel__section", children: [_jsx("h3", { className: "ub-panel__subheading", children: node === undefined ? labels.triggersOnOpenHeading : labels.triggersHeading }), shown.map(({ trigger, index }, n) => (_jsx(TriggerRow, { n: n + 1, current: trigger, fresh: fresh, node, group, parts, stateNamesOf, nameOf, labels, onWrite: next => onReplace(index, next), onRemove: () => onRemove(index) }, `row-${n}`))), adding && (_jsx(TriggerRow, { n: shown.length + 1, current: undefined, fresh: fresh, node, group, parts, stateNamesOf, nameOf, labels, onWrite: next => {
+                    onAdd(next);
+                    setAdding(false);
+                }, onRemove: () => setAdding(false) }, `row-${shown.length}`)), !adding && (_jsx("button", { type: "button", className: "ub-action", onClick: () => setAdding(true), children: labels.addTrigger }))] }));
+}
+function TriggerRow({ n, current, fresh, node, group, parts, stateNamesOf, nameOf, labels, onWrite, onRemove, }) {
+    const [draft, setDraft] = useState(() => (current ? draftOf(current, group) : fresh));
+    // A trigger arriving that this row did not write (Undo, a row removed above it) replaces the draft.
+    const [seen, setSeen] = useState(current);
+    const [written, setWritten] = useState(current);
+    if (current !== seen) {
+        setSeen(current);
+        if (current !== written)
+            setDraft(current ? draftOf(current, group) : fresh);
+    }
+    const statesId = useId();
+    /** The node the trigger is about: the one being edited, or — for every item — the part they belong to. */
+    const target = (d) => (d.every && group !== undefined ? group : node);
+    const result = triggerOf(draft, target(draft));
+    const change = (next) => {
+        setDraft(next);
+        const made = triggerOf(next, target(next));
+        if ('trigger' in made) {
+            setWritten(made.trigger);
+            onWrite(made.trigger);
+        }
+    };
+    const label = (text) => text.replace('{n}', String(n));
+    const ownStates = node === undefined ? [] : stateNamesOf(node);
+    return (_jsxs("fieldset", { className: "ub-panel__trigger", style: { minWidth: 0 }, children: [_jsx("legend", { children: label(labels.triggerHeading) }), node !== undefined && (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerEvent, _jsxs("select", { value: draft.on.event, onChange: e => change({ ...draft, on: { ...draft.on, event: e.target.value } }), children: [_jsx("option", { value: "click", children: labels.triggerOnClick }), _jsx("option", { value: "element", children: labels.triggerOnElement }), _jsx("option", { value: "enter", children: labels.triggerOnEnter }), _jsx("option", { value: "leave", children: labels.triggerOnLeave })] })] })), group !== undefined && (_jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: !!draft.every, onChange: e => change({ ...draft, every: e.target.checked }) }), labels.triggerEveryItem.replace('{part}', group)] })), draft.on.event === 'element' && (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerEventName, _jsx("input", { value: draft.on.name, onChange: e => change({ ...draft, on: { ...draft.on, name: e.target.value } }), placeholder: "open-valve" })] })), (draft.on.event === 'enter' || draft.on.event === 'leave') && (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerState, _jsx("input", { list: `${statesId}-own`, value: draft.on.state, onChange: e => change({ ...draft, on: { ...draft.on, state: e.target.value } }), placeholder: "fault" })] })), (draft.on.event === 'enter' || draft.on.event === 'leave') && (_jsx("datalist", { id: `${statesId}-own`, children: ownStates.map(s => (_jsx("option", { value: s, children: s }, s))) })), _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: !!draft.when, onChange: e => change({ ...draft, when: e.target.checked ? { node: node ?? parts[0] ?? '', state: '' } : undefined }) }), labels.triggerOnlyWhen] }), draft.when && (_jsxs("div", { style: GROUP_STYLE, children: [_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerWhenPart, _jsx("select", { value: draft.when.node, onChange: e => change({ ...draft, when: { ...draft.when, node: e.target.value } }), children: parts.map(p => (_jsx("option", { value: p, children: optionName(p, nameOf) }, p))) })] }), _jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerWhenState, _jsx("input", { list: `${statesId}-when`, value: draft.when.state, onChange: e => change({ ...draft, when: { ...draft.when, state: e.target.value } }), placeholder: "fault, hot" })] }), _jsx("datalist", { id: `${statesId}-when`, children: stateNamesOf(draft.when.node).map(s => (_jsx("option", { value: s, children: s }, s))) })] })), draft.do.map((action, i) => {
+                const setAction = (next) => change({ ...draft, do: draft.do.map((a, j) => (j === i ? next : a)) });
+                const k = String(i + 1);
+                return (_jsxs("div", { className: "ub-panel__trigger-action", style: GROUP_STYLE, children: [_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerAction.replace('{n}', k), _jsxs("select", { value: action.action, onChange: e => setAction({ action: e.target.value, value: '' }), children: [_jsx("option", { value: "open-link", children: labels.triggerOpenLink }), _jsx("option", { value: "focus", children: labels.triggerFocus }), _jsx("option", { value: "emit", children: labels.triggerEmit }), _jsx("option", { value: "go-to-board", children: labels.triggerGoToBoard })] })] }), action.action === 'focus' ? (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.triggerFocusPart.replace('{n}', k), _jsxs("select", { value: action.value, onChange: e => setAction({ ...action, value: e.target.value }), children: [_jsx("option", { value: "", children: "\u2014" }), parts.map(p => (_jsx("option", { value: p, children: optionName(p, nameOf) }, p)))] })] })) : (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [(action.action === 'open-link' ? labels.triggerLinkUrl : action.action === 'emit' ? labels.triggerEmitName : labels.triggerBoardId).replace('{n}', k), _jsx("input", { value: action.value, onChange: e => setAction({ ...action, value: e.target.value }), placeholder: action.action === 'open-link' ? 'https://example.com/asset/{{node}}' : action.action === 'emit' ? 'details' : '' })] })), _jsx("button", { type: "button", className: "ub-action ub-action--icon", "aria-label": labels.removeTriggerAction.replace('{n}', k), onClick: () => change({ ...draft, do: draft.do.filter((_, j) => j !== i) }), children: "\u00D7" })] }, i));
+            }), _jsxs("div", { style: GROUP_STYLE, children: [_jsx("button", { type: "button", className: "ub-action", onClick: () => change({ ...draft, do: [...draft.do, { action: 'emit', value: '' }] }), children: labels.addTriggerAction }), _jsx("button", { type: "button", className: "ub-action", onClick: onRemove, children: label(labels.removeTrigger) })] }), 'problem' in result && (_jsx("p", { className: "ub-panel__hint", style: result.problem === 'link' ? ERROR_STYLE : undefined, children: result.problem === 'link' ? labels.triggerLinkRefused : labels.triggerIncomplete }))] }));
+}
+/** A part as a choice reads: its name and, when that is not its id, the id a trigger keeps. */
+function optionName(part, nameOf) {
+    const name = nameOf?.(part) ?? part;
+    return name === part ? part : `${name} (${part})`;
+}
+/** The parts a trigger may name are the parts the board places. */
+export function triggerEditing(doc, updateDoc, locale) {
+    const placed = placedIn(doc);
+    return {
+        triggers: doc.triggers,
+        parts: placed.map(part => part.id),
+        stateNamesOf: id => stateNames(placed.find(part => part.id === id)?.states?.map),
+        ...(doc.kind === 'canvas' && { nameOf: partNamer(doc, locale) }),
+        onAdd: trigger => updateDoc(current => withTrigger(current, trigger)),
+        onReplace: (index, trigger) => updateDoc(current => replaceTrigger(current, index, trigger)),
+        onRemove: index => updateDoc(current => removeTrigger(current, index)),
+    };
+}

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

@@ -0,0 +1,64 @@
+import { type DesignerLabels } from '../labels.js';
+import type { ValueMap } from '@iyulab/u-board/picture';
+/** A value map as a form edits it — rows of source value → mapped value, numeric bands, and the value for anything
+ *  else (empty: none). Written as text: a map's usual job is a status word, a level or a state's name. */
+export interface MapDraft {
+    mappings: MappingRow[];
+    /** Numeric bands → mapped value (`ValueMap.ranges`), tried after `mappings`. */
+    ranges: RangeRow[];
+    otherwise: string;
+    /** The map's `otherwise` as loaded, kept as it was unless its text is edited (see `MappingRow.loaded`). */
+    otherwiseLoaded?: {
+        value: unknown;
+    };
+}
+/** A row of the value map as the form edits it. `loaded` is the shown value the row was loaded with:
+ * while its text is left as shown, that value is saved back as it was — a number stays a number —
+ * rather than as the text the form displays it with. */
+export interface MappingRow {
+    from: string;
+    to: string;
+    loaded?: {
+        value: unknown;
+    };
+}
+/** A numeric range row as the form edits it: its bounds as typed (empty: that end is open) and
+ * its shown value, kept as loaded like `MappingRow.to`. */
+export interface RangeRow {
+    min: string;
+    max: string;
+    to: string;
+    loaded?: {
+        value: unknown;
+    };
+}
+/** The form's text for a mapped value — itself when it is text, its JSON otherwise. */
+export declare const asText: (value: unknown) => string;
+export declare function draftMap(map: ValueMap | undefined): MapDraft;
+/** The rows (1-based) whose range is not a range — a shown value with neither end, an upper end not
+ * above the lower one, or a bound that is not a number. Such a binding is not saved: a row with no
+ * end would be dropped silently, the others refused with the document. */
+export declare function invalidRanges(draft: MapDraft): number[];
+/** The `Binding.map` the form describes, or `undefined` when it describes none. A row without a
+ * source value, and a range row with neither end, is left out. */
+export declare function mapFromDraft(draft: MapDraft): ValueMap | undefined;
+export interface ValueMapFieldsProps {
+    draft: MapDraft;
+    /** Applies a change to the map's part of the draft. */
+    onChange: (update: (draft: MapDraft) => MapDraft) => void;
+    labels: DesignerLabels;
+    /** The heading — `labels.valueMapHeading` by default. */
+    heading?: string;
+    /** What a row maps to, as its field is named — `labels.mapTo` and `labels.rangeTo` by default ({n} is the row). */
+    toLabel?: {
+        mapping: string;
+        range: string;
+    };
+    /** Examples shown in a row's two sides while they are empty. */
+    placeholders?: {
+        from: string;
+        to: string;
+    };
+}
+/** The rows of a value map — source value → mapped value, numeric bands, the value for anything else — as one form. */
+export declare function ValueMapFields({ draft, onChange: setDraft, labels, heading, toLabel, placeholders, }: ValueMapFieldsProps): import("react").JSX.Element;

package/dist/lib/authoring/ValueMapFields.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { FIELD_STYLE } from './field-style.js';
+import { ERROR_STYLE } from '@iyulab/u-board/toolkit';
+/** The value a form field stands for: what it was loaded with if its text was not edited, else its text. */
+function fieldValue(text, loaded) {
+    return loaded && text === asText(loaded.value) ? loaded.value : text;
+}
+/** A row of the value map: its inputs share the line. */
+const ROW_STYLE = { display: 'flex', gap: 'var(--ub-space-1, 4px)', alignItems: 'center' };
+const ROW_INPUT_STYLE = { flex: 1, minWidth: 0 };
+/** The form's text for a mapped value — itself when it is text, its JSON otherwise. */
+export const asText = (value) => (typeof value === 'string' ? value : JSON.stringify(value));
+const boundText = (bound) => (bound === undefined ? '' : String(bound));
+export function draftMap(map) {
+    if (!map)
+        return { mappings: [], ranges: [], otherwise: '' };
+    return {
+        mappings: Object.entries(map.values ?? {}).map(([from, to]) => ({ from, to: asText(to), loaded: { value: to } })),
+        ranges: (map.ranges ?? []).map(r => ({ min: boundText(r.min), max: boundText(r.max), to: asText(r.value), loaded: { value: r.value } })),
+        otherwise: 'otherwise' in map ? asText(map.otherwise) : '',
+        ...('otherwise' in map && { otherwiseLoaded: { value: map.otherwise } }),
+    };
+}
+/** A range bound as typed: `undefined` when left empty (an open end), else the number it reads as. */
+const bound = (text) => (text.trim() === '' ? undefined : Number(text));
+/** The rows (1-based) whose range is not a range — a shown value with neither end, an upper end not
+ * above the lower one, or a bound that is not a number. Such a binding is not saved: a row with no
+ * end would be dropped silently, the others refused with the document. */
+export function invalidRanges(draft) {
+    return draft.ranges.flatMap((row, i) => {
+        const [min, max] = [bound(row.min), bound(row.max)];
+        const broken = (min === undefined && max === undefined && row.to.trim() !== '') ||
+            [min, max].some(b => b !== undefined && !Number.isFinite(b)) ||
+            (min !== undefined && max !== undefined && !(min < max));
+        return broken ? [i + 1] : [];
+    });
+}
+/** The `Binding.map` the form describes, or `undefined` when it describes none. A row without a
+ * source value, and a range row with neither end, is left out. */
+export function mapFromDraft(draft) {
+    const rows = draft.mappings.filter(row => row.from !== '');
+    const ranges = draft.ranges.filter(row => bound(row.min) !== undefined || bound(row.max) !== undefined);
+    if (rows.length === 0 && ranges.length === 0 && draft.otherwise === '')
+        return undefined;
+    return {
+        ...(rows.length > 0 || ranges.length === 0 ? { values: Object.fromEntries(rows.map(row => [row.from, fieldValue(row.to, row.loaded)])) } : {}),
+        ...(ranges.length > 0 && {
+            ranges: ranges.map(row => {
+                const [min, max] = [bound(row.min), bound(row.max)];
+                return { ...(min !== undefined && { min }), ...(max !== undefined && { max }), value: fieldValue(row.to, row.loaded) };
+            }),
+        }),
+        ...(draft.otherwise !== '' && { otherwise: fieldValue(draft.otherwise, draft.otherwiseLoaded) }),
+    };
+}
+/** The rows of a value map — source value → mapped value, numeric bands, the value for anything else — as one form. */
+export function ValueMapFields({ draft, onChange: setDraft, labels, heading = labels.valueMapHeading, toLabel = { mapping: labels.mapTo, range: labels.rangeTo }, placeholders = { from: 'Fault', to: 'error' }, }) {
+    const rangeIssues = invalidRanges(draft);
+    return (_jsxs("fieldset", { className: "ub-panel__value-map", style: { minWidth: 0 }, children: [_jsx("legend", { children: heading }), draft.mappings.map((row, i) => {
+                const n = String(i + 1);
+                const setRow = (change) => setDraft(d => ({ ...d, mappings: d.mappings.map((r, j) => (j === i ? { ...r, ...change } : r)) }));
+                return (_jsxs("div", { className: "ub-panel__map-row", style: ROW_STYLE, children: [_jsx("input", { style: ROW_INPUT_STYLE, "aria-label": labels.mapFrom.replace('{n}', n), value: row.from, onChange: e => setRow({ from: e.target.value }), placeholder: placeholders.from }), _jsx("span", { "aria-hidden": "true", children: "\u2192" }), _jsx("input", { style: ROW_INPUT_STYLE, "aria-label": toLabel.mapping.replace('{n}', n), value: row.to, onChange: e => setRow({ to: e.target.value }), placeholder: placeholders.to }), _jsx("button", { type: "button", className: "ub-action ub-action--icon", "aria-label": labels.removeMapping.replace('{n}', n), onClick: () => setDraft(d => ({ ...d, mappings: d.mappings.filter((_, j) => j !== i) })), children: "\u00D7" })] }, i));
+            }), _jsx("button", { type: "button", className: "ub-action", onClick: () => setDraft(d => ({ ...d, mappings: [...d.mappings, { from: '', to: '' }] })), children: labels.addMapping }), draft.ranges.map((row, i) => {
+                const n = String(i + 1);
+                const setRow = (change) => setDraft(d => ({ ...d, ranges: d.ranges.map((r, j) => (j === i ? { ...r, ...change } : r)) }));
+                return (_jsxs("div", { className: "ub-panel__map-row", style: ROW_STYLE, children: [_jsx("input", { type: "number", style: ROW_INPUT_STYLE, "aria-label": labels.rangeMin.replace('{n}', n), value: row.min, onChange: e => setRow({ min: e.target.value }), placeholder: "70" }), _jsx("span", { "aria-hidden": "true", children: "\u2264 x <" }), _jsx("input", { type: "number", style: ROW_INPUT_STYLE, "aria-label": labels.rangeMax.replace('{n}', n), value: row.max, onChange: e => setRow({ max: e.target.value }), placeholder: "80" }), _jsx("span", { "aria-hidden": "true", children: "\u2192" }), _jsx("input", { style: ROW_INPUT_STYLE, "aria-label": toLabel.range.replace('{n}', n), value: row.to, onChange: e => setRow({ to: e.target.value }), placeholder: "warning" }), _jsx("button", { type: "button", className: "ub-action ub-action--icon", "aria-label": labels.removeRange.replace('{n}', n), onClick: () => setDraft(d => ({ ...d, ranges: d.ranges.filter((_, j) => j !== i) })), children: "\u00D7" })] }, i));
+            }), _jsx("button", { type: "button", className: "ub-action", onClick: () => setDraft(d => ({ ...d, ranges: [...d.ranges, { min: '', max: '', to: '' }] })), children: labels.addRange }), rangeIssues.map(n => (_jsx("p", { role: "alert", className: "ub-panel__error", style: ERROR_STYLE, children: labels.rangeInvalid.replace('{n}', String(n)) }, n))), _jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [labels.mapOtherwise, _jsx("input", { value: draft.otherwise, onChange: e => setDraft(d => ({ ...d, otherwise: e.target.value })), placeholder: labels.mapOtherwisePlaceholder })] })] }));
+}

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

@@ -0,0 +1,27 @@
+import { type DesignerLabels } from '../labels.js';
+import type { ElementDefinition, Widget } from '@iyulab/u-board/picture';
+import { type WidgetField } from './widget-fields.js';
+export interface WidgetPropsFormProps {
+    widget: Widget;
+    onChange: (widget: Widget) => void;
+    labels?: DesignerLabels;
+    /** The board's elements, which a placed element's fields are read from. */
+    elements?: Readonly<Record<string, ElementDefinition>>;
+}
+/**
+ * A control for each value of the widget the widget library describes — its data fields, and the
+ * options whose type is known — or, for an element, each prop its definition's schema lists
+ * (`widgetFields`). A typed value is written when the control is left (or a choice is made), not on
+ * every keystroke: each change re-resolves the preview's bindings.
+ */
+export declare function WidgetPropsForm({ widget, onChange, labels, elements }: WidgetPropsFormProps): import("react").JSX.Element | null;
+/** The control for one field: `value` is its value now, `write` sets it (`undefined` takes it out), `bound` marks a value
+ *  a binding fills. A typed value is written when the control is left (or a choice is made), not on every keystroke. */
+/** The control of one field: a text, a number, a check box or a choice, named as the widget library names it. */
+export declare function FieldControl({ field, value, write, bound, labels }: {
+    field: WidgetField;
+    value: unknown;
+    write: (value: unknown) => void;
+    bound?: boolean;
+    labels: DesignerLabels;
+}): import("react").JSX.Element;

package/dist/lib/authoring/WidgetPropsForm.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DEFAULT_DESIGNER_LABELS } from '../labels.js';
+import { useMemo } from 'react';
+import { readField, widgetFields, withField } from './widget-fields.js';
+const FIELD_STYLE = { display: 'flex', flexDirection: 'column' };
+const CHECK_STYLE = { display: 'flex', alignItems: 'center', gap: 'var(--ub-space-2, 8px)' };
+const text = (value) => (value === undefined || value === null ? '' : typeof value === 'string' ? value : JSON.stringify(value));
+/**
+ * A control for each value of the widget the widget library describes — its data fields, and the
+ * options whose type is known — or, for an element, each prop its definition's schema lists
+ * (`widgetFields`). A typed value is written when the control is left (or a choice is made), not on
+ * every keystroke: each change re-resolves the preview's bindings.
+ */
+export function WidgetPropsForm({ widget, onChange, labels = DEFAULT_DESIGNER_LABELS, elements }) {
+    const { fields, otherOptions } = useMemo(() => widgetFields(widget, labels.locale, elements), [widget, labels.locale, elements]);
+    if (fields.length === 0 && otherOptions === 0)
+        return null;
+    const set = (field, value) => {
+        if (value === readField(widget, field))
+            return;
+        onChange(withField(widget, field, value));
+    };
+    const control = (field) => (_jsx(FieldControl, { field: field, value: readField(widget, field), write: value => set(field, value), bound: field.section !== 'options' && widget.bindings?.[field.path.join('.')] !== undefined, labels: labels }, field.path.join('.')));
+    const data = fields.filter(f => f.section === 'data');
+    const options = fields.filter(f => f.section === 'options');
+    const element = fields.filter(f => f.section === 'element');
+    return (_jsxs("div", { className: "ub-panel__widget-form", children: [element.length > 0 && (_jsxs("fieldset", { className: "ub-panel__group", style: { minWidth: 0 }, children: [_jsx("legend", { children: labels.elementProps }), element.map(control)] })), data.length > 0 && (_jsxs("fieldset", { className: "ub-panel__group", style: { minWidth: 0 }, children: [_jsx("legend", { children: labels.widgetData }), data.map(control)] })), options.length > 0 && (_jsxs("fieldset", { className: "ub-panel__group", style: { minWidth: 0 }, children: [_jsx("legend", { children: labels.widgetOptions }), options.map(control)] })), otherOptions > 0 && _jsx("p", { className: "ub-panel__hint", children: labels.moreInAdvanced.replace('{count}', String(otherOptions)) })] }));
+}
+/** The control for one field: `value` is its value now, `write` sets it (`undefined` takes it out), `bound` marks a value
+ *  a binding fills. A typed value is written when the control is left (or a choice is made), not on every keystroke. */
+/** The control of one field: a text, a number, a check box or a choice, named as the widget library names it. */
+export function FieldControl({ field, value, write, bound = false, labels }) {
+    const name = (_jsxs("span", { className: "ub-panel__field-name", title: field.description, children: [field.label, " ", _jsx("code", { children: field.key }), bound && _jsxs("span", { className: "ub-panel__binding-tag", children: [" \u00B7 ", labels.boundField] })] }));
+    const id = field.path.join('.');
+    switch (field.kind) {
+        case 'boolean':
+            return (_jsxs("label", { className: "ub-panel__field ub-panel__field--check", style: CHECK_STYLE, children: [_jsx("input", { type: "checkbox", checked: value === undefined ? field.defaultValue === true : value === true, onChange: e => write(e.target.checked) }), name] }, id));
+        case 'choice':
+            return (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [name, _jsxs("select", { value: typeof value === 'string' ? value : '', onChange: e => write(e.target.value === '' ? undefined : e.target.value), children: [_jsx("option", { value: "", children: field.defaultValue === undefined ? labels.choiceDefault : `${labels.choiceDefault} (${text(field.defaultValue)})` }), field.choices.map(choice => (_jsx("option", { value: choice, children: choice }, choice)))] })] }, id));
+        case 'number':
+            return (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [name, _jsx("input", { type: "number", min: field.min, max: field.max, step: field.integer ? 1 : undefined, defaultValue: typeof value === 'number' ? value : '', 
+                        // Left empty, the widget's own default applies — shown so the empty field does not read as nothing.
+                        placeholder: field.defaultValue === undefined ? undefined : text(field.defaultValue), onBlur: e => {
+                            const raw = e.currentTarget.value.trim();
+                            // Cleared: the widget's own default applies again. A whole-number field keeps whole numbers.
+                            const number = raw === '' || !Number.isFinite(Number(raw)) ? undefined : Number(raw);
+                            write(number !== undefined && field.integer ? Math.round(number) : number);
+                        } }, `${id}=${text(value)}`)] }, id));
+        case 'text':
+            return (_jsxs("label", { className: "ub-panel__field", style: FIELD_STYLE, children: [name, _jsx("input", { defaultValue: text(value), placeholder: field.defaultValue === undefined ? undefined : text(field.defaultValue), onBlur: e => {
+                            // Left as shown: nothing to write (an absent value stays absent).
+                            if (e.currentTarget.value !== text(value))
+                                write(e.currentTarget.value);
+                        } }, `${id}=${text(value)}`)] }, id));
+    }
+}

package/dist/lib/authoring/background-image.d.ts

@@ -0,0 +1,25 @@
+import type { BackgroundImage } from '@iyulab/u-board/picture';
+/** The image types a background may be — what every browser draws. */
+export declare const BACKGROUND_IMAGE_TYPES: string[];
+/** The largest background file accepted. The image is kept inside the document — a board needs no
+ *  other store, opens the same on a closed network, and is in every backup and exported file — so
+ *  it is bounded: every save and every open of the board carries it. */
+export declare const MAX_BACKGROUND_BYTES: number;
+export type BackgroundImageProblem = 'type' | 'size' | 'unreadable';
+export declare class BackgroundImageError extends Error {
+    readonly problem: BackgroundImageProblem;
+    constructor(problem: BackgroundImageProblem);
+}
+/** Reads a chosen file into a background: the image as a `data:` URL, and its own size in pixels —
+ *  the scene units the board is laid out in. Refuses another type, a file over the limit, and an
+ *  image the browser cannot draw or that has no size of its own. */
+export declare function readBackgroundImage(file: File, measure?: (src: string) => Promise<{
+    width: number;
+    height: number;
+}>): Promise<BackgroundImage>;
+/** An SVG drawing's size from its root element: `width`/`height` in plain numbers or pixels, else
+ *  its `viewBox`. Zero when it states neither. */
+export declare function svgSize(text: string): {
+    width: number;
+    height: number;
+};

package/dist/lib/authoring/background-image.js

@@ -0,0 +1,63 @@
+/** The image types a background may be — what every browser draws. */
+export const BACKGROUND_IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/svg+xml'];
+/** The largest background file accepted. The image is kept inside the document — a board needs no
+ *  other store, opens the same on a closed network, and is in every backup and exported file — so
+ *  it is bounded: every save and every open of the board carries it. */
+export const MAX_BACKGROUND_BYTES = 4 * 1024 * 1024;
+export class BackgroundImageError extends Error {
+    problem;
+    constructor(problem) {
+        super(`background image refused: ${problem}`);
+        this.problem = problem;
+    }
+}
+/** Reads a chosen file into a background: the image as a `data:` URL, and its own size in pixels —
+ *  the scene units the board is laid out in. Refuses another type, a file over the limit, and an
+ *  image the browser cannot draw or that has no size of its own. */
+export async function readBackgroundImage(file, measure = naturalSize) {
+    // Some systems give an SVG file no type; its name still says what it is.
+    const type = file.type || (/\.svg$/i.test(file.name) ? 'image/svg+xml' : '');
+    if (!BACKGROUND_IMAGE_TYPES.includes(type))
+        throw new BackgroundImageError('type');
+    if (file.size > MAX_BACKGROUND_BYTES)
+        throw new BackgroundImageError('size');
+    const src = await readAsDataUrl(type === file.type ? file : new Blob([file], { type }));
+    let { width, height } = await measure(src).catch(() => ({ width: 0, height: 0 }));
+    // An SVG sized only by its viewBox has no size the browser reports; read it from the drawing.
+    if (!(width > 0 && height > 0) && type === 'image/svg+xml')
+        ({ width, height } = svgSize(await file.text()));
+    if (!(width > 0 && height > 0))
+        throw new BackgroundImageError('unreadable');
+    return { src, width, height };
+}
+/** An SVG drawing's size from its root element: `width`/`height` in plain numbers or pixels, else
+ *  its `viewBox`. Zero when it states neither. */
+export function svgSize(text) {
+    const root = /<svg\b[^>]*>/i.exec(text)?.[0] ?? '';
+    const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, 'i').exec(root)?.[1];
+    const pixels = (value) => (value && /^\s*[\d.]+\s*(px)?\s*$/i.test(value) ? parseFloat(value) : NaN);
+    const width = pixels(attr('width'));
+    const height = pixels(attr('height'));
+    if (width > 0 && height > 0)
+        return { width, height };
+    const box = attr('viewBox')?.trim().split(/[\s,]+/).map(Number);
+    if (box?.length === 4 && box[2] > 0 && box[3] > 0)
+        return { width: box[2], height: box[3] };
+    return { width: 0, height: 0 };
+}
+function readAsDataUrl(file) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result);
+        reader.onerror = () => reject(new BackgroundImageError('unreadable'));
+        reader.readAsDataURL(file);
+    });
+}
+function naturalSize(src) {
+    return new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve({ width: image.naturalWidth, height: image.naturalHeight });
+        image.onerror = () => reject(new Error('the image could not be drawn'));
+        image.src = src;
+    });
+}

package/dist/lib/authoring/board-layout.d.ts

@@ -0,0 +1,64 @@
+import { type ViewDocument } from '@iyulab/u-board/picture';
+import type { Board, Shape } from '@iyulab/u-board/toolkit';
+/**
+ * Whether the editor lays this board out: a canvas, or a grid — of parts, canvases, and grids of parts and canvases in
+ * its cells (one level, as the picture draws them). A grid in a cell is laid out on its own (`cellBoard`): the picture
+ * flattens it into the outer grid's rows, which the editor does not say back item by item.
+ */
+export declare function layoutEditable(board: Board): boolean;
+/** The id the picture draws a grid's canvas cell — entry `i` of its items — with; what it draws in the cell is named
+ *  past `<id>:`. */
+export declare function cellId(i: number): string;
+/** The grid entry a canvas cell's id names, if the board has a canvas there. */
+export declare function cellIndex(board: Board, id: string): number | undefined;
+/** The grid entry holding a grid that the picture's item `id` is drawn from — one of its parts (or their items), or a
+ *  canvas in it (`cell-<i>-<j>`) — if it is one. */
+export declare function gridCellOf(board: Board, id: string): number | undefined;
+/** The cell of grid entry `i` — a canvas, or a grid — as a board of its own: the board, that cell its layout. */
+export declare function cellBoard(board: Board, i: number): Board | undefined;
+/** The board with grid entry `i`'s cell — and its parts, triggers and all the rest — as `cell` (one `cellBoard` gave,
+ *  edited) has them. */
+export declare function withCell(board: Board, i: number, cell: Board): Board;
+/** The id the picture draws a board's own link with — `link.<id>`. */
+export declare const LINK = "link.";
+/** The link of a canvas board a picture connector `id` draws, if it is one of the board's own (not a group's). */
+export declare function linkOf(board: Board, id: string): string | undefined;
+/** The id the picture draws a board's own shape with — `shape.<id>`. */
+export declare const SHAPE = "shape.";
+/** The shape of a canvas board a picture piece `id` draws, if it is one of the board's own — a box or a text (drawn as a
+ *  decoration), or a line or a path (drawn as a node of its own). */
+export declare function shapeOf(board: Board, id: string): string | undefined;
+/** The line or path of a canvas board a picture node `id` draws, if it is one. */
+export declare function lineOf(board: Board, id: string): string | undefined;
+/** A line or path moved and sized as its node was, from box `from` to box `to`: each point where it stands in the box. */
+export declare function shapeIn(shape: Shape, from: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, to: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): Shape;
+/** The board with a new shape — a box, a text, or a line — at the canvas's top left, stepped from the shapes it has, and its
+ *  id. */
+export declare function withNewShape(board: Board, kind: 'box' | 'text' | 'line', text: string): {
+    board: Board;
+    id: string;
+};
+/** The board with a new link from part `from` to part `to` — drawn with an arrowhead, as a flow is — and its id. */
+export declare function withNewLink(board: Board, from: string, to: string): {
+    board: Board;
+    id: string;
+};
+/** Whether the picture node or item `id` is one the board places itself: a part, or an item of an `each` part — not a
+ *  part inside a group, which moves with its group. */
+export declare function placesItself(board: Board, id: string): boolean;
+/**
+ * The board with its canvas layout as the picture `after` shows it, the picture having been `before`: each part (or
+ * item) that moved or was sized placed where it is now, each part deleted gone — with the links and triggers that
+ * named it. An item of an `each` part is there while its data has it, so deleting one deletes nothing.
+ */
+export declare function withPictureLayout(board: Board, before: ViewDocument, after: ViewDocument): Board;