forgebook 0.1.8 → 0.3.0

package/dist/src/shell/HomePage.js

@@ -1,13 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-import { componentId, findComponent, findStory } from "../storyTree.js";
+import { findPage } from "../pageTree.js";
+import { findComponent, findStory } from "../storyTree.js";
 import { PackageHtml } from "./PackageHtml.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
 import { STRINGS } from "./strings.js";
 import { useLoaded } from "./useLoaded.js";
 /** The most components a family's card lists before "Show all". */
 const CARD_COMPONENTS = 6;
 /** A link to a page, opened in place unless the user asks for another tab. */
-const PageLink = ({ page, hrefOf, onOpen, className, children }) => (_jsx("a", { className: className, href: hrefOf(page), onClick: (event) => {
+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)
             return;
         event.preventDefault();
@@ -19,7 +21,7 @@ const PageLink = ({ page, hrefOf, onOpen, className, children }) => (_jsx("a", {
  * @param tree - the tree.
  * @param recent - the pages opened last.
  */
-const recentEntries = (tree, recent) => recent.flatMap((page) => {
+export const recentEntries = (tree, recent) => recent.flatMap((page) => {
     if (page.kind === "story") {
         const location = findStory(tree, page.id);
         if (location === undefined)
@@ -27,6 +29,13 @@ const recentEntries = (tree, recent) => recent.flatMap((page) => {
         const place = [location.source.name, location.family.name, location.component.name].join(" · ");
         return [{ page, name: location.story.name, place }];
     }
+    if (page.kind === "page") {
+        const location = findPage(tree, page.id);
+        if (location === undefined)
+            return [];
+        const place = [location.source.name, location.page.group].filter((part) => part !== undefined);
+        return [{ page, name: location.page.name, place: place.join(" · ") }];
+    }
     const location = findComponent(tree, page.id);
     if (location === undefined)
         return [];
@@ -51,35 +60,65 @@ const introState = (value) => {
  *
  * @param props - the loader.
  */
-const SourceIntro = ({ load }) => {
+export const SourceIntro = ({ load }) => {
     const intro = useLoaded(load, introState);
     if (intro.status === "error") {
-        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.homeIntroError, ": ", intro.message] }));
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [PAGE_STRINGS.homeIntroError, ": ", intro.message] }));
     }
     return intro.status === "ready" ? (_jsx(PackageHtml, { className: "forgebook-prose", html: intro.value.html })) : null;
 };
 /**
  * A family's card: its name and how many components it has, then its components, the first few until asked for all.
  *
- * @param props - the source, the family, and how to open a component.
+ * @param props - the family, and how to open a component.
  */
-const FamilyCard = ({ source, family, hrefOf, onOpen }) => {
+export const FamilyCard = ({ family, hrefOf, onOpen }) => {
     const [isOpen, setIsOpen] = useState(false);
     const components = family.groups.flatMap((group) => [...group.components]);
     const shown = isOpen ? components : components.slice(0, CARD_COMPONENTS);
-    return (_jsxs("article", { className: "forgebook-home__card", "aria-label": family.name, children: [_jsxs("h3", { className: "forgebook-home__card-title", children: [family.name, _jsx("span", { className: "forgebook-home__count", children: STRINGS.componentsCount(components.length) })] }), _jsx("ul", { className: "forgebook-home__components", children: shown.map((component) => (_jsx("li", { children: _jsx(PageLink, { page: { kind: "component", id: componentId(source.id, component.title) }, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: component.name }) }, component.title))) }), components.length > CARD_COMPONENTS ? (_jsx("button", { type: "button", className: "forgebook-text-button", "aria-expanded": isOpen, onClick: () => setIsOpen(!isOpen), children: isOpen ? STRINGS.showFewer : STRINGS.showAll(components.length) })) : null] }));
+    return (_jsxs("article", { className: "forgebook-home__card", "aria-label": family.name, children: [_jsxs("h3", { className: "forgebook-home__card-title", children: [family.name, _jsx("span", { className: "forgebook-home__count", children: PAGE_STRINGS.componentsCount(components.length) })] }), _jsx("ul", { className: "forgebook-home__components", children: shown.map((component) => (_jsx("li", { children: _jsx(PageLink, { page: { kind: "component", id: component.id }, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: component.name }) }, component.title))) }), components.length > CARD_COMPONENTS ? (_jsx("button", { type: "button", className: "forgebook-text-button", "aria-expanded": isOpen, onClick: () => setIsOpen(!isOpen), children: isOpen ? PAGE_STRINGS.showFewer : PAGE_STRINGS.showAll(components.length) })) : null] }));
 };
+/**
+ * A source's docs pages as a card, in their reading order, first among its families.
+ *
+ * @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))) })] }));
+/**
+ * How many components a tree has, in every library.
+ *
+ * @param tree - the tree.
+ */
+export const componentCount = (tree) => tree.sources.reduce((total, source) => total +
+    source.families.reduce((sum, family) => sum + family.groups.reduce((count, group) => count + group.components.length, 0), 0), 0);
+/**
+ * How many libraries of a tree have components.
+ *
+ * @param tree - the tree.
+ */
+export const libraryCount = (tree) => tree.sources.filter((source) => source.families.length > 0).length;
+/**
+ * The pages opened last, under their heading; nothing when there are none.
+ *
+ * @param props - the tree, the recent pages, how to open one, and the heading; "Recently opened" by default.
+ */
+export const RecentSection = ({ tree, recent, hrefOf, onOpen, label = PAGE_STRINGS.recentlyOpened }) => {
+    const entries = recentEntries(tree, recent);
+    return entries.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-recent", children: [_jsx("h2", { id: "forgebook-recent", children: label }), _jsx("ul", { className: "forgebook-home__recent", children: entries.map((entry) => (_jsx("li", { children: _jsxs(PageLink, { page: entry.page, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-home__recent-link", children: [_jsx("span", { className: "forgebook-home__recent-name", children: entry.name }), _jsx("span", { className: "forgebook-home__recent-place", children: entry.place })] }) }, `${entry.page.kind}:${entry.page.id}`))) })] }));
+};
+/**
+ * A library on the home: its name and logo, its introduction, its docs pages and its families.
+ *
+ * @param props - the library, the sources for its introduction, and how to open a page.
+ */
+export const LibrarySection = ({ source, sources, hrefOf, onOpen }) => (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": `forgebook-source-${source.id}`, children: [_jsxs("h2", { id: `forgebook-source-${source.id}`, className: "forgebook-home__source", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 28, height: 28 })), source.name] }), _jsx(SourceIntro, { load: sources.find((candidate) => candidate.id === source.id)?.home }), _jsxs("div", { className: "forgebook-home__families", children: [source.pages.length === 0 ? null : _jsx(DocsCard, { source: source, hrefOf: hrefOf, onOpen: onOpen }), source.families.map((family) => (_jsx(FamilyCard, { family: family, hrefOf: hrefOf, onOpen: onOpen }, family.name)))] })] }));
 /**
  * The home.
  *
  * @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 }) => {
-    const entries = recentEntries(tree, recent);
-    const componentCount = tree.sources.reduce((total, source) => total +
-        source.families.reduce((sum, family) => sum + family.groups.reduce((count, group) => count + group.components.length, 0), 0), 0);
     return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-home", children: [_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: title }), _jsx("p", { className: "forgebook-doc__lead", children: tree.sources.length === 0
-                                        ? STRINGS.homeEmpty
-                                        : STRINGS.homeSummary(componentCount, tree.sources.length) })] }), entries.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-recent", children: [_jsx("h2", { id: "forgebook-recent", children: STRINGS.recentlyOpened }), _jsx("ul", { className: "forgebook-home__recent", children: entries.map((entry) => (_jsx("li", { children: _jsxs(PageLink, { page: entry.page, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-home__recent-link", children: [_jsx("span", { className: "forgebook-home__recent-name", children: entry.name }), _jsx("span", { className: "forgebook-home__recent-place", children: entry.place })] }) }, `${entry.page.kind}:${entry.page.id}`))) })] })), tree.sources.map((source) => (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": `forgebook-source-${source.id}`, children: [_jsxs("h2", { id: `forgebook-source-${source.id}`, className: "forgebook-home__source", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 28, height: 28 })), source.name] }), _jsx(SourceIntro, { load: sources.find((candidate) => candidate.id === source.id)?.home }), _jsx("div", { className: "forgebook-home__families", children: source.families.map((family) => (_jsx(FamilyCard, { source: source, family: family, hrefOf: hrefOf, onOpen: onOpen }, family.name))) })] }, source.id)))] }) })] }));
+                                        ? 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)))] }) })] }));
 };
-//# sourceMappingURL=HomePage.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * The pieces of the generated home a written home places among its own text: the pages opened last (`::recent`), the
+ * libraries (`::libraries`), their families (`::families`) and their docs pages (`::pages`).
+ *
+ * @remarks
+ * Each piece is drawn by the generated home's own components (`HomePage.tsx`), so a written home that places them
+ * looks and behaves as the generated one, and both change together. A piece may show one library (`source="kit"`);
+ * a library the catalogue does not have is said in place.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import type { ReactNode } from "react";
+import type { HomePiece } from "../docPages.ts";
+import type { StoryTree } from "../storyTree.ts";
+import type { RecentPage } from "./useRecentPages.ts";
+/** What the home's pieces read. */
+export type HomePiecesContext = {
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The sources, for their introductions. */
+    readonly sources: readonly StorySource[];
+    /** The pages opened last, the newest first. */
+    readonly recent: readonly RecentPage[];
+    /** A page's address, for its link. */
+    readonly hrefOf: (page: RecentPage) => string;
+    /** Opens a page. */
+    readonly onOpen: (page: RecentPage) => void;
+};
+/**
+ * One piece of the generated home.
+ *
+ * @param props - the piece, its heading, the library it shows alone, and what the pieces read.
+ */
+export declare const HomePieceView: ({ piece, label, source, context }: {
+    readonly piece: HomePiece;
+    readonly label: string | undefined;
+    readonly source: string | undefined;
+    readonly context: HomePiecesContext;
+}) => ReactNode;

package/dist/src/shell/HomePieces.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DocsCard, FamilyCard, LibrarySection, RecentSection } from "./HomePage.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
+/**
+ * A piece's heading, when the home gives it one.
+ *
+ * @param props - the heading.
+ */
+const PieceHeading = ({ label }) => label === undefined ? null : _jsx("h2", { children: label });
+/**
+ * One piece of the generated home.
+ *
+ * @param props - the piece, its heading, the library it shows alone, and what the pieces read.
+ */
+export const HomePieceView = ({ piece, label, source, context }) => {
+    const { tree, sources, recent, hrefOf, onOpen } = context;
+    if (piece === "recent")
+        return _jsx(RecentSection, { tree: tree, recent: recent, hrefOf: hrefOf, onOpen: onOpen, label: label });
+    const shown = source === undefined ? tree.sources : tree.sources.filter((each) => each.id === source);
+    if (source !== undefined && shown.length === 0) {
+        return (_jsx("p", { className: "forgebook-problems", role: "alert", children: PAGE_STRINGS.unknownSource(source) }));
+    }
+    if (piece === "libraries") {
+        return shown.map((each) => (_jsx(LibrarySection, { source: each, sources: sources, hrefOf: hrefOf, onOpen: onOpen }, each.id)));
+    }
+    return (_jsxs("section", { className: "forgebook-doc__section", children: [_jsx(PieceHeading, { label: label }), _jsx("div", { className: "forgebook-home__families", children: piece === "pages"
+                    ? shown.map((each) => each.pages.length === 0 ? null : (_jsx(DocsCard, { source: each, hrefOf: hrefOf, onOpen: onOpen }, each.id)))
+                    : shown.flatMap((each) => each.families.map((family) => (_jsx(FamilyCard, { family: family, hrefOf: hrefOf, onOpen: onOpen }, `${each.id}:${family.name}`)))) })] }));
+};

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

