forgebook 0.3.3 → 0.4.1

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;

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)));
+};