forgebook 0.3.3 → 0.4.1

package/dist/src/argControl.d.ts

@@ -0,0 +1,148 @@
+/**
+ * A custom control's contract: a module a catalogue or a library's preset registers by name (`argControls`) and a story
+ * uses as `argTypes: { x: { control: "name" } }`, or that takes the props of a type in every story (`matches`); and its
+ * frame module, which turns the control's value into the story's.
+ *
+ * @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; the frame module in the stories' frames, as a preview.
+ *
+ * @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;
+    /**
+     * The control's texts as the catalogue words them: its `strings` (a preset's, then the catalogue's own over them) whose
+     * key starts with `argControls.<name>.`, by the rest of the key (`none` for `argControls.icon.none`). A control falls
+     * back to its own words for a key it does not find. Always given by the panel; optional so a control's own tests need
+     * not build it.
+     */
+    readonly strings?: Readonly<Record<string, string>>;
+};
+/** 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;
+    /**
+     * The code a value is written as in the story's code (the Code tab, `forgebook story`), when it is not the value as
+     * JSON: the expression the attribute holds, `IconStar` for the icon the name `"IconStar"` gives the story (written
+     * `icon={IconStar}`). None, or `undefined` for a value, writes the JSON value. Runs in the page and on the dev server,
+     * so it reads nothing of either.
+     *
+     * @param value - the panel's value.
+     * @param argType - what the story says of the arg.
+     * @returns the expression, as code.
+     */
+    readonly toCode?: (value: JsonValue, argType: ControlArgType) => string | undefined;
+};
+/** What a frame module is told of the arg whose value it turns into the story's. */
+export type FrameArgType = {
+    /** The arg's name. */
+    readonly name: string;
+    /** The control's `settings` the story's `argTypes` write, as JSON; none when they write none. */
+    readonly settings?: JsonValue;
+};
+/** A custom control's frame module: loaded in a story's frame when the panel first gives it a value of that control. */
+export type ArgControlFrameModule = {
+    /**
+     * The value the story receives for the panel's: a name turned into the component it names, say. Links and agents keep
+     * the JSON value; this runs only in the frame, after the shell checked the value against the control's schema. A link
+     * chose it, so read it as any JSON: look a name up among your own entries (`Object.hasOwn`), never through a prototype.
+     *
+     * @param value - the panel's value, as JSON.
+     * @param argType - the arg.
+     * @returns what the story receives; `undefined` gives the story no value.
+     */
+    readonly toStoryValue: (value: JsonValue, argType: FrameArgType) => unknown;
+    /**
+     * The panel's value for a value the story gives itself (the icon its `args` name back into its name), so the control
+     * shows what the story draws; none leaves the control without one, as for any value JSON cannot hold.
+     *
+     * @param value - the story's own value.
+     * @param argType - the arg.
+     * @returns the panel's value, which the control's schema must take; `undefined` when it has none.
+     */
+    readonly toPanelValue?: (value: unknown, argType: FrameArgType) => JsonValue | undefined;
+};

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[];