forgebook 0.1.8 → 0.3.0

package/dist/src/shell/StoryCoverage.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { useRef, useState } from "react";
+import { groupLabel } from "../catalogue.js";
+import { groupedStories } from "../storyTree.js";
+import { AUDIENCE_TEXTS } from "./audiencePage.js";
+import { CodeText } from "./CodeText.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { StoryLink } from "./Example.js";
+import { framesOrigin } from "./framesOrigin.js";
+import { a11yHint } from "./tabSummaries.js";
+import { useFrameMessages } from "./useFrameMessages.js";
+/**
+ * What a frame of the page said of its story; a frame that settled before the section listened is taken as shown, and
+ * one that failed then never answers.
+ *
+ * @param said - what each frame said, by story.
+ * @param settled - the addresses of the frames that finished loading.
+ * @param storyId - the frame's story.
+ * @param address - the frame's address.
+ */
+const frameState = (said, settled, storyId, address) => said.get(storyId) ?? (settled.has(address) ? "ready" : undefined);
+/**
+ * The checks of a page's stories.
+ *
+ * @remarks
+ * A frame on the frames' own origin keeps its document from the shell, so what each one says of its story is kept
+ * from its messages, and from the page's frames that settled before this section was drawn.
+ *
+ * @param pageRef - the element that holds the page's frames.
+ * @param queue - the page's frames' queue.
+ * @param settled - the addresses of the page's frames that finished loading.
+ */
+const usePageChecks = (pageRef, queue, settled) => {
+    const [checks, setChecks] = useState(new Map());
+    const isAsked = useRef(false);
+    // read by a frame's ready message, which may repeat: a second run of axe in a document refuses to start
+    const running = useRef(new Set());
+    // what each frame said of its story, by story: shown, or failed
+    const said = useRef(new Map());
+    const setCheck = (storyId, check) => setChecks((current) => new Map(current).set(storyId, check));
+    const ask = (frame, storyId) => {
+        if (running.current.has(storyId))
+            return;
+        running.current.add(storyId);
+        setCheck(storyId, { status: "running" });
+        const message = { type: "forgebook:check" };
+        frame.postMessage(message, framesOrigin());
+    };
+    useFrameMessages({
+        onReady: (frame, { storyId }) => {
+            said.current.set(storyId, "ready");
+            if (isAsked.current)
+                ask(frame, storyId);
+        },
+        onCall: () => undefined,
+        onFailed: (storyId) => {
+            said.current.set(storyId, "error");
+            if (isAsked.current)
+                setCheck(storyId, { status: "error", message: AUDIENCE_TEXTS.coverageFailed });
+        },
+        onChecked: (result) => {
+            // a check asked for before the view changed answers for a view no longer shown
+            if (!running.current.delete(result.storyId))
+                return;
+            setCheck(result.storyId, "error" in result
+                ? { status: "error", message: result.error }
+                : { status: "done", violations: result.violations });
+        }
+    });
+    const checkAll = () => {
+        isAsked.current = true;
+        queue.loadAll();
+        for (const frame of pageRef.current?.querySelectorAll("iframe") ?? []) {
+            const address = frame.getAttribute("src") ?? "";
+            const storyId = new URL(address, window.location.href).searchParams.get("story");
+            if (storyId === null || frame.contentWindow === null)
+                continue;
+            const state = frameState(said.current, settled, storyId, address);
+            if (state === "ready")
+                ask(frame.contentWindow, storyId);
+            if (state === "error")
+                setCheck(storyId, { status: "error", message: AUDIENCE_TEXTS.coverageFailed });
+        }
+    };
+    return { checks, checkAll };
+};
+/** Whether the generated tests leave a story out. */
+const isUntested = (story) => story.tags.includes("!test");
+/**
+ * A check as a table's cell says it.
+ *
+ * @param check - the story's check; none before it is asked for.
+ */
+const checkText = (check) => {
+    if (check === undefined || check.status === "idle")
+        return AUDIENCE_TEXTS.coverageNotChecked;
+    if (check.status === "running")
+        return AUDIENCE_TEXTS.coverageChecking;
+    if (check.status === "error")
+        return check.message;
+    return a11yHint(check) ?? AUDIENCE_TEXTS.coverageNotChecked;
+};
+/**
+ * What the stories cover.
+ *
+ * @param props - the stories, how they group and open, and the page's frames.
+ */
+export const StoryCoverage = ({ stories, storyGroups, queue, pageRef, settled, hrefOf, onOpen }) => {
+    const { checks, checkAll } = usePageChecks(pageRef, queue, settled);
+    // a catalogue that checks no accessibility has no column for it, nor a check to run
+    const hasA11y = useCatalogue().a11y !== undefined;
+    const ordered = groupedStories(stories, storyGroups.map((group) => group.id)).flatMap((section) => section.stories);
+    const played = stories.filter((story) => story.hasPlay).length;
+    const untested = stories.filter(isUntested).length;
+    const finished = [...checks.values()].filter((check) => check.status !== "running").length;
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-coverage", children: [_jsx("h2", { id: "forgebook-coverage", children: AUDIENCE_TEXTS.coverage }), _jsxs("div", { className: "forgebook-coverage__head", children: [_jsx("p", { className: "forgebook-coverage__summary", children: AUDIENCE_TEXTS.coverageSummary(stories.length, played, untested) }), hasA11y ? (_jsx("button", { type: "button", className: "forgebook-button", onClick: checkAll, children: AUDIENCE_TEXTS.coverageCheckAll })) : null] }), hasA11y ? (_jsx("p", { className: "forgebook-coverage__progress", role: "status", children: checks.size === 0 ? "" : AUDIENCE_TEXTS.coverageChecked(finished, stories.length) })) : null, _jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageStory }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageGroup }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coveragePlay }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageTests }), hasA11y ? _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageA11y }) : null] }) }), _jsx("tbody", { children: ordered.map((story) => (_jsxs("tr", { children: [_jsxs("th", { scope: "row", className: "forgebook-coverage__story", children: [_jsx(StoryLink, { story: story, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: story.name }), story.description === undefined ? null : (_jsx("span", { className: "forgebook-coverage__covers", children: _jsx(CodeText, { text: story.description }) }))] }), _jsx("td", { children: story.group === undefined ? "" : groupLabel(storyGroups, story.group) }), _jsx("td", { children: story.hasPlay ? AUDIENCE_TEXTS.coverageHasPlay : AUDIENCE_TEXTS.coverageNoPlay }), _jsx("td", { children: isUntested(story) ? AUDIENCE_TEXTS.coverageUntested : AUDIENCE_TEXTS.coverageTested }), hasA11y ? _jsx("td", { children: checkText(checks.get(story.id)) }) : null] }, story.id))) })] }) })] }));
+};

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

