@ldkj/web-ui 0.18.0 → 0.20.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/interact/alert/Alert.d.ts

@@ -5,5 +5,19 @@ export type AlertProps = React.HTMLAttributes<HTMLDivElement> & {
     variant?: AlertVariant;
     title?: React.ReactNode;
     description?: React.ReactNode;
+    /** Custom leading icon. Pass showIcon to use the built-in tone marker. */
+    icon?: React.ReactNode;
+    /** Whether to render the leading icon area. */
+    showIcon?: boolean;
+    /** Optional trailing action, such as a retry button or detail link. */
+    action?: React.ReactNode;
+    /** Render a close button. */
+    closable?: boolean;
+    /** Controlled visibility. */
+    open?: boolean;
+    /** Fired after the close button is clicked. */
+    onClose?: () => void;
+    /** Controlled visibility callback. */
+    onOpenChange?: (open: boolean) => void;
 };
-export declare function Alert(props: AlertProps): import("react/jsx-runtime").JSX.Element;
+export declare function Alert(props: AlertProps): import("react/jsx-runtime").JSX.Element | null;

package/components/interact/drawer/Drawer.d.ts

@@ -1,11 +1,29 @@
 import * as React from "react";
-export type DrawerProps = {
+export type DrawerPlacement = "left" | "right" | "top" | "bottom";
+export type DrawerProps = React.HTMLAttributes<HTMLDivElement> & {
     open: boolean;
     title?: React.ReactNode;
     width?: number | string;
+    height?: number | string;
+    placement?: DrawerPlacement;
     className?: string;
     class?: string;
+    overlayClassName?: string;
+    bodyClassName?: string;
+    footer?: React.ReactNode;
     children?: React.ReactNode;
     onOpenChange?: (open: boolean) => void;
+    /** Enables slide/fade transitions. Set false when a test or host app needs instant state changes. */
+    animated?: boolean;
+    /** Transition duration in ms. */
+    animationDuration?: number;
+    /** Locks document scrolling while the drawer is open. */
+    lockScroll?: boolean;
+    /** Close when clicking the mask. */
+    maskClosable?: boolean;
+    /** Close when pressing Escape. */
+    closeOnEsc?: boolean;
+    /** Keep content mounted after close. */
+    destroyOnClose?: boolean;
 };
 export declare function Drawer(props: DrawerProps): import("react/jsx-runtime").JSX.Element | null;

package/components/interact/loading/Loading.d.ts

@@ -1,3 +1,19 @@
-export declare function Loading({ text }: {
-    text?: string;
-}): import("react/jsx-runtime").JSX.Element;
+import * as React from "react";
+import { type SpinProps } from "@/components/interact/spin";
+export type LoadingVariant = "inline" | "block" | "overlay" | "fullscreen";
+export type LoadingProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** Loading text. Set to null to hide text while keeping the spinner. */
+    text?: React.ReactNode;
+    /** Layout mode for inline hints, blocks, overlays, or full-screen masks. */
+    variant?: LoadingVariant;
+    /** Spinner size. Numbers are treated as px. */
+    size?: SpinProps["size"];
+    /** Spinner tone. */
+    tone?: SpinProps["tone"];
+    /** Set to false to hide loading state without unmounting wrapped children. */
+    spinning?: boolean;
+    /** Delay in ms before showing the loading indicator. */
+    delay?: number;
+    class?: string;
+};
+export declare function Loading(props: LoadingProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,8 +1,18 @@
 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?: ProgressSize;
+    strokeWidth?: number;
+    strokeColor?: string;
+    trailColor?: string;
+    format?: (percent: number, value: number, max: number) => React.ReactNode;
     class?: string;
 };
 export declare function Progress(props: ProgressProps): import("react/jsx-runtime").JSX.Element;

package/components/interact/spin/Spin.d.ts

@@ -1,6 +1,16 @@
 import * as React from "react";
+export type SpinTone = "primary" | "muted" | "success" | "warning" | "danger";
 export type SpinProps = React.HTMLAttributes<HTMLSpanElement> & {
-    size?: number;
+    /** Spinner size. Numbers are treated as px. */
+    size?: number | string;
+    /** Ring stroke width. Numbers are treated as px. */
+    strokeWidth?: number | string;
+    /** Color tone for the active ring segment. */
+    tone?: SpinTone;
+    /** Accessible label announced by screen readers. */
+    label?: string;
+    /** Set to false to suppress the spinner without branching in user code. */
+    spinning?: boolean;
     class?: string;
 };
-export declare function Spin(props: SpinProps): import("react/jsx-runtime").JSX.Element;
+export declare function Spin(props: SpinProps): import("react/jsx-runtime").JSX.Element | null;