forgebook 0.3.3 → 0.4.1

package/dist/src/shell/useSidebarOverlay.d.ts

@@ -1,6 +1,7 @@
 /**
  * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
  * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ * Beside the page, on a wide window, the focus only follows the button it stood on, which goes away with the press.
  *
  * @module
  */
@@ -26,7 +27,7 @@ export type SidebarOverlayState = {
     readonly onClose: () => void;
 };
 /**
- * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ * Wires a sidebar lying over the page, and the focus of one beside it on a wide window.
  *
  * @param state - the sidebar's state.
  * @returns whether it lies over the page, and the references to give the sidebar and its buttons.

package/dist/src/shell/useSidebarOverlay.js

@@ -1,12 +1,13 @@
 /**
  * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
  * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ * Beside the page, on a wide window, the focus only follows the button it stood on, which goes away with the press.
  *
  * @module
  */
 import { useEffect, useRef } from "react";
 /**
- * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ * Wires a sidebar lying over the page, and the focus of one beside it on a wide window.
  *
  * @param state - the sidebar's state.
  * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
@@ -32,20 +33,27 @@ export const useSidebarOverlay = ({ isOverlay, isOpen, onClose }) => {
         return () => document.removeEventListener("keydown", closeOnEscape);
     }, [isOver, onClose]);
     const wasOver = useRef(false);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: also looked at when the window crosses the width, and never when a wide window's sidebar is hidden, which leaves the focus alone
+    const wasOpen = useRef(isOpen);
+    // also looked at when the window crosses the width
     useEffect(() => {
         const focused = document.activeElement;
         const isFocusInSidebar = sidebarRef.current?.contains(focused) === true;
+        const isFocusNowhere = focused === document.body || focused === null;
         // the platform's search key has already put the focus on the search field
         if (isOver && !isFocusInSidebar)
             hideButtonRef.current?.focus({ preventScroll: true });
+        // shown beside the page, the sidebar took away the button that showed it, and Tab would start over from the top
+        if (isOpen && !wasOpen.current && !isOverlay && isFocusNowhere) {
+            hideButtonRef.current?.focus({ preventScroll: true });
+        }
         // the sidebar went away with the focus in it, closed or by the window crossing the width; one still shown keeps the
         // focus, and a search's result that has already taken it to what it found keeps it too
-        const isFocusLost = isFocusInSidebar || (wasOver.current && (focused === document.body || focused === null));
+        const isFocusLost = isFocusInSidebar || (wasOver.current && isFocusNowhere);
         if (!isOver && sidebarRef.current?.inert === true && isFocusLost) {
             showButtonRef.current?.focus({ preventScroll: true });
         }
         wasOver.current = isOver;
-    }, [isOver, isOverlay]);
+        wasOpen.current = isOpen;
+    }, [isOver, isOverlay, isOpen]);
     return { isOver, sidebarRef, hideButtonRef, showButtonRef };
 };

package/dist/src/shell/useStoryCode.d.ts

@@ -1,5 +1,6 @@
 /**
- * A story file's code for the Code card: each story's `render` as written, loaded from the source's `code`.
+ * A story file's code for the Code card: each story's `render`, or the args it writes as code, as written, loaded from
+ * the source's `code`.
  *
  * @module
  */

package/dist/src/shell/useStoryCode.js

@@ -1,12 +1,17 @@
 import { useLoaded } from "./useLoaded.js";
-/** Whether a value is one story's code: its text and its HTML. */
-const isStoryCode = (value) => typeof value === "object" &&
+/** Whether a value is a record of texts, as a story's written args are. */
+const isTexts = (value) => typeof value === "object" &&
     value !== null &&
-    "text" in value &&
-    typeof value.text === "string" &&
-    "html" in value &&
-    typeof value.html === "string";
-/** Whether the plugin's answer is a file's code: each story's text and HTML, by export name. */
+    Object.values(value).every((each) => typeof each === "string");
+/** Whether a value is one story's code: its render's text and HTML, or the args it writes as code. */
+const isStoryCode = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if ("args" in value)
+        return isTexts(value.args);
+    return ("text" in value && typeof value.text === "string" && "html" in value && typeof value.html === "string");
+};
+/** Whether the plugin's answer is a file's code: each story's, by export name. */
 const isStoryFileCode = (value) => typeof value === "object" &&
     value !== null &&
     !("error" in value) &&

