forgebook 0.1.7 → 0.2.0

package/dist/src/shell/PluginTabHost.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A plugin's tab in the panel: what it is told. The dock draws a tab's content only while it is chosen, so a view's own
+ * state goes when another tab is chosen; a frame's report does not, since the stage keeps it.
+ *
+ * @module
+ */
+import { useCallback, useMemo, useRef } from "react";
+import { showAsideStory } from "./asideStory.js";
+import { PluginViewHost, pluginText, useShellAppearance } from "./PluginViewHost.js";
+/**
+ * A plugin's tab.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export const PluginTabHost = ({ load, pluginId, strings, story, report, aside }) => {
+    const appearance = useShellAppearance();
+    // read when the view asks: the stage of that moment, without a new context for every change of the stage
+    const asideRef = useRef(aside);
+    asideRef.current = aside;
+    const showStory = useCallback((target, { title }) => showAsideStory(target, title, asideRef.current), []);
+    const text = useMemo(() => pluginText(strings, pluginId), [strings, pluginId]);
+    const context = useMemo(() => ({ appearance, text, story, report, showStory }), [appearance, text, story, report, showStory]);
+    return _jsx(PluginViewHost, { load: load, context: context });
+};

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

@@ -0,0 +1,37 @@
+/**
+ * A plugin's view in its place: loads its module, hands it an element and its context, keeps it up to date, and takes
+ * it away.
+ *
+ * @remarks
+ * Loads with the first plugin view shown. A view is someone else's code: one that cannot load, or that throws, is said
+ * in its place and leaves the shell standing.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { PluginTabContext, PluginView, PluginViewContext } from "../plugin.ts";
+/**
+ * The shell's appearance, followed while a view is shown.
+ *
+ * @returns the appearance.
+ */
+export declare const useShellAppearance: () => PluginTabContext["appearance"];
+/**
+ * What a plugin's text says.
+ *
+ * @param strings - the texts the catalogue replaces, by name.
+ * @param pluginId - the plugin's id.
+ * @returns the context's `text`.
+ */
+export declare const pluginText: (strings: Readonly<Record<string, string>>, pluginId: string) => PluginViewContext["text"];
+/**
+ * A plugin's view.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export declare const PluginViewHost: <TContext extends PluginViewContext>({ load, context }: {
+    readonly load: () => Promise<{
+        readonly view: PluginView<TContext>;
+    }>;
+    readonly context: TContext;
+}) => ReactNode;

package/dist/src/shell/PluginViewHost.js

@@ -0,0 +1,89 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A plugin's view in its place: loads its module, hands it an element and its context, keeps it up to date, and takes
+ * it away.
+ *
+ * @remarks
+ * Loads with the first plugin view shown. A view is someone else's code: one that cannot load, or that throws, is said
+ * in its place and leaves the shell standing.
+ *
+ * @module
+ */
+import { useEffect, useRef, useState } from "react";
+import { LATER_STRINGS } from "./laterStrings.js";
+import { APPEARANCE_ATTRIBUTE } from "./useAppearance.js";
+/** The shell's appearance, as its root says it now. */
+const appearanceNow = () => document.documentElement.getAttribute(APPEARANCE_ATTRIBUTE) === "dark" ? "dark" : "light";
+/**
+ * The shell's appearance, followed while a view is shown.
+ *
+ * @returns the appearance.
+ */
+export const useShellAppearance = () => {
+    const [appearance, setAppearance] = useState(appearanceNow);
+    useEffect(() => {
+        const observer = new MutationObserver(() => setAppearance(appearanceNow()));
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: [APPEARANCE_ATTRIBUTE] });
+        return () => observer.disconnect();
+    }, []);
+    return appearance;
+};
+/**
+ * What a plugin's text says.
+ *
+ * @param strings - the texts the catalogue replaces, by name.
+ * @param pluginId - the plugin's id.
+ * @returns the context's `text`.
+ */
+export const pluginText = (strings, pluginId) => (key, fallback, values = {}) => (strings[`plugin.${pluginId}.${key}`] ?? fallback).replace(/\{(\w+)\}/g, (written, name) => values[name] ?? written);
+/** An error as a sentence. */
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * A plugin's view.
+ *
+ * @param props - how it loads, and what it is told.
+ */
+export const PluginViewHost = ({ load, context }) => {
+    const targetRef = useRef(null);
+    const viewRef = useRef(undefined);
+    const [problem, setProblem] = useState(undefined);
+    const contextRef = useRef(context);
+    contextRef.current = context;
+    useEffect(() => {
+        let isCurrent = true;
+        load()
+            .then((module) => {
+            const target = targetRef.current;
+            if (isCurrent && target !== null)
+                viewRef.current = module.view(target, contextRef.current);
+        })
+            .catch((error) => {
+            if (isCurrent)
+                setProblem(messageOf(error));
+        });
+        return () => {
+            isCurrent = false;
+            try {
+                viewRef.current?.unmount();
+            }
+            catch (error) {
+                // nobody is left to read it in place, and thrown here it would take the shell down
+                window.reportError(error);
+            }
+            viewRef.current = undefined;
+        };
+    }, [load]);
+    useEffect(() => {
+        try {
+            viewRef.current?.update(context);
+        }
+        catch (error) {
+            setProblem(messageOf(error));
+        }
+    }, [context]);
+    if (problem !== undefined) {
+        return (_jsxs("p", { className: "forgebook-problems", role: "alert", children: [LATER_STRINGS.pluginError, ": ", problem] }));
+    }
+    // no box of its own: a view's height reads its place's
+    return _jsx("div", { ref: targetRef, style: { display: "contents" } });
+};

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

