forgebook 0.1.8 → 0.2.0

package/dist/src/vite/previewRunner.js

@@ -0,0 +1,207 @@
+/**
+ * Loads a catalogue's previews on the dev server for tools, with the packages they import that only a browser can run
+ * left as placeholders, so their args and parameters are read on Node.
+ *
+ * @remarks
+ * A preview is written for a browser: it imports Storybook's docs blocks for its docs container, or a package that
+ * reads `document` while it loads. The server reads only its args, parameters and globals, which rarely come from
+ * those, but one such import would leave the whole preview out of every answer. So the previews load in a module
+ * runner of their own whose evaluator takes a package (a module Vite leaves to Node) that stops on a browser global
+ * (`document is not defined`) for a namespace of placeholders. A placeholder can be kept in a parameter (a docs
+ * container, a decorator) or called (an addon's factory in `definePreview`), and what a call made can be looked into
+ * as the framework composing the preview does; but reading a property of an export, using any placeholder as a
+ * string, a number or a list, or listing the names of the namespace throws, naming the package: a preview that uses
+ * such a package while it loads still fails to load, and is named among the answers' problems, rather than giving
+ * values a browser would not. A placeholder kept in the preview's args or parameters is left out of the answers, as a
+ * function is. A file of the catalogue's own that reads a browser global is not replaced: half run, it would leave
+ * values a browser does not have.
+ *
+ * The runner is Vite's (`createServerModuleRunner`, experimental in Vite 8), on the server environment, with its hot
+ * updates: an edit of a preview or of a file it imports is read on the next answer. One runner serves a dev server
+ * for as long as it runs, made on the first preview asked for. Story files are not loaded through it: a story that
+ * only a browser can load is a problem of its own story, which the answers name.
+ *
+ * @module
+ */
+import { createServerModuleRunner } from "vite";
+import { ESModulesEvaluator } from "vite/module-runner";
+/** The message of a script that read a global its runtime does not have: `document is not defined`. */
+const UNDEFINED_GLOBAL = /^(\S+) is not defined$/;
+/**
+ * The globals a browser has and Node does not, that a package reads while it loads: a missing one of these names a
+ * package for browsers, where another missing name is a mistake to report.
+ */
+const BROWSER_GLOBALS = new Set([
+    "window",
+    "document",
+    "navigator",
+    "location",
+    "history",
+    "self",
+    "localStorage",
+    "sessionStorage",
+    "matchMedia",
+    "getComputedStyle",
+    "requestAnimationFrame",
+    "cancelAnimationFrame",
+    "customElements",
+    "HTMLElement",
+    "Element",
+    "Node",
+    "CSS",
+    "CSSStyleSheet",
+    "IntersectionObserver",
+    "ResizeObserver",
+    "MutationObserver"
+]);
+/**
+ * Whether an error is a script reading a global that a browser has and Node does not.
+ *
+ * @param error - what a module threw while it loaded.
+ */
+export const isBrowserGlobalError = (error) => {
+    if (!(error instanceof ReferenceError))
+        return false;
+    const name = UNDEFINED_GLOBAL.exec(error.message)?.[1];
+    return name !== undefined && BROWSER_GLOBALS.has(name);
+};
+/**
+ * What a placeholder or a namespace answers as absent: what `JSON.stringify` and `await` look for, so a parameter that
+ * holds one is written without it and a namespace is not taken for a promise.
+ */
+const ABSENT_KEYS = new Set(["toJSON", "then"]);
+/** What a placeholder answers as any function does. */
+const FUNCTION_KEYS = new Set(["name", "length", "prototype", "constructor"]);
+/**
+ * What a script reads of a value to use it as data: to turn it into a string or a number (`${value}`, `value + 1`), and
+ * to iterate it (`[...value]`, `for of`, `for await`). A placeholder has no such value, so reading these throws.
+ */
+const VALUE_SYMBOLS = new Set([
+    Symbol.toPrimitive,
+    Symbol.iterator,
+    Symbol.asyncIterator
+]);
+/**
+ * Why a placeholder cannot be used.
+ *
+ * @param name - the export, or what was done with it.
+ * @param file - the package's module.
+ * @param reason - why the module did not load.
+ */
+const unavailable = (name, file, reason) => new Error(`${name} of ${file} cannot be used on the server: it needs a browser (${reason})`);
+/**
+ * How many calls and reads a chain may take from an export: far more than a framework's composition needs (Storybook's
+ * takes three, `docs().default.parameters`), and a bound on a loop that walks a placeholder (`while (node.parent)`),
+ * which would otherwise never end and hold the dev server with it.
+ */
+const MAX_STEPS = 16;
+/**
+ * An export of a package that did not load on Node, or what a call of one made: a function that can be kept and called
+ * (what it returns is another), and throws when it is constructed or used as data (made a string or a number, or
+ * iterated).
+ *
+ * @remarks
+ * A property read differs by origin. Of an export, it throws: the preview's own code reads a value of the package
+ * (`themes.light`), which a browser would give and a placeholder cannot. Of what a call made, it is a placeholder too,
+ * the same one each time it is read: what a factory returns is handed whole to the framework that composes the
+ * preview, which looks into it for what it contributes (Storybook's `definePreview` reads
+ * `addon.default?.parameters ?? addon.parameters` of every addon in `addons: [docs()]`), keeps what it finds, or merges
+ * it with `Object.assign`, which finds no names on a placeholder. So the composition runs to its end, its values from
+ * the package being placeholders, while a string, a number or a list taken from them still throws.
+ *
+ * @param name - the export, and what was done with it (`docs().default`).
+ * @param file - the package's module.
+ * @param reason - why the module did not load.
+ * @param steps - the calls and reads from the export to this placeholder: none for the export itself.
+ */
+const placeholder = (name, file, reason, steps) => {
+    const read = new Map();
+    // the next placeholder of the chain, or why it goes no further
+    const next = (step) => {
+        if (steps >= MAX_STEPS)
+            throw unavailable(step, file, reason);
+        return placeholder(step, file, reason, steps + 1);
+    };
+    // a class, not an arrow function: `new` reaches the trap of a constructor only, and its message names the package
+    const target = class {
+    };
+    const proxy = new Proxy(target, {
+        apply: () => next(`${name}()`),
+        construct: () => {
+            throw unavailable(`new ${name}`, file, reason);
+        },
+        get: (self, key, receiver) => {
+            if (typeof key === "symbol") {
+                if (VALUE_SYMBOLS.has(key))
+                    throw unavailable(name, file, reason);
+                return Reflect.get(self, key, receiver);
+            }
+            if (FUNCTION_KEYS.has(key))
+                return Reflect.get(self, key, receiver);
+            if (ABSENT_KEYS.has(key))
+                return undefined;
+            if (steps === 0)
+                throw unavailable(`${name}.${key}`, file, reason);
+            if (!read.has(key))
+                read.set(key, next(`${name}.${key}`));
+            return read.get(key);
+        }
+    });
+    // the class's prototype leads back to the placeholder, not to a constructor that would make a plain object
+    target.prototype.constructor = proxy;
+    return proxy;
+};
+/**
+ * The namespace of a package that did not load on Node: every name it is asked for is a placeholder, so an import of
+ * any of them resolves; listing its names throws, since it has none to give.
+ *
+ * @param file - the package's module.
+ * @param reason - why it did not load.
+ */
+export const browserOnlyNamespace = (file, reason) => new Proxy(Object.create(null), {
+    has: (_target, key) => typeof key === "string" && !ABSENT_KEYS.has(key),
+    get: (_target, key) => typeof key === "string" && !ABSENT_KEYS.has(key) ? placeholder(key, file, reason, 0) : undefined,
+    ownKeys: () => {
+        throw unavailable("The names", file, reason);
+    }
+});
+/**
+ * An evaluator that runs every module as Vite's does, and takes a package that stops on a browser global for a
+ * namespace of placeholders.
+ *
+ * @param base - the evaluator it wraps.
+ */
+export const browserTolerantEvaluator = (base = new ESModulesEvaluator()) => ({
+    ...(base.startOffset === undefined ? {} : { startOffset: base.startOffset }),
+    runInlinedModule: (...run) => base.runInlinedModule(...run),
+    runExternalModule: async (file) => {
+        try {
+            return await base.runExternalModule(file);
+        }
+        catch (error) {
+            if (!isBrowserGlobalError(error))
+                throw error;
+            return browserOnlyNamespace(file, error.message);
+        }
+    }
+});
+/** The runner of each dev server's server environment, made on its first preview. */
+const runners = new WeakMap();
+/**
+ * Loads a preview on the server, through the runner of the dev server's server environment.
+ *
+ * @param environment - the dev server's server environment.
+ * @param file - the preview's path.
+ * @returns the preview's module.
+ */
+export const loadPreview = (environment, file) => {
+    let runner = runners.get(environment);
+    if (runner === undefined) {
+        runner = createServerModuleRunner(environment, {
+            hmr: { logger: false },
+            evaluator: browserTolerantEvaluator()
+        });
+        runners.set(environment, runner);
+    }
+    return runner.import(file);
+};

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

