forgebook 0.1.7 → 0.2.0

package/dist/src/shell/Sidebar.js

@@ -1,22 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * The sidebar: a search field and the tree, by source, family and named group (each folds open and shut, animated; a
- * group starts shut unless it holds the shown component) and component, one line per component that never opens: a
- * component's link opens its page, and its stories are picked in the page's header, so nothing in the list folds under
- * the pointer. A family or a group stays open once opened; a search opens every one it finds something in, and finds a
- * 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.
- *
- * @module
- */
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { AppearanceMenu } from "./AppearanceMenu.js";
+import { FORGEBOOK_MARK_URL } from "./forgebookMark.js";
 import { Icon } from "./icons.js";
-import { isTyping } from "./keyboard.js";
+import { SidebarDocs } from "./SidebarDocs.js";
 import { FamilyGroup, TreeFold } from "./SidebarEntries.js";
+import { SidebarSearch } from "./SidebarSearch.js";
 import { STRINGS } from "./strings.js";
-import { foundFamily, searchWords } from "./treeSearch.js";
 /** 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. */
@@ -46,6 +36,13 @@ const currentGroupOf = (tree, current) => {
         .find((candidate) => candidate.name !== undefined && holdsCurrent(source.id, candidate, current));
     return family === undefined || group === undefined ? undefined : groupKey(family, group);
 };
+/** The tree as it is, with no search on. */
+const wholeTree = (tree) => ({
+    sources: tree.sources.map((source) => ({ source, families: source.families })),
+    pages: tree.sources
+        .filter(({ pages }) => pages.length > 0)
+        .map((source) => ({ source, pages: source.pages }))
+});
 /** How many components a family holds. */
 const componentCount = (family) => family.groups.reduce((count, group) => count + group.components.length, 0);
 /**
@@ -53,33 +50,21 @@ const componentCount = (family) => family.groups.reduce((count, group) => count
  *
  * @param props - the tree, the shown component and how to open one.
  */
-export const Sidebar = ({ title, logo, tree, isHome, homeHref, onOpenHome, current, width, isOpen, onHide, appearance, ...links }) => {
+export const Sidebar = ({ title, logo, hasBranding, tree, sources: storySources, searchHref, onOpenResult, isHome, homeHref, onOpenHome, current, currentPageId, pageHref, onOpenPage, width, isOpen, onHide, onShow, appearance, ...links }) => {
     const [query, setQuery] = useState("");
-    const searchRef = useRef(null);
+    const [filterTree, setFilterTree] = useState();
+    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 currentTitle = current?.title;
+    const currentEntry = currentPageId ?? current?.title;
     useEffect(() => {
-        if (currentTitle === undefined)
+        if (currentEntry === undefined)
             return;
         navRef.current
             ?.querySelector(".forgebook-tree__item[aria-current]")
             ?.scrollIntoView({ block: "nearest" });
-    }, [currentTitle]);
-    useEffect(() => {
-        // "/" goes to the search from anywhere in the shell, as in most catalogues
-        // a hidden sidebar leaves the key to the page
-        if (!isOpen)
-            return;
-        const focusSearch = (event) => {
-            if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey || isTyping(event.target))
-                return;
-            event.preventDefault();
-            searchRef.current?.focus();
-        };
-        document.addEventListener("keydown", focusSearch);
-        return () => document.removeEventListener("keydown", focusSearch);
-    }, [isOpen]);
+    }, [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());
@@ -94,36 +79,19 @@ export const Sidebar = ({ title, logo, tree, isHome, homeHref, onOpenHome, curre
                 ...opened.filter((key) => !choices.has(key)).map((key) => [key, true])
             ]));
     }, [currentFamilyKey, currentGroupKey]);
