@homepages/template-kit 0.1.0 → 0.3.0

package/dist/cli/theme/generate.js

@@ -0,0 +1,43 @@
+import { TokenThemeSchema, compileThemeToCss } from "../../design-system/theme.js";
+import { loadTheme } from "./load-theme.js";
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+
+//#region src/cli/theme/generate.ts
+const OUT_FILE = "theme.css";
+const HEADER = "/* Generated by `template-kit theme` from theme.ts — do not edit.\n   Re-run `template-kit theme` after changing theme.ts. */\n";
+/** theme.ts's `theme` export failed TokenThemeSchema; `issues` are `path: message` lines. */
+var InvalidTheme = class extends Error {
+	path;
+	issues;
+	constructor(path, issues) {
+		super(`${path} is not a valid TokenTheme:\n${issues.map((i) => `  - ${i}`).join("\n")}`);
+		this.path = path;
+		this.issues = issues;
+		this.name = "InvalidTheme";
+	}
+};
+/**
+* Compile `templates/<key>/theme.ts` to `templates/<key>/theme.css`. Throws
+* MissingThemeFile / MissingThemeExport (load-theme.ts) or InvalidTheme.
+*/
+async function generateTemplateTheme(root, template) {
+	const raw = await loadTheme(root, template);
+	const parsed = TokenThemeSchema.safeParse(raw);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`);
+		throw new InvalidTheme(join("templates", template.key, "theme.ts"), issues);
+	}
+	const theme = parsed.data;
+	const outPath = join(template.dir, OUT_FILE);
+	await writeFile(outPath, `${HEADER}${compileThemeToCss(theme)}`, "utf8");
+	const tokenCount = Object.keys(theme.colors).length + Object.keys(theme.fonts).length + Object.keys(theme.type).length + Object.keys(theme.radii).length + Object.keys(theme.shadows).length + Object.keys(theme.layout).length;
+	return {
+		outPath,
+		relPath: join("templates", template.key, OUT_FILE),
+		tokenCount
+	};
+}
+
+//#endregion
+export { InvalidTheme, generateTemplateTheme };

package/dist/cli/theme/index.js

@@ -0,0 +1,33 @@
+import { findWorkspaceRoot, selectTemplates, templateFromCwd } from "../check/workspace.js";
+import { generateTemplateTheme } from "./generate.js";
+import { parseArgs } from "node:util";
+
+//#region src/cli/theme/index.ts
+async function runTheme(argv, cwd) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		options: { all: {
+			type: "boolean",
+			default: false
+		} },
+		allowPositionals: true
+	});
+	const root = await findWorkspaceRoot(cwd);
+	const selected = await selectTemplates(root, positionals[0] ?? (values.all ? void 0 : templateFromCwd(root, cwd)), values.all, "theme");
+	if (selected.length === 0) return {
+		code: 1,
+		output: "No template to generate theme CSS for: templates/ holds no template folder."
+	};
+	const lines = [];
+	for (const template of selected) {
+		const { relPath, tokenCount } = await generateTemplateTheme(root, template);
+		lines.push(`  ${template.key}  wrote ${relPath} (${tokenCount} tokens)`);
+	}
+	return {
+		code: 0,
+		output: `template-kit theme\n${lines.join("\n")}`
+	};
+}
+
+//#endregion
+export { runTheme };

package/dist/cli/theme/load-theme.js

@@ -0,0 +1,69 @@
+import { loadEsbuild } from "../check/resolve-tool.js";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+//#region src/cli/theme/load-theme.ts
+const THEME_FILE = "theme.ts";
+const THEME_EXPORT = "theme";
+/** A template has no theme.ts. `path` is workspace-relative. */
+var MissingThemeFile = class extends Error {
+	path;
+	constructor(path) {
+		super(`${path} not found. A template's design tokens live in theme.ts — create it exporting \`${THEME_EXPORT}\` (a TokenTheme).`);
+		this.path = path;
+		this.name = "MissingThemeFile";
+	}
+};
+/** theme.ts built, but exports no `theme` binding. `path` is workspace-relative. */
+var MissingThemeExport = class extends Error {
+	path;
+	constructor(path) {
+		super(`${path} does not export \`${THEME_EXPORT}\`. It must \`export const ${THEME_EXPORT}: TokenTheme = { … }\`.`);
+		this.path = path;
+		this.name = "MissingThemeExport";
+	}
+};
+const isFile = async (p) => {
+	try {
+		return (await stat(p)).isFile();
+	} catch {
+		return false;
+	}
+};
+/**
+* Transpile + evaluate `templates/<key>/theme.ts` and return its `theme` export,
+* unvalidated (the caller parses it with TokenThemeSchema). Throws MissingThemeFile
+* when theme.ts is absent and MissingThemeExport when it builds without a `theme`
+* binding.
+*/
+async function loadTheme(root, template) {
+	const source = join(template.dir, THEME_FILE);
+	const rel = join("templates", template.key, THEME_FILE);
+	if (!await isFile(source)) throw new MissingThemeFile(rel);
+	const outdir = join(root, "node_modules", ".template-kit", "theme", createHash("sha256").update(template.dir).digest("hex").slice(0, 12));
+	await rm(outdir, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(outdir, { recursive: true });
+	const { build } = await loadEsbuild(root);
+	await build({
+		entryPoints: [source],
+		outdir,
+		bundle: true,
+		format: "esm",
+		platform: "neutral",
+		packages: "external",
+		logLevel: "silent",
+		absWorkingDir: root
+	});
+	const version = createHash("sha256").update(await readFile(source)).digest("hex").slice(0, 12);
+	const value = (await import(`${pathToFileURL(join(outdir, "theme.js")).href}?v=${version}`))[THEME_EXPORT];
+	if (value === void 0) throw new MissingThemeExport(rel);
+	return value;
+}
+
+//#endregion
+export { MissingThemeExport, MissingThemeFile, loadTheme };

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { KIT_VERSION } from "./index.js";
+import { runCheck } from "./cli/check/index.js";
+import { runTheme } from "./cli/theme/index.js";
 
 //#region src/cli/index.ts
 /**
@@ -10,7 +12,6 @@ import { KIT_VERSION } from "./index.js";
 */
 const NOT_IMPLEMENTED = /* @__PURE__ */ new Set([
 	"dev",
-	"check",
 	"pack",
 	"link",
 	"unlink",
@@ -22,7 +23,8 @@ Usage: template-kit <command>
 
 Commands:
   dev       Local preview server                 (not implemented yet)
-  check     Typecheck, lint, and validate        (not implemented yet)
+  check     Typecheck, lint, and validate a template
+  theme     Generate a template's theme CSS from its theme.ts
   pack      Build the submission artifact        (not implemented yet)
   link      Overlay a local kit build            (not implemented yet)
   unlink    Remove the overlay                   (not implemented yet)
@@ -32,7 +34,7 @@ Options:
   -v, --version   Print the kit version
   -h, --help      Print this message
 `;
-function main(argv) {
+async function main(argv) {
 	const cmd = argv[0];
 	if (cmd === "--version" || cmd === "-v") {
 		process.stdout.write(`${KIT_VERSION}\n`);
@@ -42,6 +44,22 @@ function main(argv) {
 		process.stdout.write(USAGE);
 		return 0;
 	}
+	if (cmd === "check") try {
+		const { code, output } = await runCheck(argv.slice(1), process.cwd());
+		process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+		return code;
+	} catch (cause) {
+		process.stderr.write(`template-kit check: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+		return 1;
+	}
+	if (cmd === "theme") try {
+		const { code, output } = await runTheme(argv.slice(1), process.cwd());
+		process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+		return code;
+	} catch (cause) {
+		process.stderr.write(`template-kit theme: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+		return 1;
+	}
 	if (NOT_IMPLEMENTED.has(cmd)) {
 		process.stderr.write(`template-kit ${cmd}: not implemented yet.\nThis 0.0.x release ships the package skeleton only.\n`);
 		return 1;
@@ -49,6 +67,6 @@ function main(argv) {
 	process.stderr.write(`template-kit: unknown command '${cmd}'\n\n${USAGE}`);
 	return 1;
 }
-process.exit(main(process.argv.slice(2)));
+process.exit(await main(process.argv.slice(2)));
 
 //#endregion

package/dist/contracts/fill-treatments.js

@@ -0,0 +1,47 @@
+//#region src/contracts/fill-treatments.ts
+const GENERATED_KINDS = ["text", "list<text>"];
+const COMPUTED_FNS = ["haversine_miles", "mint_id"];
+const CATALOG_FIELDS = [
+	"key",
+	"label",
+	"icon",
+	"slot"
+];
+function parseTreatment(raw) {
+	if (raw === "source") return {
+		kind: "source",
+		path: null
+	};
+	if (raw.startsWith("source:")) {
+		const path = raw.slice(7);
+		return path ? {
+			kind: "source",
+			path
+		} : null;
+	}
+	if (raw.startsWith("computed:")) {
+		const fn = raw.slice(9);
+		return COMPUTED_FNS.includes(fn) ? {
+			kind: "computed",
+			fn
+		} : null;
+	}
+	if (raw.startsWith("catalog:")) {
+		const field = raw.slice(8);
+		return CATALOG_FIELDS.includes(field) ? {
+			kind: "catalog",
+			field
+		} : null;
+	}
+	if (raw.startsWith("generated:")) {
+		const outKind = raw.slice(10);
+		return GENERATED_KINDS.includes(outKind) ? {
+			kind: "generated",
+			outKind
+		} : null;
+	}
+	return null;
+}
+
+//#endregion
+export { CATALOG_FIELDS, COMPUTED_FNS, GENERATED_KINDS, parseTreatment };

package/dist/design-system/theme.d.ts

@@ -1,307 +1,38 @@
 import { z } from "zod";
 //#region src/design-system/theme.d.ts
-declare const COLOR_ROLE_VARS: {
-  readonly ink: "--tr-color-ink";
-  readonly inkSoft: "--tr-color-ink-soft";
-  readonly inkMute: "--tr-color-ink-mute";
-  readonly background: "--tr-color-background";
-  readonly surface: "--tr-color-surface";
-  readonly surfaceAlt: "--tr-color-surface-alt";
-  readonly border: "--tr-color-border";
-  readonly borderStrong: "--tr-color-border-strong";
-  readonly primary: "--tr-color-primary";
-  readonly primaryFg: "--tr-color-primary-fg";
-  readonly primaryStrong: "--tr-color-primary-darker";
-  readonly accent: "--tr-color-accent";
-  readonly accentFg: "--tr-color-accent-contrast";
-  readonly accentStrong: "--tr-color-accent-strong";
-  readonly overlay: "--tr-color-overlay";
-  readonly overlayStrong: "--tr-color-overlay-strong";
-  readonly overlayLight: "--tr-color-overlay-light";
-  readonly darkBg: "--tr-color-footer-bg";
-  readonly darkFg: "--tr-color-footer-fg";
-  readonly darkFgMute: "--tr-color-footer-fg-mute";
-  readonly darkBorder: "--tr-color-footer-divider";
-};
-type ColorRole = keyof typeof COLOR_ROLE_VARS;
-declare const FONT_ROLE_VARS: {
-  readonly body: "--tr-font-sans";
-  readonly heading: "--tr-font-serif";
-  readonly numeric: "--tr-font-num";
-  readonly label: "--tr-font-label";
-};
-declare const TYPE_STEP_VARS: {
-  readonly xs: "--tr-text-xs";
-  readonly sm: "--tr-text-sm";
-  readonly base: "--tr-text-base";
-  readonly lg: "--tr-text-lg";
-  readonly xl: "--tr-text-xl";
-  readonly "2xl": "--tr-text-2xl";
-  readonly "3xl": "--tr-text-3xl";
-  readonly "4xl": "--tr-text-4xl";
-  readonly "5xl": "--tr-text-5xl";
-  readonly display: "--tr-text-display";
-};
-declare const RADIUS_VARS: {
-  readonly sm: "--tr-radius-sm";
-  readonly md: "--tr-radius-md";
-  readonly lg: "--tr-radius-lg";
-  readonly full: "--tr-radius-full";
-};
-declare const SHADOW_VARS: {
-  readonly sm: "--tr-shadow-sm";
-  readonly md: "--tr-shadow-md";
-  readonly lg: "--tr-shadow-lg";
-};
-declare const LAYOUT_VARS: {
-  readonly containerMax: "--tr-container-max";
-  readonly containerPad: "--tr-container-pad";
-  readonly headerHeight: "--tr-header-height";
-};
+declare const TokenNameSchema: z.ZodString;
 declare const TokenThemeSchema: z.ZodObject<{
-  colors: z.ZodObject<Record<"ink" | "inkSoft" | "inkMute" | "background" | "surface" | "surfaceAlt" | "border" | "borderStrong" | "primary" | "primaryFg" | "primaryStrong" | "accent" | "accentFg" | "accentStrong" | "overlay" | "overlayStrong" | "overlayLight" | "darkBg" | "darkFg" | "darkFgMute" | "darkBorder", z.ZodString>, "strip", z.ZodTypeAny, {
-    ink: string;
-    inkSoft: string;
-    inkMute: string;
-    background: string;
-    surface: string;
-    surfaceAlt: string;
-    border: string;
-    borderStrong: string;
-    primary: string;
-    primaryFg: string;
-    primaryStrong: string;
-    accent: string;
-    accentFg: string;
-    accentStrong: string;
-    overlay: string;
-    overlayStrong: string;
-    overlayLight: string;
-    darkBg: string;
-    darkFg: string;
-    darkFgMute: string;
-    darkBorder: string;
-  }, {
-    ink: string;
-    inkSoft: string;
-    inkMute: string;
-    background: string;
-    surface: string;
-    surfaceAlt: string;
-    border: string;
-    borderStrong: string;
-    primary: string;
-    primaryFg: string;
-    primaryStrong: string;
-    accent: string;
-    accentFg: string;
-    accentStrong: string;
-    overlay: string;
-    overlayStrong: string;
-    overlayLight: string;
-    darkBg: string;
-    darkFg: string;
-    darkFgMute: string;
-    darkBorder: string;
-  }>;
-  /** Optional open brand palette → `--tr-color-<name>` (the escape hatch). */
-  palette: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  fonts: z.ZodObject<Record<"body" | "heading" | "numeric" | "label", z.ZodString> & {
-    /** Font-loading block (@import / @font-face) emitted before :root. */
-    fontFaces: z.ZodOptional<z.ZodString>;
-  }, "strip", z.ZodTypeAny, {
-    body: string;
-    heading: string;
-    numeric: string;
-    label: string;
-    fontFaces?: string | undefined;
-  }, {
-    body: string;
-    heading: string;
-    numeric: string;
-    label: string;
-    fontFaces?: string | undefined;
-  }>;
-  type: z.ZodObject<Record<"xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "display", z.ZodString>, "strip", z.ZodTypeAny, {
-    xs: string;
-    sm: string;
-    base: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "3xl": string;
-    "4xl": string;
-    "5xl": string;
-    display: string;
-  }, {
-    xs: string;
-    sm: string;
-    base: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "3xl": string;
-    "4xl": string;
-    "5xl": string;
-    display: string;
-  }>;
-  radii: z.ZodObject<Record<"sm" | "lg" | "md" | "full", z.ZodString>, "strip", z.ZodTypeAny, {
-    sm: string;
-    lg: string;
-    md: string;
-    full: string;
-  }, {
-    sm: string;
-    lg: string;
-    md: string;
-    full: string;
-  }>;
-  shadows: z.ZodObject<Record<"sm" | "lg" | "md", z.ZodString>, "strip", z.ZodTypeAny, {
-    sm: string;
-    lg: string;
-    md: string;
-  }, {
-    sm: string;
-    lg: string;
-    md: string;
-  }>;
-  layout: z.ZodObject<Record<"containerMax" | "containerPad" | "headerHeight", z.ZodString>, "strip", z.ZodTypeAny, {
-    containerMax: string;
-    containerPad: string;
-    headerHeight: string;
-  }, {
-    containerMax: string;
-    containerPad: string;
-    headerHeight: string;
-  }>;
-}, "strict", z.ZodTypeAny, {
-  type: {
-    xs: string;
-    sm: string;
-    base: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "3xl": string;
-    "4xl": string;
-    "5xl": string;
-    display: string;
-  };
-  colors: {
-    ink: string;
-    inkSoft: string;
-    inkMute: string;
-    background: string;
-    surface: string;
-    surfaceAlt: string;
-    border: string;
-    borderStrong: string;
-    primary: string;
-    primaryFg: string;
-    primaryStrong: string;
-    accent: string;
-    accentFg: string;
-    accentStrong: string;
-    overlay: string;
-    overlayStrong: string;
-    overlayLight: string;
-    darkBg: string;
-    darkFg: string;
-    darkFgMute: string;
-    darkBorder: string;
-  };
-  fonts: {
-    body: string;
-    heading: string;
-    numeric: string;
-    label: string;
-    fontFaces?: string | undefined;
-  };
-  radii: {
-    sm: string;
-    lg: string;
-    md: string;
-    full: string;
-  };
-  shadows: {
-    sm: string;
-    lg: string;
-    md: string;
-  };
-  layout: {
-    containerMax: string;
-    containerPad: string;
-    headerHeight: string;
-  };
-  palette?: Record<string, string> | undefined;
-}, {
-  type: {
-    xs: string;
-    sm: string;
-    base: string;
-    lg: string;
-    xl: string;
-    "2xl": string;
-    "3xl": string;
-    "4xl": string;
-    "5xl": string;
-    display: string;
-  };
-  colors: {
-    ink: string;
-    inkSoft: string;
-    inkMute: string;
-    background: string;
-    surface: string;
-    surfaceAlt: string;
-    border: string;
-    borderStrong: string;
-    primary: string;
-    primaryFg: string;
-    primaryStrong: string;
-    accent: string;
-    accentFg: string;
-    accentStrong: string;
-    overlay: string;
-    overlayStrong: string;
-    overlayLight: string;
-    darkBg: string;
-    darkFg: string;
-    darkFgMute: string;
-    darkBorder: string;
-  };
-  fonts: {
-    body: string;
-    heading: string;
-    numeric: string;
-    label: string;
-    fontFaces?: string | undefined;
-  };
-  radii: {
-    sm: string;
-    lg: string;
-    md: string;
-    full: string;
-  };
-  shadows: {
-    sm: string;
-    lg: string;
-    md: string;
-  };
-  layout: {
-    containerMax: string;
-    containerPad: string;
-    headerHeight: string;
-  };
-  palette?: Record<string, string> | undefined;
-}>;
+  colors: z.ZodRecord<z.ZodString, z.ZodString>;
+  fonts: z.ZodRecord<z.ZodString, z.ZodString>;
+  type: z.ZodRecord<z.ZodString, z.ZodString>;
+  radii: z.ZodRecord<z.ZodString, z.ZodString>;
+  shadows: z.ZodRecord<z.ZodString, z.ZodString>;
+  layout: z.ZodRecord<z.ZodString, z.ZodString>;
+  fontFaces: z.ZodOptional<z.ZodString>;
+  document: z.ZodObject<{
+    font: z.ZodString;
+    color: z.ZodString;
+    background: z.ZodString;
+    fontSize: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>;
 type TokenTheme = z.infer<typeof TokenThemeSchema>;
 /**
- * Compile a `TokenTheme` into the CSS a template's bundle ships: an optional
- * font-loading block followed by a single `:root { --tr-*: … }` declaration.
- * Deterministic (stable key order; palette keys sorted) so the same theme
- * always content-hashes identically.
+ * Compile a `TokenTheme` into the CSS a template's bundle ships:
+ *
+ *   1. the optional font-loading block;
+ *   2. `@theme inline { --color-<name>: var(--tr-color-<name>); … }` — the Tailwind
+ *      alias layer, which is what brings the token utilities into existence;
+ *   3. `:root { --tr-color-<name>: <value>; … }` — the values behind those aliases;
+ *   4. `body { … }` — the document defaults, as `var()` indirections so that a runtime
+ *      `:root` override still cascades to the page.
+ *
+ * The output MUST be compiled INSIDE the Tailwind build graph: `@theme` is a Tailwind
+ * directive, and anywhere else it is inert — silently, yielding a stylesheet with no
+ * token utilities and no error to explain why.
+ *
+ * Deterministic: keys are sorted, so the same theme always content-hashes identically.
  */
 declare function compileThemeToCss(theme: TokenTheme): string;
 //#endregion
-export { COLOR_ROLE_VARS, ColorRole, FONT_ROLE_VARS, LAYOUT_VARS, RADIUS_VARS, SHADOW_VARS, TYPE_STEP_VARS, TokenTheme, TokenThemeSchema, compileThemeToCss };
+export { TokenNameSchema, TokenTheme, TokenThemeSchema, compileThemeToCss };