@@ -23,4 +23,3 @@ export type StoryPickerProps = {
  * @param props - the component, the shown story and how to open a page.
  */
 export declare const StoryPicker: ({ component, currentStoryId, onOpenComponent, onOpenStory }: StoryPickerProps) => ReactNode;
-//# sourceMappingURL=StoryPicker.d.ts.map

package/dist/src/shell/StoryPicker.js

@@ -29,4 +29,3 @@ export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpen
                         onOpenStory(chosen);
                 }, children: [_jsx("option", { value: ALL, children: STRINGS.allStories(component.stories.length) }), sections.map((section) => section.group === undefined ? (section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id)))) : (_jsx("optgroup", { label: groupLabel(storyGroups, section.group), children: section.stories.map((story) => (_jsx("option", { value: story.id, children: story.name }, story.id))) }, section.group)))] })] }));
 };
-//# sourceMappingURL=StoryPicker.js.map

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

@@ -4,12 +4,13 @@
  *
  * @remarks
  * The controls are the catalogue's switches and Forgebook's own (the background, the style sheets, the text size, the
- * stage's width); which start pinned is the catalogue's choice, where each sits is the person's (`toolbarLayout.ts`).
+ * stage's width, the audience); which start pinned is the catalogue's choice, where each sits is the person's (`toolbarLayout.ts`).
  * The panel and Compare belong to the page, not to the view: they stay at the end.
  *
  * @module
  */
 import { type ReactNode } from "react";
+import { type DeviceDefault } from "../deviceView.ts";
 import { type FixedView } from "../storyGlobals.ts";
 import { type ViewState } from "../viewState.ts";
 /** The toolbar's props. */
@@ -20,6 +21,8 @@ export type ToolbarProps = {
     readonly onViewChange: (view: ViewState) => void;
     /** Whether a story's page is shown: the props panel and Compare belong to it, not to a component's page. */
     readonly isStoryPage?: boolean;
+    /** Whether a component's page is shown: the audience changes nothing elsewhere. */
+    readonly isComponentPage?: boolean;
     /** Shows the hidden sidebar; none while it is shown. */
     readonly onShowSidebar?: (() => void) | undefined;
     /** The width the shown story really has, in CSS px, for the width field; none on a component's page. */
@@ -28,6 +31,8 @@ export type ToolbarProps = {
     readonly fixed?: FixedView;
     /** Whether the shown page is about logic (a hook's story or page): the bar puts away what only changes looks. */
     readonly isLogic?: boolean;
+    /** The page's default device: the shown story's, or the catalogue's on a component's page; none by default. */
+    readonly deviceDefault?: DeviceDefault;
 };
 /**
  * The button that shows the hidden sidebar, at the toolbar's start; the home's bar holds only it.
@@ -42,5 +47,4 @@ export declare const ShowSidebarButton: ({ onShowSidebar }: {
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, onShowSidebar, shownWidth, fixed, isLogic }: ToolbarProps) => ReactNode;
-//# sourceMappingURL=Toolbar.d.ts.map
+export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;

package/dist/src/shell/Toolbar.js

@@ -5,12 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * @remarks
  * The controls are the catalogue's switches and Forgebook's own (the background, the style sheets, the text size, the
- * stage's width); which start pinned is the catalogue's choice, where each sits is the person's (`toolbarLayout.ts`).
+ * stage's width, the audience); which start pinned is the catalogue's choice, where each sits is the person's (`toolbarLayout.ts`).
  * The panel and Compare belong to the page, not to the view: they stay at the end.
  *
  * @module
  */
 import { useId, useRef } from "react";
+import { NO_DEVICE } from "../deviceView.js";
 import { NOT_FIXED, withFixed, withOwnFixed } from "../storyGlobals.js";
 import { switchWithRole } from "../switches.js";
 import { hasViewChanges, isComparing } from "../viewState.js";
@@ -78,14 +79,14 @@ export const ShowSidebarButton = ({ onShowSidebar }) => (_jsx("button", { type:
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, onShowSidebar, shownWidth, fixed = NOT_FIXED, isLogic = false }) => {
+export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
     const layout = useToolbarLayout();
     const catalogue = useCatalogue();
     // the story's fixed values are shown, and a change of anything else keeps the user's own in the address
     const view = withFixed(ownView, fixed);
     const onViewChange = (changed) => onOwnViewChange(withOwnFixed(changed, ownView, fixed));
-    const context = { view, onViewChange, isStoryPage, fixed, shownWidth };
-    useControlKeys({ keys: layout.keys, view, onViewChange, fixed, isStoryPage });
+    const context = { view, onViewChange, isStoryPage, isComponentPage, fixed, shownWidth, deviceDefault };
+    useControlKeys({ keys: layout.keys, view, onViewChange, fixed, isStoryPage, isComponentPage });
     const pinnedRef = useRef(null);
     // a page about logic puts away the pinned controls that only change looks: the View menu then counts them
     const putAway = layout.placed
@@ -95,6 +96,5 @@ export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryP
     const moved = useToolbarOverflow(pinnedRef, pinned.map((each) => each.control.id));
     // a bar that wraps has room for every pinned control
     const onBar = layout.isWrapped ? pinned : pinned.filter((each) => !moved.includes(each.control.id));
-    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : _jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar }), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id]), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
+    return (_jsxs("div", { className: layout.isWrapped ? "forgebook-toolbar forgebook-toolbar--wrap" : "forgebook-toolbar", children: [onShowSidebar === undefined ? null : _jsx(ShowSidebarButton, { onShowSidebar: onShowSidebar }), _jsx(ViewMenu, { layout: layout, ownView: ownView, movedIds: [...(layout.isWrapped ? [] : moved), ...putAway], ...context }), onBar.length === 0 ? null : _jsx("span", { className: "forgebook-toolbar__divider" }), _jsx("div", { ref: pinnedRef, className: "forgebook-toolbar__pinned-list", children: onBar.map((each) => (_jsx(PinnedControl, { control: each.control, isHidden: each.isHidden, isChanged: hasViewChanges(ownView, catalogue.switches, [each.control.id], catalogue.audience), layout: layout, ...context }, each.control.id))) }), _jsxs("button", { type: "button", className: "forgebook-button", title: STRINGS.panel, "aria-pressed": view.isPanelOpen, disabled: !isStoryPage, onClick: () => onViewChange({ ...view, isPanelOpen: !view.isPanelOpen }), children: [_jsx(Icon, { name: "panel", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.panel })] }), isLogic ? null : (_jsx(CompareMenu, { view: view, onViewChange: onViewChange, isDisabled: !isStoryPage, fixed: fixed }))] }));
 };
