@vavt/react-ui 1.0.0

package/dist/types/Form/type.d.cts

@@ -0,0 +1,119 @@
+/**
+ * Form 的公共类型契约。
+ *
+ * values 是扁平键值对象，字段规则共享提交时的同一份 values 快照；异步 validator 只返回错误文案，
+ * 不负责直接修改 Form 状态。FormRef 暴露命令式编排能力，但受控 values 的最终渲染仍由调用方回传决定。
+ */
+import type { FormHTMLAttributes, HTMLAttributes, ReactElement, ReactNode, RefAttributes } from 'react';
+/** 表单值对象字典 */
+export type FormValues = Record<string, unknown>;
+/** 表单布局方式：垂直 (`vertical`) | 水平 (`horizontal`) | 行内 (`inline`) */
+export type FormLayout = 'vertical' | 'horizontal' | 'inline';
+/** 表单校验触发时机：值变化 (`change`) | 失去焦点 (`blur`) | 提交时 (`submit`) */
+export type FormValidateTrigger = 'change' | 'blur' | 'submit';
+/** 基础规则类型校验 */
+export type FormRuleType = 'string' | 'number' | 'boolean' | 'array' | 'email';
+/** 单条表单校验规则定义 */
+export interface FormRule<V extends FormValues = FormValues> {
+    /** 是否为必填字段 */
+    required?: boolean;
+    /** 字段基础类型校验 */
+    type?: FormRuleType;
+    /** 最小值（数字）或最小长度（字符串/数组） */
+    min?: number;
+    /** 最大值（数字）或最大长度（字符串/数组） */
+    max?: number;
+    /** 精确长度（字符串/数组） */
+    len?: number;
+    /** 正则表达式校验 */
+    pattern?: RegExp;
+    /** 校验失败时展示的错误文案 */
+    message?: string;
+    /** 自定义校验函数，返回错误文案字符串或 reject 都会转成字段错误；返回空/Promise<void> 表示校验通过 */
+    validator?: (value: unknown, values: V) => string | void | Promise<string | void>;
+}
+/** 表单错误信息字典（字段名 -> 错误消息数组） */
+export type FormErrors<V extends FormValues = FormValues> = Partial<Record<keyof V & string, string[]>>;
+/** 表单整体校验结果对象 */
+export type FormValidationResult<V extends FormValues = FormValues> = {
+    valid: true;
+    values: V;
+    errors: FormErrors<V>;
+} | {
+    valid: false;
+    values: V;
+    errors: FormErrors<V>;
+};
+/**
+ * Form 组件属性接口
+ */
+export interface FormProps<V extends FormValues = FormValues> extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onReset'> {
+    /** 受控表单值数据对象 */
+    values?: V;
+    /** 非受控初始表单值数据对象 */
+    defaultValues?: V;
+    /** 表单布局排版方式，默认为 `vertical` */
+    layout?: FormLayout;
+    /** 标签文本统一宽度（如 `100px` 或 `100`） */
+    labelWidth?: number | string;
+    /** 标签对齐方式，默认为 `right`（水平布局下） */
+    labelAlign?: 'left' | 'right';
+    /** 全局默认的校验触发时机，默认为 `['change', 'blur']` */
+    validateTrigger?: FormValidateTrigger | FormValidateTrigger[];
+    /** 任何字段值发生变更时的回调函数 */
+    onValuesChange?: (changedValues: Partial<V>, values: V) => void;
+    /** 校验成功并通过后的提交回调函数 */
+    onFinish?: (values: V) => void | Promise<void>;
+    /** 提交回调抛出异常时触发；Form 会消费异常，避免原生 submit 产生未处理 Promise */
+    onFinishError?: (error: unknown, values: V) => void;
+    /** 校验失败未能提交时的回调函数 */
+    onFinishFailed?: (errors: FormErrors<V>, values: V) => void;
+}
+/**
+ * FormItem 表单项组件属性接口
+ */
+export interface FormItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** 绑定的表单字段名 */
+    name?: string;
+    /** 标签标题文本或自定义节点 */
+    label?: ReactNode;
+    /** 是否标记为必填（展示必填星号） */
+    required?: boolean;
+    /** 当前字段专属的校验规则列表 */
+    rules?: FormRule[];
+    /** 额外的底部帮助/说明文本 */
+    help?: ReactNode;
+    /** 子控件绑定值的属性名，默认为 `'value'`（如 Checkbox 可指定为 `'checked'`） */
+    valuePropName?: string;
+    /** 收集子控件值变化的原生/自定义事件名称，默认为 `'onChange'` */
+    trigger?: string;
+    /** 自定义从事件参数中提取目标值的转换函数 */
+    getValueFromEvent?: (...args: unknown[]) => unknown;
+    /** 当前字段专属的校验触发时机，覆盖 Form 顶层配置 */
+    validateTrigger?: FormValidateTrigger | FormValidateTrigger[];
+    /** 唯一的表单输入控件子元素（如 Input、Select、Switch 等） */
+    children: ReactElement;
+}
+/**
+ * Form 组件暴露的命令式 Ref 操作句柄
+ */
+export interface FormRef<V extends FormValues = FormValues> {
+    /** 获取最近一次同步写入的值快照，可在 React 下一次渲染前读取 */
+    getValues: () => V;
+    /** 命令式批量设置表单字段值 */
+    setValues: (values: Partial<V>) => void;
+    /** 重置表单所有字段至初始值并清空错误 */
+    reset: () => void;
+    /** 校验当前已注册字段，不触发 onFinish/onFinishFailed */
+    validate: () => Promise<FormValidationResult<V>>;
+    /** 校验并执行提交流程；同一时间的重复调用复用同一个 Promise */
+    submit: () => Promise<FormValidationResult<V>>;
+    /** 查询当前是否正在执行提交操作 */
+    isSubmitting: () => boolean;
+    /** 获取当前所有字段的错误信息快照 */
+    getErrors: () => FormErrors<V>;
+}
+/** Form 组件类型定义（支持泛型值推导） */
+export type FormComponent = {
+    <V extends FormValues = FormValues>(props: FormProps<V> & RefAttributes<FormRef<V>>): ReactElement;
+};

