@ponchia/ui 0.4.1 → 0.5.0

package/docs/sources.md

@@ -0,0 +1,110 @@
+# Sources, citations & provenance
+
+`@ponchia/ui/css/sources.css` is an opt-in **trust layer** for generated
+reports, AI output, audits, and docs — the grammar that answers _"where did
+this come from?"_. Generic UI kits have tags and footnotes; this is a small,
+explicit vocabulary for sources and their trust state.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sources.css';
+```
+
+Bronto owns the visual grammar and the trust **states**. The host owns fetching,
+citation numbering, permission checks, and whether a source is actually
+trustworthy. The state is carried by a rationed tone **and** an author-written
+label, so it never relies on colour alone (WCAG 1.4.1). Not in the core bundle.
+
+## Trust states
+
+A cross-cutting trust-state class — `ui-src--verified`, `ui-src--stale`, and the
+rest in the table below — sets the tone on a citation chip, source card, or
+provenance item. Always pair it with a word: the colour is a second channel, not
+the only one.
+
+| State | Class | Tone |
+| --- | --- | --- |
+| Verified | `ui-src--verified` | success |
+| Reviewed (by a human) | `ui-src--reviewed` | accent |
+| Generated | `ui-src--generated` | info |
+| Unverified | `ui-src--unverified` | muted |
+| Stale | `ui-src--stale` | warning |
+| Conflict | `ui-src--conflict` | danger |
+
+## Inline citation — `.ui-citation`
+
+A reference marker on a real `<a>` or `<button>` (the visual index is never the
+only label — give it an accessible name).
+
+```html
+<p>
+  Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.
+</p>
+
+<!-- Named-source pill, with a leading trust dot: -->
+<a class="ui-citation ui-citation--chip ui-src--verified" href="#s1">
+  Q3 incident review
+</a>
+```
+
+## Source card — `.ui-source-card`
+
+A single source preview: title, origin, time, excerpt, actions. The
+`border-inline-start` carries the trust tone.
+
+```html
+<article class="ui-source-card ui-src--generated">
+  <h3 class="ui-source-card__title">Model output — pricing summary</h3>
+  <p class="ui-source-card__origin">gpt-x · internal</p>
+  <p class="ui-source-card__time">2026-06-01 09:42</p>
+  <p class="ui-source-card__excerpt">The migration cut p95 latency by 38%…</p>
+  <div class="ui-source-card__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Open</button>
+  </div>
+</article>
+```
+
+## Source list — `.ui-source-list`
+
+A references section: a reset list of source cards (or rows).
+
+```html
+<ol class="ui-source-list">
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--verified">…</article></li>
+  <li class="ui-source-list__item"><article class="ui-source-card ui-src--stale">…</article></li>
+</ol>
+```
+
+## Provenance — `.ui-provenance`
+
+A compact metadata row beside generated content — each `__item` carries a trust
+dot and a label.
+
+```html
+<p class="ui-provenance">
+  <span class="ui-provenance__item ui-src--generated">Generated</span>
+  <span class="ui-provenance__item ui-src--verified">3 sources</span>
+  <span class="ui-provenance__item ui-src--reviewed">Human-reviewed</span>
+</p>
+```
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.citation({ chip: true, state: 'verified' });
+// "ui-citation ui-citation--chip ui-src--verified"
+ui.source({ state: 'generated' }); // "ui-source-card ui-src--generated"
+ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"
+```
+
+## Accessibility & print
+
+- A citation must be a real link or button with a stable accessible name; the
+  bracketed index alone is not enough.
+- The trust state must be readable as text — the tone dot/border is decorative
+  reinforcement. Under `forced-colors`, dots and borders fall back to
+  `CanvasText`, so the label remains the channel.
+- Tone dots and the card's tone border carry `print-color-adjust: exact`, so
+  they survive printing; expand citation URLs in print where it helps the reader.

package/docs/spotlight.md

