@tenphi/glaze 0.0.0-snapshot.7c1fc7d → 0.0.0-snapshot.7f3fb7f

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +157 -3
  2. package/dist/index.cjs +261 -57
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +80 -5
  5. package/dist/index.d.mts +80 -5
  6. package/dist/index.mjs +260 -58
  7. package/dist/index.mjs.map +1 -1
  8. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -6,6 +6,7 @@
6
6
  * against a base color. Used by glaze when resolving dependent colors
7
7
  * with `contrast`.
8
8
  */
9
+ type LinearRgb = [number, number, number];
9
10
  type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
10
11
  type MinContrast$1 = number | ContrastPreset;
11
12
  interface FindLightnessForContrastOptions {
@@ -42,6 +43,39 @@ declare function resolveMinContrast(value: MinContrast$1): number;
42
43
  * against a base color, staying as close to `preferredLightness` as possible.
43
44
  */
44
45
  declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
46
+ interface FindValueForMixContrastOptions {
47
+ /** Preferred mix parameter (0–1). */
48
+ preferredValue: number;
49
+ /** Base color as linear sRGB. */
50
+ baseLinearRgb: LinearRgb;
51
+ /** Target color as linear sRGB. */
52
+ targetLinearRgb: LinearRgb;
53
+ /** WCAG contrast target. */
54
+ contrast: MinContrast$1;
55
+ /**
56
+ * Compute the luminance of the mixed color at parameter t.
57
+ * For opaque: luminance of OKHSL-interpolated color.
58
+ * For transparent: luminance of alpha-composited color over base.
59
+ */
60
+ luminanceAtValue: (t: number) => number;
61
+ /** Convergence threshold. Default: 1e-4. */
62
+ epsilon?: number;
63
+ /** Maximum binary-search iterations per branch. Default: 20. */
64
+ maxIterations?: number;
65
+ }
66
+ interface FindValueForMixContrastResult {
67
+ /** Chosen mix parameter (0–1). */
68
+ value: number;
69
+ /** Achieved WCAG contrast ratio. */
70
+ contrast: number;
71
+ /** Whether the target was reached. */
72
+ met: boolean;
73
+ }
74
+ /**
75
+ * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
76
+ * target against a base color, staying as close to `preferredValue` as possible.
77
+ */
78
+ declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
45
79
  //#endregion
46
80
  //#region src/types.d.ts
47
81
  /** A value or [normal, high-contrast] pair. */
@@ -144,7 +178,41 @@ interface ShadowColorDef {
144
178
  /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
145
179
  tuning?: ShadowTuning;
146
180
  }
147
- type ColorDef = RegularColorDef | ShadowColorDef;
181
+ interface MixColorDef {
182
+ type: 'mix';
183
+ /** Background/base color name — the "from" color. */
184
+ base: string;
185
+ /** Target color name — the "to" color to mix toward. */
186
+ target: string;
187
+ /**
188
+ * Mix ratio 0–100 (0 = pure base, 100 = pure target).
189
+ * In 'transparent' blend mode, this controls the opacity of the target.
190
+ * Supports [normal, highContrast] pair.
191
+ */
192
+ value: HCPair<number>;
193
+ /**
194
+ * Blending mode. Default: 'opaque'.
195
+ * - 'opaque': produces a solid color by interpolating base and target.
196
+ * - 'transparent': produces the target color with alpha = value/100.
197
+ */
198
+ blend?: 'opaque' | 'transparent';
199
+ /**
200
+ * Interpolation color space for opaque blending. Default: 'okhsl'.
201
+ * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
202
+ * - 'srgb': linear sRGB interpolation, matches browser compositing.
203
+ *
204
+ * Ignored for 'transparent' blend (always composites in linear sRGB).
205
+ */
206
+ space?: 'okhsl' | 'srgb';
207
+ /**
208
+ * Minimum WCAG contrast between the base and the resulting color.
209
+ * In 'opaque' mode, adjusts the mix ratio to meet contrast.
210
+ * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
211
+ * Supports [normal, highContrast] pair.
212
+ */
213
+ contrast?: HCPair<MinContrast>;
214
+ }
215
+ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
148
216
  type ColorMap = Record<string, ColorDef>;
149
217
  /** Resolved color for a single scheme variant. */
150
218
  interface ResolvedColorVariant {
@@ -394,6 +462,10 @@ declare namespace glaze {
394
462
  * computation for WCAG 2 contrast calculations, and multi-format output
395
463
  * (okhsl, rgb, hsl, oklch).
396
464
  */
465
+ /**
466
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
467
+ */
468
+ declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
397
469
  /**
398
470
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
399
471
  * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
@@ -413,9 +485,11 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
413
485
  */
414
486
  declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
415
487
  /**
416
- * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
488
+ * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
489
+ * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
490
+ * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
417
491
  */
418
- declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
492
+ declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
419
493
  /**
420
494
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
421
495
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
@@ -432,7 +506,8 @@ declare function parseHex(hex: string): [number, number, number] | null;
432
506
  */
433
507
  declare function formatOkhsl(h: number, s: number, l: number): string;
434
508
  /**
435
- * Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
509
+ * Format OKHSL values as a CSS `rgb(R G B)` string.
510
+ * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
436
511
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
437
512
  */
438
513
  declare function formatRgb(h: number, s: number, l: number): string;
@@ -447,5 +522,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
447
522
  */
448
523
  declare function formatOklch(h: number, s: number, l: number): string;
449
524
  //#endregion
450
- export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, 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 OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
525
+ 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 };
451
526
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -6,6 +6,7 @@
6
6
  * against a base color. Used by glaze when resolving dependent colors
7
7
  * with `contrast`.
8
8
  */
9
+ type LinearRgb = [number, number, number];
9
10
  type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
10
11
  type MinContrast$1 = number | ContrastPreset;
11
12
  interface FindLightnessForContrastOptions {
@@ -42,6 +43,39 @@ declare function resolveMinContrast(value: MinContrast$1): number;
42
43
  * against a base color, staying as close to `preferredLightness` as possible.
43
44
  */
44
45
  declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
46
+ interface FindValueForMixContrastOptions {
47
+ /** Preferred mix parameter (0–1). */
48
+ preferredValue: number;
49
+ /** Base color as linear sRGB. */
50
+ baseLinearRgb: LinearRgb;
51
+ /** Target color as linear sRGB. */
52
+ targetLinearRgb: LinearRgb;
53
+ /** WCAG contrast target. */
54
+ contrast: MinContrast$1;
55
+ /**
56
+ * Compute the luminance of the mixed color at parameter t.
57
+ * For opaque: luminance of OKHSL-interpolated color.
58
+ * For transparent: luminance of alpha-composited color over base.
59
+ */
60
+ luminanceAtValue: (t: number) => number;
61
+ /** Convergence threshold. Default: 1e-4. */
62
+ epsilon?: number;
63
+ /** Maximum binary-search iterations per branch. Default: 20. */
64
+ maxIterations?: number;
65
+ }
66
+ interface FindValueForMixContrastResult {
67
+ /** Chosen mix parameter (0–1). */
68
+ value: number;
69
+ /** Achieved WCAG contrast ratio. */
70
+ contrast: number;
71
+ /** Whether the target was reached. */
72
+ met: boolean;
73
+ }
74
+ /**
75
+ * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
76
+ * target against a base color, staying as close to `preferredValue` as possible.
77
+ */
78
+ declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
45
79
  //#endregion
46
80
  //#region src/types.d.ts
47
81
  /** A value or [normal, high-contrast] pair. */
@@ -144,7 +178,41 @@ interface ShadowColorDef {
144
178
  /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
145
179
  tuning?: ShadowTuning;
146
180
  }
147
- type ColorDef = RegularColorDef | ShadowColorDef;
181
+ interface MixColorDef {
182
+ type: 'mix';
183
+ /** Background/base color name — the "from" color. */
184
+ base: string;
185
+ /** Target color name — the "to" color to mix toward. */
186
+ target: string;
187
+ /**
188
+ * Mix ratio 0–100 (0 = pure base, 100 = pure target).
189
+ * In 'transparent' blend mode, this controls the opacity of the target.
190
+ * Supports [normal, highContrast] pair.
191
+ */
192
+ value: HCPair<number>;
193
+ /**
194
+ * Blending mode. Default: 'opaque'.
195
+ * - 'opaque': produces a solid color by interpolating base and target.
196
+ * - 'transparent': produces the target color with alpha = value/100.
197
+ */
198
+ blend?: 'opaque' | 'transparent';
199
+ /**
200
+ * Interpolation color space for opaque blending. Default: 'okhsl'.
201
+ * - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
202
+ * - 'srgb': linear sRGB interpolation, matches browser compositing.
203
+ *
204
+ * Ignored for 'transparent' blend (always composites in linear sRGB).
205
+ */
206
+ space?: 'okhsl' | 'srgb';
207
+ /**
208
+ * Minimum WCAG contrast between the base and the resulting color.
209
+ * In 'opaque' mode, adjusts the mix ratio to meet contrast.
210
+ * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
211
+ * Supports [normal, highContrast] pair.
212
+ */
213
+ contrast?: HCPair<MinContrast>;
214
+ }
215
+ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
148
216
  type ColorMap = Record<string, ColorDef>;
149
217
  /** Resolved color for a single scheme variant. */
150
218
  interface ResolvedColorVariant {
@@ -394,6 +462,10 @@ declare namespace glaze {
394
462
  * computation for WCAG 2 contrast calculations, and multi-format output
395
463
  * (okhsl, rgb, hsl, oklch).
396
464
  */
465
+ /**
466
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
467
+ */
468
+ declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
397
469
  /**
398
470
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
399
471
  * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
@@ -413,9 +485,11 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
413
485
  */
414
486
  declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
415
487
  /**
416
- * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
488
+ * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
489
+ * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
490
+ * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
417
491
  */
418
- declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
492
+ declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
419
493
  /**
420
494
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
421
495
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
@@ -432,7 +506,8 @@ declare function parseHex(hex: string): [number, number, number] | null;
432
506
  */
433
507
  declare function formatOkhsl(h: number, s: number, l: number): string;
434
508
  /**
435
- * Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
509
+ * Format OKHSL values as a CSS `rgb(R G B)` string.
510
+ * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
436
511
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
437
512
  */
438
513
  declare function formatRgb(h: number, s: number, l: number): string;
@@ -447,5 +522,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
447
522
  */
448
523
  declare function formatOklch(h: number, s: number, l: number): string;
449
524
  //#endregion
450
- export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, 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 OkhslColor, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
525
+ 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 };
451
526
  //# sourceMappingURL=index.d.mts.map