forgebook 0.1.8 → 0.3.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/PropRows.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One prop of the Props tab as it is drawn: its head (its name, whether it is required, its group in the "Required"
+ * group, its type), then its control, its toggle, or its description for reading.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import { type PanelProp } from "../argTypes.ts";
+import { type ArgValue } from "../messages.ts";
+import { type OnValueChange } from "./PropFields.tsx";
+/** A prop the story gives a text by its key (`storyText("key")`): the key, and whether the panel wrote over it. */
+export type TextArgNote = {
+    /** The text's key. */
+    readonly key: string;
+    /** Whether the panel holds a value of its own for the prop. */
+    readonly isChanged: boolean;
+};
+/** One adjustable prop with its control. */
+export declare const PropControl: ({ prop, showsGroup, value, named, textArg, onValueChange }: {
+    readonly prop: PanelProp;
+    /** Whether it names its group: in the "Required" group. */
+    readonly showsGroup: boolean;
+    readonly value: ArgValue | undefined;
+    /** The values the source names for the prop's type, when it names some. */
+    readonly named: Readonly<Record<string, unknown>> | undefined;
+    /** Where the story's text for the prop comes from, when the story names one by its key. */
+    readonly textArg: TextArgNote | undefined;
+    readonly onValueChange: OnValueChange;
+}) => ReactNode;
+/** A toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
+export declare const Toggle: ({ prop, showsGroup, value, onValueChange }: {
+    readonly prop: PanelProp;
+    /** Whether it names its group: in the "Required" group. */
+    readonly showsGroup: boolean;
+    readonly value: ArgValue | undefined;
+    readonly onValueChange: OnValueChange;
+}) => ReactNode;
+/** A prop the panel cannot set: its name, its type and its description, for reading; its group when asked. */
+export declare const ReadOnlyProp: ({ prop, showsGroup }: {
+    readonly prop: PanelProp;
+    readonly showsGroup: boolean;
+}) => ReactNode;

