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

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 "../para-ui-core/node_modules/@para-ui/icons/Up/index.js";
+import { Down as je } from "../para-ui-core/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

package/es/Label/component.json

@@ -0,0 +1,126 @@
+{
+    "name": "Label",
+    "category": "Data Display",
+    "description": "表单标签，显示字段标题，支持必填红星、帮助提示（icon 或下划线两种样式）、自定义标题后缀",
+    "semantic": {
+        "intent": [
+            "字段标题",
+            "表单标签"
+        ],
+        "useCases": [
+            "表单字段",
+            "配置项",
+            "详情展示"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "tooltipType='icon' — label 后渲染问号图标，hover 显示 tooltip"
+        },
+        "line": {
+            "meaning": "tooltipType='line' — label 文字加下划线，hover 整个 label 显示 tooltip"
+        }
+    },
+    "states": [
+        "default",
+        "required"
+    ],
+    "idealProps": {
+        "label": {
+            "type": "ReactNode",
+            "description": "标题文案；可传字符串或 ReactNode；不传时只渲染必填红星/tooltip 区域"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填；true 时在 label 后渲染 `<span class='label-required'>*</span>` 红星"
+        },
+        "tooltip": {
+            "type": "ReactNode",
+            "description": "帮助提示内容；tooltipType='icon' 时渲染 Help 图标；tooltipType='line' 时整个 label 加下划线触发。**不传时不渲染 tooltip 区域**"
+        },
+        "tooltipType": {
+            "type": "enum",
+            "values": [
+                "icon",
+                "line"
+            ],
+            "default": "icon",
+            "description": "提示类型：icon=问号图标（默认），line=label 文字下划线"
+        },
+        "tooltipIcon": {
+            "type": "ReactNode",
+            "description": "自定义 tooltip 触发图标（tooltipType='icon' 时生效）；不传时使用 Help 组件默认问号图标"
+        },
+        "labelSign": {
+            "type": "ReactNode",
+            "description": "标题旁的次级标记，渲染在必填红星之后（如 '(可选)' '(Beta)' 等短文本）"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", "right-end"],
+            "default": "top-start",
+            "description": "tooltip 弹出方向（透传给底层 Help 组件）"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": true,
+            "description": "tooltip 箭头"
+        },
+        "onClick": {
+            "type": "(e: React.MouseEvent<HTMLLabelElement>) => void",
+            "description": "点击 label 元素时触发"
+        },
+        "className": {
+            "type": "string",
+            "description": "label 容器类名"
+        }
+    },
+    "do": [
+        "为每个表单字段提供清晰的 Label，文案简洁（< 10 字）",
+        "必填字段传 required={true} 显示红星",
+        "需要字段说明时用 tooltip prop + 选择合适的 tooltipType（icon 更常用，line 适合较长 label）"
+    ],
+    "dont": [
+        "Label 过长（> 15 字）——会撑宽表单布局，截断或换行",
+        "忽略 Label 的可访问性——for/htmlFor 关联逻辑由外层 FormItem 管理，Label 本身不自动关联"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onClick={(e) => console.log('clicked', e.currentTarget.textContent)} — 点击 label 时触发",
+                "通常不需要监听 label click——表单字段聚焦由 <label for> 或 FormItem 关联处理",
+                "自定义行为：onClick={(e) => { e.preventDefault(); openHelperModal(); }} — 阻止默认并打开详细说明"
+            ],
+            "commonMistakes": [
+                "期望 onClick 触发对应输入框聚焦——Label 组件的 <label> 没有 htmlFor 属性，聚焦关联由外层 FormItem 控制",
+                "传 onClick 期望阻止 tooltip 弹出——onClick 和 tooltip（hover）是独立行为，onClick 不影响 Tooltip 的 hover 逻辑",
+                "期望 label text 点击和 tooltipIcon 点击都触发同一 onClick——tooltipIcon 的点击事件由 Help 组件内部处理（hover），不冒泡到 Label onClick"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "tooltip 类型是 ReactNode，但底层 Help 组件要求 NonNullable<ReactNode>，直接传可选字段可能报 TS2322",
+            "wrong": "const tip: ReactNode | undefined = getTooltip(); <Label tooltip={tip} /> // 若 tip 推断含 undefined 分支，Help 内部 title 报 TS2322",
+            "right": "const tip = getTooltip(); <Label tooltip={tip ?? ''} /> // 用空字符串兜底（空字符串不显示 Tooltip 弹层）"
+        },
+        {
+            "issue": "LabelProps 通过 extends LabelTooltipProps 继承了 [name: string]: any 索引签名，导致所有额外 prop 被 TS 接受但无效",
+            "wrong": "<Label label='姓名' onFocus={handler} /> // TS 不报错（索引签名兜底），但 onFocus 不会触发任何行为",
+            "right": "<Label label='姓名' onClick={handler} /> // 只用 LabelProps 实际声明的 onClick prop"
+        },
+        {
+            "issue": "labelSign 是 ReactNode，不会被 required 的 * 替换——两者独立渲染",
+            "wrong": "// 期望 required=true 时 labelSign 文本替换红星\n<Label required label='邮箱' labelSign='（必填）' /> // 实际渲染：邮箱 * （必填）——两者都显示",
+            "right": "// 只传 required 控制红星；labelSign 是额外后缀，不替换\n<Label required label='邮箱' /> // 只显示 邮箱 *"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Label",
+        "adapter": null
+    }
+}

package/es/Label/index.d.ts

@@ -16,7 +16,7 @@ export interface LabelTooltipProps {
     placement?: 'bottom-end' | 'bottom-start' | 'bottom' | 'left-end' | 'left-start' | 'left' | 'right-end' | 'right-start' | 'right' | 'top-end' | 'top-start' | 'top';
     /** 提示箭头 */
     arrow?: boolean;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface LabelProps extends LabelTooltipProps {
     /** 是否必填 */
@@ -26,7 +26,7 @@ export interface LabelProps extends LabelTooltipProps {
     /** 标题提示,可用来自定义 */
     labelSign?: ReactNode;
     onClick?: (e: React.MouseEvent<HTMLLabelElement>) => void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const Label: FunctionComponent<LabelProps>;
 export default Label;