@adia-ai/web-components 0.7.23 → 0.7.25

package/components/accordion/accordion.class.js

@@ -38,6 +38,12 @@ export class UIAccordion extends UIElement {
 
   static properties = {
     multiple: { type: Boolean, default: false, reflect: true },
+    // `reflect: true` is load-bearing: the CSS ancestor selector
+    // (accordion.css `@scope (accordion-item-ui)`) matches
+    // `accordion-ui[variant="contained"]`. Default 'flat' ⇒ absent-attribute
+    // = current behavior. No render/JS logic keys off it — inheritance of
+    // the contained posture into child items is pure CSS.
+    variant: { type: String, default: 'flat', reflect: true }, // 'flat' | 'contained'
   };
 
   static template = () => null;
@@ -70,6 +76,10 @@ export class UIAccordionItem extends UIElement {
   static properties = {
     text: { type: String,  default: '', reflect: true },
     open: { type: Boolean, default: false, reflect: true },
+    // Per-item posture override against the host accordion-ui's [variant]
+    // (see UIAccordion.variant above). Default 'flat'; CSS-only, pure
+    // token re-point in contained (accordion.css).
+    variant: { type: String, default: 'flat', reflect: true }, // 'flat' | 'contained'
   };
 
   static template = () => null;
@@ -77,13 +87,24 @@ export class UIAccordionItem extends UIElement {
   #bound = false;
 
   connected() {
-    // Stamp header if not present
-    if (!this.querySelector('[slot="header"]')) {
+    // Stamp header if not present; otherwise restore the disclosure caret
+    // (FN-1) — a consumer's custom [slot="header"] previously suppressed it
+    // entirely because the caret only ever got stamped alongside the header.
+    const existingHeader = this.querySelector('[slot="header"]');
+    if (!existingHeader) {
       const header = document.createElement('div');
       header.setAttribute('slot', 'header');
+      // SPEC-R8: the auto-stamped header was mouse-only (no tabindex/keydown).
+      // Make it keyboard-operable; a consumer-authored header keeps owning
+      // its own semantics (data-autofocusable marks the header WE own).
+      header.setAttribute('tabindex', '0');
+      header.setAttribute('role', 'button');
+      header.setAttribute('aria-expanded', 'false');
+      header.dataset.autofocusable = '';
 
       const label = document.createElement('span');
       label.setAttribute('slot', 'header-text');
+      label.dataset.autolabel = ''; // marks THIS label as prop-driven (FN-2)
       header.appendChild(label);
 
       const caret = document.createElement('icon-ui');
@@ -92,6 +113,13 @@ export class UIAccordionItem extends UIElement {
       header.appendChild(caret);
 
       this.prepend(header);
+    } else if (!existingHeader.querySelector('[slot="caret"]')) {
+      // Scope to the HEADER, not the whole item — a caret placed in
+      // [slot="body"] must not suppress this (Finding 10).
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('name', 'caret-down');
+      caret.setAttribute('slot', 'caret');
+      existingHeader.appendChild(caret); // restore the disclosure signifier
     }
 
     // Stamp content wrapper if not present
@@ -112,17 +140,26 @@ export class UIAccordionItem extends UIElement {
     if (!this.#bound) {
       this.#bound = true;
       this.addEventListener('click', this.#onClick);
+      this.addEventListener('keydown', this.#onKeydown);
     }
   }
 
   disconnected() {
     this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKeydown);
     this.#bound = false;
   }
 
   render() {
-    const label = this.querySelector('[slot="header-text"]');
+    // Only the auto-stamped label follows [text] — an authored
+    // [slot="header-text"] (no data-autolabel marker) is never touched (FN-2).
+    const label = this.querySelector('[slot="header-text"][data-autolabel]');
     if (label) label.textContent = this.text;
+
+    // Keep aria-expanded in sync on the auto-stamped header — `open` is a
+    // reactive prop, so render() re-runs on every toggle (SPEC-R8).
+    const hdr = this.querySelector('[slot="header"][data-autofocusable]');
+    if (hdr) hdr.setAttribute('aria-expanded', String(this.open));
   }
 
   #onClick = (e) => {
@@ -140,4 +177,17 @@ export class UIAccordionItem extends UIElement {
       detail: { open: this.open },
     }));
   };
+
+  // SPEC-R8: Enter/Space on the auto-stamped header toggles it. Scoped to
+  // OUR stamped header only (data-autofocusable) — never a consumer control
+  // inside a custom header. Routes through header.click() → #onClick, so
+  // there is exactly one toggle code path (DRY).
+  #onKeydown = (e) => {
+    const header = this.querySelector('[slot="header"][data-autofocusable]');
+    if (!header || e.target !== header) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault(); // Space: no page scroll
+      header.click();
+    }
+  };
 }

package/components/accordion/accordion.css

@@ -27,6 +27,16 @@
 /* ── Item ── */
 @scope (accordion-item-ui) {
   :where(:scope) {
+    /* ── Surface (variant) ──
+       Flat-pixel-exact defaults (SPEC-R2/AC-2): transparent bg, no border,
+       no header/body divider, zero body top-padding — byte-identical to the
+       pre-variant item. Re-pointed by :scope[variant="contained"] below
+       (SPEC-R1/AC-1); consumer-overridable in BOTH postures (SPEC-R3/AC-3). */
+    --accordion-item-bg:      transparent;
+    --accordion-item-border:  none;
+    --accordion-item-divider: none;
+    --accordion-item-body-pt: 0;
+
     /* ── Colors ── */
     --accordion-item-header-fg:       var(--a-fg-subtle);
     --accordion-item-header-fg-hover: var(--a-fg-strong);
@@ -51,11 +61,58 @@
 
     /* ── State ── */
     --accordion-item-focus-ring:      var(--a-focus-ring);
+
+    /* Header-scoped surface tokens — flat defaults keep today's look; contained
+       re-points them (pill flush + inner ring off, ring relocates to the item).
+       Kept as tokens (not [slot="header"] rules under an accordion-ui-led selector)
+       so slot-vocab-vs-css attributes the header slot to accordion-item.yaml. */
+    --accordion-item-header-radius:        var(--accordion-item-radius);
+    --accordion-item-header-focus-shadow:  var(--accordion-item-focus-ring);
   }
 
   :scope {
     box-sizing: border-box;
     display: block;
+    background: var(--accordion-item-bg);
+    border: var(--accordion-item-border);
+    border-radius: var(--accordion-item-radius);   /* invisible in flat: no border/bg */
+  }
+
+  /* ═══════ Variant: contained (token-only re-point + sanctioned layout exception) ═══════
+     Own variant OR inherited from a contained host. CHILD combinator (`>`) so a FLAT
+     accordion nested inside a contained one does NOT leak contained styling to the inner
+     items (Finding 4); items are canonically direct children. Per-item opt-out: [variant="flat"].
+     Two layout touches (overflow clip + surface focus-ring relocation) are documented
+     exceptions in component-token-contract.md's sanctioned-exception table; bg/border/divider/
+     body-pt AND the header pill-radius / inner-ring (via --accordion-item-header-*) stay pure
+     token re-points.
+     NB: the inherited form MUST use `:scope` (not a literal `accordion-item-ui`) — under
+     @scope, only `:scope` may reference the `accordion-ui` ancestor to its LEFT; a literal
+     tag is confined to the scope donut and would not match the outside ancestor. */
+  :scope[variant="contained"],
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]) {
+    --accordion-item-bg:                  var(--a-bg-subtle);
+    --accordion-item-border:              1px solid var(--a-border-subtle);
+    --accordion-item-divider:             1px solid var(--a-border-subtle);
+    --accordion-item-body-pt:             var(--a-space-2);
+    --accordion-item-header-radius:       0;      /* pill corners flush to the surface (Finding 8) */
+    --accordion-item-header-focus-shadow: none;   /* inner ring off; surface ring below (Finding 2) */
+  }
+
+  :scope[variant="contained"],
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]) {
+    overflow: hidden;                              /* pill + body clip to --accordion-item-radius */
+  }
+
+  /* Focus ring follows the SURFACE radius (AC-4); the item's own box-shadow is NOT clipped by
+     its own overflow:hidden. `:has(> :focus-visible)` fires when the header — the item's only
+     focusable DIRECT child (a body-nested control is a grandchild) — is focused, WITHOUT naming
+     [slot="header"] in an accordion-ui-led selector. Covers BOTH own-variant and host-inherited
+     forms; the inner ring is suppressed via --accordion-item-header-focus-shadow → none, so no
+     double ring in the attribute-less-item case (Finding 2). */
+  :scope[variant="contained"]:has(> :focus-visible),
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]):has(> :focus-visible) {
+    box-shadow: var(--accordion-item-focus-ring);
   }
 
   /* ── Header ── */
