forgebook 0.1.7 → 0.2.0

package/dist/src/shell/Stage.js

@@ -14,24 +14,29 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { panelProps, settableProps } from "../argTypes.js";
 import { matrixOf, matrixProps } from "../matrix.js";
+import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
 import { NOT_FIXED, withFixed, withOwnFixed } from "../storyGlobals.js";
-import { frameAddress, isComparing, liveView } from "../viewState.js";
-import { ClockControls, useStoryClockControls } from "./ClockControls.js";
+import { frameAddress, isComparing, liveView, schemeOf, viewParams } from "../viewState.js";
+import { useStoryClockControls } from "./ClockControls.js";
 import { useCatalogue } from "./catalogueContext.js";
-import { compareVariants } from "./compareVariants.js";
+import { DeviceSlot, deviceAddress, isWaitingForDevice, roomSizing, useInkScheme, useStageDevice } from "./DeviceSlot.js";
 import { Dock } from "./Dock.js";
+import { DroppedArgsNote } from "./DroppedArgsNote.js";
 import { dockTabs } from "./dockTabs.js";
 import { FrameView, tellFrames } from "./FrameView.js";
-import { Icon } from "./icons.js";
-import { MatrixPicker } from "./MatrixPicker.js";
+import { framesOrigin } from "./framesOrigin.js";
+import { StageCompare } from "./StageCompare.js";
 import { StageTools } from "./StageTools.js";
 import { StageViewport } from "./StageViewport.js";
+import { StoryBar } from "./StoryBar.js";
 import { STRINGS } from "./strings.js";
+import { useAddressArgs } from "./useAddressArgs.js";
 import { useComponentDocs } from "./useComponentDocs.js";
-import { useCopy } from "./useCopy.js";
 import { useFrameMessages } from "./useFrameMessages.js";
 import { useLiveView, useLoadedView } from "./useLiveView.js";
+import { usePluginStory, usePluginTabs } from "./usePluginTabs.js";
 import { useScrollMemory } from "./useScrollMemory.js";
+import { useStoryCheck } from "./useStoryCheck.js";
 import { useStoryCode } from "./useStoryCode.js";
 import { useWorstCase } from "./useWorstCase.js";
 /** The `argTypes` of a story before its frame reported them. */
