forgebook 0.1.8 → 0.3.0

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

@@ -1,22 +1,31 @@
 import type { StoryFileIndex } from "@forgebook/story-format/source";
-/** A pattern of story files and the folder it is read from: the declaring module's folder, the import's pattern. */
+import { type DiskCache } from "./diskCache.ts";
+/**
+ * A group of story files and the folder its patterns are read from: the declaring module's folder, the import's
+ * patterns.
+ */
 export type StoryFilesGroup = {
     /** The declaring module's folder, absolute: the files' keys are relative to it. */
     readonly root: string;
-    /** The pattern relative to it, its leading `./` dropped (`../src/**\/*.stories.tsx`). */
-    readonly pattern: string;
+    /**
+     * The patterns relative to it, their leading `./` dropped (`../src/**\/*.stories.tsx`), and the `!` ones that leave
+     * files out (`listedFiles`).
+     */
+    readonly patterns: readonly string[];
 };
+/** Between a group's parts in a module's id: no path or pattern holds it. */
+export declare const GROUP_SEPARATOR = "::";
 /**
- * A `?forgebook-files` group written for a module's id: the folder, how many folders the pattern climbs, and the rest
- * of the pattern. A Vite module's id is served under a URL path, whose normalisation would let a `..` remove the part
- * before it (`app::../storybook`: the folder and the separator), so the pattern's leading `../` are counted, never
+ * A group of story files written for a module's id: the folder, then for each pattern how many folders it climbs and
+ * the rest of it. A Vite module's id is served under a URL path, whose normalisation would let a `..` remove the part
+ * before it (`app::../storybook`: the folder and the separator), so a pattern's leading `../` are counted, never
  * written. The files keep their keys relative to the declaring module (`../src/x.stories.tsx`), unique in a source and
  * the testing package's too.
  *
  * @param folder - the declaring module's folder.
- * @param pattern - the pattern as the import writes it (`../src/**\/*.stories.tsx`).
+ * @param patterns - the patterns as the import or the configuration writes them (`../src/**\/*.stories.tsx`).
  */
-export declare const storyFilesGroupText: (folder: string, pattern: string) => string;
+export declare const storyFilesGroupText: (folder: string, patterns: readonly string[]) => string;
 /**
  * A group read back from a module's id (`storyFilesGroupText`).
  *
@@ -24,43 +33,118 @@ export declare const storyFilesGroupText: (folder: string, pattern: string) => s
  */
 export declare const storyFilesGroupOf: (text: string) => StoryFilesGroup;
 /**
- * The story files patterns match, as paths relative to `root` starting with `./` or `../`, sorted.
+ * Whether a file a group lists may be read. A dev server refuses what `server.fs.deny` names (`fileAccess.ts`).
+ *
+ * @param file - the file, absolute in Vite's form.
+ */
+export type IsFileKept = (file: string) => boolean;
+/** Every file a group lists: a build's, and a test's that reads the files from the disk. */
+export declare const EVERY_FILE: IsFileKept;
+/**
+ * The story files patterns list, as paths relative to `root` starting with `./` or `../`, each once, sorted: the union
+ * of the patterns less what the `!` ones match (`listedFiles`).
  *
  * @param root - the folder the patterns are relative to: the declaring module's.
- * @param patterns - the patterns (`../src/**\/*.stories.tsx`).
+ * @param patterns - the patterns (`../src/**\/*.stories.tsx`, `!../src/**\/legacy/*`).
+ * @param isKept - whether a listed file may be read; every one by default.
+ * @throws when every pattern is a `!` one.
  */
-export declare const storyFileKeys: (root: string, patterns: readonly string[]) => string[];
+export declare const storyFileKeys: (root: string, patterns: readonly string[], isKept?: IsFileKept) => string[];
+/**
+ * The specifier prefix of a group of story files named by its patterns, the group following (`storyFilesGroupText`):
+ * how the module generated for a catalogue's `stories` imports them as one group, `!` patterns included, which a
+ * `?forgebook-files` import of one pattern cannot say.
+ */
+export declare const FILES_SPECIFIER_PREFIX = "virtual:forgebook-files:";
+/** The specifier prefix of a group of docs pages named by its patterns, the same way: a catalogue's `docs`. */
+export declare const DOCS_PAGES_SPECIFIER_PREFIX = "virtual:forgebook-docs-pages:";
 /**
  * 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 declare const USAGE_PREFIX = "virtual:forgebook-usage:";
-/** A story file a pattern matches, with its key and its index. */
+/**
+ * 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 group lists, with its key, the pattern that lists it and its index. */
 export type IndexedStoryFile = {
     /** Its path relative to the declaring module (`../src/x.stories.tsx`). */
     readonly key: string;
+    /** The group's first pattern that lists it, whose static start begins its title when its meta writes none. */
+    readonly pattern: string;
     /** Its absolute path. */
     readonly file: string;
     /** Its index. */
     readonly index: StoryFileIndex;
 };
