@adia-ai/web-components 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.2] — 2026-06-01
+
+### Fixed
+
+- **template engine — ARIA-transparent `display:contents` wrapper spans (FB-94)** — the interpolation wrapper span the engine emits for `${…}` parts (`.map()` / conditional / `repeat()`) now carries `role="presentation"`. `display:contents` removes the span's box from layout but it still generated a generic accessibility node, which broke `aria-required-children` / `aria-required-parent` when the span sat between a role-bearing parent and role-bearing children rendered via interpolation — e.g. a `.map()`-rendered `<tree-ui>` (the mainstream consumer case) tripped axe `aria-required-children` even after the FB-91 static-markup fix landed. `role="presentation"` promotes the children to the real parent in the a11y tree. Fixed at all three wrapper sites (`wrap()` + array branch + keyed `repeat()`); +3 regression tests assert the wrappers carry `role="presentation"`. This is the consumer-preferred + peer-recommended central fix and is structurally sound (the spurious generic node between `tree`→`treeitem` is removed). **Honest verification note:** `aria-required-children` could not be made to fire on any in-repo tree (shallow *or* deeply-nested, axe-core, `:5300`) — it triggers only on color-app's exact published-package `dts-token-tree` — so local axe reads 0 both before and after; the firing→cleared transition is **pending the consumer's confirmation** on their next `@adia-ai/web-components` upgrade. (Tokens Studio / color-app FB-94)
+- **`<menu-item-ui>` no longer an orphan `menuitem` when the menu is closed (FB-95)** — `UIMenuItem.connected()` set `role="menuitem"` unconditionally, but a closed `<menu-ui>` moves its items back into its own light DOM (no `role="menu"` ancestor), so every closed declarative menu tripped axe `aria-required-parent`. The role (+ `tabindex="-1"`) is now applied only when the item has a `role="menu"`/`menubar` ancestor; the open popover adopts items via `appendChild` (which re-fires `connected()`), so the role re-applies on open and drops on close. **Verified with axe-core**: closed menu → **0** `aria-required-parent` violations (was 3); open menu → items are `role="menuitem"`, 0 violations. (Tokens Studio / color-app FB-95)
+
+### Changed — styles + build
+
+- **Tokens cascade-layer completed (`styles/`)** — `typography.css` (`type/scale.css`) + `roles.css` `:root` role-token blocks moved into `@layer(tokens)`, finishing the `@layer` migration's tokens cut (the type-scale + role tokens had stayed unlayered). Behavior-neutral — the `[variant]`/state rules keep their existing precedence; only the base `:root` token declarations join the layer.
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) for the template-engine + tokens-layer changes.
+
+## [0.7.1] — 2026-05-31
+
+### Fixed
+
+- **`<input-ui>` leading/trailing affordance vertical centering** — the affordance slots used `align-self: stretch`, which top-aligned any child carrying a definite `height` (a `<kbd-ui slot="trailing">` ⌘K hint sat ~4px high in a 30px chrome) and also overrode a `<button-ui>` child's own `--button-height`. Changed to `align-self: center` so each affordance keeps its token height and sits on the field's vertical center. Affects every intrinsic-height affordance (kbd / icon / badge); button affordances are unchanged (they already filled the chrome). (bug-60)
+- **`<tree-ui>` nested items now satisfy the WAI-ARIA tree pattern** — the `tree-item-ui` host is now `role="group"` and its focusable `[slot="row"]` is the `role="treeitem"` (with `aria-expanded`/`aria-selected` moved onto the row). Previously the host was the `treeitem` and nested items had no `group`/`tree` required parent, tripping axe-core `aria-required-parent` (critical) on every nested node. Done without re-homing children, so it holds for static markup AND template-engine `.map()` trees; no CSS/yaml change. Validated with real axe-core (0 violations). (FEEDBACK-91)
+- **`<menu-ui>` renders dynamically-generated items** — `#show()` collected items with a direct-child `:scope >` query, which missed `menu-item-ui` rendered via `.map()`/`repeat()` (the template engine nests them in `display:contents` wrapper spans) → the popover opened empty. Now uses a descendant query (skipping items already relocated into the popover), matching `#hide()` and resolving the show/hide asymmetry. Static children unaffected. (FEEDBACK-92)
+- **`<input-ui>` reactive `prefix=`/`suffix=` bindings resolve** — a reactive attribute binding (`suffix="${expr}"`) leaked the literal template placeholder `{{p:N}}` as affix text, because the shell was snapshotted once in `connected()` before the binding resolved and never re-synced. `render()` now re-resolves the prefix/suffix slots each cycle (handling text↔icon affixes), mirroring the slider-ui FB-45 fix. Literal and `.property` affixes are unchanged. (FEEDBACK-93)
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) to carry the input/tree/menu fixes above.
+
+### Changed — demos
+
+- **`<field-ui>` inline-layout demo** — the "Results: 12" count moved from a field-level `<span slot="trailing">` (beside the input) into the input's `suffix` prop, so it renders **in-chrome, left of the Clear button** (DOM order value → `suffix` → `trailing`). The demo now shows all three affordances inside the input chrome and the note explains the suffix-vs-trailing split. (bug-60)
+
 ## [0.7.0] — 2026-05-31
 
 ### Added — component features from the docs-QA pass

