@ponchia/ui 0.10.0 → 0.12.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/CHANGELOG.md +84 -0
- package/MIGRATIONS.json +52 -9
- package/README.md +3 -3
- package/behaviors/forms.d.ts +1 -1
- package/behaviors/internal.d.ts +1 -1
- package/classes/classes.json +31 -2
- package/classes/index.d.ts +12 -0
- package/classes/index.js +13 -0
- package/css/annotations.css +2 -2
- package/css/app.css +3 -1
- package/css/command.css +4 -4
- package/css/dataviz.css +117 -64
- package/css/discussion.css +150 -0
- package/css/figure.css +6 -4
- package/css/generated.css +19 -12
- package/css/legend.css +14 -7
- package/css/report.css +25 -11
- package/css/sources.css +1 -1
- package/dist/bronto.css +1 -1
- package/dist/css/analytical.css +1 -1
- package/dist/css/annotations.css +1 -1
- package/dist/css/app.css +1 -1
- package/dist/css/command.css +1 -1
- package/dist/css/dataviz.css +1 -1
- package/dist/css/discussion.css +1 -0
- package/dist/css/figure.css +1 -1
- package/dist/css/generated.css +1 -1
- package/dist/css/legend.css +1 -1
- package/dist/css/report-kit.css +1 -1
- package/dist/css/report.css +1 -1
- package/dist/css/sources.css +1 -1
- package/docs/adr/0001-color-system.md +29 -0
- package/docs/architecture.md +1 -1
- package/docs/compositions.md +23 -2
- package/docs/contrast.md +24 -24
- package/docs/discussion.md +64 -0
- package/docs/figure.md +10 -1
- package/docs/frontier-primitives.md +5 -0
- package/docs/mermaid.md +1 -1
- package/docs/migrations/0.10-to-0.11.md +61 -0
- package/docs/migrations/0.11-to-0.12.md +47 -0
- package/docs/package-contract.md +14 -2
- package/docs/reference.md +18 -1
- package/docs/renderer.md +100 -0
- package/docs/reporting.md +9 -9
- package/docs/stability.md +4 -2
- package/docs/theming.md +29 -19
- package/docs/usage.md +12 -8
- package/docs/vega.md +24 -23
- package/llms.txt +8 -4
- package/package.json +18 -3
- package/renderer/index.d.ts +203 -0
- package/renderer/index.d.ts.map +1 -0
- package/renderer/index.js +650 -0
- package/tokens/charts.d.ts +16 -10
- package/tokens/charts.js +65 -49
- package/tokens/charts.json +77 -29
- package/tokens/mermaid.js +56 -56
- package/tokens/mermaid.json +56 -56
- package/tokens/vega.d.ts +3 -3
- package/tokens/vega.js +111 -72
- package/tokens/vega.json +198 -126
package/docs/theming.md
CHANGED
|
@@ -309,9 +309,11 @@ you have, so the one-accent discipline holds.
|
|
|
309
309
|
|
|
310
310
|
## Data-viz palette
|
|
311
311
|
|
|
312
|
-
Opt-in Tier-4
|
|
313
|
-
(
|
|
314
|
-
|
|
312
|
+
Opt-in Tier-4 categorical colour — **never UI chrome** (a build gate fails on
|
|
313
|
+
`var(--chart-*)` or `var(--cat-*)` in component CSS), and never in the default
|
|
314
|
+
bundle. One leaf carries eight fixed hues in two namespaces: `--chart-*` for
|
|
315
|
+
data-viz series and ramps, and `--cat-*` for categorical **identity** — a tag,
|
|
316
|
+
a participant, a user-chosen tint.
|
|
315
317
|
|
|
316
318
|
```html
|
|
317
319
|
<link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
|
|
@@ -320,28 +322,36 @@ default bundle.
|
|
|
320
322
|
```js
|
|
321
323
|
// resolved hex for canvas / SVG / Chart.js etc.
|
|
322
324
|
import charts from '@ponchia/ui/charts.json' with { type: 'json' };
|
|
323
|
-
const series = charts.dark.categorical; // ['#
|
|
325
|
+
const series = charts.dark.categorical; // ['#3987e5', '#d95926', …] — blue first
|
|
324
326
|
```
|
|
325
327
|
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
328
|
+
For a page that switches theme, skin, contrast or the OLED surface at runtime,
|
|
329
|
+
read the live values with [`@ponchia/ui/renderer`](renderer.md) instead of the
|
|
330
|
+
static JSON.
|
|
331
|
+
|
|
332
|
+
- **Categorical `--chart-1..8` = `--cat-1..8`** — blue, orange, aqua, yellow,
|
|
333
|
+
magenta, green, violet, red, in that fixed order (`CATEGORICAL_HUES` names
|
|
334
|
+
them). No slot is the accent, so an ordinary first series never reads as an
|
|
335
|
+
alert. `check:charts` measures each theme against the panel, the page and
|
|
336
|
+
the OLED surfaces: OKLCH lightness inside the theme's band, chroma above the
|
|
337
|
+
grey floor, adjacent slots separated under simulated protanopia and
|
|
338
|
+
deuteranopia and in normal vision. Slots under 3:1 against a surface are
|
|
339
|
+
reported in the gate output; relief is the pattern fill or a direct label.
|
|
340
|
+
Any two slots can meet in a scatter or a map, so pair colour with pattern
|
|
341
|
+
there.
|
|
342
|
+
- **Identity `--cat-N-tint` / `--cat-N-ink`** — a 16% wash of the hue over
|
|
343
|
+
`--panel` (it follows a skin's or OLED's panel) and a text colour that holds
|
|
344
|
+
4.5:1 on the panel, the page and its own tint. Use them for a tag chip, a
|
|
345
|
+
participant's name, or a user-chosen highlight — never for status.
|
|
346
|
+
- **Sequential `--chart-seq-1..5`** — one blue hue; step 1 sits nearest the
|
|
347
|
+
surface (pale in light, deep in dark), for heatmaps/intensity. **Diverging
|
|
348
|
+
`--chart-div-1..7`** — blue↔neutral↔orange, for ±/gains-losses.
|
|
339
349
|
- **Pattern fills `--chart-pattern-1..8`** — a dot-matrix second channel so
|
|
340
350
|
colour is never the sole signal (WCAG 1.4.1). Pair colour N with pattern N:
|
|
341
351
|
`background: var(--chart-2); background-image: var(--chart-pattern-2); background-size: var(--chart-pattern-size); --chart-pattern-ink: rgb(0 0 0 / .34);`
|
|
342
352
|
- A chart colour's WCAG ratio vs the background is published **advisory** in
|
|
343
|
-
[contrast.md](contrast.md) (a fill is not body text) —
|
|
344
|
-
|
|
353
|
+
[contrast.md](contrast.md) (a fill is not body text) — for thin lines or
|
|
354
|
+
points use the slot's `--cat-N-ink`, or lean on the pattern.
|
|
345
355
|
|
|
346
356
|
## Accessibility markup contracts
|
|
347
357
|
|
package/docs/usage.md
CHANGED
|
@@ -584,18 +584,22 @@ phosphor-green | e-ink"` — a **root-level** colorway (apply on `<html>`, like
|
|
|
584
584
|
|
|
585
585
|
`@ponchia/ui/css/dataviz.css` (opt-in) adds a Tier-4 chart palette for
|
|
586
586
|
dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
|
|
587
|
-
`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills)
|
|
588
|
-
|
|
589
|
-
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
587
|
+
`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills), plus
|
|
588
|
+
the same eight hues as categorical identity: `--cat-N`, `--cat-N-tint` and
|
|
589
|
+
`--cat-N-ink` for tags, participants and user-chosen tints.
|
|
590
|
+
|
|
591
|
+
- **Use it for categories, never for chrome or status.** A build gate fails if
|
|
592
|
+
`var(--chart-*)` or `var(--cat-*)` appears in component CSS. Style buttons
|
|
593
|
+
and badges with the accent/status tiers.
|
|
594
|
+
- **No slot is the accent.** The order is fixed (blue, orange, aqua, yellow,
|
|
595
|
+
magenta, green, violet, red) and adjacent slots are gated for separation
|
|
596
|
+
under simulated protanopia/deuteranopia and in normal vision.
|
|
594
597
|
- **Always pair colour with pattern** (`--chart-pattern-N`) and/or a direct
|
|
595
598
|
label — never colour alone (WCAG 1.4.1):
|
|
596
599
|
`background: var(--chart-3); background-image: var(--chart-pattern-3); background-size: var(--chart-pattern-size);`
|
|
597
600
|
- **In JS** (Chart.js, canvas, SVG): import resolved hex from
|
|
598
|
-
`@ponchia/ui/charts.json` (`{ light, dark }
|
|
601
|
+
`@ponchia/ui/charts.json` (`{ hues, light, dark }`), or read the live page
|
|
602
|
+
with [`@ponchia/ui/renderer`](renderer.md) when it can change skin or theme.
|
|
599
603
|
Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
|
|
600
604
|
"Data-viz palette".
|
|
601
605
|
|
package/docs/vega.md
CHANGED
|
@@ -113,18 +113,23 @@ colours are **baked into the output** and parsed by `d3-color`, which understand
|
|
|
113
113
|
real hex/rgb but **not** `var()` (nor `oklch()`). So the config ships **resolved
|
|
114
114
|
hex per theme**, projected from the same token source as
|
|
115
115
|
[`tokens/resolved.json`](./architecture.md) / [`charts.json`](./theming.md).
|
|
116
|
-
Re-call `brontoVegaConfig()` when the theme toggles and re-embed.
|
|
116
|
+
Re-call `brontoVegaConfig()` when the theme toggles and re-embed. A page that
|
|
117
|
+
switches skin, contrast or the OLED surface at runtime cannot be served by a
|
|
118
|
+
per-theme snapshot: build the config from the live page with
|
|
119
|
+
[`@ponchia/ui/renderer`](./renderer.md) — `vegaConfig(readTokens())` is the
|
|
120
|
+
same mapping these files are generated from.
|
|
117
121
|
|
|
118
122
|
### What the slots paint
|
|
119
123
|
|
|
120
|
-
The
|
|
121
|
-
|
|
124
|
+
The chrome stays quiet and neutral; colour is spent on data. The plot has no
|
|
125
|
+
frame (a chart already sits on a panel), and a single series takes the first
|
|
126
|
+
categorical hue rather than the alert accent:
|
|
122
127
|
|
|
123
128
|
| Slot | Paint | bronto token |
|
|
124
129
|
| --- | --- | --- |
|
|
125
|
-
| `background` | Chart canvas | `--bg` |
|
|
126
|
-
| `view.stroke` | Plot frame |
|
|
127
|
-
| `mark.color` | Default / single-series mark | `--
|
|
130
|
+
| `background` | Chart canvas | `--bg` (runtime default: transparent) |
|
|
131
|
+
| `view.stroke` | Plot frame | none (`null`) |
|
|
132
|
+
| `mark.color` | Default / single-series mark | `--chart-1` |
|
|
128
133
|
| `rule.color` | Reference rules, annotations | `--line-strong` |
|
|
129
134
|
| `axis.domainColor` · `tickColor` | Axis line · ticks | `--line-strong` |
|
|
130
135
|
| `axis.gridColor` | Gridlines | `--line` |
|
|
@@ -132,7 +137,8 @@ one chromatic default (series 1 / the lone mark), never the chrome:
|
|
|
132
137
|
| `text.color` | Free `text`/`label` marks | `--text` |
|
|
133
138
|
| `legend.*` · `header.*` · `title.*` | Legend, facet headers, title | `--text-soft` / `--text` / `--text-dim` |
|
|
134
139
|
| `*.font` / `*Font` | All text | `--sans` |
|
|
135
|
-
| `
|
|
140
|
+
| `rect`/`arc`/`area` `.stroke` | Gap between adjacent fills | `--panel` |
|
|
141
|
+
| `range.category` | 8-series categorical palette | `charts.json` categorical (blue first) |
|
|
136
142
|
| `range.ordinal` · `ramp` · `heatmap` | Single-hue sequential ramp | `charts.json` sequential |
|
|
137
143
|
| `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
|
|
138
144
|
|
|
@@ -143,14 +149,12 @@ series needs the redundant second channel, drive the mark's fill from the
|
|
|
143
149
|
|
|
144
150
|
### Spending the accent
|
|
145
151
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
rule the rest of the system follows. Two small helpers hand you the exact
|
|
153
|
-
per-theme hexes so you never hard-code a palette array index:
|
|
152
|
+
No categorical slot is the accent, so an ordinary chart never reads as an
|
|
153
|
+
alert. To emphasise one mark, paint just that mark with the accent and leave
|
|
154
|
+
the rest neutral — the same "reserve the accent for the one thing a reader must
|
|
155
|
+
not miss" rule the rest of the system follows. Two small helpers hand you the
|
|
156
|
+
exact per-theme hexes (baked into the generated files; Vega output does not
|
|
157
|
+
live-reskin from `--accent`):
|
|
154
158
|
|
|
155
159
|
```js
|
|
156
160
|
import { brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
|
|
@@ -171,14 +175,11 @@ const spec = {
|
|
|
171
175
|
};
|
|
172
176
|
```
|
|
173
177
|
|
|
174
|
-
`brontoVegaAccent(theme)` is
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
`--chart-8`, so a [legend](./legends.md#swatch-colour) for an accent-rationed
|
|
180
|
-
chart keys those two series with `ui-legend__swatch--1` and
|
|
181
|
-
`ui-legend__swatch--8` — the swatches mirror the marks exactly.
|
|
178
|
+
`brontoVegaAccent(theme)` is the resolved `--accent` and `brontoVegaNeutral(theme)`
|
|
179
|
+
the resolved `--text-dim`; re-read both when the theme toggles. A
|
|
180
|
+
[legend](./legends.md#swatch-colour) for an accent-rationed chart keys the two
|
|
181
|
+
with inline swatch colours (`style="--chart-color: …"`), not with categorical
|
|
182
|
+
slots.
|
|
182
183
|
|
|
183
184
|
### Selecting the themed ramp in a spec
|
|
184
185
|
|
package/llms.txt
CHANGED
|
@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
|
|
|
45
45
|
<!-- installed locally -->
|
|
46
46
|
<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
|
|
47
47
|
<!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
|
|
48
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.
|
|
48
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/<leaf>.css" />
|
|
49
49
|
```
|
|
50
50
|
|
|
51
51
|
The flattened default bundle is `dist/bronto.css` (bundler shorthand
|
|
@@ -183,7 +183,9 @@ Charting is the same path: bronto does NOT ship a chart component (a chart needs
|
|
|
183
183
|
scales + data binding, which the analytical layer refuses). For charts, recommend
|
|
184
184
|
Vega-Lite — a declarative JSON spec an external system can emit — themed by the
|
|
185
185
|
on-brand `config` (resolved hex; Vega bakes colours into SVG/canvas, can't read
|
|
186
|
-
`var()`). `range.category` is the `--chart-*` palette
|
|
186
|
+
`var()`). `range.category` is the `--chart-*` palette (blue first; no slot is the
|
|
187
|
+
accent). For a live page that switches skin or theme, build the same config at
|
|
188
|
+
runtime with `vegaConfig(readTokens())` from `@ponchia/ui/renderer`:
|
|
187
189
|
|
|
188
190
|
```js
|
|
189
191
|
import { brontoVegaConfig, brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
|
|
@@ -204,8 +206,10 @@ accent-filled DOM control, set `--button-text`. Details: `docs/vega.md`. (Observ
|
|
|
204
206
|
Plot works too — it inherits the page CSS, so it needs even less theming;
|
|
205
207
|
Vega-Lite is the recommended LLM-emittable path.)
|
|
206
208
|
|
|
207
|
-
`--chart-1..8` (categorical
|
|
208
|
-
simulated protan/deutan
|
|
209
|
+
`--chart-1..8` (categorical: blue, orange, aqua, yellow, magenta, green, violet,
|
|
210
|
+
red; adjacent slots gated under simulated protan/deutan), `--cat-N` /
|
|
211
|
+
`--cat-N-tint` / `--cat-N-ink` (the same hues as tag/participant identity),
|
|
212
|
+
`--chart-seq-*` (sequential), `--chart-div-*`
|
|
209
213
|
(diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
|
|
210
214
|
pattern N; colour is never the sole signal). Details in `docs/theming.md`.
|
|
211
215
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ponchia/ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
|
|
6
6
|
"keywords": [
|
|
@@ -58,6 +58,7 @@
|
|
|
58
58
|
"schemas",
|
|
59
59
|
"annotations",
|
|
60
60
|
"connectors",
|
|
61
|
+
"renderer",
|
|
61
62
|
"shiki",
|
|
62
63
|
"llms.txt",
|
|
63
64
|
"CHANGELOG.md",
|
|
@@ -78,9 +79,11 @@
|
|
|
78
79
|
"docs/vega.md",
|
|
79
80
|
"docs/figure.md",
|
|
80
81
|
"docs/annotations.md",
|
|
82
|
+
"docs/discussion.md",
|
|
81
83
|
"docs/legends.md",
|
|
82
84
|
"docs/marks.md",
|
|
83
85
|
"docs/connectors.md",
|
|
86
|
+
"docs/renderer.md",
|
|
84
87
|
"docs/spotlight.md",
|
|
85
88
|
"docs/crosshair.md",
|
|
86
89
|
"docs/selection.md",
|
|
@@ -117,7 +120,9 @@
|
|
|
117
120
|
"docs/compositions.md",
|
|
118
121
|
"docs/adr/0005-productive-tools-and-editorial-reports.md",
|
|
119
122
|
"docs/migrations/0.9-to-0.10.md",
|
|
120
|
-
"docs/adr/0006-trusted-publishing.md"
|
|
123
|
+
"docs/adr/0006-trusted-publishing.md",
|
|
124
|
+
"docs/migrations/0.10-to-0.11.md",
|
|
125
|
+
"docs/migrations/0.11-to-0.12.md"
|
|
121
126
|
],
|
|
122
127
|
"style": "./dist/bronto.css",
|
|
123
128
|
"scripts": {
|
|
@@ -362,6 +367,7 @@
|
|
|
362
367
|
"./docs/legends.md": "./docs/legends.md",
|
|
363
368
|
"./docs/marks.md": "./docs/marks.md",
|
|
364
369
|
"./docs/connectors.md": "./docs/connectors.md",
|
|
370
|
+
"./docs/renderer.md": "./docs/renderer.md",
|
|
365
371
|
"./docs/spotlight.md": "./docs/spotlight.md",
|
|
366
372
|
"./docs/crosshair.md": "./docs/crosshair.md",
|
|
367
373
|
"./docs/selection.md": "./docs/selection.md",
|
|
@@ -498,6 +504,10 @@
|
|
|
498
504
|
"types": "./connectors/index.d.ts",
|
|
499
505
|
"default": "./connectors/index.js"
|
|
500
506
|
},
|
|
507
|
+
"./renderer": {
|
|
508
|
+
"types": "./renderer/index.d.ts",
|
|
509
|
+
"default": "./renderer/index.js"
|
|
510
|
+
},
|
|
501
511
|
"./skins": {
|
|
502
512
|
"types": "./tokens/skins.d.ts",
|
|
503
513
|
"default": "./tokens/skins.js"
|
|
@@ -526,7 +536,12 @@
|
|
|
526
536
|
"./docs/compositions.md": "./docs/compositions.md",
|
|
527
537
|
"./docs/adr/0005-productive-tools-and-editorial-reports.md": "./docs/adr/0005-productive-tools-and-editorial-reports.md",
|
|
528
538
|
"./docs/migrations/0.9-to-0.10.md": "./docs/migrations/0.9-to-0.10.md",
|
|
529
|
-
"./docs/adr/0006-trusted-publishing.md": "./docs/adr/0006-trusted-publishing.md"
|
|
539
|
+
"./docs/adr/0006-trusted-publishing.md": "./docs/adr/0006-trusted-publishing.md",
|
|
540
|
+
"./docs/migrations/0.10-to-0.11.md": "./docs/migrations/0.10-to-0.11.md",
|
|
541
|
+
"./docs/migrations/0.11-to-0.12.md": "./docs/migrations/0.11-to-0.12.md",
|
|
542
|
+
"./css/discussion.css": "./dist/css/discussion.css",
|
|
543
|
+
"./css/unlayered/discussion.css": "./css/discussion.css",
|
|
544
|
+
"./docs/discussion.md": "./docs/discussion.md"
|
|
530
545
|
},
|
|
531
546
|
"overrides": {
|
|
532
547
|
"adm-zip": "0.6.0",
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse a resolved CSS colour to sRGB, gamut-clipped: hex, `rgb()`, `hsl()`,
|
|
3
|
+
* `oklch()`, `oklab()`, `lab()`, `lch()`, `color(srgb | srgb-linear |
|
|
4
|
+
* display-p3 | xyz | xyz-d65 | xyz-d50 …)` and `transparent`. Anything else —
|
|
5
|
+
* `var()`, `color-mix()`, `light-dark()`, a named colour — returns null; use
|
|
6
|
+
* `resolveColor()` to have the browser compute it first.
|
|
7
|
+
* @param {string} value
|
|
8
|
+
* @returns {Rgba | null}
|
|
9
|
+
*/
|
|
10
|
+
export function parseColor(value: string): Rgba | null;
|
|
11
|
+
/**
|
|
12
|
+
* Serialize for a renderer: `#rrggbb` when opaque, `rgba(r, g, b, a)` when
|
|
13
|
+
* not — the two forms canvas, SVG, d3-color, xterm, three.js and MapLibre
|
|
14
|
+
* all accept.
|
|
15
|
+
* @param {Rgba} color
|
|
16
|
+
*/
|
|
17
|
+
export function formatColor({ r, g, b, alpha }: Rgba): string;
|
|
18
|
+
/**
|
|
19
|
+
* Resolve any CSS colour expression to a renderer literal, using the browser
|
|
20
|
+
* for what `parseColor()` cannot compute (`var()`, `color-mix()`,
|
|
21
|
+
* `light-dark()`, named colours). Returns null for an invalid colour or when no
|
|
22
|
+
* document is available.
|
|
23
|
+
* @param {string} value
|
|
24
|
+
* @param {{ element?: Element }} [options] Context for `var()` and `light-dark()`.
|
|
25
|
+
*/
|
|
26
|
+
export function resolveColor(value: string, options?: {
|
|
27
|
+
element?: Element;
|
|
28
|
+
}): string | null;
|
|
29
|
+
/**
|
|
30
|
+
* Resolve the page's bronto tokens for a renderer. Reads custom properties as
|
|
31
|
+
* computed on `element` (default: the root), so a subtree that re-points them
|
|
32
|
+
* is honoured. When the categorical leaf (`css/dataviz.css`) is not loaded,
|
|
33
|
+
* the categorical, sequential and diverging sets fall back to the packaged
|
|
34
|
+
* palette for the resolved scheme. Without a DOM it returns the packaged light
|
|
35
|
+
* (or `options.scheme`) values.
|
|
36
|
+
* @param {Element} [element]
|
|
37
|
+
* @param {{ scheme?: 'light' | 'dark' }} [options] Force the scheme instead of reading the background.
|
|
38
|
+
* @returns {RendererTokens}
|
|
39
|
+
*/
|
|
40
|
+
export function readTokens(element?: Element, options?: {
|
|
41
|
+
scheme?: "light" | "dark";
|
|
42
|
+
}): RendererTokens;
|
|
43
|
+
/**
|
|
44
|
+
* Call `callback` with fresh tokens whenever they change: after an attribute
|
|
45
|
+
* on the root changes (`data-theme`, `data-bronto-skin`, `data-contrast`,
|
|
46
|
+
* `data-surface`, `data-density`, `class`, `style`) and a token's value moved
|
|
47
|
+
* with it, or when the system colour scheme or contrast preference changes.
|
|
48
|
+
* A host that writes unrelated inline styles on the root every frame costs one
|
|
49
|
+
* computed-style read per frame, not a re-resolution. Calls are coalesced to
|
|
50
|
+
* one per animation frame. Returns a function that stops observing.
|
|
51
|
+
* @param {(tokens: RendererTokens) => void} callback
|
|
52
|
+
* @param {{ element?: Element, signal?: AbortSignal }} [options]
|
|
53
|
+
* @returns {() => void}
|
|
54
|
+
*/
|
|
55
|
+
export function observeTokens(callback: (tokens: RendererTokens) => void, options?: {
|
|
56
|
+
element?: Element;
|
|
57
|
+
signal?: AbortSignal;
|
|
58
|
+
}): () => void;
|
|
59
|
+
/**
|
|
60
|
+
* A Vega-Lite (default) or Vega `config` from resolved tokens: quiet chrome in
|
|
61
|
+
* the bronto inks, the categorical palette as `range.category` (a single
|
|
62
|
+
* series takes its first hue), the sequential ramp for ordinal/ramp/heatmap
|
|
63
|
+
* scales and the diverging ramp for diverging ones. A spec's own `config`
|
|
64
|
+
* still wins where Vega merges it over this one.
|
|
65
|
+
* @param {RendererTokens} tokens
|
|
66
|
+
* @param {{ mode?: 'vega-lite' | 'vega', narrow?: boolean, background?: string }} [options]
|
|
67
|
+
* `narrow` moves the legend under the plot and thins ticks for a small
|
|
68
|
+
* container; `background` defaults to transparent so the host surface shows.
|
|
69
|
+
* @returns {Record<string, any>}
|
|
70
|
+
*/
|
|
71
|
+
export function vegaConfig(tokens: RendererTokens, options?: {
|
|
72
|
+
mode?: "vega-lite" | "vega";
|
|
73
|
+
narrow?: boolean;
|
|
74
|
+
background?: string;
|
|
75
|
+
}): Record<string, any>;
|
|
76
|
+
/**
|
|
77
|
+
* An xterm.js `ITheme` from resolved tokens: page ink on the page background,
|
|
78
|
+
* the accent as the cursor, status colours for red/green/yellow/blue and the
|
|
79
|
+
* categorical magenta and aqua for magenta/cyan, so all six ANSI hues differ.
|
|
80
|
+
* @param {RendererTokens} tokens
|
|
81
|
+
* @returns {Record<string, string>}
|
|
82
|
+
*/
|
|
83
|
+
export function xtermTheme(tokens: RendererTokens): Record<string, string>;
|
|
84
|
+
/**
|
|
85
|
+
* A colour as sRGB channels (0–255) and alpha (0–1).
|
|
86
|
+
*/
|
|
87
|
+
export type Rgba = {
|
|
88
|
+
r: number;
|
|
89
|
+
g: number;
|
|
90
|
+
b: number;
|
|
91
|
+
alpha: number;
|
|
92
|
+
};
|
|
93
|
+
/**
|
|
94
|
+
* The bronto roles a renderer draws with, resolved to literals: opaque colours
|
|
95
|
+
* as `#rrggbb`, translucent ones as `rgba(r, g, b, a)`.
|
|
96
|
+
*/
|
|
97
|
+
export type RendererTokens = {
|
|
98
|
+
/**
|
|
99
|
+
* The resolved scheme of the page background.
|
|
100
|
+
*/
|
|
101
|
+
scheme: "light" | "dark";
|
|
102
|
+
/**
|
|
103
|
+
* Page background (`--bg`).
|
|
104
|
+
*/
|
|
105
|
+
bg: string;
|
|
106
|
+
/**
|
|
107
|
+
* A lifted page background (`--bg-elevated`).
|
|
108
|
+
*/
|
|
109
|
+
bgElevated: string;
|
|
110
|
+
/**
|
|
111
|
+
* The surface a renderer usually draws on (`--panel`).
|
|
112
|
+
*/
|
|
113
|
+
panel: string;
|
|
114
|
+
/**
|
|
115
|
+
* A raised surface (`--panel-strong`).
|
|
116
|
+
*/
|
|
117
|
+
panelStrong: string;
|
|
118
|
+
/**
|
|
119
|
+
* Primary ink (`--text`).
|
|
120
|
+
*/
|
|
121
|
+
text: string;
|
|
122
|
+
/**
|
|
123
|
+
* Secondary ink (`--text-soft`).
|
|
124
|
+
*/
|
|
125
|
+
textSoft: string;
|
|
126
|
+
/**
|
|
127
|
+
* Tertiary ink (`--text-dim`).
|
|
128
|
+
*/
|
|
129
|
+
textDim: string;
|
|
130
|
+
/**
|
|
131
|
+
* Hairline and grid (`--line`).
|
|
132
|
+
*/
|
|
133
|
+
line: string;
|
|
134
|
+
/**
|
|
135
|
+
* Axis, domain and rule (`--line-strong`).
|
|
136
|
+
*/
|
|
137
|
+
lineStrong: string;
|
|
138
|
+
/**
|
|
139
|
+
* The one accent (`--accent`).
|
|
140
|
+
*/
|
|
141
|
+
accent: string;
|
|
142
|
+
/**
|
|
143
|
+
* Accent as text on the page (`--accent-text`).
|
|
144
|
+
*/
|
|
145
|
+
accentText: string;
|
|
146
|
+
/**
|
|
147
|
+
* Ink on an accent fill (`--on-accent`).
|
|
148
|
+
*/
|
|
149
|
+
onAccent: string;
|
|
150
|
+
/**
|
|
151
|
+
* Focus ring (`--focus-ring`).
|
|
152
|
+
*/
|
|
153
|
+
focus: string;
|
|
154
|
+
/**
|
|
155
|
+
* A translucent selection wash over `panel`.
|
|
156
|
+
*/
|
|
157
|
+
selection: string;
|
|
158
|
+
/**
|
|
159
|
+
* Status: success.
|
|
160
|
+
*/
|
|
161
|
+
success: string;
|
|
162
|
+
/**
|
|
163
|
+
* Status: warning.
|
|
164
|
+
*/
|
|
165
|
+
warning: string;
|
|
166
|
+
/**
|
|
167
|
+
* Status: danger.
|
|
168
|
+
*/
|
|
169
|
+
danger: string;
|
|
170
|
+
/**
|
|
171
|
+
* Status: info.
|
|
172
|
+
*/
|
|
173
|
+
info: string;
|
|
174
|
+
/**
|
|
175
|
+
* The sans font stack.
|
|
176
|
+
*/
|
|
177
|
+
sans: string;
|
|
178
|
+
/**
|
|
179
|
+
* The monospace font stack.
|
|
180
|
+
*/
|
|
181
|
+
mono: string;
|
|
182
|
+
/**
|
|
183
|
+
* Eight categorical hues, fixed order.
|
|
184
|
+
*/
|
|
185
|
+
categorical: string[];
|
|
186
|
+
/**
|
|
187
|
+
* Each hue's wash over `panel`.
|
|
188
|
+
*/
|
|
189
|
+
categoricalTint: string[];
|
|
190
|
+
/**
|
|
191
|
+
* Each hue as text on `panel` and its tint.
|
|
192
|
+
*/
|
|
193
|
+
categoricalInk: string[];
|
|
194
|
+
/**
|
|
195
|
+
* One-hue ramp; step 1 nearest the surface.
|
|
196
|
+
*/
|
|
197
|
+
sequential: string[];
|
|
198
|
+
/**
|
|
199
|
+
* Negative … neutral … positive ramp.
|
|
200
|
+
*/
|
|
201
|
+
diverging: string[];
|
|
202
|
+
};
|
|
203
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AAkOA;;;;;;;;GAQG;AACH,kCAHW,MAAM,GACJ,IAAI,GAAG,IAAI,CAcvB;AAED;;;;;GAKG;AACH,gDAFW,IAAI,UAMd;AAED;;;;;;;GAOG;AACH,oCAHW,MAAM,YACN;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,iBAqB/B;AAkCD;;;;;;;;;;GAUG;AACH,qCAJW,OAAO,YACP;IAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,GAC3B,cAAc,CA6E1B;AAqDD;;;;;;;;;;;GAWG;AACH,wCAJW,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,YAChC;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACzC,MAAM,IAAI,CAqDtB;AAID;;;;;;;;;;;GAWG;AACH,mCANW,cAAc,YACd;IAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAGpE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA6E/B;AAED;;;;;;GAMG;AACH,mCAHW,cAAc,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BlC;;;;mBAjnBY;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;;;;;;;;;YAOjD,OAAO,GAAG,MAAM;;;;QAChB,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;iBACN,MAAM;;;;UACN,MAAM;;;;cACN,MAAM;;;;aACN,MAAM;;;;UACN,MAAM;;;;gBACN,MAAM;;;;YACN,MAAM;;;;gBACN,MAAM;;;;cACN,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;UACN,MAAM;;;;UACN,MAAM;;;;UACN,MAAM;;;;iBACN,MAAM,EAAE;;;;qBACR,MAAM,EAAE;;;;oBACR,MAAM,EAAE;;;;gBACR,MAAM,EAAE;;;;eACR,MAAM,EAAE"}
|