@vavt/react-ui 1.0.0

package/dist/types/_shared/date.d.cts

@@ -0,0 +1,55 @@
+/**
+ * 日期选择器共用的本地时区工具。
+ *
+ * 这里刻意不使用 `new Date('YYYY-MM-DD')`：该写法在不同运行环境会按 UTC
+ * 解析，接近午夜时可能跨到前一天。所有解析都通过本地构造函数完成。
+ */
+/** 数字前导补零 */
+export declare const pad: (value: number, length?: number) => string;
+/** 克隆 Date 对象 */
+export declare const cloneDate: (value: Date) => Date;
+/** 获取当日起始时间（00:00:00.000） */
+export declare const startOfDay: (value: Date) => Date;
+/** 获取当月第一天起始时间（1 号 00:00:00.000） */
+export declare const startOfMonth: (value: Date) => Date;
+/** 增加/减少天数 */
+export declare const addDays: (value: Date, amount: number) => Date;
+/** 增加/减少月份，自动处理月底天数溢出 */
+export declare const addMonths: (value: Date, amount: number) => Date;
+/** 比较两个日期的先后顺序 */
+export declare const compareDates: (left: Date, right: Date) => number;
+/** 判断两个日期是否为同一天（基于本地年月日） */
+export declare const isSameDay: (left: Date, right: Date) => boolean;
+/** 判断两个日期是否为同一个月（基于本地年月） */
+export declare const isSameMonth: (left: Date, right: Date) => boolean;
+/**
+ * 按照指定格式模版格式化日期对象
+ *
+ * @param value 目标日期
+ * @param format 格式字符串，如 'YYYY-MM-DD HH:mm:ss'
+ * @returns 格式化后的字符串
+ */
+export declare const formatDate: (value: Date, format: string) => string;
+/** 严格按 format 解析本地时间；格式中未出现的字段使用日期/时间默认值。 */
+export declare const parseDate: (value: string, format: string) => Date | null;
+/** 将字符串或 Date 统一转换为合法 Date 实例；无法解析时返回 null */
+export declare const toDate: (value: Date | string | null | undefined, format: string) => Date | null;
+/** 生成 6 行 7 列（共 42 天）的标准日历网格天数列表 */
+export declare const getCalendarDays: (month: Date) => Date[];
+/** 设置日期的时分秒毫秒并返回新 Date 实例 */
+export declare const setTime: (date: Date, hours: number, minutes: number, seconds: number) => Date;
+/** 将 'HH:mm:ss' 转换为自当日午夜起的总秒数 */
+export declare const timeToSeconds: (value: string) => number | null;
+/** 将自午夜起的总秒数转换为 'HH:mm:ss' 格式字符串 */
+export declare const secondsToTime: (value: number) => string;
+/**
+ * 在给定时间段内寻找最接近期望值的可用秒数。
+ *
+ * 时间面板不能只用“当前分秒”判断整个小时是否禁用：例如最小时间为
+ * 09:30:00 时，09:00:00 虽不可选，但 9 点这一列仍然存在有效值。
+ * 该函数让小时、分钟选项可以先判断区间内是否至少有一个可用时间，
+ * 并在用户切换上级字段时自动落到最近的合法组合。
+ */
+export declare const findAvailableTime: (startSeconds: number, endSeconds: number, preferredSeconds: number, isDisabled: (time: string) => boolean) => number | null;
+/** 将 'HH:mm:ss' 格式的时间字符串附加到基准日期上 */
+export declare const timeStringToDate: (value: string, base?: Date) => Date | null;

