forgebook 0.3.3 → 0.4.1

package/dist/src/shell/ApiReference.js

@@ -1,11 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState } from "react";
 import { canOrderRequired, laidOutProps, propGroupOrder } from "../propGroups.js";
+import { ApiTableBox } from "./ApiTableBox.js";
 import { Code } from "./Code.js";
 import { CodeText } from "./CodeText.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
 import { LATER_STRINGS } from "./laterStrings.js";
+import { propNoteTexts, propsNoteText } from "./propNotes.js";
 import { RequiredFirstSwitch } from "./RequiredFirstSwitch.js";
 import { SignatureReference } from "./SignatureReference.js";
 import { STRINGS } from "./strings.js";
@@ -39,7 +41,7 @@ const RowPlace = ({ row }) => {
 const Row = ({ row, hasDefaults, columns, part, showsGroup }) => {
     const [isOpen, setOpen] = useState(false);
     const { members } = row;
-    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "data-prop": part === undefined ? row.name : `${part}.${row.name}`, children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: row.name }), row.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null, showsGroup ? _jsx(RowPlace, { row: row }) : null] }), _jsxs("td", { className: "forgebook-api__type", children: [_jsx(Code, { text: typeText(row), names: row.signature?.parameters.map((parameter) => parameter.name) ?? [] }), members === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-api__members-toggle", "aria-expanded": isOpen, "aria-label": `${LATER_STRINGS.membersOf(row.type)}: ${LATER_STRINGS.memberCount(members.length)}`, onClick: () => setOpen(!isOpen), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), LATER_STRINGS.memberCount(members.length)] }))] }), hasDefaults ? (_jsx("td", { children: row.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: row.defaultValue })) })) : null, _jsx("td", { children: _jsx(CodeText, { text: row.description }) })] }), members !== undefined && isOpen ? (_jsx("tr", { className: "forgebook-api__members", children: _jsx("td", { colSpan: columns, children: _jsx(PropTable, { rows: members, kind: "members", label: LATER_STRINGS.membersOf(row.type), part: part === undefined ? row.name : `${part}.${row.name}` }) }) })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "data-prop": part === undefined ? row.name : `${part}.${row.name}`, children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: row.name }), row.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null, showsGroup ? _jsx(RowPlace, { row: row }) : null] }), _jsxs("td", { className: "forgebook-api__type", children: [_jsx(Code, { text: typeText(row), names: row.signature?.parameters.map((parameter) => parameter.name) ?? [] }), members === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-api__members-toggle", "aria-expanded": isOpen, "aria-label": `${LATER_STRINGS.membersOf(row.type)}: ${LATER_STRINGS.memberCount(members.length)}`, onClick: () => setOpen(!isOpen), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), LATER_STRINGS.memberCount(members.length)] }))] }), hasDefaults ? (_jsx("td", { children: row.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: row.defaultValue })) })) : null, _jsxs("td", { children: [_jsx(CodeText, { text: row.description }), propNoteTexts(row).map((note) => (_jsx("span", { className: "forgebook-api__note", children: _jsx(CodeText, { text: note }) }, note)))] })] }), members !== undefined && isOpen ? (_jsx("tr", { className: "forgebook-api__members", children: _jsx("td", { colSpan: columns, children: _jsx(PropTable, { rows: members, kind: "members", label: LATER_STRINGS.membersOf(row.type), part: part === undefined ? row.name : `${part}.${row.name}` }) }) })) : null] }));
 };
 /**
  * A table of props, events or members: the Default column only when one of them has a default.
@@ -49,7 +51,7 @@ const Row = ({ row, hasDefaults, columns, part, showsGroup }) => {
  */
 const PropTable = ({ rows, kind, label, part, showsGroups = false }) => {
     const hasDefaults = kind !== "events" && rows.some((row) => row.defaultValue !== undefined);
-    return (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", "aria-label": label, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: NAME_HEADINGS[kind]() }), _jsx("th", { scope: "col", children: kind === "events" ? LATER_STRINGS.apiSignature : STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: LATER_STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: rows.map((row) => (_jsx(Row, { row: row, hasDefaults: hasDefaults, columns: hasDefaults ? 4 : 3, part: part, showsGroup: showsGroups }, row.name))) })] }) }));
+    return (_jsx(ApiTableBox, { children: _jsxs("table", { className: "forgebook-api__table", "aria-label": label, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: NAME_HEADINGS[kind]() }), _jsx("th", { scope: "col", children: kind === "events" ? LATER_STRINGS.apiSignature : LATER_STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: LATER_STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: LATER_STRINGS.apiWhat })] }) }), _jsx("tbody", { children: rows.map((row) => (_jsx(Row, { row: row, hasDefaults: hasDefaults, columns: hasDefaults ? 4 : 3, part: part, showsGroup: showsGroups }, row.name))) })] }) }));
 };
 /**
  * A group of props: the props that name none as a table alone, a named group under its heading, open until a reader
@@ -100,5 +102,6 @@ export const ApiReference = ({ docs, isLogic, componentGroups = NO_GROUPS, requi
         ...(isSignature ? [] : docs.props),
         ...docs.subcomponents.flatMap((subcomponent) => subcomponent.props)
     ];
-    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsxs("div", { className: "forgebook-api__head", children: [_jsx("h2", { id: "forgebook-api", children: LATER_STRINGS.apiReference }), canOrderRequired(shown) ? _jsx(RequiredFirstSwitch, { state: ordering }) : null] }), isSignature ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, layout: ordering.layout, level: 3 })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent, groupOrder: groupOrder, layout: ordering.layout }, subcomponent.name)))] }));
+    const propsNote = isSignature ? undefined : propsNoteText(docs);
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsxs("div", { className: "forgebook-api__head", children: [_jsx("h2", { id: "forgebook-api", children: LATER_STRINGS.apiReference }), canOrderRequired(shown) ? _jsx(RequiredFirstSwitch, { state: ordering }) : null] }), isSignature ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, layout: ordering.layout, level: 3 })), propsNote === undefined ? null : (_jsx("p", { className: "forgebook-api__note", children: _jsx(CodeText, { text: propsNote }) })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent, groupOrder: groupOrder, layout: ordering.layout }, subcomponent.name)))] }));
 };

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

@@ -0,0 +1,15 @@
+/**
+ * The box around a table of the API reference: a table wider than the page scrolls in it, never the page, by the
+ * pointer or from its Tab stop.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+/**
+ * A table's box.
+ *
+ * @param props - the table.
+ */
+export declare const ApiTableBox: ({ children }: {
+    readonly children: ReactNode;
+}) => ReactNode;

