forgebook 0.3.2 → 0.4.0

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/CodeTab.d.ts

@@ -1,11 +1,12 @@
 /**
  * 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.
  *
  * @module
  */
 import type { ReactNode } from "react";
-import { type StoryCodeSource } from "./StoryCodeBlock.tsx";
+import { type StoryCodeSource } from "../storyCodeText.ts";
 /** The tab's props: the story whose code it shows. */
 export type CodeTabProps = StoryCodeSource;
 /**

package/dist/src/shell/CodeTab.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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";
 /**
@@ -12,6 +13,6 @@ import { useCopy } from "./useCopy.js";
 export const CodeTab = (props) => {
     const { isCopied, copy } = useCopy();
     const write = useCodeWriter();
-    const hasRender = props.code[props.exportName] !== undefined;
+    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,5 +1,5 @@
 /**
- * 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.
  *

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,7 @@ import { Example } from "./Example.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { LazyView, lazyModule } from "./lazyModule.js";
 import { PackageHtml } from "./PackageHtml.js";
+import { PageTagView } from "./pageTagView.js";
 import { UsedIn } from "./UsedIn.js";
 import { useComponentDocs } from "./useComponentDocs.js";
 import { usePageDoc } from "./usePageDoc.js";
@@ -97,6 +99,8 @@ export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouch
     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 +163,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: [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}`) })] }));
 };

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,132 @@
+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, useRef, useState } from "react";
+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 })
+});
+/** 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, onAccepted, onProblem }) => {
+    const element = useRef(null);
+    const start = useRef({ value, argType, onAccepted, onProblem });
+    start.current = { value, argType, onAccepted, onProblem };
+    useEffect(() => {
+        const host = element.current;
+        if (host === null)
+            return;
+        const { value: shown, argType: told, 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
+            });
+        }
+        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 = argTypeOf(prop);
+    return (_jsxs(_Fragment, { children: [_jsx(ControlRoom, { module: module, name: name, value: value, argType: argType, 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 }))] }));

package/dist/src/shell/EmbedPage.js

@@ -15,24 +15,33 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import "./embed.css";
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { addressArgsFor } from "../addressTexts.js";
+import { checkedArgsMessage } from "../addressArgs.js";
+import { readArgsParam, readStorybookLink } from "../addressArgsParam.js";
+import { addressArgsRead } from "../addressTexts.js";
 import { EMBED_SIZE_TYPE } from "../embed.js";
-import { parsePanelArgsParam } from "../messages.js";
+import { sourceFiles } from "../sourceFiles.js";
 import { storyBackground } from "../storyBackground.js";
 import { NOT_FIXED, withFixed } from "../storyGlobals.js";
-import { findStory, storyTree } from "../storyTree.js";
+import { findStory, storyOfAddress, storyTree } from "../storyTree.js";
 import { frameAddress, parseView, STAGE_HEIGHT_RANGE } from "../viewState.js";
 import { CatalogueContext, useCatalogue, useConfiguredCatalogue } from "./catalogueContext.js";
+import { DroppedArgsNote } from "./DroppedArgsNote.js";
 import { FrameView } from "./FrameView.js";
 import { framesOrigin } from "./framesOrigin.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { shellIsDark } from "./shellScheme.js";
 import { STRINGS } from "./strings.js";
+import { useAddressArgs } from "./useAddressArgs.js";
 import { APPEARANCE_ATTRIBUTE } from "./useAppearance.js";
 import { useFrameMessages } from "./useFrameMessages.js";
+import { usePanelDocs } from "./usePanelDocs.js";
 import { useSystemDark } from "./useSystemDark.js";
 /** The height of the frame before its story reports its own, in CSS px, in a page with no height of its own yet. */
 const WAITING_HEIGHT = 240;
+/** No actions, before the frame reported its own. */
+const NO_ACTIONS = [];
+/** No `argTypes`, before the frame reported its own. */
+const NO_ARG_TYPES = {};
 /**
  * Tells the page around the embed how tall the story is.
  *
@@ -98,17 +107,37 @@ const EmbedNotice = ({ message, detail, isFailure }) => {
  *
  * @param props - the story, the view, its args and the frame page.
  */