package/dist/types/Form/type.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Form 的公共类型契约。
+ *
+ * values 是扁平键值对象，字段规则共享提交时的同一份 values 快照；异步 validator 只返回错误文案，
+ * 不负责直接修改 Form 状态。FormRef 暴露命令式编排能力，但受控 values 的最终渲染仍由调用方回传决定。
+ */
+import type { FormHTMLAttributes, HTMLAttributes, ReactElement, ReactNode, RefAttributes } from 'react';
+/** 表单值对象字典 */
+export type FormValues = Record<string, unknown>;
+/** 表单布局方式：垂直 (`vertical`) | 水平 (`horizontal`) | 行内 (`inline`) */
+export type FormLayout = 'vertical' | 'horizontal' | 'inline';
+/** 表单校验触发时机：值变化 (`change`) | 失去焦点 (`blur`) | 提交时 (`submit`) */
+export type FormValidateTrigger = 'change' | 'blur' | 'submit';
+/** 基础规则类型校验 */
+export type FormRuleType = 'string' | 'number' | 'boolean' | 'array' | 'email';
+/** 单条表单校验规则定义 */
+export interface FormRule<V extends FormValues = FormValues> {
+    /** 是否为必填字段 */
+    required?: boolean;
+    /** 字段基础类型校验 */
+    type?: FormRuleType;
+    /** 最小值（数字）或最小长度（字符串/数组） */
+    min?: number;
+    /** 最大值（数字）或最大长度（字符串/数组） */
+    max?: number;
+    /** 精确长度（字符串/数组） */
+    len?: number;
+    /** 正则表达式校验 */
+    pattern?: RegExp;
+    /** 校验失败时展示的错误文案 */
+    message?: string;
+    /** 自定义校验函数，返回错误文案字符串或 reject 都会转成字段错误；返回空/Promise<void> 表示校验通过 */
+    validator?: (value: unknown, values: V) => string | void | Promise<string | void>;
+}
+/** 表单错误信息字典（字段名 -> 错误消息数组） */
+export type FormErrors<V extends FormValues = FormValues> = Partial<Record<keyof V & string, string[]>>;
+/** 表单整体校验结果对象 */
+export type FormValidationResult<V extends FormValues = FormValues> = {
+    valid: true;
+    values: V;
+    errors: FormErrors<V>;
+} | {
+    valid: false;
+    values: V;
+    errors: FormErrors<V>;
+};
+/**
+ * Form 组件属性接口
+ */
+export interface FormProps<V extends FormValues = FormValues> extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'onReset'> {
+    /** 受控表单值数据对象 */
+    values?: V;
+    /** 非受控初始表单值数据对象 */
+    defaultValues?: V;
+    /** 表单布局排版方式，默认为 `vertical` */
+    layout?: FormLayout;
+    /** 标签文本统一宽度（如 `100px` 或 `100`） */
+    labelWidth?: number | string;
+    /** 标签对齐方式，默认为 `right`（水平布局下） */
+    labelAlign?: 'left' | 'right';
+    /** 全局默认的校验触发时机，默认为 `['change', 'blur']` */
+    validateTrigger?: FormValidateTrigger | FormValidateTrigger[];
+    /** 任何字段值发生变更时的回调函数 */
+    onValuesChange?: (changedValues: Partial<V>, values: V) => void;
+    /** 校验成功并通过后的提交回调函数 */
+    onFinish?: (values: V) => void | Promise<void>;
+    /** 提交回调抛出异常时触发；Form 会消费异常，避免原生 submit 产生未处理 Promise */
+    onFinishError?: (error: unknown, values: V) => void;
+    /** 校验失败未能提交时的回调函数 */
+    onFinishFailed?: (errors: FormErrors<V>, values: V) => void;
+}
+/**
+ * FormItem 表单项组件属性接口
+ */
+export interface FormItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** 绑定的表单字段名 */
+    name?: string;
+    /** 标签标题文本或自定义节点 */
+    label?: ReactNode;
+    /** 是否标记为必填（展示必填星号） */
+    required?: boolean;
+    /** 当前字段专属的校验规则列表 */
+    rules?: FormRule[];
+    /** 额外的底部帮助/说明文本 */
+    help?: ReactNode;
+    /** 子控件绑定值的属性名，默认为 `'value'`（如 Checkbox 可指定为 `'checked'`） */
+    valuePropName?: string;
+    /** 收集子控件值变化的原生/自定义事件名称，默认为 `'onChange'` */
+    trigger?: string;
+    /** 自定义从事件参数中提取目标值的转换函数 */
+    getValueFromEvent?: (...args: unknown[]) => unknown;
+    /** 当前字段专属的校验触发时机，覆盖 Form 顶层配置 */
+    validateTrigger?: FormValidateTrigger | FormValidateTrigger[];
+    /** 唯一的表单输入控件子元素（如 Input、Select、Switch 等） */
+    children: ReactElement;
+}
+/**
+ * Form 组件暴露的命令式 Ref 操作句柄
+ */
+export interface FormRef<V extends FormValues = FormValues> {
+    /** 获取最近一次同步写入的值快照，可在 React 下一次渲染前读取 */
+    getValues: () => V;
+    /** 命令式批量设置表单字段值 */
+    setValues: (values: Partial<V>) => void;
+    /** 重置表单所有字段至初始值并清空错误 */
+    reset: () => void;
+    /** 校验当前已注册字段，不触发 onFinish/onFinishFailed */
+    validate: () => Promise<FormValidationResult<V>>;
+    /** 校验并执行提交流程；同一时间的重复调用复用同一个 Promise */
+    submit: () => Promise<FormValidationResult<V>>;
+    /** 查询当前是否正在执行提交操作 */
+    isSubmitting: () => boolean;
+    /** 获取当前所有字段的错误信息快照 */
+    getErrors: () => FormErrors<V>;
+}
+/** Form 组件类型定义（支持泛型值推导） */
+export type FormComponent = {
+    <V extends FormValues = FormValues>(props: FormProps<V> & RefAttributes<FormRef<V>>): ReactElement;
+};

