forgebook 0.1.8 → 0.2.0

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

@@ -0,0 +1,31 @@
+/**
+ * What the panel's row of tabs shows of a tab before its content is drawn: its hint, and whether it has anything to
+ * show.
+ *
+ * @remarks
+ * Apart from the tabs themselves, whose modules load the first time each is chosen (`dockTabs`): the row is on every
+ * story's page, a tab's content only once it is chosen.
+ *
+ * @module
+ */
+import type { ComponentDocs } from "../componentDocs.ts";
+import type { PlayTrace } from "../playTrace.ts";
+import type { CheckState } from "./A11yTab.tsx";
+/**
+ * The Accessibility tab's hint: how many rules are broken once checked.
+ *
+ * @param check - the check's state.
+ */
+export declare const a11yHint: (check: CheckState) => string | undefined;
+/**
+ * The Interactions tab's hint: the play's status.
+ *
+ * @param trace - the trace.
+ */
+export declare const interactionsHint: (trace: PlayTrace) => string;
+/**
+ * The `data-*` hooks of a component's modifiers, which the Parts and styling tab lists.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const styleHooks: (docs: ComponentDocs) => string[];

package/dist/src/shell/tabSummaries.js

@@ -0,0 +1,27 @@
+import { STRINGS } from "./strings.js";
+/**
+ * The Accessibility tab's hint: how many rules are broken once checked.
+ *
+ * @param check - the check's state.
+ */
+export const a11yHint = (check) => {
+    if (check.status !== "done")
+        return undefined;
+    return check.violations.length === 0 ? STRINGS.a11yPasses : STRINGS.a11yCount(check.violations.length);
+};
+/**
+ * The Interactions tab's hint: the play's status.
+ *
+ * @param trace - the trace.
+ */
+export const interactionsHint = (trace) => STRINGS.playStatus[trace.status];
+/** The props that carry a component's modifiers, each mirrored by a `data-*` styling hook. */
+const MODIFIERS = ["variant", "size", "tone", "shape", "width", "orientation"];
+/**
+ * The `data-*` hooks of a component's modifiers, which the Parts and styling tab lists.
+ *
+ * @param docs - the component's docs.
+ */
+export const styleHooks = (docs) => docs.props
+    .filter((prop) => prop.kind === "choice" && MODIFIERS.includes(prop.name))
+    .map((prop) => `data-${prop.name}="${(prop.choices ?? []).join(" | ")}"`);

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

@@ -6,11 +6,13 @@
  * @remarks
  * Case and accents are ignored. A component whose own name, title and search words hold every word is found whole; otherwise only
  * the stories that hold the words the component lacks are kept. An alias entry is found by its name, the place
- * it is listed in and the place it lives in, whole or not at all: its stories are picked on its page. Pure.
+ * it is listed in and the place it lives in, whole or not at all: its stories are picked on its page. Pure. Loaded with
+ * the search's list: a tree nobody filters needs none of it.
  *
  * @module
  */
-import type { TreeComponent, TreeFamily } from "../storyTree.ts";
+import type { TreePage } from "../pageTree.ts";
+import type { StoryTree, TreeComponent, TreeFamily, TreeSource } from "../storyTree.ts";
 /**
  * The words of a query, folded; none for an empty query.
  *
@@ -32,4 +34,38 @@ export declare const foundComponent: (component: TreeComponent, words: readonly
  * @param words - the query's words (`searchWords`).
  */
 export declare const foundFamily: (family: TreeFamily, words: readonly string[]) => TreeFamily | undefined;
-//# sourceMappingURL=treeSearch.d.ts.map
+/**
+ * The docs pages the search finds: by their title and description; every page for no words.
+ *
+ * @param pages - the pages.
+ * @param words - the query's words (`searchWords`).
+ */
+export declare const foundPages: (pages: readonly TreePage[], words: readonly string[]) => readonly TreePage[];
+/** What the tree shows of a source's components. */
+export type ShownSource = {
+    /** The source. */
+    readonly source: TreeSource;
+    /** Its families, with what the search finds. */
+    readonly families: readonly TreeFamily[];
+};
+/** What the tree shows of a source's docs pages. */
+export type ShownPages = {
+    /** The source. */
+    readonly source: TreeSource;
+    /** Its pages the search finds. */
+    readonly pages: readonly TreePage[];
+};
+/** What the tree shows. */
+export type ShownTree = {
+    /** Each source with its families. */
+    readonly sources: readonly ShownSource[];
+    /** The sources with pages to show. */
+    readonly pages: readonly ShownPages[];
+};
+/**
+ * What the tree shows for a query.
+ *
+ * @param tree - the tree.
+ * @param query - what the user typed.
+ */
+export declare const shownTree: (tree: StoryTree, query: string) => ShownTree;

