forgebook 0.1.8 → 0.2.0

package/dist/src/shell/EmbedPage.js

@@ -0,0 +1,168 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * One story alone, for a page of someone else's: no sidebar, no toolbar, no panel, nothing but the story at the width
+ * it is given, in the catalogue's theme. What `?embed` mounts instead of the shell; loaded only then.
+ *
+ * @remarks
+ * It stays the catalogue's page around the story's frame, so a story keeps the document of its own it has everywhere
+ * else, and whatever is not the story (the wait, the message when there is none) is drawn by the shell's style sheets
+ * with the catalogue's theme. Its appearance follows the story, so a dark story has no light edge. It never needs the
+ * browser's storage, which a third-party frame may be denied, and nothing listens to the page around it: all that
+ * crosses is the height (`EmbedSizeMessage`), for a page that wants to follow it. A page that cannot, such
+ * as a wiki with a fixed box, gets a story that fills the box and scrolls inside it when it is taller.
+ *
+ * @module
+ */
+import "./embed.css";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { addressArgsFor } from "../addressTexts.js";
+import { EMBED_SIZE_TYPE } from "../embed.js";
+import { parsePanelArgsParam } from "../messages.js";
+import { storyBackground } from "../storyBackground.js";
+import { NOT_FIXED, withFixed } from "../storyGlobals.js";
+import { findStory, storyTree } from "../storyTree.js";
+import { frameAddress, parseView, STAGE_HEIGHT_RANGE } from "../viewState.js";
+import { CatalogueContext, useCatalogue, useConfiguredCatalogue } from "./catalogueContext.js";
+import { FrameView } from "./FrameView.js";
+import { framesOrigin } from "./framesOrigin.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { shellIsDark } from "./shellScheme.js";
+import { STRINGS } from "./strings.js";
+import { APPEARANCE_ATTRIBUTE } from "./useAppearance.js";
+import { useFrameMessages } from "./useFrameMessages.js";
+import { useSystemDark } from "./useSystemDark.js";
+/** The height of the frame before its story reports its own, in CSS px, in a page with no height of its own yet. */
+const WAITING_HEIGHT = 240;
+/**
+ * Tells the page around the embed how tall the story is.
+ *
+ * @param height - the height, in CSS px; none until it is known, so a page never shrinks to a story still loading.
+ */
+const useHostHeight = (height) => {
+    useEffect(() => {
+        if (height === undefined || window.parent === window)
+            return;
+        const message = { type: EMBED_SIZE_TYPE, height };
+        window.parent.postMessage(message, "*");
+    }, [height]);
+};
+/**
+ * The height the story's frame is held at: the one the address sets, or the tallest the stage allows. A story that
+ * grows with its window would otherwise grow its frame, and a page that follows it, for ever; one that is really
+ * taller scrolls inside its frame.
+ *
+ * @param view - the view.
+ * @param reported - the height the story reported, in CSS px.
+ */
+const heightSet = (view, reported) => {
+    if (view.height !== "auto")
+        return view.height;
+    return reported !== undefined && reported > STAGE_HEIGHT_RANGE.max ? STAGE_HEIGHT_RANGE.max : undefined;
+};
+/** Follows the window's height: the room the page around the embed gives it. */
+const subscribeToResize = (onChange) => {
+    window.addEventListener("resize", onChange);
+    return () => window.removeEventListener("resize", onChange);
+};
+/** The window's height, in CSS px. */
+const useWindowHeight = () => useSyncExternalStore(subscribeToResize, () => window.innerHeight);
+/**
+ * An element's height, followed: a message wraps as the page around it narrows.
+ *
+ * @param element - the element.
+ */
+const useElementHeight = (element) => {
+    const [height, setHeight] = useState(undefined);
+    useEffect(() => {
+        const shown = element.current;
+        if (shown === null)
+            return;
+        const observer = new ResizeObserver(() => setHeight(Math.ceil(shown.getBoundingClientRect().height)));
+        observer.observe(shown);
+        return () => observer.disconnect();
+    }, [element]);
+    return height;
+};
+/**
+ * A text in place of a story, in the catalogue's theme; the frame's own error box would be drawn by the frame.
+ *
+ * @param props - the message, what went wrong when it is known, and whether something failed.
+ */
+const EmbedNotice = ({ message, detail, isFailure }) => {
+    const notice = useRef(null);
+    useHostHeight(useElementHeight(notice));
+    return (_jsxs("div", { ref: notice, className: "forgebook-embed__message", role: "alert", "data-failed": isFailure === true ? "" : undefined, children: [message, detail === undefined ? null : _jsx("p", { className: "forgebook-embed__detail", children: detail })] }));
+};
+/**
+ * The story, in its frame, as tall as it is and at least the height the window gives it.
+ *
+ * @param props - the story, the view, its args and the frame page.
+ */
+const EmbedStory = ({ location, view, panelArgs, frameUrl }) => {
+    const catalogue = useCatalogue();
+    const { story, component, source } = location;
+    const [fixed, setFixed] = useState(NOT_FIXED);
+    const [failure, setFailure] = useState(undefined);
+    const { heights, settled } = useFrameMessages({
+        onReady: (frame, message) => {
+            setFixed(message.fixed);
+            setFailure(undefined);
+            const args = { type: "forgebook:args", args: panelArgs };
+            frame.postMessage(args, framesOrigin());
+        },
+        onCall: () => undefined,
+        onFailed: (_storyId, message) => setFailure(message)
+    });
+    const shownView = withFixed(view, fixed);
+    const isSystemDark = useSystemDark();
+    const isDark = shellIsDark({
+        appearance: "story",
+        values: shownView.switches,
+        switches: catalogue.switches,
+        isSystemDark,
+        isComparing: false
+    });
+    useEffect(() => {
+        document.documentElement.setAttribute(APPEARANCE_ATTRIBUTE, isDark ? "dark" : "light");
+    }, [isDark]);
+    const windowHeight = useWindowHeight();
+    // the frame's address is the one the page opened with: what the story fixes comes from the frame itself, and a new
+    // address would load it again
+    const address = frameAddress(frameUrl, story.id, view, catalogue.switches);
+    const reported = settled.has(address) ? heights.get(address) : undefined;
+    const fixedHeight = heightSet(shownView, reported);
+    const ownHeight = fixedHeight ?? (reported === undefined ? undefined : Math.max(reported, story.height ?? 0));
+    useHostHeight(failure === undefined ? ownHeight : undefined);
+    return (_jsxs("main", { className: "forgebook-embed", style: {
+            backgroundColor: storyBackground(source.background, shownView, catalogue, isSystemDark)
+        }, children: [failure === undefined ? null : (_jsx(EmbedNotice, { message: STRINGS.embedFailed, detail: failure, isFailure: true })), _jsx("div", { className: "forgebook-embed__story", hidden: failure !== undefined, style: { width: shownView.width === "fill" ? undefined : shownView.width }, children: _jsx(FrameView, { title: STRINGS.frameTitle(component.name, story.name), address: address, heights: heights, settled: settled, fallbackHeight: WAITING_HEIGHT, sceneHeight: Math.max(story.height ?? 0, windowHeight), fixedHeight: fixedHeight }) })] }));
+};
+/**
+ * The page: the story the address names, or why there is none.
+ *
+ * @param props - the catalogue's name, its sources, its frame page, and how its stories take the address's texts.
+ */
+const EmbedContent = ({ title, sources, frameUrl, addressTexts }) => {
+    const catalogue = useCatalogue();
+    const tree = useMemo(() => storyTree(sources), [sources]);
+    // the address is read once: an embed has nowhere to go, so nothing rewrites it
+    const [params] = useState(() => new URLSearchParams(window.location.search));
+    const storyId = params.get("story");
+    const location = storyId === null ? undefined : findStory(tree, storyId);
+    const name = location?.component.name;
+    useEffect(() => {
+        document.title = name === undefined ? title : `${name} · ${title}`;
+    }, [name, title]);
+    if (location === undefined) {
+        return (_jsx("main", { className: "forgebook-embed", children: _jsx(EmbedNotice, { message: storyId === null ? LATER_STRINGS.embedNoStory : LATER_STRINGS.embedUnknownStory(storyId) }) }));
+    }
+    return (_jsx(EmbedStory, { location: location, view: parseView(params.toString(), catalogue), 
+        // whoever embeds the story writes its address, as whoever shares a link does: the same rule applies
+        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts), frameUrl: frameUrl }));
+};
+/**
+ * One story alone, inside the catalogue's settings.
+ *
+ * @param props - the catalogue's configuration.
+ */
+export const EmbedPage = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(EmbedContent, { title: props.title, sources: props.sources, frameUrl: props.frameUrl, addressTexts: props.addressTexts ?? "any" }) }));

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