@@ -51,53 +56,53 @@ const widthSetter = (fixed, view, onViewChange) => fixed.width === undefined ? (
  * @param panels - what each story's frame reported, by story.
  * @param story - the story.
  */
-const reportedPanel = (panels, story) => panels.get(story.id) ?? { argTypes: NO_ARG_TYPES, controls: story.controls, actions: [], fixed: NOT_FIXED };
+const reportedPanel = (panels, story) => panels.get(story.id) ?? {
+    argTypes: NO_ARG_TYPES,
+    controls: story.controls,
+    actions: [],
+    fixed: NOT_FIXED,
+    parameters: []
+};
 /** The height of the first frame before its story reports its own, in CSS px. */
 const INITIAL_FRAME_HEIGHT = 240;
 /** The most calls the Events tab keeps. */
 const MAX_CALLS = 50;
 /**
- * The accessibility check of the shown story: its state, cleared when the story or the view changes, and how to run
- * it in the frame.
+ * Whether a story's args change what it draws: not for a story of fixed examples, nor for one about logic, whose scene
+ * takes none.
  *
- * @param frameRef - the story's frame.
- * @param checkKey - the story and the view, as one text: a check belongs to them.
+ * @param story - the story.
  */
-const useStoryCheck = (frameRef, checkKey) => {
-    const [check, setCheck] = useState({ status: "idle" });
-    const [checkedKey, setCheckedKey] = useState(checkKey);
-    if (checkedKey !== checkKey) {
-        setCheckedKey(checkKey);
-        setCheck({ status: "idle" });
-    }
-    return {
-        check,
-        run: () => {
-            setCheck({ status: "running" });
-            const message = { type: "forgebook:check" };
-            frameRef.current?.contentWindow?.postMessage(message, window.location.origin);
-        },
-        receive: (result) => setCheck("error" in result
-            ? { status: "error", message: result.error }
-            : { status: "done", violations: result.violations })
-    };
-};
+const takesArgs = (story) => !story.isLogic && (story.controls === "all" || story.controls.length > 0);
 /**
- * Copies the story's id (`kit:inputs-selection-select--overview`), the name tests and tools address it by; the id
- * shows as the button's tooltip.
+ * What an embed of the story keeps of the page: its view and the values set in the panel. An embed draws no device
+ * frame, so the device chosen is left out: the embed is the story at the width its iframe gives it.
  *
- * @param props - the story's id.
+ * @param view - the reader's view, without what the story fixes, which the story fixes again.
+ * @param panelArgs - the values set in the panel.
+ * @param switches - the catalogue's switches.
  */
-const CopyIdButton = ({ storyId }) => {
-    const { isCopied, copy } = useCopy();
-    return (_jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon", title: `${STRINGS.copyStoryId}: ${storyId}`, "aria-label": isCopied ? STRINGS.copied : STRINGS.copyStoryId, onClick: () => copy(storyId), children: _jsx(Icon, { name: isCopied ? "check" : "hash", size: 14 }) }));
+const embedQuery = (view, panelArgs, switches) => {
+    const params = viewParams({ ...view, device: "auto", orientation: "auto" }, switches);
+    const args = panelArgsParam(panelArgs);
+    if (args !== "")
+        params.set("args", args);
+    return params.toString();
 };
+/**
+ * The height an embed's iframe starts at: as tall as the frame is on the stage.
+ *
+ * @param view - the view, with the height set on the stage.
+ * @param contentHeight - the story's content, in CSS px.
+ * @param story - the story, with the height its scene declares.
+ */
+const embedHeight = (view, contentHeight, story) => view.height === "auto" ? Math.max(contentHeight, story.height ?? 0) : view.height;
 /**
  * The stage.
  *
  * @param props - the component, the story, the view, the panel's values, the frame page and the loaders.
  */
-export const Stage = ({ component, story, view: ownView, onViewChange: onOwnViewChange, onFixedChange, panelArgs, onPanelArgsChange, matrixAxes, onMatrixAxesChange, frameUrl, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }) => {
+export const Stage = ({ component, story, view: ownView, onViewChange: onOwnViewChange, onFixedChange, panelArgs, onPanelArgsChange, matrixAxes, onMatrixAxesChange, frameUrl, plugins, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }) => {
     const frameRef = useRef(null);
     const storyRef = useRef(null);
     const docs = useComponentDocs(loadDocs);
@@ -115,18 +120,30 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     const [calls, setCalls] = useState([]);
     // each story's play trace, by story: a trace belongs to the story that played
     const [traces, setTraces] = useState(new Map());
+    // what each plugin's frame module last told its tab, by story: a plugin's report belongs to the story that sent it
+    const [pluginReports, setPluginReports] = useState(new Map());
     const catalogue = useCatalogue();
     const { switches } = catalogue;
     const storyCheck = useStoryCheck(frameRef, frameAddress(frameUrl, story.id, view, switches));
     const eventNames = useMemo(() => docs.status === "ready"
         ? docs.value.props.filter((prop) => prop.kind === "event").map((prop) => prop.name)
         : [], [docs]);
-    // a story of fixed examples ignores its args, so a matrix of them would repeat one drawing
-    const axisProps = docs.status === "ready" && (story.controls === "all" || story.controls.length > 0)
-        ? matrixProps(docs.value.props)
-        : [];
-    const matrix = useMemo(() => (docs.status === "ready" ? matrixOf(docs.value.props, matrixAxes) : undefined) ?? null, [docs, matrixAxes]);
-    const values = { ...storyArgs.get(story.id), ...panelArgs };
+    // a story of fixed examples, or about logic (its scene takes no args), ignores its args, so a matrix of them would
+    // repeat one drawing
+    const axisProps = docs.status === "ready" && takesArgs(story) ? matrixProps(docs.value.props) : [];
+    const matrix = useMemo(() => (docs.status === "ready" && !story.isLogic ? matrixOf(docs.value.props, matrixAxes) : undefined) ??
+        null, [docs, matrixAxes, story.isLogic]);
+    // the address's values reach the frames only once checked against what the story declares
+    const addressArgs = useAddressArgs({
+        panelArgs,
+        docs,
+        storyArgs: storyArgs.get(story.id),
+        argTypes: panel.argTypes,
+        controls: panel.controls,
+        namedValues
+    });
+    const acceptedArgs = addressArgs.accepted;
+    const values = { ...storyArgs.get(story.id), ...acceptedArgs };
     const settable = useMemo(() => docs.status === "ready"
         ? settableProps(panelProps(docs.value.props, panel.argTypes), panel.controls, namedValues ?? {})
         : [], [docs, panel.argTypes, panel.controls, namedValues]);
@@ -135,7 +152,7 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         storyId: story.id,
         settable,
         values,
-        panelArgs,
+        panelArgs: acceptedArgs,
         onPanelArgsChange
     });
     const clockControls = useStoryClockControls(frameRef, story.id);
@@ -147,12 +164,16 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
                 argTypes: message.argTypes,
                 controls: message.controls,
                 actions: message.actions,
-                fixed: message.fixed
+                fixed: message.fixed,
+                parameters: message.parameters
             }));
             onFixedChange(message.storyId, message.fixed);
