npm - @ponchia/ui - Versions diffs - 0.6.0 → 0.6.3 - Mend

@ponchia/ui 0.6.0 → 0.6.3

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 (156) hide show

package/CHANGELOG.md +64 -4
package/README.md +1 -1
package/annotations/index.d.ts.map +1 -1
package/annotations/index.js +36 -33
package/behaviors/carousel.d.ts +28 -0
package/behaviors/carousel.d.ts.map +1 -0
package/behaviors/carousel.js +3 -0
package/behaviors/combobox.d.ts +40 -0
package/behaviors/combobox.d.ts.map +1 -0
package/behaviors/combobox.js +71 -20
package/behaviors/command.d.ts +41 -0
package/behaviors/command.d.ts.map +1 -0
package/behaviors/command.js +9 -0
package/behaviors/connectors.d.ts +17 -0
package/behaviors/connectors.d.ts.map +1 -0
package/behaviors/connectors.js +3 -0
package/behaviors/crosshair.d.ts +42 -0
package/behaviors/crosshair.d.ts.map +1 -0
package/behaviors/crosshair.js +19 -1
package/behaviors/dialog.d.ts +20 -0
package/behaviors/dialog.d.ts.map +1 -0
package/behaviors/dialog.js +3 -0
package/behaviors/disclosure.d.ts +10 -0
package/behaviors/disclosure.d.ts.map +1 -0
package/behaviors/disclosure.js +3 -0
package/behaviors/dismissible.d.ts +10 -0
package/behaviors/dismissible.d.ts.map +1 -0
package/behaviors/dismissible.js +3 -0
package/behaviors/forms.d.ts +27 -0
package/behaviors/forms.d.ts.map +1 -0
package/behaviors/forms.js +18 -5
package/behaviors/glyph.d.ts +14 -0
package/behaviors/glyph.d.ts.map +1 -0
package/behaviors/glyph.js +24 -0
package/behaviors/index.d.ts +31 -237
package/behaviors/index.d.ts.map +1 -0
package/behaviors/index.js +17 -0
package/behaviors/inert.d.ts +20 -0
package/behaviors/inert.d.ts.map +1 -0
package/behaviors/inert.js +46 -0
package/behaviors/internal.d.ts +25 -0
package/behaviors/internal.d.ts.map +1 -0
package/behaviors/internal.js +30 -1
package/behaviors/legend.d.ts +35 -0
package/behaviors/legend.d.ts.map +1 -0
package/behaviors/legend.js +9 -0
package/behaviors/menu.d.ts +16 -0
package/behaviors/menu.d.ts.map +1 -0
package/behaviors/menu.js +3 -0
package/behaviors/modal.d.ts +41 -0
package/behaviors/modal.d.ts.map +1 -0
package/behaviors/modal.js +124 -0
package/behaviors/popover.d.ts +28 -0
package/behaviors/popover.d.ts.map +1 -0
package/behaviors/popover.js +17 -17
package/behaviors/spotlight.d.ts +17 -0
package/behaviors/spotlight.d.ts.map +1 -0
package/behaviors/spotlight.js +3 -0
package/behaviors/table.d.ts +36 -0
package/behaviors/table.d.ts.map +1 -0
package/behaviors/table.js +48 -8
package/behaviors/tabs.d.ts +20 -0
package/behaviors/tabs.d.ts.map +1 -0
package/behaviors/tabs.js +3 -0
package/behaviors/theme.d.ts +54 -0
package/behaviors/theme.d.ts.map +1 -0
package/behaviors/theme.js +17 -0
package/behaviors/toast.d.ts +49 -0
package/behaviors/toast.d.ts.map +1 -0
package/behaviors/toast.js +34 -2
package/classes/classes.json +683 -13
package/classes/index.d.ts +106 -2
package/classes/index.js +249 -65
package/connectors/index.d.ts +12 -0
package/connectors/index.d.ts.map +1 -1
package/connectors/index.js +23 -2
package/css/app.css +26 -0
package/css/bullet.css +108 -0
package/css/code.css +98 -0
package/css/content.css +15 -2
package/css/crosshair.css +7 -7
package/css/diff.css +153 -0
package/css/disclosure.css +18 -4
package/css/dots.css +37 -7
package/css/feedback.css +39 -7
package/css/forms.css +71 -3
package/css/legend.css +5 -2
package/css/motion.css +79 -14
package/css/overlay.css +59 -2
package/css/primitives.css +67 -8
package/css/report.css +40 -0
package/css/sidenote.css +67 -0
package/css/spark.css +62 -0
package/css/table.css +9 -2
package/css/term.css +110 -0
package/css/textref.css +63 -0
package/css/toc.css +91 -0
package/css/tokens.css +14 -1
package/css/tree.css +134 -0
package/dist/bronto.css +1 -1
package/dist/css/analytical.css +1 -1
package/dist/css/app.css +1 -1
package/dist/css/bullet.css +1 -0
package/dist/css/code.css +1 -0
package/dist/css/content.css +1 -1
package/dist/css/crosshair.css +1 -1
package/dist/css/diff.css +1 -0
package/dist/css/disclosure.css +1 -1
package/dist/css/dots.css +1 -1
package/dist/css/feedback.css +1 -1
package/dist/css/forms.css +1 -1
package/dist/css/legend.css +1 -1
package/dist/css/motion.css +1 -1
package/dist/css/overlay.css +1 -1
package/dist/css/primitives.css +1 -1
package/dist/css/report.css +1 -1
package/dist/css/sidenote.css +1 -0
package/dist/css/spark.css +1 -0
package/dist/css/table.css +1 -1
package/dist/css/term.css +1 -0
package/dist/css/textref.css +1 -0
package/dist/css/toc.css +1 -0
package/dist/css/tokens.css +1 -1
package/dist/css/tree.css +1 -0
package/docs/annotations.md +39 -0
package/docs/architecture.md +2 -3
package/docs/bullet.md +78 -0
package/docs/code.md +76 -0
package/docs/d2.md +4 -3
package/docs/diff.md +146 -0
package/docs/legends.md +8 -4
package/docs/mermaid.md +21 -4
package/docs/reference.md +127 -8
package/docs/reporting.md +35 -14
package/docs/sidenote.md +64 -0
package/docs/spark.md +78 -0
package/docs/stability.md +1 -0
package/docs/term.md +81 -0
package/docs/textref.md +78 -0
package/docs/theming.md +44 -5
package/docs/toc.md +83 -0
package/docs/tree.md +74 -0
package/docs/usage.md +264 -23
package/docs/vega.md +22 -3
package/glyphs/glyphs.js +7 -1
package/llms.txt +159 -13
package/package.json +47 -7
package/qwik/index.d.ts +4 -2
package/qwik/index.d.ts.map +1 -1
package/qwik/index.js +10 -0
package/react/index.d.ts +4 -2
package/react/index.d.ts.map +1 -1
package/react/index.js +6 -0
package/solid/index.d.ts +6 -2
package/solid/index.d.ts.map +1 -1
package/solid/index.js +6 -0

