@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.
- package/LICENSE +21 -0
- package/README.md +304 -2
- package/package.json +437 -4
- package/src/autocomplete.tsx +581 -0
- package/src/breadcrumbs.tsx +297 -0
- package/src/button.tsx +468 -0
- package/src/calendar.tsx +2316 -0
- package/src/checkbox.tsx +732 -0
- package/src/collections.ts +1059 -0
- package/src/color.ts +2119 -0
- package/src/colorpicker.tsx +2023 -0
- package/src/colorswatchpicker.tsx +240 -0
- package/src/combobox.tsx +3003 -0
- package/src/command.tsx +1203 -0
- package/src/date.ts +674 -0
- package/src/datefield.tsx +2066 -0
- package/src/datepicker.tsx +907 -0
- package/src/dialog.tsx +1077 -0
- package/src/disclosure.tsx +711 -0
- package/src/dnd/clipboard.ts +125 -0
- package/src/dnd/collection.ts +1265 -0
- package/src/dnd/data.ts +409 -0
- package/src/dnd/drag-drop.ts +801 -0
- package/src/dnd/index.ts +133 -0
- package/src/dnd/manager.ts +639 -0
- package/src/dnd/strings.ts +1279 -0
- package/src/dnd/targets.ts +726 -0
- package/src/dnd/types.ts +212 -0
- package/src/dom.ts +703 -0
- package/src/drag-and-drop.tsx +669 -0
- package/src/drawer.ts +674 -0
- package/src/dropzone.tsx +208 -0
- package/src/file-trigger.tsx +103 -0
- package/src/focus.ts +1370 -0
- package/src/form.tsx +94 -0
- package/src/gridlist.tsx +1354 -0
- package/src/group.tsx +146 -0
- package/src/i18n.ts +823 -0
- package/src/index.ts +1672 -0
- package/src/interactions/description.ts +73 -0
- package/src/interactions/flags.ts +35 -0
- package/src/interactions/focus-events.ts +226 -0
- package/src/interactions/focusable.ts +86 -0
- package/src/interactions/hover.ts +213 -0
- package/src/interactions/interact-outside.ts +123 -0
- package/src/interactions/keyboard.ts +298 -0
- package/src/interactions/listeners.ts +78 -0
- package/src/interactions/long-press.ts +160 -0
- package/src/interactions/modality.ts +428 -0
- package/src/interactions/move.ts +257 -0
- package/src/interactions/open-link.ts +226 -0
- package/src/interactions/press.ts +915 -0
- package/src/interactions/prevent-focus.ts +102 -0
- package/src/interactions/scroll-wheel.ts +43 -0
- package/src/interactions/text-selection.ts +77 -0
- package/src/interactions.ts +81 -0
- package/src/label.ts +140 -0
- package/src/link.tsx +477 -0
- package/src/listbox.tsx +1247 -0
- package/src/live.ts +208 -0
- package/src/menu.tsx +2383 -0
- package/src/menubar.tsx +579 -0
- package/src/navigation-tree.tsx +357 -0
- package/src/navigation.ts +735 -0
- package/src/numberfield.tsx +942 -0
- package/src/otp.ts +430 -0
- package/src/overlay-arrow.tsx +157 -0
- package/src/overlays.ts +1549 -0
- package/src/platform.ts +75 -0
- package/src/presence.ts +164 -0
- package/src/preview-trigger.tsx +582 -0
- package/src/progress-bar-context.ts +15 -0
- package/src/questionnaire.tsx +1717 -0
- package/src/radio.tsx +641 -0
- package/src/register-dom.ts +12 -0
- package/src/scroller.ts +1165 -0
- package/src/select.tsx +1745 -0
- package/src/selection-indicator.tsx +74 -0
- package/src/selection.ts +1472 -0
- package/src/shared-element-transition.tsx +316 -0
- package/src/sheet.tsx +1461 -0
- package/src/slider.tsx +1137 -0
- package/src/splitter.ts +1152 -0
- package/src/static-collection.ts +211 -0
- package/src/switch.tsx +212 -0
- package/src/table.tsx +2218 -0
- package/src/tabs.tsx +1127 -0
- package/src/tag.tsx +637 -0
- package/src/textarea.tsx +186 -0
- package/src/textfield.tsx +483 -0
- package/src/toast-components.tsx +589 -0
- package/src/toast.ts +658 -0
- package/src/toggle-button-group.tsx +175 -0
- package/src/toggle-input.tsx +86 -0
- package/src/toggle.ts +384 -0
- package/src/togglegroup.ts +365 -0
- package/src/tokenfield.tsx +1673 -0
- package/src/toolbar.tsx +184 -0
- package/src/tooltip.tsx +674 -0
- package/src/tree.tsx +2075 -0
- package/src/utils.ts +787 -0
- package/src/validation.ts +504 -0
- package/src/virtualizer.tsx +837 -0
package/src/tooltip.tsx
ADDED
|
@@ -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
|
+
}
|