package/dist/types/Input/Input.d.cts

@@ -0,0 +1,3 @@
+import type { InputProps } from './type.cjs';
+declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export default Input;

package/dist/types/Input/Input.d.ts

@@ -0,0 +1,3 @@
+import type { InputProps } from './type.js';
+declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export default Input;

package/dist/types/Input/index.d.cts

@@ -0,0 +1,5 @@
+import Input from './Input.cjs';
+/** Input 文本输入框组件 */
+export declare const VlInput: import("react").ForwardRefExoticComponent<import("./type.cjs").InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export type { InputProps, InputSize, InputRef, InputIcon } from './type.cjs';
+export default Input;

package/dist/types/Input/index.d.ts

@@ -0,0 +1,5 @@
+import Input from './Input.js';
+/** Input 文本输入框组件 */
+export declare const VlInput: import("react").ForwardRefExoticComponent<import("./type.js").InputProps & import("react").RefAttributes<HTMLInputElement>>;
+export type { InputProps, InputSize, InputRef, InputIcon } from './type.js';
+export default Input;

package/dist/types/Input/type.d.cts

@@ -0,0 +1,43 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+import type { ComponentIcon } from '../_shared/icon.cjs';
+/** 输入框尺寸：小 (sm) | 中等 (md) | 大 (lg) */
+export type InputSize = 'sm' | 'md' | 'lg';
+/** 输入框图标类型 */
+export type InputIcon = ComponentIcon;
+/**
+ * Input 组件属性接口
+ */
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange' | 'prefix' | 'suffix'> {
+    /** 受控模式：当前输入框文本值 */
+    value?: string | number;
+    /** 非受控模式：初始输入框文本值 */
+    defaultValue?: string | number;
+    /** 原生占位提示文案 */
+    placeholder?: string;
+    /** 是否禁用输入框，默认为 false */
+    disabled?: boolean;
+    /** 是否展示加载中动画指示器，默认为 false */
+    loading?: boolean;
+    /** 输入框尺寸大小，默认为 `md` */
+    size?: InputSize;
+    /** 原生 `<input>` 类型（如 `'text'`、`'password'` 等），默认为 `'text'` */
+    type?: string;
+    /** 是否支持一键清空输入内容，默认为 false */
+    clearable?: boolean;
+    /** 前置装饰图标 */
+    prefixIcon?: InputIcon;
+    /** 后置装饰图标 */
+    suffixIcon?: InputIcon;
+    /** 底部辅助提示/错误文案 */
+    tips?: string;
+    /** 前置自定义内容插槽（位于输入框内部最左侧） */
+    prefix?: ReactNode;
+    /** 后置自定义内容插槽（位于输入框内部最右侧） */
+    suffix?: ReactNode;
+    /** 输入值变化时的回调函数（返回规整后的字符串） */
+    onChange?: (value: string) => void;
+    /** 点击清空图标时的回调函数 */
+    onClear?: () => void;
+}
+/** Input 根原生 input DOM 元素类型 */
+export type InputRef = HTMLInputElement;

