forgebook 0.4.0 → 0.4.1

package/dist/src/shell/CustomControl.js

@@ -9,21 +9,11 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  *
  * @module
  */
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { controlArgTypeOf } from "../controlCode.js";
 import { isArgValue, UNSET_ARG } from "../messages.js";
-import { CONTROL_STRINGS, controlValueProblem, loadControl } from "./customControls.js";
-/** What a control is told of its arg. */
-const argTypeOf = (prop) => ({
-    name: prop.name,
-    label: prop.label ?? prop.name,
-    description: prop.description,
-    ...(prop.choices === undefined ? {} : { options: prop.choices }),
-    ...(prop.min === undefined ? {} : { min: prop.min }),
-    ...(prop.max === undefined ? {} : { max: prop.max }),
-    ...(prop.step === undefined ? {} : { step: prop.step }),
-    // the frame's word, read here since only a control needs it: what is no plain data never reaches a control
-    ...(prop.settings === undefined || !isArgValue(prop.settings) ? {} : { settings: prop.settings })
-});
+import { useCatalogue } from "./catalogueContext.js";
+import { CONTROL_STRINGS, controlStringsOf, controlValueProblem, loadControl } from "./customControls.js";
 /** The value as text, to tell whether it is still the one the control gave. */
 const textOf = (value) => JSON.stringify(value) ?? "";
 /** A value a control gave, checked: what to send, or what is wrong with it. */
@@ -40,15 +30,15 @@ const checkedChange = (module, next) => {
  *
  * @param props - the module, the value it starts from, and what it reports to.
  */
-const ControlRoom = ({ module, name, value, argType, onAccepted, onProblem }) => {
+const ControlRoom = ({ module, name, value, argType, strings, onAccepted, onProblem }) => {
     const element = useRef(null);
-    const start = useRef({ value, argType, onAccepted, onProblem });
-    start.current = { value, argType, onAccepted, onProblem };
+    const start = useRef({ value, argType, strings, onAccepted, onProblem });
+    start.current = { value, argType, strings, onAccepted, onProblem };
     useEffect(() => {
         const host = element.current;
         if (host === null)
             return;
-        const { value: shown, argType: told, onProblem: say } = start.current;
+        const { value: shown, argType: told, strings: words, onProblem: say } = start.current;
         const refusal = shown === undefined ? undefined : controlValueProblem(module, shown);
         say(refusal === undefined ? undefined : CONTROL_STRINGS.controlValue(name, refusal));
         let isMounted = true;
@@ -68,7 +58,8 @@ const ControlRoom = ({ module, name, value, argType, onAccepted, onProblem }) =>
                         start.current.onAccepted(change.value);
                     }
                 },
-                argType: told
+                argType: told,
+                strings: words
             });
         }
         catch (error) {
@@ -100,8 +91,10 @@ const MountedControl = ({ module, prop, name, value, onValueChange }) => {
         given.current = textOf(value);
         setMounts(mounts + 1);
     }
-    const argType = argTypeOf(prop);
-    return (_jsxs(_Fragment, { children: [_jsx(ControlRoom, { module: module, name: name, value: value, argType: argType, onProblem: setProblem, onAccepted: (next) => {
+    const argType = controlArgTypeOf(prop);
+    const { strings: catalogueStrings } = useCatalogue();
+    const strings = useMemo(() => controlStringsOf(catalogueStrings, name), [catalogueStrings, name]);
+    return (_jsxs(_Fragment, { children: [_jsx(ControlRoom, { module: module, name: name, value: value, argType: argType, strings: strings, onProblem: setProblem, onAccepted: (next) => {
                     given.current = textOf(next);
                     onValueChange(prop.name, next ?? UNSET_ARG);
                 } }, `${mounts}|${JSON.stringify(argType)}`), problem === undefined ? null : (_jsx("p", { className: "forgebook-prop__description forgebook-prop__problem", role: "alert", children: problem }))] }));

package/dist/src/shell/HomePage.js

@@ -4,6 +4,7 @@ import { findPage } from "../pageTree.js";
 import { findComponent, findStory } from "../storyTree.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { PackageHtml } from "./PackageHtml.js";
+import { usePageWidth } from "./PageWidth.js";
 import { PAGE_STRINGS } from "./pageStrings.js";
 import { useLoaded } from "./useLoaded.js";
 /** The most components a family's card lists before "Show all". */
@@ -128,7 +129,8 @@ export const HomePage = ({ title, tree, sources, storyGlobs = [], recent, hrefOf
     // it stops on a pattern that matches nothing
     const listingGlobs = storyGlobs.filter((glob) => !glob.startsWith("!") || glob.startsWith("!("));
     const isWaiting = listingGlobs.length > 0 && componentCount(tree) === 0;
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-home", children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsxs("p", { className: "forgebook-doc__lead", children: [isWaiting ? PAGE_STRINGS.homeNoStoryTitle : null, !isWaiting && tree.sources.length === 0 ? PAGE_STRINGS.homeEmpty : null, !isWaiting && tree.sources.length > 0
-                                            ? PAGE_STRINGS.homeSummary(componentCount(tree), libraryCount(tree))
-                                            : null] })] }), isWaiting ? _jsx(NoStoryYet, { globs: listingGlobs }) : null, _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen }), tree.sources.map((source) => (_jsx(LibrarySection, { source: source, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, source.id)))] }) })] }));
+    const pageWidth = usePageWidth();
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("div", { className: "forgebook-scroll", children: [_jsx("div", { className: "forgebook-home__tools", children: pageWidth.toggle }), _jsxs("div", { className: "forgebook-home", "data-page-width": pageWidth.width, children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsxs("p", { className: "forgebook-doc__lead", children: [isWaiting ? PAGE_STRINGS.homeNoStoryTitle : null, !isWaiting && tree.sources.length === 0 ? PAGE_STRINGS.homeEmpty : null, !isWaiting && tree.sources.length > 0
+                                                ? PAGE_STRINGS.homeSummary(componentCount(tree), libraryCount(tree))
+                                                : null] })] }), isWaiting ? _jsx(NoStoryYet, { globs: listingGlobs }) : null, _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen }), tree.sources.map((source) => (_jsx(LibrarySection, { source: source, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, source.id)))] })] })] }));
 };

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

