@para-ui/core 5.0.0-beta.9 → 5.0.0

package/es/InputNumber/component.json

@@ -0,0 +1,162 @@
+{
+    "name": "InputNumber",
+    "category": "Data Entry",
+    "description": "数字输入框，提供加减按钮",
+    "semantic": {
+        "intent": [
+            "数字录入",
+            "数量调整"
+        ],
+        "useCases": [
+            "商品数量",
+            "金额输入",
+            "年龄录入"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准数字显示"
+        }
+    },
+    "states": [
+        "focus",
+        "blur",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "number | null | undefined",
+            "description": "受控值;clearable=true 时类型为 number | null,默认为 number | undefined"
+        },
+        "defaultValue": {
+            "type": "number | null | undefined",
+            "description": "非受控默认值;类型规则同 value"
+        },
+        "onChange": {
+            "type": "(value: number | null) => void",
+            "description": "值变化回调;clearable=true 时入参 number | null;默认时收敛为 number"
+        },
+        "clearable": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否允许清空;true 时 onChange 入参 number | null;false(默认)时清空被拦截、失焦回填上一值。组件泛型 InputNumberProps<C extends boolean> 由该 prop 驱动"
+        },
+        "max": {
+            "type": "number",
+            "description": "最大值;超出后加按钮禁用,失焦回收"
+        },
+        "min": {
+            "type": "number",
+            "description": "最小值;低于后减按钮禁用,失焦回收"
+        },
+        "step": {
+            "type": "number",
+            "default": 1,
+            "description": "步进值"
+        },
+        "btnMode": {
+            "type": "'lr' | 'tb' | 'none'",
+            "values": ["lr", "tb", "none"],
+            "default": "tb",
+            "description": "按钮模式;lr=左右加减、tb=右侧上下加减、none=无按钮"
+        },
+        "formatter": {
+            "type": "(value: number | string, info: { userTyping: boolean; input: string }) => string",
+            "description": "数字 → 展示字符串;必须与 parser 配对"
+        },
+        "parser": {
+            "type": "(displayValue: string) => number",
+            "description": "展示字符串 → 数字;与 formatter 配对,返回值作为 onChange 入参"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "尺寸"
+        }
+    },
+    "do": [
+        "限制 min 和 max 以符合业务逻辑",
+        "需要小数精度时通过 formatter / parser 组合实现",
+        "受控模式必须同时传 value 和 onChange",
+        "需要清空场景显式传 clearable=true,并用 number | null 类型的 state"
+    ],
+    "dont": [
+        "使用 Text Input 录入需要计算的数字",
+        "步进值 (step) 设置过大导致无法精确调节",
+        "clearable=false(默认)时把 state 初始化为 null —— 会触发类型错误",
+        "传 formatter 不传 parser(或反之)—— 二者必须配对"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "clearable=false: (value: number) => void | clearable=true: (value: number | null) => void",
+            "asyncSupported": false,
+            "examples": [
+                "clearable=false（默认）: onChange={(val) => setState(val)} — val 是 number，清空被拦截，失焦时回填上一次有效值",
+                "clearable=true: onChange={(val) => setState(val)} — val 是 number | null，用户清空后 val=null 传出",
+                "加减按钮点击也触发 onChange，通过内部精度计算避免浮点误差（12位精度）"
+            ],
+            "commonMistakes": [
+                "clearable=false 时把 state 类型声明为 number | null——ts 会报错 null 不符合 onChange 签名的 number 入参",
+                "期望 onChange 在 mount 时触发初始 defaultValue——组件不触发初始 onChange，只在用户交互时触发",
+                "使用受控 value 但不传 onChange——value 更新不回流到组件，显示值和 state 不同步"
+            ]
+        },
+        "onBlur": {
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onBlur={(e) => validate(e.target.value)} — 失焦时校验",
+                "clearable=false 时 onBlur 之后组件内部回填上一次有效值（如用户清空输入框）——在 onBlur 里读 e.target.value 可能是回填前的空串",
+                "onBlur={(e) => setError(Number(e.target.value) < min ? '低于最小值' : '')} — 配合 min/max 做自定义错误提示"
+            ],
+            "commonMistakes": [
+                "在 onBlur 里读 e.target.value 作为最终值——clearable=false 失焦会触发回填，此时 value 可能已被重写，应用 onChange 最新值或 ref 维护",
+                "期望 onBlur 和 onChange 同时触发——清空后失焦只触发 onBlur（onChange 被拦截了），需在 onBlur 里独立处理",
+                "期望 onBlur 的 e.target 是最终显示值——回填逻辑发生在 onBlur handler 内部，timing 依赖 dom.value 写入"
+            ]
+        },
+        "onEnter": {
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onEnter={(e) => submitForm()} — 按回车提交表单",
+                "onEnter={(e) => { e.preventDefault(); nextFieldRef.current?.focus(); }} — 回车跳到下一字段",
+                "onEnter 和 onChange 独立触发——回车不会触发失焦，不会触发回填逻辑"
+            ],
+            "commonMistakes": [
+                "在 onEnter 里读 e.target.value 期望是最终数字——回车时 rc-input-number 可能还没 commit 值，建议用受控 value 而非 target.value",
+                "期望 onEnter 代替 onBlur 触发校验——两者行为不同，回车不失焦，需独立监听",
+                "传 onKeyDown 期望捕获回车——底层用的是 onPressEnter（rc-input-number），应用 onEnter prop"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "InputNumber 是泛型组件 InputNumber<C extends boolean>，clearable 决定 onChange/value 类型，不传 clearable 时默认 false（number 类型）",
+            "wrong": "const [val, setVal] = useState<number | null>(null); <InputNumber value={val} onChange={setVal} /> // val 和 setVal 含 null，但 clearable 默认 false 不允许 null，TS 报错",
+            "right": "const [val, setVal] = useState<number | null>(null); <InputNumber<true> clearable value={val} onChange={setVal} /> // 显式泛型参数或 clearable=true 驱动类型"
+        },
+        {
+            "issue": "formatter 和 parser 必须成对使用，只传一个会导致显示和实际值不同步",
+            "wrong": "formatter={(val) => `${val}%`} // 没有 parser，用户看到 '50%' 但内部 onChange 收到 '50%' 字符串而非数字",
+            "right": "formatter={(val) => `${val}%`} parser={(val) => parseFloat(val.replace('%', '')) as any} // 成对，parser 把展示串转回数字"
+        },
+        {
+            "issue": "addonBefore/addonAfter 是 ReactNode，传字符串可能 TS 允许但布局与 ReactNode 写法不一致",
+            "wrong": "<InputNumber addonBefore='¥' /> // 字符串是合法 ReactNode，但建议显式包 span 控制样式",
+            "right": "<InputNumber addonBefore={<span>¥</span>} /> // 或直接字符串；字符串也 OK，仅风格建议"
+        }
+    ],
+    "mapping": {
+        "realComponent": "InputNumber",
+        "adapter": null
+    }
+}