@@ -67,7 +124,7 @@
     justify-content: space-between;
     gap: var(--accordion-item-header-gap);
     padding: var(--accordion-item-py) var(--accordion-item-px);
-    border-radius: var(--accordion-item-radius);
+    border-radius: var(--accordion-item-header-radius);   /* flat: = --accordion-item-radius; contained: 0 */
     cursor: pointer;
     user-select: none;
     font-size: var(--accordion-item-header-font);
@@ -90,7 +147,7 @@
   }
 
   :scope [slot="header"]:focus-visible {
-    box-shadow: var(--accordion-item-focus-ring);
+    box-shadow: var(--accordion-item-header-focus-shadow);   /* flat: = --accordion-item-focus-ring; contained: none (surface ring instead) */
   }
 
   :scope[open] [slot="header"] {
@@ -125,6 +182,7 @@
 
   :scope[open] [slot="body"] {
     display: block;
-    padding: 0 var(--accordion-item-px) var(--accordion-item-py);
+    padding: var(--accordion-item-body-pt) var(--accordion-item-px) var(--accordion-item-py);
+    border-top: var(--accordion-item-divider);   /* default `none` in flat → invisible, zero layout (Finding 3) */
   }
 }

package/components/accordion/accordion.d.ts

@@ -29,6 +29,14 @@ export type AccordionToggleEvent = CustomEvent<AccordionToggleEventDetail>;
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
   multiple: boolean;
