forgebook 0.2.0 → 0.3.0

package/dist/src/shell/PropsTab.js

@@ -1,69 +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 { groupedProps, propGroupOrder } from "../propGroups.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 { ChoiceControl, NumberField, textOf } from "./PropFields.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 = {};
 /** 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. */
-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. */
-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 })] }));
-};
-/** 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.
+ * the panel cannot set. The "Required" group is drawn as one, each of its props naming its own group.
  *
- * @param props - the group's name and props, and how each prop is drawn.
+ * @param props - the group's name and props, how each prop is drawn, and whether it is the "Required" group.
  */
-const NamedGroup = ({ name, props, isSettable, control, toggle }) => {
+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", 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))) }))] })] }) }));
+    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).
@@ -76,17 +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, componentGroups = NO_GROUPS }) => {
+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 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 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 = 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 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,
@@ -100,5 +60,5 @@ export const PropsTab = ({ props, values, controls, onValueChange, onReset, wors
     const toggles = settable.filter((prop) => prop.kind === "toggle");
     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(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] }));
+    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] }));
 };

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/Stage.js

@@ -15,7 +15,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { panelProps, settableProps } from "../argTypes.js";
 import { matrixOf, matrixProps } from "../matrix.js";
 import { panelArgsParam, parsePanelArgsParam } from "../messages.js";
-import { NOT_FIXED, withFixed, withOwnFixed } from "../storyGlobals.js";
+import { withFixed, withOwnFixed } from "../storyGlobals.js";
 import { frameAddress, isComparing, liveView, schemeOf, viewParams } from "../viewState.js";
 import { useStoryClockControls } from "./ClockControls.js";
 import { useCatalogue } from "./catalogueContext.js";
@@ -25,22 +25,21 @@ import { DroppedArgsNote } from "./DroppedArgsNote.js";
 import { dockTabs } from "./dockTabs.js";
 import { FrameView, tellFrames } from "./FrameView.js";
 import { framesOrigin } from "./framesOrigin.js";
+import { reportedPanel } from "./reportedPanel.js";
 import { StageCompare } from "./StageCompare.js";
 import { StageTools } from "./StageTools.js";
 import { StageViewport } from "./StageViewport.js";
 import { StoryBar } from "./StoryBar.js";
 import { STRINGS } from "./strings.js";
 import { useAddressArgs } from "./useAddressArgs.js";
-import { useComponentDocs } from "./useComponentDocs.js";
 import { useFrameMessages } from "./useFrameMessages.js";
 import { useLiveView, useLoadedView } from "./useLiveView.js";
+import { usePanelDocs } from "./usePanelDocs.js";
 import { usePluginStory, usePluginTabs } from "./usePluginTabs.js";
 import { useScrollMemory } from "./useScrollMemory.js";
 import { useStoryCheck } from "./useStoryCheck.js";
 import { useStoryCode } from "./useStoryCode.js";
 import { useWorstCase } from "./useWorstCase.js";
-/** The `argTypes` of a story before its frame reported them. */
-const NO_ARG_TYPES = {};
 /**
  * What the stage's handles set the width with; none, so no handles, when the story fixes the width.
  *
@@ -49,20 +48,6 @@ const NO_ARG_TYPES = {};
  * @param onViewChange - the view's setter.
  */
 const widthSetter = (fixed, view, onViewChange) => fixed.width === undefined ? (width) => onViewChange({ ...view, width }) : undefined;
-/**
- * A story's `argTypes`, controls, actions and fixed view for the panel and the stage: as its frame read them once it ran, which sees a setting
- * written by code the index leaves out; the index's controls and no `argTypes` or actions before.
- *
- * @param panels - what each story's frame reported, by story.
- * @param story - the story.
- */
-const reportedPanel = (panels, story) => panels.get(story.id) ?? {
-    argTypes: NO_ARG_TYPES,
-    controls: story.controls,
-    actions: [],
-    fixed: NOT_FIXED,
-    parameters: []
-};
 /** The height of the first frame before its story reports its own, in CSS px. */
 const INITIAL_FRAME_HEIGHT = 240;
 /** The most calls the Events tab keeps. */
