forgebook 0.3.2 → 0.4.0

package/dist/src/shell/Sidebar.js

@@ -1,12 +1,24 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { hasFilterTags } from "../storyTagNames.js";
 import { AppearanceMenu } from "./AppearanceMenu.js";
+import { HAS_REFS } from "./composition.js";
 import { FORGEBOOK_MARK_URL } from "./forgebookMark.js";
 import { Icon } from "./icons.js";
-import { SidebarDocs } from "./SidebarDocs.js";
+import { LazyView, lazyModule } from "./lazyModule.js";
 import { FamilyGroup, TreeFold } from "./SidebarEntries.js";
+import { SidebarHandle } from "./SidebarHandle.js";
 import { SidebarSearch } from "./SidebarSearch.js";
 import { STRINGS } from "./strings.js";
+import { TagViewSlot } from "./tagView.js";
+/** The docs pages' section, loaded only for a catalogue that has some. */
+const SIDEBAR_DOCS = lazyModule(() => import("./SidebarDocs.js").then((module) => module.SidebarDocs));
+/**
+ * The docs pages' section, once its module is there; nothing for a catalogue with no pages.
+ *
+ * @param props - the section's props.
+ */
+const LoadedDocs = (props) => props.sources.length === 0 ? null : (_jsx(LazyView, { module: SIDEBAR_DOCS, props: props, loading: null, failed: (message) => _jsx("p", { className: "forgebook-tree__empty", children: message }) }));
 /** A family's key, unique across sources. */
 const familyKey = (source, family) => `${source.id}/${family.name}`;
 /** A named group's key, unique across sources and families. */
@@ -37,7 +49,7 @@ const currentGroupOf = (tree, current) => {
     return family === undefined || group === undefined ? undefined : groupKey(family, group);
 };
 /** The tree as it is, with no search on. */