-//# sourceMappingURL=Toolbar.js.map

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

@@ -1,6 +1,6 @@
 /**
  * One control of the toolbar or the View menu, wherever the person placed it: a switch the catalogue declares, or one
- * of Forgebook's own (the background, the style sheets, the text size, the stage's width), drawn for the toolbar or for
+ * of Forgebook's own (the background, the style sheets, the text size, the stage's width, the audience), drawn for the toolbar or for
  * a row of the View menu; off while the compare view sets it or the story fixes it.
  *
  * @remarks
@@ -11,6 +11,7 @@
  * @module
  */
 import { type ReactNode } from "react";
+import { type DeviceDefault } from "../deviceView.ts";
 import type { FixedView } from "../storyGlobals.ts";
 import type { ToolbarControl as Control } from "../toolbarLayout.ts";
 import { type ViewState } from "../viewState.ts";
@@ -24,17 +25,15 @@ export type ControlContext = {
     readonly onViewChange: (view: ViewState) => void;
     /** Whether a story's page is shown: the compare view sets values there, never on a component's page. */
     readonly isStoryPage: boolean;
+    /** Whether a component's page is shown: the only page the audience changes. */
+    readonly isComponentPage: boolean;
     /** What the shown story fixes of the view. */
     readonly fixed: FixedView;
     /** The width the shown story really has, in CSS px, for the width field; none on a component's page. */
     readonly shownWidth: number | undefined;
+    /** The page's default device: the shown story's, or the catalogue's on a component's page. */
+    readonly deviceDefault: DeviceDefault;
 };
