forgebook 0.3.3 → 0.4.0

package/dist/src/shell/Example.js

@@ -1,6 +1,8 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useState } from "react";
 import { deviceDefaultOf, shownDevice } from "../deviceView.js";
+import { storyCodeText } from "../storyCodeText.js";
+import { isFilterTag } from "../storyTagNames.js";
 import { frameAddress, schemeOf } from "../viewState.js";
 import { BoxWidthControl, useBoxWidth } from "./BoxWidth.js";
 import { CodeText } from "./CodeText.js";
@@ -10,8 +12,9 @@ import { DeviceSlot, deviceAddress, inkScheme, isWaitingForDevice, roomSizing, u
 import { FrameView } from "./FrameView.js";
 import { Icon } from "./icons.js";
 import { LATER_STRINGS } from "./laterStrings.js";
+import { PageTagView } from "./pageTagView.js";
 import { StageViewport } from "./StageViewport.js";
-import { StoryCodeBlock, storyCodeText } from "./StoryCodeBlock.js";
+import { StoryCodeBlock } from "./StoryCodeBlock.js";
 import { touchedView } from "./storyTouch.js";
 import { STRINGS } from "./strings.js";
 import { useCopy } from "./useCopy.js";
@@ -39,7 +42,12 @@ export const StoryLink = ({ story, hrefOf, onOpen, className, label, children })
 const ExampleCode = ({ id, source, isShown }) => {
     const { isCopied, copy } = useCopy();
     const write = useCodeWriter();
-    return (_jsx("div", { id: id, className: "forgebook-example__code", "data-open": isShown ? "" : undefined, inert: !isShown, children: _jsxs("div", { className: "forgebook-example__code-inner", children: [_jsx("button", { type: "button", className: "forgebook-example__copy", onClick: () => copy(storyCodeText(source, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : LATER_STRINGS.copy }), _jsx(StoryCodeBlock, { ...source })] }) }));
+    // a page of fifty stories would hold fifty coloured blocks nobody opened: the code is written when first shown, then
+    // kept, so closing it plays the same transition as opening it
+    const [wasShown, setWasShown] = useState(isShown);
+    if (isShown && !wasShown)
+        setWasShown(true);
+    return (_jsx("div", { id: id, className: "forgebook-example__code", "data-open": isShown ? "" : undefined, inert: !isShown, children: _jsx("div", { className: "forgebook-example__code-inner", children: wasShown || isShown ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "forgebook-example__copy", onClick: () => copy(storyCodeText(source, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : LATER_STRINGS.copy }), _jsx(StoryCodeBlock, { ...source })] })) : null }) }));
 };
 /**
  * The height an example's story is drawn at least at: its scene's, and over the page the room its stage has.
@@ -49,11 +57,11 @@ const ExampleCode = ({ id, source, isShown }) => {
  */
 const sceneHeightOf = (story, stageHeight) => stageHeight === undefined ? story.height : Math.max(story.height ?? 0, stageHeight);
 /**
- * An example's title, a link to its story's page, and its description.
+ * An example's title, a link to its story's page with the statuses the story holds of its own, and its description.
  *
  * @param props - the story and how its link opens it.
  */
