forgebook 0.1.7 → 0.2.0

package/dist/src/shell/DocContents.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A docs page's contents: its second- and third-level headings, the one being read marked, as a column beside the text
+ * where there is room and a list that folds above it where there is not.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+import { headingElementId } from "../docAnchors.js";
+import { filledText } from "../docPages.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
+/** How far below the page's top a heading counts as being read, in CSS px. */
+const READING_LINE = 96;
+/** How far from the page's end the last heading counts as being read: a short last section never reaches the line. */
+const END_ROOM = 2;
+/**
+ * The heading being read: the last one past the reading line, or the last of all at the end of the page.
+ *
+ * @param scroller - the page's scrolling element.
+ * @param headings - the page's headings.
+ */
+const readHeading = (scroller, headings) => {
+    if (scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - END_ROOM)
+        return headings.at(-1)?.anchor;
+    const line = scroller.getBoundingClientRect().top + READING_LINE;
+    let current = headings[0]?.anchor;
+    for (const heading of headings) {
+        const element = scroller.querySelector(`[id="${CSS.escape(headingElementId(heading.anchor))}"]`);
+        if (element === null)
+            continue;
+        if (element.getBoundingClientRect().top > line)
+            break;
+        current = heading.anchor;
+    }
+    return current;
+};
+/**
+ * The heading being read, followed as the page scrolls.
+ *
+ * @param ref - the page's scrolling element.
+ * @param headings - the page's headings.
+ */
+const useReadHeading = (ref, headings) => {
+    const [current, setCurrent] = useState(undefined);
+    useEffect(() => {
+        const scroller = ref.current;
+        if (scroller === null)
+            return;
+        let frame;
+        const follow = () => {
+            frame ??= window.requestAnimationFrame(() => {
+                frame = undefined;
+                setCurrent(readHeading(scroller, headings));
+            });
+        };
+        follow();
+        scroller.addEventListener("scroll", follow, { passive: true });
+        return () => {
+            scroller.removeEventListener("scroll", follow);
+            if (frame !== undefined)
+                window.cancelAnimationFrame(frame);
+        };
+    }, [ref, headings]);
+    return current;
+};
+/**
+ * The list of headings.
+ *
+ * @param props - the headings, the one being read, and how to go to one.
+ */
+const ContentsList = ({ headings, values, current, hrefOf, onOpen }) => (_jsx("ul", { className: "forgebook-contents__list", children: headings.map((heading) => (_jsx("li", { "data-depth": heading.depth, children: _jsx("a", { className: "forgebook-contents__link", href: hrefOf(heading.anchor), "aria-current": heading.anchor === current ? "location" : undefined, onClick: (event) => {
+                if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                    return;
+                event.preventDefault();
+                onOpen(heading.anchor);
+            }, children: filledText(heading.text, values) }) }, heading.anchor))) }));
+/**
+ * A page's contents; nothing for a page with fewer than two headings, which has nothing to find.
+ *
+ * @param props - the headings, the page's scrolling element, whether there is room for a column, and the links.
+ */
+export const DocContents = ({ headings, values, scrollRef, isColumn, hrefOf, onOpen }) => {
+    const current = useReadHeading(scrollRef, headings);
+    if (headings.length < 2)
+        return null;
+    const list = (_jsx(ContentsList, { headings: headings, values: values, current: current, hrefOf: hrefOf, onOpen: onOpen }));
+    return isColumn ? (_jsxs("nav", { className: "forgebook-contents forgebook-contents--column", "aria-label": PAGE_STRINGS.pageContents, children: [_jsx("p", { className: "forgebook-contents__title", children: PAGE_STRINGS.pageContents }), list] })) : (_jsxs("details", { className: "forgebook-contents forgebook-contents--fold", children: [_jsx("summary", { className: "forgebook-contents__title", children: PAGE_STRINGS.pageContents }), _jsx("nav", { "aria-label": PAGE_STRINGS.pageContents, children: list })] }));
+};

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

