forgebook 0.1.8 → 0.2.0

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

@@ -0,0 +1,106 @@
+/**
+ * What goes around the frames of a component's page drawn for one audience, in the order `audienceLayout.ts` gives it:
+ * the note that says so, the page's own sections, and the audience's: when to use the component, the docs pages that
+ * show it, its tokens and its parts.
+ *
+ * @remarks
+ * One chunk split from the shell, loaded with the first page drawn for someone else: a catalogue read by everyone pays
+ * for it nothing. The tokens come from the plugin's module, loaded by their section; the whole catalogue's stay closed
+ * until asked for, since a library may have thousands.
+ *
+ * @module
+ */
+import "./audienceSections.scss";
+import { type ReactNode, type RefObject } from "react";
+import type { AudienceId } from "../audiences.ts";
+import type { ComponentDocs, UsageGuidance as Guidance } from "../componentDocs.ts";
+import type { StoryTree, TreeComponent, TreeStory } from "../storyTree.ts";
+import { type StoryCoverageProps } from "./StoryCoverage.tsx";
+import { type UsedInProps } from "./UsedIn.tsx";
+import { type Loaded } from "./useLoaded.ts";
+import type { PageDoc } from "./usePageDoc.ts";
+/** The place around the frames a part of the page goes in. */
+export type AudiencePlace = "beforeDemo" | "afterDemo" | "afterExamples";
+/** What the sections read. */
+export type AudienceSectionsProps = {
+    /** The place drawn. */
+    readonly place: AudiencePlace;
+    /** Who the page is drawn for. */
+    readonly audience: Exclude<AudienceId, "everyone">;
+    /** Whether the page says so: the catalogue may have fixed it, and then offers no way back. */
+    readonly hasNote: boolean;
+    /** Goes back to the whole page. */
+    readonly onShowAll: () => void;
+    /** The component. */
+    readonly component: TreeComponent;
+    /** Its docs; none until they load, or when it has none. */
+    readonly docs: ComponentDocs | undefined;
+    /** Whether it is about logic. */
+    readonly isLogic: boolean;
+    /** The documentation file. */
+    readonly page: Loaded<PageDoc>;
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The component's id. */
+    readonly componentId: string;
+    /** A docs page's address. */
+    readonly pageHrefOf: (id: string) => string;
+    /** Opens a docs page. */
+    readonly onOpenPage: (id: string) => void;
+    /** Loads the design tokens; none when the catalogue has none. */
+    readonly loadTokens: (() => Promise<unknown>) | undefined;
+    /** What the coverage table reads, and the view, whose change clears its checks. */
+    readonly coverage: StoryCoverageProps & {
+        readonly viewKey: string;
+    };
+    /** What "Used in" reads; none when the catalogue turned it off. */
+    readonly usedIn: Omit<UsedInProps, "title"> | undefined;
+    /** The page's scrolling element. */
+    readonly pageRef: RefObject<HTMLDivElement | null>;
+};
+/**
+ * When to use the component and when not, from its TSDoc.
+ *
+ * @param props - the guidance.
+ */
+export declare const UsageGuidance: ({ guidance }: {
+    readonly guidance: Guidance;
+}) => ReactNode;
+/** What the docs pages' section reads. */
+export type AboutPagesProps = {
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The component's id. */
+    readonly id: string;
+    /** Its stories. */
+    readonly stories: readonly TreeStory[];
+    /** A docs page's address. */
+    readonly hrefOf: (id: string) => string;
+    /** Opens a docs page. */
+    readonly onOpen: (id: string) => void;
+};
+/**
+ * The docs pages that show the component.
+ *
+ * @param props - the tree, the component's id and stories, the pages' addresses and how one opens.
+ */
+export declare const AboutPages: ({ tree, id, stories, hrefOf, onOpen }: AboutPagesProps) => ReactNode;
+/** What the tokens' section reads. */
+export type TokensSectionProps = {
+    /** Loads the tokens. */
+    readonly load: () => Promise<unknown>;
+    /** The component's name. */
+    readonly componentName: string;
+};
+/**
+ * The component's design tokens, then the whole catalogue's, closed.
+ *
+ * @param props - the tokens' loader and the component's name.
+ */
+export declare const TokensSection: ({ load, componentName }: TokensSectionProps) => ReactNode;
+/**
+ * What goes in one place around the frames of a page drawn for an audience, the note first.
+ *
+ * @param props - the place, the audience and what the sections read.
+ */
+export declare const AudienceSections: (props: AudienceSectionsProps) => ReactNode;