@@ -0,0 +1,29 @@
+/**
+ * The width of the pages that list stories, the home and a component's page: contained in a centred column, or the
+ * whole width of the page; a reader's choice kept in their browser.
+ *
+ * @remarks
+ * It loads with those pages, never with the first screen: the shell's header keeps an empty place of the button's size
+ * beside the stories' picker (`.forgebook-page-width`), which the component's page fills with the button, so the
+ * picker stays where it is between a component's page, while its code arrives, and its stories' pages. A story's page
+ * has its own width controls on its stage. Each page writes the width on its column (`data-page-width`), where
+ * `shell.scss` reads it.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+/** How wide the pages that list stories are: in a centred column, or the whole page. */
+export type PageWidth = "contained" | "full";
+/** The reader's page width and the button that switches it. */
+export type PageWidthState = {
+    /** The width, for the column's `data-page-width`. */
+    readonly width: PageWidth;
+    /** The button, pressed while the page is contained. */
+    readonly toggle: ReactNode;
+};
+/**
+ * The reader's page width, kept for the next visit, and its button.
+ *
+ * @returns the width and the button.
+ */
+export declare const usePageWidth: () => PageWidthState;

package/dist/src/shell/PageWidth.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { useStored } from "./useStored.js";
+/** The width a stored text holds: contained unless the reader chose the whole page. */
+const storedWidth = (stored) => (stored === "full" ? "full" : "contained");
+/**
+ * The reader's page width, kept for the next visit, and its button.
+ *
+ * @returns the width and the button.
+ */
+export const usePageWidth = () => {
+    const [width, setWidth] = useStored("page-width", storedWidth, String);
+    return {
+        width,
+        toggle: (_jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon forgebook-page-width", title: LATER_STRINGS.pageContained, "aria-label": LATER_STRINGS.pageContained, "aria-pressed": width === "contained", onClick: () => setWidth(width === "full" ? "contained" : "full"), children: _jsx(Icon, { name: "width", size: 14 }) }))
+    };
+};

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

@@ -1,6 +1,6 @@
 /**
  * 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
  */
@@ -26,7 +26,7 @@ export type FieldState = {
     /** Called with a changed value. */
     readonly onValueChange: OnValueChange;
 };
-/** One adjustable prop with its control. */
+/** 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. */
@@ -46,16 +46,6 @@ export declare const PropControl: ({ prop, showsGroup, value, panelValue, named,
     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, 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. */
 export declare const ReadOnlyProp: ({ prop, showsGroup }: {
     readonly prop: PanelProp;

package/dist/src/shell/PropRows.js

@@ -1,7 +1,7 @@
 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
  */
@@ -11,6 +11,7 @@ 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));
@@ -60,12 +61,15 @@ const usesEditors = (prop, named) => named !== undefined ||
     (prop.kind === "choice" &&
         (prop.control === undefined || prop.control === "select") &&
         (prop.choices?.length ?? 0) > MOST_PLAIN_OPTIONS);
-/** One adjustable prop with its control. */
+/** 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;
     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,
@@ -90,10 +94,5 @@ export const PropControl = ({ prop, showsGroup, value, panelValue, named, namedV
     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, panelValue, onValueChange }) => {
-    const descriptionId = useId();
-    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.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";
@@ -45,8 +45,7 @@ export const PropsTab = ({ props, values, panelArgs, loadTokens, argControls, co
     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], 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, 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] }));
+    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/Shell.js

@@ -582,7 +582,10 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, storyGlobs, fra
     const files = source === undefined ? undefined : sourceFiles(source);
     const storyHrefOf = (story) => addressQuery(pageAddress(storyPage(story)), catalogue);
     const columnHeightOf = (storyId) => knownHeight(storyHeights, storyId, drawnWidth(address.view.width, PAGE_COLUMN_WIDTH));
-    const header = (_jsx(ShellHeader, { problems: problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    // the component's page puts its width's button in the header (`PageWidth.tsx`); until then, and on a story's page,
+    // an empty place of the button's size keeps the picker where it stays
+    const headerWith = (tools) => (_jsx(ShellHeader, { problems: problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)), children: tools })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    const header = headerWith(_jsx("span", { className: "forgebook-page-width" }));
     const homeProps = {
         title,
         tree,
@@ -625,7 +628,7 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, storyGlobs, fra
                             ...componentLoaders(files, shown.location.component),
                             background: storyBackground(shown.location.source.background, address.view, catalogue, isSystemDark),
                             heightOf: columnHeightOf,
-                            header,
+                            headerWith,
                             scroll,
                             usedIn: usedInLinks(source, catalogue.hasUsedIn, tree, {
                                 hrefOf: (page) => addressQuery(pageAddress(page), catalogue),

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

@@ -16,10 +16,12 @@ export type StoryPickerProps = {
     readonly onOpenComponent: () => void;
     /** Opens a story's page. */
     readonly onOpenStory: (story: TreeStory) => void;
+    /** What sits beside the select, at the header's end: the page width's button. */
+    readonly children?: ReactNode;
 };
 /**
  * The picker of a component's stories.
  *
- * @param props - the component, the shown story and how to open a page.
+ * @param props - the component, the shown story, how to open a page, and what sits beside the select.
  */
-export declare const StoryPicker: ({ component, currentStoryId, onOpenComponent, onOpenStory }: StoryPickerProps) => ReactNode;
+export declare const StoryPicker: ({ component, currentStoryId, onOpenComponent, onOpenStory, children }: StoryPickerProps) => ReactNode;

package/dist/src/shell/StoryPicker.js

@@ -15,9 +15,9 @@ const ALL = "";
 /**
  * The picker of a component's stories.
  *
- * @param props - the component, the shown story and how to open a page.
+ * @param props - the component, the shown story, how to open a page, and what sits beside the select.
  */
-export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpenStory }) => {
+export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpenStory, children }) => {
     const id = useId();
     const { storyGroups } = useCatalogue();
     const sections = groupedStories(component.stories, storyGroups.map((group) => group.id));
@@ -27,5 +27,5 @@ export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpen
                         onOpenComponent();
                     else
                         onOpenStory(chosen);
-                }, children: [_jsx("option", { value: ALL, children: STRINGS.allStories(component.stories.length) }), sections.map((section) => section.group === undefined ? (section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id)))) : (_jsx("optgroup", { label: groupLabel(storyGroups, section.group), children: section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id))) }, section.group)))] })] }));
+                }, children: [_jsx("option", { value: ALL, children: STRINGS.allStories(component.stories.length) }), sections.map((section) => section.group === undefined ? (section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id)))) : (_jsx("optgroup", { label: groupLabel(storyGroups, section.group), children: section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id))) }, section.group)))] }), children] }));
 };

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

