forgebook 0.1.8 → 0.3.0

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()))
+];

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

@@ -0,0 +1,42 @@
+import type { DocBlock } from "../docPages.ts";
+import type { SearchSection } from "../searchIndex.ts";
+import type { DocsResult } from "./docsExtractor.ts";
+import type { PackJson } from "./packedModule.ts";
+import { type IsFileKept } from "./storyFilesModule.ts";
+/**
+ * HTML as stretches of documentation, one per heading that carries an anchor.
+ *
+ * @param html - the HTML.
+ * @returns the stretches, those with neither a heading nor a text left out.
+ */
+export declare const htmlSections: (html: string) => SearchSection[];
+/**
+ * A docs page's blocks as stretches of documentation, one per heading: a code block belongs to the heading above it.
+ * A live story or an API table adds no text: what they show is found under its own name.
+ *
+ * @param blocks - the page's blocks.
+ */
+export declare const blockSections: (blocks: readonly DocBlock[]) => SearchSection[];
+/**
+ * A group of story files' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param watch - adds a file whose edit renews the module.
+ * @param extract - reads a story file's component.
+ * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
+ * a static build leaves them out.
+ * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
+ * few visits read.
+ */
+export declare const storySearchModule: (root: string, patterns: readonly string[], watch: (file: string) => void, extract: (storyFile: string) => Promise<DocsResult>, isServing: boolean, pack: PackJson, isKept?: IsFileKept) => Promise<string>;
+/**
+ * A group of docs pages' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param watch - adds a file whose edit renews the module.
+ * @param pack - writes the index's JSON as the module's value.
+ * @param isKept - whether a listed page may be read; every one by default.
+ */
+export declare const pagesSearchModule: (root: string, patterns: readonly string[], watch: (file: string) => void, pack: PackJson, isKept?: IsFileKept) => string;

package/dist/src/vite/searchModule.js

