@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

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 (270) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/BottomSheet/BottomSheet.d.ts +3 -1
  3. package/dist/BottomSheet/BottomSheet.d.ts.map +1 -1
  4. package/dist/BottomSheet/BottomSheet.js +4 -3
  5. package/dist/BottomSheet/BottomSheetEdgeTint.d.ts +2 -2
  6. package/dist/BottomSheet/BottomSheetEdgeTint.d.ts.map +1 -1
  7. package/dist/BottomSheet/BottomSheetEdgeTint.js +7 -10
  8. package/dist/BottomSheet/BottomSheetSwitcher.d.ts.map +1 -1
  9. package/dist/BottomSheet/BottomSheetSwitcher.js +1 -1
  10. package/dist/Button/Button.d.ts +2 -1
  11. package/dist/Button/Button.d.ts.map +1 -1
  12. package/dist/Button/Button.js +11 -4
  13. package/dist/Carousel/Carousel.d.ts.map +1 -1
  14. package/dist/Carousel/Carousel.js +2 -2
  15. package/dist/Chat/ChatToolCalls.d.ts.map +1 -1
  16. package/dist/Chat/ChatToolCalls.js +34 -17
  17. package/dist/ContextMenu/ContextMenu.d.ts +14 -3
  18. package/dist/ContextMenu/ContextMenu.d.ts.map +1 -1
  19. package/dist/ContextMenu/ContextMenu.js +149 -26
  20. package/dist/ContextMenu/index.d.ts +1 -0
  21. package/dist/ContextMenu/index.d.ts.map +1 -1
  22. package/dist/DropdownMenu/DropdownMenu.d.ts +24 -5
  23. package/dist/DropdownMenu/DropdownMenu.d.ts.map +1 -1
  24. package/dist/DropdownMenu/DropdownMenu.js +340 -26
  25. package/dist/DropdownMenu/DropdownMenuContext.d.ts +1 -1
  26. package/dist/DropdownMenu/DropdownMenuContext.d.ts.map +1 -1
  27. package/dist/DropdownMenu/DropdownMenuItem.d.ts.map +1 -1
  28. package/dist/DropdownMenu/DropdownMenuItem.js +1 -1
  29. package/dist/DropdownMenu/DropdownMenuSubMenu.d.ts +6 -2
  30. package/dist/DropdownMenu/DropdownMenuSubMenu.d.ts.map +1 -1
  31. package/dist/DropdownMenu/DropdownMenuSubMenu.js +43 -14
  32. package/dist/DropdownMenu/MenuBottomSheet.d.ts +20 -0
  33. package/dist/DropdownMenu/MenuBottomSheet.d.ts.map +1 -0
  34. package/dist/DropdownMenu/MenuBottomSheet.js +36 -0
  35. package/dist/DropdownMenu/MenuBottomSheetActionList.d.ts +10 -0
  36. package/dist/DropdownMenu/MenuBottomSheetActionList.d.ts.map +1 -0
  37. package/dist/DropdownMenu/MenuBottomSheetActionList.js +111 -0
  38. package/dist/DropdownMenu/index.d.ts +2 -1
  39. package/dist/DropdownMenu/index.d.ts.map +1 -1
  40. package/dist/DropdownMenu/menuWidth.d.ts +14 -0
  41. package/dist/DropdownMenu/menuWidth.d.ts.map +1 -0
  42. package/dist/DropdownMenu/menuWidth.js +35 -0
  43. package/dist/DropdownMenu/useMenuOverflow.d.ts +10 -0
  44. package/dist/DropdownMenu/useMenuOverflow.d.ts.map +1 -0
  45. package/dist/DropdownMenu/useMenuOverflow.js +60 -0
  46. package/dist/MoreMenu/MoreMenu.d.ts +8 -2
  47. package/dist/MoreMenu/MoreMenu.d.ts.map +1 -1
  48. package/dist/MoreMenu/MoreMenu.js +2 -0
  49. package/dist/MultiSelector/MultiSelector.d.ts +11 -1
  50. package/dist/MultiSelector/MultiSelector.d.ts.map +1 -1
  51. package/dist/MultiSelector/MultiSelector.js +97 -68
  52. package/dist/MultiSelector/index.d.ts +1 -1
  53. package/dist/MultiSelector/index.d.ts.map +1 -1
  54. package/dist/Popover/Popover.d.ts +10 -6
  55. package/dist/Popover/Popover.d.ts.map +1 -1
  56. package/dist/Popover/Popover.js +141 -16
  57. package/dist/Popover/usePopover.d.ts +4 -0
  58. package/dist/Popover/usePopover.d.ts.map +1 -1
  59. package/dist/Popover/usePopover.js +52 -5
  60. package/dist/Selector/Selector.d.ts +10 -0
  61. package/dist/Selector/Selector.d.ts.map +1 -1
  62. package/dist/Selector/Selector.js +106 -80
  63. package/dist/Selector/SelectorBottomSheet.d.ts +21 -0
  64. package/dist/Selector/SelectorBottomSheet.d.ts.map +1 -0
  65. package/dist/Selector/SelectorBottomSheet.js +83 -0
  66. package/dist/Selector/index.d.ts +1 -1
  67. package/dist/Selector/index.d.ts.map +1 -1
  68. package/dist/Selector/selectorPresentation.stylex.d.ts +16 -0
  69. package/dist/Selector/selectorPresentation.stylex.d.ts.map +1 -0
  70. package/dist/Selector/selectorPresentation.stylex.js +21 -0
  71. package/dist/Selector/useSelectorPresentation.d.ts +32 -0
  72. package/dist/Selector/useSelectorPresentation.d.ts.map +1 -0
  73. package/dist/Selector/useSelectorPresentation.js +90 -0
  74. package/dist/Toast/useToastGesture.d.ts.map +1 -1
  75. package/dist/Toast/useToastGesture.js +46 -9
  76. package/dist/astryx.css +19 -1
  77. package/dist/hooks/useAdaptivePresentation.d.ts +5 -0
  78. package/dist/hooks/useAdaptivePresentation.d.ts.map +1 -0
  79. package/dist/hooks/useAdaptivePresentation.js +19 -0
  80. package/dist/hooks/useFocusReturnVisibility.d.ts +7 -0
  81. package/dist/hooks/useFocusReturnVisibility.d.ts.map +1 -0
  82. package/dist/hooks/useFocusReturnVisibility.js +35 -0
  83. package/dist/hooks/useFocusTrap.d.ts.map +1 -1
  84. package/dist/hooks/useFocusTrap.js +12 -0
  85. package/dist/i18n/InternationalizationContext.d.ts +2 -0
  86. package/dist/i18n/InternationalizationContext.d.ts.map +1 -1
  87. package/dist/i18n/InternationalizationContext.js +3 -1
  88. package/dist/i18n/InternationalizationProvider.d.ts.map +1 -1
  89. package/dist/i18n/InternationalizationProvider.js +3 -1
  90. package/dist/i18n/resolve.d.ts +1 -1
  91. package/dist/i18n/resolve.d.ts.map +1 -1
  92. package/dist/i18n/resolve.js +37 -38
  93. package/dist/i18n/useTranslator.d.ts.map +1 -1
  94. package/dist/i18n/useTranslator.js +2 -3
  95. package/locales/af-ZA.json +0 -4
  96. package/locales/ar-SA.json +0 -4
  97. package/locales/ca-ES.json +0 -4
  98. package/locales/cs-CZ.json +0 -4
  99. package/locales/da-DK.json +0 -4
  100. package/locales/de-DE.json +0 -4
  101. package/locales/el-GR.json +0 -4
  102. package/locales/en.json +20 -0
  103. package/locales/es-ES.json +0 -4
  104. package/locales/fi-FI.json +0 -4
  105. package/locales/fr-FR.json +0 -4
  106. package/locales/he-IL.json +0 -4
  107. package/locales/hu-HU.json +0 -4
  108. package/locales/it-IT.json +0 -4
  109. package/locales/ja-JP.json +0 -4
  110. package/locales/ko-KR.json +0 -4
  111. package/locales/nl-NL.json +0 -4
  112. package/locales/no-NO.json +0 -4
  113. package/locales/pl-PL.json +0 -4
  114. package/locales/pseudo.json +15 -0
  115. package/locales/pt-BR.json +0 -4
  116. package/locales/pt-PT.json +0 -4
  117. package/locales/ro-RO.json +0 -4
  118. package/locales/ru-RU.json +0 -4
  119. package/locales/sr-SP.json +0 -4
  120. package/locales/sv-SE.json +0 -4
  121. package/locales/tr-TR.json +0 -4
  122. package/locales/uk-UA.json +0 -4
  123. package/locales/vi-VN.json +0 -4
  124. package/locales/zh-CN.json +0 -4
  125. package/locales/zh-TW.json +0 -4
  126. package/package.json +3 -3
  127. package/src/BottomSheet/BottomSheet.doc.mjs +37 -0
  128. package/src/BottomSheet/BottomSheet.spec.md +177 -0
  129. package/src/BottomSheet/BottomSheet.test.tsx +29 -0
  130. package/src/BottomSheet/BottomSheet.tsx +7 -4
  131. package/src/BottomSheet/BottomSheetEdgeTint.test.tsx +4 -6
  132. package/src/BottomSheet/BottomSheetEdgeTint.tsx +7 -10
  133. package/src/BottomSheet/BottomSheetSwitcher.tsx +1 -2
  134. package/src/Button/Button.doc.mjs +56 -0
  135. package/src/Button/Button.test.tsx +10 -0
  136. package/src/Button/Button.tsx +13 -5
  137. package/src/ButtonGroup/ButtonGroup.doc.mjs +47 -0
  138. package/src/Calendar/Calendar.doc.mjs +1 -1
  139. package/src/Carousel/Carousel.test.tsx +83 -0
  140. package/src/Carousel/Carousel.tsx +8 -2
  141. package/src/Chat/ChatToolCalls.test.tsx +44 -0
  142. package/src/Chat/ChatToolCalls.tsx +36 -15
  143. package/src/CheckboxInput/CheckboxInput.doc.mjs +1 -1
  144. package/src/CheckboxList/CheckboxList.doc.mjs +173 -32
  145. package/src/CheckboxList/CheckboxList.spec.md +214 -0
  146. package/src/CommandPalette/CommandPalette.doc.mjs +72 -0
  147. package/src/CommandPalette/CommandPalette.spec.md +223 -0
  148. package/src/ComplexSelector/ComplexSelector.doc.mjs +44 -2
  149. package/src/ComplexSelector/ComplexSelector.spec.md +189 -0
  150. package/src/ContextMenu/ContextMenu.doc.mjs +13 -1
  151. package/src/ContextMenu/ContextMenu.test.tsx +131 -1
  152. package/src/ContextMenu/ContextMenu.tsx +199 -32
  153. package/src/ContextMenu/index.ts +1 -0
  154. package/src/DateInput/DateInput.doc.mjs +1 -1
  155. package/src/DateRangeInput/DateRangeInput.doc.mjs +1 -1
  156. package/src/DateTimeInput/DateTimeInput.doc.mjs +1 -1
  157. package/src/Divider/Divider.doc.mjs +24 -0
  158. package/src/Divider/Divider.spec.md +150 -0
  159. package/src/DropdownMenu/DropdownMenu.doc.mjs +201 -40
  160. package/src/DropdownMenu/DropdownMenu.test.tsx +518 -7
  161. package/src/DropdownMenu/DropdownMenu.tsx +459 -28
  162. package/src/DropdownMenu/DropdownMenuContext.tsx +1 -1
  163. package/src/DropdownMenu/DropdownMenuItem.tsx +2 -0
  164. package/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs +4 -2
  165. package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx +124 -0
  166. package/src/DropdownMenu/DropdownMenuSubMenu.tsx +72 -17
  167. package/src/DropdownMenu/MenuBottomSheet.tsx +46 -0
  168. package/src/DropdownMenu/MenuBottomSheetActionList.tsx +141 -0
  169. package/src/DropdownMenu/index.ts +2 -0
  170. package/src/DropdownMenu/menuWidth.ts +51 -0
  171. package/src/DropdownMenu/useMenuOverflow.ts +77 -0
  172. package/src/Field/Field.doc.mjs +1 -1
  173. package/src/FieldStatus/FieldStatus.doc.mjs +22 -1
  174. package/src/FieldStatus/FieldStatus.spec.md +212 -0
  175. package/src/FileInput/FileInput.doc.mjs +1 -1
  176. package/src/Grid/Grid.doc.mjs +19 -0
  177. package/src/Grid/Grid.spec.md +161 -0
  178. package/src/Icon/Icon.doc.mjs +196 -48
  179. package/src/Icon/Icon.spec.md +191 -0
  180. package/src/IconButton/IconButton.doc.mjs +38 -0
  181. package/src/Indicator/Indicator.doc.mjs +1 -1
  182. package/src/InputGroup/InputGroup.doc.mjs +1 -1
  183. package/src/Kbd/Kbd.doc.mjs +18 -0
  184. package/src/Kbd/Kbd.spec.md +141 -0
  185. package/src/Layout/Layout.doc.mjs +32 -0
  186. package/src/Layout/Layout.spec.md +199 -0
  187. package/src/Lightbox/Lightbox.doc.mjs +149 -33
  188. package/src/Lightbox/Lightbox.spec.md +197 -0
  189. package/src/Markdown/Markdown.doc.mjs +60 -0
  190. package/src/Markdown/Markdown.spec.md +200 -0
  191. package/src/MobileNav/MobileNav.doc.mjs +140 -32
  192. package/src/MobileNav/MobileNav.spec.md +208 -0
  193. package/src/MoreMenu/MoreMenu.doc.mjs +17 -0
  194. package/src/MoreMenu/MoreMenu.test.tsx +47 -0
  195. package/src/MoreMenu/MoreMenu.tsx +13 -1
  196. package/src/MultiSelector/MultiSelector.doc.mjs +129 -1
  197. package/src/MultiSelector/MultiSelector.spec.md +266 -0
  198. package/src/MultiSelector/MultiSelector.test.tsx +127 -0
  199. package/src/MultiSelector/MultiSelector.tsx +121 -73
  200. package/src/MultiSelector/index.ts +1 -0
  201. package/src/NavIcon/NavIcon.doc.mjs +17 -0
  202. package/src/NavIcon/NavIcon.spec.md +133 -0
  203. package/src/NavMenu/NavHeadingMenu.spec.md +205 -0
  204. package/src/NavMenu/NavMenu.doc.mjs +37 -0
  205. package/src/NumberInput/NumberInput.doc.mjs +1 -1
  206. package/src/Outline/Outline.doc.mjs +35 -0
  207. package/src/Outline/Outline.spec.md +161 -0
  208. package/src/OverflowList/OverflowList.doc.mjs +24 -0
  209. package/src/OverflowList/OverflowList.spec.md +156 -0
  210. package/src/Pagination/Pagination.doc.mjs +74 -0
  211. package/src/Pagination/Pagination.spec.md +225 -0
  212. package/src/Popover/Popover.doc.mjs +11 -11
  213. package/src/Popover/Popover.test.tsx +397 -2
  214. package/src/Popover/Popover.tsx +228 -21
  215. package/src/Popover/usePopover.tsx +92 -15
  216. package/src/PowerSearch/PowerSearch.doc.mjs +1 -1
  217. package/src/ProgressBar/ProgressBar.doc.mjs +198 -38
  218. package/src/ProgressBar/ProgressBar.spec.md +260 -0
  219. package/src/RadioList/RadioList.doc.mjs +1 -1
  220. package/src/Resizable/Resizable.doc.mjs +59 -16
  221. package/src/Resizable/Resizable.spec.md +194 -0
  222. package/src/Section/Section.doc.mjs +17 -0
  223. package/src/Section/Section.spec.md +138 -0
  224. package/src/SegmentedControl/SegmentedControl.doc.mjs +83 -0
  225. package/src/SegmentedControl/SegmentedControl.spec.md +151 -0
  226. package/src/Selector/Selector.doc.mjs +13 -1
  227. package/src/Selector/Selector.test.tsx +135 -0
  228. package/src/Selector/Selector.tsx +141 -82
  229. package/src/Selector/SelectorBottomSheet.tsx +97 -0
  230. package/src/Selector/index.ts +1 -0
  231. package/src/Selector/selectorPresentation.stylex.ts +20 -0
  232. package/src/Selector/useSelectorPresentation.ts +147 -0
  233. package/src/Skeleton/Skeleton.doc.mjs +12 -0
  234. package/src/Skeleton/Skeleton.spec.md +126 -0
  235. package/src/Slider/Slider.doc.mjs +186 -32
  236. package/src/Slider/Slider.spec.md +223 -0
  237. package/src/Stack/Stack.doc.mjs +22 -0
  238. package/src/Stack/Stack.spec.md +154 -0
  239. package/src/StatusDot/StatusDot.doc.mjs +17 -0
  240. package/src/StatusDot/StatusDot.spec.md +137 -0
  241. package/src/Switch/Switch.doc.mjs +41 -1
  242. package/src/Switch/Switch.spec.md +174 -0
  243. package/src/Text/Text.doc.mjs +190 -43
  244. package/src/Text/Text.spec.md +205 -0
  245. package/src/TextArea/TextArea.doc.mjs +256 -46
  246. package/src/TextArea/TextArea.spec.md +204 -0
  247. package/src/TextInput/TextInput.doc.mjs +1 -1
  248. package/src/TimeInput/TimeInput.doc.mjs +1 -1
  249. package/src/Toast/ToastViewport.test.tsx +118 -4
  250. package/src/Toast/useToastGesture.ts +61 -8
  251. package/src/ToggleButton/ToggleButton.doc.mjs +56 -0
  252. package/src/Tokenizer/Tokenizer.doc.mjs +1 -1
  253. package/src/Toolbar/Toolbar.doc.mjs +19 -0
  254. package/src/Toolbar/Toolbar.spec.md +173 -0
  255. package/src/Tooltip/Tooltip.doc.mjs +17 -0
  256. package/src/Tooltip/Tooltip.spec.md +141 -0
  257. package/src/TreeList/TreeList.doc.mjs +58 -0
  258. package/src/TreeList/TreeList.spec.md +220 -0
  259. package/src/Typeahead/Typeahead.doc.mjs +84 -2
  260. package/src/Typeahead/Typeahead.spec.md +250 -0
  261. package/src/hooks/useAdaptivePresentation.ts +35 -0
  262. package/src/hooks/useFocusReturnVisibility.ts +45 -0
  263. package/src/hooks/useFocusTrap.test.tsx +40 -0
  264. package/src/hooks/useFocusTrap.ts +13 -0
  265. package/src/i18n/InternationalizationContext.ts +3 -0
  266. package/src/i18n/InternationalizationProvider.tsx +8 -1
  267. package/src/i18n/__tests__/resolve.test.ts +23 -1
  268. package/src/i18n/resolve.ts +46 -49
  269. package/src/i18n/useTranslator.ts +2 -7
  270. package/src/theme/themingTargets.test.ts +91 -25
