forgebook 0.1.8 → 0.2.0

package/dist/src/vite/sourceTokens.js

@@ -0,0 +1,164 @@
+/**
+ * What the module of a package's source declares, read without running it: its id and its tokens files; and tokens files
+ * read from disk, for the catalogue's answers and for `forgebook docs`.
+ *
+ * @remarks
+ * A source's module imports the stories' index, its texts and whatever its named values need, and only a catalogue's
+ * bundler answers those imports, so running it would let a broken story take the tokens down, and `forgebook docs` has
+ * no bundler at all. The text is enough when `export const source` is an object written plainly. A source built by code
+ * gives no id, and a `tokens` key inside it is a problem, named: its tokens would otherwise vanish in silence.
+ *
+ * A module that cannot be read says nothing either way, so it is `unread`, apart from `problems`: a tool shows it, but
+ * only tokens known to be declared stop a check, or every catalogue would fail on a source mid-edit that has none.
+ *
+ * A source's paths stay inside its package. A dependency writes them and the answers travel, so a path leading out would
+ * read files the dev server's `server.fs` never serves.
+ *
+ * @module
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parseSync } from "vite";
+import { readTokens } from "./designTokens.js";
+import { propertyValue, unwrapped } from "./indexFields.js";
+/** What to do about tokens the module's text does not give. */
+const NOT_PLAIN = "tokens are read without running the module: write them as a list of strings or `{ file, mode }` in `export const source = { … }`";
+/** What a top-level `export const source = …` holds, if the statement is one. */
+const sourceValue = (statement) => {
+    if (statement.type !== "ExportNamedDeclaration" || statement.declaration?.type !== "VariableDeclaration")
+        return undefined;
+    for (const declarator of statement.declaration.declarations) {
+        if (declarator.id.type === "Identifier" && declarator.id.name === "source" && declarator.init !== null)
+            return unwrapped(declarator.init);
+    }
+    return undefined;
+};
+/** Whether a syntax tree holds a `tokens` key: how a source built by code still shows it means tokens. */
+const holdsTokensKey = (node) => {
+    if (Array.isArray(node))
+        return node.some(holdsTokensKey);
+    if (typeof node !== "object" || node === null)
+        return false;
+    const isKey = "type" in node &&
+        node.type === "Property" &&
+        "key" in node &&
+        typeof node.key === "object" &&
+        node.key !== null &&
+        (("name" in node.key && node.key.name === "tokens") ||
+            ("value" in node.key && node.key.value === "tokens"));
+    return isKey || Object.values(node).some(holdsTokensKey);
+};
+/** A property's text, when it is written as one. */
+const plainText = (object, name) => {
+    const value = propertyValue(object, name);
+    return value?.type === "Literal" && typeof value.value === "string" ? value.value : undefined;
+};
+/** One entry of the list, or none when it is not written plainly. */
+const tokensEntry = (element) => {
+    if (element === null || element.type === "SpreadElement")
+        return undefined;
+    const entry = unwrapped(element);
+    if (entry.type === "Literal" && typeof entry.value === "string")
+        return { file: entry.value, mode: undefined };
+    if (entry.type !== "ObjectExpression")
+        return undefined;
+    const file = plainText(entry, "file");
+    const mode = plainText(entry, "mode");
+    return file === undefined || mode === undefined ? undefined : { file, mode };
+};
+/**
+ * What a source's module declares, from its text.
+ *
+ * @param file - the module's path, for the parser (its extension says TypeScript or JSX).
+ * @param text - the module's text.
+ */
+export const declaredSource = (file, text) => {
+    const { program, errors } = parseSync(file, text);
+    if (errors.length > 0) {
+        const unread = `it cannot be parsed: ${errors[0]?.message ?? ""}`;
+        return { id: undefined, tokens: [], problems: [], unread };
+    }
+    const value = program.body.map(sourceValue).find((each) => each !== undefined);
+    if (value?.type !== "ObjectExpression")
+        return { id: undefined, tokens: [], problems: holdsTokensKey(value ?? program.body) ? [NOT_PLAIN] : [] };
+    const object = value;
+    const id = plainText(object, "id");
+    const list = propertyValue(object, "tokens");
+    if (list === undefined)
+        return { id, tokens: [], problems: [] };
+    if (list.type !== "ArrayExpression")
+        return { id, tokens: [], problems: [NOT_PLAIN] };
+    const entries = list.elements.map(tokensEntry);
+    return {
+        id,
+        tokens: entries.filter((entry) => entry !== undefined),
+        problems: entries.includes(undefined) ? [NOT_PLAIN] : []
+    };
+};
+/** The folder of the package a module is in: the nearest with a manifest, or the module's own. */
+const packageRoot = (file) => {
+    const start = dirname(file);
+    for (let dir = start; dir !== dirname(dir); dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+    }
+    return start;
+};
+/** Whether a path, its links followed where it exists, is inside a folder. */
+const isInside = (root, path) => {
+    const real = (each) => (existsSync(each) ? realpathSync(each) : each);
+    const fromRoot = relative(real(root), real(path));
+    return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+};
+/**
+ * What the source in a module gives, its paths absolute.
+ *
+ * @param file - the module's absolute path.
+ * @param name - what names the module, for the problems and the files' labels (`@acme/ui/stories`).
+ */
+export const sourceTokensIn = (file, name) => {
+    let declared;
+    try {
+        declared = declaredSource(file, readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { id: undefined, files: [], problems: [], unread: `${name}: ${reason}` };
+    }
+    const source = declared.id ?? name;
+    const root = packageRoot(file);
+    const located = declared.tokens.map((each) => ({ ...each, path: resolve(dirname(file), each.file) }));
+    const outside = located.filter(({ path }) => !isInside(root, path));
+    return {
+        id: declared.id,
+        files: located
+            .filter(({ path }) => isInside(root, path))
+            .map(({ file: written, mode, path }) => ({ path, mode, label: `${name}: ${written}`, source })),
+        problems: [...declared.problems, ...outside.map((each) => `${each.file} is outside the package`)].map((problem) => `${name}: ${problem}`),
+        ...(declared.unread === undefined ? {} : { unread: `${name}: ${declared.unread}` })
+    };
+};
+/** A file's content as a reading's input, or none with a problem. */
+const fileInput = (file, unread) => {
+    const { path, mode, label, source } = file;
+    try {
+        const content = JSON.parse(readFileSync(path, "utf8"));
+        return [{ label, mode, file: content, ...(source === undefined ? {} : { source }) }];
+    }
+    catch (error) {
+        // the parser's message quotes the file, and a path may not lead to tokens at all
+        const reason = error instanceof SyntaxError ? "it is not JSON" : String(error);
+        unread.push(`${label}: ${reason}`);
+        return [];
+    }
+};
+/**
+ * Reads tokens files from disk.
+ *
+ * @param files - the files: each source's, then the catalogue's own.
+ */
+export const readTokenFiles = (files) => {
+    const unread = [];
+    const { tokens, problems, clashes } = readTokens(files.flatMap((file) => fileInput(file, unread)));
+    return { tokens, problems: [...unread, ...problems], clashes };
+};

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

@@ -25,4 +25,3 @@ export declare const dedented: (text: string, indent: number) => string;
  * @returns the texts by export name, or a message saying why the file cannot be read.
  */
 export declare const storyCode: (file: string, text: string) => Readonly<Record<string, string>> | string;
-//# sourceMappingURL=storyCode.d.ts.map

package/dist/src/vite/storyCode.js

@@ -9,7 +9,7 @@
  *
  * @module
  */
-import { parseSync } from "vite";
+import { parseStoryFile } from "./storyParse.js";
 /** An expression without the TypeScript wrappers around it (`satisfies`, `as`, parentheses). */
 const unwrapped = (expression) => {
     if (expression.type === "TSSatisfiesExpression" ||
@@ -61,7 +61,7 @@ const renderText = (declarator, text) => {
  * @returns the texts by export name, or a message saying why the file cannot be read.
  */
 export const storyCode = (file, text) => {
-    const { program, errors } = parseSync(file, text);
+    const { program, errors } = parseStoryFile(file, text);
     const [error] = errors;
     if (error !== undefined)
         return `${file} does not parse: ${error.message}`;
@@ -77,4 +77,3 @@ export const storyCode = (file, text) => {
     }
     return code;
 };
-//# sourceMappingURL=storyCode.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * A story file's named exports, read from its parsed source: the names the index takes as stories.
+ *
+ * @remarks
+ * Kept apart from `indexStoryFile.ts`, which reads each export's fields. Pure.
+ *
+ * @module
+ */
+import type { ESTree } from "vite";
+/**
+ * One named export of the file: its exported name, the local name it points at (none for a re-export from another
+ * file), whether its statement declares it (`export const A = …`, not `export { A }`), and where the statement starts.
+ */
+export type NamedExport = {
+    /** The name it is exported as. */
+    readonly exportName: string;
+    /** The local name it points at; none for a re-export from another file. */
+    readonly local: string | undefined;
+    /** Whether its statement declares it (`export const A = …`), not only names it (`export { A }`). */
+    readonly isDeclared: boolean;
+    /** Where its statement starts. */
+    readonly start: number;
+};
+/** An export's or an import's name: an identifier's, or a string's (`export { A as "a story" }`). */
+export declare const moduleName: (name: ESTree.ModuleExportName) => string;
+/**
+ * The file's named exports that exist when it runs, in their order: declared ones and re-exports (`export { A as B }`,
+ * from this file or another); never the default export, a type, or the names of an `export *`.
+ *
+ * @param program - the parsed file.
+ */
+export declare const namedExports: (program: ESTree.Program) => NamedExport[];

package/dist/src/vite/storyExports.js

@@ -0,0 +1,27 @@
+/** An export's or an import's name: an identifier's, or a string's (`export { A as "a story" }`). */
+export const moduleName = (name) => name.type === "Literal" ? String(name.value) : name.name;
+/**
+ * The file's named exports that exist when it runs, in their order: declared ones and re-exports (`export { A as B }`,
+ * from this file or another); never the default export, a type, or the names of an `export *`.
+ *
+ * @param program - the parsed file.
+ */
+export const namedExports = (program) => program.body.flatMap((statement) => {
+    if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type")
+        return [];
+    const { declaration, start } = statement;
+    if (declaration?.type === "VariableDeclaration") {
+        return declaration.declarations.flatMap((declarator) => declarator.id.type === "Identifier"
+            ? [{ exportName: declarator.id.name, local: declarator.id.name, isDeclared: true, start }]
+            : []);
+    }
+    if (declaration?.type === "FunctionDeclaration" && declaration.id !== null)
+        return [{ exportName: declaration.id.name, local: declaration.id.name, isDeclared: true, start }];
+    return statement.specifiers.flatMap((specifier) => {
+        const exportName = moduleName(specifier.exported);
+        if (specifier.exportKind === "type" || exportName === "default")
+            return [];
+        const local = statement.source === null ? moduleName(specifier.local) : undefined;
+        return [{ exportName, local, isDeclared: false, start }];
+    });
+});

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

@@ -1,4 +1,5 @@
 import type { StoryFileIndex } from "@forgebook/story-format/source";
+import { type DiskCache } from "./diskCache.ts";
 /** A pattern of story files and the folder it is read from: the declaring module's folder, the import's pattern. */
 export type StoryFilesGroup = {
     /** The declaring module's folder, absolute: the files' keys are relative to it. */
@@ -35,6 +36,23 @@ export declare const storyFileKeys: (root: string, patterns: readonly string[])
  * module's id. The plugin answers it (`usageModule.ts`) only when a page asks.
  */
 export declare const USAGE_PREFIX = "virtual:forgebook-usage:";
+/**
+ * The id prefix of a group's search index: the group follows (`storyFilesGroupText`). The plugin answers it
+ * (`searchModule.ts`) only when a page asks, on the first search.
+ */
+export declare const SEARCH_PREFIX = "virtual:forgebook-search:";
+/** The id prefix of a docs pages' search index, the same way: the plugin answers it only on the first search. */
+export declare const PAGES_SEARCH_PREFIX = "virtual:forgebook-search-pages:";
+/**
+ * The id prefix of a group's texts module, the same way: a build's, imported by the group's module, which holds each
+ * file's docs, code and page as data (`builtTexts.ts`).
+ */
+export declare const TEXTS_PREFIX = "virtual:forgebook-texts:";
+/**
+ * The id prefix of a group's reach module, what each story reaches, the same way: only the dev server's tools ask for
+ * it, so a page that shows "Used in" never downloads it.
+ */
+export declare const REACH_PREFIX = "virtual:forgebook-reach:";
 /** A story file a pattern matches, with its key and its index. */
 export type IndexedStoryFile = {
     /** Its path relative to the declaring module (`../src/x.stories.tsx`). */
@@ -44,23 +62,57 @@ export type IndexedStoryFile = {
     /** Its index. */
     readonly index: StoryFileIndex;
 };
+/** A pattern's index as it is kept between starts, by file key. */
+export type KeptIndex = Readonly<Record<string, StoryFileIndex>>;
+/** Whether what a cache file holds is a pattern's index. */
+export declare const isKeptIndex: (value: unknown) => value is KeptIndex;
+/**
+ * One story file a pattern matches, indexed from its text on disk, with the title its path makes when it writes none.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param key - the file's path relative to the declaring module.
+ * @returns the index, or a message saying why the file cannot be indexed.
+ */
+export declare const storyFileIndex: (root: string, pattern: string, key: string) => StoryFileIndex | string;
 /**
  * Every story file a pattern matches, indexed.
  *
  * @param root - the declaring module's folder.
  * @param pattern - the pattern.
  * @param watch - adds a file whose edit renews the module that read it.
+ * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
  * @throws when a story file cannot be indexed.
  */
-export declare const indexedStoryFiles: (root: string, pattern: string, watch: (file: string) => void) => IndexedStoryFile[];
+export declare const indexedStoryFiles: (root: string, pattern: string, watch: (file: string) => void, cache?: DiskCache<KeptIndex>) => IndexedStoryFile[];
+/** The loaders a group offers besides its story files'. */
+export type GroupLoaders = {
+    /** Whether it offers its "Used in" (the catalogue did not turn it off). */
+    readonly hasUsage: boolean;
+    /** Whether it offers what each story reaches: only on a dev server, for its tools. */
+    readonly hasReach: boolean;
+};
 /**
  * The code of the module for one pattern.
  *
  * @param root - the declaring module's folder.
  * @param pattern - the pattern before `?forgebook-files`.
  * @param watch - adds a file whose edit renews the module (each story file: its index is in the module).
- * @param hasUsage - whether the group offers its "Used in" loader (the catalogue did not turn it off).
+ * @param loaders - the group's loaders besides its story files'; both by default.
+ * @param cache - the index kept between starts.
  * @returns the module's code, or a message saying which file cannot be indexed.
  */
-export declare const storyFilesModule: (root: string, pattern: string, watch: (file: string) => void, hasUsage?: boolean) => string;
-//# sourceMappingURL=storyFilesModule.d.ts.map
+export declare const storyFilesModule: (root: string, pattern: string, watch: (file: string) => void, loaders?: GroupLoaders, cache?: DiskCache<KeptIndex>) => string;
+/**
+ * The code of the module for one pattern, from its story files indexed.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern before `?forgebook-files`.
+ * @param files - the story files it matches, indexed.
+ * @param loaders - the group's loaders besides its story files'.
+ * @param hasTexts - a build's: whether each file's docs, code and page come from the group's texts module, in the
+ * rows' order (`TEXTS_PREFIX`), and not each from its query.
+ */
+export declare const storyFilesCode: (root: string, pattern: string, files: readonly IndexedStoryFile[], loaders: GroupLoaders, hasTexts?: boolean) => string;

package/dist/src/vite/storyFilesModule.js

@@ -6,14 +6,18 @@
  * @remarks
  * One module per pattern, instead of an import per file: in development the browser fetched every index module one by
  * one, a few hundred requests per frame. The keys are the files' paths relative to the declaring module
- * (`../src/x.stories.tsx`), the same keys `storyFileKeys` gives the tests that read the files from the disk.
+ * (`../src/x.stories.tsx`), the same keys `storyFileKeys` gives the tests that read the files from the disk. A build
+ * takes each file's docs, code and page from the group's texts module, written as data, instead of their loaders'
+ * imports (`builtTexts.ts`).
  *
  * @module
  */
 import { globSync, readFileSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { codeLiteral } from "../codeLiteral.js";
 import { autoTitle, patternBase } from "./autoTitle.js";
+import { isSettledSince, nowNs, stampPaths } from "./diskCache.js";
 import { indexStoryFile } from "./indexStoryFile.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /** Between a group's parts in a module's id: no path or pattern holds it. */
 const GROUP_SEPARATOR = "::";
 /**
@@ -43,6 +47,15 @@ export const storyFilesGroupOf = (text) => {
     const [root = "", up = "0", own = ""] = text.split(GROUP_SEPARATOR);
     return { root, pattern: `${"../".repeat(Number(up))}${own}` };
 };
+/** The folder of a project's dependencies. */
+const DEPENDENCIES = "node_modules";
+/**
+ * What a pattern leaves out: the dependencies, unless it names them. A `**` from a monorepo's root would otherwise walk
+ * every package's, seconds on the server's thread for files nobody asked for, as Storybook's own globs skip them.
+ *
+ * @param pattern - the pattern.
+ */
+const excludedFrom = (pattern) => pattern.includes(DEPENDENCIES) ? () => false : (name) => name === DEPENDENCIES;
 /**
  * The story files patterns match, as paths relative to `root` starting with `./` or `../`, sorted.
  *
@@ -50,62 +63,137 @@ export const storyFilesGroupOf = (text) => {
  * @param patterns - the patterns (`../src/**\/*.stories.tsx`).
  */
 export const storyFileKeys = (root, patterns) => patterns
-    .flatMap((pattern) => globSync(pattern, { cwd: root }))
-    .map((file) => {
-    const path = relative(root, join(root, file)).split("\\").join("/");
-    return path.startsWith(".") ? path : `./${path}`;
-})
+    .flatMap((pattern) => globSync(pattern, { cwd: root, exclude: excludedFrom(pattern) }))
+    // with forward slashes on every system, so a story file has the same key wherever the catalogue runs
+    .map((file) => VITE_PATHS.relativeKey(root, file))
     .sort();
 /**
  * The id prefix of a group's "Used in" module: the group follows (`storyFilesGroupText`), as in a `?forgebook-files`
  * module's id. The plugin answers it (`usageModule.ts`) only when a page asks.
  */
 export const USAGE_PREFIX = "virtual:forgebook-usage:";
+/**
+ * The id prefix of a group's search index: the group follows (`storyFilesGroupText`). The plugin answers it
+ * (`searchModule.ts`) only when a page asks, on the first search.
+ */
+export const SEARCH_PREFIX = "virtual:forgebook-search:";
+/** The id prefix of a docs pages' search index, the same way: the plugin answers it only on the first search. */
+export const PAGES_SEARCH_PREFIX = "virtual:forgebook-search-pages:";
+/**
+ * The id prefix of a group's texts module, the same way: a build's, imported by the group's module, which holds each
+ * file's docs, code and page as data (`builtTexts.ts`).
+ */
+export const TEXTS_PREFIX = "virtual:forgebook-texts:";
+/**
+ * The id prefix of a group's reach module, what each story reaches, the same way: only the dev server's tools ask for
+ * it, so a page that shows "Used in" never downloads it.
+ */
+export const REACH_PREFIX = "virtual:forgebook-reach:";
+/** Whether what a cache file holds is a pattern's index. */
+export const isKeptIndex = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * One story file a pattern matches, indexed from its text on disk, with the title its path makes when it writes none.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param key - the file's path relative to the declaring module.
+ * @returns the index, or a message saying why the file cannot be indexed.
+ */
+export const storyFileIndex = (root, pattern, key) => {
+    const file = VITE_PATHS.resolve(root, key);
+    const title = autoTitle(patternBase(pattern), key);
+    return indexStoryFile(file, readFileSync(file, "utf8"), title === undefined ? {} : { autoTitle: title });
+};
 /**
  * Every story file a pattern matches, indexed.
  *
  * @param root - the declaring module's folder.
  * @param pattern - the pattern.
  * @param watch - adds a file whose edit renews the module that read it.
+ * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
  * @throws when a story file cannot be indexed.
  */
-export const indexedStoryFiles = (root, pattern, watch) => storyFileKeys(root, [pattern]).map((key) => {
-    const file = resolve(root, key);
-    watch(file);
-    const title = autoTitle(patternBase(pattern), key);
-    const index = indexStoryFile(file, readFileSync(file, "utf8"), title === undefined ? {} : { autoTitle: title });
-    if (typeof index === "string")
-        throw new Error(index);
-    return { key, file, index };
-});
-/** An object literal of a key per file, each value written by `value`. */
-const objectOf = (keys, value) => `{${keys.map((key) => `${JSON.stringify(key)}: ${value(key)}`).join(",\n")}}`;
+export const indexedStoryFiles = (root, pattern, watch, cache) => {
+    const name = storyFilesGroupText(VITE_PATHS.normalize(root), pattern);
+    const since = nowNs();
+    const kept = cache?.read(name);
+    const files = storyFileKeys(root, [pattern]).map((key) => {
+        const file = VITE_PATHS.resolve(root, key);
+        watch(file);
+        const known = kept?.[key];
+        if (known !== undefined)
+            return { key, file, index: known };
+        const index = storyFileIndex(root, pattern, key);
+        if (typeof index === "string")
+            throw new Error(index);
+        return { key, file, index };
+    });
+    // kept again when anything was read anew: a file added, or the kept index out of date
+    if (cache !== undefined && files.some(({ key }) => kept?.[key] === undefined)) {
+        const stamps = stampPaths(files.map((each) => each.file));
+        const index = Object.fromEntries(files.map((each) => [each.key, each.index]));
+        if (isSettledSince(stamps, since))
+            cache.write(name, index, stamps);
+    }
+    return files;
+};
 /**
  * The code of the module for one pattern.
  *
  * @param root - the declaring module's folder.
  * @param pattern - the pattern before `?forgebook-files`.
  * @param watch - adds a file whose edit renews the module (each story file: its index is in the module).
- * @param hasUsage - whether the group offers its "Used in" loader (the catalogue did not turn it off).
+ * @param loaders - the group's loaders besides its story files'; both by default.
+ * @param cache - the index kept between starts.
  * @returns the module's code, or a message saying which file cannot be indexed.
  */
-export const storyFilesModule = (root, pattern, watch, hasUsage = true) => {
-    const files = indexedStoryFiles(root, pattern, watch);
-    const keys = files.map((file) => file.key);
-    const index = Object.fromEntries(files.map((file) => [file.key, file.index]));
-    const usage = JSON.stringify(`${USAGE_PREFIX}${storyFilesGroupText(root, pattern)}`);
-    // absolute paths: the module has no folder of its own; Vite serves them under /@fs/ in development
-    const path = (key) => JSON.stringify(resolve(root, key));
-    const query = (key, name) => JSON.stringify(`${resolve(root, key)}?${name}`);
+export const storyFilesModule = (root, pattern, watch, loaders = { hasUsage: true, hasReach: true }, cache) => storyFilesCode(root, pattern, indexedStoryFiles(root, pattern, watch, cache), loaders);
+/**
+ * The code of the module for one pattern, from its story files indexed.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern before `?forgebook-files`.
+ * @param files - the story files it matches, indexed.
+ * @param loaders - the group's loaders besides its story files'.
+ * @param hasTexts - a build's: whether each file's docs, code and page come from the group's texts module, in the
+ * rows' order (`TEXTS_PREFIX`), and not each from its query.
+ */
+export const storyFilesCode = (root, pattern, files, loaders, hasTexts = false) => {
+    const { hasUsage, hasReach } = loaders;
+    // the group's id in Vite's form, as the plugin names the declaring module's folder
+    const folder = VITE_PATHS.normalize(root);
+    const usage = codeLiteral(`${USAGE_PREFIX}${storyFilesGroupText(folder, pattern)}`);
+    const search = codeLiteral(`${SEARCH_PREFIX}${storyFilesGroupText(folder, pattern)}`);
+    const reach = codeLiteral(`${REACH_PREFIX}${storyFilesGroupText(folder, pattern)}`);
+    const texts = codeLiteral(`${TEXTS_PREFIX}${storyFilesGroupText(folder, pattern)}`);
+    // absolute paths in Vite's form: the module has no folder of its own, Vite serves them under /@fs/ in development,
+    // and the queries' ids come back to the plugin as written here
+    const absolute = (key) => VITE_PATHS.resolve(folder, key);
+    const path = (key) => codeLiteral(absolute(key));
+    const query = (key, name) => `() => import(${codeLiteral(`${absolute(key)}?${name}`)}).then((module) => module.default)`;
+    const textLoaders = (key) => hasTexts
+        ? []
+        : [query(key, "forgebook-docs"), query(key, "forgebook-code"), query(key, "forgebook-page")];
+    // a row per file, its name written once and not once per column (its index, each loader): a large catalogue's
+    // names are a tenth of its index
+    const rows = files.map(({ key, index }) => [codeLiteral(key), codeLiteral(index), `() => import(${path(key)})`, ...textLoaders(key)].join(", "));
+    const written = `[${rows.map((row) => `[${row}]`).join(",\n")}]`;
     return [
+        ...(hasTexts ? [`import texts from ${texts};`] : []),
+        // a build's texts are their module's rows, in the same order: each joins its file's
+        `const rows = ${hasTexts ? `${written}.map((row, at) => row.concat(texts[at]))` : written};`,
+        "const column = (at) => Object.fromEntries(rows.map((row) => [row[0], row[at]]));",
         "export default {",
-        `index: ${JSON.stringify(index)},`,
-        `stories: ${objectOf(keys, (key) => `() => import(${path(key)})`)},`,
-        `docs: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-docs")}).then((module) => module.default)`)},`,
-        `code: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-code")}).then((module) => module.default)`)},`,
-        `pages: ${objectOf(keys, (key) => `() => import(${query(key, "forgebook-page")}).then((module) => module.default)`)}${hasUsage ? "," : ""}`,
-        ...(hasUsage ? [`usage: () => import(${usage}).then((module) => module.default)`] : []),
+        "index: column(1),",
+        "stories: column(2),",
+        "docs: column(3),",
+        "code: column(4),",
+        "pages: column(5),",
+        `search: () => import(${search}).then((module) => module.default),`,
+        ...(hasUsage ? [`usage: () => import(${usage}).then((module) => module.default),`] : []),
+        ...(hasReach ? [`reach: () => import(${reach}).then((module) => module.default),`] : []),
         "};"
     ].join("\n");
 };
-//# sourceMappingURL=storyFilesModule.js.map

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

@@ -1,10 +1,11 @@
 /**
- * A story file's meta, read from its source with the TypeScript compiler's parser: the value of one of its fields, the
- * component it names and the module it imports that component from.
+ * A story file's meta, read from its source with the TypeScript compiler's parser, for the docs: the value of one of its
+ * fields, the component it names and its subcomponents.
  *
  * @remarks
- * CSF is the same whatever framework a story is written for, so the plugin, `forgebook-docs` and every framework's
- * docs extractor read the meta through this module. Pure: a parsed file in, nodes or a specifier out.
+ * CSF is the same whatever framework a story is written for, so `forgebook-docs` and every framework's docs extractor
+ * read the meta through this module, inside their TypeScript program. The plugin's own reading, outside any program,
+ * is `componentImport.ts`. Pure: a parsed file in, nodes out.
  *
  * @module
  */
@@ -22,13 +23,21 @@ export declare const metaField: (source: ts.SourceFile, name: string) => ts.Expr
  * @param source - the story file, parsed.
  */
 export declare const metaComponent: (source: ts.SourceFile) => ts.Expression | undefined;
+/** An expression without the wrappers around a literal list (`as const`, `satisfies`, parentheses). */
+export declare const unwrapped: (expression: ts.Expression) => ts.Expression;
+/** A subcomponent the meta names: the name it gives it, and where the code names its value. */
+export type MetaSubcomponent = {
+    /** Its key in `subcomponents`. */
+    readonly name: string;
+    /** The expression that names the component, the location the checker reads its type at. */
+    readonly expression: ts.Expression;
+    /** The component's symbol as written there; a shorthand (`{ ChipList }`) names the value, not the key. */
+    readonly symbol: ts.Symbol | undefined;
+};
 /**
- * The module a story file imports its meta's component from (`./Button`), read from the file alone: no program, so
- * it answers at once, where the docs need the package's program.
+ * The subcomponents the meta names, in the order it writes them: `subcomponents: { ChipList, Items: MenuItem }`.
  *
- * @param storyFile - the story file's path, for the parser.
- * @param text - the story file's text.
- * @returns the import's module specifier, or none when the meta names no imported component.
+ * @param source - the story file, parsed.
+ * @param checker - the program's checker.
  */
-export declare const componentImport: (storyFile: string, text: string) => string | undefined;
-//# sourceMappingURL=storyMeta.d.ts.map
+export declare const metaSubcomponents: (source: ts.SourceFile, checker: ts.TypeChecker) => MetaSubcomponent[];