package/es/InputNumber/index.d.ts

@@ -1,8 +1,8 @@
-import { default as React, FunctionComponent, ReactNode } from 'react';
+import { default as React, ReactNode } from 'react';
 import { LabelTooltipProps } from '../Label';
 import { HelperTextDetailProps } from '../HelperText';
 import { TooltipProps } from '../Tooltip';
-export interface InputNumberProps extends HelperTextDetailProps {
+export interface InputNumberProps<Clearable extends boolean = false> extends HelperTextDetailProps {
     /** 样式class */
     className?: string;
     /** style */
@@ -47,6 +47,12 @@ export interface InputNumberProps extends HelperTextDetailProps {
     autoFocus?: boolean;
     /** 只读 */
     readOnly?: boolean;
+    /**
+     * 是否允许清空（清空后 onChange 回传 null）；
+     * 默认 false 时 onChange 入参收敛为 number，清空操作会被组件内部拦截并在失焦时回填上一次有效值；
+     * 显式 true 时 onChange 入参为 number | null，沿用历史行为
+     */
+    clearable?: Clearable;
     /** 指定输入框展示值的格式 */
     formatter?: (value: number | string, info: {
         userTyping: boolean;
@@ -55,15 +61,15 @@ export interface InputNumberProps extends HelperTextDetailProps {
     /** 指定从 formatter 里转换回数字的方式，和 formatter 搭配使用 */
     parser?: (displayValue: string) => number;
     /** 默认值 不受控 */
-    defaultValue?: number | null;
+    defaultValue?: Clearable extends true ? number | null : number | undefined;
     /** 默认值 受控 */
-    value?: number | null;
+    value?: Clearable extends true ? number | null : number | undefined;
     /** 前缀 */
     addonBefore?: ReactNode;
     /** 后缀 */
     addonAfter?: ReactNode;
-    /** 改变事件 number / null */
-    onChange?: (value: number | null) => void;
+    /** 改变事件 number（默认）或 number | null（clearable=true） */
+    onChange?: (value: Clearable extends true ? number | null : number) => void;
     /** 回车事件 */
     onEnter?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
     /** 失去焦点 */
@@ -73,5 +79,5 @@ export interface InputNumberProps extends HelperTextDetailProps {
     /** name */
     name?: string;
 }
-export declare const InputNumber: FunctionComponent<InputNumberProps>;
+export declare function InputNumber<C extends boolean = false>(props: InputNumberProps<C>): JSX.Element;
 export default InputNumber;

package/es/InputNumber/index.js

@@ -1,216 +1,224 @@
 import { j as n } from "../_virtual/jsx-runtime.js";
-import { useState as z, useRef as fe, useEffect as U, useMemo as be } from "react";
-import pe from "rc-input-number";
-import { Up as he } from "../node_modules/@para-ui/icons/Up/index.js";
-import { Down as xe } from "../node_modules/@para-ui/icons/Down/index.js";
-import ve from "../Label/index.js";
-import je from "../HelperText/index.js";
-import { Tooltip as g } from "../Tooltip/index.js";
-import { $prefixCls as o, $rcPrefixCls as Ce } from "../GlobalContext/constant.js";
+import { useState as G, useRef as J, useEffect as K, useMemo as he } from "react";
+import xe from "rc-input-number";
+import { Up as ve } from "../node_modules/@para-ui/icons/Up/index.js";
+import { Down as je } from "../node_modules/@para-ui/icons/Down/index.js";
+import Ce from "../Label/index.js";
+import Ne from "../HelperText/index.js";
+import { Tooltip as B } from "../Tooltip/index.js";
+import { $prefixCls as o, $rcPrefixCls as $e } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
-const Pe = (s) => {
+function Ee(l) {
   const {
-    className: B,
-    style: G,
-    step: x = 1,
-    min: l,
-    max: i,
-    size: F = "large",
-    placeholder: R = "",
-    label: c,
-    labelTooltip: m,
-    labelMode: v = "outside",
+    className: F,
+    style: Q,
+    step: j = 1,
+    min: i,
+    max: s,
+    size: R = "large",
+    placeholder: k = "",
+    label: b,
+    labelTooltip: p,
+    labelMode: C = "outside",
     labelSign: a,
-    btnMode: j = "tb",
-    disabled: u = !1,
-    disabledTooltip: V,
-    disabledTooltipAdd: J,
-    disabledTooltipReduce: K,
-    readOnly: f = !1,
-    disabledAdd: k = !1,
-    disabledReduce: M = !1,
-    required: b = !1,
-    error: P = !1,
-    hideErrorDom: Q,
-    helperText: W = "",
-    keyboard: X = !0,
-    autoFocus: Y = !1,
-    formatter: Z,
-    parser: _,
-    value: p,
-    onChange: w,
-    onEnter: ee,
-    onBlur: E,
-    onFocus: A,
-    addonBefore: C,
-    addonAfter: N,
-    ...ne
-  } = s, [D, I] = z(!1), [$, T] = z(), L = fe(null);
-  U(() => {
-    s.defaultValue !== void 0 && T(s.defaultValue);
-  }, []), U(() => {
-    p !== void 0 && T(p);
-  }, [p]);
-  const S = () => s.value === void 0 ? $ : p, re = () => {
-    if (u || f) return;
-    L?.current?.focus();
-  }, te = (e) => {
-    I(!0), A && A(e);
-  }, oe = (e) => {
-    I(!1), E && E(e);
-  }, q = (e, ...t) => {
-    const r = Math.pow(10, 12), d = t.map((me) => Math.round(me * r)).reduce(e) / r;
-    return parseFloat(d.toFixed(12));
-  }, H = (e) => () => {
-    if (e === "add" && (u || k || f) || e === "reduce" && (u || M || f)) return;
-    const t = $ === void 0 ? 0 : Number($);
-    let r;
+    btnMode: N = "tb",
+    disabled: d = !1,
+    disabledTooltip: M,
+    disabledTooltipAdd: W,
+    disabledTooltipReduce: X,
+    readOnly: h = !1,
+    disabledAdd: P = !1,
+    disabledReduce: w = !1,
+    required: x = !1,
+    error: E = !1,
+    hideErrorDom: Y,
+    helperText: Z = "",
+    keyboard: _ = !0,
+    autoFocus: ee = !1,
+    formatter: ne,
+    parser: te,
+    value: u,
+    clearable: A = !1,
+    onChange: D,
+    onEnter: re,
+    onBlur: S,
+    onFocus: I,
+    addonBefore: $,
+    addonAfter: V,
+    ...le
+  } = l, [L, q] = G(!1), [g, c] = G(), T = J(null), f = J(void 0);
+  K(() => {
+    l.defaultValue !== void 0 && l.defaultValue !== null ? (c(l.defaultValue), f.current = l.defaultValue) : l.defaultValue !== void 0 && c(l.defaultValue);
+  }, []), K(() => {
+    u !== void 0 && (c(u), u !== null && (f.current = u));
+  }, [u]);
+  const H = () => l.value === void 0 ? g : u, oe = () => {
+    if (d || h) return;
+    T?.current?.focus();
+  }, ie = (e) => {
+    q(!0), I && I(e);
+  }, se = (e) => {
+    if (q(!1), !A) {
+      const r = T.current;
+      if (r && r.value === "" && f.current !== void 0) {
+        const t = f.current;
+        l.value === void 0 ? c(t) : r.value = String(t);
+      }
+    }
+    S && S(e);
+  }, O = (e, ...r) => {
+    const t = Math.pow(10, 12), m = r.map((pe) => Math.round(pe * t)).reduce(e) / t;
+    return parseFloat(m.toFixed(12));
+  }, y = (e) => () => {
+    if (e === "add" && (d || P || h) || e === "reduce" && (d || w || h)) return;
+    const r = g === void 0 ? 0 : Number(g);
+    let t;
     if (e === "add") {
-      if (i !== void 0 && t >= i) return;
-      r = q((h, d) => h + d, t, x), i !== void 0 && r > i && (r = i);
+      if (s !== void 0 && r >= s) return;
+      t = O((v, m) => v + m, r, j), s !== void 0 && t > s && (t = s);
     } else {
-      if (l !== void 0 && t <= l) return;
-      r = q((h, d) => h - d, t, x), l !== void 0 && r < l && (r = l);
+      if (i !== void 0 && r <= i) return;
+      t = O((v, m) => v - m, r, j), i !== void 0 && t < i && (t = i);
     }
-    O(r);
-  }, O = (e) => {
-    s.value === void 0 && T(e), w && w(e);
-  }, se = be(() => {
-    if (v === "outside" && !!(b || a || c)) {
-      const t = () => {
-        let r = "input-number-label";
-        return m && m.className && (r += ` ${m.className}`), r;
+    z(t);
+  }, z = (e) => {
+    !A && e === null || (e != null && (f.current = e), l.value === void 0 && c(e), D && D(e));
+  }, ue = he(() => {
+    if (C === "outside" && !!(x || a || b)) {
+      const r = () => {
+        let t = "input-number-label";
+        return p && p.className && (t += ` ${p.className}`), t;
       };
       return /* @__PURE__ */ n.jsx(
-        ve,
+        Ce,
         {
-          label: c,
-          required: b,
+          label: b,
+          required: x,
           labelSign: a,
-          ...m,
-          className: t()
+          ...p,
+          className: r()
         }
       );
     }
-  }, [v, c, a, b]), le = () => {
-    const e = S();
-    if (D || e != null) return;
-    const t = () => v === "outside" ? R : /* @__PURE__ */ n.jsxs(n.Fragment, { children: [
-      c || R,
-      b && /* @__PURE__ */ n.jsx("span", { className: "input-number-required", children: "*" }),
+  }, [C, b, a, x]), ae = () => {
+    const e = H();
+    if (L || e != null) return;
+    const r = () => C === "outside" ? k : /* @__PURE__ */ n.jsxs(n.Fragment, { children: [
+      b || k,
+      x && /* @__PURE__ */ n.jsx("span", { className: "input-number-required", children: "*" }),
       a && /* @__PURE__ */ n.jsx("span", { children: a })
     ] });
     return /* @__PURE__ */ n.jsx(
       "span",
       {
         className: "input-number-label-placeholder",
-        onClick: re,
-        children: t()
+        onClick: oe,
+        children: r()
       }
     );
-  }, ie = () => {
-    if (N)
-      return /* @__PURE__ */ n.jsx("div", { className: "input-number-content-after", children: N });
-  }, ae = () => {
-    if (C)
-      return /* @__PURE__ */ n.jsx("div", { className: "input-number-content-before", children: C });
-  }, ue = () => j === "none" ? null : /* @__PURE__ */ n.jsxs("div", { className: "input-number-btn", children: [
+  }, de = () => {
+    if (V)
+      return /* @__PURE__ */ n.jsx("div", { className: "input-number-content-after", children: V });
+  }, ce = () => {
+    if ($)
+      return /* @__PURE__ */ n.jsx("div", { className: "input-number-content-before", children: $ });
+  }, fe = () => N === "none" ? null : /* @__PURE__ */ n.jsxs("div", { className: "input-number-btn", children: [
     /* @__PURE__ */ n.jsx(
-      g,
+      B,
       {
         disabled: !0,
         placement: "top-end",
-        ...J,
+        ...W,
         children: /* @__PURE__ */ n.jsx(
           "span",
           {
             className: "tb-btn-top",
-            onClick: H("add"),
-            children: /* @__PURE__ */ n.jsx(he, {})
+            onClick: y("add"),
+            children: /* @__PURE__ */ n.jsx(ve, {})
           }
         )
       }
     ),
     /* @__PURE__ */ n.jsx(
-      g,
+      B,
       {
         disabled: !0,
         placement: "bottom-end",
-        ...K,
+        ...X,
         children: /* @__PURE__ */ n.jsx(
           "span",
           {
             className: "tb-btn-bottom",
-            onClick: H("reduce"),
-            children: /* @__PURE__ */ n.jsx(xe, {})
+            onClick: y("reduce"),
+            children: /* @__PURE__ */ n.jsx(je, {})
           }
         )
       }
     )
-  ] }), y = () => /* @__PURE__ */ n.jsxs("div", { className: "input-number-content", children: [
-    ae(),
+  ] }), U = () => /* @__PURE__ */ n.jsxs("div", { className: "input-number-content", children: [
+    ce(),
     /* @__PURE__ */ n.jsxs("div", { className: "input-number-content-within", children: [
       /* @__PURE__ */ n.jsx(
-        pe,
+        xe,
         {
-          ref: L,
-          step: x,
-          min: l,
-          max: i,
-          keyboard: X,
-          disabled: u,
-          value: S() ?? void 0,
-          defaultValue: s.defaultValue === null ? void 0 : s.defaultValue,
-          autoFocus: Y,
-          readOnly: f,
-          formatter: Z,
-          parser: _,
-          prefixCls: Ce,
-          onChange: O,
-          onFocus: te,
-          onBlur: oe,
-          onPressEnter: ee,
-          ...ne
+          ref: T,
+          step: j,
+          min: i,
+          max: s,
+          keyboard: _,
+          disabled: d,
+          value: H() ?? void 0,
+          defaultValue: l.defaultValue === null ? void 0 : l.defaultValue,
+          autoFocus: ee,
+          readOnly: h,
+          formatter: ne,
+          parser: te,
+          prefixCls: $e,
+          onChange: z,
+          onFocus: ie,
+          onBlur: se,
+          onPressEnter: re,
+          ...le
         }
       ),
-      le()
+      ae()
     ] }),
-    ie(),
-    ue()
-  ] }), de = () => V ? /* @__PURE__ */ n.jsx(
-    g,
+    de(),
+    fe()
+  ] }), me = () => M ? /* @__PURE__ */ n.jsx(
+    B,
     {
       disabled: !0,
-      ...V,
-      children: y()
+      ...M,
+      children: U()
     }
-  ) : y(), ce = () => {
+  ) : U(), be = () => {
     let e = `${o}-input-number `;
-    return B && (e += ` ${B}`), F && (e += ` ${o}-input-number-${F}`), j && (e += ` ${o}-input-number-${j === "none" ? "none" : "tb"}`), D && (e += ` ${o}-input-number-focus`), u && (e += ` ${o}-input-number-disabled`), k && (e += ` ${o}-input-number-disabled-add`), M && (e += ` ${o}-input-number-disabled-reduce`), P && (e += ` ${o}-input-number-error`), N && (e += ` ${o}-input-number-after`), C && (e += ` ${o}-input-number-before`), e;
+    return F && (e += ` ${F}`), R && (e += ` ${o}-input-number-${R}`), N && (e += ` ${o}-input-number-${N === "none" ? "none" : "tb"}`), L && (e += ` ${o}-input-number-focus`), d && (e += ` ${o}-input-number-disabled`), P && (e += ` ${o}-input-number-disabled-add`), w && (e += ` ${o}-input-number-disabled-reduce`), E && (e += ` ${o}-input-number-error`), V && (e += ` ${o}-input-number-after`), $ && (e += ` ${o}-input-number-before`), e;
   };
   return /* @__PURE__ */ n.jsxs(
     "div",
     {
-      className: ce(),
-      style: G,
+      className: be(),
+      style: Q,
       children: [
-        se,
-        de(),
+        ue,
+        me(),
         /* @__PURE__ */ n.jsx(
-          je,
+          Ne,
           {
             className: "input-number-error-text",
-            error: P,
-            helperText: W,
-            hideErrorDom: Q
+            error: E,
+            helperText: Z,
+            hideErrorDom: Y
           }
         )
       ]
     }
   );
-};
+}
 export {
-  Pe as InputNumber,
-  Pe as default
+  Ee as InputNumber,
+  Ee as default
 };
 //# sourceMappingURL=index.js.map