-            const send = (shellMessage) => frame.postMessage(shellMessage, window.location.origin);
+            const send = (shellMessage) => frame.postMessage(shellMessage, framesOrigin());
             send({ type: "forgebook:events", names: eventNames });
-            send({ type: "forgebook:args", args: panelArgs });
+            // checked against the shown story's declaration only: a late message of the story shown before sends nothing
+            const accepted = message.storyId === story.id ? addressArgs.acceptedFor(message) : undefined;
+            if (accepted !== undefined)
+                send({ type: "forgebook:args", args: accepted });
             send({ type: "forgebook:matrix", matrix });
             // the view may have changed while the frame loaded
             if (!isComparing(view))
@@ -168,20 +189,30 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
             if (result.storyId === story.id)
                 storyCheck.receive(result);
         },
-        onSpills: worstCase.receive
+        onSpills: worstCase.receive,
+        onPluginReport: (message) => setPluginReports((current) => new Map(current).set(`${message.storyId}|${message.plugin}`, message)),
+        // a story that changes its own args changes the panel's values, as the reader would
+        onStoryArgs: (storyId, args) => storyId === story.id ? onPanelArgsChange(args) : undefined
     });
     // the docs may arrive after the frames: they learn the events then
     useEffect(() => tellFrames(storyRef.current, { type: "forgebook:events", names: eventNames }), [eventNames]);
     useEffect(() => tellFrames(storyRef.current, { type: "forgebook:matrix", matrix }), [matrix]);
-    // the values reach the frames from the address, so going back in the history sets them too
-    useEffect(() => tellFrames(storyRef.current, { type: "forgebook:args", args: panelArgs }), [panelArgs]);
+    // 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 { acceptedParam } = addressArgs;
+    useEffect(() => {
+        if (acceptedParam === undefined)
+            return;
+        tellFrames(storyRef.current, { type: "forgebook:args", args: parsePanelArgsParam(acceptedParam) });
+    }, [acceptedParam]);
+    // a change starts from the values the story takes: one the address named and the story does not is let go
     const changeValue = (name, value) => {
-        const { [name]: _removed, ...rest } = panelArgs;
+        const { [name]: _removed, ...rest } = acceptedArgs;
         onPanelArgsChange(value === undefined ? rest : { ...rest, [name]: value });
     };
     const replay = () => {
         const message = { type: "forgebook:replay" };
-        frameRef.current?.contentWindow?.postMessage(message, window.location.origin);
+        frameRef.current?.contentWindow?.postMessage(message, framesOrigin());
     };
     const title = STRINGS.frameTitle(component.name, story.name);
     const canReplay = replayable === story.id && !isComparing(view);
@@ -189,9 +220,12 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     const hasClock = clocked === story.id && !isComparing(view);
     // the frame loads again only for another story or style sheets; the rest of the view (the switches, the language
     // among them) is sent live
-    const address = frameAddress(frameUrl, story.id, useLoadedView(`${story.id}|${view.sheets}`, view), switches);
+    // a device sets the story's width and height in place of the stage's own, and its story area is the toolbar's width
+    const { shown, framed } = useStageDevice(view, story.device, onShownWidthChange);
+    const address = deviceAddress(frameAddress(frameUrl, story.id, useLoadedView(`${story.id}|${view.sheets}`, view), switches), framed);
     useLiveView(storyRef, view, !isComparing(view));
     useScrollMemory(storyRef, scroll);
+    const ink = useInkScheme(schemeOf(view, switches));
     // a story not shown yet waits at its measured height, or keeps the last story's, until it reports its own, so the
     // page does not jump twice
     const reportedHeight = heights.get(address);
@@ -200,11 +234,28 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         if (reportedHeight !== undefined)
             setLastHeight(reportedHeight);
     }, [reportedHeight]);
