forgebook 0.0.0-stage → 0.1.2

package/dist/src/shell/ComponentPage.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo, useRef, useState } from "react";
+import { groupLabel } from "../catalogue.js";
+import { groupedStories, mainStory } from "../storyTree.js";
+import { frameAddress, liveView } from "../viewState.js";
+import { ApiReference } from "./ApiReference.js";
+import { CodeText } from "./CodeText.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { useCodeWriter } from "./codeWriter.js";
+import { FrameView } from "./FrameView.js";
+import { Icon } from "./icons.js";
+import { PackageHtml } from "./PackageHtml.js";
+import { StageViewport } from "./StageViewport.js";
+import { StoryCodeBlock, storyCodeText } from "./StoryCodeBlock.js";
+import { STRINGS } from "./strings.js";
+import { useComponentDocs } from "./useComponentDocs.js";
+import { useCopy } from "./useCopy.js";
+import { useFrameMessages } from "./useFrameMessages.js";
+import { useFrameQueue } from "./useFrameQueue.js";
+import { useLiveView, useLoadedView } from "./useLiveView.js";
+import { usePageDoc } from "./usePageDoc.js";
+import { useScrollMemory } from "./useScrollMemory.js";
+import { useStoryCode } from "./useStoryCode.js";
+/** The height of a frame before its story reports its own, in CSS px. */
+const FALLBACK_HEIGHT = 160;
+/** The demo's height before its story reports its own, in CSS px: the demo is the page's first, larger frame. */
+const DEMO_FALLBACK_HEIGHT = 280;
+/** A link to a story's own page, opened in place unless the user asks for another tab. */
+const StoryLink = ({ story, hrefOf, onOpen, className, children }) => (_jsx("a", { className: className, href: hrefOf(story), onClick: (event) => {
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+            return;
+        event.preventDefault();
+        onOpen(story);
+    }, children: children }));
+/**
+ * The code under an example: closed until asked for, then opened in place with a button that copies it.
+ *
+ * @param props - the story's code and whether it is shown.
+ */
+const ExampleCode = ({ id, source, isShown }) => {
+    const { isCopied, copy } = useCopy();
+    const write = useCodeWriter();
+    return (_jsx("div", { id: id, className: "forgebook-example__code", "data-open": isShown ? "" : undefined, inert: !isShown, children: _jsxs("div", { className: "forgebook-example__code-inner", children: [_jsx("button", { type: "button", className: "forgebook-example__copy", onClick: () => copy(storyCodeText(source, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : STRINGS.copy }), _jsx(StoryCodeBlock, { ...source })] }) }));
+};
+/**
+ * One example: its title and description (the demo has none: it opens the page), its story in a frame, and a bar
+ * that shows its code.
+ *
+ * @param props - the story, whether it is the demo, whether its frame may load, where the queue watches it, and what
+ * every example shares.
+ */
+const Example = ({ story, isDemo, isMounted, observe, ...context }) => {
+    const [isCodeShown, setIsCodeShown] = useState(false);
+    const codeId = useId();
+    // the story's measured height when there is one; a guess otherwise, larger for the demo; never below the height its
+    // scene needs, which its frame has from the start
+    const fallbackHeight = Math.max(story.height ?? 0, context.heightOf(story.id) ?? (isDemo ? DEMO_FALLBACK_HEIGHT : FALLBACK_HEIGHT));
+    const source = context.code.status === "ready"
+        ? {
+            code: context.code.value,
+            exportName: story.exportName,
+            componentName: context.componentName,
+            args: context.argsOf(story.id)
+        }
+        : undefined;
+    return (_jsxs("article", { ref: observe, className: "forgebook-example", "data-demo": isDemo ? "" : undefined, "aria-label": isDemo ? STRINGS.frameTitle(context.component.name, story.name) : story.name, children: [isDemo ? null : (_jsxs("header", { className: "forgebook-example__head", children: [_jsx("h4", { className: "forgebook-example__title", children: _jsx(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-link", children: story.name }) }), story.description === undefined ? null : (_jsx("p", { className: "forgebook-example__description", children: _jsx(CodeText, { text: story.description }) }))] })), _jsxs("div", { className: "forgebook-example__box", children: [_jsx("div", { className: "forgebook-example__stage", children: _jsx(StageViewport, { width: context.view.width, background: context.background, children: isMounted ? (_jsx(FrameView, { title: STRINGS.frameTitle(context.component.name, story.name), address: frameAddress(context.frameUrl, story.id, context.frameView, context.switches), heights: context.heights, settled: context.settled, fallbackHeight: fallbackHeight, sceneHeight: story.height })) : (_jsx("div", { className: "forgebook-frame-placeholder", style: { height: fallbackHeight } })) }) }), _jsxs("div", { className: "forgebook-example__bar", children: [source === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-example__toggle", "aria-expanded": isCodeShown, "aria-controls": codeId, onClick: () => setIsCodeShown(!isCodeShown), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), isCodeShown ? STRINGS.hideCode : STRINGS.showCode] })), isDemo ? (_jsxs(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-example__open", children: [STRINGS.openStory, _jsx(Icon, { name: "external", size: 12 })] })) : null] }), source === undefined ? null : _jsx(ExampleCode, { id: codeId, source: source, isShown: isCodeShown })] })] }));
+};
+/**
+ * The page's lead: what the component is and does, from its file's `@module` comment (its own TSDoc is often a bare
+ * name), read with the documentation file so it comes with the page; else its TSDoc summary, once the docs come.
+ *
+ * @param props - the loaded page and the component's docs.
+ */
+const Lead = ({ page, docs }) => {
+    const summary = page.status === "ready" ? page.value.summary : "";
+    const lead = summary || docs?.summary || docs?.description || "";
+    return lead === "" ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: lead }) }));
+};
+/**
+ * The documentation file's text, or why it could not be read.
+ *
+ * @param props - the loaded page.
+ */
+const Prose = ({ page }) => {
+    if (page.status === "error") {
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.pageError, ": ", page.message] }));
+    }
+    if (page.status !== "ready" || page.value.html === "")
+        return null;
+    return _jsx(PackageHtml, { className: "forgebook-prose", html: page.value.html });
+};
+/**
+ * A component's page.
+ *
+ * @param props - the component, the view, its loaders and how to open a story.
+ */
+export const ComponentPage = ({ component, view, frameUrl, hrefOf, onOpen, loadDocs, loadCode, loadPage, heightOf, background, header, scroll }) => {
+    const pageRef = useRef(null);
+    const docs = useComponentDocs(loadDocs);
+    const code = useStoryCode(loadCode);
+    const page = usePageDoc(loadPage);
+    // each story's own args, as its frame reports them: the code of a story drawn from its args is written from them
+    const [storyArgs, setStoryArgs] = useState(new Map());
+    const demo = mainStory(component);
+    const examples = useMemo(() => component.stories.filter((story) => story.id !== demo?.id), [component, demo]);
+    // the frames keep the view they loaded with; only the style sheets load them again, the rest of the view (the
+    // switches, the language among them) is sent to them live
+    const frameView = useLoadedView(view.sheets, view);
+    const catalogue = useCatalogue();
+    const { switches } = catalogue;
+    const exampleIds = useMemo(() => examples.map((story) => story.id), [examples]);
+    const queue = useFrameQueue(exampleIds, pageRef);
+    const { heights, settled } = useFrameMessages({
+        onReady: (frame, message) => {
+            queue.markReady(message.storyId);
+            setStoryArgs((current) => new Map(current).set(message.storyId, message.args));
+            const send = (shellMessage) => frame.postMessage(shellMessage, window.location.origin);
+            send({ type: "forgebook:view", view: liveView(view) });
+            send({ type: "forgebook:tools", tools: view.tools });
+        },
+        onCall: () => undefined,
+        // a frame that failed is over too: its place in the queue goes to the next one
+        onFailed: queue.markReady
+    });
+    useLiveView(pageRef, view, true);
+    useScrollMemory(pageRef, scroll);
+    const componentDocs = docs.status === "ready" ? docs.value : undefined;
+    const context = {
+        component,
+        view,
+        frameUrl,
+        hrefOf,
+        onOpen,
+        frameView,
+        switches,
+        heights,
+        settled,
+        code,
+        componentName: componentDocs?.name ?? component.name,
+        argsOf: (storyId) => storyArgs.get(storyId) ?? {},
+        heightOf,
+        background
+    };
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", children: [_jsx(Lead, { page: page, docs: componentDocs }), demo === undefined ? null : _jsx(Example, { ...context, story: demo, isDemo: true, isMounted: true }), _jsx(Prose, { page: page }), componentDocs === undefined || componentDocs.props.length === 0 ? null : (_jsx(ApiReference, { docs: componentDocs })), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, isMounted: queue.mounted.has(story.id), observe: (element) => queue.observe(story.id, element) }, story.id)))] }, section.group ?? "")))] }))] }, `${component.file}|${component.title}`) })] }));
+};
+//# sourceMappingURL=ComponentPage.js.map

package/dist/src/shell/ComponentPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentPage.js","sourceRoot":"","sources":["../../../src/shell/ComponentPage.tsx"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,42 @@
+/**
+ * The panel docked under a story: a row of tabs (Props, Events, Parts and styling, Code, Accessibility) and the chosen
+ * tab's content, which scrolls on its own, so reading the props or the code never moves the story away.
+ *
+ * @remarks
+ * The tabs follow the ARIA tabs pattern: the arrow keys move between them, Home and End go to the ends. The handle on
+ * the top edge sets the panel's height (dragged, or with the arrow keys); the height is a convenience of this browser,
+ * kept in its storage, not in the address. Only the tabs the story has something for are shown.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { PanelTab } from "../viewState.ts";
+/** One tab of the panel. */
+export type DockTab = {
+    /** The tab's id, kept in the address. */
+    readonly id: PanelTab;
+    /** The tab's name. */
+    readonly label: string;
+    /** A short note beside the name (a count); none by default. */
+    readonly hint?: string | undefined;
+    /** What the tab shows. */
+    readonly content: ReactNode;
+};
+/** The dock's props. */
+export type DockProps = {
+    /** The tabs the story has something for, in order. */
+    readonly tabs: readonly DockTab[];
+    /** The chosen tab; the first tab shows when the story has nothing for it. */
+    readonly activeTab: PanelTab;
+    /** Called with the tab chosen. */
+    readonly onTabChange: (tab: PanelTab) => void;
+    /** Closes the panel. */
+    readonly onClose: () => void;
+};
+/**
+ * The panel under a story.
+ *
+ * @param props - the tabs, the chosen one and the setters.
+ */
+export declare const Dock: ({ tabs, activeTab, onTabChange, onClose }: DockProps) => ReactNode;
+//# sourceMappingURL=Dock.d.ts.map

package/dist/src/shell/Dock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dock.d.ts","sourceRoot":"","sources":["../../../src/shell/Dock.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAyC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAE7F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAKhD,4BAA4B;AAC5B,MAAM,MAAM,OAAO,GAAG;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;CAC7B,CAAC;AAEF,wBAAwB;AACxB,MAAM,MAAM,SAAS,GAAG;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC9C,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAkBF;;;;GAIG;AACH,eAAO,MAAM,IAAI,GAAI,2CAA2C,SAAS,KAAG,SA+G3E,CAAC"}

package/dist/src/shell/Dock.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The panel docked under a story: a row of tabs (Props, Events, Parts and styling, Code, Accessibility) and the chosen
+ * tab's content, which scrolls on its own, so reading the props or the code never moves the story away.
+ *
+ * @remarks
+ * The tabs follow the ARIA tabs pattern: the arrow keys move between them, Home and End go to the ends. The handle on
+ * the top edge sets the panel's height (dragged, or with the arrow keys); the height is a convenience of this browser,
+ * kept in its storage, not in the address. Only the tabs the story has something for are shown.
+ *
+ * @module
+ */
+import { useId, useRef } from "react";
+import { Icon } from "./icons.js";
+import { STRINGS } from "./strings.js";
+import { useStored } from "./useStored.js";
+/** The panel's height, in CSS px: the default, the bounds a drag keeps to, and one arrow key's step. */
+const HEIGHT = { initial: 300, min: 120, step: 24 };
+/** Where this browser keeps the panel's height. */
+const HEIGHT_KEY = "dock-height";
+/** The height a stored text holds, or the default. */
+const storedHeight = (stored) => {
+    const value = Number(stored);
+    return stored !== null && Number.isFinite(value) && value >= HEIGHT.min ? value : HEIGHT.initial;
+};
+/** A height kept between the minimum and most of the window, so the story always keeps some room. */
+const boundedHeight = (height) => Math.round(Math.min(window.innerHeight * 0.8, Math.max(HEIGHT.min, height)));
+/**
+ * The panel under a story.
+ *
+ * @param props - the tabs, the chosen one and the setters.
+ */
+export const Dock = ({ tabs, activeTab, onTabChange, onClose }) => {
+    const [height, setHeight] = useStored(HEIGHT_KEY, storedHeight, (value) => String(Math.round(value)));
+    const tabRefs = useRef(new Map());
+    const baseId = useId();
+    const shown = tabs.find((tab) => tab.id === activeTab) ?? tabs[0];
+    const startResize = (event) => {
+        if (event.button !== 0)
+            return;
+        event.preventDefault();
+        const handle = event.currentTarget;
+        handle.setPointerCapture(event.pointerId);
+        const startY = event.clientY;
+        const startHeight = height;
+        const move = (moveEvent) => setHeight(boundedHeight(startHeight + startY - moveEvent.clientY));
+        const end = () => {
+            handle.removeEventListener("pointermove", move);
+            handle.removeEventListener("pointerup", end);
+            handle.removeEventListener("pointercancel", end);
+        };
+        handle.addEventListener("pointermove", move);
+        handle.addEventListener("pointerup", end);
+        handle.addEventListener("pointercancel", end);
+    };
+    const resizeWithKeys = (event) => {
+        if (event.key === "ArrowUp")
+            setHeight(boundedHeight(height + HEIGHT.step));
+        else if (event.key === "ArrowDown")
+            setHeight(boundedHeight(height - HEIGHT.step));
+        else
+            return;
+        event.preventDefault();
+    };
+    const moveFocus = (event) => {
+        const index = tabs.findIndex((tab) => tab.id === shown?.id);
+        const targets = {
+            ArrowRight: (index + 1) % tabs.length,
+            ArrowLeft: (index - 1 + tabs.length) % tabs.length,
+            Home: 0,
+            End: tabs.length - 1
+        };
+        const next = tabs[targets[event.key] ?? -1];
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        onTabChange(next.id);
+        tabRefs.current.get(next.id)?.focus();
+    };
+    return (_jsxs("section", { className: "forgebook-dock", style: { height }, "aria-label": STRINGS.panel, children: [_jsx("div", { className: "forgebook-dock__handle", role: "separator", "aria-orientation": "horizontal", "aria-label": STRINGS.panelHeight, "aria-valuenow": height, "aria-valuemin": HEIGHT.min, tabIndex: 0, onPointerDown: startResize, onKeyDown: resizeWithKeys }), _jsxs("div", { className: "forgebook-dock__bar", children: [_jsx("div", { className: "forgebook-dock__tabs", role: "tablist", "aria-label": STRINGS.panel, onKeyDown: moveFocus, children: tabs.map((tab) => {
+                            const isActive = tab.id === shown?.id;
+                            return (_jsxs("button", { ref: (element) => {
+                                    if (element === null)
+                                        tabRefs.current.delete(tab.id);
+                                    else
+                                        tabRefs.current.set(tab.id, element);
+                                }, type: "button", role: "tab", id: `${baseId}-${tab.id}`, className: "forgebook-dock__tab", "aria-selected": isActive, "aria-controls": `${baseId}-panel`, tabIndex: isActive ? 0 : -1, onClick: () => onTabChange(tab.id), children: [tab.label, tab.hint === undefined ? null : _jsx("span", { className: "forgebook-dock__hint", children: tab.hint })] }, tab.id));
+                        }) }), _jsx("button", { type: "button", className: "forgebook-icon-button", title: STRINGS.closePanel, "aria-label": STRINGS.closePanel, onClick: onClose, children: _jsx(Icon, { name: "close", size: 14 }) })] }), shown === undefined ? null : (_jsx("div", { id: `${baseId}-panel`, className: "forgebook-dock__body", role: "tabpanel", "aria-labelledby": `${baseId}-${shown.id}`, children: shown.content }))] }));
+};
+//# sourceMappingURL=Dock.js.map

package/dist/src/shell/Dock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dock.js","sourceRoot":"","sources":["../../../src/shell/Dock.tsx"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,25 @@
+/**
+ * The panel's Events tab: each event of the component with its signature highlighted and its description, then the
+ * calls the story made, newest first.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { PropDocs } from "../componentDocs.ts";
+import type { EventCall } from "./useFrameMessages.ts";
+/** The tab's props. */
+export type EventsTabProps = {
+    /** The component's events (its `on…` props). */
+    readonly events: readonly PropDocs[];
+    /** The calls received, newest first. */
+    readonly calls: readonly EventCall[];
+    /** Clears the calls. */
+    readonly onClearCalls: () => void;
+};
+/**
+ * The Events tab.
+ *
+ * @param props - the events, the calls and how to clear them.
+ */
+export declare const EventsTab: ({ events, calls, onClearCalls }: EventsTabProps) => ReactNode;
+//# sourceMappingURL=EventsTab.d.ts.map

package/dist/src/shell/EventsTab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventsTab.d.ts","sourceRoot":"","sources":["../../../src/shell/EventsTab.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,uBAAuB;AACvB,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,wBAAwB;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AA2BF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,iCAAiC,cAAc,KAAG,SAmC3E,CAAC"}

package/dist/src/shell/EventsTab.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Code } from "./Code.js";
+import { STRINGS } from "./strings.js";
+/** An event's signature as TypeScript would write it. */
+const signatureText = (event) => event.signature === undefined
+    ? event.type
+    : `(${event.signature.parameters.map((parameter) => `${parameter.name}: ${parameter.type}`).join(", ")}) => ${event.signature.returns}`;
+/**
+ * One call: the event with its arguments written short, opening on their content when one is an object or a list.
+ *
+ * @param props - the call.
+ */
+const CallLine = ({ call }) => {
+    const line = _jsx(Code, { text: `${call.name}(${call.values.join(", ")})`, names: [call.name] });
+    const details = call.details.filter((detail) => detail !== null);
+    if (details.length === 0)
+        return line;
+    return (_jsxs("details", { className: "forgebook-calls__details", children: [_jsx("summary", { children: line }), _jsx("pre", { className: "forgebook-code-block", children: _jsx(Code, { text: details.join("\n"), names: [] }) })] }));
+};
+/**
+ * The Events tab.
+ *
+ * @param props - the events, the calls and how to clear them.
+ */
+export const EventsTab = ({ events, calls, onClearCalls }) => (_jsxs("div", { className: "forgebook-tab-columns", children: [_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.events }), events.map((event) => (_jsxs("div", { className: "forgebook-event", children: [_jsx("code", { className: "forgebook-prop__name", children: event.name }), _jsx(Code, { text: signatureText(event), names: event.signature?.parameters.map((parameter) => parameter.name) ?? [] }), _jsx("p", { className: "forgebook-prop__description", children: event.description })] }, event.name)))] }), _jsxs("div", { className: "forgebook-prop-group forgebook-calls", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.calls }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: onClearCalls, children: STRINGS.clearCalls })] }), calls.length === 0 ? _jsx("p", { className: "forgebook-prop__description", children: STRINGS.noCalls }) : null, _jsx("ol", { className: "forgebook-calls__list", "aria-live": "polite", children: calls.map((call) => (_jsxs("li", { className: "forgebook-calls__item", children: [_jsx(CallLine, { call: call }), _jsx("time", { className: "forgebook-calls__time", dateTime: new Date(call.time).toISOString(), children: new Date(call.time).toLocaleTimeString() })] }, `${call.time}-${call.name}-${call.values.join(",")}`))) })] })] }));
+//# sourceMappingURL=EventsTab.js.map