@@ -28,4 +28,3 @@ export declare const NumberField: ({ prop, value, descriptionId, onValueChange }
     readonly descriptionId: string;
     readonly onValueChange: OnValueChange;
 }) => ReactNode;
-//# sourceMappingURL=PropFields.d.ts.map

package/dist/src/shell/PropFields.js

@@ -78,4 +78,3 @@ export const NumberField = ({ prop, value, descriptionId, onValueChange }) => {
     const change = (text) => onValueChange(prop.name, text === "" ? undefined : Number(text));
     return (_jsxs(_Fragment, { children: [prop.control === "range" ? (_jsx("input", { type: "range", "aria-label": label, "aria-describedby": descriptionId, ...bounds, value: typeof value === "number" ? value : (prop.min ?? 0), onChange: (event) => change(event.target.value) })) : null, _jsx("input", { type: "number", "aria-label": prop.control === "range" ? STRINGS.rangeValue(label) : label, "aria-describedby": descriptionId, ...bounds, value: textOf(value), onChange: (event) => change(event.target.value) })] }));
 };
-//# sourceMappingURL=PropFields.js.map

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

@@ -5,6 +5,11 @@
  * (`argTypes.ts`): a control they name (a list, buttons, checkboxes, a range, a colour, a date) wins over the one
  * the prop's type gives.
  *
+ * @remarks
+ * Props whose TSDoc names a group (`@group Selection`) are listed under its name after the others, as the API reference
+ * lists them (`propGroups.ts`): each group's controls, its toggles, then its props the panel cannot set. Each starts
+ * open, and a reader may fold it away. A component whose props name no group shows the tab as it always was.
+ *
  * @module
  */
 import type { StoryControlsSetting } from "@forgebook/story-format/source";
@@ -38,11 +43,15 @@ export type PropsTabProps = {
     readonly namedValues?: NamedValues | undefined;
     /** The props the story gives a text by its key, by name; none by default. */
     readonly textArgs?: Readonly<Record<string, TextArgNote>>;
+    /**
+     * The prop groups the component's meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's;
+     * none by default.
+     */
+    readonly componentGroups?: readonly string[];
 };
 /**
  * The Props tab.
  *
  * @param props - the props, the values, which props the story lets the panel set, and the setters.
  */
-export declare const PropsTab: ({ props, values, controls, onValueChange, onReset, worstCase, namedValues, textArgs }: PropsTabProps) => ReactNode;
-//# sourceMappingURL=PropsTab.d.ts.map
+export declare const PropsTab: ({ props, values, controls, onValueChange, onReset, worstCase, namedValues, textArgs, componentGroups }: PropsTabProps) => ReactNode;

package/dist/src/shell/PropsTab.js

@@ -2,12 +2,17 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useId } from "react";
 import { isColorProp, isNamedProp, settableProps } from "../argTypes.js";
 import { isNamedArg } from "../messages.js";
+import { groupedProps, propGroupOrder } from "../propGroups.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { Icon } from "./icons.js";
 import { ChoiceControl, NumberField, textOf } from "./PropFields.js";
 import { STRINGS } from "./strings.js";
 /** A CSS colour as the colour picker takes it (`#rrggbb`), or black when the value is not one. */
 const pickerColor = (value) => typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
 /** No prop named by a text key. */
 const NO_TEXT_ARGS = {};
