forgebook 0.3.3 → 0.4.1

package/dist/src/storybookArgs.js

@@ -0,0 +1,185 @@
+import { isChoiceList, UNSET_ARG } from "./messages.js";
+/** A number as Storybook's links write it. */
+const NUMBER_TEXT = /^-?[0-9]+(\.[0-9]+)?$/;
+/** A colour as Storybook writes it after its `!`. */
+const COLOR = /^(rgba?|hsla?)\(([0-9]{1,3}),\s?([0-9]{1,3})%?,\s?([0-9]{1,3})%?,?\s?([0-9](\.[0-9]{1,2})?)?\)$/i;
+/** An arg's name in Storybook's form, with a list's index: `tags[1]`, `tags[]`. */
+const STORYBOOK_KEY = /^([^.[\]]+)(?:\[([0-9]*)\])?$/;
+/**
+ * What a text of a link is for a prop, whose type it does not carry: a number for a prop that takes numbers, a toggle's
+ * value, a choice's option; a text otherwise.
+ *
+ * @param prop - a prop the panel sets.
+ * @param text - the link's text.
+ */
+const typedText = (prop, text) => {
+    const option = (prop.choices ?? []).find((choice) => String(choice) === text);
+    if (option !== undefined)
+        return option;
+    const isToggle = prop.control === "boolean" || (prop.control === undefined && prop.kind === "toggle");
+    if (isToggle && (text === "true" || text === "false"))
+        return text === "true";
+    const isNumeric = prop.control === "number" ||
+        prop.control === "range" ||
+        prop.control === "date" ||
+        (prop.control === undefined && prop.kind === "number") ||
+        // a mixed union's number (`"sm" | number`): a text it takes too stays one only when the text is no number
+        (prop.shape?.kind === "union" && prop.shape.of.some((member) => member.kind === "number")) ||
+        (prop.shape?.kind === "list" && prop.shape.of.kind === "number");
+    return isNumeric && NUMBER_TEXT.test(text) ? Number(text) : text;
+};
+/**
+/** What a text is for a custom control, whose type only its schema knows: a number or a toggle when it writes one. */
+const customText = (text) => {
+    if (text === "true" || text === "false")
+        return text === "true";
+    return NUMBER_TEXT.test(text) ? Number(text) : text;
+};
+/**
+ * A value of a link, typed for a prop.
+ *
+ * @param prop - the prop that receives it.
+ * @param value - the link's value.
+ */
+const typedLinkValue = (prop, value) => {
+    if (typeof value === "string" && prop.customControl !== undefined)
+        return customText(value);
+    if (typeof value === "string")
+        return typedText(prop, value);
+    if (!isChoiceList(value))
+        return value;
+    return value.map((item) => {
+        const typed = typeof item === "string" ? typedText(prop, item) : item;
+        return typeof typed === "boolean" ? String(typed) : typed;
+    });
+};
+/**
+ * A text decoded once more: Storybook's form goes through its own query parser after the address's. A `%` that starts no
+ * escape is the text's own.
+ *
+ * @param text - the text.
+ */
+const decoded = (text) => {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        return text;
+    }
+};
+/**
+ * A colour's text, as Storybook's reading writes it.
+ *
+ * @param marked - the value after its `!`.
+ * @returns the text; none when it is no colour.
+ */
+const colorOf = (marked) => {
+    const color = COLOR.exec(marked);
+    if (color === null)
+        return undefined;
+    const [, kind = "", first, second, third, alpha] = color;
+    const unit = kind.toLowerCase().startsWith("hsl") ? "%" : "";
+    return kind.toLowerCase().endsWith("a")
+        ? `${kind}(${first}, ${second}${unit}, ${third}${unit}, ${alpha})`
+        : `${kind}(${first}, ${second}${unit}, ${third}${unit})`;
+};
+/**
+ * One of Storybook's values: its marked ones read, the others left as text.
+ *
+ * @param text - the value.
+ * @returns the value; none when no arg can hold it.
+ */
+const storybookValue = (text) => {
+    if (!text.startsWith("!"))
+        return text;
+    if (text === "!undefined")
+        return UNSET_ARG;
+    if (text === "!null")
+        return null;
+    if (text === "!true")
+        return true;
+    if (text === "!false")
+        return false;
+    if (text.startsWith("!date(") && text.endsWith(")")) {
+        const time = Date.parse(text.slice(6, -1).replaceAll(" ", "+"));
+        return Number.isNaN(time) ? undefined : time;
+    }
+    if (text.startsWith("!hex(") && text.endsWith(")"))
+        return `#${text.slice(5, -1)}`;
+    // a mark that means nothing is the text's own, as Storybook reads it
+    return colorOf(text.slice(1)) ?? text;
+};
+/**
+ * What one arg's entries make: its value, or a list when there are several or a bracket says so, as Storybook repeats a
+ * key for a list too (`tags:a;tags:b`).
+ *
+ * @param entries - its entries, in the address's order.
+ * @returns the value; none when it cannot be held, a list with a hole among them.
+ */
+const valueOfEntries = (entries) => {
+    const [only] = entries;
+    if (entries.length === 1 && only !== undefined && !only.isListed)
+        return only.value;
+    const items = new Map();
+    for (const { index, value } of entries)
+        items.set(index ?? items.size, value);
+    const list = [...Array(items.size).keys()].map((index) => items.get(index));
+    return isChoiceList(list) ? list : undefined;
+};
+/**
+ * The name of an arg in a key: what comes before its first `.` or `[`.
+ *
+ * @param key - the key.
+ */
+const nameOfKey = (key) => key.split(/[.[]/, 1)[0] || key;
+/**
+ * One `name:value` of Storybook's form, or the name to report when it is none that can be held.
+ *
+ * @param part - the text between two `;`.
+ */
+const storybookPart = (part) => {
+    const colon = part.indexOf(":");
+    const key = decoded(colon === -1 ? part : part.slice(0, colon));
+    const match = colon <= 0 ? null : STORYBOOK_KEY.exec(key);
+    const name = match?.[1];
+    if (name === undefined)
+        return { name: key === "" ? part : nameOfKey(key) };
+    const bracket = match?.[2];
+    const index = bracket === undefined || bracket === "" ? undefined : Number(bracket);
+    const value = storybookValue(decoded(part.slice(colon + 1)));
+    return { name, entry: { index, isListed: bracket !== undefined, value } };
+};
+/**
+ * Storybook's form, read.
+ *
+ * @param param - the parameter.
+ */
+export const readStorybookArgs = (param) => {
+    const entries = new Map();
+    const unread = new Set();
+    for (const { name, entry } of param
+        .split(";")
+        .filter((each) => each !== "")
+        .map(storybookPart)) {
+        if (entry === undefined)
+            unread.add(name);
+        else {
+            const ofName = entries.get(name);
+            if (ofName === undefined)
+                entries.set(name, [entry]);
+            else
+                ofName.push(entry);
+        }
+    }
+    const read = [...entries].flatMap(([name, ofName]) => {
+        const value = valueOfEntries(ofName);
+        if (value === undefined)
+            unread.add(name);
+        return value === undefined ? [] : [[name, value]];
+    });
+    return {
+        // an arg with an entry that cannot be read is not given in part
+        args: Object.fromEntries(read.filter(([name]) => !unread.has(name))),
+        link: { param, isWaiting: false, typeValue: typedLinkValue, unread: [...unread] }
+    };
+};

package/dist/src/switches.d.ts

@@ -12,6 +12,25 @@
  *
  * @module
  */
+/**
+ * What a gallery shows of a value before it is applied (`control: "gallery"`): a picture the catalogue provides, or a
+ * few colours with a font's name.
+ *
+ * @remarks
+ * Nothing here loads from an address. The picture is a file on disk, which the build gives an address of its own;
+ * the colours paint swatches; the font is a name, drawn in that font only where the reader has it installed. The
+ * configuration's check refuses anything else (`vite/switchValuesCheck.ts`).
+ */
+export type SwitchPreview = 
+/** A picture: a file by its path from the configuration's folder, or absolute (a preset's). */
+{
+    readonly image: string;
+}
+/** Up to eight CSS colours, and a font's name to show beside them; none by default. */
+ | {
+    readonly swatches: readonly string[];
+    readonly font?: string;
+};
 /** One value a switch offers. */
 export type SwitchValue = {
     /** The value, as the address and the root's attribute write it (`dark`). */
@@ -26,6 +45,22 @@ export type SwitchValue = {
     readonly isMore?: boolean;
     /** For a `language` switch: whether the language reads right to left, which draws the story right to left. */
     readonly isRightToLeft?: boolean;
+    /** What a gallery shows of it; a value with none shows its label's first letter. */
+    readonly preview?: SwitchPreview;
+    /**
+     * The values this value sets on other switches, by switch id (`{ theme: "dark" }`: a look drawn only for dark). While
+     * it is chosen, each named switch draws that value and its control is off, saying what sets it; the address keeps the
+     * reader's own value, which comes back when the value is left. It wins over the address, and over what a story fixes.
+     * When two values imply different values of a switch, the one of the switch declared first wins. An implied value
+     * implies nothing further: the configuration's check refuses one that would.
+     */
+    readonly implies?: Readonly<Record<string, string>>;
+    /**
+     * A style sheet of this value alone: a file by its path from the configuration's folder, or absolute (a preset's).
+     * Loaded only while the value is drawn, with Styles › Full, after the source's sheets, the switches' in the order they
+     * are declared. A change of value keeps the old sheet until the new one has loaded.
+     */
+    readonly sheet?: string;
 };
 /** Where a switch applies. */
 export type SwitchApply = 
@@ -58,6 +93,8 @@ export type SwitchApply =
  * texts and the language's provider), the direction (a catalogue's own switch in place of the ready-made one).
  */
 export type SwitchRole = "colorScheme" | "contrast" | "language" | "direction" | "touch";
+/** The ways a switch can be offered. */
+export type SwitchControlKind = "segments" | "list" | "gallery";
 /** A switch of the toolbar or the View menu. */
 export type ViewSwitch = {
     /** A stable id, the address's parameter (`theme`). */
@@ -72,8 +109,11 @@ export type ViewSwitch = {
     readonly apply: SwitchApply;
     /** What the catalogue reads of it; none for a switch only the library reads. */
     readonly role?: SwitchRole;
-    /** How the View menu offers it: a row of segments (by default, up to six values) or a list. */
-    readonly control?: "segments" | "list";
+    /**
+     * How the toolbar and the View menu offer it: a row of segments (by default, up to six values), a list, or a gallery,
+     * a menu whose items show each value's `preview`.
+     */
+    readonly control?: SwitchControlKind;
     /** What a reader should know of it, in a sentence or two: under its row in the View menu and in its tooltip. */
     readonly description?: string;
 };
@@ -147,12 +187,35 @@ export declare const touchChoiceOf: (switches: readonly ViewSwitch[]) => TouchCh
  * @param value - the value given; none for the default.
  */
 export declare const switchValueOf: (each: ViewSwitch, value: string | undefined) => SwitchValue | undefined;
+/**
+ * The values other switches' values imply, by the implied switch's id, each with the value that implies it.
+ *
+ * @remarks
+ * Read from the values alone, so applying it twice gives the same answer: the shell, a frame and a tool opening a
+ * frame's address agree without telling each other. A switch already implied implies nothing itself, and one whose value
+ * already implies cannot be implied, so a value that is not drawn never implies, and the switch declared first wins a
+ * conflict.
+ *
+ * @param values - the switches' values, by id; a switch left out has its default.
+ * @param switches - the catalogue's switches.
+ */
+export declare const impliedSwitches: (values: Readonly<Record<string, string>>, switches: readonly ViewSwitch[]) => ReadonlyMap<string, {
+    readonly value: string;
+    readonly by: SwitchValue;
+}>;
+/**
+ * The switches' values as they are drawn: the ones given, with what their values imply over them.
+ *
+ * @param values - the switches' values, by id.
+ * @param switches - the catalogue's switches.
+ */
+export declare const shownSwitches: (values: Readonly<Record<string, string>>, switches: readonly ViewSwitch[]) => Readonly<Record<string, string>>;
 /**
  * How the View menu offers a switch: as it declares, or segments up to six values and a list past them.
  *
  * @param each - the switch.
  */
-export declare const switchControl: (each: ViewSwitch) => "segments" | "list";
+export declare const switchControl: (each: ViewSwitch) => SwitchControlKind;
 /**
  * A catalogue's switches: the ones it declares (the theme and the contrast when it declares none), then, when it or a
  * source offers languages, the language switch over all of them, then the ready-made direction and touch switches,

package/dist/src/switches.js

@@ -16,6 +16,8 @@ import { DEVICE_PARAMETER, ORIENTATION_PARAMETER } from "./deviceView.js";
 /** The address's own parameters: a switch may not take their names. */
 const RESERVED_IDS = [
     "embed",
+    "play",
+    "tag",
     "story",
     "component",
     "backdrop",
@@ -33,7 +35,8 @@ const RESERVED_IDS = [
     "args",
     "matrix",
     "clock",
-    "audience"
+    "audience",
+    "ref"
 ];
 /**
  * Why a list of switches cannot be used, or none: ids unique and not the address's own, a default among the values,
@@ -173,6 +176,44 @@ export const touchChoiceOf = (switches) => {
  * @param value - the value given; none for the default.
  */
 export const switchValueOf = (each, value) => each.values.find((candidate) => candidate.value === (value ?? each.default));
+/**
+ * The values other switches' values imply, by the implied switch's id, each with the value that implies it.
+ *
+ * @remarks
+ * Read from the values alone, so applying it twice gives the same answer: the shell, a frame and a tool opening a
+ * frame's address agree without telling each other. A switch already implied implies nothing itself, and one whose value
+ * already implies cannot be implied, so a value that is not drawn never implies, and the switch declared first wins a
+ * conflict.
+ *
+ * @param values - the switches' values, by id; a switch left out has its default.
+ * @param switches - the catalogue's switches.
+ */
+export const impliedSwitches = (values, switches) => {
+    const implied = new Map();
+    const implying = new Set();
+    for (const each of switches) {
+        const by = switchValueOf(each, values[each.id]);
+        if (by?.implies === undefined || implied.has(each.id))
+            continue;
+        implying.add(each.id);
+        for (const [id, value] of Object.entries(by.implies))
+            if (!implied.has(id) && !implying.has(id))
+                implied.set(id, { value, by });
+    }
+    return implied;
+};
+/**
+ * The switches' values as they are drawn: the ones given, with what their values imply over them.
+ *
+ * @param values - the switches' values, by id.
+ * @param switches - the catalogue's switches.
+ */
+export const shownSwitches = (values, switches) => {
+    const shown = { ...values };
+    for (const [id, { value }] of impliedSwitches(values, switches))
+        shown[id] = value;
+    return shown;
+};
 /**
  * How the View menu offers a switch: as it declares, or segments up to six values and a list past them.
  *

package/dist/src/valueSchema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The schema of a custom control's value, and the check of a value against it: a small part of JSON Schema, written by the
+ * control's author, read in the shell and by the commands. No dependency, so the check costs a catalogue with custom
+ * controls little and any other nothing.
+ *
+ * @remarks
+ * A keyword outside this list is refused rather than ignored: a schema that says less than it seems to would let a link
+ * through. Pure.
+ *
+ * @module
+ */
+import type { ValueSchema } from "./argControl.ts";
+import { type ArgValue } from "./messages.ts";
+/**
+ * Whether a module's `schema` is one this check reads in full, at any depth: a keyword it does not know, or one holding what
+ * it cannot use, would let through what the schema seems to refuse.
+ *
+ * @param value - the module's export.
+ */
+export declare const isValueSchema: (value: unknown) => value is ValueSchema;
+/**
+ * What is wrong with a value, in a sentence.
+ *
+ * @param schema - the control's schema.
+ * @param value - the value.
+ * @returns the sentence; none when it fits.
+ */
+export declare const schemaProblem: (schema: ValueSchema, value: ArgValue) => string | undefined;

package/dist/src/valueSchema.js

@@ -0,0 +1,196 @@
+import { isArgList, isArgObject } from "./messages.js";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The keywords a schema may use. */
+const KEYWORDS = [
+    "title",
+    "description",
+    "default",
+    "type",
+    "enum",
+    "const",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "items",
+    "minItems",
+    "maxItems",
+    "properties",
+    "required",
+    "additionalProperties",
+    "anyOf"
+];
+/** The types JSON Schema names. */
+const SCHEMA_TYPES = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+    "object",
+    "array"
+];
+/** Whether a keyword holds a number, when it is there: one that holds another thing would refuse nothing. */
+const areNumbers = (schema, keywords) => keywords.every((keyword) => schema[keyword] === undefined || typeof schema[keyword] === "number");
+/** Whether a pattern compiles, and repeats no repeat (`(a+)+`), the form that hangs a page on a short text. */
+const isUsablePattern = (pattern) => {
+    if (pattern === undefined)
+        return true;
+    if (typeof pattern !== "string" || /\([^)]*[+*}][^)]*\)[+*{]/.test(pattern))
+        return false;
+    try {
+        return new RegExp(pattern, "u") !== undefined;
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether a keyword holding one schema, or several, holds schemas. */
+const areNested = (value) => {
+    const { items, properties, additionalProperties, anyOf } = value;
+    return ((items === undefined || isValueSchema(items)) &&
+        (properties === undefined || (isRecord(properties) && Object.values(properties).every(isValueSchema))) &&
+        (additionalProperties === undefined ||
+            typeof additionalProperties === "boolean" ||
+            isValueSchema(additionalProperties)) &&
+        (anyOf === undefined || (Array.isArray(anyOf) && anyOf.every(isValueSchema))));
+};
+/** Whether the keywords of one level hold what they say. */
+const areLeavesRead = (value) => {
+    const { type, required } = value;
+    const types = type === undefined ? [] : [type].flat();
+    return (types.every((each) => SCHEMA_TYPES.includes(each)) &&
+        (value["enum"] === undefined || Array.isArray(value["enum"])) &&
+        (required === undefined ||
+            (Array.isArray(required) && required.every((name) => typeof name === "string"))) &&
+        areNumbers(value, ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"]) &&
+        isUsablePattern(value["pattern"]));
+};
+/**
+ * Whether a module's `schema` is one this check reads in full, at any depth: a keyword it does not know, or one holding what
+ * it cannot use, would let through what the schema seems to refuse.
+ *
+ * @param value - the module's export.
+ */
+export const isValueSchema = (value) => isRecord(value) &&
+    Object.keys(value).every((key) => KEYWORDS.includes(key)) &&
+    areLeavesRead(value) &&
+    areNested(value);
+/** Whether a value is of one of JSON Schema's types. */
+const isOfType = (type, value) => {
+    switch (type) {
+        case "string":
+        case "boolean":
+            return typeof value === type;
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return Number.isInteger(value);
+        case "null":
+            return value === null;
+        case "array":
+            return isArgList(value);
+        case "object":
+            return isArgObject(value);
+    }
+};
+/** Whether two values are the same JSON, whatever order an object writes its fields in. */
+const isSameValue = (left, right) => {
+    if (Array.isArray(left) && Array.isArray(right))
+        return left.length === right.length && left.every((each, index) => isSameValue(each, right[index]));
+    if (!isRecord(left) || !isRecord(right))
+        return left === right;
+    const names = Object.keys(left);
+    return (names.length === Object.keys(right).length &&
+        names.every((name) => Object.hasOwn(right, name) && isSameValue(left[name], right[name])));
+};
+/** What is wrong with a value's own kind: its type and the values it may be. */
+const kindProblem = (schema, value, path) => {
+    const types = schema.type === undefined ? [] : [schema.type].flat();
+    if (types.length > 0 && !types.some((type) => isOfType(type, value)))
+        return `${path} must be of type ${types.join(" or ")}`;
+    if (schema.enum !== undefined && !schema.enum.some((each) => isSameValue(each, value)))
+        return `${path} must be one of ${JSON.stringify(schema.enum)}`;
+    return schema.const !== undefined && !isSameValue(schema.const, value)
+        ? `${path} must be ${JSON.stringify(schema.const)}`
+        : undefined;
+};
+/** What is wrong with a number or a text. */
+const leafProblem = (schema, value, path) => {
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum)
+            return `${path} must be at least ${schema.minimum}`;
+        if (schema.maximum !== undefined && value > schema.maximum)
+            return `${path} must be at most ${schema.maximum}`;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    // in characters, as JSON Schema counts: an emoji is one
+    const { length } = [...value];
+    if (schema.minLength !== undefined && length < schema.minLength)
+        return `${path} must have at least ${schema.minLength} characters`;
+    if (schema.maxLength !== undefined && length > schema.maxLength)
+        return `${path} must have at most ${schema.maxLength} characters`;
+    return schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value)
+        ? `${path} must match ${schema.pattern}`
+        : undefined;
+};
+/** What is wrong with a list. */
+const listProblem = (schema, value, path) => {
+    if (schema.minItems !== undefined && value.length < schema.minItems)
+        return `${path} must have at least ${schema.minItems} items`;
+    if (schema.maxItems !== undefined && value.length > schema.maxItems)
+        return `${path} must have at most ${schema.maxItems} items`;
+    const { items } = schema;
+    if (items === undefined)
+        return undefined;
+    return value
+        .map((item, index) => problemAt(items, item, `${path}[${index}]`))
+        .find((each) => each !== undefined);
+};
+/** What is wrong with an object. */
+const objectProblem = (schema, value, path) => {
+    const missing = (schema.required ?? []).find((name) => !Object.hasOwn(value, name));
+    if (missing !== undefined)
+        return `${path} must have ${missing}`;
+    for (const [name, each] of Object.entries(value)) {
+        const fieldPath = `${path}.${name}`;
+        const declared = schema.properties !== undefined && Object.hasOwn(schema.properties, name);
+        const field = declared ? schema.properties?.[name] : schema.additionalProperties;
+        if (field === false)
+            return `${fieldPath} is not a field it takes`;
+        const problem = isRecord(field) ? problemAt(field, each, fieldPath) : undefined;
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+};
+/** What is wrong with a value, at a place in the whole. */
+const problemAt = (schema, value, path) => {
+    const problem = kindProblem(schema, value, path) ?? leafProblem(schema, value, path);
+    if (problem !== undefined)
+        return problem;
+    if (schema.anyOf !== undefined && schema.anyOf.every((each) => problemAt(each, value, path) !== undefined))
+        return `${path} fits none of its forms`;
+    if (isArgList(value))
+        return listProblem(schema, value, path);
+    return isArgObject(value) ? objectProblem(schema, value, path) : undefined;
+};
+/**
+ * What is wrong with a value, in a sentence.
+ *
+ * @param schema - the control's schema.
+ * @param value - the value.
+ * @returns the sentence; none when it fits.
+ */
+export const schemaProblem = (schema, value) => {
+    try {
+        return problemAt(schema, value, "the value");
+    }
+    catch (error) {
+        // a pattern that is no regular expression is the control's mistake: no value can be known to fit it
+        return error instanceof Error ? error.message : String(error);
+    }
+};

package/dist/src/valueShape.d.ts

@@ -0,0 +1,94 @@
+/**
+ * What a prop's value looks like when it is more than one text or number: an object's fields, a list's items, the
+ * members of a mixed union. Read from the component's types (`vite/shapeDocs.ts`) or from a story's own arg, it drives
+ * the panel's nested fields, the check on a link's values, the worst case and what agents read of a prop.
+ *
+ * @remarks
+ * A shape is plain JSON, so it crosses from the plugin to the page and reaches an agent as it is. A value that fits a
+ * shape is plain JSON too, so a link can hold it. What JSON cannot hold (a component, a function, a date) is a `named`
+ * leaf: only one of the source's `namedValues` can stand for it. `json` is the way out for what cannot be drawn as
+ * fields: any JSON value, typed by hand. This module holds what the first screen needs of a shape; what reads a value
+ * against one is `shapeValues.ts`, which loads with the first prop that has a shape. Pure.
+ *
+ * @module
+ */
+import type { ArgValue } from "./messages.ts";
+import type { NamedValues } from "./namedValues.ts";
+/** One field of an object's shape. */
+export type ShapeField = {
+    /** The field's name. */
+    readonly name: string;
+    /** What it holds. */
+    readonly shape: ValueShape;
+    /** Whether a value must give it. */
+    readonly isRequired: boolean;
+    /** Whether it may hold `null`. Left out when not. */
+    readonly isNullable?: true;
+    /** The first paragraph of its TSDoc; left out when it has none. */
+    readonly description?: string;
+};
+/** What a value looks like. */
+export type ValueShape = {
+    readonly kind: "text";
+} | {
+    readonly kind: "number";
+} | {
+    readonly kind: "boolean";
+    /** The one value it may hold, for one branch of a discriminated union. Left out when it takes both. */
+    readonly only?: boolean;
+} | {
+    /** One of these values. */
+    readonly kind: "choice";
+    /** The values, in the order of the type. */
+    readonly values: readonly (string | number)[];
+} | {
+    /** Any number of items of one shape. */
+    readonly kind: "list";
+    /** The items' shape. */
+    readonly of: ValueShape;
+} | {
+    /** A fixed number of items, each of its own shape (`[number, number]`). */
+    readonly kind: "tuple";
+    /** Each item's shape, in order. */
+    readonly items: readonly ValueShape[];
+} | {
+    /** Named fields. */
+    readonly kind: "object";
+    /** The fields, in the order of the source. */
+    readonly fields: readonly ShapeField[];
+} | {
+    /** Any names, each holding one shape (`Record<string, number>`). */
+    readonly kind: "record";
+    /** The values' shape. */
+    readonly of: ValueShape;
+} | {
+    /** One of several shapes, chosen first (`"sm" | number`). */
+    readonly kind: "union";
+    /** The shapes, in the order of the type. */
+    readonly of: readonly ValueShape[];
+} | {
+    /** What JSON cannot hold: one of the source's named values, under the type as the source writes it. */
+    readonly kind: "named";
+    /** The type, as `namedValues` lists it (`IconComponent`). */
+    readonly type: string;
+    /** Whether a plain text can be given too (a node). Left out when not. */
+    readonly canTakeText?: true;
+} | {
+    /** A moment: a `Date`, which the story receives as one (`DateArg`). */
+    readonly kind: "date";
+} | {
+    /** Any JSON: what fields cannot show. */
+    readonly kind: "json";
+} | {
+    /** What a story's own arg looks like, for an arg no type describes: read from it when it is needed. */
+    readonly kind: "like";
+    /** The story's own value. */
+    readonly value: ArgValue;
+};
+/**
+ * Whether the panel can give a shape a value at all: a required part the source names no value for leaves it no way.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values.
+ */
+export declare const canSetShape: (shape: ValueShape, namedValues: NamedValues) => boolean;