@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

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 (635) hide show
  1. package/CHANGELOG.md +141 -0
  2. package/dist/AlertDialog/AlertDialog.d.ts +1 -1
  3. package/dist/AlertDialog/AlertDialog.d.ts.map +1 -1
  4. package/dist/AlertDialog/AlertDialog.js +20 -18
  5. package/dist/AlertDialog/useImperativeAlertDialog.d.ts +0 -2
  6. package/dist/AlertDialog/useImperativeAlertDialog.d.ts.map +1 -1
  7. package/dist/AlertDialog/useImperativeAlertDialog.js +3 -5
  8. package/dist/AppShell/AppShell.d.ts +1 -1
  9. package/dist/AppShell/AppShell.d.ts.map +1 -1
  10. package/dist/AppShell/AppShell.js +55 -53
  11. package/dist/AspectRatio/AspectRatio.d.ts +48 -10
  12. package/dist/AspectRatio/AspectRatio.d.ts.map +1 -1
  13. package/dist/AspectRatio/AspectRatio.js +33 -12
  14. package/dist/AspectRatio/index.d.ts +1 -1
  15. package/dist/AspectRatio/index.d.ts.map +1 -1
  16. package/dist/Avatar/Avatar.d.ts.map +1 -1
  17. package/dist/Avatar/Avatar.js +28 -26
  18. package/dist/Avatar/AvatarStatusDot.js +6 -6
  19. package/dist/AvatarGroup/AvatarGroup.js +6 -6
  20. package/dist/AvatarGroup/AvatarGroupOverflow.js +7 -7
  21. package/dist/Badge/Badge.js +3 -3
  22. package/dist/Banner/Banner.d.ts.map +1 -1
  23. package/dist/Banner/Banner.js +32 -25
  24. package/dist/Blockquote/Blockquote.js +7 -7
  25. package/dist/Breadcrumbs/BreadcrumbItem.js +17 -17
  26. package/dist/Breadcrumbs/Breadcrumbs.js +7 -7
  27. package/dist/Button/Button.js +19 -19
  28. package/dist/ButtonGroup/ButtonGroup.js +7 -7
  29. package/dist/Calendar/Calendar.d.ts.map +1 -1
  30. package/dist/Calendar/Calendar.js +68 -48
  31. package/dist/Calendar/dayCellUtils.d.ts.map +1 -1
  32. package/dist/Calendar/styles.d.ts +2 -2
  33. package/dist/Calendar/styles.d.ts.map +1 -1
  34. package/dist/Calendar/styles.js +2 -2
  35. package/dist/Card/Card.d.ts +4 -2
  36. package/dist/Card/Card.d.ts.map +1 -1
  37. package/dist/Card/Card.js +18 -10
  38. package/dist/Carousel/Carousel.d.ts.map +1 -1
  39. package/dist/Carousel/Carousel.js +24 -21
  40. package/dist/Center/Center.js +3 -3
  41. package/dist/Chat/ChatComposer.js +23 -23
  42. package/dist/Chat/ChatComposerDrawer.js +14 -14
  43. package/dist/Chat/ChatComposerInput.d.ts +1 -1
  44. package/dist/Chat/ChatComposerInput.d.ts.map +1 -1
  45. package/dist/Chat/ChatComposerInput.js +27 -15
  46. package/dist/Chat/ChatDictationButton.d.ts +1 -1
  47. package/dist/Chat/ChatDictationButton.d.ts.map +1 -1
  48. package/dist/Chat/ChatDictationButton.js +13 -11
  49. package/dist/Chat/ChatLayout.js +17 -17
  50. package/dist/Chat/ChatLayoutScrollButton.d.ts +1 -1
  51. package/dist/Chat/ChatLayoutScrollButton.d.ts.map +1 -1
  52. package/dist/Chat/ChatLayoutScrollButton.js +12 -10
  53. package/dist/Chat/ChatMessage.js +12 -12
  54. package/dist/Chat/ChatMessageBubble.js +7 -7
  55. package/dist/Chat/ChatMessageList.js +14 -14
  56. package/dist/Chat/ChatMessageMetadata.d.ts +1 -1
  57. package/dist/Chat/ChatMessageMetadata.d.ts.map +1 -1
  58. package/dist/Chat/ChatMessageMetadata.js +14 -12
  59. package/dist/Chat/ChatPastedTextToken.js +13 -13
  60. package/dist/Chat/ChatSendButton.js +3 -3
  61. package/dist/Chat/ChatSystemMessage.d.ts +1 -1
  62. package/dist/Chat/ChatSystemMessage.d.ts.map +1 -1
  63. package/dist/Chat/ChatSystemMessage.js +17 -17
  64. package/dist/Chat/ChatTokenizedText.d.ts +1 -1
  65. package/dist/Chat/ChatTokenizedText.d.ts.map +1 -1
  66. package/dist/Chat/ChatTokenizedText.js +24 -15
  67. package/dist/Chat/ChatToolCalls.d.ts.map +1 -1
  68. package/dist/Chat/ChatToolCalls.js +81 -74
  69. package/dist/Chat/index.d.ts +1 -1
  70. package/dist/Chat/index.d.ts.map +1 -1
  71. package/dist/Chat/useTriggerMenu.d.ts.map +1 -1
  72. package/dist/Chat/useTriggerMenu.js +15 -15
  73. package/dist/CheckboxInput/CheckboxInput.d.ts +1 -1
  74. package/dist/CheckboxInput/CheckboxInput.d.ts.map +1 -1
  75. package/dist/CheckboxInput/CheckboxInput.js +25 -23
  76. package/dist/CheckboxList/CheckboxList.js +9 -9
  77. package/dist/CheckboxList/CheckboxListItem.d.ts +1 -1
  78. package/dist/CheckboxList/CheckboxListItem.d.ts.map +1 -1
  79. package/dist/CheckboxList/CheckboxListItem.js +8 -6
  80. package/dist/Citation/Citation.js +10 -10
  81. package/dist/ClickableCard/ClickableCard.d.ts.map +1 -1
  82. package/dist/ClickableCard/ClickableCard.js +32 -9
  83. package/dist/Code/Code.js +3 -3
  84. package/dist/CodeBlock/CodeBlock.d.ts +10 -1
  85. package/dist/CodeBlock/CodeBlock.d.ts.map +1 -1
  86. package/dist/CodeBlock/CodeBlock.js +88 -52
  87. package/dist/Collapsible/Collapsible.d.ts +9 -3
  88. package/dist/Collapsible/Collapsible.d.ts.map +1 -1
  89. package/dist/Collapsible/Collapsible.js +109 -22
  90. package/dist/Collapsible/CollapsibleGroup.d.ts +37 -7
  91. package/dist/Collapsible/CollapsibleGroup.d.ts.map +1 -1
  92. package/dist/Collapsible/CollapsibleGroup.js +64 -12
  93. package/dist/Collapsible/CollapsibleGroupContext.d.ts +24 -0
  94. package/dist/Collapsible/CollapsibleGroupContext.d.ts.map +1 -1
  95. package/dist/Collapsible/CollapsibleGroupContext.js +26 -3
  96. package/dist/Collapsible/index.d.ts +1 -0
  97. package/dist/Collapsible/index.d.ts.map +1 -1
  98. package/dist/Collapsible/useCollapsible.d.ts +4 -1
  99. package/dist/Collapsible/useCollapsible.d.ts.map +1 -1
  100. package/dist/Collapsible/useCollapsible.js +20 -6
  101. package/dist/CommandPalette/CommandPalette.d.ts.map +1 -1
  102. package/dist/CommandPalette/CommandPalette.js +36 -34
  103. package/dist/CommandPalette/CommandPaletteEmpty.js +3 -3
  104. package/dist/CommandPalette/CommandPaletteFooter.js +16 -16
  105. package/dist/CommandPalette/CommandPaletteGroup.js +5 -5
  106. package/dist/CommandPalette/CommandPaletteInput.js +13 -13
  107. package/dist/CommandPalette/CommandPaletteItem.js +3 -3
  108. package/dist/CommandPalette/CommandPaletteList.js +3 -3
  109. package/dist/ContextMenu/ContextMenu.d.ts +7 -2
  110. package/dist/ContextMenu/ContextMenu.d.ts.map +1 -1
  111. package/dist/ContextMenu/ContextMenu.js +76 -43
  112. package/dist/DateInput/DateInput.js +18 -18
  113. package/dist/DateRangeInput/DateRangeInput.js +21 -21
  114. package/dist/DateTimeInput/DateTimeInput.d.ts +5 -2
  115. package/dist/DateTimeInput/DateTimeInput.d.ts.map +1 -1
  116. package/dist/DateTimeInput/DateTimeInput.js +30 -26
  117. package/dist/DateTimeInput/index.d.ts +1 -1
  118. package/dist/DateTimeInput/index.d.ts.map +1 -1
  119. package/dist/Dialog/Dialog.js +9 -9
  120. package/dist/Dialog/DialogHeader.js +16 -16
  121. package/dist/Dialog/useImperativeDialog.js +3 -3
  122. package/dist/Divider/Divider.js +7 -7
  123. package/dist/DropdownMenu/DropdownMenu.js +10 -10
  124. package/dist/DropdownMenu/DropdownMenuItem.d.ts +2 -17
  125. package/dist/DropdownMenu/DropdownMenuItem.d.ts.map +1 -1
  126. package/dist/DropdownMenu/DropdownMenuItem.js +3 -3
  127. package/dist/DropdownMenu/renderDropdownItems.js +10 -10
  128. package/dist/EmptyState/EmptyState.js +9 -9
  129. package/dist/Field/Field.js +17 -17
  130. package/dist/Field/FieldLabel.js +15 -15
  131. package/dist/Field/InputClearButton.js +5 -5
  132. package/dist/FieldStatus/FieldStatus.js +3 -3
  133. package/dist/FileInput/FileInput.js +29 -29
  134. package/dist/FormLayout/FormLayout.js +5 -5
  135. package/dist/Grid/Grid.d.ts +4 -3
  136. package/dist/Grid/Grid.d.ts.map +1 -1
  137. package/dist/Grid/Grid.js +29 -12
  138. package/dist/Grid/GridSpan.js +3 -3
  139. package/dist/HStack/HStack.js +3 -3
  140. package/dist/Heading/Heading.js +10 -10
  141. package/dist/HoverCard/HoverCard.js +9 -9
  142. package/dist/HoverCard/useHoverCard.d.ts +5 -1
  143. package/dist/HoverCard/useHoverCard.d.ts.map +1 -1
  144. package/dist/HoverCard/useHoverCard.js +3 -3
  145. package/dist/Icon/Icon.d.ts.map +1 -1
  146. package/dist/Icon/Icon.js +16 -12
  147. package/dist/Icon/defaultIcons.js +116 -116
  148. package/dist/IconButton/IconButton.js +3 -3
  149. package/dist/InputGroup/InputGroup.js +11 -11
  150. package/dist/InputGroup/InputGroupText.js +3 -3
  151. package/dist/Item/Item.js +18 -18
  152. package/dist/Kbd/Kbd.js +5 -5
  153. package/dist/Layer/LayerProvider.js +7 -7
  154. package/dist/Layer/useLayer.d.ts +29 -2
  155. package/dist/Layer/useLayer.d.ts.map +1 -1
  156. package/dist/Layer/useLayer.js +44 -31
  157. package/dist/Layout/Layout.js +21 -21
  158. package/dist/Layout/LayoutContent.js +3 -3
  159. package/dist/Layout/LayoutFooter.js +5 -5
  160. package/dist/Layout/LayoutHeader.js +5 -5
  161. package/dist/Layout/LayoutPanel.js +3 -3
  162. package/dist/Lightbox/Lightbox.d.ts.map +1 -1
  163. package/dist/Lightbox/Lightbox.js +55 -31
  164. package/dist/Lightbox/useLightbox.d.ts +0 -1
  165. package/dist/Lightbox/useLightbox.d.ts.map +1 -1
  166. package/dist/Lightbox/useLightbox.js +3 -4
  167. package/dist/Link/Link.d.ts +0 -2
  168. package/dist/Link/Link.d.ts.map +1 -1
  169. package/dist/Link/Link.js +15 -17
  170. package/dist/Link/LinkProvider.js +3 -3
  171. package/dist/Link/useLinkify.js +3 -3
  172. package/dist/List/List.js +11 -11
  173. package/dist/List/ListItem.js +11 -11
  174. package/dist/Markdown/Markdown.d.ts.map +1 -1
  175. package/dist/Markdown/Markdown.js +102 -102
  176. package/dist/MetadataList/MetadataList.js +10 -10
  177. package/dist/MetadataList/MetadataListItem.js +15 -15
  178. package/dist/MobileNav/MobileNav.d.ts +1 -1
  179. package/dist/MobileNav/MobileNav.d.ts.map +1 -1
  180. package/dist/MobileNav/MobileNav.js +26 -23
  181. package/dist/MobileNav/MobileNavToggle.js +5 -5
  182. package/dist/MoreMenu/MoreMenu.js +3 -3
  183. package/dist/MultiSelector/MultiSelector.js +56 -56
  184. package/dist/NavIcon/NavIcon.js +3 -3
  185. package/dist/NavMenu/NavHeadingMenu.js +5 -5
  186. package/dist/NavMenu/NavHeadingMenuItem.js +8 -8
  187. package/dist/NumberInput/NumberInput.d.ts.map +1 -1
  188. package/dist/NumberInput/NumberInput.js +48 -32
  189. package/dist/Outline/Outline.js +15 -15
  190. package/dist/OverflowList/OverflowList.js +8 -8
  191. package/dist/Overlay/Overlay.js +3 -3
  192. package/dist/Overlay/OverlayScrim.js +5 -5
  193. package/dist/Overlay/useOverlay.d.ts +0 -3
  194. package/dist/Overlay/useOverlay.d.ts.map +1 -1
  195. package/dist/Overlay/useOverlay.js +3 -6
  196. package/dist/Pagination/Pagination.d.ts +1 -1
  197. package/dist/Pagination/Pagination.d.ts.map +1 -1
  198. package/dist/Pagination/Pagination.js +125 -72
  199. package/dist/Popover/Popover.js +16 -16
  200. package/dist/Popover/usePopover.js +7 -7
  201. package/dist/PowerSearch/PowerSearch.d.ts.map +1 -1
  202. package/dist/PowerSearch/PowerSearch.js +110 -92
  203. package/dist/PowerSearch/PowerSearchEditPopover.js +84 -84
  204. package/dist/PowerSearch/PowerSearchFilterEditor.js +3 -3
  205. package/dist/PowerSearch/PowerSearchToken.js +5 -5
  206. package/dist/PowerSearch/PowerSearchValueEditor.js +54 -54
  207. package/dist/ProgressBar/ProgressBar.d.ts.map +1 -1
  208. package/dist/ProgressBar/ProgressBar.js +25 -18
  209. package/dist/RadioList/RadioList.js +7 -7
  210. package/dist/RadioList/RadioListItem.d.ts +1 -1
  211. package/dist/RadioList/RadioListItem.d.ts.map +1 -1
  212. package/dist/RadioList/RadioListItem.js +24 -21
  213. package/dist/Resizable/ResizeHandle.d.ts.map +1 -1
  214. package/dist/Resizable/ResizeHandle.js +28 -10
  215. package/dist/Section/Section.js +5 -5
  216. package/dist/SegmentedControl/SegmentedControl.d.ts +1 -1
  217. package/dist/SegmentedControl/SegmentedControl.d.ts.map +1 -1
  218. package/dist/SegmentedControl/SegmentedControl.js +32 -10
  219. package/dist/SegmentedControl/SegmentedControlItem.d.ts +1 -1
  220. package/dist/SegmentedControl/SegmentedControlItem.d.ts.map +1 -1
  221. package/dist/SegmentedControl/SegmentedControlItem.js +18 -12
  222. package/dist/SelectableCard/SelectableCard.js +5 -5
  223. package/dist/Selector/Selector.js +46 -46
  224. package/dist/Selector/SelectorOption.js +3 -3
  225. package/dist/SideNav/SideNav.d.ts.map +1 -1
  226. package/dist/SideNav/SideNav.js +38 -34
  227. package/dist/SideNav/SideNavCollapseButton.d.ts +1 -1
  228. package/dist/SideNav/SideNavCollapseButton.d.ts.map +1 -1
  229. package/dist/SideNav/SideNavCollapseButton.js +8 -6
  230. package/dist/SideNav/SideNavHeading.js +87 -87
  231. package/dist/SideNav/SideNavItem.js +42 -42
  232. package/dist/SideNav/SideNavSection.d.ts +1 -1
  233. package/dist/SideNav/SideNavSection.d.ts.map +1 -1
  234. package/dist/SideNav/SideNavSection.js +18 -16
  235. package/dist/Skeleton/Skeleton.js +3 -3
  236. package/dist/Slider/Slider.js +23 -23
  237. package/dist/Spinner/Spinner.js +9 -9
  238. package/dist/StatusDot/StatusDot.js +5 -5
  239. package/dist/Switch/Switch.d.ts +8 -4
  240. package/dist/Switch/Switch.d.ts.map +1 -1
  241. package/dist/Switch/Switch.js +34 -29
  242. package/dist/TabList/Tab.js +18 -18
  243. package/dist/TabList/TabList.js +5 -5
  244. package/dist/TabList/TabMenu.d.ts.map +1 -1
  245. package/dist/TabList/TabMenu.js +57 -30
  246. package/dist/TabList/tab.markers.stylex.d.ts +1 -1
  247. package/dist/Table/BaseTable.d.ts.map +1 -1
  248. package/dist/Table/BaseTable.js +50 -39
  249. package/dist/Table/Table.js +7 -7
  250. package/dist/Table/TableBody.d.ts +1 -1
  251. package/dist/Table/TableBody.d.ts.map +1 -1
  252. package/dist/Table/TableBody.js +9 -5
  253. package/dist/Table/TableCell.js +3 -3
  254. package/dist/Table/TableFooter.d.ts +1 -1
  255. package/dist/Table/TableFooter.d.ts.map +1 -1
  256. package/dist/Table/TableFooter.js +9 -5
  257. package/dist/Table/TableHeader.d.ts +1 -1
  258. package/dist/Table/TableHeader.d.ts.map +1 -1
  259. package/dist/Table/TableHeader.js +9 -5
  260. package/dist/Table/TableHeaderCell.js +3 -3
  261. package/dist/Table/TableRow.js +5 -5
  262. package/dist/Table/index.d.ts +2 -0
  263. package/dist/Table/index.d.ts.map +1 -1
  264. package/dist/Table/index.js +1 -0
  265. package/dist/Table/plugins/columnResize/useTableColumnResize.d.ts.map +1 -1
  266. package/dist/Table/plugins/columnResize/useTableColumnResize.js +14 -11
  267. package/dist/Table/plugins/filtering/useTableFiltering.js +71 -71
  268. package/dist/Table/plugins/groupedRows/index.d.ts +3 -0
  269. package/dist/Table/plugins/groupedRows/index.d.ts.map +1 -0
  270. package/dist/Table/plugins/groupedRows/index.js +3 -0
  271. package/dist/Table/plugins/groupedRows/useTableGroupedRows.d.ts +78 -0
  272. package/dist/Table/plugins/groupedRows/useTableGroupedRows.d.ts.map +1 -0
  273. package/dist/Table/plugins/groupedRows/useTableGroupedRows.js +250 -0
  274. package/dist/Table/plugins/pagination/paginateData.d.ts.map +1 -1
  275. package/dist/Table/plugins/pagination/paginateData.js +5 -1
  276. package/dist/Table/plugins/pagination/useTablePagination.js +7 -7
  277. package/dist/Table/plugins/rowExpansion/useTableRowExpansion.d.ts +1 -1
  278. package/dist/Table/plugins/rowExpansion/useTableRowExpansion.js +23 -23
  279. package/dist/Table/plugins/selection/useTableSelection.js +18 -18
  280. package/dist/Table/plugins/selection/useTableSelectionState.d.ts.map +1 -1
  281. package/dist/Table/plugins/selection/useTableSelectionState.js +11 -1
  282. package/dist/Table/plugins/sortable/useTableSortable.js +17 -17
  283. package/dist/Table/plugins/sortable/useTableSortableState.d.ts.map +1 -1
  284. package/dist/Table/plugins/sortable/useTableSortableState.js +8 -4
  285. package/dist/Table/tableContextMenu.js +9 -9
  286. package/dist/Text/Text.js +10 -10
  287. package/dist/TextArea/TextArea.js +14 -14
  288. package/dist/TextInput/TextInput.js +15 -15
  289. package/dist/Thumbnail/Thumbnail.d.ts +3 -2
  290. package/dist/Thumbnail/Thumbnail.d.ts.map +1 -1
  291. package/dist/Thumbnail/Thumbnail.js +30 -29
  292. package/dist/TimeInput/TimeInput.d.ts.map +1 -1
  293. package/dist/TimeInput/TimeInput.js +26 -21
  294. package/dist/Timestamp/Timestamp.d.ts +1 -1
  295. package/dist/Timestamp/Timestamp.d.ts.map +1 -1
  296. package/dist/Timestamp/Timestamp.js +37 -26
  297. package/dist/Toast/Toast.d.ts.map +1 -1
  298. package/dist/Toast/Toast.js +25 -17
  299. package/dist/Toast/ToastViewport.d.ts.map +1 -1
  300. package/dist/Toast/ToastViewport.js +23 -11
  301. package/dist/Toast/useToast.d.ts.map +1 -1
  302. package/dist/Toast/useToast.js +44 -4
  303. package/dist/ToggleButton/ToggleButton.js +12 -12
  304. package/dist/ToggleButton/ToggleButtonGroup.js +5 -5
  305. package/dist/Token/Token.js +21 -21
  306. package/dist/Tokenizer/Tokenizer.d.ts.map +1 -1
  307. package/dist/Tokenizer/Tokenizer.js +36 -34
  308. package/dist/Toolbar/Toolbar.js +18 -18
  309. package/dist/Tooltip/Tooltip.js +11 -11
  310. package/dist/Tooltip/useTooltip.d.ts +5 -1
  311. package/dist/Tooltip/useTooltip.d.ts.map +1 -1
  312. package/dist/Tooltip/useTooltip.js +3 -3
  313. package/dist/TopNav/TopNav.js +32 -32
  314. package/dist/TopNav/TopNavHeading.js +67 -67
  315. package/dist/TopNav/TopNavItem.js +5 -5
  316. package/dist/TopNav/TopNavMegaMenu.js +30 -30
  317. package/dist/TopNav/TopNavMegaMenuFeaturedCard.d.ts +1 -1
  318. package/dist/TopNav/TopNavMegaMenuFeaturedCard.d.ts.map +1 -1
  319. package/dist/TopNav/TopNavMegaMenuFeaturedCard.js +25 -14
  320. package/dist/TopNav/TopNavMegaMenuItem.js +16 -16
  321. package/dist/TopNav/TopNavMenu.js +32 -32
  322. package/dist/TreeList/TreeList.js +8 -8
  323. package/dist/TreeList/TreeListBranches.js +11 -11
  324. package/dist/TreeList/TreeListItem.js +30 -30
  325. package/dist/Typeahead/BaseTypeahead.d.ts.map +1 -1
  326. package/dist/Typeahead/BaseTypeahead.js +23 -20
  327. package/dist/Typeahead/Typeahead.js +12 -12
  328. package/dist/Typeahead/TypeaheadItem.js +10 -10
  329. package/dist/VStack/VStack.js +3 -3
  330. package/dist/VisuallyHidden/VisuallyHidden.d.ts +0 -3
  331. package/dist/VisuallyHidden/VisuallyHidden.d.ts.map +1 -1
  332. package/dist/VisuallyHidden/VisuallyHidden.js +0 -3
  333. package/dist/astryx.css +7 -0
  334. package/dist/astryx.umd.js +63 -63
  335. package/dist/astryx.umd.js.map +4 -4
  336. package/dist/docs-types.d.ts +8 -2
  337. package/dist/docs-types.d.ts.map +1 -1
  338. package/dist/hooks/focusableSelector.d.ts +1 -1
  339. package/dist/hooks/focusableSelector.d.ts.map +1 -1
  340. package/dist/hooks/focusableSelector.js +1 -1
  341. package/dist/hooks/index.d.ts +2 -0
  342. package/dist/hooks/index.d.ts.map +1 -1
  343. package/dist/hooks/index.js +1 -0
  344. package/dist/hooks/useFocusTrap.d.ts +3 -0
  345. package/dist/hooks/useFocusTrap.d.ts.map +1 -1
  346. package/dist/hooks/useFocusTrap.js +38 -1
  347. package/dist/hooks/useHotkeys.d.ts +51 -0
  348. package/dist/hooks/useHotkeys.d.ts.map +1 -0
  349. package/dist/hooks/useHotkeys.js +160 -0
  350. package/dist/hooks/useInteractiveRole.d.ts +6 -2
  351. package/dist/hooks/useInteractiveRole.d.ts.map +1 -1
  352. package/dist/hooks/useInteractiveRole.js +6 -2
  353. package/dist/hooks/useKeyboardHint.js +9 -9
  354. package/dist/hooks/useStreamingText.d.ts +3 -1
  355. package/dist/hooks/useStreamingText.d.ts.map +1 -1
  356. package/dist/hooks/useStreamingText.js +14 -5
  357. package/dist/theme/MediaTheme.js +3 -3
  358. package/dist/theme/Theme.js +7 -7
  359. package/dist/theme/defineTheme.d.ts +1 -1
  360. package/dist/theme/defineTheme.d.ts.map +1 -1
  361. package/dist/theme/expandColorScale.d.ts.map +1 -1
  362. package/dist/theme/expandColorScale.js +10 -3
  363. package/dist/theme/hct.d.ts +0 -15
  364. package/dist/theme/hct.d.ts.map +1 -1
  365. package/dist/theme/hct.js +9 -9
  366. package/dist/theme/syntax/SyntaxTheme.js +5 -5
  367. package/dist/theme/tokens.d.ts +10 -2
  368. package/dist/theme/tokens.d.ts.map +1 -1
  369. package/dist/theme/tokens.js +220 -4
  370. package/dist/theme/useTheme.d.ts +3 -2
  371. package/dist/theme/useTheme.d.ts.map +1 -1
  372. package/dist/theme/useTheme.js +73 -6
  373. package/dist/utils/color.d.ts +42 -0
  374. package/dist/utils/color.d.ts.map +1 -0
  375. package/dist/utils/color.js +150 -0
  376. package/dist/utils/composeEventHandlers.d.ts +30 -0
  377. package/dist/utils/composeEventHandlers.d.ts.map +1 -0
  378. package/dist/utils/composeEventHandlers.js +40 -0
  379. package/dist/utils/index.d.ts +3 -0
  380. package/dist/utils/index.d.ts.map +1 -1
  381. package/dist/utils/index.js +3 -1
  382. package/dist/utils/timeParser.d.ts.map +1 -1
  383. package/dist/utils/timeParser.js +8 -5
  384. package/package.json +4 -4
  385. package/src/AlertDialog/AlertDialog.doc.mjs +4 -0
  386. package/src/AlertDialog/AlertDialog.tsx +2 -0
  387. package/src/AlertDialog/useImperativeAlertDialog.tsx +0 -2
  388. package/src/AppShell/AppShell.tsx +2 -0
  389. package/src/AspectRatio/AspectRatio.doc.mjs +28 -1
  390. package/src/AspectRatio/AspectRatio.test.tsx +142 -1
  391. package/src/AspectRatio/AspectRatio.tsx +70 -10
  392. package/src/AspectRatio/index.ts +5 -1
  393. package/src/Avatar/Avatar.doc.mjs +11 -0
  394. package/src/Avatar/Avatar.test.tsx +32 -1
  395. package/src/Avatar/Avatar.tsx +14 -22
  396. package/src/Avatar/AvatarStatusDot.tsx +2 -2
  397. package/src/AvatarGroup/AvatarGroup.doc.mjs +1 -0
  398. package/src/AvatarGroup/AvatarGroup.tsx +2 -2
  399. package/src/AvatarGroup/AvatarGroupOverflow.tsx +2 -2
  400. package/src/Banner/Banner.doc.mjs +8 -0
  401. package/src/Banner/Banner.test.tsx +38 -0
  402. package/src/Banner/Banner.tsx +8 -1
  403. package/src/Calendar/Calendar.doc.mjs +1 -1
  404. package/src/Calendar/Calendar.test.tsx +122 -17
  405. package/src/Calendar/Calendar.tsx +26 -5
  406. package/src/Calendar/dayCellUtils.ts +3 -1
  407. package/src/Calendar/styles.ts +12 -2
  408. package/src/Card/Card.doc.mjs +1 -1
  409. package/src/Card/Card.tsx +16 -6
  410. package/src/Carousel/Carousel.doc.mjs +12 -12
  411. package/src/Carousel/Carousel.test.tsx +13 -0
  412. package/src/Carousel/Carousel.tsx +4 -2
  413. package/src/Chat/Chat.doc.mjs +1 -1
  414. package/src/Chat/ChatComposerInput.test.tsx +27 -1
  415. package/src/Chat/ChatComposerInput.tsx +20 -15
  416. package/src/Chat/ChatDictationButton.test.tsx +43 -0
  417. package/src/Chat/ChatDictationButton.tsx +4 -4
  418. package/src/Chat/ChatLayoutScrollButton.test.tsx +33 -0
  419. package/src/Chat/ChatLayoutScrollButton.tsx +3 -1
  420. package/src/Chat/ChatMessageMetadata.test.tsx +32 -0
  421. package/src/Chat/ChatMessageMetadata.tsx +4 -6
  422. package/src/Chat/ChatSystemMessage.test.tsx +26 -11
  423. package/src/Chat/ChatSystemMessage.tsx +7 -7
  424. package/src/Chat/ChatTokenizedText.test.tsx +29 -16
  425. package/src/Chat/ChatTokenizedText.tsx +15 -8
  426. package/src/Chat/ChatToolCalls.test.tsx +55 -0
  427. package/src/Chat/ChatToolCalls.tsx +10 -12
  428. package/src/Chat/index.ts +1 -4
  429. package/src/Chat/useTriggerMenu.tsx +1 -4
  430. package/src/CheckboxInput/CheckboxInput.doc.mjs +3 -3
  431. package/src/CheckboxInput/CheckboxInput.test.tsx +71 -4
  432. package/src/CheckboxInput/CheckboxInput.tsx +2 -0
  433. package/src/CheckboxList/CheckboxList.test.tsx +19 -0
  434. package/src/CheckboxList/CheckboxListItem.tsx +11 -2
  435. package/src/Citation/Citation.doc.mjs +5 -0
  436. package/src/ClickableCard/ClickableCard.tsx +45 -2
  437. package/src/CodeBlock/CodeBlock.doc.mjs +7 -2
  438. package/src/CodeBlock/CodeBlock.test.tsx +122 -3
  439. package/src/CodeBlock/CodeBlock.tsx +62 -4
  440. package/src/Collapsible/Collapsible.doc.mjs +8 -4
  441. package/src/Collapsible/Collapsible.test.tsx +403 -0
  442. package/src/Collapsible/Collapsible.tsx +85 -10
  443. package/src/Collapsible/CollapsibleGroup.doc.mjs +27 -3
  444. package/src/Collapsible/CollapsibleGroup.test.tsx +314 -0
  445. package/src/Collapsible/CollapsibleGroup.tsx +97 -9
  446. package/src/Collapsible/CollapsibleGroupContext.tsx +34 -2
  447. package/src/Collapsible/index.ts +1 -0
  448. package/src/Collapsible/useCollapsible.ts +20 -6
  449. package/src/CommandPalette/CommandPalette.doc.mjs +5 -0
  450. package/src/CommandPalette/CommandPalette.tsx +5 -3
  451. package/src/CommandPalette/CommandPaletteEmpty.doc.mjs +5 -0
  452. package/src/CommandPalette/CommandPaletteGroup.doc.mjs +10 -0
  453. package/src/CommandPalette/CommandPaletteInput.doc.mjs +6 -0
  454. package/src/CommandPalette/CommandPaletteItem.doc.mjs +6 -0
  455. package/src/CommandPalette/CommandPaletteList.doc.mjs +9 -0
  456. package/src/ContextMenu/ContextMenu.doc.mjs +15 -0
  457. package/src/ContextMenu/ContextMenu.test.tsx +87 -0
  458. package/src/ContextMenu/ContextMenu.tsx +87 -28
  459. package/src/ContextMenu/ContextMenuItem.doc.mjs +6 -0
  460. package/src/DateInput/DateInput.test.tsx +11 -20
  461. package/src/DateRangeInput/DateRangeInput.doc.mjs +9 -6
  462. package/src/DateRangeInput/DateRangeInput.test.tsx +31 -44
  463. package/src/DateTimeInput/DateTimeInput.doc.mjs +3 -2
  464. package/src/DateTimeInput/DateTimeInput.test.tsx +118 -16
  465. package/src/DateTimeInput/DateTimeInput.tsx +8 -2
  466. package/src/DateTimeInput/index.ts +1 -0
  467. package/src/Dialog/Dialog.doc.mjs +4 -0
  468. package/src/Dialog/DialogHeader.doc.mjs +45 -0
  469. package/src/DropdownMenu/DropdownMenu.doc.mjs +1 -1
  470. package/src/DropdownMenu/DropdownMenu.test.tsx +22 -2
  471. package/src/DropdownMenu/DropdownMenuItem.tsx +5 -17
  472. package/src/EmptyState/EmptyState.doc.mjs +1 -1
  473. package/src/Field/Field.test.tsx +1 -4
  474. package/src/Field/FieldLabel.test.tsx +2 -2
  475. package/src/FieldStatus/FieldStatus.test.tsx +282 -0
  476. package/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap +0 -3
  477. package/src/Grid/Grid.test.tsx +43 -18
  478. package/src/Grid/Grid.tsx +26 -9
  479. package/src/HoverCard/HoverCard.doc.mjs +6 -6
  480. package/src/HoverCard/useHoverCard.doc.mjs +5 -5
  481. package/src/HoverCard/useHoverCard.tsx +9 -2
  482. package/src/Icon/Icon.test.tsx +41 -29
  483. package/src/Icon/Icon.tsx +6 -2
  484. package/src/InputGroup/InputGroup.doc.mjs +1 -0
  485. package/src/InputGroup/InputGroup.tsx +2 -2
  486. package/src/InteractiveRoleContext/InteractiveRoleContext.test.tsx +185 -0
  487. package/src/Item/Item.tsx +1 -1
  488. package/src/Layer/useLayer.doc.mjs +2 -2
  489. package/src/Layer/useLayer.test.tsx +221 -2
  490. package/src/Layer/useLayer.tsx +69 -30
  491. package/src/Layout/Layout.test.tsx +285 -0
  492. package/src/Layout/LayoutContent.doc.mjs +12 -0
  493. package/src/Layout/LayoutPanel.doc.mjs +40 -0
  494. package/src/Layout/LayoutSlots.test.tsx +364 -0
  495. package/src/Lightbox/Lightbox.doc.mjs +5 -0
  496. package/src/Lightbox/Lightbox.test.tsx +123 -2
  497. package/src/Lightbox/Lightbox.tsx +29 -1
  498. package/src/Lightbox/useLightbox.tsx +0 -1
  499. package/src/Link/Link.tsx +0 -2
  500. package/src/Markdown/Markdown.tsx +9 -7
  501. package/src/Markdown/parser.perf.test.ts +34 -12
  502. package/src/MobileNav/MobileNav.test.tsx +56 -0
  503. package/src/MobileNav/MobileNav.tsx +13 -8
  504. package/src/NavMenu/NavMenu.doc.mjs +15 -0
  505. package/src/NumberInput/NumberInput.test.tsx +48 -3
  506. package/src/NumberInput/NumberInput.tsx +32 -15
  507. package/src/Outline/Outline.doc.mjs +2 -0
  508. package/src/Outline/parseOutlineFromMarkdown.test.ts +80 -0
  509. package/src/OverflowList/OverflowList.test.tsx +416 -0
  510. package/src/Overlay/Overlay.doc.mjs +6 -0
  511. package/src/Overlay/Overlay.test.tsx +356 -0
  512. package/src/Overlay/useOverlay.tsx +0 -3
  513. package/src/Pagination/Pagination.test.tsx +162 -0
  514. package/src/Pagination/Pagination.tsx +80 -26
  515. package/src/Popover/Popover.doc.mjs +6 -6
  516. package/src/Popover/Popover.test.tsx +65 -0
  517. package/src/Popover/usePopover.doc.mjs +1 -1
  518. package/src/PowerSearch/PowerSearch.doc.mjs +2 -2
  519. package/src/PowerSearch/PowerSearch.test.tsx +109 -1
  520. package/src/PowerSearch/PowerSearch.tsx +37 -16
  521. package/src/ProgressBar/ProgressBar.doc.mjs +2 -0
  522. package/src/ProgressBar/ProgressBar.test.tsx +30 -0
  523. package/src/ProgressBar/ProgressBar.tsx +12 -5
  524. package/src/RadioList/RadioList.test.tsx +19 -0
  525. package/src/RadioList/RadioListItem.tsx +9 -4
  526. package/src/Resizable/ResizeHandle.test.tsx +218 -0
  527. package/src/Resizable/ResizeHandle.tsx +22 -4
  528. package/src/SegmentedControl/SegmentedControl.doc.mjs +1 -1
  529. package/src/SegmentedControl/SegmentedControl.test.tsx +192 -0
  530. package/src/SegmentedControl/SegmentedControl.tsx +27 -5
  531. package/src/SegmentedControl/SegmentedControlItem.tsx +9 -4
  532. package/src/SelectableCard/SelectableCard.doc.mjs +1 -1
  533. package/src/Selector/Selector.test.tsx +27 -1
  534. package/src/SideNav/SideNav.doc.mjs +7 -1
  535. package/src/SideNav/SideNav.test.tsx +66 -0
  536. package/src/SideNav/SideNav.tsx +6 -2
  537. package/src/SideNav/SideNavCollapseButton.tsx +4 -3
  538. package/src/SideNav/SideNavSection.tsx +6 -4
  539. package/src/SizeContext/SizeContext.test.tsx +226 -0
  540. package/src/Switch/Switch.doc.mjs +7 -7
  541. package/src/Switch/Switch.test.tsx +102 -3
  542. package/src/Switch/Switch.tsx +20 -7
  543. package/src/TabList/TabList.test.tsx +185 -1
  544. package/src/TabList/TabMenu.tsx +45 -9
  545. package/src/Table/BaseTable.tsx +13 -2
  546. package/src/Table/Table.doc.mjs +6 -1
  547. package/src/Table/Table.test.tsx +87 -0
  548. package/src/Table/TableBody.tsx +15 -2
  549. package/src/Table/TableFooter.tsx +15 -2
  550. package/src/Table/TableHeader.tsx +15 -2
  551. package/src/Table/index.ts +5 -0
  552. package/src/Table/plugins/columnResize/useTableColumnResize.test.tsx +13 -0
  553. package/src/Table/plugins/columnResize/useTableColumnResize.tsx +3 -1
  554. package/src/Table/plugins/groupedRows/index.ts +7 -0
  555. package/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx +231 -0
  556. package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx +349 -0
  557. package/src/Table/plugins/pagination/paginateData.ts +5 -1
  558. package/src/Table/plugins/pagination/useTablePagination.test.tsx +13 -0
  559. package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx +1 -1
  560. package/src/Table/plugins/selection/useTableSelectionState.test.tsx +23 -0
  561. package/src/Table/plugins/selection/useTableSelectionState.tsx +11 -6
  562. package/src/Table/plugins/sortable/useTableSortableState.test.tsx +35 -1
  563. package/src/Table/plugins/sortable/useTableSortableState.tsx +8 -4
  564. package/src/Table/useTableGroupedRows.doc.mjs +71 -0
  565. package/src/TextArea/TextArea.test.tsx +3 -3
  566. package/src/TextInput/TextInput.test.tsx +3 -3
  567. package/src/Thumbnail/Thumbnail.test.tsx +36 -2
  568. package/src/Thumbnail/Thumbnail.tsx +4 -2
  569. package/src/TimeInput/TimeInput.test.tsx +37 -0
  570. package/src/TimeInput/TimeInput.tsx +11 -1
  571. package/src/Timestamp/Timestamp.doc.mjs +1 -1
  572. package/src/Timestamp/Timestamp.test.tsx +52 -0
  573. package/src/Timestamp/Timestamp.tsx +30 -16
  574. package/src/Toast/Toast.tsx +11 -3
  575. package/src/Toast/ToastViewport.test.tsx +64 -0
  576. package/src/Toast/ToastViewport.tsx +12 -0
  577. package/src/Toast/useToast.test.tsx +258 -0
  578. package/src/Toast/useToast.tsx +41 -0
  579. package/src/ToggleButton/ToggleButton.doc.mjs +1 -0
  580. package/src/Tokenizer/Tokenizer.doc.mjs +2 -2
  581. package/src/Tokenizer/Tokenizer.test.tsx +54 -0
  582. package/src/Tokenizer/Tokenizer.tsx +5 -4
  583. package/src/Tooltip/Tooltip.doc.mjs +6 -6
  584. package/src/Tooltip/useTooltip.doc.mjs +5 -5
  585. package/src/Tooltip/useTooltip.tsx +12 -2
  586. package/src/TopNav/TopNav.doc.mjs +1 -1
  587. package/src/TopNav/TopNav.test.tsx +23 -7
  588. package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx +9 -2
  589. package/src/TreeList/TreeList.doc.mjs +2 -2
  590. package/src/Typeahead/BaseTypeahead.doc.mjs +19 -0
  591. package/src/Typeahead/BaseTypeahead.tsx +5 -2
  592. package/src/Typeahead/Typeahead.doc.mjs +1 -1
  593. package/src/Typeahead/Typeahead.test.tsx +45 -1
  594. package/src/VisuallyHidden/VisuallyHidden.tsx +0 -3
  595. package/src/__tests__/TestIcon.tsx +26 -0
  596. package/src/__tests__/fastRoleQueries.ts +66 -0
  597. package/src/docPropReferences.test.ts +178 -0
  598. package/src/docs-types.ts +9 -1
  599. package/src/hooks/focusableSelector.ts +1 -1
  600. package/src/hooks/index.ts +3 -0
  601. package/src/hooks/useFocusTrap.doc.mjs +4 -2
  602. package/src/hooks/useFocusTrap.test.tsx +149 -1
  603. package/src/hooks/useFocusTrap.ts +50 -1
  604. package/src/hooks/useHotkeys.doc.mjs +52 -0
  605. package/src/hooks/useHotkeys.test.ts +245 -0
  606. package/src/hooks/useHotkeys.ts +203 -0
  607. package/src/hooks/useInteractiveRole.ts +12 -4
  608. package/src/hooks/useStreamingText.test.ts +54 -19
  609. package/src/hooks/useStreamingText.ts +16 -5
  610. package/src/hooks/useTreeFocus.test.tsx +1 -3
  611. package/src/reset.css +29 -0
  612. package/src/theme/SyntaxTheme.doc.mjs +4 -4
  613. package/src/theme/defineTheme.ts +4 -13
  614. package/src/theme/derivedVarRegistry.test.ts +2 -2
  615. package/src/theme/expandColorScale.test.ts +29 -0
  616. package/src/theme/expandColorScale.ts +11 -6
  617. package/src/theme/hct.ts +9 -17
  618. package/src/theme/themingTargets.test.ts +353 -0
  619. package/src/theme/tokens.test.ts +182 -9
  620. package/src/theme/tokens.ts +239 -4
  621. package/src/theme/useTheme.test.tsx +126 -2
  622. package/src/theme/useTheme.ts +87 -6
  623. package/src/utils/color.test.ts +133 -0
  624. package/src/utils/color.ts +148 -0
  625. package/src/utils/composeEventHandlers.test.ts +71 -0
  626. package/src/utils/composeEventHandlers.ts +44 -0
  627. package/src/utils/index.ts +4 -0
  628. package/src/utils/mergeProps.test.ts +166 -0
  629. package/src/utils/sharedResizeObserver.test.ts +2 -2
  630. package/src/utils/timeParser.test.ts +13 -0
  631. package/src/utils/timeParser.ts +8 -5
  632. package/dist/Carousel/carousel.markers.stylex.d.ts +0 -7
  633. package/dist/Carousel/carousel.markers.stylex.d.ts.map +0 -1
  634. package/dist/Carousel/carousel.markers.stylex.js +0 -12
  635. package/src/Carousel/carousel.markers.stylex.ts +0 -10
