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