forgebook 0.3.2 → 0.4.0

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;

package/dist/src/catalogueRefs.js

@@ -0,0 +1,122 @@
+/**
+ * Another catalogue, already built and deployed, shown in this one's sidebar (`refs` in the configuration): where its
+ * index and its stories are, and how its index reads.
+ *
+ * @remarks
+ * A composed catalogue stays on its own origin. Its stories are shown through its own embed page (`?embed`), which
+ * frames them on its own frames' origin and tells the page around it nothing but a height, so this catalogue never runs
+ * its code and gives it nothing it could act on: the view's switches cross in the embed's address, read there as any
+ * address is, and the panel's values never do. Its list comes from the index `forgebook build --agent-index` writes,
+ * fetched only when its section is first opened. Pure, so the shell's lazy parts and the plugin share it.
+ *
+ * @module
+ */
+import { AGENT_INDEX_FILE } from "./agentIndexFile.js";
+import { EMBED_PARAMETER } from "./embed.js";
+/** A composed catalogue's id: lower-case words and digits, joined by dashes. */
+const REF_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A field of an object that is a list, or an empty one. */
+const listAt = (value, name) => {
+    const list = value[name];
+    return Array.isArray(list) ? list : [];
+};
+/** A story of the index, when it is one the sidebar lists. */
+const listedStory = (value) => {
+    if (!isRecord(value) || value["isUnlisted"] === true)
+        return [];
+    const { id, name } = value;
+    return typeof id === "string" && typeof name === "string" ? [{ id, name }] : [];
+};
+/** A component of the index, with its listed stories; nothing when it has none. */
+const listedComponent = (value) => {
+    if (!isRecord(value))
+        return [];
+    const { id, title } = value;
+    const stories = listAt(value, "stories").flatMap(listedStory);
+    return typeof id === "string" && typeof title === "string" && stories.length > 0
+        ? [{ id, title, stories }]
+        : [];
+};
+/**
+ * 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 const refIndexOf = (value) => {
+    if (!isRecord(value) || value["schema"] !== 1 || !isRecord(value["stories"]))
+        return undefined;
+    return { components: listAt(value["stories"], "components").flatMap(listedComponent) };
+};
+/**
+ * The address of a composed catalogue's index.
+ *
+ * @param ref - the composed catalogue.
+ */
+export const refIndexAddress = (ref) => new URL(AGENT_INDEX_FILE, ref.url).href;
+/**
+ * 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 const refStoryAddress = (ref, storyId) => {
+    const address = new URL(ref.url);
+    address.searchParams.set("story", storyId);
+    return address.href;
+};
+/**
+ * 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 const refEmbedAddress = (ref, storyId, switches) => {
+    const address = new URL(ref.url);
+    address.searchParams.set(EMBED_PARAMETER, "");
+    address.searchParams.set("story", storyId);
+    for (const [id, value] of Object.entries(switches)) {
+        // the story's own parameters stay the story's: a switch cannot take their place
+        if (id !== EMBED_PARAMETER && id !== "story")
+            address.searchParams.set(id, value);
+    }
+    return address.href;
+};
+/**
+ * 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 const refProblem = (id, value) => {
+    if (!REF_ID.test(id))
+        return `refs: "${id}" is not an id: write lower-case words and digits joined by dashes (design-system)`;
+    if (!isRecord(value))
+        return `refs.${id} must be an object with a title and a url`;
+    const { title, url } = value;
+    if (typeof title !== "string" || title.trim() === "")
+        return `refs.${id}.title is missing`;
+    if (typeof url !== "string" || !URL.canParse(url))
+        return `refs.${id}.url must be an absolute address (https://design.example.com/)`;
+    const address = new URL(url);
+    if (address.protocol !== "https:" && address.protocol !== "http:")
+        return `refs.${id}.url must be an http or https address`;
+    if (address.username !== "" || address.password !== "")
+        return `refs.${id}.url must not hold credentials: the address is written into the page`;
+    if (address.search !== "" || address.hash !== "")
+        return `refs.${id}.url must be the catalogue's folder, with no query or fragment`;
+    return 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 const refFolder = (url) => (url.endsWith("/") ? url : `${url}/`);

package/dist/src/componentDocs.d.ts

@@ -10,6 +10,7 @@
  *
  * @module
  */
+import type { ValueShape } from "./valueShape.ts";
 /** How a prop is set from the panel, and the group it is listed in. */
 export type PropKind = "choice" | "text" | "number" | "toggle" | "event" | "other";
 /** One parameter of an event's signature. */
