@fibrae/semi-ui-svelte 0.9.0 → 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 (169) 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/cascader.svelte +1 -0
  16. package/dist/components/cascader/interface.d.ts +57 -0
  17. package/dist/components/checkbox/interface.d.ts +19 -0
  18. package/dist/components/code-highlight/interface.d.ts +3 -0
  19. package/dist/components/collapse/interface.d.ts +16 -0
  20. package/dist/components/collapsible/interface.d.ts +10 -0
  21. package/dist/components/color-picker/interface.d.ts +10 -0
  22. package/dist/components/config-provider/interface.d.ts +7 -0
  23. package/dist/components/cropper/interface.d.ts +11 -0
  24. package/dist/components/date-picker/interface.d.ts +47 -0
  25. package/dist/components/descriptions/interface.d.ts +6 -0
  26. package/dist/components/divider/interface.d.ts +4 -0
  27. package/dist/components/dropdown/interface.d.ts +8 -0
  28. package/dist/components/empty/interface.d.ts +7 -0
  29. package/dist/components/feedback/interface.d.ts +16 -0
  30. package/dist/components/float-button/interface.d.ts +14 -0
  31. package/dist/components/form/interface.d.ts +47 -0
  32. package/dist/components/form/label.svelte +2 -2
  33. package/dist/components/grid/interface.d.ts +13 -0
  34. package/dist/components/highlight/interface.d.ts +7 -0
  35. package/dist/components/hot-keys/interface.d.ts +3 -0
  36. package/dist/components/image/interface.d.ts +59 -0
  37. package/dist/components/input/interface.d.ts +67 -0
  38. package/dist/components/input-number/interface.d.ts +24 -0
  39. package/dist/components/json-viewer/interface.d.ts +7 -0
  40. package/dist/components/layout/interface.d.ts +3 -0
  41. package/dist/components/list/interface.d.ts +18 -0
  42. package/dist/components/locale/interface.d.ts +4 -0
  43. package/dist/components/lottie/interface.d.ts +2 -0
  44. package/dist/components/markdown-render/interface.d.ts +5 -0
  45. package/dist/components/modal/interface.d.ts +29 -0
  46. package/dist/components/navigation/interface.d.ts +47 -0
  47. package/dist/components/overflow-list/interface.d.ts +11 -0
  48. package/dist/components/pagination/interface.d.ts +12 -0
  49. package/dist/components/pincode/interface.d.ts +8 -0
  50. package/dist/components/popconfirm/interface.d.ts +12 -0
  51. package/dist/components/popover/interface.d.ts +30 -0
  52. package/dist/components/progress/interface.d.ts +13 -0
  53. package/dist/components/radio/interface.d.ts +22 -0
  54. package/dist/components/rating/interface.d.ts +12 -0
  55. package/dist/components/resizable/interface.d.ts +30 -0
  56. package/dist/components/scroll-list/interface.d.ts +6 -0
  57. package/dist/components/select/interface.d.ts +63 -0
  58. package/dist/components/side-sheet/interface.d.ts +19 -0
  59. package/dist/components/skeleton/interface.d.ts +7 -0
  60. package/dist/components/slider/interface.d.ts +23 -0
  61. package/dist/components/space/interface.d.ts +4 -0
  62. package/dist/components/spin/interface.d.ts +7 -0
  63. package/dist/components/steps/interface.d.ts +9 -0
  64. package/dist/components/switch/interface.d.ts +7 -0
  65. package/dist/components/table/interface.d.ts +48 -0
  66. package/dist/components/tabs/interface.d.ts +29 -0
  67. package/dist/components/tag/interface.d.ts +22 -0
  68. package/dist/components/tag-input/interface.d.ts +29 -0
  69. package/dist/components/time-picker/interface.d.ts +31 -0
  70. package/dist/components/timeline/interface.d.ts +5 -0
  71. package/dist/components/tooltip/interface.d.ts +20 -0
  72. package/dist/components/tooltip/tooltip.svelte +3 -0
  73. package/dist/components/transfer/interface.d.ts +18 -0
  74. package/dist/components/tree/interface.d.ts +45 -0
  75. package/dist/components/tree-select/interface.d.ts +55 -0
  76. package/dist/components/typography/interface.d.ts +33 -0
  77. package/dist/components/upload/interface.d.ts +64 -0
  78. package/dist/components/user-guide/interface.d.ts +15 -0
  79. package/dist/components/video-player/interface.d.ts +22 -0
  80. package/dist/styles.css +1 -1
  81. package/docs/advanced/dark-mode.md +288 -0
  82. package/docs/basic/button.md +605 -0
  83. package/docs/basic/divider.md +103 -0
  84. package/docs/basic/float-button.md +246 -0
  85. package/docs/basic/grid.md +427 -0
  86. package/docs/basic/layout.md +459 -0
  87. package/docs/basic/resizable.md +584 -0
  88. package/docs/basic/space.md +163 -0
  89. package/docs/basic/tokens.md +425 -0
  90. package/docs/basic/typography.md +615 -0
  91. package/docs/changes-from-semi.md +105 -0
  92. package/docs/ecosystem/tailwind.md +210 -0
  93. package/docs/experience/accessibility.md +82 -0
  94. package/docs/experience/content-guidelines.md +819 -0
  95. package/docs/experience/internationalization.md +7 -0
  96. package/docs/feedback/banner.md +198 -0
  97. package/docs/feedback/feedback.md +294 -0
  98. package/docs/feedback/notification.md +401 -0
  99. package/docs/feedback/popconfirm.md +243 -0
  100. package/docs/feedback/progress.md +389 -0
  101. package/docs/feedback/skeleton.md +388 -0
  102. package/docs/feedback/spin.md +172 -0
  103. package/docs/feedback/toast.md +393 -0
  104. package/docs/input/auto-complete.md +399 -0
  105. package/docs/input/cascader.md +1558 -0
  106. package/docs/input/checkbox.md +408 -0
  107. package/docs/input/color-picker.md +175 -0
  108. package/docs/input/date-picker.md +942 -0
  109. package/docs/input/form.md +2550 -0
  110. package/docs/input/input-number.md +451 -0
  111. package/docs/input/input.md +640 -0
  112. package/docs/input/pincode.md +191 -0
  113. package/docs/input/radio.md +337 -0
  114. package/docs/input/rating.md +214 -0
  115. package/docs/input/select.md +1230 -0
  116. package/docs/input/slider.md +347 -0
  117. package/docs/input/switch.md +206 -0
  118. package/docs/input/tag-input.md +465 -0
  119. package/docs/input/time-picker.md +358 -0
  120. package/docs/input/transfer.md +1061 -0
  121. package/docs/input/tree-select.md +1300 -0
  122. package/docs/input/upload.md +1811 -0
  123. package/docs/llms.txt +147 -0
  124. package/docs/navigation/anchor.md +377 -0
  125. package/docs/navigation/backtop.md +100 -0
  126. package/docs/navigation/breadcrumb.md +284 -0
  127. package/docs/navigation/navigation.md +851 -0
  128. package/docs/navigation/pagination.md +217 -0
  129. package/docs/navigation/steps.md +315 -0
  130. package/docs/navigation/tabs.md +754 -0
  131. package/docs/navigation/tree.md +1956 -0
  132. package/docs/other/config-provider.md +599 -0
  133. package/docs/other/locale.md +353 -0
  134. package/docs/plus/audio-player.md +155 -0
  135. package/docs/plus/code-highlight.md +150 -0
  136. package/docs/plus/drag-move.md +214 -0
  137. package/docs/plus/hot-keys.md +174 -0
  138. package/docs/plus/json-viewer.md +392 -0
  139. package/docs/plus/lottie.md +176 -0
  140. package/docs/plus/markdown-render.md +240 -0
  141. package/docs/plus/video-player.md +325 -0
  142. package/docs/show/avatar.md +475 -0
  143. package/docs/show/badge.md +276 -0
  144. package/docs/show/calendar.md +352 -0
  145. package/docs/show/card.md +485 -0
  146. package/docs/show/carousel.md +592 -0
  147. package/docs/show/collapse.md +289 -0
  148. package/docs/show/collapsible.md +216 -0
  149. package/docs/show/cropper.md +285 -0
  150. package/docs/show/descriptions.md +325 -0
  151. package/docs/show/dropdown.md +466 -0
  152. package/docs/show/empty.md +225 -0
  153. package/docs/show/highlight.md +144 -0
  154. package/docs/show/image.md +433 -0
  155. package/docs/show/list.md +927 -0
  156. package/docs/show/modal.md +517 -0
  157. package/docs/show/overflow-list.md +272 -0
  158. package/docs/show/popover.md +534 -0
  159. package/docs/show/scroll-list.md +156 -0
  160. package/docs/show/side-sheet.md +274 -0
  161. package/docs/show/table.md +5437 -0
  162. package/docs/show/tag.md +428 -0
  163. package/docs/show/timeline.md +277 -0
  164. package/docs/show/tooltip.md +442 -0
  165. package/docs/show/user-guide.md +419 -0
  166. package/docs/start/getting-started.md +234 -0
  167. package/docs/start/introduction.md +57 -0
  168. package/docs/start/overview.md +21 -0
  169. package/package.json +5 -4