@@ -0,0 +1,25 @@
+/**
+ * What the Embed button opens: the story's link, for a wiki or Notion, and its HTML, for a page of one's own, each with
+ * a button that copies it. Loaded the first time it opens.
+ *
+ * @module
+ */
+import "./embed.scss";
+import { type ReactNode } from "react";
+/** What the panel shows. */
+export type EmbedPanelProps = {
+    /** The story's id. */
+    readonly storyId: string;
+    /** The iframe's accessible title. */
+    readonly title: string;
+    /** The view and the args to embed the story in, as the address's query. */
+    readonly query: string;
+    /** The story's height now, in CSS px: what the iframe starts at. */
+    readonly height: number;
+};
+/**
+ * The panel.
+ *
+ * @param props - the story, its view and its height.
+ */
+export declare const EmbedPanel: ({ storyId, title, query, height }: EmbedPanelProps) => ReactNode;

package/dist/src/shell/EmbedPanel.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * What the Embed button opens: the story's link, for a wiki or Notion, and its HTML, for a page of one's own, each with
+ * a button that copies it. Loaded the first time it opens.
+ *
+ * @module
+ */
+import "./embed.css";
+import { useEffect, useId, useRef, useState } from "react";
+import { embedAddressOf, embedCode, isLocalAddress } from "../embedCode.js";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { STRINGS } from "./strings.js";
+import { useCopy } from "./useCopy.js";
+/**
+ * One text to copy: its label, the text in a field that selects it when focused, and the button.
+ *
+ * @param props - the label, the text, and whether the panel's focus starts here.
+ */
+const EmbedField = ({ label, value, isFirst }) => {
+    const { isCopied, hasFailed, copy } = useCopy();
+    const id = useId();
+    const field = useRef(null);
+    // the panel loads after the popover opens, so the popover's own focus finds nothing to take it
+    useEffect(() => {
+        if (isFirst === true)
+            field.current?.focus();
+    }, [isFirst]);
+    // with no clipboard, the text selected is one key away
+    useEffect(() => {
+        if (hasFailed)
+            field.current?.select();
+    }, [hasFailed]);
+    const buttonText = isCopied ? STRINGS.copied : LATER_STRINGS.copy;
+    return (_jsxs("div", { className: "forgebook-embed-field", children: [_jsx("label", { className: "forgebook-embed-field__label", htmlFor: id, children: label }), _jsx("input", { ref: field, id: id, className: "forgebook-embed-field__value", readOnly: true, value: value, onFocus: (event) => event.currentTarget.select() }), _jsx("button", { type: "button", className: "forgebook-button", "aria-label": `${LATER_STRINGS.copy}: ${label}`, "aria-live": "polite", onClick: () => copy(value), children: hasFailed ? LATER_STRINGS.embedCopyFailed : buttonText })] }));
+};
+/**
+ * The panel.
+ *
+ * @param props - the story, its view and its height.
+ */
+export const EmbedPanel = ({ storyId, title, query, height }) => {
+    const [isFollowing, setIsFollowing] = useState(false);
+    const page = `${window.location.origin}${window.location.pathname}`;
+    const link = embedAddressOf(page, storyId, query);
+    return (_jsxs(_Fragment, { children: [_jsx("p", { className: "forgebook-embed-panel__hint", children: LATER_STRINGS.embedHint }), _jsx(EmbedField, { label: LATER_STRINGS.embedLink, value: link, isFirst: true }), _jsx(EmbedField, { label: LATER_STRINGS.embedCode, value: embedCode({ link, title, height, isFollowing }) }), _jsxs("label", { className: "forgebook-embed-panel__follow", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": isFollowing, className: "forgebook-switch", checked: isFollowing, onChange: (event) => setIsFollowing(event.currentTarget.checked) }), LATER_STRINGS.embedFollow] }), isFollowing ? _jsx("p", { className: "forgebook-embed-panel__hint", children: LATER_STRINGS.embedFollowHint }) : null, isLocalAddress(link) ? (_jsx("p", { className: "forgebook-embed-panel__hint", "data-warning": "", children: LATER_STRINGS.embedLocal })) : null] }));
+};

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

@@ -22,4 +22,3 @@ export type EventsTabProps = {
  * @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.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Code } from "./Code.js";
-import { STRINGS } from "./strings.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 /** An event's signature as TypeScript would write it. */
 const signatureText = (event) => event.signature === undefined
     ? event.type
@@ -22,5 +22,4 @@ const CallLine = ({ call }) => {
  *
  * @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
+export const EventsTab = ({ events, calls, onClearCalls }) => (_jsxs("div", { className: "forgebook-tab-columns", children: [events.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: LATER_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: LATER_STRINGS.calls }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: onClearCalls, children: LATER_STRINGS.clearCalls })] }), calls.length === 0 ? _jsx("p", { className: "forgebook-prop__description", children: LATER_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(",")}`))) })] })] }));

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

@@ -12,6 +12,15 @@ import type { ViewSwitch } from "../switches.ts";
 import { type ViewState } from "../viewState.ts";
 import { type StoryTouches } from "./storyTouch.ts";
 import type { Loaded } from "./useLoaded.ts";
+/** How a page's audience draws its examples. */
+export type ExampleReading = {
+    /** Whether the examples offer their code. */
+    readonly hasCode: boolean;
+    /** Whether their code starts open. */
+    readonly isCodeOpen: boolean;
+    /** Whether the demo is drawn larger, with more room around it. */
+    readonly isDemoLarge: boolean;
+};
 /** What every example of the page shares: the frames' address, view and reports, the code, how to open a story. */
 export type ExampleContext = {
     /** The component. */
@@ -38,7 +47,7 @@ export type ExampleContext = {
     readonly settled: ReadonlySet<string>;
     /** The story file's code. */
     readonly code: Loaded<StoryFileCode>;
-    /** The component's name, for the JSX of a story drawn from its args. */
+    /** The component's name as code writes it (`codeNameOf`), for the code of a story drawn from its args. */
     readonly componentName: string;
     /** A story's own args, as its frame reported them; none before it loads. */
     readonly argsOf: (storyId: string) => PanelArgs;
@@ -46,7 +55,17 @@ export type ExampleContext = {
     readonly heightOf: (storyId: string) => number | undefined;
     /** The colour the stories' page has, which each box waits on. */
     readonly background: string | undefined;
+    /** How the page's audience draws its examples. */
+    readonly reading: ExampleReading;
 };
+/** A link to a story's own page, opened in place unless the user asks for another tab. */
+export declare const StoryLink: ({ story, hrefOf, onOpen, className, label, children }: Pick<ExampleContext, "hrefOf" | "onOpen"> & {
+    readonly story: TreeStory;
+    readonly className: string;
+    /** The link's name when its text is the same for every story; its text by default. */
+    readonly label?: string;
+    readonly children: ReactNode;
+}) => ReactNode;
 /**
  * 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 and opens the story on its own page.
@@ -60,4 +79,3 @@ export declare const Example: ({ story, isDemo, isMounted, observe, ...context }
     readonly isMounted: boolean;
     readonly observe?: (element: HTMLElement | null) => void;
 }) => ReactNode;
-//# sourceMappingURL=Example.d.ts.map

package/dist/src/shell/Example.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useId, useState } from "react";
-import { frameAddress } from "../viewState.js";
+import { deviceDefaultOf, shownDevice } from "../deviceView.js";
+import { frameAddress, schemeOf } from "../viewState.js";
 import { BoxWidthControl, useBoxWidth } from "./BoxWidth.js";
 import { CodeText } from "./CodeText.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { useCodeWriter } from "./codeWriter.js";
+import { DeviceSlot, deviceAddress, inkScheme, isWaitingForDevice, roomSizing, useFramedDevice } from "./DeviceSlot.js";
 import { FrameView } from "./FrameView.js";
 import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { StageViewport } from "./StageViewport.js";
 import { StoryCodeBlock, storyCodeText } from "./StoryCodeBlock.js";
 import { touchedView } from "./storyTouch.js";
@@ -14,12 +17,15 @@ import { STRINGS } from "./strings.js";
 import { useCopy } from "./useCopy.js";
 import { useFullPage } from "./useFullPage.js";
 import { useLoadedView } from "./useLiveView.js";
+import { useSystemDark } from "./useSystemDark.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;
+/** The least height of a demo an audience draws larger, in CSS px: its room, never a scale, so its sizes stay true. */
+const LARGE_DEMO_HEIGHT = 360;
 /** A link to a story's own page, opened in place unless the user asks for another tab. */
-const StoryLink = ({ story, hrefOf, onOpen, className, label, children }) => (_jsx("a", { className: className, "aria-label": label, href: hrefOf(story), onClick: (event) => {
+export const StoryLink = ({ story, hrefOf, onOpen, className, label, children }) => (_jsx("a", { className: className, "aria-label": label, href: hrefOf(story), onClick: (event) => {
         if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
             return;
         event.preventDefault();
@@ -33,7 +39,7 @@ const StoryLink = ({ story, hrefOf, onOpen, className, label, children }) => (_j
 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 })] }) }));
+    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 : LATER_STRINGS.copy }), _jsx(StoryCodeBlock, { ...source })] }) }));
 };
 /**
  * The height an example's story is drawn at least at: its scene's, and over the page the room its stage has.
@@ -61,16 +67,68 @@ const FullPageSlot = ({ full }) => (_jsxs(_Fragment, { children: [_jsx("div", {
  *
  * @param props - the story, whether its finger is on, and how to change it.
  */
-const TouchToggle = ({ story, isTouch, onTouchChange }) => (_jsxs("label", { className: "forgebook-example__touch", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": isTouch, "aria-label": STRINGS.touchNamed(story.name), className: "forgebook-switch", checked: isTouch, onChange: (event) => onTouchChange(story.id, event.currentTarget.checked) }), STRINGS.touch] }));
+const TouchToggle = ({ story, isTouch, onTouchChange }) => (_jsxs("label", { className: "forgebook-example__touch", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": isTouch, "aria-label": LATER_STRINGS.touchNamed(story.name), className: "forgebook-switch", checked: isTouch, onChange: (event) => onTouchChange(story.id, event.currentTarget.checked) }), LATER_STRINGS.touch] }));
 /**
  * An example's bar: its code shown or hidden, the story's width while its box fills the page, its box filling the page
  * or back in its place, and its story opened on its own page.
  *
  * @param props - the story, what every example shares, its code's state and its box's state over the page.
  */
-const ExampleBar = ({ story, context, hasCode, isCodeShown, onCodeShownChange, codeId, full, boxWidth }) => {
+const ExampleBar = ({ story, context, hasCode, isCodeShown, onCodeShownChange, codeId, full, boxWidth, isFramed }) => {
     const isTouch = context.touches.get(story.id);
-    return (_jsxs("div", { className: "forgebook-example__bar", children: [hasCode ? (_jsxs("button", { type: "button", className: "forgebook-example__toggle", "aria-expanded": isCodeShown, "aria-controls": codeId, onClick: () => onCodeShownChange(!isCodeShown), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), isCodeShown ? STRINGS.hideCode : STRINGS.showCode] })) : null, isTouch === undefined ? null : (_jsx(TouchToggle, { story: story, isTouch: isTouch, onTouchChange: context.onTouchChange })), _jsx(BoxWidthControl, { boxWidth: boxWidth }), _jsxs("button", { type: "button", className: "forgebook-example__full", "aria-label": full.isFull ? STRINGS.backToPlaceNamed(story.name) : STRINGS.fillPageNamed(story.name), onClick: (event) => full.toggle(event), children: [_jsx(Icon, { name: full.isFull ? "collapse" : "expand", size: 12 }), full.isFull ? STRINGS.backToPlace : STRINGS.fillPage] }), _jsxs(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-example__open", label: STRINGS.openStoryNamed(story.name), children: [STRINGS.openStory, _jsx(Icon, { name: "external", size: 12 })] })] }));
+    return (_jsxs("div", { className: "forgebook-example__bar", children: [hasCode ? (_jsxs("button", { type: "button", className: "forgebook-example__toggle", "aria-expanded": isCodeShown, "aria-controls": codeId, onClick: () => onCodeShownChange(!isCodeShown), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), isCodeShown ? LATER_STRINGS.hideCode : LATER_STRINGS.showCode] })) : null, isTouch === undefined ? null : (_jsx(TouchToggle, { story: story, isTouch: isTouch, onTouchChange: context.onTouchChange })), isFramed ? null : _jsx(BoxWidthControl, { boxWidth: boxWidth }), _jsxs("button", { type: "button", className: "forgebook-example__full", "aria-label": full.isFull ? LATER_STRINGS.backToPlaceNamed(story.name) : LATER_STRINGS.fillPageNamed(story.name), onClick: (event) => full.toggle(event), children: [_jsx(Icon, { name: full.isFull ? "collapse" : "expand", size: 12 }), full.isFull ? LATER_STRINGS.backToPlace : LATER_STRINGS.fillPage] }), _jsxs(StoryLink, { story: story, hrefOf: context.hrefOf, onOpen: context.onOpen, className: "forgebook-example__open", label: LATER_STRINGS.openStoryNamed(story.name), children: [LATER_STRINGS.openStory, _jsx(Icon, { name: "external", size: 12 })] })] }));
+};
+/**
+ * An example's code: what it shows, whether its audience offers it, and whether it is open: the audience's default until
+ * the person says otherwise, so changing audience opens or closes what they left alone.
+ *
+ * @param story - the story.
+ * @param context - what every example shares.
+ */
+const useExampleCode = (story, context) => {
+    const [ownCodeShown, setIsCodeShown] = useState(undefined);
+    const source = context.code.status === "ready"
+        ? {
+            code: context.code.value,
+            exportName: story.exportName,
+            componentName: context.componentName,
+            args: context.argsOf(story.id)
+        }
+        : undefined;
+    return {
+        source,
+        hasCode: source !== undefined && context.reading.hasCode,
+        isCodeShown: ownCodeShown ?? context.reading.isCodeOpen,
+        setIsCodeShown
+    };
+};
+/**
+ * The device an example is drawn in, over the page as in the list: the view's choice over the story's and the
+ * catalogue's defaults, and the ink of its status bar.
+ *
+ * @param story - the story.
+ * @param context - the page's view and switches.
+ */
+const useExampleDevice = (story, context) => {
+    const shown = shownDevice(context.view, deviceDefaultOf(useCatalogue().device, story.device));
+    return {
+        shown,
+        framed: useFramedDevice(shown),
+        scheme: inkScheme(schemeOf(context.view, context.switches), useSystemDark())
+    };
+};
+/**
+ * The heights an example's frame waits at: the story's measured one when there is one, a guess otherwise (larger for
+ * the demo), never below the height its scene needs; and the least a large demo is given.
+ *
+ * @param story - the story.
+ * @param context - the page's measured heights and how it reads.
+ * @param isDemo - whether it is the page's demo.
+ */
+const exampleHeights = (story, context, isDemo) => {
+    const least = isDemo && context.reading.isDemoLarge ? LARGE_DEMO_HEIGHT : 0;
+    const guess = isDemo ? DEMO_FALLBACK_HEIGHT : FALLBACK_HEIGHT;
+    return { fallback: Math.max(story.height ?? 0, context.heightOf(story.id) ?? guess, least), least };
 };
 /**
  * One example: its title and description (the demo has none: it opens the page), its story in a frame, and a bar
@@ -80,26 +138,21 @@ const ExampleBar = ({ story, context, hasCode, isCodeShown, onCodeShownChange, c
  * every example shares.
  */
 export const Example = ({ story, isDemo, isMounted, observe, ...context }) => {
-    const [isCodeShown, setIsCodeShown] = useState(false);
+    const { source, hasCode, isCodeShown, setIsCodeShown } = useExampleCode(story, context);
     const codeId = useId();
     const full = useFullPage();
     const { touch } = useCatalogue();
+    const { shown, framed, scheme } = useExampleDevice(story, context);
     // the frame loads with the story's finger as it is then; a change after reaches it live, keeping the story's state
     const loadedView = useLoadedView(context.frameView.sheets, touchedView(context.frameView, story.id, context.touches, touch));
     const boxWidth = useBoxWidth(full.isOver, context.view.width);
-    // 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 : _jsx(ExampleHead, { story: story, context: context }), full.isOver ? _jsx(FullPageSlot, { full: full }) : null, _jsxs("div", { ref: full.boxRef, className: "forgebook-example__box", "data-full": full.isOver ? "" : undefined, ...(full.isFull ? { role: "dialog", "aria-label": story.name } : {}), children: [_jsx("div", { ref: full.stageRef, className: "forgebook-example__stage", children: _jsx(StageViewport, { width: boxWidth.width, onWidthChange: boxWidth.onWidthChange, onShownWidthChange: boxWidth.onShownWidthChange, background: context.background, children: isMounted ? (_jsx(FrameView, { title: STRINGS.frameTitle(context.component.name, story.name), address: frameAddress(context.frameUrl, story.id, loadedView, context.switches), heights: context.heights, settled: context.settled, fallbackHeight: fallbackHeight, 
-                                // over the page, the story fills the room it has
-                                sceneHeight: sceneHeightOf(story, full.stageHeight) })) : (_jsx("div", { className: "forgebook-frame-placeholder", style: { height: fallbackHeight } })) }) }), _jsx(ExampleBar, { story: story, context: context, hasCode: source !== undefined, isCodeShown: isCodeShown, onCodeShownChange: setIsCodeShown, codeId: codeId, full: full, boxWidth: boxWidth }), source === undefined ? null : _jsx(ExampleCode, { id: codeId, source: source, isShown: isCodeShown })] })] }));
+    const { fallback: fallbackHeight, least: leastHeight } = exampleHeights(story, context, isDemo);
+    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 : _jsx(ExampleHead, { story: story, context: context }), full.isOver ? _jsx(FullPageSlot, { full: full }) : null, _jsxs("div", { ref: full.boxRef, className: "forgebook-example__box", "data-full": full.isOver ? "" : undefined, ...(full.isFull ? { role: "dialog", "aria-label": story.name } : {}), children: [_jsx("div", { ref: full.stageRef, className: "forgebook-example__stage", children: _jsx(StageViewport, { ...roomSizing(framed, {
+                                width: boxWidth.width,
+                                onWidthChange: boxWidth.onWidthChange,
+                                onShownWidthChange: boxWidth.onShownWidthChange,
+                                background: context.background
+                            }), children: _jsx(DeviceSlot, { framed: framed, scheme: scheme, background: context.background, children: isMounted && !isWaitingForDevice(shown, framed) ? (_jsx(FrameView, { title: STRINGS.frameTitle(context.component.name, story.name), address: deviceAddress(frameAddress(context.frameUrl, story.id, loadedView, context.switches), framed), heights: context.heights, settled: context.settled, fallbackHeight: fallbackHeight, 
+                                    // over the page, the story fills the room it has
+                                    sceneHeight: Math.max(sceneHeightOf(story, full.stageHeight) ?? 0, leastHeight), fixedHeight: framed?.area.height })) : (_jsx("div", { className: "forgebook-frame-placeholder", style: { height: framed?.area.height ?? fallbackHeight } })) }) }) }), _jsx(ExampleBar, { story: story, context: context, hasCode: hasCode, isCodeShown: isCodeShown, onCodeShownChange: setIsCodeShown, codeId: codeId, full: full, boxWidth: boxWidth, isFramed: framed !== undefined }), source === undefined || !hasCode ? null : (_jsx(ExampleCode, { id: codeId, source: source, isShown: isCodeShown }))] })] }));
 };
-//# sourceMappingURL=Example.js.map

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

@@ -23,7 +23,7 @@ export type FrameViewProps = {
      */
     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;
+     * A height set on the stage (the foot handle), in CSS px: the frame takes it whatever its story's;
      * none by default.
      */
     readonly fixedHeight?: number | undefined;
@@ -53,4 +53,3 @@ export declare const tellFrames: (container: HTMLElement | null, message: ShellM
  * @param messageOf - the message for a frame's story (the address's `story`; none when it names none).
  */
 export declare const tellEachFrame: (container: HTMLElement | null, messageOf: (storyId: string | undefined) => ShellMessage) => void;
-//# sourceMappingURL=FrameView.d.ts.map

package/dist/src/shell/FrameView.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { framesOrigin, storyFrameAttributes } from "./framesOrigin.js";
 import { STRINGS } from "./strings.js";
 /**
  * A story's frame, as tall as its story.
@@ -13,7 +14,7 @@ export const FrameView = ({ title, address, heights, fallbackHeight, settled, sc
     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] }));
+    return (_jsxs("div", { className: "forgebook-frame-box", "data-loading": isLoading ? "" : undefined, children: [_jsx("iframe", { ref: ref, className: "forgebook-frame-view", title: title, src: address, ...storyFrameAttributes(), 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.
@@ -23,7 +24,7 @@ export const FrameView = ({ title, address, heights, fallbackHeight, settled, sc
  */
 export const tellFrames = (container, message) => {
     for (const frame of container?.querySelectorAll("iframe") ?? []) {
-        frame.contentWindow?.postMessage(message, window.location.origin);
+        frame.contentWindow?.postMessage(message, framesOrigin());
     }
 };
 /**
@@ -35,7 +36,6 @@ export const tellFrames = (container, message) => {
 export const tellEachFrame = (container, messageOf) => {
     for (const frame of container?.querySelectorAll("iframe") ?? []) {
         const storyId = new URL(frame.src, window.location.href).searchParams.get("story") ?? undefined;
-        frame.contentWindow?.postMessage(messageOf(storyId), window.location.origin);
+        frame.contentWindow?.postMessage(messageOf(storyId), framesOrigin());
     }
 };
-//# sourceMappingURL=FrameView.js.map

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

@@ -1,6 +1,6 @@
 /**
- * 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.
+ * The catalogue's home: the pages opened last, then each source with its own introduction, its docs pages 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
@@ -11,7 +11,7 @@
  */
 import type { StorySource } from "@forgebook/story-format/source";
 import { type ReactNode } from "react";
-import { type StoryTree } from "../storyTree.ts";
+import { type StoryTree, type TreeFamily, type TreeSource } from "../storyTree.ts";
 import type { RecentPage } from "./useRecentPages.ts";
 /** The home's props. */
 export type HomePageProps = {
@@ -30,10 +30,84 @@ export type HomePageProps = {
     /** What stays above the home: the index's problems, when it has some. */
     readonly header: ReactNode;
 };
+/** A link to a page, opened in place unless the user asks for another tab. */
+export declare const PageLink: ({ page, hrefOf, onOpen, className, children }: Pick<HomePageProps, "hrefOf" | "onOpen"> & {
+    readonly page: RecentPage;
+    readonly className: string;
+    readonly children: ReactNode;
+}) => ReactNode;
+/** A recent page as the home lists it: its name and its place, or none when the tree no longer has it. */
+type RecentEntry = {
+    /** The page. */
+    readonly page: RecentPage;
+    /** The component's or the story's name. */
+    readonly name: string;
+    /** Where it sits: the component's place, and its name for a story. */
+    readonly place: string;
+};
+/**
+ * The recent pages the tree still has, with their names and places.
+ *
+ * @param tree - the tree.
+ * @param recent - the pages opened last.
+ */
+export declare const recentEntries: (tree: StoryTree, recent: readonly RecentPage[]) => RecentEntry[];
+/**
+ * A source's introduction, as its package wrote it; nothing while it loads or when the source has none.
+ *
+ * @param props - the loader.
+ */
+export declare const SourceIntro: ({ load }: {
+    readonly load: StorySource["home"];
+}) => ReactNode;
+/**
+ * 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 family, and how to open a component.
+ */
+export declare const FamilyCard: ({ family, hrefOf, onOpen }: Pick<HomePageProps, "hrefOf" | "onOpen"> & {
+    readonly family: TreeFamily;
+}) => ReactNode;
+/**
+ * A source's docs pages as a card, in their reading order, first among its families.
+ *
+ * @param props - the source, and how to open a page.
+ */
+export declare const DocsCard: ({ source, hrefOf, onOpen }: Pick<HomePageProps, "hrefOf" | "onOpen"> & {
+    readonly source: TreeSource;
+}) => ReactNode;
+/**
+ * How many components a tree has, in every library.
+ *
+ * @param tree - the tree.
+ */
+export declare const componentCount: (tree: StoryTree) => number;
+/**
+ * How many libraries of a tree have components.
+ *
+ * @param tree - the tree.
+ */
+export declare const libraryCount: (tree: StoryTree) => number;
+/**
+ * The pages opened last, under their heading; nothing when there are none.
+ *
+ * @param props - the tree, the recent pages, how to open one, and the heading; "Recently opened" by default.
+ */
+export declare const RecentSection: ({ tree, recent, hrefOf, onOpen, label }: Pick<HomePageProps, "tree" | "recent" | "hrefOf" | "onOpen"> & {
+    readonly label?: string | undefined;
+}) => ReactNode;
+/**
+ * A library on the home: its name and logo, its introduction, its docs pages and its families.
+ *
+ * @param props - the library, the sources for its introduction, and how to open a page.
+ */
+export declare const LibrarySection: ({ source, sources, hrefOf, onOpen }: Pick<HomePageProps, "sources" | "hrefOf" | "onOpen"> & {
+    readonly source: TreeSource;
+}) => 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
+export {};