@ldkj/web-ui 0.15.0 → 0.16.2

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 {};

package/components/form/rate/Rate.d.ts

@@ -1,9 +1,74 @@
-export type RateProps = {
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export type RateSize = "sm" | "md" | "lg";
+export type RateProps = Omit<React.ComponentPropsWithoutRef<"div">, "children" | "onChange"> & {
+    /** 受控评分值。 */
     value?: number;
+    /** 非受控默认评分值。 */
+    defaultValue?: number;
+    /** 星级总数，最小为 `1`。 */
     count?: number;
+    /** 是否允许再次点击当前值后清空。 */
+    allowClear?: boolean;
+    /** 是否移除外层边框与背景。 */
+    borderless?: boolean;
+    /** 是否禁用。 */
     disabled?: boolean;
+    /** 是否只读。只读时保留展示，不响应交互。 */
+    readOnly?: boolean;
+    /** 与原生表单联动的字段名。 */
+    name?: string;
+    /** 评分变更回调。 */
+    onChange?: (value: number) => void;
+    /** 鼠标悬停预览值变更回调。 */
+    onHoverChange?: (value: number | null) => void;
+    /** 星星尺寸。 */
+    size?: RateSize;
+    /** 评分图标。 */
+    character?: React.ReactNode;
+    /** 根节点类名。 */
     className?: string;
+    /** 兼容旧写法的类名。 */
     class?: string;
-    onChange?: (value: number) => void;
+    /** 根节点样式。 */
+    style?: React.CSSProperties;
+    /** CSS-in-JS 样式入口。 */
+    sx?: SxProps;
 };
-export declare function Rate(props: RateProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Rate 用于星级评分、满意度打分和快速反馈场景，支持受控/非受控、悬停预览、键盘操作与表单提交。
+ */
+export declare const Rate: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "onChange"> & {
+    /** 受控评分值。 */
+    value?: number;
+    /** 非受控默认评分值。 */
+    defaultValue?: number;
+    /** 星级总数，最小为 `1`。 */
+    count?: number;
+    /** 是否允许再次点击当前值后清空。 */
+    allowClear?: boolean;
+    /** 是否移除外层边框与背景。 */
+    borderless?: boolean;
+    /** 是否禁用。 */
+    disabled?: boolean;
+    /** 是否只读。只读时保留展示，不响应交互。 */
+    readOnly?: boolean;
+    /** 与原生表单联动的字段名。 */
+    name?: string;
+    /** 评分变更回调。 */
+    onChange?: (value: number) => void;
+    /** 鼠标悬停预览值变更回调。 */
+    onHoverChange?: (value: number | null) => void;
+    /** 星星尺寸。 */
+    size?: RateSize;
+    /** 评分图标。 */
+    character?: React.ReactNode;
+    /** 根节点类名。 */
+    className?: string;
+    /** 兼容旧写法的类名。 */
+    class?: string;
+    /** 根节点样式。 */
+    style?: React.CSSProperties;
+    /** CSS-in-JS 样式入口。 */
+    sx?: SxProps;
+} & React.RefAttributes<HTMLDivElement>>;

package/components/form/slider/Slider.d.ts

@@ -0,0 +1,30 @@
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export type SliderProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "onChange"> & {
+    value?: number;
+    class?: string;
+    /**
+     * 视觉变体。
+     * - `"solid"`：纯色风格，与组件库整体风格统一（默认）
+     * - `"gradient"`：渐变色风格，提供更丰富的视觉效果
+     */
+    variant?: "solid" | "gradient";
+    /**
+     * 轨道粗细。数字会自动转换为 px，字符串会作为 CSS 长度值透传。
+     */
+    trackSize?: number | string;
+    /**
+     * 滑块头尺寸。数字会自动转换为 px，字符串会作为 CSS 长度值透传。
+     */
+    thumbSize?: number | string;
+    sx?: SxProps;
+    onValueChange?: (value: number) => void;
+};
+/**
+ * Slider 是原生 range 输入的封装，保留浏览器原生交互语义，
+ * 同时提供更符合本库风格的视觉样式与数值回调。
+ */
+export declare function Slider(props: SliderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Slider {
+    var displayName: string;
+}

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

@@ -0,0 +1 @@
+export * from "./Slider";

package/components/form/uploader/Uploader.d.ts

@@ -1,6 +1,10 @@
+/**
+ * Uploader 属性。组件通过 `onChange(FileList | null)` 暴露用户选择的文件列表。
+ */
 export type UploaderProps = {
     accept?: string;
     multiple?: boolean;
+    name?: string;
     disabled?: boolean;
     onChange?: (files: FileList | null) => void;
 };

package/components/interact/popover/Popover.d.ts

@@ -11,6 +11,7 @@ type PopoverWrapperProps<TProps> = Omit<TProps, "className" | "style"> & {
     class?: string;
     style?: React.CSSProperties;
     sx?: SxProps;
+    asChildWrapper?: React.ElementType;
 };
 export type PopoverTriggerProps = PopoverWrapperProps<RadixPopoverTriggerProps>;
 export type PopoverCloseProps = PopoverWrapperProps<RadixPopoverCloseProps>;
@@ -30,6 +31,7 @@ declare const PopoverTrigger: React.ForwardRefExoticComponent<Omit<Omit<PopoverP
     class?: string;
     style?: React.CSSProperties;
     sx?: SxProps;
+    asChildWrapper?: React.ElementType;
 } & React.RefAttributes<HTMLElement>>;
 /**
  * Popover 锚点。
@@ -47,6 +49,7 @@ declare const PopoverClose: React.ForwardRefExoticComponent<Omit<Omit<PopoverPri
     class?: string;
     style?: React.CSSProperties;
     sx?: SxProps;
+    asChildWrapper?: React.ElementType;
 } & React.RefAttributes<HTMLElement>>;
 /**
  * PopoverContent 的属性。

package/components/mobile/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mobile-select";
+export * from "./mobile-cascader";

package/components/mobile/mobile-cascader/MobileCascader.d.ts

@@ -0,0 +1,85 @@
+import * as React from "react";
+import type { CascaderFieldNames, CascaderLoadDataMeta, CascaderOption, CascaderRenderOptionState, CascaderValue, CascaderValueChangeMeta } from "@/components/form/cascader";
+import { type SxProps } from "@/styling";
+import { type MobileOptionAlign } from "../shared";
+export type MobileCascaderRef = {
+    focus: () => void;
+    blur: () => void;
+    open: () => void;
+    close: () => void;
+    clear: () => void;
+    getValue: () => CascaderValue;
+};
+export type MobileCascaderProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "value" | "defaultValue" | "onChange"> & {
+    class?: string;
+    sx?: SxProps;
+    options?: CascaderOption[];
+    value?: CascaderValue;
+    defaultValue?: CascaderValue;
+    onValueChange?: (value: CascaderValue, meta: CascaderValueChangeMeta) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placeholder?: React.ReactNode;
+    title?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    confirmText?: React.ReactNode;
+    separator?: React.ReactNode;
+    displayRender?: (labels: React.ReactNode[], options: CascaderOption[]) => React.ReactNode;
+    renderOption?: (option: CascaderOption, state: CascaderRenderOptionState) => React.ReactNode;
+    fieldNames?: CascaderFieldNames;
+    changeOnSelect?: boolean;
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    loadData?: (selectedOptions: CascaderOption[], meta: CascaderLoadDataMeta) => void | Promise<void>;
+    align?: MobileOptionAlign;
+    levelLabels?: React.ReactNode[];
+    drawerClassName?: string;
+    drawerClass?: string;
+    drawerStyle?: React.CSSProperties;
+    drawerSx?: SxProps;
+    maxDrawerHeight?: number | string;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+};
+/**
+ * MobileCascader 是移动端级联抽屉，沿用 Cascader 的路径数组值模型。
+ */
+export declare const MobileCascader: 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;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placeholder?: React.ReactNode;
+    title?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    confirmText?: React.ReactNode;
+    separator?: React.ReactNode;
+    displayRender?: (labels: React.ReactNode[], options: CascaderOption[]) => React.ReactNode;
+    renderOption?: (option: CascaderOption, state: CascaderRenderOptionState) => React.ReactNode;
+    fieldNames?: CascaderFieldNames;
+    changeOnSelect?: boolean;
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    loadData?: (selectedOptions: CascaderOption[], meta: CascaderLoadDataMeta) => void | Promise<void>;
+    align?: MobileOptionAlign;
+    levelLabels?: React.ReactNode[];
+    drawerClassName?: string;
+    drawerClass?: string;
+    drawerStyle?: React.CSSProperties;
+    drawerSx?: SxProps;
+    maxDrawerHeight?: number | string;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+} & React.RefAttributes<MobileCascaderRef>>;

package/components/mobile/mobile-cascader/index.d.ts

@@ -0,0 +1 @@
+export * from "./MobileCascader";

package/components/mobile/mobile-select/MobileSelect.d.ts

@@ -0,0 +1,86 @@
+import * as React from "react";
+import type { SelectOption, SelectOptionGroup } from "@/components/form/select";
+import { type SxProps } from "@/styling";
+import { type MobileOptionAlign } from "../shared";
+export type MobileSelectValueChangeReason = "select" | "clear";
+export type MobileSelectValueChangeMeta = {
+    reason: MobileSelectValueChangeReason;
+    option?: SelectOption;
+    event?: React.SyntheticEvent;
+};
+export type MobileSelectRenderOptionState = {
+    active: boolean;
+    checked: boolean;
+    disabled: boolean;
+};
+export type MobileSelectRef = {
+    focus: () => void;
+    blur: () => void;
+    open: () => void;
+    close: () => void;
+    clear: () => void;
+    getValue: () => string;
+};
+export type MobileSelectProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "value" | "defaultValue" | "onChange"> & {
+    class?: string;
+    sx?: SxProps;
+    options?: Array<SelectOption | SelectOptionGroup>;
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string, meta: MobileSelectValueChangeMeta) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placeholder?: React.ReactNode;
+    title?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    confirmText?: React.ReactNode;
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    align?: MobileOptionAlign;
+    displayRender?: (option: SelectOption | undefined) => React.ReactNode;
+    renderOption?: (option: SelectOption, state: MobileSelectRenderOptionState) => React.ReactNode;
+    drawerClassName?: string;
+    drawerClass?: string;
+    drawerStyle?: React.CSSProperties;
+    drawerSx?: SxProps;
+    maxDrawerHeight?: number | string;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+};
+/**
+ * MobileSelect 是面向移动端的单选抽屉，沿用 Select 的 option 数据模型。
+ */
+export declare const MobileSelect: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "children" | "defaultValue" | "onChange"> & {
+    class?: string;
+    sx?: SxProps;
+    options?: Array<SelectOption | SelectOptionGroup>;
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string, meta: MobileSelectValueChangeMeta) => void;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placeholder?: React.ReactNode;
+    title?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    confirmText?: React.ReactNode;
+    clearable?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    align?: MobileOptionAlign;
+    displayRender?: (option: SelectOption | undefined) => React.ReactNode;
+    renderOption?: (option: SelectOption, state: MobileSelectRenderOptionState) => React.ReactNode;
+    drawerClassName?: string;
+    drawerClass?: string;
+    drawerStyle?: React.CSSProperties;
+    drawerSx?: SxProps;
+    maxDrawerHeight?: number | string;
+    optionClassName?: string;
+    optionClass?: string;
+    optionStyle?: React.CSSProperties;
+    optionSx?: SxProps;
+} & React.RefAttributes<MobileSelectRef>>;

