forgebook 0.3.3 → 0.4.1

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

@@ -0,0 +1,44 @@
+/**
+ * A pinned control's small menu, opened by a right-click or the keyboard's menu key: take it off the toolbar, hide it in
+ * the View menu or show it there again.
+ *
+ * @remarks
+ * Loaded the first time one opens (`PinnedControl.tsx`): the control is on the first screen, and few readers ever ask for
+ * its menu.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { ToolbarLayout } from "./useToolbarLayout.ts";
+/** Where the menu opens, in the window's px. */
+export type MenuPoint = {
+    /** From the window's left. */
+    readonly x: number;
+    /** From the window's top. */
+    readonly y: number;
+};
+/** The menu's props. */
+export type ControlMenuProps = {
+    /** The control's id. */
+    readonly id: string;
+    /**
+     * The control's name. Given rather than read here: a module the page also imports would be taken into a chunk of its
+     * own, and the first load would grow by more than this menu saves.
+     */
+    readonly label: string;
+    /** Whether it takes no row in the View menu. */
+    readonly isHidden: boolean;
+    /** Where the menu opens. */
+    readonly at: MenuPoint;
+    /** The toolbar's arrangement, which its choices change. */
+    readonly layout: ToolbarLayout;
+    /** Called when it closes. */
+    readonly onClose: () => void;
+};
+/**
+ * The control's menu: its two choices as menu items, the first focused, the arrow keys between them; closed by a
+ * choice, a press outside or Escape, the focus going back where it was.
+ *
+ * @param props - the control, where the menu opens, what its choices do, and what closing it does.
+ */
+export declare const ControlMenu: ({ id, label, isHidden, at, layout, onClose }: ControlMenuProps) => ReactNode;

package/dist/src/shell/PinnedControlMenu.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A pinned control's small menu, opened by a right-click or the keyboard's menu key: take it off the toolbar, hide it in
+ * the View menu or show it there again.
+ *
+ * @remarks
+ * Loaded the first time one opens (`PinnedControl.tsx`): the control is on the first screen, and few readers ever ask for
+ * its menu.
+ *
+ * @module
+ */
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { LATER_STRINGS } from "./laterStrings.js";
+/** The room the menu keeps from the window's edges, in CSS px. */
+const EDGE_PX = 8;
+/**
+ * The control's menu: its two choices as menu items, the first focused, the arrow keys between them; closed by a
+ * choice, a press outside or Escape, the focus going back where it was.
+ *
+ * @param props - the control, where the menu opens, what its choices do, and what closing it does.
+ */
+export const ControlMenu = ({ id, label, isHidden, at, layout, onClose }) => {
+    const menuRef = useRef(null);
+    // the menu stays inside the window: opened near its right or lower edge, it moves back by what would run past
+    useLayoutEffect(() => {
+        const menu = menuRef.current;
+        if (menu === null)
+            return;
+        const box = menu.getBoundingClientRect();
+        menu.style.left = `${Math.max(EDGE_PX, Math.min(at.x, window.innerWidth - box.width - EDGE_PX))}px`;
+        menu.style.top = `${Math.max(EDGE_PX, Math.min(at.y, window.innerHeight - box.height - EDGE_PX))}px`;
+    }, [at]);
+    useEffect(() => {
+        const before = document.activeElement;
+        menuRef.current?.querySelector("[role=menuitem]")?.focus();
+        const close = (event) => {
+            const isOutside = event instanceof PointerEvent &&
+                !(event.target instanceof Node && menuRef.current?.contains(event.target));
+            const isEscape = event instanceof KeyboardEvent && event.key === "Escape";
+            if (!isOutside && !isEscape)
+                return;
+            onClose();
+            if (isEscape && before instanceof HTMLElement)
+                before.focus();
+        };
+        document.addEventListener("pointerdown", close);
+        document.addEventListener("keydown", close);
+        return () => {
+            document.removeEventListener("pointerdown", close);
+            document.removeEventListener("keydown", close);
+        };
+    }, [onClose]);
+    const step = (event) => {
+        if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
+            return;
+        event.preventDefault();
+        const items = [...(menuRef.current?.querySelectorAll("[role=menuitem]") ?? [])];
+        const focused = document.activeElement;
+        const index = focused instanceof HTMLButtonElement ? items.indexOf(focused) : -1;
+        const next = (index + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+        items[next]?.focus();
+    };
+    const unpin = () => {
+        onClose();
+        layout.pin(id, false);
+    };
+    const toggleHidden = () => {
+        onClose();
+        layout.hide(id, !isHidden);
+    };
+    return (_jsxs("div", { ref: menuRef, className: "forgebook-context-menu", role: "menu", "aria-label": LATER_STRINGS.controlMenu(label), style: { left: at.x, top: at.y }, onKeyDown: step, children: [_jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: unpin, children: LATER_STRINGS.unpinControl }), _jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: toggleHidden, children: isHidden ? LATER_STRINGS.showInView : LATER_STRINGS.hideInView })] }));
+};

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