-const EmbedStory = ({ location, view, panelArgs, frameUrl }) => {
+const EmbedStory = ({ location, view, panelArgs, link, loadDocs, namedValues, argControls, frameUrl }) => {
     const catalogue = useCatalogue();
     const { story, component, source } = location;
     const [fixed, setFixed] = useState(NOT_FIXED);
     const [failure, setFailure] = useState(undefined);
+    const [ready, setReady] = useState(undefined);
+    const storyRef = useRef(null);
+    const note = useRef(null);
+    // the docs only serve the check: an embed whose address names no value does not load them
+    const hasValues = Object.keys(panelArgs).length > 0 || link?.refused !== undefined;
+    const docs = usePanelDocs(hasValues ? loadDocs : undefined, component.name, ready?.args, ready?.actions ?? NO_ACTIONS);
+    // whoever embeds the story writes its address, as whoever shares a link does: the same check applies
+    const addressArgs = useAddressArgs({
+        panelArgs,
+        link,
+        docs,
+        storyArgs: ready?.args,
+        argTypes: ready?.argTypes ?? NO_ARG_TYPES,
+        controls: ready?.controls ?? "all",
+        namedValues,
+        argControls,
+        frames: storyRef
+    });
     const { heights, settled } = useFrameMessages({
         onReady: (frame, message) => {
             setFixed(message.fixed);
             setFailure(undefined);
-            const args = { type: "forgebook:args", args: panelArgs };
-            frame.postMessage(args, framesOrigin());
+            setReady(message);
+            const accepted = addressArgs.acceptedFor(message);
+            if (accepted !== undefined)
+                frame.postMessage(checkedArgsMessage(accepted), framesOrigin());
         },
         onCall: () => undefined,
         onFailed: (_storyId, message) => setFailure(message)
@@ -132,37 +161,52 @@ const EmbedStory = ({ location, view, panelArgs, frameUrl }) => {
     const reported = settled.has(address) ? heights.get(address) : undefined;
     const fixedHeight = heightSet(shownView, reported);
     const ownHeight = fixedHeight ?? (reported === undefined ? undefined : Math.max(reported, story.height ?? 0));
-    useHostHeight(failure === undefined ? ownHeight : undefined);
+    // the note sits above the frame and takes nothing from it: the page around the embed grows by the note
+    const noteHeight = useElementHeight(note) ?? 0;
+    useHostHeight(failure === undefined && ownHeight !== undefined ? ownHeight + noteHeight : undefined);
     return (_jsxs("main", { className: "forgebook-embed", style: {
             backgroundColor: storyBackground(source.background, shownView, catalogue, isSystemDark)
-        }, children: [failure === undefined ? null : (_jsx(EmbedNotice, { message: STRINGS.embedFailed, detail: failure, isFailure: true })), _jsx("div", { className: "forgebook-embed__story", hidden: failure !== undefined, style: { width: shownView.width === "fill" ? undefined : shownView.width }, children: _jsx(FrameView, { title: STRINGS.frameTitle(component.name, story.name), address: address, heights: heights, settled: settled, fallbackHeight: WAITING_HEIGHT, sceneHeight: Math.max(story.height ?? 0, windowHeight), fixedHeight: fixedHeight }) })] }));
+        }, children: [failure === undefined ? null : (_jsx(EmbedNotice, { message: STRINGS.embedFailed, detail: failure, isFailure: true })), _jsx("div", { ref: note, children: _jsx(DroppedArgsNote, { dropped: addressArgs.dropped }) }), _jsx("div", { ref: storyRef, className: "forgebook-embed__story", hidden: failure !== undefined, style: { width: shownView.width === "fill" ? undefined : shownView.width }, children: _jsx(FrameView, { title: STRINGS.frameTitle(component.name, story.name), address: address, heights: heights, settled: settled, fallbackHeight: WAITING_HEIGHT, 
+                    // the window follows the page's height, note included: counted here, the frame would grow with each answer
+                    sceneHeight: Math.max(story.height ?? 0, windowHeight - noteHeight), fixedHeight: fixedHeight }) })] }));
 };
 /**
  * The page: the story the address names, or why there is none.
  *
  * @param props - the catalogue's name, its sources, its frame page, and how its stories take the address's texts.
  */