package/dist/src/shell/EventsTab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventsTab.js","sourceRoot":"","sources":["../../../src/shell/EventsTab.tsx"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,49 @@
+/**
+ * A story's frame as the shell shows it, as tall as its story (or the room its scene declares) and showing that it loads until it is ready, and how the shell talks to the frames of a page: the
+ * story page and the component page use both.
+ *
+ * @module
+ */
+import type { ReactNode, Ref } from "react";
+import type { ShellMessage } from "../messages.ts";
+/** The frame view's props. */
+export type FrameViewProps = {
+    /** The frame's accessible title. */
+    readonly title: string;
+    /** The frame's address. */
+    readonly address: string;
+    /** Each frame's reported height, by its address. */
+    readonly heights: ReadonlyMap<string, number>;
+    /** The height until the frame reports its own, in CSS px. */
+    readonly fallbackHeight: number;
+    /**
+     * The height the story's scene needs (its `parameters.height`), in CSS px: the frame is never shorter, from the
+     * start, so the window an overlay is placed in has that room while the story's document stays as tall as its
+     * content. None by default.
+     */
+    readonly sceneHeight?: number | undefined;
+    /**
+     * A height set on the stage (the foot handle, note 142), in CSS px: the frame takes it whatever its story's;
+     * none by default.
+     */
+    readonly fixedHeight?: number | undefined;
+    /** The addresses of the frames that finished loading: until its own is there, the frame shows that it loads. */
+    readonly settled: ReadonlySet<string>;
+    /** The iframe. */
+    readonly ref?: Ref<HTMLIFrameElement>;
+};
+/**
+ * A story's frame, as tall as its story.
+ *
+ * @param props - the frame's title, address, the reported heights, the height until its own arrives, and the frames
+ * that finished loading.
+ */
+export declare const FrameView: ({ title, address, heights, fallbackHeight, settled, sceneHeight, fixedHeight, ref }: FrameViewProps) => ReactNode;
+/**
+ * Sends a message to every frame inside an element.
+ *
+ * @param container - the element that holds the frames.
+ * @param message - the message.
+ */
+export declare const tellFrames: (container: HTMLElement | null, message: ShellMessage) => void;
+//# sourceMappingURL=FrameView.d.ts.map

