@solid-primitives/utils 7.0.0-next.1 → 7.0.0-next.2

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.
@@ -1,4 +1,6 @@
1
- export * from "./intl.js";
2
- export * from "./types.js";
3
- export * from "./helpers.js";
4
- export * from "./manipulation.js";
1
+ /* @ts-self-types="./index.d.ts" */
2
+ import { COLOR_INTL_TRANSLATIONS, ColorIntlTranslations } from "./intl.js";
3
+ import { Color, ColorAxes, ColorChannel, ColorChannelRange, ColorFormat, ColorSpace } from "./types.js";
4
+ import { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor } from "./helpers.js";
5
+ import { colorScale, complement, contrastRatio, darken, desaturate, detectColorFormat, isReadable, isValidColor, lighten, mix, perceptualColorScale, saturate, tryParseColor } from "./manipulation.js";
6
+ export { COLOR_INTL_TRANSLATIONS, Color, ColorAxes, ColorChannel, ColorChannelRange, ColorFormat, ColorIntlTranslations, ColorSpace, colorScale, colorToOKLCH, complement, contrastRatio, darken, desaturate, detectColorFormat, getColorChannels, isReadable, isValidColor, lighten, mix, normalizeColor, normalizeHue, parseColor, perceptualColorScale, saturate, tryParseColor };
@@ -1,4 +1,5 @@
1
- export * from "./intl.js";
2
- export * from "./types.js";
3
- export * from "./helpers.js";
4
- export * from "./manipulation.js";
1
+ /* @ts-self-types="./index.d.ts" */
2
+ import { colorToOKLCH, getColorChannels, normalizeColor, normalizeHue, parseColor } from "./helpers.js";
3
+ import { COLOR_INTL_TRANSLATIONS } from "./intl.js";
4
+ import { colorScale, complement, contrastRatio, darken, desaturate, detectColorFormat, isReadable, isValidColor, lighten, mix, perceptualColorScale, saturate, tryParseColor } from "./manipulation.js";
5
+ export { COLOR_INTL_TRANSLATIONS, colorScale, colorToOKLCH, complement, contrastRatio, darken, desaturate, detectColorFormat, getColorChannels, isReadable, isValidColor, lighten, mix, normalizeColor, normalizeHue, parseColor, perceptualColorScale, saturate, tryParseColor };
@@ -1,54 +1,58 @@
1
+ /* @ts-self-types="./intl.d.ts" */
2
+ //#region src/colors/intl.d.ts
1
3
  /**
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;
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: {
18
+ hue: string;
19
+ saturation: string;
20
+ lightness: string;
21
+ brightness: string;
22
+ red: string;
23
+ green: string;
24
+ blue: string;
25
+ alpha: string;
26
+ colorName: (lightness: string, chroma: string, hue: string) => string;
27
+ transparentColorName: (lightness: string, chroma: string, hue: string, percentTransparent: string) => string;
28
+ "very dark": string;
29
+ dark: string;
30
+ light: string;
31
+ "very light": string;
32
+ pale: string;
33
+ grayish: string;
34
+ vibrant: string;
35
+ black: string;
36
+ white: string;
37
+ gray: string;
38
+ pink: string;
39
+ "pink red": string;
40
+ "red orange": string;
41
+ brown: string;
42
+ orange: string;
43
+ "orange yellow": string;
44
+ "brown yellow": string;
45
+ yellow: string;
46
+ "yellow green": string;
47
+ "green cyan": string;
48
+ cyan: string;
49
+ "cyan blue": string;
50
+ "blue purple": string;
51
+ purple: string;
52
+ "purple magenta": string;
53
+ magenta: string;
54
+ "magenta pink": string;
53
55
  };
54
- export type ColorIntlTranslations = typeof COLOR_INTL_TRANSLATIONS;
56
+ type ColorIntlTranslations = typeof COLOR_INTL_TRANSLATIONS;
57
+ //#endregion
58
+ export { COLOR_INTL_TRANSLATIONS, ColorIntlTranslations };
@@ -1,68 +1,57 @@
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
- */
1
+ /* @ts-self-types="./intl.d.ts" */
2
+ //#region src/colors/intl.ts
8
3
  /**
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",
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
+ const COLOR_INTL_TRANSLATIONS = {
18
+ hue: "Hue",
19
+ saturation: "Saturation",
20
+ lightness: "Lightness",
21
+ brightness: "Brightness",
22
+ red: "Red",
23
+ green: "Green",
24
+ blue: "Blue",
25
+ alpha: "Alpha",
26
+ colorName: (lightness, chroma, hue) => `${lightness} ${chroma} ${hue}`,
27
+ transparentColorName: (lightness, chroma, hue, percentTransparent) => `${lightness} ${chroma} ${hue}, ${percentTransparent} transparent`,
28
+ "very dark": "very dark",
29
+ dark: "dark",
30
+ light: "light",
31
+ "very light": "very light",
32
+ pale: "pale",
33
+ grayish: "grayish",
34
+ vibrant: "vibrant",
35
+ black: "black",
36
+ white: "white",
37
+ gray: "gray",
38
+ pink: "pink",
39
+ "pink red": "pink red",
40
+ "red orange": "red orange",
41
+ brown: "brown",
42
+ orange: "orange",
43
+ "orange yellow": "orange yellow",
44
+ "brown yellow": "brown yellow",
45
+ yellow: "yellow",
46
+ "yellow green": "yellow green",
47
+ "green cyan": "green cyan",
48
+ cyan: "cyan",
49
+ "cyan blue": "cyan blue",
50
+ "blue purple": "blue purple",
51
+ purple: "purple",
52
+ "purple magenta": "purple magenta",
53
+ magenta: "magenta",
54
+ "magenta pink": "magenta pink"
68
55
  };
56
+ //#endregion
57
+ export { COLOR_INTL_TRANSLATIONS };
@@ -1,144 +1,149 @@
1
- import type { Color, ColorFormat } from "./types.js";
1
+ /* @ts-self-types="./manipulation.d.ts" */
2
+ import { Color, ColorFormat } from "./types.js";
3
+
4
+ //#region src/colors/manipulation.d.ts
2
5
  /**
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;
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;
12
15
  /**
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;
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;
22
25
  /**
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;
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;
39
42
  /**
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;
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;
49
52
  /**
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;
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;
54
57
  /**
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;
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;
59
62
  /**
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;
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;
64
67
  /**
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;
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;
74
77
  /**
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;
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;
85
88
  /**
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;
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;
98
101
  /**
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;
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;
115
118
  /**
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[];
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[];
128
131
  /**
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[];
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 };