@tenphi/glaze 0.8.0 → 0.9.1

package/README.md

@@ -70,8 +70,8 @@ const danger  = primary.extend({ hue: 23 });
 const success = primary.extend({ hue: 157 });
 
 // Compose into a palette and export
-const palette = glaze.palette({ primary, danger, success });
-const tokens = palette.tokens({ primary: 'primary' });
+const palette = glaze.palette({ primary, danger, success }, { primary: 'primary' });
+const tokens = palette.tokens();
 // → { light: { 'primary-surface': 'okhsl(...)', 'surface': 'okhsl(...)', ... }, dark: { ... } }
 ```
 
@@ -647,7 +647,7 @@ const t = (100 - lightness) / 100;
 const invertedL = lo + (hi - lo) * t / (t + darkCurve * (1 - t)); // darkCurve default: 0.5
 ```
 
-The `darkCurve` parameter (default `0.5`, range 0–1) controls how much the dark-mode inversion expands lightness deltas. Lower values produce stronger expansion; `1` gives linear (legacy) behavior. Unlike a power curve, the Möbius transformation provides **proportional expansion** — small and large deltas are scaled by similar ratios, preserving the visual hierarchy of the light theme.
+The `darkCurve` parameter (default `0.5`, range 0–1) controls how much the dark-mode inversion expands lightness deltas. Lower values produce stronger expansion; `1` gives linear (legacy) behavior. Accepts a `[normal, highContrast]` pair for separate HC tuning (e.g. `darkCurve: [0.5, 0.3]`); a single number applies to both. Unlike a power curve, the Möbius transformation provides **proportional expansion** — small and large deltas are scaled by similar ratios, preserving the visual hierarchy of the light theme.
 
 **`fixed`** — mapped without inversion (not affected by `darkCurve`):
 
@@ -661,7 +661,7 @@ const mappedL = (lightness * (hi - lo)) / 100 + lo;
 | accent-fill (L=52) | 52 | 66.9 | 53.4 | 56.6 |
 | accent-text (L=100) | 100 | 15 | 15 | 95 |
 
-In high-contrast variants, the `darkLightness` window is bypassed. Auto uses the same Möbius curve over the full [0, 100] range. Fixed uses identity (`L`). This allows HC colors to reach the full 0–100 range.
+In high-contrast variants, the `darkLightness` window is bypassed — auto uses the Möbius curve over the full [0, 100] range, and fixed uses identity (`L`). To use a different curve shape for HC, pass a `[normal, hc]` pair to `darkCurve` (e.g. `darkCurve: [0.5, 0.3]`).
 
 ### Saturation
 
@@ -701,6 +701,15 @@ Combine multiple themes into a single palette:
 const palette = glaze.palette({ primary, danger, success, warning });
 ```
 
+Optionally designate a primary theme at creation time:
+
+```ts
+const palette = glaze.palette(
+  { primary, danger, success, warning },
+  { primary: 'primary' },
+);
+```
+
 ### Prefix Behavior
 
 Palette export methods (`tokens()`, `tasty()`, `css()`) default to `prefix: true` — all tokens are automatically prefixed with the theme name to avoid collisions:
@@ -719,15 +728,28 @@ 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).
+To disable prefixing entirely, pass `prefix: false` explicitly.
+
+### Collision Detection
+
+When two themes produce the same output key (via `prefix: false`, custom prefix maps, or primary unprefixed aliases), the first-written value wins and a `console.warn` is emitted:
+
+```ts
+const palette = glaze.palette({ a, b });
+palette.tokens({ prefix: false });
+// ⚠ glaze: token "surface" from theme "b" collides with theme "a" — skipping.
+```
 
 ### 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:
+The primary theme's tokens are duplicated without prefix, providing convenient short aliases alongside the prefixed versions. Set at palette creation to apply to all exports automatically:
 
 ```ts