-const ExampleHead = ({ story, context }) => (_jsxs("header", { className: "forgebook-example__head", children: [_jsx("h4", { className: "forgebook-example__title", children: _jsx(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-link", children: story.name }) }), story.description === undefined ? null : (_jsx("p", { className: "forgebook-example__description", children: _jsx(CodeText, { text: story.description }) }))] }));
+const ExampleHead = ({ story, titleTag: Title, context }) => (_jsxs("header", { className: "forgebook-example__head", children: [_jsxs(Title, { className: "forgebook-example__title", children: [_jsx(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-link", children: story.name }), story.tags.some(isFilterTag) ? (_jsx(PageTagView, { place: "story", story: story, component: context.component })) : null] }), story.description === undefined ? null : (_jsx("p", { className: "forgebook-example__description", children: _jsx(CodeText, { text: story.description }) }))] }));
 /**
  * What keeps an example's place while its box is over the page: a slot of its height in the list, and the shade
  * under the box, a press on which brings it back.
@@ -137,17 +145,17 @@ const exampleHeights = (story, context, isDemo) => {
  * @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 const Example = ({ story, isDemo, isMounted, observe, ...context }) => {
+export const Example = ({ story, isDemo, titleTag = "h3", isMounted, observe, ...context }) => {
     const { source, hasCode, isCodeShown, setIsCodeShown } = useExampleCode(story, context);
     const codeId = useId();
     const full = useFullPage();
     const { touch } = useCatalogue();
     const { shown, framed, scheme } = useExampleDevice(story, context);
     // the frame loads with the story's finger as it is then; a change after reaches it live, keeping the story's state
-    const loadedView = useLoadedView(context.frameView.sheets, touchedView(context.frameView, story.id, context.touches, touch));
+    const loadedView = useLoadedView(`${context.frameView.sheets}|${context.frameView.play}`, touchedView(context.frameView, story.id, context.touches, touch));
     const boxWidth = useBoxWidth(full.isOver, context.view.width);
     const { fallback: fallbackHeight, least: leastHeight } = exampleHeights(story, context, isDemo);
-    return (_jsxs("article", { ref: observe, className: "forgebook-example", "data-demo": isDemo ? "" : undefined, "aria-label": isDemo ? STRINGS.frameTitle(context.component.name, story.name) : story.name, children: [isDemo ? null : _jsx(ExampleHead, { story: story, context: context }), full.isOver ? _jsx(FullPageSlot, { full: full }) : null, _jsxs("div", { ref: full.boxRef, className: "forgebook-example__box", "data-full": full.isOver ? "" : undefined, ...(full.isFull ? { role: "dialog", "aria-label": story.name } : {}), children: [_jsx("div", { ref: full.stageRef, className: "forgebook-example__stage", children: _jsx(StageViewport, { ...roomSizing(framed, {
+    return (_jsxs("article", { ref: observe, className: "forgebook-example", "data-demo": isDemo ? "" : undefined, "aria-label": isDemo ? STRINGS.frameTitle(context.component.name, story.name) : story.name, children: [isDemo ? null : _jsx(ExampleHead, { story: story, titleTag: titleTag, context: context }), full.isOver ? _jsx(FullPageSlot, { full: full }) : null, _jsxs("div", { ref: full.boxRef, className: "forgebook-example__box", "data-full": full.isOver ? "" : undefined, ...(full.isFull ? { role: "dialog", "aria-label": story.name } : {}), children: [_jsx("div", { ref: full.stageRef, className: "forgebook-example__stage", children: _jsx(StageViewport, { ...roomSizing(framed, {
                                 width: boxWidth.width,
                                 onWidthChange: boxWidth.onWidthChange,
                                 onShownWidthChange: boxWidth.onShownWidthChange,

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

@@ -29,8 +29,11 @@ export type FrameViewProps = {
     readonly fixedHeight?: number | undefined;
     /** The addresses of the frames that finished loading: until its own is there, the frame shows that it loads. */
     readonly settled: ReadonlySet<string>;
-    /** The iframe. */
-    readonly ref?: Ref<HTMLIFrameElement>;
+    /**
+     * The ref the iframe is given. A prop of its own rather than `ref`: the shell runs on the project's React, and React 18
+     * passes no `ref` to a function component. Short, as every byte of the shell's first load counts.
+     */
+    readonly frame?: Ref<HTMLIFrameElement>;
 };
 /**
  * A story's frame, as tall as its story.
@@ -38,7 +41,7 @@ export type FrameViewProps = {
  * @param props - the frame's title, address, the reported heights, the height until its own arrives, and the frames
  * that finished loading.
  */
-export declare const FrameView: ({ title, address, heights, fallbackHeight, settled, sceneHeight, fixedHeight, ref }: FrameViewProps) => ReactNode;
+export declare const FrameView: ({ title, address, heights, fallbackHeight, settled, sceneHeight, fixedHeight, frame }: FrameViewProps) => ReactNode;
 /**
  * Sends a message to every frame inside an element.
  *

package/dist/src/shell/FrameView.js

@@ -7,14 +7,14 @@ import { STRINGS } from "./strings.js";
  * @param props - the frame's title, address, the reported heights, the height until its own arrives, and the frames
  * that finished loading.
  */
-export const FrameView = ({ title, address, heights, fallbackHeight, settled, sceneHeight = 0, fixedHeight, ref }) => {
+export const FrameView = ({ title, address, heights, fallbackHeight, settled, sceneHeight = 0, fixedHeight, frame }) => {
     const isLoading = !settled.has(address);
     // while it loads, an empty document reports a height of nothing: the box keeps its waiting height until the story
     // is there, then takes the story's
     const reported = heights.get(address);
     const contentHeight = isLoading ? Math.max(reported ?? 0, fallbackHeight) : (reported ?? fallbackHeight);
     const height = fixedHeight ?? Math.max(contentHeight, sceneHeight);
-    return (_jsxs("div", { className: "forgebook-frame-box", "data-loading": isLoading ? "" : undefined, children: [_jsx("iframe", { ref: ref, className: "forgebook-frame-view", title: title, src: address, ...storyFrameAttributes(), style: { height } }), isLoading ? (_jsx("div", { className: "forgebook-frame-loading", role: "status", children: _jsxs("span", { className: "forgebook-frame-loading__label", children: [_jsx("span", { className: "forgebook-spinner", "aria-hidden": "true" }), STRINGS.loadingStory] }) })) : null] }));
+    return (_jsxs("div", { className: "forgebook-frame-box", "data-loading": isLoading ? "" : undefined, children: [_jsx("iframe", { ref: frame, className: "forgebook-frame-view", title: title, src: address, ...storyFrameAttributes(), style: { height } }), isLoading ? (_jsx("div", { className: "forgebook-frame-loading", role: "status", children: _jsxs("span", { className: "forgebook-frame-loading__label", children: [_jsx("span", { className: "forgebook-spinner", "aria-hidden": "true" }), STRINGS.loadingStory] }) })) : null] }));
 };
 /**
  * Sends a message to every frame inside an element.

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

@@ -21,6 +21,8 @@ export type HomePageProps = {
     readonly tree: StoryTree;
     /** The sources, for their introductions. */
     readonly sources: readonly StorySource[];
+    /** The catalogue's own story patterns, for a home with no story to say where it looks; none by default. */
+    readonly storyGlobs?: readonly string[] | undefined;
     /** The pages opened last, the newest first. */
     readonly recent: readonly RecentPage[];
     /** A page's address, for its link. */
@@ -109,5 +111,5 @@ export declare const LibrarySection: ({ source, sources, hrefOf, onOpen }: Pick<
  *
  * @param props - the title, the tree, the sources, the recent pages, and how to open a page.
  */
-export declare const HomePage: ({ title, tree, sources, recent, hrefOf, onOpen, header }: HomePageProps) => ReactNode;
+export declare const HomePage: ({ title, tree, sources, storyGlobs, recent, hrefOf, onOpen, header }: HomePageProps) => ReactNode;
 export {};

package/dist/src/shell/HomePage.js

@@ -2,12 +2,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { findPage } from "../pageTree.js";
 import { findComponent, findStory } from "../storyTree.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { PackageHtml } from "./PackageHtml.js";
 import { PAGE_STRINGS } from "./pageStrings.js";
-import { STRINGS } from "./strings.js";
 import { useLoaded } from "./useLoaded.js";
 /** The most components a family's card lists before "Show all". */
 const CARD_COMPONENTS = 6;
+/**
+ * What the home says before the first story: where the catalogue looks, and how to write one.
+ *
+ * @param props - the catalogue's story patterns.
+ */
+const NoStoryYet = ({ globs }) => (_jsxs("section", { className: "forgebook-home__no-story", "data-testid": "forgebook-no-story", children: [_jsx("p", { children: PAGE_STRINGS.homeNoStoryLead }), _jsx("ul", { children: globs.map((glob) => (_jsx("li", { children: _jsx("code", { children: glob }) }, glob))) }), _jsx("p", { children: PAGE_STRINGS.homeNoStoryHelp }), _jsx("pre", { children: _jsx("code", { children: PAGE_STRINGS.homeNoStoryCommand }) })] }));
 /** A link to a page, opened in place unless the user asks for another tab. */
 export const PageLink = ({ page, hrefOf, onOpen, className, children }) => (_jsx("a", { className: className, href: hrefOf(page), onClick: (event) => {
         if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
@@ -83,7 +89,7 @@ export const FamilyCard = ({ family, hrefOf, onOpen }) => {
  *
  * @param props - the source, and how to open a page.
  */
-export const DocsCard = ({ source, hrefOf, onOpen }) => (_jsxs("article", { className: "forgebook-home__card", "aria-label": STRINGS.docsNav, children: [_jsx("h3", { className: "forgebook-home__card-title", children: STRINGS.docsNav }), _jsx("ul", { className: "forgebook-home__components", children: source.pages.map((page) => (_jsx("li", { children: _jsx(PageLink, { page: { kind: "page", id: page.id }, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: page.name }) }, page.id))) })] }));
+export const DocsCard = ({ source, hrefOf, onOpen }) => (_jsxs("article", { className: "forgebook-home__card", "aria-label": LATER_STRINGS.docsNav, children: [_jsx("h3", { className: "forgebook-home__card-title", children: LATER_STRINGS.docsNav }), _jsx("ul", { className: "forgebook-home__components", children: source.pages.map((page) => (_jsx("li", { children: _jsx(PageLink, { page: { kind: "page", id: page.id }, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: page.name }) }, page.id))) })] }));
 /**
  * How many components a tree has, in every library.
  *
@@ -117,8 +123,12 @@ export const LibrarySection = ({ source, sources, hrefOf, onOpen }) => (_jsxs("s
  *
  * @param props - the title, the tree, the sources, the recent pages, and how to open a page.
  */
-export const HomePage = ({ title, tree, sources, recent, hrefOf, onOpen, header }) => {
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-home", children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsx("p", { className: "forgebook-doc__lead", children: tree.sources.length === 0
-                                        ? PAGE_STRINGS.homeEmpty
-                                        : PAGE_STRINGS.homeSummary(componentCount(tree), libraryCount(tree)) })] }), _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen }), tree.sources.map((source) => (_jsx(LibrarySection, { source: source, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, source.id)))] }) })] }));
+export const HomePage = ({ title, tree, sources, storyGlobs = [], recent, hrefOf, onOpen, header }) => {
+    // a catalogue that names patterns and lists nothing is one about to get its first story: a build never gets here, since
+    // it stops on a pattern that matches nothing
+    const listingGlobs = storyGlobs.filter((glob) => !glob.startsWith("!") || glob.startsWith("!("));
+    const isWaiting = listingGlobs.length > 0 && componentCount(tree) === 0;
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-home", children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsxs("p", { className: "forgebook-doc__lead", children: [isWaiting ? PAGE_STRINGS.homeNoStoryTitle : null, !isWaiting && tree.sources.length === 0 ? PAGE_STRINGS.homeEmpty : null, !isWaiting && tree.sources.length > 0
+                                            ? PAGE_STRINGS.homeSummary(componentCount(tree), libraryCount(tree))
+                                            : null] })] }), isWaiting ? _jsx(NoStoryYet, { globs: listingGlobs }) : null, _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen }), tree.sources.map((source) => (_jsx(LibrarySection, { source: source, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, source.id)))] }) })] }));
 };