package/dist/types/_shared/date.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 日期选择器共用的本地时区工具。
+ *
+ * 这里刻意不使用 `new Date('YYYY-MM-DD')`：该写法在不同运行环境会按 UTC
+ * 解析，接近午夜时可能跨到前一天。所有解析都通过本地构造函数完成。
+ */
+/** 数字前导补零 */
+export declare const pad: (value: number, length?: number) => string;
+/** 克隆 Date 对象 */
+export declare const cloneDate: (value: Date) => Date;
+/** 获取当日起始时间（00:00:00.000） */
+export declare const startOfDay: (value: Date) => Date;
+/** 获取当月第一天起始时间（1 号 00:00:00.000） */
+export declare const startOfMonth: (value: Date) => Date;
+/** 增加/减少天数 */
+export declare const addDays: (value: Date, amount: number) => Date;
+/** 增加/减少月份，自动处理月底天数溢出 */
+export declare const addMonths: (value: Date, amount: number) => Date;
+/** 比较两个日期的先后顺序 */
+export declare const compareDates: (left: Date, right: Date) => number;
+/** 判断两个日期是否为同一天（基于本地年月日） */
+export declare const isSameDay: (left: Date, right: Date) => boolean;
+/** 判断两个日期是否为同一个月（基于本地年月） */
+export declare const isSameMonth: (left: Date, right: Date) => boolean;
+/**
+ * 按照指定格式模版格式化日期对象
+ *
+ * @param value 目标日期
+ * @param format 格式字符串，如 'YYYY-MM-DD HH:mm:ss'
+ * @returns 格式化后的字符串
+ */
+export declare const formatDate: (value: Date, format: string) => string;
+/** 严格按 format 解析本地时间；格式中未出现的字段使用日期/时间默认值。 */
+export declare const parseDate: (value: string, format: string) => Date | null;
+/** 将字符串或 Date 统一转换为合法 Date 实例；无法解析时返回 null */
+export declare const toDate: (value: Date | string | null | undefined, format: string) => Date | null;
+/** 生成 6 行 7 列（共 42 天）的标准日历网格天数列表 */
+export declare const getCalendarDays: (month: Date) => Date[];
+/** 设置日期的时分秒毫秒并返回新 Date 实例 */
+export declare const setTime: (date: Date, hours: number, minutes: number, seconds: number) => Date;
+/** 将 'HH:mm:ss' 转换为自当日午夜起的总秒数 */
+export declare const timeToSeconds: (value: string) => number | null;
+/** 将自午夜起的总秒数转换为 'HH:mm:ss' 格式字符串 */
+export declare const secondsToTime: (value: number) => string;
+/**
+ * 在给定时间段内寻找最接近期望值的可用秒数。
+ *
+ * 时间面板不能只用“当前分秒”判断整个小时是否禁用：例如最小时间为
+ * 09:30:00 时，09:00:00 虽不可选，但 9 点这一列仍然存在有效值。
+ * 该函数让小时、分钟选项可以先判断区间内是否至少有一个可用时间，
+ * 并在用户切换上级字段时自动落到最近的合法组合。
+ */
+export declare const findAvailableTime: (startSeconds: number, endSeconds: number, preferredSeconds: number, isDisabled: (time: string) => boolean) => number | null;
+/** 将 'HH:mm:ss' 格式的时间字符串附加到基准日期上 */
+export declare const timeStringToDate: (value: string, base?: Date) => Date | null;

package/dist/types/_shared/dialog-shell.d.cts

@@ -0,0 +1,59 @@
+/**
+ * Modal、Drawer 共用的 Portal 与 Transition 外壳。
+ *
+ * 视觉组件仍负责 panel 内容、尺寸和拖拽；这里仅固定 mask/panel 的挂载、ARIA 基础属性和离场卸载时机，
+ * 避免两个弹层在未来新增属性时只修改其中一份外壳逻辑。
+ */
+import type { CSSProperties, HTMLAttributes, MouseEvent as ReactMouseEvent, ReactNode, Ref } from 'react';
+/** DialogShell 属性接口 */
+interface DialogShellProps {
+    /** 客户端挂载就绪标志（SSR 期间不渲染 Portal） */
+    clientReady: boolean;
+    /** 弹层是否处于打开状态 */
+    open: boolean;
+    /** 是否展示遮罩层 */
+    mask: boolean;
+    /** 关闭后是否销毁子节点 DOM */
+    destroyOnClose: boolean;
+    /** 遮罩离开动画完成后是否销毁 DOM */
+    maskUnmountOnExit?: boolean;
+    /** 遮罩过渡动效名称 */
+    maskTransitionName: string;
+    /** 内容面板过渡动效名称 */
+    transitionName: string;
+    /** 遮罩层 DOM 类名 */
+    maskClassName: string;
+    /** 内容面板 DOM 类名 */
+    panelClassName: string;
+    /** 内容面板内联样式 */
+    panelStyle: CSSProperties;
+    /** 遮罩层内联样式 */
+    maskStyle?: CSSProperties;
+    /** 内容面板 Ref 转发 */
+    panelRef: Ref<HTMLDivElement>;
+    /** ARIA role 角色（如 'dialog' | 'alertdialog'） */
+    role: string;
+    /** 是否声明为模态弹层 aria-modal */
+    ariaModal?: boolean | 'true' | 'false';
+    /** 无障碍标题说明 */
+    ariaLabel?: string;
+    /** 无障碍标题元素 ID 关联 */
+    ariaLabelledBy?: string;
+    /** 无障碍描述元素 ID 关联 */
+    ariaDescribedBy?: string;
+    /** 点击遮罩层回调 */
+    onMaskClick: () => void;
+    /** 点击面板区域回调 */
+    onPanelClick: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    /** 离开动画结束回调 */
+    onAfterLeave?: () => void;
+    /** 透传至面板容器的原生 HTML 属性 */
+    panelProps?: HTMLAttributes<HTMLDivElement>;
+    /** 弹窗内部子内容 */
+    children: ReactNode;
+}
+/**
+ * 模态弹层共享外壳组件
+ */
+declare const DialogShell: ({ clientReady, open, mask, destroyOnClose, maskUnmountOnExit, maskTransitionName, transitionName, maskClassName, panelClassName, panelStyle, maskStyle, panelRef, role, ariaModal, ariaLabel, ariaLabelledBy, ariaDescribedBy, onMaskClick, onPanelClick, onAfterLeave, panelProps, children }: DialogShellProps) => import("react").ReactPortal | null;
+export default DialogShell;

