@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 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.
@@ -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];
@@ -1,6 +1,6 @@
1
1
  /* @ts-self-types="./helpers.d.ts" */
2
2
  import { clamp } from "../index.js";
3
- //#region src/colors/helpers.ts
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") if (l < ORANGE_LIGHTNESS_THRESHOLD) hueName = "brown";
198
- else l = l - ORANGE_LIGHTNESS_THRESHOLD + MAX_DARK_LIGHTNESS;
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 };
@@ -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 };
@@ -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;
@@ -1,5 +1,5 @@
1
1
  /* @ts-self-types="./intl.d.ts" */
2
- //#region src/colors/intl.ts
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
- //#region src/colors/manipulation.ts
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 };
@@ -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
- * Serializes the color to a CSS string.
34
- * Defaults to `"css"` which produces the most browser-compatible form for each space
35
- * (`rgb(...)`, `hsla(...)`, etc.).
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
- * Returns the numeric value for `channel`.
44
- * @throws if `channel` is not part of this color's space.
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
- * Returns a new `Color` with `channel` set to `value`.
49
- * @throws if `channel` is not part of this color's space.
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
- * Resolves the x/y/z channel assignment for a 2D color area picker.
64
- * Pass `xChannel` and/or `yChannel` to fix specific axes; the remaining
65
- * channel is inferred as the z axis.
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
- * Returns a human-readable color name derived from OKLCH analysis
75
- * (e.g. `"dark vibrant blue"`, `"pale cyan, 20% transparent"`).
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
+ }