package/dist/src/shell/InfoTip.js

@@ -11,7 +11,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  */
 import { useId, useRef } from "react";
 import { Icon } from "./icons.js";
-import { STRINGS } from "./strings.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 /** The room kept between the note, its button and the window's edges, in CSS px. */
 const GAP_PX = 6;
 /**
@@ -40,7 +40,7 @@ export const InfoTip = ({ note, about }) => {
         if (noteRef.current?.matches(":popover-open") === true)
             noteRef.current.hidePopover();
     };
-    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: buttonRef, type: "button", className: "forgebook-info-tip", "aria-label": STRINGS.aboutControl(about), "aria-describedby": noteId, 
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: buttonRef, type: "button", className: "forgebook-info-tip", "aria-label": LATER_STRINGS.aboutControl(about), "aria-describedby": noteId, 
                 // its own note is its tooltip: an empty title keeps a parent's (a pinned control's key) from showing over it
                 title: "", onPointerEnter: show, onPointerLeave: hide, onFocus: show, onBlur: hide, onKeyDown: (event) => {
                     // an open note takes the first Escape; the menu around it, the next

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

@@ -1,21 +1,28 @@
 /**
  * The panel's Interactions tab: the story's play function as it ran, whether it passed or where it failed, each step
- * it named with `step`, and a button that runs it again on a fresh mount.
+ * it named with `step`, each action it took through its context's tools, a button that runs it again on a fresh mount,
+ * and a debugger that stops it before each action.
  *
  * @module
  */
 import type { ReactNode } from "react";
