@fibrae/semi-ui-svelte 0.9.1 → 0.10.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 (165) hide show
  1. package/README.md +8 -4
  2. package/README.zh-CN.md +8 -4
  3. package/dist/components/anchor/interface.d.ts +14 -0
  4. package/dist/components/audio-player/interface.d.ts +5 -0
  5. package/dist/components/auto-complete/interface.d.ts +29 -0
  6. package/dist/components/avatar/interface.d.ts +24 -0
  7. package/dist/components/backtop/interface.d.ts +2 -0
  8. package/dist/components/badge/interface.d.ts +7 -0
  9. package/dist/components/banner/interface.d.ts +7 -0
  10. package/dist/components/breadcrumb/interface.d.ts +10 -0
  11. package/dist/components/button/interface.d.ts +18 -0
  12. package/dist/components/calendar/interface.d.ts +16 -0
  13. package/dist/components/card/interface.d.ts +18 -0
  14. package/dist/components/carousel/interface.d.ts +16 -0
  15. package/dist/components/cascader/interface.d.ts +57 -0
  16. package/dist/components/checkbox/interface.d.ts +19 -0
  17. package/dist/components/code-highlight/interface.d.ts +3 -0
  18. package/dist/components/collapse/interface.d.ts +16 -0
  19. package/dist/components/collapsible/interface.d.ts +10 -0
  20. package/dist/components/color-picker/interface.d.ts +10 -0
  21. package/dist/components/config-provider/interface.d.ts +7 -0
  22. package/dist/components/cropper/interface.d.ts +11 -0
  23. package/dist/components/date-picker/interface.d.ts +47 -0
  24. package/dist/components/descriptions/interface.d.ts +6 -0
  25. package/dist/components/divider/interface.d.ts +4 -0
  26. package/dist/components/dropdown/interface.d.ts +8 -0
  27. package/dist/components/empty/interface.d.ts +7 -0
  28. package/dist/components/feedback/interface.d.ts +16 -0
  29. package/dist/components/float-button/interface.d.ts +14 -0
  30. package/dist/components/form/interface.d.ts +47 -0
  31. package/dist/components/grid/interface.d.ts +13 -0
  32. package/dist/components/highlight/interface.d.ts +7 -0
  33. package/dist/components/hot-keys/interface.d.ts +3 -0
  34. package/dist/components/image/interface.d.ts +59 -0
  35. package/dist/components/input/interface.d.ts +67 -0
  36. package/dist/components/input-number/interface.d.ts +24 -0
  37. package/dist/components/json-viewer/interface.d.ts +7 -0
  38. package/dist/components/layout/interface.d.ts +3 -0
  39. package/dist/components/list/interface.d.ts +18 -0
  40. package/dist/components/locale/interface.d.ts +4 -0
  41. package/dist/components/lottie/interface.d.ts +2 -0
  42. package/dist/components/markdown-render/interface.d.ts +5 -0
  43. package/dist/components/modal/interface.d.ts +29 -0
  44. package/dist/components/navigation/interface.d.ts +47 -0
  45. package/dist/components/overflow-list/interface.d.ts +11 -0
  46. package/dist/components/pagination/interface.d.ts +12 -0
  47. package/dist/components/pincode/interface.d.ts +8 -0
  48. package/dist/components/popconfirm/interface.d.ts +12 -0
  49. package/dist/components/popover/interface.d.ts +30 -0
  50. package/dist/components/progress/interface.d.ts +13 -0
  51. package/dist/components/radio/interface.d.ts +22 -0
  52. package/dist/components/rating/interface.d.ts +12 -0
  53. package/dist/components/resizable/interface.d.ts +30 -0
  54. package/dist/components/scroll-list/interface.d.ts +6 -0
  55. package/dist/components/select/interface.d.ts +63 -0
  56. package/dist/components/side-sheet/interface.d.ts +19 -0
  57. package/dist/components/skeleton/interface.d.ts +7 -0
  58. package/dist/components/slider/interface.d.ts +23 -0
  59. package/dist/components/space/interface.d.ts +4 -0
  60. package/dist/components/spin/interface.d.ts +7 -0
  61. package/dist/components/steps/interface.d.ts +9 -0
  62. package/dist/components/switch/interface.d.ts +7 -0
  63. package/dist/components/table/interface.d.ts +48 -0
  64. package/dist/components/tabs/interface.d.ts +29 -0
  65. package/dist/components/tag/interface.d.ts +22 -0
  66. package/dist/components/tag-input/interface.d.ts +29 -0
  67. package/dist/components/time-picker/interface.d.ts +31 -0
  68. package/dist/components/timeline/interface.d.ts +5 -0
  69. package/dist/components/tooltip/interface.d.ts +20 -0
  70. package/dist/components/transfer/interface.d.ts +18 -0
  71. package/dist/components/tree/interface.d.ts +45 -0
  72. package/dist/components/tree-select/interface.d.ts +55 -0
  73. package/dist/components/typography/interface.d.ts +33 -0
  74. package/dist/components/upload/interface.d.ts +64 -0
  75. package/dist/components/user-guide/interface.d.ts +15 -0
  76. package/dist/components/video-player/interface.d.ts +22 -0
  77. package/docs/advanced/dark-mode.md +288 -0
  78. package/docs/basic/button.md +605 -0
  79. package/docs/basic/divider.md +103 -0
  80. package/docs/basic/float-button.md +246 -0
  81. package/docs/basic/grid.md +427 -0
  82. package/docs/basic/layout.md +459 -0
  83. package/docs/basic/resizable.md +584 -0
  84. package/docs/basic/space.md +163 -0
  85. package/docs/basic/tokens.md +425 -0
  86. package/docs/basic/typography.md +615 -0
  87. package/docs/changes-from-semi.md +105 -0
  88. package/docs/ecosystem/tailwind.md +210 -0
  89. package/docs/experience/accessibility.md +82 -0
  90. package/docs/experience/content-guidelines.md +819 -0
  91. package/docs/experience/internationalization.md +7 -0
  92. package/docs/feedback/banner.md +198 -0
  93. package/docs/feedback/feedback.md +294 -0
  94. package/docs/feedback/notification.md +401 -0
  95. package/docs/feedback/popconfirm.md +243 -0
  96. package/docs/feedback/progress.md +389 -0
  97. package/docs/feedback/skeleton.md +388 -0
  98. package/docs/feedback/spin.md +172 -0
  99. package/docs/feedback/toast.md +393 -0
  100. package/docs/input/auto-complete.md +399 -0
  101. package/docs/input/cascader.md +1558 -0
  102. package/docs/input/checkbox.md +408 -0
  103. package/docs/input/color-picker.md +175 -0
  104. package/docs/input/date-picker.md +942 -0
  105. package/docs/input/form.md +2550 -0
  106. package/docs/input/input-number.md +451 -0
  107. package/docs/input/input.md +640 -0
  108. package/docs/input/pincode.md +191 -0
  109. package/docs/input/radio.md +337 -0
  110. package/docs/input/rating.md +214 -0
  111. package/docs/input/select.md +1230 -0
  112. package/docs/input/slider.md +347 -0
  113. package/docs/input/switch.md +206 -0
  114. package/docs/input/tag-input.md +465 -0
  115. package/docs/input/time-picker.md +358 -0
  116. package/docs/input/transfer.md +1061 -0
  117. package/docs/input/tree-select.md +1300 -0
  118. package/docs/input/upload.md +1811 -0
  119. package/docs/llms.txt +147 -0
  120. package/docs/navigation/anchor.md +377 -0
  121. package/docs/navigation/backtop.md +100 -0
  122. package/docs/navigation/breadcrumb.md +284 -0
  123. package/docs/navigation/navigation.md +851 -0
  124. package/docs/navigation/pagination.md +217 -0
  125. package/docs/navigation/steps.md +315 -0
  126. package/docs/navigation/tabs.md +754 -0
  127. package/docs/navigation/tree.md +1956 -0
  128. package/docs/other/config-provider.md +599 -0
  129. package/docs/other/locale.md +353 -0
  130. package/docs/plus/audio-player.md +155 -0
  131. package/docs/plus/code-highlight.md +150 -0
  132. package/docs/plus/drag-move.md +214 -0
  133. package/docs/plus/hot-keys.md +174 -0
  134. package/docs/plus/json-viewer.md +392 -0
  135. package/docs/plus/lottie.md +176 -0
  136. package/docs/plus/markdown-render.md +240 -0
  137. package/docs/plus/video-player.md +325 -0
  138. package/docs/show/avatar.md +475 -0
  139. package/docs/show/badge.md +276 -0
  140. package/docs/show/calendar.md +352 -0
  141. package/docs/show/card.md +485 -0
  142. package/docs/show/carousel.md +592 -0
  143. package/docs/show/collapse.md +289 -0
  144. package/docs/show/collapsible.md +216 -0
  145. package/docs/show/cropper.md +285 -0
  146. package/docs/show/descriptions.md +325 -0
  147. package/docs/show/dropdown.md +466 -0
  148. package/docs/show/empty.md +225 -0
  149. package/docs/show/highlight.md +144 -0
  150. package/docs/show/image.md +433 -0
  151. package/docs/show/list.md +927 -0
  152. package/docs/show/modal.md +517 -0
  153. package/docs/show/overflow-list.md +272 -0
  154. package/docs/show/popover.md +534 -0
  155. package/docs/show/scroll-list.md +156 -0
  156. package/docs/show/side-sheet.md +274 -0
  157. package/docs/show/table.md +5437 -0
  158. package/docs/show/tag.md +428 -0
  159. package/docs/show/timeline.md +277 -0
  160. package/docs/show/tooltip.md +442 -0
  161. package/docs/show/user-guide.md +419 -0
  162. package/docs/start/getting-started.md +234 -0
  163. package/docs/start/introduction.md +57 -0
  164. package/docs/start/overview.md +21 -0
  165. package/package.json +5 -4
