@tenphi/glaze 0.0.0-snapshot.07e5d83

package/dist/index.d.mts

@@ -0,0 +1,525 @@
+//#region src/contrast-solver.d.ts
+/**
+ * OKHSL Contrast Solver
+ *
+ * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
+ * against a base color. Used by glaze when resolving dependent colors
+ * with `contrast`.
+ */
+type LinearRgb = [number, number, number];
+type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
+type MinContrast$1 = number | ContrastPreset;
+interface FindLightnessForContrastOptions {
+  /** Hue of the candidate color (0–360). */
+  hue: number;
+  /** Saturation of the candidate color (0–1). */
+  saturation: number;
+  /** Preferred lightness of the candidate (0–1). */
+  preferredLightness: number;
+  /** Base/reference color as linear sRGB (channels may be outside 0–1 before clamp). */
+  baseLinearRgb: [number, number, number];
+  /** WCAG contrast ratio target floor. */
+  contrast: MinContrast$1;
+  /** Search bounds for lightness. Default: [0, 1]. */
+  lightnessRange?: [number, number];
+  /** Convergence threshold. Default: 1e-4. */
+  epsilon?: number;
+  /** Maximum binary-search iterations per branch. Default: 14. */
+  maxIterations?: number;
+}
+interface FindLightnessForContrastResult {
+  /** Chosen lightness in 0–1. */
+  lightness: number;
+  /** Achieved WCAG contrast ratio. */
+  contrast: number;
+  /** Whether the target was reached. */
+  met: boolean;
+  /** Which branch was selected. */
+  branch: 'lighter' | 'darker' | 'preferred';
+}
+declare function resolveMinContrast(value: MinContrast$1): number;
+/**
+ * Find the OKHSL lightness that satisfies a WCAG 2 contrast target
+ * against a base color, staying as close to `preferredLightness` as possible.
+ */
+declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
+interface FindValueForMixContrastOptions {
+  /** Preferred mix parameter (0–1). */
+  preferredValue: number;
+  /** Base color as linear sRGB. */
+  baseLinearRgb: LinearRgb;
+  /** Target color as linear sRGB. */
+  targetLinearRgb: LinearRgb;
+  /** WCAG contrast target. */
+  contrast: MinContrast$1;
+  /**
+   * Compute the luminance of the mixed color at parameter t.
+   * For opaque: luminance of OKHSL-interpolated color.
+   * For transparent: luminance of alpha-composited color over base.
+   */
+  luminanceAtValue: (t: number) => number;
+  /** Convergence threshold. Default: 1e-4. */
+  epsilon?: number;
+  /** Maximum binary-search iterations per branch. Default: 20. */
+  maxIterations?: number;
+}
+interface FindValueForMixContrastResult {
+  /** Chosen mix parameter (0–1). */
+  value: number;
+  /** Achieved WCAG contrast ratio. */
+  contrast: number;
+  /** Whether the target was reached. */
+  met: boolean;
+}
+/**
+ * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
+ * target against a base color, staying as close to `preferredValue` as possible.
+ */
+declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
+//#endregion
+//#region src/types.d.ts
+/** A value or [normal, high-contrast] pair. */
+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';
+/**
+ * Controls which scheme variants are generated in the export.
+ * Light is always included (it's the default).
+ */
+interface GlazeOutputModes {
+  /** Include dark scheme variants. Default: true. */
+  dark?: boolean;
+  /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
+  highContrast?: boolean;
+}
+/** Hex color string for DX hints. Runtime validation in `parseHex()`. */
+type HexColor = `#${string}`;
+/** Direct OKHSL color input. */
+interface OkhslColor {
+  h: number;
+  s: number;
+  l: number;
+}
+interface RegularColorDef {
+  /**
+   * 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). */
+  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;
+  /** WCAG contrast ratio floor against the base color. */
+  contrast?: HCPair<MinContrast>;
+  /** Adaptation mode. Default: 'auto'. */
+  mode?: AdaptationMode;
+  /**
+   * Fixed opacity (0–1).
+   * Output includes alpha in the CSS value.
+   * Does not affect contrast resolution — a semi-transparent color
+   * has no fixed perceived lightness, so `contrast` and `opacity`
+   * should not be combined (a console.warn is emitted).
+   */
+  opacity?: number;
+}
+/** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
+interface ShadowTuning {
+  /** Fraction of fg saturation kept in pigment (0-1). Default: 0.18. */
+  saturationFactor?: number;
+  /** Upper clamp on pigment saturation (0-1). Default: 0.25. */
+  maxSaturation?: number;
+  /** Multiplier for bg lightness → pigment lightness. Default: 0.25. */
+  lightnessFactor?: number;
+  /** [min, max] clamp for pigment lightness (0-1). Default: [0.05, 0.20]. */
+  lightnessBounds?: [number, number];
+  /**
+   * Target minimum gap between pigment lightness and bg lightness (0-1).
+   * Default: 0.05.
+   */
+  minGapTarget?: number;
+  /** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
+  alphaMax?: number;
+  /**
+   * Blend weight (0-1) pulling pigment hue toward bg hue.
+   * 0 = pure fg hue, 1 = pure bg hue. Default: 0.2.
+   */
+  bgHueBlend?: number;
+}
+interface ShadowColorDef {
+  type: 'shadow';
+  /**
+   * Background color name — the surface the shadow sits on.
+   * Must reference a non-shadow color in the same theme.
+   */
+  bg: string;
+  /**
+   * Foreground color name for tinting and intensity modulation.
+   * Must reference a non-shadow color in the same theme.
+   * Omit for achromatic shadow at full user-specified intensity.
+   */
+  fg?: string;
+  /**
+   * Shadow intensity, 0-100.
+   * Supports [normal, highContrast] pair.
+   */
+  intensity: HCPair<number>;
+  /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
+  tuning?: ShadowTuning;
+}
+interface MixColorDef {
+  type: 'mix';
+  /** Background/base color name — the "from" color. */
+  base: string;
+  /** Target color name — the "to" color to mix toward. */
+  target: string;
+  /**
+   * Mix ratio 0–100 (0 = pure base, 100 = pure target).
+   * In 'transparent' blend mode, this controls the opacity of the target.
+   * Supports [normal, highContrast] pair.
+   */
+  value: HCPair<number>;
+  /**
+   * Blending mode. Default: 'opaque'.
+   * - 'opaque': produces a solid color by interpolating base and target.
+   * - 'transparent': produces the target color with alpha = value/100.
+   */
+  blend?: 'opaque' | 'transparent';
+  /**
+   * Interpolation color space for opaque blending. Default: 'okhsl'.
+   * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
+   * - 'srgb': linear sRGB interpolation, matches browser compositing.
+   *
+   * Ignored for 'transparent' blend (always composites in linear sRGB).
+   */
+  space?: 'okhsl' | 'srgb';
+  /**
+   * Minimum WCAG contrast between the base and the resulting color.
+   * In 'opaque' mode, adjusts the mix ratio to meet contrast.
+   * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
+   * Supports [normal, highContrast] pair.
+   */
+  contrast?: HCPair<MinContrast>;
+}
+type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
+type ColorMap = Record<string, ColorDef>;
+/** Resolved color for a single scheme variant. */
+interface ResolvedColorVariant {
+  /** OKHSL hue (0–360). */
+  h: number;
+  /** OKHSL saturation (0–1). */
+  s: number;
+  /** OKHSL lightness (0–1). */
+  l: number;
+  /** Opacity (0–1). Default: 1. */
+  alpha: number;
+}
+/** Fully resolved color across all scheme variants. */
+interface ResolvedColor {
+  name: string;
+  light: ResolvedColorVariant;
+  dark: ResolvedColorVariant;
+  lightContrast: ResolvedColorVariant;
+  darkContrast: ResolvedColorVariant;
+  /** Adaptation mode. Present only for regular colors, omitted for shadows. */
+  mode?: AdaptationMode;
+}
+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];
+  /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
+  darkDesaturation?: number;
+  /** State alias names for token export. */
+  states?: {
+    dark?: string;
+    highContrast?: string;
+  };
+  /** Which scheme variants to include in exports. Default: both true. */
+  modes?: GlazeOutputModes;
+  /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
+  shadowTuning?: ShadowTuning;
+}
+interface GlazeConfigResolved {
+  lightLightness: [number, number];
+  darkLightness: [number, number];
+  darkDesaturation: number;
+  states: {
+    dark: string;
+    highContrast: string;
+  };
+  modes: Required<GlazeOutputModes>;
+  shadowTuning?: ShadowTuning;
+}
+/** Serialized theme configuration (no resolved values). */
+interface GlazeThemeExport {
+  hue: number;
+  saturation: number;
+  colors: ColorMap;
+}
+/** Input for `glaze.shadow()` standalone factory. */
+interface GlazeShadowInput {
+  /** Background color — hex string or OKHSL { h, s (0-1), l (0-1) }. */
+  bg: HexColor | OkhslColor;
+  /** Foreground color for tinting + intensity modulation. */
+  fg?: HexColor | OkhslColor;
+  /** Intensity 0-100. */
+  intensity: number;
+  tuning?: ShadowTuning;
+}
+/** Input for `glaze.color()` standalone factory. */
+interface GlazeColorInput {
+  hue: number;
+  saturation: number;
+  lightness: HCPair<number>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+}
+/** Return type for `glaze.color()`. */
+interface GlazeColorToken {
+  /** Resolve the color across all scheme variants. */
+  resolve(): ResolvedColor;
+  /** Export as a flat token map (no color name key). */
+  token(options?: GlazeTokenOptions): Record<string, string>;
+  /**
+   * Export as a tasty style-to-state binding (no color name key).
+   * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
+   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   */
+  tasty(options?: GlazeTokenOptions): Record<string, string>;
+  /** Export as a flat JSON map (no color name key). */
+  json(options?: GlazeJsonOptions): Record<string, string>;
+}
+interface GlazeTheme {
+  /** The hue seed (0–360). */
+  readonly hue: number;
+  /** The saturation seed (0–100). */
+  readonly saturation: number;
+  /** Add/replace colors (additive merge with existing definitions). */
+  colors(defs: ColorMap): void;
+  /** Get a color definition by name. */
+  color(name: string): ColorDef | undefined;
+  /** Set a single color definition. */
+  color(name: string, def: ColorDef): void;
+  /** Remove one or more color definitions. */
+  remove(names: string | string[]): void;
+  /** Check if a color is defined. */
+  has(name: string): boolean;
+  /** List all defined color names. */
+  list(): string[];
+  /** Clear all color definitions. */
+  reset(): void;
+  /** Export the theme configuration as a JSON-safe object. */
+  export(): GlazeThemeExport;
+  /** Create a child theme inheriting all color definitions. */
+  extend(options: GlazeExtendOptions): GlazeTheme;
+  /** Resolve all colors and return the result map. */
+  resolve(): Map<string, ResolvedColor>;
+  /**
+   * Export as a flat token map grouped by scheme variant.
+   *
+   * ```ts
+   * theme.tokens()
+   * // → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
+   * ```
+   */
+  tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
+  /**
+   * Export as tasty style-to-state bindings.
+   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Spread into component styles or register as a recipe via `configure({ recipes })`.
+   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   */
+  tasty(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;
+  saturation?: number;
+  colors?: ColorMap;
+}
+interface GlazeTokenOptions {
+  /** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
+  prefix?: boolean | Record<string, string>;
+  /** Override state aliases for this export. */
+  states?: {
+    dark?: string;
+    highContrast?: string;
+  };
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /** Output color format. Default: 'okhsl'. */
+  format?: GlazeColorFormat;
+}
+interface GlazeJsonOptions {
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /** 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 flat token map grouped by scheme variant.
+   *
+   * ```ts
+   * palette.tokens({ prefix: true })
+   * // → { light: { 'primary-surface': 'okhsl(...)' }, dark: { 'primary-surface': 'okhsl(...)' } }
+   * ```
+   */
+  tokens(options?: GlazeJsonOptions & {
+    prefix?: boolean | Record<string, string>;
+  }): Record<string, Record<string, string>>;
+  /**
+   * Export all themes as tasty style-to-state bindings.
+   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Spread into component styles or register as a recipe via `configure({ recipes })`.
+   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   */
+  tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
+  /** Export all themes as plain JSON. */
+  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
+type PaletteInput = Record<string, GlazeTheme>;
+/**
+ * Create a single-hue glaze theme.
+ *
+ * @example
+ * ```ts
+ * const primary = glaze({ hue: 280, saturation: 80 });
+ * // or shorthand:
+ * const primary = glaze(280, 80);
+ * ```
+ */
+declare function glaze(hueOrOptions: number | {
+  hue: number;
+  saturation: number;
+}, saturation?: number): GlazeTheme;
+declare namespace glaze {
+  var configure: (config: GlazeConfig) => void;
+  var palette: (themes: PaletteInput) => {
+    tokens(options?: GlazeJsonOptions & {
+      prefix?: boolean | Record<string, string>;
+    }): Record<string, Record<string, string>>;
+    tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
+    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;
+  var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
+  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
+  var fromHex: (hex: string) => GlazeTheme;
+  var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
+  var getConfig: () => GlazeConfigResolved;
+  var resetConfig: () => void;
+}
+//#endregion
+//#region src/okhsl-color-math.d.ts
+/**
+ * OKHSL color math primitives for the glaze theme generator.
+ *
+ * Provides bidirectional OKHSL ↔ sRGB conversion, relative luminance
+ * computation for WCAG 2 contrast calculations, and multi-format output
+ * (okhsl, rgb, hsl, oklch).
+ */
+/**
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
+ */
+declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
+/**
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
+ * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
+ */
+declare function okhslToLinearSrgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * Compute relative luminance Y from linear sRGB channels.
+ * Per WCAG 2: Y = 0.2126·R + 0.7152·G + 0.0722·B
+ */
+declare function relativeLuminanceFromLinearRgb(rgb: [number, number, number]): number;
+/**
+ * WCAG 2 contrast ratio from two luminance values.
+ */
+declare function contrastRatioFromLuminance(yA: number, yB: number): number;
+/**
+ * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
+ */
+declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
+ * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
+ * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
+ */
+declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
+/**
+ * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
+ * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+ */
+declare function srgbToOkhsl(rgb: [number, number, number]): [number, number, number];
+/**
+ * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
+ * Returns null if the string is not a valid hex color.
+ */
+declare function parseHex(hex: string): [number, number, number] | null;
+/**
+ * Format OKHSL values as a CSS `okhsl(H S% L%)` string.
+ * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ */
+declare function formatOkhsl(h: number, s: number, l: number): string;
+/**
+ * Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
+ * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ */
+declare function formatRgb(h: number, s: number, l: number): string;
+/**
+ * Format OKHSL values as a CSS `hsl(H S% L%)` string.
+ * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ */
+declare function formatHsl(h: number, s: number, l: number): string;
+/**
+ * Format OKHSL values as a CSS `oklch(L C H)` string.
+ * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
+ */
+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 GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, 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, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+//# sourceMappingURL=index.d.mts.map