@clhaas/palette-kit 0.1.7 → 0.3.0

package/dist/cli/codegen/tokens.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { generateTokenArtifacts } from "./tokens.js";
+describe("codegen tokens", () => {
+    const registry = {
+        tokens: {
+            "bg.app": {
+                name: "bg.app",
+                description: "App background.",
+                category: "bg",
+                query: { role: "bg.app", usage: "bg", surface: "app" },
+            },
+            "text.primary": {
+                name: "text.primary",
+                description: "Primary text on standard surfaces.",
+                category: "text",
+                query: { role: "text.primary", usage: "text", surface: "surface" },
+                states: { hover: true },
+            },
+            "border.default": {
+                name: "border.default",
+                description: "Default border color.",
+                category: "border",
+                query: { role: "border.default", usage: "border", surface: "surface" },
+            },
+        },
+    };
+    it("generates navigable tokens.ts and tokens.d.ts", () => {
+        const { tokensTs, tokensDts } = generateTokenArtifacts(registry);
+        expect(tokensTs).toContain('export const tokens = {');
+        expect(tokensTs).toContain('bg: {');
+        expect(tokensTs).toContain('app: "bg.app"');
+        expect(tokensTs).toContain('text: {');
+        expect(tokensTs).toContain('primary: "text.primary"');
+        expect(tokensTs).toMatchSnapshot();
+        expect(tokensDts).toMatchSnapshot();
+    });
+    it("is deterministic regardless of registry object order", () => {
+        const shuffled = {
+            tokens: {
+                "text.primary": registry.tokens["text.primary"],
+                "bg.app": registry.tokens["bg.app"],
+                "border.default": registry.tokens["border.default"],
+            },
+        };
+        const a = generateTokenArtifacts(registry);
+        const b = generateTokenArtifacts(shuffled);
+        expect(b.tokenNames).toEqual(a.tokenNames);
+        expect(b.tokensTs).toBe(a.tokensTs);
+        expect(b.tokensDts).toBe(a.tokensDts);
+    });
+});

package/dist/cli/config.d.ts

@@ -0,0 +1,40 @@
+import type { ThemeConfig } from "../engine/resolveBaseColor.js";
+import type { OutputOptions } from "../types/index.js";
+/**
+ * Official token preset names supported by Palette Kit tooling.
+ *
+ * These map to `src/presets/tokens/*` registries.
+ */
+export type TokenPresetName = "minimal-ui" | "radixLike-ui" | "modern-ui";
+/**
+ * Configuration contract for `palette-kit build`.
+ *
+ * This file is consumed by the CLI and is intended to be used from
+ * `palette.config.ts` created by `palette-kit init`.
+ */
+export type PaletteConfig = {
+    /**
+     * Theme inputs for palette generation (seed colors + optional variants).
+     */
+    theme: ThemeConfig;
+    /**
+     * Token preset selection for exporters/CLI.
+     */
+    tokens: {
+        preset: TokenPresetName;
+    };
+    /**
+     * Exporter options (formatting, gamut mapping, precision).
+     */
+    output?: OutputOptions;
+};
+/**
+ * Build a `palette.config.ts` template for `palette-kit init`.
+ *
+ * @param packageName - Import path used for `PaletteConfig` typing (usually the package name).
+ */
+export declare const buildConfigTemplate: (packageName: string) => string;
+/**
+ * Runtime guard for token preset strings coming from user config.
+ */
+export declare const isTokenPresetName: (value: string) => value is TokenPresetName;

package/dist/cli/config.js

@@ -0,0 +1,34 @@
+/**
+ * Build a `palette.config.ts` template for `palette-kit init`.
+ *
+ * @param packageName - Import path used for `PaletteConfig` typing (usually the package name).
+ */
+export const buildConfigTemplate = (packageName) => `import type { PaletteConfig } from "${packageName}";
+
+/**
+ * Palette Kit configuration.
+ * Update seeds, preset, and output options to match your design system.
+ */
+const config: PaletteConfig = {
+  theme: {
+    seeds: {
+      light: { neutral: "#8B8D98", accent: "#3D63DD" },
+      dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+    },
+    preset: "modern",
+  },
+  tokens: {
+    preset: "modern-ui",
+  },
+  output: {
+    preferSpace: "oklch",
+    includeSpaces: ["srgb", "p3"],
+  },
+};
+
+export default config;
+`;
+/**
+ * Runtime guard for token preset strings coming from user config.
+ */
+export const isTokenPresetName = (value) => value === "minimal-ui" || value === "radixLike-ui" || value === "modern-ui";