package/docs/usage.md CHANGED Viewed

@@ -26,6 +26,14 @@ into a preset on `<html>` or any subtree:
 Scope it, don't globalize blindly: a dashboard with one marketing-style
 hero can set `compact` on `<html>` and `comfortable` on the hero section.
+> **`data-density` is the global preset; per-component density verbs differ by
+> family.** Some components carry their own local density modifier, and the verb
+> is **not** uniform: it's `--dense` on `ui-table`/`ui-dotgrid` but `--compact`
+> on `ui-prose`/`ui-legend`/`ui-report`. So `ui-prose--dense` and
+> `ui-table--compact` both no-op. When in doubt, reach for the global
+> `data-density` preset; use the local modifier only where it exists (check the
+> base's `modifiers` in classes.json).
 ## Badge vs chip vs status dot
 All three are small. They are **not** interchangeable:
@@ -35,18 +43,39 @@ All three are small. They are **not** interchangeable:
 | **status dot** | a single piece of state on something else (row online, build ok). Smallest possible signal; pair with text for a11y, never color-only. |
 | **badge**      | a label *classifying* the thing it sits on (count, tone, "BETA"). Static, not actionable. `ui.badge({ tone })`. |
 | **chip**       | a discrete, often removable/selectable token the user manipulated (a filter, a tag input value). Interactive affordance implied. |
+| **tag**        | a static keyword/category label (`ui.tag`), like a badge but reads as a non-interactive tag. Use `chip` for anything the user selects/removes; `tag` for a fixed label. |
 Rule of thumb: state → dot, classification → badge, user-controlled value
-→ chip.
+→ chip, fixed keyword → tag. (`ui-property` is a **workbench** primitive — a
+key/value spec row scoped to `@ponchia/ui/css/workbench.css`, not a general
+content label; don't reach for it to tag prose.)
 **Tone vocabulary varies by family — by design.** Colour is rationed, so not
-every component carries every tone: `--info`/`--muted` exist on some families
-(badge, dot, state) and not others (alert/toast/meter lead with
-`--success`/`--warning`/`--danger`). The authoritative per-component tone list is
-each base's `modifiers` array in
+every component carries every tone. The status tones
+(`--success`/`--warning`/`--danger`) plus `--info` ride the status families —
+`ui-alert`, `ui-toast`, `ui-meter`, `ui-dot`, and `ui-badge` all carry `--info`.
+The neutral `--muted` is **not** a status tone: it rides several *neutral*
+bases (`ui-badge`, `ui-num`, `ui-eyebrow`, `ui-mark`, `ui-annotation`,
+`ui-connector`, `ui-crosshair`) but is deliberately absent from the status
+families `ui-dot`/`ui-alert`/`ui-toast`/`ui-meter`. Because the CSS is a
+plain class list, a hand-written unknown modifier (e.g. `ui-dot--muted`,
+`ui-meter--muted`) **silently no-ops** — CSS can't warn. The `ui.*` builders are
+safer on both ends: TypeScript rejects an out-of-set tone at author time, and at
+runtime they `console.warn` (then drop the tone) so a JS caller sees the mistake
+rather than shipping a bare, untoned element. The authoritative
+per-component tone list is each base's `modifiers` array in
 [`@ponchia/ui/classes.json`](../classes/classes.json) — read it rather than
 extrapolating a tone you saw on one component onto another.
+**Tone is a colour channel, so it collapses under Windows High-Contrast Mode.**
+A `ui-badge--success` and a `ui-badge--danger` render identically once HCM
+remaps colours (the tinted background + tone border are flattened to one system
+colour). Status dots and the meter fill re-assert a distinct system colour, but
+the badge/chip/tag tints cannot carry five differentiable tones — so treat badge
+tone as **decorative emphasis** and make sure the badge's text label carries the
+status word ("Failed", not a bare red pill). Same WCAG 1.4.1 reasoning the dots
+follow.
 ## Numbers: `ui-num` vs the table state classes
 - Inside `.ui-table`, a numeric cell is `.is-num` (+ `.is-pos` /
@@ -57,6 +86,21 @@ extrapolating a tone you saw on one component onto another.
   freed from the table. Do not hand-roll right-align + `text-green`;
   that's the duplication `ui-num` exists to kill.
+**The positive/negative vocabulary is spelled three ways — match the mechanism
+to the host, they are not interchangeable:**
+| Where | Positive / negative | Kind |
+| --- | --- | --- |
+| `ui-num` primitive (anywhere) | `ui-num--pos` / `ui-num--neg` (`ui.num({ tone: 'pos' })`) | **modifier** |
+| Inside `.ui-table` | `is-pos` / `is-neg` | **state hook** (table-scoped) |
+| `ui-delta` trend | `ui-delta--up` / `ui-delta--down` (`ui.delta({ dir })`) | **direction** |
+They share the same tone tokens but **don't cross over**: `ui-num is-pos`
+no-ops (the `is-pos` rule is scoped to table cells), and `ui-delta--pos` doesn't
+exist. Use the modifier on `ui-num`, the `is-*` state inside a table, and
+`--up`/`--down` on `ui-delta` (which also flips with `ui.delta({ invert })` when
+up is the *bad* direction — latency, error rate, cost).
 ## Prose vs primitives, and prose inside a card
 - `ui-prose` styles **raw, unclassed semantic HTML** (MDX / CMS / LLM
@@ -68,6 +112,42 @@ extrapolating a tone you saw on one component onto another.
   `.ui-card` itself, so card padding/border stays the card's and prose
   rhythm stays the content's. One responsibility per element.
+## Centred width: `ui-center` vs `ui-container`
+Both cap a centred column, but they are **different primitives with different
+box models** — pick by intent:
+- **`ui-center`** — a *reading measure*. `--center-max` is the **inner** content
+  width (content-box); the `--center-gutter` padding adds *outside* it. Use it to
+  hold prose/body to a comfortable line length.
+- **`ui-container`** — a *page frame*. `--container` (/`--container-narrow`
+  /`--container-wide`) is the **total** max width (border-box). Use it as the
+  outer wrapper that aligns a page's sections to a shared edge.
+Rule of thumb: measure of text → `ui-center`; page-level frame → `ui-container`.
+Don't nest one inside the other expecting the caps to compose — they measure
+different boxes.
+## Container queries: `ui-cq`
+`ui-cq` is the one primitive that changes how *other* primitives respond. Add it
+to a wrapper and its descendants adapt to **that box's** inline size, not the
+viewport — so the same `ui-grid` / `ui-statgrid` / `ui-app-metrics` collapses to
+one column inside a slim panel even when the window is wide (island-safe; it
+nests). Two thresholds are built in: `ui-grid` drops to a single column at
+**34rem** and `ui-statgrid`/`ui-app-metrics` at **30rem**, measured on the `ui-cq`
+box. Note `rem` in a container query resolves against the **root** font size, not
+16px — at Bronto's 15px root that's ≈**510px** and ≈**450px**, ~6% tighter than a
+16px mental model. And be aware `ui-grid` already collapses on its own via an
+intrinsic `auto-fit` minmax, so `ui-cq` barely changes it — the primitive that
+genuinely *needs* `ui-cq` to collapse by container (not viewport) is
+`ui-statgrid`/`ui-app-metrics`. The container is named `bronto` (hardcoded — there
+is no `--cq-name` knob; an author-set one is ignored), so an outer query never
+accidentally matches an inner grid. `ui-cq` is inert until applied, so adding it
+never shifts an existing layout. Reach for it whenever a layout must respond to
+its container (a resizable pane, a sidebar widget, an embedded card) rather than
+the page.
 ## Static reports
 Use the opt-in `@ponchia/ui/css/report.css` layer for static, PDF-first
@@ -126,10 +206,22 @@ Both are a thin horizontal bar; they mean different things.
   indeterminate (`ui-progress--indeterminate`). The fill is always accent.
 - **`ui-meter`** — a *measured static value*: coverage, disk, capacity, a
   KPI against a target. Never indeterminate. Tone the fill by threshold
-  (`ui.meter({ tone })` → accent/success/warning/danger); the unset
-  default is neutral. Drive the width with the shared `--value` knob
-  (`style="--value: 72"`, 0–100) and author `role="meter"` +
-  `aria-valuenow/min/max` for AT.
+  (`ui.meter({ tone })` → accent/success/warning/danger/info); the unset
+  default is neutral. Drive the width with the shared `--value` knob — a
+  **unitless number 0–100** (`style="--value: 72"`, *not* `72%`: a `%` is
+  invalid against the registered `<number>` type and the fill drops to empty).
+  The class string paints a 0-width, unannounced bar on its own, so set the
+  value **and** its ARIA together with `attrs.meter(72)` (or `attrs.progress`)
+  from `@ponchia/ui/classes` — it returns `role="meter"` +
+  `aria-valuenow/min/max` + the `--value` style, normalized to your
+  `{ min, max }`. Spread it: `<div class={ui.meter({ tone })} {...attrs.meter(72)}>`.
+  **Indeterminate progress** is the one exception: call `attrs.progress()` with
+  **no argument**. ARIA requires `aria-valuenow` be *omitted* for an indeterminate
+  bar — emitting `0` would announce "0%", indistinguishable from a real stalled-at-
+  zero bar — so the helper returns just `role="progressbar"` + `aria-busy="true"`
+  (no `aria-valuenow`, no `--value`). Pair it with the class:
+  `<div class={ui.progress({ indeterminate: true })} {...attrs.progress()}>`.
 Rule of thumb: *something is happening* → progress; *something measures
 this much* → meter.
@@ -139,7 +231,10 @@ this much* → meter.
 - **`ui-steps`** — a stepper for a multi-step flow. Use an `<ol>`. State is
   ARIA-driven (the framework rule): the active step is `aria-current="step"`
   (no class); completed steps take `ui-steps__item--done`. Markers are
-  auto-numbered by CSS counter.
+  auto-numbered by CSS counter. `--done` is a **visual** state only — it isn't
+  announced, so if "completed" must reach AT, add visually-hidden text
+  (e.g. `<span class="ui-visually-hidden">completed</span>`) or an `aria-label`
+  on the step.
 - **`ui-timeline`** — a vertical event list on a hairline spine (`<ol>` of
   `ui-timeline__item`, optional `ui-timeline__time`). `aria-current` on an
   item marks the live/most-recent event.
@@ -161,18 +256,76 @@ without it these widgets are unlabelled or unannounced:
 - **`ui-pagination`** — wrap it in `<nav aria-label="Pagination">`; give the
   current page `aria-current="page"`; label icon-only prev/next controls
   (`aria-label="Previous page"`). Disable a control with native `disabled`
-  (a `<button>`) **or** `aria-disabled="true"` — both now render disabled and
-  are non-interactive; don't ship an `aria-disabled` control that still acts.
+  (a `<button>`) for full inertness, **or** `aria-disabled="true"` for a control
+  that stays focusable/announced (e.g. a disabled `<a>`). CSS dims both and makes
+  `aria-disabled` pointer-inert, but only native `disabled` is keyboard-inert on
+  its own — to stop an `aria-disabled` control from activating on Enter/Space,
+  wire `initDisabledGuard()` once near your root (see Behaviors).
 - **`ui-tabs`** — `initTabs` adds the full APG wiring (roles, roving tabindex,
   `aria-selected`, panel `hidden`, focusable panel). If you wire tabs yourself,
   name the `ui-tabs__list` (`role="tablist"` + an `aria-label`) and pair each
-  tab with its panel via `aria-controls`/`aria-labelledby`.
+  tab with its panel via `aria-controls`/`aria-labelledby`. Every tab needs a
+  matching panel — a tab with no `aria-controls` target is an orphan that
+  announces as selected but reveals nothing.
+- **Icon-only buttons** (`ui-button--icon` and any glyph-only control) carry no
+  text node, so they're nameless to AT — give them an `aria-label`
+  (`<button class="ui-button ui-button--icon" aria-label="Delete">`).
 - **`ui-sitenav` / `ui-app-nav`** — signal the current link with
   `aria-current="page"` (both honour it; `ui-app-nav` also accepts the
   visual-only `.is-active`, but prefer `aria-current`).
 - **`ui-skiplink`** — keep it the first focusable element and point its `href`
   at the `id` of your main landmark.
+## App shell: the admin dashboard frame
+`ui-app-shell` is a CSS-only two-column admin frame (sidebar rail + main
+column) that collapses to a single column with a horizontal rail below 880px —
+no behavior required. The nesting matters; the rail is `ui-app-rail` and the
+content side is `ui-app-main`:
+```html
+<div class="ui-app-shell">
+  <aside class="ui-app-rail">
+    <span class="ui-app-rail__brand">Acme</span>
+    <nav class="ui-app-nav" aria-label="Primary">
+      <span class="ui-app-nav__section">Main</span>
+      <a href="/overview" aria-current="page">Overview</a>
+      <a href="/reports">Reports</a>
+    </nav>
+    <div class="ui-app-rail__account">…</div>
+  </aside>
+  <main class="ui-app-main">
+    <header class="ui-app-topbar"><h1 class="ui-app-topbar__title">Overview</h1></header>
+    <div class="ui-app-content">
+      <section class="ui-app-panel">
+        <div class="ui-app-panel__head"><h2 class="ui-app-panel__title">KPIs</h2></div>
+        <div class="ui-app-metrics">…<div class="ui-app-metric">…</div></div>
+      </section>
+    </div>
+  </main>
+</div>
+```
+Knobs: `--app-rail` sets the rail width (default 14rem); `ui-app-shell--full`
+drops the rail for a single-column app. `ui-app-nav` honours `aria-current="page"`
+(preferred) and the visual-only `.is-active`.
+## Menus: `data-bronto-menu` + `initMenu`
+A dropdown menu is a native `<details data-bronto-menu>` styled as
+`ui-menu-host` → `ui-menu` (with `ui-menu__item` / `ui-menu__sep` /
+`ui-menu__label`). It opens/closes natively, but `initMenu()` adds the close
+affordances a menu needs: outside-click close, Escape, and closing on item
+activation. Without the behavior the menu opens but never dismisses itself.
+**Clipping limitation.** The menu panel is positioned in normal flow (not the
+top layer), so an ancestor with `overflow: hidden`/`auto` or a transform
+**clips** it — the same edge case the tooltip has. If your menu lives inside a
+scroll container or a clipped card and the panel gets cut off, either lift the
+`ui-menu-host` out of the clipping ancestor, or reach for `initPopover` (which
+escapes to the browser top layer via the native `popover` attribute) for that
+control instead.
 ## Avatar: it's an unlabelled blob until you name it
 `ui-avatar` is a presentation box. Give it an accessible name yourself: an
@@ -185,11 +338,24 @@ convey identity to AT. Keep initials to ~2 characters — the box is
 ## Modal: native `<dialog>` vs `is-open`
 Prefer the **native `<dialog>`** path — you get top-layer, backdrop and
-focus-trap free. Only use `ui-modal.is-open` (`ui.modal({ open: true })`)
-when a portal/React modal genuinely can't be a `<dialog>`; then the
-backdrop and focus-trap are **yours** to provide. A drawer is a modal
+focus-trap free (wire it with `initDialog` for open-triggers + focus-return).
+Only use `ui-modal.is-open` (`ui.modal({ open: true })`) when a portal/React
+modal genuinely can't be a `<dialog>`. The **backdrop and top-layer stacking
+stay yours**, but you no longer have to hand-roll the focus trap: mark the
+overlay `data-bronto-modal` and call `initModal()`. While `is-open` it traps
+focus with `inert` (the rest of the page goes non-interactive), returns focus to
+the opener on close, and dispatches a cancelable `bronto:modal:close` on Escape —
+you still own the `is-open` class, so drop it in response. On bind `initModal`
+also gives the overlay `role="dialog"` + `aria-modal="true"` and dev-warns if it
+has no accessible name (add `aria-label`/`aria-labelledby`). A drawer is a modal
 that enters from an edge — same rule.
+**Scroll-lock is not automatic on either path.** Neither the native `<dialog>`
+nor the `is-open` path freezes the background — the page behind an open modal can
+still scroll. If that matters, toggle a lock yourself while the modal is open
+(`document.documentElement.style.overflow = 'hidden'`, restored on close), or add
+`html:has(dialog[open]) { overflow: hidden }` for the native path.
 ## Carousel & lightbox: one primitive, two skins
 `ui-carousel` is a scroll-snap track of `__slide`s wired by `initCarousel`
@@ -347,11 +513,25 @@ authoring engine.
   `ui-button`): the browser greys it, blocks activation, and skips it in tab
   order, and bronto styles the disabled cue. Use `aria-disabled="true"` **only**
   when the control must stay focusable/announced — bronto then adds
-  `pointer-events: none` to `ui-button`/`ui-link` so it can't be activated, but
-  you still own removing it from the submit logic.
+  `pointer-events: none` to `ui-button`/`ui-link` so the pointer can't activate
+  it. That is **pointer-inert, not keyboard-inert**: CSS can't stop Enter/Space,
+  so wire `initDisabledGuard()` (Behaviors) to block keyboard activation across
+  every `aria-disabled` control. Either way you still own removing it from the
+  submit logic.
+- **Read-only ≠ disabled.** A `readonly` input keeps its value in form submission
+  and stays focusable/selectable; `disabled` does neither. Bronto gives a
+  read-only field a quiet muted fill so it doesn't read as a live editable field —
+  reach for `readonly` when the value matters but mustn't be edited, `disabled`
+  when it should be inert and skipped.
 - **Combobox** (`data-bronto-combobox`) reads its options from the DOM at
-  `initCombobox()` time — re-run it after you replace the option list. The
-  `<input>` owns the value; the listbox is a view.
+  `initCombobox()` time — re-run it after you replace the option list (or add
+  `data-bronto-combobox-live`). The selected **option's text label** is shown in
+  the input while the `bronto:change` event carries the option's `data-value`
+  code — so put the human label in the `<li>` text and the code in `data-value`.
+  The `.ui-combobox__empty` ("No matches") is hidden until a filter empties the
+  list. Two intentional single-select APG deviations: ArrowDown on a closed list
+  filters rather than pre-selecting the first option, and Tab closes without
+  committing a merely-highlighted option (Enter/click commits).
 - **Validation** is opt-in via `data-bronto-validate` on the form plus
   `initFormValidation()`; it surfaces messages into a `ui-error-summary` you
   provide. The summary's title is the legible sans, not the display face — it's
@@ -366,6 +546,16 @@ With scripting disabled it degrades to fully visible, but if scripting is *on*
 and nothing toggles `is-visible`, the content stays hidden — so only use
 `ui-reveal` when you are wiring that toggle.
+**View transitions (`ui-vt`).** `ui-vt` names an element via `--ui-vt-name` so it
+morphs across a `document.startViewTransition()` or a cross-document navigation.
+The name must be **unique per document** at the moment a transition runs: applying
+`ui-vt` with one shared `--ui-vt-name` across every card in a list (the obvious
+loop) makes the browser skip the transition — and it is **not** silent: it logs a
+console error and **rejects `vt.ready`** (with an `InvalidStateError`). If you
+don't `vt.ready.catch(…)`, that surfaces as an unhandled promise rejection. Give
+each element its own name (`--ui-vt-name: card-7`) or only mark the single element
+that actually morphs.
 ## Loading affordances need a role you supply
 `ui-spinner`, `ui-dotspinner`, `ui-skeleton`, and an indeterminate `ui-progress`
@@ -382,13 +572,64 @@ without it, it falls back to an `is-open` class that a clipping ancestor can cut
 off. Add `popover` to the panel for the robust path — the `is-open` form is a
 fallback, not the default to copy.
+It is a **non-modal** dialog by design: the panel gets `role="dialog"` and focus
+moves into it, but there is **no focus trap** and the rest of the page stays
+interactive — Tab moves *out* of the panel (it does not cycle), and it closes on
+Escape or outside-click. Don't assume `<dialog>`-modal semantics; if you need a
+trap and an inert backdrop, use a real modal (`<dialog>` + `initDialog`, or
+`initModal`). And the `is-open` fallback is a plain stacked element, so it sits
+*under* any open native `<dialog>`'s top layer — another reason to prefer the
+native `popover` attribute when a popover and a dialog can be open together.
+## Two tiers: CSS-native vs behavior-required
+Not every component works with JavaScript off — know which tier you are shipping
+before you rely on the no-JS path.
+**CSS-native — fully operable with JS off.** Safe in static or LLM-authored
+HTML, print/PDF, and before any hydration:
+| Component | How it works without JS |
+| --- | --- |
+| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` (+ anchor positioning where supported) |
+| Accordion | native `<details>` / `<summary>` |
+| Segmented control (`ui-segmented`) | `:has(input:checked)` over a radio group |
+| Scroll-reveal (`ui-scroll-reveal`) | scroll-driven animation, zero JS |
+| Modal via native `<dialog>` | the element brings focus-trap + Escape; `initDialog` only adds open-triggers + focus-return |
+**Behavior-required — a CSS skin that needs its `init*` to be interactive.**
+These are JS widgets wearing the Bronto look; without the behavior they are inert
+(and a couple are *worse* than inert — see the tabs row):
+| Component | Behavior | With the behavior absent |
+| --- | --- | --- |
+| Tabs (`ui-tabs`) | `initTabs` | **author panels visible** — ship `hidden` panels and if `initTabs` never runs the content is unreachable |
+| Combobox (`ui-combobox`) | `initCombobox` | a plain text input beside an unfiltered list |
+| Command palette (`ui-command`) | `initCommand` | a static, unfiltered list |
+| Table sort/select (`[data-bronto-sortable]`) | `initTableSort` | a static table (still readable) |
+| Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
+| Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
+| Controlled modal (`ui-modal.is-open`) | `initModal` | no focus trap — provide one or use native `<dialog>` |
+| Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
+| Toast | `toast()` | nothing — it is imperative-only |
+One cross-cutting guard, not tied to a single component:
+| Concern | Behavior | With the behavior absent |
+| --- | --- | --- |
+| `aria-disabled="true"` controls | `initDisabledGuard` | dimmed + pointer-inert via CSS, but still **keyboard**-activatable on Enter/Space (native `disabled` is already fully inert) |
+Rule of thumb: if a component needs ARIA-state sync, focus management, a keyboard
+model, or persisted/dynamic state, it is behavior-required — that is the exact
+boundary of what CSS alone cannot do.
 ## When to add a behavior
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*
 home for the little JS that genuinely needs scripting (theme persistence,
-disclosure, dialog glue, toast, combobox, form-validation, table-sort).
-Reach for it instead of reimplementing — every initializer is SSR-safe,
-idempotent, and returns a cleanup. If you find yourself writing focus
+disclosure, dialog glue, modal focus-trap, toast, combobox, form-validation,
+table-sort). Reach for it instead of reimplementing — every initializer is
+SSR-safe, idempotent, and returns a cleanup. If you find yourself writing focus
 management or `aria-expanded` toggling by hand, there is probably already
 a behavior for it.

package/docs/vega.md CHANGED Viewed

@@ -65,8 +65,9 @@ vega-embed 7), so don't mix a Vega-Lite 6 with a Vega 5 runtime:
 <script src="https://cdn.jsdelivr.net/npm/vega-lite@6.4.3/build/vega-lite.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/vega-embed@7.1.0/build/vega-embed.min.js"></script>
 <script>
-  // INLINE the config (copy the object for your theme from @ponchia/ui/vega.json).
-  // This is the only path that also works from a file:// report — see below.
+  // INLINE the config — generate the paste-ready literal with
+  // `npm run emit:theme vega light` (mirrors the annotations author-time-copy
+  // pattern). This is the only path that also works from a file:// report.
   const brontoLight = {
     /* …paste tokens/vega.json → light here… */
   };
@@ -78,12 +79,30 @@ vega-embed 7), so don't mix a Vega-Lite 6 with a Vega 5 runtime:
 > `import` the `@ponchia/ui/vega` module **nor** `fetch('…/vega.json')` — the
 > browser blocks both across the `null`/file origin (CORS). So for a
 > double-clickable or PDF-bound report, **inline the resolved config object**
-> (as above) rather than fetching it. Over an `http(s)` origin (a dev server, a
+> (as above) rather than fetching it. Generate the paste-ready, sentinel-tagged
+> literal with `npm run emit:theme vega light` (or `dark`); re-running
+> `npm run emit:theme:check <file>` re-derives every tagged block and fails if a
+> token change has left an inlined copy stale. Over an `http(s)` origin (a dev server, a
 > static host, a bundler), the `import { brontoVegaConfig }` form and a
 > `fetch('https://cdn.jsdelivr.net/npm/@ponchia/ui@VERSION/tokens/vega.json')`
 > both work — pin the package version in the URL, since the unversioned latest
 > may predate this target.
+**Over `http(s)`, skip the inline copy — import the helper as an ES module.**
+`tokens/vega.js` (the `@ponchia/ui/vega` entry) has **zero dependencies**, so it
+loads straight from a CDN as a browser ES module with no bundler and no
+import-map. You get `brontoVegaConfig(theme)` itself (live theme switching), not
+a frozen object to keep in sync. Pin the package version; this needs a real
+origin (it does **not** work from `file://` — use the inline form above there):
+```html
+<script type="module">
+  import { brontoVegaConfig } from 'https://cdn.jsdelivr.net/npm/@ponchia/ui@VERSION/tokens/vega.js';
+  // vegaEmbed loaded from its UMD bundle above (window.vegaEmbed), or import it as ESM too.
+  vegaEmbed('#chart', spec, { config: brontoVegaConfig('light'), renderer: 'svg', actions: false });
+</script>
+```
 For a build step or non-JS host, read `@ponchia/ui/vega.json` directly
 (`{ light, dark }`, each a ready Vega-Lite `config`).

package/glyphs/glyphs.js CHANGED Viewed

@@ -1027,7 +1027,13 @@ export function renderGlyph(name, options = {}) {
   const style = [`--dotmatrix-cols:${GLYPH_SIZE}`];
   const dotLen = dot && cssLen(dot);
   const gapLen = gap && cssLen(gap);
-  if (dotLen) style.push(`--dotmatrix-dot:${dotLen}`);
+  // Default the dot track to an intrinsic icon scale when the author set no
+  // (valid) `--dotmatrix-dot`. Without it the CSS grid falls back to
+  // `minmax(0, 1fr)` and the 16×16 matrix balloons to fill its container
+  // (full-bleed, ~1250px) — the string API would then render an icon-intent call
+  // very differently from the DOM `initDotGlyph` path, which already defaults to
+  // 0.08em. Mirror that default here so both paths render the same icon. (C7.)
+  style.push(`--dotmatrix-dot:${dotLen || '0.08em'}`);
   // Solid mode fuses the dots into a crisp pixel glyph: square cells, no gap.
   if (solid) style.push('--dotmatrix-dot-radius:0', '--dotmatrix-gap:0');
   else if (gapLen) style.push(`--dotmatrix-gap:${gapLen}`);