-/**
- * A control's name, as its row, its menu and its buttons' names write it.
- *
- * @param control - the control.
- */
-export declare const controlLabel: (control: Control) => string;
 /**
  * One control, drawn for where it sits.
  *
@@ -44,4 +43,3 @@ export declare const ToolbarControl: ({ control, form, ...context }: ControlCont
     readonly control: Control;
     readonly form: ControlForm;
 }) => ReactNode;
-//# sourceMappingURL=ToolbarControl.d.ts.map

package/dist/src/shell/ToolbarControl.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * One control of the toolbar or the View menu, wherever the person placed it: a switch the catalogue declares, or one
- * of Forgebook's own (the background, the style sheets, the text size, the stage's width), drawn for the toolbar or for
+ * of Forgebook's own (the background, the style sheets, the text size, the stage's width, the audience), drawn for the toolbar or for
  * a row of the View menu; off while the compare view sets it or the story fixes it.
  *
  * @remarks
@@ -12,9 +12,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @module
  */
 import { useId } from "react";
+import { AUDIENCE_IDS } from "../audiences.js";
+import { DEVICE_PARAMETER, shownDevice } from "../deviceView.js";
 import { switchControl } from "../switches.js";
 import { isComparing, PLAIN_BACKDROP, SHEETS_CHOICES } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
