@adia-ai/web-components 0.8.30 → 0.8.32

package/components/radio-group/radio-group.yaml

@@ -0,0 +1,114 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIRadioGroup
+tag: radio-group-ui
+status: stable
+component: RadioGroup
+category: input
+version: 1
+description: >-
+  Groups a set of bare <radio-ui label="…"> children under one accessible
+  name — role="radiogroup" on the host plus aria-labelledby pointing at
+  its own [label]. Radio-ui already supports ancestor fieldset/[role=radiogroup]
+  grouping for exclusivity + arrow-key navigation (unchanged by this
+  wrapper); a plain layout container (Column) can carry neither the role
+  nor the label association, which left the canonical questionnaire shape
+  (radio.yaml's own example) with no programmatic question↔group link
+  (gh#729). Use this wherever a question/prompt introduces a set of
+  mutually-exclusive radio-ui options — it is the ONLY primitive that
+  carries the group's accessible name; radio-ui itself stays self-labeling
+  per-option.
+props:
+  label:
+    description: >-
+      The question or prompt text — rendered above the options and wired
+      to the host via aria-labelledby. This is the group's accessible
+      name; without it the group has none.
+    required: true
+    type: string
+    default: ""
+    reflect: true
+  required:
+    description: Marks the group as requiring a selection for form validation (visual + aria-required only — the constraint itself lives on each radio-ui's own [required]).
+    type: boolean
+    default: false
+    reflect: true
+events: {}
+slots:
+  default:
+    description: "radio-ui children sharing one [name=] — exclusivity and arrow-key navigation are unchanged; they still resolve via closest('fieldset, [role=radiogroup]'), which now matches this host."
+  label:
+    description: Auto-minted label element (mounted by radio-group-ui from the [label] prop) — do not author this slot directly.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens:
+  --radio-group-gap:
+    description: Gap between the label and the option stack, and between each option.
+  --radio-group-label-color:
+    description: Override the question/prompt label color.
+  --radio-group-label-font-size:
+    description: Override the question/prompt label font size.
+  --radio-group-label-font-weight:
+    description: Override the question/prompt label font weight.
+a2ui:
+  rules:
+    - "The canonical radio-group shape is <radio-group-ui label=\"…\"> wrapping a set of bare <radio-ui label=\"…\" name=\"…\"> children — the wrapper supplies the group's accessible name (role=radiogroup + aria-labelledby); Column/Section cannot carry a role, so a bare Column of radios has no programmatic question↔group association."
+    - rule: "Do not put the question text as a sibling Text node before a Column of radios — put it in radio-group-ui's own [label] prop instead."
+      reason: "A sibling Text has no aria relationship to the radios; radio-group-ui's [label] is wired via aria-labelledby, which a sibling Text is not."
+    - rule: "radio-ui children keep their own [label] per-option; radio-group-ui's [label] is the shared question, not a per-option label."
+      reason: "Two different accessible names at two different levels — the group's name and each option's name — both need to reach an AT user."
+anti_patterns:
+  - description: Wrapping radio-ui options in a bare Column/Section with the question as a sibling Text node instead of radio-group-ui's [label].
+    wrong: |
+      <column>
+        <text>How often do you exercise?</text>
+        <radio-ui label="Never" name="exercise"></radio-ui>
+        <radio-ui label="Sometimes" name="exercise"></radio-ui>
+      </column>
+    right: |
+      <radio-group-ui label="How often do you exercise?">
+        <radio-ui label="Never" name="exercise"></radio-ui>
+        <radio-ui label="Sometimes" name="exercise"></radio-ui>
+      </radio-group-ui>
+    rule: The question that introduces a radio-ui set belongs in radio-group-ui's [label], not a sibling Text node.
+examples:
+  - name: questionnaire-item
+    description: "A single scored-questionnaire item: the question as the group's accessible label, three bare radio-ui options sharing one [name=]."
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "RadioGroup",
+          "label": "Little interest or pleasure in doing things?",
+          "children": ["opt-0", "opt-1", "opt-2"]
+        },
+        { "id": "opt-0", "component": "Radio", "label": "Not at all", "name": "phq2-1", "value": "0" },
+        { "id": "opt-1", "component": "Radio", "label": "Several days", "name": "phq2-1", "value": "1" },
+        { "id": "opt-2", "component": "Radio", "label": "More than half the days", "name": "phq2-1", "value": "2" }
+      ]
+keywords:
+  - radio
+  - radiogroup
+  - fieldset
+  - legend
+  - questionnaire
+  - survey
+  - poll
+  - accessibility
+  - aria-labelledby
+synonyms:
+  questionnaire:
+    - radio-group
+    - form
+    - survey
+  survey:
+    - radio-group
+    - questionnaire
+  poll:
+    - radio-group
+    - questionnaire
+related:
+  - radio
+  - field

package/components/segmented/segmented.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "allowEmpty": {
+      "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state.",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "Segmented"
     },

package/components/segmented/segmented.class.js

@@ -29,6 +29,14 @@ export class UISegmented extends UIFormElement {
   static properties = {
     ...UIFormElement.properties,
     value: { type: String, default: '', reflect: true },
+    // gh#693: absent (default false) preserves the original self-select
+    // behavior below. A path-bound consumer whose bound value can be a
+    // real empty state (e.g. "no disposition recorded yet") sets this to
+    // suppress the connect-time self-select, so a falsy `value` renders
+    // every segment unselected instead of silently picking one — a
+    // display-truth defect where the UI claimed a state the data never
+    // recorded.
+    allowEmpty: { type: Boolean, default: false, reflect: true, attribute: 'allow-empty' },
   };
 
   static template = () => null;
@@ -55,8 +63,10 @@ export class UISegmented extends UIFormElement {
       this.addEventListener('keydown', this.#handleKeydown);
     }
 
-    // Default to first segment if no value
-    if (!this.value) {
+    // Default to first segment if no value — unless allow-empty opts out
+    // (a falsy path-bound value must render as truly empty, not silently
+    // pick one, gh#693).
+    if (!this.value && !this.allowEmpty) {
       const first = this.querySelector('segment-ui:not([disabled])');
       if (first) this.value = first.value || first.getAttribute('value') || '';
     }
@@ -128,16 +138,24 @@ export class UISegmented extends UIFormElement {
     if (!segs.length) return;
 
     // Sync selection state
+    let anyActive = false;
     for (const seg of segs) {
       const segVal = seg.value || seg.getAttribute('value') || '';
       const isActive = segVal === this.value;
       if (isActive) {
         seg.setAttribute('selected', '');
+        anyActive = true;
       } else {
         seg.removeAttribute('selected');
       }
       seg.setAttribute('tabindex', isActive ? '0' : '-1');
     }
+    // allow-empty's "nothing selected" state must still be keyboard
+    // reachable — mirrors list-ui's roving-tabindex fallback (list.class.js).
+    if (!anyActive) {
+      const firstEnabled = segs.find((s) => !s.disabled);
+      firstEnabled?.setAttribute('tabindex', '0');
+    }
 
     if (this.label) this.setAttribute('aria-label', this.label);
 

package/components/segmented/segmented.yaml

@@ -11,6 +11,11 @@ props:
     description: Value of the currently selected segment.
     type: string
     default: ''
+  allowEmpty:
+    description: Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state.
+    type: boolean
+    default: false
+    attribute: allow-empty
 events:
   change:
     description: Fired when the selected segment changes. detail contains { value }.

package/components/stat/stat.css

@@ -202,19 +202,23 @@
     white-space: nowrap;
   }
 
-  /* Trend arrows via ::before */
-  :scope[trend="up"] [slot="change"]::before {
-    content: "\25B2";
-    color: var(--stat-up-fg);
+  /* Trend arrow — Phosphor icon-ui, colored via currentColor from the
+     [trend] color rules below (issue 805; was a CSS ::before unicode
+     triangle). Sized relative to the change text so it scales with
+     --stat-change-size instead of a fixed px value. No slot="icon"
+     attribute — that value is reserved for stat's own [slot="icon"]
+     region; an ancestor's `[slot="icon"]` descendant rule would otherwise
+     leak margin/positioning onto this nested icon-ui (issue 809, PR 810
+     shape). Spacing from the text comes from [slot="change"]'s own
+     `gap`, not margin, for the same reason. */
+  [slot="change"] icon-ui[data-trend-icon] {
+    --a-icon-size: 1em;
   }
+
   :scope[trend="up"] [slot="change"] {
     color: var(--stat-up-fg);
   }
 
-  :scope[trend="down"] [slot="change"]::before {
-    content: "\25BC";
-    color: var(--stat-down-fg);
-  }
   :scope[trend="down"] [slot="change"] {
     color: var(--stat-down-fg);
   }

package/components/stat/stat.js

@@ -32,9 +32,15 @@ class UIStat extends UIElement {
 
   static template = () => null;
 
+  // Trend arrows the class stamps directly (issue 805) — consumers calling
+  // installIconLoaders() manually need these two names present.
+  static requiredIcons = ['arrow-up', 'arrow-down'];
+
   #valueEl = null;
   #labelEl = null;
   #changeEl = null;
+  #changeIconEl = null;
+  #changeTextEl = null;
   #iconEl = null;
 
   connected() {
@@ -59,6 +65,28 @@ class UIStat extends UIElement {
       this.appendChild(this.#changeEl);
     }
 
+    // Trend arrow (issue 805): a real icon-ui child instead of a CSS ::before
+    // unicode triangle, so the delta indicator rides the Phosphor icon
+    // system (contrast, weight, RTL) like every other icon on the page.
+    // No `slot="icon"` attribute on this child — that value is reserved for
+    // stat's own outer `[slot="icon"]` region, and an ancestor's `[slot="icon"]`
+    // descendant selector would otherwise leak margin/positioning onto it
+    // (issue 809, PR 810 shape). `[data-trend-icon]` is scoped to stat's own CSS.
+    this.#changeIconEl = this.#changeEl.querySelector(':scope > icon-ui[data-trend-icon]');
+    if (!this.#changeIconEl) {
+      this.#changeIconEl = document.createElement('icon-ui');
+      this.#changeIconEl.setAttribute('data-trend-icon', '');
+      this.#changeIconEl.hidden = true;
+      this.#changeEl.appendChild(this.#changeIconEl);
+    }
+
+    this.#changeTextEl = this.#changeEl.querySelector(':scope > [data-trend-text]');
+    if (!this.#changeTextEl) {
+      this.#changeTextEl = document.createElement('span');
+      this.#changeTextEl.setAttribute('data-trend-text', '');
+      this.#changeEl.appendChild(this.#changeTextEl);
+    }
+
     this.#iconEl = this.querySelector(':scope > [slot="icon"]');
     if (!this.#iconEl) {
       this.#iconEl = document.createElement('icon-ui');
@@ -83,6 +111,9 @@ class UIStat extends UIElement {
       // value+change visual mass without being so wide as to look like text.
       this.#valueEl.textContent = '';
       this.#valueEl.innerHTML = '<skeleton-ui width="60%" height="2em" radius="sm"></skeleton-ui>';
+      // Skeleton replaces the trend icon + text children wholesale; the
+      // non-loading branch below detects the detached refs (parentNode
+      // check) and re-inserts them once real data arrives.
       this.#changeEl.textContent = '';
       this.#changeEl.innerHTML = '<skeleton-ui width="40%" height="1em" radius="sm"></skeleton-ui>';
       this.#changeEl.hidden = false;
@@ -103,7 +134,39 @@ class UIStat extends UIElement {
 
     // Change badge
     if (this.change) {
-      this.#changeEl.textContent = this.change;
+      // Contract: the generated icon+text pair owns [slot="change"]'s
+      // content — same "consumer content is overwritten" rule #valueEl /
+      // #labelEl already apply (their textContent is replaced every render
+      // regardless of what markup a consumer authored there). #changeEl
+      // additionally needs a specific two-node SHAPE (icon then text), not
+      // just overwritten text, so any deviation from that exact shape is
+      // normalized before writing: a consumer-authored `<stat-ui
+      // change="…"><span slot="change">stale</span></stat-ui>` gets its
+      // stale content cleared and the generated pair installed; loading's
+      // skeleton wipe (above) detaches the pair the same way and is
+      // recovered by the same branch; a disconnect/reconnect cycle that
+      // leaves an orphaned skeleton behind is also caught here (fresh
+      // #changeIconEl/#changeTextEl instances from the new connected()
+      // never match old stray children).
+      const hasOnlyTrendChildren =
+        this.#changeEl.childNodes.length === 2 &&
+        this.#changeEl.firstChild === this.#changeIconEl &&
+        this.#changeEl.lastChild === this.#changeTextEl;
+      if (!hasOnlyTrendChildren) {
+        this.#changeEl.textContent = '';
+        this.#changeEl.appendChild(this.#changeIconEl);
+        this.#changeEl.appendChild(this.#changeTextEl);
+      }
+      this.#changeTextEl.textContent = this.change;
+      if (this.trend === 'up') {
+        this.#changeIconEl.setAttribute('name', 'arrow-up');
+        this.#changeIconEl.hidden = false;
+      } else if (this.trend === 'down') {
+        this.#changeIconEl.setAttribute('name', 'arrow-down');
+        this.#changeIconEl.hidden = false;
+      } else {
+        this.#changeIconEl.hidden = true;
+      }
       this.#changeEl.hidden = false;
     } else {
       this.#changeEl.hidden = true;
@@ -122,6 +185,8 @@ class UIStat extends UIElement {
     this.#valueEl = null;
     this.#labelEl = null;
     this.#changeEl = null;
+    this.#changeIconEl = null;
+    this.#changeTextEl = null;
     this.#iconEl = null;
   }
 }

package/components/stat/stat.yaml

@@ -112,6 +112,9 @@ tokens:
     description: Font size for the primary value
   --stat-value-weight:
     description: Font weight for the primary value
+requiredIcons:
+  - arrow-up
+  - arrow-down
 a2ui:
   rules:
     - rule: 'Use for prominent metric/KPI displays inside dashboard cards. Value + label + optional delta indicator.'

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

@@ -21,6 +21,11 @@
     "component": {
       "const": "StepperItem"
     },
+    "disabled": {
+      "description": "S2's phase-gating mechanism (gh#711 S1 review). Skipped in the parent's [interactive] roving tabindex/arrow order, unclickable, carries aria-disabled. Independent of [status] — a completed or upcoming step can still be disabled for a different reason (e.g. the visit phase hasn't unlocked it yet).",
+      "type": "boolean",
+      "default": false
+    },
     "icon": {
       "description": "Optional leading Phosphor icon name; overrides the auto-stamped numeric badge.",
       "type": "string",

package/components/stepper/stepper-item.yaml

@@ -39,6 +39,15 @@ props:
       - active
       - completed
       - error
+  disabled:
+    description: >-
+      S2's phase-gating mechanism (gh#711 S1 review). Skipped in the
+      parent's [interactive] roving tabindex/arrow order, unclickable,
+      carries aria-disabled. Independent of [status] — a completed or
+      upcoming step can still be disabled for a different reason (e.g.
+      the visit phase hasn't unlocked it yet).
+    type: boolean
+    default: false
 slots:
   label:
     description: Custom label content; falls through to `[text]` prop if not slotted.
@@ -73,3 +82,5 @@ a2ui:
       reason: 'Parent owns step progression.'
     - rule: 'For chronological events (no completion semantics) use <timeline-item-ui> instead.'
       reason: 'Stepper is process; timeline is history.'
+    - rule: 'Set [disabled] to phase-gate a step out of click/keyboard reach without changing [status].'
+      reason: 'gh#711 S1 review — S2 uses this to lock steps the current visit phase hasn''t unlocked.'

package/components/stepper/stepper.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stepper.json",
   "title": "Stepper",
-  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
+  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving- tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.",
   "type": "object",
   "allOf": [
     {
@@ -16,6 +16,11 @@
     "component": {
       "const": "Stepper"
     },
+    "interactive": {
+      "description": "Opt into click-to-navigate + roving-tabindex keyboard nav (arrow keys / Home / End / Enter / Space). Absent by default — a bare stepper is a read-only progress display, not a nav control (gh#711 S1).",
+      "type": "boolean",
+      "default": false
+    },
     "orientation": {
       "description": "horizontal | vertical",
       "type": "string",
@@ -37,12 +42,40 @@
     "composes": [
       "icon-ui"
     ],
-    "events": {},
+    "events": {
+      "change": {
+        "description": "Fired after a click or keyboard navigation changes [step] (i.e. only when the preceding [step-request] wasn't vetoed). Only fires when [interactive] is set.",
+        "detail": {
+          "step": {
+            "description": "New current step index.",
+            "type": "number"
+          }
+        }
+      },
+      "step-request": {
+        "description": "Cancelable — fires BEFORE [step] mutates, on a click or keyboard navigation. call preventDefault() to veto: the step does not change, [change] does not fire, and focus/roving-tabindex stay exactly where they were. A host that never listens for this event keeps the pre-veto uncontrolled behavior unchanged (gh#711 S1 review).",
+        "detail": {
+          "previous": {
+            "description": "The current step index before this navigation.",
+            "type": "number"
+          },
+          "step": {
+            "description": "The step index the navigation would land on if not vetoed.",
+            "type": "number"
+          }
+        }
+      }
+    },
     "examples": [
       {
         "description": "Three-step wizard",
         "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Stepper\",\n    \"step\": 1,\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Account\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Details\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Review\"\n  }\n]",
         "name": "basic"
+      },
+      {
+        "description": "Click/keyboard-navigable stepper — host allows jumping between steps.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Stepper\",\n    \"step\": 1,\n    \"interactive\": true,\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Account\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Details\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Review\"\n  }\n]",
+        "name": "interactive"
       }
     ],
     "keywords": [
@@ -51,7 +84,9 @@
       "steps",
       "process",
       "onboarding",
-      "multi-step"
+      "multi-step",
+      "interactive",
+      "click-to-navigate"
     ],
     "name": "UIStepper",
     "related": [