@barqjs/aria 0.0.0-stage → 0.2.0-next.1

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 (103) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +304 -2
  3. package/package.json +437 -4
  4. package/src/autocomplete.tsx +581 -0
  5. package/src/breadcrumbs.tsx +297 -0
  6. package/src/button.tsx +468 -0
  7. package/src/calendar.tsx +2316 -0
  8. package/src/checkbox.tsx +732 -0
  9. package/src/collections.ts +1059 -0
  10. package/src/color.ts +2119 -0
  11. package/src/colorpicker.tsx +2023 -0
  12. package/src/colorswatchpicker.tsx +240 -0
  13. package/src/combobox.tsx +3003 -0
  14. package/src/command.tsx +1203 -0
  15. package/src/date.ts +674 -0
  16. package/src/datefield.tsx +2066 -0
  17. package/src/datepicker.tsx +907 -0
  18. package/src/dialog.tsx +1077 -0
  19. package/src/disclosure.tsx +711 -0
  20. package/src/dnd/clipboard.ts +125 -0
  21. package/src/dnd/collection.ts +1265 -0
  22. package/src/dnd/data.ts +409 -0
  23. package/src/dnd/drag-drop.ts +801 -0
  24. package/src/dnd/index.ts +133 -0
  25. package/src/dnd/manager.ts +639 -0
  26. package/src/dnd/strings.ts +1279 -0
  27. package/src/dnd/targets.ts +726 -0
  28. package/src/dnd/types.ts +212 -0
  29. package/src/dom.ts +703 -0
  30. package/src/drag-and-drop.tsx +669 -0
  31. package/src/drawer.ts +674 -0
  32. package/src/dropzone.tsx +208 -0
  33. package/src/file-trigger.tsx +103 -0
  34. package/src/focus.ts +1370 -0
  35. package/src/form.tsx +94 -0
  36. package/src/gridlist.tsx +1354 -0
  37. package/src/group.tsx +146 -0
  38. package/src/i18n.ts +823 -0
  39. package/src/index.ts +1672 -0
  40. package/src/interactions/description.ts +73 -0
  41. package/src/interactions/flags.ts +35 -0
  42. package/src/interactions/focus-events.ts +226 -0
  43. package/src/interactions/focusable.ts +86 -0
  44. package/src/interactions/hover.ts +213 -0
  45. package/src/interactions/interact-outside.ts +123 -0
  46. package/src/interactions/keyboard.ts +298 -0
  47. package/src/interactions/listeners.ts +78 -0
  48. package/src/interactions/long-press.ts +160 -0
  49. package/src/interactions/modality.ts +428 -0
  50. package/src/interactions/move.ts +257 -0
  51. package/src/interactions/open-link.ts +226 -0
  52. package/src/interactions/press.ts +915 -0
  53. package/src/interactions/prevent-focus.ts +102 -0
  54. package/src/interactions/scroll-wheel.ts +43 -0
  55. package/src/interactions/text-selection.ts +77 -0
  56. package/src/interactions.ts +81 -0
  57. package/src/label.ts +140 -0
  58. package/src/link.tsx +477 -0
  59. package/src/listbox.tsx +1247 -0
  60. package/src/live.ts +208 -0
  61. package/src/menu.tsx +2383 -0
  62. package/src/menubar.tsx +579 -0
  63. package/src/navigation-tree.tsx +357 -0
  64. package/src/navigation.ts +735 -0
  65. package/src/numberfield.tsx +942 -0
  66. package/src/otp.ts +430 -0
  67. package/src/overlay-arrow.tsx +157 -0
  68. package/src/overlays.ts +1549 -0
  69. package/src/platform.ts +75 -0
  70. package/src/presence.ts +164 -0
  71. package/src/preview-trigger.tsx +582 -0
  72. package/src/progress-bar-context.ts +15 -0
  73. package/src/questionnaire.tsx +1717 -0
  74. package/src/radio.tsx +641 -0
  75. package/src/register-dom.ts +12 -0
  76. package/src/scroller.ts +1165 -0
  77. package/src/select.tsx +1745 -0
  78. package/src/selection-indicator.tsx +74 -0
  79. package/src/selection.ts +1472 -0
  80. package/src/shared-element-transition.tsx +316 -0
  81. package/src/sheet.tsx +1461 -0
  82. package/src/slider.tsx +1137 -0
  83. package/src/splitter.ts +1152 -0
  84. package/src/static-collection.ts +211 -0
  85. package/src/switch.tsx +212 -0
  86. package/src/table.tsx +2218 -0
  87. package/src/tabs.tsx +1127 -0
  88. package/src/tag.tsx +637 -0
  89. package/src/textarea.tsx +186 -0
  90. package/src/textfield.tsx +483 -0
  91. package/src/toast-components.tsx +589 -0
  92. package/src/toast.ts +658 -0
  93. package/src/toggle-button-group.tsx +175 -0
  94. package/src/toggle-input.tsx +86 -0
  95. package/src/toggle.ts +384 -0
  96. package/src/togglegroup.ts +365 -0
  97. package/src/tokenfield.tsx +1673 -0
  98. package/src/toolbar.tsx +184 -0
  99. package/src/tooltip.tsx +674 -0
  100. package/src/tree.tsx +2075 -0
  101. package/src/utils.ts +787 -0
  102. package/src/validation.ts +504 -0
  103. package/src/virtualizer.tsx +837 -0
