forgebook 0.3.3 → 0.4.0

package/dist/src/storyTags.d.ts

@@ -0,0 +1,29 @@
+import type { StoryTree } from "./storyTree.ts";
+/** One tag the catalogue's stories hold. */
+export type CatalogueTag = {
+    /** The tag. */
+    readonly tag: string;
+    /** How many listed stories hold it. */
+    readonly stories: number;
+};
+/**
+ * Whether a story's tags pass a filter.
+ *
+ * @param tags - the story's tags.
+ * @param filter - the filter's tags, each `name` or `!name`; none keeps every story.
+ */
+export declare const passesTags: (tags: readonly string[], filter: readonly string[]) => boolean;
+/**
+ * The tags a person can filter a catalogue by, by name, with the listed stories each one holds.
+ *
+ * @param tree - the tree.
+ */
+export declare const catalogueTags: (tree: StoryTree) => readonly CatalogueTag[];
+/**
+ * The tree the sidebar lists under a filter: only the stories that pass, and what holds them. Pages keep opening from
+ * the whole tree: an address still shows a story the filter leaves out.
+ *
+ * @param tree - the whole tree.
+ * @param filter - the filter's tags, each `name` or `!name`; none gives the tree as it is.
+ */
+export declare const taggedTree: (tree: StoryTree, filter: readonly string[]) => StoryTree;

package/dist/src/storyTags.js

