@ponchia/ui 0.5.0 → 0.6.0

package/docs/marks.md

@@ -44,6 +44,13 @@ Put `.ui-mark` on a `<mark>` so the emphasis is semantic, not just visual.
 `prefers-reduced-motion` (reduced motion shows the resting full highlight). It
 applies to the highlight fill, so pair it with the default (no style modifier).
 
+> **A mark is a behind-text highlight, not a filled chip.** The fill is a
+> low-alpha gradient *behind* the running text, so the text keeps its normal ink
+> and the contrast stays text-on-background — even `ui-mark--accent` is
+> contrast-safe by construction. Don't reach for `--on-accent` here (that ink is
+> for a *solid* accent fill, like a button or a D2 node); a `<mark>` never needs
+> it.
+
 ## Passage bracket — `.ui-bracket-note`
 
 Brackets a whole block and optionally labels it — the prose analogue of
@@ -56,8 +63,8 @@ Brackets a whole block and optionally labels it — the prose analogue of
 </blockquote>
 ```
 
-Tones: `--accent` (the rationed accent), `--warning`, `--danger`, `--info`. The
-default is a neutral bracket.
+Tones: `--accent` (the rationed accent), `--success`, `--warning`, `--danger`,
+`--info`. The default is a neutral bracket.
 
 ## Recipes
 

package/docs/mermaid.md

@@ -0,0 +1,152 @@
+# Mermaid
+
+[Mermaid](https://mermaid.js.org) renders diagrams (flowcharts, sequence, pie,
+git, gantt…) from text to **SVG**. `@ponchia/ui` does not render diagrams — it
+**themes** the ones you already have and lets you **annotate** them, the same way
+it dresses any other SVG figure in a report. Two things ship:
+
+- `@ponchia/ui/mermaid` — a resolved Mermaid `base` theme, per bronto theme.
+- `@ponchia/ui/mermaid.json` — the same data as plain JSON, for any consumer.
+
+Mermaid stays the consumer's renderer. This is config only: bronto never imports
+or runs Mermaid, and Mermaid is **not** a dependency.
+
+## Theme a diagram
+
+Mermaid's `base` theme is the only one meant to be customized. Hand it the
+bronto theme variables:
+
+```js
+import mermaid from 'mermaid';
+import { brontoMermaidTheme } from '@ponchia/ui/mermaid';
+
+mermaid.initialize(brontoMermaidTheme()); // light
+await mermaid.run();
+```
+
+`brontoMermaidTheme(theme)` returns `{ theme: 'base', themeVariables }` ready to
+spread into `initialize`. Pass `'dark'` for the dark palette, or read the active
+bronto theme:
+
+```js
+const theme = document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light';
+mermaid.initialize(brontoMermaidTheme(theme));
+```
+
+You can also splice the variables into a single diagram via an init directive,
+or read the raw maps (`import { mermaid } from '@ponchia/ui/mermaid'` →
+`{ light, dark }`). For a build step or non-JS host, read
+`@ponchia/ui/mermaid.json` directly.
+
+> **file:// portability.** A report opened straight from disk (`file://`) cannot
+> `import` the `@ponchia/ui/mermaid` module **nor** `fetch('…/mermaid.json')` —
+> the browser blocks both across the `null`/file origin (CORS), exactly as with
+> [Vega](./vega.md#from-a-cdn-no-bundler). So for a double-clickable or PDF-bound
+> report either **inline the theme variables** (paste the object for your theme
+> from `mermaid.json` into the init directive) or, better, **pre-render to a
+> frozen SVG** with the Mermaid CLI (`mmdc`, below) so there is no runtime at
+> all. Over an `http(s)` origin the `import`/`fetch` forms both work.
+
+The result is monochrome surfaces and lines with the rationed accent reserved
+for notes — a diagram that looks like the rest of a bronto surface and
+**re-skins for free** when you change `--accent`, exactly like the chart palette.
+
+### Why resolved colours, not `var(--x)`
+
+Mermaid's theming engine derives shades (lighten/darken) from your seed colours,
+so it only understands real colours — a `var(--accent)` string breaks
+derivation. The theme map therefore ships **resolved hex/rgba per theme**,
+projected from the same token source that feeds
+[`tokens/resolved.json`](./architecture.md) and `charts.json`. That projection
+is the bridge a CSS-first system needs until Mermaid can read CSS variables
+directly. It also means the theme is **static per theme**: on a light/dark
+switch, re-`initialize` with the other palette and re-render.
+
+### Which diagrams get the palette
+
+- **Chart-like** diagrams carry a categorical series palette — **pie**
+  (`pie1`…`pie12`), **git** (`git0`…`git7`), and **user-journey**
+  (`fillType0`…`fillType7`) are wired to the CVD-safe
+  [charts palette](./legends.md) (series 1 = the live accent).
+- **Structural** diagrams — flowchart, sequence, class, ER, state — use the
+  monochrome node/edge/cluster grammar and spend the accent only on notes.
+- **Not themed: `gantt` and `timeline`.** Their colours come from
+  diagram-specific slots (`taskBkgColor`, `sectionBkgColor*`, `gridColor`,
+  `todayLineColor`, …) that the base `themeVariables` map does **not** set, so a
+  gantt/timeline renders with Mermaid's own off-brand defaults (red/grey bars),
+  not the bronto palette. For a **report timeline**, prefer the native,
+  fully-themed [`ui-timeline`](./reporting.md) primitive (it also prints and
+  needs no renderer); reach for a Mermaid gantt only when you specifically need
+  its scheduling layout, and accept its default colours.
+
+Pie wedge labels (`pieSectionTextColor`) sit on arbitrary palette colours; if a
+label is hard to read on a given wedge, prefer a legend or direct labels over
+recolouring.
+
+### Fit to small screens
+
+The theme map sets colours, not size — sizing stays Mermaid's. Keep `useMaxWidth`
+on (the default for most diagram types) so each SVG scales to its container
+instead of forcing page-wide horizontal scroll:
+
+```js
+mermaid.initialize({
+  ...brontoMermaidTheme(theme),
+  flowchart: { useMaxWidth: true },
+  sequence: { useMaxWidth: true },
+});
+```
+
+A genuinely wide diagram (a long flowchart, a big ER) can still be unreadable
+once squeezed onto a phone. Rather than let it overflow the page, wrap the render
+in a scroll container so the *diagram* scrolls, not the document — the same
+pattern the report layer uses for wide figures and tables:
+
+```css
+.diagram-scroll {
+  overflow-x: auto;
+}
+```
+
+## Annotate a diagram
+
+Mermaid output is SVG, and the [annotation layer](./annotations.md) is
+renderer-agnostic SVG — so a `<g class="ui-annotation">` callout composes onto a
+rendered diagram the same as onto any figure. bronto supplies the geometry and
+the styling; **placing a callout on a specific node is yours**, because that
+means reading Mermaid's laid-out coordinates, which bronto deliberately does not
+own (no scales, no DOM, no hit-testing — see [annotations.md](./annotations.md)).
+
+The robust path is **build-time**, mirroring the
+[static-report recipe](./annotations.md#using-the-helpers-in-a-static-no-js-report):
+
+1. Pre-render the diagram to a frozen SVG with the Mermaid CLI
+   (`mmdc -t base -i diagram.mmd -o diagram.svg`, feeding the same
+   `themeVariables`).
+2. From that SVG, read the target node's box (`getBBox()` / the node's
+   `transform`), accounting for the diagram's root `<g>` translate and the
+   `viewBox`.
+3. Compute the callout strings with `@ponchia/ui/annotations` and paste a
+   `<g class="ui-annotation …">` into the SVG at those coordinates.
+
+The output is a static, on-brand, annotated SVG with no runtime — ideal for the
+[report layer](./reporting.md).
+
+To annotate a **live** client render instead, run the same measure-and-inject
+pass on the SVG returned by `mermaid.render()`, after it is in the DOM. Two
+honest caveats, both inherent to overlaying a foreign renderer (not bronto
+limitations):
+
+- **Mermaid's internal SVG structure is not a public contract.** Node ids and
+  classes are undocumented and have changed across major versions. Match nodes
+  by your own author-supplied id substring, measure positions rather than
+  hard-coding them, and **pin your Mermaid version**.
+- **Every re-render replaces the SVG**, discarding injected overlays. Re-apply
+  the annotation pass after each `render()` / theme switch / resize.
+
+## Scope
+
+bronto owns the theme map (gated: every value resolves to a colour, both themes,
+no `var()` leaks) and the annotation geometry. It does **not** own Mermaid's
+rendering, its internal DOM, or its re-render lifecycle — those stay Mermaid's,
+and the overlay above is a documented composition, not a shipped runtime binding.

package/docs/reference.md

@@ -9,8 +9,11 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 474 classes across 148 component groups
+- 477 classes across 149 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
+- Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
+  vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
+  `customProperties`), for an external linter or non-JS host
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
 ## Classes
