@ponchia/ui 0.11.0 → 0.13.0

package/docs/theming.md

@@ -129,7 +129,10 @@ you change CSS `--accent` later.
 
 - **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
   preset: `data-density="compact"` / `data-density="comfortable"` on any
-  element (defaults to the middle scale).
+  element (defaults to the middle scale). Dense tool chrome also gets four half
+  steps on the 0.25rem unit that the t-shirt scale skips: `--space-0-5`,
+  `--space-0-75`, `--space-1-5` and `--space-2-5` (2, 3, 6 and 10px at a 16px
+  root). The density presets scale them with the rest.
 
   **Read this before relying on the preset.** It re-points the `--space-*`
   scale, and only components whose padding is *expressed in that scale* move
@@ -189,6 +192,50 @@ you change CSS `--accent` later.
   set `accent-color` yourself on them — this is the one accent surface
   the framework can't tune for you.
 
+## A tool over a canvas: layers and zoom
+
+**Layers.** A page needs six stacking layers (`--z-base`, `--z-raised`,
+`--z-sticky`, `--z-overlay`, `--z-popover`, `--z-toast`). A tool drawn over a
+canvas needs named ones, lowest first:
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--z-canvas` | `--z-base` | the canvas plane; its nodes stack locally inside it |
+| `--z-chrome` | `--z-sticky` | toolbars, headers and rails over the canvas |
+| `--z-panel` | 25 | docked and floating panels |
+| `--z-modal` | `--z-overlay` | dialogs and their scrim |
+| `--z-menu` | `--z-popover` | menus and popovers, including those a dialog opens |
+| `--z-toast` | 60 | toasts |
+| `--z-tooltip` | 70 | tooltips |
+| `--z-navigation` | 80 | presentation and tour chrome that drives the whole surface |
+
+Where a workspace layer means the same as a page layer it is an alias, so the
+two scales cannot disagree.
+
+**Zoom.** A host that draws bronto UI inside a scaled surface, such as a
+zoomable canvas, marks the scaled element with `data-ui-zoom` and sets
+`--ui-zoom` to its scale there:
+
+```css
+.canvas-viewport {
+  --ui-zoom: var(--my-canvas-zoom);
+}
+```
+
+```html
+<div class="canvas-viewport" data-ui-zoom>…</div>
+```
+
+Inside it `--ui-px` is one screen pixel (1px divided by the zoom, with the zoom
+floored at 0.15), and `--hairline`, `--focus-ring-width` and
+`--focus-ring-offset` are re-declared in it. Every bronto focus ring uses those
+tokens, so a control inside a zoomed-out canvas keeps a 2px ring on screen.
+Size your own canvas overlays the same way: `width: calc(1.5 * var(--ui-px))`.
+
+The scope is an attribute rather than an inherited value on purpose. A custom
+property that reads `--ui-zoom` resolves where it is declared, so a value set on
+`:root` could not follow a zoomed subtree.
+
 ## Beyond accent: full re-skins
 
 The "Nothing" look is the **default skin, not the architecture**. It is
@@ -309,9 +356,11 @@ you have, so the one-accent discipline holds.
 
 ## Data-viz palette
 
-Opt-in Tier-4 chart colours for dashboards — **charts only, never UI chrome**
-(a build gate fails on `var(--chart-*)` in component CSS), and never in the
-default bundle.
+Opt-in Tier-4 categorical colour — **never UI chrome** (a build gate fails on
+`var(--chart-*)` or `var(--cat-*)` in component CSS), and never in the default
+bundle. One leaf carries eight fixed hues in two namespaces: `--chart-*` for
+data-viz series and ramps, and `--cat-*` for categorical **identity** — a tag,
+a participant, a user-chosen tint.
 
 ```html
 <link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
@@ -320,28 +369,36 @@ default bundle.
 ```js
 // resolved hex for canvas / SVG / Chart.js etc.
 import charts from '@ponchia/ui/charts.json' with { type: 'json' };
-const series = charts.dark.categorical; // ['#ff3b41', '#e69f00', …] — series 0 = accent
+const series = charts.dark.categorical; // ['#3987e5', '#d95926', …] — blue first
 ```
 
