@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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 (576) hide show
  1. package/dist/components/Accordion/accordion.d.ts +1 -1
  2. package/dist/components/Accordion/accordion.d.ts.map +1 -1
  3. package/dist/components/Accordion/accordion.js +8 -3
  4. package/dist/components/Accordion/accordion.js.map +1 -1
  5. package/dist/components/AccountMenu/account-menu.d.ts.map +1 -1
  6. package/dist/components/AccountMenu/account-menu.js.map +1 -1
  7. package/dist/components/AgentPanel/agent-panel-fab.d.ts +7 -1
  8. package/dist/components/AgentPanel/agent-panel-fab.d.ts.map +1 -1
  9. package/dist/components/AgentPanel/agent-panel-fab.js +36 -14
  10. package/dist/components/AgentPanel/agent-panel-fab.js.map +1 -1
  11. package/dist/components/AgentPanel/agent-panel-logo.d.ts +3 -3
  12. package/dist/components/AgentPanel/agent-panel-logo.js.map +1 -1
  13. package/dist/components/AgentPanel/agent-panel.d.ts +1 -1
  14. package/dist/components/AgentPanel/agent-panel.d.ts.map +1 -1
  15. package/dist/components/AgentPanel/agent-panel.js +28 -22
  16. package/dist/components/AgentPanel/agent-panel.js.map +1 -1
  17. package/dist/components/AppShell/app-shell.d.ts +1 -1
  18. package/dist/components/AppShell/app-shell.js +1 -1
  19. package/dist/components/AppShell/app-shell.js.map +1 -1
  20. package/dist/components/Avatar/avatar.d.ts +95 -1
  21. package/dist/components/Avatar/avatar.d.ts.map +1 -1
  22. package/dist/components/Avatar/avatar.js +106 -15
  23. package/dist/components/Avatar/avatar.js.map +1 -1
  24. package/dist/components/Avatar/index.js +14 -2
  25. package/dist/components/Breadcrumb/breadcrumb.d.ts +4 -2
  26. package/dist/components/Breadcrumb/breadcrumb.d.ts.map +1 -1
  27. package/dist/components/Breadcrumb/breadcrumb.js +2 -2
  28. package/dist/components/Breadcrumb/breadcrumb.js.map +1 -1
  29. package/dist/components/BulkActionBar/bulk-action-bar.d.ts.map +1 -1
  30. package/dist/components/BulkActionBar/bulk-action-bar.js +27 -2
  31. package/dist/components/BulkActionBar/bulk-action-bar.js.map +1 -1
  32. package/dist/components/Button/button.d.ts +2 -2
  33. package/dist/components/Button/button.d.ts.map +1 -1
  34. package/dist/components/Button/button.js +118 -22
  35. package/dist/components/Button/button.js.map +1 -1
  36. package/dist/components/Calendar/calendar.d.ts +34 -10
  37. package/dist/components/Calendar/calendar.d.ts.map +1 -1
  38. package/dist/components/Calendar/calendar.js +210 -36
  39. package/dist/components/Calendar/calendar.js.map +1 -1
  40. package/dist/components/Carousel/carousel.d.ts +1 -1
  41. package/dist/components/Carousel/carousel.d.ts.map +1 -1
  42. package/dist/components/Carousel/carousel.js +3 -2
  43. package/dist/components/Carousel/carousel.js.map +1 -1
  44. package/dist/components/Chart/chart.d.ts +1 -0
  45. package/dist/components/Chart/chart.d.ts.map +1 -1
  46. package/dist/components/Chart/chart.js +8 -0
  47. package/dist/components/Chart/chart.js.map +1 -1
  48. package/dist/components/Checkbox/checkbox.d.ts +1 -1
  49. package/dist/components/Checkbox/checkbox.d.ts.map +1 -1
  50. package/dist/components/Checkbox/checkbox.js +10 -2
  51. package/dist/components/Checkbox/checkbox.js.map +1 -1
  52. package/dist/components/Chip/chip.d.ts +1 -1
  53. package/dist/components/Chip/chip.d.ts.map +1 -1
  54. package/dist/components/Chip/chip.js +4 -2
  55. package/dist/components/Chip/chip.js.map +1 -1
  56. package/dist/components/Combobox/combobox.d.ts +1 -1
  57. package/dist/components/Combobox/combobox.d.ts.map +1 -1
  58. package/dist/components/Combobox/combobox.js +37 -11
  59. package/dist/components/Combobox/combobox.js.map +1 -1
  60. package/dist/components/Command/command.d.ts +1 -1
  61. package/dist/components/Command/command.d.ts.map +1 -1
  62. package/dist/components/Command/command.js +106 -8
  63. package/dist/components/Command/command.js.map +1 -1
  64. package/dist/components/DataTable/cell-registry.d.ts.map +1 -1
  65. package/dist/components/DataTable/cell-registry.js +3 -2
  66. package/dist/components/DataTable/cell-registry.js.map +1 -1
  67. package/dist/components/DataTable/data-table-column-visibility-panel.d.ts.map +1 -1
  68. package/dist/components/DataTable/data-table-column-visibility-panel.js +24 -24
  69. package/dist/components/DataTable/data-table-column-visibility-panel.js.map +1 -1
  70. package/dist/components/DataTable/data-table-interaction-layer.d.ts +2 -1
  71. package/dist/components/DataTable/data-table-interaction-layer.d.ts.map +1 -1
  72. package/dist/components/DataTable/data-table-interaction-layer.js +3 -4
  73. package/dist/components/DataTable/data-table-interaction-layer.js.map +1 -1
  74. package/dist/components/DataTable/data-table-sort-manager.d.ts.map +1 -1
  75. package/dist/components/DataTable/data-table-sort-manager.js +20 -20
  76. package/dist/components/DataTable/data-table-sort-manager.js.map +1 -1
  77. package/dist/components/DataTable/data-table.d.ts +8 -5
  78. package/dist/components/DataTable/data-table.d.ts.map +1 -1
  79. package/dist/components/DataTable/data-table.js +197 -71
  80. package/dist/components/DataTable/data-table.js.map +1 -1
  81. package/dist/components/DateGrid/date-grid.d.ts +1 -1
  82. package/dist/components/DateGrid/date-grid.d.ts.map +1 -1
  83. package/dist/components/DateGrid/date-grid.js +358 -225
  84. package/dist/components/DateGrid/date-grid.js.map +1 -1
  85. package/dist/components/DatePicker/date-picker.d.ts.map +1 -1
  86. package/dist/components/DatePicker/date-picker.js +16 -1
  87. package/dist/components/DatePicker/date-picker.js.map +1 -1
  88. package/dist/components/Dialog/dialog.d.ts.map +1 -1
  89. package/dist/components/Dialog/dialog.js +55 -43
  90. package/dist/components/Dialog/dialog.js.map +1 -1
  91. package/dist/components/DropdownMenu/dropdown-menu-keyboard.d.ts +86 -0
  92. package/dist/components/DropdownMenu/dropdown-menu-keyboard.d.ts.map +1 -0
  93. package/dist/components/DropdownMenu/dropdown-menu-keyboard.js +172 -0
  94. package/dist/components/DropdownMenu/dropdown-menu-keyboard.js.map +1 -0
  95. package/dist/components/DropdownMenu/dropdown-menu.d.ts +6 -1
  96. package/dist/components/DropdownMenu/dropdown-menu.d.ts.map +1 -1
  97. package/dist/components/DropdownMenu/dropdown-menu.js +50 -39
  98. package/dist/components/DropdownMenu/dropdown-menu.js.map +1 -1
  99. package/dist/components/Field/field-context.d.ts +4 -0
  100. package/dist/components/Field/field-context.d.ts.map +1 -1
  101. package/dist/components/Field/field-context.js +1 -2
  102. package/dist/components/Field/field-context.js.map +1 -1
  103. package/dist/components/Field/field-edit-keys.d.ts +8 -0
  104. package/dist/components/Field/field-edit-keys.d.ts.map +1 -1
  105. package/dist/components/Field/field-edit-keys.js +3 -0
  106. package/dist/components/Field/field-edit-keys.js.map +1 -1
  107. package/dist/components/Field/field-wrapper.d.ts +18 -1
  108. package/dist/components/Field/field-wrapper.d.ts.map +1 -1
  109. package/dist/components/Field/field-wrapper.js +39 -10
  110. package/dist/components/Field/field-wrapper.js.map +1 -1
  111. package/dist/components/Field/field.d.ts +3 -2
  112. package/dist/components/Field/field.d.ts.map +1 -1
  113. package/dist/components/Field/field.js +2 -1
  114. package/dist/components/Field/field.js.map +1 -1
  115. package/dist/components/FileItem/file-item.d.ts +26 -2
  116. package/dist/components/FileItem/file-item.d.ts.map +1 -1
  117. package/dist/components/FileItem/file-item.js +82 -25
  118. package/dist/components/FileItem/file-item.js.map +1 -1
  119. package/dist/components/FileItem/index.js +4 -2
  120. package/dist/components/FileUpload/file-upload.d.ts +1 -1
  121. package/dist/components/FileUpload/file-upload.d.ts.map +1 -1
  122. package/dist/components/FileUpload/file-upload.js +132 -55
  123. package/dist/components/FileUpload/file-upload.js.map +1 -1
  124. package/dist/components/FileViewer/file-viewer.d.ts +1 -1
  125. package/dist/components/FileViewer/file-viewer.d.ts.map +1 -1
  126. package/dist/components/FileViewer/file-viewer.js +9 -4
  127. package/dist/components/FileViewer/file-viewer.js.map +1 -1
  128. package/dist/components/InlineEdit/inline-edit.d.ts.map +1 -1
  129. package/dist/components/InlineEdit/inline-edit.js +1 -1
  130. package/dist/components/InlineEdit/inline-edit.js.map +1 -1
  131. package/dist/components/Input/input.d.ts.map +1 -1
  132. package/dist/components/Input/input.js +6 -1
  133. package/dist/components/Input/input.js.map +1 -1
  134. package/dist/components/LinkInput/link-input.d.ts.map +1 -1
  135. package/dist/components/LinkInput/link-input.js +20 -4
  136. package/dist/components/LinkInput/link-input.js.map +1 -1
  137. package/dist/components/Notice/notice.js +1 -1
  138. package/dist/components/Notice/notice.js.map +1 -1
  139. package/dist/components/NumberInput/number-input.d.ts.map +1 -1
  140. package/dist/components/NumberInput/number-input.js +6 -1
  141. package/dist/components/NumberInput/number-input.js.map +1 -1
  142. package/dist/components/OverflowIndicator/index.js +2 -1
  143. package/dist/components/OverflowIndicator/overflow-indicator.d.ts +19 -1
  144. package/dist/components/OverflowIndicator/overflow-indicator.d.ts.map +1 -1
  145. package/dist/components/OverflowIndicator/overflow-indicator.js +47 -27
  146. package/dist/components/OverflowIndicator/overflow-indicator.js.map +1 -1
  147. package/dist/components/Pagination/pagination.d.ts +1 -1
  148. package/dist/components/Pagination/pagination.js +1 -1
  149. package/dist/components/Pagination/pagination.js.map +1 -1
  150. package/dist/components/PeoplePicker/avatar-stack-overflow.d.ts +7 -6
  151. package/dist/components/PeoplePicker/avatar-stack-overflow.d.ts.map +1 -1
  152. package/dist/components/PeoplePicker/avatar-stack-overflow.js +6 -7
  153. package/dist/components/PeoplePicker/avatar-stack-overflow.js.map +1 -1
  154. package/dist/components/PeoplePicker/people-picker-helpers.d.ts.map +1 -1
  155. package/dist/components/PeoplePicker/people-picker-helpers.js +1 -1
  156. package/dist/components/PeoplePicker/people-picker-helpers.js.map +1 -1
  157. package/dist/components/PeoplePicker/people-picker.d.ts.map +1 -1
  158. package/dist/components/PeoplePicker/people-picker.js +2 -2
  159. package/dist/components/PeoplePicker/people-picker.js.map +1 -1
  160. package/dist/components/PeoplePicker/person-display.d.ts.map +1 -1
  161. package/dist/components/PeoplePicker/person-display.js +26 -28
  162. package/dist/components/PeoplePicker/person-display.js.map +1 -1
  163. package/dist/components/ProfileCard/profile-card.d.ts.map +1 -1
  164. package/dist/components/ProfileCard/profile-card.js.map +1 -1
  165. package/dist/components/RadioGroup/radio-group.d.ts +1 -1
  166. package/dist/components/RadioGroup/radio-group.d.ts.map +1 -1
  167. package/dist/components/RadioGroup/radio-group.js +10 -4
  168. package/dist/components/RadioGroup/radio-group.js.map +1 -1
  169. package/dist/components/Rating/rating.d.ts +28 -6
  170. package/dist/components/Rating/rating.d.ts.map +1 -1
  171. package/dist/components/Rating/rating.js +97 -80
  172. package/dist/components/Rating/rating.js.map +1 -1
  173. package/dist/components/ScrollArea/scroll-area.d.ts +1 -1
  174. package/dist/components/ScrollArea/scroll-area.js +1 -1
  175. package/dist/components/ScrollArea/scroll-area.js.map +1 -1
  176. package/dist/components/SegmentedControl/segmented-control.d.ts +1 -1
  177. package/dist/components/SegmentedControl/segmented-control.d.ts.map +1 -1
  178. package/dist/components/SegmentedControl/segmented-control.js +3 -2
  179. package/dist/components/SegmentedControl/segmented-control.js.map +1 -1
  180. package/dist/components/Select/select.d.ts.map +1 -1
  181. package/dist/components/Select/select.js +15 -8
  182. package/dist/components/Select/select.js.map +1 -1
  183. package/dist/components/SelectMenu/index.js +2 -1
  184. package/dist/components/SelectMenu/index.js.map +1 -1
  185. package/dist/components/SelectMenu/select-menu-keyboard.d.ts +59 -0
  186. package/dist/components/SelectMenu/select-menu-keyboard.d.ts.map +1 -0
  187. package/dist/components/SelectMenu/select-menu-keyboard.js +107 -0
  188. package/dist/components/SelectMenu/select-menu-keyboard.js.map +1 -0
  189. package/dist/components/SelectMenu/select-menu.d.ts +1 -22
  190. package/dist/components/SelectMenu/select-menu.d.ts.map +1 -1
  191. package/dist/components/SelectMenu/select-menu.js +18 -34
  192. package/dist/components/SelectMenu/select-menu.js.map +1 -1
  193. package/dist/components/SelectionControl/selection-item.d.ts.map +1 -1
  194. package/dist/components/SelectionControl/selection-item.js +1 -0
  195. package/dist/components/SelectionControl/selection-item.js.map +1 -1
  196. package/dist/components/Sidebar/sidebar.d.ts +7 -9
  197. package/dist/components/Sidebar/sidebar.d.ts.map +1 -1
  198. package/dist/components/Sidebar/sidebar.js +171 -50
  199. package/dist/components/Sidebar/sidebar.js.map +1 -1
  200. package/dist/components/Slider/slider.d.ts +1 -1
  201. package/dist/components/Slider/slider.d.ts.map +1 -1
  202. package/dist/components/Slider/slider.js +9 -4
  203. package/dist/components/Slider/slider.js.map +1 -1
  204. package/dist/components/Steps/steps.d.ts.map +1 -1
  205. package/dist/components/Steps/steps.js +54 -26
  206. package/dist/components/Steps/steps.js.map +1 -1
  207. package/dist/components/Switch/switch.d.ts +1 -1
  208. package/dist/components/Switch/switch.d.ts.map +1 -1
  209. package/dist/components/Switch/switch.js +7 -2
  210. package/dist/components/Switch/switch.js.map +1 -1
  211. package/dist/components/Tabs/tabs.d.ts +1 -1
  212. package/dist/components/Tabs/tabs.d.ts.map +1 -1
  213. package/dist/components/Tabs/tabs.js +39 -4
  214. package/dist/components/Tabs/tabs.js.map +1 -1
  215. package/dist/components/Tag/tag.d.ts +1 -1
  216. package/dist/components/Tag/tag.d.ts.map +1 -1
  217. package/dist/components/Tag/tag.js +3 -2
  218. package/dist/components/Tag/tag.js.map +1 -1
  219. package/dist/components/Textarea/textarea.d.ts.map +1 -1
  220. package/dist/components/Textarea/textarea.js +8 -2
  221. package/dist/components/Textarea/textarea.js.map +1 -1
  222. package/dist/components/TimePicker/time-columns.d.ts.map +1 -1
  223. package/dist/components/TimePicker/time-columns.js +8 -4
  224. package/dist/components/TimePicker/time-columns.js.map +1 -1
  225. package/dist/components/TimePicker/time-picker.d.ts +1 -1
  226. package/dist/components/TimePicker/time-picker.js +1 -1
  227. package/dist/components/TimePicker/time-picker.js.map +1 -1
  228. package/dist/components/TreeView/tree-view.d.ts +9 -5
  229. package/dist/components/TreeView/tree-view.d.ts.map +1 -1
  230. package/dist/components/TreeView/tree-view.js +266 -214
  231. package/dist/components/TreeView/tree-view.js.map +1 -1
  232. package/dist/hooks/use-input-modality.d.ts +12 -17
  233. package/dist/hooks/use-input-modality.d.ts.map +1 -1
  234. package/dist/hooks/use-input-modality.js +4 -34
  235. package/dist/hooks/use-input-modality.js.map +1 -1
  236. package/dist/hooks/use-overflow-items.d.ts.map +1 -1
  237. package/dist/hooks/use-overflow-items.js +2 -0
  238. package/dist/hooks/use-overflow-items.js.map +1 -1
  239. package/dist/hooks/use-truncated.d.ts.map +1 -1
  240. package/dist/hooks/use-truncated.js.map +1 -1
  241. package/dist/index.d.ts +3 -0
  242. package/dist/index.d.ts.map +1 -1
  243. package/dist/index.js +23 -3
  244. package/dist/index.js.map +1 -1
  245. package/dist/lib/drag-announcements.d.ts +32 -0
  246. package/dist/lib/drag-announcements.d.ts.map +1 -1
  247. package/dist/lib/drag-announcements.js +39 -1
  248. package/dist/lib/drag-announcements.js.map +1 -1
  249. package/dist/lib/focus-after-trigger.d.ts +45 -0
  250. package/dist/lib/focus-after-trigger.d.ts.map +1 -0
  251. package/dist/lib/focus-after-trigger.js +66 -0
  252. package/dist/lib/focus-after-trigger.js.map +1 -0
  253. package/dist/lib/overlay-coexistence.js +1 -1
  254. package/dist/lib/roving-list-keyboard.d.ts +208 -0
  255. package/dist/lib/roving-list-keyboard.d.ts.map +1 -0
  256. package/dist/lib/roving-list-keyboard.js +174 -0
  257. package/dist/lib/roving-list-keyboard.js.map +1 -0
  258. package/dist/lib/utils.d.ts.map +1 -1
  259. package/dist/lib/utils.js +6 -1
  260. package/dist/lib/utils.js.map +1 -1
  261. package/dist/patterns/element-anatomy/item-anatomy.d.ts +4 -4
  262. package/dist/patterns/element-anatomy/item-anatomy.d.ts.map +1 -1
  263. package/dist/patterns/element-anatomy/item-anatomy.js +14 -4
  264. package/dist/patterns/element-anatomy/item-anatomy.js.map +1 -1
  265. package/dist/patterns/horizontal-overflow/horizontal-overflow.d.ts.map +1 -1
  266. package/dist/patterns/horizontal-overflow/horizontal-overflow.js +25 -0
  267. package/dist/patterns/horizontal-overflow/horizontal-overflow.js.map +1 -1
  268. package/dist/patterns/overlay-surface/overlay-surface.d.ts.map +1 -1
  269. package/dist/patterns/overlay-surface/overlay-surface.js.map +1 -1
  270. package/dist/tokens/categorical-color.d.ts +6 -1
  271. package/dist/tokens/categorical-color.d.ts.map +1 -1
  272. package/dist/tokens/categorical-color.js.map +1 -1
  273. package/dist/tokens/uiSize/icon-size.d.ts +1 -1
  274. package/dist/tokens/uiSize/stack-gap.d.ts +18 -0
  275. package/dist/tokens/uiSize/stack-gap.d.ts.map +1 -0
  276. package/dist/tokens/uiSize/stack-gap.js +5 -0
  277. package/dist/tokens/uiSize/stack-gap.js.map +1 -0
  278. package/ds-canonical/fork/codex/agents/skills/performance-audit/SKILL.md +1 -1
  279. package/ds-canonical/fork/codex/hooks.json +1 -1
  280. package/ds-canonical/fork/consumer/lock.json +17 -14
  281. package/ds-canonical/fork/consumer/managed-files/423729840acdd43c812f17c245b871716c6b60f76e4d3e94864d0e34a815bf8d.blob +9 -0
  282. package/ds-canonical/fork/consumer/managed-files/46f10bc55cdfdf834d0749eebff42ea0bb8576f361b36d2b6ba1851354c50150.blob +47 -9
  283. package/ds-canonical/fork/consumer/managed-files/5a0d134a2645114c8caac20458070b00a7f0fd55b3e8805b7325cb4cf52fa15e.blob +110 -0
  284. package/ds-canonical/fork/consumer/managed-files/5af0a46760af338d51fd0f7950675f8e97f7d2f09386b8818fcd7a58e6654e75.blob +790 -0
  285. package/ds-canonical/fork/consumer/managed-files/68bfcddff9c4a16388c248cd34fb66163e9e64b3d809a48ef3984f6ae4ff6d12.blob +211 -0
  286. package/ds-canonical/fork/consumer/managed-files/7eb6cc60abfdabaf6617c336058fad1454ccde08889295767bfd9b7fd153cc6e.blob +45 -6
  287. package/ds-canonical/fork/consumer/managed-files/92e4828cdcb96ff0d01daa16f6885f24045a8e72820665650f2a1890dc3a446c.blob +42 -2
  288. package/ds-canonical/fork/consumer/managed-files/ab072e7f2eca51f0e18a5e18c4b333260ee5d219a12cc6df5bb2d683f0b2734d.blob +27 -1
  289. package/ds-canonical/fork/consumer/managed-files/e71c65f45c6af7ce12b6b3c0d8028f185da5b719e2050c9b2a6b243d41ae4878.blob +62 -14
  290. package/ds-canonical/fork/governance.lock +41 -17
  291. package/ds-canonical/fork/hooks/check_consumer_app_invariants.sh +16 -4
  292. package/ds-canonical/fork/hooks/check_consumer_code_quality.sh +3 -1
  293. package/ds-canonical/fork/hooks/check_pattern_invariants.sh +13 -9
  294. package/ds-canonical/fork/launchers/settings-hooks.json +1 -1
  295. package/ds-canonical/fork/manifest.json +17 -11
  296. package/ds-canonical/fork/providers/claude/skills/performance-audit/SKILL.md +1 -1
  297. package/ds-canonical/fork/providers/codex/hook-config.json +1 -1
  298. package/ds-canonical/fork/providers/codex/skills/performance-audit/SKILL.md +1 -1
  299. package/ds-canonical/fork/skills/performance-audit/SKILL.md +1 -1
  300. package/ds-canonical/hooks/check_consumer_app_invariants.sh +16 -4
  301. package/ds-canonical/hooks/check_consumer_code_quality.sh +3 -1
  302. package/ds-canonical/hooks/check_datatable_invariants.sh +4 -1
  303. package/ds-canonical/hooks/check_pattern_invariants.sh +13 -9
  304. package/ds-canonical/hooks/check_plugin_fork_health.sh +8 -1
  305. package/ds-canonical/hooks/check_propose_discipline.sh +8 -1
  306. package/ds-canonical/hooks/check_storybook_addon_packaging.sh +8 -1
  307. package/ds-canonical/hooks/check_substantive_edit_approval_preflight.sh +64 -2
  308. package/ds-canonical/hooks/lib/_overlay_handcraft.sh +5 -2
  309. package/ds-canonical/hooks/registrations.json +12 -7
  310. package/ds-canonical/hooks/session_start_governance_check.sh +16 -0
  311. package/ds-canonical/hooks/tests/test_check_consumer_app_invariants.sh +25 -0
  312. package/ds-canonical/hooks/tests/test_check_consumer_code_quality.sh +4 -0
  313. package/ds-canonical/hooks/tests/test_check_consumer_ds_primitive_misuse.sh +14 -0
  314. package/ds-canonical/hooks/tests/test_check_datatable_invariants.sh +24 -0
  315. package/ds-canonical/hooks/tests/test_check_overlay_handcraft.sh +32 -0
  316. package/ds-canonical/hooks/tests/test_check_pattern_invariants.sh +59 -0
  317. package/ds-canonical/hooks/tests/test_check_plugin_fork_health.sh +32 -1
  318. package/ds-canonical/hooks/tests/test_check_propose_discipline.sh +21 -0
  319. package/ds-canonical/hooks/tests/test_check_storybook_addon_packaging.sh +21 -0
  320. package/ds-canonical/hooks/tests/test_check_substantive_edit_approval_preflight.sh +97 -0
  321. package/ds-canonical/hooks/tests/test_session_start_governance_check.sh +49 -0
  322. package/ds-canonical/references/README.md +12 -6
  323. package/ds-canonical/references/drag-canonical.md +3 -1
  324. package/ds-canonical/references/focus-canonical.md +26 -13
  325. package/ds-canonical/references/governance-audit-coverage.md +1 -1
  326. package/ds-canonical/references/hit-area-canonical.md +361 -0
  327. package/ds-canonical/references/item-anatomy-recipe.md +4 -2
  328. package/ds-canonical/references/keyboard-model-canonical.md +559 -0
  329. package/ds-canonical/rules/meta-patterns.md +4 -4
  330. package/ds-canonical/rules/self-verify.md +4 -4
  331. package/ds-canonical/skills/design-system-audit/references/audit-prompts.md +1 -1
  332. package/ds-canonical/skills/design-system-audit/references/historical-bugs.md +96 -0
  333. package/ds-canonical/skills/knowledge-prune/SKILL.md +4 -1
  334. package/ds-canonical/skills/performance-audit/SKILL.md +1 -1
  335. package/ds-story-manifest.json +19 -7
  336. package/llms-full.txt +2 -2
  337. package/llms.txt +2 -2
  338. package/package.json +3 -1
  339. package/src/components/Accordion/accordion.anatomy.stories.tsx +3 -3
  340. package/src/components/Accordion/accordion.spec.md +1 -1
  341. package/src/components/Accordion/accordion.tsx +8 -3
  342. package/src/components/AccountMenu/account-menu.spec.md +2 -3
  343. package/src/components/AccountMenu/account-menu.tsx +0 -1
  344. package/src/components/AgentPanel/agent-decision-card.spec.md +88 -0
  345. package/src/components/AgentPanel/agent-panel-fab.spec.md +151 -0
  346. package/src/components/AgentPanel/agent-panel-fab.tsx +67 -24
  347. package/src/components/AgentPanel/agent-panel-logo.spec.md +87 -0
  348. package/src/components/AgentPanel/agent-panel-logo.tsx +3 -3
  349. package/src/components/AgentPanel/agent-panel.anatomy.stories.tsx +1 -1
  350. package/src/components/AgentPanel/agent-panel.principles.stories.tsx +1 -1
  351. package/src/components/AgentPanel/agent-panel.spec.md +30 -275
  352. package/src/components/AgentPanel/agent-panel.stories.tsx +113 -8
  353. package/src/components/AgentPanel/agent-panel.tsx +59 -22
  354. package/src/components/Alert/alert.anatomy.stories.tsx +1 -1
  355. package/src/components/AppShell/app-shell.tsx +1 -1
  356. package/src/components/AspectRatio/aspect-ratio.anatomy.stories.tsx +10 -15
  357. package/src/components/Avatar/avatar.anatomy.stories.tsx +23 -26
  358. package/src/components/Avatar/avatar.principles.stories.tsx +10 -10
  359. package/src/components/Avatar/avatar.spec.md +45 -6
  360. package/src/components/Avatar/avatar.stories.tsx +8 -8
  361. package/src/components/Avatar/avatar.tsx +227 -21
  362. package/src/components/Badge/badge.anatomy.stories.tsx +16 -21
  363. package/src/components/Breadcrumb/breadcrumb.anatomy.stories.tsx +3 -3
  364. package/src/components/Breadcrumb/breadcrumb.spec.md +3 -3
  365. package/src/components/Breadcrumb/breadcrumb.tsx +5 -3
  366. package/src/components/BulkActionBar/bulk-action-bar.anatomy.stories.tsx +1 -1
  367. package/src/components/BulkActionBar/bulk-action-bar.principles.stories.tsx +1 -1
  368. package/src/components/BulkActionBar/bulk-action-bar.spec.md +1 -0
  369. package/src/components/BulkActionBar/bulk-action-bar.stories.tsx +57 -2
  370. package/src/components/BulkActionBar/bulk-action-bar.tsx +32 -2
  371. package/src/components/Button/button.anatomy.stories.tsx +174 -33
  372. package/src/components/Button/button.spec.md +23 -8
  373. package/src/components/Button/button.tsx +116 -21
  374. package/src/components/Calendar/calendar.anatomy.stories.tsx +34 -11
  375. package/src/components/Calendar/calendar.principles.stories.tsx +44 -1
  376. package/src/components/Calendar/calendar.spec.md +97 -20
  377. package/src/components/Calendar/calendar.stories.tsx +101 -4
  378. package/src/components/Calendar/calendar.tsx +379 -74
  379. package/src/components/Carousel/carousel.anatomy.stories.tsx +16 -17
  380. package/src/components/Carousel/carousel.spec.md +48 -2
  381. package/src/components/Carousel/carousel.tsx +9 -3
  382. package/src/components/Chart/chart.anatomy.stories.tsx +7 -5
  383. package/src/components/Chart/chart.spec.md +32 -7
  384. package/src/components/Chart/chart.tsx +9 -0
  385. package/src/components/Checkbox/checkbox.anatomy.stories.tsx +21 -28
  386. package/src/components/Checkbox/checkbox.spec.md +4 -2
  387. package/src/components/Checkbox/checkbox.tsx +10 -2
  388. package/src/components/Chip/chip.anatomy.stories.tsx +1 -1
  389. package/src/components/Chip/chip.spec.md +2 -1
  390. package/src/components/Chip/chip.tsx +4 -2
  391. package/src/components/Combobox/combobox.anatomy.stories.tsx +30 -37
  392. package/src/components/Combobox/combobox.spec.md +11 -3
  393. package/src/components/Combobox/combobox.tsx +43 -12
  394. package/src/components/Command/command.spec.md +11 -0
  395. package/src/components/Command/command.tsx +143 -10
  396. package/src/components/DataTable/cell-registry.tsx +5 -1
  397. package/src/components/DataTable/data-table-column-visibility-panel.tsx +5 -6
  398. package/src/components/DataTable/data-table-interaction-layer.tsx +27 -14
  399. package/src/components/DataTable/data-table-known-defects.spec.md +72 -0
  400. package/src/components/DataTable/data-table-scroll-performance.spec.md +295 -0
  401. package/src/components/DataTable/data-table-sort-manager.tsx +5 -6
  402. package/src/components/DataTable/data-table.anatomy.stories.tsx +1 -1
  403. package/src/components/DataTable/data-table.css +64 -0
  404. package/src/components/DataTable/data-table.spec.md +70 -346
  405. package/src/components/DataTable/data-table.stories.tsx +56 -9
  406. package/src/components/DataTable/data-table.tsx +392 -103
  407. package/src/components/DateGrid/date-grid.anatomy.stories.tsx +2 -2
  408. package/src/components/DateGrid/date-grid.spec.md +163 -1
  409. package/src/components/DateGrid/date-grid.tsx +270 -7
  410. package/src/components/DatePicker/date-picker.anatomy.stories.tsx +18 -27
  411. package/src/components/DatePicker/date-picker.spec.md +6 -2
  412. package/src/components/DatePicker/date-picker.tsx +20 -1
  413. package/src/components/Dialog/dialog.spec.md +6 -2
  414. package/src/components/Dialog/dialog.stories.tsx +18 -9
  415. package/src/components/Dialog/dialog.tsx +83 -48
  416. package/src/components/DropdownMenu/dropdown-menu-keyboard.ts +255 -0
  417. package/src/components/DropdownMenu/dropdown-menu.anatomy.stories.tsx +32 -33
  418. package/src/components/DropdownMenu/dropdown-menu.spec.md +18 -5
  419. package/src/components/DropdownMenu/dropdown-menu.stories.tsx +58 -1
  420. package/src/components/DropdownMenu/dropdown-menu.tsx +70 -33
  421. package/src/components/Empty/empty.spec.md +1 -2
  422. package/src/components/Field/field-context.ts +9 -4
  423. package/src/components/Field/field-controls.spec.md +5 -2
  424. package/src/components/Field/field-edit-keys.ts +12 -0
  425. package/src/components/Field/field-wrapper.tsx +76 -10
  426. package/src/components/Field/field.anatomy.stories.tsx +1 -1
  427. package/src/components/Field/field.spec.md +11 -6
  428. package/src/components/Field/field.stories.tsx +24 -1
  429. package/src/components/Field/field.tsx +10 -4
  430. package/src/components/FileItem/file-item.anatomy.stories.tsx +20 -10
  431. package/src/components/FileItem/file-item.principles.stories.tsx +14 -7
  432. package/src/components/FileItem/file-item.spec.md +50 -48
  433. package/src/components/FileItem/file-item.stories.tsx +41 -28
  434. package/src/components/FileItem/file-item.tsx +184 -50
  435. package/src/components/FileUpload/file-upload.anatomy.stories.tsx +11 -15
  436. package/src/components/FileUpload/file-upload.spec.md +27 -1
  437. package/src/components/FileUpload/file-upload.stories.tsx +33 -0
  438. package/src/components/FileUpload/file-upload.tsx +173 -43
  439. package/src/components/FileViewer/file-viewer.tsx +9 -4
  440. package/src/components/HoverCard/hover-card.stories.tsx +2 -2
  441. package/src/components/InlineEdit/inline-edit.spec.md +2 -0
  442. package/src/components/InlineEdit/inline-edit.tsx +8 -3
  443. package/src/components/Input/input.anatomy.stories.tsx +23 -31
  444. package/src/components/Input/input.spec.md +11 -0
  445. package/src/components/Input/input.tsx +6 -1
  446. package/src/components/LinkInput/link-input.anatomy.stories.tsx +18 -21
  447. package/src/components/LinkInput/link-input.principles.stories.tsx +4 -4
  448. package/src/components/LinkInput/link-input.spec.md +12 -1
  449. package/src/components/LinkInput/link-input.tsx +37 -4
  450. package/src/components/Menu/menu-item.anatomy.stories.tsx +50 -56
  451. package/src/components/Menu/menu-item.spec.md +1 -1
  452. package/src/components/Menu/menu-item.stories.tsx +48 -42
  453. package/src/components/Notice/notice.anatomy.stories.tsx +8 -16
  454. package/src/components/Notice/notice.spec.md +1 -1
  455. package/src/components/Notice/notice.tsx +1 -1
  456. package/src/components/NumberInput/number-input.anatomy.stories.tsx +21 -28
  457. package/src/components/NumberInput/number-input.spec.md +2 -0
  458. package/src/components/NumberInput/number-input.tsx +8 -1
  459. package/src/components/OverflowIndicator/overflow-indicator.anatomy.stories.tsx +28 -48
  460. package/src/components/OverflowIndicator/overflow-indicator.spec.md +13 -1
  461. package/src/components/OverflowIndicator/overflow-indicator.stories.tsx +12 -9
  462. package/src/components/OverflowIndicator/overflow-indicator.tsx +32 -12
  463. package/src/components/Pagination/pagination.spec.md +1 -0
  464. package/src/components/Pagination/pagination.tsx +1 -1
  465. package/src/components/PeoplePicker/avatar-stack-overflow.ts +14 -13
  466. package/src/components/PeoplePicker/people-picker-helpers.ts +5 -2
  467. package/src/components/PeoplePicker/people-picker.anatomy.stories.tsx +1 -1
  468. package/src/components/PeoplePicker/people-picker.spec.md +4 -2
  469. package/src/components/PeoplePicker/people-picker.tsx +1 -4
  470. package/src/components/PeoplePicker/person-display.tsx +45 -28
  471. package/src/components/Popover/popover.anatomy.stories.tsx +1 -1
  472. package/src/components/Popover/popover.principles.stories.tsx +3 -12
  473. package/src/components/Popover/popover.spec.md +7 -3
  474. package/src/components/ProfileCard/profile-card.anatomy.stories.tsx +1 -1
  475. package/src/components/ProfileCard/profile-card.spec.md +1 -1
  476. package/src/components/ProfileCard/profile-card.tsx +0 -3
  477. package/src/components/ProgressBar/progress-bar.anatomy.stories.tsx +11 -21
  478. package/src/components/ProgressBar/progress-bar.spec.md +1 -1
  479. package/src/components/RadioGroup/radio-group.anatomy.stories.tsx +17 -24
  480. package/src/components/RadioGroup/radio-group.spec.md +1 -1
  481. package/src/components/RadioGroup/radio-group.tsx +22 -4
  482. package/src/components/Rating/rating.anatomy.stories.tsx +131 -124
  483. package/src/components/Rating/rating.principles.stories.tsx +69 -43
  484. package/src/components/Rating/rating.spec.md +142 -63
  485. package/src/components/Rating/rating.stories.tsx +11 -15
  486. package/src/components/Rating/rating.tsx +131 -117
  487. package/src/components/ScrollArea/scroll-area.anatomy.stories.tsx +1 -1
  488. package/src/components/ScrollArea/scroll-area.principles.stories.tsx +6 -3
  489. package/src/components/ScrollArea/scroll-area.spec.md +3 -1
  490. package/src/components/ScrollArea/scroll-area.stories.tsx +5 -2
  491. package/src/components/ScrollArea/scroll-area.tsx +1 -1
  492. package/src/components/SegmentedControl/segmented-control.anatomy.stories.tsx +1 -1
  493. package/src/components/SegmentedControl/segmented-control.spec.md +2 -2
  494. package/src/components/SegmentedControl/segmented-control.tsx +3 -2
  495. package/src/components/Select/select.anatomy.stories.tsx +26 -35
  496. package/src/components/Select/select.spec.md +4 -3
  497. package/src/components/Select/select.tsx +11 -4
  498. package/src/components/SelectMenu/select-menu-keyboard.ts +218 -0
  499. package/src/components/SelectMenu/select-menu.anatomy.stories.tsx +6 -17
  500. package/src/components/SelectMenu/select-menu.spec.md +12 -4
  501. package/src/components/SelectMenu/select-menu.tsx +21 -56
  502. package/src/components/SelectionControl/selection-item.anatomy.stories.tsx +9 -33
  503. package/src/components/SelectionControl/selection-item.spec.md +2 -2
  504. package/src/components/SelectionControl/selection-item.tsx +3 -1
  505. package/src/components/Separator/separator.stories.tsx +4 -4
  506. package/src/components/Sheet/sheet.principles.stories.tsx +31 -13
  507. package/src/components/Sidebar/sidebar.anatomy.stories.tsx +1 -1
  508. package/src/components/Sidebar/sidebar.spec.md +73 -6
  509. package/src/components/Sidebar/sidebar.stories.tsx +82 -4
  510. package/src/components/Sidebar/sidebar.tsx +281 -64
  511. package/src/components/Skeleton/skeleton.spec.md +1 -1
  512. package/src/components/Slider/slider.anatomy.stories.tsx +1 -1
  513. package/src/components/Slider/slider.spec.md +6 -5
  514. package/src/components/Slider/slider.tsx +13 -8
  515. package/src/components/Steps/steps-state-visuals.spec.md +157 -0
  516. package/src/components/Steps/steps.anatomy.stories.tsx +1 -0
  517. package/src/components/Steps/steps.spec.md +59 -142
  518. package/src/components/Steps/steps.stories.tsx +1 -1
  519. package/src/components/Steps/steps.tsx +125 -33
  520. package/src/components/Switch/switch.spec.md +3 -3
  521. package/src/components/Switch/switch.tsx +6 -1
  522. package/src/components/Tabs/tabs.spec.md +5 -1
  523. package/src/components/Tabs/tabs.tsx +42 -3
  524. package/src/components/Tag/tag.anatomy.stories.tsx +24 -28
  525. package/src/components/Tag/tag.spec.md +10 -11
  526. package/src/components/Tag/tag.tsx +3 -3
  527. package/src/components/Textarea/textarea.tsx +7 -1
  528. package/src/components/TimePicker/time-columns.tsx +9 -4
  529. package/src/components/TimePicker/time-picker.spec.md +4 -1
  530. package/src/components/TimePicker/time-picker.tsx +1 -1
  531. package/src/components/Tooltip/tooltip.anatomy.stories.tsx +6 -15
  532. package/src/components/Tooltip/tooltip.principles.stories.tsx +4 -16
  533. package/src/components/Tooltip/tooltip.spec.md +2 -1
  534. package/src/components/TreeView/tree-view.anatomy.stories.tsx +35 -13
  535. package/src/components/TreeView/tree-view.spec.md +67 -38
  536. package/src/components/TreeView/tree-view.stories.tsx +221 -12
  537. package/src/components/TreeView/tree-view.tsx +463 -356
  538. package/src/hooks/use-input-modality.ts +17 -46
  539. package/src/hooks/use-overflow-items.ts +4 -0
  540. package/src/hooks/use-truncated.ts +3 -2
  541. package/src/index.ts +17 -0
  542. package/src/lib/README.md +2 -0
  543. package/src/lib/drag-announcements.ts +78 -0
  544. package/src/lib/focus-after-trigger.ts +102 -0
  545. package/src/lib/roving-list-keyboard.ts +400 -0
  546. package/src/lib/utils.ts +5 -0
  547. package/src/patterns/action-bar/action-bar.spec.md +2 -0
  548. package/src/patterns/element-anatomy/inline-action.spec.md +16 -12
  549. package/src/patterns/element-anatomy/item-anatomy.spec.md +98 -6
  550. package/src/patterns/element-anatomy/item-anatomy.stories.tsx +75 -70
  551. package/src/patterns/element-anatomy/item-anatomy.tsx +17 -6
  552. package/src/patterns/element-anatomy/truncated-text.spec.md +1 -0
  553. package/src/patterns/header-canonical/header-canonical.spec.md +3 -2
  554. package/src/patterns/horizontal-overflow/horizontal-overflow.spec.md +2 -0
  555. package/src/patterns/horizontal-overflow/horizontal-overflow.stories.tsx +36 -0
  556. package/src/patterns/horizontal-overflow/horizontal-overflow.tsx +28 -0
  557. package/src/patterns/overlay-surface/overlay-chrome-sizing.spec.md +180 -0
  558. package/src/patterns/overlay-surface/overlay-surface.spec.md +8 -162
  559. package/src/patterns/overlay-surface/overlay-surface.tsx +5 -3
  560. package/src/patterns/resize-handle/resize-handle.spec.md +3 -3
  561. package/src/styles/base.css +1 -1
  562. package/src/tokens/categorical-color.ts +6 -1
  563. package/src/tokens/color/color.spec.md +91 -24
  564. package/src/tokens/color/color.stories.tsx +50 -2
  565. package/src/tokens/color/primitives.css +41 -38
  566. package/src/tokens/color/semantic.css +105 -36
  567. package/src/tokens/layoutSpace/layoutSpace.spec.md +2 -0
  568. package/src/tokens/motion/motion.spec.md +31 -8
  569. package/src/tokens/orphan-tokens.spec.md +1 -1
  570. package/src/tokens/uiSize/icon-size.ts +1 -1
  571. package/src/tokens/uiSize/stack-gap.ts +17 -0
  572. package/src/tokens/uiSize/uiSize.css +12 -0
  573. package/src/tokens/uiSize/uiSize.spec.md +17 -16
  574. package/src/tokens/uiSize/uiSize.stories.tsx +1 -1
  575. package/dist/node_modules/aria-hidden/dist/es2015/index.js +0 -147
  576. package/dist/node_modules/aria-hidden/dist/es2015/index.js.map +0 -1
