forgebook 0.3.3 → 0.4.0

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

@@ -7,6 +7,8 @@
 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,24 +17,43 @@ export type TextArgNote = {
     /** Whether the panel holds a value of its own for the prop. */
     readonly isChanged: boolean;
 };
+/** 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. */
-export declare const PropControl: ({ prop, showsGroup, value, named, textArg, onValueChange }: {
+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 }: {
+export declare const Toggle: ({ prop, showsGroup, value, panelValue, 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;
     readonly onValueChange: OnValueChange;
 }) => ReactNode;
 /** A prop the panel cannot set: its name, its type and its description, for reading; its group when asked. */

package/dist/src/shell/PropRows.js

@@ -7,19 +7,41 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 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 { 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 +51,49 @@ 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] }));
+/** 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. */
-export const PropControl = ({ prop, showsGroup, value, named, textArg, onValueChange }) => {
+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 (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 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 toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
-export const Toggle = ({ prop, showsGroup, value, onValueChange }) => {
+export const Toggle = ({ prop, showsGroup, value, panelValue, 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 })] }));
+    return (_jsxs("span", { className: "forgebook-toggle-row", children: [_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 })] }), isUnsetArg(panelValue) ? _jsx("span", { className: "forgebook-prop__state", children: STRINGS.stateUnset }) : null, _jsx(FieldActions, { prop: prop, value: value, panelValue: panelValue, onValueChange: onValueChange })] }));
 };
 /** 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

@@ -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,9 @@ 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 field = (prop, showsGroup) => prop.kind === "toggle" ? (_jsx(Toggle, { prop: prop, showsGroup: showsGroup, value: values[prop.name], panelValue: panelArgs[prop.name], onValueChange: onValueChange }, prop.name)) : (control(prop, showsGroup));
     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: field, isRequired: true })), settable.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-group", children: _jsx("div", { className: "forgebook-prop-grid", children: settable.map((prop) => field(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: field }, 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;

package/dist/src/shell/RefStoryPage.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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.css";
+import { useEffect, useRef, useState } from "react";
+import { refEmbedAddress, refStoryAddress } from "../catalogueRefs.js";
+import { EMBED_SIZE_TYPE } from "../embed.js";
+import { STAGE_HEIGHT_RANGE } from "../viewState.js";
+import { FRAME_SANDBOX, framesOrigin } from "./framesOrigin.js";
+import { Icon } from "./icons.js";
+import { REF_STRINGS } from "./refStrings.js";
+import { useRefIndex } from "./useRefIndex.js";
+/** The frame's height before the embed reports its own, in CSS px. */
+const WAITING_HEIGHT = 240;
+/**
+ * The browser features another site's page may use: what shows a story (full screen, a video, a copy button), and none
+ * that asks the reader (the camera, the microphone, the position, the clipboard's reading). A permission the reader
+ * gave this catalogue would otherwise be that site's too, without a question.
+ */
+const REF_PERMISSIONS = [
+    "fullscreen",
+    "picture-in-picture",
+    "autoplay",
+    "encrypted-media",
+    "clipboard-write"
+].join("; ");
+/** The story's component title and name, as the index gives them; none until it is read, or when it lists neither. */
+const namesOf = (index, storyId) => {
+    for (const component of index?.components ?? []) {
+        const story = component.stories.find((each) => each.id === storyId);
+        if (story !== undefined)
+            return { component: component.title.split("/").join(" › "), story: story.name };
+    }
+    return undefined;
+};
+/**
+ * Whether a message is a height from the embed page: its type and a number, nothing else is read.
+ *
+ * @param data - the message.
+ */
+const heightOf = (data) => {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const type = Reflect.get(data, "type");
+    const height = Reflect.get(data, "height");
+    // never taller than a stage: the embed scrolls a taller story inside its frame, and a page could say any number
+    return type === EMBED_SIZE_TYPE && typeof height === "number" && Number.isFinite(height) && height > 0
+        ? Math.min(Math.ceil(height), STAGE_HEIGHT_RANGE.max)
+        : undefined;
+};
+/**
+ * The embed page's frame, as tall as the story it reports.
+ *
+ * @param props - the composed catalogue, the frame's address and its accessible name.
+ */
+const RefFrame = ({ composed, address, title }) => {
+    const frameRef = useRef(null);
+    const [height, setHeight] = useState(undefined);
+    const origin = new URL(composed.url).origin;
+    useEffect(() => {
+        const onMessage = (event) => {
+            if (event.origin !== origin || event.source !== frameRef.current?.contentWindow)
+                return;
+            const reported = heightOf(event.data);
+            if (reported !== undefined)
+                setHeight(reported);
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [origin]);
+    return (_jsx("iframe", { ref: frameRef, className: "forgebook-ref-story__frame", src: address, title: title, allow: REF_PERMISSIONS, 
+        // on this catalogue's own origin a sandbox could be lifted by what runs in it; elsewhere it keeps this tab
+        sandbox: origin === window.location.origin ? undefined : FRAME_SANDBOX, style: { height: height ?? WAITING_HEIGHT } }));
+};
+/**
+ * Whether a composed catalogue is served on the origin this catalogue's stories run on, where it is not this page.
+ *
+ * @param composed - the composed catalogue.
+ */
+const isOnFramesOrigin = (composed) => {
+    const origin = new URL(composed.url).origin;
+    return origin === framesOrigin() && origin !== window.location.origin;
+};
+/**
+ * Why a story of a composed catalogue is not shown, or none: the shell names only a catalogue it composes, and one on
+ * this catalogue's stories' origin would be framed as one of them and share their storage.
+ *
+ * @param composed - the composed catalogue the address names, if the configuration has it.
+ * @param refId - the id the address names.
+ */
+const refusalOf = (composed, refId) => {
+    if (composed === undefined)
+        return REF_STRINGS.unknownRef(refId);
+    return isOnFramesOrigin(composed) ? REF_STRINGS.onFramesOrigin(composed.title) : undefined;
+};
+/**
+ * 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 const RefStoryPage = ({ refs, refId, storyId, switches }) => {
+    const composed = refs.find((each) => each.id === refId);
+    const state = useRefIndex(composed, true);
+    const refusal = refusalOf(composed, refId);
+    if (composed === undefined || refusal !== undefined)
+        return (_jsx("div", { className: "forgebook-workspace", role: "alert", children: _jsx("h1", { className: "forgebook-empty", children: refusal }) }));
+    const names = namesOf(state.status === "ready" ? state.index : undefined, storyId);
+    const storyName = names?.story ?? storyId;
+    return (_jsxs("div", { className: "forgebook-workspace forgebook-ref-story", children: [_jsxs("header", { className: "forgebook-header", children: [_jsx("p", { className: "forgebook-header__path", children: [composed.title, names?.component].filter((part) => part !== undefined).join(" · ") }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: storyName }), _jsxs("a", { className: "forgebook-button", href: refStoryAddress(composed, storyId), target: "_blank", rel: "noopener noreferrer", children: [_jsx(Icon, { name: "external", size: 12 }), REF_STRINGS.openThere(composed.title)] })] }), _jsx("p", { className: "forgebook-ref-story__note", children: REF_STRINGS.readOnly })] }), _jsx("div", { className: "forgebook-ref-story__stage", children: _jsx(RefFrame
+                // a new story is a new frame: its height starts over with it
+                , { composed: composed, address: refEmbedAddress(composed, storyId, switches), title: REF_STRINGS.storyTitle(storyName, composed.title) }, storyId) })] }));
+};

package/dist/src/shell/SearchPanel.js

@@ -112,24 +112,30 @@ const ResultNote = ({ result, listed }) => {
     return (_jsxs("p", { className: "forgebook-result__note", children: [more > 0 ? _jsx("span", { children: SEARCH_STRINGS.more(more) }) : null, result.missed.length > 0 ? _jsx("span", { children: SEARCH_STRINGS.missing(result.missed.join(", ")) }) : null] }));
 };
 /** The answer's rows, for the keys and the list. */
-const useResultRows = (answer) => {
+const useResultRows = (answer, hrefOf) => {
     const baseId = useId();
     return useMemo(() => answer.results.map((result, place) => ({
         result,
-        own: { id: `${baseId}-${place}`, target: result.target },
+        own: { id: `${baseId}-${place}`, key: hrefOf(result.target), target: result.target },
         hits: result.hits.map((hit, hitPlace) => ({
             hit,
-            row: { id: `${baseId}-${place}-${hitPlace}`, target: hit.target }
+            row: {
+                id: `${baseId}-${place}-${hitPlace}`,
+                key: `${hrefOf(result.target)} ${hitPlace}`,
+                target: hit.target
+            }
         }))
-    })), [answer, baseId]);
+    })), [answer, baseId, hrefOf]);
 };
 /** The highlighted row: moved by the keys and the pointer, kept in view, named to the field. */
