@symblight/md-colors 0.1.0 → 0.2.0

package/README.md

@@ -10,44 +10,61 @@ Built on [`@material/material-color-utilities`](https://github.com/material-foun
 npm install @symblight/md-colors
 ```
 
-## Two builds
+## Builds
 
 | Build | Entry | Format | Use case |
 |---|---|---|---|
-| Node / bundler | `dist/index.js` | ESM | Programmatic token generation, CSS file output |
-| Browser (bundler) | `dist/client.esm.js` | ESM | Vite, Storybook, bundler imports |
-| Browser (script) | `dist/client.js` | IIFE | Plain `<script>` tag, no bundler |
+| Node / bundler | `dist/index.js` | ESM | `generateTokens`, `generateCSSFile` |
+| Browser (bundler) | `dist/client.esm.js` | ESM | Vite, Storybook — named import |
+| Browser (CJS) | `dist/client.cjs` | CJS | `require("@symblight/md-colors/client")` |
+| Browser (script) | `dist/client.js` | IIFE | Plain `<script>` tag — `window.MdColors` |
+| CLI | `dist/cli.js` | ESM | Terminal usage via `md-colors` |
 
 ---
 
 ## Node — programmatic API
 
-Import `generateTokens` to build token maps in Node.js scripts or server-side tooling.
-
 ```js
-import { generateTokens } from "@symblight/md-colors";
+import { generateTokens, generateCSSFile } from "@symblight/md-colors";
+```
+
+### `generateTokens(config)`
+
+Returns a token map — use it to apply tokens however you like. All 49 MD3
+color roles are resolved from one tonal-spot scheme (the M3 default), including
+`surface-container`, `surface-tint` and the `*-fixed` / `*-fixed-dim` /
+`on-*-fixed` / `on-*-fixed-variant` roles. Missing config fields fall back to
+their defaults; an invalid `sourceColor` or `scheme` throws a `TypeError`.
 
+```js
 const tokens = generateTokens({ sourceColor: "#6750A4", scheme: "dark" });
 // { "--md-sys-color-primary": "oklch(…)", … }
 ```
 
-### `generateTokens(config)`
-
 | Param | Type | Default | Description |
 |---|---|---|---|
 | `config.sourceColor` | `string` | `"#1D5D78"` | Seed color as a hex string |
 | `config.scheme` | `"light" \| "dark"` | `"light"` | Color scheme variant |
 
-Returns `Record<string, string>` — CSS variable names mapped to oklch color strings.
-
-### Generate a CSS file
+### `generateCSSFile(config)`
 
-Run the following to write a `colors.css` file to the package directory:
+Writes a `colors.css` file with `:root`-scoped tokens. Returns a promise that
+resolves with the absolute output path and rejects if the write fails.
 
-```bash
-pnpm generate-theme
+```js
+await generateCSSFile({
+  sourceColor: "#6750A4",
+  scheme: "dark",
+  output: "./theme/colors.css",
+});
 ```
 
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `config.sourceColor` | `string` | `"#1D5D78"` | Seed color as a hex string |
+| `config.scheme` | `"light" \| "dark"` | `"light"` | Color scheme variant |
+| `config.output` | `string` | `./colors.css` (next to module) | Output file path |
+
 Output:
 
 ```css
@@ -59,47 +76,77 @@ Output:
 }
 ```
 
-Source color and scheme are configured directly in `create-theme-file.mjs`.
-
 ---
 
 ## Browser client — runtime theming
 
-The browser build registers `window.generateTheme`, which injects tokens as CSS custom properties on `:root` at runtime.
+Import `generateTheme` and call it directly — no globals, no window assignment.
 
-### Via ES module import (Vite, Storybook)
+### Named import (Vite, Storybook, bundler)
 
 ```js
-import "@symblight/md-colors/client";
+import { generateTheme } from "@symblight/md-colors/client";
 
-window.generateTheme({ sourceColor: "#6750A4", scheme: "dark" });
+generateTheme({ sourceColor: "#6750A4", scheme: "dark" });
 ```
 
 ### Via `<script>` tag (no bundler)
 
+```html
+<script type="module">
+  import { generateTheme } from "./node_modules/@symblight/md-colors/dist/client.esm.js";
+  generateTheme({ sourceColor: "#6750A4", scheme: "dark" });
+</script>
+```
+
+Or with the self-contained IIFE build:
+
 ```html
 <script src="node_modules/@symblight/md-colors/dist/client.js"></script>
 <script>
-  window.generateTheme({ sourceColor: "#6750A4", scheme: "dark" });
+  MdColors.generateTheme({ sourceColor: "#6750A4", scheme: "dark" });
 </script>
 ```
 
-### `window.generateTheme(options)`
+### `generateTheme(options)`
 
 | Param | Type | Default | Description |
 |---|---|---|---|
-| `options.sourceColor` | `string` | — | Seed color as a hex string |
+| `options.sourceColor` | `string` | `"#1D5D78"` | Seed color as a hex string |
 | `options.scheme` | `"light" \| "dark"` | `"light"` | Color scheme variant |
 
 Sets every `--md-sys-color-*` variable on `document.documentElement` via `style.setProperty`.
 
 ---
 
+## CLI
+
+```bash
+# npx (no install)
+npx md-colors --sourceColor="#6750A4" --scheme=dark --output=./theme/colors.css
+
+# global install
+npm install -g @symblight/md-colors
+md-colors --sourceColor="#6750A4" --scheme=light --output=./colors.css
+```
+
+### Options
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--sourceColor` | `-c` | `#1D5D78` | Seed color as a hex string |
+| `--scheme` | `-s` | `light` | `light` or `dark` |
+| `--output` | `-o` | `./colors.css` | Output file path |
+
+Exits with code 1 on an invalid color, invalid scheme or failed write.
+
+---
+
 ## Development
 
 ```bash
 pnpm build            # Build all dist outputs
-pnpm generate-theme   # Write colors.css
+pnpm generate-theme   # Write colors.css via CLI (uses defaults)
 pnpm test             # Run Jest tests
 ```
 

package/dist/cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+// cli.mjs
+import { parseArgs } from "node:util";
+
+// create-theme-file.mjs
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+// tokens.mjs
+import {
+  argbFromHex,
+  hexFromArgb,
+  MaterialDynamicColors,
+  SchemeTonalSpot,
+  Hct
+} from "@material/material-color-utilities";
+import { converter, formatCss } from "culori";
+var oklch = converter("oklch");
+var DEFAULT_SOURCE_COLOR = "#1D5D78";
+var HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+var COLOR_ROLES = (
+  /** @type {const} */
+  [
+    "primary",
+    "onPrimary",
+    "primaryContainer",
+    "onPrimaryContainer",
+    "inversePrimary",
+    "primaryFixed",
+    "primaryFixedDim",
+    "onPrimaryFixed",
+    "onPrimaryFixedVariant",
+    "secondary",
+    "onSecondary",
+    "secondaryContainer",
+    "onSecondaryContainer",
+    "secondaryFixed",
+    "secondaryFixedDim",
+    "onSecondaryFixed",
+    "onSecondaryFixedVariant",
+    "tertiary",
+    "onTertiary",
+    "tertiaryContainer",
+    "onTertiaryContainer",
+    "tertiaryFixed",
+    "tertiaryFixedDim",
+    "onTertiaryFixed",
+    "onTertiaryFixedVariant",
+    "error",
+    "onError",
+    "errorContainer",
+    "onErrorContainer",
+    "surface",
+    "onSurface",
+    "surfaceVariant",
+    "onSurfaceVariant",
+    "surfaceDim",
+    "surfaceBright",
+    "surfaceContainerLowest",
+    "surfaceContainerLow",
+    "surfaceContainer",
+    "surfaceContainerHigh",
+    "surfaceContainerHighest",
+    "surfaceTint",
+    "inverseSurface",
+    "inverseOnSurface",
+    "outline",
+    "outlineVariant",
+    "shadow",
+    "scrim",
+    "background",
+    "onBackground"
+  ]
+);
+function resolveConfig({ sourceColor = DEFAULT_SOURCE_COLOR, scheme = "light" } = {}) {
+  if (typeof sourceColor !== "string" || !HEX_RE.test(sourceColor)) {
+    throw new TypeError(`sourceColor must be a hex color like "#6750A4", got ${JSON.stringify(sourceColor)}`);
+  }
+  if (scheme !== "light" && scheme !== "dark") {
+    throw new TypeError(`scheme must be "light" or "dark", got ${JSON.stringify(scheme)}`);
+  }
+  return { sourceColor, scheme: (
+    /** @type {ColorScheme} */
+    scheme
+  ) };
+}
+function setSchemeProperties(scheme, suffix = "") {
+  let result = {};
+  for (const [key, value] of Object.entries(scheme)) {
+    const token = key.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+    const color = hexFromArgb(value);
+    const converted = oklch(color);
+    const name = formatCss(converted);
+    const variableName = `--md-sys-color-${token}${suffix}`;
+    result[variableName] = name;
+  }
+  return result;
+}
+function generateTokens(config = {}) {
+  const { sourceColor, scheme } = resolveConfig(config);
+  const dynamicScheme = new SchemeTonalSpot(
+    Hct.fromInt(argbFromHex(sourceColor)),
+    scheme === "dark",
+    0
+  );
+  let palette = {};
+  for (const role of COLOR_ROLES) {
+    palette[role] = MaterialDynamicColors[role].getArgb(dynamicScheme);
+  }
+  return setSchemeProperties(palette);
+}
+
+// create-theme-file.mjs
+function template(variables) {
+  return `:root {
+          ${variables}
+    }`;
+}
+function normalizeCSSVariablesContent(variables = {}) {
+  let str = "";
+  for (const cssVar in variables) {
+    str += `${cssVar}: ${variables[cssVar]};
+`;
+  }
+  return str;
+}
+async function generateCSSFile(config = {}) {
+  const { output: output2, ...tokenConfig } = config;
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const outputPath = output2 ? path.resolve(output2) : path.join(__dirname, "colors.css");
+  const tokens = generateTokens(tokenConfig);
+  const stringTokens = normalizeCSSVariablesContent(tokens);
+  const themeBody = template(stringTokens);
+  await fs.writeFile(outputPath, themeBody);
+  return outputPath;
+}
+
+// cli.mjs
+var { values } = parseArgs({
+  options: {
+    sourceColor: { type: "string", short: "c", default: DEFAULT_SOURCE_COLOR },
+    scheme: { type: "string", short: "s", default: "light" },
+    output: { type: "string", short: "o", default: "./colors.css" }
+  }
+});
+var { output } = values;
+try {
+  const { sourceColor, scheme } = resolveConfig(values);
+  const outputPath = await generateCSSFile({ sourceColor, scheme, output });
+  console.log(`Generated ${outputPath} (sourceColor: ${sourceColor}, scheme: ${scheme})`);
+} catch (err) {
+  console.error(`Error: ${err instanceof Error ? err.message : err}`);
+  process.exit(1);
+}