@fibrae/semi-ui-svelte 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/README.md +8 -4
  2. package/README.zh-CN.md +8 -4
  3. package/dist/components/anchor/interface.d.ts +14 -0
  4. package/dist/components/audio-player/interface.d.ts +5 -0
  5. package/dist/components/auto-complete/interface.d.ts +29 -0
  6. package/dist/components/avatar/interface.d.ts +24 -0
  7. package/dist/components/backtop/interface.d.ts +2 -0
  8. package/dist/components/badge/interface.d.ts +7 -0
  9. package/dist/components/banner/interface.d.ts +7 -0
  10. package/dist/components/breadcrumb/interface.d.ts +10 -0
  11. package/dist/components/button/interface.d.ts +18 -0
  12. package/dist/components/calendar/interface.d.ts +16 -0
  13. package/dist/components/card/interface.d.ts +18 -0
  14. package/dist/components/carousel/interface.d.ts +16 -0
  15. package/dist/components/cascader/cascader.svelte +1 -0
  16. package/dist/components/cascader/interface.d.ts +57 -0
  17. package/dist/components/checkbox/interface.d.ts +19 -0
  18. package/dist/components/code-highlight/interface.d.ts +3 -0
  19. package/dist/components/collapse/interface.d.ts +16 -0
  20. package/dist/components/collapsible/interface.d.ts +10 -0
  21. package/dist/components/color-picker/interface.d.ts +10 -0
  22. package/dist/components/config-provider/interface.d.ts +7 -0
  23. package/dist/components/cropper/interface.d.ts +11 -0
  24. package/dist/components/date-picker/interface.d.ts +47 -0
  25. package/dist/components/descriptions/interface.d.ts +6 -0
  26. package/dist/components/divider/interface.d.ts +4 -0
  27. package/dist/components/dropdown/interface.d.ts +8 -0
  28. package/dist/components/empty/interface.d.ts +7 -0
  29. package/dist/components/feedback/interface.d.ts +16 -0
  30. package/dist/components/float-button/interface.d.ts +14 -0
  31. package/dist/components/form/interface.d.ts +47 -0
  32. package/dist/components/form/label.svelte +2 -2
  33. package/dist/components/grid/interface.d.ts +13 -0
  34. package/dist/components/highlight/interface.d.ts +7 -0
  35. package/dist/components/hot-keys/interface.d.ts +3 -0
  36. package/dist/components/image/interface.d.ts +59 -0
  37. package/dist/components/input/interface.d.ts +67 -0
  38. package/dist/components/input-number/interface.d.ts +24 -0
  39. package/dist/components/json-viewer/interface.d.ts +7 -0
  40. package/dist/components/layout/interface.d.ts +3 -0
  41. package/dist/components/list/interface.d.ts +18 -0
  42. package/dist/components/locale/interface.d.ts +4 -0
  43. package/dist/components/lottie/interface.d.ts +2 -0
  44. package/dist/components/markdown-render/interface.d.ts +5 -0
  45. package/dist/components/modal/interface.d.ts +29 -0
  46. package/dist/components/navigation/interface.d.ts +47 -0
  47. package/dist/components/overflow-list/interface.d.ts +11 -0
  48. package/dist/components/pagination/interface.d.ts +12 -0
  49. package/dist/components/pincode/interface.d.ts +8 -0
  50. package/dist/components/popconfirm/interface.d.ts +12 -0
  51. package/dist/components/popover/interface.d.ts +30 -0
  52. package/dist/components/progress/interface.d.ts +13 -0
  53. package/dist/components/radio/interface.d.ts +22 -0
  54. package/dist/components/rating/interface.d.ts +12 -0
  55. package/dist/components/resizable/interface.d.ts +30 -0
  56. package/dist/components/scroll-list/interface.d.ts +6 -0
  57. package/dist/components/select/interface.d.ts +63 -0
  58. package/dist/components/side-sheet/interface.d.ts +19 -0
  59. package/dist/components/skeleton/interface.d.ts +7 -0
  60. package/dist/components/slider/interface.d.ts +23 -0
  61. package/dist/components/space/interface.d.ts +4 -0
  62. package/dist/components/spin/interface.d.ts +7 -0
  63. package/dist/components/steps/interface.d.ts +9 -0
  64. package/dist/components/switch/interface.d.ts +7 -0
  65. package/dist/components/table/interface.d.ts +48 -0
  66. package/dist/components/tabs/interface.d.ts +29 -0
  67. package/dist/components/tag/interface.d.ts +22 -0
  68. package/dist/components/tag-input/interface.d.ts +29 -0
  69. package/dist/components/time-picker/interface.d.ts +31 -0
  70. package/dist/components/timeline/interface.d.ts +5 -0
  71. package/dist/components/tooltip/interface.d.ts +20 -0
  72. package/dist/components/tooltip/tooltip.svelte +3 -0
  73. package/dist/components/transfer/interface.d.ts +18 -0
  74. package/dist/components/tree/interface.d.ts +45 -0
  75. package/dist/components/tree-select/interface.d.ts +55 -0
  76. package/dist/components/typography/interface.d.ts +33 -0
  77. package/dist/components/upload/interface.d.ts +64 -0
  78. package/dist/components/user-guide/interface.d.ts +15 -0
  79. package/dist/components/video-player/interface.d.ts +22 -0
  80. package/dist/styles.css +1 -1
  81. package/docs/advanced/dark-mode.md +288 -0
  82. package/docs/basic/button.md +605 -0
  83. package/docs/basic/divider.md +103 -0
  84. package/docs/basic/float-button.md +246 -0
  85. package/docs/basic/grid.md +427 -0
  86. package/docs/basic/layout.md +459 -0
  87. package/docs/basic/resizable.md +584 -0
  88. package/docs/basic/space.md +163 -0
  89. package/docs/basic/tokens.md +425 -0
  90. package/docs/basic/typography.md +615 -0
  91. package/docs/changes-from-semi.md +105 -0
  92. package/docs/ecosystem/tailwind.md +210 -0
  93. package/docs/experience/accessibility.md +82 -0
  94. package/docs/experience/content-guidelines.md +819 -0
  95. package/docs/experience/internationalization.md +7 -0
  96. package/docs/feedback/banner.md +198 -0
  97. package/docs/feedback/feedback.md +294 -0
  98. package/docs/feedback/notification.md +401 -0
  99. package/docs/feedback/popconfirm.md +243 -0
  100. package/docs/feedback/progress.md +389 -0
  101. package/docs/feedback/skeleton.md +388 -0
  102. package/docs/feedback/spin.md +172 -0
  103. package/docs/feedback/toast.md +393 -0
  104. package/docs/input/auto-complete.md +399 -0
  105. package/docs/input/cascader.md +1558 -0
  106. package/docs/input/checkbox.md +408 -0
  107. package/docs/input/color-picker.md +175 -0
  108. package/docs/input/date-picker.md +942 -0
  109. package/docs/input/form.md +2550 -0
  110. package/docs/input/input-number.md +451 -0
  111. package/docs/input/input.md +640 -0
  112. package/docs/input/pincode.md +191 -0
  113. package/docs/input/radio.md +337 -0
  114. package/docs/input/rating.md +214 -0
  115. package/docs/input/select.md +1230 -0
  116. package/docs/input/slider.md +347 -0
  117. package/docs/input/switch.md +206 -0
  118. package/docs/input/tag-input.md +465 -0
  119. package/docs/input/time-picker.md +358 -0
  120. package/docs/input/transfer.md +1061 -0
  121. package/docs/input/tree-select.md +1300 -0
  122. package/docs/input/upload.md +1811 -0
  123. package/docs/llms.txt +147 -0
  124. package/docs/navigation/anchor.md +377 -0
  125. package/docs/navigation/backtop.md +100 -0
  126. package/docs/navigation/breadcrumb.md +284 -0
  127. package/docs/navigation/navigation.md +851 -0
  128. package/docs/navigation/pagination.md +217 -0
  129. package/docs/navigation/steps.md +315 -0
  130. package/docs/navigation/tabs.md +754 -0
  131. package/docs/navigation/tree.md +1956 -0
  132. package/docs/other/config-provider.md +599 -0
  133. package/docs/other/locale.md +353 -0
  134. package/docs/plus/audio-player.md +155 -0
  135. package/docs/plus/code-highlight.md +150 -0
  136. package/docs/plus/drag-move.md +214 -0
  137. package/docs/plus/hot-keys.md +174 -0
  138. package/docs/plus/json-viewer.md +392 -0
  139. package/docs/plus/lottie.md +176 -0
  140. package/docs/plus/markdown-render.md +240 -0
  141. package/docs/plus/video-player.md +325 -0
  142. package/docs/show/avatar.md +475 -0
  143. package/docs/show/badge.md +276 -0
  144. package/docs/show/calendar.md +352 -0
  145. package/docs/show/card.md +485 -0
  146. package/docs/show/carousel.md +592 -0
  147. package/docs/show/collapse.md +289 -0
  148. package/docs/show/collapsible.md +216 -0
  149. package/docs/show/cropper.md +285 -0
  150. package/docs/show/descriptions.md +325 -0
  151. package/docs/show/dropdown.md +466 -0
  152. package/docs/show/empty.md +225 -0
  153. package/docs/show/highlight.md +144 -0
  154. package/docs/show/image.md +433 -0
  155. package/docs/show/list.md +927 -0
  156. package/docs/show/modal.md +517 -0
  157. package/docs/show/overflow-list.md +272 -0
  158. package/docs/show/popover.md +534 -0
  159. package/docs/show/scroll-list.md +156 -0
  160. package/docs/show/side-sheet.md +274 -0
  161. package/docs/show/table.md +5437 -0
  162. package/docs/show/tag.md +428 -0
  163. package/docs/show/timeline.md +277 -0
  164. package/docs/show/tooltip.md +442 -0
  165. package/docs/show/user-guide.md +419 -0
  166. package/docs/start/getting-started.md +234 -0
  167. package/docs/start/introduction.md +57 -0
  168. package/docs/start/overview.md +21 -0
  169. package/package.json +5 -4
