forgebook 0.4.0 → 0.4.1

package/dist/src/vite/argControlsConfig.js

@@ -0,0 +1,176 @@
+/**
+ * A catalogue's custom controls, its own and its presets', checked and merged: what the pages load and what the props
+ * docs are matched against.
+ *
+ * @remarks
+ * A preset's control runs in the catalogue's page as the catalogue's own do, so it passes the same checks: a name a story
+ * can write that no control of the panel has, and a module named as a path or a package's specifier, never an address
+ * (`https:`, `data:`) that would load code from elsewhere. A preset names its files by absolute path, as its preview: a
+ * relative path would be read from wherever the catalogue is; nor can it take every prop of a keyword type (`string`). The catalogue's
+ * registration of a name replaces a preset's, and `false` removes it; a later preset's replaces an earlier one's. The
+ * order kept is the precedence among controls that match the same prop: the catalogue's first, then the presets' in
+ * their order.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { CONTROLS } from "../storyArgTypes.js";
+/** The keys a control's option may have. */
+const OPTION_KEYS = ["module", "frame", "matches"];
+/** The keys a match may have. */
+const MATCH_KEYS = ["typeName", "propName"];
+/** The type names TypeScript writes as keywords: a preset that takes one by type alone would take most of a catalogue. */
+const KEYWORD_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "bigint",
+    "symbol",
+    "object",
+    "unknown",
+    "any",
+    "null",
+    "undefined",
+    "never",
+    "void"
+];
+/** An address with a scheme (`https:`, `data:`), which would load code from elsewhere; a Windows drive's letter is none. */
+const SCHEME = /^[A-Za-z][\w+.-]+:/;
+/** Whether a value is an object that is not a list. */
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A key of an object no version reads, when it has one.
+ *
+ * @param value - the object.
+ * @param known - its keys.
+ */
+const unknownKey = (value, known) => Object.keys(value).find((key) => !known.includes(key));
+/**
+ * One field of a match, checked: a text, or none.
+ *
+ * @param match - the match.
+ * @param key - the field.
+ * @param where - where it is written, for a problem.
+ */
+const matchField = (match, key, where) => {
+    const value = Reflect.get(match, key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value === "")
+        throw new Error(`${where}: a match's ${key} is no name`);
+    return value;
+};
+/**
+ * The matches a control's option writes, checked.
+ *
+ * @param value - its `matches`.
+ * @param where - where it is written, for a problem.
+ */
+const matchesOf = (value, where) => {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map((match) => {
+        if (!isObject(match))
+            throw new Error(`${where}: a match is an object ({ typeName } or { propName })`);
+        const key = unknownKey(match, MATCH_KEYS);
+        if (key !== undefined)
+            throw new Error(`${where}: a match has no key "${key}"; it takes typeName, propName`);
+        const typeName = matchField(match, "typeName", where);
+        const propName = matchField(match, "propName", where);
+        if (typeName === undefined && propName === undefined)
+            throw new Error(`${where}: a match names a typeName, a propName, or both`);
+        return {
+            ...(typeName === undefined ? {} : { typeName }),
+            ...(propName === undefined ? {} : { propName })
+        };
+    });
+};
+/**
+ * One control, checked and resolved; `false` removes a preset's control of its name.
+ *
+ * @param name - its name.
+ * @param value - what the list writes for it.
+ * @param where - where the list is, for a problem.
+ * @param place - places a module it names.
+ */
+const resolvedControl = (name, value, where, place) => {
+    const at = `${where}: "${name}"`;
+    if (Object.hasOwn(CONTROLS, name))
+        throw new Error(`${at} is a control of the panel already`);
+    if (!/^[A-Za-z][\w-]*$/.test(name))
+        throw new Error(`${at} is no name a control can have`);
+    if (value === false)
+        return false;
+    if (!isObject(value))
+        return { module: place(value, at), matches: [] };
+    const key = unknownKey(value, OPTION_KEYS);
+    if (key !== undefined)
+        throw new Error(`${at} has no key "${key}"; it takes ${OPTION_KEYS.join(", ")}`);
+    const frame = Reflect.get(value, "frame");
+    return {
+        module: place(Reflect.get(value, "module"), at),
+        ...(frame === undefined ? {} : { frame: place(frame, `${at}: its frame`) }),
+        matches: matchesOf(Reflect.get(value, "matches"), at)
+    };
+};
+/**
+ * A list's controls, checked and resolved, in its order.
+ *
+ * @param controls - the list.
+ * @param where - where it is, for a problem.
+ * @param place - places a module it names.
+ */
+const listed = (controls, where, place) => {
+    if (controls !== undefined && !isObject(controls))
+        throw new Error(`${where} is an object of controls by name`);
+    return Object.entries(controls ?? {}).map(([name, value]) => [
+        name,
+        resolvedControl(name, value, where, place)
+    ]);
+};
+/**
+ * The catalogue's custom controls and its presets', checked, merged, in their precedence.
+ *
+ * @param config - the configuration, its presets included.
+ * @param dir - its folder.
+ * @param paths - the path functions.
+ * @throws when a name, a module or a match cannot be used.
+ */
+export const resolvedArgControls = (config, dir, paths) => {
+    const file = resolve(dir, "forgebook.config");
+    const named = (module, where) => {
+        if (typeof module !== "string" || module === "")
+            throw new Error(`${where} names no module, as a path or a package's specifier`);
+        if (SCHEME.test(module))
+            throw new Error(`${where} names an address, not a path or a package's specifier`);
+        return module;
+    };
+    const own = listed(config.argControls, `${file}: argControls`, (module, where) => {
+        const path = named(module, where);
+        return path.startsWith(".") || paths.isAbsolute(path) ? paths.absolute(path) : path;
+    });
+    // a later preset's control replaces an earlier one's of the same name, where the first was
+    const fromPresets = new Map();
+    for (const preset of config.presets ?? []) {
+        const where = `${file}: its preset "${preset.name}": argControls`;
+        for (const [name, control] of listed(preset.argControls, where, (module, at) => {
+            const path = named(module, at);
+            if (path.startsWith("."))
+                throw new Error(`${at}: a preset names a module by absolute path or package`);
+            return paths.isAbsolute(path) ? paths.normalize(path) : path;
+        })) {
+            if (control === false)
+                throw new Error(`${where}: "${name}": only a catalogue removes a control`);
+            const keyword = control.matches.find((match) => match.propName === undefined && KEYWORD_TYPES.includes(match.typeName ?? ""));
+            if (keyword !== undefined)
+                throw new Error(`${where}: "${name}": a preset takes no "${keyword.typeName}" prop by its type alone`);
+            fromPresets.set(name, control);
+        }
+    }
+    // a removal that removes nothing is a misspelt name
+    const removing = own.find(([name, control]) => control === false && !fromPresets.has(name));
+    if (removing !== undefined)
+        throw new Error(`${file}: argControls: "${removing[0]}" is no preset's control to remove`);
+    const ownNames = new Set(own.map(([name]) => name));
+    return Object.fromEntries([...own, ...[...fromPresets].filter(([name]) => !ownNames.has(name))].flatMap(([name, control]) => (control === false ? [] : [[name, control]])));
+};