-const wholeTree = (tree) => ({
+const unsearchedTree = (tree) => ({
     sources: tree.sources.map((source) => ({ source, families: source.families })),
     pages: tree.sources
         .filter(({ pages }) => pages.length > 0)
@@ -45,16 +57,83 @@ const wholeTree = (tree) => ({
 });
 /** How many components a family holds. */
 const componentCount = (family) => family.groups.reduce((count, group) => count + group.components.length, 0);
+/**
+ * The families and groups the user opened or closed, and the ones a shown component opened: once open, one stays open
+ * until the user closes it, so opening a component elsewhere never folds the list under the pointer.
+ *
+ * @param tree - the tree.
+ * @param current - the shown component, if one is.
+ */
+const useFoldChoices = (tree, current) => {
+    const [foldChoices, setFoldChoices] = useState(new Map());
+    const currentFamilyKey = currentFamilyOf(tree, current);
+    const currentGroupKey = currentGroupOf(tree, current);
+    useEffect(() => {
+        const opened = [currentFamilyKey, currentGroupKey].filter((key) => key !== undefined);
+        setFoldChoices((choices) => opened.every((key) => choices.has(key))
+            ? choices
+            : new Map([
+                ...choices,
+                ...opened.filter((key) => !choices.has(key)).map((key) => [key, true])
+            ]));
+    }, [currentFamilyKey, currentGroupKey]);
+    return {
+        foldChoices,
+        setFoldOpen: (key, isOpen) => setFoldChoices((choices) => new Map(choices).set(key, isOpen))
+    };
+};
+/**
+ * The tag filter, where there is something to filter by, or on an address that names a tag: it is the way out of a list
+ * that tag emptied.
+ *
+ * @param props - the filter's props.
+ */
+const TagFilterSlot = (props) => {
+    const hasTags = useMemo(() => hasFilterTags(props.tree), [props.tree]);
+    return hasTags || props.tags.length > 0 ? _jsx(TagViewSlot, { place: "filter", ...props }) : null;
+};
+/**
+ * A family: a button that folds it, and its groups.
+ *
+ * @param props - the family, its source, what the user chose to fold, the shown page and the links.
+ */
+const FamilyEntry = ({ source, family, isNarrowed, foldChoices, onFoldChange, current, links }) => {
+    const key = familyKey(source, family);
+    const isCurrentFamily = current?.sourceId === source.id &&
+        family.groups.some((group) => group.components.some((component) => component.title === current.title));
+    const isOpen = isNarrowed || (foldChoices.get(key) ?? isCurrentFamily);
+    return (_jsxs("div", { className: "forgebook-tree__family", children: [_jsxs("button", { type: "button", className: "forgebook-tree__family-button", "aria-expanded": isOpen, onClick: () => onFoldChange(key, !isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: family.name }), _jsx("span", { className: "forgebook-tree__count", children: componentCount(family) || null })] }), _jsx(TreeFold, { isOpen: isOpen, isInstant: isNarrowed, content: () => family.groups.map((group) => {
+                    const groupOf = groupKey(key, group);
+                    const isGroupOpen = isNarrowed || (foldChoices.get(groupOf) ?? holdsCurrent(source.id, group, current));
+                    return (_jsx(FamilyGroup, { sourceId: source.id, group: group, isOpen: isGroupOpen, isInstant: isNarrowed, onToggle: () => onFoldChange(groupOf, !isGroupOpen), current: current, links: links }, group.name ?? ""));
+                }) })] }));
+};
+/**
+ * A source: its name and its families; nothing when no family is left of it.
+ *
+ * @param props - the source, its families, and what each family reads.
+ */
+const SourceEntry = ({ source, families, ...family }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((each) => (_jsx(FamilyEntry, { source: source, family: each, ...family }, familyKey(source, each))))] }));
+/**
+ * The catalogue's name and logo, the way home.
+ *
+ * @param props - the name, the logo's address if it has one, and the home's address.
+ */
+const SidebarBrand = ({ title, mark, isHome, homeHref, onOpenHome }) => (_jsx(_Fragment, { children: _jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
+                return;
+            event.preventDefault();
+            onOpenHome();
+        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }) }));
 /**
  * The sidebar.
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export 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 }) => {
+export 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 }) => {
     const [query, setQuery] = useState("");
-    const [filterTree, setFilterTree] = useState();
+    const [filterTree, setFilterTree] = useState(() => unsearchedTree);
     const showFiltered = useCallback((filter) => setFilterTree(() => filter), []);
-    const mark = logo ?? (hasBranding ? FORGEBOOK_MARK_URL : undefined);
     const navRef = useRef(null);
     // the shown component stays in sight: a page opened by a key, the picker or the address scrolls the list to it
     const currentEntry = currentPageId ?? current?.title;
@@ -65,41 +144,13 @@ export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources,
             ?.querySelector(".forgebook-tree__item[aria-current]")
             ?.scrollIntoView({ block: "nearest" });
     }, [currentEntry]);
-    // the families and groups the user opened or closed, and the ones a shown component opened: once open, one stays
-    // open until the user closes it, so opening a component elsewhere never folds the list under the pointer
-    const [foldChoices, setFoldChoices] = useState(new Map());
-    const currentFamilyKey = currentFamilyOf(tree, current);
-    const currentGroupKey = currentGroupOf(tree, current);
-    useEffect(() => {
-        const opened = [currentFamilyKey, currentGroupKey].filter((key) => key !== undefined);
-        setFoldChoices((choices) => opened.every((key) => choices.has(key))
-            ? choices
-            : new Map([
-                ...choices,
-                ...opened.filter((key) => !choices.has(key)).map((key) => [key, true])
-            ]));
-    }, [currentFamilyKey, currentGroupKey]);
+    const { foldChoices, setFoldOpen } = useFoldChoices(tree, current);
+    // the tag filter opens what it keeps, as a search does
+    const isFiltered = tags.length > 0;
     const isSearching = query.trim() !== "";
-    const isCurrentFamily = (source, family) => current?.sourceId === source.id &&
-        family.groups.some((group) => group.components.some((component) => component.title === current.title));
-    const setFoldOpen = (key, isOpen) => setFoldChoices((choices) => new Map(choices).set(key, isOpen));
+    const isNarrowed = isSearching || isFiltered;
     // the filter comes with the search's list; a moment before it, or with no words, the tree shows whole
-    const { sources, pages } = isSearching && filterTree !== undefined ? filterTree(tree, query) : wholeTree(tree);
+    const { sources, pages } = isSearching ? filterTree(tree, query) : unsearchedTree(tree);
     const hasMatches = pages.length > 0 || sources.some(({ families }) => families.length > 0);
-    return (_jsxs("aside", { ref: sidebarRef, className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, "data-overlay": isOverlay ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsxs("a", { className: "forgebook-brand__home", href: homeHref, "aria-current": isHome ? "page" : undefined, title: STRINGS.home, onClick: (event) => {
-                            if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0)
-                                return;
-                            event.preventDefault();
-                            onOpenHome();
-                        }, children: [mark === undefined ? null : (_jsx("img", { className: "forgebook-brand__logo", src: mark, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { ref: hideButtonRef, type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(SidebarDocs, { sources: pages, currentPageId: currentPageId, isSearching: isSearching, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => families.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsxs("h2", { className: "forgebook-tree__source-name", children: [source.logo === undefined ? null : (_jsx("img", { className: "forgebook-source-logo", src: source.logo, alt: "", width: 14, height: 14 })), source.name] }), families.map((family) => {
-                                const key = familyKey(source, family);
-                                // a search opens every family it finds something in
-                                const isOpen = isSearching || (foldChoices.get(key) ?? isCurrentFamily(source, family));
-                                return (_jsxs("div", { className: "forgebook-tree__family", children: [_jsxs("button", { type: "button", className: "forgebook-tree__family-button", "aria-expanded": isOpen, onClick: () => setFoldOpen(key, !isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: family.name }), _jsx("span", { className: "forgebook-tree__count", children: componentCount(family) })] }), _jsx(TreeFold, { isOpen: isOpen, isInstant: isSearching, content: () => family.groups.map((group) => {
-                                                const key = groupKey(familyKey(source, family), group);
-                                                // shut by default; a search opens every group it finds something in
-                                                const isGroupOpen = isSearching || (foldChoices.get(key) ?? holdsCurrent(source.id, group, current));
-                                                return (_jsx(FamilyGroup, { sourceId: source.id, group: group, isOpen: isGroupOpen, isInstant: isSearching, onToggle: () => setFoldOpen(key, !isGroupOpen), current: current, links: links }, group.name ?? ""));
-                                            }) })] }, key));
-                            })] }, source.id)))] }), _jsx(AppearanceMenu, { ...appearance })] }));
+    return (_jsxs("aside", { ref: sidebarRef, className: "forgebook-sidebar", "data-open": isOpen ? "" : undefined, "data-overlay": isOverlay ? "" : undefined, inert: !isOpen, style: { width, marginInlineStart: isOpen ? 0 : -width }, children: [_jsxs("div", { className: "forgebook-brand", children: [_jsx(SidebarBrand, { title: title, mark: logo ?? (hasBranding ? FORGEBOOK_MARK_URL : undefined), isHome: isHome, homeHref: homeHref, onOpenHome: onOpenHome }), _jsx("button", { ref: hideButtonRef, type: "button", className: "forgebook-icon-button forgebook-brand__hide", title: STRINGS.hideSidebar, "aria-label": STRINGS.hideSidebar, onClick: onHide, children: _jsx(Icon, { name: "sidebar", size: 14 }) })] }), _jsxs("div", { className: "forgebook-search-row", children: [_jsx(SidebarSearch, { query: query, onQueryChange: setQuery, onFilterReady: showFiltered, tree: tree, sources: storySources, sidebarWidth: width, isSidebarOpen: isOpen, onShowSidebar: onShow, searchHref: searchHref, onOpenResult: onOpenResult }), _jsx(TagFilterSlot, { tree: wholeTree, tags: tags, onTagsChange: onTagsChange })] }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches || !isNarrowed ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), _jsx(LoadedDocs, { sources: pages, currentPageId: currentPageId, isSearching: isNarrowed, foldChoices: foldChoices, onFoldChange: setFoldOpen, pageHref: pageHref, onOpenPage: onOpenPage }), sources.map(({ source, families }) => (_jsx(SourceEntry, { source: source, families: families, isNarrowed: isNarrowed, foldChoices: foldChoices, onFoldChange: setFoldOpen, current: current, links: links }, source.id))), HAS_REFS && !isNarrowed ? links.composed : null] }), _jsx(AppearanceMenu, { ...appearance, onShowKeys: onShowKeys }), isOpen && !isOverlay ? _jsx(SidebarHandle, { width: width, onWidthChange: onWidthChange }) : null] }));
 };

package/dist/src/shell/SidebarDocs.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { pageGroups } from "../pageTree.js";
 import { Icon } from "./icons.js";
+import { LATER_STRINGS } from "./laterStrings.js";
 import { PageLink, TreeFold } from "./SidebarEntries.js";
-import { STRINGS } from "./strings.js";
 /**
  * A page's link.
  *
@@ -27,4 +27,4 @@ const PageGroupEntries = ({ sourceId, group, currentPageId, isSearching, foldCho
  *
  * @param props - the sources with their pages, the shown page, the folds and the links.
  */
