npm - lingee-ui - Versions diffs - 0.0.7 → 0.0.9 - Mend

lingee-ui 0.0.7 → 0.0.9

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 (50) hide show

package/dist/button/index.css +1 -1
package/dist/button/index.d.mts +1 -1
package/dist/button/index.d.ts +1 -1
package/dist/{chunk-FQRDHJQZ.mjs → chunk-6M7ESUQX.mjs} +1 -1
package/dist/chunk-C5BDJQIO.js +2 -0
package/dist/chunk-H7GT6UT4.mjs +1 -0
package/dist/chunk-IE7TAOTL.mjs +2 -0
package/dist/{chunk-T5QR25R6.js → chunk-QIMQMSJB.js} +1 -1
package/dist/chunk-WAYZVZQB.js +1 -0
package/dist/{chunk-RM4W5RV7.mjs → chunk-XG3DE76O.mjs} +1 -1
package/dist/{chunk-KT3HSLBA.js → chunk-ZXUYGVWB.js} +1 -1
package/dist/{index-BVXwKHfX.d.mts → index-7pb5YOcq.d.mts} +1 -1
package/dist/{index-BVXwKHfX.d.ts → index-7pb5YOcq.d.ts} +1 -1
package/dist/index.css +1 -1
package/dist/index.d.mts +677 -62
package/dist/index.d.ts +677 -62
package/dist/index.js +2 -2
package/dist/index.mjs +2 -2
package/dist/input/index.css +1 -1
package/dist/input/index.js +1 -1
package/dist/input/index.mjs +1 -1
package/dist/tabs/index.css +1 -1
package/dist/tabs/index.d.mts +1 -1
package/dist/tabs/index.d.ts +1 -1
package/dist/tabs/index.js +1 -1
package/dist/tabs/index.mjs +1 -1
package/dist/textarea/index.css +1 -1
package/dist/toast/index.js +1 -1
package/dist/toast/index.mjs +1 -1
package/dist/tokens.css +1 -1
package/dist/tree/index.css +1 -0
package/dist/tree/index.d.mts +229 -0
package/dist/tree/index.d.ts +229 -0
package/dist/tree/index.js +1 -0
package/dist/tree/index.mjs +1 -0
package/package.json +7 -2
package/skill/AGENTS-SNIPPET.md +21 -19
package/skill/SKILL.md +19 -15
package/skill/VERSION.json +3 -3
package/skill/references/components/dropdown.md +35 -2
package/skill/references/components/ellipsis-tooltip.md +44 -0
package/skill/references/components/empty.md +28 -2
package/skill/references/components/sidebar.md +53 -27
package/skill/references/components/tree.md +118 -0
package/skill/references/components/upload.md +4 -1
package/skill/references/setup.md +2 -1
package/skill/references/tokens.md +16 -16
package/CHANGELOG.md +0 -119
package/dist/chunk-KQ733636.mjs +0 -1
package/dist/chunk-PQVYDWUK.js +0 -1

package/skill/SKILL.md CHANGED Viewed

@@ -2,17 +2,17 @@
 name: lingee-ui-usage
 description: 使用 lingee-ui 组件库与 lingee-icon 图标库开发 React 界面。当需要编写含按钮、表单、弹窗、表格、下拉、页签、图标等 UI 的 React/TypeScript 代码，或需要查询 lingee-ui 组件 API、Design Token 语义变量、可用图标名时触发。关键词：lingee-ui、lingee-icon、组件库、图标库、Design Token、语义变量、lg- 前缀、UI 组件。
 metadata:
-  lingeeUi: "0.0.7"
+  lingeeUi: "0.0.9"
   lingeeIcon: "1.0.16"
   generatedBy: "gen-skill.mjs"
 ---
 # lingee-ui 组件库使用技能
-Kingdee Lingee 设计体系的 React 组件库（36 个组件）与图标库（967 个图标）。
+Kingdee Lingee 设计体系的 React 组件库（38 个组件）与图标库（967 个图标）。
 本技能面向**消费方项目**，只覆盖「如何用」，不含组件库内部开发约定。
-- 组件库版本 `0.0.7` ｜ 图标库版本 `1.0.16`
+- 组件库版本 `0.0.9` ｜ 图标库版本 `1.0.16`
 - 组件在线预览：https://kingdee.github.io/lingee-ui/
 - 图标在线预览：https://kingdee.github.io/lingee-icon/
