forgebook 0.1.7 → 0.2.0

package/dist/src/vite/componentImport.js

@@ -0,0 +1,35 @@
+/**
+ * Where a story file's component comes from, read with Vite's parser from the file alone: the plugin resolves it for
+ * the component's page, which answers at once, where the docs need the package's TypeScript program.
+ *
+ * @remarks
+ * The meta is read as the index reads it (`storyFileMeta`), so the forms the sidebar understands, a meta held in a
+ * constant or exported by name, give a page too; the dev server's thread loads no compiler for it.
+ *
+ * @module
+ */
+import { propertyValue } from "./indexFields.js";
+import { storyFileMeta } from "./indexStoryFile.js";
+import { parseStoryFile } from "./storyParse.js";
+/**
+ * The module a story file imports its meta's component from (`./Button`).
+ *
+ * @param storyFile - the story file's path, for the parser (its extension decides TypeScript and JSX).
+ * @param text - the story file's text.
+ * @returns the import's module specifier, or none when the meta names no imported component.
+ */
+export const componentImport = (storyFile, text) => {
+    const { program } = parseStoryFile(storyFile, text);
+    const meta = storyFileMeta(program);
+    const component = meta === undefined ? undefined : propertyValue(meta, "component");
+    if (component?.type !== "Identifier")
+        return undefined;
+    for (const statement of program.body) {
+        if (statement.type !== "ImportDeclaration")
+            continue;
+        const isImported = statement.specifiers.some(({ local }) => local.name === component.name);
+        if (isImported)
+            return statement.source.value;
+    }
+    return undefined;
+};

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

