@astryxdesign/core 0.7.6-canary.eecd9c1 → 0.7.6-canary.f73623d

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/dist/DropdownMenu/DropdownMenu.d.ts.map +1 -1
  2. package/dist/DropdownMenu/DropdownMenu.js +28 -19
  3. package/dist/Outline/Outline.d.ts.map +1 -1
  4. package/dist/Outline/Outline.js +27 -0
  5. package/dist/Popover/usePopover.d.ts.map +1 -1
  6. package/dist/Popover/usePopover.js +10 -3
  7. package/dist/RadioList/RadioListItem.d.ts.map +1 -1
  8. package/dist/RadioList/RadioListItem.js +5 -2
  9. package/dist/Table/Table.d.ts.map +1 -1
  10. package/dist/Table/Table.js +36 -10
  11. package/dist/Table/plugins/sortable/useTableSortable.d.ts.map +1 -1
  12. package/dist/Table/plugins/sortable/useTableSortable.js +46 -58
  13. package/dist/ToggleButton/ToggleButtonGroup.d.ts +7 -1
  14. package/dist/ToggleButton/ToggleButtonGroup.d.ts.map +1 -1
  15. package/dist/ToggleButton/ToggleButtonGroup.js +16 -2
  16. package/dist/Token/Token.d.ts.map +1 -1
  17. package/dist/Token/Token.js +37 -5
  18. package/dist/Token/TokenLink.d.ts.map +1 -1
  19. package/dist/Token/TokenLink.js +14 -2
  20. package/dist/i18n/generated-locales/af-ZA.generated.d.ts.map +1 -1
  21. package/dist/i18n/generated-locales/af-ZA.generated.js +0 -5
  22. package/dist/i18n/generated-locales/ar-SA.generated.d.ts.map +1 -1
  23. package/dist/i18n/generated-locales/ar-SA.generated.js +0 -5
  24. package/dist/i18n/generated-locales/ca-ES.generated.d.ts.map +1 -1
  25. package/dist/i18n/generated-locales/ca-ES.generated.js +0 -5
  26. package/dist/i18n/generated-locales/cs-CZ.generated.d.ts.map +1 -1
  27. package/dist/i18n/generated-locales/cs-CZ.generated.js +0 -5
  28. package/dist/i18n/generated-locales/da-DK.generated.d.ts.map +1 -1
  29. package/dist/i18n/generated-locales/da-DK.generated.js +0 -5
  30. package/dist/i18n/generated-locales/de-DE.generated.d.ts.map +1 -1
  31. package/dist/i18n/generated-locales/de-DE.generated.js +0 -5
  32. package/dist/i18n/generated-locales/el-GR.generated.d.ts.map +1 -1
  33. package/dist/i18n/generated-locales/el-GR.generated.js +0 -5
  34. package/dist/i18n/generated-locales/en.generated.d.ts.map +1 -1
  35. package/dist/i18n/generated-locales/en.generated.js +1 -5
  36. package/dist/i18n/generated-locales/es-ES.generated.d.ts.map +1 -1
  37. package/dist/i18n/generated-locales/es-ES.generated.js +0 -5
  38. package/dist/i18n/generated-locales/fi-FI.generated.d.ts.map +1 -1
  39. package/dist/i18n/generated-locales/fi-FI.generated.js +0 -5
  40. package/dist/i18n/generated-locales/fr-FR.generated.d.ts.map +1 -1
  41. package/dist/i18n/generated-locales/fr-FR.generated.js +0 -5
  42. package/dist/i18n/generated-locales/he-IL.generated.d.ts.map +1 -1
  43. package/dist/i18n/generated-locales/he-IL.generated.js +0 -5
  44. package/dist/i18n/generated-locales/hu-HU.generated.d.ts.map +1 -1
  45. package/dist/i18n/generated-locales/hu-HU.generated.js +0 -5
  46. package/dist/i18n/generated-locales/it-IT.generated.d.ts.map +1 -1
  47. package/dist/i18n/generated-locales/it-IT.generated.js +0 -5
  48. package/dist/i18n/generated-locales/ja-JP.generated.d.ts.map +1 -1
  49. package/dist/i18n/generated-locales/ja-JP.generated.js +0 -5
  50. package/dist/i18n/generated-locales/ko-KR.generated.d.ts.map +1 -1
  51. package/dist/i18n/generated-locales/ko-KR.generated.js +0 -5
  52. package/dist/i18n/generated-locales/nl-NL.generated.d.ts.map +1 -1
  53. package/dist/i18n/generated-locales/nl-NL.generated.js +0 -5
  54. package/dist/i18n/generated-locales/no-NO.generated.d.ts.map +1 -1
  55. package/dist/i18n/generated-locales/no-NO.generated.js +0 -5
  56. package/dist/i18n/generated-locales/pl-PL.generated.d.ts.map +1 -1
  57. package/dist/i18n/generated-locales/pl-PL.generated.js +0 -5
  58. package/dist/i18n/generated-locales/pseudo.generated.d.ts.map +1 -1
  59. package/dist/i18n/generated-locales/pseudo.generated.js +1 -5
  60. package/dist/i18n/generated-locales/pt-BR.generated.d.ts.map +1 -1
  61. package/dist/i18n/generated-locales/pt-BR.generated.js +0 -5
  62. package/dist/i18n/generated-locales/pt-PT.generated.d.ts.map +1 -1
  63. package/dist/i18n/generated-locales/pt-PT.generated.js +0 -5
  64. package/dist/i18n/generated-locales/ro-RO.generated.d.ts.map +1 -1
  65. package/dist/i18n/generated-locales/ro-RO.generated.js +0 -5
  66. package/dist/i18n/generated-locales/ru-RU.generated.d.ts.map +1 -1
  67. package/dist/i18n/generated-locales/ru-RU.generated.js +0 -5
  68. package/dist/i18n/generated-locales/sr-SP.generated.d.ts.map +1 -1
  69. package/dist/i18n/generated-locales/sr-SP.generated.js +0 -5
  70. package/dist/i18n/generated-locales/sv-SE.generated.d.ts.map +1 -1
  71. package/dist/i18n/generated-locales/sv-SE.generated.js +0 -5
  72. package/dist/i18n/generated-locales/tr-TR.generated.d.ts.map +1 -1
  73. package/dist/i18n/generated-locales/tr-TR.generated.js +0 -5
  74. package/dist/i18n/generated-locales/uk-UA.generated.d.ts.map +1 -1
  75. package/dist/i18n/generated-locales/uk-UA.generated.js +0 -5
  76. package/dist/i18n/generated-locales/vi-VN.generated.d.ts.map +1 -1
  77. package/dist/i18n/generated-locales/vi-VN.generated.js +0 -5
  78. package/dist/i18n/generated-locales/zh-CN.generated.d.ts.map +1 -1
  79. package/dist/i18n/generated-locales/zh-CN.generated.js +0 -5
  80. package/dist/i18n/generated-locales/zh-TW.generated.d.ts.map +1 -1
  81. package/dist/i18n/generated-locales/zh-TW.generated.js +0 -5
  82. package/locales/af-ZA.json +0 -21
  83. package/locales/ar-SA.json +0 -21
  84. package/locales/ca-ES.json +0 -21
  85. package/locales/cs-CZ.json +0 -21
  86. package/locales/da-DK.json +0 -21
  87. package/locales/de-DE.json +0 -21
  88. package/locales/el-GR.json +0 -21
  89. package/locales/en.json +3 -19
  90. package/locales/es-ES.json +0 -21
  91. package/locales/fi-FI.json +0 -21
  92. package/locales/fr-FR.json +0 -21
  93. package/locales/he-IL.json +0 -21
  94. package/locales/hu-HU.json +0 -21
  95. package/locales/it-IT.json +0 -21
  96. package/locales/ja-JP.json +0 -21
  97. package/locales/ko-KR.json +0 -21
  98. package/locales/nl-NL.json +0 -21
  99. package/locales/no-NO.json +0 -21
  100. package/locales/pl-PL.json +0 -21
  101. package/locales/pseudo.json +2 -14
  102. package/locales/pt-BR.json +0 -21
  103. package/locales/pt-PT.json +0 -21
  104. package/locales/ro-RO.json +0 -21
  105. package/locales/ru-RU.json +0 -21
  106. package/locales/sr-SP.json +0 -21
  107. package/locales/sv-SE.json +0 -21
  108. package/locales/tr-TR.json +0 -21
  109. package/locales/uk-UA.json +0 -21
  110. package/locales/vi-VN.json +0 -21
  111. package/locales/zh-CN.json +0 -21
  112. package/locales/zh-TW.json +0 -21
  113. package/package.json +4 -4
  114. package/src/Chat/ChatLayout.spec.md +41 -36
  115. package/src/Chat/ChatLayoutScrollButton.spec.md +87 -103
  116. package/src/Chat/ChatSendButton.spec.md +78 -67
  117. package/src/ContextMenu/ContextMenu.spec.md +84 -56
  118. package/src/ContextMenu/ContextMenuItem.spec.md +132 -0
  119. package/src/DropdownMenu/DropdownMenu.spec.md +198 -218
  120. package/src/DropdownMenu/DropdownMenu.test.tsx +117 -0
  121. package/src/DropdownMenu/DropdownMenu.tsx +33 -18
  122. package/src/DropdownMenu/DropdownMenuCheckboxItem.spec.md +192 -0
  123. package/src/DropdownMenu/DropdownMenuDivider.spec.md +25 -31
  124. package/src/DropdownMenu/DropdownMenuGroup.spec.md +145 -0
  125. package/src/DropdownMenu/DropdownMenuItem.spec.md +48 -42
  126. package/src/DropdownMenu/DropdownMenuRadioGroup.spec.md +34 -37
  127. package/src/DropdownMenu/DropdownMenuRadioItem.spec.md +54 -53
  128. package/src/DropdownMenu/DropdownMenuSubMenu.spec.md +47 -41
  129. package/src/EmptyState/EmptyState.spec.md +35 -29
  130. package/src/Outline/Outline.spec.md +165 -69
  131. package/src/Outline/Outline.test.tsx +67 -2
  132. package/src/Outline/Outline.tsx +23 -0
  133. package/src/Outline/modules/parseOutlineFromMarkdown.spec.md +3 -4
  134. package/src/Popover/Popover.test.tsx +44 -0
  135. package/src/Popover/usePopover.tsx +10 -3
  136. package/src/RadioList/RadioList.test.tsx +56 -0
  137. package/src/RadioList/RadioListItem.tsx +5 -2
  138. package/src/Table/Table.spec.md +1 -1
  139. package/src/Table/Table.test.tsx +32 -0
  140. package/src/Table/Table.tsx +43 -11
  141. package/src/Table/__tests__/Table.a11y.states.ts +1 -5
  142. package/src/Table/plugins/sortable/useTableSortable.test.tsx +73 -144
  143. package/src/Table/plugins/sortable/useTableSortable.tsx +44 -73
  144. package/src/Table/plugins/sortable/useTableSortableState.test.tsx +9 -21
  145. package/src/ToggleButton/ToggleButton.test.tsx +27 -0
  146. package/src/ToggleButton/ToggleButtonGroup.tsx +20 -1
  147. package/src/Token/Token.doc.mjs +2 -2
  148. package/src/Token/Token.spec.md +41 -51
  149. package/src/Token/Token.test.tsx +67 -0
  150. package/src/Token/Token.tsx +60 -5
  151. package/src/Token/TokenLink.tsx +21 -7
  152. package/src/i18n/generated-locales/af-ZA.generated.ts +0 -7
  153. package/src/i18n/generated-locales/ar-SA.generated.ts +0 -6
  154. package/src/i18n/generated-locales/ca-ES.generated.ts +0 -7
  155. package/src/i18n/generated-locales/cs-CZ.generated.ts +0 -6
  156. package/src/i18n/generated-locales/da-DK.generated.ts +0 -6
  157. package/src/i18n/generated-locales/de-DE.generated.ts +0 -6
  158. package/src/i18n/generated-locales/el-GR.generated.ts +0 -7
  159. package/src/i18n/generated-locales/en.generated.ts +1 -6
  160. package/src/i18n/generated-locales/es-ES.generated.ts +0 -7
  161. package/src/i18n/generated-locales/fi-FI.generated.ts +0 -6
  162. package/src/i18n/generated-locales/fr-FR.generated.ts +0 -7
  163. package/src/i18n/generated-locales/he-IL.generated.ts +0 -6
  164. package/src/i18n/generated-locales/hu-HU.generated.ts +0 -6
  165. package/src/i18n/generated-locales/it-IT.generated.ts +0 -7
  166. package/src/i18n/generated-locales/ja-JP.generated.ts +0 -6
  167. package/src/i18n/generated-locales/ko-KR.generated.ts +0 -6
  168. package/src/i18n/generated-locales/nl-NL.generated.ts +0 -6
  169. package/src/i18n/generated-locales/no-NO.generated.ts +0 -6
  170. package/src/i18n/generated-locales/pl-PL.generated.ts +0 -7
  171. package/src/i18n/generated-locales/pseudo.generated.ts +1 -6
  172. package/src/i18n/generated-locales/pt-BR.generated.ts +0 -7
  173. package/src/i18n/generated-locales/pt-PT.generated.ts +0 -7
  174. package/src/i18n/generated-locales/ro-RO.generated.ts +0 -6
  175. package/src/i18n/generated-locales/ru-RU.generated.ts +0 -7
  176. package/src/i18n/generated-locales/sr-SP.generated.ts +0 -6
  177. package/src/i18n/generated-locales/sv-SE.generated.ts +0 -6
  178. package/src/i18n/generated-locales/tr-TR.generated.ts +0 -7
  179. package/src/i18n/generated-locales/uk-UA.generated.ts +0 -7
  180. package/src/i18n/generated-locales/vi-VN.generated.ts +0 -6
  181. package/src/i18n/generated-locales/zh-CN.generated.ts +0 -6
  182. package/src/i18n/generated-locales/zh-TW.generated.ts +0 -6
