@mrchar/cumquat 0.0.0-stage → 0.1.0

package/dist/composables/index.d.ts

@@ -0,0 +1,1962 @@
+import { CSSProperties, ComputedRef, MaybeRefOrGetter, Ref, WritableComputedRef, computed, ref } from "vue";
+//#region src/types.d.ts
+/**
+ * 公共类型契约：所有组合函数与组件之间共享的最小类型集合。
+ */
+/** 异步数据状态：数据型组件/组合函数唯一依赖的数据契约 */
+interface AsyncStateLike<T> {
+  status: 'pending' | 'success' | 'error';
+  data: T;
+  error?: unknown;
+  isStale?: boolean;
+  retry?: () => void;
+}
+/** 动作结果：action 返回值可导出状态与错误，组件据此控制状态与错误提示 */
+interface ActionResult {
+  /** 动作结果状态，缺省视为 success */
+  status?: 'success' | 'error';
+  /** 失败信息；status 为 error 或携带 error 时组件进入失败分支 */
+  error?: unknown;
+  /** 提示文案，覆盖组件默认错误文案 */
+  message?: string;
+}
+/** 动作：交互组件传入的异步操作，执行期间自动派生 loading/disabled */
+type ActionLike = (...args: any[]) => Promise<ActionResult | void> | ActionResult | void;
+/** 订阅结果：subscribe 处理方法返回值，导出状态、数据与错误 */
+interface SubscribeResult<T> {
+  /** 订阅状态，缺省视为 success */
+  status?: 'loading' | 'success' | 'error';
+  /** 订阅到的数据；status 为 success 时由组件渲染 */
+  data?: T;
+  /** 失败信息；status 为 error 或携带 error 时组件进入失败分支 */
+  error?: unknown;
+  /** 提示文案，覆盖组件默认错误文案 */
+  message?: string;
+}
+/** 订阅处理：数据展示组件传入的订阅函数，挂载时调用，resolve 后渲染数据 */
+type SubscribeHandler<T> = () => Promise<SubscribeResult<T>> | SubscribeResult<T>;
+/** 受控值的标准入参形态 */
+interface ControlledProps<T> {
+  modelValue?: T;
+  defaultValue?: T;
+  'onUpdate:modelValue'?: (value: T) => void;
+}
+/** 异步请求函数：返回 Promise，可携带任意参数 */
+type AsyncFn<T, A extends unknown[]> = (...args: A) => Promise<T>;
+/** 浮层方位（含主方位与对齐方式） */
+type Placement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+/** 浮层策略：fixed 相对视口，absolute 相对最近定位祖先 */
+type Strategy = 'fixed' | 'absolute';
+//#endregion
+//#region src/core/useId.d.ts
+/**
+ * SSR 安全的组件内唯一标识，用于 label/aria 关联。
+ *
+ * @param prefix 标识前缀，默认 `cq`
+ * @returns 形如 `cq-input-0` 的只读字符串引用
+ * @internal 消费组件：FormItem、Tooltip 及全部需要 aria 关联的控件
+ */
+export declare function useId(prefix?: string): import("vue").ComputedRef<string>;
+//#endregion
+//#region src/core/useControllableModel.d.ts
+interface ControllableModelOptions<T> {
+  /** 受控值（可直接传值、ref 或 getter；SFC 中传 `() => props.modelValue` 保持响应式） */
+  modelValue?: MaybeRefOrGetter<T>;
+  /** 非受控初始值 */
+  defaultValue?: T;
+  /** 受控回调（通常直接传 props['onUpdate:modelValue']） */
+  onChange?: (value: T) => void;
+  /** 无任何值时使用的兜底初始值 */
+  fallback?: T;
+  /** 值比较器，默认 Object.is */
+  equals?: (a: T, b: T) => boolean;
+}
+interface ControllableModelReturn<T> {
+  /** 统一读写入口：受控时读 props，非受控时读内部状态 */
+  value: WritableComputedRef<T>;
+  /** 主动写入（等价于 value.value = next） */
+  setValue: (next: T) => void;
+  /** 是否处于受控模式 */
+  isControlled: Ref<boolean>;
+}
+/**
+ * 受控 / 非受控统一封装。
+ *
+ * - 传入 `modelValue` 时为受控：读外部值，写入时通过 onChange 回发事件；
+ * - 仅传入 `defaultValue` 时为非受控：内部自持状态，写入同样回发事件以便宿主监听。
+ *
+ * `v-model` 永远是纯同步的，本函数不做任何异步编排。
+ */
+export declare function useControllableModel<T>(options?: ControllableModelOptions<T>): ControllableModelReturn<T>;
+/** 从标准 props 形态构造受控模型的便捷方法 */
+export declare function createControllableModel<T>(props: ControlledProps<T>, fallback?: T): ControllableModelReturn<T>;
+//#endregion
+//#region src/core/useToggle.d.ts
+interface ToggleReturn {
+  value: Ref<boolean>;
+  toggle: (next?: boolean) => void;
+  setTrue: () => void;
+  setFalse: () => void;
+}
+/**
+ * 布尔状态及取反操作。
+ *
+ * @param initial 初始值，默认 false
+ * @internal 消费组件：Switch、Layout、FloatButton
+ */
+export declare function useToggle(initial?: boolean): ToggleReturn;
+//#endregion
+//#region src/core/useEventListener.d.ts
+type EventMap = WindowEventMap & DocumentEventMap & HTMLElementEventMap & Record<string, Event>;
+/**
+ * 绑定 DOM 事件并在作用域销毁时自动卸载；目标支持响应式引用，
+ * 目标变化（如 Teleport 后重挂载）时自动重新绑定。
+ *
+ * @param target 事件目标（元素 / window / document，可为 ref 或 getter）
+ * @param event 事件名
+ * @param listener 处理函数
+ * @param options addEventListener 选项
+ * @returns 手动解绑函数
+ */
+export declare function useEventListener<K extends keyof EventMap>(target: MaybeRefOrGetter<EventTarget | null | undefined>, event: K, listener: (ev: EventMap[K]) => void, options?: AddEventListenerOptions | boolean): () => void;
+//#endregion
+//#region src/internal/dom.d.ts
+/** 可注入到 DOM 类组合函数的目标类型：元素、元素引用或 getter */
+type MaybeElement<T extends Element = Element> = MaybeRefOrGetter<T | null | undefined>;
+//#endregion
+//#region src/core/useResizeObserver.d.ts
+interface ElementSize {
+  width: number;
+  height: number;
+}
+interface UseResizeObserverReturn {
+  width: Ref<number>;
+  height: Ref<number>;
+  stop: () => void;
+}
+/**
+ * 监听元素内容盒尺寸变化。SSR 环境下尺寸恒为 0 且不报错。
+ *
+ * @internal 消费方：useFloating；Watermark / Typography / VirtualList 组件内联复用
+ */
+export declare function useResizeObserver(target: MaybeElement<HTMLElement>): UseResizeObserverReturn;
+//#endregion
+//#region src/core/useIntersectionObserver.d.ts
+interface UseIntersectionObserverOptions {
+  root?: MaybeElement<HTMLElement>;
+  rootMargin?: string;
+  threshold?: number | number[];
+  /** 首次进入视口后即停止监听（懒加载场景），默认 false */
+  once?: boolean;
+}
+interface UseIntersectionObserverReturn {
+  isIntersecting: Ref<boolean>;
+  ratio: Ref<number>;
+  stop: () => void;
+}
+/**
+ * 监听元素进出视口状态。SSR 安全，不支持 IntersectionObserver 时按可见处理。
+ *
+ * @internal 消费方：useImageState 懒加载；宿主可独立使用
+ */
+export declare function useIntersectionObserver(target: MaybeElement<HTMLElement>, options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn;
+//#endregion
+//#region src/core/useTimeoutFn.d.ts
+interface UseTimeoutFnReturn {
+  isPending: Ref<boolean>;
+  /** 重新启动计时（可覆盖延迟毫秒数） */
+  start: (ms?: number) => void;
+  stop: () => void;
+}
+/**
+ * 可随时停止 / 重启的一次性定时器，作用域销毁时自动清理。
+ *
+ * @param cb 到时回调
+ * @param ms 延迟毫秒；构造时传 null/undefined 表示不自动启动，需手动 start
+ * @internal 消费方：useOpen 延迟开合、useHoverIntent、useToastQueue、useTypeahead
+ */
+export declare function useTimeoutFn(cb: () => void, ms?: number): UseTimeoutFnReturn;
+//#endregion
+//#region src/core/useIntervalFn.d.ts
+interface UseIntervalFnOptions {
+  /** 是否立即启动，默认 true */
+  immediate?: boolean;
+  /** 立即执行一次回调后再开始计时，默认 false */
+  immediateCallback?: boolean;
+}
+interface UseIntervalFnReturn {
+  isActive: Ref<boolean>;
+  pause: () => void;
+  resume: () => void;
+  /** 暂停后立即执行一次回调并恢复计时 */
+  restart: () => void;
+}
+/**
+ * 可暂停 / 恢复的周期定时器，作用域销毁时自动清理。
+ *
+ * @param cb 周期回调
+ * @param interval 间隔毫秒，可随 resume 动态变更
+ * @internal 消费方：Carousel 自动播放；宿主可独立使用
+ */
+export declare function useIntervalFn(cb: () => void, interval?: number, options?: UseIntervalFnOptions): UseIntervalFnReturn;
+//#endregion
+//#region src/core/useMediaQuery.d.ts
+/**
+ * 订阅 CSS 媒体查询结果。SSR 环境下恒为 false。
+ * 查询串支持响应式引用，变化时自动重新订阅。
+ *
+ * @internal 消费组件：Layout、Grid；断点语义由宿主基于本函数自行封装
+ */
+export declare function useMediaQuery(query: MaybeRefOrGetter<string>): Ref<boolean>;
+//#endregion
+//#region src/core/useScroll.d.ts
+type ScrollDirection = 'up' | 'down' | 'left' | 'right' | 'none';
+interface UseScrollOptions {
+  /** 滚动监听是否使用捕获阶段（读取内部元素滚动时常用），默认 true */
+  capture?: boolean;
+  /** 是否启用方向记录，默认 true */
+  direction?: boolean;
+  /** 节流：同一帧内只处理一次，默认 true */
+  throttle?: boolean;
+}
+interface ScrollPosition {
+  x: Ref<number>;
+  y: Ref<number>;
+  directionX: Ref<ScrollDirection>;
+  directionY: Ref<ScrollDirection>;
+}
+/**
+ * 监听目标元素或窗口的滚动位置与方向，SSR 安全。
+ *
+ * @param target 滚动容器（window / document / 元素），可为响应式
+ * @internal 消费组件：Affix、Anchor、BackTop 内联复用；宿主可独立使用
+ */
+export declare function useScroll(target?: MaybeRefOrGetter<EventTarget | null | undefined>, options?: UseScrollOptions): ScrollPosition;
+//#endregion
+//#region src/core/useScrollLock.d.ts
+interface ScrollLockReturn {
+  isLocked: Ref<boolean>;
+  lock: () => void;
+  unlock: () => void;
+  /** 切换锁定状态 */
+  toggle: (next?: boolean) => void;
+}
+/**
+ * 打开浮层时锁定背景滚动。采用引用计数，支持多浮层叠加；
+ * 作用域销毁时自动释放一次锁定，SSR 安全。
+ *
+ * @param initial 初始是否锁定，默认 false
+ * @internal 消费方：useModal 及下拉浮层
+ */
+export declare function useScrollLock(initial?: boolean): ScrollLockReturn;
+//#endregion
+//#region src/core/useScrollIntoView.d.ts
+interface ScrollIntoViewOptions {
+  behavior?: ScrollBehavior;
+  block?: ScrollLogicalPosition;
+  inline?: ScrollLogicalPosition;
+}
+/**
+ * 将目标元素平滑滚动至可视区。返回命令式方法，供 Tour/Anchor/Tabs 复用。
+ *
+ * @param defaultTarget 默认滚动目标（调用时可覆盖）
+ */
+export declare function useScrollIntoView(defaultTarget?: MaybeElement<HTMLElement>): (target?: MaybeElement<HTMLElement>, options?: ScrollIntoViewOptions) => void;
+//#endregion
+//#region src/core/useClickOutside.d.ts
+interface UseClickOutsideOptions {
+  /** 额外视为"内部"的容器（如浮层本体与触发器同时参与判定） */
+  ignore?: MaybeRefOrGetter<Array<MaybeElement<Element>>>;
+  /** 是否启用监听，默认 true；关闭浮层时可通过它停用 */
+  enabled?: MaybeRefOrGetter<boolean>;
+  /** 监听事件，pointerdown 早于 click，默认 pointerdown */
+  event?: 'pointerdown' | 'click' | 'mousedown';
+}
+/**
+ * 点击目标元素外部时触发回调。SSR 安全，作用域销毁自动解绑。
+ *
+ * @internal 消费方：useDismiss 及各选择器组件
+ */
+export declare function useClickOutside(target: MaybeElement<HTMLElement>, handler: (event: PointerEvent | MouseEvent) => void, options?: UseClickOutsideOptions): void;
+//#endregion
+//#region src/core/useFocusTrap.d.ts
+interface UseFocusTrapOptions {
+  /** 初始焦点元素选择器；不传则聚焦容器内第一个可聚焦元素 */
+  initialFocus?: string;
+  /** 是否在激活时立即聚焦，默认 true */
+  immediate?: boolean;
+}
+interface UseFocusTrapReturn {
+  isActive: Ref<boolean>;
+  trap: () => void;
+  release: () => void;
+  /** 焦点移动到容器内第一个 / 最后一个可聚焦元素 */
+  focusFirst: () => void;
+  focusLast: () => void;
+}
+/**
+ * 焦点陷阱：激活期间 Tab 在容器内循环，Esc 不做处理（由 useDismiss 编排）。
+ *
+ * @param container 陷阱容器，可为响应式引用
+ * @internal 消费方：useModal
+ */
+export declare function useFocusTrap(container: MaybeElement<HTMLElement>, options?: UseFocusTrapOptions): UseFocusTrapReturn;
+//#endregion
+//#region src/core/useFocusReturn.d.ts
+interface FocusReturnOptions {
+  /** 作用域销毁时是否自动归还，默认 true */
+  autoRestore?: boolean;
+}
+interface FocusReturnReturn {
+  /** 记录当前焦点元素（通常在浮层打开时调用） */
+  record: () => void;
+  /** 主动归还焦点 */
+  restore: () => void;
+}
+/**
+ * 浮层关闭后将焦点归还至打开前的元素。
+ *
+ * @internal 消费方：useModal、usePopoverModel
+ */
+export declare function useFocusReturn(options?: FocusReturnOptions): FocusReturnReturn;
+//#endregion
+//#region src/core/useRovingFocus.d.ts
+interface RovingFocusOptions {
+  /** 选项数量或选项元素数组的来源（响应式） */
+  count: MaybeRefOrGetter<number>;
+  /** 判定索引对应项是否禁用（禁用项在键盘移动时跳过） */
+  isItemDisabled?: (index: number) => boolean;
+  /** 导航方向，默认 vertical */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+  /** 到达边界后循环，默认 true */
+  loop?: boolean;
+  /** 初始激活索引，默认 0 */
+  initialIndex?: number;
+  /** 移动时是否自动聚焦 DOM，默认 true（传 false 时仅维护 tabindex） */
+  autofocus?: boolean;
+  /** 容器，配合 autofocus 定位选项；选项通过 [data-roving-index] 标记 */
+  container?: MaybeElement<HTMLElement>;
+}
+interface RovingFocusReturn {
+  activeIndex: Ref<number>;
+  setActiveIndex: (index: number) => void;
+  /** 绑定到选项容器的键盘处理器 */
+  onKeydown: (event: KeyboardEvent) => void;
+  /** 返回某项的 tabindex：激活项为 0，其余为 -1 */
+  getTabIndex: (index: number) => 0 | -1;
+  /** 绑定到单个选项上，获得焦点时同步激活索引 */
+  onItemFocus: (index: number) => () => void;
+}
+/**
+ * 列表内 roving-tabindex 焦点管理：方向键 / Home / End 移动激活项，
+ * 自动跳过禁用项，可选循环。Tab 只落到当前激活项。
+ *
+ * @internal 消费组件：Select、Menu、Tabs、Segmented、Tree
+ */
+export declare function useRovingFocus(options: RovingFocusOptions): RovingFocusReturn;
+//#endregion
+//#region src/core/useTypeahead.d.ts
+interface TypeaheadOptions {
+  /** 获取当前可匹配的选项标签列表 */
+  getLabels: () => string[];
+  /** 命中选项时的回调（参数为索引） */
+  onMatch?: (index: number) => void;
+  /** 起始搜索索引（通常为当前激活项） */
+  startIndex?: () => number;
+  /** 输入重置间隔，默认 500ms */
+  resetDelay?: number;
+  /** 是否循环匹配，默认 true */
+  loop?: boolean;
+}
+interface TypeaheadReturn {
+  /** 当前累计的搜索串 */
+  query: Ref<string>;
+  /** 绑定到列表容器的键盘处理器（字符键触发匹配） */
+  onKeydown: (event: KeyboardEvent) => void;
+  reset: () => void;
+}
+/**
+ * 键盘输入匹配选项：在重置间隔内连续输入字符组成搜索串，
+ * 按前缀匹配选项标签并跳转，单字符重复按时序循环匹配。
+ *
+ * @internal 消费组件：Select、Menu、Tree
+ */
+export declare function useTypeahead(options: TypeaheadOptions): TypeaheadReturn;
+//#endregion
+//#region src/core/useDraggable.d.ts
+interface DraggablePosition {
+  /** 相对元素盒左上角的像素偏移 */
+  x: number;
+  y: number;
+  /** 0~1 之间的归一化位置（已钳制在元素盒内） */
+  ratioX: number;
+  ratioY: number;
+}
+interface UseDraggableOptions {
+  /** 拖拽手柄，默认为目标元素自身 */
+  handle?: MaybeElement<HTMLElement>;
+  /** 限制拖拽轴，默认 both */
+  axis?: 'x' | 'y' | 'both';
+  /** 拖拽边界元素，默认为目标元素自身 */
+  bounds?: MaybeElement<HTMLElement>;
+  /** 初始归一化位置 */
+  initialRatio?: {
+    x: number;
+    y: number;
+  };
+  /** 是否禁用 */
+  disabled?: MaybeRefOrGetter<boolean>;
+  onStart?: (position: DraggablePosition, event: PointerEvent) => void;
+  onMove?: (position: DraggablePosition, event: PointerEvent) => void;
+  onEnd?: (position: DraggablePosition, event: PointerEvent) => void;
+}
+interface UseDraggableReturn {
+  x: Ref<number>;
+  y: Ref<number>;
+  ratioX: Ref<number>;
+  ratioY: Ref<number>;
+  dragging: Ref<boolean>;
+  /** 命令式按归一化比例写入位置（轨道点击定位时使用） */
+  moveToRatio: (ratioX: number, ratioY: number) => void;
+}
+/**
+ * 基于 Pointer Events 的拖拽原语：在目标元素盒内测量归一化位置，
+ * 自动处理边界钳制、指针捕获与清理。Slider / ColorPicker 共用同一份几何计算。
+ */
+export declare function useDraggable(target: MaybeElement<HTMLElement>, options?: UseDraggableOptions): UseDraggableReturn;
+//#endregion
+//#region src/core/useClipboard.d.ts
+interface UseClipboardOptions {
+  /** 复制成功后 copied 状态保持时长，默认 1500ms */
+  copiedDuration?: number;
+  /** 是否在非安全上下文降级使用 execCommand，默认 true */
+  legacy?: boolean;
+}
+interface UseClipboardReturn {
+  copied: Ref<boolean>;
+  error: Ref<unknown>;
+  copy: (text: string) => Promise<boolean>;
+}
+/**
+ * 复制文本到剪贴板，自动派生短暂的成功反馈；
+ * 不支持 Clipboard API 时降级为隐藏 textarea + execCommand。
+ *
+ * @internal 消费组件：Typography；宿主可独立使用
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+//#endregion
+//#region src/core/useTransitionVisible.d.ts
+interface TransitionVisibleReturn {
+  /** 是否应将浮层挂载到 DOM（离场动画结束后才卸载） */
+  rendered: Ref<boolean>;
+  /** 是否处于可见态（驱动进出场 class） */
+  visible: Ref<boolean>;
+  /** 绑定到 <Transition> 的 after-leave 事件 */
+  onAfterLeave: () => void;
+}
+/**
+ * 进出场过渡的挂载状态机：
+ * - 打开时先 rendered=true（挂载），下一帧 visible=true（触发进入过渡）；
+ * - 关闭时 visible=false（触发离开过渡），after-leave 后 rendered=false（卸载）。
+ *
+ * 组件模板用法：
+ * `<Transition @after-leave="onAfterLeave"><div v-if="rendered" v-show="visible" />`
+ *
+ * @param isOpen 开合来源（ref / getter）
+ */
+export declare function useTransitionVisible(isOpen: MaybeRefOrGetter<boolean>): TransitionVisibleReturn;
+//#endregion
+//#region src/core/useZIndex.d.ts
+interface ZIndexReturn {
+  /** 当前分配到的层级 */
+  currentZIndex: Ref<number>;
+  /** 取下一个层级（浮层每次打开时调用） */
+  nextZIndex: () => number;
+  /** 当前全局最大值（供初始化样式参考） */
+  getGlobalZIndex: () => number;
+}
+/**
+ * 全局浮层层级递增管理。Dialog/Drawer/Popover/Message/Notification
+ * 共用同一序列，组件卸载无需回收（仅单调递增）。
+ */
+export declare function useZIndex(initial?: number): ZIndexReturn;
+/** 重置全局层级（仅供测试使用） */
+export declare function resetGlobalZIndex(value?: number): void;
+//#endregion
+//#region src/behavior/useOpen.d.ts
+interface UseOpenOptions extends ControlledProps<boolean> {
+  /** 打开延迟（毫秒），默认 0 */
+  openDelay?: number;
+  /** 关闭延迟（毫秒），默认 0（悬停浮层常用） */
+  closeDelay?: number;
+  /** 开合状态变化回调 */
+  onChange?: (open: boolean) => void;
+}
+interface UseOpenReturn {
+  isOpen: Ref<boolean>;
+  open: () => void;
+  close: () => void;
+  toggle: (next?: boolean) => void;
+}
+/**
+ * 开合状态机：支持受控（modelValue + update:modelValue）与非受控，
+ * 可选的打开 / 关闭延迟（由 useHoverIntent 之类场景复用）。
+ *
+ * @internal 消费组件：Dialog/Drawer（经 useModal）、Popover、Dropdown、Select、Tooltip
+ */
+export declare function useOpen(options?: UseOpenOptions): UseOpenReturn;
+//#endregion
+//#region src/behavior/useDismiss.d.ts
+type DismissReason = 'escape-key' | 'outside-press' | 'scroll';
+interface UseDismissOptions {
+  /** 是否处于打开态（仅打开时响应关闭策略） */
+  isOpen: MaybeRefOrGetter<boolean>;
+  /** 触发元素：点击它不判定为外部点击 */
+  reference?: MaybeElement<HTMLElement>;
+  /** 浮层本体 */
+  floating?: MaybeElement<HTMLElement>;
+  /** 触发关闭回调 */
+  onDismiss: (reason: DismissReason) => void;
+  /** ESC 关闭，默认 true */
+  escapeKey?: boolean;
+  /** 外部点击关闭，默认 true */
+  outsidePress?: boolean;
+  /** 外部点击是否使用鼠标按下（pointerdown），默认 true */
+  outsidePressEvent?: 'pointerdown' | 'click' | 'mousedown';
+  /** 滚动关闭，默认 false（下拉选择类浮层可开启） */
+  scroll?: boolean;
+  /** 是否启用，默认 true */
+  enabled?: MaybeRefOrGetter<boolean>;
+}
+/**
+ * ESC、外部点击、滚动失焦的统一关闭编排。仅在浮层打开时生效，
+ * 监听器随作用域自动清理。
+ *
+ * @internal 消费组件：全部浮层（经 useModal / usePopoverModel 或直接使用）
+ */
+export declare function useDismiss(options: UseDismissOptions): void;
+//#endregion
+//#region src/behavior/useFloating.d.ts
+interface UseFloatingOptions {
+  placement?: MaybeRefOrGetter<Placement>;
+  strategy?: Strategy;
+  /** 浮层与锚点的主间距，默认 4 */
+  gap?: number;
+  /** 距视口边缘的最小留白（移位与箭头钳制共用），默认 4 */
+  shiftPadding?: number;
+  /** 空间不足时自动翻转，默认 true */
+  flip?: boolean;
+  /** 超出视口时平移回可见区，默认 true */
+  shift?: boolean;
+  /** 箭头元素尺寸（不传则从箭头元素测量） */
+  arrowSize?: number;
+  /** 打开状态来源；变为 true 后立即重新定位 */
+  open?: MaybeRefOrGetter<boolean>;
+  /** 定位完成回调（可读取最终方位） */
+  onPositioned?: (data: {
+    placement: Placement;
+    x: number;
+    y: number;
+  }) => void;
+}
+interface UseFloatingReturn {
+  /** 绑定到锚点元素：ref="referenceRef" */
+  referenceRef: Ref<HTMLElement | null>;
+  /** 绑定到浮层元素 */
+  floatingRef: Ref<HTMLElement | null>;
+  /** 绑定到箭头元素 */
+  arrowRef: Ref<HTMLElement | null>;
+  /** 翻转后的实际方位 */
+  placement: Ref<Placement>;
+  x: Ref<number>;
+  y: Ref<number>;
+  arrowX: Ref<number | undefined>;
+  arrowY: Ref<number | undefined>;
+  /** 直接绑定到浮层的 style */
+  floatingStyles: Ref<CSSProperties>;
+  /** 手动重新计算定位 */
+  update: () => void;
+}
+/**
+ * 锚点浮层定位引擎：方位、自动翻转、视口移位、间距、箭头坐标；
+ * 滚动、窗口尺寸、锚点与浮层尺寸变化时自动更新。零第三方依赖。
+ *
+ * @internal 消费组件：Tooltip/Popover/Dropdown/Select/Cascader/DatePicker/
+ * TimePicker/ColorPicker/TreeSelect/AutoComplete/Mention/Popconfirm
+ */
+export declare function useFloating(options?: UseFloatingOptions): UseFloatingReturn;
+//#endregion
+//#region src/behavior/useHoverIntent.d.ts
+interface HoverIntentOptions {
+  /** 打开延迟，默认 100ms（防止快速划过敏触发） */
+  showDelay?: number;
+  /** 关闭延迟，默认 100ms（鼠标在触发器与浮层间移动时不闪烁） */
+  hideDelay?: number;
+  /** 是否禁用（触屏设备可关闭） */
+  disabled?: boolean;
+}
+interface HoverIntentReturn {
+  isHovered: Ref<boolean>;
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+  /** 立即开合，跳过延迟 */
+  setOpen: (open: boolean) => void;
+}
+/**
+ * 悬停触发的开合延迟控制，防止抖动与误触。
+ * 触发器与浮层应同时绑定返回的 enter/leave 处理器。
+ *
+ * @internal 消费组件：Tooltip、Dropdown(hover)、Menu
+ */
+export declare function useHoverIntent(options?: HoverIntentOptions): HoverIntentReturn;
+//#endregion
+//#region src/behavior/useListboxNavigation.d.ts
+interface ListboxNavigationOptions {
+  /** 选项总数（响应式） */
+  count: MaybeRefOrGetter<number>;
+  /** 禁用项判定 */
+  isItemDisabled?: (index: number) => boolean;
+  /** 导航方向，默认 vertical */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+  /** 边界循环，默认 true */
+  loop?: boolean;
+  /** 初始激活索引，默认 -1（尚未激活，首次按键落到首项） */
+  initialIndex?: number;
+  /** 回车 / 空格选中时回调 */
+  onSelect?: (index: number) => void;
+  /** 激活项变化回调（用于滚动到可视区） */
+  onActiveChange?: (index: number) => void;
+}
+interface ListboxNavigationReturn {
+  activeIndex: Ref<number>;
+  setActiveIndex: (index: number) => void;
+  moveNext: () => void;
+  movePrev: () => void;
+  moveFirst: () => void;
+  moveLast: () => void;
+  /** 绑定到列表容器：方向键移动、回车/空格选中 */
+  onKeydown: (event: KeyboardEvent) => void;
+  reset: () => void;
+}
+/**
+ * 选项列表键盘导航：上下移动、Home/End、回车选中、禁用项跳过、边界循环。
+ * 与焦点管理解耦——本函数只维护逻辑激活索引。
+ *
+ * @internal 消费组件：Select、Dropdown、Menu、Cascader、AutoComplete、
+ * Mention、Segmented、TreeSelect、TimePicker
+ */
+export declare function useListboxNavigation(options: ListboxNavigationOptions): ListboxNavigationReturn;
+//#endregion
+//#region src/behavior/useAsyncState.d.ts
+interface UseAsyncStateOptions<T, A extends unknown[]> {
+  /** 初始 data，默认 undefined */
+  initialData?: T;
+  /** 是否立即以初始参数执行一次，默认 true */
+  immediate?: boolean;
+  /** 立即执行时的参数 */
+  immediateArgs?: A;
+  /** 重新拉取时保留旧数据并标记 isStale，默认 true */
+  preserveDataOnRefresh?: boolean;
+  /** 成功回调 */
+  onSuccess?: (data: T, ...args: A) => void;
+  /** 失败回调 */
+  onError?: (error: unknown, ...args: A) => void;
+}
+interface UseAsyncStateReturn<T, A extends unknown[]> {
+  state: Ref<AsyncStateLike<T>>;
+  /** 手动执行请求；再次执行时已有成功数据会标记 isStale */
+  run: (...args: A) => Promise<T | undefined>;
+  /** 以最近一次参数重试 */
+  retry: () => Promise<T | undefined>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+}
+/**
+ * 将外部异步函数包装为标准 AsyncStateLike：
+ * 管理 pending/success/error 三态、重试与 stale 标记。
+ * 函数自身不发起任何业务请求——请求函数由宿主提供。
+ *
+ * @param fetcher 返回 Promise 的数据获取函数
+ * @internal 消费方：远程 Select/AutoComplete/Mention；Table 内联编排；宿主可独立使用
+ */
+export declare function useAsyncState<T, A extends unknown[] = []>(fetcher: (...args: A) => Promise<T>, options?: UseAsyncStateOptions<T, A>): UseAsyncStateReturn<T, A>;
+//#endregion
+//#region src/behavior/useActionState.d.ts
+/** 归一 action 返回值：resolve 值导出错误（status 为 error 或携带 error）时返回失败信息，否则 null */
+export declare function extractActionFailure(result: unknown): {
+  error: unknown;
+} | null;
+/** 把动作错误归一为可展示文案：优先 message，其次 error 字符串 / Error.message，最后回退文案 */
+export declare function actionErrorText(error: unknown, fallback?: string): string;
+interface UseActionStateOptions {
+  /** 执行期间是否派生 disabled，默认 true */
+  disableOnPending?: boolean;
+  /** 外部附加禁用条件（响应式值通过 getter 传入） */
+  disabled?: () => boolean;
+  /** 成功回调 */
+  onSuccess?: (result: unknown) => void;
+  /** 失败回调（不抛出，错误归一存放在 error） */
+  onError?: (error: unknown) => void;
+  /** 无论成功失败的收尾回调 */
+  onFinally?: () => void;
+}
+interface UseActionStateReturn {
+  pending: Ref<boolean>;
+  disabled: Ref<boolean>;
+  error: Ref<unknown>;
+  /** 执行动作；同一时刻重复调用会被忽略 */
+  run: (...args: unknown[]) => Promise<unknown>;
+}
+/**
+ * 消费 ActionLike：执行期间自动派生 pending / disabled，错误归一存储。
+ *
+ * @internal 消费组件：Button、Switch、Popconfirm、Upload、Form 提交
+ */
+export declare function useActionState(action?: ActionLike, options?: UseActionStateOptions): UseActionStateReturn;
+//#endregion
+//#region src/behavior/useActionValue.d.ts
+interface UseActionValueReturn {
+  /** 动作执行中，期间组件应禁用新的交互 */
+  pending: Ref<boolean>;
+  /** 最近一次失败的错误信息 */
+  error: Ref<unknown>;
+  /**
+   * 乐观提交：组件先应用新值，再调用 commit 执行动作。
+   * 失败（reject 或返回值导出错误）时记录 error、执行 revert 回退并返回 false；
+   * 无 execute 时视为无动作，直接成功。同一时刻重复调用会被忽略。
+   */
+  commit: (options: {
+    execute?: () => unknown;
+    revert?: () => void;
+  }) => Promise<boolean>;
+}
+/**
+ * 切换型组件的 action 消费：值变更先乐观应用，动作失败自动回退并记录错误。
+ *
+ * @internal 消费组件：Select、DatePicker、ColorPicker、Transfer、Rate、Segmented、Tabs 等即时变更组件
+ */
+export declare function useActionValue(): UseActionValueReturn;
+//#endregion
+//#region src/behavior/useToastQueue.d.ts
+type ToastType = 'info' | 'success' | 'warning' | 'error' | 'loading';
+interface ToastItem<T = unknown> {
+  id: number;
+  type: ToastType;
+  content: string;
+  title?: string;
+  duration: number;
+  /** 自定义载荷（动作文案、图标等渲染所需数据） */
+  meta?: T;
+  /** 悬停暂停期间剩余时长，关闭后为 0 */
+  remaining: number;
+  /** 是否常驻（duration <= 0），需手动关闭 */
+  closable: boolean;
+}
+interface UseToastQueueOptions {
+  /** 默认自动关闭时长，默认 3000ms；<=0 表示常驻 */
+  duration?: number;
+  /** 同时存在的最大条数，超出挤出最早项，默认 5 */
+  max?: number;
+  /** 去重：相同 type+content 时不重复入队，默认 true */
+  dedupe?: boolean;
+}
+interface PushToastOptions<T = unknown> {
+  duration?: number;
+  title?: string;
+  meta?: T;
+  closable?: boolean;
+}
+interface UseToastQueueReturn<T = unknown> {
+  items: Ref<Array<ToastItem<T>>>;
+  count: Ref<number>;
+  push: (type: ToastType, content: string, options?: PushToastOptions<T>) => ToastItem<T>;
+  remove: (id: number) => void;
+  clear: () => void;
+  /** 悬停暂停计时（不清零剩余时长） */
+  pause: (id: number) => void;
+  /** 恢复计时 */
+  resume: (id: number) => void;
+}
+/**
+ * 命令式浮层队列：堆叠管理、去重、自动关闭、悬停暂停、手动销毁。
+ * 只管理数据与计时，不渲染任何 DOM——渲染由 Message/Notification 组件承担。
+ *
+ * @internal 消费方：createMessage、createNotification
+ */
+export declare function useToastQueue<T = unknown>(options?: UseToastQueueOptions): UseToastQueueReturn<T>;
+//#endregion
+//#region src/behavior/useOverlayContainer.d.ts
+interface OverlayContainerOptions {
+  /**
+   * Teleport 目标：
+   * - 选择器字符串（'#app' / '.xxx'）
+   * - 元素引用
+   * - 不传时使用 document.body
+   */
+  to?: string | HTMLElement;
+  /** 选择器 / 元素不存在时是否回退到 body，默认 true */
+  fallbackToBody?: boolean;
+}
+/**
+ * Teleport 目标容器的 SSR 安全解析。挂载后才访问 document，
+ * 选择器不存在时按策略回退到 body。
+ *
+ * @internal 消费组件：全部 Teleport 浮层
+ */
+export declare function useOverlayContainer(options?: OverlayContainerOptions): {
+  container: Ref<HTMLElement | null>;
+};
+//#endregion
+//#region src/behavior/useFormContext.d.ts
+/**
+ * 表单上下文：useForm 提供整表模型，useFormField 注入后完成
+ * 字段注册、规则继承与提交/重置联动；FormItem 再向具体控件注入字段上下文。
+ */
+interface FormFieldContext {
+  /** 字段名 */
+  name: string | number;
+  /** 当前校验错误信息（无错误为 undefined） */
+  error?: string;
+  /** 是否被触碰过（blur 后置 true） */
+  touched: boolean;
+  /** 控件 id（label/aria 关联） */
+  fieldId: string;
+  /** 校验状态变化时由控件调用 */
+  setError?: (error: string | undefined) => void;
+}
+/** 字段注册到表单时提供的控制器 */
+interface FormFieldController {
+  validate: () => Promise<string | true> | string | true;
+  reset: () => void;
+  clearValidate: () => void;
+  getValue?: () => unknown;
+  setValue?: (value: unknown) => void;
+}
+interface FormContext {
+  /** 整表值的只读快照（响应式对象） */
+  values: Record<string, unknown>;
+  /** 整表校验错误映射 */
+  errors: Record<string, string | undefined>;
+  /** 注册字段，返回注销函数 */
+  registerField: (name: string | number, controller: FormFieldController) => () => void;
+  /** 读取字段在表单规则中的校验器 */
+  getFieldRules?: (name: string | number) => unknown;
+  /** 提交表单（经 useForm 编排，触发校验与 submit 事件） */
+  submit: () => Promise<void>;
+  /** 重置整表 */
+  reset: () => void;
+  /** 字段值变化时回写整表聚合值 */
+  setFieldValue?: (name: string | number, value: unknown) => void;
+  /** 是否禁用整表 */
+  disabled?: boolean;
+  /** label 位置等布局信息（仅传递，不参与逻辑） */
+  labelPosition?: 'left' | 'right' | 'top';
+}
+/** useForm 注册整表上下文 */
+export declare function provideForm(context: FormContext): void;
+/** 表单控件 / FormItem 注入整表上下文，未处于表单中时返回 undefined */
+export declare function injectForm(): FormContext | undefined;
+/** FormItem 注册字段上下文（向内部控件传递错误、id 等） */
+export declare function provideFormField(context: FormFieldContext): void;
+/** 具体表单控件注入所属字段上下文 */
+export declare function injectFormField(): FormFieldContext | undefined;
+//#endregion
+//#region src/form/form-types.d.ts
+/**
+ * 表单领域共享类型。
+ */
+/** 校验规则：返回 true 通过，返回字符串作为错误信息；支持异步 */
+type FormRule<T = unknown> = (value: T, values: Record<string, unknown>) => string | true | Promise<string | true>;
+/** 必填规则的简写配置（由组件内构造为 FormRule） */
+interface FieldRuleConfig<T = unknown> {
+  required?: boolean;
+  message?: string;
+  validator?: FormRule<T>;
+  trigger?: 'change' | 'blur' | 'submit';
+}
+type FormRules<T extends Record<string, unknown>> = Partial<Record<keyof T, Array<FormRule> | FormRule>>;
+//#endregion
+//#region src/form/useForm.d.ts
+interface UseFormOptions<T extends Record<string, unknown>> {
+  /** 受控整表值 */
+  modelValue?: MaybeRefOrGetter<T>;
+  /** 非受控初始值 */
+  defaultValue?: T;
+  /** 字段规则（也可由各 useFormField 传入，按字段名合并） */
+  rules?: MaybeRefOrGetter<FormRules<T>>;
+  disabled?: boolean;
+  labelPosition?: 'left' | 'right' | 'top';
+  /** 值变化回调（受控时即 update:modelValue） */
+  onChange?: (values: T) => void;
+  /** 校验通过后的提交回调 */
+  onSubmit?: (values: T) => void | Promise<void>;
+  /** 校验失败回调 */
+  onInvalid?: (errors: Record<string, string | undefined>) => void;
+}
+interface UseFormReturn<T extends Record<string, unknown>> {
+  values: T;
+  errors: Record<string, string | undefined>;
+  touched: Record<string, boolean>;
+  valid: ReturnType<typeof computed<boolean>>;
+  dirty: ReturnType<typeof computed<boolean>>;
+  registerField: (name: string | number, controller: FormFieldController) => () => void;
+  validateField: (name: string | number) => Promise<string | true>;
+  validate: () => Promise<boolean>;
+  clearValidate: (name?: string | number) => void;
+  setFieldValue: (name: string | number, value: unknown) => void;
+  resetField: (name: string | number) => void;
+  reset: () => void;
+  submit: () => Promise<void>;
+  context: FormContext;
+}
+/**
+ * 无头表单模型：字段注册/注销、整表聚合值、同步/异步规则校验、
+ * 提交、重置与脏检查。组件只负责布局与错误提示渲染。
+ */
+export declare function useForm<T extends Record<string, unknown>>(options?: UseFormOptions<T>): UseFormReturn<T>;
+//#endregion
+//#region src/form/useFormField.d.ts
+interface UseFormFieldOptions<T> {
+  /** 字段名；处于表单上下文中时用于注册与聚合 */
+  name?: string | number;
+  modelValue?: MaybeRefOrGetter<T>;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
+  /** 字段级规则（会与表单同名规则合并执行） */
+  rules?: Array<FormRule> | FormRule;
+  /** blur 时触发校验，默认 true */
+  validateOnBlur?: boolean;
+  /** change 时触发校验（仅在校验过一次或触碰后生效），默认 true */
+  validateOnChange?: boolean;
+  /** 外部禁用条件 */
+  disabled?: MaybeRefOrGetter<boolean>;
+  /** id 前缀 */
+  idPrefix?: string;
+}
+interface UseFormFieldReturn<T> {
+  value: WritableComputedRef<T>;
+  error: ReturnType<typeof ref<string | undefined>>;
+  touched: ReturnType<typeof ref<boolean>>;
+  valid: ReturnType<typeof computed<boolean>>;
+  disabled: ReturnType<typeof computed<boolean>>;
+  fieldId: ReturnType<typeof useId>;
+  errorId: ReturnType<typeof useId>;
+  /** 绑定到控件的 aria 属性集合 */
+  aria: ReturnType<typeof computed<Record<string, unknown>>>;
+  /** 值变化统一入口（同步 v-model + 按策略校验） */
+  handleChange: (next: T) => void;
+  /** blur 统一入口 */
+  handleBlur: () => void;
+  validate: () => Promise<string | true>;
+  reset: () => void;
+  clearValidate: () => void;
+}
+/**
+ * 单字段模型：值的受控/非受控统一、校验信息、touched 状态、
+ * aria 注入与表单上下文联动。所有表单控件共用。
+ */
+export declare function useFormField<T>(options?: UseFormFieldOptions<T>): UseFormFieldReturn<T>;
+//#endregion
+//#region src/form/useCheckableGroup.d.ts
+interface CheckableGroupOptions<V> {
+  /** true 为多选（值数组），false 为单选互斥，默认 true */
+  multiple?: boolean;
+  modelValue?: V[] | V | null;
+  defaultValue?: V[] | V | null;
+  onChange?: (value: V[] | V | null) => void;
+  /** 多选时可选值全集（用于全选/半选推导与数量约束） */
+  options?: () => V[];
+  /** 多选时最少选中数 */
+  min?: number;
+  /** 多选时最多选中数 */
+  max?: number;
+  /** 禁用项判定 */
+  isOptionDisabled?: (value: V) => boolean;
+}
+interface CheckableGroupReturn<V> {
+  /** 单选当前值 / 多选当前值数组 */
+  model: ReturnType<typeof useControllableModel<V[] | V | null>>['value'];
+  /** 某选项是否选中 */
+  isChecked: (value: V) => boolean;
+  /** 勾选 / 取消勾选（单选时直接替换） */
+  select: (value: V, checked?: boolean) => void;
+  /** 多选切换某项 */
+  toggle: (value: V) => void;
+  /** 多选：是否全选 */
+  allChecked: ReturnType<typeof computed<boolean>>;
+  /** 多选：是否半选（选了一部分） */
+  indeterminate: ReturnType<typeof computed<boolean>>;
+  /** 多选：全选 / 取消全选 */
+  toggleAll: (checked?: boolean) => void;
+  /** 多选：当前选中数量 */
+  checkedCount: ReturnType<typeof computed<number>>;
+}
+/**
+ * 成组勾选值管理：多选数组（增删、全选、半选、数量约束）与单选互斥。
+ *
+ * @internal 消费组件：CheckboxGroup、RadioGroup
+ */
+export declare function useCheckableGroup<V>(options?: CheckableGroupOptions<V>): CheckableGroupReturn<V>;
+//#endregion
+//#region src/form/useSelectModel.d.ts
+interface SelectOption<V = string | number, L = string> {
+  value: V;
+  label: L;
+  disabled?: boolean;
+  /** 选项分组标题（扁平数据中用于分组组织） */
+  group?: string;
+}
+interface UseSelectModelOptions<V, L> {
+  /** 全部选项（响应式） */
+  options: MaybeRefOrGetter<Array<SelectOption<V, L>>>;
+  /** 单选当前值 / 多选值数组 */
+  modelValue?: MaybeRefOrGetter<V | V[] | null>;
+  defaultValue?: V | V[] | null;
+  onChange?: (value: V | V[] | null) => void;
+  multiple?: boolean;
+  /** 是否可搜索（启用 keyword 与本地过滤） */
+  filterable?: boolean;
+  /** 自定义过滤谓词，默认按 label 包含匹配 */
+  filterMethod?: (option: SelectOption<V, L>, keyword: string) => boolean;
+  /** 值比较器，默认 Object.is */
+  equals?: (a: V, b: V) => boolean;
+}
+interface UseSelectModelReturn<V, L> {
+  /** 当前值（单选 V / 多选 V[]） */
+  model: Ref<V | V[] | null>;
+  /** 已选中的完整选项对象（用于标签回显） */
+  selectedOptions: Ref<Array<SelectOption<V, L>>>;
+  /** 单选已选标签（无选中为 undefined） */
+  selectedLabel: Ref<L | undefined>;
+  keyword: Ref<string>;
+  /** 按搜索词过滤后的选项 */
+  filteredOptions: Ref<Array<SelectOption<V, L>>>;
+  isSelected: (option: SelectOption<V, L>) => boolean;
+  /** 选中 / 取消选中；返回是否发生了变化 */
+  selectOption: (option: SelectOption<V, L>, checked?: boolean) => boolean;
+  /** 多选移除某个已选标签 */
+  removeValue: (value: V) => void;
+  clear: () => void;
+  setKeyword: (keyword: string) => void;
+}
+/**
+ * 选择器值模型：单选/多选值、选项标签回显、本地过滤、清除。
+ * 不发请求、不管浮层开合（分别由 useAsyncState / useOpen 承担）。
+ *
+ * @internal 消费组件：Select、TreeSelect
+ */
+export declare function useSelectModel<V = string | number, L = string>(options: UseSelectModelOptions<V, L>): UseSelectModelReturn<V, L>;
+//#endregion
+//#region src/form/useTreeModel.d.ts
+interface TreeFieldNames {
+  value: string;
+  label: string;
+  children: string;
+  disabled: string;
+  /** 叶子标记字段；显式 false 表示“尚未加载子级”的父节点（远程懒加载） */
+  isLeaf: string;
+}
+interface TreeFlatNode<V = string | number> {
+  key: V;
+  label: string;
+  depth: number;
+  disabled: boolean;
+  isLeaf: boolean;
+  parentKey: V | null;
+  childKeys: V[];
+  /** 全部后代叶子的 key（含自身为叶子的情况） */
+  leafKeys: V[];
+  /** 原始数据节点 */
+  raw: Record<string, unknown>;
+}
+interface UseTreeModelOptions<V = string | number> {
+  data: MaybeRefOrGetter<Array<Record<string, unknown>>>;
+  fieldNames?: Partial<TreeFieldNames>;
+  /** 勾选值（受控） */
+  modelValue?: V[];
+  defaultValue?: V[];
+  onChange?: (keys: V[]) => void;
+  /** 展开值（受控） */
+  expandedKeys?: V[];
+  defaultExpandedKeys?: V[];
+  onExpandedChange?: (keys: V[]) => void;
+  /** 父子是否联动勾选，默认 true；false 时只切换节点自身 */
+  cascade?: boolean;
+}
+interface UseTreeModelReturn<V = string | number> {
+  /** 扁平化的全部节点 */
+  flatNodes: ComputedRef<Array<TreeFlatNode<V>>>;
+  /** 当前可见节点（受展开集合过滤），按深度优先顺序 */
+  visibleNodes: ComputedRef<Array<TreeFlatNode<V>>>;
+  checkedKeys: Ref<V[]>;
+  expandedKeys: Ref<V[]>;
+  getNode: (key: V) => TreeFlatNode<V> | undefined;
+  isExpanded: (key: V) => boolean;
+  setExpanded: (key: V, expanded: boolean) => void;
+  toggleExpand: (key: V) => void;
+  expandAll: () => void;
+  collapseAll: () => void;
+  isChecked: (key: V) => boolean;
+  isIndeterminate: (key: V) => boolean;
+  halfCheckedKeys: ComputedRef<V[]>;
+  check: (key: V, checked?: boolean) => void;
+  setCheckedKeys: (keys: V[]) => void;
+}
+/**
+ * 树形数据模型：展开集合、勾选集合（级联传播与半选推导）、
+ * 可见节点扁平化。不渲染任何缩进 / 连接线（由组件内联）。
+ *
+ * @internal 消费组件：Tree、TreeSelect
+ */
+export declare function useTreeModel<V extends string | number = string | number>(options: UseTreeModelOptions<V>): UseTreeModelReturn<V>;
+//#endregion
+//#region src/form/useAsyncSuggest.d.ts
+type SuggestStatus = 'idle' | 'pending' | 'success' | 'error';
+interface UseAsyncSuggestOptions<S> {
+  /** 异步建议源：输入关键词返回候选列表 */
+  fetch: (keyword: string) => Promise<S[]>;
+  /** 防抖时长，默认 300ms */
+  debounce?: number;
+  /** 挂载后是否立即以空关键词请求一次，默认 false */
+  immediate?: boolean;
+  /** 触发请求的最小关键词长度，默认 0 */
+  minKeywordLength?: number;
+  onSuccess?: (suggestions: S[], keyword: string) => void;
+  onError?: (error: unknown) => void;
+}
+interface UseAsyncSuggestReturn<S> {
+  suggestions: Ref<S[]>;
+  status: Ref<SuggestStatus>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  keyword: Ref<string>;
+  /** 更新关键词并按防抖触发请求（过短则清空建议） */
+  setKeyword: (keyword: string) => void;
+  /** 立即以指定关键词（默认当前关键词）请求 */
+  run: (keyword?: string) => Promise<void>;
+  clear: () => void;
+}
+/**
+ * 输入防抖 → 调用异步建议源 → loading/空态管理。
+ * 竞态请求以最后一次为准，旧响应被丢弃。
+ *
+ * @internal 消费组件：AutoComplete、Mention
+ */
+export declare function useAsyncSuggest<S>(options: UseAsyncSuggestOptions<S>): UseAsyncSuggestReturn<S>;
+//#endregion
+//#region src/form/useDateGrid.d.ts
+type DatePanelType = 'date' | 'month' | 'year';
+interface DateCell {
+  date: Date;
+  /** 是否属于当前面板月份（外部填充格为 false） */
+  inMonth: boolean;
+  isToday: boolean;
+  disabled: boolean;
+  isWeekend: boolean;
+}
+interface LabeledCell {
+  /** 该格代表的日期锚点（月格为该月 1 号，年格为该年 1 月 1 号） */
+  date: Date;
+  label: string;
+  disabled: boolean;
+  /** 年面板下该十年段的实际范围 */
+  inPanel: boolean;
+}
+interface UseDateGridOptions {
+  /** 面板视角日期（内部默认今天，多面板时可外部注入） */
+  viewDate?: Ref<Date>;
+  type?: DatePanelType;
+  /** 每周第一天：0=周日，1=周一，默认 1 */
+  firstDayOfWeek?: 0 | 1;
+  disabledDate?: (date: Date) => boolean;
+  /** 选中态标记（单选） */
+  isSelected?: (date: Date) => boolean;
+  /** 范围区间内标记（含悬停预览） */
+  isInRange?: (date: Date) => boolean;
+  isRangeStart?: (date: Date) => boolean;
+  isRangeEnd?: (date: Date) => boolean;
+}
+interface MarkedDateCell extends DateCell {
+  selected: boolean;
+  inRange: boolean;
+  rangeStart: boolean;
+  rangeEnd: boolean;
+}
+interface UseDateGridReturn {
+  viewDate: Ref<Date>;
+  panelType: Ref<DatePanelType>;
+  setPanelType: (type: DatePanelType) => void;
+  /** 星期表头索引序列（0~6，按 firstDayOfWeek 轮转） */
+  weekdayOrder: ComputedRef<number[]>;
+  /** 日期面板：6 行 × 7 列 */
+  weeks: ComputedRef<MarkedDateCell[][]>;
+  /** 月份面板：12 个月 */
+  months: ComputedRef<LabeledCell[]>;
+  /** 年份面板：10 年段（12 格，含上/下一年段填充） */
+  years: ComputedRef<LabeledCell[]>;
+  panelLabel: ComputedRef<string>;
+  prevView: () => void;
+  nextView: () => void;
+  goToDate: (date: Date) => void;
+}
+/**
+ * 日历网格纯计算：月首偏移、当月天数、外部填充、周末/禁用/选中/范围标记。
+ * 同一模型驱动 DatePicker 与 Calendar；多面板由组件内创建多个实例实现。
+ */
+export declare function useDateGrid(options?: UseDateGridOptions): UseDateGridReturn;
+//#endregion
+//#region src/form/useDateModel.d.ts
+type DateGranularity = 'day' | 'month' | 'year';
+interface DateShortcut {
+  label: string;
+  value: Date | [Date, Date];
+}
+interface UseDateModelOptions {
+  /** 单选值（字符串 / Date），与 range 二选一 */
+  modelValue?: string | Date | null;
+  defaultValue?: string | Date | null;
+  /** 范围值：[起, 止]，字符串可为 null 占位 */
+  rangeModelValue?: [string | Date | null, string | Date | null] | null;
+  defaultRangeValue?: [string | Date | null, string | Date | null] | null;
+  onChange?: (value: string | Date | null | [string | null, string | null] | null) => void;
+  range?: boolean;
+  /** 选择粒度：day=完整日期，month=年月，year=年 */
+  granularity?: DateGranularity;
+  format?: string;
+  minDate?: string | Date;
+  maxDate?: string | Date;
+  disabledDate?: (date: Date) => boolean;
+  shortcuts?: DateShortcut[];
+}
+interface UseDateModelReturn {
+  /** 单选模型（字符串） */
+  model: Ref<string | Date | null>;
+  /** 范围模型（字符串对） */
+  rangeModel: Ref<[string | null, string | null] | null>;
+  selectedDate: ComputedRef<Date | null>;
+  rangeDates: ComputedRef<[Date | null, Date | null]>;
+  viewDate: Ref<Date>;
+  /** 范围选择中已选起点、等待终点时的悬停日期 */
+  hoverDate: Ref<Date | null>;
+  /** 输入框回显文本（范围为 '起 ~ 止'） */
+  displayText: ComputedRef<string>;
+  isSelected: (date: Date) => boolean;
+  isDisabled: (date: Date) => boolean;
+  isInRange: (date: Date) => boolean;
+  isRangeStart: (date: Date) => boolean;
+  isRangeEnd: (date: Date) => boolean;
+  /** 选择日期：范围模式内部处理起止两段式提交 */
+  selectDate: (date: Date) => void;
+  setHoverDate: (date: Date | null) => void;
+  selectShortcut: (shortcut: DateShortcut) => void;
+  clear: () => void;
+  prevMonth: () => void;
+  nextMonth: () => void;
+  goToDate: (date: Date) => void;
+  format: (date: Date | null) => string;
+}
+/**
+ * 日期值模型：解析/格式化、粒度（日/月/年）、范围两段式选择、
+ * 最小/最大与禁用限制、快捷选项。不负责网格计算（见 useDateGrid）。
+ *
+ * @internal 消费组件：DatePicker、Calendar
+ */
+export declare function useDateModel(options?: UseDateModelOptions): UseDateModelReturn;
+//#endregion
+//#region src/form/useTimeModel.d.ts
+interface TimeColumnItem {
+  value: number;
+  label: string;
+  disabled: boolean;
+}
+interface UseTimeModelOptions {
+  /** 'HH:mm:ss' 或 'HH:mm'，默认 'HH:mm:ss' */
+  modelValue?: string | null;
+  defaultValue?: string | null;
+  onChange?: (value: string | null) => void;
+  hourStep?: number;
+  minuteStep?: number;
+  secondStep?: number;
+  /** 是否使用秒列，默认 true */
+  useSeconds?: boolean;
+  /** 最早可选时间 'HH:mm[:ss]' */
+  minTime?: string;
+  /** 最晚可选时间 'HH:mm[:ss]' */
+  maxTime?: string;
+}
+interface UseTimeModelReturn {
+  model: Ref<string | null>;
+  hour: Ref<number | null>;
+  minute: Ref<number | null>;
+  second: Ref<number | null>;
+  hourColumn: ComputedRef<TimeColumnItem[]>;
+  minuteColumn: ComputedRef<TimeColumnItem[]>;
+  secondColumn: ComputedRef<TimeColumnItem[]>;
+  displayText: ComputedRef<string>;
+  setHour: (value: number) => void;
+  setMinute: (value: number) => void;
+  setSecond: (value: number) => void;
+  setUnit: (unit: 'hour' | 'minute' | 'second', value: number) => void;
+  now: () => void;
+  clear: () => void;
+  confirm: () => string | null;
+}
+/**
+ * 时间选择模型：时/分/秒三列数据与步进、范围限制、回写与回显。
+ * 滚动列渲染与确认按钮编排由 TimePicker 组件承担。
+ *
+ * @internal 消费组件：TimePicker、DatePicker（日期时间模式）
+ */
+export declare function useTimeModel(options?: UseTimeModelOptions): UseTimeModelReturn;
+//#endregion
+//#region src/overlay/useModal.d.ts
+interface UseModalOptions extends ControlledProps<boolean> {
+  /** 点击遮罩是否关闭，默认 true */
+  maskClosable?: boolean;
+  /** ESC 是否关闭，默认 true */
+  escClosable?: boolean;
+  /** 打开时是否锁定背景滚动，默认 true */
+  lockScroll?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+interface UseModalReturn {
+  isOpen: Ref<boolean>;
+  open: () => void;
+  close: () => void;
+  toggle: (next?: boolean) => void;
+  /** 绑定到模态内容容器（焦点陷阱需要） */
+  contentRef: Ref<HTMLElement | null>;
+  /** 进出场过渡挂载状态 */
+  rendered: Ref<boolean>;
+  visible: Ref<boolean>;
+  onAfterLeave: () => void;
+  /** 当前层级（每次打开重新分配） */
+  zIndex: Ref<number>;
+  /** 遮罩点击：按 maskClosable 决定是否关闭 */
+  onMaskClick: () => void;
+}
+/**
+ * 模态开合编排：useOpen + 滚动锁定 + 焦点陷阱/归还 + ESC + 层级 +
+ * 进出场过渡。Dialog/Drawer 共用，差异仅在方向与尺寸（组件内联）。
+ */
+export declare function useModal(options?: UseModalOptions): UseModalReturn;
+//#endregion
+//#region src/overlay/usePopoverModel.d.ts
+type PopoverTrigger = 'click' | 'hover' | 'focus' | 'manual';
+interface UsePopoverModelOptions extends ControlledProps<boolean> {
+  trigger?: PopoverTrigger;
+  openDelay?: number;
+  closeDelay?: number;
+}
+interface PopoverTriggerProps {
+  onClick?: () => void;
+  onMouseenter?: () => void;
+  onMouseleave?: () => void;
+  onFocus?: () => void;
+  onBlur?: () => void;
+}
+interface UsePopoverModelReturn {
+  isOpen: Ref<boolean>;
+  open: () => void;
+  close: () => void;
+  toggle: (next?: boolean) => void;
+  rendered: Ref<boolean>;
+  visible: Ref<boolean>;
+  onAfterLeave: () => void;
+  /** 直接绑定到触发元素的事件集合 */
+  triggerProps: Ref<PopoverTriggerProps>;
+  /** hover 模式下需同时绑定到浮层本体，防止触发器与浮层间移动时关闭 */
+  floatingHoverProps: Ref<PopoverTriggerProps>;
+}
+/**
+ * 浮层触发模型：click / hover / focus / manual 四种触发方式与
+ * 延迟开合、进出场过渡的组合编排。定位由 useFloating 独立承担。
+ *
+ * @internal 消费组件：Popover、Dropdown、Tooltip
+ */
+export declare function usePopoverModel(options?: UsePopoverModelOptions): UsePopoverModelReturn;
+//#endregion
+//#region src/overlay/createMessage.d.ts
+interface MessageOptions<T = unknown> extends PushToastOptions<T> {
+  type?: ToastType;
+}
+interface MessageApi {
+  /** 当前消息列表（渲染组件直接消费） */
+  items: Ref<Array<ToastItem>>;
+  /** 入队并返回消息 id */
+  push: (content: string, options?: MessageOptions) => number;
+  success: (content: string, duration?: number) => number;
+  warning: (content: string, duration?: number) => number;
+  info: (content: string, duration?: number) => number;
+  error: (content: string, duration?: number) => number;
+  loading: (content: string, duration?: number) => number;
+  remove: (id: number) => void;
+  clear: () => void;
+  pause: (id: number) => void;
+  resume: (id: number) => void;
+}
+/**
+ * 创建一套命令式消息服务。底层为共享响应式 toast 队列，
+ * 渲染由 Message 组件承担；宿主也可在不引入组件的情况下调用。
+ */
+export declare function createMessage(options?: {
+  duration?: number;
+  max?: number;
+}): MessageApi;
+/** 全局默认单例：所有 Message 组件与宿主共享同一队列 */
+export declare const message: MessageApi;
+//#endregion
+//#region src/overlay/createNotification.d.ts
+interface NotificationMeta {
+  title: string;
+  description?: string;
+  /** 动作文案等渲染数据 */
+  action?: unknown;
+  placement?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+}
+interface NotificationEntry {
+  id: number;
+  type: ToastType;
+  title: string;
+  description?: string;
+  duration: number;
+  meta?: NotificationMeta;
+}
+interface NotificationApi {
+  items: Ref<Array<NotificationEntry>>;
+  open: (type: ToastType, title: string, description?: string, duration?: number) => number;
+  success: (title: string, description?: string) => number;
+  warning: (title: string, description?: string) => number;
+  info: (title: string, description?: string) => number;
+  error: (title: string, description?: string) => number;
+  remove: (id: number) => void;
+  clear: () => void;
+}
+/**
+ * 创建命令式通知服务。消息体携带标题 / 描述 / 动作数据，
+ * 角落堆叠方向由渲染组件按 placement 分组。
+ */
+export declare function createNotification(options?: {
+  duration?: number;
+  max?: number;
+}): NotificationApi;
+/** 全局默认单例 */
+export declare const notification: NotificationApi;
+//#endregion
+//#region src/overlay/useLoadingService.d.ts
+interface LoadingService {
+  /** 计数大于 0 即视为加载中（多请求自动合并） */
+  loading: Ref<boolean>;
+  count: Ref<number>;
+  /** 开始一次加载，返回结束函数 */
+  start: () => () => void;
+  /** 结束一次加载 */
+  finish: () => void;
+  /** 包裹异步任务：开始 → 任务结束（成功或失败）自动结束 */
+  wrap: <T>(task: Promise<T>) => Promise<T>;
+  clear: () => void;
+}
+/** 创建一套隔离的计数式加载服务 */
+export declare function createLoadingService(): LoadingService;
+/**
+ * 局部 / 全屏加载的计数式服务（多请求合并显示一个加载态）。
+ * 需要隔离实例时使用 createLoadingService。
+ *
+ * @internal 消费组件：Loading
+ */
+export declare function useLoadingService(): LoadingService;
+//#endregion
+//#region src/data/usePagination.d.ts
+type PaginationPageItem = number | 'start-ellipsis' | 'end-ellipsis';
+interface UsePaginationOptions {
+  /** 当前页（受控；传 getter 保持外部变化的响应性） */
+  currentPage?: MaybeRefOrGetter<number>;
+  defaultCurrentPage?: number;
+  onPageChange?: (page: number) => void;
+  /** 页大小（受控；传 getter 保持外部变化的响应性） */
+  pageSize?: MaybeRefOrGetter<number>;
+  defaultPageSize?: number;
+  onPageSizeChange?: (size: number) => void;
+  /** 总条数，默认 0 */
+  total?: number;
+  /** 每页条数候选 */
+  pageSizes?: number[];
+  /** 当前页两侧始终展示的兄弟页数，默认 1 */
+  siblingCount?: number;
+  /** 首尾始终展示的页数，默认 1 */
+  boundaryCount?: number;
+  /** 页码或页大小变化统一回调（组件据此组装 change 事件参数） */
+  onChange?: (payload: {
+    currentPage: number;
+    pageSize: number;
+  }) => void;
+}
+interface UsePaginationReturn {
+  currentPage: Ref<number>;
+  pageSize: Ref<number>;
+  total: Ref<number>;
+  totalPages: Ref<number>;
+  pageSizes: number[];
+  /** 含省略号占位的页码序列 */
+  pages: Ref<PaginationPageItem[]>;
+  isFirst: Ref<boolean>;
+  isLast: Ref<boolean>;
+  canPrev: Ref<boolean>;
+  canNext: Ref<boolean>;
+  /** 起始条目序号（用于"第 x-y 条"展示） */
+  rangeStart: Ref<number>;
+  rangeEnd: Ref<number>;
+  go: (page: number) => void;
+  prev: () => void;
+  next: () => void;
+  setPageSize: (size: number) => void;
+}
+/**
+ * 分页模型：当前页 / 页大小、总页数、含省略号的页码序列、跳页与边界约束。
+ * 组件自身不发请求，go/setPageSize 只负责状态与 onChange 通知。
+ *
+ * @internal 消费组件：Pagination；Table 内联复用；宿主列表可独立使用
+ */
+export declare function usePagination(options?: UsePaginationOptions): UsePaginationReturn;
+//#endregion
+//#region src/data/fetch.d.ts
+/** 组件自动注入的分页参数，页码从 1 开始 */
+interface FetchPagination {
+  currentPage: number;
+  pageSize: number;
+}
+/** 排序状态 */
+interface FetchSorter {
+  key: string;
+  order: 'asc' | 'desc' | null;
+}
+/**
+ * 统一查询参数：组件按自身交互产生其中片段，字段全部可选。
+ * 宿主 fetch 方法按需消费，不使用的片段忽略即可。
+ */
+interface FetchQuery<TFilters = Record<string, unknown>> {
+  /** 分页（表格、虚拟列表等） */
+  pagination?: FetchPagination;
+  /** 关键词（远程搜索、输入建议） */
+  keyword?: string;
+  /** 排序 */
+  sorter?: FetchSorter;
+  /** 业务筛选：列筛选、父节点 key、日期范围等，形状由宿主与组件约定 */
+  filters?: TFilters;
+  /** 取消信号：新请求发起时上一次请求会被 abort */
+  signal?: AbortSignal;
+}
+/** 分页结果：fetch 方法返回此形态时，组件自动启用分页并回填总数 */
+interface PagedResult<T> {
+  list: T[];
+  total: number;
+}
+/** fetch 方法的原始返回：数组为列表，{ list, total } 为分页，其余视为单值 */
+type FetchResult<T> = T[] | PagedResult<T> | T;
+/**
+ * 所有组件 fetch 属性的统一方法类型。
+ * 列表组件返回 `T[]` 或 `PagedResult<T>`，单值组件返回 `T`。
+ */
+type Fetch<T, TFilters = Record<string, unknown>> = (query: FetchQuery<TFilters>) => Promise<FetchResult<T>>;
+/** 归一化后的结果 */
+interface NormalizedFetch<T> {
+  data: T[] | T;
+  total?: number;
+  raw: FetchResult<T>;
+}
+/** 判断是否为分页结果形态 */
+export declare function isPagedResult<T>(value: unknown): value is PagedResult<T>;
+/** 归一化：数组 → 列表；{ list, total } → 分页；其他 → 单值 */
+export declare function normalizeFetchResult<T>(raw: FetchResult<T>): NormalizedFetch<T>;
+interface FetchController<T = unknown> {
+  run: (query: FetchQuery) => Promise<NormalizedFetch<T> | undefined>;
+  /** 以最近一次查询重新请求 */
+  refresh: () => Promise<NormalizedFetch<T> | undefined>;
+  abort: () => void;
+  state: Ref<AsyncStateLike<NormalizedFetch<T> | undefined>>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+}
+/**
+ * 创建资源请求控制器。纯工厂、无生命周期副作用，可在组件、组合函数或测试中使用。
+ * 不主动发起请求，首次调用由消费方（组件资源钩子或宿主）触发。
+ */
+export declare function createFetchController<T>(fetcher: Fetch<T>): FetchController<T>;
+/** useFetch 返回对象的品牌标记（内部识别用） */
+export declare const FETCH_RESOURCE: unique symbol;
+interface UseFetchReturn<T> {
+  /** 绑定给组件 fetch 属性的方法；也可独立调用 */
+  fetch: (query?: FetchQuery) => Promise<FetchResult<T> | undefined>;
+  /** 异步状态投影（AsyncStateLike 同形），初始为 pending */
+  state: ComputedRef<AsyncStateLike<T[] | T | undefined>>;
+  status: ComputedRef<'pending' | 'success' | 'error'>;
+  /** 最近一次成功的数据（列表或单值） */
+  data: ComputedRef<T[] | T | undefined>;
+  error: Ref<unknown>;
+  loading: ComputedRef<boolean>;
+  isStale: ComputedRef<boolean>;
+  /** 分页总数；非分页结果为数据条数；单值结果为 undefined */
+  total: Ref<number | undefined>;
+  /** 手动刷新（可携带查询片段） */
+  refresh: (query?: FetchQuery) => Promise<FetchResult<T> | undefined>;
+  /** 内部控制器（组件资源钩子识别复用，宿主无需关心） */
+  [FETCH_RESOURCE]: FetchController<T>;
+}
+/**
+ * 宿主侧资源封装：把一个 Fetch 方法升级为带响应式状态的对象。
+ * 不绑定组件时不会自动请求；组件接收其 `fetch` 后由组件机制驱动，
+ * 状态在组件内外共享同一份。
+ */
+export declare function useFetch<T>(fetcher: Fetch<T>): UseFetchReturn<T>;
+/** 组件 fetch 属性可接收的形态：裸 Fetch 方法或 useFetch 返回对象 */
+type FetchLike<T, TFilters = Record<string, unknown>> = Fetch<T, TFilters> | UseFetchReturn<T>;
+/** 判断是否为 useFetch 返回对象 */
+export declare function isUseFetchReturn<T>(value: FetchLike<T> | undefined): value is UseFetchReturn<T>;
+interface UseFetchResourceOptions<D> {
+  /** 响应式查询来源：deep 监听，变化即按防抖策略重新请求 */
+  getQuery: () => FetchQuery;
+  /** 占位数据（首次 pending 时渲染） */
+  initialData: D;
+  /** 从归一化结果映射为组件消费数据；默认直接取 data（数组或单值） */
+  mapData?: (normalized: NormalizedFetch<unknown>) => D;
+  /** 关键词防抖毫秒，默认 0 */
+  debounce?: number;
+  /**
+   * 结果合并。
+   * - 累积模式（虚拟列表触底加载）：与上一页数据拼接；
+   * - 懒加载模式（树/级联）：依据 query.filters.parentKey 将子级挂到已有树。
+   *
+   * 第三个参数为本次实际查询。分页查询回到第 1 页（筛选/搜索变化）时
+   * 钩子会先把数据重置为 initialData；无分页的懒加载查询不重置。
+   */
+  merge?: (previous: D, next: D, query: FetchQuery) => D;
+}
+interface FetchResource<D> {
+  /** 是否存在可用的 fetch 源（决定远程/本地分支） */
+  enabled: Ref<boolean>;
+  /** 异步状态；无 fetch 源时为 undefined，组件回退本地数据 */
+  state: ComputedRef<AsyncStateLike<D> | undefined>;
+  loading: ComputedRef<boolean>;
+  error: ComputedRef<unknown>;
+  /** 分页总数（非分页为数据条数，无 fetch 源时为 0） */
+  total: Ref<number>;
+  /** 手动重取；override 与当前查询浅合并，用于懒加载等命令式场景 */
+  refresh: (override?: Partial<FetchQuery>) => Promise<void>;
+}
+/**
+ * 组件内部统一资源机制：
+ * 挂载即请求；getQuery 的 deep 变化自动重取；防抖、竞态后到为准、stale 保留旧数据。
+ * 所有 fetch 型组件共用此钩子，开发者只绑定 fetch 方法即可。
+ */
+export declare function useFetchResource<D>(source: MaybeRefOrGetter<FetchLike<unknown> | undefined>, options: UseFetchResourceOptions<D>): FetchResource<D>;
+//#endregion
+//#region src/data/useSubscribe.d.ts
+/** 归一 subscribe 返回值：导出错误（status 为 error 或携带 error）时返回失败信息，否则 null */
+export declare function extractSubscribeFailure<T>(result: SubscribeResult<T> | undefined): {
+  error: unknown;
+} | null;
+interface UseSubscribeReturn<T> {
+  state: Ref<AsyncStateLike<T | undefined>>;
+  data: Ref<T | undefined>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  isStale: Ref<boolean>;
+  /** 重新执行订阅处理方法 */
+  refresh: () => Promise<void>;
+}
+/**
+ * 订阅型数据消费：挂载时调用处理方法，resolve 出数据后渲染，
+ * 失败时记录错误并保留旧数据（与 fetch 失败策略一致），支持 refresh 重试。
+ *
+ * @internal 消费组件：Table、Statistic、Tabs、Progress、Image 等所有数据展示类组件
+ */
+export declare function useSubscribe<T>(handler?: SubscribeHandler<T>): UseSubscribeReturn<T>;
+//#endregion
+//#region src/data/useChat.d.ts
+/**
+ * 聊天消息：id 是唯一锚点——历史与推送按 id 去重，
+ * 本地乐观消息以 __local_ 前缀临时占位，被服务端回显替换。
+ */
+interface ChatMessage {
+  /** 消息唯一标识 */
+  id: string | number;
+  /** 发送者展示名 */
+  sender?: string;
+  /** 消息内容 */
+  content: string;
+  /** 发送时间戳（毫秒） */
+  time?: number;
+  /** 是否自己发送：决定气泡方向 */
+  self?: boolean;
+  /** 发送状态：本地消息的中间态，服务端消息可缺省 */
+  status?: 'sending' | 'sent' | 'failed';
+}
+interface UseChatOptions {
+  /** 历史消息加载：注入分页查询，currentPage 递增表示更早一页；返回数组或 { list, total } */
+  fetch?: Fetch<ChatMessage[]>;
+  /** 新消息订阅：推送单条或数组；返回响应式数据时持续更新（经 useSubscribe 消费） */
+  subscribe?: SubscribeHandler<ChatMessage[] | ChatMessage>;
+  /** 发送动作：入参为消息内容，抛错或返回 error 结果即发送失败 */
+  send?: (content: string) => Promise<ActionResult | void>;
+  /** 历史分页每页条数，默认 20 */
+  pageSize?: number;
+}
+interface UseChatReturn {
+  /** 展示消息列表（含本地乐观消息），新消息追加在末尾 */
+  messages: Ref<ChatMessage[]>;
+  /** 发送中 */
+  sending: Ref<boolean>;
+  /** 加载更早历史中 */
+  loadingOlder: Ref<boolean>;
+  /** 是否还有更早的历史 */
+  hasMore: Ref<boolean>;
+  /** 最近一次发送失败文案 */
+  sendError: Ref<string | undefined>;
+  /** 历史加载失败文案 */
+  historyError: Ref<string | undefined>;
+  /** 发送消息：乐观上屏，成功返回落位消息，失败返回 undefined（消息保留为 failed 可重试） */
+  send: (content: string) => Promise<ChatMessage | undefined>;
+  /** 重试失败消息：移除原消息并按原内容重新发送 */
+  retry: (message: ChatMessage) => Promise<ChatMessage | undefined>;
+  /** 加载更早一页历史：结果前插去重 */
+  loadOlder: () => Promise<void>;
+}
+/**
+ * 聊天消息模型：fetch 管历史（向上翻页前插）、subscribe 管新消息（追加去重）、
+ * send 管发送（乐观上屏 + 失败保留重试）。
+ *
+ * @internal 消费组件：Chat
+ */
+export declare function useChat(options: UseChatOptions): UseChatReturn;
+//#endregion
+//#region src/resources/types.d.ts
+/**
+ * 资源池契约：解析器与池之间的唯一边界。
+ * 自定义解析器只负责把协议与约定翻译成 ResourceSchema，
+ * URL 拼装、路径参数替换、查询片段注入、请求体序列化等运行时行为全部由池完成。
+ */
+/** 资源操作支持的 HTTP 方法 */
+type ResourceMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** 资源操作：方法 + 路径模板 */
+interface ResourceOperation {
+  method: ResourceMethod;
+  /** 路径模板：{id} 占位在运行时以方法参数替换 */
+  path: string;
+}
+/** 统一查询片段 → 请求参数名的映射，未声明的字段回落默认名 */
+interface QueryNames {
+  /** 关键词参数名，默认 keyword */
+  keyword?: string;
+  /** 页码参数名（页码从 1 起），默认 page */
+  currentPage?: string;
+  /** 每页大小参数名，默认 pageSize */
+  pageSize?: string;
+  /** 排序参数名：值序列化为 key,order，无排序时不注入，默认 sorter */
+  sorter?: string;
+  /** 筛选参数名：设置时将 filters 对象整体 JSON 序列化为该参数；未设置时逐键展开为独立参数，数组值以逗号连接 */
+  filters?: string;
+}
+/** 列表响应形状：数组与总数在响应体中的点分路径；缺省时响应体即数组 */
+interface ListResponseMapping {
+  /** 列表数组在响应体中的路径，如 'records' 或 'data.list'；缺省为响应体本身 */
+  list?: string;
+  /** 总数在响应体中的路径，如 'total' 或 'meta.total'；缺省则不启用分页 */
+  total?: string;
+}
+/** 字段值类型：决定筛选与表单的控件选择 */
+type ResourceFieldType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum';
+/** 枚举选项 */
+interface ResourceFieldOption {
+  label: string;
+  value: string | number;
+}
+/** 字段元数据：视图中性的字段描述，columns / filters / properties 均按 scope 投影 */
+interface ResourceField {
+  /** 字段名：数据对象键 */
+  name: string;
+  /** 展示名，解析自文档描述，缺失回落字段名 */
+  label: string;
+  type: ResourceFieldType;
+  /** 内容格式：原样透传文档声明的 format（如 email / uri / int64），与 type 的保存格式互补 */
+  format?: string;
+  /** 枚举选项：type 为 enum 时提供，可直接喂给选项组件 */
+  options?: ResourceFieldOption[];
+  /** 表单场景是否必填 */
+  required?: boolean;
+  /** 出现场景标记：未标记的字段不进入任何投影 */
+  scope?: {
+    /** 出现在列表列 */
+    list?: boolean;
+    /** 作为筛选项 */
+    filter?: boolean;
+    /** 出现在创建表单 */
+    create?: boolean;
+    /** 出现在编辑表单 */
+    update?: boolean;
+  };
+}
+/** 列表列投影：与 Table 的 columns 属性形状对齐 */
+interface ResourceColumn {
+  key: string;
+  title: string;
+  /** 保存格式提示：字段 type 原样投影，供 Table 单元格竞选消费 */
+  type?: ResourceFieldType;
+  /** 内容格式提示：字段 format 原样透传（如 email / uri / int64） */
+  format?: string;
+  sortable?: boolean;
+  /** 枚举字段的筛选项（表头勾选面板） */
+  filters?: ResourceFieldOption[];
+}
+/** 单个资源的操作集合与元数据：未声明的操作不可用（只读资源仅声明 list / detail 即可） */
+interface ResourceDefinition {
+  list?: ResourceOperation;
+  detail?: ResourceOperation;
+  create?: ResourceOperation;
+  update?: ResourceOperation;
+  remove?: ResourceOperation;
+  queryNames?: QueryNames;
+  /** 列表响应形状，由解析器从文档响应结构中识别 */
+  response?: ListResponseMapping;
+  /** 字段元数据：columns / filters / properties 的唯一来源，文档缺失时为空数组 */
+  fields?: ResourceField[];
+}
+/** 资源表：元数据解析的唯一产物，也是池运行的唯一依据 */
+interface ResourceSchema {
+  resources: Record<string, ResourceDefinition>;
+}
+/** 元数据解析器：输入任意协议文档，输出资源表 */
+type MetadataParser = (doc: unknown, context: {
+  server: string;
+}) => ResourceSchema | Promise<ResourceSchema>;
+/** 请求描述：池生成、适配器消费 */
+interface ResourceRequest {
+  method: ResourceMethod;
+  url: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** 竞态取消：由消费侧的 FetchQuery 透传 */
+  signal?: AbortSignal;
+}
+/** 传输适配器：发起请求并 resolve 响应体（未提供时使用内置 fetch 实现） */
+type RequestAdapter = (request: ResourceRequest) => Promise<unknown>;
+/** useResources 选项 */
+interface UseResourcesOptions {
+  /** 服务器根地址：请求 URL = server + 操作路径 */
+  server: string;
+  /** 元数据文档地址：相对 server 或绝对 URL */
+  doc?: string;
+  /** 元数据解析器，默认 OpenAPI（Swagger）解析 */
+  parse?: MetadataParser;
+  /** 直接提供资源表：跳过文档加载与解析，协议完全自定义时的出口 */
+  schema?: ResourceSchema | (() => ResourceSchema | Promise<ResourceSchema>);
+  /** 传输适配器，默认基于 fetch */
+  request?: RequestAdapter;
+  /** 附加请求头：鉴权 token 等随每次请求注入 */
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /** 解析后的微调：改名、合并资源、调整参数映射与字段标记 */
+  refine?: (schema: ResourceSchema) => ResourceSchema | Promise<ResourceSchema>;
+}
+/** 资源客户端：请求方法与组件协议同形，字段元数据按组件属性形状投影 */
+interface ResourceClient<D = unknown> {
+  readonly name: string;
+  /** 列表：Fetch 形态，直接绑定 Table / Select / VirtualList 的 :fetch */
+  list(query?: FetchQuery): Promise<FetchResult<D>>;
+  /** 详情：Fetch 单值形态 */
+  detail(id: string | number): Promise<D>;
+  /** 创建：ActionLike 形态，直接绑定 Form 的 :action */
+  create(payload: unknown): Promise<ActionResult | void>;
+  /** 更新：ActionLike 形态 */
+  update(id: string | number, payload: unknown): Promise<ActionResult | void>;
+  /** 删除：ActionLike 形态，直接绑定 Popconfirm / Button 的 :action */
+  remove(id: string | number): Promise<ActionResult | void>;
+  /** 完整字段元数据原始列表 */
+  readonly fields: ResourceField[];
+  /** 列表列投影（scope.list），直接绑定 Table 的 :columns */
+  readonly columns: ResourceColumn[];
+  /** 筛选字段投影（scope.filter） */
+  readonly filters: ResourceField[];
+  /** 表单字段投影（scope.create / scope.update，保留场景标记） */
+  readonly properties: ResourceField[];
+}
+/** 资源池：按名称取客户端，元数据加载状态可直接交给状态视图渲染 */
+interface ResourcePool {
+  /** 元数据加载状态：pending / success / error（带 retry） */
+  readonly state: AsyncStateLike<ResourceSchema>;
+  /** 取资源客户端；资源不存在时抛出错误，让拼写问题在开发期即暴露 */
+  client<D = unknown>(name: string): ResourceClient<D>;
+  /** 资源是否存在（池就绪前恒为 false） */
+  has(name: string): boolean;
+  /** 全部资源名（池就绪前为空数组） */
+  readonly names: string[];
+}
+//#endregion
+//#region src/resources/use-resources.d.ts
+/**
+ * 元数据驱动的资源池：声明一次「服务器地址 + 元数据解析方式」，
+ * 按资源名取客户端，请求方法与 fetch / action 协议同形，
+ * 字段元数据（columns / filters / properties）按组件属性形状导出。
+ *
+ * 池初始化时开始加载元数据；client() 无需等待就绪，方法调用时内部自动等待。
+ */
+export declare function useResources(options: UseResourcesOptions): ResourcePool;
+//#endregion
+//#region src/resources/parse-open-api.d.ts
+/**
+ * OpenAPI（Swagger）解析器。
+ * 支持路径级 + 操作级参数合并（Swagger 2.0 常见）、$ref 引用、
+ * 信封响应（数组属性 + 总数属性）与裸数组响应。
+ */
+export declare const parseOpenApi: MetadataParser;
+//#endregion
+//#region src/resources/create-fetch-adapter.d.ts
+/** 内置适配器的 HTTP 错误：携带状态码与解析后的响应体 */
+export declare class ResourceHttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(method: string, url: string, status: number, body: unknown);
+}
+/**
+ * 基于 fetch 的内置传输适配器。
+ * GET 以 query 拼装 URL，写操作以 JSON 提交 body；非 2xx 状态拒绝为
+ * ResourceHttpError（携带状态码与响应体）；响应体自动 JSON 解析，空体为 undefined。
+ */
+export declare function createFetchAdapter(): RequestAdapter;
+//#endregion
+//#region src/media/useImageState.d.ts
+type ImageLoadStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface UseImageStateOptions {
+  /** 是否懒加载（元素进入视口才发起加载），默认 false */
+  lazy?: boolean;
+  /** 懒加载时被观测的图片元素（组件绑定 img 外层引用） */
+  target?: MaybeElement<HTMLElement>;
+  /** IntersectionObserver 的根元素，默认视口 */
+  root?: MaybeElement<HTMLElement>;
+  rootMargin?: string;
+  onLoad?: (event: Event) => void;
+  onError?: (event: Event) => void;
+}
+interface UseImageStateReturn {
+  status: Ref<ImageLoadStatus>;
+  isLoading: Ref<boolean>;
+  isLoaded: Ref<boolean>;
+  isError: Ref<boolean>;
+  /** 绑定到 <img> 的 load 事件 */
+  onLoad: (event: Event) => void;
+  /** 绑定到 <img> 的 error 事件 */
+  onError: (event: Event) => void;
+  /** 手动重新加载（重置后需由 img 重新触发 src 设置） */
+  reload: () => void;
+  /** 是否应当渲染真实 img（懒加载未触发前为 false） */
+  shouldLoad: Ref<boolean>;
+}
+/**
+ * 图片加载状态机：loading / loaded / error，可选视口感知懒加载。
+ * 不创建 DOM，组件把返回的事件绑定到 <img> 即可。
+ *
+ * @internal 消费组件：Image、Avatar
+ */
+export declare function useImageState(src: MaybeRefOrGetter<string | undefined>, options?: UseImageStateOptions): UseImageStateReturn;
+//#endregion
+export { type ActionLike, type ActionResult, type AsyncFn, type AsyncStateLike, type ChatMessage, type CheckableGroupOptions, type CheckableGroupReturn, type ControllableModelOptions, type ControllableModelReturn, type ControlledProps, type DateCell, type DateGranularity, type DatePanelType, type DateShortcut, type DismissReason, type DraggablePosition, type ElementSize, type Fetch, type FetchController, type FetchLike, type FetchPagination, type FetchQuery, type FetchResource, type FetchResult, type FetchSorter, type FieldRuleConfig, type FocusReturnOptions, type FocusReturnReturn, type FormContext, type FormFieldContext, type FormFieldController, type FormRule, type FormRules, type HoverIntentOptions, type HoverIntentReturn, type ImageLoadStatus, type LabeledCell, type ListResponseMapping, type ListboxNavigationOptions, type ListboxNavigationReturn, type LoadingService, type MarkedDateCell, type MessageApi, type MessageOptions, type MetadataParser, type NormalizedFetch, type NotificationApi, type NotificationEntry, type NotificationMeta, type OverlayContainerOptions, type PagedResult, type PaginationPageItem, type Placement, type PopoverTrigger, type PopoverTriggerProps, type PushToastOptions, type QueryNames, type RequestAdapter, type ResourceClient, type ResourceColumn, type ResourceDefinition, type ResourceField, type ResourceFieldOption, type ResourceFieldType, type ResourceMethod, type ResourceOperation, type ResourcePool, type ResourceRequest, type ResourceSchema, type RovingFocusOptions, type RovingFocusReturn, type ScrollDirection, type ScrollIntoViewOptions, type ScrollLockReturn, type ScrollPosition, type SelectOption, type Strategy, type SubscribeHandler, type SubscribeResult, type SuggestStatus, type TimeColumnItem, type ToastItem, type ToastType, type ToggleReturn, type TransitionVisibleReturn, type TreeFieldNames, type TreeFlatNode, type TypeaheadOptions, type TypeaheadReturn, type UseActionStateOptions, type UseActionStateReturn, type UseActionValueReturn, type UseAsyncStateOptions, type UseAsyncStateReturn, type UseAsyncSuggestOptions, type UseAsyncSuggestReturn, type UseChatOptions, type UseChatReturn, type UseClickOutsideOptions, type UseClipboardOptions, type UseClipboardReturn, type UseDateGridOptions, type UseDateGridReturn, type UseDateModelOptions, type UseDateModelReturn, type UseDismissOptions, type UseDraggableOptions, type UseDraggableReturn, type UseFetchResourceOptions, type UseFetchReturn, type UseFloatingOptions, type UseFloatingReturn, type UseFocusTrapOptions, type UseFocusTrapReturn, type UseFormFieldOptions, type UseFormFieldReturn, type UseFormOptions, type UseFormReturn, type UseImageStateOptions, type UseImageStateReturn, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseIntervalFnOptions, type UseIntervalFnReturn, type UseModalOptions, type UseModalReturn, type UseOpenOptions, type UseOpenReturn, type UsePaginationOptions, type UsePaginationReturn, type UsePopoverModelOptions, type UsePopoverModelReturn, type UseResizeObserverReturn, type UseResourcesOptions, type UseScrollOptions, type UseSelectModelOptions, type UseSelectModelReturn, type UseSubscribeReturn, type UseTimeModelOptions, type UseTimeModelReturn, type UseTimeoutFnReturn, type UseToastQueueOptions, type UseToastQueueReturn, type UseTreeModelOptions, type UseTreeModelReturn, type ZIndexReturn, actionErrorText as subscribeErrorText };