forgebook 0.1.8 → 0.3.0

package/dist/bin/forgebook-docs/catalogueMarkdown.js

@@ -1,4 +1,4 @@
-import { storyId } from "../../src/storyTree.js";
+import { pageSlug } from "../../src/pageAddress.js";
 /** The props whose keys are the parts. */
 const PART_MAPS = ["classNames", "styles", "refs"];
 /** A prop in short. */
@@ -49,10 +49,11 @@ const componentLine = (packageName, component, sourceId) => {
             .map(shortProp)
             .join(" ");
     const parts = docs.parts.length === 0 ? "" : ` · parts: ${docs.parts.join(", ")}`;
-    const story = sourceId === undefined || component.mainStory === undefined
+    const story = sourceId === undefined || component.mainStoryId === undefined
         ? ""
-        : ` · story: \`${storyId(sourceId, component.title, component.mainStory)}\``;
-    return `- **${docs.name}**${where}: ${sentence(docs.description)}. ${props}${parts}${story}`;
+        : ` · story: \`${sourceId}:${component.mainStoryId}\``;
+    const design = component.design === undefined ? "" : ` · design: ${component.design}`;
+    return `- **${docs.name}**${where}: ${sentence(docs.description)}. ${props}${parts}${story}${design}`;
 };
 /** Letters and digits only, lower case: how a subpath and an export name are compared. */
 const comparable = (text) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -96,22 +97,68 @@ const byPlace = (left, right) => {
         leftGroup.localeCompare(rightGroup) ||
         leftName.localeCompare(rightName));
 };
