forgebook 0.3.3 → 0.4.1

package/dist/src/argTypes.js

@@ -1,17 +1,18 @@
 /**
- * A story's `argTypes` (Storybook's): read in the frame from the meta and the story, sent to the shell in a form that
- * crosses between the documents, laid over the props the component's types give, and their `mapping` applied to the
- * args the story receives.
+ * A story's `argTypes` (Storybook's) as the shell reads them: in the form that crosses between the documents, laid over the
+ * props the component's types give. What reads them from the story's module is `storyArgTypes.ts`.
  *
  * @remarks
  * The panel's props come from the component's types (`componentDocs.ts`); `argTypes` say otherwise where a story
  * means another control, other options, other names, or an arg the types do not name. Without `argTypes` the panel
  * shows the props exactly as the types give them. Option values that cannot cross (a component, a function) are
- * sent as their `mapping` keys, which the frame turns back into the values. `object` and `file` controls have no
- * control in the panel: their args are listed for reading. Pure.
+ * sent as their `mapping` keys, which the frame turns back into the values. An `object` control edits the prop by the
+ * shape its type gives (`valueShape.ts`), by what the story's own arg looks like without one, as JSON when nothing says.
+ * Pure.
  *
  * @module
  */
+import { isArgCondition } from "./argConditions.js";
 /**
  * Whether a prop is a colour: named so by its `argTypes`, or by the name convention (`color`, `accentColor`).
  *
@@ -30,145 +31,23 @@ export const isColorProp = (prop) => prop.control === "color" ||
 export const isNamedProp = (prop, namedValues) => prop.kind === "other" && prop.control === undefined && namedValues[prop.type] !== undefined;
 /**
  * The props the panel can set: a prop of a type the source names values for is chosen among them, a node that takes a
- * text is set as one; any other `other` prop, and an event, cannot be set; nor a prop the story's controls leave out.
+ * text is set as one, a prop with a shape by its fields; any other `other` prop, and an event, cannot be set; nor a prop
+ * the story's controls leave out.
  *
  * @param props - the component's props, with the story's `argTypes` laid over them.
  * @param controls - the props the story lets the panel set.
  * @param namedValues - the source's named values.
  */
