oklchtohex 0.2.0 → 0.3.1

package/README.md

@@ -34,8 +34,41 @@ const convertedTailwindCss = convertTailwindCssToHex(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.
+- Tailwind opacity utilities like `border-red-500/30` are handled when emitted as `color-mix(... var(--color-*) ..., transparent)` and converted to 8-digit HEX when the source variable is resolvable.
 - `gamut` option supports `clip` (default) and `fit`.
 
+## Vite plugin (auto on dev + build)
+
+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
+    })
+  ]
+});
+```
+
+### 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`:

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "oklchtohex",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Convert OKLCH colors to HEX as a JavaScript package.",
   "type": "module",
-  "main": "./src/converter.js",
+  "main": "./src/index.js",
   "exports": {
-    ".": "./src/converter.js"
+    ".": "./src/index.js",
+    "./vite": "./src/vite-plugin.js",
+    "./converter": "./src/converter.js"
   },
   "files": [
     "src",
@@ -16,6 +18,8 @@
     "hex",
     "tailwind",
     "tailwindcss",
+    "vite",
+    "vite-plugin",
     "color",
     "converter"
   ],

package/src/converter.js

@@ -1,5 +1,7 @@
 import { getTailwindDefaultHexForVar } from "./tailwind-default-hex.js";
 const OKLCH_REGEX = /oklch\(([^)]*)\)/gi;
+const COLOR_MIX_WITH_TRANSPARENT_REGEX =
+  /color-mix\(\s*in\s+oklab\s*,\s*var\(\s*(--[\w-]+)\s*\)\s*([0-9.]+)%\s*,\s*transparent\s*\)/gi;
 
 function clamp(value, min, max) {
   return Math.min(max, Math.max(min, value));
@@ -157,6 +159,45 @@ function channelToHex(channel) {
   return byte.toString(16).padStart(2, "0");
 }
 
+function normalizeHexColor(hex) {
+  const trimmed = hex.trim().toLowerCase();
+  if (!trimmed.startsWith("#")) {
+    return null;
+  }
+  const raw = trimmed.slice(1);
+  if (raw.length === 3) {
+    return `#${raw[0]}${raw[0]}${raw[1]}${raw[1]}${raw[2]}${raw[2]}`;
+  }
+  if (raw.length === 4) {
+    return `#${raw[0]}${raw[0]}${raw[1]}${raw[1]}${raw[2]}${raw[2]}${raw[3]}${raw[3]}`;
+  }
+  if (raw.length === 6 || raw.length === 8) {
+    return `#${raw}`;
+  }
+  return null;
+}
+
+function splitHexChannels(hex) {
+  const normalized = normalizeHexColor(hex);
+  if (!normalized) {
+    return null;
+  }
+  const raw = normalized.slice(1);
+  const rgbHex = raw.slice(0, 6);
+  const alphaHex = raw.length === 8 ? raw.slice(6, 8) : "ff";
+  return { rgbHex, alphaHex };
+}
+
+function alphaToHex(alpha) {
+  return channelToHex(clamp(alpha, 0, 1));
+}
+
+function combineAlpha(existingAlphaHex, mixPercent) {
+  const baseAlpha = Number.parseInt(existingAlphaHex, 16) / 255;
+  const mixedAlpha = baseAlpha * clamp(mixPercent / 100, 0, 1);
+  return alphaToHex(mixedAlpha);
+}
+
 function normalizeInput(input) {
   if (typeof input === "string") {
     return parseOklch(input);
@@ -219,14 +260,63 @@ function replaceTailwindDefaultColorVariables(text) {
   );
 }
 
+function collectHexVariableDeclarations(text) {
+  const declarationRegex = /(--[\w-]+)\s*:\s*(#[0-9a-fA-F]{3,8})\s*;/g;
+  const map = new Map();
+  let match = declarationRegex.exec(text);
+  while (match) {
+    const variableName = match[1].toLowerCase();
+    const normalized = normalizeHexColor(match[2]);
+    if (normalized) {
+      map.set(variableName, normalized);
+    }
+    match = declarationRegex.exec(text);
+  }
+  return map;
+}
+
+function replaceTailwindColorMixWithHex(text, variableHexMap) {
+  return text.replace(
+    COLOR_MIX_WITH_TRANSPARENT_REGEX,
+    (fullMatch, variableNameRaw, percentRaw) => {
+      const variableName = String(variableNameRaw).toLowerCase();
+      const percent = Number.parseFloat(percentRaw);
+      if (Number.isNaN(percent)) {
+        return fullMatch;
+      }
+
+      const sourceHex =
+        variableHexMap.get(variableName) ??
+        getTailwindDefaultHexForVar(variableName);
+
+      if (!sourceHex) {
+        return fullMatch;
+      }
+
+      const channels = splitHexChannels(sourceHex);
+      if (!channels) {
+        return fullMatch;
+      }
+
+      const alphaHex = combineAlpha(channels.alphaHex, percent);
+      return `#${channels.rgbHex}${alphaHex}`;
+    }
+  );
+}
+
 export function replaceOklchInText(text, options = {}) {
   if (typeof text !== "string") {
     throw new Error("replaceOklchInText expects a string");
   }
   const { onError = "preserve", ...convertOptions } = options;
   const withMappedTailwindDefaults = replaceTailwindDefaultColorVariables(text);
+  const variableHexMap = collectHexVariableDeclarations(withMappedTailwindDefaults);
+  const withResolvedTailwindColorMix = replaceTailwindColorMixWithHex(
+    withMappedTailwindDefaults,
+    variableHexMap
+  );
 
-  return withMappedTailwindDefaults.replace(OKLCH_REGEX, (match) => {
+  return withResolvedTailwindColorMix.replace(OKLCH_REGEX, (match) => {
     try {
       return oklchToHex(match, convertOptions);
     } catch (error) {

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;
+        }
+      }
+    }
+  };
+}
+