+  /** Visual posture, inherited by child accordion-item-ui elements unless a
+child sets its own [variant]. `flat` (default) renders items with no
+chrome — settings pages, FAQ blocks, anywhere the accordion sits
+directly on the page canvas. `contained` gives every item a bounded
+surface (background + border + radius spanning header and open body,
+plus a divider between them when open) — the composition to reach for
+when nesting the accordion inside <card-ui>. */
+  variant: 'flat' | 'contained';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
@@ -50,6 +58,10 @@ export class UIAccordionItem extends UIElement {
   open: boolean;
   /** Header text — the clickable label that toggles the section. */
   text: string;
+  /** Per-item posture override. Items normally inherit their host
+accordion-ui's [variant] — set this directly on ONE item only to
+opt it out of (`flat`) or into (`contained`) the host's posture. */
+  variant: 'flat' | 'contained';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/accordion/accordion.yaml

@@ -24,6 +24,21 @@ props:
     description: Allow multiple panels to be open simultaneously
     type: boolean
     default: false
+  variant:
+    description: |-
+      Visual posture, inherited by child accordion-item-ui elements unless a
+      child sets its own [variant]. `flat` (default) renders items with no
+      chrome — settings pages, FAQ blocks, anywhere the accordion sits
+      directly on the page canvas. `contained` gives every item a bounded
+      surface (background + border + radius spanning header and open body,
+      plus a divider between them when open) — the composition to reach for
+      when nesting the accordion inside <card-ui>.
+    type: string
+    default: flat
+    enum:
+      - flat
+      - contained
+    reflect: true
 events:
   toggle:
     description: Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).
@@ -49,6 +64,8 @@ a2ui:
       reason: 'Decision rule vs tabs.'
     - rule: 'Item ordering is DOM-order; no auto-sort.'
       reason: 'Author-controlled order.'
+    - rule: 'Set variant="contained" for a bounded per-item surface (background, border, radius, and an open-state divider) — the composition to reach for when nesting inside <card-ui>. Default variant="flat" (no chrome) suits settings pages and FAQ blocks sitting on the page canvas.'
+      reason: 'Posture selection guidance (flat vs contained).'
 anti_patterns: []
 examples:
   - name: accordion-settings

package/components/code/code.class.js

@@ -26,7 +26,7 @@
  * CodeMirror 6 is lazy-loaded and mounted in place of `<pre><code>` for
  * syntax-highlighted rendering. Phase 1 shipped read-only; Phase 2 added
  * `[editable]`; Phase 3 added lint + form-association (see
- * `docs/specs/code-editor.md §12`).
+ * `.claude/docs/specs/code-editor.md §12`).
  *
  * Form participation — editable instances are Form-Associated Custom
  * Elements (FACE). Set `name`, `required`, `disabled`, `readonly` to

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