@ponchia/ui 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,86 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.9.0 — 2026-08-11
+
+Two additions and one correction, all from the same source: migrating a
+downstream workbench onto 0.8.1 and watching where adoption stalled.
+
+### Added
+
+- **`.ui-row` — the dense selectable row, in the default bundle.** Every
+  workbench grows a list of these: a search result, a file in an explorer, an
+  outline entry, a backlink, a commit. Bronto already had the shape and it was
+  imprisoned — `.ui-menu__item` was exactly it, minus the persistence — so a
+  consumer building an explorer either claimed to be a menu or wrote the row
+  again. The one that migrated had **63 families of it, about 1,200 lines**,
+  each re-deciding the selected state, the hover, the ellipsis and the coarse
+  floor.
+
+  `__title` is the part that truncates and `__meta` is the part that does not;
+  that asymmetry is the contract. Selection reads `aria-selected` /
+  `aria-current` — the attributes a host already sets for assistive tech — so
+  the visual state cannot disagree with the announced one. `--stacked` for a
+  row with a snippet, `--ruled` for a list that reads as one object.
+
+  Selection: use **`aria-current`** for a row that is merely the current one —
+  that is the common case and valid anywhere. `aria-selected` is only legal on a
+  role that accepts it (`option` in a `listbox`, or `row`/`tab`/`gridcell`/
+  `treeitem`); on a bare `<button>` it is invalid ARIA and axe rates it
+  *critical*. This release's own demo shipped that mistake, three a11y specs
+  went red, and a new unit gate now catches the same class of error in
+  milliseconds rather than twenty minutes of browser matrix.
+
+  `min-inline-size: 0` is on the row itself and is not optional: a row is
+  usually a flex or grid item, whose automatic minimum is its min-content width,
+  and `__title` is `white-space: nowrap` — so without it a long title stops the
+  row shrinking and pushes its container past the viewport instead of
+  truncating. The demo proved that at 320/360/390px before release.
+
+  It is in **core**, unusually for a new surface, because `.ui-menu__item` now
+  composes it and a core component cannot depend on an opt-in leaf. It also
+  earns the roadmap's stronger argument for a core addition on two counts:
+  universal application chrome, and it *reduces duplicated core markup*. A unit
+  proof asserts the menu item does not restate what the row says, so the two
+  cannot drift back apart.
+
+### Changed
+
+- **`.ui-menu` no longer welds placement into the surface.** It used to declare
+  `position: absolute` plus a trigger-relative offset, so a menu opened at a
+  pointer — a canvas context menu, a long-press — could not use it at all, and
+  consumers re-declared the panel, border, radius and shadow to get a surface.
+  The dropdown placement is now `--dropdown` (unchanged behaviour, opted into)
+  and `--at-pointer` takes a menu out of flow for a host that computes its own
+  position.
+
+  **Migration:** add `ui-menu--dropdown` to an existing `ui-menu` inside a
+  `ui-menu-host`. Without it the surface renders in flow.
+
+### Fixed
+
+- **`data-density` claimed more than it does, and the guard could not tell.**
+  `docs/theming.md` said the preset applies "on any element". Measured: it
+  re-points the `--space-*` scale, so it reaches the ~40 components whose
+  padding is expressed in that scale and **none** of the rest — `ui-alert` and
+  `ui-menu__item` among them. The remaining paddings are tuned pairs like
+  `0.5rem 0.55rem` that a seven-step scale cannot express, so tokenising them
+  would change how they look at the default density; exactly one declaration in
+  the whole catalog mapped cleanly and was converted.
+
+  The docs now say which components respond and why the others cannot, and a
+  test pins the responding set. The previous guard checked that the preset
+  changed the token *family*, which is true and useless — it would have passed
+  with every component hardcoded. That is the third contract in three releases
+  whose gate validated the mechanism instead of the effect, after the 43.5px tap
+  floor and the shipped-docs list.
+
+### Notes
+
+- Bundle budget raised to 95,600 B / 16,400 B for `.ui-row` (+1,234 B raw /
+  +83 B gzip). The gzip cost is small because the new rules compress against the
+  menu rules they replaced.
+
 ## 0.8.1 — 2026-08-11
 
 A packaging fix, plus dependency hygiene. **No published CSS, token, class, or

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![default CSS](https://img.shields.io/badge/default%20CSS-~92kB%20%2F%20~16kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![default CSS](https://img.shields.io/badge/default%20CSS-~93kB%20%2F%20~16kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
@@ -81,12 +81,12 @@ Or drop it in with no build step, straight from a CDN (replace the version only
 when deliberately upgrading across a breaking pre-1.0 minor):
 
 ```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.9.0/dist/bronto.css">
 ```
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~92 kB raw / ~16 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
+**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~93 kB raw / ~16 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 669,
-    "groups": 183
+    "classes": 677,
+    "groups": 184
   },
   "groups": {
     "ui-accordion": {
@@ -830,7 +830,10 @@
     },
     "ui-menu": {
       "base": "ui-menu",
-      "modifiers": [],
+      "modifiers": [
+        "ui-menu--at-pointer",
+        "ui-menu--dropdown"
+      ],
       "parts": [
         "ui-menu__item",
         "ui-menu__label",
@@ -1074,6 +1077,18 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-row": {
+      "base": "ui-row",
+      "modifiers": [
+        "ui-row--ruled",
+        "ui-row--stacked"
+      ],
+      "parts": [
+        "ui-row__mark",
+        "ui-row__meta",
+        "ui-row__title"
+      ]
+    },
     "ui-screen-only": {
       "base": "ui-screen-only",
       "modifiers": [],
@@ -1924,6 +1939,8 @@
     "ui-mark--warning",
     "ui-matrix",
     "ui-menu",
+    "ui-menu--at-pointer",
+    "ui-menu--dropdown",
     "ui-menu-host",
     "ui-menu__item",
     "ui-menu__label",
@@ -2039,6 +2056,12 @@
     "ui-report__title",
     "ui-report__toc",
     "ui-reveal",
+    "ui-row",
+    "ui-row--ruled",
+    "ui-row--stacked",
+    "ui-row__mark",
+    "ui-row__meta",
+    "ui-row__title",
     "ui-screen-only",
     "ui-scroll-progress",
     "ui-scroll-reveal",

package/classes/index.d.ts

@@ -55,6 +55,12 @@ export declare const cls: {
   readonly linkArrow: 'ui-link--arrow';
   readonly linkCta: 'ui-link--cta';
   readonly keyValue: 'ui-key-value';
+  readonly row: 'ui-row';
+  readonly rowTitle: 'ui-row__title';
+  readonly rowMeta: 'ui-row__meta';
+  readonly rowMark: 'ui-row__mark';
+  readonly rowStacked: 'ui-row--stacked';
+  readonly rowRuled: 'ui-row--ruled';
   readonly emptyState: 'ui-empty-state';
   readonly emptyStateInvite: 'ui-empty-state--invite';
   readonly emptyStateGlyph: 'ui-empty-state__glyph';
@@ -164,6 +170,8 @@ export declare const cls: {
   readonly modalDrawer: 'ui-modal--drawer';
   readonly menuHost: 'ui-menu-host';
   readonly menu: 'ui-menu';
+  readonly menuDropdown: 'ui-menu--dropdown';
+  readonly menuAtPointer: 'ui-menu--at-pointer';
   readonly menuLabel: 'ui-menu__label';
   readonly menuItem: 'ui-menu__item';
   readonly menuSep: 'ui-menu__sep';

package/classes/index.js

@@ -59,6 +59,12 @@ export const cls = Object.freeze({
   linkArrow: 'ui-link--arrow',
   linkCta: 'ui-link--cta',
   keyValue: 'ui-key-value',
+  row: 'ui-row',
+  rowTitle: 'ui-row__title',
+  rowMeta: 'ui-row__meta',
+  rowMark: 'ui-row__mark',
+  rowStacked: 'ui-row--stacked',
+  rowRuled: 'ui-row--ruled',
   emptyState: 'ui-empty-state',
   emptyStateInvite: 'ui-empty-state--invite',
   emptyStateGlyph: 'ui-empty-state__glyph',
@@ -173,6 +179,8 @@ export const cls = Object.freeze({
   modalDrawer: 'ui-modal--drawer',
   menuHost: 'ui-menu-host',
   menu: 'ui-menu',
+  menuDropdown: 'ui-menu--dropdown',
+  menuAtPointer: 'ui-menu--at-pointer',
   menuLabel: 'ui-menu__label',
   menuItem: 'ui-menu__item',
   menuSep: 'ui-menu__sep',

package/css/core.css

@@ -18,6 +18,7 @@
 @import url('./site.css') layer(bronto);
 @import url('./content.css') layer(bronto);
 @import url('./primitives.css') layer(bronto);
+@import url('./row.css') layer(bronto);
 @import url('./forms.css') layer(bronto);
 @import url('./feedback.css') layer(bronto);
 @import url('./overlay.css') layer(bronto);

package/css/overlay.css

@@ -247,6 +247,12 @@ html:has(.ui-modal.is-open) {
   position: relative;
 }
 
+/* The SURFACE only. Placement is a separate decision, because a menu is not
+   always a dropdown: a canvas context menu opens at the pointer, a mobile one
+   arrives as a sheet. This rule used to weld `position: absolute` plus a
+   trigger-relative offset into the surface itself, so a consumer with a
+   pointer-positioned menu could not use it at all and re-declared the panel,
+   the border, the radius and the shadow to get one. */
 .ui-menu {
   background: var(--panel-strong);
   border: 1px solid var(--line-strong);
@@ -256,12 +262,25 @@ html:has(.ui-modal.is-open) {
   gap: 1px;
   min-inline-size: 11rem;
   padding: 0.3rem;
+}
+
+/* The dropdown placement this class always had: anchored under its trigger
+   inside a `.ui-menu-host`. Unchanged behaviour, now opted into. */
+.ui-menu--dropdown {
   position: absolute;
   inset-inline-end: 0;
   inset-block-start: calc(100% + 0.4rem);
   z-index: var(--z-overlay);
 }
 
+/* Opened at a point the host computes — a right-click, a long-press. The host
+   sets `left`/`top` (or `inset-inline-start`/`inset-block-start`); Bronto only
+   takes it out of flow and gives it the layer. */
+.ui-menu--at-pointer {
+  position: fixed;
+  z-index: var(--z-popover);
+}
+
 .ui-menu__label {
   color: var(--text-dim);
   font-family: var(--mono);
@@ -271,20 +290,15 @@ html:has(.ui-modal.is-open) {
   text-transform: uppercase;
 }
 
+/* Composes `.ui-row` (css/row.css) — a menu item IS a dense selectable row,
+   and keeping two copies of that shape is how they drift. What is menu-specific
+   stays here: the mono face, the slightly roomier padding a pointer target
+   wants, and the leading bullet below. `row.css` is in the core bundle, which
+   is what lets a core component compose it. */
 .ui-menu__item {
-  align-items: center;
-  background: transparent;
-  border: 0;
-  border-radius: var(--radius-sm);
-  color: var(--text-soft);
-  cursor: pointer;
-  display: flex;
   font-family: var(--mono);
   font-size: var(--text-sm);
-  gap: 0.5rem;
   padding: 0.5rem 0.55rem;
-  text-align: start;
-  inline-size: 100%;
 }
 
 .ui-menu__item::before {

package/css/row.css

@@ -0,0 +1,154 @@
+/* ==========================================================================
+   row — the dense selectable row. IN THE DEFAULT BUNDLE.
+
+   Every workbench grows a list of these: a search result, a file in an
+   explorer, an outline entry, a backlink, an inbox item, a commit. They are not
+   table rows — there is no column contract and no header — and they are not
+   menu items, because they persist rather than dismissing. But they are all the
+   same object: a full-width clickable line with a leading mark, a title that
+   gives up space first, and trailing metadata that does not.
+
+   Bronto already had this shape and it was imprisoned. `.ui-menu__item` is
+   exactly it, minus the persistence — so a consumer building an explorer either
+   claimed to be a menu or wrote the row again. One downstream workbench had
+   SIXTY-THREE families of it, about 1,200 lines, each re-deciding the selected
+   state, the hover, the ellipsis and the coarse-pointer floor.
+
+   `.ui-menu__item` now composes this, so the two cannot drift.
+
+   BOUNDARY. The host owns what a row means, what selects it, and what its
+   columns are. Bronto owns the line: its rhythm, its states, and the fact that
+   the title is the part that truncates. Rows that carry a severity should reach
+   for `.ui-severity-row` in `state.css` instead — that one adds the tone gutter.
+
+   In core rather than opt-in, unusually for a new surface, because
+   `.ui-menu__item` composes it and a core component cannot depend on a leaf.
+   ========================================================================== */
+
+.ui-row {
+  align-items: center;
+  background: transparent;
+  border: 0;
+  border-radius: var(--radius-sm);
+  color: var(--text-soft);
+  cursor: pointer;
+  display: flex;
+  font: inherit;
+  gap: 0.5rem;
+
+  /* The companion to `__title`'s ellipsis, and the demo proved it is not
+     optional: a row is usually a flex or grid ITEM, whose automatic minimum
+     size is its min-content width — and `__title` is `white-space: nowrap`, so
+     that min-content is the WHOLE title. Without this a long title stops the
+     row shrinking and pushes its container past the viewport instead of
+     truncating. Caught at 320/360/390px by the overflow specs. */
+  min-inline-size: 0;
+  padding: 0.4rem 0.5rem;
+  text-align: start;
+  inline-size: 100%;
+}
+
+/* A row is usually a <button> or an <a>; when it is neither, it still needs to
+   look inert rather than pressable. */
+.ui-row:not(button, a, [role='button'], [role='option'], [tabindex]) {
+  cursor: default;
+}
+
+/* The title gives up space FIRST — it is the only part of a row that can be
+   truncated without losing a fact. Everything else keeps its size. */
+.ui-row__title {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Trailing facts: a count, an age, a path fragment. Never the thing that
+   shrinks, because a half-rendered number is worse than no number. */
+.ui-row__meta {
+  color: var(--text-dim);
+  flex: none;
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+}
+
+/* A leading mark — an icon, a glyph, a status dot. Sized by the host. */
+.ui-row__mark {
+  display: inline-flex;
+  flex: none;
+}
+
+/* A row that wraps to a second line: a result with a snippet under its title.
+   The parts stack rather than sharing the baseline. */
+.ui-row--stacked {
+  align-items: stretch;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+
+.ui-row--stacked .ui-row__title {
+  flex: none;
+}
+
+/* Rows in a list read as one object when they share a rule; rows in a menu
+   float. `--ruled` is the list form. */
+.ui-row--ruled {
+  border-block-end: 1px solid var(--line);
+  border-radius: 0;
+}
+
+/* --- States, and WHICH attribute is yours to use.
+
+   `aria-selected` is only valid on a row that has a role which accepts it —
+   `option` inside a `listbox`, or `row` / `tab` / `gridcell` / `treeitem`. On a
+   bare `<button>` it is invalid ARIA, and axe rates that CRITICAL. This project
+   shipped exactly that mistake in its own demo and the a11y gate caught it.
+
+   So: `aria-current` for a row that is merely the current one (the common
+   case), `aria-selected` only when the row genuinely carries an option/row
+   role, and `.is-selected` when neither applies. All three paint the same. --- */
+
+.ui-row[aria-selected='true'],
+.ui-row[aria-current]:not([aria-current='false']),
+.ui-row.is-selected {
+  background: var(--panel-soft);
+  color: var(--text);
+}
+
+@media (hover: hover) {
+  .ui-row:is(button, a, [role='button'], [role='option'], [tabindex]):hover {
+    background: var(--bg-accent);
+    color: var(--text);
+  }
+}
+
+.ui-row:focus-visible {
+  background: var(--bg-accent);
+  color: var(--text);
+  outline: 2px solid var(--focus-ring);
+  outline-offset: -2px;
+}
+
+/* Touch: a row is a primary target in a list, so it floats to the full
+   tap-target rather than the 24px minimum. */
+@media (pointer: coarse) {
+  .ui-row {
+    min-block-size: var(--tap-target);
+  }
+}
+
+/* Forced colours strip the tinted hover/selected background, which would leave
+   the current row indistinguishable from its siblings. Re-assert a system
+   Highlight, the same way the menu and combobox rows do. */
+@media (forced-colors: active) {
+  .ui-row[aria-selected='true'],
+  .ui-row[aria-current]:not([aria-current='false']),
+  .ui-row.is-selected,
+  .ui-row:hover,
+  .ui-row:focus-visible {
+    forced-color-adjust: none;
+    background: Highlight;
+    color: HighlightText;
+  }
+}

package/css/workbench.css

@@ -53,7 +53,7 @@
 
 .ui-toolstrip--compact {
   gap: var(--space-2xs);
-  padding: 0.25rem;
+  padding: var(--space-2xs);
 }
 
 /* Pane-scale — a control bar belonging to ONE pane rather than to the app. The