forgebook 0.3.3 → 0.4.0

package/dist/src/shell/valueEditors/FileEditor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A `file` control: small files kept as `data:` addresses, since the value must be JSON a link can hold. A file too large
+ * for an address, or of a type a browser would run as a page, is refused with the reason, as the check on a link would
+ * refuse it (`addressArgs.ts`).
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import { type ArgValue } from "../../messages.ts";
+/** The file control's props. */
+export type FileEditorProps = {
+    /** The field's name. */
+    readonly label: string;
+    /** The element that describes it. */
+    readonly describedBy: string;
+    /** The files it takes, as `<input accept>` writes it. */
+    readonly accept: string | undefined;
+    /** The kept files. */
+    readonly value: ArgValue | undefined;
+    /** Called with the kept files; none when none is left. */
+    readonly onChange: (value: readonly string[] | undefined) => void;
+};
+/**
+ * The file control.
+ *
+ * @param props - the field's name, what it takes, and the kept files.
+ */
+export declare const FileEditor: ({ label, describedBy, accept, value, onChange }: FileEditorProps) => ReactNode;

package/dist/src/shell/valueEditors/FileEditor.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A `file` control: small files kept as `data:` addresses, since the value must be JSON a link can hold. A file too large
+ * for an address, or of a type a browser would run as a page, is refused with the reason, as the check on a link would
+ * refuse it (`addressArgs.ts`).
+ *
+ * @module
+ */
+import { useState } from "react";
+import { isChoiceList } from "../../messages.js";
+import { isFileText, MOST_FILE_TEXT } from "../../shapeValues.js";
+import { Icon } from "../icons.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+/** A file as a `data:` address. */
+const readFile = (file) => new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(typeof reader.result === "string" ? reader.result : "");
+    reader.onerror = () => reject(new Error(file.name));
+    reader.readAsDataURL(file);
+});
+/** A length in bytes, for a person. */
+const sizeText = (bytes) => (bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`);
+/** What a kept file is, from its address. */
+const fileLine = (text) => {
+    const comma = text.indexOf(",");
+    const type = text.slice(5, comma).split(";")[0] ?? "";
+    // what base64 holds: three bytes for each four characters
+    return EDITOR_STRINGS.fileLine(type, sizeText(Math.floor(((text.length - comma - 1) * 3) / 4)));
+};
+/**
+ * The file control.
+ *
+ * @param props - the field's name, what it takes, and the kept files.
+ */
+export const FileEditor = ({ label, describedBy, accept, value, onChange }) => {
+    const files = isChoiceList(value) ? value.filter((each) => typeof each === "string") : [];
+    const [problems, setProblems] = useState([]);
+    const add = async (chosen) => {
+        const kept = [];
+        const refused = [];
+        for (const file of chosen) {
+            try {
+                const text = await readFile(file);
+                if (text.length > MOST_FILE_TEXT)
+                    refused.push(EDITOR_STRINGS.fileTooLarge(file.name, sizeText((MOST_FILE_TEXT * 3) / 4)));
+                else if (isFileText(text))
+                    kept.push(text);
+                else
+                    refused.push(EDITOR_STRINGS.fileRefused(file.name));
+            }
+            catch {
+                refused.push(EDITOR_STRINGS.fileFailed(file.name));
+            }
+        }
+        setProblems(refused);
+        if (kept.length > 0)
+            onChange([...files, ...kept]);
+    };
+    return (_jsxs("div", { className: "forgebook-value-list", children: [_jsx("input", { type: "file", multiple: true, "aria-label": EDITOR_STRINGS.fileChoose(label), "aria-describedby": describedBy, ...(accept === undefined ? {} : { accept }), onChange: (event) => {
+                    void add([...(event.target.files ?? [])]);
+                    event.target.value = "";
+                } }), files.map((file, index) => (_jsxs("div", { className: "forgebook-value-list__item", children: [_jsx("span", { className: "forgebook-value-list__field forgebook-value-note", children: fileLine(file) }), _jsx("div", { className: "forgebook-value-list__buttons", children: _jsx("button", { type: "button", className: "forgebook-prop__action", "aria-label": EDITOR_STRINGS.fileRemove(EDITOR_STRINGS.itemName(label, index + 1)), onClick: () => {
+                                const left = files.filter((_, position) => position !== index);
+                                onChange(left.length === 0 ? undefined : left);
+                            }, children: _jsx(Icon, { name: "close", size: 12 }) }) })] }, file))), problems.map((problem) => (_jsx("p", { className: "forgebook-value-note", "data-tone": "problem", role: "alert", children: problem }, problem)))] }));
+};

package/dist/src/shell/valueEditors/JsonEditor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A value typed as JSON: the way out for what cannot be drawn as fields, and for pasting a whole value. What does not
+ * parse, or is not what the prop takes, stays in the field with the reason beside it and never reaches the story.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { FieldProps } from "./fieldTypes.ts";
+/**
+ * A value's JSON field.
+ *
+ * @param props - the field's props.
+ */
+export declare const JsonEditor: ({ shape, value, label, describedBy, namedValues, onChange }: FieldProps) => ReactNode;

package/dist/src/shell/valueEditors/JsonEditor.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A value typed as JSON: the way out for what cannot be drawn as fields, and for pasting a whole value. What does not
+ * parse, or is not what the prop takes, stays in the field with the reason beside it and never reaches the story.
+ *
+ * @module
+ */
+import { useId, useState } from "react";
+import { isArgValue } from "../../messages.js";
+import { isValueOfShape } from "../../shapeValues.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+/** A value as the field writes it. */
+const jsonText = (value) => value === undefined ? "" : JSON.stringify(value, null, 2);
+/** What a text says: the value it writes, or why it is not one. */
+const readJson = (text, { shape, namedValues }) => {
+    if (text.trim() === "")
+        return { value: undefined };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { problem: EDITOR_STRINGS.jsonInvalid(error instanceof Error ? error.message : String(error)) };
+    }
+    if (!isArgValue(parsed))
+        return { problem: EDITOR_STRINGS.jsonRefused };
+    return isValueOfShape(shape, parsed, namedValues)
+        ? { value: parsed }
+        : { problem: EDITOR_STRINGS.jsonMisfit };
+};
+/**
+ * A value's JSON field.
+ *
+ * @param props - the field's props.
+ */
+export const JsonEditor = ({ shape, value, label, describedBy, namedValues, onChange }) => {
+    const problemId = useId();
+    const written = jsonText(value);
+    const [draft, setDraft] = useState({ text: written, before: written, after: written });
+    // a value changed from outside (Reset, the worst case) replaces what was typed; the field's own stays as typed, and so
+    // does what its parent did not take (an item of a list cannot be left without a value)
+    const text = draft.before === written || draft.after === written ? draft.text : written;
+    const read = readJson(text, { shape, namedValues });
+    const problem = "problem" in read ? read.problem : undefined;
+    return (_jsxs("div", { className: "forgebook-value-json", children: [_jsx("textarea", { className: "forgebook-value-json__text", "aria-label": label, "aria-describedby": problem === undefined ? describedBy : problemId, "aria-invalid": problem !== undefined, spellCheck: false, rows: Math.min(12, Math.max(3, text.split("\n").length)), value: text, onChange: (event) => {
+                    const next = event.target.value;
+                    const nextRead = readJson(next, { shape, namedValues });
+                    const after = "value" in nextRead ? jsonText(nextRead.value) : written;
+                    setDraft({ text: next, before: written, after });
+                    if ("value" in nextRead)
+                        onChange(nextRead.value);
+                } }), problem === undefined ? null : (_jsx("p", { id: problemId, className: "forgebook-value-note", "data-tone": "problem", role: "alert", children: problem }))] }));
+};

package/dist/src/shell/valueEditors/ListEditor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A list's items as fields, added, removed and moved with buttons, so a keyboard does all a pointer does: the focus
+ * follows an item it moved, and a screen reader is told where it went.
+ *
+ * @remarks
+ * Items keep their place as their key: an item has no identity of its own in JSON, and a key that moved with the value
+ * would take the focus out of the field being typed in on every keystroke.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { ValueShape } from "../../valueShape.ts";
+import type { DrawField, FieldProps } from "./fieldTypes.ts";
+/**
+ * A list's editor.
+ *
+ * @param props - the field's props, and how to draw an item.
+ */
+export declare const ListEditor: ({ shape, value, label, namedValues, depth, onChange, drawField }: FieldProps & {
+    readonly shape: {
+        readonly of: ValueShape;
+    };
+    readonly drawField: DrawField;
+}) => ReactNode;

package/dist/src/shell/valueEditors/ListEditor.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A list's items as fields, added, removed and moved with buttons, so a keyboard does all a pointer does: the focus
+ * follows an item it moved, and a screen reader is told where it went.
+ *
+ * @remarks
+ * Items keep their place as their key: an item has no identity of its own in JSON, and a key that moved with the value
+ * would take the focus out of the field being typed in on every keystroke.
+ *
+ * @module
+ */
+import { useEffect, useRef, useState } from "react";
+import { isArgList } from "../../messages.js";
+import { startValueOf } from "../../shapeValues.js";
+import { Icon } from "../icons.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+/** The arrows, drawn as text: the first screen's icons stay what the first screen uses. */
+const ARROWS = { up: "↑", down: "↓" };
+/** One small button of an item; at an end of the list it does nothing, but keeps the focus it was given. */
+const ItemButton = ({ action, label, isOff = false, onPress }) => (_jsx("button", { type: "button", className: "forgebook-prop__action", "data-action": action, "aria-label": label, title: label, "aria-disabled": isOff || undefined, onClick: isOff ? undefined : onPress, children: action === "remove" ? _jsx(Icon, { name: "close", size: 12 }) : ARROWS[action] }));
+/**
+ * A list's editor.
+ *
+ * @param props - the field's props, and how to draw an item.
+ */
+export const ListEditor = ({ shape, value, label, namedValues, depth, onChange, drawField }) => {
+    const items = value !== undefined && isArgList(value) ? value : [];
+    const listRef = useRef(null);
+    const pending = useRef(undefined);
+    const [announcement, setAnnouncement] = useState("");
+    const itemShape = shape.of;
+    const start = startValueOf(itemShape, namedValues);
+    useEffect(() => {
+        const focus = pending.current;
+        if (focus === undefined)
+            return;
+        pending.current = undefined;
+        const selector = focus.action === "add"
+            ? "[data-action='add']"
+            : `[data-item='${focus.index}'] [data-action='${focus.action}']`;
+        const fallback = listRef.current?.querySelector("[data-action='add']");
+        (listRef.current?.querySelector(selector) ?? fallback)?.focus();
+    });
+    const itemLabel = (index) => EDITOR_STRINGS.itemName(label, index + 1);
+    const move = (index, by, action) => {
+        const next = [...items];
+        const [item] = next.splice(index, 1);
+        if (item === undefined)
+            return;
+        next.splice(index + by, 0, item);
+        pending.current = { index: index + by, action };
+        setAnnouncement(EDITOR_STRINGS.itemMoved(itemLabel(index), index + by + 1, next.length));
+        onChange(next);
+    };
+    const remove = (index) => {
+        const next = items.filter((_, position) => position !== index);
+        pending.current =
+            next.length === 0
+                ? { index: 0, action: "add" }
+                : { index: Math.min(index, next.length - 1), action: "remove" };
+        setAnnouncement(EDITOR_STRINGS.itemRemoved(itemLabel(index), next.length));
+        onChange(next);
+    };
+    const change = (index, item) => {
+        if (item === undefined)
+            return;
+        onChange(items.map((each, position) => (position === index ? item : each)));
+    };
+    return (_jsxs("div", { className: "forgebook-value-list", ref: listRef, children: [items.length === 0 ? _jsx("p", { className: "forgebook-value-note", children: EDITOR_STRINGS.emptyList }) : null, items.map((item, index) => (_jsxs("div", { className: "forgebook-value-list__item", "data-item": index, children: [_jsx("div", { className: "forgebook-value-list__field", children: drawField({
+                            shape: itemShape,
+                            value: item,
+                            label: itemLabel(index),
+                            namedValues,
+                            depth: depth + 1,
+                            isRequired: true,
+                            onChange: (next) => change(index, next)
+                        }) }), _jsxs("div", { className: "forgebook-value-list__buttons", children: [_jsx(ItemButton, { action: "up", label: EDITOR_STRINGS.moveUp(itemLabel(index)), isOff: index === 0, onPress: () => move(index, -1, "up") }), _jsx(ItemButton, { action: "down", label: EDITOR_STRINGS.moveDown(itemLabel(index)), isOff: index === items.length - 1, onPress: () => move(index, 1, "down") }), _jsx(ItemButton, { action: "remove", label: EDITOR_STRINGS.removeItem(itemLabel(index)), onPress: () => remove(index) })] })] }, index))), _jsxs("button", { type: "button", className: "forgebook-text-button forgebook-value-add", "data-action": "add", disabled: start === undefined, onClick: () => {
+                    if (start === undefined)
+                        return;
+                    onChange([...items, start]);
+                }, children: [_jsx(Icon, { name: "plus", size: 12 }), EDITOR_STRINGS.addItem(label)] }), _jsx("span", { className: "forgebook-visually-hidden", role: "status", children: announcement })] }));
+};

package/dist/src/shell/valueEditors/ObjectEditor.d.ts

@@ -0,0 +1,32 @@
+/**
+ * An object's fields, one under the other, and a tuple's items: what a type declares, each with its name, whether it is
+ * required, and a way to take an optional one away.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type ShapeField, type ValueShape } from "../../valueShape.ts";
+import type { DrawField, FieldProps } from "./fieldTypes.ts";
+/**
+ * An object's editor. The first change starts from what the required fields must hold, so what reaches the story always
+ * fits its type.
+ *
+ * @param props - the field's props, and how to draw a field.
+ */
+export declare const ObjectEditor: ({ shape, value, label, namedValues, depth, onChange, drawField }: FieldProps & {
+    readonly shape: {
+        readonly fields: readonly ShapeField[];
+    };
+    readonly drawField: DrawField;
+}) => ReactNode;
+/**
+ * A tuple's editor: its items, fixed in number, each of its own shape.
+ *
+ * @param props - the field's props, and how to draw an item.
+ */
+export declare const TupleEditor: ({ shape, value, label, namedValues, depth, onChange, drawField }: FieldProps & {
+    readonly shape: {
+        readonly items: readonly ValueShape[];
+    };
+    readonly drawField: DrawField;
+}) => ReactNode;

package/dist/src/shell/valueEditors/ObjectEditor.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isArgList, isArgObject } from "../../messages.js";
+import { startValueOf } from "../../shapeValues.js";
+import { canSetShape } from "../../valueShape.js";
+import { Icon } from "../icons.js";
+import { STRINGS } from "../strings.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+/** Whether a field's shape opens further: an optional one that holds nothing stays closed behind a button. */
+const opensFurther = (shape) => shape.kind === "object" || shape.kind === "list" || shape.kind === "record" || shape.kind === "tuple";
+/** One field of an object: its name and its value, or the button that gives it one. */
+const ObjectField = ({ field, value, label, namedValues, depth, onChange, drawField }) => {
+    const fieldLabel = EDITOR_STRINGS.fieldValue(label, field.name);
+    const start = startValueOf(field.shape, namedValues);
+    const isClosed = value === undefined && !field.isRequired && opensFurther(field.shape);
+    return (_jsxs("div", { className: "forgebook-value-field", children: [_jsxs("div", { className: "forgebook-value-field__head", children: [_jsxs("code", { className: "forgebook-value-field__name", title: field.description, children: [field.name, field.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), value === undefined || field.isRequired ? null : (_jsx("button", { type: "button", className: "forgebook-prop__action", "aria-label": EDITOR_STRINGS.clearField(fieldLabel), title: EDITOR_STRINGS.clearField(fieldLabel), onClick: () => onChange(undefined), children: _jsx(Icon, { name: "noValue", size: 12 }) }))] }), isClosed ? (_jsxs("button", { type: "button", className: "forgebook-text-button forgebook-value-add", disabled: start === undefined, onClick: () => onChange(start), children: [_jsx(Icon, { name: "plus", size: 12 }), EDITOR_STRINGS.addField(fieldLabel)] })) : (drawField({
+                shape: field.shape,
+                value,
+                label: fieldLabel,
+                namedValues,
+                depth: depth + 1,
+                isRequired: field.isRequired,
+                onChange: (next) => {
+                    // a required field cannot go: what reaches the story always fits its type
+                    if (next !== undefined || !field.isRequired)
+                        onChange(next);
+                }
+            }))] }));
+};
+/**
+ * An object's editor. The first change starts from what the required fields must hold, so what reaches the story always
+ * fits its type.
+ *
+ * @param props - the field's props, and how to draw a field.
+ */
+export const ObjectEditor = ({ shape, value, label, namedValues, depth, onChange, drawField }) => {
+    const current = value !== undefined && isArgObject(value) ? value : {};
+    const change = (name, next) => {
+        const started = startValueOf({ kind: "object", fields: shape.fields }, namedValues);
+        const base = value === undefined && started !== undefined && isArgObject(started) ? started : current;
+        const { [name]: _removed, ...rest } = base;
+        onChange(next === undefined ? rest : { ...base, [name]: next });
+    };
+    return (_jsx("div", { className: "forgebook-value-object", "data-depth": depth, children: shape.fields
+            // a part only the source's named values can fill, and it names none, has nothing to draw
+            .filter((field) => canSetShape(field.shape, namedValues))
+            .map((field) => (_jsx(ObjectField, { field: field, value: Object.hasOwn(current, field.name) ? current[field.name] : undefined, label: label, namedValues: namedValues, depth: depth, onChange: (next) => change(field.name, next), drawField: drawField }, field.name))) }));
+};
+/**
+ * A tuple's editor: its items, fixed in number, each of its own shape.
+ *
+ * @param props - the field's props, and how to draw an item.
+ */
+export const TupleEditor = ({ shape, value, label, namedValues, depth, onChange, drawField }) => {
+    const current = value !== undefined && isArgList(value) ? value : undefined;
+    const started = startValueOf({ kind: "tuple", items: shape.items }, namedValues);
+    const base = current ?? (started !== undefined && isArgList(started) ? started : []);
+    return (_jsx("div", { className: "forgebook-value-tuple", children: shape.items.map((item, index) => (_jsx("div", { className: "forgebook-value-field", children: drawField({
+                shape: item,
+                value: current?.[index],
+                label: EDITOR_STRINGS.itemName(label, index + 1),
+                namedValues,
+                depth: depth + 1,
+                isRequired: true,
+                onChange: (next) => {
+                    if (next === undefined)
+                        return;
+                    onChange(base.map((each, position) => (position === index ? next : each)));
+                }
+            }) }, index))) }));
+};

package/dist/src/shell/valueEditors/PropEditor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The panel's editors that load on use, as one prop asks for them: nested fields from its shape, a search among its
+ * options or the source's named values, the catalogue's tokens, files. A catalogue of plain props never loads this module
+ * (`PropRows.tsx`).
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { PanelProp } from "../../argTypes.ts";
+import { type ArgValue } from "../../messages.ts";
+import type { NamedValues } from "../../namedValues.ts";
+import type { ArgControlLoaders } from "../customControls.ts";
+import type { OnValueChange } from "../PropFields.tsx";
+import "./valueEditors.scss";
+/** The editor's props. */
+export type PropEditorProps = {
+    /** The prop. */
+    readonly prop: PanelProp;
+    /** Its value. */
+    readonly value: ArgValue | undefined;
+    /** The element that describes it. */
+    readonly descriptionId: string;
+    /** The source's named values. */
+    readonly namedValues: NamedValues;
+    /** Loads the catalogue's design tokens; none when it has none. */
+    readonly loadTokens: (() => Promise<unknown>) | undefined;
+    /** Loads each custom control the catalogue registers, by name; none when it registers none. */
+    readonly argControls: ArgControlLoaders | undefined;
+    /** Called with a changed value. */
+    readonly onValueChange: OnValueChange;
+};
+/**
+ * One prop's editor.
+ *
+ * @param props - the prop, its value, and what it may draw from.
+ */
+export declare const PropEditor: ({ prop, value, descriptionId, namedValues, loadTokens, argControls, onValueChange }: PropEditorProps) => ReactNode;

package/dist/src/shell/valueEditors/PropEditor.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { UNSET_ARG } from "../../messages.js";
+import { resolvedShape } from "../../shapeValues.js";
+import { canSetShape } from "../../valueShape.js";
+import { LazyView, lazyModule } from "../lazyModule.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+import { FileEditor } from "./FileEditor.js";
+import { SearchSelect } from "./SearchSelect.js";
+import { TokenEditor } from "./TokenEditor.js";
+import { ValueField } from "./ValueField.js";
+import "./valueEditors.css";
+/** The host of the custom controls, which a catalogue with none never loads. */
+const CUSTOM_CONTROL = lazyModule(() => import("../CustomControl.js").then((module) => module.CustomControl));
+/** No custom control registered. */
+const NO_ARG_CONTROLS = {};
+/** A custom control's field: its host loads with the first, so an editor of any other kind pays nothing for it. */
+const CustomField = ({ prop, name, value, argControls, onValueChange }) => (_jsx(LazyView, { module: CUSTOM_CONTROL, props: { prop, name, value, loaders: argControls ?? NO_ARG_CONTROLS, onValueChange }, loading: null, failed: (message) => (_jsx("p", { className: "forgebook-prop__description forgebook-prop__problem", role: "alert", children: message })) }));
+/** A prop's fields, or why it has none: a required part only named values can fill, and the source names none. */
+const ShapedField = (props) => canSetShape(props.shape, props.namedValues) ? (_jsx(ValueField, { ...props })) : (_jsx("p", { className: "forgebook-value-note", children: EDITOR_STRINGS.cannotSet }));
+/**
+ * One prop's editor.
+ *
+ * @param props - the prop, its value, and what it may draw from.
+ */
+export const PropEditor = ({ prop, value, descriptionId, namedValues, loadTokens, argControls, onValueChange }) => {
+    const label = prop.label ?? prop.name;
+    const change = (next) => onValueChange(prop.name, next ?? UNSET_ARG);
+    if (prop.customControl !== undefined) {
+        return (_jsx(CustomField, { prop: prop, name: prop.customControl, value: value, argControls: argControls, onValueChange: onValueChange }));
+    }
+    if (prop.control === "file") {
+        return (_jsx(FileEditor, { label: label, describedBy: descriptionId, accept: prop.accept, value: value, onChange: change }));
+    }
+    if (prop.control === "token" && prop.tokens !== undefined) {
+        return (_jsx(TokenEditor, { label: label, describedBy: descriptionId, tokens: prop.tokens, value: typeof value === "string" ? value : undefined, loadTokens: loadTokens, onChange: change }));
+    }
+    if (Object.hasOwn(namedValues, prop.type) && prop.control === undefined && prop.kind === "other") {
+        return (_jsx(ValueField, { shape: {
+                kind: "named",
+                type: prop.type,
+                ...(prop.canTakeText === true ? { canTakeText: true } : {})
+            }, value: value, label: label, describedBy: descriptionId, namedValues: namedValues, depth: 0, onChange: change }));
+    }
+    if (prop.shape !== undefined) {
+        return (_jsx(ShapedField, { shape: resolvedShape(prop.shape), value: value, label: label, describedBy: descriptionId, namedValues: namedValues, depth: 0, onChange: change }));
+    }
+    // many options, searched
+    const choices = prop.choices ?? [];
+    return (_jsx(SearchSelect, { label: label, describedBy: descriptionId, options: choices.map((choice) => ({
+            value: String(choice),
+            label: prop.labels?.[String(choice)] ?? String(choice)
+        })), value: typeof value === "string" || typeof value === "number" ? String(value) : undefined, onChange: (text) => change(choices.find((choice) => String(choice) === text)) }));
+};

package/dist/src/shell/valueEditors/RecordEditor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Any names, each holding a value of one shape (`Record<string, number>`): each entry's name and value, added and
+ * removed. A name that cannot be kept stays in its field with the reason beside it, and the value is untouched.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { ValueShape } from "../../valueShape.ts";
+import type { DrawField, FieldProps } from "./fieldTypes.ts";
+/**
+ * A record's editor.
+ *
+ * @param props - the field's props, and how to draw a value.
+ */
+export declare const RecordEditor: ({ shape, value, label, namedValues, depth, onChange, drawField }: FieldProps & {
+    readonly shape: {
+        readonly of: ValueShape;
+    };
+    readonly drawField: DrawField;
+}) => ReactNode;

package/dist/src/shell/valueEditors/RecordEditor.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Any names, each holding a value of one shape (`Record<string, number>`): each entry's name and value, added and
+ * removed. A name that cannot be kept stays in its field with the reason beside it, and the value is untouched.
+ *
+ * @module
+ */
+import { useId, useState } from "react";
+import { isArgObject } from "../../messages.js";
+import { isUnsafeFreeName, startValueOf } from "../../shapeValues.js";
+import { Icon } from "../icons.js";
+import { EDITOR_STRINGS } from "./editorStrings.js";
+/** Names no object holds: a component that merges it would write on every object of the page. */
+const PROTOTYPE_NAMES = ["__proto__", "constructor", "prototype"];
+/** Why a name cannot be kept, or none when it can. */
+const nameProblem = (name, others) => {
+    if (name === "")
+        return EDITOR_STRINGS.nameEmpty;
+    if (others.includes(name))
+        return EDITOR_STRINGS.nameTaken;
+    return PROTOTYPE_NAMES.includes(name) || isUnsafeFreeName(name) ? EDITOR_STRINGS.nameRefused : undefined;
+};
+/** An entry's name: what is typed stays here until it can be kept. */
+const EntryName = ({ name, others, label, onRename }) => {
+    const problemId = useId();
+    const [draft, setDraft] = useState(name);
+    // the row may come to hold another entry (one above it removed, a reset): what was typed was for the last
+    const [shownName, setShownName] = useState(name);
+    if (shownName !== name) {
+        setShownName(name);
+        setDraft(name);
+    }
+    const problem = nameProblem(draft, others);
+    return (_jsxs("div", { className: "forgebook-value-record__name", children: [_jsx("input", { type: "text", "aria-label": EDITOR_STRINGS.fieldName(label), "aria-invalid": problem !== undefined, "aria-describedby": problem === undefined ? undefined : problemId, value: draft, onChange: (event) => {
+                    const next = event.target.value;
+                    setDraft(next);
+                    if (nameProblem(next, others) === undefined)
+                        onRename(next);
+                }, onBlur: () => {
+                    if (problem !== undefined)
+                        setDraft(name);
+                } }), problem === undefined ? null : (_jsx("p", { id: problemId, className: "forgebook-value-note", "data-tone": "problem", role: "alert", children: problem }))] }));
+};
+/**
+ * A record's editor.
+ *
+ * @param props - the field's props, and how to draw a value.
+ */
+export const RecordEditor = ({ shape, value, label, namedValues, depth, onChange, drawField }) => {
+    const current = value !== undefined && isArgObject(value) ? value : {};
+    const entries = Object.entries(current);
+    const names = entries.map(([name]) => name);
+    const start = startValueOf(shape.of, namedValues);
+    const newName = () => {
+        const base = EDITOR_STRINGS.newField;
+        let count = names.length + 1;
+        while (names.includes(`${base}${count}`))
+            count += 1;
+        return `${base}${count}`;
+    };
+    // renamed in place, so the entries keep their order and the field keeps its focus
+    const rename = (from, to) => onChange(Object.fromEntries(entries.map(([name, each]) => [name === from ? to : name, each])));
+    const change = (name, next) => {
+        if (next !== undefined)
+            onChange({ ...current, [name]: next });
+    };
+    return (_jsxs("div", { className: "forgebook-value-list", children: [entries.length === 0 ? _jsx("p", { className: "forgebook-value-note", children: EDITOR_STRINGS.emptyList }) : null, entries.map(([name, each], index) => {
+                const entryLabel = EDITOR_STRINGS.itemName(label, index + 1);
+                return (_jsxs("div", { className: "forgebook-value-list__item", children: [_jsxs("div", { className: "forgebook-value-record__entry", children: [_jsx(EntryName, { name: name, others: names.filter((other) => other !== name), label: entryLabel, onRename: (to) => rename(name, to) }), _jsx("div", { className: "forgebook-value-list__field", children: drawField({
+                                        shape: shape.of,
+                                        value: each,
+                                        label: EDITOR_STRINGS.fieldValue(entryLabel, name),
+                                        namedValues,
+                                        depth: depth + 1,
+                                        onChange: (next) => change(name, next)
+                                    }) })] }), _jsx("div", { className: "forgebook-value-list__buttons", children: _jsx("button", { type: "button", className: "forgebook-prop__action", "aria-label": EDITOR_STRINGS.removeItem(entryLabel), title: EDITOR_STRINGS.removeItem(entryLabel), onClick: () => {
+                                    const { [name]: _removed, ...rest } = current;
+                                    onChange(rest);
+                                }, children: _jsx(Icon, { name: "close", size: 12 }) }) })] }, index));
+            }), _jsxs("button", { type: "button", className: "forgebook-text-button forgebook-value-add", disabled: start === undefined, onClick: () => {
+                    if (start !== undefined)
+                        onChange({ ...current, [newName()]: start });
+                }, children: [_jsx(Icon, { name: "plus", size: 12 }), EDITOR_STRINGS.addItem(label)] })] }));
+};

package/dist/src/shell/valueEditors/SearchSelect.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A list to search: a text field that narrows its options, walked with the arrow keys, as a combobox for screen readers.
+ * For many options, and for the source's named values and the catalogue's tokens, where a name is what a reader knows.
+ *
+ * @remarks
+ * The list opens in the flow rather than over the panel: the panel scrolls, and would cut an overlay at its edge.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+/** One option of the list. */
+export type SearchOption = {
+    /** What choosing it gives. */
+    readonly value: string;
+    /** What it is called. */
+    readonly label: string;
+    /** What it holds, beside its name; none by default. */
+    readonly hint?: string;
+    /** A colour to show beside its name; none by default. */
+    readonly swatch?: string;
+};
+/** The list's props. */
+export type SearchSelectProps = {
+    /** The field's name. */
+    readonly label: string;
+    /** The element that describes it. */
+    readonly describedBy?: string | undefined;
+    /** The options. */
+    readonly options: readonly SearchOption[];
+    /** The chosen value; none when nothing is. */
+    readonly value: string | undefined;
+    /** Whether the list offers "no value"; `true` by default. */
+    readonly canClear?: boolean;
+    /** Called with the chosen value; none for "no value". */
+    readonly onChange: (value: string | undefined) => void;
+};
+/**
+ * A list to search.
+ *
+ * @param props - the options and the chosen value.
+ */
+export declare const SearchSelect: ({ label, describedBy, options, value, canClear, onChange }: SearchSelectProps) => ReactNode;