@ldkj/web-ui 0.15.0 → 0.16.1

package/components/form/auto-complete/AutoComplete.d.ts

@@ -1,9 +1,106 @@
+import * as React from "react";
 import { type InputProps } from "@/components/form/input";
+import { type SxProps } from "@/styling";
 export type AutoCompleteOption = {
-    label: string;
+    label: React.ReactNode;
     value: string;
+    disabled?: boolean;
+    description?: React.ReactNode;
+    keywords?: string[];
+    textValue?: string;
 };
-export type AutoCompleteProps = Omit<InputProps, "list"> & {
+export type AutoCompleteValueChangeReason = "input" | "select";
+export type AutoCompleteValueChangeMeta = {
+    reason: AutoCompleteValueChangeReason;
+    option?: AutoCompleteOption;
+    event: React.ChangeEvent<HTMLInputElement>;
+};
+export type AutoCompleteFilterOption = (option: AutoCompleteOption, keyword: string) => boolean;
+export type AutoCompleteRenderOptionState = {
+    active: boolean;
+    disabled: boolean;
+    inputValue: string;
+    selected: boolean;
+};
+export type AutoCompleteProps = Omit<InputProps, "defaultValue" | "list" | "onChange" | "value"> & {
     options?: AutoCompleteOption[];
+    value?: string | number;
+    defaultValue?: string | number;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+    /**
+     * 返回输入值变化。`reason` 为 `select` 时表示来自建议项选择。
+     */
+    onValueChange?: (value: string, meta: AutoCompleteValueChangeMeta) => void;
+    /**
+     * 点击或键盘确认建议项时触发。
+     */
+    onOptionSelect?: (option: AutoCompleteOption, event: React.KeyboardEvent<HTMLInputElement> | React.MouseEvent<HTMLDivElement>) => void;
+    /**
+     * 自定义过滤逻辑。传入 `false` 时不做本地过滤。
+     */
+    filterOption?: AutoCompleteFilterOption | false;
+    /**
+     * 输入框聚焦时是否立即展示建议面板。
+     */
+    openOnFocus?: boolean;
+    /**
+     * 没有匹配项时的提示内容。传入 `null` 可隐藏空状态面板。
+     */
+    emptyText?: React.ReactNode;
+    /**
+     * 自定义建议项渲染。
+     */
+    renderOption?: (option: AutoCompleteOption, state: AutoCompleteRenderOptionState) => React.ReactNode;
+    rootClassName?: string;
+    rootStyle?: React.CSSProperties;
+    rootSx?: SxProps;
+    dropdownClassName?: string;
+    dropdownStyle?: React.CSSProperties;
+    dropdownSx?: SxProps;
+    optionClassName?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
 };
-export declare function AutoComplete(props: AutoCompleteProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * AutoComplete 是带建议面板的文本输入组件。组件使用自绘 listbox 替代原生
+ * datalist，使下拉样式、键盘交互和空状态与本库表单组件保持一致。
+ */
+export declare const AutoComplete: React.ForwardRefExoticComponent<Omit<InputProps, "value" | "list" | "defaultValue" | "onChange"> & {
+    options?: AutoCompleteOption[];
+    value?: string | number;
+    defaultValue?: string | number;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+    /**
+     * 返回输入值变化。`reason` 为 `select` 时表示来自建议项选择。
+     */
+    onValueChange?: (value: string, meta: AutoCompleteValueChangeMeta) => void;
+    /**
+     * 点击或键盘确认建议项时触发。
+     */
+    onOptionSelect?: (option: AutoCompleteOption, event: React.KeyboardEvent<HTMLInputElement> | React.MouseEvent<HTMLDivElement>) => void;
+    /**
+     * 自定义过滤逻辑。传入 `false` 时不做本地过滤。
+     */
+    filterOption?: AutoCompleteFilterOption | false;
+    /**
+     * 输入框聚焦时是否立即展示建议面板。
+     */
+    openOnFocus?: boolean;
+    /**
+     * 没有匹配项时的提示内容。传入 `null` 可隐藏空状态面板。
+     */
+    emptyText?: React.ReactNode;
+    /**
+     * 自定义建议项渲染。
+     */
+    renderOption?: (option: AutoCompleteOption, state: AutoCompleteRenderOptionState) => React.ReactNode;
+    rootClassName?: string;
+    rootStyle?: React.CSSProperties;
+    rootSx?: SxProps;
+    dropdownClassName?: string;
+    dropdownStyle?: React.CSSProperties;
+    dropdownSx?: SxProps;
+    optionClassName?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+} & React.RefAttributes<HTMLInputElement>>;

package/components/form/cascader/Cascader.d.ts

@@ -1,12 +1,133 @@
+import * as React from "react";
+import { type PopoverContentProps } from "@/components/interact/popover";
+import { type SxProps } from "@/styling";
+export type CascaderFieldNames = {
+    label?: string;
+    value?: string;
+    children?: string;
+    disabled?: string;
+    isLeaf?: string;
+    loading?: string;
+};
 export type CascaderOption = {
-    label: string;
-    value: string;
+    label?: React.ReactNode;
+    value?: string;
     children?: CascaderOption[];
+    disabled?: boolean;
+    isLeaf?: boolean;
+    loading?: boolean;
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+} & Record<string, unknown>;
+export type CascaderValue = string[];
+export type CascaderValueChangeReason = "select" | "clear";
+export type CascaderValueChangeMeta = {
+    reason: CascaderValueChangeReason;
+    path: string[];
+    options: CascaderOption[];
+    option?: CascaderOption;
+    labels: React.ReactNode[];
+    event?: React.SyntheticEvent;
+};
+export type CascaderLoadDataMeta = {
+    option: CascaderOption;
+    path: string[];
+    options: CascaderOption[];
 };
-export type CascaderProps = {
+export type CascaderRenderOptionState = {
+    active: boolean;
+    checked: boolean;
+    disabled: boolean;
+    hasChildren: boolean;
+    isLeaf: boolean;
+    level: number;
+    loading: boolean;
+    path: string[];
+    selected: boolean;
+};
+export type CascaderRef = {
+    focus: () => void;
+    blur: () => void;
+    open: () => void;
+    close: () => void;
+    clear: () => void;
+    getValue: () => CascaderValue;
+};
+export type CascaderProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "value" | "defaultValue" | "onChange"> & {
+    class?: string;
+    sx?: SxProps;
     options?: CascaderOption[];
-    value?: string;
-    placeholder?: string;
-    onValueChange?: (value: string) => void;
+    value?: CascaderValue;
+    defaultValue?: CascaderValue;
+    onValueChange?: (value: CascaderValue, meta: CascaderValueChangeMeta) => void;
+    onOpenChange?: (open: boolean) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    placeholder?: React.ReactNode;
+    separator?: React.ReactNode;
+    displayRender?: (labels: React.ReactNode[], options: CascaderOption[]) => React.ReactNode;
+    renderOption?: (option: CascaderOption, state: CascaderRenderOptionState) => React.ReactNode;
+    fieldNames?: CascaderFieldNames;
+    changeOnSelect?: boolean;
+    expandTrigger?: "click" | "hover";
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    loadData?: (selectedOptions: CascaderOption[], meta: CascaderLoadDataMeta) => void | Promise<void>;
+    contentWidth?: number | string;
+    maxPanelHeight?: number | string;
+    side?: PopoverContentProps["side"];
+    align?: PopoverContentProps["align"];
+    sideOffset?: number;
+    contentClassName?: string;
+    contentClass?: string;
+    contentStyle?: React.CSSProperties;
+    contentSx?: SxProps;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
 };
-export declare function Cascader(props: CascaderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Cascader 是多级联动选择器，支持受控/非受控、路径值、清除、懒加载与自定义选项渲染。
+ *
+ * 组件默认按路径数组提交值，例如 `["zhejiang", "hangzhou"]`。
+ * 如果开启 `changeOnSelect`，选择中间层节点也会立即提交当前路径。
+ */
+export declare const Cascader: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "children" | "defaultValue" | "onChange"> & {
+    class?: string;
+    sx?: SxProps;
+    options?: CascaderOption[];
+    value?: CascaderValue;
+    defaultValue?: CascaderValue;
+    onValueChange?: (value: CascaderValue, meta: CascaderValueChangeMeta) => void;
+    onOpenChange?: (open: boolean) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    placeholder?: React.ReactNode;
+    separator?: React.ReactNode;
+    displayRender?: (labels: React.ReactNode[], options: CascaderOption[]) => React.ReactNode;
+    renderOption?: (option: CascaderOption, state: CascaderRenderOptionState) => React.ReactNode;
+    fieldNames?: CascaderFieldNames;
+    changeOnSelect?: boolean;
+    expandTrigger?: "click" | "hover";
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    loadData?: (selectedOptions: CascaderOption[], meta: CascaderLoadDataMeta) => void | Promise<void>;
+    contentWidth?: number | string;
+    maxPanelHeight?: number | string;
+    side?: PopoverContentProps["side"];
+    align?: PopoverContentProps["align"];
+    sideOffset?: number;
+    contentClassName?: string;
+    contentClass?: string;
+    contentStyle?: React.CSSProperties;
+    contentSx?: SxProps;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+} & React.RefAttributes<CascaderRef>>;

package/components/form/form/Form.d.ts

@@ -0,0 +1,67 @@
+import * as React from "react";
+import { type SxProps } from "@/styling";
+import { type FormCallbacks, type FormInstance, type FormNamePath, type FormRule, type FormValidateTrigger, type FormValues, useForm, useFormInstance, useFormValue, useFormWatch } from "./useForm";
+type AnyRecord = Record<string, unknown>;
+/**
+ * Form 组件属性。默认保持原生 `form` 语义，传入增强回调或 `form` 实例后启用状态管理提交链路。
+ */
+export type FormProps<TValues extends FormValues = FormValues> = Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & FormCallbacks<TValues> & {
+    class?: string;
+    form?: FormInstance<TValues>;
+    initialValues?: Partial<TValues>;
+    nativeSubmit?: boolean;
+    onSubmit?: React.FormEventHandler<HTMLFormElement>;
+    sx?: SxProps;
+};
+/**
+ * `Form.Item` render props，用于自定义字段渲染时读取当前值、meta 和表单实例。
+ */
+export type FormItemRenderProps<TValues extends FormValues = FormValues> = {
+    form: FormInstance<TValues>;
+    value: unknown;
+    values: TValues;
+    meta: ReturnType<FormInstance<TValues>["getFieldMeta"]>;
+};
+/**
+ * `Form.Item` 属性。通过 `name` 注册字段，并把子控件自动接入 `useForm` 状态层。
+ */
+export type FormItemProps<TValues extends FormValues = FormValues> = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    children?: React.ReactNode | ((props: FormItemRenderProps<TValues>) => React.ReactNode);
+    class?: string;
+    controlClassName?: string;
+    controlStyle?: React.CSSProperties;
+    dependencies?: FormNamePath[];
+    extra?: React.ReactNode;
+    getValueFromEvent?: (...args: unknown[]) => unknown;
+    getValueProps?: (value: unknown) => AnyRecord;
+    help?: React.ReactNode;
+    initialValue?: unknown;
+    label?: React.ReactNode;
+    labelClassName?: string;
+    labelStyle?: React.CSSProperties;
+    name?: FormNamePath;
+    noStyle?: boolean;
+    preserve?: boolean;
+    required?: boolean;
+    rules?: FormRule<TValues>[];
+    sx?: SxProps;
+    trigger?: string;
+    validateFirst?: boolean;
+    validateStatus?: "error" | "success" | "warning" | "validating";
+    validateTrigger?: FormValidateTrigger;
+    valuePropName?: string;
+};
+declare function FormItem<TValues extends FormValues = FormValues>(props: FormItemProps<TValues>): import("react/jsx-runtime").JSX.Element;
+declare namespace FormItem {
+    var displayName: string;
+}
+type FormComponent = (<TValues extends FormValues = FormValues>(props: FormProps<TValues>) => React.ReactElement) & {
+    displayName?: string;
+    Item: typeof FormItem;
+    useForm: typeof useForm;
+    useFormInstance: typeof useFormInstance;
+    useFormValue: typeof useFormValue;
+    useFormWatch: typeof useFormWatch;
+};
+declare const Form: FormComponent;
+export { Form, FormItem, useForm, useFormInstance, useFormValue, useFormWatch, };

package/components/form/form/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Form";
+export type { FormCallbacks, FormErrorField, FormFieldData, FormFieldMeta, FormFinishFailedInfo, FormInstance, FormNamePath, FormRule, FormValidateOptions, FormValidateTrigger, FormValues, } from "./useForm";

package/components/form/form/useForm.d.ts

@@ -0,0 +1,157 @@
+import * as React from "react";
+/**
+ * 表单字段路径，支持字符串、数字或数组路径，例如 `user.name` 或 `["user", "name"]`。
+ */
+export type FormNamePath = string | number | readonly (string | number)[];
+/**
+ * 表单值对象类型。
+ */
+export type FormValues = Record<string, unknown>;
+/**
+ * 字段校验触发器名称，通常是 `onChange`、`onBlur` 或控件自定义事件。
+ */
+export type FormValidateTrigger = string | readonly string[];
+/**
+ * 字段校验规则，支持必填、值转换和同步/异步自定义校验。
+ */
+export type FormRule<TValues extends FormValues = FormValues> = {
+    required?: boolean;
+    message?: React.ReactNode;
+    validateTrigger?: FormValidateTrigger;
+    transform?: (value: unknown) => unknown;
+    validator?: (value: unknown, values: TValues, form: FormInstance<TValues>) => void | boolean | React.ReactNode | Promise<void | boolean | React.ReactNode>;
+};
+/**
+ * 字段状态信息，用于展示 touched、validating 与错误文案。
+ */
+export type FormFieldMeta = {
+    touched: boolean;
+    validating: boolean;
+    errors: React.ReactNode[];
+};
+/**
+ * 字段数据快照，用于 `setFields` 与 `onFieldsChange`。
+ */
+export type FormFieldData = {
+    name: FormNamePath;
+    value?: unknown;
+    touched?: boolean;
+    validating?: boolean;
+    errors?: React.ReactNode[];
+};
+/**
+ * 校验失败字段信息。
+ */
+export type FormErrorField = {
+    name: FormNamePath;
+    errors: React.ReactNode[];
+};
+/**
+ * 表单提交失败回调参数。
+ */
+export type FormFinishFailedInfo<TValues extends FormValues = FormValues> = {
+    values: TValues;
+    errorFields: FormErrorField[];
+    outOfDate: boolean;
+};
+/**
+ * 表单增强回调集合。
+ */
+export type FormCallbacks<TValues extends FormValues = FormValues> = {
+    onValuesChange?: (changedValues: Partial<TValues>, values: TValues) => void;
+    onFieldsChange?: (changedFields: FormFieldData[], fields: FormFieldData[]) => void;
+    onFinish?: (values: TValues) => void;
+    onFinishFailed?: (info: FormFinishFailedInfo<TValues>) => void;
+};
+/**
+ * 校验选项，内部校验可指定字段、触发器和仅校验模式。
+ */
+export type FormValidateOptions = {
+    names?: FormNamePath[];
+    trigger?: string;
+    validateOnly?: boolean;
+};
+type FormFieldEntity<TValues extends FormValues = FormValues> = {
+    name: FormNamePath;
+    rules: FormRule<TValues>[];
+    validateTrigger?: FormValidateTrigger;
+    dependencies: FormNamePath[];
+    validateFirst?: boolean;
+};
+type FormSetValueOptions = {
+    touched?: boolean;
+    trigger?: string;
+    source?: "internal" | "external";
+};
+type FormInternalHooks<TValues extends FormValues = FormValues> = {
+    getStoreSnapshot: () => TValues;
+    getMetaSnapshot: (name: FormNamePath) => FormFieldMeta;
+    setCallbacks: (callbacks: FormCallbacks<TValues>) => void;
+    setInitialValues: (values: Partial<TValues> | undefined, init: boolean) => void;
+    registerField: (entity: FormFieldEntity<TValues>) => (options?: {
+        preserve?: boolean;
+    }) => void;
+    setFieldValue: (name: FormNamePath, value: unknown, options?: FormSetValueOptions) => void;
+    validateFields: (names?: FormNamePath[], options?: Pick<FormValidateOptions, "trigger" | "validateOnly">) => Promise<TValues>;
+};
+/**
+ * 表单实例 API，用于读取、写入、重置、校验、提交和订阅表单状态。
+ */
+export type FormInstance<TValues extends FormValues = FormValues> = {
+    getFieldValue: (name: FormNamePath) => unknown;
+    getFieldsValue: (names?: FormNamePath[]) => TValues;
+    getFieldError: (name: FormNamePath) => React.ReactNode[];
+    getFieldsError: (names?: FormNamePath[]) => FormErrorField[];
+    getFieldMeta: (name: FormNamePath) => FormFieldMeta;
+    isFieldTouched: (name: FormNamePath) => boolean;
+    isFieldsTouched: (names?: FormNamePath[]) => boolean;
+    setFieldValue: (name: FormNamePath, value: unknown) => void;
+    setFieldsValue: (values: Partial<TValues>) => void;
+    setFields: (fields: FormFieldData[]) => void;
+    resetFields: (names?: FormNamePath[]) => void;
+    validateFields: (names?: FormNamePath[]) => Promise<TValues>;
+    submit: () => Promise<void>;
+    subscribe: (listener: () => void) => () => void;
+    __INTERNAL__: FormInternalHooks<TValues>;
+};
+/**
+ * Form 内部上下文，供 `Form.Item` 和表单 hooks 读取当前表单实例。
+ */
+export declare const FormContext: React.Context<FormInstance<FormValues> | null>;
+/**
+ * 将字段路径统一转换为数组路径。
+ */
+export declare function toNamePath(name: FormNamePath): (string | number)[];
+/**
+ * 获取字段路径的稳定 key，用于字段注册表和 meta 映射。
+ */
+export declare function getNamePathKey(name: FormNamePath): string;
+/**
+ * 获取字段路径字符串，用于透传原生控件 `name` 属性。
+ */
+export declare function getNamePathString(name: FormNamePath): string;
+/**
+ * 创建独立表单实例。通常优先使用 `useForm`，测试或外部 store 场景可直接使用。
+ */
+export declare function createForm<TValues extends FormValues = FormValues>(initialValues?: Partial<TValues>): FormInstance<TValues>;
+/**
+ * 创建或复用表单实例，返回值结构与 Ant Design 的 `Form.useForm()` 保持一致。
+ */
+export declare function useForm<TValues extends FormValues = FormValues>(form?: FormInstance<TValues>): readonly [FormInstance<TValues>];
+/**
+ * 从当前 Form 上下文读取表单实例。
+ */
+export declare function useFormInstance<TValues extends FormValues = FormValues>(): FormInstance<TValues>;
+/**
+ * 订阅并读取字段值；不传 `name` 时返回整份表单值。
+ */
+export declare function useFormValue<TValue = unknown>(name?: FormNamePath, form?: FormInstance): TValue;
+/**
+ * `useFormValue` 的语义化别名，用于表达字段监听场景。
+ */
+export declare function useFormWatch<TValue = unknown>(name?: FormNamePath, form?: FormInstance): TValue;
+/**
+ * 订阅字段 meta，用于 `Form.Item` 内部和高级自定义字段状态展示。
+ */
+export declare function useFormFieldMeta(name: FormNamePath, form?: FormInstance): FormFieldMeta;
+export {};

package/components/form/input/index.d.ts

@@ -1 +1,2 @@
 export * from "./input";
+export * from "./useInputValue";

package/components/form/input/useInputValue.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+export type InputValueChangeReason = "input" | "commit" | "set";
+export type InputValueChangeMeta = {
+    reason: InputValueChangeReason;
+    valueAsString: string;
+    event?: React.ChangeEvent<HTMLInputElement> | React.FocusEvent<HTMLInputElement>;
+};
+export type UseInputValueOptions = {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string, meta: InputValueChangeMeta) => void;
+    formatOnBlur?: (value: string) => string;
+};
+export type UseInputValueResult = {
+    value: string;
+    setValue: (value: string) => void;
+    inputProps: {
+        value: string;
+        onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+        onBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
+    };
+};
+/**
+ * 管理文本输入的字符串状态，并可在失焦时统一格式化。
+ * 适合需要 trim、大小写转换、简单掩码前置处理等场景。
+ */
+export declare function useInputValue(options?: UseInputValueOptions): UseInputValueResult;

package/components/form/input-number/InputNumber.d.ts

@@ -1,7 +1,51 @@
+import * as React from "react";
 import { type InputProps } from "@/components/form/input";
+export type InputNumberValueChangeReason = "input" | "commit";
+export type InputNumberValueChangeMeta = {
+    reason: InputNumberValueChangeReason;
+    valueAsString: string;
+    event: React.ChangeEvent<HTMLInputElement> | React.FocusEvent<HTMLInputElement>;
+};
 export type InputNumberProps = Omit<InputProps, "type" | "inputMode"> & {
     min?: number;
     max?: number;
     step?: number;
+    /** 失焦时是否将输入值修正到 `min/max/step` 描述的合法区间。 */
+    clampOnBlur?: boolean;
+    /** 失焦归一化后的固定小数位数。 */
+    precision?: number;
+    /** 返回解析后的数值；空值或非法临时值返回 `null`。 */
+    onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+};
+export type UseInputNumberStateOptions = NormalizeOptions & {
+    defaultValue?: string | number | null;
+    onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+};
+export type UseInputNumberStateResult = {
+    value: string;
+    numberValue: number | null;
+    setValue: (value: string | number | null) => void;
+    inputProps: Pick<InputNumberProps, "clampOnBlur" | "max" | "min" | "onChange" | "onValueChange" | "precision" | "step" | "value">;
 };
-export declare function InputNumber(props: InputNumberProps): import("react/jsx-runtime").JSX.Element;
+type NormalizeOptions = Pick<InputNumberProps, "clampOnBlur" | "max" | "min" | "precision" | "step">;
+/**
+ * 管理 InputNumber 的字符串输入态与解析后的数字值。
+ * 它会自动同步 `clampOnBlur` 产生的提交值，避免业务侧手写 commit 分支。
+ */
+export declare function useInputNumberState(options?: UseInputNumberStateOptions): UseInputNumberStateResult;
+/**
+ * InputNumber 是数字输入框组件。默认保留原生 number 输入行为；
+ * 需要强业务约束时可开启 `clampOnBlur`，在失焦时归一化到合法数值。
+ */
+export declare const InputNumber: React.ForwardRefExoticComponent<Omit<InputProps, "type" | "inputMode"> & {
+    min?: number;
+    max?: number;
+    step?: number;
+    /** 失焦时是否将输入值修正到 `min/max/step` 描述的合法区间。 */
+    clampOnBlur?: boolean;
+    /** 失焦归一化后的固定小数位数。 */
+    precision?: number;
+    /** 返回解析后的数值；空值或非法临时值返回 `null`。 */
+    onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+} & React.RefAttributes<HTMLInputElement>>;
+export {};

package/components/form/input-opt/InputOPT.d.ts

@@ -1,9 +1,103 @@
-export type InputOPTProps = {
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export type InputOPTValueType = "numeric" | "alphabetic" | "alphanumeric";
+export type InputOPTSize = "sm" | "md" | "lg";
+export type InputOPTVariant = "outline" | "filled" | "underline";
+type NativeInputProps = Omit<React.ComponentPropsWithoutRef<"input">, "autoFocus" | "children" | "className" | "defaultValue" | "maxLength" | "onChange" | "pattern" | "placeholder" | "size" | "style" | "type" | "value">;
+export type InputOPTProps = NativeInputProps & {
+    /** 受控验证码值。 */
     value?: string;
+    /** 非受控默认验证码值。 */
+    defaultValue?: string;
+    /** 验证码位数。 */
     length?: number;
-    disabled?: boolean;
+    /** 值变化回调，返回过滤后的完整验证码字符串。 */
+    onChange?: (value: string) => void;
+    /** 填满所有位后触发。 */
+    onComplete?: (value: string) => void;
+    /** 字符类型过滤规则。 */
+    type?: InputOPTValueType;
+    /** 自定义单字符过滤规则。 */
+    pattern?: RegExp | string;
+    /** 粘贴内容进入过滤前的转换函数。 */
+    pasteTransformer?: (value: string) => string;
+    /** 是否视觉掩码展示，传入字符串可自定义掩码字符。 */
+    mask?: boolean | string;
+    /** 空槽位占位字符。 */
+    placeholder?: string;
+    /** 首次挂载时是否自动聚焦输入。 */
+    autoFocus?: boolean;
+    /** 是否启用一次性验证码自动填充语义。 */
+    oneTimeCode?: boolean;
+    /** 槽位尺寸。 */
+    size?: InputOPTSize;
+    /** 槽位视觉风格。 */
+    variant?: InputOPTVariant;
+    /** 是否展示错误态。 */
+    invalid?: boolean;
+    /** 根节点类名。 */
     className?: string;
+    /** 兼容旧写法的根节点类名。 */
     class?: string;
-    onChange?: (value: string) => void;
+    /** 真实 input 的类名。 */
+    inputClassName?: string;
+    /** 单个槽位类名。 */
+    slotClassName?: string;
+    /** 槽位之间的分隔内容。 */
+    separator?: React.ReactNode | ((index: number) => React.ReactNode);
+    /** 根节点样式。 */
+    style?: React.CSSProperties;
+    /** CSS-in-JS 样式入口。 */
+    sx?: SxProps;
 };
-export declare function InputOPT(props: InputOPTProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * InputOPT 是一次性验证码输入组件。它使用一个真实 input 承接输入、自动填充和表单提交，
+ * 再用槽位展示验证码字符，确保线性输入、连续删除和粘贴分发行为稳定一致。
+ */
+export declare const InputOPT: React.ForwardRefExoticComponent<NativeInputProps & {
+    /** 受控验证码值。 */
+    value?: string;
+    /** 非受控默认验证码值。 */
+    defaultValue?: string;
+    /** 验证码位数。 */
+    length?: number;
+    /** 值变化回调，返回过滤后的完整验证码字符串。 */
+    onChange?: (value: string) => void;
+    /** 填满所有位后触发。 */
+    onComplete?: (value: string) => void;
+    /** 字符类型过滤规则。 */
+    type?: InputOPTValueType;
+    /** 自定义单字符过滤规则。 */
+    pattern?: RegExp | string;
+    /** 粘贴内容进入过滤前的转换函数。 */
+    pasteTransformer?: (value: string) => string;
+    /** 是否视觉掩码展示，传入字符串可自定义掩码字符。 */
+    mask?: boolean | string;
+    /** 空槽位占位字符。 */
+    placeholder?: string;
+    /** 首次挂载时是否自动聚焦输入。 */
+    autoFocus?: boolean;
+    /** 是否启用一次性验证码自动填充语义。 */
+    oneTimeCode?: boolean;
+    /** 槽位尺寸。 */
+    size?: InputOPTSize;
+    /** 槽位视觉风格。 */
+    variant?: InputOPTVariant;
+    /** 是否展示错误态。 */
+    invalid?: boolean;
+    /** 根节点类名。 */
+    className?: string;
+    /** 兼容旧写法的根节点类名。 */
+    class?: string;
+    /** 真实 input 的类名。 */
+    inputClassName?: string;
+    /** 单个槽位类名。 */
+    slotClassName?: string;
+    /** 槽位之间的分隔内容。 */
+    separator?: React.ReactNode | ((index: number) => React.ReactNode);
+    /** 根节点样式。 */
+    style?: React.CSSProperties;
+    /** CSS-in-JS 样式入口。 */
+    sx?: SxProps;
+} & React.RefAttributes<HTMLInputElement>>;
+export {};