@adia-ai/web-components 0.8.40 → 0.8.41

package/components/input/input.class.js

@@ -148,12 +148,7 @@ export class UIInput extends UIFormElement {
     const trailingNodes = logicalSlotted(this, 'trailing');
 
     if (!this.querySelector('[slot="text"]')) {
-      const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';
-      this.innerHTML = this.#shellHTML(labelId);
-      // innerHTML wiped the consumer-supplied leading/trailing nodes; re-attach
-      // them into the field at the right positions. Order matches the JSDoc:
-      //   prefix → leading → label → text → suffix → trailing → controls
-      this.#installAffordances(leadingNodes, trailingNodes);
+      this.#buildShell(leadingNodes, trailingNodes);
     }
 
     this.#textEl  = this.querySelector('[slot="text"]');
@@ -200,6 +195,64 @@ export class UIInput extends UIFormElement {
     }
   }
 
+  #buildShell(leadingNodes, trailingNodes) {
+    const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';
+    this.innerHTML = this.#shellHTML(labelId);
+    // innerHTML wiped the consumer-supplied leading/trailing nodes; re-attach
+    // them into the field at the right positions. Order matches the JSDoc:
+    //   prefix → leading → label → text → suffix → trailing → controls
+    this.#installAffordances(leadingNodes, trailingNodes);
+  }
+
+  /**
+   * Post-connect `type` reconciliation (gh#1332 review follow-up). The shell
+   * is built once at connect, but `type` is reactive and reflected — since
+   * number-mode CSS now keys off the host's [type="number"] directly, a
+   * text↔number flip after connect would restyle without restructuring
+   * (role, inputmode, stepper controls, beforeinput filter all stale).
+   * Rebuild the shell + listeners when the built mode disagrees with the
+   * live property. No-op on every render where the modes already agree.
+   */
+  #reconcileTypeMode() {
+    if (this.#isNativePassword || !this.#textEl) return;
+    const builtNumberMode = !!this.querySelector(':scope > [slot="field"] [data-controls]');
+    if (builtNumberMode === this.#isNumberMode) return;
+
+    // Unwire the old surface, capture consumer affordances from inside the
+    // live field (logicalSlotted won't re-match nodes already moved there).
+    this.#textEl.removeEventListener('input',    this.#onInput);
+    this.#textEl.removeEventListener('keydown',  this.#onKeydown);
+    this.#textEl.removeEventListener('blur',     this.#onBlur);
+    this.#textEl.removeEventListener('focus',    this.#onFocus);
+    this.#textEl.removeEventListener('paste',    this.#onPaste);
+    this.#textEl.removeEventListener('beforeinput', this.#onBeforeInput);
+    const field = this.querySelector(':scope > [slot="field"]');
+    const leadingNodes  = field ? [...field.querySelectorAll(':scope > [slot="leading"]')]  : [];
+    const trailingNodes = field ? [...field.querySelectorAll(':scope > [slot="trailing"]')] : [];
+
+    this.#buildShell(leadingNodes, trailingNodes);
+    this.setAttribute('role', this.#isNumberMode ? 'spinbutton' : 'textbox');
+    this.#textEl  = this.querySelector('[slot="text"]');
+    this.#labelEl = this.querySelector('[slot="label"]');
+    this.#upBtn   = this.querySelector('[data-step="up"]');
+    this.#downBtn = this.querySelector('[data-step="down"]');
+    if (this.#textEl) {
+      this.#textEl.addEventListener('input',    this.#onInput);
+      this.#textEl.addEventListener('keydown',  this.#onKeydown);
+      this.#textEl.addEventListener('blur',     this.#onBlur);
+      this.#textEl.addEventListener('focus',    this.#onFocus);
+      this.#textEl.addEventListener('paste',    this.#onPaste);
+      if (this.#isNumberMode) {
+        this.#textEl.addEventListener('beforeinput', this.#onBeforeInput);
+      }
+    }
+    this.#upBtn?.addEventListener('pointerdown', this.#onStepperUpDown);
+    this.#downBtn?.addEventListener('pointerdown', this.#onStepperDownDown);
+    if (this.prefix || this.suffix) {
+      whenIconRegistryReady.then(() => this.#promoteAffixes());
+    }
+  }
+
   #shellHTML(labelId) {
     const prefix  = this.prefix ? `<span slot="prefix">${renderAffix(this.prefix)}</span>` : '';
     const label   = this.label  ? `<span slot="label" id="${labelId}">${this.label}</span>` : '';
@@ -234,8 +287,11 @@ export class UIInput extends UIFormElement {
                    icon="caret-down" data-step="down" aria-label="Decrease"></button-ui>
       </span>` : '';
 
+    // No private data-number mirror on the field div — number-mode CSS keys
+    // off the declared, reflected host [type="number"] directly (gh#1332
+    // Category A; select-ui data-multi-chips precedent).
     return `
-      <div slot="field"${this.#isNumberMode ? ' data-number' : ''}>
+      <div slot="field">
         ${prefix}${label}${editable}${suffix}${controls}
       </div>
     `;
@@ -372,6 +428,7 @@ export class UIInput extends UIFormElement {
 
   render() {
     if (!this.#textEl) return;
+    this.#reconcileTypeMode();
 
     const text = this.value ?? '';
 

package/components/input/input.css

@@ -191,10 +191,10 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
      absolutely against the field's inline-end edge so it NEVER affects
      the field's flex-sized height — number-mode inputs share the same
      24/30/36px (sm/md/lg) baseline as text/email/password/etc. */
-  [data-number] [slot="text"] {
+  :scope[type="number"] [slot="field"] [slot="text"] {
     text-align: end;
     font-variant-numeric: tabular-nums;
-    font-weight: var(--a-weight-medium, 500);
+    font-weight: var(--a-weight-medium);
     /* Reserve space for the absolutely-positioned controls column so the
        value never collides with the stepper buttons. */
     padding-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
@@ -202,7 +202,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
 
   /* Suffix sits flush after the value in number mode (no auto margin so
      the value+suffix pair stays right-aligned together). */
-  [data-number] [slot="suffix"] {
+  :scope[type="number"] [slot="field"] [slot="suffix"] {
     margin-inline-start: 0;
     /* Reserve space for the absolutely-positioned controls column so the
        suffix never collides with the stepper buttons. The padding moves
@@ -210,11 +210,11 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
        — only one element needs the reservation since they're adjacent. */
     margin-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
   }
-  [data-number]:has([slot="suffix"]) [slot="text"] {
+  :scope[type="number"] [slot="field"]:has([slot="suffix"]) [slot="text"] {
     padding-inline-end: 0;
   }
 
-  [data-number] {
+  :scope[type="number"] [slot="field"] {
     position: relative;
   }
 
@@ -230,7 +230,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     overflow: hidden;
   }
 
-  [data-number] [slot="controls"] button-ui {
+  :scope[type="number"] [slot="field"] [slot="controls"] button-ui {
     /* Defeat button-ui's intrinsic min-height (driven by --button-height) so
        its content can't push past half the column height. Padding + border
        are zeroed; the divider between the two buttons comes from the
@@ -256,14 +256,14 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
      because its own `:where(:scope)` declaration of --icon-size wins over
      any value inherited from its parent button-ui. Tying it to
      --input-height keeps the caret proportional across sm/md/lg. */
-  [data-number] [slot="controls"] icon-ui {
+  :scope[type="number"] [slot="field"] [slot="controls"] icon-ui {
     --icon-size: calc(var(--input-height) * 0.4);
   }
-  [data-number] [slot="controls"] button-ui:hover {
+  :scope[type="number"] [slot="field"] [slot="controls"] button-ui:hover {
     --button-bg: var(--a-ui-bg-hover);
     --button-fg: var(--a-ui-text);
   }
-  [data-number] [slot="controls"] button-ui[disabled] {
+  :scope[type="number"] [slot="field"] [slot="controls"] button-ui[disabled] {
     --button-fg: var(--a-ui-text-disabled);
     pointer-events: none;
   }
@@ -273,11 +273,11 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
      field radius cleanly. The divider between the two buttons is the
      inline-start border on the column + the bottom-border on the upper
      button. */
-  [data-number] [slot="controls"] button-ui:first-child {
+  :scope[type="number"] [slot="field"] [slot="controls"] button-ui:first-child {
     border-bottom: 1px solid var(--input-border);
     border-start-end-radius: calc(var(--input-radius) - 1px);
   }
-  [data-number] [slot="controls"] button-ui:last-child {
+  :scope[type="number"] [slot="field"] [slot="controls"] button-ui:last-child {
     border-end-end-radius: calc(var(--input-radius) - 1px);
   }
 
@@ -287,8 +287,8 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     margin-inline-end: 0;
     border-inline-start: none;
   }
-  :scope[raw] [data-number] [slot="controls"] button-ui:first-child,
-  :scope[raw] [data-number] [slot="controls"] button-ui:last-child {
+  :scope[raw][type="number"] [slot="field"] [slot="controls"] button-ui:first-child,
+  :scope[raw][type="number"] [slot="field"] [slot="controls"] button-ui:last-child {
     border-bottom: none;
     border-radius: 0;
   }
@@ -373,7 +373,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
      for the stepper column so it doesn't overlap. (controls is
      absolutely positioned at inset-inline-end: 0; trailing sits in the
      flex flow.) Same pattern as [slot="suffix"] in number mode. */
-  [data-number]:has(> [slot="trailing"]) > [slot="trailing"] {
+  :scope[type="number"] [slot="field"]:has(> [slot="trailing"]) > [slot="trailing"] {
     margin-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
   }
 

package/components/input/input.d.ts

@@ -1,20 +1,25 @@
 /**
- * `<input-ui>` — Text + email + password + number + tel + url + search input.
+ * `<input-ui>` — Text + email + password + number + tel + url input.
  *
  * @see https://ui-kit.exe.xyz/site/components/input
  */
 
 import { UIFormElement } from '../../core/form.js';
 
-/** Native HTML input types this primitive supports. */
+/**
+ * Native HTML input types this primitive actually implements. Does NOT
+ * cover date/datetime-local/time/month/week/color/search — those never
+ * rendered a native affordance on this primitive (v0.9.0, gh#1363 B10);
+ * route to CalendarPicker/DatetimePicker/TimePicker/ColorInput/Search
+ * instead.
+ */
 export type UIInputType =
   | 'text'
   | 'email'
   | 'password'
   | 'number'
   | 'tel'
-  | 'url'
-  | 'search';
+  | 'url';
 
 export interface InputChangeEventDetail {
   value: string;

package/components/input/input.yaml

@@ -23,8 +23,19 @@ props:
     type: string
     default: ''
   type:
-    description: Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper
-      buttons (no native input). All other types use plain contenteditable.
+    description: >-
+      Input type. `password` wraps a native `<input>` for disc masking;
+      `number` renders a contenteditable + stepper buttons (no native
+      input). `text`/`email`/`tel`/`url` use plain contenteditable.
+      input-ui does NOT implement date/time/color/search affordances —
+      those HTML5 type values render as a plain contenteditable with no
+      calendar, clock, swatch, or search affordance (first-pass-VALID
+      against this enum historically, but functionally broken generation
+      output). Use the owning primitive instead — CalendarPicker for date
+      (+ month/week, no dedicated granularity primitive exists),
+      DatetimePicker for datetime-local, TimePicker for time,
+      ColorInput/ColorPicker for color, Search for search. See
+      anti_patterns.
     type: string
     default: text
     enum:
@@ -34,13 +45,6 @@ props:
     - number
     - tel
     - url
-    - search
-    - date
-    - datetime-local
-    - time
-    - month
-    - week
-    - color
   required:
     description: Marks the field as required for form validation. Sets aria-required.
     type: boolean
@@ -282,7 +286,71 @@ a2ui:
       primitive ALSO fires a bubbling `submit` event on Enter
       (unconditional, no opt-in attribute); <chat-input-ui> simply
       builds on that semantic.
-anti_patterns: []
+    - >-
+      input-ui's `type` enum covers only the modes it actually implements
+      — text/email/password/number/tel/url (gh#1363 B10). Never
+      set [type] to an HTML5 value input-ui doesn't render — route
+      date/time/color/search intents to the owning primitive instead:
+      CalendarPicker, DatetimePicker, TimePicker, ColorInput (or
+      ColorPicker directly), Search. See anti_patterns.
+anti_patterns:
+  - wrong: |
+      {"component": "Input", "type": "date"}
+    why: |
+      input-ui's `type` enum no longer includes "date" (gh#1363
+      B10) — it never rendered a native date picker, just a plain
+      contenteditable surface with no calendar affordance. Use
+      CalendarPicker for single-date input.
+    fix: |
+      {"component": "CalendarPicker"}
+  - wrong: |
+      {"component": "Input", "type": "datetime-local"}
+    why: |
+      Same gap as "date" — no native datetime picker rendered. Use
+      DatetimePicker for combined date + time input.
+    fix: |
+      {"component": "DatetimePicker"}
+  - wrong: |
+      {"component": "Input", "type": "time"}
+    why: |
+      Same gap as "date" — no native time picker rendered. Use
+      TimePicker for time-of-day input.
+    fix: |
+      {"component": "TimePicker"}
+  - wrong: |
+      {"component": "Input", "type": "month"}
+    why: |
+      No native month picker rendered, and no dedicated month-granularity
+      primitive exists in the catalog. CalendarPicker (day granularity)
+      is the closest routed primitive.
+    fix: |
+      {"component": "CalendarPicker"}
+  - wrong: |
+      {"component": "Input", "type": "week"}
+    why: |
+      No native week picker rendered, and no dedicated week-granularity
+      primitive exists in the catalog. CalendarPicker (day granularity)
+      is the closest routed primitive.
+    fix: |
+      {"component": "CalendarPicker"}
+  - wrong: |
+      {"component": "Input", "type": "color"}
+    why: |
+      No native color swatch/picker rendered — just a plain text
+      surface. Use ColorInput for a compact form-bearing swatch +
+      popover, or ColorPicker directly for the full OKLCH picker
+      surface.
+    fix: |
+      {"component": "ColorInput"}
+  - wrong: |
+      {"component": "Input", "type": "search"}
+    why: |
+      No search icon or clear affordance rendered — plain
+      contenteditable, functionally identical to the default text
+      type. Use Search for the dedicated magnifying-glass + clear +
+      debounced-search-event primitive.
+    fix: |
+      {"component": "Search"}
 examples:
 - name: quantity-stepper
   description: Number input with [+]/[-] stepper buttons, min/max bounds, and a quantity label. Use for product quantity,
@@ -391,3 +459,8 @@ related:
 - table
 - pagination
 - check-box
+- search
+- calendar-picker
+- datetime-picker
+- time-picker
+- color-input

package/components/inspector/inspector.a2ui.json

@@ -46,6 +46,7 @@
       "inspector"
     ],
     "name": "UIInspector",
+    "parts": {},
     "related": [
       "A2uiRoot",
       "EditorSidebar",

package/components/integration-card/integration-card.a2ui.json

@@ -150,6 +150,7 @@
       "tile"
     ],
     "name": "UIIntegrationCard",
+    "parts": {},
     "related": [
       "card",
       "badge",

package/components/kbd/kbd.a2ui.json

@@ -56,6 +56,7 @@
       "keybinding"
     ],
     "name": "UIKbd",
+    "parts": {},
     "related": [
       "grid"
     ],

package/components/link/link.a2ui.json

@@ -79,7 +79,7 @@
       "❌ `<link-ui>` with no `href` AND no `press` handler — a link to nowhere is a bug. Either set `href` or wire a navigate action handler.",
       "❌ `<link-ui>` for form submission — submission is a button concern. Use `<button-ui type=\"submit\">`."
     ],
-    "category": "content",
+    "category": "display",
     "composes": [],
     "events": {
       "press": {
@@ -121,6 +121,7 @@
       "url"
     ],
     "name": "UILink",
+    "parts": {},
     "related": [
       "Button",
       "NavItem",

package/components/link/link.yaml

@@ -3,7 +3,7 @@ name: UILink
 tag: link-ui
 status: stable
 component: Link
-category: content
+category: display
 version: 1
 description: |
   Inline navigation primitive — semantic `<a href>` wrapper. Use for

package/components/list/list-item.a2ui.json

@@ -24,6 +24,11 @@
       "description": "Optional leading icon name (Phosphor).",
       "type": "string"
     },
+    "selected": {
+      "description": "Whether this row is the current selection. Managed by the parent <list-ui>[selectable] — don't set directly; the parent's [selectedKey] is the single source of truth (ADR-0056).",
+      "type": "boolean",
+      "default": false
+    },
     "text": {
       "description": "Primary text. Renders as semibold inline body.",
       "type": "string"
@@ -34,6 +39,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "List"
+    ],
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
@@ -47,6 +55,7 @@
       "row"
     ],
     "name": "UIListItem",
+    "parts": {},
     "related": [
       "List",
       "NavItem",

package/components/list/list-item.yaml

@@ -28,6 +28,14 @@ props:
   description:
     description: Secondary line below the primary text. Subtle color.
     type: string
+  selected:
+    description: >-
+      Whether this row is the current selection. Managed by the parent
+      <list-ui>[selectable] — don't set directly; the parent's
+      [selectedKey] is the single source of truth (ADR-0056).
+    type: boolean
+    default: false
+    reflect: true
 
 slots:
   text:
@@ -78,6 +86,8 @@ related:
   - TreeItem
 
 a2ui:
+  allowedParents:
+    - List
   rules:
     - rule: 'Child of <list-ui> — one row of generic-list content.'
       reason: 'Cluster contract.'
@@ -85,3 +95,5 @@ a2ui:
       reason: 'Per-context list-row primitives — list-item is generic.'
     - rule: 'Interactive list-items should have role=''button'' or be wrapped in <button-ui>; default is non-interactive.'
       reason: 'Accessibility — semantic clarity.'
+    - rule: '[selected] reflects the row current-selection state under <list-ui selectable> — it is parent-managed (ADR-0056); drive selection via the parent''s [selectedKey], never [selected] directly.'
+      reason: 'Single source of truth stays on the parent, mirroring <segment-ui>.'

package/components/list/list.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/List.json",
   "title": "List",
-  "description": "Styled flat list with optional row dividers and icons — each row\nis a <list-item-ui> child. Selectable mode via [selectable] +\n[selectedKey] / `select` event. Composes <icon-ui> for row leading\nglyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),\n<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>\n(tabular data with columns). Use list-ui for non-navigable,\nnon-tabular vertical rows — comment lists, file lists, message\nstreams outside chat-shell.\n",
+  "description": "Styled flat list with optional row dividers and icons — each row\nis a <list-item-ui> child. Selectable mode via [selectable] +\n[selectedKey] / `selection-change` event. Composes <icon-ui> for row\nleading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),\n<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>\n(tabular data with columns). Use list-ui for non-navigable,\nnon-tabular vertical rows — comment lists, file lists, message\nstreams outside chat-shell.\n",
   "type": "object",
   "allOf": [
     {
@@ -32,13 +32,18 @@
       "default": false
     },
     "selectedKey": {
-      "description": "ID (or data-key) of the currently-selected child listitem.",
+      "description": "ID (or data-key) of the currently-selected child listitem — drives each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept as `selectedKey` rather than renamed to `value` (segmented/tabs/ select's parent-selection prop name): list rows are identified by DOM id/data-key, not an option value, and ADR-0056 itself governs only the child's own [selected] state surface, not this naming — a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up).",
       "type": "string",
       "default": ""
     },
     "spacing": {
-      "description": "Item spacing",
+      "description": "Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset.",
       "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
       "default": "md"
     }
   },
@@ -84,6 +89,7 @@
       "star"
     ],
     "name": "UIList",
+    "parts": {},
     "related": [
       "ListItem",
       "Tree",

package/components/list/list.class.js

@@ -28,7 +28,9 @@
  * When `selectable`:
  *   - Children (role="listitem") become keyboard-focusable via roving tabindex.
  *   - Click selects the child; key is its id or data-key.
- *   - aria-selected is set on all children.
+ *   - [selected] (ADR-0056, #1363 B7) and aria-selected are both set on
+ *     all children — [selected] is the declared API state, aria-selected
+ *     is wiring.
  *   - Fires `selection-change` with { key, previousKey }.
  */
 
@@ -73,6 +75,7 @@ export class UIList extends UIElement {
       // (patient-visit rail's roving tabindex, gh#746).
       if (this.#stampedSelection) {
         for (const ch of this.#items()) {
+          ch.removeAttribute('selected');
           ch.removeAttribute('aria-selected');
           ch.removeAttribute('tabindex');
         }
@@ -87,6 +90,11 @@ export class UIList extends UIElement {
     for (const ch of items) {
       const k = this.#keyOf(ch);
       const selected = k && k === key;
+      // [selected] (ADR-0056, #1363 B7) is the declared, reflected API
+      // surface — parent-managed, mirrors <segment-ui>. aria-selected
+      // stays as-is: ARIA is wiring, not API.
+      if (selected) ch.setAttribute('selected', '');
+      else ch.removeAttribute('selected');
       ch.setAttribute('aria-selected', selected ? 'true' : 'false');
       ch.setAttribute('tabindex', selected ? '0' : '-1');
       if (selected) focusTarget = ch;
@@ -173,6 +181,11 @@ export class UIListItem extends UIElement {
     icon:        { type: String, default: '', reflect: true },
     text:        { type: String, default: '', reflect: true },
     description: { type: String, default: '', reflect: true },
+    // ADR-0056 (gh#1303, #1363 B7): declared reflected selection-item
+    // state, parent-managed — <list-ui>[selectable] stamps this instead
+    // of leaving selection visible only via aria-selected. Mirrors
+    // <segment-ui>'s [selected].
+    selected:    { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;

package/components/list/list.css

@@ -67,7 +67,18 @@
     background: var(--a-bg-hover);
   }
 
-  :scope[selectable] > [role="listitem"][aria-selected="true"] {
+  /* [selected] is the declared, reflected state hook (ADR-0056, #1363 B7)
+     — list.class.js stamps it in lockstep with aria-selected; ARIA stays
+     wiring, not the style hook. Matched on the tag directly (not only
+     [role="listitem"]): UIList's adopt-or-stamp (gh#753) lets a
+     consumer-authored role (e.g. role="button") survive on <list-item-ui>
+     — #items() still selects/stamps it by TAG, so the style hook must
+     too, or a role-overridden selected row silently loses its selected
+     colors. The role fallback stays for non-list-item-ui children that
+     opt into role="listitem" themselves (list-ui also hosts "arbitrary
+     children", list.yaml). */
+  :scope[selectable] > list-item-ui[selected],
+  :scope[selectable] > [role="listitem"][selected] {
     background: var(--list-bg-selected);
     color: var(--list-fg-selected);
     border-inline-start-color: var(--list-border-selected);

package/components/list/list.d.ts

@@ -1,8 +1,8 @@
 /**
  * `<list-ui>` — Styled flat list with optional row dividers and icons — each row
 is a <list-item-ui> child. Selectable mode via [selectable] +
-[selectedKey] / `select` event. Composes <icon-ui> for row leading
-glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+[selectedKey] / `selection-change` event. Composes <icon-ui> for row
+leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
 <tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
 (tabular data with columns). Use list-ui for non-navigable,
 non-tabular vertical rows — comment lists, file lists, message
@@ -41,10 +41,10 @@ so content sits at the list-ui edges (canonical edge-to-edge style).
   divider: boolean;
   /** Enable selection on child listitems (roving tabindex + aria-selected). */
   selectable: boolean;
-  /** ID (or data-key) of the currently-selected child listitem. */
+  /** ID (or data-key) of the currently-selected child listitem — drives each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept as `selectedKey` rather than renamed to `value` (segmented/tabs/ select's parent-selection prop name): list rows are identified by DOM id/data-key, not an option value, and ADR-0056 itself governs only the child's own [selected] state surface, not this naming — a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up). */
   selectedKey: string;
-  /** Item spacing */
-  spacing: string;
+  /** Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset. */
+  spacing: 'sm' | 'md' | 'lg';
 
   addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
@@ -59,6 +59,8 @@ export class UIListItem extends UIElement {
   description: string;
   /** Optional leading icon name (Phosphor). */
   icon: string;
+  /** Whether this row is the current selection. Managed by the parent <list-ui>[selectable] — don't set directly; the parent's [selectedKey] is the single source of truth (ADR-0056). */
+  selected: boolean;
   /** Primary text. Renders as semibold inline body. */
   text: string;
 }

package/components/list/list.yaml

@@ -10,8 +10,8 @@ version: 1
 description: |
   Styled flat list with optional row dividers and icons — each row
   is a <list-item-ui> child. Selectable mode via [selectable] +
-  [selectedKey] / `select` event. Composes <icon-ui> for row leading
-  glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+  [selectedKey] / `selection-change` event. Composes <icon-ui> for row
+  leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
   <tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
   (tabular data with columns). Use list-ui for non-navigable,
   non-tabular vertical rows — comment lists, file lists, message
@@ -40,14 +40,22 @@ props:
     type: boolean
     default: false
   selectedKey:
-    description: ID (or data-key) of the currently-selected child listitem.
+    description: >-
+      ID (or data-key) of the currently-selected child listitem — drives
+      each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept
+      as `selectedKey` rather than renamed to `value` (segmented/tabs/
+      select's parent-selection prop name): list rows are identified by
+      DOM id/data-key, not an option value, and ADR-0056 itself governs
+      only the child's own [selected] state surface, not this naming —
+      a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up).
     type: string
     default: ""
     attribute: selected-key
   spacing:
-    description: Item spacing
+    description: Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset.
     type: string
     default: md
+    enum: [sm, md, lg]
 events:
   selection-change:
     description: "Fired on selection-change."
@@ -68,10 +76,12 @@ a2ui:
   rules:
     - rule: 'Generic vertical list container — hosts <list-item-ui> or arbitrary children.'
       reason: 'Lowest-friction list primitive.'
-    - rule: 'For interactive selection lists use <nav-ui> (single-select navigation) or <menu-ui> (action menu); list-ui is content display.'
-      reason: 'Different interaction contracts.'
+    - rule: 'list-ui supports single selection natively via [selectable] + [selectedKey] (ADR-0056, #1363 B7) — the parent stamps the matching <list-item-ui>''s [selected] + aria-selected and fires selection-change. For route-aware navigation use <nav-ui> instead; for a popover action menu use <menu-ui> instead — both have different interaction contracts than a plain selectable list.'
+      reason: 'list-ui selectable is the supported non-navigation, non-menu selection surface; nav-ui/menu-ui remain the right choice for their own contracts.'
     - rule: 'For data-grid / sortable / sticky-header needs use <table-ui> instead.'
       reason: 'Table has different semantics.'
+    - rule: 'list-ui carries no fire-and-forget "action" mode. [selectable] keeps a persisted single selection (`selectedKey` / `aria-selected`, roving tabindex); for rows that activate immediately with no persisted selection state use <action-list-ui> + <action-item-ui> instead.'
+      reason: 'Container-level decision (#1363 C5): kept separate rather than absorbed as a mode axis — stateful selection and fire-and-forget activation are genuinely different interaction contracts, and list-item-ui''s selection state is under active convergence elsewhere (#1379); rationale in gh#1374 Findings.'
 anti_patterns: []
 examples:
   - name: basic-list

package/components/list-window/list-window.a2ui.json

@@ -179,6 +179,7 @@
       "10k-rows"
     ],
     "name": "UIListWindow",
+    "parts": {},
     "related": [
       "List",
       "ListItem",