-const EmbedContent = ({ title, sources, frameUrl, addressTexts }) => {
+const EmbedContent = ({ title, sources, frameUrl, argControls, addressTexts }) => {
     const catalogue = useCatalogue();
     const tree = useMemo(() => storyTree(sources), [sources]);
     // the address is read once: an embed has nowhere to go, so nothing rewrites it
     const [params] = useState(() => new URLSearchParams(window.location.search));
-    const storyId = params.get("story");
+    const storyId = storyOfAddress(params);
     const location = storyId === null ? undefined : findStory(tree, storyId);
     const name = location?.component.name;
+    const [read, setRead] = useState(() => readArgsParam(params.get("args")));
+    const waiting = read.link?.isWaiting === true ? read.link.param : undefined;
+    useEffect(() => {
+        if (waiting === undefined)
+            return;
+        void readStorybookLink(waiting, ({ readStorybookArgs }, param) => readStorybookArgs(param)).then(setRead);
+    }, [waiting]);
+    // one object for as long as the address is read: the check is not run again for each render
+    const { panelArgs, link } = useMemo(() => addressArgsRead(read, params.get("args"), addressTexts), [read, params, addressTexts]);
     useEffect(() => {
         document.title = name === undefined ? title : `${name} · ${title}`;
     }, [name, title]);
     if (location === undefined) {
         return (_jsx("main", { className: "forgebook-embed", children: _jsx(EmbedNotice, { message: storyId === null ? LATER_STRINGS.embedNoStory : LATER_STRINGS.embedUnknownStory(storyId) }) }));
     }
-    return (_jsx(EmbedStory, { location: location, view: parseView(params.toString(), catalogue), 
-        // whoever embeds the story writes its address, as whoever shares a link does: the same rule applies
-        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts), frameUrl: frameUrl }));
+    // the values are known before the frame starts, so it is told them once
+    if (waiting !== undefined)
+        return null;
+    const source = sources.find((each) => each.id === location.source.id);
+    return (_jsx(EmbedStory, { location: location, view: parseView(params.toString(), catalogue), link: link, panelArgs: panelArgs, loadDocs: source === undefined ? undefined : sourceFiles(source).docs[location.story.file], namedValues: source?.namedValues, argControls: argControls, frameUrl: frameUrl }));
 };
 /**
  * One story alone, inside the catalogue's settings.
  *
  * @param props - the catalogue's configuration.
  */
-export const EmbedPage = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(EmbedContent, { title: props.title, sources: props.sources, frameUrl: props.frameUrl, addressTexts: props.addressTexts ?? "any" }) }));
+export const EmbedPage = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(EmbedContent, { title: props.title, sources: props.sources, frameUrl: props.frameUrl, ...(props.argControls === undefined ? {} : { argControls: props.argControls }), addressTexts: props.addressTexts ?? "any" }) }));

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

@@ -21,6 +21,8 @@ export type ExampleReading = {
     /** Whether the demo is drawn larger, with more room around it. */
     readonly isDemoLarge: boolean;
 };
+/** The heading an example's title is: the level under the heading above it, so no level is skipped. */
+type ExampleTitleTag = "h3" | "h4";
 /** What every example of the page shares: the frames' address, view and reports, the code, how to open a story. */
 export type ExampleContext = {
     /** The component. */
@@ -73,9 +75,11 @@ export declare const StoryLink: ({ story, hrefOf, onOpen, className, label, chil
  * @param props - the story, whether it is the demo, whether its frame may load, where the queue watches it, and what
  * every example shares.
  */
-export declare const Example: ({ story, isDemo, isMounted, observe, ...context }: ExampleContext & {
+export declare const Example: ({ story, isDemo, titleTag, isMounted, observe, ...context }: ExampleContext & {
     readonly story: TreeStory;
     readonly isDemo: boolean;
+    readonly titleTag?: ExampleTitleTag;
     readonly isMounted: boolean;
     readonly observe?: (element: HTMLElement | null) => void;
 }) => ReactNode;
+export {};