forgebook 0.1.8 → 0.3.0

package/dist/src/vite/codeFence.js

@@ -0,0 +1,267 @@
+import { highlightCode } from "./highlightCode.js";
+/** The class of every line of a block whose lines are elements. */
+const LINE_CLASS = "forgebook-code-line";
+/** A fence's line split into words: a quoted value or braces stay whole. */
+const fenceWords = (info) => {
+    const words = [];
+    const pattern = /(?:[^\s"'{=]+(?:=(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|\{[^}]*\}|[^\s]*))?|\{[^}]*\}|"[^"]*"|\S+)/g;
+    for (const match of info.matchAll(pattern))
+        words.push({ text: match[0], offset: match.index });
+    return words;
+};
+/** The highest line a fence may name. */
+const MAX_LINE = 100_000;
+/**
+ * The lines a range list names: `1,4-6` is 1, 4, 5 and 6.
+ *
+ * @param text - the list, without its braces.
+ * @returns the lines, or none when the list cannot be read.
+ */
+const rangeLines = (text) => {
+    const lines = new Set();
+    for (const part of text.split(",")) {
+        const range = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+        if (range?.[1] === undefined)
+            return undefined;
+        const from = Number(range[1]);
+        const to = range[2] === undefined ? from : Number(range[2]);
+        // a range no code can hold is a mistake, and would fill the set with millions of lines
+        if (from < 1 || to < from || to > MAX_LINE)
+            return undefined;
+        for (let line = from; line <= to; line += 1)
+            lines.add(line);
+    }
+    return lines;
+};
+/** A value without its quotes or braces, its escapes read. */
+const bareValue = (value) => {
+    const first = value.charAt(0);
+    if ((first === '"' || first === "'") && value.endsWith(first) && value.length > 1)
+        return value.slice(1, -1).replace(/\\(.)/g, "$1");
+    return value;
+};
+/** The words that name lines, and the set each fills. */
+const RANGE_KEYS = {
+    mark: "marked",
+    ins: "inserted",
+    del: "deleted"
+};
+/**
+ * Adds the lines a `{1,4-6}` list names to a set, or notes that it is no list.
+ *
+ * @param target - the set.
+ * @param value - the list, with its braces.
+ * @param position - where it starts, for the note.
+ * @param notes - receives what cannot be read.
+ */
+const addRanges = (target, value, position, notes) => {
+    const lines = value.startsWith("{") && value.endsWith("}") ? rangeLines(value.slice(1, -1)) : undefined;
+    if (lines === undefined) {
+        notes.push({ position, message: `"${value}" is not a list of lines: write {1,4-6}` });
+        return;
+    }
+    for (const line of lines)
+        target.add(line);
+};
+/**
+ * Reads one word of a fence's line into what it says.
+ *
+ * @param word - the word.
+ * @param isDiff - whether the fence is a diff, the one that takes `lang`.
+ * @param reading - what the line says so far.
+ * @param at - the position of a place of the line.
+ * @param notes - receives what cannot be read.
+ */
+const readFenceWord = ({ text, offset }, isDiff, reading, at, notes) => {
+    if (text.startsWith("{")) {
+        addRanges(reading.marked, text, at(offset), notes);
+        return;
+    }
+    if (text === "wrap") {
+        reading.isWrapped = true;
+        return;
+    }
+    const equals = text.indexOf("=");
+    const key = equals === -1 ? text : text.slice(0, equals);
+    const value = equals === -1 ? "" : text.slice(equals + 1);
+    const range = RANGE_KEYS[key];
+    if (range !== undefined) {
+        addRanges(reading[range], value, at(offset + equals + 1), notes);
+        return;
+    }
+    if (key === "title" && value !== "") {
+        reading.title = bareValue(value);
+        return;
+    }
+    if (key === "lang" && isDiff && value !== "") {
+        reading.language = bareValue(value);
+        return;
+    }
+    const hint = key === "lang"
+        ? '`lang` goes with a diff (```diff lang="tsx")'
+        : 'it reads title="…", {1,4-6}, ins={…}, del={…} and wrap';
+    notes.push({ position: at(offset), message: `the code fence's "${text}" is not read: ${hint}` });
+};
+/**
+ * What a code fence's line says, every word it does not read reported where it is.
+ *
+ * @param info - the line after the backticks.
+ * @param start - where the line starts in the file, for the notes.
+ * @param notes - receives what cannot be read.
+ */
+export const fenceInfo = (info, start, notes) => {
+    const at = (offset) => ({ line: start.line, column: start.column + offset });
+    const words = fenceWords(info);
+    const first = words[0];
+    const named = first !== undefined && first.text !== "wrap" && !first.text.includes("=") && !/^[{"]/.test(first.text)
+        ? first.text
+        : undefined;
+    const isDiff = named === "diff";
+    const reading = {
+        language: isDiff ? undefined : named,
+        title: undefined,
+        isWrapped: false,
+        marked: new Set(),
+        inserted: new Set(),
+        deleted: new Set()
+    };
+    for (const word of named === undefined ? words : words.slice(1))
+        readFenceWord(word, isDiff, reading, at, notes);
+    return { ...reading, isDiff };
+};
+/**
+ * Coloured HTML split at its lines, every span closed at a line's end and opened again on the next, so each line can
+ * be an element of its own.
+ *
+ * @param html - the coloured code.
+ */
+export const htmlLines = (html) => {
+    const lines = [];
+    const open = [];
+    let current = "";
+    for (const part of html.split(/(<span[^>]*>|<\/span>|\n)/)) {
+        if (part === "\n") {
+            lines.push(current + "</span>".repeat(open.length));
+            current = open.join("");
+        }
+        else if (part.startsWith("<span")) {
+            open.push(part);
+            current += part;
+        }
+        else if (part === "</span>") {
+            open.pop();
+            current += part;
+        }
+        else
+            current += part;
+    }
+    lines.push(current);
+    return lines;
+};
+/** The kind of line each sign of a diff starts. */
+const DIFF_SIGNS = { "+": "ins", "-": "del" };
+/** A patch's file headers (`--- a/x`, `+++ b/x`): plain lines, never a deletion or an insertion. */
+const PATCH_HEADER = /^(---|\+\+\+)( |$)/;
+/**
+ * A diff's lines and the kind of each. A diff in a language (`lang="tsx"`) is code whose signs come off, so it is
+ * coloured and copied as code; one without is a patch, kept as written, so what is copied still applies.
+ *
+ * @param code - the diff.
+ * @param isCode - whether its signs come off.
+ */
+const diffLines = (code, isCode) => {
+    const kinds = [];
+    const lines = code.split("\n").map((line) => {
+        const sign = line.charAt(0);
+        kinds.push(PATCH_HEADER.test(line) ? "plain" : (DIFF_SIGNS[sign] ?? "plain"));
+        return isCode && (sign === "+" || sign === "-" || sign === " ") ? line.slice(1) : line;
+    });
+    return { code: lines.join("\n"), kinds };
+};
+/** Whether a fence is a diff of code in a language, whose signs come off: a diff without one is a patch. */
+const isCodeDiff = (info) => info.isDiff && info.language !== undefined;
+/** A line as an element of its kind. */
+const lineElement = (html, kind) => {
+    const element = kind === "plain" ? "span" : kind;
+    return `<${element} class="${LINE_CLASS}">${html}</${element}>`;
+};
+/**
+ * Each line coloured, the code before the change and after it apart: a deleted line that leaves a string or a comment
+ * open would otherwise colour the inserted line after it as part of it.
+ *
+ * @param code - the code, its diff signs taken off.
+ * @param kinds - each line's kind.
+ * @param language - the language it is coloured in.
+ */
+const coloredLines = (code, kinds, language) => {
+    const lines = code.split("\n");
+    if (!kinds.includes("del"))
+        return htmlLines(highlightCode(code, language));
+    const version = (left) => {
+        const places = lines.flatMap((_line, index) => (kinds[index] === left ? [] : [index]));
+        const html = htmlLines(highlightCode(places.map((index) => lines[index] ?? "").join("\n"), language));
+        return { places, html };
+    };
+    const coloured = [];
+    for (const { places, html } of [version("ins"), version("del")]) {
+        places.forEach((index, at) => {
+            coloured[index] ??= html[at] ?? "";
+        });
+    }
+    return lines.map((_line, index) => coloured[index] ?? "");
+};
+/**
+ * A diff's code without its signs, or the code itself.
+ *
+ * @param code - the code as the fence holds it.
+ * @param info - what its fence's line says.
+ */
+const shownCode = (code, info) => info.isDiff ? diffLines(code, isCodeDiff(info)).code : code;
+/**
+ * The first line a fence names that its code does not have; none when every line it names is there.
+ *
+ * @param code - the code as the fence holds it.
+ * @param info - what its fence's line says.
+ * @returns the line, and how many the code has.
+ */
+export const missingLine = (code, info) => {
+    const count = shownCode(code, info).split("\n").length;
+    const beyond = [...info.marked, ...info.inserted, ...info.deleted].filter((line) => line > count);
+    return beyond.length === 0 ? undefined : { line: Math.min(...beyond), count };
+};
+/**
+ * A fenced block's code as the page draws it.
+ *
+ * @param code - the code as the fence holds it.
+ * @param info - what its fence's line says.
+ */
+export const fencedCode = (code, info) => {
+    const diff = info.isDiff ? diffLines(code, isCodeDiff(info)) : undefined;
+    const plain = shownCode(code, info);
+    const base = { language: info.language, title: info.title, isWrapped: info.isWrapped };
+    if (diff === undefined && info.marked.size + info.inserted.size + info.deleted.size === 0) {
+        return { ...base, text: code, html: highlightCode(code, info.language) };
+    }
+    const kinds = plain.split("\n").map((_line, index) => {
+        const line = index + 1;
+        if (info.deleted.has(line))
+            return "del";
+        if (info.inserted.has(line))
+            return "ins";
+        if (info.marked.has(line))
+            return "mark";
+        return diff?.kinds[index] ?? "plain";
+    });
+    const html = coloredLines(plain, kinds, info.language)
+        .map((line, index) => lineElement(line, kinds[index] ?? "plain"))
+        .join("\n");
+    // a patch is copied whole, to apply; code is copied as it reads after the change
+    const isPatch = info.isDiff && !isCodeDiff(info);
+    const text = isPatch
+        ? plain
+        : plain
+            .split("\n")
+            .filter((_line, index) => kinds[index] !== "del")
+            .join("\n");
+    return { ...base, text, html };
+};

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

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const componentImport: (storyFile: string, text: string) => string | undefined;

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