forgebook 0.3.2 → 0.4.0

package/dist/src/argControl.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A custom control's contract: a module a catalogue registers by name (`argControls` in `forgebook.config`) and a story
+ * uses as `argTypes: { x: { control: "name" } }`.
+ *
+ * @remarks
+ * `mount` rather than a component, so a team writes one in whatever its stories are written in: the shell knows nothing of
+ * how it draws. The value is always JSON with a declared schema, so a link keeps working and an agent can set it with no
+ * UI. The module runs in the shell's page, with a plugin's trust.
+ *
+ * @module
+ */
+import type { JsonValue } from "./plugin.ts";
+/** The types a value may be, as JSON Schema names them. */
+export type SchemaType = "string" | "number" | "integer" | "boolean" | "null" | "object" | "array";
+/**
+ * What a custom control's value looks like: a part of JSON Schema. A keyword outside this type is refused rather than
+ * ignored: a schema that says less than it seems to would let a link through.
+ */
+export type ValueSchema = {
+    /** What it is, for a reader. */
+    readonly title?: string;
+    /** What it is for, for a reader. */
+    readonly description?: string;
+    /** What it holds at first, for a reader. */
+    readonly default?: unknown;
+    /** Its type, or the types it may be. */
+    readonly type?: SchemaType | readonly SchemaType[];
+    /** The values it may be. */
+    readonly enum?: readonly unknown[];
+    /** The one value it may be. */
+    readonly const?: unknown;
+    /** A number's lowest value. */
+    readonly minimum?: number;
+    /** A number's highest value. */
+    readonly maximum?: number;
+    /** A text's fewest characters. */
+    readonly minLength?: number;
+    /** A text's most characters. */
+    readonly maxLength?: number;
+    /** What a text matches: a regular expression with the `u` flag, without a repeat of a repeat, which could hang the page. */
+    readonly pattern?: string;
+    /** A list's items. */
+    readonly items?: ValueSchema;
+    /** A list's fewest items. */
+    readonly minItems?: number;
+    /** A list's most items. */
+    readonly maxItems?: number;
+    /** An object's fields. */
+    readonly properties?: Readonly<Record<string, ValueSchema>>;
+    /** The fields an object must give. */
+    readonly required?: readonly string[];
+    /** Any other field: `false` refuses them, a schema checks them; any by default. */
+    readonly additionalProperties?: boolean | ValueSchema;
+    /** Schemas of which it must fit at least one. */
+    readonly anyOf?: readonly ValueSchema[];
+};
+/** What a control is told of its arg, from the story's `argTypes` entry. */
+export type ControlArgType = {
+    /** The arg's name. */
+    readonly name: string;
+    /** The name the panel shows. */
+    readonly label: string;
+    /** What the arg does; empty when nothing says. */
+    readonly description: string;
+    /** The entry's `options`: texts and numbers. */
+    readonly options?: readonly (string | number)[];
+    /** The control's `min`. */
+    readonly min?: number;
+    /** The control's `max`. */
+    readonly max?: number;
+    /** The control's `step`. */
+    readonly step?: number;
+    /** The control's `settings`: anything of its own, as JSON. */
+    readonly settings?: JsonValue;
+};
+/** What `mount` receives. */
+export type ArgControlProps = {
+    /** The value to show; none when the prop has none. */
+    readonly value: JsonValue | undefined;
+    /**
+     * Gives the panel a new value, checked against `schema`; none leaves the prop without one. The control keeps what it
+     * draws: it is mounted again only when the value changes from outside (Reset, a link).
+     */
+    readonly onChange: (value: JsonValue | undefined) => void;
+    /** What the story says of the arg. */
+    readonly argType: ControlArgType;
+};
+/** A custom control's module. */
+export type ArgControlModule = {
+    /**
+     * Draws the control in an element the shell keeps for it.
+     *
+     * @param element - where it draws.
+     * @param props - its value, how to change it, and what the story says of the arg.
+     * @returns what takes it away.
+     */
+    readonly mount: (element: HTMLElement, props: ArgControlProps) => () => void;
+    /** What its value looks like: a link's value and each `onChange` are checked against it. */
+    readonly schema: ValueSchema;
+};

package/dist/src/argExpression.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A list or an object among a story's args as code, for the writers of a story's code in each framework: every framework
+ * writes it as a JavaScript literal, and differs only in how a text is quoted and how a named value is written. Pure.
+ *
+ * @module
+ */
+import { type ArgValue, type NamedArg } from "./messages.ts";
+/** How a framework writes the leaves of a literal. */
+export type ExpressionWriter = {
+    /** A text as an expression in this framework's markup. */
+    readonly text: (text: string) => string;
+    /** A named value as an expression, by its name. */
+    readonly named: (named: NamedArg) => string;
+};
+/**
+ * A value as a JavaScript expression.
+ *
+ * @param value - the value.
+ * @param writer - how the framework writes its leaves.
+ */
+export declare const argExpression: (value: ArgValue, writer: ExpressionWriter) => string;

package/dist/src/argExpression.js

