forgebook 0.3.2 → 0.4.0

package/dist/src/addressArgs.d.ts

@@ -10,14 +10,20 @@
  * have set it: a prop the panel lets the person set (the component's props with the story's `argTypes` laid over them,
  * or an arg only the `argTypes` or the story's own args name), with a value of that prop's type. Everything else is
  * left out and reported. A value that is code never comes from an address: a named value is looked up among the
- * source's own entries only, never through an object's prototype (`constructor`). Pure.
+ * source's own entries only, never through an object's prototype (`constructor`). An object's names are checked the
+ * same way, against its type (`valueShape.ts`). The panel's "no value" (`UnsetArg`) passes for any prop the panel sets:
+ * the story receives `undefined`, which any prop may. Pure.
+ *
+ * A frame takes values from one kind of message only, whichever frame it is (the stage's, an embed's, a plugin's aside),
+ * so `checkedArgsMessage` builds it, from nothing but what this check sealed (`AcceptedArgs`): a page that skipped the
+ * check has no value of that type to give it. A test holds every other module to not writing the message itself.
  *
  * @module
  */
 import type { StoryControlsSetting } from "@forgebook/story-format/source";
 import { type PanelArgTypes, type PanelProp } from "./argTypes.ts";
 import type { PropDocs } from "./componentDocs.ts";
-import { type ArgValue, type PanelArgs } from "./messages.ts";
+import { type ArgValue, type PanelArgs, type ShellMessage } from "./messages.ts";
 import { type NamedValues } from "./namedValues.ts";
 /** What a story declares about the args the panel sets, as the shell knows it once the story's frame is ready. */
 export type ArgDeclaration = {
@@ -32,8 +38,11 @@ export type ArgDeclaration = {
     /** The values the source names for types the panel cannot write. */
     readonly namedValues: NamedValues;
 };
-/** Why a value of the address was left out: its name is not one the panel sets, or its value is not of the prop's type. */
-export type DroppedArgReason = "undeclared" | "type";
+/**
+ * Why a value of the address was left out: its name is not one the panel sets, its value is not of the prop's type, its
+ * text could not be read as a value at all, or its custom control refuses it or cannot load.
+ */
+export type DroppedArgReason = "undeclared" | "type" | "unreadable" | "control" | "markup";
 /** A value of the address left out. */
 export type DroppedArg = {
     /** The arg's name, as the address wrote it. */
@@ -47,7 +56,22 @@ export type CheckedArgs = {
     readonly accepted: PanelArgs;
     /** The values left out, in the address's order. */
     readonly dropped: readonly DroppedArg[];
+    /** Whether a value waits for what checks it: it is neither taken nor left out yet. */
+    readonly isWaiting: boolean;
+    /** The values the story receives, as a frame can be told them. */
+    readonly sealed: AcceptedArgs;
 };
+/** What only this module can write on values: the type system's proof that they went through the check. */
+declare const ACCEPTED: unique symbol;
+/** Values the check accepted, the only ones a frame can be told. */
+export type AcceptedArgs = {
+    /** The values. */
+    readonly values: PanelArgs;
+    /** Marks them as the check's. */
+    readonly [ACCEPTED]: true;
+};
+/** No values: what a frame the address has no say in receives (a story on a docs page). */
+export declare const NO_ACCEPTED_ARGS: AcceptedArgs;
 /**
  * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
  * them and the args only the `argTypes` name, then the story's own args the two leave out, each kept only when the
@@ -56,6 +80,19 @@ export type CheckedArgs = {
  * @param declaration - what the story declares.
  */
 export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly PanelProp[];
+/** What checks a custom control's value, by control: gives what is wrong with it. A control missing here refuses all. */
+export type CustomChecks = Readonly<Record<string, (value: ArgValue) => string | undefined>>;
+/** What checks a structured value: `shapeValues.ts` and each control's schema, loaded with the first prop that needs them. */
+export type ArgChecks = Pick<typeof import("./shapeValues.ts"), "isValueOfShape" | "isFileList"> & {
+    /** What checks a custom control's value; none refuses them all. */
+    readonly custom?: CustomChecks;
+};
+/**
+ * Whether a prop's values are checked by `shapeValues.ts`.
+ *
+ * @param prop - a prop the panel sets.
+ */
+export declare const needsShapeChecks: (prop: PanelProp) => boolean;
 /**
  * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
  * kind.
@@ -63,12 +100,23 @@ export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly
  * @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 declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues) => boolean;
+export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues, shapes?: ArgChecks) => boolean;
 /**
  * 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 declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration, typeValue?: (prop: PanelProp, value: ArgValue) => ArgValue, checks?: ArgChecks) => CheckedArgs;
+/**
+ * The message that gives a frame its values.
+ *
+ * @param accepted - the values `checkedAddressArgs` accepted.
  */
-export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration) => CheckedArgs;
+export declare const checkedArgsMessage: (accepted: AcceptedArgs) => ShellMessage;
+export {};

package/dist/src/addressArgs.js

@@ -1,6 +1,10 @@
 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");
+/** No values: what a frame the address has no say in receives (a story on a docs page). */
+export const NO_ACCEPTED_ARGS = { values: {}, [ACCEPTED]: true };
 /** A prop made from one of the story's own args, for an arg neither the types nor the `argTypes` name. */
 const propOfStoryArg = (name, value) => {
     const prop = { name, type: "", description: "", isRequired: false };
@@ -13,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
@@ -32,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.
@@ -45,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":
@@ -63,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:
@@ -78,32 +101,65 @@ 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 });
     }
-    return { accepted: Object.fromEntries(accepted), dropped };
+    const values = Object.fromEntries(accepted);
+    return { accepted: values, dropped, isWaiting, sealed: { values, [ACCEPTED]: true } };
 };
+/**
+ * The message that gives a frame its values.
+ *
+ * @param accepted - the values `checkedAddressArgs` accepted.
+ */
+export const checkedArgsMessage = (accepted) => ({
+    type: "forgebook:args",
+    args: accepted.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);
+};