lingee-ui 0.0.14 → 0.0.16

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

@@ -38,3 +38,5 @@ export default function BasicDemo() {
 | `error` | 是否显示错误状态 | `boolean` | `false` |
 | `placement` | 面板弹出方向 | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
 | `panelExtra` | 面板额外内容（如预设色板） | `ReactNode` | - |
+| `placeholder` | 占位文本 | `string` | - |
+| `onChangeComplete` | 拖拽结束回调，适合只在最终色值上触发请求的场景 | `(color: string) => void` | - |

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`。
@@ -80,6 +103,33 @@ export default function BasicDemo() {
 
 需要精确关闭某一个弹窗时，不要依赖这个全局 API，改由调用方自己控制触发时机。
 
+### HostModalPage
+
+宿主弹窗的承载页外壳，与 `Dialog` 的 `hostModal` 配对使用。负责取参、上报就绪、回传结果与关窗。
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `children` | 内容渲染函数，收到入参与 `close` | `(params, close) => ReactNode` | - |
+| `fallback` | 无入参时的兜底（页面被直接访问） | `ReactNode` | `null` |
+| `ready` | 内容是否就绪，`false` 时保留宿主 loading 占位 | `boolean` | `true` |
+| `header` | 自绘头部，配合发起端 `hostModal.headless` | `(close) => ReactNode` | - |
+| `closable` | 是否渲染内置关闭按钮（面板右上角） | `boolean` | 发起端开 `headless` 且未传 `header` 时 `true`，否则 `false` |
+| `className` | 容器类名，用于控制内边距等业务样式 | `string` | - |
+
+`closable` 存在的原因：发起端开 `headless` 后宿主不再提供关闭入口，而设计稿常把关闭按钮画在内容区右上角、并不需要一整个自绘头部。内置按钮复用 `.lg-dialog__close` 取样式，因此同一份内容组件在本地 `Dialog` 与宿主承载两种形态下按钮位置一致，业务侧不必写两套。
+
+默认值按「宿主有没有提供关闭入口」自动判定，业务通常无需传值：
+
+- 发起端开了 `headless` → 宿主不画标题栏与关闭按钮，本组件补上；
+- 发起端未开 `headless` → 宿主标题栏自带关闭按钮，不再叠加；
+- 传了 `header` → 自绘头部通常已含关闭入口，同样不叠加，确有需要可显式传 `true`。
+
+`headless` 状态由发起端经承载页路由的内部 query 参数传来（`Dialog` 的 `hostModal.headless` 自动挂上）。两条承载通道的取参协议只回业务入参、不带外壳信息，承载页无从自行判断，故走 URL 捎带。该参数属实现细节，业务不应读写。
+
+按钮在承载页内为 `fixed` 定位 —— 承载页容器自身可滚动，`absolute` 会让按钮随内容滚出视口，而承载页的视口就是弹窗面板，`fixed` 与「面板右上角」等价。
+
+按钮在承载页内为 `fixed` 定位 —— 承载页容器自身可滚动，`absolute` 会让按钮随内容滚出视口，而承载页的视口就是弹窗面板，`fixed` 与「面板右上角」等价。
+
 ### 面板高度与视口
 
 `height` 与 `maxHeight` 都是**面板总高**（含 68px 标题栏），不是内容区高度。

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

@@ -3,7 +3,7 @@
 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。
 
 - 导入：`import { Empty, EmptyCard } from "lingee-ui";`
-- 可用类型：`EmptyProps`, `EmptySize`, `EmptyIconComponent`, `EmptyCardProps`, `EmptyCardStatus`, `EmptyCardVariant`, `EmptyCardSpacing`
+- 可用类型：`EmptyProps`, `EmptySize`, `EmptyIconComponent`, `EmptyCardProps`, `EmptyCardStatus`, `EmptyCardVariant`, `EmptyCardSpacing`, `EmptyCardAlign`
 
 ## 最小示例
 
@@ -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` | - |
 
@@ -37,6 +37,7 @@ export default function BasicDemo() {
 | `size` | 尺寸，语义同 `Empty`，透传给内部 `Empty` | `"sm" \| "md" \| "lg"` | `"sm"` |
 | `variant` | 留白密度：`block` 区块级 / `inline` 行内轻量 | `"block" \| "inline"` | `"block"` |
 | `spacing` | 留白档位。`loose` 为顶部大留白（列表级空态） | `"none" \| "normal" \| "loose"` | `"normal"` |
+| `align` | 水平对齐。`start` 用于列表内嵌占位，与上方列表项同一阅读起点；只管对齐不含缩进，需要缩进时由消费方在外层补 `padding` | `"center" \| "start"` | `"center"` |
 | `onRetry` | 重试回调。仅 `status="error"` 生效，传入后整体可点击，并自动追加主题色「重试」 | `() => void` | - |
 | `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

@@ -4,7 +4,7 @@
 
 - 导入：`import { Popover, PopoverTrigger, PopoverAnchor, PopoverContent, PopoverArrow, PopoverClose } from "lingee-ui";`
 - 按需导入：`import { Popover } from "lingee-ui/popover";`
-- 可用类型：`PopoverProps`, `PopoverTriggerProps`, `PopoverAnchorProps`, `PopoverContentProps`, `PopoverArrowProps`, `PopoverCloseProps`, `PopoverPlacement`
+- 可用类型：`PopoverTriggerAction`, `PopoverProps`, `PopoverTriggerProps`, `PopoverAnchorProps`, `PopoverContentProps`, `PopoverArrowProps`, `PopoverCloseProps`, `PopoverPlacement`
 
 ## 最小示例
 
@@ -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>
@@ -29,17 +29,32 @@ export default function BasicDemo() {
 
 ### Popover
 
-| 属性 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| `open` | 受控打开状态 | `boolean` | - |
-| `onOpenChange` | 打开状态变化回调 | `(open: boolean) => void` | - |
-| `modal` | 是否为模态模式 | `boolean` | `false` |
-| `children` | 子元素（Trigger + Content） | `ReactNode` | - |
+| 属性              | 说明                                         | 类型                      | 默认值    |
+| ----------------- | -------------------------------------------- | ------------------------- | --------- |
+| `open`            | 受控打开状态                                 | `boolean`                 | -         |
+| `defaultOpen`     | 非受控默认打开状态                           | `boolean`                 | -         |
+| `onOpenChange`    | 打开状态变化回调                             | `(open: boolean) => void` | -         |
+| `modal`           | 是否为模态模式                               | `boolean`                 | `false`   |
+| `trigger`         | 打开方式                                     | `"click" \| "hover"`      | `"click"` |
+| `mouseEnterDelay` | `trigger="hover"` 时指针进入后延迟打开（ms） | `number`                  | `100`     |
+| `mouseLeaveDelay` | `trigger="hover"` 时指针离开后延迟关闭（ms） | `number`                  | `100`     |
+| `children`        | 子元素（Trigger + Content）                  | `ReactNode`               | -         |
 
 ### 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/sidebar.md

@@ -2,8 +2,8 @@
 
 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。
 
-- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarFolderNode, SidebarFolderSection, 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`, `SidebarFolderNodeProps`, `SidebarFolderSectionProps`, `SidebarFolderStatus`, `SidebarFolderStatusText`, `SidebarFooterProps`, `SidebarFooterUserProps`, `SidebarFooterMenuStaticRowProps`, `SidebarFooterBadgeProps`, `SidebarUsageBarProps`, `SidebarUsageTone`, `SidebarUsagePanelProps`, `SidebarUsagePanelSectionProps`
+- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarStickyHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarFolderNode, SidebarFolderSection, 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`, `SidebarStickyHeaderProps`, `SidebarTabBarProps`, `SidebarTabItem`, `SidebarNavItemProps`, `SidebarCollapsibleNavItemProps`, `SidebarCollapsibleNavItemChild`, `SidebarCaretTone`, `SidebarGroupHeaderProps`, `SidebarListItemProps`, `SidebarIndicatorType`, `SidebarCollapsibleListItemProps`, `SidebarCaretPlacement`, `SidebarFolderNodeProps`, `SidebarFolderSectionProps`, `SidebarFolderStatus`, `SidebarFolderStatusText`, `SidebarFooterProps`, `SidebarFooterUserProps`, `SidebarFooterMenuStaticRowProps`, `SidebarFooterBadgeProps`, `SidebarUsageBarProps`, `SidebarUsageTone`, `SidebarUsagePanelProps`, `SidebarUsagePanelSectionProps`
 
 ## 最小示例
 
@@ -73,6 +73,15 @@ export default function BasicDemo() {
 |------|------|------|--------|
 | `children` | 内容 | `ReactNode` | - |
 
+### Sidebar.StickyHeader
+
+继承原生 `div` 属性。必须作为滚动容器的直接子元素，才能相对该容器吸顶。
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `children` | 占满剩余宽度的主内容 | `ReactNode` | - |
+| `actions` | 固定在右侧的操作区 | `ReactNode` | - |
+
 ### Sidebar.TabBar
 
 | 属性 | 说明 | 类型 | 默认值 |
@@ -103,6 +112,7 @@ export default function BasicDemo() {
 | `icon` | 左侧图标 | `ReactNode` | - |
 | `label` | 分组标题 | `ReactNode` | - |
 | `active` | 头部高亮。内部与子项 active 互斥 | `boolean` | `false` |
+| `caretTone` | 箭头视觉层级。`muted` 叠加弱化透明度，`default` 保留语义色完整不透明度 | `"muted" \| "default"` | `"muted"` |
 | `open` | 受控展开态 | `boolean` | - |
 | `defaultOpen` | 非受控初始展开态 | `boolean` | `false` |
 | `onOpenChange` | 展开态变化回调 | `(next: boolean) => void` | - |

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