@adia-ai/web-components 0.7.22 → 0.7.24

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+- **`button-ui` (`components/button/`) — child text now labels the button, same as `text=`.** A label written as child text (`<button-ui>Save</button-ui>`, no `text=` attr) was treated as icon-only and collapsed to a square icon slot with the text clipped — the collapse rule keyed off `:scope:not([text]), :scope[text=""]`, which can't see text-node children. `render()` now scans child nodes for non-whitespace text and reflects a JS-derived `[data-icon-only]` state **only** when there is neither a `text=` value nor child text; `button.css` keys its collapse + inline-level rules off `[data-icon-only]` instead of the `[text]` selectors. A child-text button now renders at full content width, identical to `text="Save"`, while a genuine `<button-ui icon="…">` still collapses; the icon-only accessible-name warning is re-gated to respect child text. Adds an `icon-only` state to `button.yaml`; `button.a2ui.json` + `dist/web-components.min.{js,css}` + `.sheet.js` (and the `theme-provider` / `everything` bundles) regenerated. (journal 2026-06-30 §1)
+
+### Changed
+- **`accordion-ui` (`components/accordion/`) — normal block-flow gap, borderless items.** `--accordion-gap` changed from `0` to `var(--a-gap)`, so stacked items separate with the same canonical block-flow stack gap `col-ui` / `row-ui` / `grid-ui` use instead of butting together. The per-item `border-bottom` separator — with its `--accordion-item-border` token and the `:last-child` border reset — was removed for a clean borderless stack. Visible re-spacing, no public-API change (PATCH). (journal 2026-06-30 §2)
+
 ## [0.7.22] — 2026-06-16
 
 ### Changed

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/accordion/accordion.css