+/** No group named first. */
+const NO_GROUPS = [];
 /** A prop's name, whether it is required, and its type (whole in the tooltip when it is cut). */
 const PropHead = ({ prop }) => (_jsxs("div", { className: "forgebook-prop__head", children: [_jsxs("code", { className: "forgebook-prop__name", children: [prop.label ?? prop.name, prop.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsx("code", { className: "forgebook-prop__type", title: prop.type, children: prop.type })] }));
 /** A prop's description and default, under its control. */
@@ -46,6 +51,20 @@ const Toggle = ({ prop, value, onValueChange }) => {
     const descriptionId = useId();
     return (_jsxs("label", { className: "forgebook-toggle", title: prop.description, children: [_jsx("input", { type: "checkbox", checked: value === true, "aria-describedby": descriptionId, onChange: (event) => onValueChange(prop.name, event.target.checked) }), _jsx("code", { children: prop.label ?? prop.name }), _jsx("span", { id: descriptionId, className: "forgebook-visually-hidden", children: prop.description })] }));
 };
+/** A prop the panel cannot set: its name, its type and its description, for reading. */
+const ReadOnlyProp = ({ prop }) => (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsx("p", { className: "forgebook-prop__description", children: prop.description })] }));
+/**
+ * A group the props' TSDoc names, under its name: its controls in the order of the props, its toggles, then the props
+ * the panel cannot set.
+ *
+ * @param props - the group's name and props, and how each prop is drawn.
+ */
+const NamedGroup = ({ name, props, isSettable, control, toggle }) => {
+    const controls = props.filter((prop) => isSettable(prop) && prop.kind !== "toggle");
+    const toggles = props.filter((prop) => isSettable(prop) && prop.kind === "toggle");
+    const others = props.filter((prop) => !isSettable(prop));
+    return (_jsx("div", { className: "forgebook-prop-group", children: _jsxs("details", { className: "forgebook-fold", open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary forgebook-prop-group__title", children: [_jsx(Icon, { name: "chevronRight", size: 12 }), _jsx("h3", { className: "forgebook-fold__name", children: name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(props.length) })] }), _jsxs("div", { className: "forgebook-prop-group__body", children: [controls.length === 0 ? null : _jsx("div", { className: "forgebook-prop-grid", children: controls.map(control) }), toggles.length === 0 ? null : _jsx("div", { className: "forgebook-toggles", children: toggles.map(toggle) }), others.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop }, prop.name))) }))] })] }) }));
+};
 /**
  * The worst case's button, and once it is on, how many elements spill (the frame outlines them).
  *
@@ -57,9 +76,17 @@ const WorstCaseControl = ({ worstCase }) => (_jsxs(_Fragment, { children: [_jsx(
  *
  * @param props - the props, the values, which props the story lets the panel set, and the setters.
  */
-export const PropsTab = ({ props, values, controls, onValueChange, onReset, worstCase, namedValues = {}, textArgs = NO_TEXT_ARGS }) => {
+export const PropsTab = ({ props, values, controls, onValueChange, onReset, worstCase, namedValues = {}, textArgs = NO_TEXT_ARGS, componentGroups = NO_GROUPS }) => {
+    const catalogue = useCatalogue();
     const isNamed = (prop) => isNamedProp(prop, namedValues);
-    const settable = settableProps(props, controls, namedValues);
+    const allSettable = settableProps(props, controls, namedValues);
+    const isSettable = (prop) => allSettable.includes(prop);
+    const propGroups = groupedProps(props.filter((prop) => prop.kind !== "event"), propGroupOrder(componentGroups, catalogue.propGroups));
+    // the props that name no group are drawn as the tab always drew them, by control
+    const ungrouped = propGroups.find((group) => group.name === undefined)?.props ?? [];
+    const settable = allSettable.filter((prop) => ungrouped.includes(prop));
+    const control = (prop) => (_jsx(PropControl, { prop: prop, value: values[prop.name], named: isNamed(prop) ? namedValues[prop.type] : undefined, textArg: textArgs[prop.name], onValueChange: onValueChange }, prop.name));
+    const toggle = (prop) => (_jsx(Toggle, { prop: prop, value: values[prop.name], onValueChange: onValueChange }, prop.name));
     const groups = [
         {
             title: STRINGS.propGroups.choice,
@@ -71,8 +98,7 @@ export const PropsTab = ({ props, values, controls, onValueChange, onReset, wors
         }
     ].filter((group) => group.props.length > 0);
     const toggles = settable.filter((prop) => prop.kind === "toggle");
-    const others = props.filter((prop) => prop.kind !== "event" && !settable.includes(prop));
+    const others = ungrouped.filter((prop) => !isSettable(prop));
     const hasControls = controls === "all" || controls.length > 0;
-    return (_jsxs("div", { className: "forgebook-tab-props", children: [hasControls ? null : _jsx("p", { className: "forgebook-tab-note", children: STRINGS.fixedExamples }), groups.map((group) => (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: group.title }), _jsx("div", { className: "forgebook-prop-grid", children: group.props.map((prop) => (_jsx(PropControl, { prop: prop, value: values[prop.name], named: isNamed(prop) ? namedValues[prop.type] : undefined, textArg: textArgs[prop.name], onValueChange: onValueChange }, prop.name))) })] }, group.title))), toggles.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.propGroups.toggle }), _jsx("div", { className: "forgebook-toggles", children: toggles.map((prop) => (_jsx(Toggle, { prop: prop, value: values[prop.name], onValueChange: onValueChange }, prop.name))) })] })), others.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasControls ? STRINGS.otherProps : STRINGS.allProps }), _jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsx("p", { className: "forgebook-prop__description", children: prop.description })] }, prop.name))) })] })), hasControls ? (_jsxs("div", { className: "forgebook-tab-foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: onReset, children: STRINGS.resetArgs }), worstCase?.canApply === true ? _jsx(WorstCaseControl, { worstCase: worstCase }) : null] })) : null] }));
+    return (_jsxs("div", { className: "forgebook-tab-props", children: [hasControls ? null : _jsx("p", { className: "forgebook-tab-note", children: STRINGS.fixedExamples }), groups.map((group) => (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: group.title }), _jsx("div", { className: "forgebook-prop-grid", children: group.props.map(control) })] }, group.title))), toggles.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: STRINGS.propGroups.toggle }), _jsx("div", { className: "forgebook-toggles", children: toggles.map(toggle) })] })), others.length === 0 ? null : (_jsxs("div", { className: "forgebook-prop-group", children: [_jsx("h3", { className: "forgebook-prop-group__title", children: hasControls ? STRINGS.otherProps : STRINGS.allProps }), _jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop }, prop.name))) })] })), propGroups.map((group) => group.name === undefined ? null : (_jsx(NamedGroup, { name: group.name, props: group.props, isSettable: isSettable, control: control, toggle: toggle }, group.name))), hasControls ? (_jsxs("div", { className: "forgebook-tab-foot", children: [_jsx("button", { type: "button", className: "forgebook-text-button", onClick: onReset, children: STRINGS.resetArgs }), worstCase?.canApply === true ? _jsx(WorstCaseControl, { worstCase: worstCase }) : null] })) : null] }));
 };