package/dist/types/_shared/dialog-shell.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Modal、Drawer 共用的 Portal 与 Transition 外壳。
+ *
+ * 视觉组件仍负责 panel 内容、尺寸和拖拽；这里仅固定 mask/panel 的挂载、ARIA 基础属性和离场卸载时机，
+ * 避免两个弹层在未来新增属性时只修改其中一份外壳逻辑。
+ */
+import type { CSSProperties, HTMLAttributes, MouseEvent as ReactMouseEvent, ReactNode, Ref } from 'react';
+/** DialogShell 属性接口 */
+interface DialogShellProps {
+    /** 客户端挂载就绪标志（SSR 期间不渲染 Portal） */
+    clientReady: boolean;
+    /** 弹层是否处于打开状态 */
+    open: boolean;
+    /** 是否展示遮罩层 */
+    mask: boolean;
+    /** 关闭后是否销毁子节点 DOM */
+    destroyOnClose: boolean;
+    /** 遮罩离开动画完成后是否销毁 DOM */
+    maskUnmountOnExit?: boolean;
+    /** 遮罩过渡动效名称 */
+    maskTransitionName: string;
+    /** 内容面板过渡动效名称 */
+    transitionName: string;
+    /** 遮罩层 DOM 类名 */
+    maskClassName: string;
+    /** 内容面板 DOM 类名 */
+    panelClassName: string;
+    /** 内容面板内联样式 */
+    panelStyle: CSSProperties;
+    /** 遮罩层内联样式 */
+    maskStyle?: CSSProperties;
+    /** 内容面板 Ref 转发 */
+    panelRef: Ref<HTMLDivElement>;
+    /** ARIA role 角色（如 'dialog' | 'alertdialog'） */
+    role: string;
+    /** 是否声明为模态弹层 aria-modal */
+    ariaModal?: boolean | 'true' | 'false';
+    /** 无障碍标题说明 */
+    ariaLabel?: string;
+    /** 无障碍标题元素 ID 关联 */
+    ariaLabelledBy?: string;
+    /** 无障碍描述元素 ID 关联 */
+    ariaDescribedBy?: string;
+    /** 点击遮罩层回调 */
+    onMaskClick: () => void;
+    /** 点击面板区域回调 */
+    onPanelClick: (event: ReactMouseEvent<HTMLDivElement>) => void;
+    /** 离开动画结束回调 */
+    onAfterLeave?: () => void;
+    /** 透传至面板容器的原生 HTML 属性 */
+    panelProps?: HTMLAttributes<HTMLDivElement>;
+    /** 弹窗内部子内容 */
+    children: ReactNode;
+}
+/**
+ * 模态弹层共享外壳组件
+ */
+declare const DialogShell: ({ clientReady, open, mask, destroyOnClose, maskUnmountOnExit, maskTransitionName, transitionName, maskClassName, panelClassName, panelStyle, maskStyle, panelRef, role, ariaModal, ariaLabel, ariaLabelledBy, ariaDescribedBy, onMaskClick, onPanelClick, onAfterLeave, panelProps, children }: DialogShellProps) => import("react").ReactPortal | null;
+export default DialogShell;

package/dist/types/_shared/dialog.d.cts

