forgebook 0.2.0 → 0.3.0

package/dist/src/propGroups.js

@@ -1,16 +1,3 @@
-/**
- * A component's props in their groups, as its TSDoc names them (`@group Selection`): the API reference and the Props
- * tab list them the same way.
- *
- * @remarks
- * The props that name no group come first: they are the ones an author left out of every group, most often the few
- * every use of the component sets (`value`, `onChange`). Then each group, in the order a configuration names them
- * (the component's meta, then the catalogue), the others in the order they first appear among the props. A component
- * whose props name no group is one list, as it always was. Every group starts open: a reader folds one away, never the
- * catalogue. Pure.
- *
- * @module
- */
 /**
  * The order of the groups named first: the component's own (its meta's `parameters.propGroups`), then the
  * catalogue's (`propGroups` in its configuration) not already named, each once.
@@ -57,3 +44,70 @@ export const groupedProps = (props, order) => {
  * @param props - the props.
  */
 export const hasPropGroups = (props) => props.some((prop) => prop.group !== undefined);
+/** The layouts the required props can take, as a configuration and `parameters.requiredFirst` write them. */
+export const REQUIRED_FIRST_LAYOUTS = ["in-groups", "section", false];
+/**
+ * The layout a reader sees: the narrowest the developer set (the story's or the component's, else the catalogue's),
+ * with the reader's switch over it. Turned off, the source's order; turned on where the developer chose the source's
+ * order, the catalogue's layout, else `in-groups`.
+ *
+ * @param own - the story's or the component's setting; none leaves it to the catalogue.
+ * @param catalogue - the catalogue's setting.
+ * @param isReaderOn - the reader's switch; none when the reader never turned it.
+ */
+export const requiredFirstLayout = (own, catalogue, isReaderOn) => {
+    const chosen = own ?? catalogue;
+    if (isReaderOn === undefined)
+        return chosen;
+    if (!isReaderOn)
+        return false;
+    if (chosen !== false)
+        return chosen;
+    return catalogue === false ? "in-groups" : catalogue;
+};
+/**
+ * Whether putting the required props first changes anything: a required prop and one that is not. A table without
+ * shows no "Required first" switch.
+ *
+ * @param props - the props shown.
+ */
+export const canOrderRequired = (props) => props.some((prop) => prop.isRequired) && props.some((prop) => !prop.isRequired);
+/**
+ * Props with the required ones first, the rest in their order.
+ *
+ * @param props - the props, in their order.
+ */
+export const requiredPropsFirst = (props) => [
+    ...props.filter((prop) => prop.isRequired),
+    ...props.filter((prop) => !prop.isRequired)
+];
+/**
+ * Props laid out for reading: in their groups (`groupedProps`), the events apart, the required ones where the layout
+ * puts them.
+ *
+ * @param props - the props, events among them (`kind: "event"`), in the order of the source.
+ * @param order - the groups to show first, in this order (`propGroupOrder`).
+ * @param layout - where the required props go (`requiredFirstLayout`).
+ */
+export const laidOutProps = (props, order, layout) => {
+    const isEvent = (prop) => prop.kind === "event";
+    const listed = props.filter((prop) => !isEvent(prop));
+    const groups = groupedProps(listed, order);
+    const events = props.filter(isEvent);
+    if (layout === false)
+        return { required: [], groups, events };
+    if (layout === "in-groups" || !hasPropGroups(listed)) {
+        return {
+            required: [],
+            groups: groups.map((group) => ({ name: group.name, props: requiredPropsFirst(group.props) })),
+            events: requiredPropsFirst(events)
+        };
+    }
+    return {
+        required: [...groups.flatMap((group) => group.props), ...events].filter((prop) => prop.isRequired),
+        groups: groups
+            .map((group) => ({ name: group.name, props: group.props.filter((prop) => !prop.isRequired) }))
+            .filter((group) => group.props.length > 0),
+        events: events.filter((prop) => !prop.isRequired)
+    };
+};

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