@@ -1,3 +1,17 @@
+import { type Tokens } from "marked";
+/**
+ * A Markdown code block as HTML, coloured when its fence names a language.
+ *
+ * @param token - the block.
+ */
+export declare const codeHtml: ({ text, lang }: Tokens.Code) => string;
+/**
+ * A page's anchors, made from its headings as GitHub makes them (`tokens`, `tokens-1`), so a link written for a
+ * repository's reader keeps working here. One per page: it counts the headings it saw.
+ *
+ * @returns what gives a heading's text its anchor.
+ */
+export declare const headingAnchors: () => ((text: string) => string);
 /** A component's page text, as HTML. */
 export type ComponentPageText = {
     /** The text. */
@@ -6,7 +20,7 @@ export type ComponentPageText = {
     readonly file: string;
 };
 /**
- * The documentation file beside a story file: its component's name in kebab case, with `.md`.
+ * The documentation file beside a story file: its component's name in kebab case, with `.md`, in Vite's form.
  *
  * @param storyFile - the story file's absolute path.
  */
@@ -31,4 +45,3 @@ export declare const markdownHtml: (text: string) => string;
  * @returns the HTML and the file it came from, or none when the component has no documentation file.
  */
 export declare const componentPage: (storyFile: string) => ComponentPageText | undefined;
-//# sourceMappingURL=componentPage.d.ts.map

package/dist/src/vite/componentPage.js

@@ -13,32 +13,71 @@
  * @module
  */
 import { existsSync, readFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename } from "node:path";
 import { Marked } from "marked";
-import { highlightCode } from "./highlightCode.js";
+import { headingElementId } from "../docAnchors.js";
+import { escapeHtml, highlightCode } from "./highlightCode.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/**
+ * A Markdown code block as HTML, coloured when its fence names a language.
+ *
+ * @param token - the block.
+ */
+export const codeHtml = ({ text, lang }) => {
+    const language = lang?.trim().split(/\s+/)[0] || undefined;
+    const languageClass = language === undefined ? "" : ` class="language-${escapeHtml(language)}"`;
+    return `<pre><code${languageClass}>${highlightCode(text, language)}</code></pre>\n`;
+};
 /** Markdown with GitHub's tables, its code blocks coloured. */
-const markdown = new Marked({
-    async: false,
-    gfm: true,
-    renderer: {
-        code: ({ text, lang }) => {
-            const language = lang?.trim().split(/\s+/)[0] || undefined;
-            const languageClass = language === undefined ? "" : ` class="language-${language}"`;
-            return `<pre><code${languageClass}>${highlightCode(text, language)}</code></pre>\n`;
+const markdown = new Marked({ async: false, gfm: true, renderer: { code: codeHtml } });
+/**
+ * A page's anchors, made from its headings as GitHub makes them (`tokens`, `tokens-1`), so a link written for a
+ * repository's reader keeps working here. One per page: it counts the headings it saw.
+ *
+ * @returns what gives a heading's text its anchor.
+ */
+export const headingAnchors = () => {
+    const seen = new Set();
+    return (text) => {
+        const slug = text
+            .toLowerCase()
+            .replace(/[^\p{L}\p{N}]+/gu, "-")
+            .replace(/^-|-$/g, "") || "section";
+        let anchor = slug;
+        // "Tokens", "Tokens", "Tokens 1": counting alone would give the last two the same anchor
+        for (let count = 1; seen.has(anchor); count += 1)
+            anchor = `${slug}-${count}`;
+        seen.add(anchor);
+        return anchor;
+    };
+};
+/** The Markdown of one component's page: its headings carry their anchors, and take the focus when a search opens one. */
+const componentPageRenderer = () => {
+    const anchorOf = headingAnchors();
+    return new Marked({
+        async: false,
+        gfm: true,
+        renderer: {
+            code: codeHtml,
+            heading({ tokens, depth }) {
+                const anchor = anchorOf(this.parser.parseInline(tokens, this.parser.textRenderer));
+                const id = escapeHtml(headingElementId(anchor));
+                return `<h${depth} id="${id}">${this.parser.parseInline(tokens)}</h${depth}>\n`;
+            }
         }
-    }
-});
+    });
+};
 /** The Markdown sections the page draws from the component's types instead. */
 const GENERATED_SECTIONS = ["Props"];
 /**
- * The documentation file beside a story file: its component's name in kebab case, with `.md`.
+ * The documentation file beside a story file: its component's name in kebab case, with `.md`, in Vite's form.
  *
  * @param storyFile - the story file's absolute path.
  */
 export const pageFileOf = (storyFile) => {
     const component = basename(storyFile).replace(/\.stories\.tsx?$/, "");
     const kebab = component.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-    return join(dirname(storyFile), `${kebab}.md`);
+    return VITE_PATHS.join(VITE_PATHS.dirname(storyFile), `${kebab}.md`);
 };
 /**
  * A Markdown text without its first `# ` title: the catalogue shows the name above it.
@@ -89,6 +128,6 @@ export const componentPage = (storyFile) => {
     const file = pageFileOf(storyFile);
     if (!existsSync(file))
         return undefined;
-    return { html: markdown.parse(pageMarkdown(readFileSync(file, "utf8")), { async: false }), file };
+    const html = componentPageRenderer().parse(pageMarkdown(readFileSync(file, "utf8")), { async: false });
+    return { html, file };
 };
-//# sourceMappingURL=componentPage.js.map

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

@@ -10,10 +10,13 @@
  *
  * @module
  */
-import type { StoryLanguage } from "@forgebook/story-format/source";
+import type { StoryLanguage, StoryTokensFile } from "@forgebook/story-format/source";
 import type { CatalogueLists } from "../catalogue.ts";
+import type { ForgebookPlugin } from "../plugin.ts";
+import type { ShellOptions } from "../shellTheme.types.ts";
 import type { ViewSwitch } from "../switches.ts";
 import type { FrameworkAdapter } from "./adapter.ts";
+import type { FramesOption } from "./framesConfig.ts";
 /** What a library's preset gives a catalogue. */
 export type ForgebookPreset = CatalogueLists & {
     /** The preset's name, in a problem's message (`acme-ui`). */
@@ -26,14 +29,21 @@ export type ForgebookPreset = CatalogueLists & {
     readonly preview?: string;
     /** Tags for every frame's `<head>`, before the catalogue's. */
     readonly head?: string;
+    /** The shell's look, under the catalogue's: its theme, and a style sheet by absolute path. */
+    readonly shell?: ShellOptions;
 };
+/** A tokens file: its path from the configuration's folder, with its theme when it is a theme's. */
+export type TokensFile = StoryTokensFile;
 /** A catalogue's configuration: the lists of `CatalogueLists` (widths, backgrounds, story groups…) besides these. */
 export type ForgebookConfig = CatalogueLists & {
     /** The framework its stories are written for (`react()` of `@forgebook/react/vite`). */
     readonly framework: FrameworkAdapter;
     /** Its name, in the page's title and the sidebar. */
     readonly title: string;
-    /** Its logo: a square image, by path from the configuration's folder; Forgebook's own mark by default. */
+    /**
+     * Its logo: a square image, by path from the configuration's folder; Forgebook's own mark by default, or its title
+     * alone with `shell: { branding: false }`.
+     */
     readonly logo?: string;
     /** The stories' measured heights, the file `forgebook-heights` writes, served from the public folder; none by default. */
     readonly heights?: string;
@@ -42,12 +52,31 @@ export type ForgebookConfig = CatalogueLists & {
      * named after the catalogue. Give `stories` or `sources`, or both.
      */
     readonly stories?: readonly string[];
+    /**
+     * The project's own docs pages, as globs from the configuration's folder (`["docs/**\/*.md"]`): Markdown with live
+     * stories, listed in the sidebar's Docs section, in the source named after the catalogue.
+     */
+    readonly docs?: readonly string[];
+    /**
+     * The catalogue's home, written by its authors: a Markdown file by path from the configuration's folder, read with
+     * the docs pages' syntax, with values (`{{components}}`) and pieces of the generated home (`::families`).
+     * `forgebook.home.md` beside the configuration when there; without either, or with `false`, the home is generated.
+     */
+    readonly home?: string | false;
     /** The packages' story sources, as module specifiers exporting a `source` (`["@acme/ui/stories"]`). */
     readonly sources?: readonly string[];
     /** The switches of the toolbar and the View menu; the theme and the contrast when neither it nor a preset declares any. */
     readonly switches?: readonly ViewSwitch[];
     /** The languages its stories can be drawn in; none turns the Language row off. */
     readonly languages?: readonly StoryLanguage[];
+    /** The shell's look: a theme of colours, fonts and corners, an escape hatch, and whether Forgebook's mark shows. */
+    readonly shell?: ShellOptions;
+    /**
+     * Its design tokens, DTCG 2025.10 files by path from the configuration's folder, the base first; a theme is a file of
+     * its own (`["tokens.json", { file: "dark.tokens.json", mode: "dark" }]`). What tools and agents read tokens from,
+     * after each source's: a name given twice takes the catalogue's value, and tools report the clash.
+     */
+    readonly tokens?: readonly TokensFile[];
     /** Its preview's path from the configuration's folder; `forgebook.preview.ts` (or `.tsx`) beside it when there. */
     readonly preview?: string;
     /** Tags for every frame's `<head>` (a font's link); none by default. */
@@ -56,6 +85,26 @@ export type ForgebookConfig = CatalogueLists & {
     readonly watch?: readonly string[];
     /** The libraries' presets, in order; the configuration's own values win over theirs. */
     readonly presets?: readonly ForgebookPreset[];
+    /** The plugins, in order (`[figma()]`): a package adds nothing to the catalogue until it is listed here. */
+    readonly plugins?: readonly ForgebookPlugin[];
+    /**
+     * Where the stories' frames run. On the dev server, an origin of their own by default (the catalogue's port + 1), so
+     * a story's code cannot reach the catalogue's page, its agent API or the project's files; a build keeps the
+     * catalogue's origin unless `origins` names a second host. `"same-origin"` runs them on the catalogue's origin.
+     */
+    readonly frames?: FramesOption;
+    /** How `forgebook build` writes the catalogue. */
+    readonly build?: BuildOptions;
+};
+/** How `forgebook build` writes the catalogue. */
+export type BuildOptions = {
+    /**
+     * Whether each script a build writes is named after its module as well as its hash (`assets/Button-3f9a1c2b.js`), for
+     * whoever reads a build's files; `false` by default: its hash alone (`assets/3f9a1c2b.js`), since a catalogue names
+     * each story file's scripts once per loader, and the names are a tenth of what its index weighs.
+     * `forgebook build --readable-names` turns it on for one build.
+     */
+    readonly readableNames?: boolean;
 };
 /**
  * A catalogue's configuration, typed: what `forgebook.config.ts` exports by default.
@@ -69,4 +118,3 @@ export declare const defineConfig: (config: ForgebookConfig) => ForgebookConfig;
  * @param preset - the preset.
  */
 export declare const definePreset: (preset: ForgebookPreset) => ForgebookPreset;
-//# sourceMappingURL=config.d.ts.map

package/dist/src/vite/config.js

@@ -22,4 +22,3 @@ export const defineConfig = (config) => config;
  * @param preset - the preset.
  */
 export const definePreset = (preset) => preset;
-//# sourceMappingURL=config.js.map

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

@@ -1,11 +1,53 @@
+/**
+ * A catalogue's configuration file read: found in its folder, loaded, checked, and merged with its presets, as the
+ * plugin and the `forgebook` command use it.
+ *
+ * @remarks
+ * Node loads the file with its types stripped (`forgebook.config.ts`, `.mts` or `.js`). A preset's switches,
+ * languages and head come before the catalogue's, and a switch or language the catalogue declares with the same id
+ * replaces the preset's; its preview sits under the catalogue's. Every problem is named with the file it comes from.
+ *
+ * @module
+ */
 import type { StoryLanguage } from "@forgebook/story-format/source";
 import type { CatalogueLists } from "../catalogue.ts";
+import type { ForgebookPlugin } from "../plugin.ts";
 import { type ViewSwitch } from "../switches.ts";
 import type { FrameworkAdapter } from "./adapter.ts";
-import type { ForgebookConfig } from "./config.ts";
+import type { BuildOptions, ForgebookConfig } from "./config.ts";
+import { type ResolvedFrames } from "./framesConfig.ts";
+import { type VitePaths } from "./vitePaths.ts";
 /** The names a configuration file may have, in the order they are looked for. */
 export declare const CONFIG_FILES: string[];
-/** A configuration ready for the pages: its folder, its presets merged, its paths absolute. */
+/**
+ * The name the written home has beside the configuration. Prefixed as the preview is, so a `home.md` a project
+ * keeps for another reason never replaces the generated home of a catalogue that did not ask for it.
+ */
+export declare const HOME_FILE = "forgebook.home.md";
+/** The shell's look, ready for its page. */
+export type ResolvedShell = {
+    /** The theme, as CSS; empty for none. */
+    readonly themeCss: string;
+    /** What the frames need of the theme, as CSS; empty for none. */
+    readonly frameCss: string;
+    /** Whether Forgebook's mark stands in for a catalogue without a logo. */
+    readonly hasBranding: boolean;
+    /** The style sheets it loads after its own, absolute, the presets' first. */
+    readonly styleSheets: readonly string[];
+    /** What in the theme will not work, for a warning. */
+    readonly problems: readonly string[];
+};
+/** A tokens file, its path absolute. */
+export type ResolvedTokensFile = {
+    /** The file's absolute path. */
+    readonly path: string;
+    /** The theme it belongs to; none for the base. */
+    readonly mode: string | undefined;
+};
+/**
+ * A configuration ready for the pages: its folder, its presets merged, its paths absolute and in Vite's form (forward
+ * slashes on every system, `vitePaths.ts`), so they compare with Vite's ids and can be written into generated code.
+ */
 export type ResolvedConfig = {
     /** The folder the configuration file is in: Vite's root. */
     readonly dir: string;
@@ -13,12 +55,16 @@ export type ResolvedConfig = {
     readonly framework: FrameworkAdapter;
     /** The catalogue's name. */
     readonly title: string;
-    /** The logo's absolute path; none for Forgebook's own mark. */
+    /** The logo's absolute path; none for Forgebook's own mark, or the title alone without branding. */
     readonly logo: string | undefined;
     /** The heights file's address, relative to the pages. */
     readonly heights: string | undefined;
     /** The project's own story globs, from the configuration's folder. */
     readonly stories: readonly string[];
+    /** The project's own docs pages' globs, from the configuration's folder. */
+    readonly docs: readonly string[];
+    /** The written home's absolute path; none for the generated home. */
+    readonly home: string | undefined;
     /** The sources' module specifiers. */
     readonly sources: readonly string[];
     /** The switches, the presets' and the catalogue's merged; none when neither declares any. */
@@ -29,12 +75,22 @@ export type ResolvedConfig = {
     readonly previews: readonly string[];
     /** The tags for every frame's `<head>`. */
     readonly head: string;
+    /** The shell's look, the presets' and the catalogue's merged. */
+    readonly shell: ResolvedShell;
+    /** The tokens files, absolute, the base first. */
+    readonly tokens: readonly ResolvedTokensFile[];
     /** The folders the dev server watches for new story files, absolute. */
     readonly watch: readonly string[];
     /** The lists (widths, backgrounds, story groups…), the presets' and the catalogue's merged. */
     readonly lists: CatalogueLists;
     /** Whether the project installs Testing Library, whose `canvas` and `userEvent` every play then receives. */
     readonly hasPlayTools: boolean;
+    /** The plugins, checked, in the configuration's order. */
+    readonly plugins: readonly ForgebookPlugin[];
+    /** Where the stories' frames run. */
+    readonly frames: ResolvedFrames;
+    /** How `forgebook build` writes the catalogue, every option given its default. */
+    readonly build: Required<BuildOptions>;
 };
 /** The packages of the play tools: both installed, or the plays get neither. */
 export declare const PLAY_TOOLS_PACKAGES: readonly ["@testing-library/dom", "@testing-library/user-event"];
@@ -53,20 +109,21 @@ export declare const findConfigFile: (dir: string) => string | undefined;
 /**
  * The lists of the presets and the catalogue, in that order, merged: a single value (a width range, the grid's step)
  * the last that gives one; the backgrounds, the story groups and the texts entry by entry, a later one replacing an
- * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar the last
- * that names one.
+ * earlier one with the same id or name; the tabs, the controls and the rules turned off by any; the toolbar and the
+ * prop groups' order the last that names one; the device field by field.
  *
  * @param all - the presets' lists, then the catalogue's.
  */
 export declare const mergedLists: (all: readonly CatalogueLists[]) => CatalogueLists;
 /**
- * A configuration with its presets merged and its paths made absolute.
+ * A configuration with its presets merged and its paths made absolute, in Vite's form.
  *
  * @param config - the configuration.
- * @param dir - the folder of its file.
+ * @param fileDir - the folder of its file.
+ * @param paths - the path functions; the running system's unless a test names another.
  * @throws when the merged switches cannot be used.
  */
-export declare const resolveConfig: (config: ForgebookConfig, dir: string) => ResolvedConfig;
+export declare const resolveConfig: (config: ForgebookConfig, fileDir: string, paths?: VitePaths) => ResolvedConfig;
 /**
  * Loads a configuration file and resolves it.
  *
@@ -74,4 +131,3 @@ export declare const resolveConfig: (config: ForgebookConfig, dir: string) => Re
  * @throws when the file does not load, or exports no usable configuration.
  */
 export declare const loadConfigFile: (file: string) => Promise<ResolvedConfig>;
-//# sourceMappingURL=configFile.d.ts.map