-//# sourceMappingURL=PropsTab.js.map

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

@@ -0,0 +1,63 @@
+/**
+ * The search's results: beside the sidebar, what the words find across the catalogue, each component or docs page with
+ * what matched inside it and why, and a key for every move.
+ *
+ * @remarks
+ * Loaded with its style sheet on first use, and it loads the index only when something is typed, so a reader who never
+ * searches pays for neither. The focus stays in the search field, as a list that follows the words needs: the arrows
+ * move the row `aria-activedescendant` names. Every row is a real link, so a modified press opens a new tab. The results
+ * sit beside the tree, which goes on filtering by name: the tree is for browsing what the words leave, this list for
+ * going to the exact place.
+ *
+ * @module
+ */
+import "./search.scss";
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ReactNode, type RefObject } from "react";
+import { type SearchTarget } from "../search.ts";
+import type { StoryTree } from "../storyTree.ts";
+import { shownTree } from "./treeSearch.ts";
+/** What the search field asks of the list. */
+export type SearchPanelKeys = {
+    /**
+     * Answers a key pressed in the field.
+     *
+     * @param key - the key.
+     * @param hasModifier - whether a key that opens a new tab is held.
+     * @returns whether the list used it.
+     */
+    readonly press: (key: string, hasModifier: boolean) => boolean;
+};
+/** The list's props. */
+export type SearchPanelProps = {
+    /** The tree. */
+    readonly tree: StoryTree;
+    /** The sources, with the loaders of their index. */
+    readonly sources: readonly StorySource[];
+    /** What was typed. */
+    readonly query: string;
+    /** Whether the list shows: closed, it stays mounted, so the index and the place are kept. */
+    readonly isOpen: boolean;
+    /** The search field: the list opens from where it is. */
+    readonly field: RefObject<HTMLInputElement | null>;
+    /** The sidebar's width, in CSS px. */
+    readonly sidebarWidth: number;
+    /** Called with the tree's filter, which comes with the list. */
+    readonly onFilterReady: (filter: typeof shownTree) => void;
+    /** The address of a result. */
+    readonly hrefOf: (target: SearchTarget) => string;
+    /** Goes to a result. */
+    readonly onOpen: (target: SearchTarget) => void;
+    /** Called with the highlighted row's element id. */
+    readonly onActiveChange: (id: string | undefined) => void;
+    /** Filled with what the field asks of the list. */
+    readonly keysRef: RefObject<SearchPanelKeys | null>;
+    /** The list's element id, for the field's `aria-controls`. */
+    readonly id: string;
+};
+/**
+ * The search's results.
+ *
+ * @param props - what was typed, what can be found and how to go to it.
+ */
+export declare const SearchPanel: ({ tree, sources, query, isOpen, field, sidebarWidth, onFilterReady, hrefOf, onOpen, onActiveChange, keysRef, id }: SearchPanelProps) => ReactNode;