@@ -5,22 +5,27 @@
  *
  * @remarks
  * Props whose TSDoc names a group (`@group Selection`) are listed under its heading, after the props that name none
- * (`propGroups.ts`), each open, so a reader may fold one away. A prop whose type is an object the
+ * (`propGroups.ts`), each open, so a reader may fold one away. The required props come first in each group and among
+ * the events, or in one "Required" section before the groups, each naming its group, as the component, the catalogue
+ * and the reader's switch in the header say (`useRequiredFirst.ts`). A prop whose type is an object the
  * package documents (`texts?: FileFinderTexts`) unfolds in place to list that type's members; they are drawn only
  * once unfolded, so a library with large text types keeps a light page.
  *
  * @module
  */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
 import { type ReactNode } from "react";
 import type { ComponentDocs } from "../componentDocs.ts";
 /**
  * The API reference.
  *
- * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), and the
- * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's; none by default.
+ * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), the
+ * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's, none by default;
+ * and where its meta puts the required props (`parameters.requiredFirst`), none for the catalogue's.
  */
-export declare const ApiReference: ({ docs, isLogic, componentGroups }: {
+export declare const ApiReference: ({ docs, isLogic, componentGroups, requiredFirst }: {
     readonly docs: ComponentDocs;
     readonly isLogic: boolean;
     readonly componentGroups?: readonly string[];
+    readonly requiredFirst?: RequiredFirst | undefined;
 }) => ReactNode;

package/dist/src/shell/ApiReference.js

@@ -1,26 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-/**
- * The API reference on a component's page: its props and its events, drawn from its types and TSDoc, as a table
- * (prop, type, default, what it does), never written by hand, then the same for each part the meta names in
- * `subcomponents`. The table scrolls sideways on its own when the page is narrower than it.
- *
- * @remarks
- * Props whose TSDoc names a group (`@group Selection`) are listed under its heading, after the props that name none
- * (`propGroups.ts`), each open, so a reader may fold one away. A prop whose type is an object the
- * package documents (`texts?: FileFinderTexts`) unfolds in place to list that type's members; they are drawn only
- * once unfolded, so a library with large text types keeps a light page.
- *
- * @module
- */
 import { useState } from "react";
-import { groupedProps, propGroupOrder } from "../propGroups.js";
+import { canOrderRequired, laidOutProps, propGroupOrder } from "../propGroups.js";
 import { Code } from "./Code.js";
 import { CodeText } from "./CodeText.js";
 import { useCatalogue } from "./catalogueContext.js";
 import { Icon } from "./icons.js";
 import { LATER_STRINGS } from "./laterStrings.js";
+import { RequiredFirstSwitch } from "./RequiredFirstSwitch.js";
 import { SignatureReference } from "./SignatureReference.js";
 import { STRINGS } from "./strings.js";
+import { useRequiredFirst } from "./useRequiredFirst.js";
 /** A prop's or an event's type as one line of TypeScript: an event's signature as an arrow. */
 const typeText = (row) => row.signature === undefined
     ? row.type
@@ -31,66 +20,85 @@ const NAME_HEADINGS = {
     events: () => LATER_STRINGS.apiEvent,
     members: () => LATER_STRINGS.apiMember
 };
+/**
+ * Where a row of the "Required" section comes from, beside its name: "Event" for an event, which the section gathers
+ * with the props, else its group, when it names one.
+ *
+ * @param props - the row.
+ */
+const RowPlace = ({ row }) => {
+    const place = row.signature === undefined ? row.group : LATER_STRINGS.apiEvent;
+    return place === undefined ? null : _jsx("span", { className: "forgebook-prop__group", children: place });
+};
 /**
  * One row, and under it, once unfolded, the members of its object type across the whole table.
  *
- * @param props - the row, whether the table has a Default column, its number of columns, and the part it belongs to:
- * the row says its name (`data-prop`), for an address to open it.
+ * @param props - the row, whether the table has a Default column, its number of columns, the part it belongs to (the
+ * row says its name, `data-prop`, for an address to open it), and whether it names its group (in "Required").
  */
-const Row = ({ row, hasDefaults, columns, part }) => {
+const Row = ({ row, hasDefaults, columns, part, showsGroup }) => {
     const [isOpen, setOpen] = useState(false);
     const { members } = row;
-    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "data-prop": part === undefined ? row.name : `${part}.${row.name}`, children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: row.name }), row.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null] }), _jsxs("td", { className: "forgebook-api__type", children: [_jsx(Code, { text: typeText(row), names: row.signature?.parameters.map((parameter) => parameter.name) ?? [] }), members === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-api__members-toggle", "aria-expanded": isOpen, "aria-label": `${LATER_STRINGS.membersOf(row.type)}: ${LATER_STRINGS.memberCount(members.length)}`, onClick: () => setOpen(!isOpen), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), LATER_STRINGS.memberCount(members.length)] }))] }), hasDefaults ? (_jsx("td", { children: row.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: row.defaultValue })) })) : null, _jsx("td", { children: _jsx(CodeText, { text: row.description }) })] }), members !== undefined && isOpen ? (_jsx("tr", { className: "forgebook-api__members", children: _jsx("td", { colSpan: columns, children: _jsx(PropTable, { rows: members, kind: "members", label: LATER_STRINGS.membersOf(row.type), part: part === undefined ? row.name : `${part}.${row.name}` }) }) })) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("tr", { "data-prop": part === undefined ? row.name : `${part}.${row.name}`, children: [_jsxs("th", { scope: "row", children: [_jsx("code", { className: "forgebook-api__name", children: row.name }), row.isRequired ? (_jsx("span", { className: "forgebook-prop__required", title: STRINGS.required, children: "*" })) : null, showsGroup ? _jsx(RowPlace, { row: row }) : null] }), _jsxs("td", { className: "forgebook-api__type", children: [_jsx(Code, { text: typeText(row), names: row.signature?.parameters.map((parameter) => parameter.name) ?? [] }), members === undefined ? null : (_jsxs("button", { type: "button", className: "forgebook-api__members-toggle", "aria-expanded": isOpen, "aria-label": `${LATER_STRINGS.membersOf(row.type)}: ${LATER_STRINGS.memberCount(members.length)}`, onClick: () => setOpen(!isOpen), children: [_jsx(Icon, { name: "chevronRight", size: 12 }), LATER_STRINGS.memberCount(members.length)] }))] }), hasDefaults ? (_jsx("td", { children: row.defaultValue === undefined ? null : (_jsx("code", { className: "forgebook-inline-code", children: row.defaultValue })) })) : null, _jsx("td", { children: _jsx(CodeText, { text: row.description }) })] }), members !== undefined && isOpen ? (_jsx("tr", { className: "forgebook-api__members", children: _jsx("td", { colSpan: columns, children: _jsx(PropTable, { rows: members, kind: "members", label: LATER_STRINGS.membersOf(row.type), part: part === undefined ? row.name : `${part}.${row.name}` }) }) })) : null] }));
 };
 /**
  * A table of props, events or members: the Default column only when one of them has a default.
  *
- * @param props - the rows, what they are, the table's name when it needs one (a members table), and the part they
- * belong to.
+ * @param props - the rows, what they are, the table's name when it needs one (a members table), the part they
+ * belong to, and whether each names its group (the "Required" section).
  */
-const PropTable = ({ rows, kind, label, part }) => {
+const PropTable = ({ rows, kind, label, part, showsGroups = false }) => {
     const hasDefaults = kind !== "events" && rows.some((row) => row.defaultValue !== undefined);
-    return (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", "aria-label": label, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: NAME_HEADINGS[kind]() }), _jsx("th", { scope: "col", children: kind === "events" ? LATER_STRINGS.apiSignature : STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: LATER_STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: rows.map((row) => (_jsx(Row, { row: row, hasDefaults: hasDefaults, columns: hasDefaults ? 4 : 3, part: part }, row.name))) })] }) }));
+    return (_jsx("div", { className: "forgebook-api", children: _jsxs("table", { className: "forgebook-api__table", "aria-label": label, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: NAME_HEADINGS[kind]() }), _jsx("th", { scope: "col", children: kind === "events" ? LATER_STRINGS.apiSignature : STRINGS.apiType }), hasDefaults ? _jsx("th", { scope: "col", children: LATER_STRINGS.apiDefault }) : null, _jsx("th", { scope: "col", children: STRINGS.apiWhat })] }) }), _jsx("tbody", { children: rows.map((row) => (_jsx(Row, { row: row, hasDefaults: hasDefaults, columns: hasDefaults ? 4 : 3, part: part, showsGroup: showsGroups }, row.name))) })] }) }));
 };
 /**
  * A group of props: the props that name none as a table alone, a named group under its heading, open until a reader
- * folds it.
+ * folds it. The "Required" section is drawn as a group, each of its props naming its own.
  *
- * @param props - the group, the level of its heading, and the part it belongs to.
+ * @param props - the group, the level of its heading, the part it belongs to, and whether it is the "Required"
+ * section.
  */