@@ -105,7 +90,6 @@ const embedHeight = (view, contentHeight, story) => view.height === "auto" ? Mat
 export const Stage = ({ component, story, view: ownView, onViewChange: onOwnViewChange, onFixedChange, panelArgs, onPanelArgsChange, matrixAxes, onMatrixAxesChange, frameUrl, plugins, loadCode, loadDocs, namedValues, header, onShownWidthChange, measuredHeight, backgroundOf, scroll }) => {
     const frameRef = useRef(null);
     const storyRef = useRef(null);
-    const docs = useComponentDocs(loadDocs);
     const code = useStoryCode(loadCode);
     // the story's own args, as each frame reported them, by story
     const [storyArgs, setStoryArgs] = useState(new Map());
@@ -115,14 +99,17 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     const [storyPanels, setStoryPanels] = useState(new Map());
     // the story is drawn with what it fixes of the view; a change from here keeps the user's own in the address
     const panel = reportedPanel(storyPanels, story);
-    const view = withFixed(ownView, panel.fixed);
+    const catalogue = useCatalogue();
+    const docs = usePanelDocs(loadDocs, component.name, storyArgs.get(story.id), panel.actions);
+    // kept while neither changes: every new switches' object sends the frames the view, and a story whose height moves
+    // renders the stage at each report
+    const view = useMemo(() => withFixed(ownView, panel.fixed), [ownView, panel.fixed]);
     const onViewChange = (changed) => onOwnViewChange(withOwnFixed(changed, ownView, panel.fixed));
     const [calls, setCalls] = useState([]);
     // each story's play trace, by story: a trace belongs to the story that played
     const [traces, setTraces] = useState(new Map());
     // what each plugin's frame module last told its tab, by story: a plugin's report belongs to the story that sent it
     const [pluginReports, setPluginReports] = useState(new Map());
-    const catalogue = useCatalogue();
     const { switches } = catalogue;
     const storyCheck = useStoryCheck(frameRef, frameAddress(frameUrl, story.id, view, switches));
     const eventNames = useMemo(() => docs.status === "ready"
@@ -192,6 +179,8 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
         onSpills: worstCase.receive,
         onPluginReport: (message) => setPluginReports((current) => new Map(current).set(`${message.storyId}|${message.plugin}`, message)),
         // a story that changes its own args changes the panel's values, as the reader would
+        // a story that could not be shown reports no args: the panel built from them has none, rather than waiting
+        onFailed: (storyId) => setStoryArgs((current) => (current.has(storyId) ? current : new Map(current).set(storyId, {}))),
         onStoryArgs: (storyId, args) => storyId === story.id ? onPanelArgsChange(args) : undefined
     });
     // the docs may arrive after the frames: they learn the events then