@@ -20,4 +20,3 @@ export declare const InfoTip: ({ note, about }: {
     /** What it is about, for the button's name (`Touch`). */
     readonly about: string;
 }) => ReactNode;
-//# sourceMappingURL=InfoTip.d.ts.map

package/dist/src/shell/InfoTip.js

@@ -50,4 +50,3 @@ export const InfoTip = ({ note, about }) => {
                     hide();
                 }, children: _jsx(Icon, { name: "info", size: 14 }) }), _jsx("span", { ref: noteRef, id: noteId, className: "forgebook-info-tip__note", popover: "manual", role: "tooltip", children: note })] }));
 };
-//# sourceMappingURL=InfoTip.js.map

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

@@ -13,16 +13,9 @@ export type InteractionsTabProps = {
     /** Runs the play again on a fresh mount. */
     readonly onPlayAgain: () => void;
 };
-/**
- * The tab's hint: the play's status.
- *
- * @param trace - the trace.
- */
-export declare const interactionsHint: (trace: PlayTrace) => string;
 /**
  * The Interactions tab.
  *
  * @param props - the trace and how to run the play again.
  */
 export declare const InteractionsTab: ({ trace, onPlayAgain }: InteractionsTabProps) => ReactNode;
-//# sourceMappingURL=InteractionsTab.d.ts.map