package/dist/src/shell/PropRows.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * One prop of the Props tab as it is drawn: its head (its name, whether it is required, its group in the "Required"
+ * group, its type), then its control, its toggle, or its description for reading.
+ *
+ * @module
+ */
+import { useId } from "react";
+import { isColorProp } from "../argTypes.js";
+import { isNamedArg } from "../messages.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";
+/** A prop's group, beside its name in the "Required" group, which gathers props of every group. */
+const GroupName = ({ prop, showsGroup }) => showsGroup && prop.group !== undefined ? _jsx("span", { className: "forgebook-prop__group", children: prop.group }) : null;
+/**
+ * A prop's name, whether it is required, its group when asked, and its type (whole in the tooltip when it is cut).
+ *
+ * @param props - the prop, and whether it names its group.
+ */
+const PropHead = ({ prop, showsGroup }) => (_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(GroupName, { prop: prop, showsGroup: showsGroup }), _jsx("code", { className: "forgebook-prop__type", title: prop.type, children: prop.type })] }));
+/** A prop's description and default, under its control. */
+const PropNote = ({ id, prop }) => prop.description === "" && prop.defaultValue === undefined ? null : (_jsxs("p", { id: id, className: "forgebook-prop__description", children: [prop.description, prop.defaultValue === undefined ? null : (_jsxs(_Fragment, { children: [prop.description === "" ? null : " ", STRINGS.defaultIs, " ", _jsx("code", { children: prop.defaultValue })] }))] }));
+/**
+ * Where a prop's text comes from, under its field: the key of the story's text, and a way back to it once the panel
+ * wrote over it.
+ *
+ * @param props - the note, the prop's name and the value setter.
+ */
+const TextArgLine = ({ note, name, onValueChange }) => (_jsxs("p", { className: "forgebook-prop__text-arg", children: [STRINGS.fromTexts, " ", _jsx("code", { children: note.key }), note.isChanged ? (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => onValueChange(name, undefined), children: STRINGS.backToText })) : null] }));
+/** One adjustable prop with its control. */
+export const PropControl = ({ prop, showsGroup, value, named, textArg, onValueChange }) => {
+    // the description is shown under the control and named by it, so the control's name is the prop alone
+    const descriptionId = useId();
+    const label = prop.label ?? prop.name;
+    if (named !== undefined) {
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsxs("select", { "aria-label": label, "aria-describedby": descriptionId, value: isNamedArg(value) ? value.named : "", onChange: (event) => {
+                        const chosen = event.target.value;
+                        onValueChange(prop.name, chosen === "" ? undefined : { of: prop.type, named: chosen });
+                    }, children: [_jsx("option", { value: "", children: STRINGS.unset }), Object.keys(named).map((name) => (_jsx("option", { value: name, children: name }, name)))] }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+    }
+    if (prop.kind === "choice") {
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx(ChoiceControl, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+    }
+    if (prop.kind === "number") {
+        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx("div", { className: "forgebook-prop__field", children: _jsx(NumberField, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+    }
+    return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsxs("div", { className: "forgebook-prop__field", children: [_jsx("input", { type: "text", "aria-label": label, "aria-describedby": descriptionId, value: textOf(value), onChange: (event) => {
+                            const text = event.target.value;
+                            onValueChange(prop.name, text === "" ? undefined : text);
+                        } }), isColorProp(prop) ? (_jsx("input", { type: "color", className: "forgebook-prop__color", "aria-label": STRINGS.pickColor(label), value: pickerColor(value), onChange: (event) => onValueChange(prop.name, event.target.value) })) : null] }), textArg === undefined ? null : (_jsx(TextArgLine, { note: textArg, name: prop.name, onValueChange: onValueChange })), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
+};
+/** A toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
+export const Toggle = ({ prop, showsGroup, value, onValueChange }) => {
+    const descriptionId = useId();
+    return (_jsxs("label", { className: "forgebook-toggle", title: prop.description, children: [_jsx("input", { type: "checkbox", "aria-label": prop.label ?? prop.name, checked: value === true, "aria-describedby": descriptionId, onChange: (event) => onValueChange(prop.name, event.target.checked) }), _jsx("code", { children: prop.label ?? prop.name }), _jsx(GroupName, { prop: prop, showsGroup: showsGroup }), _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; its group when asked. */
+export const ReadOnlyProp = ({ prop, showsGroup }) => (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop, showsGroup: showsGroup }), _jsx("p", { className: "forgebook-prop__description", children: prop.description })] }));

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

