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

package/README.md

@@ -71,8 +71,8 @@ const success = primary.extend({ hue: 157 });
 
 // Compose into a palette and export
 const palette = glaze.palette({ primary, danger, success });
-const tokens = palette.tokens({ prefix: true });
-// → { light: { 'primary-surface': 'okhsl(...)', ... }, dark: { 'primary-surface': 'okhsl(...)', ... } }
+const tokens = palette.tokens({ primary: 'primary' });
+// → { light: { 'primary-surface': 'okhsl(...)', 'surface': 'okhsl(...)', ... }, dark: { ... } }
 ```
 
 ## Core Concepts
@@ -618,7 +618,7 @@ Modes control how colors adapt across schemes:
 
 ### Lightness
 
-Root color lightness is mapped linearly within the configured `lightLightness` window:
+Absolute lightness values (both root colors and dependent colors with absolute lightness) are mapped linearly within the configured `lightLightness` window:
 
 ```ts
 const [lo, hi] = lightLightness; // default: [10, 100]
@@ -694,12 +694,12 @@ Combine multiple themes into a single palette:
 const palette = glaze.palette({ primary, danger, success, warning });
 ```
 
-### Token Export
+### Prefix Behavior
 
-Tokens are grouped by scheme variant, with plain color names as keys:
+Palette export methods (`tokens()`, `tasty()`, `css()`) default to `prefix: true` — all tokens are automatically prefixed with the theme name to avoid collisions:
 
 ```ts
-const tokens = palette.tokens({ prefix: true });
+const tokens = palette.tokens();
 // → {
 //   light: { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
 //   dark:  { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' },
@@ -712,15 +712,44 @@ Custom prefix mapping:
 palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
 ```
 
+To disable prefixing entirely, pass `prefix: false` explicitly. Note that tokens with the same name will overwrite each other (last theme wins).
+
+### Primary Theme
+
+Use the `primary` option to designate one theme as the primary. Its tokens are duplicated without prefix, providing convenient short aliases alongside the prefixed versions:
+
+```ts
+const palette = glaze.palette({ primary, danger, success });
+const tokens = palette.tokens({ primary: 'primary' });
+// → {
+//   light: {
+//     'primary-surface': 'okhsl(...)',  // prefixed (all themes)
+//     'danger-surface':  'okhsl(...)',
+//     'success-surface': 'okhsl(...)',
+//     'surface':         'okhsl(...)',  // unprefixed alias (primary only)
+//   },
+// }
+```
+
+The `primary` option works on `tokens()`, `tasty()`, and `css()`. It combines with any prefix mode — when using a custom prefix map, primary tokens are still duplicated without prefix:
+
+```ts
+palette.tokens({ prefix: { primary: 'p-', danger: 'd-' }, primary: 'primary' });
+// → 'p-surface' + 'surface' (alias) + 'd-surface'
+```
+
+An error is thrown if the primary name doesn't match any theme in the palette.
+
 ### Tasty Export (for [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style system)
 
 The `tasty()` method exports tokens in the [Tasty](https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs) style-to-state binding format — `#name` color token keys with state aliases (`''`, `@dark`, etc.):
 
 ```ts
-const tastyTokens = palette.tasty({ prefix: true });
+const tastyTokens = palette.tasty({ primary: 'primary' });
 // → {
 //   '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 //   '#danger-surface':  { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
+//   '#surface':         { '': 'okhsl(...)', '@dark': 'okhsl(...)' },  // alias
 // }
 ```
 
@@ -787,8 +816,10 @@ palette.tasty({ states: { dark: '@dark', highContrast: '@hc' } });
 
 ### JSON Export (Framework-Agnostic)
 
+JSON export groups by theme name (no prefix needed):
+
 ```ts
-const data = palette.json({ prefix: true });
+const data = palette.json();
 // → {
 //   primary: { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } },
 //   danger:  { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } },
@@ -810,7 +841,7 @@ const css = theme.css();
 Use in a stylesheet:
 
 ```ts
-const css = palette.css({ prefix: true });
+const css = palette.css({ primary: 'primary' });
 
 const stylesheet = `
 :root { ${css.light} }
@@ -826,7 +857,8 @@ Options:
 |---|---|---|
 | `format` | `'rgb'` | Color format (`'rgb'`, `'hsl'`, `'okhsl'`, `'oklch'`) |
 | `suffix` | `'-color'` | Suffix appended to each CSS property name |
-| `prefix` | — | (palette only) Same prefix behavior as `tokens()` |
+| `prefix` | `true` (palette) | (palette only) `true` uses `"<themeName>-"`, or provide a custom map |
+| `primary` | — | (palette only) Theme name to duplicate without prefix |
 
 ```ts
 // Custom suffix