@@ -162,7 +165,6 @@ each one matches a real selector in the stylesheet.
 | `cls.appRailAccount` | `ui-app-rail__account` | part |
 | `cls.appRailBrand` | `ui-app-rail__brand` | part |
 | `cls.appRailFoot` | `ui-app-rail__foot` | part |
-| `cls.appRailToggle` | `ui-app-rail__toggle` | part |
 
 ### `.ui-app-shell`
 
@@ -221,6 +223,7 @@ each one matches a real selector in the stylesheet.
 | `cls.bracketNoteAccent` | `ui-bracket-note--accent` | modifier |
 | `cls.bracketNoteDanger` | `ui-bracket-note--danger` | modifier |
 | `cls.bracketNoteInfo` | `ui-bracket-note--info` | modifier |
+| `cls.bracketNoteSuccess` | `ui-bracket-note--success` | modifier |
 | `cls.bracketNoteWarning` | `ui-bracket-note--warning` | modifier |
 
 ### `.ui-breadcrumb`
@@ -289,19 +292,6 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.center` | `ui-center` | base |
 
-### `.ui-chart`
-
-| Registry key | Class | Kind |
-| --- | --- | --- |
-| `cls.chart` | `ui-chart` | base |
-| `cls.chartBar` | `ui-chart__bar` | part |
-| `cls.chartCaption` | `ui-chart__caption` | part |
-| `cls.chartFallback` | `ui-chart__fallback` | part |
-| `cls.chartFill` | `ui-chart__fill` | part |
-| `cls.chartLabel` | `ui-chart__label` | part |
-| `cls.chartPlot` | `ui-chart__plot` | part |
-| `cls.chartTrack` | `ui-chart__track` | part |
-
 ### `.ui-check`
 
 | Registry key | Class | Kind |
@@ -352,6 +342,15 @@ each one matches a real selector in the stylesheet.
 | `cls.commandMeta` | `ui-command__meta` | part |
 | `cls.commandShortcut` | `ui-command__shortcut` | part |
 
+### `.ui-compare`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.compare` | `ui-compare` | base |
+| `cls.compareCol` | `ui-compare__col` | part |
+| `cls.compareHead` | `ui-compare__head` | part |
+| `cls.compare2up` | `ui-compare--2up` | modifier |
+
 ### `.ui-connector`
 
 | Registry key | Class | Kind |
