lingee-ui 0.0.15 → 0.0.17

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

@@ -44,3 +44,6 @@ export default function BasicDemo() {
 | `maxDate` | 最大可选日期 | `Date` | - |
 | `allowClear` | 是否允许清除 | `boolean` | `true` |
 | `showToday` | 是否显示今天按钮 | `boolean` | `true` |
+| `weekStartsOn` | 一周起始日，`0` 为周日 | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |
+| `getPopupContainer` | 浮层挂载容器，用于在 `overflow` 裁剪的滚动容器内就地挂载 | `() => HTMLElement` | - |
+| `onOpenChange` | 面板展开/收起回调 | `(open: boolean) => void` | - |

package/skill/references/components/dialog.md

@@ -44,34 +44,57 @@ export default function BasicDemo() {
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
 | `open` | 是否打开 | `boolean` | - |
-| `onOpenChange` | 打开状态变化回调 | `(open: boolean) => void` | - |
-| `zIndex` | 遮罩层层级，内容层自动加 1；优先于 Provider 基线 | `number` | `LingeeProvider.dialog.zIndex` |
+| `onOpenChange` | 打开状态变化回调（关闭时 `false`） | `(open: boolean) => void` | - |
 | `title` | 标题 | `ReactNode` | - |
-| `description` | 描述文本 | `ReactNode` | - |
-| `width` | 宽度 | `number` | `460` |
+| `extra` | 标题栏右侧额外内容 | `ReactNode` | - |
+| `children` | 内容区域 | `ReactNode` | - |
+| `width` | 宽度 | `number \| string` | `460` |
 | `height` | 面板总高 | `number \| string` | 自适应内容 |
-| `maxHeight` | 面板总高上限，仅 `autoHeight` 时生效 | `number \| string` | `640` |
+| `maxHeight` | 面板总高上限 | `number \| string` | `640` |
 | `autoHeight` | body 高度跟随内容，面板上限改由 `maxHeight` 给出 | `boolean` | `false` |
 | `closable` | 是否显示关闭按钮 | `boolean` | `true` |
-| `okText` | 确认按钮文本 | `string` | - |
+| `footer` | 底部操作区，传 `ReactNode` 完全自定义；传 `null` 隐藏 | `ReactNode` | - |
+| `okText` | 确认按钮文本（传入后自动渲染 footer，与 `footer` 互斥） | `string` | - |
 | `cancelText` | 取消按钮文本 | `string` | - |
-| `onOk` | 确认回调 | `() => void` | - |
+| `onOk` | 确认回调，返回 Promise 时按钮显示 loading | `() => void \| Promise<void>` | - |
 | `onCancel` | 取消回调 | `() => void` | - |
-| `children` | 内容区域 | `ReactNode` | - |
+| `okDanger` | 确认按钮是否为危险样式 | `boolean` | `false` |
+| `okProps` | 确认按钮额外属性（`disabled` / `loading` / `size` 等） | `DialogButtonProps` | - |
+| `cancelProps` | 取消按钮额外属性 | `DialogButtonProps` | - |
+| `modal` | 是否为模态，`true` 时点击遮罩**不**关闭 | `boolean` | `false` |
+| `mask` | 是否显示遮罩层 | `boolean` | `true` |
+| `maskClassName` | 遮罩层自定义类名，仅 `mask=true` 时生效 | `string` | - |
+| `destroyOnHidden` | 关闭后是否销毁子节点 | `boolean` | `true` |
+| `zIndex` | 遮罩层层级，内容层自动加 1；优先于 Provider 基线 | `number` | `LingeeProvider.dialog.zIndex` |
+| `hostModal` | 宿主承载配置，见下方说明 | `DialogHostModal` | - |
+| `className` | 自定义类名 | `string` | - |
+| `style` | 自定义样式 | `CSSProperties` | - |
+
+`Dialog` **没有 `description` 属性**，说明文案直接写在 `children` 里。`description` 只属于 `Dialog.confirm(options)`。
 
 ### Dialog.confirm(options)
 
+类型为 `DialogConfirmOptions`，**继承 `Omit<DialogProps, "open" | "onOpenChange" | "children">`** ——
+上面 Dialog 表里除这三项外的属性都可用（`width` / `footer` / `okProps` / `modal` / `hostModal` 等）。
+以下是 confirm 独有或默认值不同的字段：
+
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
 | `title` | 标题 | `ReactNode` | - |
-| `description` | 描述内容 | `ReactNode` | - |
-| `content` | 自定义内容 | `ReactNode` | - |
+| `description` | 描述文案（使用默认布局时展示） | `ReactNode` | - |
+| `icon` | 标题前的图标（使用默认布局时展示） | `ReactNode` | - |
+| `content` | 自定义内容，传入后 `title` / `description` / `icon` 均不生效 | `ReactNode` | - |
+| `contentRender` | 动态内容渲染函数，参数含 `setOkDisabled` 可动态控制确认按钮 | `(props: ConfirmRenderProps) => ReactNode` | - |
 | `okText` | 确认按钮文本 | `string` | `"确定"` |
 | `cancelText` | 取消按钮文本 | `string` | `"取消"` |
 | `okDanger` | 确认按钮是否为危险样式 | `boolean` | `false` |
-| `icon` | 自定义图标 | `ReactNode` | - |
+| `maskClosable` | 点击遮罩是否关闭（按取消结算），**三态**，见下方说明 | `boolean` | 各承载方现状不一 |
 | `zIndex` | 本次确认框层级，优先于 Provider 基线 | `number` | `LingeeProvider.dialog.zIndex` |
 
+返回 `Promise<boolean>`，确认为 `true`、取消为 `false`。
+
+`maskClosable` 是三态字段，不传时各渲染方保持各自现状：本地渲染与浏览器内 webui 承载均为「点遮罩**不**关闭」，客户端原生确认框为「点遮罩关闭」。需要两端一致时显式传值。与 `modal` 同时出现时 `modal` 优先。
+
 ### Dialog.closeConfirm()
 
 强制关闭确认弹窗的兜底 API：**当前显示的一项与队列中排队的全部**按 `false` 结算，与旧实现的无条件清场语义一致，不额外调用 `onCancel`。

package/skill/references/components/drawer.md

@@ -39,4 +39,7 @@ export default function BasicDemo() {
 | `mask` | 是否显示遮罩 | `boolean` | `true` |
 | `modal` | 是否为模态模式 | `boolean` | `false` |
 | `footer` | 底部操作区 | `ReactNode` | - |
+| `extra` | 标题栏右侧额外内容 | `ReactNode` | - |
+| `destroyOnHidden` | 关闭后是否销毁子节点 | `boolean` | `true` |
+| `zIndex` | 自定义 z-index，优先于 Provider 基线 | `number` | - |
 | `children` | 内容区域 | `ReactNode` | - |

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/infinite-scroll.md

@@ -0,0 +1,74 @@
+# InfiniteScroll 无限滚动
+
+列表滚动到底部自动加载下一页，内置并发去重、首屏续拉与失败熔断
+
+- 导入：`import { InfiniteScroll } from "lingee-ui";`
+- 可用类型：`InfiniteScrollProps`, `InfiniteScrollTarget`
+
+## 最小示例
+
+```tsx
+import { useState } from "react";
+import { InfiniteScroll, ScrollArea } from "lingee-ui";
+
+/** 模拟分页请求 */
+function fetchPage(page: number): Promise<string[]> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(Array.from({ length: 10 }, (_, i) => `Item ${page * 10 + i + 1}`));
+    }, 600);
+  });
+}
+
+const TOTAL_PAGES = 3;
+
+export default function Basic() {
+  const [items, setItems] = useState<string[]>([]);
+  const [page, setPage] = useState(0);
+
+  const hasMore = page < TOTAL_PAGES;
+
+  const loadMore = async () => {
+    const next = await fetchPage(page);
+    setItems((prev) => [...prev, ...next]);
+    setPage((prev) => prev + 1);
+  };
+
+  return (
+    <ScrollArea fill style={{ height: 240 }}>
+      <div style={{ display: "flex", flexDirection: "column", gap: 8, padding: 12 }}>
+        {items.map((item) => (
+          <div
+            key={item}
+            style={{
+              padding: "8px 12px",
+              borderRadius: 8,
+              background: "var(--lg-g-bg-color-black-faint)",
+              color: "var(--lg-g-fg-color-black-strong)",
+            }}
+          >
+            {item}
+          </div>
+        ))}
+        <InfiniteScroll loadMore={loadMore} hasMore={hasMore} />
+      </div>
+    </ScrollArea>
+  );
+}
+```
+
+## API
+
+继承 `HTMLAttributes<HTMLDivElement>`（不含 `children`）。
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| loadMore | 加载下一页，必须返回 Promise。`isRetry` 为 true 表示由用户点击重试触发 | `(isRetry: boolean) => Promise<void>` | — |
+| hasMore | 是否还有更多数据，为 false 时停止观测并渲染「没有更多」态 | `boolean` | — |
+| threshold | 距容器底部多少像素时触发 | `number` | `80` |
+| scrollTarget | 显式指定滚动容器，缺省自动查找最近可滚动祖先 | `HTMLElement \| Window \| null \| (() => HTMLElement \| Window \| null)` | — |
+| loading | 加载中的自定义内容，传 `null` 则不渲染 | `ReactNode` | `Empty.Card` inline 加载态 |
+| noMore | 无更多数据时的自定义内容，传 `null` 则不渲染 | `ReactNode` | `Empty.Card` inline 空态 |
+| error | 加载失败时的自定义内容，函数形态可拿到重试句柄 | `ReactNode \| ((retry: () => void) => ReactNode)` | `Empty.Card` inline 错误态 + 重试 |
+| className | 自定义类名 | `string` | — |
+| style | 自定义行内样式 | `CSSProperties` | — |

package/skill/references/components/input.md

@@ -27,6 +27,7 @@ export default function BasicDemo() {
 | `error` | 错误状态 | `boolean` | `false` |
 | `disabled` | 禁用状态 | `boolean` | `false` |
 | `collapsed` | 折叠为正方形，仅展示单个插槽；受控，展开时机由 `onClick` 自行处理 | `boolean` | `false` |
+| `autoFocusOnExpand` | 折叠切换为展开时是否自动聚焦；布局驱动展开的场景传 `false` 自行控制聚焦时机 | `boolean` | `true` |
 | `onPressEnter` | 按下 Enter 键回调 | `(e: KeyboardEvent) => void` | - |
 | `placeholder` | 占位提示文字 | `string` | - |
 | `value` | 输入值（受控） | `string` | - |

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` | - |