-export const SidebarDocs = ({ sources, ...shared }) => sources.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsx("h2", { className: "forgebook-tree__source-name", children: STRINGS.docsNav }), sources.map(({ source, pages }) => (_jsxs("div", { children: [sources.length > 1 ? _jsx("h3", { className: "forgebook-tree__docs-source", children: source.name }) : null, pageGroups(pages).map((group) => (_jsx(PageGroupEntries, { sourceId: source.id, group: group, ...shared }, group.name ?? group.pages[0]?.id)))] }, source.id)))] }));
+export const SidebarDocs = ({ sources, ...shared }) => sources.length === 0 ? null : (_jsxs("section", { className: "forgebook-tree__source", children: [_jsx("h2", { className: "forgebook-tree__source-name", children: LATER_STRINGS.docsNav }), sources.map(({ source, pages }) => (_jsxs("div", { children: [sources.length > 1 ? _jsx("h3", { className: "forgebook-tree__docs-source", children: source.name }) : null, pageGroups(pages).map((group) => (_jsx(PageGroupEntries, { sourceId: source.id, group: group, ...shared }, group.name ?? group.pages[0]?.id)))] }, source.id)))] }));

package/dist/src/shell/SidebarEntries.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isFilterTag } from "../storyTagNames.js";
 import { isLogicComponent } from "../storyTree.js";
 import { Icon } from "./icons.js";
 import { STRINGS } from "./strings.js";
