oklchtohex 0.1.0 → 0.3.0

package/README.md

@@ -20,60 +20,80 @@ A build-time package is the most practical fix:
 npm i -D oklchtohex
 ```
 
-## CLI usage
+## JS API
 
-Convert one value:
+```js
+import { oklchToHex, replaceOklchInText, convertTailwindCssToHex } from "oklchtohex";
 
-```bash
-npx oklchtohex --value "oklch(70.4% 0.191 22.216)"
+const hex = oklchToHex("oklch(70.4% 0.191 22.216)");
+const css = replaceOklchInText("color: oklch(70.4% 0.191 22.216);");
+const convertedTailwindCss = convertTailwindCssToHex(css);
 ```
 
-Convert a CSS file and write to a new file:
+### Conversion behavior
 
-```bash
-npx oklchtohex ./dist/app.css -o ./dist/app.hex.css
-```
+- Known Tailwind default variables like `--color-red-500` are replaced with exact Tailwind HEX palette values.
+- Unknown variables and raw `oklch(...)` values use functional conversion.
+- `gamut` option supports `clip` (default) and `fit`.
 
-Print transformed CSS to stdout:
+## Vite plugin (auto on dev + build)
 
-```bash
-npx oklchtohex ./dist/app.css --stdout
+Use the built-in plugin to auto-convert CSS during `vite dev` and `vite build`.
+
+```js
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { oklchToHexVitePlugin } from "oklchtohex/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    oklchToHexVitePlugin({
+      gamut: "clip",
+      convertDev: true,
+      convertBuild: true
+    })
+  ]
+});
 ```
 
-### Options
+### Plugin options
+
+- `gamut`: `"clip"` (default) or `"fit"`
+- `includeAlpha`: `"auto"` (default), `"always"`, `"never"`
+- `uppercase`: `false` (default)
+- `onError`: `"preserve"` (default) or `"throw"`
+- `include`: `RegExp | (id) => boolean` (default matches CSS-like files)
+- `exclude`: `RegExp | (id) => boolean`
+- `convertDev`: `true` by default
+- `convertBuild`: `true` by default
+
+## Tailwind v4 build integration (package-only)
+
+Create a small Node script in your app, for example `scripts/convert-tailwind-to-hex.mjs`:
 
-- `--gamut fit|clip`  
-  `clip` (default) hard-clamps channels; `fit` reduces chroma to stay in sRGB.
-- `--alpha auto|always|never`  
-  defaults to `auto`.
-- `--upper`  
-  outputs uppercase HEX.
+```js
+import fs from "node:fs/promises";
+import { convertTailwindCssToHex } from "oklchtohex";
+
+const inputPath = "./dist/tailwind.css";
+const outputPath = "./dist/tailwind.css"; // in-place rewrite
 