package/dist/cli/validate.d.ts

@@ -0,0 +1,2 @@
+import { type PaletteConfig } from "./config.js";
+export declare const validateConfig: (config: PaletteConfig) => void;

package/dist/cli/validate.js

@@ -0,0 +1,33 @@
+import { isTokenPresetName } from "./config.js";
+const validateSeed = (context, value) => {
+    if (!value || typeof value !== "object") {
+        throw new Error(`Config.theme.seeds.${context} must be an object`);
+    }
+    const seed = value;
+    if (typeof seed.neutral !== "string") {
+        throw new Error(`Config.theme.seeds.${context}.neutral must be a string color`);
+    }
+    if (typeof seed.accent !== "string") {
+        throw new Error(`Config.theme.seeds.${context}.accent must be a string color`);
+    }
+};
+export const validateConfig = (config) => {
+    if (!config || typeof config !== "object") {
+        throw new Error("Config must export a default object");
+    }
+    if (!config.theme) {
+        throw new Error("Config.theme is required");
+    }
+    const seeds = config.theme.seeds;
+    if (!seeds?.light || !seeds?.dark) {
+        throw new Error("Config.theme.seeds.light and .dark are required");
+    }
+    validateSeed("light", seeds.light);
+    validateSeed("dark", seeds.dark);
+    if (!config.tokens?.preset) {
+        throw new Error("Config.tokens.preset is required");
+    }
+    if (!isTokenPresetName(config.tokens.preset)) {
+        throw new Error(`Unsupported token preset: ${config.tokens.preset}`);
+    }
+};

package/dist/cli/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/validate.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { validateConfig } from "./validate.js";
+describe("cli config validation", () => {
+    it("accepts a valid config", () => {
+        const config = {
+            theme: {
+                seeds: {
+                    light: { neutral: "#111827", accent: "#3d63dd" },
+                    dark: { neutral: "#111827", accent: "#3d63dd" },
+                },
+            },
+            tokens: { preset: "modern-ui" },
+        };
+        expect(() => validateConfig(config)).not.toThrow();
+    });
+    it("rejects missing neutral/accent", () => {
+        const config = {
+            theme: {
+                seeds: {
+                    light: { neutral: "#111827" },
+                    dark: { accent: "#3d63dd" },
+                },
+            },
+            tokens: { preset: "modern-ui" },
+        };
+        expect(() => validateConfig(config)).toThrow(/must be a string color/);
+    });
+    it("rejects invalid preset", () => {
+        const config = {
+            theme: {
+                seeds: {
+                    light: { neutral: "#111827", accent: "#3d63dd" },
+                    dark: { neutral: "#111827", accent: "#3d63dd" },
+                },
+            },
+            tokens: { preset: "nope" },
+        };
+        expect(() => validateConfig(config)).toThrow(/Unsupported token preset/);
+    });
+});

package/dist/cli.js