+import type { PlayStepCommand } from "../messages.ts";
 import type { PlayTrace } from "../playTrace.ts";
+import type { ViewState } from "../viewState.ts";
 /** The tab's props. */
 export type InteractionsTabProps = {
     /** The play's trace. */
     readonly trace: PlayTrace;
-    /** Runs the play again on a fresh mount. */
-    readonly onPlayAgain: () => void;
+    /** Runs the play again on a fresh mount, or steps through it. */
+    readonly onPlayStep: (command: PlayStepCommand) => void;
+    /** The view, whose play switch it shows. */
+    readonly view: ViewState;
+    /** Changes the view. */
+    readonly onViewChange: (view: ViewState) => void;
 };
 /**
  * The Interactions tab.
  *
  * @param props - the trace and how to run the play again.
  */
-export declare const InteractionsTab: ({ trace, onPlayAgain }: InteractionsTabProps) => ReactNode;
+export declare const InteractionsTab: (props: InteractionsTabProps) => ReactNode;

package/dist/src/shell/InteractionsTab.js

@@ -1,11 +1,27 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCatalogue } from "./catalogueContext.js";
 import { LATER_STRINGS } from "./laterStrings.js";
+import { rememberPlay } from "./playMemory.js";
 import { STRINGS } from "./strings.js";
 /** A status with its time, as a line ends. */
 const StatusNote = ({ status, ms }) => (_jsxs("span", { className: "forgebook-play__status", "data-status": status, children: [STRINGS.playStatus[status], ms === undefined ? null : ` · ${LATER_STRINGS.playTime(ms)}`] }));
+/** Actions, in order; nothing when there are none. */
+const ActionList = ({ actions }) => actions.length === 0 ? null : (_jsx("ol", { className: "forgebook-play__actions", children: actions.map((action, index) => (_jsxs("li", { className: "forgebook-play__action", "data-status": action.status, children: [_jsx("code", { className: "forgebook-play__label", children: action.label }), _jsx(StatusNote, { status: action.status, ms: action.ms }), action.error === undefined ? null : _jsx("p", { className: "forgebook-play__error", children: action.error })] }, index))) }));
+/** The buttons that run the play: to its end, or one action at a time. */
+const PlayButtons = ({ trace, onPlayStep }) => trace.pausedAt === undefined ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "forgebook-button", disabled: trace.status === "running", onClick: () => onPlayStep("start"), children: LATER_STRINGS.playStepThrough }), _jsx("button", { type: "button", className: "forgebook-button", disabled: trace.status === "running", onClick: () => onPlayStep("again"), children: trace.status === "off" ? LATER_STRINGS.playRun : LATER_STRINGS.playAgain })] })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "forgebook-button", onClick: () => onPlayStep("next"), children: LATER_STRINGS.playNext }), _jsx("button", { type: "button", className: "forgebook-button", onClick: () => onPlayStep("continue"), children: LATER_STRINGS.playContinue })] }));
 /**
  * The Interactions tab.
  *
  * @param props - the trace and how to run the play again.
  */