+import { TagViewSlot } from "./tagView.js";
 import { useFold } from "./useFold.js";
 /** A link that opens a page in place, keeping a real address for a new tab. */
 export const PageLink = ({ href, className, current, onOpen, children }) => (_jsx("a", { className: className, href: href, "aria-current": current, onClick: (event) => {
@@ -29,12 +31,12 @@ export const FamilyGroup = ({ sourceId, group, isOpen, isInstant, onToggle, curr
     const entries = () => groupEntries(group).map((entry) => entry.kind === "component" ? (_jsx(ComponentEntry, { sourceId: sourceId, component: entry.component, isCurrent: current?.sourceId === sourceId && current.title === entry.component.title, currentStoryId: current?.storyId, links: links }, entry.component.title)) : (_jsx(AliasEntry, { sourceId: sourceId, alias: entry.alias, links: links }, `alias:${entry.alias.title}`)));
     if (group.name === undefined)
         return _jsx("div", { className: "forgebook-tree__group", children: entries() });
-    return (_jsxs("div", { className: "forgebook-tree__group", children: [_jsx("h3", { className: "forgebook-tree__group-name", children: _jsxs("button", { type: "button", className: "forgebook-tree__group-button", "aria-expanded": isOpen, onClick: onToggle, children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: group.name }), _jsx("span", { className: "forgebook-tree__count", children: group.components.length })] }) }), _jsx(TreeFold, { isOpen: isOpen, isInstant: isInstant, content: entries })] }));
+    return (_jsxs("div", { className: "forgebook-tree__group", children: [_jsx("h3", { className: "forgebook-tree__group-name", children: _jsxs("button", { type: "button", className: "forgebook-tree__group-button", "aria-expanded": isOpen, onClick: onToggle, children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: group.name }), _jsx("span", { className: "forgebook-tree__count", children: group.components.length || null })] }) }), _jsx(TreeFold, { isOpen: isOpen, isInstant: isInstant, content: entries })] }));
 };
