lingee-ui 0.0.9 → 0.0.11

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { B as ButtonProps } from './index-7pb5YOcq.mjs';
-export { a as Button, b as ButtonShape, c as ButtonSize, d as ButtonVariant } from './index-7pb5YOcq.mjs';
+import { B as ButtonProps } from './index-89atTLPD.mjs';
+export { a as Button, b as ButtonShape, c as ButtonSize, d as ButtonVariant } from './index-89atTLPD.mjs';
 import * as React$1 from 'react';
 import React__default, { ReactNode, CSSProperties, HTMLAttributes, MouseEvent, ComponentType, Key, ReactElement, UIEventHandler, Ref } from 'react';
 import { TooltipProps } from './tooltip/index.mjs';
 export { Tooltip, TooltipPlacement } from './tooltip/index.mjs';
-export { TabItem, Tabs, TabsProps, TabsSize, TabsVariant } from './tabs/index.mjs';
+export { TabItem, Tabs, TabsOverflow, TabsProps, TabsScrollOptions, TabsSize, TabsVariant } from './tabs/index.mjs';
 import { PopoverContentProps } from './popover/index.mjs';
 export { Popover, PopoverAnchor, PopoverAnchorProps, PopoverArrow, PopoverArrowProps, PopoverClose, PopoverCloseProps, PopoverContent, PopoverPlacement, PopoverProps, PopoverTrigger, PopoverTriggerProps } from './popover/index.mjs';
 export { Switch, SwitchProps, SwitchSize } from './switch/index.mjs';
@@ -70,6 +70,39 @@ interface EllipsisTooltipProps extends Omit<TooltipProps, "children" | "content"
  */
 declare const EllipsisTooltip: React__default.ForwardRefExoticComponent<EllipsisTooltipProps & React__default.RefAttributes<HTMLElement>>;
 
+/**
+ * site 全局配置
+ *
+ * `Dialog.confirm` 等命令式 API 不在 React 树内，读不到 Provider 的 context，
+ * 因此 LingeeProvider 把 site 同步写入这个模块级变量供它们读取。
+ *
+ * site 用于开启仅特定宿主环境需要的集成能力，默认关闭，
+ * 其它项目使用组件库时行为不变。
+ *
+ * ── 为什么不是单个变量，而是一份带深度的注册表 ──
+ *
+ * Provider 可能嵌套（如文档站给个别隐藏页单独开 site，外层保持关闭），
+ * 也可能在运行时卸载（微前端子应用退出）。单变量 + 无条件覆盖会有两个问题：
+ *
+ *   1. **外层重渲染冲掉内层的值**。两层 Provider 首次渲染时内层后跑、值正确，
+ *      但外层此后任何一次重渲染（切语言、切主题）都会把它写回自己的值，
+ *      而 React 不一定跟着重渲内层。表现为代理能力时好时坏，复现条件隐蔽。
+ *   2. **卸载后值残留**。Provider 卸载了 site 还留着，后续命令式调用
+ *      仍按宿主环境走。
+ *
+ * 改为按实例注册，并记录每个实例在 React 树中的**深度**：
+ * 生效值取深度最大者，即最内层，与 context 的语义一致。
+ *
+ * 为什么用深度而非「最后注册者」：注册顺序在重渲染与卸载后会乱。
+ * 例如内层卸载后外层重渲染，Map 里外层反而成了最后一个 —— 恰好正确；
+ * 但若外层先重渲染再挂载另一个内层，顺序又反了。深度是结构属性，不受时序影响。
+ *
+ * 为什么用 Map 而非计数器：render 期的调用可能被 React 丢弃或重复执行
+ * （并发渲染、严格模式二次调用），计数会漂移；按 token 覆盖写入则天然幂等。
+ */
+/** 组件库运行宿主标识。lingee = 运行在 lingee 客户端 webview 内 */
+type LingeeSite = 'lingee';
+
 /**
  * 中文语言包（默认语言）
  * 按组件名为 key 组织翻译文案
@@ -84,6 +117,8 @@ declare const zhCN: {
     Select: {
         loading: string;
         loadError: string;
+        /** 传入 onRetry 时使用：引导语由 Empty.Card 统一追加，此处不含「请重试」 */
+        loadFailed: string;
         notFound: string;
         clear: string;
     };
@@ -97,6 +132,13 @@ declare const zhCN: {
         scrollLeft: string;
         scrollRight: string;
     };
