forgebook 0.3.3 → 0.4.1

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. */
@@ -78,12 +129,24 @@ export type PropDocs = {
      * union by the types it happened to meet first, so it changed between reads of a program kept in memory.
      */
     readonly type: string;
+    /**
+     * The names its type goes by, when they are more than `type`: the name written, the name it was declared with when an
+     * import renamed it, and each alias it is declared through (`ButtonIcon`, `IconComponent` for
+     * `type ButtonIcon = IconComponent`), without `undefined` and `null`; for a union, the names every member goes by. Left
+     * out when `type` says them all.
+     */
+    readonly typeNames?: readonly string[];
     /** The first paragraph of its TSDoc; empty when it has none. */
     readonly description: string;
     /** Its `@defaultValue`, when the TSDoc gives one. */
     readonly defaultValue?: string;
     /** Whether the prop must be passed. */
     readonly isRequired: boolean;
+    /**
+     * The custom control the catalogue gives it by its type or its name (a control's `matches`), when one does: the
+     * plugin adds it as it serves the docs, so the panel draws it in every story that names no control for the prop.
+     */
+    readonly customControl?: string;
     /** For a choice, its values in the order of the type. */
     readonly choices?: readonly (string | number)[];
     /** For an event, its signature. */
@@ -103,6 +166,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 +243,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,7 +30,13 @@ const isMemberDocs = (value) => isRecord(value) &&
     typeof value["description"] === "string" &&
     typeof value["isRequired"] === "boolean" &&
     (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
-/** Whether a value is one prop's docs. */
+/** 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. Some fields are left to what reads them, as a choice's values and a signature are:
+ * a custom control's name is only looked up among the catalogue's own controls, so a wrong one finds none and says so
+ * beside the field; the shell reads no type's names.
+ */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
     PROP_KINDS.some((kind) => kind === value["kind"]) &&
@@ -39,8 +45,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 +90,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/controlCode.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a custom control is told of its arg, and the code its values are written as in a story's code: the expression a
+ * control's `toCode` gives (`IconStar` for the name `"IconStar"`), for the Code tab and `forgebook story`. Pure.
+ *
+ * @module
+ */
+import type { ArgControlModule, ControlArgType } from "./argControl.ts";
+import type { PanelProp } from "./argTypes.ts";
+import { type PanelArgs } from "./messages.ts";
+/**
+ * What a control is told of its arg.
+ *
+ * @param prop - the prop, with the story's `argTypes` laid over it.
+ */
+export declare const controlArgTypeOf: (prop: PanelProp) => ControlArgType;
+/** A control's `toCode`, by control: what writes its values as code. */
+export type ControlCoders = Readonly<Record<string, ArgControlModule["toCode"]>>;
+/**
+ * The code each arg of a custom control is written as, by arg: the expression its control's `toCode` gives for its
+ * value. An arg without a value, with the panel's "no value", whose control writes no code, or whose `toCode` throws
+ * or gives nothing, is written from its value as before.
+ *
+ * @param props - the props the panel sets, with the story's `argTypes` laid over them.
+ * @param args - the values the code is written from.
+ * @param coders - each control's `toCode`, by control.
+ */
+export declare const controlCodeOf: (props: readonly PanelProp[], args: PanelArgs, coders: ControlCoders) => Readonly<Record<string, string>>;

package/dist/src/controlCode.js

@@ -0,0 +1,41 @@
+import { isArgValue, isUnsetArg } from "./messages.js";
+/**
+ * What a control is told of its arg.
+ *
+ * @param prop - the prop, with the story's `argTypes` laid over it.
+ */
+export const controlArgTypeOf = (prop) => ({
+    name: prop.name,
+    label: prop.label ?? prop.name,
+    description: prop.description,
+    ...(prop.choices === undefined ? {} : { options: prop.choices }),
+    ...(prop.min === undefined ? {} : { min: prop.min }),
+    ...(prop.max === undefined ? {} : { max: prop.max }),
+    ...(prop.step === undefined ? {} : { step: prop.step }),
+    // the frame's word, read here since only a control needs it: what is no plain data never reaches a control
+    ...(prop.settings === undefined || !isArgValue(prop.settings) ? {} : { settings: prop.settings })
+});
+/**
+ * The code each arg of a custom control is written as, by arg: the expression its control's `toCode` gives for its
+ * value. An arg without a value, with the panel's "no value", whose control writes no code, or whose `toCode` throws
+ * or gives nothing, is written from its value as before.
+ *
+ * @param props - the props the panel sets, with the story's `argTypes` laid over them.
+ * @param args - the values the code is written from.
+ * @param coders - each control's `toCode`, by control.
+ */
+export const controlCodeOf = (props, args, coders) => Object.fromEntries(props.flatMap((prop) => {
+    const control = prop.customControl;
+    const value = Object.hasOwn(args, prop.name) ? args[prop.name] : undefined;
+    const toCode = control !== undefined && Object.hasOwn(coders, control) ? coders[control] : undefined;
+    if (toCode === undefined || value === undefined || isUnsetArg(value))
+        return [];
+    try {
+        const code = toCode(value, controlArgTypeOf(prop));
+        return typeof code === "string" && code !== "" ? [[prop.name, code]] : [];
+    }
+    catch {
+        // the control's code is its own: a failure writes the value as JSON, as a control without `toCode`
+        return [];
+    }
+}));

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

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

@@ -0,0 +1,33 @@
+/**
+ * Tells the shell the colour scheme a frame's document draws in, so the frame element can have the same one.
+ *
+ * @remarks
+ * A browser paints an opaque canvas behind an embedded document when its used colour scheme differs from its frame
+ * element's: white for a light document, near black for a dark one, over the page colour the shell draws behind the
+ * frame. Which scheme the document draws in is its own business (a theme's `color-scheme`, a `meta` tag, the system's
+ * preference), and only the document can read it; writing a scheme on the document instead would change how the story
+ * draws its controls.
+ *
+ * @module
+ */
+import type { FrameMessage } from "../messages.ts";
+/** A colour scheme a document draws in. */
+export type CanvasScheme = "light" | "dark";
+/**
+ * The scheme a canvas colour belongs to.
+ *
+ * @param colour - the computed colour of `Canvas`, as `rgb(18, 18, 18)`.
+ * @returns the scheme; light when the text is not a colour, as a document that declares no scheme draws.
+ */
+export declare const schemeOfCanvas: (colour: string) => CanvasScheme;
+/**
+ * Follows the scheme a frame's document draws in: tells it now, and again when it changes with the root (a switch, a
+ * theme's class), a style sheet that finished loading, or the system's preference.
+ *
+ * @param document - the frame's document.
+ * @param window - its window.
+ * @param storyId - the story's id, for the shell.
+ * @param tellShell - tells the shell, once for each change.
+ * @returns what checks it again, for what no event says: styles a story's module brought with it.
+ */
+export declare const followCanvasScheme: (document: Document, window: Window, storyId: string, tellShell: (message: FrameMessage) => void) => (() => void);

package/dist/src/frame/canvasScheme.js

@@ -0,0 +1,67 @@
+/**
+ * Tells the shell the colour scheme a frame's document draws in, so the frame element can have the same one.
+ *
+ * @remarks
+ * A browser paints an opaque canvas behind an embedded document when its used colour scheme differs from its frame
+ * element's: white for a light document, near black for a dark one, over the page colour the shell draws behind the
+ * frame. Which scheme the document draws in is its own business (a theme's `color-scheme`, a `meta` tag, the system's
+ * preference), and only the document can read it; writing a scheme on the document instead would change how the story
+ * draws its controls.
+ *
+ * @module
+ */
+/** Red, green and blue summed above this is a light canvas: browsers keep theirs near white or near black. */
+const LIGHT_CANVAS_SUM = 382;
+/**
+ * The scheme a canvas colour belongs to.
+ *
+ * @param colour - the computed colour of `Canvas`, as `rgb(18, 18, 18)`.
+ * @returns the scheme; light when the text is not a colour, as a document that declares no scheme draws.
+ */
+export const schemeOfCanvas = (colour) => {
+    const channels = colour.match(/\d+(?:\.\d+)?/g)?.slice(0, 3) ?? [];
+    const sum = channels.reduce((total, channel) => total + Number(channel), 0);
+    return channels.length === 3 && sum <= LIGHT_CANVAS_SUM ? "dark" : "light";
+};
+/**
+ * The scheme a document draws in, read from what its `Canvas` system colour resolves to: this takes in `color-scheme`
+ * with several values, the system's preference and a `meta` tag, which the computed property alone does not say.
+ *
+ * @param document - the document.
+ * @param window - its window.
+ */
+const usedScheme = (document, window) => {
+    // in the `head`, where no story's observer of the page sees it come and go; it inherits the root's scheme
+    const probe = document.createElement("meta");
+    probe.style.color = "Canvas";
+    document.head.append(probe);
+    const colour = window.getComputedStyle(probe).color;
+    probe.remove();
+    return schemeOfCanvas(colour);
+};
+/**
+ * Follows the scheme a frame's document draws in: tells it now, and again when it changes with the root (a switch, a
+ * theme's class), a style sheet that finished loading, or the system's preference.
+ *
+ * @param document - the frame's document.
+ * @param window - its window.
+ * @param storyId - the story's id, for the shell.
+ * @param tellShell - tells the shell, once for each change.
+ * @returns what checks it again, for what no event says: styles a story's module brought with it.
+ */
+export const followCanvasScheme = (document, window, storyId, tellShell) => {
+    let told;
+    const check = () => {
+        const scheme = usedScheme(document, window);
+        if (scheme === told)
+            return;
+        told = scheme;
+        tellShell({ type: "forgebook:scheme", storyId, scheme });
+    };
+    new MutationObserver(check).observe(document.documentElement, { attributes: true });
+    // a `load` does not bubble: seen on its way down, as a `link` of the `head` finishes
+    document.addEventListener("load", check, true);
+    window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", check);
+    check();
+    return check;
+};

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

@@ -0,0 +1,39 @@
+import { type PanelArgs } from "../messages.ts";
+import { panelArgTypesOf } from "../storyArgTypes.ts";
+import type { ControlFrameLoaders } from "./panelControls.ts";
+/** What the frame modules made of the values. */
+export type ControlValues = {
+    /** What the story receives, by arg, over what the panel's JSON gives it. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** The args whose value could not be made: the story keeps its own. */
+    readonly dropped: readonly string[];
+    /** The story's own values as the panel shows them, by arg, for those a frame module names. */
+    readonly own: PanelArgs;
+    /** What went wrong, one sentence per failure. */
+    readonly problems: readonly string[];
+};
+/** The story, as the frame modules read it. */
+export type ControlStory = {
+    /** Its own args. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Its `argTypes`: the controls they name, and a control's `settings`. */
+    readonly argTypes: Parameters<typeof panelArgTypesOf>[0];
+    /** Loads its component's docs, which name the controls the catalogue gives props by type; none without docs. */
+    readonly loadDocs?: (() => Promise<unknown>) | undefined;
+};
+/**
+ * The custom control of each arg, as the panel draws it: a control the story's `argTypes` name, else the one the
+ * catalogue gives the prop by type, unless the `argTypes` name another control for it.
+ *
+ * @param argTypes - the story's `argTypes`, as the panel reads them.
+ * @param docs - its component's docs, as the plugin served them.
+ */
+export declare const argControlsOf: (argTypes: ReturnType<typeof panelArgTypesOf>, docs: unknown) => Readonly<Record<string, string>>;
+/**
+ * The values of the controls with a frame module, as the story and the panel take them.
+ *
+ * @param args - the panel's values, checked by the shell.
+ * @param loaders - the frame modules, by control.
+ * @param story - the story's own args, its `argTypes` and its docs.
+ */
+export declare const controlValuesOf: (args: PanelArgs, loaders: ControlFrameLoaders, story: ControlStory) => Promise<ControlValues>;