@ateliercartographie/ok-palette 0.1.0
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/LICENSE +15 -0
- package/README.md +295 -0
- package/dist/ok-palette.cjs +1 -0
- package/dist/ok-palette.js +192 -0
- package/dist/src/categorical.d.ts +29 -0
- package/dist/src/divergent.d.ts +67 -0
- package/dist/src/index.d.ts +10 -0
- package/dist/src/patterns.d.ts +37 -0
- package/dist/src/presets.d.ts +46 -0
- package/dist/src/resolve.d.ts +41 -0
- package/dist/src/sequential.d.ts +22 -0
- package/dist/src/types.d.ts +132 -0
- package/dist/src/utils.d.ts +42 -0
- package/package.json +51 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Thomas Ansart — Atelier de cartographie de Sciences Po
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
10
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
11
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
12
|
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
13
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
14
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
15
|
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
# @ateliercartographie/ok-palette
|
|
2
|
+
|
|
3
|
+
Générateur de palettes de couleurs **séquentielles, divergentes et catégorielles** pour la **dataviz** et la **cartographie**. Génère aussi des **palettes de motifs** compatibles avec [@ateliercartographie/motif.js](https://github.com/AtelierCartographie/motif.js).
|
|
4
|
+
|
|
5
|
+
Zero dependencies. Relies entirely on modern browser CSS capabilities (`oklch`, `color-mix()`) to guarantee perceptually uniform results.
|
|
6
|
+
|
|
7
|
+
**Created by:** [Thomas Ansart — Atelier de cartographie de Sciences Po](https://www.sciencespo.fr/cartographie/)
|
|
8
|
+
**License:** ISC
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pnpm add @ateliercartographie/ok-palette
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import {
|
|
20
|
+
sequential,
|
|
21
|
+
divergent,
|
|
22
|
+
divergentSequential,
|
|
23
|
+
categorical,
|
|
24
|
+
categoricalPatterns,
|
|
25
|
+
sequentialPatterns,
|
|
26
|
+
resolveColor,
|
|
27
|
+
resolvePalette,
|
|
28
|
+
presets,
|
|
29
|
+
temperature,
|
|
30
|
+
} from "@ateliercartographie/ok-palette";
|
|
31
|
+
|
|
32
|
+
// 5-class monochrome sequential palette
|
|
33
|
+
const mono = sequential({ colorStart: "steelblue" });
|
|
34
|
+
|
|
35
|
+
// 7-class two-tone sequential palette, high contrast
|
|
36
|
+
const biTone = sequential({
|
|
37
|
+
colorStart: "#f4e285",
|
|
38
|
+
colorEnd: "#1d3557",
|
|
39
|
+
steps: 7,
|
|
40
|
+
contrast: "high",
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
// Symmetric diverging palette (3+1+3 classes)
|
|
44
|
+
const div = divergent({ colorA: "#3b4cc0" });
|
|
45
|
+
|
|
46
|
+
// Asymmetric diverging palette, oklch interpolation
|
|
47
|
+
const divLch = divergent({
|
|
48
|
+
colorA: "#d7191c",
|
|
49
|
+
colorB: "#2b83ba",
|
|
50
|
+
steps: [5, 2],
|
|
51
|
+
contrast: "high",
|
|
52
|
+
colorSpace: "oklch",
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
// Diverging palette built as two mirrored sequential palettes
|
|
56
|
+
const divSeq = divergentSequential({ colorA: "steelblue" });
|
|
57
|
+
|
|
58
|
+
// 8-color vivid categorical palette
|
|
59
|
+
const colors = categorical(8, presets.vif);
|
|
60
|
+
|
|
61
|
+
// Warm categorical palette with hue offset
|
|
62
|
+
const warm = categorical(6, {
|
|
63
|
+
...presets.vif,
|
|
64
|
+
...temperature.chaude,
|
|
65
|
+
hueOffset: 30,
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
// Categorical patterns for motif.js
|
|
69
|
+
const patterns = categoricalPatterns(6);
|
|
70
|
+
|
|
71
|
+
// Sequential patterns (size progressively increases with contrast)
|
|
72
|
+
const seqPatterns = sequentialPatterns(5, { shape: "line", contrast: "high" });
|
|
73
|
+
|
|
74
|
+
// Resolve CSS colors to usable values
|
|
75
|
+
const css = resolvePalette(mono); // string[]
|
|
76
|
+
const webgl = resolvePalette(mono, { format: "webgl" }); // [r,g,b,a][]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## API
|
|
80
|
+
|
|
81
|
+
### `sequential(options)`
|
|
82
|
+
|
|
83
|
+
Generates a sequential palette (monochrome or two-tone).
|
|
84
|
+
|
|
85
|
+
| Option | Type | Default | Description |
|
|
86
|
+
| ------------ | ----------------------------- | ------------ | --------------------------------------------------- |
|
|
87
|
+
| `colorStart` | `string` | — | CSS start color (light tones) |
|
|
88
|
+
| `colorEnd` | `string?` | `colorStart` | CSS end color (dark tones). If omitted → monochrome |
|
|
89
|
+
| `steps` | `number` | `5` | Number of classes (2–12) |
|
|
90
|
+
| `contrast` | `"low" \| "normal" \| "high"` | `"normal"` | Contrast profile |
|
|
91
|
+
|
|
92
|
+
**Returns** `string[]` — CSS colors `color-mix(in oklch, …)`.
|
|
93
|
+
|
|
94
|
+
#### How it works
|
|
95
|
+
|
|
96
|
+
The start color is normalized to a light tone (chroma halved to avoid a fluorescent effect), the end color to a dark tone. The lightness range is automatically adapted to the number of classes via the contrast profile, inspired by ColorBrewer palette analysis:
|
|
97
|
+
|
|
98
|
+
- **3 classes** → ~30% lightness gap
|
|
99
|
+
- **9 classes** → ~70% lightness gap
|
|
100
|
+
|
|
101
|
+
Interpolation is entirely delegated to the browser via `color-mix(in oklch, …)`: no color library needed.
|
|
102
|
+
|
|
103
|
+
### `divergent(options)`
|
|
104
|
+
|
|
105
|
+
Generates a diverging (bipolar) palette around a tinted pivot.
|
|
106
|
+
|
|
107
|
+
| Option | Type | Default | Description |
|
|
108
|
+
| ---------------- | ----------------------------- | ---------------------- | -------------------------------- |
|
|
109
|
+
| `colorA` | `string` | — | Left-extreme CSS color |
|
|
110
|
+
| `colorB` | `string?` | complement of `colorA` | Right-extreme CSS color |
|
|
111
|
+
| `steps` | `[number, number]` | `[3, 3]` | Classes per side `[left, right]` |
|
|
112
|
+
| `contrast` | `"low" \| "normal" \| "high"` | `"normal"` | Contrast profile |
|
|
113
|
+
| `hasCenterClass` | `boolean` | `true` | Add a neutral center class |
|
|
114
|
+
| `colorSpace` | `"oklab" \| "oklch"` | `"oklab"` | Ramp interpolation color space |
|
|
115
|
+
|
|
116
|
+
**Returns** `string[]` — CSS colors.
|
|
117
|
+
|
|
118
|
+
#### How it works
|
|
119
|
+
|
|
120
|
+
Both extremes converge toward an automatically derived **tinted pivot**: the OkLab midpoint of light, highly-desaturated variants of A and B. Because A and B are opposite on the hue wheel, their components almost cancel in OkLab, producing a quasi-neutral, slightly-tinted tone — visually integrated rather than a foreign grey.
|
|
121
|
+
|
|
122
|
+
- `colorSpace: "oklab"` (default): Cartesian path — smoother, avoids hue artifacts
|
|
123
|
+
- `colorSpace: "oklch"`: circular path on the hue wheel — more saturated at the center
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
// Default symmetric palette (7 classes: 3 + pivot + 3)
|
|
127
|
+
divergent({ colorA: "#3b4cc0" });
|
|
128
|
+
|
|
129
|
+
// Asymmetric, high contrast, oklch interpolation
|
|
130
|
+
divergent({
|
|
131
|
+
colorA: "#d7191c",
|
|
132
|
+
colorB: "#2b83ba",
|
|
133
|
+
steps: [5, 2],
|
|
134
|
+
contrast: "high",
|
|
135
|
+
colorSpace: "oklch",
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
// Even count without center class (6 classes)
|
|
139
|
+
divergent({ colorA: "steelblue", steps: [3, 3], hasCenterClass: false });
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### `divergentSequential(options)`
|
|
143
|
+
|
|
144
|
+
Generates a diverging palette built as two mirrored `sequential()` calls — guarantees full consistency with the sequential palette.
|
|
145
|
+
|
|
146
|
+
Accepts the same options as `divergent()` **except** `colorSpace` (interpolation is always oklch, as in `sequential`).
|
|
147
|
+
|
|
148
|
+
| Option | Type | Default | Description |
|
|
149
|
+
| ---------------- | ----------------------------- | ---------- | -------------------------- |
|
|
150
|
+
| `colorA` | `string` | — | Left-extreme color |
|
|
151
|
+
| `colorB` | `string?` | complement | Right-extreme color |
|
|
152
|
+
| `steps` | `[number, number]` | `[3, 3]` | Classes per side |
|
|
153
|
+
| `contrast` | `"low" \| "normal" \| "high"` | `"normal"` | Contrast profile |
|
|
154
|
+
| `hasCenterClass` | `boolean` | `true` | Add a neutral center class |
|
|
155
|
+
|
|
156
|
+
**Returns** `string[]` — CSS colors.
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
// Rigorously identical to two mirrored `sequential` calls
|
|
160
|
+
divergentSequential({ colorA: "#3b4cc0" });
|
|
161
|
+
|
|
162
|
+
// Asymmetric without center class
|
|
163
|
+
divergentSequential({
|
|
164
|
+
colorA: "#d7191c",
|
|
165
|
+
colorB: "#2b83ba",
|
|
166
|
+
steps: [5, 2],
|
|
167
|
+
hasCenterClass: false,
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### `categorical(count, options?)`
|
|
172
|
+
|
|
173
|
+
Generates a categorical color palette.
|
|
174
|
+
|
|
175
|
+
| Option | Type | Default | Description |
|
|
176
|
+
| ---------------- | ------------------ | -------------- | ---------------------------------- |
|
|
177
|
+
| `hueRange` | `[number, number]` | `[0, 360]` | Hue range in degrees |
|
|
178
|
+
| `hueOffset` | `number` | `0` | Hue rotation applied to all colors |
|
|
179
|
+
| `chromaRange` | `[number, number]` | `[0.15, 0.25]` | Oklch chroma range |
|
|
180
|
+
| `lightnessRange` | `[number, number]` | `[0.5, 0.75]` | Oklch lightness range, values 0–1 |
|
|
181
|
+
|
|
182
|
+
**Returns** `string[]` — CSS colors `oklch(…)`.
|
|
183
|
+
|
|
184
|
+
#### Presets
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
presets.vif; // Saturated, vivid colors
|
|
188
|
+
presets.pastel; // Soft, light colors
|
|
189
|
+
presets.sepia; // Warm, desaturated tones
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
#### Temperature filters
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
temperature.mixte; // Full hue wheel
|
|
196
|
+
temperature.chaude; // Reds, oranges, yellows
|
|
197
|
+
temperature.froide; // Greens, blues, purples
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Combining: `categorical(8, { ...presets.vif, ...temperature.chaude })`
|
|
201
|
+
|
|
202
|
+
#### Van der Corput sequence
|
|
203
|
+
|
|
204
|
+
Hue distribution relies on the [Van der Corput sequence](https://en.wikipedia.org/wiki/Van_der_Corput_sequence) in base 2. It always fills the largest gap on the hue wheel, guaranteeing maximum distance between colors regardless of count.
|
|
205
|
+
|
|
206
|
+
Performance: 10 000 colors in ~4 ms.
|
|
207
|
+
|
|
208
|
+
### `categoricalPatterns(count, options?)`
|
|
209
|
+
|
|
210
|
+
Generates categorical pattern parameters compatible with [@ateliercartographie/motif.js](https://github.com/AtelierCartographie/motif.js).
|
|
211
|
+
|
|
212
|
+
| Option | Type | Default | Description |
|
|
213
|
+
| ------------ | ------------------ | ----------------------------------------- | ----------------------- |
|
|
214
|
+
| `shapes` | `string[]` | `["line", "circle", "plaid", "triangle"]` | Shapes to cycle through |
|
|
215
|
+
| `angleRange` | `[number, number]` | `[0, 180]` | Angle range (degrees) |
|
|
216
|
+
| `scaleRange` | `[number, number]` | `[2, 8]` | Scale range |
|
|
217
|
+
| `size` | `number` | `10` | Fixed size |
|
|
218
|
+
| `fill` | `string` | `"#ffffff"` | Fill color |
|
|
219
|
+
| `background` | `string` | `"transparent"` | Background color |
|
|
220
|
+
| `patchSize` | `boolean` | `true` | Enable patchSize |
|
|
221
|
+
| `vdcOffset` | `number` | `0` | Van der Corput offset |
|
|
222
|
+
|
|
223
|
+
**Returns** `PatternParams[]`
|
|
224
|
+
|
|
225
|
+
### `sequentialPatterns(count, options?)`
|
|
226
|
+
|
|
227
|
+
Generates sequential pattern parameters compatible with [@ateliercartographie/motif.js](https://github.com/AtelierCartographie/motif.js).
|
|
228
|
+
|
|
229
|
+
Pattern **size** increases monotonically across classes, analogous to the lightness range in sequential color palettes. The size range is adapted to both the class count and the contrast profile.
|
|
230
|
+
|
|
231
|
+
The shape is fixed to preserve the perception of order.
|
|
232
|
+
|
|
233
|
+
| Option | Type | Default | Description |
|
|
234
|
+
| ------------ | ----------------------------- | --------------- | ------------------------- |
|
|
235
|
+
| `shape` | `string` | `"line"` | Pattern shape |
|
|
236
|
+
| `sizeRange` | `[number, number]` | `[4, 14]` | Size range [small, large] |
|
|
237
|
+
| `angle` | `number` | `45` | Fixed angle (degrees) |
|
|
238
|
+
| `scale` | `number` | `4` | Fixed scale |
|
|
239
|
+
| `contrast` | `"low" \| "normal" \| "high"` | `"normal"` | Contrast profile |
|
|
240
|
+
| `fill` | `string` | `"#ffffff"` | Fill color |
|
|
241
|
+
| `background` | `string` | `"transparent"` | Background color |
|
|
242
|
+
| `patchSize` | `boolean` | `true` | Enable patchSize |
|
|
243
|
+
|
|
244
|
+
**Returns** `PatternParams[]`
|
|
245
|
+
|
|
246
|
+
### `resolveColor(color, options?)`
|
|
247
|
+
|
|
248
|
+
Resolves a complex CSS color (`color-mix(…)`, `oklch(from …)`, etc.) to a usable value.
|
|
249
|
+
|
|
250
|
+
- `{ format: "css" }` (default) → `string` as computed by the browser
|
|
251
|
+
- `{ format: "webgl" }` → `[r, g, b, a]` (0–255)
|
|
252
|
+
|
|
253
|
+
### `resolvePalette(colors, options?)`
|
|
254
|
+
|
|
255
|
+
Applies `resolveColor` to an entire array of colors.
|
|
256
|
+
|
|
257
|
+
## Why this approach?
|
|
258
|
+
|
|
259
|
+
### Problem 1 — Color space
|
|
260
|
+
|
|
261
|
+
The choice of interpolation space dramatically changes the result. Using **oklch** guarantees perceptually uniform steps across each component (lightness, chroma, hue). As of 2025, oklch is supported by all modern browsers.
|
|
262
|
+
|
|
263
|
+
### Problem 2 — Lightness range
|
|
264
|
+
|
|
265
|
+
A sequential palette only works if the lightness gap between the first and last color is sufficient and adapted to the number of classes. This library automatically normalizes input colors to guarantee a readable result.
|
|
266
|
+
|
|
267
|
+
### Solution
|
|
268
|
+
|
|
269
|
+
- **Universal**: normalizes any CSS color before generating the palette
|
|
270
|
+
- **Modern**: zero dependencies, relies on native `oklch` and `color-mix()`
|
|
271
|
+
- **Performant**: the Van der Corput sequence generates categorical palettes in constant time, unlike iterative approaches like I Want Hue
|
|
272
|
+
|
|
273
|
+
## Development
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
# Start the demo page
|
|
277
|
+
pnpm dev
|
|
278
|
+
|
|
279
|
+
# Build the library
|
|
280
|
+
pnpm build
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
## License
|
|
284
|
+
|
|
285
|
+
ISC — Atelier de cartographie de Sciences Po
|
|
286
|
+
|
|
287
|
+
## Resources
|
|
288
|
+
|
|
289
|
+
- [Chroma.js](https://gka.github.io/chroma.js) — Documentation
|
|
290
|
+
- [Chroma.js Color Palette Helper](https://gka.github.io/palettes)
|
|
291
|
+
- [MDN — `color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color-mix)
|
|
292
|
+
- [ColorBrewer](https://colorbrewer2.org/)
|
|
293
|
+
- [Mastering Multi-hued Color Scales](https://www.vis4.net/blog/mastering-multi-hued-color-scales/) — Gregor Aisch
|
|
294
|
+
- [Van der Corput sequence](https://en.wikipedia.org/wiki/Van_der_Corput_sequence)
|
|
295
|
+
- [@ateliercartographie/motif.js](https://github.com/AtelierCartographie/motif.js)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const P=3,T=9,R={low:{start:[85,90],end:[70,50]},normal:{start:[90,97],end:[60,25]},high:{start:[96,99],end:[40,10]}};function k(t){let n=0,e=.5;for(;t>0;)t&1&&(n+=e),t>>=1,e/=2;return n}function x(t,n="normal"){const e=R[n]??R.normal,o=Math.min(1,Math.max(0,(t-P)/(T-P))),i=e.start[0]+o*(e.start[1]-e.start[0]),c=e.end[0]+o*(e.end[1]-e.end[0]);return{start:i,end:c}}function p(t,n){return t[0]+n*(t[1]-t[0])}function S({colorStart:t,colorEnd:n,steps:e=5,contrast:o="normal"}){const i=n??t,{start:c,end:r}=x(e,o),a=o==="low"?1.5:o==="high"?3.5:2.5,l=`oklch(from ${t} ${c.toFixed(1)}% calc(c / ${a}) h)`,s=`oklch(from ${i} ${r.toFixed(1)}% c h)`,f=[];for(let h=0;h<e;h++){const m=e===1?0:h/(e-1)*100;f.push(`color-mix(in oklch, ${l}, ${s} ${m}%)`)}return f}function b({colorA:t,colorB:n,steps:e=[3,3],contrast:o="normal",hasCenterClass:i=!0,colorSpace:c="oklab"}){const[r,a]=e,{start:l,end:s}=x(Math.max(r,a),o),f=`oklch(from ${t} ${s.toFixed(1)}% c h)`,h=n?`oklch(from ${n} ${s.toFixed(1)}% c h)`:`oklch(from ${t} ${s.toFixed(1)}% c calc(h + 180))`,m=`oklch(from ${t} ${l.toFixed(1)}% calc(c / 8) h)`,u=n?`oklch(from ${n} ${l.toFixed(1)}% calc(c / 8) h)`:`oklch(from ${t} ${l.toFixed(1)}% calc(c / 8) calc(h + 180))`,d=`color-mix(in oklab, ${m}, ${u} 50%)`,$=[];for(let g=0;g<r;g++){const F=r===1?0:g/r*100;$.push(`color-mix(in ${c}, ${d} ${F.toFixed(1)}%, ${f})`)}i&&$.push(d);for(let g=a-1;g>=0;g--){const F=a===1?0:g/a*100;$.push(`color-mix(in ${c}, ${d} ${F.toFixed(1)}%, ${h})`)}return $}function w({colorA:t,colorB:n,steps:e=[3,3],contrast:o="normal",hasCenterClass:i=!0}){const[c,r]=e,a=n??`oklch(from ${t} l c calc(h + 180))`,l=S({colorStart:t,steps:c,contrast:o}).reverse(),s=S({colorStart:a,steps:r,contrast:o});if(!i)return[...l,...s];const{start:f}=x(c,o),{start:h}=x(r,o),m=`oklch(from ${t} ${f.toFixed(1)}% 0.02 h)`,u=n?`oklch(from ${n} ${h.toFixed(1)}% 0.02 h)`:`oklch(from ${t} ${h.toFixed(1)}% 0.02 calc(h + 180))`,d=`color-mix(in oklab, ${m}, ${u} 50%)`;return[...l,d,...s]}const A=[.8,.2,.5],q=[.2,.8,.5];function _(t,{hueRange:n=[0,360],hueOffset:e=0,chromaRange:o=[.15,.25],lightnessRange:i=[.5,.75]}={}){const c=[];for(let r=0;r<t;r++){const a=r===0?0:k(r),l=(p(n,a)+e)%360,s=p(i,A[r%3]),f=p(o,q[r%3]);c.push(`oklch(${Math.round(s*100)}% ${f.toFixed(3)} ${l.toFixed(2)})`)}return c}const E=[0,1,.5];function I(t,{shapes:n=["line","circle","plaid","triangle"],angleRange:e=[0,180],scaleRange:o=[2,8],size:i=25,fill:c="#000000",background:r="#ffffff",patchSize:a=!0,vdcOffset:l=0,colorize:s=!1}={}){const f=n.length,h=s?_(t,typeof s=="object"?s:void 0):void 0;return Array.from({length:t},(m,u)=>{const d=u%f,$=Math.floor(u/f),g=n[d],F=d*17,O=k($+l+F),y=Math.round(p(e,O)),L=+p(o,E[u%3]).toFixed(2),M=h?.[u]??c;return{type:g,angle:y,scale:L,size:i,fill:M,background:r,patchSize:a}})}function D(t,{shape:n="line",sizeRange:e=[10,90],angle:o=45,scale:i=3,contrast:c="normal",fill:r="#000000",background:a="#ffffff",patchSize:l=!0}={}){const{start:s,end:f}=x(t,c);return Array.from({length:t},(h,m)=>{const u=t<=1?0:m/(t-1),d=(s+u*(f-s))/100,$=p(e,1-d);return{type:n,angle:o,scale:i,size:Math.round(+$),fill:r,background:a,patchSize:l}})}let v=null;function N(){if(!v&&(v=new OffscreenCanvas(1,1).getContext("2d",{willReadFrequently:!0}),!v))throw new Error("Could not create an OffscreenCanvas 2D context");return v}function C(t,{format:n="css"}={}){const e=N();if(e.fillStyle=t,n==="css")return e.fillStyle;e.clearRect(0,0,1,1),e.fillRect(0,0,1,1);const{data:o}=e.getImageData(0,0,1,1);return[o[0],o[1],o[2],o[3]]}function j(t,{format:n="css"}={}){return n==="webgl"?t.map(e=>C(e,{format:"webgl"})):t.map(e=>C(e,{format:"css"}))}const z={vif:{hueRange:[0,360],chromaRange:[.15,.22],lightnessRange:[.6,.8]},pastel:{hueRange:[0,360],chromaRange:[.05,.1],lightnessRange:[.8,.9]},sepia:{hueRange:[50,90],chromaRange:[.02,.05],lightnessRange:[.6,.9]}},B={mixte:{hueRange:[0,360]},chaude:{hueRange:[300,480]},froide:{hueRange:[120,300]}};exports.CONTRAST_PROFILES=R;exports.categorical=_;exports.categoricalPatterns=I;exports.divergent=b;exports.divergentSequential=w;exports.getAdaptiveBounds=x;exports.presets=z;exports.resolveColor=C;exports.resolvePalette=j;exports.sequential=S;exports.sequentialPatterns=D;exports.temperature=B;exports.vanDerCorput=k;
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
const R = {
|
|
2
|
+
low: {
|
|
3
|
+
start: [85, 90],
|
|
4
|
+
end: [70, 50]
|
|
5
|
+
},
|
|
6
|
+
normal: {
|
|
7
|
+
start: [90, 97],
|
|
8
|
+
end: [60, 25]
|
|
9
|
+
},
|
|
10
|
+
high: {
|
|
11
|
+
start: [96, 99],
|
|
12
|
+
end: [40, 10]
|
|
13
|
+
}
|
|
14
|
+
};
|
|
15
|
+
function C(t) {
|
|
16
|
+
let n = 0, e = 0.5;
|
|
17
|
+
for (; t > 0; )
|
|
18
|
+
t & 1 && (n += e), t >>= 1, e /= 2;
|
|
19
|
+
return n;
|
|
20
|
+
}
|
|
21
|
+
function F(t, n = "normal") {
|
|
22
|
+
const e = R[n] ?? R.normal, o = Math.min(1, Math.max(0, (t - 3) / 6)), i = e.start[0] + o * (e.start[1] - e.start[0]), r = e.end[0] + o * (e.end[1] - e.end[0]);
|
|
23
|
+
return { start: i, end: r };
|
|
24
|
+
}
|
|
25
|
+
function p(t, n) {
|
|
26
|
+
return t[0] + n * (t[1] - t[0]);
|
|
27
|
+
}
|
|
28
|
+
function k({
|
|
29
|
+
colorStart: t,
|
|
30
|
+
colorEnd: n,
|
|
31
|
+
steps: e = 5,
|
|
32
|
+
contrast: o = "normal"
|
|
33
|
+
}) {
|
|
34
|
+
const i = n ?? t, { start: r, end: c } = F(e, o), a = o === "low" ? 1.5 : o === "high" ? 3.5 : 2.5, l = `oklch(from ${t} ${r.toFixed(1)}% calc(c / ${a}) h)`, s = `oklch(from ${i} ${c.toFixed(1)}% c h)`, f = [];
|
|
35
|
+
for (let h = 0; h < e; h++) {
|
|
36
|
+
const $ = e === 1 ? 0 : h / (e - 1) * 100;
|
|
37
|
+
f.push(`color-mix(in oklch, ${l}, ${s} ${$}%)`);
|
|
38
|
+
}
|
|
39
|
+
return f;
|
|
40
|
+
}
|
|
41
|
+
function b({
|
|
42
|
+
colorA: t,
|
|
43
|
+
colorB: n,
|
|
44
|
+
steps: e = [3, 3],
|
|
45
|
+
contrast: o = "normal",
|
|
46
|
+
hasCenterClass: i = !0,
|
|
47
|
+
colorSpace: r = "oklab"
|
|
48
|
+
}) {
|
|
49
|
+
const [c, a] = e, { start: l, end: s } = F(
|
|
50
|
+
Math.max(c, a),
|
|
51
|
+
o
|
|
52
|
+
), f = `oklch(from ${t} ${s.toFixed(1)}% c h)`, h = n ? `oklch(from ${n} ${s.toFixed(1)}% c h)` : `oklch(from ${t} ${s.toFixed(1)}% c calc(h + 180))`, $ = `oklch(from ${t} ${l.toFixed(1)}% calc(c / 8) h)`, u = n ? `oklch(from ${n} ${l.toFixed(1)}% calc(c / 8) h)` : `oklch(from ${t} ${l.toFixed(1)}% calc(c / 8) calc(h + 180))`, d = `color-mix(in oklab, ${$}, ${u} 50%)`, g = [];
|
|
53
|
+
for (let m = 0; m < c; m++) {
|
|
54
|
+
const x = c === 1 ? 0 : m / c * 100;
|
|
55
|
+
g.push(`color-mix(in ${r}, ${d} ${x.toFixed(1)}%, ${f})`);
|
|
56
|
+
}
|
|
57
|
+
i && g.push(d);
|
|
58
|
+
for (let m = a - 1; m >= 0; m--) {
|
|
59
|
+
const x = a === 1 ? 0 : m / a * 100;
|
|
60
|
+
g.push(`color-mix(in ${r}, ${d} ${x.toFixed(1)}%, ${h})`);
|
|
61
|
+
}
|
|
62
|
+
return g;
|
|
63
|
+
}
|
|
64
|
+
function A({
|
|
65
|
+
colorA: t,
|
|
66
|
+
colorB: n,
|
|
67
|
+
steps: e = [3, 3],
|
|
68
|
+
contrast: o = "normal",
|
|
69
|
+
hasCenterClass: i = !0
|
|
70
|
+
}) {
|
|
71
|
+
const [r, c] = e, a = n ?? `oklch(from ${t} l c calc(h + 180))`, l = k({ colorStart: t, steps: r, contrast: o }).reverse(), s = k({ colorStart: a, steps: c, contrast: o });
|
|
72
|
+
if (!i)
|
|
73
|
+
return [...l, ...s];
|
|
74
|
+
const { start: f } = F(r, o), { start: h } = F(c, o), $ = `oklch(from ${t} ${f.toFixed(1)}% 0.02 h)`, u = n ? `oklch(from ${n} ${h.toFixed(1)}% 0.02 h)` : `oklch(from ${t} ${h.toFixed(1)}% 0.02 calc(h + 180))`, d = `color-mix(in oklab, ${$}, ${u} 50%)`;
|
|
75
|
+
return [...l, d, ...s];
|
|
76
|
+
}
|
|
77
|
+
const w = [0.8, 0.2, 0.5], E = [0.2, 0.8, 0.5];
|
|
78
|
+
function L(t, {
|
|
79
|
+
hueRange: n = [0, 360],
|
|
80
|
+
hueOffset: e = 0,
|
|
81
|
+
chromaRange: o = [0.15, 0.25],
|
|
82
|
+
lightnessRange: i = [0.5, 0.75]
|
|
83
|
+
} = {}) {
|
|
84
|
+
const r = [];
|
|
85
|
+
for (let c = 0; c < t; c++) {
|
|
86
|
+
const a = c === 0 ? 0 : C(c), l = (p(n, a) + e) % 360, s = p(i, w[c % 3]), f = p(o, E[c % 3]);
|
|
87
|
+
r.push(
|
|
88
|
+
`oklch(${Math.round(s * 100)}% ${f.toFixed(3)} ${l.toFixed(2)})`
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
return r;
|
|
92
|
+
}
|
|
93
|
+
const y = [0, 1, 0.5];
|
|
94
|
+
function I(t, {
|
|
95
|
+
shapes: n = ["line", "circle", "plaid", "triangle"],
|
|
96
|
+
angleRange: e = [0, 180],
|
|
97
|
+
scaleRange: o = [2, 8],
|
|
98
|
+
size: i = 25,
|
|
99
|
+
fill: r = "#000000",
|
|
100
|
+
background: c = "#ffffff",
|
|
101
|
+
patchSize: a = !0,
|
|
102
|
+
vdcOffset: l = 0,
|
|
103
|
+
colorize: s = !1
|
|
104
|
+
} = {}) {
|
|
105
|
+
const f = n.length, h = s ? L(
|
|
106
|
+
t,
|
|
107
|
+
typeof s == "object" ? s : void 0
|
|
108
|
+
) : void 0;
|
|
109
|
+
return Array.from({ length: t }, ($, u) => {
|
|
110
|
+
const d = u % f, g = Math.floor(u / f), m = n[d], x = d * 17, _ = C(g + l + x), M = Math.round(p(e, _)), P = +p(o, y[u % 3]).toFixed(2), T = h?.[u] ?? r;
|
|
111
|
+
return { type: m, angle: M, scale: P, size: i, fill: T, background: c, patchSize: a };
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
function q(t, {
|
|
115
|
+
shape: n = "line",
|
|
116
|
+
sizeRange: e = [10, 90],
|
|
117
|
+
angle: o = 45,
|
|
118
|
+
scale: i = 3,
|
|
119
|
+
contrast: r = "normal",
|
|
120
|
+
fill: c = "#000000",
|
|
121
|
+
background: a = "#ffffff",
|
|
122
|
+
patchSize: l = !0
|
|
123
|
+
} = {}) {
|
|
124
|
+
const { start: s, end: f } = F(t, r);
|
|
125
|
+
return Array.from({ length: t }, (h, $) => {
|
|
126
|
+
const u = t <= 1 ? 0 : $ / (t - 1), d = (s + u * (f - s)) / 100, g = p(e, 1 - d);
|
|
127
|
+
return {
|
|
128
|
+
type: n,
|
|
129
|
+
angle: o,
|
|
130
|
+
scale: i,
|
|
131
|
+
size: Math.round(+g),
|
|
132
|
+
fill: c,
|
|
133
|
+
background: a,
|
|
134
|
+
patchSize: l
|
|
135
|
+
};
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
let S = null;
|
|
139
|
+
function O() {
|
|
140
|
+
if (!S && (S = new OffscreenCanvas(1, 1).getContext("2d", {
|
|
141
|
+
willReadFrequently: !0
|
|
142
|
+
}), !S))
|
|
143
|
+
throw new Error("Could not create an OffscreenCanvas 2D context");
|
|
144
|
+
return S;
|
|
145
|
+
}
|
|
146
|
+
function v(t, { format: n = "css" } = {}) {
|
|
147
|
+
const e = O();
|
|
148
|
+
if (e.fillStyle = t, n === "css")
|
|
149
|
+
return e.fillStyle;
|
|
150
|
+
e.clearRect(0, 0, 1, 1), e.fillRect(0, 0, 1, 1);
|
|
151
|
+
const { data: o } = e.getImageData(0, 0, 1, 1);
|
|
152
|
+
return [o[0], o[1], o[2], o[3]];
|
|
153
|
+
}
|
|
154
|
+
function N(t, { format: n = "css" } = {}) {
|
|
155
|
+
return n === "webgl" ? t.map((e) => v(e, { format: "webgl" })) : t.map((e) => v(e, { format: "css" }));
|
|
156
|
+
}
|
|
157
|
+
const D = {
|
|
158
|
+
vif: {
|
|
159
|
+
hueRange: [0, 360],
|
|
160
|
+
chromaRange: [0.15, 0.22],
|
|
161
|
+
lightnessRange: [0.6, 0.8]
|
|
162
|
+
},
|
|
163
|
+
pastel: {
|
|
164
|
+
hueRange: [0, 360],
|
|
165
|
+
chromaRange: [0.05, 0.1],
|
|
166
|
+
lightnessRange: [0.8, 0.9]
|
|
167
|
+
},
|
|
168
|
+
sepia: {
|
|
169
|
+
hueRange: [50, 90],
|
|
170
|
+
chromaRange: [0.02, 0.05],
|
|
171
|
+
lightnessRange: [0.6, 0.9]
|
|
172
|
+
}
|
|
173
|
+
}, X = {
|
|
174
|
+
mixte: { hueRange: [0, 360] },
|
|
175
|
+
chaude: { hueRange: [300, 480] },
|
|
176
|
+
froide: { hueRange: [120, 300] }
|
|
177
|
+
};
|
|
178
|
+
export {
|
|
179
|
+
R as CONTRAST_PROFILES,
|
|
180
|
+
L as categorical,
|
|
181
|
+
I as categoricalPatterns,
|
|
182
|
+
b as divergent,
|
|
183
|
+
A as divergentSequential,
|
|
184
|
+
F as getAdaptiveBounds,
|
|
185
|
+
D as presets,
|
|
186
|
+
v as resolveColor,
|
|
187
|
+
N as resolvePalette,
|
|
188
|
+
k as sequential,
|
|
189
|
+
q as sequentialPatterns,
|
|
190
|
+
X as temperature,
|
|
191
|
+
C as vanDerCorput
|
|
192
|
+
};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { CategoricalColorOptions, CSSColor } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Generates a categorical color palette.
|
|
4
|
+
*
|
|
5
|
+
* Hues are distributed optimally using the base-2 Van der Corput sequence:
|
|
6
|
+
* the largest gap on the hue wheel is always filled next.
|
|
7
|
+
*
|
|
8
|
+
* Lightness and chroma oscillate over a 3-step cycle to maximize
|
|
9
|
+
* perceptual contrast between neighboring colors.
|
|
10
|
+
*
|
|
11
|
+
* Style presets (vif, pastel, sepia, etc.) and temperature filters
|
|
12
|
+
* (mixte, chaude, froide) are configured via the range options.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* // 8 vivid colors across the full hue wheel
|
|
17
|
+
* categorical(8);
|
|
18
|
+
*
|
|
19
|
+
* // 5 pastel colors
|
|
20
|
+
* categorical(5, { chromaRange: [0.05, 0.1], lightnessRange: [0.8, 0.9] });
|
|
21
|
+
*
|
|
22
|
+
* // 6 warm colors
|
|
23
|
+
* categorical(6, { hueRange: [300, 480] });
|
|
24
|
+
*
|
|
25
|
+
* // 4 colors with a starting hue offset of 45°
|
|
26
|
+
* categorical(4, { hueOffset: 45 });
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
export declare function categorical(count: number, { hueRange, hueOffset, chromaRange, lightnessRange, }?: CategoricalColorOptions): CSSColor[];
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { CSSColor, DivergentPaletteOptions } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Génère une palette divergente (bi-polaire) autour d'un pivot teinté.
|
|
4
|
+
*
|
|
5
|
+
* La palette est construite en deux rampes indépendantes (gauche et droite)
|
|
6
|
+
* convergeant vers un pivot neutre dérivé automatiquement des couleurs A et B.
|
|
7
|
+
*
|
|
8
|
+
* **Ce que la fonction gère automatiquement :**
|
|
9
|
+
*
|
|
10
|
+
* 1. **Couleur B complémentaire** : Si colorB n'est pas fournie, le CSS natif
|
|
11
|
+
* effectue une rotation de +180° sur la teinte de colorA.
|
|
12
|
+
*
|
|
13
|
+
* 2. **Pivot teinté** : Le pivot central n'est pas un gris pur (chroma=0) mais
|
|
14
|
+
* le point médian OkLab entre A et B, dont on force la luminance à startL.
|
|
15
|
+
* Comme A et B sont sur des côtés opposés de la roue des couleurs, leurs
|
|
16
|
+
* composantes a/b s'annulent presque entièrement dans OkLab, produisant un
|
|
17
|
+
* quasi-neutre très légèrement teinté — visuellement intégré à la palette
|
|
18
|
+
* plutôt qu'un gris "étranger".
|
|
19
|
+
*
|
|
20
|
+
* 3. **Intensité maximale sur chaque côté** : Les deux extrêmes atteignent
|
|
21
|
+
* toujours la même luminance cible (endL), quel que soit le nombre de classes.
|
|
22
|
+
* Les marches sont plus grandes du côté avec moins de classes.
|
|
23
|
+
*
|
|
24
|
+
* 4. **Gestion pair/impair** : `hasCenterClass` injecte explicitement le pivot
|
|
25
|
+
* comme classe centrale. Sans lui, les deux rampes s'arrêtent avant le pivot.
|
|
26
|
+
*
|
|
27
|
+
* 5. **Espace d'interpolation** : `colorSpace` contrôle si chaque rampe
|
|
28
|
+
* interpole en OkLab (trajectoire cartésienne, plus douce, évite les teintes
|
|
29
|
+
* parasites) ou en OkLCH (trajectoire circulaire sur la roue des teintes).
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* ```ts
|
|
33
|
+
* // Palette symétrique par défaut (OkLab, 3+3 classes)
|
|
34
|
+
* divergent({ colorA: "#3b4cc0" });
|
|
35
|
+
*
|
|
36
|
+
* // Asymétrique, contraste élevé, OkLCH
|
|
37
|
+
* divergent({ colorA: "#d7191c", colorB: "#2b83ba", steps: [5, 2], contrast: "high", colorSpace: "oklch" });
|
|
38
|
+
*
|
|
39
|
+
* // Sans classe centrale (nombre de classes pair)
|
|
40
|
+
* divergent({ colorA: "steelblue", steps: [4, 4], hasCenterClass: false });
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export declare function divergent({ colorA, colorB, steps, contrast, hasCenterClass, colorSpace, }: DivergentPaletteOptions): CSSColor[];
|
|
44
|
+
/**
|
|
45
|
+
* Generates a diverging palette built as two mirrored sequential palettes —
|
|
46
|
+
* an approach that guarantees full consistency with `sequential()`.
|
|
47
|
+
*
|
|
48
|
+
* Each side is exactly identical to `sequential({ colorStart, steps, contrast })`
|
|
49
|
+
* in monochrome mode. The left ramp is reversed (dark → light) to converge
|
|
50
|
+
* toward the center; the right ramp is in natural order (light → dark).
|
|
51
|
+
*
|
|
52
|
+
* **Center class**: If `hasCenterClass` is `true`, a transition class is
|
|
53
|
+
* inserted between the two ramps. It is computed as the OkLab blend of the
|
|
54
|
+
* highly-desaturated (chroma/4) light variants of both colors, producing a
|
|
55
|
+
* quasi-neutral, slightly tinted tone — softer than pure grey without
|
|
56
|
+
* requiring an explicit pivot.
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* ```ts
|
|
60
|
+
* // Symmetric 3+3 — rigorously identical to two mirrored `sequential` calls
|
|
61
|
+
* divergentSequential({ colorA: "#3b4cc0" });
|
|
62
|
+
*
|
|
63
|
+
* // Asymmetric without center class
|
|
64
|
+
* divergentSequential({ colorA: "#d7191c", colorB: "#2b83ba", steps: [5, 2], hasCenterClass: false });
|
|
65
|
+
* ```
|
|
66
|
+
*/
|
|
67
|
+
export declare function divergentSequential({ colorA, colorB, steps, contrast, hasCenterClass, }: Omit<DivergentPaletteOptions, "colorSpace">): CSSColor[];
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export { sequential } from "./sequential";
|
|
2
|
+
export { divergent, divergentSequential } from "./divergent";
|
|
3
|
+
export { categorical } from "./categorical";
|
|
4
|
+
export { categoricalPatterns, sequentialPatterns } from "./patterns";
|
|
5
|
+
export { resolveColor, resolvePalette } from "./resolve";
|
|
6
|
+
export { presets, temperature } from "./presets";
|
|
7
|
+
export { CONTRAST_PROFILES, vanDerCorput, getAdaptiveBounds } from "./utils";
|
|
8
|
+
export type { ContrastMode, ColorFormat, CSSColor, WebGLColor, Range, ContrastProfile, ContrastProfiles, SequentialPaletteOptions, DivergentPaletteOptions, DivergentColorSpace, CategoricalColorOptions, CategoricalColorPreset, CategoricalPatternOptions, SequentialPatternOptions, PatternParams, } from "./types";
|
|
9
|
+
export type { AdaptiveBounds } from "./utils";
|
|
10
|
+
export type { PresetName, TemperatureName } from "./presets";
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { CategoricalPatternOptions, PatternParams, SequentialPatternOptions } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Generates a categorical pattern palette (parameters for motif.js).
|
|
4
|
+
*
|
|
5
|
+
* The parallel with `categorical` (colors) is as follows:
|
|
6
|
+
* - **Shape** ↔ Hue category (most perceptible dimension, strict cycle)
|
|
7
|
+
* - **Angle** ↔ Hue value (distributed with Van der Corput)
|
|
8
|
+
* - **Scale** ↔ Chroma (secondary variation, 3 oscillating levels)
|
|
9
|
+
* - **Size** ↔ Lightness (fixed → constant visual weight)
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* categoricalPatterns(6);
|
|
14
|
+
* categoricalPatterns(4, { shapes: ["line", "circle"], fill: "#333" });
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
export declare function categoricalPatterns(count: number, { shapes, angleRange, scaleRange, size, fill, background, patchSize, vdcOffset, colorize, }?: CategoricalPatternOptions): PatternParams[];
|
|
18
|
+
/**
|
|
19
|
+
* Generates a sequential pattern palette (parameters for motif.js).
|
|
20
|
+
*
|
|
21
|
+
* Pattern **size** increases monotonically across classes,
|
|
22
|
+
* analogous to the lightness range in color palettes.
|
|
23
|
+
* The size range is adapted to the number of classes and contrast profile,
|
|
24
|
+
* exactly as in `sequential` (colors).
|
|
25
|
+
*
|
|
26
|
+
* The shape is fixed to preserve the perception of order.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* // 5 line patterns, normal contrast
|
|
31
|
+
* sequentialPatterns(5);
|
|
32
|
+
*
|
|
33
|
+
* // 7 circle patterns, high contrast, size 2→20
|
|
34
|
+
* sequentialPatterns(7, { shape: "circle", contrast: "high", sizeRange: [2, 20] });
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
export declare function sequentialPatterns(count: number, { shape, sizeRange, angle, scale, contrast, fill, background, patchSize, }?: SequentialPatternOptions): PatternParams[];
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { Range } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Style presets for categorical palettes.
|
|
4
|
+
*
|
|
5
|
+
* Each preset defines hue, chroma and lightness ranges
|
|
6
|
+
* that produce a distinct visual mood.
|
|
7
|
+
*/
|
|
8
|
+
export declare const presets: {
|
|
9
|
+
readonly vif: {
|
|
10
|
+
readonly hueRange: Range;
|
|
11
|
+
readonly chromaRange: Range;
|
|
12
|
+
readonly lightnessRange: Range;
|
|
13
|
+
};
|
|
14
|
+
readonly pastel: {
|
|
15
|
+
readonly hueRange: Range;
|
|
16
|
+
readonly chromaRange: Range;
|
|
17
|
+
readonly lightnessRange: Range;
|
|
18
|
+
};
|
|
19
|
+
readonly sepia: {
|
|
20
|
+
readonly hueRange: Range;
|
|
21
|
+
readonly chromaRange: Range;
|
|
22
|
+
readonly lightnessRange: Range;
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Color temperature filters.
|
|
27
|
+
*
|
|
28
|
+
* Combined with a style preset (e.g. `{ ...presets.vif, ...temperature.chaude }`),
|
|
29
|
+
* they restrict the palette to warm or cool hues.
|
|
30
|
+
*
|
|
31
|
+
* Note: `chaude` exceeds 360° to cover the red → yellow transition
|
|
32
|
+
* without discontinuity.
|
|
33
|
+
*/
|
|
34
|
+
export declare const temperature: {
|
|
35
|
+
readonly mixte: {
|
|
36
|
+
readonly hueRange: Range;
|
|
37
|
+
};
|
|
38
|
+
readonly chaude: {
|
|
39
|
+
readonly hueRange: Range;
|
|
40
|
+
};
|
|
41
|
+
readonly froide: {
|
|
42
|
+
readonly hueRange: Range;
|
|
43
|
+
};
|
|
44
|
+
};
|
|
45
|
+
export type PresetName = keyof typeof presets;
|
|
46
|
+
export type TemperatureName = keyof typeof temperature;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { CSSColor, WebGLColor } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Resolves a complex CSS color to a usable value.
|
|
4
|
+
*
|
|
5
|
+
* **`"css"` format** (default): returns the color as computed by the browser
|
|
6
|
+
* (may be `oklch(…)`, `rgba(…)`, etc.).
|
|
7
|
+
*
|
|
8
|
+
* **`"webgl"` format**: draws a pixel and reads raw data to obtain a
|
|
9
|
+
* `[r, g, b, a]` tuple (0–255). This is the most reliable approach
|
|
10
|
+
* as it handles oklch, display-p3, lab, etc.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* resolveColor("color-mix(in oklch, red, blue 50%)");
|
|
15
|
+
* // → "oklch(0.546 0.223 351.6)" (browser-dependent)
|
|
16
|
+
*
|
|
17
|
+
* resolveColor("color-mix(in oklch, red, blue 50%)", { format: "webgl" });
|
|
18
|
+
* // → [188, 0, 182, 255]
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export declare function resolveColor(color: string, options?: {
|
|
22
|
+
format: "css";
|
|
23
|
+
}): CSSColor;
|
|
24
|
+
export declare function resolveColor(color: string, options: {
|
|
25
|
+
format: "webgl";
|
|
26
|
+
}): WebGLColor;
|
|
27
|
+
/**
|
|
28
|
+
* Resolves a full array of CSS colors.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* resolvePalette(palette, { format: "webgl" });
|
|
33
|
+
* // → [[255, 0, 0, 255], [0, 0, 255, 255], …]
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
export declare function resolvePalette(colors: CSSColor[], options?: {
|
|
37
|
+
format: "css";
|
|
38
|
+
}): CSSColor[];
|
|
39
|
+
export declare function resolvePalette(colors: CSSColor[], options: {
|
|
40
|
+
format: "webgl";
|
|
41
|
+
}): WebGLColor[];
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { CSSColor, SequentialPaletteOptions } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Generates a sequential palette (monochrome or two-tone).
|
|
4
|
+
*
|
|
5
|
+
* The start color is normalized to a light tone (chroma reduced according to the
|
|
6
|
+
* contrast profile to avoid a fluorescent effect), the end color to a dark tone.
|
|
7
|
+
* The lightness range is automatically adapted to the number of classes
|
|
8
|
+
* via the chosen contrast profile.
|
|
9
|
+
*
|
|
10
|
+
* Interpolation relies entirely on `color-mix(in oklch, …)`:
|
|
11
|
+
* no external dependency is needed — the browser does the computation.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* // 5-class monochrome palette
|
|
16
|
+
* sequential({ colorStart: "steelblue" });
|
|
17
|
+
*
|
|
18
|
+
* // 7-class two-tone palette, high contrast
|
|
19
|
+
* sequential({ colorStart: "#f4e285", colorEnd: "#1d3557", steps: 7, contrast: "high" });
|
|
20
|
+
* ```
|
|
21
|
+
*/
|
|
22
|
+
export declare function sequential({ colorStart, colorEnd, steps, contrast, }: SequentialPaletteOptions): CSSColor[];
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/** Contrast profile for sequential palettes */
|
|
2
|
+
export type ContrastMode = "low" | "normal" | "high";
|
|
3
|
+
/** Output format for color resolution */
|
|
4
|
+
export type ColorFormat = "css" | "webgl";
|
|
5
|
+
/** Resolved CSS color (e.g. "oklch(70% 0.15 230)") */
|
|
6
|
+
export type CSSColor = string;
|
|
7
|
+
/** WebGL color: tuple [r, g, b, a] with values 0–255 */
|
|
8
|
+
export type WebGLColor = [r: number, g: number, b: number, a: number];
|
|
9
|
+
/** Numeric range [min, max] */
|
|
10
|
+
export type Range = [min: number, max: number];
|
|
11
|
+
/** Contrast profile: lightness bounds for 3 classes and 9+ classes */
|
|
12
|
+
export interface ContrastProfile {
|
|
13
|
+
/** Start lightness [for 3 classes, for 9+ classes] */
|
|
14
|
+
start: Range;
|
|
15
|
+
/** End lightness [for 3 classes, for 9+ classes] */
|
|
16
|
+
end: Range;
|
|
17
|
+
}
|
|
18
|
+
/** Set of contrast profiles indexed by mode */
|
|
19
|
+
export type ContrastProfiles = Record<ContrastMode, ContrastProfile>;
|
|
20
|
+
/** Options for sequential palette generation */
|
|
21
|
+
export interface SequentialPaletteOptions {
|
|
22
|
+
/** Start CSS color – used for light tones */
|
|
23
|
+
colorStart: string;
|
|
24
|
+
/** End CSS color – if omitted, produces a monochrome palette */
|
|
25
|
+
colorEnd?: string;
|
|
26
|
+
/** Number of classes (default: 5) */
|
|
27
|
+
steps?: number;
|
|
28
|
+
/** Contrast profile (default: "normal") */
|
|
29
|
+
contrast?: ContrastMode;
|
|
30
|
+
}
|
|
31
|
+
/** Interpolation color space for divergent palettes */
|
|
32
|
+
export type DivergentColorSpace = "oklab" | "oklch";
|
|
33
|
+
/** Options for divergent palette generation */
|
|
34
|
+
export interface DivergentPaletteOptions {
|
|
35
|
+
/** Left-extreme color (valid CSS) */
|
|
36
|
+
colorA: string;
|
|
37
|
+
/** Right-extreme color (valid CSS) – if omitted, uses the complement of colorA */
|
|
38
|
+
colorB?: string;
|
|
39
|
+
/** Number of classes per side [left, right] (default: [3, 3]) */
|
|
40
|
+
steps?: [number, number];
|
|
41
|
+
/** Contrast profile (default: "normal") */
|
|
42
|
+
contrast?: ContrastMode;
|
|
43
|
+
/** Add a neutral center class (default: true) */
|
|
44
|
+
hasCenterClass?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* Color space for interpolating each ramp (default: "oklab").
|
|
47
|
+
* - "oklab": Cartesian path — smoother, avoids hue artifacts
|
|
48
|
+
* - "oklch": Circular path on the hue wheel — more saturated at the center
|
|
49
|
+
*/
|
|
50
|
+
colorSpace?: DivergentColorSpace;
|
|
51
|
+
}
|
|
52
|
+
/** Categorical color preset */
|
|
53
|
+
export interface CategoricalColorPreset {
|
|
54
|
+
hueRange?: Range;
|
|
55
|
+
chromaRange?: Range;
|
|
56
|
+
lightnessRange?: Range;
|
|
57
|
+
}
|
|
58
|
+
/** Options for categorical color generation */
|
|
59
|
+
export interface CategoricalColorOptions {
|
|
60
|
+
/** Hue range in degrees (default: [0, 360]) */
|
|
61
|
+
hueRange?: Range;
|
|
62
|
+
/** Hue offset (rotation) in degrees, applied to all colors (default: 0) */
|
|
63
|
+
hueOffset?: number;
|
|
64
|
+
/** Oklch chroma range (default: [0.15, 0.25]) */
|
|
65
|
+
chromaRange?: Range;
|
|
66
|
+
/** Oklch lightness range, values 0–1 (default: [0.5, 0.75]) */
|
|
67
|
+
lightnessRange?: Range;
|
|
68
|
+
}
|
|
69
|
+
/** Predefined categorical color presets */
|
|
70
|
+
export interface CategoricalPresets {
|
|
71
|
+
[key: string]: CategoricalColorPreset;
|
|
72
|
+
}
|
|
73
|
+
/** Color temperature filters */
|
|
74
|
+
export interface TemperaturePresets {
|
|
75
|
+
[key: string]: {
|
|
76
|
+
hueRange: Range;
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** Options for categorical pattern generation */
|
|
80
|
+
export interface CategoricalPatternOptions {
|
|
81
|
+
/** Shapes to cycle through (default: ["line", "circle", "plaid", "triangle"]) */
|
|
82
|
+
shapes?: string[];
|
|
83
|
+
/** Angle range in degrees (default: [0, 180]) */
|
|
84
|
+
angleRange?: Range;
|
|
85
|
+
/** Scale range (default: [2, 8]) */
|
|
86
|
+
scaleRange?: Range;
|
|
87
|
+
/** Fixed size – constant visual weight (default: 10) */
|
|
88
|
+
size?: number;
|
|
89
|
+
/** Fill color (default: "#ffffff") */
|
|
90
|
+
fill?: string;
|
|
91
|
+
/** Background color (default: "transparent") */
|
|
92
|
+
background?: string;
|
|
93
|
+
/** Enable patchSize (default: true) */
|
|
94
|
+
patchSize?: boolean;
|
|
95
|
+
/** Offset into the Van der Corput sequence (default: 0) */
|
|
96
|
+
vdcOffset?: number;
|
|
97
|
+
/**
|
|
98
|
+
* Automatically colorize patterns using `categorical`.
|
|
99
|
+
* - `true` → uses default `categorical` options
|
|
100
|
+
* - object → options passed to `categorical`
|
|
101
|
+
*/
|
|
102
|
+
colorize?: boolean | CategoricalColorOptions;
|
|
103
|
+
}
|
|
104
|
+
/** Options for sequential pattern generation */
|
|
105
|
+
export interface SequentialPatternOptions {
|
|
106
|
+
/** Pattern shape (default: "line") */
|
|
107
|
+
shape?: string;
|
|
108
|
+
/** Size range [small, large] (default: [4, 14]) */
|
|
109
|
+
sizeRange?: Range;
|
|
110
|
+
/** Fixed angle in degrees (default: 45) */
|
|
111
|
+
angle?: number;
|
|
112
|
+
/** Fixed scale (default: 4) */
|
|
113
|
+
scale?: number;
|
|
114
|
+
/** Contrast profile (default: "normal") */
|
|
115
|
+
contrast?: ContrastMode;
|
|
116
|
+
/** Fill color (default: "#ffffff") */
|
|
117
|
+
fill?: string;
|
|
118
|
+
/** Background color (default: "transparent") */
|
|
119
|
+
background?: string;
|
|
120
|
+
/** Enable patchSize (default: true) */
|
|
121
|
+
patchSize?: boolean;
|
|
122
|
+
}
|
|
123
|
+
/** Pattern parameters (compatible with motif.js) */
|
|
124
|
+
export interface PatternParams {
|
|
125
|
+
type: string;
|
|
126
|
+
angle: number;
|
|
127
|
+
scale: number;
|
|
128
|
+
size: number;
|
|
129
|
+
fill: string;
|
|
130
|
+
background: string;
|
|
131
|
+
patchSize: boolean;
|
|
132
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { ContrastMode, ContrastProfiles, Range } from "./types";
|
|
2
|
+
/**
|
|
3
|
+
* Predefined contrast profiles.
|
|
4
|
+
*
|
|
5
|
+
* Each profile defines start and end bounds as a range
|
|
6
|
+
* [value for 3 classes, value for 9+ classes].
|
|
7
|
+
* Interpolation is linear between these two extremes.
|
|
8
|
+
*
|
|
9
|
+
* Used for both lightness in color palettes
|
|
10
|
+
* and progressive size in pattern palettes.
|
|
11
|
+
*/
|
|
12
|
+
export declare const CONTRAST_PROFILES: ContrastProfiles;
|
|
13
|
+
/**
|
|
14
|
+
* Van der Corput sequence in base 2.
|
|
15
|
+
*
|
|
16
|
+
* Returns a real number in [0, 1) that splits the interval optimally.
|
|
17
|
+
* Guarantees that the first k points are always the k best-spaced ones.
|
|
18
|
+
*
|
|
19
|
+
* VdC(0) = 0, VdC(1) = 0.5, VdC(2) = 0.25, VdC(3) = 0.75, VdC(4) = 0.125…
|
|
20
|
+
*/
|
|
21
|
+
export declare function vanDerCorput(n: number): number;
|
|
22
|
+
/** Result of adaptive bounds computation */
|
|
23
|
+
export interface AdaptiveBounds {
|
|
24
|
+
start: number;
|
|
25
|
+
end: number;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Computes adaptive bounds based on the number of classes
|
|
29
|
+
* and the chosen contrast profile.
|
|
30
|
+
*
|
|
31
|
+
* Interpolation is linear: at 3 classes the "few classes" bound is used,
|
|
32
|
+
* at 9+ the "many classes" bound is used.
|
|
33
|
+
*
|
|
34
|
+
* This is the shared building block used for:
|
|
35
|
+
* - lightness in sequential color palettes
|
|
36
|
+
* - progressive size in sequential pattern palettes
|
|
37
|
+
*/
|
|
38
|
+
export declare function getAdaptiveBounds(steps: number, mode?: ContrastMode): AdaptiveBounds;
|
|
39
|
+
/**
|
|
40
|
+
* Linearly interpolates within a range [min, max] for a factor t ∈ [0, 1].
|
|
41
|
+
*/
|
|
42
|
+
export declare function lerp(range: Range, t: number): number;
|
package/package.json
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ateliercartographie/ok-palette",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Générateur de palettes de couleurs séquentielles, divergentes et catégorielles pour la dataviz et la cartographie",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/ok-palette.cjs",
|
|
7
|
+
"module": "./dist/ok-palette.js",
|
|
8
|
+
"types": "./dist/src/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/src/index.d.ts",
|
|
12
|
+
"import": "./dist/ok-palette.js",
|
|
13
|
+
"require": "./dist/ok-palette.cjs"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"dev": "vite serve demo",
|
|
21
|
+
"build": "tsc --noEmit && vite build && tsc --declaration --emitDeclarationOnly",
|
|
22
|
+
"preview": "vite preview",
|
|
23
|
+
"release:patch": "npm version patch && git push && git push --tags",
|
|
24
|
+
"release:minor": "npm version minor && git push && git push --tags",
|
|
25
|
+
"release:major": "npm version major && git push && git push --tags"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"color",
|
|
29
|
+
"palette",
|
|
30
|
+
"dataviz",
|
|
31
|
+
"cartography",
|
|
32
|
+
"oklch",
|
|
33
|
+
"sequential",
|
|
34
|
+
"divergent",
|
|
35
|
+
"categorical",
|
|
36
|
+
"pattern",
|
|
37
|
+
"motif"
|
|
38
|
+
],
|
|
39
|
+
"author": "Atelier de cartographie de Sciences Po",
|
|
40
|
+
"license": "ISC",
|
|
41
|
+
"repository": {
|
|
42
|
+
"type": "git",
|
|
43
|
+
"url": "https://github.com/AtelierCartographie/ok-palette"
|
|
44
|
+
},
|
|
45
|
+
"packageManager": "pnpm@10.17.1",
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@ateliercartographie/motif.js": "^0.1.4",
|
|
48
|
+
"typescript": "^5.9.3",
|
|
49
|
+
"vite": "^7.3.1"
|
|
50
|
+
}
|
|
51
|
+
}
|