@@ -0,0 +1,20 @@
+import type { RefObject } from 'react';
+/** 拖拽期间禁止文本选择；使用引用计数以兼容嵌套弹层或同时结束的拖拽清理。 */
+export declare const acquireBodyUserSelectLock: () => () => void;
+export interface DialogInteractionOptions {
+    active: boolean;
+    containerRef: RefObject<HTMLElement | null>;
+    closeOnPressEscape: boolean;
+    lockScroll: boolean;
+    onRequestClose: () => void;
+}
+/**
+ * 统一模态弹层的层级、Escape、焦点陷阱、焦点恢复与 body 滚动锁。
+ *
+ * active=false 时不注册任何全局监听；激活后记录打开前焦点，并在下一帧把焦点送入已完成挂载的弹层。
+ * 当上层弹层关闭时，订阅栈变化的父层会重新确认焦点是否仍在自身内部。最终卸载会恢复打开前焦点；
+ * 若仍有父弹层存在，其 focusin 陷阱会自然把焦点约束回父层，因此无需在这里感知具体父子关系。
+ */
+export declare const useDialogInteraction: ({ active, containerRef, closeOnPressEscape, lockScroll, onRequestClose }: DialogInteractionOptions) => {
+    isTopLayer: () => boolean;
+};

package/dist/types/_shared/dialog.d.ts

@@ -0,0 +1,20 @@
+import type { RefObject } from 'react';
+/** 拖拽期间禁止文本选择；使用引用计数以兼容嵌套弹层或同时结束的拖拽清理。 */
+export declare const acquireBodyUserSelectLock: () => () => void;
+export interface DialogInteractionOptions {
+    active: boolean;
+    containerRef: RefObject<HTMLElement | null>;
+    closeOnPressEscape: boolean;
+    lockScroll: boolean;
+    onRequestClose: () => void;
+}
+/**
+ * 统一模态弹层的层级、Escape、焦点陷阱、焦点恢复与 body 滚动锁。
+ *
+ * active=false 时不注册任何全局监听；激活后记录打开前焦点，并在下一帧把焦点送入已完成挂载的弹层。
+ * 当上层弹层关闭时，订阅栈变化的父层会重新确认焦点是否仍在自身内部。最终卸载会恢复打开前焦点；
+ * 若仍有父弹层存在，其 focusin 陷阱会自然把焦点约束回父层，因此无需在这里感知具体父子关系。
+ */
+export declare const useDialogInteraction: ({ active, containerRef, closeOnPressEscape, lockScroll, onRequestClose }: DialogInteractionOptions) => {
+    isTopLayer: () => boolean;
+};

package/dist/types/_shared/effect.d.cts

@@ -0,0 +1,8 @@
+/**
+ * 在浏览器中保留布局阶段执行时机，在服务端降级为普通 effect。
+ *
+ * React 18 会在 SSR 期间对 useLayoutEffect 输出警告。组件仍需要在浏览器首帧前完成测量或 DOM
+ * property 同步，因此不能简单地全部改成 useEffect；这个同构包装同时满足两种运行环境的约束。
+ */
+import { useEffect } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useEffect;

package/dist/types/_shared/effect.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 在浏览器中保留布局阶段执行时机，在服务端降级为普通 effect。
+ *
+ * React 18 会在 SSR 期间对 useLayoutEffect 输出警告。组件仍需要在浏览器首帧前完成测量或 DOM
+ * property 同步，因此不能简单地全部改成 useEffect；这个同构包装同时满足两种运行环境的约束。
+ */
+import { useEffect } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useEffect;

package/dist/types/_shared/floating.d.cts