-/** A component's link: its page, where its stories are picked from the header. */
+/** A component's link: its page, where its stories are picked from the header, with its status's badges. */
 const ComponentEntry = ({ sourceId, component, isCurrent, currentStoryId, links }) => {
     const current = isCurrent ? currentKind(currentStoryId) : undefined;
-    return (_jsx("div", { className: "forgebook-tree__component", children: _jsxs(PageLink, { href: links.componentHref(sourceId, component.title), className: "forgebook-tree__item", current: current, onOpen: () => links.onOpenComponent(sourceId, component.title), children: [_jsx("span", { className: "forgebook-tree__item-name", children: component.name }), isLogicComponent(component) ? (_jsxs("span", { className: "forgebook-tree__logic", title: STRINGS.logicHint, children: [_jsx(Icon, { name: "function", size: 12 }), _jsx("span", { className: "forgebook-visually-hidden", children: STRINGS.logic })] })) : null, _jsx("span", { className: "forgebook-tree__count", children: component.stories.length })] }) }));
+    return (_jsx("div", { className: "forgebook-tree__component", children: _jsxs(PageLink, { href: links.componentHref(sourceId, component.title), className: "forgebook-tree__item", current: current, onOpen: () => links.onOpenComponent(sourceId, component.title), children: [_jsx("span", { className: "forgebook-tree__item-name", children: component.name }), isLogicComponent(component) ? (_jsxs("span", { className: "forgebook-tree__logic", title: STRINGS.logicHint, children: [_jsx(Icon, { name: "function", size: 12 }), _jsx("span", { className: "forgebook-visually-hidden", children: STRINGS.logic })] })) : null, component.tags.some(isFilterTag) ? _jsx(TagViewSlot, { place: "entry", component: component }) : null, _jsx("span", { className: "forgebook-tree__count", children: component.stories.length })] }) }));
 };
 /** The family a title places a component in: its first segment. */
 const familyOf = (title) => title.split("/")[0]?.trim() ?? title;

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

@@ -28,14 +28,12 @@ export declare const SidebarHandle: ({ width, onWidthChange }: {
     readonly onWidthChange: (width: number) => void;
 }) => ReactNode;
 /**
- * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ * The shade on the page under a sidebar lying over it; none while the sidebar lies beside the page.
  *
- * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ * @param props - where the sidebar lies, whether it is shown and how to hide it.
  */
