@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,408 @@
1
+ # Checkbox
2
+
3
+ > Checkboxes allow the user to select one or more items from a set.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/checkbox/
6
+
7
+ ## When to use
8
+
9
+ - When making multiple choices in a set of options;
10
+ - Use independently to select from different states, similar to the Switch component. The difference is that switching the Switch triggers a state change directly, while Checkbox is generally used for tagging status and works with the submission.
11
+
12
+ ## Demos
13
+
14
+ ### How to import
15
+
16
+ ```svelte
17
+ <script lang="ts">
18
+ import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';
19
+ </script>
20
+ ```
21
+
22
+ ### Basic Usage
23
+
24
+ When the Checkbox is used individually, a plain `checked` is only the initial checked state and the user's clicks toggle it afterwards. Use `bind:checked` to read and write the state; see "Controlled".
25
+
26
+ ```svelte
27
+ <script lang="ts">
28
+ import { Checkbox } from '@fibrae/semi-ui-svelte';
29
+ </script>
30
+
31
+ <Checkbox aria-label="Checkbox 示例" onChange={(e) => console.log(e)}>Semi Design</Checkbox>
32
+ ```
33
+
34
+ ```svelte
35
+ <script lang="ts">
36
+ import { Checkbox } from '@fibrae/semi-ui-svelte';
37
+ </script>
38
+
39
+ <Checkbox aria-label="Checkbox 示例" checked onChange={(e) => console.log(e)}>Semi Design</Checkbox>
40
+ ```
41
+
42
+ You can use `extra` to add extra information. It takes a snippet: define it inside the Checkbox tag with `{#snippet extra()}...{/snippet}`, and the rest of the content is the label. The extra information usually is longer and even has line changes.
43
+
44
+ ```svelte
45
+ <script lang="ts">
46
+ import { Checkbox } from '@fibrae/semi-ui-svelte';
47
+ </script>
48
+
49
+ <Checkbox aria-label="Checkbox 示例">
50
+ Semi Design
51
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
52
+ </Checkbox>
53
+ <br />
54
+ <Checkbox aria-label="Checkbox 示例" style="width: 280px">
55
+ Semi Design
56
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
57
+ </Checkbox>
58
+ ```
59
+
60
+ ### Disabled
61
+
62
+ ```svelte
63
+ <script lang="ts">
64
+ import { Checkbox } from '@fibrae/semi-ui-svelte';
65
+ </script>
66
+
67
+ <div>
68
+ <Checkbox aria-label="Checkbox 示例" checked={false} disabled>Unchecked Disabled</Checkbox>
69
+ <br />
70
+ <Checkbox aria-label="Checkbox 示例" checked disabled>Checked Disabled</Checkbox>
71
+ </div>
72
+ ```
73
+
74
+ ### Checkbox Group in JSX
75
+
76
+ By placing the Checkbox element inside the CheckboxGroup, you can declare the Checkbox group. Using the Checkbox group, you can more conveniently control the selection of a group of Checkboxes through the `value` of the CheckboxGroup: a plain `value` is the initial value, and `bind:value` reads and writes it. At this time, Checkbox does not need to declare `checked`.
77
+
78
+ ```svelte
79
+ <script lang="ts">
80
+ import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';
81
+ </script>
82
+
83
+ <CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%" value={['A', 'B']}>
84
+ <Checkbox value="A">A</Checkbox>
85
+ <Checkbox value="B">B</Checkbox>
86
+ <Checkbox value="C">C</Checkbox>
87
+ <Checkbox value="D">D</Checkbox>
88
+ <Checkbox value="E">E</Checkbox>
89
+ </CheckboxGroup>
90
+ ```
91
+
92
+ ### Checkbox Group in options
93
+
94
+ You can pass an array using `options` to `CheckboxGroup` directly to generate a set of checkboxs.
95
+
96
+ ```svelte
97
+ <script lang="ts">
98
+ import { CheckboxGroup, type CheckboxValue } from '@fibrae/semi-ui-svelte';
99
+
100
+ const onChange = (checkedValues: CheckboxValue[]) => console.log('checked = ', checkedValues);
101
+
102
+ const plainOptions = ['Semi UI', 'Semi Theme', 'Semi Core'];
103
+
104
+ const optionsWithExtra = [
105
+ {
106
+ extra: '通过 --semi-* 变量快速定制你的主题,并应用在设计稿和代码中',
107
+ label: 'Semi Theme',
108
+ value: 'theme',
109
+ },
110
+ { extra: '一套组件,四个框架原生可用', label: 'Semi Core', value: 'core' },
111
+ ];
112
+
113
+ const optionsWithDisabled = [
114
+ { label: 'Photography', value: 'Photography' },
115
+ { label: 'Movies', value: 'Movies' },
116
+ { label: 'Running', value: 'Running', disabled: false },
117
+ ];
118
+ </script>
119
+
120
+ <div>
121
+ <CheckboxGroup aria-label="CheckboxGroup 示例" {onChange} options={plainOptions} value={['Semi Core']} />
122
+ <br />
123
+ <br />
124
+ <CheckboxGroup aria-label="带 extra 示例" {onChange} options={optionsWithExtra} value={[]} />
125
+ <br />
126
+ <br />
127
+ <CheckboxGroup aria-label="Checkbox 示例" disabled {onChange} options={optionsWithDisabled} value={['Photography']} />
128
+ </div>
129
+ ```
130
+
131
+ ### Layout Direction
132
+
133
+ By setting `direction` to `horizontal` or `vertical`, You can adjust the layout within the Checkbox Group.
134
+
135
+ ```svelte
136
+ <script lang="ts">
137
+ import { CheckboxGroup } from '@fibrae/semi-ui-svelte';
138
+
139
+ const options = [
140
+ { label: '短视频', value: 'video' },
141
+ { label: '资讯', value: 'news' },
142
+ ];
143
+ </script>
144
+
145
+ <CheckboxGroup aria-label="CheckboxGroup 示例" direction="horizontal" {options} />
146
+ ```
147
+
148
+ ### Controlled Component
149
+
150
+ Used as a controlled component.
151
+
152
+ ```svelte
153
+ <script lang="ts">
154
+ import { Button, Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';
155
+
156
+ let checked = $state(true);
157
+ let disabled = $state(false);
158
+ const label = $derived(`${checked ? 'Checked' : 'Unchecked'} ${disabled ? 'Disabled' : 'Enabled'}`);
159
+
160
+ const onChange = (e: CheckboxEvent) => console.log('checked = ', e.target.checked);
161
+ </script>
162
+
163
+ <div>
164
+ <div style="margin-bottom: 20px">
165
+ <Checkbox aria-label="Checkbox 示例" bind:checked {disabled} {onChange}>
166
+ {label}
167
+ </Checkbox>
168
+ </div>
169
+ <p>
170
+ <Button size="small" type="primary" onclick={() => (checked = !checked)}>{!checked ? 'Check' : 'Uncheck'}</Button>
171
+ <Button size="small" style="margin-left: 10px" type="primary" onclick={() => (disabled = !disabled)}>
172
+ {!disabled ? 'Disable' : 'Enable'}
173
+ </Button>
174
+ </p>
175
+ </div>
176
+ ```
177
+
178
+ ### Checkbox State
179
+
180
+ You may use the `indeterminate` property to set the state to indeterminate.
181
+
182
+ ```svelte
183
+ <script lang="ts">
184
+ import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrae/semi-ui-svelte';
185
+
186
+ const plainOptions = ['Photography', 'Movies', 'Running'];
187
+ let checkedList = $state<CheckboxValue[]>(['Photography', 'Running']);
188
+ let indeterminate = $state(true);
189
+ let checkAll = $state(false);
190
+
191
+ const onChange = (list: CheckboxValue[]) => {
192
+ checkedList = list;
193
+ indeterminate = !!list.length && list.length < plainOptions.length;
194
+ checkAll = list.length === plainOptions.length;
195
+ };
196
+ const onCheckAllChange = (e: CheckboxEvent) => {
197
+ console.log(e);
198
+ checkedList = e.target.checked ? plainOptions : [];
199
+ indeterminate = false;
200
+ checkAll = e.target.checked;
201
+ };
202
+ </script>
203
+
204
+ <div>
205
+ <div style="padding-bottom: 8px; border-bottom: 1px solid var(--semi-color-border)">
206
+ <Checkbox aria-label="Checkbox 示例" checked={checkAll} {indeterminate} onChange={onCheckAllChange}>Check all</Checkbox>
207
+ </div>
208
+ <CheckboxGroup aria-label="CheckboxGroup 示例" {onChange} options={plainOptions} style="margin-top: 6px" value={checkedList} />
209
+ </div>
210
+ ```
211
+
212
+ ### Card Style
213
+
214
+ You can set `type='card'` to CheckboxGroup to realize card style with background.
215
+
216
+ ```svelte
217
+ <script lang="ts">
218
+ import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';
219
+ </script>
220
+
221
+ <CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="card" value={['1', '3']}>
222
+ <Checkbox disabled style="width: 280px" value="1">
223
+ 单选框标题
224
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
225
+ </Checkbox>
226
+ <Checkbox disabled style="width: 280px" value="2">
227
+ 单选框标题
228
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
229
+ </Checkbox>
230
+ <Checkbox style="width: 280px" value="3">
231
+ 单选框标题
232
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
233
+ </Checkbox>
234
+ <Checkbox style="width: 280px" value="4">
235
+ 单选框标题
236
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
237
+ </Checkbox>
238
+ </CheckboxGroup>
239
+ ```
240
+
241
+ ### Pure Card Style
242
+
243
+ You can set `type='pureCard'` to CheckboxGroup to realize a pure card style with background and no checkbox.
244
+
245
+ ```svelte
246
+ <script lang="ts">
247
+ import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';
248
+ </script>
249
+
250
+ <CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="pureCard" value={['1', '3']}>
251
+ <Checkbox disabled style="width: 280px" value="1">
252
+ 单选框标题
253
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
254
+ </Checkbox>
255
+ <Checkbox disabled style="width: 280px" value="2">
256
+ 单选框标题
257
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
258
+ </Checkbox>
259
+ <Checkbox style="width: 280px" value="3">
260
+ 单选框标题
261
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
262
+ </Checkbox>
263
+ <Checkbox style="width: 280px" value="4">
264
+ 单选框标题
265
+ {#snippet extra()}Semi Design Next 是 Semi Design 的社区版设计系统,一套组件在 React、Vue、Solid、Svelte 中原生可用{/snippet}
266
+ </Checkbox>
267
+ </CheckboxGroup>
268
+ ```
269
+
270
+ ### Using with Grid
271
+
272
+ Use `CheckboxGroup` with `Grid` to achieve flexible layouts.
273
+
274
+ ```svelte
275
+ <script lang="ts">
276
+ import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';
277
+ </script>
278
+
279
+ <CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%">
280
+ <Row>
281
+ <Col span={8}>
282
+ <Checkbox value="A">A</Checkbox>
283
+ </Col>
284
+ <Col span={8}>
285
+ <Checkbox value="B">B</Checkbox>
286
+ </Col>
287
+ <Col span={8}>
288
+ <Checkbox value="C">C</Checkbox>
289
+ </Col>
290
+ <Col span={8}>
291
+ <Checkbox value="D">D</Checkbox>
292
+ </Col>
293
+ <Col span={8}>
294
+ <Checkbox value="E">E</Checkbox>
295
+ </Col>
296
+ </Row>
297
+ </CheckboxGroup>
298
+ ```
299
+
300
+ ## API Reference
301
+
302
+ ### Checkbox
303
+
304
+ **Props**
305
+
306
+ | Property | Description | Type | Default |
307
+ | - | - | - | - |
308
+ | addonId | Id of the addon node, which aria-labelledby points to. Generated when omitted. | `string` | - |
309
+ | checked | Whether the checkbox is checked; bind it with `bind:checked`. Ignored inside a CheckboxGroup. `bind:checked={get, set}` makes it fully controlled; a plain `checked` is the initial value, a click overrides it inside the component, and a new value from the parent wins again. | `boolean` | - |
310
+ | children | Label content snippet of the checkbox, which is also the native input's accessible name. The rest of the tag's content is this snippet. | `Snippet` | - |
311
+ | disabled | Whether the checkbox is disabled. | `boolean` | `false` |
312
+ | extra | Snippet of the supplementary text, which aria-describedby points to. | `Snippet` | - |
313
+ | extraId | Id of the extra node, which aria-describedby points to. Generated when omitted. | `string` | - |
314
+ | indeterminate | Indeterminate state. It only affects the appearance and the native input's indeterminate flag, never the checked value. | `boolean` | `false` |
315
+ | name | The native input's name. Inside a CheckboxGroup the group's `name` applies. | `string \| null` | - |
316
+ | onChange | Called when the checked state changes. The event's `target` is `{ checked, value, name, disabled }`. | `(event: CheckboxEvent) => void` | - |
317
+ | onclick | Called when the root element is clicked, before the toggle. | `MouseEventHandler<T> \| null` | - |
318
+ | preventScroll | Whether focusing prevents the browser from scrolling the element into view; applies to the focus method. | `boolean` | - |
319
+ | type | Style type: default, card or pureCard. Inside a CheckboxGroup the group's type applies. | `CheckboxType` | `"default"` |
320
+ | value | The value this checkbox stands for in a CheckboxGroup. Without it the checkbox is not part of the group. | `CheckboxValue` | - |
321
+
322
+ **Methods**
323
+
324
+ | Method | Description | Type |
325
+ | - | - | - |
326
+ | blur | Removes focus from the native input. | `() => void` |
327
+ | focus | Focuses the native input. | `() => void` |
328
+
329
+ `class` and `style` (a string) land on the root `<span>`. `id`, `name`, `tabindex`, `autofocus`, `aria-*`, `onfocus` and `onblur` land on the inner native input; other native attributes and events (such as `onmouseenter`) land on the root element, and `onclick` is called before the toggle. Inside a CheckboxGroup the group's `name` wins.
330
+
331
+ ### CheckboxGroup
332
+
333
+ **Props**
334
+
335
+ | Property | Description | Type | Default |
336
+ | - | - | - | - |
337
+ | children | Checkbox components in the group. Ignored when options is set. | `Snippet` | - |
338
+ | direction | Layout direction inside the group: horizontal or vertical. | `CheckboxDirection` | `"vertical"` |
339
+ | disabled | Whether the whole group is disabled. | `boolean` | `false` |
340
+ | extra | Snippet for the extra text of each item in options, with the parameter `{ option, index }`. | `Snippet<[CheckboxGroupOptionSnippetProps]>` | - |
341
+ | label | Snippet for the label of each item in options, with the parameter `{ option, index }`. | `Snippet<[CheckboxGroupOptionSnippetProps]>` | - |
342
+ | name | The name of every native input in the group. A unique value is generated per group when omitted. | `string` | - |
343
+ | onBlur | Called when focus leaves the whole group; moving focus between its checkboxes does not call it. | `(event: FocusEvent) => void` | - |
344
+ | onChange | Called when the selected values change, with the new array of values. | `(value: CheckboxValue[]) => void` | - |
345
+ | onfocusout | Callback for the root element's focusout event, called before onBlur. | `FocusEventHandler<T> \| null` | - |
346
+ | options | Declares the options as data. Each item is a string or `{ label, value, disabled, extra, class, style }`, where `style` is a string. | `Array<string \| CheckboxOptionItem>` | - |
347
+ | type | Style type of every Checkbox in the group: default, card or pureCard. | `CheckboxType` | `"default"` |
348
+ | value | Selected values, matched against each Checkbox's value; bind it with `bind:value`. `bind:value={get, set}` makes it fully controlled; a plain `value` is the initial value. | `CheckboxValue[]` | - |
349
+
350
+ Each item in `options` has the fields `label`, `value`, `disabled`, `extra` (`string | number`), `class` and `style` (a string), and no `onChange`. Use the `label` and `extra` snippets, with the parameter `{ option, index }`, for custom content. `class`, `style` (a string), native attributes and events land on the root `<div>`; `onBlur` is called when focus leaves the whole group, not when it moves between the checkboxes inside. `aria-invalid` and `aria-errormessage` are passed to the native input of every Checkbox in the group; `aria-required`, `tabindex` and the `aria-expanded`, `aria-haspopup`, `aria-controls` injected by Tooltip are not rendered.
351
+
352
+ ## Methods
353
+
354
+ ### Checkbox
355
+
356
+ Call them on the Checkbox instance obtained with `bind:this`; see Methods above.
357
+
358
+ ## Accessibility
359
+
360
+ ### ARIA
361
+
362
+ - The role of Checkbox is `checkbox`, the role of CheckboxGroup is `group`, and its children have no extra role
363
+ - `aria-label`: When using the Checkbox alone, if Children have no text, it is recommended to pass in the `aria-label` prop to describe the function of the Checkbox in one sentence, which will make the screen reader read out the content of this label
364
+ - The native input's `aria-labelledby` points to the `addon` node, used to explain the role of the current Checkbox; a passed `aria-labelledby` also lands on the input, placed before the `addon` id
365
+ - `aria-describedby` points to the `extra` node, which is used to supplement the explanation of the current Checkbox
366
+ - The checked and disabled states are expressed by the native input's `checked` and `disabled`; `aria-checked` and `aria-disabled` are not rendered
367
+
368
+ ### Keyboard and focus
369
+
370
+ - Checkbox can be focused, keyboard users can use Tab and Shift + Tab to switch focus.
371
+ - The Checkbox that gets the focus can switch the selected and unselected states through Space.
372
+ - The click area of ​​Checkbox is larger than the box itself and contains the text behind the box; for checkboxes with auxiliary text, the auxiliary text is also included in the click area.
373
+ - Disabled Checkbox is not focusable.
374
+
375
+ ## Content Guidelines
376
+
377
+ Checkbox Content Demo
378
+
379
+ - Capitalize the first letter
380
+ - No punctuation
381
+
382
+ ## Design Tokens
383
+
384
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/checkbox/>
385
+
386
+ ## Changes from Semi Design
387
+
388
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
389
+
390
+ - 破坏性(样式钩子):删除 `semi-switch-focus`(及 `cssClasses.FOCUS`)、`semi-checkbox-focus`、`semi-checkbox-focus-border`,焦点环改由 CSS `:has(input:focus-visible)` 绘制;`SwitchState.nativeControlChecked` 改名 `checked`;Switch 的 `checked` 与 `defaultChecked` 同传时取 `checked`。
391
+ - 行为变化:Checkbox、Radio 的 `id` 落在原生 input 上(用 `#id` 选根元素的写法需改选 input 的父级),input 带 `value`;Checkbox 不再响应 Enter 切换(仅空格);`onClick` 在切换前调用;Switch 的 `loading` 期间切换被忽略且不通知 `onChange`;Switch 的全部 `aria-*` 落在 `role="switch"` 的 input 上,不再有任何 `aria-*` 落在根元素。
392
+ - CheckboxGroup 内没有 `value` 的 Checkbox 不参与分组取值,也不再继承分组的 `aria-invalid`、`aria-errormessage`。
393
+ - Svelte:Switch 的 `checked` 可绑定,`checkedText`、`uncheckedText` 为 snippet;`aria-*`、`id`、`name`、`tabindex`、`autofocus` 与焦点监听落在原生 input 上,其余未声明属性落在根元素。
394
+ - Svelte:Checkbox 的 `checked` 与 CheckboxGroup 的 `value` 可绑定,不提供 `defaultChecked`、`defaultValue`;`onChange` 对 Checkbox 收 `(event)`,`target` 为 `{ checked, value, name, disabled }`,对 CheckboxGroup 收 `(value)`。
395
+ - Svelte:`extra` 以及分组选项的 `label`、`extra` 是 snippet,参数 `{ option, index }`;`Checkbox.Group` 与具名导出 `CheckboxGroup` 是同一组件;`onclick` 在切换前调用,`onBlur` 在焦点离开整个分组时触发;`focus()`、`blur()` 经 `bind:this` 调用。
396
+ - Svelte:Switch、Checkbox 作为 Tooltip `child` snippet 的触发器时,`{...props}` 里的 attachment 会传到根元素。
397
+
398
+ - 破坏性:Radio 与 RadioGroup 删除 `addonClassName`、`addonStyle`,`options` 项删除 `addonClassName`(Vue、Solid、Svelte 为 `addonClass`)、`addonStyle`,改用 `classNames.addon`、`styles.addon`,落在 addon 容器上;`options` 项上的同名字段由 RadioGroup 下发给 Radio。
399
+ - 破坏性:Radio `mode="advanced"` 的 input 由 `type="checkbox"` 改回 `type="radio"`,按 `checkbox` 查询的测试需改为 `radio`;Checkbox、Radio 的 `onChange` 事件 `target` 在四个框架都只有 `{ checked, value, name, disabled }`,不再展开组件 props(原 Semi 为全部 props 加 `checked`);删除 `semi-radio-focus`、`semi-radio-focus-border` 等焦点与悬停类名,改用 CSS `:focus-visible`、`:hover`。
400
+ - 破坏性(类型):CheckboxGroup 的 `options` 收窄为 `Array<string | CheckboxOptionItem>`,`value`、`defaultValue`、`onChange` 参数收窄为 `Array<string | number | boolean>`,新增 `CheckboxOptionItem`;`RadioInnerProps` 不再含 `style`、`className`、`children`、`preventScroll`,新增 `id`、`value`。未传 `name` 时每组生成唯一 name,RadioGroup 内没有 `value` 的 Radio 在组值为 `undefined` 时不再判为选中。
401
+ - 行为变化:Radio 的 `checked` 与 `defaultChecked` 同传时取 `checked`,`checked={false}` 时内部状态不再被 `defaultChecked` 置为选中。
402
+ - Solid 破坏性(类型):RadioGroup `options` 项的 `label`、`extra` 收窄为 `string | number`(同 Vue),其他内容由 RadioGroup 新增的 `renderLabel(option, index)`、`renderExtra(option, index)` 提供(对应 Vue 的 `#label`、`#extra`),按钮型不调用 `renderExtra`;AIChatInput 的 `Configure.RadioButton` 同样适用。
403
+ - Svelte:Radio 的 `checked` 与 RadioGroup 的 `value` 可绑定,支持 `bind:`、函数绑定、单向传值、不传四种写法,不提供 `defaultChecked`、`defaultValue`,全局默认值也不能设 `value`、`checked`;`onChange(event)` 的 `target` 为 `{ checked, value, name, disabled }`。
404
+ - Svelte:RadioGroup 保留 `options`,自定义内容用 `label`、`extra` snippet(参数 `{ option, index }`),Radio 的 `children`、`extra` 是 snippet;`Radio.Group` 与具名导出 `RadioGroup` 是同一组件;`style`、`styles` 的值及选项里的同名字段只接受字符串。
405
+ - Svelte:根元素透传的是 `onclick`,只在点击落在 input 上时调用一次;`onBlur` 在焦点离开整个分组时触发;`focus()`、`blur()` 经 `bind:this` 调用。
406
+ - 行为变化:RadioGroup 内的 Radio 一律使用组的 `name`,Radio 自己的 `name` 不再生效(原来 Radio 的优先,设了不同 `name` 的 Radio 会脱离组的方向键导航),与 CheckboxGroup、Ant Design 一致。
407
+ - Vue(类型):RadioGroup 改为泛型 `RadioGroup<T extends RadioValue>`,`modelValue`、`defaultValue` 与 `update:modelValue` 的参数取 `T`,字面量联合类型的 ref 可直接 `v-model`;`RadioGroupProps`、`RadioGroupEmits` 带同名类型参数(默认 `RadioValue`),FormRadioGroup 随之泛型。
408
+ - 破坏性(类型):Checkbox、Radio 的 `onChange` 事件 `target` 中 `value`、`name` 改为可选属性(`value?: T`、`name?: string`),四个框架与 foundation 的 `RadioChangeEvent`、`BasicTargetObject` 一致;手写成必填属性的回调参数类型需改为可选或直接用导出的事件类型。
@@ -0,0 +1,175 @@
1
+ # ColorPicker
2
+
3
+ > Quickly and easily select colors, and provide a dropper tool to pick colors
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/color-picker/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Button, ColorPicker, colorStringToValue } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Use
18
+
19
+ #### In portal
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { Button, ColorPicker } from '@fibrae/semi-ui-svelte';
24
+ </script>
25
+
26
+ <div>
27
+ <ColorPicker alpha onChange={(value) => console.log(value)} usePopover />
28
+ <br />
29
+ <div>自定义 trigger</div>
30
+ <ColorPicker alpha onChange={(value) => console.log(value)} usePopover>
31
+ <Button>Trigger</Button>
32
+ </ColorPicker>
33
+ </div>
34
+ ```
35
+
36
+ #### Normal display
37
+
38
+ ```svelte
39
+ <script lang="ts">
40
+ import { ColorPicker } from '@fibrae/semi-ui-svelte';
41
+ </script>
42
+
43
+ <ColorPicker alpha onChange={(value) => console.log(value)} />
44
+ ```
45
+
46
+ ### Eyedropper Color Picker
47
+
48
+ The eyedropper is enabled by default and supports picking colors from the browser or external software screen. Pass `eyeDropper={false}` to turn it off.
49
+
50
+ > **Notes**
51
+ >
52
+ > To enable this function, the current web page must be deployed in a secure context such as HTTPS or localhost domain name, otherwise it will have no effect. It relies on the [EyeDropper API](https://developer.mozilla.org/docs/Web/API/EyeDropper), which only Chromium-based browsers support for now; in Firefox and
53
+ > Safari the eyedropper button does nothing
54
+
55
+ ```svelte
56
+ <script lang="ts">
57
+ import { ColorPicker } from '@fibrae/semi-ui-svelte';
58
+ </script>
59
+
60
+ <ColorPicker alpha eyeDropper onChange={(value) => console.log(value)} />
61
+ ```
62
+
63
+ ### Default Value
64
+
65
+ When converting between various color representation formats, there are theoretical errors between some formats, so the value returned to you by `onChange` is an object containing color values in three formats: hsva, hex, and rgba.
66
+
67
+ The `value` you pass in should also be an object containing the same three formats. Without `value` the picker manages its own color, and a one-way `value={x}` only seeds it.
68
+
69
+ We provide the tool function `colorStringToValue`, a named export of `@fibrae/semi-ui-svelte` rather than a member of the component, to convert common color strings to this object, supporting direct passing of strings such as rgb(57,197,187) #39c5bb (the short form #3cb is also accepted) and hsv(176,71,77). A string that cannot be parsed throws an error.
70
+
71
+ ```svelte
72
+ <script lang="ts">
73
+ import { ColorPicker, colorStringToValue } from '@fibrae/semi-ui-svelte';
74
+
75
+ const defaultValue = colorStringToValue('rgb(57,197,187)');
76
+ </script>
77
+
78
+ <div>
79
+ <ColorPicker alpha onChange={(value) => console.log(value)} value={defaultValue} />
80
+ </div>
81
+ ```
82
+
83
+ ### Controlled
84
+
85
+ Bind `value` with `bind:value` for controlled use; for full control use the function binding `bind:value={get, set}`. Treat the color value as immutable and replace it as a whole when updating (declare it with `$state.raw`); mutating a field such as `hsva.h` in place does not sync the text inputs.
86
+
87
+ ```svelte
88
+ <script lang="ts">
89
+ import { ColorPicker, colorStringToValue } from '@fibrae/semi-ui-svelte';
90
+
91
+ let value = $state.raw(colorStringToValue('#39c5bb'));
92
+ </script>
93
+
94
+ <div>
95
+ <ColorPicker alpha bind:value />
96
+ </div>
97
+ ```
98
+
99
+ ### Rendering additional elements at the top and bottom
100
+
101
+ Use the `topSlot` and `bottomSlot` snippets to render additional elements at the top and bottom
102
+
103
+ ```svelte
104
+ <script lang="ts">
105
+ import { ColorPicker } from '@fibrae/semi-ui-svelte';
106
+ </script>
107
+
108
+ <ColorPicker alpha onChange={(value) => console.log(value)}>
109
+ {#snippet topSlot()}
110
+ <div>TopSlot</div>
111
+ {/snippet}
112
+ {#snippet bottomSlot()}
113
+ <div>Bottom Slot</div>
114
+ {/snippet}
115
+ </ColorPicker>
116
+ ```
117
+
118
+ ### Keyboard and Focus
119
+
120
+ - With `usePopover`, the default trigger is a named button, and `Enter` or `Space` opens the popup. The popup is a `dialog` that opens on click by default and closes with `Esc`. Its name defaults to the built-in text; an `aria-label` or `aria-labelledby` passed in `popoverProps` (`ariaLabel`, `ariaLabelledby` in Vue) takes precedence.
121
+ - The handles of the color area, the hue slider and the alpha slider can all be operated with the keyboard. The color area has two sliders, saturation and brightness; the hue slider and the alpha slider have one each.
122
+ - Arrow keys step by 1, `PageUp` and `PageDown` step by 10, and `Home` and `End` jump to the ends. In the color area, whichever slider has focus, Left and Right change saturation, while Up, Down, `PageUp` and `PageDown` change brightness; `Home` and `End` act on the focused slider. Keys pressed with `Alt`, `Ctrl` or `Meta` are not handled, so the browser and assistive technology keep them.
123
+ - A focused handle shows the theme focus ring; the color input, the alpha input and the format selector all have accessible names.
124
+
125
+ ### API Table
126
+
127
+ #### ColorPicker
128
+
129
+ **Props**
130
+
131
+ | Property | Description | Type | Default |
132
+ | - | - | - | - |
133
+ | alpha | Whether to enable transparency selection. | `boolean` | `true` |
134
+ | bottomSlot | Snippet that renders extra elements at the bottom. | `Snippet` | - |
135
+ | children | Snippet used as the trigger when usePopover is on, a swatch of the current color by default; not rendered without usePopover. | `Snippet` | - |
136
+ | defaultFormat | Color format used by default for manual input: `rgba`, `hex` or `hsva`. | `ColorFormat` | `"hex"` |
137
+ | eyeDropper | Whether to enable the eyedropper color picker. | `boolean` | `true` |
138
+ | height | Height in pixels; 280 when not set. | `number` | `280` |
139
+ | onChange | Called with a ColorValue, holding hsva, hex and rgba, when the user picks a color. | `(value: ColorValue) => void` | - |
140
+ | popoverProps | Props passed to the Popover when usePopover is on, such as `trigger`, `aria-label` and `aria-labelledby`. The popup opens on click with role `dialog` by default and takes its name from the locale; `aria-label` or `aria-labelledby` takes precedence. | `PopoverProps` | - |
141
+ | topSlot | Snippet that renders extra elements at the top. | `Snippet` | - |
142
+ | usePopover | Whether to render inside a Popover; the trigger is `children`. Defaults to false. | `boolean` | `false` |
143
+ | value | The color, supports `bind:value`; an object holding hsva, hex and rgba. Left out, the component manages it and starts at `#39c5bb`. A one-way `value={x}` only seeds it; for a fully controlled picker use the function binding `bind:value={get, set}`. `null` is a controlled empty value: it shows the default color and only reports changes. Treat ColorValue as immutable and replace it as a whole. | `ColorValue \| null` | - |
144
+ | width | Width in pixels; 280 when not set. | `number` | `280` |
145
+
146
+ **Methods**
147
+
148
+ | Method | Description | Type |
149
+ | - | - | - |
150
+ | getRoot | Returns the picker root element; inside the popup when usePopover is on, so null while the popup is closed. | `() => HTMLDivElement \| null` |
151
+
152
+ #### Attribute placement
153
+
154
+ `class` (a string, array or object), `style` (a string) and other native attributes and events land on the picker root element; with `usePopover` they land on the picker element inside the popup, not on the trigger or the dialog. When the caller passes `aria-label` or `aria-labelledby` without a `role`, the picker root gets `role="group"`.
155
+
156
+ #### ColorValue
157
+
158
+ The `value` and the `onChange` payload are the same kind of object:
159
+
160
+ | Field | Description | Type |
161
+ | - | - | - |
162
+ | hsva | HSV color and opacity; h is 0-360, s and v are 0-100, a is 0-1 | `{ h: number; s: number; v: number; a: number }` |
163
+ | rgba | RGB color and opacity; r, g and b are 0-255, a is 0-1 | `{ r: number; g: number; b: number; a: number }` |
164
+ | hex | Hexadecimal color, `#rrggbb`, or `#rrggbbaa` with opacity | `string` |
165
+
166
+ ## Changes from Semi Design
167
+
168
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
169
+
170
+ - 输入区的间距改为逻辑属性,RTL 下镜像。
171
+ - `usePopover` 时弹层打开后焦点进入面板(第一个可聚焦控件),关闭后回到触发器(APG dialog)。
172
+ - 破坏性:`usePopover` 时弹层默认 trigger 由 `hover` 改为 `click`(`popoverProps.trigger` 优先)。`alpha` 默认为 true;受控 `value` 为 `null` 是受控的空值,变回 `undefined` 时回到 `defaultValue`。
173
+ - 破坏性(类型):`@fibrae/semi-ui-react/color-picker` 只导出 `ColorValue`、`ColorFormat`、`HsvaColor`、`RgbaColor`,不再导出 `ColorModel`、`AnyColor`、`ObjectColor` 等;`ColorPickerFoundation` 的静态转换方法删除,改从 `@fibrae/semi-foundation/color-picker/utils/convert` 导入。
174
+ - `ColorPicker.colorStringToValue` 支持 `#rgb`、`#rgba`,无法解析或越界的颜色字符串抛出以 `Semi ColorPicker` 开头的错误(原来得到 NaN、黑色或非法 hex)。选色区与两条滑条可用键盘操作。
175
+ - Svelte:`value` 可绑定,没有 `defaultValue`;单向 `value={x}` 只作初值,要完全受控用函数绑定 `bind:value={get, set}`;`value` 可为 `null`,表示受控的空值,显示默认色,只报告变化(同 Solid);`colorStringToValue` 是具名导出,不挂在组件上;`usePopover` 时顶层 `children` 是触发器 snippet,`topSlot`、`bottomSlot` 是 snippet,`popoverProps` 直接是 Popover 的 props;根元素经 `bind:this` 后调用 `getRoot()` 获取,没有 `ColorPickerHandle` 类型。