@@ -0,0 +1,88 @@
+import type { RefObject } from 'react';
+/** 角对齐浮层方向 */
+export type CornerPlacement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+/** 完整 12 方向浮层定位枚举 */
+export type FloatingPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+/** 角对齐定位计算入参配置 */
+export interface CornerPositionOptions<T extends CornerPlacement> {
+    /** 触发器锚点元素的视口矩形 */
+    anchorRect: DOMRect;
+    /** 浮层内容元素的视口矩形 */
+    floatingRect: DOMRect;
+    /** 期望的首选对齐方向 */
+    placement: T;
+    /** 浮层与锚点之间的偏移距离（px） */
+    offset: number;
+    /** 视口边缘安全内边距（px），默认为 8 */
+    edgePadding?: number;
+}
+/** 通用浮层定位计算入参配置 */
+export interface FloatingPositionOptions<T extends FloatingPlacement> {
+    /** 触发器锚点元素的视口矩形 */
+    anchorRect: DOMRect;
+    /** 浮层内容元素的视口矩形 */
+    floatingRect: DOMRect;
+    /** 期望的首选对齐方向 */
+    placement: T;
+    /** 浮层与锚点之间的偏移距离（px） */
+    offset: number;
+    /** 视口边缘安全内边距（px），默认为 8 */
+    edgePadding?: number;
+    /** 自定义候选翻转方向列表生成函数 */
+    getCandidates?: (placement: T) => T[];
+    /** 自定义主轴或次轴回退容纳条件 */
+    fallbackFits?: (position: {
+        x: number;
+        y: number;
+    }) => boolean;
+}
+/** 通用浮层定位计算返回的解析结果 */
+export interface ResolvedFloatingPosition<T extends FloatingPlacement> {
+    /** 最终生效的对齐方向 */
+    placement: T;
+    /** 浮层相对于视口的 X 坐标 (px) */
+    x: number;
+    /** 浮层相对于视口的 Y 坐标 (px) */
+    y: number;
+}
+/** 浮层全局销毁 Hook 入参选项 */
+export interface FloatingDismissOptions {
+    /** 是否处于激活监听状态 */
+    active: boolean;
+    /** 触发器根节点 Ref */
+    rootRef: RefObject<HTMLElement | null>;
+    /** 浮层 DOM 节点 Ref */
+    floatingRef: RefObject<HTMLElement | null>;
+    /** 点击外部是否触发关闭，默认为 true */
+    closeOnOutsideClick?: boolean;
+    /** 焦点位于浮层内部时是否忽略 Escape 键，默认为 false */
+    ignoreEscapeInsideFloating?: boolean;
+    /** 判断事件路径是否属于从属子弹层（如日期选择器中嵌套的时间滚轮弹窗） */
+    isOwnedPopup?: (path: EventTarget[]) => boolean;
+    /** 点击外部触发的回调函数 */
+    onOutsideClick?: () => void;
+    /** 按下 Escape 键触发的回调函数 */
+    onEscape?: () => void;
+    /** 视口尺寸调整或滚动时触发的回调函数 */
+    onViewportChange?: () => void;
+}
+/**
+ * 统一浮层的全局事件清理。
+ *
+ * Portal 会让浮层脱离触发器 DOM 子树，因此 outside click 必须基于 composedPath 同时判断
+ * 触发器和浮层；日期时间选择器还可以通过 isOwnedPopup 声明嵌套的时间子浮层。组件自身
+ * 仍负责键盘导航和关闭后的焦点策略，这个 helper 只管理 document/window 监听的生命周期。
+ */
+export declare const useFloatingDismiss: ({ active, rootRef, floatingRef, closeOnOutsideClick, ignoreEscapeInsideFloating, isOwnedPopup, onOutsideClick, onEscape, onViewportChange }: FloatingDismissOptions) => void;
+/**
+ * 为 Tooltip、Select、Dropdown、Picker 这类 fixed 浮层选择可用方向，并把最终坐标约束在视口内。
+ * 默认候选顺序覆盖四边和 start/end 对齐；角对齐组件可以传入自己的候选顺序与主轴 fallback 规则。
+ */
+export declare const resolveFloatingPosition: <T extends FloatingPlacement>({ anchorRect, floatingRect, placement, offset, edgePadding, getCandidates, fallbackFits }: FloatingPositionOptions<T>) => ResolvedFloatingPosition<T>;
+/**
+ * 保留 Select/Dropdown 原有“先保证垂直方向可见，再夹紧横向坐标”的回退策略。
+ *
+ * @param options 角对齐定位配置选项
+ * @returns 解析后的方向与坐标
+ */
+export declare const resolveCornerPosition: <T extends CornerPlacement>(options: CornerPositionOptions<T>) => ResolvedFloatingPosition<T>;

package/dist/types/_shared/floating.d.ts

