@tenphi/glaze 0.0.0-snapshot.c84faa6 → 0.0.0-snapshot.e76f494

package/README.md

@@ -22,6 +22,7 @@ Glaze generates robust **light**, **dark**, and **high-contrast** color schemes
 
 - **OKHSL color space** — perceptually uniform hue and saturation
 - **WCAG 2 contrast solving** — automatic lightness adjustment to meet AA/AAA targets
+- **Mix colors** — blend two colors with OKHSL or sRGB interpolation, opaque or transparent, with optional contrast solving
 - **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
 - **Light + Dark + High-Contrast** — all schemes from one definition
 - **Per-color hue override** — absolute or relative hue shifts within a theme
@@ -413,6 +414,139 @@ const css = glaze.format(v, 'oklch');
 }
 ```
 
+## Mix Colors
+
+Mix colors blend two existing colors together. Use them for hover overlays, tints, shades, and any derived color that sits between two reference colors.
+
+### Opaque Mix
+
+Produces a solid color by interpolating between `base` and `target`:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // 30% of the way from surface toward accent
+  tint: { type: 'mix', base: 'surface', target: 'accent', value: 30 },
+});
+```
+
+- `value` — mix ratio 0–100 (0 = pure base, 100 = pure target)
+- The result is a fully opaque color (alpha = 1)
+- Adapts to light/dark/HC schemes automatically via the resolved base and target
+
+### Transparent Mix
+
+Produces the target color with a controlled opacity — useful for hover overlays:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  black:   { lightness: 0, saturation: 0 },
+
+  hover: {
+    type: 'mix',
+    base: 'surface',
+    target: 'black',
+    value: 8,
+    blend: 'transparent',
+  },
+});
+// hover → target color (black) with alpha = 0.08
+```
+
+The output color has `h`, `s`, `l` from the target and `alpha = value / 100`.
+
+### Blend Space
+
+By default, opaque mixing interpolates in OKHSL (perceptually uniform, consistent with Glaze's model). Use `space: 'srgb'` for linear sRGB interpolation, which matches browser compositing:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // sRGB blend — matches what the browser would render
+  hover: { type: 'mix', base: 'surface', target: 'accent', value: 20, space: 'srgb' },
+});
+```
+
+| Space | Behavior | Best for |
+|---|---|---|
+| `'okhsl'` (default) | Perceptually uniform OKHSL interpolation | Design token derivation |
+| `'srgb'` | Linear sRGB channel interpolation | Matching browser compositing |
+
+The `space` option only affects opaque blending. Transparent blending always composites in linear sRGB (matching browser alpha compositing).
+
+### Contrast Solving
+
+Mix colors support the same `contrast` prop as regular colors. The solver adjusts the mix ratio (opaque) or opacity (transparent) to meet the WCAG target:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  // Ensure the mixed color has at least AA contrast against surface
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 10,
+    contrast: 'AA',
+  },
+
+  // Ensure the transparent overlay has at least 3:1 contrast
+  overlay: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: 5,
+    blend: 'transparent',
+    contrast: 3,
+  },
+});
+```
+
+### High-Contrast Pairs
+
+Both `value` and `contrast` support `[normal, highContrast]` pairs:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  accent:  { lightness: 30 },
+
+  tint: {
+    type: 'mix',
+    base: 'surface',
+    target: 'accent',
+    value: [20, 40],          // stronger mix in high-contrast mode
+    contrast: [3, 'AAA'],     // stricter contrast in high-contrast mode
+  },
+});
+```
+
+### Achromatic Colors
+
+When mixing with achromatic colors (saturation near zero, e.g., white or black) in `okhsl` space, the hue comes from whichever color has saturation. This prevents meaningless hue artifacts and matches CSS `color-mix()` "missing component" behavior. For purely achromatic mixes, prefer `space: 'srgb'` where hue is irrelevant.
+
+### Mix Chaining
+
+Mix colors can reference other mix colors, enabling multi-step derivations:
+
+```ts
+theme.colors({
+  white: { lightness: 100, saturation: 0 },
+  black: { lightness: 0, saturation: 0 },
+  gray:  { type: 'mix', base: 'white', target: 'black', value: 50, space: 'srgb' },
+  lightGray: { type: 'mix', base: 'white', target: 'gray', value: 50, space: 'srgb' },
+});
+```
+
+Mix colors cannot reference shadow colors (same restriction as regular dependent colors).
+
 ## Output Formats
 
 Control the color format in exports with the `format` option:
@@ -758,10 +892,10 @@ glaze.configure({
 
 ## Color Definition Shape
 
-`ColorDef` is a discriminated union of regular colors and shadow colors:
+`ColorDef` is a discriminated union of regular colors, shadow colors, and mix colors:
 
 ```ts
-type ColorDef = RegularColorDef | ShadowColorDef;
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 
 interface RegularColorDef {
   lightness?: HCPair<number | RelativeValue>;
@@ -780,9 +914,19 @@ interface ShadowColorDef {
   intensity: HCPair<number>; // 0–100
   tuning?: ShadowTuning;
 }
+
+interface MixColorDef {
+  type: 'mix';
+  base: string;     // "from" color name
+  target: string;   // "to" color name
+  value: HCPair<number>;     // 0–100 (mix ratio or opacity)
+  blend?: 'opaque' | 'transparent'; // default: 'opaque'
+  space?: 'okhsl' | 'srgb';        // default: 'okhsl'
+  contrast?: HCPair<MinContrast>;
+}
 ```
 
-A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`. Shadow colors use `type: 'shadow'` and must reference a non-shadow `bg` color.
+A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`. Shadow colors use `type: 'shadow'` and must reference a non-shadow `bg` color. Mix colors use `type: 'mix'` and must reference two non-shadow colors.
 
 ## Validation
 
@@ -801,6 +945,12 @@ A root color must have absolute `lightness` (a number). A dependent color must h
 | Regular color `base` references a shadow color | Validation error |
 | Shadow `intensity` outside 0–100 | Clamp silently |
 | `contrast` + `opacity` combined | Warning |
+| Mix `base` references non-existent color | Validation error |
+| Mix `target` references non-existent color | Validation error |
+| Mix `base` references a shadow color | Validation error |
+| Mix `target` references a shadow color | Validation error |
+| Mix `value` outside 0–100 | Clamp silently |
+| Circular references involving mix colors | Validation error |
 
 ## Advanced: Color Math Utilities
 
@@ -846,6 +996,10 @@ primary.colors({
   'shadow-md':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 },
   'shadow-lg':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 },
 
+  // Mix colors — hover overlays and tints
+  'hover':       { type: 'mix', base: 'surface', target: 'accent-fill', value: 8, blend: 'transparent' },
+  'tint':        { type: 'mix', base: 'surface', target: 'accent-fill', value: 20 },
+
   // Fixed-alpha overlay
   overlay:       { lightness: 0, opacity: 0.5 },
 });

package/dist/index.cjs

@@ -518,7 +518,7 @@ const cacheOrder = [];
 * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
 * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
 */
-function gamutClampedLuminance(linearRgb) {
+function gamutClampedLuminance$1(linearRgb) {
 	const r = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0]))));
 	const g = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1]))));
 	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
