forgebook 0.3.3 → 0.4.0

package/dist/src/addressArgs.js

@@ -1,5 +1,5 @@
 import { panelProps, settableProps } from "./argTypes.js";
-import { isChoiceList, isNamedArg } from "./messages.js";
+import { isChoiceList, isNamedArg, isUnsetArg } from "./messages.js";
 import { namedValueOf } from "./namedValues.js";
 /** What only this module can write on values: the type system's proof that they went through the check. */
 const ACCEPTED = Symbol("accepted");
@@ -17,8 +17,10 @@ const propOfStoryArg = (name, value) => {
     // a named value keeps the type it is offered for, so only another value named for it is taken
     if (isNamedArg(value))
         return { ...prop, kind: "other", type: value.of };
-    // a list's options and a `null`'s type are not known: nothing the address names is taken for them
-    return undefined;
+    // a `null`'s type is not known: nothing the address names is taken for it
+    if (value === null)
+        return undefined;
+    return { ...prop, kind: "other", shape: { kind: "like", value } };
 };
 /**
  * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
@@ -36,12 +38,21 @@ export const declaredArgProps = (declaration) => {
         const prop = propOfStoryArg(name, value);
         return prop === undefined ? [] : [prop];
     });
-    return settableProps([...panelProps(props, argTypes), ...ownProps], controls, namedValues);
+    return settableProps([...panelProps(props, argTypes, storyArgs), ...ownProps], controls, namedValues);
 };
 /** Whether a value is a finite number: what a number field sets (an address's JSON has no `NaN` anyway). */
 const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 /** Whether a value is one of a choice's options. */
 const isOption = (prop, value) => (typeof value === "string" || typeof value === "number") && (prop.choices ?? []).includes(value);
+/**
+ * Whether a prop's values are checked by `shapeValues.ts`.
+ *
+ * @param prop - a prop the panel sets.
+ */
+export const needsShapeChecks = (prop) => prop.customControl !== undefined ||
+    prop.control === "file" ||
+    prop.control === "object" ||
+    (prop.control === undefined && prop.kind === "other" && prop.shape !== undefined);
 /**
  * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
  * kind.
@@ -49,8 +60,9 @@ const isOption = (prop, value) => (typeof value === "string" || typeof value ===
  * @param prop - a prop the panel sets.
  * @param value - the address's value.
  * @param namedValues - the source's named values.
+ * @param shapes - what checks a value against a shape; none refuses a prop that needs it.
  */
