@tenphi/glaze 0.10.1 → 0.11.0

package/dist/index.d.cts

@@ -376,16 +376,17 @@ interface GlazeColorOverrides {
   /** Saturation multiplier on the seed (0–1). Default: 1. */
   saturationFactor?: number;
   /**
-   * Adaptation mode. Defaults vary by input form:
-   * - String inputs (`'#1a1a1a'`, `'rgb(...)'`, etc.): `'auto'` (Möbius
-   *   curve — pairs with the extended dark window to invert
-   *   `#000` ↔ `#fff` between light and dark).
-   * - `OkhslColor` and `[r, g, b]` tuple inputs: `'fixed'` (linear,
-   *   preserves light lightness exactly).
+   * Adaptation mode. Defaults to `'auto'` for every input form, so
+   * colors automatically adapt between light and dark like an ordinary
+   * theme color. The default *scaling* snapshot differs by input form:
+   * string inputs preserve their light lightness and extend the dark
+   * window to `[lo, 100]` (`#000` ↔ `#fff` flip), while `OkhslColor`
+   * and `[r, g, b]` tuple inputs snapshot the full `globalConfig.
+   * lightLightness` / `globalConfig.darkLightness` windows.
    *
-   * Pass `'fixed'` explicitly to opt a string input back into the
-   * linear, non-inverting mapping; pass `'static'` to pin the same
-   * lightness across every variant.
+   * Pass `'fixed'` explicitly to opt back into the legacy linear, non-
+   * inverting mapping; pass `'static'` to pin the same lightness
+   * across every variant.
    */
   mode?: AdaptationMode;
   /**
@@ -442,8 +443,9 @@ interface GlazeColorOverrides {
  *     the way up to white.
  *
  * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
- *   - `lightLightness: false` — preserve input exactly.
- *   - `darkLightness: globalConfig.darkLightness` — same window
+ *   - `lightLightness: globalConfig.lightLightness` — same light window
+ *     theme colors use, snapshotted at create time.
+ *   - `darkLightness: globalConfig.darkLightness` — same dark window
  *     theme colors use, snapshotted at create time.
  *
  * Passing this object replaces both fields at once. To keep one
@@ -451,7 +453,12 @@ interface GlazeColorOverrides {
  * explicitly.
  */
 interface GlazeColorScaling {
-  /** Light-mode lightness window. `false` (default) preserves input. */
+  /**
+   * Light-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: `false` (preserve input) for string inputs, plain
+   * `globalConfig.lightLightness` for object / tuple / structured
+   * inputs. Pass `false` to preserve input lightness in light mode.
+   */
   lightLightness?: false | [number, number];
   /**
    * Dark-mode lightness window. Snapshotted from `globalConfig` at

package/dist/index.d.mts

@@ -376,16 +376,17 @@ interface GlazeColorOverrides {
   /** Saturation multiplier on the seed (0–1). Default: 1. */
   saturationFactor?: number;
   /**
-   * Adaptation mode. Defaults vary by input form:
-   * - String inputs (`'#1a1a1a'`, `'rgb(...)'`, etc.): `'auto'` (Möbius
-   *   curve — pairs with the extended dark window to invert
-   *   `#000` ↔ `#fff` between light and dark).
-   * - `OkhslColor` and `[r, g, b]` tuple inputs: `'fixed'` (linear,
-   *   preserves light lightness exactly).
+   * Adaptation mode. Defaults to `'auto'` for every input form, so
+   * colors automatically adapt between light and dark like an ordinary
+   * theme color. The default *scaling* snapshot differs by input form:
+   * string inputs preserve their light lightness and extend the dark
+   * window to `[lo, 100]` (`#000` ↔ `#fff` flip), while `OkhslColor`
+   * and `[r, g, b]` tuple inputs snapshot the full `globalConfig.
+   * lightLightness` / `globalConfig.darkLightness` windows.
    *
-   * Pass `'fixed'` explicitly to opt a string input back into the
-   * linear, non-inverting mapping; pass `'static'` to pin the same
-   * lightness across every variant.
+   * Pass `'fixed'` explicitly to opt back into the legacy linear, non-
+   * inverting mapping; pass `'static'` to pin the same lightness
+   * across every variant.
    */
   mode?: AdaptationMode;
   /**
@@ -442,8 +443,9 @@ interface GlazeColorOverrides {
  *     the way up to white.
  *
  * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
- *   - `lightLightness: false` — preserve input exactly.
- *   - `darkLightness: globalConfig.darkLightness` — same window
+ *   - `lightLightness: globalConfig.lightLightness` — same light window
+ *     theme colors use, snapshotted at create time.
+ *   - `darkLightness: globalConfig.darkLightness` — same dark window
  *     theme colors use, snapshotted at create time.
  *
  * Passing this object replaces both fields at once. To keep one
@@ -451,7 +453,12 @@ interface GlazeColorOverrides {
  * explicitly.
  */
 interface GlazeColorScaling {
-  /** Light-mode lightness window. `false` (default) preserves input. */
+  /**
+   * Light-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: `false` (preserve input) for string inputs, plain
+   * `globalConfig.lightLightness` for object / tuple / structured
+   * inputs. Pass `false` to preserve input lightness in light mode.
+   */
   lightLightness?: false | [number, number];
   /**
    * Dark-mode lightness window. Snapshotted from `globalConfig` at

package/dist/index.mjs

@@ -908,16 +908,25 @@ const STANDALONE_BASE = "externalBase";
 * retroactively change the resolved variants of an already-created
 * token (matches the documented "frozen at create time" semantics).
 *
-* String value-shorthand inputs use an extended dark window
+* String value-shorthand inputs preserve their light lightness exactly
+* (`lightLightness: false`) and use an extended dark window
 * `[globalConfig.darkLightness[0], 100]` so a totally-black input can
-* Möbius-invert to totally-white in dark mode; object / tuple /
-* structured inputs use `globalConfig.darkLightness` verbatim.
+* Möbius-invert to totally-white in dark mode. Object / tuple /
+* structured inputs snapshot both windows from `globalConfig` verbatim
+* so they behave like an ordinary theme color (auto-adapted on both
+* sides).
 */
-function defaultStandaloneScaling(extendDark) {
-	const [lo, hi] = globalConfig.darkLightness;
+function defaultStandaloneScaling(isString) {
+	if (isString) {
+		const [darkLo] = globalConfig.darkLightness;
+		return {
+			lightLightness: false,
+			darkLightness: [darkLo, 100]
+		};
+	}
 	return {
-		lightLightness: false,
-		darkLightness: extendDark ? [lo, 100] : [lo, hi]
+		lightLightness: globalConfig.lightLightness,
+		darkLightness: globalConfig.darkLightness
 	};
 }
 /** Reserved internal names that user-supplied `name` must not collide with. */
@@ -1946,17 +1955,18 @@ function extractOkhslFromValue(value) {
 * Build the `ColorMap` for a value-shorthand `glaze.color()` call.
 *
 * The user-facing color (`STANDALONE_VALUE`) defaults to `mode: 'auto'`
-* for string inputs (Möbius-inverted dark variant — pairs with the
+* across every value-shorthand form. String inputs pair with the
 * extended dark window so a totally-black input renders as totally-white
-* in dark mode) and `mode: 'fixed'` for `OkhslColor` / RGB-tuple inputs
-* (linear, no inversion).
+* in dark mode; `OkhslColor` / RGB-tuple inputs auto-adapt into the
+* snapshotted `globalConfig.lightLightness` / `globalConfig.darkLightness`
+* windows.
 *
 * When the user requests `contrast` or relative `lightness`, a hidden
 * `STANDALONE_SEED` def is synthesized at `mode: 'static'`. That keeps
 * the seed pinned to the literal user-provided color across all four
 * variants, so the contrast solver always anchors against it.
 */
-function buildStandaloneValueDefs(main, options, inputIsString) {
+function buildStandaloneValueDefs(main, options) {
 	const seedHue = typeof options?.hue === "number" ? options.hue : main.h;
 	const seedSaturation = options?.saturation ?? main.s * 100;
 	const relativeHue = typeof options?.hue === "string" ? options.hue : void 0;
@@ -1972,7 +1982,7 @@ function buildStandaloneValueDefs(main, options, inputIsString) {
 		saturation: options?.saturationFactor,
 		lightness: lightnessOption ?? main.l * 100,
 		contrast: options?.contrast,
-		mode: options?.mode ?? (inputIsString ? "auto" : "fixed"),
+		mode: options?.mode ?? "auto",
 		opacity: options?.opacity,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
 	};
@@ -2073,7 +2083,7 @@ function createColorToken(input, scaling) {
 	const defs = { [primary]: {
 		lightness: input.lightness,
 		saturation: input.saturationFactor,
-		mode: input.mode ?? "fixed",
+		mode: input.mode ?? "auto",
 		contrast: input.contrast,
 		opacity: input.opacity,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
@@ -2095,7 +2105,7 @@ function createColorTokenFromValue(value, options, scaling) {
 	const inputIsString = typeof value === "string";
 	const main = extractOkhslFromValue(value);
 	const baseToken = resolveBaseToken(options?.base);
-	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options, inputIsString);
+	const { seedHue, seedSaturation, defs, primary } = buildStandaloneValueDefs(main, options);
 	const effectiveScaling = scaling ?? defaultStandaloneScaling(inputIsString);
 	const exportData = () => ({
 		form: "value",
@@ -2215,17 +2225,23 @@ function isStructuredColorInput(input) {
 *   emits (`rgb()`, `hsl()`, `okhsl()`, `oklch()`), an `OkhslColor`
 *   object `{ h, s, l }` (0–1 ranges), or an `[r, g, b]` (0–255) tuple.
 *
-* Defaults vary by input form:
-* - String value-shorthand: `mode: 'auto'` with snapshotted scaling
-*   `{ lightLightness: false, darkLightness: [globalConfig.darkLightness[0], 100] }`.
-*   Light preserves the input exactly; dark Möbius-inverts up to 100, so
-*   `glaze.color('#000')` renders as `#fff` in dark mode (and
-*   `glaze.color('#fff')` falls to the dark `lo` floor).
-* - `OkhslColor` object / RGB-tuple value-shorthand: `mode: 'fixed'`
-*   with `scaling: { lightLightness: false }` — light preserves the
-*   input; dark linearly maps into `globalConfig.darkLightness`.
-* - Structured form (`{ hue, saturation, lightness, ... }`):
-*   `mode: 'fixed'`; both windows come from `globalConfig`.
+* Defaults: every input form defaults to `mode: 'auto'` so colors
+* automatically adapt between light and dark like an ordinary theme
+* color. The scaling snapshot taken at create time differs by input
+* form:
+* - String value-shorthand: `{ lightLightness: false, darkLightness:
+*   [globalConfig.darkLightness[0], 100] }`. Light preserves the input
+*   exactly; dark Möbius-inverts up to 100, so `glaze.color('#000')`
+*   renders as `#fff` in dark mode (and `glaze.color('#fff')` falls to
+*   the dark `lo` floor).
+* - `OkhslColor` object / RGB-tuple / structured value-shorthand:
+*   `{ lightLightness: globalConfig.lightLightness, darkLightness:
+*   globalConfig.darkLightness }` — both windows come straight from
+*   `globalConfig`, so the resulting token behaves like a theme color.
+*
+* Pass `{ mode: 'fixed' }` to opt back into the legacy linear, non-
+* inverting mapping, or `{ mode: 'static' }` to pin the same lightness
+* across every variant.
 *
 * Relative `lightness: '+N'` and `contrast: <ratio>` are anchored to
 * the literal seed (the value passed in) by default, pinned at