-const GroupTable = ({ group, level, part }) => {
+const GroupTable = ({ group, level, part, isRequired = false }) => {
     if (group.name === undefined)
         return _jsx(PropTable, { rows: group.props, kind: "props", part: part });
     const Heading = level === 3 ? "h3" : "h4";
-    return (_jsxs("details", { className: "forgebook-fold forgebook-api__group", open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary", children: [_jsx(Icon, { name: "chevronRight", size: 14 }), _jsx(Heading, { className: "forgebook-fold__name", children: group.name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(group.props.length) })] }), _jsx(PropTable, { rows: group.props, kind: "props", part: part })] }));
+    return (_jsxs("details", { className: "forgebook-fold forgebook-api__group", "data-required": isRequired || undefined, open: true, children: [_jsxs("summary", { className: "forgebook-fold__summary", children: [_jsx(Icon, { name: "chevronRight", size: 14 }), _jsx(Heading, { className: "forgebook-fold__name", children: group.name }), _jsx("span", { className: "forgebook-fold__count", children: STRINGS.propCount(group.props.length) })] }), _jsx(PropTable, { rows: group.props, kind: "props", part: part, showsGroups: isRequired })] }));
 };
 /**
- * A component's or a part's props in their groups, then its events under their own heading.
+ * A component's or a part's props in their groups, then its events under their own heading, the required ones where
+ * the layout puts them.
  *
- * @param props - the props, the groups to list first, the level of the headings (under the section's, or under a
- * part's) and the part they belong to.
+ * @param props - the props, the groups to list first, the layout of the required props, the level of the headings
+ * (under the section's, or under a part's) and the part they belong to.
  */
-const PropsAndEvents = ({ props, groupOrder, level, part }) => {
+const PropsAndEvents = ({ props, groupOrder, layout, level, part }) => {
     const EventsHeading = level === 3 ? "h3" : "h4";
-    const groups = groupedProps(props.filter((prop) => prop.kind !== "event"), groupOrder);
-    const events = props.filter((prop) => prop.kind === "event");
-    return (_jsxs(_Fragment, { children: [groups.map((group) => (_jsx(GroupTable, { group: group, level: level, part: part }, group.name ?? ""))), events.length === 0 ? null : (_jsxs(_Fragment, { children: [_jsx(EventsHeading, { children: LATER_STRINGS.events }), _jsx(PropTable, { rows: events, kind: "events", part: part })] }))] }));
+    const { required, groups, events } = laidOutProps(props, groupOrder, layout);
+    return (_jsxs(_Fragment, { children: [required.length === 0 ? null : (_jsx(GroupTable, { group: { name: STRINGS.required, props: required }, level: level, part: part, isRequired: true })), groups.map((group) => (_jsx(GroupTable, { group: group, level: level, part: part }, group.name ?? ""))), events.length === 0 ? null : (_jsxs(_Fragment, { children: [_jsx(EventsHeading, { children: LATER_STRINGS.events }), _jsx(PropTable, { rows: events, kind: "events", part: part })] }))] }));
 };
 /**
  * A part's reference: its name, its summary, its props and events.
  *
- * @param props - the part's docs, and the groups to list first.
+ * @param props - the part's docs, the groups to list first, and the layout of the required props.
  */
-const SubcomponentReference = ({ docs, groupOrder }) => (_jsxs("section", { className: "forgebook-api__subcomponent", "aria-label": docs.name, "data-prop": docs.name, children: [_jsx("h3", { children: _jsx("code", { className: "forgebook-inline-code", children: docs.name }) }), docs.description === "" ? null : (_jsx("p", { children: _jsx(CodeText, { text: docs.description }) })), _jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, level: 4, part: docs.name })] }));
+const SubcomponentReference = ({ docs, groupOrder, layout }) => (_jsxs("section", { className: "forgebook-api__subcomponent", "aria-label": docs.name, "data-prop": docs.name, children: [_jsx("h3", { children: _jsx("code", { className: "forgebook-inline-code", children: docs.name }) }), docs.description === "" ? null : (_jsx("p", { children: _jsx(CodeText, { text: docs.description }) })), _jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, layout: layout, level: 4, part: docs.name })] }));
 /** No group named first. */
 const NO_GROUPS = [];
 /**
  * The API reference.
  *
- * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), and the
- * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's; none by default.
+ * @param props - the component's docs, whether it is a hook's or a function's (its stories are about logic), the
+ * prop groups its meta lists first, in order (`parameters.propGroups`), ahead of the catalogue's, none by default;
+ * and where its meta puts the required props (`parameters.requiredFirst`), none for the catalogue's.
  */
-export const ApiReference = ({ docs, isLogic, componentGroups = NO_GROUPS }) => {
+export const ApiReference = ({ docs, isLogic, componentGroups = NO_GROUPS, requiredFirst }) => {
     const groupOrder = propGroupOrder(componentGroups, useCatalogue().propGroups);
-    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsx("h2", { id: "forgebook-api", children: LATER_STRINGS.apiReference }), isLogic && docs.signature !== undefined ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, level: 3 })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent, groupOrder: groupOrder }, subcomponent.name)))] }));
+    const ordering = useRequiredFirst(requiredFirst);
+    // a hook's or a function's page documents its call, not the props of a component
+    const isSignature = isLogic && docs.signature !== undefined;
+    const shown = [
+        ...(isSignature ? [] : docs.props),
+        ...docs.subcomponents.flatMap((subcomponent) => subcomponent.props)
+    ];
+    return (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-api", children: [_jsxs("div", { className: "forgebook-api__head", children: [_jsx("h2", { id: "forgebook-api", children: LATER_STRINGS.apiReference }), canOrderRequired(shown) ? _jsx(RequiredFirstSwitch, { state: ordering }) : null] }), isSignature ? (_jsx(SignatureReference, { name: docs.name, signature: docs.signature })) : (_jsx(PropsAndEvents, { props: docs.props, groupOrder: groupOrder, layout: ordering.layout, level: 3 })), docs.subcomponents.map((subcomponent) => (_jsx(SubcomponentReference, { docs: subcomponent, groupOrder: groupOrder, layout: ordering.layout }, subcomponent.name)))] }));
 };