package/dist/types/Input/type.d.ts

@@ -0,0 +1,43 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+import type { ComponentIcon } from '../_shared/icon.js';
+/** 输入框尺寸：小 (sm) | 中等 (md) | 大 (lg) */
+export type InputSize = 'sm' | 'md' | 'lg';
+/** 输入框图标类型 */
+export type InputIcon = ComponentIcon;
+/**
+ * Input 组件属性接口
+ */
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange' | 'prefix' | 'suffix'> {
+    /** 受控模式：当前输入框文本值 */
+    value?: string | number;
+    /** 非受控模式：初始输入框文本值 */
+    defaultValue?: string | number;
+    /** 原生占位提示文案 */
+    placeholder?: string;
+    /** 是否禁用输入框，默认为 false */
+    disabled?: boolean;
+    /** 是否展示加载中动画指示器，默认为 false */
+    loading?: boolean;
+    /** 输入框尺寸大小，默认为 `md` */
+    size?: InputSize;
+    /** 原生 `<input>` 类型（如 `'text'`、`'password'` 等），默认为 `'text'` */
+    type?: string;
+    /** 是否支持一键清空输入内容，默认为 false */
+    clearable?: boolean;
+    /** 前置装饰图标 */
+    prefixIcon?: InputIcon;
+    /** 后置装饰图标 */
+    suffixIcon?: InputIcon;
+    /** 底部辅助提示/错误文案 */
+    tips?: string;
+    /** 前置自定义内容插槽（位于输入框内部最左侧） */
+    prefix?: ReactNode;
+    /** 后置自定义内容插槽（位于输入框内部最右侧） */
+    suffix?: ReactNode;
+    /** 输入值变化时的回调函数（返回规整后的字符串） */
+    onChange?: (value: string) => void;
+    /** 点击清空图标时的回调函数 */
+    onClear?: () => void;
+}
+/** Input 根原生 input DOM 元素类型 */
+export type InputRef = HTMLInputElement;

