@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,419 @@
1
+ # UserGuide
2
+
3
+ > Used to guide new users through pages
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/user-guide/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { UserGuide } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ ```svelte
20
+ <script lang="ts">
21
+ import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
22
+
23
+ let visible = $state(false);
24
+ const steps: UserGuideStepItem[] = [
25
+ {
26
+ target: () => document.querySelector('#basic-demo-1'),
27
+ title: '新手引导',
28
+ description: 'Hello Semi!',
29
+ position: 'bottom',
30
+ },
31
+ {
32
+ target: () => document.querySelector('#basic-demo-2'),
33
+ title: 'Switch',
34
+ description: 'This is a Semi Switch',
35
+ position: 'bottom',
36
+ },
37
+ {
38
+ target: () => document.querySelector('#basic-demo-3'),
39
+ title: 'Button',
40
+ description: 'This is a Semi Button',
41
+ position: 'bottom',
42
+ },
43
+ ];
44
+ </script>
45
+
46
+ <div>
47
+ <Button onclick={() => (visible = true)}>开始引导</Button>
48
+ <br />
49
+ <br />
50
+ <Space>
51
+ <Switch aria-label="示例开关" checked id="basic-demo-1" />
52
+ <Tag id="basic-demo-2">Default Tag</Tag>
53
+ <Button id="basic-demo-3">确定</Button>
54
+ </Space>
55
+ <UserGuide bind:visible mask mode="popup" onChange={(current) => console.log('当前引导步骤', current)} onFinish={() => console.log('引导完成')} onNext={() => console.log('下一步引导')} onPrev={() => console.log('上一步引导')} onSkip={() => console.log('跳过引导')} {steps} />
56
+ </div>
57
+ ```
58
+
59
+ ### Theme
60
+
61
+ `popup` bubble card mode provides two themes `default` and `primary`, set by the `theme` property.
62
+
63
+ ```svelte
64
+ <script lang="ts">
65
+ import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
66
+
67
+ let visible = $state(false);
68
+ const steps: UserGuideStepItem[] = [
69
+ {
70
+ target: () => document.querySelector('#theme-demo-1'),
71
+ title: '新手引导',
72
+ description: 'Hello Semi!',
73
+ position: 'bottom',
74
+ },
75
+ {
76
+ target: () => document.querySelector('#theme-demo-2'),
77
+ title: 'Switch',
78
+ description: 'This is a Semi Switch',
79
+ position: 'bottom',
80
+ },
81
+ {
82
+ target: () => document.querySelector('#theme-demo-3'),
83
+ title: 'Button',
84
+ description: 'This is a Semi Button',
85
+ position: 'bottom',
86
+ },
87
+ ];
88
+ </script>
89
+
90
+ <div>
91
+ <Button onclick={() => (visible = true)}>开始引导</Button>
92
+ <br />
93
+ <br />
94
+ <Space>
95
+ <Switch aria-label="示例开关" checked id="theme-demo-1" />
96
+ <Tag id="theme-demo-2">Default Tag</Tag>
97
+ <Button id="theme-demo-3">确定</Button>
98
+ </Space>
99
+ <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} theme="primary" />
100
+ </div>
101
+ ```
102
+
103
+ ### Popup position
104
+
105
+ `popup` bubble card mode provides 16 positions, optional values are `top`, `topLeft`, `topRight`, `left`, `leftTop`, `leftBottom`, `right`, `rightTop`, `rightBottom`, `bottom`, `bottomLeft`, `bottomRight`, `leftTopOver`, `rightTopOver`, `leftBottomOver`, `rightBottomOver`, and can be set by the `showArrow` property to display the arrow.
106
+
107
+ ```svelte
108
+ <script lang="ts">
109
+ import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
110
+
111
+ let visible = $state(false);
112
+ const steps: UserGuideStepItem[] = [
113
+ {
114
+ target: () => document.querySelector('#position-demo'),
115
+ title: '新手引导',
116
+ description: 'Hello Semi!',
117
+ position: 'top',
118
+ },
119
+ {
120
+ target: () => document.querySelector('#position-demo'),
121
+ title: 'New Position',
122
+ description: 'This is Right Position',
123
+ position: 'right',
124
+ },
125
+ {
126
+ target: () => document.querySelector('#position-demo'),
127
+ title: 'Hide Arrow',
128
+ description: 'We hide the arrow',
129
+ position: 'bottom',
130
+ showArrow: false,
131
+ },
132
+ ];
133
+ </script>
134
+
135
+ <div>
136
+ <Button id="position-demo" onclick={() => (visible = true)}>开始引导</Button>
137
+ <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
138
+ </div>
139
+ ```
140
+
141
+ ### Set the size of the highlight area
142
+
143
+ Set by the `spotlightPadding` property.
144
+
145
+ ```svelte
146
+ <script lang="ts">
147
+ import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
148
+
149
+ let visible = $state(false);
150
+ const steps: UserGuideStepItem[] = [
151
+ {
152
+ target: () => document.querySelector('#padding-demo-1'),
153
+ title: '新手引导',
154
+ description: 'Hello Semi!',
155
+ },
156
+ {
157
+ target: () => document.querySelector('#padding-demo-2'),
158
+ title: 'New Padding',
159
+ description: 'This is 10px padding',
160
+ },
161
+ {
162
+ target: () => document.querySelector('#padding-demo-3'),
163
+ title: 'Change Padding',
164
+ spotlightPadding: 15,
165
+ description: 'We change the Padding to 15px',
166
+ },
167
+ ];
168
+ </script>
169
+
170
+ <div>
171
+ <Button onclick={() => (visible = true)}>开始引导</Button>
172
+ <br />
173
+ <br />
174
+ <Space>
175
+ <Switch aria-label="示例开关" checked id="padding-demo-1" />
176
+ <Tag id="padding-demo-2">Default Tag</Tag>
177
+ <Button id="padding-demo-3">确定</Button>
178
+ </Space>
179
+ <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} spotlightPadding={10} {steps} />
180
+ </div>
181
+ ```
182
+
183
+ ### Customize the button
184
+
185
+ Set by the `nextButtonProps` and `prevButtonProps` properties.
186
+
187
+ Use the `nextText` and `prevText` snippets for the button text. The text of the button on the last step is set by `finishText`.
188
+
189
+ ```svelte
190
+ <script lang="ts">
191
+ import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
192
+
193
+ let visible = $state(false);
194
+ const steps: UserGuideStepItem[] = [
195
+ {
196
+ target: () => document.querySelector('#button-demo-1'),
197
+ title: '新手引导',
198
+ description: 'Hello Semi!',
199
+ },
200
+ {
201
+ target: () => document.querySelector('#button-demo-2'),
202
+ title: 'New Button Style',
203
+ description: 'Button text is Next',
204
+ },
205
+ {
206
+ target: () => document.querySelector('#button-demo-3'),
207
+ title: 'New finish button text',
208
+ description: 'Button text is I know',
209
+ },
210
+ ];
211
+ </script>
212
+
213
+ <div>
214
+ <Button onclick={() => (visible = true)}>开始引导</Button>
215
+ <br />
216
+ <br />
217
+ <Space>
218
+ <Switch aria-label="示例开关" checked id="button-demo-1" />
219
+ <Tag id="button-demo-2">Default Tag</Tag>
220
+ <Button id="button-demo-3">确定</Button>
221
+ </Space>
222
+ <UserGuide bind:visible finishText="我知道啦!" mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} prevButtonProps={{ theme: 'borderless' }} {steps}>
223
+ {#snippet nextText()}Next{/snippet}
224
+ {#snippet prevText()}Prev{/snippet}
225
+ </UserGuide>
226
+ </div>
227
+ ```
228
+
229
+ ### Controlled
230
+
231
+ Set by the `current` property.
232
+
233
+ Bind the current step with `bind:current` and the visibility with `bind:visible`.
234
+
235
+ ```svelte
236
+ <script lang="ts">
237
+ import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
238
+
239
+ let visible = $state(false);
240
+ let current = $state(0);
241
+ const steps: UserGuideStepItem[] = [
242
+ {
243
+ target: () => document.querySelector('#controlled-demo-1'),
244
+ title: '新手引导',
245
+ description: 'Hello Semi!',
246
+ position: 'bottom',
247
+ },
248
+ {
249
+ target: () => document.querySelector('#controlled-demo-2'),
250
+ title: 'Switch',
251
+ description: 'This is a Semi Switch',
252
+ position: 'bottom',
253
+ },
254
+ {
255
+ target: () => document.querySelector('#controlled-demo-3'),
256
+ title: 'Button',
257
+ description: 'This is a Semi Button',
258
+ position: 'bottom',
259
+ },
260
+ ];
261
+ </script>
262
+
263
+ <div>
264
+ <Button onclick={() => (visible = true)}>开始引导</Button>
265
+ <br />
266
+ <br />
267
+ <Space>
268
+ <Switch aria-label="示例开关" checked id="controlled-demo-1" />
269
+ <Tag id="controlled-demo-2">Default Tag</Tag>
270
+ <Button id="controlled-demo-3">确定</Button>
271
+ </Space>
272
+ <UserGuide
273
+ bind:current
274
+ bind:visible
275
+ mask
276
+ mode="popup"
277
+ onFinish={() => {
278
+ current = 0;
279
+ console.log('引导完成');
280
+ }}
281
+ onSkip={() => {
282
+ current = 0;
283
+ console.log('跳过引导');
284
+ }}
285
+ {steps}
286
+ />
287
+ </div>
288
+ ```
289
+
290
+ ### Modal guide
291
+
292
+ Set by the `mode` property.
293
+
294
+ Use the `cover` snippet in the step data for the cover, and write `description` as a snippet for rich-text descriptions; a snippet receives `{ item, index }`.
295
+
296
+ ```svelte
297
+ <script lang="ts">
298
+ import { Button, Image, Typography, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
299
+
300
+ let visible = $state(false);
301
+ const covers = ['/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg', '/assets/root-web-sites/colorful.jpg'];
302
+ const steps: UserGuideStepItem[] = [
303
+ { title: '欢迎使用 Semi Design Next!', description: welcome, cover, position: 'bottom' },
304
+ { title: '高可用的色盘', description: '选取主色后,我们的颜色算法会为你生成一套高可用的色盘', cover, position: 'bottom' },
305
+ { title: '自由定制', description: '开始定制属于你的设计系统吧!', cover, position: 'bottom' },
306
+ ];
307
+ </script>
308
+
309
+ {#snippet welcome()}
310
+ <div>你可以从已发布的主题出发,或者选择<Typography.Text strong>立即创造</Typography.Text>来创造一个新的主题</div>
311
+ {/snippet}
312
+
313
+ {#snippet cover(renderProps: { index: number })}
314
+ <Image height="100%" src={covers[renderProps.index]} width="600px" />
315
+ {/snippet}
316
+
317
+ <div>
318
+ <Button onclick={() => (visible = true)}>开始引导</Button>
319
+ <UserGuide bind:visible mask mode="modal" onChange={(current) => console.log('当前引导步骤', current)} onFinish={() => console.log('引导完成')} onNext={() => console.log('下一步引导')} onPrev={() => console.log('上一步引导')} onSkip={() => console.log('跳过引导')} {steps} />
320
+ </div>
321
+ ```
322
+
323
+ ### No mask
324
+
325
+ Set by the `mask` property.
326
+
327
+ ```svelte
328
+ <script lang="ts">
329
+ import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';
330
+
331
+ let visible = $state(false);
332
+ const steps: UserGuideStepItem[] = [
333
+ {
334
+ target: () => document.querySelector('#mask-demo'),
335
+ title: 'No Mask',
336
+ description: 'Hello Semi!',
337
+ },
338
+ ];
339
+ </script>
340
+
341
+ <div>
342
+ <Button id="mask-demo" onclick={() => (visible = true)}>开始引导</Button>
343
+ <UserGuide bind:visible mask={false} mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
344
+ </div>
345
+ ```
346
+
347
+ ## API Reference
348
+
349
+ ---
350
+
351
+ **Props**
352
+
353
+ | Property | Description | Type | Default |
354
+ | - | - | - | - |
355
+ | class | Lands on the popover card in popup mode and on the outermost element of the Modal in modal mode. | `string` | - |
356
+ | current | Index of the current step, bound with `bind:current`. Without it the component keeps the index itself, starting at 0. | `number` | - |
357
+ | finishText | Text of the finish button on the last step. When empty, the text from the locale pack is used. | `string` | - |
358
+ | getPopupContainer | In modal mode the dialog is rendered into this DOM node. In popup mode body scrolling is not locked when it points to an element other than body. The popover card sits in the top layer and is not affected. | `() => HTMLElement` | - |
359
+ | mask | Whether to show the mask. A step's own mask overrides it. | `boolean` | `true` |
360
+ | mode | Guide mode: popup for a bubble card, modal for a dialog. | `'modal' \| 'popup'` | `"popup"` |
361
+ | nextButtonProps | Props of the next button. onclick is called before the built-in handling; use the nextText snippet for the button text. | `UserGuideButtonProps` | - |
362
+ | nextText | Snippet for the text of the next button; the last step shows finishText. Without it the text from the locale pack is used. | `Snippet` | - |
363
+ | onChange | Called with the new index when the step changes, after current was written. | `(current: number) => void` | - |
364
+ | onFinish | Called when the finish button on the last step is clicked, after visible was written. | `() => void` | - |
365
+ | onNext | Called with the new index when the next button is clicked. The last step calls onFinish instead. | `(current: number) => void` | - |
366
+ | onPrev | Called with the new index when the previous button is clicked. | `(current: number) => void` | - |
367
+ | onSkip | Called when the skip button is clicked or Escape is pressed, after visible was written. | `() => void` | - |
368
+ | position | Position of the bubble card relative to the target element. A step's own position overrides it. | `Position` | `"bottom"` |
369
+ | prevButtonProps | Props of the previous button. onclick is called before the built-in handling; use the prevText snippet for the button text. | `UserGuideButtonProps` | - |
370
+ | prevText | Snippet for the text of the previous button. Without it the text from the locale pack is used. | `Snippet` | - |
371
+ | showPrevButton | Whether to show the previous button. It is never shown on the first step. | `boolean` | `true` |
372
+ | showSkipButton | Whether to show the skip button. It is never shown on the last step. | `boolean` | `true` |
373
+ | spotlightPadding | Extra space in pixels around the highlighted area. A step's own spotlightPadding overrides it; 5 when neither is set. | `number` | - |
374
+ | steps | Data of the guide steps. A title or description is a string or a snippet, a cover is a snippet; a snippet receives `{ item, index }`. | `UserGuideStepItem[]` | `[]` |
375
+ | style | Style string. Lands on the popover card in popup mode and on `.semi-modal` in modal mode. | `string` | - |
376
+ | theme | Theme of the popup mode. A step's own theme overrides it. | `'default' \| 'primary'` | `"default"` |
377
+ | visible | Whether the guide is shown, bound with `bind:visible`. Skip, Escape and finish write `false` back. | `boolean` | - |
378
+ | zIndex | The z-index of the mask in popup mode and of the dialog in modal mode. The popover card sits in the top layer, always above the mask. | `number` | `1030` |
379
+
380
+ UserGuide has no root element. In popup mode `class` and `style` land on the popover card; in modal mode `class` lands on the outermost element of the Modal and `style` on `.semi-modal`. Undeclared attributes such as `aria-*` and native events are dropped. The dialog's accessible name comes only from the `title` of the current step.
381
+
382
+ ### StepItem
383
+
384
+ Each item of `steps` (type `UserGuideStepItem`) holds data only. `title` and `description` are strings or snippets and `cover` is a snippet; a snippet receives `{ item, index }` (type `UserGuideStepSnippetProps`).
385
+
386
+ | Property | Description | Type | Default |
387
+ | - | - | - | - |
388
+ | class | Custom class name of the step | string | - |
389
+ | cover | Cover of the step; without it the step has no cover area | Snippet<\[UserGuideStepSnippetProps]> | - |
390
+ | target | The target element, the highlight area will focus on this element. The function form is called when the step is measured and may return `null` or `undefined` while the target is absent | Element \| (() => Element \| null \| undefined) | - |
391
+ | title | Title of the step, a string or a snippet | string \| Snippet<\[UserGuideStepSnippetProps]> | - |
392
+ | description | Description of the step, a string or a snippet | string \| Snippet<\[UserGuideStepSnippetProps]> | - |
393
+ | mask | Whether to display the mask of this step, it will override the global configuration | boolean | - |
394
+ | showArrow | Whether to display the arrow (only valid when mode=`popup`) | boolean | true |
395
+ | spotlightPadding | The inner padding of the highlight area of this step, it will override the global configuration | number | - |
396
+ | theme | The theme of this step, it will override the global configuration | `default` \| `primary` | - |
397
+ | position | The position of the pop-up layer of this step, it will override the global configuration | Position | - |
398
+
399
+ ## Accessibility
400
+
401
+ - Each step is a dialog named by the step `title`; Escape works like clicking Skip.
402
+ - In both modes, focus moves to the primary button (Next or Finish) when each step appears. In popup mode Tab cycles inside the card, and focus returns to the element focused before the guide when it closes; in modal mode, Modal manages the focus cycle and its return.
403
+
404
+ ## Design Tokens
405
+
406
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/user-guide/>
407
+
408
+ ## Changes from Semi Design
409
+
410
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
411
+
412
+ - `StepItem.mask`、`className` 生效;步骤的 `theme` 优先于全局;`nextButtonProps`、`prevButtonProps` 的 `onClick` 先调用使用方的再执行内置处理(原为替换);`target` 允许 `null`;popup 卡片在 top layer,不接收 `getPopupContainer`、`zIndex`。
413
+ - 滚动锁只在 popup 模式且当前步骤显示遮罩时加锁(`mask` 为 false 不再锁页面);Esc 等同「跳过」。
414
+ - popup 模式切换到 `target` 解析为 null 的步骤时,开发环境 `console.warn` 一次(该步骤在目标出现前不显示)。
415
+ - Svelte:UserGuide 的 `visible`、`current` 可绑定(`bind:`、函数绑定、单向、不传四种写法);回调是 `onChange`、`onNext`、`onPrev`、`onSkip`、`onFinish`;跳过、Escape、完成时先把 `visible` 写成 `false` 再调回调,`current` 变化先写回再调 `onChange`;单向传 `visible` 只作初值,点跳过会在本地关闭,要拒绝关闭请用函数绑定。
416
+ - Svelte:`steps` 的 `title`、`description` 是字符串或 snippet,`cover` 是 snippet(参数 `{ item, index }`),没有 `cover` 的步骤没有封面区;按钮文字用组件级 `nextText`、`prevText` snippet,最后一步用 `finishText`。
417
+ - Svelte:未绑定、未传 `current` 时关闭后重开从第一步开始,`current` 由父级传入时保持关闭前的步骤;没有 KeepAlive 对应物,不提供失活后释放滚动锁的行为;服务端和 hydration 首帧不输出内容(popup 要等目标挂载后测量,modal 经 Portal 挂载后才渲染)。
418
+ - 引导隐藏结束后 `current` 回到受控值,未受控时回到第一步。
419
+ - 显示期间逐帧跟随目标位置,目标自行移动或晚于显示挂载时聚光区域随之更新。
@@ -0,0 +1,234 @@
1
+ # Quick Start
2
+
3
+ > Install Semi Design Next and start using it in a React, Vue, Solid or Svelte project.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/start/getting-started/
6
+
7
+ `@fibrae/semi-ui-svelte` is the Svelte component library of Semi Design Next, for Svelte 5 applications; for server-side rendering see [Server-side rendering](#server-side-rendering).
8
+
9
+ ## Requirements
10
+
11
+ Peer dependency: `svelte` ^5.57.0.
12
+
13
+ | Item | Requirement |
14
+ | - | - |
15
+ | Browser | Chrome 120, Firefox 125, Safari 17.2 or later. Supporting Safari below 17.4 needs `@fibrae/semi-polyfill`; see Install below |
16
+ | Modules and syntax | ESM only; syntax and built-ins ship as ESNext, without lowering |
17
+ | Node.js | 24 or later, since server rendering runs component code; 22.17 or later when Node only runs the build plugins and `semi-build-scss` |
18
+ | Build plugins | Vite 8 or later, webpack 5.77 or later, rspack 2 |
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pnpm add svelte @fibrae/semi-ui-svelte @fibrae/semi-icons-svelte
24
+ ```
25
+
26
+ The icon package `@fibrae/semi-icons-svelte` is a dependency of the component library, and illustrations come from its `@fibrae/semi-icons-svelte/illustrations` entry. When your code imports it directly, declare it in your own `package.json`, since pnpm does not allow importing undeclared packages.
27
+
28
+ The Svelte packages ship `.svelte` sources and `.d.ts` files, not compiled output: `exports` carries a `svelte` condition, and `@sveltejs/vite-plugin-svelte` (built into SvelteKit) compiles them for the app's target, DOM or server. Tools that do not recognise the `svelte` condition or do not compile `.svelte` cannot use these packages.
29
+
30
+ With npm or yarn, use the equivalent commands.
31
+
32
+ To support Safari below 17.4, also install `@fibrae/semi-polyfill` and import it on the first line of the app entry, before any Semi component. It only adds `AbortSignal.any` and `Element.prototype.checkVisibility`, and does nothing where the browser has them natively; to add just one of them, import `@fibrae/semi-polyfill/abort-signal-any` or `@fibrae/semi-polyfill/check-visibility`.
33
+
34
+ ```js
35
+ import '@fibrae/semi-polyfill';
36
+ ```
37
+
38
+ ## Import the tokens
39
+
40
+ The components import the theme tokens (the `--semi-*` CSS variables) and the base rules themselves, so pages render correctly without this step. When the first component is lazy loaded, though, the tokens only apply once that component's chunk has loaded. Import the tokens entry first in your app's entry file and the tokens load with the entry's CSS, so your own styles can use the `--semi-*` variables from the first paint.
41
+
42
+ In a Vite + Svelte app, import it in the entry file:
43
+
44
+ ```ts
45
+ // src/main.ts, before any other import
46
+ import '@fibrae/semi-ui-svelte/tokens';
47
+ ```
48
+
49
+ SvelteKit has no such entry file; import it at the top of the root layout's script:
50
+
51
+ ```svelte
52
+ <!-- src/routes/+layout.svelte -->
53
+ <script lang="ts">
54
+ import '@fibrae/semi-ui-svelte/tokens';
55
+
56
+ let { children } = $props();
57
+ </script>
58
+
59
+ {@render children()}
60
+ ```
61
+
62
+ The tokens entry is a JS module that imports the same tokens the components use, so the build output holds one copy, and build plugin options such as `prefixCls` apply to it as well. With `omitCss` it is removed along with the component styles, and the full stylesheet provides the tokens.
63
+
64
+ ## Use components
65
+
66
+ ```svelte
67
+ <script lang="ts">
68
+ import { Button, Switch, Toast } from '@fibrae/semi-ui-svelte';
69
+
70
+ let checked = $state(false);
71
+ </script>
72
+
73
+ <Button theme="solid" type="primary" onclick={() => Toast.warning({ content: 'welcome' })}>Hello Semi</Button>
74
+ <Switch bind:checked aria-label="Switch" />
75
+ ```
76
+
77
+ Controlled values use two-way `bind:checked={value}`; passing only `checked` sets the initial value, and there are no `default*` props such as `defaultChecked`. With a one-way value, what the user changes inside the component is temporary: when the value passed by the parent changes, the parent's value wins; when the same component also takes spread props (`{...rest}`), replacing the spread object with a new one applies the parent's value again. To keep the user's change, use `bind:` or write it back to your own state in the callback (such as `onChange`). Content props (React's ReactNode and render functions) are snippets, written inside the component tag or defined with `{#snippet}`; `style` only accepts a string, and native events use lowercase names (`onclick`).
78
+
79
+ A single component can also be imported by its directory path, written down to `/index`, such as `import { Button } from '@fibrae/semi-ui-svelte/button/index'`; the component file is `<directory>/<name>.svelte`, such as `@fibrae/semi-ui-svelte/button/button.svelte`.
80
+
81
+ Styles and tokens load on demand with the components, and only the components you use are bundled. Semi ships `box-sizing: border-box` and the scrollbar base styles itself, so a reset stylesheet such as reset.css is not needed; an extra reset changes component sizes.
82
+
83
+ ## Build plugins
84
+
85
+ webpack and rspack need no build plugin when you keep the default `semi` prefix, layered styles and per-component style imports. The components import precompiled CSS with the `semi` class prefix, wrapped in `@layer semi`: you need a rule for `.css` imports, such as `css-loader` with `style-loader` (or the `mini-css-extract-plugin` loader) in webpack, or `type: 'css'` in rspack. The Vite dev server works without the plugin, but `vite build` needs `@fibrae/semi-vite-plugin`, for the reason given below. For hosts that render on the server, see [Server-side rendering](#server-side-rendering).
86
+
87
+ For the options below, use the plugin for your build tool: `@fibrae/semi-vite-plugin` for Vite, `@fibrae/semi-webpack-plugin` for webpack 5, and `@fibrae/semi-rspack-plugin` for rspack 2. The plugins apply to the component library, the icon packages and the AI packages.
88
+
89
+ | Option | Default | Description |
90
+ | - | - | - |
91
+ | `prefixCls` | `'semi'` | Class prefix, rewritten both in the component JS and in the compiled styles |
92
+ | `cssLayer` | `true` | Whether the styles are wrapped in `@layer semi`; `false` outputs unlayered styles |
93
+ | `omitCss` | `false` | Drops the style imports inside the Semi packages so the app loads the full stylesheet instead, see [Full stylesheet](#full-stylesheet) |
94
+
95
+ ```ts
96
+ // vite.config.ts
97
+ import { defineConfig } from 'vite';
98
+ import semi from '@fibrae/semi-vite-plugin';
99
+
100
+ export default defineConfig({
101
+ plugins: [semi({ prefixCls: 'my' })],
102
+ });
103
+ ```
104
+
105
+ ```js
106
+ // webpack.config.mjs
107
+ import SemiWebpackPlugin from '@fibrae/semi-webpack-plugin';
108
+
109
+ export default {
110
+ plugins: [new SemiWebpackPlugin({ prefixCls: 'my' })],
111
+ };
112
+ ```
113
+
114
+ ```js
115
+ // rspack.config.mjs; the project needs a rule that treats .scss as CSS
116
+ import { SemiRspackPlugin } from '@fibrae/semi-rspack-plugin';
117
+
118
+ export default {
119
+ module: { rules: [{ test: /\.s?css$/, type: 'css' }] },
120
+ plugins: [new SemiRspackPlugin({ prefixCls: 'my' })],
121
+ };
122
+ ```
123
+
124
+ The webpack plugin also takes `extractCssOptions` (for example to use the `mini-css-extract-plugin` loader) and `overrideStylesheetLoaders` (to append your own loaders to the default chain). If class names are still `semi-*` in `vite dev`, the prebundle cache comes from the previous configuration; rebuild it with `vite --force`.
125
+
126
+ Svelte projects differ as follows:
127
+
128
+ - Vite only: the Svelte packages are compiled by `@sveltejs/vite-plugin-svelte` (built into SvelteKit). there is no verified Svelte setup for webpack or rspack, so do not use `@fibrae/semi-webpack-plugin` or `@fibrae/semi-rspack-plugin` in a Svelte project.
129
+ - `@fibrae/semi-vite-plugin` applies to `@fibrae/semi-ui-svelte`, `@fibrae/semi-ai-svelte` and `@fibrae/semi-icons-svelte`, and `prefixCls`, `cssLayer` and `omitCss` mean the same, as `plugins: [svelte(), semi()]`; for SvelteKit see [Server-side rendering](#server-side-rendering).
130
+
131
+ The published `.scss` files use `semi:` URLs that plain Sass cannot resolve; compile them through a build plugin or `@fibrae/semi-scss-compile`.
132
+
133
+ ## Full stylesheet
134
+
135
+ To load every component's styles at once, import the full stylesheet and turn on the build plugin's `omitCss`; otherwise the components' own style imports are bundled again and each component's styles appear twice. The full stylesheet includes the tokens and the icon styles, uses the `semi` class prefix, and is wrapped in `@layer semi`.
136
+
137
+ ```ts
138
+ import '@fibrae/semi-ui-svelte/styles.css';
139
+ // with the AI components, import theirs after it
140
+ import '@fibrae/semi-ai-svelte/styles.css';
141
+ ```
142
+
143
+ With `omitCss` the plugins no longer compile styles, so `cssLayer` has no effect, and the webpack and rspack plugins throw when both are passed. For a full stylesheet with a custom prefix or without layers, generate one with `@fibrae/semi-scss-compile`: `--prefix` matches the plugin's `prefixCls`, and `--no-layer` outputs unlayered styles. `-f` and `-i` are optional and default to the foundation and icons-core that `@fibrae/semi-scss-compile` itself depends on, so its version must match the component library; when it does not, point `-f` and `-i` to the `dist` of the `@fibrae/semi-foundation` and `@fibrae/semi-icons-core` installed in your app, which pnpm requires as direct dependencies. `--ai` always needs a path, to the `dist` of `@fibrae/semi-ai-foundation`; with pnpm add it as a direct dependency at the same version as the component library.
144
+
145
+ ```bash
146
+ pnpm add -D @fibrae/semi-scss-compile
147
+ pnpm exec semi-build-scss -o src/semi.css --min --prefix my
148
+ # with the AI components, generate a second file and import it after the first (also install @fibrae/semi-ai-foundation)
149
+ pnpm add -D @fibrae/semi-ai-foundation
150
+ pnpm exec semi-build-scss --ai node_modules/@fibrae/semi-ai-foundation/dist -o src/semi-ai.css --min --prefix my
151
+ ```
152
+
153
+ ## Customize styles
154
+
155
+ Customizing styles needs no build plugin: override the `--semi-*` CSS variables in your own stylesheet to change the global colors, radii, font sizes, spacing and so on (see [Design Tokens](../basic/tokens.md) for the list, and [Dark Mode](../advanced/dark-mode.md) for dark values). Semi's styles sit in `@layer semi`, so your unlayered CSS rules always win and can override a component's own styles without `!important`.
156
+
157
+ ```css
158
+ :root {
159
+ --semi-color-primary: var(--semi-violet-5);
160
+ }
161
+
162
+ .my-toolbar .semi-button {
163
+ border-radius: 0;
164
+ }
165
+ ```
166
+
167
+ When using Tailwind, see [Tailwind](../ecosystem/tailwind.md) for the layer order and for using Semi tokens in utility classes.
168
+
169
+ ## Icons and illustrations
170
+
171
+ ```svelte
172
+ <script lang="ts">
173
+ import { IconHome } from '@fibrae/semi-icons-svelte';
174
+ </script>
175
+
176
+ <IconHome aria-label="Home" />
177
+ ```
178
+
179
+ For a custom SVG, use the `children` snippet of the default export `Icon`; its argument carries `fill`:
180
+
181
+ ```svelte
182
+ <script lang="ts">
183
+ import Icon from '@fibrae/semi-icons-svelte';
184
+ </script>
185
+
186
+ <Icon size="large">
187
+ {#snippet children({ fill })}
188
+ <svg viewBox="0 0 24 24" {fill}><circle cx="12" cy="12" r="10" /></svg>
189
+ {/snippet}
190
+ </Icon>
191
+ ```
192
+
193
+ Illustrations are imported from `@fibrae/semi-icons-svelte/illustrations`, such as `IllustrationNoContent`.
194
+
195
+ Icon styles load with the icon components. See [Icon](https://semi-design-next.pages.dev/en-US/svelte/basic/icon/) for the icon list and usage.
196
+
197
+ ## AI components
198
+
199
+ The AI components (AIChatInput, AIChatDialogue, Chat, Sidebar and others) live in a separate AI package built on the component library, and their styles load with the components. When loading full stylesheets, import the AI package's after the component library's. See [AI components](https://semi-design-next.pages.dev/en-US/svelte/ai/ai-component/) for an overview.
200
+
201
+ ```bash
202
+ pnpm add @fibrae/semi-ai-svelte
203
+ ```
204
+
205
+ `@fibrae/semi-ai-svelte` currently completes only AIChatDialogue; AIChatInput, Chat and Sidebar are being ported and are not exported yet.
206
+
207
+ ## Server-side rendering
208
+
209
+ For server-side rendering and hydration, configure the host as the table below shows; most hosts also need the Semi build plugin. By default styles load per component: the component JS imports its own styles and you do not import `styles.css`. The full stylesheet is an optional route: turn on the build plugin's `omitCss` and import `styles.css` once, see [Full stylesheet](#full-stylesheet). Do not mix the two routes; mixed, the CSS roughly doubles.
210
+
211
+ | Host | Install | Host configuration | Styles |
212
+ | - | - | - | - |
213
+ | SvelteKit 3 | `@fibrae/semi-ui-svelte`, `-D @fibrae/semi-vite-plugin` | `plugins: [sveltekit({ adapter }), semi()]` | none |
214
+
215
+ ```ts
216
+ // vite.config.ts
217
+ import { sveltekit } from '@sveltejs/kit/vite';
218
+ import { defineConfig } from 'vite';
219
+ import semi from '@fibrae/semi-vite-plugin';
220
+
221
+ // replace adapter with the SvelteKit adapter you use
222
+ export default defineConfig({
223
+ plugins: [sveltekit({ adapter }), semi()],
224
+ });
225
+ ```
226
+
227
+ Components render server HTML through `render` from `svelte/server` and in SvelteKit, and the browser hydrates with `hydrate`. Ids inside components come from `$props.id()` and match between server and browser; `onMount` and `$effect` do not run on the server, so state that depends on them (such as measured sizes) appears after hydration.
228
+
229
+ Common conventions:
230
+
231
+ - Import the built-in locale packs `zh_CN` and `en_US` from the `/locale` entry of the UI package (such as `import { en_US } from '@fibrae/semi-ui-react/locale'`); you do not need to install `@fibrae/semi-foundation` directly.
232
+ - Set `semiGlobal` only at app startup; use `ConfigProvider` for configuration that changes per request.
233
+ - Overlays that are open by default appear after hydration.
234
+ - CodeHighlight bundles no languages: install `shiki` directly in your app (pnpm does not allow importing undeclared packages) and pass languages from `shiki/langs/*` through `CodeHighlight.register` or `languages`, see [CodeHighlight](../plus/code-highlight.md).