lingee-ui 0.0.15 → 0.0.16

package/skill/references/components/dropdown.md

@@ -1,6 +1,6 @@
 # Dropdown 下拉菜单
 
-向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。
+从指定方向弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。
 
 - 导入：`import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownLabel, DropdownSeparator, DropdownGroup, DropdownStatus, DropdownSub, DropdownSubTrigger, DropdownSubContent, DropdownButton } from "lingee-ui";`
 - 可用类型：`DropdownEllipsisTooltip`, `DropdownProps`, `DropdownTriggerProps`, `DropdownContentProps`, `DropdownItemProps`, `DropdownCheckboxItemProps`, `DropdownRadioGroupProps`, `DropdownRadioItemProps`, `DropdownLabelProps`, `DropdownSeparatorProps`, `DropdownGroupProps`, `DropdownStatusProps`, `DropdownStatusType`, `DropdownStatusText`, `DropdownSubProps`, `DropdownSubTriggerProps`, `DropdownSubContentProps`, `DropdownItemData`, `DropdownMenuItemData`, `DropdownSeparatorData`, `DropdownLabelData`, `DropdownButtonProps`
@@ -29,58 +29,62 @@ export default function BasicDemo() {
 
 ### Dropdown
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `items` | 菜单项数据（快捷模式） | `DropdownItemData[]` | - |
-| `open` | 受控打开状态 | `boolean` | - |
-| `defaultOpen` | 非受控默认打开状态 | `boolean` | `false` |
-| `onOpenChange` | 打开状态变化回调 | `(open: boolean) => void` | - |
-| `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` | - |
+| 属性             | 说明                                                       | 类型                                     | 默认值  |
+| ---------------- | ---------------------------------------------------------- | ---------------------------------------- | ------- |
+| `items`          | 菜单项数据（快捷模式）                                     | `DropdownItemData[]`                     | -       |
+| `open`           | 受控打开状态                                               | `boolean`                                | -       |
+| `defaultOpen`    | 非受控默认打开状态                                         | `boolean`                                | `false` |
+| `onOpenChange`   | 打开状态变化回调                                           | `(open: boolean) => void`                | -       |
+| `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`                              | -       |
+| `contentProps`   | `items` 快捷模式下面板的定位配置，取值同 `DropdownContent` | `Omit<DropdownContentProps, "children">` | -       |
+| `children`       | 触发器元素                                                 | `ReactNode`                              | -       |
 
 ### DropdownStatus
 
 面板内三态占位。`items` 模式下由 Dropdown 自动渲染，Compound Component 模式需手动使用。
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `status` | 占位状态 | `"loading" \| "empty" \| "error"` | - |
-| `description` | 覆盖该状态的默认文案 | `ReactNode` | 取自语言包 |
-| `onRetry` | 重试回调，仅 `status="error"` 生效 | `() => void` | - |
-| `className` | 额外类名 | `string` | - |
+| 属性          | 说明                               | 类型                              | 默认值     |
+| ------------- | ---------------------------------- | --------------------------------- | ---------- |
+| `status`      | 占位状态                           | `"loading" \| "empty" \| "error"` | -          |
+| `description` | 覆盖该状态的默认文案               | `ReactNode`                       | 取自语言包 |
+| `onRetry`     | 重试回调，仅 `status="error"` 生效 | `() => void`                      | -          |
+| `className`   | 额外类名                           | `string`                          | -          |
 
 ### DropdownSubTrigger
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `icon` | 前缀图标 | `ReactNode` | - |
-| `disabled` | 是否禁用 | `boolean` | `false` |
-| `onMouseEnter` | 鼠标进入回调，在内部展开子菜单后执行，可用于懒加载数据 | `MouseEventHandler` | - |
-| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，见 [长文本溢出提示](#长文本溢出提示) | `boolean \| ReactNode` | - |
-| `children` | 触发项内容 | `ReactNode` | - |
+| 属性              | 说明                                                             | 类型                   | 默认值  |
+| ----------------- | ---------------------------------------------------------------- | ---------------------- | ------- |
+| `icon`            | 前缀图标                                                         | `ReactNode`            | -       |
+| `disabled`        | 是否禁用                                                         | `boolean`              | `false` |
+| `onMouseEnter`    | 鼠标进入回调，在内部展开子菜单后执行，可用于懒加载数据           | `MouseEventHandler`    | -       |
+| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，见 [长文本溢出提示](#长文本溢出提示) | `boolean \| ReactNode` | -       |
+| `children`        | 触发项内容                                                       | `ReactNode`            | -       |
 
 ### DropdownSubContent
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `side` | 弹出方向 | `"top" \| "bottom" \| "left" \| "right"` | `"right"` |
-| `align` | 对齐方式 | `"start" \| "center" \| "end"` | `"start"` |
-| `sideOffset` | 侧向偏移 | `number` | `8` |
-| `style.maxHeight` | 覆盖面板高度上限 | `number \| string` | `346` |
-| `footer` | 固定底部内容（不随列表滚动） | `ReactNode` | - |
-| `children` | 子菜单内容 | `ReactNode` | - |
+| 属性               | 说明                                | 类型                                     | 默认值          |
+| ------------------ | ----------------------------------- | ---------------------------------------- | --------------- |
+| `side`             | 弹出方向                            | `"top" \| "bottom" \| "left" \| "right"` | `"right"`       |
+| `align`            | 对齐方式                            | `"start" \| "center" \| "end"`           | `"start"`       |
+| `sideOffset`       | 侧向偏移                            | `number`                                 | `8`             |
+| `alignOffset`      | 对齐方向偏移（px）                  | `number`                                 | `0`             |
+| `collisionPadding` | 碰撞边界内边距（px），防止浮层贴边  | `number`                                 | `8`             |
+| `container`        | 挂载容器；传 `null` 则不使用 Portal | `HTMLElement \| null`                    | `document.body` |
+| `style.maxHeight`  | 覆盖面板高度上限                    | `number \| string`                       | `346`           |
+| `footer`           | 固定底部内容（不随列表滚动）        | `ReactNode`                              | -               |
+| `children`         | 子菜单内容                          | `ReactNode`                              | -               |
 
 子菜单与主面板同口径限高：默认上限 346px（10 个菜单项），并始终与视口可用空间取较小值，超出部分由内置 ScrollArea 滚动。选项数量不受控的场景（如租户列表）无需额外处理。
 
@@ -97,42 +101,55 @@ export default function BasicDemo() {
 
 ### DropdownContent
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `side` | 弹出方向 | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
-| `align` | 对齐方式 | `"start" \| "center" \| "end"` | `"start"` |
-| `sideOffset` | 侧向偏移 | `number` | `4` |
-| `header` | 固定头部内容 | `ReactNode` | - |
-| `footer` | 固定底部内容 | `ReactNode` | - |
-| `autoFocusFirstItem` | 打开时是否聚焦第一项，不传则按输入模态自动判断 | `boolean` | - |
+| 属性                   | 说明                                             | 类型                                     | 默认值          |
+| ---------------------- | ------------------------------------------------ | ---------------------------------------- | --------------- |
+| `side`                 | 弹出方向                                         | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"`      |
+| `align`                | 对齐方式                                         | `"start" \| "center" \| "end"`           | `"start"`       |
+| `sideOffset`           | 与触发器沿弹出方向的距离                         | `number`                                 | `4`             |
+| `header`               | 固定头部内容                                     | `ReactNode`                              | -               |
+| `footer`               | 固定底部内容                                     | `ReactNode`                              | -               |
+| `autoFocusFirstItem`   | 打开时是否聚焦第一项，不传则按输入模态自动判断   | `boolean`                                | -               |
+| `borderless`           | 隐藏面板默认描边                                 | `boolean`                                | `false`         |
+| `alignOffset`          | 对齐方向偏移（px）                               | `number`                                 | `0`             |
+| `collisionPadding`     | 碰撞边界内边距（px），防止浮层贴边               | `number`                                 | `8`             |
+| `container`            | 挂载容器；传 `null` 则不使用 Portal              | `HTMLElement \| null`                    | `document.body` |
+| `onEscapeKeyDown`      | Escape 按下回调，可 `preventDefault` 阻止关闭    | `(event: KeyboardEvent) => void`         | -               |
+| `onPointerDownOutside` | 点击外部回调，可 `preventDefault` 阻止关闭       | `(event: CustomEvent) => void`           | -               |
+| `onInteractOutside`    | 外部交互回调（pointerDown + focus 的合集）       | `(event: CustomEvent) => void`           | -               |
+| `onCloseAutoFocus`     | 关闭时自动回焦回调，可 `preventDefault` 阻止回焦 | `(event: Event) => void`                 | -               |
 
 打开面板时的焦点落点默认按最近一次输入方式自动判断：键盘（Enter / Space / Tab / 方向键）打开聚焦第一项，鼠标点击打开则把焦点留在菜单容器上。这样鼠标用户不会看到第一项自带 hover 态，键盘用户仍能看到焦点位置。仅在需要强制某一种行为时才传 `autoFocusFirstItem`。
 
 ### DropdownItem
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `onSelect` | 选中回调 | `(event: Event) => void` | - |
-| `disabled` | 是否禁用 | `boolean` | `false` |
-| `danger` | 是否为危险操作（红色） | `boolean` | `false` |
-| `icon` | 前缀图标 | `ReactNode` | - |
-| `description` | 副标题描述（显示在主文本下方） | `ReactNode` | - |
-| `selected` | 是否选中（显示勾选） | `boolean` | `false` |
-| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，详见下方章节 | `boolean \| ReactNode` | - |
-| `children` | 菜单项内容 | `ReactNode` | - |
+| 属性              | 说明                                     | 类型                     | 默认值  |
+| ----------------- | ---------------------------------------- | ------------------------ | ------- |
+| `onSelect`        | 选中回调                                 | `(event: Event) => void` | -       |
+| `disabled`        | 是否禁用                                 | `boolean`                | `false` |
+| `danger`          | 是否为危险操作（红色）                   | `boolean`                | `false` |
+| `icon`            | 前缀图标                                 | `ReactNode`              | -       |
+| `description`     | 副标题描述（显示在主文本下方）           | `ReactNode`              | -       |
+| `selected`        | 是否选中（显示勾选）                     | `boolean`                | `false` |
+| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，详见下方章节 | `boolean \| ReactNode`   | -       |
+| `children`        | 菜单项内容                               | `ReactNode`              | -       |
 
 ### 长文本溢出提示
 
 面板宽度默认随内容撑开，长文案会把浮层顶出屏幕。给菜单项传 `ellipsisTooltip` 后文本带最大宽度（240px）并单行截断，**仅在真正被截断时**悬浮显示完整内容 —— 未截断不弹，不会出现重复可见文字的干扰提示。
 
 ```tsx
-{/* true：取 children 作为提示内容 */}
-<DropdownItem ellipsisTooltip>{tenantName}</DropdownItem>
+{
+  /* true：取 children 作为提示内容 */
+}
+<DropdownItem ellipsisTooltip>{tenantName}</DropdownItem>;
 
-{/* children 是 JSX 时显式传纯文本，否则整块 JSX 会被塞进浮层 */}
+{
+  /* children 是 JSX 时显式传纯文本，否则整块 JSX 会被塞进浮层 */
+}
 <DropdownItem ellipsisTooltip={file.name}>
-  <span>{file.name}</span><Tag>new</Tag>
-</DropdownItem>
+  <span>{file.name}</span>
+  <Tag>new</Tag>
+</DropdownItem>;
 ```
 
 `DropdownItem` / `DropdownRadioItem` / `DropdownCheckboxItem` / `DropdownSubTrigger` 均支持，`items` 快捷模式在数据项上同名传入即可。
@@ -148,6 +165,7 @@ export default function BasicDemo() {
 ## DropdownButton 触发器按钮
 
 统一的下拉触发器按钮组件，提供两种视觉态：
+
 - **Default**：透明背景 + 深色文字，hover 时浅灰底
 - **Selected**：蓝色浅底 + 蓝色文字，支持 hover 显示清除图标
 - **Glassy**：半透明白底 + 描边，适用于有色背景
@@ -160,17 +178,17 @@ export default function BasicDemo() {
 
 ### DropdownButton
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `children` | 按钮文本 | `ReactNode` | - |
-| `variant` | 按钮变体 | `"default" \| "glassy"` | `"default"` |
-| `size` | 尺寸 | `"sm" \| "lg"` | `"sm"` |
-| `icon` | 前置图标 | `ReactNode` | - |
-| `selected` | 是否已有选中内容（蓝色态） | `boolean` | `false` |
-| `open` | 是否展开态（箭头旋转 180°） | `boolean` | `false` |
-| `clearable` | hover 时是否显示清除图标 | `boolean` | `false` |
-| `hideArrow` | 隐藏箭头（用于纯 toggle 按钮） | `boolean` | `false` |
-| `disabled` | 是否禁用 | `boolean` | `false` |
-| `onClear` | 清除回调 | `(e: MouseEvent) => void` | - |
-| `onClick` | 点击回调 | `(e: MouseEvent) => void` | - |
-| `className` | 额外类名 | `string` | - |
+| 属性        | 说明                           | 类型                      | 默认值      |
+| ----------- | ------------------------------ | ------------------------- | ----------- |
+| `children`  | 按钮文本                       | `ReactNode`               | -           |
+| `variant`   | 按钮变体                       | `"default" \| "glassy"`   | `"default"` |
+| `size`      | 尺寸                           | `"sm" \| "lg"`            | `"sm"`      |
+| `icon`      | 前置图标                       | `ReactNode`               | -           |
+| `selected`  | 是否已有选中内容（蓝色态）     | `boolean`                 | `false`     |
+| `open`      | 是否展开态（箭头旋转 180°）    | `boolean`                 | `false`     |
+| `clearable` | hover 时是否显示清除图标       | `boolean`                 | `false`     |
+| `hideArrow` | 隐藏箭头（用于纯 toggle 按钮） | `boolean`                 | `false`     |
+| `disabled`  | 是否禁用                       | `boolean`                 | `false`     |
+| `onClear`   | 清除回调                       | `(e: MouseEvent) => void` | -           |
+| `onClick`   | 点击回调                       | `(e: MouseEvent) => void` | -           |
+| `className` | 额外类名                       | `string`                  | -           |

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

@@ -40,5 +40,13 @@ export default function BasicDemo() {
 | `getPopupContainer` | 浮层挂载容器，接收触发节点 | `(node: HTMLElement) => HTMLElement` | - |
 | `placement` | 弹出方向 | `TooltipPlacement` | `"top"` |
 | `maxWidth` | 浮层最大宽度（px），`anchorClassName` 命中时以后者为准 | `number` | `280` |
+| `disabled` | 禁用后不渲染浮层，直接展示 `children` | `boolean` | `false` |
+| `delayDuration` | hover 延迟展示时间（ms） | `number` | `200` |
+| `sideOffset` | 浮层与触发元素的间距（px） | `number` | `6` |
+| `arrow` | 是否显示箭头 | `boolean` | `true` |
+| `defaultOpen` | 非受控默认打开状态 | `boolean` | `false` |
+| `scrollable` | 内容超出限高时是否滚动；传 `false` 则完整撑开 | `boolean` | `true` |
+
+其余属性继承 `Omit<TooltipProps, "children" \| "content" \| "open" \| "onOpenChange" \| "container">`。
 
 其余属性透传给 `Tooltip`（`delayDuration`、`sideOffset`、`arrow` 等）。

package/skill/references/components/empty.md

@@ -23,7 +23,7 @@ export default function BasicDemo() {
 | `icon` | 图标：传 lingee-icon 组件自动注入渐变，传 ReactNode 完全自定义，不传使用默认图标 | `ComponentType<SvgIconProps> \| ReactNode` | 默认 DocumentLibrary |
 | `description` | 描述文字 | `ReactNode` | - |
 | `size` | 尺寸：`lg` 页面级 / `md` 局部（默认）/ `sm` 迷你 | `"sm" \| "md" \| "lg"` | `"md"` |
-| `children` | 自定义底部内容（如操作按钮） | `ReactNode` | - |
+| `children` | 描述下方的自定义内容（如操作按钮），渲染在 `.lg-empty__extra` 内，间距由组件提供无需自行加 margin | `ReactNode` | - |
 | `className` | 自定义类名 | `string` | - |
 | `style` | 自定义内联样式 | `CSSProperties` | - |
 

package/skill/references/components/form.md

@@ -41,6 +41,8 @@ export default function BasicDemo() {
 | `form` | Form 实例（useForm 创建） | `FormInstance` | - |
 | `onFinish` | 提交且校验通过回调 | `(values) => void` | - |
 | `onFinishFailed` | 校验失败回调 | `() => void` | - |
+| `onValuesChange` | 字段值变化回调 | `(changedValues, allValues) => void` | - |
+| `requiredMark` | 是否在必填项标签后显示 `*` | `boolean` | `true` |
 
 ### Form.Item
 
@@ -51,6 +53,12 @@ export default function BasicDemo() {
 | `required` | 是否必填 | `boolean` | `false` |
 | `rules` | 校验规则 | `Rule[]` | - |
 | `valuePropName` | 值属性名 | `string` | `"value"` |
+| `trigger` | 触发 onChange 的 prop 名 | `string` | `"onChange"` |
+| `getValueFromEvent` | 从事件参数中提取值 | `(...args: unknown[]) => unknown` | - |
+| `requiredMessage` | 必填提示文案，配合 `required` 使用 | `string` | - |
+| `tooltip` | 标签后的提示信息 | `ReactNode` | - |
+| `extra` | 额外说明，显示在控件下方 | `ReactNode` | - |
+| `injectError` | 校验失败时是否向子控件注入 `error={true}` | `boolean` | `true` |
 
 ### Form.useForm
 

package/skill/references/components/pagination.md

@@ -40,3 +40,8 @@ export default function BasicDemo() {
 | `showQuickJumper` | 是否显示快速跳转 | `boolean` | `false` |
 | `variant` | 样式变体 | `"simple" \| "bordered" \| "borderless"` | `"bordered"` |
 | `disabled` | 是否禁用 | `boolean` | `false` |
+| `align` | 水平对齐方式 | `"start" \| "center" \| "end"` | - |
+| `defaultPageSize` | 非受控默认每页条数 | `number` | - |
+| `pageSizeOptions` | 每页条数下拉选项 | `number[]` | - |
+| `hideOnSinglePage` | 仅一页时是否隐藏整个分页器 | `boolean` | `false` |
+| `onPageSizeChange` | 每页条数变化回调 | `(current: number, size: number) => void` | - |

package/skill/references/components/popover.md

@@ -17,7 +17,7 @@ export default function BasicDemo() {
       <PopoverTrigger>
         <Button>Click me</Button>
       </PopoverTrigger>
-      <PopoverContent>
+      <PopoverContent className="lg-popover--card">
         <p style={{ margin: 0 }}>This is the content of the popover.</p>
       </PopoverContent>
     </Popover>
@@ -42,8 +42,19 @@ export default function BasicDemo() {
 
 ### PopoverContent
 
-| 属性         | 说明                 | 类型                                     | 默认值     |
-| ------------ | -------------------- | ---------------------------------------- | ---------- |
-| `side`       | 弹出方向             | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
-| `align`      | 对齐方式             | `"start" \| "center" \| "end"`           | `"center"` |
-| `sideOffset` | 弹出层与触发器的间距 | `number`                                 | `4`        |
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `side` | 期望弹出方向；空间不足时可能自动翻转 | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
+| `align` | 沿弹出方向的对齐方式 | `"start" \| "center" \| "end"` | `"center"` |
+| `sideOffset` | 弹出层与触发器的间距（px） | `number` | `4` |
+| `alignOffset` | 沿对齐轴的偏移（px） | `number` | `0` |
+| `collisionPadding` | 与碰撞边界的最小距离（px） | `number` | `8` |
+| `container` | Portal 挂载容器；传 `null` 时就地渲染 | `HTMLElement \| null` | `document.body` |
+| `className` | 自定义类名；使用 `lg-popover--card` 启用标准卡片外观 | `string` | - |
+| `onEscapeKeyDown` | Escape 按下回调，可 `preventDefault` 阻止关闭 | `(event: KeyboardEvent) => void` | - |
+| `onPointerDownOutside` | 点击外部回调，可 `preventDefault` 阻止关闭 | `(event: CustomEvent) => void` | - |
+| `onFocusOutside` | 焦点移出回调 | `(event: CustomEvent) => void` | - |
+| `onInteractOutside` | 外部交互回调（pointerDown + focus） | `(event: CustomEvent) => void` | - |
+| `onOpenAutoFocus` | 打开时自动聚焦回调，可 `preventDefault` 阻止自动聚焦 | `(event: Event) => void` | - |
+| `onCloseAutoFocus` | 关闭时自动回焦回调，可 `preventDefault` 阻止回焦 | `(event: Event) => void` | - |
+| `children` | 浮层内容 | `ReactNode` | - |

package/skill/references/components/radio.md

@@ -29,10 +29,14 @@ export default function BasicDemo() {
 |------|------|------|--------|
 | `value` | 受控选中值 | `string` | - |
 | `defaultValue` | 默认选中值 | `string` | - |
-| `onValueChange` | 选中值变化回调 | `(value: string) => void` | - |
+| `onChange` | 选中值变化回调 | `(value: string) => void` | - |
 | `disabled` | 是否整组禁用 | `boolean` | `false` |
 | `orientation` | 排列方向 | `"horizontal" \| "vertical"` | `"vertical"` |
 | `size` | 尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `name` | 组名（用于原生 form） | `string` | - |
+| `children` | 子元素（`RadioItem` 列表） | `ReactNode` | - |
+| `className` | 自定义类名 | `string` | - |
+| `style` | 自定义样式 | `CSSProperties` | - |
 
 ### RadioItem
 

package/skill/references/components/range-picker.md

@@ -38,6 +38,14 @@ export default function BasicDemo() {
 | `errorMessage` | 错误提示信息 | `string` | - |
 | `minDate` | 最小可选日期 | `Date` | - |
 | `maxDate` | 最大可选日期 | `Date` | - |
+| `disabledDate` | 禁用日期判断函数 | `(date: Date) => boolean` | - |
+| `format` | 日期格式化 | `string` | `"yyyy/MM/dd"` |
+| `separator` | 起止日期之间的分隔符 | `string` | `"～"` |
+| `size` | 尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
+| `allowClear` | 是否显示清空按钮 | `boolean` | `true` |
+| `weekStartsOn` | 一周起始日，`0` 为周日 | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |
+| `getPopupContainer` | 浮层挂载容器，用于在 `overflow` 裁剪的滚动容器内就地挂载 | `() => HTMLElement` | - |
+| `onOpenChange` | 面板展开/收起回调 | `(open: boolean) => void` | - |
 
 ### DateRange
 

package/skill/references/components/select.md

@@ -51,3 +51,6 @@ export default function BasicDemo() {
 | `suffixIcon` | 后缀图标 | `ReactNode` | - |
 | `maxTagCount` | 多选模式最多显示 Tag 数 | `number` | - |
 | `dropdown` | 下拉面板配置 | `SelectDropdownProps` | - |
+| `defaultValue` | 非受控默认值 | `T \| T[]` | - |
+| `onDropdownVisibleChange` | 下拉展开/收起回调 | `(open: boolean) => void` | - |
+| `labelRender` | 自定义选中值在触发器中的渲染。用于下拉面板展示丰富内容（如头像+名字+工号）、触发器只显示简短文本的场景 | `(value: T, option?: SelectOption<T>) => ReactNode` | 渲染 `option.label` |

package/skill/references/components/slider.md

@@ -40,3 +40,4 @@ export default function BasicDemo() {
 | `orientation` | 方向 | `"horizontal" \| "vertical"` | `"horizontal"` |
 | `tooltip` | 是否显示 Tooltip | `boolean` | `true` |
 | `tipFormatter` | Tooltip 格式化 | `(value: number) => string` | - |
+| `onValueCommit` | 拖拽结束时回调，适合只在最终值上触发请求的场景 | `(value: number[]) => void` | - |

package/skill/references/components/steps.md

@@ -31,4 +31,5 @@ export default function BasicDemo() {
 | `size` | 尺寸 | `"default" \| "small"` | `"default"` |
 | `status` | 当前步骤状态 | `"process" \| "error"` | `"process"` |
 | `titlePlacement` | 标题方向 | `"vertical" \| "horizontal"` | `"vertical"` |
+| `initial` | 起始序号 | `number` | `0` |
 | `onChange` | 步骤点击回调 | `(current: number) => void` | - |

package/skill/references/components/table.md

@@ -3,7 +3,7 @@
 用于展示行列数据的表格组件，支持排序、行选择、加载态等。
 
 - 导入：`import { Table } from "lingee-ui";`
-- 可用类型：`TableProps`, `TableColumnType`, `TableRowSelection`, `TableSize`, `TableSorterState`
+- 可用类型：`TableProps`, `TableColumnType`, `TableRowSelection`, `TableSize`, `TableSorterState`, `TableStatusType`, `TableStatusText`
 
 ## 最小示例
 
@@ -33,7 +33,10 @@ export default function BasicDemo() {
 |------|------|------|--------|
 | `columns` | 列定义 | `Array<{ title, dataIndex, key, render?, width?, align?, fixed?, sorter? }>` | - |
 | `dataSource` | 数据源 | `Array<Record<string, any>>` | `[]` |
-| `loading` | 是否显示加载状态 | `boolean` | `false` |
+| `loading` | 加载中。无数据时表体展示加载缺省态，已有数据时展示遮罩 | `boolean` | `false` |
+| `loadError` | 加载失败，表体展示失败缺省态。优先级低于 `loading` | `boolean` | `false` |
+| `onRetry` | 失败缺省态的重试回调，传入后缺省态可点击 | `() => void` | - |
+| `statusText` | 覆盖三态缺省文案 | `{ loading?, empty?, error? }` | - |
 | `rowKey` | 行唯一标识字段 | `string \| ((record) => string)` | `"key"` |
 | `rowSelection` | 行选择配置 | `{ selectedRowKeys, onChange }` | - |
 | `onRow` | 行事件 | `(record, index) => HTMLAttributes` | - |
@@ -42,3 +45,9 @@ export default function BasicDemo() {
 | `striped` | 是否显示斑马纹 | `boolean` | `false` |
 | `hoverable` | 是否行悬浮高亮 | `boolean` | `true` |
 | `scroll` | 滚动设置 | `{ x?: number, y?: number }` | - |
+| `showHeader` | 是否显示表头 | `boolean` | `true` |
+| `title` | 表格标题 | `ReactNode \| (() => ReactNode)` | - |
+| `footer` | 表格底部 | `ReactNode \| (() => ReactNode)` | - |
+| `empty` | 自定义空态内容，覆盖内置空缺省态 | `ReactNode` | - |
+| `errorContent` | 自定义失败内容，覆盖内置失败缺省态 | `ReactNode` | - |
+| `onSortChange` | 排序变化回调 | `(sorter: TableSorterState) => void` | - |

package/skill/references/components/textarea.md

@@ -3,7 +3,7 @@
 多行纯文本编辑控件，支持字数统计和自动高度。
 
 - 导入：`import { Textarea } from "lingee-ui";`
-- 可用类型：`TextareaProps`
+- 可用类型：`TextareaProps`, `TextareaAutoSizeConfig`
 
 ## 最小示例
 
@@ -20,11 +20,14 @@ export default function BasicDemo() {
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
 | `placeholder` | 占位文本 | `string` | - |
-| `rows` | 显示行数 | `number` | - |
+| `rows` | 显示行数，开启 `autoSize` 后失效 | `number` | - |
 | `maxLength` | 最大字符数 | `number` | - |
-| `showCount` | 是否显示字数统计 | `boolean` | `false` |
-| `autoSize` | 自适应高度 | `boolean \| { minRows: number; maxRows: number }` | - |
+| `showCount` | 是否显示字数统计（需配合 `maxLength`） | `boolean` | `false` |
+| `autoSize` | 高度随内容自适应；对象形式约束行数区间 | `boolean \| { minRows?: number; maxRows?: number }` | `false` |
 | `disabled` | 是否禁用 | `boolean` | `false` |
 | `error` | 是否为错误状态 | `boolean` | `false` |
 | `value` | 受控值 | `string` | - |
-| `onChange` | 值变化回调 | `(e: ChangeEvent) => void` | - |
+| `onChange` | 值变化回调 | `(e: ChangeEvent<HTMLTextAreaElement>) => void` | - |
+| `onPressEnter` | 按下 Enter 时的回调（不含 Shift+Enter） | `(e: KeyboardEvent<HTMLTextAreaElement>) => void` | - |
+
+其余原生 `<textarea>` 属性均可透传。`TextareaProps` 继承 `Omit<TextareaHTMLAttributes, "onChange">`。

package/skill/references/components/time-picker.md

@@ -37,6 +37,8 @@ export default function BasicDemo() {
 | `error` | 是否显示错误状态 | `boolean` | `false` |
 | `errorMessage` | 错误提示信息 | `string` | - |
 | `allowClear` | 是否允许清除 | `boolean` | `true` |
+| `getPopupContainer` | 浮层挂载容器，用于在 `overflow` 裁剪的滚动容器内就地挂载 | `() => HTMLElement` | - |
+| `onOpenChange` | 面板展开/收起回调 | `(open: boolean) => void` | - |
 
 ### TimeValue
 

package/skill/references/components/toast.md

@@ -29,19 +29,42 @@ Toast 通过命令式方法调用，无需手动渲染组件。
 
 ### 方法
 
-| 方法 | 说明 | 参数 |
-|------|------|------|
-| `toast.success(message)` | 成功提示 | `string \| ToastOptions` |
-| `toast.error(message)` | 错误提示 | `string \| ToastOptions` |
-| `toast.warning(message)` | 警告提示 | `string \| ToastOptions` |
-| `toast.info(message)` | 信息提示 | `string \| ToastOptions` |
-| `toast.destroy()` | 销毁所有消息 | - |
+四个提示方法均返回**关闭函数**，调用即可手动关掉该条提示。
 
-### ToastOptions
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `toast.info(message)` | 信息提示 | `string \| ToastConfig` | `() => void` |
+| `toast.success(message)` | 成功提示 | `string \| ToastConfig` | `() => void` |
+| `toast.warning(message)` | 警告提示 | `string \| ToastConfig` | `() => void` |
+| `toast.error(message)` | 错误提示 | `string \| ToastConfig` | `() => void` |
+| `toast.destroy()` | 销毁所有提示 | - | `void` |
+| `toast.config(options)` | 设置全局默认项 | `ToastGlobalConfig` | `void` |
+
+设 `duration: 0` 的常驻提示不会自动消失，也不随发起页卸载而消失，**必须持有返回的关闭函数并主动调用**：
+
+```tsx
+const close = toast.info({ content: "正在同步…", duration: 0 });
+// 时机合适时
+close();
+```
+
+### ToastConfig
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `content` | 提示内容 | `ReactNode` | - |
+| `icon` | 自定义图标，替换默认类型图标；传 `null` 不显示图标 | `ReactNode \| null` | 按类型取 |
+| `duration` | 自动关闭延时（ms），`0` 为不自动关闭 | `number` | `3000` |
+| `closable` | 是否显示关闭按钮 | `boolean` | `false` |
+| `onClose` | 关闭时回调 | `() => void` | - |
+| `key` | 唯一标识，相同 key 会更新已有提示 | `string` | - |
+| `className` | 自定义类名 | `string` | - |
+
+### ToastGlobalConfig
 
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
-| `content` | 提示内容 | `string` | - |
-| `duration` | 自动关闭延时（ms），0 为不关闭 | `number` | `3000` |
-| `closable` | 是否可手动关闭 | `boolean` | `false` |
-| `key` | 唯一标识，相同 key 会更新内容 | `string` | - |
+| `maxCount` | 同时显示的最大提示数 | `number` | - |
+| `duration` | 默认自动关闭延时（ms） | `number` | `3000` |
+| `top` | 距顶部距离（px） | `number` | - |
+| `getContainer` | 自定义挂载容器 | `() => HTMLElement` | - |

package/skill/references/components/tooltip.md

@@ -31,6 +31,11 @@ export default function BasicDemo() {
 | `sideOffset` | 箭头尖端与触发元素的间距（px） | `number` | `4` |
 | `maxWidth` | 浮层最大宽度（px），覆盖档位默认宽度 | `number` | 按档位取 240 / 240 / 320 / 500 |
 | `scrollable` | 内容超出限高时滚动（单行档不生效） | `boolean` | `true` |
+| `disabled` | 禁用后不渲染浮层，直接展示 `children` | `boolean` | `false` |
+| `open` | 受控开关 | `boolean` | - |
+| `defaultOpen` | 非受控默认打开状态 | `boolean` | `false` |
+| `onOpenChange` | 开关变化回调 | `(open: boolean) => void` | - |
+| `container` | 挂载容器；传 `null` 则不使用 Portal（就地渲染） | `HTMLElement \| null` | `document.body` |
 
 | `children` | 触发元素 | `ReactNode` | - |
 

package/skill/references/components/upload.md

@@ -46,6 +46,9 @@ export default function BasicDemo() {
 | `beforeUpload` | 上传前钩子，返回 `false` 阻止、返回 `File`/`Blob` 替换待传文件 | `(file, fileList) => boolean \| File \| Blob \| Promise<...>` | - |
 | `pasteable` | 是否支持粘贴文件（如截图） | `boolean` | `false` |
 | `validateAccept` | 是否按 `accept` 校验类型，拦住拖拽与粘贴 | `boolean` | `false` |
+| `defaultFileList` | 非受控默认文件列表 | `UploadFile[]` | - |
+| `onRemove` | 移除前拦截，返回 `false` 或 reject 阻止移除 | `(file: UploadFile) => boolean \| void \| Promise<boolean>` | - |
+| `renderItem` | 自定义文件列表项渲染 | `(file: UploadFile, actions: FileItemActions) => ReactNode` | - |
 | `children` | 触发区域 | `ReactNode` | - |
 
 ## 内置 XHR 上传