package/dist/types/Loading/Loading.d.cts

@@ -0,0 +1,3 @@
+import type { LoadingProps } from './type.cjs';
+declare const Loading: import("react").ForwardRefExoticComponent<LoadingProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Loading;

package/dist/types/Loading/Loading.d.ts

@@ -0,0 +1,3 @@
+import type { LoadingProps } from './type.js';
+declare const Loading: import("react").ForwardRefExoticComponent<LoadingProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Loading;

package/dist/types/Loading/index.d.cts

@@ -0,0 +1,5 @@
+import Loading from './Loading.cjs';
+/** Loading 加载指示器组件 */
+export declare const VlLoading: import("react").ForwardRefExoticComponent<import("./type.cjs").LoadingProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { LoadingProps, LoadingRef } from './type.cjs';
+export default Loading;

package/dist/types/Loading/index.d.ts

@@ -0,0 +1,5 @@
+import Loading from './Loading.js';
+/** Loading 加载指示器组件 */
+export declare const VlLoading: import("react").ForwardRefExoticComponent<import("./type.js").LoadingProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { LoadingProps, LoadingRef } from './type.js';
+export default Loading;

package/dist/types/Loading/type.d.cts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+/** Loading 根 DOM 元素类型 */
+export type LoadingRef = HTMLDivElement;
+/**
+ * Loading 组件属性接口
+ */
+export interface LoadingProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** 是否显示加载中状态，默认为 false */
+    visible?: boolean;
+    /** 加载文案提示 */
+    text?: ReactNode;
+    /** 自定义加载指示器，使用 ReactNode 避免执行未经净化的 HTML 字符串 */
+    spinner?: ReactNode;
+    /** 遮罩层背景颜色（如 `rgba(255, 255, 255, 0.8)`） */
+    background?: string;
+    /** 是否以全屏模态遮罩形式展示，默认为 false */
+    fullscreen?: boolean;
+}

