forgebook 0.1.8 → 0.2.0

package/dist/src/shell/DeviceSlot.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { deviceDefaultOf, shownDevice } from "../deviceView.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { useSystemDark } from "./useSystemDark.js";
+/** The chunk once it loaded, for every later use; none before. */
+let loadedParts;
+/** The chunk while it loads, so two frames asking at once fetch it once. */
+let loadingParts;
+/**
+ * The device's parts, loaded the first time they are needed.
+ *
+ * @param isNeeded - whether a device is to be drawn.
+ * @returns the parts once loaded; none before, or when the chunk could not be fetched (the story is then shown
+ *   without its device, never broken).
+ */
+export const useDeviceParts = (isNeeded) => {
+    const [parts, setParts] = useState(loadedParts);
+    useEffect(() => {
+        if (!isNeeded || parts !== undefined)
+            return;
+        let isCurrent = true;
+        loadingParts ??= import("./device/deviceParts.js");
+        loadingParts.then((loaded) => {
+            loadedParts = loaded;
+            if (isCurrent)
+                setParts(loaded);
+        }, () => {
+            // a failed fetch is forgotten so a later frame asks again; a browser may keep the failure until a reload,
+            // and the story is shown without its device meanwhile
+            loadingParts = undefined;
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [isNeeded, parts]);
+    return parts;
+};
+/**
+ * The device a story is drawn in, once its parts are there.
+ *
+ * @param shown - the device shown; none for no device.
+ */
+export const useFramedDevice = (shown) => {
+    const parts = useDeviceParts(shown !== undefined);
+    const model = shown?.model;
+    const orientation = shown?.orientation;
+    const isEdgeToEdge = shown?.isEdgeToEdge === true;
+    return useMemo(() => parts === undefined || model === undefined || orientation === undefined
+        ? undefined
+        : {
+            parts,
+            shown: { model, orientation },
+            drawing: parts.drawingOf({ model, orientation }),
+            area: parts.areaOf({ model, orientation }, isEdgeToEdge)
+        }, [parts, model, orientation, isEdgeToEdge]);
+};
+/**
+ * The device a story on the stage is drawn in: the view's choice over the story's and the catalogue's defaults, and
+ * once its parts are there, its screen's width told as the story's width.
+ *
+ * @param view - the view's device.
+ * @param storyDevice - the story's own setting, over the catalogue's.
+ * @param onShownWidthChange - told the width the story really has.
+ */
+export const useStageDevice = (view, storyDevice, onShownWidthChange) => {
+    const shown = shownDevice(view, deviceDefaultOf(useCatalogue().device, storyDevice));
+    const framed = useFramedDevice(shown);
+    const screenWidth = framed?.area.width;
+    useEffect(() => {
+        if (screenWidth !== undefined)
+            onShownWidthChange(screenWidth);
+    }, [screenWidth, onShownWidthChange]);
+    return { shown, framed };
+};
+/**
+ * Whether a story's frame waits for its device's parts before it loads: a story drawn edge to edge is told its safe
+ * areas in its address, which only the parts know, and loading it first would load it twice.
+ *
+ * @param shown - the device shown; none for none.
+ * @param framed - the device once its parts are there.
+ */
+export const isWaitingForDevice = (shown, framed) => shown?.isEdgeToEdge === true && framed === undefined;
+/**
+ * A story frame's address in its device: with the safe areas a story drawn edge to edge is told; as it is otherwise.
+ *
+ * @param address - the frame's address.
+ * @param framed - the device; none for none.
+ */
+export const deviceAddress = (address, framed) => framed === undefined ? address : framed.parts.addressIn(address, framed.area);
+/**
+ * The frame's place, with the device around it when there is one: the parts draw it, this place stays.
+ *
+ * @param props - the device, the story's scheme and page colour, and the frame.
+ */
+export const DeviceSlot = ({ framed, scheme, background, children }) => {
+    const framing = framed?.parts.deviceFraming(framed, scheme, background);
+    return (_jsxs("div", { className: "forgebook-device", ...framing?.root, children: [framing?.under, _jsx("div", { className: "forgebook-device__screen", style: framing?.screen, children: children }), framing?.over] }));
+};
+/**
+ * The scheme a story is drawn in, for the status bar's ink: its colour scheme switch's, the system's for `system`.
+ *
+ * @param scheme - the view's scheme (`schemeOf`).
+ * @param isSystemDark - whether the system is dark.
+ */
+export const inkScheme = (scheme, isSystemDark) => {
+    if (scheme !== "system")
+        return scheme;
+    return isSystemDark ? "dark" : "light";
+};
+/**
+ * The scheme a story is drawn in, for the status bar's ink, following the system's for `system`.
+ *
+ * @param scheme - the view's scheme (`schemeOf`).
+ */
+export const useInkScheme = (scheme) => inkScheme(scheme, useSystemDark());
+/**
+ * The room's sizing with a device: the device's size, no handles (the device sets the width and the height), no
+ * surface of the room's own; the stage's own sizing without one.
+ *
+ * @param framed - the device; none keeps the stage's own.
+ * @param own - the stage's own sizing.
+ */
+export const roomSizing = (framed, own) => framed === undefined
+    ? own
+    : {
+        width: framed.drawing.width,
+        onWidthChange: undefined,
+        onShownWidthChange: undefined,
+        background: undefined,
+        height: "auto",
+        onHeightChange: undefined,
+        isDevice: true
+    };

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

@@ -0,0 +1,100 @@
+/**
+ * The blocks of a docs page: its text, its code, its stories in their frames and its components' API tables.
+ *
+ * @remarks
+ * Each kind of block is one case of `DocBlockView`, and the plugin's compiler gives each its fence or directive, so a
+ * new kind (a table of the catalogue's tokens, a comparison of a story's themes) is one type, one name and one case,
+ * and needs no page of its own. A plugin's block is one of those cases, its view loaded as the page draws it. A
+ * container draws its blocks through the same view, so a story may sit in an aside, a tab or a step. A story's block is
+ * an example of a component's page, without its heading: the page's own text says
+ * what it shows. It loads as it comes near, through the same queue as a component's examples, and its code and a
+ * table's docs wait for that too; each block keeps its place in the page's reading order, however deep it sits. The
+ * written home's pieces (`::families`) draw today's home, from the same components.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ReactNode } from "react";
+import { type DocBlock, type PageValues } from "../docPages.ts";
+import { type StoryTree, type TreeSource } from "../storyTree.ts";
+import type { ViewSwitch } from "../switches.ts";
+import type { ViewState } from "../viewState.ts";
+import { type ExampleContext } from "./Example.tsx";
+import { type HomePiecesContext } from "./HomePieces.tsx";
+import type { ShellPlugin } from "./pluginTabs.tsx";
+import type { PageFrames } from "./usePageFrames.ts";
+/** What every block of a page shares. */
+export type DocBlocksContext = {
+    /** The tree, where the blocks find what they name. */
+    readonly tree: StoryTree;
+    /** The sources, with their loaders. */
+    readonly sources: readonly StorySource[];
+    /** The page's frames. */
+    readonly frames: PageFrames;
+    /** The view. */
+    readonly view: ViewState;
+    /** The frame page's address. */
+    readonly frameUrl: string;
+    /** The plugins, whose blocks the page may hold. */
+    readonly plugins: readonly ShellPlugin[];
+    /** The texts the catalogue replaces, by name. */
+    readonly strings: Readonly<Record<string, string>>;
+    /** The catalogue's switches, for the frames' addresses. */
+    readonly switches: readonly ViewSwitch[];
+    /** The addresses of the page's images. */
+    readonly assets: readonly string[];
+    /** The address of a page of the same source, by its slug and anchor. */
+    readonly pageHrefOf: (slug: string, anchor: string | undefined) => string;
+    /** How a story's links open it. */
+    readonly stories: Pick<ExampleContext, "hrefOf" | "onOpen">;
+    /** Called when the user turns a story's finger on or off. */
+    readonly onTouchChange: (storyId: string, isTouch: boolean) => void;
+    /** A story's measured height, for its box while it loads. */
+    readonly heightOf: (storyId: string) => number | undefined;
+    /** The colour a source's stories' page has in the view, which each box waits on. */
+    readonly backgroundOf: (source: TreeSource) => string | undefined;
+    /** The values the text names (`{{components}}`). */
+    readonly values: PageValues;
+    /** Opens an address of the catalogue a link card names; `false` when it names no page of the catalogue. */
+    readonly onOpenAddress: (href: string) => boolean;
+    /** What the written home's pieces read; none on a docs page, where they are not drawn. */
+    readonly home?: HomePiecesContext;
+    /** Each story's and table's place in the page's reading order, for the queue. */
+    readonly places: ReadonlyMap<DocBlock, number>;
+};
+/**
+ * The values a page's text can name, as the catalogue has them now.
+ *
+ * @param title - the catalogue's name.
+ * @param tree - its tree.
+ */
+export declare const catalogueValues: (title: string, tree: StoryTree) => PageValues;
+/**
+ * Every block of a page in its reading order, a container before what it holds.
+ *
+ * @param blocks - the page's blocks.
+ */
+export declare const readingOrder: (blocks: readonly DocBlock[]) => DocBlock[];
+/**
+ * Each block's place in a page's reading order.
+ *
+ * @param blocks - the page's blocks.
+ */
+export declare const blockPlaces: (blocks: readonly DocBlock[]) => ReadonlyMap<DocBlock, number>;
+/**
+ * What a page's blocks load as they come near, in the page's order: a story by its own id, as its frame reports, though
+ * the page may name it by a former one (`formerStoryId`).
+ *
+ * @param blocks - the page's blocks.
+ * @param tree - the tree, which finds a story by either id.
+ */
+export declare const queuedBlocks: (blocks: readonly DocBlock[], tree: StoryTree) => string[];
+/**
+ * A page's blocks, in the order of its file.
+ *
+ * @param props - the blocks and what they share.
+ */
+export declare const DocBlocks: ({ blocks, context }: {
+    readonly blocks: readonly DocBlock[];
+    readonly context: DocBlocksContext;
+}) => ReactNode;

package/dist/src/shell/DocBlocks.js

@@ -0,0 +1,206 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect } from "react";
+import { isComponentDocs } from "../componentDocs.js";
+import { filledHtml, filledText, linkedHref, linkedHtml } from "../docPages.js";
+import { sourceFiles } from "../sourceFiles.js";
+import { findComponent, findStory, isLogicComponent } from "../storyTree.js";
+import { ApiReference } from "./ApiReference.js";
+import { AsideBlock, CardBlock, CardsBlock, LinkCardBlock, StepsBlock, TabsBlock } from "./DocContainers.js";
+import { Example } from "./Example.js";
+import { componentCount, libraryCount } from "./HomePage.js";
+import { HomePieceView } from "./HomePieces.js";
+import { LazyHost } from "./LazyHost.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { PackageHtml } from "./PackageHtml.js";
+import { MISSING_PLUGIN_HOSTS, usePluginHosts } from "./pluginHostsContext.js";
+import { STRINGS } from "./strings.js";
+import { useComponentDocs } from "./useComponentDocs.js";
+import { useCopy } from "./useCopy.js";
+import { useStoryCode } from "./useStoryCode.js";
+/**
+ * The values a page's text can name, as the catalogue has them now.
+ *
+ * @param title - the catalogue's name.
+ * @param tree - its tree.
+ */
+export const catalogueValues = (title, tree) => ({
+    title,
+    components: String(componentCount(tree)),
+    // the stories the sidebar lists: a story a component keeps out of the list is not one a reader can open
+    stories: String(tree.sources
+        .flatMap((source) => source.families)
+        .flatMap((family) => family.groups)
+        .flatMap((group) => group.components)
+        .reduce((total, component) => total + component.stories.length, 0)),
+    libraries: String(libraryCount(tree)),
+    pages: String(tree.sources.reduce((total, source) => total + source.pages.length, 0))
+});
+/** The blocks a block holds, in their order: none for a block that holds none. */
+const childrenOf = (block) => {
+    switch (block.kind) {
+        case "aside":
+        case "cards":
+        case "card":
+            return block.children;
+        case "tabs":
+            return block.tabs.flatMap((tab) => tab.children);
+        case "steps":
+            return block.steps.flat();
+        default:
+            return [];
+    }
+};
+/**
+ * Every block of a page in its reading order, a container before what it holds.
+ *
+ * @param blocks - the page's blocks.
+ */
+export const readingOrder = (blocks) => blocks.flatMap((block) => [block, ...readingOrder(childrenOf(block))]);
+/**
+ * Each block's place in a page's reading order.
+ *
+ * @param blocks - the page's blocks.
+ */
+export const blockPlaces = (blocks) => new Map(readingOrder(blocks).map((block, place) => [block, place]));
+/** The queue's name for a component's table, apart from the ids of the stories. */
+const propsKey = (id) => `props:${id}`;
+/**
+ * What a page's blocks load as they come near, in the page's order: a story by its own id, as its frame reports, though
+ * the page may name it by a former one (`formerStoryId`).
+ *
+ * @param blocks - the page's blocks.
+ * @param tree - the tree, which finds a story by either id.
+ */
+export const queuedBlocks = (blocks, tree) => readingOrder(blocks).flatMap((block) => {
+    if (block.kind === "story")
+        return [findStory(tree, block.id)?.story.id ?? block.id];
+    return block.kind === "props" ? [propsKey(block.id)] : [];
+});
+/** A block that names what the catalogue does not have: said in place, and in the index's problems. */
+const MissingBlock = ({ message }) => (_jsx("p", { className: "forgebook-problems", role: "alert", children: message }));
+/**
+ * Code the page's text shows, with a button that copies it.
+ *
+ * @param props - the code as copied and as HTML.
+ */
+const CodeBlock = ({ text, html, title, isWrapped }) => {
+    const { isCopied, copy } = useCopy();
+    return (_jsxs("div", { className: "forgebook-docs__code", "data-titled": title !== undefined, "data-wrap": isWrapped, children: [title === undefined ? null : _jsx("p", { className: "forgebook-docs__code-title", children: title }), _jsx("button", { type: "button", className: "forgebook-example__copy", onClick: () => copy(text), "aria-live": "polite", children: isCopied ? STRINGS.copied : LATER_STRINGS.copy }), _jsx(PackageHtml, { className: "forgebook-prose", html: `<pre><code>${html}</code></pre>` })] }));
+};
+/**
+ * A story of the page, in its frame.
+ *
+ * @param props - the story's id, its place in the page and what the blocks share.
+ */
+const StoryBlock = ({ id, place, context }) => {
+    const { frames, tree, sources } = context;
+    const location = findStory(tree, id);
+    // a page may name a story by a former id (`formerStoryId`): its frame reports under its own
+    const storyId = location?.story.id ?? id;
+    const source = sources.find((candidate) => candidate.id === location?.source.id);
+    const isMounted = frames.queue.mounted.has(storyId);
+    // the story's own file: a component may span several (`TreeComponent.files`)
+    const code = useStoryCode(isMounted && source !== undefined && location !== undefined
+        ? sourceFiles(source).code[location.story.file]
+        : undefined);
+    if (location === undefined)
+        return _jsx(MissingBlock, { message: STRINGS.unknownStory(id) });
+    return (_jsx(Example, { ...frames, ...context.stories, component: location.component, view: context.view, frameUrl: context.frameUrl, switches: context.switches, onTouchChange: context.onTouchChange, code: code, componentName: location.component.name, heightOf: context.heightOf, background: context.backgroundOf(location.source), reading: { hasCode: true, isCodeOpen: false, isDemoLarge: false }, story: location.story, isDemo: true, isMounted: isMounted, observe: frames.queue.observerOf(storyId, place) }));
+};
+/**
+ * A component's API table: its docs read only as it comes near, since they wait for the package's types.
+ *
+ * @param props - the component's id and what the blocks share.
+ */
+const PropsBlock = ({ id, context }) => {
+    const { frames, tree, sources } = context;
+    const { queue } = frames;
+    const location = findComponent(tree, id);
+    const source = sources.find((candidate) => candidate.id === location?.source.id);
+    const key = propsKey(id);
+    const docs = useComponentDocs(queue.mounted.has(key) && source !== undefined && location !== undefined
+        ? sourceFiles(source).docs[location.component.file]
+        : undefined);
+    // a component with no docs is over too: "none" counts only once its turn came, since it is also the state before
+    const isOver = queue.mounted.has(key) && docs.status !== "loading";
+    // its place in the queue goes to the next block once it is there: a table holds no frame to wait for
+    useEffect(() => {
+        if (isOver)
+            queue.markReady(key);
+    }, [isOver, key, queue]);
+    if (location === undefined)
+        return _jsx(MissingBlock, { message: STRINGS.unknownComponent(id) });
+    if (docs.status === "error")
+        return _jsx(MissingBlock, { message: `${LATER_STRINGS.pageError}: ${docs.message}` });
+    return (_jsx("div", { ref: queue.observerOf(key), children: docs.status === "ready" && isComponentDocs(docs.value) ? (_jsx(ApiReference, { docs: docs.value, isLogic: isLogicComponent(location.component), componentGroups: location.component.propGroups })) : null }));
+};
+/**
+ * A plugin's block; a fence no plugin of this catalogue draws is said, as a block that names what is not there.
+ *
+ * @param props - the block and what the blocks share.
+ */
+const PluginBlock = ({ block, context }) => {
+    const plugin = context.plugins.find((each) => each.docBlocks.some((candidate) => candidate.fence === block.fence));
+    const load = plugin?.docBlocks.find((candidate) => candidate.fence === block.fence)?.load;
+    const loadHosts = usePluginHosts();
+    // a stable loader: the host loads again whenever it changes
+    const loadBlockHost = useCallback(async () => {
+        if (loadHosts === undefined)
+            throw new Error(MISSING_PLUGIN_HOSTS);
+        return (await loadHosts()).loadBlockHost();
+    }, [loadHosts]);
+    if (plugin === undefined || load === undefined)
+        return _jsx(MissingBlock, { message: block.fence });
+    return (_jsx(LazyHost, { loadHost: loadBlockHost, props: {
+            load,
+            pluginId: plugin.id,
+            argument: block.argument,
+            body: block.body,
+            page: context
+        } }));
+};
+/**
+ * One block of a page.
+ *
+ * @param props - the block and what the blocks share.
+ */
+const DocBlockView = ({ block, context }) => {
+    const inner = (blocks) => _jsx(DocBlocks, { blocks: blocks, context: context });
+    const text = (written) => filledText(written, context.values);
+    switch (block.kind) {
+        case "text":
+            return (_jsx(PackageHtml, { className: "forgebook-prose", html: filledHtml(linkedHtml(block.html, context.pageHrefOf, context.assets), context.values) }));
+        case "code":
+            return (_jsx(CodeBlock, { text: block.text, html: block.html, title: block.title, isWrapped: block.isWrapped === true }));
+        case "story":
+            return _jsx(StoryBlock, { id: block.id, place: context.places.get(block) ?? 0, context: context });
+        case "props":
+            return _jsx(PropsBlock, { id: block.id, context: context });
+        case "aside":
+            return (_jsx(AsideBlock, { tone: block.tone, title: block.title === undefined ? undefined : text(block.title), children: inner(block.children) }));
+        case "tabs":
+            return (_jsx(TabsBlock, { labels: block.tabs.map((tab) => text(tab.label)), sync: block.sync, panels: block.tabs.map((tab) => inner(tab.children)) }));
+        case "steps":
+            return _jsx(StepsBlock, { steps: block.steps.map(inner) });
+        case "cards":
+            return _jsx(CardsBlock, { children: inner(block.children) });
+        case "card":
+            return _jsx(CardBlock, { title: text(block.title), children: inner(block.children) });
+        case "link-card":
+            return (_jsx(LinkCardBlock, { title: text(block.title), description: block.description === undefined ? undefined : text(block.description), href: linkedHref(block.href, context.pageHrefOf), onOpen: context.onOpenAddress }));
+        case "home":
+            return context.home === undefined ? null : (_jsx(HomePieceView, { piece: block.piece, label: block.label === undefined ? undefined : text(block.label), source: block.source, context: context.home }));
+        case "problem":
+            return _jsx(MissingBlock, { message: block.message });
+        case "plugin":
+            return _jsx(PluginBlock, { block: block, context: context });
+        default:
+            return null;
+    }
+};
+/**
+ * A page's blocks, in the order of its file.
+ *
+ * @param props - the blocks and what they share.
+ */
+export const DocBlocks = ({ blocks, context }) => blocks.map((block, place) => (_jsx(DocBlockView, { block: block, context: context }, place)));

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

@@ -0,0 +1,70 @@
+/**
+ * The blocks of a docs page that hold others: an aside, tabs, steps, cards and a link card, each given what it holds
+ * already drawn.
+ *
+ * @remarks
+ * Part of the docs pages' chunk, loaded with the first page or written home that opens, so the shell's first load pays
+ * nothing for them. Each is HTML and the catalogue's style sheet, but the tabs, whose few lines of script pick a panel
+ * and move between tabs with the arrow keys as a tab list does. A panel that is not shown stays in the page, hidden, so a
+ * story in it loads only once its tab is picked, and keeps its frame after.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { AsideTone } from "../docPages.ts";
+/**
+ * A remark set apart, its tone in its colour and its title.
+ *
+ * @param props - its tone, its title (its tone's name when none), and what it holds.
+ */
+export declare const AsideBlock: ({ tone, title, children }: {
+    readonly tone: AsideTone;
+    readonly title: string | undefined;
+    readonly children: ReactNode;
+}) => ReactNode;
+/**
+ * Panels of which one shows at a time, behind a tab list.
+ *
+ * @param props - the tabs' labels, the name they share their choice under, and each panel drawn.
+ */
+export declare const TabsBlock: ({ labels, sync, panels }: {
+    readonly labels: readonly string[];
+    readonly sync: string | undefined;
+    readonly panels: readonly ReactNode[];
+}) => ReactNode;
+/**
+ * Numbered steps, each drawn as a list item with what it holds.
+ *
+ * @param props - each step drawn.
+ */
+export declare const StepsBlock: ({ steps }: {
+    readonly steps: readonly ReactNode[];
+}) => ReactNode;
+/**
+ * Cards side by side, as many to a row as fit.
+ *
+ * @param props - the cards drawn.
+ */
+export declare const CardsBlock: ({ children }: {
+    readonly children: ReactNode;
+}) => ReactNode;
+/**
+ * A card with a title and what it holds.
+ *
+ * @param props - its title and what it holds.
+ */
+export declare const CardBlock: ({ title, children }: {
+    readonly title: string;
+    readonly children: ReactNode;
+}) => ReactNode;
+/**
+ * A card that links somewhere: a page of the catalogue opens in place, another site in a new tab.
+ *
+ * @param props - its title, its description, its address, and how the catalogue opens one of its own.
+ */
+export declare const LinkCardBlock: ({ title, description, href, onOpen }: {
+    readonly title: string;
+    readonly description: string | undefined;
+    readonly href: string;
+    readonly onOpen: (href: string) => boolean;
+}) => ReactNode;

package/dist/src/shell/DocContainers.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The blocks of a docs page that hold others: an aside, tabs, steps, cards and a link card, each given what it holds
+ * already drawn.
+ *
+ * @remarks
+ * Part of the docs pages' chunk, loaded with the first page or written home that opens, so the shell's first load pays
+ * nothing for them. Each is HTML and the catalogue's style sheet, but the tabs, whose few lines of script pick a panel
+ * and move between tabs with the arrow keys as a tab list does. A panel that is not shown stays in the page, hidden, so a
+ * story in it loads only once its tab is picked, and keeps its frame after.
+ *
+ * @module
+ */
+import { useId, useRef } from "react";
+import { Icon } from "./icons.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
+import { useSyncedTab } from "./useSyncedTab.js";
+/**
+ * A remark set apart, its tone in its colour and its title.
+ *
+ * @param props - its tone, its title (its tone's name when none), and what it holds.
+ */
+export const AsideBlock = ({ tone, title, children }) => {
+    const id = useId();
+    return (_jsxs("aside", { className: "forgebook-aside", "data-tone": tone, "aria-labelledby": id, children: [_jsx("p", { id: id, className: "forgebook-aside__title", children: title ?? PAGE_STRINGS.asides[tone] }), children] }));
+};
+/**
+ * The tab a key moves to in a tab list: the next or the one before, round the ends, or the first or the last.
+ *
+ * @param key - the key pressed.
+ * @param shown - the place of the tab shown.
+ * @param count - how many tabs there are.
+ * @returns the place to move to; none for a key that moves nowhere.
+ */
+const keyedTab = (key, shown, count) => {
+    if (key === "ArrowRight")
+        return (shown + 1) % count;
+    if (key === "ArrowLeft")
+        return (shown - 1 + count) % count;
+    if (key === "Home")
+        return 0;
+    return key === "End" ? count - 1 : undefined;
+};
+/**
+ * Panels of which one shows at a time, behind a tab list.
+ *
+ * @param props - the tabs' labels, the name they share their choice under, and each panel drawn.
+ */
+export const TabsBlock = ({ labels, sync, panels }) => {
+    const id = useId();
+    const [shown, pick] = useSyncedTab(labels, sync);
+    const list = useRef(null);
+    const move = (event) => {
+        const target = keyedTab(event.key, shown, labels.length);
+        if (target === undefined)
+            return;
+        event.preventDefault();
+        pick(target);
+        list.current?.querySelectorAll('[role="tab"]')[target]?.focus();
+    };
+    return (_jsxs("div", { className: "forgebook-tabs", children: [_jsx("div", { ref: list, className: "forgebook-tabs__list", role: "tablist", onKeyDown: move, children: labels.map((label, place) => (_jsx("button", { type: "button", role: "tab", id: `${id}-tab-${place}`, className: "forgebook-tabs__tab", "aria-selected": place === shown, "aria-controls": `${id}-panel-${place}`, tabIndex: place === shown ? 0 : -1, onClick: () => pick(place), children: label }, place))) }), panels.map((panel, place) => (_jsx("div", { role: "tabpanel", id: `${id}-panel-${place}`, "aria-labelledby": `${id}-tab-${place}`, className: "forgebook-tabs__panel", hidden: place !== shown, children: panel }, place)))] }));
+};
+/**
+ * Numbered steps, each drawn as a list item with what it holds.
+ *
+ * @param props - each step drawn.
+ */
+export const StepsBlock = ({ steps }) => (_jsx("ol", { className: "forgebook-steps", children: steps.map((step, place) => (_jsx("li", { className: "forgebook-steps__step", children: step }, place))) }));
+/**
+ * Cards side by side, as many to a row as fit.
+ *
+ * @param props - the cards drawn.
+ */
+export const CardsBlock = ({ children }) => (_jsx("div", { className: "forgebook-cards", children: children }));
+/**
+ * A card with a title and what it holds.
+ *
+ * @param props - its title and what it holds.
+ */
+export const CardBlock = ({ title, children }) => (_jsxs("section", { className: "forgebook-card", "aria-label": title === "" ? undefined : title, children: [title === "" ? null : _jsx("p", { className: "forgebook-card__title", children: title }), children] }));
+/**
+ * A card that links somewhere: a page of the catalogue opens in place, another site in a new tab.
+ *
+ * @param props - its title, its description, its address, and how the catalogue opens one of its own.
+ */
+export const LinkCardBlock = ({ title, description, href, onOpen }) => {
+    const isOther = /^(https?:|mailto:)/i.test(href);
+    return (_jsxs("a", { className: "forgebook-card forgebook-card--link", href: href, ...(isOther ? { target: "_blank", rel: "noreferrer" } : {}), onClick: (event) => {
+            if (isOther || event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                return;
+            if (onOpen(href))
+                event.preventDefault();
+        }, children: [_jsxs("span", { className: "forgebook-card__title", children: [title, _jsx(Icon, { name: isOther ? "external" : "chevronRight", size: 12 })] }), description === undefined ? null : _jsx("span", { className: "forgebook-card__description", children: description })] }));
+};

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

@@ -0,0 +1,29 @@
+/**
+ * A docs page's contents: its second- and third-level headings, the one being read marked, as a column beside the text
+ * where there is room and a list that folds above it where there is not.
+ *
+ * @module
+ */
+import { type ReactNode, type RefObject } from "react";
+import { type DocHeading, type PageValues } from "../docPages.ts";
+/** The contents' props. */
+export type DocContentsProps = {
+    /** The page's headings. */
+    readonly headings: readonly DocHeading[];
+    /** The values a heading's text names (`{{title}}`). */
+    readonly values: PageValues;
+    /** The page's scrolling element. */
+    readonly scrollRef: RefObject<HTMLElement | null>;
+    /** Whether there is room for a column beside the text. */
+    readonly isColumn: boolean;
+    /** A heading's address, for its link. */
+    readonly hrefOf: (anchor: string) => string;
+    /** Goes to a heading. */
+    readonly onOpen: (anchor: string) => void;
+};
+/**
+ * A page's contents; nothing for a page with fewer than two headings, which has nothing to find.
+ *
+ * @param props - the headings, the page's scrolling element, whether there is room for a column, and the links.
+ */
+export declare const DocContents: ({ headings, values, scrollRef, isColumn, hrefOf, onOpen }: DocContentsProps) => ReactNode;