forgebook 0.1.8 → 0.2.0

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;

package/dist/src/shell/lazyTab.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LazyView } from "./lazyModule.js";
+import { STRINGS } from "./strings.js";
+/**
+ * A tab drawn once its module is there.
+ *
+ * @param props - the tab's module and its own props.
+ */
+export const LazyTab = ({ module, tabProps }) => (_jsx(LazyView, { module: module, props: tabProps, loading: _jsx("p", { className: "forgebook-tab-note", children: STRINGS.tabLoading }), failed: (message) => (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.tabError, ": ", message] })) }));

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

@@ -1,14 +1,3 @@
-/**
- * What a story about logic (`parameters.logic`) leaves out of the toolbar and the stage: what only changes its looks.
- *
- * @remarks
- * A logic story is a hook's or a function's scene, so the bar puts away the controls that only change how it looks
- * (the colour scheme, the contrast, the style sheets, the text size, the backdrop), which the View menu still offers,
- * and Compare, which it does not: the story is drawn once, never compared, while the address keeps its compare for the
- * other stories.
- *
- * @module
- */
 import { type ViewSwitch } from "../switches.ts";
 import type { ViewState } from "../viewState.ts";
 /**
@@ -33,4 +22,3 @@ export declare const logicView: (view: ViewState, isLogic: boolean) => ViewState
  * @param isLogic - whether the story is about logic.
  */
 export declare const logicViewChange: (next: ViewState, addressView: ViewState, isLogic: boolean) => ViewState;
-//# sourceMappingURL=logicView.d.ts.map

package/dist/src/shell/logicView.js

@@ -9,9 +9,10 @@
  *
  * @module
  */
+import { DEVICE_PARAMETER } from "../deviceView.js";
 import { switchWithRole } from "../switches.js";
 /** Forgebook's own controls that only change a story's looks. */
-const LOOK_OWN_CONTROLS = ["backdrop", "sheets", "text"];
+const LOOK_OWN_CONTROLS = ["backdrop", "sheets", "text", DEVICE_PARAMETER];
 /**
  * Whether a toolbar control only changes a story's looks.
  *
@@ -36,4 +37,3 @@ export const logicView = (view, isLogic) => isLogic && view.compare.length > 0 ?
  * @param isLogic - whether the story is about logic.
  */
 export const logicViewChange = (next, addressView, isLogic) => isLogic ? { ...next, compare: addressView.compare } : next;
-//# sourceMappingURL=logicView.js.map

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

@@ -6,17 +6,19 @@
  */
 import "./shell.scss";
 import type { StoryCodeWriter } from "../frame/renderer.ts";
+import { type FramesPlacement } from "../frameOrigins.ts";
 import { type ShellConfig } from "./Shell.tsx";
-/** What an app passes to the shell: the catalogue's configuration and the framework's code writer. */
+/** What the generated page passes to the shell: the catalogue's configuration and the framework's code writer. */
 export type MountShellConfig = ShellConfig & {
     /** Writes a story drawn from its args in the framework's code (`storyJsx` of `@forgebook/react`). */
     readonly codeOf: StoryCodeWriter;
+    /** Where the frames run: on the catalogue's own origin by default. */
+    readonly frames?: FramesPlacement;
 };
 /**
- * Shows the catalogue in the given element.
+ * Shows the catalogue in the given element, or one story alone when the address asks for it.
  *
  * @param container - the element the page renders into.
  * @param config - the catalogue's name, its logo, its sources, its frame page and the framework's code writer.
  */
 export declare const mountShell: (container: HTMLElement, config: MountShellConfig) => void;
-//# sourceMappingURL=mountShell.d.ts.map

package/dist/src/shell/mountShell.js

@@ -7,33 +7,64 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import "./shell.css";
 import { createRoot } from "react-dom/client";
+import { isEmbedAddress } from "../embed.js";
+import { framePageAddress, pageOrigins, SAME_ORIGIN } from "../frameOrigins.js";
 import { CodeWriterContext } from "./codeWriter.js";
+import { FORGEBOOK_MARK_URL } from "./forgebookMark.js";
+import { setFramesOrigin } from "./framesOrigin.js";
 import { Shell } from "./Shell.js";
-import { configureStrings } from "./strings.js";
+import { configureStrings, STRINGS } from "./strings.js";
 /**
- * The page's icon: the catalogue's logo, replacing any the page declares.
+ * The page's icon: the catalogue's logo, replacing any the page declares; without a logo, Forgebook's mark, unless the
+ * page declares an icon of its own or the catalogue turned the branding off.
  *
- * @param logo - the logo's URL.
+ * @param logo - the logo's URL; none for Forgebook's mark.
+ * @param hasBranding - whether Forgebook's mark may stand in for a logo.
  */