@@ -65,8 +65,9 @@ createRoot(el).render(
 | `Dialog` | 弹出窗 | 模态对话框，用于需要用户确认或填写信息的场景。支持声明式和命令式两种调用方式。 | `dialog.md` | — |
 | `Divider` | 分割线 | 用于分隔内容区块，使页面结构更清晰。 | `divider.md` | — |
 | `Drawer` | 抽屉 | 从屏幕边缘滑出的浮层面板，用于承载表单或详情内容。 | `drawer.md` | — |
-| `Dropdown` +13 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 | `dropdown.md` | — |
-| `Empty` | 空状态 | 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。 | `empty.md` | — |
+| `Dropdown` +14 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 | `dropdown.md` | — |
+| `EllipsisTooltip` | 省略提示 | 单行省略文本，仅在真正被截断时才悬停显示完整内容。 | `ellipsis-tooltip.md` | — |
+| `Empty`、`EmptyCard` | 空状态 | 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。 | `empty.md` | — |
 | `Flex` | 弹性布局 | 弹性布局容器，用于快速搭建横向/纵向排列，避免为简单布局单独写样式文件。 | `flex.md` | — |
 | `Form` | 表单 | 数据录入和校验组件，支持垂直、水平、行内布局。 | `form.md` | — |
 | `Image` | 图片预览 | 图片展示组件，支持点击放大预览、旋转、缩放等操作。 | `image.md` | — |
@@ -78,7 +79,7 @@ createRoot(el).render(
 | `RangePicker` | 日期范围选择器 | 用于选择日期范围的输入组件。 | `range-picker.md` | — |
 | `ScrollArea`、`ScrollBar` | 自定义滚动区域 | 自定义样式的滚动容器组件，提供美观的滚动条体验。 | `scroll-area.md` | — |
 | `Select` | 选择器 | 下拉选择器，支持单选、多选、搜索和远程加载。 | `select.md` | — |
-| `Sidebar` +10 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 | `sidebar.md` | — |
+| `Sidebar` +26 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 | `sidebar.md` | — |
 | `Skeleton` | 骨架屏 | 在数据加载完成前通过占位图形展示页面结构，降低用户等待焦虑。 | `skeleton.md` | — |
 | `Slider` | 数值滑块 | 滑动输入器，用于在数值区间内进行选择。 | `slider.md` | — |
 | `Spin` | 加载中 | 用于页面和区域的加载中状态指示器。 | `spin.md` | — |
@@ -91,6 +92,7 @@ createRoot(el).render(
 | `TimePicker` | 时间选择器 | 用于选择时间的输入组件。 | `time-picker.md` | — |
 | `toast` | 全局提示 | 命令式全局提示组件，用于操作反馈。 | `toast.md` | ✓ |
 | `Tooltip` | 文字提示 | 鼠标悬停时显示的简短提示信息。 | `tooltip.md` | ✓ |
+| `Tree` | 树形控件 | 用于展示层级结构数据，支持勾选、拖拽排序、异步加载与虚拟滚动。 | `tree.md` | ✓ |
 | `Upload` | 上传 | 文件上传组件，支持点击和拖拽上传。 | `upload.md` | — |
 - 「文档」列对应 `references/components/` 下的文件名，含完整 Props 与示例
@@ -155,7 +157,7 @@ import { Search, Trash } from "lingee-icon";
 | 文本-标题/正文 | `var(--lg-g-fg-color-black-strong)` | `rgba(0, 0, 0, 0.82)` |
 | 文本-次要 | `var(--lg-g-fg-color-black-muted)` | `rgba(0, 0, 0, 0.64)` |
 | 文本-辅助说明 | `var(--lg-g-fg-color-black-default)` | `rgba(0, 0, 0, 0.46)` |
-| 文本-禁用/占位 | `var(--lg-g-fg-color-black-aint)` | `rgba(0, 0, 0, 0.28)` |
+| 文本-禁用/占位 | `var(--lg-g-fg-color-black-faint)` | `rgba(0, 0, 0, 0.28)` |
 | 文本-品牌色 | `var(--lg-g-fg-color-primary-default)` | `#495DFF` |
 | 文本-危险 | `var(--lg-g-fg-color-danger-default)` | `#F12234` |
 | 文本-白色 | `var(--lg-g-fg-color-white-heavy)` | `#FFFFFF` |
@@ -174,16 +176,18 @@ import { Search, Trash } from "lingee-icon";
 暗色模式给 `<html>` 加 `data-theme="dark"` 即自动切换，无需额外处理。
-### 命名异常的 Token
+### 已废弃的错拼 Token
-以下 Token 名在设计源文件里拼错了，但已被组件库使用**不能改**。按正确拼写写出来的变量不存在，
-CSS 不报错、颜色直接丢失，属于极难排查的静默失效：
+以下 Token 早期从设计源文件带入了拼写错误，现已提供正确拼写。错拼名作为兼容别名保留、与正确名同值，
+但**会在后续版本移除**。改动存量代码时顺手换成正确名：
-- `var(--lg-g-fg-color-indigo-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-indigo-default`
-- `var(--lg-g-fg-color-lime-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-lime-default`
-- `var(--lg-g-fg-color-violet-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-violet-default`
-- `var(--lg-g-bg-color-emeraid-translucent-soft)` ← 照抄，不要写成 `--lg-g-bg-color-emerald-translucent-soft`
-- `var(--lg-g-fg-color-black-aint)` ← 片段 `aint` 命名不规范，照抄即可
+- `var(--lg-g-fg-color-black-faint)` ← 用这个，不要写 `--lg-g-fg-color-black-aint`
+- `var(--lg-g-fg-color-indigo-default)` ← 用这个，不要写 `--lg-g-fg-color-indigo-defauit`
+- `var(--lg-g-fg-color-lime-default)` ← 用这个，不要写 `--lg-g-fg-color-lime-defauit`
+- `var(--lg-g-fg-color-violet-default)` ← 用这个，不要写 `--lg-g-fg-color-violet-defauit`
+- `var(--lg-g-bg-color-emerald-translucent-soft)` ← 用这个，不要写 `--lg-g-bg-color-emeraid-translucent-soft`
+在旧代码里看到错拼名不要照抄延用，也不要把两者当成不同的 Token。
 ### 拿设计稿色值找 Token

package/skill/VERSION.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
-  "lingeeUi": "0.0.7",
+  "lingeeUi": "0.0.9",
   "lingeeIcon": "1.0.16",
-  "componentCount": 36,
+  "componentCount": 38,
   "iconCount": 967,
-  "sourceHash": "aeccd0bbb2cfd3c6"
+  "sourceHash": "b97bcbaa2290a729"
 }

package/skill/references/components/dropdown.md CHANGED Viewed

@@ -2,8 +2,8 @@
 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。
-- 导入：`import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownLabel, DropdownSeparator, DropdownGroup, DropdownSub, DropdownSubTrigger, DropdownSubContent, DropdownButton } from "lingee-ui";`
-- 可用类型：`DropdownProps`, `DropdownTriggerProps`, `DropdownContentProps`, `DropdownItemProps`, `DropdownCheckboxItemProps`, `DropdownRadioGroupProps`, `DropdownRadioItemProps`, `DropdownLabelProps`, `DropdownSeparatorProps`, `DropdownGroupProps`, `DropdownSubProps`, `DropdownSubTriggerProps`, `DropdownSubContentProps`, `DropdownItemData`, `DropdownMenuItemData`, `DropdownSeparatorData`, `DropdownLabelData`, `DropdownButtonProps`
+- 导入：`import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownLabel, DropdownSeparator, DropdownGroup, DropdownStatus, DropdownSub, DropdownSubTrigger, DropdownSubContent, DropdownButton } from "lingee-ui";`
+- 可用类型：`DropdownProps`, `DropdownTriggerProps`, `DropdownContentProps`, `DropdownItemProps`, `DropdownCheckboxItemProps`, `DropdownRadioGroupProps`, `DropdownRadioItemProps`, `DropdownLabelProps`, `DropdownSeparatorProps`, `DropdownGroupProps`, `DropdownStatusProps`, `DropdownStatusType`, `DropdownStatusText`, `DropdownSubProps`, `DropdownSubTriggerProps`, `DropdownSubContentProps`, `DropdownItemData`, `DropdownMenuItemData`, `DropdownSeparatorData`, `DropdownLabelData`, `DropdownButtonProps`
 ## 最小示例
@@ -38,8 +38,38 @@ export default function BasicDemo() {
 | `modal` | 是否为模态弹出 | `boolean` | `true` |
 | `disabled` | 是否禁用 | `boolean` | `false` |
 | `selectedKeys` | 选中项 key 数组（显示勾选） | `string[]` | - |
+| `loading` | 加载中，面板显示加载占位 | `boolean` | `false` |
+| `loadError` | 加载失败，面板显示失败占位（优先级低于 `loading`） | `boolean` | `false` |
+| `onRetry` | 失败占位的重试回调，传入后占位可点击 | `() => void` | - |
+| `statusText` | 覆盖三态文案，未传的键走语言包 | `DropdownStatusText` | - |
+| `loadingContent` | 自定义加载中内容 | `ReactNode` | - |
+| `errorContent` | 自定义失败内容 | `ReactNode` | - |
+| `emptyContent` | 自定义空态内容 | `ReactNode` | - |
+| `dropdownRender` | 包裹菜单内容 | `(menu: ReactNode) => ReactNode` | - |
+| `header` | 固定头部内容 | `ReactNode` | - |
+| `footer` | 固定底部内容 | `ReactNode` | - |
 | `children` | 触发器元素 | `ReactNode` | - |
+### DropdownStatus
+面板内三态占位。`items` 模式下由 Dropdown 自动渲染，Compound Component 模式需手动使用。
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `status` | 占位状态 | `"loading" \| "empty" \| "error"` | - |
+| `description` | 覆盖该状态的默认文案 | `ReactNode` | 取自语言包 |
+| `onRetry` | 重试回调，仅 `status="error"` 生效 | `() => void` | - |
+| `className` | 额外类名 | `string` | - |
+### DropdownSubTrigger
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `icon` | 前缀图标 | `ReactNode` | - |
+| `disabled` | 是否禁用 | `boolean` | `false` |
+| `onMouseEnter` | 鼠标进入回调，在内部展开子菜单后执行，可用于懒加载数据 | `MouseEventHandler` | - |
+| `children` | 触发项内容 | `ReactNode` | - |
 ### DropdownContent
 | 属性 | 说明 | 类型 | 默认值 |
@@ -49,6 +79,9 @@ export default function BasicDemo() {
 | `sideOffset` | 侧向偏移 | `number` | `4` |
 | `header` | 固定头部内容 | `ReactNode` | - |
 | `footer` | 固定底部内容 | `ReactNode` | - |
+| `autoFocusFirstItem` | 打开时是否聚焦第一项，不传则按输入模态自动判断 | `boolean` | - |
+打开面板时的焦点落点默认按最近一次输入方式自动判断：键盘（Enter / Space / Tab / 方向键）打开聚焦第一项，鼠标点击打开则把焦点留在菜单容器上。这样鼠标用户不会看到第一项自带 hover 态，键盘用户仍能看到焦点位置。仅在需要强制某一种行为时才传 `autoFocusFirstItem`。
 ### DropdownItem

package/skill/references/components/ellipsis-tooltip.md ADDED Viewed

@@ -0,0 +1,44 @@
+# EllipsisTooltip 省略提示
+单行省略文本，仅在真正被截断时才悬停显示完整内容。
+- 导入：`import { EllipsisTooltip } from "lingee-ui";`
+- 可用类型：`EllipsisTooltipProps`
+## 最小示例
+```tsx
+import { EllipsisTooltip } from "lingee-ui";
+const LONG_TEXT =
+  "A rather long single-line text that gets clipped and reveals its full content on hover";
+export default function BasicDemo() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12, width: 240 }}>
+      {/* Clipped: hover reveals the full text */}
+      <EllipsisTooltip content={LONG_TEXT}>{LONG_TEXT}</EllipsisTooltip>
+      {/* Not clipped: no tooltip, so it never repeats visible content */}
+      <EllipsisTooltip content="Short text">Short text</EllipsisTooltip>
+    </div>
+  );
+}
+```
+## API
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `content` | 提示内容，为空时不弹出 | `ReactNode` | - |
+| `children` | 文本内容 | `ReactNode` | - |
+| `as` | 容器标签 | `"span" \| "div"` | `"span"` |
+| `ellipsis` | 是否自带单行省略样式 | `boolean` | `true` |
+| `threshold` | 触发阈值（0~1），文本宽度超过 `容器宽度 × threshold` 时弹出 | `number` | `1` |
+| `maxLength` | 提示内容最大字符数，超出截断 | `number` | `2000` |
+| `anchorClassName` | 祖先 className，浮层最大宽度对齐该祖先 | `string` | - |
+| `getPopupContainer` | 浮层挂载容器，接收触发节点 | `(node: HTMLElement) => HTMLElement` | - |
+| `placement` | 弹出方向 | `TooltipPlacement` | `"top"` |
+| `maxWidth` | 浮层最大宽度（px），`anchorClassName` 命中时以后者为准 | `number` | `280` |
+其余属性透传给 `Tooltip`（`delayDuration`、`sideOffset`、`arrow` 等）。

package/skill/references/components/empty.md CHANGED Viewed

@@ -2,8 +2,8 @@
 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。
-- 导入：`import { Empty } from "lingee-ui";`
-- 可用类型：`EmptyProps`, `EmptySize`, `EmptyIconComponent`
+- 导入：`import { Empty, EmptyCard } from "lingee-ui";`
+- 可用类型：`EmptyProps`, `EmptySize`, `EmptyIconComponent`, `EmptyCardProps`, `EmptyCardStatus`, `EmptyCardVariant`, `EmptyCardSpacing`
 ## 最小示例
@@ -26,3 +26,29 @@ export default function BasicDemo() {
 | `children` | 自定义底部内容（如操作按钮） | `ReactNode` | - |
 | `className` | 自定义类名 | `string` | - |
 | `style` | 自定义内联样式 | `CSSProperties` | - |
+### Empty.Card
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `status` | 状态，决定默认图标与无障碍语义 | `"loading" \| "empty" \| "error"` | - |
+| `description` | 描述文案 | `ReactNode` | - |
+| `icon` | 覆盖默认图标；传 `null` 不渲染图标 | `ReactNode \| null` | 按 `status` 取 |
+| `variant` | 布局：`block` 区块级 / `inline` 行内轻量 | `"block" \| "inline"` | `"block"` |
+| `spacing` | 留白档位。`loose` 为顶部大留白（列表级空态） | `"none" \| "normal" \| "loose"` | `"normal"` |
+| `onRetry` | 重试回调。仅 `status="error"` 生效，传入后整体可点击 | `() => void` | - |
+| `className` | 自定义类名 | `string` | - |
+| `style` | 自定义内联样式 | `CSSProperties` | - |
+默认图标：`loading` 用旋转的 `LoaderCircle`，`empty` 用 `Inbox`，`error` 用 `ExclamationCircle`。
+**三态等高**：组件按 `variant` + `spacing` 设定 `min-height`，同档位下
+`loading` / `empty` / `error` 高度完全一致。
+| variant | spacing | 高度 |
+|---------|---------|------|
+| `block` | `none` | 18px |
+| `block` | `normal` | 64px |
+| `block` | `loose` | 85px（顶部 44 + 内容 18 + 底部 23） |
+| `inline` | `none` | 18px |
+| `inline` | `normal` | 26px |

package/skill/references/components/sidebar.md CHANGED Viewed

@@ -2,8 +2,8 @@
 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。
-- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarSkeletonItem, SidebarFooter } from "lingee-ui";`
-- 可用类型：`SidebarRootProps`, `SidebarHeaderProps`, `SidebarTabBarProps`, `SidebarTabItem`, `SidebarNavItemProps`, `SidebarCollapsibleNavItemProps`, `SidebarCollapsibleNavItemChild`, `SidebarGroupHeaderProps`, `SidebarListItemProps`, `SidebarIndicatorType`, `SidebarCollapsibleListItemProps`, `SidebarSkeletonItemProps`, `SidebarSkeletonItemStatus`, `SidebarSkeletonItemVariant`, `SidebarSkeletonItemSpacing`, `SidebarFooterProps`
+- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarFooter, SidebarFooterUser, SidebarFooterMenuStaticRow, SidebarFooterBadge, SidebarUsageBar, SidebarUsagePanel, SidebarUsagePanelSection, SidebarFeedbackModal, SidebarFeedbackSubmitPanel, SidebarFeedbackField, SidebarFeedbackFileWall, SidebarFeedbackHistoryPanel, SidebarFeedbackHistoryItem, SidebarFeedbackDetail, SidebarFeedbackAttachmentRow, SidebarFeedbackSimilarItem, SidebarAuthImage, formatFileSize } from "lingee-ui";`
+- 可用类型：`FeedbackAttachment`, `FeedbackStatus`, `FeedbackHistoryItem`, `FeedbackReply`, `FeedbackSimilarItem`, `FeedbackHistoryDetail`, `FeedbackTabKey`, `FeedbackFileWallItem`, `SidebarFeedbackModalProps`, `SidebarFeedbackSubmitPanelProps`, `SidebarFeedbackFieldProps`, `SidebarFeedbackFileWallProps`, `SidebarFeedbackHistoryPanelProps`, `SidebarFeedbackHistoryItemProps`, `SidebarFeedbackDetailProps`, `SidebarFeedbackAttachmentRowProps`, `SidebarFeedbackSimilarItemProps`, `SidebarAuthImageProps`, `SidebarRootProps`, `SidebarHeaderProps`, `SidebarTabBarProps`, `SidebarTabItem`, `SidebarNavItemProps`, `SidebarCollapsibleNavItemProps`, `SidebarCollapsibleNavItemChild`, `SidebarGroupHeaderProps`, `SidebarListItemProps`, `SidebarIndicatorType`, `SidebarCollapsibleListItemProps`, `SidebarCaretPlacement`, `SidebarFooterProps`, `SidebarFooterUserProps`, `SidebarFooterMenuStaticRowProps`, `SidebarFooterBadgeProps`, `SidebarUsageBarProps`, `SidebarUsageTone`, `SidebarUsagePanelProps`, `SidebarUsagePanelSectionProps`
 ## 最小示例
@@ -17,9 +17,7 @@ export default function BasicDemo() {
   const [active, setActive] = useState("new-task");
   return (
-    <Sidebar.Root
-      style={{ height: 420, borderRadius: 12 }}
-    >
+    <Sidebar.Root style={{ height: 320, borderRadius: 12, paddingTop: 10 }}>
       <Sidebar.TabBar
         items={[
           { key: "work", label: "工作", icon: <List size={20} /> },
@@ -145,37 +143,23 @@ export default function BasicDemo() {
 | `title` | 标题 | `ReactNode` | - |
 | `expanded` | 展开态 | `boolean` | `false` |
 | `onToggle` | 切换回调 | `() => void` | - |
+| `caretPlacement` | 箭头位置。`title` 紧跟标题、悬停才显现；`end` 恒在行尾且常显 | `"title" \| "end"` | `"title"` |
 | `actions` | 头部操作区插槽 | `ReactNode` | - |
 | `actionsVisible` | 操作区常显。菜单打开时置 `true` | `boolean` | `false` |
 | `active` | 头部高亮 | `boolean` | `false` |
 | `children` | 展开区内容 | `ReactNode` | - |
 | `expandLabel` / `collapseLabel` | 无障碍标签 | `string` | - |
-### Sidebar.SkeletonItem
+### Sidebar.Footer
+继承 `Sidebar.FooterUser` 的全部属性（不传 `children` 时透传给内建用户区），另有：
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
-| `status` | 状态，决定默认图标与无障碍语义 | `"loading" \| "empty" \| "error"` | - |
-| `text` | 提示文案 | `ReactNode` | - |
-| `icon` | 覆盖默认图标；传 `null` 不渲染图标 | `ReactNode \| null` | 按 `status` 取 |
-| `variant` | 布局：`block` 区块级 / `inline` 行内轻量 | `"block" \| "inline"` | `"block"` |
-| `spacing` | 留白档位。`loose` 为顶部大留白（列表级空态） | `"none" \| "normal" \| "loose"` | `"normal"` |
-| `onRetry` | 重试回调。仅 `status="error"` 生效，传入后整体可点击 | `() => void` | - |
-默认图标：`loading` 用旋转的 `LoaderCircle`，`empty` 用 `Inbox`，`error` 用 `ExclamationCircle`。
-**三态等高**：组件按 `variant` + `spacing` 设定 `min-height`，同档位下
-`loading` / `empty` / `error` 高度完全一致，因此「加载中 → 空态 / 错误态」
-切换时容器高度不变，列表不会跳动。
-| variant | spacing | 高度 |
-|---------|---------|------|
-| `block` | `none` | 24px |
-| `block` | `normal` | 48px |
-| `block` | `loose` | 80px（顶部 44 + 内容 24 + 底部 12） |
-| `inline` | `normal` | 26px |
+| `actions` | 右侧动作区插槽 | `ReactNode` | - |
+| `children` | 自定义左侧内容，传入时忽略 `avatar`/`name` 等 | `ReactNode` | - |
-### Sidebar.Footer
+### Sidebar.FooterUser
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
@@ -183,5 +167,47 @@ export default function BasicDemo() {
 | `name` | 名称，为空时不渲染身份区 | `ReactNode` | - |
 | `nameSuffix` | 名称后插槽（套餐标签等） | `ReactNode` | - |
 | `menuOpen` | 菜单展开态，驱动触发区高亮与箭头旋转 | `boolean` | `false` |
+| `showCaret` | 是否显示展开箭头 | `boolean` | `false` |
+| `nameTooltip` | 姓名超长时 hover 出全称提示 | `boolean` | `true` |
 | `onTriggerClick` | 点击触发区，回传 `DOMRect` 供手动定位浮层 | `(rect: DOMRect) => void` | - |
-| `actions` | 右侧动作区插槽 | `ReactNode` | - |
+### Sidebar.FooterMenuStaticRow
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `icon` | 行首图标 | `ReactNode` | - |
+| `children` | 行内容 | `ReactNode` | - |
+### Sidebar.FooterBadge
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `dot` | 是否显示未读红点 | `boolean` | `false` |
+| `children` | 被包裹的按钮 | `ReactNode` | - |
+### Sidebar.UsageBar
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `used` | 已用量 | `number` | - |
+| `total` | 总量。为 0 时进度按 0 处理 | `number` | - |
+| `formatNumber` | 数字格式化（千分位/小数位依赖 locale） | `(n: number) => string` | `String` |
+| `percentSuffix` | 总量后缀，如「（65%）」 | `ReactNode` | - |
+| `remainingPrefix` | 剩余量前缀，如「剩余 」 | `ReactNode` | - |
+| `ariaLabel` | 进度条无障碍标签 | `string` | - |
+### Sidebar.UsagePanel
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `title` | 面板标题，为空时不渲染头部 | `ReactNode` | - |
+| `loading` | 加载态，展示骨架屏并隐藏内容 | `boolean` | `false` |
+| `children` | 各额度分区 | `ReactNode` | - |
+### Sidebar.UsagePanelSection
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `title` | 分区标题 | `ReactNode` | - |
+| `extra` | 标题行右侧附加信息，如到期日 | `ReactNode` | - |
+| `children` | 分区内容，通常是一个 `UsageBar` | `ReactNode` | - |

package/skill/references/components/tree.md ADDED Viewed

@@ -0,0 +1,118 @@
+# Tree 树形控件
+用于展示层级结构数据，支持勾选、拖拽排序、异步加载与虚拟滚动。
+- 导入：`import { Tree } from "lingee-ui";`
+- 按需导入：`import { Tree } from "lingee-ui/tree";`
+- 可用类型：`TreeProps`, `TreeNodeData`, `TreeNodeState`, `TreeSize`, `TreeIndentGuide`, `TreeFieldNames`, `TreeCheckInfo`, `TreeSelectInfo`, `TreeExpandInfo`, `TreeDropInfo`, `TreeAllowDropOptions`, `TreeExpandAction`
+## 最小示例
+```tsx
+import { Tree } from "lingee-ui";
+import type { TreeNodeData } from "lingee-ui";
+const treeData: TreeNodeData[] = [
+  {
+    key: "finance",
+    title: "Finance Analysis",
+    children: [
+      { key: "finance-annual", title: "Annual Report" },
+      { key: "finance-budget", title: "Budget Execution" },
+      { key: "finance-cost", title: "Cost Breakdown" },
+    ],
+  },
+  {
+    key: "sales",
+    title: "Sales Analysis",
+    children: [
+      { key: "sales-review", title: "Performance Review" },
+      {
+        key: "sales-region",
+        title: "Regional Breakdown",
+        children: [
+          { key: "sales-region-north", title: "North Region" },
+          { key: "sales-region-south", title: "South Region" },
+        ],
+      },
+    ],
+  },
+  { key: "customer", title: "Customer Satisfaction" },
+];
+export default function BasicDemo() {
+  return (
+    <div style={{ width: 280 }}>
+      <Tree
+        treeData={treeData}
+        defaultExpandedKeys={["finance", "sales"]}
+        defaultSelectedKeys={["finance-budget"]}
+      />
+    </div>
+  );
+}
+```
+## API
+### Tree
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `treeData` | 节点数据 | `TreeNodeData[]` | - |
+| `fieldNames` | 字段名映射，用于适配非标准数据结构 | `{ key?, title?, children? }` | - |
+| `size` | 行高尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `indentGuide` | 缩进引导线形态 | `"none" \| "line"` | `"line"` |
+| `expandedKeys` | 展开的节点 key（受控） | `Key[]` | - |
+| `defaultExpandedKeys` | 默认展开的节点 key | `Key[]` | - |
+| `defaultExpandAll` | 默认展开全部节点 | `boolean` | `false` |
+| `autoExpandParent` | 展开子节点时自动展开其父节点 | `boolean` | `false` |
+| `expandAction` | 触发展开的交互方式 | `false \| "click" \| "doubleClick"` | `"click"` |
+| `onExpand` | 展开状态变化回调 | `(keys, info) => void` | - |
+| `selectable` | 是否可选中 | `boolean` | `true` |
+| `multiple` | 是否支持多选 | `boolean` | `false` |
+| `selectedKeys` | 选中的节点 key（受控） | `Key[]` | - |
+| `defaultSelectedKeys` | 默认选中的节点 key | `Key[]` | - |
+| `onSelect` | 选中状态变化回调 | `(keys, info) => void` | - |
+| `checkable` | 是否显示勾选框 | `boolean` | `false` |
+| `checkStrictly` | 父子节点勾选状态不再联动 | `boolean` | `false` |
+| `checkedKeys` | 勾选的节点 key（受控） | `Key[] \| { checked, halfChecked }` | - |
+| `defaultCheckedKeys` | 默认勾选的节点 key | `Key[]` | - |
+| `onCheck` | 勾选状态变化回调 | `(keys, info) => void` | - |
+| `showIcon` | 是否显示节点图标 | `boolean` | `false` |
+| `icon` | 全局节点图标，函数形式可按展开态切换 | `ReactNode \| ((node, state: { expanded, isLeaf }) => ReactNode)` | - |
+| `switcherIcon` | 自定义展开箭头，函数形式可按展开态切换 | `ReactNode \| ((state: { expanded, isLeaf }) => ReactNode)` | - |
+| `titleRender` | 自定义单行内容 | `(node) => ReactNode` | - |
+| `loadData` | 异步加载子节点 | `(node) => Promise<unknown>` | - |
+| `loadedKeys` | 已加载完成的节点 key | `Key[]` | - |
+| `draggable` | 是否可拖拽排序 | `boolean \| ((node) => boolean)` | `false` |
+| `allowDrop` | 校验能否放置到目标位置 | `(options) => boolean` | - |
+| `onDrop` | 拖拽放置回调 | `(info) => void` | - |
+| `height` | 可视区高度，设置后启用虚拟滚动 | `number` | - |
+| `itemHeight` | 虚拟滚动的单项高度 | `number` | 按 `size` 推导 |
+| `virtual` | 关闭虚拟滚动 | `boolean` | - |
+| `disabled` | 整体禁用 | `boolean` | `false` |
+| `loading` | 加载状态，展示遮罩 | `boolean` | `false` |
+| `empty` | 无数据时的展示内容 | `ReactNode` | `<Empty />` |
+| `animated` | 展开 / 折叠是否启用高度过渡动效（虚拟滚动下无效） | `boolean` | `true` |
+| `onRightClick` | 节点右键回调 | `(info) => void` | - |
+### TreeNodeData
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| `key` | 节点唯一标识 | `Key` |
+| `title` | 节点标题 | `ReactNode` |
+| `children` | 子节点 | `TreeNodeData[]` |
+| `icon` | 节点前置图标，覆盖 Tree 上的全局 `icon` | `ReactNode` |
+| `disabled` | 是否禁用 | `boolean` |
+| `disableCheckbox` | 是否禁用勾选框 | `boolean` |
+| `checkable` | 是否可勾选 | `boolean` |
+| `isLeaf` | 是否强制视作叶子节点 | `boolean` |
+| `selectable` | 是否可选中 | `boolean` |
+## 注意事项
+- 组件不持有 `treeData`，异步加载与拖拽排序均需消费方自行更新数据
+- 节点内部结构由底层 `@rc-component/tree` 生成，类名为 `lg-tree-treenode`、`lg-tree-switcher` 等单横线形式，覆盖样式时需按此书写
+- 虚拟滚动开启后行高必须固定，`titleRender` 中不要渲染高度不定的内容

package/skill/references/components/upload.md CHANGED Viewed

@@ -34,5 +34,8 @@ export default function BasicDemo() {
 | `fileList` | 文件列表（受控） | `UploadFile[]` | - |
 | `showFileList` | 是否显示文件列表 | `boolean` | `true` |
 | `onChange` | 文件列表变化回调 | `(fileList: UploadFile[]) => void` | - |
-| `customRequest` | 自定义上传请求 | `(options: CustomRequestOptions) => { abort }` | - |
+| `onReject` | 校验未通过回调 | `(files: File[], reason: "size" \| "type" \| "count") => void` | - |
+| `customRequest` | 自定义上传请求。省略则为仅收集模式 | `(options: CustomRequestOptions) => { abort }` | - |
+| `pasteable` | 是否支持粘贴文件（如截图） | `boolean` | `false` |
+| `validateAccept` | 是否按 `accept` 校验类型，拦住拖拽与粘贴 | `boolean` | `false` |
 | `children` | 触发区域 | `ReactNode` | - |

package/skill/references/setup.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # 接入指南
-组件库 `0.0.7` ｜ 图标库 `1.0.16`
+组件库 `0.0.9` ｜ 图标库 `1.0.16`
 ## 安装
@@ -63,6 +63,7 @@ document.documentElement.setAttribute("data-theme", "dark");
 - `lingee-ui/toast`
 - `lingee-ui/tooltip`
 - `lingee-ui/popover`
+- `lingee-ui/tree`
 - `lingee-ui/skill`
 - `lingee-ui/skill/*`

package/skill/references/tokens.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # 语义 Token 全表
-组件库 `0.0.7`。仅列语义层（`--lg-g-*`）。
+组件库 `0.0.9`。仅列语义层（`--lg-g-*`）。
 亮色与暗色**变量名完全相同**，给 `<html>` 加 `data-theme="dark"` 即自动切换，业务代码只写一次。
@@ -11,18 +11,18 @@
 **业务代码禁止直接写这些色值，也禁止引用 primitives 色板**，色值仅供查阅与比对。
-## ⚠️ 命名异常的 Token（照抄，不要纠正）
+## ⚠️ 已废弃的错拼 Token
-以下 Token 名在设计源文件中拼写有误，但**已被组件库使用，不能改**。
-CSS 变量不存在时不报错、颜色直接丢失，按「正确」拼写写出来会静默失效：
+以下 Token 早期从设计源文件带入了拼写错误，现已提供正确拼写。
+错拼名作为兼容别名保留（与正确名同值，供存量项目过渡），**后续版本会移除**：
-| 实际可用（照抄这个） | 说明 |
-|---------------------|------|
-| `var(--lg-g-fg-color-indigo-defauit)` | ~~`--lg-g-fg-color-indigo-default`~~ |
-| `var(--lg-g-fg-color-lime-defauit)` | ~~`--lg-g-fg-color-lime-default`~~ |
-| `var(--lg-g-fg-color-violet-defauit)` | ~~`--lg-g-fg-color-violet-default`~~ |
-| `var(--lg-g-bg-color-emeraid-translucent-soft)` | ~~`--lg-g-bg-color-emerald-translucent-soft`~~ |
-| `var(--lg-g-fg-color-black-aint)` | 片段 `aint` 非标准命名，照抄即可 |
+| 正确拼写（用这个） | 已废弃，勿再使用 |
+|-------------------|-----------------|
+| `var(--lg-g-fg-color-black-faint)` | ~~`--lg-g-fg-color-black-aint`~~ |
+| `var(--lg-g-fg-color-indigo-default)` | ~~`--lg-g-fg-color-indigo-defauit`~~ |
+| `var(--lg-g-fg-color-lime-default)` | ~~`--lg-g-fg-color-lime-defauit`~~ |
+| `var(--lg-g-fg-color-violet-default)` | ~~`--lg-g-fg-color-violet-defauit`~~ |
+| `var(--lg-g-bg-color-emerald-translucent-soft)` | ~~`--lg-g-bg-color-emeraid-translucent-soft`~~ |
 ## 前景色 fg（color / fill / stroke）（34）
@@ -31,7 +31,7 @@ CSS 变量不存在时不报错、颜色直接丢失，按「正确」拼写写
 | `var(--lg-g-fg-color-white-heavy)` | `#FFFFFF` | `#FFFFFF` |
 | `var(--lg-g-fg-color-white-dark)` | `#FFFFFF` | `rgba(255, 255, 255, 0.28)` |
 | `var(--lg-g-fg-color-black-moderate)` | `rgba(0, 0, 0, 0.18)` | `rgba(255, 255, 255, 0.18)` |
-| `var(--lg-g-fg-color-black-aint)` | `rgba(0, 0, 0, 0.28)` | `rgba(255, 255, 255, 0.28)` |
+| `var(--lg-g-fg-color-black-faint)` | `rgba(0, 0, 0, 0.28)` | `rgba(255, 255, 255, 0.28)` |
 | `var(--lg-g-fg-color-black-default)` | `rgba(0, 0, 0, 0.46)` | `rgba(255, 255, 255, 0.46)` |
 | `var(--lg-g-fg-color-black-muted)` | `rgba(0, 0, 0, 0.64)` | `rgba(255, 255, 255, 0.64)` |
 | `var(--lg-g-fg-color-black-strong)` | `rgba(0, 0, 0, 0.82)` | `rgba(255, 255, 255, 0.82)` |
@@ -54,14 +54,14 @@ CSS 变量不存在时不报错、颜色直接丢失，按「正确」拼写写
 | `var(--lg-g-fg-color-amber-default)` | `#E28800` | `#E28800` |
 | `var(--lg-g-fg-color-teal-default)` | `#00BFB8` | `#00BFB8` |
 | `var(--lg-g-fg-color-purple-default)` | `#7F2AF3` | `#7F2AF3` |
-| `var(--lg-g-fg-color-indigo-defauit)` | `#4343F5` | `#4343F5` |
+| `var(--lg-g-fg-color-indigo-default)` | `#4343F5` | `#4343F5` |
 | `var(--lg-g-fg-color-yellow-default)` | `#D1A600` | `#D1A600` |
 | `var(--lg-g-fg-color-cyan-default)` | `#0083D4` | `#0083D4` |
 | `var(--lg-g-fg-color-pink-default)` | `#ED1165` | `#ED1165` |
 | `var(--lg-g-fg-color-fuchsia-default)` | `#ED1DB9` | `#ED1DB9` |
 | `var(--lg-g-fg-color-emerald-default)` | `#009D72` | `#009D72` |
-| `var(--lg-g-fg-color-lime-defauit)` | `#5FBA04` | `#5FBA04` |
-| `var(--lg-g-fg-color-violet-defauit)` | `#572FF7` | `#572FF7` |
+| `var(--lg-g-fg-color-lime-default)` | `#5FBA04` | `#5FBA04` |
+| `var(--lg-g-fg-color-violet-default)` | `#572FF7` | `#572FF7` |
 ## 背景色 bg（background）（92）
@@ -148,7 +148,7 @@ CSS 变量不存在时不报错、颜色直接丢失，按「正确」拼写写
 | `var(--lg-g-bg-color-indigo-faint)` | `#F5F6FF` | `rgba(81, 85, 246, 0.03)` |
 | `var(--lg-g-bg-color-indigo-faint-dark)` | `#F5F6FF` | `#222327` |
 | `var(--lg-g-bg-color-gray-subtle)` | `#F7F8FA` | `#F7F8FA` |
-| `var(--lg-g-bg-color-emeraid-translucent-soft)` | `rgba(8, 199, 135, 0.08)` | `rgba(8, 199, 135, 0.08)` |
+| `var(--lg-g-bg-color-emerald-translucent-soft)` | `rgba(8, 199, 135, 0.08)` | `rgba(8, 199, 135, 0.08)` |
 | `var(--lg-g-bg-color-emerald-default)` | `#009D72` | `#009D72` |
 | `var(--lg-g-bg-color-lime-translucent-soft)` | `rgba(116, 215, 11, 0.08)` | `rgba(116, 215, 11, 0.08)` |
 | `var(--lg-g-bg-color-lime-default)` | `#5FBA04` | `#5FBA04` |