forgebook 0.4.0 → 0.4.1

package/dist/src/frame/controlValues.js

@@ -0,0 +1,143 @@
+import { isArgValue, isUnsetArg } from "../messages.js";
+import { panelArgTypesOf } from "../storyArgTypes.js";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The controls the catalogue gives the component's props by type, by prop, from its docs as the plugin served them.
+ *
+ * @param docs - the docs module's value.
+ */
+const typedControlsOf = (docs) => {
+    const props = isRecord(docs) && Array.isArray(docs["props"]) ? docs["props"] : [];
+    return Object.fromEntries(props.flatMap((prop) => isRecord(prop) && typeof prop["name"] === "string" && typeof prop["customControl"] === "string"
+        ? [[prop["name"], prop["customControl"]]]
+        : []));
+};
+/**
+ * The custom control of each arg, as the panel draws it: a control the story's `argTypes` name, else the one the
+ * catalogue gives the prop by type, unless the `argTypes` name another control for it.
+ *
+ * @param argTypes - the story's `argTypes`, as the panel reads them.
+ * @param docs - its component's docs, as the plugin served them.
+ */
+export const argControlsOf = (argTypes, docs) => {
+    const typed = Object.entries(typedControlsOf(docs)).filter(([name]) => argTypes[name]?.control === undefined && argTypes[name]?.customControl === undefined);
+    const named = Object.entries(argTypes).flatMap(([name, argType]) => argType.customControl === undefined ? [] : [[name, argType.customControl]]);
+    return Object.fromEntries([...typed, ...named]);
+};
+/** Each story file's docs, loaded once by the frame. */
+const docsLoads = new Map();
+/**
+ * A story's component docs, or none when they cannot load: the panel then has no docs either, so no control by type.
+ *
+ * @param load - the loader.
+ */
+const loadedDocs = (load) => {
+    if (load === undefined)
+        return Promise.resolve(undefined);
+    // a load that failed is tried again by the next values: the docs may be there by then
+    const started = docsLoads.get(load) ??
+        load().catch(() => {
+            docsLoads.delete(load);
+            return undefined;
+        });
+    docsLoads.set(load, started);
+    return started;
+};
+/** Whether a module exports a `toStoryValue` function, and a `toPanelValue` function or none. */
+const isFrameModule = (value) => typeof value === "object" &&
+    value !== null &&
+    "toStoryValue" in value &&
+    typeof value.toStoryValue === "function" &&
+    (!("toPanelValue" in value) ||
+        value.toPanelValue === undefined ||
+        typeof value.toPanelValue === "function");
+/** Each frame module's load, kept: every value of a page shares one. */
+const loads = new Map();
+/** The reason an error gives. */
+const reasonOf = (error) => (error instanceof Error ? error.message : String(error));
+/** A frame module, loaded once, or why it cannot be. */
+const loadedModule = async (control, load) => {
+    try {
+        const started = loads.get(load) ?? load();
+        loads.set(load, started);
+        const module = await started;
+        return isFrameModule(module)
+            ? module
+            : `The control "${control}" names a frame module that exports no toStoryValue function`;
+    }
+    catch (error) {
+        return `The control "${control}" could not load its frame module: ${reasonOf(error)}`;
+    }
+};
+/**
+ * One arg's values as its control's frame module turns them.
+ *
+ * @param module - the module.
+ * @param control - the control's name.
+ * @param argType - the arg.
+ * @param args - the panel's values.
+ * @param story - the story.
+ */
+const argOutcome = (module, control, argType, args, story) => {
+    const { name } = argType;
+    const problems = [];
+    let own;
+    const ownValue = Object.hasOwn(story.args, name) ? story.args[name] : undefined;
+    if (module.toPanelValue !== undefined && ownValue !== undefined) {
+        try {
+            const named = module.toPanelValue(ownValue, argType);
+            own = named !== undefined && isArgValue(named) ? named : undefined;
+        }
+        catch (error) {
+            problems.push(`The control "${control}" could not name the story's value of "${name}": ${reasonOf(error)}`);
+        }
+    }
+    const named = own === undefined ? {} : { own };
+    const given = Object.hasOwn(args, name) ? args[name] : undefined;
+    if (given === undefined)
+        return { isDropped: false, problems, ...named };
+    // the panel's "no value" stays one: the story receives `undefined`, as for any arg
+    if (isUnsetArg(given))
+        return { value: { made: undefined }, isDropped: false, problems, ...named };
+    try {
+        return { value: { made: module.toStoryValue(given, argType) }, isDropped: false, problems, ...named };
+    }
+    catch (error) {
+        problems.push(`The control "${control}" could not turn the value of "${name}": ${reasonOf(error)}`);
+        return { isDropped: true, problems, ...named };
+    }
+};
+/**
+ * The values of the controls with a frame module, as the story and the panel take them.
+ *
+ * @param args - the panel's values, checked by the shell.
+ * @param loaders - the frame modules, by control.
+ * @param story - the story's own args, its `argTypes` and its docs.
+ */
+export const controlValuesOf = async (args, loaders, story) => {
+    const types = panelArgTypesOf(story.argTypes, []);
+    const controls = argControlsOf(types, await loadedDocs(story.loadDocs));
+    const outcomes = await Promise.all(Object.entries(controls).flatMap(([name, control]) => {
+        const load = Object.hasOwn(loaders, control) ? loaders[control] : undefined;
+        if (load === undefined)
+            return [];
+        const settings = Object.hasOwn(types, name) ? types[name]?.settings : undefined;
+        const argType = { name, ...(settings === undefined ? {} : { settings }) };
+        return [
+            loadedModule(control, load).then((module) => [
+                name,
+                typeof module === "string"
+                    ? { isDropped: Object.hasOwn(args, name), problems: [module] }
+                    : argOutcome(module, control, argType, args, story)
+            ])
+        ];
+    }));
+    return {
+        values: Object.fromEntries(outcomes.flatMap(([name, outcome]) => (outcome.value === undefined ? [] : [[name, outcome.value.made]]))),
+        dropped: outcomes.flatMap(([name, outcome]) => (outcome.isDropped ? [name] : [])),
+        own: Object.fromEntries(outcomes.flatMap(([name, outcome]) => (outcome.own === undefined ? [] : [[name, outcome.own]]))),
+        // a module that fails is said once, however many args use it
+        problems: [...new Set(outcomes.flatMap(([, outcome]) => outcome.problems))]
+    };
+};