package/dist/src/shell/AudienceSections.js

@@ -0,0 +1,154 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * What goes around the frames of a component's page drawn for one audience, in the order `audienceLayout.ts` gives it:
+ * the note that says so, the page's own sections, and the audience's: when to use the component, the docs pages that
+ * show it, its tokens and its parts.
+ *
+ * @remarks
+ * One chunk split from the shell, loaded with the first page drawn for someone else: a catalogue read by everyone pays
+ * for it nothing. The tokens come from the plugin's module, loaded by their section; the whole catalogue's stay closed
+ * until asked for, since a library may have thousands.
+ *
+ * @module
+ */
+import "./audienceSections.css";
+import { Fragment } from "react";
+import { AUDIENCE_PAGES } from "./audienceLayout.js";
+import { AUDIENCE_TEXTS, isShellTokens, pagesAbout, proseFor, tokensAbout } from "./audiencePage.js";
+import { CodeText } from "./CodeText.js";
+import { Lead, PageApi } from "./ComponentPage.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { PackageHtml } from "./PackageHtml.js";
+import { PartsTab } from "./PartsTab.js";
+import { StoryCoverage } from "./StoryCoverage.js";
+import { STRINGS } from "./strings.js";
+import { styleHooks } from "./tabSummaries.js";
+import { UsedIn } from "./UsedIn.js";
+import { useLoaded } from "./useLoaded.js";
+/**
+ * Says that the page is drawn for one audience, so a shared link never reads as a page with parts missing, and goes back
+ * to all of it. The button goes with the note, so the focus moves to the page rather than being lost.
+ *
+ * @param props - the audience's name, how to show everything, and the page's scrolling element.
+ */
+const AudienceNote = ({ name, onShowAll, pageRef }) => (_jsxs("p", { className: "forgebook-audience-note", children: [AUDIENCE_TEXTS.audienceNote(name), " ", _jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => {
+                onShowAll();
+                const page = pageRef.current;
+                if (page === null)
+                    return;
+                page.tabIndex = -1;
+                page.focus({ preventScroll: true });
+                page.addEventListener("blur", () => page.removeAttribute("tabindex"), { once: true });
+            }, children: AUDIENCE_TEXTS.audienceShowAll })] }));
+/**
+ * The parts and the styling hooks, the panel's own tab; nothing without either.
+ *
+ * @param props - the docs.
+ */
+const PartsSection = ({ docs }) => docs === undefined || (docs.parts.length === 0 && styleHooks(docs).length === 0) ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-parts", children: [_jsx("h2", { id: "forgebook-parts", children: AUDIENCE_TEXTS.partsTitle }), _jsx(PartsTab, { docs: docs })] }));
+/** The most of the whole catalogue's tokens drawn at once: more would only slow the page. */
+const TOKENS_SHOWN = 100;
+/**
+ * A list of what the guidance says, under its heading; nothing when it says nothing.
+ *
+ * @param props - the heading and the items.
+ */
+const GuidanceList = ({ title, items }) => items === undefined || items.length === 0 ? null : (_jsxs("div", { className: "forgebook-guidance__list", children: [_jsx("h3", { children: title }), _jsx("ul", { children: items.map((item) => (_jsx("li", { children: _jsx(CodeText, { text: item }) }, item))) })] }));
+/**
+ * When to use the component and when not, from its TSDoc.
+ *
+ * @param props - the guidance.
+ */
+export const UsageGuidance = ({ guidance }) => (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-guidance", children: [_jsx("h2", { id: "forgebook-guidance", children: AUDIENCE_TEXTS.guidance }), guidance.deprecated === undefined ? null : (_jsxs("p", { className: "forgebook-guidance__deprecated", children: [_jsxs("strong", { children: [AUDIENCE_TEXTS.guidanceDeprecated, "."] }), " ", _jsx(CodeText, { text: guidance.deprecated }), guidance.replacedBy === undefined ? null : (_jsxs(_Fragment, { children: [" ", AUDIENCE_TEXTS.guidanceReplacedBy, ": ", _jsx(CodeText, { text: guidance.replacedBy })] }))] })), _jsxs("div", { className: "forgebook-guidance", children: [_jsx(GuidanceList, { title: AUDIENCE_TEXTS.guidanceUse, items: guidance.useWhen }), _jsx(GuidanceList, { title: AUDIENCE_TEXTS.guidanceAvoid, items: guidance.avoidWhen }), _jsx(GuidanceList, { title: AUDIENCE_TEXTS.guidanceAlternatives, items: guidance.alternatives })] })] }));
+/**
+ * The docs pages that show the component.
+ *
+ * @param props - the tree, the component's id and stories, the pages' addresses and how one opens.
+ */
+export const AboutPages = ({ tree, id, stories, hrefOf, onOpen }) => {
+    const pages = pagesAbout(tree, id, stories.map((story) => story.id));
+    return pages.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-about-pages", children: [_jsx("h2", { id: "forgebook-about-pages", children: AUDIENCE_TEXTS.aboutPages }), _jsx("ul", { className: "forgebook-about-pages", children: pages.map((page) => (_jsxs("li", { children: [_jsx("a", { className: "forgebook-link", href: hrefOf(page.id), onClick: (event) => {
+                                if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                                    return;
+                                event.preventDefault();
+                                onOpen(page.id);
+                            }, children: page.name }), page.description === undefined ? null : (_jsx("span", { className: "forgebook-about-pages__description", children: page.description }))] }, page.id))) })] }));
+};
+/** What the tokens' module answered, as a state. */
+const tokensState = (value) => isShellTokens(value)
+    ? { status: "ready", value }
+    : { status: "error", message: "The tokens have an unexpected shape" };
+/**
+ * A table of tokens: each one's name and value, in every theme where it differs, a colour with its swatch.
+ *
+ * @param props - the tokens.
+ */
+const TokenTable = ({ tokens }) => (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: AUDIENCE_TEXTS.tokenName }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.tokenValue })] }) }), _jsx("tbody", { children: tokens.map((token) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", className: "forgebook-api__name", children: token.name }), _jsx("td", { children: [["", token.value], ...Object.entries(token.modes)].map(([mode, value]) => (_jsxs("span", { className: "forgebook-token", children: [token.type === "color" ? (_jsx("span", { className: "forgebook-token__swatch", style: { background: value } })) : null, mode === "" ? value : `${mode}: ${value}`] }, mode))) })] }, token.name))) })] }) }));
+/**
+ * The component's design tokens, then the whole catalogue's, closed.
+ *
+ * @param props - the tokens' loader and the component's name.
+ */
+export const TokensSection = ({ load, componentName }) => {
+    const loaded = useLoaded(load, tokensState);
+    if (loaded.status === "error") {
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [AUDIENCE_TEXTS.tokensError, ": ", loaded.message] }));
+    }
+    if (loaded.status !== "ready")
+        return null;
+    const { tokens, problems } = loaded.value;
+    const own = tokensAbout(tokens, componentName);
+    const others = tokens.filter((token) => !own.includes(token));
+    if (tokens.length === 0 && problems.length === 0)
+        return null;
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-tokens", children: [_jsx("h2", { id: "forgebook-tokens", children: AUDIENCE_TEXTS.tokens }), problems.length === 0 ? null : (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [AUDIENCE_TEXTS.tokensError, ": ", problems.join("; ")] })), own.length === 0 ? null : _jsx(TokenTable, { tokens: own }), others.length === 0 ? null : (_jsxs("details", { className: "forgebook-tokens__others", children: [_jsx("summary", { children: AUDIENCE_TEXTS.tokensOther(others.length) }), _jsx(TokenTable, { tokens: others.slice(0, TOKENS_SHOWN) }), others.length > TOKENS_SHOWN ? (_jsx("p", { children: _jsx(CodeText, { text: AUDIENCE_TEXTS.tokensMore(others.length - TOKENS_SHOWN) }) })) : null] }))] }));
+};
+/**
+ * The documentation file as an audience reads it, or why it could not be read.
+ *
+ * @param props - the file and how much of it the audience sees.
+ */
+const AudienceProse = ({ page, reading }) => {
+    if (page.status === "error") {
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.pageError, ": ", page.message] }));
+    }
+    if (page.status !== "ready")
+        return null;
+    const html = proseFor(page.value.html, reading);
+    return html === "" ? null : _jsx(PackageHtml, { className: "forgebook-prose", html: html });
+};
+/**
+ * One section.
+ *
+ * @param props - its name and what the sections read.
+ */
+const Section = ({ id, ...props }) => {
+    const { component, docs, isLogic, page, loadTokens, coverage, usedIn } = props;
+    const { viewKey, ...table } = coverage;
+    switch (id) {
+        case "lead":
+            return _jsx(Lead, { page: page, docs: docs });
+        case "guidance":
+            return docs?.guidance === undefined ? null : _jsx(UsageGuidance, { guidance: docs.guidance });
+        case "prose":
+            return _jsx(AudienceProse, { page: page, reading: AUDIENCE_PAGES[props.audience].prose });
+        case "api":
+            return _jsx(PageApi, { docs: docs, isLogic: isLogic, componentGroups: component.propGroups });
+        case "parts":
+            return _jsx(PartsSection, { docs: docs });
+        case "pages":
+            return (_jsx(AboutPages, { tree: props.tree, id: props.componentId, stories: component.stories, hrefOf: props.pageHrefOf, onOpen: props.onOpenPage }));
+        case "tokens":
+            return loadTokens === undefined ? null : (_jsx(TokensSection, { load: loadTokens, componentName: docs?.name ?? component.name }));
+        case "coverage":
+            return _jsx(StoryCoverage, { ...table }, viewKey);
+        default:
+            return usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn });
+    }
+};
+/**
+ * What goes in one place around the frames of a page drawn for an audience, the note first.
+ *
+ * @param props - the place, the audience and what the sections read.
+ */
+export const AudienceSections = (props) => (_jsxs(_Fragment, { children: [props.place === "beforeDemo" && props.hasNote ? (_jsx(AudienceNote, { name: STRINGS.audiences[props.audience], onShowAll: props.onShowAll, pageRef: props.pageRef })) : null, AUDIENCE_PAGES[props.audience][props.place].map((id) => (_jsx(Fragment, { children: _jsx(Section, { id: id, ...props }) }, id)))] }));

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

