@adia-ai/web-components 0.7.23 → 0.7.25

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/drawer/drawer.class.js

@@ -88,7 +88,7 @@ export class UIDrawer extends UIElement {
     // after the property change, which Safari treats as outside the user-gesture
     // window and silently no-ops the showModal. Wrap the auto-installed `open`
     // setter so dialog state syncs in the same synchronous frame as the
-    // assignment. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+    // assignment. See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
     const desc = Object.getOwnPropertyDescriptor(this, 'open');
     if (desc?.set) {
       const origSet = desc.set;
@@ -337,7 +337,7 @@ export class UIDrawer extends UIElement {
       // requestAnimationFrame when a top-layer dialog is open, sometimes
       // delaying [data-open] (and the slide-in transition) by tens of
       // seconds. Forcing a reflow keeps the animation start in the same
-      // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+      // synchronous frame. See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
       void dialog.offsetHeight;
       dialog.setAttribute('data-open', '');
       // §FB-27 (P2): emit `opened` after the slide-in transition completes

package/components/feed/feed.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Feed.json",
   "title": "Feed",
-  "description": "Shared top-layer feed channel. Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
+  "description": "Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
   "type": "object",
   "allOf": [
     {

package/components/feed/feed.class.js

@@ -14,7 +14,7 @@
 /**
  * <feed-ui> + <feed-item-ui> — Shared top-layer feed channel.
  *
- * Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
+ * Per .claude/docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
  *
  * Phase 1 (skeleton) ships here:
  *   - Per-position singletons (`<feed-ui position="bottom-right">`)

package/components/feed/feed.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<feed-ui>` — Shared top-layer feed channel. Per docs/specs/feed-channel.md
+ * `<feed-ui>` — Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md
  * (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
  * document.body via Popover API; consumers post via the static API
  * (`UIFeed.post()`) or the global 'feed' CustomEvent.

package/components/feed/feed.yaml

@@ -8,7 +8,7 @@ component: Feed
 category: container
 version: 1
 description: >-
-  Shared top-layer feed channel. Per docs/specs/feed-channel.md
+  Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md
   (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
   document.body via Popover API; consumers post via the static API
   (`UIFeed.post()`) or the global 'feed' CustomEvent.
@@ -60,7 +60,7 @@ related:
 a2ui:
   rules:
     - rule: 'Top-layer notification feed channel — singleton per position (top-right, bottom-center, etc.) mounted lazily into document.body.'
-      reason: 'Per docs/specs/feed-channel.md.'
+      reason: 'Per .claude/docs/specs/feed-channel.md.'
     - rule: 'Hosts <feed-item-ui> children programmatically via static API (UIFeed.post(...)). Do not place feed-items declaratively.'
       reason: 'Imperative API ownership.'
     - rule: 'For inline persistent alerts inside content regions use <alert-ui> instead; feed is ephemeral overlay.'

package/components/field/field.class.js

@@ -60,7 +60,7 @@ export class UIField extends UIElement {
   // is the single source of truth — validity is a property of the value, not
   // of the layout wrapper). field-ui mirrors the child's error string into
   // its own [data-field-error] slot so the validation message renders below
-  // the control. See docs/specs/component-token-contract.md "Toggle state
+  // the control. See .claude/docs/specs/component-token-contract.md "Toggle state
   // naming" / open decisions resolution log.
   get error() {
     const ctrl = this.#findControl();

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/loading-overlay/loading-overlay.class.js

@@ -49,7 +49,7 @@
  * changes are driven by the reactive [active] setter wrapper, which
  * starts/cancels the timer + applies aria-busy when the timer fires.
  *
- * @see SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md)
+ * @see SPEC-034 (.claude/docs/specs/implementation-ready/SPEC-034-loading-overlay.md)
  */
 
 import { UIElement } from '../../core/element.js';

package/components/loading-overlay/loading-overlay.yaml

@@ -1,4 +1,4 @@
-# Hand-authored per SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md).
+# Hand-authored per SPEC-034 (.claude/docs/specs/implementation-ready/SPEC-034-loading-overlay.md).
 # Edit this file; run `npm run build:components` to regenerate loading-overlay.a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UILoadingOverlay

package/components/modal/modal.class.js

@@ -212,7 +212,7 @@ export class UIModal extends UIElement {
     // Sync open state. Synchronous reflow instead of rAF — Safari throttles
     // requestAnimationFrame when a top-layer dialog is open, sometimes
     // delaying [data-open] (and the scale-in transition) by tens of seconds.
-    // See docs/BROWSER-COMPAT.md §3a (Flavor C).
+    // See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
     if (this.open && !dialog.open) {
       this.#closing = false;
       this.#previousFocus = document.activeElement;

package/components/nav/nav.class.js

@@ -134,7 +134,7 @@ export class UINav extends UIElement {
   // Safari macOS leaves :hover stuck on items the cursor passed through
   // when the DOM mutates during click+route navigation. Toggling pointer-
   // events forces re-evaluation of hover state on next paint.
-  // See docs/BROWSER-COMPAT.md §3a.
+  // See .claude/docs/BROWSER-COMPAT.md §3a.
   #flushHoverState() {
     this.style.pointerEvents = 'none';
     requestAnimationFrame(() => {

package/components/nav/nav.examples.md

@@ -18,10 +18,10 @@
 
 ```html
 <nav-ui variant="section" heading="Documentation" style="width:240px;">
-  <nav-item-ui text="Overview" value="docs/overview" selected></nav-item-ui>
-  <nav-item-ui text="Quickstart" value="docs/quickstart"></nav-item-ui>
-  <nav-item-ui text="API reference" value="docs/api"></nav-item-ui>
-  <nav-item-ui text="Examples" value="docs/examples"></nav-item-ui>
+  <nav-item-ui text="Overview" value=".claude/docs/overview" selected></nav-item-ui>
+  <nav-item-ui text="Quickstart" value=".claude/docs/quickstart"></nav-item-ui>
+  <nav-item-ui text="API reference" value=".claude/docs/api"></nav-item-ui>
+  <nav-item-ui text="Examples" value=".claude/docs/examples"></nav-item-ui>
 </nav-ui>
 ```
 

package/components/popover/popover.class.js

@@ -96,7 +96,7 @@ export class UIPopover extends UIElement {
       // try/catch covers test envs (happy-dom) without the API. Known iOS
       // Safari quirks at the supported floor (light-dismiss broken on
       // 17.0–18.2, virtual-keyboard-on-input persists past 18.3) are
-      // documented in docs/BROWSER-COMPAT.md §3a.
+      // documented in .claude/docs/BROWSER-COMPAT.md §3a.
       try { content.showPopover(); } catch { /* popover API unavailable — anchor positioning still runs */ }
     }
 

package/components/spinner/spinner.class.js

@@ -36,7 +36,7 @@
  * sets the three ARIA attributes once; render() keeps aria-valuetext in
  * sync with the [label] prop.
  *
- * @see SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
+ * @see SPEC-001 (.claude/docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
  */
 
 import { UIElement } from '../../core/element.js';