@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,105 @@
1
+ # Changes from Semi Design
2
+
3
+ > Breaking and behavior changes that apply to every component, from the project release notes (written in Chinese). Component-specific changes are at the end of each component page.
4
+
5
+ ## 全局
6
+
7
+ - 支持 Chrome 120、Firefox 125、Safari 17.2 及以上(D15)。支持 Safari 17.4 以下时,在应用入口最先 `import '@fibrae/semi-polyfill'`,它只补齐 `AbortSignal.any` 与 `Element.prototype.checkVisibility`。
8
+ - 破坏性:React 包支持 React 19,Vue 包支持 Vue 3.5+。React 组件都是函数组件,ref 不再是类实例:有命令式方法的组件经 `XxxHandle` 暴露(如 `SelectHandle`、`DatePickerHandle`、`FormHandle`),其余指向根 DOM。删除 `BaseComponent` 导出与组件的 `propTypes` 静态属性。
9
+ - 破坏性:包名 `@fibrae/semi-ui` 改为 `@fibrae/semi-ui-react`,`@fibrae/semi-ai` 改为 `@fibrae/semi-ai-react`,`@fibrae/semi-illustrations` 改为 `@fibrae/semi-icons-react/illustrations`;`@fibrae/semi-foundation`、`@fibrae/semi-ai-foundation` 不变,类名不变。
10
+ - 破坏性:插画并入图标包(D17),不再发布 `@fibrae/semi-illustrations-{react,vue,solid,svelte}`。`@fibrae/semi-illustrations-<框架>` 改为 `@fibrae/semi-icons-<框架>/illustrations`,单个插画的深路径改为 `@fibrae/semi-icons-<框架>/illustrations/illustration-<name>`,导出名不变;依赖中删除插画包。
11
+ - 破坏性:图标包 `@fibrae/semi-icons` 改为 `@fibrae/semi-icons-react`,如 `@fibrae/semi-icons/lab` 改为 `@fibrae/semi-icons-react/lab`,`@fibrae/semi-icons/styles/icons.scss` 改为 `@fibrae/semi-icons-core/styles/icons.scss`。新增 `@fibrae/semi-icons-core`,放图标与插画的框架无关数据(`@fibrae/semi-icons-core/lab`、`@fibrae/semi-icons-core/illustrations`,单个插画的深路径为 `@fibrae/semi-icons-core/illustrations/illustration-<name>`),semi-icons-react 已依赖它。semi-icons-react 的深路径 `components/Icon`、`components/createIcon` 改为 `components/icon`、`components/create-icon`。
12
+ - 破坏性:AI 组件拆为独立包(D9):AIChatInput、AIChatDialogue、Chat、Sidebar、Annotation、MCPConfigure 与 `getConfigureItem`、`chatCompletionToMessage` 等改从 `@fibrae/semi-ai-react` 导入。深路径 `@fibrae/semi-ui-react/{ai-chat-input,ai-chat-dialogue,chat,sidebar}/...` 改为 `@fibrae/semi-ai-react/...`,`@fibrae/semi-foundation/{同上}/...` 改为 `@fibrae/semi-ai-foundation/...`。
13
+ - 破坏性:`@fibrae/semi-ui-react/styles.css` 不含 AI 样式,整包加载时在其后引入 `@fibrae/semi-ai-react/styles.css`(自定义前缀用 `semi-build-scss --ai <semi-ai-foundation>`);`OverrideDefaultProps` 引入 AI 包后才含 AI 组件名。新增对应的 `@fibrae/semi-ai-vue`、`@fibrae/semi-ai-solid`、`@fibrae/semi-ai-svelte`,样式在对应 UI 包的 `styles.css` 之后引入各自的 `styles.css`(如 `@fibrae/semi-ui-vue/styles.css` 之后引入 `@fibrae/semi-ai-vue/styles.css`)。
14
+ - 破坏性:目录与文件名统一为 kebab-case(D4):`@fibrae/semi-ui-react/iconButton/index` 改为 `@fibrae/semi-ui-react/icon-button/index`,`@fibrae/semi-foundation/datePicker/datePicker.scss` 改为 `@fibrae/semi-foundation/date-picker/date-picker.scss`,`@fibrae/semi-ui-react/table/Table` 改为 `@fibrae/semi-ui-react/table/table`;单个图标与插画的深路径改为导出名的 kebab-case,如 `@fibrae/semi-icons-react/icons/IconHome` 改为 `@fibrae/semi-icons-react/icons/icon-home`、`@fibrae/semi-icons-react/illustrations/IllustrationNoContent` 改为 `@fibrae/semi-icons-react/illustrations/illustration-no-content`;`@fibrae/semi-animation/styles/viewTransition.css` 改为 `@fibrae/semi-animation/styles/view-transition.css`。导出名、类名(含 `semi-icon-<SVG 文件名>`)、Sass 变量名与语言包文件名不变。文档站页面路径同样改为 kebab-case,如 `/input/datepicker` 改为 `/input/date-picker`。
15
+ - 破坏性(深路径):四个框架的 UI 包与 AI 包按 D18 整理组件目录:入口组件是与目录同名的文件,`index` 只做导出,`<组件>/index` 深路径不变;有两个及以上 hook 的组件把 hook 放进 `hooks/`(Vue 为 `composables/`,Solid 为 `primitives/`);多个文件组成的部分放进以该部分命名的子目录,如 `@fibrae/semi-ui-vue/form/composables/use-form-api`、`@fibrae/semi-ui-solid/table/table-header/head-table`、`@fibrae/semi-ui-svelte/form/fields/form-input.svelte`、`@fibrae/semi-ui-svelte/image/preview/preview.svelte`。semi-ui-react:`button/button` 改为完整的 Button,原不带 icon 的基础渲染器改为 `button/base-button`;`table/table` 改为 Table 入口,原表格主体改为 `table/normal-table`,`table/body/index` 改为 `table/body/body`,`table/{table-header,table-header-row,head-table,resizable-header-cell}` 改为 `table/table-header/<名>`;`image/preview`、`image/preview-*` 改为 `image/preview/<名>`;`calendar/use-*` 改为 `calendar/hooks/use-*`;`form/base-form` 改为 `form/form`,`form/hoc/with-*` 改为 `form/with-*`,SchemaForm 与 SchemaField 在 `form/schema-form/` 下;Toast、Notification 的命令式入口为 `toast/static-api`、`notification/static-api`;`color-picker/{alpha-slider,color-choose-area,color-slider,data-part}/index` 改为 `color-picker/<名>`;`resizable/group/resize-context` 改为 `resizable/context`,`resizable/group/<名>`、`resizable/single/<名>` 改为 `resizable/<名>`;`toast/use-toast/index`、`modal/use-modal/index`、`notification/use-notification/index` 改为 `toast/use-toast`、`modal/use-modal`、`notification/use-notification`,`modal/use-modal/hook-modal` 删除(`HookModalRef` 改从 `modal/use-modal` 导入,`HookModal` 组件不再导出)。semi-ai-react:`chat/chat-box/index` 改为 `chat/chat-box/chat-box`,`chat/input-box/index` 改为 `chat/input-box`,`ai-chat-input/extension/<名>-slot/index` 改为 `ai-chat-input/extension/<名>-slot`,`ai-chat-input/extension/input-slot/component` 改为 `ai-chat-input/extension/input-slot-component`。
16
+ - 破坏性(深路径):`@fibrae/semi-foundation` 的组件目录移到 `components/` 下,如 `@fibrae/semi-foundation/button/button.scss` 改为 `@fibrae/semi-foundation/components/button/button.scss`,`@fibrae/semi-foundation/table/foundation` 改为 `@fibrae/semi-foundation/components/table/foundation`,`_portal/portal.scss` 改为 `components/portal/portal.scss`。`utils/` 中的 `popup-lifecycle`、`modal-resources`、`focus-scope`、`focus-handle`、`reset-timer`、`release-holder` 移到 `base/`。`base/`、`utils/`、`locale/`、`theme/` 下的其余路径不变。`@fibrae/semi-ai-foundation` 同样把组件目录移到 `components/`(如 `chat/foundation` 改为 `components/chat/foundation`),`message-list-foundation`、`action-bar-foundation` 改为 `base/message-list-foundation`、`base/action-bar-foundation`,`file-suffix`、`upload-status` 改为 `utils/file-suffix`、`utils/upload-status`。
17
+ - 破坏性(深路径):各框架的 UI 包与 AI 包把源码分为 `components/`、`base/`、`utils/`、`internal/` 与通用 hook 目录(React、Svelte 为 `hooks/`,Vue 为 `composables/`,Solid 为 `primitives/`)。组件深路径不变(如 `@fibrae/semi-ui-react/button/index`),`_base/*`、`_utils/*`、`_portal`、`_sortable`、`_css-animation` 子路径删除:适配层改为 `base/*`(如 `@fibrae/semi-ui-svelte/base/create-context`),通用 hook 改为对应目录(如 `@fibrae/semi-ui-svelte/hooks/watch.svelte.js`),无状态工具与 `semi-global` 改为 `utils/*`,AI 包根目录的 `semi-global` 同样改为 `utils/semi-global`。`internal/*` 是 AI 包使用的内部组件,不属于公开 API。Vue 的 hooks 入口改名为 `@fibrae/semi-ui-vue/composables`,Solid 的改名为 `@fibrae/semi-ui-solid/primitives`;React、Svelte 仍为 `/hooks`。semi-ui-react 的 context 模块统一命名为 `context`:`anchor/anchor-context`、`breadcrumb/bread-context`、`collapse/collapse-context`、`descriptions/descriptions-context`、`image/preview-context`、`layout/layout-context`、`list/list-context`、`navigation/nav-context`、`table/table-context`、`tabs/tabs-context`、`tree/tree-context` 改为 `<组件>/context`,`markdown-render/components/link-context` 改为 `markdown-render/context`。四个 AI 包的 Chat、AIChatDialogue、AIChatInput、Sidebar 的子组件放在组件目录根部,合起来组成一个部分的放进以该部分命名的子目录,深路径随之变化:如 `@fibrae/semi-ai-react/chat/chat-box/chat-box`、`@fibrae/semi-ai-svelte/ai-chat-dialogue/dialogue/dialogue-title.svelte`、`@fibrae/semi-ai-vue/ai-chat-input/rich-text-input`、`@fibrae/semi-ai-solid/sidebar/container`,Sidebar 原 `widget/<名>` 下的子组件改为 `sidebar/<名>`(如 `sidebar/options`)。入口深路径 `<组件>/index`(如 `@fibrae/semi-ai-react/chat/index`)不变。
18
+ - 破坏性(深路径):`@fibrae/semi-ai-foundation/utils/upload-status` 删除,`isUploadFailed`、`isUploadProgressVisible` 改从 `@fibrae/semi-foundation/components/upload/utils` 导入;`ignoreExpectedMediaErrors` 从 `components/video-player/utils` 移到 `@fibrae/semi-foundation/utils`(`utils/media`);`isValidDate` 从 `components/date-picker/_utils` 移到 `@fibrae/semi-foundation/utils/date-fns-extra`。
19
+ - 新增目录入口(D22):`@fibrae/semi-foundation/base`、`/utils`、`/locale`,`@fibrae/semi-ai-foundation/base`、`/utils`,以及各 UI 包的 `/base`、`/utils`、`/internal`,各自汇总该目录的导出,如 `import { BaseFoundation, FocusScope } from '@fibrae/semi-foundation/base'`。原有深路径照常可用;foundation 的日期模块(`utils/date-fns-extra`、`utils/date-fns-locale`、`utils/zoned-time`)与 `base/env` 不在入口中,只按深路径导入。
20
+ - 破坏性:发布产物合并为单一 `dist/`(只含 ESM、类型与 CSS),删除 `lib/`、`dist/css/`、`./dist/*` 与 foundation 的 `./lib/*` 子路径。`@fibrae/semi-ui/dist/css/semi.min.css` 改为 `@fibrae/semi-ui-react/styles.css`,`dist/css/semi-tailwind.css` 改为 `@fibrae/semi-ui-react/tailwind.css`,`dist/css/semi-ai.min.css` 改为 `@fibrae/semi-ai-react/styles.css`,其余框架包同理。
21
+ - `semi-scss-compile` 的 `foundationPath`、`aiFoundationPath`(`-f`、`--ai`)指向包内 `dist/`,`iconPath`(`-i`)改为 `node_modules/@fibrae/semi-icons-core/dist`;构建插件只能与本版本的 Semi 包搭配。
22
+ - 新增 hooks 入口 `@fibrae/semi-ui-react/hooks` 与 Vue 的组合式函数入口 `@fibrae/semi-ui-vue/composables`,导出 `useLocale`、`useClickOutside`、`useCopied`、`useDidUpdate`、`useEventListener`(及 `getWindow`、`getDocument`、`getBody`)、`useFocusHandover`、`useResizeObserver`,React 另有 `useMergedRef`。Vue 另有 `useMounted`(服务端与 hydration 期间为 `false`,挂载后为 `true`)与 `useRecordFocus(scope, visible)`(在 `visible` 变为 `true` 时记录焦点,首帧可见时在 `onBeforeMount` 记录,服务端不执行)。React 的 `useResizeObserver(target, onResize, { enabled })` 接受 ref、元素或 `null`,为空或 `enabled` 为 false 时不观察。
23
+ - 包入口导出各组件 Props 与辅助类型,重名的加组件前缀(如 `CascaderValue`、`TableSize`)。内部名改为公开名:`ModalReactProps` 为 `ModalProps`,`SideSheetReactProps` 为 `SideSheetProps`,`ToastReactProps` 为 `ToastProps`,`NoticeReactProps` 为 `NoticeProps`,`CollapseReactProps` 为 `CollapseProps`,`ColorPickerReactProps` 为 `ColorPickerProps`,`BaseFormProps` 为 `FormProps`,`BasicLayoutProps` 为 `LayoutProps`。
24
+ - 组件根 DOM 接收未声明属性(F2),如 `id`、`title`、Form 注入的 `name`;没有根 DOM 的包装组件(Popover、Popconfirm、Dropdown、UserGuide)丢弃未声明属性(F11)。Props 类型包含落点元素的原生属性(F6),同名不同签名的保持原 Semi 签名;F11、F12 组件与 Provider 不接受任意 DOM 属性。
25
+ - 破坏性:受控判断改看值是否为 `undefined`:`value={undefined}`(及 `checked`、`visible`、`activeKey` 等)与不传相同,按非受控处理,`defaultXxx` 生效;`null` 仍是受控值。受控值变回 `undefined` 时输入类组件清空并转为非受控,Tabs、Collapse、Carousel、UserGuide 从最后的受控值继续。
26
+ - 「是否传入」类属性同样按值判断,写成 `undefined` 与不传相同,隐藏 Modal 的 footer、header 需传 `null`。React 中回调属性传 `null` 按未传处理,内容类属性传 `0` 照常渲染。
27
+ - 对外导出的顶层组件每次渲染读取 `semiGlobal.config.overrideDefaultProps`(F7),Provider、Consumer 与 React 的 Icon 例外;TagGroup、IconButton、Divider、ButtonGroup 等有自己的键,IconButton 不再沿用 `Button`。破坏性:Navigation 的键名为 `Nav`,React 原 `Navigation` 键不再生效。
28
+ - `overrideDefaultProps` 中写成 `undefined` 的键视为未设置;`id`、`insetLabelId`、`wrapperId`、`addonId`、`extraId` 不再生效,类型也去掉。Vue 的非函数全局默认值在实例首次缺省时读取并缓存。
29
+ - 破坏性:收集子组件的组件(Steps、Timeline、Navigation、Tabs、Breadcrumb、Select、Carousel、FormInputGroup、Layout 的 Sider、Table 的 `Table.Column`)展开 children 中的 Fragment,其中子项与直接写出的一样处理。只能在父组件内使用的子组件在外部使用时抛出 `<子组件> must be used inside <父组件>`。
30
+ - 键盘:不再监听 `keypress`,按键读 `KeyboardEvent.key` 而非 `keyCode`,输入法组合中的按键跳过。只设 `keyCode` 的模拟事件(如 `fireEvent.keyDown(el, { keyCode: 13 })`)需改传 `key`;`@fibrae/semi-foundation/utils/key-code` 不再有默认导出。
31
+ - 指针:拖动、缩放与按住连发(Slider、DragMove、Cropper、Resizable、ColorPicker、ImagePreview、Table 列宽、AudioPlayer 与 VideoPlayer 进度条、InputNumber 步进按钮)只在主键按下(`button` 为 0)时开始,笔的侧键与橡皮擦不再触发;鼠标左键、触摸与笔尖不变。
32
+ - 破坏性(样式):`semi-` 前缀元素及其伪元素统一为 `box-sizing: border-box`(`@layer semi-base`),`style` 传入的宽高包含边框与内边距,部分组件小 1 到 2px;依赖 content-box 的自定义样式需调整。
33
+ - 组件自绘的可聚焦元素键盘聚焦时统一显示主题焦点环(`$width-focus-ring`、`$color-focus-ring`)。Semi 元素统一为细滚动条(`$color-scrollbar-thumb`),可被覆盖;`.semi-light-scrollbar` 更名为 `.semi-scrollbar`。
34
+ - 浮层统一入栈,Esc 只关闭栈顶浮层,在 document 冒泡阶段处理,模拟 Esc 需在焦点元素而非 window 上派发;带遮罩的 Modal、SideSheet、ImagePreview 打开时页面其余部分为 `inert`。锁定滚动时,页面有滚动条就给根元素设 `scrollbar-gutter: stable` 保留滚动条槽,`position: fixed` 的元素也不横移(不支持的浏览器改为给 body 加 `padding-inline-end`),不再改写 `width`;`getPopupContainer` 返回 `null` 或 `undefined` 时 Portal 抛错。
35
+ - 破坏性:图标默认装饰性(`aria-hidden="true"`),不再输出 `role="img"` 与英文类型名的 `aria-label`;只有图标的按钮需传 `aria-label`,按 `getByRole('img', { name: 'close' })` 查询的测试需调整。图标不再用 `forwardRef`,判断图标改用 `elementType === 'Icon'`。
36
+ - 虚拟列表由 `react-window` 换为 `@tanstack/react-virtual`。拖拽排序换为 `@dnd-kit/react` 0.5(`~0.5.1`):TagInput、Transfer 拖动中实时重排,触摸按住 250ms 后才开始;删除深路径 `@fibrae/semi-ui-react/transfer/sortable-list`。
37
+ - 破坏性(类型):`BaseProps` 的 `children` 收紧为 `ReactNode`;每次都会传入的回调参数改为必填(如 Table 的 `sorter(a, b)`、Tree 的 `onChange(value)`);回调事件参数改为运行时实际事件(点击外部为原生 `MouseEvent`,Esc 为原生 `KeyboardEvent`),读取 `e.nativeEvent`、`e.persist()` 会报错。
38
+ - 复制:Typography 的 `copyable.onCopy` 与 Sidebar 的 `onDetailContentCopy` 在剪贴板写入完成后异步回调,失败时 `res` 为 false。
39
+ - 破坏性(样式钩子):RTL 改由 `dir` 与 `:dir(rtl)` 决定,删除 `semi-rtl`、`semi-portal-rtl`、`semi-modal-rtl`、`semi-table-wrapper-rtl` 等方向类名,自定义样式改用 `:dir(rtl)`。ConfigProvider 的 `direction` 与外层不同时,在内容外包一层带 `dir` 的 `div`。
40
+ - 破坏性:子组件 `elementType` 统一为 `Parent.Child`:`'BreadcrumbItem'` 改为 `'Breadcrumb.Item'`,`'NavHeader'`、`'NavFooter'` 改为 `'Nav.Header'`、`'Nav.Footer'`,Vue 的 `'AnchorLink'` 改为 `'Anchor.Link'`、`'DescriptionsItem'` 改为 `'Descriptions.Item'`;部分无人读取的 `elementType` 删除。
41
+ - Svelte:新增组件包 `@fibrae/semi-ui-svelte`、图标包 `@fibrae/semi-icons-svelte`(插画入口为 `/illustrations`),`svelte` peer 依赖为 `^5.57.0`。导出名、prop 名与回调名同 React 包;`className` 写作 `class`(接受字符串、数组与对象),`style` 只接受字符串;节点型 prop 与 render 函数改为 snippet,名字同 Vue 插槽(去掉 `render` 前缀),参数是带具名字段的对象,默认内容为 `children`。
42
+ - Svelte:受控值是可绑定 prop:`bind:checked={x}` 双向同步,`bind:checked={get, set}` 完全受控(setter 可拒绝或改写),`checked={x}` 单向传值只作初值、交互后本地覆盖、父级再推新值时以父级为准,同一组件上的展开属性(`{...rest}`)换成新对象时父级的值也会重新生效(Svelte 对未绑定 prop 的本地改写是临时的),要保留交互结果用 `bind:` 或在回调里写回;不提供 `defaultValue`、`defaultChecked`、`defaultVisible` 等 `default*` 属性。只为声明数据的子组件(`TabPane`、`Select.Option`、`Table.Column`)不提供,改用数据 prop(`tabList`、`optionList`、`columns`)加逐项 snippet。
43
+ - Svelte:包发布 `.svelte` 源码与 `.d.ts`,应用需用 `@sveltejs/vite-plugin-svelte` 等 Svelte 编译插件构建;组件导入同目录的 `.css`。对外方法经 `bind:this` 取组件实例调用;图标不支持 `elementType` 与 ref。`overrideDefaultProps` 在组件创建时读取;按子树变化的全局默认值用 `setContext(semiGlobalKey, new SemiGlobal())` 下发(`semiGlobalKey`、`SemiGlobal` 从包根导入)。
44
+ - Svelte:写在组件上的 `{@attach}` 作用于组件接收 `aria-*` 与 `tabindex` 的元素:有内部原生控件的组件(Input、TextArea、Switch、Checkbox、Radio、Select、TagInput 等)是该控件,其余是根元素;组件句柄(如 `focus()`)经 `bind:this` 获取。
45
+ - Svelte:带子组件的组件同时提供静态成员与具名导出,两者是同一个组件:`Layout.Header`、`Dropdown.Item`、`Nav.Sub`、`Typography.Text`、`Card.Meta`、`List.Item`、`Checkbox.Group`、`Radio.Group`、`Collapse.Panel`、`Tabs.TabItem`、`Skeleton.Avatar`、`ScrollList.Item` 等,模板中可写 `<Dropdown.Item>`,也可导入 `DropdownItem`。Form 例外,只有具名导出(F17)。
46
+ - Svelte:`@fibrae/semi-ui-svelte` 根导出的类型名都带组件前缀(如 `ButtonProps`、`ResizableSize`、`SpaceAlign`、`CardMetaProps`、`GridGutter`、`ModalSize`、`TypographyTextProps`),`Size`、`Type`、`Direction` 这类通用名不从包根导出。
47
+ - 服务端渲染:默认打开的弹层不进服务端 HTML,hydration 后才打开。Toast、Notification、Modal 的命令式 API 只在客户端调用,在服务端调用抛带说明的错误。Calendar 在服务端渲染时需传 `displayValue`,「今天」标记只在挂载后出现;服务端与客户端时区须一致,否则给 DatePicker、TimePicker 传 `timeZone`(可经 ConfigProvider)。`semiGlobal` 只在应用启动时设置,按请求变化的配置用 ConfigProvider。
48
+ - 行为变化:组件被隐藏而不卸载(React StrictMode 重放、`<Activity>`、Vue `<KeepAlive>`)时,已打开的面板、弹层、卡片、确认框、裁剪弹窗保持打开,随子树隐藏,重新显示后原样出现,隐藏与显示都不发 `onVisibleChange` 等可见性通知。原来 Vue 版在 KeepAlive 失活时关闭这些弹层(部分还会发 `visibleChange(false)` 或写回 `v-model`),React 的 Tooltip 系在 Activity 隐藏时关闭。涉及 Tooltip、Popover、Dropdown、Popconfirm、Select、AutoComplete、TreeSelect、Cascader、DatePicker、TimePicker、Calendar 的事件卡片、Chat 的删除确认、AIChatInput 面板、Upload 裁剪弹窗、Navigation 子菜单。Vue 的 `useClickOutside` 与 HotKeys 在 KeepAlive 缓存期间不响应。
49
+ - 公开类型:React 的 `JsonViewerState`、`DayColState`、`MonthCalendarState` 移除;`OverflowListState`、`UserGuideState`、`AnchorState`、`PopconfirmState` 改为 foundation 类型的别名;Vue、Svelte 的 `UserGuideState`、`AnchorState` 改为从 foundation 再导出。
50
+ - Svelte:RadioGroup、PinCode、Slider、InputGroup、TagInput 上传的 `onfocusin`、`onfocusout`、`onmouseenter`、`onmouseleave` 与组件自身的处理同时生效,不再被覆盖。
51
+ - 破坏性(类型):Semi 组件之间传递的内部属性移出公开 Props 类型,API 表不再列出。React 与 Solid:TextArea 的 `disabledEnterStartNewLine`,Input(及继承它的 InputNumber)的 `showClearIgnoreDisabled`,OverflowList 的 `overflowRenderDirection`,FormErrorMessage 的 `errorMessageId`、`helpTextId`、`isInInputGroup`;React 另有 Breadcrumb.Item 的 `active`、`shouldRenderSeparator`、`route`,Select.Option 的 `current`;Solid 另有 ScrollList 的 `x-semi-header-alias`、`x-semi-footer-alias`。React 删除 Tooltip、Popover、Dropdown(及继承它的 AIChatInput `Mcp`)、Popconfirm、Button、Row、Col、Layout、Layout.Sider、Skeleton 各子组件、InputNumber、Rating、Steps、TimePicker、ScrollList、Table 的 `prefixCls`,类名固定为组件默认前缀,自定义前缀改用构建插件的 `prefixCls`。React 另删 Radio、RadioGroup、Checkbox、CheckboxGroup、DatePicker 与 Steps 各子项的 `prefixCls`;Radio、Checkbox 不再读全局默认值里的 `prefixCls`,foundation 的 Radio、Checkbox、DatePicker 类型随之去掉该字段。Solid 删除 Row、Col、Layout 及其 Header、Footer、Content、Sider、Skeleton 各子组件、InputNumber、Rating、Radio、RadioGroup、Checkbox、CheckboxGroup、DatePicker、TimePicker、Popover、Popconfirm、Dropdown、ScrollList、Table、Steps 及各 Step 的 `prefixCls`,Tooltip 的 `prefixCls` 拆入 `TooltipInternalProps`,由 Popover、Dropdown 使用。Vue 与 Svelte 删除 Row、Col、Layout 及其各部件、Skeleton 各子组件、Steps、Rating、Table、Radio、RadioGroup、Checkbox、CheckboxGroup、Popover、Popconfirm、Dropdown、Tooltip 的 `prefixCls`(Vue 另删 Select.Option 的),Popover、Dropdown 给 Tooltip 的前缀改经内部 context 传入(Vue 的 AutoComplete 给 Select.Option 同理)。四个图标包的 `Icon` 删除 `prefixCls`,类名前缀固定为 `semi`。
52
+ - 破坏性:删除 React、Solid 的 Input(及 InputNumber)的 `onlyBorder` 与 `semi-input-only_border` 类名;各框架删除 ScrollList.Item 的 `type`(`onSelect` 的参数不再带 `type`),删除 Layout.Header、Layout.Footer、Layout.Content 的 `type`。React 的 Cascader、Image、UserGuide 的 Props 类型去掉未渲染的 `children`。Solid 的 TimePicker、PinCode 在类型中声明 `autofocus`。
53
+
54
+ ### 构建与宿主
55
+
56
+ - UI、AI、图标包的发布物新增 `docs/`:给编码 agent 读的文档,与安装版本一致,入口为 `node_modules/<包名>/docs/llms.txt`;类型声明中的组件属性带英文 JSDoc 说明。文档站另提供 `/llms.txt`、`/en-US/<框架>/llms.txt` 与每页的 `.md` 版本。
57
+ - `@fibrae/semi-json-viewer-core` 把 `jsonc-parser` 打进自身 `dist`,不再作为运行时依赖,Next Pages Router 的 webpack 不再解析其 UMD 入口。
58
+ - `@fibrae/semi-foundation` 新增依赖 `@shikijs/core`,代码高亮改从它导入,不再导入 `shiki/core`(`shiki` 仍提供 engine 与主题)。
59
+ - `@fibrae/semi-webpack-plugin` 的 peer `webpack` 标为可选:插件运行时经 `compiler.webpack` 取宿主自带的 webpack(如 Next.js),无需单独安装;类型声明仍引用 `webpack`。
60
+ - `@fibrae/semi-vite-plugin` 为每个 server 环境(含 Nuxt 未设 `consumer` 的环境与 React Router `serverBundles` 的 `ssrBundle_*`)把 React、Vue 的 UI、AI、图标包设为 `resolve.noExternal`,服务端渲染无需再配 `ssr.noExternal`;Solid 包不在其中,foundation 与 ai-foundation 只在设置了 `prefixCls` 时一并打进服务端产物(它们持有 `BASE_CLASS_PREFIX`,保持 external 会使服务端类名仍为 `semi-`,与客户端不一致);SolidStart dev 中 vite-plugin-solid 会把 foundation 写进服务端环境的 `resolve.external`,插件在所有插件之后把它移除,`prefixCls` 才对服务端渲染生效。
61
+ - 破坏性:`@fibrae/semi-vite-plugin` 的 `semiTheming()` 返回 `Plugin[]` 而不是单个 `Plugin`:写进 Vite 的 `plugins` 数组时会被展开,常规用法不变;把返回值当单个插件对象使用的代码(读取 `.name`、直接调用其钩子)须改为按数组处理。
62
+ - `@fibrae/semi-vite-plugin` 的 `omitCss` 同时作用于 dev 预构建,dev 不再注入组件 CSS;改选项后用 `vite --force` 重建 `.vite/deps`。
63
+ - `@fibrae/semi-vite-plugin` 在应用依赖 `@fibrae/semi-ui-solid`、`@fibrae/semi-ai-solid` 时,把 foundation、ai-foundation 的依赖经直接依赖它们的 Solid 包加入 `optimizeDeps.include`(只装 ai-solid 的应用也覆盖 foundation 的依赖),SolidStart dev 不再因 CommonJS 依赖白屏:有根入口的依赖按包名加入,foundation 按未导出深路径导入的 CommonJS 文件(Lottie 的 `lottie-web/build/player/lottie_light`)另行加入,只有子路径导出的依赖(如 `@tiptap/pm`)按 `exports` 中的子路径逐个加入,dev 中 ai-foundation 直接导入的 `@tiptap/pm/state` 与 `@tiptap/core` 预构建内的 ProseMirror 是同一份实例,AIChatInput 不再因 ProseMirror 报 `Adding different instances of a keyed plugin` 而无法挂载。
64
+ - `@fibrae/semi-vite-plugin` 的 `omitCss` 与 `prefixCls` 覆盖 Solid 包。
65
+ - 破坏性:`@fibrae/semi-next` 的 `omitCss` 默认值由 `true` 改为 `false`,组件按需带出自己的样式,不再需要导入 `styles.css`;仍要整包样式时显式传 `omitCss: true` 并导入一次 `styles.css`。自定义 `prefixCls` 须同时传 `omitCss: true`,否则读取配置时抛错。不传选项时 `--webpack` 下不再挂 `SemiWebpackPlugin`,由 Next 直接处理组件导入的 `.css`。
66
+ - `@fibrae/semi-next` 删除对服务端 `externals` 的改写(Next 16 中从未生效),改为把 `@fibrae/semi-ui-react`、`@fibrae/semi-ai-react`、`@fibrae/semi-icons-react`、`@fibrae/semi-icons-react/illustrations` 合并进 `transpilePackages`,Pages Router 两种打包器的 dev、build、start 不再报 `.css` 扩展名错误。
67
+ - `@fibrae/semi-next` 同时返回 `turbopack.rules` 与 `webpack()`,支持 Next 16 默认的 Turbopack;开 `omitCss` 或 `prefixCls` 时,应用已有同 glob 的 Turbopack 规则(`*.js`)即抛错,其他规则保留。
68
+ - `@fibrae/semi-next` 在 Turbopack 下(按 Next 读取配置前设置的 `process.env.TURBOPACK` 判断)传入 `cssLayer`、`extractCssOptions`、`overrideStylesheetLoaders` 即在读取配置时抛错。
69
+ - `@fibrae/semi-webpack-plugin` 新增子路径导出 `./semi-omit-css-loader`、`./semi-prefix-loader`,供按绝对路径引用 loader 的宿主(Next 的 `turbopack.rules`)使用。
70
+ - `semi-build-scss` 的 `-f`、`-i`(JS API 的 `foundationPath`、`iconPath`)改为可选:缺省时由 `@fibrae/semi-scss-compile` 自带的 `@fibrae/semi-foundation`、`@fibrae/semi-icons-core` 依赖解析,pnpm 隔离布局下应用无需直接安装这两个包,`semi-build-scss --prefix my -o app/semi-my.css` 即可,但 `@fibrae/semi-scss-compile` 的版本须与组件库一致,不一致时显式传 `-f`。`--ai` 路线的 `-f` 同样可选,`--ai` 本身仍须给出路径。
71
+ - `@fibrae/semi-ui-solid`、`@fibrae/semi-ai-solid`、`@fibrae/semi-icons-solid`、`@fibrae/semi-icons-solid/illustrations` 的 `dist` 在 dom 产物 `.js` 之外新增同名的 `.jsx` 产物(JSX 原样保留,导出名一致)。`exports` 的 `.`、`./*`(icons 另有 `./lab`)改为 `solid` 条件指向 `.jsx`、`default` 指向 `.js`,并新增 `types` 条件指向 `.d.ts`。识别 `solid` 条件的工具(vite-plugin-solid、SolidStart)使用 `.jsx`,其他打包器取 dom 产物、只能客户端渲染;包体积约翻倍。
72
+ - `@fibrae/semi-ui-vue`、`@fibrae/semi-ai-vue` 的 `dist` 中,SFC 脚本产物由 `<名>.vue_vue_type_script_setup_true_lang.js` 改名为 `<名>.script.js`,文件名不再含 `.vue`;`exports` 不变,不应深层导入这些内部文件。
73
+ - `@fibrae/semi-ui-react`、`@fibrae/semi-ai-react`、`@fibrae/semi-icons-react` 的 `dist` 中,除入口(`index.js`,icons 另有 `lab/index.js`、`illustrations/index.js`)以外的全部 `.js` 首行新增 `'use client'`。Server Component 里的图标因此保留组件身份,传给 Input、Select、Button 等的 `prefix`、`suffix`、`icon` 时仍按 Semi 图标处理;`createSvgComponent` 也只能在 `'use client'` 文件中调用。Next App Router 与 React Router RSC 模式的 Server Component 可直接导入扁平组件;点语法的子组件(如 `Typography.Title`)仍只能在 `'use client'` 文件中使用;`semiGlobal` 与 Form 的 HOC、hooks 同样只能在 `'use client'` 文件中使用,RSC 应用在 `'use client'` 模块中设置 `semiGlobal`。
74
+ - `@fibrae/semi-vite-plugin` 丢弃来自 `@fibrae/semi-ui-react`、`@fibrae/semi-ai-react`、`@fibrae/semi-icons-react` 的 `"use client"` 指令警告(`MODULE_LEVEL_DIRECTIVE`),并保留用户已有的 `build.rolldownOptions.onLog`。未使用该插件且未装 `@vitejs/plugin-react` 的 RSC 宿主构建会看到这些警告,可以忽略。
75
+ - 新增包 `@fibrae/semi-nuxt`:Nuxt 4 的模块,`modules: ['@fibrae/semi-nuxt']` 即把 `@fibrae/semi-vite-plugin` 注册进 Nuxt 的 Vite 构建,选项写在 `semi` 配置键下并原样传给插件(`prefixCls`、`cssLayer`、`omitCss`)。Nuxt 的服务端渲染与 dev 无需再配 `ssr.noExternal`;不做组件自动导入。peer 依赖 `nuxt >=4.6.2`。应用未设置 `features.inlineStyles` 时模块把它设为 `false`:Nuxt 默认内联 facade 为页面 `.vue` 的客户端 chunk 中的 CSS,只被单个页面导入、因而打进该页 chunk 的 Semi 组件样式会内联一份、同时仍链接一份,增量随页面独占的组件而定(实测常用组件页约 200KB);关闭后样式只经 `<link>` 加载。代价是应用自己的 SFC 样式也不再内联;要保留内联,在 `nuxt.config.ts` 或 `.nuxtrc` 显式设置 `features.inlineStyles`(或旧键 `experimental.inlineSSRStyles`),模块不覆盖。
76
+ - 破坏性:`@fibrae/semi-ui-react`、`@fibrae/semi-ui-vue`、`@fibrae/semi-ui-solid`、`@fibrae/semi-ui-svelte` 新增入口 `./locale`,导出内置语言包 `zh_CN`、`en_US` 与类型 `Locale`、`LocaleInput`(如 `import { zh_CN } from '@fibrae/semi-ui-vue/locale'`),应用无需直接安装 foundation;组件入口不导出它们,没有 `@fibrae/semi-ui-<框架>/locale/source/<名>` 深路径。React 的 `locale` 入口不带 `'use client'`,语言包是纯数据,RSC 应用可在 Server Component 中导入并传给 `ConfigProvider`、`LocaleProvider`。
77
+ - 新增包 `@fibrae/semi-ui-svelte`、`@fibrae/semi-ai-svelte`、`@fibrae/semi-icons-svelte`、`@fibrae/semi-icons-svelte/illustrations`:由 `svelte-package` 发布 `.svelte` 源码与 `.d.ts`,不经 `vp pack`;`exports` 的 `.`、`./*`、`./*.svelte`、`./*.svelte.js`(只有 ui 包有 `./*.svelte.js`,icons 另有 `./lab`)带 `types`、`svelte`、`default` 条件,须由识别 `svelte` 条件并编译 `.svelte` 的工具使用(`@sveltejs/vite-plugin-svelte`、SvelteKit);peer 依赖 `svelte ^5.57.0`。包内相对导入都带完整扩展名(`.js`、`.svelte.js`、`.svelte`),Node 的 ESM 解析、webpack 的 `fullySpecified` 与 TS `moduleResolution: nodenext` 都能解析。
78
+ - `@fibrae/semi-ui-svelte` 提供 `hooks`、`tokens`、`styles.css`、`tailwind.css` 入口。attachment `observeResize` 与 `dragMove` 都从包根导出,`hooks` 入口仍导出 `observeResize`。
79
+ - `@fibrae/semi-vite-plugin` 的 `omitCss` 覆盖 Svelte 包:注释掉 `semi-(ui|ai|icons)-svelte/dist` 下 `.svelte` 与 `.js` 里的 `.css` 导入,包括 `tokens` 入口;`prefixCls` 无需改动即生效;Svelte 包的服务端构建由 vite-plugin-svelte 处理,插件不把它们加入 `resolve.noExternal`。
80
+
81
+ ## 语言包
82
+
83
+ - 破坏性:只内置 zh_CN、en_US(D21),删除其他 55 个语言包。`zh_CN`、`en_US` 与 `Locale`、`LocaleInput` 类型从 UI 包的 `locale` 入口导入(如 `import { zh_CN } from '@fibrae/semi-ui-react/locale'`);`@fibrae/semi-ui-react/locale/source/<code>`、`@fibrae/semi-ui-react/locale/interface` 删除。
84
+ - 其他语言由应用自己提供:`locale` 接受 `LocaleInput`,`code` 必填,只写要翻译的命名空间与键,缺的部分回退 en_US。日期组件的月份、星期等另需 ConfigProvider 的 `dateFnsLocale`(D20)。
85
+ - 破坏性(类型):删除 `Image.loading`、`Image.loadError`、`DatePicker.day`、`Upload.illegalTips`、`Upload.cropOk`、`Upload.cropCancel`、`Table.sortedAscending`、`Table.sortedDescending`、`Table.sortedNone`、`Table.sortRoleDescription`、`Table.deselectRow`、`Table.deselectAllRows`、`Select.selected`、`Select.createItem`、`Tree.toggleCheck`、`Tree.expandItem`、`Tree.collapseItem`、`Avatar.clickable`、`Slider.disabled`;`Upload.cropTitle` 改为必填。
86
+ - 语言包新增键(如 `BackTop`、`Input`、`Notification`、`Sortable` 命名空间),自定义语言包未写的键显示英文;原来写死英文的可访问名称改读语言包,默认 zh_CN 下为中文,按英文名称查询元素的测试需改为按语言包取值。
87
+ - zh_CN 的 `DatePicker.fullMonths` 改为「1月」到「12月」。
88
+
89
+ ## 动画
90
+
91
+ - CSSAnimation 只响应元素自身的动画事件,子元素冒泡的不再结束父动画。Feedback 底部滑入、滑出的 keyframes 改名为 `semi-feedback-slideShow_bottom`、`semi-feedback-slideHide_bottom`。
92
+ - 根元素设置 `line-height: 1.4286`,依赖继承行高的组件不再随宿主变化;需要其他行高时在容器上覆盖。
93
+
94
+ ## 主题
95
+
96
+ - 破坏性:删除主题包与编译期 Sass 覆写:`@fibrae/semi-theme-default` 删除(并入 `@fibrae/semi-foundation/theme/`),插件删除 `theme`、`variables`、`include` 选项,`semi-scss-compile` 删除 `themePath`(`-t`/`--theme`),`local.scss`、`custom.scss` 不再加载。定制只走 `--semi-*` CSS 变量与 `@layer semi` 之外的 CSS;`prefixCls`、`cssLayer`、`omitCss` 保留。
97
+ - 破坏性:Sass 变量不再是公开定制面,`!default` 删除;`semi-theme-shared` 删除 `resolveThemeDir`、`convertMapToString`。
98
+ - token 入口由 `semi-ui-react/_base/base.scss` 移到 `@fibrae/semi-foundation/base/tokens.scss`,任一组件入口自带 token;新增 `@fibrae/semi-ui-react/tokens`(Vue、Solid、Svelte 的 UI 包同名),在应用入口最先导入。
99
+ - 破坏性:删除 Web Component 构建工具链:semi-webpack、semi-rspack 删除 `webComponentPath`、`semiWebComponentLoader`、`semiCssModuleLoader`,`semi-theme-shared` 删除 `injectWebComponentStyles`、`cssToModule`。组件可在 open ShadowRoot 内使用(F13),样式由应用加入 ShadowRoot。
100
+ - 破坏性:删除 `$z-popover`、`$z-dropdown`、`$z-tooltip` 等变量与 `--semi-z-popover`、`--semi-z-dropdown`、`--semi-z-tooltip` 等 CSS 变量:弹层在 top layer,z-index 不起作用(D5)。
101
+ - base 层名由 `base` 改为 `semi-base`。与 Tailwind 同用时须先声明 `@layer theme, base, semi, components, utilities;` 并保持 `cssLayer` 为 `true`;新增 `@fibrae/semi-ui-react/tailwind.css`(Vue、Solid、Svelte 的 UI 包同名)映射 token,圆角工具类由 `rounded-semi-border-radius-*` 改为 `rounded-semi-*`。
102
+ - 破坏性:token 落点由 `body` 改为 `:root`(暗色为 `[theme-mode='dark']`),`theme-mode` 仍写在 `body` 上;`:root` 上的未分层覆盖现在对浅色生效。
103
+ - 破坏性:调色板 token 改为完整颜色(`--semi-blue-5: 0, 100, 250` 改为 `#0064fa`);`rgba(var(--semi-x), a)` 须改为 `color-mix(in srgb, var(--semi-x) A%, transparent)`,不透明时直接写 `var(--semi-x)`;`color-mix` 与 token 自身的透明度相乘,调色板 token 配成半透明时结果会更淡。
104
+ - 改名:`--semi-transform-rotate-none` 改为 `--semi-transform_rotate-none`;重复声明的 `--semi-color-ai-background-top-hover`(激活态)改为 `--semi-color-ai-background-top-active`。暗色主题块设 `color-scheme: dark`。
105
+ - 新增 `--semi-spacing-*`、`--semi-font-size-*`、`--semi-line-height-*`、`--semi-font-weight-*`、`--semi-z-*` 等尺寸类 CSS 变量与 `--semi-shadow-knob`;字号、字重、字体栈等在 `:root` 覆盖即运行时生效,间距、控件高度、描边宽度的变量只影响 Tailwind 原子类。
@@ -0,0 +1,210 @@
1
+ # With TailwindCSS
2
+
3
+ > Use TailwindCSS and Semi more elegantly
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/ecosystem/tailwind/
6
+
7
+ ## Notice
8
+
9
+ This page will provide best practices for some issues encountered when using atomic style libraries such as TailwindCSS (v4) with Semi.
10
+
11
+ These problems are often encountered when other component libraries are used with Tailwind, but Semi provides official solutions. It is recommended to follow the instructions in this article to configure the project correctly.
12
+
13
+ > **Note**
14
+ >
15
+ > Semi does not rely on any third-party style libraries and can run without installing Tailwind. If you do not use atomic libraries such as Tailwind, please close this page directly.
16
+
17
+ ### 1. Solve the problem of style override priority
18
+
19
+ #### Problem performance
20
+
21
+ There is no effect or component library style exception when using some atomic classes in components.
22
+
23
+ #### Cause Analysis
24
+
25
+ When using Tailwind, Tailwind modifies the dom style through class names, which also affects the Semi component library. At the same time, Tailwind enables [Preflight](https://tailwindcss.com/docs/preflight) by default to reset the browser's default style.
26
+
27
+ Without any layer declaration there are only two possible outcomes, depending on the configuration of your project and the order of the entry imports:
28
+
29
+ 1. Tailwind is introduced before Semi style, and Semi has higher priority
30
+ 2. Semi style was introduced before Tailwind, and Tailwind has a higher priority.
31
+
32
+ If it is 1, it will appear that when Tailwind adds certain atomic classes, if the component style has defined a certain css attribute, the priority of the atomic class is lower than that of Semi, and the atomic class becomes invalid. For example, under the premise of 1, setting padding on the Button component will cause failure.
33
+
34
+ If it is 2, because Tailwind has a higher priority, its Preflight overwriting the browser's default style will also override Semi's style. For example, under the premise of 2, the background color of the light Button will be overwritten as transparent, causing the style to behave abnormally.
35
+
36
+ #### Solution
37
+
38
+ No matter which side of Tailwind or the component library has higher priority, problems will occur, so the solution lies in correctly handling the relationship between the priority of Preflight and the atomic classes required by users in the Tailwind style relative to the priority of the component library. **Declaring the layer order is a prerequisite of the integration, not an optional optimization.**
39
+
40
+ **1. Semi styles are in the `semi` layer by default**
41
+
42
+ Every stylesheet Semi ships is wrapped in `@layer semi { ... }`: the compiled CSS of each framework's component library, such as `@fibrae/semi-ui-react` (including `styles.css`), and the output of the Semi theme plugins (`@fibrae/semi-webpack-plugin`, `@fibrae/semi-rspack-plugin`, `@fibrae/semi-vite-plugin` and `@fibrae/semi-next`), whose `cssLayer` option defaults to `true`. Keep the default when using Tailwind and do not pass `cssLayer: false`: unlayered Semi styles are no longer controlled by the layer order and you are back to the two outcomes above.
43
+
44
+ **2. Declare the layer order**
45
+
46
+ 1. Create a CSS file (e.g., `semi-layer.css`) with the following content, listing all five layers:
47
+
48
+ ```css
49
+ @layer theme, base, semi, components, utilities;
50
+ ```
51
+
52
+ `semi` must come after `base` and before `components` and `utilities`: Preflight (`base`) cannot override Semi, and utilities can. Leaving `components` out moves Tailwind's own `components` layer after `utilities`, which breaks Tailwind's default contract.
53
+
54
+ 2. Import this file at the **very top** of your project's JS entry file (e.g., `main.ts`, `main.tsx`, or `index.js`), before all other import statements:
55
+
56
+ ```js
57
+ // src/main.ts - must be at the very top
58
+ import './semi-layer.css'; // must be first
59
+ import './tailwind.css'; // file containing @import "tailwindcss";
60
+ import { mount } from 'svelte';
61
+ import App from './App.svelte';
62
+ // ... other imports
63
+ ```
64
+
65
+ SvelteKit has no such JS entry file. Put the two imports at the very top of the script in the root layout `src/routes/+layout.svelte` instead. The root layout loads before every page, so the server-rendered styles of the first paint start with the layer order declaration in both development and production.
66
+
67
+ ```svelte
68
+ <!-- src/routes/+layout.svelte, at the very top of the script -->
69
+ <script lang="ts">
70
+ import './semi-layer.css';
71
+ import './tailwind.css';
72
+
73
+ let { children } = $props();
74
+ </script>
75
+
76
+ {@render children()}
77
+ ```
78
+
79
+ Add Tailwind to the build with `@tailwindcss/vite`, as its official guide describes, next to the Semi Vite plugin:
80
+
81
+ ```ts
82
+ // vite.config.ts, SvelteKit
83
+ import { sveltekit } from '@sveltejs/kit/vite';
84
+ import semi from '@fibrae/semi-vite-plugin';
85
+ import tailwindcss from '@tailwindcss/vite';
86
+ import { defineConfig } from 'vite';
87
+
88
+ // replace adapter with the SvelteKit adapter you use
89
+ export default defineConfig({
90
+ plugins: [tailwindcss(), sveltekit({ adapter }), semi()],
91
+ });
92
+ ```
93
+
94
+ > **Important**
95
+ >
96
+ > `semi-layer.css` must be imported before any CSS file containing `@import "tailwindcss";` and before any Semi component imports, otherwise the CSS Layer order will be incorrect. It is recommended to place it on the first line of the entry file. You can also write the layer order declaration on the first line of the Tailwind entry CSS and import only that one file.
97
+
98
+ #### Principle
99
+
100
+ Through the CSS Layer feature, priority setting of styles from different sources is achieved. All Semi styles are wrapped in `@layer semi { ... }`, and the declaration above sets the priority order of the layers:
101
+
102
+ ```css
103
+ @layer theme, base, semi, components, utilities;
104
+ ```
105
+
106
+ It means that `base` (including Preflight) has the lowest priority, followed by Semi, while Tailwind's `components` and the atomic classes set by the user (`p-0`, etc.) have the highest priority. A layer declared later wins regardless of selector specificity, so a single utility class can override Semi's root element styles without `!important`.
107
+
108
+ ### 2. Atomic classes on a component's inner elements
109
+
110
+ The root element takes atomic classes through `className` (`class` in Vue, Solid and Svelte). Inner elements, such as the body of a Card, the popup of a Select or the mask of a Modal, take them through `classNames`; `styles` sets their inline styles. Both are keyed by part name, and the API table of each component lists its parts. A part's classes go after the component's built-in classes, so utilities win through the layer order above.
111
+
112
+ ```svelte
113
+ <Card class="w-80" classNames={{ header: 'bg-semi-color-fill-0', body: 'p-0' }} styles={{ footer: 'text-align: end' }}>...</Card>
114
+ ```
115
+
116
+ `classNames` and `styles` given in the global `overrideDefaultProps` are defaults: a value passed to the component replaces them as a whole instead of merging key by key.
117
+
118
+ ### 3. Solve the problem of using Semi Token in Tailwind atomic class (optional)
119
+
120
+ Tailwind supports users to configure their own Token to implement themes. At the same time, Semi also provides its own theme solution and corresponding Token. If you want to use Semi Token directly in the project, for example, set the text color of a span to `--semi-color-text-0` to automatically switch between light and dark colors to be consistent with the theme, you need to set the css `color: var(--semi-color-text-0)` separately, which is very inconvenient.
121
+
122
+ Semi generates a Tailwind theme mapping file, `tailwind.css`, from the default theme at build time. It maps the semantic tokens and the palette to Tailwind tokens, so nothing needs to be copied by hand. Import it in the CSS file containing `@import "tailwindcss";`:
123
+
124
+ ```css
125
+ @import 'tailwindcss';
126
+ @import '@fibrae/semi-ui-svelte/tailwind.css';
127
+ ```
128
+
129
+ Then use utilities such as `bg-semi-color-primary` and `text-semi-color-text-0`; opacity modifiers work too:
130
+
131
+ ```svelte
132
+ <div class="bg-semi-color-primary/50 text-semi-color-text-0 rounded-semi-large shadow-semi-elevated">...</div>
133
+ ```
134
+
135
+ The file uses `@theme inline` and only writes `var(--semi-*)` references, so utilities follow the current theme and dark mode, and inside `.semi-always-light` and `.semi-always-dark` subtrees they resolve at the element that uses them. Naming:
136
+
137
+ | Semi Token | Tailwind Token | Utility example |
138
+ | - | - | - |
139
+ | `--semi-color-*` (non-gradient) | `--color-semi-color-*` | `bg-semi-color-primary` |
140
+ | Palette `--semi-<hue>-<shade>` | `--color-semi-<hue>-<shade>` | `bg-semi-blue-5` |
141
+ | `--semi-border-radius-*` | `--radius-semi-*` | `rounded-semi-large` |
142
+ | `--semi-shadow-*` | `--shadow-semi-*` | `shadow-semi-elevated` |
143
+ | `--semi-transition_function-*` | `--ease-semi-*` | `ease-semi-easeIn` |
144
+ | `--semi-spacing-*` | `--spacing-semi-*` | `p-semi-base`, `gap-semi-tight` |
145
+ | `--semi-font-size-*` | `--text-semi-*` | `text-semi-regular` |
146
+ | `--semi-line-height-*` | `--text-semi-*--line-height` | set together with `text-semi-*` |
147
+ | `--semi-font-weight-*` | `--font-weight-semi-*` | `font-semi-bold` |
148
+ | `--semi-font-family-*` | `--font-semi-family-*` | `font-semi-family-regular` |
149
+
150
+ `text-semi-regular` sets Semi's paired font size and line height (14px/20px). Font families carry a `family-` infix because Tailwind's `font-*` utilities read both the font family and the font weight namespaces; without it, `font-semi-regular` would name both the regular family and the regular weight.
151
+
152
+ ```svelte
153
+ <div class="p-semi-base gap-semi-tight text-semi-header-6 font-semi-bold">...</div>
154
+ ```
155
+
156
+ z-index, control heights and border widths have no Tailwind namespace and are not mapped; use the arbitrary value syntax:
157
+
158
+ ```svelte
159
+ <div class="z-(--semi-z-modal) h-(--semi-height-control-default) border-(length:--semi-border-thickness-control)">...</div>
160
+ ```
161
+
162
+ The palette has 212 colors: 16 hues with shades 0 to 9 (such as `semi-blue-5` and `semi-light-green-2`), `semi-white`, `semi-black`, the AI purple `semi-ai-purple-0` to `semi-ai-purple-9`, and the AI gradient stops `semi-ai-general-<shade>-<0 to 3>`. Palette values are complete colors; in dark mode each shade takes its dark value, and opacity modifiers work as well:
163
+
164
+ ```svelte
165
+ <div class="bg-semi-blue-0 text-semi-blue-7 border-semi-grey-2/50">...</div>
166
+ ```
167
+
168
+ The AI gradients (`--semi-color-ai-general*`, `--semi-ai-general-<shade>`), animation durations and other tokens are not mapped; use the arbitrary value syntax for them too, for example `bg-(image:--semi-color-ai-general)`.
169
+
170
+ The mapping is generated from the default theme. With another theme package, the spacing, font size, line height, font weight and font family utilities only have values if that theme's `global.scss` declares the same `--semi-*` variables.
171
+
172
+ #### The `dark:` variant
173
+
174
+ Semi switches to dark mode with the `theme-mode` attribute, not with Tailwind's default `prefers-color-scheme`. To use the `dark:` variant, declare it in your Tailwind entry CSS:
175
+
176
+ ```css
177
+ @custom-variant dark (&:where([theme-mode='dark'], [theme-mode='dark'] *));
178
+ ```
179
+
180
+ This variant only matches `[theme-mode='dark']`; it does not include `.semi-always-dark`.
181
+
182
+ ### 4. Known differences
183
+
184
+ With the layer order in place, Tailwind's Preflight still rewrites properties that Semi does not declare and leaves to the browser (UA) defaults. These components look different on a Tailwind page than on a blank page:
185
+
186
+ | Component / element | Property | Semi only | With Tailwind |
187
+ | - | - | - | - |
188
+ | MarkdownRender `hr` | `color`, `border-color` | gray | black |
189
+ | MarkdownRender outer `pre` | `font-family`, `font-size` | monospace, 13px | Tailwind's monospace stack, 16px |
190
+ | Empty: an `<img width height>` passed by the user | `height`, `max-width` | HTML attributes | `height: auto` and `max-width: 100%` |
191
+
192
+ Semi declares `line-height` on the root element (`:root`) explicitly (the 20px to 14px ratio), so component heights no longer change with the host page's line height; only `.semi-always-light` and `.semi-always-dark` subtrees inherit the page's own value. The documentation site uses modern-normalize, so its line height and element defaults differ from a blank page; compare component sizes on the same page base.
193
+
194
+ #### Overriding tokens at runtime
195
+
196
+ Semi declares its tokens on `:root`; tokens that change with the mode or read the palette are declared again on `[theme-mode='dark']`, `.semi-always-light` and `.semi-always-dark`. Override those with one unlayered rule per mode; unlayered styles always win over the `semi` layer:
197
+
198
+ ```css
199
+ :root {
200
+ --semi-color-primary: rgb(0, 120, 90);
201
+ }
202
+
203
+ [theme-mode='dark'] {
204
+ --semi-color-primary: rgb(90, 200, 160);
205
+ }
206
+ ```
207
+
208
+ To change the mode of a local area only, also override `.semi-always-light` or `.semi-always-dark` (`.{prefixCls}-always-*` with a custom `prefixCls`).
209
+
210
+ Spacing, font size, line height, font weight, font family, z-index, border width, border radius, the overlay color, `--semi-white` and `--semi-black` are the same in both modes and are declared on `:root` only, so one `:root` rule overrides them and `.semi-always-*` subtrees inherit it. Component stylesheets compute with `--semi-spacing-*` (except `none`, `loose` and `extra-loose`), `--semi-height-control-*`, `--semi-border-thickness`, `--semi-border-thickness-control` and `--semi-z-table-fixed` at compile time, so components use the compiled numbers instead of reading these variables; overriding them only affects Tailwind utilities. Change components through the theme's Sass variables.
@@ -0,0 +1,82 @@
1
+ # Accessibility
2
+
3
+ > 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.
4
+
5
+ Package: `@fibrae/semi-ui-svelte`. Web page: https://semi-design-next.pages.dev/en-US/svelte/experience/accessibility/
6
+
7
+ ## Understand user needs
8
+
9
+ To design and develop inclusive products, you first need to understand the different needs of different users and consider the aids and methods they use.
10
+
11
+ ### Visual impairment
12
+
13
+ Blind users rely on screen readers to access websites and applications. Typically, screen reader users navigate pages by navigating through specific elements such as headings, links, or form elements. So, you need to use semantic elements and check if the tags make sense out of context.
14
+
15
+ Low vision users have different needs depending on the nature of their vision impairment. Users may be unable to distinguish text or other content without magnification, especially small text, or have difficulty distinguishing text and images with low color contrast, etc. These requirements mean that the interface should not rely on color to convey information, the color palette needs to have sufficient contrast, and the layout should be responsive as the font size increases.
16
+
17
+ ### Device dependencies
18
+
19
+ Users who rely on the keyboard need to be able to access the focusable element on the screen through the keyboard.
20
+
21
+ Users who rely on mouse or touch need to have a target area large enough to hit easily.
22
+
23
+ ### Cognitive Impairment
24
+
25
+ Users who struggle with information should benefit from well-written content. Therefore, the application's information should be clear, concise, and easy to navigate; also consider visual hierarchy, break content into short, related sections, and avoid long paragraphs.
26
+
27
+ ## Keyboard and focus
28
+
29
+ Many users, including the visually impaired, rely on keyboard navigation to use our products. Therefore, all focusable components should be keyboard accessible, including links, buttons, and form controls.
30
+
31
+ ### Keyboard Shortcuts
32
+
33
+ - Tab key to switch focus: Tab order should follow a predictable sequential hierarchy, eg: top to bottom, left to right. When some key elements get the focus, the prompt information of the element should be displayed; when the focus is lost, the prompt disappears.
34
+ - Arrows: Navigate between related radio buttons, menu items or widget items.
35
+ - Enter: activate button, submit form, etc.
36
+ - Space: page down the screen.
37
+ - Esc: Exit from various bullet layers.
38
+ - Component detailed keyboard interactions are also provided in the documentation for each component.
39
+
40
+ ### Focus Principle
41
+
42
+ Focus states are an important part of the design because they let the keyboard user know where the focus is currently. The focus needs to follow the following principles:
43
+
44
+ - Initial focus: To enable users to complete tasks efficiently, always set initial focus for tasks. Set focus to the first logical interactive element or the first element in the task. When the focus is switched, if the current focus control is covered, the focus needs to be automatically switched to the first focus area of ​​the new page.
45
+ - Navigation is reversible: when the user switches to the next focus through the \[tab key], he must be able to switch to the previous focus through \[shift + Tab];
46
+ - Returnable: If the currently focused element disappears, the focus state should always return to the previous position. For example, closing a modal might mean that your focus is on the close button; when the modal is closed, you should return focus to the button that opened the modal;
47
+
48
+ ## Color and Contrast
49
+
50
+ ### Multiple prompts
51
+
52
+ Don't use color as the only way to convey information. Use adding icons, text, underlines, etc. to ensure that all groups of people receive the same message.
53
+
54
+ ### Text element comparison
55
+
56
+ According to WCAG recommended thresholds: the contrast between the text and background color of text elements should be at least 4.5:1 (including the text inside the component), and the contrast can be reduced to 3:1 for text 18px or larger, but can be used for disabled text. Not limited by contrast ratio requirements.
57
+
58
+ ### Component Status and Comparison
59
+
60
+ All operable components need to have a focus state. The active, hover, and focus states of the component all need to meet the 3:1 contrast ratio with the adjacent color. But there is no contrast requirement between the different states.
61
+
62
+ For a component with a stroke, it only needs to meet the 3:1 contrast between the stroke color and the base color. No contrast is required between the fill and stroke colors.
63
+
64
+ ### exception
65
+
66
+ For some components that mainly focus on reading, such as: Message, banner, etc., it is not necessary to strictly follow the AA standard. However, the actionable items in the component still need to meet the contrast requirements.
67
+
68
+ ## Pictures and Videos
69
+
70
+ We provide a way to provide a text-based alternative to all images, icons, and SVGs so that screen readers can succinctly describe images and videos, such as avatars.
71
+
72
+ Use `alt` to describe the content of an avatar image for screen readers.
73
+
74
+ ```svelte
75
+ <script lang="ts">
76
+ import { Avatar } from '@fibrae/semi-ui-svelte';
77
+ </script>
78
+
79
+ <div>
80
+ <Avatar alt="用户姓名" src="/assets/a11y-img-alt-avatar.png" style="margin: 4px" />
81
+ </div>
82
+ ```