package/dist/types/Loading/type.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+/** Loading 根 DOM 元素类型 */
+export type LoadingRef = HTMLDivElement;
+/**
+ * Loading 组件属性接口
+ */
+export interface LoadingProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** 是否显示加载中状态，默认为 false */
+    visible?: boolean;
+    /** 加载文案提示 */
+    text?: ReactNode;
+    /** 自定义加载指示器，使用 ReactNode 避免执行未经净化的 HTML 字符串 */
+    spinner?: ReactNode;
+    /** 遮罩层背景颜色（如 `rgba(255, 255, 255, 0.8)`） */
+    background?: string;
+    /** 是否以全屏模态遮罩形式展示，默认为 false */
+    fullscreen?: boolean;
+}

package/dist/types/MessageBox/MessageBox.d.cts

@@ -0,0 +1,3 @@
+import type { MessageBoxProps } from './type.cjs';
+declare const MessageBox: import("react").ForwardRefExoticComponent<MessageBoxProps & import("react").RefAttributes<HTMLDivElement>>;
+export default MessageBox;

package/dist/types/MessageBox/MessageBox.d.ts

@@ -0,0 +1,3 @@
+import type { MessageBoxProps } from './type.js';
+declare const MessageBox: import("react").ForwardRefExoticComponent<MessageBoxProps & import("react").RefAttributes<HTMLDivElement>>;
+export default MessageBox;

package/dist/types/MessageBox/index.d.cts

@@ -0,0 +1,5 @@
+import type { MessageBoxComponent } from './type.cjs';
+/** MessageBox 确认消息弹框组件（支持声明式与命令式 alert/confirm 调用） */
+export declare const VlMessageBox: MessageBoxComponent;
+export type { MessageBoxProps, MessageBoxOptions, MessageBoxType, MessageBoxAction, MessageBoxRef, MessageBoxComponent } from './type.cjs';
+export default VlMessageBox;

package/dist/types/MessageBox/index.d.ts

@@ -0,0 +1,5 @@
+import type { MessageBoxComponent } from './type.js';
+/** MessageBox 确认消息弹框组件（支持声明式与命令式 alert/confirm 调用） */
+export declare const VlMessageBox: MessageBoxComponent;
+export type { MessageBoxProps, MessageBoxOptions, MessageBoxType, MessageBoxAction, MessageBoxRef, MessageBoxComponent } from './type.js';
+export default VlMessageBox;

package/dist/types/MessageBox/service.d.cts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { MessageBoxAction, MessageBoxOptions } from './type.cjs';
+/**
+ * 打开仅含确认操作的命令式消息框。
+ * Promise 在确认成功后 resolve；通过关闭按钮或 Escape 退出时以 `close` reject。
+ */
+export declare const alert: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+/**
+ * 打开同时提供确认与取消操作的命令式消息框。
+ * 取消按钮与其他关闭入口分别以 `cancel`、`close` reject，便于调用方保留不同业务分支。
+ */
+export declare const confirm: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;

package/dist/types/MessageBox/service.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { MessageBoxAction, MessageBoxOptions } from './type.js';
+/**
+ * 打开仅含确认操作的命令式消息框。
+ * Promise 在确认成功后 resolve；通过关闭按钮或 Escape 退出时以 `close` reject。
+ */
+export declare const alert: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+/**
+ * 打开同时提供确认与取消操作的命令式消息框。
+ * 取消按钮与其他关闭入口分别以 `cancel`、`close` reject，便于调用方保留不同业务分支。
+ */
+export declare const confirm: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;

package/dist/types/MessageBox/type.d.cts