+/** One docs page's line, ending with its id when the package's source id is known. */
+const pageLine = (page, sourceId) => {
+    const about = page.description === undefined ? "" : `: ${sentence(page.description)}`;
+    const id = sourceId === undefined ? "" : ` · page: \`${sourceId}:${pageSlug(page.title)}\``;
+    return `- **${page.title}** \`${page.file}\`${about}${id}`;
+};
+/** Text on one line, whatever its file wrote, since an entry is one line. */
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+/** One token's line: its value, each theme's, what it aliases, what it is for and why not to use it. */
+const tokenLine = (token) => {
+    const facts = [
+        `\`${oneLine(token.value)}\``,
+        ...Object.entries(token.modes).map(([mode, value]) => `${oneLine(mode)} \`${oneLine(value)}\``),
+        ...(token.isThemeOnly === true ? ["only in themes"] : []),
+        ...(token.alias === undefined ? [] : [`alias of \`${oneLine(token.alias)}\``]),
+        ...(token.description === undefined ? [] : [sentence(oneLine(token.description))]),
+        ...(token.deprecated === undefined ? [] : [`deprecated: ${sentence(oneLine(token.deprecated))}`])
+    ];
+    return `- \`${oneLine(token.name)}\`: ${facts.join(" · ")}`;
+};
+/** The tokens' lines, by type, each type in the order the files first give it; none when the package has none. */
+const tokenLines = (tokens) => {
+    if (tokens.length === 0)
+        return [];
+    const types = [...new Set(tokens.map((token) => token.type))];
+    return [
+        "## Tokens",
+        "",
+        "Write a token, not its value: each line gives its value, then its value in each theme.",
+        "",
+        ...types.flatMap((type) => [
+            `### ${oneLine(type)}`,
+            ...tokens.filter((token) => token.type === type).map(tokenLine)
+        ]),
+        ""
+    ];
+};
+/** The components' lines, by family and group. */
+const componentLines = (data) => {
+    const lines = ["## Components", ""];
+    if (data.components.length === 0)
+        return [...lines, "None yet.", ""];
+    let heading = "";
+    for (const component of [...data.components].sort(byPlace)) {
+        const group = component.title.split("/").slice(0, -1).join(" › ");
+        if (group !== heading) {
+            lines.push(`### ${group}`);
+            heading = group;
+        }
+        lines.push(componentLine(data.packageName, component, data.sourceId));
+    }
+    return [...lines, ""];
+};
 /** The lines of one kind of entries, a heading first; none when the package has none of it. */
 const sectionLines = (data, section) => {
-    if (section === "components") {
-        const lines = ["## Components", ""];
-        if (data.components.length === 0)
-            return [...lines, "None yet.", ""];
-        let heading = "";
-        for (const component of [...data.components].sort(byPlace)) {
-            const group = component.title.split("/").slice(0, -1).join(" › ");
-            if (group !== heading) {
-                lines.push(`### ${group}`);
-                heading = group;
-            }
-            lines.push(componentLine(data.packageName, component, data.sourceId));
-        }
-        return [...lines, ""];
+    if (section === "components")
+        return componentLines(data);
+    if (section === "pages") {
+        const pages = data.pages ?? [];
+        if (pages.length === 0)
+            return [];
+        return ["## Docs", "", ...pages.map((page) => pageLine(page, data.sourceId)), ""];
     }
     if (section === "modules") {
         if (data.modules.length === 0)
@@ -134,6 +181,8 @@ const sectionLines = (data, section) => {
             ""
         ];
     }
+    if (section === "tokens")
+        return tokenLines(data.tokens);
     if (data.styleSheets.length === 0)
         return [];
     return [
@@ -165,4 +214,3 @@ export const catalogueMarkdown = (data, sections) => {
     ];
     return `${lines.join("\n").trimEnd()}\n`;
 };
-//# sourceMappingURL=catalogueMarkdown.js.map

package/dist/bin/forgebook-docs/catalogueOptions.d.ts

@@ -5,7 +5,7 @@
  * @module
  */
 /** The kinds of entries the file lists, in the order they are written by default. */
-export declare const CATALOGUE_SECTIONS: readonly ["components", "modules", "sassModules", "styleSheets"];
+export declare const CATALOGUE_SECTIONS: readonly ["components", "pages", "modules", "sassModules", "styleSheets", "tokens"];
 /** One kind of entries. */
 export type CatalogueSection = (typeof CATALOGUE_SECTIONS)[number];
 /** How a package's `CATALOG.md` is written. */
@@ -36,4 +36,3 @@ export declare const catalogueOptionsOf: (manifest: unknown) => {
  * @param exclude - the options' `exclude`.
  */
 export declare const isExcluded: (subpath: string, exclude: readonly string[]) => boolean;
-//# sourceMappingURL=catalogueOptions.d.ts.map

package/dist/bin/forgebook-docs/catalogueOptions.js

@@ -5,7 +5,14 @@
  * @module
  */
 /** The kinds of entries the file lists, in the order they are written by default. */
-export const CATALOGUE_SECTIONS = ["components", "modules", "sassModules", "styleSheets"];
+export const CATALOGUE_SECTIONS = [
+    "components",
+    "pages",
+    "modules",
+    "sassModules",
+    "styleSheets",
+    "tokens"
+];
 /** The options of a package that sets none. */
 export const DEFAULT_CATALOGUE_OPTIONS = {
     file: "CATALOG.md",
@@ -73,4 +80,3 @@ export const catalogueOptionsOf = (manifest) => {
  * @param exclude - the options' `exclude`.
  */
 export const isExcluded = (subpath, exclude) => exclude.some((pattern) => pattern.endsWith("*") ? subpath.startsWith(pattern.slice(0, -1)) : subpath === pattern);
-//# sourceMappingURL=catalogueOptions.js.map

package/dist/bin/forgebook-docs/collectDocs.d.ts

@@ -5,7 +5,7 @@ import { type CatalogueOptions } from "./catalogueOptions.ts";
 export type CollectedDocs = {
     /** The catalogue's data. */
     readonly data: CatalogueData;
-    /** One message per file that could not be read. */
+    /** One message per thing that could not be read: a file, a token. */
     readonly problems: readonly string[];
 };
 /**
@@ -13,7 +13,7 @@ export type CollectedDocs = {
  *
  * @param packageDir - the package's folder.
  * @param extractStoryComponent - the framework's reading of a story file's component (its docs module).
- * @param options - the package's catalogue options: the subpaths it leaves out.
+ * @param options - the package's catalogue options: the subpaths it leaves out, and the sections it lists, which leave
+ *   the tokens unread when they do not name them (every section by default).
  */
-export declare const collectDocs: (packageDir: string, extractStoryComponent: ExtractStoryComponent, options: Pick<CatalogueOptions, "exclude">) => CollectedDocs;
-//# sourceMappingURL=collectDocs.d.ts.map
+export declare const collectDocs: (packageDir: string, extractStoryComponent: ExtractStoryComponent, options: Pick<CatalogueOptions, "exclude"> & Partial<Pick<CatalogueOptions, "sections">>) => CollectedDocs;

package/dist/bin/forgebook-docs/collectDocs.js

@@ -1,22 +1,28 @@
 /**
- * What `forgebook-docs` reads from a package: its exports, their TSDoc and types, its stories, its Sass modules and
- * style sheets.
+ * What `forgebook-docs` reads from a package: its exports, their TSDoc and types, its stories, its Sass modules, its
+ * style sheets and the design tokens its source declares.
  *
  * @remarks
  * The package's `exports` (the source map, `./src/…`) say what is public; its `*.stories.tsx` say which components
  * exist and where they sit. Components are read with the catalogue's extractor (the props panel's data), modules with
- * TypeScript 6, Sass modules and style sheets from their text. The development-only `./stories` export is left out.
+ * TypeScript 6, Sass modules and style sheets from their text. The development-only `./stories` export is left out of
+ * the lists; the id and the tokens of the source it declares are read from its text.
  *
  * @module
  */
 import { globSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { csfStoryId } from "../../src/storyIds.js";
 import { autoTitle, STORY_FILE } from "../../src/vite/autoTitle.js";
+import { readLinkedFile } from "../../src/vite/docPageLinks.js";
+import { indexedDocPages } from "../../src/vite/docPagesModule.js";
 import { indexStoryFile } from "../../src/vite/indexStoryFile.js";
+import { readTokenFiles, sourceTokensIn } from "../../src/vite/sourceTokens.js";
+import { VITE_PATHS } from "../../src/vite/vitePaths.js";
 import { isExcluded } from "./catalogueOptions.js";
 import { moduleDocs } from "./moduleDocs.js";
 import { sassMembers, styleSheetSummary } from "./sassDocs.js";
-import { sourceIdOf } from "./sourceId.js";
+/** Whether a folder's name is one whose story files are not the package's own: its dependencies, its build. */
+const isLeftOutFolder = (name) => name === "node_modules" || name === "dist";
 /** The subpath that is never published: the package's stories for a catalogue. */
 const STORIES_SUBPATH = "./stories";
 /** A package's `exports`, as written: subpath → source. */
@@ -34,16 +40,53 @@ const sourceExports = (manifest) => {
  * @param index - the file's index.
  */
 const isLogicFile = (index) => index.stories.length > 0 && index.stories.every((story) => (story.isLogic ?? index.isLogic) === true);
+/**
+ * A story file's main story (`parameters.main`, else its first): its export and its id without the source's.
+ *
+ * @param index - the file's index.
+ */
+const mainStoryOf = (index) => {
+    const main = index.stories.find((story) => story.isMain === true) ?? index.stories[0];
+    if (main === undefined)
+        return { mainStory: undefined, mainStoryId: undefined };
+    return {
+        mainStory: main.exportName,
+        mainStoryId: main.id ?? csfStoryId(index.id ?? index.title, main.exportName)
+    };
+};
+/**
+ * Adds a story file's component to the list, or its stories to the component of its title already listed: files with
+ * one title are one component, as the catalogue lists them, with the first file's docs and main story.
+ *
+ * @param components - the components so far.
+ * @param component - the file's.
+ */
+const addComponent = (components, component) => {
+    const same = components.findIndex((each) => each.title === component.title);
+    const first = components[same];
+    if (first === undefined) {
+        components.push(component);
+        return;
+    }
+    components[same] = {
+        ...first,
+        stories: [...first.stories, ...component.stories],
+        isLogic: first.isLogic && component.isLogic
+    };
+};
 /** The components of the package's story files, read by the framework's extractor. */
 const collectComponents = (packageDir, exports, problems, extractStoryComponent, exclude) => {
     const components = [];
     const componentFiles = new Set();
-    const storyFiles = globSync("**/*.stories.*", { cwd: packageDir })
+    // with forward slashes: the glob gives backslashes on Windows, and the folders and the title are read by `/`
+    // the dependencies and the build are never walked: a package's node_modules alone can hold thousands of folders
+    const storyFiles = globSync("**/*.stories.*", { cwd: packageDir, exclude: isLeftOutFolder })
+        .map((file) => VITE_PATHS.normalize(file))
         .filter((file) => STORY_FILE.test(file))
-        .filter((file) => !file.split("/").some((segment) => segment === "node_modules" || segment === "dist"))
+        .filter((file) => !file.split("/").some(isLeftOutFolder))
         .sort();
     for (const relative of storyFiles) {
-        const file = join(packageDir, relative);
+        const file = VITE_PATHS.join(packageDir, relative);
         // a meta without a title is placed by its path from the package's folder: the catalogue's patterns are not known
         const title = autoTitle("", relative);
         const options = title === undefined ? {} : { autoTitle: title };
@@ -55,19 +98,21 @@ const collectComponents = (packageDir, exports, problems, extractStoryComponent,
         }
         if (!("file" in component))
             continue;
-        const subpath = Object.entries(exports).find(([, source]) => resolve(packageDir, source) === component.file)?.[0];
+        const subpath = Object.entries(exports).find(([, source]) => VITE_PATHS.isSame(VITE_PATHS.resolve(packageDir, source), component.file))?.[0];
         // a component no subpath exports is a story's own (a foundations page), not part of the package
         if (subpath === undefined || isExcluded(subpath, exclude))
             continue;
-        componentFiles.add(component.file);
-        components.push({
+        componentFiles.add(VITE_PATHS.normalize(component.file));
+        const collected = {
             title: index.title,
             subpath,
             docs: component.docs,
             stories: index.stories.map((story) => story.name ?? story.exportName),
-            mainStory: (index.stories.find((story) => story.isMain === true) ?? index.stories[0])?.exportName,
-            isLogic: isLogicFile(index)
-        });
+            ...mainStoryOf(index),
+            isLogic: isLogicFile(index),
+            design: index.design?.url
+        };
+        addComponent(components, collected);
     }
     return { components, componentFiles };
 };
@@ -93,28 +138,65 @@ const manifestText = (manifest, key) => {
     const value = Reflect.get(manifest, key);
     return typeof value === "string" ? value : undefined;
 };
-/** The id the package's stories carry, from its `./stories` export's module, when it writes it plainly. */
-const sourceIdIn = (packageDir, exports) => {
+/** What the package's `./stories` export declares, its tokens files named from the package's folder. */
+const declaredIn = (packageDir, exports) => {
     const source = exports[STORIES_SUBPATH];
     if (source === undefined)
         return undefined;
-    const file = resolve(packageDir, source);
-    try {
-        return sourceIdOf(file, readFileSync(file, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
+    const declared = sourceTokensIn(VITE_PATHS.resolve(packageDir, source), STORIES_SUBPATH);
+    return {
+        ...declared,
+        files: declared.files.map((file) => ({ ...file, label: VITE_PATHS.relative(packageDir, file.path) }))
+    };
+};
+/** The package's tokens, with what could not be read of them; nothing is read for a section left out. */
+const collectTokens = (declared, sections) => {
+    if (declared === undefined || sections?.includes("tokens") === false)
+        return { tokens: [], problems: [] };
+    const { tokens, problems } = readTokenFiles(declared.files);
+    return { tokens, problems: [...declared.problems, ...problems] };
+};
+/** A `?forgebook-docs-pages` import of a source module: its pattern, before the query. */
+const PAGES_IMPORT = /["']([^"']+)\?forgebook-docs-pages["']/g;
+/** A page's position: its `order`, or after every page with one. */
+const orderOf = (order) => order ?? Number.POSITIVE_INFINITY;
+/**
+ * The docs pages a package's `./stories` export declares, read from its `?forgebook-docs-pages` imports, in reading
+ * order.
+ *
+ * @param packageDir - the package's folder.
+ * @param exports - its exports.
+ * @param problems - receives what the pages' index noticed.
+ */
+const collectPages = (packageDir, exports, problems) => {
+    const source = exports[STORIES_SUBPATH];
+    if (source === undefined)
+        return [];
+    const file = VITE_PATHS.resolve(packageDir, source);
+    const patterns = [...(readLinkedFile(file) ?? "").matchAll(PAGES_IMPORT)].flatMap((match) => match[1] ?? []);
+    const pages = patterns.flatMap((pattern) => indexedDocPages(VITE_PATHS.dirname(file), [pattern], () => undefined));
+    for (const page of pages)
+        for (const note of page.index.notes ?? [])
+            problems.push(`${VITE_PATHS.relative(packageDir, page.file)}: ${note}`);
+    return pages
+        .sort((left, right) => orderOf(left.index.order) - orderOf(right.index.order) ||
+        left.index.title.localeCompare(right.index.title))
+        .map((page) => ({
+        title: page.index.title,
+        file: VITE_PATHS.relative(packageDir, page.file),
+        description: page.index.description
+    }));
 };
 /**
  * Reads a package for its catalogue.
  *
  * @param packageDir - the package's folder.
  * @param extractStoryComponent - the framework's reading of a story file's component (its docs module).
- * @param options - the package's catalogue options: the subpaths it leaves out.
+ * @param options - the package's catalogue options: the subpaths it leaves out, and the sections it lists, which leave
+ *   the tokens unread when they do not name them (every section by default).
  */
 export const collectDocs = (packageDir, extractStoryComponent, options) => {
-    const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+    const manifest = JSON.parse(readFileSync(VITE_PATHS.join(packageDir, "package.json"), "utf8"));
     const packageName = manifestText(manifest, "name") ?? packageDir;
     const exports = sourceExports(manifest);
     const problems = [];
@@ -123,7 +205,7 @@ export const collectDocs = (packageDir, extractStoryComponent, options) => {
     const sassModules = [];
     const styleSheets = [];
     for (const [subpath, source] of Object.entries(exports)) {
-        const file = resolve(packageDir, source);
+        const file = VITE_PATHS.resolve(packageDir, source);
         if (subpath === STORIES_SUBPATH || componentFiles.has(file) || isExcluded(subpath, options.exclude))
             continue;
         const entry = readExport(subpath, source, file);
@@ -137,10 +219,20 @@ export const collectDocs = (packageDir, extractStoryComponent, options) => {
             problems.push(entry.message);
     }
     const description = manifestText(manifest, "description");
-    const sourceId = sourceIdIn(packageDir, exports);
+    const declared = declaredIn(packageDir, exports);
+    const { tokens, problems: tokenProblems } = collectTokens(declared, options.sections);
     return {
-        data: { packageName, description, sourceId, components, modules, sassModules, styleSheets },
-        problems
+        data: {
+            packageName,
+            description,
+            sourceId: declared?.id,
+            components,
+            pages: collectPages(packageDir, exports, problems),
+            modules,
+            sassModules,
+            styleSheets,
+            tokens
+        },
+        problems: [...problems, ...tokenProblems]
     };
 };
-//# sourceMappingURL=collectDocs.js.map

package/dist/bin/forgebook-docs/forgebook-docs.d.mts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=forgebook-docs.d.mts.map

package/dist/bin/forgebook-docs/forgebook-docs.mjs

@@ -48,4 +48,3 @@ await defineScript({
         }, log);
     }
 }).run();
-//# sourceMappingURL=forgebook-docs.mjs.map

package/dist/bin/forgebook-docs/llmsText.d.ts

@@ -5,6 +5,7 @@
  *
  * @module
  */
+import type { CataloguePage } from "./catalogueDocs.types.ts";
 /** What the file says. */
 export type LlmsTextInput = {
     /** The package's name. */
@@ -13,6 +14,10 @@ export type LlmsTextInput = {
     readonly description: string | undefined;
     /** The catalogue's file name (`CATALOG.md`). */
     readonly catalogueFile: string;
+    /** The package's docs pages; none by default. */
+    readonly pages?: readonly CataloguePage[];
+    /** Whether the catalogue lists design tokens. @defaultValue `false` */
+    readonly hasTokens?: boolean;
 };
 /**
  * The text of `llms.txt`.
@@ -21,4 +26,3 @@ export type LlmsTextInput = {
  * @returns the text, ending with a newline.
  */
 export declare const llmsText: (input: LlmsTextInput) => string;
-//# sourceMappingURL=llmsText.d.ts.map

package/dist/bin/forgebook-docs/llmsText.js

@@ -20,7 +20,8 @@ export const llmsText = (input) => [
     "",
     "## Docs",
     "",
-    `- [${input.catalogueFile}](${input.catalogueFile}): every component, hook, helper and style module, one line each: what it is, how to import it, its props, and the id of a story that shows it`,
+    `- [${input.catalogueFile}](${input.catalogueFile}): every component, hook, helper and style module, one line each: what it is, how to import it, its props, and the id of a story that shows it${input.hasTokens === true ? ", then its design tokens" : ""}`,
+    ...(input.pages ?? []).map((page) => `- [${page.title}](${page.file})${page.description === undefined ? "" : `: ${page.description}`}`),
     "",
     "## Optional",
     "",
@@ -28,6 +29,8 @@ export const llmsText = (input) => [
     "",
     "- `npx forgebook story <id> --json`: a story's args and its component's props",
     "- `npx forgebook mcp`: the same for an agent, over the Model Context Protocol (`list_stories`, `get_story`)",
+    ...(input.hasTokens === true
+        ? ['- `npx forgebook tokens --nearest "#1c1b1b" --json`: the token to write instead of a raw value']
+        : []),
     ""
 ].join("\n");
-//# sourceMappingURL=llmsText.js.map

package/dist/bin/forgebook-docs/moduleDocs.d.ts

@@ -6,4 +6,3 @@ import type { ExportDocs } from "./catalogueDocs.types.ts";
  * @returns its exports in the module's order, or a message saying why it cannot be read.
  */
 export declare const moduleDocs: (file: string) => ExportDocs[] | string;
-//# sourceMappingURL=moduleDocs.d.ts.map

package/dist/bin/forgebook-docs/moduleDocs.js

@@ -59,4 +59,3 @@ export const moduleDocs = (file) => {
         .sort((left, right) => position(left) - position(right))
         .map((symbol) => exportDocs(symbol, program.checker, source));
 };
-//# sourceMappingURL=moduleDocs.js.map

package/dist/bin/forgebook-docs/sassDocs.d.ts

@@ -17,4 +17,3 @@ export declare const sassMembers: (text: string) => SassMemberDocs[];
  * @param text - the style sheet's source.
  */
 export declare const styleSheetSummary: (text: string) => string;
-//# sourceMappingURL=sassDocs.d.ts.map

package/dist/bin/forgebook-docs/sassDocs.js

@@ -74,4 +74,3 @@ export const styleSheetSummary = (text) => {
     const end = comment.search(/\.(\s|$)/);
     return end === -1 ? comment : comment.slice(0, end + 1);
 };
-//# sourceMappingURL=sassDocs.js.map

package/dist/bin/forgebook-texts/forgebook-texts.d.mts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=forgebook-texts.d.mts.map

package/dist/bin/forgebook-texts/forgebook-texts.mjs

@@ -17,7 +17,7 @@ import { storyTextsReport } from "./storyTextsReport.js";
 /** The command, as the hints print it. */
 const COMMAND = "forgebook-texts";
 /** Where a package's story files and fixtures are, relative to it. */
-const SOURCE_PATTERNS = ["src/**/*.stories.tsx", "stories/**/*.{ts,tsx}"];
+const SOURCE_PATTERNS = ["src/**/*.stories.{ts,tsx}", "stories/**/*.{ts,tsx}"];
 /** A locale file's table, read as JSON. */
 const readTable = (file) => {
     const value = JSON.parse(readFileSync(file, "utf8"));
@@ -91,4 +91,3 @@ await defineScript({
         return report;
     }
 }).run();
-//# sourceMappingURL=forgebook-texts.mjs.map

package/dist/bin/forgebook-texts/storyTextsReport.d.ts

@@ -23,4 +23,3 @@ export declare const usedKeys: (source: string) => string[];
  * @param locales - the locale files by language id; `en` is the one every key is in.
  */
 export declare const storyTextsReport: (sources: readonly string[], locales: Readonly<Record<string, Readonly<Record<string, string>>>>) => StoryTextsReport;
-//# sourceMappingURL=storyTextsReport.d.ts.map

package/dist/bin/forgebook-texts/storyTextsReport.js

@@ -32,4 +32,3 @@ export const storyTextsReport = (sources, locales) => {
         untranslated
     };
 };
-//# sourceMappingURL=storyTextsReport.js.map

package/dist/bin/forgebook-texts/storyTextsReport.types.d.ts

@@ -22,4 +22,3 @@ export type StoryTextsReport = {
     /** By language id (every file but English), the texts it lacks. */
     readonly untranslated: Readonly<Record<string, readonly UntranslatedText[]>>;
 };
-//# sourceMappingURL=storyTextsReport.types.d.ts.map

package/dist/bin/forgebook-texts/storyTextsReport.types.js

@@ -4,4 +4,3 @@
  *
  * @module
  */
-//# sourceMappingURL=storyTextsReport.types.js.map

package/dist/bin/frameworkDocs.d.ts

@@ -7,4 +7,3 @@ import { type DocsModule } from "../src/vite/adapter.ts";
  * @throws a `ScriptError` when the package cannot resolve it or the module is not a docs module.
  */
 export declare const frameworkDocsModule: (packageDir: string, framework: string) => Promise<DocsModule>;
-//# sourceMappingURL=frameworkDocs.d.ts.map

package/dist/bin/frameworkDocs.js

@@ -40,4 +40,3 @@ export const frameworkDocsModule = async (packageDir, framework) => {
         throw new ScriptError(`${specifier} exports no extractStoryComponent`);
     return module;
 };
-//# sourceMappingURL=frameworkDocs.js.map

package/dist/src/a11y.d.ts

@@ -25,4 +25,3 @@ export type Violation = {
 };
 /** Whether a value is a violation, as it arrives in a message. */
 export declare const isViolation: (value: unknown) => value is Violation;
-//# sourceMappingURL=a11y.d.ts.map

package/dist/src/a11y.js

@@ -26,4 +26,3 @@ export const isViolation = (value) => {
         Array.isArray(targets) &&
         targets.every((target) => typeof target === "string"));
 };
-//# sourceMappingURL=a11y.js.map

package/dist/src/addressArgs.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The props panel's values an address names (`?args=`), checked against what the story declares before any reaches
+ * its frame.
+ *
+ * @remarks
+ * A link shares a view, so whoever writes the link chooses these values, and the frame runs on the catalogue's own
+ * origin. Handed on unchecked, a name the story never declared reaches the component, which may pass it to an element
+ * as an attribute: `innerHTML` or `onclick` on Vue's fallthrough attributes, `srcDoc` on a React element that spreads
+ * its rest props; each runs a script with the catalogue's rights. So a value is kept only when the panel itself could
+ * have set it: a prop the panel lets the person set (the component's props with the story's `argTypes` laid over them,
+ * or an arg only the `argTypes` or the story's own args name), with a value of that prop's type. Everything else is
+ * left out and reported. A value that is code never comes from an address: a named value is looked up among the
+ * source's own entries only, never through an object's prototype (`constructor`). Pure.
+ *
+ * @module
+ */
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+import { type PanelArgTypes, type PanelProp } from "./argTypes.ts";
+import type { PropDocs } from "./componentDocs.ts";
+import { type ArgValue, type PanelArgs } from "./messages.ts";
+import { type NamedValues } from "./namedValues.ts";
+/** What a story declares about the args the panel sets, as the shell knows it once the story's frame is ready. */
+export type ArgDeclaration = {
+    /** The props the component's types give; none when the story has no component or its docs could not be read. */
+    readonly props: readonly PropDocs[];
+    /** The story's `argTypes`, as its frame reported them. */
+    readonly argTypes: PanelArgTypes;
+    /** The props the story lets the panel set. */
+    readonly controls: StoryControlsSetting;
+    /** The story's own args the panel can show, as its frame reported them. */
+    readonly storyArgs: PanelArgs;
+    /** The values the source names for types the panel cannot write. */
+    readonly namedValues: NamedValues;
+};
+/** Why a value of the address was left out: its name is not one the panel sets, or its value is not of the prop's type. */
+export type DroppedArgReason = "undeclared" | "type";
+/** A value of the address left out. */
+export type DroppedArg = {
+    /** The arg's name, as the address wrote it. */
+    readonly name: string;
+    /** Why it was left out. */
+    readonly reason: DroppedArgReason;
+};
+/** The address's values once checked. */
+export type CheckedArgs = {
+    /** The values the story receives. */
+    readonly accepted: PanelArgs;
+    /** The values left out, in the address's order. */
+    readonly dropped: readonly DroppedArg[];
+};
+/**
+ * The props the panel sets for a story, whatever the address says: the component's props with the `argTypes` over
+ * them and the args only the `argTypes` name, then the story's own args the two leave out, each kept only when the
+ * story's controls let the panel set it.
+ *
+ * @param declaration - what the story declares.
+ */
+export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly PanelProp[];
+/**
+ * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
+ * kind.
+ *
+ * @param prop - a prop the panel sets.
+ * @param value - the address's value.
+ * @param namedValues - the source's named values.
+ */
+export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues) => boolean;
+/**
+ * The address's values the story receives, and those left out with the reason.
+ *
+ * @param args - the values the address names.
+ * @param declaration - what the story declares.
+ */
+export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration) => CheckedArgs;