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