@@ -66,6 +67,56 @@ export type MemberDocs = {
     /** Whether the member must be given. */
     readonly isRequired: boolean;
 };
+/**
+ * Why a prop's type is not the one its source writes, or says nothing: a generic's type parameter and what it is shown
+ * as, a name the checker cannot find, an `any`.
+ */
+export type PropTypeNote = {
+    /** A type parameter of the props type, replaced in the prop's type. */
+    readonly reason: "generic";
+    /** Its name (`TItem`). */
+    readonly parameter: string;
+    /** What it is shown as: its constraint, its default when it has no constraint, `unknown` when it has neither. */
+    readonly shownAs: "constraint" | "default" | "unknown";
+    /** That type, as the source writes it. */
+    readonly type: string;
+} | {
+    /** A name in the prop's type that the checker cannot find (a missing import), so the type means `any`. */
+    readonly reason: "unresolved";
+    /** The name, as written. */
+    readonly name: string;
+} | {
+    /** The prop's type is `any`: nothing can be said of its values. */
+    readonly reason: "any";
+};
+/**
+ * When a prop can be passed: the values of the discriminant that select the variants of the props that declare it
+ * (`href` only when `kind` is `"link"`).
+ */
+export type PropCondition = {
+    /** The discriminant: a prop every variant declares with a literal type. */
+    readonly prop: string;
+    /** Its values in the variants that declare the prop, in the order the variants come. */
+    readonly values: readonly (string | number | boolean)[];
+    /**
+     * Whether the prop also applies with the discriminant left out, since a variant that declares it takes it so
+     * (`mode?: "single"`). Left out when `false`.
+     */
+    readonly orOmitted?: boolean;
+};
+/** Why a component lists no props although it takes some. */
+export type PropsNote = {
+    /** Its props are typed `any` (or not typed): there is nothing to read. */
+    readonly reason: "untyped";
+} | {
+    /** Its type cannot be called or constructed with props, so it gives none to read. */
+    readonly reason: "no-signature";
+} | {
+    /** Every prop it takes is declared outside its package (an element's attributes), which the docs leave out. */
+    readonly reason: "outside-package";
+    /** How many props were left out. */
+    readonly count: number;
+};
 /** One prop of a component. */
 export type PropDocs = {
     /** The prop's name. */
@@ -103,6 +154,24 @@ export type PropDocs = {
      * in the order the source declares them: the API reference lists them under the prop, folded. Left out otherwise.
      */
     readonly members?: readonly MemberDocs[];
+    /**
+     * For a prop of kind `other`, what its value looks like when plain JSON can hold it (`readonly string[]`, `{ a; b? }`,
+     * `"sm" | number`): the panel draws fields from it and a link's value is checked against it. Left out otherwise.
+     */
+    readonly shape?: ValueShape;
+    /**
+     * The design tokens its TSDoc asks for (`@token color`): a token's type or a part of its name. Left out when it asks
+     * for none.
+     */
+    readonly token?: string;
+    /**
+     * For a prop only some variants of a union of props declare, when it can be passed: the discriminant's values that
+     * select them. Such a prop is never required. Left out for a prop every variant declares, and when the union has no
+     * discriminant.
+     */
+    readonly onlyWhen?: PropCondition;
+    /** Why its type is not the one its source writes, or says nothing, in source order. Left out when there is none. */
+    readonly notes?: readonly PropTypeNote[];
 };
 /** A part the component is used with, named in the meta's `subcomponents`: listed under it on its page. */
 export type SubcomponentDocs = {
@@ -162,6 +231,8 @@ export type ComponentDocs = {
      * markup from it. Left out when the component is written by its name.
      */
     readonly selector?: string;
+    /** Why it lists no props although it takes some; left out when its props are read, or it takes none. */
+    readonly propsNote?: PropsNote;
 };
 /**
  * The name a story's code writes the component with: its selector when its framework matches components by one, its

package/dist/src/componentDocs.js

@@ -30,6 +30,8 @@ const isMemberDocs = (value) => isRecord(value) &&
     typeof value["description"] === "string" &&
     typeof value["isRequired"] === "boolean" &&
     (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
+/** Whether a value is a note with a reason: what the reference reads first. */
+const isNote = (value) => isRecord(value) && typeof value["reason"] === "string";
 /** Whether a value is one prop's docs. */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -39,8 +41,18 @@ const isPropDocs = (value) => isRecord(value) &&
     typeof value["isRequired"] === "boolean" &&
     (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean") &&
     (value["group"] === undefined || typeof value["group"] === "string") &&
+    (value["token"] === undefined || typeof value["token"] === "string") &&
+    // the plugin's own answer: looked at closer by what reads it, which loads with the first prop that has one
+    (value["shape"] === undefined ||
+        (isRecord(value["shape"]) && typeof value["shape"]["kind"] === "string")) &&
     (value["members"] === undefined ||
-        (Array.isArray(value["members"]) && value["members"].every(isMemberDocs)));
+        (Array.isArray(value["members"]) && value["members"].every(isMemberDocs))) &&
+    // the plugin's own answers, read by the reference, which loads later and draws only the reasons it knows
+    (value["onlyWhen"] === undefined ||
+        (isRecord(value["onlyWhen"]) &&
+            typeof value["onlyWhen"]["prop"] === "string" &&
+            Array.isArray(value["onlyWhen"]["values"]))) &&
+    (value["notes"] === undefined || (Array.isArray(value["notes"]) && value["notes"].every(isNote)));
 /** Whether a value is a subcomponent's docs. */
 const isSubcomponentDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -74,4 +86,5 @@ export const isComponentDocs = (value) => isRecord(value) &&
     Array.isArray(value["subcomponents"]) &&
     value["subcomponents"].every(isSubcomponentDocs) &&
     (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"])) &&
-    (value["selector"] === undefined || typeof value["selector"] === "string");
+    (value["selector"] === undefined || typeof value["selector"] === "string") &&
+    (value["propsNote"] === undefined || isNote(value["propsNote"]));

package/dist/src/frame/callValues.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A call's arguments as the Events tab shows them: each written short for the log, and an object's or a list's content to
+ * open in it. Read in the frame, where the values are; only the text crosses. Pure.
+ *
+ * @module
+ */
+/**
+ * An event's argument written short for the call log.
+ *
+ * @param value - anything a callback received.
+ */
+export declare const previewValue: (value: unknown) => string;
+/**
+ * An argument's content for the log, when it is an object or a list: JSON, two spaces deep, a function as `ƒ`, an
+ * object met again as `[circular]`, cut past `DETAIL_LENGTH`; `null` for anything else (a text, a number, an event).
+ *
+ * @param value - anything a callback received.
+ */
+export declare const detailOf: (value: unknown) => string | null;

package/dist/src/frame/callValues.js

@@ -0,0 +1,58 @@
+/**
+ * A call's arguments as the Events tab shows them: each written short for the log, and an object's or a list's content to
+ * open in it. Read in the frame, where the values are; only the text crosses. Pure.
+ *
+ * @module
+ */
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * An event's argument written short for the call log.
+ *
+ * @param value - anything a callback received.
+ */
+export const previewValue = (value) => {
+    if (typeof value === "string")
+        return JSON.stringify(value.length > 60 ? `${value.slice(0, 60)}…` : value);
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+        return String(value);
+    if (value === null || value === undefined)
+        return String(value);
+    if (typeof value === "function")
+        return "ƒ";
+    if (typeof Event !== "undefined" && value instanceof Event)
+        return value.constructor.name;
+    if (isRecord(value) && "nativeEvent" in value)
+        return "SyntheticEvent";
+    return Array.isArray(value) ? `[…${value.length}]` : "{…}";
+};
+/** The most characters an argument's content keeps in the log. */
+const DETAIL_LENGTH = 2000;
+/**
+ * An argument's content for the log, when it is an object or a list: JSON, two spaces deep, a function as `ƒ`, an
+ * object met again as `[circular]`, cut past `DETAIL_LENGTH`; `null` for anything else (a text, a number, an event).
+ *
+ * @param value - anything a callback received.
+ */
+export const detailOf = (value) => {
+    if (typeof value !== "object" || value === null)
+        return null;
+    if (typeof Event !== "undefined" && value instanceof Event)
+        return null;
+    if ("nativeEvent" in value)
+        return null;
+    const seen = new WeakSet();
+    const text = JSON.stringify(value, (_key, inner) => {
+        if (typeof inner === "function")
+            return "ƒ";
+        if (typeof inner === "bigint")
+            return `${inner}n`;
+        if (typeof inner === "object" && inner !== null) {
+            if (seen.has(inner))
+                return "[circular]";
+            seen.add(inner);
+        }
+        return inner;
+    }, 2);
+    return text.length > DETAIL_LENGTH ? `${text.slice(0, DETAIL_LENGTH)}…` : text;
+};