@ponchia/ui 0.8.1 → 0.9.0

package/docs/package-contract.md

@@ -49,6 +49,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/skins.css` | `./dist/css/skins.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/dataviz.css` | `./dist/css/dataviz.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/report.css` | `./dist/css/report.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/row.css` | `./dist/css/row.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
 | `./css/figure.css` | `./dist/css/figure.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/annotations.css` | `./dist/css/annotations.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/legend.css` | `./dist/css/legend.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
@@ -94,6 +95,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/unlayered/skins.css` | `./css/skins.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/dataviz.css` | `./css/dataviz.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/report.css` | `./css/report.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/row.css` | `./css/row.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/figure.css` | `./css/figure.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/annotations.css` | `./css/annotations.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/legend.css` | `./css/legend.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -300,6 +302,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/migrations/0.5-to-0.6.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.6-to-0.7.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/migrations/0.7-to-0.8.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.8-to-0.9.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0001-color-system.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0002-scope-and-2026-baseline.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0003-theme-model.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -316,7 +319,7 @@ result. The listed gates are part of `npm run check`.
 | Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh; check:exports; check:pack; check:consumer-surface; check:consumer-types; check:publint; check:attw | The complete export/file matrix in this document is generated from the manifest; packed tarball imports, concrete file resolution, and package-level type resolution are smoke-tested in clean consumers. |
 | Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/figma.variables.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; figma:variables:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved and Figma handoff values are visual tuning before 1.0. |
 | Class registry | `classes/index.js plus css/*.css selectors` | classes/classes.json; classes/index.d.ts; classes/vscode.css-custom-data.json; docs/reference.md | `npm run classes:json:build; dts:build; vscode:build; reference:build` | check:fresh; check:classes; check:contract | The typed registry, JSON vocabulary, and generated reference stay aligned with real selectors. |
-| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (46 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
+| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (47 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
 | JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/; svelte/; vue/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
 | Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; check:unit | Glyph names and render options are public. The registry stays sorted and type-covered. |
 | Display colorways | `tokens/skins.js` | css/skins.css; tokens/skins.d.ts | `npm run skins:build` | check:skins; check:contrast | Skins are opt-in root-level choices and never part of dist/bronto.css. |

package/docs/reference.md

@@ -9,7 +9,7 @@ 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).
 
-- 669 classes across 183 component groups
+- 677 classes across 184 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`,
@@ -874,6 +874,8 @@ each one matches a real selector in the stylesheet.
 | `cls.menuItem` | `ui-menu__item` | part |
 | `cls.menuLabel` | `ui-menu__label` | part |
 | `cls.menuSep` | `ui-menu__sep` | part |
+| `cls.menuAtPointer` | `ui-menu--at-pointer` | modifier |
+| `cls.menuDropdown` | `ui-menu--dropdown` | modifier |
 
 ### `.ui-menu-host`
 
@@ -1117,6 +1119,17 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.reveal` | `ui-reveal` | base |
 
+### `.ui-row`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.row` | `ui-row` | base |
+| `cls.rowMark` | `ui-row__mark` | part |
+| `cls.rowMeta` | `ui-row__meta` | part |
+| `cls.rowTitle` | `ui-row__title` | part |
+| `cls.rowRuled` | `ui-row--ruled` | modifier |
+| `cls.rowStacked` | `ui-row--stacked` | modifier |
+
 ### `.ui-screen-only`
 
 | Registry key | Class | Kind |

package/docs/reporting.md

@@ -54,18 +54,18 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/report-kit.css" />
 ```
 
 Leaf-by-leaf CDN imports use the same `dist/css/` paths:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -879,7 +879,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.1/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/stability.md

@@ -1,7 +1,7 @@
 # Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.8.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.9.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
@@ -140,6 +140,7 @@ current public-surface matrix and the release policy above still applies.
 | 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. |
+| Rows (`css/row.css`, `.ui-row*`) | Stable additive | Class names, the `__title` / `__meta` / `__mark` parts, the `--stacked` / `--ruled` modifiers, and the selection contract are public: `aria-selected`, `aria-current` and `.is-selected` all paint the selected state, so the visual state cannot disagree with the announced one. `__title` is the part that truncates and `__meta` is the part that does not — that asymmetry is the contract, not a detail. **In the default bundle**, unusually for a new surface: `.ui-menu__item` composes it, so a core component depends on it. Also exported standalone, which is why it appears here, but it is NOT opt-in. |
 | 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 nine analytical leaves (figure, annotations, legend, marks, connectors, spotlight, crosshair, selection, highlights). 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--*`, `initSources`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), the optional `data-bronto-sources` / `data-bronto-source-ref` behavior contract, `bronto:source:focus`, and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |

package/docs/theming.md

@@ -130,6 +130,22 @@ 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).
+
+  **Read this before relying on the preset.** It re-points the `--space-*`
+  scale, and only components whose padding is *expressed in that scale* move
+  with it — around 40 of them, including `ui-panel`, `ui-modal__body`,
+  `ui-evidence-item`, `ui-claim`, `ui-job`, `ui-code__body` and the report
+  surfaces. The rest carry tuned padding pairs like `0.5rem 0.55rem`, which the
+  seven-step scale cannot express, so **they do not respond at all** —
+  `ui-alert` and `ui-menu__item` are the two most likely to surprise you.
+
+  That is a real limit, not an oversight to work around: flattening a tuned pair
+  onto the nearest scale step would change how those components look at the
+  default density, which is the one nearly everyone uses. If you need a denser
+  variant of a component that does not respond, override its padding directly —
+  and if you find yourself doing that repeatedly for the same component, that is
+  worth reporting, because it is evidence for a real `--dense` modifier rather
+  than a preset that half-works.
 - **Dark surface** — the dark theme's base is a deliberately *elevated*
   near-black (`--bg: #121212`) for readability: pure black + bright text
   causes halation, and near-black-on-black surface steps are imperceptible.

package/docs/usage.md

@@ -186,6 +186,48 @@ a `.ui-legend` key, and fallback data. Full LLM/static report cookbook:
   spinner is CSS. This is the ARIA-driven contract — see reference.md
   → "Composition & state".
 
+## Rows: `ui-row` vs table vs menu item
+
+Three shapes look alike and are not interchangeable:
+
+- **`ui-table`** when the data has columns and a header. A table promises that
+  the third cell means the same thing on every line.
+- **`ui-menu__item`** when the list is a menu: it dismisses on choice, and it is
+  reached through `ui-menu-host`.
+- **`ui-row`** for everything else — a search result, a file in an explorer, an
+  outline entry, a backlink, a commit. A full-width clickable line that
+  *persists*.
+
+```html
+<button class="ui-row ui-row--ruled" type="button" aria-current="true">
+  <span class="ui-row__mark" aria-hidden="true">◆</span>
+  <span class="ui-row__title">apps/server/src/collab/room.ts</span>
+  <span class="ui-row__meta">4m</span>
+</button>
+```
+
+The one rule worth knowing: **`__title` is what truncates.** It takes the slack
+and gives it back first; `__meta` never shrinks, because a half-rendered number
+is worse than no number.
+
+**Pick the right attribute, and it is probably not `aria-selected`.** That one
+is only valid on a row whose role accepts it — `option` inside a `listbox`, or
+`row` / `tab` / `gridcell` / `treeitem`. On a bare `<button>` it is invalid ARIA
+and axe rates it *critical*; this project shipped that mistake in its own demo
+and the a11y gate caught it before release.
+
+- `aria-current="true"` — the row is the current one. The common case, and valid
+  on any element.
+- `aria-selected="true"` — only when the row really is an `option` in a
+  `listbox`, or another role that accepts it.
+- `.is-selected` — when neither fits.
+
+All three paint the same, so the visual state cannot disagree with the announced
+one. Rows carrying a severity should use `ui-severity-row` (`css/state.css`)
+instead, which adds the tone gutter.
+
+`ui-menu__item` composes `ui-row`, which is why they cannot drift.
+
 ## Empty state vs invite
 
 Both use `ui-empty-state`, and the slots are the same three parts — a quiet

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.8.1/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
-  "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.",
+  "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.",
   "keywords": [
     "css",
     "ui",
@@ -114,6 +114,7 @@
     "docs/migrations/0.5-to-0.6.md",
     "docs/migrations/0.6-to-0.7.md",
     "docs/migrations/0.7-to-0.8.md",
+    "docs/migrations/0.8-to-0.9.md",
     "docs/adr/0001-color-system.md",
     "docs/adr/0002-scope-and-2026-baseline.md",
     "docs/adr/0003-theme-model.md",
@@ -279,6 +280,7 @@
     "./css/skins.css": "./dist/css/skins.css",
     "./css/dataviz.css": "./dist/css/dataviz.css",
     "./css/report.css": "./dist/css/report.css",
+    "./css/row.css": "./dist/css/row.css",
     "./css/figure.css": "./dist/css/figure.css",
     "./css/annotations.css": "./dist/css/annotations.css",
     "./css/legend.css": "./dist/css/legend.css",
@@ -324,6 +326,7 @@
     "./css/unlayered/skins.css": "./css/skins.css",
     "./css/unlayered/dataviz.css": "./css/dataviz.css",
     "./css/unlayered/report.css": "./css/report.css",
+    "./css/unlayered/row.css": "./css/row.css",
     "./css/unlayered/figure.css": "./css/figure.css",
     "./css/unlayered/annotations.css": "./css/annotations.css",
     "./css/unlayered/legend.css": "./css/legend.css",