package/dist/src/shell/FrameView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrameView.d.ts","sourceRoot":"","sources":["../../../src/shell/FrameView.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,gHAAgH;IAChH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,kBAAkB;IAClB,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,qFASvB,cAAc,KAAG,SAqBnB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,WAAW,GAAG,IAAI,EAAE,SAAS,YAAY,KAAG,IAIjF,CAAC"}

package/dist/src/shell/FrameView.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { STRINGS } from "./strings.js";
+/**
+ * A story's frame, as tall as its story.
+ *
+ * @param props - the frame's title, address, the reported heights, the height until its own arrives, and the frames
+ * that finished loading.
+ */
+export const FrameView = ({ title, address, heights, fallbackHeight, settled, sceneHeight = 0, fixedHeight, ref }) => {
+    const isLoading = !settled.has(address);
+    // while it loads, an empty document reports a height of nothing: the box keeps its waiting height until the story
+    // is there, then takes the story's
+    const reported = heights.get(address);
+    const contentHeight = isLoading ? Math.max(reported ?? 0, fallbackHeight) : (reported ?? fallbackHeight);
+    const height = fixedHeight ?? Math.max(contentHeight, sceneHeight);
+    return (_jsxs("div", { className: "forgebook-frame-box", "data-loading": isLoading ? "" : undefined, children: [_jsx("iframe", { ref: ref, className: "forgebook-frame-view", title: title, src: address, style: { height } }), isLoading ? (_jsx("div", { className: "forgebook-frame-loading", role: "status", children: _jsxs("span", { className: "forgebook-frame-loading__label", children: [_jsx("span", { className: "forgebook-spinner", "aria-hidden": "true" }), STRINGS.loadingStory] }) })) : null] }));
+};
+/**
+ * Sends a message to every frame inside an element.
+ *
+ * @param container - the element that holds the frames.
+ * @param message - the message.
+ */
+export const tellFrames = (container, message) => {
+    for (const frame of container?.querySelectorAll("iframe") ?? []) {
+        frame.contentWindow?.postMessage(message, window.location.origin);
+    }
+};
+//# sourceMappingURL=FrameView.js.map

