forgebook 0.3.3 → 0.4.1

package/dist/src/shell/useAddressArgs.js

@@ -9,8 +9,8 @@
  *
  * @module
  */
-import { useEffect, useMemo, useRef } from "react";
-import { checkedAddressArgs, checkedArgsMessage } from "../addressArgs.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { checkedAddressArgs, checkedArgsMessage, declaredArgProps, needsShapeChecks } from "../addressArgs.js";
 import { panelArgsParam } from "../messages.js";
 import { tellFrames } from "./FrameView.js";
 /**
@@ -38,19 +38,57 @@ const NO_ARGS = {};
 const NOTHING_DROPPED = [];
 /** A source without named values. */
 const NO_NAMED_VALUES = {};
+/** No custom control registered. */
+const NO_ARG_CONTROLS = {};
+/**
+ * What checks a story's structured values, loaded when a story first has a prop that needs it. Until it arrives such a
+ * prop's value waits, whichever its story.
+ *
+ * @param declaration - what the story declares.
+ * @param loaders - the catalogue's custom controls.
+ */
+const useArgChecks = (declaration, loaders) => {
+    const props = declaration === undefined ? [] : declaredArgProps(declaration);
+    const names = props.flatMap((prop) => prop.customControl ?? []).join("\n");
+    const isNeeded = props.some(needsShapeChecks);
+    const [loaded, setLoaded] = useState();
+    useEffect(() => {
+        if (!isNeeded)
+            return;
+        let isCurrent = true;
+        void import("./argChecks.js")
+            .then(({ loadedChecks }) => loadedChecks(names === "" ? [] : names.split("\n"), loaders ?? NO_ARG_CONTROLS))
+            .then((checks) => {
+            if (isCurrent)
+                setLoaded({ names, checks });
+        });
+        return () => {
+            isCurrent = false;
+        };
+    }, [isNeeded, names, loaders]);
+    return loaded?.names === names ? loaded.checks : undefined;
+};
 /**
  * The address's values, checked against what the story declares.
  *
  * @param input - the address's values and what the stage knows of the story.
  */
 export const useAddressArgs = (input) => {
-    const { panelArgs, docs, storyArgs, argTypes, controls, frames } = input;
+    const { panelArgs, link, docs, storyArgs, argTypes, controls, frames } = input;
+    const typeValue = link?.typeValue;
     const namedValues = input.namedValues ?? NO_NAMED_VALUES;
-    const checked = useMemo(() => {
+    const declaration = useMemo(() => {
         const ready = storyArgs === undefined ? undefined : { args: storyArgs, argTypes, controls };
-        const declaration = declarationOf(docs, ready, namedValues);
-        return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration);
-    }, [panelArgs, docs, storyArgs, argTypes, controls, namedValues]);
+        return declarationOf(docs, ready, namedValues);
+    }, [docs, storyArgs, argTypes, controls, namedValues]);
+    const checks = useArgChecks(declaration, input.argControls);
+    const checked = useMemo(() => {
+        if (declaration === undefined)
+            return undefined;
+        const read = checkedAddressArgs(panelArgs, declaration, typeValue, checks);
+        // nothing is told of the address until all of it can be: a story must not draw half a link
+        return read.isWaiting ? undefined : read;
+    }, [panelArgs, typeValue, declaration, checks]);
     const acceptedParam = checked === undefined ? undefined : panelArgsParam(checked.accepted);
     // the values reach the frames from the address, so going back in the history sets them too; compared as text, so a
     // frame is told again only when they change
@@ -61,14 +99,21 @@ export const useAddressArgs = (input) => {
             return;
         tellFrames(frames.current, checkedArgsMessage(sealedRef.current));
     }, [acceptedParam, frames]);