package/dist/src/vite/catalogueConfig.js

@@ -1,6 +1,7 @@
 /**
  * What Forgebook's plugin sets in Vite's configuration for a catalogue: its folder as the root, what to pre-bundle, the
- * pages as the build's inputs, the build's script names, and the dev server's reads kept to each origin.
+ * pages as the build's inputs, the build's script names, no single-page fallback, and the dev server's reads kept to
+ * each origin.
  *
  * @module
  */
@@ -68,6 +69,10 @@ export const catalogueConfig = (config, userConfig, findings = {}) => ({
                 : { output: { chunkFileNames: "assets/[hash].js", hashCharacters: "base36" } })
         }
     },
+    // the plugin serves the catalogue's pages itself, so the only page a single-page fallback could answer with is the
+    // app's own `index.html`: a story's missing image would get it, and the server would load the whole app its scripts
+    // reach, pre-bundle again what the stories never import, and reload every frame open (unless the app chose its own)
+    ...(userConfig.appType === undefined ? { appType: "mpa" } : {}),
     // Vite lets any localhost page read the server: neither origin needs another's reads, and the guards
     // would be the only wall left between the frames and the catalogue (unless the app chose its own)
     ...(config.frames.kind === "isolated" && userConfig.server?.cors === undefined

package/dist/src/vite/config.d.ts

@@ -32,6 +32,40 @@ export type ForgebookPreset = CatalogueLists & {
     readonly head?: string;
     /** The shell's look, under the catalogue's: its theme, and a style sheet by absolute path. */
     readonly shell?: ShellOptions;
+    /**
+     * Custom controls of the props panel it brings to every catalogue that lists it, by name, each module by absolute path
+     * or a package's specifier: a catalogue's registration of the same name replaces it. They run in the catalogue's page
+     * with a plugin's trust, as the catalogue's own do.
+     */
+    readonly argControls?: Readonly<Record<string, string | ArgControlOption>>;
+};
+/**
+ * Which props a custom control takes without a story naming it: each field given must hold, so `{ typeName, propName }`
+ * takes only that prop of that type.
+ */
+export type ArgControlMatch = {
+    /**
+     * The type's name as the props are read: as the source writes it (`IconComponent`), or any alias it is declared
+     * through (`type ButtonIcon = IconComponent`), without `undefined` and `null`; a union only when every member goes by it.
+     */
+    readonly typeName?: string;
+    /** The prop's name (`icon`). */
+    readonly propName?: string;
+};
+/** A custom control with more than its module: its frame module, and the props it takes on its own. */
+export type ArgControlOption = {
+    /** The module the panel draws it with, exporting `mount` and `schema`. */
+    readonly module: string;
+    /**
+     * A module of the stories' frames exporting `toStoryValue(value, argType)`, which turns the panel's JSON value into
+     * what the story receives (a name into an icon); none gives the story the JSON value.
+     */
+    readonly frame?: string;
+    /**
+     * The props it is the control of in every story that names no control for them, by type or by name; one or a list,
+     * of which any may match. A match by name wins over one by type, then the catalogue's controls over its presets'.
+     */
+    readonly matches?: ArgControlMatch | readonly ArgControlMatch[];
 };
 /** A tokens file: its path from the configuration's folder, with its theme when it is a theme's. */
 export type TokensFile = StoryTokensFile;
@@ -82,10 +116,11 @@ export type ForgebookConfig = CatalogueLists & {
     readonly tokens?: readonly TokensFile[];
     /**
      * Custom controls of the props panel, by the name a story's `argTypes` use (`{ rating: "./controls/rating.ts" }`): each a
-     * module, by path from the configuration's folder or a package's specifier, exporting `mount` and `schema`. It loads when
-     * a story names it, and runs in the shell's page with a plugin's trust.
+     * module, by path from the configuration's folder or a package's specifier, exporting `mount` and `schema`, or an
+     * `ArgControlOption` with a frame module and the props it matches. It loads when a story's panel shows it, and runs in
+     * the shell's page with a plugin's trust. A name its presets register is replaced; `false` removes theirs.
      */
-    readonly argControls?: Readonly<Record<string, string>>;
+    readonly argControls?: Readonly<Record<string, string | ArgControlOption | false>>;
     /** Its preview's path from the configuration's folder; `forgebook.preview.ts` (or `.tsx`) beside it when there. */
     readonly preview?: string;
     /** Tags for every frame's `<head>` (a font's link); none by default. */

package/dist/src/vite/configFile.d.ts

@@ -15,6 +15,7 @@ import type { ForgebookPlugin } from "../plugin.ts";
 import { type ViewSwitch } from "../switches.ts";
 import type { FrameworkAdapter } from "./adapter.ts";
 import { type ResolvedAppBuild } from "./appBuildOption.ts";
+import { type ResolvedArgControls } from "./argControlsConfig.ts";
 import type { BuildOptions, ForgebookConfig } from "./config.ts";
 import { type ResolvedFrames } from "./framesConfig.ts";
 import { type ResolvedRefs } from "./refsConfig.ts";
@@ -85,8 +86,8 @@ export type ResolvedConfig = {
     readonly tokens: readonly ResolvedTokensFile[];
     /** Whether the configuration says `tokens: []`: no system at all, so the application's own files are not read for one. */
     readonly isAppTokensOff?: boolean;
-    /** The custom controls' modules by name: a path absolute, a package's specifier as written. */
-    readonly argControls: Readonly<Record<string, string>>;
+    /** The custom controls by name, the catalogue's and its presets', in their precedence. */
+    readonly argControls: ResolvedArgControls;
     /** The folders the dev server watches for new story files, absolute. */
     readonly watch: readonly string[];
     /** The lists (widths, backgrounds, story groups…), the presets' and the catalogue's merged. */

package/dist/src/vite/configFile.js

@@ -26,10 +26,10 @@ import { catalogueSettings, playProblem } from "../catalogue.js";
 import { deviceSettingProblem } from "../deviceView.js";
 import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
 import { frameThemeCss, mergedThemes, shellThemeCss, shellThemeProblems, themeValueProblem } from "../shellTheme.js";
-import { CONTROLS } from "../storyArgTypes.js";
 import { mergedStatuses, statusesProblem } from "../storyStatuses.js";
 import { catalogueSwitches, switchesProblem } from "../switches.js";
 import { appBuildProblem, resolvedAppBuild } from "./appBuildOption.js";
+import { resolvedArgControls } from "./argControlsConfig.js";
 import { saysNoTokens, unknownKeysProblem } from "./configKeys.js";
 import { configLoadMessage } from "./configLoadError.js";
 import { framesProblem, resolvedFrames } from "./framesConfig.js";
@@ -443,7 +443,11 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
         },
         tokens,
         isAppTokensOff: saysNoTokens(config),
-        argControls: resolvedArgControls(config.argControls, dir, absolute, paths.isAbsolute),
+        argControls: resolvedArgControls(config, dir, {
+            absolute,
+            isAbsolute: paths.isAbsolute,
+            normalize: paths.normalize
+        }),
         watch: (config.watch ?? []).map(absolute),
         lists,
         hasPlayTools: hasPlayToolsIn(dir),
@@ -454,25 +458,6 @@ export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
         appBuild: resolvedAppBuild(config.appBuild)
     };
 };