@@ -0,0 +1,674 @@
1
+ /**
2
+ * Tooltips: a short description that appears on hover or keyboard focus.
3
+ *
4
+ * The timing is the whole design, and it is shared between every tooltip on
5
+ * the page rather than owned by each one. The first tooltip waits — a pointer
6
+ * crossing a toolbar on its way somewhere else must not leave a trail of
7
+ * popups. Once one has appeared the group is WARM, so the next appears at
8
+ * once, which is what makes a row of icon buttons readable. A pause anywhere
9
+ * cools the group down again.
10
+ *
11
+ * Two things a tooltip is not:
12
+ *
13
+ * - It is not a label. `aria-describedby` is the relationship, so the trigger
14
+ * keeps its own name and gains a description; `aria-labelledby` would
15
+ * replace the name with the tooltip's text.
16
+ * - It is not reachable. A tooltip contains no interactive content and takes
17
+ * no focus, which is why it can vanish on blur without stranding anyone.
18
+ *
19
+ * A touch user has neither hover nor focus, so a tooltip is invisible to them
20
+ * by design. Anything a touch user must be able to read belongs in the
21
+ * interface, not in a tooltip.
22
+ */
23
+
24
+ import {
25
+ cells,
26
+ type Accessor,
27
+ type Child,
28
+ createContext,
29
+ createEffect,
30
+ getContext,
31
+ getOwner,
32
+ type Incoming,
33
+ onCleanup,
34
+ provide,
35
+ Show,
36
+ createSignal,
37
+ } from "@barqjs/core";
38
+ import { isServer, Portal } from "@barqjs/web";
39
+ import { ref as makeRef, mergeRefs, type RefTarget } from "@barqjs/primitives/refs";
40
+ import { ownerDocument } from "./dom.ts";
41
+ import { useLocale } from "./i18n.ts";
42
+ import { focusable } from "./interactions/focusable.ts";
43
+ import { hover } from "./interactions/hover.ts";
44
+ import { getInteractionModality, isFocusVisible, trackModality } from "./interactions/modality.ts";
45
+ import type { ElementRef } from "./interactions/press.ts";
46
+ import { OverlayArrowProvider } from "./overlay-arrow.tsx";
47
+ import {
48
+ alignOf,
49
+ followOpen,
50
+ overlayPosition,
51
+ overlayTriggerState,
52
+ portalContainer,
53
+ usePortalTarget,
54
+ type OverlayTriggerState,
55
+ type OverlayTriggerStateOptions,
56
+ type Placement,
57
+ } from "./overlays.ts";
58
+ import {
59
+ access,
60
+ type DOMProps,
61
+ filterDOMProps,
62
+ fromProps,
63
+ id,
64
+ type MaybeAccessor,
65
+ clearTriggerSlot,
66
+ mergeProps,
67
+ provideTriggerSlot,
68
+ type StyleProps,
69
+ styleProps,
70
+ } from "./utils.ts";
71
+
72
+ // ---------------------------------------------------------------------------
73
+ // State
74
+ // ---------------------------------------------------------------------------
75
+
76
+ /** How long the FIRST tooltip in a group waits before appearing. */
77
+ const WARM_UP = 1500;
78
+ /** How long the group stays warm after the last tooltip goes away. */
79
+ const COOL_DOWN = 500;
80
+
81
+ /**
82
+ * Every mounted tooltip, so one appearing can take the others away.
83
+ *
84
+ * Two tooltips on screen at once is always a bug: the pointer is over one
85
+ * trigger, and the other is a leftover from the one it just left.
86
+ */
87
+ const openTooltips = new Map<number, (immediate?: boolean) => void>();
88
+ let nextTooltip = 0;
89
+ let warm = false;
90
+ let warmUpTimer: ReturnType<typeof setTimeout> | null = null;
91
+ let coolDownTimer: ReturnType<typeof setTimeout> | null = null;
92
+
93
+ function clearTimer(timer: ReturnType<typeof setTimeout> | null): null {
94
+ if (timer !== null) clearTimeout(timer);
95
+ return null;
96
+ }
97
+
98
+ /**
99
+ * Forget the shared warm-up state.
100
+ *
101
+ * A test that leaves the group warm makes the next one measure a delay that
102
+ * is not there. Nothing in an application needs this.
103
+ */
104
+ export function resetTooltipWarmup(): void {
105
+ warmUpTimer = clearTimer(warmUpTimer);
106
+ coolDownTimer = clearTimer(coolDownTimer);
107
+ warm = false;
108
+ openTooltips.clear();
109
+ }
110
+
111
+ export interface TooltipTriggerStateOptions extends OverlayTriggerStateOptions {
112
+ /** How long the first tooltip waits. @default 1500 */
113
+ delay?: MaybeAccessor<number | undefined>;
114
+ /** How long it stays after the pointer leaves. @default 500 */
115
+ closeDelay?: MaybeAccessor<number | undefined>;
116
+ /**
117
+ * How long after this tooltip goes the next one may still appear at once.
118
+ *
119
+ * Counted from the moment it is gone, so a tooltip that lingers for its
120
+ * close delay does not use the window up while it is still on screen. Zero
121
+ * means every tooltip waits.
122
+ *
123
+ * @default 500, or the close delay when that is longer
124
+ */
125
+ skipDelay?: MaybeAccessor<number | undefined>;
126
+ }
127
+
128
+ export interface TooltipTriggerState extends Omit<OverlayTriggerState, "open" | "close"> {
129
+ /**
130
+ * Whether the tooltip showing now skipped its entrance animation.
131
+ *
132
+ * True when it opened while the group was warm: swapping between two
133
+ * triggers is one tooltip moving, not one fading in after another. Never
134
+ * true once it is closing, since the exit plays either way, as Base UI's
135
+ * under shadcn's classes does.
136
+ */
137
+ shouldSkipAnimation: Accessor<boolean>;
138
+ /**
139
+ * Whether it opened without waiting: from the keyboard, or while the group
140
+ * was warm. A pointer that waited out the delay, however short, did not.
141
+ */
142
+ isInstant: Accessor<boolean>;
143
+ open(immediate?: boolean): void;
144
+ close(immediate?: boolean): void;
145
+ }
146
+
147
+ /** Whether a tooltip is showing, and the shared timing that decides when. */
148
+ export function tooltipTriggerState(options: TooltipTriggerStateOptions = {}): TooltipTriggerState {
149
+ const overlay = overlayTriggerState(options);
150
+ const [skipAnimation, setSkipAnimation] = createSignal(false);
151
+ const [isInstant, setInstant] = createSignal(false);
152
+ const key = nextTooltip++;
153
+
154
+ const delay = (): number => access(options.delay) ?? WARM_UP;
155
+ const closeDelay = (): number => access(options.closeDelay) ?? COOL_DOWN;
156
+
157
+ let closeTimer: ReturnType<typeof setTimeout> | null = null;
158
+
159
+ const closeOthers = (): void => {
160
+ for (const [other, hide] of openTooltips) {
161
+ if (other === key) continue;
162
+ hide(true);
163
+ openTooltips.delete(other);
164
+ }
165
+ };
166
+
167
+ const show = (instant: boolean): void => {
168
+ closeTimer = clearTimer(closeTimer);
169
+ closeOthers();
170
+ openTooltips.set(key, hide);
171
+ setSkipAnimation(instant);
172
+ warm = true;
173
+ overlay.open();
174
+ warmUpTimer = clearTimer(warmUpTimer);
175
+ coolDownTimer = clearTimer(coolDownTimer);
176
+ };
177
+
178
+ const hide = (immediate?: boolean): void => {
179
+ if (immediate === true || closeDelay() <= 0) {
180
+ closeTimer = clearTimer(closeTimer);
181
+ overlay.close();
182
+ } else if (closeTimer === null) {
183
+ closeTimer = setTimeout(() => {
184
+ closeTimer = null;
185
+ overlay.close();
186
+ }, closeDelay());
187
+ }
188
+
189
+ warmUpTimer = clearTimer(warmUpTimer);
190
+ if (!warm) return;
191
+
192
+ const lingers = immediate === true ? 0 : Math.max(0, closeDelay());
193
+ const skipDelay = access(options.skipDelay);
194
+ const window = skipDelay === undefined ? Math.max(COOL_DOWN, lingers) : lingers + skipDelay;
195
+
196
+ coolDownTimer = clearTimer(coolDownTimer);
197
+ if (window <= 0) {
198
+ openTooltips.delete(key);
199
+ warm = false;
200
+ return;
201
+ }
202
+ coolDownTimer = setTimeout(() => {
203
+ openTooltips.delete(key);
204
+ coolDownTimer = null;
205
+ warm = false;
206
+ }, window);
207
+ };
208
+
209
+ const warmUp = (): void => {
210
+ closeOthers();
211
+ openTooltips.set(key, hide);
212
+
213
+ if (overlay.isOpen()) return;
214
+
215
+ if (warm) {
216
+ setInstant(true);
217
+ show(true);
218
+ return;
219
+ }
220
+
221
+ warmUpTimer = clearTimer(warmUpTimer);
222
+ warmUpTimer = setTimeout(() => {
223
+ warmUpTimer = null;
224
+ warm = true;
225
+ setInstant(false);
226
+ show(false);
227
+ }, delay());
228
+ };
229
+
230
+ if (!isServer) {
231
+ onCleanup(() => {
232
+ closeTimer = clearTimer(closeTimer);
233
+ openTooltips.delete(key);
234
+ });
235
+ }
236
+
237
+ return {
238
+ isOpen: overlay.isOpen,
239
+ setOpen: overlay.setOpen,
240
+ toggle: overlay.toggle,
241
+ shouldSkipAnimation: () => overlay.isOpen() && skipAnimation(),
242
+ isInstant,
243
+ open(immediate?: boolean) {
244
+ if (immediate !== true && delay() > 0 && closeTimer === null) {
245
+ warmUp();
246
+ return;
247
+ }
248
+ // One already showing keeps the way it arrived: the pointer reaching the
249
+ // tooltip itself, or coming back before it has gone, opens nothing.
250
+ if (!overlay.isOpen()) setInstant(immediate === true || warm);
251
+ // Focus opens at once, but only skips the animation if the group was
252
+ // already warm — otherwise the first tooltip of a session would appear
253
+ // with no transition at all.
254
+ show(warm);
255
+ },
256
+ close: hide,
257
+ };
258
+ }
259
+
260
+ // ---------------------------------------------------------------------------
261
+ // Hooks
262
+ // ---------------------------------------------------------------------------
263
+
264
+ export interface TooltipOptions {
265
+ "aria-label"?: MaybeAccessor<string | undefined>;
266
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
267
+ "aria-describedby"?: MaybeAccessor<string | undefined>;
268
+ /** Whether resting the pointer on the tooltip holds it open. @default true */
269
+ isHoverable?: MaybeAccessor<boolean | undefined>;
270
+ }
271
+
272
+ /** `closed`, `delayed-open` or `instant-open`: the three states Radix names. */
273
+ export type TooltipStateName = "closed" | "delayed-open" | "instant-open";
274
+
275
+ /** The state of a tooltip as a design system's selectors spell it. */
276
+ export function tooltipStateName(state: TooltipTriggerState): TooltipStateName {
277
+ if (!state.isOpen()) return "closed";
278
+ return state.isInstant() ? "instant-open" : "delayed-open";
279
+ }
280
+
281
+ export interface TooltipResult {
282
+ tooltipProps: DOMProps;
283
+ }
284
+
285
+ /**
286
+ * The tooltip element itself.
287
+ *
288
+ * Hovering the tooltip keeps it open: a pointer travelling from the trigger to
289
+ * a tooltip that is positioned beside it must not make it disappear on the
290
+ * way.
291
+ */
292
+ export function tooltip(options: TooltipOptions = {}, state?: TooltipTriggerState): TooltipResult {
293
+ const { hoverProps } = hover({
294
+ isDisabled: () => access(options.isHoverable) === false,
295
+ onHoverStart: () => state?.open(true),
296
+ onHoverEnd: () => state?.close(),
297
+ });
298
+
299
+ return {
300
+ tooltipProps: mergeProps(filterDOMProps(options, { labelable: true }), hoverProps, {
301
+ role: "tooltip",
302
+ "data-state": () => (state === undefined ? undefined : tooltipStateName(state)),
303
+ }),
304
+ };
305
+ }
306
+
307
+ export interface TooltipTriggerOptions {
308
+ ref: ElementRef;
309
+ isDisabled?: MaybeAccessor<boolean | undefined>;
310
+ /** Open on hover and focus, or on focus alone. @default "hover" */
311
+ trigger?: MaybeAccessor<"hover" | "focus" | undefined>;
312
+ /** @default true */
313
+ shouldCloseOnPress?: MaybeAccessor<boolean | undefined>;
314
+ }
315
+
316
+ export interface TooltipTriggerResult {
317
+ triggerProps: DOMProps;
318
+ tooltipProps: DOMProps;
319
+ }
320
+
321
+ /**
322
+ * The element a tooltip describes.
323
+ *
324
+ * Focus opens it only when the focus ring is showing. Focus that arrived from
325
+ * a click is focus the user can already see the target of, and a tooltip
326
+ * appearing under the pointer on every click is the single most common way to
327
+ * make one unbearable.
328
+ */
329
+ export function tooltipTrigger(
330
+ options: TooltipTriggerOptions,
331
+ state: TooltipTriggerState,
332
+ ): TooltipTriggerResult {
333
+ const tooltipId = id();
334
+
335
+ // Both the hover and the focus rules ask what the user last did, and nothing
336
+ // knows unless the listeners are installed.
337
+ if (!isServer) {
338
+ createEffect(
339
+ () => access(options.ref),
340
+ (element) => trackModality(element),
341
+ );
342
+ }
343
+
344
+ let hovered = false;
345
+ let focused = false;
346
+
347
+ const showIfEngaged = (): void => {
348
+ if (hovered || focused) state.open(focused);
349
+ };
350
+
351
+ const hideIfIdle = (immediate?: boolean): void => {
352
+ if (!hovered && !focused) state.close(immediate);
353
+ };
354
+
355
+ const forget = (immediate: boolean): void => {
356
+ focused = false;
357
+ hovered = false;
358
+ hideIfIdle(immediate);
359
+ };
360
+
361
+ // Escape closes it wherever focus is. A trigger pressed and then escaped
362
+ // keeps DOM focus, so without this the tooltip stays under the pointer with
363
+ // no way to dismiss it.
364
+ if (!isServer) {
365
+ followOpen(
366
+ () => (state.isOpen() ? ownerDocument(access(options.ref) as Element | null) : null),
367
+ (doc) => {
368
+ if (doc === null) return undefined;
369
+ const onKeyDown = (event: KeyboardEvent): void => {
370
+ if (event.key !== "Escape") return;
371
+ event.stopPropagation();
372
+ state.close(true);
373
+ };
374
+ doc.addEventListener("keydown", onKeyDown, true);
375
+ return () => doc.removeEventListener("keydown", onKeyDown, true);
376
+ },
377
+ );
378
+ }
379
+
380
+ const { hoverProps } = hover({
381
+ isDisabled: options.isDisabled,
382
+ onHoverStart: () => {
383
+ if (access(options.trigger) === "focus") return;
384
+ // A hover that began because something covering the trigger went away —
385
+ // a menu closing, focus moving on — is not the pointer arriving, and
386
+ // reopening the tooltip there would be a popup nobody asked for. An
387
+ // unknown modality is a real hover: the pointer may have been resting
388
+ // over the trigger since the page loaded, having moved not at all.
389
+ const modality = getInteractionModality();
390
+ hovered = modality !== "keyboard" && modality !== "virtual";
391
+ showIfEngaged();
392
+ },
393
+ onHoverEnd: () => {
394
+ if (access(options.trigger) === "focus") return;
395
+ forget(false);
396
+ },
397
+ });
398
+
399
+ // Only the handlers. `focusable` also writes a `tabIndex`, and a trigger is
400
+ // whatever it already was: an element that becomes a Tab stop merely by
401
+ // carrying a tooltip is a Tab stop that does nothing.
402
+ const { focusableProps } = focusable(
403
+ {
404
+ isDisabled: options.isDisabled,
405
+ onFocus: () => {
406
+ if (!isFocusVisible()) return;
407
+ focused = true;
408
+ showIfEngaged();
409
+ },
410
+ onBlur: () => forget(true),
411
+ },
412
+ options.ref,
413
+ );
414
+ const { tabIndex: _tabIndex, ...focusHandlers } = focusableProps;
415
+
416
+ const dismissOnPress = (): void => {
417
+ if (access(options.shouldCloseOnPress) === false) return;
418
+ forget(true);
419
+ };
420
+
421
+ return {
422
+ triggerProps: mergeProps(focusHandlers, hoverProps, {
423
+ "aria-describedby": () => (state.isOpen() ? tooltipId() : undefined),
424
+ "data-state": () => tooltipStateName(state),
425
+ onPointerDown: dismissOnPress,
426
+ onKeyDown: dismissOnPress,
427
+ }),
428
+ tooltipProps: { id: tooltipId },
429
+ };
430
+ }
431
+
432
+ // ---------------------------------------------------------------------------
433
+ // Components
434
+ // ---------------------------------------------------------------------------
435
+
436
+ export interface TooltipTriggerValue {
437
+ state: TooltipTriggerState;
438
+ triggerRef: ReturnType<typeof makeRef<HTMLElement>>;
439
+ triggerProps: DOMProps;
440
+ tooltipProps: DOMProps;
441
+ /** Whether resting the pointer on the tooltip holds it open. */
442
+ isContentHoverable: Accessor<boolean>;
443
+ }
444
+
445
+ /** The timing a {@link TooltipProvider} gives every tooltip inside it. */
446
+ export interface TooltipGroup {
447
+ delay: Accessor<number | undefined>;
448
+ skipDelay: Accessor<number | undefined>;
449
+ isContentHoverable: Accessor<boolean | undefined>;
450
+ }
451
+
452
+ const TooltipGroupContext = createContext<TooltipGroup | null>(null);
453
+
454
+ /** The enclosing {@link TooltipProvider}'s timing, if there is one. */
455
+ export function useTooltipGroup(): TooltipGroup | null {
456
+ return getContext(TooltipGroupContext) ?? null;
457
+ }
458
+
459
+ export interface TooltipProviderComponentProps {
460
+ children?: Child;
461
+ /** How long the first tooltip inside waits. @default 1500 */
462
+ delay?: number;
463
+ /** How long after one goes the next may still appear at once. @default 500 */
464
+ skipDelay?: number;
465
+ /** Whether resting the pointer on a tooltip holds it open. @default true */
466
+ isContentHoverable?: boolean;
467
+ }
468
+
469
+ /**
470
+ * One set of timings for every tooltip inside.
471
+ *
472
+ * ```tsx
473
+ * <TooltipProvider delay={300} skipDelay={200}>
474
+ * <Toolbar />
475
+ * </TooltipProvider>
476
+ * ```
477
+ *
478
+ * A tooltip works without one, and a tooltip that sets its own `delay` keeps
479
+ * it. Whether the group is WARM is still shared by the whole page rather than
480
+ * by the provider: two toolbars a pointer crosses in one movement are one
481
+ * gesture, and the second should not make it wait again.
482
+ */
483
+ export function TooltipProvider(props: Incoming<TooltipProviderComponentProps>) {
484
+ const group: TooltipGroup = {
485
+ delay: () => props.delay?.(),
486
+ skipDelay: () => props.skipDelay?.(),
487
+ isContentHoverable: () => props.isContentHoverable?.(),
488
+ };
489
+
490
+ return provide(
491
+ TooltipGroupContext,
492
+ () => group,
493
+ () => props.children as unknown,
494
+ );
495
+ }
496
+
497
+ const TooltipTriggerContext = createContext<TooltipTriggerValue | null>(null);
498
+
499
+ /** The enclosing {@link TooltipTrigger}, if there is one. */
500
+ export function useTooltipTrigger(): TooltipTriggerValue {
501
+ const value = getContext(TooltipTriggerContext);
502
+ if (value === null || value === undefined) {
503
+ throw new Error("This must be rendered inside a TooltipTrigger.");
504
+ }
505
+ return value;
506
+ }
507
+
508
+ export interface TooltipTriggerComponentProps {
509
+ children?: Child;
510
+ isOpen?: boolean;
511
+ defaultOpen?: boolean;
512
+ isDisabled?: boolean;
513
+ /** @default "hover" */
514
+ trigger?: "hover" | "focus";
515
+ /** @default 1500 */
516
+ delay?: number;
517
+ /** @default 500, or 0 when the content is not hoverable */
518
+ closeDelay?: number;
519
+ /** @default the enclosing {@link TooltipProvider}'s, then 500 */
520
+ skipDelay?: number;
521
+ /**
522
+ * Whether resting the pointer on the tooltip holds it open.
523
+ *
524
+ * @default the enclosing {@link TooltipProvider}'s, then true
525
+ */
526
+ isContentHoverable?: boolean;
527
+ /** @default true */
528
+ shouldCloseOnPress?: boolean;
529
+ onOpenChange?: (isOpen: boolean) => void;
530
+ }
531
+
532
+ /**
533
+ * A trigger and its tooltip.
534
+ *
535
+ * ```tsx
536
+ * <TooltipTrigger>
537
+ * <Button onPress={save}>Save</Button>
538
+ * <Tooltip>Saves without closing</Tooltip>
539
+ * </TooltipTrigger>
540
+ * ```
541
+ *
542
+ * The control inside takes the trigger's props for itself: `aria-describedby`
543
+ * and the focus handlers have to be on the focusable element, and a wrapper
544
+ * around it hears neither focus nor a description. A control this package does
545
+ * not provide spreads `useTooltipTrigger().triggerProps` by hand.
546
+ */
547
+ export function TooltipTrigger(props: TooltipTriggerComponentProps) {
548
+ const triggerRef = makeRef<HTMLElement>();
549
+ const options = fromProps(cells(props));
550
+ const group = useTooltipGroup();
551
+ const isContentHoverable = (): boolean =>
552
+ (props.isContentHoverable ?? group?.isContentHoverable()) !== false;
553
+ const state = tooltipTriggerState({
554
+ ...options,
555
+ delay: () => props.delay ?? group?.delay(),
556
+ skipDelay: () => props.skipDelay ?? group?.skipDelay(),
557
+ // The close delay is the time a pointer has to travel from the trigger to
558
+ // the tooltip, and with nothing to travel to it is only a tooltip that
559
+ // will not go away.
560
+ closeDelay: () => props.closeDelay ?? (isContentHoverable() ? undefined : 0),
561
+ });
562
+
563
+ const { triggerProps, tooltipProps } = tooltipTrigger(
564
+ { ...(options as unknown as TooltipTriggerOptions), ref: triggerRef },
565
+ state,
566
+ );
567
+
568
+ const value: TooltipTriggerValue = {
569
+ state,
570
+ triggerRef,
571
+ triggerProps,
572
+ tooltipProps,
573
+ isContentHoverable,
574
+ };
575
+ const owner = getOwner();
576
+ if (owner === null) return <>{props.children}</>;
577
+
578
+ // `provide`, not `install`: a component does not get a scope of its own, so
579
+ // installing on the ambient owner writes where its SIBLINGS read. Two
580
+ // tooltip triggers beside each other both ran their bodies before either
581
+ // one's children were built, and every child of both then saw the second
582
+ // one's state.
583
+ return provide(
584
+ TooltipTriggerContext,
585
+ () => value,
586
+ () => {
587
+ provideTriggerSlot({
588
+ props: triggerProps,
589
+ ref: triggerRef.set,
590
+ });
591
+ return props.children;
592
+ },
593
+ );
594
+ }
595
+
596
+ export interface TooltipComponentProps extends StyleProps {
597
+ children?: Child;
598
+ /** @default "top" */
599
+ placement?: Placement;
600
+ /** @default 8 */
601
+ offset?: number;
602
+ crossOffset?: number;
603
+ shouldFlip?: boolean;
604
+ containerPadding?: number;
605
+ /** The least distance between an arrow and the tooltip's ends. @default 0 */
606
+ arrowBoundaryOffset?: number;
607
+ ref?: RefTarget<HTMLDivElement>;
608
+ }
609
+
610
+ /**
611
+ * The tooltip, mounted only while it is showing.
612
+ *
613
+ * `data-skip-animation` marks the entrance a warm group makes: moving between
614
+ * two triggers is one tooltip changing place, and fading it in again reads as
615
+ * a flicker.
616
+ */
617
+ export function Tooltip(props: TooltipComponentProps) {
618
+ clearTriggerSlot();
619
+ const target = usePortalTarget();
620
+ const domRef = makeRef<HTMLDivElement>();
621
+ const trigger = useTooltipTrigger();
622
+ const locale = useLocale();
623
+ const placement = (): Placement => props.placement ?? "top";
624
+
625
+ const arrowRef = makeRef<Element>();
626
+ const position = overlayPosition({
627
+ targetRef: trigger.triggerRef,
628
+ overlayRef: domRef,
629
+ arrowRef,
630
+ arrowBoundaryOffset: () => props.arrowBoundaryOffset,
631
+ placement,
632
+ offset: () => props.offset ?? 8,
633
+ crossOffset: () => props.crossOffset,
634
+ shouldFlip: () => props.shouldFlip,
635
+ containerPadding: () => props.containerPadding,
636
+ isOpen: trigger.state.isOpen,
637
+ direction: () => locale().direction,
638
+ });
639
+
640
+ const { tooltipProps } = tooltip({ isHoverable: trigger.isContentHoverable }, trigger.state);
641
+
642
+ const elementProps = mergeProps(
643
+ tooltipProps,
644
+ trigger.tooltipProps,
645
+ position.overlayProps,
646
+ filterDOMProps(fromProps(cells(props)), { global: true }),
647
+ styleProps(cells(props)),
648
+ {
649
+ "data-placement": position.placement,
650
+ "data-side": position.placement,
651
+ "data-align": () => alignOf(placement()),
652
+ "data-skip-animation": trigger.state.shouldSkipAnimation,
653
+ "data-testid": () => props["data-testid"],
654
+ },
655
+ );
656
+
657
+ return (
658
+ <Show when={trigger.state.isOpen()}>
659
+ <Portal mount={portalContainer(target)}>
660
+ <div {...elementProps} ref={mergeRefs(domRef.set, props.ref)}>
661
+ <OverlayArrowProvider
662
+ value={{
663
+ placement: position.placement,
664
+ arrowProps: position.arrowProps,
665
+ ref: arrowRef.set,
666
+ }}
667
+ >
668
+ {props.children}
669
+ </OverlayArrowProvider>
670
+ </div>
671
+ </Portal>
672
+ </Show>
673
+ );
674
+ }