package/dist/src/shell/SearchPanel.js

@@ -0,0 +1,209 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The search's results: beside the sidebar, what the words find across the catalogue, each component or docs page with
+ * what matched inside it and why, and a key for every move.
+ *
+ * @remarks
+ * Loaded with its style sheet on first use, and it loads the index only when something is typed, so a reader who never
+ * searches pays for neither. The focus stays in the search field, as a list that follows the words needs: the arrows
+ * move the row `aria-activedescendant` names. Every row is a real link, so a modified press opens a new tab. The results
+ * sit beside the tree, which goes on filtering by name: the tree is for browsing what the words leave, this list for
+ * going to the exact place.
+ *
+ * @module
+ */
+import "./search.css";
+import { useDeferredValue, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { searchables, searchCatalogue } from "../search.js";
+import { SEARCH_STRINGS } from "./searchStrings.js";
+import { shownTree } from "./treeSearch.js";
+import { useSearchIndex } from "./useSearchIndex.js";
+/** How much a page shows: what a person reads before refining the words. */
+const LIMITS = { results: 24, hits: 3 };
+/** The narrowest window where the list opens beside the sidebar: a smaller one has it over the sidebar, under the field. */
+const BESIDE_WIDTH = 720;
+/** The room between the field and the list when the list opens under it, in CSS px. */
+const LIST_GAP = 6;
+/** The room the list leaves around it, in CSS px. */
+const LIST_MARGIN = 8;
+/** The list's widest: long enough for a sentence around a match. */
+const LIST_WIDTH = "38rem";
+/**
+ * Where the list sits: beside the sidebar, or under the field on a small window.
+ *
+ * @param field - where the field is.
+ * @param sidebarWidth - the sidebar's width, in CSS px.
+ */
+const listPlace = (field, sidebarWidth) => {
+    if (window.innerWidth < BESIDE_WIDTH)
+        return { top: field.bottom + LIST_GAP, insetInline: LIST_MARGIN };
+    const start = sidebarWidth + LIST_MARGIN;
+    return {
+        top: field.top,
+        insetInlineStart: start,
+        width: `min(${LIST_WIDTH}, calc(100vw - ${start + LIST_MARGIN}px))`
+    };
+};
+/** How far each key moves the highlighted row. */
+const KEY_STEPS = { ArrowDown: 1, ArrowUp: -1 };
+/** The name of each kind of hit. */
+const HIT_NAMES = {
+    prop: SEARCH_STRINGS.hitProp,
+    event: SEARCH_STRINGS.hitEvent,
+    story: SEARCH_STRINGS.hitStory,
+    heading: SEARCH_STRINGS.hitHeading,
+    text: SEARCH_STRINGS.hitText,
+    description: SEARCH_STRINGS.hitDescription
+};
+/** Whether a press is a modified one, left to the browser: a new tab or a download. */
+const isModified = (event) => event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0;
+/**
+ * A text with what matched marked.
+ *
+ * @param props - the pieces.
+ */
+const Marked = ({ pieces }) => pieces.map((piece, place) => 
+// the pieces of a text never move: their place is who they are
+// biome-ignore lint/suspicious/noArrayIndexKey: see above
+piece.isMatch ? _jsx("mark", { children: piece.text }, place) : _jsx("span", { children: piece.text }, place));
+/** What a reason says. */
+const reasonText = ({ place, means }) => {
+    if (means !== undefined)
+        return SEARCH_STRINGS.means(means);
+    if (place === "keyword")
+        return SEARCH_STRINGS.reasonKeyword;
+    return place === "title" ? SEARCH_STRINGS.reasonPlace : undefined;
+};
+/**
+ * A row's link.
+ *
+ * @param props - the row, whether it is highlighted, and how it opens.
+ */
+const RowLink = ({ row, isActive, hrefOf, onOpen, onActive, className, children }) => (_jsx("a", { id: row.id, role: "option", tabIndex: -1, "aria-selected": isActive, "data-active": isActive ? "" : undefined, className: className, href: hrefOf(row.target), onPointerMove: onActive, onClick: (event) => {
+        if (isModified(event))
+            return;
+        event.preventDefault();
+        onOpen(row.target);
+    }, children: children }));
+/**
+ * A hit's line: what it is, its name, the words around the match.
+ *
+ * @param props - the hit.
+ */
+const HitLine = ({ hit }) => (_jsxs(_Fragment, { children: [_jsx("span", { className: "forgebook-result__why", children: HIT_NAMES[hit.kind] }), _jsxs("span", { className: "forgebook-result__body", children: [hit.label === undefined ? null : (_jsx("span", { className: "forgebook-result__label", "data-code": hit.kind === "prop" || hit.kind === "event" ? "" : undefined, children: _jsx(Marked, { pieces: hit.label }) })), hit.snippet.length === 0 ? null : (_jsx("span", { className: "forgebook-result__snippet", children: _jsx(Marked, { pieces: hit.snippet }) }))] })] }));
+/**
+ * A result's own line: its name, where it sits, and why its name is there.
+ *
+ * @param props - the result.
+ */
+const ResultLine = ({ result }) => {
+    const reasons = result.reasons.flatMap((reason) => reasonText(reason) ?? []);
+    return (_jsxs(_Fragment, { children: [_jsx("span", { className: "forgebook-result__name", children: _jsx(Marked, { pieces: result.name }) }), reasons.map((reason) => (_jsx("span", { className: "forgebook-result__why", children: reason }, reason))), _jsx("span", { className: "forgebook-result__place", children: result.place }), _jsx("span", { className: "forgebook-result__kind", children: result.kind === "page" ? SEARCH_STRINGS.kindPage : SEARCH_STRINGS.kindComponent })] }));
+};
+/**
+ * What a result leaves out: how much more is inside it, and the words it does not hold; nothing when it leaves out
+ * nothing.
+ *
+ * @param props - the result, and how many of its hits are listed.
+ */
+const ResultNote = ({ result, listed }) => {
+    const more = result.hitCount - listed;
+    if (more === 0 && result.missed.length === 0)
+        return null;
+    return (_jsxs("p", { className: "forgebook-result__note", children: [more > 0 ? _jsx("span", { children: SEARCH_STRINGS.more(more) }) : null, result.missed.length > 0 ? _jsx("span", { children: SEARCH_STRINGS.missing(result.missed.join(", ")) }) : null] }));
+};
+/** The answer's rows, for the keys and the list. */
+const useResultRows = (answer) => {
+    const baseId = useId();
+    return useMemo(() => answer.results.map((result, place) => ({
+        result,
+        own: { id: `${baseId}-${place}`, target: result.target },
+        hits: result.hits.map((hit, hitPlace) => ({
+            hit,
+            row: { id: `${baseId}-${place}-${hitPlace}`, target: hit.target }
+        }))
+    })), [answer, baseId]);
+};
+/** The highlighted row: moved by the keys and the pointer, kept in view, named to the field. */
+const useActiveRow = ({ rows, isShown, hrefOf, onOpen, onActiveChange, keysRef }) => {
+    const [place, setPlace] = useState(0);
+    // new words, or an index that arrived, change what each place holds: Enter must not open what the reader never saw
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the rows are what resets it
+    useEffect(() => setPlace(0), [rows]);
+    const active = rows[Math.min(place, rows.length - 1)];
+    const activeId = isShown ? active?.id : undefined;
+    useEffect(() => onActiveChange(activeId), [activeId, onActiveChange]);
+    const listRef = useRef(null);
+    useEffect(() => {
+        if (activeId === undefined)
+            return;
+        listRef.current?.querySelector(`[id="${CSS.escape(activeId)}"]`)?.scrollIntoView({ block: "nearest" });
+    }, [activeId]);
+    useImperativeHandle(keysRef, () => ({
+        press: (key, hasModifier) => {
+            if (activeId === undefined || active === undefined)
+                return false;
+            const step = KEY_STEPS[key];
+            if (step !== undefined)
+                setPlace((row) => (row + step + rows.length) % rows.length);
+            else if (key !== "Enter")
+                return false;
+            else if (hasModifier)
+                window.open(hrefOf(active.target), "_blank", "noopener");
+            else
+                onOpen(active.target);
+            return true;
+        }
+    }));
+    return { active, setActive: (row) => setPlace(rows.indexOf(row)), listRef };
+};
+/** The answer's state, in a line: how many results, what is still coming, what could not be read. */
+const PanelStatus = ({ total, query, isLoading, hasFailed }) => (_jsxs("p", { className: "forgebook-search-panel__status", role: "status", children: [total === 0 && !isLoading ? _jsx("span", { children: SEARCH_STRINGS.nothing(query.trim()) }) : null, total > 0 ? _jsx("span", { children: SEARCH_STRINGS.count(total) }) : null, isLoading ? _jsx("span", { children: SEARCH_STRINGS.reading }) : null, hasFailed ? _jsx("span", { children: SEARCH_STRINGS.unreadable }) : null] }));
+/**
+ * The search's results.
+ *
+ * @param props - what was typed, what can be found and how to go to it.
+ */
+export const SearchPanel = ({ tree, sources, query, isOpen, field, sidebarWidth, onFilterReady, hrefOf, onOpen, onActiveChange, keysRef, id }) => {
+    useEffect(() => onFilterReady(shownTree), [onFilterReady]);
+    // the index is asked for once, by the first words
+    const hasQuery = query.trim() !== "";
+    const [isWanted, setIsWanted] = useState(hasQuery);
+    if (hasQuery && !isWanted)
+        setIsWanted(true);
+    const { indexes, isLoading, hasFailed } = useSearchIndex(sources, isWanted);
+    const all = useMemo(() => searchables(tree, indexes), [tree, indexes]);
+    // the field never waits for a long list
+    const words = useDeferredValue(query);
+    const answer = useMemo(() => searchCatalogue(all, words, LIMITS), [all, words]);
+    const results = useResultRows(answer);
+    const rows = useMemo(() => results.flatMap(({ own, hits }) => [own, ...hits.map(({ row }) => row)]), [results]);
+    const isShown = isOpen && hasQuery;
+    const panelRef = useRef(null);
+    // in the top layer: the sidebar's own stacking would otherwise leave the list under the page it opens over
+    useLayoutEffect(() => {
+        if (isShown)
+            panelRef.current?.showPopover();
+    }, [isShown]);
+    const rect = isShown ? field.current?.closest("label")?.getBoundingClientRect() : undefined;
+    const { active, setActive, listRef } = useActiveRow({
+        rows,
+        isShown,
+        hrefOf,
+        onOpen,
+        onActiveChange,
+        keysRef
+    });
+    if (!isShown)
+        return null;
+    const rowProps = (row) => ({
+        row,
+        hrefOf,
+        onOpen,
+        isActive: row.id === active?.id,
+        onActive: () => setActive(row)
+    });
+    return (_jsxs("section", { ref: panelRef, popover: "manual", className: "forgebook-search-panel", "aria-label": SEARCH_STRINGS.results, "data-ready": isLoading ? undefined : "", style: rect === undefined ? undefined : listPlace(rect, sidebarWidth), 
+        // the focus stays in the field: a press here would take it away and close the list before it opens anything
+        onMouseDown: (event) => event.preventDefault(), children: [_jsx(PanelStatus, { total: answer.total, query: query, isLoading: isLoading, hasFailed: hasFailed }), _jsx("div", { id: id, ref: listRef, className: "forgebook-search-panel__list", role: "listbox", "aria-label": SEARCH_STRINGS.results, children: results.map(({ result, own, hits }) => (_jsxs("div", { className: "forgebook-result", children: [_jsx(RowLink, { ...rowProps(own), className: "forgebook-result__own", children: _jsx(ResultLine, { result: result }) }), hits.map(({ hit, row }) => (_jsx(RowLink, { ...rowProps(row), className: "forgebook-result__hit", children: _jsx(HitLine, { hit: hit }) }, row.id))), _jsx(ResultNote, { result: result, listed: hits.length })] }, own.id))) }), _jsxs("p", { className: "forgebook-search-panel__keys", children: [_jsx("kbd", { children: "\u2191" }), _jsx("kbd", { children: "\u2193" }), " ", SEARCH_STRINGS.keyMove, " ", _jsx("kbd", { children: "\u21B5" }), " ", SEARCH_STRINGS.keyOpen, " ", _jsx("kbd", { children: "esc" }), " ", SEARCH_STRINGS.keyClear] })] }));
+};

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

@@ -38,4 +38,3 @@ export type SegmentedProps<TValue extends string | number> = {
  * @param props - the options and the chosen value.
  */
 export declare const Segmented: <TValue extends string | number>({ label, options, value, onValueChange, isDisabled, disabledNote, after }: SegmentedProps<TValue>) => ReactNode;
-//# sourceMappingURL=Segmented.d.ts.map

package/dist/src/shell/Segmented.js

@@ -16,4 +16,3 @@ export const Segmented = ({ label, options, value, onValueChange, isDisabled = f
     const name = useId();
     return (_jsxs("fieldset", { className: "forgebook-segmented", disabled: isDisabled, title: isDisabled ? disabledNote : undefined, children: [_jsx("legend", { className: "forgebook-visually-hidden", children: label }), options.map((option) => (_jsxs("label", { className: "forgebook-segmented__option", title: option.icon ? option.label : undefined, children: [_jsx("input", { type: "radio", className: "forgebook-visually-hidden", name: name, checked: option.value === value, "aria-label": option.icon ? option.label : undefined, onChange: () => onValueChange(option.value) }), _jsx("span", { className: "forgebook-segmented__face", children: option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : option.label })] }, String(option.value)))), after] }));
 };
-//# sourceMappingURL=Segmented.js.map

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

@@ -5,18 +5,24 @@
  * @module
  */
 import type { StoryLanguage, StorySource } from "@forgebook/story-format/source";
-import { type ReactNode } from "react";
-import { type CatalogueLists } from "../catalogue.ts";
-import { type ViewSwitch } from "../switches.ts";
+import { type ComponentType, type ReactNode } from "react";
+import { type AddressTexts } from "../addressTexts.ts";
+import type { CatalogueLists } from "../catalogue.ts";
+import type { ViewSwitch } from "../switches.ts";
+import type { WrittenHomeProps } from "./AuthoredHome.tsx";
+import { type LoadPluginHosts } from "./pluginHostsContext.ts";
+import type { ShellPlugin } from "./pluginTabs.tsx";
 /** What an app passes to the shell. */
 export type ShellConfig = {
     /** The catalogue's name, in the page title and the sidebar. */
     readonly title: string;
     /**
      * The catalogue's logo, the URL of a square image: beside its name in the sidebar and as the page's icon. None by
-     * default: the catalogue's own mark. The catalogue belongs to whoever mounts it, so the logo is theirs to give.
+     * default: Forgebook's mark. The catalogue belongs to whoever mounts it, so the logo is theirs to give.
      */
     readonly logo?: string;
+    /** Whether a catalogue without a logo shows Forgebook's mark; off, it shows its name alone. On by default. */
+    readonly hasBranding?: boolean;
     /**
      * The stories' measured heights, the address of the file `forgebook-heights` writes (relative to the page): a story's
      * box waits at its height while it loads. None by default, and a missing file is none: boxes then wait at a guess.
@@ -24,7 +30,10 @@ export type ShellConfig = {
     readonly heights?: string;
     /** The sources, in the order the sidebar lists them. */
     readonly sources: readonly StorySource[];
-    /** The frame page's address, relative to the shell's (`frame.html`). */
+    /**
+     * The frame page's address: relative to the shell's (`frame.html`) when the frames share its origin, on the frames'
+     * origin otherwise (`mountShell` makes it).
+     */
     readonly frameUrl: string;
     /**
      * The languages every story can be drawn in (the View menu's Language row); none turns them off. Give the frame
@@ -38,6 +47,26 @@ export type ShellConfig = {
     readonly switches?: readonly ViewSwitch[];
     /** The catalogue's lists (its widths, zoom steps, backgrounds, story groups…); the defaults when none. */
     readonly lists?: CatalogueLists;
+    /**
+     * Loads the catalogue's written home (`forgebook.home.md`), drawn in place of the generated home: the page's entry
+     * gives it only for a catalogue that has one, so the others' first load carries nothing of it. None keeps the
+     * generated home.
+     */
+    readonly home?: () => Promise<ComponentType<WrittenHomeProps>>;
+    /** Loads the catalogue's design tokens, on first use; none when it has none. */
+    readonly loadTokens?: () => Promise<unknown>;
+    /** The plugins with views (the generated page passes them); none by default. */
+    readonly plugins?: readonly ShellPlugin[];
+    /**
+     * Loads the code that draws the plugins' views (`forgebook/shell/plugin-hosts`): the generated page gives it only
+     * with plugins that have views, so a catalogue without one ships none of it. None draws no plugin's view.
+     */
+    readonly pluginHosts?: LoadPluginHosts;
+    /**
+     * How the framework's stories take the texts the address carries (`addressTexts.ts`): `plain` keeps a shared link's
+     * texts that are not plain words from a story that may write them into markup. `any` by default.
+     */
+    readonly addressTexts?: AddressTexts;
 };
 /**
  * The catalogue's page: its settings computed once from the configuration (its switches, its languages' switch, its
@@ -46,4 +75,3 @@ export type ShellConfig = {
  * @param props - the configuration.
  */
 export declare const Shell: (props: ShellConfig) => ReactNode;
-//# sourceMappingURL=Shell.d.ts.map