-export const settableProps = (props, controls, namedValues) => props.filter((prop) => (prop.kind !== "other" || prop.canTakeText === true || isNamedProp(prop, namedValues)) &&
+export const settableProps = (props, controls, namedValues) => props.filter((prop) => (prop.kind !== "other" ||
+    prop.canTakeText === true ||
+    prop.control === "file" ||
+    prop.customControl !== undefined ||
+    isNamedProp(prop, namedValues) ||
+    prop.shape !== undefined) &&
     prop.kind !== "event" &&
     (controls === "all" || controls.includes(prop.name)));
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** Storybook's control names, as the panel draws them (the inline variants look the same here). */
-const CONTROLS = {
-    select: "select",
-    radio: "radio",
-    "inline-radio": "radio",
-    check: "check",
-    "inline-check": "check",
-    "multi-select": "multi-select",
-    boolean: "boolean",
-    text: "text",
-    number: "number",
-    range: "range",
-    color: "color",
-    date: "date",
-    object: "none",
-    file: "none"
-};
-/** The panel controls, for the check on arrival. */
-const PANEL_CONTROLS = [...new Set(Object.values(CONTROLS))];
-/** A number field of an object, when it is a finite number. */
-const numberOf = (part, name) => {
-    const value = part[name];
-    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-};
-/** The labels of a control, when every one is a text. */
-const labelsOf = (value) => isRecord(value) && Object.values(value).every((label) => typeof label === "string")
-    ? Object.fromEntries(Object.entries(value).map(([option, label]) => [option, String(label)]))
-    : undefined;
-/**
- * The control an entry names: `false` and a disabled control are none, a name or `{ type }` is that control, and
- * options without a control make a select.
- */
-const controlOf = (entry) => {
-    const control = entry["control"];
-    if (control === false)
-        return "none";
-    if (typeof control === "string")
-        return CONTROLS[control];
-    if (isRecord(control)) {
-        if (control["disable"] === true)
-            return "none";
-        if (typeof control["type"] === "string")
-            return CONTROLS[control["type"]];
-    }
-    return Array.isArray(entry["options"]) ? "select" : undefined;
-};
-/**
- * The options as they cross: texts and numbers as they are; any other value only through `mapping`, whose keys are
- * the options then.
- */
-const optionsOf = (entry) => {
-    const options = entry["options"];
-    if (!Array.isArray(options))
-        return undefined;
-    return options.filter((option) => typeof option === "string" || typeof option === "number");
-};
-/**
- * One entry as the panel reads it.
- *
- * @param entry - the `argTypes` entry, the story's laid over the meta's.
- * @param isExcluded - whether `parameters.controls.exclude` names the arg.
- */
-const panelArgTypeOf = (entry, isExcluded) => {
-    const control = controlOf(entry);
-    const options = optionsOf(entry);
-    const settings = isRecord(entry["control"]) ? entry["control"] : {};
-    const table = entry["table"];
-    const name = entry["name"];
-    const description = entry["description"];
-    const labels = labelsOf(settings["labels"]);
-    const min = numberOf(settings, "min");
-    const max = numberOf(settings, "max");
-    const step = numberOf(settings, "step");
-    return {
-        isHidden: isExcluded || (isRecord(table) && table["disable"] === true),
-        ...(typeof name === "string" ? { label: name } : {}),
-        ...(typeof description === "string" ? { description } : {}),
-        ...(control === undefined ? {} : { control }),
-        ...(options === undefined ? {} : { options }),
-        ...(labels === undefined ? {} : { labels }),
-        ...(min === undefined ? {} : { min }),
-        ...(max === undefined ? {} : { max }),
-        ...(step === undefined ? {} : { step })
-    };
-};
-/**
- * The `argTypes` of the meta and the story, merged: each arg's entry from both, the story's fields over the meta's.
- *
- * @param meta - the meta's `argTypes`.
- * @param story - the story's `argTypes`.
- */
-export const mergedArgTypes = (meta, story) => {
-    const merged = {};
-    for (const part of [meta, story]) {
-        if (!isRecord(part))
-            continue;
-        for (const [name, entry] of Object.entries(part)) {
-            if (isRecord(entry))
-                merged[name] = { ...merged[name], ...entry };
-        }
-    }
-    return merged;
-};
-/**
- * The arg types the frame sends: each entry read, and the args `parameters.controls.exclude` names hidden.
- *
- * @param argTypes - the merged `argTypes`.
- * @param excluded - the args `parameters.controls.exclude` names.
- */
-export const panelArgTypesOf = (argTypes, excluded) => {
-    const names = [...new Set([...Object.keys(argTypes), ...excluded])];
-    return Object.fromEntries(names.map((name) => [name, panelArgTypeOf(argTypes[name] ?? {}, excluded.includes(name))]));
-};
-/**
- * The args with each `mapping` applied: an arg whose value is a key of its entry's `mapping` receives the value the
- * key stands for, as Storybook's (an arg written as the key in the story, or chosen in the panel).
- *
- * @param args - the args.
- * @param argTypes - the merged `argTypes`.
- */
-export const mappedArgs = (args, argTypes) => Object.fromEntries(Object.entries(args).map(([name, value]) => {
-    const mapping = argTypes[name]?.["mapping"];
-    if (!isRecord(mapping) || (typeof value !== "string" && typeof value !== "number"))
-        return [name, value];
-    const key = String(value);
-    // the mapping's own keys only: a value a shared link chose (`constructor`) never reaches its prototype
-    return [name, Object.hasOwn(mapping, key) ? mapping[key] : value];
-}));
 /** The prop kind a control sets, for the panel's groups. */
 const KIND_OF_CONTROL = {
     select: "choice",
@@ -181,21 +60,50 @@ const KIND_OF_CONTROL = {
     range: "number",
     color: "text",
     date: "number",
+    object: "other",
+    textarea: "text",
+    token: "text",
+    file: "other",
     none: "other"
 };
+/**
+ * What a prop's editor reads of its arg type: an `object` control's shape, from its type, else from the story's own value,
+ * else JSON; a `token` control's tokens; what a `file` control takes.
+ */
+const editorFieldsOf = (prop, argType, own) => {
+    const shapeOfOwn = own === undefined || own === null ? { kind: "json" } : { kind: "like", value: own };
+    return {
+        ...(argType.control === "object" ? { shape: prop.shape ?? shapeOfOwn } : {}),
+        // a `token` control that names no tokens asks for those named after its arg
+        ...(argType.control === "token" ? { tokens: argType.tokens ?? { of: prop.name } } : {}),
+        ...(argType.accept === undefined ? {} : { accept: argType.accept }),
+        ...(argType.customControl === undefined
+            ? {}
+            : {
+                kind: "other",
+                customControl: argType.customControl,
+                ...(argType.settings === undefined ? {} : { settings: argType.settings })
+            })
+    };
+};
 /**
  * A prop with its arg type laid over it.
  *
  * @param prop - the prop as the types give it.
  * @param argType - its arg type.
+ * @param own - the story's own value of the arg: what an `object` control with no type to read draws its fields from.
  */
-const withArgType = (prop, argType) => {
+const withArgType = (prop, argType, own) => {
     const { control } = argType;
     // a control the panel cannot draw makes the prop one it lists for reading, never one that takes a text
     const isReadOnly = control === "none";
-    const { canTakeText: _canTakeText, ...rest } = prop;
+    // a control the story names wins over the one the catalogue gives the prop's type
+    const { customControl: _typed, ...untyped } = prop;
+    const { canTakeText: _canTakeText, ...rest } = untyped;
+    // a control the story names decides what its value is: the type's shape no longer draws nor checks it
+    const { shape: _shape, ...shapeless } = isReadOnly || argType.customControl !== undefined ? rest : untyped;
     return {
-        ...(isReadOnly ? rest : prop),
+        ...(control === undefined && argType.customControl === undefined ? prop : shapeless),
         ...(control === undefined ? {} : { kind: KIND_OF_CONTROL[control], control }),
         ...(argType.options === undefined ? {} : { choices: argType.options }),
         ...(argType.description === undefined ? {} : { description: argType.description }),
@@ -203,58 +111,49 @@ const withArgType = (prop, argType) => {
         ...(argType.labels === undefined ? {} : { labels: argType.labels }),
         ...(argType.min === undefined ? {} : { min: argType.min }),
         ...(argType.max === undefined ? {} : { max: argType.max }),
-        ...(argType.step === undefined ? {} : { step: argType.step })
+        ...(argType.step === undefined ? {} : { step: argType.step }),
+        ...editorFieldsOf(prop, argType, own)
     };
 };
 /** A prop the types do not name, made from its arg type alone: a text when it names no control. */
-const propOfArgType = (name, argType) => withArgType({ name, kind: "text", type: "", description: "", isRequired: false }, argType);
+const propOfArgType = (name, argType, own) => withArgType({ name, kind: "text", type: "", description: "", isRequired: false }, argType, own);
+/** A prop as its TSDoc asks: chosen among the tokens `@token` names, when it is set as a text. */
+const propAsDocumented = (prop) => prop.token !== undefined && (prop.kind === "text" || prop.canTakeText === true)
+    ? { ...prop, kind: "text", control: "token", tokens: { of: prop.token } }
+    : prop;
 /**
  * The panel's props: the component's, with their arg types laid over them, the hidden ones left out, then the args
  * only the arg types name, in their order.
  *
  * @param props - the props the component's types give.
  * @param argTypes - the story's arg types; none leaves the props as they are.
+ * @param storyArgs - the story's own args, for an `object` control no type describes; none by default.
  */
-export const panelProps = (props, argTypes) => {
+export const panelProps = (props, argTypes, storyArgs = {}) => {
     const typed = new Set(props.map((prop) => prop.name));
     const fromTypes = props.flatMap((prop) => {
         const argType = argTypes[prop.name];
         if (argType === undefined)
-            return [prop];
-        return argType.isHidden ? [] : [withArgType(prop, argType)];
+            return [propAsDocumented(prop)];
+        if (argType.isHidden)
+            return [];
+        return [
+            withArgType(argType.control === undefined ? propAsDocumented(prop) : prop, argType, storyArgs[prop.name])
+        ];
     });
-    const fromArgTypes = Object.entries(argTypes).flatMap(([name, argType]) => typed.has(name) || argType.isHidden ? [] : [propOfArgType(name, argType)]);
+    const fromArgTypes = Object.entries(argTypes).flatMap(([name, argType]) => typed.has(name) || argType.isHidden ? [] : [propOfArgType(name, argType, storyArgs[name])]);
     return [...fromTypes, ...fromArgTypes];
 };
-/**
- * The props the panel can set, as the story's parameters say: `false` none, a list or `{ include }` those, anything
- * else every one.
- *
- * @param value - `parameters.controls`.
- */
-export const controlsOfParameter = (value) => {
-    if (value === false)
-        return [];
-    if (Array.isArray(value) && value.every((name) => typeof name === "string"))
-        return value;
-    const include = isRecord(value) ? value["include"] : undefined;
-    if (Array.isArray(include) && include.every((name) => typeof name === "string"))
-        return include;
-    return "all";
-};
-/**
- * The args `parameters.controls.exclude` hides.
- *
- * @param value - `parameters.controls`.
- */
-export const excludedControls = (value) => {
-    const exclude = isRecord(value) ? value["exclude"] : undefined;
-    return Array.isArray(exclude) ? exclude.filter((name) => typeof name === "string") : [];
-};
 /** Whether a value is one arg's panel arg type. */
 const isPanelArgType = (value) => isRecord(value) &&
     typeof value["isHidden"] === "boolean" &&
-    (value["control"] === undefined || PANEL_CONTROLS.some((control) => control === value["control"])) &&
+    (value["if"] === undefined || isArgCondition(value["if"])) &&
+    (value["control"] === undefined ||
+        (typeof value["control"] === "string" && Object.hasOwn(KIND_OF_CONTROL, value["control"]))) &&
+    (value["tokens"] === undefined ||
+        (isRecord(value["tokens"]) && typeof value["tokens"]["of"] === "string")) &&
+    (value["accept"] === undefined || typeof value["accept"] === "string") &&
+    (value["customControl"] === undefined || typeof value["customControl"] === "string") &&
     (value["options"] === undefined ||
         (Array.isArray(value["options"]) &&
             value["options"].every((option) => typeof option === "string" || typeof option === "number")));
@@ -264,18 +163,3 @@ const isPanelArgType = (value) => isRecord(value) &&
  * @param value - the message's field.
  */
 export const isPanelArgTypes = (value) => isRecord(value) && Object.values(value).every(isPanelArgType);
-/** Whether a value is a spy (`fn()` of `storybook/test` or Vitest): a function with its calls under `mock`. */
-const isSpy = (value) => typeof value === "function" && "mock" in value;
-/**
- * The args whose calls the Events tab records as actions: those whose value is a spy, and those whose `argTypes`
- * entry names an `action`. Explicit only: no arg is recorded for its name alone.
- *
- * @param args - the story's args.
- * @param argTypes - the merged `argTypes`.
- */
-export const actionNames = (args, argTypes) => [
-    ...new Set([
-        ...Object.entries(args).flatMap(([name, value]) => (isSpy(value) ? [name] : [])),
-        ...Object.entries(argTypes).flatMap(([name, entry]) => typeof entry["action"] === "string" || entry["action"] === true ? [name] : [])
-    ])
-];

package/dist/src/argsProps.d.ts

@@ -4,8 +4,8 @@
  *
  * @remarks
  * An arg's kind is read from its value: a text, a number, a toggle, an event for an arg the frame records as an
- * action. A list or a value the source names (`namedValues`) is listed for reading, unless its type is one the source
- * names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
+ * action, fields for an object or a list. A value the source names (`namedValues`) is listed for
+ * reading, unless its type is one the source names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
  * The story's `argTypes` are laid over these as over the types' props (`argTypes.ts`). A shared link's values are
  * checked against these kinds (`addressArgs.ts`): without the types, a text arg takes any text, so a prop of a few
  * values keeps a link to them only through its `argTypes` options. Pure.
@@ -13,7 +13,7 @@
  * @module
  */
 import type { ComponentDocs, PropDocs } from "./componentDocs.ts";
-import type { PanelArgs } from "./messages.ts";
+import { type PanelArgs } from "./messages.ts";
 /**
  * The props a story's args stand for, in the args' order, then its actions the args do not hold.
  *

package/dist/src/argsProps.js

@@ -4,14 +4,15 @@
  *
  * @remarks
  * An arg's kind is read from its value: a text, a number, a toggle, an event for an arg the frame records as an
- * action. A list or a value the source names (`namedValues`) is listed for reading, unless its type is one the source
- * names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
+ * action, fields for an object or a list. A value the source names (`namedValues`) is listed for
+ * reading, unless its type is one the source names values for. Nothing is said of a prop the story gives no arg: without the types there is no way to know it.
  * The story's `argTypes` are laid over these as over the types' props (`argTypes.ts`). A shared link's values are
  * checked against these kinds (`addressArgs.ts`): without the types, a text arg takes any text, so a prop of a few
  * values keeps a link to them only through its `argTypes` options. Pure.
  *
  * @module
  */
+import { isArgList, isNamedArg } from "./messages.js";
 /**
  * The prop an arg stands for, its kind and type read from its value.
  *
@@ -31,10 +32,15 @@ const propOfArg = (name, value, isAction) => {
         return { ...prop, kind: "toggle", type: "boolean" };
     if (value === null)
         return { ...prop, kind: "other", type: "null" };
-    if (Array.isArray(value))
-        return { ...prop, kind: "other", type: "array" };
     // a value the source names: its type, so the panel offers the source's values for it
-    return { ...prop, kind: "other", type: "of" in value ? value.of : "unknown" };
+    if (isNamedArg(value))
+        return { ...prop, kind: "other", type: value.of };
+    return {
+        ...prop,
+        kind: "other",
+        type: isArgList(value) ? "array" : "object",
+        shape: { kind: "like", value }
+    };
 };
 /**
  * The props a story's args stand for, in the args' order, then its actions the args do not hold.

package/dist/src/bundlerErrors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a bundler's error says, as Forgebook reports it: its file, line and column when they are known, and its reason,
+ * without the plugin that raised it, the stack and the code frame a terminal or an overlay has room for.
+ *
+ * @remarks
+ * Shared by `forgebook build`, on what the build throws, and by a frame, on what the dev server says of a module it
+ * could not serve. Both hold the same text: Vite's transform and the build run the same parser.
+ *
+ * @module
+ */
+/** Where in a file a bundler places an error, when it does; its column counts from 0. */
+export type BundlerErrorPlace = {
+    /** The file, absolute. */
+    readonly id?: string | undefined;
+    /** Its line and column. */
+    readonly loc?: {
+        readonly file?: string | undefined;
+        readonly line: number;
+        readonly column: number;
+    } | undefined;
+};
+/**
+ * A bundler's error as lines: its place and reason first.
+ *
+ * @param message - its message, without colours.
+ * @param place - what the error says of its place.
+ * @returns the lines; none when the message says nothing.
+ */
+export declare const bundlerErrorLines: (message: string, place?: BundlerErrorPlace) => readonly string[];

package/dist/src/bundlerErrors.js

@@ -0,0 +1,49 @@
+/**
+ * What a bundler's error says, as Forgebook reports it: its file, line and column when they are known, and its reason,
+ * without the plugin that raised it, the stack and the code frame a terminal or an overlay has room for.
+ *
+ * @remarks
+ * Shared by `forgebook build`, on what the build throws, and by a frame, on what the dev server says of a module it
+ * could not serve. Both hold the same text: Vite's transform and the build run the same parser.
+ *
+ * @module
+ */
+/** The place at the head of a code frame (`╭─[ src/Broken.tsx:1:48 ]`), which a parse error alone names its file in. */
+const FRAME_PLACE = /╭─\[\s*(.+?)\s*\]/;
+/** A line that says nothing of the reason: a count of errors, a stack's, a code frame's. */
+const NOISE = /^(?:(?:Transform|Build) failed with \d+ errors?:?$|at .*:\d+:\d+\)?$|[╭│╰─┬]|\d+\s*[│|])/;
+/** The plugin or tool that raised an error, before its reason (`[PARSE_ERROR]`, `[plugin forgebook]`). */
+const RAISED_BY = /^\[[^\]]+\]\s*/;
+/**
+ * An error's place, as an editor counts: `file:line:column`, or the file alone.
+ *
+ * @param place - what the error says of it.
+ * @param message - its message, without colours.
+ */
+const placeOf = ({ id, loc }, message) => {
+    const framed = FRAME_PLACE.exec(message)?.[1];
+    if (framed !== undefined)
+        return framed;
+    const file = loc?.file ?? id;
+    if (file === undefined || loc === undefined)
+        return file;
+    return `${file}:${loc.line}:${loc.column + 1}`;
+};
+/**
+ * A bundler's error as lines: its place and reason first.
+ *
+ * @param message - its message, without colours.
+ * @param place - what the error says of its place.
+ * @returns the lines; none when the message says nothing.
+ */
+export const bundlerErrorLines = (message, place = {}) => {
+    const lines = message
+        .split("\n")
+        .map((line) => line.replace(RAISED_BY, "").trim())
+        .filter((line) => line !== "" && !NOISE.test(line));
+    const where = placeOf(place, message);
+    const [first, ...rest] = lines;
+    if (first === undefined || where === undefined || first.startsWith(where))
+        return lines;
+    return [`${where}: ${first}`, ...rest];
+};

package/dist/src/catalogue.d.ts

@@ -17,6 +17,7 @@ import { type Backdrop, type CustomBackdrop } from "./backdrops.ts";
 import { type ControlKeys } from "./controlKeys.ts";
 import { type DeviceDefault } from "./deviceView.ts";
 import type { CatalogueView } from "./namedViews.ts";
+import type { StatusSettings } from "./storyStatuses.ts";
 import { type TouchChoice, type ViewSwitch } from "./switches.ts";
 /** A preset width of the toolbar. */
 export type StageWidthPreset = {
@@ -58,8 +59,22 @@ export type A11ySettings = {
     /** Rules turned off by id (`color-contrast`). */
     readonly disabledRules: readonly string[];
 };
+/** Whether a story's play function runs when its frame opens. */
+export type PlaySwitch = "on" | "off";
+/**
+ * Why a configuration's `play` cannot be used, or none: it is written by JavaScript too, which no type stops.
+ *
+ * @param play - the value written.
+ */
+export declare const playProblem: (play: unknown) => string | undefined;
 /** The lists a configuration may set, every one optional. */
 export type CatalogueLists = {
+    /**
+     * Whether a story's play function runs when a reader opens it. `on` on a dev server and `off` in a build by default: an
+     * author is checking the play, a reader of published docs did not ask for it. A reader's own choice comes first, and
+     * tests and `check` run every play whatever this says.
+     */
+    readonly play?: PlaySwitch;
     /** The catalogue's id, the prefix of what the browser stores for it; from its title by default. */
     readonly id?: string;
     /** The toolbar's preset widths. */
@@ -160,6 +175,13 @@ export type CatalogueLists = {
      * switch turns the ordering on or off over both.
      */
     readonly requiredFirst?: RequiredFirst;
+    /**
+     * The tags that are statuses, shown as a badge on the component's or the story's page and in the sidebar, by tag:
+     * `{ review: { label: "In review", tone: "caution" } }`. `review`, `experimental` and `deprecated` are declared by
+     * default; a catalogue's entry restyles or renames one, `false` turns one off. A meta's tags give the component's
+     * status, a story's the story's; the tag filter filters by them.
+     */
+    readonly statuses?: StatusSettings;
 };
 /** The shell's own appearance: light, dark, the system's, or the colour scheme of the story shown. */
 export type Appearance = "light" | "dark" | "system" | "story";
@@ -201,6 +223,10 @@ export type CatalogueSettings = {
     readonly gridStep: number;
     /** The shell's texts replaced, by name. */
     readonly strings: Readonly<Record<string, string>>;
+    /** Whether a story's play function runs when a reader opens it, as the catalogue says: an address names what differs. */
+    readonly play: PlaySwitch;
+    /** What a page shows unless its address names one: the reader's choice, else the catalogue's. */
+    readonly readerPlay: PlaySwitch;
     /** Forgebook's own controls shown, in their order. */
     readonly ownControls: readonly OwnControlId[];
     /** The controls that start on the toolbar, in their order, by id. */
@@ -226,6 +252,11 @@ export type CatalogueSettings = {
     readonly propGroups: readonly string[];
     /** Where the required props are listed when a component or a story does not say; `"in-groups"` by default. */
     readonly requiredFirst: RequiredFirst;
+    /**
+     * The statuses as the configuration declares them; the defaults are filled in where the badges are drawn
+     * (`storyStatuses.ts`), which load only for a catalogue whose stories have tags. None when it declares none.
+     */
+    readonly statuses: StatusSettings | undefined;
 };
 /** WCAG 2.2 at levels A and AA: the rules every story passes by default. */
 export declare const DEFAULT_A11Y_TAGS: readonly string[];

package/dist/src/catalogue.js

@@ -27,6 +27,14 @@ export const PANEL_TAB_IDS = ["props", "events", "play", "parts", "code", "a11y"
  * keeps its id.
  */
 export const OWN_CONTROL_IDS = [DEVICE_PARAMETER, "backdrop", "sheets", "text", "width", "audience"];
+/**
+ * Why a configuration's `play` cannot be used, or none: it is written by JavaScript too, which no type stops.
+ *
+ * @param play - the value written.
+ */
+export const playProblem = (play) => play === undefined || play === "on" || play === "off"
+    ? undefined
+    : `play is ${JSON.stringify(play)}: write "on" or "off"`;
 /** The appearances, in the order the reader is offered them. */
 export const APPEARANCES = ["light", "dark", "system", "story"];
 /** WCAG 2.2 at levels A and AA: the rules every story passes by default. */
@@ -79,7 +87,7 @@ const toolbarProblem = (toolbar, switches) => {
     const known = new Set([...switches.map((each) => each.id), ...OWN_CONTROL_IDS]);
     const unknown = toolbar.find((id) => !known.has(id));
     if (unknown !== undefined)
-        return `The toolbar names "${unknown}", which is no control of the catalogue`;
+        return `The toolbar names "${unknown}", which is no control of the catalogue: it has ${[...known].join(", ")}`;
     const twice = toolbar.find((id, index) => toolbar.indexOf(id) !== index);
     if (twice !== undefined)
         return `The toolbar names "${twice}" twice`;
@@ -186,6 +194,8 @@ export const catalogueSettings = (title, switches, lists = {}, pluginTabs = [])
     const toolbar = named.filter((id) => !OWN_CONTROL_IDS.some((own) => own === id && !ownControls.includes(own)));
     return {
         id: lists.id ?? idOf(title),
+        play: lists.play ?? "on",
+        readerPlay: lists.play ?? "on",
         switches,
         touch: touchChoiceOf(switches),
         widths: lists.widths ?? DEFAULT_WIDTHS,
@@ -209,7 +219,8 @@ export const catalogueSettings = (title, switches, lists = {}, pluginTabs = [])
         views: catalogueViews(switches, lists.views),
         // checked when the configuration loads (`configFile.ts`): a model that is none is left out here
         device: deviceDefaultOf(NO_DEVICE, lists.device),
-        requiredFirst: lists.requiredFirst ?? "in-groups"
+        requiredFirst: lists.requiredFirst ?? "in-groups",
+        statuses: lists.statuses
     };
 };
 /**

package/dist/src/catalogueRefs.d.ts

@@ -0,0 +1,75 @@
+/** A composed catalogue, as the configuration gives it and the shell reads it. */
+export type CatalogueRef = {
+    /** Its id, the configuration's key: in the address (`?ref=<id>&story=<id>`). */
+    readonly id: string;
+    /** Its name, as its section's heading. */
+    readonly title: string;
+    /** Its address, always ending in `/`, so its files resolve under it (`https://ds.example.com/catalogue/`). */
+    readonly url: string;
+};
+/** A story of a composed catalogue, as its index lists it. */
+export type RefStory = {
+    /** Its id in that catalogue. */
+    readonly id: string;
+    /** The name it shows. */
+    readonly name: string;
+};
+/** A component of a composed catalogue, with its listed stories. */
+export type RefComponent = {
+    /** Its id in that catalogue. */
+    readonly id: string;
+    /** Its whole title (`Inputs/Select`). */
+    readonly title: string;
+    /** Its stories listed in the sidebar (unlisted ones left out), in that catalogue's order. */
+    readonly stories: readonly RefStory[];
+};
+/** What the sidebar shows of a composed catalogue. */
+export type RefIndex = {
+    /** Its components, in its order; only those with a listed story. */
+    readonly components: readonly RefComponent[];
+};
+/**
+ * What the sidebar shows of a composed catalogue's index, read from the parsed file.
+ *
+ * @param value - the parsed `forgebook-agent.json`.
+ * @returns the index; none when the value is no index of a version this one reads.
+ */
+export declare const refIndexOf: (value: unknown) => RefIndex | undefined;
+/**
+ * The address of a composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ */
+export declare const refIndexAddress: (ref: CatalogueRef) => string;
+/**
+ * The address of a story in a composed catalogue's own page, to open it there.
+ *
+ * @param ref - the composed catalogue.
+ * @param storyId - the story's id in it.
+ */
+export declare const refStoryAddress: (ref: CatalogueRef, storyId: string) => string;
+/**
+ * The address of a story alone in a composed catalogue's embed page, with this catalogue's switches.
+ *
+ * @remarks
+ * Every switch is written, defaults included: the composed catalogue's default may be another value, and the story
+ * shows what this catalogue's toolbar says. It keeps those it declares, with values it knows, and drops the others.
+ *
+ * @param ref - the composed catalogue.
+ * @param storyId - the story's id in it.
+ * @param switches - this catalogue's switches, by id, with the values the view gives them.
+ */
+export declare const refEmbedAddress: (ref: CatalogueRef, storyId: string, switches: Readonly<Record<string, string>>) => string;
+/**
+ * What is wrong with one composed catalogue of the configuration; nothing when it can be shown.
+ *
+ * @param id - its key.
+ * @param value - what the configuration gives it.
+ */
+export declare const refProblem: (id: string, value: unknown) => string | undefined;
+/**
+ * A composed catalogue's address as the shell uses it: its folder, ending in `/`.
+ *
+ * @param url - the address the configuration gives, checked by `refProblem`.
+ */
+export declare const refFolder: (url: string) => string;