-export const InteractionsTab = ({ trace, onPlayAgain }) => (_jsxs("div", { className: "forgebook-prop-group", "aria-live": "polite", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsxs("h3", { className: "forgebook-prop-group__title", children: [LATER_STRINGS.playTitle, " ", _jsx(StatusNote, { status: trace.status, ms: trace.ms })] }), _jsx("button", { type: "button", className: "forgebook-button", disabled: trace.status === "running", onClick: onPlayAgain, children: LATER_STRINGS.playAgain })] }), trace.error === undefined ? null : (_jsx("p", { className: "forgebook-problems", role: "alert", children: trace.error })), trace.steps.length === 0 ? (_jsx("p", { className: "forgebook-prop__description", children: LATER_STRINGS.playNoSteps })) : (_jsx("ol", { className: "forgebook-play__steps", children: trace.steps.map((step, index) => (_jsxs("li", { className: "forgebook-play__step", "data-status": step.status, children: [_jsx("span", { className: "forgebook-play__label", children: step.label }), _jsx(StatusNote, { status: step.status, ms: step.ms }), step.error === undefined ? null : _jsx("p", { className: "forgebook-play__error", children: step.error })] }, index))) }))] }));
+export const InteractionsTab = (props) => {
+    const { trace, view, onViewChange } = props;
+    const catalogue = useCatalogue();
+    const actions = trace.actions ?? [];
+    const outside = actions.filter((action) => action.step === undefined);
+    return (_jsxs("div", { className: "forgebook-prop-group", "aria-live": "polite", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsxs("h3", { className: "forgebook-prop-group__title", children: [LATER_STRINGS.playTitle, " ", _jsx(StatusNote, { status: trace.status, ms: trace.ms })] }), _jsx("div", { className: "forgebook-play__buttons", children: _jsx(PlayButtons, { ...props }) })] }), _jsxs("label", { className: "forgebook-play__switch", children: [_jsx("input", { type: "checkbox", checked: view.play === "on", onChange: (event) => {
+                            const play = event.target.checked ? "on" : "off";
+                            rememberPlay(catalogue, play);
+                            onViewChange({ ...view, play });
+                        } }), LATER_STRINGS.playOnOpen] }), trace.pausedAt === undefined ? null : (_jsx("p", { className: "forgebook-play__paused", role: "status", children: LATER_STRINGS.playPaused(trace.pausedAt) })), trace.error === undefined ? null : (_jsx("p", { className: "forgebook-problems", role: "alert", children: trace.error })), trace.steps.length === 0 && actions.length === 0 ? (_jsx("p", { className: "forgebook-prop__description", children: trace.status === "off" ? LATER_STRINGS.playOff : LATER_STRINGS.playNoSteps })) : null, trace.steps.length === 0 ? null : (_jsx("ol", { className: "forgebook-play__steps", children: trace.steps.map((step, index) => (_jsxs("li", { className: "forgebook-play__step", "data-status": step.status, children: [_jsx("span", { className: "forgebook-play__label", children: step.label }), _jsx(StatusNote, { status: step.status, ms: step.ms }), step.error === undefined ? null : _jsx("p", { className: "forgebook-play__error", children: step.error }), _jsx(ActionList, { actions: actions.filter((action) => action.step === index) })] }, index))) })), _jsx(ActionList, { actions: outside }), actions.length === 0 ? (_jsx("p", { className: "forgebook-prop__description", children: LATER_STRINGS.playActionsNote })) : null] }));
+};

package/dist/src/shell/LazyPage.js

@@ -6,4 +6,4 @@ import { STRINGS } from "./strings.js";
  *
  * @param props - the page's module, its own props and the header.
  */
-export const LazyPage = ({ module, pageProps, header }) => (_jsx(LazyView, { module: module, props: pageProps, loading: _jsx("div", { className: "forgebook-workspace", "aria-busy": "true", children: header }), failed: (message) => (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.pageLoadError, ": ", message] })] })) }));
+export const LazyPage = ({ module, pageProps, header }) => (_jsx(LazyView, { module: module, props: pageProps, loading: _jsx("div", { className: "forgebook-workspace", "aria-busy": "true", children: header }), failed: (message) => (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.pageLoadError, ". ", message] })] })) }));

package/dist/src/shell/PackageHtml.js

@@ -1,12 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { useScrollStops } from "./useScrollStops.js";
 /**
  * The package's HTML, as trusted as its stories' code: it comes from the package's own files, read at build time.
  *
  * @param props - the element's class and the HTML.
  */
 export const PackageHtml = ({ className, html }) => {
+    const rootRef = useScrollStops("pre", html);
     // biome-ignore lint/style/useNamingConvention: React's own name for markup set as HTML
     const markup = { __html: html };
     // biome-ignore lint/security/noDangerouslySetInnerHtml: the package's own Markdown, rendered by the plugin
-    return _jsx("div", { className: className, dangerouslySetInnerHTML: markup });
+    return _jsx("div", { ref: rootRef, className: className, dangerouslySetInnerHTML: markup });
 };

package/dist/src/shell/PinnedControl.js

@@ -6,70 +6,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * @module
  */
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useCallback, useState } from "react";
 import { controlLabel } from "./controlLabel.js";