@@ -254,8 +243,7 @@ export const Stage = ({ component, story, view: ownView, onViewChange: onOwnView
     const tabs = dockTabs({
         docs,
         code,
-        exportName: story.exportName,
-        isLogic: story.isLogic,
+        story,
         componentName: component.name,
         argTypes: panel.argTypes,
         controls: panel.controls,

package/dist/src/shell/StoryCoverage.js

@@ -16,6 +16,7 @@ import { groupLabel } from "../catalogue.js";
 import { groupedStories } from "../storyTree.js";
 import { AUDIENCE_TEXTS } from "./audiencePage.js";
 import { CodeText } from "./CodeText.js";
+import { useCatalogue } from "./catalogueContext.js";
 import { StoryLink } from "./Example.js";
 import { framesOrigin } from "./framesOrigin.js";
 import { a11yHint } from "./tabSummaries.js";
@@ -118,9 +119,11 @@ const checkText = (check) => {
  */
 export const StoryCoverage = ({ stories, storyGroups, queue, pageRef, settled, hrefOf, onOpen }) => {
     const { checks, checkAll } = usePageChecks(pageRef, queue, settled);
+    // a catalogue that checks no accessibility has no column for it, nor a check to run
+    const hasA11y = useCatalogue().a11y !== undefined;
     const ordered = groupedStories(stories, storyGroups.map((group) => group.id)).flatMap((section) => section.stories);
     const played = stories.filter((story) => story.hasPlay).length;
     const untested = stories.filter(isUntested).length;
     const finished = [...checks.values()].filter((check) => check.status !== "running").length;
-    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-coverage", children: [_jsx("h2", { id: "forgebook-coverage", children: AUDIENCE_TEXTS.coverage }), _jsxs("div", { className: "forgebook-coverage__head", children: [_jsx("p", { className: "forgebook-coverage__summary", children: AUDIENCE_TEXTS.coverageSummary(stories.length, played, untested) }), _jsx("button", { type: "button", className: "forgebook-button", onClick: checkAll, children: AUDIENCE_TEXTS.coverageCheckAll })] }), _jsx("p", { className: "forgebook-coverage__progress", role: "status", children: checks.size === 0 ? "" : AUDIENCE_TEXTS.coverageChecked(finished, stories.length) }), _jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageStory }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageGroup }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coveragePlay }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageTests }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageA11y })] }) }), _jsx("tbody", { children: ordered.map((story) => (_jsxs("tr", { children: [_jsxs("th", { scope: "row", className: "forgebook-coverage__story", children: [_jsx(StoryLink, { story: story, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: story.name }), story.description === undefined ? null : (_jsx("span", { className: "forgebook-coverage__covers", children: _jsx(CodeText, { text: story.description }) }))] }), _jsx("td", { children: story.group === undefined ? "" : groupLabel(storyGroups, story.group) }), _jsx("td", { children: story.hasPlay ? AUDIENCE_TEXTS.coverageHasPlay : AUDIENCE_TEXTS.coverageNoPlay }), _jsx("td", { children: isUntested(story) ? AUDIENCE_TEXTS.coverageUntested : AUDIENCE_TEXTS.coverageTested }), _jsx("td", { children: checkText(checks.get(story.id)) })] }, story.id))) })] }) })] }));
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-coverage", children: [_jsx("h2", { id: "forgebook-coverage", children: AUDIENCE_TEXTS.coverage }), _jsxs("div", { className: "forgebook-coverage__head", children: [_jsx("p", { className: "forgebook-coverage__summary", children: AUDIENCE_TEXTS.coverageSummary(stories.length, played, untested) }), hasA11y ? (_jsx("button", { type: "button", className: "forgebook-button", onClick: checkAll, children: AUDIENCE_TEXTS.coverageCheckAll })) : null] }), hasA11y ? (_jsx("p", { className: "forgebook-coverage__progress", role: "status", children: checks.size === 0 ? "" : AUDIENCE_TEXTS.coverageChecked(finished, stories.length) })) : null, _jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageStory }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageGroup }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coveragePlay }), _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageTests }), hasA11y ? _jsx("th", { scope: "col", children: AUDIENCE_TEXTS.coverageA11y }) : null] }) }), _jsx("tbody", { children: ordered.map((story) => (_jsxs("tr", { children: [_jsxs("th", { scope: "row", className: "forgebook-coverage__story", children: [_jsx(StoryLink, { story: story, hrefOf: hrefOf, onOpen: onOpen, className: "forgebook-link", children: story.name }), story.description === undefined ? null : (_jsx("span", { className: "forgebook-coverage__covers", children: _jsx(CodeText, { text: story.description }) }))] }), _jsx("td", { children: story.group === undefined ? "" : groupLabel(storyGroups, story.group) }), _jsx("td", { children: story.hasPlay ? AUDIENCE_TEXTS.coverageHasPlay : AUDIENCE_TEXTS.coverageNoPlay }), _jsx("td", { children: isUntested(story) ? AUDIENCE_TEXTS.coverageUntested : AUDIENCE_TEXTS.coverageTested }), hasA11y ? _jsx("td", { children: checkText(checks.get(story.id)) }) : null] }, story.id))) })] }) })] }));
 };

package/dist/src/shell/docPage.css

@@ -168,6 +168,7 @@
   .forgebook-aside {
     --forgebook-tone: var(--forgebook-accent-text);
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.5rem;
     min-width: 0;
     margin: 0;
@@ -199,6 +200,7 @@
   }
   .forgebook-tabs {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.75rem;
     min-width: 0;
   }
@@ -234,6 +236,7 @@
   }
   .forgebook-tabs__panel {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 1rem;
     min-width: 0;
   }
@@ -242,6 +245,7 @@
   }
   .forgebook-steps {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 1.25rem;
     margin: 0;
     padding: 0;
@@ -251,6 +255,7 @@
   .forgebook-steps__step {
     position: relative;
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.75rem;
     min-width: 0;
     padding-inline-start: calc(1.75rem + 0.75rem);
@@ -288,6 +293,7 @@
   }
   .forgebook-card {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     align-content: start;
     gap: 0.5rem;
     min-width: 0;

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

@@ -16,9 +16,10 @@ import { type ComponentDocs } from "../componentDocs.ts";
 import type { ArgValue, PanelArgs } from "../messages.ts";
 import type { NamedValues } from "../namedValues.ts";
 import type { PlayTrace } from "../playTrace.ts";
+import type { TreeStory } from "../storyTree.ts";
 import type { CheckState } from "./A11yTab.tsx";
 import type { DockTab } from "./Dock.tsx";
-import { type TextArgNote } from "./PropsTab.tsx";
+import type { TextArgNote } from "./PropRows.tsx";
 import type { EventCall } from "./useFrameMessages.ts";
 import type { Loaded } from "./useLoaded.ts";
 import type { WorstCaseState } from "./worstArgs.ts";
@@ -28,10 +29,11 @@ export type DockTabsInput = {
     readonly docs: Loaded<ComponentDocs>;
     /** The story file's code, as loaded. */
     readonly code: Loaded<StoryFileCode>;
-    /** The story's export name. */
-    readonly exportName: string;
-    /** Whether the story is about logic: its hook's signature comes first. */
-    readonly isLogic: boolean;
+    /**
+     * The story: its export name, whether it is about logic (its hook's signature comes first), and where it puts the
+     * required props (none for the catalogue's).
+     */
+    readonly story: Pick<TreeStory, "exportName" | "isLogic" | "requiredFirst">;
     /** The component's name from the sidebar, for the JSX when the docs have none. */
     readonly componentName: string;
     /** The props the story lets the panel set. */

package/dist/src/shell/dockTabs.js

@@ -30,7 +30,7 @@ const propsTab = (input, props) => props.some((prop) => prop.kind !== "event")
         {
             id: "props",
             label: STRINGS.tabs.props,
-            content: (_jsx(PropsTab, { props: props, values: input.values, controls: input.controls, onValueChange: input.onValueChange, onReset: input.onReset, worstCase: input.worstCase, namedValues: input.namedValues, textArgs: input.textArgs, componentGroups: input.propGroups }))
+            content: (_jsx(PropsTab, { props: props, values: input.values, controls: input.controls, onValueChange: input.onValueChange, onReset: input.onReset, worstCase: input.worstCase, namedValues: input.namedValues, textArgs: input.textArgs, componentGroups: input.propGroups, requiredFirst: input.story.requiredFirst }))
         }
     ]
     : [];
@@ -78,7 +78,7 @@ const docsTabs = (input) => {
         ];
     }
     // the docs' place while they load or fail: the tab the story opens on once they are read
-    const docsTab = input.isLogic
+    const docsTab = input.story.isLogic
         ? { id: "signature", label: STRINGS.tabs.signature }
         : { id: "props", label: STRINGS.tabs.props };
     // the play's trace comes from the frame, not from the docs: a first read of a project's docs can take seconds, and a
@@ -91,7 +91,7 @@ const docsTabs = (input) => {
     }
     const component = docs.value;
     const events = eventsOf(component.props, input.actions);
-    if (input.isLogic)
+    if (input.story.isLogic)
         return logicTabs(input, component);
     const tabs = [];
     tabs.push(...propsTab(input, panelProps(component.props, input.argTypes)));
@@ -158,7 +158,7 @@ const codeTabs = (input) => {
             label: STRINGS.tabs.code,
             content: (_jsx(LazyTab, { module: CODE_TAB, tabProps: {
                     code: code.value,
-                    exportName: input.exportName,
+                    exportName: input.story.exportName,
                     componentName: docs.status === "ready" ? codeNameOf(docs.value) : input.componentName,
                     args: input.values
                 } }))

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

@@ -0,0 +1,12 @@
+import type { TreeStory } from "../storyTree.ts";
+import type { ReadyMessage } from "./useFrameMessages.ts";
+/** What a story's frame reports for the panel and the stage. */
+export type ReportedPanel = Pick<ReadyMessage, "argTypes" | "controls" | "actions" | "fixed" | "parameters">;
+/**
+ * A story's `argTypes`, controls, actions and fixed view for the panel and the stage: as its frame read them once it ran, which sees a setting
+ * written by code the index leaves out; the index's controls and no `argTypes` or actions before.
+ *
+ * @param panels - what each story's frame reported, by story.
+ * @param story - the story.
+ */
+export declare const reportedPanel: (panels: ReadonlyMap<string, ReportedPanel>, story: TreeStory) => ReportedPanel;

package/dist/src/shell/reportedPanel.js

@@ -0,0 +1,19 @@
+import { NOT_FIXED } from "../storyGlobals.js";
+/** The `argTypes` of a story before its frame reported them. */
+const NO_ARG_TYPES = {};
+/** No actions, as one value: the panel's docs made from the args are kept while it stays the same. */
+const NO_ACTIONS = [];
+/**
+ * A story's `argTypes`, controls, actions and fixed view for the panel and the stage: as its frame read them once it ran, which sees a setting
+ * written by code the index leaves out; the index's controls and no `argTypes` or actions before.
+ *
+ * @param panels - what each story's frame reported, by story.
+ * @param story - the story.
+ */
+export const reportedPanel = (panels, story) => panels.get(story.id) ?? {
+    argTypes: NO_ARG_TYPES,
+    controls: story.controls,
+    actions: NO_ACTIONS,
+    fixed: NOT_FIXED,
+    parameters: []
+};

package/dist/src/shell/shell.css

@@ -453,6 +453,7 @@
   }
   .forgebook-story {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.625rem;
     margin: 1rem 2rem 2rem;
     min-width: 0;
@@ -464,6 +465,7 @@
   }
   .forgebook-story__bar {
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
     gap: 0.5rem;
   }
@@ -598,6 +600,11 @@
     grid-template-columns: repeat(auto-fill, minmax(min(100%, 17rem), 1fr));
     gap: 0.75rem 1.25rem;
   }
+  .forgebook-tab-head {
+    display: flex;
+    justify-content: flex-end;
+    padding: 0.625rem 0.875rem 0;
+  }
   .forgebook-tab-note {
     margin: 0;
     padding: 0.75rem 0.875rem 0;
@@ -1549,8 +1556,9 @@
     font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
   }
   .forgebook-stage__heading {
-    flex: 1;
+    flex: 1 1 10rem;
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.125rem;
     min-width: 0;
   }
@@ -1559,6 +1567,7 @@
     font: 500 0.8125rem/1.35 var(--forgebook-font-sans);
     font-weight: 600;
     color: var(--forgebook-text);
+    overflow-wrap: break-word;
   }
   .forgebook-stage__description {
     display: -webkit-box;
@@ -1622,6 +1631,7 @@
   }
   .forgebook-viewport {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.375rem;
   }
   .forgebook-viewport__canvas {
@@ -1726,15 +1736,18 @@
   .forgebook-home {
     box-sizing: border-box;
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 1.5rem;
     width: 100%;
     max-width: 56rem;
     margin: 0 auto;
     padding: 1.5rem 2rem 2rem;
+    overflow-wrap: break-word;
     animation: forgebook-rise 260ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
   }
   .forgebook-home__head {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.5rem;
   }
   .forgebook-home__title {
@@ -1766,6 +1779,7 @@
   }
   .forgebook-home__recent-link {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.125rem;
     padding: 0.5rem 0.75rem;
     border-radius: var(--forgebook-radius-control);
@@ -1805,6 +1819,7 @@
   }
   .forgebook-home__card {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     align-content: start;
     justify-items: start;
     gap: 0.5rem;
@@ -1821,6 +1836,7 @@
     width: 100%;
     margin: 0;
     font: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    overflow-wrap: anywhere;
   }
   .forgebook-home__count {
     font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
@@ -1829,6 +1845,7 @@
   }
   .forgebook-home__components {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.25rem;
     margin: 0;
     padding: 0;
@@ -1903,6 +1920,7 @@
   }
   .forgebook-doc__section {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 1rem;
   }
   .forgebook-doc__section > h2 {
@@ -1916,6 +1934,7 @@
   }
   .forgebook-doc__group {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 1.5rem;
   }
   .forgebook-doc__group-name {
@@ -1938,10 +1957,12 @@
   }
   .forgebook-example {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.625rem;
   }
   .forgebook-example__head {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.25rem;
   }
   .forgebook-example__title {
@@ -2152,6 +2173,7 @@
   .forgebook-prose {
     font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
     line-height: 1.6;
+    overflow-wrap: break-word;
   }
   .forgebook-prose > :first-child {
     margin-top: 0;
@@ -2218,6 +2240,7 @@
     text-align: start;
     vertical-align: top;
     box-shadow: inset 0 -1px 0 var(--forgebook-separator);
+    overflow-wrap: anywhere;
   }
   .forgebook-prose th {
     font-weight: 600;
@@ -2261,11 +2284,43 @@
     font-weight: 600;
     color: var(--forgebook-code-name);
   }
+  .forgebook-api__head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem 1rem;
+    margin-top: 1rem;
+  }
+  .forgebook-api__head > h2 {
+    margin: 0;
+    font: 700 1.375rem/1.2 var(--forgebook-font-sans);
+  }
+  .forgebook-required-first {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font-weight: 500;
+    color: var(--forgebook-text-secondary);
+    cursor: pointer;
+  }
+  .forgebook-prop__group {
+    margin-inline: 0.375rem auto;
+    padding: 0 0.375rem;
+    border-radius: 999px;
+    background: var(--forgebook-fill);
+    font: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    font-weight: 400;
+    color: var(--forgebook-text-secondary);
+    white-space: nowrap;
+  }
   .forgebook-api__type {
     min-width: 10rem;
   }
   .forgebook-api__subcomponent {
     display: grid;
+    grid-template-columns: minmax(0, 1fr);
     gap: 0.75rem;
     margin-top: 1rem;
   }

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

@@ -160,6 +160,8 @@ declare const shellStrings: {
     rangeValue: (prop: string) => string;
     setByStory: string;
     required: string;
+    requiredFirst: string;
+    requiredFirstHint: string;
     resetArgs: string;
     appearance: string;
     appearanceOf: (name: string) => string;

package/dist/src/shell/strings.js

@@ -127,6 +127,8 @@ const shellStrings = {
     rangeValue: (prop) => `${prop}: value`,
     setByStory: "Set by the story",
     required: "Required",
+    requiredFirst: "Required first",
+    requiredFirstHint: "Every component's required props before the others; kept in this browser",
     resetArgs: "Reset",
     appearance: "Appearance",
     appearanceOf: (name) => `Appearance: ${name}`,