@adia-ai/web-components 0.8.30 → 0.8.32

package/components/nav-item/nav-item.d.ts

@@ -47,10 +47,10 @@ export class UINavItem extends UIElement {
   /** Visual treatment. Default ('') renders as a primary-rail item (reserved icon space, in-icon selected accent). 'section' renders flat — no icon space when absent, left-edge accent bar for selected. When the parent <nav-ui> carries variant="section", this item inherits it via CSS cascade unless an explicit variant is set. */
   variant: '' | 'section';
 
+  addEventListener(type: 'nav-select', listener: (ev: NavItemNavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINavItem, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'nav-select', listener: (ev: NavItemNavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/noodles/noodles.d.ts

@@ -62,12 +62,12 @@ export class UINoodles extends UIElement {
   /** Bezier control point distance (0-1). Higher = wider curves */
   tension: number;
 
+  addEventListener(type: 'noodle-connect', listener: (ev: NoodlesNoodleConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'noodle-disconnect', listener: (ev: NoodlesNoodleDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'noodle-drag', listener: (ev: NoodlesNoodleDragEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINoodles, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'noodle-connect', listener: (ev: NoodlesNoodleConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'noodle-disconnect', listener: (ev: NoodlesNoodleDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'noodle-drag', listener: (ev: NoodlesNoodleDragEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/option-card/option-card.css

@@ -1,7 +1,7 @@
 /* Safari 17.x bug: `:scope:not(...):hover` (Flavor A) and `:scope[checked]`
    (Flavor B — attribute-removal restyle) both fail inside `@scope`.
    Selectors moved out. See docs/BROWSER-COMPAT.md §3a. */
-option-card-ui:not([checked]):not([disabled]):hover {
+option-card-ui:not([checked]):not([disabled]):hover:not(:focus-visible) {
   background: var(--option-card-bg-hover);
   border-color: var(--option-card-border-hover);
 }

package/components/pagination/pagination.d.ts

@@ -35,10 +35,10 @@ default; pass `size="sm"` for a denser numbered row.
   /** Visual variant — `default` (ghost buttons w/ hover bg) or `button` (1×1 bordered cells; active page filled). */
   variant: 'default' | 'button';
 
+  addEventListener(type: 'page-change', listener: (ev: PaginationPageChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPagination, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'page-change', listener: (ev: PaginationPageChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/pane/pane.d.ts

@@ -38,10 +38,10 @@ grabber when resizable).
  */
   side: '' | 'leading' | 'trailing';
 
+  addEventListener(type: 'toggle', listener: (ev: PaneToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPane, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'toggle', listener: (ev: PaneToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/password-strength/password-strength.d.ts

@@ -50,10 +50,10 @@ meter.value = e.target.value)`.
  */
   value: string;
 
+  addEventListener(type: 'score-change', listener: (ev: PasswordStrengthScoreChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPasswordStrength, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'score-change', listener: (ev: PasswordStrengthScoreChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/pipeline-status/pipeline-status.a2ui.json

@@ -13,23 +13,29 @@
     }
   ],
   "properties": {
-    "complete": {
-      "description": "Component property: complete.",
-      "type": "boolean",
-      "default": false
-    },
     "component": {
       "const": "PipelineStatus"
     },
     "message": {
-      "description": "Component property: message.",
+      "description": "Current stage description shown alongside the stage label.",
       "type": "string",
       "default": ""
     },
     "stage": {
-      "description": "Component property: stage.",
+      "description": "Current stage name (interpret, analyze, plan, generate, validate, render).",
       "type": "string",
       "default": ""
+    },
+    "status": {
+      "description": "Canonical stage-progress state. Set to `completed` to render the\nfinal state and collapse the history log.",
+      "type": "string",
+      "enum": [
+        "idle",
+        "active",
+        "completed",
+        "error"
+      ],
+      "default": "idle"
     }
   },
   "required": [
@@ -59,7 +65,7 @@
       },
       {
         "description": "Pipeline status marked complete; indicator switches to success state.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"PipelineStatus\",\n    \"stage\": \"Done\",\n    \"message\": \"All 100 intents passed\",\n    \"complete\": true\n  }\n]",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"PipelineStatus\",\n    \"stage\": \"Done\",\n    \"message\": \"All 100 intents passed\",\n    \"status\": \"completed\"\n  }\n]",
         "name": "complete"
       }
     ],

package/components/pipeline-status/pipeline-status.d.ts

@@ -13,10 +13,11 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIPipelineStatus extends UIElement {
-  /** Component property: complete. */
-  complete: boolean;
-  /** Component property: message. */
+  /** Current stage description shown alongside the stage label. */
   message: string;
-  /** Component property: stage. */
+  /** Current stage name (interpret, analyze, plan, generate, validate, render). */
   stage: string;
+  /** Canonical stage-progress state. Set to `completed` to render the
+final state and collapse the history log. */
+  status: 'idle' | 'active' | 'completed' | 'error';
 }

package/components/pipeline-status/pipeline-status.yaml

@@ -11,19 +11,25 @@ description: >-
   updates via the status property. Use for long-running agent or build
   pipelines; for multi-step wizards use <stepper-ui> instead.
 props:
-  complete:
-    description: 'Component property: complete.'
-    type: boolean
-    default: false
-    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
-  message:
-    description: 'Component property: message.'
+  stage:
+    description: 'Current stage name (interpret, analyze, plan, generate, validate, render).'
     type: string
     default: ''
-  stage:
-    description: 'Component property: stage.'
+  message:
+    description: 'Current stage description shown alongside the stage label.'
     type: string
     default: ''
+  status:
+    description: |-
+      Canonical stage-progress state. Set to `completed` to render the
+      final state and collapse the history log.
+    type: string
+    default: idle
+    enum:
+      - idle
+      - active
+      - completed
+      - error
 events: {}
 slots:
   default:
@@ -37,7 +43,7 @@ a2ui:
   rules:
     - rule: 'Single updating pipeline status indicator — status pill with optional progress bar.'
       reason: 'Long-running task indicator.'
-    - rule: 'stage + complete + message attributes drive the current display state.'
+    - rule: 'stage + status + message attributes drive the current display state.'
       reason: 'State contract.'
     - rule: 'For multi-step wizards use <stepper-ui>; for chronological history use <timeline-ui>; pipeline-status is a single current-state pill.'
       reason: 'Sibling boundary.'
@@ -61,7 +67,7 @@ examples:
 - name: complete
   description: Pipeline status marked complete; indicator switches to success state.
   a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"PipelineStatus\",\n    \"stage\": \"Done\",\n    \"message\"\
-    : \"All 100 intents passed\",\n    \"complete\": true\n  }\n]"
+    : \"All 100 intents passed\",\n    \"status\": \"completed\"\n  }\n]"
 keywords:
 - pipelinestatus
 - pipeline-status

package/components/radio/radio.a2ui.json

@@ -84,8 +84,8 @@
     },
     "examples": [
       {
-        "description": "Card with radio group for plan selection: Basic, Pro, and Enterprise tiers.",
-        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\",\n      \"desc\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Choose a Plan\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"desc\",\n    \"component\": \"Text\",\n    \"slot\": \"description\",\n    \"variant\": \"caption\",\n    \"textContent\": \"Select the plan that works best for you\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"options\"\n    ]\n  },\n  {\n    \"id\": \"options\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"basic\",\n      \"pro\",\n      \"enterprise\"\n    ],\n    \"gap\": \"3\"\n  },\n  {\n    \"id\": \"basic\",\n    \"component\": \"Radio\",\n    \"label\": \"Basic — $9/mo\",\n    \"value\": \"basic\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"pro\",\n    \"component\": \"Radio\",\n    \"label\": \"Pro — $29/mo\",\n    \"value\": \"pro\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"enterprise\",\n    \"component\": \"Radio\",\n    \"label\": \"Enterprise — $99/mo\",\n    \"value\": \"enterprise\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"confirm-btn\"\n    ]\n  },\n  {\n    \"id\": \"confirm-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Confirm Plan\",\n    \"variant\": \"primary\",\n    \"block\": true,\n    \"slot\": \"action\"\n  }\n]",
+        "description": "Card with radio group for plan selection: Basic, Pro, and Enterprise tiers. The options are wrapped in radio-group-ui (gh#729) — its own [label] IS the group's accessible name (role=radiogroup + aria-labelledby), not a sibling Text node.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Choose a Plan\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"options\"\n    ]\n  },\n  {\n    \"id\": \"options\",\n    \"component\": \"RadioGroup\",\n    \"label\": \"Select the plan that works best for you\",\n    \"children\": [\n      \"basic\",\n      \"pro\",\n      \"enterprise\"\n    ]\n  },\n  {\n    \"id\": \"basic\",\n    \"component\": \"Radio\",\n    \"label\": \"Basic — $9/mo\",\n    \"value\": \"basic\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"pro\",\n    \"component\": \"Radio\",\n    \"label\": \"Pro — $29/mo\",\n    \"value\": \"pro\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"enterprise\",\n    \"component\": \"Radio\",\n    \"label\": \"Enterprise — $99/mo\",\n    \"value\": \"enterprise\",\n    \"name\": \"plan\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"confirm-btn\"\n    ]\n  },\n  {\n    \"id\": \"confirm-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Confirm Plan\",\n    \"variant\": \"primary\",\n    \"block\": true,\n    \"slot\": \"action\"\n  }\n]",
         "name": "radio-group"
       }
     ],
@@ -102,7 +102,8 @@
     ],
     "name": "UIRadio",
     "related": [
-      "button"
+      "button",
+      "radio-group"
     ],
     "slots": {
       "dot": {

package/components/radio/radio.css

@@ -2,11 +2,11 @@
    `:scope[checked] [descendant]` (Flavor B — attribute-removal restyle)
    both fail inside `@scope`. Selectors moved out. See
    docs/BROWSER-COMPAT.md §3a. */
-radio-ui:not([disabled]):hover [slot="dot"] {
+radio-ui:not([disabled]):hover:not(:focus-visible) [slot="dot"] {
   border-color: var(--radio-border-hover);
   background: var(--radio-bg-hover);
 }
-radio-ui[checked]:not([disabled]):hover [slot="dot"] {
+radio-ui[checked]:not([disabled]):hover:not(:focus-visible) [slot="dot"] {
   background: var(--radio-bg-checked-hover);
   border-color: var(--radio-bg-checked-hover);
 }

package/components/radio/radio.yaml

@@ -111,7 +111,7 @@ tokens:
     description: Override transition timing
 a2ui:
   rules:
-    - "Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For radio groups, the canonical pattern is a column of bare <radio-ui label='…'> elements sharing a [name=] — no field-ui wrapper around each radio."
+    - "Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For radio groups, the canonical pattern is <radio-group-ui label='…'> wrapping bare <radio-ui label='…'> elements sharing a [name=] — radio-group-ui supplies the group's accessible name (role=radiogroup + aria-labelledby); a bare Column of radios cannot (gh#729)."
     - rule: 'Use the [name] attribute to group radios — exactly one is selected per name group; form-associated.'
       reason: 'Standard radio-group semantics; name= is the group key.'
     - rule: 'For button-style single-select clusters (visually richer) use <segmented-ui> + <segment-ui> instead.'
@@ -127,7 +127,7 @@ anti_patterns:
     rule: Use [label] on radio-ui directly; do not wrap in field-ui.
 examples:
   - name: radio-group
-    description: "Card with radio group for plan selection: Basic, Pro, and Enterprise tiers."
+    description: "Card with radio group for plan selection: Basic, Pro, and Enterprise tiers. The options are wrapped in radio-group-ui (gh#729) — its own [label] IS the group's accessible name (role=radiogroup + aria-labelledby), not a sibling Text node."
     a2ui: >-
       [
         {
@@ -143,8 +143,7 @@ examples:
           "id": "hdr",
           "component": "Header",
           "children": [
-            "title",
-            "desc"
+            "title"
           ]
         },
         {
@@ -154,13 +153,6 @@ examples:
           "textContent": "Choose a Plan",
           "variant": "section"
         },
-        {
-          "id": "desc",
-          "component": "Text",
-          "slot": "description",
-          "variant": "caption",
-          "textContent": "Select the plan that works best for you"
-        },
         {
           "id": "sec",
           "component": "Section",
@@ -170,13 +162,13 @@ examples:
         },
         {
           "id": "options",
-          "component": "Column",
+          "component": "RadioGroup",
+          "label": "Select the plan that works best for you",
           "children": [
             "basic",
             "pro",
             "enterprise"
-          ],
-          "gap": "3"
+          ]
         },
         {
           "id": "basic",
@@ -262,3 +254,4 @@ synonyms:
     - settings
 related:
   - button
+  - radio-group

package/components/radio-group/radio-group.a2ui.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/RadioGroup.json",
+  "title": "RadioGroup",
+  "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.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "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
+    },
+    "component": {
+      "const": "RadioGroup"
+    },
+    "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.",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component",
+    "label"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "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].",
+        "right": "<radio-group-ui label=\"How often do you exercise?\">\n  <radio-ui label=\"Never\" name=\"exercise\"></radio-ui>\n  <radio-ui label=\"Sometimes\" name=\"exercise\"></radio-ui>\n</radio-group-ui>\n",
+        "rule": "The question that introduces a radio-ui set belongs in radio-group-ui's [label], not a sibling Text node.",
+        "wrong": "<column>\n  <text>How often do you exercise?</text>\n  <radio-ui label=\"Never\" name=\"exercise\"></radio-ui>\n  <radio-ui label=\"Sometimes\" name=\"exercise\"></radio-ui>\n</column>\n"
+      }
+    ],
+    "category": "input",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "A single scored-questionnaire item: the question as the group's accessible label, three bare radio-ui options sharing one [name=].",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"RadioGroup\",\n    \"label\": \"Little interest or pleasure in doing things?\",\n    \"children\": [\"opt-0\", \"opt-1\", \"opt-2\"]\n  },\n  { \"id\": \"opt-0\", \"component\": \"Radio\", \"label\": \"Not at all\", \"name\": \"phq2-1\", \"value\": \"0\" },\n  { \"id\": \"opt-1\", \"component\": \"Radio\", \"label\": \"Several days\", \"name\": \"phq2-1\", \"value\": \"1\" },\n  { \"id\": \"opt-2\", \"component\": \"Radio\", \"label\": \"More than half the days\", \"name\": \"phq2-1\", \"value\": \"2\" }\n]",
+        "name": "questionnaire-item"
+      }
+    ],
+    "keywords": [
+      "radio",
+      "radiogroup",
+      "fieldset",
+      "legend",
+      "questionnaire",
+      "survey",
+      "poll",
+      "accessibility",
+      "aria-labelledby"
+    ],
+    "name": "UIRadioGroup",
+    "related": [
+      "radio",
+      "field"
+    ],
+    "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": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "poll": [
+        "radio-group",
+        "questionnaire"
+      ],
+      "questionnaire": [
+        "radio-group",
+        "form",
+        "survey"
+      ],
+      "survey": [
+        "radio-group",
+        "questionnaire"
+      ]
+    },
+    "tag": "radio-group-ui",
+    "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."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/radio-group/radio-group.class.js

@@ -0,0 +1,75 @@
+/**
+ * Non-side-effect class export for `<radio-group-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/radio-group`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <radio-group-ui label="Choose a plan">
+ *   <radio-ui label="Basic" name="plan" value="basic"></radio-ui>
+ *   <radio-ui label="Pro" name="plan" value="pro"></radio-ui>
+ * </radio-group-ui>
+ *
+ * Programmatic question↔group association for a set of bare radio-ui
+ * options (gh#729). role="radiogroup" on the host + aria-labelledby
+ * pointing at an auto-minted label element rendered from [label] — the
+ * ONLY job this component does. Exclusivity + arrow-key navigation are
+ * unchanged: radio-ui's own #select/#onKey already resolve their group
+ * via `closest('fieldset, [role="radiogroup"]')` (radio.class.js:48),
+ * which now matches this host instead of falling through to
+ * `this.parentElement`.
+ *
+ * Not a form-associated element itself — it carries no value; each child
+ * radio-ui is its own form participant per the existing [name=] contract.
+ */
+import { UIElement } from '../../core/element.js';
+
+export class UIRadioGroup extends UIElement {
+  static properties = {
+    label:    { type: String,  default: '', reflect: true },
+    required: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #labelEl = null;
+
+  connected() {
+    this.setAttribute('role', 'radiogroup');
+    this.#ensureLabelElement();
+    if (this.#labelEl?.id) this.setAttribute('aria-labelledby', this.#labelEl.id);
+  }
+
+  disconnected() {
+    this.#labelEl = null;
+  }
+
+  render() {
+    if (this.#labelEl) this.#labelEl.textContent = this.label || '';
+    if (this.required) this.setAttribute('aria-required', 'true');
+    else this.removeAttribute('aria-required');
+  }
+
+  #ensureLabelElement() {
+    this.#labelEl = this.querySelector(':scope > [data-radio-group-label]');
+    if (!this.#labelEl) {
+      const el = document.createElement('div');
+      el.setAttribute('slot', 'label');
+      el.setAttribute('data-radio-group-label', '');
+      el.id = UIRadioGroup.#nextId();
+      el.textContent = this.label || '';
+      this.prepend(el);
+      this.#labelEl = el;
+    }
+  }
+
+  static #idSeq = 0;
+  static #nextId() { return `radio-group-label-${++UIRadioGroup.#idSeq}`; }
+}

package/components/radio-group/radio-group.css

@@ -0,0 +1,31 @@
+@scope (radio-group-ui) {
+  :where(:scope) {
+    /* ── Tokens ── */
+    --radio-group-gap:               var(--a-space-2);
+    --radio-group-label-color:       var(--md-sys-color-neutral-on-surface);
+    --radio-group-label-font-size:   var(--a-ui-md);
+    --radio-group-label-font-weight: var(--a-weight-medium);
+  }
+
+  /* ── Base — vertical stack: label row, then each radio-ui option. ── */
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--radio-group-gap);
+  }
+
+  :scope [slot="label"] {
+    color: var(--radio-group-label-color);
+    font-size: var(--radio-group-label-font-size);
+    font-weight: var(--radio-group-label-font-weight);
+  }
+
+  /* No accessible name set → hide the (empty) label row rather than
+     reserve blank space. label is required in practice (radio-group-ui's
+     entire purpose is carrying it); this only guards the transient/
+     misuse case. */
+  :scope:not([label]) [slot="label"] {
+    display: none;
+  }
+}

package/components/radio-group/radio-group.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `<radio-group-ui>` — 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.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/radio-group
+ *
+ * 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 UIRadioGroup extends UIElement {
+  /** 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]). */
+  required: boolean;
+  /** 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. */
+  label: string;
+}

package/components/radio-group/radio-group.examples.md

@@ -0,0 +1,37 @@
+# radio-group — Examples
+
+## label
+
+```html
+<radio-group-ui label="Little interest or pleasure in doing things?">
+  <radio-ui label="Not at all" name="rg-demo-phq" value="0" checked></radio-ui>
+  <radio-ui label="Several days" name="rg-demo-phq" value="1"></radio-ui>
+  <radio-ui label="More than half the days" name="rg-demo-phq" value="2"></radio-ui>
+</radio-group-ui>
+```
+
+## required
+
+```html
+<radio-group-ui label="How would you rate your overall health?" required>
+  <radio-ui label="Excellent" name="rg-demo-health" value="excellent" required></radio-ui>
+  <radio-ui label="Good" name="rg-demo-health" value="good" required></radio-ui>
+  <radio-ui label="Fair" name="rg-demo-health" value="fair" required></radio-ui>
+  <radio-ui label="Poor" name="rg-demo-health" value="poor" required></radio-ui>
+</radio-group-ui>
+```
+
+## Combinations
+
+```html
+<col-ui gap="5">
+  <radio-group-ui label="Little interest or pleasure in doing things?">
+    <radio-ui label="Not at all" name="rg-demo-multi-1" value="0" checked></radio-ui>
+    <radio-ui label="Several days" name="rg-demo-multi-1" value="1"></radio-ui>
+  </radio-group-ui>
+  <radio-group-ui label="Feeling down, depressed, or hopeless?">
+    <radio-ui label="Not at all" name="rg-demo-multi-2" value="0"></radio-ui>
+    <radio-ui label="Several days" name="rg-demo-multi-2" value="1" checked></radio-ui>
+  </radio-group-ui>
+</col-ui>
+```

package/components/radio-group/radio-group.js

@@ -0,0 +1,17 @@
+/**
+ * `<radio-group-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIRadioGroup } from '@adia-ai/web-components/components/radio-group/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIRadioGroup } from './radio-group.class.js';
+
+defineIfFree('radio-group-ui', UIRadioGroup);
+
+export { UIRadioGroup };