@@ -7,10 +7,12 @@
 import type { ReactNode } from "react";
 import type { PanelProp } from "../argTypes.ts";
 import { type ArgValue } from "../messages.ts";
-/** Called with a changed value; `undefined` removes the panel's value. */
+/** Called with a changed value; `undefined` removes the panel's value, `UNSET_ARG` leaves the prop with none. */
 export type OnValueChange = (name: string, value: ArgValue | undefined) => void;
 /** A value as a text field shows it: texts and numbers as they are, anything else empty. */
 export declare const textOf: (value: ArgValue | undefined) => string;
+/** The most options a native list holds before the panel offers a search among them. */
+export declare const MOST_PLAIN_OPTIONS = 12;
 /**
  * A choice's control: buttons side by side for `radio` or a few short values, a list for `select` or otherwise, and
  * a multiple choice for `check` and `multi-select`.

package/dist/src/shell/PropFields.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { isChoiceList } from "../messages.js";
+import { isChoiceList, UNSET_ARG } from "../messages.js";
 import { Segmented } from "./Segmented.js";
 import { STRINGS } from "./strings.js";
 /** A value as a text field shows it: texts and numbers as they are, anything else empty. */
@@ -16,8 +16,10 @@ const dateFieldOf = (value) => {
     const local = new Date(value - date.getTimezoneOffset() * 60_000);
     return local.toISOString().slice(0, 16);
 };
-/** The value of the choice that leaves a prop to the story: no choice of a component is an empty text. */
+/** The value of the choice that leaves a prop without one: no choice of a component is an empty text. */
 const UNSET = "";
+/** The most options a native list holds before the panel offers a search among them. */
+export const MOST_PLAIN_OPTIONS = 12;
 /** The most choices shown as buttons, and the longest label; past either, a list. */
 const FEW_CHOICES = { count: 4, length: 10 };
 /** Whether a choice's values fit side by side as buttons. */
@@ -52,11 +54,11 @@ export const ChoiceControl = ({ prop, value, descriptionId, onValueChange }) =>
         return (_jsx(Segmented, { label: prop.label ?? prop.name, options: [
                 { value: UNSET, label: unsetLabel },
                 ...choices.map((choice) => ({ value: choice, label: choiceLabel(prop, choice) }))
-            ], value: choiceOf(value) ?? UNSET, onValueChange: (chosen) => onValueChange(prop.name, chosen === UNSET ? undefined : chosen) }));
+            ], value: choiceOf(value) ?? UNSET, onValueChange: (chosen) => onValueChange(prop.name, chosen === UNSET ? UNSET_ARG : chosen) }));
     }
     return (_jsxs("select", { "aria-label": prop.label ?? prop.name, "aria-describedby": descriptionId, value: textOf(value), onChange: (event) => {
             const chosen = choices.find((choice) => String(choice) === event.target.value);
-            onValueChange(prop.name, chosen);
+            onValueChange(prop.name, chosen ?? UNSET_ARG);
         }, children: [_jsx("option", { value: "", children: unsetLabel }), choices.map((choice) => (_jsx("option", { value: String(choice), children: choiceLabel(prop, choice) }, String(choice))))] }));
 };
 /** A field for a number, a range or a date, as its `argTypes` say; a date's value is ms since the Unix epoch. */
@@ -66,7 +68,7 @@ export const NumberField = ({ prop, value, descriptionId, onValueChange }) => {
         return (_jsx("input", { type: "datetime-local", "aria-label": label, "aria-describedby": descriptionId, value: dateFieldOf(value), onChange: (event) => {
                 const time = event.target.valueAsNumber;
                 // the field's own value is in UTC: read back in the browser's time zone, as it was shown
-                const local = Number.isNaN(time) ? undefined : time + new Date(time).getTimezoneOffset() * 60_000;
+                const local = Number.isNaN(time) ? UNSET_ARG : time + new Date(time).getTimezoneOffset() * 60_000;
                 onValueChange(prop.name, local);
             } }));
     }