-const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }) => {
-    const [place, setPlace] = useState(0);
-    // new words, or an index that arrived, change what each place holds: Enter must not open what the reader never saw
-    // biome-ignore lint/correctness/useExhaustiveDependencies: the rows are what resets it
-    useEffect(() => setPlace(0), [rows]);
-    const active = rows[Math.min(place, rows.length - 1)];
+const useActiveRow = ({ rows, isShown, words, isBehind, hrefOf, onOpen, onActiveChange, keysRef }) => {
+    // what a person chose is a row, not a place: an index that arrives moves the rows, and Enter must open the one chosen.
+    // Until they choose, and for new words, it is the first
+    const [chosen, setChosen] = useState();
+    const chosenPlace = chosen?.words === words ? rows.findIndex((row) => row.key === chosen.key) : -1;
+    const place = Math.max(chosenPlace, 0);
+    const active = rows[place];
+    const setActive = (row) => setChosen({ words, key: row.key });
     const activeId = isShown ? active?.id : undefined;
     useEffect(() => onActiveChange(activeId), [activeId, onActiveChange]);
     const listRef = useRef(null);
@@ -138,23 +144,42 @@ const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }
             return;
         listRef.current?.querySelector(`[id="${CSS.escape(activeId)}"]`)?.scrollIntoView({ block: "nearest" });
     }, [activeId]);
