@halogen-ui/tokens 0.1.0

package/src/color/oklch.ts

@@ -0,0 +1,306 @@
+/**
+ * Halogen — color engine.
+ *
+ * Self-contained OKLCH <-> sRGB conversion, sRGB gamut mapping, and WCAG 2.x
+ * contrast. No runtime dependency: this file is the single source of color
+ * truth for the token build, and it is unit-tested against known values.
+ *
+ * References:
+ *   Oklab       — Björn Ottosson, https://bottosson.github.io/posts/oklab/
+ *   sRGB        — IEC 61966-2-1
+ *   Contrast    — WCAG 2.2 SC 1.4.3 / 1.4.11 relative-luminance formula
+ */
+
+export interface Oklch {
+  /** Perceptual lightness, 0..1 */
+  l: number;
+  /** Chroma, 0..~0.37 in sRGB */
+  c: number;
+  /** Hue angle in degrees, 0..360 */
+  h: number;
+}
+
+export interface Rgb {
+  /** 0..1 */ r: number;
+  /** 0..1 */ g: number;
+  /** 0..1 */ b: number;
+}
+
+const clamp01 = (x: number): number => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+/* -------------------------------------------------------------------------- */
+/* sRGB transfer function                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** sRGB electro-optical transfer: gamma-encoded channel -> linear-light. */
+export function srgbToLinear(x: number): number {
+  return x <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
+}
+
+/** sRGB opto-electronic transfer: linear-light channel -> gamma-encoded. */
+export function linearToSrgb(x: number): number {
+  return x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Oklab <-> linear sRGB                                                       */
+/* -------------------------------------------------------------------------- */
+
+function linearRgbToOklab(r: number, g: number, b: number): [number, number, number] {
+  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);
+
+  return [
+    0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,
+  ];
+}
+
+function oklabToLinearRgb(L: number, a: number, b: number): [number, number, number] {
+  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_;
+
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+/* -------------------------------------------------------------------------- */
+/* OKLCH <-> sRGB                                                              */
+/* -------------------------------------------------------------------------- */
+
+const DEG = 180 / Math.PI;
+const RAD = Math.PI / 180;
+
+/** OKLCH -> unclamped linear-light sRGB. May fall outside 0..1 (out of gamut). */
+function oklchToLinearRgb({ l, c, h }: Oklch): [number, number, number] {
+  return oklabToLinearRgb(l, c * Math.cos(h * RAD), c * Math.sin(h * RAD));
+}
+
+/** True when the OKLCH triple is representable in sRGB (within `eps`). */
+export function inGamut(color: Oklch, eps = 1e-6): boolean {
+  const [r, g, b] = oklchToLinearRgb(color);
+  const lo = -eps;
+  const hi = 1 + eps;
+  return r >= lo && r <= hi && g >= lo && g <= hi && b >= lo && b <= hi;
+}
+
+/**
+ * Largest chroma representable in sRGB at this lightness and hue.
+ * Bisection to 1e-4 — well below a perceptible step.
+ */
+export function maxChroma(l: number, h: number): number {
+  if (l <= 0 || l >= 1) return 0;
+  let lo = 0;
+  let hi = 0.5;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    if (inGamut({ l, c: mid, h })) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Map an out-of-gamut OKLCH color into sRGB by reducing chroma while holding
+ * lightness and hue — the CSS Color 4 approach. In-gamut colors pass through.
+ */
+export function toGamut(color: Oklch): Oklch {
+  if (inGamut(color)) return color;
+  return { ...color, c: Math.min(color.c, maxChroma(color.l, color.h)) };
+}
+
+/** OKLCH -> sRGB in 0..1. Gamut-maps first, then clamps residual float error. */
+export function oklchToRgb(color: Oklch): Rgb {
+  const [r, g, b] = oklchToLinearRgb(toGamut(color));
+  return {
+    r: clamp01(linearToSrgb(r)),
+    g: clamp01(linearToSrgb(g)),
+    b: clamp01(linearToSrgb(b)),
+  };
+}
+
+/** sRGB in 0..1 -> OKLCH. Hue is normalized to 0..360; achromatic hue is 0. */
+export function rgbToOklch({ r, g, b }: Rgb): Oklch {
+  const [L, a, bb] = linearRgbToOklab(srgbToLinear(r), srgbToLinear(g), srgbToLinear(b));
+  const c = Math.sqrt(a * a + bb * bb);
+  let h = c < 1e-7 ? 0 : Math.atan2(bb, a) * DEG;
+  if (h < 0) h += 360;
+  return { l: L, c, h };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Hex                                                                         */
+/* -------------------------------------------------------------------------- */
+
+const hex2 = (x: number): string =>
+  Math.round(clamp01(x) * 255)
+    .toString(16)
+    .padStart(2, '0');
+
+export function rgbToHex({ r, g, b }: Rgb): string {
+  return `#${hex2(r)}${hex2(g)}${hex2(b)}`.toUpperCase();
+}
+
+export function hexToRgb(hex: string): Rgb {
+  const s = hex.replace('#', '').trim();
+  const full =
+    s.length === 3
+      ? s
+          .split('')
+          .map((ch) => ch + ch)
+          .join('')
+      : s;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+    throw new Error(`Not a 6-digit hex color: "${hex}"`);
+  }
+  return {
+    r: parseInt(full.slice(0, 2), 16) / 255,
+    g: parseInt(full.slice(2, 4), 16) / 255,
+    b: parseInt(full.slice(4, 6), 16) / 255,
+  };
+}
+
+export const oklchToHex = (c: Oklch): string => rgbToHex(oklchToRgb(c));
+export const hexToOklch = (h: string): Oklch => rgbToOklch(hexToRgb(h));
+
+/** CSS `oklch()` string, rounded for readable output. */
+export function formatOklch({ l, c, h }: Oklch): string {
+  const L = (l * 100).toFixed(2).replace(/\.?0+$/, '');
+  const C = c.toFixed(4).replace(/\.?0+$/, '');
+  const H = h.toFixed(2).replace(/\.?0+$/, '');
+  return `oklch(${L}% ${C || '0'} ${H || '0'})`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* WCAG contrast                                                               */
+/* -------------------------------------------------------------------------- */
+
+/** WCAG 2.x relative luminance of an sRGB color. */
+export function relativeLuminance({ r, g, b }: Rgb): number {
+  return (
+    0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b)
+  );
+}
+
+/** WCAG 2.x contrast ratio, 1..21. Order-independent. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export const contrastHex = (a: string, b: string): number =>
+  contrastRatio(hexToRgb(a), hexToRgb(b));
+
+/**
+ * Round an sRGB triple to the 8-bit grid.
+ *
+ * Tokens ship as 6-digit hex, so every contrast figure the system publishes or
+ * asserts must be measured on the *quantised* color. Measuring at full float
+ * precision silently overstates contrast by up to ~0.03:1 — enough to let a
+ * value that reads 4.50 in the solver ship as 4.48 in the browser.
+ */
+export const quantize = (c: Rgb): Rgb => hexToRgb(rgbToHex(c));
+
+/**
+ * Composite a translucent foreground over an opaque background (simple alpha
+ * compositing in gamma-encoded sRGB, which is what browsers do for `rgba()`).
+ * Needed because several Halogen tokens — scrims, hairline borders — are
+ * alpha values whose contrast must be measured against the *composited*
+ * result, not the nominal color.
+ */
+export function compositeOver(fg: Rgb, alpha: number, bg: Rgb): Rgb {
+  return {
+    r: fg.r * alpha + bg.r * (1 - alpha),
+    g: fg.g * alpha + bg.g * (1 - alpha),
+    b: fg.b * alpha + bg.b * (1 - alpha),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Contrast solving                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Find the *lightest* OKLCH lightness at the given hue that still reaches
+ * `target` contrast against `bg` — i.e. the most vivid accessible step.
+ * Chroma is held at `chromaFraction` of the in-gamut maximum for each candidate
+ * lightness, so the result stays as saturated as sRGB allows.
+ *
+ * Returns null when no lightness in [lo, hi] reaches the target, which is a
+ * real answer — some hues simply cannot carry text on some backgrounds.
+ */
+export function solveLightnessForContrast(opts: {
+  hue: number;
+  bg: Rgb;
+  target: number;
+  chromaFraction: number;
+  /** Search bounds. Defaults span the usable range. */
+  lo?: number;
+  hi?: number;
+  /** 'darker' walks down from hi (light bg); 'lighter' walks up from lo. */
+  direction: 'darker' | 'lighter';
+}): Oklch | null {
+  const { hue, bg, target, chromaFraction, direction } = opts;
+  const lo = opts.lo ?? 0.05;
+  const hi = opts.hi ?? 0.99;
+
+  const at = (l: number): Oklch => ({ l, c: maxChroma(l, hue) * chromaFraction, h: hue });
+  // Measured on the quantised color: the solver must optimize the value that
+  // actually ships as hex, not an idealised float that rounds the wrong way.
+  const ratioAt = (l: number): number => contrastRatio(quantize(oklchToRgb(at(l))), bg);
+
+  // Along the sRGB gamut boundary chroma varies with lightness, so contrast is
+  // not perfectly monotonic in L. Bisection converges on a passing value, and
+  // the invariant below re-checks it rather than trusting the search.
+  let a = direction === 'darker' ? lo : hi;
+  let b = direction === 'darker' ? hi : lo;
+
+  if (ratioAt(a) < target) return null; // even the extreme fails
+
+  for (let i = 0; i < 60; i++) {
+    const mid = (a + b) / 2;
+    if (ratioAt(mid) >= target) a = mid;
+    else b = mid;
+  }
+
+  // Guard the non-monotonic case: never hand back a value that misses the
+  // target. Step back toward the passing end until it genuinely clears.
+  let result = a;
+  for (let i = 0; i < 64 && ratioAt(result) < target; i++) {
+    result += direction === 'darker' ? -0.002 : 0.002;
+    if (result <= 0 || result >= 1) return null;
+  }
+  return ratioAt(result) >= target ? at(result) : null;
+}
+
+/** Perceptual distance in Oklab — a defensible "are these two colors confusable" metric. */
+export function deltaEOk(a: Oklch, b: Oklch): number {
+  const ax = a.c * Math.cos(a.h * RAD);
+  const ay = a.c * Math.sin(a.h * RAD);
+  const bx = b.c * Math.cos(b.h * RAD);
+  const by = b.c * Math.sin(b.h * RAD);
+  return Math.hypot(a.l - b.l, ax - bx, ay - by);
+}
+
+/** Smallest signed angular difference between two hues, in degrees (0..180). */
+export function hueDistance(h1: number, h2: number): number {
+  const d = Math.abs(((h1 - h2) % 360) + 360) % 360;
+  return d > 180 ? 360 - d : d;
+}