@tenphi/glaze 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,298 @@
+//#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 `ensureContrast`.
+ */
+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];
+  /** Ensures the WCAG contrast ratio meets a target floor. */
+  ensureContrast: 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;
+//#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';
+/** 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;
+}
+interface ColorDef {
+  /** Lightness in the light scheme (0–100). Root color. */
+  l?: HCPair<number>;
+  /** Saturation factor applied to the seed saturation (0–1, default: 1). */
+  sat?: number;
+  /** 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>;
+  /** Adaptation mode. Default: 'auto'. */
+  mode?: AdaptationMode;
+}
+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;
+}
+/** Fully resolved color across all scheme variants. */
+interface ResolvedColor {
+  name: string;
+  light: ResolvedColorVariant;
+  dark: ResolvedColorVariant;
+  lightContrast: ResolvedColorVariant;
+  darkContrast: ResolvedColorVariant;
+  mode: AdaptationMode;
+}
+interface GlazeConfig {
+  /** Dark scheme lightness window [lo, hi]. Default: [10, 90]. */
+  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;
+}
+interface GlazeConfigResolved {
+  darkLightness: [number, number];
+  darkDesaturation: number;
+  states: {
+    dark: string;
+    highContrast: string;
+  };
+  modes: Required<GlazeOutputModes>;
+}
+/** Serialized theme configuration (no resolved values). */
+interface GlazeThemeExport {
+  hue: number;
+  saturation: number;
+  colors: ColorMap;
+}
+/** Input for `glaze.color()` standalone factory. */
+interface GlazeColorInput {
+  hue: number;
+  saturation: number;
+  l: HCPair<number>;
+  sat?: 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 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 token map. */
+  tokens(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
+  /** Export as plain JSON. */
+  json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
+}
+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 GlazePalette {
+  /** Export all themes as a combined token map. */
+  tokens(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>>>;
+}
+//#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?: GlazeTokenOptions): Record<string, Record<string, string>>;
+    json(options?: GlazeJsonOptions & {
+      prefix?: boolean | Record<string, string>;
+    }): Record<string, Record<string, Record<string, string>>>;
+  };
+  var from: (data: GlazeThemeExport) => GlazeTheme;
+  var color: (input: GlazeColorInput) => GlazeColorToken;
+  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 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];
+/**
+ * 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 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 fractional 0–255 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 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 };
+//# sourceMappingURL=index.d.mts.map