+    // said with the check's: the note's button keeps what the story accepts, which is not known before
+    const unread = (link?.unread ?? []).map((name) => ({ name, reason: "unreadable" }));
+    const refused = (link?.refused ?? []).map((name) => ({ name, reason: "markup" }));
     return {
         accepted: checked?.accepted ?? NO_ARGS,
         checked: checked?.sealed,
-        dropped: checked?.dropped ?? NOTHING_DROPPED,
+        dropped: checked === undefined ? NOTHING_DROPPED : [...unread, ...refused, ...checked.dropped],
         acceptedParam,
         acceptedFor: (message) => {
-            const declaration = declarationOf(docs, message, namedValues);
-            return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration).sealed;
-        }
+            const ready = declarationOf(docs, message, namedValues);
+            if (ready === undefined)
+                return undefined;
+            const read = checkedAddressArgs(panelArgs, ready, typeValue, checks);
+            return read.isWaiting ? undefined : read.sealed;
+        },
+        worstOfShape: checks?.worstOfShape
     };
 };

package/dist/src/shell/useControlKeys.js

@@ -8,7 +8,7 @@ import { useEffect, useRef } from "react";
 import { pressedControl } from "../controlKeys.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { cycledView } from "./controlCycle.js";
-import { isTyping } from "./keyboard.js";
+import { isSingleKeyFree } from "./keyboard.js";
 /**
  * Listens to the controls' keys.
  *
@@ -21,7 +21,7 @@ export const useControlKeys = (input) => {
     latest.current = input;
     useEffect(() => {
         const cycle = (event) => {
-            if (isTyping(event.target))
+            if (!isSingleKeyFree(event))
                 return;
             const { keys, view, onViewChange, fixed, isStoryPage, isComponentPage } = latest.current;
             const pressed = pressedControl(keys, {

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

@@ -0,0 +1,6 @@
+/**
+ * The problems to show.
+ *
+ * @param problems - the index's problems, as the page read them.
+ */
+export declare const useEditedProblems: (problems: readonly string[]) => readonly string[];

package/dist/src/shell/useEditedProblems.js

@@ -0,0 +1,40 @@
+/**
+ * The index's problems as a dev server's edits leave them: a story file that an edit left unreadable, or a component
+ * that no longer parses, is named at once, without a reload that would take its story away from the reader, and no
+ * longer once a later edit fixed it.
+ *
+ * @module
+ */
+import { useEffect, useMemo, useState } from "react";
+import { STORY_FILE_READ_EVENT, storyFileReadOf } from "../hotModules.js";
+/** No file an edit told of. */
+const NONE = new Map();
+/**
+ * The problems to show.
+ *
+ * @param problems - the index's problems, as the page read them.
+ */
+export const useEditedProblems = (problems) => {
+    const [edited, setEdited] = useState(NONE);
+    useEffect(() => {
+        // a build has no edits
+        if (import.meta.hot === undefined)
+            return undefined;
+        const follow = (event) => {
+            const read = storyFileReadOf(event);
+            if (read === undefined)
+                return;
+            setEdited((before) => {
+                // a fix is kept too: it takes away what the page read of the file (a component that did not parse)
+                return new Map(before).set(read.file, read.problem);
+            });
+        };
+        window.addEventListener(STORY_FILE_READ_EVENT, follow);
+        return () => window.removeEventListener(STORY_FILE_READ_EVENT, follow);
+    }, []);
+    // an edit's word on a file replaces what the page read of it: the problem names its file first
+    return useMemo(() => {
+        const kept = problems.filter((problem) => ![...edited.keys()].some((file) => problem.startsWith(file)));
+        return [...kept, ...[...edited.values()].filter((problem) => problem !== undefined)];
+    }, [problems, edited]);
+};

package/dist/src/shell/useFrameMessages.js

