1 | // Type definitions for Chroma.js 2.4
|
2 | // Project: https://github.com/gka/chroma.js
|
3 | // Definitions by: Sebastian Brückner <https://github.com/invliD>, Marcin Pacholec <https://github.com/mpacholec>, Charlie Zhuo <https://github.com/CharlieZhuo>
|
4 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
5 |
|
6 | /**
|
7 | * Chroma.js is a tiny library for all kinds of color conversions and color scales.
|
8 | */
|
9 | declare namespace chroma {
|
10 | interface ColorSpaces {
|
11 | rgb: [number, number, number];
|
12 | rgba: [number, number, number, number];
|
13 | hsl: [number, number, number];
|
14 | hsv: [number, number, number];
|
15 | hsi: [number, number, number];
|
16 | lab: [number, number, number];
|
17 | oklab: [number, number, number];
|
18 | lch: [number, number, number];
|
19 | oklch: [number, number, number];
|
20 | hcl: [number, number, number];
|
21 | cmyk: [number, number, number, number];
|
22 | gl: [number, number, number, number];
|
23 | }
|
24 |
|
25 | type InterpolationMode = 'rgb' | 'hsl' | 'hsv' | 'hsi' | 'lab' | 'oklab' | 'lch' | 'oklch' | 'hcl' | 'lrgb';
|
26 |
|
27 | interface ChromaStatic {
|
28 | /**
|
29 | * Creates a color from a string representation (as supported in CSS).
|
30 | * Creates a color from a number representation [0; 16777215]
|
31 | *
|
32 | * @param color The string to convert to a color.
|
33 | * @return the color object.
|
34 | */
|
35 | (color: string | number | Color): Color;
|
36 |
|
37 | /**
|
38 | * Create a color in the specified color space using a, b and c as values.
|
39 | *
|
40 | * @param colorSpace The color space to use. Defaults to "rgb".
|
41 | * @return the color object.
|
42 | */
|
43 | (a: number, b: number, c: number, colorSpace?: keyof ColorSpaces): Color;
|
44 |
|
45 | (a: number, b: number, c: number, d: number, colorSpace?: keyof ColorSpaces): Color;
|
46 |
|
47 | /**
|
48 | * Create a color in the specified color space using values.
|
49 | *
|
50 | * @param values An array of values (e.g. [r, g, b, a?]).
|
51 | * @param colorSpace The color space to use. Defaults to "rgb".
|
52 | * @return the color object.
|
53 | */
|
54 | (values: number[], colorSpace?: keyof ColorSpaces): Color;
|
55 |
|
56 | /**
|
57 | * Create a color from a hex or string representation (as supported in CSS).
|
58 | *
|
59 | * This is an alias of chroma.css().
|
60 | *
|
61 | * @param color The string to convert to a color.
|
62 | * @return the color object.
|
63 | */
|
64 | hex(color: string): Color;
|
65 |
|
66 | valid(color: any, mode?: string): boolean;
|
67 |
|
68 | hsl(h: number, s: number, l: number, alpha?: number): Color;
|
69 |
|
70 | hsv(h: number, s: number, v: number, alpha?: number): Color;
|
71 |
|
72 | lab(lightness: number, a: number, b: number, alpha?: number): Color;
|
73 |
|
74 | oklab(lightness: number, a: number, b: number, alpha?: number): Color;
|
75 |
|
76 | lch(l: number, c: number, h: number, alpha?: number): Color;
|
77 |
|
78 | oklch(l: number, c: number, h: number, alpha?: number): Color;
|
79 |
|
80 | /**
|
81 | * Same meaning as lch(), but in different order.
|
82 | */
|
83 | hcl(h: number, c: number, l: number, alpha?: number): Color;
|
84 |
|
85 | rgb(r: number, g: number, b: number, alpha?: number): Color;
|
86 |
|
87 | /**
|
88 | * GL is a variant of RGB(A), with the only difference that the components are normalized to the range of 0..1.
|
89 | */
|
90 | gl(red: number, green: number, blue: number, alpha?: number): Color;
|
91 |
|
92 | /**
|
93 | * Returns a color from the color temperature scale.
|
94 | * light 2000K, bright sunlight 6000K.
|
95 | * Based on Neil Bartlett's implementation.
|
96 | * https://github.com/neilbartlett/color-temperature
|
97 | */
|
98 | temperature(t: number): Color;
|
99 |
|
100 | /**
|
101 | * Mixes two colors. The mix ratio is a value between 0 and 1.
|
102 | * The color mixing produces different results based the color space used for interpolation. Defaults to LRGB.
|
103 | * @example chroma.mix('red', 'blue', 0.25) // => #bf0040
|
104 | * @example chroma.mix('red', 'blue', 0.5, 'hsl') // => #ff00ff
|
105 | */
|
106 | mix(color1: string | Color, color2: string | Color, f?: number, colorSpace?: InterpolationMode): Color;
|
107 |
|
108 | /**
|
109 | * Alias for {@see mix}.
|
110 | */
|
111 | interpolate(color1: string | Color, color2: string | Color, f?: number, colorSpace?: InterpolationMode): Color;
|
112 |
|
113 | /**
|
114 | * Similar to {@link mix}, but accepts more than two colors. Simple averaging of R,G,B components and the alpha
|
115 | * channel.
|
116 | */
|
117 | average(colors: Array<string | Color>, colorSpace?: InterpolationMode, weights?: number[]): Color;
|
118 |
|
119 | /**
|
120 | * Blends two colors using RGB channel-wise blend functions.
|
121 | */
|
122 | blend(
|
123 | color1: string | Color,
|
124 | color2: string | Color,
|
125 | blendMode: 'multiply' | 'darken' | 'lighten' | 'screen' | 'overlay' | 'burn' | 'dodge',
|
126 | ): Color;
|
127 |
|
128 | /**
|
129 | * Returns a random color.
|
130 | */
|
131 | random(): Color;
|
132 |
|
133 | /**
|
134 | * Computes the WCAG contrast ratio between two colors.
|
135 | * A minimum contrast of 4.5:1 is recommended {@link https://www.w3.org/TR/WCAG20-TECHS/G18.html}
|
136 | * to ensure that text is still readable against a background color.
|
137 | */
|
138 | contrast(color1: string | Color, color2: string | Color): number;
|
139 |
|
140 | /**
|
141 | * Computes the eucledian distance between two colors in a given color space (default is 'lab').
|
142 | * {@link https://en.wikipedia.org/wiki/Euclidean_distance#Three_dimensions}
|
143 | */
|
144 | distance(color1: string | Color, color2: string | Color, colorSpace?: keyof ColorSpaces): number;
|
145 |
|
146 | /**
|
147 | * Computes color difference {@link https://en.wikipedia.org/wiki/Color_difference#CMC_l:c_.281984.29} as
|
148 | * developed by the Colour Measurement Committee of the Society of Dyers and Colourists (CMC) in 1984.
|
149 | * The implementation is adapted from Bruce Lindbloom.
|
150 | * {@link https://web.archive.org/web/20160306044036/http://www.brucelindbloom.com/javascript/ColorDiff.js}
|
151 | * The parameters L (default 1) and C (default 1) are weighting factors for lightness and chromacity.
|
152 | */
|
153 | deltaE(color1: string | Color, color2: string | Color, L?: number, C?: number): number;
|
154 |
|
155 | /**
|
156 | * chroma.brewer is an map of ColorBrewer scales that are included in chroma.js for convenience.
|
157 | * chroma.scale uses the colors to construct.
|
158 | */
|
159 | brewer: {
|
160 | OrRd: string[];
|
161 | PuBu: string[];
|
162 | BuPu: string[];
|
163 | Oranges: string[];
|
164 | BuGn: string[];
|
165 | YlOrBr: string[];
|
166 | YlGn: string[];
|
167 | Reds: string[];
|
168 | RdPu: string[];
|
169 | Greens: string[];
|
170 | YlGnBu: string[];
|
171 | Purples: string[];
|
172 | GnBu: string[];
|
173 | Greys: string[];
|
174 | YlOrRd: string[];
|
175 | PuRd: string[];
|
176 | Blues: string[];
|
177 | PuBuGn: string[];
|
178 | Spectral: string[];
|
179 | RdYlGn: string[];
|
180 | RdBu: string[];
|
181 | PiYG: string[];
|
182 | PRGn: string[];
|
183 | RdYlBu: string[];
|
184 | BrBG: string[];
|
185 | RdGy: string[];
|
186 | PuOr: string[];
|
187 | Set2: string[];
|
188 | Accent: string[];
|
189 | Set1: string[];
|
190 | Set3: string[];
|
191 | Dark2: string[];
|
192 | Paired: string[];
|
193 | Pastel2: string[];
|
194 | Pastel1: string[];
|
195 | };
|
196 |
|
197 | /**
|
198 | * Helper function that computes class breaks based on data.
|
199 | * Mode:
|
200 | * <li>equidistant <code>'e'</code> breaks are computed by dividing the total range of the data into n groups
|
201 | * of equal size.
|
202 | * <li>quantile <code>'q'</code> input domain is divided by quantile ranges.
|
203 | * <li>logarithmic <code>'l'</code> breaks are equidistant breaks but on a logarithmic scale.
|
204 | * <li>k-means <code>'k'</code> breaks use the 1-dimensional
|
205 | * [k-means clustering algorithm]{@link https://en.wikipedia.org/wiki/K-means_clustering} to find (roughly) n
|
206 | * groups of "similar" values. Note that this k-means implementation does not guarantee to find exactly n groups.
|
207 | */
|
208 | limits(data: number[], mode: 'e' | 'q' | 'l' | 'k', c: number): number[];
|
209 |
|
210 | /**
|
211 | * Returns a function that
|
212 | * [bezier-interpolates]{@link https://www.vis4.net/blog/posts/mastering-multi-hued-color-scales/} between
|
213 | * colors in Lab space. The input range of the function is [0..1].
|
214 | * You can convert it to a scale instance by calling <code>chroma.bezier(...).scale()</code>
|
215 | */
|
216 | bezier(colors: string[]): { (t: number): Color; scale(): Scale };
|
217 |
|
218 | scale(name: string | Color): Scale;
|
219 |
|
220 | scale(colors?: Array<string | Color>): Scale;
|
221 |
|
222 | cubehelix(): Cubehelix;
|
223 |
|
224 | cmyk(c: number, m: number, y: number, k: number): Color;
|
225 |
|
226 | css(col: string): Color;
|
227 | }
|
228 |
|
229 | interface Color {
|
230 | /**
|
231 | * Get and set the color opacity.
|
232 | */
|
233 | alpha(a: number): Color;
|
234 | alpha(): number;
|
235 |
|
236 | darken(f?: number): Color;
|
237 |
|
238 | mix(targetColor: string | Color, f?: number, colorSpace?: keyof ColorSpaces): Color;
|
239 |
|
240 | brighten(f?: number): Color;
|
241 |
|
242 | /**
|
243 | * Changes the saturation of a color by manipulating the Lch chromacity.
|
244 | */
|
245 | saturate(s?: number): Color;
|
246 |
|
247 | /**
|
248 | * Similar to saturate, but the opposite direction.
|
249 | */
|
250 | desaturate(s?: number): Color;
|
251 |
|
252 | /**
|
253 | * Changes a single channel and returns the result a new chroma object.
|
254 | * @example
|
255 | * // half Lab lightness
|
256 | * chroma('orangered').set('lab.l', '*0.5')
|
257 | * @example
|
258 | * // double Lch saturation
|
259 | * chroma('darkseagreen').set('lch.c', '*2')
|
260 | */
|
261 | set(modechan: string, v: number | string): Color;
|
262 |
|
263 | /**
|
264 | * Returns a single channel value.
|
265 | * Also @see set
|
266 | */
|
267 | get(modechan: string): number;
|
268 |
|
269 | /**
|
270 | * Relative brightness, according to the
|
271 | * [WCAG]{@link http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef} definition. Normalized to
|
272 | * 0 for darkest black and 1 for lightest white.
|
273 | */
|
274 | luminance(): number;
|
275 |
|
276 | /**
|
277 | * Set luminance of color. The source color will be interpolated with black or white until the correct luminance is found.
|
278 | * The color space used defaults to RGB.
|
279 | */
|
280 | luminance(l: number, colorSpace?: InterpolationMode): Color;
|
281 |
|
282 | /**
|
283 | * Get color as hexadecimal string.
|
284 | *
|
285 | * @param mode `auto` - string will include alpha channel only if it's less than 1.
|
286 | * `rgb` - string will not include alpha channel.
|
287 | * `rgba` - string will include alpha channel.
|
288 | *
|
289 | * @example
|
290 | * chroma('orange').hex() === '#ffa500'
|
291 | * chroma('orange').alpha(0.5).hex() === '#ffa50080'
|
292 | * chroma('orange').alpha(0.5).hex('rgb') === '#ffa500'
|
293 | */
|
294 | hex(mode?: 'auto' | 'rgb' | 'rgba'): string;
|
295 |
|
296 | /**
|
297 | * Returns the named color. Falls back to hexadecimal RGB string, if the color isn't present.
|
298 | */
|
299 | name(): string;
|
300 |
|
301 | /**
|
302 | * Returns a RGB() or HSL() string representation that can be used as CSS-color definition.
|
303 | * mode defaults to <code>'rgb'</code>
|
304 | */
|
305 | css(mode?: 'hsl'): string;
|
306 |
|
307 | /**
|
308 | * Estimate the temperature in Kelvin of any given color, though this makes the only sense for colors from the
|
309 | * [temperature gradient]{@link ChromaStatic.temperature} above.
|
310 | */
|
311 | temperature(): number;
|
312 |
|
313 | /**
|
314 | * Returns the numeric representation of the hexadecimal RGB color.
|
315 | *
|
316 | * @example
|
317 | * chroma('#000000').num() === 0
|
318 | * chroma('#0000ff').num() === 255
|
319 | * chroma('#00ff00').num() === 65280
|
320 | * chroma('#ff0000').num() === 16711680
|
321 | */
|
322 | num(): number;
|
323 |
|
324 | /**
|
325 | * Returns an array with the red, green, and blue component, each as
|
326 | * number within the range 0..255. Chroma internally stores RGB
|
327 | * channels as floats but rounds the numbers before returning them.
|
328 | * You can pass false to prevent the rounding.
|
329 | *
|
330 | * @example
|
331 | * chroma('orange').rgb() === [255,165,0]
|
332 | * chroma('orange').darken().rgb() === [198,118,0]
|
333 | * chroma('orange').darken().rgb(false) === [198.05,118.11,0]
|
334 | */
|
335 | rgb: (round?: boolean) => ColorSpaces['rgb'];
|
336 |
|
337 | /**
|
338 | * Just like color.rgb but adds the alpha channel to the returned array.
|
339 | *
|
340 | * @example
|
341 | * chroma('orange').rgba() === [255,165,0,1]
|
342 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
343 | */
|
344 | rgba: (round?: boolean) => ColorSpaces['rgba'];
|
345 |
|
346 | /**
|
347 | * Returns an array with the `hue`, `saturation`, and `lightness`
|
348 | * component. Hue is the color angle in degree (`0..360`), saturation
|
349 | * and lightness are within `0..1`. Note that for hue-less colors
|
350 | * (black, white, and grays), the hue component will be NaN.
|
351 | *
|
352 | * @example
|
353 | * chroma('orange').hsl() === [38.82,1,0.5,1]
|
354 | * chroma('white').hsl() === [NaN,0,1,1]
|
355 | */
|
356 | hsl: () => ColorSpaces['hsl'];
|
357 |
|
358 | /**
|
359 | * Returns an array with the `hue`, `saturation`, and `value`
|
360 | * components. Hue is the color angle in degree (`0..360`),
|
361 | * saturation and value are within `0..1`. Note that for hue-less
|
362 | * colors (black, white, and grays), the hue component will be NaN.
|
363 | *
|
364 | * @example
|
365 | * chroma('orange').hsv() === [38.82,1,1]
|
366 | * chroma('white').hsv() === [NaN,0,1]
|
367 | */
|
368 | hsv: () => ColorSpaces['hsv'];
|
369 |
|
370 | /**
|
371 | * Returns an array with the `hue`, `saturation`, and `intensity`
|
372 | * components, each as number between 0 and 255. Note that for hue-less
|
373 | * colors (black, white, and grays), the hue component will be NaN.
|
374 | *
|
375 | * @example
|
376 | * chroma('orange').hsi() === [39.64,1,0.55]
|
377 | * chroma('white').hsi() === [NaN,0,1]
|
378 | */
|
379 | hsi: () => ColorSpaces['hsi'];
|
380 |
|
381 | /**
|
382 | * Returns an array with the **L**, **a**, and **b** components.
|
383 | *
|
384 | * @example
|
385 | * chroma('orange').lab() === [74.94,23.93,78.95]
|
386 | */
|
387 | lab: () => ColorSpaces['lab'];
|
388 |
|
389 | /**
|
390 | * Returns an array with the **L**, **a**, and **b** components.
|
391 | *
|
392 | * @example
|
393 | * chroma('orange').oklab() === [0.7927,0.0566,0.1614]
|
394 | */
|
395 | oklab: () => ColorSpaces['oklab'];
|
396 |
|
397 | /**
|
398 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
399 | * components.
|
400 | *
|
401 | * @example
|
402 | * chroma('skyblue').lch() === [79.21,25.94,235.11]
|
403 | */
|
404 | lch: () => ColorSpaces['lch'];
|
405 |
|
406 | /**
|
407 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
408 | * components.
|
409 | *
|
410 | * @example
|
411 | * chroma('skyblue').oklch() === [0.8148,0.0819,225.8]
|
412 | */
|
413 | oklch: () => ColorSpaces['oklch'];
|
414 |
|
415 | /**
|
416 | * Alias of [lch](#color-lch), but with the components in reverse
|
417 | * order.
|
418 | *
|
419 | * @example
|
420 | * chroma('skyblue').hcl() === [235.11,25.94,79.21]
|
421 | */
|
422 | hcl: () => ColorSpaces['hcl'];
|
423 |
|
424 | /**
|
425 | * Just like color.rgb but adds the alpha channel to the returned
|
426 | * array.
|
427 | *
|
428 | * @example
|
429 | * chroma('orange').rgba() === [255,165,0,1]
|
430 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
431 | */
|
432 | cmyk: () => ColorSpaces['cmyk'];
|
433 |
|
434 | /**
|
435 | * Returns an array with the cyan, magenta, yellow, and key (black)
|
436 | * components, each as a normalized value between 0 and 1.
|
437 | *
|
438 | * @example
|
439 | * chroma('33cc00').gl() === [0.2,0.8,0,1]
|
440 | */
|
441 | gl: () => ColorSpaces['gl'];
|
442 |
|
443 | /**
|
444 | * Test if a color has been clipped or not.
|
445 | * Colors generated from CIELab color space may have their RGB
|
446 | * channels clipped to the range of [0..255].
|
447 | * Colors outside that range may exist in nature but are not
|
448 | * displayable on RGB monitors (such as ultraviolet).
|
449 | *
|
450 | * @example
|
451 | * chroma.hcl(50, 40, 20).clipped() === true
|
452 | */
|
453 | clipped: () => boolean;
|
454 |
|
455 | /**
|
456 | * The unclipped RGB components.
|
457 | *
|
458 | * @example
|
459 | * chroma.hcl(50, 40, 100)._rgb._unclipped === [322.65,235.24,196.7,1]
|
460 | */
|
461 | _rgb: { _unclipped: ColorSpaces['rgba'] };
|
462 | }
|
463 |
|
464 | interface Scale<OutType = Color> {
|
465 | (c: string[]): Scale;
|
466 |
|
467 | (value: number | null | undefined): OutType;
|
468 |
|
469 | domain(d?: number[], n?: number, mode?: string): this;
|
470 |
|
471 | mode(mode: InterpolationMode): this;
|
472 |
|
473 | gamma(g: number): this;
|
474 |
|
475 | cache(use: boolean): boolean;
|
476 |
|
477 | correctLightness(enable?: boolean): this;
|
478 |
|
479 | padding(p: number | number[]): this;
|
480 |
|
481 | /**
|
482 | * You can call scale.colors(n) to quickly grab `c` equi-distant colors from a color scale. If called with no
|
483 | * arguments, scale.colors returns the original array of colors used to create the scale.
|
484 | */
|
485 | colors(
|
486 | c: number | undefined,
|
487 | format: undefined | null | 'alpha' | 'darken' | 'brighten' | 'saturate' | 'desaturate',
|
488 | ): Color[];
|
489 | colors(c: number | undefined, format: 'luminance' | 'temperature'): number[];
|
490 | colors<K extends keyof ColorSpaces>(c: number | undefined, format: K): Array<ColorSpaces[K]>;
|
491 | colors(c: number | undefined, format?: 'hex' | 'name'): string[];
|
492 |
|
493 | /**
|
494 | * If you want the scale function to return a distinct set of colors instead of a continuous gradient, you can
|
495 | * use scale.classes. If you pass a number the scale will broken into equi-distant classes.
|
496 | * You can also define custom class breaks by passing them as array
|
497 | */
|
498 | classes(c: number | number[]): this;
|
499 |
|
500 | /**
|
501 | * Set out format for scale() call. Passing null will result in a scale which outputs colors.
|
502 | */
|
503 | out(format: null): Scale;
|
504 | out<K extends keyof ColorSpaces>(format: K): Scale<ColorSpaces[K]>;
|
505 | out(format: 'hex'): Scale<string>;
|
506 | }
|
507 |
|
508 | interface Cubehelix {
|
509 | /**
|
510 | * Set start color for hue rotation, default=300
|
511 | */
|
512 | start(s: number): Cubehelix;
|
513 |
|
514 | /**
|
515 | * number (and direction) of hue rotations (e.g. 1=360°, 1.5=`540°``), default=-1.5
|
516 | */
|
517 | rotations(r: number): Cubehelix;
|
518 |
|
519 | /**
|
520 | * gamma factor can be used to emphasise low or high intensity values, default=1
|
521 | */
|
522 | gamma(g: number): Cubehelix;
|
523 |
|
524 | /**
|
525 | * lightness range: default: [0,1] (black -> white)
|
526 | */
|
527 | lightness(l: number[]): Cubehelix;
|
528 |
|
529 | /**
|
530 | * You can call cubehelix.scale() to use the cube-helix through the chroma.scale interface.
|
531 | */
|
532 | scale(): Scale;
|
533 | }
|
534 | }
|
535 |
|
536 | declare var chroma: chroma.ChromaStatic;
|
537 |
|
538 | export = chroma;
|
539 | export as namespace chroma;
|