-/**
- * The custom controls' modules, each checked: a name a story can write, that no control of the panel already has.
- *
- * @param controls - what the configuration writes.
- * @param dir - the configuration's folder.
- * @param absolute - a path from that folder, made absolute.
- * @param isAbsolutePath - whether a path is one already.
- * @throws when a name or a module cannot be used.
- */
-const resolvedArgControls = (controls, dir, absolute, isAbsolutePath) => Object.fromEntries(Object.entries(controls ?? {}).map(([name, module]) => {
-    const where = `${resolve(dir, "forgebook.config")}: argControls`;
-    if (Object.hasOwn(CONTROLS, name))
-        throw new Error(`${where}: "${name}" is a control of the panel already`);
-    if (!/^[A-Za-z][\w-]*$/.test(name))
-        throw new Error(`${where}: "${name}" is no name a control can have`);
-    if (typeof module !== "string" || module === "")
-        throw new Error(`${where}: "${name}" names no module, as a path or a package's specifier`);
-    return [name, module.startsWith(".") || isAbsolutePath(module) ? absolute(module) : module];
-}));
 /**
  * Loads a configuration file and resolves it.
  *

package/dist/src/vite/configKeys.js

@@ -77,7 +77,8 @@ const PRESET_KEYS = {
     languages: true,
     preview: true,
     head: true,
-    shell: true
+    shell: true,
+    argControls: true
 };
 const BUILD_KEYS = { readableNames: true };
 const APP_BUILD_KEYS = {

package/dist/src/vite/forgebookPlugin.js

@@ -53,6 +53,7 @@ import { scriptProblems } from "./scriptProblems.js";
 import { isKeptIndex } from "./storyFilesModule.js";
 import { tokensModule } from "./storylessRoutes.js";
 import { DOCS_QUERY, RENEWED_QUERIES, TEXT_QUERIES } from "./textQueries.js";
+import { withTypedControls } from "./typedControls.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** This module's folder, in the core's package: the core's own dependencies resolve from here, not the project's. */
 const PACKAGE_DIR = import.meta.dirname;
