@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/cli/codegen/tokens.ts

@@ -1,191 +0,0 @@
-import type { TokenDefinition, TokenRegistry } from "../../types/index.js";
-
-type TokenTreeNode = {
-  children: Map<string, TokenTreeNode>;
-  token?: TokenDefinition;
-};
-
-const RESERVED_WORDS = new Set([
-  "break",
-  "case",
-  "catch",
-  "class",
-  "const",
-  "continue",
-  "debugger",
-  "default",
-  "delete",
-  "do",
-  "else",
-  "export",
-  "extends",
-  "finally",
-  "for",
-  "function",
-  "if",
-  "import",
-  "in",
-  "instanceof",
-  "new",
-  "return",
-  "super",
-  "switch",
-  "this",
-  "throw",
-  "try",
-  "typeof",
-  "var",
-  "void",
-  "while",
-  "with",
-  "yield",
-]);
-
-const isValidIdentifier = (value: string) => {
-  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)) return false;
-  return !RESERVED_WORDS.has(value);
-};
-
-const toPropertyKey = (key: string) => (isValidIdentifier(key) ? key : JSON.stringify(key));
-
-const indentLines = (lines: string[], spaces: number) => {
-  const prefix = " ".repeat(spaces);
-  return lines.map((line) => (line.length ? `${prefix}${line}` : line));
-};
-
-const escapeJsDoc = (value: string) => value.replace(/\*\//g, "*\\/");
-
-const buildTokenJsDocLines = (tokenName: string, token: TokenDefinition) => {
-  const lines: string[] = [];
-  if (token.description?.trim()) {
-    lines.push(escapeJsDoc(token.description.trim()));
-  }
-
-  lines.push(`@token ${tokenName}`);
-
-  if (token.category?.trim()) {
-    lines.push(`@category ${escapeJsDoc(token.category.trim())}`);
-  }
-
-  const states = token.states ? Object.keys(token.states).sort() : [];
-  if (states.length > 0) {
-    lines.push(`@states ${states.join(", ")}`);
-  }
-
-  return ["/**", ...lines.map((line) => ` * ${line}`), " */"];
-};
-
-const buildTree = (registry: TokenRegistry): TokenTreeNode => {
-  const root: TokenTreeNode = { children: new Map() };
-
-  const entries = Object.entries(registry.tokens).sort(([a], [b]) => a.localeCompare(b));
-  for (const [tokenName, token] of entries) {
-    const segments = tokenName.split(".").filter(Boolean);
-    if (segments.length === 0) continue;
-
-    let node = root;
-    for (const segment of segments) {
-      let child = node.children.get(segment);
-      if (!child) {
-        child = { children: new Map() };
-        node.children.set(segment, child);
-      }
-      node = child;
-    }
-
-    node.token = token;
-  }
-
-  return root;
-};
-
-const renderTreeTs = (node: TokenTreeNode, tokenNamePrefix: string): string[] => {
-  const lines: string[] = ["{"];
-
-  const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
-  for (const key of keys) {
-    const child = node.children.get(key);
-    if (!child) continue;
-
-    const fullTokenName = tokenNamePrefix ? `${tokenNamePrefix}.${key}` : key;
-    const propKey = toPropertyKey(key);
-
-    if (child.token && child.children.size === 0) {
-      lines.push(...buildTokenJsDocLines(fullTokenName, child.token));
-      lines.push(`${propKey}: "${fullTokenName}",`);
-      continue;
-    }
-
-    const childLines = renderTreeTs(child, fullTokenName);
-    lines.push(`${propKey}: ${childLines[0]}`);
-    lines.push(...indentLines(childLines.slice(1), 2));
-    lines[lines.length - 1] = `${lines[lines.length - 1]},`;
-  }
-
-  lines.push("}");
-  return lines;
-};
-
-const renderTreeDts = (node: TokenTreeNode, tokenNamePrefix: string): string[] => {
-  const lines: string[] = ["{"];
-
-  const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
-  for (const key of keys) {
-    const child = node.children.get(key);
-    if (!child) continue;
-
-    const fullTokenName = tokenNamePrefix ? `${tokenNamePrefix}.${key}` : key;
-    const propKey = toPropertyKey(key);
-
-    if (child.token && child.children.size === 0) {
-      lines.push(...buildTokenJsDocLines(fullTokenName, child.token));
-      lines.push(`${propKey}: "${fullTokenName}";`);
-      continue;
-    }
-
-    const childLines = renderTreeDts(child, fullTokenName);
-    lines.push(`${propKey}: ${childLines[0]}`);
-    lines.push(...indentLines(childLines.slice(1), 2));
-    lines[lines.length - 1] = `${lines[lines.length - 1]};`;
-  }
-
-  lines.push("}");
-  return lines;
-};
-
-export type GeneratedTokens = {
-  tokenNames: string[];
-  tokensTs: string;
-  tokensDts: string;
-};
-
-/**
- * Generate `dist/palette/tokens.ts` and `dist/palette/tokens.d.ts` sources.
- *
- * Output is deterministic and derived from the token registry.
- */
-export const generateTokenArtifacts = (registry: TokenRegistry): GeneratedTokens => {
-  const tokenNames = Object.keys(registry.tokens).sort((a, b) => a.localeCompare(b));
-  const tree = buildTree(registry);
-
-  const tokensObject = renderTreeTs(tree, "");
-  const tokensDtsObject = renderTreeDts(tree, "");
-
-  const tokensTs = `/* This file is generated by palette-kit build (Phase 7). */\n\nexport const tokens = ${tokensObject.join(
-    "\n",
-  )} as const;\n\nexport const tokenNames = ${JSON.stringify(
-    tokenNames,
-    null,
-    2,
-  )} as const;\n\nexport type TokenName = (typeof tokenNames)[number];\n\nexport type ColorRole = TokenName;\n`;
-
-  const tokensDts = `/* This file is generated by palette-kit build (Phase 7). */\n\nexport declare const tokens: ${tokensDtsObject.join(
-    "\n",
-  )};\n\nexport declare const tokenNames: readonly ${JSON.stringify(
-    tokenNames,
-    null,
-    2,
-  )};\n\nexport type TokenName = (typeof tokenNames)[number];\n\nexport type ColorRole = TokenName;\n`;
-
-  return { tokenNames, tokensTs, tokensDts };
-};

package/src/cli/config.ts

@@ -1,71 +0,0 @@
-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 const buildConfigTemplate = (
-  packageName: string,
-) => `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: string): value is TokenPresetName =>
-  value === "minimal-ui" || value === "radixLike-ui" || value === "modern-ui";

package/src/cli/validate.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { validateConfig } from "./validate.js";
-import type { PaletteConfig } from "./config.js";
-
-describe("cli config validation", () => {
-  it("accepts a valid config", () => {
-    const config: PaletteConfig = {
-      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" },
-    } as unknown as PaletteConfig;
-
-    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" },
-    } as unknown as PaletteConfig;
-
-    expect(() => validateConfig(config)).toThrow(/Unsupported token preset/);
-  });
-});
-

package/src/cli/validate.ts

@@ -1,38 +0,0 @@
-import { isTokenPresetName, type PaletteConfig } from "./config.js";
-
-const validateSeed = (context: "light" | "dark", value: unknown) => {
-  if (!value || typeof value !== "object") {
-    throw new Error(`Config.theme.seeds.${context} must be an object`);
-  }
-  const seed = value as Record<string, unknown>;
-  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: PaletteConfig) => {
-  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/src/cli.ts

@@ -1,183 +0,0 @@
-#!/usr/bin/env node
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { CliUsageError, COMMANDS, HELP_TEXT, type ParsedArgs, parseArgs } from "./cli/args.js";
-import { generateTokenArtifacts } from "./cli/codegen/tokens.js";
-import { buildConfigTemplate, type PaletteConfig } from "./cli/config.js";
-import { validateConfig } from "./cli/validate.js";
-import { createTheme } from "./core/createTheme.js";
-import { validateTokenRegistry } from "./core/tokenRegistry.js";
-import type { ThemeTokens } from "./export/exportTheme.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) as { name: string; version: string };
-};
-
-const printHelp = () => {
-  console.log(HELP_TEXT);
-};
-
-const printVersion = async () => {
-  const pkg = await readPackageJson();
-  console.log(pkg.version);
-};
-
-const ensureDir = async (dir: string) => {
-  await mkdir(dir, { recursive: true });
-};
-
-const exists = async (filePath: string) => {
-  try {
-    await stat(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-const loadConfig = async (configPath: string): Promise<PaletteConfig> => {
-  const resolved = resolve(configPath);
-  try {
-    const module = await import(pathToFileURL(resolved).href);
-    const config = (module.default ?? module) as PaletteConfig;
-    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: typeof minimalUiTokens): ThemeTokens =>
-  Object.fromEntries(Object.entries(registry.tokens).map(([name, token]) => [name, token.query]));
-
-const writeTokensCodegen = async (outDir: string, registry: typeof minimalUiTokens) => {
-  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: string,
-  config: PaletteConfig,
-  tokenCount: number,
-  outputFiles: string[],
-) => {
-  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: ParsedArgs["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: ParsedArgs["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 (parsed.help || !parsed.command) {
-      printHelp();
-      return;
-    }
-
-    if (!COMMANDS.includes(parsed.command as (typeof COMMANDS)[number])) {
-      throw new CliUsageError(`Unknown command: ${parsed.command}`);
-    }
-
-    if (parsed.command === "init") {
-      await runInit(parsed.flags);
-      return;
-    }
-
-    if (parsed.command === "build") {
-      await runBuild(parsed.flags);
-      return;
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
-    if (error instanceof CliUsageError) {
-      console.error("");
-      printHelp();
-    }
-    process.exitCode = 1;
-  }
-};
-
-void main();

package/src/contrast/apca.test.ts

@@ -1,20 +0,0 @@
-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/src/contrast/apca.ts

@@ -1,26 +0,0 @@
-import { APCAcontrast, sRGBtoY } from "apca-w3";
-
-import type { SrgbColor } from "./types.js";
-
-// NOTE:
-// sRGBtoY expects 0-255 RGB values (3-tuple). Also APCA impl can yield
-// a string|number, so normalize to number before Number.isFinite.
-
-type SrgbTriplet = [r: number, g: number, b: number];
-
-const clamp01 = (value: number) => Math.min(1, Math.max(0, value));
-
-const toApcaInput = (color: SrgbColor): SrgbTriplet => [
-  clamp01(color.r) * 255,
-  clamp01(color.g) * 255,
-  clamp01(color.b) * 255,
-];
-
-export function computeApcaLc(fg: SrgbColor, bg: SrgbColor): number {
-  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/src/contrast/index.ts

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