package/dist/src/shell/treeSearch.js

@@ -57,4 +57,30 @@ export const foundFamily = (family, words) => {
         .filter((group) => group.components.length > 0 || group.aliases.length > 0);
     return groups.length === 0 ? undefined : { ...family, groups };
 };
-//# sourceMappingURL=treeSearch.js.map
+/**
+ * The docs pages the search finds: by their title and description; every page for no words.
+ *
+ * @param pages - the pages.
+ * @param words - the query's words (`searchWords`).
+ */
+export const foundPages = (pages, words) => words.length === 0
+    ? pages
+    : pages.filter((page) => holdsEvery(folded(`${page.title.replaceAll("/", " ")} ${page.description ?? ""}`), words));
+/**
+ * What the tree shows for a query.
+ *
+ * @param tree - the tree.
+ * @param query - what the user typed.
+ */
+export const shownTree = (tree, query) => {
+    const words = searchWords(query);
+    return {
+        sources: tree.sources.map((source) => ({
+            source,
+            families: source.families.flatMap((family) => foundFamily(family, words) ?? [])
+        })),
+        pages: tree.sources
+            .map((source) => ({ source, pages: foundPages(source.pages, words) }))
+            .filter((entry) => entry.pages.length > 0)
+    };
+};

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

@@ -0,0 +1,55 @@
+import { type ArgDeclaration, type DroppedArg } from "../addressArgs.ts";
+import type { ComponentDocs } from "../componentDocs.ts";
+import { type PanelArgs } from "../messages.ts";
+import type { NamedValues } from "../namedValues.ts";
+import type { ReadyMessage } from "./useFrameMessages.ts";
+import type { Loaded } from "./useLoaded.ts";
+/** What the story's frame reported that the check reads: its own args, its `argTypes` and its controls. */
+export type ReadyDeclaration = Pick<ReadyMessage, "args" | "argTypes" | "controls">;
+/**
+ * What a story declares, once both its frame and its docs answered.
+ *
+ * @param docs - the component's docs; a story without a component, or whose docs failed, declares no typed props.
+ * @param ready - what the story's frame reported; none before it is ready.
+ * @param namedValues - the source's named values.
+ * @returns the declaration; none while the frame or the docs are still loading.
+ */
+export declare const declarationOf: (docs: Loaded<ComponentDocs>, ready: ReadyDeclaration | undefined, namedValues: NamedValues) => ArgDeclaration | undefined;
+/** What the stage knows of the story when it checks the address's values. */
+export type AddressArgsInput = {
+    /** The values the address names. */
+    readonly panelArgs: PanelArgs;
+    /** The component's docs. */
+    readonly docs: Loaded<ComponentDocs>;
+    /** The story's own args its frame reported; none before it is ready. */
+    readonly storyArgs: PanelArgs | undefined;
+    /** The story's `argTypes`, as its frame reported them. */
+    readonly argTypes: ReadyDeclaration["argTypes"];
+    /** The props the story lets the panel set. */
+    readonly controls: ReadyDeclaration["controls"];
+    /** The source's named values; none when it has none. */
+    readonly namedValues: NamedValues | undefined;
+};
+/** The address's values once checked, and how to check them for a frame that has just reported ready. */
+export type AddressArgs = {
+    /** The values the story receives; none before its declaration is known. */
+    readonly accepted: PanelArgs;
+    /** The values left out, with the reason. */
+    readonly dropped: readonly DroppedArg[];
+    /**
+     * The accepted values as the address writes them, to tell the frames only when they change; none before the
+     * declaration is known, when no frame is told anything.
+     */
+    readonly acceptedParam: string | undefined;
+    /**
+     * The values to send a frame that has just reported ready, from its own message, since the state that holds it
+     * updates after; none while the docs load.
+     */
+    readonly acceptedFor: (ready: ReadyDeclaration) => PanelArgs | 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 declare const useAddressArgs: (input: AddressArgsInput) => AddressArgs;

package/dist/src/shell/useAddressArgs.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ *
+ * @remarks
+ * The address is written by whoever shares the link, so its values are checked here, in the core, before any frame
+ * receives them, whatever framework draws the story (`addressArgs.ts`). Until the story's frame is ready and its docs
+ * are read (or known to be missing), no value is sent: the frame draws the story's own args meanwhile.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { checkedAddressArgs } from "../addressArgs.js";
+import { panelArgsParam } from "../messages.js";
+/**
+ * What a story declares, once both its frame and its docs answered.
+ *
+ * @param docs - the component's docs; a story without a component, or whose docs failed, declares no typed props.
+ * @param ready - what the story's frame reported; none before it is ready.
+ * @param namedValues - the source's named values.
+ * @returns the declaration; none while the frame or the docs are still loading.
+ */
+export const declarationOf = (docs, ready, namedValues) => {
+    if (ready === undefined || docs.status === "loading")
+        return undefined;
+    return {
+        props: docs.status === "ready" ? docs.value.props : [],
+        argTypes: ready.argTypes,
+        controls: ready.controls,
+        storyArgs: ready.args,
+        namedValues
+    };
+};
+/** No value: what the story receives of the address before its declaration is known. */
+const NO_ARGS = {};
+/** No value left out. */
+const NOTHING_DROPPED = [];
+/** A source without named values. */
+const NO_NAMED_VALUES = {};
+/**
+ * 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 namedValues = input.namedValues ?? NO_NAMED_VALUES;
+    const checked = 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 {
+        accepted: checked?.accepted ?? NO_ARGS,
+        dropped: checked?.dropped ?? NOTHING_DROPPED,
+        acceptedParam: checked === undefined ? undefined : panelArgsParam(checked.accepted),
+        acceptedFor: (message) => {
+            const declaration = declarationOf(docs, message, namedValues);
+            return declaration === undefined ? undefined : checkedAddressArgs(panelArgs, declaration).accepted;
+        }
+    };
+};

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

@@ -0,0 +1,24 @@
+/**
+ * Brings a page's heading or prop into view when the address names one: at once when the page opens, smoothly when the
+ * reader follows a link inside it, and lit for a moment after a search, since a table's row is hard to find with the eye.
+ *
+ * @remarks
+ * What comes near as the page moves loads then, frames taking their real heights and tables arriving, which moves what
+ * follows them, so a heading is placed again whenever the content's size changes, until the person scrolls themselves.
+ * After a link inside the page or a search, focus moves to what was opened: without it, the next Tab starts again from
+ * where the link was.
+ *
+ * @module
+ */
+import { type RefObject } from "react";
+import { type PageVisit } from "./useScrollMemory.ts";
+/**
+ * Keeps a page's heading in view.
+ *
+ * @param ref - the page's scrolling element.
+ * @param anchor - the heading the address names; none when it names none.
+ * @param visit - the visit of the page.
+ * @param isReady - whether the page's text is there.
+ * @returns what brings the named heading back into view: a link to it again changes no address.
+ */
+export declare const useAnchorScroll: (ref: RefObject<HTMLElement | null>, anchor: string | undefined, visit: PageVisit, isReady: boolean) => (() => void);

package/dist/src/shell/useAnchorScroll.js

@@ -0,0 +1,90 @@
+/**
+ * Brings a page's heading or prop into view when the address names one: at once when the page opens, smoothly when the
+ * reader follows a link inside it, and lit for a moment after a search, since a table's row is hard to find with the eye.
+ *
+ * @remarks
+ * What comes near as the page moves loads then, frames taking their real heights and tables arriving, which moves what
+ * follows them, so a heading is placed again whenever the content's size changes, until the person scrolls themselves.
+ * After a link inside the page or a search, focus moves to what was opened: without it, the next Tab starts again from
+ * where the link was.
+ *
+ * @module
+ */
+import { useCallback, useLayoutEffect } from "react";
+import { anchorSelector } from "../docAnchors.js";
+import { OWN_SCROLL_EVENTS } from "./useScrollMemory.js";
+/** The room left above a heading brought into view, in CSS px. */
+const TOP_ROOM = 16;
+/** How a heading comes into view: at once, or smoothly when the reader's preference allows. */
+const scrollStyle = (isOwnLink) => isOwnLink && !window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "smooth" : "auto";
+/** Scrolls an element so a heading of it sits at its top. */
+const placeHeading = (scroller, heading, behavior) => {
+    const top = heading.getBoundingClientRect().top - scroller.getBoundingClientRect().top;
+    scroller.scrollTo({ top: scroller.scrollTop + top - TOP_ROOM, behavior });
+};
+/** A heading of the page or a prop's row, by its anchor. */
+const headingOf = (scroller, anchor) => scroller.querySelector(anchorSelector(anchor));
+/** Gives the focus to what an address opened: a heading's own link, or the element itself. */
+const focusHeading = (heading) => {
+    const target = heading.querySelector("a") ?? heading;
+    if (!(target instanceof HTMLElement))
+        return;
+    // a table's row or a component's heading takes no focus of its own
+    if (target.tabIndex < 0)
+        target.tabIndex = -1;
+    target.focus({ preventScroll: true });
+};
+/** Brings a heading into view from a link inside the page. */
+const goToHeading = (scroller, heading) => {
+    placeHeading(scroller, heading, scrollStyle(true));
+    focusHeading(heading);
+};
+/** Marks what a search opened for as long as its animation lasts (`[data-found]` in the style sheet). */
+const markFound = (heading) => {
+    focusHeading(heading);
+    heading.setAttribute("data-found", "");
+    heading.addEventListener("animationend", () => heading.removeAttribute("data-found"), { once: true });
+};
+/**
+ * Keeps a page's heading in view.
+ *
+ * @param ref - the page's scrolling element.
+ * @param anchor - the heading the address names; none when it names none.
+ * @param visit - the visit of the page.
+ * @param isReady - whether the page's text is there.
+ * @returns what brings the named heading back into view: a link to it again changes no address.
+ */
+export const useAnchorScroll = (ref, anchor, visit, isReady) => {
+    useLayoutEffect(() => {
+        const scroller = ref.current;
+        if (scroller === null || anchor === undefined || !isReady)
+            return;
+        const heading = headingOf(scroller, anchor);
+        if (heading === null)
+            return;
+        const isOwnLink = visit.isInPage === true;
+        if (isOwnLink)
+            goToHeading(scroller, heading);
+        else
+            placeHeading(scroller, heading, "auto");
+        if (visit.movesFocus === true)
+            markFound(heading);
+        const resizes = new ResizeObserver(() => placeHeading(scroller, heading, scrollStyle(isOwnLink)));
+        const stop = () => {
+            resizes.disconnect();
+            for (const name of OWN_SCROLL_EVENTS)
+                scroller.removeEventListener(name, stop);
+        };
+        for (const child of scroller.children)
+            resizes.observe(child);
+        for (const name of OWN_SCROLL_EVENTS)
+            scroller.addEventListener(name, stop, { passive: true });
+        return stop;
+    }, [ref, anchor, visit, isReady]);
+    return useCallback(() => {
+        const scroller = ref.current;
+        const heading = scroller === null || anchor === undefined ? null : headingOf(scroller, anchor);
+        if (scroller !== null && heading !== null)
+            goToHeading(scroller, heading);
+    }, [ref, anchor]);
+};

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

@@ -1,4 +1,6 @@
 import { type Appearance } from "../catalogue.ts";
+import type { ViewSwitch } from "../switches.ts";
+import { type ViewState } from "../viewState.ts";
 /** The root's attribute the palettes read: `light` or `dark`, the system's resolved. */
 export declare const APPEARANCE_ATTRIBUTE = "data-forgebook-appearance";
 /** The shell's appearance and its setter. */
@@ -7,11 +9,14 @@ export type AppearanceState = {
     readonly appearance: Appearance;
     /** Picks an appearance, kept for the next visit. */
     readonly setAppearance: (appearance: Appearance) => void;
+    /** The appearances this catalogue offers. */
+    readonly offered: readonly Appearance[];
 };
 /**
  * The shell's appearance, applied to the page's root.
  *
+ * @param view - the view, whose colour scheme the shell can follow.
+ * @param switches - the catalogue's switches.
  * @returns the appearance shown and its setter.
  */
-export declare const useAppearance: () => AppearanceState;
-//# sourceMappingURL=useAppearance.d.ts.map
+export declare const useAppearance: (view: ViewState, switches: readonly ViewSwitch[]) => AppearanceState;

package/dist/src/shell/useAppearance.js

@@ -1,5 +1,5 @@
 /**
- * The shell's own appearance: light, dark or the system's, a reader's choice kept in their browser, the catalogue's
+ * The shell's own appearance: light, dark, the system's or the story's, a reader's choice kept in their browser, the catalogue's
  * default before they pick one; written on the page's root, where the palettes of `shell.scss` read it.
  *
  * @remarks
@@ -10,7 +10,9 @@
  */
 import { useEffect } from "react";
 import { APPEARANCES } from "../catalogue.js";
+import { isComparing } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
+import { offeredAppearances, shellIsDark } from "./shellScheme.js";
 import { useStored } from "./useStored.js";
 import { useSystemDark } from "./useSystemDark.js";
 /** The root's attribute the palettes read: `light` or `dark`, the system's resolved. */
@@ -20,17 +22,24 @@ const storedAppearance = (stored) => APPEARANCES.find((appearance) => appearance
 /**
  * The shell's appearance, applied to the page's root.
  *
+ * @param view - the view, whose colour scheme the shell can follow.
+ * @param switches - the catalogue's switches.
  * @returns the appearance shown and its setter.
  */
-export const useAppearance = () => {
+export const useAppearance = (view, switches) => {
     const catalogue = useCatalogue();
     const [chosen, setChosen] = useStored("appearance", storedAppearance, (value) => value ?? "");
     const appearance = chosen ?? catalogue.appearance;
     const isSystemDark = useSystemDark();
-    const isDark = appearance === "dark" || (appearance === "system" && isSystemDark);
+    const isDark = shellIsDark({
+        appearance,
+        values: view.switches,
+        switches,
+        isSystemDark,
+        isComparing: isComparing(view)
+    });
     useEffect(() => {
         document.documentElement.setAttribute(APPEARANCE_ATTRIBUTE, isDark ? "dark" : "light");
     }, [isDark]);
-    return { appearance, setAppearance: setChosen };
+    return { appearance, setAppearance: setChosen, offered: offeredAppearances(switches) };
 };
-//# sourceMappingURL=useAppearance.js.map

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

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

package/dist/src/shell/useComponentDocs.js

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

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

@@ -13,6 +13,8 @@ export type ControlKeysInput = {
     readonly fixed: FixedView;
     /** Whether a story's page is shown. */
     readonly isStoryPage: boolean;
+    /** Whether a component's page is shown: the audience's key does nothing elsewhere, as its control. */
+    readonly isComponentPage: boolean;
 };
 /**
  * Listens to the controls' keys.
@@ -20,4 +22,3 @@ export type ControlKeysInput = {
  * @param input - the keys, the view and its setter, what the story fixes and the page shown.
  */
 export declare const useControlKeys: (input: ControlKeysInput) => void;
-//# sourceMappingURL=useControlKeys.d.ts.map

package/dist/src/shell/useControlKeys.js

@@ -23,13 +23,13 @@ export const useControlKeys = (input) => {
         const cycle = (event) => {
             if (isTyping(event.target))
                 return;
-            const { keys, view, onViewChange, fixed, isStoryPage } = latest.current;
+            const { keys, view, onViewChange, fixed, isStoryPage, isComponentPage } = latest.current;
             const pressed = pressedControl(keys, {
                 key: event.key,
                 shiftKey: event.shiftKey,
                 hasModifier: event.metaKey || event.ctrlKey || event.altKey
             });
-            if (pressed === undefined)
+            if (pressed === undefined || (pressed.id === "audience" && !isComponentPage))
                 return;
             const changed = cycledView(view, pressed.id, pressed.step, catalogue, fixed, isStoryPage);
             if (changed === undefined)
@@ -41,4 +41,3 @@ export const useControlKeys = (input) => {
         return () => document.removeEventListener("keydown", cycle);
     }, [catalogue]);
 };
-//# sourceMappingURL=useControlKeys.js.map

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

@@ -2,9 +2,10 @@
 export type Copy = {
     /** Whether the text was copied a moment ago. */
     readonly isCopied: boolean;
+    /** Whether the last copy failed a moment ago: the browser gives no clipboard on plain HTTP, or refused. */
+    readonly hasFailed: boolean;
     /** Copies a text to the clipboard. */
     readonly copy: (text: string) => void;
 };
 /** Copies texts, remembering the last copy for a moment. */
 export declare const useCopy: () => Copy;
-//# sourceMappingURL=useCopy.d.ts.map

package/dist/src/shell/useCopy.js

@@ -9,15 +9,20 @@ const COPIED_FOR = 1500;
 /** Copies texts, remembering the last copy for a moment. */
 export const useCopy = () => {
     const [isCopied, setIsCopied] = useState(false);
+    const [hasFailed, setHasFailed] = useState(false);
     const timer = useRef(undefined);
     useEffect(() => () => window.clearTimeout(timer.current), []);
     const copy = useCallback((text) => {
-        void navigator.clipboard.writeText(text).then(() => {
-            setIsCopied(true);
+        const show = (setShown) => {
+            setShown(true);
             window.clearTimeout(timer.current);
-            timer.current = window.setTimeout(() => setIsCopied(false), COPIED_FOR);
-        });
+            timer.current = window.setTimeout(() => setShown(false), COPIED_FOR);
+        };
+        // inside a promise, since on plain HTTP the clipboard is not there at all
+        Promise.resolve()
+            .then(() => navigator.clipboard.writeText(text))
+            .then(() => show(setIsCopied))
+            .catch(() => show(setHasFailed));
     }, []);
-    return { isCopied, copy };
+    return { isCopied, hasFailed, copy };
 };
-//# sourceMappingURL=useCopy.js.map

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

@@ -24,4 +24,3 @@ export type Fold = {
  * @param isInstant - whether it opens and shuts at once this time.
  */
 export declare const useFold: (isOpen: boolean, isInstant: boolean) => Fold;
-//# sourceMappingURL=useFold.d.ts.map

package/dist/src/shell/useFold.js

@@ -86,4 +86,3 @@ export const useFold = (isOpen, isInstant) => {
     }, [isOpen]);
     return { isDrawn, ref };
 };
-//# sourceMappingURL=useFold.js.map

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

@@ -1,10 +1,19 @@
 import type { Violation } from "../a11y.ts";
-import { type FrameMessage } from "../messages.ts";
+import { type FrameMessage, type PanelArgs } from "../messages.ts";
 import type { PlayTrace } from "../playTrace.ts";
+/**
+ * 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 declare const FRAME_ASIDE_ATTRIBUTE = "data-forgebook-aside";
 /** A message of a frame that the stage answers. */
 export type ReadyMessage = Extract<FrameMessage, {
     type: "forgebook:ready";
 }>;
+/** What a plugin's frame module reported. */
+export type PluginReportMessage = Extract<FrameMessage, {
+    type: "forgebook:plugin";
+}>;
 /** A call of an event, as the log shows it. */
 export type EventCall = Omit<Extract<FrameMessage, {
     type: "forgebook:call";
@@ -29,8 +38,8 @@ export type FrameHandlers = {
     readonly onReady: (frame: Window, message: ReadyMessage) => void;
     /** An event was called. */
     readonly onCall: (call: EventCall) => void;
-    /** A frame could not show its story; none where nothing waits for it. */
-    readonly onFailed?: (storyId: string) => void;
+    /** A frame could not show its story, and why; none where nothing waits for it. */
+    readonly onFailed?: (storyId: string, message: string) => void;
     /** A story's play function reported its trace; none where nothing shows it. */
     readonly onPlay?: (storyId: string, trace: PlayTrace) => void;
     /** An accessibility check is over: the rules broken, or why it could not run; none where nothing asks for one. */
@@ -40,6 +49,13 @@ export type FrameHandlers = {
      * several frames of a story); none where nothing shows them.
      */
     readonly onSpills?: (storyId: string, count: number, frame: string) => void;
+    /** A plugin's frame module told its tab about a story; none where no tab shows it. */
+    readonly onPluginReport?: (message: PluginReportMessage) => void;
+    /**
+     * A story changed its own args (Storybook's `useArgs`): its id, and the panel's values the change makes; none where no
+     * panel shows them.
+     */
+    readonly onStoryArgs?: (storyId: string, args: PanelArgs) => void;
 };
 /** An accessibility check's result, as a frame reported it. */
 export type CheckResult = {
@@ -56,4 +72,3 @@ export type CheckResult = {
  * @returns what they reported.
  */
 export declare const useFrameMessages: (handlers: FrameHandlers) => FrameReports;
-//# sourceMappingURL=useFrameMessages.d.ts.map