forgebook 0.1.8 → 0.2.0

package/dist/src/vite/configFile.js

@@ -1,11 +1,3 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 /**
  * 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.
@@ -17,13 +9,33 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  *
  * @module
  */
-import { existsSync } from "node:fs";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { AUDIENCE_IDS } from "../audiences.js";
+import { deviceSettingProblem } from "../deviceView.js";
+import { frameThemeCss, mergedThemes, shellThemeCss, shellThemeProblems, themeValueProblem } from "../shellTheme.js";
 import { switchesProblem } from "../switches.js";
+import { framesProblem, resolvedFrames } from "./framesConfig.js";
+import { pluginsProblem, withPluginSwitches } from "./pluginConfig.js";
+import { tokenThemeOf } from "./themeFromTokens.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /** The names a configuration file may have, in the order they are looked for. */
 export const CONFIG_FILES = ["forgebook.config.ts", "forgebook.config.mts", "forgebook.config.js"];
+/**
+ * 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 const HOME_FILE = "forgebook.home.md";
 /** The names a preview may have beside the configuration, in the order they are looked for. */
 const PREVIEW_FILES = ["forgebook.preview.ts", "forgebook.preview.tsx", "forgebook.preview.js"];
 /** The packages of the play tools: both installed, or the plays get neither. */
@@ -84,13 +96,15 @@ const singleValues = (lists) => ({
     ...(lists.gridStep === undefined ? {} : { gridStep: lists.gridStep }),
     ...(lists.toolbar === undefined ? {} : { toolbar: lists.toolbar }),
     ...(lists.usedIn === undefined ? {} : { usedIn: lists.usedIn }),
-    ...(lists.appearance === undefined ? {} : { appearance: lists.appearance })
+    ...(lists.audience === undefined ? {} : { audience: lists.audience }),
+    ...(lists.appearance === undefined ? {} : { appearance: lists.appearance }),
+    ...(lists.propGroups === undefined ? {} : { propGroups: lists.propGroups })
 });
 /**
  * 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.
  */