-    const words = searchWords(query);
-    const isSearching = words.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 sources = tree.sources.map((source) => ({
-        source,
-        families: source.families.flatMap((family) => {
-            const shown = foundFamily(family, words);
-            return shown === undefined ? [] : [shown];
-        })
-    }));
-    const hasMatches = sources.some(({ families }) => families.length > 0);
+    // 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 hasMatches = pages.length > 0 || sources.some(({ families }) => families.length > 0);
     return (_jsxs("aside", { className: "forgebook-sidebar", "data-open": isOpen ? "" : 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: [logo === undefined ? (_jsx("span", { className: "forgebook-brand__mark", children: _jsx(Icon, { name: "compare", size: 14 }) })) : (_jsx("img", { className: "forgebook-brand__logo", src: logo, alt: "", width: 28, height: 28 })), _jsx("span", { className: "forgebook-brand__name", children: title })] }), _jsx("button", { 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("label", { className: "forgebook-search", children: [_jsx(Icon, { name: "search", size: 14 }), _jsx("input", { type: "search", ref: searchRef, value: query, onKeyDown: (event) => {
-                            // Escape empties the search first, then leaves the field
-                            if (event.key !== "Escape")
-                                return;
-                            if (query === "")
-                                event.currentTarget.blur();
-                            else
-                                setQuery("");
-                        }, placeholder: STRINGS.searchPlaceholder, "aria-label": STRINGS.searchLabel, onChange: (event) => setQuery(event.target.value) }), query === "" ? (_jsx("kbd", { className: "forgebook-search__key", children: "/" })) : (_jsx("button", { type: "button", className: "forgebook-search__clear", "aria-label": STRINGS.clearSearch, title: STRINGS.clearSearch, onClick: () => {
-                            setQuery("");
-                            searchRef.current?.focus();
-                        }, children: _jsx(Icon, { name: "close", size: 10 }) }))] }), _jsxs("nav", { ref: navRef, className: "forgebook-tree", "aria-label": STRINGS.componentsNav, children: [hasMatches ? null : _jsx("p", { className: "forgebook-tree__empty", children: STRINGS.noMatch }), 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) => {
+                        }, 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", { 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));
@@ -135,4 +103,3 @@ export const Sidebar = ({ title, logo, tree, isHome, homeHref, onOpenHome, curre
                                             }) })] }, key));
                             })] }, source.id)))] }), _jsx(AppearanceMenu, { ...appearance })] }));
 };
-//# sourceMappingURL=Sidebar.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * The sidebar's Docs section, above the components: each source's pages in their reading order, by group, a group
+ * open until the reader folds it, since a catalogue's docs are few and read in order.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import { type TreePage } from "../pageTree.ts";
+import type { TreeSource } from "../storyTree.ts";
+/** How the section links its pages. */
+export type SidebarPageLinks = {
+    /** The address of a docs page, by its id, for its link. */
+    readonly pageHref: (id: string) => string;
+    /** Opens a docs page, by its id. */
+    readonly onOpenPage: (id: string) => void;
+};
+/** The section's props. */
+export type SidebarDocsProps = SidebarPageLinks & {
+    /** The sources with the pages shown, those with none left out. */
+    readonly sources: readonly {
+        readonly source: TreeSource;
+        readonly pages: readonly TreePage[];
+    }[];
+    /** The shown page's id; none on any other page. */
+    readonly currentPageId: string | undefined;
+    /** Whether a search is on: every group it finds something in opens at once. */
+    readonly isSearching: boolean;
+    /** Whether the reader folded a group open or shut, by its key. */
+    readonly foldChoices: ReadonlyMap<string, boolean>;
+    /** Called when the reader folds a group. */
+    readonly onFoldChange: (key: string, isOpen: boolean) => void;
+};
+/**
+ * The section; nothing when no page is shown.
+ *
+ * @param props - the sources with their pages, the shown page, the folds and the links.
+ */
+export declare const SidebarDocs: ({ sources, ...shared }: SidebarDocsProps) => ReactNode;

