@solid-primitives/utils 6.4.1 → 7.0.0-next.1
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.
- package/LICENSE +71 -0
- package/README.md +276 -0
- package/dist/colors/helpers.d.ts +46 -0
- package/dist/colors/helpers.js +895 -0
- package/dist/colors/index.d.ts +4 -0
- package/dist/colors/index.js +4 -0
- package/dist/colors/intl.d.ts +54 -0
- package/dist/colors/intl.js +68 -0
- package/dist/colors/manipulation.d.ts +144 -0
- package/dist/colors/manipulation.js +278 -0
- package/dist/colors/types.d.ts +77 -0
- package/dist/colors/types.js +14 -0
- package/dist/index.d.ts +106 -21
- package/dist/index.js +113 -19
- package/dist/types.d.ts +4 -2
- package/package.json +84 -3
|
@@ -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 {};
|