package/dist/src/shell/FrameView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrameView.js","sourceRoot":"","sources":["../../../src/shell/FrameView.tsx"],"names":[],"mappings":";AASA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA6BvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EACxB,KAAK,EACL,OAAO,EACP,OAAO,EACP,cAAc,EACd,OAAO,EACP,WAAW,GAAG,CAAC,EACf,WAAW,EACX,GAAG,EACY,EAAa,EAAE;IAC9B,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxC,kHAAkH;IAClH,mCAAmC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,cAAc,CAAC,CAAC;IACzG,MAAM,MAAM,GAAG,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IACnE,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,kBAAe,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,aAC3E,iBAAQ,GAAG,EAAE,GAAG,EAAE,SAAS,EAAC,sBAAsB,EAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAI,EAEnG,SAAS,CAAC,CAAC,CAAC,CACX,cAAK,SAAS,EAAC,yBAAyB,EAAC,IAAI,EAAC,QAAQ,YACpD,gBAAM,SAAS,EAAC,gCAAgC,aAC9C,eAAM,SAAS,EAAC,mBAAmB,iBAAa,MAAM,GAAG,EACxD,OAAO,CAAC,YAAY,IAChB,GACH,CACP,CAAC,CAAC,CAAC,IAAI,IACJ,CACP,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAA6B,EAAE,OAAqB,EAAQ,EAAE;IACvF,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QAChE,KAAK,CAAC,aAAa,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpE,CAAC;AACH,CAAC,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * The catalogue's home: the pages opened last, then each source with its own introduction and its families, each
+ * family a card of its components. The logo opens it, and so does an address that names no page.
+ *
+ * @remarks
+ * Everything but a source's introduction is drawn from the tree, so it never goes stale; the introduction is the
+ * package's own Markdown (`StorySource.home`), rendered by the plugin. No story loads here: a home of frames would load
+ * dozens of them before anyone picked one.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ReactNode } from "react";
+import { type StoryTree } from "../storyTree.ts";
+import type { RecentPage } from "./useRecentPages.ts";
+/** The home's props. */
+export type HomePageProps = {
+    /** The catalogue's title. */
+    readonly title: string;
+    /** 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;
+    /** What stays above the home: the index's problems, when it has some. */
+    readonly header: ReactNode;
+};
+/**
+ * The home.
+ *
+ * @param props - the title, the tree, the sources, the recent pages, and how to open a page.
+ */
+export declare const HomePage: ({ title, tree, sources, recent, hrefOf, onOpen, header }: HomePageProps) => ReactNode;
+//# sourceMappingURL=HomePage.d.ts.map

