forgebook 0.3.2 → 0.4.0

package/dist/src/shell/Stage.js

@@ -12,11 +12,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * @module
  */
 import { useEffect, useMemo, useRef, useState } from "react";
+import { checkedArgsMessage } from "../addressArgs.js";
 import { panelProps, settableProps } from "../argTypes.js";
 import { matrixOf, matrixProps } from "../matrix.js";
-import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
 import { withFixed, withOwnFixed } from "../storyGlobals.js";
-import { frameAddress, isComparing, liveView, schemeOf, viewParams } from "../viewState.js";
+import { shownSwitches } from "../switches.js";
+import { frameAddress, isComparing, liveView, schemeOf } from "../viewState.js";
 import { useStoryClockControls } from "./ClockControls.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { DeviceSlot, deviceAddress, isWaitingForDevice, roomSizing, useInkScheme, useStageDevice } from "./DeviceSlot.js";
@@ -30,6 +31,7 @@ import { StageCompare } from "./StageCompare.js";
 import { StageTools } from "./StageTools.js";
 import { StageViewport } from "./StageViewport.js";
 import { StoryBar } from "./StoryBar.js";
+import { embedHeight, embedQuery, takesArgs, usePanelValues } from "./stageArgs.js";
 import { STRINGS } from "./strings.js";
 import { useAddressArgs } from "./useAddressArgs.js";
 import { useFrameMessages } from "./useFrameMessages.js";