@@ -0,0 +1,69 @@
+/**
+ * A docs page: Markdown a package wrote, with live stories, under the catalogue's header, with its contents beside it
+ * and the pages around it at its foot.
+ *
+ * @remarks
+ * Loaded on first use, since a catalogue may have none: the shell's first load pays nothing for it, here or in its
+ * style sheet. The text comes rendered from the plugin (`vite/docPageMarkdown.ts`); a story's frame loads as it comes
+ * near, and the view reaches the frames live, as on a component's page.
+ *
+ * @module
+ */
+import "./docPage.scss";
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ReactNode } from "react";
+import type { PageLocation } from "../pageTree.ts";
+import { type StoryTree, type TreeSource, type TreeStory } from "../storyTree.ts";
+import type { ViewState } from "../viewState.ts";
+import type { ShellPlugin } from "./pluginTabs.tsx";
+import type { TouchOverrides } from "./storyTouch.ts";
+import { type PageScroll } from "./useScrollMemory.ts";
+/** The docs page's props. */
+export type DocPageProps = {
+    /** The catalogue's name, for the values a page's text names. */
+    readonly title: string;
+    /** The plugins, whose blocks the page may hold. */
+    readonly plugins: readonly ShellPlugin[];
+    /** The page and its source. */
+    readonly location: PageLocation;
+    /** The heading the address names; none when it names none. */
+    readonly anchor: string | undefined;
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The sources, with their loaders. */
+    readonly sources: readonly StorySource[];
+    /** The view. */
+    readonly view: ViewState;
+    /** What the user chose for each story marked for a phone. */
+    readonly touchOverrides: TouchOverrides;
+    /** Called when the user turns a story's finger on or off. */
+    readonly onTouchChange: (storyId: string, isTouch: boolean) => void;
+    /** The frame page's address. */
+    readonly frameUrl: string;
+    /** The address of a story's page, for its link. */
+    readonly storyHrefOf: (story: TreeStory) => string;
+    /** Opens a story's page. */
+    readonly onOpenStory: (story: TreeStory) => void;
+    /** The address of a docs page, by its id and anchor. */
+    readonly pageHrefOf: (id: string, anchor: string | undefined) => string;
+    /** Opens a docs page. */
+    readonly onOpenPage: (id: string) => void;
+    /** Goes to a heading of the shown page, as a new entry of the history. */
+    readonly onOpenAnchor: (anchor: string) => void;
+    /** Opens an address of the catalogue a page's text links to; `false` when it names no page of the catalogue. */
+    readonly onOpenAddress: (address: string) => boolean;
+    /** A story's measured height, for its box while it loads. */
+    readonly heightOf: (storyId: string) => number | undefined;
+    /** The colour a source's stories' page has in the view, which each box waits on. */
+    readonly backgroundOf: (source: TreeSource) => string | undefined;
+    /** What stays above the page while it scrolls: its header. */
+    readonly header: ReactNode;
+    /** Where its scrolling part starts: the shell's visit of the page and every page's last position. */
+    readonly scroll: PageScroll;
+};
+/**
+ * A docs page.
+ *
+ * @param props - the page, its anchor, the view, and how it opens what it links to.
+ */
+export declare const DocPage: ({ title, plugins, location, anchor, tree, sources, view, touchOverrides, onTouchChange, frameUrl, storyHrefOf, onOpenStory, pageHrefOf, onOpenPage, onOpenAnchor, onOpenAddress, heightOf, backgroundOf, header, scroll }: DocPageProps) => ReactNode;