+    const pluginTabs = usePluginTabs({
+        plugins,
+        strings: catalogue.strings,
+        story: usePluginStory(component, story),
+        parameters: panel.parameters,
+        reports: pluginReports,
+        isComparing: isComparing(view),
+        aside: {
+            // as the stage draws it: at its device's screen width and told its safe areas
+            address: deviceAddress(frameAddress(frameUrl, story.id, view, switches), framed),
+            width: framed?.area.width ?? view.width,
+            background: backgroundOf(view),
+            args: panelArgs,
+            view: liveView(view)
+        }
+    });
     // a tab the catalogue turns off is never shown
     const tabs = dockTabs({
         docs,
         code,
         exportName: story.exportName,
+        isLogic: story.isLogic,
         componentName: component.name,
         argTypes: panel.argTypes,
         controls: panel.controls,
@@ -216,20 +267,30 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         namedValues,
         textArgs: Object.fromEntries(Object.entries(storyTextKeys.get(story.id) ?? {}).map(([name, key]) => [
             name,
-            { key, isChanged: panelArgs[name] !== undefined }
+            { key, isChanged: acceptedArgs[name] !== undefined }
         ])),
+        propGroups: component.propGroups,
         calls: calls.filter((call) => call.storyId === story.id),
         onClearCalls: () => setCalls([]),
         trace: isComparing(view) ? undefined : traces.get(story.id),
         onPlayAgain: () => {
             const message = { type: "forgebook:play-again" };
-            frameRef.current?.contentWindow?.postMessage(message, window.location.origin);
+            frameRef.current?.contentWindow?.postMessage(message, framesOrigin());
         },
         check: storyCheck.check,
-        onCheck: isComparing(view) ? undefined : storyCheck.run
+        onCheck: isComparing(view) ? undefined : storyCheck.run,
+        pluginTabs
     }).filter((tab) => catalogue.tabs.includes(tab.id));
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("div", { className: "forgebook-story-pane", children: [_jsx("div", { ref: storyRef, className: "forgebook-scroll", children: _jsxs("section", { className: "forgebook-story", "aria-label": STRINGS.storyLabel, children: [_jsxs("div", { className: "forgebook-story__bar", children: [_jsxs("div", { className: "forgebook-stage__heading", children: [_jsx("h2", { className: "forgebook-stage__title", children: story.name }), story.description === undefined ? null : (_jsx("p", { className: "forgebook-stage__description", title: story.description, children: story.description }))] }), axisProps.length === 0 ? null : (_jsx(MatrixPicker, { props: axisProps, axes: matrixAxes, onAxesChange: onMatrixAxesChange })), canReplay ? (_jsxs("button", { type: "button", className: "forgebook-button", onClick: replay, children: [_jsx(Icon, { name: "replay", size: 14 }), STRINGS.replay] })) : null, hasClock ? _jsx(ClockControls, { controls: clockControls }) : null, _jsx(CopyIdButton, { storyId: story.id }), _jsx("a", { className: "forgebook-button forgebook-button--icon", href: frameAddress(frameUrl, story.id, view, switches), target: "_blank", rel: "noopener", title: STRINGS.openFrame, "aria-label": STRINGS.openFrame, children: _jsx(Icon, { name: "external", size: 14 }) })] }), isComparing(view) ? (_jsx("div", { className: "forgebook-compare", children: compareVariants(view.compare, catalogue).map((variant) => (_jsxs("figure", { className: "forgebook-compare__cell", 
-                                        // the label (the shell's text) reads on the page's colour; the frame draws the backdrop
-                                        style: { backgroundColor: backgroundOf({ ...variant.viewOf(view), backdrop: "plain" }) }, children: [_jsx("figcaption", { className: "forgebook-compare__label", children: variant.label }), _jsx(FrameView, { title: `${title} · ${variant.label}`, address: frameAddress(frameUrl, story.id, variant.viewOf(view), switches), heights: heights, settled: settled, fallbackHeight: lastHeight, sceneHeight: story.height })] }, variant.label))) })) : (_jsx(StageViewport, { zoom: view.zoom, width: view.width, onWidthChange: widthSetter(panel.fixed, view, onViewChange), onShownWidthChange: onShownWidthChange, background: backgroundOf(view), height: view.height, onHeightChange: (height) => onViewChange({ ...view, height }), children: (fixedHeight) => (_jsx(FrameView, { ref: frameRef, title: title, address: address, heights: heights, settled: settled, fallbackHeight: measuredHeight ?? lastHeight, sceneHeight: story.height, fixedHeight: fixedHeight }, story.id)) }))] }) }), isComparing(view) ? null : (_jsx(StageTools, { zoom: view.zoom, onZoomChange: (zoom) => onViewChange({ ...view, zoom }), tools: view.tools, onToolsChange: (tools) => onViewChange({ ...view, tools }) }))] }), view.isPanelOpen ? (_jsx(Dock, { tabs: tabs, activeTab: view.panelTab, onTabChange: (panelTab) => onViewChange({ ...view, panelTab }), onClose: () => onViewChange({ ...view, isPanelOpen: false }) })) : null] }));
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, _jsxs("div", { className: "forgebook-story-pane", children: [_jsx("div", { ref: storyRef, className: "forgebook-scroll", children: _jsxs("section", { className: "forgebook-story", "aria-label": STRINGS.storyLabel, children: [_jsx(StoryBar, { story: story, axisProps: axisProps, matrixAxes: matrixAxes, onMatrixAxesChange: onMatrixAxesChange, onReplay: canReplay ? replay : undefined, clockControls: hasClock ? clockControls : undefined, frameAddress: frameAddress(frameUrl, story.id, view, switches), embed: {
+                                        title,
+                                        query: embedQuery(ownView, panelArgs, switches),
+                                        height: embedHeight(view, reportedHeight ?? lastHeight, story)
+                                    } }), _jsx(DroppedArgsNote, { dropped: addressArgs.dropped, onRemove: () => onPanelArgsChange(acceptedArgs) }), isComparing(view) ? (_jsx(StageCompare, { story: story, title: title, view: view, frameUrl: frameUrl, framed: framed, heights: heights, settled: settled, fallbackHeight: lastHeight, backgroundOf: backgroundOf })) : (_jsx(StageViewport, { zoom: view.zoom, ...roomSizing(framed, {
+                                        width: view.width,
+                                        onWidthChange: widthSetter(panel.fixed, view, onViewChange),
+                                        onShownWidthChange,
+                                        background: backgroundOf(view),
+                                        height: view.height,
+                                        onHeightChange: (height) => onViewChange({ ...view, height })
+                                    }), children: (fixedHeight) => (_jsx(DeviceSlot, { framed: framed, scheme: ink, background: backgroundOf(view), children: isWaitingForDevice(shown, framed) ? null : (_jsx(FrameView, { ref: frameRef, title: title, address: address, heights: heights, settled: settled, fallbackHeight: measuredHeight ?? lastHeight, sceneHeight: story.height, fixedHeight: framed?.area.height ?? fixedHeight }, story.id)) })) }))] }) }), isComparing(view) ? null : (_jsx(StageTools, { zoom: view.zoom, onZoomChange: (zoom) => onViewChange({ ...view, zoom }), tools: view.tools, onToolsChange: (tools) => onViewChange({ ...view, tools }) }))] }), view.isPanelOpen ? (_jsx(Dock, { tabs: tabs, activeTab: view.panelTab, onTabChange: (panelTab) => onViewChange({ ...view, panelTab }), onClose: () => onViewChange({ ...view, isPanelOpen: false }) })) : null] }));
 };
