@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.
Files changed (62) hide show
  1. package/CHANGELOG.md +84 -0
  2. package/MIGRATIONS.json +52 -9
  3. package/README.md +3 -3
  4. package/behaviors/forms.d.ts +1 -1
  5. package/behaviors/internal.d.ts +1 -1
  6. package/classes/classes.json +31 -2
  7. package/classes/index.d.ts +12 -0
  8. package/classes/index.js +13 -0
  9. package/css/annotations.css +2 -2
  10. package/css/app.css +3 -1
  11. package/css/command.css +4 -4
  12. package/css/dataviz.css +117 -64
  13. package/css/discussion.css +150 -0
  14. package/css/figure.css +6 -4
  15. package/css/generated.css +19 -12
  16. package/css/legend.css +14 -7
  17. package/css/report.css +25 -11
  18. package/css/sources.css +1 -1
  19. package/dist/bronto.css +1 -1
  20. package/dist/css/analytical.css +1 -1
  21. package/dist/css/annotations.css +1 -1
  22. package/dist/css/app.css +1 -1
  23. package/dist/css/command.css +1 -1
  24. package/dist/css/dataviz.css +1 -1
  25. package/dist/css/discussion.css +1 -0
  26. package/dist/css/figure.css +1 -1
  27. package/dist/css/generated.css +1 -1
  28. package/dist/css/legend.css +1 -1
  29. package/dist/css/report-kit.css +1 -1
  30. package/dist/css/report.css +1 -1
  31. package/dist/css/sources.css +1 -1
  32. package/docs/adr/0001-color-system.md +29 -0
  33. package/docs/architecture.md +1 -1
  34. package/docs/compositions.md +23 -2
  35. package/docs/contrast.md +24 -24
  36. package/docs/discussion.md +64 -0
  37. package/docs/figure.md +10 -1
  38. package/docs/frontier-primitives.md +5 -0
  39. package/docs/mermaid.md +1 -1
  40. package/docs/migrations/0.10-to-0.11.md +61 -0
  41. package/docs/migrations/0.11-to-0.12.md +47 -0
  42. package/docs/package-contract.md +14 -2
  43. package/docs/reference.md +18 -1
  44. package/docs/renderer.md +100 -0
  45. package/docs/reporting.md +9 -9
  46. package/docs/stability.md +4 -2
  47. package/docs/theming.md +29 -19
  48. package/docs/usage.md +12 -8
  49. package/docs/vega.md +24 -23
  50. package/llms.txt +8 -4
  51. package/package.json +18 -3
  52. package/renderer/index.d.ts +203 -0
  53. package/renderer/index.d.ts.map +1 -0
  54. package/renderer/index.js +650 -0
  55. package/tokens/charts.d.ts +16 -10
  56. package/tokens/charts.js +65 -49
  57. package/tokens/charts.json +77 -29
  58. package/tokens/mermaid.js +56 -56
  59. package/tokens/mermaid.json +56 -56
  60. package/tokens/vega.d.ts +3 -3
  61. package/tokens/vega.js +111 -72
  62. 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 chart colours for dashboards — **charts only, never UI chrome**
313
- (a build gate fails on `var(--chart-*)` in component CSS), and never in the
314
- default bundle.
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; // ['#ff3b41', '#e69f00', …] — series 0 = accent
325
+ const series = charts.dark.categorical; // ['#3987e5', '#d95926', …] — blue first
324
326
  ```
325
327
 
326
- - **Categorical `--chart-1..8`** — hybrid accent-led: series 1 is the live
327
- `var(--accent)` (your brand leads), series 2–8 are the Okabe-Ito
328
- colourblind-safe set. The set is **gated for mutual distinguishability under
329
- normal + simulated protanopia/deuteranopia/tritanopia** (OKLab ΔE).
330
- **Caveat — the CVD gate measures the SHIPPED default accent.** Series 1 is
331
- `var(--accent)`, so if you re-skin `--accent` you change series 1 but not the
332
- Okabe-Ito 2–8, and the gate never re-checks your custom hue: a brand close to
333
- series 3's orange can collide for a deuteranope. If a re-brand drives data-viz,
334
- re-verify your accent against the set, or pin `--chart-1` to a fixed Okabe-Ito
335
- value (`--chart-1: #0072b2`) and let your brand lead the UI only.
336
- - **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
337
- heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
338
- for ±/gains-losses.
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) — pick a darker series
344
- for thin lines/points, or lean on the pattern.
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
- - **Use it for charts only.** These are not UI tokens — a build gate fails if
590
- `var(--chart-*)` appears in component CSS. Style buttons/badges with the
591
- accent/status tiers, not chart colours.
592
- - **Series 1 is the accent**, so your brand leads the palette; series 2–8 are a
593
- colourblind-safe set (gated for distinctness under protan/deutan/tritan).
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 }`, series 1 = the resolved accent).
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 config keeps a chart **monochrome by default** — the rationed accent is the
121
- one chromatic default (series 1 / the lone mark), never the chrome:
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 | `--line` |
127
- | `mark.color` | Default / single-series mark | `--accent` |
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
- | `range.category` | 8-series categorical palette | `charts.json` categorical (series 1 = accent) |
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
- Series 1 of `range.category` resolves to the accent (per theme), so a single-series
147
- chart and the first category carry the accent automatically — baked into the
148
- generated `config`, so regenerate the config and re-render to change it (Vega output
149
- does not live-reskin from `--accent`). To emphasise one mark in a
150
- multi-series chart, paint just that mark with the accent and leave the rest
151
- neutral — the same "reserve the accent for the one thing a reader must not miss"
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 `range.category[0]` (the resolved accent) and
175
- `brontoVegaNeutral(theme)` is the last category (the quiet neutral); re-read both
176
- when the theme toggles. Prefer them over digging the hex out of
177
- `tokens/resolved.json` — they are guaranteed to match the palette the config
178
- already ships. In token terms the accent is `--chart-1` and the neutral is
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.10.0/dist/css/<leaf>.css" />
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, series 1 = accent:
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; series 1 = accent; colourblind-safe, gated under
208
- simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
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.10.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"}