forgebook 0.3.3 → 0.4.1

package/dist/src/vite/projectPostcss.js

@@ -0,0 +1,250 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * A project's PostCSS, as its own build runs it on every style sheet: Tailwind CSS (`@tailwindcss/postcss`, or
+ * `tailwindcss` before 4), Autoprefixer or any plugin its configuration names.
+ *
+ * @remarks
+ * A catalogue's style sheets go through Lightning CSS (the forced states are a rewrite of it), which leaves PostCSS's
+ * configuration unread: what this module makes runs first, so Lightning CSS receives what the app's build would have
+ * produced. A configuration is a file exporting `{ plugins }`, the plugins an object of names and options (`false` turns
+ * one off) or a list, as PostCSS's loader reads it. Loading one runs the project's code, as its own build does, and
+ * nothing loads until the first style sheet asks. The project's folders are searched up to its repository's root, where
+ * a workspace keeps the one its packages share. PostCSS itself is the project's, or Vite's own: the catalogue adds none.
+ *
+ * @module
+ */
+import { existsSync, globSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { inlineCssImports } from "./cssImports.js";
+/** The names of a PostCSS configuration, in the order they are read. */
+const CONFIG_FILES = [
+    ".postcssrc.json",
+    ".postcssrc",
+    "postcss.config.json",
+    "postcss.config.js",
+    "postcss.config.mjs",
+    "postcss.config.cjs",
+    "postcss.config.ts",
+    "postcss.config.mts",
+    "postcss.config.cts",
+    ".postcssrc.js",
+    ".postcssrc.cjs",
+    ".postcssrc.mjs",
+    ".postcssrc.ts"
+];
+/** What marks a repository's root: a project's search for a configuration stops there. */
+const ROOT_MARKS = [".git", "pnpm-workspace.yaml"];
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a value is PostCSS's function. */
+const isPostCss = (value) => typeof value === "function";
+/**
+ * The files PostCSS's plugins said they read: each `dependency`, and each file of a `dir-dependency`'s glob.
+ *
+ * @param messages - the messages of PostCSS's result.
+ */
+export const watchedFiles = (messages) => messages.flatMap((message) => {
+    if (!isRecord(message))
+        return [];
+    if (message["type"] === "dependency" && typeof message["file"] === "string")
+        return [message["file"]];
+    if (message["type"] !== "dir-dependency" || typeof message["dir"] !== "string")
+        return [];
+    const { dir } = message;
+    const glob = typeof message["glob"] === "string" ? message["glob"] : "**/*";
+    return globSync(glob, { cwd: dir, exclude: ["**/node_modules/**"] }).map((file) => resolve(dir, file));
+});
+/** The configuration in `package.json`'s `postcss`, or none. */
+const packageConfig = (dir) => {
+    const file = join(dir, "package.json");
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const manifest = JSON.parse(readFileSync(file, "utf8"));
+        return isRecord(manifest) ? manifest["postcss"] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Where a project's PostCSS configuration is, or none: in its folder, else in the ones above it, up to its repository's
+ * root.
+ *
+ * @param dir - the project's folder.
+ */
+export const postcssConfigPlace = (dir) => {
+    let current = resolve(dir);
+    while (true) {
+        const file = CONFIG_FILES.map((name) => join(current, name)).find((path) => existsSync(path));
+        if (file !== undefined)
+            return { kind: "file", file };
+        const config = packageConfig(current);
+        if (config !== undefined)
+            return { kind: "package", file: join(current, "package.json"), config };
+        const parent = dirname(current);
+        const isLast = current === homedir() || ROOT_MARKS.some((mark) => existsSync(join(current, mark)));
+        if (parent === current || isLast)
+            return undefined;
+        current = parent;
+    }
+};
+/**
+ * The project's PostCSS configuration file, or none.
+ *
+ * @param dir - the project's folder.
+ */
+export const postcssConfigFile = (dir) => postcssConfigPlace(dir)?.file;
+/**
+ * The entries of a configuration's `plugins`: each plugin (a name, or a plugin already made) with its options.
+ *
+ * @param plugins - an object of names and options, or a list of names, `[name, options]` pairs and plugins.
+ */
+const pluginEntries = (plugins) => {
+    if (isRecord(plugins))
+        return Object.entries(plugins);
+    if (!Array.isArray(plugins))
+        return [];
+    return plugins.map((plugin) => Array.isArray(plugin) ? [plugin[0], plugin[1]] : [plugin, undefined]);
+};
+/**
+ * A plugin made from its package: its factory called with its options (none for `true` or nothing).
+ *
+ * @param module - the package, loaded.
+ * @param options - the plugin's options.
+ */
+const madePlugin = (module, options) => {
+    const factory = isRecord(module) && "default" in module ? module["default"] : module;
+    if (typeof factory !== "function")
+        return factory;
+    return Reflect.apply(factory, undefined, options === undefined || options === true ? [] : [options]);
+};
+/**
+ * The plugins a configuration names, each loaded from the project and given its options; one set to `false` is off.
+ *
+ * @param plugins - the configuration's `plugins`: an object of names and options, or a list.
+ * @param load - loads a plugin's package by name.
+ */
+export const configuredPlugins = async (plugins, load) => {
+    const loaded = [];
+    for (const [plugin, options] of pluginEntries(plugins)) {
+        if (options === false)
+            continue;
+        loaded.push(typeof plugin === "string" ? madePlugin(await load(plugin), options) : plugin);
+    }
+    return loaded;
+};
+/**
+ * A module loaded as Node loads it, from the first of the places that has it.
+ *
+ * @param dirs - the folders to resolve it from, in order.
+ * @param name - the package.
+ */
+const moduleFrom = async (dirs, name) => {
+    let failure;
+    for (const dir of dirs) {
+        try {
+            return await import(__rewriteRelativeImportExtension(pathToFileURL(createRequire(join(dir, "package.json")).resolve(name)).href));
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    throw failure;
+};
+/**
+ * A configuration file, loaded.
+ *
+ * @param file - its file.
+ */
+const loadConfig = async (file) => {
+    if (file.endsWith(".json") || file.endsWith(".postcssrc"))
+        return JSON.parse(readFileSync(file, "utf8"));
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    return isRecord(module) && "default" in module ? module["default"] : module;
+};
+/**
+ * The folder of a package a project has, to resolve what it brings from there; none when it has none.
+ *
+ * @param dir - the project's folder.
+ * @param name - the package.
+ */
+const packageFolder = (dir, name) => {
+    try {
+        return dirname(createRequire(join(dir, "package.json")).resolve(`${name}/package.json`));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The folder of the Vite this module runs on, whose PostCSS a project without its own uses. */
+const viteFolder = () => packageFolder(import.meta.dirname, "vite");
+/** The `plugins` of a configuration, read from where it is. */
+const pluginsOf = async (place) => {
+    if (place === undefined)
+        return undefined;
+    const loaded = place.kind === "package" ? place.config : await loadConfig(place.file);
+    // PostCSS's loader calls a configuration that is a function, with what it runs for
+    const config = typeof loaded === "function"
+        ? await Reflect.apply(loaded, undefined, [{ cwd: dirname(place.file), env: "development" }])
+        : loaded;
+    return isRecord(config) ? config["plugins"] : undefined;
+};
+/**
+ * A project's PostCSS configuration that could not be loaded, which is a different thing from a sheet it refuses: every
+ * sheet would fail alike, so a catalogue goes on without it and says so once.
+ */
+export class PostcssConfigError extends Error {
+}
+/**
+ * The project's PostCSS, ready to run: its configuration and plugins loaded on the first style sheet.
+ *
+ * @param dir - the project's folder.
+ * @param options - where else to look, and plugins already made.
+ * @returns the runner, or none for a project without a PostCSS configuration.
+ */
+export const projectPostcss = (dir, options = {}) => {
+    const place = options.plugins === undefined ? postcssConfigPlace(dir) : undefined;
+    if (options.plugins === undefined && place === undefined)
+        return undefined;
+    let processor;
+    const ready = async () => {
+        const brought = options.bringsPostcss === undefined ? undefined : packageFolder(dir, options.bringsPostcss);
+        const searched = [
+            dir,
+            ...(place === undefined ? [] : [dirname(place.file)]),
+            ...(brought === undefined ? [] : [brought])
+        ];
+        const plugins = options.plugins ??
+            (await configuredPlugins(await pluginsOf(place), (name) => moduleFrom(searched, name)));
+        const vite = viteFolder();
+        const module = await moduleFrom([...searched, ...(vite === undefined ? [] : [vite])], "postcss");
+        const postcss = isRecord(module) && "default" in module ? module["default"] : module;
+        if (!isPostCss(postcss))
+            throw new Error(`${place?.file ?? dir} names plugins, and PostCSS could not be loaded to run them`);
+        return postcss(plugins);
+    };
+    return async (css, path) => {
+        processor ??= ready().catch((error) => {
+            // read again on the next sheet: the configuration may be saved fixed while the server runs
+            processor = undefined;
+            throw new PostcssConfigError(error instanceof Error ? error.message : String(error));
+        });
+        const { css: inlined, files } = inlineCssImports(css, path);
+        const result = await (await processor).process(inlined, { from: path, to: path });
+        return {
+            css: result.css,
+            messages: [...result.messages, ...files.map((file) => ({ type: "dependency", file }))]
+        };
+    };
+};

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

@@ -1,5 +1,6 @@
 import ts from "typescript-6";
 import type { PropDocs } from "../componentDocs.ts";
+import { type Bindings } from "./typeParameters.ts";
 /**
  * A symbol, through an import to what it names.
  *
@@ -40,6 +41,17 @@ export type PropReading = {
      * capital by default.
      */
     readonly eventName?: RegExp | undefined;
+    /**
+     * The same prop as the other variants of a union of props declare it (`selected?: Date` beside `selected?: Date[]`):
+     * their written types join its own. When their types differ, what only one of them would say (an event's signature,
+     * a value's shape, an object's members) is left out, and its kind is `other` unless all share one.
+     */
+    readonly variants?: readonly ts.Symbol[] | undefined;
+    /**
+     * What the props type's type parameters stand for in the component (`typeParameters.ts`), so a type parameter left
+     * open is shown by the component's constraint; none reads each by its own.
+     */
+    readonly bindings?: Bindings | undefined;
 };
 /**
  * One prop's docs.

package/dist/src/vite/propDocs.js

@@ -12,18 +12,11 @@
 import { dirname } from "node:path";
 import ts from "typescript-6";
 import { summaryOf, tagOf } from "./docsProgram.js";
+import { literalValues, typeAndKind } from "./propKind.js";
+import { propTypeNotes } from "./propTypeNotes.js";
+import { shapeOfProp } from "./shapeDocs.js";
 import { unwrapped } from "./storyMeta.js";
-/** An event: a function prop named `on` and a capital (React's `onPress`). */
-const EVENT_NAME = /^on[A-Z]/;
-/** Whether a type is a union of string or number literals (a choice). */
-const literalValues = (type) => {
-    if (!type.isUnion())
-        return undefined;
-    const values = type.types.map((member) => member.isStringLiteral() || member.isNumberLiteral() ? member.value : undefined);
-    return values.every((value) => value !== undefined)
-        ? values.filter((value) => value !== undefined)
-        : undefined;
-};
+import { genericFreeText, usesTypeParameter } from "./typeParameters.js";
 /** A literal value an expression writes (`"md"`, `3`, `-1`), or none for anything else. */
 const literalOfExpression = (expression) => {
     if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))
@@ -131,25 +124,48 @@ const writtenLiterals = (node, checker, seen) => {
     return [...fromArguments, ...(alias === undefined ? [] : writtenLiterals(alias.type, checker, seen))];
 };
 /**
- * A choice's values in the order the source writes them: the checker's order follows the order it happened to meet
- * the types in, which a program kept between reads changes from one read to the next.
+ * What puts a choice's values in the order the source writes them: the checker's order follows the order it happened to
+ * meet the types in, which a program kept between reads changes from one read to the next.
+ *
+ * @remarks
+ * A prop's shape asks for the order of every union inside it, and a library's unions can hold hundreds of values (an
+ * icon's name): the declared values are read once per prop, on the first ask, and each value's place is looked up, not
+ * searched for.
  *
- * @param values - the values, in the checker's order.
  * @param declared - the prop's declared type nodes.
  * @param checker - the type checker.
- * @returns the values, those the source writes in its order first, any other after them in the checker's order.
+ * @returns the sorter: given values in the checker's order, those the source writes in its order first, any other
+ * after them in the checker's order.
  */
-const writtenOrder = (values, declared, checker) => {
-    const seen = new Set();
-    const written = declared.flatMap((node) => ts.isMethodSignature(node) ? [] : writtenLiterals(node, checker, seen));
-    const rank = (value) => {
-        const index = written.indexOf(value);
-        return index === -1 ? written.length : index;
+const writtenOrderOf = (declared, checker) => {
+    let places;
+    let unwritten = 0;
+    return (values) => {
+        if (places === undefined) {
+            const seen = new Set();
+            const written = declared.flatMap((node) => ts.isMethodSignature(node) ? [] : writtenLiterals(node, checker, seen));
+            places = new Map();
+            unwritten = written.length;
+            // a value written twice keeps its first place, as a search from the start would find it
+            for (const [index, value] of written.entries())
+                if (!places.has(value))
+                    places.set(value, index);
+        }
+        const known = places;
+        const rank = (value) => known.get(value) ?? unwritten;
+        return [...values].sort((left, right) => rank(left) - rank(right));
     };
-    return [...values].sort((left, right) => rank(left) - rank(right));
 };
 /** A choice's type as TypeScript writes it, its members in the given order (`"md" | "sm"`). */
 const choiceTypeText = (values) => values.map((value) => (typeof value === "string" ? JSON.stringify(value) : String(value))).join(" | ");
+/**
+ * Declarations by file and position: a prop several variants declare comes with them in the order the checker met
+ * the variants, which a program kept between reads changes.
+ *
+ * @param declarations - the declarations.
+ */
+const byPosition = (declarations) => [...declarations].sort((left, right) => left.getSourceFile().fileName.localeCompare(right.getSourceFile().fileName) ||
+    left.getStart() - right.getStart());
 /**
  * The props in the order the source declares them: those declared in the component's own folder first, then the
  * ones it takes from elsewhere, each by file and position. The checker's order follows the types it met first (an
@@ -160,7 +176,7 @@ const choiceTypeText = (values) => values.map((value) => (typeof value === "stri
  */
 export const declarationOrder = (props, componentFolder) => {
     const keyOf = (prop) => {
-        const [declaration] = prop.declarations ?? [];
+        const [declaration] = byPosition(prop.declarations ?? []);
         if (declaration === undefined)
             return [2, "", 0];
         const file = declaration.getSourceFile().fileName;
@@ -172,8 +188,15 @@ export const declarationOrder = (props, componentFolder) => {
         return leftOwn - rightOwn || leftFile.localeCompare(rightFile) || leftAt - rightAt;
     });
 };
-/** A type node's text as the source writes it, on one line. */
-const nodeText = (node) => node.getText().replace(/\s+/g, " ").trim();
+/**
+ * A type node's text as the source writes it, on one line; given a checker, each generic type parameter it uses
+ * replaced by what it is shown as (`typeParameters.ts`).
+ */
+const nodeText = (node, generic) => (generic === undefined ? node.getText() : genericFreeText(node, generic))
+    // an inline object's TSDoc is the docs' to read, not part of its type
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\s+/g, " ")
+    .trim();
 /**
  * Whether a type node adds nothing a prop can take: `undefined` and `null` (left out as the checker's `NonNullable`
  * did) and `never` (a branch of the props where the prop is not allowed).
@@ -193,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" }`)
@@ -200,7 +274,7 @@ const declaredMembers = (node) => {
  *
  * @param symbol - the prop.
  */
-const declaredTypesOf = (symbol) => (symbol.declarations ?? []).flatMap((declaration) => {
+const declaredTypesOf = (symbol) => byPosition(symbol.declarations ?? []).flatMap((declaration) => {
     if (ts.isMethodSignature(declaration))
         return [declaration];
     return (ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration)) &&
@@ -214,36 +288,51 @@ const declaredTypesOf = (symbol) => (symbol.declarations ?? []).flatMap((declara
  * between reads changes from one read to the next.
  *
  * @param declaredTypes - the prop's declared type nodes.
+ * @param generic - the checker and the bindings when the prop's type is still generic, to replace the type parameters
+ * its text uses; none to write it as it is.
  * @returns the text, or none when the prop writes no type (the caller falls back to the checker's).
  */
-const writtenTypeText = (declaredTypes) => {
+const writtenTypeText = (declaredTypes, generic) => {
+    const text = (node) => nodeText(node, generic);
     const texts = declaredTypes.flatMap((declared) => {
         if (!ts.isMethodSignature(declared))
-            return declaredMembers(declared).map(nodeText);
-        const parameters = declared.parameters.map(nodeText).join(", ");
-        return [`(${parameters}) => ${declared.type === undefined ? "void" : nodeText(declared.type)}`];
+            return declaredMembers(declared).map(text);
+        const parameters = declared.parameters.map(text).join(", ");
+        return [`(${parameters}) => ${declared.type === undefined ? "void" : text(declared.type)}`];
     });
     // each branch's members once, in the order the branches write them
     const unique = [...new Set(texts)];
     return unique.length === 0 ? undefined : unique.join(" | ");
 };
+/**
+ * A prop's type as the source writes it, or none for the checker's: a text naming a type parameter the component
+ * instantiates (`value: TValue` in `BaseProps<string>`) says less than the checker's `string`.
+ *
+ * @param declared - the prop's declared types.
+ * @param generic - the checker and the bindings when the prop's type is still generic.
+ * @param checker - the program's checker.
+ */
+const writtenText = (declared, generic, checker) => generic === undefined && usesTypeParameter(declared, checker)
+    ? undefined
+    : writtenTypeText(declared, generic);
 /**
  * An event's signature as the source writes it: a function type among the prop's declared members, or a method.
  *
  * @param declaredTypes - the event prop's declared type nodes.
+ * @param generic - the checker and the bindings when the event's type is still generic, as `writtenTypeText` takes them.
  * @returns the signature, or none when the source writes none in place (a named handler type).
  */
-const writtenSignature = (declaredTypes) => {
+const writtenSignature = (declaredTypes, generic) => {
     const nodes = declaredTypes.flatMap((declared) => ts.isMethodSignature(declared) ? [declared] : declaredMembers(declared));
     const fn = nodes.find((node) => ts.isMethodSignature(node) || ts.isFunctionTypeNode(node));
     if (fn === undefined)
         return undefined;
     return {
         parameters: fn.parameters.map((parameter) => ({
-            name: nodeText(parameter.name),
-            type: parameter.type === undefined ? "unknown" : nodeText(parameter.type)
+            name: nodeText(parameter.name, undefined),
+            type: parameter.type === undefined ? "unknown" : nodeText(parameter.type, generic)
         })),
-        returns: fn.type === undefined ? "void" : nodeText(fn.type)
+        returns: fn.type === undefined ? "void" : nodeText(fn.type, generic)
     };
 };
 /** An event's signature. */
@@ -259,20 +348,6 @@ const signatureOf = (type, checker, node) => {
         returns: checker.typeToString(signature.getReturnType())
     };
 };
-/** A prop's kind, from its name and its type without `undefined`. */
-const kindOf = (name, type, eventName) => {
-    if (eventName.test(name) && type.getCallSignatures().length > 0)
-        return "event";
-    if (type.flags & ts.TypeFlags.Boolean || type.flags & ts.TypeFlags.BooleanLiteral)
-        return "toggle";
-    if (literalValues(type) !== undefined)
-        return "choice";
-    if (type.flags & ts.TypeFlags.String)
-        return "text";
-    if (type.flags & ts.TypeFlags.Number)
-        return "number";
-    return "other";
-};
 /** Whether a symbol is declared outside the package (a DOM attribute from React's types). */
 export const isForeign = (symbol) => (symbol.declarations ?? []).every((declaration) => declaration.getSourceFile().fileName.includes("/node_modules/"));
 /**
@@ -334,6 +409,22 @@ const groupingOf = (symbol, kind, type, checker, node) => {
         ...(members === undefined ? {} : { members })
     };
 };
+/**
+ * A choice's values across the variants' types that declare it, each once, in the order the source writes them.
+ *
+ * @param kind - the prop's kind: only a choice has values.
+ * @param types - its type in each variant, its own first.
+ * @param declared - its declared types, for their order.
+ * @param checker - the program's checker.
+ */
+const choicesOf = (kind, types, declared, checker) => {
+    if (kind !== "choice")
+        return undefined;
+    const lists = types.map(literalValues);
+    return lists.every((list) => list !== undefined)
+        ? writtenOrderOf(declared, checker)([...new Set(lists.flat())])
+        : undefined;
+};
 /**
  * One prop's docs.
  *
@@ -343,31 +434,67 @@ const groupingOf = (symbol, kind, type, checker, node) => {
  * @param reading - how the framework's props differ from a plain function's; none for a plain prop.
  */
 export const propDocs = (symbol, checker, node, reading = {}) => {
-    const { taken, eventName = EVENT_NAME } = reading;
-    const type = checker.getNonNullableType(taken?.type ?? checker.getTypeOfSymbolAtLocation(symbol, node));
+    const { taken, variants = [] } = reading;
     const takenNodes = taken?.typeNode === undefined ? [] : [taken.typeNode];
-    const declared = taken === undefined ? declaredTypesOf(symbol) : takenNodes;
+    const declared = taken === undefined ? [symbol, ...variants].flatMap(declaredTypesOf) : takenNodes;
+    const { type, variantTypes, isMixed, kind, generic } = typeAndKind(symbol, reading, checker, node);
     const name = symbol.getName();
-    const kind = kindOf(name, type, eventName);
     const defaultValue = tagOf(symbol, checker, "defaultValue");
-    const checkerChoices = kind === "choice" ? literalValues(type) : undefined;
-    const choices = checkerChoices === undefined ? undefined : writtenOrder(checkerChoices, declared, checker);
-    const signature = kind === "event" ? (writtenSignature(declared) ?? signatureOf(type, checker, node)) : undefined;
+    const choices = choicesOf(kind, [type, ...variantTypes], declared, checker);
+    // what one variant's type says of its values is not true of the others'
+    const signature = kind === "event" && !isMixed
+        ? (writtenSignature(declared, generic) ?? signatureOf(type, checker, node))
+        : undefined;
     // a node takes a text: the panel can set it as one, which covers labels, titles and children
-    const canTakeText = kind === "other" && checker.isTypeAssignableTo(checker.getStringType(), type);
+    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
-            ? (writtenTypeText(declared) ?? 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 }),
         ...(choices === undefined ? {} : { choices }),
         ...(signature === undefined ? {} : { signature }),
         ...(canTakeText ? { canTakeText } : {}),
-        ...groupingOf(symbol, kind, type, checker, node)
+        ...(isMixed
+            ? {}
+            : {
+                ...editingOf(symbol, { kind, type, canTakeText, declared, checker, node }),
+                ...groupingOf(symbol, kind, type, checker, node)
+            }),
+        ...(notes.length === 0 ? {} : { notes })
+    };
+};
+/**
+ * How a prop's value is edited, beyond its kind: what it looks like, and the tokens its TSDoc asks for.
+ *
+ * @param symbol - the prop.
+ * @param prop - what is known of it.
+ */
+const editingOf = (symbol, prop) => {
+    const { kind, type, canTakeText, declared, checker, node } = prop;
+    const shape = kind === "other"
+        ? shapeOfProp(type, canTakeText, {
+            checker,
+            node,
+            order: writtenOrderOf(declared, checker),
+            typeText: (member) => writtenTypeText(declaredTypesOf(member)),
+            description: (member) => summaryOf(member, checker)
+        })
+        : undefined;
+    const token = tagOf(symbol, checker, "token");
+    return {
+        ...(shape === undefined ? {} : { shape }),
+        ...(token === undefined || token === "" ? {} : { token })
     };
 };
 /** The props whose keys are the component's parts. */