+import { DeviceControl } from "./DeviceControl.js";
 import { Icon } from "./icons.js";
 import { Segmented } from "./Segmented.js";
 import { STRINGS } from "./strings.js";
@@ -36,19 +39,6 @@ const COMPACT_VALUES = 3;
  * @param labels - the values' names.
  */
 const isCompact = (labels) => labels.length <= COMPACT_VALUES && labels.join("").length <= COMPACT_LETTERS;
-/** The name of each of Forgebook's own controls. */
-const OWN_LABELS = {
-    backdrop: () => STRINGS.backdrop,
-    sheets: () => STRINGS.sheets,
-    text: () => STRINGS.text,
-    width: () => STRINGS.width
-};
-/**
- * A control's name, as its row, its menu and its buttons' names write it.
- *
- * @param control - the control.
- */
-export const controlLabel = (control) => control.kind === "switch" ? control.switch.label : OWN_LABELS[control.id]();
 /**
  * A choice as a native list: the platform's keys and screen reader support, for values too many or too long for
  * segments.
@@ -100,24 +90,36 @@ const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed }) =
     return (_jsx(FormChoice, { form: form, isList: switchControl(each) === "list", label: each.label, options: each.values.map((option) => ({ value: option.value, label: option.label })), value: value, onValueChange: choose, isDisabled: isDisabled, disabledNote: disabledNote }));
 };
 /**
- * The stage's width: its presets as segments, closed by the field that takes any width.
+ * The stage's width: its presets as segments, closed by the field that takes any width; off while a device sets it.
  *
  * @param props - its form and what every control shares.
  */
