forgebook 0.3.2 → 0.4.0

package/dist/src/shell/useAddressArgs.js

@@ -1,6 +1,6 @@
 /**
- * The props panel's values an address names, as the stage hands them to the story's frames: only those the story
- * declares, with a value of the declared type, once the story's frame and its component's docs say what that is.
+ * The props panel's values an address names, as a page hands them to the story's frames: only those the story declares,
+ * with a value of the declared type, once the story's frame and its component's docs say what that is.
  *
  * @remarks
  * The address is written by whoever shares the link, so its values are checked here, in the core, before any frame
@@ -9,9 +9,10 @@
  *
  * @module
  */
-import { useMemo } from "react";
-import { checkedAddressArgs } 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";
 /**
  * What a story declares, once both its frame and its docs answered.
  *
@@ -37,26 +38,82 @@ 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 } = 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
+    const sealedRef = useRef(checked?.sealed);
+    sealedRef.current = checked?.sealed;
+    useEffect(() => {
+        if (acceptedParam === undefined || sealedRef.current === undefined)
+            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,
-        dropped: checked?.dropped ?? NOTHING_DROPPED,
-        acceptedParam: checked === undefined ? undefined : panelArgsParam(checked.accepted),
+        checked: checked?.sealed,
+        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).accepted;
-        }
+            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/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/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)
+    };
+};

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

@@ -1,6 +1,7 @@
 /**
  * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
  * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ * Beside the page, on a wide window, the focus only follows the button it stood on, which goes away with the press.
  *
  * @module
  */
@@ -26,7 +27,7 @@ export type SidebarOverlayState = {
     readonly onClose: () => void;
 };
 /**
- * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ * Wires a sidebar lying over the page, and the focus of one beside it on a wide window.
  *
  * @param state - the sidebar's state.
  * @returns whether it lies over the page, and the references to give the sidebar and its buttons.

package/dist/src/shell/useSidebarOverlay.js

@@ -1,12 +1,13 @@
 /**
  * What a sidebar lying over the page does beyond its look: Escape closes it, the focus moves into it as it opens and back
  * to the button that shows it as it closes. The page behind is made inert by the shell, and a tap on the shade closes it.
+ * Beside the page, on a wide window, the focus only follows the button it stood on, which goes away with the press.
  *
  * @module
  */
 import { useEffect, useRef } from "react";
 /**
- * Wires a sidebar lying over the page; nothing on a wide window, where the sidebar sits beside it.
+ * Wires a sidebar lying over the page, and the focus of one beside it on a wide window.
  *
  * @param state - the sidebar's state.
  * @returns whether it lies over the page, and the references to give the sidebar and its buttons.
@@ -32,20 +33,27 @@ export const useSidebarOverlay = ({ isOverlay, isOpen, onClose }) => {
         return () => document.removeEventListener("keydown", closeOnEscape);
     }, [isOver, onClose]);
     const wasOver = useRef(false);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: also looked at when the window crosses the width, and never when a wide window's sidebar is hidden, which leaves the focus alone
+    const wasOpen = useRef(isOpen);
+    // also looked at when the window crosses the width
     useEffect(() => {
         const focused = document.activeElement;
         const isFocusInSidebar = sidebarRef.current?.contains(focused) === true;
+        const isFocusNowhere = focused === document.body || focused === null;
         // the platform's search key has already put the focus on the search field
         if (isOver && !isFocusInSidebar)
             hideButtonRef.current?.focus({ preventScroll: true });
+        // shown beside the page, the sidebar took away the button that showed it, and Tab would start over from the top
+        if (isOpen && !wasOpen.current && !isOverlay && isFocusNowhere) {
+            hideButtonRef.current?.focus({ preventScroll: true });
+        }
         // the sidebar went away with the focus in it, closed or by the window crossing the width; one still shown keeps the
         // focus, and a search's result that has already taken it to what it found keeps it too
-        const isFocusLost = isFocusInSidebar || (wasOver.current && (focused === document.body || focused === null));
+        const isFocusLost = isFocusInSidebar || (wasOver.current && isFocusNowhere);
         if (!isOver && sidebarRef.current?.inert === true && isFocusLost) {
             showButtonRef.current?.focus({ preventScroll: true });
         }
         wasOver.current = isOver;
-    }, [isOver, isOverlay]);
+        wasOpen.current = isOpen;
+    }, [isOver, isOverlay, isOpen]);
     return { isOver, sidebarRef, hideButtonRef, showButtonRef };
 };

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

@@ -1,5 +1,6 @@
 /**
- * A story file's code for the Code card: each story's `render` as written, loaded from the source's `code`.
+ * A story file's code for the Code card: each story's `render`, or the args it writes as code, as written, loaded from
+ * the source's `code`.
  *
  * @module
  */