@@ -3,11 +3,11 @@ schema_version: 3
3
3
  template_version: 7
4
4
  kind: component
5
5
  id: component:DropdownMenuRadioItem
6
- authority: draft
6
+ authority: current
7
7
  archive_reason: null
8
8
  superseded_by: null
9
- approved_by: null
10
- approved_at: null
9
+ approved_by: cixzhang
10
+ approved_at: 2026-10-31
11
11
  owners: [cixzhang]
12
12
  review_triggers: [public-api, behavior, accessibility, theming, testing]
13
13
  verified_by:
@@ -16,7 +16,6 @@ verified_by:
16
16
  packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
17
17
  packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
18
18
  packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioItemAudit.a11y.chromium.spec.ts,
19
- apps/storybook/stories/DropdownMenuRadioItem.stories.tsx,
20
19
  apps/storybook/rtl-audit/verified-not-applicable.json,
21
20
  scripts/check-knowledge.mjs,
22
21
  ]
@@ -31,22 +30,22 @@ architecture:
31
30
  architecture:interaction-modality,
32
31
  ]
33
32
  contributing: []
34
- system_specs: [spec:AST-020, spec:AST-029]
33
+ system_specs: [spec:AST-020]
35
34
  ---
36
35
 
37
36
  # DropdownMenuRadioItem component contract