-When converting Tailwind CSS, known default variables like `--color-red-500` are replaced with the exact Tailwind HEX palette value first. Unknown variables and raw `oklch(...)` values use functional conversion.
+const css = await fs.readFile(inputPath, "utf8");
+const converted = convertTailwindCssToHex(css, { gamut: "clip" });
+await fs.writeFile(outputPath, converted, "utf8");
+```
 
-## Tailwind v4 integration (Inspect Element workflow)
+Then call it in your app `package.json`:
 
 ```json
 {
   "scripts": {
     "build:css": "tailwindcss -i ./src/input.css -o ./dist/tailwind.css",
-    "build:css:hex": "oklchtohex ./dist/tailwind.css -o ./dist/tailwind.css",
+    "build:css:hex": "node ./scripts/convert-tailwind-to-hex.mjs",
     "build": "npm run build:css && npm run build:css:hex"
   }
 }
 ```
 
-This rewrites Tailwind output in-place, so your existing HTML `<link>` remains unchanged and DevTools "Styles" pane shows HEX declarations.
-
-If you want two files instead, output to `./dist/tailwind.hex.css` and link that file.
-
-Note: some browsers still show `rgb(...)` in the "Computed" pane. The "Styles" pane reflects your source declaration format.
-
-## JS API
-
-```js
-import { oklchToHex, replaceOklchInText } from "oklchtohex";
-
-const hex = oklchToHex("oklch(70.4% 0.191 22.216)");
-const css = replaceOklchInText("color: oklch(70.4% 0.191 22.216);");
-```
+This keeps the package library-only while still giving build-time conversion.

package/package.json

@@ -1,27 +1,25 @@
 {
   "name": "oklchtohex",
-  "version": "0.1.0",
-  "description": "Convert OKLCH colors to HEX and rewrite CSS at build time.",
+  "version": "0.3.0",
+  "description": "Convert OKLCH colors to HEX as a JavaScript package.",
   "type": "module",
-  "main": "./src/converter.js",
+  "main": "./src/index.js",
   "exports": {
-    ".": "./src/converter.js"
-  },
-  "bin": {
-    "oklchtohex": "./src/cli.js"
+    ".": "./src/index.js",
+    "./vite": "./src/vite-plugin.js",
+    "./converter": "./src/converter.js"
   },
   "files": [
     "src",
     "README.md"
   ],
-  "scripts": {
-    "check": "node ./src/cli.js --help"
-  },
   "keywords": [
     "oklch",
     "hex",
     "tailwind",
     "tailwindcss",
+    "vite",
+    "vite-plugin",
     "color",
     "converter"
   ],

package/src/index.js

@@ -0,0 +1,3 @@
+export * from "./converter.js";
+export { oklchToHexVitePlugin } from "./vite-plugin.js";
+

package/src/vite-plugin.js

@@ -0,0 +1,105 @@
+import { replaceOklchInText } from "./converter.js";
+
+const DEFAULT_CSS_FILE_REGEX =
+  /\.(css|pcss|postcss|scss|sass|less|styl|stylus)(?:$|\?)/i;
+
+function isRegexMatch(regex, value) {
+  if (!(regex instanceof RegExp)) {
+    return false;
+  }
+  regex.lastIndex = 0;
+  return regex.test(value);
+}
+
+function matches(matcher, value) {
+  if (!matcher) {
+    return true;
+  }
+  if (matcher instanceof RegExp) {
+    return isRegexMatch(matcher, value);
+  }
+  if (typeof matcher === "function") {
+    return Boolean(matcher(value));
+  }
+  return false;
+}
+
+function shouldProcessId(id, include, exclude) {
+  if (!matches(include, id)) {
+    return false;
+  }
+  if (exclude && matches(exclude, id)) {
+    return false;
+  }
+  return true;
+}
+
+function maybeConvertCss(code, convertOptions) {
+  if (typeof code !== "string") {
+    return null;
+  }
+  if (!code.toLowerCase().includes("oklch(")) {
+    return null;
+  }
+  const converted = replaceOklchInText(code, convertOptions);
+  return converted === code ? null : converted;
+}
+
+export function oklchToHexVitePlugin(options = {}) {
+  const {
+    include = DEFAULT_CSS_FILE_REGEX,
+    exclude,
+    convertDev = true,
+    convertBuild = true,
+    ...convertOptions
+  } = options;
+
+  let command = "build";
+
+  return {
+    name: "oklchtohex-vite-plugin",
+    enforce: "post",
+    configResolved(config) {
+      command = config.command;
+    },
+    transform(code, id) {
+      if (command === "serve" && !convertDev) {
+        return null;
+      }
+      if (command === "build" && !convertBuild) {
+        return null;
+      }
+      if (!shouldProcessId(id, include, exclude)) {
+        return null;
+      }
+
+      const converted = maybeConvertCss(code, convertOptions);
+      if (!converted) {
+        return null;
+      }
+      return { code: converted, map: null };
+    },
+    generateBundle(_, bundle) {
+      if (!convertBuild) {
+        return;
+      }
+      for (const [fileName, asset] of Object.entries(bundle)) {
+        if (asset.type !== "asset") {
+          continue;
+        }
+        if (!shouldProcessId(fileName, include, exclude)) {
+          continue;
+        }
+        if (typeof asset.source !== "string") {
+          continue;
+        }
+
+        const converted = maybeConvertCss(asset.source, convertOptions);
+        if (converted) {
+          asset.source = converted;
+        }
+      }
+    }
+  };
+}
+

package/src/cli.js

@@ -1,152 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { oklchToHex, replaceOklchInText } from "./converter.js";
-
-function printHelp() {
-  const help = `
-oklchtohex
-
-Convert OKLCH values to HEX, or rewrite an entire CSS file.
-
-Usage:
-  oklchtohex --value "oklch(70.4% 0.191 22.216)"
-  oklchtohex ./dist/app.css -o ./dist/app.hex.css
-  oklchtohex ./dist/app.css --stdout
-
-Options:
-  --value <oklch>        Convert a single OKLCH value to HEX
-  -o, --output <file>    Output file path for transformed CSS
-  --stdout               Print transformed CSS to stdout
-  --gamut <fit|clip>     Gamut strategy (default: clip)
-  --alpha <auto|always|never>
-                         Include alpha in HEX (default: auto)
-  --upper                Uppercase HEX output
-  -h, --help             Show this help text
-`;
-  process.stdout.write(help);
-}
-
-function parseArgs(argv) {
-  const parsed = {
-    input: undefined,
-    output: undefined,
-    value: undefined,
-    stdout: false,
-    gamut: "clip",
-    includeAlpha: "auto",
-    uppercase: false,
-    help: false
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-
-    if (arg === "-h" || arg === "--help") {
-      parsed.help = true;
-      continue;
-    }
-    if (arg === "--value") {
-      parsed.value = argv[i + 1];
-      i += 1;
-      continue;
-    }
-    if (arg === "-o" || arg === "--output") {
-      parsed.output = argv[i + 1];
-      i += 1;
-      continue;
-    }
-    if (arg === "--stdout") {
-      parsed.stdout = true;
-      continue;
-    }
-    if (arg === "--gamut") {
-      parsed.gamut = argv[i + 1];
-      i += 1;
-      continue;
-    }
-    if (arg === "--alpha") {
-      parsed.includeAlpha = argv[i + 1];
-      i += 1;
-      continue;
-    }
-    if (arg === "--upper") {
-      parsed.uppercase = true;
-      continue;
-    }
-    if (!arg.startsWith("-") && !parsed.input) {
-      parsed.input = arg;
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${arg}`);
-  }
-
-  return parsed;
-}
-
-function normalizeIncludeAlpha(value) {
-  if (!value || value === "auto") {
-    return "auto";
-  }
-  if (value === "always") {
-    return true;
-  }
-  if (value === "never") {
-    return false;
-  }
-  throw new Error(`Invalid --alpha value: ${value}`);
-}
-
-function normalizeGamut(value) {
-  if (value === "fit" || value === "clip") {
-    return value;
-  }
-  throw new Error(`Invalid --gamut value: ${value}`);
-}
-
-async function run() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    printHelp();
-    return;
-  }
-
-  const options = {
-    gamut: normalizeGamut(args.gamut),
-    includeAlpha: normalizeIncludeAlpha(args.includeAlpha),
-    uppercase: args.uppercase
-  };
-
-  if (args.value) {
-    const hex = oklchToHex(args.value, options);
-    process.stdout.write(`${hex}\n`);
-    return;
-  }
-
-  if (!args.input) {
-    throw new Error("Missing input. Provide --value or a CSS file path.");
-  }
-
-  const inputPath = path.resolve(process.cwd(), args.input);
-  const css = await fs.readFile(inputPath, "utf8");
-  const transformed = replaceOklchInText(css, options);
-
-  if (args.stdout || !args.output) {
-    process.stdout.write(transformed);
-    if (!transformed.endsWith("\n")) {
-      process.stdout.write("\n");
-    }
-    return;
-  }
-
-  const outputPath = path.resolve(process.cwd(), args.output);
-  await fs.writeFile(outputPath, transformed, "utf8");
-}
-
-run().catch((error) => {
-  process.stderr.write(`${error.message}\n`);
-  process.exit(1);
-});