@zag-js/tooltip 2.0.0-next.2 → 2.0.0-next.4

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.
@@ -1,199 +1,288 @@
1
- import { Machine, EventObject, Service } from '@zag-js/core';
2
- import { PositioningOptions, Placement, PlacementSide } from '@zag-js/popper';
3
- export { Placement, PositioningOptions } from '@zag-js/popper';
4
- import { PropTypes, DirectionProperty, CommonProperties } from '@zag-js/types';
5
-
6
- interface OpenChangeDetails {
7
- open: boolean;
1
+ import { Placement, PlacementSide, PositioningOptions } from "@zag-js/popper";
2
+ import { EventObject, Machine, Service } from "@zag-js/core";
3
+ import { CommonProperties, DirectionProperty, PopupActivationDirection, PropTypes } from "@zag-js/types";
4
+ /**
5
+ * What opened or closed the tooltip:
6
+ * - `trigger-hover`: the pointer entered, or left, the trigger or content
7
+ * - `trigger-focus`: the trigger received keyboard focus
8
+ * - `trigger-blur`: the trigger lost focus
9
+ * - `trigger-click`: the trigger was pressed
10
+ * - `escape-key`: Escape was pressed
11
+ * - `scroll`: an ancestor of the trigger scrolled
12
+ * - `sibling-open`: another tooltip opened
13
+ * - `interact-outside`: the pointer was locked
14
+ * - `disabled`: the tooltip was disabled while open
15
+ * - `script`: `setOpen` was called
16
+ */
17
+ export type OpenChangeReason = "trigger-hover" | "trigger-focus" | "trigger-blur" | "trigger-click" | "escape-key" | "scroll" | "sibling-open" | "interact-outside" | "disabled" | "script";
18
+ export interface OpenChangeDetails {
19
+ open: boolean;
20
+ /**
21
+ * What opened or closed the tooltip
22
+ */
23
+ reason?: OpenChangeReason | undefined;
8
24
  }
9
- interface TriggerValueChangeDetails {
10
- /**
11
- * The value of the trigger
12
- */
13
- value: string | null;
14
- /**
15
- * The trigger element
16
- */
17
- triggerElement: HTMLElement | null;
25
+ export interface TriggerValueChangeDetails {
26
+ /**
27
+ * The value of the trigger
28
+ */
29
+ value: string | null;
30
+ /**
31
+ * The trigger element
32
+ */
33
+ triggerElement: HTMLElement | null;
18
34
  }
19
- interface ElementIds {
20
- trigger?: (string | ((value?: string) => string)) | undefined;
21
- content?: string | undefined;
22
- arrow?: string | undefined;
23
- positioner?: string | undefined;
35
+ export interface ElementIds {
36
+ trigger?: (string | ((value?: string) => string)) | undefined;
37
+ content?: string | undefined;
38
+ arrow?: string | undefined;
39
+ positioner?: string | undefined;
24
40
  }
25
- interface TooltipProps extends DirectionProperty, CommonProperties {
26
- /**
27
- * The ids of the elements in the tooltip. Useful for composition.
28
- */
29
- ids?: ElementIds | undefined;
30
- /**
31
- * The open delay of the tooltip.
32
- * @default 400
33
- */
34
- openDelay?: number | undefined;
35
- /**
36
- * The close delay of the tooltip.
37
- * @default 150
38
- */
39
- closeDelay?: number | undefined;
40
- /**
41
- * Whether to close the tooltip on pointerdown.
42
- * @default true
43
- */
44
- closeOnPointerDown?: boolean | undefined;
45
- /**
46
- * Whether to close the tooltip when the Escape key is pressed.
47
- * @default true
48
- */
49
- closeOnEscape?: boolean | undefined;
50
- /**
51
- * Whether the tooltip should close on scroll
52
- * @default true
53
- */
54
- closeOnScroll?: boolean | undefined;
55
- /**
56
- * Whether the tooltip should close on click
57
- * @default true
58
- */
59
- closeOnClick?: boolean | undefined;
60
- /**
61
- * Whether the tooltip's content is interactive.
62
- * In this mode, the tooltip will remain open when user hovers over the content.
63
- * @see https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus
64
- *
65
- * @default false
66
- */
67
- interactive?: boolean | undefined;
68
- /**
69
- * Function called when the tooltip is opened.
70
- */
71
- onOpenChange?: ((details: OpenChangeDetails) => void) | undefined;
72
- /**
73
- * Custom label for the tooltip.
74
- */
75
- "aria-label"?: string | undefined;
76
- /**
77
- * The user provided options used to position the popover content
78
- */
79
- positioning?: PositioningOptions | undefined;
80
- /**
81
- * Whether the tooltip is disabled
82
- */
83
- disabled?: boolean | undefined;
84
- /**
85
- * The controlled open state of the tooltip
86
- */
87
- open?: boolean | undefined;
41
+ export interface TooltipProps extends DirectionProperty, CommonProperties {
42
+ /**
43
+ * The ids of the elements in the tooltip. Useful for composition.
44
+ */
45
+ ids?: ElementIds | undefined;
46
+ /**
47
+ * The open delay of the tooltip.
48
+ * @default 400
49
+ */
50
+ openDelay?: number | undefined;
51
+ /**
52
+ * The close delay of the tooltip.
53
+ * @default 150
54
+ */
55
+ closeDelay?: number | undefined;
56
+ /**
57
+ * Whether to close the tooltip on pointerdown.
58
+ * @default true
59
+ */
60
+ closeOnPointerDown?: boolean | undefined;
61
+ /**
62
+ * Whether to close the tooltip when the Escape key is pressed.
63
+ * @default true
64
+ */
65
+ closeOnEscape?: boolean | undefined;
66
+ /**
67
+ * Whether the tooltip should close on scroll
68
+ * @default true
69
+ */
70
+ closeOnScroll?: boolean | undefined;
71
+ /**
72
+ * Whether the tooltip should close on click
73
+ * @default true
74
+ */
75
+ closeOnClick?: boolean | undefined;
76
+ /**
77
+ * Whether the tooltip's content is interactive.
78
+ * In this mode, the tooltip will remain open when user hovers over the content.
79
+ * @see https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus
80
+ *
81
+ * @default false
82
+ */
83
+ interactive?: boolean | undefined;
84
+ /**
85
+ * Function called when the tooltip is opened.
86
+ */
87
+ onOpenChange?: ((details: OpenChangeDetails) => void) | undefined;
88
+ /**
89
+ * Custom label for the tooltip.
90
+ */
91
+ "aria-label"?: string | undefined;
92
+ /**
93
+ * The user provided options used to position the popover content
94
+ */
95
+ positioning?: PositioningOptions | undefined;
96
+ /**
97
+ * Whether the tooltip is disabled
98
+ */
99
+ disabled?: boolean | undefined;
100
+ /**
101
+ * The controlled open state of the tooltip
102
+ */
103
+ open?: boolean | undefined;
104
+ /**
105
+ * The initial open state of the tooltip when rendered.
106
+ * Use when you don't need to control the open state of the tooltip.
107
+ */
108
+ defaultOpen?: boolean | undefined;
109
+ /**
110
+ * The controlled trigger value
111
+ */
112
+ triggerValue?: string | null | undefined;
113
+ /**
114
+ * The initial trigger value when rendered.
115
+ * Use when you don't need to control the trigger value.
116
+ */
117
+ defaultTriggerValue?: string | null | undefined;
118
+ /**
119
+ * Function called when the trigger value changes.
120
+ */
121
+ onTriggerValueChange?: ((details: TriggerValueChangeDetails) => void) | undefined;
122
+ }
123
+ type PropsWithDefault = "openDelay" | "closeDelay" | "closeOnPointerDown" | "closeOnEscape" | "closeOnScroll" | "closeOnClick" | "interactive" | "id" | "positioning";
124
+ export interface TooltipSchema {
125
+ state: "open" | "closed" | "opening" | "closing";
126
+ props: TooltipProps;
127
+ defaultPropKey: PropsWithDefault;
128
+ context: {
129
+ currentPlacement: Placement | undefined;
130
+ hasPointerMoveOpened: string | null;
131
+ isPointer: boolean;
132
+ triggerValue: string | null;
88
133
  /**
89
- * The initial open state of the tooltip when rendered.
90
- * Use when you don't need to control the open state of the tooltip.
134
+ * Where the current trigger sits relative to the previous one, after switching triggers while open
91
135
  */
92
- defaultOpen?: boolean | undefined;
136
+ activationDirection: PopupActivationDirection | null;
137
+ /** The trigger value before the last switch, kept until the switch ends */
138
+ previousTriggerValue: string | null;
93
139
  /**
94
- * The controlled trigger value
140
+ * Whether the tooltip is moving between triggers
95
141
  */
96
- triggerValue?: string | null | undefined;
142
+ transitioning: boolean;
97
143
  /**
98
- * The initial trigger value when rendered.
99
- * Use when you don't need to control the trigger value.
144
+ * Whether a viewport is rendered, with one content per trigger
100
145
  */
101
- defaultTriggerValue?: string | null | undefined;
146
+ viewportRendered: boolean;
102
147
  /**
103
- * Function called when the trigger value changes.
148
+ * The size of the current content, when the viewport is rendered
104
149
  */
105
- onTriggerValueChange?: ((details: TriggerValueChangeDetails) => void) | undefined;
150
+ viewportSize: ViewportSize | null;
151
+ };
152
+ refs: {
153
+ cancelTriggerSwitch: VoidFunction | null;
154
+ awaitingViewportSize: boolean;
155
+ };
156
+ event: EventObject;
157
+ action: string;
158
+ effect: string;
159
+ guard: string;
106
160
  }
107
- type PropsWithDefault = "openDelay" | "closeDelay" | "closeOnPointerDown" | "closeOnEscape" | "closeOnScroll" | "closeOnClick" | "interactive" | "id" | "positioning";
108
- interface TooltipSchema {
109
- state: "open" | "closed" | "opening" | "closing";
110
- props: TooltipProps;
111
- defaultPropKey: PropsWithDefault;
112
- context: {
113
- currentPlacement: Placement | undefined;
114
- hasPointerMoveOpened: string | null;
115
- isPointer: boolean;
116
- triggerValue: string | null;
117
- };
118
- event: EventObject;
119
- action: string;
120
- effect: string;
121
- guard: string;
161
+ export type TooltipService = Service<TooltipSchema>;
162
+ export type TooltipMachine = Machine<TooltipSchema>;
163
+ export interface TriggerProps {
164
+ /**
165
+ * The value that identifies this specific trigger
166
+ */
167
+ value?: string;
122
168
  }
123
- type TooltipService = Service<TooltipSchema>;
124
- type TooltipMachine = Machine<TooltipSchema>;
125
- interface TriggerProps {
126
- /**
127
- * The value that identifies this specific trigger
128
- */
129
- value?: string;
169
+ export interface TriggerState {
170
+ /**
171
+ * The value that identifies this specific trigger
172
+ */
173
+ value: string | undefined;
174
+ /**
175
+ * Whether this trigger is the one that opened the tooltip
176
+ */
177
+ current: boolean;
178
+ /**
179
+ * Whether the tooltip is open
180
+ */
181
+ open: boolean;
130
182
  }
131
- interface TriggerState {
132
- /**
133
- * The value that identifies this specific trigger
134
- */
135
- value: string | undefined;
136
- /**
137
- * Whether this trigger is the one that opened the tooltip
138
- */
139
- current: boolean;
140
- /**
141
- * Whether the tooltip is open
142
- */
143
- open: boolean;
183
+ export interface ViewportSize {
184
+ width: number;
185
+ height: number;
144
186
  }
145
- interface ContentState {
146
- /**
147
- * Whether the tooltip is open
148
- */
149
- open: boolean;
150
- /**
151
- * Whether the tooltip should skip its enter animation, following a rapid switch between triggers
152
- */
153
- instant: boolean;
154
- /**
155
- * The current placement of the content relative to the trigger
156
- */
157
- placement: Placement | undefined;
158
- /**
159
- * The side of the trigger the content is placed on
160
- */
161
- side: PlacementSide | undefined;
187
+ export interface ContentProps {
188
+ /**
189
+ * The trigger value this content belongs to. Use one content per trigger inside the viewport.
190
+ */
191
+ value?: string | undefined;
162
192
  }
163
- interface TooltipApi<T extends PropTypes = PropTypes> {
164
- /**
165
- * Whether the tooltip is open.
166
- */
167
- open: boolean;
168
- /**
169
- * Function to open the tooltip.
170
- */
171
- setOpen: (open: boolean) => void;
172
- /**
173
- * The trigger value
174
- */
175
- triggerValue: string | null;
176
- /**
177
- * Function to set the trigger value
178
- */
179
- setTriggerValue: (value: string | null) => void;
180
- /**
181
- * Function to reposition the popover
182
- */
183
- reposition: (options?: Partial<PositioningOptions>) => void;
184
- /**
185
- * Returns the state of a specific trigger, including whether it's the currently active one
186
- */
187
- getTriggerState: (props?: TriggerProps) => TriggerState;
188
- getTriggerProps: (props?: TriggerProps) => T["button"];
189
- getArrowProps: () => T["element"];
190
- getArrowTipProps: () => T["element"];
191
- getPositionerProps: () => T["element"];
192
- /**
193
- * Returns the state of the content
194
- */
195
- getContentState: () => ContentState;
196
- getContentProps: () => T["element"];
193
+ export interface ContentState {
194
+ /**
195
+ * Whether the content is shown. For a content with a `value`, whether its trigger is the current one.
196
+ */
197
+ open: boolean;
198
+ /**
199
+ * Whether the tooltip should skip its enter animation, following a rapid switch between triggers
200
+ */
201
+ instant: boolean;
202
+ /**
203
+ * The current placement of the content relative to the trigger
204
+ */
205
+ placement: Placement | undefined;
206
+ /**
207
+ * The side of the trigger the content is placed on
208
+ */
209
+ side: PlacementSide | undefined;
210
+ /**
211
+ * Where the current trigger sits relative to the previous one, e.g. `"right"` or `"left down"`.
212
+ * `null` until the tooltip switches triggers while open.
213
+ */
214
+ activationDirection: PopupActivationDirection | null;
215
+ }
216
+ export interface ViewportState {
217
+ /**
218
+ * Whether the tooltip is open
219
+ */
220
+ open: boolean;
221
+ /**
222
+ * Whether the tooltip should skip its enter animation, following a rapid switch between tooltips
223
+ */
224
+ instant: boolean;
225
+ /**
226
+ * The side of the trigger the viewport is placed on
227
+ */
228
+ side: PlacementSide | undefined;
229
+ /**
230
+ * Where the current trigger sits relative to the previous one, e.g. `"right"` or `"left down"`.
231
+ * `null` until the tooltip switches triggers while open.
232
+ */
233
+ activationDirection: PopupActivationDirection | null;
234
+ /**
235
+ * Whether the tooltip is moving between triggers
236
+ */
237
+ transitioning: boolean;
238
+ }
239
+ export interface TooltipApi<T extends PropTypes = PropTypes> {
240
+ /**
241
+ * Whether the tooltip is open.
242
+ */
243
+ open: boolean;
244
+ /**
245
+ * Function to open the tooltip.
246
+ */
247
+ setOpen: (open: boolean, reason?: OpenChangeReason) => void;
248
+ /**
249
+ * The trigger value
250
+ */
251
+ triggerValue: string | null;
252
+ /**
253
+ * Function to set the trigger value
254
+ */
255
+ setTriggerValue: (value: string | null) => void;
256
+ /**
257
+ * Where the current trigger sits relative to the previous one, after switching triggers while open
258
+ */
259
+ activationDirection: PopupActivationDirection | null;
260
+ /**
261
+ * Returns the trigger values whose content to render: the current one, plus the previous one while
262
+ * it animates out after a switch. Oldest first.
263
+ */
264
+ getContentValues: () => string[];
265
+ /**
266
+ * Function to reposition the popover
267
+ */
268
+ reposition: (options?: Partial<PositioningOptions>) => void;
269
+ /**
270
+ * Returns the state of a specific trigger, including whether it's the currently active one
271
+ */
272
+ getTriggerState: (props?: TriggerProps) => TriggerState;
273
+ getTriggerProps: (props?: TriggerProps) => T["button"];
274
+ getArrowProps: () => T["element"];
275
+ getArrowTipProps: () => T["element"];
276
+ getPositionerProps: () => T["element"];
277
+ /**
278
+ * Returns the state of the content
279
+ */
280
+ getContentState: (props?: ContentProps) => ContentState;
281
+ getContentProps: (props?: ContentProps) => T["element"];
282
+ /**
283
+ * Returns the state of the viewport
284
+ */
285
+ getViewportState: () => ViewportState;
286
+ getViewportProps: () => T["element"];
197
287
  }
198
-
199
- export type { ContentState, ElementIds, OpenChangeDetails, TooltipApi, TooltipMachine, TooltipProps, TooltipSchema, TooltipService, TriggerProps, TriggerState, TriggerValueChangeDetails };
288
+ export type { Placement, PositioningOptions };