38
37
 
39
38
  ## Contract at a glance
40
39
 
41
- | Area | Contract |
42
- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
43
- | Public contract | One `menuitemradio` row inside a DropdownMenuRadioGroup with a required value and label, optional description, icon, end content, disabled state, root inputs, and an explicit React 19 ref. |
44
- | Behavior | Enabled activation emits the row value through the group, applies the group close policy, then runs the caller click handler; disabled activation does none of these. |
45
- | End-user impact | Assistive technology hears one radio option with its checked state; pointer and keyboard selection commit the same value, and a disabled option cannot be chosen. |
46
- | Builder impact | Place the row inside a DropdownMenuRadioGroup and give it a unique value and a label; caller handlers run alongside the row's own behavior. |
47
- | Compatibility/readiness | Released subcomponent; observational draft of current behavior. Authority stays `draft` until owner approval. |
48
- | Review checks | Reject a nested semantic radio, a second keyboard owner, local selection state, a dropped caller input, or disabled activation that selects, closes, or calls the caller click handler. |
49
- | Governing rules | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV4–INV6`; `spec:AST-020/FR1,FR2`. |
40
+ | Area | Contract |
41
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42
+ | Public contract | One `menuitemradio` row inside a DropdownMenuRadioGroup with a required value and label, optional description, icon, end content, disabled state, root inputs, and a ref. |
43
+ | Behavior | Enabled activation emits the row value through the group, applies the group close policy, then runs the caller click handler; disabled activation does none of these. |
44
+ | End-user impact | Assistive technology hears one radio option with its checked state; pointer and keyboard selection commit the same value, and a disabled option cannot be chosen. |
45
+ | Builder impact | Place the row inside a DropdownMenuRadioGroup and give it a unique value and a label; caller handlers run alongside the row's own behavior. |
46
+ | Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. |
47
+ | Review checks | Reject a nested semantic radio, a second keyboard owner, local selection state, a dropped caller input, or disabled activation that selects, closes, or calls the caller click handler. |
48
+ | Governing rules | `spec:AST-020` FR15; `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV4–INV6`; `spec:AST-020/FR1,FR2`. |
50
49
 
51
50
  This table is a review projection; the body below is authoritative.
52
51
 
@@ -62,8 +61,8 @@ activation, and the menu lifecycle.
62
61
  ## Compatibility and migration
63
62
 
64
63
  - Released default preserved: yes (`isDisabled=false`).
65
- - Compatibility class: no public API change; caller `onClick` and
66
- `onPointerMove` compose with the row's own behavior.
64
+ - Compatibility class: records shipped behavior; no public prop, default,
65
+ export, or DOM change.
67
66
  - Controlled behavior: the checked state always derives from the group `value`;
68
67
  the row holds no selection state.
69
68
  - Migration decision: none.
@@ -106,19 +105,16 @@ Consumer migration instructions belong in consumer docs and release notes.
106
105
 
107
106
  ## Behavioral and layout contract
108
107
 
109
- Draft requirements identify their basis so observed code is not mistaken for an
110
- intentional decision.
111
-
112
- | ID | Candidate invariant | Basis | Draft review state |
113
- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ |
114
- | FR1 | The row MUST render one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It MUST NOT nest a native or ARIA radio. | WAI-ARIA menu pattern; current source and focused tests | verify |
115
- | FR2 | Rendering the row outside a DropdownMenuRadioGroup MUST throw. | Current source and focused tests | verify |
116
- | FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, MUST call the group `onChange` with the row value, then ask DropdownMenu to close when the group's close policy is on, then call the caller `onClick`. | Released behavior; `architecture:public-component-api/INV7`; focused tests | verify |
117
- | FR4 | A disabled row MUST expose `aria-disabled="true"`, render no `tabindex`, take no hover focus, and on any activation, including an assistive-technology click, MUST NOT call `onChange`, close the menu, or call the caller `onClick`. It paints at half opacity with a default cursor. | Current source, focused tests, and browser evidence | verify |
118
- | FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root. Caller `onPointerMove` MUST run after the row's hover focus, and caller handlers MUST NOT replace the row's own behavior. | `architecture:public-component-api/INV5–INV8`; focused tests | verify |
119
- | FR6 | The marker MUST be the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer. | Current source, focused tests, and browser evidence | verify |
120
- | FR7 | The row MUST carry the `dropdown-menu-item` target with the menu size and the marker MUST carry the `dropdown-menu-radio` target with size, checked, and disabled reflections. | `architecture:component-theming-surface/INV4–INV6`; current source/docs | verify |
121
- | FR8 | The row MUST add no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click. | `architecture:interaction-modality`; parent keyboard tests | verify |
108
+ | ID | Invariant | Basis |
109
+ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
110
+ | FR1 | The row renders one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It nests no native or ARIA radio. | `spec:AST-020`; current source and tests |
111
+ | FR2 | Rendering the row outside a DropdownMenuRadioGroup throws. | Current source and focused tests |
112
+ | FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls the group `onChange` with the row value, then asks DropdownMenu to close when the group's close policy is on, then calls the caller `onClick`. | `architecture:public-component-api` INV7; current behavior and tests |
113
+ | FR4 | A disabled row exposes `aria-disabled="true"`, renders no `tabindex`, takes no hover focus, and on any activation, including an assistive-technology click, calls neither `onChange` nor the caller `onClick` and does not close the menu. It paints at half opacity with a default cursor. | Current source and tests |
114
+ | FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root. Caller `onPointerMove` runs after the row's hover focus, and caller handlers do not replace the row's own behavior. | `architecture:public-component-api` INV5–INV8; current tests |
115
+ | FR6 | The marker is the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer. | Current source and tests |
116
+ | FR7 | The row carries the `dropdown-menu-item` target with the menu size and the marker carries the `dropdown-menu-radio` target with size, checked, and disabled reflections. | `architecture:component-theming-surface`; current source and docs |
117
+ | FR8 | The row adds no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click. | `architecture:interaction-modality`; parent keyboard tests |
122
118
 
123
119
  ### Allowed variation
124
120
 
@@ -165,23 +161,21 @@ intentional decision.
165
161
  - **AR3 — Keyboard ownership.** DropdownMenu owns focus movement and activation;
166
162
  the row adds no key handling. Whether disabled rows stay keyboard-discoverable
167
163
  is owned by `component:DropdownMenu` (its OQ1).
168
- - **AR4 — Focus visibility (objective gap).** Keyboard focus MUST be
169
- perceivable (WCAG 2.2 SC 2.4.7 and 1.4.11). The row currently paints focus
170
- only as the menu overlay tint with no outline, which measures about 1.1:1
171
- against the menu surface and paints nothing under forced colors. The
172
- remediation is a shared row-visual decision with `component:DropdownMenuItem`
173
- (its OQ2); this draft records the gap and does not settle it.
164
+ - **AR4 — Focus visibility.** Keyboard focus paints only the menu overlay
165
+ tint, about 1.1:1 against the menu surface in the default themes, with no
166
+ outline, and nothing under forced colors. The shared row
167
+ treatment is `component:DropdownMenuItem` OQ2.
174
168
 
175
169
  ## Design relationships
176
170
 
177
- | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
178
- | ---------------- | ---------------------------------------------------------------- | -------------------------------- | -------------- | ------------------ |
179
- | Row | Menu row paint and radius; focus paint is the AR4 objective gap. | Current source and menu tokens | structural | FR7, AR4 |
180
- | Radio marker | Shared radio Indicator at the menu's control size. | Shared radio Indicator | prominent | FR1, FR6 |
181
- | Disabled | Half-opacity row with a default cursor. | Current source | supporting | FR4 |
182
- | Direction/touch | Logical marker placement that mirrors and moves on touch. | Bidirectionality and current CSS | structural | FR6 |
171
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
172
+ | ---------------- | --------------------------------------------------------- | -------------------------------- | -------------- | ------------------ |
173
+ | Row | Menu row paint and radius; focus paint is AR4. | Current source and menu tokens | structural | FR7, AR4 |
174
+ | Radio marker | Shared radio Indicator at the menu's control size. | Shared radio Indicator | prominent | FR1, FR6 |
175
+ | Disabled | Half-opacity row with a default cursor. | Current source | supporting | FR4 |
176
+ | Direction/touch | Logical marker placement that mirrors and moves on touch. | Bidirectionality and current CSS | structural | FR6 |
183
177
 
184
- No new component-local visual decision is settled by this draft.
178
+ No component-local visual decision is recorded.
185
179
 
186
180
  ## Family and system relationships
187
181
 
@@ -195,21 +189,29 @@ No new component-local visual decision is settled by this draft.
195
189
  reflection.
196
190
  - `architecture:component-test-sufficiency` owns proportionate observable evidence.
197
191
  - `spec:AST-020` supplies WCAG/APG adoption and evidence-layer boundaries.
198
- - `spec:AST-029` keeps this observational draft separate from the audit receipt.
199
192
 
200
193
  ## Verification map
201
194
 
202
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
203
- | ------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
204
- | FR1, FR2, AR1 | `DropdownMenuSelectable.test.tsx`; reusable radio-group and Menu contracts; scoped axe | checked, unchecked, outside a group | A nested radio, wrong checked row, extra announced control, or missing throw fails | `audit:DropdownMenuRadioItem/§1,§4,§6` |
205
- | FR3, FR5, FR8 | `DropdownMenuSelectable.test.tsx` handler, keyboard, close, and ref cases; browser fixture counters | pointer and keyboard activation, close on/off, caller handlers | A dropped caller handler, wrong order, or missing close fails | `audit:DropdownMenuRadioItem/§3,§4,§6` |
206
- | FR4, AR2 | Disabled focused test with an assistive-technology click; browser disabled-hover frame | disabled checked/unchecked | Removing the disabled guard makes the focused test fail | `audit:DropdownMenuRadioItem/§1,§4` |
207
- | AR4 | Exact-head keyboard-focus and forced-colors frames with rendered contrast | Neutral/Butter light/dark focus, forced colors | Current frames record the gap; a remediation passes only with a perceivable indicator in every theme and under forced colors | `audit:DropdownMenuRadioItem/§1,§5` |
208
- | FR6, FR7 | Marker and target tests; exact-head Neutral/Butter/RTL/narrow/size/coarse/focus frames | sm/md/lg, fine/coarse, LTR/RTL, light/dark | A lost target or reflection, a marker that is announced, wrongly sized, or misplaced fails | `audit:DropdownMenuRadioItem/§2,§5,§9,§10` |
195
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
196
+ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
197
+ | FR1, AR1 | `DropdownMenuSelectable.test.tsx` "renders the shared radio indicator in the menu marker" and "composes caller root inputs without replacing the row semantics"; `Menu.a11y.test.tsx` menu binding cases | Checked and unchecked | A row that is not `menuitemradio` or a wrong `aria-checked` fails. Evidence gap: no test asserts the absence of a nested radio. | `audit:DropdownMenuRadioItem/semantics` |
198
+ | FR2 | `DropdownMenuSelectable.test.tsx` "throws when a radio item is used outside a group" | Outside a group | A row that renders outside a group fails. | `audit:DropdownMenuRadioItem/behavior` |
199
+ | FR3, FR8 | `DropdownMenuSelectable.test.tsx` "calls onChange with the selected value", "composes the caller click handler with the selection", "composes the caller click handler on keyboard activation", "keeps the menu open while controlled selection updates when requested"; `DropdownMenu.test.tsx` "activates a focused menuitemradio with Enter and a menuitemcheckbox with Space" | Pointer and keyboard activation; close off | A missing `onChange`, a dropped caller `onClick`, or a close despite the opt-out fails. Evidence gap: no test asserts the `onChange`, close, `onClick` order or the `tabindex="-1"` on enabled rows. | `audit:DropdownMenuRadioItem/behavior` |
200
+ | FR4, AR2 | `DropdownMenuSelectable.test.tsx` "does not select, close, or call the caller click handler when disabled"; `DropdownMenu.test.tsx` "does not move focus on hover for a disabled item" | Disabled | A selection, close, or caller `onClick` while disabled, or hover focus on a disabled row, fails. Evidence gap: no test asserts the absent `tabindex` or the half-opacity paint. | `audit:DropdownMenuRadioItem/behavior` |
201
+ | FR5 | `DropdownMenuSelectable.test.tsx` "composes caller root inputs without replacing the row semantics", "composes the caller pointer-move handler with menu hover focus", and "a ref reaches the menuitemradio element" | Ref, host attributes, class, style, pointer move | A dropped ref, attribute, class, style, or handler fails. Evidence gap: no test asserts `xstyle` on the row. | `audit:DropdownMenuRadioItem/api` |
202
+ | FR6, FR7 | `DropdownMenuSelectable.test.tsx` "renders the shared radio indicator in the menu marker"; `DropdownMenuRadioItemAudit.a11y.chromium.spec.ts` | Marker in the row | A missing shared radio marker fails. Evidence gap: no test asserts the marker size by menu size, its fine and coarse placement, or the `dropdown-menu-radio` reflections. | `audit:DropdownMenuRadioItem/visual` |
203
+ | AR4, PR1 | Evidence gap: no test asserts the focus paint, forced-colors focus, or the absence of lifecycle resources | — | — | `audit:DropdownMenuRadioItem/visual` |
204
+
205
+ ## Current-state impact
206
+
207
+ - **Focus visibility (AR4).** Keyboard focus on a radio row shows only an
208
+ overlay tint about 1.1:1 against the menu surface, and no indicator in
209
+ forced-colors mode; the shared row treatment is
210
+ `component:DropdownMenuItem` OQ2.
209
211
 
210
212
  ## Decision log
211
213
 
212
- None. This draft records current facts and introduces no product decision.
214
+ No component-local decision.
213
215
 
214
216
  ## Open questions
215
217
 
@@ -222,5 +224,4 @@ None. This draft records current facts and introduces no product decision.
222
224
  ## Content boundary
223
225
 
224
226
  This file does not duplicate consumer prop tables/examples, current audit scores,
225
- screenshot matrices, implementation steps, or group/parent contracts. The audit
226
- pull request owns the closed run evidence required by `spec:AST-029/FR5`.
227
+ screenshot matrices, implementation steps, or group/parent contracts. It links to their owners.
@@ -3,20 +3,20 @@ schema_version: 3
3
3
  template_version: 7
4
4
  kind: component
5
5
  id: component:DropdownMenuSubMenu
6
- authority: draft
6
+ authority: current
7
7
  archive_reason: null
8
8
  superseded_by: null
9
- approved_by: null
10
- approved_at: null
9
+ approved_by: cixzhang
10
+ approved_at: 2026-10-31
11
11
  owners: [cixzhang]
12
12
  review_triggers: [public-api, behavior, accessibility, theming, layout, testing]
13
13
  verified_by:
14
14
  [
15
15
  packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx,
16
+ packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx,
16
17
  packages/core/src/DropdownMenu/__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts,
17
18
  packages/core/src/DropdownMenu/__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts,
18
19
  packages/core/src/DropdownMenu/__tests__/DropdownMenuSubMenuAudit.a11y.chromium.spec.ts,
19
- apps/storybook/stories/DropdownMenuSubMenu.stories.tsx,
20
20
  apps/storybook/rtl-audit/targets.json,
21
21
  scripts/check-knowledge.mjs,
22
22
  ]
@@ -33,7 +33,7 @@ architecture:
33
33
  architecture:react-component-runtime,
34
34
  ]
35
35
  contributing: []
36
- system_specs: [spec:AST-020, spec:AST-029, spec:AST-086]
36
+ system_specs: [spec:AST-020, spec:AST-086]
37
37
  ---
38
38
 
39
39
  # DropdownMenuSubMenu component contract
@@ -46,9 +46,9 @@ system_specs: [spec:AST-020, spec:AST-029, spec:AST-086]
46
46
  | Behavior | The row reveals its children as a flyout beside it or as a drilled-in view led by a Back row; with a header or footer that surface is a modal dialog named by the row. |
47
47
  | End-user impact | Pointer, keyboard, and touch users reach nested commands from one row; assistive technology hears the row's popup kind and expanded state, and Escape or the close arrow returns to the row. |
48
48
  | Builder impact | Place the row inside a DropdownMenu or ContextMenu and give it a label and rows; data-driven menus get it from a nested `items` array. |
49
- | Compatibility/readiness | Released subcomponent; observational draft of current behavior. Authority stays `draft` until owner approval. |
49
+ | Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. |
50
50
  | Review checks | Reject a second keyboard owner, a lost popup state, a flyout that does not flip under RTL, a disabled row that opens, dropped caller inputs, or an open callback that misses a transition. |
51
- | Governing rules | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV8`; `architecture:react-component-runtime/INV2`; `architecture:layer-runtime`; `spec:AST-020/FR1,FR2`; `spec:AST-086/FR8`. |
51
+ | Governing rules | `spec:AST-020` FR15; `architecture:public-component-api/INV5–INV8`; `architecture:react-component-runtime/INV2`; `architecture:layer-runtime`; `spec:AST-020/FR1,FR2`; `spec:AST-086/FR8`. |
52
52
 
