@astryxdesign/core 0.7.7-canary.ae97fa8 → 0.7.7-canary.b377b21

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 (228) hide show
  1. package/dist/AlertDialog/AlertDialog.d.ts +4 -1
  2. package/dist/AlertDialog/AlertDialog.d.ts.map +1 -1
  3. package/dist/AlertDialog/AlertDialog.js +36 -6
  4. package/dist/BottomSheet/BottomSheetPanel.d.ts.map +1 -1
  5. package/dist/BottomSheet/BottomSheetPanel.js +22 -3
  6. package/dist/BottomSheet/useSheetGestures.d.ts.map +1 -1
  7. package/dist/BottomSheet/useSheetGestures.js +3 -1
  8. package/dist/Button/Button.d.ts.map +1 -1
  9. package/dist/Button/Button.js +17 -1
  10. package/dist/CheckboxInput/CheckboxInput.d.ts.map +1 -1
  11. package/dist/CheckboxInput/CheckboxInput.js +13 -2
  12. package/dist/ComplexSelector/ComplexSelector.d.ts +4 -1
  13. package/dist/ComplexSelector/ComplexSelector.d.ts.map +1 -1
  14. package/dist/ComplexSelector/ComplexSelector.js +14 -4
  15. package/dist/ContextMenu/ContextMenu.js +2 -2
  16. package/dist/Dialog/Dialog.d.ts.map +1 -1
  17. package/dist/Dialog/Dialog.js +7 -31
  18. package/dist/Field/Field.js +2 -2
  19. package/dist/HoverCard/HoverCard.d.ts +4 -3
  20. package/dist/HoverCard/HoverCard.d.ts.map +1 -1
  21. package/dist/HoverCard/useHoverCard.d.ts +5 -4
  22. package/dist/HoverCard/useHoverCard.d.ts.map +1 -1
  23. package/dist/HoverCard/useHoverCard.js +17 -31
  24. package/dist/Icon/Icon.d.ts +5 -1
  25. package/dist/Icon/Icon.d.ts.map +1 -1
  26. package/dist/Icon/Icon.js +5 -2
  27. package/dist/Layer/usePressPin.d.ts +17 -5
  28. package/dist/Layer/usePressPin.d.ts.map +1 -1
  29. package/dist/Layer/usePressPin.js +62 -12
  30. package/dist/Lightbox/Lightbox.d.ts.map +1 -1
  31. package/dist/Lightbox/Lightbox.js +18 -0
  32. package/dist/PowerSearch/PowerSearch.d.ts +36 -3
  33. package/dist/PowerSearch/PowerSearch.d.ts.map +1 -1
  34. package/dist/PowerSearch/PowerSearch.js +433 -127
  35. package/dist/PowerSearch/PowerSearchBottomSheet.d.ts +100 -0
  36. package/dist/PowerSearch/PowerSearchBottomSheet.d.ts.map +1 -0
  37. package/dist/PowerSearch/PowerSearchBottomSheet.js +1913 -0
  38. package/dist/PowerSearch/PowerSearchEditPopover.d.ts +32 -1
  39. package/dist/PowerSearch/PowerSearchEditPopover.d.ts.map +1 -1
  40. package/dist/PowerSearch/PowerSearchEditPopover.js +17 -6
  41. package/dist/PowerSearch/PowerSearchValueEditor.d.ts +38 -3
  42. package/dist/PowerSearch/PowerSearchValueEditor.d.ts.map +1 -1
  43. package/dist/PowerSearch/PowerSearchValueEditor.js +170 -61
  44. package/dist/PowerSearch/formatFilterValue.d.ts +7 -0
  45. package/dist/PowerSearch/formatFilterValue.d.ts.map +1 -1
  46. package/dist/PowerSearch/formatFilterValue.js +11 -1
  47. package/dist/PowerSearch/formatTokenValue.d.ts +28 -0
  48. package/dist/PowerSearch/formatTokenValue.d.ts.map +1 -0
  49. package/dist/PowerSearch/formatTokenValue.js +160 -0
  50. package/dist/PowerSearch/powerSearchSheetUtils.d.ts +65 -0
  51. package/dist/PowerSearch/powerSearchSheetUtils.d.ts.map +1 -0
  52. package/dist/PowerSearch/powerSearchSheetUtils.js +168 -0
  53. package/dist/RadioList/RadioList.d.ts.map +1 -1
  54. package/dist/RadioList/RadioList.js +3 -2
  55. package/dist/RadioList/RadioListItem.d.ts +1 -1
  56. package/dist/RadioList/RadioListItem.d.ts.map +1 -1
  57. package/dist/RadioList/RadioListItem.js +5 -3
  58. package/dist/Resizable/ResizeHandle.d.ts +2 -1
  59. package/dist/Resizable/ResizeHandle.d.ts.map +1 -1
  60. package/dist/Resizable/ResizeHandle.js +99 -77
  61. package/dist/SegmentedControl/useSegmentedSelectionMotion.d.ts.map +1 -1
  62. package/dist/SegmentedControl/useSegmentedSelectionMotion.js +3 -3
  63. package/dist/Slider/sliderTouchController.js +2 -2
  64. package/dist/Spinner/Spinner.d.ts +1 -1
  65. package/dist/Spinner/Spinner.d.ts.map +1 -1
  66. package/dist/Spinner/Spinner.js +60 -58
  67. package/dist/Switch/useSwitchTouch.js +4 -4
  68. package/dist/Table/BaseTable.d.ts.map +1 -1
  69. package/dist/Table/BaseTable.js +29 -8
  70. package/dist/TextInput/TextInput.d.ts +2 -2
  71. package/dist/TextInput/TextInput.d.ts.map +1 -1
  72. package/dist/TextInput/TextInput.js +10 -7
  73. package/dist/Toast/Toast.d.ts +11 -1
  74. package/dist/Toast/Toast.d.ts.map +1 -1
  75. package/dist/Toast/Toast.js +25 -15
  76. package/dist/Toast/ToastViewport.d.ts.map +1 -1
  77. package/dist/Toast/ToastViewport.js +94 -34
  78. package/dist/Toast/types.d.ts +9 -3
  79. package/dist/Toast/types.d.ts.map +1 -1
  80. package/dist/Tooltip/useTooltip.d.ts +19 -1
  81. package/dist/Tooltip/useTooltip.d.ts.map +1 -1
  82. package/dist/Tooltip/useTooltip.js +34 -53
  83. package/dist/Typeahead/TypeaheadItem.d.ts +2 -1
  84. package/dist/Typeahead/TypeaheadItem.d.ts.map +1 -1
  85. package/dist/animator/createAnimator.d.ts +98 -0
  86. package/dist/animator/createAnimator.d.ts.map +1 -0
  87. package/dist/animator/createAnimator.js +259 -0
  88. package/dist/astryx.css +35 -6
  89. package/dist/gestures/PressTracker.d.ts.map +1 -1
  90. package/dist/gestures/PressTracker.js +4 -3
  91. package/dist/hooks/actionGroupTracker.d.ts +4 -1
  92. package/dist/hooks/actionGroupTracker.d.ts.map +1 -1
  93. package/dist/hooks/actionGroupTracker.js +13 -3
  94. package/dist/hooks/index.d.ts +1 -0
  95. package/dist/hooks/index.d.ts.map +1 -1
  96. package/dist/hooks/index.js +1 -0
  97. package/dist/hooks/pressGroupContext.d.ts +6 -0
  98. package/dist/hooks/pressGroupContext.d.ts.map +1 -0
  99. package/dist/hooks/pressGroupContext.js +20 -0
  100. package/dist/hooks/useActionGroupTracking.d.ts +53 -0
  101. package/dist/hooks/useActionGroupTracking.d.ts.map +1 -0
  102. package/dist/hooks/useActionGroupTracking.js +174 -0
  103. package/dist/hooks/useAnimator.d.ts +41 -0
  104. package/dist/hooks/useAnimator.d.ts.map +1 -0
  105. package/dist/hooks/useAnimator.js +70 -0
  106. package/dist/hooks/useAttachment.d.ts +1 -1
  107. package/dist/hooks/useAttachment.js +1 -1
  108. package/dist/hooks/useInputStatusIcon.d.ts +1 -1
  109. package/dist/hooks/useInputStatusIcon.d.ts.map +1 -1
  110. package/dist/hooks/useInputStatusIcon.js +2 -2
  111. package/dist/hooks/useLongPress.d.ts +6 -2
  112. package/dist/hooks/useLongPress.d.ts.map +1 -1
  113. package/dist/hooks/useLongPress.js +95 -15
  114. package/dist/i18n/generated-english/PowerSearch/PowerSearchBottomSheet.generated.d.ts +8 -0
  115. package/dist/i18n/generated-english/PowerSearch/PowerSearchBottomSheet.generated.d.ts.map +1 -0
  116. package/dist/i18n/generated-english/PowerSearch/PowerSearchBottomSheet.generated.js +42 -0
  117. package/dist/i18n/generated-english/PowerSearch/PowerSearchValueEditor.generated.d.ts.map +1 -1
  118. package/dist/i18n/generated-english/PowerSearch/PowerSearchValueEditor.generated.js +6 -0
  119. package/dist/i18n/generated-english/PowerSearch/formatTokenValue.generated.d.ts +8 -0
  120. package/dist/i18n/generated-english/PowerSearch/formatTokenValue.generated.d.ts.map +1 -0
  121. package/dist/i18n/generated-english/PowerSearch/formatTokenValue.generated.js +14 -0
  122. package/dist/i18n/generated-locales/en.generated.d.ts.map +1 -1
  123. package/dist/i18n/generated-locales/en.generated.js +30 -0
  124. package/dist/i18n/generated-locales/pseudo.generated.d.ts.map +1 -1
  125. package/dist/i18n/generated-locales/pseudo.generated.js +30 -0
  126. package/dist/index.d.ts +1 -0
  127. package/dist/index.d.ts.map +1 -1
  128. package/dist/index.js +4 -0
  129. package/dist/internal/indicatorPress.stylex.d.ts +20 -0
  130. package/dist/internal/indicatorPress.stylex.d.ts.map +1 -0
  131. package/dist/internal/indicatorPress.stylex.js +26 -0
  132. package/dist/motion/animator.d.ts +14 -14
  133. package/dist/motion/animator.d.ts.map +1 -1
  134. package/dist/motion/animator.js +41 -18
  135. package/dist/motion/uikit/alert.d.ts +41 -0
  136. package/dist/motion/uikit/alert.d.ts.map +1 -0
  137. package/dist/motion/uikit/alert.js +43 -0
  138. package/dist/privateAttributes/pressGroupItem.stylex.d.ts +15 -0
  139. package/dist/privateAttributes/pressGroupItem.stylex.d.ts.map +1 -0
  140. package/dist/privateAttributes/pressGroupItem.stylex.js +23 -0
  141. package/dist/utils/focusReturn.d.ts +15 -0
  142. package/dist/utils/focusReturn.d.ts.map +1 -1
  143. package/dist/utils/focusReturn.js +28 -0
  144. package/dist/utils/interactionOverlay.stylex.d.ts +3 -2
  145. package/dist/utils/interactionOverlay.stylex.d.ts.map +1 -1
  146. package/dist/utils/interactionOverlay.stylex.js +3 -2
  147. package/dist/utils/pressFeedback.d.ts.map +1 -1
  148. package/dist/utils/pressFeedback.js +19 -6
  149. package/dist/utils/triggerFocus.d.ts +36 -0
  150. package/dist/utils/triggerFocus.d.ts.map +1 -0
  151. package/dist/utils/triggerFocus.js +65 -0
  152. package/locales/en.json +120 -0
  153. package/locales/pseudo.json +90 -0
  154. package/package.json +9 -4
  155. package/src/AlertDialog/AlertDialog.doc.mjs +2 -2
  156. package/src/AlertDialog/AlertDialog.tsx +37 -5
  157. package/src/BottomSheet/BottomSheetPanel.tsx +33 -3
  158. package/src/BottomSheet/useSheetGestures.ts +3 -1
  159. package/src/Button/Button.tsx +26 -4
  160. package/src/CheckboxInput/CheckboxInput.doc.mjs +18 -0
  161. package/src/CheckboxInput/CheckboxInput.tsx +36 -9
  162. package/src/ComplexSelector/ComplexSelector.tsx +20 -5
  163. package/src/ContextMenu/ContextMenu.tsx +2 -2
  164. package/src/Dialog/Dialog.tsx +10 -31
  165. package/src/Field/Field.tsx +2 -2
  166. package/src/HoverCard/HoverCard.doc.mjs +4 -2
  167. package/src/HoverCard/HoverCard.tsx +4 -3
  168. package/src/HoverCard/useHoverCard.doc.mjs +178 -36
  169. package/src/HoverCard/useHoverCard.tsx +46 -52
  170. package/src/Icon/Icon.doc.mjs +49 -8
  171. package/src/Icon/Icon.tsx +15 -7
  172. package/src/Layer/usePressPin.ts +81 -15
  173. package/src/Lightbox/Lightbox.tsx +18 -0
  174. package/src/PowerSearch/PowerSearch.doc.mjs +54 -5
  175. package/src/PowerSearch/PowerSearch.tsx +609 -155
  176. package/src/PowerSearch/PowerSearchBottomSheet.tsx +2515 -0
  177. package/src/PowerSearch/PowerSearchEditPopover.tsx +28 -6
  178. package/src/PowerSearch/PowerSearchValueEditor.tsx +203 -38
  179. package/src/PowerSearch/formatFilterValue.ts +18 -1
  180. package/src/PowerSearch/formatTokenValue.ts +215 -0
  181. package/src/PowerSearch/powerSearchSheetUtils.ts +224 -0
  182. package/src/RadioList/RadioList.tsx +3 -2
  183. package/src/RadioList/RadioListItem.tsx +5 -3
  184. package/src/Resizable/Resizable.doc.mjs +5 -4
  185. package/src/Resizable/ResizeHandle.tsx +167 -109
  186. package/src/SegmentedControl/useSegmentedSelectionMotion.ts +6 -3
  187. package/src/Slider/sliderTouchController.ts +2 -2
  188. package/src/Spinner/Spinner.tsx +77 -63
  189. package/src/Switch/useSwitchTouch.ts +4 -4
  190. package/src/Table/BaseTable.tsx +46 -12
  191. package/src/TextInput/TextInput.tsx +11 -10
  192. package/src/Toast/Toast.doc.mjs +4 -3
  193. package/src/Toast/Toast.tsx +52 -32
  194. package/src/Toast/ToastViewport.tsx +121 -35
  195. package/src/Toast/types.ts +9 -3
  196. package/src/Tooltip/useTooltip.doc.mjs +24 -0
  197. package/src/Tooltip/useTooltip.tsx +61 -56
  198. package/src/Typeahead/TypeaheadItem.doc.mjs +6 -3
  199. package/src/Typeahead/TypeaheadItem.tsx +2 -1
  200. package/src/animator/createAnimator.doc.mjs +153 -0
  201. package/src/animator/createAnimator.ts +324 -0
  202. package/src/gestures/PressTracker.ts +4 -3
  203. package/src/gestures/README.md +7 -1
  204. package/src/hooks/actionGroupTracker.ts +20 -5
  205. package/src/hooks/index.ts +2 -0
  206. package/src/hooks/pressGroupContext.ts +21 -0
  207. package/src/hooks/useActionGroupTracking.ts +224 -0
  208. package/src/hooks/useAnimator.doc.mjs +109 -0
  209. package/src/hooks/useAnimator.ts +67 -0
  210. package/src/hooks/useAttachment.ts +1 -1
  211. package/src/hooks/useInputStatusIcon.tsx +3 -2
  212. package/src/hooks/useLongPress.doc.mjs +2 -2
  213. package/src/hooks/useLongPress.ts +136 -15
  214. package/src/i18n/generated-english/PowerSearch/PowerSearchBottomSheet.generated.ts +43 -0
  215. package/src/i18n/generated-english/PowerSearch/PowerSearchValueEditor.generated.ts +6 -0
  216. package/src/i18n/generated-english/PowerSearch/formatTokenValue.generated.ts +15 -0
  217. package/src/i18n/generated-locales/en.generated.ts +41 -0
  218. package/src/i18n/generated-locales/pseudo.generated.ts +42 -0
  219. package/src/index.ts +13 -0
  220. package/src/internal/indicatorPress.stylex.ts +24 -0
  221. package/src/motion/README.md +8 -5
  222. package/src/motion/animator.ts +61 -29
  223. package/src/motion/uikit/alert.ts +43 -0
  224. package/src/privateAttributes/pressGroupItem.stylex.ts +23 -0
  225. package/src/utils/focusReturn.ts +30 -0
  226. package/src/utils/interactionOverlay.stylex.ts +3 -2
  227. package/src/utils/pressFeedback.ts +19 -6
  228. package/src/utils/triggerFocus.ts +80 -0