package/dist/src/frame/mountFrame.d.ts

@@ -16,6 +16,7 @@ import type { StoryLanguage, StorySource } from "@forgebook/story-format/source"
 import { type CatalogueLists } from "../catalogue.ts";
 import { type FramesPlacement } from "../frameOrigins.ts";
 import { type ViewSwitch } from "../switches.ts";
+import { type ControlFrameLoaders } from "./panelControls.ts";
 import type { PlayToolsLoader } from "./playStory.ts";
 import { type FramePlugin } from "./pluginFrames.ts";
 import type { FrameRenderer } from "./renderer.ts";
@@ -50,6 +51,8 @@ export type FrameConfig = {
     readonly plugins?: readonly FramePlugin[];
     /** Where the frames run, so the frame hears only its shell: on the catalogue's own origin by default. */
     readonly frames?: FramesPlacement;
+    /** The custom controls' frame modules, by control, each loaded when first needed (the generated frame passes them). */
+    readonly argControls?: ControlFrameLoaders;
 };
 /**
  * Shows the story the address names in the given element.

package/dist/src/frame/mountFrame.js

@@ -34,6 +34,7 @@ import { followTouch } from "./followTouch.js";
 import { storyFrameClock } from "./frameClock.js";
 import { ERROR_MESSAGE_CLASS, ERROR_STACK_CLASS, FRAME_STARTED_ATTRIBUTE, NOT_AWAITED_ATTRIBUTE, PENDING_REASON_ATTRIBUTE, STATUS_ATTRIBUTE } from "./frameStatus.js";
 import { applyView, loadSheets, viewSheets } from "./frameView.js";
+import { panelControls } from "./panelControls.js";
 import { panelArgsOf, storyArgsOf } from "./panelValues.js";
 import { startPluginFrames } from "./pluginFrames.js";
 import { shellChannel } from "./shellChannel.js";
@@ -107,7 +108,7 @@ const failedToLoad = (message, fail) => {
 };
 /**
  * Does what a message of the shell asks of the rendered story; the view's live part is applied apart, before the story
- * loads.
+ * loads, and so are the panel's values (`panelControls.ts`).
  *
  * @param message - the message.
  * @param controls - the rendered story's controls.
@@ -121,8 +122,6 @@ const failedToLoad = (message, fail) => {
 const answerShell = (message, controls, storyId, pendingReason, rules, axeUrl, tellShell) => {
     if (message.type === "forgebook:replay")
         void controls.replay();
-    else if (message.type === "forgebook:args")
-        controls.setPanelArgs(message.args);
     else if (message.type === "forgebook:events")
         controls.setEvents(message.names);
     else if (message.type === "forgebook:matrix")
@@ -327,10 +326,9 @@ export const mountFrame = async (container, config) => {
         // why the story was not seen in its final state: a check of what it shows would pass on a fallback
         let pendingReason;
         const clock = storyFrameClock(story.clockStart, isClockHeldIn(window.location.search));
-        shell.listen((message) => {
-            if (controls !== undefined)
-                answerShell(message, controls, storyId, pendingReason, catalogue.a11y, config.axeUrl, tellShell);
-        });
+        // the controls with a frame module, which turn the panel's values first; their docs name those given by type
+        const typed = panelControls(config.argControls, source, location.story.file, reportError);
+        shell.listen((message) => typed.take(message, { story, controls, tellReady }, (drawn) => answerShell(message, drawn, storyId, pendingReason, catalogue.a11y, config.axeUrl, tellShell)));
         // the language's texts, and the switches the story reads (the language's provider reads its id among them); a
         // language the source gives as a loader is loaded as it is shown
         const shownFor = async (live) => {
@@ -353,7 +351,7 @@ export const mountFrame = async (container, config) => {
                 storyId,
                 canReplay: story.replay !== undefined,
                 hasClock: story.clockStart !== undefined,
-                args,
+                args: typed.withOwn(args),
                 textKeys: storyTextKeysOf(story.args),
                 argTypes: panelArgTypesOf(story.argTypes, excludedControls(story.parameters["controls"])),
                 controls: story.controls,
@@ -373,7 +371,7 @@ export const mountFrame = async (container, config) => {
             // the first of the list is the innermost
             decorators: [...preview.decorators, ...plugins.decorators],
             ...shown,
-            resolveArgs: (args) => storyArgsOf(args, source.namedValues),
+            resolveArgs: (args) => typed.storyArgs(storyArgsOf(args, source.namedValues)),
             onControlsReady: (next, outcome) => {
                 controls = next;
                 clearRetry(sessionStorageOf(window), window.location.href);
@@ -421,7 +419,7 @@ export const mountFrame = async (container, config) => {
                 values: values.map(previewValue),
                 details: values.map(detailOf)
             }),
-            panelArgsOf: (values) => panelArgsOf(values, source.namedValues),
+            panelArgsOf: (values) => typed.panelArgs(values, panelArgsOf(values, source.namedValues)),
             onArgsChange: (args) => tellShell({ type: "forgebook:story-args", storyId, args })
         });
         // an edit of the story file, or of a file it re-exports stories from, draws the story anew in place: the reader keeps

package/dist/src/frame/panelControls.d.ts

@@ -0,0 +1,67 @@
+/**
+ * What a frame keeps of the custom controls with a frame module: the panel's latest values as their modules turned them,
+ * and the story's own values they named. The turning itself (`controlValues.ts`) loads when the shell first gives values.
+ *
+ * @remarks
+ * Turning values takes a load, so the shell's other messages wait for the values before them: a Replay or a matrix
+ * right after a change draws the changed values, as without any frame module.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import type { PanelArgs, ShellMessage } from "../messages.ts";
+import type { ControlStory } from "./controlValues.ts";
+import type { StoryControls } from "./storyRun.ts";
+/** The custom controls' frame modules, by control: how to load each. */
+export type ControlFrameLoaders = Readonly<Record<string, () => Promise<unknown>>>;
+/** The story a message is for, as `take` reads it. */
+export type TakenStory<TControls> = {
+    /** The story as it is now. */
+    readonly story: Omit<ControlStory, "loadDocs">;
+    /** Its controls once drawn; none before, when nothing is answered. */
+    readonly controls: TControls | undefined;
+    /** Tells the shell the story's own values again. */
+    readonly tellReady: () => void;
+};
+/** A frame's custom controls with a frame module; with none, it hands the shell's messages on as they come. */
+export type PanelControls = {
+    /**
+     * Answers a message of the shell: the panel's values turned first, then given to the story; any other message after
+     * the values before it. A later change of values overtakes one still turning.
+     *
+     * @param message - the message.
+     * @param story - the story as it is now, and its controls once drawn; none before, when nothing is answered.
+     * @param answer - answers any other message.
+     */
+    readonly take: <TControls extends Pick<StoryControls, "setPanelArgs">>(message: ShellMessage, story: TakenStory<TControls>, answer: (controls: TControls) => void) => void;
+    /**
+     * The story's values with the turned ones over them; an arg whose control failed is left out, so the story keeps its
+     * own: its JSON is not what the story takes.
+     *
+     * @param resolved - the panel's values as the story would take them without the modules.
+     */
+    readonly storyArgs: (resolved: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+    /**
+     * The story's own values for the panel, with those the modules named over them.
+     *
+     * @param own - the story's own values, as plain data gives them.
+     */
+    readonly withOwn: (own: PanelArgs) => PanelArgs;
+    /**
+     * The panel's values of a story that changed its own args: a value a module made is given back as the panel's JSON it
+     * came from, which plain data cannot hold, so the panel keeps the reader's choice.
+     *
+     * @param values - the story's values.
+     * @param shown - the same as plain data gives them.
+     */
+    readonly panelArgs: (values: Readonly<Record<string, unknown>>, shown: PanelArgs) => PanelArgs;
+};
+/**
+ * A frame's custom controls with a frame module.
+ *
+ * @param loaders - the frame modules, by control; none hands every message on as it comes.
+ * @param source - the story's source, whose docs name the controls given by type.
+ * @param file - the story's file, the key of its docs.
+ * @param report - says what went wrong.
+ */
+export declare const panelControls: (loaders: ControlFrameLoaders | undefined, source: StorySource, file: string, report: (message: string) => void) => PanelControls;

package/dist/src/frame/panelControls.js

@@ -0,0 +1,110 @@
+import { sourceFiles } from "../sourceFiles.js";
+import { panelArgTypesOf } from "../storyArgTypes.js";
+import { STATUS_ATTRIBUTE } from "./frameStatus.js";
+import { panelArgsOf } from "./panelValues.js";
+/**
+ * Whether a frame module may have something to do for the story, so its docs are worth loading: the panel gives a
+ * value (any prop may be one a control takes by type), the story's `argTypes` name a control with a frame module, or
+ * the story gives itself a value plain data cannot show (an icon a module could name). A story with none of these, most
+ * of a page's frames, loads neither the turning code nor its docs.
+ *
+ * @param args - the panel's values.
+ * @param story - the story.
+ * @param loaders - the frame modules, by control.
+ * @param source - the story's source, whose named values show some values plainly.
+ */
+const mayTurn = (args, story, loaders, source) => {
+    if (Object.keys(args).length > 0)
+        return true;
+    const named = Object.values(panelArgTypesOf(story.argTypes, [])).some((argType) => argType.customControl !== undefined && Object.hasOwn(loaders, argType.customControl));
+    const shown = panelArgsOf(story.args, source.namedValues);
+    // an event's handler is no value a control sets: a type's control never takes an event
+    return (named ||
+        Object.entries(story.args).some(([name, value]) => value !== undefined && !Object.hasOwn(shown, name) && !/^on[A-Z]/.test(name)));
+};
+/**
+ * A frame's custom controls with a frame module.
+ *
+ * @param loaders - the frame modules, by control; none hands every message on as it comes.
+ * @param source - the story's source, whose docs name the controls given by type.
+ * @param file - the story's file, the key of its docs.
+ * @param report - says what went wrong.
+ */
+export const panelControls = (loaders, source, file, report) => {
+    const loadDocs = sourceFiles(source).docs[file];
+    let made;
+    // the panel's values last given, as JSON: what the made values came from
+    let given = {};
+    let count = 0;
+    // the values still turning, which the other messages wait for
+    let turning = Promise.resolve();
+    const reportError = (error) => report(error instanceof Error ? error.message : String(error));
+    return {
+        take: (message, { story, controls, tellReady }, answer) => {
+            if (controls === undefined)
+                return;
+            if (message.type !== "forgebook:args") {
+                if (loaders === undefined)
+                    answer(controls);
+                else
+                    turning = turning.then(() => answer(controls));
+            }
+            else if (loaders === undefined)
+                controls.setPanelArgs(message.args);
+            else if (!mayTurn(message.args, story, loaders, source)) {
+                // nothing a module could turn or name: no module, and no docs, load for this story
+                const hadOwn = Object.keys(made?.own ?? {}).length > 0;
+                count += 1;
+                made = undefined;
+                turning = turning.then(() => {
+                    controls.setPanelArgs(message.args);
+                    if (hadOwn)
+                        tellReady();
+                });
+            }
+            else {
+                count += 1;
+                const asked = count;
+                turning = import("./controlValues.js")
+                    .then(({ controlValuesOf }) => controlValuesOf(message.args, loaders, { ...story, loadDocs }))
+                    .then((next) => {
+                    // values the reader changed again meanwhile are the next call's to draw
+                    if (asked !== count)
+                        return;
+                    const isOwnNew = JSON.stringify(next.own) !== JSON.stringify(made?.own ?? {});
+                    made = next;
+                    given = message.args;
+                    controls.setPanelArgs(message.args);
+                    for (const problem of next.problems)
+                        report(problem);
+                    // the panel shows the story's own value a module names, told once known; a story in error stays one
+                    const isError = document.documentElement.getAttribute(STATUS_ATTRIBUTE) === "error";
+                    if (isOwnNew && !isError)
+                        tellReady();
+                })
+                    .catch((error) => {
+                    reportError(error);
+                    // without the modules the story still takes the values plain data can give
+                    if (asked !== count)
+                        return;
+                    made = undefined;
+                    controls.setPanelArgs(message.args);
+                });
+            }
+        },
+        storyArgs: (resolved) => {
+            const dropped = made?.dropped ?? [];
+            return Object.fromEntries(Object.entries({ ...resolved, ...made?.values }).filter(([name]) => !dropped.includes(name)));
+        },
+        withOwn: (own) => ({ ...own, ...made?.own }),
+        panelArgs: (values, shown) => {
+            const kept = Object.entries(made?.values ?? {}).flatMap(([name, value]) => {
+                const json = given[name];
+                return json !== undefined && Object.hasOwn(values, name) && values[name] === value
+                    ? [[name, json]]
+                    : [];
+            });
+            return { ...shown, ...Object.fromEntries(kept) };
+        }
+    };
+};

package/dist/src/shell/AuthoredHome.js

@@ -20,6 +20,7 @@ import { findStory } from "../storyTree.js";
 import { CodeText } from "./CodeText.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { blockPlaces, catalogueValues, DocBlocks, queuedBlocks } from "./DocBlocks.js";
+import { usePageWidth } from "./PageWidth.js";
 import { PAGE_STRINGS } from "./pageStrings.js";
 import { useLoaded } from "./useLoaded.js";
 import { usePageFrames } from "./usePageFrames.js";
@@ -53,6 +54,7 @@ export const AuthoredHome = ({ load, title, plugins, tree, sources, recent, href
     const places = useMemo(() => blockPlaces(content.blocks), [content.blocks]);
     const values = useMemo(() => catalogueValues(title, tree), [title, tree]);
     const frames = usePageFrames({ stories, queued, pageRef, view, touchOverrides });
+    const pageWidth = usePageWidth();
     useScrollMemory(pageRef, scroll);
     const openLink = useCallback((href) => {
         if (href.startsWith("#")) {
@@ -84,7 +86,7 @@ export const AuthoredHome = ({ load, title, plugins, tree, sources, recent, href
         plugins,
         strings: catalogue.strings
     };
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { ref: bodyRef, className: "forgebook-home forgebook-home--written", children: [loaded.status === "loading" ? null : (_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: filledText(content.title ?? title, values) }), content.description === undefined ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: filledText(content.description, values) }) }))] })), loaded.status === "error" ? (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [PAGE_STRINGS.homeError, ": ", loaded.message] })) : null, _jsx(HomeNotes, { notes: content.notes }), _jsx(DocBlocks, { blocks: content.blocks, context: context })] }) })] }));
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("div", { ref: pageRef, className: "forgebook-scroll", children: [_jsx("div", { className: "forgebook-home__tools", children: pageWidth.toggle }), _jsxs("div", { ref: bodyRef, className: "forgebook-home forgebook-home--written", "data-page-width": pageWidth.width, children: [loaded.status === "loading" ? null : (_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: filledText(content.title ?? title, values) }), content.description === undefined ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: filledText(content.description, values) }) }))] })), loaded.status === "error" ? (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [PAGE_STRINGS.homeError, ": ", loaded.message] })) : null, _jsx(HomeNotes, { notes: content.notes }), _jsx(DocBlocks, { blocks: content.blocks, context: context })] })] })] }));
 };
 /**
  * The written home as the shell draws it, its loader bound: what the page's entry hands the shell, so the shell's own

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

@@ -1,17 +1,22 @@
 /**
  * The panel's Code tab: the story's `render` as written in its file, or, for a story drawn from its args, the
  * component's JSX with the args its file writes as code and the values of the moment (the story's and the Props
- * tab's), with a button that copies it.
+ * tab's), with a button that copies it. A value a custom control sets is written as the code its control's `toCode`
+ * gives (`icon={IconStar}`), its module loaded as the panel loads it.
  *
  * @module
  */
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import { type StoryCodeSource } from "../storyCodeText.ts";
-/** The tab's props: the story whose code it shows. */
-export type CodeTabProps = StoryCodeSource;
+import type { DockTabsInput } from "./dockTabs.tsx";
+/** The tab's props: the story whose code it shows, and what the panel knows of its props. */
+export type CodeTabProps = StoryCodeSource & {
+    /** The component's docs, the story's `argTypes` and the catalogue's custom controls; none writes every value as JSON. */
+    readonly panel?: Pick<DockTabsInput, "docs" | "argTypes" | "storyArgs" | "controls" | "argControls">;
+};
 /**
  * The Code tab.
  *
  * @param props - the file's code, the story, the component's name and the args.
  */