-- **Categorical `--chart-1..8`** — hybrid accent-led: series 1 is the live
-  `var(--accent)` (your brand leads), series 2–8 are the Okabe-Ito
-  colourblind-safe set. The set is **gated for mutual distinguishability under
-  normal + simulated protanopia/deuteranopia/tritanopia** (OKLab ΔE).
-  **Caveat — the CVD gate measures the SHIPPED default accent.** Series 1 is
-  `var(--accent)`, so if you re-skin `--accent` you change series 1 but not the
-  Okabe-Ito 2–8, and the gate never re-checks your custom hue: a brand close to
-  series 3's orange can collide for a deuteranope. If a re-brand drives data-viz,
-  re-verify your accent against the set, or pin `--chart-1` to a fixed Okabe-Ito
-  value (`--chart-1: #0072b2`) and let your brand lead the UI only.
-- **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
-  heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
-  for ±/gains-losses.
+For a page that switches theme, skin, contrast or the OLED surface at runtime,
+read the live values with [`@ponchia/ui/renderer`](renderer.md) instead of the
+static JSON.
+
+- **Categorical `--chart-1..8` = `--cat-1..8`** — blue, orange, aqua, yellow,
+  magenta, green, violet, red, in that fixed order (`CATEGORICAL_HUES` names
+  them). No slot is the accent, so an ordinary first series never reads as an
+  alert. `check:charts` measures each theme against the panel, the page and
+  the OLED surfaces: OKLCH lightness inside the theme's band, chroma above the
+  grey floor, adjacent slots separated under simulated protanopia and
+  deuteranopia and in normal vision. Slots under 3:1 against a surface are
+  reported in the gate output; relief is the pattern fill or a direct label.
+  Any two slots can meet in a scatter or a map, so pair colour with pattern
+  there.
+- **Identity `--cat-N-tint` / `--cat-N-ink`** — a 16% wash of the hue over
+  `--panel` (it follows a skin's or OLED's panel) and a text colour that holds
+  4.5:1 on the panel, the page and its own tint. Use them for a tag chip, a
+  participant's name, or a user-chosen highlight — never for status.
+- **Sequential `--chart-seq-1..5`** — one blue hue; step 1 sits nearest the
+  surface (pale in light, deep in dark), for heatmaps/intensity. **Diverging
+  `--chart-div-1..7`** — blue↔neutral↔orange, for ±/gains-losses.
 - **Pattern fills `--chart-pattern-1..8`** — a dot-matrix second channel so
   colour is never the sole signal (WCAG 1.4.1). Pair colour N with pattern N:
   `background: var(--chart-2); background-image: var(--chart-pattern-2); background-size: var(--chart-pattern-size); --chart-pattern-ink: rgb(0 0 0 / .34);`
 - A chart colour's WCAG ratio vs the background is published **advisory** in
-  [contrast.md](contrast.md) (a fill is not body text) — pick a darker series
-  for thin lines/points, or lean on the pattern.
+  [contrast.md](contrast.md) (a fill is not body text) — for thin lines or
+  points use the slot's `--cat-N-ink`, or lean on the pattern.
 
 ## Accessibility markup contracts
 

package/docs/usage.md

@@ -584,18 +584,22 @@ phosphor-green | e-ink"` — a **root-level** colorway (apply on `<html>`, like
 
 `@ponchia/ui/css/dataviz.css` (opt-in) adds a Tier-4 chart palette for
 dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
-`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills).
-
-- **Use it for charts only.** These are not UI tokens — a build gate fails if
-  `var(--chart-*)` appears in component CSS. Style buttons/badges with the
-  accent/status tiers, not chart colours.
-- **Series 1 is the accent**, so your brand leads the palette; series 2–8 are a
-  colourblind-safe set (gated for distinctness under protan/deutan/tritan).
+`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills), plus
+the same eight hues as categorical identity: `--cat-N`, `--cat-N-tint` and
+`--cat-N-ink` for tags, participants and user-chosen tints.
+
+- **Use it for categories, never for chrome or status.** A build gate fails if
+  `var(--chart-*)` or `var(--cat-*)` appears in component CSS. Style buttons
+  and badges with the accent/status tiers.
+- **No slot is the accent.** The order is fixed (blue, orange, aqua, yellow,
+  magenta, green, violet, red) and adjacent slots are gated for separation
+  under simulated protanopia/deuteranopia and in normal vision.
 - **Always pair colour with pattern** (`--chart-pattern-N`) and/or a direct
   label — never colour alone (WCAG 1.4.1):
   `background: var(--chart-3); background-image: var(--chart-pattern-3); background-size: var(--chart-pattern-size);`
 - **In JS** (Chart.js, canvas, SVG): import resolved hex from