@@ -0,0 +1,85 @@
+/**
+ * The tag filter: which stories a list of tags keeps, for the sidebar's tree and the agents' documents alike.
+ *
+ * @remarks
+ * Written as CSF writes a tag: `beta` asks for it, `!beta` asks to leave it out. A story stays when it holds any tag
+ * asked for and none left out, as Storybook's filter reads its choices, so ticking one more tag widens the list. A docs
+ * page holds no tags, so it reads as a story with none. Pure.
+ *
+ * @module
+ */
+import { isFilterTag } from "./storyTagNames.js";
+/**
+ * Whether a story's tags pass a filter.
+ *
+ * @param tags - the story's tags.
+ * @param filter - the filter's tags, each `name` or `!name`; none keeps every story.
+ */
+export const passesTags = (tags, filter) => {
+    const asked = filter.filter((tag) => !tag.startsWith("!"));
+    return (filter.every((tag) => !tag.startsWith("!") || !tags.includes(tag.slice(1))) &&
+        (asked.length === 0 || asked.some((tag) => tags.includes(tag))));
+};
+/** Every component of a source, whatever group it sits in. */
+const componentsOf = (source) => source.families.flatMap((family) => family.groups.flatMap((group) => group.components));
+/**
+ * The tags a person can filter a catalogue by, by name, with the listed stories each one holds.
+ *
+ * @param tree - the tree.
+ */
+export const catalogueTags = (tree) => {
+    const counts = new Map();
+    const stories = tree.sources.flatMap((source) => componentsOf(source).flatMap((component) => component.stories));
+    for (const tag of stories.flatMap((story) => story.tags.filter(isFilterTag))) {
+        counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+    return [...counts]
+        .map(([tag, count]) => ({ tag, stories: count }))
+        .sort((one, other) => one.tag.localeCompare(other.tag));
+};
+/**
+ * A group with what the filter keeps: its components with only the stories that pass, and the aliases of the components
+ * that stay; an alias is opened to its component's page, so it follows that component.
+ *
+ * @param group - the group.
+ * @param filter - the filter's tags.
+ * @param keptTitles - the titles of the source's components that stay.
+ */
+const groupOf = (group, filter, keptTitles) => ({
+    ...group,
+    components: group.components.flatMap((component) => {
+        const stories = component.stories.filter((story) => passesTags(story.tags, filter));
+        return stories.length === 0 ? [] : [{ ...component, stories }];
+    }),
+    aliases: group.aliases.filter((alias) => keptTitles.has(alias.title))
+});
+/**
+ * The tree the sidebar lists under a filter: only the stories that pass, and what holds them. Pages keep opening from
+ * the whole tree: an address still shows a story the filter leaves out.
+ *
+ * @param tree - the whole tree.
+ * @param filter - the filter's tags, each `name` or `!name`; none gives the tree as it is.
+ */
+export const taggedTree = (tree, filter) => {
+    if (filter.length === 0)
+        return tree;
+    const hasAsked = filter.some((tag) => !tag.startsWith("!"));
+    return {
+        ...tree,
+        sources: tree.sources.map((source) => {
+            const keptTitles = new Set(componentsOf(source)
+                .filter((component) => component.stories.some((story) => passesTags(story.tags, filter)))
+                .map((component) => component.title));
+            return {
+                ...source,
+                pages: hasAsked ? [] : source.pages,
+                families: source.families.flatMap((family) => {
+                    const groups = family.groups
+                        .map((group) => groupOf(group, filter, keptTitles))
+                        .filter((group) => group.components.length > 0 || group.aliases.length > 0);
+                    return groups.length === 0 ? [] : [{ ...family, groups }];
+                })
+            };
+        })
+    };
+};

package/dist/src/storyTree.d.ts

@@ -97,6 +97,11 @@ export type TreeComponent = {
      * none, for the catalogue's.
      */
     readonly requiredFirst: RequiredFirst | undefined;
+    /**
+     * Its first file's meta's tags, the previews' under them: what is said of the component as a whole, its status
+     * among them (`storyStatuses.ts`), whatever a story adds or takes away. Empty when none.
+     */
+    readonly tags: readonly string[];
 };
 /** A group's entry for a component that lives elsewhere and is listed here too (the meta's `alsoIn`). */
 export type TreeAlias = {
@@ -239,6 +244,14 @@ export declare const testedStoryLocations: (tree: StoryTree) => StoryLocation[];
  * @returns its place, or `undefined` when no story has this id.
  */
 export declare const findStory: (tree: StoryTree, id: string) => StoryLocation | undefined;
+/**
+ * The story an address names: its `story`, or the one of a link written for Storybook. Either is only a name: it opens
+ * a page by `findStory`, or says that no such story is there.
+ *
+ * @param params - the address's query.
+ * @returns the story's id; none when the address names none.
+ */
+export declare const storyOfAddress: (params: URLSearchParams) => string | null;
 /** Where a component sits: its source, family and group. */
 export type ComponentLocation = Omit<StoryLocation, "story">;
 /**

package/dist/src/storyTree.js

@@ -126,7 +126,8 @@ const startedComponent = (source, file, entry, titlesById) => {
 const placedComponents = (source, problems) => {
     const byTitle = new Map();
     const titlesById = new Map();
-    const index = sourceFiles(source).index;
+    const { index, problems: unread = [] } = sourceFiles(source);
+    problems.push(...unread);
     // sorted, so a component's files, and so its stories, its docs and a clash's winner, never depend on the groups' order
     for (const file of Object.keys(index).sort()) {
         const entry = index[file];
@@ -249,7 +250,8 @@ const sourceFamilies = (source, problems) => {
             design: componentDesign(component),
             // its first file's, as its docs are
             propGroups: component.files[0]?.entry.propGroups ?? [],
-            requiredFirst: component.files[0]?.entry.requiredFirst
+            requiredFirst: component.files[0]?.entry.requiredFirst,
+            tags: component.files[0]?.entry.tags ?? []
         });
     }
     placeAliases(source, placed, families, problems);
@@ -299,7 +301,13 @@ export const storyTree = (sources) => {
     const shown = tree.filter((source) => source.families.length > 0 || source.pages.length > 0);
     return {
         sources: shown,
-        problems: [...problems, ...pageProblems(shown, new Set(storyIds(shown)), new Set(componentIds(shown)))]
+        // a script that does not parse is named by every group a dev server serves: once is enough
+        problems: [
+            ...new Set([
+                ...problems,
+                ...pageProblems(shown, new Set(storyIds(shown)), new Set(componentIds(shown)))
+            ])
+        ]
     };
 };
 /**
@@ -341,8 +349,20 @@ export const testedStoryLocations = (tree) => storyLocations(tree).filter((locat
 export const findStory = (tree, id) => {
     const locations = storyLocations(tree);
     return (locations.find((location) => location.story.id === id) ??
-        locations.find(({ source, component, story }) => formerStoryId(source.id, component.title, story.exportName) === id));
+        locations.find(({ source, component, story }) => formerStoryId(source.id, component.title, story.exportName) === id) ??
+        // a Storybook link names no source: the first in the catalogue's order that has a story of that id
+        locations.find(({ source, story }) => story.id === `${source.id}:${id}`));
 };
+/** Storybook's address of a story: `?path=/story/<id>`. */
+const STORYBOOK_STORY_PATH = /^\/story\/([^/]+)$/;
+/**
+ * The story an address names: its `story`, or the one of a link written for Storybook. Either is only a name: it opens
+ * a page by `findStory`, or says that no such story is there.
+ *
+ * @param params - the address's query.
+ * @returns the story's id; none when the address names none.
+ */
+export const storyOfAddress = (params) => params.get("story") ?? STORYBOOK_STORY_PATH.exec(params.get("path") ?? "")?.[1] ?? null;
 /**
  * Every component of the tree with its place.
  *

package/dist/src/storybookArgs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Storybook's form of an address's `args`, read as Storybook's `parseArgsParam` reads it, and its values typed for the
+ * props that receive them. Loaded only for a link in that form (`addressArgsParam.ts`). Pure.
+ *
+ * @remarks
+ * `name:value` pairs split by `;`, a list as `tags[0]:a;tags[1]:b`, `tags[]:a;tags[]:b` or `tags:a;tags:b`, and the marked
+ * values `!true`, `!false`, `!null`, `!hex(ff0000)`, `!rgba(1,2,3,0.5)`, `!hsl(…)`, `!date(…)`. Its unmarked values are
+ * only text, whatever they look like: whether `5` is a number and `007` a text depends on the prop, which the story
+ * declares later, so they stay text here and the check types them, keeping what Storybook's own reading loses (its `007`
+ * becomes `7`). Storybook leaves out any text outside a few characters as unsafe; here every value meets the same check as
+ * a JSON one (`addressArgs.ts`), so non-ASCII text is read.
+ *
+ * What cannot be held is named as unread: an object (`style.color:red`), a list with a hole (`tags[1]:b`, which patches a
+ * list the story owns), `!undefined`, a date that is none.
+ *
+ * @module
+ */
+import type { ArgsParamRead } from "./addressArgsParam.ts";
+/**
+ * Storybook's form, read.
+ *
+ * @param param - the parameter.
+ */
+export declare const readStorybookArgs: (param: string) => ArgsParamRead;

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;