@@ -110,6 +110,18 @@ export const docs = {
110
110
  description:
111
111
  'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.',
112
112
  },
113
+ {
114
+ name: 'show',
115
+ type: '() => void',
116
+ description:
117
+ 'Opens the tooltip now and keeps it open until hide(), Escape, a press outside, or focus leaving its trigger. Its text is announced once, and onShow fires. Under a controlled isOpen it only calls onShow. Does nothing while isEnabled is false.',
118
+ },
119
+ {
120
+ name: 'hide',
121
+ type: '() => void',
122
+ description:
123
+ 'Closes the tooltip now, and onHide fires. Under a controlled isOpen it only calls onHide.',
124
+ },
113
125
  ],
114
126
  usage: {
115
127
  description:
@@ -125,6 +137,11 @@ export const docs = {
125
137
  description:
126
138
  'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.',
127
139
  },
140
+ {
141
+ guidance: true,
142
+ description:
143
+ 'For a toggle-style trigger, have your own button call show() and hide() on each press. Give it aria-describedby and aria-controls set to describedBy, and aria-expanded (true while show() holds the tooltip, false after hide() or onHide), and keep its own accessible name. For an info icon, use InfoTip instead.',
144
+ },
128
145
  {
129
146
  guidance: false,
130
147
  description:
@@ -167,6 +184,8 @@ export const docsDense = {
167
184
  anchorId: 'CSS anchor name.',
168
185
  describedBy: 'ID for aria-describedby.',
169
186
  renderTooltip: 'renders anchor-positioned tooltip content.',
187
+ show: 'opens + holds until hide()/Escape/outside press/focus leave; announces once; onShow. Controlled: onShow only. No-op when disabled.',
188
+ hide: 'closes; onHide. Controlled: onHide only.',
170
189
  },
171
190
  usage: {
172
191
  description:
@@ -182,6 +201,11 @@ export const docsDense = {
182
201
  description:
183
202
  'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.',
184
203
  },
204
+ {
205
+ guidance: true,
206
+ description:
207
+ 'Toggle-style trigger: own button calls show()/hide() per press, sets aria-describedby + aria-controls={describedBy}, aria-expanded (true while held), keeps its own name. Info icon: use InfoTip.',
208
+ },
185
209
  {
186
210
  guidance: false,
187
211
  description:
@@ -5,7 +5,8 @@
5
5
  /**
6
6
  * @file useTooltip.tsx
7
7
  * @input Uses useLayer, usePressPin, React hooks
8
- * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips,
8
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
9
+ * and imperative show() and hide() for an app-built toggle trigger,
9
10
  * and the module-only useTooltipWithTriggerBehavior that InfoTip's press-to-pin uses
10
11
  * @position Layer hook; builds on useLayer for tooltip behavior
11
12
  *
@@ -17,9 +18,11 @@ import {
17
18
  useCallback,
18
19
  useEffect,
19
20
  useRef,
21
+ useState,
20
22
  type ReactNode,
21
23
  type RefCallback,
22
24
  } from 'react';
25
+ import {createTriggerFocusGate} from '../utils/triggerFocus';
23
26
  import * as stylex from '@stylexjs/stylex';
24
27
  import {
25
28
  useLayerInternal,
@@ -216,29 +219,25 @@ export interface TooltipReturn {
216
219
  children: ReactNode,
217
220
  props?: Omit<ContextRenderProps, 'positioning'>,
218
221
  ) => ReactNode;
219
- }
220
222
 
221
- /**
222
- * Check if an element is naturally focusable
223
- */
224
- function isFocusable(element: HTMLElement): boolean {
225
- // Elements with explicit tabindex
226
- if (element.hasAttribute('tabindex')) {
227
- return element.tabIndex >= 0;
228
- }
229
-
230
- // Naturally focusable elements
231
- const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
232
- if (focusableTags.includes(element.tagName)) {
233
- return !(element as HTMLButtonElement).disabled;
234
- }
235
-
236
- // Elements with contenteditable
237
- if (element.isContentEditable) {
238
- return true;
239
- }
240
-
241
- return false;
223
+ /**
224
+ * Opens the tooltip now and keeps it open until `hide()`, Escape, a press
225
+ * outside, or focus leaving its trigger, as a pinned tooltip does. Its text
226
+ * is announced once. Reports through `onShow`. Under a controlled `isOpen`,
227
+ * it calls `onShow` and does not change `isOpen`. Does nothing while
228
+ * `isEnabled` is false.
229
+ *
230
+ * Use `show()` and `hide()` to build a toggle-style trigger: your own button
231
+ * calls them, sets `aria-describedby` and `aria-controls` to `describedBy`
232
+ * and `aria-expanded` (true while shown), and keeps its own accessible name.
233
+ */
234
+ show: () => void;
235
+
236
+ /**
237
+ * Closes the tooltip now. Reports through `onHide`. Under a controlled
238
+ * `isOpen`, it calls `onHide` and does not change `isOpen`.
239
+ */
240
+ hide: () => void;
242
241
  }
243
242
 
244
243
  /**
@@ -375,6 +374,9 @@ export function useTooltipWithTriggerBehavior(
375
374
  isHeldOpen: isPressHeldOpen,
376
375
  attach: attachPressPin,
377
376
  unpin: unpinPress,
377
+ hold: holdPress,
378
+ release: releasePress,
379
+ isAppHeld,
378
380
  isPinShown,
379
381
  touch: {
380
382
  isTouchPointerRef,
@@ -485,32 +487,13 @@ export function useTooltipWithTriggerBehavior(
485
487
  [isTouchPointerRef, layerId, scheduleHide],
486
488
  );
487
489
 
488
- // Under `auto`, whether focus counts is decided when it arrives, not when
489
- // the listeners attach: a roving-tabindex member that was `tabindex="-1"`
490
- // then can be the tab stop now. A trigger that receives focus is focusable
491
- // by definition; focus inside it counts only while the trigger is
492
- // focusable too, so a plain wrapper still ignores its children's focus.
493
- const isFocusForTrigger = useCallback(
494
- (e: Event): boolean => {
495
- if (focusTrigger === 'always') {
496
- return true;
497
- }
498
- const triggerEl = e.currentTarget as HTMLElement | null;
499
- return (
500
- triggerEl != null && (e.target === triggerEl || isFocusable(triggerEl))
501
- );
502
- },
503
- [focusTrigger],
504
- );
505
-
506
- // Whether the trigger's current focus counted when it arrived, so its blur
507
- // hides the tooltip even if the trigger has since left the tab order.
508
- const focusCountedRef = useRef(false);
490
+ // Under `auto`, whether focus counts is decided when it arrives, and a
491
+ // focus that counted still hides on blur (utils/triggerFocus.ts).
492
+ const [focusGate] = useState(createTriggerFocusGate);
509
493
 
510
494
  const handleFocusIn = useCallback(
511
495
  (e: Event) => {
512
- focusCountedRef.current = isFocusForTrigger(e);
513
- if (!isEnabled || !focusCountedRef.current) {
496
+ if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
514
497
  return;
515
498
  }
516
499
  // A tap focuses the trigger it activates, and `:focus-visible` does not
@@ -531,8 +514,9 @@ export function useTooltipWithTriggerBehavior(
531
514
  showLayer();
532
515
  },
533
516
  [
517
+ focusGate,
518
+ focusTrigger,
534
519
  isEnabled,
535
- isFocusForTrigger,
536
520
  isTouchInteraction,
537
521
  clearTimeouts,
538
522
  showLayer,
@@ -544,13 +528,12 @@ export function useTooltipWithTriggerBehavior(
544
528
  // which a held tooltip skips.
545
529
  const handleFocusOut = useCallback(
546
530
  (e: Event) => {
547
- if (!focusCountedRef.current && !isFocusForTrigger(e)) {
531
+ if (!focusGate.focusOut(e, focusTrigger)) {
548
532
  return;
549
533
  }
550
- focusCountedRef.current = false;
551
534
  scheduleHide();
552
535
  },
553
- [isFocusForTrigger, scheduleHide],
536
+ [focusGate, focusTrigger, scheduleHide],
554
537
  );
555
538
 
556
539
  // Pressing the trigger hides its own tooltip: once the control is activated
@@ -562,9 +545,10 @@ export function useTooltipWithTriggerBehavior(
562
545
  // tooltip at all), so the touch path answers it first.
563
546
  const handlePointerDown = useCallback(
564
547
  (event: PointerEvent) => {
565
- // A press on a toggle trigger pins or closes through its click. It
566
- // neither hides the preview here nor waits for a tap verdict.
567
- if (isToggleTrigger(triggerRef.current)) {
548
+ // A toggle trigger's press pins or closes through its click. The app's
549
+ // hide() closes a held tooltip. Neither path hides here or waits for a
550
+ // tap verdict.
551
+ if (isToggleTrigger(triggerRef.current) || isAppHeld()) {
568
552
  return;
569
553
  }
570
554
  if (handleTouchPointerDown(event)) {
@@ -576,7 +560,14 @@ export function useTooltipWithTriggerBehavior(
576
560
  clearTimeouts();
577
561
  hideLayer();
578
562
  },
579
- [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
563
+ [
564
+ isToggleTrigger,
565
+ isAppHeld,
566
+ handleTouchPointerDown,
567
+ isOpen,
568
+ clearTimeouts,
569
+ hideLayer,
570
+ ],
580
571
  );
581
572
 
582
573
  // Interaction ref that handles event listeners only
@@ -609,7 +600,7 @@ export function useTooltipWithTriggerBehavior(
609
600
  el.addEventListener('pointerdown', handlePointerDown);
610
601
 
611
602
  // Focus listeners unless focus never opens the tooltip; `auto` decides
612
- // per event (isFocusForTrigger).
603
+ // per event (utils/triggerFocus.ts).
613
604
  if (focusTrigger !== 'never') {
614
605
  el.addEventListener('focusin', handleFocusIn);
615
606
  el.addEventListener('focusout', handleFocusOut);
@@ -665,9 +656,11 @@ export function useTooltipWithTriggerBehavior(
665
656
  showLayer();
666
657
  } else {
667
658
  clearTimeouts();
659
+ // A pin or app hold ends when the consumer closes the tooltip.
660
+ unpinPress();
668
661
  hideLayer();
669
662
  }
670
- }, [isOpen, clearTimeouts, showLayer, hideLayer]);
663
+ }, [isOpen, clearTimeouts, showLayer, hideLayer, unpinPress]);
671
664
 
672
665
  // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
673
666
  // stack. A visible tip is the top-most layer, so it takes the press and
@@ -763,6 +756,16 @@ export function useTooltipWithTriggerBehavior(
763
756
  ],
764
757
  );
765
758
 
759
+ const show = useCallback(() => {
760
+ clearTimeouts();
761
+ holdPress();
762
+ }, [clearTimeouts, holdPress]);
763
+
764
+ const hide = useCallback(() => {
765
+ clearTimeouts();
766
+ releasePress();
767
+ }, [clearTimeouts, releasePress]);
768
+
766
769
  return {
767
770
  ref,
768
771
  positionRef: layerRef,
@@ -770,5 +773,7 @@ export function useTooltipWithTriggerBehavior(
770
773
  anchorId: layerAnchorId,
771
774
  describedBy: layerId,
772
775
  renderTooltip,
776
+ show,
777
+ hide,
773
778
  };
774
779
  }
@@ -43,7 +43,8 @@ export const docs = {
43
43
  {
44
44
  name: 'group',
45
45
  type: 'string',
46
- description: 'Group label for grouping items visually.',
46
+ description:
47
+ 'This prop has no effect. Set `item.auxiliaryData.group` on search-source items to group results in Typeahead or BaseTypeahead.',
47
48
  },
48
49
  ],
49
50
  };
@@ -79,7 +80,8 @@ export const docsZh = {
79
80
  {
80
81
  name: 'group',
81
82
  type: 'string',
82
- description: '用于视觉分组的分组标签。',
83
+ description:
84
+ '此属性不影响渲染。要在 Typeahead 或 BaseTypeahead 中分组,请在搜索源返回的结果项上设置 `item.auxiliaryData.group`。',
83
85
  },
84
86
  ],
85
87
  };
@@ -94,6 +96,7 @@ export const docsDense = {
94
96
  icon: 'Icon/avatar before label.',
95
97
  description: 'Text below label.',
96
98
  isDisabled: 'Visually disabled.',
97
- group: 'Group label for visual grouping.',
99
+ group:
100
+ 'No effect. Group results via `item.auxiliaryData.group` in the search source.',
98
101
  },
99
102
  };
@@ -54,7 +54,8 @@ export interface TypeaheadItemProps<
54
54
  isDisabled?: boolean;
55
55
 
56
56
  /**
57
- * Group label for grouping items visually.
57
+ * This prop has no effect. Set `item.auxiliaryData.group` on search-source
58
+ * items to group results in Typeahead or BaseTypeahead.
58
59
  */
59
60
  group?: string;
60
61
  }
@@ -0,0 +1,153 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').HookDoc} */
4
+ export const docs = {
5
+ name: 'createAnimator',
6
+ displayName: 'createAnimator',
7
+ // A factory documented as a hook: listed with the utilities, beside its
8
+ // hook, not as a tile in the components gallery.
9
+ group: 'Utilities',
10
+ keywords: [
11
+ 'animate',
12
+ 'animation',
13
+ 'animator',
14
+ 'spring',
15
+ 'decay',
16
+ 'momentum',
17
+ 'fling',
18
+ 'motion',
19
+ 'transform',
20
+ 'opacity',
21
+ 'vanilla',
22
+ 'factory',
23
+ ],
24
+ params: [
25
+ {
26
+ name: 'element',
27
+ type: 'HTMLElement',
28
+ description:
29
+ 'The element to animate. The animator writes its `translate`, `scale`, `rotate` and `opacity`, and while it moves an inline `will-change` for them, merged with any it already has and restored 500 ms after its last motion; nothing else, so lay it out and style it as usual. Use one animator per element: two on one element overwrite each other.',
30
+ required: true,
31
+ },
32
+ ],
33
+ returns: [
34
+ {
35
+ name: 'animate',
36
+ type: '(target: {x?, y?, scale?, rotate?, opacity?}, options?: {velocity?}) => Promise<void>',
37
+ description:
38
+ "Springs the given channels to `target` from wherever they are on screen, on the state-change motion Astryx's components use, and resolves when they arrive (or as soon as a later call takes them over). `x` and `y` are px, `scale` is 1 at the element's size, `rotate` is degrees and `opacity` runs from 0 to 1. Pass `velocity` (units per second, such as a drag's release velocity) to start with it; without it a channel keeps the velocity it has on screen, so interrupting a motion never jumps.",
39
+ },
40
+ {
41
+ name: 'decay',
42
+ type: '(velocity: {x?, y?, scale?, rotate?, opacity?}) => Promise<void>',
43
+ description:
44
+ "Coasts the given channels from a release velocity in their units per second, slowing as a scroll view's momentum does, and resolves when they stop (or as soon as a later call takes any of them over); opacity stops at 0 or 1. The distance follows from the velocity: use it to fling something away, then remove or reset it.",
45
+ },
46
+ {
47
+ name: 'set',
48
+ type: '(values: {x?, y?, scale?, rotate?, opacity?}) => void',
49
+ description:
50
+ 'Puts the given channels at these values at once, ending their motion: follow a finger with it, frame by frame.',
51
+ },
52
+ {
53
+ name: 'get',
54
+ type: '() => {x, y, scale, rotate, opacity}',
55
+ description: "Every channel's value on screen now.",
56
+ },
57
+ {
58
+ name: 'getVelocity',
59
+ type: '() => {x, y, scale, rotate, opacity}',
60
+ description:
61
+ "Every channel's velocity on screen now, in units per second.",
62
+ },
63
+ {
64
+ name: 'stop',
65
+ type: '() => void',
66
+ description: 'Halts every channel where it is on screen.',
67
+ },
68
+ {
69
+ name: 'destroy',
70
+ type: '() => void',
71
+ description:
72
+ 'Stops every motion and lets the element go; the element keeps the values it shows. Call it when you remove the element or no longer animate it.',
73
+ },
74
+ ],
75
+ usage: {
76
+ description:
77
+ "Animates one element with the motion Astryx's own components use, without React. `animate` springs an element to new values on the state-change motion, `decay` flings it with the momentum of a released scroll view, and `set` moves it directly, so a card can follow a finger, snap back and be thrown away. Use the `useAnimator` hook in React. To animate an area's layout as its items change, use `useAnimatedLayout`; for what a component already animates, such as a sheet's detents or a carousel's snapping, use the component's own props.",
78
+ bestPractices: [
79
+ {
80
+ guidance: true,
81
+ description:
82
+ 'Start every `animate` that follows a drag with the release velocity, so the element carries on as it was thrown.',
83
+ },
84
+ {
85
+ guidance: true,
86
+ description:
87
+ 'Reach every state an animation shows without the animation too: a key, a button or a menu item that calls the same code.',
88
+ },
89
+ {
90
+ guidance: true,
91
+ description:
92
+ '`await` the promise before removing an element you animate out, and call `destroy` once it is gone.',
93
+ },
94
+ {
95
+ guidance: false,
96
+ description:
97
+ 'Read the element\u2019s position from layout while it moves: `get` gives the value on screen, wherever the motion runs.',
98
+ },
99
+ ],
100
+ accessibility: [
101
+ {
102
+ name: 'Keyboard and assistive technology',
103
+ category: 'Keyboard',
104
+ description:
105
+ 'An animator moves an element; it adds no way to act. Give every action an animation stands for a control a keyboard and a screen reader can reach, such as a button that discards a card, and have it call `animate`, which Reduce Motion turns into a fade in place. Keep `decay` for a throw the person made: Reduce Motion keeps the momentum of a coast, as it continues that throw. Keep focus on an element that stays on screen: move it before you fling its element away.',
106
+ },
107
+ {
108
+ name: 'Reduce Motion',
109
+ category: 'Content',
110
+ criterion: '2.3.3 Animation from Interactions',
111
+ description:
112
+ 'When the person asks for reduced motion, every call is planned for them. On a touch screen a move or a scale becomes a short opacity cross-fade: the element fades out where it was and fades back in where it lands. With a mouse it lands at once. A decay of `x` and `y` keeps its momentum, as it continues the throw the person made; a decay of `scale`, `rotate` or `opacity` is planned like a move. No option turns this off.',
113
+ },
114
+ ],
115
+ },
116
+ relatedHooks: ['useAnimator', 'useAnimatedLayout'],
117
+ importPath: '@astryxdesign/core',
118
+ category: 'interaction',
119
+ };
120
+
121
+ /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
122
+ export const docsDense = {
123
+ description:
124
+ "Animates one element (x, y, scale, rotate, opacity) with Astryx's motion, without React.",
125
+ paramDescriptions: {
126
+ element: 'The element to animate; one animator per element.',
127
+ },
128
+ returnDescriptions: {
129
+ animate:
130
+ '(target, {velocity?}) => Promise<void>; springs on the state-change motion.',
131
+ decay:
132
+ '({x?, y?, scale?, rotate?, opacity?}) => Promise<void>; coasts from a release velocity.',
133
+ set: '(values) => void; jumps, ending motion.',
134
+ get: '() => every value on screen.',
135
+ getVelocity: '() => every velocity on screen.',
136
+ stop: '() => void; halts where it is.',
137
+ destroy: '() => void; lets the element go.',
138
+ },
139
+ usage: {
140
+ description:
141
+ 'Spring with animate, fling with decay, follow a finger with set. Reduce Motion: a cross-fade on touch, at once with a mouse; decay keeps its momentum.',
142
+ bestPractices: [
143
+ {
144
+ guidance: true,
145
+ description: 'Pass the release velocity to animate after a drag.',
146
+ },
147
+ {
148
+ guidance: false,
149
+ description: 'Read layout for the position mid-motion; use get.',
150
+ },
151
+ ],
152
+ },
153
+ };