@@ -0,0 +1,78 @@
+# Spotlight (guided focus)
+
+`@ponchia/ui/css/spotlight.css` is an opt-in **guided-focus overlay** — a
+dimming layer with a cutout over a target element, an optional ring, and a
+callout note. It's the *visual language* of a product tour or onboarding step.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/spotlight.css';
+```
+
+**Bronto is not a tour engine.** It owns the look and (via `initSpotlight`)
+positions the cutout over a target. Step order, advancing, persistence, and
+whether the overlay is shown are the host's job — Bronto deliberately stays out
+of that state machine.
+
+## Markup
+
+```html
+<div
+  class="ui-spotlight ui-spotlight--ring"
+  data-bronto-spotlight
+  data-target="save-button"
+  role="region"
+  aria-label="Tour"
+>
+  <div class="ui-spotlight__hole"></div>
+
+  <div class="ui-tour-note" style="position: absolute; …place near the hole…">
+    <span class="ui-tour-note__step">Step 2 of 4</span>
+    <h2 class="ui-tour-note__title">Save your work</h2>
+    <p class="ui-tour-note__body">Changes autosave, but you can force a save here.</p>
+    <div class="ui-tour-note__actions">
+      <button class="ui-button ui-button--ghost" type="button">Skip</button>
+      <button class="ui-button" type="button">Next</button>
+    </div>
+  </div>
+</div>
+```
+
+```js
+import { initSpotlight } from '@ponchia/ui/behaviors';
+const stop = initSpotlight(); // positions the cutout; re-places on resize/scroll
+// Advance the tour by pointing at the next target — the cutout follows:
+document.querySelector('[data-bronto-spotlight]').dataset.target = 'next-thing';
+// Hide it when the tour ends (host-owned):
+document.querySelector('[data-bronto-spotlight]').hidden = true;
+```
+
+## Pieces
+
+| Class | Role |
+| --- | --- |
+| `ui-spotlight` | The fixed overlay. Non-blocking (`pointer-events: none`) — a visual highlight, not a modal trap. |
+| `ui-spotlight__hole` | The cutout. Dims the page via one box-shadow; positioned by `--spot-x/y/w/h`. |
+| `ui-spotlight--ring` | Adds an accent ring around the cutout. |
+| `ui-tour-note` | The callout card (re-enables pointer events for its controls). |
+| `ui-tour-note__step` / `__title` / `__body` / `__actions` | Callout parts. |
+
+`ui.spotlight({ ring })` builds the overlay class string.
+
+## How positioning works
+
+`initSpotlight` reads each `[data-bronto-spotlight]`'s `data-target` id, measures
+that element with `getBoundingClientRect`, and sets `--spot-x/y/w/h` (viewport
+coordinates) on the overlay. Because the overlay is `position: fixed`, those map
+directly. It re-places on resize, scroll, and whenever `data-target` changes —
+so stepping a tour is just updating `data-target`. `--spot-pad` insets the
+cutout from the target; `--spot-radius` rounds it.
+
+## Accessibility notes
+
+- The overlay is **non-blocking by design** (the dim is a box-shadow, not an
+  interaction trap). If a step must block interaction, that's a host concern —
+  add your own inert/`aria-hidden` handling around it.
+- Put the tour's real content in `.ui-tour-note` (a focusable region with a
+  heading), not in the visual dim, so screen-reader users get the same guidance.
+- Keep the callout's label stable and move focus to it when a step opens (host).

package/docs/stability.md

@@ -11,6 +11,7 @@ patches are non-breaking. This matrix defines what counts as public API.
 | Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
+| Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. (A computed-style smoke test guards the OLED `--bg` flip; the others are unverified.) |
 | Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
 | Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
 | Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
@@ -18,7 +19,21 @@ patches are non-breaking. This matrix defines what counts as public API.
 | React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
 | Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
-| Reports (`css/report.css`, `.ui-report*`, `.ui-chart*`, print utilities) | Stable additive | Report class names, BEM part names, chart helper class names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. |
+| Reports (`css/report.css`, `.ui-report*`, `.ui-chart*`, print utilities) | Stable additive | Report class names, BEM part names, chart helper class names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`. |
+| Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
+| Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
+| Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
+| Connectors (`@ponchia/ui/connectors`, `css/connectors.css`, `.ui-connector*`, `initConnectors`) | Stable additive | Connector class names, the `data-bronto-connector` attribute contract, geometry helper function names, and recipe options are public. Helper internals/heuristics may tune before 1.0. Opt-in, not in the default bundle. |
+| Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
+| Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
+| Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
+| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the seven analytical leaves (annotations, legend, marks, connectors, spotlight, crosshair, selection). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
+| Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
+| Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
+| Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
+| Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |
+| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
 | Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
 