package/dist/src/shell/ApiTableBox.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useScrollStops } from "./useScrollStops.js";
+/**
+ * A table's box.
+ *
+ * @param props - the table.
+ */
+export const ApiTableBox = ({ children }) => {
+    const boxRef = useScrollStops();
+    return (_jsx("div", { ref: boxRef, className: "forgebook-api", children: children }));
+};

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

@@ -11,4 +11,7 @@ import type { AppearanceState } from "./useAppearance.ts";
  *
  * @param props - the appearance shown and its setter.
  */
-export declare const AppearanceMenu: ({ appearance, setAppearance, offered }: AppearanceState) => ReactNode;
+export declare const AppearanceMenu: ({ appearance, setAppearance, offered, onShowKeys }: AppearanceState & {
+    /** Opens the list of the shell's keys, which a reader who turned them off reaches here. */
+    readonly onShowKeys: () => void;
+}) => ReactNode;

package/dist/src/shell/AppearanceMenu.js

@@ -21,11 +21,14 @@ const ICONS = {
  *
  * @param props - the appearance shown and its setter.
  */
-export const AppearanceMenu = ({ appearance, setAppearance, offered }) => {
-    const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
+export const AppearanceMenu = ({ appearance, setAppearance, offered, onShowKeys }) => {
+    const { isOpen, isDrawn, setIsOpen, closeAfterChoice, buttonRef, panelRef, panelId } = usePopover();
     const name = useId();
-    return (_jsxs("div", { className: "forgebook-appearance", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button forgebook-button--quiet", "aria-expanded": isOpen, "aria-controls": panelId, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: ICONS[appearance], size: 14 }), STRINGS.appearanceOf(STRINGS.appearances[appearance])] }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--up", role: "dialog", "aria-label": STRINGS.appearance, children: _jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.appearance }), offered.map((each) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, checked: each === appearance, onChange: () => {
-                                        setAppearance(each);
-                                        setIsOpen(false);
-                                    } }), _jsx(Icon, { name: ICONS[each], size: 14 }), STRINGS.appearances[each]] }, each)))] }) })) : null] }));
+    return (_jsxs("div", { className: "forgebook-appearance", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button forgebook-button--quiet", "aria-expanded": isOpen, "aria-controls": panelId, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: ICONS[appearance], size: 14 }), STRINGS.appearanceOf(STRINGS.appearances[appearance])] }), isDrawn ? (_jsxs("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--up", role: "dialog", "aria-label": STRINGS.appearance, children: [_jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.appearance }), offered.map((each) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, checked: each === appearance, onChange: () => {
+                                            setAppearance(each);
+                                            closeAfterChoice();
+                                        } }), _jsx(Icon, { name: ICONS[each], size: 14 }), STRINGS.appearances[each]] }, each)))] }), _jsx("button", { type: "button", className: "forgebook-button forgebook-button--quiet", onClick: (event) => {
+                            setIsOpen(false, event);
+                            onShowKeys();
+                        }, children: STRINGS.keys })] })) : null] }));
 };

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,16 +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 values of the moment (the story's and the Props tab's), with a button that copies it.
+ * 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 type { ReactNode } from "react";
-import { type StoryCodeSource } from "./StoryCodeBlock.tsx";
-/** The tab's props: the story whose code it shows. */
-export type CodeTabProps = StoryCodeSource;
+import { type ReactNode } from "react";
+import { type StoryCodeSource } from "../storyCodeText.ts";
+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,17 +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 { StoryCodeBlock, storyCodeText } from "./StoryCodeBlock.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 hasRender = props.code[props.exportName] !== undefined;
+    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/CodeText.d.ts