-import { InfoTip } from "./InfoTip.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 import { STRINGS } from "./strings.js";
 import { ToolbarControl } from "./ToolbarControl.js";
-/** The room the menu keeps from the window's edges, in CSS px. */
-const EDGE_PX = 8;
-/**
- * The control's menu: its two choices as menu items, the first focused, the arrow keys between them; closed by a
- * choice, a press outside or Escape, the focus going back where it was.
- *
- * @param props - the control, where the menu opens, what its choices do, and what closing it does.
- */
-const ControlMenu = ({ control, isHidden, at, layout, onClose }) => {
-    const menuRef = useRef(null);
-    // the menu stays inside the window: opened near its right or lower edge, it moves back by what would run past
-    useLayoutEffect(() => {
-        const menu = menuRef.current;
-        if (menu === null)
-            return;
-        const box = menu.getBoundingClientRect();
-        menu.style.left = `${Math.max(EDGE_PX, Math.min(at.x, window.innerWidth - box.width - EDGE_PX))}px`;
-        menu.style.top = `${Math.max(EDGE_PX, Math.min(at.y, window.innerHeight - box.height - EDGE_PX))}px`;
-    }, [at]);
-    useEffect(() => {
-        const before = document.activeElement;
-        menuRef.current?.querySelector("[role=menuitem]")?.focus();
-        const close = (event) => {
-            const isOutside = event instanceof PointerEvent &&
-                !(event.target instanceof Node && menuRef.current?.contains(event.target));
-            const isEscape = event instanceof KeyboardEvent && event.key === "Escape";
-            if (!isOutside && !isEscape)
-                return;
-            onClose();
-            if (isEscape && before instanceof HTMLElement)
-                before.focus();
-        };
-        document.addEventListener("pointerdown", close);
-        document.addEventListener("keydown", close);
-        return () => {
-            document.removeEventListener("pointerdown", close);
-            document.removeEventListener("keydown", close);
-        };
-    }, [onClose]);
-    const step = (event) => {
-        if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
-            return;
-        event.preventDefault();
-        const items = [...(menuRef.current?.querySelectorAll("[role=menuitem]") ?? [])];
-        const focused = document.activeElement;
-        const index = focused instanceof HTMLButtonElement ? items.indexOf(focused) : -1;
-        const next = (index + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
-        items[next]?.focus();
-    };
-    const unpin = () => {
-        onClose();
-        layout.pin(control.id, false);
-    };
-    const toggleHidden = () => {
-        onClose();
-        layout.hide(control.id, !isHidden);
-    };
-    return (_jsxs("div", { ref: menuRef, className: "forgebook-context-menu", role: "menu", "aria-label": STRINGS.controlMenu(controlLabel(control)), style: { left: at.x, top: at.y }, onKeyDown: step, children: [_jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: unpin, children: STRINGS.unpinControl }), _jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: toggleHidden, children: isHidden ? STRINGS.showInView : STRINGS.hideInView })] }));
-};
+/** A note's button, for the few switches with a note: most catalogues pin none of them. */
+const INFO_TIP = lazyModule(() => import("./InfoTip.js").then((module) => module.InfoTip));
+/** The control's menu, loaded the first time one opens. */
+const CONTROL_MENU = lazyModule(() => import("./PinnedControlMenu.js").then((module) => module.ControlMenu));
 /**
  * A pinned control.
  *
@@ -89,5 +34,12 @@ export const PinnedControl = ({ control, isHidden, isChanged, layout, ...context
     };
     return (_jsxs("div", { className: "forgebook-toolbar__pinned", "data-control": control.id, 
         // the key that cycles it, in the tooltip of every part that has no tooltip of its own
-        title: shortcut === undefined ? undefined : STRINGS.cycleKey(controlLabel(control), shortcut.toUpperCase()), onContextMenu: open, children: [_jsx(ToolbarControl, { control: control, form: "bar", ...context }), control.kind === "switch" && control.switch.description !== undefined ? (_jsx(InfoTip, { note: control.switch.description, about: controlLabel(control) })) : null, isChanged ? (_jsx("span", { className: "forgebook-dot forgebook-toolbar__changed", role: "img", "aria-label": STRINGS.controlChanged(controlLabel(control)) })) : null, menuAt === undefined ? null : (_jsx(ControlMenu, { control: control, isHidden: isHidden, at: menuAt, layout: layout, onClose: close }))] }));
+        title: shortcut === undefined ? undefined : STRINGS.cycleKey(controlLabel(control), shortcut.toUpperCase()), onContextMenu: open, children: [_jsx(ToolbarControl, { control: control, form: "bar", ...context }), control.kind === "switch" && control.switch.description !== undefined ? (_jsx(LazyView, { module: INFO_TIP, props: { note: control.switch.description, about: controlLabel(control) }, loading: null, failed: () => null })) : null, isChanged ? (_jsx("span", { className: "forgebook-dot forgebook-toolbar__changed", role: "img", "aria-label": STRINGS.controlChanged(controlLabel(control)) })) : null, menuAt === undefined ? null : (_jsx(LazyView, { module: CONTROL_MENU, props: {
+                    id: control.id,
+                    label: controlLabel(control),
+                    isHidden,
+                    at: menuAt,
+                    layout,
+                    onClose: close
+                }, loading: null, failed: () => null }))] }));
 };

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

@@ -0,0 +1,44 @@
+/**
+ * A pinned control's small menu, opened by a right-click or the keyboard's menu key: take it off the toolbar, hide it in
+ * the View menu or show it there again.
+ *
+ * @remarks
+ * Loaded the first time one opens (`PinnedControl.tsx`): the control is on the first screen, and few readers ever ask for
+ * its menu.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { ToolbarLayout } from "./useToolbarLayout.ts";
+/** Where the menu opens, in the window's px. */
+export type MenuPoint = {
+    /** From the window's left. */
+    readonly x: number;
+    /** From the window's top. */
+    readonly y: number;
+};
+/** The menu's props. */
+export type ControlMenuProps = {
+    /** The control's id. */
+    readonly id: string;
+    /**
+     * The control's name. Given rather than read here: a module the page also imports would be taken into a chunk of its
+     * own, and the first load would grow by more than this menu saves.
+     */
+    readonly label: string;
+    /** Whether it takes no row in the View menu. */
+    readonly isHidden: boolean;
+    /** Where the menu opens. */
+    readonly at: MenuPoint;
+    /** The toolbar's arrangement, which its choices change. */
+    readonly layout: ToolbarLayout;
+    /** Called when it closes. */
+    readonly onClose: () => void;
+};
+/**
+ * The control's menu: its two choices as menu items, the first focused, the arrow keys between them; closed by a
+ * choice, a press outside or Escape, the focus going back where it was.
+ *
+ * @param props - the control, where the menu opens, what its choices do, and what closing it does.
+ */
+export declare const ControlMenu: ({ id, label, isHidden, at, layout, onClose }: ControlMenuProps) => ReactNode;