@@ -0,0 +1,37 @@
+/**
+ * The catalogue's home as its authors wrote it (`forgebook.home.md`): their text, with the docs pages' blocks, live
+ * stories, values (`{{components}}`) and pieces of the generated home (`::families`), in place of the generated home.
+ *
+ * @remarks
+ * Loaded on first use with the docs pages' chunk, and only by a catalogue that has a written home, so the shell's first
+ * load pays nothing for it and a catalogue without one keeps its generated home exactly. What the file gets wrong is
+ * listed above it, each mistake with its line and column, and the rest still draws. The home has no address of its own
+ * for a heading, so a link to one scrolls to it without a new entry in the history.
+ *
+ * @module
+ */
+import "./docPage.scss";
+import { type ReactNode } from "react";
+import type { DocPageProps } from "./DocPage.tsx";
+import type { HomePageProps } from "./HomePage.tsx";
+/** The written home's props: a docs page's, without a page of its own, and the generated home's. */
+export type AuthoredHomeProps = Omit<DocPageProps, "location" | "anchor" | "onOpenAnchor" | "onOpenPage"> & Pick<HomePageProps, "recent" | "hrefOf" | "onOpen"> & {
+    /** Loads the written home, as the plugin compiled it. */
+    readonly load: () => Promise<unknown>;
+};
+/** The written home's props, as the shell gives them: its loader is the page entry's. */
+export type WrittenHomeProps = Omit<AuthoredHomeProps, "load">;
+/**
+ * The written home.
+ *
+ * @param props - the loader, the generated home's and a docs page's props.
+ */
+export declare const AuthoredHome: ({ load, title, plugins, tree, sources, recent, hrefOf, onOpen, view, touchOverrides, onTouchChange, frameUrl, storyHrefOf, onOpenStory, pageHrefOf, onOpenAddress, heightOf, backgroundOf, header, scroll }: AuthoredHomeProps) => ReactNode;
+/**
+ * The written home as the shell draws it, its loader bound: what the page's entry hands the shell, so the shell's own
+ * code holds nothing of the written home.
+ *
+ * @param load - loads the written home, as the plugin compiled it.
+ * @returns the home's component.
+ */
+export declare const writtenHome: (load: () => Promise<unknown>) => (props: WrittenHomeProps) => ReactNode;