53
53
  This table is a review projection; the body below is authoritative.
54
54
 
@@ -66,7 +66,8 @@ host that a sub-menu with a header or footer renders into.
66
66
 
67
67
  - Released default preserved: yes (`isDisabled=false`, `hasSpinner=false`,
68
68
  `presentation='adaptive'`).
69
- - Compatibility class: no public API change.
69
+ - Compatibility class: records shipped behavior; no public prop, default,
70
+ export, or DOM change.
70
71
  - Controlled behavior: the open state is internal; `onOpenChange` reports it.
71
72
  - Migration decision: none.
72
73
 
@@ -107,20 +108,17 @@ Consumer migration instructions belong in consumer docs and release notes.
107
108
 
108
109
  ## Behavioral and layout contract
109
110
 
110
- Draft requirements identify their basis so observed code is not mistaken for an
111
- intentional decision.
112
-
113
- | ID | Candidate invariant | Basis | Draft review state |
114
- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
115
- | FR1 | The row MUST expose `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface MUST be labelled by the row. | WAI-ARIA menu pattern; current source and focused tests | verify |
116
- | FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) MUST open the surface; a keyboard open MUST focus its first row. Escape or the close arrow MUST close only this level and return focus to the row. A hover MUST open a flyout after an intent delay. | WAI-ARIA menu pattern; `architecture:interaction-modality`; tests | verify |
117
- | FR3 | A flyout MUST sit beside the row on the inline-end side, flip with direction, and stay within the viewport; its block size MUST cap at the smaller of its own cap and the viewport. | `architecture:layer-runtime`; current source and browser evidence | verify |
118
- | FR4 | A drilled-in view MUST replace the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow MUST return to the row. | Current source and focused tests | verify |
119
- | FR5 | Selecting a leaf row inside the surface MUST close every level and the root menu. | Current source, focused tests, and browser evidence | verify |
120
- | FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change. | Documented promise; `architecture:react-component-runtime/INV2` | objective gap: a drilled-in view reset by the root menu closing reports no `false` (owner: DropdownMenu) |
121
- | FR7 | A disabled row MUST expose `aria-disabled="true"`, render no `tabindex`, take no hover focus, open on no input, and run no caller `onClick`. | Current source, focused tests, and browser evidence | verify |
122
- | FR8 | With `hasSpinner` the row MUST show a decorative spinner in place of the caret and announce the busy start once the root menu shows. | `spec:AST-086/FR8`; current source | verify |
123
- | FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler. | `architecture:public-component-api/INV5–INV8`; focused tests | verify |
111
+ | ID | Invariant | Basis |
112
+ | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
113
+ | FR1 | The row exposes `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface is labelled by the row. | `spec:AST-020`; current source and tests |
114
+ | FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) opens the surface; a keyboard open focuses its first row. Escape or the close arrow closes only this level and returns focus to the row. A hover opens a flyout after an intent delay. | `spec:AST-020`; `architecture:interaction-modality`; current tests |
115
+ | FR3 | A flyout sits beside the row on the inline-end side, flips with direction, and stays within the viewport; its block size caps at the smaller of its own cap and the viewport. | `architecture:layer-runtime`; current source |
116
+ | FR4 | A drilled-in view replaces the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow return to the row. | Current source and focused tests |
117
+ | FR5 | Selecting a leaf row inside the surface closes every level and the root menu. | Current source and tests |
118
+ | FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change. Implementation gap: a drilled-in view reset by the root menu closing reports no `false` (OQ1). | Documented promise; `architecture:react-component-runtime` INV2 |
119
+ | FR7 | A disabled row exposes `aria-disabled="true"`, renders no `tabindex`, takes no hover focus, opens on no input, and runs no caller `onClick`. | Current source and tests |
120
+ | FR8 | With `hasSpinner` the row shows a decorative spinner in place of the caret and announces the busy start once the root menu shows. | `spec:AST-086` FR8; current source and tests |
121
+ | FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler. | `architecture:public-component-api` INV5–INV8; current tests |
124
122
 