package/dist/src/shell/InteractionsTab.js

@@ -1,17 +1,11 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { STRINGS } from "./strings.js";
-/**
- * The tab's hint: the play's status.
- *
- * @param trace - the trace.
- */
-export const interactionsHint = (trace) => STRINGS.playStatus[trace.status];
 /** 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 : ` · ${STRINGS.playTime(ms)}`] }));
+const StatusNote = ({ status, ms }) => (_jsxs("span", { className: "forgebook-play__status", "data-status": status, children: [STRINGS.playStatus[status], ms === undefined ? null : ` · ${LATER_STRINGS.playTime(ms)}`] }));
 /**
  * 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: [STRINGS.playTitle, " ", _jsx(StatusNote, { status: trace.status, ms: trace.ms })] }), _jsx("button", { type: "button", className: "forgebook-button", disabled: trace.status === "running", onClick: onPlayAgain, children: 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: 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))) }))] }));
-//# sourceMappingURL=InteractionsTab.js.map
+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))) }))] }));

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

@@ -0,0 +1,16 @@
+/**
+ * Loads a plugin view's host the first time it is needed, so a catalogue pays nothing for it until then; a host that
+ * cannot load is said in place, and leaves the page standing.
+ *
+ * @module
+ */
+import { type ComponentType, type ReactNode } from "react";
+/**
+ * A host, once its module is there.
+ *
+ * @param props - how it loads, and its own props.
+ */
+export declare const LazyHost: <TProps extends object>({ loadHost, props }: {
+    readonly loadHost: () => Promise<ComponentType<TProps>>;
+    readonly props: TProps;
+}) => ReactNode;