-  `@ponchia/ui/charts.json` (`{ light, dark }`, series 1 = the resolved accent).
+  `@ponchia/ui/charts.json` (`{ hues, light, dark }`), or read the live page
+  with [`@ponchia/ui/renderer`](renderer.md) when it can change skin or theme.
   Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
   "Data-viz palette".
 

package/docs/vega.md

@@ -113,18 +113,23 @@ colours are **baked into the output** and parsed by `d3-color`, which understand
 real hex/rgb but **not** `var()` (nor `oklch()`). So the config ships **resolved
 hex per theme**, projected from the same token source as
 [`tokens/resolved.json`](./architecture.md) / [`charts.json`](./theming.md).
-Re-call `brontoVegaConfig()` when the theme toggles and re-embed.
+Re-call `brontoVegaConfig()` when the theme toggles and re-embed. A page that
+switches skin, contrast or the OLED surface at runtime cannot be served by a
+per-theme snapshot: build the config from the live page with
+[`@ponchia/ui/renderer`](./renderer.md) — `vegaConfig(readTokens())` is the
+same mapping these files are generated from.
 
 ### What the slots paint
 
-The config keeps a chart **monochrome by default** — the rationed accent is the
-one chromatic default (series 1 / the lone mark), never the chrome:
+The chrome stays quiet and neutral; colour is spent on data. The plot has no
+frame (a chart already sits on a panel), and a single series takes the first
+categorical hue rather than the alert accent:
 
 | Slot | Paint | bronto token |
 | --- | --- | --- |
-| `background` | Chart canvas | `--bg` |
-| `view.stroke` | Plot frame | `--line` |
-| `mark.color` | Default / single-series mark | `--accent` |
+| `background` | Chart canvas | `--bg` (runtime default: transparent) |
+| `view.stroke` | Plot frame | none (`null`) |
+| `mark.color` | Default / single-series mark | `--chart-1` |
 | `rule.color` | Reference rules, annotations | `--line-strong` |
 | `axis.domainColor` · `tickColor` | Axis line · ticks | `--line-strong` |
 | `axis.gridColor` | Gridlines | `--line` |
@@ -132,7 +137,8 @@ one chromatic default (series 1 / the lone mark), never the chrome:
 | `text.color` | Free `text`/`label` marks | `--text` |
 | `legend.*` · `header.*` · `title.*` | Legend, facet headers, title | `--text-soft` / `--text` / `--text-dim` |
 | `*.font` / `*Font` | All text | `--sans` |