+    Carousel: {
+        carousel: string;
+        prev: string;
+        next: string;
+        /** {page} 为页码，从 1 开始 */
+        goToPage: string;
+    };
     Form: {
         /** {label} 为表单项名称 */
         required: string;
@@ -172,6 +214,10 @@ declare const zhCN: {
     Spin: {
         loading: string;
     };
+    Empty: {
+        /** 错误态传入 onRetry 后，固定追加在 description 之后的重试引导 */
+        retry: string;
+    };
 };
 
 /** 语言包类型，由 zh-CN 推导结构 */
@@ -179,6 +225,18 @@ type Locale = typeof zhCN;
 interface LingeeProviderProps {
     /** 语言包，默认中文 */
     locale?: Locale;
+    /**
+     * 运行宿主标识，默认不传。
+     *
+     * 传 "lingee" 表示应用运行在 lingee 客户端 webview 内，开启宿主集成能力：
+     * `Dialog.confirm` 与设置了 `lingeeRoute` 的 `Dialog` 会改由客户端渲染，
+     * 使遮罩能覆盖客户端侧边栏（webview 内的遮罩只能盖住 webview 视口）。
+     *
+     * 不传即保持纯前端行为，其它项目接入组件库不受影响。
+     * 注意：即使传了 lingee，浏览器环境下因取不到 lingeeBridge 也会自动回退本地渲染，
+     * 因此无需按环境条件传值。
+     */
+    site?: LingeeSite;
     children: ReactNode;
 }
 
@@ -196,6 +254,7 @@ declare const enUS: {
     Select: {
         loading: string;
         loadError: string;
+        loadFailed: string;
         notFound: string;
         clear: string;
     };
@@ -209,6 +268,12 @@ declare const enUS: {
         scrollLeft: string;
         scrollRight: string;
     };
+    Carousel: {
+        carousel: string;
+        prev: string;
+        next: string;
+        goToPage: string;
+    };
     Form: {
         required: string;
         requiredNoLabel: string;
@@ -282,6 +347,9 @@ declare const enUS: {
     Spin: {
         loading: string;
     };
+    Empty: {
+        retry: string;
+    };
 };
 
 /**
@@ -299,7 +367,7 @@ declare const enUS: {
  * </LingeeProvider>
  * ```
  */
-declare function LingeeProvider({ locale, children }: LingeeProviderProps): react_jsx_runtime.JSX.Element;
+declare function LingeeProvider({ locale, site, children }: LingeeProviderProps): react_jsx_runtime.JSX.Element;
 declare namespace LingeeProvider {
     var displayName: string;
 }
@@ -311,6 +379,10 @@ declare function useLocale(): Locale;
  * 获取指定组件的语言包片段
  */
 declare function useComponentLocale<K extends keyof Omit<Locale, "locale">>(componentName: K): Locale[K];
+/**
+ * 获取当前接入方标识（React 组件内使用；命令式场景用 site-config 的 getSite）
+ */
+declare function useSite(): LingeeSite | undefined;
 
 /** 预设语义色 */
 type TagPresetColor = "primary" | "info" | "success" | "warning" | "danger" | "amber" | "yellow" | "cyan" | "purple";
@@ -354,14 +426,100 @@ declare const Tag: React__default.ForwardRefExoticComponent<TagProps & React__de
 
 /** 透传给 OK/Cancel 按钮的属性子集（排除 children 和事件，由 Dialog 统一管理） */
 type DialogButtonProps = Omit<ButtonProps, "children" | "onClick" | "htmlType">;
+/**
+ * 宿主弹窗配置
+ *
+ * 承载容器（客户端 webview / 被嵌的 iframe）内渲染的遮罩只能覆盖容器视口，
+ * 盖不住外层的侧边栏。传入本配置后，Dialog 在这类环境中不再本地渲染，
+ * 而是请求宿主在更外层开窗、加载 `route` 指向的独立路由页，遮罩即可覆盖整个宿主视口。
+ *
+ * 三条路径的选择由组件库内部完成（见 host-modal.ts）：
+ *  - 被 iframe 嵌套 → postMessage 请父窗口承载（端上父窗口会再转给客户端）
+ *  - 客户端 webview 顶层（需 site="lingee"）→ 直连 lingeeBridge
+ *  - 浏览器顶层、或宿主拒绝承载 → 本地渲染 `children`
+ *
+ * 调用方无需分支判断，但 `children` 必须写上 —— 那是回退路径的内容。
+ *
+ * 尺寸无需单独配置：宽度取 Dialog 的 `width`；`height` / `maxHeight` 是面板总高，
+ * 直接沿用本地 Dialog 的尺寸。只有显式 `contentHeight` 表示纯内容区高度，
+ * 常规模式由组件库补上宿主标题栏的 68px，headless 模式不补。
+ */
+interface DialogHostModal {
+    /** 应用内绝对路径，如 "/host-modal/skill-detail"；宿主会拼上当前页 origin */
+    route: string;
+    /** 业务入参，经宿主内存传递，不落 URL；须可结构化克隆 */
+    params?: unknown;
+    /**
+     * 不要宿主的标题栏，头部由承载页自绘（默认 false）。
+     *
+     * 宿主标题栏只能显示一行纯文本 + 右上角关闭按钮。头部较复杂的弹窗
+     * （带图标、副标题、右侧操作、Tab 等）用它关掉，自己在承载页里画
+     * （配合 `HostModalPage` 的 `header`）。
+     *
+     * 两点后果：
+     * 1. **关闭按钮一并消失**（它长在标题栏上）。承载页必须自备关闭入口调
+     *    `closeHostModal()`，否则用户只能点遮罩关闭。
+     * 2. `contentHeight` 不再叠加标题栏的 68px，内容区高度就是面板总高。
+     *    `height` / `maxHeight` 无论是否 headless，始终表示面板总高。
+     *
+     * 回退路径（浏览器顶层）不受影响：那条渲染 Dialog 自己的外壳，
+     * 标题栏由 `title` / `closable` 控制。
+     */
+    headless?: boolean;
+    /**
+     * 纯内容区高度，优先于 Dialog 的 `height` / `maxHeight`。
+     *
+     * 宿主开窗必须在开窗前拿到确定像素值，而部分弹窗的高度是由 CSS 控制的
+     * （如 `max-height: 85vh`），组件库读不到。此时用本字段告知内容区高度即可：
+     * 有宿主标题栏时自动加 68px，headless 时直接作为面板总高。
+     */
+    contentHeight?: number;
+    /**
+     * 点击宿主遮罩是否关闭弹窗。
+     *
+     * **三态字段**：
+     *  - 不传 → 沿用宿主的既有默认值（浏览器 webui 与客户端都是「可点遮罩关闭」）
+     *  - `true` / `false` → 宿主一律按此值
+     *
+     * 为什么不复用 Dialog 的 `modal`：`modal` 只作用于本地渲染的外壳，且极性相反
+     * （`modal: true` 等于「不可关」）。宿主承载时组件库整个不产出 DOM，`modal`
+     * 到不了宿主；而把它顺带映射过去，会让 `Dialog.confirm` 那些默认 `modal: true`
+     * 的存量调用点在端上突然变成「点遮罩关不掉」—— 那是行为变更，不是补能力。
+     * 因此新增独立字段，只在显式声明时生效。
+     *
+     * ⚠️ 只管遮罩点击。Esc 与宿主标题栏的关闭按钮仍能关闭弹窗；
+     * `headless` 时没有关闭按钮，此处再传 `false` 会让弹窗只剩 Esc 可退出，
+     * 承载页必须自绘关闭入口。
+     *
+     * ⚠️ 旧客户端不认识该字段，会静默忽略并保持「可点遮罩关闭」。
+     * 若用它防止表单被误关，端上灰度期内防不住。
+     */
+    maskClosable?: boolean;
+    /**
+     * 宿主弹窗关闭时回调。
+     * @param result 承载页通过 `closeHostModal` 回传的业务结果；用户直接关窗时为 undefined
+     */
+    onResult?: (result?: unknown) => void;
+}
 interface DialogProps {
     /** 是否打开 */
     open: boolean;
     /** 状态变化回调（关闭时 nextOpen=false） */
     onOpenChange: (open: boolean) => void;
+    /**
+     * 宿主弹窗配置。
+     *
+     * 传入后，在有外层容器的环境中（客户端 webview / 被 iframe 嵌套）本组件不渲染
+     * 任何 DOM，改由宿主开窗承载 `route` 路由页；浏览器顶层或宿主拒绝时自动回退
+     * 为本地渲染，`children` 照常生效。
+     *
+     * 客户端 webview 那条路径需 LingeeProvider 设置 site="lingee"；
+     * iframe 那条不需要（被嵌的第三方页面拿不到该配置）。
+     */
+    hostModal?: DialogHostModal;
     /** 弹窗宽度，默认 460 */
     width?: number | string;
-    /** 弹窗高度，默认自适应内容 */
+    /** 弹窗面板总高，默认自适应内容 */
     height?: number | string;
     /** 标题（支持 ReactNode） */
     title?: ReactNode;
@@ -395,7 +553,7 @@ interface DialogProps {
     destroyOnHidden?: boolean;
     /** 自定义 z-index */
     zIndex?: number;
-    /** 内容区最大高度，默认 640px */
+    /** 弹窗面板总高上限，默认 640px */
     maxHeight?: number | string;
     /** 开启后 body 高度跟随内容自适应，弹窗整体高度由 maxHeight 兜底上限，默认 false */
     autoHeight?: boolean;
@@ -413,6 +571,25 @@ interface ConfirmRenderProps {
 }
 /** Dialog.confirm 命令式参数 */
 interface DialogConfirmOptions extends Omit<DialogProps, "open" | "onOpenChange" | "children"> {
+    /**
+     * 点击遮罩是否关闭确认框（按取消结算）。
+     *
+     * **三态字段**，不传时各渲染方保持各自现状 —— 这条链路的既有默认值本就不一致：
+     *
+     * | 渲染方 | 不传时的行为 |
+     * |---|---|
+     * | 本地渲染（`modal ?? true`） | 点遮罩**不**关闭 |
+     * | 浏览器里由 webui 承载 | 点遮罩**不**关闭（同样是本地 `Dialog.confirm`） |
+     * | 客户端原生确认框 | 点遮罩关闭，按取消结算 |
+     *
+     * 没有把端上拉平到「不关闭」：那会改变所有走代理的存量确认框行为，
+     * 而 webui 侧 `Dialog.confirm` 调用点有三十余处，收益不抵回归成本。
+     * 需要两端一致时显式传值即可 —— 显式传值会**同时**约束本地渲染与宿主，
+     * 这也是它与 `modal` 分开的原因：`modal` 只影响本地外壳且极性相反。
+     *
+     * 与 `modal` 同时出现时 `modal` 优先（它是更早的本地专用参数，不破坏既有代码）。
+     */
+    maskClosable?: boolean;
     /** 描述文案（使用默认布局时展示） */
     description?: ReactNode;
     /** 标题前的图标（使用默认布局时展示） */
@@ -429,14 +606,83 @@ interface DialogConfirmOptions extends Omit<DialogProps, "open" | "onOpenChange"
  */
 declare const Dialog$1: React__default.FC<DialogProps>;
 
-/**
- * 命令式确认弹窗
- * @returns Promise<boolean> — 确认返回 true，取消返回 false
- */
 declare function confirm(options: DialogConfirmOptions): Promise<boolean>;
 /** 命令式关闭当前 confirm 弹窗（不 resolve，用于外部强制关闭兜底） */
 declare function closeConfirm(): void;
 
+/** 当前页面是否运行在宿主弹窗内（含端侧 webview 与浏览器 iframe 两种承载） */
+declare function isInHostModal(): boolean;
+/**
+ * 读取宿主传入的业务入参（同步）。
+ *
+ * 仅端侧承载可用 —— 那边是同步 IPC。浏览器 iframe 承载下必然返回 null，
+ * 需要用 `HostModalPage`（内部走异步通道）。
+ */
+declare function getHostModalParams<T = unknown>(): T | null;
+/**
+ * 通知宿主内容已渲染，据此撤掉 loading 占位。
+ *
+ * 不能让宿主依赖容器的加载事件：那只表示 DOM 结构就绪，
+ * 此时 SPA 的 JS 还没执行完、React 未挂载、页面是空白的，
+ * 过早撤 loading 会露出一段白屏。
+ */
+declare function notifyHostModalReady(): void;
+/** 关闭宿主弹窗并回传业务结果 */
+declare function closeHostModal(result?: unknown): void;
+interface HostModalPageProps<P> {
+    /**
+     * 内容渲染函数。
+     * @param params 宿主传入的业务入参
+     * @param close  回传结果并关窗
+     */
+    children: (params: P, close: (result?: unknown) => void) => React__default.ReactNode;
+    /**
+     * 无入参时的兜底渲染（页面被直接访问、或开发期无宿主）。
+     * 不提供则渲染 null。
+     */
+    fallback?: React__default.ReactNode;
+    /**
+     * 内容是否已就绪。
+     *
+     * 缺省 true —— 入参由宿主给出，拿到即等于内容可见。
+     * 若业务页还需等接口，传入 `!loading` 让 loading 占位保留到数据到位，
+     * 避免撤早了露出骨架或空列表。
+     *
+     * ⚠️ 注意宿主有 8 秒兜底超时，超时会切「连接失败」错误态。
+     * 接口可能慢过 8 秒的页面建议先渲染骨架并立即上报，数据到位后局部刷新。
+     */
+    ready?: boolean;
+    /**
+     * 自绘头部内容，配合发起端的 `hostModal.headless` 使用。
+     *
+     * 发起端开了 `headless` 后宿主不再渲染标题栏与关闭按钮，头部由这里提供。
+     * 渲染函数收到 `close`，用于绘制自己的关闭按钮。
+     *
+     * 只传本属性不会让宿主去掉标题栏 —— 那由发起端的 `headless` 决定。
+     * 两处不匹配的后果：发起端开了而这里没传 → 弹窗没有任何关闭入口（只能点遮罩）；
+     * 这里传了而发起端没开 → 宿主标题栏与自绘头部上下叠两层。
+     */
+    header?: (close: (result?: unknown) => void) => React__default.ReactNode;
+    /** 附加到容器上的类名，用于控制内边距等业务样式 */
+    className?: string;
+}
+/**
+ * 宿主弹窗承载页外壳。
+ *
+ * @example
+ * export default function SkillDetailModalPage() {
+ *   return (
+ *     <HostModalPage<{ skill: Skill }> className="my-modal" fallback={<Navigate to="/skills" replace />}>
+ *       {({ skill }, close) => <SkillDetailContent skill={skill} onUse={() => close({ type: 'use' })} />}
+ *     </HostModalPage>
+ *   );
+ * }
+ */
+declare function HostModalPage<P = unknown>({ children, fallback, ready, header, className, }: HostModalPageProps<P>): react_jsx_runtime.JSX.Element | null;
+declare namespace HostModalPage {
+    var displayName: string;
+}
+
 type DialogType = typeof Dialog$1 & {
     confirm: typeof confirm;
     closeConfirm: typeof closeConfirm;
@@ -503,8 +749,14 @@ interface SelectProps<T = string> {
     onSearch?: (keyword: string) => void;
     /** 加载中状态（远程搜索时展示 loading） */
     loading?: boolean;
-    /** 加载失败状态（下拉面板展示「加载失败，请重试」缺省） */
+    /** 加载失败状态（下拉面板展示加载失败缺省） */
     loadError?: boolean;
+    /**
+     * 加载失败后的重试回调。
+     * 传入后 loadError 缺省态可点击，并在文案后追加「重试」；
+     * 不传则为纯提示（此时 loadError 文案自带「请重试」引导）
+     */
+    onRetry?: () => void;
     /** 禁用 */
     disabled?: boolean;
     /** 错误态 */
@@ -541,6 +793,20 @@ declare const Select: <T = string>(props: SelectProps<T> & {
     ref?: React__default.Ref<HTMLDivElement>;
 }) => React__default.ReactElement | null;
 
+/**
+ * 菜单项文本的溢出提示开关。
+ *
+ * 不传时行为与此前完全一致（文本撑开面板，不打点也不弹提示）。
+ * 传入后文本带默认最大宽度并单行截断，**仅在真正被截断时**悬浮显示完整内容，
+ * 未截断不弹（由 EllipsisTooltip 在 hover 时实时测量决定）。
+ *
+ * - `true`：取 `label` / `children` 作为提示内容。内容为 JSX 时会整块塞进浮层，
+ *   这类场景应显式传 ReactNode 指定纯文本
+ * - `ReactNode`：以其作为提示内容
+ *
+ * 最大宽度默认 240px，可通过 `--lg-dropdown-label-max-width` 覆盖。
+ */
+type DropdownEllipsisTooltip = boolean | ReactNode;
 interface DropdownMenuItemData {
     type?: "item";
     /** 唯一标识 */
@@ -557,6 +823,8 @@ interface DropdownMenuItemData {
     disabled?: boolean;
     /** 选中回调 */
     onSelect?: (event: Event) => void;
+    /** 文本溢出时悬浮显示完整内容，详见 DropdownEllipsisTooltip */
+    ellipsisTooltip?: DropdownEllipsisTooltip;
 }
 interface DropdownSeparatorData {
     type: "separator";
@@ -680,6 +948,8 @@ interface DropdownItemProps {
     selected?: boolean;
     /** 选中回调，调用 event.preventDefault() 可阻止面板自动关闭 */
     onSelect?: (event: Event) => void;
+    /** 文本溢出时悬浮显示完整内容，详见 DropdownEllipsisTooltip */
+    ellipsisTooltip?: DropdownEllipsisTooltip;
 }
 interface DropdownCheckboxItemProps {
     /** 菜单项内容 */
@@ -694,6 +964,8 @@ interface DropdownCheckboxItemProps {
     icon?: ReactNode;
     /** 选中状态变化回调 */
     onCheckedChange?: (checked: boolean) => void;
+    /** 文本溢出时悬浮显示完整内容，详见 DropdownEllipsisTooltip */
+    ellipsisTooltip?: DropdownEllipsisTooltip;
 }
 interface DropdownRadioGroupProps {
     /** 子元素（DropdownRadioItem） */
@@ -714,6 +986,8 @@ interface DropdownRadioItemProps {
     disabled?: boolean;
     /** 前置图标 */
     icon?: ReactNode;
+    /** 文本溢出时悬浮显示完整内容，详见 DropdownEllipsisTooltip */
+    ellipsisTooltip?: DropdownEllipsisTooltip;
 }
 interface DropdownLabelProps {
     /** 标题内容 */
@@ -753,10 +1027,22 @@ interface DropdownSubTriggerProps {
      * 用于「展开时才拉取数据」这类懒加载场景
      */
     onMouseEnter?: React__default.MouseEventHandler<HTMLDivElement>;
+    /** 文本溢出时悬浮显示完整内容，详见 DropdownEllipsisTooltip */
+    ellipsisTooltip?: DropdownEllipsisTooltip;
 }
 interface DropdownSubContentProps extends Pick<PopoverContentProps, "side" | "align" | "sideOffset" | "alignOffset" | "className" | "collisionPadding" | "container"> {
     /** 子菜单面板内容 */
     children: ReactNode;
+    /**
+     * 面板自定义样式
+     * - maxHeight: 面板高度上限，超出时内置 ScrollArea 滚动。
+     *   不传时仅以视口可用空间为界（子菜单承载的内容形态差异大，
+     *   统一给固定上限会截断设计高度更大的自定义面板）
+     * - width / minWidth 等其它 CSS 属性均可使用
+     */
+    style?: CSSProperties;
+    /** 固定在面板底部的内容（不随列表滚动），与 DropdownContent 同口径 */
+    footer?: ReactNode;
 }
 interface DropdownButtonProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
     /** 按钮文本内容 */
@@ -1213,22 +1499,33 @@ interface EmptyProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
  */
 type EmptyCardStatus = "loading" | "empty" | "error";
 /**
- * 布局形态。
- * - block: 块级居中，用于区块级占位
- * - inline: 行内小字，用于「加载更多」这类轻量提示
+ * 密度形态。仅影响留白，图标与文字尺寸由 size 决定。
+ * - block: 区块级占位，留白按 spacing 档位给足
+ * - inline: 行内轻量提示（如「加载更多」），上下留白收紧、左右补 12px
  */
 type EmptyCardVariant = "block" | "inline";
 /** 上下留白档位 */
 type EmptyCardSpacing = "none" | "normal" | "loose";
-interface EmptyCardProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onClick"> {
+interface EmptyCardProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onClick" | "size"> {
     status: EmptyCardStatus;
     /** 描述文案。组件不内置文案，由消费方传入 */
     description: ReactNode;
     /** 覆盖默认图标；传 null 则不渲染图标 */
     icon?: ReactNode | null;
+    /**
+     * 尺寸，默认 "sm"。语义与 Empty 的 size 一致，内部直接透传：
+     * - sm: 图标 16px + 文字 12px，横向排列（占位场景默认值）
+     * - md: 图标 24px + 文字 14px，纵向排列
+     * - lg: 图标 56px + 文字 16px，纵向排列
+     */
+    size?: EmptySize;
     variant?: EmptyCardVariant;
     spacing?: EmptyCardSpacing;
-    /** 重试回调。仅 status="error" 时生效，传入后整体渲染为可点击按钮 */
+    /**
+     * 重试回调。仅 status="error" 时生效。
+     * 传入后整体渲染为可点击按钮：带浅色底 + hover 反馈，
+     * 并在 description 之后自动追加主题色「重试」（文案取自 locale，无需消费方拼接）
+     */
     onRetry?: () => void;
     className?: string;
     style?: CSSProperties;
@@ -1237,12 +1534,11 @@ interface EmptyCardProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"
 /**
  * Empty.Card — 等高三态占位
  *
- * 统一「加载中 / 加载结束空 / 加载结束失败」三态：图标 + 文案横向排列，
- * 同一 spacing 档位下三态 min-height 一致，状态切换时容器高度不变，
- * 避免列表或卡片区域跳动。
+ * 统一「加载中 / 加载结束空 / 加载结束失败」三态：同一 size + spacing 档位下
+ * 三态 min-height 一致，状态切换时容器高度不变，避免列表或卡片区域跳动。
  *
- * 收敛为单组件的原因：这类占位在列表与折叠区块内散落出现十余处，
- * 各处自行拼装会导致图标尺寸、间距、灰度层层漂移。
+ * 图标与文案的排版直接复用 Empty（size 透传），本组件只额外负责三件事：
+ * 等高约束、重试交互、状态无障碍播报。
  */
 declare const EmptyCard: React__default.ForwardRefExoticComponent<EmptyCardProps & React__default.RefAttributes<HTMLDivElement>>;
 
@@ -1252,8 +1548,8 @@ declare const EmptyCard: React__default.ForwardRefExoticComponent<EmptyCardProps
  * 用 Object.assign 而非对象字面量挂载子组件：
  * 保留 EmptyRoot 的 forwardRef 类型，使 <Empty ref={...} /> 仍可直接使用。
  */
-declare const Empty: React__default.ForwardRefExoticComponent<EmptyProps & React__default.RefAttributes<HTMLDivElement>> & {
-    Card: React__default.ForwardRefExoticComponent<EmptyCardProps & React__default.RefAttributes<HTMLDivElement>>;
+declare const Empty: React$1.ForwardRefExoticComponent<EmptyProps & React$1.RefAttributes<HTMLDivElement>> & {
+    Card: React$1.ForwardRefExoticComponent<EmptyCardProps & React$1.RefAttributes<HTMLDivElement>>;
 };
 
 /** 附件/截图元信息 */
@@ -2706,6 +3002,10 @@ interface FileItemActions {
     /** 重新上传 */
     retry: () => void;
 }
+/** 上传请求方法 */
+type UploadMethod = "POST" | "PUT" | "PATCH" | "post" | "put" | "patch";
+/** beforeUpload 允许的返回值：false 阻止上传，File/Blob 替换待传文件 */
+type BeforeUploadReturn = boolean | void | File | Blob;
 interface UploadProps {
     /** 接受的文件 MIME 类型，如 "image/*,.pdf" */
     accept?: string;
@@ -2717,6 +3017,11 @@ interface UploadProps {
     multiple?: boolean;
     /** 是否渲染拖拽上传区域 */
     drag?: boolean;
+    /**
+     * 是否选择文件夹。开启后点击选择目录，拖拽时递归遍历子目录，
+     * 并强制按 `accept` 过滤（目录内文件不经过选择器，无法靠原生 accept 拦截）。
+     */
+    directory?: boolean;
     /** 禁用状态 */
     disabled?: boolean;
     /** 受控文件列表 */
@@ -2731,6 +3036,28 @@ interface UploadProps {
      * 由消费方在提交时自行携带。
      */
     customRequest?: (options: CustomRequestOptions) => CustomRequestReturn | void;
+    /**
+     * 上传地址。传入即启用内置 XHR 上传（含真实进度事件），
+     * 无需自行实现 `customRequest`。同时传入时 `customRequest` 优先。
+     */
+    action?: string | ((file: File) => string | PromiseLike<string>);
+    /** 请求方法，默认 POST。仅 `action` 模式生效 */
+    method?: UploadMethod;
+    /** 附加请求头。仅 `action` 模式生效 */
+    headers?: Record<string, string>;
+    /** 附加表单字段，可为函数按文件动态生成。仅 `action` 模式生效 */
+    data?: Record<string, unknown> | ((file: File) => Record<string, unknown>);
+    /** 跨域请求是否携带 cookie。仅 `action` 模式生效 */
+    withCredentials?: boolean;
+    /** 表单中文件字段名，默认 "file"。仅 `action` 模式生效 */
+    name?: string;
+    /**
+     * 上传前钩子，在内置校验（类型/数量/大小）通过之后执行。
+     *
+     * 返回 `false` 或 reject 阻止该文件上传；返回 `File`/`Blob` 则用其替换
+     * 待上传的文件，适用于压缩、转格式等场景（原始文件仍保留在 `originFile`）。
+     */
+    beforeUpload?: (file: File, fileList: File[]) => BeforeUploadReturn | Promise<BeforeUploadReturn>;
     /**
      * 粘贴上传。开启后监听容器内的 paste 事件，
      * 取剪贴板中的文件（如截图）走同一套校验与收集流程。
@@ -2767,7 +3094,10 @@ interface UploadProps {
 
 /**
  * Upload 上传组件
- * 支持点击选择和拖拽上传两种模式，文件校验、进度展示、文件列表管理
+ *
+ * 内核采用 rc-upload（@rc-component/upload）：原生 input、点击/键盘触发、
+ * 拖拽落盘、文件夹递归遍历、accept 判定、XHR 请求与中止均由其承担。
+ * 本层负责 lingee 的 UploadFile 列表语义、批量校验与 UI。
  */
 declare const Upload: React__default.ForwardRefExoticComponent<UploadProps & React__default.RefAttributes<HTMLDivElement>>;
 
@@ -2803,6 +3133,19 @@ interface ScrollAreaProps {
     onScroll?: UIEventHandler<HTMLDivElement>;
     /** Viewport（实际滚动元素）的 ref，用于外部控制滚动位置 */
     viewportRef?: Ref<HTMLDivElement>;
+    /**
+     * 声明「本组件是 flex/grid 容器的子项，请撑满分配到的高度」。
+     *
+     * 默认（false）下 viewport 通过 `height: inherit` 取高度，而 `inherit` 拿的是
+     * 父级的**样式值**不是布局结果。当 Root 作为 flex item 被兄弟节点（如面板的
+     * header / footer）压缩时，继承来的仍是未扣除头尾的整高，viewport 因此比 Root
+     * 高出头尾的量，超出部分被裁掉且滚不到，列表末尾永远露不出来。
+     *
+     * 传 true 后 Root 转为 flex 容器、viewport 走 `flex: 1`，高度取自实际布局结果。
+     * 代价是 Root 的 `display` 被组件占用，故不设为默认值 —— 只有确实放在
+     * flex/grid 容器里被压缩的场景才需要开启。
+     */
+    fill?: boolean;
 }
 interface ScrollBarProps {
     /** 滚动条方向 */
@@ -2833,6 +3176,101 @@ declare const ScrollArea: React__default.ForwardRefExoticComponent<ScrollAreaPro
  */
 declare const ScrollBar: React__default.ForwardRefExoticComponent<ScrollBarProps & React__default.RefAttributes<HTMLDivElement>>;
 
+/** 指示器位置 */
+type CarouselDotsPlacement = "inside" | "outside";
+/**
+ * 轮播实例 API
+ * 刻意收窄为最小可用集合，不直接暴露 embla 类型，避免消费方类型依赖泄漏
+ */
+interface CarouselApi {
+    /** 跳转到指定序号（0 开始），jump 为 true 时不播放过渡动画 */
+    scrollTo: (index: number, jump?: boolean) => void;
+    /** 上一页 */
+    scrollPrev: () => void;
+    /** 下一页 */
+    scrollNext: () => void;
+    /** 是否可向前翻页（loop 模式下恒为 true） */
+    canScrollPrev: () => boolean;
+    /** 是否可向后翻页（loop 模式下恒为 true） */
+    canScrollNext: () => boolean;
+    /** 当前选中序号 */
+    selectedIndex: () => number;
+    /** 总页数 */
+    count: () => number;
+    /** 启动自动轮播 */
+    play: () => void;
+    /** 暂停自动轮播 */
+    stop: () => void;
+    /** 重新初始化（外部改变了尺寸或结构时手动触发） */
+    reInit: () => void;
+}
+interface CarouselProps {
+    /** 轮播项，需为 CarouselItem */
+    children: ReactNode;
+    /** 自定义类名（应用于根容器） */
+    className?: string;
+    /** 自定义样式（应用于根容器） */
+    style?: CSSProperties;
+    /** 是否循环轮播 */
+    loop?: boolean;
+    /** 是否开启自动轮播 */
+    autoplay?: boolean;
+    /** 自动轮播间隔（ms），设计规范建议 3000 ~ 6000 */
+    autoplayDelay?: number;
+    /** 鼠标移入时暂停自动轮播，移出恢复 */
+    stopOnMouseEnter?: boolean;
+    /** 用户手动交互（拖拽 / 点击指示器）后彻底停止自动轮播 */
+    stopOnInteraction?: boolean;
+    /** 是否允许拖拽 / 滑动切换 */
+    draggable?: boolean;
+    /** 每屏展示的轮播项数量，多图模式下配合 gap 使用 */
+    slidesPerView?: number;
+    /** 轮播项之间的间距（px） */
+    gap?: number;
+    /** 初始选中序号（0 开始） */
+    defaultIndex?: number;
+    /** 是否展示圆点指示器 */
+    dots?: boolean;
+    /** 指示器位置：inside 浮于内容上方，outside 位于轮播下方 */
+    dotsPlacement?: CarouselDotsPlacement;
+    /** 指示器是否使用半透明毛玻璃胶囊底，用于内容色彩复杂的场景 */
+    dotsGlassy?: boolean;
+    /** 是否展示左右箭头 */
+    arrows?: boolean;
+    /** 选中项变化回调 */
+    onChange?: (index: number) => void;
+    /** 获取轮播实例，用于外部控制翻页 */
+    apiRef?: Ref<CarouselApi>;
+}
+interface CarouselItemProps {
+    /** 轮播项内容 */
+    children?: ReactNode;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: CSSProperties;
+}
+
+/**
+ * Carousel 轮播容器组件
+ *
+ * 水平方向切换，默认从右至左自动轮播，也支持拖拽与点击指示器切换。
+ *
+ * ```tsx
+ * <Carousel autoplay loop>
+ *   <Carousel.Item>第一屏</Carousel.Item>
+ *   <Carousel.Item>第二屏</Carousel.Item>
+ * </Carousel>
+ * ```
+ */
+declare const CarouselRoot: React__default.ForwardRefExoticComponent<CarouselProps & React__default.RefAttributes<HTMLDivElement>>;
+/** Carousel.Item 轮播项 */
+declare const CarouselItem: React__default.ForwardRefExoticComponent<CarouselItemProps & React__default.RefAttributes<HTMLDivElement>>;
+type CarouselComponent = typeof CarouselRoot & {
+    Item: typeof CarouselItem;
+};
+declare const Carousel: CarouselComponent;
+
 /**
  * 合并 CSS 类名，支持条件拼接
  * @param inputs - 任意数量的 ClassValue 参数
@@ -2840,4 +3278,4 @@ declare const ScrollBar: React__default.ForwardRefExoticComponent<ScrollBarProps
  */
 declare function cn(...inputs: ClassValue[]): string;
 
-export { Alert, type AlertProps, type AlertType, AvatarWithGroup as Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, ButtonProps, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, type CheckboxSize, ColorPicker, type ColorPickerProps, type ColorPickerSize, type CoverConfig, type CustomRequestOptions, type CustomRequestReturn, DatePicker, type DatePickerProps, type DatePickerSize, type DateRange, Dialog, type DialogConfirmOptions, type DialogProps, Divider, type DividerOrientation, type DividerProps, type DividerVariant, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, DropdownButton, type DropdownButtonProps, DropdownCheckboxItem, type DropdownCheckboxItemProps, DropdownContent, type DropdownContentProps, DropdownGroup, type DropdownGroupProps, DropdownItem, type DropdownItemData, type DropdownItemProps, DropdownLabel, type DropdownLabelData, type DropdownLabelProps, type DropdownMenuItemData, type DropdownProps, DropdownRadioGroup, type DropdownRadioGroupProps, DropdownRadioItem, type DropdownRadioItemProps, DropdownSeparator, type DropdownSeparatorData, type DropdownSeparatorProps, DropdownStatus, type DropdownStatusProps, type DropdownStatusText, type DropdownStatusType, DropdownSub, DropdownSubContent, type DropdownSubContentProps, type DropdownSubProps, DropdownSubTrigger, type DropdownSubTriggerProps, DropdownTrigger, type DropdownTriggerProps, EllipsisTooltip, type EllipsisTooltipProps, Empty, EmptyCard, type EmptyCardProps, type EmptyCardSpacing, type EmptyCardStatus, type EmptyCardVariant, type EmptyIconComponent, type EmptyProps, type EmptySize, type FeedbackAttachment, type FeedbackFileWallItem, type FeedbackHistoryDetail, type FeedbackHistoryItem, type FeedbackReply, type FeedbackSimilarItem, type FeedbackStatus, type FeedbackTabKey, type FileItemActions, Flex, type FlexGapSize, type FlexOrientation, type FlexProps, Form, type FormInstance, type FormItemProps, type FormLayout, type FormProps, Image, type ImagePreviewGroupProps, type ImageProps, type ImgInfo, LgSize, LingeeProvider, type LingeeProviderProps, type Locale, Pagination, type PaginationProps, type PaginationVariant, PopoverContentProps, type PreviewGroupType, type PreviewType, Progress, type ProgressProps, type ProgressStatus, type ProgressType, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, type RadioSize, RangePicker, type RangePickerProps, type RangePickerSize, type RejectReason, ScrollArea, type ScrollAreaProps, ScrollBar, type ScrollBarProps, Select, type SelectDropdownProps, type SelectMode, type SelectOption, type SelectOptionGroup, type SelectProps, type SelectSize, Sidebar, SidebarAuthImage, type SidebarAuthImageProps, type SidebarCaretPlacement, SidebarCollapsibleListItem, type SidebarCollapsibleListItemProps, SidebarCollapsibleNavItem, type SidebarCollapsibleNavItemChild, type SidebarCollapsibleNavItemProps, SidebarFeedbackAttachmentRow, type SidebarFeedbackAttachmentRowProps, SidebarFeedbackDetail, type SidebarFeedbackDetailProps, SidebarFeedbackField, type SidebarFeedbackFieldProps, SidebarFeedbackFileWall, type SidebarFeedbackFileWallProps, SidebarFeedbackHistoryItem, type SidebarFeedbackHistoryItemProps, SidebarFeedbackHistoryPanel, type SidebarFeedbackHistoryPanelProps, SidebarFeedbackModal, type SidebarFeedbackModalProps, SidebarFeedbackSimilarItem, type SidebarFeedbackSimilarItemProps, SidebarFeedbackSubmitPanel, type SidebarFeedbackSubmitPanelProps, SidebarFooter, SidebarFooterBadge, type SidebarFooterBadgeProps, SidebarFooterMenuStaticRow, type SidebarFooterMenuStaticRowProps, type SidebarFooterProps, SidebarFooterUser, type SidebarFooterUserProps, SidebarGroupHeader, type SidebarGroupHeaderProps, SidebarHeader, type SidebarHeaderProps, type SidebarIndicatorType, SidebarListItem, type SidebarListItemProps, SidebarNavItem, type SidebarNavItemProps, SidebarRoot, type SidebarRootProps, SidebarTabBar, type SidebarTabBarProps, type SidebarTabItem, SidebarUsageBar, type SidebarUsageBarProps, SidebarUsagePanel, type SidebarUsagePanelProps, SidebarUsagePanelSection, type SidebarUsagePanelSectionProps, type SidebarUsageTone, Skeleton, type SkeletonAnimation, type SkeletonProps, type SkeletonVariant, Slider, type SliderProps, type SliderSize, Spin, type SpinProps, type SpinSize, type StepItem, type StepStatus, Steps, type StepsProps, type StepsSize, type StepsTitlePlacement, Table, type TableColumnType, type TableProps, type TableRowSelection, type TableSize, type TableSorterState, Tag, type TagPresetColor, type TagProps, type TagShape, type TagSize, TimePicker, type TimePickerProps, type TimePickerSize, type TimeValue, TooltipProps, type TransformAction, type TransformType, Upload, type UploadFile, type UploadFileStatus, type UploadProps, cn, enUS, formatFileSize, useComponentLocale, useLocale, zhCN };
+export { Alert, type AlertProps, type AlertType, AvatarWithGroup as Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, ButtonProps, Carousel, type CarouselApi, type CarouselDotsPlacement, CarouselItem, type CarouselItemProps, type CarouselProps, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, type CheckboxSize, ColorPicker, type ColorPickerProps, type ColorPickerSize, type CoverConfig, type CustomRequestOptions, type CustomRequestReturn, DatePicker, type DatePickerProps, type DatePickerSize, type DateRange, Dialog, type DialogConfirmOptions, type DialogHostModal, type DialogProps, Divider, type DividerOrientation, type DividerProps, type DividerVariant, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, DropdownButton, type DropdownButtonProps, DropdownCheckboxItem, type DropdownCheckboxItemProps, DropdownContent, type DropdownContentProps, type DropdownEllipsisTooltip, DropdownGroup, type DropdownGroupProps, DropdownItem, type DropdownItemData, type DropdownItemProps, DropdownLabel, type DropdownLabelData, type DropdownLabelProps, type DropdownMenuItemData, type DropdownProps, DropdownRadioGroup, type DropdownRadioGroupProps, DropdownRadioItem, type DropdownRadioItemProps, DropdownSeparator, type DropdownSeparatorData, type DropdownSeparatorProps, DropdownStatus, type DropdownStatusProps, type DropdownStatusText, type DropdownStatusType, DropdownSub, DropdownSubContent, type DropdownSubContentProps, type DropdownSubProps, DropdownSubTrigger, type DropdownSubTriggerProps, DropdownTrigger, type DropdownTriggerProps, EllipsisTooltip, type EllipsisTooltipProps, Empty, EmptyCard, type EmptyCardProps, type EmptyCardSpacing, type EmptyCardStatus, type EmptyCardVariant, type EmptyIconComponent, type EmptyProps, type EmptySize, type FeedbackAttachment, type FeedbackFileWallItem, type FeedbackHistoryDetail, type FeedbackHistoryItem, type FeedbackReply, type FeedbackSimilarItem, type FeedbackStatus, type FeedbackTabKey, type FileItemActions, Flex, type FlexGapSize, type FlexOrientation, type FlexProps, Form, type FormInstance, type FormItemProps, type FormLayout, type FormProps, HostModalPage, type HostModalPageProps, Image, type ImagePreviewGroupProps, type ImageProps, type ImgInfo, LgSize, LingeeProvider, type LingeeProviderProps, type LingeeSite, type Locale, Pagination, type PaginationProps, type PaginationVariant, PopoverContentProps, type PreviewGroupType, type PreviewType, Progress, type ProgressProps, type ProgressStatus, type ProgressType, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, type RadioSize, RangePicker, type RangePickerProps, type RangePickerSize, type RejectReason, ScrollArea, type ScrollAreaProps, ScrollBar, type ScrollBarProps, Select, type SelectDropdownProps, type SelectMode, type SelectOption, type SelectOptionGroup, type SelectProps, type SelectSize, Sidebar, SidebarAuthImage, type SidebarAuthImageProps, type SidebarCaretPlacement, SidebarCollapsibleListItem, type SidebarCollapsibleListItemProps, SidebarCollapsibleNavItem, type SidebarCollapsibleNavItemChild, type SidebarCollapsibleNavItemProps, SidebarFeedbackAttachmentRow, type SidebarFeedbackAttachmentRowProps, SidebarFeedbackDetail, type SidebarFeedbackDetailProps, SidebarFeedbackField, type SidebarFeedbackFieldProps, SidebarFeedbackFileWall, type SidebarFeedbackFileWallProps, SidebarFeedbackHistoryItem, type SidebarFeedbackHistoryItemProps, SidebarFeedbackHistoryPanel, type SidebarFeedbackHistoryPanelProps, SidebarFeedbackModal, type SidebarFeedbackModalProps, SidebarFeedbackSimilarItem, type SidebarFeedbackSimilarItemProps, SidebarFeedbackSubmitPanel, type SidebarFeedbackSubmitPanelProps, SidebarFooter, SidebarFooterBadge, type SidebarFooterBadgeProps, SidebarFooterMenuStaticRow, type SidebarFooterMenuStaticRowProps, type SidebarFooterProps, SidebarFooterUser, type SidebarFooterUserProps, SidebarGroupHeader, type SidebarGroupHeaderProps, SidebarHeader, type SidebarHeaderProps, type SidebarIndicatorType, SidebarListItem, type SidebarListItemProps, SidebarNavItem, type SidebarNavItemProps, SidebarRoot, type SidebarRootProps, SidebarTabBar, type SidebarTabBarProps, type SidebarTabItem, SidebarUsageBar, type SidebarUsageBarProps, SidebarUsagePanel, type SidebarUsagePanelProps, SidebarUsagePanelSection, type SidebarUsagePanelSectionProps, type SidebarUsageTone, Skeleton, type SkeletonAnimation, type SkeletonProps, type SkeletonVariant, Slider, type SliderProps, type SliderSize, Spin, type SpinProps, type SpinSize, type StepItem, type StepStatus, Steps, type StepsProps, type StepsSize, type StepsTitlePlacement, Table, type TableColumnType, type TableProps, type TableRowSelection, type TableSize, type TableSorterState, Tag, type TagPresetColor, type TagProps, type TagShape, type TagSize, TimePicker, type TimePickerProps, type TimePickerSize, type TimeValue, TooltipProps, type TransformAction, type TransformType, Upload, type UploadFile, type UploadFileStatus, type UploadProps, closeHostModal, cn, enUS, formatFileSize, getHostModalParams, isInHostModal, notifyHostModalReady, useComponentLocale, useLocale, useSite, zhCN };