@tenphi/glaze 0.11.1 → 0.13.0

package/dist/index.d.cts

@@ -26,6 +26,30 @@ interface FindLightnessForContrastOptions {
   epsilon?: number;
   /** Maximum binary-search iterations per branch. Default: 14. */
   maxIterations?: number;
+  /**
+   * Preferred search direction before auto-flip is considered.
+   *
+   * Theme resolution sets this from the requested lightness relative to
+   * the base color so `autoFlip: false` preserves the authored direction.
+   * When omitted, the solver falls back to the side whose extreme has
+   * higher contrast against the base.
+   */
+  initialDirection?: 'lighter' | 'darker';
+  /**
+   * Auto-flip lightness direction when contrast can't be met.
+   *
+   * When `true`, the solver searches the initial direction first. If that side
+   * doesn't reach the target, it tries the opposite direction and
+   * uses it when it passes. If neither side passes, it returns the
+   * extreme lightness of the initial direction.
+   *
+   * When `false`, only the initial direction is considered. If it
+   * doesn't reach the target, the result is pinned to the initial
+   * direction's extreme — never to the original preferred lightness.
+   *
+   * Default: false.
+   */
+  flip?: boolean;
 }
 interface FindLightnessForContrastResult {
   /** Chosen lightness in 0–1. */
@@ -36,6 +60,12 @@ interface FindLightnessForContrastResult {
   met: boolean;
   /** Which branch was selected. */
   branch: 'lighter' | 'darker' | 'preferred';
+  /**
+   * Whether the result was auto-flipped to the opposite direction.
+   * Only set when the initial direction failed and the opposite
+   * direction satisfied the target.
+   */
+  flipped?: boolean;
 }
 declare function resolveMinContrast(value: MinContrast$1): number;
 /**
@@ -62,6 +92,22 @@ interface FindValueForMixContrastOptions {
   epsilon?: number;
   /** Maximum binary-search iterations per branch. Default: 20. */
   maxIterations?: number;
+  /**
+   * Auto-flip mix direction when contrast can't be met.
+   *
+   * When `true`, the solver searches the initial direction first
+   * (the side whose extreme has higher contrast against the base).
+   * If that side doesn't reach the target, it tries the opposite
+   * direction and uses it when it passes. If neither side passes,
+   * it returns the extreme mix value of the initial direction.
+   *
+   * When `false`, only the initial direction is considered. If it
+   * doesn't reach the target, the result is pinned to the initial
+   * direction's extreme — never to the original preferred value.
+   *
+   * Default: false.
+   */
+  flip?: boolean;
 }
 interface FindValueForMixContrastResult {
   /** Chosen mix parameter (0–1). */
@@ -70,6 +116,12 @@ interface FindValueForMixContrastResult {
   contrast: number;
   /** Whether the target was reached. */
   met: boolean;
+  /**
+   * Whether the result was auto-flipped to the opposite direction.
+   * Only set when the initial direction failed and the opposite
+   * direction satisfied the target.
+   */
+  flipped?: boolean;
 }
 /**
  * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
@@ -104,6 +156,18 @@ interface OkhslColor {
   s: number;
   l: number;
 }
+/** sRGB components in 0–255 (value-shorthand object form). */
+interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+/** OKLCh components matching CSS `oklch(L C H)` (L/C: 0–1, H: degrees). */
+interface OklchColor {
+  l: number;
+  c: number;
+  h: number;
+}
 interface RegularColorDef {
   /**
    * Lightness value (0–100).
@@ -250,11 +314,16 @@ interface ResolvedColor {
   /** Adaptation mode. Present only for regular colors, omitted for shadows. */
   mode?: AdaptationMode;
 }
+/**
+ * Lightness window value. A `[lo, hi]` tuple (0–100) or `false` to disable
+ * clamping entirely (equivalent to `[0, 100]`).
+ */
+type LightnessWindow = false | [number, number];
 interface GlazeConfig {
-  /** Light scheme lightness window [lo, hi]. Default: [10, 100]. */
-  lightLightness?: [number, number];
-  /** Dark scheme lightness window [lo, hi]. Default: [15, 95]. */
-  darkLightness?: [number, number];
+  /** Light scheme lightness window [lo, hi]. Default: [10, 100]. Pass `false` to disable clamping. */
+  lightLightness?: LightnessWindow;
+  /** Dark scheme lightness window [lo, hi]. Default: [15, 95]. Pass `false` to disable clamping. */
+  darkLightness?: LightnessWindow;
   /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
   darkDesaturation?: number;
   /**
@@ -273,10 +342,25 @@ interface GlazeConfig {
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /**
+   * Automatically flip lightness direction when contrast can't be met.
+   *
+   * When enabled (default `true`), the solver searches the requested
+   * lightness direction first. If that direction can't reach the target,
+   * it tries the opposite direction and uses it when it passes. If neither
+   * side passes, the lightness is pinned to the requested-direction
+   * extreme and a warning is emitted.
+   *
+   * Set to `false` for strict "no flip" behavior. The opposite
+   * direction is never considered: if the requested direction can't
+   * meet the target, the lightness is pinned to its extreme (never
+   * falls back to the originally requested lightness).
+   */
+  autoFlip?: boolean;
 }
 interface GlazeConfigResolved {
-  lightLightness: [number, number];
-  darkLightness: [number, number];
+  lightLightness: LightnessWindow;
+  darkLightness: LightnessWindow;
   darkDesaturation: number;
   darkCurve: HCPair<number>;
   states: {
@@ -285,20 +369,47 @@ interface GlazeConfigResolved {
   };
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
+  autoFlip: boolean;
+}
+/**
+ * Per-instance config override for `glaze.color()` and `glaze()` themes.
+ * Fields that are set take priority over the live global config. Fields
+ * that are omitted fall through to the live global at resolve time.
+ *
+ * `false` for a lightness window disables clamping (equivalent to `[0, 100]`).
+ */
+interface GlazeConfigOverride {
+  /** Light scheme lightness window, or `false` to disable clamping. */
+  lightLightness?: LightnessWindow;
+  /** Dark scheme lightness window, or `false` to disable clamping. */
+  darkLightness?: LightnessWindow;
+  /** Saturation reduction factor for dark scheme (0–1). */
+  darkDesaturation?: number;
+  /** Möbius beta for dark auto-inversion. Accepts [normal, hc] pair. */
+  darkCurve?: HCPair<number>;
+  /** Whether to auto-flip lightness when contrast can't be met. */
+  autoFlip?: boolean;
+  /**
+   * Shadow tuning defaults. Only meaningful for themes; harmless on
+   * standalone color tokens.
+   */
+  shadowTuning?: ShadowTuning;
 }
 /** Serialized theme configuration (no resolved values). */
 interface GlazeThemeExport {
   hue: number;
   saturation: number;
   colors: ColorMap;
+  /** Per-theme config override, if any. */
+  config?: GlazeConfigOverride;
 }
 /** Input for `glaze.shadow()` standalone factory. */
 interface GlazeShadowInput {
   /**
    * Background color — accepts any `GlazeColorValue` form: hex
    * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
-   * / `oklch()` strings, an `OkhslColor` object, or an `[r, g, b]`
-   * (0–255) tuple. Alpha components are dropped with a warning.
+   * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
+   * `{ l, c, h }`). Alpha components are dropped with a warning.
    */
   bg: GlazeColorValue;
   /**
@@ -349,15 +460,14 @@ interface GlazeColorInput {
  * `rgb()`, `hsl()`, `okhsl()`, `oklch()` (alpha components also dropped
  * with a warning).
  *
- * The OKHSL object form `{ h, s, l }` matches Glaze's native shape
- * (h: 0–360, s/l: 0–1). Passing 0–100 values for `s`/`l` throws with
- * a hint to use the structured `{ hue, saturation, lightness }` form.
- *
- * The tuple form is `[r, g, b]` in 0–255, matching `glaze.fromRgb`'s
- * range. Out-of-range or non-finite components throw.
+ * Literal object forms:
+ * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
+ *   throws with a hint to use the structured form.
+ * - `{ r, g, b }` — sRGB 0–255.
+ * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
  */
-type GlazeColorValue = string | OkhslColor | readonly [number, number, number];
-/** Optional overrides for `glaze.color(value, overrides?)`. */
+type GlazeColorValue = string | OkhslColor | RgbColor | OklchColor;
+/** Color overrides for the `from` and value-shorthand inputs. */
 interface GlazeColorOverrides {
   /**
    * Override hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
@@ -378,11 +488,11 @@ interface GlazeColorOverrides {
   /**
    * 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.
+   * theme color. All value-shorthand inputs (strings and literal objects)
+   * preserve light lightness (`lightLightness: false`) and snapshot
+   * `globalConfig.darkLightness` on the dark side. Only the structured
+   * `{ hue, saturation, lightness }` form also snapshots
+   * `globalConfig.lightLightness`.
    *
    * Pass `'fixed'` explicitly to opt back into the legacy linear, non-
    * inverting mapping; pass `'static'` to pin the same lightness
@@ -398,7 +508,7 @@ interface GlazeColorOverrides {
   /**
    * Optional dependency on another color. Accepts either a
    * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
-   * `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`),
+   * `GlazeColorValue` (hex / CSS strings / `{ r, g, b }` / `{ h, s, l }` / …),
    * which is automatically wrapped in `glaze.color(value)`.
    *
    * When set:
@@ -408,6 +518,11 @@ interface GlazeColorOverrides {
    *   lightness per-scheme (matches theme behavior for dependent colors).
    * - Relative `hue: '+N'` / `'-N'` still anchors to the seed (the
    *   value passed to `glaze.color()`), not the base.
+   * - When the base was created via the structured form (with explicit
+   *   `hue`/`saturation`/`lightness`), it is resolved at full range
+   *   (`lightLightness: false`) for the linking math — ensuring the
+   *   contrast/lightness anchor matches the input lightness, not the
+   *   windowed output. The base's own `.resolve()` output is unaffected.
    *
    * The base token's `.resolve()` is called lazily on first resolve and
    * its result is captured by reference; later mutations to the base's
@@ -428,46 +543,17 @@ interface GlazeColorOverrides {
   name?: string;
 }
 /**
- * Per-call lightness-window overrides for `glaze.color()`. Mirrors
- * the field names from `GlazeConfig`.
- *
- * Defaults for `glaze.color()` vary by input form, and both fields are
- * snapshotted from `globalConfig` at color-creation time so later
- * `glaze.configure()` calls don't retroactively change already-created
- * tokens (and `token.export()` round-trips byte-for-byte):
+ * Object input for `glaze.color()` that carries a raw color value plus
+ * optional color overrides in the same object.
  *
- * - **String inputs** (`'#1a1a1a'`, `'rgb(...)'`, `'okhsl(...)'`, ...):
- *   - `lightLightness: false` — preserve input exactly.
- *   - `darkLightness: [globalConfig.darkLightness[0], 100]` — extended
- *     dark window so the auto-mode dark variant can Möbius-invert all
- *     the way up to white.
- *
- * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
- *   - `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
- * field's default while overriding the other, restate the default
- * explicitly.
+ * ```ts
+ * glaze.color({ from: '#1a1a2e', base: bg, contrast: 'AA' })
+ * glaze.color({ from: { r: 38, g: 252, b: 178 }, lightness: '+10' })
+ * ```
  */
-interface GlazeColorScaling {
-  /**
-   * 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
-   * create time: extended `[globalConfig.darkLightness[0], 100]` for
-   * string inputs, plain `globalConfig.darkLightness` for object /
-   * tuple / structured inputs. Pass `false` to preserve input
-   * lightness in dark mode too.
-   */
-  darkLightness?: false | [number, number];
+interface GlazeFromInput extends GlazeColorOverrides {
+  /** The source color value. Accepts the same forms as a bare `GlazeColorValue`. */
+  from: GlazeColorValue;
 }
 /** Options for `GlazeColorToken.css()`. */
 interface GlazeColorCssOptions {
@@ -503,7 +589,7 @@ interface GlazeColorToken {
   css(options: GlazeColorCssOptions): GlazeCssResult;
   /**
    * Serialize the token as a JSON-safe object. Captures the original
-   * input value, overrides, and scaling so it can be rehydrated via
+   * input value, overrides, and config so it can be rehydrated via
    * `glaze.colorFrom(...)`. `base` is recursively serialized.
    */
   export(): GlazeColorTokenExport;
@@ -515,8 +601,8 @@ interface GlazeColorToken {
 interface GlazeColorTokenExport {
   /**
    * Discriminator for the source overload that created the token.
-   * - `'value'`: created via `glaze.color(value, overrides?, scaling?)`.
-   * - `'structured'`: created via `glaze.color({ hue, saturation, ... }, scaling?)`.
+   * - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
+   * - `'structured'`: created via `glaze.color({ hue, saturation, ... })`.
    */
   form: 'value' | 'structured';
   /** Original input. For `form: 'value'` this is the raw `GlazeColorValue`; for `form: 'structured'` this is the structured input. */
@@ -526,8 +612,14 @@ interface GlazeColorTokenExport {
    * serialized. Only present for `form: 'value'`.
    */
   overrides?: GlazeColorOverridesExport;
-  /** Lightness scaling override, if any. */
-  scaling?: GlazeColorScaling;
+  /**
+   * Effective config snapshot at creation time — captures the merged
+   * result of the global config + any per-call override at the moment
+   * the token was created. Only fields that differ from their
+   * post-merge defaults are present. Used by `glaze.colorFrom()` to
+   * reproduce deterministic behavior across `configure()` calls.
+   */
+  config?: GlazeConfigOverride;
 }
 /**
  * Serializable shape of a structured `glaze.color({...})` input.
@@ -610,6 +702,8 @@ interface GlazeExtendOptions {
   hue?: number;
   saturation?: number;
   colors?: ColorMap;
+  /** Config override for the child theme. Merged with the parent's override. */
+  config?: GlazeConfigOverride;
 }
 interface GlazeTokenOptions {
   /** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
@@ -708,25 +802,30 @@ type PaletteInput = Record<string, GlazeTheme>;
 /**
  * Create a single-hue glaze theme.
  *
+ * An optional `config` override can be supplied to customize the resolve
+ * behavior for this theme (lightness windows, dark curve, etc.). The
+ * override is **merged over the live global config at resolve time** —
+ * the theme still reacts to later `configure()` calls for fields it
+ * didn't override.
+ *
  * @example
  * ```ts
- * const primary = glaze({ hue: 280, saturation: 80 });
- * // or shorthand:
  * const primary = glaze(280, 80);
+ * // or shorthand:
+ * const primary = glaze({ hue: 280, saturation: 80 });
+ * // with config override:
+ * const raw = glaze(280, 80, { lightLightness: false });
  * ```
  */
 declare function glaze(hueOrOptions: number | {
   hue: number;
   saturation: number;
-}, saturation?: number): GlazeTheme;
+}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
   var from: (data: GlazeThemeExport) => GlazeTheme;
-  var color: {
-    (input: GlazeColorInput, scaling?: GlazeColorScaling): GlazeColorToken;
-    (value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: GlazeColorScaling): GlazeColorToken;
-  };
+  var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
   var fromHex: (hex: string) => GlazeTheme;
@@ -831,5 +930,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 FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorScaling, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type MinContrast, type MixColorDef, type OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type LightnessWindow, type MinContrast, type MixColorDef, type OkhslColor, type OklchColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type RgbColor, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.cts.map