125
123
  ### Allowed variation
126
124
 
@@ -164,12 +162,10 @@ intentional decision.
164
162
  Escape; a deeper level's keys never act on its parent.
165
163
  - **AR3 — Disabled discoverability.** Whether disabled rows stay
166
164
  keyboard-discoverable is owned by `component:DropdownMenu` (its OQ1).
167
- - **AR4 — Focus visibility (objective gap).** Keyboard focus MUST be
168
- perceivable (WCAG 2.2 SC 2.4.7 and 1.4.11). The row currently paints focus
169
- only as the menu overlay tint with no outline, and paints nothing under
170
- forced colors. The remediation is a shared row-visual decision with
171
- `component:DropdownMenuItem` (its OQ2); this draft records the gap and does
172
- not settle it.
165
+ - **AR4 — Focus visibility.** Keyboard focus paints only the menu overlay
166
+ tint, about 1.1:1 against the menu surface in the default themes, with no
167
+ outline, and nothing under forced colors. The shared row
168
+ treatment is `component:DropdownMenuItem` OQ2.
173
169
 
174
170
  ## Design relationships
175
171
 
@@ -181,7 +177,7 @@ intentional decision.
181
177
  | Drilled view | Rows inside the root's box, led by a mirrored Back row. | Current source | structural | FR4 |