@@ -38,6 +38,9 @@ const onFrameMessage = (message, frame, targets) => {
             if (address !== undefined)
                 targets.setHeight(address, message.height);
             return;
+        case "forgebook:scheme":
+            frame.style.colorScheme = message.scheme;
+            return;
         case "forgebook:error":
             handlers.onFailed?.(message.storyId, message.message);
             return;

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

@@ -1,12 +1,17 @@
 /**
- * Which frames of a page of many stories may load: those near the visible part of the page, a few at a time, so the
- * browser is never asked for thousands of modules at once.
+ * Which frames of a page of many stories may load: those near the visible part of the page, nearest first, a few at a
+ * time, so the browser is never asked for thousands of modules at once.
  *
  * @remarks
  * In development every frame loads its sources' modules one by one (a few hundred requests); twenty frames at once
  * exhaust the browser ("insufficient resources") and stories stay blank. A frame loads once its story is near the
  * visible part of the scrolling page and fewer than `MAX_LOADING` frames are still loading; once loaded it stays.
  *
+ * The reader may be anywhere on the page, so a free place goes to the waiting story nearest the visible part, not to
+ * the first one in the page's order (`frameOrder.ts`); and no frame starts while the page scrolls fast
+ * (`useScrollSettled.ts`), so the stories a scroll flies past never hold a place the stories where it stops need. A
+ * frame already loading finishes wherever the page goes.
+ *
  * @module
  */
 import { type RefObject } from "react";
@@ -21,7 +26,7 @@ export type FrameQueue = {
     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. */
+    /** Loads every frame of the page, wherever it is, still a few at a time and nearest first. */
     readonly loadAll: () => void;
 };
 /**

package/dist/src/shell/useFrameQueue.js

@@ -1,19 +1,44 @@
 /**
- * Which frames of a page of many stories may load: those near the visible part of the page, a few at a time, so the
- * browser is never asked for thousands of modules at once.
+ * Which frames of a page of many stories may load: those near the visible part of the page, nearest first, a few at a
+ * time, so the browser is never asked for thousands of modules at once.
  *
  * @remarks
  * In development every frame loads its sources' modules one by one (a few hundred requests); twenty frames at once
  * exhaust the browser ("insufficient resources") and stories stay blank. A frame loads once its story is near the
  * visible part of the scrolling page and fewer than `MAX_LOADING` frames are still loading; once loaded it stays.
  *
+ * The reader may be anywhere on the page, so a free place goes to the waiting story nearest the visible part, not to
+ * the first one in the page's order (`frameOrder.ts`); and no frame starts while the page scrolls fast
+ * (`useScrollSettled.ts`), so the stories a scroll flies past never hold a place the stories where it stops need. A
+ * frame already loading finishes wherever the page goes.
+ *
  * @module
  */
 import { useCallback, useEffect, useRef, useState } from "react";
+import { distanceFromView, nearestFrames } from "./frameOrder.js";
+import { useScrollSettled } from "./useScrollSettled.js";
 /** The most frames loading at once. */
 const MAX_LOADING = 2;
 /** How far beyond the visible part a story counts as near, as an IntersectionObserver margin. */
 const NEAR_MARGIN = "600px 0px";
+/**
+ * How far each waiting story is from the visible part of the page: its nearest place, for a story shown twice.
+ *
+ * @param waiting - the stories waiting for their frame.
+ * @param elements - the elements that hold the page's frames, with their story.
+ * @param root - the element that scrolls the page; the window when there is none.
+ */
+const distancesOf = (waiting, elements, root) => {
+    const view = root?.getBoundingClientRect() ?? { top: 0, bottom: window.innerHeight };
+    const distances = new Map();
+    for (const [element, storyId] of elements) {
+        if (!waiting.has(storyId))
+            continue;
+        const distance = distanceFromView(element.getBoundingClientRect(), view);
+        distances.set(storyId, Math.min(distance, distances.get(storyId) ?? distance));
+    }
+    return distances;
+};
 /**
  * The queue of a page's frames.
  *
@@ -30,6 +55,7 @@ export const useFrameQueue = (storyIds, root) => {
     const observerRef = useRef(undefined);
     const elements = useRef(new Map());
     const observers = useRef(new Map());
+    const isSettled = useScrollSettled(root);
     useEffect(() => {
         const observer = new IntersectionObserver((entries) => setNear((current) => {
             const next = new Set(current);
@@ -46,17 +72,21 @@ 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 frame the page no longer lists never
-    // finishes, and must not hold a place
+    // a few more frames whenever a story comes near, a frame finishes loading or the page stops flying; a frame the page
+    // no longer lists never finishes, and must not hold a place
     useEffect(() => {
-        setMounted((current) => {
-            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, isEveryStoryNear]);
+        if (!isSettled)
+            return;
+        const free = MAX_LOADING - [...mounted].filter((id) => storyIds.includes(id) && !ready.has(id)).length;
+        if (free <= 0)
+            return;
+        const nearIds = new Set([...near].map((element) => elements.current.get(element)));
+        const waiting = storyIds.filter((id) => (isEveryStoryNear || nearIds.has(id)) && !mounted.has(id));
+        if (waiting.length === 0)
+            return;
+        const next = nearestFrames(waiting, distancesOf(new Set(waiting), elements.current, root.current), free);
+        setMounted(new Set([...mounted, ...next]));
+    }, [storyIds, near, ready, isEveryStoryNear, isSettled, mounted, root]);
     const observerOf = useCallback((storyId, place = 0) => {
         const key = `${storyId}\n${place}`;
         const known = observers.current.get(key);

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

@@ -0,0 +1,13 @@
+import type { taggedTree } from "../storyTags.ts";
+import type { StoryTree } from "../storyTree.ts";
+/** The filter, set by the tag filter's button, which loads its code: read during a render, never waited for. */
+export declare const loadedTagFilter: {
+    current?: typeof taggedTree;
+};
+/**
+ * The tree to list.
+ *
+ * @param tree - the whole tree.
+ * @param tags - the address's tags; none lists the whole tree.
+ */
+export declare const useListedTree: (tree: StoryTree, tags: readonly string[]) => StoryTree;

package/dist/src/shell/useListedTree.js

@@ -0,0 +1,32 @@
+/**
+ * The tree the sidebar and the story keys list: the whole one, or what the address's tags keep of it.
+ *
+ * @remarks
+ * The filter's code loads only when an address names a tag, or with the tag filter's button, which hands it over
+ * (`loadedTagFilter`) so the render that puts a checked tag in the address is already filtered. A catalogue nobody
+ * filters pays for a question and not for its answer. Opened on an address that names a tag, the whole tree shows
+ * until the code arrives, as the search's tree does before its list comes.
+ *
+ * @module
+ */
+import { useEffect, useMemo, useState } from "react";
+/** The filter, set by the tag filter's button, which loads its code: read during a render, never waited for. */
+export const loadedTagFilter = {};
+/**
+ * The tree to list.
+ *
+ * @param tree - the whole tree.
+ * @param tags - the address's tags; none lists the whole tree.
+ */
+export const useListedTree = (tree, tags) => {
+    const [filter, setFilter] = useState();
+    const isFiltered = tags.length > 0;
+    useEffect(() => {
+        if (isFiltered)
+            void import("../storyTags.js").then((module) => setFilter(() => module.taggedTree));
+    }, [isFiltered]);
+    return useMemo(() => {
+        const loaded = filter ?? loadedTagFilter.current;
+        return isFiltered && loaded !== undefined ? loaded(tree, tags) : tree;
+    }, [filter, isFiltered, tree, tags]);
+};

package/dist/src/shell/usePageFrames.js

@@ -20,9 +20,9 @@ import { useLiveView, useLoadedView } from "./useLiveView.js";
 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
+    // the frames keep the view they loaded with; only the style sheets and the play switch 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 frameView = useLoadedView(`${view.sheets}|${view.play}`, 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

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

@@ -25,6 +25,11 @@ export type Popover = {
     readonly setIsOpen: (isOpen: boolean, press?: {
         readonly detail: number;
     }) => void;
+    /**
+     * Closes the panel after a choice in it was taken by the pointer. The arrow keys choose as they move: a panel that
+     * closed on the first would keep every choice past the next one out of reach, so with the keys Escape closes it.
+     */
+    readonly closeAfterChoice: () => void;
     /** The button. */
     readonly buttonRef: RefObject<HTMLButtonElement | null>;
     /** The panel. */

package/dist/src/shell/usePopover.js

@@ -27,6 +27,7 @@ export const usePopover = () => {
     const panelRef = useRef(null);
     const closing = useRef(undefined);
     const isByPointer = useRef(false);
+    const isLastInputKey = useRef(false);
     const panelId = useId();
     const setIsOpen = (isOpening, press) => {
         const panel = panelRef.current;
@@ -60,6 +61,10 @@ export const usePopover = () => {
             // a cancelled closing (opened again) leaves the panel open
             .catch(() => undefined);
     };
+    const closeAfterChoice = () => {
+        if (!isLastInputKey.current)
+            setIsOpen(false);
+    };
     // it grows in from its button's corner as it is drawn
     useLayoutEffect(() => {
         const panel = panelRef.current;
@@ -76,6 +81,7 @@ export const usePopover = () => {
             return;
         panelRef.current?.querySelector("input:checked")?.focus();
         const close = (event) => {
+            isLastInputKey.current = event instanceof KeyboardEvent;
             const target = event.target instanceof Node ? event.target : null;
             const isOutside = event instanceof PointerEvent &&
                 !panelRef.current?.contains(target) &&
@@ -95,5 +101,5 @@ export const usePopover = () => {
             document.removeEventListener("keydown", close);
         };
     }, [isOpen]);
-    return { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId };
+    return { isOpen, isDrawn, setIsOpen, closeAfterChoice, buttonRef, panelRef, panelId };
 };

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

@@ -0,0 +1,22 @@
+import type { CatalogueRef, RefIndex } from "../catalogueRefs.ts";
+/** A composed catalogue's index: loading, read, or why it could not be. */
+export type RefIndexState = {
+    readonly status: "loading";
+} | {
+    readonly status: "ready";
+    readonly index: RefIndex;
+} | {
+    readonly status: "error";
+    readonly message: string;
+};
+/**
+ * A composed catalogue's index, fetched once it is wanted (its section open, one of its stories shown).
+ *
+ * @remarks
+ * What a load ended with is kept with the address it was for, so another catalogue's index never stands in for this
+ * one's while its own loads: two catalogues built from one library share story ids.
+ *
+ * @param ref - the composed catalogue; none when there is none to read.
+ * @param isWanted - whether it is wanted yet.
+ */
+export declare const useRefIndex: (ref: CatalogueRef | undefined, isWanted: boolean) => RefIndexState;

package/dist/src/shell/useRefIndex.js

@@ -0,0 +1,36 @@
+/**
+ * A composed catalogue's index as a state the shell can show: loading, read, or why it failed.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+import { loadRefIndex } from "./refIndexLoad.js";
+/** Before any load ended. */
+const LOADING = { status: "loading" };
+/**
+ * A composed catalogue's index, fetched once it is wanted (its section open, one of its stories shown).
+ *
+ * @remarks
+ * What a load ended with is kept with the address it was for, so another catalogue's index never stands in for this
+ * one's while its own loads: two catalogues built from one library share story ids.
+ *
+ * @param ref - the composed catalogue; none when there is none to read.
+ * @param isWanted - whether it is wanted yet.
+ */
+export const useRefIndex = (ref, isWanted) => {
+    const [settled, setSettled] = useState(undefined);
+    useEffect(() => {
+        if (ref === undefined || !isWanted)
+            return;
+        let isCurrent = true;
+        const settle = (state) => {
+            if (isCurrent)
+                setSettled({ url: ref.url, state });
+        };
+        loadRefIndex(ref).then((index) => settle({ status: "ready", index }), (error) => settle({ status: "error", message: error instanceof Error ? error.message : String(error) }));
+        return () => {
+            isCurrent = false;
+        };
+    }, [ref, isWanted]);
+    return settled !== undefined && settled.url === ref?.url ? settled.state : LOADING;
+};

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

@@ -0,0 +1,18 @@
+/**
+ * Whether a scrolling page has stopped flying past its content, for the frame queue (`useFrameQueue`).
+ *
+ * @remarks
+ * A fast scroll to the end of a long page passes over stories the reader never looks at: a frame started for one of
+ * them takes a loading place from the stories where the scroll stops. The page counts as unsettled while it scrolls
+ * faster than `FAST_SCROLL`, and settles `SETTLE_MS` after its last fast step; a slow scroll, a reader's, stays
+ * settled, so stories keep loading as they come near.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/**
+ * Whether the page is settled: true unless it scrolled fast in the last `SETTLE_MS`.
+ *
+ * @param root - the element that scrolls the page; the hook reads nothing when it is not there.
+ */
+export declare const useScrollSettled: (root: RefObject<HTMLElement | null>) => boolean;

package/dist/src/shell/useScrollSettled.js

@@ -0,0 +1,56 @@
+/**
+ * Whether a scrolling page has stopped flying past its content, for the frame queue (`useFrameQueue`).
+ *
+ * @remarks
+ * A fast scroll to the end of a long page passes over stories the reader never looks at: a frame started for one of
+ * them takes a loading place from the stories where the scroll stops. The page counts as unsettled while it scrolls
+ * faster than `FAST_SCROLL`, and settles `SETTLE_MS` after its last fast step; a slow scroll, a reader's, stays
+ * settled, so stories keep loading as they come near.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+/** The scroll speed above which the page flies past its stories, in CSS px per millisecond: 2000 px a second. */
+const FAST_SCROLL = 2;
+/** How long after its last fast step the page counts as settled, in milliseconds. */
+const SETTLE_MS = 150;
+/**
+ * The longest time read between two scroll events, in milliseconds: a jump after a pause (the End key, a link to a
+ * story further down) counts as fast, not as a long slow step.
+ */
+const LONGEST_STEP_MS = 100;
+/**
+ * Whether the page is settled: true unless it scrolled fast in the last `SETTLE_MS`.
+ *
+ * @param root - the element that scrolls the page; the hook reads nothing when it is not there.
+ */
+export const useScrollSettled = (root) => {
+    const [isSettled, setIsSettled] = useState(true);
+    useEffect(() => {
+        const element = root.current;
+        if (element === null)
+            return undefined;
+        let lastTop = element.scrollTop;
+        let lastTime = performance.now();
+        let timer;
+        const onScroll = () => {
+            const now = performance.now();
+            const step = Math.min(Math.max(now - lastTime, 1), LONGEST_STEP_MS);
+            const speed = Math.abs(element.scrollTop - lastTop) / step;
+            lastTop = element.scrollTop;
+            lastTime = now;
+            if (speed <= FAST_SCROLL)
+                return;
+            setIsSettled(false);
+            clearTimeout(timer);
+            timer = setTimeout(() => setIsSettled(true), SETTLE_MS);
+        };
+        element.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+            element.removeEventListener("scroll", onScroll);
+            clearTimeout(timer);
+            setIsSettled(true);
+        };
+    }, [root]);
+    return isSettled;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Tab stops for what scrolls sideways: a part with nothing of its own to focus can only be scrolled by a keyboard from a
+ * stop on the part itself.
+ *
+ * @remarks
+ * A part takes a stop only while it overflows: on a wide window, where a code block or a props table fits, a stop would
+ * be one more press on the way through the page with nothing to do there. The parts are read again whenever the root
+ * changes size: the window narrowed, a fold opened, the fonts arrived.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+/**
+ * Gives the parts of an element that overflow sideways a Tab stop, and takes it back when they fit.
+ *
+ * @param selector - the parts, inside the element; the element itself when absent.
+ * @param content - what the parts are drawn from, when it can change with no change of the element's size.
+ * @returns the ref for the element.
+ */
+export declare const useScrollStops: (selector?: string, content?: string) => RefObject<HTMLDivElement | null>;

package/dist/src/shell/useScrollStops.js

@@ -0,0 +1,41 @@
+/**
+ * Tab stops for what scrolls sideways: a part with nothing of its own to focus can only be scrolled by a keyboard from a
+ * stop on the part itself.
+ *
+ * @remarks
+ * A part takes a stop only while it overflows: on a wide window, where a code block or a props table fits, a stop would
+ * be one more press on the way through the page with nothing to do there. The parts are read again whenever the root
+ * changes size: the window narrowed, a fold opened, the fonts arrived.
+ *
+ * @module
+ */
+import { useEffect, useRef } from "react";
+/**
+ * Gives the parts of an element that overflow sideways a Tab stop, and takes it back when they fit.
+ *
+ * @param selector - the parts, inside the element; the element itself when absent.
+ * @param content - what the parts are drawn from, when it can change with no change of the element's size.
+ * @returns the ref for the element.
+ */
+export const useScrollStops = (selector, content) => {
+    const rootRef = useRef(null);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `content` replaces the parts, whose stops go with them
+    useEffect(() => {
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        const update = () => {
+            const parts = selector === undefined ? [root] : root.querySelectorAll(selector);
+            for (const part of parts) {
+                if (part.scrollWidth > part.clientWidth)
+                    part.tabIndex = 0;
+                else
+                    part.removeAttribute("tabindex");
+            }
+        };
+        const observer = new ResizeObserver(update);
+        observer.observe(root);
+        return () => observer.disconnect();
+    }, [selector, content]);
+    return rootRef;
+};

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

@@ -0,0 +1,18 @@
+/**
+ * The list of the shell's keys: `?` opens it anywhere the shell's keys work, or the menu at the sidebar's foot.
+ *
+ * @remarks
+ * Only the key and whether it is open sit in the first load; the list comes with its first opening.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+/** What the shell wires to the list. */
+export type ShortcutHelp = {
+    /** The list, while it is open. */
+    readonly help: ReactNode;
+    /** Opens it. */
+    readonly showHelp: () => void;
+};
+/** Listens to the key that opens the list, and holds whether it is open. */
+export declare const useShortcutHelp: () => ShortcutHelp;

package/dist/src/shell/useShortcutHelp.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The list of the shell's keys: `?` opens it anywhere the shell's keys work, or the menu at the sidebar's foot.
+ *
+ * @remarks
+ * Only the key and whether it is open sit in the first load; the list comes with its first opening.
+ *
+ * @module
+ */
+import { useEffect, useState } from "react";
+import { isSingleKeyFree } from "./keyboard.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
+/** The list, loaded when first opened. */
+const SHORTCUT_HELP = lazyModule(() => import("./ShortcutHelp.js").then((module) => module.ShortcutHelp));
+/** Listens to the key that opens the list, and holds whether it is open. */
+export const useShortcutHelp = () => {
+    const [isOpen, setIsOpen] = useState(false);
+    useEffect(() => {
+        const open = (event) => {
+            if (event.key !== "?" || event.metaKey || event.ctrlKey || event.altKey || !isSingleKeyFree(event))
+                return;
+            event.preventDefault();
+            setIsOpen(true);
+        };
+        document.addEventListener("keydown", open);
+        return () => document.removeEventListener("keydown", open);
+    }, []);
+    return {
+        help: isOpen ? (_jsx(LazyView, { module: SHORTCUT_HELP, props: { onClose: () => setIsOpen(false) }, loading: null, failed: () => null })) : null,
+        showHelp: () => setIsOpen(true)
+    };
+};