package/dist/src/shell/AuthoredHome.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The catalogue's home as its authors wrote it (`forgebook.home.md`): their text, with the docs pages' blocks, live
+ * stories, values (`{{components}}`) and pieces of the generated home (`::families`), in place of the generated home.
+ *
+ * @remarks
+ * Loaded on first use with the docs pages' chunk, and only by a catalogue that has a written home, so the shell's first
+ * load pays nothing for it and a catalogue without one keeps its generated home exactly. What the file gets wrong is
+ * listed above it, each mistake with its line and column, and the rest still draws. The home has no address of its own
+ * for a heading, so a link to one scrolls to it without a new entry in the history.
+ *
+ * @module
+ */
+import "./docPage.css";
+import { useCallback, useMemo, useRef } from "react";
+import { headingElementId } from "../docAnchors.js";
+import { filledText, isHomeDocument, OWN_SOURCE_ID } from "../docPages.js";
+import { anchorOf } from "../pageAddress.js";
+import { findStory } from "../storyTree.js";
+import { CodeText } from "./CodeText.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { blockPlaces, catalogueValues, DocBlocks, queuedBlocks } from "./DocBlocks.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
+import { useLoaded } from "./useLoaded.js";
+import { usePageFrames } from "./usePageFrames.js";
+import { useProseLinks } from "./useProseLinks.js";
+import { useScrollMemory } from "./useScrollMemory.js";
+/** A home that loaded nothing yet. */
+const NO_HOME = { blocks: [], stories: [], notes: [], assets: [] };
+/** What the plugin answered, as a state. */
+const homeState = (value) => isHomeDocument(value)
+    ? { status: "ready", value }
+    : { status: "error", message: "The home has an unexpected shape" };
+/**
+ * What is wrong with the home's file, above it.
+ *
+ * @param props - the notes.
+ */
+const HomeNotes = ({ notes }) => notes.length === 0 ? null : (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: PAGE_STRINGS.homeProblems }), _jsx("ul", { children: notes.map((note) => (_jsx("li", { children: note }, note))) })] }));
+/**
+ * The written home.
+ *
+ * @param props - the loader, the generated home's and a docs page's props.
+ */
+export const AuthoredHome = ({ load, title, plugins, tree, sources, recent, hrefOf, onOpen, view, touchOverrides, onTouchChange, frameUrl, storyHrefOf, onOpenStory, pageHrefOf, onOpenAddress, heightOf, backgroundOf, header, scroll }) => {
+    const pageRef = useRef(null);
+    const bodyRef = useRef(null);
+    const loaded = useLoaded(load, homeState);
+    const content = loaded.status === "ready" ? loaded.value : NO_HOME;
+    const catalogue = useCatalogue();
+    const stories = useMemo(() => content.stories.flatMap((id) => findStory(tree, id)?.story ?? []), [content.stories, tree]);
+    const queued = useMemo(() => queuedBlocks(content.blocks, tree), [content.blocks, tree]);
+    const places = useMemo(() => blockPlaces(content.blocks), [content.blocks]);
+    const values = useMemo(() => catalogueValues(title, tree), [title, tree]);
+    const frames = usePageFrames({ stories, queued, pageRef, view, touchOverrides });
+    useScrollMemory(pageRef, scroll);
+    const openLink = useCallback((href) => {
+        if (href.startsWith("#")) {
+            const heading = document.getElementById(headingElementId(anchorOf(href.slice(1)) ?? ""));
+            heading?.scrollIntoView({ block: "start" });
+            return heading !== null;
+        }
+        return href.startsWith("?") && onOpenAddress(href);
+    }, [onOpenAddress]);
+    useProseLinks(bodyRef, openLink);
+    const context = {
+        tree,
+        sources,
+        frames,
+        view,
+        frameUrl,
+        switches: catalogue.switches,
+        assets: content.assets,
+        // a page the home links to by its file is one of the project's own docs pages
+        pageHrefOf: (slug, anchor) => pageHrefOf(`${OWN_SOURCE_ID}:${slug}`, anchor),
+        stories: { hrefOf: storyHrefOf, onOpen: onOpenStory },
+        onTouchChange,
+        heightOf,
+        backgroundOf,
+        values,
+        onOpenAddress: openLink,
+        home: { tree, sources, recent, hrefOf, onOpen },
+        places,
+        plugins,
+        strings: catalogue.strings
+    };
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { ref: bodyRef, className: "forgebook-home forgebook-home--written", children: [loaded.status === "loading" ? null : (_jsxs("header", { className: "forgebook-home__head", children: [_jsx("h1", { className: "forgebook-home__title", children: filledText(content.title ?? title, values) }), content.description === undefined ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: filledText(content.description, values) }) }))] })), loaded.status === "error" ? (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [PAGE_STRINGS.homeError, ": ", loaded.message] })) : null, _jsx(HomeNotes, { notes: content.notes }), _jsx(DocBlocks, { blocks: content.blocks, context: context })] }) })] }));
+};
+/**
+ * The written home as the shell draws it, its loader bound: what the page's entry hands the shell, so the shell's own
+ * code holds nothing of the written home.
+ *
+ * @param load - loads the written home, as the plugin compiled it.
+ * @returns the home's component.
+ */
+export const writtenHome = (load) => (props) => _jsx(AuthoredHome, { ...props, load: load });

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