package/dist/src/shell/SidebarDocs.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { pageGroups } from "../pageTree.js";
+import { Icon } from "./icons.js";
+import { PageLink, TreeFold } from "./SidebarEntries.js";
+import { STRINGS } from "./strings.js";
+/**
+ * A page's link.
+ *
+ * @param props - the page, whether it is shown, and its link.
+ */
+const PageEntry = ({ page, isCurrent, pageHref, onOpenPage }) => (_jsx("div", { className: "forgebook-tree__component", children: _jsx(PageLink, { href: pageHref(page.id), className: "forgebook-tree__item", current: isCurrent ? "page" : undefined, onOpen: () => onOpenPage(page.id), children: _jsx("span", { className: "forgebook-tree__item-name", children: page.name }) }) }));
+/**
+ * A group of pages, under a button that folds it when it has a name.
+ *
+ * @param props - the group, its source and what the section shares.
+ */
+const PageGroupEntries = ({ sourceId, group, currentPageId, isSearching, foldChoices, onFoldChange, ...links }) => {
+    const entries = () => group.pages.map((page) => (_jsx(PageEntry, { page: page, isCurrent: page.id === currentPageId, ...links }, page.id)));
+    if (group.name === undefined)
+        return _jsx("div", { className: "forgebook-tree__group", children: entries() });
+    const key = `docs/${sourceId}/${group.name}`;
+    const isOpen = isSearching || (foldChoices.get(key) ?? true);
+    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: () => 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: group.name }), _jsx("span", { className: "forgebook-tree__count", children: group.pages.length })] }) }), _jsx(TreeFold, { isOpen: isOpen, isInstant: isSearching, content: entries })] }));
+};
+/**
+ * The section; nothing when no page is shown.
+ *
+ * @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)))] }));

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

@@ -5,7 +5,7 @@
  * @module
  */
 import type { ReactNode } from "react";
-import type { TreeGroup } from "../storyTree.ts";
+import { type TreeGroup } from "../storyTree.ts";
 /** The shown component: its source and title, to mark it and keep its family open, and the shown story's id. */
 export type ShownComponent = {
     /** Its source's id. */
@@ -22,6 +22,15 @@ export type SidebarLinks = {
     /** Opens a component's page, by its title. */
     readonly onOpenComponent: (sourceId: string, title: string) => void;
 };
+/** A link that opens a page in place, keeping a real address for a new tab. */
+export declare const PageLink: ({ href, className, current, onOpen, children }: {
+    readonly href: string;
+    readonly className: string;
+    /** What the link is when current: the shown page, or the place the shown page is in; none when not current. */
+    readonly current: "page" | "location" | undefined;
+    readonly onOpen: () => void;
+    readonly children: ReactNode;
+}) => ReactNode;
 /**
  * What a family's or a group's button folds open and shut animated: drawn only while open or shutting.
  *
@@ -47,4 +56,3 @@ export declare const FamilyGroup: ({ sourceId, group, isOpen, isInstant, onToggl
     readonly current: ShownComponent | undefined;
     readonly links: SidebarLinks;
 }) => ReactNode;
-//# sourceMappingURL=SidebarEntries.d.ts.map

package/dist/src/shell/SidebarEntries.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isLogicComponent } from "../storyTree.js";
 import { Icon } from "./icons.js";
 import { STRINGS } from "./strings.js";
 import { useFold } from "./useFold.js";
 /** A link that opens a page in place, keeping a real address for a new tab. */
-const PageLink = ({ href, className, current, onOpen, children }) => (_jsx("a", { className: className, href: href, "aria-current": current, onClick: (event) => {
+export const PageLink = ({ href, className, current, onOpen, children }) => (_jsx("a", { className: className, href: href, "aria-current": current, onClick: (event) => {
         event.preventDefault();
         onOpen();
     }, children: children }));
@@ -33,7 +34,7 @@ export const FamilyGroup = ({ sourceId, group, isOpen, isInstant, onToggle, curr
 /** A component's link: its page, where its stories are picked from the header. */
 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 }), _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, _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;
@@ -48,4 +49,3 @@ const groupEntries = (group) => [
     ...group.components.map((component) => ({ kind: "component", component, name: component.name })),
     ...group.aliases.map((alias) => ({ kind: "alias", alias, name: alias.name }))
 ].sort((left, right) => left.name.localeCompare(right.name));
-//# sourceMappingURL=SidebarEntries.js.map

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

@@ -26,4 +26,3 @@ export declare const SidebarHandle: ({ width, onWidthChange }: {
     readonly width: number;
     readonly onWidthChange: (width: number) => void;
 }) => ReactNode;
-//# sourceMappingURL=SidebarHandle.d.ts.map

package/dist/src/shell/SidebarHandle.js

@@ -43,4 +43,3 @@ 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 }));
 };
-//# sourceMappingURL=SidebarHandle.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * The sidebar's search field: `/` or the platform's search key comes here from anywhere in the shell, and what is typed
+ * filters the tree at once and opens the results beside it (`SearchPanel.tsx`), loaded the first time the field is used.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ReactNode } from "react";
+import type { SearchTarget } from "../search.ts";
+import type { StoryTree } from "../storyTree.ts";
+import type { shownTree } from "./treeSearch.ts";
+/** The field's props. */
+export type SidebarSearchProps = {
+    /** What is typed: the tree filters by it. */
+    readonly query: string;
+    /** Called when it changes. */
+    readonly onQueryChange: (query: string) => void;
+    /** Called with the tree's filter, which comes with the list. */
+    readonly onFilterReady: (filter: typeof shownTree) => void;
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The sources, with the loaders of their index. */
+    readonly sources: readonly StorySource[];
+    /** The sidebar's width, in CSS px. */
+    readonly sidebarWidth: number;
+    /** Whether the sidebar is shown: hidden, it leaves `/` to the page. */
+    readonly isSidebarOpen: boolean;
+    /** Shows a hidden sidebar: the platform's search key must reach the field wherever it is. */
+    readonly onShowSidebar: () => void;
+    /** The address of a result. */
+    readonly searchHref: (target: SearchTarget) => string;
+    /** Goes to a result. */
+    readonly onOpenResult: (target: SearchTarget) => void;
+};
+/**
+ * The search field.
+ *
+ * @param props - what is typed, what can be found and how to go to it.
+ */
+export declare const SidebarSearch: ({ query, onQueryChange, onFilterReady, tree, sources, sidebarWidth, isSidebarOpen, onShowSidebar, searchHref, onOpenResult }: SidebarSearchProps) => ReactNode;

