@solid-primitives/utils 7.0.0-next.4 → 7.0.0-next.8
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/README.md +13 -0
- package/dist/colors/helpers.d.ts +40 -44
- package/dist/colors/helpers.js +7 -10
- package/dist/colors/index.js +1 -1
- package/dist/colors/intl.d.ts +15 -18
- package/dist/colors/intl.js +1 -2
- package/dist/colors/manipulation.d.ts +130 -134
- package/dist/colors/manipulation.js +1 -2
- package/dist/colors/types.d.ts +24 -28
- package/dist/immutable/array.d.ts +105 -108
- package/dist/immutable/array.js +1 -2
- package/dist/immutable/copy.d.ts +21 -24
- package/dist/immutable/copy.js +1 -2
- package/dist/immutable/index.d.ts +2 -2
- package/dist/immutable/index.js +2 -2
- package/dist/immutable/number.d.ts +7 -10
- package/dist/immutable/number.js +1 -2
- package/dist/immutable/object.d.ts +51 -53
- package/dist/immutable/object.js +1 -2
- package/dist/immutable/types.d.ts +5 -7
- package/dist/immutable/update.d.ts +22 -26
- package/dist/immutable/update.js +1 -2
- package/dist/index.d.ts +248 -231
- package/dist/index.js +31 -6
- package/dist/types.d.ts +53 -56
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -155,6 +155,19 @@ const [count, setCount, data] = wrapSetter(
|
|
|
155
155
|
);
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
+
## createServerSafeSignal
|
|
159
|
+
|
|
160
|
+
`createSignal` on the client; a plain mutable box on the server.
|
|
161
|
+
|
|
162
|
+
Solid 2 flags a setter that runs during a server render (`SERVER_WRITE` — the write is inert today and throws in a later release): server render is pure, state enters through async sources. Primitives that hold _interactive_ state (a cursor, a toggle, a controlled value) have no async source, so on the server they keep a plain value instead. Reads and updater-form writes behave the same within a request; nothing touches the reactive graph. The signal is still _created_ on the server so hydration ids stay aligned with the client — it is just never read or written there.
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
import { createServerSafeSignal } from "@solid-primitives/utils";
|
|
166
|
+
|
|
167
|
+
const [cursor, setCursor] = createServerSafeSignal<string | undefined>(undefined);
|
|
168
|
+
setCursor("b"); // a signal write in the browser, a plain assignment on the server
|
|
169
|
+
```
|
|
170
|
+
|
|
158
171
|
## Color utilities
|
|
159
172
|
|
|
160
173
|
Multi-format color parsing, conversion, and accessibility naming — available as a separate subpath so you only pay for what you use.
|
package/dist/colors/helpers.d.ts
CHANGED
|
@@ -1,51 +1,47 @@
|
|
|
1
1
|
/* @ts-self-types="./helpers.d.ts" */
|
|
2
2
|
import { Color, ColorChannel, ColorSpace } from "./types.js";
|
|
3
|
-
|
|
4
|
-
//#region src/colors/helpers.d.ts
|
|
5
3
|
/**
|
|
6
|
-
* Parses a color string into a {@link Color} object.
|
|
7
|
-
*
|
|
8
|
-
* Supported formats:
|
|
9
|
-
* - **Hex**: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
|
|
10
|
-
* - **RGB**: `rgb(r g b)`, `rgb(r, g, b)`, `rgb(r g b / a)`, `rgba(r, g, b, a)`
|
|
11
|
-
* - **HSL**: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
|
|
12
|
-
* - **HSB**: `hsb(h, s%, b%)`, `hsba(h, s%, b%, a)`
|
|
13
|
-
*
|
|
14
|
-
* @throws if the string does not match any supported format.
|
|
15
|
-
*
|
|
16
|
-
* @example
|
|
17
|
-
* ```ts
|
|
18
|
-
* const color = parseColor("#3264C8");
|
|
19
|
-
* color.toString("hsl"); // "hsl(220 60% 49.02%)"
|
|
20
|
-
* ```
|
|
21
|
-
*/
|
|
22
|
-
declare function parseColor(value: string): Color;
|
|
4
|
+
* Parses a color string into a {@link Color} object.
|
|
5
|
+
*
|
|
6
|
+
* Supported formats:
|
|
7
|
+
* - **Hex**: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
|
|
8
|
+
* - **RGB**: `rgb(r g b)`, `rgb(r, g, b)`, `rgb(r g b / a)`, `rgba(r, g, b, a)`
|
|
9
|
+
* - **HSL**: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
|
|
10
|
+
* - **HSB**: `hsb(h, s%, b%)`, `hsba(h, s%, b%, a)`
|
|
11
|
+
*
|
|
12
|
+
* @throws if the string does not match any supported format.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* const color = parseColor("#3264C8");
|
|
17
|
+
* color.toString("hsl"); // "hsl(220 60% 49.02%)"
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export declare function parseColor(value: string): Color;
|
|
23
21
|
/**
|
|
24
|
-
* Accepts either a color string or an existing {@link Color} and always returns a `Color`.
|
|
25
|
-
* Useful for normalizing props that accept both forms.
|
|
26
|
-
*/
|
|
27
|
-
declare function normalizeColor(v: string | Color): Color;
|
|
22
|
+
* Accepts either a color string or an existing {@link Color} and always returns a `Color`.
|
|
23
|
+
* Useful for normalizing props that accept both forms.
|
|
24
|
+
*/
|
|
25
|
+
export declare function normalizeColor(v: string | Color): Color;
|
|
28
26
|
/**
|
|
29
|
-
* Returns the ordered channel triple for a given color space.
|
|
30
|
-
*
|
|
31
|
-
* - `"rgb"` → `["red", "green", "blue"]`
|
|
32
|
-
* - `"hsl"` → `["hue", "saturation", "lightness"]`
|
|
33
|
-
* - `"hsb"` → `["hue", "saturation", "brightness"]`
|
|
34
|
-
*/
|
|
35
|
-
declare function getColorChannels(colorSpace: ColorSpace): [ColorChannel, ColorChannel, ColorChannel];
|
|
27
|
+
* Returns the ordered channel triple for a given color space.
|
|
28
|
+
*
|
|
29
|
+
* - `"rgb"` → `["red", "green", "blue"]`
|
|
30
|
+
* - `"hsl"` → `["hue", "saturation", "lightness"]`
|
|
31
|
+
* - `"hsb"` → `["hue", "saturation", "brightness"]`
|
|
32
|
+
*/
|
|
33
|
+
export declare function getColorChannels(colorSpace: ColorSpace): [ColorChannel, ColorChannel, ColorChannel];
|
|
36
34
|
/**
|
|
37
|
-
* Normalizes a hue angle to the range `[0, 360]`.
|
|
38
|
-
* Exactly `360` is kept as-is so that a full-circle endpoint stays distinct from `0`.
|
|
39
|
-
*/
|
|
40
|
-
declare function normalizeHue(hue: number): number;
|
|
35
|
+
* Normalizes a hue angle to the range `[0, 360]`.
|
|
36
|
+
* Exactly `360` is kept as-is so that a full-circle endpoint stays distinct from `0`.
|
|
37
|
+
*/
|
|
38
|
+
export declare function normalizeHue(hue: number): number;
|
|
41
39
|
/**
|
|
42
|
-
* Converts any {@link Color} to OKLCH `[L, C, H]` — a perceptually uniform space
|
|
43
|
-
* where L is perceived lightness (0–1), C is chroma (≥ 0), and H is a hue angle (0–360).
|
|
44
|
-
*
|
|
45
|
-
* Full pipeline: sRGB bytes → linear sRGB (gamma-expand) → CIE XYZ D65 → OKLab → OKLCH.
|
|
46
|
-
*
|
|
47
|
-
* @see https://www.w3.org/TR/css-color-4/#color-conversion-code
|
|
48
|
-
*/
|
|
49
|
-
declare function colorToOKLCH(color: Color): [l: number, c: number, h: number];
|
|
50
|
-
//#endregion
|
|
51
|
-
export { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor };
|
|
40
|
+
* Converts any {@link Color} to OKLCH `[L, C, H]` — a perceptually uniform space
|
|
41
|
+
* where L is perceived lightness (0–1), C is chroma (≥ 0), and H is a hue angle (0–360).
|
|
42
|
+
*
|
|
43
|
+
* Full pipeline: sRGB bytes → linear sRGB (gamma-expand) → CIE XYZ D65 → OKLab → OKLCH.
|
|
44
|
+
*
|
|
45
|
+
* @see https://www.w3.org/TR/css-color-4/#color-conversion-code
|
|
46
|
+
*/
|
|
47
|
+
export declare function colorToOKLCH(color: Color): [l: number, c: number, h: number];
|
package/dist/colors/helpers.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/* @ts-self-types="./helpers.d.ts" */
|
|
2
2
|
import { clamp } from "../index.js";
|
|
3
|
-
|
|
3
|
+
// src/colors/helpers.ts
|
|
4
4
|
/**
|
|
5
5
|
* Parses a color string into a {@link Color} object.
|
|
6
6
|
*
|
|
@@ -194,8 +194,10 @@ var Color = class {
|
|
|
194
194
|
let hueName = OKLCH_HUES[i][1];
|
|
195
195
|
const [nextHue, nextHueName] = OKLCH_HUES[i + 1] || [360, "pink"];
|
|
196
196
|
if (h >= hue && h < nextHue) {
|
|
197
|
-
if (hueName === "orange")
|
|
198
|
-
|
|
197
|
+
if (hueName === "orange") {
|
|
198
|
+
if (l < ORANGE_LIGHTNESS_THRESHOLD) hueName = "brown";
|
|
199
|
+
else l = l - ORANGE_LIGHTNESS_THRESHOLD + MAX_DARK_LIGHTNESS;
|
|
200
|
+
}
|
|
199
201
|
if (h > hue + (nextHue - hue) / 2 && hueName !== nextHueName) hueName = `${hueName} ${nextHueName}`;
|
|
200
202
|
else if (hueName === "yellow" && l < YELLOW_GREEN_LIGHTNESS_THRESHOLD) hueName = "yellow green";
|
|
201
203
|
return [translations[hueName], l];
|
|
@@ -322,9 +324,7 @@ var RGBColor = class RGBColor extends Color {
|
|
|
322
324
|
case green:
|
|
323
325
|
hue = (blue - red) / chroma + 2;
|
|
324
326
|
break;
|
|
325
|
-
case blue:
|
|
326
|
-
hue = (red - green) / chroma + 4;
|
|
327
|
-
break;
|
|
327
|
+
case blue: hue = (red - green) / chroma + 4;
|
|
328
328
|
}
|
|
329
329
|
hue /= 6;
|
|
330
330
|
}
|
|
@@ -356,9 +356,7 @@ var RGBColor = class RGBColor extends Color {
|
|
|
356
356
|
case green:
|
|
357
357
|
hue = (blue - red) / chroma + 2;
|
|
358
358
|
break;
|
|
359
|
-
default:
|
|
360
|
-
hue = (red - green) / chroma + 4;
|
|
361
|
-
break;
|
|
359
|
+
default: hue = (red - green) / chroma + 4;
|
|
362
360
|
}
|
|
363
361
|
hue /= 6;
|
|
364
362
|
}
|
|
@@ -816,5 +814,4 @@ function toFixedNumber(value, digits, base = 10) {
|
|
|
816
814
|
const pow = base ** digits;
|
|
817
815
|
return Math.round(value * pow) / pow;
|
|
818
816
|
}
|
|
819
|
-
//#endregion
|
|
820
817
|
export { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor };
|
package/dist/colors/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/* @ts-self-types="./index.d.ts" */
|
|
2
|
-
import { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor } from "./helpers.js";
|
|
3
2
|
import { COLOR_INTL_TRANSLATIONS } from "./intl.js";
|
|
3
|
+
import { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor } from "./helpers.js";
|
|
4
4
|
import { colorScale, complement, contrastRatio, darken, desaturate, detectColorFormat, isReadable, isValidColor, lighten, mix, perceptualColorScale, saturate, tryParseColor } from "./manipulation.js";
|
|
5
5
|
export { COLOR_INTL_TRANSLATIONS, colorScale, colorToOKLCH, complement, contrastRatio, darken, desaturate, detectColorFormat, getColorChannels, isReadable, isValidColor, lighten, mix, normalizeColor, normalizeHue, parseColor, perceptualColorScale, saturate, tryParseColor };
|
package/dist/colors/intl.d.ts
CHANGED
|
@@ -1,20 +1,19 @@
|
|
|
1
1
|
/* @ts-self-types="./intl.d.ts" */
|
|
2
|
-
//#region src/colors/intl.d.ts
|
|
3
2
|
/**
|
|
4
|
-
* Default English translations for color channel names, descriptors, and hue families.
|
|
5
|
-
* Pass this object (or a translated equivalent) to {@link Color.getColorName} and
|
|
6
|
-
* {@link Color.getHueName} to produce human-readable, accessible color labels.
|
|
7
|
-
*
|
|
8
|
-
* @example
|
|
9
|
-
* ```ts
|
|
10
|
-
* import { parseColor, COLOR_INTL_TRANSLATIONS } from "@solid-primitives/utils/colors";
|
|
11
|
-
*
|
|
12
|
-
* const color = parseColor("hsl(220 60% 49%)");
|
|
13
|
-
* color.getColorName(COLOR_INTL_TRANSLATIONS); // "dark vibrant blue"
|
|
14
|
-
* color.getHueName(COLOR_INTL_TRANSLATIONS); // "blue"
|
|
15
|
-
* ```
|
|
16
|
-
*/
|
|
17
|
-
declare const COLOR_INTL_TRANSLATIONS: {
|
|
3
|
+
* Default English translations for color channel names, descriptors, and hue families.
|
|
4
|
+
* Pass this object (or a translated equivalent) to {@link Color.getColorName} and
|
|
5
|
+
* {@link Color.getHueName} to produce human-readable, accessible color labels.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { parseColor, COLOR_INTL_TRANSLATIONS } from "@solid-primitives/utils/colors";
|
|
10
|
+
*
|
|
11
|
+
* const color = parseColor("hsl(220 60% 49%)");
|
|
12
|
+
* color.getColorName(COLOR_INTL_TRANSLATIONS); // "dark vibrant blue"
|
|
13
|
+
* color.getHueName(COLOR_INTL_TRANSLATIONS); // "blue"
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
16
|
+
export declare const COLOR_INTL_TRANSLATIONS: {
|
|
18
17
|
hue: string;
|
|
19
18
|
saturation: string;
|
|
20
19
|
lightness: string;
|
|
@@ -53,6 +52,4 @@ declare const COLOR_INTL_TRANSLATIONS: {
|
|
|
53
52
|
magenta: string;
|
|
54
53
|
"magenta pink": string;
|
|
55
54
|
};
|
|
56
|
-
type ColorIntlTranslations = typeof COLOR_INTL_TRANSLATIONS;
|
|
57
|
-
//#endregion
|
|
58
|
-
export { COLOR_INTL_TRANSLATIONS, ColorIntlTranslations };
|
|
55
|
+
export type ColorIntlTranslations = typeof COLOR_INTL_TRANSLATIONS;
|
package/dist/colors/intl.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/* @ts-self-types="./intl.d.ts" */
|
|
2
|
-
|
|
2
|
+
// src/colors/intl.ts
|
|
3
3
|
/**
|
|
4
4
|
* Default English translations for color channel names, descriptors, and hue families.
|
|
5
5
|
* Pass this object (or a translated equivalent) to {@link Color.getColorName} and
|
|
@@ -53,5 +53,4 @@ const COLOR_INTL_TRANSLATIONS = {
|
|
|
53
53
|
magenta: "magenta",
|
|
54
54
|
"magenta pink": "magenta pink"
|
|
55
55
|
};
|
|
56
|
-
//#endregion
|
|
57
56
|
export { COLOR_INTL_TRANSLATIONS };
|
|
@@ -1,149 +1,145 @@
|
|
|
1
1
|
/* @ts-self-types="./manipulation.d.ts" */
|
|
2
2
|
import { Color, ColorFormat } from "./types.js";
|
|
3
|
-
|
|
4
|
-
//#region src/colors/manipulation.d.ts
|
|
5
3
|
/**
|
|
6
|
-
* Like {@link parseColor} but returns `undefined` instead of throwing for invalid input.
|
|
7
|
-
*
|
|
8
|
-
* @example
|
|
9
|
-
* ```ts
|
|
10
|
-
* tryParseColor("#3264C8") // Color
|
|
11
|
-
* tryParseColor("nope") // undefined
|
|
12
|
-
* ```
|
|
13
|
-
*/
|
|
14
|
-
declare function tryParseColor(value: string): Color | undefined;
|
|
4
|
+
* Like {@link parseColor} but returns `undefined` instead of throwing for invalid input.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* tryParseColor("#3264C8") // Color
|
|
9
|
+
* tryParseColor("nope") // undefined
|
|
10
|
+
* ```
|
|
11
|
+
*/
|
|
12
|
+
export declare function tryParseColor(value: string): Color | undefined;
|
|
15
13
|
/**
|
|
16
|
-
* Returns `true` if `value` is a parseable color string.
|
|
17
|
-
*
|
|
18
|
-
* @example
|
|
19
|
-
* ```ts
|
|
20
|
-
* isValidColor("#3264C8") // true
|
|
21
|
-
* isValidColor("nope") // false
|
|
22
|
-
* ```
|
|
23
|
-
*/
|
|
24
|
-
declare function isValidColor(value: string): boolean;
|
|
14
|
+
* Returns `true` if `value` is a parseable color string.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* isValidColor("#3264C8") // true
|
|
19
|
+
* isValidColor("nope") // false
|
|
20
|
+
* ```
|
|
21
|
+
*/
|
|
22
|
+
export declare function isValidColor(value: string): boolean;
|
|
25
23
|
/**
|
|
26
|
-
* Detects the format of a color string without parsing it.
|
|
27
|
-
* Returns `undefined` for strings that do not match any known format.
|
|
28
|
-
*
|
|
29
|
-
* The returned format reflects the **syntax** of the string (e.g. `"rgb"` for
|
|
30
|
-
* `rgb(...)` even if an alpha channel is present via slash notation).
|
|
31
|
-
*
|
|
32
|
-
* @example
|
|
33
|
-
* ```ts
|
|
34
|
-
* detectColorFormat("#3264C8") // "hex"
|
|
35
|
-
* detectColorFormat("#3264C8FF") // "hexa"
|
|
36
|
-
* detectColorFormat("rgb(50, 100, 200)") // "rgb"
|
|
37
|
-
* detectColorFormat("hsla(220, 60%, 49%, 0.5)") // "hsla"
|
|
38
|
-
* detectColorFormat("nope") // undefined
|
|
39
|
-
* ```
|
|
40
|
-
*/
|
|
41
|
-
declare function detectColorFormat(value: string): ColorFormat | undefined;
|
|
24
|
+
* Detects the format of a color string without parsing it.
|
|
25
|
+
* Returns `undefined` for strings that do not match any known format.
|
|
26
|
+
*
|
|
27
|
+
* The returned format reflects the **syntax** of the string (e.g. `"rgb"` for
|
|
28
|
+
* `rgb(...)` even if an alpha channel is present via slash notation).
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* detectColorFormat("#3264C8") // "hex"
|
|
33
|
+
* detectColorFormat("#3264C8FF") // "hexa"
|
|
34
|
+
* detectColorFormat("rgb(50, 100, 200)") // "rgb"
|
|
35
|
+
* detectColorFormat("hsla(220, 60%, 49%, 0.5)") // "hsla"
|
|
36
|
+
* detectColorFormat("nope") // undefined
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
export declare function detectColorFormat(value: string): ColorFormat | undefined;
|
|
42
40
|
/**
|
|
43
|
-
* Returns a new color with lightness increased by `amount` (0–1 ratio = percentage points).
|
|
44
|
-
* Operates in HSL space; the returned color is in HSL.
|
|
45
|
-
*
|
|
46
|
-
* @example
|
|
47
|
-
* ```ts
|
|
48
|
-
* lighten(parseColor("hsl(220, 60%, 50%)"), 0.1).getChannelValue("lightness") // 60
|
|
49
|
-
* ```
|
|
50
|
-
*/
|
|
51
|
-
declare function lighten(color: Color, amount: number): Color;
|
|
41
|
+
* Returns a new color with lightness increased by `amount` (0–1 ratio = percentage points).
|
|
42
|
+
* Operates in HSL space; the returned color is in HSL.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* lighten(parseColor("hsl(220, 60%, 50%)"), 0.1).getChannelValue("lightness") // 60
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
export declare function lighten(color: Color, amount: number): Color;
|
|
52
50
|
/**
|
|
53
|
-
* Returns a new color with lightness decreased by `amount` (0–1 ratio = percentage points).
|
|
54
|
-
* Operates in HSL space; the returned color is in HSL.
|
|
55
|
-
*/
|
|
56
|
-
declare function darken(color: Color, amount: number): Color;
|
|
51
|
+
* Returns a new color with lightness decreased by `amount` (0–1 ratio = percentage points).
|
|
52
|
+
* Operates in HSL space; the returned color is in HSL.
|
|
53
|
+
*/
|
|
54
|
+
export declare function darken(color: Color, amount: number): Color;
|
|
57
55
|
/**
|
|
58
|
-
* Returns a new color with saturation increased by `amount` (0–1 ratio = percentage points).
|
|
59
|
-
* Operates in HSL space; the returned color is in HSL.
|
|
60
|
-
*/
|
|
61
|
-
declare function saturate(color: Color, amount: number): Color;
|
|
56
|
+
* Returns a new color with saturation increased by `amount` (0–1 ratio = percentage points).
|
|
57
|
+
* Operates in HSL space; the returned color is in HSL.
|
|
58
|
+
*/
|
|
59
|
+
export declare function saturate(color: Color, amount: number): Color;
|
|
62
60
|
/**
|
|
63
|
-
* Returns a new color with saturation decreased by `amount` (0–1 ratio = percentage points).
|
|
64
|
-
* Operates in HSL space; the returned color is in HSL.
|
|
65
|
-
*/
|
|
66
|
-
declare function desaturate(color: Color, amount: number): Color;
|
|
61
|
+
* Returns a new color with saturation decreased by `amount` (0–1 ratio = percentage points).
|
|
62
|
+
* Operates in HSL space; the returned color is in HSL.
|
|
63
|
+
*/
|
|
64
|
+
export declare function desaturate(color: Color, amount: number): Color;
|
|
67
65
|
/**
|
|
68
|
-
* Returns the complementary color (hue rotated 180°), preserving saturation, lightness, and alpha.
|
|
69
|
-
* The returned color is in HSL.
|
|
70
|
-
*
|
|
71
|
-
* @example
|
|
72
|
-
* ```ts
|
|
73
|
-
* complement(parseColor("hsl(60, 50%, 50%)")).getChannelValue("hue") // 240
|
|
74
|
-
* ```
|
|
75
|
-
*/
|
|
76
|
-
declare function complement(color: Color): Color;
|
|
66
|
+
* Returns the complementary color (hue rotated 180°), preserving saturation, lightness, and alpha.
|
|
67
|
+
* The returned color is in HSL.
|
|
68
|
+
*
|
|
69
|
+
* @example
|
|
70
|
+
* ```ts
|
|
71
|
+
* complement(parseColor("hsl(60, 50%, 50%)")).getChannelValue("hue") // 240
|
|
72
|
+
* ```
|
|
73
|
+
*/
|
|
74
|
+
export declare function complement(color: Color): Color;
|
|
77
75
|
/**
|
|
78
|
-
* Mixes two colors in RGB space at the given `ratio` (0 = fully `a`, 1 = fully `b`).
|
|
79
|
-
* Alpha is also interpolated. The returned color is in RGB.
|
|
80
|
-
*
|
|
81
|
-
* @example
|
|
82
|
-
* ```ts
|
|
83
|
-
* mix(parseColor("#000000"), parseColor("#ffffff")).toString("hex") // "#808080"
|
|
84
|
-
* mix(parseColor("#000000"), parseColor("#ffffff"), 0.25).toString("hex") // "#404040"
|
|
85
|
-
* ```
|
|
86
|
-
*/
|
|
87
|
-
declare function mix(a: Color, b: Color, ratio?: number): Color;
|
|
76
|
+
* Mixes two colors in RGB space at the given `ratio` (0 = fully `a`, 1 = fully `b`).
|
|
77
|
+
* Alpha is also interpolated. The returned color is in RGB.
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```ts
|
|
81
|
+
* mix(parseColor("#000000"), parseColor("#ffffff")).toString("hex") // "#808080"
|
|
82
|
+
* mix(parseColor("#000000"), parseColor("#ffffff"), 0.25).toString("hex") // "#404040"
|
|
83
|
+
* ```
|
|
84
|
+
*/
|
|
85
|
+
export declare function mix(a: Color, b: Color, ratio?: number): Color;
|
|
88
86
|
/**
|
|
89
|
-
* Returns the WCAG 2.1 contrast ratio between two colors (1–21).
|
|
90
|
-
* The order of arguments does not matter.
|
|
91
|
-
*
|
|
92
|
-
* - Black on white: `21`
|
|
93
|
-
* - Same color: `1`
|
|
94
|
-
*
|
|
95
|
-
* @example
|
|
96
|
-
* ```ts
|
|
97
|
-
* contrastRatio(parseColor("#000"), parseColor("#fff")) // 21
|
|
98
|
-
* ```
|
|
99
|
-
*/
|
|
100
|
-
declare function contrastRatio(a: Color, b: Color): number;
|
|
87
|
+
* Returns the WCAG 2.1 contrast ratio between two colors (1–21).
|
|
88
|
+
* The order of arguments does not matter.
|
|
89
|
+
*
|
|
90
|
+
* - Black on white: `21`
|
|
91
|
+
* - Same color: `1`
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* ```ts
|
|
95
|
+
* contrastRatio(parseColor("#000"), parseColor("#fff")) // 21
|
|
96
|
+
* ```
|
|
97
|
+
*/
|
|
98
|
+
export declare function contrastRatio(a: Color, b: Color): number;
|
|
101
99
|
/**
|
|
102
|
-
* Returns whether the contrast between `foreground` and `background` meets the
|
|
103
|
-
* specified WCAG 2.1 conformance level and text size.
|
|
104
|
-
*
|
|
105
|
-
* | Level | Normal text | Large text (≥18pt / ≥14pt bold) |
|
|
106
|
-
* |-------|-------------|----------------------------------|
|
|
107
|
-
* | AA | 4.5 : 1 | 3 : 1 |
|
|
108
|
-
* | AAA | 7 : 1 | 4.5 : 1 |
|
|
109
|
-
*
|
|
110
|
-
* @example
|
|
111
|
-
* ```ts
|
|
112
|
-
* isReadable(parseColor("#fff"), parseColor("#000")) // true (AA, normal)
|
|
113
|
-
* isReadable(parseColor("#fff"), parseColor("#000"), "AAA") // true
|
|
114
|
-
* isReadable(parseColor("#777"), parseColor("#fff"), "AAA") // false
|
|
115
|
-
* ```
|
|
116
|
-
*/
|
|
117
|
-
declare function isReadable(foreground: Color, background: Color, level?: "AA" | "AAA", size?: "normal" | "large"): boolean;
|
|
100
|
+
* Returns whether the contrast between `foreground` and `background` meets the
|
|
101
|
+
* specified WCAG 2.1 conformance level and text size.
|
|
102
|
+
*
|
|
103
|
+
* | Level | Normal text | Large text (≥18pt / ≥14pt bold) |
|
|
104
|
+
* |-------|-------------|----------------------------------|
|
|
105
|
+
* | AA | 4.5 : 1 | 3 : 1 |
|
|
106
|
+
* | AAA | 7 : 1 | 4.5 : 1 |
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```ts
|
|
110
|
+
* isReadable(parseColor("#fff"), parseColor("#000")) // true (AA, normal)
|
|
111
|
+
* isReadable(parseColor("#fff"), parseColor("#000"), "AAA") // true
|
|
112
|
+
* isReadable(parseColor("#777"), parseColor("#fff"), "AAA") // false
|
|
113
|
+
* ```
|
|
114
|
+
*/
|
|
115
|
+
export declare function isReadable(foreground: Color, background: Color, level?: "AA" | "AAA", size?: "normal" | "large"): boolean;
|
|
118
116
|
/**
|
|
119
|
-
* Returns an array of `steps` colors linearly interpolated in RGB space between
|
|
120
|
-
* `from` and `to`. The first element is `from`, the last is `to`.
|
|
121
|
-
*
|
|
122
|
-
* @throws if `steps` is not a finite integer >= 2.
|
|
123
|
-
*
|
|
124
|
-
* @example
|
|
125
|
-
* ```ts
|
|
126
|
-
* colorScale(parseColor("#000"), parseColor("#fff"), 3)
|
|
127
|
-
* // [#000000, #808080, #FFFFFF]
|
|
128
|
-
* ```
|
|
129
|
-
*/
|
|
130
|
-
declare function colorScale(from: Color, to: Color, steps: number): Color[];
|
|
117
|
+
* Returns an array of `steps` colors linearly interpolated in RGB space between
|
|
118
|
+
* `from` and `to`. The first element is `from`, the last is `to`.
|
|
119
|
+
*
|
|
120
|
+
* @throws if `steps` is not a finite integer >= 2.
|
|
121
|
+
*
|
|
122
|
+
* @example
|
|
123
|
+
* ```ts
|
|
124
|
+
* colorScale(parseColor("#000"), parseColor("#fff"), 3)
|
|
125
|
+
* // [#000000, #808080, #FFFFFF]
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
export declare function colorScale(from: Color, to: Color, steps: number): Color[];
|
|
131
129
|
/**
|
|
132
|
-
* Returns an array of `steps` colors interpolated in OKLCH space between `from` and `to`.
|
|
133
|
-
* OKLCH is a perceptually uniform color space, so the steps appear more evenly distributed
|
|
134
|
-
* to the human eye than a plain RGB scale.
|
|
135
|
-
*
|
|
136
|
-
* Hue interpolation takes the shortest arc around the color wheel.
|
|
137
|
-
* Alpha is linearly interpolated. The returned colors are in RGB.
|
|
138
|
-
*
|
|
139
|
-
* @throws if `steps` is not a finite integer >= 2.
|
|
140
|
-
*
|
|
141
|
-
* @example
|
|
142
|
-
* ```ts
|
|
143
|
-
* // A scale from red to blue that passes through purple rather than through green
|
|
144
|
-
* perceptualColorScale(parseColor("hsl(0, 80%, 50%)"), parseColor("hsl(240, 80%, 50%)"), 5)
|
|
145
|
-
* ```
|
|
146
|
-
*/
|
|
147
|
-
declare function perceptualColorScale(from: Color, to: Color, steps: number): Color[];
|
|
148
|
-
//#endregion
|
|
149
|
-
export { colorScale, complement, contrastRatio, darken, desaturate, detectColorFormat, isReadable, isValidColor, lighten, mix, perceptualColorScale, saturate, tryParseColor };
|
|
130
|
+
* Returns an array of `steps` colors interpolated in OKLCH space between `from` and `to`.
|
|
131
|
+
* OKLCH is a perceptually uniform color space, so the steps appear more evenly distributed
|
|
132
|
+
* to the human eye than a plain RGB scale.
|
|
133
|
+
*
|
|
134
|
+
* Hue interpolation takes the shortest arc around the color wheel.
|
|
135
|
+
* Alpha is linearly interpolated. The returned colors are in RGB.
|
|
136
|
+
*
|
|
137
|
+
* @throws if `steps` is not a finite integer >= 2.
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* ```ts
|
|
141
|
+
* // A scale from red to blue that passes through purple rather than through green
|
|
142
|
+
* perceptualColorScale(parseColor("hsl(0, 80%, 50%)"), parseColor("hsl(240, 80%, 50%)"), 5)
|
|
143
|
+
* ```
|
|
144
|
+
*/
|
|
145
|
+
export declare function perceptualColorScale(from: Color, to: Color, steps: number): Color[];
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/* @ts-self-types="./manipulation.d.ts" */
|
|
2
2
|
import { clamp } from "../index.js";
|
|
3
3
|
import { colorToOKLCH, normalizeHue, parseColor } from "./helpers.js";
|
|
4
|
-
|
|
4
|
+
// src/colors/manipulation.ts
|
|
5
5
|
/**
|
|
6
6
|
* Like {@link parseColor} but returns `undefined` instead of throwing for invalid input.
|
|
7
7
|
*
|
|
@@ -247,5 +247,4 @@ function perceptualColorScale(from, to, steps) {
|
|
|
247
247
|
return oklchToColor(l, c, h, alphaFrom + (alphaTo - alphaFrom) * t);
|
|
248
248
|
});
|
|
249
249
|
}
|
|
250
|
-
//#endregion
|
|
251
250
|
export { colorScale, complement, contrastRatio, darken, desaturate, detectColorFormat, isReadable, isValidColor, lighten, mix, perceptualColorScale, saturate, tryParseColor };
|
package/dist/colors/types.d.ts
CHANGED
|
@@ -1,21 +1,19 @@
|
|
|
1
1
|
/* @ts-self-types="./types.d.ts" */
|
|
2
2
|
import { ColorIntlTranslations } from "./intl.js";
|
|
3
|
-
|
|
4
|
-
//#region src/colors/types.d.ts
|
|
5
3
|
/** Supported color string formats. Formats without an `a` suffix treat alpha as fully opaque. */
|
|
6
|
-
type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
|
|
4
|
+
export type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
|
|
7
5
|
/** The three supported color spaces. */
|
|
8
|
-
type ColorSpace = "rgb" | "hsl" | "hsb";
|
|
6
|
+
export type ColorSpace = "rgb" | "hsl" | "hsb";
|
|
9
7
|
/** Individual channel names across all supported color spaces. */
|
|
10
|
-
type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
|
|
8
|
+
export type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
|
|
11
9
|
/** Maps x/y/z axes to {@link ColorChannel} names for 2D color gradient pickers. */
|
|
12
|
-
type ColorAxes = {
|
|
10
|
+
export type ColorAxes = {
|
|
13
11
|
xChannel: ColorChannel;
|
|
14
12
|
yChannel: ColorChannel;
|
|
15
13
|
zChannel: ColorChannel;
|
|
16
14
|
};
|
|
17
15
|
/** Numeric constraints for a single color channel, used to drive sliders and steppers. */
|
|
18
|
-
interface ColorChannelRange {
|
|
16
|
+
export interface ColorChannelRange {
|
|
19
17
|
/** Minimum value of the channel. */
|
|
20
18
|
minValue: number;
|
|
21
19
|
/** Maximum value of the channel. */
|
|
@@ -26,28 +24,28 @@ interface ColorChannelRange {
|
|
|
26
24
|
pageSize: number;
|
|
27
25
|
}
|
|
28
26
|
/** Represents an immutable color value. All mutation methods return a new `Color` instance. */
|
|
29
|
-
interface Color {
|
|
27
|
+
export interface Color {
|
|
30
28
|
/** Returns a new `Color` converted to `format`. */
|
|
31
29
|
toFormat(format: ColorFormat): Color;
|
|
32
30
|
/**
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
31
|
+
* Serializes the color to a CSS string.
|
|
32
|
+
* Defaults to `"css"` which produces the most browser-compatible form for each space
|
|
33
|
+
* (`rgb(...)`, `hsla(...)`, etc.).
|
|
34
|
+
*/
|
|
37
35
|
toString(format?: ColorFormat | "css"): string;
|
|
38
36
|
/** Returns a deep clone of this color. */
|
|
39
37
|
clone(): Color;
|
|
40
38
|
/** Returns the RGB integer representation (`0xRRGGBB`), ignoring alpha. */
|
|
41
39
|
toHexInt(): number;
|
|
42
40
|
/**
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
41
|
+
* Returns the numeric value for `channel`.
|
|
42
|
+
* @throws if `channel` is not part of this color's space.
|
|
43
|
+
*/
|
|
46
44
|
getChannelValue(channel: ColorChannel): number;
|
|
47
45
|
/**
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
* Returns a new `Color` with `channel` set to `value`.
|
|
47
|
+
* @throws if `channel` is not part of this color's space.
|
|
48
|
+
*/
|
|
51
49
|
withChannelValue(channel: ColorChannel, value: number): Color;
|
|
52
50
|
/** Returns the {@link ColorChannelRange} for `channel` in this color space. */
|
|
53
51
|
getChannelRange(channel: ColorChannel): ColorChannelRange;
|
|
@@ -60,10 +58,10 @@ interface Color {
|
|
|
60
58
|
/** Returns the color space this color lives in. */
|
|
61
59
|
getColorSpace(): ColorSpace;
|
|
62
60
|
/**
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
61
|
+
* Resolves the x/y/z channel assignment for a 2D color area picker.
|
|
62
|
+
* Pass `xChannel` and/or `yChannel` to fix specific axes; the remaining
|
|
63
|
+
* channel is inferred as the z axis.
|
|
64
|
+
*/
|
|
67
65
|
getColorSpaceAxes(xyChannels: {
|
|
68
66
|
xChannel?: ColorChannel;
|
|
69
67
|
yChannel?: ColorChannel;
|
|
@@ -71,12 +69,10 @@ interface Color {
|
|
|
71
69
|
/** Returns the three channel names for this color's space, in display order. */
|
|
72
70
|
getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
|
|
73
71
|
/**
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
72
|
+
* Returns a human-readable color name derived from OKLCH analysis
|
|
73
|
+
* (e.g. `"dark vibrant blue"`, `"pale cyan, 20% transparent"`).
|
|
74
|
+
*/
|
|
77
75
|
getColorName(translations: ColorIntlTranslations): string;
|
|
78
76
|
/** Returns just the hue family name (e.g. `"blue"`, `"orange yellow"`). */
|
|
79
77
|
getHueName(translations: ColorIntlTranslations): string;
|
|
80
|
-
}
|
|
81
|
-
//#endregion
|
|
82
|
-
export { Color, ColorAxes, ColorChannel, ColorChannelRange, ColorFormat, ColorSpace };
|
|
78
|
+
}
|