@@ -0,0 +1,401 @@
1
+ # Notification
2
+
3
+ > Notifications are used to actively send message notifications to users.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/feedback/notification/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Notification } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ The static methods can only be called in the browser (calling them on the server throws); call them in event handlers. They read `Notification.config()`, the global defaults and the default locale, and do not inherit the ConfigProvider or LocaleProvider of their position; use `Notification.useNotification()` when you need those.
18
+
19
+ ### Basic Usage
20
+
21
+ Close after 3 seconds.
22
+
23
+ ```svelte
24
+ <script lang="ts">
25
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
26
+ </script>
27
+
28
+ <Button
29
+ onclick={() =>
30
+ Notification.open({
31
+ title: 'Hi, Semi',
32
+ content: 'ies dance dance dance',
33
+ duration: 3,
34
+ })}
35
+ >
36
+ Display Notification
37
+ </Button>
38
+ ```
39
+
40
+ ### Position
41
+
42
+ Use `position` to set pop up position, supporting one of: `top`、`bottom`、`topLeft`、`topRight`(default)、`bottomLeft`、`bottomRight`。
43
+
44
+ ```svelte
45
+ <script lang="ts">
46
+ import { Button, ButtonGroup, Notification } from '@fibrae/semi-ui-svelte';
47
+
48
+ const opts = {
49
+ duration: 3,
50
+ position: 'topRight',
51
+ content: 'semi-ui-notification',
52
+ title: 'Hi semi',
53
+ } as const;
54
+ </script>
55
+
56
+ <ButtonGroup>
57
+ <Button onclick={() => Notification.info({ ...opts, position: 'top' })}>top</Button>
58
+ <Button onclick={() => Notification.info({ ...opts, position: 'topLeft' })}>topLeft</Button>
59
+ <Button onclick={() => Notification.info(opts)}>topRight</Button>
60
+ </ButtonGroup>
61
+ <br />
62
+ <br />
63
+ <ButtonGroup>
64
+ <Button onclick={() => Notification.info({ ...opts, position: 'bottom' })}>bottom</Button>
65
+ <Button onclick={() => Notification.info({ ...opts, position: 'bottomRight' })}>bottomRight</Button>
66
+ <Button onclick={() => Notification.info({ ...opts, position: 'bottomLeft' })}>bottomLeft</Button>
67
+ </ButtonGroup>
68
+ ```
69
+
70
+ ### With Icons
71
+
72
+ Use different methods to show Notification with icons or you can pass in `icon` for customized icon.
73
+
74
+ ```svelte
75
+ <script lang="ts">
76
+ import { IconBell, IconHome } from '@fibrae/semi-icons-svelte';
77
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
78
+
79
+ const opts = {
80
+ title: 'Hi, Semi',
81
+ content: 'ies dance dance dance',
82
+ duration: 3,
83
+ };
84
+ </script>
85
+
86
+ {#snippet bell()}<IconBell style="color: red" />{/snippet}
87
+ {#snippet home()}<IconHome />{/snippet}
88
+ {#snippet pinkHome()}<IconHome style="color: pink" />{/snippet}
89
+
90
+ <h5>默认的图标</h5>
91
+ <Button style="margin: 4px" type="primary" onclick={() => Notification.success(opts)}>Success</Button>
92
+ <Button style="margin: 4px" onclick={() => Notification.info(opts)}>Info</Button>
93
+ <Button style="margin: 4px" type="warning" onclick={() => Notification.warning(opts)}>Warning</Button>
94
+ <Button style="margin: 4px" type="danger" onclick={() => Notification.error(opts)}>Error</Button>
95
+ <h5>自定义图标</h5>
96
+ <Button aria-label="铃铛图标通知" style="margin-inline-end: 5px" onclick={() => Notification.info({ ...opts, icon: bell })}>
97
+ {#snippet icon()}
98
+ <IconBell />
99
+ {/snippet}
100
+ </Button>
101
+ <Button aria-label="主页图标通知" style="margin-inline-end: 5px" onclick={() => Notification.info({ ...opts, icon: home })}>
102
+ {#snippet icon()}
103
+ <IconHome />
104
+ {/snippet}
105
+ </Button>
106
+ <Button aria-label="粉色主页图标通知" onclick={() => Notification.info({ ...opts, icon: pinkHome })}>
107
+ {#snippet icon()}
108
+ <IconHome />
109
+ {/snippet}
110
+ </Button>
111
+ ```
112
+
113
+ ### Colored Background
114
+
115
+ You could use `theme` for a colored background style. Default is `normal`.
116
+
117
+ ```svelte
118
+ <script lang="ts">
119
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
120
+
121
+ const opts = {
122
+ title: 'Hi, Semi',
123
+ content: 'Hi, Semi dance dance',
124
+ duration: 3,
125
+ theme: 'light',
126
+ } as const;
127
+ </script>
128
+
129
+ <Button onclick={() => Notification.info(opts)}>Info</Button>
130
+ <br />
131
+ <br />
132
+ <Button onclick={() => Notification.success(opts)}>Success</Button>
133
+ <br />
134
+ <br />
135
+ <Button type="warning" onclick={() => Notification.warning(opts)}>Warning</Button>
136
+ <br />
137
+ <br />
138
+ <Button type="danger" onclick={() => Notification.error(opts)}>Error</Button>
139
+ ```
140
+
141
+ ### Custom Children with Link
142
+
143
+ Use with Typography to create operation links for more complicated situations.
144
+
145
+ `title`, `content` and `icon` accept a string or a snippet: define it with `{#snippet}` in the component and pass it in; components such as Typography can be used directly inside the snippet.
146
+
147
+ ```svelte
148
+ <script lang="ts">
149
+ import { Button, Notification, Typography } from '@fibrae/semi-ui-svelte';
150
+ </script>
151
+
152
+ {#snippet content()}
153
+ <div>Hi, Semi dance dance</div>
154
+ <div style="margin-block-start: 8px">
155
+ <Typography.Text link>查看详情</Typography.Text>
156
+ <Typography.Text link style="margin-inline-start: 20px">一会再看</Typography.Text>
157
+ </div>
158
+ {/snippet}
159
+
160
+ <Button onclick={() => Notification.info({ title: 'This is a title', content, duration: 3 })}>Display Notification</Button>
161
+ ```
162
+
163
+ ### Delay
164
+
165
+ Use `duration` to set up time delay. By default it closes after 3 seconds.
166
+
167
+ ```svelte
168
+ <script lang="ts">
169
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
170
+
171
+ const opts = {
172
+ content: 'Hi, Semi dance dance',
173
+ duration: 10,
174
+ };
175
+ </script>
176
+
177
+ <Button onclick={() => Notification.info(opts)}>Close After 10s</Button>
178
+ ```
179
+
180
+ ### Manual Close
181
+
182
+ Set `duration` to 0 if you do not want the Notification to close by itself. In this case, it could only be closed manually.
183
+
184
+ ```svelte
185
+ <script lang="ts">
186
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
187
+
188
+ const opts = {
189
+ content: 'Not auto close',
190
+ title: 'Hi',
191
+ duration: 0,
192
+ };
193
+ const ids: string[] = [];
194
+
195
+ const show = () => {
196
+ ids.push(Notification.info(opts));
197
+ };
198
+
199
+ const hide = () => {
200
+ const first = ids.shift();
201
+ if (first) {
202
+ Notification.close(first);
203
+ }
204
+ };
205
+ </script>
206
+
207
+ <Button type="primary" onclick={show}>Show Notification</Button>
208
+ <br />
209
+ <br />
210
+ <Button type="primary" onclick={hide}>Hide Notification</Button>
211
+ ```
212
+
213
+ ### Stack
214
+
215
+ With `stack`, the notifications at one position stack once there are more than the threshold, and expand on hover. `true` sets the threshold to 3, and a number sets a custom one; a stack shows its front 3 layers only.
216
+
217
+ ```svelte
218
+ <script lang="ts">
219
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
220
+ </script>
221
+
222
+ <Button
223
+ onclick={() => {
224
+ Notification.info({ title: 'Hi', content: 'Hi, Semi dance dance', duration: 10, stack: true });
225
+ }}
226
+ >
227
+ Click multiple times
228
+ </Button>
229
+ ```
230
+
231
+ ### Update content
232
+
233
+ You can use id to update notification content.
234
+
235
+ ```svelte
236
+ <script lang="ts">
237
+ import { Button, Notification } from '@fibrae/semi-ui-svelte';
238
+
239
+ const show = () => {
240
+ const id = Notification.open({
241
+ title: 'Hi, Semi',
242
+ content: 'ies dance dance dance',
243
+ duration: 3,
244
+ });
245
+ setTimeout(() => {
246
+ Notification.open({
247
+ title: 'Hi, Semi',
248
+ content: 'updated',
249
+ duration: 10,
250
+ id,
251
+ });
252
+ }, 1000);
253
+ };
254
+ </script>
255
+
256
+ <Button onclick={show}>Display Notification</Button>
257
+ ```
258
+
259
+ ### Consume Context
260
+
261
+ Call `Notification.useNotification()` during component initialization: notifications inherit the context, ConfigProvider and locale of the calling component, no Holder is needed, and they enter and leave with the same animations as the static methods. They are mounted under `document.body` and removed when the calling component is destroyed. A snippet passed as `content`, `icon` or `title` can call `getContext` to read the calling component's context.
262
+
263
+ ```svelte
264
+ <script lang="ts">
265
+ import { getContext, setContext } from 'svelte';
266
+ import { Button, Notification, Space } from '@fibrae/semi-ui-svelte';
267
+
268
+ const reachableKey = Symbol('reachable');
269
+ setContext(reachableKey, 'Light');
270
+
271
+ const notification = Notification.useNotification();
272
+ const ids: string[] = [];
273
+
274
+ const show = () => {
275
+ ids.push(notification.info({ title: 'Hook Notification', content: reachable, duration: 0 }));
276
+ };
277
+
278
+ const hide = () => {
279
+ const first = ids.shift();
280
+ if (first) {
281
+ notification.close(first);
282
+ }
283
+ };
284
+ </script>
285
+
286
+ <!-- The snippet renders inside the list mounted with this component's contexts, so it reads the context set above -->
287
+ {#snippet reachable()}ReachableContext: {getContext(reachableKey)}{/snippet}
288
+
289
+ <Space>
290
+ <Button onclick={show}>Show Notification</Button>
291
+ <Button onclick={hide}>Hide Notification</Button>
292
+ </Space>
293
+ ```
294
+
295
+ ## API Reference
296
+
297
+ The static methods provided are as follows:
298
+
299
+ Display: You can pass in options object directly. Methods return the value of `id`: `const id = Notification.open({ /*...options*/ })`
300
+
301
+ - `Notification.open({content: 'message', duration: 3})`
302
+ - `Notification.info({content: 'message', duration: 3})`
303
+ - `Notification.error({content: 'message', duration: 3})`
304
+ - `Notification.warning({content: 'message', duration: 3})`
305
+ - `Notification.success({content: 'message', duration: 3})`
306
+
307
+ Close Manually (`id` is the return value of the display methods)
308
+
309
+ - `Notification.close(id)`
310
+
311
+ | Property | Description | Type | Default |
312
+ | - | - | - | - |
313
+ | class | Class name of the notification element | string \| object \| array | |
314
+ | content | Content, a string or a snippet; the snippet is rendered inside the notification | string \| Snippet | '' |
315
+ | direction | Text direction. A per-notification option only, not part of the global configuration; follows ConfigProvider when omitted | `ltr` \| `rtl` | |
316
+ | duration | Automatic close delay in seconds; 0 disables auto-close | number | 3 |
317
+ | getPopupContainer | The parent DOM node the popup renders into; it needs `position: relative`. This changes where the popup sits in the DOM tree, not where it is shown. Only takes effect when the container is first created | () => HTMLElement | () => document.body |
318
+ | icon | Icon at the top left, a string or a snippet | string \| Snippet | |
319
+ | id | Custom notification id; updates the content when a notification with the same id exists | string | |
320
+ | position | Pop-up position, one of `top`, `bottom`, `topLeft`, `topRight`, `bottomLeft`, `bottomRight` | string | `topRight` |
321
+ | showClose | Whether to show the close button | boolean | true |
322
+ | stack | Stack the notifications at one position once there are more than this many; `true` means 3, `false` never stacks. The newest notification at the position decides | boolean \| number | false |
323
+ | style | Inline style of the notification element, a string only | string | |
324
+ | theme | Style of background fill, one of `light`, `normal` | string | `normal` |
325
+ | title | Title, a string or a snippet | string \| Snippet | '' |
326
+ | zIndex | Z-index value. Applied each time a notification is shown. | number | 1010 |
327
+ | onClick | Called when the notification is clicked; lands on the notification element | (e: MouseEvent) => void | |
328
+ | onClose | Called when the notification closes, automatically or manually, once per close | () => void | |
329
+ | onCloseClick | Called when the close button is clicked | (id: string) => void | |
330
+
331
+ `class`, `style` and native attributes and events (such as `aria-*` and `data-*`) land on the root `div` of the notification. `onClick`, `onClose` and `onCloseClick` keep their key names in the options; pass functions directly.
332
+
333
+ The global configuration is set before any method call, and takes effect only once:
334
+
335
+ - `Notification.config(config)`
336
+ - `Notification.resetConfig()` restores the global configuration to its defaults; only notifications shown afterwards are affected
337
+
338
+ `Notification.config` does not accept `direction`; text direction is an option of a single notification only.
339
+
340
+ | Properties | Instructions | type | Default |
341
+ | - | - | - | - |
342
+ | bottom | Bottom, absolute position | number \| string | - |
343
+ | duration | Automatic close delay, no auto-close when set to 0 | number(second) | 3 |
344
+ | left | Left, absolute position | number \| string | - |
345
+ | position | Pop-up position, one of `top`、`bottom`、`topLeft`、`topRight`、`bottomLeft`、`bottomRight` | string | `topRight` |
346
+ | right | Right, absolute position | number \| string | - |
347
+ | stack | Stack the notifications at one position once there are more than this many; `true` means 3, `false` never stacks | boolean \| number | false |
348
+ | top | Top, absolute position | number \| string | - |
349
+ | zIndex | Z-index | number | 1010 |
350
+
351
+ Globally Destroy:
352
+
353
+ - `Notification.destroyAll()`
354
+
355
+ Hook Notification
356
+
357
+ - `Notification.useNotification()`\
358
+ Call it during component initialization; it returns the notification object. Notifications created through it can access the context of the calling component. The notification object has the methods `info`, `success`, `warning`, `error`, `open` and `close`; the first five take the options without `type`, `id`, `zIndex` and `getPopupContainer` and return the notification id, and `close(id)` closes one manually. Notifications created by the hook use the built-in defaults and ignore `Notification.config()`; `close(id)` removes the notification after its leave animation without calling `onClose`. The values of ConfigProvider and LocaleProvider cannot be read by the static `Notification`; use `useNotification()` when you need them.
359
+
360
+ ## Accessibility
361
+
362
+ ### ARIA
363
+
364
+ - The `role` of a notification depends on its type: `warning` and `error` are `alert`; `info`, `success` and `open` are `status`
365
+ - `status` notifications are read by a persistent `aria-live="polite"` region owned by the list; the notification itself is `aria-live="off"`, and only the text of the title and content is announced. `warning` and `error` still announce themselves as `alert`
366
+ - The notification's `aria-labelledby` is marked as the corresponding notification title
367
+
368
+ ### Keyboard and Focus
369
+
370
+ - The close button is a native `button`: focus it with `Tab`, and activate it with `Enter` or `Space`
371
+ - A notification does not take focus when it appears
372
+ - When the pointer or keyboard focus enters a notification, its auto-close timer pauses and a stack expands; both resume when it leaves
373
+
374
+ ## Content Guidelines
375
+
376
+ - Title
377
+ - Explain in clear and concise language
378
+ - Avoid punctuation such as commas, periods, etc.
379
+ - Text
380
+ - On the premise of complete information transmission, try to compress the text to 1-2 sentences
381
+ - A detailed description or explanation of the title, rather than a repetition of the title
382
+ - Use correct punctuation, commas within sentences and periods between sentences
383
+ - Operate
384
+ - The copy needs to show the specific meaning of the operation
385
+
386
+ ## Design Tokens
387
+
388
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/feedback/notification/>
389
+
390
+ ## Changes from Semi Design
391
+
392
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
393
+
394
+ - 破坏性:默认导出 `Notification` 由组件改为普通对象,只承载静态方法与 `useNotification`,删除未文档化的 `<Notification />` 树内渲染(改用 `useNotification` 的 `contextHolder`);删除 `NotificationListHandle`、`NoticeHandle`、`NoticeProps.onHookClose`、`NoticeState.visible`;`ConfigProps` 删除 `direction`,`NoticeInstance` 删除 `motion`;选项类型不再含 `close`、`ref`、`onAnimationEnd`、`onAnimationStart`。
395
+ - 新增 `Notification.resetConfig()` 与 `stack?: boolean | number`(`true` 为 3,同位置通知超过阈值时堆叠,悬停展开)及类型 `NotificationHookOptions`;悬停或键盘聚焦列表时全部通知暂停自动关闭;`useNotification` 的通知有进场、离场动画,并读取 `overrideDefaultProps.Notification`;`.semi-notification-notice` 上方 margin 改由 `.semi-notification-list` 的 `padding-block-start` 提供,覆盖过上方 margin 的需改覆盖列表 padding。
396
+ - 样式:堆叠中的 `.semi-notification-notice-stack-item` 改为单行 grid,展开收起由 `grid-template-rows` 过渡,覆盖其 `height` 的样式不再生效;不支持 `interpolate-size` 的浏览器在进出场动画期间给通知写内联 `height`。
397
+ - Svelte:提供静态 `Notification`(`open`、`info`、`success`、`warning`、`error`、`close`、`destroyAll`、`config`、`resetConfig`、`addNotice`、`removeNotice`)和 `Notification.useNotification()`,没有 Vue 的 `Notification.install(app)`;`title`、`content`、`icon` 接受字符串或 snippet,`onClick` 签名为 `(event: MouseEvent) => void`,落在通知元素上;没有 `type` 且自定义 `icon` 时,图标元素不再带 `-undefined` 类名。
398
+ - Svelte:`Notification.useNotification()` 在组件初始化时调用,只返回 `api`,没有 Holder:通知挂在 `document.body`,读调用组件所在处的 context、ConfigProvider 与语言包,调用组件销毁时一并移除;容器带 `data-semi-keep-interactive`,模态层打开时仍可交互。
399
+ - 同一批内更新一条通知再新增另一条时,被更新的通知仍重新计时。
400
+ - React、Vue:静态方法与 `useNotification` 的选项类型并入通知元素的原生属性(`dir`、`onMouseEnter` 等),与运行时透传一致(F6)。
401
+ - 行为变化:`useNotification` 返回的 id 前缀由 `semi_notice_` 改为 `notification-`;列表处于悬停或聚焦暂停时新挂载的通知从一开始就不计时,四个框架一致。
@@ -0,0 +1,243 @@
1
+ # Popconfirm
2
+
3
+ > Used when the operation of the target element requires further confirmation from the user. Compared with Popover, it has a built-in series of configurable action buttons. Compared with Modal, it does not force full-screen centering, and the interaction is lighter.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/feedback/popconfirm/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Popconfirm } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ `Popconfirm` is based on the `Tooltip` component. Children support the same type as `Tooltip`. For details, please refer to [Tooltip Cautions](../show/tooltip.md#Cautions)
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { Button, Popconfirm, Toast } from '@fibrae/semi-ui-svelte';
24
+
25
+ const onConfirm = () => {
26
+ Toast.success('确认保存!');
27
+ };
28
+
29
+ const onCancel = () => {
30
+ Toast.warning('取消保存!');
31
+ };
32
+ </script>
33
+
34
+ <Popconfirm {onCancel} {onConfirm} title="确定是否要保存此修改?">
35
+ <Button>保存</Button>
36
+ {#snippet content()}此修改将不可逆{/snippet}
37
+ </Popconfirm>
38
+ ```
39
+
40
+ ### Type collocation
41
+
42
+ Developers can use scenario-based `okType`/`cancelType` and the `icon` snippet to match different styles of bubble confirmation boxes. Without `icon` the default warning icon is shown; `icon={null}` renders no icon.
43
+
44
+ ```svelte
45
+ <script lang="ts">
46
+ import { IconAlertTriangle } from '@fibrae/semi-icons-svelte';
47
+ import { Button, Popconfirm, Radio, RadioGroup, type RadioValue } from '@fibrae/semi-ui-svelte';
48
+
49
+ type TypeKey = 'default' | 'warning' | 'danger' | 'tertiary';
50
+
51
+ const typeMap: Record<TypeKey, { okType?: 'danger'; color?: string }> = {
52
+ default: {},
53
+ warning: { color: 'var(--semi-color-warning)' },
54
+ danger: { okType: 'danger', color: 'var(--semi-color-danger)' },
55
+ tertiary: { color: 'var(--semi-color-tertiary)' },
56
+ };
57
+ const keys = Object.keys(typeMap) as TypeKey[];
58
+ let value = $state<RadioValue | undefined>('default');
59
+ let visible = $state(true);
60
+ const type = $derived(keys.find((key) => key === value) ?? 'default');
61
+ </script>
62
+
63
+ <div>
64
+ <RadioGroup bind:value style="margin-block-start: 14px; margin-block-end: 14px" type="button">
65
+ {#each keys as key (key)}
66
+ <Radio value={key}>
67
+ <span style={`color: var(--semi-color-${key === 'default' ? 'primary' : key})`}>{key}</span>
68
+ </Radio>
69
+ {/each}
70
+ </RadioGroup>
71
+ <div>
72
+ <Popconfirm bind:visible okType={typeMap[type].okType} title="确定是否要保存此修改?" trigger="custom">
73
+ <Button onclick={() => (visible = !visible)}>点击此处</Button>
74
+ {#snippet icon()}
75
+ <IconAlertTriangle size="extra-large" style={typeMap[type].color ? `color: ${typeMap[type].color}` : undefined} />
76
+ {/snippet}
77
+ {#snippet content()}此修改将不可逆{/snippet}
78
+ </Popconfirm>
79
+ </div>
80
+ </div>
81
+ ```
82
+
83
+ ### Delay hide
84
+
85
+ `onConfirm` and `onCancel` can be closed after click through return Promise.\
86
+ When onCancel and onConfirm are triggered, the corresponding Button will automatically switch to `loading: true`\
87
+ promise solve will close the bubble confirmation box, the bubble will remain when promise reject, and button loading will automatically switch to false
88
+
89
+ ```svelte
90
+ <script lang="ts">
91
+ import { Button, Popconfirm } from '@fibrae/semi-ui-svelte';
92
+
93
+ const onConfirm = () =>
94
+ new Promise<void>((resolve) => {
95
+ setTimeout(() => {
96
+ console.log('resolve,close popconfirm');
97
+ resolve();
98
+ }, 2000);
99
+ });
100
+
101
+ const onCancel = () =>
102
+ new Promise<void>((_resolve, reject) => {
103
+ setTimeout(() => {
104
+ console.log('reject, popconfirm still exist');
105
+ reject();
106
+ }, 2000);
107
+ });
108
+ </script>
109
+
110
+ <Popconfirm {onCancel} {onConfirm} title="确定是否要保存此修改?">
111
+ <Button>保存</Button>
112
+ {#snippet content()}此修改将不可逆{/snippet}
113
+ </Popconfirm>
114
+ ```
115
+
116
+ ### Initialize the Focus Position of Popup Layer
117
+
118
+ `okButtonProps` and `cancelButtonProps` support passing in the `autoFocus` parameter, which will automatically focus at this position when the panel is opened.
119
+
120
+ The `content` snippet receives `{ initialFocusRef }` as its argument. Bind it to the focusable DOM or component with `{@attach initialFocusRef}`, and it will automatically focus at this position when the panel is opened. When a button `autoFocus` and `initialFocusRef` are both given, the button wins.
121
+
122
+ ```svelte
123
+ <script lang="ts">
124
+ import { Button, Popconfirm, Space } from '@fibrae/semi-ui-svelte';
125
+ </script>
126
+
127
+ <Space>
128
+ <Popconfirm okButtonProps={{ autoFocus: true, type: 'danger' }} title="确定是否要保存此修改?">
129
+ <Button>确认聚焦</Button>
130
+ {#snippet content()}此修改将不可逆{/snippet}
131
+ </Popconfirm>
132
+ <Popconfirm cancelButtonProps={{ autoFocus: true }} title="确定是否要保存此修改?">
133
+ <Button>取消聚焦</Button>
134
+ {#snippet content()}此修改将不可逆{/snippet}
135
+ </Popconfirm>
136
+ <Popconfirm title="确定是否要保存此修改?">
137
+ <Button>内容聚焦</Button>
138
+ {#snippet content(focus)}
139
+ <input {@attach focus.initialFocusRef} placeholder="focus here" />
140
+ {/snippet}
141
+ </Popconfirm>
142
+ </Space>
143
+ ```
144
+
145
+ ### Use with Tooltip or Popover
146
+
147
+ Please refer to [Use with Tooltip/Popover](../show/tooltip.md#Use%20with%20Popver%20or%20Popconfirm)
148
+
149
+ ## API Reference
150
+
151
+ **Props**
152
+
153
+ | Property | Description | Type | Default |
154
+ | - | - | - | - |
155
+ | afterClose | Called after the card has closed and its leave animation has finished. | `TooltipProps['afterClose']` | - |
156
+ | afterOpen | Called after the card 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']` | - |
157
+ | aria-describedby | aria-describedby of the dialog. Defaults to the content when there are both a title and content. | `string` | - |
158
+ | aria-label | aria-label of the dialog. When given, it takes precedence over the title. | `string` | - |
159
+ | aria-labelledby | aria-labelledby of the dialog. Defaults to the title, or to the content without a title. | `string` | - |
160
+ | arrowPointAtCenter | Whether the arrow points at the center of the trigger. Requires showArrow. | `boolean` | - |
161
+ | autoAdjustOverflow | Whether the popup flips automatically when it would be clipped. | `boolean` | - |
162
+ | cancelButtonProps | Props of the cancel button. autoFocus focuses it on open; onclick runs before the built-in cancel handling. | `PopconfirmButtonProps` | - |
163
+ | cancelText | Cancel button text. Defaults to the locale entry Popconfirm.cancel. | `string` | - |
164
+ | cancelType | Type of the cancel button. | `ButtonType` | `"tertiary"` |
165
+ | 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']` | - |
166
+ | children | Snippet for the trigger. It is wrapped in Tooltip's own span, which receives the trigger attributes. | `TooltipProps['children']` | - |
167
+ | class | Class name of the confirmation card. | `string` | - |
168
+ | classNames | Class names of the inner parts, keyed by `content` (the content container `.semi-popover` inside the popup) and `arrow`; merged with the built-in classes. The class of the confirmation card `.semi-popconfirm` is set with `class`. | `Partial<Record<PopconfirmPart, ClassValue>>` | - |
169
+ | clickToHide | Whether a click on the popup or anything inside it closes it. | `boolean` | - |
170
+ | closeOnEsc | Whether Esc closes the open card. With trigger custom it only calls onEscKeyDown and the caller decides whether to close. | `boolean` | - |
171
+ | condition | Whether it may be triggered. Only an explicit false disables the hover, click and focus triggers. Changing it from true to false closes an open card at once; with a controlled visible it only calls onVisibleChange(false), and the card closes once the caller writes back. | `boolean` | - |
172
+ | content | Snippet for the content of the card. Its argument `{ initialFocusRef }` is a callback; write `{@attach initialFocusRef}` to bind it to the element that receives focus on open. Omitted, no content area is rendered. | `Snippet<[RenderContentProps]>` | - |
173
+ | disableArrowKeyDown | Whether the arrow keys on the trigger are prevented from moving focus into the card. | `boolean` | - |
174
+ | disabled | Whether it is disabled. A disabled Popconfirm renders only the trigger and never opens. | `boolean` | `false` |
175
+ | disableFocusListener | Whether keyboard focus is ignored when trigger is hover. | `boolean` | - |
176
+ | guardFocus | Whether Tab cycles inside the card while focus is in it. | `boolean` | - |
177
+ | icon | Snippet for a custom icon. The default warning icon shows when omitted; `null` renders no icon. | `Snippet \| null` | - |
178
+ | keepDOM | Whether the content stays mounted while closed. | `boolean` | - |
179
+ | motion | Whether the popup is animated. | `boolean` | - |
180
+ | mouseEnterDelay | Milliseconds before the card shows after the pointer enters. Applies to the hover and focus triggers. | `number` | - |
181
+ | mouseLeaveDelay | Milliseconds before the card hides after the pointer leaves. Applies to the hover and focus triggers. | `number` | - |
182
+ | okButtonProps | Props of the confirm button. autoFocus focuses it on open; onclick runs before the built-in confirm handling. | `PopconfirmButtonProps` | - |
183
+ | okText | Confirm button text. Defaults to the locale entry Popconfirm.confirm. | `string` | - |
184
+ | okType | Type of the confirm button. | `ButtonType` | `"primary"` |
185
+ | onCancel | Called when the cancel or close button is clicked, with the button's native click event. A returned Promise keeps the button loading and closes the card once it resolves; a rejection keeps it open. | `(event: MouseEvent) => Promise<unknown> \| void` | - |
186
+ | onClickOutSide | Called when the mouse is pressed outside of the trigger and the open card. Only for trigger click, contextMenu or custom. | `TooltipProps['onClickOutSide']` | - |
187
+ | onConfirm | Called when the confirm button is clicked, with the button's native click event. A returned Promise keeps the button loading and closes the card once it resolves; a rejection keeps it open. | `(event: MouseEvent) => Promise<unknown> \| void` | - |
188
+ | onEscKeyDown | Called when Esc is pressed while the card is open and closeOnEsc is true. | `TooltipProps['onEscKeyDown']` | - |
189
+ | onOpen | Called once per opening when the card 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']` | - |
190
+ | onVisibleChange | Called when the visibility changes; with a controlled visible it reports only requests from user interaction, not changes the caller makes to visible. | `TooltipProps['onVisibleChange']` | - |
191
+ | position | Position of the popup relative to the trigger element, in twelve directions. | `TooltipProps['position']` | - |
192
+ | returnFocusOnClose | Whether focus returns to the trigger after closing. It also works with a controlled visible, and has no effect with trigger custom. | `boolean` | - |
193
+ | role | ARIA role of the popup. Defaults to dialog. | `string` | `"dialog"` |
194
+ | showArrow | Whether the arrow is shown. | `boolean` | - |
195
+ | showCloseIcon | Whether the close button in the corner is shown. | `boolean` | `true` |
196
+ | spacing | Distance in pixels between the popup and the trigger. An object sets the horizontal and vertical distances. | `number \| { x: number; y: number }` | - |
197
+ | stopPropagation | Whether click, mousedown and focus in/out events on the popup stop propagating. | `boolean \| string` | `true` |
198
+ | style | Style string of the confirmation card. | `string` | - |
199
+ | styles | Inline styles of the inner parts, keyed like `classNames`. `content` is the style string of the content container; `arrow` holds the arrow's borderColor, backgroundColor and borderOpacity. | `{ content?: string; arrow?: ArrowStyle }` | - |
200
+ | title | Title, a string or a snippet, which also names the dialog. | `string \| Snippet` | - |
201
+ | trigger | When the card shows: hover, focus, click, contextMenu or custom. With custom, visible alone decides. | `TooltipProps['trigger']` | `"click"` |
202
+ | visible | Whether it is shown; bind it with `bind:visible`. When given, this value decides; trigger keeps its value and the trigger events still work. | `boolean` | - |
203
+
204
+ **Methods**
205
+
206
+ | Method | Description | Type |
207
+ | - | - | - |
208
+ | focusTrigger | Focuses the trigger. Only works when returnFocusOnClose is true and trigger is not custom; does nothing when disabled. | `() => void` |
209
+
210
+ `class` and `style` land on the confirmation card, and the props in `okButtonProps` and `cancelButtonProps` land on their buttons (except `autoFocus`); `bind:this` receives the `focusTrigger` handle. Popconfirm has no root DOM element, so other undeclared native attributes and events are dropped.
211
+
212
+ ## Accessibility
213
+
214
+ ### ARIA
215
+
216
+ - Whatever the trigger, `hover` and `focus` included, the Popconfirm popup has role `dialog`, named by `title` (by `content` when there is no `title`); the `role` prop overrides it
217
+ - For the rest, please refer to [Popover](../show/popover.md#ARIA)
218
+
219
+ ### Keyboard and focus
220
+
221
+ - Popconfirm must have trigger, trigger can be focused, use `Enter` key to open Popconfirm
222
+ - After Popconfirm is activated, press the arrow key ⬇️ to move the focus to Popconfirm. The initial focus of Popconfirm should follow several principles:
223
+ - If the Popconfirm contains the last step of an irreversible process, such as: deleting data, etc., then this initial focus is preferably on the least destructive interactable element, such as: the cancel button (by passing the `autoFocus` to the object `cancelButtonProps`)
224
+ - If you only read text in Popconfirm, it is recommended to set the initial focus on the most likely interactive elements, such as: confirm button (implemented by passing `autoFocus` to the object `okButtonProps` )
225
+ - Keyboard users can dismiss Popconfirm by pressing `Esc` and focus should return to the trigger. After the user closes the Pop through the interactive element within the Popconfirm, the focus should also return to the trigger (except when trigger is `custom`)
226
+ - When it is opened, after the user clicks `Esc` in the blank space in Popconfirm, the focus will also return to the trigger (except when trigger is `custom`)
227
+
228
+ ## Design Tokens
229
+
230
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/feedback/popconfirm/>
231
+
232
+ ## Changes from Semi Design
233
+
234
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
235
+
236
+ - 破坏性:删除 `contentClassName`、`arrowStyle`,改用 `classNames`、`styles` 的 `content`、`arrow` 键,转发给内部 Popover;确认卡片的类名与样式仍用 `className`、`style`。
237
+ - 破坏性(类型):`onConfirm`、`onCancel` 参数改为原生 `MouseEvent`;ref 为 `PopconfirmHandle { focusTrigger }`。`okButtonProps`、`cancelButtonProps` 的 `onClick` 改为追加调用(先调用使用方的,再执行内置确认、取消流程,原来替换内置流程);`icon` 接受任意 ReactNode。
238
+ - 行为变化:`visible` 受控时 `trigger` 不再强制为 `custom`,点击、悬停调用 `onVisibleChange(true)` 请求打开,点击外部与 Esc 调用 `onVisibleChange(false)`,由使用方回写;使用方自行改变 `visible` 不再上报。确认框真正关闭时才把焦点还给触发元素;所有触发方式的弹层都是 `role="dialog"`,以标题命名。
239
+ - 确认框渲染在 shadow root 内时,焦点已移到主文档的元素后关闭,焦点不再被拉回触发元素。
240
+ - 行为变化:footer 挂载后,四个框架都直接聚焦 `autoFocus` 按钮,同时把它交给 Tooltip 作初始焦点(原来 React、Solid 在 footer 晚挂载时只交给 Tooltip);最终焦点落点不变。
241
+ - Svelte:`title` 接受字符串或 snippet;`content` 是 snippet,参数含 `initialFocusRef`;`icon` 是 snippet,传 `null` 不显示图标,空 snippet 无法判断,照常显示图标框;可见性用可绑定的 `visible` 配 `onVisibleChange`,没有 `defaultVisible`;`okButtonProps`、`cancelButtonProps` 的 `onclick` 先于内置的确认、取消流程调用,`autoFocus` 不落到 DOM;`class`、`style` 落在 `.semi-popconfirm` 卡片上;`stopPropagation={false}` 时,卡片内的点击会到达 document 与外层监听;`focusTrigger()` 经 `bind:this` 调用。
242
+ - `disabled` 与启用之间切换时触发器不再重新挂载,焦点与内部状态保留;禁用时触发器也带 Tooltip 的 aria 属性与 `data-popupid`。
243
+ - React、Solid:使用方传入的 `aria-describedby` 落在确认框上,优先于默认指向内容的描述(同时有标题与内容时)。