feat(DropdownMenuRadioGroup): title — a radio set with its own heading is one named group

.changeset/dropdown-menu-group-block-radio-title.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] The "DropdownMenuGroup — Selectable rows" block titles its radio set with the set's own `title` instead of wrapping it in a `DropdownMenuGroup`, so the menu exposes one group named "Model" rather than two nested groups with the same name.
+
+@vjeux

.changeset/dropdown-menu-radio-group-title.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `DropdownMenuRadioGroup` (also exported as `ContextMenuRadioGroup`) takes a `title`: a visible heading above its radios, drawn like a `DropdownMenuGroup` heading, that names the group. With a title, `label` is optional, and the title names the group so the name always holds the visible heading: a caller's `aria-labelledby` is read after it, and `label` or a caller's `aria-label` is ignored, with a development warning when it differs from the title's text. A `title` that renders no text counts as no title. Give a menu section that holds one radio set this title instead of wrapping the set in a `DropdownMenuGroup`: the menu then exposes one group named by its heading rather than two nested groups with the same name. Without `title` nothing changes.
+
+@vjeux

apps/storybook/stories/DropdownMenu.stories.tsx

@@ -869,6 +869,40 @@ export const LabRadioGroup: Story = {
   },
 };
 
+/**
+ * A section of a menu that holds one radio set gives the set a `title`
+ * instead of wrapping it in a DropdownMenuGroup: the heading shows as any
+ * group heading does, and the menu exposes the set as one group named by
+ * that heading.
+ */
+export const RadioGroupWithTitle: Story = {
+  name: 'Radio group with a title',
+  render: function RadioGroupWithTitleStory() {
+    const [hidden, setHidden] = useState('hide');
+    const [showDrafts, setShowDrafts] = useState(true);
+    return (
+      <div data-testid="radio-title-fixture">
+        <DropdownMenu button={{label: 'Filter'}}>
+          <DropdownMenuCheckboxItem
+            label="Show drafts"
+            value={showDrafts}
+            onChange={setShowDrafts}
+          />
+          <DropdownMenuDivider />
+          <DropdownMenuRadioGroup
+            value={hidden}
+            onChange={setHidden}
+            title="Hidden files">
+            <DropdownMenuRadioItem value="hide" label="Hide hidden files" />
+            <DropdownMenuRadioItem value="show" label="Show hidden files" />
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+        <output data-testid="hidden">{hidden}</output>
+      </div>
+    );
+  },
+};
+
 export const LabSelectableSizes: Story = {
   render: function LabSelectableSizesStory() {
     const [sm, setSm] = useState('a');

apps/storybook/stories/RadioGroupA11y.stories.tsx

@@ -98,6 +98,8 @@ export const SegmentedOptionGroupDisabledWithMessage = storyFor(
 
 export const MenuGroupSelected = storyFor('menu-group-selected');
 export const MenuGroupNoneSelected = storyFor('menu-group-none-selected');
+export const MenuGroupTitled = storyFor('menu-group-titled');
+export const MenuGroupTitledLabelled = storyFor('menu-group-titled-labelled');
 export const MenuOptionUnselectedDescribed = storyFor(
   'menu-option-unselected-described',
 );

packages/cli/assets/templates/blocks/components/DropdownMenuGroup/DropdownMenuGroupWithSelectable.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'DropdownMenuGroup — Selectable rows',
   displayName: 'DropdownMenuGroup — Selectable rows',
   description:
-    'Titled groups around a radio group and checkbox rows — the rows the data API cannot express, which is why the heading lives in compound mode.',
+    'A radio set titled by its own title and a titled group of checkbox rows — the rows the data API cannot express, which is why the headings live in compound mode. A section holding one radio set titles the set itself rather than a group around it, so it is one group with one name.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: [

packages/cli/assets/templates/blocks/components/DropdownMenuGroup/DropdownMenuGroupWithSelectable.tsx

@@ -19,17 +19,15 @@ export default function DropdownMenuGroupWithSelectable() {
 
   return (
     <DropdownMenu button={{label: 'Run settings'}}>
-      <DropdownMenuGroup title="Model">
-        <DropdownMenuRadioGroup
-          label="Model"
-          value={model}
-          onChange={setModel}
-          hasCloseOnSelect={false}>
-          <DropdownMenuRadioItem value="fast" label="Fast" />
-          <DropdownMenuRadioItem value="balanced" label="Balanced" />
-          <DropdownMenuRadioItem value="thorough" label="Thorough" />
-        </DropdownMenuRadioGroup>
-      </DropdownMenuGroup>
+      <DropdownMenuRadioGroup
+        title="Model"
+        value={model}
+        onChange={setModel}
+        hasCloseOnSelect={false}>
+        <DropdownMenuRadioItem value="fast" label="Fast" />
+        <DropdownMenuRadioItem value="balanced" label="Balanced" />
+        <DropdownMenuRadioItem value="thorough" label="Thorough" />
+      </DropdownMenuRadioGroup>
       <DropdownMenuDivider />
       <DropdownMenuGroup title="On completion">
         <DropdownMenuCheckboxItem

packages/cli/test/__golden__/no-icon-set/search-icon-set.json

@@ -3,7 +3,7 @@
   "type": "search",
   "data": {
     "query": "icon set",
-    "matchCount": 370,
+    "matchCount": 371,
     "results": [
       {
         "domain": "doc",

packages/cli/test/__golden__/no-icon-set/search-icon-set.txt

@@ -1,4 +1,4 @@
-Results for "icon set" (20 of 370)
+Results for "icon set" (20 of 371)
 name:        authoring/building-blocks/templates/build-the-template/template-assets/template-icons
 section:     use-astryx-icon
 domain:      doc

packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -99,8 +99,13 @@ export const docs = {
       name: 'label',
       type: 'string',
       description:
-        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required even when aria-labelledby (via base props) points to visible text; that visible reference becomes the computed name while label remains the fallback.',
-      required: true,
+        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required unless title is given. An aria-labelledby passed through base props that points at visible text becomes the computed name, while label remains the fallback. With a title, the title names the group instead, so the name holds the visible heading; label (or an aria-label passed through base props) is then ignored, with a development warning when it differs from the text of the title. Without a title, an aria-label passed through base props names the group when label is omitted.',
+    },
+    {
+      name: 'title',
+      type: 'ReactNode',
+      description:
+        'A visible heading above the radios, with the same treatment as a DropdownMenuGroup heading, that names the group through aria-labelledby; an aria-labelledby passed through base props is read after it. With a title, label is optional. A title that renders no text (true, an empty fragment, a component that returns null) counts as no title: no heading shows and the group is named as without one. Give a menu section that holds one radio set this title instead of wrapping the set in a DropdownMenuGroup, so the set is one group with one name rather than two nested groups with the same name.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -132,7 +137,9 @@ export const docsZh = {
     value: '组中当前选中的值。尚无选中项时传 undefined。',
     onChange: '所选值变化时触发的回调。',
     label:
-      '组的无障碍名称，作为 aria-label 应用。即使 aria-labelledby（通过基础属性）指向可见文本，label 仍然必需并作为后备名称。',
+      '组的无障碍名称，作为 aria-label 应用，以便屏幕阅读器将单选项作为命名集合朗读，例如“Sort by”。未提供 title 时必需。通过基础属性传入、指向可见文本的 aria-labelledby 会成为计算出的名称，label 作为后备名称。提供 title 时改由 title 命名该组，使名称始终包含可见标题；此时 label（或通过基础属性传入的 aria-label）会被忽略，若其与 title 的文本不同，开发环境会发出警告。未提供 title 且省略 label 时，通过基础属性传入的 aria-label 为该组命名。',
+    title:
+      '显示在单选项上方的可见标题，样式与 DropdownMenuGroup 的标题相同，并通过 aria-labelledby 为该组命名；通过基础属性传入的 aria-labelledby 会接在其后。提供 title 时 label 可省略。不渲染任何文本的 title（true、空 Fragment、返回 null 的组件）视为未提供：不显示标题，组按未提供 title 时的方式命名。菜单中只包含一组单选项的分区应使用此标题，而不是用 DropdownMenuGroup 包裹该组，这样该组只是一个具有一个名称的组。',
     hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
     ref: '转发到 role="group" 根元素的 ref。',
     children: '组成该组的 DropdownMenuRadioItem。',
@@ -147,7 +154,10 @@ export const docsDense = {
   propDescriptions: {
     value: 'selected value (undefined = none)',
     onChange: 'fired when selected value changes',
-    label: 'accessible group name (applied as aria-label); required',
+    label:
+      'accessible group name (applied as aria-label); required unless title is given',
+    title:
+      'visible heading (DropdownMenuGroup treatment) that names the group via aria-labelledby; use it instead of a DropdownMenuGroup around one radio set',
     hasCloseOnSelect: 'close menu on select (default true)',
     ref: 'forwarded to the role="group" root',
     children: 'the DropdownMenuRadioItems',