-const setPageIcon = (logo) => {
-    for (const link of document.querySelectorAll('link[rel~="icon"]'))
+const setPageIcon = (logo, hasBranding) => {
+    const declared = document.querySelectorAll('link[rel~="icon"]');
+    if (logo === undefined && (declared.length > 0 || !hasBranding))
+        return;
+    for (const link of declared)
         link.remove();
     const icon = document.createElement("link");
     icon.rel = "icon";
-    icon.href = logo;
+    icon.href = logo ?? FORGEBOOK_MARK_URL;
     document.head.append(icon);
 };
 /**
- * Shows the catalogue in the given element.
+ * Shows one story alone in the given element, what `?embed` asks for; the shell is not drawn at all.
+ *
+ * @param root - the page's root.
+ * @param shell - the catalogue's configuration.
+ */
+const mountEmbed = (root, shell) => {
+    import("./EmbedPage.js")
+        .then(({ EmbedPage }) => root.render(_jsx(EmbedPage, { ...shell })))
+        // a stale page after a new deployment: a text, since a blank box in someone's wiki says nothing
+        .catch(() => root.render(_jsx("p", { role: "alert", children: STRINGS.embedFailed })));
+};
+/**
+ * Shows the catalogue in the given element, or one story alone when the address asks for it.
  *
  * @param container - the element the page renders into.
  * @param config - the catalogue's name, its logo, its sources, its frame page and the framework's code writer.
  */
 export const mountShell = (container, config) => {
-    if (config.logo !== undefined)
-        setPageIcon(config.logo);
+    setPageIcon(config.logo, config.hasBranding ?? true);
     configureStrings(config.lists?.strings ?? {});
-    const { codeOf, ...shell } = config;
-    createRoot(container).render(_jsx(CodeWriterContext.Provider, { value: codeOf, children: _jsx(Shell, { ...shell }) }));
+    const { codeOf, frames = SAME_ORIGIN, ...page } = config;
+    // set before anything renders, the embed included: its story's frame runs on the frames' origin too
+    const origins = pageOrigins(frames, window.location, "catalogue");
+    setFramesOrigin(origins.frames);
+    const shell = {
+        ...page,
+        frameUrl: framePageAddress(page.frameUrl, origins.frames, window.location.pathname)
+    };
+    const root = createRoot(container);
+    if (isEmbedAddress(window.location.search)) {
+        mountEmbed(root, shell);
+        return;
+    }
+    root.render(_jsx(CodeWriterContext.Provider, { value: codeOf, children: _jsx(Shell, { ...shell }) }));
 };
-//# sourceMappingURL=mountShell.js.map

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

@@ -0,0 +1,24 @@
+/** The texts of the home and the docs pages, the catalogue's replacements applied. */
+export declare const PAGE_STRINGS: {
+    homeEmpty: string;
+    homeSummary: (components: number, sources: number) => string;
+    homeIntroError: string;
+    recentlyOpened: string;
+    componentsCount: (count: number) => string;
+    showAll: (count: number) => string;
+    showFewer: string;
+    pageContents: string;
+    previousPage: string;
+    nextPage: string;
+    docPageError: string;
+    homeError: string;
+    homeProblems: string;
+    unknownSource: (id: string) => string;
+    asides: {
+        note: string;
+        tip: string;
+        important: string;
+        caution: string;
+        danger: string;
+    };
+};

package/dist/src/shell/pageStrings.js

@@ -0,0 +1,26 @@
+/**
+ * The texts of the pages loaded on first use (the home, generated or written, and the docs pages): loaded with them, so
+ * a story's or a component's first load does not carry them. A catalogue replaces them by the same names as the shell's
+ * other texts (`strings: { "asides.tip": "Hint" }`).
+ *
+ * @module
+ */
+import { lateStrings } from "./strings.js";
+/** The texts of the home and the docs pages, the catalogue's replacements applied. */
+export const PAGE_STRINGS = lateStrings({
+    homeEmpty: "No stories yet: a source with story files shows its families here.",
+    homeSummary: (components, sources) => `${components} ${components === 1 ? "component" : "components"} in ${sources} ${sources === 1 ? "library" : "libraries"}.`,
+    homeIntroError: "The library's introduction could not be read",
+    recentlyOpened: "Recently opened",
+    componentsCount: (count) => `${count} ${count === 1 ? "component" : "components"}`,
+    showAll: (count) => `Show all ${count}`,
+    showFewer: "Show fewer",
+    pageContents: "On this page",
+    previousPage: "Previous",
+    nextPage: "Next",
+    docPageError: "The page could not be read",
+    homeError: "The home could not be read",
+    homeProblems: "The home's file has problems",
+    unknownSource: (id) => `No library "${id}": the home names one the catalogue does not have.`,
+    asides: { note: "Note", tip: "Tip", important: "Important", caution: "Caution", danger: "Danger" }
+});

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

@@ -0,0 +1,9 @@
+/**
+ * The code that draws the plugins' views: their tabs in a story's panel and their docs blocks. The generated page
+ * imports it (`forgebook/shell/plugin-hosts`) only for a catalogue that lists a plugin with views.
+ *
+ * @module
+ */
+import type { PluginHosts } from "./pluginHostsContext.ts";
+/** The plugins' hosts. */
+export declare const pluginHosts: PluginHosts;

package/dist/src/shell/pluginHosts.js

@@ -0,0 +1,6 @@
+import { pluginTabsFor } from "./pluginTabs.js";
+/** The plugins' hosts. */
+export const pluginHosts = {
+    tabsFor: pluginTabsFor,
+    loadBlockHost: async () => (await import("./PluginBlockHost.js")).PluginBlockHost
+};

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

@@ -0,0 +1,20 @@
+import type { PluginBlockHost } from "./PluginBlockHost.tsx";
+import type { pluginTabsFor } from "./pluginTabs.tsx";
+/** The code that draws the plugins' views (`pluginHosts.ts`). */
+export type PluginHosts = {
+    /** Builds a story's plugin tabs. */
+    readonly tabsFor: typeof pluginTabsFor;
+    /** Loads the host of a plugin's docs block, apart: a page with a block need not be a story's page. */
+    readonly loadBlockHost: () => Promise<typeof PluginBlockHost>;
+};
+/** Loads the code that draws the plugins' views. */
+export type LoadPluginHosts = () => Promise<PluginHosts>;
+/** The loader of the plugins' hosts; none in a catalogue that lists no plugin with views. */
+export declare const PluginHostsContext: import("react").Context<LoadPluginHosts | undefined>;
+/**
+ * What a plugin's view reports when the page lists plugins without the code that draws them: a shell configured by
+ * hand that left `pluginHosts` out, said rather than drawn as no plugin.
+ */
+export declare const MISSING_PLUGIN_HOSTS = "The page lists plugins without pluginHosts, the code that draws their views";
+/** Reads the loader of the plugins' hosts the page provides; none in a catalogue without a plugin with views. */
+export declare const usePluginHosts: () => LoadPluginHosts | undefined;

package/dist/src/shell/pluginHostsContext.js

@@ -0,0 +1,16 @@
+/**
+ * How the shell's parts reach the code that draws the plugins' views: a loader the generated page gives only to a
+ * catalogue that lists a plugin with views, so a catalogue without one ships none of that code.
+ *
+ * @module
+ */
+import { createContext, useContext } from "react";
+/** The loader of the plugins' hosts; none in a catalogue that lists no plugin with views. */
+export const PluginHostsContext = createContext(undefined);
+/**
+ * What a plugin's view reports when the page lists plugins without the code that draws them: a shell configured by
+ * hand that left `pluginHosts` out, said rather than drawn as no plugin.
+ */
+export const MISSING_PLUGIN_HOSTS = "The page lists plugins without pluginHosts, the code that draws their views";
+/** Reads the loader of the plugins' hosts the page provides; none in a catalogue without a plugin with views. */
+export const usePluginHosts = () => useContext(PluginHostsContext);

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

@@ -0,0 +1,63 @@
+import type { JsonValue, PluginDocBlock, PluginDocBlockContext, PluginStory, PluginTab, PluginTabContext, PluginView } from "../plugin.ts";
+import type { AsideStory } from "./asideStory.ts";
+import type { DockTab } from "./Dock.tsx";
+/** A plugin's tab as the generated page hands it over: its declaration, and the import of its view. */
+export type ShellPluginTab = Pick<PluginTab, "id" | "label"> & {
+    /** When it is offered; for every story without one. */
+    readonly when: PluginTab["when"] | undefined;
+    /** Loads the module that draws it. */
+    readonly load: () => Promise<{
+        readonly view: PluginView<PluginTabContext>;
+    }>;
+};
+/** A plugin's docs block as the generated page hands it over. */
+export type ShellPluginBlock = Pick<PluginDocBlock, "fence"> & {
+    /** Loads the module that draws it. */
+    readonly load: () => Promise<{
+        readonly view: PluginView<PluginDocBlockContext>;
+    }>;
+};
+/** A plugin with views, as the generated page hands it over. */
+export type ShellPlugin = {
+    /** The plugin's id. */
+    readonly id: string;
+    /** Its tabs. */
+    readonly tabs: readonly ShellPluginTab[];
+    /** Its docs blocks. */
+    readonly docBlocks: readonly ShellPluginBlock[];
+};
+/** What a plugin's frame module last said for a story. */
+type PluginReport = {
+    /** What its tabs receive. */
+    readonly value: JsonValue;
+    /** The note beside a tab's name; none shows nothing. */
+    readonly hint: string | null;
+    /** The tab the note is for; none for the plugin's first. */
+    readonly tab: string | null;
+};
+/** The plugins' reports, by `<story>|<plugin>`. */
+export type PluginReports = ReadonlyMap<string, PluginReport>;
+/** What the plugins' tabs are built from. */
+export type PluginTabsInput = {
+    /** The plugins. */
+    readonly plugins: readonly ShellPlugin[];
+    /** The texts the catalogue replaces, by name. */
+    readonly strings: Readonly<Record<string, string>>;
+    /** The story shown. */
+    readonly story: PluginStory;
+    /** The names of the parameters its frame reported; none before it ran. */
+    readonly parameters: readonly string[];
+    /** The plugins' reports. */
+    readonly reports: PluginReports;
+    /** Whether the compare view is shown: its frames each report, and none of them is the story's. */
+    readonly isComparing: boolean;
+    /** What draws the story again for a tab, with the view's live part. */
+    readonly aside: AsideStory;
+};
+/**
+ * The plugins' tabs the story has something for, in the order of `plugins`.
+ *
+ * @param input - the plugins, the story and what it reported.
+ */
+export declare const pluginTabsFor: (input: PluginTabsInput) => DockTab[];
+export {};

package/dist/src/shell/pluginTabs.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LazyHost } from "./LazyHost.js";
+/** Loads the host of a tab. */
+const loadHost = async () => (await import("./PluginTabHost.js")).PluginTabHost;
+/**
+ * Whether a tab is offered for a story.
+ *
+ * @param tab - the tab.
+ * @param story - the story.
+ * @param parameters - the names of the parameters its frame reported.
+ */
+const isOffered = (tab, story, parameters) => {
+    if (tab.when === undefined)
+        return true;
+    return "design" in tab.when ? story.design.figma !== undefined : parameters.includes(tab.when.parameter);
+};
+/**
+ * A tab's content: its host, once loaded.
+ *
+ * @param plugin - the tab's plugin.
+ * @param tab - the tab.
+ * @param input - what it is told.
+ */
+const pluginTabContent = (plugin, tab, { strings, story, reports, isComparing, aside }) => (_jsx(LazyHost
+// a view lives for one story: it holds what it drew for it (a viewer's position, a dialog)
+, { loadHost: loadHost, props: {
+        load: tab.load,
+        pluginId: plugin.id,
+        strings,
+        story,
+        report: isComparing ? undefined : reports.get(`${story.id}|${plugin.id}`)?.value,
+        // the compare view's address already says the whole view
+        aside: isComparing ? { ...aside, view: undefined } : aside
+    } }, `${tab.id}|${story.id}`));
+/**
+ * The note beside a tab's name.
+ *
+ * @param plugin - the tab's plugin.
+ * @param tab - the tab.
+ * @param input - the reports.
+ */
+const hintOf = (plugin, tab, input) => {
+    const report = input.reports.get(`${input.story.id}|${plugin.id}`);
+    if (input.isComparing || report === undefined)
+        return undefined;
+    return (report.tab ?? plugin.tabs[0]?.id) === tab.id ? (report.hint ?? undefined) : undefined;
+};
+/**
+ * The plugins' tabs the story has something for, in the order of `plugins`.
+ *
+ * @param input - the plugins, the story and what it reported.
+ */
+export const pluginTabsFor = (input) => input.plugins.flatMap((plugin) => plugin.tabs
+    .filter((tab) => isOffered(tab, input.story, input.parameters))
+    .map((tab) => ({
+    id: tab.id,
+    label: input.strings[`tabs.${tab.id}`] ?? tab.label,
+    hint: hintOf(plugin, tab, input),
+    content: pluginTabContent(plugin, tab, input)
+})));