package/dist/src/shell/useToolbarLayout.d.ts

@@ -5,7 +5,7 @@
  *
  * @module
  */
-import { type ControlKeys } from "../controlKeys.ts";
+import { type ControlKeys, type ReaderKeys } from "../controlKeys.ts";
 import { type PlacedControl } from "../toolbarLayout.ts";
 /** The arrangement and what changes it. */
 export type ToolbarLayout = {
@@ -34,5 +34,9 @@ export type ToolbarLayout = {
      */
     readonly setKey: (id: string, key: string | null) => string | undefined;
 };
+/** The person's keys a stored text holds; none for anything else. */
+export declare const readKeys: (stored: string | null) => ReaderKeys;
+/** The text the person's keys are stored as; empty for none. */
+export declare const keysText: (keys: ReaderKeys) => string;
 /** The person's arrangement of the toolbar. */
 export declare const useToolbarLayout: () => ToolbarLayout;

package/dist/src/shell/useToolbarLayout.js

@@ -10,7 +10,7 @@ import { arrangementOf, arrangementText, placedControls, readArrangement, withHi
 import { useCatalogue } from "./catalogueContext.js";
 import { useStored } from "./useStored.js";
 /** The person's keys a stored text holds; none for anything else. */
-const readKeys = (stored) => {
+export const readKeys = (stored) => {
     if (stored === null || stored === "")
         return {};
     try {
@@ -24,7 +24,7 @@ const readKeys = (stored) => {
     }
 };
 /** The text the person's keys are stored as; empty for none. */
-const keysText = (keys) => (Object.keys(keys).length === 0 ? "" : JSON.stringify(keys));
+export const keysText = (keys) => Object.keys(keys).length === 0 ? "" : JSON.stringify(keys);
 /** The person's arrangement of the toolbar. */
 export const useToolbarLayout = () => {
     const catalogue = useCatalogue();

package/dist/src/shell/useWorstCase.d.ts

@@ -11,7 +11,9 @@
  */
 import { type RefObject } from "react";
 import type { PanelProp } from "../argTypes.ts";
-import type { PanelArgs } from "../messages.ts";
+import type { ArgValue, PanelArgs } from "../messages.ts";
+import type { NamedValues } from "../namedValues.ts";
+import type { ValueShape } from "../valueShape.ts";
 import { type WorstCaseState } from "./worstArgs.ts";
 /** What the hook reads. */
 export type WorstCaseInput = {
@@ -25,6 +27,10 @@ export type WorstCaseInput = {
     readonly values: PanelArgs;
     /** The panel's own values. */
     readonly panelArgs: PanelArgs;
+    /** The source's named values, for a required part only they can fill. */
+    readonly namedValues: NamedValues | undefined;
+    /** Gives a prop with a shape its worst value, once its module loaded. */
+    readonly worstOfShape: ((shape: ValueShape, namedValues: NamedValues) => ArgValue | undefined) | undefined;
     /** Sets the panel's values. */
     readonly onPanelArgsChange: (args: PanelArgs) => void;
 };
@@ -42,4 +48,4 @@ export type WorstCase = {
  *
  * @param input - the frames, the story, its settable props and its values.
  */
-export declare const useWorstCase: ({ storyRef, storyId, settable, values, panelArgs, onPanelArgsChange }: WorstCaseInput) => WorstCase;
+export declare const useWorstCase: ({ storyRef, storyId, settable, values, panelArgs, namedValues, worstOfShape, onPanelArgsChange }: WorstCaseInput) => WorstCase;

package/dist/src/shell/useWorstCase.js

@@ -24,8 +24,8 @@ const mostOf = (frames) => frames === undefined || frames.size === 0 ? undefined
  *
  * @param input - the frames, the story, its settable props and its values.
  */
-export const useWorstCase = ({ storyRef, storyId, settable, values, panelArgs, onPanelArgsChange }) => {
-    const args = useMemo(() => worstArgs(settable), [settable]);
+export const useWorstCase = ({ storyRef, storyId, settable, values, panelArgs, namedValues, worstOfShape, onPanelArgsChange }) => {
+    const args = useMemo(() => worstArgs(settable, namedValues, worstOfShape), [settable, namedValues, worstOfShape]);
     const isOn = isWorstCase(args, values);
     // each frame's count, by story then by frame: the compare view draws a story in several
     const [counts, setCounts] = useState(new Map());

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;