@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,156 @@
1
+ # ScrollList
2
+
3
+ > Scroll through the list.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/scroll-list/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { ScrollList, ScrollItem } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ The scrolling list provides a scrolling selection mode similar to the iOS operating system, while supporting scrolling to the specified window location selection and click selection.
20
+
21
+ Bind the selected item with `bind:selectedIndex`, which writes the new index back on selection; the callback is `onSelect`. Write a column as `ScrollList.Item` or the named export `ScrollItem`, which are the same component. `header` and `footer` accept a string or a snippet and render whenever given: define one with `{#snippet footer()}...{/snippet}` and pass it as a prop, or write it inside the ScrollList tag.
22
+
23
+ ```svelte
24
+ <script lang="ts">
25
+ import { Button, ScrollItem, ScrollList, type ScrollItemSelectData } from '@fibrae/semi-ui-svelte';
26
+
27
+ const ampms = [{ value: '上午' }, { value: '下午' }];
28
+ const hours = Array.from({ length: 12 }, (_, index) => ({ value: index + 1 }));
29
+ const minutes = Array.from({ length: 60 }, (_, index) => ({ value: index, disabled: index % 3 === 0 }));
30
+
31
+ let selectIndex1 = $state(1);
32
+ let selectIndex2 = $state(1);
33
+ let selectIndex3 = $state(1);
34
+
35
+ const onSelectHour = (data: ScrollItemSelectData) => {
36
+ console.log('You have choose the hour for: ', data.value);
37
+ };
38
+
39
+ const onSelectMinute = (data: ScrollItemSelectData) => {
40
+ console.log('You have choose the minute for: ', data.value);
41
+ };
42
+
43
+ const handleClose = () => {
44
+ console.log('close');
45
+ };
46
+ </script>
47
+
48
+ <ScrollList header="无限滚动列表" style="border: unset; box-shadow: unset">
49
+ <ScrollItem aria-label="上午或下午" bind:selectedIndex={selectIndex1} cycled={false} list={ampms} mode="wheel" />
50
+ <ScrollItem aria-label="小时" bind:selectedIndex={selectIndex2} cycled list={hours} mode="wheel" onSelect={onSelectHour} />
51
+ <ScrollItem aria-label="分钟" bind:selectedIndex={selectIndex3} cycled list={minutes} mode="wheel" onSelect={onSelectMinute} />
52
+ {#snippet footer()}
53
+ <Button size="small" type="primary" onclick={handleClose}>Ok</Button>
54
+ {/snippet}
55
+ </ScrollList>
56
+ ```
57
+
58
+ ## API Reference
59
+
60
+ ### ScrollList
61
+
62
+ **Props**
63
+
64
+ | Property | Description | Type | Default |
65
+ | - | - | - | - |
66
+ | bodyHeight | Height of the list body. | `number \| string` | - |
67
+ | children | The ScrollItem columns, written inside the tag. | `Snippet` | - |
68
+ | footer | Footer content, a string or a snippet; rendered whenever given. | `Snippet \| string` | - |
69
+ | header | Header content, a string or a snippet; rendered whenever given. | `Snippet \| string` | - |
70
+
71
+ `class`, `style` (a string) and native attributes such as `aria-*` land on the root element.
72
+
73
+ ### ScrollItem
74
+
75
+ **Props**
76
+
77
+ | Property | Description | Type | Default |
78
+ | - | - | - | - |
79
+ | cycled | Whether the column cycles. In wheel mode the list scrolls without end; in both modes the arrow keys wrap around. | `boolean` | `false` |
80
+ | list | Items of the column. | `T[]` | - |
81
+ | mode | Mode: normal or wheel. | `'normal' \| 'wheel'` | `"wheel"` |
82
+ | motion | Whether to animate scrolling. | `boolean` | `true` |
83
+ | onSelect | Called when an item is selected, with the item's data plus the item's index in list. | `(data: ScrollItemSelectData<T>) => void` | - |
84
+ | selectedIndex | Index of the selected item; bind it with `bind:selectedIndex`. A selection writes the new index back. | `number` | - |
85
+ | transform | Formats the text of the selected item; the text is undefined for an item without one. When omitted, text is shown, or value when there is no text. An item's own transform takes precedence. | `(value: T['value'], text?: string) => string` | - |
86
+
87
+ **Methods**
88
+
89
+ | Method | Description | Type |
90
+ | - | - | - |
91
+ | scrollToIndex | Scrolls the list to the selected item. `selectedIndex` has no effect yet, the target is always the item last selected; `duration` is the animation time in milliseconds, 120 by default. | `(_selectedIndex?: number, duration?: number) => void` |
92
+
93
+ `aria-label`, `aria-labelledby` and `aria-describedby` land on the list (`role="listbox"`); `class`, `style` (a string) and other attributes land on the root element.
94
+
95
+ #### ItemData
96
+
97
+ | Properties | Instructions | type | Default |
98
+ | - | - | - | - |
99
+ | disabled | Whether the item is prohibited or not | boolean | |
100
+ | text | The copy of each item. | string | |
101
+ | transform | When the transformation is in the selected state, the return value is displayed as a copy, and if the ScrollItem component is passed at the same time, the transform method in ItemData will be selected first. When omitted, `text` is shown, or `value` when there is no `text`. | (value: any, text: string \| undefined) => string | |
102
+ | value | The value of each item | any | |
103
+
104
+ #### Methods
105
+
106
+ Call these on the ScrollItem instance obtained through `bind:this`; see the Methods table of ScrollItem above for the signature.
107
+
108
+ ## Accessibility
109
+
110
+ ### ARIA
111
+
112
+ - When `aria-label` or `aria-labelledby` is passed, the root element of `ScrollList` gets `role="group"`
113
+ - `ScrollItem` is a `role="listbox"` and supports `aria-label`, which indicates the label of the current column.
114
+ - `ScrollItem` uses `aria-disabled` to indicate whether the item is disabled
115
+ - `ScrollItem` uses `aria-selected` to indicate whether the item is selected
116
+ - The copies that fill the wheel of a `cycled` column carry `aria-hidden="true"`, so screen readers only read the real options
117
+
118
+ ### Keyboard and Focus
119
+
120
+ - Each column is a `listbox`: focus it with `Tab`. Focus stays on the list and the selected item is exposed through `aria-activedescendant`; selection follows focus, and each selection fires the select callback
121
+ - `ArrowUp` selects the previous item and `ArrowDown` the next one, skipping disabled items; `Home` selects the first item and `End` the last one
122
+ - With `cycled`, the arrow keys wrap around at both ends in either mode; without it they stop at the ends
123
+ - Typing characters selects the item whose text starts with them; typing the same character repeatedly moves on to the next match
124
+
125
+ ## Design Tokens
126
+
127
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/scroll-list/>
128
+
129
+ ## Changes from Semi Design
130
+
131
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
132
+
133
+ - ScrollList:滚动列(TimePicker 的时间列同用)的键盘处理放行带 Alt、Ctrl、Meta 的按键(如 Alt+ArrowDown),不再 `preventDefault`、不改选中项。
134
+ - Carousel:`ref.stop()` 后手动切换、焦点离开、幻灯片增加等都不再恢复自动播放,直到 `ref.play()`;`prefers-reduced-motion: reduce` 时不自动播放且无切换动画;键盘焦点进入时暂停自动播放;非当前幻灯片带 `inert`。
135
+ - Carousel 箭头改为原生 `<button type="button">`(`arrowProps.*.props` 类型改为 `ButtonHTMLAttributes<HTMLButtonElement>`),指示点改为 `role="tab"` 的 button;新增语言包键 `Carousel.indicators`、`Carousel.slideN`、`Carousel.carousel`、`Carousel.slide`(自定义语言包需补齐)与主题变量 `$radius-carousel_arrow`,箭头高度由 39px 改为 32px。
136
+ - Typography 的复制按钮与展开、收起控件改为原生 `<button type="button">`,`ellipsis.onExpand` 事件类型改为 `React.MouseEvent<HTMLButtonElement>`,复制按钮不再带内联 `margin-left`;`ellipsis` 对象中写成 `undefined` 的 `rows`、`pos`、`suffix` 取默认值(`1`、`'end'`、`''`);无 `href` 的 `link` 有点击监听时获得 `role="link"`;`disabled` 的 `link` 不再触发 `link.onClick`。
137
+ - 修复(Vue、Svelte):`link` 里写成 `undefined` 的 `aria-describedby` 不再覆盖省略提示的关联,链接仍以 Tooltip 作描述,与 React、Solid 一致。
138
+ - 破坏性:Numeral 不再支持函数 children;`CopyableConfig`、`LinkType` 的深路径从 `typography/title` 移到 `typography/interface`;`BaseTypographyProps` 不再从入口导出;类型上 `ScrollItemProps` 不再包含 `children`,ScrollItem 的 `motion` 收为 `boolean`,`onSelect` 参数收窄为 `T & { type?: string | number; index: number }`。
139
+ - 破坏性(类型):React、Solid 的 `CopyableProps` 的 `content`、`duration` 必填,经 `Typography` 的 `copyable` 使用不受影响。
140
+ - React、Solid 破坏性(深路径导入):`typography/copyable` 只有默认导出,删除同名的具名导出 `Copyable`。
141
+ - ScrollList 的各列不显示滚动条(原来随系统设置显示),用滚轮、拖动或方向键滚动。
142
+ - ScrollItem wheel 模式的高亮行(`.semi-scrolllist-item-selected`)由渲染输出,重新渲染改写类名时不再丢失;React、Solid 的 `transform` 参数 `value` 类型为 `T['value']`(原为 `any`),与 Vue、Svelte 一致。
143
+ - Solid 破坏性:箭头内容由 `arrowProps.leftArrow.children`、`arrowProps.rightArrow.children` 改为 Carousel 的 `leftArrow`、`rightArrow` 属性(`JSX.Element`,`null` 时按钮为空,与 Vue 的 `#leftArrow`、`#rightArrow` 一致),只在显示箭头时创建,`ArrowButton` 只剩 `props`;箭头按钮的 `x-semi-prop` 改为 `leftArrow`、`rightArrow`。
144
+ - Solid 破坏性(类型):`copyable` 配置的 `copyTip`、`successTip` 改为 `string | (() => JSX.Element)`,`icon` 改为 `() => JSX.Element`(`icon: () => <X />`),只在对应内容显示时调用。
145
+ - Solid 破坏性:Numeral 只格式化字符串与数字 children,每个分别格式化(动态插值 `{price()}` 单独成段,与 React 一致);元素 children(含子组件渲染出的元素)原样输出,其中的文字不格式化。copyable 按钮的可访问名称只取字符串的 `copyTip`(未复制时)与 `successTip`(已复制时),否则用语言包的 `copy`、`copied`;`icon`、`successTip` 渲染出的元素上的 `aria-label` 不再参与命名。
146
+ - Svelte 破坏性:Carousel 的幻灯片用 `items` 数据 prop 加 `slide` snippet(参数 `{ item, index }`),不接受 children 形式,Carousel 给每张包一层带 role、`inert` 的元素;箭头内容为 `leftArrow`、`rightArrow` snippet;`activeIndex` 可绑定,回调 `onChange(activeIndex, preIndex)`;`play`、`stop`、`goTo`、`prev`、`next` 经 `bind:this` 调用。
147
+ - Svelte:Typography 的 `Text`、`Title`、`Paragraph`、`Numeral` 与根组件 `Typography` 均为具名导出,平铺在包根;`copyable` 配置对象只含 `content`、`duration`、`class`、`style`(字符串)、`onCopy`,图标、提示、自定义渲染改用 snippet `copyIcon`、`copyTip`、`copySuccessTip`、`copyAction`(参数 `{ copied, copy, config }`);`ellipsis` 的 `onExpand` 写在 `ellipsis` 配置里。
148
+ - Svelte:`showTooltip` 的 `opts` 同时接受 Tooltip 与 Popover 属性(`type` 为 `'popover'` 时渲染带箭头的 Popover,类名含 `semi-typography-ellipsis-popover`),提示内容用 `ellipsisContent` snippet,整体接管提示用 `ellipsisTooltip` snippet(参数 `{ content, trigger }`);`icon` 为 snippet;`component` 只接受字符串标签名。
149
+ - Svelte:省略截断时,完整文本留在 DOM 中并设 `hidden`,根元素的 `textContent` 含全文;Numeral 格式化与图标 small 尺寸在挂载后才应用,服务端输出原始文本与默认图标尺寸。
150
+ - Svelte:ScrollList 的 `header`、`footer` 接受字符串或 snippet,传了就渲染;ScrollItem 的 `selectedIndex` 可绑定,配 `onSelect(data)`;`ScrollList.Item` 与具名导出 `ScrollItem` 是同一组件;`scrollToIndex` 经 `bind:this` 调用。
151
+ - 破坏性(Solid):Carousel 给每张幻灯片外包一层 `div.semi-carousel-content-item`,class、`role`、`aria-*`、`id`、`inert` 与切换动画写在包装元素上,使用方的幻灯片元素原样保留,要撑满轮播区域需自己设置 `height: 100%`(同 Svelte);按幻灯片元素写的 `.semi-carousel-content-item` 选择器改为选包装元素;幻灯片自带的 `id`、`aria-label` 不再用作 tab 的 `aria-controls` 目标与幻灯片名称。服务端 HTML 已带这些 class 与属性。
152
+ - Typography(React):`showTooltip.type` 显式为 `undefined` 时按默认 Tooltip 渲染,不再抛错。
153
+ - Typography:Numeral 不接受 `ellipsis`(类型与文档本就未声明),经透传带上也不截断(四个框架一致)。
154
+ - Typography:展开后按钮消失(可展开且不可收起)时,只在按钮持有焦点的情况下,于按钮移除后把焦点交给文字根元素(`tabindex="-1"`);按钮保留时焦点留在按钮上。React、Solid 不再在点击时无条件同步聚焦根元素(四个框架一致)。
155
+ - Typography(Vue):JS 省略的首帧按原插槽渲染,测量后再截断,放得下的内容不再先压成纯文本再恢复。
156
+ - ScrollList:cycled wheel 不再移动 `<li>`,DOM 顺序就是渲染顺序,列表长度变化后顺序、选中定位与点击回调值都正确,选中项立即定位且无动画。隐藏状态下挂载或隐藏后再显示的列,显示时定位到选中项,不触发 `onSelect`。任何定位都取消进行中的滚动动画,包括 `scrollToIndex(_, 0)`。删除 `ItemFoundation` 的 `shouldAppend`、`shouldPrepend`。
@@ -0,0 +1,274 @@
1
+ # SideSheet
2
+
3
+ > An overlay panel that slides out from the edge of the screen, typically used to host secondary action pages.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/show/side-sheet/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Banner, Button, Form, FormDatePicker, FormRadio, FormRadioGroup, FormSelect, Radio, RadioGroup, SideSheet, TextArea, Typography } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ By default, SideSheet slides from the right side of the screen and could be closed by clicking on the mask.
20
+
21
+ Use `bind:visible` to control visibility: the close button, the mask and Esc write `false` back to `visible` first, then call `onCancel`. With a one-way `visible` and `onCancel` only, the sheet does not close by itself; set `visible` to `false` in the `onCancel` handler.
22
+
23
+ ```svelte
24
+ <script lang="ts">
25
+ import { Button, SideSheet } from '@fibrae/semi-ui-svelte';
26
+
27
+ let visible = $state(false);
28
+ </script>
29
+
30
+ <Button onclick={() => (visible = !visible)}>Open SideSheet</Button>
31
+ <SideSheet bind:visible title="滑动侧边栏">
32
+ <p>This is the content of a basic sidesheet.</p>
33
+ <p>Here is more content...</p>
34
+ </SideSheet>
35
+ ```
36
+
37
+ ### Placement
38
+
39
+ You could use `placement` to set the position from which SideSheet comes in, supporting one of `top`, `bottom`, `left`, `right`.
40
+
41
+ ```svelte
42
+ <script lang="ts">
43
+ import { Button, Radio, RadioGroup, SideSheet, type SideSheetProps } from '@fibrae/semi-ui-svelte';
44
+
45
+ let visible = $state(false);
46
+ let placement = $state<SideSheetProps['placement']>('right');
47
+ </script>
48
+
49
+ <RadioGroup aria-label="侧边栏位置" onChange={(e) => (placement = e.target.value as SideSheetProps['placement'])} value={placement}>
50
+ <Radio value="right">right</Radio>
51
+ <Radio value="left">left</Radio>
52
+ <Radio value="top">top</Radio>
53
+ <Radio value="bottom">bottom</Radio>
54
+ </RadioGroup>
55
+ <br />
56
+ <br />
57
+ <Button onclick={() => (visible = !visible)}>Open SideSheet</Button>
58
+ <SideSheet bind:visible {placement} title="滑动侧边栏">
59
+ <p>This is the content of a basic sidesheet.</p>
60
+ <p>Here is more content...</p>
61
+ </SideSheet>
62
+ ```
63
+
64
+ ### Size
65
+
66
+ You could use `size` to set the size of SideSheet, supporting one of `small`(448px), `medium`(684px), and `large`(920px). Only takes effects when `placement` is set to `left` or `right`. If the default size does not meet your needs, you can also set the width by setting the `width` property, for example `width={900}` / `width="800px"`
67
+
68
+ ```svelte
69
+ <script lang="ts">
70
+ import { Button, Radio, RadioGroup, SideSheet, type SideSheetProps } from '@fibrae/semi-ui-svelte';
71
+
72
+ let visible = $state(false);
73
+ let size = $state<SideSheetProps['size']>('small');
74
+ </script>
75
+
76
+ <RadioGroup aria-label="侧边栏尺寸" onChange={(e) => (size = e.target.value as SideSheetProps['size'])} value={size}>
77
+ <Radio value="small">small</Radio>
78
+ <Radio value="medium">medium</Radio>
79
+ <Radio value="large">large</Radio>
80
+ </RadioGroup>
81
+ <br />
82
+ <br />
83
+ <Button onclick={() => (visible = !visible)}>Open SideSheet</Button>
84
+ <SideSheet bind:visible {size} title="滑动侧边栏">
85
+ <p>This is the content of a basic sidesheet.</p>
86
+ <p>Here is more content...</p>
87
+ </SideSheet>
88
+ ```
89
+
90
+ ### Non-blocking Workflow
91
+
92
+ > **Tips**
93
+ >
94
+ > With `mask` set to `false` the body scroll is not locked, so the area outside SideSheet scrolls as usual. Only a SideSheet with a mask that is rendered inside body (when you are not setting `getPopupContainer`) adds `overflow: hidden` to body when opened; set disableScroll to false to keep body scrollable.
95
+
96
+ You could set `mask={false}` to continue working on the area outside SideSheet.
97
+
98
+ ```svelte
99
+ <script lang="ts">
100
+ import { Button, SideSheet, TextArea } from '@fibrae/semi-ui-svelte';
101
+
102
+ let visible = $state(false);
103
+ let value = $state('');
104
+ </script>
105
+
106
+ <Button onclick={() => (visible = true)}>Open SideSheet</Button>
107
+ <TextArea bind:value placeholder="Please enter something" style="margin-block-start: 12px" />
108
+ <SideSheet bind:visible disableScroll={false} mask={false} title="可操作外部的侧边栏">
109
+ <p>这里是输入的内容:</p>
110
+ <p>{value}</p>
111
+ </SideSheet>
112
+ ```
113
+
114
+ ### Rendered Inside Container
115
+
116
+ You could use `getPopupContainer` to render SideSheet in targeted DOM.
117
+
118
+ > **Tips**
119
+ >
120
+ > The container must have `overflow: hidden` to avoid animated SideSheet overflows.
121
+
122
+ ```svelte
123
+ <script lang="ts">
124
+ import { Button, SideSheet } from '@fibrae/semi-ui-svelte';
125
+
126
+ let visible = $state(false);
127
+ const getContainer = () => document.querySelector('.sidesheet-container') as HTMLElement;
128
+ </script>
129
+
130
+ <div class="sidesheet-container" style="height: 320px; overflow: hidden; position: relative; border: 1px solid var(--semi-color-border); border-radius: 2px; padding: 24px; text-align: center; background: var(--semi-color-fill-0)">
131
+ <span>Render in this</span>
132
+ <br />
133
+ <br />
134
+ <Button onclick={() => (visible = true)}>Open SideSheet</Button>
135
+ <SideSheet bind:visible getPopupContainer={getContainer} title="渲染在指定容器内部" width={220}>
136
+ <p>This is the content of a basic sidesheet.</p>
137
+ <p>Here is more content...</p>
138
+ </SideSheet>
139
+ </div>
140
+ ```
141
+
142
+ ### Customized Content
143
+
144
+ Use the `title` prop (plain text or a snippet), the `footer` snippet and other Semi Components to create customized information display layers.
145
+
146
+ ```svelte
147
+ <script lang="ts">
148
+ import { Banner, Button, Form, FormDatePicker, FormRadio, FormRadioGroup, FormSelect, SideSheet, Typography } from '@fibrae/semi-ui-svelte';
149
+
150
+ let visible = $state(false);
151
+ const createTime = new Date();
152
+ const border = 'border-bottom: 1px solid var(--semi-color-border)';
153
+ const users = [
154
+ { value: '1', label: '曲晨一' },
155
+ { value: '2', label: '夏可曼' },
156
+ { value: '3', label: '曲晨三' },
157
+ { value: '4', label: '蔡妍' },
158
+ ];
159
+ </script>
160
+
161
+ <Button onclick={() => (visible = true)}>More Information</Button>
162
+ <SideSheet bind:visible closable={false} styles={{ header: border, body: border }} title="创建资源包">
163
+ {#snippet footer()}
164
+ <div style="display: flex; justify-content: flex-end">
165
+ <Button style="margin-inline-end: 8px">重置</Button>
166
+ <Button theme="solid">提交</Button>
167
+ </div>
168
+ {/snippet}
169
+ <Form>
170
+ <FormDatePicker field="date" initValue={createTime} label={{ text: '创建时间', required: true }} style="width: 272px" type="dateTime" />
171
+ <FormRadioGroup direction="horizontal" field="type" initValue="all" label="目标操作系统">
172
+ <FormRadio value="all">全平台</FormRadio>
173
+ <FormRadio value="ios">iOS</FormRadio>
174
+ <FormRadio value="android">Android</FormRadio>
175
+ <FormRadio value="web">Web</FormRadio>
176
+ </FormRadioGroup>
177
+ <FormRadioGroup direction="horizontal" field="origin" initValue="scm" label="资源包来源">
178
+ <FormRadio value="scm">从SCM上传</FormRadio>
179
+ <FormRadio value="manual">手动上传</FormRadio>
180
+ </FormRadioGroup>
181
+ <Banner bordered fullMode={false} icon={null} type="warning">
182
+ {#snippet description()}
183
+ <Typography.Text strong>当前部署环境:线上部署</Typography.Text>
184
+ <br />
185
+ <Typography.Text>请选择正确的SCM构建产物,防止出现不符合预期的发布操作。</Typography.Text>
186
+ {/snippet}
187
+ </Banner>
188
+ <br />
189
+ <FormSelect field="users" initValue={['1', '2', '3', '4']} label={{ text: '创建用户', required: true }} multiple optionList={users} style="width: 560px" />
190
+ </Form>
191
+ </SideSheet>
192
+ ```
193
+
194
+ ## API Reference
195
+
196
+ **Props**
197
+
198
+ | Property | Description | Type | Default |
199
+ | - | - | - | - |
200
+ | afterVisibleChange | Called with true after the enter animation ends, or right after showing without motion. Called with false after the leave animation, and once with false if the sheet is unmounted while shown. | `(isVisible: boolean) => void` | - |
201
+ | canVerticalSetWidth | Whether width applies when placement is top or bottom. By default those sheets span the full width. | `boolean` | - |
202
+ | children | Body of the sheet, written inside the tag. | `Snippet` | - |
203
+ | classNames | Class names of the inner parts, keyed by mask, content, header, body and footer; values take anything class takes (string, array or object) and merge with the built-in classes. content lands on the dialog element (.semi-sidesheet-inner). | `Partial<Record<SideSheetPart, ClassValue>>` | - |
204
+ | closable | Whether the close button in the corner is shown. | `boolean` | `true` |
205
+ | closeIcon | Snippet for the icon inside the close button; hide the button with closable set to false. | `Snippet` | - |
206
+ | closeOnEsc | Whether Esc closes the sheet. | `boolean` | `false` |
207
+ | disableScroll | Whether body scrolling is locked (overflow: hidden on body) while a masked sheet is rendered in document.body. | `boolean` | `true` |
208
+ | footer | Snippet for the footer of the sheet. Nothing is rendered when it is empty. | `Snippet` | - |
209
+ | getPopupContainer | Parent element the sheet is rendered into. A custom container needs position: relative; this changes where the sheet sits in the DOM, not where it is shown. | `() => HTMLElement` | - |
210
+ | height | Height, used when placement is top or bottom. A number is in pixels; a string is any valid CSS length. 448 when omitted. | `number \| string` | - |
211
+ | keepDOM | Whether the sheet content stays mounted while closed. | `boolean` | `false` |
212
+ | mask | Whether the mask is shown. When false the content outside stays operable. | `boolean` | `true` |
213
+ | maskClosable | Whether clicking the mask closes the sheet. | `boolean` | `true` |
214
+ | motion | Whether animation is enabled. | `boolean` | `true` |
215
+ | onCancel | Called when the user closes the sheet with the close button, the mask or Esc, after visible has been written back to false. The argument is the native MouseEvent, or the native KeyboardEvent for Esc. | `(event: MouseEvent \| KeyboardEvent) => void` | - |
216
+ | placement | Edge the sheet slides in from. | `Placement` | `"right"` |
217
+ | size | Size: small is 448px, medium 684px, large 920px. Used only when placement is left or right. | `'large' \| 'medium' \| 'small'` | `"small"` |
218
+ | style | Style that lands on the role=dialog element, as a string. | `string` | - |
219
+ | styles | Inline styles of the inner parts, keyed like classNames; every value is a style string. Like style, content is merged with the computed width and height, which take precedence. | `Partial<Record<SideSheetPart, string>>` | - |
220
+ | title | Title, plain text or a snippet, which also names the dialog. It is a declared prop, so it never lands on an element as the native title attribute. | `Snippet \| string` | - |
221
+ | visible | Whether the sheet is visible, used with bind:visible. | `boolean` | - |
222
+ | width | Width, used when placement is left or right. A number is in pixels; a string is any valid CSS length. Decided by size when omitted. | `number \| string` | - |
223
+ | zIndex | z-index of the layer. | `number` | `1000` |
224
+
225
+ **Methods**
226
+
227
+ | Method | Description | Type |
228
+ | - | - | - |
229
+ | getRoot | Returns the outer .semi-sidesheet element inside the portal, or null while nothing is rendered. | `() => HTMLDivElement \| null` |
230
+
231
+ `aria-*` attributes and `style` land on the `role="dialog"` element (`.semi-sidesheet-inner`); `class` and other native attributes and events land on the outermost `.semi-sidesheet` element inside the portal, which is also what `getRoot()` returns.
232
+
233
+ ## Accessibility
234
+
235
+ ### ARIA
236
+
237
+ - SideSheet has a `dialog` role to indicate that it is a pop-up component. The title element (`.semi-sidesheet-title`) has the `heading` role and `aria-level="2"` and names the dialog through `aria-labelledby`; the header itself has no role. When `aria-label` is passed it wins and that reference is not generated.
238
+ - Every `aria-*` attribute and `style` land on the `role="dialog"` element; other undeclared props land on the outer element.
239
+ - `aria-modal` is output only when the dialog is modal. A dialog is modal when it has a mask (`mask`) and is rendered in the body (judged by the actual container, so the `getPopupContainer` of ConfigProvider counts). With `mask` set to `false`, or a mask confined to a custom container, it is not output.
240
+
241
+ ### Keyboard and focus
242
+
243
+ - Focus moves into the sheet when it opens.
244
+ - With `closeOnEsc` set, pressing `Esc` closes the sheet (off by default).
245
+ - A modal dialog (with a mask, rendered in the body): Tab cycles inside the sheet, the rest of the page is inert, and focus returns to the element focused before it opened when it closes. A sheet with a mask rendered in a custom container does not make the page inert; see the next item.
246
+ - A non-modal dialog (`mask` set to `false`, or a mask confined to a custom container): Tab can leave the sheet for the page and the page outside the container stays usable; focus returns on close only if it is still inside the sheet or has fallen to the body, and focus the user has moved elsewhere on the page stays. With a mask confined to a custom container, other content inside that container can still be reached by Tab.
247
+
248
+ ## Design Tokens
249
+
250
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/show/side-sheet/>
251
+
252
+ ## FAQ
253
+
254
+ - Does SideSheet disable body scrolling automatically? When a SideSheet with a mask is rendered in the body by default (no `getPopupContainer`), it adds `overflow: hidden` to the body on open to block scrolling. Set `disableScroll` to `false` to allow scrolling; scrolling is not locked when `mask` is `false`.
255
+
256
+ ## Changes from Semi Design
257
+
258
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
259
+
260
+ - 破坏性:Modal 删除 `bodyStyle`、`maskStyle`,SideSheet 删除 `bodyStyle`、`headerStyle`、`maskStyle`,改用 `classNames`、`styles`,部位为 `mask`、`content`(`role="dialog"` 元素)、`header`、`body`、`footer`;Modal 的 `header` 部位只在默认标题头时存在。`Modal.info` 等静态方法与 `useModal` 的选项同样使用 `classNames`、`styles`。
261
+ - 破坏性:`Modal.info`、`success`、`error`、`warning`、`confirm`、`useModal`、`destroyAll` 改由 `modal/index` 挂载,深导入 `modal/modal` 的组件不再带这些静态方法;`cancelButtonProps.onClick`、`okButtonProps.onClick` 不再替换内置处理,先于 `onCancel`、`onOk` 调用,需替换的改在这两个回调里处理。
262
+ - 行为变化:SideSheet 关闭时与 Modal 一致,等离场动画结束(无动画时立即)才解除页面 inert、Tab 陷阱与 body 滚动锁,并把焦点还给打开前的元素(四个框架一致)。
263
+ - 行为变化:SideSheet 的 `afterVisibleChange(true)` 改在进场动画结束后调用,无动画时显示后立即调用;进场中被关闭时先补报 `true` 再报 `false`。
264
+ - 破坏性(类型):`onCancel` 参数为 `React.MouseEvent | KeyboardEvent`(Esc 传原生事件);Modal 的 `direction` 收窄为 `'ltr' | 'rtl'`,删除深路径导出的 `ConfirmType`、`Directions`;`Modal.useModal` 返回 `[ModalHookApi, ReactElement]`;`SideSheetState` 删除 `displayNone`;深路径 `side-sheet/index` 导出的 `SideSheetContentProps` 以 `sheetSize` 代替 `width`、`height`。
265
+ - 行为变化:Modal 的 `footer={undefined}`、`header={undefined}` 与不传相同,隐藏传 `null`;SideSheet 隐藏关闭按钮用 `closable={false}`;Modal 新增 `role?: 'dialog' | 'alertdialog'`(确认框默认 `alertdialog`),组件版不再默认设 `aria-describedby`;模态判断统一为 Modal `mask && (容器在 body 内 || maskFixed)`、SideSheet `mask && 容器在 body 内`,`mask={false}` 时不再锁 body 滚动、不拦截页面点击,非模态不再把 Tab 锁在层内。
266
+ - Svelte:SideSheet 的 `visible` 可绑定,没有 `defaultVisible`;关闭按钮、遮罩、Esc 先把 `visible` 写回 false,再调 `onCancel`(收到原生 `MouseEvent | KeyboardEvent`),函数绑定的 setter 可以拒绝关闭;`afterVisibleChange` 是回调 prop。
267
+ - Svelte:SideSheet 的 `title`(字符串或 snippet)、`footer`、`closeIcon`、`children` 是 snippet;`style` 与 `styles` 的值只接受字符串;`aria-*` 与 `style` 落在 `role="dialog"` 元素,`class` 和其余属性落在外层 `.semi-sidesheet`;抽屉挂载后才渲染,服务端不输出;`visible` 不读全局默认值;`bind:this` 的实例提供 `getRoot()`。
268
+ - Svelte:`Modal` 与 `Modal.info/success/error/warning/confirm`、`Modal.destroyAll`、`Modal.useModal` 随包提供;`useModal()` 返回 `{ info, success, error, warning, confirm }`,不返回 Holder,也没有 `install()`,确认框读调用组件所在处的 ConfigProvider 与 LocaleProvider;命令式确认框只能在浏览器调用,服务端调用抛出指明 API 名的错误。
269
+ - Svelte:`visible` 用 `bind:visible`;`onCancel` 返回 Promise 时,兑现后才写回 `false`,拒绝则保持打开,原因由 foundation 重新抛出;`title`、`header`、`footer`、`icon`、`closeIcon`、`modal` 是 snippet,`title`、`content`、`closeIcon` 也接受字符串;尺寸类型导出名为 `ModalSize`;动画由 class 驱动,`keepDOM` 重开保留节点和内部状态。
270
+ - 容器是全屏元素(`document.fullscreenElement`)时按覆盖整页处理:Modal、SideSheet、ImagePreview 为模态并锁 body 滚动。
271
+ - 同一元素有多个退出动画时,等全部结束才卸载(React、Solid、Svelte)。React:页面取消动画(`animation: none`)时离场立即结束并卸载,原来一直不卸载。
272
+ - 行为变化:Modal 的 `afterClose`、SideSheet 的 `afterVisibleChange` 每次显示只报一次:离场动画期间重新打开算同一次显示,卸载时仍欠着的 `afterClose` 补报。`Modal.destroyAll()` 只关闭本框架包创建的确认框,不同框架的包同页时互不关闭。确认框挂载前调用 `destroy()` 时不再渲染,`afterClose` 在 `destroy()` 内同步调用。
273
+ - 行为变化:React 的 Modal、SideSheet 被 `<Activity mode="hidden">` 隐藏时不报 `afterClose`、`afterVisibleChange(false)`,只有真正卸载才报;隐藏期间释放 body 滚动锁与遮罩栈,重新显示后再取回。SideSheet 每次显示时判定一次是否模态,显示期间改 `mask` 或容器要到下次显示才生效。React ModalContent 的初始焦点按 `autofocus` 处理,与其余三个框架一致。
274
+ - Vue、Svelte:显式传 `aria-labelledby={undefined}`、`aria-modal={undefined}` 时按未传处理,对话框仍由标题命名并保留默认的 `aria-modal`,与 React、Solid 一致(原来会去掉标题引用,对话框没有可访问名称)。