@@ -837,9 +869,9 @@ theme.css({ suffix: '' });
 theme.css({ format: 'hsl' });
 // → "--surface-color: hsl(...);"
 
-// Palette with prefix
-palette.css({ prefix: true });
-// → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+// Palette with primary
+palette.css({ primary: 'primary' });
+// → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 ```
 
 ## Output Modes
@@ -1011,16 +1043,16 @@ const note    = primary.extend({ hue: 302 });
 
 const palette = glaze.palette({ primary, danger, success, warning, note });
 
-// Export as flat token map grouped by variant
-const tokens = palette.tokens({ prefix: true });
-// tokens.light → { 'primary-surface': 'okhsl(...)', 'primary-shadow-md': 'okhsl(... / 0.1)' }
+// Export as flat token map grouped by variant (prefix defaults to true)
+const tokens = palette.tokens({ primary: 'primary' });
+// tokens.light → { 'primary-surface': '...', 'surface': '...', 'danger-surface': '...' }
 
 // Export as tasty style-to-state bindings (for Tasty style system)
-const tastyTokens = palette.tasty({ prefix: true });
+const tastyTokens = palette.tasty({ primary: 'primary' });
 
 // Export as CSS custom properties (rgb format by default)
-const css = palette.css({ prefix: true });
-// css.light → "--primary-surface-color: rgb(...);\n--primary-shadow-md-color: rgb(... / 0.1);"
+const css = palette.css({ primary: 'primary' });
+// css.light → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 
 // Standalone shadow computation
 const v = glaze.shadow({ bg: '#f0eef5', fg: '#1a1a2e', intensity: 10 });

package/dist/index.cjs