@@ -0,0 +1,534 @@
1
+ # Popover
2
+
3
+ > Click / mouse to move into the element and pop up the bubble card floating layer.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/popover/
6
+
7
+ ## When to Use
8
+
9
+ When the target element has further description and related operations, it can be included in the card and displayed according to the user's operational behavior.
10
+
11
+ The difference with Tooltip is that users can operate on elements on the floating layer, so it can carry more complex content, such as links or buttons.
12
+
13
+ ## Demos
14
+
15
+ ### How to import
16
+
17
+ ```svelte
18
+ <script lang="ts">
19
+ import { Popover } from '@fibrae/semi-ui-svelte';
20
+ </script>
21
+ ```
22
+
23
+ ### Cautions
24
+
25
+ Popover applies the trigger attributes and event listeners to the trigger element, and uses the real DOM element of the trigger to calculate the position of the popup layer, so the trigger supports the following forms:
26
+
27
+ 1. The `child` snippet: spread its argument `{ props }` whole onto the element that receives focus, either a real DOM element such as span, div, p..., or a component that passes its props through to its root DOM element (such as `<Button {...props} />`)
28
+ 2. The `children` snippet (content written inside the tag): text, a component or several nodes, which Popover wraps in a span as the trigger element
29
+
30
+ ```svelte
31
+ <script lang="ts">
32
+ import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-icons-svelte/illustrations';
33
+ import { Empty, Popover, Space, Tag } from '@fibrae/semi-ui-svelte';
34
+
35
+ const style = 'border: 2px solid var(--semi-color-border); padding-inline-start: 4px; padding-inline-end: 4px; border-radius: 4px';
36
+ </script>
37
+
38
+ {#snippet card()}
39
+ <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
40
+ {#snippet image()}
41
+ <IllustrationSuccess style="width: 150px; height: 150px" />
42
+ {/snippet}
43
+ {#snippet darkModeImage()}
44
+ <IllustrationSuccessDark style="width: 150px; height: 150px" />
45
+ {/snippet}
46
+ {#snippet description()}一套组件,四个框架原生可用{/snippet}
47
+ </Empty>
48
+ {/snippet}
49
+
50
+ <Space>
51
+ <Popover content={card}>
52
+ <Tag {style}>Component</Tag>
53
+ </Popover>
54
+ <Popover content={card}>Text</Popover>
55
+ <Popover content={card}>
56
+ {#snippet child({ props })}
57
+ <span {...props} {style}>DOM</span>
58
+ {/snippet}
59
+ </Popover>
60
+ </Space>
61
+ ```
62
+
63
+ ### Basic Usage
64
+
65
+ Write the trigger inside the Popover tag (the trigger is a Tag in the example below) and pass the popup content through the `content` snippet.\
66
+ The cautions are the same as [Tooltip](../show/tooltip.md#Cautions)
67
+
68
+ ```svelte
69
+ <script lang="ts">
70
+ import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-icons-svelte/illustrations';
71
+ import { Empty, Popover, Tag } from '@fibrae/semi-ui-svelte';
72
+ </script>
73
+
74
+ {#snippet card()}
75
+ <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
76
+ {#snippet image()}
77
+ <IllustrationSuccess style="width: 150px; height: 150px" />
78
+ {/snippet}
79
+ {#snippet darkModeImage()}
80
+ <IllustrationSuccessDark style="width: 150px; height: 150px" />
81
+ {/snippet}
82
+ {#snippet description()}一套组件,四个框架原生可用{/snippet}
83
+ </Empty>
84
+ {/snippet}
85
+
86
+ <Popover content={card}>
87
+ <Tag>悬停此处</Tag>
88
+ </Popover>
89
+ ```
90
+
91
+ ### Pop-up Position
92
+
93
+ Support twelve directions.
94
+
95
+ ```svelte
96
+ <script lang="ts">
97
+ import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-icons-svelte/illustrations';
98
+ import { Empty, Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';
99
+
100
+ const tops: [Position, string][] = [
101
+ ['topLeft', 'TL'],
102
+ ['top', 'Top'],
103
+ ['topRight', 'TR'],
104
+ ];
105
+ const lefts: [Position, string][] = [
106
+ ['leftTop', 'LT'],
107
+ ['left', 'Left'],
108
+ ['leftBottom', 'LB'],
109
+ ];
110
+ const rights: [Position, string][] = [
111
+ ['rightTop', 'RT'],
112
+ ['right', 'Right'],
113
+ ['rightBottom', 'RB'],
114
+ ];
115
+ const bottoms: [Position, string][] = [
116
+ ['bottomLeft', 'BL'],
117
+ ['bottom', 'Bottom'],
118
+ ['bottomRight', 'BR'],
119
+ ];
120
+ </script>
121
+
122
+ {#snippet content()}
123
+ <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
124
+ {#snippet image()}
125
+ <IllustrationSuccess style="width: 150px; height: 150px" />
126
+ {/snippet}
127
+ {#snippet darkModeImage()}
128
+ <IllustrationSuccessDark style="width: 150px; height: 150px" />
129
+ {/snippet}
130
+ {#snippet description()}一套组件,四个框架原生可用{/snippet}
131
+ </Empty>
132
+ {/snippet}
133
+
134
+ <div>
135
+ <div style="margin-inline-start: 80px; white-space: nowrap">
136
+ {#each tops as [position, label] (position)}
137
+ <Popover {content} {position}>
138
+ <Tag style="margin: 8px; padding: 20px">{label}</Tag>
139
+ </Popover>
140
+ {/each}
141
+ </div>
142
+ <div style="width: 80px; float: left">
143
+ {#each lefts as [position, label] (position)}
144
+ <Popover {content} {position}>
145
+ <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
146
+ </Popover>
147
+ {/each}
148
+ </div>
149
+ <div style="width: 40px; margin-inline-start: 300px">
150
+ {#each rights as [position, label] (position)}
151
+ <Popover {content} {position}>
152
+ <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
153
+ </Popover>
154
+ {/each}
155
+ </div>
156
+ <div style="margin-inline-start: 80px; clear: both; white-space: nowrap">
157
+ {#each bottoms as [position, label] (position)}
158
+ <Popover {content} {position}>
159
+ <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
160
+ </Popover>
161
+ {/each}
162
+ </div>
163
+ </div>
164
+ ```
165
+
166
+ ### Controlled Display
167
+
168
+ Set `trigger="custom"`. In this scenario, Popover's display is completely at the control of parameter `visible`, which can be used with `bind:visible`.
169
+
170
+ ```svelte
171
+ <script lang="ts">
172
+ import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-icons-svelte/illustrations';
173
+ import { Empty, Popover, Radio, RadioGroup, type RadioValue } from '@fibrae/semi-ui-svelte';
174
+
175
+ let value = $state<RadioValue | undefined>(false);
176
+ </script>
177
+
178
+ {#snippet content()}
179
+ <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
180
+ {#snippet image()}
181
+ <IllustrationSuccess style="width: 150px; height: 150px" />
182
+ {/snippet}
183
+ {#snippet darkModeImage()}
184
+ <IllustrationSuccessDark style="width: 150px; height: 150px" />
185
+ {/snippet}
186
+ {#snippet description()}一套组件,四个框架原生可用{/snippet}
187
+ </Empty>
188
+ {/snippet}
189
+
190
+ <Popover {content} trigger="custom" visible={value === true}>
191
+ <span style="display: inline-block">
192
+ <RadioGroup bind:value type="button">
193
+ <Radio value={true}>受控显示</Radio>
194
+ <Radio value={false}>受控隐藏</Radio>
195
+ </RadioGroup>
196
+ </span>
197
+ </Popover>
198
+ ```
199
+
200
+ ### Conditional trigger (condition)
201
+
202
+ When `condition={false}`, Popover will not respond to hover/click/focus triggers (with `trigger="custom"`, `visible` still decides); when condition changes from true to false, an open popup closes at once; with `visible` controlled it only calls `onVisibleChange(false)`, and the popup closes once the owner sets `visible` to false.
203
+
204
+ ```svelte
205
+ <script lang="ts">
206
+ import { Button, Popover, Space, Switch, Typography } from '@fibrae/semi-ui-svelte';
207
+
208
+ let enabled = $state(true);
209
+ const text = $derived(`condition is ${enabled ? 'true' : 'false'}`);
210
+ </script>
211
+
212
+ {#snippet content()}{text}{/snippet}
213
+
214
+ <Space align="center">
215
+ <Typography.Text id="popover-condition-label">condition</Typography.Text>
216
+ <Switch aria-labelledby="popover-condition-label" bind:checked={enabled} />
217
+ <Popover condition={enabled} {content}>
218
+ {#snippet child({ props })}
219
+ <Button {...props}>Hover me</Button>
220
+ {/snippet}
221
+ </Popover>
222
+ <Popover condition={enabled} {content} trigger="click">
223
+ {#snippet child({ props })}
224
+ <Button {...props}>Click me</Button>
225
+ {/snippet}
226
+ </Popover>
227
+ </Space>
228
+ ```
229
+
230
+ ### Show Small Triangle
231
+
232
+ Popover also supports the display of a small triangle.
233
+
234
+ > The floating layer in this mode has a default style that you can overwrite by passing the style parameters.
235
+
236
+ ```svelte
237
+ <script lang="ts">
238
+ import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';
239
+
240
+ const tops: [Position, string][] = [
241
+ ['topLeft', 'TL'],
242
+ ['top', 'Top'],
243
+ ['topRight', 'TR'],
244
+ ];
245
+ const lefts: [Position, string][] = [
246
+ ['leftTop', 'LT'],
247
+ ['left', 'Left'],
248
+ ['leftBottom', 'LB'],
249
+ ];
250
+ const rights: [Position, string][] = [
251
+ ['rightTop', 'RT'],
252
+ ['right', 'Right'],
253
+ ['rightBottom', 'RB'],
254
+ ];
255
+ const bottoms: [Position, string][] = [
256
+ ['bottomLeft', 'BL'],
257
+ ['bottom', 'Bottom'],
258
+ ['bottomRight', 'BR'],
259
+ ];
260
+ </script>
261
+
262
+ {#snippet content()}
263
+ <article>
264
+ Hi Semi, this is a popover.
265
+ <br />
266
+ We have 2 lines.
267
+ </article>
268
+ {/snippet}
269
+
270
+ <div class="tag-margin-right" style="padding-inline-start: 40px">
271
+ <div style="margin-inline-start: 40px; white-space: nowrap">
272
+ {#each tops as [position, label] (position)}
273
+ <Popover {content} {position} showArrow>
274
+ <Tag>{label}</Tag>
275
+ </Popover>
276
+ {/each}
277
+ </div>
278
+ <div style="width: 40px; float: left">
279
+ {#each lefts as [position, label] (position)}
280
+ <Popover {content} {position} showArrow>
281
+ <Tag>{label}</Tag>
282
+ </Popover>
283
+ {/each}
284
+ </div>
285
+ <div style="width: 40px; margin-inline-start: 180px">
286
+ {#each rights as [position, label] (position)}
287
+ <Popover {content} {position} showArrow>
288
+ <Tag>{label}</Tag>
289
+ </Popover>
290
+ {/each}
291
+ </div>
292
+ <div style="margin-inline-start: 40px; clear: both; white-space: nowrap">
293
+ {#each bottoms as [position, label] (position)}
294
+ <Popover {content} {position} showArrow>
295
+ <Tag>{label}</Tag>
296
+ </Popover>
297
+ {/each}
298
+ </div>
299
+ </div>
300
+ ```
301
+
302
+ ### Arrow Point at Center
303
+
304
+ Under the condition of **showArrow=true**, you can pass in `arrowPointAtCenter=true` so that the small triangle always points to the center of the element.
305
+
306
+ ```svelte
307
+ <script lang="ts">
308
+ import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';
309
+
310
+ const tops: [Position, string][] = [
311
+ ['topLeft', 'TL'],
312
+ ['top', 'Top'],
313
+ ['topRight', 'TR'],
314
+ ];
315
+ const lefts: [Position, string][] = [
316
+ ['leftTop', 'LT'],
317
+ ['left', 'Left'],
318
+ ['leftBottom', 'LB'],
319
+ ];
320
+ const rights: [Position, string][] = [
321
+ ['rightTop', 'RT'],
322
+ ['right', 'Right'],
323
+ ['rightBottom', 'RB'],
324
+ ];
325
+ const bottoms: [Position, string][] = [
326
+ ['bottomLeft', 'BL'],
327
+ ['bottom', 'Bottom'],
328
+ ['bottomRight', 'BR'],
329
+ ];
330
+ </script>
331
+
332
+ {#snippet content()}
333
+ <article>
334
+ Hi Semi, this is a popover.
335
+ <br />
336
+ We have 2 lines.
337
+ </article>
338
+ {/snippet}
339
+
340
+ <div class="tag-margin-right" style="padding-inline-start: 40px">
341
+ <div style="margin-inline-start: 40px; white-space: nowrap">
342
+ {#each tops as [position, label] (position)}
343
+ <Popover arrowPointAtCenter {content} {position} showArrow>
344
+ <Tag>{label}</Tag>
345
+ </Popover>
346
+ {/each}
347
+ </div>
348
+ <div style="width: 40px; float: left">
349
+ {#each lefts as [position, label] (position)}
350
+ <Popover arrowPointAtCenter {content} {position} showArrow>
351
+ <Tag>{label}</Tag>
352
+ </Popover>
353
+ {/each}
354
+ </div>
355
+ <div style="width: 40px; margin-inline-start: 180px">
356
+ {#each rights as [position, label] (position)}
357
+ <Popover arrowPointAtCenter {content} {position} showArrow>
358
+ <Tag>{label}</Tag>
359
+ </Popover>
360
+ {/each}
361
+ </div>
362
+ <div style="margin-inline-start: 40px; clear: both; white-space: nowrap">
363
+ {#each bottoms as [position, label] (position)}
364
+ <Popover arrowPointAtCenter {content} {position} showArrow>
365
+ <Tag>{label}</Tag>
366
+ </Popover>
367
+ {/each}
368
+ </div>
369
+ </div>
370
+ ```
371
+
372
+ ### Set Floating Layer Background Color
373
+
374
+ If you need to customize the background color or border color of the floating layer, please **Be sure to set `backgroundColor` and `borderColor` properties in `style` separately.** This enables the "small triangle" to apply the same background color and border color.
375
+
376
+ ```svelte
377
+ <script lang="ts">
378
+ import { Popover, Tag } from '@fibrae/semi-ui-svelte';
379
+ </script>
380
+
381
+ <div>
382
+ <Popover aria-label="Colorful Popover" position="right" showArrow style="background-color: var(--semi-blue-6); border-color: var(--semi-blue-6); color: var(--semi-color-white); border-width: 1px; border-style: solid" trigger="custom" visible>
383
+ <Tag style="background-color: var(--semi-blue-6); color: var(--semi-color-white)">Colorful Popover</Tag>
384
+ {#snippet content()}
385
+ <article style="padding: 4px">Hi, Semi UI Popover.</article>
386
+ {/snippet}
387
+ </Popover>
388
+ </div>
389
+ ```
390
+
391
+ ### Initialize the Focus Position of Popup Layer
392
+
393
+ The `content` snippet receives `{ initialFocusRef }` as its argument. Bind it to a focusable element with `{@attach initialFocusRef}`, and it will automatically focus at this position when the panel is opened. On a component, `{@attach}` lands on the inner native control that receives `aria-*` and `tabindex` (such as the native `<input>` of Input in the example).
394
+
395
+ ```svelte
396
+ <script lang="ts">
397
+ import { Button, Input, Popover, Space } from '@fibrae/semi-ui-svelte';
398
+ </script>
399
+
400
+ <Popover trigger="click">
401
+ <Button>click me</Button>
402
+ {#snippet content(contentProps)}
403
+ <div style="padding: 12px">
404
+ <Space>
405
+ <Button>first focusable element</Button>
406
+ <Input {@attach contentProps.initialFocusRef} placeholder="focus here" />
407
+ </Space>
408
+ </div>
409
+ {/snippet}
410
+ </Popover>
411
+ ```
412
+
413
+ ### Use with Tooltip or Popconfirm
414
+
415
+ Please refer to [Use with Tooltip/Popconfirm](../show/tooltip.md#%E6%90%AD%E9%85%8D%20Popover%20%E6%88%96%20Popconfirm%20%E4%BD%BF%E7%94%A8)
416
+
417
+ ## API Reference
418
+
419
+ **Props**
420
+
421
+ | Property | Description | Type | Default |
422
+ | - | - | - | - |
423
+ | afterClose | Called after the popup has closed and its leave animation has finished. | `TooltipProps['afterClose']` | - |
424
+ | afterOpen | Called after the popup has opened and its enter animation has finished, or right after opening when there is no enter animation, controlled or not; not called for an open that is closed before the enter animation ends. | `TooltipProps['afterOpen']` | - |
425
+ | aria-describedby | aria-describedby of the popup when its role is dialog. | `string` | - |
426
+ | aria-label | aria-label of the popup when its role is dialog. | `string` | - |
427
+ | aria-labelledby | aria-labelledby of the popup when its role is dialog. | `string` | - |
428
+ | arrowPointAtCenter | Whether the arrow points at the center of the trigger. Requires showArrow. | `boolean` | - |
429
+ | autoAdjustOverflow | Whether the popup flips automatically when it would be clipped. | `boolean` | `true` |
430
+ | child | Snippet that renders the trigger element itself. Its argument `{ props }` must be spread whole onto the trigger; when `child` is passed, `children` has no effect. | `TooltipProps['child']` | - |
431
+ | children | Snippet for the trigger. It is wrapped in Tooltip's own span, which receives the trigger attributes. | `TooltipProps['children']` | - |
432
+ | class | Class name of the popup. | `string` | - |
433
+ | classNames | Class names of the inner parts, keyed by `content` (the content card) and `arrow`; merged with the built-in classes. | `Partial<Record<PopoverPart, ClassValue>>` | - |
434
+ | clickToHide | Whether a click on the popup or anything inside it closes the popup. | `boolean` | - |
435
+ | closeOnEsc | Whether Esc closes the open popup. With trigger custom it only calls onEscKeyDown and the caller decides whether to close. | `boolean` | `true` |
436
+ | condition | Whether the popup may be triggered. Only an explicit false disables the hover, click and focus triggers; with trigger custom, visible still shows the popup. Changing it from true to false closes an open popup at once; with a controlled visible it only calls onVisibleChange(false), and the popup closes once the caller writes back. | `boolean` | - |
437
+ | content | Snippet for the card content. Its argument `{ initialFocusRef }` is a callback; write `{@attach initialFocusRef}` to bind it to the element that receives focus when the popup opens. | `TooltipProps['content']` | - |
438
+ | disableArrowKeyDown | Whether the arrow keys on the trigger are prevented from moving focus into the popup. | `boolean` | - |
439
+ | disableFocusListener | Whether keyboard focus is ignored when trigger is hover. | `boolean` | - |
440
+ | guardFocus | Whether Tab cycles inside the popup while focus is in it. | `boolean` | `true` |
441
+ | keepDOM | Whether the popup content stays mounted while closed. | `boolean` | - |
442
+ | motion | Whether the popup is animated. | `boolean` | `true` |
443
+ | mouseEnterDelay | Milliseconds before the popup shows after the pointer enters. Applies to the hover and focus triggers. | `number` | - |
444
+ | mouseLeaveDelay | Milliseconds before the popup hides after the pointer leaves. Applies to the hover and focus triggers; not less than mouseEnterDelay. | `number` | - |
445
+ | onClickOutSide | Called when the mouse is pressed outside of the trigger and the open popup. Only for trigger click, contextMenu or custom. | `TooltipProps['onClickOutSide']` | - |
446
+ | onEscKeyDown | Called when Esc is pressed while the popup is open and closeOnEsc is true. | `TooltipProps['onEscKeyDown']` | - |
447
+ | onOpen | Called once per opening when the popup is shown, as its enter animation starts, before afterOpen, controlled or not; not called for a hover open withdrawn because the pointer already left. | `TooltipProps['onOpen']` | - |
448
+ | onVisibleChange | Called when the visibility of the popup changes; with a controlled visible it reports only requests from user interaction, not changes the caller makes to visible. | `TooltipProps['onVisibleChange']` | - |
449
+ | position | Position of the popup relative to the trigger element, in twelve directions. | `TooltipProps['position']` | `"bottom"` |
450
+ | returnFocusOnClose | Whether focus returns to the trigger after Esc closes the popup. | `boolean` | `true` |
451
+ | role | ARIA role of the popup. Omitted, it is dialog for the click, contextMenu and custom triggers and tooltip for the rest; pass presentation when the popup only belongs to another control, such as a combobox list. | `string` | - |
452
+ | showArrow | Whether the arrow is shown. | `boolean` | `false` |
453
+ | spacing | Distance in pixels between the popup and the trigger. An object sets the horizontal and vertical distances. Omitted, it is 4 without an arrow and 10 with one. | `number \| { x: number; y: number }` | - |
454
+ | stopPropagation | Whether click, mousedown and focus in/out events on the popup stop propagating. | `boolean \| string` | - |
455
+ | style | Style string of the popup; its background-color and border-color also color the arrow. | `string` | - |
456
+ | styles | Inline styles of the inner parts, keyed like `classNames`. `content` is the style string of the content card; `arrow` holds the arrow's borderColor, backgroundColor and borderOpacity, and colors that are not set follow background-color and border-color of the popup style. | `{ content?: string; arrow?: ArrowStyle }` | - |
457
+ | trigger | When the popup shows. With custom, visible alone decides. | `TooltipProps['trigger']` | `"hover"` |
458
+ | visible | Whether the popup is shown, used with trigger custom; bind it with `bind:visible`. When given, this value decides. | `boolean` | - |
459
+
460
+ **Methods**
461
+
462
+ | Method | Description | Type |
463
+ | - | - | - |
464
+ | focusTrigger | Focuses the trigger element. Only works when returnFocusOnClose is true and trigger is not custom. | `() => void` |
465
+ | getPopup | Returns the popup element, or `null` while the popup is not in the document. | `() => any` |
466
+ | rePosition | Recomputes the popup position from the trigger's current position at once. The popup already follows scrolling, window resizing, trigger moves and size changes of the trigger or popup, so this is rarely needed; following a trigger move lands a frame late, so call this to align within the same frame. | `() => void` |
467
+
468
+ `class` and `style` land on the popup layer, and other undeclared attributes are dropped (Popover has no root DOM element); the trigger attributes are only added to the trigger element. `bind:this` receives the instance methods, not a DOM element.
469
+
470
+ ## Accessibility
471
+
472
+ ### ARIA
473
+
474
+ - About role
475
+ - If the trigger is set to `click`, `contextMenu` or `custom`, the PopoverContent element has role set to `dialog`.
476
+ - If the trigger is set to `hover` or `focus`, it has role set to `tooltip`.
477
+ - The `role` prop overrides the default. A `dialog` needs a name: pass `aria-label`, or point `aria-labelledby` at a heading in the content; an unnamed dialog logs a warning in development
478
+ - Popover's content
479
+ - The content wrapper will be automatically added with the id attribute
480
+ - Popover's children (for a `tooltip` they only get `aria-describedby`; for other roles, such as `presentation`, nothing is added)
481
+ - Will be automatically added [aria-expanded](https://www.w3.org/TR/wai-aria-1.1/#aria-expanded) attribute, when Popover is visible, the attribute value is `true`, when invisible Is `false`
482
+ - Will be automatically added [aria-haspopup](https://www.w3.org/TR/wai-aria-1.1/#aria-haspopup) attribute, which is `dialog`
483
+ - Will be automatically added [aria-controls](https://www.w3.org/TR/wai-aria-1.1/#aria-controls) attribute, which is the id of the content wrapper
484
+
485
+ ### Keyboard and Focus
486
+
487
+ - When the Popover trigger method is set to `hover`: Open the Popover when the mouse is hovered or focused
488
+ - When the Popover trigger method is set to `click`: Click the trigger or focus and use the Enter key to open the Popover
489
+ - After the Popover is activated, press the `arrow key` ⬇️ to move the focus to the Popover. At this time, the focus is on the first interactive element in the Popover by default, and the user can also customize the focus position (if there is no interactive element in the Popover, it will appear as No response)
490
+ - Use the `Tab` key when the focus is in the Popover, the focus will cycle in the Popover, and use `Shift + Tab` to move the focus in the opposite direction
491
+ - Keyboard users can close the Popover by pressing `Esc`, after closing the focus returns to the trigger (when the trigger is click)
492
+
493
+ ## Design Tokens
494
+
495
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/popover/>
496
+
497
+ ## FAQ
498
+
499
+ - **Why the position of the popover overlay card and the relative position of the overlay trigger are not as expected?**\
500
+ Popover relies on Tooltip at the bottom. In order to calculate positioning, Tooltip needs to obtain the real DOM elements of children. Therefore, the Popover type currently supports the following types of children:
501
+
502
+ 1. The `child` snippet: spread `props` onto a real DOM element, or onto a component that passes its props through to its root DOM element
503
+ 2. The `children` snippet (text, a component, several nodes), which Popover wraps in a span
504
+
505
+ When Semi Input with prefix is used as the trigger, even if the same width of Input and Popover content are set, the position of the floating card is still positioned relative to the input box that does not contain the prefix part. At this time, just put another div on the outer layer of the trigger to solve the problem.
506
+
507
+ ## Changes from Semi Design
508
+
509
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
510
+
511
+ - 破坏性:Popover 删除 `contentClassName`、`arrowStyle`,改用 `classNames`、`styles` 的 `content`(内容卡片)、`arrow` 键,`styles.arrow` 仍是 `borderColor`、`backgroundColor`、`borderOpacity` 这组箭头颜色;Tooltip 删除 `wrapperClassName`,改用 `classNames.wrapper`,新增 `styles.wrapper`,作用在触发元素被包裹时的 span 上。
512
+ - 破坏性:弹层改用 Popover API 进入 top layer,Portal 到触发元素所在根节点,不受祖先 `overflow`、`transform`、`z-index` 影响,也不在触发元素 DOM 内。位置按视口计算,`x-placement` 是自动翻转后的方位;放得下视口的弹层夹在视口内,触发器滚出或被裁出可见区域时弹层隐藏;打开期间随滚动、窗口 resize、触发器或弹层的尺寸变化重新定位,只随触发器所在区域的滚动重算,同一帧内的多个弹层一起重算;触发器只因别处布局变化而移动时也会跟随,但晚一帧。Tooltip、Popover、Dropdown 与 Select 的 ref 都提供 `rePosition()`(Popover 的 `PopoverHandle` 为新增),立即按触发器当前位置重新定位,一般无需调用。Tooltip 左右两侧边角方位(`leftTop`、`leftBottom`、`rightTop`、`rightBottom`)的箭头离弹层角 1px 更远,与 Popover 和上下方位一致,`arrowPointAtCenter` 时正对触发器中心。
513
+ - 新增:页面有固定顶栏时,在 `:root` 上设 CSS 变量 `--semi-tooltip-viewport-inset-top`(顶栏高度,可写 `calc()`、`var()`),所有基于 Tooltip 的弹层把视口顶部这一段当作不可用:翻转与夹取都避开它,触发器整个落在顶栏下方时弹层隐藏。top layer 不受 `z-index` 影响,顶栏无法靠层级盖住弹层。打开时读取一次,打开期间修改要到下次打开才生效。
514
+ - 新增:Tooltip、Popover 与 Dropdown 的 ref 提供 `getPopup()`,返回当前弹层元素,未显示时为 `null`(Svelte 经 `bind:this` 调用,Dropdown 原有);React、Solid 的 Tooltip、Popover 新增 `aria-describedby`,`role="dialog"` 时落在弹层上,其他 role 不落弹层。
515
+ - 破坏性:删除 Tooltip、Popover、Popconfirm 的 `getPopupContainer`、`zIndex`、`margin`、`rePosKey`,`numbers.DEFAULT_Z_INDEX`、`MARGIN`、`ARROW_BOUNDING`,以及 `arrowBounding`、`transformFromCenter`、`ArrowBounding`;新增 `TooltipHandle.hide()`。`onEscKeyDown`、`onClickOutSide` 的参数类型改为原生 `KeyboardEvent`、`MouseEvent`。
516
+ - 行为变化:`closeOnEsc` 默认 `true`(Modal 内的提示先按 Esc 只关提示,旧行为传 `closeOnEsc={false}`);Popover 的 `disableFocusListener` 默认改为 `false`;新增 `afterOpen`(Vue `afterOpen` 事件,进场动画结束后调用)与 `onOpen`(Vue `open` 事件,弹层显示时调用,早于 `afterOpen`),Popover、Popconfirm、Dropdown 一并转发;受控 `visible` 只报告请求,触发器操作只报告 `onVisibleChange(true)`、关闭类操作只报告 `(false)`,React 在 `visible={false}` 时须在回调中回写才会打开。
517
+ - 行为变化:进出场改为 keyframes 动画(`semi-tooltip-zoom-in`、`semi-tooltip-zoom-out`),Popover、Dropdown 同样适用;关闭时弹层在出场动画期间仍为 `:popover-open`,动画结束才隐藏,出场中重新打开从头播放进场。覆盖过弹层 `transition` 的自定义样式改为覆盖 `animation`。
518
+ - 行为变化:弹层在打开回调执行前就被关闭(如 `trigger="focus"` 聚焦后立即失焦)时,先补报一次 `onVisibleChange(true)` 再报 `(false)`,两者成对。
519
+ - 行为变化:React 中触发元素卸载后仍显示的弹层,在外部按下时照常通知 `onClickOutSide` 并按触发方式关闭,与 Vue 一致。
520
+ - 行为变化:出场动画期间重新打开时,这次出场作废并立即调用一次 `afterClose`,每次显示都有自己的 `afterClose`(Modal、SideSheet 仍把它算作同一次显示)。在外部元素的 mousedown 处理中打开受控的 `trigger="custom"` 弹层时,同一次按下不再算点击外部。React、Solid 中 `trigger="custom"` 的弹层,在触发器内渲染的 Portal 里按下不算点击外部(Solid 只在 `onMouseDown` 经 `getTriggerProps` 传入时)。Popover 的箭头 svg 带 `aria-hidden="true"`。
521
+ - 行为变化:Select、AutoComplete、Cascader、TreeSelect 与 AIChatDialogue 的「更多」菜单打开时的点击外部改由弹层判断。React、Vue、Svelte 的 mousedown 监听从 `document` 移到 `window`(Solid 原本就在 `window`),在 `document` 上被 `stopPropagation()` 拦下的按下不再关闭下拉;TreeSelect 聚焦但未打开时的失焦判断仍监听 `document`。
522
+ - 行为变化:Select、TreeSelect、Cascader、AutoComplete 的下拉打开而焦点不在组件内时,按 Esc 也关闭下拉(原来 Esc 被弹层认领后没有任何反应);Select 在 `loading` 时仍不响应。
523
+ - 行为变化:hover、focus 触发的提示(`role="tooltip"`,含 hover 触发的 Popover)同一时间只显示一组:一个打开时关闭其他已打开的,几个在延迟内先后请求显示时只显示最后一个,嵌套在其触发器或弹层中的除外(参照 Radix Tooltip、React Aria);Dropdown 等其他 role 的弹层不参与。hover 触发的弹层(含 Dropdown)只在触发器 `:focus-visible` 时随聚焦打开,点击或鼠标关闭 Modal 后由脚本还回的焦点不再打开。
524
+ - 行为变化:hover 触发的弹层(含 Popover、Dropdown 及其子菜单、Navigation 弹出的子菜单)有指针宽限:鼠标离开触发器后,只要朝弹层一侧移动、且在离开点与弹层近侧两角围成的三角区内,弹层就保持打开,途中经过的其他 hover 触发器也不打开,最长 300ms(参照 Radix Menu)。离开三角区、反向移动或超时后,照常按 `mouseLeaveDelay` 关闭,指针此时停留的触发器再按 `mouseEnterDelay` 打开。默认开启,没有开关;只在主指针可悬停(`(hover: hover)`)时生效,键盘焦点打开的弹层不受影响。
525
+ - 行为变化:Tooltip、Popover、Dropdown 的弹层在关闭动画期间不响应指针(参照 Ant Design 的 leave motion)。原来指针扫过正在淡出、已经透明的弹层会让它重新打开,打开后又因触发器未被悬停而立即关闭,表现为菜单闪现。
526
+ - 行为变化:hover 触发的弹层在隐藏后重新显示时,若指针与焦点都已离开触发器与弹层则关闭;隐藏期间受控 `visible` 变为 false 或 `condition` 变为 false,重新显示时关闭。React 的 `<Activity>` 隐藏不再误发 `afterClose`;Svelte 无出场动画的关闭,`afterClose` 推迟一个微任务。
527
+ - Svelte:触发器默认包进 Tooltip 自己的 span(`semi-tooltip-trigger-wrapper`);可聚焦的触发器改用 `child` snippet:`{#snippet child({ props })}<button {...props}>…</button>{/snippet}`,`props` 带 `data-popupid`、`tabindex`、`aria-describedby` 和取元素引用的 attachment,必须整体展开;`role="dialog"` 且元素可承载弹层状态时另带 `aria-haspopup`、`aria-expanded`、`aria-controls`;包装 span 里有可聚焦元素时,span 退出 Tab 顺序并在开发期告警。
528
+ - Svelte:`visible` 可绑定,配 `onVisibleChange`;事件为 `onClickOutSide`、`onEscKeyDown`、`onOpen`、`afterOpen`、`afterClose`;`content({ initialFocusRef })` 的 `initialFocusRef` 是回调,可直接写 `{@attach initialFocusRef}`;箭头用 `arrow` snippet;`class`、`style` 只落在弹层上,`style` 只接受字符串,其中的 `background-color` 也给箭头着色;对外方法 `focusTrigger`、`getPopupId`、`hide`、`rePosition` 经 `bind:this` 调用。
529
+ - Svelte:不提供 `useTooltipDescription`(弹层 id 已在 `child` 的 `props` 里);弹层只在挂载后渲染,服务端不输出。
530
+ - Svelte:span 内唯一的子元素(Button 的组分隔线不算)是 Semi Button、IconButton、Switch、Checkbox 时,由它们向 Tooltip 登记:disabled 或 loading 的 Button、IconButton 在 `click`、`contextMenu` 触发(loading 时除 `custom` 外的所有触发)下由 span 接管指针;loading 的 Button 的 `aria-describedby` 与弹层状态落在按钮上,span 的 `tabindex` 为 -1;Switch、Checkbox 的描述落在 input 上,Tab 只停在 input;新增 `wrapWhenSpecial`(默认 true);原生 `<button disabled>` 与 `child` snippet 里的特殊触发器不识别,首帧与服务端不知道特殊状态,挂载后才补上。
531
+ - Svelte:`stopPropagation` 在弹层元素的 Svelte `onclick` 里执行(含 `stopImmediatePropagation`),弹层内容的 `onclick` 正常收到点击;在 Svelte 事件委托注册之前添加的 document 点击监听仍会收到事件,之后添加的收不到。
532
+ - Svelte:Popover 触发器写法同 Tooltip,可聚焦触发器用 `child` snippet 展开 `props`,不传时包进 Tooltip 的 span;内容用 `content({ initialFocusRef })` snippet;`visible` 可绑定,配 `onVisibleChange`,没有 `defaultVisible`;对话框名称键为 `'aria-label'`、`'aria-labelledby'`、`'aria-describedby'`;`class`、`style` 落在弹层上,`style` 只接受字符串,未传 `arrowStyle` 时箭头颜色读 `style` 里的 `background-color`、`border-color`;`focusTrigger()`、`rePosition()` 经 `bind:this` 调用;箭头 svg 带 `aria-hidden="true"`。
533
+ - 行为变化:`guardFocus` 的 Tab 环由 FocusTrapHandle 处理,焦点停在弹层容器本身时按 Tab 也被圈住;`guardFocus` 每次打开读取一次,打开期间修改要到下次打开才生效。`mouseLeaveDelay` 小于 `mouseEnterDelay` 的警告统一按 `(mouseLeaveDelay ?? 0) < (mouseEnterDelay ?? 0)` 判断,两个延时变化时重新检查。
534
+ - 行为变化:Vue、Solid、Svelte 的弹层在 KeepAlive 激活、`<Activity>` 重新显示时也会重新检查指针是否仍在触发器上(React 原本如此);Vue KeepAlive 失活时释放弹层的 layer。