@@ -131,7 +132,8 @@ export const forgebookPlugin = (options = {}) => {
     const isServing = () => command === "serve";
     // the search's indexes, a build reading each component's docs once for its page and its index
     const search = searchIndexes({
-        extract: (storyFile) => extractor().extract(storyFile),
+        // the catalogue's controls by type are written into the docs here, so every reader of them sees the same panel
+        extract: async (storyFile) => withTypedControls(await extractor().extract(storyFile), config?.argControls ?? {}),
         isServing,
         track: (id, isPages) => (isPages ? docsModules : searchModules).add(id),
         isKept: access.isKept

package/dist/src/vite/pages.js

@@ -365,10 +365,20 @@ const argControlLines = (config) => {
         ? []
         : [
             "    argControls: {",
-            ...controls.map(([name, module]) => `      ${codeLiteral(name)}: () => import(${codeLiteral(module)}),`),
+            ...controls.map(([name, { module }]) => `      ${codeLiteral(name)}: () => import(${codeLiteral(module)}),`),
             "    },"
         ];
 };
+/**
+ * The frame's list of the custom controls' frame modules, each with the import that loads it when the shell first gives
+ * the story a value of that control; nothing for a catalogue whose controls have none.
+ *
+ * @param config - the configuration.
+ */
+const argControlFrameLines = (config) => {
+    const frames = Object.entries(config.argControls).flatMap(([name, { frame }]) => frame === undefined ? [] : [`      ${codeLiteral(name)}: () => import(${codeLiteral(frame)}),`]);
+    return frames.length === 0 ? [] : ["    argControls: {", ...frames, "    },"];
+};
 /**
  * The shell's entry: the shell mounted with the configuration's data, the logo, the sources and the code writer.
  *
@@ -482,6 +492,7 @@ export const frameEntry = (config, axe) => {
         "    lists: config.lists,",
         "    frames: config.frames,",
         ...(config.hasPlayTools ? [playToolsLoader()] : []),
+        ...argControlFrameLines(config),
         ...(frames.length === 0
             ? []
             : [

package/dist/src/vite/propDocs.js

@@ -216,6 +216,57 @@ const declaredMembers = (node) => {
     const bare = bareType(node);
     return (ts.isUnionTypeNode(bare) ? bare.types : [bare]).filter((member) => !isNothing(member));
 };
+/**
+ * The names a type node goes by: a plain reference's name as written, the name it was declared with (an import may
+ * rename it), and the names of the aliases it is declared through (`type ButtonIcon = IconComponent`); for a union, the
+ * names every member goes by, without `undefined`, `null` and `never`. A generic's reference (`ComponentType<Props>`) and a
+ * type parameter name no type of their own, so they end the walk.
+ *
+ * @param node - the type node.
+ * @param checker - the type checker, to follow a name to its declaration.
+ * @param seen - the nodes already walked, so a recursive alias ends.
+ */
+const typeNamesOf = (node, checker, seen) => {
+    const bare = bareType(node);
+    if (seen.has(bare))
+        return [];
+    const walked = new Set([...seen, bare]);
+    if (ts.isUnionTypeNode(bare))
+        return sharedNames(declaredMembers(bare), checker, walked);
+    if (!ts.isTypeReferenceNode(bare) || bare.typeArguments !== undefined)
+        return [];
+    const symbol = declaredSymbol(checker.getSymbolAtLocation(bare.typeName), checker);
+    if (symbol === undefined || symbol.flags & ts.SymbolFlags.TypeParameter)
+        return [];
+    // a default export's symbol is named `default`: its declaration keeps the name it was written with
+    const declared = ts.getNameOfDeclaration(symbol.declarations?.[0])?.getText() ?? bare.typeName.getText();
+    const alias = symbol.declarations?.find(ts.isTypeAliasDeclaration);
+    const through = alias !== undefined && !alias.typeParameters ? typeNamesOf(alias.type, checker, walked) : [];
+    return [...new Set([bare.typeName.getText(), declared, ...through])];
+};
+/**
+ * The names every one of several type nodes goes by, in the first one's order.
+ *
+ * @param nodes - the type nodes: a union's members, or a prop's declarations.
+ * @param checker - the type checker.
+ * @param seen - the nodes already walked.
+ */
+const sharedNames = (nodes, checker, seen) => {
+    const [first, ...others] = nodes.map((node) => typeNamesOf(node, checker, seen));
+    return (first ?? []).filter((name) => others.every((names) => names.includes(name)));
+};
+/**
+ * The names a prop's declared types all go by: what a custom control's `matches` reads. A branch of the props where the
+ * prop is `never` takes no value, so it names no type; a method names none.
+ *
+ * @param declared - the prop's declared types.
+ * @param checker - the program's checker.
+ */
+const writtenTypeNames = (declared, checker) => {
+    const taking = declared.filter((node) => ts.isMethodSignature(node) || declaredMembers(node).length > 0);
+    const nodes = taking.flatMap((node) => (ts.isMethodSignature(node) ? [] : [node]));
+    return nodes.length === taking.length ? sharedNames(nodes, checker, new Set()) : [];
+};
 /**
  * A prop's declared type nodes: a property's type (in a type or a class) or a method's whole signature, once per
  * declaration. A prop of props written as alternatives (`{ indicator?: never } | { indicator?: "dot" | "spinner" }`)
@@ -398,12 +449,16 @@ export const propDocs = (symbol, checker, node, reading = {}) => {
     const canTakeText = kind === "other" &&
         [type, ...variantTypes].every((each) => checker.isTypeAssignableTo(checker.getStringType(), each));
     const notes = propTypeNotes(declared, type, checker, generic);
+    const typeText = choices === undefined
+        ? (writtenText(declared, generic, checker) ?? checker.typeToString(type))
+        : choiceTypeText(choices);
+    const typeNames = writtenTypeNames(declared, checker);
     return {
         name,
         kind,
-        type: choices === undefined
-            ? (writtenText(declared, generic, checker) ?? checker.typeToString(type))
-            : choiceTypeText(choices),
+        type: typeText,
+        // only when they say more than the type's text
+        ...(typeNames.some((each) => each !== typeText) ? { typeNames } : {}),
         description: summaryOf(symbol, checker),
         isRequired: (symbol.flags & ts.SymbolFlags.Optional) === 0,
         ...(defaultValue === undefined ? {} : { defaultValue }),

package/dist/src/vite/typedControls.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The custom controls a catalogue gives props by their type or their name (a control's `matches`), written into a
+ * component's docs as the plugin serves them: the panel, the address's check and the agents then read the control from
+ * the prop, as if every story had named it. Pure.
+ *
+ * @remarks
+ * Done on the server, where the docs are made, so the shell's first load carries no matching: a prop's `customControl`
+ * is read as a story's `argTypes` control is. Only props the component has get one, so no story ever gains a prop. A
+ * story whose `argTypes` name a control for the prop keeps its own (`argTypes.ts`). Among the controls that match a prop,
+ * a match by name wins over a match by type alone, then the first in the catalogue's order.
+ *
+ * @module
+ */
+import type { PropDocs } from "../componentDocs.ts";
+import type { StoryComponentResult } from "./adapter.ts";
+import type { ResolvedArgControls } from "./argControlsConfig.ts";
+/**
+ * The control a catalogue gives a prop by its type or its name, when one does.
+ *
+ * @param prop - the prop, as its docs read it.
+ * @param controls - the catalogue's custom controls, in their precedence.
+ * @returns the control's name; none when no match fits, or for an event.
+ */
+export declare const matchedControlOf: (prop: Pick<PropDocs, "name" | "kind" | "type" | "typeNames">, controls: ResolvedArgControls) => string | undefined;
+/**
+ * A story file's component docs with the controls the catalogue gives its props; as it is when no control matches.
+ *
+ * @param result - what the framework read of the story file.
+ * @param controls - the catalogue's custom controls.
+ */
+export declare const withTypedControls: (result: StoryComponentResult, controls: ResolvedArgControls) => StoryComponentResult;

package/dist/src/vite/typedControls.js

@@ -0,0 +1,66 @@
+/**
+ * How well a match fits a prop: 2 when it names the prop, 1 when it names only its type, 0 when it does not fit.
+ *
+ * @param match - the match.
+ * @param prop - the prop.
+ */
+const fitOf = (match, prop) => {
+    const names = prop.typeNames ?? [prop.type];
+    if (match.typeName !== undefined && !names.includes(match.typeName))
+        return 0;
+    if (match.propName !== undefined)
+        return match.propName === prop.name ? 2 : 0;
+    return 1;
+};
+/**
+ * The control a catalogue gives a prop by its type or its name, when one does.
+ *
+ * @param prop - the prop, as its docs read it.
+ * @param controls - the catalogue's custom controls, in their precedence.
+ * @returns the control's name; none when no match fits, or for an event.
+ */
+export const matchedControlOf = (prop, controls) => {
+    if (prop.kind === "event")
+        return undefined;
+    let best;
+    for (const [name, control] of Object.entries(controls)) {
+        const fit = Math.max(0, ...control.matches.map((match) => fitOf(match, prop)));
+        // the first of equal fits keeps its place: the catalogue's controls come before its presets'
+        if (fit > (best?.fit ?? 0))
+            best = { name, fit };
+    }
+    return best?.name;
+};
+/**
+ * A prop with the control a catalogue gives it: the control decides what its value is, so the type's shape, text,
+ * choices and tokens no longer draw nor check it, and it is no longer a choice a matrix can take, as for a control a
+ * story names.
+ *
+ * @param prop - the prop.
+ * @param controls - the catalogue's custom controls.
+ */
+const withMatchedControl = (prop, controls) => {
+    const customControl = matchedControlOf(prop, controls);
+    if (customControl === undefined)
+        return prop;
+    const { shape: _shape, canTakeText: _canTakeText, choices: _choices, token: _token, ...rest } = prop;
+    return { ...rest, kind: "other", customControl };
+};
+/**
+ * A story file's component docs with the controls the catalogue gives its props; as it is when no control matches.
+ *
+ * @param result - what the framework read of the story file.
+ * @param controls - the catalogue's custom controls.
+ */
+export const withTypedControls = (result, controls) => {
+    // a story file whose meta names no component has no props to match
+    if (typeof result === "string" || !("file" in result))
+        return result;
+    if (!Object.values(controls).some((control) => control.matches.length > 0))
+        return result;
+    const { docs } = result;
+    return {
+        ...result,
+        docs: { ...docs, props: docs.props.map((prop) => withMatchedControl(prop, controls)) }
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgebook",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "See every component in every theme, contrast, language and width: CSF stories, one frame per story, and a props table from the components' types.",
   "keywords": [
     "react",
@@ -265,7 +265,7 @@
     "marked": "18.1.0",
     "typescript-6": "npm:typescript@6.0.3",
     "vite": "^8.3.4",
-    "@forgebook/story-format": "0.3.0"
+    "@forgebook/story-format": "0.3.1"
   },
   "peerDependencies": {
     "@testing-library/dom": "^10.4.0",