-const palette = glaze.palette({ primary, danger, success });
-const tokens = palette.tokens({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tokens = palette.tokens();
 // → {
 //   light: {
 //     'primary-surface': 'okhsl(...)',  // prefixed (all themes)
@@ -738,11 +760,18 @@ const tokens = palette.tokens({ primary: 'primary' });
 // }
 ```
 
+Override or disable per-export:
+
+```ts
+palette.tokens({ primary: 'danger' });  // use danger as primary for this call
+palette.tokens({ primary: false });     // no primary for this call
+```
+
 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'
+palette.tokens({ prefix: { primary: 'p-', danger: 'd-' } });
+// → 'p-surface' + 'surface' (alias from palette-level primary) + 'd-surface'
 ```
 
 An error is thrown if the primary name doesn't match any theme in the palette.
@@ -752,7 +781,11 @@ An error is thrown if the primary name doesn't match any theme in the palette.
 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({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const tastyTokens = palette.tasty();
 // → {
 //   '#primary-surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
 //   '#danger-surface':  { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
@@ -848,7 +881,11 @@ const css = theme.css();
 Use in a stylesheet:
 
 ```ts
-const css = palette.css({ primary: 'primary' });
+const palette = glaze.palette(
+  { primary, danger, success },
+  { primary: 'primary' },
+);
+const css = palette.css();
 
 const stylesheet = `
 :root { ${css.light} }
@@ -865,7 +902,7 @@ Options:
 | `format` | `'rgb'` | Color format (`'rgb'`, `'hsl'`, `'okhsl'`, `'oklch'`) |
 | `suffix` | `'-color'` | Suffix appended to each CSS property name |
 | `prefix` | `true` (palette) | (palette only) `true` uses `"<themeName>-"`, or provide a custom map |
-| `primary` | — | (palette only) Theme name to duplicate without prefix |
+| `primary` | inherited | (palette only) Override or disable (`false`) the palette-level primary for this call |
 
 ```ts
 // Custom suffix
@@ -876,8 +913,8 @@ theme.css({ suffix: '' });
 theme.css({ format: 'hsl' });
 // → "--surface-color: hsl(...);"
 
-// Palette with primary
-palette.css({ primary: 'primary' });
+// Palette with primary (inherited from palette creation)
+palette.css();
 // → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 ```
 
@@ -914,7 +951,7 @@ glaze.configure({
   lightLightness: [10, 100],   // Light scheme lightness window [lo, hi] (bypassed in HC)
   darkLightness: [15, 95],     // Dark scheme lightness window [lo, hi] (bypassed in HC)
   darkDesaturation: 0.1,       // Saturation reduction in dark scheme (0–1)
-  darkCurve: 0.5,              // Möbius beta for dark auto-inversion (0–1, lower = more expansion)
+  darkCurve: 0.5,              // Möbius beta for dark auto-inversion (0–1); or [normal, hc] pair
   states: {
     dark: '@dark',             // State alias for dark mode tokens
     highContrast: '@high-contrast',
@@ -1049,17 +1086,20 @@ const success = primary.extend({ hue: 157 });
 const warning = primary.extend({ hue: 84 });
 const note    = primary.extend({ hue: 302 });
 
-const palette = glaze.palette({ primary, danger, success, warning, note });
+const palette = glaze.palette(
+  { primary, danger, success, warning, note },
+  { primary: 'primary' },
+);
 
 // Export as flat token map grouped by variant (prefix defaults to true)
-const tokens = palette.tokens({ primary: 'primary' });
+const tokens = palette.tokens();
 // tokens.light → { 'primary-surface': '...', 'surface': '...', 'danger-surface': '...' }
 
 // Export as tasty style-to-state bindings (for Tasty style system)
-const tastyTokens = palette.tasty({ primary: 'primary' });
+const tastyTokens = palette.tasty();
 
 // Export as CSS custom properties (rgb format by default)
-const css = palette.css({ primary: 'primary' });
+const css = palette.css();
 // css.light → "--primary-surface-color: rgb(...);\n--surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
 
 // Standalone shadow computation
@@ -1115,7 +1155,7 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | Method | Description |
 |---|---|
 | `glaze.configure(config)` | Set global configuration |
-| `glaze.palette(themes)` | Compose themes into a palette |
+| `glaze.palette(themes, options?)` | Compose themes into a palette (options: `{ primary? }`) |
 | `glaze.getConfig()` | Get current global config |
 | `glaze.resetConfig()` | Reset to defaults |
 

package/dist/index.cjs

@@ -962,9 +962,13 @@ function topoSort(defs) {
 	for (const name of Object.keys(defs)) visit(name);
 	return result;
 }
+function lightnessWindow(isHighContrast, kind) {
+	if (isHighContrast) return [0, 100];
+	return kind === "dark" ? globalConfig.darkLightness : globalConfig.lightLightness;
+}
 function mapLightnessLight(l, mode, isHighContrast) {
-	if (mode === "static" || isHighContrast) return l;
-	const [lo, hi] = globalConfig.lightLightness;
+	if (mode === "static") return l;
+	const [lo, hi] = lightnessWindow(isHighContrast, "light");
 	return l * (hi - lo) / 100 + lo;
 }
 function mobiusCurve(t, beta) {
@@ -973,22 +977,17 @@ function mobiusCurve(t, beta) {
 }
 function mapLightnessDark(l, mode, isHighContrast) {
 	if (mode === "static") return l;
-	const beta = globalConfig.darkCurve;
-	if (isHighContrast) {
-		if (mode === "fixed") return l;
-		return 100 * mobiusCurve((100 - l) / 100, beta);
-	}
-	const [darkLo, darkHi] = globalConfig.darkLightness;
+	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
 	if (mode === "fixed") return l * (darkHi - darkLo) / 100 + darkLo;
-	const [lightLo, lightHi] = globalConfig.lightLightness;
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
 	const t = (lightHi - (l * (lightHi - lightLo) / 100 + lightLo)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
 function lightMappedToDark(lightL, isHighContrast) {
-	const beta = globalConfig.darkCurve;
-	if (isHighContrast) return 100 * mobiusCurve((100 - lightL) / 100, beta);
-	const [lightLo, lightHi] = globalConfig.lightLightness;
-	const [darkLo, darkHi] = globalConfig.darkLightness;
+	const beta = isHighContrast ? pairHC(globalConfig.darkCurve) : pairNormal(globalConfig.darkCurve);
+	const [lightLo, lightHi] = lightnessWindow(isHighContrast, "light");
+	const [darkLo, darkHi] = lightnessWindow(isHighContrast, "dark");
 	const t = (lightHi - clamp(lightL, lightLo, lightHi)) / (lightHi - lightLo);
 	return darkLo + (darkHi - darkLo) * mobiusCurve(t, beta);
 }
@@ -997,8 +996,8 @@ function mapSaturationDark(s, mode) {
 	return s * (1 - globalConfig.darkDesaturation);
 }
 function schemeLightnessRange(isDark, mode, isHighContrast) {
-	if (mode === "static" || isHighContrast) return [0, 1];
-	const [lo, hi] = isDark ? globalConfig.darkLightness : globalConfig.lightLightness;
+	if (mode === "static") return [0, 1];
+	const [lo, hi] = lightnessWindow(isHighContrast, isDark ? "dark" : "light");
 	return [lo / 100, hi / 100];
 }
 function clamp(v, min, max) {
@@ -1453,40 +1452,74 @@ function validatePrimaryTheme(primary, themes) {
 		throw new Error(`glaze: primary theme "${primary}" not found in palette. Available: ${available}.`);
 	}
 }
-function createPalette(themes) {
+/**
+* Resolve the effective primary for an export call.
+* `false` disables, a string overrides, `undefined` inherits from palette.
+*/
+function resolveEffectivePrimary(exportPrimary, palettePrimary) {
+	if (exportPrimary === false) return void 0;
+	return exportPrimary ?? palettePrimary;
+}
+/**
+* Filter a resolved color map, skipping keys already in `seen`.
+* Warns on collision and keeps the first-written value (first-write-wins).
+* Returns a new map containing only non-colliding entries.
+*/
+function filterCollisions(resolved, prefix, seen, themeName, isPrimary) {
+	const filtered = /* @__PURE__ */ new Map();
+	const label = isPrimary ? `${themeName} (primary)` : themeName;
+	for (const [name, color] of resolved) {
+		const key = `${prefix}${name}`;
+		if (seen.has(key)) {
+			console.warn(`glaze: token "${key}" from theme "${label}" collides with theme "${seen.get(key)}" — skipping.`);
+			continue;
+		}
+		seen.set(key, label);
+		filtered.set(name, color);
+	}
+	return filtered;
+}
+function createPalette(themes, paletteOptions) {
+	validatePrimaryTheme(paletteOptions?.primary, themes);
 	return {
 		tokens(options) {
-			validatePrimaryTheme(options?.primary, themes);
+			const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
+			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
 			const modes = resolveModes(options?.modes);
 			const allTokens = {};
+			const seen = /* @__PURE__ */ new Map();
 			for (const [themeName, theme] of Object.entries(themes)) {
 				const resolved = theme.resolve();
-				const tokens = buildFlatTokenMap(resolved, resolvePrefix(options, themeName, true), modes, options?.format);
+				const prefix = resolvePrefix(options, themeName, true);
+				const tokens = buildFlatTokenMap(filterCollisions(resolved, prefix, seen, themeName), prefix, 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);
+				if (themeName === effectivePrimary) {
+					const unprefixed = buildFlatTokenMap(filterCollisions(resolved, "", seen, themeName, true), "", 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 effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
+			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
 			const states = {
 				dark: options?.states?.dark ?? globalConfig.states.dark,
 				highContrast: options?.states?.highContrast ?? globalConfig.states.highContrast
 			};
 			const modes = resolveModes(options?.modes);
 			const allTokens = {};
+			const seen = /* @__PURE__ */ new Map();
 			for (const [themeName, theme] of Object.entries(themes)) {
 				const resolved = theme.resolve();
-				const tokens = buildTokenMap(resolved, resolvePrefix(options, themeName, true), states, modes, options?.format);
+				const prefix = resolvePrefix(options, themeName, true);
+				const tokens = buildTokenMap(filterCollisions(resolved, prefix, seen, themeName), prefix, states, modes, options?.format);
 				Object.assign(allTokens, tokens);
-				if (themeName === options?.primary) {
-					const unprefixed = buildTokenMap(resolved, "", states, modes, options?.format);
+				if (themeName === effectivePrimary) {
+					const unprefixed = buildTokenMap(filterCollisions(resolved, "", seen, themeName, true), "", states, modes, options?.format);
 					Object.assign(allTokens, unprefixed);
 				}
 			}
@@ -1499,7 +1532,8 @@ function createPalette(themes) {
 			return result;
 		},
 		css(options) {
-			validatePrimaryTheme(options?.primary, themes);
+			const effectivePrimary = resolveEffectivePrimary(options?.primary, paletteOptions?.primary);
+			if (options?.primary !== void 0) validatePrimaryTheme(effectivePrimary, themes);
 			const suffix = options?.suffix ?? "-color";
 			const format = options?.format ?? "rgb";
 			const allLines = {
@@ -1508,17 +1542,19 @@ function createPalette(themes) {
 				lightContrast: [],
 				darkContrast: []
 			};
+			const seen = /* @__PURE__ */ new Map();
 			for (const [themeName, theme] of Object.entries(themes)) {
 				const resolved = theme.resolve();
-				const css = buildCssMap(resolved, resolvePrefix(options, themeName, true), suffix, format);
+				const prefix = resolvePrefix(options, themeName, true);
+				const css = buildCssMap(filterCollisions(resolved, prefix, seen, themeName), prefix, 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);
+				if (themeName === effectivePrimary) {
+					const unprefixed = buildCssMap(filterCollisions(resolved, "", seen, themeName, true), "", suffix, format);
 					for (const key of [
 						"light",
 						"dark",
@@ -1600,8 +1636,8 @@ glaze.configure = function configure(config) {
 /**
 * Compose multiple themes into a palette.
 */
-glaze.palette = function palette(themes) {
-	return createPalette(themes);
+glaze.palette = function palette(themes, options) {
+	return createPalette(themes, options);
 };
 /**
 * Create a theme from a serialized export.