@@ -1,6 +1,6 @@
 /**
  * A TSDoc or Markdown sentence with its code spans shown as code: what is between backticks (as `href` is written in
- * a TSDoc) is set in the code face, the rest stays text.
+ * a TSDoc) is set in the code face, the rest stays text. Spans are read as CommonMark reads them (`codeSpans.ts`).
  *
  * @module
  */

package/dist/src/shell/CodeText.js

@@ -1,9 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { sentencePieces } from "./codeSpans.js";
 /**
  * A sentence, its backtick spans as code.
  *
  * @param props - the sentence.
  */
-export const CodeText = ({ text }) => 
-// a split on the backticks alternates text and code: the odd pieces were between backticks
-text.split("`").map((piece, index) => index % 2 === 1 ? (_jsx("code", { className: "forgebook-inline-code", children: piece }, index)) : (piece));
+export const CodeText = ({ text }) => sentencePieces(text).map((piece, index) => piece.isCode ? (_jsx("code", { className: "forgebook-inline-code", children: piece.text }, index)) : (piece.text));

package/dist/src/shell/CompareGrid.js

@@ -14,7 +14,7 @@ export const CompareGrid = ({ story, title, view, frameUrl, framed, heights, set
     const catalogue = useCatalogue();
     const { switches } = catalogue;
     const isSystemDark = useSystemDark();
-    return (_jsx("div", { className: "forgebook-compare", ...framed?.parts.compareGridProps(framed.drawing), children: compareVariants(view.compare, catalogue).map((variant) => {
+    return (_jsx("div", { className: "forgebook-compare", ...framed?.parts.compareGridProps(framed.drawing), children: compareVariants(view.compare, catalogue, view).map((variant) => {
             const cellView = variant.viewOf(view);
             // the label (the shell's text) reads on the page's colour, or on the shell's around a device, whose screen
             // has it; the frame draws the backdrop

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

@@ -1,11 +1,11 @@
 /**
- * A component's page, as a library documents a component: what it is, its demo (the story marked `main`) with
+ * A component's page, as a library documents a component: its status, what it is, its demo (the story marked `main`) with
  * its code, the text of its documentation file, its API reference drawn from its types, then every other story as an
  * 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

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { lazy, Suspense, useEffect, useMemo, useRef } from "react";
 import { groupLabel } from "../catalogue.js";
 import { codeNameOf } from "../componentDocs.js";
+import { hasFilterTags } from "../storyTagNames.js";
 import { groupedStories, isLogicComponent, mainStory } from "../storyTree.js";
 import { usageLoader } from "../usedIn.js";
 import { viewParams } from "../viewState.js";
@@ -13,6 +14,8 @@ 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";
 import { usePageDoc } from "./usePageDoc.js";
@@ -89,14 +92,17 @@ 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();
+    // statuses are tags: a catalogue with none draws none, and loads nothing for them
+    const hasTags = useMemo(() => hasFilterTags(tree), [tree]);
     // the demo first in the queue, at the top of the page, and counted in it: a frame of a library served as source asks
     // for thousands of modules, and one more beside those the queue allows makes the browser refuse some of them
     const queued = useMemo(() => [...(demo === undefined ? [] : [demo.id]), ...examples.map((story) => story.id)], [demo, examples]);
@@ -159,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: [_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, 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}`) })] }));
 };

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

@@ -0,0 +1,34 @@
+/**
+ * The element a custom control draws in, and what stands between it and the panel: its value checked both ways, and its
+ * failures kept beside the field. Loaded with the first story that names such a control.
+ *
+ * @remarks
+ * The control keeps what it draws: mounting it again on each of its own changes would take the focus out of it. So it is
+ * mounted again only when the value differs from the one it last gave, which is a change from outside (Reset, a link). An error it throws later, in its own event handler, is out of reach here: the page's own, as a plugin's.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { PanelProp } from "../argTypes.ts";
+import { type ArgValue } from "../messages.ts";
+import { type ArgControlLoaders } from "./customControls.ts";
+import type { OnValueChange } from "./PropFields.tsx";
+/** The host's props. */
+export type CustomControlProps = {
+    /** The prop. */
+    readonly prop: PanelProp;
+    /** The name of the control it asks for. */
+    readonly name: string;
+    /** Its value. */
+    readonly value: ArgValue | undefined;
+    /** The catalogue's custom controls. */
+    readonly loaders: ArgControlLoaders;
+    /** Called with a changed value. */
+    readonly onValueChange: OnValueChange;
+};
+/**
+ * A custom control, or why there is none.
+ *
+ * @param props - the prop, the control's name, its value, and the catalogue's controls.
+ */
+export declare const CustomControl: ({ loaders, ...props }: CustomControlProps) => ReactNode;

package/dist/src/shell/CustomControl.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The element a custom control draws in, and what stands between it and the panel: its value checked both ways, and its
+ * failures kept beside the field. Loaded with the first story that names such a control.
+ *
+ * @remarks
+ * The control keeps what it draws: mounting it again on each of its own changes would take the focus out of it. So it is
+ * mounted again only when the value differs from the one it last gave, which is a change from outside (Reset, a link). An error it throws later, in its own event handler, is out of reach here: the page's own, as a plugin's.
+ *
+ * @module
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { controlArgTypeOf } from "../controlCode.js";
+import { isArgValue, UNSET_ARG } from "../messages.js";
+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. */
+const checkedChange = (module, next) => {
+    if (next === undefined)
+        return { value: undefined };
+    if (!isArgValue(next))
+        return { problem: "not plain JSON" };
+    const problem = controlValueProblem(module, next);
+    return problem === undefined ? { value: next } : { problem };
+};
+/**
+ * The element one mount of a control draws in. It is given a new key for each mount, so nothing it holds outlives one.
+ *
+ * @param props - the module, the value it starts from, and what it reports to.
+ */
+const ControlRoom = ({ module, name, value, argType, strings, onAccepted, onProblem }) => {
+    const element = useRef(null);
+    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, 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;
+        let unmount;
+        try {
+            unmount = module.mount(host, {
+                // what does not fit never reaches a control that wrote its schema so as not to expect it
+                value: refusal === undefined ? shown : undefined,
+                onChange: (next) => {
+                    if (!isMounted)
+                        return;
+                    const change = checkedChange(module, next);
+                    if ("problem" in change)
+                        start.current.onProblem(CONTROL_STRINGS.controlValue(name, change.problem));
+                    else {
+                        start.current.onProblem(undefined);
+                        start.current.onAccepted(change.value);
+                    }
+                },
+                argType: told,
+                strings: words
+            });
+        }
+        catch (error) {
+            say(CONTROL_STRINGS.controlThrew(name, error instanceof Error ? error.message : String(error)));
+        }
+        return () => {
+            isMounted = false;
+            // after this commit: a control written in React cannot take its own root away while the shell's is rendering
+            queueMicrotask(() => {
+                try {
+                    if (typeof unmount === "function")
+                        unmount();
+                }
+                catch {
+                    // it is leaving: there is no field left to say so beside, and the next mount says what is still wrong
+                }
+            });
+        };
+    }, [module, name]);
+    return _jsx("div", { ref: element, className: "forgebook-custom-control", "data-control": name });
+};
+/** A loaded control, and what it last said. */
+const MountedControl = ({ module, prop, name, value, onValueChange }) => {
+    const [problem, setProblem] = useState(undefined);
+    const given = useRef(textOf(value));
+    // counts the changes from outside: each is a new mount, which reads the value of its moment
+    const [mounts, setMounts] = useState(0);
+    if (textOf(value) !== given.current) {
+        given.current = textOf(value);
+        setMounts(mounts + 1);
+    }
+    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 }))] }));
+};
+/**
+ * A custom control, or why there is none.
+ *
+ * @param props - the prop, the control's name, its value, and the catalogue's controls.
+ */
+export const CustomControl = ({ loaders, ...props }) => {
+    const [loaded, setLoaded] = useState(undefined);
+    useEffect(() => {
+        let isCurrent = true;
+        void loadControl(props.name, loaders).then((control) => {
+            if (isCurrent)
+                setLoaded(control);
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [props.name, loaders]);
+    if (loaded === undefined)
+        return null;
+    if (loaded.status === "failed") {
+        return (_jsx("p", { className: "forgebook-prop__description forgebook-prop__problem", role: "alert", children: loaded.message }));
+    }
+    return _jsx(MountedControl, { ...props, module: loaded.module });
+};

package/dist/src/shell/DocContainers.js

@@ -22,7 +22,7 @@ import { useSyncedTab } from "./useSyncedTab.js";
  */
 export const AsideBlock = ({ tone, title, children }) => {
     const id = useId();
-    return (_jsxs("aside", { className: "forgebook-aside", "data-tone": tone, "aria-labelledby": id, children: [_jsx("p", { id: id, className: "forgebook-aside__title", children: title ?? PAGE_STRINGS.asides[tone] }), children] }));
+    return (_jsxs("aside", { className: "forgebook-aside", role: "note", "data-tone": tone, "aria-labelledby": id, children: [_jsx("p", { id: id, className: "forgebook-aside__title", children: title ?? PAGE_STRINGS.asides[tone] }), children] }));
 };
 /**
  * The tab a key moves to in a tab list: the next or the one before, round the ends, or the first or the last.

package/dist/src/shell/DocPage.js

@@ -21,8 +21,8 @@ import { useCatalogue } from "./catalogueContext.js";
 import { blockPlaces, catalogueValues, DocBlocks, queuedBlocks } from "./DocBlocks.js";
 import { DocContents } from "./DocContents.js";
 import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { PAGE_STRINGS } from "./pageStrings.js";
-import { STRINGS } from "./strings.js";
 import { useAnchorScroll } from "./useAnchorScroll.js";
 import { useLoaded } from "./useLoaded.js";
 import { usePageFrames } from "./usePageFrames.js";
@@ -58,7 +58,7 @@ const PageFoot = ({ previous, next, hrefOf, onOpen }) => {
             event.preventDefault();
             onOpen(page.id);
         }, children: [_jsx("span", { className: "forgebook-docs__around-label", children: label }), _jsxs("span", { className: "forgebook-docs__around-name", children: [page.name, side === "next" ? _jsx(Icon, { name: "chevronRight", size: 12 }) : null] })] }));
-    return previous === undefined && next === undefined ? null : (_jsxs("nav", { className: "forgebook-docs__foot", "aria-label": STRINGS.docsNav, children: [link(previous, PAGE_STRINGS.previousPage, "previous"), link(next, PAGE_STRINGS.nextPage, "next")] }));
+    return previous === undefined && next === undefined ? null : (_jsxs("nav", { className: "forgebook-docs__foot", "aria-label": LATER_STRINGS.docsNav, children: [link(previous, PAGE_STRINGS.previousPage, "previous"), link(next, PAGE_STRINGS.nextPage, "next")] }));
 };
 /**
  * The page's width, followed as the window or the sidebar changes it.

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

@@ -15,8 +15,8 @@ import type { DroppedArg } from "../addressArgs.ts";
 export type DroppedArgsListProps = {
     /** The values left out. */
     readonly dropped: readonly DroppedArg[];
-    /** Removes them from the address. */
-    readonly onRemove: () => void;
+    /** Removes them from the address; none where nothing can rewrite it (an embed's is its author's). */
+    readonly onRemove?: () => void;
 };
 /**
  * The note.

package/dist/src/shell/DroppedArgsList.js

@@ -5,4 +5,4 @@ import { LATER_STRINGS } from "./laterStrings.js";
  *
  * @param props - the values left out and the remover.
  */
-export const DroppedArgsList = ({ dropped, onRemove }) => (_jsxs("div", { className: "forgebook-dropped-args", role: "status", children: [_jsx("p", { className: "forgebook-dropped-args__text", children: LATER_STRINGS.droppedArgs }), _jsx("ul", { className: "forgebook-dropped-args__list", children: dropped.map(({ name, reason }) => (_jsxs("li", { children: [_jsx("code", { children: name }), " ", LATER_STRINGS.droppedArgReasons[reason]] }, name))) }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: onRemove, children: LATER_STRINGS.removeDroppedArgs })] }));
+export const DroppedArgsList = ({ dropped, onRemove }) => (_jsxs("div", { className: "forgebook-dropped-args", role: "status", children: [_jsx("p", { className: "forgebook-dropped-args__text", children: LATER_STRINGS.droppedArgs }), _jsx("ul", { className: "forgebook-dropped-args__list", children: dropped.map(({ name, reason }) => (_jsxs("li", { children: [_jsx("code", { children: name }), " ", LATER_STRINGS.droppedArgReasons[reason]] }, name))) }), onRemove === undefined ? null : (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: onRemove, children: LATER_STRINGS.removeDroppedArgs }))] }));