182
178
  | Disabled | Half-opacity row with a default cursor. | Current source | supporting | FR7 |
183
179
 
184
- No new component-local visual decision is settled by this draft.
180
+ No component-local visual decision is recorded.
185
181
 
186
182
  ## Family and system relationships
187
183
 
@@ -193,22 +189,33 @@ No new component-local visual decision is settled by this draft.
193
189
  - `architecture:public-component-api` owns root input and handler composition.
194
190
  - `architecture:react-component-runtime` owns callback timing.
195
191
  - `spec:AST-086` owns the loading announcement.
196
- - `spec:AST-029` keeps this observational draft separate from the audit receipt.
197
192
 
198
193
  ## Verification map
199
194
 
200
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
201
- | ------------- | ----------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------- |
202
- | FR1, FR2, AR2 | `DropdownMenuSubMenu.test.tsx` keyboard, hover, typeahead, and nesting suites | open, close, nested, loading | A lost popup state, wrong focus target, or double-stepped level fails | `audit:DropdownMenuSubMenu/§1,§4,§6` |
203
- | FR3 | RTL D4 flyout target; exact-head LTR/RTL/narrow open frames | LTR, RTL, 320px | A flyout on the wrong side or outside the viewport fails | `audit:DropdownMenuSubMenu/§5,§9,§10` |
204
- | FR4, FR5 | Drill-in and selection tests; exact-head drill-in and select frames | drilled, nested selection | A missing Back row or a stack that stays open fails | `audit:DropdownMenuSubMenu/§4` |
205
- | FR6 | onOpenChange test (mutation-sensitive); browser select-frame counters | flyout open and close | Dropping the close report fails; the drill-in reset gap is recorded, not asserted | `audit:DropdownMenuSubMenu/§3,§4` |
206
- | FR7, FR9 | Host-attribute, handler, and disabled tests; disabled-hover frames | disabled, caller handlers, test ids | A disabled open or dropped caller input fails | `audit:DropdownMenuSubMenu/§1,§3` |
207
- | AR4 | Exact-head keyboard-focus and forced-colors frames with rendered contrast | Neutral/Butter focus, forced colors | Current frames record the gap; a remediation passes only with a perceivable indicator | `audit:DropdownMenuSubMenu/§1,§5` |
195
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
196
+ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
197
+ | FR1, AR1 | `DropdownMenuSubMenu.test.tsx` "renders the trigger with aria-haspopup and collapsed aria-expanded", "names the flyout from its trigger via aria-labelledby", "the row keeps its own popup state and tab stop"; header-and-footer case "holds the header, the rows and the footer in a dialog named by the row, outside every menu" | Closed and open; with regions | A missing `aria-haspopup`, `aria-expanded`, or row label on the surface fails. Evidence gap: no test asserts `aria-controls` while open. | `audit:DropdownMenuSubMenu/semantics` |
198
+ | FR2, AR2 | `DropdownMenuSubMenu.test.tsx` "opens the flyout on trigger click and exposes its items", "opens on ArrowRight and returns focus to the trigger on ArrowLeft", "mirrors its indicator and keyboard directions under RTL", "closes only the submenu on Escape and restores focus to the trigger", "supports first-character type-ahead within the flyout", "navigates a two-level nested submenu without double-stepping", "moves focus to the submenu trigger on hover, keeping a single highlight"; hover/click-guard cases | Click, arrows, RTL, Escape, hover, nesting | A key that does not open or close, a wrong focus target, a double-stepped level, or a reversed RTL arrow fails. Evidence gap: no test asserts Enter or Space opening the row. | `audit:DropdownMenuSubMenu/accessibility` |
199
+ | FR3 | `DropdownMenuSubMenu.test.tsx` "caps the flyout width and height to the available viewport"; `apps/storybook/rtl-audit/targets.json` DropdownMenuSubMenu entry | Viewport cap; RTL | A flyout that escapes the viewport fails. Evidence gap: no test asserts the inline-end placement or its flip. | `audit:DropdownMenuSubMenu/layout` |
200
+ | FR4 | `DropdownMenuSubMenu.test.tsx` drill-in cases; `DropdownMenuDrillIn.a11y.chromium.spec.ts` | Drilled view; Back | A missing Back row or a Back that does not return fails. | `audit:DropdownMenuSubMenu/behavior` |
201
+ | FR5 | `DropdownMenuSubMenu.test.tsx` "closes the whole menu after selecting a nested item" and "activates a nested item with the Enter key and closes the menu" | Pointer and Enter | A level left open after a leaf pick fails. | `audit:DropdownMenuSubMenu/behavior` |
202
+ | FR6 | `DropdownMenuSubMenu.test.tsx` "reports each flyout open and close to onOpenChange once" | Flyout open and close | A missing or repeated report fails. Evidence gap: the drill-in reset gap is not asserted. | `audit:DropdownMenuSubMenu/behavior` |
203
+ | FR7, FR9 | `DropdownMenuSubMenu.test.tsx` "does not open a disabled submenu", "a disabled row does not pass a click on to the caller's onClick", host-attribute and ref cases ("aria-\*, data-\* and id reach the trigger row, and the flyout stays labelled by it", "a ref reaches the trigger row", "a caller's handlers run after the row's own, and the row still opens and takes the hover focus") | Disabled; caller handlers and attributes | A disabled open or caller click, or a dropped attribute, ref, or handler, fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the row. | `audit:DropdownMenuSubMenu/api` |
204
+ | FR8 | `BusyOwnerAnnouncement.test.tsx` "DropdownMenuSubMenu loading state" cases; `DropdownMenuSubMenu.test.tsx` loading-flyout cases | Loading closed and open | A busy start announced while closed, twice, or not at all, or an announced Spinner, fails. | `audit:DropdownMenuSubMenu/accessibility` |
205
+ | AR4, PR1 | Evidence gap: no test asserts the focus paint, forced-colors focus, or the timer bounds | — | — | `audit:DropdownMenuSubMenu/visual` |
206
+
207
+ ## Current-state impact
208
+
209
+ - **Drill-in close report (FR6).** When the root menu closes a drilled-in view,
210
+ `onOpenChange(false)` does not run (OQ1).
211
+ - **Focus visibility (AR4).** Keyboard focus on the row shows only an
212
+ overlay tint about 1.1:1 against the menu surface, and no indicator in
213
+ forced-colors mode; the shared row treatment is
214
+ `component:DropdownMenuItem` OQ2.
208
215
 