package/docs/state.md

@@ -0,0 +1,85 @@
+# Lifecycle & system state
+
+`@ponchia/ui/css/state.css` is an opt-in vocabulary for the states real apps
+spend their time in — saving, saved, queued, offline, stale, conflicted, locked,
+reviewed. These are usually improvised per product, so even good apps feel
+inconsistent. This is the canonical set: a labelled state object with a rationed
+tone, plus a page/document sync bar.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/state.css';
+```
+
+Bronto ships the visual states and the canonical wording. The host owns the
+state machine, retry policy, persistence, and announcements. **Persistent state
+deserves persistent UI** — a toast is secondary, not the answer. The tone is a
+second channel; the **label is the state**, so it survives forced-colors and
+screen readers (WCAG 1.4.1).
+
+## `.ui-state`
+
+A leading tone dot, a `__label`, and an optional `__detail`. Add `--busy` to
+pulse the indicator for an in-progress state (reduced-motion-safe).
+
+```html
+<span class="ui-state ui-state--saving ui-state--busy">
+  <span class="ui-state__label">Saving…</span>
+</span>
+
+<span class="ui-state ui-state--saved">
+  <span class="ui-state__label">Saved</span>
+  <span class="ui-state__detail">2m ago</span>
+</span>
+```
+
+## State matrix
+
+Use the canonical label; the modifier bakes in the tone.
+
+| State | Class | Canonical label | Tone | Busy? |
+| --- | --- | --- | --- | --- |
+| Saving | `ui-state--saving` | "Saving…" | accent | yes |
+| Saved | `ui-state--saved` | "Saved" / "All changes saved" | success | — |
+| Queued | `ui-state--queued` | "Queued" / "Pending" | muted | — |
+| Offline | `ui-state--offline` | "Offline" | warning | — |
+| Stale | `ui-state--stale` | "Out of date" | warning | — |
+| Conflict | `ui-state--conflict` | "Conflict" | danger | — |
+| Error | `ui-state--error` | "Failed" / "Couldn't save" | danger | — |
+| Locked | `ui-state--locked` | "Locked" / "Read-only" | muted | — |
+| Reviewed | `ui-state--reviewed` | "Reviewed" | success | — |
+| Needs review | `ui-state--needs-review` | "Needs review" | warning | — |
+
+"Syncing" and "Retrying" are the saving tone with their own label — use
+`ui-state--saving ui-state--busy` and write the word.
+
+## `.ui-syncbar`
+
+A page- or document-level status strip: a state on one side, optional actions on
+the other.
+
+```html
+<div class="ui-syncbar">
+  <span class="ui-state ui-state--saved">
+    <span class="ui-state__label">All changes saved</span>
+    <span class="ui-state__detail">just now</span>
+  </span>
+  <button class="ui-button ui-button--subtle ui-button--sm" type="button">View history</button>
+</div>
+```
+
+## Recipe
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
+ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
+```
+
+## Scope
+
+CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago") or live
+progress text is the host's job; a small optional behavior may come later if a
+real consumer needs it. Background-job progress and conflict-resolution
+affordances are deliberately deferred until then.