package/dist/src/shell/SidebarSearch.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { lazy, Suspense, useEffect, useId, useRef, useState } from "react";
+import { Icon } from "./icons.js";
+import { isTyping } from "./keyboard.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 search field.
+ *
+ * @param props - what is typed, what can be found and how to go to it.
+ */
+export const SidebarSearch = ({ query, onQueryChange, onFilterReady, tree, sources, sidebarWidth, isSidebarOpen, onShowSidebar, searchHref, onOpenResult }) => {
+    const inputRef = useRef(null);
+    const keysRef = useRef(null);
+    const [isUsed, setIsUsed] = useState(false);
+    const [isListOpen, setIsListOpen] = useState(false);
+    const [activeId, setActiveId] = useState(undefined);
+    const listId = useId();
+    // the sidebar is still out of the tab order when its search key shows it: the focus follows once it is back
+    const isFocusWaiting = useRef(false);
+    useEffect(() => {
+        if (!isSidebarOpen || !isFocusWaiting.current)
+            return;
+        isFocusWaiting.current = false;
+        inputRef.current?.focus();
+    }, [isSidebarOpen]);
+    useEffect(() => {
+        const focusSearch = (event) => {
+            const isSearchKey = event.key === "k" && (event.metaKey || event.ctrlKey) && !event.altKey;
+            if (isSearchKey) {
+                event.preventDefault();
+                if (isSidebarOpen)
+                    inputRef.current?.focus();
+                else {
+                    isFocusWaiting.current = true;
+                    onShowSidebar();
+                }
+                return;
+            }
+            // "/" goes to the search from anywhere in the shell, as in most catalogues
+            // a hidden sidebar leaves the key to the page
+            if (!isSidebarOpen)
+                return;
+            if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey || isTyping(event.target))
+                return;
+            event.preventDefault();
+            inputRef.current?.focus();
+        };
+        document.addEventListener("keydown", focusSearch);
+        return () => document.removeEventListener("keydown", focusSearch);
+    }, [isSidebarOpen, onShowSidebar]);
+    const openResult = (target) => {
+        setIsListOpen(false);
+        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: () => {
+                            setIsUsed(true);
+                            setIsListOpen(true);
+                        }, onBlur: () => setIsListOpen(false), onKeyDown: (event) => {
+                            // Enter confirms what an input method is composing, never a result
+                            if (event.nativeEvent.isComposing)
+                                return;
+                            if (keysRef.current?.press(event.key, event.metaKey || event.ctrlKey) === true) {
+                                event.preventDefault();
+                                return;
+                            }
+                            // Escape empties the search first, then leaves the field
+                            if (event.key !== "Escape")
+                                return;
+                            if (query === "")
+                                event.currentTarget.blur();
+                            else
+                                onQueryChange("");
+                        }, placeholder: STRINGS.searchPlaceholder, "aria-label": STRINGS.searchLabel, onChange: (event) => {
+                            onQueryChange(event.target.value);
+                            setIsListOpen(true);
+                        } }), 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] }));
+};

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