@@ -0,0 +1,29 @@
+/**
+ * A boolean's switch, in the Props tab's fields and in the nested fields of the value editors.
+ *
+ * @remarks
+ * A native checkbox drawn as a switch (`role="switch"`, `.forgebook-switch`): it keeps Space, the label and the
+ * disabled state of a checkbox, and Enter turns it as well, as a switch's button would.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+/** What a switch shows and calls. */
+export type SwitchProps = {
+    /** Its accessible name. */
+    readonly label: string;
+    /** Whether it is on. */
+    readonly isOn: boolean;
+    /** The id of the text that describes it, when there is one. */
+    readonly describedBy?: string | undefined;
+    /** Whether it cannot be turned: a value the type fixes. */
+    readonly disabled?: boolean | undefined;
+    /** Called with the new state. */
+    readonly onChange: (isOn: boolean) => void;
+};
+/**
+ * The switch.
+ *
+ * @param props - its name, state and setter.
+ */
+export declare const Switch: ({ label, isOn, describedBy, disabled, onChange }: SwitchProps) => ReactNode;

package/dist/src/shell/Switch.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The switch.
+ *
+ * @param props - its name, state and setter.
+ */
+export const Switch = ({ label, isOn, describedBy, disabled, onChange }) => (_jsx("input", { type: "checkbox", role: "switch", className: "forgebook-switch", "aria-label": label, "aria-checked": isOn, "aria-describedby": describedBy, checked: isOn, disabled: disabled, onChange: (event) => onChange(event.target.checked), onKeyDown: (event) => {
+        // a click turns it as Space does, through its change
+        if (event.key === "Enter")
+            event.currentTarget.click();
+    } }));

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