-const WidthControl = ({ form, view, onViewChange, isStoryPage, fixed, shownWidth }) => {
+const WidthControl = ({ form, view, onViewChange, isStoryPage, fixed, shownWidth, deviceDefault }) => {
     const { widths } = useCatalogue();
     const setWidth = (width) => onViewChange({ ...view, width });
-    const presets = (_jsx(Segmented, { label: STRINGS.width, isDisabled: (isStoryPage && isComparing(view)) || fixed.width !== undefined, disabledNote: fixed.width === undefined ? undefined : STRINGS.setByStory, options: [
+    const note = widthNote(shownDevice(view, deviceDefault) !== undefined, fixed);
+    const presets = (_jsx(Segmented, { label: STRINGS.width, isDisabled: (isStoryPage && isComparing(view)) || note !== undefined, disabledNote: note, options: [
             { value: "fill", label: STRINGS.widthFill },
             ...widths.map((preset) => ({
                 value: preset.width,
                 label: preset.label ?? STRINGS.widthPx(preset.width)
             }))
-        ], value: view.width, onValueChange: setWidth, after: _jsx(WidthField, { width: view.width, shownWidth: shownWidth, onWidthChange: setWidth }) }));
+        ], value: view.width, onValueChange: setWidth, after: _jsx(WidthField, { width: view.width, shownWidth: shownWidth, onWidthChange: setWidth, disabledNote: note }) }));
     if (form === "row")
         return presets;
     return (_jsxs("div", { className: "forgebook-toolbar__width", children: [_jsx("span", { className: "forgebook-toolbar__icon", title: STRINGS.width, children: _jsx(Icon, { name: "width", size: 14 }) }), presets] }));
 };
+/**
+ * Why the width cannot be set, or none: a device shown sets it, then a story that fixes it.
+ *
+ * @param isFramed - whether a device is shown.
+ * @param fixed - what the story fixes.
+ */
+const widthNote = (isFramed, fixed) => {
+    if (isFramed)
+        return STRINGS.setByDevice;
+    return fixed.width === undefined ? undefined : STRINGS.setByStory;
+};
 /**
  * One of Forgebook's own controls.
  *
@@ -125,9 +127,16 @@ const WidthControl = ({ form, view, onViewChange, isStoryPage, fixed, shownWidth
  */
 const OwnControl = ({ id, form, ...context }) => {
     const catalogue = useCatalogue();
-    const { view, onViewChange, isStoryPage, fixed } = context;
+    const { view, onViewChange, isStoryPage, isComponentPage, fixed } = context;
     if (id === "width")
         return _jsx(WidthControl, { form: form, ...context });
+    if (id === "audience") {
+        return (_jsx(FormChoice, { form: form, 
+            // its names are too long for segments, and a list stays quiet on the bar
+            isList: true, label: STRINGS.audience, options: AUDIENCE_IDS.map((audience) => ({ value: audience, label: STRINGS.audiences[audience] })), value: view.audience, onValueChange: (audience) => onViewChange({ ...view, audience }), isDisabled: !isComponentPage, disabledNote: isComponentPage ? undefined : STRINGS.audienceElsewhere }));
+    }
+    if (id === DEVICE_PARAMETER)
+        return (_jsx(DeviceControl, { form: form, view: view, onViewChange: onViewChange, defaults: context.deviceDefault }));
     if (id === "backdrop") {
         return (_jsx(FormChoice, { form: form, 
             // its names are too long for segments
@@ -147,4 +156,3 @@ const OwnControl = ({ id, form, ...context }) => {
  * @param props - the control, its form, and what every control shares.
  */
 export const ToolbarControl = ({ control, form, ...context }) => control.kind === "switch" ? (_jsx(SwitchControl, { each: control.switch, form: form, ...context })) : (_jsx(OwnControl, { id: control.id, form: form, ...context }));
-//# sourceMappingURL=ToolbarControl.js.map

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

@@ -10,15 +10,15 @@
  *
  * @module
  */
+import type { StorySource } from "@forgebook/story-format/source";
 import { type ReactNode } from "react";
 import type { TreeComponent, TreeStory } from "../storyTree.ts";
-import { type UsageIndex } from "../usedIn.ts";
 /** What the block reads and opens. */
 export type UsedInProps = {
     /** The page's component's title. */
     readonly title: string;
-    /** Loads the source's usage. */
-    readonly load: () => Promise<UsageIndex | string>;
+    /** The page's source, whose usage the block reads (`usageLoader`). */
+    readonly source: StorySource;
     /** A component of the source, by its title; none when the tree no longer has it. */
     readonly componentOf: (title: string) => TreeComponent | undefined;
     /** The address of a component's page. */
@@ -33,7 +33,6 @@ export type UsedInProps = {
 /**
  * The block.
  *
- * @param props - the page's component, the usage's loader and how pages open.
+ * @param props - the page's component, its source and how pages open.
  */
-export declare const UsedIn: ({ title, load, componentOf, ...links }: UsedInProps) => ReactNode;
-//# sourceMappingURL=UsedIn.d.ts.map
+export declare const UsedIn: ({ title, source, componentOf, ...links }: UsedInProps) => ReactNode;

package/dist/src/shell/UsedIn.js

@@ -1,20 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-/**
- * "Used in" on a component's page: the other components of its source whose stories use it, each linking to its page
- * with the stories that use it, direct users first; a reader folds it away and their browser keeps that.
- *
- * @remarks
- * The block shows only when another component's stories use the component: an empty "Used in" says nothing, so the
- * usage is loaded with the page (once per source, then kept) and the block waits until it is known. Twelve components
- * show at first, then "and N more" shows the rest. A component used only through another (Tree renders Row, Row
- * renders it) says so.
- *
- * @module
- */
 import { useId, useState } from "react";
-import { isUsageIndex, USED_IN_SHOWN } from "../usedIn.js";
+import { isUsageIndex, USED_IN_SHOWN, usageLoader } from "../usedIn.js";
 import { Icon } from "./icons.js";
-import { STRINGS } from "./strings.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { useFold } from "./useFold.js";
 import { useLoaded } from "./useLoaded.js";
 import { useStored } from "./useStored.js";
@@ -50,7 +38,7 @@ const PageLink = ({ href, onOpen, className, children }) => (_jsx("a", { classNa
 const UserList = ({ users, ...links }) => {
     const [isAll, setIsAll] = useState(false);
     const shown = isAll ? users : users.slice(0, USED_IN_SHOWN);
-    return (_jsxs(_Fragment, { children: [_jsx("ul", { className: "forgebook-used-in__list", children: shown.map((user) => (_jsxs("li", { className: "forgebook-used-in__user", children: [_jsx(PageLink, { href: links.componentHrefOf(user.component), onOpen: () => links.onOpenComponent(user.component), className: "forgebook-link forgebook-used-in__component", children: user.component.name }), _jsx("span", { className: "forgebook-used-in__note", children: user.isDirect ? STRINGS.usedInStories(user.stories.length) : STRINGS.usedInThrough }), _jsx("span", { className: "forgebook-used-in__stories", children: user.stories.map((story) => (_jsx(PageLink, { href: links.storyHrefOf(story), onOpen: () => links.onOpenStory(story), className: "forgebook-used-in__story", children: story.name }, story.id))) })] }, user.component.title))) }), isAll || users.length <= USED_IN_SHOWN ? null : (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => setIsAll(true), children: STRINGS.usedInMore(users.length - USED_IN_SHOWN) }))] }));
+    return (_jsxs(_Fragment, { children: [_jsx("ul", { className: "forgebook-used-in__list", children: shown.map((user) => (_jsxs("li", { className: "forgebook-used-in__user", children: [_jsx(PageLink, { href: links.componentHrefOf(user.component), onOpen: () => links.onOpenComponent(user.component), className: "forgebook-link forgebook-used-in__component", children: user.component.name }), _jsx("span", { className: "forgebook-used-in__note", children: user.isDirect ? LATER_STRINGS.usedInStories(user.stories.length) : LATER_STRINGS.usedInThrough }), _jsx("span", { className: "forgebook-used-in__stories", children: user.stories.map((story) => (_jsx(PageLink, { href: links.storyHrefOf(story), onOpen: () => links.onOpenStory(story), className: "forgebook-used-in__story", children: story.name }, story.id))) })] }, user.component.title))) }), isAll || users.length <= USED_IN_SHOWN ? null : (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => setIsAll(true), children: LATER_STRINGS.usedInMore(users.length - USED_IN_SHOWN) }))] }));
 };
 /** What the source's usage answered, as a state. */
 const usageState = (value) => {
@@ -63,19 +51,18 @@ const usageState = (value) => {
 /**
  * The block.
  *
- * @param props - the page's component, the usage's loader and how pages open.
+ * @param props - the page's component, its source and how pages open.
  */
-export const UsedIn = ({ title, load, componentOf, ...links }) => {
+export const UsedIn = ({ title, source, componentOf, ...links }) => {
     const [isOpen, setIsOpen] = useStored("used-in", (stored) => stored !== "closed", (open) => (open ? "open" : "closed"));
     // read even while folded: a component no other story uses gets no block at all, and the block waits until that is
     // known, so it never shows to go away again
-    const usage = useLoaded(load, usageState);
+    const usage = useLoaded(usageLoader(source), usageState);
     const fold = useFold(isOpen, false);
     const headingId = useId();
     const bodyId = useId();
     const users = usage.status === "ready" ? shownUsers(usage.value[title] ?? [], componentOf) : [];
     if (usage.status === "loading" || (usage.status === "ready" && users.length === 0))
         return null;
-    return (_jsxs("section", { className: "forgebook-doc__section forgebook-used-in", "aria-labelledby": headingId, children: [_jsx("h2", { id: headingId, className: "forgebook-used-in__heading", children: _jsxs("button", { type: "button", className: "forgebook-used-in__toggle", "aria-expanded": isOpen, "aria-controls": bodyId, onClick: () => setIsOpen(!isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 14 }) }), STRINGS.usedIn] }) }), _jsx("div", { ref: fold.ref, id: bodyId, className: "forgebook-used-in__body", children: fold.isDrawn ? (_jsxs(_Fragment, { children: [usage.status === "error" ? _jsx("p", { className: "forgebook-used-in__note", children: usage.message }) : null, usage.status === "ready" ? _jsx(UserList, { users: users, ...links }) : null] })) : null })] }));
+    return (_jsxs("section", { className: "forgebook-doc__section forgebook-used-in", "aria-labelledby": headingId, children: [_jsx("h2", { id: headingId, className: "forgebook-used-in__heading", children: _jsxs("button", { type: "button", className: "forgebook-used-in__toggle", "aria-expanded": isOpen, "aria-controls": bodyId, onClick: () => setIsOpen(!isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 14 }) }), LATER_STRINGS.usedIn] }) }), _jsx("div", { ref: fold.ref, id: bodyId, className: "forgebook-used-in__body", children: fold.isDrawn ? (_jsxs(_Fragment, { children: [usage.status === "error" ? _jsx("p", { className: "forgebook-used-in__note", children: usage.message }) : null, usage.status === "ready" ? _jsx(UserList, { users: users, ...links }) : null] })) : null })] }));
 };
-//# sourceMappingURL=UsedIn.js.map

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

@@ -1,12 +1,13 @@
 /**
- * The View menu: every control the person did not hide in it, in their order, each with its value, a handle to move
- * it, a pin that puts it on the toolbar and a button that hides it here (a pinned one stays on the toolbar); at its
- * foot the hidden controls, the wrap choice, the values' reset and the toolbar's reset.
+ * The View menu: its button, with a dot when one of its values is changed, and its panel (`ViewMenuPanel`): every
+ * control the person did not hide in it, in their order, each with its value, a handle to move it, a pin that puts it
+ * on the toolbar and a button that hides it here (a pinned one stays on the toolbar); at its foot the hidden controls,
+ * the wrap choice, the values' reset and the toolbar's reset.
  *
  * @remarks
- * The order is set here only, and the toolbar shows the pinned controls in it: nothing is dragged on the toolbar. A row
- * follows the pointer one to one while it is dragged, and the others move out of its way animated; with the keyboard,
- * the handle moves its row with the arrow keys and the new position is announced.
+ * The button is on every page and the panel only once asked for, so the panel's module loads the first time the menu
+ * opens, fetched already when the pointer comes over the button or the focus reaches it. The popover opens at once as
+ * before, and its content is drawn as soon as the module is there, the focus then going to its chosen option.
  *
  * @module
  */
@@ -36,4 +37,3 @@ export declare const ViewMenu: ({ layout, ownView, movedIds, ...context }: Contr
     /** The person's own view, without what the story fixes: a value the story fixes is not a change of theirs. */
     readonly ownView: ViewState;
 }) => ReactNode;
-//# sourceMappingURL=ViewMenu.d.ts.map