@@ -0,0 +1,88 @@
+import type { RefObject } from 'react';
+/** 角对齐浮层方向 */
+export type CornerPlacement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+/** 完整 12 方向浮层定位枚举 */
+export type FloatingPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+/** 角对齐定位计算入参配置 */
+export interface CornerPositionOptions<T extends CornerPlacement> {
+    /** 触发器锚点元素的视口矩形 */
+    anchorRect: DOMRect;
+    /** 浮层内容元素的视口矩形 */
+    floatingRect: DOMRect;
+    /** 期望的首选对齐方向 */
+    placement: T;
+    /** 浮层与锚点之间的偏移距离（px） */
+    offset: number;
+    /** 视口边缘安全内边距（px），默认为 8 */
+    edgePadding?: number;
+}
+/** 通用浮层定位计算入参配置 */
+export interface FloatingPositionOptions<T extends FloatingPlacement> {
+    /** 触发器锚点元素的视口矩形 */
+    anchorRect: DOMRect;
+    /** 浮层内容元素的视口矩形 */
+    floatingRect: DOMRect;
+    /** 期望的首选对齐方向 */
+    placement: T;
+    /** 浮层与锚点之间的偏移距离（px） */
+    offset: number;
+    /** 视口边缘安全内边距（px），默认为 8 */
+    edgePadding?: number;
+    /** 自定义候选翻转方向列表生成函数 */
+    getCandidates?: (placement: T) => T[];
+    /** 自定义主轴或次轴回退容纳条件 */
+    fallbackFits?: (position: {
+        x: number;
+        y: number;
+    }) => boolean;
+}
+/** 通用浮层定位计算返回的解析结果 */
+export interface ResolvedFloatingPosition<T extends FloatingPlacement> {
+    /** 最终生效的对齐方向 */
+    placement: T;
+    /** 浮层相对于视口的 X 坐标 (px) */
+    x: number;
+    /** 浮层相对于视口的 Y 坐标 (px) */
+    y: number;
+}
+/** 浮层全局销毁 Hook 入参选项 */
+export interface FloatingDismissOptions {
+    /** 是否处于激活监听状态 */
+    active: boolean;
+    /** 触发器根节点 Ref */
+    rootRef: RefObject<HTMLElement | null>;
+    /** 浮层 DOM 节点 Ref */
+    floatingRef: RefObject<HTMLElement | null>;
+    /** 点击外部是否触发关闭，默认为 true */
+    closeOnOutsideClick?: boolean;
+    /** 焦点位于浮层内部时是否忽略 Escape 键，默认为 false */
+    ignoreEscapeInsideFloating?: boolean;
+    /** 判断事件路径是否属于从属子弹层（如日期选择器中嵌套的时间滚轮弹窗） */
+    isOwnedPopup?: (path: EventTarget[]) => boolean;
+    /** 点击外部触发的回调函数 */
+    onOutsideClick?: () => void;
+    /** 按下 Escape 键触发的回调函数 */
+    onEscape?: () => void;
+    /** 视口尺寸调整或滚动时触发的回调函数 */
+    onViewportChange?: () => void;
+}
+/**
+ * 统一浮层的全局事件清理。
+ *
+ * Portal 会让浮层脱离触发器 DOM 子树，因此 outside click 必须基于 composedPath 同时判断
+ * 触发器和浮层；日期时间选择器还可以通过 isOwnedPopup 声明嵌套的时间子浮层。组件自身
+ * 仍负责键盘导航和关闭后的焦点策略，这个 helper 只管理 document/window 监听的生命周期。
+ */
+export declare const useFloatingDismiss: ({ active, rootRef, floatingRef, closeOnOutsideClick, ignoreEscapeInsideFloating, isOwnedPopup, onOutsideClick, onEscape, onViewportChange }: FloatingDismissOptions) => void;
+/**
+ * 为 Tooltip、Select、Dropdown、Picker 这类 fixed 浮层选择可用方向，并把最终坐标约束在视口内。
+ * 默认候选顺序覆盖四边和 start/end 对齐；角对齐组件可以传入自己的候选顺序与主轴 fallback 规则。
+ */
+export declare const resolveFloatingPosition: <T extends FloatingPlacement>({ anchorRect, floatingRect, placement, offset, edgePadding, getCandidates, fallbackFits }: FloatingPositionOptions<T>) => ResolvedFloatingPosition<T>;
+/**
+ * 保留 Select/Dropdown 原有“先保证垂直方向可见，再夹紧横向坐标”的回退策略。
+ *
+ * @param options 角对齐定位配置选项
+ * @returns 解析后的方向与坐标
+ */
+export declare const resolveCornerPosition: <T extends CornerPlacement>(options: CornerPositionOptions<T>) => ResolvedFloatingPosition<T>;

package/dist/types/_shared/focus.d.cts

