@solid-primitives/utils 6.4.0 → 7.0.0-next.0

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.
@@ -0,0 +1,4 @@
1
+ export * from "./intl.js";
2
+ export * from "./types.js";
3
+ export * from "./helpers.js";
4
+ export * from "./manipulation.js";
@@ -0,0 +1,4 @@
1
+ export * from "./intl.js";
2
+ export * from "./types.js";
3
+ export * from "./helpers.js";
4
+ export * from "./manipulation.js";
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Default English translations for color channel names, descriptors, and hue families.
3
+ * Pass this object (or a translated equivalent) to {@link Color.getColorName} and
4
+ * {@link Color.getHueName} to produce human-readable, accessible color labels.
5
+ *
6
+ * @example
7
+ * ```ts
8
+ * import { parseColor, COLOR_INTL_TRANSLATIONS } from "@solid-primitives/utils/colors";
9
+ *
10
+ * const color = parseColor("hsl(220 60% 49%)");
11
+ * color.getColorName(COLOR_INTL_TRANSLATIONS); // "dark vibrant blue"
12
+ * color.getHueName(COLOR_INTL_TRANSLATIONS); // "blue"
13
+ * ```
14
+ */
15
+ export declare const COLOR_INTL_TRANSLATIONS: {
16
+ hue: string;
17
+ saturation: string;
18
+ lightness: string;
19
+ brightness: string;
20
+ red: string;
21
+ green: string;
22
+ blue: string;
23
+ alpha: string;
24
+ colorName: (lightness: string, chroma: string, hue: string) => string;
25
+ transparentColorName: (lightness: string, chroma: string, hue: string, percentTransparent: string) => string;
26
+ "very dark": string;
27
+ dark: string;
28
+ light: string;
29
+ "very light": string;
30
+ pale: string;
31
+ grayish: string;
32
+ vibrant: string;
33
+ black: string;
34
+ white: string;
35
+ gray: string;
36
+ pink: string;
37
+ "pink red": string;
38
+ "red orange": string;
39
+ brown: string;
40
+ orange: string;
41
+ "orange yellow": string;
42
+ "brown yellow": string;
43
+ yellow: string;
44
+ "yellow green": string;
45
+ "green cyan": string;
46
+ cyan: string;
47
+ "cyan blue": string;
48
+ "blue purple": string;
49
+ purple: string;
50
+ "purple magenta": string;
51
+ magenta: string;
52
+ "magenta pink": string;
53
+ };
54
+ export type ColorIntlTranslations = typeof COLOR_INTL_TRANSLATIONS;
@@ -0,0 +1,68 @@
1
+ /*
2
+ * Portions of this file are based on code from Kobalte.
3
+ * MIT License, Copyright Fabien Marie-Louise.
4
+ *
5
+ * Credits to the Kobalte team:
6
+ * https://github.com/kobaltedev/kobalte/tree/main/packages/core/src/colors
7
+ */
8
+ /**
9
+ * Default English translations for color channel names, descriptors, and hue families.
10
+ * Pass this object (or a translated equivalent) to {@link Color.getColorName} and
11
+ * {@link Color.getHueName} to produce human-readable, accessible color labels.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import { parseColor, COLOR_INTL_TRANSLATIONS } from "@solid-primitives/utils/colors";
16
+ *
17
+ * const color = parseColor("hsl(220 60% 49%)");
18
+ * color.getColorName(COLOR_INTL_TRANSLATIONS); // "dark vibrant blue"
19
+ * color.getHueName(COLOR_INTL_TRANSLATIONS); // "blue"
20
+ * ```
21
+ */
22
+ export const COLOR_INTL_TRANSLATIONS = {
23
+ // Channel names
24
+ hue: "Hue",
25
+ saturation: "Saturation",
26
+ lightness: "Lightness",
27
+ brightness: "Brightness",
28
+ red: "Red",
29
+ green: "Green",
30
+ blue: "Blue",
31
+ alpha: "Alpha",
32
+ // Full color name composers
33
+ colorName: (lightness, chroma, hue) => `${lightness} ${chroma} ${hue}`,
34
+ transparentColorName: (lightness, chroma, hue, percentTransparent) => `${lightness} ${chroma} ${hue}, ${percentTransparent} transparent`,
35
+ // Lightness descriptors
36
+ "very dark": "very dark",
37
+ dark: "dark",
38
+ light: "light",
39
+ "very light": "very light",
40
+ // Chroma descriptors
41
+ pale: "pale",
42
+ grayish: "grayish",
43
+ vibrant: "vibrant",
44
+ // Achromatic
45
+ black: "black",
46
+ white: "white",
47
+ gray: "gray",
48
+ // Hue families (in OKLCH hue order).
49
+ // Note: "red", "green", "blue" are intentionally absent — the channel name
50
+ // entries above ("Red", "Green", "Blue") serve as their hue family labels too.
51
+ pink: "pink",
52
+ "pink red": "pink red",
53
+ "red orange": "red orange",
54
+ brown: "brown",
55
+ orange: "orange",
56
+ "orange yellow": "orange yellow",
57
+ "brown yellow": "brown yellow",
58
+ yellow: "yellow",
59
+ "yellow green": "yellow green",
60
+ "green cyan": "green cyan",
61
+ cyan: "cyan",
62
+ "cyan blue": "cyan blue",
63
+ "blue purple": "blue purple",
64
+ purple: "purple",
65
+ "purple magenta": "purple magenta",
66
+ magenta: "magenta",
67
+ "magenta pink": "magenta pink",
68
+ };
@@ -0,0 +1,144 @@
1
+ import type { Color, ColorFormat } from "./types.js";
2
+ /**
3
+ * Like {@link parseColor} but returns `undefined` instead of throwing for invalid input.
4
+ *
5
+ * @example
6
+ * ```ts
7
+ * tryParseColor("#3264C8") // Color
8
+ * tryParseColor("nope") // undefined
9
+ * ```
10
+ */
11
+ export declare function tryParseColor(value: string): Color | undefined;
12
+ /**
13
+ * Returns `true` if `value` is a parseable color string.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * isValidColor("#3264C8") // true
18
+ * isValidColor("nope") // false
19
+ * ```
20
+ */
21
+ export declare function isValidColor(value: string): boolean;
22
+ /**
23
+ * Detects the format of a color string without parsing it.
24
+ * Returns `undefined` for strings that do not match any known format.
25
+ *
26
+ * The returned format reflects the **syntax** of the string (e.g. `"rgb"` for
27
+ * `rgb(...)` even if an alpha channel is present via slash notation).
28
+ *
29
+ * @example
30
+ * ```ts
31
+ * detectColorFormat("#3264C8") // "hex"
32
+ * detectColorFormat("#3264C8FF") // "hexa"
33
+ * detectColorFormat("rgb(50, 100, 200)") // "rgb"
34
+ * detectColorFormat("hsla(220, 60%, 49%, 0.5)") // "hsla"
35
+ * detectColorFormat("nope") // undefined
36
+ * ```
37
+ */
38
+ export declare function detectColorFormat(value: string): ColorFormat | undefined;
39
+ /**
40
+ * Returns a new color with lightness increased by `amount` (0–1 ratio = percentage points).
41
+ * Operates in HSL space; the returned color is in HSL.
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * lighten(parseColor("hsl(220, 60%, 50%)"), 0.1).getChannelValue("lightness") // 60
46
+ * ```
47
+ */
48
+ export declare function lighten(color: Color, amount: number): Color;
49
+ /**
50
+ * Returns a new color with lightness decreased by `amount` (0–1 ratio = percentage points).
51
+ * Operates in HSL space; the returned color is in HSL.
52
+ */
53
+ export declare function darken(color: Color, amount: number): Color;
54
+ /**
55
+ * Returns a new color with saturation increased by `amount` (0–1 ratio = percentage points).
56
+ * Operates in HSL space; the returned color is in HSL.
57
+ */
58
+ export declare function saturate(color: Color, amount: number): Color;
59
+ /**
60
+ * Returns a new color with saturation decreased by `amount` (0–1 ratio = percentage points).
61
+ * Operates in HSL space; the returned color is in HSL.
62
+ */
63
+ export declare function desaturate(color: Color, amount: number): Color;
64
+ /**
65
+ * Returns the complementary color (hue rotated 180°), preserving saturation, lightness, and alpha.
66
+ * The returned color is in HSL.
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * complement(parseColor("hsl(60, 50%, 50%)")).getChannelValue("hue") // 240
71
+ * ```
72
+ */
73
+ export declare function complement(color: Color): Color;
74
+ /**
75
+ * Mixes two colors in RGB space at the given `ratio` (0 = fully `a`, 1 = fully `b`).
76
+ * Alpha is also interpolated. The returned color is in RGB.
77
+ *
78
+ * @example
79
+ * ```ts
80
+ * mix(parseColor("#000000"), parseColor("#ffffff")).toString("hex") // "#808080"
81
+ * mix(parseColor("#000000"), parseColor("#ffffff"), 0.25).toString("hex") // "#404040"
82
+ * ```
83
+ */
84
+ export declare function mix(a: Color, b: Color, ratio?: number): Color;
85
+ /**
86
+ * Returns the WCAG 2.1 contrast ratio between two colors (1–21).
87
+ * The order of arguments does not matter.
88
+ *
89
+ * - Black on white: `21`
90
+ * - Same color: `1`
91
+ *
92
+ * @example
93
+ * ```ts
94
+ * contrastRatio(parseColor("#000"), parseColor("#fff")) // 21
95
+ * ```
96
+ */
97
+ export declare function contrastRatio(a: Color, b: Color): number;
98
+ /**
99
+ * Returns whether the contrast between `foreground` and `background` meets the
100
+ * specified WCAG 2.1 conformance level and text size.
101
+ *
102
+ * | Level | Normal text | Large text (≥18pt / ≥14pt bold) |
103
+ * |-------|-------------|----------------------------------|
104
+ * | AA | 4.5 : 1 | 3 : 1 |
105
+ * | AAA | 7 : 1 | 4.5 : 1 |
106
+ *
107
+ * @example
108
+ * ```ts
109
+ * isReadable(parseColor("#fff"), parseColor("#000")) // true (AA, normal)
110
+ * isReadable(parseColor("#fff"), parseColor("#000"), "AAA") // true
111
+ * isReadable(parseColor("#777"), parseColor("#fff"), "AAA") // false
112
+ * ```
113
+ */
114
+ export declare function isReadable(foreground: Color, background: Color, level?: "AA" | "AAA", size?: "normal" | "large"): boolean;
115
+ /**
116
+ * Returns an array of `steps` colors linearly interpolated in RGB space between
117
+ * `from` and `to`. The first element is `from`, the last is `to`.
118
+ *
119
+ * @throws if `steps` is not a finite integer >= 2.
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * colorScale(parseColor("#000"), parseColor("#fff"), 3)
124
+ * // [#000000, #808080, #FFFFFF]
125
+ * ```
126
+ */
127
+ export declare function colorScale(from: Color, to: Color, steps: number): Color[];
128
+ /**
129
+ * Returns an array of `steps` colors interpolated in OKLCH space between `from` and `to`.
130
+ * OKLCH is a perceptually uniform color space, so the steps appear more evenly distributed
131
+ * to the human eye than a plain RGB scale.
132
+ *
133
+ * Hue interpolation takes the shortest arc around the color wheel.
134
+ * Alpha is linearly interpolated. The returned colors are in RGB.
135
+ *
136
+ * @throws if `steps` is not a finite integer >= 2.
137
+ *
138
+ * @example
139
+ * ```ts
140
+ * // A scale from red to blue that passes through purple rather than through green
141
+ * perceptualColorScale(parseColor("hsl(0, 80%, 50%)"), parseColor("hsl(240, 80%, 50%)"), 5)
142
+ * ```
143
+ */
144
+ export declare function perceptualColorScale(from: Color, to: Color, steps: number): Color[];
@@ -0,0 +1,278 @@
1
+ /*
2
+ * Portions of this file incorporate color science from the following sources:
3
+ *
4
+ * OKLab/OKLCH color space by Björn Ottosson.
5
+ * MIT License, Copyright Björn Ottosson.
6
+ * https://bottosson.github.io/posts/oklab/
7
+ *
8
+ * WCAG 2.1 relative luminance and contrast ratio formulas.
9
+ * W3C Web Content Accessibility Guidelines 2.1, Copyright W3C.
10
+ * https://www.w3.org/TR/WCAG21/#contrast-minimum
11
+ */
12
+ import { clamp } from "../index.js";
13
+ import { colorToOKLCH, normalizeHue, parseColor } from "./helpers.js";
14
+ // ─── Safe parsing ─────────────────────────────────────────────────────────────
15
+ /**
16
+ * Like {@link parseColor} but returns `undefined` instead of throwing for invalid input.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * tryParseColor("#3264C8") // Color
21
+ * tryParseColor("nope") // undefined
22
+ * ```
23
+ */
24
+ export function tryParseColor(value) {
25
+ try {
26
+ return parseColor(value);
27
+ }
28
+ catch {
29
+ return undefined;
30
+ }
31
+ }
32
+ /**
33
+ * Returns `true` if `value` is a parseable color string.
34
+ *
35
+ * @example
36
+ * ```ts
37
+ * isValidColor("#3264C8") // true
38
+ * isValidColor("nope") // false
39
+ * ```
40
+ */
41
+ export function isValidColor(value) {
42
+ return tryParseColor(value) !== undefined;
43
+ }
44
+ /**
45
+ * Detects the format of a color string without parsing it.
46
+ * Returns `undefined` for strings that do not match any known format.
47
+ *
48
+ * The returned format reflects the **syntax** of the string (e.g. `"rgb"` for
49
+ * `rgb(...)` even if an alpha channel is present via slash notation).
50
+ *
51
+ * @example
52
+ * ```ts
53
+ * detectColorFormat("#3264C8") // "hex"
54
+ * detectColorFormat("#3264C8FF") // "hexa"
55
+ * detectColorFormat("rgb(50, 100, 200)") // "rgb"
56
+ * detectColorFormat("hsla(220, 60%, 49%, 0.5)") // "hsla"
57
+ * detectColorFormat("nope") // undefined
58
+ * ```
59
+ */
60
+ export function detectColorFormat(value) {
61
+ const s = value.trim();
62
+ if (/^#[\da-f]+$/i.test(s)) {
63
+ if (s.length === 4 || s.length === 7)
64
+ return "hex";
65
+ if (s.length === 5 || s.length === 9)
66
+ return "hexa";
67
+ }
68
+ if (/^rgba?\(/i.test(s))
69
+ return /^rgba\(/i.test(s) ? "rgba" : "rgb";
70
+ if (/^hsla?\(/i.test(s))
71
+ return /^hsla\(/i.test(s) ? "hsla" : "hsl";
72
+ if (/^hsba?\(/i.test(s))
73
+ return /^hsba\(/i.test(s) ? "hsba" : "hsb";
74
+ return undefined;
75
+ }
76
+ // ─── Manipulation ─────────────────────────────────────────────────────────────
77
+ /**
78
+ * Returns a new color with lightness increased by `amount` (0–1 ratio = percentage points).
79
+ * Operates in HSL space; the returned color is in HSL.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * lighten(parseColor("hsl(220, 60%, 50%)"), 0.1).getChannelValue("lightness") // 60
84
+ * ```
85
+ */
86
+ export function lighten(color, amount) {
87
+ const hsl = color.toFormat("hsl");
88
+ return hsl.withChannelValue("lightness", clamp(hsl.getChannelValue("lightness") + amount * 100, 0, 100));
89
+ }
90
+ /**
91
+ * Returns a new color with lightness decreased by `amount` (0–1 ratio = percentage points).
92
+ * Operates in HSL space; the returned color is in HSL.
93
+ */
94
+ export function darken(color, amount) {
95
+ return lighten(color, -amount);
96
+ }
97
+ /**
98
+ * Returns a new color with saturation increased by `amount` (0–1 ratio = percentage points).
99
+ * Operates in HSL space; the returned color is in HSL.
100
+ */
101
+ export function saturate(color, amount) {
102
+ const hsl = color.toFormat("hsl");
103
+ return hsl.withChannelValue("saturation", clamp(hsl.getChannelValue("saturation") + amount * 100, 0, 100));
104
+ }
105
+ /**
106
+ * Returns a new color with saturation decreased by `amount` (0–1 ratio = percentage points).
107
+ * Operates in HSL space; the returned color is in HSL.
108
+ */
109
+ export function desaturate(color, amount) {
110
+ return saturate(color, -amount);
111
+ }
112
+ /**
113
+ * Returns the complementary color (hue rotated 180°), preserving saturation, lightness, and alpha.
114
+ * The returned color is in HSL.
115
+ *
116
+ * @example
117
+ * ```ts
118
+ * complement(parseColor("hsl(60, 50%, 50%)")).getChannelValue("hue") // 240
119
+ * ```
120
+ */
121
+ export function complement(color) {
122
+ const hsl = color.toFormat("hsl");
123
+ return hsl.withChannelValue("hue", normalizeHue(hsl.getChannelValue("hue") + 180));
124
+ }
125
+ /**
126
+ * Mixes two colors in RGB space at the given `ratio` (0 = fully `a`, 1 = fully `b`).
127
+ * Alpha is also interpolated. The returned color is in RGB.
128
+ *
129
+ * @example
130
+ * ```ts
131
+ * mix(parseColor("#000000"), parseColor("#ffffff")).toString("hex") // "#808080"
132
+ * mix(parseColor("#000000"), parseColor("#ffffff"), 0.25).toString("hex") // "#404040"
133
+ * ```
134
+ */
135
+ export function mix(a, b, ratio = 0.5) {
136
+ const r = Number.isFinite(ratio) ? clamp(ratio, 0, 1) : 0.5;
137
+ const ra = a.toFormat("rgb");
138
+ const rb = b.toFormat("rgb");
139
+ const lerp = (x, y) => x + (y - x) * r;
140
+ return ra
141
+ .withChannelValue("red", Math.round(lerp(ra.getChannelValue("red"), rb.getChannelValue("red"))))
142
+ .withChannelValue("green", Math.round(lerp(ra.getChannelValue("green"), rb.getChannelValue("green"))))
143
+ .withChannelValue("blue", Math.round(lerp(ra.getChannelValue("blue"), rb.getChannelValue("blue"))))
144
+ .withChannelValue("alpha", lerp(ra.getChannelValue("alpha"), rb.getChannelValue("alpha")));
145
+ }
146
+ // ─── Accessibility ────────────────────────────────────────────────────────────
147
+ /** WCAG 2.1 relative luminance. Alpha is ignored (assumes opaque rendering). */
148
+ function relativeLuminance(color) {
149
+ const rgb = color.toFormat("rgb");
150
+ const linearize = (v) => {
151
+ const c = v / 255;
152
+ return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
153
+ };
154
+ return (0.2126 * linearize(rgb.getChannelValue("red")) +
155
+ 0.7152 * linearize(rgb.getChannelValue("green")) +
156
+ 0.0722 * linearize(rgb.getChannelValue("blue")));
157
+ }
158
+ /**
159
+ * Returns the WCAG 2.1 contrast ratio between two colors (1–21).
160
+ * The order of arguments does not matter.
161
+ *
162
+ * - Black on white: `21`
163
+ * - Same color: `1`
164
+ *
165
+ * @example
166
+ * ```ts
167
+ * contrastRatio(parseColor("#000"), parseColor("#fff")) // 21
168
+ * ```
169
+ */
170
+ export function contrastRatio(a, b) {
171
+ const l1 = relativeLuminance(a);
172
+ const l2 = relativeLuminance(b);
173
+ return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
174
+ }
175
+ /**
176
+ * Returns whether the contrast between `foreground` and `background` meets the
177
+ * specified WCAG 2.1 conformance level and text size.
178
+ *
179
+ * | Level | Normal text | Large text (≥18pt / ≥14pt bold) |
180
+ * |-------|-------------|----------------------------------|
181
+ * | AA | 4.5 : 1 | 3 : 1 |
182
+ * | AAA | 7 : 1 | 4.5 : 1 |
183
+ *
184
+ * @example
185
+ * ```ts
186
+ * isReadable(parseColor("#fff"), parseColor("#000")) // true (AA, normal)
187
+ * isReadable(parseColor("#fff"), parseColor("#000"), "AAA") // true
188
+ * isReadable(parseColor("#777"), parseColor("#fff"), "AAA") // false
189
+ * ```
190
+ */
191
+ export function isReadable(foreground, background, level = "AA", size = "normal") {
192
+ const ratio = contrastRatio(foreground, background);
193
+ if (level === "AAA")
194
+ return ratio >= (size === "large" ? 4.5 : 7);
195
+ return ratio >= (size === "large" ? 3 : 4.5);
196
+ }
197
+ // ─── Color scales ─────────────────────────────────────────────────────────────
198
+ /**
199
+ * Returns an array of `steps` colors linearly interpolated in RGB space between
200
+ * `from` and `to`. The first element is `from`, the last is `to`.
201
+ *
202
+ * @throws if `steps` is not a finite integer >= 2.
203
+ *
204
+ * @example
205
+ * ```ts
206
+ * colorScale(parseColor("#000"), parseColor("#fff"), 3)
207
+ * // [#000000, #808080, #FFFFFF]
208
+ * ```
209
+ */
210
+ export function colorScale(from, to, steps) {
211
+ if (!Number.isFinite(steps) || !Number.isInteger(steps) || steps < 2)
212
+ throw new Error("colorScale: steps must be a finite integer >= 2");
213
+ return Array.from({ length: steps }, (_, i) => mix(from, to, i / (steps - 1)));
214
+ }
215
+ /** Interpolate between two OKLCH triplets, taking the shortest hue path. */
216
+ function lerpOKLCH([l1, c1, h1], [l2, c2, h2], t) {
217
+ let dh = h2 - h1;
218
+ if (dh > 180)
219
+ dh -= 360;
220
+ if (dh < -180)
221
+ dh += 360;
222
+ return [l1 + (l2 - l1) * t, c1 + (c2 - c1) * t, normalizeHue(h1 + dh * t)];
223
+ }
224
+ /**
225
+ * Convert OKLCH back to an RGB `Color` via the OKLab → LMS → linear sRGB → sRGB pipeline.
226
+ * Out-of-gamut values are clamped to [0, 1] before gamma encoding.
227
+ * Coefficients from https://bottosson.github.io/posts/oklab/
228
+ */
229
+ function oklchToColor(l, c, h, alpha) {
230
+ const hRad = (h * Math.PI) / 180;
231
+ const a = c * Math.cos(hRad);
232
+ const b = c * Math.sin(hRad);
233
+ // OKLab → cube-root LMS
234
+ const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
235
+ const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
236
+ const s_ = l - 0.0894841775 * a - 1.291485548 * b;
237
+ // Cube to LMS, then combined (M1_inv × XYZ→sRGB) matrix to linear sRGB
238
+ const ll = l_ ** 3;
239
+ const mm = m_ ** 3;
240
+ const ss = s_ ** 3;
241
+ const r_lin = +4.0767416621 * ll - 3.3077115913 * mm + 0.2309699292 * ss;
242
+ const g_lin = -1.2684380046 * ll + 2.6097574011 * mm - 0.3413193965 * ss;
243
+ const b_lin = -0.0041960863 * ll - 0.7034186147 * mm + 1.7076147010 * ss;
244
+ const toSRGB = (v) => {
245
+ const clamped = clamp(v, 0, 1);
246
+ return Math.round((clamped <= 0.0031308 ? 12.92 * clamped : 1.055 * clamped ** (1 / 2.4) - 0.055) * 255);
247
+ };
248
+ return parseColor(`rgba(${toSRGB(r_lin)}, ${toSRGB(g_lin)}, ${toSRGB(b_lin)}, ${alpha})`);
249
+ }
250
+ /**
251
+ * Returns an array of `steps` colors interpolated in OKLCH space between `from` and `to`.
252
+ * OKLCH is a perceptually uniform color space, so the steps appear more evenly distributed
253
+ * to the human eye than a plain RGB scale.
254
+ *
255
+ * Hue interpolation takes the shortest arc around the color wheel.
256
+ * Alpha is linearly interpolated. The returned colors are in RGB.
257
+ *
258
+ * @throws if `steps` is not a finite integer >= 2.
259
+ *
260
+ * @example
261
+ * ```ts
262
+ * // A scale from red to blue that passes through purple rather than through green
263
+ * perceptualColorScale(parseColor("hsl(0, 80%, 50%)"), parseColor("hsl(240, 80%, 50%)"), 5)
264
+ * ```
265
+ */
266
+ export function perceptualColorScale(from, to, steps) {
267
+ if (!Number.isFinite(steps) || !Number.isInteger(steps) || steps < 2)
268
+ throw new Error("perceptualColorScale: steps must be a finite integer >= 2");
269
+ const fromOKLCH = colorToOKLCH(from);
270
+ const toOKLCH = colorToOKLCH(to);
271
+ const alphaFrom = from.getChannelValue("alpha");
272
+ const alphaTo = to.getChannelValue("alpha");
273
+ return Array.from({ length: steps }, (_, i) => {
274
+ const t = i / (steps - 1);
275
+ const [l, c, h] = lerpOKLCH(fromOKLCH, toOKLCH, t);
276
+ return oklchToColor(l, c, h, alphaFrom + (alphaTo - alphaFrom) * t);
277
+ });
278
+ }
@@ -0,0 +1,77 @@
1
+ import type { ColorIntlTranslations } from "./intl.js";
2
+ /** Supported color string formats. Formats without an `a` suffix treat alpha as fully opaque. */
3
+ export type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
4
+ /** The three supported color spaces. */
5
+ export type ColorSpace = "rgb" | "hsl" | "hsb";
6
+ /** Individual channel names across all supported color spaces. */
7
+ export type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
8
+ /** Maps x/y/z axes to {@link ColorChannel} names for 2D color gradient pickers. */
9
+ export type ColorAxes = {
10
+ xChannel: ColorChannel;
11
+ yChannel: ColorChannel;
12
+ zChannel: ColorChannel;
13
+ };
14
+ /** Numeric constraints for a single color channel, used to drive sliders and steppers. */
15
+ export interface ColorChannelRange {
16
+ /** Minimum value of the channel. */
17
+ minValue: number;
18
+ /** Maximum value of the channel. */
19
+ maxValue: number;
20
+ /** Increment/decrement step (e.g. arrow key). */
21
+ step: number;
22
+ /** Larger increment/decrement step (e.g. page-up/down key). */
23
+ pageSize: number;
24
+ }
25
+ /** Represents an immutable color value. All mutation methods return a new `Color` instance. */
26
+ export interface Color {
27
+ /** Returns a new `Color` converted to `format`. */
28
+ toFormat(format: ColorFormat): Color;
29
+ /**
30
+ * Serializes the color to a CSS string.
31
+ * Defaults to `"css"` which produces the most browser-compatible form for each space
32
+ * (`rgb(...)`, `hsla(...)`, etc.).
33
+ */
34
+ toString(format?: ColorFormat | "css"): string;
35
+ /** Returns a deep clone of this color. */
36
+ clone(): Color;
37
+ /** Returns the RGB integer representation (`0xRRGGBB`), ignoring alpha. */
38
+ toHexInt(): number;
39
+ /**
40
+ * Returns the numeric value for `channel`.
41
+ * @throws if `channel` is not part of this color's space.
42
+ */
43
+ getChannelValue(channel: ColorChannel): number;
44
+ /**
45
+ * Returns a new `Color` with `channel` set to `value`.
46
+ * @throws if `channel` is not part of this color's space.
47
+ */
48
+ withChannelValue(channel: ColorChannel, value: number): Color;
49
+ /** Returns the {@link ColorChannelRange} for `channel` in this color space. */
50
+ getChannelRange(channel: ColorChannel): ColorChannelRange;
51
+ /** Returns a localized label for `channel` (e.g. `"Red"`, `"Saturation"`). */
52
+ getChannelName(channel: ColorChannel, translations: ColorIntlTranslations): string;
53
+ /** Returns `Intl.NumberFormatOptions` appropriate for displaying this channel's value. */
54
+ getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions;
55
+ /** Returns the channel value formatted as a locale-aware string (e.g. `"50%"`, `"220°"`). */
56
+ formatChannelValue(channel: ColorChannel): string;
57
+ /** Returns the color space this color lives in. */
58
+ getColorSpace(): ColorSpace;
59
+ /**
60
+ * Resolves the x/y/z channel assignment for a 2D color area picker.
61
+ * Pass `xChannel` and/or `yChannel` to fix specific axes; the remaining
62
+ * channel is inferred as the z axis.
63
+ */
64
+ getColorSpaceAxes(xyChannels: {
65
+ xChannel?: ColorChannel;
66
+ yChannel?: ColorChannel;
67
+ }): ColorAxes;
68
+ /** Returns the three channel names for this color's space, in display order. */
69
+ getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
70
+ /**
71
+ * Returns a human-readable color name derived from OKLCH analysis
72
+ * (e.g. `"dark vibrant blue"`, `"pale cyan, 20% transparent"`).
73
+ */
74
+ getColorName(translations: ColorIntlTranslations): string;
75
+ /** Returns just the hue family name (e.g. `"blue"`, `"orange yellow"`). */
76
+ getHueName(translations: ColorIntlTranslations): string;
77
+ }
@@ -0,0 +1,14 @@
1
+ /*
2
+ * Portions of this file are based on code from Kobalte.
3
+ * MIT License, Copyright Fabien Marie-Louise.
4
+ *
5
+ * Credits to the Kobalte team:
6
+ * https://github.com/kobaltedev/kobalte/tree/main/packages/core/src/colors
7
+ *
8
+ * Which in turn is based on code from React Spectrum.
9
+ * Apache License Version 2.0, Copyright 2020 Adobe.
10
+ *
11
+ * Credits to the React Spectrum team:
12
+ * https://github.com/adobe/react-spectrum/blob/68e305768cb829bab7b9836dded593bd731259f3/packages/%40react-types/color/src/index.d.ts
13
+ */
14
+ export {};