forgebook 0.0.0-stage → 0.1.0

package/dist/src/vite/forgebookPlugin.js

@@ -0,0 +1,375 @@
+/**
+ * The Vite plugin an app adds to show a catalogue: the story files of every source, and the forced-states rewrite of
+ * every style sheet.
+ *
+ * @remarks
+ * A source names its story files with `import files from "<pattern>?forgebook-files"`: the plugin answers each with
+ * one module (`storyFilesModule.ts`) holding every matched file's index, read from its source with Vite's parser, and
+ * the loaders of its module, of its component's docs and of its code (D-438). Those loaders ask for
+ * `?forgebook-docs`, answered with the component's props as the framework reads them (`adapter.ts`, in a worker) or
+ * `{ error }` for the panel, `?forgebook-code`, answered with each story's `render` as written (`storyCode.ts`),
+ * `?forgebook-page`, answered with the component's documentation file as HTML (`componentPage.ts`), and
+ * `?forgebook-markdown`, a source's own Markdown file (its introduction on the home) as HTML. It also sets
+ * Lightning CSS as the CSS transformer with the forced-states visitor (`forcedStates.ts`) and lets Sass resolve
+ * `pkg:` URLs, which the library's style sheets use.
+ *
+ * A pattern's module watches its story files, so an edit renews it. Vite watches only its root for new files, and the
+ * sources' story files live in other packages: `watch` names their folders, and a story file added or removed there
+ * renews every pattern's module and reloads the page, so the sidebar lists it at once.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import ts from "typescript-6";
+import { STORY_FILE } from "./autoTitle.js";
+import { componentPage, markdownHtml } from "./componentPage.js";
+import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
+import { createDocsExtractor } from "./docsExtractor.js";
+import { moduleSummaryOf } from "./docsProgram.js";
+import { FORCED_STATES_VISITOR } from "./forcedStates.js";
+import { highlightCode } from "./highlightCode.js";
+import { CONFIG_MODULE, configModule, frameEntry, PAGE_ENTRIES, PAGE_FILES, pageHtml, STORIES_SOURCE_FILE, shellEntry, storiesSourceModule } from "./pages.js";
+import { prebundled, scannedEntries } from "./prebundled.js";
+import { storyCode } from "./storyCode.js";
+import { storyFilesModule } from "./storyFilesModule.js";
+import { componentImport } from "./storyMeta.js";
+/**
+ * A file's text, or none when it cannot be read.
+ *
+ * @param file - the file.
+ */
+const readTextFile = (file) => {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/** This module's folder, in the core's package: the core's own dependencies resolve from here, not the project's. */
+const PACKAGE_DIR = import.meta.dirname;
+/**
+ * Sass's `pkg:` importer, when the project installs Sass (`sass-embedded`, an optional peer): a library's styles
+ * import its packages' with `pkg:` URLs. Without Sass, Vite compiles no `.scss` and needs none.
+ */
+const sassOptions = async () => {
+    if (packageResolver(PACKAGE_DIR)("sass-embedded") === undefined)
+        return {};
+    const { NodePackageImporter } = await import("sass-embedded");
+    return { preprocessorOptions: { scss: { importers: [new NodePackageImporter()] } } };
+};
+/** The query that asks for the story files a pattern matches (`../src/**\/*.stories.tsx?forgebook-files`). */
+const FILES_QUERY = "?forgebook-files";
+/** The id of a pattern's module: virtual, with the declaring module's folder and the pattern after it. */
+const FILES_PREFIX = "\0forgebook-files:";
+/** Between the folder and the pattern in a pattern module's id: no path or pattern holds it. */
+const FILES_SEPARATOR = "::";
+/** The query that asks for a story file's code: each story's `render` as written. */
+const CODE_QUERY = "?forgebook-code";
+/** The query that asks for a story file's component page: its documentation file as HTML. */
+const PAGE_QUERY = "?forgebook-page";
+/** The query a source's Markdown file is imported with (its introduction on the home), answered with its HTML. */
+const MARKDOWN_QUERY = "?forgebook-markdown";
+/** A TypeScript source file, whose edit may change a component's docs. */
+const SOURCE_FILE = /\.tsx?$/;
+/** The query that asks for a story file's component docs. */
+const DOCS_QUERY = "?forgebook-docs";
+/**
+ * The module that answers a `?forgebook-docs` import: the story file's component docs, or `{ error }` for the panel.
+ *
+ * @param component - what the extractor read for the story file.
+ * @param watch - adds a file whose edit renews the module.
+ */
+const docsModule = (component, watch) => {
+    // the docs come from the component's files, not the story file the id names: Vite renews them on an edit only if
+    // it watches those files too
+    if (typeof component !== "string" && "sources" in component) {
+        for (const file of component.sources)
+            watch(file);
+    }
+    const value = typeof component === "string" ? { error: component } : component.docs;
+    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
+};
+/**
+ * The module that answers a `?forgebook-code` import: each story's `render` text and its coloured HTML, or `{ error }`
+ * for the card.
+ *
+ * @param storyFile - the story file's absolute path; Vite renews the module when it changes, as the id names it.
+ */
+const codeModule = (storyFile) => {
+    const code = storyCode(storyFile, readFileSync(storyFile, "utf8"));
+    const value = typeof code === "string"
+        ? { error: code }
+        : Object.fromEntries(Object.entries(code).map(([name, text]) => [name, { text, html: highlightCode(text, "tsx") }]));
+    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
+};
+/**
+ * The file of a story file's component, from the meta's import, resolved as the app resolves it.
+ *
+ * @param storyFile - the story file's absolute path.
+ * @param resolve - resolves an import of the story file to its file; none when it does not resolve.
+ * @returns the component's file, or none when the meta names no imported component.
+ */
+const componentFileOf = async (storyFile, resolve) => {
+    const specifier = componentImport(storyFile, readFileSync(storyFile, "utf8"));
+    return specifier === undefined ? undefined : resolve(specifier);
+};
+/**
+ * The module that answers a `?forgebook-page` import: the component's documentation file as HTML (empty without
+ * one), and its file's summary, the first paragraph of its `@module` comment, for the page's lead.
+ *
+ * @remarks
+ * The summary is read here, from the component's file alone, rather than with the docs: the docs wait for the
+ * package's TypeScript program, and the lead would come seconds after the rest of the page.
+ *
+ * @param storyFile - the story file's absolute path.
+ * @param componentFile - the component's file, as the story file's import resolves; none when it names none.
+ * @param watch - adds a file whose edit renews the module (the documentation file, the component's file).
+ */
+const pageModule = (storyFile, componentFile, watch) => {
+    const page = componentPage(storyFile);
+    if (page !== undefined)
+        watch(page.file);
+    if (componentFile !== undefined)
+        watch(componentFile);
+    const summary = componentFile === undefined
+        ? ""
+        : moduleSummaryOf(ts.createSourceFile(componentFile, readFileSync(componentFile, "utf8"), ts.ScriptTarget.Latest, true));
+    const value = { html: page?.html ?? "", summary };
+    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
+};
+/**
+ * The module that answers a `?forgebook-markdown` import: a source's Markdown file (its introduction) as HTML.
+ *
+ * @param file - the Markdown file's absolute path.
+ * @param watch - adds a file whose edit renews the module (the Markdown file).
+ */
+const markdownModule = (file, watch) => {
+    watch(file);
+    const value = { html: markdownHtml(readFileSync(file, "utf8")) };
+    return { code: `export default ${JSON.stringify(value)};`, moduleType: "js" };
+};
+/**
+ * The module of a `?forgebook-files` pattern: every matched story file's index and loaders.
+ *
+ * @param id - the module's id (`FILES_PREFIX`, the importer's folder, `FILES_SEPARATOR`, the pattern).
+ * @param watch - adds a file whose edit renews the module (each story file).
+ * @param warm - builds the program that holds a story file, so the package's docs are ready before a page asks.
+ * @throws when a story file cannot be indexed.
+ */
+const patternModule = (id, watch, warm) => {
+    const [root = "", pattern = ""] = id.slice(FILES_PREFIX.length).split(FILES_SEPARATOR);
+    let first;
+    const code = storyFilesModule(root, pattern, (file) => {
+        first ??= file;
+        watch(file);
+    });
+    if (first !== undefined)
+        warm(first);
+    return { code, moduleType: "js" };
+};
+/** The resolved id of the configuration's data module. */
+const CONFIG_ID = `\0${CONFIG_MODULE}`;
+/**
+ * The page a request names, when it names one: `/` is the shell's.
+ *
+ * @param url - the request's address.
+ */
+const requestedPage = (url) => {
+    const path = url.split("?")[0] ?? "";
+    const name = path === "/" ? "index.html" : path.replace(/^\//, "");
+    return PAGE_FILES.find((page) => page === name);
+};
+/**
+ * A module the plugin answers from a file's text alone, when the id asks for one: a story file's code, or a Markdown
+ * file as HTML.
+ *
+ * @param id - the module's id.
+ * @param watch - adds a file whose edit renews the module.
+ */
+const textModule = (id, watch) => {
+    if (id.endsWith(CODE_QUERY))
+        return codeModule(id.slice(0, -CODE_QUERY.length));
+    if (id.endsWith(MARKDOWN_QUERY))
+        return markdownModule(id.slice(0, -MARKDOWN_QUERY.length), watch);
+    return undefined;
+};
+/**
+ * A module the plugin generates for a catalogue's pages, when the id names one: the configuration's data, an entry,
+ * the project's own stories' source, or a page's HTML (unless the folder has one of its own).
+ *
+ * @param id - the module's id.
+ * @param config - the catalogue's configuration.
+ */
+const generatedModule = (id, config) => {
+    if (id === CONFIG_ID)
+        return { code: configModule(config), moduleType: "js" };
+    if (id === join(config.dir, PAGE_ENTRIES["index.html"]))
+        return { code: shellEntry(config), moduleType: "js" };
+    if (id === join(config.dir, PAGE_ENTRIES["frame.html"]))
+        return { code: frameEntry(config), moduleType: "js" };
+    if (id === join(config.dir, STORIES_SOURCE_FILE))
+        return { code: storiesSourceModule(config), moduleType: "js" };
+    const page = PAGE_FILES.find((candidate) => id === join(config.dir, candidate));
+    return page !== undefined && !existsSync(id) ? pageHtml(page, config) : undefined;
+};
+/**
+ * The catalogue's Vite plugin: the story index, the docs, the code and the Markdown of the stories, the forced-states
+ * rewrite of every style sheet and, with a configuration, the catalogue's two pages.
+ *
+ * @param options - the configuration (read from Vite's root when not given), or the framework alone, and the folders
+ * to watch.
+ * @returns the plugin, for the app's `plugins`.
+ */
+export const forgebookPlugin = (options = {}) => {
+    /** The modules of the patterns, renewed when a story file is added or removed. */
+    const filesModules = new Set();
+    let config = options.config;
+    // the docs are read in a worker, made once the framework is known: a package's TypeScript program takes seconds to
+    // build and would hold every other answer of the dev server meanwhile
+    let docs;
+    const extractor = () => {
+        const framework = config?.framework ?? options.framework;
+        if (framework === undefined)
+            throw new Error("Forgebook has no framework: add forgebook.config.ts, or give the plugin `framework`");
+        docs ??= createDocsExtractor(framework.docsModule);
+        return docs;
+    };
+    const pagePath = (page) => config === undefined ? undefined : join(config.dir, page);
+    const entryPath = (page) => config === undefined ? undefined : join(config.dir, PAGE_ENTRIES[page]);
+    const storiesSource = () => config === undefined ? undefined : join(config.dir, STORIES_SOURCE_FILE);
+    /**
+     * A module a story file's query asks for (`?forgebook-docs`, `-code`, `-page`, `-markdown`), when the id is one.
+     *
+     * @param id - the module's id.
+     * @param watch - adds a file whose edit renews the module.
+     * @param resolveImport - resolves an import of a file as the app resolves it.
+     */
+    const queryModule = async (id, watch, resolveImport) => {
+        if (id.endsWith(DOCS_QUERY)) {
+            return docsModule(await extractor().extract(id.slice(0, -DOCS_QUERY.length)), watch);
+        }
+        if (id.endsWith(PAGE_QUERY)) {
+            const storyFile = id.slice(0, -PAGE_QUERY.length);
+            const componentFile = await componentFileOf(storyFile, (specifier) => resolveImport(specifier, storyFile));
+            return pageModule(storyFile, componentFile, watch);
+        }
+        return textModule(id, watch);
+    };
+    return {
+        name: "forgebook",
+        enforce: "pre",
+        config: async (userConfig) => {
+            if (config === undefined && options.framework === undefined) {
+                const file = findConfigFile(resolve(userConfig.root ?? process.cwd()));
+                if (file !== undefined)
+                    config = await loadConfigFile(file);
+            }
+            const pages = config === undefined
+                ? {}
+                : {
+                    root: config.dir,
+                    // the pages are generated, so Vite's scanner cannot find what they import: it is named here, and the
+                    // story files (the project's and the sources') are scanned for what their components import
+                    optimizeDeps: {
+                        include: prebundled(config, packageResolver(config.dir), packageResolver(PACKAGE_DIR)),
+                        entries: scannedEntries(config, packageResolver(config.dir), readTextFile)
+                    },
+                    build: {
+                        rolldownOptions: {
+                            input: { index: join(config.dir, "index.html"), frame: join(config.dir, "frame.html") }
+                        }
+                    }
+                };
+            return {
+                ...pages,
+                css: {
+                    transformer: "lightningcss",
+                    lightningcss: { visitor: FORCED_STATES_VISITOR },
+                    ...(await sassOptions())
+                }
+            };
+        },
+        resolveId(source, importer) {
+            if (source === CONFIG_MODULE)
+                return CONFIG_ID;
+            const entry = PAGE_FILES.find((page) => source === `/${PAGE_ENTRIES[page]}` || source === entryPath(page));
+            if (entry !== undefined)
+                return entryPath(entry) ?? null;
+            if (source === storiesSource())
+                return source;
+            const page = PAGE_FILES.find((candidate) => source === pagePath(candidate) || source === `/${candidate}`);
+            if (page !== undefined)
+                return pagePath(page) ?? null;
+            if (!source.endsWith(FILES_QUERY) || importer === undefined)
+                return null;
+            return `${FILES_PREFIX}${dirname(importer)}${FILES_SEPARATOR}${source.slice(0, -FILES_QUERY.length)}`;
+        },
+        configureServer: (server) => {
+            server.httpServer?.on("close", () => void docs?.close());
+            // an edited component or type file changes its docs: the worker renews its programs on their next read
+            server.watcher.on("change", (file) => {
+                if (SOURCE_FILE.test(file))
+                    docs?.changed();
+            });
+            // the catalogue's pages, made here: no HTML file is written
+            server.middlewares.use((request, response, next) => {
+                const page = requestedPage(request.url ?? "/");
+                if (config === undefined || page === undefined) {
+                    next();
+                    return;
+                }
+                server
+                    .transformIndexHtml(request.url ?? "/", pageHtml(page, config))
+                    .then((html) => {
+                    response.setHeader("Content-Type", "text/html");
+                    response.end(html);
+                })
+                    .catch(next);
+            });
+            const watched = [...(config?.watch ?? []), ...(options.watch ?? [])];
+            if (watched.length === 0)
+                return;
+            server.watcher.add(watched);
+            const refresh = (file) => {
+                if (!STORY_FILE.test(file))
+                    return;
+                const graph = server.environments.client.moduleGraph;
+                for (const id of filesModules) {
+                    const module = graph.getModuleById(id);
+                    if (module !== undefined)
+                        graph.invalidateModule(module);
+                }
+                server.ws.send({ type: "full-reload" });
+            };
+            server.watcher.on("add", refresh);
+            server.watcher.on("unlink", refresh);
+        },
+        closeBundle: async () => {
+            await docs?.close();
+        },
+        async load(id) {
+            const generated = config === undefined ? undefined : generatedModule(id, config);
+            if (generated !== undefined)
+                return generated;
+            const watch = (file) => this.addWatchFile(file);
+            const answered = await queryModule(id, watch, async (specifier, importer) => {
+                const resolved = await this.resolve(specifier, importer);
+                return resolved?.id;
+            });
+            if (answered !== undefined)
+                return answered;
+            if (!id.startsWith(FILES_PREFIX))
+                return null;
+            filesModules.add(id);
+            try {
+                return patternModule(id, watch, extractor().warm);
+            }
+            catch (error) {
+                this.error(error instanceof Error ? error.message : String(error));
+            }
+        }
+    };
+};
+//# sourceMappingURL=forgebookPlugin.js.map

package/dist/src/vite/forgebookPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebookPlugin.js","sourceRoot":"","sources":["../../../src/vite/forgebookPlugin.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,16 @@
+/** The class prefix of every coloured piece. */
+export declare const HIGHLIGHT_PREFIX = "forgebook-hl-";
+/**
+ * A text as HTML that shows it as written.
+ *
+ * @param text - the text.
+ */
+export declare const escapeHtml: (text: string) => string;
+/**
+ * Code as HTML, coloured when its language is known.
+ *
+ * @param code - the code.
+ * @param language - its language as a Markdown fence names it (`tsx`, `ts`, `scss`, `sh`); none leaves it plain.
+ */
+export declare const highlightCode: (code: string, language: string | undefined) => string;
+//# sourceMappingURL=highlightCode.d.ts.map

package/dist/src/vite/highlightCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlightCode.d.ts","sourceRoot":"","sources":["../../../src/vite/highlightCode.ts"],"names":[],"mappings":"AAuBA,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAoBhD;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MACiC,CAAC;AA0B5E;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,MAK1E,CAAC"}

package/dist/src/vite/highlightCode.js

@@ -0,0 +1,82 @@
+/**
+ * Code as coloured HTML, at build time: the code blocks of a component's documentation file and each story's
+ * `render`, so the page shows them coloured without a highlighter in the browser.
+ *
+ * @remarks
+ * The TypeScript family (TypeScript, TSX, JavaScript, JSX) is split by the TypeScript compiler
+ * (`typeScriptPieces.ts`): highlight.js reads JSX as HTML and loses the rest of the example at the first function or
+ * `>` in an attribute (D-690). highlight.js keeps the other languages a component's documentation writes (CSS, SCSS,
+ * JSON, bash, HTML), on its own instance, so nothing else that uses highlight.js in the same process sees these
+ * settings. Both write the same classes, with the catalogue's prefix (`forgebook-hl-keyword`), coloured by the
+ * shell's style sheet with its code palette. A language neither knows is escaped and left plain.
+ *
+ * @module
+ */
+import hljs from "highlight.js/lib/core";
+import bash from "highlight.js/lib/languages/bash";
+import css from "highlight.js/lib/languages/css";
+import json from "highlight.js/lib/languages/json";
+import scss from "highlight.js/lib/languages/scss";
+import xml from "highlight.js/lib/languages/xml";
+import { isTypeScriptLanguage, typeScriptPieces } from "./typeScriptPieces.js";
+/** The class prefix of every coloured piece. */
+export const HIGHLIGHT_PREFIX = "forgebook-hl-";
+/** The catalogue's own highlighter: the languages outside the TypeScript family a component's documentation writes. */
+const highlighter = hljs.newInstance();
+highlighter.configure({ classPrefix: HIGHLIGHT_PREFIX });
+highlighter.registerLanguage("xml", xml);
+highlighter.registerLanguage("css", css);
+highlighter.registerLanguage("scss", scss);
+highlighter.registerLanguage("json", json);
+highlighter.registerLanguage("bash", bash);
+/** The characters HTML gives a meaning to, as entities. */
+const ENTITIES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+};
+/**
+ * A text as HTML that shows it as written.
+ *
+ * @param text - the text.
+ */
+export const escapeHtml = (text) => text.replace(/[&<>"']/g, (character) => ENTITIES[character] ?? character);
+/**
+ * The classes of each role a TypeScript piece can have: the ones highlight.js gives the same thing, so the palette
+ * colours both alike.
+ */
+const ROLE_CLASSES = {
+    keyword: `${HIGHLIGHT_PREFIX}keyword`,
+    string: `${HIGHLIGHT_PREFIX}string`,
+    number: `${HIGHLIGHT_PREFIX}number`,
+    comment: `${HIGHLIGHT_PREFIX}comment`,
+    type: `${HIGHLIGHT_PREFIX}type`,
+    function: `${HIGHLIGHT_PREFIX}title function_`,
+    property: `${HIGHLIGHT_PREFIX}property`,
+    tag: `${HIGHLIGHT_PREFIX}name`,
+    attribute: `${HIGHLIGHT_PREFIX}attr`
+};
+/**
+ * A piece of code as HTML: escaped on its own, so a span never splits an entity.
+ *
+ * @param piece - the piece.
+ */
+const pieceHtml = ({ text, role }) => role === undefined ? escapeHtml(text) : `<span class="${ROLE_CLASSES[role]}">${escapeHtml(text)}</span>`;
+/**
+ * Code as HTML, coloured when its language is known.
+ *
+ * @param code - the code.
+ * @param language - its language as a Markdown fence names it (`tsx`, `ts`, `scss`, `sh`); none leaves it plain.
+ */
+export const highlightCode = (code, language) => {
+    if (language === undefined)
+        return escapeHtml(code);
+    if (isTypeScriptLanguage(language))
+        return typeScriptPieces(code, language).map(pieceHtml).join("");
+    if (highlighter.getLanguage(language) === undefined)
+        return escapeHtml(code);
+    return highlighter.highlight(code, { language, ignoreIllegals: true }).value;
+};
+//# sourceMappingURL=highlightCode.js.map

package/dist/src/vite/highlightCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlightCode.js","sourceRoot":"","sources":["../../../src/vite/highlightCode.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+/**
+ * A story file's index, read from its source without running it: the meta's title and the stories with their names,
+ * as Forgebook's and Storybook's files write them.
+ *
+ * @remarks
+ * The sidebar lists every story before any is loaded, so the index comes from the code itself, parsed with Vite's
+ * parser (the same files Vite compiles). It reads a meta written inline or as a constant (`export default meta`), a
+ * story as an object (CSF 3) or as a function with its properties assigned after it (CSF 2: `A.storyName`,
+ * `A.parameters`), named exports and re-exports (`export { A as B }`), `includeStories`, `excludeStories`,
+ * `__namedExportsOrder`, the meta's and the stories' `tags`, the TSDoc above a story, and `parameters.docs.description`.
+ *
+ * A value the index needs (the title, a name, `parameters.controls`, `group`, `height`, `main`, the meta's `alsoIn`,
+ * `related`, `keywords`) is read when written plainly; written by code, it is left to the frame, which reads it when
+ * the story loads. A title written by code, or none, is the file's path (`autoTitle`, as Storybook's auto-title); one
+ * written by code is also noted, since the author meant another. A value written plainly but wrongly
+ * (`controls: true`) is a problem. Pure: text in, index or problem out.
+ *
+ * @module
+ */
+import type { StoryFileIndex } from "@forgebook/story-format/source";
+/** What the index is given besides the file: the title its path makes, for a meta that writes none. */
+export type IndexOptions = {
+    /** The title from the file's path (`Inputs/Select`); none when the file's place gives none. */
+    readonly autoTitle?: string;
+};
+/**
+ * The index of one story file.
+ *
+ * @param file - the file's path, for the parser (its extension decides TypeScript and JSX) and the messages.
+ * @param text - the file's source.
+ * @param options - the title the file's path makes, for a meta that writes none.
+ * @returns the title and the stories, or a message saying why the file cannot be indexed.
+ */
+export declare const indexStoryFile: (file: string, text: string, options?: IndexOptions) => StoryFileIndex | string;
+//# sourceMappingURL=indexStoryFile.d.ts.map

package/dist/src/vite/indexStoryFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexStoryFile.d.ts","sourceRoot":"","sources":["../../../src/vite/indexStoryFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAwB,cAAc,EAAmB,MAAM,gCAAgC,CAAC;AAG5G,uGAAuG;AACvG,MAAM,MAAM,YAAY,GAAG;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAueF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,UAAS,YAAiB,KACzB,cAAc,GAAG,MA6BnB,CAAC"}