@tenphi/glaze 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@
  *
  * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
  * against a base color. Used by glaze when resolving dependent colors
- * with `ensureContrast`.
+ * with `contrast`.
  */
 type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 type MinContrast$1 = number | ContrastPreset;
@@ -17,8 +17,8 @@ interface FindLightnessForContrastOptions {
   preferredLightness: number;
   /** Base/reference color as linear sRGB (channels may be outside 0–1 before clamp). */
   baseLinearRgb: [number, number, number];
-  /** Ensures the WCAG contrast ratio meets a target floor. */
-  ensureContrast: MinContrast$1;
+  /** WCAG contrast ratio target floor. */
+  contrast: MinContrast$1;
   /** Search bounds for lightness. Default: [0, 1]. */
   lightnessRange?: [number, number];
   /** Convergence threshold. Default: 1e-4. */
@@ -48,6 +48,8 @@ declare function findLightnessForContrast(options: FindLightnessForContrastOptio
 type HCPair<T> = T | [T, T];
 type MinContrast = number | ContrastPreset;
 type AdaptationMode = 'auto' | 'fixed' | 'static';
+/** A signed relative offset string, e.g. '+20' or '-15.5'. */
+type RelativeValue = `+${number}` | `-${number}`;
 /** Color format for output. */
 type GlazeColorFormat = 'okhsl' | 'rgb' | 'hsl' | 'oklch';
 /**
@@ -61,16 +63,24 @@ interface GlazeOutputModes {
   highContrast?: boolean;
 }
 interface ColorDef {
-  /** Lightness in the light scheme (0–100). Root color. */
-  l?: HCPair<number>;
+  /**
+   * Lightness value (0–100).
+   * - Number: absolute lightness.
+   * - String ('+N' / '-N'): relative to base color's lightness (requires `base`).
+   */
+  lightness?: HCPair<number | RelativeValue>;
   /** Saturation factor applied to the seed saturation (0–1, default: 1). */
-  sat?: number;
+  saturation?: number;
+  /**
+   * Hue override for this color.
+   * - Number: absolute hue (0–360).
+   * - String ('+N' / '-N'): relative to the theme seed hue.
+   */
+  hue?: number | RelativeValue;
   /** Name of another color in the same theme (dependent color). */
   base?: string;
-  /** Lightness delta from the base color. */
-  contrast?: HCPair<number>;
-  /** Ensures the WCAG contrast ratio meets a target floor against the base. */
-  ensureContrast?: HCPair<MinContrast>;
+  /** WCAG contrast ratio floor against the base color. */
+  contrast?: HCPair<MinContrast>;
   /** Adaptation mode. Default: 'auto'. */
   mode?: AdaptationMode;
 }
@@ -125,8 +135,8 @@ interface GlazeThemeExport {
 interface GlazeColorInput {
   hue: number;
   saturation: number;
-  l: HCPair<number>;
-  sat?: number;
+  lightness: HCPair<number>;
+  saturationFactor?: number;
   mode?: AdaptationMode;
 }
 /** Return type for `glaze.color()`. */
@@ -167,6 +177,8 @@ interface GlazeTheme {
   tokens(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
   /** Export as plain JSON. */
   json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
+  /** Export as CSS custom property declarations. */
+  css(options?: GlazeCssOptions): GlazeCssResult;
 }
 interface GlazeExtendOptions {
   hue?: number;
@@ -192,6 +204,19 @@ interface GlazeJsonOptions {
   /** Output color format. Default: 'okhsl'. */
   format?: GlazeColorFormat;
 }
+interface GlazeCssOptions {
+  /** Output color format. Default: 'rgb'. */
+  format?: GlazeColorFormat;
+  /** Suffix appended to each CSS custom property name. Default: '-color'. */
+  suffix?: string;
+}
+/** CSS custom property declarations grouped by scheme variant. */
+interface GlazeCssResult {
+  light: string;
+  dark: string;
+  lightContrast: string;
+  darkContrast: string;
+}
 interface GlazePalette {
   /** Export all themes as a combined token map. */
   tokens(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
@@ -199,6 +224,10 @@ interface GlazePalette {
   json(options?: GlazeJsonOptions & {
     prefix?: boolean | Record<string, string>;
   }): Record<string, Record<string, Record<string, string>>>;
+  /** Export all themes as CSS custom property declarations. */
+  css(options?: GlazeCssOptions & {
+    prefix?: boolean | Record<string, string>;
+  }): GlazeCssResult;
 }
 //#endregion
 //#region src/glaze.d.ts
@@ -224,6 +253,9 @@ declare namespace glaze {
     json(options?: GlazeJsonOptions & {
       prefix?: boolean | Record<string, string>;
     }): Record<string, Record<string, Record<string, string>>>;
+    css(options?: GlazeCssOptions & {
+      prefix?: boolean | Record<string, string>;
+    }): GlazeCssResult;
   };
   var from: (data: GlazeThemeExport) => GlazeTheme;
   var color: (input: GlazeColorInput) => GlazeColorToken;
@@ -294,5 +326,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
  */
 declare function formatOklch(h: number, s: number, l: number): string;
 //#endregion
-export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type MinContrast, type ResolvedColor, type ResolvedColorVariant, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type MinContrast, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -493,7 +493,7 @@ function formatOklch(h, s, l) {
 *
 * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
 * against a base color. Used by glaze when resolving dependent colors
-* with `ensureContrast`.
+* with `contrast`.
 */
 const CONTRAST_PRESETS = {
 	AA: 4.5,
@@ -631,8 +631,8 @@ function coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter) {
 * against a base color, staying as close to `preferredLightness` as possible.
 */
 function findLightnessForContrast(options) {
-	const { hue, saturation, preferredLightness, baseLinearRgb, ensureContrast: ensureContrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
-	const target = resolveMinContrast(ensureContrastInput);
+	const { hue, saturation, preferredLightness, baseLinearRgb, contrast: contrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
+	const target = resolveMinContrast(contrastInput);
 	const yBase = relativeLuminanceFromLinearRgb(baseLinearRgb);
 	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
 	if (crPref >= target) return {
@@ -713,9 +713,10 @@ function validateColorDefs(defs) {
 	const names = new Set(Object.keys(defs));
 	for (const [name, def] of Object.entries(defs)) {
 		if (def.contrast !== void 0 && !def.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
-		if (def.l !== void 0 && def.base !== void 0) console.warn(`glaze: color "${name}" has both "l" and "base". "l" takes precedence.`);
+		if (def.lightness !== void 0 && !isAbsoluteLightness(def.lightness) && !def.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
+		if (isAbsoluteLightness(def.lightness) && def.base !== void 0) console.warn(`glaze: color "${name}" has absolute "lightness" and "base". Absolute lightness takes precedence.`);
 		if (def.base && !names.has(def.base)) throw new Error(`glaze: color "${name}" references non-existent base "${def.base}".`);
-		if (def.l === void 0 && def.base === void 0) throw new Error(`glaze: color "${name}" must have either "l" (root) or "base" + "contrast" (dependent).`);
+		if (!isAbsoluteLightness(def.lightness) && def.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
 	}
 	const visited = /* @__PURE__ */ new Set();
 	const inStack = /* @__PURE__ */ new Set();
@@ -724,7 +725,7 @@ function validateColorDefs(defs) {
 		if (visited.has(name)) return;
 		inStack.add(name);
 		const def = defs[name];
-		if (def.base && def.l === void 0) dfs(def.base);
+		if (def.base && !isAbsoluteLightness(def.lightness)) dfs(def.base);
 		inStack.delete(name);
 		visited.add(name);
 	}
@@ -737,7 +738,7 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
-		if (def.base && def.l === void 0) visit(def.base);
+		if (def.base && !isAbsoluteLightness(def.lightness)) visit(def.base);
 		result.push(name);
 	}
 	for (const name of Object.keys(defs)) visit(name);
@@ -753,44 +754,75 @@ function mapSaturationDark(s, mode) {
 	if (mode === "static") return s;
 	return s * (1 - globalConfig.darkDesaturation);
 }
+function clamp(v, min, max) {
+	return Math.max(min, Math.min(max, v));
+}
 /**
-* Resolve the effective lightness from a contrast delta.
+* Parse a value that can be absolute (number) or relative (signed string).
+* Returns the numeric value and whether it's relative.
 */
-function resolveContrastLightness(baseLightness, contrast) {
-	if (contrast < 0) return clamp(baseLightness + contrast, 0, 100);
-	const candidate = baseLightness + contrast;
-	if (candidate > 100) return clamp(baseLightness - contrast, 0, 100);
-	return clamp(candidate, 0, 100);
+function parseRelativeOrAbsolute(value) {
+	if (typeof value === "number") return {
+		value,
+		relative: false
+	};
+	return {
+		value: parseFloat(value),
+		relative: true
+	};
 }
-function clamp(v, min, max) {
-	return Math.max(min, Math.min(max, v));
+/**
+* Compute the effective hue for a color, given the theme seed hue
+* and an optional per-color hue override.
+*/
+function resolveEffectiveHue(seedHue, defHue) {
+	if (defHue === void 0) return seedHue;
+	const parsed = parseRelativeOrAbsolute(defHue);
+	if (parsed.relative) return ((seedHue + parsed.value) % 360 + 360) % 360;
+	return (parsed.value % 360 + 360) % 360;
+}
+/**
+* Check whether a lightness value represents an absolute root definition
+* (i.e. a number, not a relative string).
+*/
+function isAbsoluteLightness(lightness) {
+	if (lightness === void 0) return false;
+	return typeof (Array.isArray(lightness) ? lightness[0] : lightness) === "number";
 }
 function resolveRootColor(_name, def, _ctx, isHighContrast) {
-	const rawL = def.l;
+	const rawL = def.lightness;
 	return {
-		lightL: clamp(isHighContrast ? pairHC(rawL) : pairNormal(rawL), 0, 100),
-		sat: clamp(def.sat ?? 1, 0, 1)
+		lightL: clamp(parseRelativeOrAbsolute(isHighContrast ? pairHC(rawL) : pairNormal(rawL)).value, 0, 100),
+		satFactor: clamp(def.saturation ?? 1, 0, 1)
 	};
 }
-function resolveDependentColor(name, def, ctx, isHighContrast, isDark) {
+function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue) {
 	const baseName = def.base;
 	const baseResolved = ctx.resolved.get(baseName);
 	if (!baseResolved) throw new Error(`glaze: base "${baseName}" not yet resolved for "${name}".`);
 	const mode = def.mode ?? "auto";
-	const sat = clamp(def.sat ?? 1, 0, 1);
+	const satFactor = clamp(def.saturation ?? 1, 0, 1);
 	let baseL;
 	if (isDark && isHighContrast) baseL = baseResolved.darkContrast.l * 100;
 	else if (isDark) baseL = baseResolved.dark.l * 100;
 	else if (isHighContrast) baseL = baseResolved.lightContrast.l * 100;
 	else baseL = baseResolved.light.l * 100;
-	const rawContrast = def.contrast ?? 0;
-	let contrast = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
-	if (isDark && mode === "auto") contrast = -contrast;
-	const preferredL = resolveContrastLightness(baseL, contrast);
-	const rawEnsureContrast = def.ensureContrast;
-	if (rawEnsureContrast !== void 0) {
-		const minCr = isHighContrast ? pairHC(rawEnsureContrast) : pairNormal(rawEnsureContrast);
-		const effectiveSat = isDark ? mapSaturationDark(sat * ctx.saturation / 100, mode) : sat * ctx.saturation / 100;
+	let preferredL;
+	const rawLightness = def.lightness;
+	if (rawLightness === void 0) preferredL = baseL;
+	else {
+		const parsed = parseRelativeOrAbsolute(isHighContrast ? pairHC(rawLightness) : pairNormal(rawLightness));
+		if (parsed.relative) {
+			let delta = parsed.value;
+			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);
+	}
+	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;
 		let baseH;
 		let baseS;
 		let baseLNorm;
@@ -814,48 +846,49 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark) {
 		const baseLinearRgb = okhslToLinearSrgb(baseH, baseS, baseLNorm);
 		return {
 			l: findLightnessForContrast({
-				hue: ctx.hue,
+				hue: effectiveHue,
 				saturation: effectiveSat,
 				preferredLightness: preferredL / 100,
 				baseLinearRgb,
-				ensureContrast: minCr
+				contrast: minCr
 			}).lightness * 100,
-			sat
+			satFactor
 		};
 	}
 	return {
 		l: clamp(preferredL, 0, 100),
-		sat
+		satFactor
 	};
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	const mode = def.mode ?? "auto";
-	const isRoot = def.l !== void 0;
+	const isRoot = isAbsoluteLightness(def.lightness) && !def.base;
+	const effectiveHue = resolveEffectiveHue(ctx.hue, def.hue);
 	let lightL;
-	let sat;
+	let satFactor;
 	if (isRoot) {
 		const root = resolveRootColor(name, def, ctx, isHighContrast);
 		lightL = root.lightL;
-		sat = root.sat;
+		satFactor = root.satFactor;
 	} else {
-		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark);
+		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue);
 		lightL = dep.l;
-		sat = dep.sat;
+		satFactor = dep.satFactor;
 	}
 	let finalL;
 	let finalSat;
 	if (isDark && isRoot) {
 		finalL = mapLightnessDark(lightL, mode);
-		finalSat = mapSaturationDark(sat * ctx.saturation / 100, mode);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else if (isDark && !isRoot) {
 		finalL = lightL;
-		finalSat = mapSaturationDark(sat * ctx.saturation / 100, mode);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else {
 		finalL = lightL;
-		finalSat = sat * ctx.saturation / 100;
+		finalSat = satFactor * ctx.saturation / 100;
 	}
 	return {
-		h: ctx.hue,
+		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
 		l: clamp(finalL / 100, 0, 1)
 	};
@@ -974,6 +1007,27 @@ function buildJsonMap(resolved, modes, format = "okhsl") {
 	}
 	return result;
 }
+function buildCssMap(resolved, prefix, suffix, format) {
+	const lines = {
+		light: [],
+		dark: [],
+		lightContrast: [],
+		darkContrast: []
+	};
+	for (const [name, color] of resolved) {
+		const prop = `--${prefix}${name}${suffix}`;
+		lines.light.push(`${prop}: ${formatVariant(color.light, format)};`);
+		lines.dark.push(`${prop}: ${formatVariant(color.dark, format)};`);
+		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format)};`);
+		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format)};`);
+	}
+	return {
+		light: lines.light.join("\n"),
+		dark: lines.dark.join("\n"),
+		lightContrast: lines.lightContrast.join("\n"),
+		darkContrast: lines.darkContrast.join("\n")
+	};
+}
 function createTheme(hue, saturation, initialColors) {
 	let colorDefs = initialColors ? { ...initialColors } : {};
 	return {
@@ -1030,6 +1084,9 @@ function createTheme(hue, saturation, initialColors) {
 		},
 		json(options) {
 			return buildJsonMap(resolveAllColors(hue, saturation, colorDefs), resolveModes(options?.modes), options?.format);
+		},
+		css(options) {
+			return buildCssMap(resolveAllColors(hue, saturation, colorDefs), "", options?.suffix ?? "-color", options?.format ?? "rgb");
 		}
 	};
 }
@@ -1057,13 +1114,42 @@ function createPalette(themes) {
 			const result = {};
 			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, options?.format);
 			return result;
+		},
+		css(options) {
+			const suffix = options?.suffix ?? "-color";
+			const format = options?.format ?? "rgb";
+			const allLines = {
+				light: [],
+				dark: [],
+				lightContrast: [],
+				darkContrast: []
+			};
+			for (const [themeName, theme] of Object.entries(themes)) {
+				const resolved = theme.resolve();
+				let prefix = "";
+				if (options?.prefix === true) prefix = `${themeName}-`;
+				else if (typeof options?.prefix === "object" && options.prefix !== null) prefix = options.prefix[themeName] ?? `${themeName}-`;
+				const css = buildCssMap(resolved, prefix, suffix, format);
+				for (const key of [
+					"light",
+					"dark",
+					"lightContrast",
+					"darkContrast"
+				]) if (css[key]) allLines[key].push(css[key]);
+			}
+			return {
+				light: allLines.light.join("\n"),
+				dark: allLines.dark.join("\n"),
+				lightContrast: allLines.lightContrast.join("\n"),
+				darkContrast: allLines.darkContrast.join("\n")
+			};
 		}
 	};
 }
 function createColorToken(input) {
 	const defs = { __color__: {
-		l: input.l,
-		sat: input.sat,
+		lightness: input.lightness,
+		saturation: input.saturationFactor,
 		mode: input.mode
 	} };
 	return {