@@ -53,3 +53,10 @@ export declare const controlValueProblem: (module: ArgControlModule, value: ArgV
  * @param loaders - the catalogue's custom controls.
  */
 export declare const customChecksOf: (names: readonly string[], loaders: ArgControlLoaders) => Promise<Readonly<Record<string, (value: ArgValue) => string | undefined>>>;
+/**
+ * A control's texts as the catalogue words them: its `strings` under `argControls.<name>.`, by the rest of the key.
+ *
+ * @param strings - the catalogue's replaced texts.
+ * @param name - the control's name.
+ */
+export declare const controlStringsOf: (strings: Readonly<Record<string, string>>, name: string) => Readonly<Record<string, string>>;

package/dist/src/shell/customControls.js

@@ -16,7 +16,8 @@ const isControlModule = (value) => typeof value === "object" &&
     "mount" in value &&
     typeof value.mount === "function" &&
     "schema" in value &&
-    isValueSchema(value.schema);
+    isValueSchema(value.schema) &&
+    (!("toCode" in value) || value.toCode === undefined || typeof value.toCode === "function");
 /** Each control's load, kept: every field and check of a page share one. */
 const loads = new Map();
 /** Loads one control's module, once, and reads what it exports. */
@@ -68,3 +69,13 @@ export const customChecksOf = async (names, loaders) => {
         ? [[name, (value) => controlValueProblem(control.module, value)]]
         : []));
 };
+/**
+ * A control's texts as the catalogue words them: its `strings` under `argControls.<name>.`, by the rest of the key.
+ *
+ * @param strings - the catalogue's replaced texts.
+ * @param name - the control's name.
+ */
+export const controlStringsOf = (strings, name) => {
+    const prefix = `argControls.${name}.`;
+    return Object.fromEntries(Object.entries(strings).flatMap(([key, text]) => key.startsWith(prefix) && key.length > prefix.length ? [[key.slice(prefix.length), text]] : []));
+};

