@xsolla/xui-tooltip 0.149.1 → 0.150.0-pr271.1778110548

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 (2) hide show
  1. package/README.md +87 -163
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,25 +1,27 @@
1
1
  # Tooltip
2
2
 
3
- A cross-platform React tooltip component that displays contextual information when a user hovers over or focuses on an element. Supports multiple placements and animations.
3
+ A hover- or focus-triggered popover that displays contextual information next to a trigger element. Web-only rendering (uses a portal); on React Native the trigger is rendered without the tooltip surface.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @xsolla/xui-tooltip
9
- # or
10
- yarn add @xsolla/xui-tooltip
11
9
  ```
12
10
 
13
- ## Demo
11
+ ## Imports
14
12
 
15
- ### Basic Tooltip
13
+ ```tsx
14
+ import { Tooltip, type TooltipProps, type TooltipPlacement, type TooltipSize } from '@xsolla/xui-tooltip';
15
+ ```
16
+
17
+ ## Quick start
16
18
 
17
19
  ```tsx
18
20
  import * as React from 'react';
19
21
  import { Tooltip } from '@xsolla/xui-tooltip';
20
22
  import { Button } from '@xsolla/xui-button';
21
23
 
22
- export default function BasicTooltip() {
24
+ export default function Example() {
23
25
  return (
24
26
  <Tooltip content="This is a helpful tip">
25
27
  <Button>Hover me</Button>
@@ -28,128 +30,108 @@ export default function BasicTooltip() {
28
30
  }
29
31
  ```
30
32
 
31
- ### Tooltip Placements
33
+ ## API Reference
34
+
35
+ ### `<Tooltip>`
36
+
37
+ | Prop | Type | Default | Description |
38
+ | --- | --- | --- | --- |
39
+ | `content` | `ReactNode` | — | **Required.** Tooltip content. Strings/numbers render as themed text. |
40
+ | `children` | `ReactNode` | — | **Required.** Trigger element. |
41
+ | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Typography size. |
42
+ | `placement` | `TooltipPlacement` | `"top"` | Position relative to trigger. |
43
+ | `offset` | `number` | `12` | Distance from trigger in pixels. |
44
+ | `delayEnter` | `number` | `0` | Delay before showing (ms). |
45
+ | `delayLeave` | `number` | `0` | Delay before hiding (ms). |
46
+ | `controlledVisible` | `boolean` | — | Externally controlled visibility. Overrides hover/focus state. |
47
+ | `style` | `CSSProperties` | — | Custom styles applied to the tooltip surface (web only). |
48
+ | `className` | `string` | — | Custom class for the trigger wrapper. |
49
+ | `data-testid` | `string` | — | Test identifier. |
50
+
51
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
52
+
53
+ `TooltipPlacement` is `"top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right" | "left" | "right"`.
54
+
55
+ ### Size typography
56
+
57
+ | Size | Font size | Line height |
58
+ | --- | --- | --- |
59
+ | `sm` | 14px | 16px |
60
+ | `md` | 16px | 18px |
61
+ | `lg` | 18px | 20px |
62
+ | `xl` | 20px | 22px |
63
+
64
+ ## Examples
65
+
66
+ ### Placements
32
67
 
33
68
  ```tsx
34
69
  import * as React from 'react';
35
70
  import { Tooltip } from '@xsolla/xui-tooltip';
36
71
  import { Button } from '@xsolla/xui-button';
37
72
 
38
- export default function TooltipPlacements() {
73
+ export default function Placements() {
39
74
  return (
40
75
  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 16, padding: 48 }}>
41
- <Tooltip content="Top left" placement="top-left">
42
- <Button variant="secondary">Top Left</Button>
43
- </Tooltip>
44
- <Tooltip content="Top center" placement="top">
45
- <Button variant="secondary">Top</Button>
46
- </Tooltip>
47
- <Tooltip content="Top right" placement="top-right">
48
- <Button variant="secondary">Top Right</Button>
49
- </Tooltip>
50
-
51
- <Tooltip content="Left side" placement="left">
52
- <Button variant="secondary">Left</Button>
53
- </Tooltip>
76
+ <Tooltip content="Top left" placement="top-left"><Button variant="secondary">Top Left</Button></Tooltip>
77
+ <Tooltip content="Top centre" placement="top"><Button variant="secondary">Top</Button></Tooltip>
78
+ <Tooltip content="Top right" placement="top-right"><Button variant="secondary">Top Right</Button></Tooltip>
79
+ <Tooltip content="Left" placement="left"><Button variant="secondary">Left</Button></Tooltip>
54
80
  <div />
55
- <Tooltip content="Right side" placement="right">
56
- <Button variant="secondary">Right</Button>
57
- </Tooltip>
58
-
59
- <Tooltip content="Bottom left" placement="bottom-left">
60
- <Button variant="secondary">Bottom Left</Button>
61
- </Tooltip>
62
- <Tooltip content="Bottom center" placement="bottom">
63
- <Button variant="secondary">Bottom</Button>
64
- </Tooltip>
65
- <Tooltip content="Bottom right" placement="bottom-right">
66
- <Button variant="secondary">Bottom Right</Button>
67
- </Tooltip>
81
+ <Tooltip content="Right" placement="right"><Button variant="secondary">Right</Button></Tooltip>
82
+ <Tooltip content="Bottom left" placement="bottom-left"><Button variant="secondary">Bottom Left</Button></Tooltip>
83
+ <Tooltip content="Bottom centre" placement="bottom"><Button variant="secondary">Bottom</Button></Tooltip>
84
+ <Tooltip content="Bottom right" placement="bottom-right"><Button variant="secondary">Bottom Right</Button></Tooltip>
68
85
  </div>
69
86
  );
70
87
  }
71
88
  ```
72
89
 
73
- ### Tooltip Sizes
90
+ ### Sizes
74
91
 
75
92
  ```tsx
76
93
  import * as React from 'react';
77
94
  import { Tooltip } from '@xsolla/xui-tooltip';
78
95
  import { Button } from '@xsolla/xui-button';
79
96
 
80
- export default function TooltipSizes() {
97
+ export default function Sizes() {
81
98
  return (
82
99
  <div style={{ display: 'flex', gap: 16 }}>
83
- <Tooltip content="Small tooltip" size="sm">
84
- <Button variant="secondary">Small</Button>
85
- </Tooltip>
86
- <Tooltip content="Medium tooltip" size="md">
87
- <Button variant="secondary">Medium</Button>
88
- </Tooltip>
89
- <Tooltip content="Large tooltip" size="lg">
90
- <Button variant="secondary">Large</Button>
91
- </Tooltip>
92
- <Tooltip content="Extra large tooltip" size="xl">
93
- <Button variant="secondary">XL</Button>
94
- </Tooltip>
100
+ <Tooltip content="Small" size="sm"><Button variant="secondary">Small</Button></Tooltip>
101
+ <Tooltip content="Medium" size="md"><Button variant="secondary">Medium</Button></Tooltip>
102
+ <Tooltip content="Large" size="lg"><Button variant="secondary">Large</Button></Tooltip>
103
+ <Tooltip content="Extra large" size="xl"><Button variant="secondary">XL</Button></Tooltip>
95
104
  </div>
96
105
  );
97
106
  }
98
107
  ```
99
108
 
100
- ### Tooltip with Delay
109
+ ### With delay
101
110
 
102
111
  ```tsx
103
112
  import * as React from 'react';
104
113
  import { Tooltip } from '@xsolla/xui-tooltip';
105
114
  import { Button } from '@xsolla/xui-button';
106
115
 
107
- export default function TooltipWithDelay() {
116
+ export default function Delays() {
108
117
  return (
109
118
  <div style={{ display: 'flex', gap: 16 }}>
110
- <Tooltip content="Appears immediately" delayEnter={0}>
111
- <Button variant="secondary">No Delay</Button>
112
- </Tooltip>
113
- <Tooltip content="Appears after 500ms" delayEnter={500}>
114
- <Button variant="secondary">500ms Delay</Button>
115
- </Tooltip>
116
- <Tooltip content="Stays visible for 500ms" delayLeave={500}>
117
- <Button variant="secondary">Slow Hide</Button>
118
- </Tooltip>
119
+ <Tooltip content="Appears immediately" delayEnter={0}><Button variant="secondary">No delay</Button></Tooltip>
120
+ <Tooltip content="Appears after 500ms" delayEnter={500}><Button variant="secondary">500ms enter</Button></Tooltip>
121
+ <Tooltip content="Stays for 500ms" delayLeave={500}><Button variant="secondary">Slow hide</Button></Tooltip>
119
122
  </div>
120
123
  );
121
124
  }
122
125
  ```
123
126
 
124
- ## Anatomy
125
-
126
- Import the component and wrap your trigger element:
127
-
128
- ```jsx
129
- import { Tooltip } from '@xsolla/xui-tooltip';
130
-
131
- <Tooltip
132
- content="Tooltip text" // Content to display
133
- placement="top" // Position relative to trigger
134
- size="md" // Size variant
135
- offset={12} // Distance from trigger
136
- delayEnter={0} // Delay before showing
137
- delayLeave={0} // Delay before hiding
138
- >
139
- <TriggerElement />
140
- </Tooltip>
141
- ```
142
-
143
- ## Examples
144
-
145
- ### Rich Content Tooltip
127
+ ### Rich content
146
128
 
147
129
  ```tsx
148
130
  import * as React from 'react';
149
131
  import { Tooltip } from '@xsolla/xui-tooltip';
150
132
  import { Avatar } from '@xsolla/xui-avatar';
151
133
 
152
- export default function RichContentTooltip() {
134
+ export default function Rich() {
153
135
  return (
154
136
  <Tooltip
155
137
  content={
@@ -166,64 +148,57 @@ export default function RichContentTooltip() {
166
148
  }
167
149
  ```
168
150
 
169
- ### Icon with Tooltip
151
+ ### Icons with tooltip
170
152
 
171
153
  ```tsx
172
154
  import * as React from 'react';
173
155
  import { Tooltip } from '@xsolla/xui-tooltip';
174
- import { Edit, TrashCan, MoreHorizontal } from '@xsolla/xui-icons-base';
156
+ import { Edit, TrashCan, MoreHr } from '@xsolla/xui-icons-base';
175
157
 
176
- export default function IconTooltip() {
158
+ export default function Icons() {
177
159
  return (
178
160
  <div style={{ display: 'flex', gap: 16 }}>
179
- <Tooltip content="Edit item">
180
- <Edit style={{ cursor: 'pointer' }} />
181
- </Tooltip>
182
- <Tooltip content="Delete item">
183
- <TrashCan style={{ cursor: 'pointer' }} />
184
- </Tooltip>
185
- <Tooltip content="More options">
186
- <MoreHorizontal style={{ cursor: 'pointer' }} />
187
- </Tooltip>
161
+ <Tooltip content="Edit item"><Edit style={{ cursor: 'pointer' }} /></Tooltip>
162
+ <Tooltip content="Delete item"><TrashCan style={{ cursor: 'pointer' }} /></Tooltip>
163
+ <Tooltip content="More options"><MoreHr style={{ cursor: 'pointer' }} /></Tooltip>
188
164
  </div>
189
165
  );
190
166
  }
191
167
  ```
192
168
 
193
- ### Controlled Tooltip
169
+ ### Controlled visibility
194
170
 
195
171
  ```tsx
196
172
  import * as React from 'react';
197
173
  import { Tooltip } from '@xsolla/xui-tooltip';
198
174
  import { Button } from '@xsolla/xui-button';
199
175
 
200
- export default function ControlledTooltip() {
176
+ export default function Controlled() {
201
177
  const [visible, setVisible] = React.useState(false);
202
-
203
178
  return (
204
179
  <div style={{ display: 'flex', gap: 16 }}>
205
- <Tooltip content="I'm controlled!" controlledVisible={visible}>
180
+ <Tooltip content="I'm controlled" controlledVisible={visible}>
206
181
  <Button variant="secondary">Target</Button>
207
182
  </Tooltip>
208
- <Button onPress={() => setVisible(!visible)}>
209
- {visible ? 'Hide' : 'Show'} Tooltip
210
- </Button>
183
+ <Button onPress={() => setVisible((v) => !v)}>{visible ? 'Hide' : 'Show'}</Button>
211
184
  </div>
212
185
  );
213
186
  }
214
187
  ```
215
188
 
216
- ### Disabled Button with Tooltip
189
+ ### Disabled trigger
190
+
191
+ `disabled` elements do not emit pointer events; wrap them so the tooltip can still register hover.
217
192
 
218
193
  ```tsx
219
194
  import * as React from 'react';
220
195
  import { Tooltip } from '@xsolla/xui-tooltip';
221
196
  import { Button } from '@xsolla/xui-button';
222
197
 
223
- export default function DisabledButtonTooltip() {
198
+ export default function DisabledTrigger() {
224
199
  return (
225
- <Tooltip content="You need to complete the form first">
226
- <span> {/* Wrapper needed for disabled elements */}
200
+ <Tooltip content="Complete the form first">
201
+ <span>
227
202
  <Button disabled>Submit</Button>
228
203
  </span>
229
204
  </Tooltip>
@@ -231,64 +206,13 @@ export default function DisabledButtonTooltip() {
231
206
  }
232
207
  ```
233
208
 
234
- ## API Reference
235
-
236
- ### Tooltip
237
-
238
- A tooltip component that shows on hover/focus.
239
-
240
- **Tooltip Props:**
209
+ ## Accessibility
241
210
 
242
- | Prop | Type | Default | Description |
243
- | :--- | :--- | :------ | :---------- |
244
- | content | `ReactNode` | - | **Required.** Tooltip content. |
245
- | children | `ReactNode` | - | **Required.** Trigger element. |
246
- | size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the tooltip. |
247
- | placement | `TooltipPlacement` | `"top"` | Position relative to trigger. |
248
- | offset | `number` | `12` | Distance from trigger in pixels. |
249
- | delayEnter | `number` | - | Delay before showing (ms). |
250
- | delayLeave | `number` | - | Delay before hiding (ms). |
251
- | controlledVisible | `boolean` | - | Control visibility externally. |
252
- | style | `CSSProperties` | - | Custom styles. |
253
- | className | `string` | - | Custom class name. |
254
- | data-testid | `string` | - | Test identifier. |
255
-
256
- **TooltipPlacement Options:**
257
-
258
- | Placement | Description |
259
- | :-------- | :---------- |
260
- | `top` | Centered above trigger |
261
- | `top-left` | Above, aligned to left edge |
262
- | `top-right` | Above, aligned to right edge |
263
- | `bottom` | Centered below trigger |
264
- | `bottom-left` | Below, aligned to left edge |
265
- | `bottom-right` | Below, aligned to right edge |
266
- | `left` | Centered to the left |
267
- | `right` | Centered to the right |
268
-
269
- **Size Typography:**
270
-
271
- | Size | Font Size | Line Height |
272
- | :--- | :-------- | :---------- |
273
- | sm | 14px | 16px |
274
- | md | 16px | 18px |
275
- | lg | 18px | 20px |
276
- | xl | 20px | 22px |
277
-
278
- ## Theming
279
-
280
- Tooltip uses the design system theme for colors:
281
-
282
- ```typescript
283
- // Colors accessed via theme
284
- theme.colors.background.inverse // Tooltip background
285
- theme.colors.content.inverse // Tooltip text
286
- ```
211
+ - Tooltip surface uses `role="tooltip"` and `aria-hidden` reflects visibility.
212
+ - Trigger receives `aria-describedby` while the tooltip is visible.
213
+ - Press Escape to dismiss.
214
+ - Tooltip content is non-interactive — for interactive content, prefer [Toggletip](./toggletip.md).
287
215
 
288
- ## Accessibility
216
+ ## Related
289
217
 
290
- - Tooltip appears on focus for keyboard users
291
- - Press Escape to dismiss tooltip
292
- - Arrow indicator points to trigger element
293
- - Content is accessible to screen readers
294
- - Follows WCAG tooltip guidelines
218
+ - [Toggletip](./toggletip.md) — click-triggered popover with rich content.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-tooltip",
3
- "version": "0.149.1",
3
+ "version": "0.150.0-pr271.1778110548",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -13,9 +13,9 @@
13
13
  "test:coverage": "vitest run --coverage"
14
14
  },
15
15
  "dependencies": {
16
- "@xsolla/xui-button": "0.149.1",
17
- "@xsolla/xui-core": "0.149.1",
18
- "@xsolla/xui-primitives-core": "0.149.1"
16
+ "@xsolla/xui-button": "0.150.0-pr271.1778110548",
17
+ "@xsolla/xui-core": "0.150.0-pr271.1778110548",
18
+ "@xsolla/xui-primitives-core": "0.150.0-pr271.1778110548"
19
19
  },
20
20
  "peerDependencies": {
21
21
  "react": ">=16.8.0",