forgebook 0.1.8 → 0.3.0

package/dist/src/shell/embed.css

@@ -0,0 +1,74 @@
+@layer catalogue {
+  .forgebook-embed {
+    min-height: 100vh;
+    background: var(--forgebook-surface);
+  }
+  .forgebook-embed__story {
+    max-width: 100%;
+    margin-inline: auto;
+  }
+  .forgebook-embed__message {
+    margin: 0;
+    padding: 1rem;
+    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-embed__message[data-failed] {
+    color: var(--forgebook-danger-text);
+  }
+  .forgebook-embed__detail {
+    margin: 0.25rem 0 0;
+    color: var(--forgebook-text-secondary);
+    overflow-wrap: anywhere;
+  }
+  .forgebook-popover--embed {
+    box-sizing: border-box;
+    width: min(26rem, 100vw - 1.5rem);
+    max-height: calc(100vh - 1.5rem);
+    overflow-y: auto;
+    white-space: normal;
+  }
+  .forgebook-embed-panel__hint {
+    margin: 0;
+    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-embed-panel__hint[data-warning] {
+    color: var(--forgebook-danger-text);
+  }
+  .forgebook-embed-field {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 0.25rem 0.5rem;
+    align-items: center;
+  }
+  .forgebook-embed-field__label {
+    grid-column: 1/-1;
+    font: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    color: var(--forgebook-text-secondary);
+  }
+  .forgebook-embed-field__value {
+    box-sizing: border-box;
+    width: 100%;
+    min-width: 0;
+    padding: 0.375rem 0.5rem;
+    border: 0;
+    border-radius: var(--forgebook-radius-control);
+    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    color: var(--forgebook-text);
+    background: var(--forgebook-fill-quiet);
+    box-shadow: inset 0 0 0 1px var(--forgebook-edge-field);
+  }
+  .forgebook-embed-field__value:focus-visible {
+    outline: 2px solid color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    outline-offset: 0;
+    box-shadow: inset 0 0 0 1px var(--forgebook-accent);
+  }
+  .forgebook-embed-panel__follow {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    font: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    color: var(--forgebook-text);
+  }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The code of a component whose stories come from several files, as one loader: the Code cards of its page read each
+ * story's code by its export, whichever file it is in.
+ *
+ * @remarks
+ * The loader of a component in one file is the source's own, unchanged. One in several files is made once per list of
+ * files and kept, since the page loads the code again whenever its loader changes.
+ *
+ * @module
+ */
+/** A source's loaders of its files' code, by file. */
+type CodeLoaders = Readonly<Record<string, () => Promise<unknown>>>;
+/**
+ * One loader for the code of several files: each file's code, a story's export found in the first file that has it.
+ *
+ * @param loaders - the source's loaders of its files' code.
+ * @param files - the component's files, its first file first.
+ * @returns the loader; `undefined` when no file has one.
+ */
+export declare const filesCodeLoader: (loaders: CodeLoaders, files: readonly string[]) => (() => Promise<unknown>) | undefined;
+export {};

package/dist/src/shell/filesCode.js

@@ -0,0 +1,37 @@
+/**
+ * The code of a component whose stories come from several files, as one loader: the Code cards of its page read each
+ * story's code by its export, whichever file it is in.
+ *
+ * @remarks
+ * The loader of a component in one file is the source's own, unchanged. One in several files is made once per list of
+ * files and kept, since the page loads the code again whenever its loader changes.
+ *
+ * @module
+ */
+/** The loaders made so far, by the source's loaders, then by the files joined. */
+const MADE = new WeakMap();
+/**
+ * One loader for the code of several files: each file's code, a story's export found in the first file that has it.
+ *
+ * @param loaders - the source's loaders of its files' code.
+ * @param files - the component's files, its first file first.
+ * @returns the loader; `undefined` when no file has one.
+ */
+export const filesCodeLoader = (loaders, files) => {
+    const own = files.flatMap((file) => {
+        const load = loaders[file];
+        return load === undefined ? [] : [load];
+    });
+    if (own.length <= 1)
+        return own[0];
+    const made = MADE.get(loaders) ?? new Map();
+    MADE.set(loaders, made);
+    const key = files.join("\n");
+    const known = made.get(key);
+    if (known !== undefined)
+        return known;
+    // the last file is assigned first, so a story of an earlier file wins; an `error` of any file stays and is shown
+    const load = () => Promise.all(own.map((each) => each())).then((codes) => Object.assign({}, ...codes.reverse()));
+    made.set(key, load);
+    return load;
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Forgebook's own mark: an open book whose two pages rise into a flame, in an ember gradient. The sidebar shows it for
+ * a catalogue without a logo of its own, and the page's icon uses it then (`mountShell.tsx`).
+ *
+ * @remarks
+ * One SVG text, drawn as an image (a data address), so its gradients never clash with ids in the page and the
+ * sidebar and the icon cannot drift apart. `assets/forgebook-logo.svg` at the repository's root is the same drawing,
+ * for the READMEs.
+ *
+ * @module
+ */
+/** The mark's SVG, on a 64 × 64 grid. */
+export declare const FORGEBOOK_MARK_SVG: string;
+/** The mark as an image's address. */
+export declare const FORGEBOOK_MARK_URL: string;

package/dist/src/shell/forgebookMark.js

@@ -0,0 +1,28 @@
+/**
+ * Forgebook's own mark: an open book whose two pages rise into a flame, in an ember gradient. The sidebar shows it for
+ * a catalogue without a logo of its own, and the page's icon uses it then (`mountShell.tsx`).
+ *
+ * @remarks
+ * One SVG text, drawn as an image (a data address), so its gradients never clash with ids in the page and the
+ * sidebar and the icon cannot drift apart. `assets/forgebook-logo.svg` at the repository's root is the same drawing,
+ * for the READMEs.
+ *
+ * @module
+ */
+/** The mark's SVG, on a 64 × 64 grid. */
+export const FORGEBOOK_MARK_SVG = [
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">',
+    "<defs>",
+    '<linearGradient id="ember" x1="0" y1="1" x2="0.6" y2="0">',
+    '<stop offset="0" stop-color="#E0115F"/><stop offset="0.5" stop-color="#FF5A1F"/><stop offset="1" stop-color="#FFB020"/>',
+    "</linearGradient>",
+    '<linearGradient id="ember-dark" x1="0" y1="1" x2="0.6" y2="0">',
+    '<stop offset="0" stop-color="#B00E4C"/><stop offset="1" stop-color="#F0441A"/>',
+    "</linearGradient>",
+    "</defs>",
+    '<path d="M30.5 56C16 53 8 41 13 27C15.5 20 20 15 23 8C24.5 20 28 25 30.5 31Z" fill="url(#ember-dark)"/>',
+    '<path d="M33.5 56C48 53 57 40 51 25C48.5 18 44 13 42 4C39.5 18 36 24 33.5 31Z" fill="url(#ember)"/>',
+    "</svg>"
+].join("");
+/** The mark as an image's address. */
+export const FORGEBOOK_MARK_URL = `data:image/svg+xml,${encodeURIComponent(FORGEBOOK_MARK_SVG)}`;

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

@@ -0,0 +1,23 @@
+/**
+ * Sets the frames' origin, before the shell renders.
+ *
+ * @param origin - the frames' origin (`http://localhost:5174`).
+ */
+export declare const setFramesOrigin: (origin: string) => void;
+/** The frames' origin: the catalogue's own until `mountShell` sets it. */
+export declare const framesOrigin: () => string;
+/**
+ * Whether a message comes from the frames' origin.
+ *
+ * @param event - the message's event.
+ */
+export declare const isFromFrames: (event: MessageEvent) => boolean;
+/** What a story's frame element is given, wherever the shell draws one. */
+export type StoryFrameAttributes = {
+    /** The browser features it may use. */
+    readonly allow: string;
+    /** Its sandbox; none on the catalogue's own origin. */
+    readonly sandbox: string | undefined;
+};
+/** The attributes of a story's frame element: the features it is delegated, and its sandbox off the catalogue's origin. */
+export declare const storyFrameAttributes: () => StoryFrameAttributes;

package/dist/src/shell/framesOrigin.js

@@ -0,0 +1,69 @@
+/**
+ * The shell's side of the messages with the stories' frames: the frames' origin, the only one the shell sends to and
+ * listens to, and what each frame element the shell draws is allowed (the stage's, a page's, the design comparison's).
+ *
+ * @remarks
+ * A page holds one shell, and its frames run on one origin for the page's life, so the origin is a fact of the page,
+ * set once by `mountShell` before anything renders, as the page's address is. A message from anywhere else is not a
+ * frame's, and a message sent with the frames' origin never reaches a document that is not one of them.
+ *
+ * @module
+ */
+/** The frames' origin, once `mountShell` set it. */
+let pageFramesOrigin;
+/**
+ * Sets the frames' origin, before the shell renders.
+ *
+ * @param origin - the frames' origin (`http://localhost:5174`).
+ */
+export const setFramesOrigin = (origin) => {
+    pageFramesOrigin = origin;
+};
+/** The frames' origin: the catalogue's own until `mountShell` sets it. */
+export const framesOrigin = () => pageFramesOrigin ?? window.location.origin;
+/**
+ * Whether a message comes from the frames' origin.
+ *
+ * @param event - the message's event.
+ */
+export const isFromFrames = (event) => event.origin === framesOrigin();
+/**
+ * The browser features a story may use, delegated to its frame. A frame on the catalogue's own origin had each of them;
+ * on an origin of its own it gets only those its element allows (a copy button, a video's full screen, a scanner's
+ * camera).
+ */
+const FRAME_PERMISSIONS = [
+    "clipboard-read",
+    "clipboard-write",
+    "fullscreen",
+    "camera",
+    "microphone",
+    "geolocation",
+    "display-capture",
+    "autoplay",
+    "picture-in-picture",
+    "encrypted-media",
+    "screen-wake-lock"
+].join("; ");
+/**
+ * What a story's frame may do, as a sandbox: everything a page does but navigate the catalogue's tab, which a story's
+ * link could otherwise send to any address. The frames keep their own origin (`allow-same-origin`): it is not the
+ * catalogue's, so the pair gives the story nothing of the catalogue's. Frames on the catalogue's own origin get none:
+ * there the pair would let a story lift its own sandbox, and browsers warn of it.
+ */
+const FRAME_SANDBOX = [
+    "allow-scripts",
+    "allow-same-origin",
+    "allow-forms",
+    "allow-modals",
+    "allow-popups",
+    "allow-popups-to-escape-sandbox",
+    "allow-downloads",
+    "allow-pointer-lock",
+    "allow-presentation"
+].join(" ");
+/** The attributes of a story's frame element: the features it is delegated, and its sandbox off the catalogue's origin. */
+export const storyFrameAttributes = () => ({
+    allow: FRAME_PERMISSIONS,
+    sandbox: framesOrigin() === window.location.origin ? undefined : FRAME_SANDBOX
+});

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

@@ -25,8 +25,11 @@ declare const PATHS: {
     readonly ruler: "M2 10.5 10.5 2l3.5 3.5L5.5 14zM5 8l1.5 1.5M7 6l1 1M9 4l1.5 1.5";
     readonly sidebar: "M2 3h12v10H2zM6 3v10";
     readonly close: "M4 4l8 8M12 4l-8 8";
+    readonly embed: "M5.5 4.5 2 8l3.5 3.5M10.5 4.5 14 8l-3.5 3.5";
     readonly external: "M9 2.5h4.5V7M13.5 2.5 8 8M11.5 9.5v4h-9v-9h4";
     readonly width: "M2 4v8M14 4v8M4.5 8h7M6 6.5 4.5 8 6 9.5M10 6.5l1.5 1.5-1.5 1.5";
+    readonly turn: "M2.5 9.5h7a1 1 0 0 0 1-1v-4a1 1 0 0 0-1-1h-7a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1ZM12 12.5a2.5 2.5 0 0 0 2.5-2.5V8.5M13.5 10l1-1.5 1 1.5";
+    readonly device: "M5.5 1.5h5a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1ZM7.25 3.5h1.5";
     readonly plus: "M8 3.5v9M3.5 8h9";
     readonly minus: "M3.5 8h9";
     readonly hash: "M6 2.5 5 13.5M11 2.5l-1 11M3 6h10.5M2.5 10H13";
@@ -52,4 +55,3 @@ export declare const Icon: ({ name, size }: {
     readonly size?: number;
 }) => ReactNode;
 export {};
-//# sourceMappingURL=icons.d.ts.map

package/dist/src/shell/icons.js

@@ -20,8 +20,11 @@ const PATHS = {
     ruler: "M2 10.5 10.5 2l3.5 3.5L5.5 14zM5 8l1.5 1.5M7 6l1 1M9 4l1.5 1.5",
     sidebar: "M2 3h12v10H2zM6 3v10",
     close: "M4 4l8 8M12 4l-8 8",
+    embed: "M5.5 4.5 2 8l3.5 3.5M10.5 4.5 14 8l-3.5 3.5",
     external: "M9 2.5h4.5V7M13.5 2.5 8 8M11.5 9.5v4h-9v-9h4",
     width: "M2 4v8M14 4v8M4.5 8h7M6 6.5 4.5 8 6 9.5M10 6.5l1.5 1.5-1.5 1.5",
+    turn: "M2.5 9.5h7a1 1 0 0 0 1-1v-4a1 1 0 0 0-1-1h-7a1 1 0 0 0-1 1v4a1 1 0 0 0 1 1ZM12 12.5a2.5 2.5 0 0 0 2.5-2.5V8.5M13.5 10l1-1.5 1 1.5",
+    device: "M5.5 1.5h5a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1h-5a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1ZM7.25 3.5h1.5",
     plus: "M8 3.5v9M3.5 8h9",
     minus: "M3.5 8h9",
     hash: "M6 2.5 5 13.5M11 2.5l-1 11M3 6h10.5M2.5 10H13",
@@ -41,4 +44,3 @@ const PATHS = {
  * @param props - the icon and its size in px.
  */
 export const Icon = ({ name, size = 16 }) => (_jsx("svg", { width: size, height: size, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: PATHS[name] }) }));
-//# sourceMappingURL=icons.js.map

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

@@ -33,4 +33,3 @@ export declare const storyStep: (event: Pick<KeyboardEvent, "key" | "metaKey" |
  * @param firstOfPage - on a component's page, the id of its first story.
  */
 export declare const steppedStory: (ids: readonly string[], currentId: string | undefined, step: StoryStep, firstOfPage: string | undefined) => string | undefined;
-//# sourceMappingURL=keyboard.d.ts.map

package/dist/src/shell/keyboard.js

@@ -51,4 +51,3 @@ export const steppedStory = (ids, currentId, step, firstOfPage) => {
     const index = ids.indexOf(currentId);
     return index === -1 ? undefined : ids[index + step];
 };
-//# sourceMappingURL=keyboard.js.map

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

@@ -0,0 +1,91 @@
+/** The later parts' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export declare const LATER_STRINGS: {
+    audienceError: string;
+    controlKey: (control: string, key: string | undefined) => string;
+    changeKey: string;
+    pressAKey: string;
+    namedViews: string;
+    saveView: string;
+    viewName: string;
+    removeView: (name: string) => string;
+    resetView: string;
+    viewInAddress: string;
+    pinControl: (label: string) => string;
+    hideControl: (label: string) => string;
+    showControl: (label: string) => string;
+    moveControl: (label: string) => string;
+    moveControlHint: string;
+    controlMoved: (label: string, position: number, count: number) => string;
+    pinnedNoRoom: string;
+    resetToolbar: string;
+    wrapToolbar: string;
+    hiddenControls: (count: number, pinned: number) => string;
+    toolbarInBrowser: string;
+    compareCell: (labels: readonly string[]) => string;
+    embedHint: string;
+    embedLink: string;
+    embedCode: string;
+    embedFollow: string;
+    embedFollowHint: string;
+    embedLocal: string;
+    embedCopyFailed: string;
+    embedNoStory: string;
+    embedUnknownStory: (id: string) => string;
+    pluginLoading: string;
+    pluginError: string;
+    playTitle: string;
+    playTime: (ms: number) => string;
+    playAgain: string;
+    playNoSteps: string;
+    codeFromArgs: string;
+    codeRender: string;
+    copy: string;
+    a11yCheck: string;
+    a11yRunning: string;
+    a11yNone: string;
+    a11yError: string;
+    a11yNotInCompare: string;
+    clockLabel: string;
+    clockPause: string;
+    clockResume: string;
+    clockRestart: string;
+    clockSpeed: string;
+    clockRate: (rate: number) => string;
+    apiReference: string;
+    apiProp: string;
+    apiEvent: string;
+    apiSignature: string;
+    apiDefault: string;
+    apiMember: string;
+    memberCount: (count: number) => string;
+    membersOf: (type: string) => string;
+    showCode: string;
+    hideCode: string;
+    openStory: string;
+    usedIn: string;
+    usedInThrough: string;
+    usedInMore: (count: number) => string;
+    usedInStories: (count: number) => string;
+    openStoryNamed: (name: string) => string;
+    touch: string;
+    touchNamed: (name: string) => string;
+    fillPage: string;
+    fillPageNamed: (name: string) => string;
+    backToPlace: string;
+    backToPlaceNamed: (name: string) => string;
+    examples: string;
+    pageError: string;
+    droppedArgs: string;
+    droppedArgReasons: {
+        undeclared: string;
+        type: string;
+    };
+    removeDroppedArgs: string;
+    events: string;
+    calls: string;
+    noCalls: string;
+    clearCalls: string;
+    partsList: string;
+    styleHooks: string;
+    testIds: string;
+};

package/dist/src/shell/laterStrings.js

@@ -0,0 +1,102 @@
+/**
+ * The texts of the shell's parts that load after the first screen, but for the home and the docs pages
+ * (`pageStrings.ts`): a component's page, the panel's tabs but Props, the View menu's panel, the embed panel and page,
+ * the comparison, the story clock's bar, the plugins' hosts and the note on args a link dropped. They load with the
+ * first of those parts, so a first load carries none of them.
+ *
+ * @remarks
+ * Each keeps the plain name it would have in `STRINGS`, so a catalogue replaces it the same way
+ * (`strings: { copy: "Copia" }`): the replacements set before the shell drew apply when this module loads
+ * (`lateStrings`).
+ *
+ * @module
+ */
+import { lateStrings } from "./strings.js";
+/** The later parts' texts, as shown: Forgebook's, with the catalogue's replacements. */
+export const LATER_STRINGS = lateStrings({
+    audienceError: "This part of the page could not be loaded",
+    controlKey: (control, key) => key === undefined ? `${control}: no key` : `${control}: key ${key.toUpperCase()}`,
+    changeKey: "Change the key: press it, then the new key; Backspace takes it away",
+    pressAKey: "Press a key",
+    namedViews: "Views",
+    saveView: "Save view…",
+    viewName: "View name",
+    removeView: (name) => `Remove the view ${name}`,
+    resetView: "Reset to defaults",
+    viewInAddress: "Saved in the address",
+    pinControl: (label) => `Pin ${label} to the toolbar`,
+    hideControl: (label) => `Hide ${label} in View`,
+    showControl: (label) => `Show ${label}`,
+    moveControl: (label) => `Move ${label}`,
+    moveControlHint: "Drag, or press the arrow keys",
+    controlMoved: (label, position, count) => `${label}, ${position} of ${count}`,
+    pinnedNoRoom: "Pinned: back on the toolbar when there is room",
+    resetToolbar: "Reset toolbar",
+    wrapToolbar: "Wrap the toolbar onto more lines when it is full",
+    hiddenControls: (count, pinned) => pinned === 0 ? `${count} hidden` : `${count} hidden · ${pinned} on the toolbar`,
+    toolbarInBrowser: "The toolbar is kept in this browser",
+    compareCell: (labels) => labels.join(" · "),
+    embedHint: "Paste the link in a wiki or Notion, the HTML in a page of your own.",
+    embedLink: "Link",
+    embedCode: "HTML",
+    embedFollow: "Follow the story's height",
+    embedFollowHint: "Adds a script, which some pages remove: the frame then keeps the height written in it.",
+    embedLocal: "This address opens only on this computer: copy it from the published catalogue.",
+    embedCopyFailed: "Selected: copy it with your keys",
+    embedNoStory: "This address names no story.",
+    embedUnknownStory: (id) => `No story "${id}": it may have been renamed.`,
+    pluginLoading: "Loading the tab…",
+    pluginError: "This tab could not be loaded",
+    playTitle: "Play function",
+    playTime: (ms) => `${ms} ms`,
+    playAgain: "Run again",
+    playNoSteps: "The play names no steps: wrap its parts in step(label, run) to see them here.",
+    codeFromArgs: "from the args",
+    codeRender: "the story's render",
+    copy: "Copy",
+    a11yCheck: "Check the story",
+    a11yRunning: "Checking…",
+    a11yNone: "No WCAG 2.2 A or AA rule is broken in the story as it is now.",
+    a11yError: "The check could not run",
+    a11yNotInCompare: "One story at a time: leave Compare to check it",
+    clockLabel: "Story clock",
+    clockPause: "Pause the clock",
+    clockResume: "Resume the clock",
+    clockRestart: "Restart",
+    clockSpeed: "Clock speed",
+    clockRate: (rate) => `×${rate}`,
+    apiReference: "API reference",
+    apiProp: "Prop",
+    apiEvent: "Event",
+    apiSignature: "Signature",
+    apiDefault: "Default",
+    apiMember: "Member",
+    memberCount: (count) => `${count} ${count === 1 ? "member" : "members"}`,
+    membersOf: (type) => `Members of ${type}`,
+    showCode: "Show code",
+    hideCode: "Hide code",
+    openStory: "Open the story",
+    usedIn: "Used in",
+    usedInThrough: "through another component",
+    usedInMore: (count) => `and ${count} more`,
+    usedInStories: (count) => (count === 1 ? "1 story" : `${count} stories`),
+    openStoryNamed: (name) => `Open the story ${name}`,
+    touch: "Touch",
+    touchNamed: (name) => `Touch ${name} with a finger`,
+    fillPage: "Fill the page",
+    fillPageNamed: (name) => `Fill the page with ${name}`,
+    backToPlace: "Back to its place",
+    backToPlaceNamed: (name) => `Put ${name} back in its place`,
+    examples: "Examples",
+    pageError: "The component's page could not be read",
+    droppedArgs: "The link sets values this story does not take; they were left out:",
+    droppedArgReasons: { undeclared: "not one of its props", type: "not of the prop's type" },
+    removeDroppedArgs: "Remove them from the address",
+    events: "Events",
+    calls: "Calls",
+    noCalls: "No call yet",
+    clearCalls: "Clear",
+    partsList: "Parts",
+    styleHooks: "Styling attributes",
+    testIds: "Test ids"
+});

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

@@ -0,0 +1,49 @@
+/**
+ * A part of the shell whose module loads the first time it is drawn: a page other than a story's (the home, a
+ * component's page, a docs page), a tab of the story's panel. What a first screen does not show stays out of the first
+ * load.
+ *
+ * @remarks
+ * The load is watched here rather than through `React.lazy` and `Suspense`, for two reasons. Once a Suspense boundary
+ * has shown its fallback, React holds the content back for 300 ms so a page does not flash, which would put that delay
+ * on every first visit to a page or a tab; here the content replaces its fallback the moment its code arrives. And the
+ * shell has no error boundary: a module that is gone (a page left open across a new build) must cost that part, not
+ * the whole page. Once loaded, the part draws at once wherever it is drawn again.
+ *
+ * @module
+ */
+import { type ComponentType, type ReactNode } from "react";
+/** A part's module: how to load its component, and the component once loaded. */
+export type LazyModule<TProps> = {
+    /** Loads the part's component. */
+    readonly load: () => Promise<ComponentType<TProps>>;
+    /** The component, once a load gave it. */
+    loaded: ComponentType<TProps> | undefined;
+};
+/**
+ * A part's module, not loaded yet.
+ *
+ * @param load - loads the part's component.
+ */
+export declare const lazyModule: <TProps>(load: () => Promise<ComponentType<TProps>>) => LazyModule<TProps>;
+/** The props of a part drawn from its module. */
+export type LazyViewProps<TProps> = {
+    /** The part's module. */
+    readonly module: LazyModule<TProps>;
+    /** The part's own props. */
+    readonly props: TProps;
+    /** What is drawn while it loads. */
+    readonly loading: ReactNode;
+    /** What is drawn when it cannot load, from the reason. */
+    readonly failed: (message: string) => ReactNode;
+};
+/**
+ * A part drawn once its module is there.
+ *
+ * @remarks
+ * One place may be given another part's module (the dock draws each chosen tab in the same place): its state is that
+ * module's, never the last one's.
+ *
+ * @param props - the part's module, its own props, and what to draw until it is there.
+ */
+export declare const LazyView: <TProps extends object>({ module, props, loading, failed }: LazyViewProps<TProps>) => ReactNode;

package/dist/src/shell/lazyModule.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A part of the shell whose module loads the first time it is drawn: a page other than a story's (the home, a
+ * component's page, a docs page), a tab of the story's panel. What a first screen does not show stays out of the first
+ * load.
+ *
+ * @remarks
+ * The load is watched here rather than through `React.lazy` and `Suspense`, for two reasons. Once a Suspense boundary
+ * has shown its fallback, React holds the content back for 300 ms so a page does not flash, which would put that delay
+ * on every first visit to a page or a tab; here the content replaces its fallback the moment its code arrives. And the
+ * shell has no error boundary: a module that is gone (a page left open across a new build) must cost that part, not
+ * the whole page. Once loaded, the part draws at once wherever it is drawn again.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+/**
+ * A part's module, not loaded yet.
+ *
+ * @param load - loads the part's component.
+ */
+export const lazyModule = (load) => ({
+    load,
+    loaded: undefined
+});
+/**
+ * A part's state as its module first gives it: drawn at once when an earlier draw loaded it.
+ *
+ * @param module - the part's module.
+ */
+const initialState = (module) => module.loaded === undefined ? { status: "loading" } : { status: "ready", value: module.loaded };
+/**
+ * A part drawn once its module is there.
+ *
+ * @remarks
+ * One place may be given another part's module (the dock draws each chosen tab in the same place): its state is that
+ * module's, never the last one's.
+ *
+ * @param props - the part's module, its own props, and what to draw until it is there.
+ */
+export const LazyView = ({ module, props, loading, failed }) => {
+    const [state, setState] = useState(() => ({ module, part: initialState(module) }));
+    if (state.module !== module)
+        setState({ module, part: initialState(module) });
+    const part = state.module === module ? state.part : initialState(module);
+    useEffect(() => {
+        if (part.status !== "loading")
+            return;
+        let isCurrent = true;
+        module
+            .load()
+            .then((value) => {
+            module.loaded = value;
+            if (isCurrent)
+                setState({ module, part: { status: "ready", value } });
+        })
+            .catch((error) => {
+            if (isCurrent) {
+                const message = error instanceof Error ? error.message : String(error);
+                setState({ module, part: { status: "error", message } });
+            }
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [module, part.status]);
+    if (part.status === "ready") {
+        const Part = part.value;
+        return _jsx(Part, { ...props });
+    }
+    return part.status === "error" ? failed(part.message) : loading;
+};

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

@@ -0,0 +1,21 @@
+/**
+ * A tab of the story's panel whose module loads the first time it is drawn (`lazyModule.tsx`), with a note until it is
+ * there and the reason when it cannot load.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type LazyModule } from "./lazyModule.tsx";
+/** The props of a tab drawn from its module. */
+export type LazyTabProps<TProps> = {
+    /** The tab's module. */
+    readonly module: LazyModule<TProps>;
+    /** The tab's own props. */
+    readonly tabProps: TProps;
+};
+/**
+ * A tab drawn once its module is there.
+ *
+ * @param props - the tab's module and its own props.
+ */
+export declare const LazyTab: <TProps extends object>({ module, tabProps }: LazyTabProps<TProps>) => ReactNode;