@@ -13,6 +13,7 @@ import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
13
13
  import { Tag } from '@/design-system/components/Tag/tag'
14
14
  import { Avatar, type AvatarData } from '@/design-system/components/Avatar/avatar'
15
15
  import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
16
+ import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
16
17
 
17
18
  /** Person avatar hover canonical helper — avatar.spec.md DS-wide rule:
18
19
  * profile-card.spec.md 重要資訊 canonical(status / statusMessage / fields 皆必含)
@@ -133,7 +134,7 @@ const CONSUMERS: Record<ConsumerKey, ConsumerPreset> = {
133
134
  desc: '頁面列表(未來元件)',
134
135
  mode: 'reading',
135
136
  py: 'py-3 (12px)',
136
- pyDesc: '觸控友好的列表行高',
137
+ pyDesc: '頁面級列表的寬鬆行高(配閱讀模式與較大 avatar)',
137
138
  px: 'px-4 (16px)',
138
139
  pxDesc: '頁面標準水平間距',
139
140
  gap: 'gap-3 (12px)',
@@ -203,15 +204,6 @@ const Swatch = ({ value, size = 'md' }: { value: string; size?: 'sm' | 'md' }) =
203
204
  return <span className={`${s} rounded-md shrink-0 border border-black/10`} style={{ backgroundColor: `var(${value})` }} />
204
205
  }
205
206
 
206
- const Tab = ({ active, onClick, children }: { active: boolean; onClick: () => void; children: React.ReactNode }) => (
207
- <button type="button" onClick={onClick}
208
- className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
209
- active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
210
- }`}>
211
- {children}
212
- </button>
213
- )
214
-
215
207
  const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
216
208
  <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
217
209
  <span className="text-[11px] text-fg-muted font-medium w-[88px] shrink-0 pt-0.5 flex items-center gap-1.5">
@@ -243,10 +235,20 @@ const Z = {
243
235
  },
244
236
  }
245
237
 
246
- /** Menu container — role=listbox 滿足內部 MenuItem role=option 的 parent(axe aria-required-parent)。 */
238
+ /**
239
+ * Menu container — **靜態視覺預覽,不是真的 listbox**。
240
+ *
241
+ * 2026-09-24:原本是 `role="listbox"`,理由是「滿足內部 MenuItem role=option 的 parent
242
+ *(axe aria-required-parent)」。那是拿一個 ARIA 角色去消 lint,而不是描述這東西真的是什麼 ——
243
+ * 這個容器沒有選取狀態、沒有方向鍵、沒有焦點管理,`listbox` 是對輔助科技的空頭承諾
244
+ *(SSOT:`ds-canonical/references/keyboard-model-canonical.md`「鐵律」)。
245
+ * 正解是**兩邊一起拿掉**:容器改 `role="group"`(結構角色,不承諾鍵盤),
246
+ * 裡面的 MenuItem 傳 `role="presentation"`(元件本就支援,見 menu-item.tsx 的「ARIA 單一 owner gate」),
247
+ * 於是既沒有孤兒 option,也沒有假的 composite。
248
+ */
247
249
  const MenuFrame = ({ children, width = 320 }: { children: React.ReactNode; width?: number }) => (
248
250
  <div
249
- role="listbox"
251
+ role="group"
250
252
  aria-label="Anatomy inspector menu preview"
251
253
  className="rounded-lg bg-surface-raised border border-border overflow-hidden py-2"
252
254
  style={{ width, boxShadow: 'var(--elevation-200)' }}
@@ -444,29 +446,30 @@ const InspectorInner = () => {
444
446
 
445
447
  return (
446
448
  <div className="flex flex-col gap-6">
447
- {/* Controls */}
449
+ {/* Controls — 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項;
450
+ 取代手刻 Tab:它靜止借 neutral-hover、hover 借 neutral-active,是 color.spec.md 成對 token 的錯配) */}
448
451
  <div className="flex flex-col gap-2.5">
449
452
  <div className="flex items-center gap-2">
450
453
  <span className="text-[11px] text-fg-muted w-24 shrink-0">情境</span>
451
- <div className="flex gap-1.5">
454
+ <SegmentedControl size="sm" aria-label="情境" value={consumer} onValueChange={(v) => setConsumer(v as ConsumerKey)}>
452
455
  {(Object.keys(CONSUMERS) as ConsumerKey[]).map((c) => (
453
- <Tab key={c} active={consumer === c} onClick={() => setConsumer(c)}>{CONSUMER_DISPLAY[c].tab}</Tab>
456
+ <SegmentedControlItem key={c} value={c}>{CONSUMER_DISPLAY[c].tab}</SegmentedControlItem>
454
457
  ))}
455
- </div>
458
+ </SegmentedControl>
456
459
  <span className="text-[10px] text-fg-muted font-mono">{CONSUMER_DISPLAY[consumer].sub}</span>
457
460
  </div>
458
461
  <div className="flex items-center gap-2">
459
462
  <span className="text-[11px] text-fg-muted w-24 shrink-0">Size</span>
460
- <div className="flex gap-1.5">
461
- {SIZES.map((sz) => <Tab key={sz} active={size === sz} onClick={() => setSize(sz)}>{sz}</Tab>)}
462
- </div>
463
+ <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
464
+ {SIZES.map((sz) => <SegmentedControlItem key={sz} value={sz}>{sz}</SegmentedControlItem>)}
465
+ </SegmentedControl>
463
466
  </div>
464
467
  <div className="flex items-center gap-2">
465
468
  <span className="text-[11px] text-fg-muted w-24 shrink-0">hasPrefix</span>
466
- <div className="flex gap-1.5">
467
- <Tab active={hasPrefix} onClick={() => setHasPrefix(true)}>on</Tab>
468
- <Tab active={!hasPrefix} onClick={() => setHasPrefix(false)}>off</Tab>
469
- </div>
469
+ <SegmentedControl size="sm" aria-label="hasPrefix" value={hasPrefix ? 'on' : 'off'} onValueChange={(v) => setHasPrefix(v === 'on')}>
470
+ <SegmentedControlItem value="on">on</SegmentedControlItem>
471
+ <SegmentedControlItem value="off">off</SegmentedControlItem>
472
+ </SegmentedControl>
470
473
  {consumer === 'SelectionItem' && (
471
474
  <span className="text-[11px] text-fg-muted">
472
475
  SelectionItem 的 prefix 是<strong>除了 control 之外</strong>的視覺輔助
@@ -476,60 +479,62 @@ const InspectorInner = () => {
476
479
  {hasPrefix && (
477
480
  <div className="flex items-center gap-2">
478
481
  <span className="text-[11px] text-fg-muted w-24 shrink-0">prefixType</span>
479
- <div className="flex gap-1.5">
480
- <Tab active={prefixType === 'icon'} onClick={() => setPrefixType('icon')}>icon</Tab>
481
- <Tab active={prefixType === 'avatar'} onClick={() => setPrefixType('avatar')}>avatar</Tab>
482
- </div>
482
+ <SegmentedControl size="sm" aria-label="prefixType" value={prefixType} onValueChange={(v) => setPrefixType(v as PrefixType)}>
483
+ <SegmentedControlItem value="icon">icon</SegmentedControlItem>
484
+ <SegmentedControlItem value="avatar">avatar</SegmentedControlItem>
485
+ </SegmentedControl>
483
486
  </div>
484
487
  )}
485
488
  {/* SelectionItem avatar 沒有 block 模式(left checkbox + block avatar = 歪斜) */}
486
489
  <div className="flex items-center gap-2">
487
490
  <span className="text-[11px] text-fg-muted w-24 shrink-0">label 內容長度</span>
488
- <div className="flex gap-1.5">
489
- <Tab active={labelLength === 'short'} onClick={() => setLabelLength('short')}>short</Tab>
490
- <Tab active={labelLength === 'medium'} onClick={() => setLabelLength('medium')}>medium</Tab>
491
- <Tab active={labelLength === 'long'} onClick={() => setLabelLength('long')}>long</Tab>
492
- </div>
491
+ <SegmentedControl size="sm" aria-label="label 內容長度" value={labelLength} onValueChange={(v) => setLabelLength(v as ContentLength)}>
492
+ <SegmentedControlItem value="short">short</SegmentedControlItem>
493
+ <SegmentedControlItem value="medium">medium</SegmentedControlItem>
494
+ <SegmentedControlItem value="long">long</SegmentedControlItem>
495
+ </SegmentedControl>
493
496
  </div>
494
497
  <div className="flex items-center gap-2">
495
498
  <span className="text-[11px] text-fg-muted w-24 shrink-0">label clamp</span>
496
- <div className="flex gap-1.5">
497
- <Tab active={labelClampOverride === 'preset'} onClick={() => setLabelClampOverride('preset')}>
499
+ {/* 值有數字(1 / 2)也有字串(preset / unbounded);SegmentedControl 的 value 是字串 → 轉 String、回寫時還原型別 */}
500
+ <SegmentedControl size="sm" aria-label="label clamp" value={String(labelClampOverride)} onValueChange={(v) => setLabelClampOverride(v === '1' ? 1 : v === '2' ? 2 : (v as 'preset' | 'unbounded'))}>
501
+ <SegmentedControlItem value="preset">
498
502
  preset({preset.labelMaxLines ?? '∞'})
499
- </Tab>
500
- <Tab active={labelClampOverride === 1} onClick={() => setLabelClampOverride(1)}>1</Tab>
501
- <Tab active={labelClampOverride === 2} onClick={() => setLabelClampOverride(2)}>2</Tab>
502
- <Tab active={labelClampOverride === 'unbounded'} onClick={() => setLabelClampOverride('unbounded')}>∞</Tab>
503
- </div>
503
+ </SegmentedControlItem>
504
+ <SegmentedControlItem value="1">1</SegmentedControlItem>
505
+ <SegmentedControlItem value="2">2</SegmentedControlItem>
506
+ <SegmentedControlItem value="unbounded">∞</SegmentedControlItem>
507
+ </SegmentedControl>
504
508
  </div>
505
509
  <div className="flex items-center gap-2">
506
510
  <span className="text-[11px] text-fg-muted w-24 shrink-0">description</span>
507
- <div className="flex gap-1.5">
508
- <Tab active={descContent === 'none'} onClick={() => setDescContent('none')}>none</Tab>
509
- <Tab active={descContent === 'short'} onClick={() => setDescContent('short')}>short</Tab>
510
- <Tab active={descContent === 'medium'} onClick={() => setDescContent('medium')}>medium</Tab>
511
- <Tab active={descContent === 'long'} onClick={() => setDescContent('long')}>long</Tab>
512
- </div>
511
+ <SegmentedControl size="sm" aria-label="description" value={descContent} onValueChange={(v) => setDescContent(v as DescContent)}>
512
+ <SegmentedControlItem value="none">none</SegmentedControlItem>
513
+ <SegmentedControlItem value="short">short</SegmentedControlItem>
514
+ <SegmentedControlItem value="medium">medium</SegmentedControlItem>
515
+ <SegmentedControlItem value="long">long</SegmentedControlItem>
516
+ </SegmentedControl>
513
517
  </div>
514
518
  {hasDescription && (
515
519
  <div className="flex items-center gap-2">
516
520
  <span className="text-[11px] text-fg-muted w-24 shrink-0">desc clamp</span>
517
- <div className="flex gap-1.5">
518
- <Tab active={descClampOverride === 'preset'} onClick={() => setDescClampOverride('preset')}>
521
+ {/* 值有數字(1 / 2)也有字串(preset / unbounded);SegmentedControl 的 value 是字串 → 轉 String、回寫時還原型別 */}
522
+ <SegmentedControl size="sm" aria-label="desc clamp" value={String(descClampOverride)} onValueChange={(v) => setDescClampOverride(v === '1' ? 1 : v === '2' ? 2 : (v as 'preset' | 'unbounded'))}>
523
+ <SegmentedControlItem value="preset">
519
524
  preset({preset.descMaxLines ?? '∞'})
520
- </Tab>
521
- <Tab active={descClampOverride === 1} onClick={() => setDescClampOverride(1)}>1</Tab>
522
- <Tab active={descClampOverride === 2} onClick={() => setDescClampOverride(2)}>2</Tab>
523
- <Tab active={descClampOverride === 'unbounded'} onClick={() => setDescClampOverride('unbounded')}>∞</Tab>
524
- </div>
525
+ </SegmentedControlItem>
526
+ <SegmentedControlItem value="1">1</SegmentedControlItem>
527
+ <SegmentedControlItem value="2">2</SegmentedControlItem>
528
+ <SegmentedControlItem value="unbounded">∞</SegmentedControlItem>
529
+ </SegmentedControl>
525
530
  </div>
526
531
  )}
527
532
  <div className="flex items-center gap-2">
528
533
  <span className="text-[11px] text-fg-muted w-24 shrink-0">hasSuffix</span>
529
- <div className="flex gap-1.5">
530
- <Tab active={hasSuffix} onClick={() => setHasSuffix(true)}>on</Tab>
531
- <Tab active={!hasSuffix} onClick={() => setHasSuffix(false)}>off</Tab>
532
- </div>
534
+ <SegmentedControl size="sm" aria-label="hasSuffix" value={hasSuffix ? 'on' : 'off'} onValueChange={(v) => setHasSuffix(v === 'on')}>
535
+ <SegmentedControlItem value="on">on</SegmentedControlItem>
536
+ <SegmentedControlItem value="off">off</SegmentedControlItem>
537
+ </SegmentedControl>
533
538
  </div>
534
539
  </div>
535
540
 
@@ -541,7 +546,7 @@ const InspectorInner = () => {
541
546
  <div className="px-8 py-8 rounded-lg bg-canvas border border-divider flex items-center justify-center">
542
547
  {consumer === 'MenuItem' && (
543
548
  <MenuFrame width={360}>
544
- <MenuItem
549
+ <MenuItem role="presentation"
545
550
  size={size}
546
551
  startIcon={effectiveHasPrefix && effectivePrefixType === 'icon' ? Mail : undefined}
547
552
  avatar={effectiveHasPrefix && effectivePrefixType === 'avatar' ? { alt: "Alice", color: "indigo" as const, hoverCard: personHover("Alice", "Design team lead") } : undefined}
@@ -986,10 +991,10 @@ export const AlignmentThreshold = {
986
991
 
987
992
  {/* Live example */}
988
993
  <MenuFrame width={360}>
989
- <MenuItem size="md" startIcon={Mail} description="每日寄送摘要信件" tag={<Tag size="md" color="blue">Pro</Tag>}>
994
+ <MenuItem role="presentation" size="md" startIcon={Mail} description="每日寄送摘要信件" tag={<Tag size="md" color="blue">Pro</Tag>}>
990
995
  電子郵件通知
991
996
  </MenuItem>
992
- <MenuItem size="md" startIcon={Bell} description="瀏覽器推送即時通知" tag={<Tag size="md" color="green">Free</Tag>}>
997
+ <MenuItem role="presentation" size="md" startIcon={Bell} description="瀏覽器推送即時通知" tag={<Tag size="md" color="green">Free</Tag>}>
993
998
  推送通知
994
999
  </MenuItem>
995
1000
  </MenuFrame>
@@ -1040,10 +1045,10 @@ export const AlignmentThreshold = {
1040
1045
 
1041
1046
  {/* Live example */}
1042
1047
  <MenuFrame width={360}>
1043
- <MenuItem size="md" avatar={{ src: avatarSrc("Alice Chen", 64), alt: "Alice", color: "indigo" as const, hoverCard: personHover("Alice Chen", "Design team lead") }} description="Design team lead">
1048
+ <MenuItem role="presentation" size="md" avatar={{ src: avatarSrc("Alice Chen", 64), alt: "Alice", color: "indigo" as const, hoverCard: personHover("Alice Chen", "Design team lead") }} description="Design team lead">
1044
1049
  Alice Chen
1045
1050
  </MenuItem>
1046
- <MenuItem size="md" avatar={{ src: avatarSrc("Bob Wang", 64), alt: "Bob", color: "yellow" as const, hoverCard: personHover("Bob Wang", "Backend engineer") }} description="Backend engineer">
1051
+ <MenuItem role="presentation" size="md" avatar={{ src: avatarSrc("Bob Wang", 64), alt: "Bob", color: "yellow" as const, hoverCard: personHover("Bob Wang", "Backend engineer") }} description="Backend engineer">
1047
1052
  Bob Wang
1048
1053
  </MenuItem>
1049
1054
  </MenuFrame>
@@ -1123,7 +1128,7 @@ export const ReadingModes = {
1123
1128
  <div key={sz} className="flex items-start gap-3">
1124
1129
  <span className="text-[12px] text-fg-muted w-6 shrink-0 pt-2 font-mono font-semibold">{sz}</span>
1125
1130
  <MenuFrame width={300}>
1126
- <MenuItem size={sz} startIcon={Mail} description="每日寄送摘要信件">
1131
+ <MenuItem role="presentation" size={sz} startIcon={Mail} description="每日寄送摘要信件">
1127
1132
  電子郵件通知
1128
1133
  </MenuItem>
1129
1134
  </MenuFrame>
@@ -1287,9 +1292,9 @@ export const IconColorsAndPresets = {
1287
1292
  <div className="flex flex-col gap-2">
1288
1293
  <span className="text-[11px] text-fg-muted font-medium">Prefix icon = foreground(代表內容)</span>
1289
1294
  <MenuFrame width={260}>
1290
- <MenuItem size="md" startIcon={Mail}>電子郵件</MenuItem>
1291
- <MenuItem size="md" startIcon={Settings}>設定</MenuItem>
1292
- <MenuItem size="md" startIcon={Star}>收藏</MenuItem>
1295
+ <MenuItem role="presentation" size="md" startIcon={Mail}>電子郵件</MenuItem>
1296
+ <MenuItem role="presentation" size="md" startIcon={Settings}>設定</MenuItem>
1297
+ <MenuItem role="presentation" size="md" startIcon={Star}>收藏</MenuItem>
1293
1298
  </MenuFrame>
1294
1299
  </div>
1295
1300
 
@@ -1297,7 +1302,7 @@ export const IconColorsAndPresets = {
1297
1302
  <div className="flex flex-col gap-2">
1298
1303
  <span className="text-[11px] text-fg-muted font-medium">Suffix indicator = fg-muted(指示方向)</span>
1299
1304
  <MenuFrame width={280}>
1300
- <MenuItem
1305
+ <MenuItem role="presentation"
1301
1306
  size="md"
1302
1307
  startIcon={Globe}
1303
1308
  endContent={
@@ -1309,7 +1314,7 @@ export const IconColorsAndPresets = {
1309
1314
  >
1310
1315
  語言
1311
1316
  </MenuItem>
1312
- <MenuItem
1317
+ <MenuItem role="presentation"
1313
1318
  size="md"
1314
1319
  startIcon={Lock}
1315
1320
  endContent={
@@ -1327,7 +1332,7 @@ export const IconColorsAndPresets = {
1327
1332
  <div className="flex flex-col gap-2">
1328
1333
  <span className="text-[11px] text-fg-muted font-medium">危險操作 = 與 label 同色(text-error)</span>
1329
1334
  <MenuFrame width={260}>
1330
- <MenuItem size="md" startIcon={Trash2} className="text-error">
1335
+ <MenuItem role="presentation" size="md" startIcon={Trash2} className="text-error">
1331
1336
  刪除專案
1332
1337
  </MenuItem>
1333
1338
  </MenuFrame>
@@ -1380,10 +1385,10 @@ export const IconColorsAndPresets = {
1380
1385
  <div className="flex flex-col gap-2">
1381
1386
  <span className="text-[11px] text-fg-muted font-medium">MenuItem</span>
1382
1387
  <MenuFrame width={280}>
1383
- <MenuItem size="md" startIcon={Mail} description="每日寄送摘要信件">
1388
+ <MenuItem role="presentation" size="md" startIcon={Mail} description="每日寄送摘要信件">
1384
1389
  電子郵件通知
1385
1390
  </MenuItem>
1386
- <MenuItem size="md" startIcon={Bell}>
1391
+ <MenuItem role="presentation" size="md" startIcon={Bell}>
1387
1392
  推送通知
1388
1393
  </MenuItem>
1389
1394
  </MenuFrame>
@@ -727,7 +727,17 @@ export const ItemInlineActionButton = React.forwardRef<
727
727
  <span
728
728
  aria-hidden
729
729
  className={cn(
730
- "absolute pointer-events-none",
730
+ // ⚠️ 這裡**刻意沒有** `pointer-events-none`,日後不得以「它只是裝飾層」為由加回去。
731
+ // 這塊底色比按鈕盒每邊大 1px(16→18,lg 20→22)。它是 <button> 的子節點,只要不擋指標,
732
+ // 溢出的那 1px 會自己接住點擊並冒泡到 button —— 命中區於是恰好等於使用者看得到的那塊底色。
733
+ // 依據:user 2026-09-24 裁示「重點是要讓 inline action 的可點擊範圍跟其 hover 底色一樣吧?
734
+ // 都是 18*18」,並於同日對本檔本行確認「對,就這樣改」。跨元件 owner =
735
+ // ds-canonical/references/hit-area-canonical.md(規則:懸停回饋的形狀 ≡ 命中區;圖示是內容,可比命中區小)。
736
+ // 本 DS 以滑鼠精度為前提,不以觸控尺寸建議當依據把命中區撐大到超過懸停回饋(同日 user 裁示)。
737
+ // 歷史:原本那行 `pointer-events-none` 沒有任何理由 —— 2026-04-01 7dd65fbf 隨首版誕生、
738
+ // 2026-04-14 4e53ff99 逐字搬進本檔,兩次 commit message 與註解都沒出現 hit / pointer / 點擊 任何一個字。
739
+ // 實測(改前):命中 16.75×16.75,右緣與下緣各短約 1.25px;側欄點在看得見的底色下緣會穿過去觸發整列導覽。
740
+ "absolute",
731
741
  "rounded-md",
732
742
  "bg-transparent",
733
743
  hoverBgClassName ?? "group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active",
@@ -790,7 +800,8 @@ ItemInlineAction.displayName = "ItemInlineAction"
790
800
  // - `h-[1lh]`:suffix 永遠對齊第一行 label(跟 prefix 解耦)
791
801
  // - `ml-auto`:靠右
792
802
  // - `gap-2`:多個 inline action 之間的標準間距(inline-action.spec.md canonical SSOT)
793
- // - `hoverReveal` opt-in:opacity 0→1 on 父層 row hover/focus-visible
803
+ // - `hoverReveal` opt-in:opacity 0→1 on 父層 row hover/focus-visible —— **瞬間出現,不淡入**
804
+ // (tokens/motion/motion.spec.md「hover 回饋不做過渡」;2026-09-26 延伸到滑過才出現的按鈕,待辦總帳 L9 / N4(3))
794
805
  //
795
806
  // `hoverGroup`(2026-05-05 v8 SSOT 升級):row primitive group selector 參數化。
796
807
  // 先前 `/menu-item` hardcode → TreeView(`/tree-item`)/ FileItem(`/row`)/
@@ -800,17 +811,17 @@ ItemInlineAction.displayName = "ItemInlineAction"
800
811
 
801
812
  const SUFFIX_HOVER_REVEAL_BY_GROUP = {
802
813
  "menu-item":
803
- "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0",
814
+ "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100",
804
815
  "tree-item":
805
- "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0",
806
- row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150 motion-reduce:duration-0",
816
+ "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100",
817
+ row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100",
807
818
  } as const
808
819
 
809
820
  export type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP
810
821
 
811
822
  export interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {
812
823
  /**
813
- * Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才淡入。
824
+ * Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才出現(瞬間,不淡入;tokens/motion/motion.spec.md)。
814
825
  * 對齊 TreeView / SidebarMenuButton inline action 行為。預設 false(永遠顯示,如 Badge)。
815
826
  *
816
827
  * 用 `group-has-[:focus-visible]` 而非 `group-focus-within`——後者會被 mouse click 觸發,
@@ -60,6 +60,7 @@ benchmark:
60
60
 
61
61
  > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
62
62
 
63
+ - `agent-panel.spec.md`
63
64
  - `calendar.spec.md`
64
65
  - `date-picker.spec.md`
65
66
  - `dialog.spec.md`
@@ -53,7 +53,7 @@ benchmark:
53
53
 
54
54
  ### 1. Border-bottom
55
55
 
56
- - **Token**:`border-b border-divider`(1px / `--divider-color`)
56
+ - **Token**:`border-b border-divider`(1px / `--divider`,`semantic.css`;`--divider-color` 這個名字從不存在,2026-07-10 hunt 判 STALE、2026-09-29 改正)
57
57
  - **Default**:有 border(分區效果)
58
58
  - **Auto-suppress when withTabs**:見下「withTabs 連動」段
59
59
 
@@ -77,7 +77,7 @@ benchmark:
77
77
 
78
78
  **Canonical**:Chrome header avatar = **24px,density-fixed,row-size-fixed**。涵蓋同一條 chrome header 內**兩種** avatar,皆 24px:**(a) 品牌 mark**(WorkspaceBrand,左)+ **(b) 帳號入口 account entry**(primary-header globalHeader 右側的個人設定 avatar)。同一條 chrome header 內所有 avatar 尺寸一致。
79
79
 
80
- 對齊 5 家世界級共識(Linear / Notion / Figma / Slack / Polaris chrome header brand mark 皆固定 24px,不 density-scale 也不 row-size-scale;GitHub 20 / Atlassian small 24 / Linear 右上帳號 avatar 同屬此小尺寸區間)。設計理由:chrome header avatar(品牌或帳號)是身份識別 mark,視覺穩定優於 density 緊鬆 / row size 調整;**帳號入口雖可互動,互動感由 focus ring + hover 提供,不靠把 avatar 放大到 field height**(button 跟 density 走 touch target 邏輯,avatar 不綁同邏輯)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
80
+ 對齊 5 家世界級共識(Linear / Notion / Figma / Slack / Polaris chrome header brand mark 皆固定 24px,不 density-scale 也不 row-size-scale;GitHub 20 / Atlassian small 24 / Linear 右上帳號 avatar 同屬此小尺寸區間)。設計理由:chrome header avatar(品牌或帳號)是身份識別 mark,視覺穩定優於 density 緊鬆 / row size 調整;**帳號入口雖可互動,互動感由 focus ring + hover 提供,不靠把 avatar 放大到 field height**(button 的尺寸跟著 density 走 `--field-height-*`,avatar 不綁同邏輯;2026-09-24 更正原文的「button 跟 density 走 touch target 邏輯」—— 本 DS 以滑鼠指標的精度為前提,尺寸不以觸控門檻推導,見 `ds-canonical/references/hit-area-canonical.md`)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
81
81
 
82
82
  **Chrome header 不是 row context**:無 sm/md/lg row size lookup 需求 → chrome header 內 avatar 用 **raw `<Avatar size={24}>`**,**不用 `<ItemAvatar>`**(後者是 row primitive anatomy helper,scope 是 row context — 詳 `item-anatomy.spec.md`「Scope 例外:Chrome header 不是 row context」段)。
83
83
 
@@ -326,6 +326,7 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
326
326
  > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
327
327
 
328
328
  - `account-menu.spec.md`
329
+ - `agent-panel.spec.md`
329
330
  - `app-shell.spec.md`
330
331
  - `density.spec.md`
331
332
  - `dialog.spec.md`
@@ -132,6 +132,8 @@ return (
132
132
  )
133
133
  ```
134
134
 
135
+ > **箭頭卸載時的焦點接力(2026-09-29,待辦總帳 OE26)**:箭頭是條件渲染,鍵盤使用者按到底的那一下焦點正停在它上面;`OverflowScrollArrow` 在 layout-effect cleanup(React 拿掉節點之前)看到焦點在自己身上,就交給同容器另一側箭頭,兩側都沒有(內容不再溢出)就交給捲動容器(`useScrollEdges` 在容器上標 `data-overflow-scroller`,必要時補 `tabindex=-1`)。消費者不用多傳任何東西;同 BulkActionBar / Dialog 的 return-focus 契約。閘:`horizontal-overflow.stories.tsx`「到底時焦點交給另一側箭頭」play。
136
+
135
137
  > **雙軸 overflow contract(2026-05-19 codify)**:啟用水平捲動時必同時抑制垂直捲動,避免 CSS overflow 軸計算讓 active indicator 進入非預期的垂直 scroll range。確切 utility 由各 consumer source 擁有;Primer UnderlineNav 採同一雙軸約束。
136
138
 
137
139
  ### 典型 menu 模式組裝
@@ -5,6 +5,7 @@
5
5
  // overflow affordance(scroll arrows / menu trigger / fade mask)一律從這裡取用。
6
6
  // 本頁給 DS contributor 看 primitive 的組裝方式與 canonical 規則。
7
7
  import type { Meta, StoryObj } from '@storybook/react'
8
+ import { expect, waitFor, within } from '@storybook/test'
8
9
  import {
9
10
  useScrollEdges,
10
11
  useScrollByPage,
@@ -137,3 +138,38 @@ export const MenuMode: Story = {
137
138
  </div>
138
139
  ),
139
140
  }
141
+
142
+
143
+ /**
144
+ * 到底時焦點交給另一側箭頭(2026-09-29 待辦總帳 OE26):箭頭是條件渲染,鍵盤使用者按到底的那一下焦點正停在它上面,
145
+ * 卸載會讓焦點掉到 body。test-only:以 play 當閘(story-demo-focus 閘載入每支 story 並跑 play,斷言不成立就紅);
146
+ * 對照組 = 先驗證焦點真的在右箭頭上、右箭頭真的卸載了,再驗證焦點落在左箭頭。
147
+ */
148
+ export const ArrowUnmountHandsOffFocus: Story = {
149
+ name: '到底時焦點交給另一側箭頭',
150
+ tags: ['test-only'],
151
+ parameters: { demoFocus: 'keep' },
152
+ render: () => <FilmstripScrollDemo />,
153
+ play: async ({ canvasElement }) => {
154
+ const canvas = within(canvasElement)
155
+ // 容器的標記由 useScrollEdges 的 effect 在掛載後才寫上;慢的 runner 上 play 可能先於 passive effect 跑到,
156
+ // 所以等元素本身出現(M32:等那個元素,不用固定睡眠),不拿「第一次查不到」當產品裁決(2026-09-29 CI 首跑抓到)。
157
+ const scroller = await waitFor(() => {
158
+ const el = canvasElement.querySelector<HTMLElement>('[data-overflow-scroller]')
159
+ if (!el) throw new Error('捲動容器尚未被 useScrollEdges 標上 data-overflow-scroller')
160
+ return el
161
+ })
162
+ const right = await canvas.findByRole('button', { name: '向右捲動' })
163
+ right.focus()
164
+ await expect(document.activeElement).toBe(right)
165
+ // 一步捲到底(不走 smooth 動畫,免得時序決定結果)
166
+ scroller.scrollTo({ left: scroller.scrollWidth, behavior: 'instant' as ScrollBehavior })
167
+ await waitFor(() => expect(canvas.queryByRole('button', { name: '向右捲動' })).toBeNull())
168
+ const left = canvas.getByRole('button', { name: '向左捲動' })
169
+ await expect(document.activeElement).toBe(left)
170
+ // 兩側都不在(內容不再溢出)→ 焦點交給捲動容器本身
171
+ scroller.scrollTo({ left: 0, behavior: 'instant' as ScrollBehavior })
172
+ await waitFor(() => expect(canvas.queryByRole('button', { name: '向左捲動' })).toBeNull())
173
+ await expect(document.activeElement).toBe(canvas.getByRole('button', { name: '向右捲動' }))
174
+ },
175
+ }
@@ -152,8 +152,35 @@ export const OverflowScrollArrow: React.FC<OverflowScrollArrowProps> = ({
152
152
  'aria-label': ariaLabel,
153
153
  }) => {
154
154
  const defaultLabel = direction === 'left' ? '向左捲動' : '向右捲動' // i18n-allow: DS default; consumer override via aria-label prop
155
+ const buttonRef = React.useRef<HTMLButtonElement>(null)
156
+ // ── 焦點接力(2026-09-29,待辦總帳 OE26)──
157
+ // 箭頭是條件渲染(spec「典型 scroll 模式組裝」:`!atEnd && canScroll`),鍵盤使用者按到底的那一下,焦點正停在它上面,
158
+ // 卸載會讓焦點掉到 body、下一次 Tab 從文件開頭重來。layout-effect 的 cleanup 在 React 把節點拿掉之前跑,此時 activeElement
159
+ // 還是這顆鈕 → 交給同一個容器裡的另一側箭頭(到底時左箭頭一定在);另一側也沒有(內容不再溢出)→ 交給捲動容器本身
160
+ //(`useScrollEdges` 在容器上標 `data-overflow-scroller`,焦點給它時補 tabindex=-1)。同 BulkActionBar 的 return-focus,沒有新 prop。
161
+ React.useLayoutEffect(() => {
162
+ const el = buttonRef.current
163
+ return () => {
164
+ if (!el || document.activeElement !== el) return
165
+ const host = el.closest<HTMLElement>('[data-overflow-arrow]')?.parentElement
166
+ if (!host) return
167
+ // 等這次 commit 做完再找另一側:同一次 commit 常常「卸掉這一側、掛上另一側」(捲回起點:左箭頭卸、右箭頭掛),
168
+ // React 先做刪除再做插入,cleanup 當下另一側還不在 DOM 裡 —— 2026-09-29 第一版在這裡直接找,story 閘抓到焦點落到容器而不是箭頭。
169
+ queueMicrotask(() => {
170
+ const active = document.activeElement
171
+ if (active && active !== document.body && host.contains(active)) return // 已有人接手(例如消費者自己搬了焦點)
172
+ const other = Array.from(host.querySelectorAll<HTMLElement>('[data-overflow-arrow] button')).find((b) => b !== el && b.isConnected)
173
+ if (other) { other.focus({ preventScroll: true }); return }
174
+ const scroller = host.querySelector<HTMLElement>('[data-overflow-scroller]')
175
+ if (!scroller) return
176
+ if (!scroller.hasAttribute('tabindex')) scroller.setAttribute('tabindex', '-1')
177
+ scroller.focus({ preventScroll: true })
178
+ })
179
+ }
180
+ }, [])
155
181
  return (
156
182
  <div
183
+ data-overflow-arrow={direction}
157
184
  className={cn(
158
185
  'absolute top-0 bottom-0 flex items-center pointer-events-none z-10',
159
186
  direction === 'left' ? 'left-0' : 'right-0',
@@ -161,6 +188,7 @@ export const OverflowScrollArrow: React.FC<OverflowScrollArrowProps> = ({
161
188
  >
162
189
  <div className="pointer-events-auto">
163
190
  <Button
191
+ ref={buttonRef}
164
192
  variant="text"
165
193
  size="sm"
166
194
  iconOnly