+    const act = ({ key, hasModifier }) => {
+        if (activeId === undefined || active === undefined)
+            return false;
+        const step = KEY_STEPS[key];
+        const next = step === undefined ? undefined : rows[(place + step + rows.length) % rows.length];
+        if (next !== undefined)
+            setActive(next);
+        else if (key !== "Enter")
+            return false;
+        else if (hasModifier)
+            window.open(hrefOf(active.target), "_blank", "noopener");
+        else
+            onOpen(active.target);
+        return true;
+    };
+    // a key pressed while the list is behind the words is meant for the list of those words, and waits for it
+    const waitingKeys = useRef([]);
+    useEffect(() => {
+        if (isBehind)
+            return;
+        const next = waitingKeys.current.shift();
+        // one at a time: the next key acts on the row this one moved to, which the next render gives
+        if (next !== undefined && !act(next))
+            waitingKeys.current = [];
+    });
     useImperativeHandle(keysRef, () => ({
         press: (key, hasModifier) => {
-            if (activeId === undefined || active === undefined)
-                return false;
-            const step = KEY_STEPS[key];
-            if (step !== undefined)
-                setPlace((row) => (row + step + rows.length) % rows.length);
-            else if (key !== "Enter")
-                return false;
-            else if (hasModifier)
-                window.open(hrefOf(active.target), "_blank", "noopener");
-            else
-                onOpen(active.target);
-            return true;
+            const isListKey = key === "Enter" || KEY_STEPS[key] !== undefined;
+            if (isListKey && (isBehind || waitingKeys.current.length > 0)) {
+                waitingKeys.current.push({ key, hasModifier });
+                return true;
+            }
+            return act({ key, hasModifier });
         }
     }));