-//# sourceMappingURL=Stage.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * The compare view of a story's stage, whose module (`CompareGrid.tsx`) loads the first time a view is compared: a
+ * first screen seldom compares, so its code stays out of the first load.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { CompareGridProps } from "./CompareGrid.tsx";
+/**
+ * The compare view, once its module is there.
+ *
+ * @param props - the story, the view, the device and the frames' reports.
+ */
+export declare const StageCompare: (props: CompareGridProps) => ReactNode;

package/dist/src/shell/StageCompare.js

@@ -0,0 +1,11 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { LazyView, lazyModule } from "./lazyModule.js";
+import { STRINGS } from "./strings.js";
+/** The compare view's module, loaded when a view is first compared. */
+const COMPARE_GRID = lazyModule(() => import("./CompareGrid.js").then((module) => module.CompareGrid));
+/**
+ * The compare view, once its module is there.
+ *
+ * @param props - the story, the view, the device and the frames' reports.
+ */
+export const StageCompare = (props) => (_jsx(LazyView, { module: COMPARE_GRID, props: props, loading: null, failed: (message) => (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [STRINGS.compareError, ": ", message] })) }));

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

@@ -24,4 +24,3 @@ export type StageToolsProps = {
  * @param props - the zoom, the tools and their setters.
  */
 export declare const StageTools: ({ zoom, onZoomChange, tools, onToolsChange }: StageToolsProps) => ReactNode;
-//# sourceMappingURL=StageTools.d.ts.map

package/dist/src/shell/StageTools.js

@@ -31,4 +31,3 @@ export const StageTools = ({ zoom, onZoomChange, tools, onToolsChange }) => {
                     return (_jsx("button", { type: "button", className: "forgebook-stage-tools__button", "aria-pressed": isOn, title: STRINGS.tools[tool], "aria-label": STRINGS.tools[tool], onClick: () => onToolsChange(MEASURE_TOOLS.filter((known) => (known === tool ? !isOn : tools.includes(known)))), children: _jsx(Icon, { name: TOOL_ICONS[tool], size: 14 }) }, tool));
                 }) })] }));
 };