@@ -37,4 +37,3 @@ export declare const useBoxWidth: (isOver: boolean, pageWidth: StageWidth) => Bo
 export declare const BoxWidthControl: ({ boxWidth }: {
     readonly boxWidth: BoxWidth;
 }) => ReactNode;
-//# sourceMappingURL=BoxWidth.d.ts.map

package/dist/src/shell/BoxWidth.js

@@ -53,4 +53,3 @@ export const BoxWidthControl = ({ boxWidth }) => {
                     }))
                 ], value: width, onValueChange: onWidthChange, after: _jsx(WidthField, { width: width, shownWidth: shownWidth, onWidthChange: onWidthChange }) })] }));
 };
-//# sourceMappingURL=BoxWidth.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * The story clock's controls, for a Live story: a pause or resume button, Restart, and the speed. Loaded the first time
+ * a story with a clock is shown (`ClockControls.tsx`).
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { StoryClockControls } from "./ClockControls.tsx";
+/** The controls' props. */
+export type ClockBarProps = {
+    /** The clock's state and what changes it. */
+    readonly controls: StoryClockControls;
+};
+/**
+ * The clock's controls: a pause or resume button, Restart, and the speed.
+ *
+ * @param props - the clock's state and what changes it.
+ */
+export declare const ClockBar: ({ controls }: ClockBarProps) => ReactNode;

