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

package/es/RangeInput/index.js

@@ -1,143 +1,160 @@
-import { j as r } from "../_virtual/jsx-runtime.js";
-import { useState as h, useRef as U, useEffect as V } from "react";
-import { $prefixCls as l } from "../GlobalContext/constant.js";
-import X from "../Label/index.js";
-import { InputNumber as A } from "../InputNumber/index.js";
-import M from "../HelperText/index.js";
-import Y from "clsx";
-import { Tooltip as Z } from "../Tooltip/index.js";
-import { DeepClone as _ } from "@paraview/lib";
+import { j as n } from "../_virtual/jsx-runtime.js";
+import { useState as b, useRef as q, useEffect as v } from "react";
+import { $prefixCls as u } from "../GlobalContext/constant.js";
+import ee from "../Label/index.js";
+import { InputNumber as H } from "../InputNumber/index.js";
+import P from "../HelperText/index.js";
+import re from "clsx";
+import { Tooltip as ne } from "../Tooltip/index.js";
+import { DeepClone as te } from "@snack-kit/lib";
 import './index.css';/* empty css           */
-const de = (s) => {
+function ge(o) {
   const {
-    className: W,
-    style: H,
-    label: I,
-    labelTooltip: P,
-    size: S = "large",
-    required: q = !1,
-    disabled: t = !1,
-    disabledTooltip: a,
-    warningMessage: g,
-    warnTime: z = 2e3,
-    defaultValue: ee,
-    value: d,
-    error: x = !1,
-    hideErrorDom: b,
-    helperText: L = "",
-    separator: k = "~",
-    unit: C,
+    className: S,
+    style: z,
+    label: L,
+    labelTooltip: k,
+    size: G = "large",
+    required: J = !1,
+    disabled: l = !1,
+    disabledTooltip: s,
+    warningMessage: w,
+    warnTime: K = 2e3,
+    defaultValue: ae,
+    value: h,
+    error: C = !1,
+    hideErrorDom: R,
+    helperText: O = "",
+    separator: Q = "~",
+    unit: j,
     placeholder: i,
-    onFocus: j,
-    onBlur: v,
-    onEnter: T,
-    onChange: E,
-    otherProps: u
-  } = s, [n, m] = h([null, null]), [G, N] = h(!1), [J, $] = h(!1), D = U({
-    timer: null
-  });
-  V(() => {
-    s.defaultValue !== void 0 && m(s.defaultValue);
-  }, []), V(() => {
-    d !== void 0 && m(d);
-  }, [d]);
-  const w = (e) => i && i instanceof Array ? i[e] : i, c = (e) => t && t instanceof Array ? t[e] : t, F = (e) => (o) => {
-    N(!0), j && j(o, e);
-  }, y = (e) => (o) => {
-    N(!1), v && v(o, e), n[0] !== null && n[1] !== null && n[0] > n[1] && (f(e)(null), g && K());
-  }, K = () => {
-    clearTimeout(D.current.timer), $(!0), D.current.timer = setTimeout(() => {
-      $(!1);
-    }, z);
-  }, B = (e) => (o) => {
-    T && T(o, e);
-  }, f = (e) => (o) => {
-    const p = n ? _(n) : [];
-    p[e] = o, s.value === void 0 && m(p), E && E(p, e);
-  }, R = () => /* @__PURE__ */ r.jsxs("div", { className: "range-input-content", children: [
-    /* @__PURE__ */ r.jsx(
-      A,
+    clearable: oe = !1,
+    onFocus: T,
+    onBlur: E,
+    onEnter: I,
+    onChange: c,
+    otherProps: d
+  } = o, [f, m] = b([null, null]), [U, F] = b(!1), [X, N] = b(!1), e = q({
+    timer: null,
+    swapRafId: null
+  }), $ = q(null);
+  v(() => {
+    o.defaultValue !== void 0 && m(o.defaultValue);
+  }, []), v(() => {
+    h !== void 0 && m(h);
+  }, [h]), v(() => () => {
+    e.current.swapRafId !== null && (cancelAnimationFrame(e.current.swapRafId), e.current.swapRafId = null), e.current.timer !== null && (clearTimeout(e.current.timer), e.current.timer = null);
+  }, []);
+  const A = (r) => i && i instanceof Array ? i[r] : i, p = (r) => l && l instanceof Array ? l[r] : l, D = (r) => (t) => {
+    F(!0), T && T(t, r);
+  }, y = (r) => (t) => {
+    F(!1), E && E(t, r), e.current.swapRafId !== null && cancelAnimationFrame(e.current.swapRafId), e.current.swapRafId = requestAnimationFrame(() => {
+      e.current.swapRafId = null;
+      const a = $.current;
+      if (a && a.contains(document.activeElement))
+        return;
+      const [g, x] = f;
+      if (g !== null && x !== null && g > x) {
+        const W = [x, g];
+        o.value === void 0 && m(W), c && c(W, -1), w && Y();
+      }
+    });
+  }, Y = () => {
+    clearTimeout(e.current.timer ?? void 0), N(!0), e.current.timer = setTimeout(() => {
+      N(!1);
+    }, K);
+  }, B = (r) => (t) => {
+    I && I(t, r);
+  }, V = (r) => (t) => {
+    const a = te(f);
+    a[r] = t, o.value === void 0 && m(a), c && c(a, r);
+  }, M = () => /* @__PURE__ */ n.jsxs("div", { className: "range-input-content", children: [
+    /* @__PURE__ */ n.jsx(
+      H,
       {
-        ...u && u[0],
+        ...d && d[0],
+        clearable: !0,
         btnMode: "none",
         hideErrorDom: !0,
-        placeholder: w(0),
-        disabled: c(0),
-        disabledTooltip: a?.[0],
-        value: n[0],
-        onFocus: F(0),
+        placeholder: A(0),
+        disabled: p(0),
+        disabledTooltip: s?.[0],
+        value: f[0],
+        onFocus: D(0),
         onBlur: y(0),
         onEnter: B(0),
-        onChange: f(0)
+        onChange: V(0)
       }
     ),
-    /* @__PURE__ */ r.jsx("span", { className: "separator", children: k }),
-    /* @__PURE__ */ r.jsx(
-      A,
+    /* @__PURE__ */ n.jsx("span", { className: "separator", children: Q }),
+    /* @__PURE__ */ n.jsx(
+      H,
       {
-        ...u && u[1],
+        ...d && d[1],
+        clearable: !0,
         btnMode: "none",
         hideErrorDom: !0,
-        placeholder: w(1),
-        disabled: c(1),
-        disabledTooltip: a?.[1],
-        value: n[1],
-        onFocus: F(1),
+        placeholder: A(1),
+        disabled: p(1),
+        disabledTooltip: s?.[1],
+        value: f[1],
+        onFocus: D(1),
         onBlur: y(1),
         onEnter: B(1),
-        onChange: f(1)
+        onChange: V(1)
       }
     ),
-    C && /* @__PURE__ */ r.jsx("span", { className: "unit", children: C })
-  ] }), O = () => a && !(a instanceof Array) ? /* @__PURE__ */ r.jsx(
-    Z,
+    j && /* @__PURE__ */ n.jsx("span", { className: "unit", children: j })
+  ] }), Z = () => s && !(s instanceof Array) ? /* @__PURE__ */ n.jsx(
+    ne,
     {
       disabled: !0,
-      ...a,
-      children: R()
+      ...s,
+      children: M()
     }
-  ) : R(), Q = () => J ? /* @__PURE__ */ r.jsx(
-    M,
+  ) : M(), _ = () => X ? /* @__PURE__ */ n.jsx(
+    P,
     {
       className: "range-input-warning-text",
-      helperText: g,
-      hideErrorDom: b
+      helperText: w,
+      hideErrorDom: R
     }
-  ) : /* @__PURE__ */ r.jsx(
-    M,
+  ) : /* @__PURE__ */ n.jsx(
+    P,
     {
       className: "range-input-error-text",
-      error: x,
-      helperText: L,
-      hideErrorDom: b
+      error: C,
+      helperText: O,
+      hideErrorDom: R
     }
   );
-  return /* @__PURE__ */ r.jsxs(
+  return /* @__PURE__ */ n.jsxs(
     "div",
     {
-      className: Y(W, `${l}-range-input`, `${l}-range-input-${S}`, {
-        [`${l}-range-input-focus`]: G,
-        [`${l}-range-input-disabled`]: t === !0 || c(0) && c(1),
-        [`${l}-range-input-error`]: x
+      ref: $,
+      className: re(S, `${u}-range-input`, `${u}-range-input-${G}`, {
+        [`${u}-range-input-focus`]: U,
+        [`${u}-range-input-disabled`]: l === !0 || p(0) && p(1),
+        [`${u}-range-input-error`]: C
       }),
-      style: H,
+      style: z,
       children: [
-        /* @__PURE__ */ r.jsx(
-          X,
+        /* @__PURE__ */ n.jsx(
+          ee,
           {
-            label: I,
-            required: q,
-            ...P
+            label: L,
+            required: J,
+            ...k
           }
         ),
-        O(),
-        Q()
+        Z(),
+        _()
       ]
     }
   );
-};
+}
 export {
-  de as RangeInput,
-  de as default
+  ge as RangeInput,
+  ge as default
 };
 //# sourceMappingURL=index.js.map

package/es/Result/component.json

@@ -0,0 +1,104 @@
+{
+    "name": "Result",
+    "category": "Feedback",
+    "description": "用于反馈一系列操作任务的处理结果",
+    "semantic": {
+        "intent": [
+            "展示结果",
+            "引导下一步",
+            "明确状态"
+        ],
+        "useCases": [
+            "提交成功",
+            "提交失败",
+            "加载中"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "success": {
+            "meaning": "成功(src 实装)"
+        },
+        "error": {
+            "meaning": "错误(src 实装)"
+        },
+        "loading": {
+            "meaning": "加载中(src 实装)"
+        },
+        "_blueprint_403": {
+            "meaning": "(蓝图 / src 未实装)无权限页 — 当前需用 icon 自定义模拟,见 discussions/Result-status-expansion-and-footer-epic.md"
+        },
+        "_blueprint_404": {
+            "meaning": "(蓝图 / src 未实装)未找到页 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_500": {
+            "meaning": "(蓝图 / src 未实装)服务器错误页 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_warning": {
+            "meaning": "(蓝图 / src 未实装)警告反馈 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_info": {
+            "meaning": "(蓝图 / src 未实装)信息反馈 — 当前需用 icon 自定义模拟"
+        }
+    },
+    "states": [
+        "visible"
+    ],
+    "idealProps": {
+        "status": {
+            "type": "'success' | 'error' | 'loading'",
+            "values": ["success", "error", "loading"],
+            "description": "结果状态;⚠️ src 当前仅实装这 3 个枚举值(src/Result/index.tsx:22 实证);蓝图 404/403/500/warning/info 见 variants._blueprint_* 与 discussions/Result-status-expansion-and-footer-epic.md;业务侧需要这些状态时,用 icon 自定义模拟"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "标题;src 内部经 AutoTips 包装,长文案自动 Tooltip"
+        },
+        "subTitle": {
+            "type": "ReactNode",
+            "description": "副标题;无 AutoTips 包装"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义结果图标;优先级【高于】status 默认图标;src 内部包在 .icon-box 容器中"
+        },
+        "footer": {
+            "type": "ReactNode",
+            "description": "⚠️ 操作区(底部);prop 名是 footer(不是 extra)!component.json 历史版本写过 extra 是蓝图笔误,src 实际实装的是 footer(src/Result/index.tsx:30 实证);通常放 1-2 个按钮"
+        }
+    },
+    "do": [
+        "在关键环节(支付/提交)结束后用 Result 反馈结果",
+        "提供明确的返回或重试按钮(放在 footer 插槽)",
+        "shape: 404/403/500/warning 等业务状态,通过 icon 自定义图标 + title 文案表达",
+        "长 title 文案放心使用 — 组件内部经 AutoTips 自动 Tooltip"
+    ],
+    "dont": [
+        "**不要传 status='404' / '403' / '500' / 'warning' / 'info'** — src 当前仅 success/error/loading 3 枚举,会触发 tsc 类型错误",
+        "**不要用 extra prop** — 操作区是 footer(extra 是蓝图未实装)",
+        "在简单的操作反馈中使用 Result(应使用 Message)",
+        "在 footer 内放过多按钮(2 个为佳:主+次)"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "status 枚举仅有 3 个值，传 '404'/'403'/'500'/'warning'/'info' 触发 TS 类型错误",
+            "wrong": "<Result status='404' title='Not Found' />  // TS 报 '404' 不属于 'success' | 'error' | 'loading'",
+            "right": "<Result icon={<NotFoundIcon />} title='404 - Not Found' />  // 用 icon 自定义模拟"
+        },
+        {
+            "issue": "操作区插槽名是 footer，不是 extra（历史蓝图遗留 extra 但 src 未实装）",
+            "wrong": "<Result status='success' extra={<Button>返回</Button>} />  // extra prop 不存在，静默无效",
+            "right": "<Result status='success' footer={<Button>返回</Button>} />  // src/Result/index.tsx:30 实证 footer"
+        },
+        {
+            "issue": "icon 与 status 同时传时 icon 优先，status 图标被覆盖",
+            "wrong": "// 期望用 status 图标同时用自定义外层容器 → icon 覆盖 status 图标",
+            "right": "// 需要自定义图标时只传 icon，无需传 status；需要预设图标时只传 status，不传 icon"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Result",
+        "adapter": null
+    }
+}

package/es/ScrollBar/component.json

@@ -0,0 +1,115 @@
+{
+    "name": "ScrollBar",
+    "category": "Layout",
+    "description": "滚动条美化:既支持全局 CSS 主题(默认场景),也提供 stand-alone 自驱动组件(虚拟列表/Canvas 等高级场景)",
+    "semantic": {
+        "intent": [
+            "美化原生滚动条",
+            "自驱动滚动指示器"
+        ],
+        "useCases": [
+            "固定高度内容溢出滚动(模式 A)",
+            "横向画廊(模式 A)",
+            "侧边栏/抽屉内容(模式 A)",
+            "虚拟列表/Canvas 自定义滚动(模式 B)"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "themedNative": {
+            "meaning": "模式 A:全局 className 主题 + native overflow(99% 场景推荐);使用 className `paraui-v4-scrollbar-{small|medium|large}{-deep}?` + native overflow:auto,不需要 import 任何组件"
+        },
+        "selfDriven": {
+            "meaning": "模式 B:<ScrollBar> stand-alone 组件,业务侧自驱动 scroll state(虚拟列表/Canvas 高级场景);组件本身不接受 children"
+        }
+    },
+    "states": [
+        "default",
+        "scrolling"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "'horizontal' | 'vertical'",
+            "values": ["horizontal", "vertical"],
+            "default": "'vertical'",
+            "description": "(模式 B)滚动条方向"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "'large'",
+            "description": "(模式 B)滚动条粗细;small/medium 同款细(4px),large 粗(8px)"
+        },
+        "color": {
+            "type": "'deep' | 'light'",
+            "values": ["deep", "light"],
+            "default": "'light'",
+            "description": "(模式 B)配色;light 浅背景,deep 深背景"
+        },
+        "scrollTotalLength": {
+            "type": "number",
+            "description": "(模式 B)内容总滚动距离(px);= contentTotalSize - visualWindowSize;业务侧从 scrollHeight - clientHeight 计算并传入"
+        },
+        "scrollLength": {
+            "type": "number",
+            "description": "(模式 B)当前滚动距离(px);业务侧从 native scrollTop/scrollLeft 同步进来;变化时组件移动滑块位置"
+        },
+        "onScroll": {
+            "type": "function",
+            "signature": "(val: number) => void",
+            "description": "(模式 B)用户拖拽滚动条时回调;val = 用户操作后业务侧应同步到 native 元素的 scrollTop/scrollLeft 值"
+        },
+        "themedClassName": {
+            "type": "string (literal)",
+            "description": "(模式 A)在 native overflow 容器上加 className,从下面选一个:'paraui-v4-scrollbar-small' / 'paraui-v4-scrollbar-medium' / 'paraui-v4-scrollbar-large' / '*-deep' 深色变体;src/Styles/scrollbar.scss 实现 ::-webkit-scrollbar-* 美化"
+        }
+    },
+    "do": [
+        "默认场景(限高容器 + 子内容溢出)用模式 A:className 主题 + native overflow:auto",
+        "横向滚动用 overflowX:auto + className 'paraui-v4-scrollbar-small' 等主题",
+        "虚拟列表 / Canvas 等业务侧已有 scroll state 的场景用模式 B:<ScrollBar /> 组件 + scrollTotalLength + scrollLength",
+        "深色背景上的滚动条用 *-deep 变体(浅色背景上保持默认或显式 light)"
+    ],
+    "dont": [
+        "**不要给 <ScrollBar> 组件传 children**(它不是 scroll 容器,是 visual indicator)",
+        "不要在普通业务场景重复实现 scrollTotalLength/scrollLength 计算 — 用模式 A className 即可",
+        "不要嵌套两层 ScrollBar 容器(双滚动条体验差)",
+        "不要忘了模式 B 必须搭配 native overflow:hidden 的容器才能视觉上接管滚动"
+    ],
+    "events": {
+        "onScroll": {
+            "signature": "(val: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户拖拽滚动条时触发，val = 应同步到 native 元素的 scrollTop/scrollLeft 值",
+                "onScroll={(val) => { nativeRef.current.scrollTop = val; setScrollLength(val); }}",
+                "双向绑定：业务侧同时监听 native onScroll 更新 scrollLength prop，ScrollBar.onScroll 更新 native scrollTop"
+            ],
+            "commonMistakes": [
+                "只传 onScroll 未更新 native 元素的 scrollTop——val 是期望值，需业务侧手动同步到 DOM",
+                "onScroll 和 scrollLength 没有形成闭环——用户拖 scrollbar 时 onScroll 触发更新 scrollTop；native 滚动时 onScroll 不触发，需监听 native onScroll 更新 scrollLength"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ScrollBar 组件的 Props interface 名是 Props（不是 ScrollBarProps），外部无法直接 import 类型",
+            "wrong": "import { ScrollBarProps } from '@para-ui/core/ScrollBar'  // 类型未导出",
+            "right": "// 直接使用 JSX 不需要类型引用；如需类型可自行 declare 或用 React.ComponentProps<typeof ScrollBar>"
+        },
+        {
+            "issue": "scrollTotalLength 传错含义——应是「可滚动距离」不是「内容总高度」",
+            "wrong": "scrollTotalLength={contentHeight}  // 期望传内容总高度——实际应传 scrollHeight - clientHeight",
+            "right": "scrollTotalLength={scrollHeight - clientHeight}  // = contentTotalSize - visualWindowSize"
+        },
+        {
+            "issue": "模式 A（className 主题）不需要 import ScrollBar 组件，直接加 className 即可",
+            "wrong": "import ScrollBar from '@para-ui/core/ScrollBar'; <ScrollBar>...</ScrollBar>  // ScrollBar 不接受 children",
+            "right": "<div className='paraui-v4-scrollbar-small' style={{overflowY: 'auto'}}>...</div>  // 模式 A 不 import 组件"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ScrollBar",
+        "adapter": null
+    }
+}