forgebook 0.3.3 → 0.4.1

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;

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.js

@@ -29,7 +29,8 @@ 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;
@@ -40,7 +41,11 @@ export const showAsideStory = (target, title, aside) => {
         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;
+        if (event.data.type === "forgebook:scheme")
+            frame.style.colorScheme = event.data.scheme;
+        if (event.data.type !== "forgebook:ready")
             return;
         isReady = true;
         if (args !== undefined)

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;