-//# sourceMappingURL=StageTools.js.map

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

@@ -1,7 +1,7 @@
 /**
  * The room a story's frame gets on the stage, as a browser's device mode: the stage's whole width or a fixed one,
  * centred, with a handle on each side; the width it has is reported to the toolbar's field. On a story's page a
- * handle at its foot sets its height too (note 142): the story's own (its content, at least the height it declares) or a dragged one, which is the window the story's overlays are placed in.
+ * handle at its foot sets its height too: the story's own (its content, at least the height it declares) or a dragged one, which is the window the story's overlays are placed in.
  *
  * @remarks
  * Dragging either handle widens or narrows the story on both sides at once, so it stays centred; a double click on a
@@ -31,6 +31,11 @@ export type StageViewportProps = {
     readonly height?: StageHeight;
     /** Called with the height the foot handle or its keys set; none shows no foot handle (the component's page). */
     readonly onHeightChange?: ((height: StageHeight) => void) | undefined;
+    /**
+     * Whether the room holds a device (`DeviceSlot.tsx`): the device is the story's edge, so the room draws no surface
+     * of its own; `false` by default.
+     */
+    readonly isDevice?: boolean;
     /**
      * The frame, or a function that draws it at the height set by the foot handle (a drag's while it lasts), in the
      * story's own CSS px; `undefined` lets the frame take the story's own.
@@ -42,5 +47,4 @@ export type StageViewportProps = {
  *
  * @param props - the width, its setter and the frame.
  */
-export declare const StageViewport: ({ width, onWidthChange, zoom, onShownWidthChange, background, height, onHeightChange, children }: StageViewportProps) => ReactNode;
-//# sourceMappingURL=StageViewport.d.ts.map
+export declare const StageViewport: ({ width, onWidthChange, zoom, onShownWidthChange, background, height, onHeightChange, isDevice, children }: StageViewportProps) => ReactNode;

package/dist/src/shell/StageViewport.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * The room a story's frame gets on the stage, as a browser's device mode: the stage's whole width or a fixed one,
  * centred, with a handle on each side; the width it has is reported to the toolbar's field. On a story's page a
- * handle at its foot sets its height too (note 142): the story's own (its content, at least the height it declares) or a dragged one, which is the window the story's overlays are placed in.
+ * handle at its foot sets its height too: the story's own (its content, at least the height it declares) or a dragged one, which is the window the story's overlays are placed in.
  *
  * @remarks
  * Dragging either handle widens or narrows the story on both sides at once, so it stays centred; a double click on a