-export declare const SidebarEdge: ({ isOverlay, isOpen, width, onWidthChange, onHide }: {
+export declare const SidebarShade: ({ isOverlay, isOpen, onHide }: {
     readonly isOverlay: boolean;
     readonly isOpen: boolean;
-    readonly width: number;
-    readonly onWidthChange: (width: number) => void;
     readonly onHide: () => void;
 }) => ReactNode;

package/dist/src/shell/SidebarHandle.js

@@ -44,12 +44,12 @@ export const SidebarHandle = ({ width, onWidthChange }) => {
     return (_jsx("div", { className: "forgebook-sidebar-handle", role: "separator", "aria-orientation": "vertical", "aria-label": STRINGS.sidebarWidth, "aria-valuenow": width, "aria-valuemin": SIDEBAR_WIDTH.min, "aria-valuemax": SIDEBAR_WIDTH.max, tabIndex: 0, onPointerDown: startResize, onKeyDown: resizeWithKeys }));
 };
 /**
- * What borders the sidebar: beside the page its handle, while shown; over it the shade on the page.
+ * The shade on the page under a sidebar lying over it; none while the sidebar lies beside the page.
  *
- * @param props - where the sidebar lies, whether it is shown, its width and how to hide it.
+ * @param props - where the sidebar lies, whether it is shown and how to hide it.
  */
-export const SidebarEdge = ({ isOverlay, isOpen, width, onWidthChange, onHide }) => {
+export const SidebarShade = ({ isOverlay, isOpen, onHide }) => {
     if (!isOverlay)
-        return isOpen ? _jsx(SidebarHandle, { width: width, onWidthChange: onWidthChange }) : null;
+        return null;
     return (_jsx("div", { className: "forgebook-sidebar-shade", "data-open": isOpen ? "" : undefined, "aria-hidden": "true", onClick: onHide }));
 };

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

@@ -0,0 +1,39 @@
+/**
+ * The sidebar's sections of the composed catalogues (`refs`), after this catalogue's stories: one per catalogue, shut
+ * until opened, its components and their stories read from its index when it first opens.
+ *
+ * @remarks
+ * A composed catalogue's components have no page here (their docs and controls are its own page's), so a component
+ * folds open on its stories, each a link to the story shown read-only. The sections keep their own folds, as the tree
+ * does: what holds the shown story opens and stays open until the reader shuts it, so opening another page never folds
+ * the list under the pointer. The search and the tag filter stay this catalogue's: another's index is fetched only on
+ * demand, and searching it would fetch every one at the first key.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { CatalogueRef } from "../catalogueRefs.ts";
+/** A story of a composed catalogue: the catalogue's id and the story's id in it. */
+export type RefStoryPlace = {
+    /** The composed catalogue's id. */
+    readonly refId: string;
+    /** The story's id in it. */
+    readonly storyId: string;
+};
+/** The sections' props. */
+export type SidebarRefsProps = {
+    /** The composed catalogues, in the configuration's order. */
+    readonly refs: readonly CatalogueRef[];
+    /** The shown story of a composed catalogue; none on any other page. */
+    readonly current: RefStoryPlace | undefined;
+    /** The address of a composed catalogue's story here, for its link. */
+    readonly refStoryHref: (place: RefStoryPlace) => string;
+    /** Shows a composed catalogue's story. */
+    readonly onOpenRefStory: (place: RefStoryPlace) => void;
+};
+/**
+ * The composed catalogues' sections. The section of the shown story opens, and stays open until the reader shuts it.
+ *
+ * @param props - the catalogues, the shown story and the links.
+ */
+export declare const SidebarRefs: ({ refs, ...links }: SidebarRefsProps) => ReactNode;

package/dist/src/shell/SidebarRefs.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The sidebar's sections of the composed catalogues (`refs`), after this catalogue's stories: one per catalogue, shut
+ * until opened, its components and their stories read from its index when it first opens.
+ *
+ * @remarks
+ * A composed catalogue's components have no page here (their docs and controls are its own page's), so a component
+ * folds open on its stories, each a link to the story shown read-only. The sections keep their own folds, as the tree
+ * does: what holds the shown story opens and stays open until the reader shuts it, so opening another page never folds
+ * the list under the pointer. The search and the tag filter stay this catalogue's: another's index is fetched only on
+ * demand, and searching it would fetch every one at the first key.
+ *
+ * @module
+ */
+import { useEffect, useRef, useState } from "react";
+import { Icon } from "./icons.js";
+import { REF_STRINGS } from "./refStrings.js";
+import { PageLink, TreeFold } from "./SidebarEntries.js";
+import { useRefIndex } from "./useRefIndex.js";
+/** A component's key among the folds; a section's is its catalogue's id. */
+const componentKey = (refId, componentId) => `${refId}/${componentId}`;
+/**
+ * A story's link, scrolled into sight when it is the shown one: a story opened by its address is in the list only once
+ * the index arrived, later than the sidebar's own scroll to the shown page.
+ *
+ * @param props - the link's address, whether it is shown, what opening it does and its name.
+ */
+const RefStoryEntry = ({ href, isCurrent, onOpen, name }) => {
+    const entryRef = useRef(null);
+    useEffect(() => {
+        if (isCurrent)
+            entryRef.current?.scrollIntoView({ block: "nearest" });
+    }, [isCurrent]);
+    return (_jsx("div", { ref: entryRef, className: "forgebook-tree__component", children: _jsx(PageLink, { href: href, className: "forgebook-tree__item", current: isCurrent ? "page" : undefined, onOpen: onOpen, children: _jsx("span", { className: "forgebook-tree__item-name", children: name }) }) }));
+};
+/**
+ * A component of a composed catalogue: a button that folds it, and its stories' links.
+ *
+ * @param props - the component, its catalogue, the shown story, the folds and the links.
+ */
+const RefComponentEntry = ({ composed, component, current, folds, onFold, refStoryHref, onOpenRefStory }) => {
+    const key = componentKey(composed.id, component.id);
+    const isOpen = folds.get(key) ?? false;
+    return (_jsxs("div", { className: "forgebook-tree__group", children: [_jsx("h3", { className: "forgebook-tree__group-name", children: _jsxs("button", { type: "button", className: "forgebook-tree__group-button", "aria-expanded": isOpen, onClick: () => onFold(key, !isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: component.title.split("/").join(" › ") }), _jsx("span", { className: "forgebook-tree__count", children: component.stories.length })] }) }), _jsx(TreeFold, { isOpen: isOpen, isInstant: false, content: () => component.stories.map((story) => {
+                    const place = { refId: composed.id, storyId: story.id };
+                    return (_jsx(RefStoryEntry, { href: refStoryHref(place), isCurrent: current?.refId === composed.id && current.storyId === story.id, onOpen: () => onOpenRefStory(place), name: story.name }, story.id));
+                }) })] }));
+};
+/**
+ * What an open section lists: its components once its index is read, or what it is waiting for, or why it failed. The
+ * component that holds the shown story opens once the index says which it is.
+ *
+ * @param props - the section's catalogue and what its entries read.
+ */
+const RefEntries = ({ composed, ...entries }) => {
+    const state = useRefIndex(composed, true);
+    const { current, folds, onFold } = entries;
+    const holding = state.status === "ready" && current?.refId === composed.id
+        ? state.index.components.find((component) => component.stories.some((story) => story.id === current.storyId))
+        : undefined;
+    const holdingKey = holding === undefined ? undefined : componentKey(composed.id, holding.id);
+    useEffect(() => {
+        if (holdingKey !== undefined && !folds.has(holdingKey))
+            onFold(holdingKey, true);
+    }, [holdingKey, folds, onFold]);
+    if (state.status === "error")
+        return _jsx("p", { className: "forgebook-tree__empty", children: REF_STRINGS.unreadable(composed.title, state.message) });
+    if (state.status !== "ready")
+        return _jsx("p", { className: "forgebook-tree__empty", children: REF_STRINGS.loading });
+    if (state.index.components.length === 0)
+        return _jsx("p", { className: "forgebook-tree__empty", children: REF_STRINGS.empty });
+    return state.index.components.map((component) => (_jsx(RefComponentEntry, { composed: composed, component: component, ...entries }, component.id)));
+};
+/**
+ * A composed catalogue's section: its name, which folds it, and its entries, read when it first opens.
+ *
+ * @param props - the catalogue and what its entries read.
+ */
+const RefSection = ({ composed, ...entries }) => {
+    const isOpen = entries.folds.get(composed.id) ?? false;
+    return (_jsx("section", { className: "forgebook-tree__source", "aria-label": REF_STRINGS.section(composed.title), children: _jsxs("div", { className: "forgebook-tree__family", children: [_jsxs("button", { type: "button", className: "forgebook-tree__family-button", "aria-expanded": isOpen, onClick: () => entries.onFold(composed.id, !isOpen), children: [_jsx("span", { className: "forgebook-tree__chevron", "data-open": isOpen ? "" : undefined, children: _jsx(Icon, { name: "chevronRight", size: 12 }) }), _jsx("span", { className: "forgebook-tree__family-name", children: composed.title }), _jsx(Icon, { name: "external", size: 10 })] }), _jsx(TreeFold, { isOpen: isOpen, isInstant: false, content: () => _jsx(RefEntries, { composed: composed, ...entries }) })] }) }));
+};
+/**
+ * The composed catalogues' sections. The section of the shown story opens, and stays open until the reader shuts it.
+ *
+ * @param props - the catalogues, the shown story and the links.
+ */
+export const SidebarRefs = ({ refs, ...links }) => {
+    const [folds, setFolds] = useState(new Map());
+    // one function for the sections' whole life, so the effect that opens the shown story's component runs only for it
+    const [onFold] = useState(() => (key, isOpen) => setFolds((choices) => new Map(choices).set(key, isOpen)));
+    const currentRef = links.current?.refId;
+    useEffect(() => {
+        if (currentRef === undefined)
+            return;
+        setFolds((choices) => (choices.has(currentRef) ? choices : new Map(choices).set(currentRef, true)));
+    }, [currentRef]);
+    return refs.map((composed) => (_jsx(RefSection, { composed: composed, folds: folds, onFold: onFold, ...links }, composed.id)));
+};

package/dist/src/shell/SidebarSearch.js

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

package/dist/src/shell/SignatureReference.js

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

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

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