@@ -9,7 +9,11 @@
 /* ── Container ── */
 @scope (accordion-ui) {
   :where(:scope) {
-    --accordion-gap: 0;
+    /* Normal block-flow gap between items — the same ambient stack gap
+       col-ui/row-ui/grid-ui read (`--a-gap`, base `--a-gap-md`). Items now
+       separate by this gap rather than by flush hairline dividers, so the
+       item @scope below carries no inter-item border. */
+    --accordion-gap: var(--a-gap);
   }
 
   :scope {
@@ -24,7 +28,6 @@
 @scope (accordion-item-ui) {
   :where(:scope) {
     /* ── Colors ── */
-    --accordion-item-border:          var(--a-border-subtle);
     --accordion-item-header-fg:       var(--a-fg-subtle);
     --accordion-item-header-fg-hover: var(--a-fg-strong);
     --accordion-item-header-bg-hover: var(--a-bg-muted);
@@ -53,11 +56,6 @@
   :scope {
     box-sizing: border-box;
     display: block;
-    border-bottom: 1px solid var(--accordion-item-border);
-  }
-
-  :scope:last-child {
-    border-bottom: none;
   }
 
   /* ── Header ── */

package/components/button/button.a2ui.json

@@ -145,6 +145,11 @@
         "description": "Default, ready for interaction.",
         "name": "idle"
       },
+      {
+        "description": "No text label — neither the `text` attr nor non-whitespace child text. Reflected by render() as `[data-icon-only]`; the CSS collapses the button to a square icon slot (zero inline padding, width = height) and keeps it inline-level. A button labeled by child text (`<button-ui>Save</button-ui>`) is NOT icon-only and renders at full content width, same as `text=`.",
+        "attribute": "data-icon-only",
+        "name": "icon-only"
+      },
       {
         "description": "Non-interactive; dimmed.",
         "attribute": "disabled",

package/components/button/button.class.js

@@ -82,6 +82,24 @@ export class UIButton extends UIElement {
       }
     }
 
+    // A button is "labeled" by EITHER the [text] attribute (rendered via the
+    // ::after in button.css) OR direct light-DOM child text — `<button-ui>Save
+    // </button-ui>`, which renders as-is in the flex row. Both are valid labels;
+    // only a button with NEITHER is a square icon-only (or empty) button. Detect
+    // child text by scanning direct text nodes — the auto-stamped <icon-ui>
+    // children are element nodes (nodeType 1), so they're correctly ignored.
+    // Reflect the result as [data-icon-only]: button.css keys its collapse +
+    // inline-level rules off it (mirrors the derived-marker pattern in
+    // page.class.js's [data-header-stuck]). Child-text edits don't re-trigger
+    // render() (textContent isn't reactive — see the static-properties note
+    // above), but light-DOM children are parsed before the first render, so the
+    // initial classification is correct; toolbar spillover toggles the [text]
+    // attr (reactive), which re-runs this and keeps the marker in sync.
+    const hasChildText = Array.from(this.childNodes).some(
+      (n) => n.nodeType === 3 && n.textContent.trim() !== '',
+    );
+    this.toggleAttribute('data-icon-only', !this.text && !hasChildText);
+
     // FEEDBACK-15: warn when text= begins with a symbol that icon= already
     // renders (e.g. text="+ New Claim" icon="plus" → a doubled "+"). One-shot
     // per element via WeakSet; warning-only — the button still renders. The
@@ -113,7 +131,9 @@ export class UIButton extends UIElement {
     //       so the bug class is diagnosable in dev without firing every
     //       render tick. The warning is suppressed via a one-shot
     //       WeakSet so subsequent re-renders stay quiet.
-    if (this.icon && !this.text) {
+    if (this.icon && !this.text && !hasChildText) {
+      // (child text is itself the accessible name natively, so a button with
+      //  light-DOM text is NOT icon-only and never warns here.)
       const ariaLabel = this.getAttribute('aria-label');
       const ariaLabelledBy = this.getAttribute('aria-labelledby');
       const titleAttr = this.getAttribute('title');

package/components/button/button.css

@@ -148,10 +148,11 @@ button-ui[variant="ghost"][color="warning"]:not([disabled]):hover   { --button-f
   }
 
   /* Display convention (ADR-0037): block-level by default — a text button used
-     directly in block flow fills its container. Icon-only buttons (no [text])
-     stay inline-level, and [inline] forces inline for any button. Inside
-     row-ui/col-ui/grid-ui this is moot (flex/grid items are blockified). */
-  :scope:not([text]) { display: inline-flex; }
+     directly in block flow fills its container. Icon-only buttons (no text
+     label — see [data-icon-only] below) stay inline-level, and [inline] forces
+     inline for any button. Inside row-ui/col-ui/grid-ui this is moot (flex/grid
+     items are blockified). */
+  :scope[data-icon-only] { display: inline-flex; }
   :scope[inline] { display: inline-flex; }
 
   /* Trailing icon slot — for forward-affordance carets ("Next →"), distinct
@@ -284,8 +285,13 @@ button-ui[variant="ghost"][color="warning"]:not([disabled]):hover   { --button-f
     cursor: not-allowed;
   }
 
-  /* Icon-only (no text) */
-  :scope:not([text]), :scope[text=""] {
+  /* Icon-only / empty — no text label from EITHER the [text] attr or direct
+     child text. The JS render() reflects [data-icon-only] (set only when
+     !text AND no non-whitespace child text), which subsumes the old
+     :not([text]) / [text=""] selectors AND correctly treats
+     `<button-ui>Save</button-ui>` as a labeled (full-width) button rather than
+     collapsing it into a square. */
+  :scope[data-icon-only] {
     --button-px: 0;
     width: var(--button-height);
   }

package/components/button/button.yaml

@@ -112,6 +112,14 @@ slots:
 states:
   - name: idle
     description: Default, ready for interaction.
+  - name: icon-only
+    description: >-
+      No text label — neither the `text` attr nor non-whitespace child text.
+      Reflected by render() as `[data-icon-only]`; the CSS collapses the button
+      to a square icon slot (zero inline padding, width = height) and keeps it
+      inline-level. A button labeled by child text (`<button-ui>Save</button-ui>`)
+      is NOT icon-only and renders at full content width, same as `text=`.
+    attribute: data-icon-only
   - name: disabled
     description: Non-interactive; dimmed.
     attribute: disabled

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>
+```