@tenphi/glaze 0.10.0 → 0.11.0

package/README.md

@@ -282,27 +282,33 @@ adapt to both lightness windows. The defaults vary by input form,
 because string inputs are typically end-user values (color pickers,
 theme settings) where natural light/dark inversion is the expectation:
 
+Every input form defaults to **`mode: 'auto'`** so the resolved token
+adapts between light and dark like an ordinary theme color. The
+*scaling* snapshot taken at create time differs by input form:
+
 - **String value-shorthand** (hex, `rgb()`, `hsl()`, `okhsl()`,
   `oklch()`):
   - Light variant preserves the input lightness exactly.
   - Dark variant is **Möbius-inverted** into `[globalConfig.darkLightness[0], 100]`,
     so `glaze.color('#000')` renders as `#fff` in dark mode and
     `glaze.color('#fff')` falls to the dark `lo` floor (default `0.15`).
-  - Adaptation mode defaults to `'auto'`.
   - The dark `lo` is snapshotted from `globalConfig` at color-creation
     time, matching how an explicit `scaling.darkLightness: [lo, hi]`
     behaves.
 
 - **Object / tuple value-shorthand** (`{ h, s, l }`, `[r, g, b]`) and
   the **structured form** (`{ hue, saturation, lightness, ... }`):
-  - Light variant preserves the input lightness exactly.
-  - Dark variant is linearly mapped into `globalConfig.darkLightness`
-    (default `[15, 95]`), snapshotted at color-creation time so later
+  - Both light and dark variants are mapped through
+    `globalConfig.lightLightness` / `globalConfig.darkLightness`
+    (defaults `[10, 100]` / `[15, 95]`) — the same windows a theme color
+    uses. With the `'auto'` default the dark variant is Möbius-inverted
+    into that dark window, so a near-white seed lands at a near-dark
+    dark variant.
+  - Both windows are snapshotted at color-creation time so later
     `glaze.configure()` calls don't retroactively change exported tokens.
-  - Adaptation mode defaults to `'fixed'` (linear, no Möbius curve).
 
-To opt back into the old fixed-linear default for string inputs, pass
-either `{ mode: 'fixed' }` as the second arg, or supply an explicit
+To opt back into the legacy fixed-linear default (no Möbius inversion),
+pass `{ mode: 'fixed' }` as the second arg, or supply an explicit
 `scaling` as the third arg (see [Lightness scaling](#lightness-scaling)).
 
 ```ts
@@ -373,7 +379,7 @@ All overrides:
 | `saturation` | Override seed saturation (0–100) |
 | `lightness` | Number (absolute 0–100) or `'+N'`/`'-N'`. Without `base`, relative is anchored to the literal seed; with `base`, anchored to `base`'s lightness per scheme. Supports `[normal, hc]` pairs |
 | `saturationFactor` | Multiplier on seed (0–1, default 1) |
-| `mode` | `'auto'` (default for string inputs) / `'fixed'` (default for object / tuple / structured inputs) / `'static'` — see [Adaptation Modes](#adaptation-modes) |
+| `mode` | `'auto'` (default for every input form) / `'fixed'` / `'static'` — see [Adaptation Modes](#adaptation-modes) |
 | `contrast` | WCAG floor. Without `base`, anchored to the literal seed; with `base`, solved per scheme against `base`'s resolved variant. Same shape as `RegularColorDef.contrast`. When the target can't be physically met, `glaze` emits a `console.warn` and returns the closest passing variant |
 | `base` | Another `glaze.color()` token **or** a raw `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`). Raw values are auto-wrapped via `glaze.color(value)` so they pick up the same auto-invert defaults as an explicit wrap. When set, `contrast` and relative `lightness` anchor to it per scheme; relative `hue` still anchors to the seed |
 | `opacity` | Fixed alpha 0–1 applied to every variant. Surfaces in `rgb(... / A)`, `okhsl(... / A)`, etc. Combining with `contrast` is not recommended (perceived lightness becomes unpredictable) — `glaze` emits a `console.warn` |
@@ -1423,7 +1429,7 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`) |
 | `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255) |
 | `glaze.color(input, scaling?)` | Create a standalone color token from `{ hue, saturation, lightness, opacity?, contrast?, base?, name?, ... }`. Optional `scaling` overrides the lightness windows |
-| `glaze.color(value, overrides?, scaling?)` | Create a standalone color token from a hex string (3/6/8 digits), an `rgb()` / `hsl()` / `okhsl()` / `oklch()` string, an `{ h, s, l }` OKHSL object, or an `[r, g, b]` (0–255) tuple. Overrides accept absolute or relative `hue` / `lightness`, `saturation`, `mode`, `contrast`, `opacity`, `name`, and `base` (a `GlazeColorToken` or any `GlazeColorValue`; raw values are auto-wrapped). When `base` is set, `contrast` and relative `lightness` are anchored to the base per scheme — see [Pairing Colors](#pairing-colors). String inputs default to `mode: 'auto'` with the dark window extended to upper `100`; object / tuple inputs default to `mode: 'fixed'`. |
+| `glaze.color(value, overrides?, scaling?)` | Create a standalone color token from a hex string (3/6/8 digits), an `rgb()` / `hsl()` / `okhsl()` / `oklch()` string, an `{ h, s, l }` OKHSL object, or an `[r, g, b]` (0–255) tuple. Overrides accept absolute or relative `hue` / `lightness`, `saturation`, `mode`, `contrast`, `opacity`, `name`, and `base` (a `GlazeColorToken` or any `GlazeColorValue`; raw values are auto-wrapped). When `base` is set, `contrast` and relative `lightness` are anchored to the base per scheme — see [Pairing Colors](#pairing-colors). Every input form defaults to `mode: 'auto'`; string inputs additionally preserve light lightness exactly and extend the dark window to `[lo, 100]`, while object / tuple / structured inputs snapshot both windows from `globalConfig.lightLightness` / `globalConfig.darkLightness`. |
 | `glaze.colorFrom(data)` | Rehydrate a `glaze.color()` token from a `.export()` snapshot. Inverse of `token.export()` — see [Persisting Standalone Colors](#persisting-standalone-colors) |
 | `glaze.shadow(input)` | Compute a standalone shadow color (returns `ResolvedColorVariant`). `bg` / `fg` accept any `GlazeColorValue` form |
 | `glaze.format(variant, format?)` | Format any `ResolvedColorVariant` as a CSS string |

package/dist/index.cjs

@@ -361,6 +361,12 @@ const oklabToOkhsl = (lab) => {
 		0,
 		toe(L)
 	];
+	const L_EXTREME_EPSILON = 1e-6;
+	if (L >= 1 - L_EXTREME_EPSILON || L <= L_EXTREME_EPSILON) return [
+		0,
+		0,
+		toe(L)
+	];
 	const a_ = a / C;
 	const b_ = b / C;
 	let h = Math.atan2(b, a) * (180 / Math.PI);
@@ -904,16 +910,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. */
@@ -1942,17 +1957,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;
@@ -1968,7 +1984,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
 	};
@@ -2069,7 +2085,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
@@ -2091,7 +2107,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",
@@ -2211,17 +2227,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