package/dist/src/shell/ClockBar.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CLOCK_RATES } from "../storyClock.js";
+import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { Segmented } from "./Segmented.js";
+/**
+ * The clock's controls: a pause or resume button, Restart, and the speed.
+ *
+ * @param props - the clock's state and what changes it.
+ */
+export const ClockBar = ({ controls }) => {
+    const { state, change, restart } = controls;
+    const toggleLabel = state.isRunning ? LATER_STRINGS.clockPause : LATER_STRINGS.clockResume;
+    return (_jsxs("fieldset", { className: "forgebook-clock", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: LATER_STRINGS.clockLabel }), _jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon", title: toggleLabel, "aria-label": toggleLabel, onClick: () => change({ isRunning: !state.isRunning }), children: _jsx(Icon, { name: state.isRunning ? "pause" : "play", size: 14 }) }), _jsxs("button", { type: "button", className: "forgebook-button", onClick: restart, children: [_jsx(Icon, { name: "restart", size: 14 }), LATER_STRINGS.clockRestart] }), _jsx(Segmented, { label: LATER_STRINGS.clockSpeed, options: CLOCK_RATES.map((rate) => ({ value: rate, label: LATER_STRINGS.clockRate(rate) })), value: state.rate, onValueChange: (rate) => change({ rate }) })] }));
+};

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

@@ -4,12 +4,14 @@
  * @remarks
  * The state lives in the shell, per shown story: a new story starts running at real time, and a frame that loads
  * again (an edit, another language) receives the state it had. The frame runs the clock (`frame/frameClock.ts`);
- * these controls only send it what to do, so the shell never reads the story's time.
+ * these controls only send it what to do, so the shell never reads the story's time. Few stories have a clock, so the
+ * controls themselves (`ClockBar.tsx`) load with the first that has one.
  *
  * @module
  */
 import { type ReactNode, type RefObject } from "react";
 import { type ClockState } from "../storyClock.ts";
+import type { ClockBarProps } from "./ClockBar.tsx";
 /** The clock's state for the shown story, and how to change it in its frame. */
 export type StoryClockControls = {
     /** Whether the clock runs, and how fast. */
@@ -29,15 +31,9 @@ export type StoryClockControls = {
  * @returns the state and what changes it.
  */
 export declare const useStoryClockControls: (frameRef: RefObject<HTMLIFrameElement | null>, storyId: string) => StoryClockControls;
-/** The controls' props. */
-export type ClockControlsProps = {
-    /** The clock's state and what changes it. */
-    readonly controls: StoryClockControls;
-};
 /**
- * The clock's controls: a pause or resume button, Restart, and the speed.
+ * The clock's controls, once their module is there.
  *
  * @param props - the clock's state and what changes it.
  */
-export declare const ClockControls: ({ controls }: ClockControlsProps) => ReactNode;
-//# sourceMappingURL=ClockControls.d.ts.map
+export declare const ClockControls: (props: ClockBarProps) => ReactNode;

package/dist/src/shell/ClockControls.js

@@ -1,19 +1,19 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * The story clock's controls on the stage, for a Live story: pause and resume, restart, and the speed.
  *
  * @remarks
  * The state lives in the shell, per shown story: a new story starts running at real time, and a frame that loads
  * again (an edit, another language) receives the state it had. The frame runs the clock (`frame/frameClock.ts`);
- * these controls only send it what to do, so the shell never reads the story's time.
+ * these controls only send it what to do, so the shell never reads the story's time. Few stories have a clock, so the
+ * controls themselves (`ClockBar.tsx`) load with the first that has one.
  *
  * @module
  */
 import { useEffect, useState } from "react";
-import { CLOCK_RATES, DEFAULT_CLOCK_STATE } from "../storyClock.js";
-import { Icon } from "./icons.js";
-import { Segmented } from "./Segmented.js";
-import { STRINGS } from "./strings.js";
+import { DEFAULT_CLOCK_STATE } from "../storyClock.js";
+import { framesOrigin } from "./framesOrigin.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 /**
  * The clock controls' state for the shown story, started over for each story.
  *
@@ -28,26 +28,23 @@ export const useStoryClockControls = (frameRef, storyId) => {
         setShownId(storyId);
         setLocalState(DEFAULT_CLOCK_STATE);
     }
-    const send = (message) => frameRef.current?.contentWindow?.postMessage(message, window.location.origin);
+    const send = (message) => frameRef.current?.contentWindow?.postMessage(message, framesOrigin());
     // the frame hears every state once it is drawn, so a change builds on the latest state, never on a render's copy
     useEffect(() => {
-        frameRef.current?.contentWindow?.postMessage({ type: "forgebook:clock", state }, window.location.origin);
+        frameRef.current?.contentWindow?.postMessage({ type: "forgebook:clock", state }, framesOrigin());
     }, [frameRef, state]);
     return {
         state,
         change: (patch) => setLocalState((current) => ({ ...current, ...patch })),
         restart: () => send({ type: "forgebook:clock-restart" }),
-        sendTo: (frame) => frame.postMessage({ type: "forgebook:clock", state }, window.location.origin)
+        sendTo: (frame) => frame.postMessage({ type: "forgebook:clock", state }, framesOrigin())
     };
 };
+/** The controls' module, loaded with the first story that reads the clock. */
+const CLOCK_BAR = lazyModule(() => import("./ClockBar.js").then((module) => module.ClockBar));
 /**
- * The clock's controls: a pause or resume button, Restart, and the speed.
+ * The clock's controls, once their module is there.
  *
  * @param props - the clock's state and what changes it.
  */
-export const ClockControls = ({ controls }) => {
-    const { state, change, restart } = controls;
-    const toggleLabel = state.isRunning ? STRINGS.clockPause : STRINGS.clockResume;
-    return (_jsxs("fieldset", { className: "forgebook-clock", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.clockLabel }), _jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon", title: toggleLabel, "aria-label": toggleLabel, onClick: () => change({ isRunning: !state.isRunning }), children: _jsx(Icon, { name: state.isRunning ? "pause" : "play", size: 14 }) }), _jsxs("button", { type: "button", className: "forgebook-button", onClick: restart, children: [_jsx(Icon, { name: "restart", size: 14 }), STRINGS.clockRestart] }), _jsx(Segmented, { label: STRINGS.clockSpeed, options: CLOCK_RATES.map((rate) => ({ value: rate, label: STRINGS.clockRate(rate) })), value: state.rate, onValueChange: (rate) => change({ rate }) })] }));
-};
-//# sourceMappingURL=ClockControls.js.map
+export const ClockControls = (props) => (_jsx(LazyView, { module: CLOCK_BAR, props: props, loading: null, failed: () => null }));

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

@@ -13,4 +13,3 @@ export declare const Code: ({ text, names }: {
     readonly text: string;
     readonly names: readonly string[];
 }) => ReactNode;
-//# sourceMappingURL=Code.d.ts.map

package/dist/src/shell/Code.js

@@ -6,4 +6,3 @@ import { codeTokens } from "./codeTokens.js";
  * @param props - the text, and the names coloured as names (the event's parameters).
  */
 export const Code = ({ text, names }) => (_jsx("code", { className: "forgebook-code", children: codeTokens(text, new Set(names)).map((token, index) => (_jsx("span", { className: `forgebook-code__${token.kind}`, children: token.text }, index))) }));
-//# sourceMappingURL=Code.js.map

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

@@ -14,4 +14,3 @@ export type CodeTabProps = StoryCodeSource;
  * @param props - the file's code, the story, the component's name and the args.
  */
 export declare const CodeTab: (props: CodeTabProps) => ReactNode;
-//# sourceMappingURL=CodeTab.d.ts.map

package/dist/src/shell/CodeTab.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCodeWriter } from "./codeWriter.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { StoryCodeBlock, storyCodeText } from "./StoryCodeBlock.js";
 import { STRINGS } from "./strings.js";
 import { useCopy } from "./useCopy.js";
@@ -12,6 +13,5 @@ export const CodeTab = (props) => {
     const { isCopied, copy } = useCopy();
     const write = useCodeWriter();
     const hasRender = props.code[props.exportName] !== undefined;
-    return (_jsxs("div", { className: "forgebook-prop-group", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasRender ? STRINGS.codeRender : STRINGS.codeFromArgs }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => copy(storyCodeText(props, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : STRINGS.copy })] }), _jsx(StoryCodeBlock, { ...props })] }));
+    return (_jsxs("div", { className: "forgebook-prop-group", children: [_jsxs("div", { className: "forgebook-calls__head", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasRender ? LATER_STRINGS.codeRender : LATER_STRINGS.codeFromArgs }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => copy(storyCodeText(props, write)), "aria-live": "polite", children: isCopied ? STRINGS.copied : LATER_STRINGS.copy })] }), _jsx(StoryCodeBlock, { ...props })] }));
 };
