forgebook 0.3.2 → 0.4.0

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

@@ -10,8 +10,11 @@ import { type AddressTexts } from "../addressTexts.ts";
 import type { CatalogueLists } from "../catalogue.ts";
 import type { ViewSwitch } from "../switches.ts";
 import type { WrittenHomeProps } from "./AuthoredHome.tsx";
+import type { ArgControlLoaders } from "./customControls.ts";
 import { type LoadPluginHosts } from "./pluginHostsContext.ts";
 import type { ShellPlugin } from "./pluginTabs.tsx";
+import type { ShellRefs } from "./refParts.tsx";
+import { type ToolbarProps } from "./Toolbar.tsx";
 /** What an app passes to the shell. */
 export type ShellConfig = {
     /** The catalogue's name, in the page title and the sidebar. */
@@ -30,6 +33,8 @@ export type ShellConfig = {
     readonly heights?: string;
     /** The sources, in the order the sidebar lists them. */
     readonly sources: readonly StorySource[];
+    /** The catalogue's own story patterns, for a home with no story to say where it looks; none by default. */
+    readonly storyGlobs?: readonly string[];
     /**
      * The frame page's address: relative to the shell's (`frame.html`) when the frames share its origin, on the frames'
      * origin otherwise (`mountShell` makes it).
@@ -55,6 +60,13 @@ export type ShellConfig = {
     readonly home?: () => Promise<ComponentType<WrittenHomeProps>>;
     /** Loads the catalogue's design tokens, on first use; none when it has none. */
     readonly loadTokens?: () => Promise<unknown>;
+    /**
+     * Loads the previews of the catalogue's galleries, when one first opens; none when it gives none. The generated page
+     * gives what the configuration's check allowed; the page checks nothing itself.
+     */
+    readonly loadSwitchPreviews?: ToolbarProps["loadSwitchPreviews"];
+    /** Loads each custom control `argControls` registers, by name; none when it registers none. */
+    readonly argControls?: ArgControlLoaders;
     /** The plugins with views (the generated page passes them); none by default. */
     readonly plugins?: readonly ShellPlugin[];
     /**
@@ -67,6 +79,12 @@ export type ShellConfig = {
      * texts that are not plain words from a story that may write them into markup. `any` by default.
      */
     readonly addressTexts?: AddressTexts;
+    /**
+     * Other catalogues, built and deployed, listed after this one's stories and shown read-only (`catalogueRefs.ts`), and
+     * the code that draws them (`forgebook/shell/refs`): the generated page gives them only for a catalogue that has some,
+     * so the others' first load carries none of it. None by default.
+     */
+    readonly refs?: ShellRefs;
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its

package/dist/src/shell/Shell.js

@@ -1,17 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { addressArgsFor } from "../addressTexts.js";
+import { readArgsParam, readStorybookLink } from "../addressArgsParam.js";
+import { addressArgsRead } from "../addressTexts.js";
 import { deviceDefaultOf, pageDeviceDefault } from "../deviceView.js";
-import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
+import { panelArgsParam } from "../messages.js";
 import { anchorOf } from "../pageAddress.js";
 import { findPage } from "../pageTree.js";
 import { sourceFiles } from "../sourceFiles.js";
 import { storyBackground } from "../storyBackground.js";
 import { NOT_FIXED } from "../storyGlobals.js";
 import { knownHeight } from "../storyHeights.js";
-import { componentId, findComponent, findComponentByTitle, findStory, isLogicComponent, sidebarStoryIds, storyTree } from "../storyTree.js";
+import { componentId, findComponent, findComponentByTitle, findStory, isLogicComponent, sidebarStoryIds, storyOfAddress, storyTree } from "../storyTree.js";
 import { parseView, viewParams } from "../viewState.js";
 import { CatalogueContext, NO_PLUGINS, useCatalogue, useConfiguredCatalogue } from "./catalogueContext.js";
+import { HAS_REFS, shellRefs } from "./composition.js";
 import { filesCodeLoader } from "./filesCode.js";
 import { Icon } from "./icons.js";
 import { LazyPage } from "./LazyPage.js";
@@ -19,16 +21,20 @@ import { LogicMark } from "./LogicMark.js";
 import { lazyModule } from "./lazyModule.js";
 import { PluginHostsContext } from "./pluginHostsContext.js";
 import { Sidebar } from "./Sidebar.js";
-import { SidebarEdge } from "./SidebarHandle.js";
+import { SidebarShade } from "./SidebarHandle.js";
 import { Stage } from "./Stage.js";
 import { StoryPicker } from "./StoryPicker.js";
 import { STRINGS } from "./strings.js";
 import { ShowSidebarButton, Toolbar } from "./Toolbar.js";
 import { useAppearance } from "./useAppearance.js";
+import { useEditedProblems } from "./useEditedProblems.js";
+import { useListedTree } from "./useListedTree.js";
 import { useRecentPages } from "./useRecentPages.js";
+import { useShortcutHelp } from "./useShortcutHelp.js";
 import { useShownView } from "./useShownView.js";
 import { useSidebarLayout } from "./useSidebarLayout.js";
 import { useSidebarOverlay } from "./useSidebarOverlay.js";
+import { readStored } from "./useStored.js";
 import { useStoryHeights } from "./useStoryHeights.js";
 import { useStoryIdsElement } from "./useStoryIdsElement.js";
 import { useStoryKeys } from "./useStoryKeys.js";
@@ -37,6 +43,15 @@ import { useSystemDark } from "./useSystemDark.js";
 const DOC_PAGE = lazyModule(() => import("./DocPage.js").then((module) => module.DocPage));
 /** The home, loaded when it is opened. */
 const HOME_PAGE = lazyModule(() => import("./HomePage.js").then((module) => module.HomePage));
+/** The address's parameter that names a composed catalogue; its story is in `story`, as a story of this one's is. */
+const REF_PARAMETER = "ref";
+/**
+ * A part of the composed catalogues, once its module is there; nothing for a catalogue that composes none, or on a page
+ * that shows none of their stories.
+ *
+ * @param props - the module, if any, and the part's props; none when there is nothing to draw.
+ */
+const RefSlot = ({ refs, part }) => refs === undefined || part === undefined ? null : (_jsx(LazyPage, { module: refsModuleOf(refs), header: null, pageProps: part }));
 /** A component's page, loaded when one is opened. */
 const COMPONENT_PAGE = lazyModule(() => import("./ComponentPage.js").then((module) => module.ComponentPage));
 /**
@@ -51,6 +66,8 @@ const HOME = { kind: "home" };
 const pageKey = (page) => {
     if (page.kind === "home")
         return page.kind;
+    if (HAS_REFS && page.kind === "ref")
+        return `ref:${page.ref}/${page.id}`;
     // a heading is a place of its own in the history: Back from it returns to where the reader was
     return page.kind === "story" ? `story:${page.id}` : `${page.kind}:${page.id}#${page.anchor ?? ""}`;
 };
@@ -85,16 +102,20 @@ const drawnWidth = (width, fill) => (width === "fill" ? fill : width);
  */
 const stageHeight = (heights, storyId, width, shownWidth) => knownHeight(heights, storyId, drawnWidth(width, shownWidth ?? FILL_WIDTH));
 /**
- * The page an address's query and fragment name: a story wins, then a component, then a docs page; none is the home.
+ * The page an address's query and fragment name: a composed catalogue's story wins, then a story, a component, a docs
+ * page; none is the home.
  *
  * @param search - the address's query.
  * @param hash - its fragment.
  */
 const pageOf = (search, hash) => {
     const params = new URLSearchParams(search);
-    const story = params.get("story");
+    const story = storyOfAddress(params);
     const component = params.get("component");
     const page = params.get("page");
+    const ref = HAS_REFS ? params.get(REF_PARAMETER) : null;
+    if (ref !== null && story !== null)
+        return { kind: "ref", ref, id: story };
     if (story !== null)
         return { kind: "story", id: story };
     const anchor = anchorOf(hash.replace(/^#/, ""));
@@ -112,32 +133,50 @@ const pageOf = (search, hash) => {
  */
 const readAddress = (catalogue, addressTexts) => {
     const params = new URLSearchParams(window.location.search);
+    const param = params.get("args");
     return {
         page: pageOf(window.location.search, window.location.hash),
         view: parseView(window.location.search, catalogue),
-        panelArgs: addressArgsFor(parsePanelArgsParam(params.get("args")), addressTexts),
-        matrix: (params.get("matrix") ?? "").split(",").filter((name) => name !== "")
+        ...addressArgsRead(readArgsParam(param), param, addressTexts),
+        matrix: (params.get("matrix") ?? "").split(",").filter((name) => name !== ""),
+        tags: params.getAll("tag").filter((tag) => tag !== "" && tag !== "!")
     };
 };
+/**
+ * Writes a composed catalogue's story into an address's parameters; nothing for another page.
+ *
+ * @param params - the parameters.
+ * @param page - the page.
+ */
+const writeRefPage = (params, page) => {
+    if (page.kind !== "ref")
+        return;
+    params.set(REF_PARAMETER, page.ref);
+    params.set("story", page.id);
+};
 /**
  * The query of an address.
  *
  * @param address - the page, the view, the panel's values and the matrix's axes.
  * @param catalogue - the catalogue's switches and default audience, for the view's values.
  */
-const addressQuery = ({ page, view, panelArgs, matrix }, catalogue) => {
-    const params = viewParams(view, catalogue.switches, catalogue.audience);
+const addressQuery = ({ page, view, panelArgs, link, matrix, tags }, catalogue) => {
+    const params = viewParams(view, catalogue.switches, catalogue.audience, catalogue.play);
+    if (HAS_REFS)
+        writeRefPage(params, page);
     if (page.kind === "story")
         params.set("story", page.id);
     if (page.kind === "component")
         params.set("component", page.id);
     if (page.kind === "page")
         params.set("page", page.id);
-    const args = page.kind === "story" ? panelArgsParam(panelArgs) : "";
+    const args = page.kind === "story" ? (link?.param ?? panelArgsParam(panelArgs)) : "";
     if (args !== "")
         params.set("args", args);
     if (page.kind === "story" && matrix.length > 0)
         params.set("matrix", matrix.join(","));
+    for (const tag of tags)
+        params.append("tag", tag);
     const query = params.toString();
     // the fragment is part of what is written back on every change of the view, or a change would lose the heading
     const fragment = (page.kind === "page" || page.kind === "component") && page.anchor !== undefined
@@ -145,7 +184,27 @@ const addressQuery = ({ page, view, panelArgs, matrix }, catalogue) => {
         : "";
     return `${query === "" ? window.location.pathname : `?${query}`}${fragment}`;
 };
-/** What the address's page shows: a story or a component that is not there (renamed, removed) says so, never another. */
+/**
+ * What the address's page shows in a catalogue that composes others: a composed catalogue's story, or what `shownPage`
+ * said. A `ref` that names no composed catalogue is another site's mark (`?ref=newsletter`): the story is this
+ * catalogue's.
+ *
+ * @param tree - the tree.
+ * @param page - the address's page.
+ * @param refs - the composed catalogues, if any.
+ * @param shown - what `shownPage` said of it.
+ */
+const shownRef = (tree, page, refs, shown) => {
+    if (page.kind !== "ref")
+        return shown;
+    return refs?.catalogues.some((each) => each.id === page.ref)
+        ? { kind: "ref", place: { refId: page.ref, storyId: page.id } }
+        : shownPage(tree, { kind: "story", id: page.id });
+};
+/**
+ * What the address's page shows: a story or a component that is not there (renamed, removed) says so, never another. A
+ * composed catalogue's story is `shownRef`'s.
+ */
 const shownPage = (tree, page) => {
     if (page.kind === "story") {
         const location = findStory(tree, page.id);
@@ -188,6 +247,37 @@ const isLogicPage = (shown) => {
 };
 /** The shown component's place, a story's too; none on any other page. */
 const componentLocationOf = (shown) => shown.kind === "story" || shown.kind === "component" ? shown.location : undefined;
+/** The shown story of a composed catalogue; none on any other page. */
+const refPlaceOf = (shown) => shown.kind === "ref" ? shown.place : undefined;
+/** The page of a composed catalogue's story. */
+const refPageOf = ({ refId, storyId }) => ({ kind: "ref", ref: refId, id: storyId });
+/** The composed catalogues' code, once a part of it was first drawn: a page holds one shell, with one configuration. */
+let refsModule;
+/** The composed catalogues' code, loaded when a part of it is first drawn. */
+const refsModuleOf = (refs) => {
+    refsModule ??= lazyModule(refs.load);
+    return refsModule;
+};
+/**
+ * What the composed catalogues add to the shown page: their sidebar sections, and a story's page when one is shown;
+ * nothing for a catalogue that composes none.
+ *
+ * @param refs - the composed catalogues, if any.
+ * @param current - the shown story of one of them, if any.
+ * @param links - how a story of theirs is linked and opened.
+ * @param switches - this catalogue's switches, with the view's values.
+ */
+const refSlotsOf = (refs, current, links, switches) => {
+    if (refs === undefined)
+        return { sidebar: {}, page: null };
+    const page = current === undefined ? undefined : { place: "page", refs: refs.catalogues, ...current, switches };
+    return {
+        sidebar: {
+            composed: _jsx(RefSlot, { refs: refs, part: { place: "sidebar", refs: refs.catalogues, current, ...links } })
+        },
+        page: _jsx(RefSlot, { refs: refs, part: page })
+    };
+};
 /** The shown docs page's place; none on any other page. */
 const pageLocationOf = (shown) => shown.kind === "page" ? shown.location : undefined;
 /** Whether nothing shown follows the view's switches: the home, or a docs page without a story. */
@@ -324,7 +414,7 @@ const RelatedLinks = ({ related, hrefOf, onOpen }) => related.length === 0 ? nul
  * @param props - the problems, the shown component's place, the message when a named page is missing, the picker
  * of the component's stories, and the related components.
  */
-const ShellHeader = ({ problems, location, page, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("p", { className: "forgebook-empty", role: "alert", children: message })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
+const ShellHeader = ({ problems, location, page, message, picker, related, isLogic }) => (_jsxs(_Fragment, { children: [problems.length > 0 ? (_jsxs("div", { className: "forgebook-problems", role: "alert", children: [_jsx("strong", { children: STRINGS.indexProblems }), _jsx("ul", { children: problems.map((problem) => (_jsx("li", { children: problem }, problem))) })] })) : null, message === undefined ? null : (_jsx("div", { role: "alert", children: _jsx("h1", { className: "forgebook-empty", children: message }) })), location === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsxs("p", { className: "forgebook-header__path", children: [[location.source.name, location.family.name, location.group.name]
                             .filter((part) => part !== undefined)
                             .join(" · "), location.component.alsoIn.length === 0 ? null : (_jsxs("span", { className: "forgebook-header__also-in", children: [" · ", STRINGS.alsoIn(location.component.alsoIn.map((place) => place.split("/").join(" › ")).join(", "))] }))] }), _jsxs("div", { className: "forgebook-header__row", children: [_jsx("h1", { className: "forgebook-header__title", children: location.component.name }), isLogic ? _jsx(LogicMark, {}) : null, picker, location.component.design === undefined ? null : (_jsxs("a", { className: "forgebook-button", href: location.component.design.url, target: "_blank", rel: "noopener noreferrer", children: [_jsx(Icon, { name: "external", size: 14 }), STRINGS.openInFigma] }))] }), related] })), page === undefined ? null : (_jsxs("header", { className: "forgebook-header", children: [_jsx("p", { className: "forgebook-header__path", children: [page.source.name, page.page.group].filter((part) => part !== undefined).join(" · ") }), _jsx("div", { className: "forgebook-header__row", children: _jsx("h1", { className: "forgebook-header__title", children: page.page.name }) })] }))] }));
 /** A story's page. */
@@ -357,12 +447,23 @@ const useAddress = (catalogue, addressTexts) => {
         window.addEventListener("popstate", onBack);
         return () => window.removeEventListener("popstate", onBack);
     }, [catalogue, addressTexts]);
+    // a link in Storybook's form has its reader loaded for it; a value changed meanwhile, or another page, has the last word
+    const waitingParam = address.link?.isWaiting === true ? address.link.param : undefined;
+    useEffect(() => {
+        if (waitingParam === undefined)
+            return;
+        void readStorybookLink(waitingParam, ({ readStorybookArgs }, param) => readStorybookArgs(param)).then((read) => setAddress((current) => current.link?.isWaiting === true && current.link.param === waitingParam
+            ? { ...current, ...addressArgsRead(read, waitingParam, addressTexts) }
+            : current));
+    }, [waitingParam, addressTexts]);
     // a height set with the foot handle belongs to the story it was set on: another page starts at its own
     const pageAddress = (page) => ({
         page,
         view: { ...address.view, height: "auto" },
         panelArgs: {},
-        matrix: []
+        link: undefined,
+        matrix: [],
+        tags: address.tags
     });
     const open = (page, movesFocus) => {
         const next = pageAddress(page);
@@ -411,8 +512,9 @@ const useOwnPageId = (address, ownPage, replaceAddress) => {
  *
  * @param props - the configuration.
  */
-const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addressTexts = "any", plugins = NO_PLUGINS, loadTokens, home }) => {
+const ShellPage = ({ title, logo, hasBranding, heights, sources, storyGlobs, frameUrl, addressTexts = "any", plugins = NO_PLUGINS, loadTokens, loadSwitchPreviews, argControls, home }) => {
     const tree = useMemo(() => storyTree(sources), [sources]);
+    const problems = useEditedProblems(tree.problems);
     // the written home's module, loaded when the home is first opened
     const writtenHome = useMemo(() => (home === undefined ? undefined : lazyModule(home)), [home]);
     const idsByTitle = useMemo(() => componentIdsByTitle(tree), [tree]);
@@ -440,7 +542,18 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
     const isSystemDark = useSystemDark();
     const appearance = useAppearance(address.view, catalogue.switches);
     useStoryIdsElement(useMemo(() => sidebarStoryIds(tree, catalogue.storyGroups.map((group) => group.id)), [tree, catalogue.storyGroups]));
-    const shown = shownPage(tree, address.page);
+    const { help, showHelp } = useShortcutHelp();
+    let shown = shownPage(tree, address.page);
+    // what composition adds to the page; the build removes this whole block from a catalogue that composes none
+    let refSlots;
+    if (HAS_REFS) {
+        const refs = shellRefs();
+        shown = shownRef(tree, address.page, refs, shown);
+        refSlots = refSlotsOf(refs, refPlaceOf(shown), {
+            refStoryHref: (place) => addressQuery(pageAddress(refPageOf(place)), catalogue),
+            onOpenRefStory: (place) => openPage(refPageOf(place))
+        }, address.view.switches);
+    }
     const location = componentLocationOf(shown);
     const ownPage = recentPageOf(shown);
     const recent = useRecentPages(ownPage);
@@ -463,16 +576,18 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         catalogueDevice: catalogue.device,
         onAddressViewChange: changeView
     });
-    useStoryKeys(tree, shownStoryId, shown.kind === "component" ? shown.location.component.stories[0]?.id : undefined, (id) => openPage({ kind: "story", id }));
+    const listedTree = useListedTree(tree, address.tags);
+    useStoryKeys(listedTree, shownStoryId, shown.kind === "component" ? shown.location.component.stories[0]?.id : undefined, (id) => openPage({ kind: "story", id }));
     const source = sources.find((candidate) => candidate.id === location?.source.id);
     const files = source === undefined ? undefined : sourceFiles(source);
     const storyHrefOf = (story) => addressQuery(pageAddress(storyPage(story)), catalogue);
     const columnHeightOf = (storyId) => knownHeight(storyHeights, storyId, drawnWidth(address.view.width, PAGE_COLUMN_WIDTH));
-    const header = (_jsx(ShellHeader, { problems: tree.problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
+    const header = (_jsx(ShellHeader, { problems: problems, location: location, page: shownPageLocation, isLogic: isLogicPage(shown), message: shown.kind === "missing" ? shown.message : undefined, picker: location === undefined ? null : (_jsx(StoryPicker, { component: location.component, currentStoryId: shownStoryId, onOpenComponent: () => openPage(componentPage(location.component)), onOpenStory: (story) => openPage(storyPage(story)) })), related: _jsx(RelatedLinks, { related: relatedComponents(tree, location), hrefOf: (page) => addressQuery(pageAddress(page), catalogue), onOpen: openPage }) }));
     const homeProps = {
         title,
         tree,
         sources,
+        storyGlobs,
         recent,
         hrefOf: (page) => addressQuery(pageAddress(page), catalogue),
         onOpen: (page) => openPage(page),
@@ -496,9 +611,9 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
         header,
         scroll
     };
-    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, isOpen: isSidebarOpen, isOverlay: isSidebarOverlay, sidebarRef: sidebarRef, hideButtonRef: hideButtonRef, onHide: hideSidebar, onShow: showSidebar, appearance: appearance, title: title, logo: logo, hasBranding: hasBranding !== false, tree: tree, sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), _jsx(SidebarEdge, { isOverlay: isSidebarOverlay, isOpen: isSidebarOpen, width: sidebarWidth, onWidthChange: setSidebarWidth, onHide: hideSidebar }), _jsxs("main", { className: "forgebook-main", inert: isSidebarOver, children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), 
+    return (_jsxs("div", { className: "catalogue", children: [_jsx(Sidebar, { width: sidebarWidth, onWidthChange: setSidebarWidth, isOpen: isSidebarOpen, isOverlay: isSidebarOverlay, sidebarRef: sidebarRef, hideButtonRef: hideButtonRef, onHide: hideSidebar, onShow: showSidebar, appearance: appearance, onShowKeys: showHelp, title: title, logo: logo, hasBranding: hasBranding !== false, tree: listedTree, wholeTree: tree, tags: address.tags, onTagsChange: (tags) => replaceAddress({ ...address, tags }), sources: sources, searchHref: (target) => addressQuery(pageAddress(target), catalogue), onOpenResult: openFound, isHome: shown.kind === "home", homeHref: addressQuery(pageAddress(HOME), catalogue), onOpenHome: () => openPage(HOME), current: sidebarCurrent(location, shownStoryId), currentPageId: shownPageLocation?.page.id, pageHref: (id) => addressQuery(pageAddress({ kind: "page", id }), catalogue), onOpenPage: (id) => openPage({ kind: "page", id }), ...refSlots?.sidebar, componentHref: (sourceId, componentTitle) => addressQuery(pageAddress(titledPage(idsByTitle, sourceId, componentTitle)), catalogue), onOpenComponent: (sourceId, componentTitle) => openPage(titledPage(idsByTitle, sourceId, componentTitle)) }), help, _jsx(SidebarShade, { isOverlay: isSidebarOverlay, isOpen: isSidebarOpen, onHide: hideSidebar }), _jsxs("main", { className: "forgebook-main", inert: isSidebarOver, children: [_jsx(ShellBar, { isHome: hasNoStories(shown), view: shownView, onViewChange: changeShownView, isStoryPage: shown.kind === "story", isComponentPage: shown.kind === "component", isLogic: isLogicPage(shown), 
                         // under a sidebar lying over the page the button stays, so the bar's controls never move behind it
-                        onShowSidebar: isSidebarOpen && !isSidebarOver ? undefined : showSidebar, showSidebarRef: showButtonRef, shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown) }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
+                        onShowSidebar: isSidebarOpen && !isSidebarOver ? undefined : showSidebar, showSidebarRef: showButtonRef, shownWidth: shown.kind === "story" ? shownWidth : undefined, fixed: fixedOfShown(fixedViews, shown), deviceDefault: deviceOfShown(catalogue.device, shown), loadSwitchPreviews: loadSwitchPreviews }), shown.kind === "component" ? (_jsx(LazyPage, { module: COMPONENT_PAGE, header: header, pageProps: {
                             component: shown.location.component,
                             anchor: shown.anchor,
                             view: address.view,
@@ -528,7 +643,7 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
                             anchor: shown.anchor,
                             onOpenPage: (id) => openPage({ kind: "page", id }),
                             onOpenAnchor: openAnchor
-                        } }, shown.location.page.id)) : null, shown.kind === "story" ? (_jsx(Stage, { component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, plugins: plugins, ...storyLoaders(files, shown.location.story), namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, shown.kind === "missing" ? header : null] })] }));
+                        } }, shown.location.page.id)) : null, shown.kind === "story" ? (_jsx(Stage, { loadTokens: loadTokens, argControls: argControls, component: shown.location.component, story: shown.location.story, view: shownView, onViewChange: changeShownView, onFixedChange: (storyId, fixed) => setFixedViews((current) => new Map(current).set(storyId, fixed)), panelArgs: address.panelArgs, addressLink: address.link, onPanelArgsChange: (panelArgs) => replaceAddress({ ...address, panelArgs, link: undefined }), matrixAxes: address.matrix, onMatrixAxesChange: (matrix) => replaceAddress({ ...address, matrix }), frameUrl: frameUrl, plugins: plugins, ...storyLoaders(files, shown.location.story), namedValues: source?.namedValues, header: header, onShownWidthChange: setShownWidth, scroll: scroll, backgroundOf: (view) => storyBackground(shown.location.source.background, view, catalogue, isSystemDark), measuredHeight: stageHeight(storyHeights, shown.location.story.id, address.view.width, shownWidth) })) : null, refSlots?.page, shown.kind === "missing" ? header : null] })] }));
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its
@@ -536,4 +651,4 @@ const ShellPage = ({ title, logo, hasBranding, heights, sources, frameUrl, addre
  *
  * @param props - the configuration.
  */
-export const Shell = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props), children: _jsx(PluginHostsContext.Provider, { value: props.pluginHosts, children: _jsx(ShellPage, { ...props }) }) }));
+export const Shell = (props) => (_jsx(CatalogueContext.Provider, { value: useConfiguredCatalogue(props, readStored), children: _jsx(PluginHostsContext.Provider, { value: props.pluginHosts, children: _jsx(ShellPage, { ...props }) }) }));

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