@@ -0,0 +1,33 @@
+/**
+ * 组件库统一的可聚焦元素范围选择器，供浮层触发器、Dialog 焦点陷阱和表单错误定位共用。
+ *
+ * 使用 :disabled 伪类而不是 [disabled] 属性选择器：后者漏掉 <fieldset disabled> 的后代控件，
+ * 它们没有自身的 disabled 属性但同样不可聚焦。
+ */
+export declare const focusableSelector = "button:not(:disabled), [href], input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex=\"-1\"])";
+/** 自动聚焦标记属性名称 */
+export declare const autofocusAttribute = "data-vl-autofocus";
+/**
+ * 收集指定容器内所有当前可聚焦的 HTML 元素，自动剔除 aria-hidden 及 inert 节点
+ *
+ * @param container 目标 DOM 容器
+ * @returns 可聚焦的 HTMLElement 元素数组
+ */
+export declare const getFocusableElements: (container: HTMLElement) => HTMLElement[];
+/**
+ * 将焦点送入容器内部；优先寻找带有 autofocus 或 data-${prefix}-autofocus 的元素，
+ * 其次为首个可聚焦元素，兜底为容器本身。
+ *
+ * autofocus 标记同样要经过可聚焦过滤：标记可能落在 inert 子树、aria-hidden 节点或
+ * 已禁用控件上，直接聚焦会把焦点送到用户无法感知的位置。
+ *
+ * @param container 目标 DOM 容器
+ */
+export declare const focusInitialElement: (container: HTMLElement) => void;
+/**
+ * 把焦点送到指定元素自身或其内部首个可聚焦节点。
+ *
+ * 与 focusInitialElement 的区别是不考虑 autofocus 标记、也不兜底聚焦容器：
+ * 供表单提交失败定位首个错误字段这类“尽力聚焦”场景使用。
+ */
+export declare const focusFirstFocusable: (element: HTMLElement | null) => void;

package/dist/types/_shared/focus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 组件库统一的可聚焦元素范围选择器，供浮层触发器、Dialog 焦点陷阱和表单错误定位共用。
+ *
+ * 使用 :disabled 伪类而不是 [disabled] 属性选择器：后者漏掉 <fieldset disabled> 的后代控件，
+ * 它们没有自身的 disabled 属性但同样不可聚焦。
+ */
+export declare const focusableSelector = "button:not(:disabled), [href], input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex=\"-1\"])";
+/** 自动聚焦标记属性名称 */
+export declare const autofocusAttribute = "data-vl-autofocus";
+/**
+ * 收集指定容器内所有当前可聚焦的 HTML 元素，自动剔除 aria-hidden 及 inert 节点
+ *
+ * @param container 目标 DOM 容器
+ * @returns 可聚焦的 HTMLElement 元素数组
+ */
+export declare const getFocusableElements: (container: HTMLElement) => HTMLElement[];
+/**
+ * 将焦点送入容器内部；优先寻找带有 autofocus 或 data-${prefix}-autofocus 的元素，
+ * 其次为首个可聚焦元素，兜底为容器本身。
+ *
+ * autofocus 标记同样要经过可聚焦过滤：标记可能落在 inert 子树、aria-hidden 节点或
+ * 已禁用控件上，直接聚焦会把焦点送到用户无法感知的位置。
+ *
+ * @param container 目标 DOM 容器
+ */
+export declare const focusInitialElement: (container: HTMLElement) => void;
+/**
+ * 把焦点送到指定元素自身或其内部首个可聚焦节点。
+ *
+ * 与 focusInitialElement 的区别是不考虑 autofocus 标记、也不兜底聚焦容器：
+ * 供表单提交失败定位首个错误字段这类“尽力聚焦”场景使用。
+ */
+export declare const focusFirstFocusable: (element: HTMLElement | null) => void;

package/dist/types/_shared/icon.d.cts

@@ -0,0 +1,15 @@
+import type { ComponentType, ElementType, ReactElement, ReactNode } from 'react';
+export type ComponentIcon = ElementType<{
+    className?: string;
+}> | ReactElement;
+export type DecorativeIcon = ReactNode | ComponentType<any>;
+/**
+ * 渲染组件库中的装饰性图标，并保留调用方传入的 className。
+ * 图标本身不承担可访问名称，交互控件必须通过文本或 aria-label 提供语义。
+ */
+export declare const renderIcon: (icon: ComponentIcon | null | undefined, className?: string) => ReactElement<any, string | import("react").JSXElementConstructor<any>> | null;
+/**
+ * 支持组件、React 元素以及字符型轻量图标，并统一隐藏装饰语义。
+ * React 的 memo/forwardRef 组件在运行时可能表现为带 $$typeof 的对象，因此不能只用 typeof === 'function' 判断。
+ */
+export declare const renderDecorativeIcon: (icon: DecorativeIcon | null | undefined, className?: string) => ReactNode;