@@ -0,0 +1,214 @@
1
+ # Rating
2
+
3
+ > Ratings provide insight regarding others' opinions and experiences with a product.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/input/rating/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Rating } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ Support two sizes: `default`, `small`.
20
+
21
+ Supports customized size if pass in a number. Refer to [Customize](#Customize)
22
+
23
+ ```svelte
24
+ <script lang="ts">
25
+ import { Rating } from '@fibrae/semi-ui-svelte';
26
+ </script>
27
+
28
+ <div>
29
+ <Rating value={5} />
30
+ <br />
31
+ <br />
32
+ <Rating size="small" value={5} />
33
+ </div>
34
+ ```
35
+
36
+ ### Half Star
37
+
38
+ Use `allowHalf` to support selection of half stars. Support to **display** decimals ratings other than 0.5.
39
+
40
+ ```svelte
41
+ <script lang="ts">
42
+ import { Rating } from '@fibrae/semi-ui-svelte';
43
+ </script>
44
+
45
+ <div>
46
+ <Rating allowHalf value={3.5} />
47
+ <br />
48
+ <Rating allowHalf disabled value={3.65} />
49
+ </div>
50
+ ```
51
+
52
+ ### Disabled
53
+
54
+ Use `disabled` to disabled interaction.
55
+
56
+ ```svelte
57
+ <script lang="ts">
58
+ import { Rating } from '@fibrae/semi-ui-svelte';
59
+ </script>
60
+
61
+ <Rating disabled value={3} />
62
+ ```
63
+
64
+ ### Click to Clear
65
+
66
+ `allowClear` Property allows you to clear the value when you click on the component again. By default it is set to `true`.
67
+
68
+ ```svelte
69
+ <script lang="ts">
70
+ import { Rating } from '@fibrae/semi-ui-svelte';
71
+ </script>
72
+
73
+ <div>
74
+ <span>允许再次点击清除</span>
75
+ <br />
76
+ <Rating allowClear value={3} />
77
+ <br />
78
+ <br />
79
+ <span>禁止再次点击清除</span>
80
+ <br />
81
+ <Rating allowClear={false} value={3} />
82
+ </div>
83
+ ```
84
+
85
+ ### Text Description
86
+
87
+ Use `tooltips` to add description to Rating.
88
+
89
+ ```svelte
90
+ <script lang="ts">
91
+ import { Rating } from '@fibrae/semi-ui-svelte';
92
+
93
+ let value = $state<number | undefined>(0);
94
+ const desc = ['极差', '较差', '一般', '满意', '非常满意'];
95
+ </script>
96
+
97
+ <div>
98
+ <span>
99
+ 你对获得的帮助是否满意:
100
+ {#if value}
101
+ <span>{desc[value - 1]}</span>
102
+ {/if}
103
+ </span>
104
+ <br />
105
+ <Rating bind:value tooltips={desc} />
106
+ </div>
107
+ ```
108
+
109
+ ### Customize
110
+
111
+ You can customize characters, numbers of rating and size.
112
+
113
+ > Note that customized size could only work with customized characters.
114
+
115
+ Use the `character` prop to customize the character: pass a string, or a snippet defined with `{#snippet character()}...{/snippet}`.
116
+
117
+ ```svelte
118
+ <script lang="ts">
119
+ import { IconLikeHeart } from '@fibrae/semi-icons-svelte';
120
+ import { Rating } from '@fibrae/semi-ui-svelte';
121
+ </script>
122
+
123
+ <div>
124
+ <Rating style="color: red" value={3}>
125
+ {#snippet character()}
126
+ <IconLikeHeart size="extra-large" />
127
+ {/snippet}
128
+ </Rating>
129
+ <br />
130
+ <br />
131
+ <Rating allowHalf size={48} style="color: red" value={3}>
132
+ {#snippet character()}
133
+ <IconLikeHeart style="font-size: 48px" />
134
+ {/snippet}
135
+ </Rating>
136
+ <br />
137
+ <br />
138
+ <Rating character="赞" size={18} value={3} />
139
+ <br />
140
+ <br />
141
+ <Rating count={10} value={6} />
142
+ </div>
143
+ ```
144
+
145
+ ## API Reference
146
+
147
+ **Props**
148
+
149
+ | Property | Description | Type | Default |
150
+ | - | - | - | - |
151
+ | allowClear | Whether clicking the selected star again clears the value. | `boolean` | `true` |
152
+ | allowHalf | Whether half stars can be selected. | `boolean` | `false` |
153
+ | autofocus | Whether to focus on mount. | `boolean \| null` | - |
154
+ | character | Character drawn in every star, a string or a snippet. A string is also the unit in each star's accessible name and the group summary; for a snippet the locale's unit is used. | `string \| Snippet` | - |
155
+ | count | Total number of stars. | `number` | `5` |
156
+ | disabled | Read-only: no interaction and no focus. | `boolean` | `false` |
157
+ | onBlur | Called when focus leaves the rating. | `(event: FocusEvent) => void` | - |
158
+ | onChange | Called when the selection changes, with the new value. | `(value: number) => void` | - |
159
+ | onClick | Called when a star is clicked or selected with Enter or Space, with the event and the star index. It shadows a native click listener on the root element. | `(event: MouseEvent \| KeyboardEvent, index: number) => void` | - |
160
+ | onFocus | Called when focus enters the rating; moving between stars does not call it. | `(event: FocusEvent) => void` | - |
161
+ | onHoverChange | Called when the hovered value changes; receives undefined when the pointer leaves or a click clears the value. | `(value?: number) => void` | - |
162
+ | onKeyDown | Called only for an arrow key that moved the value. | `(event: KeyboardEvent) => void` | - |
163
+ | preventScroll | Whether the browser should avoid scrolling the document to show the newly focused element, for focus inside the component. | `boolean` | - |
164
+ | size | Size: default or small, or a number for a custom size. | `'default' \| 'small' \| number` | `"default"` |
165
+ | tooltips | Prompt text for each item. | `string[]` | - |
166
+ | value | Current value; bind it with `bind:value`. `bind:value={get, set}` makes it fully controlled; a plain `value` is the initial value and user interaction changes it afterwards. | `number` | - |
167
+
168
+ **Methods**
169
+
170
+ | Method | Description | Type |
171
+ | - | - | - |
172
+ | blur | Blurs the focused element inside the rating. Does nothing when focus is elsewhere or the rating is disabled. | `() => void` |
173
+ | focus | Focuses the radio that Tab reaches, the same one autofocus uses. Does nothing when disabled. | `() => void` |
174
+
175
+ `value` is bindable and there is no `defaultValue`: a plain `value` is the initial value, `bind:value` reads and writes it, and a function binding can refuse or rewrite it. `class`, `style` (a string) and native attributes (`id`, `aria-labelledby`, `aria-invalid`, `aria-required`, `data-*` and so on) land on the `role="radiogroup"` root `ul`; `aria-label` is used as the accessible name as is, and without it the name summarizes the current value; `tabindex` and `name` are discarded and the list is fixed at `tabindex="-1"`, so only the checked radio can be reached with Tab.
176
+
177
+ `focus()` and `blur()` are called through `bind:this`: `focus()` focuses the radio that Tab reaches (the same one `autofocus` uses), and `blur()` only takes effect when focus is inside the rating.
178
+
179
+ ## Accessibility
180
+
181
+ ### ARIA
182
+
183
+ - Rating has `aria-checked` to indicate whether it is currently selected, `aria-posinset` to indicate the position in the list, and `aria-setsize` to indicate the length of the list.
184
+ - Semi supports custom Rating semantics
185
+ - `aria-label` is used as is for the accessible name of the radiogroup;
186
+ - If the custom character is plain text (the `character` prop as a string in React, a text-only `#character` slot in Vue), each star's name uses that text as the unit, otherwise the locale's default unit;
187
+ - The two are independent and can be passed together.
188
+
189
+ ### Keyboard and Focus
190
+
191
+ - Initial focus settings for Rating (the Tab stop, following the APG radio group):
192
+ - If there is a selection item in Rating, the initial focus is set to the last selection item (for example: if 3 stars are lit, the initial focus is set on the third lit star);
193
+ - If Rating has no selected item (value is 0), the initial focus is on the empty-star radio that stands for 0 stars;
194
+ - When the value matches no radio (for example 2.5 without `allowHalf`), the first radio is the Tab stop, so the keyboard can still enter; an arrow key then selects the adjacent radio (3 with the right arrow and 2 with the left arrow for 2.5).
195
+ - On a Rating group, use the `down arrow` or `right arrow` to select the next star (the value increases, and wraps to 0 after the last star) and the `up arrow` or `left arrow` to select the previous star (the value decreases, and wraps from 0 to the last star); in RTL only the left and right arrows are mirrored;
196
+ - The user sets the `allowHalf` property, and presses the arrow keys to select or deselect only half a star;
197
+ - `Space` selects the focused star when it is not selected; pressing `Space` on a selected star does not clear it. Clear with `Enter` or a click (controlled by `allowClear`);
198
+ - The list itself is not a Tab stop, so Rating used as a Tooltip trigger adds no extra Tab stop;
199
+ - Calling `focus()` on the instance focuses the radio that Tab reaches;
200
+ - With `tooltips`, keyboard focus on a star shows that star's tip, linked through `aria-describedby`;
201
+ - A disabled Rating cannot get the focus.
202
+
203
+ ## Design Tokens
204
+
205
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/input/rating/>
206
+
207
+ ## Changes from Semi Design
208
+
209
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
210
+
211
+ - 破坏性:`tabIndex` 不再是声明的属性,传入的值(含 Tooltip 注入)被丢弃,只有选中的 radio 是 Tab 停靠点。破坏性(样式钩子):删除 `semi-rating-focus` 类名,焦点环改由 `:focus-visible` 绘制。
212
+ - 键盘按 APG radio group:下、右方向键选中下一个,上、左选中上一个(原来上增下减,与文档相反),RTL 只镜像左右;空格选中未选中的星,已选中的星上不再清除;Enter 由被按下的 radio 决定值。`onFocus`、`onBlur` 只在焦点进入或离开整个控件时触发;`onHoverChange` 参数改为 `number | undefined`;配置 `tooltips` 时星距与不配置一致(默认 30px,原来 24px)。
213
+ - Svelte:`value` 可绑定,回调 `onChange(value)`,没有 `defaultValue`,受控 `value` 变回 `undefined` 时回到 0;事件为 `onChange`、`onHoverChange`、`onClick(event, index)`、`onFocus`、`onBlur`、`onKeyDown`。
214
+ - Svelte:`character` 是 `string | Snippet`,字符串既是每颗星画的字符,也是星值的单位,snippet 时单位取语言包;`aria-label`、`aria-labelledby` 是原生属性,没有 `ariaLabel`;`tabindex`、`name` 被丢弃;放进外层 Tooltip 时,描述挂在 Tooltip 的 span 上,不注入到 ul。