-//# sourceMappingURL=CodeTab.js.map

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

@@ -13,4 +13,3 @@ import type { ReactNode } from "react";
 export declare const CodeText: ({ text }: {
     readonly text: string;
 }) => ReactNode;
-//# sourceMappingURL=CodeText.d.ts.map

package/dist/src/shell/CodeText.js

@@ -7,4 +7,3 @@ import { jsx as _jsx } from "react/jsx-runtime";
 export const CodeText = ({ text }) => 
 // a split on the backticks alternates text and code: the odd pieces were between backticks
 text.split("`").map((piece, index) => index % 2 === 1 ? (_jsx("code", { className: "forgebook-inline-code", children: piece }, index)) : (piece));
-//# sourceMappingURL=CodeText.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * The compare view of a story's stage: the story once per value of the compared switches, side by side, each cell
+ * labelled; in a device each, when one is shown. Loaded the first time the view is compared (`StageCompare.tsx`).
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { TreeStory } from "../storyTree.ts";
+import { type ViewState } from "../viewState.ts";
+import { type FramedDevice } from "./DeviceSlot.tsx";
+/** The compare view's props. */
+export type CompareGridProps = {
+    /** The story. */
+    readonly story: TreeStory;
+    /** The frames' accessible title, before each cell's label. */
+    readonly title: string;
+    /** The view, its compared axes set. */
+    readonly view: ViewState;
+    /** The frame page's address. */
+    readonly frameUrl: string;
+    /** The device each cell shows; none for none. */
+    readonly framed: FramedDevice | undefined;
+    /** Each frame's reported height, by its address. */
+    readonly heights: ReadonlyMap<string, number>;
+    /** The addresses of the frames that finished loading. */
+    readonly settled: ReadonlySet<string>;
+    /** The height of a frame before its story reports its own, in CSS px. */
+    readonly fallbackHeight: number;
+    /** The colour the story's page has in a view. */
+    readonly backgroundOf: (view: Pick<ViewState, "switches" | "backdrop">) => string | undefined;
+};
+/**
+ * The compare view's cells.
+ *
+ * @param props - the story, the view, the device and the frames' reports.
+ */
+export declare const CompareGrid: ({ story, title, view, frameUrl, framed, heights, settled, fallbackHeight, backgroundOf }: CompareGridProps) => ReactNode;