package/docs/usage.md

@@ -263,6 +263,28 @@ dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
   Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
   "Data-viz palette".
 
+## SVG annotations: subject, connector, note
+
+`@ponchia/ui/css/annotations.css` (opt-in) adds Bronto-styled SVG annotations
+for reports and chart figures. It is a visual grammar, not a charting or
+authoring engine.
+
+- Compose each callout from `ui-annotation` plus a subject
+  (`ui-annotation__subject`), connector (`ui-annotation__connector`), and note
+  (`ui-annotation__note`, `ui-annotation__title`, `ui-annotation__label`).
+- Use `ui.annotation({ variant, tone, motion })` when building class strings in
+  JS. The default is a callout in the accent tone; motion is always opt-in.
+- Use `@ponchia/ui/annotations` when you want deterministic SVG path strings
+  for circle, rect, threshold, bracket, band, slope, comparison, cluster, axis,
+  timeline, line, elbow, or curve annotations. Use `notePlacement()` for a
+  single bounded note when you need a conservative first placement pass.
+- Status tones are only for status-bearing callouts; otherwise use `accent` for
+  the main insight and `muted` for secondary labels.
+- Keep annotated charts sparse. Dense figures need a scrollable SVG, a
+  simplified mobile SVG, or complete caption/fallback text.
+- Annotation text must be visible or represented in the figure caption, SVG
+  `<desc>`, or fallback table. Full detail in [annotations.md](annotations.md).
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*

package/docs/workbench.md

@@ -0,0 +1,72 @@
+# Workbench — inspector, properties, selection bar
+
+`@ponchia/ui/css/workbench.css` is an opt-in set of primitives for **real
+tools**: an inspector panel, property rows for a selected object, and a bar of
+actions on the current selection. Generic kits stop at cards/tables/forms, so
+every app builds its own half-consistent workbench. This is the low-risk CSS
+core — layout and affordances only.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/workbench.css';
+```
+
+Resizable split panes (a focusable ARIA window-splitter behavior) and drag
+handles are deliberately deferred until a consumer needs them. Not in the core
+bundle.
+
+## Inspector — `.ui-inspector`
+
+A panel of details for the selected object: a `__header` (title + actions) over
+a `__body` of property rows.
+
+```html
+<aside class="ui-inspector">
+  <div class="ui-inspector__header">
+    <h2 class="ui-eyebrow">Rectangle</h2>
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Reset</button>
+  </div>
+  <div class="ui-inspector__body">
+    <!-- property rows -->
+  </div>
+</aside>
+```
+
+## Property row — `.ui-property`
+
+A label/value pair, denser than `ui-key-value` and tuned for an inspector. The
+`__value` can hold a static read-out or an input.
+
+```html
+<div class="ui-property">
+  <span class="ui-property__label">Width</span>
+  <span class="ui-property__value">240 px</span>
+</div>
+<div class="ui-property">
+  <span class="ui-property__label">Fill</span>
+  <span class="ui-property__value"><input class="ui-input" value="#121212" /></span>
+</div>
+```
+
+## Selection bar — `.ui-selectionbar`
+
+A raised bar of actions on the current selection: a `__count` on one side,
+`__actions` on the other. The host owns what is selected and what the actions do.
+
+```html
+<div class="ui-selectionbar">
+  <span class="ui-selectionbar__count">3 selected</span>
+  <span class="ui-selectionbar__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Group</button>
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Align</button>
+    <button class="ui-button ui-button--danger ui-button--sm" type="button">Delete</button>
+  </span>
+</div>
+```
+
+## Scope
+
+CSS only, no recipes — these are structural containers and rows; apply the
+classes directly (or read them from `cls.inspector`, `cls.property`, …). Pair
+the selection bar with the cross-cutting [`ui-sel`](./selection.md) states on the
+selected items themselves; Bronto styles both, the host owns the hit-testing.