@@ -0,0 +1,60 @@
+import ts from "typescript-6";
+import type { PropDocs } from "../componentDocs.ts";
+/**
+ * A symbol, through an import to what it names.
+ *
+ * @param symbol - the symbol at the name.
+ * @param checker - the program's checker.
+ */
+export declare const declaredSymbol: (symbol: ts.Symbol | undefined, checker: ts.TypeChecker) => ts.Symbol | undefined;
+/**
+ * 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
+ * `Omit`'s keys are a union), so a program kept between reads changed it from one read to the next.
+ *
+ * @param props - the props.
+ * @param componentFolder - the folder of the file that declares the component.
+ */
+export declare const declarationOrder: (props: readonly ts.Symbol[], componentFolder: string) => ts.Symbol[];
+/** Whether a symbol is declared outside the package (a DOM attribute from React's types). */
+export declare const isForeign: (symbol: ts.Symbol) => boolean;
+/**
+ * What a prop takes, when it is not its symbol's own type: a framework whose props are wrapped (an Angular signal input,
+ * `input<string>()`, takes the `string` its `InputSignal<string>` holds) says what a binding sets.
+ */
+export type BoundType = {
+    /** The type a binding sets. */
+    readonly type: ts.Type;
+    /**
+     * The type node that writes it (`input<"md" | "sm">()`'s argument), for its text and a choice's order; none when the
+     * source writes none.
+     */
+    readonly typeNode: ts.TypeNode | undefined;
+};
+/** How a framework's props differ from a plain function's, for `propDocs`. */
+export type PropReading = {
+    /** What the prop takes, when it is not the symbol's own type; none reads the symbol's. */
+    readonly taken?: BoundType | undefined;
+    /**
+     * What an event's name is, for a framework that names its callback props otherwise (Svelte's `onclick`); `on` and a
+     * capital by default.
+     */
+    readonly eventName?: RegExp | undefined;
+};
+/**
+ * One prop's docs.
+ *
+ * @param symbol - the prop: its name, its TSDoc, whether it is optional.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ * @param reading - how the framework's props differ from a plain function's; none for a plain prop.
+ */
+export declare const propDocs: (symbol: ts.Symbol, checker: ts.TypeChecker, node: ts.Node, reading?: PropReading) => PropDocs;
+/**
+ * A component's parts: the keys of its `classNames`, `styles` and `refs` maps (the reach-every-part rule).
+ *
+ * @param propsType - the type of its props, all of them; none when it takes none.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ */
+export declare const partsOf: (propsType: ts.Type | undefined, checker: ts.TypeChecker, node: ts.Node) => readonly string[];

