forgebook 0.3.3 → 0.4.1

package/dist/src/shell/SidebarSearch.js

@@ -1,12 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { lazy, Suspense, useEffect, useId, useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import { Icon } from "./icons.js";
-import { isTyping } from "./keyboard.js";
+import { isSingleKeyFree } from "./keyboard.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 import { STRINGS } from "./strings.js";
-/** The results, loaded on first use: most visits never search. */
-const SearchPanel = lazy(() => import("./SearchPanel.js").then((module) => ({ default: module.SearchPanel }), 
-// a chunk gone after a new deployment must not take the page with it: the field simply finds nothing more
-() => ({ default: () => null })));
+/**
+ * The results, loaded on first use: most visits never search. Not through `Suspense`, which holds what it reveals back
+ * for 300 ms after its fallback, and that wait would be the first search's (`lazyModule.tsx`).
+ */
+const SEARCH_PANEL = lazyModule(() => import("./SearchPanel.js").then((module) => module.SearchPanel));
+/**
+ * Fetches the results' code when the pointer comes to the field, ahead of a press: the list then draws with the first
+ * letter typed, where it would otherwise wait for its code. A failure is the field's to report when it is used.
+ */
+const preloadPanel = () => {
+    if (SEARCH_PANEL.loaded !== undefined)
+        return;
+    SEARCH_PANEL.load()
+        .then((panel) => {
+        SEARCH_PANEL.loaded = panel;
+    })
+        .catch(() => undefined);
+};
 /**
  * The search field.
  *
@@ -44,7 +59,7 @@ export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sourc
             // a hidden sidebar leaves the key to the page
             if (!isSidebarOpen)
                 return;
-            if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey || isTyping(event.target))
+            if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey || !isSingleKeyFree(event))
                 return;
             event.preventDefault();
             inputRef.current?.focus();
@@ -57,7 +72,7 @@ export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sourc
         onOpenResult(target);
         inputRef.current?.blur();
     };
-    return (_jsxs(_Fragment, { children: [_jsxs("label", { className: "forgebook-search", children: [_jsx(Icon, { name: "search", size: 14 }), _jsx("input", { type: "search", ref: inputRef, value: query, "aria-controls": isListOpen ? listId : undefined, "aria-activedescendant": activeId, onFocus: () => {
+    return (_jsxs(_Fragment, { children: [_jsxs("label", { className: "forgebook-search", onPointerEnter: preloadPanel, children: [_jsx(Icon, { name: "search", size: 14 }), _jsx("input", { type: "search", ref: inputRef, value: query, "aria-controls": isListOpen ? listId : undefined, "aria-activedescendant": activeId, onFocus: () => {
                             setIsUsed(true);
                             setIsListOpen(true);
                         }, onBlur: () => setIsListOpen(false), onKeyDown: (event) => {
@@ -84,5 +99,18 @@ export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sourc
                         } }), query === "" ? (_jsx("kbd", { className: "forgebook-search__key", children: "/" })) : (_jsx("button", { type: "button", className: "forgebook-search__clear", "aria-label": STRINGS.clearSearch, title: STRINGS.clearSearch, onClick: () => {
                             onQueryChange("");
                             inputRef.current?.focus();
-                        }, children: _jsx(Icon, { name: "close", size: 10 }) }))] }), isUsed ? (_jsx(Suspense, { fallback: null, children: _jsx(SearchPanel, { id: listId, tree: tree, sources: sources, query: query, isOpen: isListOpen, field: inputRef, sidebarWidth: sidebarWidth, onFilterReady: onFilterReady, hrefOf: searchHref, onOpen: openResult, onActiveChange: setActiveId, keysRef: keysRef }) })) : null] }));
+                        }, children: _jsx(Icon, { name: "close", size: 10 }) }))] }), isUsed ? (_jsx(LazyView, { module: SEARCH_PANEL, props: {
+                    id: listId,
+                    tree,
+                    sources,
+                    query,
+                    isOpen: isListOpen,
+                    field: inputRef,
+                    sidebarWidth,
+                    onFilterReady,
+                    hrefOf: searchHref,
+                    onOpen: openResult,
+                    onActiveChange: setActiveId,
+                    keysRef
+                }, loading: null, failed: () => null })) : null] }));
 };

package/dist/src/shell/SignatureReference.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ApiTableBox } from "./ApiTableBox.js";
 import { Code } from "./Code.js";
 import { CodeText } from "./CodeText.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { STRINGS } from "./strings.js";
 /**
  * The type parameters as the call writes them: `<TValue>`, or nothing.
@@ -22,4 +24,4 @@ export const callText = (name, signature) => `${name}${typeParametersText(signat
  *
  * @param props - the function's name and signature.
  */
-export const SignatureReference = ({ name, signature }) => (_jsxs("div", { className: "forgebook-signature", children: [_jsx("pre", { className: "forgebook-signature__call", children: _jsx(Code, { text: callText(name, signature), names: signature.parameters.map((parameter) => parameter.name) }) }), signature.parameters.length === 0 ? (_jsx("p", { className: "forgebook-tab-note", children: STRINGS.signatureNone })) : (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: STRINGS.signatureParameter }), _jsx("th", { scope: "col", children: STRINGS.apiType }), _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: signature.parameters.map((parameter) => (_jsxs("tr", { "data-prop": parameter.name, children: [_jsxs("th", { scope: "row", children: [_jsxs("code", { className: "forgebook-api__name", children: [parameter.isRest ? "..." : "", parameter.name] }), parameter.isOptional || parameter.isRest ? null : (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" }))] }), _jsx("td", { className: "forgebook-api__type", children: _jsx(Code, { text: parameter.type, names: [] }) }), _jsx("td", { children: _jsx(CodeText, { text: parameter.description }) })] }, parameter.name))) })] }) })), _jsx("h3", { className: "forgebook-signature__returns", children: STRINGS.signatureReturns }), _jsxs("p", { children: [_jsx("code", { className: "forgebook-inline-code", children: signature.returns }), signature.returnsDescription === "" ? null : (_jsxs(_Fragment, { children: [" ", _jsx(CodeText, { text: signature.returnsDescription })] }))] })] }));
+export const SignatureReference = ({ name, signature }) => (_jsxs("div", { className: "forgebook-signature", children: [_jsx("pre", { className: "forgebook-signature__call", children: _jsx(Code, { text: callText(name, signature), names: signature.parameters.map((parameter) => parameter.name) }) }), signature.parameters.length === 0 ? (_jsx("p", { className: "forgebook-tab-note", children: LATER_STRINGS.signatureNone })) : (_jsx(ApiTableBox, { children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: LATER_STRINGS.signatureParameter }), _jsx("th", { scope: "col", children: LATER_STRINGS.apiType }), _jsx("th", { scope: "col", children: LATER_STRINGS.apiWhat })] }) }), _jsx("tbody", { children: signature.parameters.map((parameter) => (_jsxs("tr", { "data-prop": parameter.name, children: [_jsxs("th", { scope: "row", children: [_jsxs("code", { className: "forgebook-api__name", children: [parameter.isRest ? "..." : "", parameter.name] }), parameter.isOptional || parameter.isRest ? null : (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" }))] }), _jsx("td", { className: "forgebook-api__type", children: _jsx(Code, { text: parameter.type, names: [] }) }), _jsx("td", { children: _jsx(CodeText, { text: parameter.description }) })] }, parameter.name))) })] }) })), _jsx("h3", { className: "forgebook-signature__returns", children: LATER_STRINGS.signatureReturns }), _jsxs("p", { children: [_jsx("code", { className: "forgebook-inline-code", children: signature.returns }), signature.returnsDescription === "" ? null : (_jsxs(_Fragment, { children: [" ", _jsx(CodeText, { text: signature.returnsDescription })] }))] })] }));

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

@@ -11,11 +11,13 @@
  * @module
  */
 import { type ReactNode } from "react";
-import { type PanelArgs } from "../messages.ts";
+import type { AddressLink } from "../addressArgsParam.ts";
+import type { PanelArgs } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
 import { type FixedView } from "../storyGlobals.ts";
 import type { TreeComponent, TreeStory } from "../storyTree.ts";
 import { type ViewState } from "../viewState.ts";
+import type { ArgControlLoaders } from "./customControls.ts";
 import type { ShellPlugin } from "./pluginTabs.tsx";
 import { type PageScroll } from "./useScrollMemory.ts";
 /** The stage's props. */
@@ -30,11 +32,17 @@ export type StageProps = {
     readonly onViewChange: (view: ViewState) => void;
     /** Called with what a story fixes of the view, once its frame read it, for the toolbar to show. */
     readonly onFixedChange: (storyId: string, fixed: FixedView) => void;
+    /** Loads the catalogue's design tokens; none when it has none. */
+    readonly loadTokens?: (() => Promise<unknown>) | undefined;
+    /** Loads each custom control the catalogue registers, by name; none when it registers none. */
+    readonly argControls?: ArgControlLoaders | undefined;
     /**
      * The values set in the Props tab, over the story's own args (kept in the address): as the address names them, so
      * unchecked; the stage hands the frames only those the story declares.
      */
     readonly panelArgs: PanelArgs;
+    /** What else the address says of the values: how to type them, and which could not be read. */
+    readonly addressLink: AddressLink | undefined;
     /** Called with the panel's changed values. */
     readonly onPanelArgsChange: (args: PanelArgs) => void;
     /** The matrix's axes (kept in the address): the rows' prop, then the columns'; empty draws the story alone. */
@@ -70,4 +78,4 @@ export type StageProps = {
  *
  * @param props - the component, the story, the view, the panel's values, the frame page and the loaders.
  */
-export declare const Stage: ({ component, story, view: ownView, onViewChange: onOwnViewChange, onFixedChange, panelArgs, onPanelArgsChange, matrixAxes, onMatrixAxesChange, frameUrl, plugins, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }: StageProps) => ReactNode;
+export declare 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 }: StageProps) => ReactNode;

package/dist/src/shell/Stage.js

@@ -15,9 +15,9 @@ 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 } 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";
@@ -31,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";
@@ -53,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);
@@ -123,7 +98,9 @@ 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,
@@ -132,16 +109,20 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         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);
@@ -188,11 +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]);
-    // 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());
@@ -205,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));
@@ -244,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,
@@ -256,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,
@@ -275,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/StoryPicker.d.ts

@@ -16,10 +16,12 @@ export type StoryPickerProps = {
     readonly onOpenComponent: () => void;
     /** Opens a story's page. */
     readonly onOpenStory: (story: TreeStory) => void;
+    /** What sits beside the select, at the header's end: the page width's button. */
+    readonly children?: ReactNode;
 };
 /**
  * The picker of a component's stories.
  *
- * @param props - the component, the shown story and how to open a page.
+ * @param props - the component, the shown story, how to open a page, and what sits beside the select.
  */
-export declare const StoryPicker: ({ component, currentStoryId, onOpenComponent, onOpenStory }: StoryPickerProps) => ReactNode;
+export declare const StoryPicker: ({ component, currentStoryId, onOpenComponent, onOpenStory, children }: StoryPickerProps) => ReactNode;

package/dist/src/shell/StoryPicker.js

@@ -15,9 +15,9 @@ const ALL = "";
 /**
  * The picker of a component's stories.
  *
- * @param props - the component, the shown story and how to open a page.
+ * @param props - the component, the shown story, how to open a page, and what sits beside the select.
  */
-export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpenStory }) => {
+export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpenStory, children }) => {
     const id = useId();
     const { storyGroups } = useCatalogue();
     const sections = groupedStories(component.stories, storyGroups.map((group) => group.id));
@@ -27,5 +27,5 @@ export const StoryPicker = ({ component, currentStoryId, onOpenComponent, onOpen
                         onOpenComponent();
                     else
                         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)))] })] }));
+                }, 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)))] }), children] }));
 };

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