-export declare const CodeTab: (props: CodeTabProps) => ReactNode;
+export declare const CodeTab: (tab: CodeTabProps) => ReactNode;

package/dist/src/shell/CodeTab.js

@@ -1,18 +1,61 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The panel's Code tab: the story's `render` as written in its file, or, for a story drawn from its args, the
+ * component's JSX with the args its file writes as code and the values of the moment (the story's and the Props
+ * tab's), with a button that copies it. A value a custom control sets is written as the code its control's `toCode`
+ * gives (`icon={IconStar}`), its module loaded as the panel loads it.
+ *
+ * @module
+ */
+import { useEffect, useMemo, useState } from "react";
+import { panelProps, settableProps } from "../argTypes.js";
+import { controlCodeOf } from "../controlCode.js";
 import { storyCodeText } from "../storyCodeText.js";
 import { useCodeWriter } from "./codeWriter.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { hasRenderCode, StoryCodeBlock } from "./StoryCodeBlock.js";
 import { STRINGS } from "./strings.js";
 import { useCopy } from "./useCopy.js";
+/**
+ * The code the story's custom controls write its values as, once their modules are loaded.
+ *
+ * @param props - the story and what the panel knows of its props.
+ */
+const useArgCode = ({ panel, args }) => {
+    const props = useMemo(() => panel === undefined || panel.docs.status !== "ready"
+        ? []
+        : settableProps(panelProps(panel.docs.value.props, panel.argTypes, panel.storyArgs), panel.controls, {}), [panel]);
+    const names = [...new Set(props.flatMap((prop) => prop.customControl ?? []))].join("\n");
+    const [coders, setCoders] = useState({});
+    const loaders = panel?.argControls;
+    useEffect(() => {
+        if (names === "" || loaders === undefined)
+            return;
+        let isCurrent = true;
+        void import("./customControls.js")
+            .then(({ loadControl }) => Promise.all(names.split("\n").map(async (name) => [name, await loadControl(name, loaders)])))
+            .then((loaded) => {
+            if (!isCurrent)
+                return;
+            setCoders(Object.fromEntries(loaded.flatMap(([name, control]) => control.status === "ready" ? [[name, control.module.toCode]] : [])));
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [names, loaders]);
+    return useMemo(() => controlCodeOf(props, args, coders), [props, args, coders]);
+};
 /**
  * The Code tab.
  *
  * @param props - the file's code, the story, the component's name and the args.
  */
-export const CodeTab = (props) => {
+export const CodeTab = (tab) => {
     const { isCopied, copy } = useCopy();
     const write = useCodeWriter();
+    const argCode = useArgCode(tab);
+    const { panel: _panel, ...source } = tab;
+    const props = { ...source, argCode };
     const hasRender = hasRenderCode(props);
     return (_jsxs("div", { className: "forgebook-prop-group", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasRender ? LATER_STRINGS.codeRender : LATER_STRINGS.codeFromArgs }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => copy(storyCodeText(props, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : LATER_STRINGS.copy })] }), _jsx(StoryCodeBlock, { ...props })] }));
 };

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