-| `range.category` | 8-series categorical palette | `charts.json` categorical (series 1 = accent) |
+| `rect`/`arc`/`area` `.stroke` | Gap between adjacent fills | `--panel` |
+| `range.category` | 8-series categorical palette | `charts.json` categorical (blue first) |
 | `range.ordinal` · `ramp` · `heatmap` | Single-hue sequential ramp | `charts.json` sequential |
 | `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
 
@@ -143,14 +149,12 @@ series needs the redundant second channel, drive the mark's fill from the
 
 ### Spending the accent
 
-Series 1 of `range.category` resolves to the accent (per theme), so a single-series
-chart and the first category carry the accent automatically — baked into the
-generated `config`, so regenerate the config and re-render to change it (Vega output
-does not live-reskin from `--accent`). To emphasise one mark in a
-multi-series chart, paint just that mark with the accent and leave the rest
-neutral — the same "reserve the accent for the one thing a reader must not miss"
-rule the rest of the system follows. Two small helpers hand you the exact
-per-theme hexes so you never hard-code a palette array index:
+No categorical slot is the accent, so an ordinary chart never reads as an
+alert. To emphasise one mark, paint just that mark with the accent and leave
+the rest neutral — the same "reserve the accent for the one thing a reader must
+not miss" rule the rest of the system follows. Two small helpers hand you the
+exact per-theme hexes (baked into the generated files; Vega output does not
+live-reskin from `--accent`):
 
 ```js
 import { brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
@@ -171,14 +175,11 @@ const spec = {
 };
 ```
 
-`brontoVegaAccent(theme)` is `range.category[0]` (the resolved accent) and
-`brontoVegaNeutral(theme)` is the last category (the quiet neutral); re-read both
-when the theme toggles. Prefer them over digging the hex out of
-`tokens/resolved.json` — they are guaranteed to match the palette the config
-already ships. In token terms the accent is `--chart-1` and the neutral is
-`--chart-8`, so a [legend](./legends.md#swatch-colour) for an accent-rationed
-chart keys those two series with `ui-legend__swatch--1` and
-`ui-legend__swatch--8` — the swatches mirror the marks exactly.
+`brontoVegaAccent(theme)` is the resolved `--accent` and `brontoVegaNeutral(theme)`
+the resolved `--text-dim`; re-read both when the theme toggles. A
+[legend](./legends.md#swatch-colour) for an accent-rationed chart keys the two
+with inline swatch colours (`style="--chart-color: …"`), not with categorical
+slots.
 
 ### Selecting the themed ramp in a spec
 

package/llms.txt

@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/css/<leaf>.css" />
 ```
 
 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
 scales + data binding, which the analytical layer refuses). For charts, recommend
 Vega-Lite — a declarative JSON spec an external system can emit — themed by the
 on-brand `config` (resolved hex; Vega bakes colours into SVG/canvas, can't read
-`var()`). `range.category` is the `--chart-*` palette, series 1 = accent:
+`var()`). `range.category` is the `--chart-*` palette (blue first; no slot is the
+accent). For a live page that switches skin or theme, build the same config at
+runtime with `vegaConfig(readTokens())` from `@ponchia/ui/renderer`:
 
 ```js
 import { brontoVegaConfig, brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
@@ -204,8 +206,10 @@ accent-filled DOM control, set `--button-text`. Details: `docs/vega.md`. (Observ
 Plot works too — it inherits the page CSS, so it needs even less theming;
 Vega-Lite is the recommended LLM-emittable path.)
 
-`--chart-1..8` (categorical; series 1 = accent; colourblind-safe, gated under
-simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
+`--chart-1..8` (categorical: blue, orange, aqua, yellow, magenta, green, violet,
+red; adjacent slots gated under simulated protan/deutan), `--cat-N` /
+`--cat-N-tint` / `--cat-N-ink` (the same hues as tag/participant identity),
+`--chart-seq-*` (sequential), `--chart-div-*`
 (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
-  "description": "CSS-first identity and UI layer for services, tools, sites, and reports \u2014 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.",
+  "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.",
   "keywords": [
     "css",
     "ui",
@@ -58,6 +58,7 @@
     "schemas",
     "annotations",
     "connectors",
+    "renderer",
     "shiki",
     "llms.txt",
     "CHANGELOG.md",
@@ -82,6 +83,7 @@
     "docs/legends.md",
     "docs/marks.md",
     "docs/connectors.md",
+    "docs/renderer.md",
     "docs/spotlight.md",
     "docs/crosshair.md",
     "docs/selection.md",
@@ -104,6 +106,7 @@
     "docs/command.md",
     "docs/interop/tailwind.md",
     "docs/interop/react-flow.md",
+    "docs/interop/blocknote.md",
     "docs/migrations/0.2-to-0.3.md",
     "docs/migrations/0.3-to-0.4.md",
     "docs/migrations/0.4-to-0.5.md",
@@ -119,7 +122,8 @@
     "docs/adr/0005-productive-tools-and-editorial-reports.md",
     "docs/migrations/0.9-to-0.10.md",
     "docs/adr/0006-trusted-publishing.md",
-    "docs/migrations/0.10-to-0.11.md"
+    "docs/migrations/0.10-to-0.11.md",
+    "docs/migrations/0.11-to-0.12.md"
   ],
   "style": "./dist/bronto.css",
   "scripts": {
@@ -161,7 +165,6 @@
     "check:recipe-types": "node scripts/check-recipe-types.mjs",
     "check:dead": "knip --treat-config-hints-as-errors",
     "check:complexity": "node scripts/check-complexity.mjs",
-    "check:chain": "node scripts/check-chain.mjs",
     "check:dts-emit": "node scripts/check-dts-emit.mjs",
     "check:glyphs": "node scripts/check-glyphs.mjs",
     "check:color-policy": "node scripts/check-color-policy.mjs",
@@ -200,7 +203,7 @@
     "check:publint": "publint --strict",
     "check:attw": "attw --pack --ignore-rules no-resolution cjs-resolves-to-esm",
     "check:workflows": "github-actionlint .github/workflows/*.yml",
-    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:fresh && npm run check:classes && npm run check:recipe-types && npm run check:dead && npm run check:complexity && npm run check:types && npm run check:unit && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:consumer-surface && npm run check:consumer-types && npm run check:component-matrix && npm run check:behavior-matrix && npm run check:helper-matrix && npm run check:examples && npm run check:visual-baselines && npm run check:playwright-container && npm run check:schemas && npm run check:publint && npm run check:attw && npm run check:workflows && npm run check:release && npm run check:versions && npm run check:migrations && npm run check:public-metadata && npm run check:public-hygiene && npm run check:doc-links && npm run check:doc-recipes && npm run check:contract && npm run check:variables && npm run check:contrast && npm run check:dtcg && npm run check:dts-emit && npm run check:glyphs && npm run check:color-policy && npm run check:skins && npm run check:charts && npm run check:mermaid && npm run check:d2 && npm run check:vega && npm run check:report && npm run check:legend && npm run check:chain",
+    "check": "node scripts/run-checks.mjs",
     "test": "node --test \"test/*.test.mjs\"",
     "test:e2e": "playwright test",
     "test:e2e:chromium": "playwright test --project=chromium",
@@ -219,16 +222,16 @@
     "@axe-core/playwright": "^4.11.3",
     "@playwright/test": "1.60.0",
     "github-actionlint": "^1.7.12",
-    "jsdom": "^30.0.1",
-    "knip": "^6.32.1",
-    "pdfjs-dist": "^6.2.108",
-    "prettier": "^3.9.6",
-    "publint": "^0.3.23",
-    "stylelint": "^17.14.1",
+    "jsdom": "^30.1.1",
+    "knip": "^6.39.0",
+    "pdfjs-dist": "^6.3.289",
+    "prettier": "^3.9.9",
+    "publint": "^0.3.24",
+    "stylelint": "^17.16.0",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-use-logical": "^2.1.3",
     "typescript": "^6.0.3",
-    "vega": "^6.3.1",
+    "vega": "^6.4.0",
     "vega-lite": "^6.4.3"
   },
   "exports": {
@@ -259,6 +262,7 @@
     "./css/app.css": "./dist/css/app.css",
     "./css/skins.css": "./dist/css/skins.css",
     "./css/dataviz.css": "./dist/css/dataviz.css",
+    "./css/blocknote.css": "./dist/css/blocknote.css",
     "./css/report.css": "./dist/css/report.css",
     "./css/row.css": "./dist/css/row.css",
     "./css/figure.css": "./dist/css/figure.css",
@@ -305,6 +309,7 @@
     "./css/unlayered/app.css": "./css/app.css",
     "./css/unlayered/skins.css": "./css/skins.css",
     "./css/unlayered/dataviz.css": "./css/dataviz.css",
+    "./css/unlayered/blocknote.css": "./css/blocknote.css",
     "./css/unlayered/report.css": "./css/report.css",
     "./css/unlayered/row.css": "./css/row.css",
     "./css/unlayered/figure.css": "./css/figure.css",
@@ -364,6 +369,7 @@
     "./docs/legends.md": "./docs/legends.md",
     "./docs/marks.md": "./docs/marks.md",
     "./docs/connectors.md": "./docs/connectors.md",
+    "./docs/renderer.md": "./docs/renderer.md",
     "./docs/spotlight.md": "./docs/spotlight.md",
     "./docs/crosshair.md": "./docs/crosshair.md",
     "./docs/selection.md": "./docs/selection.md",
@@ -386,6 +392,7 @@
     "./docs/command.md": "./docs/command.md",
     "./docs/interop/tailwind.md": "./docs/interop/tailwind.md",
     "./docs/interop/react-flow.md": "./docs/interop/react-flow.md",
+    "./docs/interop/blocknote.md": "./docs/interop/blocknote.md",
     "./docs/migrations/0.2-to-0.3.md": "./docs/migrations/0.2-to-0.3.md",
     "./docs/migrations/0.3-to-0.4.md": "./docs/migrations/0.3-to-0.4.md",
     "./docs/migrations/0.4-to-0.5.md": "./docs/migrations/0.4-to-0.5.md",
@@ -500,6 +507,10 @@
       "types": "./connectors/index.d.ts",
       "default": "./connectors/index.js"
     },
+    "./renderer": {
+      "types": "./renderer/index.d.ts",
+      "default": "./renderer/index.js"
+    },
     "./skins": {
       "types": "./tokens/skins.d.ts",
       "default": "./tokens/skins.js"
@@ -530,6 +541,7 @@
     "./docs/migrations/0.9-to-0.10.md": "./docs/migrations/0.9-to-0.10.md",
     "./docs/adr/0006-trusted-publishing.md": "./docs/adr/0006-trusted-publishing.md",
     "./docs/migrations/0.10-to-0.11.md": "./docs/migrations/0.10-to-0.11.md",
+    "./docs/migrations/0.11-to-0.12.md": "./docs/migrations/0.11-to-0.12.md",
     "./css/discussion.css": "./dist/css/discussion.css",
     "./css/unlayered/discussion.css": "./css/discussion.css",
     "./docs/discussion.md": "./docs/discussion.md"

package/renderer/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Parse a resolved CSS colour to sRGB, gamut-clipped: hex, `rgb()`, `hsl()`,
+ * `oklch()`, `oklab()`, `lab()`, `lch()`, `color(srgb | srgb-linear |
+ * display-p3 | xyz | xyz-d65 | xyz-d50 …)` and `transparent`. Anything else —
+ * `var()`, `color-mix()`, `light-dark()`, a named colour — returns null; use
+ * `resolveColor()` to have the browser compute it first.
+ * @param {string} value
+ * @returns {Rgba | null}
+ */
+export function parseColor(value: string): Rgba | null;
+/**
+ * Serialize for a renderer: `#rrggbb` when opaque, `rgba(r, g, b, a)` when
+ * not — the two forms canvas, SVG, d3-color, xterm, three.js and MapLibre
+ * all accept.
+ * @param {Rgba} color
+ */
+export function formatColor({ r, g, b, alpha }: Rgba): string;
+/**
+ * Resolve any CSS colour expression to a renderer literal, using the browser
+ * for what `parseColor()` cannot compute (`var()`, `color-mix()`,
+ * `light-dark()`, named colours). Returns null for an invalid colour or when no
+ * document is available.
+ * @param {string} value
+ * @param {{ element?: Element }} [options] Context for `var()` and `light-dark()`.
+ */
+export function resolveColor(value: string, options?: {
+    element?: Element;
+}): string | null;
+/**
+ * Resolve the page's bronto tokens for a renderer. Reads custom properties as
+ * computed on `element` (default: the root), so a subtree that re-points them
+ * is honoured. When the categorical leaf (`css/dataviz.css`) is not loaded,
+ * the categorical, sequential and diverging sets fall back to the packaged
+ * palette for the resolved scheme. Without a DOM it returns the packaged light
+ * (or `options.scheme`) values.
+ * @param {Element} [element]
+ * @param {{ scheme?: 'light' | 'dark' }} [options] Force the scheme instead of reading the background.
+ * @returns {RendererTokens}
+ */
+export function readTokens(element?: Element, options?: {
+    scheme?: "light" | "dark";
+}): RendererTokens;
+/**
+ * Call `callback` with fresh tokens whenever they change: after an attribute
+ * on the root changes (`data-theme`, `data-bronto-skin`, `data-contrast`,
+ * `data-surface`, `data-density`, `class`, `style`) and a token's value moved
+ * with it, or when the system colour scheme or contrast preference changes.
+ * A host that writes unrelated inline styles on the root every frame costs one
+ * computed-style read per frame, not a re-resolution. Calls are coalesced to
+ * one per animation frame. Returns a function that stops observing.
+ * @param {(tokens: RendererTokens) => void} callback
+ * @param {{ element?: Element, signal?: AbortSignal }} [options]
+ * @returns {() => void}
+ */
+export function observeTokens(callback: (tokens: RendererTokens) => void, options?: {
+    element?: Element;
+    signal?: AbortSignal;
+}): () => void;
+/**
+ * A Vega-Lite (default) or Vega `config` from resolved tokens: quiet chrome in
+ * the bronto inks, the categorical palette as `range.category` (a single
+ * series takes its first hue), the sequential ramp for ordinal/ramp/heatmap
+ * scales and the diverging ramp for diverging ones. A spec's own `config`
+ * still wins where Vega merges it over this one.
+ * @param {RendererTokens} tokens
+ * @param {{ mode?: 'vega-lite' | 'vega', narrow?: boolean, background?: string }} [options]
+ *   `narrow` moves the legend under the plot and thins ticks for a small
+ *   container; `background` defaults to transparent so the host surface shows.
+ * @returns {Record<string, any>}
+ */
+export function vegaConfig(tokens: RendererTokens, options?: {
+    mode?: "vega-lite" | "vega";
+    narrow?: boolean;
+    background?: string;
+}): Record<string, any>;
+/**
+ * An xterm.js `ITheme` from resolved tokens: page ink on the page background,
+ * the accent as the cursor, status colours for red/green/yellow/blue and the
+ * categorical magenta and aqua for magenta/cyan, so all six ANSI hues differ.
+ * @param {RendererTokens} tokens
+ * @returns {Record<string, string>}
+ */
+export function xtermTheme(tokens: RendererTokens): Record<string, string>;
+/**
+ * A colour as sRGB channels (0–255) and alpha (0–1).
+ */
+export type Rgba = {
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+/**
+ * The bronto roles a renderer draws with, resolved to literals: opaque colours
+ * as `#rrggbb`, translucent ones as `rgba(r, g, b, a)`.
+ */
+export type RendererTokens = {
+    /**
+     * The resolved scheme of the page background.
+     */
+    scheme: "light" | "dark";
+    /**
+     * Page background (`--bg`).
+     */
+    bg: string;
+    /**
+     * A lifted page background (`--bg-elevated`).
+     */
+    bgElevated: string;
+    /**
+     * The surface a renderer usually draws on (`--panel`).
+     */
+    panel: string;
+    /**
+     * A raised surface (`--panel-strong`).
+     */
+    panelStrong: string;
+    /**
+     * Primary ink (`--text`).
+     */
+    text: string;
+    /**
+     * Secondary ink (`--text-soft`).
+     */
+    textSoft: string;
+    /**
+     * Tertiary ink (`--text-dim`).
+     */
+    textDim: string;
+    /**
+     * Hairline and grid (`--line`).
+     */
+    line: string;
+    /**
+     * Axis, domain and rule (`--line-strong`).
+     */
+    lineStrong: string;
+    /**
+     * The one accent (`--accent`).
+     */
+    accent: string;
+    /**
+     * Accent as text on the page (`--accent-text`).
+     */
+    accentText: string;
+    /**
+     * Ink on an accent fill (`--on-accent`).
+     */
+    onAccent: string;
+    /**
+     * Focus ring (`--focus-ring`).
+     */
+    focus: string;
+    /**
+     * A translucent selection wash over `panel`.
+     */
+    selection: string;
+    /**
+     * Status: success.
+     */
+    success: string;
+    /**
+     * Status: warning.
+     */
+    warning: string;
+    /**
+     * Status: danger.
+     */
+    danger: string;
+    /**
+     * Status: info.
+     */
+    info: string;
+    /**
+     * The sans font stack.
+     */
+    sans: string;
+    /**
+     * The monospace font stack.
+     */
+    mono: string;
+    /**
+     * Eight categorical hues, fixed order.
+     */
+    categorical: string[];
+    /**
+     * Each hue's wash over `panel`.
+     */
+    categoricalTint: string[];
+    /**
+     * Each hue as text on `panel` and its tint.
+     */
+    categoricalInk: string[];
+    /**
+     * One-hue ramp; step 1 nearest the surface.
+     */
+    sequential: string[];
+    /**
+     * Negative … neutral … positive ramp.
+     */
+    diverging: string[];
+};
+//# sourceMappingURL=index.d.ts.map

package/renderer/index.d.ts.map

@@ -0,0 +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"}