package/dist/src/shell/LazyHost.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Loads a plugin view's host the first time it is needed, so a catalogue pays nothing for it until then; a host that
+ * cannot load is said in place, and leaves the page standing.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+import { LATER_STRINGS } from "./laterStrings.js";
+/**
+ * A host, once its module is there.
+ *
+ * @param props - how it loads, and its own props.
+ */
+export const LazyHost = ({ loadHost, props }) => {
+    const [host, setHost] = useState({
+        status: "loading"
+    });
+    useEffect(() => {
+        let isCurrent = true;
+        loadHost()
+            .then((component) => {
+            if (isCurrent)
+                setHost({ status: "ready", value: { component } });
+        })
+            .catch((error) => {
+            if (isCurrent)
+                setHost({ status: "error", message: error instanceof Error ? error.message : String(error) });
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [loadHost]);
+    if (host.status === "ready") {
+        const Host = host.value.component;
+        return _jsx(Host, { ...props });
+    }
+    if (host.status === "error") {
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.pluginError, ": ", host.message] }));
+    }
+    return _jsx("p", { className: "forgebook-tab-note", children: LATER_STRINGS.pluginLoading });
+};

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

@@ -0,0 +1,24 @@
+/**
+ * A page of the shell other than a story's (the home, a component's page, a docs page), loaded the first time it is
+ * opened (`lazyModule.tsx`): most visits open a story, so their first load leaves these pages out. The workspace and
+ * its header show while the page's code arrives, and the reason when it cannot.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type LazyModule } from "./lazyModule.tsx";
+/** The props of a page drawn from its module. */
+export type LazyPageProps<TProps> = {
+    /** The page's module. */
+    readonly module: LazyModule<TProps>;
+    /** The page's own props. */
+    readonly pageProps: TProps;
+    /** The workspace's header, drawn until the page draws its own. */
+    readonly header: ReactNode;
+};
+/**
+ * A page drawn once its module is there.
+ *
+ * @param props - the page's module, its own props and the header.
+ */
+export declare const LazyPage: <TProps extends object>({ module, pageProps, header }: LazyPageProps<TProps>) => ReactNode;

