@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 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
+ }