package/dist/src/shell/AudienceSections.js

@@ -133,7 +133,7 @@ const Section = ({ id, ...props }) => {
         case "prose":
             return _jsx(AudienceProse, { page: page, reading: AUDIENCE_PAGES[props.audience].prose });
         case "api":
-            return _jsx(PageApi, { docs: docs, isLogic: isLogic, componentGroups: component.propGroups });
+            return (_jsx(PageApi, { docs: docs, isLogic: isLogic, componentGroups: component.propGroups, requiredFirst: component.requiredFirst }));
         case "parts":
             return _jsx(PartsSection, { docs: docs });
         case "pages":

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

@@ -13,6 +13,7 @@
  *
  * @module
  */
+import type { RequiredFirst } from "@forgebook/story-format/csf";
 import { type ReactNode } from "react";
 import { type ComponentDocs } from "../componentDocs.ts";
 import { type StoryTree, type TreeComponent, type TreeStory } from "../storyTree.ts";
@@ -82,12 +83,14 @@ export declare const Lead: ({ page, docs }: {
 /**
  * The API reference; nothing without props, or a signature for what is about logic.
  *
- * @param props - the component's docs, whether it is about logic, and the prop groups its meta lists first.
+ * @param props - the component's docs, whether it is about logic, the prop groups its meta lists first, and where its
+ * meta puts the required props.
  */
-export declare const PageApi: ({ docs, isLogic, componentGroups }: {
+export declare const PageApi: ({ docs, isLogic, componentGroups, requiredFirst }: {
     readonly docs: ComponentDocs | undefined;
     readonly isLogic: boolean;
     readonly componentGroups: readonly string[];
+    readonly requiredFirst: RequiredFirst | undefined;
 }) => ReactNode;
 /**
  * A component's page.

package/dist/src/shell/ComponentPage.js

@@ -1,19 +1,4 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * A component's page, as a library documents a component: what it is, its demo (the story marked `main`) with
- * its code, the text of its documentation file, its API reference drawn from its types, then every other story as an
- * example.
- *
- * @remarks
- * The frames load a few at a time (`useFrameQueue`), in the page's order, the demo first, each as it comes near the
- * visible part of the page: a component may have twenty stories. The view's live part reaches every frame as a message, as
- * on the story page; the props panel and Replay belong to a story's own page, which each story's name links to. The
- * documentation file's HTML is the package's own, made at build time (`vite/componentPage.ts`). Who reads the page
- * reorders and filters what goes around the frames (`audienceLayout.ts`); what only one audience wants loads on first use,
- * its data alongside the sections' code rather than after it.
- *
- * @module
- */
 import { lazy, Suspense, useEffect, useMemo, useRef } from "react";
 import { groupLabel } from "../catalogue.js";
 import { codeNameOf } from "../componentDocs.js";
@@ -95,9 +80,10 @@ const AudienceSlot = ({ place, audience, children }) => audience === undefined ?
 /**
  * The API reference; nothing without props, or a signature for what is about logic.
  *
- * @param props - the component's docs, whether it is about logic, and the prop groups its meta lists first.
+ * @param props - the component's docs, whether it is about logic, the prop groups its meta lists first, and where its
+ * meta puts the required props.
  */
-export const PageApi = ({ docs, isLogic, componentGroups }) => docs === undefined || (docs.props.length === 0 && !(isLogic && docs.signature !== undefined)) ? null : (_jsx(ApiReference, { docs: docs, isLogic: isLogic, componentGroups: componentGroups }));
+export const PageApi = ({ docs, isLogic, componentGroups, requiredFirst }) => docs === undefined || (docs.props.length === 0 && !(isLogic && docs.signature !== undefined)) ? null : (_jsx(ApiReference, { docs: docs, isLogic: isLogic, componentGroups: componentGroups, requiredFirst: requiredFirst }));
 /**
  * A component's page.
  *
@@ -173,5 +159,5 @@ export const ComponentPage = ({ component, anchor, view, touchOverrides, onTouch
             usedIn,
             pageRef
         };
-    return (_jsxs("div", { className: "forgebook-workspace", children: [header, anchor === undefined ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AnchorScroll, { pageRef: pageRef, anchor: anchor, visit: scroll.visit, isReady: docs.status !== "loading" && page.status !== "loading" }) })), _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", "data-audience": view.audience === "everyone" ? undefined : view.audience, children: [_jsx(AudienceSlot, { place: "beforeDemo", audience: audienceProps, children: _jsx(Lead, { page: page, docs: componentDocs }) }), demo === undefined ? null : (_jsx(Example, { ...context, story: demo, isDemo: true, isMounted: queue.mounted.has(demo.id), observe: queue.observerOf(demo.id) })), _jsxs(AudienceSlot, { place: "afterDemo", audience: audienceProps, children: [_jsx(Prose, { page: page }), _jsx(PageApi, { docs: componentDocs, isLogic: isLogic, componentGroups: component.propGroups })] }), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: LATER_STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, isMounted: queue.mounted.has(story.id), observe: queue.observerOf(story.id) }, story.id)))] }, section.group ?? "")))] })), _jsx(AudienceSlot, { place: "afterExamples", audience: audienceProps, children: usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn }) })] }, `${component.file}|${component.title}`) })] }));
+    return (_jsxs("div", { className: "forgebook-workspace", children: [header, anchor === undefined ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AnchorScroll, { pageRef: pageRef, anchor: anchor, visit: scroll.visit, isReady: docs.status !== "loading" && page.status !== "loading" }) })), _jsx("div", { ref: pageRef, className: "forgebook-scroll", children: _jsxs("div", { className: "forgebook-doc", "data-audience": view.audience === "everyone" ? undefined : view.audience, children: [_jsx(AudienceSlot, { place: "beforeDemo", audience: audienceProps, children: _jsx(Lead, { page: page, docs: componentDocs }) }), demo === undefined ? null : (_jsx(Example, { ...context, story: demo, isDemo: true, isMounted: queue.mounted.has(demo.id), observe: queue.observerOf(demo.id) })), _jsxs(AudienceSlot, { place: "afterDemo", audience: audienceProps, children: [_jsx(Prose, { page: page }), _jsx(PageApi, { docs: componentDocs, isLogic: isLogic, componentGroups: component.propGroups, requiredFirst: component.requiredFirst })] }), examples.length === 0 ? null : (_jsxs("section", { className: "forgebook-doc__section", "aria-labelledby": "forgebook-examples", children: [_jsx("h2", { id: "forgebook-examples", children: LATER_STRINGS.examples }), groupedStories(examples, catalogue.storyGroups.map((group) => group.id)).map((section) => (_jsxs("section", { className: "forgebook-doc__group", children: [section.group === undefined ? null : (_jsx("h3", { className: "forgebook-doc__group-name", children: groupLabel(catalogue.storyGroups, section.group) })), section.stories.map((story) => (_jsx(Example, { ...context, story: story, isDemo: false, isMounted: queue.mounted.has(story.id), observe: queue.observerOf(story.id) }, story.id)))] }, section.group ?? "")))] })), _jsx(AudienceSlot, { place: "afterExamples", audience: audienceProps, children: usedIn === undefined ? null : _jsx(UsedIn, { title: component.title, ...usedIn }) })] }, `${component.file}|${component.title}`) })] }));
 };

package/dist/src/shell/DocBlocks.js

@@ -132,7 +132,7 @@ const PropsBlock = ({ id, context }) => {
         return _jsx(MissingBlock, { message: STRINGS.unknownComponent(id) });
     if (docs.status === "error")
         return _jsx(MissingBlock, { message: `${LATER_STRINGS.pageError}: ${docs.message}` });
-    return (_jsx("div", { ref: queue.observerOf(key), children: docs.status === "ready" && isComponentDocs(docs.value) ? (_jsx(ApiReference, { docs: docs.value, isLogic: isLogicComponent(location.component), componentGroups: location.component.propGroups })) : null }));
+    return (_jsx("div", { ref: queue.observerOf(key), children: docs.status === "ready" && isComponentDocs(docs.value) ? (_jsx(ApiReference, { docs: docs.value, isLogic: isLogicComponent(location.component), componentGroups: location.component.propGroups, requiredFirst: location.component.requiredFirst })) : null }));
 };
 /**
  * A plugin's block; a fence no plugin of this catalogue draws is said, as a block that names what is not there.

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

@@ -10,21 +10,20 @@
  * 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. */
@@ -48,10 +47,15 @@ export type PropsTabProps = {
      * 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, componentGroups }: PropsTabProps) => ReactNode;
+export declare const PropsTab: ({ props, values, controls, onValueChange, onReset, worstCase, namedValues, textArgs, componentGroups, requiredFirst }: PropsTabProps) => ReactNode;