package/dist/src/shell/HomePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HomePage.d.ts","sourceRoot":"","sources":["../../../src/shell/HomePage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAmB,KAAK,SAAS,EAAY,MAAM,OAAO,CAAC;AAElE,OAAO,EAIL,KAAK,SAAS,EAIf,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtD,wBAAwB;AACxB,MAAM,MAAM,aAAa,GAAG;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;IAC9C,oBAAoB;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B,CAAC;AAgJF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,0DAQtB,aAAa,KAAG,SA2ElB,CAAC"}

package/dist/src/shell/HomePage.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { componentId, findComponent, findStory } from "../storyTree.js";
+import { PackageHtml } from "./PackageHtml.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) => {
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+            return;
+        event.preventDefault();
+        onOpen(page);
+    }, children: children }));
+/**
+ * The recent pages the tree still has, with their names and places.
+ *
+ * @param tree - the tree.
+ * @param recent - the pages opened last.
+ */
+const recentEntries = (tree, recent) => recent.flatMap((page) => {
+    if (page.kind === "story") {
+        const location = findStory(tree, page.id);
+        if (location === undefined)
+            return [];
+        const place = [location.source.name, location.family.name, location.component.name].join(" · ");
+        return [{ page, name: location.story.name, place }];
+    }
+    const location = findComponent(tree, page.id);
+    if (location === undefined)
+        return [];
+    const place = [location.source.name, location.family.name, location.group.name]
+        .filter((part) => part !== undefined)
+        .join(" · ");
+    return [{ page, name: location.component.name, place }];
+});
+/** What the plugin answered for a source's introduction, as a state. */
+const introState = (value) => {
+    const markdown = typeof value === "object" && value !== null && "default" in value ? value.default : undefined;
+    if (typeof markdown === "object" &&
+        markdown !== null &&
+        "html" in markdown &&
+        typeof markdown.html === "string") {
+        return { status: "ready", value: { html: markdown.html } };
+    }
+    return { status: "error", message: "The source's introduction has an unexpected shape" };
+};
+/**
+ * A source's introduction, as its package wrote it; nothing while it loads or when the source has none.
+ *
+ * @param props - the loader.
+ */
+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 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.
+ */
+const FamilyCard = ({ source, 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] }));
+};
+/**
+ * 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)))] }) })] }));
+};
+//# sourceMappingURL=HomePage.js.map