@@ -0,0 +1,22 @@
+/**
+ * The list of the shell's keys, in a modal dialog, with the switch that turns the keys without a modifier off.
+ *
+ * @remarks
+ * The platform's modal dialog holds the focus, closes on Escape and gives the focus back. A frame keeps its own keys, so
+ * the list says these work only outside a story. Loaded when first opened (`useShortcutHelp.tsx`).
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import "./shortcutHelp.scss";
+/** The list's props. */
+export type ShortcutHelpProps = {
+    /** Called when the list closes. */
+    readonly onClose: () => void;
+};
+/**
+ * The list.
+ *
+ * @param props - what to call when it closes.
+ */
+export declare const ShortcutHelp: ({ onClose }: ShortcutHelpProps) => ReactNode;

package/dist/src/shell/ShortcutHelp.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The list of the shell's keys, in a modal dialog, with the switch that turns the keys without a modifier off.
+ *
+ * @remarks
+ * The platform's modal dialog holds the focus, closes on Escape and gives the focus back. A frame keeps its own keys, so
+ * the list says these work only outside a story. Loaded when first opened (`useShortcutHelp.tsx`).
+ *
+ * @module
+ */
+import { useEffect, useRef, useState } from "react";
+import { shownKeys } from "../controlKeys.js";
+import { catalogueControls } from "../toolbarLayout.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { controlLabel } from "./controlLabel.js";
+import { SINGLE_KEYS_STORED } from "./keyboard.js";
+import "./shortcutHelp.css";
+import { textsOfGroup } from "./strings.js";
+import { readStored, writeStored } from "./useStored.js";
+import { readKeys } from "./useToolbarLayout.js";
+/** The list's texts, as shown: Forgebook's, with the catalogue's replacements. */
+const HELP_STRINGS = textsOfGroup("shortcuts", {
+    title: "Keyboard keys",
+    note: "They work while the focus is outside a story: a story keeps every key pressed inside it.",
+    search: "Go to the search",
+    previous: "Previous story",
+    next: "Next story",
+    help: "This list",
+    close: "Close",
+    singleKeys: "Keys without a modifier",
+    singleKeysNote: "Off, only the search's key with a modifier stays. This browser remembers it.",
+    control: (label) => `Next value of ${label}; Shift for the one before`
+});
+/** The key with the platform's modifier that goes to the search. */
+const searchKey = () => (/Mac|iPhone|iPad/.test(navigator.platform) ? "⌘ K" : "Ctrl K");
+/**
+ * The list.
+ *
+ * @param props - what to call when it closes.
+ */
+export const ShortcutHelp = ({ onClose }) => {
+    const catalogue = useCatalogue();
+    const dialogRef = useRef(null);
+    const [isOn, setIsOn] = useState(() => readStored(SINGLE_KEYS_STORED) !== "off");
+    useEffect(() => {
+        dialogRef.current?.showModal();
+    }, []);
+    const keys = shownKeys(catalogue.keys, readKeys(readStored(`${catalogue.id}:toolbar-keys`)));
+    const controlRows = catalogueControls(catalogue).flatMap((control) => {
+        const key = keys[control.id];
+        return key === undefined
+            ? []
+            : [{ keys: [key.toUpperCase()], text: HELP_STRINGS.control(controlLabel(control)) }];
+    });
+    const rows = [
+        { keys: ["/", searchKey()], text: HELP_STRINGS.search },
+        { keys: ["["], text: HELP_STRINGS.previous },
+        { keys: ["]"], text: HELP_STRINGS.next },
+        ...controlRows,
+        { keys: ["?"], text: HELP_STRINGS.help }
+    ];
+    return (_jsxs("dialog", { ref: dialogRef, className: "forgebook-keys", "aria-label": HELP_STRINGS.title, onClose: onClose, children: [_jsx("h2", { className: "forgebook-keys__title", children: HELP_STRINGS.title }), _jsx("p", { className: "forgebook-keys__note", children: HELP_STRINGS.note }), _jsx("dl", { className: "forgebook-keys__list", children: rows.map((row) => (_jsxs("div", { className: "forgebook-keys__row", children: [_jsx("dt", { children: row.keys.map((key) => (_jsx("kbd", { className: "forgebook-keys__key", children: key }, key))) }), _jsx("dd", { children: row.text })] }, row.text))) }), _jsxs("label", { className: "forgebook-keys__switch", children: [_jsx("input", { type: "checkbox", checked: isOn, onChange: (event) => {
+                            setIsOn(event.target.checked);
+                            writeStored(SINGLE_KEYS_STORED, event.target.checked ? "on" : "off");
+                        } }), _jsxs("span", { children: [HELP_STRINGS.singleKeys, _jsx("small", { className: "forgebook-keys__note", children: HELP_STRINGS.singleKeysNote })] })] }), _jsx("form", { method: "dialog", className: "forgebook-keys__foot", children: _jsx("button", { type: "submit", className: "forgebook-button", children: HELP_STRINGS.close }) })] }));
+};

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