@@ -529,7 +529,7 @@ function cachedLuminance(h, s, l) {
 	const key = `${h}|${s}|${lRounded}`;
 	const cached = luminanceCache.get(key);
 	if (cached !== void 0) return cached;
-	const y = gamutClampedLuminance(okhslToLinearSrgb(h, s, lRounded));
+	const y = gamutClampedLuminance$1(okhslToLinearSrgb(h, s, lRounded));
 	if (luminanceCache.size >= CACHE_SIZE) {
 		const evict = cacheOrder.shift();
 		luminanceCache.delete(evict);
@@ -649,10 +649,10 @@ function coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter) {
 function findLightnessForContrast(options) {
 	const { hue, saturation, preferredLightness, baseLinearRgb, contrast: contrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
 	const target = resolveMinContrast(contrastInput);
-	const searchTarget = target + .1;
-	const yBase = gamutClampedLuminance(baseLinearRgb);
+	const searchTarget = target + .01;
+	const yBase = gamutClampedLuminance$1(baseLinearRgb);
 	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
-	if (crPref >= target) return {
+	if (crPref >= searchTarget) return {
 		lightness: preferredLightness,
 		contrast: crPref,
 		met: true,
@@ -701,6 +701,135 @@ function findLightnessForContrast(options) {
 	candidates.sort((a, b) => b.contrast - a.contrast);
 	return candidates[0];
 }
+/**
+* Binary-search one branch [lo, hi] for the nearest passing mix value
+* to `preferred`.
+*/
+function searchMixBranch(lo, hi, yBase, target, epsilon, maxIter, preferred, luminanceAt) {
+	const crLo = contrastRatioFromLuminance(luminanceAt(lo), yBase);
+	const crHi = contrastRatioFromLuminance(luminanceAt(hi), yBase);
+	if (crLo < target && crHi < target) {
+		if (crLo >= crHi) return {
+			lightness: lo,
+			contrast: crLo,
+			met: false
+		};
+		return {
+			lightness: hi,
+			contrast: crHi,
+			met: false
+		};
+	}
+	let low = lo;
+	let high = hi;
+	for (let i = 0; i < maxIter; i++) {
+		if (high - low < epsilon) break;
+		const mid = (low + high) / 2;
+		if (contrastRatioFromLuminance(luminanceAt(mid), yBase) >= target) if (mid < preferred) low = mid;
+		else high = mid;
+		else if (mid < preferred) high = mid;
+		else low = mid;
+	}
+	const crLow = contrastRatioFromLuminance(luminanceAt(low), yBase);
+	const crHigh = contrastRatioFromLuminance(luminanceAt(high), yBase);
+	const lowPasses = crLow >= target;
+	const highPasses = crHigh >= target;
+	if (lowPasses && highPasses) {
+		if (Math.abs(low - preferred) <= Math.abs(high - preferred)) return {
+			lightness: low,
+			contrast: crLow,
+			met: true
+		};
+		return {
+			lightness: high,
+			contrast: crHigh,
+			met: true
+		};
+	}
+	if (lowPasses) return {
+		lightness: low,
+		contrast: crLow,
+		met: true
+	};
+	if (highPasses) return {
+		lightness: high,
+		contrast: crHigh,
+		met: true
+	};
+	return crLow >= crHigh ? {
+		lightness: low,
+		contrast: crLow,
+		met: false
+	} : {
+		lightness: high,
+		contrast: crHigh,
+		met: false
+	};
+}
+/**
+* Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
+* target against a base color, staying as close to `preferredValue` as possible.
+*/
+function findValueForMixContrast(options) {
+	const { preferredValue, baseLinearRgb, contrast: contrastInput, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
+	const target = resolveMinContrast(contrastInput);
+	const searchTarget = target + .01;
+	const yBase = gamutClampedLuminance$1(baseLinearRgb);
+	const crPref = contrastRatioFromLuminance(luminanceAtValue(preferredValue), yBase);
+	if (crPref >= searchTarget) return {
+		value: preferredValue,
+		contrast: crPref,
+		met: true
+	};
+	const darkerResult = preferredValue > 0 ? searchMixBranch(0, preferredValue, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
+	const lighterResult = preferredValue < 1 ? searchMixBranch(preferredValue, 1, yBase, searchTarget, epsilon, maxIterations, preferredValue, luminanceAtValue) : null;
+	if (darkerResult) darkerResult.met = darkerResult.contrast >= target;
+	if (lighterResult) lighterResult.met = lighterResult.contrast >= target;
+	const darkerPasses = darkerResult?.met ?? false;
+	const lighterPasses = lighterResult?.met ?? false;
+	if (darkerPasses && lighterPasses) {
+		if (Math.abs(darkerResult.lightness - preferredValue) <= Math.abs(lighterResult.lightness - preferredValue)) return {
+			value: darkerResult.lightness,
+			contrast: darkerResult.contrast,
+			met: true
+		};
+		return {
+			value: lighterResult.lightness,
+			contrast: lighterResult.contrast,
+			met: true
+		};
+	}
+	if (darkerPasses) return {
+		value: darkerResult.lightness,
+		contrast: darkerResult.contrast,
+		met: true
+	};
+	if (lighterPasses) return {
+		value: lighterResult.lightness,
+		contrast: lighterResult.contrast,
+		met: true
+	};
+	const candidates = [];
+	if (darkerResult) candidates.push({
+		...darkerResult,
+		branch: "lower"
+	});
+	if (lighterResult) candidates.push({
+		...lighterResult,
+		branch: "upper"
+	});
+	if (candidates.length === 0) return {
+		value: preferredValue,
+		contrast: crPref,
+		met: false
+	};
+	candidates.sort((a, b) => b.contrast - a.contrast);
+	return {
+		value: candidates[0].lightness,
+		contrast: candidates[0].contrast,
+		met: candidates[0].met
+	};
+}
 
 //#endregion
 //#region src/glaze.ts
@@ -732,6 +861,9 @@ function pairHC(p) {
 function isShadowDef(def) {
 	return def.type === "shadow";
 }
+function isMixDef(def) {
+	return def.type === "mix";
+}
 const DEFAULT_SHADOW_TUNING = {
 	saturationFactor: .18,
 	maxSaturation: .25,
@@ -799,6 +931,13 @@ function validateColorDefs(defs) {
 			}
 			continue;
 		}
+		if (isMixDef(def)) {
+			if (!names.has(def.base)) throw new Error(`glaze: mix "${name}" references non-existent base "${def.base}".`);
+			if (!names.has(def.target)) throw new Error(`glaze: mix "${name}" references non-existent target "${def.target}".`);
+			if (isShadowDef(defs[def.base])) throw new Error(`glaze: mix "${name}" base "${def.base}" references a shadow color.`);
+			if (isShadowDef(defs[def.target])) throw new Error(`glaze: mix "${name}" target "${def.target}" references a shadow color.`);
+			continue;
+		}
 		const regDef = def;
 		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
 		if (regDef.lightness !== void 0 && !isAbsoluteLightness(regDef.lightness) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
@@ -817,6 +956,9 @@ function validateColorDefs(defs) {
 		if (isShadowDef(def)) {
 			dfs(def.bg);
 			if (def.fg) dfs(def.fg);
+		} else if (isMixDef(def)) {
+			dfs(def.base);
+			dfs(def.target);
 		} else {
 			const regDef = def;
 			if (regDef.base) dfs(regDef.base);
@@ -836,6 +978,9 @@ function topoSort(defs) {
 		if (isShadowDef(def)) {
 			visit(def.bg);
 			if (def.fg) visit(def.fg);
+		} else if (isMixDef(def)) {
+			visit(def.base);
+			visit(def.target);
 		} else {
 			const regDef = def;
 			if (regDef.base) visit(regDef.base);
@@ -951,6 +1096,7 @@ function getSchemeVariant(color, isDark, isHighContrast) {
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
+	if (isMixDef(def)) return resolveMixForScheme(def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
 	const isRoot = isAbsoluteLightness(regDef.lightness) && !regDef.base;
@@ -996,6 +1142,89 @@ function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
 	const tuning = resolveShadowTuning(def.tuning);
 	return computeShadow(bgVariant, fgVariant, intensity, tuning);
 }
+function variantToLinearRgb(v) {
+	return okhslToLinearSrgb(v.h, v.s, v.l);
+}
+function gamutClampedLuminance(linearRgb) {
+	const r = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[0]))));
+	const g = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[1]))));
+	const b = sRGBGammaToLinear(Math.max(0, Math.min(1, sRGBLinearToGamma(linearRgb[2]))));
+	return .2126 * r + .7152 * g + .0722 * b;
+}
+/**
+* Resolve hue for OKHSL mixing, handling achromatic colors.
+* When one color has no saturation, its hue is meaningless —
+* use the hue from the color that has saturation (matches CSS
+* color-mix "missing component" behavior).
+*/
+function mixHue(base, target, t) {
+	const SAT_EPSILON = 1e-6;
+	const baseHasSat = base.s > SAT_EPSILON;
+	const targetHasSat = target.s > SAT_EPSILON;
+	if (baseHasSat && targetHasSat) return circularLerp(base.h, target.h, t);
+	if (targetHasSat) return target.h;
+	return base.h;
+}
+function linearSrgbLerp(base, target, t) {
+	return [
+		base[0] + (target[0] - base[0]) * t,
+		base[1] + (target[1] - base[1]) * t,
+		base[2] + (target[2] - base[2]) * t
+	];
+}
+function linearRgbToVariant(rgb) {
+	const [h, s, l] = srgbToOkhsl([
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[0]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[1]))),
+		Math.max(0, Math.min(1, sRGBLinearToGamma(rgb[2])))
+	]);
+	return {
+		h,
+		s,
+		l,
+		alpha: 1
+	};
+}
+function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
+	const baseResolved = ctx.resolved.get(def.base);
+	const targetResolved = ctx.resolved.get(def.target);
+	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
+	const targetVariant = getSchemeVariant(targetResolved, isDark, isHighContrast);
+	let t = clamp(isHighContrast ? pairHC(def.value) : pairNormal(def.value), 0, 100) / 100;
+	const blend = def.blend ?? "opaque";
+	const space = def.space ?? "okhsl";
+	const baseLinear = variantToLinearRgb(baseVariant);
+	const targetLinear = variantToLinearRgb(targetVariant);
+	if (def.contrast !== void 0) {
+		const minCr = isHighContrast ? pairHC(def.contrast) : pairNormal(def.contrast);
+		let luminanceAt;
+		if (blend === "transparent") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
+		else if (space === "srgb") luminanceAt = (v) => gamutClampedLuminance(linearSrgbLerp(baseLinear, targetLinear, v));
+		else luminanceAt = (v) => {
+			return gamutClampedLuminance(okhslToLinearSrgb(mixHue(baseVariant, targetVariant, v), baseVariant.s + (targetVariant.s - baseVariant.s) * v, baseVariant.l + (targetVariant.l - baseVariant.l) * v));
+		};
+		t = findValueForMixContrast({
+			preferredValue: t,
+			baseLinearRgb: baseLinear,
+			targetLinearRgb: targetLinear,
+			contrast: minCr,
+			luminanceAtValue: luminanceAt
+		}).value;
+	}
+	if (blend === "transparent") return {
+		h: targetVariant.h,
+		s: targetVariant.s,
+		l: targetVariant.l,
+		alpha: clamp(t, 0, 1)
+	};
+	if (space === "srgb") return linearRgbToVariant(linearSrgbLerp(baseLinear, targetLinear, t));
+	return {
+		h: mixHue(baseVariant, targetVariant, t),
+		s: clamp(baseVariant.s + (targetVariant.s - baseVariant.s) * t, 0, 1),
+		l: clamp(baseVariant.l + (targetVariant.l - baseVariant.l) * t, 0, 1),
+		alpha: 1
+	};
+}
 function resolveAllColors(hue, saturation, defs) {
 	validateColorDefs(defs);
 	const order = topoSort(defs);
@@ -1006,7 +1235,8 @@ function resolveAllColors(hue, saturation, defs) {
 		resolved: /* @__PURE__ */ new Map()
 	};
 	function defMode(def) {
-		return isShadowDef(def) ? void 0 : def.mode ?? "auto";
+		if (isShadowDef(def) || isMixDef(def)) return void 0;
+		return def.mode ?? "auto";
 	}
 	const lightMap = /* @__PURE__ */ new Map();
 	for (const name of order) {
@@ -1446,6 +1676,7 @@ glaze.resetConfig = function resetConfig() {
 //#endregion
 exports.contrastRatioFromLuminance = contrastRatioFromLuminance;
 exports.findLightnessForContrast = findLightnessForContrast;
+exports.findValueForMixContrast = findValueForMixContrast;
 exports.formatHsl = formatHsl;
 exports.formatOkhsl = formatOkhsl;
 exports.formatOklch = formatOklch;