@@ -0,0 +1,62 @@
+/**
+ * MessageBox 消息弹框的声明式与命令式公共类型定义。
+ *
+ * 动作类型用于精确区分用户退出路径：
+ * - `'confirm'`: 用户点击确认按钮且异步任务成功；
+ * - `'cancel'`: 用户主动点击取消按钮；
+ * - `'close'`: 用户点击右上角关闭按钮、遮罩层或按下 Escape。
+ */
+import type { ForwardRefExoticComponent, ReactNode, RefAttributes } from 'react';
+import type { ModalProps } from '../Modal/index.cjs';
+/** 消息弹框语义类型：信息 (info) | 成功 (success) | 警告 (warning) | 错误 (error) */
+export type MessageBoxType = 'info' | 'success' | 'warning' | 'error';
+/** 弹框动作结算字面量 */
+export type MessageBoxAction = 'confirm' | 'cancel' | 'close';
+/** MessageBox 根 DOM 元素类型 */
+export type MessageBoxRef = HTMLDivElement;
+/**
+ * MessageBox 组件属性接口
+ */
+export interface MessageBoxProps extends Omit<ModalProps, 'children' | 'footer' | 'header' | 'onClose' | 'title'> {
+    /** 弹框标题，默认为 `'提示'` */
+    title?: ReactNode;
+    /** 提示消息正文内容 */
+    children?: ReactNode;
+    /** 消息提示类型，默认为 `'info'` */
+    type?: MessageBoxType;
+    /** 是否展示取消按钮，默认为 false */
+    showCancelButton?: boolean;
+    /** 确认按钮文案，默认为 `'确定'` */
+    confirmButtonText?: ReactNode;
+    /** 确认进行中时的按钮 loading 文案 */
+    confirmButtonLoadingText?: ReactNode;
+    /** 取消按钮文案，默认为 `'取消'` */
+    cancelButtonText?: ReactNode;
+    /** 点击确认按钮触发的回调函数，可返回 Promise 触发按钮 loading；任务失败时保持打开 */
+    onConfirm?: () => void | Promise<void>;
+    /** 点击取消按钮触发的回调函数 */
+    onCancel?: () => void;
+    /** 仅由 Escape、遮罩或右上角关闭按钮触发，取消按钮单独触发 onCancel */
+    onClose?: () => void;
+    /** onConfirm 抛错或 reject 时触发，错误不会自动关闭 MessageBox */
+    onConfirmError?: (error: unknown) => void;
+}
+/** 命令式调用配置选项类型 */
+export type MessageBoxOptions = Omit<MessageBoxProps, 'children' | 'defaultOpen' | 'onChange' | 'open' | 'showCancelButton'>;
+/** 带命令式 alert/confirm 方法的 MessageBox 组件类型 */
+export interface MessageBoxComponent extends ForwardRefExoticComponent<MessageBoxProps & RefAttributes<MessageBoxRef>> {
+    /**
+     * 命令式唤起警告提示框（仅包含“确定”按钮）。
+     * @param content 提示文本或 ReactNode
+     * @param options 可选配置
+     * @returns 动作 Promise，用户确认时 resolve('confirm')，用户点击关闭或按 Esc 时 reject('close')
+     */
+    alert: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+    /**
+     * 命令式唤起操作确认框（包含“确定”与“取消”按钮）。
+     * @param content 提示文本或 ReactNode
+     * @param options 可选配置
+     * @returns 动作 Promise，用户确认时 resolve('confirm')，用户取消时 reject('cancel')，关闭/Esc 时 reject('close')
+     */
+    confirm: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+}

