@adia-ai/web-components 0.5.19 → 0.5.21

package/CHANGELOG.md

@@ -11,6 +11,23 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.21] - 2026-05-18
+
+_Lockstep ride-along (no source change in this package; companion to web-components v0.5.21 — see root CHANGELOG)._
+
+## [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/index.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

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/stat/stat.a2ui.json

@@ -49,7 +49,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
-    "composes": [],
+    "composes": [
+      "icon-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/stat/stat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `<stat-ui>` — Metric/KPI display — value + label + optional change indicator and trend.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stat
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStat extends UIElement {
+  /** Change indicator text (e.g. '+12%', '-3%') */
+  change: string;
+  /** Icon name displayed in the icon slot */
+  icon: string;
+  /** Eyebrow label describing the metric */
+  label: string;
+  /** Trend direction or narrative subtitle. Canonical values color the change badge (up=success, down=danger, neutral/flat=muted); any other string renders as caption-style text under the primary value. */
+  trend: string;
+  /** The primary metric value to display */
+  value: string;
+}

package/components/stat/stat.yaml

@@ -3,6 +3,8 @@
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIStat
 tag: stat-ui
+composes:
+  - icon-ui
 component: Stat
 category: display
 version: 1

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,48 +1,58 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "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",
   "exports": {
     ".": {
       "types": "./index.d.ts",
+      "import": "./index.js",
       "default": "./index.js"
     },
     "./css": "./index.css",
     "./core": {
       "types": "./core/index.d.ts",
+      "import": "./core/index.js",
       "default": "./core/index.js"
     },
     "./core/*": {
       "types": "./core/*.d.ts",
+      "import": "./core/*.js",
       "default": "./core/*.js"
     },
-    "./components": "./components/index.js",
+    "./components": {
+      "types": "./components/index.d.ts",
+      "import": "./components/index.js",
+      "default": "./components/index.js"
+    },
     "./components/*": {
       "types": "./components/*/*.d.ts",
+      "import": "./components/*/*.js",
       "default": "./components/*/*.js"
     },
-    "./components/stat": {
-      "types": "./components/stat/stat-ui.d.ts",
-      "default": "./components/stat/stat-ui.js"
-    },
-    "./components/stat/stat-ui.js": {
-      "types": "./components/stat/stat-ui.d.ts",
-      "default": "./components/stat/stat-ui.js"
-    },
     "./components/*/class": {
       "types": "./components/*/*.d.ts",
+      "import": "./components/*/class.js",
       "default": "./components/*/class.js"
     },
     "./components/*.css": "./components/*/*.css",
     "./components/*/*.css": "./components/*/*.css",
     "./components/*/css/*.css": "./components/*/css/*.css",
     "./styles/*": "./styles/*",
-    "./traits": "./traits/index.js",
-    "./traits/*": "./traits/*.js",
+    "./traits": {
+      "types": "./traits.d.ts",
+      "import": "./traits/index.js",
+      "default": "./traits/index.js"
+    },
+    "./traits/*": {
+      "types": "./traits.d.ts",
+      "import": "./traits/*.js",
+      "default": "./traits/*.js"
+    },
     "./color": {
       "types": "./color/index.d.ts",
+      "import": "./color/index.js",
       "default": "./color/index.js"
     },
     "./package.json": "./package.json"

package/styles/components.css

@@ -77,7 +77,7 @@
 @import "../components/otp-input/otp-input.css";
 @import "../components/image/image.css";
 @import "../components/search/search.css";
-@import "../components/stat/stat-ui.css";
+@import "../components/stat/stat.css";
 @import "../components/progress-row/progress-row.css";
 @import "../components/action-list/action-list.css";
 @import "../components/empty-state/empty-state.css";

package/components/stat/stat-ui.d.ts

@@ -1,38 +0,0 @@
-/**
- * `<stat-ui>` — Metric/KPI display. Value + label + optional change indicator and trend.
- *
- * @see https://ui-kit.exe.xyz/site/components/stat
- *
- * HAND-AUTHORED (v0.5.12 §253 FB-30 close-out). The codegen pipeline's
- * `isCssOnly()` check at `scripts/build/dts-codegen.mjs:186-194` looks for
- * `${dirname}.js` — but stat ships `stat-ui.js` (irregular filename; the
- * v0.6.0 §303 rename will normalize to `stat.js`). Pre-§303 the codegen
- * false-positives `isCssOnly` and skips this directory entirely. Hand-author
- * this file matching `stat.yaml` props until §303 lands.
- *
- * Filename mirrors the JS file (`stat-ui.js` → `stat-ui.d.ts`) so TypeScript
- * resolves the side-effect import `import '@adia-ai/web-components/components/stat/stat-ui.js'`
- * to a typed module. Post-§303, both files rename to `stat.{js,d.ts}` and
- * codegen takes over.
- */
-
-import { UIElement } from '../../core/element.js';
-
-export class UIStat extends UIElement {
-  /** Eyebrow label describing the metric. */
-  label: string;
-  /** Primary metric value (large display number / string). */
-  value: string;
-  /** Change indicator text (e.g. "+12%", "-3%"). Slotted as a badge next to value. */
-  change: string;
-  /**
-   * Trend direction or narrative subtitle. Canonical values color the change
-   * badge: `up` = success (green), `down` = danger (red), `flat`/`neutral` =
-   * muted. Any other string renders as caption-style text under the primary
-   * value (not enum-validated; yaml documents the canonical set but the type
-   * stays `string` for narrative subtitles).
-   */
-  trend: string;
-  /** Icon name displayed in the icon slot (Phosphor icon registry). */
-  icon: string;
-}