package/dist/src/shell/PinnedControlMenu.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A pinned control's small menu, opened by a right-click or the keyboard's menu key: take it off the toolbar, hide it in
+ * the View menu or show it there again.
+ *
+ * @remarks
+ * Loaded the first time one opens (`PinnedControl.tsx`): the control is on the first screen, and few readers ever ask for
+ * its menu.
+ *
+ * @module
+ */
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { LATER_STRINGS } from "./laterStrings.js";
+/** The room the menu keeps from the window's edges, in CSS px. */
+const EDGE_PX = 8;
+/**
+ * The control's menu: its two choices as menu items, the first focused, the arrow keys between them; closed by a
+ * choice, a press outside or Escape, the focus going back where it was.
+ *
+ * @param props - the control, where the menu opens, what its choices do, and what closing it does.
+ */
+export const ControlMenu = ({ id, label, isHidden, at, layout, onClose }) => {
+    const menuRef = useRef(null);
+    // the menu stays inside the window: opened near its right or lower edge, it moves back by what would run past
+    useLayoutEffect(() => {
+        const menu = menuRef.current;
+        if (menu === null)
+            return;
+        const box = menu.getBoundingClientRect();
+        menu.style.left = `${Math.max(EDGE_PX, Math.min(at.x, window.innerWidth - box.width - EDGE_PX))}px`;
+        menu.style.top = `${Math.max(EDGE_PX, Math.min(at.y, window.innerHeight - box.height - EDGE_PX))}px`;
+    }, [at]);
+    useEffect(() => {
+        const before = document.activeElement;
+        menuRef.current?.querySelector("[role=menuitem]")?.focus();
+        const close = (event) => {
+            const isOutside = event instanceof PointerEvent &&
+                !(event.target instanceof Node && menuRef.current?.contains(event.target));
+            const isEscape = event instanceof KeyboardEvent && event.key === "Escape";
+            if (!isOutside && !isEscape)
+                return;
+            onClose();
+            if (isEscape && before instanceof HTMLElement)
+                before.focus();
+        };
+        document.addEventListener("pointerdown", close);
+        document.addEventListener("keydown", close);
+        return () => {
+            document.removeEventListener("pointerdown", close);
+            document.removeEventListener("keydown", close);
+        };
+    }, [onClose]);
+    const step = (event) => {
+        if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
+            return;
+        event.preventDefault();
+        const items = [...(menuRef.current?.querySelectorAll("[role=menuitem]") ?? [])];
+        const focused = document.activeElement;
+        const index = focused instanceof HTMLButtonElement ? items.indexOf(focused) : -1;
+        const next = (index + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+        items[next]?.focus();
+    };
+    const unpin = () => {
+        onClose();
+        layout.pin(id, false);
+    };
+    const toggleHidden = () => {
+        onClose();
+        layout.hide(id, !isHidden);
+    };
+    return (_jsxs("div", { ref: menuRef, className: "forgebook-context-menu", role: "menu", "aria-label": LATER_STRINGS.controlMenu(label), style: { left: at.x, top: at.y }, onKeyDown: step, children: [_jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: unpin, children: LATER_STRINGS.unpinControl }), _jsx("button", { type: "button", role: "menuitem", className: "forgebook-context-menu__item", onClick: toggleHidden, children: isHidden ? LATER_STRINGS.showInView : LATER_STRINGS.hideInView })] }));
+};

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