@@ -0,0 +1,30 @@
+/**
+ * A list or an object among a story's args as code, for the writers of a story's code in each framework: every framework
+ * writes it as a JavaScript literal, and differs only in how a text is quoted and how a named value is written. Pure.
+ *
+ * @module
+ */
+import { isArgList, isArgObject, isDateArg, isNamedArg } from "./messages.js";
+/** A field's name in an object literal: bare when JavaScript allows it. */
+const fieldName = (name, writer) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : writer.text(name);
+/**
+ * A value as a JavaScript expression.
+ *
+ * @param value - the value.
+ * @param writer - how the framework writes its leaves.
+ */
+export const argExpression = (value, writer) => {
+    if (typeof value === "string")
+        return writer.text(value);
+    if (isNamedArg(value))
+        return writer.named(value);
+    if (isDateArg(value))
+        return `new Date(${writer.text(value.forgebookDate)})`;
+    if (isArgList(value))
+        return `[${value.map((item) => argExpression(item, writer)).join(", ")}]`;
+    if (isArgObject(value)) {
+        const fields = Object.entries(value).map(([name, each]) => `${fieldName(name, writer)}: ${argExpression(each, writer)}`);
+        return fields.length === 0 ? "{}" : `{ ${fields.join(", ")} }`;
+    }
+    return String(value);
+};

package/dist/src/argTypes.d.ts

@@ -1,22 +1,34 @@
 /**
- * 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 type { StoryControlsSetting } from "@forgebook/story-format/source";
+import { type ArgCondition } from "./argConditions.ts";
 import type { PropDocs } from "./componentDocs.ts";
+import type { ArgValue } from "./messages.ts";
 import type { NamedValues } from "./namedValues.ts";
 /** A control as the panel draws it; `none` for an arg the panel lists without a control. */
-export type PanelControl = "select" | "radio" | "check" | "multi-select" | "boolean" | "text" | "number" | "range" | "color" | "date" | "none";
+export type PanelControl = "select" | "radio" | "check" | "multi-select" | "boolean" | "text" | "number" | "range" | "color" | "date" | "object" | "textarea" | "token" | "file" | "none";
+/** Which of the catalogue's design tokens a `token` control offers, and what the story receives for one. */
+export type TokenRequest = {
+    /** A token's type (`color`, `dimension`) or a part of its name (`space`, `radius`): what it offers. */
+    readonly of: string;
+    /**
+     * What the story receives, with `{name}` for the token's name in CSS's form and `{value}` for its value
+     * (`var(--{name})`); its value by default.
+     */
+    readonly format?: string;
+};
 /** How the panel shows one arg, from its `argTypes` entry: what crosses from the frame to the shell. */
 export type PanelArgType = {
     /** The name the panel shows, when it is not the arg's. */
@@ -37,6 +49,16 @@ export type PanelArgType = {
     readonly max?: number;
     /** A range's or a number's step. */
     readonly step?: number;
+    /** When the panel shows the arg (`if`); none always. */
+    readonly if?: ArgCondition;
+    /** A `token` control's tokens. */
+    readonly tokens?: TokenRequest;
+    /** The files a `file` control takes, as `<input accept>` writes it. */
+    readonly accept?: string;
+    /** The custom control it names, of those `argControls` registers: any name that is none of the panel's. */
+    readonly customControl?: string;
+    /** The custom control's `settings`. */
+    readonly settings?: ArgValue;
 };
 /** The panel's arg types, by arg. */
 export type PanelArgTypes = Readonly<Record<string, PanelArgType>>;
@@ -54,6 +76,14 @@ export type PanelProp = PropDocs & {
     readonly max?: number;
     /** A range's or a number's step. */
     readonly step?: number;
+    /** A `token` control's tokens. */
+    readonly tokens?: TokenRequest;
+    /** The files a `file` control takes. */
+    readonly accept?: string;
+    /** The custom control it names. */
+    readonly customControl?: string;
+    /** The custom control's `settings`. */
+    readonly settings?: ArgValue;
 };
 /**
  * Whether a prop is a colour: named so by its `argTypes`, or by the name convention (`color`, `accentColor`).
@@ -70,67 +100,26 @@ export declare const isColorProp: (prop: PanelProp) => boolean;
 export declare const isNamedProp: (prop: PanelProp, namedValues: NamedValues) => boolean;
 /**
  * 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 declare const settableProps: (props: readonly PanelProp[], controls: StoryControlsSetting, namedValues: NamedValues) => PanelProp[];
-/**
- * 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 declare const mergedArgTypes: (meta: unknown, story: unknown) => Readonly<Record<string, Readonly<Record<string, unknown>>>>;
-/**
- * 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 declare const panelArgTypesOf: (argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>, excluded: readonly string[]) => PanelArgTypes;
-/**
- * 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 declare const mappedArgs: (args: Readonly<Record<string, unknown>>, argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => Readonly<Record<string, unknown>>;
 /**
  * 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 declare const panelProps: (props: readonly PropDocs[], argTypes: PanelArgTypes) => readonly PanelProp[];
-/**
- * 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 declare const controlsOfParameter: (value: unknown) => StoryControlsSetting;
-/**
- * The args `parameters.controls.exclude` hides.
- *
- * @param value - `parameters.controls`.
- */
-export declare const excludedControls: (value: unknown) => readonly string[];
+export declare const panelProps: (props: readonly PropDocs[], argTypes: PanelArgTypes, storyArgs?: Readonly<Record<string, ArgValue>>) => readonly PanelProp[];
 /**
  * Whether a value received from a frame is a story's panel arg types.
  *
  * @param value - the message's field.
  */
 export declare const isPanelArgTypes: (value: unknown) => value is PanelArgTypes;
-/**
- * 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 declare const actionNames: (args: Readonly<Record<string, unknown>>, argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => readonly string[];

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,48 @@ 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 decides what its value is: the type's shape no longer draws nor checks it
+    const { shape: _shape, ...shapeless } = isReadOnly || argType.customControl !== undefined ? rest : prop;
     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 +109,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 +161,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.
  *