@@ -100,7 +114,11 @@ export const mergedLists = (all) => {
     const strings = {};
     const keys = {};
     let merged = {};
+    // the device field by field, as a story's lies over its meta's: a preset's model stays under a catalogue's frame
+    let device;
     for (const lists of all) {
+        if (lists.device !== undefined)
+            device = { ...device, ...lists.device };
         Object.assign(tabs, lists.tabs);
         Object.assign(controls, lists.controls);
         Object.assign(strings, lists.strings);
@@ -111,6 +129,7 @@ export const mergedLists = (all) => {
     const tags = all.findLast((lists) => lists.a11y?.tags !== undefined)?.a11y?.tags;
     return {
         ...merged,
+        ...(device === undefined ? {} : { device }),
         backgrounds: {
             ...(builtIn === undefined ? {} : { builtIn }),
             custom: mergedById(all.map((lists) => lists.backgrounds?.custom))
@@ -128,6 +147,11 @@ export const mergedLists = (all) => {
         views: [...new Map(all.flatMap((lists) => lists.views ?? []).map((view) => [view.name, view])).values()]
     };
 };
+/** Whether a configuration's list has something in it. */
+const isListed = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list) && list.length > 0;
+};
 /**
  * Why a loaded configuration cannot be used, or none.
  *
@@ -140,11 +164,14 @@ const configProblem = (config) => {
         return "it names no framework (`framework: react()`)";
     if (!("title" in config) || typeof config.title !== "string")
         return "it names no title";
-    const hasStories = "stories" in config && Array.isArray(config.stories) && config.stories.length > 0;
-    const hasSources = "sources" in config && Array.isArray(config.sources) && config.sources.length > 0;
-    if (!hasStories && !hasSources)
+    if ("home" in config &&
+        config.home !== undefined &&
+        config.home !== false &&
+        typeof config.home !== "string")
+        return 'its home is neither a path (`home: "docs/home.md"`) nor false';
+    if (!["stories", "sources", "docs"].some((key) => isListed(config, key)))
         return 'it names no stories (`stories: ["src/**/*.stories.tsx"]`) and no sources';
-    return undefined;
+    return framesProblem("frames" in config ? config.frames : undefined);
 };
 /**
  * Whether a loaded configuration is one: checked by `configProblem`.
@@ -152,44 +179,172 @@ const configProblem = (config) => {
  * @param config - what the file exports by default.
  */
 const isConfig = (config) => configProblem(config) === undefined;
+/** The fields of a device setting, by name, and the type each is written in. */
+const DEVICE_FIELDS = {
+    frame: "boolean",
+    model: "string",
+    orientation: "string",
+    touch: "boolean",
+    edgeToEdge: "boolean"
+};
+/**
+ * Why a device setting cannot be used, or none: not an object of `frame`, `model`, `orientation` and `touch`, a field
+ * of another type, or a model or an orientation that is none. A configuration is code, so its types are not a
+ * promise.
+ *
+ * @param device - the setting as a configuration or a preset gives it.
+ */
+const deviceProblem = (device) => {
+    if (typeof device !== "object" || device === null || Array.isArray(device))
+        return 'write it as an object: { frame: true, model: "iphone-16" }';
+    for (const [name, value] of Object.entries(device)) {
+        const type = DEVICE_FIELDS[name];
+        if (type === undefined)
+            return `it has no field "${name}": it takes ${Object.keys(DEVICE_FIELDS).join(", ")}`;
+        if (value !== undefined && typeof value !== type)
+            return `its ${name} must be ${type === "boolean" ? "true or false" : "a text"}`;
+    }
+    const model = Reflect.get(device, "model");
+    const orientation = Reflect.get(device, "orientation");
+    return deviceSettingProblem({
+        ...(typeof model === "string" ? { model } : {}),
+        ...(typeof orientation === "string" ? { orientation } : {})
+    });
+};
+/**
+ * The configuration's and the presets' lists, once checked where the shell would leave a mistake out: a device that
+ * cannot be used.
+ *
+ * @param all - the presets' lists, then the configuration's.
+ * @param dir - the configuration's folder, for the message.
+ * @throws when a device cannot be used.
+ */
+const checkedLists = (all, dir) => {
+    for (const lists of all) {
+        const problem = lists.device === undefined ? undefined : deviceProblem(lists.device);
+        if (problem !== undefined)
+            throw new Error(`${resolve(dir, "forgebook.config")}: Forgebook's device: ${problem}`);
+    }
+    return all;
+};
+/** What a catalogue shows: its own stories and docs pages, and the sources; none where it names none. */
+const shownFiles = (config) => ({
+    stories: config.stories ?? [],
+    docs: config.docs ?? [],
+    sources: config.sources ?? []
+});
+/**
+ * The written home's absolute path: the configuration's `home`, else `forgebook.home.md` beside it when there; none
+ * with `home: false`.
+ *
+ * @param config - the configuration.
+ * @param dir - the folder of its file.
+ * @throws when the configuration names a home that is not there.
+ */
+const homeOf = (config, dir) => {
+    if (config.home === false)
+        return undefined;
+    if (config.home === undefined) {
+        const beside = VITE_PATHS.join(dir, HOME_FILE);
+        return existsSync(beside) ? beside : undefined;
+    }
+    const home = VITE_PATHS.resolve(dir, config.home);
+    if (!existsSync(home) || !statSync(home).isFile())
+        throw new Error(`${resolve(dir, "forgebook.config")}: its home "${config.home}" is not a file there`);
+    return home;
+};
 /**
- * A configuration with its presets merged and its paths made absolute.
+ * A configuration's plugins, once they can be used.
  *
  * @param config - the configuration.
  * @param dir - the folder of its file.
+ * @throws when they cannot.
+ */
+const checkedPlugins = (config, dir) => {
+    const plugins = config.plugins ?? [];
+    const problem = pluginsProblem(plugins, config.framework.name, dir);
+    if (problem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${problem}`);
+    return plugins;
+};
+/**
+ * Whether Forgebook's mark may stand in for a logo: on, unless the last that says so turns it off.
+ *
+ * @param all - the presets, then the catalogue.
+ */
+const hasBrandingIn = (all) => all.findLast((each) => each.shell?.branding !== undefined)?.shell?.branding !== false;
+/**
+ * A configuration with its presets merged and its paths made absolute, in Vite's form.
+ *
+ * @param config - the configuration.
+ * @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 const resolveConfig = (config, dir) => {
+export const resolveConfig = (config, fileDir, paths = VITE_PATHS) => {
     const presets = config.presets ?? [];
-    const absolute = (path) => (isAbsolute(path) ? path : resolve(dir, path));
+    const dir = paths.normalize(fileDir);
+    const absolute = (path) => paths.resolve(dir, path);
+    // a preset's preview and style sheet are absolute paths (its own files) or a package's specifier, kept as written
+    const ownPath = (path) => (paths.isAbsolute(path) ? paths.normalize(path) : path);
     const declared = [...presets.map((preset) => preset.switches), config.switches];
-    const switches = declared.some((list) => list !== undefined) ? mergedById(declared) : undefined;
+    const plugins = checkedPlugins(config, dir);
+    const switches = withPluginSwitches(declared.some((list) => list !== undefined) ? mergedById(declared) : undefined, plugins);
     const problem = switches === undefined ? undefined : switchesProblem(switches);
     if (problem !== undefined)
         throw new Error(`${resolve(dir, "forgebook.config")}: ${problem}`);
+    const declaredThemes = [...presets.map((preset) => preset.shell?.theme ?? {}), config.shell?.theme ?? {}];
+    const tokens = (config.tokens ?? []).map((each) => typeof each === "string"
+        ? { path: absolute(each), mode: undefined }
+        : { path: absolute(each.file), mode: each.mode });
+    const fromTokens = Object.assign({}, ...declaredThemes.map((each) => each.fromTokens));
+    const tokenThemed = tokenThemeOf(fromTokens, tokens, dir);
+    const theme = mergedThemes([tokenThemed.theme, ...declaredThemes]);
+    const lists = mergedLists(checkedLists([...presets, config], dir));
+    // the page reads it as one of the ids, and a configuration is written by JavaScript too, which no type stops
+    if (lists.audience !== undefined && !AUDIENCE_IDS.includes(lists.audience)) {
+        throw new Error(`${resolve(dir, "forgebook.config")}: the audience "${lists.audience}" is none of ${AUDIENCE_IDS.join(", ")}`);
+    }
+    const themeProblem = themeValueProblem(theme);
+    if (themeProblem !== undefined)
+        throw new Error(`${resolve(dir, "forgebook.config")}: ${themeProblem}`);
     const ownPreview = config.preview === undefined
-        ? PREVIEW_FILES.map((name) => resolve(dir, name)).find((file) => existsSync(file))
+        ? PREVIEW_FILES.map((name) => paths.join(dir, name)).find((file) => existsSync(file))
         : absolute(config.preview);
     return {
         dir,
         framework: config.framework,
         title: config.title,
+        home: homeOf(config, dir),
         logo: config.logo === undefined ? undefined : absolute(config.logo),
         heights: config.heights,
-        stories: config.stories ?? [],
-        sources: config.sources ?? [],
+        ...shownFiles(config),
         switches,
         languages: mergedById([...presets.map((preset) => preset.languages), config.languages]),
         previews: [
-            ...presets.flatMap((preset) => (preset.preview === undefined ? [] : [preset.preview])),
+            ...presets.flatMap((preset) => (preset.preview === undefined ? [] : [ownPath(preset.preview)])),
             ...(ownPreview === undefined ? [] : [ownPreview])
         ],
         head: [...presets.map((preset) => preset.head ?? ""), config.head ?? ""]
             .filter((tags) => tags !== "")
             .join("\n"),
+        shell: {
+            themeCss: shellThemeCss(theme),
+            frameCss: frameThemeCss(theme),
+            hasBranding: hasBrandingIn([...presets, config]),
+            styleSheets: [
+                ...presets.flatMap((preset) => (preset.shell?.css === undefined ? [] : [ownPath(preset.shell.css)])),
+                ...(config.shell?.css === undefined ? [] : [absolute(config.shell.css)])
+            ],
+            problems: [...tokenThemed.problems, ...shellThemeProblems(theme)]
+        },
+        tokens,
         watch: (config.watch ?? []).map(absolute),
-        lists: mergedLists([...presets, config]),
-        hasPlayTools: hasPlayToolsIn(dir)
+        lists,
+        hasPlayTools: hasPlayToolsIn(dir),
+        plugins,
+        frames: resolvedFrames(config.frames),
+        build: { readableNames: config.build?.readableNames === true }
     };
 };
 /**
@@ -205,4 +360,3 @@ export const loadConfigFile = async (file) => {
         throw new Error(`${file}: ${configProblem(config) ?? "it cannot be read"}`);
     return resolveConfig(config, dirname(file));
 };
-//# sourceMappingURL=configFile.js.map

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

@@ -0,0 +1,75 @@
+/**
+ * Design tokens read from DTCG files (the Design Tokens Format, 2025.10): a flat list with references followed and
+ * themes applied, every value as CSS writes it.
+ *
+ * @remarks
+ * Pure: parsed JSON in, tokens out. The format has no themes of its own, so a theme is a file of its own read over the
+ * base (`tokens: ["tokens.json", { file: "dark.json", mode: "dark" }]`). References are followed over base and theme
+ * together: a theme can alias the base, and a base alias follows what a theme overrides, which is why semantic tokens
+ * over a palette change with the theme at all. That is why files are collected first and resolved only once all are
+ * known. A token that cannot be used is named in `problems` with its file, and the others stay usable: nothing vanishes
+ * in silence, since a token an agent cannot find is a colour it writes by hand.
+ *
+ * Files of a catalogue's sources are read before its own, so its aliases reach a library's palette and a later file
+ * replaces an earlier one's token. Within one author's files that is plain layering; between authors it is a clash,
+ * reported and never refused: the catalogue is what puts the libraries together, so its value is the one in use.
+ *
+ * @module
+ */
+import { type TokenClash } from "./tokenClashes.ts";
+/** A token, ready to read. */
+export type DesignToken = {
+    /** Its name, the groups joined by dots (`color.brand.primary`). */
+    readonly name: string;
+    /** Its type (`color`, `dimension`…). */
+    readonly type: string;
+    /** Its value, as CSS writes it; the first theme's when only themes define it. */
+    readonly value: string;
+    /** The token it is an alias of. */
+    readonly alias?: string;
+    /** What it is for. */
+    readonly description?: string;
+    /** Why not to use it, when it is deprecated. */
+    readonly deprecated?: string;
+    /** Its value in each theme where it differs, by theme. */
+    readonly modes: Readonly<Record<string, string>>;
+    /** Whether only themes define it, so `value` does not hold everywhere. */
+    readonly isThemeOnly?: true;
+    /** The source that gives it, by its id or, when it writes none, by its module; none for the catalogue's own. */
+    readonly source?: string;
+};
+/** What the files gave. */
+export type ParsedTokens = {
+    /** The tokens that can be used, in the files' order. */
+    readonly tokens: readonly DesignToken[];
+    /** What could not be used, one line each, naming its file. */
+    readonly problems: readonly string[];
+    /** The names two authors give different values, with whose stands. */
+    readonly clashes: readonly TokenClash[];
+};
+/** A tokens file, parsed. */
+export type TokensInput = {
+    /** What a problem calls it: its name in the configuration. */
+    readonly label: string;
+    /** The theme; none for the base. */
+    readonly mode: string | undefined;
+    /** The file's content. */
+    readonly file: unknown;
+    /** The source it comes from; none for the catalogue's own. */
+    readonly source?: string;
+};
+/**
+ * Reads the files of a catalogue: the base first, then each theme over it. A theme gives a token a value when it names
+ * the token, or when a reference brings it a different one. The files of one theme are one layer, the later replacing,
+ * so a catalogue's dark file reaches what a library's dark file sets.
+ *
+ * @param inputs - the files: each source's in the catalogue's order, then the catalogue's own.
+ */
+export declare const readTokens: (inputs: readonly TokensInput[]) => ParsedTokens;
+/**
+ * The tokens of a category: a type (`color`), or a first group (`space`).
+ *
+ * @param tokens - the tokens.
+ * @param category - the category; none for all of them.
+ */
+export declare const filteredTokens: (tokens: readonly DesignToken[], category: string | undefined) => DesignToken[];