@@ -0,0 +1,29 @@
+/**
+ * A boolean's switch, in the Props tab's fields and in the nested fields of the value editors.
+ *
+ * @remarks
+ * A native checkbox drawn as a switch (`role="switch"`, `.forgebook-switch`): it keeps Space, the label and the
+ * disabled state of a checkbox, and Enter turns it as well, as a switch's button would.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+/** What a switch shows and calls. */
+export type SwitchProps = {
+    /** Its accessible name. */
+    readonly label: string;
+    /** Whether it is on. */
+    readonly isOn: boolean;
+    /** The id of the text that describes it, when there is one. */
+    readonly describedBy?: string | undefined;
+    /** Whether it cannot be turned: a value the type fixes. */
+    readonly disabled?: boolean | undefined;
+    /** Called with the new state. */
+    readonly onChange: (isOn: boolean) => void;
+};
+/**
+ * The switch.
+ *
+ * @param props - its name, state and setter.
+ */
+export declare const Switch: ({ label, isOn, describedBy, disabled, onChange }: SwitchProps) => ReactNode;

package/dist/src/shell/Switch.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The switch.
+ *
+ * @param props - its name, state and setter.
+ */
+export const Switch = ({ label, isOn, describedBy, disabled, onChange }) => (_jsx("input", { type: "checkbox", role: "switch", className: "forgebook-switch", "aria-label": label, "aria-checked": isOn, "aria-describedby": describedBy, checked: isOn, disabled: disabled, onChange: (event) => onChange(event.target.checked), onKeyDown: (event) => {
+        // a click turns it as Space does, through its change
+        if (event.key === "Enter")
+            event.currentTarget.click();
+    } }));

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;