forgebook 0.3.2 → 0.4.0

package/dist/src/shell/TagFilter.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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 { useEffect, useMemo } from "react";
+import { catalogueTags, taggedTree } from "../storyTags.js";
+import { StatusBadge, useStatuses } from "./StatusBadges.js";
+import "./tagFilter.css";
+import { textsOfGroup } from "./strings.js";
+import { loadedTagFilter } from "./useListedTree.js";
+import { usePopover } from "./usePopover.js";
+/** The filter's texts, as shown: Forgebook's, with the catalogue's replacements. */
+const TAG_STRINGS = textsOfGroup("tagFilter", {
+    button: "Filter by tag",
+    buttonOn: (count) => `Filter by tag: ${count} on`,
+    title: "Tags",
+    leaveOut: (tag) => `Leave out ${tag}`,
+    clear: "Clear the filter"
+});
+/**
+ * The tag filter.
+ *
+ * @param props - the tree, the tags on and how to change them.
+ */
+export const TagFilter = ({ tree, tags, onTagsChange }) => {
+    const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
+    // the filter's code came with this chunk: handed over, a checked tag filters the tree in the render that adds it
+    useEffect(() => {
+        loadedTagFilter.current = taggedTree;
+    }, []);
+    const offered = useMemo(() => catalogueTags(tree), [tree]);
+    const statuses = useStatuses();
+    const set = (tag, written) => onTagsChange([
+        ...tags.filter((each) => each !== tag && each !== `!${tag}`),
+        ...(written === undefined ? [] : [written])
+    ]);
+    const label = tags.length === 0 ? TAG_STRINGS.button : TAG_STRINGS.buttonOn(tags.length);
+    return (_jsxs("div", { className: "forgebook-tag-filter", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-icon-button", title: label, "aria-label": label, "aria-expanded": isOpen, "aria-controls": panelId, "data-on": tags.length > 0 ? "" : undefined, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx("svg", { viewBox: "0 0 16 16", width: 14, height: 14, "aria-hidden": "true", children: _jsx("path", { d: "M2 4h12M4.5 8h7M7 12h2", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round" }) }), tags.length === 0 ? null : _jsx("span", { className: "forgebook-tag-filter__count", children: tags.length })] }), isDrawn ? (_jsxs("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-tag-filter__panel", role: "dialog", "aria-label": TAG_STRINGS.title, children: [_jsx("ul", { className: "forgebook-tag-filter__list", children: offered.map(({ tag, stories }) => {
+                            const status = statuses.find((each) => each.id === tag);
+                            return (_jsxs("li", { className: "forgebook-tag-filter__row", children: [_jsxs("label", { className: "forgebook-tag-filter__tag", children: [_jsx("input", { type: "checkbox", checked: tags.includes(tag), onChange: (event) => set(tag, event.target.checked ? tag : undefined) }), _jsx("span", { className: "forgebook-tag-filter__name", children: status === undefined ? tag : _jsx(StatusBadge, { status: status }) }), _jsx("span", { className: "forgebook-tree__count", children: stories })] }), _jsx("button", { type: "button", className: "forgebook-icon-button", title: TAG_STRINGS.leaveOut(tag), "aria-label": TAG_STRINGS.leaveOut(tag), "aria-pressed": tags.includes(`!${tag}`), onClick: () => set(tag, tags.includes(`!${tag}`) ? undefined : `!${tag}`), children: _jsxs("svg", { viewBox: "0 0 16 16", width: 12, height: 12, "aria-hidden": "true", children: [_jsx("circle", { cx: "8", cy: "8", r: "5.5", fill: "none", stroke: "currentColor", strokeWidth: "1.5" }), _jsx("path", { d: "m4 12 8-8", stroke: "currentColor", strokeWidth: "1.5" })] }) })] }, tag));
+                        }) }), _jsx("button", { type: "button", className: "forgebook-button forgebook-button--quiet", disabled: tags.length === 0, onClick: () => onTagsChange([]), children: TAG_STRINGS.clear })] })) : null] }));
+};

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

