@adia-ai/web-components 0.7.23 → 0.7.24

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.24] — 2026-07-01
+
+Upstream consumer findings from `adia-pay` against installed `0.7.23` (F1–F6).
+
+### Added
+- **`display-field-ui` (`components/display-field/`) — new display-only labeled-value primitive.** Fills a capability gap: a field-shaped read-out for a static or masked value (a card on file, `•••• 4242`, an account id) 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 — so a readonly `input-ui` (which keeps input semantics) is no longer the only option. Props: `label` (required; names the group via `role="group"` + `aria-labelledby`), `value` (static text), `variant` (`default` | `masked` — mono/tabular treatment so `•••• 4242` aligns), `hint` (caption + `aria-describedby`), `icon` (leading glyph). The value comes from the `value` attr **or** an unnamed default-slot child (the foreign-element path) — slot content wins when both are present. Ships yaml + css + js + d.ts + a2ui sidecar + demo (`display-field.examples.html`) + 6 unit tests; registered in the component barrel + `styles/components.css`; `dist/` + `custom-elements.json` (120 → 121 modules) regenerated. Additive (PATCH). (upstream finding F5)
+- **`table-ui` (`components/table/`) — `rowExpandable` per-row expand gate.** `expandable` was host-level: every row got the same `caret-right` toggle and one host-level `expandRenderer` drove all detail panes, so heterogeneous rows (a *succeeded* payment needing no detail vs. a *failed* one that expands to a reason) could not vary the affordance. New optional `rowExpandable(row, index) => boolean` callback gates the caret per row — non-expandable rows keep the reserved expand-column cell (grid alignment never shifts) but show no caret and can't open a detail pane; `toggleExpand()` is guarded to match (it still collapses an already-open row if the predicate later flips, so a row can't get stuck open). `null` (default) preserves the legacy "every row expandable" behavior. Demo: the `rowExpandable` section in `table.examples.html` (only Failed payments expand). Regression: 3 tests in `table.test.js`. Additive — no API removed (PATCH). (upstream finding F6)
+
+### Fixed
+- **`icon-ui` (`components/icon/`) — fails loud when the icon registry was never wired.** Under Vite 8 / rolldown the zero-config `import.meta.glob('/node_modules/@phosphor-icons/…')` path in `icons-phosphor.js` does not transform from inside a published dependency, leaving the registry empty so every `<icon-ui>` renders blank — previously **silently** (a single missing icon warned, but a wholly-unwired registry did not). New `iconRegistryUnwired()` predicate (`core/icons.js`) distinguishes "never wired" (`registry.size === 0 && !registryReady`) from "one bad name"; `icon.class.js` schedules a one-shot, macrotask-deferred `console.error` naming the exact fix (install `@phosphor-icons/core` + call `installIconLoaders` from the app entry) only when a named icon resolves to nothing AND the registry is unwired. The deferral means a correctly-wired app entry is never false-flagged. Documented as the primary bundler path in `USAGE.md` § Icons. (upstream finding F1)
+- **`custom-elements.json` — manifest no longer fabricates nonexistent modules.** `scripts/build/generate-custom-elements-json.mjs` emitted a `javascript-module` + class + `custom-element-definition` for every component yaml by assuming a `components/<dir>/<base>.js` file existed — fabricating e.g. `UIHeader` → `header.js` (the CSS-only `header-ui` has no class file) and pointing co-located children (menu-item-ui, menu-divider-ui, …) at nonexistent per-child `.js` files. The generator now scans the actual `.js` sources for `customElements.define` / `defineIfFree` / `defineIfUndefined` calls, maps each tag to the file that really defines it, groups declarations by real module path, and lists genuinely CSS-only tags (aside/footer/header/section-ui) as skipped. Regenerated manifest: 120 modules / 134 tags, 0 dangling file paths (was 110 modules carrying fabricated paths). (upstream finding F4)
+
+### Changed
+- **`@phosphor-icons/core` is now a direct dependency (`^2.1.1`).** It was referenced by the icon-loader glob but absent from every dependency field, so the documented zero-config icon path could not resolve its SVG assets from a clean install. Added to `dependencies` so the assets resolve; the app still wires the loader glob from its own source graph (see `USAGE.md` § Icons / finding F1). (upstream finding F2)
+
 ## [0.7.23] — 2026-06-30
 
 ### Fixed