package/dist/src/shell/DocPage.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A docs page: Markdown a package wrote, with live stories, under the catalogue's header, with its contents beside it
+ * and the pages around it at its foot.
+ *
+ * @remarks
+ * Loaded on first use, since a catalogue may have none: the shell's first load pays nothing for it, here or in its
+ * style sheet. The text comes rendered from the plugin (`vite/docPageMarkdown.ts`); a story's frame loads as it comes
+ * near, and the view reaches the frames live, as on a component's page.
+ *
+ * @module
+ */
+import "./docPage.css";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { isDocPage } from "../docPages.js";
+import { anchorOf } from "../pageAddress.js";
+import { sourcePages } from "../sourceFiles.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 { DocContents } from "./DocContents.js";
+import { Icon } from "./icons.js";
+import { PAGE_STRINGS } from "./pageStrings.js";
+import { STRINGS } from "./strings.js";
+import { useAnchorScroll } from "./useAnchorScroll.js";
+import { useLoaded } from "./useLoaded.js";
+import { usePageFrames } from "./usePageFrames.js";
+import { useProseLinks } from "./useProseLinks.js";
+import { useScrollMemory } from "./useScrollMemory.js";
+/** The narrowest page that takes the contents as a column beside its text, in CSS px. */
+const COLUMN_WIDTH = 900;
+/** A page that loaded no block yet: its frames wait for it. */
+const NO_BLOCKS = { blocks: [], headings: [], assets: [] };
+/** What the plugin answered, as a state. */
+const pageState = (value) => isDocPage(value)
+    ? { status: "ready", value }
+    : { status: "error", message: "The page has an unexpected shape" };
+/**
+ * The pages before and after one, in the reading order of its source.
+ *
+ * @param pages - the source's pages.
+ * @param id - the page's id.
+ */
+const pagesAround = (pages, id) => {
+    const place = pages.findIndex((page) => page.id === id);
+    return { previous: pages[place - 1], next: pages[place + 1] };
+};
+/**
+ * A page's foot: the pages before and after it.
+ *
+ * @param props - the two pages, and how to open one.
+ */
+const PageFoot = ({ previous, next, hrefOf, onOpen }) => {
+    const link = (page, label, side) => page === undefined ? (_jsx("span", {})) : (_jsxs("a", { className: "forgebook-docs__around", "data-side": side, href: hrefOf(page.id, undefined), onClick: (event) => {
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                return;
+            event.preventDefault();
+            onOpen(page.id);
+        }, children: [_jsx("span", { className: "forgebook-docs__around-label", children: label }), _jsxs("span", { className: "forgebook-docs__around-name", children: [page.name, side === "next" ? _jsx(Icon, { name: "chevronRight", size: 12 }) : null] })] }));
+    return previous === undefined && next === undefined ? null : (_jsxs("nav", { className: "forgebook-docs__foot", "aria-label": STRINGS.docsNav, children: [link(previous, PAGE_STRINGS.previousPage, "previous"), link(next, PAGE_STRINGS.nextPage, "next")] }));
+};
+/**
+ * The page's width, followed as the window or the sidebar changes it.
+ *
+ * @param ref - the page's scrolling element.
+ */
+const usePageWidth = (ref) => {
+    const [width, setWidth] = useState(undefined);
+    useLayoutEffect(() => {
+        const element = ref.current;
+        if (element === null)
+            return;
+        setWidth(element.clientWidth);
+        const resizes = new ResizeObserver(() => setWidth(element.clientWidth));
+        resizes.observe(element);
+        return () => resizes.disconnect();
+    }, [ref]);
+    return width;
+};
+/** The page's text once it is there, or why it could not be read. */
+const loadedPage = (loaded) => loaded.status === "ready" ? loaded.value : NO_BLOCKS;
+/**
+ * A docs page.
+ *
+ * @param props - the page, its anchor, the view, and how it opens what it links to.
+ */
+export const DocPage = ({ title, plugins, location, anchor, tree, sources, view, touchOverrides, onTouchChange, frameUrl, storyHrefOf, onOpenStory, pageHrefOf, onOpenPage, onOpenAnchor, onOpenAddress, heightOf, backgroundOf, header, scroll }) => {
+    const { page, source } = location;
+    const pageRef = useRef(null);
+    const bodyRef = useRef(null);
+    const owner = sources.find((candidate) => candidate.id === source.id);
+    const load = owner === undefined ? undefined : sourcePages(owner).pages[page.file];
+    const loaded = useLoaded(load, pageState);
+    const content = loadedPage(loaded);
+    const catalogue = useCatalogue();
+    const stories = useMemo(() => page.stories.flatMap((id) => findStory(tree, id)?.story ?? []), [page.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 placeAgain = useAnchorScroll(pageRef, anchor, scroll.visit, loaded.status === "ready");
+    const goToAnchor = useCallback((target) => {
+        if (target === anchor)
+            placeAgain();
+        else
+            onOpenAnchor(target);
+    }, [anchor, onOpenAnchor, placeAgain]);
+    const width = usePageWidth(pageRef);
+    const openLink = useCallback((href) => {
+        if (href.startsWith("#")) {
+            goToAnchor(anchorOf(href.slice(1)) ?? "");
+            return true;
+        }
+        return href.startsWith("?") && onOpenAddress(href);
+    }, [goToAnchor, onOpenAddress]);
+    useProseLinks(bodyRef, openLink);
+    const context = {
+        tree,
+        sources,
+        frames,
+        view,
+        frameUrl,
+        plugins,
+        strings: catalogue.strings,
+        switches: catalogue.switches,
+        assets: content.assets,
+        pageHrefOf: (slug, target) => pageHrefOf(`${source.id}:${slug}`, target),
+        stories: { hrefOf: storyHrefOf, onOpen: onOpenStory },
+        onTouchChange,
+        heightOf,
+        backgroundOf,
+        values,
+        onOpenAddress: openLink,
+        places
+    };
+    const isColumn = width !== undefined && width >= COLUMN_WIDTH;
+    const contents = (_jsx(DocContents, { headings: content.headings, values: values, scrollRef: pageRef, isColumn: isColumn, hrefOf: (target) => pageHrefOf(page.id, target), onOpen: goToAnchor }));
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-docs", children: [_jsxs("article", { ref: bodyRef, className: "forgebook-doc forgebook-docs__body", children: [page.description === undefined ? null : (_jsx("p", { className: "forgebook-doc__lead", children: _jsx(CodeText, { text: page.description }) })), isColumn ? null : contents, loaded.status === "error" ? (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [PAGE_STRINGS.docPageError, ": ", loaded.message] })) : null, _jsx(DocBlocks, { blocks: content.blocks, context: context }), _jsx(PageFoot, { ...pagesAround(source.pages, page.id), hrefOf: pageHrefOf, onOpen: onOpenPage })] }), isColumn ? contents : null] }) })] }));
+};

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

@@ -1,5 +1,5 @@
 /**
- * The panel docked under a story: a row of tabs (Props, Events, Parts and styling, Code, Accessibility) and the chosen
+ * The panel docked under a story: a row of tabs (Props, Events, Parts and styling, Code, a plugin's, 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
@@ -39,4 +39,3 @@ export type DockProps = {
  * @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.js

@@ -1,6 +1,6 @@
 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
+ * The panel docked under a story: a row of tabs (Props, Events, Parts and styling, Code, a plugin's, 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
@@ -87,4 +87,3 @@ export const Dock = ({ tabs, activeTab, onTabChange, onClose }) => {
                                 }, 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/DroppedArgsList.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The note above a story whose address names values it does not take: which ones were left out and why, and a button
+ * that removes them from the address. Loaded only for such a link (`DroppedArgsNote.tsx`).
+ *
+ * @remarks
+ * A link may carry values the story never declared (a prop renamed since, or a link crafted to reach an element's
+ * attributes): they never reach the frame (`addressArgs.ts`), and the person who opened the link sees that they did
+ * not, instead of a story that silently differs from the shared view.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { DroppedArg } from "../addressArgs.ts";
+/** The note's props. */
+export type DroppedArgsListProps = {
+    /** The values left out. */
+    readonly dropped: readonly DroppedArg[];
+    /** Removes them from the address. */
+    readonly onRemove: () => void;
+};
+/**
+ * The note.
+ *
+ * @param props - the values left out and the remover.
+ */
+export declare const DroppedArgsList: ({ dropped, onRemove }: DroppedArgsListProps) => ReactNode;

package/dist/src/shell/DroppedArgsList.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LATER_STRINGS } from "./laterStrings.js";
+/**
+ * The note.
+ *
+ * @param props - the values left out and the remover.
+ */
+export const DroppedArgsList = ({ dropped, onRemove }) => (_jsxs("div", { className: "forgebook-dropped-args", role: "status", children: [_jsx("p", { className: "forgebook-dropped-args__text", children: LATER_STRINGS.droppedArgs }), _jsx("ul", { className: "forgebook-dropped-args__list", children: dropped.map(({ name, reason }) => (_jsxs("li", { children: [_jsx("code", { children: name }), " ", LATER_STRINGS.droppedArgReasons[reason]] }, name))) }), _jsx("button", { type: "button", className: "forgebook-text-button", onClick: onRemove, children: LATER_STRINGS.removeDroppedArgs })] }));

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

@@ -0,0 +1,14 @@
+/**
+ * The note above a story whose address names values it does not take. Such a link is rare, so the note's module
+ * (`DroppedArgsList.tsx`) loads only when one is opened: the first screen carries this check alone.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { DroppedArgsListProps } from "./DroppedArgsList.tsx";
+/**
+ * The note; nothing when no value was left out, nor when its module cannot load.
+ *
+ * @param props - the values left out and the remover.
+ */
+export declare const DroppedArgsNote: (props: DroppedArgsListProps) => ReactNode;

package/dist/src/shell/DroppedArgsNote.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { LazyView, lazyModule } from "./lazyModule.js";
+/** The note's module, loaded for the first link that names values its story does not take. */
+const DROPPED_ARGS_LIST = lazyModule(() => import("./DroppedArgsList.js").then((module) => module.DroppedArgsList));
+/**
+ * The note; nothing when no value was left out, nor when its module cannot load.
+ *
+ * @param props - the values left out and the remover.
+ */
+export const DroppedArgsNote = (props) => props.dropped.length === 0 ? null : (_jsx(LazyView, { module: DROPPED_ARGS_LIST, props: props, loading: null, failed: () => null }));

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

@@ -0,0 +1,19 @@
+/**
+ * The story bar's Embed button: a popover with the story's link and code. The button is all the first screen carries;
+ * the panel loads the first time it opens.
+ *
+ * @remarks
+ * The panel is placed on the window, not in the story's pane, which scrolls and would clip it: on a short window or
+ * with the dock open the pane can be shorter than the panel. Its load is watched here rather than through a suspending
+ * component, since the shell has no error boundary and a stale tab after a deployment would lose the whole page.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { EmbedPanelProps } from "./EmbedPanel.tsx";
+/**
+ * The button and its panel; nothing where the catalogue turns it off.
+ *
+ * @param props - what the panel shows.
+ */
+export declare const EmbedButton: (props: EmbedPanelProps) => ReactNode;

package/dist/src/shell/EmbedButton.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The story bar's Embed button: a popover with the story's link and code. The button is all the first screen carries;
+ * the panel loads the first time it opens.
+ *
+ * @remarks
+ * The panel is placed on the window, not in the story's pane, which scrolls and would clip it: on a short window or
+ * with the dock open the pane can be shorter than the panel. Its load is watched here rather than through a suspending
+ * component, since the shell has no error boundary and a stale tab after a deployment would lose the whole page.
+ *
+ * @module
+ */
+import { useEffect, useLayoutEffect, useState } from "react";
+import { useCatalogue } from "./catalogueContext.js";
+import { Icon } from "./icons.js";
+import { STRINGS } from "./strings.js";
+import { usePopover } from "./usePopover.js";
+/** The room kept between the panel and its button, in CSS px. */
+const BUTTON_GAP = 6;
+/** The room kept between the panel and the window's edges, in CSS px. */
+const WINDOW_MARGIN = 12;
+/**
+ * The panel's module, loaded when it is first needed and tried again each time the panel opens after a failure.
+ *
+ * @param isNeeded - whether the panel is drawn.
+ */
+const usePanelLoad = (isNeeded) => {
+    const [load, setLoad] = useState("loading");
+    useEffect(() => {
+        if (!isNeeded)
+            return;
+        import("./EmbedPanel.js")
+            .then(({ EmbedPanel }) => setLoad({ panel: EmbedPanel }))
+            .catch(() => setLoad("failed"));
+    }, [isNeeded]);
+    return load;
+};
+/**
+ * Keeps the panel under its button, its end aligned with the button's, and inside the window whatever its height.
+ *
+ * @param isDrawn - whether the panel is drawn.
+ * @param buttonRef - the button.
+ * @param panelRef - the panel.
+ */
+const usePanelPlace = (isDrawn, buttonRef, panelRef) => {
+    useLayoutEffect(() => {
+        const button = buttonRef.current;
+        const panel = panelRef.current;
+        if (!isDrawn || button === null || panel === null)
+            return;
+        const place = () => {
+            const { bottom, right } = button.getBoundingClientRect();
+            const lowest = window.innerHeight - panel.offsetHeight - WINDOW_MARGIN;
+            panel.style.top = `${Math.max(WINDOW_MARGIN, Math.min(bottom + BUTTON_GAP, lowest))}px`;
+            const width = document.documentElement.clientWidth;
+            const furthest = width - panel.offsetWidth - WINDOW_MARGIN;
+            panel.style.right = `${Math.max(WINDOW_MARGIN, Math.min(width - right, furthest))}px`;
+        };
+        place();
+        // it grows as its content loads and as the code gains its script
+        const observer = new ResizeObserver(place);
+        observer.observe(panel);
+        window.addEventListener("resize", place);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener("resize", place);
+        };
+    }, [isDrawn, buttonRef, panelRef]);
+};
+/**
+ * What the popover holds while it loads, once it has, or when it could not.
+ *
+ * @param props - the panel's load and what it shows.
+ */
+const PanelContent = ({ load, ...props }) => {
+    if (load === "loading")
+        return _jsx("span", { className: "forgebook-spinner", "aria-hidden": "true" });
+    if (load === "failed")
+        return _jsx("p", { role: "alert", children: STRINGS.embedPanelFailed });
+    const { panel: Panel } = load;
+    return _jsx(Panel, { ...props });
+};
+/**
+ * The button and its panel; nothing where the catalogue turns it off.
+ *
+ * @param props - what the panel shows.
+ */
+export const EmbedButton = (props) => {
+    const { hasEmbed } = useCatalogue();
+    const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
+    const load = usePanelLoad(isDrawn);
+    usePanelPlace(isDrawn, buttonRef, panelRef);
+    if (!hasEmbed)
+        return null;
+    return (_jsxs("div", { className: "forgebook-embed-menu", children: [_jsx("button", { ref: buttonRef, type: "button", className: "forgebook-button forgebook-button--icon", title: STRINGS.embedStory, "aria-label": STRINGS.embedStory, "aria-expanded": isOpen, "aria-controls": panelId, onClick: (event) => setIsOpen(!isOpen, event), children: _jsx(Icon, { name: "embed", size: 14 }) }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--embed", role: "dialog", "aria-label": STRINGS.embedStory, children: _jsx(PanelContent, { load: load, ...props }) })) : null] }));
+};

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

@@ -0,0 +1,23 @@
+/**
+ * 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.scss";
+import { type ReactNode } from "react";
+import type { ShellConfig } from "./Shell.tsx";
+/**
+ * One story alone, inside the catalogue's settings.
+ *
+ * @param props - the catalogue's configuration.
+ */
+export declare const EmbedPage: (props: ShellConfig) => ReactNode;