package/dist/src/shell/useStoryCode.js

@@ -1,12 +1,17 @@
 import { useLoaded } from "./useLoaded.js";
-/** Whether a value is one story's code: its text and its HTML. */
-const isStoryCode = (value) => typeof value === "object" &&
+/** Whether a value is a record of texts, as a story's written args are. */
+const isTexts = (value) => typeof value === "object" &&
     value !== null &&
-    "text" in value &&
-    typeof value.text === "string" &&
-    "html" in value &&
-    typeof value.html === "string";
-/** Whether the plugin's answer is a file's code: each story's text and HTML, by export name. */
+    Object.values(value).every((each) => typeof each === "string");
+/** Whether a value is one story's code: its render's text and HTML, or the args it writes as code. */
+const isStoryCode = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if ("args" in value)
+        return isTexts(value.args);
+    return ("text" in value && typeof value.text === "string" && "html" in value && typeof value.html === "string");
+};
+/** Whether the plugin's answer is a file's code: each story's, by export name. */
 const isStoryFileCode = (value) => typeof value === "object" &&
     value !== null &&
     !("error" in value) &&

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

@@ -5,7 +5,7 @@
  *
  * @module
  */
-import { type ControlKeys } from "../controlKeys.ts";
+import { type ControlKeys, type ReaderKeys } from "../controlKeys.ts";
 import { type PlacedControl } from "../toolbarLayout.ts";
 /** The arrangement and what changes it. */
 export type ToolbarLayout = {
@@ -34,5 +34,9 @@ export type ToolbarLayout = {
      */
     readonly setKey: (id: string, key: string | null) => string | undefined;
 };
+/** The person's keys a stored text holds; none for anything else. */
+export declare const readKeys: (stored: string | null) => ReaderKeys;
+/** The text the person's keys are stored as; empty for none. */
+export declare const keysText: (keys: ReaderKeys) => string;
 /** The person's arrangement of the toolbar. */
 export declare const useToolbarLayout: () => ToolbarLayout;

package/dist/src/shell/useToolbarLayout.js

@@ -10,7 +10,7 @@ import { arrangementOf, arrangementText, placedControls, readArrangement, withHi
 import { useCatalogue } from "./catalogueContext.js";
 import { useStored } from "./useStored.js";
 /** The person's keys a stored text holds; none for anything else. */
-const readKeys = (stored) => {
+export const readKeys = (stored) => {
     if (stored === null || stored === "")
         return {};
     try {
@@ -24,7 +24,7 @@ const readKeys = (stored) => {
     }
 };
 /** The text the person's keys are stored as; empty for none. */
-const keysText = (keys) => (Object.keys(keys).length === 0 ? "" : JSON.stringify(keys));
+export const keysText = (keys) => Object.keys(keys).length === 0 ? "" : JSON.stringify(keys);
 /** The person's arrangement of the toolbar. */
 export const useToolbarLayout = () => {
     const catalogue = useCatalogue();

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

@@ -11,7 +11,9 @@
  */
 import { type RefObject } from "react";
 import type { PanelProp } from "../argTypes.ts";
-import type { PanelArgs } from "../messages.ts";
+import type { ArgValue, PanelArgs } from "../messages.ts";
+import type { NamedValues } from "../namedValues.ts";
+import type { ValueShape } from "../valueShape.ts";
 import { type WorstCaseState } from "./worstArgs.ts";
 /** What the hook reads. */
 export type WorstCaseInput = {
@@ -25,6 +27,10 @@ export type WorstCaseInput = {
     readonly values: PanelArgs;
     /** The panel's own values. */
     readonly panelArgs: PanelArgs;
+    /** The source's named values, for a required part only they can fill. */
+    readonly namedValues: NamedValues | undefined;
+    /** Gives a prop with a shape its worst value, once its module loaded. */
+    readonly worstOfShape: ((shape: ValueShape, namedValues: NamedValues) => ArgValue | undefined) | undefined;
     /** Sets the panel's values. */
     readonly onPanelArgsChange: (args: PanelArgs) => void;
 };
@@ -42,4 +48,4 @@ export type WorstCase = {
  *
  * @param input - the frames, the story, its settable props and its values.
  */
-export declare const useWorstCase: ({ storyRef, storyId, settable, values, panelArgs, onPanelArgsChange }: WorstCaseInput) => WorstCase;
+export declare const useWorstCase: ({ storyRef, storyId, settable, values, panelArgs, namedValues, worstOfShape, onPanelArgsChange }: WorstCaseInput) => WorstCase;