forgebook 0.1.8 → 0.3.0

package/dist/src/shell/useFrameMessages.js

@@ -1,11 +1,18 @@
 /**
  * What the frames tell the shell: which story can replay, which reads the story clock, each frame's content height, which frames finished loading, its story's own args, the
- * calls of its events, its play function's trace, and the result of an accessibility check.
+ * calls of its events, its play function's trace, the args a story changed itself, and the result of an accessibility
+ * check.
  *
  * @module
  */
 import { useEffect, useRef, useState } from "react";
 import { isFrameMessage } from "../messages.js";
+import { isFromFrames } from "./framesOrigin.js";
+/**
+ * Marks a frame shown beside the page's own, which answers it itself: a story's second frame reporting here would
+ * replace the stage's play trace and add to its spills and its calls, though it runs at another size.
+ */
+export const FRAME_ASIDE_ATTRIBUTE = "data-forgebook-aside";
 /** The frame element a message came from. */
 const frameOf = (source) => source === null
     ? undefined
@@ -14,7 +21,7 @@ const frameOf = (source) => source === null
 const isSettling = (message) => message.type === "forgebook:ready" || message.type === "forgebook:error";
 /** Acts on one message of a frame. */
 const onFrameMessage = (message, frame, targets) => {
-    const address = frame?.getAttribute("src") ?? undefined;
+    const address = frame.getAttribute("src") ?? undefined;
     if (isSettling(message) && address !== undefined)
         targets.markSettled(address);
     const { handlers } = targets;
@@ -24,7 +31,7 @@ const onFrameMessage = (message, frame, targets) => {
                 targets.setReplayable(message.storyId);
             if (message.hasClock)
                 targets.setClocked(message.storyId);
-            if (frame?.contentWindow)
+            if (frame.contentWindow)
                 handlers.onReady(frame.contentWindow, message);
             return;
         case "forgebook:size":
@@ -32,7 +39,7 @@ const onFrameMessage = (message, frame, targets) => {
                 targets.setHeight(address, message.height);
             return;
         case "forgebook:error":
-            handlers.onFailed?.(message.storyId);
+            handlers.onFailed?.(message.storyId, message.message);
             return;
         case "forgebook:play":
             handlers.onPlay?.(message.storyId, message.trace);
@@ -46,6 +53,12 @@ const onFrameMessage = (message, frame, targets) => {
         case "forgebook:spills":
             handlers.onSpills?.(message.storyId, message.count, address ?? "");
             return;
+        case "forgebook:plugin":
+            handlers.onPluginReport?.(message);
+            return;
+        case "forgebook:story-args":
+            handlers.onStoryArgs?.(message.storyId, message.args);
+            return;
         case "forgebook:call":
             handlers.onCall({
                 storyId: message.storyId,
@@ -75,9 +88,13 @@ export const useFrameMessages = (handlers) => {
     handlersRef.current = handlers;
     useEffect(() => {
         const listen = (event) => {
-            if (event.origin !== window.location.origin || !isFrameMessage(event.data))
+            if (!isFromFrames(event) || !isFrameMessage(event.data))
+                return;
+            // a frame of this page, not a window a story opened on the frames' origin or another page's frame
+            const frame = frameOf(event.source);
+            if (frame === undefined || frame.hasAttribute(FRAME_ASIDE_ATTRIBUTE))
                 return;
-            onFrameMessage(event.data, frameOf(event.source), {
+            onFrameMessage(event.data, frame, {
                 handlers: handlersRef.current,
                 setReplayable,
                 setClocked,
@@ -90,4 +107,3 @@ export const useFrameMessages = (handlers) => {
     }, []);
     return { replayable, clocked, heights, settled };
 };
-//# sourceMappingURL=useFrameMessages.js.map

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

@@ -14,10 +14,15 @@ import { type RefObject } from "react";
 export type FrameQueue = {
     /** The stories whose frames may be mounted. */
     readonly mounted: ReadonlySet<string>;
-    /** Registers the element that holds a story's frame, to know when it is near; `null` when it goes away. */
-    readonly observe: (storyId: string, element: HTMLElement | null) => void;
+    /**
+     * The ref of an element that holds a story's frame, to know when it is near; the same function each time, or every
+     * render would observe the element anew. A story shown twice names each place with its own `place`.
+     */
+    readonly observerOf: (storyId: string, place?: number) => (element: HTMLElement | null) => void;
     /** Records a story whose frame finished loading. */
     readonly markReady: (storyId: string) => void;
+    /** Loads every frame of the page, wherever it is, still a few at a time. */
+    readonly loadAll: () => void;
 };
 /**
  * The queue of a page's frames.
@@ -26,4 +31,3 @@ export type FrameQueue = {
  * @param root - the element that scrolls the page.
  */
 export declare const useFrameQueue: (storyIds: readonly string[], root: RefObject<HTMLElement | null>) => FrameQueue;
-//# sourceMappingURL=useFrameQueue.d.ts.map

package/dist/src/shell/useFrameQueue.js

@@ -24,19 +24,20 @@ export const useFrameQueue = (storyIds, root) => {
     const [near, setNear] = useState(new Set());
     const [ready, setReady] = useState(new Set());
     const [mounted, setMounted] = useState(new Set());
+    // the list asked for in full: another page's stories wait for their own turn again
+    const [wholeList, setWholeList] = useState(undefined);
+    const isEveryStoryNear = wholeList === storyIds;
     const observerRef = useRef(undefined);
     const elements = useRef(new Map());
+    const observers = useRef(new Map());
     useEffect(() => {
         const observer = new IntersectionObserver((entries) => setNear((current) => {
             const next = new Set(current);
             for (const entry of entries) {
-                const id = elements.current.get(entry.target);
-                if (id === undefined)
-                    continue;
                 if (entry.isIntersecting)
-                    next.add(id);
+                    next.add(entry.target);
                 else
-                    next.delete(id);
+                    next.delete(entry.target);
             }
             return next;
         }), { root: root.current, rootMargin: NEAR_MARGIN });
@@ -45,28 +46,44 @@ export const useFrameQueue = (storyIds, root) => {
         observerRef.current = observer;
         return () => observer.disconnect();
     }, [root]);
-    // a few more frames whenever a story comes near or a frame finishes loading
+    // a few more frames whenever a story comes near or a frame finishes loading; a frame the page no longer lists never
+    // finishes, and must not hold a place
     useEffect(() => {
         setMounted((current) => {
-            const loading = [...current].filter((id) => !ready.has(id)).length;
-            const waiting = storyIds.filter((id) => near.has(id) && !current.has(id));
+            const nearIds = new Set([...near].map((element) => elements.current.get(element)));
+            const loading = [...current].filter((id) => storyIds.includes(id) && !ready.has(id)).length;
+            const waiting = storyIds.filter((id) => (isEveryStoryNear || nearIds.has(id)) && !current.has(id));
             const next = waiting.slice(0, Math.max(0, MAX_LOADING - loading));
             return next.length === 0 ? current : new Set([...current, ...next]);
         });
-    }, [storyIds, near, ready]);
-    const observe = useCallback((storyId, element) => {
-        for (const [known, id] of elements.current) {
-            if (id !== storyId)
-                continue;
-            observerRef.current?.unobserve(known);
-            elements.current.delete(known);
-        }
-        if (element === null)
-            return;
-        elements.current.set(element, storyId);
-        observerRef.current?.observe(element);
+    }, [storyIds, near, ready, isEveryStoryNear]);
+    const observerOf = useCallback((storyId, place = 0) => {
+        const key = `${storyId}\n${place}`;
+        const known = observers.current.get(key);
+        if (known !== undefined)
+            return known;
+        let shown = null;
+        const observe = (element) => {
+            if (shown !== null) {
+                const gone = shown;
+                observerRef.current?.unobserve(gone);
+                elements.current.delete(gone);
+                setNear((current) => {
+                    const next = new Set(current);
+                    next.delete(gone);
+                    return next;
+                });
+            }
+            shown = element;
+            if (element === null)
+                return;
+            elements.current.set(element, storyId);
+            observerRef.current?.observe(element);
+        };
+        observers.current.set(key, observe);
+        return observe;
     }, []);
     const markReady = useCallback((storyId) => setReady((current) => (current.has(storyId) ? current : new Set(current).add(storyId))), []);
-    return { mounted, observe, markReady };
+    const loadAll = useCallback(() => setWholeList(storyIds), [storyIds]);
+    return { mounted, observerOf, markReady, loadAll };
 };
-//# sourceMappingURL=useFrameQueue.js.map

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

@@ -42,4 +42,3 @@ export type FullPage = {
 };
 /** An example's box opened to fill the page. */
 export declare const useFullPage: () => FullPage;
-//# sourceMappingURL=useFullPage.d.ts.map

package/dist/src/shell/useFullPage.js

@@ -146,4 +146,3 @@ export const useFullPage = () => {
         }
     };
 };
-//# sourceMappingURL=useFullPage.js.map

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

@@ -33,4 +33,3 @@ export declare const useLiveView: (container: RefObject<HTMLElement | null>, vie
     readonly touches: StoryTouches;
     readonly choice: TouchChoice | undefined;
 }) => void;
-//# sourceMappingURL=useLiveView.d.ts.map

package/dist/src/shell/useLiveView.js

@@ -58,4 +58,3 @@ export const useLiveView = (container, view, isEnabled, touch) => {
         tellFrames(container.current, { type: "forgebook:tools", tools: toolsOf(tools) });
     }, [container, tools]);
 };
-//# sourceMappingURL=useLiveView.js.map

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

@@ -11,10 +11,9 @@ export type Loaded<TValue> = {
     readonly message: string;
 };
 /**
- * Loads a value when its loader changes, and reads it.
+ * Loads a value when its loader changes, and reads it; on a dev server, the value follows its module's edits.
  *
  * @param load - the source's loader for the file; `undefined` when it has none.
  * @param read - turns what the loader gave into the state: the module's default export is unchecked data.
  */
 export declare const useLoaded: <TValue>(load: (() => Promise<unknown>) | undefined, read: (value: unknown) => Loaded<TValue>) => Loaded<TValue>;
-//# sourceMappingURL=useLoaded.d.ts.map

package/dist/src/shell/useLoaded.js

@@ -4,18 +4,24 @@
  *
  * @module
  */
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { RENEWED_MODULE_EVENT, successionOf } from "../hotModules.js";
 /**
- * Loads a value when its loader changes, and reads it.
+ * Loads a value when its loader changes, and reads it; on a dev server, the value follows its module's edits.
  *
  * @param load - the source's loader for the file; `undefined` when it has none.
  * @param read - turns what the loader gave into the state: the module's default export is unchecked data.
  */
 export const useLoaded = (load, read) => {
-    const [state, setState] = useState({ status: "loading" });
+    // nothing to load is known at once: a first render that said loading would hold a tab's place for nothing
+    const [state, setState] = useState(load === undefined ? { status: "none" } : { status: "loading" });
     // the reader of the first render: a reader written inline must not load the value again on every render
     const [reader] = useState(() => read);
+    // what the loader gave, which a renewed module names as the value it replaces
+    const loadedRef = useRef(undefined);
     useEffect(() => {
+        // a renewal of the value before is no longer this one's
+        loadedRef.current = undefined;
         if (load === undefined) {
             setState({ status: "none" });
             return;
@@ -24,8 +30,10 @@ export const useLoaded = (load, read) => {
         setState({ status: "loading" });
         load()
             .then((value) => {
-            if (isCurrent)
-                setState(reader(value));
+            if (!isCurrent)
+                return;
+            loadedRef.current = value;
+            setState(reader(value));
         })
             .catch((error) => {
             if (isCurrent)
@@ -35,6 +43,20 @@ export const useLoaded = (load, read) => {
             isCurrent = false;
         };
     }, [load, reader]);
+    // an edited file's docs, code or page renew in place on a dev server; a value that is no object names no module
+    useEffect(() => {
+        const follow = (event) => {
+            const succession = successionOf(event);
+            if (succession === undefined)
+                return;
+            const { previous, next } = succession;
+            if (typeof previous !== "object" || previous === null || previous !== loadedRef.current)
+                return;
+            loadedRef.current = next;
+            setState(reader(next));
+        };
+        window.addEventListener(RENEWED_MODULE_EVENT, follow);
+        return () => window.removeEventListener(RENEWED_MODULE_EVENT, follow);
+    }, [reader]);
     return state;
 };
-//# sourceMappingURL=useLoaded.js.map

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

@@ -17,4 +17,3 @@ export type PageDoc = {
  * @param load - the source's loader for the file; `undefined` when it has none.
  */
 export declare const usePageDoc: (load: (() => Promise<unknown>) | undefined) => Loaded<PageDoc>;
-//# sourceMappingURL=usePageDoc.d.ts.map

package/dist/src/shell/usePageDoc.js

@@ -18,4 +18,3 @@ const pageState = (value) => {
  * @param load - the source's loader for the file; `undefined` when it has none.
  */
 export const usePageDoc = (load) => useLoaded(load, pageState);
-//# sourceMappingURL=usePageDoc.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * The frames of a page of many stories, a component's or a docs page: which may load, the view they load with and
+ * follow, and what they report.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+import type { PanelArgs } from "../messages.ts";
+import type { TreeStory } from "../storyTree.ts";
+import { type ViewState } from "../viewState.ts";
+import { type StoryTouches, type TouchOverrides } from "./storyTouch.ts";
+import { type FrameQueue } from "./useFrameQueue.ts";
+/** What a page gives to reach its frames. */
+export type PageFramesInput = {
+    /** The page's stories, for their fingers. */
+    readonly stories: readonly TreeStory[];
+    /** What loads as it comes near, in the page's order. */
+    readonly queued: readonly string[];
+    /** The element that scrolls the page and holds its frames. */
+    readonly pageRef: RefObject<HTMLElement | null>;
+    /** The view. */
+    readonly view: ViewState;
+    /** What the user chose for each story marked for a phone. */
+    readonly touchOverrides: TouchOverrides;
+};
+/** What a page's examples read of its frames. */
+export type PageFrames = {
+    /** Which frames may load. */
+    readonly queue: FrameQueue;
+    /** The view the frames loaded with. */
+    readonly frameView: ViewState;
+    /** The stories marked for a phone, each with its own finger. */
+    readonly touches: StoryTouches;
+    /** 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>;
+    /** A story's own args, as its frame reported them; none before it loads. */
+    readonly argsOf: (storyId: string) => PanelArgs;
+};
+/**
+ * The frames of a page.
+ *
+ * @param input - the page's stories, what it queues, its scrolling element, the view and the fingers chosen.
+ */
+export declare const usePageFrames: ({ stories, queued, pageRef, view, touchOverrides }: PageFramesInput) => PageFrames;

package/dist/src/shell/usePageFrames.js

@@ -0,0 +1,50 @@
+/**
+ * The frames of a page of many stories, a component's or a docs page: which may load, the view they load with and
+ * follow, and what they report.
+ *
+ * @module
+ */
+import { useCallback, useMemo, useState } from "react";
+import { liveView } from "../viewState.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { framesOrigin } from "./framesOrigin.js";
+import { phoneStories, storyTouchesOf, touchedView } from "./storyTouch.js";
+import { useFrameMessages } from "./useFrameMessages.js";
+import { useFrameQueue } from "./useFrameQueue.js";
+import { useLiveView, useLoadedView } from "./useLiveView.js";
+/**
+ * The frames of a page.
+ *
+ * @param input - the page's stories, what it queues, its scrolling element, the view and the fingers chosen.
+ */
+export const usePageFrames = ({ stories, queued, pageRef, view, touchOverrides }) => {
+    // each story's own args, as its frame reports them: the code of a story drawn from its args is written from them
+    const [storyArgs, setStoryArgs] = useState(new Map());
+    // the frames keep the view they loaded with; only the style sheets load them again, the rest of the view (the
+    // switches, the language among them) is sent to them live
+    const frameView = useLoadedView(view.sheets, view);
+    const catalogue = useCatalogue();
+    // each story meant for a phone (marked so, or shown in a device touched with a finger) with its own finger: its frame
+    // gets it in place of the toolbar's Touch
+    const { device, orientation } = view;
+    const touches = useMemo(() => storyTouchesOf(stories, touchOverrides, phoneStories({ device, orientation }, catalogue.device)), [stories, touchOverrides, device, orientation, catalogue.device]);
+    const queue = useFrameQueue(queued, pageRef);
+    const { heights, settled } = useFrameMessages({
+        onReady: (frame, message) => {
+            queue.markReady(message.storyId);
+            setStoryArgs((current) => new Map(current).set(message.storyId, message.args));
+            const send = (shellMessage) => frame.postMessage(shellMessage, framesOrigin());
+            send({
+                type: "forgebook:view",
+                view: touchedView(liveView(view), message.storyId, touches, catalogue.touch)
+            });
+            send({ type: "forgebook:tools", tools: view.tools });
+        },
+        onCall: () => undefined,
+        // a frame that failed is over too: its place in the queue goes to the next one
+        onFailed: queue.markReady
+    });
+    useLiveView(pageRef, view, true, { touches, choice: catalogue.touch });
+    const argsOf = useCallback((storyId) => storyArgs.get(storyId) ?? {}, [storyArgs]);
+    return { queue, frameView, touches, heights, settled, argsOf };
+};

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

@@ -0,0 +1,11 @@
+import type { PanelArgs } from "../messages.ts";
+import { type DocsState } from "./useComponentDocs.ts";
+/**
+ * The panel's docs of the shown story.
+ *
+ * @param loadDocs - loads the component's docs; `undefined` when the source has none for the file.
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them; none before it did.
+ * @param actions - the args the frame records as actions.
+ */
+export declare const usePanelDocs: (loadDocs: (() => Promise<unknown>) | undefined, name: string, args: PanelArgs | undefined, actions: readonly string[]) => DocsState;

package/dist/src/shell/usePanelDocs.js

@@ -0,0 +1,29 @@
+/**
+ * The docs the story's panel reads: the component's, read from its types, or for a catalogue that reads none
+ * (`componentDocs: false`) the story's args as its props (`argsProps.ts`), once its frame reported them.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { docsOfArgs } from "../argsProps.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { useComponentDocs } from "./useComponentDocs.js";
+/** The state before a story's frame reported its args: one value, so what reads it is not renewed each render. */
+const DOCS_LOADING = { status: "loading" };
+/**
+ * The panel's docs of the shown story.
+ *
+ * @param loadDocs - loads the component's docs; `undefined` when the source has none for the file.
+ * @param name - the component's name.
+ * @param args - the story's args, as its frame reported them; none before it did.
+ * @param actions - the args the frame records as actions.
+ */
+export const usePanelDocs = (loadDocs, name, args, actions) => {
+    const { hasComponentDocs } = useCatalogue();
+    const typeDocs = useComponentDocs(loadDocs);
+    return useMemo(() => {
+        if (hasComponentDocs)
+            return typeDocs;
+        return args === undefined ? DOCS_LOADING : { status: "ready", value: docsOfArgs(name, args, actions) };
+    }, [hasComponentDocs, typeDocs, name, args, actions]);
+};

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

@@ -0,0 +1,18 @@
+import type { PluginStory } from "../plugin.ts";
+import type { TreeComponent, TreeStory } from "../storyTree.ts";
+import type { DockTab } from "./Dock.tsx";
+import type { PluginTabsInput } from "./pluginTabs.tsx";
+/**
+ * The tabs the story has something for.
+ *
+ * @param input - the plugins, the story and what it reported.
+ * @returns the tabs; none until their code is there.
+ */
+export declare const usePluginTabs: (input: PluginTabsInput) => readonly DockTab[];
+/**
+ * The story as a plugin's tab is told it, kept while the story stays.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export declare const usePluginStory: (component: TreeComponent, story: TreeStory) => PluginStory;

package/dist/src/shell/usePluginTabs.js

@@ -0,0 +1,45 @@
+/**
+ * The plugins' tabs of a story's panel, with their code loaded only by a catalogue that lists a plugin: the shell's first
+ * load holds none of it, a catalogue without one ships none of it (`pluginHostsContext.ts`), and a listed plugin's tabs
+ * come in a moment after the panel.
+ *
+ * @module
+ */
+import { useEffect, useMemo, useState } from "react";
+import { MISSING_PLUGIN_HOSTS, usePluginHosts } from "./pluginHostsContext.js";
+/**
+ * The tabs the story has something for.
+ *
+ * @param input - the plugins, the story and what it reported.
+ * @returns the tabs; none until their code is there.
+ */
+export const usePluginTabs = (input) => {
+    const [build, setBuild] = useState(undefined);
+    const loadHosts = usePluginHosts();
+    const hasPlugins = input.plugins.length > 0;
+    useEffect(() => {
+        if (!hasPlugins)
+            return;
+        if (loadHosts === undefined) {
+            window.reportError(new Error(MISSING_PLUGIN_HOSTS));
+            return;
+        }
+        void loadHosts()
+            .then((hosts) => setBuild({ tabs: hosts.tabsFor }))
+            .catch((error) => window.reportError(error));
+    }, [hasPlugins, loadHosts]);
+    return build?.tabs(input) ?? [];
+};
+/**
+ * The story as a plugin's tab is told it, kept while the story stays.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export const usePluginStory = (component, story) => useMemo(() => ({
+    id: story.id,
+    name: story.name,
+    title: component.title,
+    componentName: component.name,
+    design: story.design === undefined ? {} : { figma: story.design }
+}), [story, component]);

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

@@ -34,4 +34,3 @@ export type Popover = {
 };
 /** A button's popover. */
 export declare const usePopover: () => Popover;
-//# sourceMappingURL=usePopover.d.ts.map

package/dist/src/shell/usePopover.js

@@ -97,4 +97,3 @@ export const usePopover = () => {
     }, [isOpen]);
     return { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId };
 };
-//# sourceMappingURL=usePopover.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * The links of a page's text, opened in place: the text is plain HTML the plugin rendered, so without this a link to
+ * another page of the catalogue would reload the whole catalogue.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/**
+ * Opens the links of a page's text through the catalogue, leaving a click with a modifier to the browser.
+ *
+ * @param bodyRef - the element that holds the text.
+ * @param openLink - opens an address; `false` when it names nothing the catalogue opens, so the browser follows it.
+ */
+export declare const useProseLinks: (bodyRef: RefObject<HTMLElement | null>, openLink: (href: string) => boolean) => void;

package/dist/src/shell/useProseLinks.js

@@ -0,0 +1,30 @@
+/**
+ * The links of a page's text, opened in place: the text is plain HTML the plugin rendered, so without this a link to
+ * another page of the catalogue would reload the whole catalogue.
+ *
+ * @module
+ */
+import { useEffect } from "react";
+/**
+ * Opens the links of a page's text through the catalogue, leaving a click with a modifier to the browser.
+ *
+ * @param bodyRef - the element that holds the text.
+ * @param openLink - opens an address; `false` when it names nothing the catalogue opens, so the browser follows it.
+ */
+export const useProseLinks = (bodyRef, openLink) => {
+    useEffect(() => {
+        const body = bodyRef.current;
+        if (body === null)
+            return;
+        const follow = (event) => {
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                return;
+            const link = event.target instanceof Element ? event.target.closest(".forgebook-prose a") : null;
+            const href = link?.getAttribute("href");
+            if (href !== null && href !== undefined && openLink(href))
+                event.preventDefault();
+        };
+        body.addEventListener("click", follow);
+        return () => body.removeEventListener("click", follow);
+    }, [bodyRef, openLink]);
+};

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

@@ -1,8 +1,8 @@
-/** A page the home can list: a story's or a component's, by id. */
+/** A page the home can list: a story's, a component's or a docs page, by id. */
 export type RecentPage = {
     /** Which kind of page. */
-    readonly kind: "story" | "component";
-    /** The story's or the component's id. */
+    readonly kind: "story" | "component" | "page";
+    /** The story's, the component's or the docs page's id. */
     readonly id: string;
 };
 /**
@@ -18,4 +18,3 @@ export declare const withRecentPage: (pages: readonly RecentPage[], page: Recent
  * @param shown - the page shown now; none on the home or a missing page.
  */
 export declare const useRecentPages: (shown: RecentPage | undefined) => readonly RecentPage[];
-//# sourceMappingURL=useRecentPages.d.ts.map

package/dist/src/shell/useRecentPages.js

@@ -17,7 +17,7 @@ const MOST_RECENT = 8;
 const isRecentPage = (value) => typeof value === "object" &&
     value !== null &&
     "kind" in value &&
-    (value.kind === "story" || value.kind === "component") &&
+    (value.kind === "story" || value.kind === "component" || value.kind === "page") &&
     "id" in value &&
     typeof value.id === "string";
 /** The stored pages, or none when the text holds none (another format, a damaged value). */
@@ -59,4 +59,3 @@ export const useRecentPages = (shown) => {
     }, [kind, id, pages, setPages]);
     return pages;
 };
-//# sourceMappingURL=useRecentPages.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * The reader's "Required first" switch, kept in this browser for the whole catalogue, and the layout of the required
+ * props it leaves for a component or a story (`requiredFirstLayout`).
+ *
+ * @remarks
+ * Stored as `useStored` stores a reader's preference (under the catalogue's id), but shared live by every table that
+ * shows it: a docs page may hold several API references, and turning the switch in one turns it in all. Storage may
+ * be refused (a private window): the switch then holds for the page only, and nothing fails.
+ *
+ * @module
+ */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
+/** Where the required props go, and the reader's switch over it. */
+export type RequiredFirstState = {
+    /** The layout to draw. */
+    readonly layout: RequiredFirst;
+    /** Whether the switch shows on: the layout puts the required props first. */
+    readonly isOn: boolean;
+    /** Turns the switch, for every component, and keeps it in this browser. */
+    readonly setIsOn: (isOn: boolean) => void;
+};
+/**
+ * Where a component's or a story's required props go for this reader.
+ *
+ * @param own - the story's or the component's own setting (`parameters.requiredFirst`); none for the catalogue's.
+ */
+export declare const useRequiredFirst: (own: RequiredFirst | undefined) => RequiredFirstState;