@@ -1,150 +1,148 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { createTheme } from "./createTheme.js";
-import { toTs, toTsWithMode } from "./exporters/toTs.js";
-const DEFAULT_CONFIG_FILES = [
-    "palette.config.mjs",
-    "palette.config.js",
-    "palette.config.cjs",
-    "palette.config.json",
-];
-const args = process.argv.slice(2);
-const command = args[0];
-if (!command || command === "--help" || command === "-h") {
-    printHelp();
-    process.exit(0);
-}
-if (command !== "generate") {
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    process.exit(1);
-}
-const options = parseArgs(args.slice(1));
-const configPath = resolveConfigPath(options.configPath);
-const outPath = path.resolve(process.cwd(), options.outPath ?? "src/theme.ts");
-const mode = options.mode;
-const config = await loadConfig(configPath);
-if (!config || typeof config !== "object") {
-    console.error("Config must export a plain object with createTheme options.");
-    process.exit(1);
-}
-if (!("neutral" in config) || !("accent" in config)) {
-    console.error("Config must include at least `neutral` and `accent` sources.");
-    process.exit(1);
-}
-const theme = createTheme(config);
-const ts = mode ? toTsWithMode(theme, mode) : toTs(theme);
-mkdirSync(path.dirname(outPath), { recursive: true });
-writeFileSync(outPath, ts);
-console.log(`Generated ${path.relative(process.cwd(), outPath)}`);
-function parseArgs(input) {
-    const options = {};
-    for (let i = 0; i < input.length; i += 1) {
-        const arg = input[i];
-        if (arg === "--config" || arg === "-c") {
-            options.configPath = input[i + 1];
-            i += 1;
-            continue;
-        }
-        if (arg?.startsWith("--config=")) {
-            options.configPath = arg.split("=")[1];
-            continue;
-        }
-        if (arg === "--out" || arg === "-o") {
-            options.outPath = input[i + 1];
-            i += 1;
-            continue;
-        }
-        if (arg?.startsWith("--out=")) {
-            options.outPath = arg.split("=")[1];
-            continue;
+import { CliUsageError, COMMANDS, HELP_TEXT, parseArgs } from "./cli/args.js";
+import { generateTokenArtifacts } from "./cli/codegen/tokens.js";
+import { buildConfigTemplate } from "./cli/config.js";
+import { validateConfig } from "./cli/validate.js";
+import { createTheme } from "./core/createTheme.js";
+import { validateTokenRegistry } from "./core/tokenRegistry.js";
+import { exportThemeCss, exportThemeJson } from "./export/exportTheme.js";
+import { minimalUiTokens, modernUiTokens, radixLikeUiTokens } from "./presets/tokens/index.js";
+const readPackageJson = async () => {
+    const url = new URL("../package.json", import.meta.url);
+    const content = await readFile(url, "utf8");
+    return JSON.parse(content);
+};
+const printHelp = () => {
+    console.log(HELP_TEXT);
+};
+const printVersion = async () => {
+    const pkg = await readPackageJson();
+    console.log(pkg.version);
+};
+const ensureDir = async (dir) => {
+    await mkdir(dir, { recursive: true });
+};
+const exists = async (filePath) => {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const loadConfig = async (configPath) => {
+    const resolved = resolve(configPath);
+    try {
+        const module = await import(pathToFileURL(resolved).href);
+        const config = (module.default ?? module);
+        return config;
+    }
+    catch (error) {
+        const suffix = resolved.endsWith(".ts")
+            ? "\nTip: Use a .mjs config or run Node with a TS loader (e.g. tsx)."
+            : "";
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to load config at ${resolved}. ${message}${suffix}`);
+    }
+};
+const tokenPresetMap = {
+    "minimal-ui": minimalUiTokens,
+    "radixLike-ui": radixLikeUiTokens,
+    "modern-ui": modernUiTokens,
+};
+const toThemeTokens = (registry) => Object.fromEntries(Object.entries(registry.tokens).map(([name, token]) => [name, token.query]));
+const writeTokensCodegen = async (outDir, registry) => {
+    const generated = generateTokenArtifacts(registry);
+    await writeFile(join(outDir, "tokens.ts"), generated.tokensTs, "utf8");
+    await writeFile(join(outDir, "tokens.d.ts"), generated.tokensDts, "utf8");
+    return generated.tokenNames;
+};
+const writeReport = async (outDir, config, tokenCount, outputFiles) => {
+    const lines = [
+        "# Palette Kit Report",
+        "",
+        `- preset: ${config.tokens.preset}`,
+        `- tokens: ${tokenCount}`,
+        `- output: preferSpace=${config.output?.preferSpace ?? "oklch"}`,
+        `- includeSpaces: ${(config.output?.includeSpaces ?? []).join(", ") || "(none)"}`,
+        `- files: ${outputFiles.join(", ")}`,
+    ];
+    await writeFile(join(outDir, "report.md"), `${lines.join("\n")}\n`, "utf8");
+};
+const runInit = async (flags) => {
+    const targetPath = typeof flags.path === "string" ? flags.path : ".";
+    const force = Boolean(flags.force);
+    const outDir = resolve(targetPath);
+    await ensureDir(outDir);
+    const filePath = join(outDir, "palette.config.ts");
+    if (!force && (await exists(filePath))) {
+        throw new Error(`Config already exists at ${filePath}. Use --force to overwrite`);
+    }
+    const pkg = await readPackageJson();
+    await writeFile(filePath, buildConfigTemplate(pkg.name), "utf8");
+    console.log(`Created ${filePath}`);
+};
+const runBuild = async (flags) => {
+    const configPath = typeof flags.config === "string" ? flags.config : "palette.config.ts";
+    const outDir = resolve(typeof flags.outDir === "string" ? flags.outDir : "dist/palette");
+    const report = Boolean(flags.report);
+    const config = await loadConfig(configPath);
+    validateConfig(config);
+    const registry = tokenPresetMap[config.tokens.preset];
+    validateTokenRegistry(registry);
+    const theme = createTheme(config.theme);
+    const tokens = toThemeTokens(registry);
+    const css = exportThemeCss(theme, tokens, config.output).css;
+    const json = exportThemeJson(theme, tokens, config.output);
+    await ensureDir(outDir);
+    const tokenNames = await writeTokensCodegen(outDir, registry);
+    await writeFile(join(outDir, "tokens.css"), css, "utf8");
+    await writeFile(join(outDir, "tokens.json"), `${JSON.stringify(json, null, 2)}\n`, "utf8");
+    if (report) {
+        await writeReport(outDir, config, tokenNames.length, [
+            "tokens.css",
+            "tokens.json",
+            "tokens.ts",
+            "tokens.d.ts",
+        ]);
+    }
+    console.log(`Wrote ${basename(outDir)}/tokens.css, tokens.json, tokens.ts, tokens.d.ts`);
+};
+const main = async () => {
+    try {
+        const parsed = parseArgs(process.argv.slice(2));
+        if (parsed.version) {
+            await printVersion();
+            return;
         }
-        if (arg === "--mode" || arg === "-m") {
-            const value = input[i + 1];
-            if (!value) {
-                console.error('Missing value for --mode. Use "srgb" or "p3".');
-                process.exit(1);
-            }
-            if (value !== "srgb" && value !== "p3") {
-                console.error(`Invalid mode: ${value}. Use "srgb" or "p3".`);
-                process.exit(1);
-            }
-            options.mode = value;
-            i += 1;
-            continue;
+        if (parsed.help || !parsed.command) {
+            printHelp();
+            return;
         }
-        if (arg?.startsWith("--mode=")) {
-            const value = arg.split("=")[1];
-            if (!value) {
-                console.error('Missing value for --mode. Use "srgb" or "p3".');
-                process.exit(1);
-            }
-            if (value !== "srgb" && value !== "p3") {
-                console.error(`Invalid mode: ${value}. Use "srgb" or "p3".`);
-                process.exit(1);
-            }
-            options.mode = value;
-            continue;
+        if (!COMMANDS.includes(parsed.command)) {
+            throw new CliUsageError(`Unknown command: ${parsed.command}`);
         }
-        if (arg === "--help" || arg === "-h") {
-            printHelp();
-            process.exit(0);
+        if (parsed.command === "init") {
+            await runInit(parsed.flags);
+            return;
         }
-        console.error(`Unknown argument: ${arg}`);
-        printHelp();
-        process.exit(1);
-    }
-    return options;
-}
-function resolveConfigPath(configPath) {
-    if (configPath) {
-        const resolved = path.resolve(process.cwd(), configPath);
-        if (!existsSync(resolved)) {
-            console.error(`Config not found: ${configPath}`);
-            process.exit(1);
+        if (parsed.command === "build") {
+            await runBuild(parsed.flags);
+            return;
         }
-        return resolved;
     }
-    for (const filename of DEFAULT_CONFIG_FILES) {
-        const candidate = path.resolve(process.cwd(), filename);
-        if (existsSync(candidate)) {
-            return candidate;
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        if (error instanceof CliUsageError) {
+            console.error("");
+            printHelp();
         }
+        process.exitCode = 1;
     }
-    console.error("No config file found. Expected one of:");
-    for (const filename of DEFAULT_CONFIG_FILES) {
-        console.error(`  - ${filename}`);
-    }
-    process.exit(1);
-    throw new Error("No config file found.");
-}
-async function loadConfig(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
-    if (ext === ".json") {
-        const raw = readFileSync(filePath, "utf8");
-        return JSON.parse(raw);
-    }
-    if (ext === ".cjs") {
-        const require = createRequire(import.meta.url);
-        return require(filePath);
-    }
-    const module = await import(pathToFileURL(filePath).href);
-    return (module.default ?? module.config ?? module.theme ?? module);
-}
-function printHelp() {
-    console.log([
-        "palette-kit generate [options]",
-        "",
-        "Options:",
-        "  -c, --config <file>  Config file (default: palette.config.*)",
-        "  -o, --out <file>     Output file (default: src/theme.ts)",
-        "  -m, --mode <srgb|p3> Export mode (default: theme as-is)",
-        "  -h, --help           Show help",
-        "",
-        "Example:",
-        "  palette-kit generate --config palette.config.mjs --out src/theme.ts",
-    ].join("\n"));
-}
+};
+void main();

package/dist/contrast/apca.d.ts

@@ -1,2 +1,2 @@
-import type { ColorHex } from "../types.js";
-export declare function apcaContrast(foreground: ColorHex, background: ColorHex): number;
+import type { SrgbColor } from "./types.js";
+export declare function computeApcaLc(fg: SrgbColor, bg: SrgbColor): number;

package/dist/contrast/apca.js

@@ -1,5 +1,15 @@
-import { calcAPCA } from "apca-w3";
-export function apcaContrast(foreground, background) {
-    const contrast = Number(calcAPCA(foreground, background));
-    return Number(contrast.toFixed(2));
+import { APCAcontrast, sRGBtoY } from "apca-w3";
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const toApcaInput = (color) => [
+    clamp01(color.r) * 255,
+    clamp01(color.g) * 255,
+    clamp01(color.b) * 255,
+];
+export function computeApcaLc(fg, bg) {
+    const fgY = sRGBtoY(toApcaInput(fg));
+    const bgY = sRGBtoY(toApcaInput(bg));
+    const raw = APCAcontrast(fgY, bgY);
+    const value = typeof raw === "number" ? raw : Number(raw);
+    // Fail-soft to avoid propagating NaN into solver scoring.
+    return Number.isFinite(value) ? value : 0;
 }

package/dist/contrast/apca.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/contrast/apca.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { computeApcaLc } from "./apca.js";
+describe("computeApcaLc", () => {
+    it("reports high magnitude for black on white", () => {
+        const lc = computeApcaLc({ r: 0, g: 0, b: 0 }, { r: 1, g: 1, b: 1 });
+        expect(Math.abs(lc)).toBeGreaterThan(60);
+    });
+    it("reports high magnitude for white on black", () => {
+        const lc = computeApcaLc({ r: 1, g: 1, b: 1 }, { r: 0, g: 0, b: 0 });
+        expect(Math.abs(lc)).toBeGreaterThan(60);
+    });
+    it("does not return NaN", () => {
+        const lc = computeApcaLc({ r: 0.2, g: 0.4, b: 0.6 }, { r: 0.1, g: 0.1, b: 0.1 });
+        expect(Number.isNaN(lc)).toBe(false);
+    });
+});

package/dist/contrast/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./apca.js";
+export * from "./solver.js";
+export * from "./types.js";
+export * from "./wcag2.js";

package/dist/contrast/index.js

@@ -0,0 +1,4 @@
+export * from "./apca.js";
+export * from "./solver.js";
+export * from "./types.js";
+export * from "./wcag2.js";

package/dist/contrast/scoring.d.ts

@@ -0,0 +1,4 @@
+import type { ContrastRequirement } from "../types/index.js";
+import type { ContrastCheckResult } from "./types.js";
+export declare const scoreApca: (value: number, target: number, min: number, max: number, hasMax: boolean) => number;
+export declare const scoreContrast: (result: ContrastCheckResult, req: ContrastRequirement) => number;

package/dist/contrast/scoring.js

@@ -0,0 +1,31 @@
+export const scoreApca = (value, target, min, max, hasMax) => {
+    if (Number.isNaN(value)) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    if (hasMax) {
+        if (value >= min && value <= max) {
+            return 1000 - Math.abs(value - target);
+        }
+        if (value < min) {
+            return -(min - value);
+        }
+        return -(value - max);
+    }
+    if (value < min) {
+        const distance = min - value;
+        return -distance * 10 - Math.abs(value - target);
+    }
+    return -Math.abs(value - target);
+};
+export const scoreContrast = (result, req) => {
+    if (!Number.isFinite(result.value)) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    if (req.model === "apca") {
+        const min = req.minLc ?? req.targetLc;
+        const hasMax = req.maxLc !== undefined;
+        const max = req.maxLc ?? Number.POSITIVE_INFINITY;
+        return scoreApca(result.value, req.targetLc, min, max, hasMax);
+    }
+    return result.value;
+};

package/dist/contrast/scoring.test.d.ts

@@ -0,0 +1 @@
+export {};