package/USAGE.md

@@ -9,17 +9,18 @@ The complete reference for engineers and agents **integrating** AdiaUI into an a
 ## Contents
 
 1. [Install](#install)
-2. [The mental model](#the-mental-model)
-3. [Property reactivity (signal-backed)](#property-reactivity-signal-backed)
-4. [Property binding patterns (templates / framework integration)](#property-binding-patterns)
-5. [Event contract — `CustomEvent` with `detail`](#event-contract)
-6. [Form participation — `UIFormElement` + `ElementInternals`](#form-participation)
-7. [Data binding with `data-stream-*`](#data-binding-with-data-stream-)
-8. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
-9. [Theming, density, size](#theming-density-size)
-10. [Registration — auto vs explicit](#registration--auto-vs-explicit)
-11. [TypeScript](#typescript)
-12. [Anti-patterns](#anti-patterns)
+2. [Icons — wiring the registry](#icons--wiring-the-registry)
+3. [The mental model](#the-mental-model)
+4. [Property reactivity (signal-backed)](#property-reactivity-signal-backed)
+5. [Property binding patterns (templates / framework integration)](#property-binding-patterns)
+6. [Event contract — `CustomEvent` with `detail`](#event-contract)
+7. [Form participation — `UIFormElement` + `ElementInternals`](#form-participation)
+8. [Data binding with `data-stream-*`](#data-binding-with-data-stream-)
+9. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
+10. [Theming, density, size](#theming-density-size)
+11. [Registration — auto vs explicit](#registration--auto-vs-explicit)
+12. [TypeScript](#typescript)
+13. [Anti-patterns](#anti-patterns)
 
 ---
 
@@ -96,6 +97,50 @@ For the live demo of every component: <https://ui-kit.exe.xyz/site/components/>.
 
 ---
 
+## Icons — wiring the registry
+
+`<icon-ui>` (and every component that renders an icon — `<button-ui icon>`,
+`<badge-ui>`, menus, etc.) draws from an **icon registry** that your app
+must wire **once, from your own entry module**. Out of the box the registry
+is empty; an un-wired registry renders every icon **blank**.
+
+**Why the app has to do it.** The zero-config glob in the package's own
+`icons-phosphor.js` uses `import.meta.glob('/node_modules/@phosphor-icons/…')`,
+which is a **build-time macro your bundler rewrites** — and under Vite 8 /
+rolldown that rewrite **does not happen for code imported from inside a
+published dependency**. The glob has to be evaluated in *your* source graph.
+`@phosphor-icons/core` ships as a dependency of this package (so the SVG
+assets resolve), but the glob that reads them must live in your app.
+
+**The one-time wiring (do this in your app entry, before first paint):**
+
+```js
+import { installIconLoaders } from '@adia-ai/web-components/core/icons';
+
+installIconLoaders({
+  regular: import.meta.glob(
+    '/node_modules/@phosphor-icons/core/assets/regular/*.svg',
+    { query: '?raw', import: 'default', eager: true },
+  ),
+  // add other weights only if you use them:
+  // bold:  import.meta.glob('/node_modules/@phosphor-icons/core/assets/bold/*.svg',  { query: '?raw', import: 'default', eager: true }),
+  // fill:  import.meta.glob('/node_modules/@phosphor-icons/core/assets/fill/*.svg',  { query: '?raw', import: 'default', eager: true }),
+});
+```
+
+`installIconLoaders` is idempotent, may be called before or after the
+elements connect (icons already on the page repaint when it runs), and
+accepts either the per-weight map above or a flat `path → svg-string` map
+if you source icons some other way (`registerIcon(name, svg)` /
+`registerIcons(map)` are the lower-level primitives).
+
+**Fail-loud, not fail-blank.** If any `<icon-ui name="…">` renders and the
+registry was never wired, the component logs a one-shot `console.error`
+naming this exact fix. A single *missing* icon (registry wired, that one
+name absent) warns separately and does not trip the un-wired error.
+
+---
+
 ## The mental model
 
 Every AdiaUI primitive is a **standard light-DOM custom element**. There's no shadow DOM, no compiler, no framework — just `customElements.define()` extending a small `UIElement` base class. The base class wires a signal-backed property system on top.

package/components/display-field/display-field.a2ui.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/DisplayField.json",
+  "title": "DisplayField",
+  "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.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "DisplayField"
+    },
+    "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": ""
+    },
+    "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": ""
+    },
+    "label": {
+      "description": "The field caption. Names the whole field for assistive tech.",
+      "type": "string",
+      "default": ""
+    },
+    "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": ""
+    },
+    "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",
+      "enum": [
+        "default",
+        "masked"
+      ],
+      "default": "default"
+    }
+  },
+  "required": [
+    "component",
+    "label"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "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.",
+        "right": "<display-field-ui label=\"Card on file\" value=\"•••• 4242\" variant=\"masked\"></display-field-ui>\n",
+        "rule": "A non-editable masked value is display-field-ui, not a readonly input.",
+        "wrong": "<input-ui readonly value=\"•••• 4242\"></input-ui>\n"
+      }
+    ],
+    "category": "form",
+    "composes": [
+      "icon-ui"
+    ],
+    "events": {},
+    "examples": [
+      {
+        "description": "A masked \"card on file\" read-out with a leading lock icon and an expiry hint.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"DisplayField\",\n    \"label\": \"Card on file\",\n    \"value\": \"•••• •••• •••• 4242\",\n    \"variant\": \"masked\",\n    \"icon\": \"lock\",\n    \"hint\": \"Expires 12/26\"\n  }\n]",
+        "name": "card-on-file"
+      },
+      {
+        "description": "A labeled slot hosting a third-party element (e.g. a Stripe Element mount).",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"DisplayField\",\n    \"label\": \"Card number\",\n    \"children\": [\"mount\"]\n  },\n  { \"id\": \"mount\", \"component\": \"Text\", \"text\": \"[Stripe Element mounts here]\" }\n]",
+        "name": "foreign-element-slot"
+      }
+    ],
+    "keywords": [
+      "display field",
+      "readonly",
+      "read-only",
+      "masked",
+      "mask",
+      "static value",
+      "card on file",
+      "last four",
+      "value",
+      "readout",
+      "stripe element",
+      "iframe slot",
+      "non-editable"
+    ],
+    "name": "UIDisplayField",
+    "related": [
+      "field",
+      "input",
+      "stat",
+      "description-list"
+    ],
+    "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."
+      },
+      "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."
+      },
+      "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."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, non-interactive read-out.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "masked": [
+        "display field",
+        "field",
+        "value"
+      ],
+      "readout": [
+        "display field",
+        "stat",
+        "field"
+      ],
+      "value": [
+        "display field",
+        "field",
+        "stat"
+      ]
+    },
+    "tag": "display-field-ui",
+    "tokens": {
+      "--display-field-gap": {
+        "description": "Vertical gap between the label, value, and hint rows."
+      },
+      "--display-field-hint-color": {
+        "description": "Hint foreground color."
+      },
+      "--display-field-hint-size": {
+        "description": "Hint font size."
+      },
+      "--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-masked-font": {
+        "description": "Font family applied to a masked value."
+      },
+      "--display-field-masked-tracking": {
+        "description": "Letter-spacing applied to a masked value."
+      },
+      "--display-field-value-color": {
+        "description": "Value foreground color."
+      },
+      "--display-field-value-size": {
+        "description": "Value font size."
+      },
+      "--display-field-value-weight": {
+        "description": "Value font weight."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/display-field/display-field.css

@@ -0,0 +1,91 @@
+@scope (display-field-ui) {
+  :where(:scope) {
+    /* ── Tokens ── (label chrome mirrors field-ui so a display value reads
+       as a sibling of an editable field) */
+    --display-field-gap:            var(--a-space-1);
+    --display-field-icon-gap:       var(--a-space-2);
+    --display-field-label-color:    var(--a-fg);
+    --display-field-label-size:     var(--a-ui-sm);
+    --display-field-label-weight:   var(--a-weight-medium);
+    --display-field-value-color:    var(--a-fg);
+    --display-field-value-size:     var(--a-ui-md);
+    --display-field-value-weight:   var(--a-weight-regular);
+    --display-field-hint-color:     var(--a-fg-muted);
+    --display-field-hint-size:      var(--a-ui-sm);
+    --display-field-masked-font:    var(--a-font-family-code);
+    --display-field-masked-tracking: 0.06em;
+  }
+
+  /* ── Base — single grid, rows placed by [slot] named areas. No DOM
+       reparenting; the value area accepts the auto [slot="value"] element
+       (from the `value` attr) AND any unnamed foreign child (a slotted
+       iframe mount). ── */
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas:
+      "label"
+      "value"
+      "hint";
+    row-gap: var(--display-field-gap);
+    min-width: 0;
+  }
+
+  /* With a leading icon → two columns; the icon spans the value row only,
+     label + hint stay full-width. The column is gated on a present icon so
+     no empty track leaks a column-gap when there's no icon. */
+  :scope:has(> [slot="icon"]) {
+    grid-template-columns: auto minmax(0, 1fr);
+    grid-template-areas:
+      "label label"
+      "icon  value"
+      "hint  hint";
+    column-gap: var(--display-field-icon-gap);
+  }
+
+  /* ── Slot styling ── */
+  :scope > [slot="label"] {
+    grid-area: label;
+    color: var(--display-field-label-color);
+    font-size: var(--display-field-label-size);
+    font-weight: var(--display-field-label-weight);
+    line-height: 1.3;
+    min-width: 0;
+  }
+
+  :scope > [slot="icon"] {
+    grid-area: icon;
+    align-self: center;
+    color: var(--a-fg-muted);
+  }
+
+  /* The value area: the auto attr element + any foreign unnamed child. */
+  :scope > [slot="value"],
+  :scope > :not([slot]) {
+    grid-area: value;
+    color: var(--display-field-value-color);
+    font-size: var(--display-field-value-size);
+    font-weight: var(--display-field-value-weight);
+    line-height: 1.3;
+    min-width: 0;
+  }
+
+  :scope > [slot="hint"] {
+    grid-area: hint;
+    color: var(--display-field-hint-color);
+    font-size: var(--display-field-hint-size);
+    line-height: 1.3;
+    min-width: 0;
+  }
+
+  /* ── Variant: masked — code/mono family + tabular numerals + tracking so
+       bullet-and-digit masked strings ("•••• 4242") align cleanly. Cosmetic
+       only; no layout change. ── */
+  :scope[variant="masked"] > [slot="value"],
+  :scope[variant="masked"] > :not([slot]) {
+    font-family: var(--display-field-masked-font);
+    font-variant-numeric: tabular-nums;
+    letter-spacing: var(--display-field-masked-tracking);
+  }
+}

package/components/display-field/display-field.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `<display-field-ui>` — 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.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/display-field
+ *
+ * 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 UIDisplayField extends UIElement {
+  /** Optional caption rendered below the value in subtle style (e.g. "Expires 12/26"). Wired into the field's aria-describedby. */
+  hint: string;
+  /** Optional leading icon name shown beside the value (e.g. a lock or card-brand glyph). Lazily creates a single icon-ui child. */
+  icon: string;
+  /** The field caption. Names the whole field for assistive tech. */
+  label: string;
+  /** 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. */
+  value: string;
+  /** 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. */
+  variant: 'default' | 'masked';
+}

package/components/display-field/display-field.examples.md

@@ -0,0 +1,44 @@
+# display-field — Examples
+
+A display-only labeled value. No input semantics (no focus, no
+contenteditable, no form participation). For an editable field use
+`field-ui` + `input-ui`; for a metric use `stat-ui`; for many read-only
+pairs use `description-list-ui`.
+
+## Basic
+
+```html
+<display-field-ui label="Account ID" value="acct_1Q9xK2"></display-field-ui>
+```
+
+## Masked value
+
+```html
+<display-field-ui
+  label="Card on file"
+  value="•••• •••• •••• 4242"
+  variant="masked"></display-field-ui>
+```
+
+## With a leading icon and a hint
+
+```html
+<display-field-ui
+  label="Card on file"
+  value="•••• 4242"
+  variant="masked"
+  icon="lock"
+  hint="Expires 12/26"></display-field-ui>
+```
+
+## Hosting a third-party element (Stripe Element)
+
+Slot the foreign element as the default child; it takes the value region
+under the label. The host's `role="group"` + `aria-labelledby` names it for
+assistive tech.
+
+```html
+<display-field-ui label="Card number">
+  <div id="card-element"><!-- stripe.elements().create('card').mount('#card-element') --></div>
+</display-field-ui>
+```

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 };