forgebook 0.3.3 → 0.4.1

package/dist/src/shell/EmbedPage.js

@@ -16,15 +16,16 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import "./embed.css";
 import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { checkedArgsMessage } from "../addressArgs.js";
-import { addressArgsFor } from "../addressTexts.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";
@@ -106,24 +107,27 @@ const EmbedNotice = ({ message, detail, isFailure }) => {
  *
  * @param props - the story, the view, its args and the frame page.
  */
-const EmbedStory = ({ location, view, panelArgs, loadDocs, namedValues, 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;
+    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({
@@ -157,38 +161,52 @@ const EmbedStory = ({ location, view, panelArgs, loadDocs, namedValues, 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", { 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, 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 = useMemo(() => addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts), [params, addressTexts]);
+    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) }) }));
     }
+    // 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), panelArgs: panelArgs, loadDocs: source === undefined ? undefined : sourceFiles(source).docs[location.story.file], namedValues: source?.namedValues, frameUrl: frameUrl }));
+    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 {};

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,19 @@ 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 { usePageWidth } from "./PageWidth.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 +90,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 +124,13 @@ 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;
+    const pageWidth = usePageWidth();
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("div", { className: "forgebook-scroll", children: [_jsx("div", { className: "forgebook-home__tools", children: pageWidth.toggle }), _jsxs("div", { className: "forgebook-home", "data-page-width": pageWidth.width, children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsxs("p", { className: "forgebook-doc__lead", children: [isWaiting ? PAGE_STRINGS.homeNoStoryTitle : null, !isWaiting && tree.sources.length === 0 ? PAGE_STRINGS.homeEmpty : null, !isWaiting && tree.sources.length > 0
+                                                ? PAGE_STRINGS.homeSummary(componentCount(tree), libraryCount(tree))
+                                                : null] })] }), isWaiting ? _jsx(NoStoryYet, { globs: listingGlobs }) : null, _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen }), tree.sources.map((source) => (_jsx(LibrarySection, { source: source, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, source.id)))] })] })] }));
 };

package/dist/src/shell/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/PageWidth.d.ts

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

package/dist/src/shell/PageWidth.js

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

package/dist/src/shell/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 }))] }));
 };