package/src/hooks/useFocusTrap.ts CHANGED
@@ -5,7 +5,8 @@
5
5
  /**
6
6
  * @file useFocusTrap.ts
7
7
  * @input Uses React useCallback, useEffect, useRef
8
- * @output Exports useFocusTrap hook for trapping focus within a container
8
+ * @output Exports useFocusTrap hook for trapping focus within a container and
9
+ * restoring focus to the previously-focused element on deactivation
9
10
  * @position Core hook; used by dialogs, modals, date pickers
10
11
  *
11
12
  * Based on WAI-ARIA dialog pattern:
@@ -178,6 +179,9 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
178
179
  * - Listens to focus events on the document
179
180
  * - Redirects focus back into the container if it escapes
180
181
  * - Handles both Tab and Shift+Tab navigation
182
+ * - Restores focus to the element that was focused before activation when the
183
+ * trap deactivates or unmounts, unless focus was already moved elsewhere
184
+ * (so consumers that restore focus themselves are unaffected)
181
185
  *
182
186
  * @example
183
187
  * ```
@@ -217,6 +221,51 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
217
221
  }
218
222
  }, []);
219
223
 
224
+ /**
225
+ * Capture the element focused before the trap activated, and restore focus to
226
+ * it when the trap deactivates (or the component unmounts). Overlays are
227
+ * opened imperatively (e.g. `showPopover()`), so the browser's declarative
228
+ * popover focus restoration does not apply — without this, closing a Popover
229
+ * via Escape or light dismiss drops keyboard focus to `<body>`.
230
+ *
231
+ * The restore is guarded so it never steals focus a consumer moved on
232
+ * purpose: it only runs when focus would otherwise be lost — i.e. the active
233
+ * element is nothing, the document body/root, or still inside the (possibly
234
+ * now-unmounted) trap container. If focus already moved to some other element
235
+ * outside the trap (the user clicked elsewhere, or a consumer such as
236
+ * DropdownMenu already refocused its trigger), the restore is a no-op.
237
+ */
238
+ useEffect(() => {
239
+ if (!isActive) {
240
+ return;
241
+ }
242
+
243
+ const previouslyFocused = document.activeElement as HTMLElement | null;
244
+ // Snapshot the container now; by cleanup it may be detached or unmounted.
245
+ const container = containerRef.current;
246
+
247
+ return () => {
248
+ const active = document.activeElement;
249
+ const focusWasLost =
250
+ active == null ||
251
+ active === document.body ||
252
+ active === document.documentElement ||
253
+ (container != null && container.contains(active));
254
+
255
+ if (!focusWasLost) {
256
+ return;
257
+ }
258
+
259
+ if (
260
+ previouslyFocused != null &&
261
+ previouslyFocused.isConnected &&
262
+ typeof previouslyFocused.focus === 'function'
263
+ ) {
264
+ previouslyFocused.focus();
265
+ }
266
+ };
267
+ }, [isActive]);
268
+
220
269
  /**
221
270
  * Handle focus events - redirect focus back into container if it escapes.
222
271
  * Only redirects for keyboard navigation, not mouse clicks.
package/src/hooks/useHotkeys.doc.mjs ADDED
@@ -0,0 +1,52 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('../docs-types').HookDoc} */
4
+ export const docs = {
5
+ name: 'useHotkeys',
6
+ displayName: 'useHotkeys',
7
+ keywords: ['hotkey', 'shortcut', 'keyboard', 'keydown', 'command', 'palette', 'mod', 'cmd', 'ctrl', 'kbd'],
8
+ params: [
9
+ {
10
+ name: 'hotkeys',
11
+ type: 'Hotkey[]',
12
+ description:
13
+ 'Shortcut registrations. Each entry: `{ keys, onPress, allowInInputs?, isDisabled? }`. `keys` is a "+"-separated combo like "mod+k", "shift+/", "escape" — "mod" is ⌘ on macOS and Ctrl elsewhere. `onPress` receives the KeyboardEvent after preventDefault(). `allowInInputs` (default false) lets the hotkey fire while typing in inputs/textareas/selects/contenteditable. `isDisabled` temporarily disables the entry.',
14
+ required: true,
15
+ },
16
+ ],
17
+ returns: [],
18
+ usage: {
19
+ description:
20
+ 'Registers global keyboard shortcuts with a single window keydown listener per hook instance. Handlers live in a ref, so re-renders never re-subscribe. Skips events from typing targets (input, textarea, select, contenteditable) unless allowInInputs, skips defaultPrevented events, and calls preventDefault() on match. SSR-safe.',
21
+ bestPractices: [
22
+ { guidance: true, description: 'Use for app-level shortcuts like command palettes (mod+k), help overlays (shift+/), and navigation keys.' },
23
+ { guidance: true, description: 'Pair with the Kbd component to display the same combo you register — both resolve "mod" per platform identically.' },
24
+ { guidance: true, description: 'Use isDisabled to suspend shortcuts while a modal or wizard owns the keyboard, instead of unmounting the hook.' },
25
+ { guidance: false, description: 'Use for focus-scoped keyboard navigation inside a widget; use useListFocus or useGridFocus instead.' },
26
+ ],
27
+ },
28
+ relatedComponents: ['Kbd'],
29
+ relatedHooks: ['useListFocus', 'useGridFocus'],
30
+ importPath: '@astryxdesign/core/hooks',
31
+ category: 'interaction',
32
+ };
33
+
34
+ /** @type {import('../docs-types').HookTranslationDoc} */
35
+ export const docsDense = {
36
+ description:
37
+ 'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',
38
+ paramDescriptions: {
39
+ hotkeys:
40
+ 'array of { keys, onPress, allowInInputs?, isDisabled? }. keys = "+"-separated combo ("mod+k", "shift+/", "escape").',
41
+ },
42
+ usage: {
43
+ description:
44
+ 'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets unless allowInInputs, skips defaultPrevented, preventDefault() on match. SSR-safe.',
45
+ bestPractices: [
46
+ { guidance: true, description: 'Use for app-level shortcuts: command palettes (mod+k), help overlays (shift+/), navigation keys.' },
47
+ { guidance: true, description: 'Pair w/ Kbd component to display same combo registered — both resolve "mod" per platform identically.' },
48
+ { guidance: true, description: 'Use isDisabled to suspend shortcuts while modal/wizard owns keyboard, instead of unmounting hook.' },
49
+ { guidance: false, description: 'Use for focus-scoped keyboard nav inside widget; use useListFocus / useGridFocus instead.' },
50
+ ],
51
+ },
52
+ };
package/src/hooks/useHotkeys.test.ts ADDED
@@ -0,0 +1,245 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file useHotkeys.test.ts
5
+ * @input Uses vitest, @testing-library/react, useHotkeys hook
6
+ * @output Unit tests for useHotkeys hook
7
+ * @position Testing; validates useHotkeys.ts implementation
8
+ *
9
+ * SYNC: When useHotkeys.ts changes, update tests to match new behavior
10
+ */
11
+
12
+ import {describe, it, expect, vi, afterEach} from 'vitest';
13
+ import {renderHook} from '@testing-library/react';
14
+ import {useHotkeys, type Hotkey} from './useHotkeys';
15
+
16
+ function stubApplePlatform() {
17
+ // jsdom's navigator has no userAgentData; platform drives detection.
18
+ vi.stubGlobal('navigator', {platform: 'MacIntel'});
19
+ }
20
+
21
+ function stubOtherPlatform() {
22
+ vi.stubGlobal('navigator', {platform: 'Win32'});
23
+ }
24
+
25
+ function press(
26
+ key: string,
27
+ init: KeyboardEventInit & {target?: HTMLElement} = {},
28
+ ): KeyboardEvent {
29
+ const {target, ...eventInit} = init;
30
+ const event = new KeyboardEvent('keydown', {
31
+ key,
32
+ bubbles: true,
33
+ cancelable: true,
34
+ ...eventInit,
35
+ });
36
+ (target ?? window).dispatchEvent(event);
37
+ return event;
38
+ }
39
+
40
+ afterEach(() => {
41
+ vi.unstubAllGlobals();
42
+ vi.restoreAllMocks();
43
+ document.body.innerHTML = '';
44
+ });
45
+
46
+ describe('useHotkeys', () => {
47
+ it('fires on mod+k via metaKey on Apple platforms', () => {
48
+ stubApplePlatform();
49
+ const onPress = vi.fn();
50
+ renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
51
+
52
+ const event = press('k', {metaKey: true});
53
+ expect(onPress).toHaveBeenCalledTimes(1);
54
+ expect(onPress).toHaveBeenCalledWith(event);
55
+ expect(event.defaultPrevented).toBe(true);
56
+ });
57
+
58
+ it('maps mod to ctrlKey on non-Apple platforms', () => {
59
+ stubOtherPlatform();
60
+ const onPress = vi.fn();
61
+ renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
62
+
63
+ press('k', {metaKey: true});
64
+ expect(onPress).not.toHaveBeenCalled();
65
+
66
+ press('k', {ctrlKey: true});
67
+ expect(onPress).toHaveBeenCalledTimes(1);
68
+ });
69
+
70
+ it('does not fire a bare key when modifiers are held', () => {
71
+ stubApplePlatform();
72
+ const onPress = vi.fn();
73
+ renderHook(() => useHotkeys([{keys: 'k', onPress}]));
74
+
75
+ press('k', {metaKey: true});
76
+ press('k', {ctrlKey: true});
77
+ press('k', {altKey: true});
78
+ expect(onPress).not.toHaveBeenCalled();
79
+
80
+ press('k');
81
+ expect(onPress).toHaveBeenCalledTimes(1);
82
+ });
83
+
84
+ it('matches named keys: escape, enter, space, arrows', () => {
85
+ stubApplePlatform();
86
+ const onEscape = vi.fn();
87
+ const onEnter = vi.fn();
88
+ const onSpace = vi.fn();
89
+ const onDown = vi.fn();
90
+ renderHook(() =>
91
+ useHotkeys([
92
+ {keys: 'escape', onPress: onEscape},
93
+ {keys: 'enter', onPress: onEnter},
94
+ {keys: 'space', onPress: onSpace},
95
+ {keys: 'down', onPress: onDown},
96
+ ]),
97
+ );
98
+
99
+ press('Escape');
100
+ press('Enter');
101
+ press(' ');
102
+ press('ArrowDown');
103
+ expect(onEscape).toHaveBeenCalledTimes(1);
104
+ expect(onEnter).toHaveBeenCalledTimes(1);
105
+ expect(onSpace).toHaveBeenCalledTimes(1);
106
+ expect(onDown).toHaveBeenCalledTimes(1);
107
+ });
108
+
109
+ it('requires shift when specified and ignores shift otherwise', () => {
110
+ stubApplePlatform();
111
+ const onSlash = vi.fn();
112
+ const onLetter = vi.fn();
113
+ renderHook(() =>
114
+ useHotkeys([
115
+ {keys: 'shift+/', onPress: onSlash},
116
+ {keys: 'c', onPress: onLetter},
117
+ ]),
118
+ );
119
+
120
+ press('/');
121
+ expect(onSlash).not.toHaveBeenCalled();
122
+ press('/', {shiftKey: true});
123
+ expect(onSlash).toHaveBeenCalledTimes(1);
124
+
125
+ // Shift not specified → matches regardless of shift state.
126
+ press('C', {shiftKey: true});
127
+ press('c');
128
+ expect(onLetter).toHaveBeenCalledTimes(2);
129
+ });
130
+
131
+ it('skips typing targets by default', () => {
132
+ stubApplePlatform();
133
+ const onPress = vi.fn();
134
+ renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
135
+
136
+ const input = document.createElement('input');
137
+ document.body.appendChild(input);
138
+ press('k', {metaKey: true, target: input});
139
+ expect(onPress).not.toHaveBeenCalled();
140
+
141
+ const textarea = document.createElement('textarea');
142
+ document.body.appendChild(textarea);
143
+ press('k', {metaKey: true, target: textarea});
144
+ expect(onPress).not.toHaveBeenCalled();
145
+ });
146
+
147
+ it('fires in typing targets when allowInInputs is true', () => {
148
+ stubApplePlatform();
149
+ const onPress = vi.fn();
150
+ renderHook(() =>
151
+ useHotkeys([{keys: 'escape', onPress, allowInInputs: true}]),
152
+ );
153
+
154
+ const input = document.createElement('input');
155
+ document.body.appendChild(input);
156
+ press('Escape', {target: input});
157
+ expect(onPress).toHaveBeenCalledTimes(1);
158
+ });
159
+
160
+ it('respects isDisabled', () => {
161
+ stubApplePlatform();
162
+ const onPress = vi.fn();
163
+ const {rerender} = renderHook(
164
+ ({isDisabled}: {isDisabled: boolean}) =>
165
+ useHotkeys([{keys: 'mod+k', onPress, isDisabled}]),
166
+ {initialProps: {isDisabled: true}},
167
+ );
168
+
169
+ press('k', {metaKey: true});
170
+ expect(onPress).not.toHaveBeenCalled();
171
+
172
+ rerender({isDisabled: false});
173
+ press('k', {metaKey: true});
174
+ expect(onPress).toHaveBeenCalledTimes(1);
175
+ });
176
+
177
+ it('skips events that are already defaultPrevented', () => {
178
+ stubApplePlatform();
179
+ const onPress = vi.fn();
180
+ renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
181
+
182
+ const event = new KeyboardEvent('keydown', {
183
+ key: 'k',
184
+ metaKey: true,
185
+ bubbles: true,
186
+ cancelable: true,
187
+ });
188
+ event.preventDefault();
189
+ window.dispatchEvent(event);
190
+ expect(onPress).not.toHaveBeenCalled();
191
+ });
192
+
193
+ it('unsubscribes on unmount', () => {
194
+ stubApplePlatform();
195
+ const onPress = vi.fn();
196
+ const removeSpy = vi.spyOn(window, 'removeEventListener');
197
+ const {unmount} = renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
198
+
199
+ unmount();
200
+ expect(removeSpy).toHaveBeenCalledWith('keydown', expect.any(Function));
201
+
202
+ press('k', {metaKey: true});
203
+ expect(onPress).not.toHaveBeenCalled();
204
+ });
205
+
206
+ it('does not re-subscribe on re-render, but uses latest handlers', () => {
207
+ stubApplePlatform();
208
+ const addSpy = vi.spyOn(window, 'addEventListener');
209
+ const first = vi.fn();
210
+ const second = vi.fn();
211
+
212
+ const {rerender} = renderHook(
213
+ ({hotkeys}: {hotkeys: Hotkey[]}) => useHotkeys(hotkeys),
214
+ {initialProps: {hotkeys: [{keys: 'mod+k', onPress: first}]}},
215
+ );
216
+
217
+ const keydownSubscriptions = () =>
218
+ addSpy.mock.calls.filter(([type]) => type === 'keydown').length;
219
+ const initialCount = keydownSubscriptions();
220
+
221
+ rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
222
+ rerender({hotkeys: [{keys: 'mod+k', onPress: second}]});
223
+ expect(keydownSubscriptions()).toBe(initialCount);
224
+
225
+ press('k', {metaKey: true});
226
+ expect(first).not.toHaveBeenCalled();
227
+ expect(second).toHaveBeenCalledTimes(1);
228
+ });
229
+
230
+ it('only fires the first matching hotkey per event', () => {
231
+ stubApplePlatform();
232
+ const first = vi.fn();
233
+ const second = vi.fn();
234
+ renderHook(() =>
235
+ useHotkeys([
236
+ {keys: 'mod+k', onPress: first},
237
+ {keys: 'mod+k', onPress: second},
238
+ ]),
239
+ );
240
+
241
+ press('k', {metaKey: true});
242
+ expect(first).toHaveBeenCalledTimes(1);
243
+ expect(second).not.toHaveBeenCalled();
244
+ });
245
+ });
package/src/hooks/useHotkeys.ts ADDED
@@ -0,0 +1,203 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @file useHotkeys.ts
7
+ * @input Uses React useEffect, useRef
8
+ * @output Exports useHotkeys hook and Hotkey interface for global keyboard shortcuts
9
+ * @position Core hook; used by consumers for app-level keyboard shortcuts
10
+ *
11
+ * Registers a single window keydown listener per hook instance. Handlers
12
+ * are kept in a ref so re-renders never re-subscribe (subscribe once on
13
+ * mount, unsubscribe on unmount). SSR-safe — window is only touched
14
+ * inside the effect.
15
+ *
16
+ * Skips events that are already handled (defaultPrevented) and events
17
+ * targeting typing surfaces (input, textarea, select, contenteditable)
18
+ * unless a hotkey opts in via `allowInInputs`.
19
+ *
20
+ * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
21
+ * ctrlKey elsewhere — mirrors the detection used by Kbd.
22
+ *
23
+ * SYNC: When modified, update:
24
+ * - /packages/core/src/hooks/index.ts
25
+ * - /packages/core/src/hooks/useHotkeys.doc.mjs
26
+ */
27
+
28
+ import {useEffect, useRef} from 'react';
29
+
30
+ /**
31
+ * A single keyboard shortcut registration.
32
+ */
33
+ export interface Hotkey {
34
+ /**
35
+ * Key combo, e.g. 'mod+k', 'shift+/', 'c', 'escape'.
36
+ * 'mod' = ⌘ on macOS, Ctrl elsewhere.
37
+ *
38
+ * Format: '+'-separated modifiers (mod, ctrl, meta, shift, alt) followed
39
+ * by a final key compared case-insensitively against event.key.
40
+ * Named keys: 'escape', 'enter', 'space', 'up', 'down', 'left', 'right'
41
+ * (arrow names map to ArrowUp/ArrowDown/ArrowLeft/ArrowRight).
42
+ * Use 'plus' for a literal '+' key.
43
+ *
44
+ * Shift semantics: when 'shift' is not specified, shift state is ignored,
45
+ * so single letters match regardless of shift. When 'shift' is specified,
46
+ * shiftKey must be pressed and the final key is still compared against
47
+ * event.key — for punctuation that shift transforms (e.g. shift+/ produces
48
+ * '?' on US layouts), prefer registering the produced character instead.
49
+ */
50
+ keys: string;
51
+ /** Called when the combo matches. The event has preventDefault() applied. */
52
+ onPress: (event: KeyboardEvent) => void;
53
+ /**
54
+ * Fire even when focus is in an input/textarea/select/contenteditable.
55
+ * @default false
56
+ */
57
+ allowInInputs?: boolean;
58
+ /** Temporarily disable this hotkey without unregistering it. */
59
+ isDisabled?: boolean;
60
+ }
61
+
62
+ /** Aliases for the final key of a combo, normalized to event.key values. */
63
+ const KEY_ALIASES: Record<string, string> = {
64
+ esc: 'escape',
65
+ space: ' ',
66
+ up: 'arrowup',
67
+ down: 'arrowdown',
68
+ left: 'arrowleft',
69
+ right: 'arrowright',
70
+ return: 'enter',
71
+ plus: '+',
72
+ };
73
+
74
+ /**
75
+ * Detects whether the current platform is macOS/iOS.
76
+ * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
77
+ * falls back to navigator.platform (deprecated but universally supported).
78
+ * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
79
+ */
80
+ function isApplePlatform(): boolean {
81
+ if (typeof navigator === 'undefined') {
82
+ return false;
83
+ }
84
+ const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
85
+ if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
86
+ return /mac/i.test((uaData as {platform: string}).platform ?? '');
87
+ }
88
+ return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
89
+ }
90
+
91
+ /**
92
+ * Whether the event target is a typing surface where global shortcuts
93
+ * should stay silent by default.
94
+ */
95
+ function isTypingTarget(target: EventTarget | null): boolean {
96
+ if (!(target instanceof HTMLElement)) {
97
+ return false;
98
+ }
99
+ if (target.isContentEditable) {
100
+ return true;
101
+ }
102
+ const tag = target.tagName;
103
+ return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
104
+ }
105
+
106
+ /**
107
+ * Whether a keydown event matches a '+'-separated combo string.
108
+ */
109
+ function matchesCombo(
110
+ keys: string,
111
+ event: KeyboardEvent,
112
+ isApple: boolean,
113
+ ): boolean {
114
+ const parts = keys
115
+ .toLowerCase()
116
+ .split('+')
117
+ .map(part => part.trim())
118
+ .filter(Boolean);
119
+ if (parts.length === 0) {
120
+ return false;
121
+ }
122
+
123
+ const key = parts[parts.length - 1];
124
+ const mods = new Set(parts.slice(0, -1));
125
+
126
+ const wantsMod = mods.has('mod');
127
+ const wantsCtrl = mods.has('ctrl') || (wantsMod && !isApple);
128
+ const wantsMeta = mods.has('meta') || (wantsMod && isApple);
129
+ const wantsAlt = mods.has('alt');
130
+ const wantsShift = mods.has('shift');
131
+
132
+ // Non-shift modifiers must match exactly so 'k' doesn't fire on 'mod+k'.
133
+ if (event.ctrlKey !== wantsCtrl) {
134
+ return false;
135
+ }
136
+ if (event.metaKey !== wantsMeta) {
137
+ return false;
138
+ }
139
+ if (event.altKey !== wantsAlt) {
140
+ return false;
141
+ }
142
+ // Shift is only enforced when specified — see Hotkey.keys docs.
143
+ if (wantsShift && !event.shiftKey) {
144
+ return false;
145
+ }
146
+
147
+ const expected = KEY_ALIASES[key] ?? key;
148
+ return event.key.toLowerCase() === expected;
149
+ }
150
+
151
+ /**
152
+ * Registers global keyboard shortcuts on window.
153
+ *
154
+ * A single keydown listener is attached per hook instance; the hotkey
155
+ * definitions live in a ref, so re-renders update behavior without
156
+ * re-subscribing. First matching hotkey wins per event.
157
+ *
158
+ * @param hotkeys - Shortcut registrations to listen for.
159
+ *
160
+ * @example
161
+ * ```
162
+ * useHotkeys([
163
+ * { keys: 'mod+k', onPress: () => openCommandPalette() },
164
+ * { keys: 'escape', onPress: () => closePanel(), allowInInputs: true },
165
+ * { keys: 'c', onPress: () => compose(), isDisabled: isModalOpen },
166
+ * ]);
167
+ * ```
168
+ */
169
+ export function useHotkeys(hotkeys: Hotkey[]): void {
170
+ const hotkeysRef = useRef(hotkeys);
171
+
172
+ // Keep the latest definitions available to the stable listener.
173
+ useEffect(() => {
174
+ hotkeysRef.current = hotkeys;
175
+ });
176
+
177
+ useEffect(() => {
178
+ const isApple = isApplePlatform();
179
+
180
+ const handleKeyDown = (event: KeyboardEvent) => {
181
+ if (event.defaultPrevented) {
182
+ return;
183
+ }
184
+ const isTyping = isTypingTarget(event.target);
185
+ for (const hotkey of hotkeysRef.current) {
186
+ if (hotkey.isDisabled) {
187
+ continue;
188
+ }
189
+ if (isTyping && !hotkey.allowInInputs) {
190
+ continue;
191
+ }
192
+ if (matchesCombo(hotkey.keys, event, isApple)) {
193
+ event.preventDefault();
194
+ hotkey.onPress(event);
195
+ return;
196
+ }
197
+ }
198
+ };
199
+
200
+ window.addEventListener('keydown', handleKeyDown);
201
+ return () => window.removeEventListener('keydown', handleKeyDown);
202
+ }, []);
203
+ }
package/src/hooks/useInteractiveRole.ts CHANGED
@@ -11,11 +11,14 @@
11
11
  * Centralizes the "what element should I render as?" decision for