@@ -4,8 +4,8 @@
  * example.
  *
  * @remarks
- * The frames load a few at a time (`useFrameQueue`), in the page's order, the demo first, each as it comes near the
- * visible part of the page: a component may have twenty stories. The view's live part reaches every frame as a message, as
+ * The frames load a few at a time (`useFrameQueue`), each as it comes near the visible part of the page, the nearest
+ * first and the demo first among those in view: a component may have a hundred stories. The view's live part reaches every frame as a message, as
  * on the story page; the props panel and Replay belong to a story's own page, which each story's name links to. The
  * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`). Who reads the page
  * reorders and filters what goes around the frames (`audienceLayout.ts`); what only one audience wants loads on first use,
@@ -51,8 +51,8 @@ export type ComponentPageProps = {
     readonly heightOf: (storyId: string) => number | undefined;
     /** The colour the stories' page has in the view (their source's), which each box waits on; none without one. */
     readonly background: string | undefined;
-    /** What stays above the page while it scrolls: the component's header. */
-    readonly header: ReactNode;
+    /** What stays above the page while it scrolls: the component's header, with the page's tools beside its picker. */
+    readonly headerWith: (tools: ReactNode) => ReactNode;
     /** Where its scrolling part starts: the shell's visit of the page and every page's last position. */
     readonly scroll: PageScroll;
     /** What "Used in" reads and opens; none when the catalogue turned it off. */
@@ -97,4 +97,4 @@ export declare const PageApi: ({ docs, isLogic, componentGroups, requiredFirst }
  *
  * @param props - the component, the view, its loaders and how to open a story.
  */
-export declare const ComponentPage: ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }: ComponentPageProps) => ReactNode;
+export declare const ComponentPage: ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, headerWith, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }: ComponentPageProps) => ReactNode;

package/dist/src/shell/ComponentPage.js

@@ -14,6 +14,7 @@ import { Example } from "./Example.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { LazyView, lazyModule } from "./lazyModule.js";
 import { PackageHtml } from "./PackageHtml.js";
+import { usePageWidth } from "./PageWidth.js";
 import { PageTagView } from "./pageTagView.js";
 import { UsedIn } from "./UsedIn.js";
 import { useComponentDocs } from "./useComponentDocs.js";
@@ -91,11 +92,12 @@ export const PageApi = ({ docs, isLogic, componentGroups, requiredFirst }) => do
  *
  * @param props - the component, the view, its loaders and how to open a story.
  */
-export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }) => {
+export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouchChange, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, headerWith, scroll, usedIn, onViewChange, tree, componentId, pageHrefOf, onOpenPage, loadTokens }) => {
     const pageRef = useRef(null);
     const docs = useComponentDocs(loadDocs);
     const code = useStoryCode(loadCode);
     const page = usePageDoc(loadPage);
+    const pageWidth = usePageWidth();
     const demo = mainStory(component);
     const examples = useMemo(() => component.stories.filter((story) => story.id !== demo?.id), [component, demo]);
     const catalogue = useCatalogue();
@@ -163,5 +165,5 @@ export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouch
             usedIn,
             pageRef
         };
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, anchor === undefined ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AnchorScroll, { pageRef: pageRef, anchor: anchor, visit: scroll.visit, isReady: docs.status !== "loading" && page.status !== "loading" }) })), _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", "data-audience": view.audience === "everyone" ? undefined : view.audience, children: [hasTags ? _jsx(PageTagView, { place: "page", component: component, loadDocs: loadDocs }) : null, _jsx(AudienceSlot, { place: "beforeDemo", audience: audienceProps, children: _jsx(Lead, { page: page, docs: componentDocs }) }), demo === undefined ? null : (_jsx(Example, { ...context, story: demo, isDemo: true, isMounted: queue.mounted.has(demo.id), observe: queue.observerOf(demo.id) })), _jsxs(AudienceSlot, { place: "afterDemo", audience: audienceProps, children: [_jsx(Prose, { page: page }), _jsx(PageApi, { docs: componentDocs, isLogic: isLogic, componentGroups: component.propGroups, requiredFirst: component.requiredFirst })] }), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: LATER_STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, titleTag: section.group === undefined ? "h3" : "h4", isMounted: queue.mounted.has(story.id), observe: queue.observerOf(story.id) }, story.id)))] }, section.group ?? "")))] })), _jsx(AudienceSlot, { place: "afterExamples", audience: audienceProps, children: usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn }) })] }, `${component.file}|${component.title}`) })] }));
+    return (_jsxs("div", { className: "forgebook-workspace", children: [headerWith(pageWidth.toggle), anchor === undefined ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AnchorScroll, { pageRef: pageRef, anchor: anchor, visit: scroll.visit, isReady: docs.status !== "loading" && page.status !== "loading" }) })), _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", "data-audience": view.audience === "everyone" ? undefined : view.audience, "data-page-width": pageWidth.width, children: [hasTags ? _jsx(PageTagView, { place: "page", component: component, loadDocs: loadDocs }) : null, _jsx(AudienceSlot, { place: "beforeDemo", audience: audienceProps, children: _jsx(Lead, { page: page, docs: componentDocs }) }), demo === undefined ? null : (_jsx(Example, { ...context, story: demo, isDemo: true, isMounted: queue.mounted.has(demo.id), observe: queue.observerOf(demo.id) })), _jsxs(AudienceSlot, { place: "afterDemo", audience: audienceProps, children: [_jsx(Prose, { page: page }), _jsx(PageApi, { docs: componentDocs, isLogic: isLogic, componentGroups: component.propGroups, requiredFirst: component.requiredFirst })] }), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: LATER_STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, titleTag: section.group === undefined ? "h3" : "h4", isMounted: queue.mounted.has(story.id), observe: queue.observerOf(story.id) }, story.id)))] }, section.group ?? "")))] })), _jsx(AudienceSlot, { place: "afterExamples", audience: audienceProps, children: usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn }) })] }, `${component.file}|${component.title}`) })] }));
 };