@@ -52,42 +54,16 @@ const widthSetter = (fixed, view, onViewChange) => fixed.width === undefined ? (
 const INITIAL_FRAME_HEIGHT = 240;
 /** The most calls the Events tab keeps. */
 const MAX_CALLS = 50;
-/**
- * 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 story - the story.
- */
-const takesArgs = (story) => !story.isLogic && (story.controls === "all" || story.controls.length > 0);
-/**
- * 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 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 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;
+/** No args of the story's own, as one value: what is computed from them is kept while it stays the same. */
+const NO_OWN_ARGS = {};
+/** A story's own args, as its frame reported them; none before it did. */
+const ownArgsOf = (reported, storyId) => reported.get(storyId) ?? NO_OWN_ARGS;
 /**
  * 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, plugins, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }) => {
+export const Stage = ({ component, story, view: ownView, onViewChange: onOwnViewChange, onFixedChange, loadTokens, argControls, panelArgs, addressLink, onPanelArgsChange, matrixAxes, onMatrixAxesChange, frameUrl, plugins, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }) => {
     const frameRef = useRef(null);
     const storyRef = useRef(null);
     const code = useStoryCode(loadCode);
@@ -122,24 +98,31 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         null, [docs, matrixAxes, story.isLogic]);
     // the address's values reach the frames only once checked against what the story declares
     const addressArgs = useAddressArgs({
+        argControls,
         panelArgs,
+        link: addressLink,
         docs,
         storyArgs: storyArgs.get(story.id),
         argTypes: panel.argTypes,
         controls: panel.controls,
-        namedValues
+        namedValues,
+        frames: storyRef
     });
     const acceptedArgs = addressArgs.accepted;
-    const values = { ...storyArgs.get(story.id), ...acceptedArgs };
+    const ownArgs = ownArgsOf(storyArgs, story.id);
+    const panelValues = usePanelValues(acceptedArgs, ownArgs, onPanelArgsChange);
+    const { values } = panelValues;
     const settable = useMemo(() => docs.status === "ready"
-        ? settableProps(panelProps(docs.value.props, panel.argTypes), panel.controls, namedValues ?? {})
-        : [], [docs, panel.argTypes, panel.controls, namedValues]);
+        ? settableProps(panelProps(docs.value.props, panel.argTypes, ownArgs), panel.controls, namedValues ?? {})
+        : [], [docs, panel.argTypes, panel.controls, namedValues, ownArgs]);
     const worstCase = useWorstCase({
         storyRef,
         storyId: story.id,
         settable,
         values,
         panelArgs: acceptedArgs,
+        namedValues,
+        worstOfShape: addressArgs.worstOfShape,
         onPanelArgsChange
     });
     const clockControls = useStoryClockControls(frameRef, story.id);
@@ -160,7 +143,7 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
             // 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(checkedArgsMessage(accepted));
             send({ type: "forgebook:matrix", matrix });
             // the view may have changed while the frame loaded
             if (!isComparing(view))
@@ -186,19 +169,6 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     // 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; 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 } = acceptedArgs;
-        onPanelArgsChange(value === undefined ? rest : { ...rest, [name]: value });
-    };
     const replay = () => {
         const message = { type: "forgebook:replay" };
         frameRef.current?.contentWindow?.postMessage(message, framesOrigin());
@@ -211,7 +181,7 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     // among them) is sent live
     // 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);
+    const address = deviceAddress(frameAddress(frameUrl, story.id, useLoadedView(`${story.id}|${view.sheets}|${view.play}`, view), switches), framed);
     useLiveView(storyRef, view, !isComparing(view));
     useScrollMemory(storyRef, scroll);
     const ink = useInkScheme(schemeOf(view, switches));
@@ -235,7 +205,8 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
             address: deviceAddress(frameAddress(frameUrl, story.id, view, switches), framed),
             width: framed?.area.width ?? view.width,
             background: backgroundOf(view),
-            args: panelArgs,
+            // as the stage's frames receive them: an aside asked for while the check waits for the docs is told when it ends
+            args: addressArgs.checked,
             view: liveView(view)
         }
     });
@@ -249,7 +220,12 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         controls: panel.controls,
         actions: panel.actions,
         values,
-        onValueChange: changeValue,
+        panelArgs: acceptedArgs,
+        storyArgs: ownArgs,
+        loadTokens,
+        argControls,
+        globals: shownSwitches(view.switches, switches),
+        onValueChange: panelValues.change,
         onReset: () => onPanelArgsChange({}),
         worstCase: worstCase.state,
         namedValues,
@@ -261,17 +237,16 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         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, framesOrigin());
-        },
+        view,
+        onViewChange,
+        onPlayStep: (command) => tellFrames(storyRef.current, { type: "forgebook:play-step", command }),
         check: storyCheck.check,
         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: [_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),
+                                        query: embedQuery(ownView, acceptedArgs, 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,
@@ -280,5 +255,5 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
                                         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] }));
+                                    }), children: (fixedHeight) => (_jsx(DeviceSlot, { framed: framed, scheme: ink, background: backgroundOf(view), children: isWaitingForDevice(shown, framed) ? null : (_jsx(FrameView, { frame: 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] }));
 };

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

@@ -0,0 +1,54 @@
+/**
+ * The statuses' badges: in a component's entry of the sidebar, at the top of its page, beside a story's example that
+ * holds a status of its own, and in the tag filter's list.
+ * Loaded with the tag filter (`TagViews.tsx`), only for a catalogue whose stories have tags.
+ *
+ * @remarks
+ * A badge says its status in words, so its colour is never the only sign; a hidden word before the badges tells a
+ * screen reader what they are. A page whose component is `@deprecated` in its TSDoc shows the `deprecated` badge even
+ * when its meta has no such tag, with the TSDoc's reason in its tooltip, so the page never says less than the docs.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import { type CatalogueStatus } from "../storyStatuses.ts";
+import type { TreeComponent } from "../storyTree.ts";
+import "./statusBadges.scss";
+/**
+ * A status's text: the catalogue's label, else Forgebook's word for a default status, else its tag.
+ *
+ * @param status - the status.
+ */
+export declare const statusLabel: (status: CatalogueStatus) => string;
+/**
+ * One badge.
+ *
+ * @param props - the status, and the tooltip it carries when there is more to say.
+ */
+export declare const StatusBadge: ({ status, hint }: {
+    readonly status: CatalogueStatus;
+    readonly hint?: string | undefined;
+}) => ReactNode;
+/**
+ * The catalogue's statuses, their defaults filled in, once per declaration.
+ */
+export declare const useStatuses: () => readonly CatalogueStatus[];
+/**
+ * The badges of the statuses a list of tags holds; nothing for none.
+ *
+ * @param props - the tags, and the row's class.
+ */
+export declare const StatusBadges: ({ tags, className }: {
+    readonly tags: readonly string[];
+    readonly className: string;
+}) => ReactNode;
+/**
+ * The badges at the top of a component's page: its meta's statuses, and `deprecated` when its TSDoc says so, with the
+ * TSDoc's reason in that badge's tooltip.
+ *
+ * @param props - the component and its docs loader.
+ */
+export declare const ComponentBadges: ({ component, loadDocs }: {
+    readonly component: TreeComponent;
+    readonly loadDocs: (() => Promise<unknown>) | undefined;
+}) => ReactNode;

package/dist/src/shell/StatusBadges.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The statuses' badges: in a component's entry of the sidebar, at the top of its page, beside a story's example that
+ * holds a status of its own, and in the tag filter's list.
+ * Loaded with the tag filter (`TagViews.tsx`), only for a catalogue whose stories have tags.
+ *
+ * @remarks
+ * A badge says its status in words, so its colour is never the only sign; a hidden word before the badges tells a
+ * screen reader what they are. A page whose component is `@deprecated` in its TSDoc shows the `deprecated` badge even
+ * when its meta has no such tag, with the TSDoc's reason in its tooltip, so the page never says less than the docs.
+ *
+ * @module
+ */
+import { useMemo } from "react";
+import { catalogueStatuses, DEPRECATED_STATUS, statusesOf } from "../storyStatuses.js";
+import "./statusBadges.css";
+import { useCatalogue } from "./catalogueContext.js";
+import { textsOfGroup } from "./strings.js";
+import { useComponentDocs } from "./useComponentDocs.js";
+/** The badges' texts, as shown: Forgebook's, with the catalogue's replacements (`strings: { "statuses.review": … }`). */
+const STATUS_TEXTS = textsOfGroup("statuses", {
+    status: "Status",
+    review: "Review",
+    experimental: "Experimental",
+    deprecated: "Deprecated",
+    fromDocs: (reason) => `Deprecated in its TSDoc: ${reason}`
+});
+/**
+ * A status's text: the catalogue's label, else Forgebook's word for a default status, else its tag.
+ *
+ * @param status - the status.
+ */
+export const statusLabel = (status) => {
+    if (status.label !== undefined)
+        return status.label;
+    if (status.id === "review" || status.id === "experimental" || status.id === "deprecated")
+        return STATUS_TEXTS[status.id];
+    return status.id;
+};
+/**
+ * One badge.
+ *
+ * @param props - the status, and the tooltip it carries when there is more to say.
+ */
+export const StatusBadge = ({ status, hint }) => (_jsx("span", { className: "forgebook-status", "data-tone": status.tone, title: hint ?? statusLabel(status), children: statusLabel(status) }));
+/**
+ * A row of badges, with the hidden word that says what they are; nothing for none.
+ *
+ * @param props - the statuses, the tooltip of each by id, and the row's class.
+ */
+const Badges = ({ statuses, hints, className }) => statuses.length === 0 ? null : (_jsxs("span", { className: className, children: [_jsxs("span", { className: "forgebook-visually-hidden", children: [STATUS_TEXTS.status, ": "] }), statuses.map((status) => (_jsx(StatusBadge, { status: status, hint: hints?.[status.id] }, status.id)))] }));
+/**
+ * The catalogue's statuses, their defaults filled in, once per declaration.
+ */
+export const useStatuses = () => {
+    const { statuses } = useCatalogue();
+    return useMemo(() => catalogueStatuses(statuses), [statuses]);
+};
+/**
+ * The badges of the statuses a list of tags holds; nothing for none.
+ *
+ * @param props - the tags, and the row's class.
+ */
+export const StatusBadges = ({ tags, className }) => _jsx(Badges, { className: className, statuses: statusesOf(tags, useStatuses()) });
+/**
+ * The badges at the top of a component's page: its meta's statuses, and `deprecated` when its TSDoc says so, with the
+ * TSDoc's reason in that badge's tooltip.
+ *
+ * @param props - the component and its docs loader.
+ */
+export const ComponentBadges = ({ component, loadDocs }) => {
+    const statuses = useStatuses();
+    const docs = useComponentDocs(loadDocs);
+    const reason = docs.status === "ready" ? docs.value.guidance?.deprecated : undefined;
+    const { tags } = component;
+    return (_jsx(Badges, { className: "forgebook-status-badges forgebook-status-badges--page", statuses: statusesOf(reason === undefined ? tags : [...tags, DEPRECATED_STATUS], statuses), hints: reason === undefined ? {} : { [DEPRECATED_STATUS]: STATUS_TEXTS.fromDocs(reason) } }));
+};

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

@@ -1,31 +1,20 @@
 /**
  * A story's code, as the panel's Code tab and the component page show it: its `render` as written, coloured by the
- * plugin, or, for a story drawn from its args, the component in the framework's code with the values of the moment.
+ * plugin, or, for a story drawn from its args, the component in the framework's code with the args its file writes as
+ * code (functions, elements) as written and the values of the moment for the rest.
+ *
+ * @see `../storyCodeText.ts` for the text.
  *
  * @module
  */
-import type { StoryFileCode } from "@forgebook/story-format/source";
 import type { ReactNode } from "react";
-import type { StoryCodeWriter } from "../frame/renderer.ts";
-import type { PanelArgs } from "../messages.ts";
-/** Which story's code, and the values its JSX is drawn from when it has no `render`. */
-export type StoryCodeSource = {
-    /** The story file's code. */
-    readonly code: StoryFileCode;
-    /** The story's export name. */
-    readonly exportName: string;
-    /** 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;
-};
+import { type StoryCodeSource } from "../storyCodeText.ts";
 /**
- * The story's code as text, as copied.
+ * Whether the story has a `render` of its own, shown as written.
  *
- * @param source - the file's code, the story, the component's name and the args.
- * @param write - the framework's code writer, for a story drawn from its args.
+ * @param source - the file's code and the story.
  */
-export declare const storyCodeText: ({ code, exportName, componentName, args }: StoryCodeSource, write: StoryCodeWriter) => string;
+export declare const hasRenderCode: (source: StoryCodeSource) => boolean;
 /**
  * The story's code, coloured.
  *

package/dist/src/shell/StoryCodeBlock.js

@@ -1,13 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { renderCodeOf, storyCodeText, writtenArgsOf } from "../storyCodeText.js";
 import { Code } from "./Code.js";
 import { useCodeWriter } from "./codeWriter.js";
 /**
- * The story's code as text, as copied.
+ * Whether the story has a `render` of its own, shown as written.
  *
- * @param source - the file's code, the story, the component's name and the args.
- * @param write - the framework's code writer, for a story drawn from its args.
+ * @param source - the file's code and the story.
  */
-export const storyCodeText = ({ code, exportName, componentName, args }, write) => code[exportName]?.text ?? write(componentName, args);
+export const hasRenderCode = (source) => renderCodeOf(source) !== undefined;
 /**
  * The story's code, coloured.
  *
@@ -15,12 +15,13 @@ export const storyCodeText = ({ code, exportName, componentName, args }, write)
  */
 export const StoryCodeBlock = (source) => {
     const write = useCodeWriter();
-    const render = source.code[source.exportName];
+    const render = renderCodeOf(source);
     if (render !== undefined) {
         // biome-ignore lint/style/useNamingConvention: React's own name for markup set as HTML
         const markup = { __html: render.html };
         return (_jsx("pre", { className: "forgebook-code-block", children: _jsx("code", { className: "forgebook-code", dangerouslySetInnerHTML: markup }) }));
     }
     // 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) }) }));
+    const names = [...Object.keys(source.args), ...Object.keys(writtenArgsOf(source))];
+    return (_jsx("pre", { className: "forgebook-code-block", children: _jsx(Code, { text: storyCodeText(source, write), names: names }) }));
 };

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

@@ -0,0 +1,36 @@
+/**
+ * A switch offered as a gallery (`control: "gallery"`): a button naming the value shown, which opens a menu of the
+ * values with their previews.
+ *
+ * @remarks
+ * Only the button is on the first screen: the menu's code, its styles and the previews themselves load when it first
+ * opens (`SwitchGalleryPanel.tsx`), so a catalogue pays for its gallery only when a reader asks for it.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type ViewSwitch } from "../switches.ts";
+import type { SwitchPreviews } from "./SwitchGalleryPanel.tsx";
+/** A gallery's props. */
+export type SwitchGalleryProps = {
+    /** The switch. */
+    readonly each: ViewSwitch;
+    /** Whether it sits on the toolbar, after its name, or in a row of the View menu, whose row names it. */
+    readonly isOnBar: boolean;
+    /** The value shown. */
+    readonly value: string;
+    /** Called with the chosen value. */
+    readonly onValueChange: (value: string) => void;
+    /** Whether it is off. */
+    readonly isDisabled: boolean;
+    /** Why it is off, as its tooltip. */
+    readonly disabledNote: string | undefined;
+    /** Loads the catalogue's previews; none when it gives none. */
+    readonly loadPreviews: (() => Promise<SwitchPreviews>) | undefined;
+};
+/**
+ * A gallery's button, and its menu once open.
+ *
+ * @param props - the switch, the value shown and its setter.
+ */
+export declare const SwitchGallery: ({ each, isOnBar, value, onValueChange, isDisabled, disabledNote, loadPreviews }: SwitchGalleryProps) => ReactNode;

package/dist/src/shell/SwitchGallery.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { switchValueOf } from "../switches.js";
+import { Icon } from "./icons.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
+import { usePopover } from "./usePopover.js";
+/** The menu's module, loaded when a gallery first opens. */
+const PANEL = lazyModule(() => import("./SwitchGalleryPanel.js").then((module) => module.SwitchGalleryPanel));
+/**
+ * A gallery's button, and its menu once open.
+ *
+ * @param props - the switch, the value shown and its setter.
+ */
+export const SwitchGallery = ({ each, isOnBar, value, onValueChange, isDisabled, disabledNote, loadPreviews }) => {
+    const popover = usePopover();
+    const name = switchValueOf(each, value)?.label ?? value;
+    return (_jsxs("div", { className: "forgebook-toolbar__control", children: [isOnBar ? (_jsx("span", { className: "forgebook-toolbar__label", "aria-hidden": "true", children: each.label })) : null, _jsxs("button", { ref: popover.buttonRef, type: "button", className: "forgebook-button", "aria-label": `${each.label}: ${name}`, "aria-expanded": popover.isOpen, "aria-controls": popover.panelId, disabled: isDisabled, title: isDisabled ? disabledNote : undefined, onClick: (event) => popover.setIsOpen(!popover.isOpen, event), children: [_jsx("span", { className: "forgebook-gallery-names", children: each.values.map((option) => (_jsx("span", { "data-shown": option.value === value ? "" : undefined, children: option.label }, option.value))) }), _jsx(Icon, { name: "chevronDown", size: 12 })] }), popover.isDrawn ? (_jsx(LazyView, { module: PANEL, props: { each, value, onValueChange, popover, loadPreviews }, loading: null, failed: (message) => (_jsx("p", { className: "forgebook-problems", role: "alert", children: message })) })) : null] }));
+};

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

@@ -0,0 +1,37 @@
+/**
+ * The menu of a gallery (`control: "gallery"`): each value of a switch with its preview, so a reader sees a look before
+ * applying it.
+ *
+ * @remarks
+ * Native radio buttons, as the shell's other menus: one tab stop, the arrow keys move and choose, and a screen reader
+ * reads the group and each value's label. The pictures are decoration beside that label, so they are hidden from it.
+ * Drawn in the top layer, positioned from its button: inside the View menu, whose rows scroll, it would be clipped.
+ * Loaded when a gallery first opens, with the previews (`SwitchGallery.tsx`): their pictures are fetched only then.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { SwitchPreview, ViewSwitch } from "../switches.ts";
+import "./switchGallery.scss";
+import type { Popover } from "./usePopover.ts";
+/** The catalogue's previews, by switch id then value: the plugin's module, with each picture's address. */
+export type SwitchPreviews = Readonly<Record<string, Readonly<Record<string, SwitchPreview>>>>;
+/** The menu's props. */
+export type SwitchGalleryPanelProps = {
+    /** The switch. */
+    readonly each: ViewSwitch;
+    /** The value shown. */
+    readonly value: string;
+    /** Called with the chosen value. */
+    readonly onValueChange: (value: string) => void;
+    /** The button's popover, which opens and closes the menu. */
+    readonly popover: Popover;
+    /** Loads the catalogue's previews; none when it gives none. */
+    readonly loadPreviews: (() => Promise<SwitchPreviews>) | undefined;
+};
+/**
+ * The menu.
+ *
+ * @param props - the switch, the value shown and its setter, and the button's popover.
+ */
+export declare const SwitchGalleryPanel: ({ each, value, onValueChange, popover, loadPreviews }: SwitchGalleryPanelProps) => ReactNode;

package/dist/src/shell/SwitchGalleryPanel.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The menu of a gallery (`control: "gallery"`): each value of a switch with its preview, so a reader sees a look before
+ * applying it.
+ *
+ * @remarks
+ * Native radio buttons, as the shell's other menus: one tab stop, the arrow keys move and choose, and a screen reader
+ * reads the group and each value's label. The pictures are decoration beside that label, so they are hidden from it.
+ * Drawn in the top layer, positioned from its button: inside the View menu, whose rows scroll, it would be clipped.
+ * Loaded when a gallery first opens, with the previews (`SwitchGallery.tsx`): their pictures are fetched only then.
+ *
+ * @module
+ */
+import { useEffect, useId, useLayoutEffect, useState } from "react";
+import { galleryPlace } from "./galleryPlace.js";
+import { Icon } from "./icons.js";
+import "./switchGallery.css";
+/**
+ * What a value shows: its picture, its colours and font, or, with no preview, its label's first letter, so it still
+ * has a place of its own in the grid.
+ *
+ * @param props - the value and its preview.
+ */
+const PreviewArt = ({ option, preview }) => {
+    const [isBroken, setIsBroken] = useState(false);
+    if (preview !== undefined && "image" in preview && !isBroken) {
+        return (_jsx("img", { className: "forgebook-gallery__image", src: preview.image, alt: "", decoding: "async", onError: (_event) => setIsBroken(true) }));
+    }
+    if (preview !== undefined && "swatches" in preview) {
+        return (_jsxs(_Fragment, { children: [_jsx("span", { className: "forgebook-gallery__swatches", children: preview.swatches.map((colour, index) => (_jsx("span", { style: { backgroundColor: colour } }, index))) }), preview.font === undefined ? null : (_jsx("span", { className: "forgebook-gallery__font", style: { fontFamily: `"${preview.font}", var(--forgebook-font-sans)` }, children: preview.font }))] }));
+    }
+    return _jsx("span", { className: "forgebook-gallery__letter", children: Array.from(option.label)[0] });
+};
+/**
+ * The menu.
+ *
+ * @param props - the switch, the value shown and its setter, and the button's popover.
+ */
+export const SwitchGalleryPanel = ({ each, value, onValueChange, popover, loadPreviews }) => {
+    const { panelRef, buttonRef, panelId, setIsOpen, closeAfterChoice } = popover;
+    const name = useId();
+    const [previews, setPreviews] = useState({});
+    useEffect(() => {
+        let isCurrent = true;
+        // without its previews the menu still works: every value then shows its letter
+        loadPreviews?.()
+            .then((loaded) => {
+            if (isCurrent)
+                setPreviews(loaded);
+        })
+            .catch(() => undefined);
+        return () => {
+            isCurrent = false;
+        };
+    }, [loadPreviews]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: both are refs, set once the panel is drawn
+    useLayoutEffect(() => {
+        const panel = panelRef.current;
+        const button = buttonRef.current;
+        if (panel === null || button === null)
+            return;
+        panel.showPopover();
+        const place = () => {
+            const { top, left } = galleryPlace(button.getBoundingClientRect(), panel.getBoundingClientRect(), {
+                width: window.innerWidth,
+                height: window.innerHeight
+            });
+            panel.style.top = `${top}px`;
+            panel.style.left = `${left}px`;
+        };
+        place();
+        // the first open arrives after its popover's own focus: the code was still loading
+        panel.querySelector("input:checked")?.focus();
+        window.addEventListener("resize", place);
+        return () => window.removeEventListener("resize", place);
+    }, []);
+    const closeWithKey = () => {
+        setIsOpen(false);
+        buttonRef.current?.focus();
+    };
+    // on the way down, wherever the focus is: this menu's alone, so a View menu around it stays open
+    // biome-ignore lint/correctness/useExhaustiveDependencies: both it calls read refs and the state's setter
+    useEffect(() => {
+        const onEscape = (event) => {
+            if (event.key !== "Escape")
+                return;
+            event.stopPropagation();
+            closeWithKey();
+        };
+        document.addEventListener("keydown", onEscape, { capture: true });
+        return () => document.removeEventListener("keydown", onEscape, { capture: true });
+    }, []);
+    return (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-gallery", popover: "manual", role: "dialog", "aria-label": each.label, onKeyDown: (event) => {
+            if (event.key === "Enter")
+                closeWithKey();
+        }, children: _jsxs("fieldset", { className: "forgebook-gallery__grid", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: each.label }), each.values.map((option) => (_jsxs("label", { className: "forgebook-gallery__item", children: [_jsx("input", { type: "radio", className: "forgebook-visually-hidden", name: name, checked: option.value === value, onChange: () => onValueChange(option.value), 
+                            // on the click, so a press on the value already shown closes the menu too
+                            onClick: closeAfterChoice }), _jsx("span", { className: "forgebook-gallery__preview", "aria-hidden": "true", children: _jsx(PreviewArt, { option: option, preview: previews[each.id]?.[option.value] }) }), _jsxs("span", { className: "forgebook-gallery__name", children: [option.value === value ? _jsx(Icon, { name: "check", size: 12 }) : null, option.label] })] }, option.value)))] }) }));
+};

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

@@ -0,0 +1,24 @@
+/**
+ * The sidebar's tag filter: a button beside the search, with how many tags are on, which opens the catalogue's tags to
+ * ask for or to leave out, a status shown as its badge. Loaded only for a catalogue whose stories have tags.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { StoryTree } from "../storyTree.ts";
+import "./tagFilter.scss";
+/** The filter's props. */
+export type TagFilterProps = {
+    /** The whole tree, whose tags it offers. */
+    readonly tree: StoryTree;
+    /** The tags on, each `name` or `!name`. */
+    readonly tags: readonly string[];
+    /** Called with the tags on, when they change. */
+    readonly onTagsChange: (tags: readonly string[]) => void;
+};
+/**
+ * The tag filter.
+ *
+ * @param props - the tree, the tags on and how to change them.
+ */
+export declare const TagFilter: ({ tree, tags, onTagsChange }: TagFilterProps) => ReactNode;