package/components/input/input.class.js

@@ -327,6 +327,41 @@ export class UIInput extends UIFormElement {
     }
   }
 
+  /**
+   * FEEDBACK-93 — re-resolve the prefix/suffix slots from the live property.
+   *
+   * `connected()` builds the shell ONCE (`this.innerHTML = #shellHTML()`),
+   * reading `this.prefix` / `this.suffix` at that moment. For a reactive
+   * attribute binding (`suffix="${expr}"`) the framework writes the literal
+   * placeholder marker (`{{p:N}}`) into the attribute first and resolves it on
+   * a later reactive tick — so the marker gets baked into the slot as text and,
+   * since `render()` never rebuilt the affixes, it stuck. This mirrors the
+   * slider-ui FEEDBACK-45 fix, but input affixes can be icon names
+   * (`renderAffix` → `<icon-ui>`), so we handle text↔icon transitions here.
+   * The static-deploy icon-registry race is still owned by `#promoteAffixes()`.
+   */
+  #syncAffixSlots() {
+    for (const which of ['prefix', 'suffix']) {
+      const el = this.querySelector(`:scope > [slot="field"] > [slot="${which}"]`);
+      if (!el) continue;
+      const value = this[which] || '';
+      const icon = el.querySelector(':scope > icon-ui');
+      if (value && isIconName(value)) {
+        if (icon) {
+          if (icon.getAttribute('name') !== value) icon.setAttribute('name', value);
+        } else {
+          el.replaceChildren();
+          const created = document.createElement('icon-ui');
+          created.setAttribute('name', value);
+          el.appendChild(created);
+        }
+      } else {
+        if (icon) el.replaceChildren();
+        if (el.textContent !== value) el.textContent = value;
+      }
+    }
+  }
+
   render() {
     if (!this.#textEl) return;
 
@@ -360,6 +395,9 @@ export class UIInput extends UIFormElement {
 
     if (this.#labelEl) this.#labelEl.textContent = this.label || '';
 
+    // Re-resolve prefix/suffix from the live property each render (FEEDBACK-93).
+    this.#syncAffixSlots();
+
     if (this.label) {
       this.removeAttribute('aria-label');
     } else if (this.placeholder) {

package/components/input/input.css

@@ -304,10 +304,14 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
   [slot="field"] > [slot="leading"],
   [slot="field"] > [slot="trailing"] {
     flex-shrink: 0;
-    /* Sized to chrome height per yaml contract. The button-ui or icon-ui
-       child receives the sizing tokens; we just constrain the slot box
-       and align it to the field's baseline. */
-    align-self: stretch;
+    /* Vertically CENTER the affordance in the chrome — do not `stretch`.
+       Stretch forces the slot box to the full chrome height; for a button-ui
+       child that overrode its own `--button-height` (chrome − 4px), and for a
+       fixed-height affordance like <kbd-ui> (definite `height`) stretch can't
+       grow the box so it pins to flex-start (top) instead — the ⌘K hint sat
+       ~4px high (bug-60). `center` lets each child keep its own token height
+       and sit on the field's vertical center. */
+    align-self: center;
     display: inline-flex;
     align-items: center;
     /* Inline padding moves from [slot="text"] (handled by the field's px)

package/components/input/input.test.js

@@ -15,6 +15,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import '../../core/element.js';
 import './input.js';
+import { html, stamp } from '../../core/template.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const INPUT_CSS = readFileSync(resolve(__dirname, 'input.css'), 'utf8');
@@ -260,3 +261,59 @@ describe('input-ui — CSS source contract: placeholder pseudo is out of flow',
     );
   });
 });
+
+describe('input-ui — FEEDBACK-93 reactive prefix/suffix re-sync', () => {
+  const settle = () => new Promise((r) => setTimeout(r, 30));
+
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  function suffixOf(el) { return el.querySelector(':scope > [slot="field"] > [slot="suffix"]'); }
+  function prefixOf(el) { return el.querySelector(':scope > [slot="field"] > [slot="prefix"]'); }
+
+  it('resolves a reactive suffix binding instead of leaking the {{p:N}} marker (the bug)', async () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    // Interpolated attribute → the engine writes {{p:0}} into `suffix` before
+    // connected() reads it, then resolves on the update() tick. Pre-fix the
+    // baked marker stuck; post-fix render() re-resolves it.
+    stamp(html`<input-ui type="number" suffix="${'px'}" value="2"></input-ui>`, container);
+    await settle();
+
+    const el = container.querySelector('input-ui');
+    const suffix = suffixOf(el);
+    expect(suffix).not.toBeNull();
+    expect(suffix.textContent).toBe('px');
+    expect(suffix.textContent).not.toMatch(/\{\{p:/);
+  });
+
+  it('resolves a reactive prefix binding', async () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    stamp(html`<input-ui prefix="${'$'}" value="9.99"></input-ui>`, container);
+    await settle();
+
+    const el = container.querySelector('input-ui');
+    expect(prefixOf(el).textContent).toBe('$');
+    expect(prefixOf(el).textContent).not.toMatch(/\{\{p:/);
+  });
+
+  it('re-resolves when the bound value later changes', async () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    stamp(html`<input-ui type="number" suffix="${'px'}" value="2"></input-ui>`, container);
+    await settle();
+    const el = container.querySelector('input-ui');
+    expect(suffixOf(el).textContent).toBe('px');
+
+    // Simulate the binding resolving to a new value on a later reactive tick.
+    el.setAttribute('suffix', 'rem');
+    await settle();
+    expect(suffixOf(el).textContent).toBe('rem');
+  });
+
+  it('literal suffix still renders (no regression)', async () => {
+    const el = mount('<input-ui suffix="%"></input-ui>');
+    await settle();
+    expect(suffixOf(el).textContent).toBe('%');
+  });
+});

package/components/menu/menu.class.js

@@ -85,9 +85,18 @@ export class UIMenu extends UIElement {
     if (!trigger) return;
     const pop = this.#ensurePopover();
 
-    // Move menu items into popover (so they render in the top layer).
-    const items = this.querySelectorAll(':scope > menu-item-ui, :scope > menu-divider-ui');
-    for (const item of items) pop.appendChild(item);
+    // Move menu items into the popover (so they render in the top layer).
+    // Use a DESCENDANT query — not `:scope >` — so items rendered via the
+    // template engine's `.map()` / `repeat()` are collected too: those wrap
+    // every interpolated child in a `display:contents` <span> (core/template.js
+    // wrap()), making the items grandchildren that a direct-child query skips
+    // → an empty popover (FEEDBACK-92). Skip anything already relocated into
+    // the popover so a re-entrant #show() (reactive re-render while open)
+    // doesn't reorder items. Mirrors the descendant query #hide() already uses.
+    const items = this.querySelectorAll('menu-item-ui, menu-divider-ui');
+    for (const item of items) {
+      if (!pop.contains(item)) pop.appendChild(item);
+    }
 
     if (!pop.matches(':popover-open')) pop.showPopover?.();
 
@@ -257,8 +266,20 @@ export class UIMenuItem extends UIElement {
   static template = () => null;
 
   connected() {
-    this.setAttribute('role', 'menuitem');
-    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '-1');
+    // role="menuitem" ONLY when actually inside a menu container. A menu-ui
+    // closes by moving its items back into its own light DOM (see #hide()),
+    // where there is no role="menu"/menubar ancestor — a bare role="menuitem"
+    // there trips axe `aria-required-parent` on every closed menu (FB-95). The
+    // open popover (role="menu") adopts items via appendChild, which re-fires
+    // connected(), so the role re-applies when the menu opens and is dropped
+    // again on close.
+    if (this.closest('[role="menu"], [role="menubar"]')) {
+      this.setAttribute('role', 'menuitem');
+      if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '-1');
+    } else {
+      this.removeAttribute('role');
+      this.removeAttribute('tabindex');
+    }
     this.#stamp();
     this.#syncAria();
   }

package/components/menu/menu.test.js

@@ -0,0 +1,130 @@
+/**
+ * <menu-ui> behavioral tests.
+ *
+ * FEEDBACK-92 (2026-05-31): `#show()` collected items with a direct-child
+ * `:scope >` query, so items rendered through the template engine's
+ * `.map()` / `repeat()` (each wrapped in a `display:contents` <span>) were
+ * skipped → the popover opened empty. The fix uses a descendant query
+ * (mirroring `#hide()`). These tests pin the dynamic + static paths.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { html, stamp, repeat } from '../../core/template.js';
+
+beforeAll(async () => {
+  await import('../../core/element.js');
+  await import('./menu.js');
+  await import('../button/button.js');
+});
+
+const settle = () => new Promise((r) => setTimeout(r, 30));
+
+describe('<menu-ui> collects dynamically-rendered items (FEEDBACK-92)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+  afterEach(() => host.remove());
+
+  function popItems(menu) {
+    const pop = menu.querySelector('[data-menu-popover]');
+    return pop ? pop.querySelectorAll('menu-item-ui') : [];
+  }
+
+  it('populates the popover from `.map()`-rendered items (the bug)', async () => {
+    const ITEMS = [{ id: 'a', text: 'Alpha' }, { id: 'b', text: 'Beta' }];
+    // Render the menu (closed) the documented way — items via `.map()`. The
+    // consumer opens it later via interaction, after the template has rendered.
+    stamp(html`
+      <menu-ui>
+        <button-ui slot="trigger" text="Open"></button-ui>
+        ${ITEMS.map((i) => html`<menu-item-ui .text=${i.text} .value=${i.id}></menu-item-ui>`)}
+      </menu-ui>
+    `, host);
+    await settle();
+
+    const menu = host.querySelector('menu-ui');
+    // The exact bug condition: items exist under the host but are NOT direct
+    // children — the template engine nested them inside display:contents spans,
+    // which the old `:scope >` query in #show() could not see.
+    expect(menu.querySelectorAll('menu-item-ui').length).toBe(2);
+    expect(menu.querySelector(':scope > menu-item-ui')).toBeNull();
+
+    menu.open = true; // user opens the menu post-render
+    await settle();
+
+    const items = popItems(menu);
+    expect(items.length).toBe(2);
+    expect([...items].map((el) => el.value)).toEqual(['a', 'b']);
+  });
+
+  it('populates the popover from `repeat()`-rendered items', async () => {
+    const ITEMS = [{ id: 'x', text: 'Ex' }, { id: 'y', text: 'Why' }, { id: 'z', text: 'Zee' }];
+    stamp(html`
+      <menu-ui>
+        <button-ui slot="trigger" text="Open"></button-ui>
+        ${repeat(ITEMS, (i) => i.id, (i) => html`<menu-item-ui .text=${i.text} .value=${i.id}></menu-item-ui>`)}
+      </menu-ui>
+    `, host);
+    await settle();
+
+    const menu = host.querySelector('menu-ui');
+    expect(menu.querySelector(':scope > menu-item-ui')).toBeNull(); // behind wrappers
+    menu.open = true;
+    await settle();
+    expect(popItems(menu).length).toBe(3);
+  });
+
+  it('still populates from static literal children (no regression)', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="Edit" value="edit"></menu-item-ui>
+      <menu-divider-ui></menu-divider-ui>
+      <menu-item-ui text="Delete" value="delete"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+
+    expect(popItems(menu).length).toBe(2);
+    const pop = menu.querySelector('[data-menu-popover]');
+    expect(pop.querySelectorAll('menu-divider-ui').length).toBe(1);
+  });
+
+  it('does not absorb the trigger into the popover', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="Edit" value="edit"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+
+    const pop = menu.querySelector('[data-menu-popover]');
+    expect(pop.querySelector('[slot="trigger"]')).toBeNull();
+    expect(menu.querySelector(':scope > [slot="trigger"]')).not.toBeNull();
+  });
+
+  it('does not reorder items on a re-entrant #show() (open → re-render → still open)', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="One" value="1"></menu-item-ui>
+      <menu-item-ui text="Two" value="2"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+    // Force another render() pass while still open (re-invokes #show()).
+    menu.placement = 'top-start';
+    await settle();
+
+    const pop = menu.querySelector('[data-menu-popover]');
+    const order = [...pop.querySelectorAll('menu-item-ui')].map((el) => el.value);
+    expect(order).toEqual(['1', '2']);
+  });
+});

package/components/tree/tree.class.js

@@ -281,11 +281,28 @@ export class UITreeItem extends UIElement {
   }
 
   connected() {
-    this.setAttribute('role', 'treeitem');
+    // The host is the structural GROUP container; the focusable [slot="row"]
+    // is the treeitem (FEEDBACK-91). The WAI-ARIA tree pattern requires every
+    // treeitem to be contained by a `group` or `tree`. Roling the host as
+    // `group` — rather than wrapping nested children in a new element — keeps
+    // the light-DOM structure intact, so it works for BOTH static markup AND
+    // template-engine `.map()` children (whose display:contents wrappers must
+    // not be re-homed) and sidesteps the parent-before-child upgrade race.
+    // axe-core: `tree` accepts `group` as a required child, `group` has no
+    // required parent, and the row's required `group` parent is the host.
+    this.setAttribute('role', 'group');
 
     if (!this.querySelector(':scope > [slot="row"]')) {
       this.#stamp();
     }
+
+    // Mark the row as the treeitem (whether we stamped it or the consumer
+    // supplied a declarative [slot="row"]) and ensure it stays focusable.
+    const row = this.querySelector(':scope > [slot="row"]');
+    if (row) {
+      row.setAttribute('role', 'treeitem');
+      if (!row.hasAttribute('tabindex')) row.setAttribute('tabindex', '0');
+    }
   }
 
   #stamp() {
@@ -350,12 +367,15 @@ export class UITreeItem extends UIElement {
     // Update depth-based indent
     row.style.paddingInlineStart = `${this.depth * 16 + 4}px`;
 
-    // Update aria
+    // Update aria — expanded/selected belong on the treeitem (the row), not
+    // the host group (FEEDBACK-91).
     if (this.hasChildren) {
-      this.setAttribute('aria-expanded', String(this.open));
+      row.setAttribute('aria-expanded', String(this.open));
     } else {
-      this.removeAttribute('aria-expanded');
+      row.removeAttribute('aria-expanded');
     }
+    if (this.selected) row.setAttribute('aria-selected', 'true');
+    else row.removeAttribute('aria-selected');
 
     // Update text
     const textEl = row.querySelector('[slot="text"]');

package/components/tree/tree.test.js

@@ -7,6 +7,7 @@
  */
 
 import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { html, stamp } from '../../core/template.js';
 
 beforeAll(async () => {
   await import('./tree.js');
@@ -153,3 +154,110 @@ describe('<tree-item-ui> caret slot + actions adoption (caret convention + FB-89
     expect(carets[0].getAttribute('name')).toBe('folder');
   });
 });
+
+describe('<tree-item-ui> ARIA tree containment (FEEDBACK-91)', () => {
+  let host;
+  const settle = () => new Promise((r) => setTimeout(r, 30));
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+  afterEach(() => host.remove());
+
+  // Mirrors axe-core's `aria-required-parent` check for `treeitem`: walking up
+  // from the treeitem, the first ancestor carrying a *non-generic* role must be
+  // `group` or `tree`. Roleless / presentation / display:contents wrapper spans
+  // are transparent pass-throughs (exactly the consumer's `.map()` case).
+  function requiredParentSatisfied(treeitem, root) {
+    let p = treeitem.parentElement;
+    while (p && p !== root.parentElement) {
+      const role = p.getAttribute('role');
+      if (role === 'group' || role === 'tree') return true;
+      if (role && role !== 'presentation' && role !== 'none') return false;
+      p = p.parentElement;
+    }
+    return false;
+  }
+
+  function buildStaticTree() {
+    const tree = document.createElement('tree-ui');
+    const parent = document.createElement('tree-item-ui');
+    parent.setAttribute('text', 'Colors');
+    parent.setAttribute('open', '');
+    for (const t of ['Neutral', 'Brand']) {
+      const c = document.createElement('tree-item-ui');
+      c.setAttribute('text', t);
+      parent.appendChild(c);
+    }
+    tree.appendChild(parent);
+    host.appendChild(tree);
+    return tree;
+  }
+
+  it('roles the host as group and the [slot="row"] as treeitem', async () => {
+    const tree = buildStaticTree();
+    await settle();
+    expect(tree.getAttribute('role')).toBe('tree');
+    for (const item of tree.querySelectorAll('tree-item-ui')) {
+      expect(item.getAttribute('role')).toBe('group');
+      const row = item.querySelector(':scope > [slot="row"]');
+      expect(row.getAttribute('role')).toBe('treeitem');
+      expect(row.getAttribute('tabindex')).toBe('0');
+    }
+  });
+
+  it('every treeitem row has a group/tree required parent (static markup)', async () => {
+    const tree = buildStaticTree();
+    await settle();
+    const rows = tree.querySelectorAll('[role="treeitem"]');
+    expect(rows.length).toBe(3); // parent + 2 children — was the axe-critical case
+    for (const row of rows) expect(requiredParentSatisfied(row, tree)).toBe(true);
+  });
+
+  it('nested treeitems satisfy required-parent when rendered via the template engine .map() (consumer repro)', async () => {
+    const ITEMS = [{ id: 'neutral', text: 'Neutral' }, { id: 'brand', text: 'Brand' }];
+    stamp(html`
+      <tree-ui>
+        <tree-item-ui text="Colors" open>
+          ${ITEMS.map((i) => html`<tree-item-ui .text=${i.text} .value=${i.id}></tree-item-ui>`)}
+        </tree-item-ui>
+      </tree-ui>
+    `, host);
+    await settle();
+
+    const tree = host.querySelector('tree-ui');
+    const rows = tree.querySelectorAll('[role="treeitem"]');
+    expect(rows.length).toBe(3);
+    for (const row of rows) expect(requiredParentSatisfied(row, tree)).toBe(true);
+
+    // The nested items sit BEHIND the template engine's display:contents wrapper
+    // span — proving the fix works without re-homing engine-owned nodes.
+    const child = tree.querySelector('tree-item-ui[value="neutral"]');
+    expect(child.parentElement.style.display).toBe('contents');
+    expect(child.getAttribute('role')).toBe('group');
+  });
+
+  it('aria-expanded lives on the row (treeitem), not the host group', async () => {
+    const tree = buildStaticTree();
+    await settle();
+    const parent = tree.querySelector('tree-item-ui');
+    const parentRow = parent.querySelector(':scope > [slot="row"]');
+    expect(parentRow.getAttribute('aria-expanded')).toBe('true');
+    expect(parent.hasAttribute('aria-expanded')).toBe(false); // not stranded on the host
+
+    const leaf = tree.querySelectorAll('tree-item-ui')[1]; // a child leaf
+    const leafRow = leaf.querySelector(':scope > [slot="row"]');
+    expect(leafRow.hasAttribute('aria-expanded')).toBe(false); // leaves carry none
+  });
+
+  it('aria-selected reflects onto the selected row only', async () => {
+    const tree = buildStaticTree();
+    await settle();
+    const [parent, neutral] = tree.querySelectorAll('tree-item-ui');
+    tree.select(neutral);
+    await settle();
+    expect(neutral.querySelector(':scope > [slot="row"]').getAttribute('aria-selected')).toBe('true');
+    expect(parent.querySelector(':scope > [slot="row"]').hasAttribute('aria-selected')).toBe(false);
+  });
+});

package/core/template.js

@@ -430,6 +430,13 @@ function wrap(part) {
   if (part.n.nodeType === 1 && part.n[PART]) return part.n;
   const c = document.createElement('span');
   c.style.display = 'contents';
+  // ARIA-transparent: display:contents removes the box from layout, but the
+  // span still generates a generic accessibility node — which breaks
+  // required-owned / required-parent relationships when it sits between a
+  // role-bearing parent and role-bearing children rendered via interpolation
+  // (tree→treeitem, menu→menuitem via `.map()`/`repeat()`). role="presentation"
+  // promotes the children to the real parent in the a11y tree. (FB-94 / FB-95)
+  c.setAttribute('role', 'presentation');
   c[PART] = true;
   part.n.replaceWith(c);
   part.n = c;
@@ -453,6 +460,7 @@ function applyValue(p, v) {
         if (isResult(item)) {
           const el = document.createElement('span');
           el.style.display = 'contents';
+          el.setAttribute('role', 'presentation'); // ARIA-transparent — see wrap()
           c.appendChild(el);
           stamp(item, el);
         } else {
@@ -526,6 +534,7 @@ export function repeat(items, keyFn, tplFn) {
         } else {
           const el = document.createElement('span');
           el.style.display = 'contents';
+          el.setAttribute('role', 'presentation'); // ARIA-transparent — see wrap()
           stamp(result, el);
           newMap.set(key, el);
         }

package/core/template.test.js

@@ -573,3 +573,39 @@ describe('html template — FB-57 (v0.6.8) nested SVG/MathML template namespace
     expect(p.namespaceURI).toBe('http://www.w3.org/1999/xhtml');
   });
 });
+
+describe('html template — FB-94/FB-95 (v0.7.x) ARIA-transparent wrapper spans', () => {
+  let container;
+  beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); });
+  afterEach(() => container.remove());
+
+  // The display:contents wrapper span the engine emits for interpolated parts
+  // must carry role="presentation" — display:contents removes the box from
+  // layout but the span still generates a generic a11y node, which breaks
+  // required-owned / required-parent relationships when it sits between a
+  // role-bearing parent and role-bearing children rendered via .map()/repeat()
+  // (tree→treeitem = FB-94, menu→menuitem = FB-95). Verified end-to-end with
+  // axe-core; these lock the substrate behaviour against regression.
+  const isContentsSpan = (s) => /display:\s*contents/.test(s.getAttribute('style') || '');
+
+  it('a `.map()` of templates wraps each item in a role="presentation" display:contents span', () => {
+    stamp(html`<ul>${['a', 'b', 'c'].map((x) => html`<li>${x}</li>`)}</ul>`, container);
+    const spans = [...container.querySelectorAll('span')].filter(isContentsSpan);
+    expect(spans.length).toBeGreaterThan(0);
+    spans.forEach((s) => expect(s.getAttribute('role')).toBe('presentation'));
+  });
+
+  it('a conditional `${cond ? html`` : null}` branch wraps in role="presentation"', () => {
+    stamp(html`<div>${true ? html`<span data-x>hi</span>` : null}</div>`, container);
+    const wrap = [...container.querySelectorAll('div > span')].find(isContentsSpan);
+    expect(wrap).toBeTruthy();
+    expect(wrap.getAttribute('role')).toBe('presentation');
+  });
+
+  it('`repeat()` keyed items wrap in role="presentation"', () => {
+    stamp(html`<ul>${repeat(['a', 'b'], (x) => x, (x) => html`<li>${x}</li>`)}</ul>`, container);
+    const spans = [...container.querySelectorAll('span')].filter(isContentsSpan);
+    expect(spans.length).toBeGreaterThan(0);
+    spans.forEach((s) => expect(s.getAttribute('role')).toBe('presentation'));
+  });
+});