package/dist/types/MessageBox/type.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MessageBox 消息弹框的声明式与命令式公共类型定义。
+ *
+ * 动作类型用于精确区分用户退出路径：
+ * - `'confirm'`: 用户点击确认按钮且异步任务成功；
+ * - `'cancel'`: 用户主动点击取消按钮；
+ * - `'close'`: 用户点击右上角关闭按钮、遮罩层或按下 Escape。
+ */
+import type { ForwardRefExoticComponent, ReactNode, RefAttributes } from 'react';
+import type { ModalProps } from '../Modal/index.js';
+/** 消息弹框语义类型：信息 (info) | 成功 (success) | 警告 (warning) | 错误 (error) */
+export type MessageBoxType = 'info' | 'success' | 'warning' | 'error';
+/** 弹框动作结算字面量 */
+export type MessageBoxAction = 'confirm' | 'cancel' | 'close';
+/** MessageBox 根 DOM 元素类型 */
+export type MessageBoxRef = HTMLDivElement;
+/**
+ * MessageBox 组件属性接口
+ */
+export interface MessageBoxProps extends Omit<ModalProps, 'children' | 'footer' | 'header' | 'onClose' | 'title'> {
+    /** 弹框标题，默认为 `'提示'` */
+    title?: ReactNode;
+    /** 提示消息正文内容 */
+    children?: ReactNode;
+    /** 消息提示类型，默认为 `'info'` */
+    type?: MessageBoxType;
+    /** 是否展示取消按钮，默认为 false */
+    showCancelButton?: boolean;
+    /** 确认按钮文案，默认为 `'确定'` */
+    confirmButtonText?: ReactNode;
+    /** 确认进行中时的按钮 loading 文案 */
+    confirmButtonLoadingText?: ReactNode;
+    /** 取消按钮文案，默认为 `'取消'` */
+    cancelButtonText?: ReactNode;
+    /** 点击确认按钮触发的回调函数，可返回 Promise 触发按钮 loading；任务失败时保持打开 */
+    onConfirm?: () => void | Promise<void>;
+    /** 点击取消按钮触发的回调函数 */
+    onCancel?: () => void;
+    /** 仅由 Escape、遮罩或右上角关闭按钮触发，取消按钮单独触发 onCancel */
+    onClose?: () => void;
+    /** onConfirm 抛错或 reject 时触发，错误不会自动关闭 MessageBox */
+    onConfirmError?: (error: unknown) => void;
+}
+/** 命令式调用配置选项类型 */
+export type MessageBoxOptions = Omit<MessageBoxProps, 'children' | 'defaultOpen' | 'onChange' | 'open' | 'showCancelButton'>;
+/** 带命令式 alert/confirm 方法的 MessageBox 组件类型 */
+export interface MessageBoxComponent extends ForwardRefExoticComponent<MessageBoxProps & RefAttributes<MessageBoxRef>> {
+    /**
+     * 命令式唤起警告提示框（仅包含“确定”按钮）。
+     * @param content 提示文本或 ReactNode
+     * @param options 可选配置
+     * @returns 动作 Promise，用户确认时 resolve('confirm')，用户点击关闭或按 Esc 时 reject('close')
+     */
+    alert: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+    /**
+     * 命令式唤起操作确认框（包含“确定”与“取消”按钮）。
+     * @param content 提示文本或 ReactNode
+     * @param options 可选配置
+     * @returns 动作 Promise，用户确认时 resolve('confirm')，用户取消时 reject('cancel')，关闭/Esc 时 reject('close')
+     */
+    confirm: (content: ReactNode, options?: MessageBoxOptions) => Promise<MessageBoxAction>;
+}

package/dist/types/Modal/Modal.d.cts

@@ -0,0 +1,3 @@
+import type { ModalProps } from './type.cjs';
+declare const Modal: import("react").ForwardRefExoticComponent<ModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Modal;

package/dist/types/Modal/Modal.d.ts

@@ -0,0 +1,3 @@
+import type { ModalProps } from './type.js';
+declare const Modal: import("react").ForwardRefExoticComponent<ModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export default Modal;

package/dist/types/Modal/index.d.cts

@@ -0,0 +1,5 @@
+import Modal from './Modal.cjs';
+/** Modal 对话框组件 */
+export declare const VlModal: import("react").ForwardRefExoticComponent<import("./type.cjs").ModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { ModalProps, ModalRef } from './type.cjs';
+export default Modal;

package/dist/types/Modal/index.d.ts

@@ -0,0 +1,5 @@
+import Modal from './Modal.js';
+/** Modal 对话框组件 */
+export declare const VlModal: import("react").ForwardRefExoticComponent<import("./type.js").ModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { ModalProps, ModalRef } from './type.js';
+export default Modal;