package/components/mobile/mobile-select/index.d.ts

@@ -0,0 +1 @@
+export * from "./MobileSelect";

package/components/mobile/shared.d.ts

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export type MobileOptionAlign = "left" | "center" | "right";
+export type MobileDrawerProps = {
+    open: boolean;
+    title?: React.ReactNode;
+    cancelText?: React.ReactNode;
+    confirmText?: React.ReactNode;
+    confirmDisabled?: boolean;
+    maxHeight?: number | string;
+    children?: React.ReactNode;
+    className?: string;
+    class?: string;
+    style?: React.CSSProperties;
+    sx?: SxProps;
+    onCancel?: () => void;
+    onConfirm?: () => void;
+    onOpenChange?: (open: boolean) => void;
+};
+export type MobileTriggerProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    open?: boolean;
+    clearable?: boolean;
+    hasValue?: boolean;
+    readOnly?: boolean;
+    placeholder?: React.ReactNode;
+    display?: React.ReactNode;
+    class?: string;
+    sx?: SxProps;
+    onClear?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+};
+type ControllableOptions<T> = {
+    value?: T;
+    defaultValue: T;
+    onChange?: (value: T) => void;
+};
+export declare function useControllableValue<T>(options: ControllableOptions<T>): readonly [T, (nextValue: T) => void, boolean];
+export declare function useResolvedSx(sx: SxProps | undefined): {
+    sxClassName: undefined;
+    sxInlineStyle: undefined;
+} | {
+    sxClassName: string;
+    sxInlineStyle: React.CSSProperties;
+};
+export declare function resolveLength(value: number | string | undefined): string | undefined;
+export declare function getAlignClass(align: MobileOptionAlign | undefined): "justify-center text-center" | "justify-end text-right" | "justify-start text-left";
+export declare function ChevronDownIcon(props: React.SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;
+export declare function ChevronRightIcon(props: React.SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;
+export declare function ClearIcon(props: React.SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;
+export declare function LoadingSpinner(): import("react/jsx-runtime").JSX.Element;
+export declare function MobileDrawer(props: MobileDrawerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const MobileTrigger: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    open?: boolean;
+    clearable?: boolean;
+    hasValue?: boolean;
+    readOnly?: boolean;
+    placeholder?: React.ReactNode;
+    display?: React.ReactNode;
+    class?: string;
+    sx?: SxProps;
+    onClear?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+} & React.RefAttributes<HTMLButtonElement>>;
+export {};