+/** A group'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 group's index. */
+export declare const isKeptIndex: (value: unknown) => value is KeptIndex;
+/**
+ * One story file a pattern lists, 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 that lists it.
+ * @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.
+ * Every story file a group's patterns list, indexed.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the patterns (`storyFileKeys`).
  * @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.
+ * @param isKept - whether a listed file may be read; every one by default.
  * @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, patterns: readonly string[], watch: (file: string) => void, cache?: DiskCache<KeptIndex>, isKept?: IsFileKept) => IndexedStoryFile[];
+/** The loaders a group offers besides its story files'. */
+export type GroupLoaders = {
+    /** Whether it offers each story file's component docs (the catalogue reads them); `true` by default. */
+    readonly hasDocs?: boolean;
+    /** 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.
+ * The code of the module for one group.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern before `?forgebook-files`.
+ * @param patterns - the group's patterns.
  * @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'; all of them 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, patterns: readonly string[], watch: (file: string) => void, loaders?: GroupLoaders, cache?: DiskCache<KeptIndex>) => string;
+/**
+ * The code of the module for one group, from its story files indexed.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param files - the story files it lists, 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, patterns: readonly string[], files: readonly IndexedStoryFile[], loaders: GroupLoaders, hasTexts?: boolean) => string;

package/dist/src/vite/storyFilesModule.js

@@ -1,111 +1,229 @@
 /**
- * The module that answers a `?forgebook-files` import: every story file a pattern matches, as one module with each
- * file's index (read from its source, never run), the loaders of its module, its component's docs and its code, and
- * the group's "Used in" loader.
+ * The module that answers a group of story files: a `?forgebook-files` import's pattern, or a catalogue's `stories`
+ * list (`FILES_SPECIFIER_PREFIX`). Every story file the group lists, as one module with each file's index (read from
+ * its source, never run), the loaders of its module, its component's docs and its code, and the group's "Used in"
+ * loader.
  *
  * @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.
+ * One module per group, instead of an import per file: in development the browser fetched every index module one by
+ * one, a few hundred requests per frame. A catalogue's `stories` are one group, not one per pattern: its `!` patterns
+ * leave files out of what all the others list, a file two patterns list is listed once, and "Used in" joins stories
+ * across every pattern. 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. 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 { readFileSync } from "node:fs";
+import { codeLiteral } from "../codeLiteral.js";
 import { autoTitle, patternBase } from "./autoTitle.js";
+import { isSettledSince, nowNs, stampPaths } from "./diskCache.js";
 import { indexStoryFile } from "./indexStoryFile.js";
+import { isNegated, listedFiles } from "./storyPatterns.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 = "::";
+export const GROUP_SEPARATOR = "::";
+/** Before a pattern's count of climbed folders in a module's id, when it is a `!` pattern. */
+const NEGATED_MARK = "!";
 /**
- * A `?forgebook-files` group written for a module's id: the folder, how many folders the pattern climbs, and the rest
- * of the pattern. A Vite module's id is served under a URL path, whose normalisation would let a `..` remove the part
- * before it (`app::../storybook`: the folder and the separator), so the pattern's leading `../` are counted, never
- * written. The files keep their keys relative to the declaring module (`../src/x.stories.tsx`), unique in a source and
- * the testing package's too.
+ * One pattern written for a module's id: whether it leaves files out and how many folders it climbs, then the rest of
+ * it. The mark goes with the count, never with the rest, which may start with an extglob's `!(…)`.
  *
- * @param folder - the declaring module's folder.
  * @param pattern - the pattern as the import writes it (`../src/**\/*.stories.tsx`).
  */
-export const storyFilesGroupText = (folder, pattern) => {
-    const segments = pattern.split("/");
+const patternParts = (pattern) => {
+    const isLeftOut = isNegated(pattern);
+    const segments = (isLeftOut ? pattern.slice(1) : pattern).split("/");
     const firstOwn = segments.findIndex((segment) => segment !== "." && segment !== "..");
     const climbed = firstOwn === -1 ? segments : segments.slice(0, firstOwn);
     const own = firstOwn === -1 ? [] : segments.slice(firstOwn);
     const up = climbed.filter((segment) => segment === "..").length;
-    return [folder, String(up), own.join("/")].join(GROUP_SEPARATOR);
+    return [`${isLeftOut ? NEGATED_MARK : ""}${up}`, own.join("/")];
 };
+/**
+ * A group of story files written for a module's id: the folder, then for each pattern how many folders it climbs and
+ * the rest of it. A Vite module's id is served under a URL path, whose normalisation would let a `..` remove the part
+ * before it (`app::../storybook`: the folder and the separator), so a pattern's leading `../` are counted, never
+ * written. The files keep their keys relative to the declaring module (`../src/x.stories.tsx`), unique in a source and
+ * the testing package's too.
+ *
+ * @param folder - the declaring module's folder.
+ * @param patterns - the patterns as the import or the configuration writes them (`../src/**\/*.stories.tsx`).
+ */
+export const storyFilesGroupText = (folder, patterns) => [folder, ...patterns.flatMap(patternParts)].join(GROUP_SEPARATOR);
 /**
  * A group read back from a module's id (`storyFilesGroupText`).
  *
  * @param text - the id's group part.
  */
 export const storyFilesGroupOf = (text) => {
-    const [root = "", up = "0", own = ""] = text.split(GROUP_SEPARATOR);
-    return { root, pattern: `${"../".repeat(Number(up))}${own}` };
+    const [root = "", ...parts] = text.split(GROUP_SEPARATOR);
+    const patterns = [];
+    for (let at = 0; at < parts.length; at += 2) {
+        const count = parts[at] ?? "0";
+        const isLeftOut = count.startsWith(NEGATED_MARK);
+        const up = Number(isLeftOut ? count.slice(NEGATED_MARK.length) : count);
+        patterns.push(`${isLeftOut ? "!" : ""}${"../".repeat(up)}${parts[at + 1] ?? ""}`);
+    }
+    return { root, patterns };
 };
+/** Every file a group lists: a build's, and a test's that reads the files from the disk. */
+export const EVERY_FILE = () => true;
 /**
- * The story files patterns match, as paths relative to `root` starting with `./` or `../`, sorted.
+ * The story files patterns list, as paths relative to `root` starting with `./` or `../`, each once, sorted: the union
+ * of the patterns less what the `!` ones match (`listedFiles`).
  *
  * @param root - the folder the patterns are relative to: the declaring module's.
- * @param patterns - the patterns (`../src/**\/*.stories.tsx`).
+ * @param patterns - the patterns (`../src/**\/*.stories.tsx`, `!../src/**\/legacy/*`).
+ * @param isKept - whether a listed file may be read; every one by default.
+ * @throws when every pattern is a `!` one.
+ */
+export const storyFileKeys = (root, patterns, isKept = EVERY_FILE) => listedFiles(root, patterns)
+    .map((file) => file.key)
+    .filter((key) => isKept(VITE_PATHS.resolve(root, key)));
+/**
+ * The specifier prefix of a group of story files named by its patterns, the group following (`storyFilesGroupText`):
+ * how the module generated for a catalogue's `stories` imports them as one group, `!` patterns included, which a
+ * `?forgebook-files` import of one pattern cannot say.
  */
-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}`;
-})
-    .sort();
+export const FILES_SPECIFIER_PREFIX = "virtual:forgebook-files:";
+/** The specifier prefix of a group of docs pages named by its patterns, the same way: a catalogue's `docs`. */
+export const DOCS_PAGES_SPECIFIER_PREFIX = "virtual:forgebook-docs-pages:";
 /**
  * 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:";
 /**
- * Every story file a pattern matches, indexed.
+ * 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 group's index. */
+export const isKeptIndex = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * One story file a pattern lists, 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 that lists it.
+ * @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 group's patterns list, indexed.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern.
+ * @param patterns - the patterns (`storyFileKeys`).
  * @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.
+ * @param isKept - whether a listed file may be read; every one by default.
  * @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, patterns, watch, cache, isKept = EVERY_FILE) => {
+    const name = storyFilesGroupText(VITE_PATHS.normalize(root), patterns);
+    const since = nowNs();
+    const kept = cache?.read(name);
+    const listed = listedFiles(root, patterns).filter(({ key }) => isKept(VITE_PATHS.resolve(root, key)));
+    const files = listed.map(({ key, pattern }) => {
+        const file = VITE_PATHS.resolve(root, key);
+        watch(file);
+        const known = kept?.[key];
+        if (known !== undefined)
+            return { key, pattern, file, index: known };
+        const index = storyFileIndex(root, pattern, key);
+        if (typeof index === "string")
+            throw new Error(index);
+        return { key, pattern, 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.
+ * The code of the module for one group.
  *
  * @param root - the declaring module's folder.
- * @param pattern - the pattern before `?forgebook-files`.
+ * @param patterns - the group's patterns.
  * @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'; all of them 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, patterns, watch, loaders = { hasUsage: true, hasReach: true }, cache) => storyFilesCode(root, patterns, indexedStoryFiles(root, patterns, watch, cache), loaders);
+/**
+ * The code of the module for one group, from its story files indexed.
+ *
+ * @internal
+ * @param root - the declaring module's folder.
+ * @param patterns - the group's patterns.
+ * @param files - the story files it lists, 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, patterns, files, loaders, hasTexts = false) => {
+    const { hasDocs = true, 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, patterns)}`);
+    const search = codeLiteral(`${SEARCH_PREFIX}${storyFilesGroupText(folder, patterns)}`);
+    const reach = codeLiteral(`${REACH_PREFIX}${storyFilesGroupText(folder, patterns)}`);
+    const texts = codeLiteral(`${TEXTS_PREFIX}${storyFilesGroupText(folder, patterns)}`);
+    // 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
+        ? []
+        : // the docs' place is kept without them, so every row's columns stay where the module reads them
+            [
+                hasDocs ? query(key, "forgebook-docs") : "null",
+                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),",
+        hasDocs ? "docs: column(3)," : "docs: {},",
+        "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[];