@stnd/lab 1.4.2 → 1.5.0

package/color.js

@@ -0,0 +1,365 @@
+/**
+ * @stnd/lab — OKLCH & CSS Color Utilities
+ *
+ * Perceptual OKLCH <-> sRGB math (Björn Ottosson) and DOM color resolution
+ * so the Design Lab color picker always reflects the true color of the page
+ * and edits natively in OKLCH or Hex.
+ */
+
+/**
+ * Clamp a number to [min, max].
+ * @param {number} v
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function clamp(v, min, max) {
+  return Math.max(min, Math.min(max, v));
+}
+
+/**
+ * Convert an sRGB channel (0..1) to linear-light value.
+ * @param {number} v
+ * @returns {number}
+ */
+export function srgbToLinear(v) {
+  v = Number(v) || 0;
+  if (v <= 0.04045) return v / 12.92;
+  return Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Convert a linear-light channel to sRGB (0..1).
+ * @param {number} v
+ * @returns {number}
+ */
+export function linearToSrgb(v) {
+  v = Number(v) || 0;
+  if (v <= 0.0031308) return v * 12.92;
+  return 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+}
+
+/**
+ * Convert sRGB (0..255) to OKLCH { L: 0..1, C: 0..0.4, h: 0..360 }.
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {{ L: number, C: number, h: number }}
+ */
+export function rgbToOklch(r, g, b) {
+  const R = srgbToLinear(clamp(r / 255, 0, 1));
+  const G = srgbToLinear(clamp(g / 255, 0, 1));
+  const B = srgbToLinear(clamp(b / 255, 0, 1));
+
+  const l_ = 0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B;
+  const m_ = 0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B;
+  const s_ = 0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B;
+
+  const l = Math.cbrt(l_);
+  const m = Math.cbrt(m_);
+  const s = Math.cbrt(s_);
+
+  let L = clamp(0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 0, 1);
+  if (Math.abs(L - 1) < 1e-5) L = 1;
+  if (L < 1e-5) L = 0;
+
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const b_ = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+
+  let C = Math.sqrt(a * a + b_ * b_);
+  if (C < 1e-4 || (r === g && g === b)) {
+    C = 0;
+  }
+  let h = C === 0 ? 0 : Math.atan2(b_, a) * (180 / Math.PI);
+  if (h < 0) h += 360;
+
+  return { L, C, h };
+}
+
+/**
+ * Convert OKLCH { L: 0..1, C: >=0, h: 0..360 } to sRGB { r, g, b, inGamut }.
+ * @param {number} L
+ * @param {number} C
+ * @param {number} h
+ * @returns {{ r: number, g: number, b: number, inGamut: boolean }}
+ */
+export function oklchToRgb(L, C, h) {
+  const rad = ((Number(h) || 0) * Math.PI) / 180;
+  const a = (Number(C) || 0) * Math.cos(rad);
+  const b = (Number(C) || 0) * Math.sin(rad);
+
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  const linR = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const linG = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const linB = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+
+  const eps = 0.001;
+  const inGamut =
+    linR >= -eps &&
+    linR <= 1 + eps &&
+    linG >= -eps &&
+    linG <= 1 + eps &&
+    linB >= -eps &&
+    linB <= 1 + eps;
+
+  const R = linearToSrgb(clamp(linR, 0, 1));
+  const G = linearToSrgb(clamp(linG, 0, 1));
+  const B = linearToSrgb(clamp(linB, 0, 1));
+
+  return {
+    r: clamp(Math.round(R * 255), 0, 255),
+    g: clamp(Math.round(G * 255), 0, 255),
+    b: clamp(Math.round(B * 255), 0, 255),
+    inGamut,
+  };
+}
+
+/**
+ * Format an RGB object as #rrggbb.
+ * @param {{ r: number, g: number, b: number }} rgb
+ * @returns {string}
+ */
+export function rgbToHex({ r, g, b }) {
+  const hr = clamp(Math.round(r), 0, 255).toString(16).padStart(2, "0");
+  const hg = clamp(Math.round(g), 0, 255).toString(16).padStart(2, "0");
+  const hb = clamp(Math.round(b), 0, 255).toString(16).padStart(2, "0");
+  return `#${hr}${hg}${hb}`;
+}
+
+/**
+ * Format OKLCH components into a clean CSS `oklch(L C H)` string.
+ * @param {number} L
+ * @param {number} C
+ * @param {number} h
+ * @returns {string}
+ */
+export function formatOklch(L, C, h) {
+  const lStr = Number(clamp(L, 0, 1).toFixed(4));
+  const cStr = Number(clamp(C, 0, 0.4).toFixed(4));
+  const hStr = Number((((h % 360) + 360) % 360).toFixed(1));
+  return `oklch(${lStr} ${cStr} ${hStr})`;
+}
+
+/**
+ * Parse a direct `#hex` string (`#rgb`, `#rrggbb`, `#rrggbbaa`) into `{ r, g, b }` or `null`.
+ * @param {string} str
+ * @returns {{ r: number, g: number, b: number } | null}
+ */
+export function parseHexString(str) {
+  if (!str || typeof str !== "string") return null;
+  let hex = str.trim();
+  if (!hex.startsWith("#")) return null;
+  hex = hex.slice(1);
+  if (hex.length === 3 || hex.length === 4) {
+    hex = hex
+      .slice(0, 3)
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  } else if (hex.length === 8) {
+    hex = hex.slice(0, 6);
+  }
+  if (!/^[0-9a-fA-F]{6}$/.test(hex)) return null;
+  const n = parseInt(hex, 16);
+  return {
+    r: (n >> 16) & 255,
+    g: (n >> 8) & 255,
+    b: n & 255,
+  };
+}
+
+/**
+ * Parse a literal `oklch(L C H)` string (where L, C, H are numbers/percentages, not `from ...`)
+ * into `{ L, C, h }` or `null`.
+ * @param {string} str
+ * @returns {{ L: number, C: number, h: number } | null}
+ */
+export function parseOklchString(str) {
+  if (!str || typeof str !== "string") return null;
+  const m = str
+    .trim()
+    .match(
+      /^oklch\(\s*([\d.]+)(%?)\s+([\d.]+)(%?)\s+([\d.]+|none)(?:deg|rad|turn)?(?:\s*\/\s*[\d.]+%?)?\s*\)$/i,
+    );
+  if (!m) return null;
+  let L = parseFloat(m[1]);
+  if (m[2] === "%") L /= 100;
+  let C = parseFloat(m[3]);
+  if (m[4] === "%") C = (C / 100) * 0.4;
+  let h = m[5].toLowerCase() === "none" ? 0 : parseFloat(m[5]);
+  if (Number.isNaN(L) || Number.isNaN(C) || Number.isNaN(h)) return null;
+  return {
+    L: clamp(L, 0, 1),
+    C: clamp(C, 0, 0.4),
+    h: Number((((h % 360) + 360) % 360).toFixed(4)),
+  };
+}
+
+/**
+ * Parse a literal `rgb(...)` or `rgba(...)` string into `{ r, g, b }` or `null`.
+ * @param {string} str
+ * @returns {{ r: number, g: number, b: number } | null}
+ */
+export function parseRgbString(str) {
+  if (!str || typeof str !== "string") return null;
+  const m = str
+    .trim()
+    .match(
+      /^rgba?\(\s*([\d.]+)\s*[,\s]\s*([\d.]+)\s*[,\s]\s*([\d.]+)(?:\s*[,/]\s*[\d.]+%?)?\s*\)$/i,
+    );
+  if (!m) return null;
+  return {
+    r: clamp(Math.round(parseFloat(m[1])), 0, 255),
+    g: clamp(Math.round(parseFloat(m[2])), 0, 255),
+    b: clamp(Math.round(parseFloat(m[3])), 0, 255),
+  };
+}
+
+/**
+ * Parse any CSS color string (including `oklch(...)`, `#hex`, `rgb(...)`, named colors,
+ * or relative `oklch(from ...)` in the DOM) into `{ L, C, h, hex, rgb, css }`.
+ *
+ * @param {string} css
+ * @param {HTMLElement} [contextEl]
+ * @returns {{ L: number, C: number, h: number, hex: string, rgb: { r: number, g: number, b: number }, css: string }}
+ */
+export function parseCssColor(css, contextEl) {
+  const raw = (css || "").trim();
+  if (!raw || raw.toLowerCase() === "black") {
+    return {
+      L: 0,
+      C: 0,
+      h: 0,
+      hex: "#000000",
+      rgb: { r: 0, g: 0, b: 0 },
+      css: raw || "#000000",
+    };
+  }
+  if (raw.toLowerCase() === "white") {
+    return {
+      L: 1,
+      C: 0,
+      h: 0,
+      hex: "#ffffff",
+      rgb: { r: 255, g: 255, b: 255 },
+      css: "#ffffff",
+    };
+  }
+
+  // 1. Direct oklch(L C H) string — preserves exact perceptual L, C, H
+  const directOklch = parseOklchString(raw);
+  if (directOklch) {
+    const rgb = oklchToRgb(directOklch.L, directOklch.C, directOklch.h);
+    const hex = rgbToHex(rgb);
+    return {
+      ...directOklch,
+      rgb,
+      hex,
+      css: formatOklch(directOklch.L, directOklch.C, directOklch.h),
+    };
+  }
+
+  // 2. Direct #hex string
+  const directHex = parseHexString(raw);
+  if (directHex) {
+    const oklch = rgbToOklch(directHex.r, directHex.g, directHex.b);
+    const hex = rgbToHex(directHex);
+    return {
+      ...oklch,
+      rgb: directHex,
+      hex,
+      css: hex,
+    };
+  }
+
+  // 3. Direct rgb(...) string
+  const directRgb = parseRgbString(raw);
+  if (directRgb) {
+    const oklch = rgbToOklch(directRgb.r, directRgb.g, directRgb.b);
+    const hex = rgbToHex(directRgb);
+    return {
+      ...oklch,
+      rgb: directRgb,
+      hex,
+      css: formatOklch(oklch.L, oklch.C, oklch.h),
+    };
+  }
+
+  // 4. Resolve via DOM & Canvas for relative colors (`oklch(from ...)`), `var(...)`, `light-dark(...)`, or named colors
+  if (typeof document !== "undefined" && document.body) {
+    try {
+      const parent = contextEl || document.body;
+      const probe = document.createElement("span");
+      probe.style.display = "none";
+      probe.style.color = raw;
+      parent.appendChild(probe);
+      const resolved = getComputedStyle(probe).color.trim();
+      probe.remove();
+
+      const resolvedOklch = parseOklchString(resolved);
+      if (resolvedOklch) {
+        const rgb = oklchToRgb(
+          resolvedOklch.L,
+          resolvedOklch.C,
+          resolvedOklch.h,
+        );
+        const hex = rgbToHex(rgb);
+        return {
+          ...resolvedOklch,
+          rgb,
+          hex,
+          css: formatOklch(resolvedOklch.L, resolvedOklch.C, resolvedOklch.h),
+        };
+      }
+
+      const resolvedRgb = parseRgbString(resolved);
+      if (resolvedRgb) {
+        const oklch = rgbToOklch(resolvedRgb.r, resolvedRgb.g, resolvedRgb.b);
+        const hex = rgbToHex(resolvedRgb);
+        return {
+          ...oklch,
+          rgb: resolvedRgb,
+          hex,
+          css: formatOklch(oklch.L, oklch.C, oklch.h),
+        };
+      }
+
+      // Fallback: 1x1 canvas pixel readback for color(srgb ...), oklab(...), etc.
+      const canvas = document.createElement("canvas");
+      canvas.width = 1;
+      canvas.height = 1;
+      const ctx = canvas.getContext("2d");
+      if (ctx && resolved) {
+        ctx.fillStyle = resolved;
+        ctx.fillRect(0, 0, 1, 1);
+        const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+        const oklch = rgbToOklch(r, g, b);
+        const hex = rgbToHex({ r, g, b });
+        return {
+          ...oklch,
+          rgb: { r, g, b },
+          hex,
+          css: formatOklch(oklch.L, oklch.C, oklch.h),
+        };
+      }
+    } catch {
+      /* noop */
+    }
+  }
+
+  return {
+    L: 0,
+    C: 0,
+    h: 0,
+    hex: "#000000",
+    rgb: { r: 0, g: 0, b: 0 },
+    css: "#000000",
+  };
+}

package/color.test.js

@@ -0,0 +1,82 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  clamp,
+  srgbToLinear,
+  linearToSrgb,
+  rgbToOklch,
+  oklchToRgb,
+  rgbToHex,
+  formatOklch,
+  parseHexString,
+  parseOklchString,
+  parseRgbString,
+  parseCssColor,
+} from "./color.js";
+
+test("clamp constraints", () => {
+  assert.equal(clamp(5, 0, 10), 5);
+  assert.equal(clamp(-2, 0, 10), 0);
+  assert.equal(clamp(15, 0, 10), 10);
+});
+
+test("linear and sRGB roundtrip", () => {
+  for (const v of [0, 0.25, 0.5, 0.75, 1]) {
+    const lin = srgbToLinear(v);
+    const srgb = linearToSrgb(lin);
+    assert.ok(Math.abs(srgb - v) < 1e-4, `Expected ${v}, got ${srgb}`);
+  }
+});
+
+test("rgbToOklch and oklchToRgb roundtrip", () => {
+  // Test white
+  const whiteOklch = rgbToOklch(255, 255, 255);
+  assert.ok(Math.abs(whiteOklch.L - 1) < 1e-3);
+  assert.ok(whiteOklch.C < 1e-3);
+
+  // Test black
+  const blackOklch = rgbToOklch(0, 0, 0);
+  assert.ok(Math.abs(blackOklch.L) < 1e-3);
+  assert.ok(blackOklch.C < 1e-3);
+
+  // Test hex roundtrip for a typical color (#262626)
+  const oklch = rgbToOklch(0x26, 0x26, 0x26);
+  const back = oklchToRgb(oklch.L, oklch.C, oklch.h);
+  assert.equal(rgbToHex(back), "#262626");
+});
+
+test("parseHexString", () => {
+  assert.deepEqual(parseHexString("#ffffff"), { r: 255, g: 255, b: 255 });
+  assert.deepEqual(parseHexString("#000"), { r: 0, g: 0, b: 0 });
+  assert.deepEqual(parseHexString("#262626"), { r: 38, g: 38, b: 38 });
+  assert.equal(parseHexString("invalid"), null);
+});
+
+test("parseOklchString", () => {
+  const parsed = parseOklchString("oklch(0.7721 0.0228 96.4)");
+  assert.ok(parsed);
+  assert.equal(parsed.L, 0.7721);
+  assert.equal(parsed.C, 0.0228);
+  assert.equal(parsed.h, 96.4);
+
+  const parsedPct = parseOklchString("oklch(75% 0.02 180deg)");
+  assert.ok(parsedPct);
+  assert.equal(parsedPct.L, 0.75);
+});
+
+test("parseCssColor", () => {
+  const oklchColor = parseCssColor("oklch(0.7721 0.0228 96.4)");
+  assert.ok(oklchColor);
+  assert.equal(oklchColor.L, 0.7721);
+  assert.equal(oklchColor.C, 0.0228);
+  assert.equal(oklchColor.h, 96.4);
+  assert.ok(oklchColor.hex.startsWith("#"));
+
+  const hexColor = parseCssColor("#ffffff");
+  assert.equal(hexColor.L, 1);
+  assert.equal(hexColor.hex, "#ffffff");
+
+  const blackColor = parseCssColor("#000000");
+  assert.equal(blackColor.L, 0);
+  assert.equal(blackColor.hex, "#000000");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stnd/lab",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "type": "module",
   "svelte": "./Lab.svelte",
   "author": "Francis Fontaine",
@@ -16,7 +16,7 @@
   "dependencies": {
     "bezier-easing": "^3.0.1",
     "svelte": "5.57.2",
-    "@stnd/ui": "0.15.0"
+    "@stnd/ui": "0.16.0"
   },
   "peerDependencies": {
     "astro": ">=5.0.0"
@@ -26,5 +26,8 @@
   },
   "devDependencies": {
     "wrangler": "^4.148.0"
+  },
+  "scripts": {
+    "test": "node --test"
   }
 }