@@ -0,0 +1,25 @@
+/**
+ * A hook's or a function's signature, as a story about logic documents it: the call on one line, a table of its
+ * parameters (name, type, what it is), then what it returns. On the component page in place of the props table, and
+ * in the story's panel as its first tab.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { FunctionSignatureDocs } from "../componentDocs.ts";
+/**
+ * The call as one line of TypeScript: `useUndo<TValue>(initial: TValue, limit?: number): UndoState<TValue>`.
+ *
+ * @param name - the function's name.
+ * @param signature - its signature.
+ */
+export declare const callText: (name: string, signature: FunctionSignatureDocs) => string;
+/**
+ * The signature's reference.
+ *
+ * @param props - the function's name and signature.
+ */
+export declare const SignatureReference: ({ name, signature }: {
+    readonly name: string;
+    readonly signature: FunctionSignatureDocs;
+}) => ReactNode;

package/dist/src/shell/SignatureReference.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Code } from "./Code.js";
+import { CodeText } from "./CodeText.js";
+import { STRINGS } from "./strings.js";
+/**
+ * The type parameters as the call writes them: `<TValue>`, or nothing.
+ *
+ * @param typeParameters - the type parameters.
+ */
+const typeParametersText = (typeParameters) => typeParameters.length === 0 ? "" : `<${typeParameters.join(", ")}>`;
+/**
+ * The call as one line of TypeScript: `useUndo<TValue>(initial: TValue, limit?: number): UndoState<TValue>`.
+ *
+ * @param name - the function's name.
+ * @param signature - its signature.
+ */
+export const callText = (name, signature) => `${name}${typeParametersText(signature.typeParameters)}(${signature.parameters
+    .map((parameter) => `${parameter.isRest ? "..." : ""}${parameter.name}${parameter.isOptional ? "?" : ""}: ${parameter.type}`)
+    .join(", ")}): ${signature.returns}`;
+/**
+ * The signature's reference.
+ *
+ * @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 })] }))] })] }));

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

@@ -11,11 +11,12 @@
  * @module
  */
 import { type ReactNode } from "react";
-import type { PanelArgs } from "../messages.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 { ShellPlugin } from "./pluginTabs.tsx";
 import { type PageScroll } from "./useScrollMemory.ts";
 /** The stage's props. */
 export type StageProps = {
@@ -29,7 +30,10 @@ 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;
-    /** The values set in the Props tab, over the story's own args (kept in the address). */
+    /**
+     * 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;
     /** Called with the panel's changed values. */
     readonly onPanelArgsChange: (args: PanelArgs) => void;
@@ -39,6 +43,8 @@ export type StageProps = {
     readonly onMatrixAxesChange: (axes: readonly string[]) => void;
     /** The frame page's address. */
     readonly frameUrl: string;
+    /** The plugins with tabs. */
+    readonly plugins: readonly ShellPlugin[];
     /** Loads the story file's code for the Code tab; `undefined` when the source has none. */
     readonly loadCode: (() => Promise<unknown>) | undefined;
     /** Loads the component's docs for the panel; `undefined` when the source has none for the file. */
@@ -64,5 +70,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, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }: StageProps) => ReactNode;
-//# sourceMappingURL=Stage.d.ts.map
+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;