@@ -5,21 +5,25 @@
  * (`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.
+ *
+ * The required props come first among each kind of control and in each group, or in one "Required" group before the
+ * others, each naming its group, as the story, its component, the catalogue and the reader's switch at the top of the
+ * tab say (`useRequiredFirst.ts`).
+ *
  * @module
  */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
 import type { StoryControlsSetting } from "@forgebook/story-format/source";
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type PanelProp } from "../argTypes.ts";
-import { type ArgValue, type PanelArgs } from "../messages.ts";
+import type { ArgValue, PanelArgs } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
+import { type TextArgNote } from "./PropRows.tsx";
 import type { WorstCaseState } from "./worstArgs.ts";
-/** A prop the story gives a text by its key (`storyText("key")`): the key, and whether the panel wrote over it. */
-export type TextArgNote = {
-    /** The text's key. */
-    readonly key: string;
-    /** Whether the panel holds a value of its own for the prop. */
-    readonly isChanged: boolean;
-};
 /** The tab's props. */
 export type PropsTabProps = {
     /** The props, from the component's types with the story's `argTypes` laid over them. */
@@ -38,11 +42,20 @@ 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[];
+    /**
+     * Where the story puts the required props (`parameters.requiredFirst`, its own or its meta's); none for the
+     * catalogue's.
+     */
+    readonly requiredFirst?: RequiredFirst | undefined;
 };
 /**
  * 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, requiredFirst }: PropsTabProps) => ReactNode;

package/dist/src/shell/PropsTab.js

@@ -1,50 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useId } from "react";
-import { isColorProp, isNamedProp, settableProps } from "../argTypes.js";
-import { isNamedArg } from "../messages.js";
-import { ChoiceControl, NumberField, textOf } from "./PropFields.js";
+import { isNamedProp, settableProps } from "../argTypes.js";
+import { canOrderRequired, laidOutProps, propGroupOrder } from "../propGroups.js";
+import { useCatalogue } from "./catalogueContext.js";
+import { Icon } from "./icons.js";
+import { PropControl, ReadOnlyProp, Toggle } from "./PropRows.js";
+import { RequiredFirstSwitch } from "./RequiredFirstSwitch.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";
+import { useRequiredFirst } from "./useRequiredFirst.js";
 /** No prop named by a text key. */
 const NO_TEXT_ARGS = {};
-/** 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. */
-const PropNote = ({ id, prop }) => prop.description === "" && prop.defaultValue === undefined ? null : (_jsxs("p", { id: id, className: "forgebook-prop__description", children: [prop.description, prop.defaultValue === undefined ? null : (_jsxs(_Fragment, { children: [prop.description === "" ? null : " ", STRINGS.defaultIs, " ", _jsx("code", { children: prop.defaultValue })] }))] }));
+/** No group named first. */
+const NO_GROUPS = [];
 /**
- * Where a prop's text comes from, under its field: the key of the story's text, and a way back to it once the panel
- * wrote over it.
+ * 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. The "Required" group is drawn as one, each of its props naming its own group.
  *
- * @param props - the note, the prop's name and the value setter.
+ * @param props - the group's name and props, how each prop is drawn, and whether it is the "Required" group.
  */
-const TextArgLine = ({ note, name, onValueChange }) => (_jsxs("p", { className: "forgebook-prop__text-arg", children: [STRINGS.fromTexts, " ", _jsx("code", { children: note.key }), note.isChanged ? (_jsx("button", { type: "button", className: "forgebook-text-button", onClick: () => onValueChange(name, undefined), children: STRINGS.backToText })) : null] }));
-/** One adjustable prop with its control. */
-const PropControl = ({ prop, value, named, textArg, onValueChange }) => {
-    // the description is shown under the control and named by it, so the control's name is the prop alone
-    const descriptionId = useId();
-    const label = prop.label ?? prop.name;
-    if (named !== undefined) {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsxs("select", { "aria-label": label, "aria-describedby": descriptionId, value: isNamedArg(value) ? value.named : "", onChange: (event) => {
-                        const chosen = event.target.value;
-                        onValueChange(prop.name, chosen === "" ? undefined : { of: prop.type, named: chosen });
-                    }, children: [_jsx("option", { value: "", children: STRINGS.unset }), Object.keys(named).map((name) => (_jsx("option", { value: name, children: name }, name)))] }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
-    }
-    if (prop.kind === "choice") {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsx(ChoiceControl, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
-    }
-    if (prop.kind === "number") {
-        return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsx("div", { className: "forgebook-prop__field", children: _jsx(NumberField, { prop: prop, value: value, descriptionId: descriptionId, onValueChange: onValueChange }) }), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
-    }
-    return (_jsxs("div", { className: "forgebook-prop", children: [_jsx(PropHead, { prop: prop }), _jsxs("div", { className: "forgebook-prop__field", children: [_jsx("input", { type: "text", "aria-label": label, "aria-describedby": descriptionId, value: textOf(value), onChange: (event) => {
-                            const text = event.target.value;
-                            onValueChange(prop.name, text === "" ? undefined : text);
-                        } }), isColorProp(prop) ? (_jsx("input", { type: "color", className: "forgebook-prop__color", "aria-label": STRINGS.pickColor(label), value: pickerColor(value), onChange: (event) => onValueChange(prop.name, event.target.value) })) : null] }), textArg === undefined ? null : (_jsx(TextArgLine, { note: textArg, name: prop.name, onValueChange: onValueChange })), _jsx(PropNote, { id: descriptionId, prop: prop })] }));
-};
-/** A toggle: its name in a compact checkbox, its description as the tooltip and for screen readers. */
-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 })] }));
+const NamedGroup = ({ name, props, isSettable, control, toggle, isRequired = false }) => {
+    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", "data-required": isRequired || undefined, 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((prop) => control(prop, isRequired)) })), toggles.length === 0 ? null : (_jsx("div", { className: "forgebook-toggles", children: toggles.map((prop) => toggle(prop, isRequired)) })), others.length === 0 ? null : (_jsx("div", { className: "forgebook-prop-grid", children: others.map((prop) => (_jsx(ReadOnlyProp, { prop: prop, showsGroup: isRequired }, prop.name))) }))] })] }) }));
 };
 /**
  * The worst case's button, and once it is on, how many elements spill (the frame outlines them).
@@ -57,9 +34,19 @@ 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, requiredFirst }) => {
+    const catalogue = useCatalogue();
+    const ordering = useRequiredFirst(requiredFirst);
     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 listed = props.filter((prop) => prop.kind !== "event");
+    const { required, groups: propGroups } = laidOutProps(listed, propGroupOrder(componentGroups, catalogue.propGroups), ordering.layout);
+    // the props that name no group are drawn as the tab always drew them, by control, in the layout's order
+    const ungrouped = propGroups.find((group) => group.name === undefined)?.props ?? [];
+    const settable = ungrouped.filter(isSettable);
+    const control = (prop, showsGroup) => (_jsx(PropControl, { prop: prop, showsGroup: showsGroup, value: values[prop.name], named: isNamed(prop) ? namedValues[prop.type] : undefined, textArg: textArgs[prop.name], onValueChange: onValueChange }, prop.name));
+    const toggle = (prop, showsGroup) => (_jsx(Toggle, { prop: prop, showsGroup: showsGroup, value: values[prop.name], onValueChange: onValueChange }, prop.name));
     const groups = [
         {
             title: STRINGS.propGroups.choice,
@@ -71,8 +58,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: [canOrderRequired(listed) ? (_jsx("div", { className: "forgebook-tab-head", children: _jsx(RequiredFirstSwitch, { state: ordering }) })) : null, hasControls ? null : _jsx("p", { className: "forgebook-tab-note", children: STRINGS.fixedExamples }), required.length === 0 ? null : (_jsx(NamedGroup, { name: STRINGS.required, props: required, isSettable: isSettable, control: control, toggle: toggle, isRequired: true })), 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) => control(prop, false)) })] }, 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) => toggle(prop, false)) })] })), 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, showsGroup: false }, 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/RequiredFirstSwitch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The "Required first" switch in the header of a props table (the API reference, the Props tab): the reader turns the
+ * ordering of the required props on or off for every component (`useRequiredFirst.ts`).
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { RequiredFirstState } from "./useRequiredFirst.ts";
+/**
+ * The switch.
+ *
+ * @param props - its state, from `useRequiredFirst`.
+ */
+export declare const RequiredFirstSwitch: ({ state }: {
+    readonly state: Pick<RequiredFirstState, "isOn" | "setIsOn">;
+}) => ReactNode;

package/dist/src/shell/RequiredFirstSwitch.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { STRINGS } from "./strings.js";
+/**
+ * The switch.
+ *
+ * @param props - its state, from `useRequiredFirst`.
+ */
+export const RequiredFirstSwitch = ({ state }) => (_jsxs("label", { className: "forgebook-required-first", title: STRINGS.requiredFirstHint, children: [_jsx("input", { type: "checkbox", role: "switch", "aria-checked": state.isOn, className: "forgebook-switch", checked: state.isOn, onChange: (event) => state.setIsOn(event.currentTarget.checked) }), STRINGS.requiredFirst] }));

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;