@@ -75,6 +77,7 @@ export const NumberField = ({ prop, value, descriptionId, onValueChange }) => {
         ...(prop.max === undefined ? {} : { max: prop.max }),
         ...(prop.step === undefined ? {} : { step: prop.step })
     };
-    const change = (text) => onValueChange(prop.name, text === "" ? undefined : Number(text));
+    // a number has no empty value, so a cleared field leaves the prop with none
+    const change = (text) => onValueChange(prop.name, text === "" ? UNSET_ARG : Number(text));
     return (_jsxs(_Fragment, { children: [prop.control === "range" ? (_jsx("input", { type: "range", "aria-label": label, "aria-describedby": descriptionId, ...bounds, value: typeof value === "number" ? value : (prop.min ?? 0), onChange: (event) => change(event.target.value) })) : null, _jsx("input", { type: "number", "aria-label": prop.control === "range" ? STRINGS.rangeValue(label) : label, "aria-describedby": descriptionId, ...bounds, value: textOf(value), onChange: (event) => change(event.target.value) })] }));
 };

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

@@ -1,12 +1,14 @@
 /**
  * One prop of the Props tab as it is drawn: its head (its name, whether it is required, its group in the "Required"
- * group, its type), then its control, its toggle, or its description for reading.
+ * group, its type), then its control, or its description for reading.
  *
  * @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";
 /** A prop the story gives a text by its key (`storyText("key")`): the key, and whether the panel wrote over it. */
 export type TextArgNote = {
@@ -15,26 +17,35 @@ export type TextArgNote = {
     /** Whether the panel holds a value of its own for the prop. */
     readonly isChanged: boolean;
 };
-/** One adjustable prop with its control. */
-export declare const PropControl: ({ prop, showsGroup, value, named, textArg, onValueChange }: {
+/** What a field says of its value, and the two ways back from it. */
+export type FieldState = {
+    /** The value shown: the story's own, or the panel's over it. */
+    readonly value: ArgValue | undefined;
+    /** The panel's own value; none when the story's own is shown. */
+    readonly panelValue: ArgValue | undefined;
+    /** Called with a changed value. */
+    readonly onValueChange: OnValueChange;
+};
+/** One adjustable prop with its control: a boolean's is a switch. */
+export declare const PropControl: ({ prop, showsGroup, value, panelValue, named, namedValues, loadTokens, argControls, textArg, onValueChange }: {
     readonly prop: PanelProp;
     /** Whether it names its group: in the "Required" group. */
     readonly showsGroup: boolean;
     readonly value: ArgValue | undefined;
+    /** The panel's own value; none when the story's own is shown. */
+    readonly panelValue: ArgValue | undefined;
     /** The values the source names for the prop's type, when it names some. */
     readonly named: Readonly<Record<string, unknown>> | undefined;
+    /** The source's named values, for the parts of a value they fill. */
+    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;
     /** Where the story's text for the prop comes from, when the story names one by its key. */
     readonly textArg: TextArgNote | undefined;
     readonly onValueChange: OnValueChange;
 }) => ReactNode;
-/** A toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
-export declare const Toggle: ({ prop, showsGroup, value, onValueChange }: {
-    readonly prop: PanelProp;
-    /** Whether it names its group: in the "Required" group. */
-    readonly showsGroup: boolean;
-    readonly value: ArgValue | undefined;
-    readonly onValueChange: OnValueChange;
-}) => ReactNode;
 /** A prop the panel cannot set: its name, its type and its description, for reading; its group when asked. */
 export declare const ReadOnlyProp: ({ prop, showsGroup }: {
     readonly prop: PanelProp;

package/dist/src/shell/PropRows.js

@@ -1,25 +1,48 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
  * One prop of the Props tab as it is drawn: its head (its name, whether it is required, its group in the "Required"
- * group, its type), then its control, its toggle, or its description for reading.
+ * group, its type), then its control, or its description for reading.
  *
  * @module
  */
 import { useId } from "react";
 import { isColorProp } from "../argTypes.js";
-import { isNamedArg } from "../messages.js";
-import { ChoiceControl, NumberField, textOf } from "./PropFields.js";
+import { isUnsetArg, UNSET_ARG } from "../messages.js";
+import { Icon } from "./icons.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
+import { ChoiceControl, MOST_PLAIN_OPTIONS, NumberField, textOf } from "./PropFields.js";
+import { Switch } from "./Switch.js";
 import { STRINGS } from "./strings.js";
+/** The editors a catalogue's plain props never load: nested fields, a searchable list, the tokens, the files. */
+const PROP_EDITOR = lazyModule(() => import("./valueEditors/PropEditor.js").then((module) => module.PropEditor));
 /** A CSS colour as the colour picker takes it (`#rrggbb`), or black when the value is not one. */
 const pickerColor = (value) => typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
 /** A prop's group, beside its name in the "Required" group, which gathers props of every group. */
 const GroupName = ({ prop, showsGroup }) => showsGroup && prop.group !== undefined ? _jsx("span", { className: "forgebook-prop__group", children: prop.group }) : null;
 /**
- * A prop's name, whether it is required, its group when asked, and its type (whole in the tooltip when it is cut).
+ * The way back from a prop's value: to no value at all, and to the story's own, each offered only when it changes
+ * something.
  *
- * @param props - the prop, and whether it names its group.
+ * @param props - the prop and its state.
  */
-const PropHead = ({ prop, showsGroup }) => (_jsxs("div", { className: "forgebook-prop__head", children: [_jsxs("code", { className: "forgebook-prop__name", children: [prop.label ?? prop.name, prop.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsx(GroupName, { prop: prop, showsGroup: showsGroup }), _jsx("code", { className: "forgebook-prop__type", title: prop.type, children: prop.type })] }));
+const FieldActions = ({ prop, value, panelValue, onValueChange }) => {
+    const label = prop.label ?? prop.name;
+    const action = (text, icon, next) => (_jsx("button", { type: "button", className: "forgebook-prop__action", "aria-label": text, title: text, onClick: () => onValueChange(prop.name, next), children: _jsx(Icon, { name: icon, size: 12 }) }));
+    return (_jsxs("span", { className: "forgebook-prop__actions", children: [value === undefined ? null : action(STRINGS.unsetProp(label), "noValue", UNSET_ARG), panelValue === undefined ? null : action(STRINGS.resetProp(label), "replay", undefined)] }));
+};
+/** What a prop's value is when its field alone cannot say: no value over the story's own, or an empty text. */
+const stateNote = (state) => {
+    if (isUnsetArg(state.panelValue))
+        return STRINGS.stateUnset;
+    return state.value === "" ? STRINGS.stateEmpty : undefined;
+};
+/**
+ * A prop's name, whether it is required, its group when asked, its type (whole in the tooltip when it is cut), what its
+ * value is and the ways back from it.
+ *
+ * @param props - the prop, whether it names its group, and its state.
+ */
+const PropHead = ({ prop, showsGroup, state }) => (_jsxs("div", { className: "forgebook-prop__head", children: [_jsxs("code", { className: "forgebook-prop__name", children: [prop.label ?? prop.name, prop.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsx(GroupName, { prop: prop, showsGroup: showsGroup }), _jsx("code", { className: "forgebook-prop__type", title: prop.type, children: prop.type }), state === undefined ? null : (_jsxs(_Fragment, { children: [stateNote(state) === undefined ? null : (_jsx("span", { className: "forgebook-prop__state", children: stateNote(state) })), _jsx(FieldActions, { prop: prop, ...state })] }))] }));
 /** A prop's description and default, under its control. */
 const PropNote = ({ id, prop }) => prop.description === "" && prop.defaultValue === undefined ? null : (_jsxs("p", { id: id, className: "forgebook-prop__description", children: [prop.description, prop.defaultValue === undefined ? null : (_jsxs(_Fragment, { children: [prop.description === "" ? null : " ", STRINGS.defaultIs, " ", _jsx("code", { children: prop.defaultValue })] }))] }));
 /**
@@ -29,32 +52,47 @@ const PropNote = ({ id, prop }) => prop.description === "" && prop.defaultValue
  * @param props - the note, the prop's name and the value setter.
  */
 const TextArgLine = ({ note, name, onValueChange }) => (_jsxs("p", { className: "forgebook-prop__text-arg", children: [STRINGS.fromTexts, " ", _jsx("code", { children: note.key }), note.isChanged ? (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => onValueChange(name, undefined), children: STRINGS.backToText })) : null] }));
-/** One adjustable prop with its control. */
-export const PropControl = ({ prop, showsGroup, value, named, textArg, onValueChange }) => {
+/** Whether a prop is drawn by the editors that load on use, not by the first screen's fields. */
+const usesEditors = (prop, named) => named !== undefined ||
+    prop.shape !== undefined ||
+    prop.customControl !== undefined ||
+    prop.control === "token" ||
+    prop.control === "file" ||
+    (prop.kind === "choice" &&
+        (prop.control === undefined || prop.control === "select") &&
+        (prop.choices?.length ?? 0) > MOST_PLAIN_OPTIONS);
+/** One adjustable prop with its control: a boolean's is a switch. */
+export const PropControl = ({ prop, showsGroup, value, panelValue, named, namedValues, loadTokens, argControls, textArg, onValueChange }) => {
     // the description is shown under the control and named by it, so the control's name is the prop alone
     const descriptionId = useId();
     const label = prop.label ?? prop.name;
-    if (named !== undefined) {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsxs("select", { "aria-label": label, "aria-describedby": descriptionId, value: isNamedArg(value) ? value.named : "", onChange: (event) => {
-                        const chosen = event.target.value;
-                        onValueChange(prop.name, chosen === "" ? undefined : { of: prop.type, named: chosen });
-                    }, children: [_jsx("option", { value: "", children: STRINGS.unset }), Object.keys(named).map((name) => (_jsx("option", { value: name, children: name }, name)))] }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+    const state = { value, panelValue, onValueChange };
+    if (prop.kind === "toggle") {
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup, state: state }), _jsx("div", { className: "forgebook-prop__field", children: _jsx(Switch, { label: label, isOn: value === true, describedBy: descriptionId, onChange: (isOn) => onValueChange(prop.name, isOn) }) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+    }
+    if (usesEditors(prop, named)) {
+        const editorProps = {
+            prop,
+            value,
+            descriptionId,
+            namedValues,
+            loadTokens,
+            argControls,
+            onValueChange
+        };
+        const isWide = (prop.shape !== undefined || prop.customControl !== undefined) && named === undefined;
+        return (_jsxs("div", { className: "forgebook-prop", "data-wide": isWide || undefined, children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup, state: state }), _jsx(LazyView, { module: PROP_EDITOR, props: editorProps, loading: null, failed: (message) => (_jsx("p", { className: "forgebook-prop__description", role: "alert", children: message })) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
     }
     if (prop.kind === "choice") {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx(ChoiceControl, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup, state: state }), _jsx(ChoiceControl, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
     }
     if (prop.kind === "number") {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx("div", { className: "forgebook-prop__field", children: _jsx(NumberField, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup, state: state }), _jsx("div", { className: "forgebook-prop__field", children: _jsx(NumberField, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
     }
-    return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsxs("div", { className: "forgebook-prop__field", children: [_jsx("input", { type: "text", "aria-label": label, "aria-describedby": descriptionId, value: textOf(value), onChange: (event) => {
-                            const text = event.target.value;
-                            onValueChange(prop.name, text === "" ? undefined : text);
-                        } }), isColorProp(prop) ? (_jsx("input", { type: "color", className: "forgebook-prop__color", "aria-label": STRINGS.pickColor(label), value: pickerColor(value), onChange: (event) => onValueChange(prop.name, event.target.value) })) : null] }), textArg === undefined ? null : (_jsx(TextArgLine, { note: textArg, name: prop.name, onValueChange: onValueChange })), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
-};
-/** A toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
-export const Toggle = ({ prop, showsGroup, value, onValueChange }) => {
-    const descriptionId = useId();
-    return (_jsxs("label", { className: "forgebook-toggle", title: prop.description, children: [_jsx("input", { type: "checkbox", "aria-label": prop.label ?? prop.name, checked: value === true, "aria-describedby": descriptionId, onChange: (event) => onValueChange(prop.name, event.target.checked) }), _jsx("code", { children: prop.label ?? prop.name }), _jsx(GroupName, { prop: prop, showsGroup: showsGroup }), _jsx("span", { id: descriptionId, className: "forgebook-visually-hidden", children: prop.description })] }));
+    // a text with a line break keeps it: an `<input>` would drop it, from the field and from the link
+    const isMultiline = prop.control === "textarea" || (typeof value === "string" && value.includes("\n"));
+    const TextControl = isMultiline ? "textarea" : "input";
+    return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup, state: state }), _jsxs("div", { className: "forgebook-prop__field", children: [_jsx(TextControl, { "aria-label": label, "aria-describedby": descriptionId, ...(isMultiline ? { rows: 4 } : { type: "text" }), value: textOf(value), onChange: (event) => onValueChange(prop.name, event.target.value) }), isColorProp(prop) ? (_jsx("input", { type: "color", className: "forgebook-prop__color", "aria-label": STRINGS.pickColor(label), value: pickerColor(value), onChange: (event) => onValueChange(prop.name, event.target.value) })) : null] }), textArg === undefined ? null : (_jsx(TextArgLine, { note: textArg, name: prop.name, onValueChange: onValueChange })), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
 };
 /** A prop the panel cannot set: its name, its type and its description, for reading; its group when asked. */
 export const ReadOnlyProp = ({ prop, showsGroup }) => (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx("p", { className: "forgebook-prop__description", children: prop.description })] }));

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

@@ -1,16 +1,16 @@
 /**
- * The panel's Props tab: the props the story lets the panel set, grouped by control (choices, text and numbers,
- * toggles), each with its description and default, then the props it cannot set. A story of fixed examples sets none:
+ * The panel's Props tab: the props the story lets the panel set, in the order the source declares them whatever their
+ * control, each with its description and default, then the props it cannot set. A story of fixed examples sets none:
  * the tab says so and lists every prop for reading. The props come with the story's `argTypes` laid over them
  * (`argTypes.ts`): a control they name (a list, buttons, checkboxes, a range, a colour, a date) wins over the one
  * the prop's type gives.
  *
  * @remarks
  * Props whose TSDoc names a group (`@group Selection`) are listed under its name after the others, as the API reference
- * lists them (`propGroups.ts`): each group's controls, its toggles, then its props the panel cannot set. Each starts
+ * lists them (`propGroups.ts`): each group's controls, then its props the panel cannot set. Each starts
  * open, and a reader may fold it away. A component whose props name no group shows the tab as it always was.
  *
- * The required props come first among each kind of control and in each group, or in one "Required" group before the
+ * The required props come first among the others and in each group, or in one "Required" group before the
  * others, each naming its group, as the story, its component, the catalogue and the reader's switch at the top of the
  * tab say (`useRequiredFirst.ts`).
  *
@@ -22,6 +22,7 @@ import type { ReactNode } from "react";
 import { type PanelProp } from "../argTypes.ts";
 import type { ArgValue, PanelArgs } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
+import type { ArgControlLoaders } from "./customControls.ts";
 import { type TextArgNote } from "./PropRows.tsx";
 import type { WorstCaseState } from "./worstArgs.ts";
 /** The tab's props. */
@@ -30,6 +31,12 @@ export type PropsTabProps = {
     readonly props: readonly PanelProp[];
     /** The values shown: the story's args with the panel's changes. */
     readonly values: PanelArgs;
+    /** The panel's own values, for what can go back to the story's. */
+    readonly panelArgs: PanelArgs;
+    /** 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;
     /** The props the story lets the panel set. */
     readonly controls: StoryControlsSetting;
     /** Called with a changed value; `undefined` removes the panel's value. */
@@ -58,4 +65,4 @@ export type PropsTabProps = {
  *
  * @param props - the props, the values, which props the story lets the panel set, and the setters.
  */
-export declare const PropsTab: ({ props, values, controls, onValueChange, onReset, worstCase, namedValues, textArgs, componentGroups, requiredFirst }: PropsTabProps) => ReactNode;
+export declare const PropsTab: ({ props, values, panelArgs, loadTokens, argControls, controls, onValueChange, onReset, worstCase, namedValues, textArgs, componentGroups, requiredFirst }: PropsTabProps) => ReactNode;

package/dist/src/shell/PropsTab.js

@@ -3,7 +3,7 @@ import { isNamedProp, settableProps } from "../argTypes.js";
 import { canOrderRequired, laidOutProps, propGroupOrder } from "../propGroups.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
-import { PropControl, ReadOnlyProp, Toggle } from "./PropRows.js";
+import { PropControl, ReadOnlyProp } from "./PropRows.js";
 import { RequiredFirstSwitch } from "./RequiredFirstSwitch.js";
 import { STRINGS } from "./strings.js";
 import { useRequiredFirst } from "./useRequiredFirst.js";
@@ -12,16 +12,15 @@ const NO_TEXT_ARGS = {};
 /** No group named first. */
 const NO_GROUPS = [];
 /**
- * A group the props' TSDoc names, under its name: its controls in the order of the props, its toggles, then the props
- * the panel cannot set. The "Required" group is drawn as one, each of its props naming its own group.
+ * A group the props' TSDoc names, under its name: its controls in the order of the props, then the props the panel
+ * cannot set. The "Required" group is drawn as one, each of its props naming its own group.
  *
  * @param props - the group's name and props, how each prop is drawn, and whether it is the "Required" group.
  */
-const NamedGroup = ({ name, props, isSettable, control, toggle, isRequired = false }) => {
-    const controls = props.filter((prop) => isSettable(prop) && prop.kind !== "toggle");
-    const toggles = props.filter((prop) => isSettable(prop) && prop.kind === "toggle");
+const NamedGroup = ({ name, props, isSettable, field, isRequired = false }) => {
+    const settable = props.filter(isSettable);
     const others = props.filter((prop) => !isSettable(prop));
-    return (_jsx("div", { className: "forgebook-prop-group", "data-required": isRequired || undefined, children: _jsxs("details", { className: "forgebook-fold", open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary forgebook-prop-group__title", children: [_jsx(Icon, { name: "chevronRight", size: 12 }), _jsx("h3", { className: "forgebook-fold__name", children: name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(props.length) })] }), _jsxs("div", { className: "forgebook-prop-group__body", children: [controls.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: controls.map((prop) => control(prop, isRequired)) })), toggles.length === 0 ? null : (_jsx("div", { className: "forgebook-toggles", children: toggles.map((prop) => toggle(prop, isRequired)) })), others.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop, showsGroup: isRequired }, prop.name))) }))] })] }) }));
+    return (_jsx("div", { className: "forgebook-prop-group", "data-required": isRequired || undefined, children: _jsxs("details", { className: "forgebook-fold", open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary forgebook-prop-group__title", children: [_jsx(Icon, { name: "chevronRight", size: 12 }), _jsx("h3", { className: "forgebook-fold__name", children: name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(props.length) })] }), _jsxs("div", { className: "forgebook-prop-group__body", children: [settable.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: settable.map((prop) => field(prop, isRequired)) })), others.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop, showsGroup: isRequired }, prop.name))) }))] })] }) }));
 };
 /**
  * The worst case's button, and once it is on, how many elements spill (the frame outlines them).
@@ -34,7 +33,7 @@ const WorstCaseControl = ({ worstCase }) => (_jsxs(_Fragment, { children: [_jsx(
  *
  * @param props - the props, the values, which props the story lets the panel set, and the setters.
  */
-export const PropsTab = ({ props, values, controls, onValueChange, onReset, worstCase, namedValues = {}, textArgs = NO_TEXT_ARGS, componentGroups = NO_GROUPS, requiredFirst }) => {
+export const PropsTab = ({ props, values, panelArgs, loadTokens, argControls, controls, onValueChange, onReset, worstCase, namedValues = {}, textArgs = NO_TEXT_ARGS, componentGroups = NO_GROUPS, requiredFirst }) => {
     const catalogue = useCatalogue();
     const ordering = useRequiredFirst(requiredFirst);
     const isNamed = (prop) => isNamedProp(prop, namedValues);
@@ -45,20 +44,8 @@ export const PropsTab = ({ props, values, controls, onValueChange, onReset, wors
     // the props that name no group are drawn as the tab always drew them, by control, in the layout's order
     const ungrouped = propGroups.find((group) => group.name === undefined)?.props ?? [];
     const settable = ungrouped.filter(isSettable);
-    const control = (prop, showsGroup) => (_jsx(PropControl, { prop: prop, showsGroup: showsGroup, value: values[prop.name], named: isNamed(prop) ? namedValues[prop.type] : undefined, textArg: textArgs[prop.name], onValueChange: onValueChange }, prop.name));
-    const toggle = (prop, showsGroup) => (_jsx(Toggle, { prop: prop, showsGroup: showsGroup, value: values[prop.name], onValueChange: onValueChange }, prop.name));
-    const groups = [
-        {
-            title: STRINGS.propGroups.choice,
-            props: settable.filter((prop) => prop.kind === "choice" || isNamed(prop))
-        },
-        {
-            title: STRINGS.propGroups.text,
-            props: settable.filter((prop) => ["text", "number", "other"].includes(prop.kind) && !isNamed(prop))
-        }
-    ].filter((group) => group.props.length > 0);
-    const toggles = settable.filter((prop) => prop.kind === "toggle");
+    const control = (prop, showsGroup) => (_jsx(PropControl, { prop: prop, showsGroup: showsGroup, value: values[prop.name], panelValue: panelArgs[prop.name], named: isNamed(prop) ? namedValues[prop.type] : undefined, namedValues: namedValues, loadTokens: loadTokens, argControls: argControls, textArg: textArgs[prop.name], onValueChange: onValueChange }, prop.name));
     const others = ungrouped.filter((prop) => !isSettable(prop));
     const hasControls = controls === "all" || controls.length > 0;
-    return (_jsxs("div", { className: "forgebook-tab-props", children: [canOrderRequired(listed) ? (_jsx("div", { className: "forgebook-tab-head", children: _jsx(RequiredFirstSwitch, { state: ordering }) })) : null, hasControls ? null : _jsx("p", { className: "forgebook-tab-note", children: STRINGS.fixedExamples }), required.length === 0 ? null : (_jsx(NamedGroup, { name: STRINGS.required, props: required, isSettable: isSettable, control: control, toggle: toggle, isRequired: true })), groups.map((group) => (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: group.title }), _jsx("div", { className: "forgebook-prop-grid", children: group.props.map((prop) => control(prop, false)) })] }, group.title))), toggles.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.propGroups.toggle }), _jsx("div", { className: "forgebook-toggles", children: toggles.map((prop) => toggle(prop, false)) })] })), others.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasControls ? STRINGS.otherProps : STRINGS.allProps }), _jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop, showsGroup: false }, prop.name))) })] })), propGroups.map((group) => group.name === undefined ? null : (_jsx(NamedGroup, { name: group.name, props: group.props, isSettable: isSettable, control: control, toggle: toggle }, group.name))), hasControls ? (_jsxs("div", { className: "forgebook-tab-foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: onReset, children: STRINGS.resetArgs }), worstCase?.canApply === true ? _jsx(WorstCaseControl, { worstCase: worstCase }) : null] })) : null] }));
+    return (_jsxs("div", { className: "forgebook-tab-props", children: [canOrderRequired(listed) ? (_jsx("div", { className: "forgebook-tab-head", children: _jsx(RequiredFirstSwitch, { state: ordering }) })) : null, hasControls ? null : _jsx("p", { className: "forgebook-tab-note", children: STRINGS.fixedExamples }), required.length === 0 ? null : (_jsx(NamedGroup, { name: STRINGS.required, props: required, isSettable: isSettable, field: control, isRequired: true })), settable.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-group", children: _jsx("div", { className: "forgebook-prop-grid", children: settable.map((prop) => control(prop, false)) }) })), others.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasControls ? STRINGS.otherProps : STRINGS.allProps }), _jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop, showsGroup: false }, prop.name))) })] })), propGroups.map((group) => group.name === undefined ? null : (_jsx(NamedGroup, { name: group.name, props: group.props, isSettable: isSettable, field: control }, group.name))), hasControls ? (_jsxs("div", { className: "forgebook-tab-foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: onReset, children: STRINGS.resetArgs }), worstCase?.canApply === true ? _jsx(WorstCaseControl, { worstCase: worstCase }) : null] })) : null] }));
 };

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

@@ -0,0 +1,33 @@
+/**
+ * A story of a composed catalogue (`refs`), shown read-only: its own catalogue's embed page in a frame, on that
+ * catalogue's origin, with this catalogue's switches. Loaded the first time one is opened.
+ *
+ * @remarks
+ * The embed page is the composed catalogue's own, so the story runs with its own preview, theme and frames, and this
+ * page runs none of its code: what crosses one way is the address (the story and the switches, which the embed reads as
+ * any address), the other way a height (`EmbedSizeMessage`), heard only from that frame's window and origin. A change of
+ * the toolbar's switches gives the frame a new address. Off this catalogue's origin the frame is sandboxed as a story's
+ * frame is, which keeps it from navigating this tab.
+ *
+ * @module
+ */
+import "./refStory.scss";
+import { type ReactNode } from "react";
+import { type CatalogueRef } from "../catalogueRefs.ts";
+/** The page's props. */
+export type RefStoryPageProps = {
+    /** The composed catalogues of the configuration. */
+    readonly refs: readonly CatalogueRef[];
+    /** The id of the catalogue the address names. */
+    readonly refId: string;
+    /** The story's id in it. */
+    readonly storyId: string;
+    /** This catalogue's switches, by id, with the values the view gives them. */
+    readonly switches: Readonly<Record<string, string>>;
+};
+/**
+ * A story of a composed catalogue, read-only.
+ *
+ * @param props - the composed catalogues, the one and the story the address names, and the switches.
+ */
+export declare const RefStoryPage: ({ refs, refId, storyId, switches }: RefStoryPageProps) => ReactNode;