-export const isValueOfProp = (prop, value, namedValues) => {
+export const isValueOfProp = (prop, value, namedValues, shapes) => {
     switch (prop.control) {
         case "select":
         case "radio":
@@ -67,6 +79,13 @@ export const isValueOfProp = (prop, value, namedValues) => {
         case "range":
         case "date":
             return isFiniteNumber(value);
+        case "textarea":
+        case "token":
+            return typeof value === "string";
+        case "object":
+            return prop.shape !== undefined && shapes?.isValueOfShape(prop.shape, value, namedValues) === true;
+        case "file":
+            return shapes?.isFileList(value) === true;
         case "none":
             return false;
         case undefined:
@@ -82,35 +101,58 @@ export const isValueOfProp = (prop, value, namedValues) => {
         case "toggle":
             return typeof value === "boolean";
         case "other":
-            if (isNamedArg(value)) {
-                return value.of === prop.type && namedValueOf(namedValues, value.of, value.named) !== undefined;
-            }
+            if (isNamedArg(value) &&
+                value.of === prop.type &&
+                namedValueOf(namedValues, value.of, value.named) !== undefined)
+                return true;
+            if (prop.shape !== undefined && shapes?.isValueOfShape(prop.shape, value, namedValues) === true)
+                return true;
             return prop.canTakeText === true && typeof value === "string";
         case "event":
             return false;
     }
 };
+/** Whether a custom control takes a value: it loaded, and its check finds nothing wrong. */
+const fitsControl = (custom, control, value) => Object.hasOwn(custom, control) && custom[control]?.(value) === undefined;
+/** What becomes of a value for a prop the panel sets: the story takes it, it waits for its check, or why it is left out. */
+const verdictOf = (prop, value, { namedValues, checks }) => {
+    if (isUnsetArg(value))
+        return "taken";
+    if (checks === undefined && needsShapeChecks(prop))
+        return "waiting";
+    if (prop.customControl !== undefined)
+        return fitsControl(checks?.custom ?? {}, prop.customControl, value) ? "taken" : "control";
+    return isValueOfProp(prop, value, namedValues, checks) ? "taken" : "type";
+};
 /**
  * The address's values the story receives, and those left out with the reason.
  *
  * @param args - the values the address names.
  * @param declaration - what the story declares.
+ * @param typeValue - types a value for its prop, for a link whose form does not say (`storybookArgs.ts`); none takes each
+ *   as written.
+ * @param checks - what checks a structured value, a custom control's among them; none leaves such a value waiting.
  */
-export const checkedAddressArgs = (args, declaration) => {
+export const checkedAddressArgs = (args, declaration, typeValue, checks) => {
     const declared = declaredArgProps(declaration);
     const accepted = [];
     const dropped = [];
-    for (const [name, value] of Object.entries(args)) {
+    let isWaiting = false;
+    for (const [name, written] of Object.entries(args)) {
         const prop = declared.find((each) => each.name === name);
-        if (prop === undefined)
-            dropped.push({ name, reason: "undeclared" });
-        else if (!isValueOfProp(prop, value, declaration.namedValues))
-            dropped.push({ name, reason: "type" });
-        else
+        const value = prop !== undefined && typeValue !== undefined ? typeValue(prop, written) : written;
+        const verdict = prop === undefined
+            ? "undeclared"
+            : verdictOf(prop, value, { namedValues: declaration.namedValues, checks });
+        if (verdict === "taken")
             accepted.push([name, value]);
+        else if (verdict === "waiting")
+            isWaiting = true;
+        else
+            dropped.push({ name, reason: verdict });
     }
     const values = Object.fromEntries(accepted);
-    return { accepted: values, dropped, sealed: { values, [ACCEPTED]: true } };
+    return { accepted: values, dropped, isWaiting, sealed: { values, [ACCEPTED]: true } };
 };
 /**
  * The message that gives a frame its values.

package/dist/src/addressArgsParam.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `args` parameter of an address, in either form it comes in: Forgebook's own JSON (`{"label":"Hi","count":5}`), or
+ * Storybook's (`label:Hi;count:5`), which a link from before a move to Forgebook carries. Pure.
+ *
+ * @remarks
+ * The two are told apart by their first character: JSON's is `{`, and in Storybook's form a parameter starts with an
+ * arg's name, which cannot hold one. Only JSON is read here: such a link is rare, so its reader (`storybookArgs.ts`) loads
+ * when one is opened, and until then the address's values are none.
+ *
+ * A value that cannot be held is named in `unread`, never lost silently. Nor is one bad entry a reason to lose the others:
+ * each is read on its own.
+ *
+ * @module
+ */
+import type { PanelProp } from "./argTypes.ts";
+import { type ArgValue, type PanelArgs } from "./messages.ts";
+/**
+ * What an address's `args` still has to say once read, when it is not plain JSON of readable values. Kept until the
+ * person changes a value, since the address must go on saying the same: Storybook's unmarked values have no JSON form
+ * until they are typed.
+ */
+export type AddressLink = {
+    /** The parameter as the address writes it. */
+    readonly param: string;
+    /** Whether it is Storybook's form and its reader has not loaded yet: its values are still to come. */
+    readonly isWaiting: boolean;
+    /** Types one of its values for the prop that receives it, for a form that does not say; none for JSON, which does. */
+    readonly typeValue?: (prop: PanelProp, value: ArgValue) => ArgValue;
+    /** The names of the values that could not be read; `args` for a parameter that could not be read at all. */
+    readonly unread: readonly string[];
+    /** The names of the values the framework's stories cannot take from an address (`addressTexts.ts`); none by default. */
+    readonly refused?: readonly string[];
+};
+/** An address's `args` once read. */
+export type ArgsParamRead = {
+    /** The values read: as they will be checked, none of them yet known to be the story's. */
+    readonly args: PanelArgs;
+    /** What else the address says; none for plain JSON, or no parameter. */
+    readonly link: AddressLink | undefined;
+};
+/**
+ * What an address's `args` names, as far as the first screen reads it.
+ *
+ * @param param - the `args` parameter, decoded as `URLSearchParams` gives it.
+ */
+export declare const readArgsParam: (param: string | null) => ArgsParamRead;
+/**
+ * What a link waiting for Storybook's reader names, once it has loaded.
+ *
+ * @param param - the parameter.
+ * @param read - turns it into values: the reader's own, or one that types them for a page with no declaration.
+ * @returns what it names; the whole parameter unread when the reader cannot load.
+ */
+export declare const readStorybookLink: (param: string, read: (module: typeof import("./storybookArgs.ts"), param: string) => ArgsParamRead) => Promise<ArgsParamRead>;

package/dist/src/addressArgsParam.js

@@ -0,0 +1,51 @@
+import { isArgValue } from "./messages.js";
+/** The name of a parameter that could not be read at all. */
+const WHOLE_PARAMETER = "args";
+/**
+ * Forgebook's own form, read entry by entry.
+ *
+ * @param param - the parameter.
+ */
+const readJsonArgs = (param) => {
+    let value;
+    try {
+        value = JSON.parse(param);
+    }
+    catch {
+        return { args: {}, link: { param, isWaiting: false, unread: [WHOLE_PARAMETER] } };
+    }
+    const entries = typeof value === "object" && value !== null ? Object.entries(value) : [];
+    const unread = entries.filter(([, each]) => !isArgValue(each)).map(([name]) => name);
+    const read = entries.flatMap(([name, each]) => isArgValue(each) ? [[name, each]] : []);
+    return {
+        args: Object.fromEntries(read),
+        link: unread.length === 0 ? undefined : { param, isWaiting: false, unread }
+    };
+};
+/**
+ * What an address's `args` names, as far as the first screen reads it.
+ *
+ * @param param - the `args` parameter, decoded as `URLSearchParams` gives it.
+ */
+export const readArgsParam = (param) => {
+    if (param === null || param === "")
+        return { args: {}, link: undefined };
+    return param.trimStart().startsWith("{")
+        ? readJsonArgs(param)
+        : { args: {}, link: { param, isWaiting: true, unread: [] } };
+};
+/**
+ * What a link waiting for Storybook's reader names, once it has loaded.
+ *
+ * @param param - the parameter.
+ * @param read - turns it into values: the reader's own, or one that types them for a page with no declaration.
+ * @returns what it names; the whole parameter unread when the reader cannot load.
+ */
+export const readStorybookLink = async (param, read) => {
+    try {
+        return read(await import("./storybookArgs.js"), param);
+    }
+    catch {
+        return { args: {}, link: { param, isWaiting: false, unread: [WHOLE_PARAMETER] } };
+    }
+};

package/dist/src/addressTexts.d.ts

@@ -13,6 +13,7 @@
  *
  * @module
  */
+import type { AddressLink, ArgsParamRead } from "./addressArgsParam.ts";
 import { type PanelArgs } from "./messages.ts";
 /**
  * How a framework's stories take the texts an address carries: `any` where a text stays text (React, Vue), `plain`
@@ -33,3 +34,16 @@ export declare const isPlainText: (text: string) => boolean;
  * @param addressTexts - the framework's rule.
  */
 export declare const addressArgsFor: (args: PanelArgs, addressTexts: AddressTexts) => PanelArgs;
+/**
+ * What an address's `args` gives a story under a framework's rule, and what it says of the values the rule took out, so
+ * the note above the story names them as it names what the story's check refuses.
+ *
+ * @param read - the parameter, once read.
+ * @param param - the parameter as the address writes it.
+ * @param addressTexts - the framework's rule.
+ * @returns the values, and the link they came from.
+ */
+export declare const addressArgsRead: (read: ArgsParamRead, param: string | null, addressTexts: AddressTexts) => {
+    readonly panelArgs: PanelArgs;
+    readonly link: AddressLink | undefined;
+};

package/dist/src/addressTexts.js

@@ -1,19 +1,4 @@
-/**
- * The texts a catalogue's address may hand a story whose framework writes texts into markup: plain words only.
- *
- * @remarks
- * A link shares the props panel's values in its address (`?args=`), so whoever writes the link chooses them, and the
- * frame runs on the catalogue's own origin. React and Vue put a text into the page as text; a plain HTML story
- * writes it into an HTML string (`<button class="${tone}">${label}</button>` in a template literal), where `<`, a
- * quote or a `javascript:` address becomes markup or code. So for a framework that says its texts may become markup
- * (`FrameworkAdapter.addressTexts`), a value the address carries reaches the story only when its name and its texts
- * are plain: letters and digits of any script, spaces and a few marks that close no tag, attribute or address. The
- * panel's own edits are the person's and are not checked; a link, or a reload of an edit with markup, falls back to
- * the story's own value, as Storybook's address does. Pure.
- *
- * @module
- */
-import { isNamedArg } from "./messages.js";
+import { isArgList, isArgObject, isNamedArg } from "./messages.js";
 /** A plain text: letters, marks and digits of any script, spaces, and `_ . , ! ? # % + -`. */
 const PLAIN_TEXT = /^[\p{L}\p{M}\p{N} _.,!?#%+-]*$/u;
 /** A plain name: what a script and an attribute both write bare (`label`, `item-count`, `$size`). */
@@ -26,17 +11,20 @@ const PLAIN_NAME = /^[A-Za-z_$][\w$-]*$/;
  */
 export const isPlainText = (text) => PLAIN_TEXT.test(text);
 /**
- * Whether an address's value can reach a story whose texts may become markup: every text in it plain. A named value is
- * looked up among the source's own values, so its name is never written into the page.
+ * Whether an address's value can reach a story whose texts may become markup: every text and name in it plain. A named
+ * value is looked up among the source's own values, so its name is never written into the page.
  *
  * @param value - the value.
  */
 const isPlainValue = (value) => {
     if (typeof value === "string")
         return isPlainText(value);
-    if (Array.isArray(value))
-        return value.every((item) => typeof item !== "string" || isPlainText(item));
-    return value === null || isNamedArg(value) || typeof value !== "object";
+    if (isArgList(value))
+        return value.every(isPlainValue);
+    if (isNamedArg(value) || !isArgObject(value))
+        return true;
+    // a name is written too, by a story that spreads the object into attributes
+    return Object.entries(value).every(([name, each]) => PLAIN_NAME.test(name) && isPlainValue(each));
 };
 /**
  * The address's values a story receives under a framework's rule: all of them, or only those whose texts are plain.
@@ -49,3 +37,22 @@ export const addressArgsFor = (args, addressTexts) => addressTexts === "any"
     : Object.fromEntries(
     // a name is checked too: a story that spreads its args into attributes writes it into the markup
     Object.entries(args).filter(([name, value]) => PLAIN_NAME.test(name) && isPlainValue(value)));
+/**
+ * What an address's `args` gives a story under a framework's rule, and what it says of the values the rule took out, so
+ * the note above the story names them as it names what the story's check refuses.
+ *
+ * @param read - the parameter, once read.
+ * @param param - the parameter as the address writes it.
+ * @param addressTexts - the framework's rule.
+ * @returns the values, and the link they came from.
+ */
+export const addressArgsRead = (read, param, addressTexts) => {
+    const panelArgs = addressArgsFor(read.args, addressTexts);
+    const refused = Object.keys(read.args).filter((name) => !Object.hasOwn(panelArgs, name));
+    if (refused.length === 0)
+        return { panelArgs, link: read.link };
+    return {
+        panelArgs,
+        link: { param: param ?? "", isWaiting: false, unread: [], ...read.link, refused }
+    };
+};

package/dist/src/agentIndexFile.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The name of the index `forgebook build --agent-index` writes beside a built catalogue's pages.
+ *
+ * @remarks
+ * Apart from the index's shape (`vite/agentIndex.ts`), so the shell, which reads a composed catalogue's index, takes
+ * the name without the code that answers from it.
+ *
+ * @module
+ */
+/** The file's name in the built catalogue. */
+export declare const AGENT_INDEX_FILE = "forgebook-agent.json";

package/dist/src/agentIndexFile.js

@@ -0,0 +1,11 @@
+/**
+ * The name of the index `forgebook build --agent-index` writes beside a built catalogue's pages.
+ *
+ * @remarks
+ * Apart from the index's shape (`vite/agentIndex.ts`), so the shell, which reads a composed catalogue's index, takes
+ * the name without the code that answers from it.
+ *
+ * @module
+ */
+/** The file's name in the built catalogue. */
+export const AGENT_INDEX_FILE = "forgebook-agent.json";

package/dist/src/argConditions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * An arg's condition, `argTypes.<name>.if` (Storybook's): whether the panel shows the arg, from another arg's or a
+ * global's value of the moment. Read in the frame, tested in the shell. Pure.
+ *
+ * @remarks
+ * `{ arg: "kind", eq: "link" }` shows the arg while `kind` is `link`, and `{ global: "theme", neq: "dark" }` reads the
+ * view's switch instead. `truthy`, `exists`, `eq` and `neq` test the value, one at a time; none tests that it is truthy. A
+ * condition hides an arg's control and nothing else: a value the address or the story sets still reaches the story, as in
+ * Storybook. Only what crosses between the documents is kept: a condition comparing with an object or a function, or
+ * that names neither an arg nor a global, is not one, and shows the arg.
+ *
+ * @module
+ */
+/** What a condition can compare a value with. */
+export type ConditionValue = string | number | boolean | null | readonly (string | number)[];
+/** An arg's condition: what it reads, and how it tests it. */
+export type ArgCondition = {
+    /** The arg it reads; none when it reads a global. */
+    readonly arg?: string;
+    /** The global it reads: a switch's id; none when it reads an arg. */
+    readonly global?: string;
+    /** Whether the value should be truthy (`true`, the default test) or falsy. */
+    readonly truthy?: boolean;
+    /** Whether the value should be set, or not set. */
+    readonly exists?: boolean;
+    /** What the value should be. */
+    readonly eq?: ConditionValue;
+    /** What the value should not be. */
+    readonly neq?: ConditionValue;
+};
+/**
+ * An `if` as it crosses between the documents: only the fields it reads, since anything else may be a function, which
+ * cannot be sent and would stop the frame from reporting at all.
+ *
+ * @param value - the entry's `if`.
+ * @returns the condition; none when it is not one.
+ */
+export declare const argConditionOf: (value: unknown) => ArgCondition | undefined;
+/**
+ * Whether a value received from a frame is an arg's condition.
+ *
+ * @param value - any value.
+ */
+export declare const isArgCondition: (value: unknown) => value is ArgCondition;
+/**
+ * Whether the panel shows an arg with a condition.
+ *
+ * @param condition - its condition; none shows it.
+ * @param args - the values of the moment, by arg.
+ * @param globals - the values of the switches, by id.
+ */
+export declare const isArgShown: (condition: ArgCondition | undefined, args: Readonly<Record<string, unknown>>, globals: Readonly<Record<string, unknown>>) => boolean;

package/dist/src/argConditions.js

@@ -0,0 +1,80 @@
+/**
+ * An arg's condition, `argTypes.<name>.if` (Storybook's): whether the panel shows the arg, from another arg's or a
+ * global's value of the moment. Read in the frame, tested in the shell. Pure.
+ *
+ * @remarks
+ * `{ arg: "kind", eq: "link" }` shows the arg while `kind` is `link`, and `{ global: "theme", neq: "dark" }` reads the
+ * view's switch instead. `truthy`, `exists`, `eq` and `neq` test the value, one at a time; none tests that it is truthy. A
+ * condition hides an arg's control and nothing else: a value the address or the story sets still reaches the story, as in
+ * Storybook. Only what crosses between the documents is kept: a condition comparing with an object or a function, or
+ * that names neither an arg nor a global, is not one, and shows the arg.
+ *
+ * @module
+ */
+/** Whether a value can be compared with: it crosses between the documents, and compares as its JSON. */
+const isConditionValue = (value) => value === null ||
+    ["string", "number", "boolean"].includes(typeof value) ||
+    (Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number"));
+/**
+ * An `if` as it crosses between the documents: only the fields it reads, since anything else may be a function, which
+ * cannot be sent and would stop the frame from reporting at all.
+ *
+ * @param value - the entry's `if`.
+ * @returns the condition; none when it is not one.
+ */
+export const argConditionOf = (value) => {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const arg = Reflect.get(value, "arg");
+    const global = Reflect.get(value, "global");
+    const truthy = Reflect.get(value, "truthy");
+    const exists = Reflect.get(value, "exists");
+    const eq = Reflect.get(value, "eq");
+    const neq = Reflect.get(value, "neq");
+    if ((typeof arg === "string") === (typeof global === "string"))
+        return undefined;
+    if (eq !== undefined && !isConditionValue(eq))
+        return undefined;
+    if (neq !== undefined && !isConditionValue(neq))
+        return undefined;
+    return {
+        ...(typeof arg === "string" ? { arg } : {}),
+        ...(typeof global === "string" ? { global } : {}),
+        ...(typeof truthy === "boolean" ? { truthy } : {}),
+        ...(typeof exists === "boolean" ? { exists } : {}),
+        ...(eq === undefined ? {} : { eq }),
+        ...(neq === undefined ? {} : { neq })
+    };
+};
+/**
+ * Whether a value received from a frame is an arg's condition.
+ *
+ * @param value - any value.
+ */
+export const isArgCondition = (value) => argConditionOf(value) !== undefined;
+/**
+ * Whether two values are the same, a list by its items.
+ *
+ * @param first - one value.
+ * @param second - the other.
+ */
+const isSameValue = (first, second) => JSON.stringify(first) === JSON.stringify(second);
+/**
+ * Whether the panel shows an arg with a condition.
+ *
+ * @param condition - its condition; none shows it.
+ * @param args - the values of the moment, by arg.
+ * @param globals - the values of the switches, by id.
+ */
+export const isArgShown = (condition, args, globals) => {
+    if (condition === undefined)
+        return true;
+    const value = condition.arg === undefined ? globals[condition.global ?? ""] : args[condition.arg];
+    if (condition.eq !== undefined)
+        return isSameValue(value, condition.eq);
+    if (condition.neq !== undefined)
+        return !isSameValue(value, condition.neq);
+    if (condition.exists !== undefined)
+        return condition.exists === (value !== undefined);
+    return (condition.truthy ?? true) === Boolean(value);
+};

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);
+};