@@ -7,10 +7,12 @@
 import type { ReactNode } from "react";
 import type { PanelProp } from "../argTypes.ts";
 import { type ArgValue } from "../messages.ts";
-/** Called with a changed value; `undefined` removes the panel's value. */
+/** Called with a changed value; `undefined` removes the panel's value, `UNSET_ARG` leaves the prop with none. */
 export type OnValueChange = (name: string, value: ArgValue | undefined) => void;
 /** A value as a text field shows it: texts and numbers as they are, anything else empty. */
 export declare const textOf: (value: ArgValue | undefined) => string;
+/** The most options a native list holds before the panel offers a search among them. */
+export declare const MOST_PLAIN_OPTIONS = 12;
 /**
  * A choice's control: buttons side by side for `radio` or a few short values, a list for `select` or otherwise, and
  * a multiple choice for `check` and `multi-select`.

package/dist/src/shell/PropFields.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { isChoiceList } from "../messages.js";
+import { isChoiceList, UNSET_ARG } from "../messages.js";
 import { Segmented } from "./Segmented.js";
 import { STRINGS } from "./strings.js";
 /** A value as a text field shows it: texts and numbers as they are, anything else empty. */
@@ -16,8 +16,10 @@ const dateFieldOf = (value) => {
     const local = new Date(value - date.getTimezoneOffset() * 60_000);
     return local.toISOString().slice(0, 16);
 };
-/** The value of the choice that leaves a prop to the story: no choice of a component is an empty text. */
+/** The value of the choice that leaves a prop without one: no choice of a component is an empty text. */
 const UNSET = "";
+/** The most options a native list holds before the panel offers a search among them. */
+export const MOST_PLAIN_OPTIONS = 12;
 /** The most choices shown as buttons, and the longest label; past either, a list. */
 const FEW_CHOICES = { count: 4, length: 10 };
 /** Whether a choice's values fit side by side as buttons. */
@@ -52,11 +54,11 @@ export const ChoiceControl = ({ prop, value, descriptionId, onValueChange }) =>
         return (_jsx(Segmented, { label: prop.label ?? prop.name, options: [
                 { value: UNSET, label: unsetLabel },
                 ...choices.map((choice) => ({ value: choice, label: choiceLabel(prop, choice) }))
-            ], value: choiceOf(value) ?? UNSET, onValueChange: (chosen) => onValueChange(prop.name, chosen === UNSET ? undefined : chosen) }));
+            ], value: choiceOf(value) ?? UNSET, onValueChange: (chosen) => onValueChange(prop.name, chosen === UNSET ? UNSET_ARG : chosen) }));
     }
     return (_jsxs("select", { "aria-label": prop.label ?? prop.name, "aria-describedby": descriptionId, value: textOf(value), onChange: (event) => {
             const chosen = choices.find((choice) => String(choice) === event.target.value);
-            onValueChange(prop.name, chosen);
+            onValueChange(prop.name, chosen ?? UNSET_ARG);
         }, children: [_jsx("option", { value: "", children: unsetLabel }), choices.map((choice) => (_jsx("option", { value: String(choice), children: choiceLabel(prop, choice) }, String(choice))))] }));
 };
 /** A field for a number, a range or a date, as its `argTypes` say; a date's value is ms since the Unix epoch. */
@@ -66,7 +68,7 @@ export const NumberField = ({ prop, value, descriptionId, onValueChange }) => {
         return (_jsx("input", { type: "datetime-local", "aria-label": label, "aria-describedby": descriptionId, value: dateFieldOf(value), onChange: (event) => {
                 const time = event.target.valueAsNumber;
                 // the field's own value is in UTC: read back in the browser's time zone, as it was shown
-                const local = Number.isNaN(time) ? undefined : time + new Date(time).getTimezoneOffset() * 60_000;
+                const local = Number.isNaN(time) ? UNSET_ARG : time + new Date(time).getTimezoneOffset() * 60_000;
                 onValueChange(prop.name, local);
             } }));
     }
@@ -75,6 +77,7 @@ export const NumberField = ({ prop, value, descriptionId, onValueChange }) => {
         ...(prop.max === undefined ? {} : { max: prop.max }),
         ...(prop.step === undefined ? {} : { step: prop.step })
     };
-    const change = (text) => onValueChange(prop.name, text === "" ? undefined : Number(text));
+    // a number has no empty value, so a cleared field leaves the prop with none
+    const change = (text) => onValueChange(prop.name, text === "" ? UNSET_ARG : Number(text));
     return (_jsxs(_Fragment, { children: [prop.control === "range" ? (_jsx("input", { type: "range", "aria-label": label, "aria-describedby": descriptionId, ...bounds, value: typeof value === "number" ? value : (prop.min ?? 0), onChange: (event) => change(event.target.value) })) : null, _jsx("input", { type: "number", "aria-label": prop.control === "range" ? STRINGS.rangeValue(label) : label, "aria-describedby": descriptionId, ...bounds, value: textOf(value), onChange: (event) => change(event.target.value) })] }));
 };