package/dist/src/shell/LazyPage.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 page drawn once its module is there.
+ *
+ * @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] })] })) }));

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

@@ -7,4 +7,3 @@
 import type { ReactNode } from "react";
 /** The mark. */
 export declare const LogicMark: () => ReactNode;
-//# sourceMappingURL=LogicMark.d.ts.map

package/dist/src/shell/LogicMark.js

@@ -3,4 +3,3 @@ import { Icon } from "./icons.js";
 import { STRINGS } from "./strings.js";
 /** The mark. */
 export const LogicMark = () => (_jsxs("span", { className: "forgebook-logic-mark", title: STRINGS.logicHint, children: [_jsx(Icon, { name: "function", size: 12 }), STRINGS.logic] }));
-//# sourceMappingURL=LogicMark.js.map

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

@@ -21,4 +21,3 @@ export type MatrixPickerProps = {
  * @param props - the props that can make an axis, the chosen ones and the setter.
  */
 export declare const MatrixPicker: ({ props, axes, onAxesChange }: MatrixPickerProps) => ReactNode;
-//# sourceMappingURL=MatrixPicker.d.ts.map

package/dist/src/shell/MatrixPicker.js

@@ -26,4 +26,3 @@ export const MatrixPicker = ({ props, axes, onAxesChange }) => {
                         .filter((prop) => prop.name !== rows)
                         .map((prop) => (_jsx("option", { value: prop.name, children: prop.name }, prop.name)))] })] }));
 };
-//# sourceMappingURL=MatrixPicker.js.map

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

@@ -20,4 +20,3 @@ export declare const NamedViews: ({ view, ownView, onViewChange }: {
     /** Called with the changed view. */
     readonly onViewChange: (view: ViewState) => void;
 }) => ReactNode;
-//# sourceMappingURL=NamedViews.d.ts.map

package/dist/src/shell/NamedViews.js

