@adia-ai/web-components 0.5.19 → 0.5.20

package/CHANGELOG.md

@@ -11,6 +11,19 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.20] - 2026-05-18
+
+### Added — §353 (v0.5.20) — `<pane-ui>` + `<tabs-ui>` bar-rule alignment
+
+Both primitives' header/tablist bars converted from `border-bottom` to `box-shadow: inset 0 -1px 0`. Header height fixed at `--pane-bar-height` / `--tabs-button-height` (was `min-height` + the border added a pixel). Pane header gains `box-sizing: border-box` + `justify-content: flex-start`. Collapsed pane header drops the box-shadow. Visually identical to consumers; measurable change in computed height (1px shorter than border-bearing version). Brings these two primitives in line with the rest of the catalog using box-shadow for bar rules.
+
+### Docs
+- §351 (FB-53 #2) — USAGE.md `§349 Event handling inside reactive lists` section gains a `CSS child-combinator caveat` paragraph. Calls out that `display:contents` wrapper-spans ARE in the DOM tree, so the CSS child combinator (`>`) walks past them: `.parent > .my-item` will NOT match items inside `repeat()` because the wrapper-span sits between. Recommends descendant combinator (single space) instead. Same caveat extended to `:nth-child` / positional pseudo-classes. Closes the post-Lane-AA1 migration docs gap surfaced by Tokens Studio.
+- §352 (FB-53 #3) — USAGE.md `§345 .map() vs repeat() for reactive lists` section gains a `Sizing heuristic` paragraph. Two cases where `repeat()` pays for itself: (a) ≥20 items re-rendering on every signal change, OR (b) any-size list whose items host custom elements with internal state (chrome slots, focus, scroll). Discourages reflexive `.map()` → `repeat()` migration when neither threshold applies.
+
+### Fixed
+- §-headers (v0.5.20) — USAGE.md headers for `§345` and `§349` renumbered from `§-TBD (v0.5.19)` to `§345 (v0.5.19)` / `§349 (v0.5.19)` — peer-agent's v0.5.19 pre-cut docs sweep renumbered the CHANGELOG but missed the USAGE.md section headers. Sync restored so the section anchors match between CHANGELOG and USAGE.md.
+
 ## [0.5.19] - 2026-05-17
 
 ### Added

package/USAGE.md

@@ -1086,7 +1086,7 @@ Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective
 - HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
 - Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
 
-### §-TBD (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
+### §345 (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
 
 Use **`repeat(items, keyFn, tplFn)`** for any list whose items are signal-driven and should preserve identity across re-renders. Plain `.map()` returns an `Array` of template results, which the template engine materializes via `container.replaceChildren()` on every parent update — correct, but per-item DOM is re-created from scratch.
 
@@ -1118,7 +1118,9 @@ html`
 
 **Key selection:** pick a stable consumer-supplied identifier (database id, slot.key, etc.), NOT array index. Array indices are unstable under insert/remove and defeat the keyed-reuse contract.
 
-### §-TBD (v0.5.19) — Event handling inside reactive lists (FB-49)
+**Sizing heuristic (FB-53 #3):** `.map()` is fine for static lists of ≤10 items that don't re-render or only re-render at navigation boundaries. `repeat()` adds per-render bookkeeping (Map lookups, key comparison, DOM reuse) that pays for itself in two cases: (a) lists of ≥20 items that re-render on every signal change (e.g. a palette grid with 66 swatches updating on every slider drag), or (b) any-size list whose items host custom elements with internal state (chrome slots, focus position, scroll offset). Don't migrate every `.map()` reflexively — migrate when one of those two thresholds applies.
+
+### §349 (v0.5.19) — Event handling inside reactive lists (FB-49)
 
 Custom-element children rendered inside `repeat()` (or as an `${array}` interpolation) are each wrapped in a `<span style="display:contents">` by the template engine. These wrapper spans generate no boxes (`display:contents`) and cannot be click targets, but they ARE in the DOM tree.
 
@@ -1154,6 +1156,32 @@ host.addEventListener('click', (e) => {
 
 **Don't reach for `composedPath()` reflexively** — it rebuilds the full path on every call and is slower than `closest()`. Default to `closest()` for direct bubble-phase handlers; use `composedPath()` only when one of the three cases above applies.
 
+**CSS child-combinator caveat (FB-53 #2):** `display:contents` wrapper-spans ARE in the DOM tree even though they generate no boxes. The CSS child combinator (`>`) walks the DOM tree (not the box tree), so consumer rules of the shape `.parent > .my-item` **will not match** items inside a `repeat()` because the wrapper-span sits between `.parent` and the items:
+
+```html
+<!-- Actual DOM produced by repeat(): -->
+<div class="parent">
+  <span style="display:contents">      <!-- ← repeat() per-item wrapper -->
+    <my-item class="my-item">…</my-item>
+  </span>
+</div>
+```
+
+Use the descendant combinator (a single space) instead, which traverses any depth:
+
+```css
+/* ❌ Won't match — wrapper-span sits between .parent and .my-item */
+.parent > .my-item { … }
+
+/* ✅ Descendant combinator pierces through the wrapper-spans */
+.parent .my-item { … }
+
+/* ✅ Or use :scope/has() if you need precision: */
+.parent > :is(.my-item, span > .my-item) { … }
+```
+
+Same caveat applies to `:nth-child()` / `:nth-of-type()` / `:first-child` / `:last-child` against the parent — those count actual children (the wrapper-spans), not the items inside. If you need nth-item styling, key it via a data attribute on the item itself rather than relying on positional pseudo-classes against the wrapper layer.
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):

package/components/pane/pane.css

@@ -82,17 +82,19 @@
 
   /* ── Pane header ── */
   > header {
+    box-sizing: border-box;
     display: flex;
     align-items: center;
+    justify-content: flex-start;
     gap: var(--pane-gap-sm);
-    min-height: var(--pane-bar-height);
-    padding: var(--pane-header-py) var(--pane-header-px);
+    height: var(--pane-bar-height);
+    padding: 0 var(--pane-header-px);
     font-size: var(--pane-header-size);
     font-weight: var(--pane-header-weight);
     color: var(--pane-header-fg);
     cursor: pointer;
     user-select: none;
-    border-bottom: 1px solid var(--pane-border);
+    box-shadow: inset 0 -1px 0 var(--pane-border);
     transition: background var(--pane-duration) var(--pane-easing);
   }
 
@@ -178,7 +180,7 @@
   }
 
   :scope[collapsed] > header {
-    border-bottom: none;
+    box-shadow: none;
   }
 
   /* ── Resize handle ──

package/components/tabs/tabs.css

@@ -61,15 +61,16 @@
     box-sizing: border-box;
     display: flex;
     gap: var(--tabs-gap);
-    border-bottom: 1px solid var(--tabs-border);
+    height: var(--tabs-button-height);
+    box-shadow: inset 0 -1px 0 var(--tabs-border);
     position: relative;
   }
 
   :scope[orientation="vertical"] > [slot="strip"] {
     flex-direction: column;
     align-items: stretch;
-    border-bottom: none;
-    border-inline-start: 1px solid var(--tabs-border);
+    height: auto;
+    box-shadow: inset 1px 0 0 var(--tabs-border);
     flex-shrink: 0;
     min-width: var(--tabs-vertical-strip-min-width);
   }
@@ -77,7 +78,7 @@
   /* ── Sliding indicator ── */
   [slot="indicator"] {
     position: absolute;
-    bottom: -1px;
+    bottom: 0;
     left: 0;
     height: var(--tabs-indicator-height);
     background: var(--tabs-indicator-color);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.19",
+  "version": "0.5.20",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",