@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
package/docs/llms.txt ADDED
@@ -0,0 +1,147 @@
1
+ # Semi Design Next for Svelte
2
+
3
+ > Documentation for coding agents covering `@fibrae/semi-ui-svelte` 0.10.0. Read the rules first, then the page of each component you use: every page lists the props, events and methods with types and defaults, and runnable Svelte examples. Pages are long: search a page for `## API reference` or a prop name instead of reading it whole.
4
+
5
+ ## Rules
6
+
7
+ - This is Semi Design Next, a community fork of Semi Design that does not keep upstream compatibility. Never import `@douyinfe/semi-ui`, `@douyinfe/semi-icons` or `@douyinfe/semi-illustrations`, and do not trust what you remember about Semi Design props: read the page of every component you use.
8
+ - Import components from `@fibrae/semi-ui-svelte`, icons from `@fibrae/semi-icons-svelte`, illustrations from `@fibrae/semi-icons-svelte/illustrations`, and AI components (Chat, AIChatInput, AIChatDialogue, Sidebar and friends) from `@fibrae/semi-ai-svelte`. Prefer these root imports over deep paths; deep paths are kebab-case (`@fibrae/semi-ui-svelte/date-picker/index`).
9
+ - Styles load with each component and need no reset stylesheet. Theme through `--semi-*` CSS variables; Sass variables and theme packages are not a customization surface, and popups render in the top layer so z-index tokens do not exist.
10
+ - Style inner parts with the `classNames` and `styles` props, keyed by part name, instead of targeting internal class names.
11
+ - Controlled detection is by value: `value={undefined}` (likewise `checked`, `visible`, `activeKey`) means uncontrolled; `null` is a controlled empty value. Hide areas such as Modal `footer` with `null`.
12
+ - Built-in locales are `zh_CN` and `en_US` only, imported from `@fibrae/semi-ui-svelte/locale` and passed to ConfigProvider or LocaleProvider.
13
+ - Global default props go through `semiGlobal.config.overrideDefaultProps`, keyed by component name (Navigation uses `Nav`).
14
+ - Icons are decorative (`aria-hidden`); an icon-only button needs `aria-label`. Subcomponents are written with dot syntax at the use site (`<Select.Option>`).
15
+ - Supported browsers: Chrome 120, Firefox 125, Safari 17.2 and later.
16
+ - Svelte 5 with runes; the package ships `.svelte` sources, so the app needs a Svelte compiler plugin (`@sveltejs/vite-plugin-svelte`, SvelteKit).
17
+ - Controlled values are bindable props: `bind:checked={x}` syncs both ways, `bind:checked={get, set}` is fully controlled, `checked={x}` is only an initial value. There are no `default*` props.
18
+ - Node props and render functions are snippets named like Vue slots (no `render` prefix) whose argument is an object with named fields; default content is `children`. `class` accepts a string, array or object; `style` accepts a string only.
19
+ - Data-only subcomponents (`TabPane`, `Select.Option`, `Table.Column`) do not exist: use data props (`tabList`, `optionList`, `columns`) with per-item snippets. Methods are called on the instance from `bind:this`. Form has named exports only.
20
+
21
+ ## Related packages
22
+
23
+ - `@fibrae/semi-ai-svelte`, AI chat components (Chat, AIChatInput, AIChatDialogue, Sidebar, AI-styled basics): `node_modules/@fibrae/semi-ai-svelte/docs/llms.txt`
24
+ - `@fibrae/semi-icons-svelte`, icons and illustrations: `node_modules/@fibrae/semi-icons-svelte/docs/llms.txt`
25
+
26
+ ## Changes from Semi Design
27
+
28
+ - [Changes from Semi Design](changes-from-semi.md): breaking and behavior changes that apply to every component
29
+
30
+ ## Start
31
+
32
+ - [Introduction](start/introduction.md): Semi Design Next is a community fork of Semi Design that ships React 19, Vue 3.5+, Solid and Svelte 5 component libraries on top of a shared, framework-free Foundation.
33
+ - [Quick Start](start/getting-started.md): Install Semi Design Next and start using it in a React, Vue, Solid or Svelte project.
34
+ - [Overview](start/overview.md): Based on Semi design language, React, Vue, Solid and Svelte UI desktop component library that can be debugged online, helps developers build applications efficiently.
35
+
36
+ ## Design Collaboration
37
+
38
+ - [Dark Mode](advanced/dark-mode.md): Every Semi color variable has a light and a dark value, so a page can switch between light and dark mode.
39
+
40
+ ## Experience
41
+
42
+ - [Accessibility](experience/accessibility.md): Accessible design is about making it easy for everyone to interact with products, including those with disabilities, to provide a better experience for everyone. The Semi design system is designed to remove barriers and create inclusive product experiences that work for all.
43
+ - [Internationalization](experience/internationalization.md): Global design is not targeted at a certain market, but is based on commonalities, looking for differences, and creating an inclusive design so that different users in different countries and regions can understand the same design language and ensure the basic experience of the interface.
44
+ - [Content Guidelines](experience/content-guidelines.md): We are all keen to use Semi to create products that users like, and copywriting is the most direct communication method between products and users, and outputting correct and consistent copywriting is an indispensable part of product design.
45
+
46
+ ## Ecosystem
47
+
48
+ - [With TailwindCSS](ecosystem/tailwind.md): Use TailwindCSS and Semi more elegantly
49
+
50
+ ## Basic
51
+
52
+ - [Tokens](basic/tokens.md): Semi Design Next Tokens
53
+ - [Layout](basic/layout.md): Used to quickly divide the overall layout of the page
54
+ - [Grid](basic/grid.md): 24 grid system.
55
+ - [Resizable](basic/resizable.md): The component size is adjusted based on the user's mouse drag, supporting both resizing of a single component and combined resizing.
56
+ - [Button](basic/button.md): Users use buttons to trigger an operation or jump.
57
+ - [FloatButton](basic/float-button.md): A floating button is an actionable button that can float on the page
58
+ - [Typography](basic/typography.md): The basic format of text, images, paragraphs, and numeric.
59
+ - [Divider](basic/divider.md): Divider is a linear, lightweight component used to logically organize element content and page structure or areas.
60
+ - [Space](basic/space.md): Set the spacing between components.
61
+
62
+ ## Plus
63
+
64
+ - [CodeHighlight](plus/code-highlight.md): Highlight code blocks in the page according to syntax
65
+ - [Markdown Render](plus/markdown-render.md): Instantly render Markdown and MDX in web pages
66
+ - [DragMove](plus/drag-move.md): Set elements to change their position by dragging
67
+ - [JsonViewer](plus/json-viewer.md): Used for displaying and editing JSON data
68
+ - [HotKeys](plus/hot-keys.md): used to facilitate the customization of keyboard shortcut
69
+ - [Lottie Animation](plus/lottie.md): Display Lottie animation on the web page
70
+ - [AudioPlayer](plus/audio-player.md): Used to play audio
71
+ - [VideoPlayer](plus/video-player.md): Used to play video
72
+
73
+ ## Input
74
+
75
+ - [AutoComplete](input/auto-complete.md): The input box is automatically filled.
76
+ - [Cascader](input/cascader.md): Used to select an option under a multi-level classification.
77
+ - [Checkbox](input/checkbox.md): Checkboxes allow the user to select one or more items from a set.
78
+ - [ColorPicker](input/color-picker.md): Quickly and easily select colors, and provide a dropper tool to pick colors
79
+ - [DatePicker](input/date-picker.md): The date selector is used to help the user select a compliant, formatted date (time) or date (time) range.
80
+ - [Form](input/form.md): Form collects, validates and submits data, with built-in layouts, field linkage and on-demand rerendering.
81
+ - [Input](input/input.md): Input is a basic component for users to enter and edit text.
82
+ - [InputNumber](input/input-number.md): Through the mouse or keyboard, input the value in the range. Unlike Input, it has a stepper operation area for digital scenes, and it can display more complex content formats when used with Parser.
83
+ - [PinCode](input/pincode.md): For easy and intuitive verification code entry
84
+ - [Radio](input/radio.md): Radio component allows the user to select one option from a relative small set.
85
+ - [Rating](input/rating.md): Ratings provide insight regarding others' opinions and experiences with a product.
86
+ - [Select](input/select.md): The user can select one or more options from a set of options through the Select selector and present the final selection result
87
+ - [Slider](input/slider.md): Selector to quickly select a number or range of values using drag interaction, more intuitive than InputNumber
88
+ - [Switch](input/switch.md): Switch is an interactive form used to switch two mutually exclusive states.
89
+ - [TagInput](input/tag-input.md): Taginput is a input component that can add content as a tag.
90
+ - [TimePicker](input/time-picker.md): Users can easily select a compliant, formatted point of time using the time selector.
91
+ - [Transfer](input/transfer.md): A more intuitive and efficient multiple-selection selector, which can reveal more information about options, and supports search functions. The disadvantage is that it takes up more space
92
+ - [TreeSelect](input/tree-select.md): TreeSelector is used for structured display & selection of multi-level tree data, such as displaying a list of folders and files, displaying a list of organizational structure members, and so on.
93
+ - [Upload](input/upload.md): File selection upload
94
+
95
+ ## Navigation
96
+
97
+ - [Anchor](navigation/anchor.md): The Anchor component is used to create a hyper Link navigation bar.
98
+ - [BackTop](navigation/backtop.md): BackTop lets users return to the top of a long page with one click.
99
+ - [Breadcrumb](navigation/breadcrumb.md): Breadcrumbs allow users to make selections from a range of values and provide an auxiliary navigation that can return to previous page.
100
+ - [Navigation](navigation/navigation.md): A menu list that provides navigation for pages and features.
101
+ - [Pagination](navigation/pagination.md): The Pager helps users navigate between multiple pages
102
+ - [Steps](navigation/steps.md): Decompose complex tasks or tasks with prior relationships, use step components to guide users to operate according to the prescribed process, and let them know their current progress
103
+ - [Tabs](navigation/tabs.md): When the content needs to be grouped and displayed in different modules or pages, you could use Tabs to switch between different groups or pages
104
+ - [Tree](navigation/tree.md): A tree view component presents a hierarchical list.
105
+
106
+ ## Show
107
+
108
+ - [Avatar](show/avatar.md): Avatar, used for image or text display.
109
+ - [Badge](show/badge.md): Badge generates a small badge to give users tips.
110
+ - [Calendar](show/calendar.md): Calendar component that allows to display corresponding events in day/week/month view
111
+ - [Card](show/card.md): Card container can consist of titles, paragraphs, pictures, lists, and other content.
112
+ - [Carousel](show/carousel.md): Carousel is a media component that can display the effect of playing multiple pictures in turn in a visualization application.
113
+ - [Collapse](show/collapse.md): Display content areas can be expanded or folded.
114
+ - [Collapsible](show/collapsible.md): The collapsible component is a container component used to put long sections of information under a block that can be expanded or collapsed.
115
+ - [Description](show/descriptions.md): The description list is used to render key-value pairs.
116
+ - [Dropdown](show/dropdown.md): A menu that pops down.
117
+ - [Empty](show/empty.md): Placeholder component when the page is empty.
118
+ - [Highlight](show/highlight.md): highlight specific content
119
+ - [Image](show/image.md): Used to display and preview images.
120
+ - [Cropper](show/cropper.md): Freely crop pictures
121
+ - [List](show/list.md): Lists display a set of related contents
122
+ - [Modal](show/modal.md): Modals are used to wait for the user to interact, inform the user of important information, or display more information without losing context.
123
+ - [OverflowList](show/overflow-list.md): OverflowList is a behavior component used to take list of items and display as many items as can fit inside itself. Overflowed items that do not fit are collected and rendered by callback function. The visible items will be recomputed when a resize is detected.
124
+ - [Popover](show/popover.md): Click / mouse to move into the element and pop up the bubble card floating layer.
125
+ - [ScrollList](show/scroll-list.md): Scroll through the list.
126
+ - [SideSheet](show/side-sheet.md): An overlay panel that slides out from the edge of the screen, typically used to host secondary action pages.
127
+ - [Table](show/table.md): Tables are used to present structured data content, usually accompanied by the ability to manipulate the data (sort, search, paginate...).
128
+ - [Tag](show/tag.md): Tag component is used to display a collection of concise information for rapid identification and grouping.
129
+ - [Timeline](show/timeline.md): Timeline component is used to display a series of information vertically.
130
+ - [Tooltip](show/tooltip.md): Tooltip is used to identify an element or attach a small amount of auxiliary information. The most typical scenario is to explain the meaning of the icon to the user, display the truncated text, display the description of the picture, and so on.
131
+ - [UserGuide](show/user-guide.md): Used to guide new users through pages
132
+
133
+ ## Feedback
134
+
135
+ - [Banner](feedback/banner.md): The Banner component is usually used to identify the status or notification of the full page. It is usually resident and requires the user to close it initiatively.
136
+ - [Notification](feedback/notification.md): Notifications are used to actively send message notifications to users.
137
+ - [Feedback](feedback/feedback.md): Quick feedback component
138
+ - [Popconfirm](feedback/popconfirm.md): Used when the operation of the target element requires further confirmation from the user. Compared with Popover, it has a built-in series of configurable action buttons. Compared with Modal, it does not force full-screen centering, and the interaction is lighter.
139
+ - [Progress](feedback/progress.md): Used to display the current progress and status of the user operation, and is generally used when the operation takes a long time. Can also be used to indicate the degree of completion of a task/object
140
+ - [Skeleton](feedback/skeleton.md): A placeholder preview of content before the data loaded.
141
+ - [Spin](feedback/spin.md): Spin is used to inform the user that the content is loading and may take an uncertain period of time.
142
+ - [Toast](feedback/toast.md): Toast component is used to give timely feedback to user's operations. It could be the result feedback of the operation, such as success, failure, error, warning, etc.
143
+
144
+ ## Other
145
+
146
+ - [ConfigProvider](other/config-provider.md): Provide a unified global configuration for components.
147
+ - [LocaleProvider](other/locale.md): Internationalized components to provide multilingual support for Semi components
@@ -0,0 +1,377 @@
1
+ # Anchor
2
+
3
+ > The Anchor component is used to create a hyper Link navigation bar.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/navigation/anchor/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { Anchor } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ There is no `Anchor.Link`; pass the links through the `links` data prop.
18
+
19
+ ### Basic Usage
20
+
21
+ Use `Link` to create an anchor, click it to jump to the hash tag location.
22
+
23
+ Write the links as a `links` array of `{ href, title, disabled, children }`, where `children` nests the next level; use the `title` snippet, with the parameter `{ item, level }`, for custom titles.
24
+
25
+ ```svelte
26
+ <script lang="ts">
27
+ import { Anchor } from '@fibrae/semi-ui-svelte';
28
+
29
+ const links = [
30
+ { href: '#基本示例', title: '基本示例' },
31
+ { href: '#组件', title: '组件' },
32
+ { href: '#设计语言', title: '设计语言' },
33
+ { href: '#物料平台', title: '物料平台' },
34
+ { href: '#主题商店', title: '主题商店' },
35
+ ];
36
+ </script>
37
+
38
+ <Anchor {links} />
39
+ ```
40
+
41
+ ### Integrated Usage
42
+
43
+ You can use `getContainer`, `targetOffset`, `offsetTop`, and `style` to create a out of the box hyperAnchor.Link navigation bar.
44
+
45
+ - getContainer:you can set the container of scroll content with `getContainer` property. Its default value is `window`.
46
+
47
+ - targetOffset: you can set the distance between the anchor point and the top of the container by setting `targetOffset`.
48
+
49
+ - style:Anchor does not position itself. Position it yourself with the `style` object, for example `position: fixed`.
50
+
51
+ - offsetTop:`offsetTop` can trigger the current Link switch when the scrolling content reaches a specified offset from the top of the container.
52
+
53
+ ```svelte
54
+ <script lang="ts">
55
+ import { Anchor } from '@fibrae/semi-ui-svelte';
56
+
57
+ const links = [
58
+ { href: '#Basic_Usage', title: 'Fixed Anchor' },
59
+ { href: '#Integrated_Usage', title: 'Integrated Usage' },
60
+ { href: '#Size', title: 'Size' },
61
+ { href: '#Rail_Theme', title: 'Rail Theme' },
62
+ { href: '#Auto_Collapse', title: 'Auto Collapse' },
63
+ { href: '#Show_Tooltip', title: 'Show Tooltip' },
64
+ { href: '#Tooltip_Position', title: 'Tooltip Position' },
65
+ {
66
+ href: '#API_Reference',
67
+ title: 'API Reference',
68
+ children: [
69
+ { href: '#Anchor', title: 'Anchor' },
70
+ { href: '#Anchor.Link', title: 'Anchor.Link' },
71
+ ],
72
+ },
73
+ ];
74
+ </script>
75
+
76
+ <span>See the fixed Anchor on the right </span>
77
+ <Anchor {links} offsetTop={100} style="position: fixed; right: 20px; top: 100px; width: 200px; z-index: 3" targetOffset={100} />
78
+ ```
79
+
80
+ ### Size
81
+
82
+ You can change Anchor size with `size` property.
83
+
84
+ ```svelte
85
+ <script lang="ts">
86
+ import { Anchor } from '@fibrae/semi-ui-svelte';
87
+
88
+ const links = [
89
+ { href: '#组件', title: '组件' },
90
+ { href: '#设计语言', title: '设计语言' },
91
+ { href: '#物料平台', title: '物料平台' },
92
+ { href: '#主题商店', title: '主题商店' },
93
+ ];
94
+ </script>
95
+
96
+ <Anchor {links} size="default" />
97
+ ```
98
+
99
+ ```svelte
100
+ <script lang="ts">
101
+ import { Anchor } from '@fibrae/semi-ui-svelte';
102
+
103
+ const links = [
104
+ { href: '#组件', title: '组件' },
105
+ { href: '#设计语言', title: '设计语言' },
106
+ { href: '#物料平台', title: '物料平台' },
107
+ { href: '#主题商店', title: '主题商店' },
108
+ ];
109
+ </script>
110
+
111
+ <Anchor {links} size="small" />
112
+ ```
113
+
114
+ ### Rail Theme
115
+
116
+ You can change rail color with `railTheme` property. Three themes are supported and the default value is `primary`.
117
+
118
+ ```svelte
119
+ <script lang="ts">
120
+ import { Anchor } from '@fibrae/semi-ui-svelte';
121
+
122
+ const links = [
123
+ { href: '#尺寸', title: '尺寸' },
124
+ { href: '#滑轨主题', title: '滑轨主题' },
125
+ { href: '#设计语言', title: '设计语言' },
126
+ { href: '#物料平台', title: '物料平台' },
127
+ { href: '#主题商店', title: '主题商店' },
128
+ ];
129
+ </script>
130
+
131
+ <div>
132
+ <Anchor {links} offsetTop={100} railTheme="primary" targetOffset={60} />
133
+ </div>
134
+ ```
135
+
136
+ ```svelte
137
+ <script lang="ts">
138
+ import { Anchor } from '@fibrae/semi-ui-svelte';
139
+
140
+ const links = [
141
+ { href: '#尺寸', title: '尺寸' },
142
+ { href: '#滑轨主题', title: '滑轨主题' },
143
+ { href: '#设计语言', title: '设计语言' },
144
+ { href: '#物料平台', title: '物料平台' },
145
+ { href: '#主题商店', title: '主题商店' },
146
+ ];
147
+ </script>
148
+
149
+ <div>
150
+ <Anchor {links} offsetTop={100} railTheme="tertiary" targetOffset={60} />
151
+ </div>
152
+ ```
153
+
154
+ ```svelte
155
+ <script lang="ts">
156
+ import { Anchor } from '@fibrae/semi-ui-svelte';
157
+
158
+ const links = [
159
+ { href: '#尺寸', title: '尺寸' },
160
+ { href: '#滑轨主题', title: '滑轨主题' },
161
+ { href: '#设计语言', title: '设计语言' },
162
+ { href: '#物料平台', title: '物料平台' },
163
+ { href: '#主题商店', title: '主题商店' },
164
+ ];
165
+ </script>
166
+
167
+ <div>
168
+ <Anchor {links} offsetTop={100} railTheme="muted" targetOffset={60} />
169
+ </div>
170
+ ```
171
+
172
+ ### Auto Collapse
173
+
174
+ Anchor can dynamically display child links with `autoCollapse` property. The default is `false`.
175
+
176
+ ```svelte
177
+ <script lang="ts">
178
+ import { Anchor } from '@fibrae/semi-ui-svelte';
179
+
180
+ const links = [
181
+ {
182
+ href: '#动态展示',
183
+ title: '1. 动态展示',
184
+ children: [
185
+ {
186
+ href: '#组件',
187
+ title: '1.1 组件',
188
+ children: [
189
+ { href: '#头像', title: '1.1.1 Avatar' },
190
+ { href: '#按钮', title: '1.1.2 Button' },
191
+ { href: '#图标', title: '1.1.3 Icon' },
192
+ ],
193
+ },
194
+ { href: '#物料', title: '1.2 物料' },
195
+ { href: '#主题商店', title: '1.3 主题商店' },
196
+ ],
197
+ },
198
+ { href: '#设计语言', title: '2. 设计语言' },
199
+ ];
200
+ </script>
201
+
202
+ <div>
203
+ <Anchor autoCollapse {links} offsetTop={100} targetOffset={60} />
204
+ </div>
205
+ ```
206
+
207
+ ```svelte
208
+ <script lang="ts">
209
+ import { Anchor } from '@fibrae/semi-ui-svelte';
210
+
211
+ const links = [
212
+ {
213
+ href: '#动态展示',
214
+ title: '1. 动态展示',
215
+ children: [
216
+ {
217
+ href: '#组件',
218
+ title: '1.1 组件',
219
+ children: [
220
+ { href: '#头像', title: '1.1.1 Avatar' },
221
+ { href: '#按钮', title: '1.1.2 Button' },
222
+ { href: '#图标', title: '1.1.3 Icon' },
223
+ ],
224
+ },
225
+ { href: '#物料', title: '1.2 物料' },
226
+ { href: '#主题商店', title: '1.3 主题商店' },
227
+ ],
228
+ },
229
+ { href: '#设计语言', title: '2. 设计语言' },
230
+ ];
231
+ </script>
232
+
233
+ <div>
234
+ <Anchor autoCollapse={false} {links} offsetTop={100} targetOffset={60} />
235
+ </div>
236
+ ```
237
+
238
+ ### Show Tooltip
239
+
240
+ `showTooltip` can display the title of link when it exceeds the max-width. The default value is `false`.
241
+
242
+ ```svelte
243
+ <script lang="ts">
244
+ import { Anchor } from '@fibrae/semi-ui-svelte';
245
+
246
+ const links = [
247
+ { href: '#显示工具提示', title: '工具提示是一个有用的工具,它可以在文字缩略时展示全部内容。' },
248
+ { href: '#组件', title: '组件' },
249
+ { href: '#设计语言', title: '设计语言' },
250
+ { href: '#物料平台', title: '物料平台' },
251
+ { href: '#主题商店', title: '主题商店' },
252
+ ];
253
+ </script>
254
+
255
+ <div>
256
+ <Anchor {links} offsetTop={100} showTooltip targetOffset={60} />
257
+ </div>
258
+ ```
259
+
260
+ ### Tooltip Position
261
+
262
+ You can change the Tooltip position with `position` property. It only works when `showTooltip` is `true`.
263
+
264
+ ```svelte
265
+ <script lang="ts">
266
+ import { Anchor } from '@fibrae/semi-ui-svelte';
267
+
268
+ const links = [
269
+ { href: '#工具提示位置', title: '工具提示是一个有用的工具,它可以在文字缩略时展示全部内容。' },
270
+ { href: '#组件', title: '组件' },
271
+ { href: '#设计语言', title: '设计语言' },
272
+ { href: '#物料平台', title: '物料平台' },
273
+ { href: '#主题商店', title: '主题商店' },
274
+ ];
275
+ </script>
276
+
277
+ <div>
278
+ <Anchor {links} offsetTop={100} position="right" showTooltip targetOffset={60} />
279
+ </div>
280
+ ```
281
+
282
+ ### Custom Scroll Position
283
+
284
+ `scrollIntoViewOptions` adjusts where the target ends up in the container after a link is clicked. Its type is the `Options` of [scroll-into-view-if-needed](https://github.com/scroll-into-view/scroll-into-view-if-needed): `block`, `inline`, `scrollMode`, `boundary` and `skipOverflowHiddenElements`. Without it `block` is `start`, which scrolls the target to the top of the container.
285
+
286
+ - `scrollMotion` still decides whether the scroll is animated (`behavior`), and `targetOffset` still shifts the position `block` produces, when passed together with `scrollIntoViewOptions`.
287
+ - Only the innermost vertically scrollable container is scrolled; the horizontal position is adjusted only when `inline` is passed.
288
+
289
+ ```svelte
290
+ <script lang="ts">
291
+ import { Anchor } from '@fibrae/semi-ui-svelte';
292
+
293
+ const sections = ['section-a', 'section-b', 'section-c'];
294
+ const links = sections.map((id, index) => ({ href: `#${id}`, title: `章节 ${index + 1}` }));
295
+ const getContainer = () => document.getElementById('scroll-box');
296
+ </script>
297
+
298
+ <div style="display: flex; gap: 24px">
299
+ <Anchor {getContainer} {links} scrollIntoViewOptions={{ block: 'center' }} scrollMotion style="width: 160px" />
300
+ <!-- Focusable so the keyboard can scroll this container -->
301
+ <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
302
+ <section aria-label="章节" id="scroll-box" style="height: 240px; width: 320px; overflow: auto; border: 1px solid #ddd" tabindex="0">
303
+ {#each sections as id, index (id)}
304
+ <div {id} style="height: 200px; padding: 8px">点击链接后,章节 {index + 1} 会滚动到容器中间</div>
305
+ {/each}
306
+ </section>
307
+ </div>
308
+ ```
309
+
310
+ ## API Reference
311
+
312
+ ### Anchor
313
+
314
+ **Props**
315
+
316
+ | Property | Description | Type | Default |
317
+ | - | - | - | - |
318
+ | autoCollapse | Whether the next level of links is shown dynamically while scrolling. | `boolean` | `false` |
319
+ | defaultAnchor | Link highlighted by default. | `string` | `""` |
320
+ | getContainer | Returns the scrolling container, window when omitted. | `() => HTMLElement \| Window \| null` | - |
321
+ | links | Link data. Each item is `{ href, title, disabled, children }`, and `children` nests the next level. An `href` starting with # is looked up by element id, anything else as a CSS selector; `title` is the plain-text title, also the native title when showTooltip is off; a `disabled` link ignores clicks. | `AnchorLinkItem[]` | `[]` |
322
+ | maxHeight | max-height of the component, with a scrollbar when exceeded. A max-height in style wins. | `string \| number` | `"750px"` |
323
+ | maxWidth | max-width of the component, truncating when exceeded. A max-width in style wins. | `string \| number` | `"200px"` |
324
+ | offsetTop | Offset from the top of the container at which the current link switches while content scrolls. | `number` | `0` |
325
+ | onChange | Called when the highlighted link changes, with the current and the previous link. | `(currentLink: string, previousLink: string) => void` | - |
326
+ | onClick | Called when a link is clicked or activated with Enter, with the native MouseEvent or KeyboardEvent and the current link. Only called when a link is activated, not for a click elsewhere on the root. | `(event: AnchorClickEvent, currentLink: string) => void` | - |
327
+ | position | Position of the Tooltip when showTooltip is on, with the same values as the Tooltip position. | `Position` | - |
328
+ | railTheme | Theme of the rail: primary, tertiary or muted. | `'muted' \| 'primary' \| 'tertiary'` | `"primary"` |
329
+ | scrollIntoViewOptions | Options passed to scroll-into-view-if-needed when a link is clicked, combined with scrollMotion and targetOffset. | `ScrollIntoViewOptions` | - |
330
+ | scrollMotion | Whether scrolling after a click is animated. | `boolean` | `false` |
331
+ | showTooltip | Whether a Tooltip shows when the text is truncated, with its options: type is the popup component, tooltip (default) or popover, and opts are passed to it. | `boolean \| ShowTooltip` | `false` |
332
+ | size | Size of the anchor: small or default. | `'default' \| 'small'` | `"default"` |
333
+ | targetOffset | Distance between the target and the top of the container when scrolling ends. | `number` | `0` |
334
+ | title | Snippet that renders every link's title, with the parameter `{ item, level }`; `level` is the nesting depth, 1 at the top. It takes precedence over `title` in `links`. | `Snippet<[AnchorTitleContext]>` | - |
335
+
336
+ `class`, `style` (a string) and native attributes (such as `data-*` and `aria-*`) land on the root element (`role="navigation"`); the `max-width` and `max-height` in `style` win over `maxWidth` and `maxHeight`. `onClick` and `onChange` are component callbacks, and `onClick` is only called when a link is activated. The first server-rendered frame carries all links, and the `autoCollapse` folding is correct from the first frame; an item without child links renders no empty `role="list"`.
337
+
338
+ ### Anchor.Link
339
+
340
+ Svelte has no separate `Anchor.Link` component; each link is an item of the `links` data, with the fields described for `links` above.
341
+
342
+ ## Content Guidelines
343
+
344
+ - Write in sentence case
345
+ - Keep it concise and avoid line breaks
346
+
347
+ ## Design Tokens
348
+
349
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/navigation/anchor/>
350
+
351
+ ## FAQ
352
+
353
+ 1. **Why didn't my link highlight and slide to follow?**\
354
+ Check whether you can scroll to the specified position by clicking the anchor:
355
+ - No, it means there is a problem with the id. check whether the id exists in the document;
356
+ - Yes, it may be that the scrolling container is not set correctly to ensure that the content of the document is wrapped in the scrolling container. The default scrolling container is window. If your container is a div of .my-container, you should set the scrolling container to this div.
357
+
358
+ ```text
359
+ <script lang="ts">
360
+ import { Anchor } from '@fibrae/semi-ui-svelte';
361
+
362
+ // This is the container of the document content, not of Anchor: the current id is computed against it
363
+ const getContainer = () => document.querySelector<HTMLElement>('.my-container');
364
+ </script>
365
+
366
+ <Anchor {getContainer} {links} />
367
+ ```
368
+
369
+ ## Changes from Semi Design
370
+
371
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
372
+
373
+ - 破坏性:根元素不再自动生成 `id="semi-anchor-xxx"`,改用 `.semi-anchor` 选择;滑轨与链接列表包在新容器 `.semi-anchor-rail-wrapper` 中,`.semi-anchor` 不再是 `position: relative`;`LinkProps` 删除无效的 `level`、`direction`;`onClick` 事件参数改为 `React.MouseEvent | React.KeyboardEvent`;删除 `strings.POSITION_SET`,改用 Tooltip 的 `POSITION_SET`。
374
+ - Link 只响应 Enter 激活;以 `#` 开头的 `href` 按元素 id 查找而非 CSS 选择器;当前链接带 `aria-current="location"`(原 `aria-details="active"`);新增 `scrollIntoViewOptions`;无激活链接时 `onChange` 收到 `''`(原 `undefined`);`defaultAnchor` 只在首次挂载时应用,React `<Activity>` 重新显示时不再跳回它。
375
+ - `autoCollapse` 下一次滚动跳进未展开的分支时,分支展开后再选一次高亮,落到其中的子链接,不停在父项(React、Vue、Solid;Svelte 本来如此)。React、Vue:Link 经 context 登记所在的父链接,经其他组件渲染的 Link(含 Anchor 的直接子组件渲染出的整组链接)同样让父项保持展开;React 的 `defaultAnchor` 指向这类 Link 下直接嵌套的折叠子项时也能展开。
376
+ - Svelte 破坏性:不提供 `Anchor.Link`,链接用数据 prop `links`(`{ href?, title?, disabled?, children? }[]`,`children` 嵌套),自定义标题用 `title` snippet(参数 `{ item, level }`);服务端首帧带全部链接,`autoCollapse` 的折叠首帧即正确;`onChange`、`onClick` 是函数 prop,`onClick` 只在激活链接时触发;没有子链接的项不输出空的 `role="list"`。
377
+ - Svelte:`getContainer` 只在挂载时以及它读取的 `$state` 变化时重新求值;容器晚于挂载出现时,让它读取一个随容器出现而变化的 `$state`(同 Solid)。
@@ -0,0 +1,100 @@
1
+ # BackTop
2
+
3
+ > BackTop lets users return to the top of a long page with one click.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/navigation/backtop/
6
+
7
+ ## Demos
8
+
9
+ ### How to import
10
+
11
+ ```svelte
12
+ <script lang="ts">
13
+ import { BackTop } from '@fibrae/semi-ui-svelte';
14
+ </script>
15
+ ```
16
+
17
+ ### Basic Usage
18
+
19
+ BackTop is a [FloatButton](../basic/float-button.md) that appears once `target` scrolls past `visibilityHeight` and scrolls it back to the top when clicked. It shows a back-to-top icon by default, and its accessible name comes from the locale by default ('Back to top' in English), which `aria-label` can override.
20
+
21
+ ```svelte
22
+ <script lang="ts">
23
+ import { BackTop } from '@fibrae/semi-ui-svelte';
24
+ </script>
25
+
26
+ <div>
27
+ <span>Scroll down to see the bottom-right gray button.</span>
28
+ <BackTop aria-label="Back to top" />
29
+ </div>
30
+ ```
31
+
32
+ ### Customized Style
33
+
34
+ BackTop sits 50px from the bottom and 100px from the right (the left in RTL) by default, which `style` can override.
35
+
36
+ Its look is customized with the `icon` snippet and the FloatButton props `shape`, `size`, `colorful` and `badge`; `style` only accepts a string.
37
+
38
+ ```svelte
39
+ <script lang="ts">
40
+ import { IconArrowUp } from '@fibrae/semi-icons-svelte';
41
+ import { BackTop } from '@fibrae/semi-ui-svelte';
42
+ </script>
43
+
44
+ <div>
45
+ <span>向下滚动,右下角会出现一个方形的多彩按钮。</span>
46
+ <BackTop aria-label="回到顶部" colorful shape="square" size="large" style="bottom: 100px">
47
+ {#snippet icon()}
48
+ <IconArrowUp />
49
+ {/snippet}
50
+ </BackTop>
51
+ </div>
52
+ ```
53
+
54
+ ## API Reference
55
+
56
+ **Props**
57
+
58
+ | Property | Description | Type | Default |
59
+ | - | - | - | - |
60
+ | badge | Badge props, same as FloatButton. | `FloatButtonBadge` | - |
61
+ | badgeCount | Snippet for custom badge content, in place of badge.count. | `Snippet` | - |
62
+ | children | Static content of the button, shown in place of the icon. Must not contain interactive elements. | `Snippet` | - |
63
+ | colorful | Colorful button, same as FloatButton. Falls back to the FloatButton default when unset. | `boolean` | - |
64
+ | duration | Milliseconds the scroll to the top takes. `onclick` is throttled by this interval. | `number` | `450` |
65
+ | icon | Snippet for the button icon. Defaults to IconBackTop. | `Snippet` | - |
66
+ | onclick | Called on click with the native click event. Throttled by duration, and called once the scroll has started. | `MouseEventHandler<T> \| null` | - |
67
+ | shape | Shape: round or square. Falls back to the FloatButton default when unset. | `FloatButtonShape` | - |
68
+ | size | Size: default, small or large. Falls back to the FloatButton default when unset. | `FloatButtonSize` | - |
69
+ | target | Function returning the scrolled element, the window when unset. Returning null means the node is not available yet. Called on mount and again when the function itself changes. | `() => Window \| HTMLElement \| null` | - |
70
+ | visibilityHeight | Scroll distance after which the BackTop appears. | `number` | `400` |
71
+
72
+ `class`, `style` (a string) and native attributes (such as `data-*` and `aria-*`) land on the button. The click callback is the native `onclick`, throttled by `duration`, and `overrideDefaultProps.BackTop` cannot set it. `children`, `icon` and `badgeCount` are snippets.
73
+
74
+ `target` is called once after mount, when the element reference of a parent container is already readable; a stable `target` function that returns the element only after mount needs BackTop remounted.
75
+
76
+ ## Accessibility
77
+
78
+ ### ARIA
79
+
80
+ - BackTop renders a single native `<button type="button">`, which screen readers announce as a button
81
+ - The accessible name comes from `aria-label`; without it, it comes from the button content when content is passed, and otherwise from the locale's default name ('Back to top' in English)
82
+ - `children` (the default slot in Vue, a snippet in Svelte) is static content of the button and becomes part of its name; the button must not contain interactive elements
83
+
84
+ ### Keyboard and focus
85
+
86
+ - Once visible, the button is reached with Tab and Shift + Tab, and Enter or Space scrolls to the top
87
+ - A focus outline is shown on keyboard focus
88
+
89
+ ## Design Tokens
90
+
91
+ The design token table of this component is on the web page: <https://semi-design-next.pages.dev/en-US/svelte/navigation/backtop/>
92
+
93
+ ## Changes from Semi Design
94
+
95
+ From the project release notes (written in Chinese). Your knowledge of Semi Design does not cover these.
96
+
97
+ - 破坏性(类型):`BackTopProps` 收窄为实际接受的属性,不再含按钮的 `type` 与 `form*`;`target` 类型为 `() => Window | HTMLElement | null`;`ref` 指向 `HTMLButtonElement`。
98
+ - 破坏性:基于 FloatButton 渲染为原生 `<button>`,新增 `icon`、`shape`、`size`、`colorful`、`badge`;`<BackTop><IconArrowUp /></BackTop>` 改为 `<BackTop icon={<IconArrowUp />} />`,宽高、圆角、背景色改用 `shape`、`size`、`colorful`,`.semi-backtop > .semi-button` 选择器改为 `button.semi-backtop`,覆盖定位需 `.semi-floatButton.semi-backtop` 的权重。Vue:`onClick` 改为 `click` 事件(经 `duration` 节流),`children` 为默认插槽,`icon` 为 `#icon`,`badge.count` 节点用 `#badgeCount`;`overrideDefaultProps.BackTop` 不能设置 `click`。
99
+ - Svelte:BackTop 的 `onClick` 改为 `onclick`(经 `duration` 节流);`children` 是静态内容的 snippet,`icon`、`badgeCount` 是 snippet;`overrideDefaultProps.BackTop` 不能设置 `onclick`。
100
+ - 点击按 `duration` 节流,窗口内多次点击合并为一次 trailing 调用;`duration` 在点击间变化时,旧窗口内待补的那次点击不再触发。