@@ -393,6 +392,16 @@ each one matches a real selector in the stylesheet.
 | `cls.crosshairLineY` | `ui-crosshair__line--y` | modifier |
 | `cls.crosshairMuted` | `ui-crosshair--muted` | modifier |
 
+### `.ui-delta`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.delta` | `ui-delta` | base |
+| `cls.deltaDown` | `ui-delta--down` | modifier |
+| `cls.deltaFlat` | `ui-delta--flat` | modifier |
+| `cls.deltaInvert` | `ui-delta--invert` | modifier |
+| `cls.deltaUp` | `ui-delta--up` | modifier |
+
 ### `.ui-display`
 
 | Registry key | Class | Kind |
@@ -556,7 +565,7 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.inspector` | `ui-inspector` | base |
 | `cls.inspectorBody` | `ui-inspector__body` | part |
-| `cls.inspectorHeader` | `ui-inspector__header` | part |
+| `cls.inspectorHead` | `ui-inspector__head` | part |
 
 ### `.ui-kbd`
 
@@ -682,6 +691,7 @@ each one matches a real selector in the stylesheet.
 | `cls.meterFill` | `ui-meter__fill` | part |
 | `cls.meterAccent` | `ui-meter--accent` | modifier |
 | `cls.meterDanger` | `ui-meter--danger` | modifier |
+| `cls.meterInfo` | `ui-meter--info` | modifier |
 | `cls.meterSuccess` | `ui-meter--success` | modifier |
 | `cls.meterWarning` | `ui-meter--warning` | modifier |
 
@@ -840,7 +850,7 @@ each one matches a real selector in the stylesheet.
 | `cls.reportFigure` | `ui-report__figure` | part |
 | `cls.reportFinding` | `ui-report__finding` | part |
 | `cls.reportFootnotes` | `ui-report__footnotes` | part |
-| `cls.reportHeader` | `ui-report__header` | part |
+| `cls.reportHead` | `ui-report__head` | part |
 | `cls.reportMeta` | `ui-report__meta` | part |
 | `cls.reportSection` | `ui-report__section` | part |
 | `cls.reportSectionUnnumbered` | `ui-report__section--unnumbered` | modifier |
@@ -1003,6 +1013,7 @@ each one matches a real selector in the stylesheet.
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
+| `cls.src` | `ui-src` | base |
 | `cls.srcConflict` | `ui-src--conflict` | modifier |
 | `cls.srcGenerated` | `ui-src--generated` | modifier |
 | `cls.srcReviewed` | `ui-src--reviewed` | modifier |
@@ -1244,11 +1255,19 @@ registry consumer should reach for these instead of re-implementing
 | Class | Where | Effect |
 | --- | --- | --- |
 | `.ui-table .is-num` | numeric `<td>`/`<th>` | tabular figures + end-aligned (the canonical numeric cell) |
-| `.ui-table .is-pos` | numeric `<td>` | positive-delta tone |
-| `.ui-table .is-neg` | numeric `<td>` | negative-delta tone |
+| `.ui-table .is-pos` | numeric `<td>`, `.ui-stat__delta` | positive-delta tone |
+| `.ui-table .is-neg` | numeric `<td>`, `.ui-stat__delta` | negative-delta tone |
+| `.ui-table .is-key` | `<td>`/`<th>` | emphasised key column |
 
 For numeric text *outside* a table, use the `ui-num` primitive
-(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent.
+(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent; for
+a trend figure use `ui-delta` (`ui.delta({ dir, invert })`). The full,
+machine-readable list of these `is-*` state hooks — and the author-set inline
+custom properties (`--chart-color`, `--chart-pattern`, `--value`, and the
+**required** `--icon-mask` on `.ui-icon` and `--ui-vt-name` on `.ui-vt` —
+without which those classes render a solid square / do nothing) — is in
+[`@ponchia/ui/classes.json`](../classes/classes.json)
+(`states` / `customProperties`).
 
 ## Composition & state (read before re-implementing glue)
 
@@ -1270,12 +1289,45 @@ works in any framework without a binding layer:
 - **Modal** — native `<dialog>` gets backdrop + top-layer + focus-trap
   free. For a controlled/portal modal, add `is-open`
   (`ui.modal({ open: true })`) for the same skin/layout; the
-  backdrop and focus-trap are then yours.
+  backdrop, top-layer stacking AND focus-trap are then yours (`.is-open`
+  is a bare grid — it does not float or stack on its own).
+- **Current page** — mark the active link with `aria-current="page"`; it is
+  the programmatic cue the navs honour (`ui-sitenav`, `ui-app-nav`). The
+  `.is-active` class is the visual-only equivalent on `ui-app-nav`/`ui-tab`;
+  prefer `aria-current` so assistive tech announces the current page.
+- **Form validation wiring** — `initFormValidation` (`@ponchia/ui/behaviors`)
+  reads these attributes; they ARE the contract, not styling. Markup that omits
+  them renders but the behavior silently no-ops: `data-bronto-validate` on the
+  `<form>`; an optional empty `[data-bronto-error]` node per field (it falls
+  back to the field's `.ui-hint`, restoring the help text when valid again); a
+  `[data-bronto-error-summary]` (`.ui-error-summary`) block. The combobox
+  reads `[data-bronto-combobox]` + per-option `data-value` and emits
+  `bronto:change` (`{ detail: { value } }`) on selection; the interactive
+  legend emits `bronto:legend:toggle` (`{ detail: { series, active } }`).
+- **Status indicator** — `ui-status` carries no dot of its own: compose it with
+  a `.ui-dot` child + a text label, e.g.
+  `<span class="ui-status"><span class="ui-dot ui-dot--success"></span> Live</span>`.
+  (`ui-state` instead bakes in its own dot + the full tone vocabulary — pick
+  one.) A semantic `ui-dot--success|warning|danger|info` is colour-only outside
+  forced-colors, so it ALWAYS needs an adjacent text/aria label — never ship a
+  bare coloured dot as the sole signal.
+- **Opt-in component CSS** — a few classes are not in the core bundle and need
+  their leaf imported, or they render unstyled: `ui-property`/`ui-readout` →
+  `@ponchia/ui/css/workbench.css`; `ui-mark`/`ui-bracket-note` →
+  `@ponchia/ui/css/marks.css`; the analytical leaves (`ui-annotations`,
+  `ui-crosshair`, `ui-spotlight`, …) → their matching leaf.
+- **Loaders need their children** — `ui-dotspinner` requires exactly eight
+  `<i>` children, `ui-dotloader` three `<span>`, and a static `ui-dotbar`
+  lights a segment with `<i class="is-on">`. A childless
+  `<span class="ui-dotspinner">` renders nothing.
+- **`ui-caret` is a typing cursor**, not a dropdown chevron — a blinking block
+  caret (driven by `initDotGlyph`/`uiBlink`). For a disclosure/affordance
+  arrow use `ui-link--arrow` (`ui.link({ arrow: true })`).
 
 ## Tokens
 
 Exact mirror of the `:root` blocks in `css/tokens.css`
-(`check-tokens` enforces parity). DTCG export:
+(`check-fresh` enforces parity). DTCG export:
 [`@ponchia/ui/tokens.dtcg.json`](../tokens/tokens.dtcg.json).
 
 ### Global (scales — shared by both themes)
@@ -1298,6 +1350,8 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--sans` | `'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif` |
 | `--dot-font` | `'Doto', var(--mono)` |
 | `--display` | `var(--dot-font)` |
+| `--display-weight` | `700` |
+| `--display-weight-strong` | `800` |
 | `--text-2xs` | `0.68rem` |
 | `--text-xs` | `0.76rem` |
 | `--text-sm` | `0.86rem` |
@@ -1371,6 +1425,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#ffffff` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 83%, #000)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 10%, transparent)` |
 | `--success` | `#2f7d4f` |
 | `--success-soft` | `rgb(47, 125, 79, 0.12)` |
@@ -1408,6 +1463,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#000000` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 84%, #fff)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 14%, transparent)` |
 | `--success` | `#4ec27e` |
 | `--success-soft` | `rgb(78, 194, 126, 0.14)` |