@adia-ai/web-components 0.7.22 → 0.7.24

package/components/display-field/display-field.js

@@ -0,0 +1,141 @@
+/**
+ * <display-field-ui label="Card on file" value="•••• 4242" variant="masked" icon="lock" hint="Expires 12/26"></display-field-ui>
+ *
+ * Display-only labeled value — a field-shaped read-out for a static or
+ * masked value, or a labeled slot that hosts a third-party element (a
+ * Stripe Element iframe) under a proper caption.
+ *
+ * Unlike <field-ui> it wraps NO interactive control: no focus, no
+ * contenteditable, no form participation, no [for]/id-minting. The label
+ * names the whole field for assistive tech via role="group" +
+ * aria-labelledby, so a slotted foreign element is announced with its
+ * caption.
+ *
+ * Value comes from EITHER the `value` attribute OR unnamed default-slot
+ * children (the foreign-element path) — slot content wins when both are
+ * present.
+ */
+
+import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+
+// Monotonic id source for label/hint association (aria-labelledby /
+// aria-describedby need stable ids; multiple instances must not collide).
+let uid = 0;
+
+class UIDisplayField extends UIElement {
+  static properties = {
+    label:   { type: String, default: '',        reflect: true },
+    value:   { type: String, default: '',        reflect: true },
+    variant: { type: String, default: 'default', reflect: true },
+    hint:    { type: String, default: '',        reflect: true },
+    icon:    { type: String, default: '',        reflect: true },
+  };
+
+  static template = () => null;
+
+  #labelEl = null;
+  #valueEl = null;
+  #hintEl = null;
+  #iconEl = null;
+
+  connected() {
+    // A non-interactive labeled group — the label is the accessible name,
+    // which holds even when the value region is a foreign iframe.
+    this.setAttribute('role', 'group');
+
+    // The label element is the group's accessible-name source; create it
+    // once and mint a stable id for aria-labelledby. Prepend so it reads
+    // first for assistive tech (visual placement is grid-area driven).
+    this.#labelEl = this.querySelector(':scope > [slot="label"]');
+    if (!this.#labelEl) {
+      this.#labelEl = document.createElement('span');
+      this.#labelEl.setAttribute('slot', 'label');
+      this.insertBefore(this.#labelEl, this.firstChild);
+    }
+    if (!this.#labelEl.id) this.#labelEl.id = `display-field-label-${++uid}`;
+
+    // Re-bind any optional slot children that already exist in the light DOM.
+    // On a DOM move (disconnect → reconnect — e.g. UIElement.reconcile's
+    // insertBefore during a keyed list reorder) disconnected() nulled these
+    // fields but left the nodes in place; without re-binding, render() would
+    // see the null field and stamp a DUPLICATE. Query-or-leave-null mirrors
+    // the label handling above.
+    this.#valueEl = this.querySelector(':scope > [slot="value"]');
+    this.#hintEl = this.querySelector(':scope > [slot="hint"]');
+    this.#iconEl = this.querySelector(':scope > icon-ui[slot="icon"]');
+  }
+
+  render() {
+    if (!this.#labelEl) return;
+
+    // ── Label — the group's accessible name. ──
+    if (this.label) {
+      this.#labelEl.textContent = this.label;
+      this.#labelEl.hidden = false;
+      this.setAttribute('aria-labelledby', this.#labelEl.id);
+    } else {
+      this.#labelEl.hidden = true;
+      this.removeAttribute('aria-labelledby');
+    }
+
+    // ── Value — attribute path. Suppressed when the consumer slotted
+    //    foreign content (a Stripe mount, rich markup): that content owns
+    //    the value region. ──
+    const foreign = this.querySelector(':scope > :not([slot])');
+    if (foreign) {
+      if (this.#valueEl) { this.#valueEl.remove(); this.#valueEl = null; }
+    } else {
+      if (!this.#valueEl) {
+        this.#valueEl = document.createElement('span');
+        this.#valueEl.setAttribute('slot', 'value');
+        this.appendChild(this.#valueEl);
+      }
+      this.#valueEl.textContent = this.value;
+    }
+
+    // ── Hint — optional caption; drives aria-describedby. Removed when
+    //    absent so no empty grid row leaks a gap. ──
+    if (this.hint) {
+      if (!this.#hintEl) {
+        this.#hintEl = document.createElement('span');
+        this.#hintEl.setAttribute('slot', 'hint');
+        this.#hintEl.id = `display-field-hint-${++uid}`;
+        this.appendChild(this.#hintEl);
+      }
+      this.#hintEl.textContent = this.hint;
+      this.setAttribute('aria-describedby', this.#hintEl.id);
+    } else if (this.#hintEl) {
+      this.#hintEl.remove();
+      this.#hintEl = null;
+      this.removeAttribute('aria-describedby');
+    }
+
+    // ── Icon — optional leading glyph. Removed when absent so the icon
+    //    column collapses (the CSS gates the two-column layout on a
+    //    present [slot="icon"] child). ──
+    if (this.icon) {
+      if (!this.#iconEl) {
+        this.#iconEl = document.createElement('icon-ui');
+        this.#iconEl.setAttribute('slot', 'icon');
+        this.#iconEl.setAttribute('aria-hidden', 'true');
+        this.appendChild(this.#iconEl);
+      }
+      this.#iconEl.setAttribute('name', this.icon);
+    } else if (this.#iconEl) {
+      this.#iconEl.remove();
+      this.#iconEl = null;
+    }
+  }
+
+  disconnected() {
+    this.#labelEl = null;
+    this.#valueEl = null;
+    this.#hintEl = null;
+    this.#iconEl = null;
+  }
+}
+
+defineIfFree('display-field-ui', UIDisplayField);
+
+export { UIDisplayField };

package/components/display-field/display-field.test.js

@@ -0,0 +1,115 @@
+/**
+ * display-field-ui — display-only labeled value (upstream finding F5).
+ *
+ * Covers the contract that makes it NOT a control: group-label a11y, the
+ * dual value path (attr vs foreign slot), and the optional icon/hint that
+ * are removed (not just hidden) when their attribute clears.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './display-field.js';
+import '../icon/icon.js';
+
+const raf = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('display-field-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders as a labeled group: role=group + aria-labelledby → the label element', async () => {
+    const el = mount('<display-field-ui label="Account ID" value="acct_1Q9xK2"></display-field-ui>');
+    await raf();
+    expect(el.getAttribute('role')).toBe('group');
+    const labelEl = el.querySelector(':scope > [slot="label"]');
+    expect(labelEl).not.toBeNull();
+    expect(labelEl.textContent).toBe('Account ID');
+    expect(labelEl.id).toBeTruthy();
+    expect(el.getAttribute('aria-labelledby')).toBe(labelEl.id);
+  });
+
+  it('carries no input/focus/form semantics (no contenteditable, not focusable, no tabindex)', async () => {
+    const el = mount('<display-field-ui label="Card" value="•••• 4242"></display-field-ui>');
+    await raf();
+    expect(el.getAttribute('contenteditable')).toBeNull();
+    expect(el.getAttribute('tabindex')).toBeNull();
+    const valueEl = el.querySelector(':scope > [slot="value"]');
+    expect(valueEl.getAttribute('contenteditable')).toBeNull();
+    expect(valueEl.textContent).toBe('•••• 4242');
+  });
+
+  it('variant="masked" reflects and the value text is preserved', async () => {
+    const el = mount('<display-field-ui label="Card" value="•••• 4242" variant="masked"></display-field-ui>');
+    await raf();
+    expect(el.getAttribute('variant')).toBe('masked');
+    expect(el.querySelector(':scope > [slot="value"]').textContent).toBe('•••• 4242');
+  });
+
+  it('a foreign default-slot child owns the value region — the attr value element is suppressed', async () => {
+    const el = mount('<display-field-ui label="Card number"><div id="mount">[stripe]</div></display-field-ui>');
+    await raf();
+    // No auto [slot="value"] element — the foreign child is the value.
+    expect(el.querySelector(':scope > [slot="value"]')).toBeNull();
+    const foreign = el.querySelector(':scope > #mount');
+    expect(foreign).not.toBeNull();
+    expect(foreign.getAttribute('slot')).toBeNull();   // genuinely unnamed
+  });
+
+  it('icon attribute creates a leading icon-ui; clearing it removes the element (no phantom column)', async () => {
+    const el = mount('<display-field-ui label="Card" value="•••• 4242" icon="lock"></display-field-ui>');
+    await raf();
+    const iconEl = el.querySelector(':scope > icon-ui[slot="icon"]');
+    expect(iconEl).not.toBeNull();
+    expect(iconEl.getAttribute('name')).toBe('lock');
+
+    el.icon = '';
+    await raf();
+    expect(el.querySelector(':scope > [slot="icon"]')).toBeNull();
+  });
+
+  it('hint attribute creates a hint element + aria-describedby; clearing it removes both', async () => {
+    const el = mount('<display-field-ui label="Card" value="•••• 4242" hint="Expires 12/26"></display-field-ui>');
+    await raf();
+    const hintEl = el.querySelector(':scope > [slot="hint"]');
+    expect(hintEl).not.toBeNull();
+    expect(hintEl.textContent).toBe('Expires 12/26');
+    expect(el.getAttribute('aria-describedby')).toBe(hintEl.id);
+
+    el.hint = '';
+    await raf();
+    expect(el.querySelector(':scope > [slot="hint"]')).toBeNull();
+    expect(el.getAttribute('aria-describedby')).toBeNull();
+  });
+
+  it('surviving a DOM move (disconnect→reconnect) does NOT duplicate slot children', async () => {
+    const host1 = mount('<div></div>');
+    const el = document.createElement('display-field-ui');
+    el.setAttribute('label', 'Card');
+    el.setAttribute('value', '•••• 4242');
+    el.setAttribute('hint', 'Expires 12/26');
+    el.setAttribute('icon', 'lock');
+    host1.appendChild(el);
+    await raf();
+    expect(el.querySelectorAll(':scope > [slot="value"]').length).toBe(1);
+    expect(el.querySelectorAll(':scope > [slot="hint"]').length).toBe(1);
+    expect(el.querySelectorAll(':scope > icon-ui[slot="icon"]').length).toBe(1);
+
+    // Move to a new parent — fires disconnectedCallback then connectedCallback,
+    // exactly what UIElement.reconcile's insertBefore does on a keyed reorder.
+    const host2 = mount('<div></div>');
+    host2.appendChild(el);
+    await raf();
+
+    // No duplicates after the move — connected() re-binds the existing nodes.
+    expect(el.querySelectorAll(':scope > [slot="label"]').length).toBe(1);
+    expect(el.querySelectorAll(':scope > [slot="value"]').length).toBe(1);
+    expect(el.querySelectorAll(':scope > [slot="hint"]').length).toBe(1);
+    expect(el.querySelectorAll(':scope > icon-ui[slot="icon"]').length).toBe(1);
+    expect(el.querySelector(':scope > [slot="value"]').textContent).toBe('•••• 4242');
+  });
+});

package/components/display-field/display-field.yaml

@@ -0,0 +1,191 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIDisplayField
+tag: display-field-ui
+status: stable
+composes:
+  - icon-ui
+component: DisplayField
+category: form
+version: 1
+description: >-
+  Display-only labeled value — a field-shaped read-out for a static or
+  masked value (e.g. a card on file "•••• 4242"), or a labeled slot that
+  hosts a third-party element (a Stripe Element iframe) under a proper
+  caption. Unlike field-ui it wraps NO interactive control: no focus, no
+  contenteditable, no form participation, no [for]/id-minting. The label
+  names the whole field for assistive tech via role="group" +
+  aria-labelledby, so a slotted foreign element (iframe) is announced
+  with its caption. Reach for field-ui + input-ui when the value is
+  EDITABLE; stat-ui for a prominent metric/KPI; description-list-ui for
+  many read-only key/value pairs at once.
+props:
+  label:
+    description: The field caption. Names the whole field for assistive tech.
+    required: true
+    type: string
+    default: ""
+    reflect: true
+  value:
+    description: >-
+      The static value text to display (e.g. "•••• 4242"). Ignored when
+      the default slot already carries content — slot a foreign element
+      OR set value=, not both.
+    type: string
+    default: ""
+    reflect: true
+  variant:
+    description: >-
+      Cosmetic value treatment. `default` renders the value in the UI
+      font; `masked` switches to the code/mono family with tabular
+      numerals and light letter-spacing so masked strings ("•••• 4242")
+      align cleanly. Tokens only — no layout change.
+    type: string
+    default: default
+    enum: [default, masked]
+    reflect: true
+  hint:
+    description: >-
+      Optional caption rendered below the value in subtle style (e.g.
+      "Expires 12/26"). Wired into the field's aria-describedby.
+    type: string
+    default: ""
+    reflect: true
+  icon:
+    description: >-
+      Optional leading icon name shown beside the value (e.g. a lock or
+      card-brand glyph). Lazily creates a single icon-ui child.
+    type: string
+    default: ""
+    reflect: true
+events: {}
+slots:
+  default:
+    description: >-
+      The value content. Slot a third-party element here — a Stripe
+      Element iframe mount, or rich markup — and it takes the value
+      region under the label, replacing the [value] attribute. The
+      host's role="group" + aria-labelledby names it for assistive tech.
+  label:
+    description: >-
+      The caption element. Auto-stamped from the [label] attribute; slot
+      your own [slot="label"] child to override with richer markup. It is
+      the group's accessible name (the aria-labelledby target).
+  value:
+    description: >-
+      The static value element. Auto-stamped from the [value] attribute;
+      suppressed when the default slot carries foreign content.
+  hint:
+    description: >-
+      The hint caption below the value. Auto-stamped from the [hint]
+      attribute; wired into aria-describedby.
+  icon:
+    description: >-
+      The leading icon (a single icon-ui). Auto-stamped from the [icon]
+      attribute.
+states:
+  - name: idle
+    description: Default, non-interactive read-out.
+traits: []
+tokens:
+  --display-field-gap:
+    description: Vertical gap between the label, value, and hint rows.
+  --display-field-icon-gap:
+    description: Horizontal gap between the leading icon and the value.
+  --display-field-label-color:
+    description: Label foreground color.
+  --display-field-label-size:
+    description: Label font size.
+  --display-field-label-weight:
+    description: Label font weight.
+  --display-field-value-color:
+    description: Value foreground color.
+  --display-field-value-size:
+    description: Value font size.
+  --display-field-value-weight:
+    description: Value font weight.
+  --display-field-hint-color:
+    description: Hint foreground color.
+  --display-field-hint-size:
+    description: Hint font size.
+  --display-field-masked-font:
+    description: Font family applied to a masked value.
+  --display-field-masked-tracking:
+    description: Letter-spacing applied to a masked value.
+a2ui:
+  rules:
+    - rule: "Use for a display-ONLY labeled value — a masked card number, a 'card on file' read-out, an account id — anywhere a value reads as a field but must not be editable."
+      reason: "field-ui wraps an editable control; display-field-ui carries no input/focus/form semantics."
+    - rule: "To host a third-party element (a Stripe Element iframe) under a label, slot it as the default child instead of setting value=. The label names it via role=group + aria-labelledby."
+      reason: "field-ui auto-mints id/[for] on a real control; a foreign iframe is not labelable, so group-labelling is the correct a11y path."
+    - rule: "For an editable field use field-ui + input-ui; for a prominent KPI use stat-ui; for many read-only pairs at once use description-list-ui."
+      reason: "Distinct roles — don't reach for display-field-ui when the value is editable or when it's a metric."
+anti_patterns:
+  - description: >-
+      Using input-ui[readonly] to render a static masked value. A
+      readonly input still carries contenteditable/focus semantics and
+      tab-stops; a display read-out should not be a control.
+    wrong: |
+      <input-ui readonly value="•••• 4242"></input-ui>
+    right: |
+      <display-field-ui label="Card on file" value="•••• 4242" variant="masked"></display-field-ui>
+    rule: A non-editable masked value is display-field-ui, not a readonly input.
+examples:
+  - name: card-on-file
+    description: A masked "card on file" read-out with a leading lock icon and an expiry hint.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "DisplayField",
+          "label": "Card on file",
+          "value": "•••• •••• •••• 4242",
+          "variant": "masked",
+          "icon": "lock",
+          "hint": "Expires 12/26"
+        }
+      ]
+  - name: foreign-element-slot
+    description: A labeled slot hosting a third-party element (e.g. a Stripe Element mount).
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "DisplayField",
+          "label": "Card number",
+          "children": ["mount"]
+        },
+        { "id": "mount", "component": "Text", "text": "[Stripe Element mounts here]" }
+      ]
+keywords:
+  - display field
+  - readonly
+  - read-only
+  - masked
+  - mask
+  - static value
+  - card on file
+  - last four
+  - value
+  - readout
+  - stripe element
+  - iframe slot
+  - non-editable
+synonyms:
+  masked:
+    - display field
+    - field
+    - value
+  readout:
+    - display field
+    - stat
+    - field
+  value:
+    - display field
+    - field
+    - stat
+related:
+  - field
+  - input
+  - stat
+  - description-list

package/components/icon/icon.class.js

@@ -12,7 +12,35 @@
  */
 
 import { UIElement } from '../../core/element.js';
-import { getIcon, whenIconRegistryReady } from '../../core/icons.js';
+import { getIcon, whenIconRegistryReady, iconRegistryUnwired } from '../../core/icons.js';
+
+// Upstream finding F1: the zero-config Phosphor glob path can leave the icon
+// registry completely unwired under Vite 8 / rolldown (the `import.meta.glob`
+// macro doesn't transform from inside a published dependency), so every
+// `<icon-ui>` renders blank. The loader layer warns, but the per-icon miss is
+// silent (`getIcon → ''`). Fail loud ONCE from the component too, with the
+// actionable fix. Deferred a macrotask so an app that calls
+// `installIconLoaders()` at entry (the correct path) is never false-flagged.
+let _unwiredCheckScheduled = false;
+function warnIfIconRegistryUnwired() {
+  if (_unwiredCheckScheduled) return;
+  _unwiredCheckScheduled = true;
+  setTimeout(() => {
+    if (!iconRegistryUnwired()) return;   // loaders arrived after all — fine
+    // eslint-disable-next-line no-console
+    console.error(
+      `[icon-ui] No icons are registered and no icon loaders were installed — every <icon-ui> renders blank.\n` +
+      `  The zero-config import.meta.glob path does not work from inside a published dependency under Vite 8 / rolldown.\n` +
+      `  Fix — from your APP entry (where import.meta.glob is transformed):\n` +
+      `    npm i @phosphor-icons/core\n` +
+      `    import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
+      `    installIconLoaders({ regular: import.meta.glob(\n` +
+      `      '/node_modules/@phosphor-icons/core/assets/regular/*.svg',\n` +
+      `      { query: '?raw', import: 'default', eager: true }) });\n` +
+      `  See USAGE.md § Icons.`,
+    );
+  }, 0);
+}
 
 export class UIIcon extends UIElement {
   static properties = {
@@ -62,6 +90,11 @@ export class UIIcon extends UIElement {
     if (this.label) this.setAttribute('aria-label', this.label);
     const svg = getIcon(this.name, this.weight || 'regular');
     if (svg && this.innerHTML !== svg) this.innerHTML = svg;
+    // A named icon that resolved to nothing AND a never-wired registry is the
+    // F1 symptom — schedule the one-shot fail-loud. A plain typo (registry
+    // populated, this one name absent) settles `iconRegistryUnwired()` false
+    // and is correctly NOT flagged here.
+    else if (this.name && !svg) warnIfIconRegistryUnwired();
 
     // Pixel / rem / em passthrough — `size="48"` → 48px,
     // `size="3.5rem"` → 3.5rem. Named-scale values (xs/sm/md/lg/xl/

package/components/index.js

@@ -71,6 +71,7 @@ export { UISwatch } from './swatch/swatch.js';
 export { UICol }   from './col/col.js';
 export { UIField } from './field/field.js';
 export { UIFields } from './fields/fields.js';
+export { UIDisplayField } from './display-field/display-field.js';
 export { UIRow }   from './row/row.js';
 export { UIGrid }  from './grid/grid.js';
 export { UIStack } from './stack/stack.js';

package/components/table/table.class.js

@@ -240,6 +240,10 @@ export class UITable extends UIElement {
   // ── Public API: expansion ──
 
   toggleExpand(index) {
+    // A row gated out by `rowExpandable` cannot be toggled — but always allow
+    // collapsing one that is already open (e.g. the predicate flipped while a
+    // detail pane was showing), so it can't get stuck expanded.
+    if (!this.#isRowExpandable(index) && !this.#expanded.has(index)) return;
     if (this.#expanded.has(index)) {
       this.#expanded.delete(index);
       this.dispatchEvent(new CustomEvent('row-collapse', { detail: { index, row: this.#data[index] }, bubbles: true }));
@@ -255,6 +259,27 @@ export class UITable extends UIElement {
   /** @type {((row: object, index: number) => HTMLElement)|null} */
   expandRenderer = null;
 
+  /**
+   * Per-row expand gate. When `expandable` is on and this is set, a row shows
+   * the expand caret (and can open a detail pane) only when the predicate
+   * returns truthy for that row. Lets heterogeneous rows opt out of the
+   * uniform affordance — e.g. `rowExpandable: r => r.status === 'failed'` so a
+   * succeeded row carries no caret while a failed one does. The reserved
+   * expand column is kept either way, so column alignment never shifts.
+   * `null` (default) = every row is expandable (legacy behavior).
+   * @type {((row: object, index: number) => boolean)|null}
+   */
+  rowExpandable = null;
+
+  /** True when `expandable` is on AND this row passes the per-row gate. */
+  #isRowExpandable(dataIndex) {
+    if (!this.expandable) return false;
+    if (typeof this.rowExpandable === 'function') {
+      return !!this.rowExpandable(this.#data[dataIndex], dataIndex);
+    }
+    return true;
+  }
+
   // ── Public API: state persistence ──
 
   getState() {
@@ -601,16 +626,18 @@ export class UITable extends UIElement {
       if (existing) this.#updateRow(existing, idx, visCols);
 
       // Expand toggle in first cell
-      if (this.expandable) {
+      if (this.#isRowExpandable(idx)) {
         const isExpanded = this.#expanded.has(idx);
         if (isExpanded) row.setAttribute('data-expanded', '');
         else row.removeAttribute('data-expanded');
+      } else {
+        row.removeAttribute('data-expanded');
       }
 
       bodyChildren.push(row);
 
       // Detail row (expansion)
-      if (this.expandable && this.#expanded.has(idx)) {
+      if (this.#isRowExpandable(idx) && this.#expanded.has(idx)) {
         let detail = body.querySelector(`:scope > [data-detail-row][data-for="${idx}"]`);
         if (!detail) {
           detail = document.createElement('div');
@@ -779,19 +806,23 @@ export class UITable extends UIElement {
 
     const cells = [];
 
-    // Expand toggle cell
+    // Expand toggle cell. The reserved column cell is always emitted (so the
+    // grid stays aligned), but the caret button is stamped only when this row
+    // passes the per-row expand gate — non-expandable rows show an empty cell.
     if (this.expandable) {
       const cell = document.createElement('div');
       cell.setAttribute('role', 'gridcell');
       cell.setAttribute('data-expand-col', '');
-      const btn = document.createElement('button');
-      btn.setAttribute('data-expand-toggle', '');
-      btn.setAttribute('aria-label', 'Expand row');
-      const icon = document.createElement('icon-ui');
-      icon.setAttribute('name', 'caret-right');
-      icon.setAttribute('size', 'xs');
-      btn.appendChild(icon);
-      cell.appendChild(btn);
+      if (this.#isRowExpandable(dataIndex)) {
+        const btn = document.createElement('button');
+        btn.setAttribute('data-expand-toggle', '');
+        btn.setAttribute('aria-label', 'Expand row');
+        const icon = document.createElement('icon-ui');
+        icon.setAttribute('name', 'caret-right');
+        icon.setAttribute('size', 'xs');
+        btn.appendChild(icon);
+        cell.appendChild(btn);
+      }
       cells.push(cell);
     }
 

package/components/table/table.test.js

@@ -336,3 +336,56 @@ describe('table-ui — raw mode passthrough (FB-53 §2)', () => {
     expect(el.querySelector(':scope > [data-body]')).not.toBeNull();
   });
 });
+
+// ── F6 (upstream): per-row expand gate via `rowExpandable` ───────────────────
+describe('table-ui — F6 per-row expand suppression (rowExpandable)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  const bodyRows = (el) =>
+    el.querySelectorAll(':scope > [data-body] > [role="row"]:not([data-detail-row])');
+
+  it('default (no predicate): every row carries an expand caret', async () => {
+    const el = mount('<table-ui expandable></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await raf();
+    const rows = bodyRows(el);
+    expect(rows.length).toBe(2);
+    for (const row of rows) {
+      expect(row.querySelector('[data-expand-toggle]')).not.toBeNull();
+    }
+  });
+
+  it('predicate suppresses the caret on gated rows but keeps the reserved cell', async () => {
+    const el = mount('<table-ui expandable></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    el.rowExpandable = (row) => row.id === 2;   // only Bob expandable
+    await raf();
+    const rows = bodyRows(el);
+
+    // Alice (id 1) — reserved cell present, NO caret button.
+    expect(rows[0].querySelector(':scope > [data-expand-col]')).not.toBeNull();
+    expect(rows[0].querySelector('[data-expand-toggle]')).toBeNull();
+
+    // Bob (id 2) — caret button present.
+    expect(rows[1].querySelector('[data-expand-toggle]')).not.toBeNull();
+  });
+
+  it('toggleExpand is a no-op on a gated row (no detail row renders)', async () => {
+    const el = mount('<table-ui expandable></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    el.rowExpandable = (row) => row.id === 2;
+    await raf();
+
+    el.toggleExpand(0);   // Alice — gated out
+    await raf();
+    expect(el.querySelector('[data-detail-row][data-for="0"]')).toBeNull();
+    expect(el.expanded).not.toContain(0);
+
+    el.toggleExpand(1);   // Bob — allowed
+    await raf();
+    expect(el.expanded).toContain(1);
+  });
+});

package/core/icons.js

@@ -135,6 +135,20 @@ let registryReady = false;
 let resolveRegistryReady;
 export const whenIconRegistryReady = new Promise((r) => { resolveRegistryReady = r; });
 
+/**
+ * True when NO icons are registered AND no loaders were ever installed — i.e.
+ * the icon subsystem was never wired. The usual cause: the zero-config
+ * `icons-phosphor.js` `import.meta.glob('/node_modules/...')` path is a
+ * build-time macro that does not transform from inside a published dependency
+ * under Vite 8 / rolldown, so `installIconLoaders` never ran and the registry
+ * stays empty. Distinct from a single bad icon name (registry non-empty, that
+ * one name absent). `<icon-ui>` uses this to fail loud once rather than render
+ * blank silently. See `USAGE.md` § Icons.
+ */
+export function iconRegistryUnwired() {
+  return registry.size === 0 && !registryReady;
+}
+
 /**
  * Install a per-weight loader map and mark the registry ready. The map
  * shape matches `import.meta.glob` output: `{ '/path/to/star.svg': loader }`.