@@ -11,7 +11,7 @@ import { checkedView, isSameView, namedViewsText, readNamedViews, viewValues, wi
 import { parseView } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
-import { STRINGS } from "./strings.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { useStored } from "./useStored.js";
 /**
  * The named views.
@@ -41,9 +41,8 @@ export const NamedViews = ({ view, ownView, onViewChange }) => {
         event.stopPropagation();
         setIsNaming(false);
     };
-    const chip = (each, isOwn) => (_jsxs("span", { className: "forgebook-named-view", children: [_jsx("button", { type: "button", className: "forgebook-named-view__pick", "aria-pressed": isSameView(each.values, own, catalogue.switches), onClick: () => onViewChange(checkedView(withViewValues(view, each.values), catalogue)), children: each.name }), isOwn ? (_jsx("button", { type: "button", className: "forgebook-named-view__remove", "aria-label": STRINGS.removeView(each.name), title: STRINGS.removeView(each.name), onClick: () => setSaved((current) => withoutView(current, each.name)), children: _jsx(Icon, { name: "close", size: 10 }) })) : null] }, `${isOwn ? "own" : "catalogue"}:${each.name}`));
-    return (_jsxs("section", { className: "forgebook-named-views", "aria-label": STRINGS.namedViews, children: [declared.map((each) => chip(each, false)), saved.map((each) => chip(each, true)), isNaming ? (_jsx("form", { className: "forgebook-named-views__form", onSubmit: save, children: _jsx("input", { type: "text", "aria-label": STRINGS.viewName, placeholder: STRINGS.viewName, value: name, 
+    const chip = (each, isOwn) => (_jsxs("span", { className: "forgebook-named-view", children: [_jsx("button", { type: "button", className: "forgebook-named-view__pick", "aria-pressed": isSameView(each.values, own, catalogue.switches), onClick: () => onViewChange(checkedView(withViewValues(view, each.values), catalogue)), children: each.name }), isOwn ? (_jsx("button", { type: "button", className: "forgebook-named-view__remove", "aria-label": LATER_STRINGS.removeView(each.name), title: LATER_STRINGS.removeView(each.name), onClick: () => setSaved((current) => withoutView(current, each.name)), children: _jsx(Icon, { name: "close", size: 10 }) })) : null] }, `${isOwn ? "own" : "catalogue"}:${each.name}`));
+    return (_jsxs("section", { className: "forgebook-named-views", "aria-label": LATER_STRINGS.namedViews, children: [declared.map((each) => chip(each, false)), saved.map((each) => chip(each, true)), isNaming ? (_jsx("form", { className: "forgebook-named-views__form", onSubmit: save, children: _jsx("input", { type: "text", "aria-label": LATER_STRINGS.viewName, placeholder: LATER_STRINGS.viewName, value: name, 
                     // biome-ignore lint/a11y/noAutofocus: the field opens on the person's press, to be typed in at once
-                    autoFocus: true, onKeyDown: cancel, onChange: (event) => setName(event.target.value) }) })) : (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => setIsNaming(true), children: STRINGS.saveView }))] }));
+                    autoFocus: true, onKeyDown: cancel, onChange: (event) => setName(event.target.value) }) })) : (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => setIsNaming(true), children: LATER_STRINGS.saveView }))] }));
 };
-//# sourceMappingURL=NamedViews.js.map

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

@@ -14,4 +14,3 @@ export declare const PackageHtml: ({ className, html }: {
     readonly className: string;
     readonly html: string;
 }) => ReactNode;
-//# sourceMappingURL=PackageHtml.d.ts.map

package/dist/src/shell/PackageHtml.js

@@ -10,4 +10,3 @@ export const PackageHtml = ({ className, html }) => {
     // biome-ignore lint/security/noDangerouslySetInnerHtml: the package's own Markdown, rendered by the plugin
     return _jsx("div", { className: className, dangerouslySetInnerHTML: markup });
 };
-//# sourceMappingURL=PackageHtml.js.map

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

@@ -6,12 +6,6 @@
  */
 import type { ReactNode } from "react";
 import type { ComponentDocs } from "../componentDocs.ts";
-/**
- * The `data-*` hooks of a component's modifiers.
- *
- * @param docs - the component's docs.
- */
-export declare const styleHooks: (docs: ComponentDocs) => string[];
 /**
  * The Parts and styling tab.
  *
@@ -20,4 +14,3 @@ export declare const styleHooks: (docs: ComponentDocs) => string[];
 export declare const PartsTab: ({ docs }: {
     readonly docs: ComponentDocs;
 }) => ReactNode;
-//# sourceMappingURL=PartsTab.d.ts.map

package/dist/src/shell/PartsTab.js

@@ -1,16 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Code } from "./Code.js";
-import { STRINGS } from "./strings.js";
-/** The props that carry a component's modifiers, each mirrored by a `data-*` styling hook. */
-const MODIFIERS = ["variant", "size", "tone", "shape", "width", "orientation"];
-/**
- * The `data-*` hooks of a component's modifiers.
- *
- * @param docs - the component's docs.
- */
-export const styleHooks = (docs) => docs.props
-    .filter((prop) => prop.kind === "choice" && MODIFIERS.includes(prop.name))
-    .map((prop) => `data-${prop.name}="${(prop.choices ?? []).join(" | ")}"`);
+import { LATER_STRINGS } from "./laterStrings.js";
+import { styleHooks } from "./tabSummaries.js";
 /**
  * The Parts and styling tab.
  *
@@ -18,6 +9,5 @@ export const styleHooks = (docs) => docs.props
  */
 export const PartsTab = ({ docs }) => {
     const hooks = styleHooks(docs);
-    return (_jsxs("div", { className: "forgebook-tab-columns", children: [docs.parts.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.partsList }), _jsxs("p", { className: "forgebook-prop__description", children: [_jsx("code", { children: "classNames" }), ", ", _jsx("code", { children: "styles" }), ", ", _jsx("code", { children: "refs" }), ": ", docs.parts.join(", ")] }), _jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.testIds }), _jsx("p", { className: "forgebook-prop__description", children: docs.parts.map((part) => `<testId>__${part}`).join(", ") })] })), hooks.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.styleHooks }), hooks.map((hook) => (_jsx(Code, { text: hook, names: [] }, hook)))] }))] }));
+    return (_jsxs("div", { className: "forgebook-tab-columns", children: [docs.parts.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: LATER_STRINGS.partsList }), _jsxs("p", { className: "forgebook-prop__description", children: [_jsx("code", { children: "classNames" }), ", ", _jsx("code", { children: "styles" }), ", ", _jsx("code", { children: "refs" }), ": ", docs.parts.join(", ")] }), _jsx("h3", { className: "forgebook-prop-group__title", children: LATER_STRINGS.testIds }), _jsx("p", { className: "forgebook-prop__description", children: docs.parts.map((part) => `<testId>__${part}`).join(", ") })] })), hooks.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: LATER_STRINGS.styleHooks }), hooks.map((hook) => (_jsx(Code, { text: hook, names: [] }, hook)))] }))] }));
 };