12
12
  * polymorphic components. The priority order:
13
13
  *
14
- * 1. href → 'link' (navigation always wins)
14
+ * 1. href → 'link' (navigation always wins, unless disabled)
15
15
  * 2. onClick → 'button' (explicit interactivity)
16
16
  * 3. interactive trigger context → 'button' (implicit via parent)
17
17
  * 4. else → 'inert' (non-interactive)
18
18
  *
19
+ * A disabled `href` is excluded at step 1 and therefore resolves via the
20
+ * remaining steps — 'inert' when no onClick or context applies.
21
+ *
19
22
  * This hook is the single place to add new context-based triggers
20
23
  * (e.g., Popover, DropdownMenu, Disclosure). Components that consume
21
24
  * this hook never need updating when new trigger contexts are added.
@@ -49,8 +52,12 @@ export interface UseInteractiveRoleOptions {
49
52
  onClick?: ((...args: never[]) => unknown) | null;
50
53
 
51
54
  /**
52
- * Whether the component is disabled. When true and href is provided,
53
- * falls back to button (disabled links are an a11y anti-pattern).
55
+ * Whether the component is disabled. When true, an `href` is ignored for
56
+ * role resolution (a disabled link is an a11y anti-pattern), so the role is
57
+ * decided by the remaining inputs: `onClick` → `'button'`, an interactive
58
+ * context → its role, otherwise `'inert'`. In particular a disabled `href`
59
+ * with no `onClick` and no context override resolves to `'inert'`, not a
60
+ * link or a button.
54
61
  * @default false
55
62
  */
56
63
  isDisabled?: boolean;
@@ -83,7 +90,8 @@ export function useInteractiveRole({
83
90
  }: UseInteractiveRoleOptions): InteractiveRole {
84
91
  const contextRole = useInteractiveRoleContext();
85
92
 
86
- // 1. href → link (unless disabled — disabled links fall through to button)
93
+ // 1. href → link (unless disabled — a disabled href is skipped here and
94
+ // resolved by the checks below, landing on 'inert' if nothing else applies)
87
95
  if (href != null && !isDisabled) {
88
96
  return 'link';
89
97
  }