@@ -6,7 +6,8 @@
  * component by its
  * name, its place, its meta's search words or its stories' names and descriptions. A component listed in other places too (`alsoIn`) has an
  * alias entry in each, beside the components that live there, which says where it lives and opens its page. Docs pages
- * come first, in a section of their own (`SidebarDocs.tsx`).
+ * come first, in a section of their own (`SidebarDocs.tsx`); other catalogues composed with `refs` come last
+ * (`SidebarRefs.tsx`).
  *
  * @module
  */
@@ -14,7 +15,7 @@ import type { StorySource } from "@forgebook/story-format/source";
 import { type ReactNode, type Ref } from "react";
 import type { SearchTarget } from "../search.ts";
 import type { StoryTree } from "../storyTree.ts";
-import { type SidebarPageLinks } from "./SidebarDocs.tsx";
+import type { SidebarPageLinks } from "./SidebarDocs.tsx";
 import { type ShownComponent } from "./SidebarEntries.tsx";
 import type { AppearanceState } from "./useAppearance.ts";
 /** The sidebar's props. */
@@ -25,8 +26,14 @@ export type SidebarProps = SidebarPageLinks & {
     readonly logo: string | undefined;
     /** Whether a catalogue without a logo shows Forgebook's mark. */
     readonly hasBranding: boolean;
-    /** The tree. */
+    /** The tree it lists: what the tag filter keeps. */
     readonly tree: StoryTree;
+    /** The whole tree, whose tags the filter offers. */
+    readonly wholeTree: 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 sources, for the search's index. */
     readonly sources: readonly StorySource[];
     /** The address of a search's result. */
@@ -52,6 +59,8 @@ export type SidebarProps = SidebarPageLinks & {
     readonly onOpenComponent: (sourceId: string, title: string) => void;
     /** The sidebar's width, in CSS px. */
     readonly width: number;
+    /** Sets the sidebar's width, from its handle. */
+    readonly onWidthChange: (width: number) => void;
     /** Whether it is shown: hidden, it slides out and stays mounted, so its search and open families come back with it. */
     readonly isOpen: boolean;
     /** Whether it lies over the page and not beside it, on a narrow window. */
@@ -66,10 +75,14 @@ export type SidebarProps = SidebarPageLinks & {
     readonly onShow: () => void;
     /** The shell's appearance and its setter, for the menu at the foot. */
     readonly appearance: AppearanceState;
+    /** Opens the list of the shell's keys. */
+    readonly onShowKeys: () => void;
+    /** What is listed after this catalogue's stories when no search or tag narrows them: the composed catalogues. */
+    readonly composed?: ReactNode;
 };
 /**
  * The sidebar.
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export declare const Sidebar: ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, ...links }: SidebarProps) => ReactNode;
+export declare const Sidebar: ({ title, logo, hasBranding, tree, wholeTree, tags, onTagsChange, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, onWidthChange, isOpen, isOverlay, sidebarRef, hideButtonRef, onHide, onShow, appearance, onShowKeys, ...links }: SidebarProps) => ReactNode;