@@ -0,0 +1,213 @@
+/**
+ * The modules that answer a group's search index: what the search reads that the tree does not hold, built at build time
+ * and loaded by the page on the first search, so nobody who never searches pays for it.
+ *
+ * @remarks
+ * A docs page's and a component's text come from the HTML the pages themselves are drawn from, so a heading's anchor here
+ * is the one on the page by construction, and whatever a page renders is what is searched. Props come from the docs the
+ * page reads too. Each stretch of text is kept whole, so a sentence is found and shown as written: it weighs little
+ * next to the code, and repeats well under compression.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { componentPage } from "./componentPage.js";
+import { compiledDocPage } from "./docPageMarkdown.js";
+import { indexedDocPages } from "./docPagesModule.js";
+import { EVERY_FILE, indexedStoryFiles } from "./storyFilesModule.js";
+/** A heading of the pages' HTML: its anchor, and what is inside it. */
+const HEADING = /<h[1-6] id="doc-([^"]*)"[^>]*>([\s\S]*?)<\/h[1-6]>/g;
+/** A tag: `>` inside a quoted attribute does not end it. */
+const TAG = /<\/?([a-z][a-z0-9]*)(?:"[^"]*"|'[^']*'|[^'">])*>/gi;
+/** The tags inside a line of text: taking one out joins what it wrote apart, as coloured code is. */
+const INLINE_TAG = /^(a|abbr|b|code|del|em|i|kbd|mark|s|small|span|strong|sub|sup|u)$/i;
+/** The entities the Markdown renderer writes, and the space a page writes by hand; `&amp;` comes last. */
+const ENTITIES = [
+    ["&lt;", "<"],
+    ["&gt;", ">"],
+    ["&quot;", '"'],
+    ["&nbsp;", " "],
+    ["&amp;", "&"]
+];
+/** HTML's text: its tags out, and what a comment or a raw `<style>` or `<script>` holds, which nobody reads. */
+const plainText = (html) => {
+    const words = html
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(TAG, (_tag, name) => (INLINE_TAG.test(name) ? "" : " "))
+        .replace(/\s+/g, " ")
+        .replace(/ ([.,;:!?)])/g, "$1")
+        .trim();
+    const numbered = words.replace(/&#(\d+);/g, (_entity, code) => String.fromCodePoint(Number(code)));
+    return ENTITIES.reduce((text, [entity, character]) => text.replaceAll(entity, character), numbered);
+};
+/**
+ * HTML as stretches of documentation, one per heading that carries an anchor.
+ *
+ * @param html - the HTML.
+ * @returns the stretches, those with neither a heading nor a text left out.
+ */
+export const htmlSections = (html) => {
+    const sections = [];
+    let reached = 0;
+    let open = {};
+    const close = (end) => {
+        const text = plainText(html.slice(reached, end));
+        if (text !== "" || open.heading !== undefined)
+            sections.push({ ...open, text });
+    };
+    for (const heading of html.matchAll(HEADING)) {
+        close(heading.index);
+        reached = heading.index + heading[0].length;
+        open = { anchor: heading[1] ?? "", heading: plainText(heading[2] ?? "") };
+    }
+    close(html.length);
+    return sections;
+};
+/**
+ * A text added to the stretch it follows: a page's text goes on after a code block or a live story under the same
+ * heading.
+ *
+ * @param sections - the stretches so far; the last one changes.
+ * @param text - the text.
+ */
+const continueSection = (sections, text) => {
+    const last = sections.pop();
+    if (last === undefined)
+        sections.push({ text });
+    else
+        sections.push({ ...last, text: `${last.text} ${text}`.trim() });
+};
+/**
+ * A docs page's blocks as stretches of documentation, one per heading: a code block belongs to the heading above it.
+ * A live story or an API table adds no text: what they show is found under its own name.
+ *
+ * @param blocks - the page's blocks.
+ */
+export const blockSections = (blocks) => {
+    const sections = [];
+    for (const block of blocks) {
+        if (block.kind === "code")
+            continueSection(sections, block.text.replace(/\s+/g, " ").trim());
+        if (block.kind !== "text")
+            continue;
+        const [first, ...rest] = htmlSections(block.html);
+        if (first?.heading === undefined && first !== undefined)
+            continueSection(sections, first.text);
+        else if (first !== undefined)
+            sections.push(first);
+        sections.push(...rest);
+    }
+    return sections;
+};
+/** Everything that is not an empty text, as one text. */
+const joinedText = (texts) => [...new Set(texts.filter((text) => text !== undefined && text !== ""))].join(" ");
+/** What a component's docs say of it, the rule of when to use it included. */
+const leadOf = ({ summary, description, guidance }) => joinedText([
+    summary,
+    description,
+    ...(guidance?.useWhen ?? []),
+    ...(guidance?.avoidWhen ?? []),
+    guidance?.deprecated
+]);
+/** A list of a component's props as the index holds them. */
+const propsOf = (props, part) => props.map(({ name, description, kind }) => ({
+    name,
+    text: description,
+    ...(part === undefined ? {} : { part }),
+    ...(kind === "event" ? { isEvent: true } : {})
+}));
+/**
+ * What the page lists of a component, in the same terms: a hook's or a function's parameters, else its props, and its
+ * parts with theirs.
+ *
+ * @param docs - the component's docs.
+ * @param isLogic - whether its stories are about logic.
+ */
+const componentProps = (docs, isLogic) => {
+    const isCall = isLogic && docs.signature !== undefined;
+    // the page draws no reference at all for a component with no props of its own, its parts' included
+    if (!isCall && docs.props.length === 0)
+        return [];
+    return [
+        ...(isCall
+            ? (docs.signature?.parameters ?? []).map(({ name, description }) => ({ name, text: description }))
+            : propsOf(docs.props, undefined)),
+        ...docs.subcomponents.flatMap((subcomponent) => [
+            { name: subcomponent.name, text: subcomponent.description },
+            ...propsOf(subcomponent.props, subcomponent.name)
+        ])
+    ];
+};
+/** The fields of a component's entry that say something, so an empty one weighs nothing. */
+const componentEntry = (docs, isLogic, sections) => {
+    const lead = docs === undefined ? "" : leadOf(docs);
+    const props = docs === undefined ? [] : componentProps(docs, isLogic);
+    return {
+        ...(lead === "" ? {} : { lead }),
+        ...(props.length === 0 ? {} : { props }),
+        ...(sections.length === 0 ? {} : { sections })
+    };
+};
+/** Whether a story file's stories are all about logic: the page then documents its call, not its props. */
+const isLogicFile = ({ index }) => index.stories.length > 0 && index.stories.every((story) => story.isLogic ?? index.isLogic ?? false);
+/** Whether what a framework read is a component's docs. */
+const isComponent = (docs) => docs.name !== null;
+/**
+ * A component's entry and, when its docs cannot be read, why: its documentation file is searched either way.
+ *
+ * @param file - the story file.
+ * @param read - what the framework read of its component.
+ * @param watch - adds a file whose edit renews the module.
+ */
+const entryOf = (file, read, watch) => {
+    const page = componentPage(file.file);
+    if (page !== undefined)
+        watch(page.file);
+    const sections = page === undefined ? [] : htmlSections(page.html);
+    if (typeof read === "string")
+        return { entry: componentEntry(undefined, false, sections), problem: `${file.key}: ${read}` };
+    if ("sources" in read)
+        for (const source of read.sources)
+            watch(source);
+    const docs = isComponent(read.docs) ? read.docs : undefined;
+    return { entry: componentEntry(docs, isLogicFile(file), sections) };
+};
+/**
+ * A group of story files' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param watch - adds a file whose edit renews the module.
+ * @param extract - reads a story file's component.
+ * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
+ * a static build leaves them out.
+ * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
+ * few visits read.
+ */
+export const storySearchModule = async (root, patterns, watch, extract, isServing, pack, isKept = EVERY_FILE) => {
+    const files = indexedStoryFiles(root, patterns, watch, undefined, isKept);
+    const entries = await Promise.all(files.map(async (file) => ({ file, ...entryOf(file, await extract(file.file), watch) })));
+    const problems = entries.flatMap(({ problem }) => problem ?? []);
+    const index = {
+        components: Object.fromEntries(entries.filter(({ entry }) => Object.keys(entry).length > 0).map(({ file, entry }) => [file.key, entry])),
+        ...(problems.length === 0 || !isServing ? {} : { problems })
+    };
+    return `export default ${pack(JSON.stringify(index))};`;
+};
+/**
+ * A group of docs pages' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param watch - adds a file whose edit renews the module.
+ * @param pack - writes the index's JSON as the module's value.
+ * @param isKept - whether a listed page may be read; every one by default.
+ */
+export const pagesSearchModule = (root, patterns, watch, pack, isKept = EVERY_FILE) => {
+    const pages = indexedDocPages(root, patterns, watch, [], isKept).map(({ key, file }) => [
+        key,
+        blockSections(compiledDocPage(file, readFileSync(file, "utf8")).blocks)
+    ]);
+    return `export default ${pack(JSON.stringify({ pages: Object.fromEntries(pages) }))};`;
+};

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

@@ -0,0 +1,7 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+/**
+ * What a query finds across the catalogue.
+ *
+ * @param context - what the routes read.
+ */
+export declare const searchAnswer: ({ tree, params, pages, view, loaded }: RouteContext) => Promise<AgentAnswer>;