-    return { active, setActive: (row) => setPlace(rows.indexOf(row)), listRef };
+    return { active, setActive, listRef };
 };
 /** The answer's state, in a line: how many results, what is still coming, what could not be read. */
 const PanelStatus = ({ total, query, isLoading, hasFailed }) => (_jsxs("p", { className: "forgebook-search-panel__status", role: "status", children: [total === 0 && !isLoading ? _jsx("span", { children: SEARCH_STRINGS.nothing(query.trim()) }) : null, total > 0 ? _jsx("span", { children: SEARCH_STRINGS.count(total) }) : null, isLoading ? _jsx("span", { children: SEARCH_STRINGS.reading }) : null, hasFailed ? _jsx("span", { children: SEARCH_STRINGS.unreadable }) : null] }));
@@ -175,7 +200,7 @@ export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth,
     // the field never waits for a long list
     const words = useDeferredValue(query);
     const answer = useMemo(() => searchCatalogue(all, words, LIMITS), [all, words]);
-    const results = useResultRows(answer);
+    const results = useResultRows(answer, hrefOf);
     const rows = useMemo(() => results.flatMap(({ own, hits }) => [own, ...hits.map(({ row }) => row)]), [results]);
     const isShown = isOpen && hasQuery;
     const panelRef = useRef(null);
@@ -188,6 +213,8 @@ export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth,
     const { active, setActive, listRef } = useActiveRow({
         rows,
         isShown,
+        words,
+        isBehind: words !== query,
         hrefOf,
         onOpen,
         onActiveChange,

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

@@ -10,8 +10,11 @@ import { type AddressTexts } from "../addressTexts.ts";
 import type { CatalogueLists } from "../catalogue.ts";
 import type { ViewSwitch } from "../switches.ts";
 import type { WrittenHomeProps } from "./AuthoredHome.tsx";
+import type { ArgControlLoaders } from "./customControls.ts";
 import { type LoadPluginHosts } from "./pluginHostsContext.ts";
 import type { ShellPlugin } from "./pluginTabs.tsx";
+import type { ShellRefs } from "./refParts.tsx";
+import { type ToolbarProps } from "./Toolbar.tsx";
 /** What an app passes to the shell. */
 export type ShellConfig = {
     /** The catalogue's name, in the page title and the sidebar. */
@@ -30,6 +33,8 @@ export type ShellConfig = {
     readonly heights?: string;
     /** The sources, in the order the sidebar lists them. */
     readonly sources: readonly StorySource[];
+    /** The catalogue's own story patterns, for a home with no story to say where it looks; none by default. */
+    readonly storyGlobs?: readonly string[];
     /**
      * The frame page's address: relative to the shell's (`frame.html`) when the frames share its origin, on the frames'
      * origin otherwise (`mountShell` makes it).
@@ -55,6 +60,13 @@ export type ShellConfig = {
     readonly home?: () => Promise<ComponentType<WrittenHomeProps>>;
     /** Loads the catalogue's design tokens, on first use; none when it has none. */
     readonly loadTokens?: () => Promise<unknown>;
+    /**
+     * Loads the previews of the catalogue's galleries, when one first opens; none when it gives none. The generated page
+     * gives what the configuration's check allowed; the page checks nothing itself.
+     */
+    readonly loadSwitchPreviews?: ToolbarProps["loadSwitchPreviews"];
+    /** Loads each custom control `argControls` registers, by name; none when it registers none. */
+    readonly argControls?: ArgControlLoaders;
     /** The plugins with views (the generated page passes them); none by default. */
     readonly plugins?: readonly ShellPlugin[];
     /**
@@ -67,6 +79,12 @@ export type ShellConfig = {
      * texts that are not plain words from a story that may write them into markup. `any` by default.
      */
     readonly addressTexts?: AddressTexts;
+    /**
+     * Other catalogues, built and deployed, listed after this one's stories and shown read-only (`catalogueRefs.ts`), and
+     * the code that draws them (`forgebook/shell/refs`): the generated page gives them only for a catalogue that has some,
+     * so the others' first load carries none of it. None by default.
+     */
+    readonly refs?: ShellRefs;
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its