@ldkj/web-ui 0.19.0 → 0.21.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ldkj
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ldkj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

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

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

@@ -1,14 +1,45 @@
 import * as React from "react";
 import { type SxProps } from "@/styling";
-export type InputProps = React.ComponentPropsWithoutRef<"input"> & {
+export type InputSlotProps = {
+    children?: React.ReactNode;
+};
+export type InputAddonProps = InputSlotProps & {
+    position?: "before" | "after";
+};
+export type InputProps = Omit<React.ComponentPropsWithoutRef<"input">, "prefix"> & {
+    addonAfter?: React.ReactNode;
+    addonBefore?: React.ReactNode;
     class?: string;
+    prefix?: React.ReactNode;
+    suffix?: React.ReactNode;
     sx?: SxProps;
 };
-/**
- * Input 是基础文本输入框组件，支持原生 input 属性、`class` 别名与本库 `sx` 样式系统。
- */
-declare const Input: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & {
+export declare const Input: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "prefix"> & {
+    addonAfter?: React.ReactNode;
+    addonBefore?: React.ReactNode;
     class?: string;
+    prefix?: React.ReactNode;
+    suffix?: React.ReactNode;
     sx?: SxProps;
-} & React.RefAttributes<HTMLInputElement>>;
-export { Input };
+} & React.RefAttributes<HTMLInputElement>> & {
+    Addon: {
+        (props: InputAddonProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    AddonAfter: {
+        (props: InputSlotProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    AddonBefore: {
+        (props: InputSlotProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Prefix: {
+        (props: InputSlotProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    Suffix: {
+        (props: InputSlotProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+};

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

@@ -1,10 +1,10 @@
 import * as React from "react";
 import { type InputProps } from "@/components/form/input";
-export type InputNumberValueChangeReason = "input" | "commit";
+export type InputNumberValueChangeReason = "input" | "commit" | "set";
 export type InputNumberValueChangeMeta = {
     reason: InputNumberValueChangeReason;
     valueAsString: string;
-    event: React.ChangeEvent<HTMLInputElement> | React.FocusEvent<HTMLInputElement>;
+    event?: React.ChangeEvent<HTMLInputElement> | React.FocusEvent<HTMLInputElement> | React.KeyboardEvent<HTMLInputElement>;
 };
 export type InputNumberProps = Omit<InputProps, "type" | "inputMode"> & {
     min?: number;
@@ -16,6 +16,32 @@ export type InputNumberProps = Omit<InputProps, "type" | "inputMode"> & {
     precision?: number;
     /** 返回解析后的数值；空值或非法临时值返回 `null`。 */
     onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+    /** 输入值提交时触发，默认在失焦或按下 Enter 时提交。 */
+    onValueCommit?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+};
+export type NumberInputValue = string | number | null;
+export type UseNumberInputOptions = NormalizeOptions & {
+    value?: NumberInputValue;
+    defaultValue?: string | number | null;
+    onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+    onValueCommit?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+};
+export type UseNumberInputGetInputProps = Omit<InputProps, "defaultValue" | "inputMode" | "max" | "min" | "onBlur" | "onChange" | "onKeyDown" | "step" | "type" | "value"> & {
+    disabled?: boolean;
+    readOnly?: boolean;
+    onBlur?: React.FocusEventHandler<HTMLInputElement>;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+};
+export type UseNumberInputResult = {
+    value: string;
+    numberValue: number | null;
+    setValue: (value: NumberInputValue) => void;
+    commitValue: (value?: NumberInputValue) => {
+        value: number | null;
+        valueAsString: string;
+    };
+    getInputProps: (props?: UseNumberInputGetInputProps) => InputProps;
 };
 export type UseInputNumberStateOptions = NormalizeOptions & {
     defaultValue?: string | number | null;
@@ -29,8 +55,11 @@ export type UseInputNumberStateResult = {
 };
 type NormalizeOptions = Pick<InputNumberProps, "clampOnBlur" | "max" | "min" | "precision" | "step">;
 /**
- * 管理 InputNumber 的字符串输入态与解析后的数字值。
- * 它会自动同步 `clampOnBlur` 产生的提交值，避免业务侧手写 commit 分支。
+ * 提供数字输入的 headless 行为层，统一管理字符串展示值、解析值和提交归一化。
+ */
+export declare function useNumberInput(options?: UseNumberInputOptions): UseNumberInputResult;
+/**
+ * @deprecated 优先使用 `useNumberInput`，通过 `getInputProps()` 组合输入控件。
  */
 export declare function useInputNumberState(options?: UseInputNumberStateOptions): UseInputNumberStateResult;
 /**
@@ -47,5 +76,7 @@ export declare const InputNumber: React.ForwardRefExoticComponent<Omit<InputProp
     precision?: number;
     /** 返回解析后的数值；空值或非法临时值返回 `null`。 */
     onValueChange?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
+    /** 输入值提交时触发，默认在失焦或按下 Enter 时提交。 */
+    onValueCommit?: (value: number | null, meta: InputNumberValueChangeMeta) => void;
 } & React.RefAttributes<HTMLInputElement>>;
 export {};

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

@@ -1,11 +1,183 @@
-/**
- * Uploader 属性。组件通过 `onChange(FileList | null)` 暴露用户选择的文件列表。
- */
-export type UploaderProps = {
+import * as React from "react";
+import { type SxProps } from "@/styling";
+export declare const UPLOADER_LIST_IGNORE: "__LDKJ_UPLOADER_LIST_IGNORE__";
+export type UploaderStatus = "ready" | "uploading" | "success" | "error";
+export type UploaderListType = "text" | "picture" | "picture-card";
+export type UploaderValue = unknown;
+export type UploaderFile = {
+    uid: string;
+    name: string;
+    size?: number;
+    type?: string;
+    status: UploaderStatus;
+    percent?: number;
+    url?: string;
+    thumbUrl?: string;
+    value?: UploaderValue;
+    response?: unknown;
+    error?: Error;
+    originFile?: File;
+};
+export type UploaderRequestResult = {
+    value?: UploaderValue;
+    url?: string;
+    thumbUrl?: string;
+    response?: unknown;
+    name?: string;
+};
+export type UploaderRequestOptions = {
+    file: File;
+    item: UploaderFile;
+    action?: string;
+    data?: Record<string, unknown>;
+    filename: string;
+    headers?: Record<string, string>;
+    method: string;
+    signal: AbortSignal;
+    withCredentials: boolean;
+    onProgress: (percent: number) => void;
+};
+export type UploaderRequest = (options: UploaderRequestOptions) => Promise<UploaderRequestResult | void> | UploaderRequestResult | void;
+export type UploaderValueChangeMeta = {
+    file?: UploaderFile;
+    fileList: UploaderFile[];
+    reason: "add" | "success" | "error" | "remove" | "retry" | "reset" | "progress";
+};
+export type UploaderRenderState = {
+    disabled: boolean;
+    dragging: boolean;
+    fileList: UploaderFile[];
+    uploading: boolean;
+    open: () => void;
+};
+export type UploaderProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
     accept?: string;
+    action?: string | ((file: File) => string | Promise<string>);
+    autoUpload?: boolean;
+    beforeRemove?: (file: UploaderFile, fileList: UploaderFile[]) => boolean | Promise<boolean>;
+    beforeUpload?: (file: File, fileList: File[]) => boolean | File | Blob | typeof UPLOADER_LIST_IGNORE | Promise<boolean | File | Blob | typeof UPLOADER_LIST_IGNORE>;
+    children?: React.ReactNode | ((state: UploaderRenderState) => React.ReactNode);
+    class?: string;
+    customRequest?: UploaderRequest;
+    data?: Record<string, unknown> | ((file: File) => Record<string, unknown> | Promise<Record<string, unknown>>);
+    defaultFileList?: UploaderFile[];
+    defaultValue?: UploaderValue | UploaderValue[];
+    directory?: boolean;
+    disabled?: boolean;
+    drag?: boolean;
+    fileList?: UploaderFile[];
+    getValueFromResult?: (result: UploaderRequestResult | void, file: UploaderFile) => UploaderValue;
+    headers?: Record<string, string>;
+    listType?: UploaderListType;
+    maxCount?: number;
+    maxSize?: number;
+    method?: string;
     multiple?: boolean;
     name?: string;
+    openFileDialogOnClick?: boolean;
+    pastable?: boolean;
+    preview?: boolean;
+    request?: UploaderRequest;
+    renderActions?: (file: UploaderFile, actions: {
+        preview: () => void;
+        download: () => void;
+        remove: () => void;
+        retry: () => void;
+        upload: () => void;
+    }) => React.ReactNode;
+    renderItem?: (file: UploaderFile, originNode: React.ReactNode, actions: {
+        preview: () => void;
+        download: () => void;
+        remove: () => void;
+        retry: () => void;
+        upload: () => void;
+    }) => React.ReactNode;
+    renderTrigger?: (state: UploaderRenderState) => React.ReactNode;
+    showFileList?: boolean;
+    sx?: SxProps;
+    transformFile?: (file: File) => File | Blob | Promise<File | Blob>;
+    value?: UploaderValue | UploaderValue[];
+    withCredentials?: boolean;
+    onChange?: (files: FileList | null) => void;
+    onDownload?: (file: UploaderFile) => void;
+    onDrop?: (event: React.DragEvent<HTMLDivElement>) => void;
+    onError?: (error: Error, file: UploaderFile, fileList: UploaderFile[]) => void;
+    onExceed?: (files: File[], fileList: UploaderFile[]) => void;
+    onFileListChange?: (fileList: UploaderFile[], meta: UploaderValueChangeMeta) => void;
+    onPreview?: (file: UploaderFile) => boolean | void | Promise<boolean | void>;
+    onReject?: (file: File, reason: "accept" | "maxSize") => void;
+    onRemove?: (file: UploaderFile, fileList: UploaderFile[]) => void;
+    onSelect?: (files: File[]) => void;
+    onSuccess?: (file: UploaderFile, fileList: UploaderFile[]) => void;
+    onValueChange?: (value: UploaderValue | UploaderValue[] | null, meta: UploaderValueChangeMeta) => void;
+};
+export type UploaderProviderConfig = Partial<Pick<UploaderProps, "accept" | "action" | "autoUpload" | "beforeRemove" | "beforeUpload" | "customRequest" | "data" | "directory" | "disabled" | "drag" | "getValueFromResult" | "headers" | "listType" | "maxCount" | "maxSize" | "method" | "multiple" | "name" | "openFileDialogOnClick" | "pastable" | "preview" | "request" | "renderActions" | "renderItem" | "renderTrigger" | "showFileList" | "transformFile" | "withCredentials" | "onDownload" | "onError" | "onExceed" | "onPreview" | "onReject" | "onRemove" | "onSelect" | "onSuccess">>;
+export type UploaderProviderProps = UploaderProviderConfig & {
+    children?: React.ReactNode;
+};
+export declare function UploaderProvider(props: UploaderProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useUploaderProvider(): Partial<Pick<UploaderProps, "drag" | "multiple" | "disabled" | "data" | "directory" | "action" | "accept" | "headers" | "name" | "onError" | "onSelect" | "preview" | "method" | "maxSize" | "autoUpload" | "beforeRemove" | "beforeUpload" | "customRequest" | "getValueFromResult" | "listType" | "maxCount" | "openFileDialogOnClick" | "pastable" | "request" | "renderActions" | "renderItem" | "renderTrigger" | "showFileList" | "transformFile" | "withCredentials" | "onDownload" | "onExceed" | "onPreview" | "onReject" | "onRemove" | "onSuccess">> | null;
+export declare const Uploader: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    accept?: string;
+    action?: string | ((file: File) => string | Promise<string>);
+    autoUpload?: boolean;
+    beforeRemove?: (file: UploaderFile, fileList: UploaderFile[]) => boolean | Promise<boolean>;
+    beforeUpload?: (file: File, fileList: File[]) => boolean | File | Blob | typeof UPLOADER_LIST_IGNORE | Promise<boolean | File | Blob | typeof UPLOADER_LIST_IGNORE>;
+    children?: React.ReactNode | ((state: UploaderRenderState) => React.ReactNode);
+    class?: string;
+    customRequest?: UploaderRequest;
+    data?: Record<string, unknown> | ((file: File) => Record<string, unknown> | Promise<Record<string, unknown>>);
+    defaultFileList?: UploaderFile[];
+    defaultValue?: UploaderValue | UploaderValue[];
+    directory?: boolean;
     disabled?: boolean;
+    drag?: boolean;
+    fileList?: UploaderFile[];
+    getValueFromResult?: (result: UploaderRequestResult | void, file: UploaderFile) => UploaderValue;
+    headers?: Record<string, string>;
+    listType?: UploaderListType;
+    maxCount?: number;
+    maxSize?: number;
+    method?: string;
+    multiple?: boolean;
+    name?: string;
+    openFileDialogOnClick?: boolean;
+    pastable?: boolean;
+    preview?: boolean;
+    request?: UploaderRequest;
+    renderActions?: (file: UploaderFile, actions: {
+        preview: () => void;
+        download: () => void;
+        remove: () => void;
+        retry: () => void;
+        upload: () => void;
+    }) => React.ReactNode;
+    renderItem?: (file: UploaderFile, originNode: React.ReactNode, actions: {
+        preview: () => void;
+        download: () => void;
+        remove: () => void;
+        retry: () => void;
+        upload: () => void;
+    }) => React.ReactNode;
+    renderTrigger?: (state: UploaderRenderState) => React.ReactNode;
+    showFileList?: boolean;
+    sx?: SxProps;
+    transformFile?: (file: File) => File | Blob | Promise<File | Blob>;
+    value?: UploaderValue | UploaderValue[];
+    withCredentials?: boolean;
     onChange?: (files: FileList | null) => void;
+    onDownload?: (file: UploaderFile) => void;
+    onDrop?: (event: React.DragEvent<HTMLDivElement>) => void;
+    onError?: (error: Error, file: UploaderFile, fileList: UploaderFile[]) => void;
+    onExceed?: (files: File[], fileList: UploaderFile[]) => void;
+    onFileListChange?: (fileList: UploaderFile[], meta: UploaderValueChangeMeta) => void;
+    onPreview?: (file: UploaderFile) => boolean | void | Promise<boolean | void>;
+    onReject?: (file: File, reason: "accept" | "maxSize") => void;
+    onRemove?: (file: UploaderFile, fileList: UploaderFile[]) => void;
+    onSelect?: (files: File[]) => void;
+    onSuccess?: (file: UploaderFile, fileList: UploaderFile[]) => void;
+    onValueChange?: (value: UploaderValue | UploaderValue[] | null, meta: UploaderValueChangeMeta) => void;
+} & React.RefAttributes<HTMLInputElement>> & {
+    LIST_IGNORE: "__LDKJ_UPLOADER_LIST_IGNORE__";
+    Provider: typeof UploaderProvider;
 };
-export declare function Uploader(props: UploaderProps): import("react/jsx-runtime").JSX.Element;

package/components/interact/progress/Progress.d.ts

@@ -1,13 +1,14 @@
 import * as React from "react";
 export type ProgressType = "line" | "circle";
 export type ProgressStatus = "normal" | "success" | "warning" | "exception";
+export type ProgressSize = "xs" | "sm" | "md" | "lg" | "xl" | number;
 export type ProgressProps = React.HTMLAttributes<HTMLDivElement> & {
     value?: number;
     max?: number;
     showInfo?: boolean;
     type?: ProgressType;
     status?: ProgressStatus;
-    size?: number;
+    size?: ProgressSize;
     strokeWidth?: number;
     strokeColor?: string;
     trailColor?: string;