209
216
  ## Decision log
210
217
 
211
- None. This draft records current facts and introduces no product decision.
218
+ No component-local decision.
212
219
 
213
220
  ## Open questions
214
221
 
@@ -221,5 +228,4 @@ None. This draft records current facts and introduces no product decision.
221
228
  ## Content boundary
222
229
 
223
230
  This file does not duplicate consumer prop tables/examples, current audit scores,
224
- screenshot matrices, implementation steps, or root/leaf contracts. The audit
225
- pull request owns the closed run evidence required by `spec:AST-029/FR5`.
231
+ screenshot matrices, implementation steps, or root/leaf contracts. It links to their owners.
@@ -3,16 +3,19 @@ schema_version: 3
3
3
  template_version: 7
4
4
  kind: component
5
5
  id: component:EmptyState
6
- authority: draft
6
+ authority: current
7
7
  archive_reason: null
8
8
  superseded_by: null
9
- approved_by: null
10
- approved_at: null
9
+ approved_by: cixzhang
10
+ approved_at: 2026-10-31
11
11
  owners: [cixzhang]
12
12
  review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
13
13
  verified_by:
14
14
  [
15
15
  packages/core/src/EmptyState/EmptyState.test.tsx,
16
+ packages/core/src/EmptyState/EmptyState.announce.test.tsx,
17
+ .github/visual-baseline/manifest.json,
18
+ scripts/check-knowledge.mjs,
16
19
  packages/core/src/theme/themingTargets.test.ts,
17
20
  packages/core/src/docPropReferences.test.ts,
18
21
  ]