-//# sourceMappingURL=PartsTab.js.map

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

@@ -22,4 +22,3 @@ export declare const PinnedControl: ({ control, isHidden, isChanged, layout, ...
     readonly isChanged: boolean;
     readonly layout: ToolbarLayout;
 }) => ReactNode;
-//# sourceMappingURL=PinnedControl.d.ts.map

package/dist/src/shell/PinnedControl.js

@@ -7,9 +7,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @module
  */
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { controlLabel } from "./controlLabel.js";
 import { InfoTip } from "./InfoTip.js";
 import { STRINGS } from "./strings.js";
-import { controlLabel, ToolbarControl } from "./ToolbarControl.js";
+import { ToolbarControl } from "./ToolbarControl.js";
 /** The room the menu keeps from the window's edges, in CSS px. */
 const EDGE_PX = 8;
 /**
@@ -90,4 +91,3 @@ export const PinnedControl = ({ control, isHidden, isChanged, layout, ...context
         // 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 }))] }));
 };
-//# sourceMappingURL=PinnedControl.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * A plugin's block of a docs page: what it is told.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { PluginDocBlockContext, PluginView } from "../plugin.ts";
+import { type StoryTree, type TreeSource } from "../storyTree.ts";
+import type { ViewSwitch } from "../switches.ts";
+import { type ViewState } from "../viewState.ts";
+/** What a block needs of its page. */
+export type PluginBlockPage = {
+    /** The tree, where a story is found. */
+    readonly tree: StoryTree;
+    /** The view. */
+    readonly view: ViewState;
+    /** The frame page's address. */
+    readonly frameUrl: string;
+    /** The catalogue's switches, for a frame's address. */
+    readonly switches: readonly ViewSwitch[];
+    /** The colour a source's stories' page has in the view. */
+    readonly backgroundOf: (source: TreeSource) => string | undefined;
+    /** The texts the catalogue replaces, by name. */
+    readonly strings: Readonly<Record<string, string>>;
+};
+/** The host's props. */
+export type PluginBlockHostProps = {
+    /** Loads the module that draws the block. */
+    readonly load: () => Promise<{
+        readonly view: PluginView<PluginDocBlockContext>;
+    }>;
+    /** The plugin's id, which names its texts. */
+    readonly pluginId: string;
+    /** What the fence's line says after its name. */
+    readonly argument: string;
+    /** The text inside the fence. */
+    readonly body: string;
+    /** Its page. */
+    readonly page: PluginBlockPage;
+};
+/**
+ * A plugin's docs block.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export declare const PluginBlockHost: ({ load, pluginId, argument, body, page }: PluginBlockHostProps) => ReactNode;

package/dist/src/shell/PluginBlockHost.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A plugin's block of a docs page: what it is told.
+ *
+ * @module
+ */
+import { useCallback, useMemo, useRef } from "react";
+import { findStory } from "../storyTree.js";
+import { frameAddress, isComparing, liveView } from "../viewState.js";
+import { showAsideStory } from "./asideStory.js";
+import { PluginViewHost, pluginText, useShellAppearance } from "./PluginViewHost.js";
+import { STRINGS } from "./strings.js";
+/**
+ * A plugin's docs block.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export const PluginBlockHost = ({ load, pluginId, argument, body, page }) => {
+    const appearance = useShellAppearance();
+    // read when the view asks: the page of that moment
+    const pageRef = useRef(page);
+    pageRef.current = page;
+    const showStory = useCallback((target, options) => {
+        const { tree, view, frameUrl, switches, backgroundOf } = pageRef.current;
+        const location = findStory(tree, options.storyId);
+        if (location === undefined)
+            throw new Error(STRINGS.unknownStory(options.storyId));
+        return showAsideStory(target, options.title, {
+            address: frameAddress(frameUrl, options.storyId, view, switches),
+            width: "fill",
+            background: backgroundOf(location.source),
+            args: {},
+            view: isComparing(view) ? undefined : liveView(view)
+        });
+    }, []);
+    const text = useMemo(() => pluginText(page.strings, pluginId), [page.strings, pluginId]);
+    const context = useMemo(() => ({ appearance, text, argument, body, showStory }), [appearance, text, argument, body, showStory]);
+    return _jsx(PluginViewHost, { load: load, context: context });
+};

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

@@ -0,0 +1,32 @@
+/**
+ * A plugin's tab in the panel: what it is told. The dock draws a tab's content only while it is chosen, so a view's own
+ * state goes when another tab is chosen; a frame's report does not, since the stage keeps it.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { JsonValue, PluginStory, PluginTabContext, PluginView } from "../plugin.ts";
+import { type AsideStory } from "./asideStory.ts";
+/** The host's props. */
+export type PluginTabHostProps = {
+    /** Loads the module that draws the tab. */
+    readonly load: () => Promise<{
+        readonly view: PluginView<PluginTabContext>;
+    }>;
+    /** The plugin's id, which names its texts. */
+    readonly pluginId: string;
+    /** The texts the catalogue replaces, by name. */
+    readonly strings: Readonly<Record<string, string>>;
+    /** The story shown. */
+    readonly story: PluginStory;
+    /** What the plugin's frame module last reported; none before it did. */
+    readonly report: JsonValue | undefined;
+    /** How the story is drawn again for the view. */
+    readonly aside: AsideStory;
+};
+/**
+ * A plugin's tab.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export declare const PluginTabHost: ({ load, pluginId, strings, story, report, aside }: PluginTabHostProps) => ReactNode;