@@ -81,8 +81,8 @@ const OKLab_to_linear_sRGB_coefficients = [
 		.73956515,
 		-.45954404,
 		.08285427,
-		.12541073,
-		-.14503204
+		.1254107,
+		.14503204
 	]],
 	[[.13110757611180954, 1.813339709266608], [
 		1.35733652,
@@ -254,10 +254,9 @@ const getCs = (L, a, b, cusp) => {
 	];
 };
 /**
-* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
-* Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
+* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
 */
-function okhslToLinearSrgb(h, s, l) {
+function okhslToOklab(h, s, l) {
 	const L = toeInv(l);
 	let a = 0;
 	let b = 0;
@@ -284,11 +283,18 @@ function okhslToLinearSrgb(h, s, l) {
 		a = c * a_;
 		b = c * b_;
 	}
-	return OKLabToLinearSRGB([
+	return [
 		L,
 		a,
 		b
-	]);
+	];
+}
+/**
+* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
+* Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
+*/
+function okhslToLinearSrgb(h, s, l) {
+	return OKLabToLinearSRGB(okhslToOklab(h, s, l));
 }
 /**
 * Compute relative luminance Y from linear sRGB channels.
@@ -327,40 +333,15 @@ function okhslToSrgb(h, s, l) {
 	];
 }
 /**
-* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+* Compute WCAG 2 relative luminance from linear sRGB, matching the browser
+* 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 okhslToOklab(h, s, l) {
-	const L = toeInv(l);
-	let a = 0;
-	let b = 0;
-	const hNorm = constrainAngle(h) / 360;
-	if (L !== 0 && L !== 1 && s !== 0) {
-		const a_ = Math.cos(TAU * hNorm);
-		const b_ = Math.sin(TAU * hNorm);
-		const [c0, cMid, cMax] = getCs(L, a_, b_, findCuspOKLCH(a_, b_));
-		const mid = .8;
-		const midInv = 1.25;
-		let t, k0, k1, k2;
-		if (s < mid) {
-			t = midInv * s;
-			k0 = 0;
-			k1 = mid * c0;
-			k2 = 1 - k1 / cMid;
-		} else {
-			t = 5 * (s - .8);
-			k0 = cMid;
-			k1 = .2 * cMid ** 2 * 1.25 ** 2 / c0;
-			k2 = 1 - k1 / (cMax - cMid);
-		}
-		const c = k0 + t * k1 / (1 - k2 * t);
-		a = c * a_;
-		b = c * b_;
-	}
-	return [
-		L,
-		a,
-		b
-	];
+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;
 }
 const linearSrgbToOklab = (rgb) => {
 	return transform(cbrt3(transform(rgb, linear_sRGB_to_LMS_M)), LMS_to_OKLab_M);
@@ -452,12 +433,13 @@ function formatOkhsl(h, s, l) {
 	return `okhsl(${fmt$1(h, 2)} ${fmt$1(s, 2)}% ${fmt$1(l, 2)}%)`;
 }
 /**
-* Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
+* Format OKHSL values as a CSS `rgb(R G B)` string.
+* Uses 2 decimal places to avoid 8-bit quantization contrast loss.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatRgb(h, s, l) {
 	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100);
-	return `rgb(${Math.round(r * 255)} ${Math.round(g * 255)} ${Math.round(b * 255)})`;
+	return `rgb(${parseFloat((r * 255).toFixed(2))} ${parseFloat((g * 255).toFixed(2))} ${parseFloat((b * 255).toFixed(2))})`;
 }
 /**
 * Format OKHSL values as a CSS `hsl(H S% L%)` string.
@@ -513,23 +495,12 @@ function resolveMinContrast(value) {
 const CACHE_SIZE = 512;
 const luminanceCache = /* @__PURE__ */ new Map();
 const cacheOrder = [];
-/**
-* Compute WCAG 2 relative luminance from linear sRGB, matching the browser
-* 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$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]))));
-	return .2126 * r + .7152 * g + .0722 * b;
-}
 function cachedLuminance(h, s, l) {
 	const lRounded = Math.round(l * 1e4) / 1e4;
 	const key = `${h}|${s}|${lRounded}`;
 	const cached = luminanceCache.get(key);
 	if (cached !== void 0) return cached;
-	const y = gamutClampedLuminance$1(okhslToLinearSrgb(h, s, lRounded));
+	const y = gamutClampedLuminance(okhslToLinearSrgb(h, s, lRounded));
 	if (luminanceCache.size >= CACHE_SIZE) {
 		const evict = cacheOrder.shift();
 		luminanceCache.delete(evict);
@@ -649,8 +620,8 @@ 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 + .01;
-	const yBase = gamutClampedLuminance$1(baseLinearRgb);
+	const searchTarget = target * 1.005;
+	const yBase = gamutClampedLuminance(baseLinearRgb);
 	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
 	if (crPref >= searchTarget) return {
 		lightness: preferredLightness,
@@ -773,8 +744,8 @@ function searchMixBranch(lo, hi, yBase, target, epsilon, maxIter, preferred, lum
 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 searchTarget = target * 1.005;
+	const yBase = gamutClampedLuminance(baseLinearRgb);
 	const crPref = contrastRatioFromLuminance(luminanceAtValue(preferredValue), yBase);
 	if (crPref >= searchTarget) return {
 		value: preferredValue,
@@ -1005,6 +976,11 @@ function mapSaturationDark(s, mode) {
 	if (mode === "static") return s;
 	return s * (1 - globalConfig.darkDesaturation);
 }
+function schemeLightnessRange(isDark, mode) {
+	if (mode === "static") return [0, 1];
+	const [lo, hi] = isDark ? globalConfig.darkLightness : globalConfig.lightLightness;
+	return [lo / 100, hi / 100];
+}
 function clamp(v, min, max) {
 	return Math.max(min, Math.min(max, v));
 }
@@ -1065,20 +1041,22 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 			if (isDark && mode === "auto") delta = -delta;
 			preferredL = clamp(baseL + delta, 0, 100);
 		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode);
-		else preferredL = clamp(parsed.value, 0, 100);
+		else preferredL = mapLightnessLight(parsed.value, mode);
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
 		const minCr = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
 		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
 		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
+		const lightnessRange = schemeLightnessRange(isDark, mode);
 		return {
 			l: findLightnessForContrast({
 				hue: effectiveHue,
 				saturation: effectiveSat,
-				preferredLightness: preferredL / 100,
+				preferredLightness: clamp(preferredL / 100, lightnessRange[0], lightnessRange[1]),
 				baseLinearRgb,
-				contrast: minCr
+				contrast: minCr,
+				lightnessRange
 			}).lightness * 100,
 			satFactor
 		};
@@ -1145,12 +1123,6 @@ function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
 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 —
@@ -1449,26 +1421,40 @@ function createTheme(hue, saturation, initialColors) {
 		}
 	};
 }
-function resolvePrefix(options, themeName) {
-	if (options?.prefix === true) return `${themeName}-`;
-	if (typeof options?.prefix === "object" && options.prefix !== null) return options.prefix[themeName] ?? `${themeName}-`;
+function resolvePrefix(options, themeName, defaultPrefix = false) {
+	const prefix = options?.prefix ?? defaultPrefix;
+	if (prefix === true) return `${themeName}-`;
+	if (typeof prefix === "object" && prefix !== null) return prefix[themeName] ?? `${themeName}-`;
 	return "";
 }
+function validatePrimaryTheme(primary, themes) {
+	if (primary !== void 0 && !(primary in themes)) {
+		const available = Object.keys(themes).join(", ");
+		throw new Error(`glaze: primary theme "${primary}" not found in palette. Available: ${available}.`);
+	}
+}
 function createPalette(themes) {
 	return {
 		tokens(options) {
+			validatePrimaryTheme(options?.primary, themes);
 			const modes = resolveModes(options?.modes);
 			const allTokens = {};
 			for (const [themeName, theme] of Object.entries(themes)) {
-				const tokens = buildFlatTokenMap(theme.resolve(), resolvePrefix(options, themeName), modes, options?.format);
+				const resolved = theme.resolve();
+				const tokens = buildFlatTokenMap(resolved, resolvePrefix(options, themeName, true), modes, options?.format);
 				for (const variant of Object.keys(tokens)) {
 					if (!allTokens[variant]) allTokens[variant] = {};
 					Object.assign(allTokens[variant], tokens[variant]);
 				}
+				if (themeName === options?.primary) {
+					const unprefixed = buildFlatTokenMap(resolved, "", modes, options?.format);
+					for (const variant of Object.keys(unprefixed)) Object.assign(allTokens[variant], unprefixed[variant]);
+				}
 			}
 			return allTokens;
 		},
 		tasty(options) {
+			validatePrimaryTheme(options?.primary, themes);
 			const states = {
 				dark: options?.states?.dark ?? globalConfig.states.dark,
 				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
@@ -1476,8 +1462,13 @@ function createPalette(themes) {
 			const modes = resolveModes(options?.modes);
 			const allTokens = {};
 			for (const [themeName, theme] of Object.entries(themes)) {
-				const tokens = buildTokenMap(theme.resolve(), resolvePrefix(options, themeName), states, modes, options?.format);
+				const resolved = theme.resolve();
+				const tokens = buildTokenMap(resolved, resolvePrefix(options, themeName, true), states, modes, options?.format);
 				Object.assign(allTokens, tokens);
+				if (themeName === options?.primary) {
+					const unprefixed = buildTokenMap(resolved, "", states, modes, options?.format);
+					Object.assign(allTokens, unprefixed);
+				}
 			}
 			return allTokens;
 		},
@@ -1488,6 +1479,7 @@ function createPalette(themes) {
 			return result;
 		},
 		css(options) {
+			validatePrimaryTheme(options?.primary, themes);
 			const suffix = options?.suffix ?? "-color";
 			const format = options?.format ?? "rgb";
 			const allLines = {
@@ -1497,13 +1489,23 @@ function createPalette(themes) {
 				darkContrast: []
 			};
 			for (const [themeName, theme] of Object.entries(themes)) {
-				const css = buildCssMap(theme.resolve(), resolvePrefix(options, themeName), suffix, format);
+				const resolved = theme.resolve();
+				const css = buildCssMap(resolved, resolvePrefix(options, themeName, true), suffix, format);
 				for (const key of [
 					"light",
 					"dark",
 					"lightContrast",
 					"darkContrast"
 				]) if (css[key]) allLines[key].push(css[key]);
+				if (themeName === options?.primary) {
+					const unprefixed = buildCssMap(resolved, "", suffix, format);
+					for (const key of [
+						"light",
+						"dark",
+						"lightContrast",
+						"darkContrast"
+					]) if (unprefixed[key]) allLines[key].push(unprefixed[key]);
+				}
 			}
 			return {
 				light: allLines.light.join("\n"),
@@ -1681,6 +1683,7 @@ exports.formatHsl = formatHsl;
 exports.formatOkhsl = formatOkhsl;
 exports.formatOklch = formatOklch;
 exports.formatRgb = formatRgb;
+exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
 exports.okhslToOklab = okhslToOklab;