package/dist/src/vite/propDocs.js

@@ -0,0 +1,387 @@
+/**
+ * One prop of a component read from its types and TSDoc: its kind (the panel's group and control), its type as the source
+ * writes it, a choice's values in the source's order, an event's signature. Shared by the frameworks' docs modules: what a
+ * prop is does not depend on how a component takes it.
+ *
+ * @remarks
+ * The checker's own order and text follow the types it happened to meet first, which a program kept between reads
+ * changes from one read to the next, so what the source writes is preferred wherever it says the same.
+ *
+ * @module
+ */
+import { dirname } from "node:path";
+import ts from "typescript-6";
+import { summaryOf, tagOf } from "./docsProgram.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;
+};
+/** A literal value an expression writes (`"md"`, `3`, `-1`), or none for anything else. */
+const literalOfExpression = (expression) => {
+    if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))
+        return expression.text;
+    if (ts.isNumericLiteral(expression))
+        return Number(expression.text);
+    if (ts.isPrefixUnaryExpression(expression) &&
+        expression.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(expression.operand)) {
+        return -Number(expression.operand.text);
+    }
+    return undefined;
+};
+/**
+ * A symbol, through an import to what it names.
+ *
+ * @param symbol - the symbol at the name.
+ * @param checker - the program's checker.
+ */
+export const declaredSymbol = (symbol, checker) => symbol !== undefined && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+/** The value a literal type node writes (`"md"`, `3`, `-1`), or none for another literal (`true`, `null`). */
+const literalTypeValue = (node) => {
+    const literal = node.literal;
+    const value = ts.isLiteralExpression(literal) || ts.isPrefixUnaryExpression(literal)
+        ? literalOfExpression(literal)
+        : undefined;
+    return value === undefined ? [] : [value];
+};
+/** The values a tuple query writes (`(typeof SIZES)[number]` with `SIZES = ["md", "sm"] as const`), in its order. */
+const tupleValues = (node, checker) => {
+    let object = node.objectType;
+    while (ts.isParenthesizedTypeNode(object))
+        object = object.type;
+    if (!ts.isTypeQueryNode(object))
+        return [];
+    const variable = declaredSymbol(checker.getSymbolAtLocation(object.exprName), checker)?.valueDeclaration;
+    if (variable === undefined || !ts.isVariableDeclaration(variable) || variable.initializer === undefined)
+        return [];
+    const list = unwrapped(variable.initializer);
+    if (!ts.isArrayLiteralExpression(list))
+        return [];
+    return list.elements.flatMap((element) => {
+        const value = literalOfExpression(element);
+        return value === undefined ? [] : [value];
+    });
+};
+/** The keys an object query writes (`keyof typeof TEXT_STYLES`), in the order the object writes them. */
+const keyValues = (node, checker) => {
+    if (node.operator !== ts.SyntaxKind.KeyOfKeyword || !ts.isTypeQueryNode(node.type))
+        return [];
+    const variable = declaredSymbol(checker.getSymbolAtLocation(node.type.exprName), checker)?.valueDeclaration;
+    if (variable === undefined || !ts.isVariableDeclaration(variable) || variable.initializer === undefined)
+        return [];
+    const object = unwrapped(variable.initializer);
+    if (!ts.isObjectLiteralExpression(object))
+        return [];
+    return object.properties.flatMap((property) => {
+        const name = property.name;
+        return name !== undefined && (ts.isIdentifier(name) || ts.isStringLiteral(name)) ? [name.text] : [];
+    });
+};
+/**
+ * The values an indexed type writes: a tuple's members (`(typeof SIZES)[number]`), or another type's prop as that
+ * type declares it (`PopoverProps["side"]`).
+ *
+ * @param node - the indexed type.
+ * @param checker - the type checker.
+ * @param seen - the nodes already walked.
+ */
+const accessedValues = (node, checker, seen) => {
+    const index = node.indexType;
+    if (!ts.isLiteralTypeNode(index) || !ts.isStringLiteral(index.literal))
+        return tupleValues(node, checker);
+    const prop = checker.getPropertyOfType(checker.getTypeFromTypeNode(node.objectType), index.literal.text);
+    return (prop?.declarations ?? []).flatMap((declaration) => ts.isPropertySignature(declaration) && declaration.type !== undefined
+        ? writtenLiterals(declaration.type, checker, seen)
+        : []);
+};
+/**
+ * The literal values a type node writes, in the order it writes them: through unions, aliases and a tuple's members.
+ *
+ * @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 writtenLiterals = (node, checker, seen) => {
+    if (seen.has(node))
+        return [];
+    seen.add(node);
+    if (ts.isParenthesizedTypeNode(node))
+        return writtenLiterals(node.type, checker, seen);
+    if (ts.isUnionTypeNode(node))
+        return node.types.flatMap((member) => writtenLiterals(member, checker, seen));
+    if (ts.isLiteralTypeNode(node))
+        return literalTypeValue(node);
+    if (ts.isIndexedAccessTypeNode(node))
+        return accessedValues(node, checker, seen);
+    if (ts.isTypeOperatorNode(node))
+        return keyValues(node, checker);
+    if (!ts.isTypeReferenceNode(node))
+        return [];
+    // a generic's arguments first (`Exclude<TableVariant, "changes">`): the values it keeps come from them
+    const fromArguments = (node.typeArguments ?? []).flatMap((argument) => writtenLiterals(argument, checker, seen));
+    const alias = declaredSymbol(checker.getSymbolAtLocation(node.typeName), checker)?.declarations?.find(ts.isTypeAliasDeclaration);
+    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.
+ *
+ * @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.
+ */
+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;
+    };
+    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(" | ");
+/**
+ * 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
+ * `Omit`'s keys are a union), so a program kept between reads changed it from one read to the next.
+ *
+ * @param props - the props.
+ * @param componentFolder - the folder of the file that declares the component.
+ */
+export const declarationOrder = (props, componentFolder) => {
+    const keyOf = (prop) => {
+        const [declaration] = prop.declarations ?? [];
+        if (declaration === undefined)
+            return [2, "", 0];
+        const file = declaration.getSourceFile().fileName;
+        return [dirname(file) === componentFolder ? 0 : 1, file, declaration.getStart()];
+    };
+    return [...props].sort((left, right) => {
+        const [leftOwn, leftFile, leftAt] = keyOf(left);
+        const [rightOwn, rightFile, rightAt] = keyOf(right);
+        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();
+/**
+ * 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).
+ */
+const isNothing = (node) => node.kind === ts.SyntaxKind.UndefinedKeyword ||
+    node.kind === ts.SyntaxKind.NeverKeyword ||
+    (ts.isLiteralTypeNode(node) && node.literal.kind === ts.SyntaxKind.NullKeyword);
+/** A type node without its parentheses. */
+const bareType = (node) => ts.isParenthesizedTypeNode(node) ? bareType(node.type) : node;
+/**
+ * A prop's declared type without what adds nothing (`undefined`, `null`, `never`): the members of a written union, or
+ * the node itself.
+ *
+ * @param node - the prop's declared type.
+ */
+const declaredMembers = (node) => {
+    const bare = bareType(node);
+    return (ts.isUnionTypeNode(bare) ? bare.types : [bare]).filter((member) => !isNothing(member));
+};
+/**
+ * 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" }`)
+ * has one per branch.
+ *
+ * @param symbol - the prop.
+ */
+const declaredTypesOf = (symbol) => (symbol.declarations ?? []).flatMap((declaration) => {
+    if (ts.isMethodSignature(declaration))
+        return [declaration];
+    return (ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration)) &&
+        declaration.type !== undefined
+        ? [declaration.type]
+        : [];
+});
+/**
+ * A prop's type as the source writes it (`ReactNode`, `Ref<HTMLElement>`), without `undefined` and `null`: the
+ * checker's own text expands it and orders a union's members by the order it met the types in, which a program kept
+ * between reads changes from one read to the next.
+ *
+ * @param declaredTypes - the prop's declared type nodes.
+ * @returns the text, or none when the prop writes no type (the caller falls back to the checker's).
+ */
+const writtenTypeText = (declaredTypes) => {
+    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)}`];
+    });
+    // each branch's members once, in the order the branches write them
+    const unique = [...new Set(texts)];
+    return unique.length === 0 ? undefined : unique.join(" | ");
+};
+/**
+ * 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.
+ * @returns the signature, or none when the source writes none in place (a named handler type).
+ */
+const writtenSignature = (declaredTypes) => {
+    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)
+        })),
+        returns: fn.type === undefined ? "void" : nodeText(fn.type)
+    };
+};
+/** An event's signature. */
+const signatureOf = (type, checker, node) => {
+    const [signature] = type.getCallSignatures();
+    if (signature === undefined)
+        return undefined;
+    return {
+        parameters: signature.parameters.map((parameter) => ({
+            name: parameter.getName(),
+            type: checker.typeToString(checker.getTypeOfSymbolAtLocation(parameter, 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/"));
+/**
+ * Whether a prop's type is a plain object, whose members can be listed one by one as values of their own: not a union,
+ * a function, a class's instance, an array or a tuple.
+ */
+const isMemberedObject = (type, checker) => (type.flags & ts.TypeFlags.Object) !== 0 &&
+    !type.isUnion() &&
+    !type.isClass() &&
+    type.getCallSignatures().length === 0 &&
+    type.getConstructSignatures().length === 0 &&
+    !checker.isArrayType(type) &&
+    !checker.isTupleType(type);
+/**
+ * The members of a prop's object type, when the package declares and documents them (`texts?: FileFinderTexts`), in
+ * the order the source declares them. The members the type takes from outside the package (an element's attributes)
+ * are left out, as the props are, and a type none of whose members has TSDoc lists nothing a reader cannot read from
+ * its name. One level only: a member's own members are not read, so a recursive type ends and the docs stay small.
+ *
+ * @param type - the prop's type, without `undefined`.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ * @returns the members, or none when the type is not such an object.
+ */
+const membersOf = (type, checker, node) => {
+    if (!isMemberedObject(type, checker))
+        return undefined;
+    const own = type.getProperties().filter((member) => !isForeign(member));
+    const [firstDeclaration] = type.getSymbol()?.declarations ?? own[0]?.declarations ?? [];
+    const folder = firstDeclaration === undefined ? "" : dirname(firstDeclaration.getSourceFile().fileName);
+    const members = declarationOrder(own, folder).map((member) => {
+        const defaultValue = tagOf(member, checker, "defaultValue");
+        const memberType = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(member, node));
+        return {
+            name: member.getName(),
+            type: writtenTypeText(declaredTypesOf(member)) ?? checker.typeToString(memberType),
+            description: summaryOf(member, checker),
+            ...(defaultValue === undefined ? {} : { defaultValue }),
+            isRequired: (member.flags & ts.SymbolFlags.Optional) === 0
+        };
+    });
+    return members.some((member) => member.description !== "") ? members : undefined;
+};
+/**
+ * A prop's place in the reference: the group its TSDoc names (`@group`, as TypeDoc reads it, so a library documented
+ * for both writes it once), and the members of its type when it is a documented object. Each only when it has one.
+ *
+ * @param symbol - the prop.
+ * @param kind - its kind: only a prop of kind `other` can be an object.
+ * @param type - its type, without `undefined`.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ */
+const groupingOf = (symbol, kind, type, checker, node) => {
+    const group = tagOf(symbol, checker, "group");
+    const members = kind === "other" ? membersOf(type, checker, node) : undefined;
+    return {
+        ...(group === undefined || group === "" ? {} : { group }),
+        ...(members === undefined ? {} : { members })
+    };
+};
+/**
+ * One prop's docs.
+ *
+ * @param symbol - the prop: its name, its TSDoc, whether it is optional.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ * @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 takenNodes = taken?.typeNode === undefined ? [] : [taken.typeNode];
+    const declared = taken === undefined ? declaredTypesOf(symbol) : takenNodes;
+    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;
+    // 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);
+    return {
+        name,
+        kind,
+        type: choices === undefined
+            ? (writtenTypeText(declared) ?? checker.typeToString(type))
+            : choiceTypeText(choices),
+        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)
+    };
+};
+/** The props whose keys are the component's parts. */
+const PART_MAPS = ["classNames", "styles", "refs"];
+/**
+ * A component's parts: the keys of its `classNames`, `styles` and `refs` maps (the reach-every-part rule).
+ *
+ * @param propsType - the type of its props, all of them; none when it takes none.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ */
+export const partsOf = (propsType, checker, node) => [
+    ...new Set((propsType?.getProperties() ?? [])
+        .filter((prop) => PART_MAPS.includes(prop.getName()))
+        .flatMap((prop) => checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(prop, node)).getProperties())
+        .map((part) => part.getName()))
+];