@@ -31,7 +31,7 @@ const columnStyle = (layoutWidth) => layoutWidth === undefined ? { flex: 1, minW
 /** The frame, drawn at the height set on the stage when it is drawn by a function. */
 const drawnFrame = (children, height) => typeof children === "function" ? children(height) : children;
 /**
- * The handle at the story's foot (note 142): a drag or the up and down keys set the story's height from the one it
+ * The handle at the story's foot: a drag or the up and down keys set the story's height from the one it
  * has, a double click gives it its own back; it shows the height set.
  *
  * @param props - the zoom, the heights and their setters.
@@ -79,7 +79,7 @@ const FootHandle = ({ scale, roomHeight, fixedHeight, currentHeight, onDrag, onH
  *
  * @param props - the width, its setter and the frame.
  */
-export const StageViewport = ({ width, onWidthChange, zoom = 100, onShownWidthChange, background, height = "auto", onHeightChange, children }) => {
+export const StageViewport = ({ width, onWidthChange, zoom = 100, onShownWidthChange, background, height = "auto", onHeightChange, isDevice = false, children }) => {
     const { widthRange } = useCatalogue();
     const roomRef = useRef(null);
     const canvasRef = useRef(null);
@@ -164,10 +164,9 @@ export const StageViewport = ({ width, onWidthChange, zoom = 100, onShownWidthCh
                                 : {
                                     width: layoutWidth * scale,
                                     height: roomHeight === undefined ? undefined : roomHeight * scale
-                                }, children: _jsx("div", { ref: roomRef, className: "forgebook-viewport__room", "data-dragging": isDragging ? "" : undefined, style: {
+                                }, children: _jsx("div", { ref: roomRef, className: "forgebook-viewport__room", "data-dragging": isDragging ? "" : undefined, "data-device": isDevice ? "" : undefined, style: {
                                     width: layoutWidth,
                                     transform: scale === 1 ? undefined : `scale(${scale})`,
                                     backgroundColor: background
                                 }, children: drawnFrame(children, fixedHeight) }) }), _jsx(FootHandle, { scale: scale, roomHeight: roomHeight, fixedHeight: fixedHeight, currentHeight: currentHeight, onDrag: setDragHeight, onHeightChange: onHeightChange })] }), handle("end")] }) }));
 };
-//# sourceMappingURL=StageViewport.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * The bar above the shown story: its name and description, the matrix's axes, Replay, a Live story's clock controls,
+ * the button that copies its id, the Embed button and the link to its frame alone.
+ *
+ * @remarks
+ * The bar only shows and forwards: the stage decides what the story can do (replay, a clock, a matrix) and owns the
+ * frame the actions reach.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { PropDocs } from "../componentDocs.ts";
+import type { TreeStory } from "../storyTree.ts";
+import { type StoryClockControls } from "./ClockControls.tsx";
+import type { EmbedPanelProps } from "./EmbedPanel.tsx";
+/** The story bar's props. */
+export type StoryBarProps = {
+    /** The shown story. */
+    readonly story: Pick<TreeStory, "id" | "name" | "description">;
+    /** The props a matrix can take as an axis; empty hides the picker. */
+    readonly axisProps: readonly PropDocs[];
+    /** The matrix's chosen axes: the rows' prop, then the columns'. */
+    readonly matrixAxes: readonly string[];
+    /** Called with the chosen axes. */
+    readonly onMatrixAxesChange: (axes: readonly string[]) => void;
+    /** Plays the story again; `undefined` hides Replay, for a story that cannot replay or the compare view. */
+    readonly onReplay: (() => void) | undefined;
+    /** The story's clock controls; `undefined` hides them, for a story without a clock or the compare view. */
+    readonly clockControls: StoryClockControls | undefined;
+    /** The address of the story's frame alone, in the view shown. */
+    readonly frameAddress: string;
+    /** What the Embed button offers: the iframe's title, the view and args as a query, the height it starts at. */
+    readonly embed: Omit<EmbedPanelProps, "storyId">;
+};
+/**
+ * The story bar.
+ *
+ * @param props - the story, the matrix's axes, the actions the story allows, its embed and its frame's address.
+ */
+export declare const StoryBar: ({ story, axisProps, matrixAxes, onMatrixAxesChange, onReplay, clockControls, frameAddress, embed }: StoryBarProps) => ReactNode;

