@clhaas/palette-kit 0.1.2 → 0.1.3

package/README.md

@@ -73,6 +73,57 @@ body {
 }
 ```
 
+## Step-by-step (install -> usage -> types)
+
+1) Install:
+
+```bash
+npm install @clhaas/palette-kit
+```
+
+2) Create a config file (`palette.config.mjs`):
+
+```js
+/** @type {import("@clhaas/palette-kit").CreateThemeOptions} */
+export default {
+  neutral: { source: "seed", value: "#111827" },
+  accent: { source: "seed", value: "#3d63dd" },
+  semantic: {
+    success: { source: "seed", value: "#16a34a" },
+    warning: { source: "seed", value: "#f59e0b" },
+    danger: { source: "seed", value: "#ef4444" },
+  },
+  tokens: { preset: "radix-like-ui" },
+  alpha: { enabled: true },
+  p3: true,
+};
+```
+
+3) Generate a typed theme file (includes token name types):
+
+```bash
+npx palette-kit generate --out src/theme.ts
+```
+
+4) Export CSS vars (for web apps):
+
+```ts
+import { toCssVars } from "@clhaas/palette-kit";
+import { theme } from "./theme";
+
+const css = toCssVars(theme, { prefix: "pk" });
+// write the string into a .css file or inject it at build time
+```
+
+5) Use the generated types:
+
+```ts
+import { theme, ThemeTokenMap, ThemeTokenName } from "./theme";
+
+const tokens: ThemeTokenMap = theme.tokens.light;
+const tokenName: ThemeTokenName = "bg.app";
+```
+
 ## React Native + Expo
 
 Use the React Native exporter and `useColorScheme()`:

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path 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;
+        }
+        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 (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 (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        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);
+        }
+        return resolved;
+    }
+    for (const filename of DEFAULT_CONFIG_FILES) {
+        const candidate = path.resolve(process.cwd(), filename);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    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"));
+}

package/dist/exporters/toTs.js

@@ -1,14 +1,14 @@
 export function toTs(theme) {
     const serialized = JSON.stringify(theme, null, 2);
-    return `export const theme = ${serialized} as const;\n`;
+    return `export const theme = ${serialized} as const;\n${typeExports()}`;
 }
 export function toTsWithMode(theme, mode) {
     if (mode === "p3") {
         const serialized = JSON.stringify(toP3Theme(theme), null, 2);
-        return `export const theme = ${serialized} as const;\n`;
+        return `export const theme = ${serialized} as const;\n${typeExports()}`;
     }
     const serialized = JSON.stringify(theme, null, 2);
-    return `export const theme = ${serialized} as const;\n`;
+    return `export const theme = ${serialized} as const;\n${typeExports()}`;
 }
 function toP3Theme(theme) {
     const scales = Object.fromEntries(Object.entries(theme.scales).map(([slot, scale]) => {
@@ -26,3 +26,12 @@ function toP3Theme(theme) {
     }));
     return { ...theme, scales };
 }
+function typeExports() {
+    return [
+        "export type Theme = typeof theme;",
+        'export type ThemeScaleName = keyof Theme["scales"];',
+        'export type ThemeTokenName = keyof Theme["tokens"]["light"];',
+        'export type ThemeTokenMap = Theme["tokens"]["light"];',
+        "",
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { generateAlphaScale } from "./alpha/generateAlphaScale.js";
 export { apcaContrast } from "./contrast/apca.js";
 export { onSolidTextTokens } from "./contrast/onSolid.js";
 export { adjustTextColor } from "./contrast/solveText.js";
+export type { CreateThemeOptions, TokenOverrides } from "./createTheme.js";
 export { createTheme } from "./createTheme.js";
 export { radixSeedNames, radixSeeds } from "./data/radixSeeds.js";
 export { analyzeScale } from "./diagnostics/analyzeScale.js";

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@clhaas/palette-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Easy way to create the color palette of your app",
   "license": "MIT",
   "author": "Claus Haas",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "palette-kit": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -19,6 +22,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "rm -rf dist",
+    "generate:theme": "tsx -e \"import { createTheme, toTs } from './src/index.ts'; import { writeFileSync } from 'node:fs'; const theme = createTheme({ neutral: { source: 'seed', value: '#111827' }, accent: { source: 'seed', value: '#3d63dd' }, semantic: { success: { source: 'seed', value: '#16a34a' }, warning: { source: 'seed', value: '#f59e0b' }, danger: { source: 'seed', value: '#ef4444' } }, tokens: { preset: 'radix-like-ui' }, alpha: { enabled: true, background: { light: '#ffffff', dark: '#111111' } }, contrast: { textPrimary: 75, textSecondary: 60 }, p3: true }); const ts = toTs(theme); writeFileSync('docs/theme.generated.ts', ts);\"",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -41,6 +45,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
     "@types/apca-w3": "^0.1.3",
+    "@types/node": "^22.10.5",
     "markdownlint-cli": "^0.47.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",