@@ -0,0 +1,39 @@
+/**
+ * What a story's tags draw, as one chunk loaded the first time one of them is drawn (`tagView.tsx`): the tag filter and
+ * the statuses' badges, which share their reading of the catalogue's statuses.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { TreeComponent, TreeStory } from "../storyTree.ts";
+import { type TagFilterProps } from "./TagFilter.tsx";
+/** One place the tags draw in, and what it reads. */
+export type TagViewProps = ({
+    /** The sidebar's tag filter. */
+    readonly place: "filter";
+} & TagFilterProps) | {
+    /** A component's entry in the sidebar: its meta's statuses. */
+    readonly place: "entry";
+    /** The component. */
+    readonly component: TreeComponent;
+} | {
+    /** The top of a component's page: its meta's statuses, and `deprecated` when its TSDoc says so. */
+    readonly place: "page";
+    /** The component. */
+    readonly component: TreeComponent;
+    /** Loads its docs; none when the source has none for its file. */
+    readonly loadDocs: (() => Promise<unknown>) | undefined;
+} | {
+    /** A story's example on its component's page: the statuses it holds that its component's meta does not. */
+    readonly place: "story";
+    /** The story. */
+    readonly story: TreeStory;
+    /** Its component. */
+    readonly component: TreeComponent;
+};
+/**
+ * What the tags draw in a place.
+ *
+ * @param props - the place, and what it reads.
+ */
+export declare const TagView: (props: TagViewProps) => ReactNode;

package/dist/src/shell/TagViews.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ComponentBadges, StatusBadges } from "./StatusBadges.js";
+import { TagFilter } from "./TagFilter.js";
+/**
+ * What the tags draw in a place.
+ *
+ * @param props - the place, and what it reads.
+ */
+export const TagView = (props) => {
+    switch (props.place) {
+        case "filter":
+            return _jsx(TagFilter, { tree: props.tree, tags: props.tags, onTagsChange: props.onTagsChange });
+        case "entry":
+            return _jsx(StatusBadges, { tags: props.component.tags, className: "forgebook-status-badges" });
+        case "page":
+            return _jsx(ComponentBadges, { component: props.component, loadDocs: props.loadDocs });
+        case "story":
+            return (_jsx(StatusBadges, { tags: props.story.tags.filter((tag) => !props.component.tags.includes(tag)), className: "forgebook-status-badges forgebook-status-badges--story" }));
+    }
+};

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

@@ -13,6 +13,7 @@ import { type ReactNode, type Ref } from "react";
 import { type DeviceDefault } from "../deviceView.ts";
 import { type FixedView } from "../storyGlobals.ts";
 import { type ViewState } from "../viewState.ts";