@@ -27,7 +30,7 @@ architecture:
27
30
  ]
28
31
  contributing: []
29
32
  system_specs:
30
- [spec:AST-020/FR1, spec:AST-029/FR3, spec:AST-086/FR2, spec:AST-086/FR11]
33
+ [spec:AST-009, spec:AST-020/FR1, spec:AST-086/FR2, spec:AST-086/FR11]
31
34
  ---
32
35
 
33
36
  # EmptyState component contract
@@ -39,8 +42,8 @@ system_specs:
39
42
  | Public contract | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one root without a live role; callers choose heading level and compact layout. |
40
43
  | Behavior | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions. |
41
44
  | End-user impact | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline. |
42
- | Builder impact | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required. |
43
- | Compatibility/readiness | No live role on the root; an EmptyState that appears after load announces once (`spec:AST-086` FR2). Otherwise this draft observes shipped behavior and the scalar-slot remediation. |
45
+ | Builder impact | None; the record describes shipped behavior. |
46
+ | Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. |
44
47
  | Review checks | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
45
48
  | Governing rules | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2. |
46
49
 
@@ -53,10 +56,12 @@ context, optional decorative visual, and optional caller-owned next actions.
53
56
 
54
57
  ## Compatibility and migration
55
58
 
56
- - Released default preserved: no; EmptyState adds no live role to the root
57
- - Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values and removes the root's live role
59
+ - Released default preserved: `yes` — heading level 3, default layout, no
60
+ live role on the root.
61
+ - Compatibility class: records shipped behavior; no public prop, default, DOM,
62
+ target, or styling output changes.
58
63
  - Controlled/uncontrolled behavior: not applicable
59
- - Migration decision: none; an EmptyState rendered with the page announces nothing, and one that appears later announces its message once through the shared polite channel, so apps need no change (`spec:AST-086` FR2)
64
+ - Migration decision: none
60
65
 
61
66
  Consumer migration instructions belong in consumer docs and release notes.
62
67
 
@@ -87,17 +92,14 @@ Consumer migration instructions belong in consumer docs and release notes.
87
92
 
88
93
  ## Behavioral and layout contract
89
94
 
90
- Draft requirements identify their basis so observed code is not mistaken for an
91
- intentional decision. A `current` contract contains no unresolved rows.
92
-
93
- | ID | Candidate invariant | Basis | Draft review state |
94
- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
95
- | FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root. | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2 | verify |
96
- | FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role. | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6 | verify |
97
- | FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify |
98
- | FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered. | Current implementation and tests; WCAG 2.2 SC 1.1.1 | verify |
99
- | FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root. | `architecture:public-component-api` INV5–INV8 | verify |
100
- | FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics. | Current implementation, tests, and consumer docs | verify |
95
+ | ID | Invariant | Basis |
96
+ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
97
+ | FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root. | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2 |
98
+ | FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role. | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6 |
99
+ | FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface |
100
+ | FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered. | Current implementation and tests; WCAG 2.2 SC 1.1.1 |
101
+ | FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root. | `architecture:public-component-api` INV5–INV8 |
102
+ | FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics. | Current implementation, tests, and consumer docs |
101
103
 
102
104
  ### Allowed variation
103
105
 
@@ -126,8 +128,9 @@ intentional decision. A `current` contract contains no unresolved rows.
126
128
 
127
129
  ### Performance and resources
128
130
 
129
- - **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
130
- observer, timer, or external resource.
131
+ - **PR1 — No resources of its own.** EmptyState holds no state, listener,
132
+ observer, or timer of its own; the shared announcement wrapper around its
133
+ text owns the observation that announces it (`spec:AST-086`).
131
134
 
132
135
  ## Accessibility contract
133
136
 
@@ -176,16 +179,19 @@ No current family record owns EmptyState-specific behavior.
176
179
 
177
180
  ## Verification map
178
181
 
179
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
180
- | -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
181
- | FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence | title only, all slots, absent/shallow-empty slots | order, heading, live role, or decorative treatment regresses | `audit:EmptyState/a11y` |
182
- | FR5, ORD1 | focused root composition tests plus shared API guards | DOM/data/event/style inputs, ref, root target | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api` |
183
- | FR6 | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow | compact state, spacing, or action direction no longer applies | `audit:EmptyState/layout` |
184
- | PR1 | source review | every render path | a retained resource appears without a named owner | `audit:EmptyState/code` |
182
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
183
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
184
+ | FR1, FR3, FR4, AR2 | `EmptyState.test.tsx` slot, order, decorative-icon, empty-slot, and live-role tests; stable visual baseline `core-emptystate--default` | Title only; all slots; absent and shallow-empty slots | A wrapper for an absent or shallow-empty slot, a changed slot order, an icon not hidden from assistive technology, or a live role on the root fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the hidden icon or the heading (`spec:AST-009` FR3). | `audit:EmptyState/a11y` |
185
+ | FR2, AR1 | `EmptyState.test.tsx` heading tests | Default level 3; every level | A title that is not the selected heading element fails. Gap: no check that the title keeps one type style at every heading level. | `audit:EmptyState/a11y` |
186
+ | AR3 | `EmptyState.announce.test.tsx` | Render with the page; appear later; iframe; inside a live container; message change; server render and hydration; hidden and revealed | An announcement during load or hydration, a missing or repeated announcement when it appears or changes later, hidden text in the message, or an announcement inside a live container fails. Gap: no test asserts that focus stays where it was when EmptyState appears. | `audit:EmptyState/a11y` |
187
+ | FR5, ORD1 | `EmptyState.test.tsx` ref, `data-testid`, and root-composition tests | DOM, data, event, style inputs; caller role; ref | A dropped input, a replaced caller role, or a ref that is not a `div` fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root. No test asserts that caller `xstyle` follows the component styles. | `audit:EmptyState/api` |
188
+ | FR6 | `EmptyState.test.tsx` compact and theming-target tests | Default and compact | A compact layout that is not reflected on the root, title, and description, or that changes slot order, fails. Gap: the reduced spacing and stacked actions have no automated check. | `audit:EmptyState/layout` |
189
+ | PR1 | Source review | Every render path | Gap: no automated check fails if EmptyState adds state, a listener, or a timer of its own. | `audit:EmptyState/code` |
190
+ | Theming anatomy map | `scripts/check-knowledge.mjs`; `themingTargets.test.ts` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:EmptyState/theming` |
185
191
 
186
192
  ## Decision log
187
193
 
188
- No component-local decision is approved in this draft.
194
+ None recorded. The record describes shipped behavior.
189
195
 
190
196
  ## Open questions
191
197