@@ -1,12 +1,92 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
 
3
+ /** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
4
+ const anatomy = [
5
+ {
6
+ name: 'Field',
7
+ required: false,
8
+ description:
9
+ 'Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.',
10
+ },
11
+ {
12
+ name: 'Input surface',
13
+ required: true,
14
+ description:
15
+ 'Painted control surface containing the editable input or the selected token.',
16
+ },
17
+ {
18
+ name: 'Icon-rendered start icon',
19
+ required: false,
20
+ description:
21
+ 'Optional leading semantic icon or icon component rendered through Icon.',
22
+ },
23
+ {
24
+ name: 'Caller-rendered start content',
25
+ required: false,
26
+ description:
27
+ 'Optional arbitrary React content rendered directly at the start of the input surface.',
28
+ },
29
+ {
30
+ name: 'Selected token',
31
+ required: false,
32
+ description:
33
+ 'Token that presents the selected item while the control is not in edit mode.',
34
+ },
35
+ {
36
+ name: 'Clear button',
37
+ required: false,
38
+ description:
39
+ 'Shared clear action that removes the selected item when hasClear is enabled.',
40
+ },
41
+ {
42
+ name: 'Dropdown',
43
+ required: false,
44
+ description:
45
+ 'Anchored listbox surface containing the current search results.',
46
+ },
47
+ {
48
+ name: 'Empty state',
49
+ required: false,
50
+ description: 'Message shown after a completed search returns no results.',
51
+ },
52
+ {
53
+ name: 'Result row',
54
+ required: false,
55
+ description:
56
+ 'Stable option wrapper that owns highlight, selection, pointer, and keyboard behavior.',
57
+ },
58
+ {
59
+ name: 'Default item content',
60
+ required: false,
61
+ description:
62
+ 'Standard TypeaheadItem label and supporting content rendered inside a result row when renderItem and item.element are absent.',
63
+ },
64
+ {
65
+ name: 'Caller-rendered item content',
66
+ required: false,
67
+ description:
68
+ 'Caller-owned result content supplied through renderItem or item.element inside the stable result row.',
69
+ },
70
+ {
71
+ name: 'Result group heading',
72
+ required: false,
73
+ description: 'Visible heading for a labeled group of result rows.',
74
+ },
75
+ {
76
+ name: 'Selected result state',
77
+ required: false,
78
+ description:
79
+ 'Selected styling and trailing check presented on the current result row.',
80
+ },
81
+ ];
82
+
3
83
  /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
4
84
 
5
85
  export const docs = {
6
86
  name: 'Typeahead',
7
87
  displayName: 'Typeahead',
8
88
  group: 'Typeahead',
9
- category: 'Data Input',
89
+ category: 'Form Controls',
10
90
  keywords: [
11
91
  'typeahead',
12
92
  'autocomplete',
@@ -86,7 +166,8 @@ export const docs = {
86
166
  {
87
167
  name: 'minQueryLength',
88
168
  type: 'number',
89
- description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
169
+ description:
170
+ 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
90
171
  default: '1',
91
172
  },
92
173
  {
@@ -199,6 +280,7 @@ export const docs = {
199
280
  ],
200
281
  },
201
282
  usage: {
283
+ anatomy,
202
284
  description:
203
285
  'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
204
286
  bestPractices: [
@@ -0,0 +1,250 @@
1
+ ---
2
+ schema_version: 1
3
+ template_version: 3
4
+ kind: component
5
+ id: component:Typeahead
6
+ authority: draft
7
+ archive_reason: null
8
+ superseded_by: null
9
+ approved_by: null
10
+ approved_at: null
11
+ owners: [cixzhang]
12
+ review_triggers: [theming]
13
+ verified_by:
14
+ [
15
+ packages/core/src/Typeahead/Typeahead.test.tsx,
16
+ packages/core/src/Typeahead/TypeaheadItem.test.tsx,
17
+ packages/core/src/Field/Field.test.tsx,
18
+ packages/core/src/Token/Token.test.tsx,
19
+ packages/core/src/Icon/Icon.test.tsx,
20
+ scripts/check-knowledge.mjs,
21
+ ]
22
+ families: [family:overlay-dismissal]
23
+ design_specs: []
24
+ architecture:
25
+ [architecture:component-theming-surface, architecture:layer-runtime]
26
+ contributing: []
27
+ system_specs: []
28
+ ---
29
+
30
+ # Typeahead component contract
31
+
32
+ ## Intent
33
+
34
+ Typeahead renders a single-selection search control with an optional standalone
35
+ Field shell and delegates its combobox engine and popup results to BaseTypeahead. This draft records current
36
+ consumer anatomy, target reachability, and the shipped difference between the
37
+ stable result row and its default TypeaheadItem content without changing runtime
38
+ behavior, styling, targets, or public API.
39
+
40
+ ## Compatibility and migration
41
+
42
+ - Released default preserved: `yes`
43
+ - Compatibility class: additive documentation only; runtime, DOM, styling,
44
+ targets, and public API remain unchanged
45
+ - Controlled/uncontrolled behavior: unchanged
46
+ - Migration decision: none
47
+
48
+ Consumer migration instructions belong in consumer docs and release notes.
49
+
50
+ ## Ownership boundary
51
+
52
+ **Owns**
53
+
54
+ - The painted Input surface and its current `typeahead` target.
55
+ - The Dropdown and Empty state rendered by BaseTypeahead and their current
56
+ `typeahead-dropdown` and `typeahead-empty-state` targets.
57
+ - Default item content rendered by TypeaheadItem and its current
58
+ `typeahead-item` target.
59
+ - The stable outer Result row, Result group heading, and Selected result state,
60
+ which currently have no Typeahead target.
61
+
62
+ **Does not own / non-goals**
63
+
64
+ - Standalone field-shell presentation — rendered by Field and themed through
65
+ Field's current `field` target; omitted when Typeahead is inside InputGroup.
66
+ - The Selected token — rendered by Token and themed through Token's current
67
+ `token` target.
68
+ - The Clear button — rendered by Field's InputClearButton and themed through
69
+ Field's current `input-clear-button` target.
70
+ - General Icon presentation for an Icon-rendered start icon.
71
+ - Arbitrary ReactNode start or item content supplied by the caller.
72
+ - A target/state for the outer Result row, Result group heading, or selected-row
73
+ concept; none exists on current `main`.
74
+ - Shared layer lifecycle, positioning, and dismissal behavior.
75
+
76
+ ## Public concepts
77
+
78
+ No new public concept is introduced. Consumer props and usage remain documented
79
+ in `Typeahead.doc.mjs`; BaseTypeahead and TypeaheadItem retain their existing
80
+ public component documentation.
81
+
82
+ ## Behavioral and layout contract
83
+
84
+ | ID | Candidate invariant | Basis | Draft review state |
85
+ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
86
+ | FR1 | The current standalone presentation contains a Field and painted Input surface; the supported InputGroup path renders the same Input surface without a Field. The surface contains an editable input when unselected or editing, and a Selected token plus collapsed input when selected and not editing. | Current source, docs, and tests | Verified current behavior; no normalization |
87
+ | FR2 | Input surface, Dropdown, Empty state, and Default item content carry the four current Typeahead targets documented in `Typeahead.doc.mjs`. | Current source, docs, and tests | Verified current behavior; no target change |
88
+ | FR3 | Every result, whether default or caller-rendered, sits inside the same stable outer Result row that owns option semantics, highlight, selected styling, pointer interaction, and keyboard indexing. | Current source and tests | Verified current behavior; no new behavior decided |
89
+ | FR4 | `typeahead-item` reaches only the standard TypeaheadItem label/supporting-content branch inside a Result row. A custom `renderItem` branch or caller-provided `item.element` does not receive that target, and no branch gives the outer Result row a Typeahead target. | Current source and owner tests | Verified current asymmetry; no normalization |
90
+ | FR5 | Result group heading and Selected result state are stable visible concepts but no current Typeahead target reaches them. The selected check uses a generic Icon, which does not expose a Typeahead-specific selected-row selector. | Current source | Verified factual reachability gaps |
91
+ | FR6 | When present, Field, Selected token, Clear button, and Icon-rendered start icon retain their Field, Token, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned. | Current composition and owners | Verified current behavior; no target change |
92
+
93
+ ### Allowed variation
94
+
95
+ - Standalone Typeahead renders Field; the supported InputGroup path omits it.
96
+ - The Input surface shows an editable input while empty or editing and a Token
97
+ while a selected value is not being edited. This shipped asymmetry is recorded,
98
+ not normalized into a new shared part or target.
99
+ - A Result row may contain standard TypeaheadItem content, custom `renderItem`
100
+ content, or a caller-provided `item.element`. Only the standard TypeaheadItem
101
+ label/supporting-content branch carries `typeahead-item`.
102
+ - Results may be ungrouped or grouped. Group wrappers and headings do not gain a
103
+ target from that variation.
104
+ - Semantic names and icon component types render through Icon. Arbitrary ReactNode
105
+ start content renders directly and stays caller-owned.
106
+
107
+ ### Representative states
108
+
109
+ | State | Required invariant | Allowed variation |
110
+ | ----------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
111
+ | Standalone or InputGroup | Field is present only standalone; Input surface anatomy and targets remain the same in both paths. | InputGroup owns grouped layout and labeling support. |
112
+ | Empty or editing | Editable input remains inside the `typeahead` Input surface. | Query, loading state, and popup visibility may vary. |
113
+ | Selected and not editing | Token owns the selected-value presentation while the input is collapsed. | Clear button may be present according to `hasClear` and disabled state. |
114
+ | Results with default renderer | Outer Result row remains untargeted; inner TypeaheadItem carries `typeahead-item`. | Item label, icon/avatar, and description may vary. |
115
+ | Results with custom renderer | Outer Result row remains untargeted; custom content receives no `typeahead-item`. | Caller owns the inner result content. |
116
+ | Grouped and selected results | Group heading and selected-row concept remain untargeted by Typeahead. | A generic Icon paints the selected check. |
117
+ | Empty completed search | Empty state carries `typeahead-empty-state` inside the Dropdown. | Consumer-supplied empty text may vary. |
118
+
119
+ ### Transformation and precedence order
120
+
121
+ - No new query, search-result, selection, edit-mode, or styling precedence rule is
122
+ introduced.
123
+
124
+ ### Performance and resources
125
+
126
+ - No new performance or resource rule is introduced.
127
+
128
+ ## Accessibility contract
129
+
130
+ This draft does not change or extend Typeahead's existing field, combobox,
131
+ listbox, option, live-region, focus, or dismissal behavior.
132
+
133
+ ## Design relationships
134
+
135
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
136
+ | ----------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------ | ----------------- | ------------------ |
137
+ | Field | Provides the label and optional supporting content outside InputGroup; omitted inside InputGroup. | Field component | Supporting | FR1, FR6 |
138
+ | Input surface | Paints the control around the editable input or selected token. | Current source and public docs | Prominent | FR1, FR2 |
139
+ | Icon-rendered start icon | Presents a semantic or component icon through Icon. | Icon component | Supporting | FR6 |
140
+ | Caller-rendered start content | Presents arbitrary caller content directly in the input surface's start slot. | Caller-supplied content | Context-dependent | FR6 |
141
+ | Selected token | Presents the selected value outside edit mode through Token. | Token component | Prominent | FR1, FR6 |
142
+ | Clear button | Removes the selected value through the shared field clear action. | Field component | Supporting | FR6 |
143
+ | Dropdown | Paints the anchored listbox surface containing results or Empty state. | Current source and public docs | Prominent | FR2 |
144
+ | Empty state | Presents the no-results message after a completed empty search. | Current source and public docs | Prominent | FR2 |
145
+ | Result row | Owns option semantics, interaction, highlight, selection styling, and keyboard index for every result. | Current source and tests | Prominent | FR3, FR4 |
146
+ | Default item content | Presents the standard TypeaheadItem label and optional supporting content inside a Result row. | TypeaheadItem component | Prominent | FR2, FR4 |
147
+ | Caller-rendered item content | Presents custom `renderItem` or `item.element` content inside the stable Result row. | Caller-supplied content | Context-dependent | FR3, FR4, FR6 |
148
+ | Result group heading | Labels a visible group of Result rows. | Current source | Supporting | FR5 |
149
+ | Selected result state | Presents selected row weight and a trailing check without a Typeahead-specific target or target state. | Current source | Supporting | FR5 |
150
+
151
+ The current target placement is asymmetric: `typeahead-item` is on default inner
152
+ TypeaheadItem content, while the stable outer Result row owns interaction and state
153
+ for both default and custom content. Group headings and the selected-result concept
154
+ are also untargeted. This record preserves those facts and does not move, add, or
155
+ normalize targets.
156
+
157
+ ### Theming anatomy
158
+
159
+ <!-- anatomy-theming:v1 -->
160
+
161
+ ```json
162
+ {
163
+ "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
164
+ "Input surface": {"target": "typeahead"},
165
+ "Icon-rendered start icon": {
166
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
167
+ },
168
+ "Caller-rendered start content": {
169
+ "none": {
170
+ "reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no Typeahead target."
171
+ }
172
+ },
173
+ "Selected token": {
174
+ "delegatesTo": {"owner": "component:Token", "target": "token"}
175
+ },
176
+ "Clear button": {
177
+ "delegatesTo": {
178
+ "owner": "component:Field",
179
+ "target": "input-clear-button"
180
+ }
181
+ },
182
+ "Dropdown": {"target": "typeahead-dropdown"},
183
+ "Empty state": {"target": "typeahead-empty-state"},
184
+ "Result row": {
185
+ "none": {
186
+ "reason": "reachability-gap: The stable outer option row owns interaction and state but has no current Typeahead target."
187
+ }
188
+ },
189
+ "Default item content": {"target": "typeahead-item"},
190
+ "Caller-rendered item content": {
191
+ "none": {
192
+ "reason": "intentional: Custom renderItem and item.element content is caller-owned and does not receive the standard TypeaheadItem target."
193
+ }
194
+ },
195
+ "Result group heading": {
196
+ "none": {
197
+ "reason": "reachability-gap: No current public target reaches the visible result-group heading."
198
+ }
199
+ },
200
+ "Selected result state": {
201
+ "none": {
202
+ "reason": "reachability-gap: No current Typeahead target or target state reaches the outer selected row and its selection concept."
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ ## Family and system relationships
209
+
210
+ - `architecture:component-theming-surface` owns anatomy qualification, local
211
+ target mapping, delegation, and factual `none` dispositions.
212
+ - `architecture:layer-runtime` owns the current Popover host, positioning, native
213
+ light-dismiss, and visibility reconciliation used by the Dropdown.
214
+ - `family:overlay-dismissal` owns shared Escape and platform-close ordering;
215
+ Typeahead participates through its composed Popover owner.
216
+ - Field, Token, and Icon retain ownership of their delegated targets and
217
+ presentation.
218
+
219
+ ## Verification map
220
+
221
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
222
+ | ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------- |
223
+ | FR1, FR6 | `Typeahead.test.tsx`, owner tests, and Typeahead composition source | Standalone/InputGroup, empty, editing, selected, clear, start icon | A documented composed part disappears, gains the wrong owner, or misreports Field presence. | `audit:Typeahead/anatomy` |
224
+ | FR2 | Source inspection, target inventories, empty-state test, and `TypeaheadItem.test.tsx` | Input, open Dropdown, empty search, default item | A current target is missed, invented, or documented on an element that does not carry it. | `audit:Typeahead/theming` |
225
+ | FR3, FR4, FR5 | BaseTypeahead source and result/group/selection tests | Default/custom result, grouped result, selected row | The record hides the outer/inner asymmetry or claims reachability that current code lacks. | `audit:Typeahead/theming` |
226
+ | Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Typeahead/theming` |
227
+
228
+ Existing tests directly assert Empty state and TypeaheadItem target presence,
229
+ selected-value Token behavior, result semantics, selection state, and standalone
230
+ Field content. Source inspection confirms InputGroup's Field omission and, with
231
+ public target inventories, provides the current Input surface and Dropdown target
232
+ evidence. No test is represented here as proof of a target it does not directly
233
+ assert.
234
+
235
+ ## Decision log
236
+
237
+ None. This draft records current facts and introduces no component-local design,
238
+ API, theming, or layer-system decision.
239
+
240
+ ## Open questions
241
+
242
+ - **OQ1 — Should the stable Result row, Result group heading, or Selected result
243
+ state gain a public Typeahead target?** (`human-api`) Their current lack of
244
+ reachability is an audit gap, not settled intent. This draft does not normalize
245
+ the existing outer-row/default-content asymmetry.
246
+
247
+ ## Content boundary
248
+
249
+ This file does not duplicate consumer prop tables, examples, search algorithms,
250
+ implementation steps, or shared layer and theming rules. It links to their owners.
@@ -0,0 +1,35 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @file useAdaptivePresentation.ts
7
+ * @input Uses the shared SSR-safe media-query hook
8
+ * @output Resolves popover/bottom-sheet presentation policy
9
+ * @position Internal overlay policy shared across component families
10
+ */
11
+
12
+ import {useMediaQuery} from './useMediaQuery';
13
+
14
+ export type AdaptivePresentation = 'popover' | 'bottom-sheet' | 'adaptive';
15
+ export type ResolvedAdaptivePresentation = Exclude<
16
+ AdaptivePresentation,
17
+ 'adaptive'
18
+ >;
19
+
20
+ // Width keeps desktop-class tablets and large touch displays anchored by
21
+ // default. Pointer capability, rather than `hover: none`, avoids excluding
22
+ // touch browsers that also report hover capability.
23
+ export const COMPACT_TOUCH_PRESENTATION_QUERY =
24
+ '(max-width: 768px) and (pointer: coarse)';
25
+
26
+ export function useAdaptivePresentation(
27
+ presentation: AdaptivePresentation,
28
+ ): ResolvedAdaptivePresentation {
29
+ const isCompactTouch = useMediaQuery(COMPACT_TOUCH_PRESENTATION_QUERY);
30
+ return presentation === 'adaptive'
31
+ ? isCompactTouch
32
+ ? 'bottom-sheet'
33
+ : 'popover'
34
+ : presentation;
35
+ }
@@ -0,0 +1,45 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @file useFocusReturnVisibility.ts
7
+ * @input Uses the shared interaction-modality tracker
8
+ * @output Preserves returned focus while suppressing pointer-only focus rings
9
+ * @position Internal focus-return policy for adaptive overlays
10
+ */
11
+
12
+ import {useCallback, useEffect, useState} from 'react';
13
+ import {
14
+ getInteractionModality,
15
+ trackInteractionModality,
16
+ } from '../utils/interactionModality';
17
+
18
+ export function useFocusReturnVisibility() {
19
+ const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
20
+
21
+ useEffect(() => {
22
+ trackInteractionModality();
23
+ }, []);
24
+
25
+ const prepareFocusReturn = useCallback(() => {
26
+ setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
27
+ }, []);
28
+
29
+ const resetFocusReturn = useCallback(() => {
30
+ setIsFocusRingSuppressed(false);
31
+ }, []);
32
+
33
+ const onFocusReturnTargetFocus = useCallback(() => {
34
+ if (getInteractionModality() === 'keyboard') {
35
+ setIsFocusRingSuppressed(false);
36
+ }
37
+ }, []);
38
+
39
+ return {
40
+ isFocusRingSuppressed,
41
+ onFocusReturnTargetFocus,
42
+ prepareFocusReturn,
43
+ resetFocusReturn,
44
+ };
45
+ }
@@ -193,6 +193,46 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
193
193
  expect(screen.getByTestId('first')).toHaveFocus();