+import type { ControlContext } from "./ToolbarControl.tsx";
 /** The toolbar's props. */
 export type ToolbarProps = {
     /** The view. */
@@ -35,6 +36,8 @@ export type ToolbarProps = {
     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;
+    /** Loads the catalogue's previews for a gallery; none when it gives none. */
+    readonly loadSwitchPreviews?: ControlContext["loadSwitchPreviews"];
 };
 /**
  * The button that shows the hidden sidebar, at the toolbar's start; the home's bar holds only it.
@@ -49,4 +52,4 @@ export declare const ShowSidebarButton: ({ onShowSidebar, showSidebarRef }: Pick
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault }: ToolbarProps) => ReactNode;
+export declare const Toolbar: ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage, isComponentPage, onShowSidebar, showSidebarRef, shownWidth, fixed, isLogic, deviceDefault, loadSwitchPreviews }: ToolbarProps) => ReactNode;

package/dist/src/shell/Toolbar.js

@@ -13,7 +13,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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 { impliedSwitches, switchWithRole } from "../switches.js";
 import { hasViewChanges, isComparing } from "../viewState.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
@@ -58,14 +58,15 @@ const compareChoices = (catalogue) => {
  * @param props - the view, its setter, and whether the page compares at all.
  */
 const CompareMenu = ({ view, onViewChange, isDisabled, fixed = NOT_FIXED }) => {
-    const { isOpen, isDrawn, setIsOpen, buttonRef, panelRef, panelId } = usePopover();
+    const { isOpen, isDrawn, setIsOpen, closeAfterChoice, buttonRef, panelRef, panelId } = usePopover();
     const catalogue = useCatalogue();
     const name = useId();
     return (_jsxs("div", { className: "forgebook-view-menu", children: [_jsxs("button", { ref: buttonRef, type: "button", className: "forgebook-button", title: STRINGS.compare, "aria-pressed": isComparing(view), "aria-expanded": isOpen, "aria-controls": panelId, disabled: isDisabled, onClick: (event) => setIsOpen(!isOpen, event), children: [_jsx(Icon, { name: "compare", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: STRINGS.compare }), _jsx(Icon, { name: "chevronDown", size: 12 })] }), isDrawn ? (_jsx("div", { ref: panelRef, id: panelId, className: "forgebook-popover forgebook-popover--end", role: "dialog", "aria-label": STRINGS.compare, children: _jsxs("fieldset", { className: "forgebook-choices", children: [_jsx("legend", { className: "forgebook-visually-hidden", children: STRINGS.compare }), compareChoices(catalogue).map((choice) => (_jsxs("label", { className: "forgebook-choice", children: [_jsx("input", { type: "radio", name: name, 
-                                    // a switch the story fixes would draw the same story in every cell
-                                    disabled: choice.axes.some((axis) => fixed.switches[axis] !== undefined), checked: view.compare.join(",") === choice.axes.join(","), onChange: () => {
+                                    // a switch the story fixes, or another switch's value implies, would draw the same in every cell
+                                    disabled: choice.axes.some((axis) => fixed.switches[axis] !== undefined ||
+                                        impliedSwitches(view.switches, catalogue.switches).has(axis)), checked: view.compare.join(",") === choice.axes.join(","), onChange: () => {
                                         onViewChange({ ...view, compare: choice.axes });
-                                        setIsOpen(false);
+                                        closeAfterChoice();
                                     } }), choice.label] }, choice.axes.join(","))))] }) })) : null] }));
 };
 /**
@@ -79,13 +80,22 @@ export const ShowSidebarButton = ({ onShowSidebar, showSidebarRef }) => (_jsx("b
  *
  * @param props - the view, its setter, the page shown and the story's width.
  */
-export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, showSidebarRef, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE }) => {
+export const Toolbar = ({ view: ownView, onViewChange: onOwnViewChange, isStoryPage = true, isComponentPage = false, onShowSidebar, showSidebarRef, shownWidth, fixed = NOT_FIXED, isLogic = false, deviceDefault = NO_DEVICE, loadSwitchPreviews }) => {
     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, isComponentPage, fixed, shownWidth, deviceDefault };
+    const context = {
+        view,
+        onViewChange,
+        isStoryPage,
+        isComponentPage,
+        fixed,
+        shownWidth,
+        deviceDefault,
+        loadSwitchPreviews
+    };
     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

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

@@ -15,6 +15,7 @@ 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";
+import type { SwitchPreviews } from "./SwitchGalleryPanel.tsx";
 /** Where a control is drawn: on the toolbar, or in a row of the View menu. */
 export type ControlForm = "bar" | "row";
 /** What every control reads and sets. */
@@ -33,6 +34,8 @@ export type ControlContext = {
     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;
+    /** Loads the catalogue's previews for a gallery; none when it gives none. */
+    readonly loadSwitchPreviews: (() => Promise<SwitchPreviews>) | undefined;
 };
 /**
  * One control, drawn for where it sits.

package/dist/src/shell/ToolbarControl.js

@@ -14,15 +14,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { AUDIENCE_IDS } from "../audiences.js";
 import { DEVICE_PARAMETER, shownDevice } from "../deviceView.js";
-import { switchControl } from "../switches.js";
+import { impliedSwitches, 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 { LazyView, lazyModule } from "./lazyModule.js";
 import { Segmented } from "./Segmented.js";
 import { STRINGS } from "./strings.js";
 import { switchValueIn, withSwitch } from "./switchView.js";
 import { WidthField } from "./WidthField.js";
+/** A switch's gallery, loaded with the first catalogue's switch that has one: most catalogues have none. */
+const SWITCH_GALLERY = lazyModule(() => import("./SwitchGallery.js").then((module) => module.SwitchGallery));
 /** The icon of each scheme a colour scheme switch's values draw in. */
 const SCHEME_ICONS = {
     light: "sun",
@@ -69,14 +72,28 @@ const FormChoice = ({ form, isList, ...choice }) => {
  *
  * @param props - the switch, its form, and what every control shares.
  */
-const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed }) => {
+const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed, loadSwitchPreviews }) => {
+    const { switches } = useCatalogue();
+    const implied = impliedSwitches(view.switches, switches).get(each.id);
     const isFixed = fixed.switches[each.id] !== undefined;
-    const isDisabled = (isStoryPage && view.compare.includes(each.id)) || isFixed;
-    const disabledNote = isFixed ? STRINGS.setByStory : undefined;
-    const value = switchValueIn(view, each);
+    const isDisabled = (isStoryPage && view.compare.includes(each.id)) || isFixed || implied !== undefined;
+    const storyNote = isFixed ? STRINGS.setByStory : undefined;
+    const disabledNote = implied === undefined ? storyNote : STRINGS.setBy.replace("{value}", implied.by.label);
+    const value = implied?.value ?? switchValueIn(view, each);
     const choose = (chosen) => onViewChange(withSwitch(view, each, chosen));
     const more = each.values.find((option) => option.isMore === true);
     const standard = each.values.find((option) => option.isMore !== true);
+    if (switchControl(each) === "gallery") {
+        return (_jsx(LazyView, { module: SWITCH_GALLERY, props: {
+                each,
+                isOnBar: form === "bar",
+                value,
+                onValueChange: choose,
+                isDisabled,
+                disabledNote,
+                loadPreviews: loadSwitchPreviews
+            }, loading: null, failed: (message) => (_jsx("p", { className: "forgebook-problems", role: "alert", children: message })) }));
+    }
     if (form === "bar" && each.role === "colorScheme") {
         return (_jsx(Segmented, { label: each.label, isDisabled: isDisabled, disabledNote: disabledNote, options: each.values.map((option) => ({
                 value: option.value,
@@ -85,7 +102,7 @@ const SwitchControl = ({ each, form, view, onViewChange, isStoryPage, fixed }) =
             })), value: value, onValueChange: choose }));
     }
     if (form === "bar" && each.role === "contrast" && more !== undefined && standard !== undefined) {
-        return (_jsxs("button", { type: "button", className: "forgebook-button", title: isFixed ? STRINGS.setByStory : each.label, "aria-pressed": value === more.value, disabled: isDisabled, onClick: () => choose(value === more.value ? standard.value : more.value), children: [_jsx(Icon, { name: "contrast", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: each.label })] }));
+        return (_jsxs("button", { type: "button", className: "forgebook-button", title: disabledNote ?? each.label, "aria-pressed": value === more.value, disabled: isDisabled, onClick: () => choose(value === more.value ? standard.value : more.value), children: [_jsx(Icon, { name: "contrast", size: 14 }), _jsx("span", { className: "forgebook-button__label", children: each.label })] }));
     }
     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 }));
 };