package/dist/src/shell/dockTabs.js

@@ -168,7 +168,8 @@ const codeTabs = (input) => {
                     exportName: input.story.exportName,
                     componentName: docs.status === "ready" ? codeNameOf(docs.value) : input.componentName,
                     args: input.values,
-                    edited: Object.keys(input.panelArgs)
+                    edited: Object.keys(input.panelArgs),
+                    panel: input
                 } }))
         }
     ];

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

@@ -0,0 +1,35 @@
+/**
+ * Which waiting frames of a page start first: the ones the reader is looking at, then their neighbours outward.
+ *
+ * @remarks
+ * A page lists its stories top to bottom, but the reader may be anywhere on it: after a scroll to the end, the stories
+ * in view must not wait behind the ones above them that are still near. Read by `useFrameQueue`.
+ *
+ * @module
+ */
+/** A box's vertical extent, in the same coordinates as the visible part of the page. */
+export type VerticalBox = {
+    /** Its top edge, in CSS px. */
+    readonly top: number;
+    /** Its bottom edge, in CSS px. */
+    readonly bottom: number;
+};
+/**
+ * How far a box is from the visible part of the page: 0 when any of it is in view, otherwise the gap to the nearest
+ * edge.
+ *
+ * @param box - the box of a story's frame.
+ * @param view - the visible part of the page.
+ * @returns The distance, in CSS px.
+ */
+export declare const distanceFromView: (box: VerticalBox, view: VerticalBox) => number;
+/**
+ * The frames to start now: the nearest to the visible part first, in the page's order among equals, at most `free`.
+ *
+ * @param waiting - the stories waiting for their frame, in the page's order.
+ * @param distances - each story's distance from the visible part, in CSS px; a story with none comes after every
+ * other.
+ * @param free - how many frames may start.
+ * @returns The stories to start, nearest first.
+ */
+export declare const nearestFrames: (waiting: readonly string[], distances: ReadonlyMap<string, number>, free: number) => string[];

package/dist/src/shell/frameOrder.js

@@ -0,0 +1,45 @@
+/**
+ * Which waiting frames of a page start first: the ones the reader is looking at, then their neighbours outward.
+ *
+ * @remarks
+ * A page lists its stories top to bottom, but the reader may be anywhere on it: after a scroll to the end, the stories
+ * in view must not wait behind the ones above them that are still near. Read by `useFrameQueue`.
+ *
+ * @module
+ */
+/**
+ * How far a box is from the visible part of the page: 0 when any of it is in view, otherwise the gap to the nearest
+ * edge.
+ *
+ * @param box - the box of a story's frame.
+ * @param view - the visible part of the page.
+ * @returns The distance, in CSS px.
+ */
+export const distanceFromView = (box, view) => {
+    if (box.bottom <= view.top)
+        return view.top - box.bottom;
+    if (box.top >= view.bottom)
+        return box.top - view.bottom;
+    return 0;
+};
+/**
+ * The frames to start now: the nearest to the visible part first, in the page's order among equals, at most `free`.
+ *
+ * @param waiting - the stories waiting for their frame, in the page's order.
+ * @param distances - each story's distance from the visible part, in CSS px; a story with none comes after every
+ * other.
+ * @param free - how many frames may start.
+ * @returns The stories to start, nearest first.
+ */
+export const nearestFrames = (waiting, distances, free) => {
+    const distanceOf = (storyId) => distances.get(storyId) ?? Number.POSITIVE_INFINITY;
+    // a stable sort keeps the page's order among stories at the same distance, the demo first among those in view
+    // (compared rather than subtracted: two stories with no distance would give NaN)
+    const byDistance = (first, second) => {
+        const [one, other] = [distanceOf(first), distanceOf(second)];
+        if (one === other)
+            return 0;
+        return one < other ? -1 : 1;
+    };
+    return [...waiting].sort(byDistance).slice(0, Math.max(0, free));
+};

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

