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

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