package/dist/src/shell/ViewMenuPanel.js

@@ -20,6 +20,7 @@ import { controlLabel } from "./controlLabel.js";
 import { Icon } from "./icons.js";
 import { LATER_STRINGS } from "./laterStrings.js";
 import { NamedViews } from "./NamedViews.js";
+import { rememberPlay } from "./playMemory.js";
 /** How long the rows take to move out of a dragged row's way, in ms: the shell's `$duration-quick`. */
 const SHIFT_MS = 150;
 /** How they move: the shell's `$ease-out`, decelerating. */
@@ -195,5 +196,9 @@ export const ViewMenuPanel = ({ layout, ownView, movedIds, ids, drawControl, ...
         window.addEventListener("pointerup", drop);
         window.addEventListener("pointercancel", drop);
     };
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "forgebook-popover__body", children: [_jsx(NamedViews, { view: context.view, ownView: ownView, onViewChange: context.onViewChange }), _jsx("ol", { ref: listRef, className: "forgebook-arrange-list", "data-dragging": draggedId === undefined ? undefined : "", children: shown.map((each, index) => (_jsx(ControlRow, { each: each, index: index, count: shown.length, isDragged: each.control.id === draggedId, isMoved: movedIds.includes(each.control.id), isChanged: hasViewChanges(ownView, switches, [each.control.id], catalogue.audience), layout: layout, hintId: hintId, onGrab: grab, onAnnounce: setAnnounced, drawControl: drawControl }, each.control.id))) }), _jsx("span", { id: hintId, className: "forgebook-visually-hidden", children: LATER_STRINGS.moveControlHint }), _jsx("span", { className: "forgebook-visually-hidden", "aria-live": "polite", children: announced }), _jsx(HiddenControls, { hidden: hidden, layout: layout, drawControl: drawControl }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": layout.isWrapped, className: "forgebook-switch", checked: layout.isWrapped, onChange: (event) => layout.setIsWrapped(event.currentTarget.checked) }), LATER_STRINGS.wrapToolbar] })] }), _jsxs("div", { className: "forgebook-popover__foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => context.onViewChange(withDefaults(context.view, switches, ids, catalogue.audience)), children: LATER_STRINGS.resetView }), _jsx("button", { type: "button", className: "forgebook-text-button", title: LATER_STRINGS.toolbarInBrowser, disabled: !layout.isArranged, onClick: layout.reset, children: LATER_STRINGS.resetToolbar }), _jsx("span", { className: "forgebook-popover__note", children: LATER_STRINGS.viewInAddress })] })] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "forgebook-popover__body", children: [_jsx(NamedViews, { view: context.view, ownView: ownView, onViewChange: context.onViewChange }), _jsx("ol", { ref: listRef, className: "forgebook-arrange-list", "data-dragging": draggedId === undefined ? undefined : "", children: shown.map((each, index) => (_jsx(ControlRow, { each: each, index: index, count: shown.length, isDragged: each.control.id === draggedId, isMoved: movedIds.includes(each.control.id), isChanged: hasViewChanges(ownView, switches, [each.control.id], catalogue.audience), layout: layout, hintId: hintId, onGrab: grab, onAnnounce: setAnnounced, drawControl: drawControl }, each.control.id))) }), _jsx("span", { id: hintId, className: "forgebook-visually-hidden", children: LATER_STRINGS.moveControlHint }), _jsx("span", { className: "forgebook-visually-hidden", "aria-live": "polite", children: announced }), _jsx(HiddenControls, { hidden: hidden, layout: layout, drawControl: drawControl }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": layout.isWrapped, className: "forgebook-switch", checked: layout.isWrapped, onChange: (event) => layout.setIsWrapped(event.currentTarget.checked) }), LATER_STRINGS.wrapToolbar] }), _jsxs("label", { className: "forgebook-wrap-choice", children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": context.view.play === "on", className: "forgebook-switch", checked: context.view.play === "on", onChange: (event) => {
+                                    const play = event.currentTarget.checked ? "on" : "off";
+                                    rememberPlay(catalogue, play);
+                                    context.onViewChange({ ...context.view, play });
+                                } }), LATER_STRINGS.playOnOpen] })] }), _jsxs("div", { className: "forgebook-popover__foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => context.onViewChange(withDefaults(context.view, switches, ids, catalogue.audience)), children: LATER_STRINGS.resetView }), _jsx("button", { type: "button", className: "forgebook-text-button", title: LATER_STRINGS.toolbarInBrowser, disabled: !layout.isArranged, onClick: layout.reset, children: LATER_STRINGS.resetToolbar }), _jsx("span", { className: "forgebook-popover__note", children: LATER_STRINGS.viewInAddress })] })] }));
 };

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

@@ -0,0 +1,22 @@
+/**
+ * What `checkedAddressArgs` needs for a story's structured values, loaded with the first story that has one: what reads a
+ * shape, the worst case of one, and the schemas of the custom controls it names. A catalogue of plain props never asks for
+ * this; one with no custom control never loads theirs.
+ *
+ * @module
+ */
+import type { ArgChecks } from "../addressArgs.ts";
+import { worstOfShape } from "../shapeValues.ts";
+import type { ArgControlLoaders } from "./customControls.ts";
+/** What the stage holds of it. */
+export type LoadedChecks = ArgChecks & {
+    /** A shape's worst value. */
+    readonly worstOfShape: typeof worstOfShape;
+};
+/**
+ * The checks for a story.
+ *
+ * @param names - the custom controls it names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export declare const loadedChecks: (names: readonly string[], loaders: ArgControlLoaders) => Promise<LoadedChecks>;

package/dist/src/shell/argChecks.js

@@ -0,0 +1,20 @@
+import { isFileList, isValueOfShape, worstOfShape } from "../shapeValues.js";
+/**
+ * The checks for a story.
+ *
+ * @param names - the custom controls it names.
+ * @param loaders - the catalogue's custom controls.
+ */
+export const loadedChecks = async (names, loaders) => {
+    const checks = { isFileList, isValueOfShape, worstOfShape };
+    if (names.length === 0)
+        return checks;
+    try {
+        const { customChecksOf } = await import("./customControls.js");
+        return { ...checks, custom: await customChecksOf(names, loaders) };
+    }
+    catch {
+        // a page left open across a new build: a control that cannot load refuses its values, as one that fails does
+        return checks;
+    }
+};

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

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import { type PanelArgs } from "../messages.ts";
+import { type AcceptedArgs } from "../addressArgs.ts";
 import type { PluginStoryFrame } from "../plugin.ts";
 import type { LiveView, StageWidth } from "../viewState.ts";
 /** How the story is drawn again. */
@@ -18,11 +18,24 @@ export type AsideStory = {
     readonly width: StageWidth;
     /** The colour its page has in the view; none without one. */
     readonly background: string | undefined;
-    /** The values set in the panel, sent once it is ready. */
-    readonly args: PanelArgs;
+    /**
+     * The values the story accepted of the panel's, sent once it is ready; `undefined` while the check waits for the
+     * story's docs, when the frame draws the story's own and `AsideFrame.settle` gives them.
+     */
+    readonly args: AcceptedArgs | undefined;
     /** The view's live part, sent once it is ready; none when the address already says it all (the compare view). */
     readonly view: LiveView | undefined;
 };
+/** A story's second frame, as the shell holds it. */
+export type AsideFrame = PluginStoryFrame & {
+    /**
+     * Gives a frame drawn before the check ended the values it accepted; a frame that has them keeps them, since it shows
+     * the panel's values of the moment it was asked for.
+     *
+     * @param args - the accepted values.
+     */
+    readonly settle: (args: AcceptedArgs) => void;
+};
 /**
  * Draws a story's second frame in an element.
  *
@@ -31,4 +44,4 @@ export type AsideStory = {
  * @param aside - how the story is drawn.
  * @returns what takes it away.
  */
-export declare const showAsideStory: (target: HTMLElement, title: string, aside: AsideStory) => PluginStoryFrame;
+export declare const showAsideStory: (target: HTMLElement, title: string, aside: AsideStory) => AsideFrame;

package/dist/src/shell/asideStory.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { checkedArgsMessage } from "../addressArgs.js";
 import { isFrameMessage } from "../messages.js";
 import { framesOrigin, isFromFrames, storyFrameAttributes } from "./framesOrigin.js";
 import { FRAME_ASIDE_ATTRIBUTE } from "./useFrameMessages.js";
@@ -28,18 +29,27 @@ export const showAsideStory = (target, title, aside) => {
         frame.setAttribute("sandbox", sandbox);
     frame.setAttribute(FRAME_ASIDE_ATTRIBUTE, "");
     // a width set on the stage holds as far as the room allows
-    frame.style.cssText = "display:block;max-width:100%;height:100%;margin-inline:auto;border:0";
+    frame.style.cssText =
+        "display:block;max-width:100%;height:100%;margin-inline:auto;border:0;color-scheme:light";
     frame.style.width = aside.width === "fill" ? "100%" : `${aside.width}px`;
     if (aside.background !== undefined)
         target.style.backgroundColor = aside.background;
+    let args = aside.args;
+    let isReady = false;
+    const send = (message) => frame.contentWindow?.postMessage(message, framesOrigin());
     const answer = (event) => {
         const story = frame.contentWindow;
         if (!isFromFrames(event) || event.source !== story || story === null)
             return;
-        if (!isFrameMessage(event.data) || event.data.type !== "forgebook:ready")
+        if (!isFrameMessage(event.data))
             return;
-        const send = (message) => story.postMessage(message, framesOrigin());
-        send({ type: "forgebook:args", args: aside.args });
+        if (event.data.type === "forgebook:scheme")
+            frame.style.colorScheme = event.data.scheme;
+        if (event.data.type !== "forgebook:ready")
+            return;
+        isReady = true;
+        if (args !== undefined)
+            send(checkedArgsMessage(args));
         if (aside.view !== undefined)
             send({ type: "forgebook:view", view: aside.view });
     };
@@ -50,6 +60,13 @@ export const showAsideStory = (target, title, aside) => {
         remove: () => {
             window.removeEventListener("message", answer);
             frame.remove();
+        },
+        settle: (accepted) => {
+            if (args !== undefined)
+                return;
+            args = accepted;
+            if (isReady)
+                send(checkedArgsMessage(accepted));
         }
     };
 };

package/dist/src/shell/audienceSections.css

@@ -8,11 +8,11 @@
     display: grid;
     align-content: start;
     gap: 0.5rem;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-guidance__list h3 {
     margin: 0;
-    font: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    font: var(--forgebook-text-label);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-guidance__list ul {
@@ -23,7 +23,7 @@
   }
   .forgebook-guidance__deprecated {
     margin: 0;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-about-pages {
     display: grid;
@@ -31,21 +31,21 @@
     margin: 0;
     padding: 0;
     list-style: none;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
   }
   .forgebook-about-pages li {
     display: grid;
     gap: 0.25rem;
   }
   .forgebook-about-pages__description {
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-token {
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono);
   }
   .forgebook-token__swatch {
     flex: none;
@@ -57,7 +57,7 @@
   .forgebook-tokens__others {
     display: grid;
     gap: 0.5rem;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-tokens__others > summary {
@@ -72,12 +72,12 @@
   }
   .forgebook-coverage__summary {
     margin: 0;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-text-secondary);
   }
   .forgebook-coverage__progress {
     margin: 0;
-    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font: var(--forgebook-text-caption);
     color: var(--forgebook-text-tertiary);
   }
   .forgebook-coverage__progress:empty {

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

@@ -25,4 +25,4 @@ export declare const useConfiguredCatalogue: ({ title, switches, languages, list
     readonly languages?: readonly StoryLanguage[];
     readonly lists?: CatalogueLists;
     readonly plugins?: readonly ShellPlugin[];
-}) => CatalogueSettings;
+}, readStored?: (key: string) => string | null) => CatalogueSettings;

package/dist/src/shell/catalogueContext.js

@@ -14,4 +14,9 @@ export const NO_PLUGINS = [];
  *
  * @param config - its name, its switches, its languages, its lists and its plugins (whose tabs it may turn off).
  */
-export const useConfiguredCatalogue = ({ title, switches, languages = NO_LANGUAGES, lists, plugins = NO_PLUGINS }) => useMemo(() => catalogueSettings(title, catalogueSwitches(switches, languages, lists?.controls), lists, plugins.flatMap((plugin) => plugin.tabs.map((tab) => tab.id))), [title, switches, languages, lists, plugins]);
+export const useConfiguredCatalogue = ({ title, switches, languages = NO_LANGUAGES, lists, plugins = NO_PLUGINS }, readStored) => useMemo(() => {
+    const settings = catalogueSettings(title, catalogueSwitches(switches, languages, lists?.controls), lists, plugins.flatMap((plugin) => plugin.tabs.map((tab) => tab.id)));
+    // a reader's choice stands in for the catalogue's default on their own pages; an address that names one comes first
+    const remembered = readStored?.(`${settings.id}:play`);
+    return remembered === "on" || remembered === "off" ? { ...settings, readerPlay: remembered } : settings;
+}, [title, switches, languages, lists, plugins, readStored]);

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

@@ -0,0 +1,27 @@
+/**
+ * A sentence's code spans, read as CommonMark reads them: a run of backticks opens a span that the next run of the same
+ * length closes, so a span holding a backtick is written with a longer run of them. Used by `CodeText.tsx`, and by
+ * what writes a sentence around a type that may hold backticks (a template literal type).
+ *
+ * @module
+ */
+/** One piece of a sentence: text, or code. */
+export type SentencePiece = {
+    /** The piece's text, a code span's without its backticks. */
+    readonly text: string;
+    /** Whether it is code. */
+    readonly isCode: boolean;
+};
+/**
+ * A sentence split into text and code spans. A run of backticks no run of the same length closes stays text.
+ *
+ * @param sentence - the sentence.
+ */
+export declare const sentencePieces: (sentence: string) => SentencePiece[];
+/**
+ * A text written as one code span, whatever backticks it holds: a run longer than any inside, with a space each side
+ * when the text starts or ends with a backtick.
+ *
+ * @param text - the code.
+ */
+export declare const codeSpan: (text: string) => string;

package/dist/src/shell/codeSpans.js

@@ -0,0 +1,76 @@
+/**
+ * A sentence's code spans, read as CommonMark reads them: a run of backticks opens a span that the next run of the same
+ * length closes, so a span holding a backtick is written with a longer run of them. Used by `CodeText.tsx`, and by
+ * what writes a sentence around a type that may hold backticks (a template literal type).
+ *
+ * @module
+ */
+/** A code span's text as CommonMark trims it: one space each side, when both are there and it is not only spaces. */
+const trimmedSpan = (text) => text.length >= 2 && text.startsWith(" ") && text.endsWith(" ") && text.trim() !== ""
+    ? text.slice(1, -1)
+    : text;
+/**
+ * A sentence split into text and code spans. A run of backticks no run of the same length closes stays text.
+ *
+ * @param sentence - the sentence.
+ */
+export const sentencePieces = (sentence) => {
+    const pieces = [];
+    let text = "";
+    let at = 0;
+    while (at < sentence.length) {
+        const open = sentence.indexOf("`", at);
+        if (open === -1)
+            break;
+        let length = 1;
+        while (sentence[open + length] === "`")
+            length += 1;
+        const close = closingRun(sentence, open + length, length);
+        if (close === -1) {
+            text += sentence.slice(at, open + length);
+            at = open + length;
+            continue;
+        }
+        text += sentence.slice(at, open);
+        if (text !== "")
+            pieces.push({ text, isCode: false });
+        text = "";
+        pieces.push({ text: trimmedSpan(sentence.slice(open + length, close)), isCode: true });
+        at = close + length;
+    }
+    text += sentence.slice(at);
+    if (text !== "")
+        pieces.push({ text, isCode: false });
+    return pieces;
+};
+/**
+ * Where the run of exactly `length` backticks that closes a span starts, or -1.
+ *
+ * @param sentence - the sentence.
+ * @param from - where the span's text starts.
+ * @param length - the opening run's length.
+ */
+const closingRun = (sentence, from, length) => {
+    let at = sentence.indexOf("`", from);
+    while (at !== -1) {
+        let run = 1;
+        while (sentence[at + run] === "`")
+            run += 1;
+        if (run === length)
+            return at;
+        at = sentence.indexOf("`", at + run);
+    }
+    return -1;
+};
+/**
+ * A text written as one code span, whatever backticks it holds: a run longer than any inside, with a space each side
+ * when the text starts or ends with a backtick.
+ *
+ * @param text - the code.
+ */
+export const codeSpan = (text) => {
+    const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(longest + 1);
+    const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+    return `${fence}${padding}${text}${padding}${fence}`;
+};