package/dist/src/shell/StoryBar.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ClockControls } from "./ClockControls.js";
+import { EmbedButton } from "./EmbedButton.js";
+import { Icon } from "./icons.js";
+import { MatrixPicker } from "./MatrixPicker.js";
+import { STRINGS } from "./strings.js";
+import { useCopy } from "./useCopy.js";
+/**
+ * Copies the story's id (`kit:inputs-selection-select--overview`), the name tests and tools address it by; the id
+ * shows as the button's tooltip.
+ *
+ * @param props - the story's id.
+ */
+const CopyIdButton = ({ storyId }) => {
+    const { isCopied, copy } = useCopy();
+    return (_jsx("button", { type: "button", className: "forgebook-button forgebook-button--icon", title: `${STRINGS.copyStoryId}: ${storyId}`, "aria-label": isCopied ? STRINGS.copied : STRINGS.copyStoryId, onClick: () => copy(storyId), children: _jsx(Icon, { name: isCopied ? "check" : "hash", size: 14 }) }));
+};
+/**
+ * The story bar.
+ *
+ * @param props - the story, the matrix's axes, the actions the story allows, its embed and its frame's address.
+ */
+export const StoryBar = ({ story, axisProps, matrixAxes, onMatrixAxesChange, onReplay, clockControls, frameAddress, embed }) => (_jsxs("div", { className: "forgebook-story__bar", children: [_jsxs("div", { className: "forgebook-stage__heading", children: [_jsx("h2", { className: "forgebook-stage__title", children: story.name }), story.description === undefined ? null : (_jsx("p", { className: "forgebook-stage__description", title: story.description, children: story.description }))] }), axisProps.length === 0 ? null : (_jsx(MatrixPicker, { props: axisProps, axes: matrixAxes, onAxesChange: onMatrixAxesChange })), onReplay === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-button", onClick: onReplay, children: [_jsx(Icon, { name: "replay", size: 14 }), STRINGS.replay] })), clockControls === undefined ? null : _jsx(ClockControls, { controls: clockControls }), _jsx(CopyIdButton, { storyId: story.id }), _jsx(EmbedButton, { storyId: story.id, ...embed }), _jsx("a", { className: "forgebook-button forgebook-button--icon", href: frameAddress, target: "_blank", rel: "noopener", title: STRINGS.openFrame, "aria-label": STRINGS.openFrame, children: _jsx(Icon, { name: "external", size: 14 }) })] }));

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

@@ -14,7 +14,7 @@ export type StoryCodeSource = {
     readonly code: StoryFileCode;
     /** The story's export name. */
     readonly exportName: string;
-    /** The component's name, for the code of a story drawn from its args. */
+    /** The component's name as code writes it (`codeNameOf`), for the code of a story drawn from its args. */
     readonly componentName: string;
     /** The values of the moment: the story's args, with the panel's over them on the story page. */
     readonly args: PanelArgs;
@@ -32,4 +32,3 @@ export declare const storyCodeText: ({ code, exportName, componentName, args }:
  * @param props - the file's code, the story, the component's name and the args.
  */
 export declare const StoryCodeBlock: (source: StoryCodeSource) => ReactNode;
-//# sourceMappingURL=StoryCodeBlock.d.ts.map

package/dist/src/shell/StoryCodeBlock.js

@@ -24,4 +24,3 @@ export const StoryCodeBlock = (source) => {
     // the attributes' names are names, not types: only the component's name is coloured as one
     return (_jsx("pre", { className: "forgebook-code-block", children: _jsx(Code, { text: storyCodeText(source, write), names: Object.keys(source.args) }) }));
 };
-//# sourceMappingURL=StoryCodeBlock.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * What a component's stories cover, for whoever tests it: each story in the page's order, what it shows, its group, its
+ * play function, whether the generated tests run it, and its accessibility check once asked for.
+ *
+ * @remarks
+ * Part of the audiences' chunk. The table reads the index only, so it costs no frame. The check is asked for by a
+ * person, never by itself: axe downloads with the first one, and the page's far frames load for it through the queue. A
+ * frame already there is asked at once; one that is not gets asked by its ready message, since a message sent to a
+ * document still loading is lost. The details of a broken rule stay on the story's page, in its Accessibility tab.
+ *
+ * @module
+ */
+import { type ReactNode, type RefObject } from "react";
+import { type StoryGroupSetting } from "../catalogue.ts";
+import { type TreeStory } from "../storyTree.ts";
+import { type ExampleContext } from "./Example.tsx";
+import type { FrameQueue } from "./useFrameQueue.ts";
+/** The section's props. */
+export type StoryCoverageProps = Pick<ExampleContext, "hrefOf" | "onOpen"> & {
+    /** The component's stories, as the page lists them. */
+    readonly stories: readonly TreeStory[];
+    /** The groups the catalogue names, in their order. */
+    readonly storyGroups: readonly StoryGroupSetting[];
+    /** The page's frames' queue, which loads them for a check. */
+    readonly queue: Pick<FrameQueue, "loadAll">;
+    /** The element that holds the page's frames. */
+    readonly pageRef: RefObject<HTMLElement | null>;
+    /** The addresses of the page's frames that finished loading. */
+    readonly settled: ReadonlySet<string>;
+};
+/**
+ * What the stories cover.
+ *
+ * @param props - the stories, how they group and open, and the page's frames.
+ */
+export declare const StoryCoverage: ({ stories, storyGroups, queue, pageRef, settled, hrefOf, onOpen }: StoryCoverageProps) => ReactNode;