194
194
  });
195
195
 
196
+ it('moves from a programmatic container focus target into the tabbable cycle', () => {
197
+ render(
198
+ <Trap>
199
+ <button type="button" data-testid="first">
200
+ First
201
+ </button>
202
+ <button type="button" data-testid="last">
203
+ Last
204
+ </button>
205
+ </Trap>,
206
+ );
207
+ const trap = screen.getByTestId('trap');
208
+ trap.tabIndex = -1;
209
+ trap.focus();
210
+
211
+ fireEvent.keyDown(document, {key: 'Tab'});
212
+
213
+ expect(screen.getByTestId('first')).toHaveFocus();
214
+ });
215
+
216
+ it('moves backward from a programmatic container focus target to the last tabbable control', () => {
217
+ render(
218
+ <Trap>
219
+ <button type="button" data-testid="first">
220
+ First
221
+ </button>
222
+ <button type="button" data-testid="last">
223
+ Last
224
+ </button>
225
+ </Trap>,
226
+ );
227
+ const trap = screen.getByTestId('trap');
228
+ trap.tabIndex = -1;
229
+ trap.focus();
230
+
231
+ fireEvent.keyDown(document, {key: 'Tab', shiftKey: true});
232
+
233
+ expect(screen.getByTestId('last')).toHaveFocus();
234
+ });
235
+
196
236
  it('keeps a programmatic focus target when the trap has no tabbable controls', () => {
197
237
  render(
198
238
  <Trap>
@@ -375,6 +375,19 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
375
375
  const first = focusable[0];
376
376
  const last = focusable[focusable.length - 1];
377
377
 
378
+ if (document.activeElement === container) {
379
+ // Programmatic initial focus can sit on the trap container itself
380
+ // (for example a dialog panel with no content controls). Move into
381
+ // the tabbable cycle instead of letting Tab escape to the page.
382
+ event.preventDefault();
383
+ if (event.shiftKey) {
384
+ last.focus();
385
+ } else {
386
+ first.focus();
387
+ }
388
+ return;
389
+ }
390
+
378
391
  if (event.shiftKey) {
379
392
  // Shift+Tab: if on first element, wrap to last
380
393
  if (document.activeElement === first) {
@@ -23,6 +23,7 @@
23
23
  */
24
24
 
25
25
  import {createContext} from 'react';
26
+ import {getResolve} from './resolve';
26
27
  import type {Locale, MessagesByLocale, Overrides} from './types';
27
28
 
28
29
  export interface InternationalizationContextValue {
@@ -30,6 +31,7 @@ export interface InternationalizationContextValue {
30
31
  direction: 'ltr' | 'rtl';
31
32
  messages: MessagesByLocale;
32
33
  overrides?: Overrides;
34
+ translate: ReturnType<typeof getResolve>;
33
35
  }
34
36
 
35
37
  /**
@@ -41,5 +43,6 @@ export const InternationalizationContext =
41
43
  locale: 'en',
42
44
  direction: 'ltr',
43
45
  messages: {},
46
+ translate: getResolve('en', {}),
44
47
  });
45
48
  InternationalizationContext.displayName = 'InternationalizationContext';
@@ -23,6 +23,7 @@ import {useMemo, type ReactNode} from 'react';
23
23
  import {InternationalizationContext} from './InternationalizationContext';
24
24
  import {getLocaleDirection} from './getLocaleDirection';
25
25
  import type {Locale, MessagesByLocale, Overrides} from './types';
26
+ import {getResolve} from './resolve';
26
27
 
27
28
  export interface InternationalizationProviderProps {
28
29
  /**
@@ -85,7 +86,13 @@ export function InternationalizationProvider({
85
86
  }: InternationalizationProviderProps) {
86
87
  const direction = dir ?? getLocaleDirection(locale);
87
88
  const value = useMemo(
88
- () => ({locale, direction, messages: messages ?? {}, overrides}),
89
+ () => ({
90
+ locale,
91
+ direction,
92
+ messages: messages ?? {},
93
+ overrides,
94
+ translate: getResolve(locale, messages ?? {}, overrides),
95
+ }),
89
96
  [locale, direction, messages, overrides],
90
97
  );
91
98
  return (
@@ -9,9 +9,16 @@
9
9
  */
10
10
 
11
11
  import {describe, expect, test, beforeEach, vi} from 'vitest';
12
- import {__resetForTests, resolve, resolveLocaleChain} from '../resolve';
12
+ import {__resetForTests, getResolve, resolveLocaleChain} from '../resolve';
13
13
  import type {Catalog, MessagesByLocale, Overrides} from '../types';
14
14
 
15
+ const resolve = (
16
+ ...[key, values, locale, messages, overrides]: [
17
+ ...Parameters<ReturnType<typeof getResolve>>,
18
+ ...Parameters<typeof getResolve>,
19
+ ]
20
+ ) => getResolve(locale, messages, overrides)(key, values);
21
+
15
22
  // Reset caches between tests so warn-once and formatter cache don't bleed.
16
23
  beforeEach(() => {
17
24
  __resetForTests();
@@ -209,6 +216,21 @@ describe('resolve — overrides', () => {
209
216
  // Should fall through to en since fr has no messages and es override doesn't apply
210
217
  expect(out).toBe('Go to next page');
211
218
  });
219
+
220
+ test('override `pt` should take precedence over message `pt-BR`', () => {
221
+ const overrides: Overrides = {
222
+ pt: {key: 'override'},
223
+ };
224
+ const messages: MessagesByLocale = {
225
+ 'pt-BR': {
226
+ key: {
227
+ defaultMessage: 'shipped',
228
+ },
229
+ },
230
+ };
231
+ const out = resolve('key', undefined, 'pt-BR', messages, overrides);
232
+ expect(out).toBe('override');
233
+ });
212
234
  });
213
235
 
214
236
  describe('resolve — ICU MessageFormat', () => {