@@ -100,6 +100,7 @@ export declare const LATER_STRINGS: {
     backToPlace: string;
     backToPlaceNamed: (name: string) => string;
     examples: string;
+    pageContained: string;
     pageError: string;
     droppedArgs: string;
     droppedArgReasons: {

package/dist/src/shell/laterStrings.js

@@ -121,6 +121,7 @@ export const LATER_STRINGS = lateStrings({
     backToPlace: "Back to its place",
     backToPlaceNamed: (name) => `Back to its place: ${name}`,
     examples: "Examples",
+    pageContained: "Contained width",
     pageError: "The component's page could not be read",
     droppedArgs: "The link sets values this story does not take; they were left out:",
     droppedArgReasons: {

package/dist/src/shell/shell.css

@@ -624,6 +624,9 @@
     min-height: 0;
     overflow: auto;
   }
+  .forgebook-dock__body:has(.forgebook-tab-foot) {
+    scroll-padding-block-end: 2.5rem;
+  }
   .forgebook-icon-button {
     display: inline-flex;
     align-self: center;
@@ -667,10 +670,14 @@
     color: var(--forgebook-text-secondary);
   }
   .forgebook-tab-foot {
+    position: sticky;
+    bottom: 0;
+    z-index: 1;
     display: flex;
     align-items: center;
     gap: 0.75rem;
     padding: 0.625rem 0.875rem;
+    background: var(--forgebook-surface);
     box-shadow: inset 0 1px 0 var(--forgebook-separator);
   }
   .forgebook-tab-foot__note {
@@ -1554,6 +1561,21 @@
   .forgebook-picker__select {
     max-width: 22rem;
   }
+  .forgebook-page-width {
+    flex: none;
+    width: 1.625rem;
+  }
+  .forgebook-home__tools {
+    display: flex;
+    justify-content: flex-end;
+    height: 0;
+    padding: 0 2rem;
+  }
+  .forgebook-home__tools > * {
+    position: relative;
+    z-index: 1;
+    margin-top: 2rem;
+  }
   .forgebook-header__title {
     margin: 0;
     font: var(--forgebook-text-display);
@@ -1991,6 +2013,13 @@
   .forgebook-doc[data-audience=designer] {
     max-width: 72rem;
   }
+  [data-page-width] {
+    transition: max-width 260ms cubic-bezier(0.22, 1, 0.36, 1);
+  }
+  .forgebook-doc[data-page-width=full],
+  .forgebook-home[data-page-width=full] {
+    max-width: 100%;
+  }
   .forgebook-doc__lead {
     margin: 0;
     font-size: 1.0625rem;
@@ -2622,6 +2651,9 @@
     .forgebook-stage-tools {
       animation-name: forgebook-appear;
     }
+    [data-page-width] {
+      transition: none;
+    }
     .forgebook-sidebar,
     .forgebook-sidebar[data-overlay],
     .forgebook-sidebar-shade {
@@ -2682,7 +2714,7 @@
     gap: 0.375rem;
   }
   .forgebook-prop select,
-  .forgebook-prop input,
+  .forgebook-prop input:not(.forgebook-switch),
   .forgebook-prop textarea {
     box-sizing: border-box;
     height: 1.625rem;
@@ -2695,7 +2727,7 @@
     color: var(--forgebook-text);
   }
   .forgebook-prop select:focus-visible,
-  .forgebook-prop input:focus-visible,
+  .forgebook-prop input:not(.forgebook-switch):focus-visible,
   .forgebook-prop textarea:focus-visible {
     outline: 2px solid var(--forgebook-focus-halo);
     outline-offset: 0;
@@ -2708,7 +2740,7 @@
     padding: 0.25rem 0.5rem;
     resize: vertical;
   }
-  .forgebook-prop input[type=checkbox],
+  .forgebook-prop input[type=checkbox]:not(.forgebook-switch),
   .forgebook-prop input[type=radio] {
     height: auto;
     box-shadow: none;
@@ -2755,11 +2787,6 @@
     font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
-  .forgebook-toggle-row {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.25rem;
-  }
   .forgebook-prop__head {
     display: flex;
     align-items: center;
@@ -2776,7 +2803,7 @@
     display: flex;
     gap: 0.375rem;
   }
-  .forgebook-prop__field > input:first-child {
+  .forgebook-prop__field > input:first-child:not(.forgebook-switch) {
     flex: 1;
     min-width: 0;
   }