package/dist/types/_shared/icon.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentType, ElementType, ReactElement, ReactNode } from 'react';
+export type ComponentIcon = ElementType<{
+    className?: string;
+}> | ReactElement;
+export type DecorativeIcon = ReactNode | ComponentType<any>;
+/**
+ * 渲染组件库中的装饰性图标，并保留调用方传入的 className。
+ * 图标本身不承担可访问名称，交互控件必须通过文本或 aria-label 提供语义。
+ */
+export declare const renderIcon: (icon: ComponentIcon | null | undefined, className?: string) => ReactElement<any, string | import("react").JSXElementConstructor<any>> | null;
+/**
+ * 支持组件、React 元素以及字符型轻量图标，并统一隐藏装饰语义。
+ * React 的 memo/forwardRef 组件在运行时可能表现为带 $$typeof 的对象，因此不能只用 typeof === 'function' 判断。
+ */
+export declare const renderDecorativeIcon: (icon: DecorativeIcon | null | undefined, className?: string) => ReactNode;

package/dist/types/_shared/id.d.cts

@@ -0,0 +1,10 @@
+/**
+ * 生成 SSR 稳定且可用于 `aria-*`（如 `aria-labelledby`, `aria-describedby`）关联的 DOM id。
+ *
+ * 如果调用方显式传入了 `providedId`，则优先使用调用方的值。
+ *
+ * @param namespace ID 前缀命名空间（如 `vl-input`）
+ * @param providedId 调用方显式指定的 ID
+ * @returns 唯一的 DOM 元素 ID 字符串
+ */
+export declare const useStableId: (namespace: string, providedId?: string) => string;

package/dist/types/_shared/id.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 生成 SSR 稳定且可用于 `aria-*`（如 `aria-labelledby`, `aria-describedby`）关联的 DOM id。
+ *
+ * 如果调用方显式传入了 `providedId`，则优先使用调用方的值。
+ *
+ * @param namespace ID 前缀命名空间（如 `vl-input`）
+ * @param providedId 调用方显式指定的 ID
+ * @returns 唯一的 DOM 元素 ID 字符串
+ */
+export declare const useStableId: (namespace: string, providedId?: string) => string;

package/dist/types/_shared/number.d.cts

@@ -0,0 +1,22 @@
+/**
+ * 数值边界与 CSS 尺寸的基础工具。
+ *
+ * 这些函数只处理通用的表示转换；组件自己的业务归一化（例如 Slider 的 step 吸附、
+ * NumberInput 的 min/max 修正）仍应保留在组件内，避免把领域规则藏进公共 helper。
+ */
+/**
+ * 将数值限制在 [min, max] 的闭区间内
+ *
+ * @param value 目标数值
+ * @param min 最小值下限
+ * @param max 最大值上限
+ * @returns 夹取后的合法数值
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * 将尺寸统一转换为合法的 CSS 尺寸表示（数字转为带有 px 单位的字符串，字符串原样返回）
+ *
+ * @param value 原始尺寸（数字、字符串或 undefined）
+ * @returns 格式化后的 CSS 尺寸值
+ */
+export declare const toCssSize: (value: string | number | undefined) => string | undefined;

package/dist/types/_shared/number.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 数值边界与 CSS 尺寸的基础工具。
+ *
+ * 这些函数只处理通用的表示转换；组件自己的业务归一化（例如 Slider 的 step 吸附、
+ * NumberInput 的 min/max 修正）仍应保留在组件内，避免把领域规则藏进公共 helper。
+ */
+/**
+ * 将数值限制在 [min, max] 的闭区间内
+ *
+ * @param value 目标数值
+ * @param min 最小值下限
+ * @param max 最大值上限
+ * @returns 夹取后的合法数值
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * 将尺寸统一转换为合法的 CSS 尺寸表示（数字转为带有 px 单位的字符串，字符串原样返回）
+ *
+ * @param value 原始尺寸（数字、字符串或 undefined）
+ * @returns 格式化后的 CSS 尺寸值
+ */
+export declare const toCssSize: (value: string | number | undefined) => string | undefined;