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

package/lib/RangeInput/index.d.ts

@@ -1,9 +1,9 @@
-import { default as React, FunctionComponent, ReactNode } from 'react';
+import { default as React, ReactNode } from 'react';
 import { LabelTooltipProps } from '../Label';
 import { InputNumberProps } from '../InputNumber';
 import { HelperTextDetailProps } from '../HelperText';
 import { TooltipProps } from '../Tooltip';
-export interface RangeInputProps extends HelperTextDetailProps {
+export interface RangeInputProps<Clearable extends boolean = false> extends HelperTextDetailProps {
     /** 样式class */
     className?: string;
     /** style */
@@ -22,10 +22,16 @@ export interface RangeInputProps extends HelperTextDetailProps {
      * 禁用提示
      */
     disabledTooltip?: TooltipProps | [TooltipProps, TooltipProps];
+    /**
+     * 是否允许清空（清空后 onChange 回传 null）；
+     * 默认 false 时 value/defaultValue/onChange 入参收敛为 number，子 InputNumber 由 RangeInput 内部以 clearable 模式承载临时 null 状态；
+     * 显式 true 时全链路类型放宽到 number | null，沿用历史行为
+     */
+    clearable?: Clearable;
     /** 默认值 不受控 */
-    defaultValue?: [number | null, number | null];
+    defaultValue?: Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined];
     /** 默认值 */
-    value?: [number | null, number | null];
+    value?: Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined];
     /** 中间符号 */
     separator?: ReactNode;
     /** 单位 */
@@ -40,8 +46,10 @@ export interface RangeInputProps extends HelperTextDetailProps {
     otherProps?: [InputNumberProps, InputNumberProps];
     /**
      * 改变值
-     * */
-    onChange?: (val: [number | null, number | null], index: number) => void;
+     * @param val 当前 value 数组
+     * @param index 触发改变的输入框下标；index === -1 表示由 RangeInput 内部 swap 触发，[0]/[1] 同时变化
+     */
+    onChange?: (val: Clearable extends true ? [number | null, number | null] : [number, number], index: number) => void;
     /** 失去焦点 */
     onBlur?: (event: React.FocusEvent<HTMLInputElement>, index: number) => void;
     /** 得到焦点 */
@@ -49,5 +57,5 @@ export interface RangeInputProps extends HelperTextDetailProps {
     /** 回车事件 */
     onEnter?: (event: React.KeyboardEvent<HTMLInputElement>, index: number) => void;
 }
-export declare const RangeInput: FunctionComponent<RangeInputProps>;
+export declare function RangeInput<C extends boolean = false>(props: RangeInputProps<C>): JSX.Element;
 export default RangeInput;

package/lib/RangeInput/index.js

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

package/lib/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/lib/Result/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),p=require("clsx"),R=require("../AutoTips/index.js"),h=require("../node_modules/@para-ui/icons/Check/index.js"),f=require("../node_modules/@para-ui/icons/Close/index.js"),E=require("../node_modules/@para-ui/icons/Loading/index.js"),o=require("../GlobalContext/constant.js");;/* empty css            */const v={success:e.jsxRuntimeExports.jsx(h.Check,{}),error:e.jsxRuntimeExports.jsx(f.Close,{}),loading:e.jsxRuntimeExports.jsx(E.Loading,{})},u=c=>{const{className:l,style:x,status:s,icon:t,title:i,subTitle:r,footer:n}=c,a=()=>{if(t)return e.jsxRuntimeExports.jsx("div",{className:"icon-box",children:t});if(s)return e.jsxRuntimeExports.jsx("div",{className:"icon-box",children:e.jsxRuntimeExports.jsx("div",{className:"icon-bg",children:v[s]})})},d=()=>{if(i)return e.jsxRuntimeExports.jsx("div",{className:"title",children:e.jsxRuntimeExports.jsx(R.default,{children:i})})},j=()=>{if(r)return e.jsxRuntimeExports.jsx("div",{className:"sub-title",children:r})},m=()=>{if(n)return e.jsxRuntimeExports.jsx("div",{className:"footer",children:n})};return e.jsxRuntimeExports.jsxs("div",{className:p(l,`${o.$prefixCls}-result`,{[`${o.$prefixCls}-result-${s}`]:s}),style:x,children:[a(),d(),j(),m()]})};exports.Result=u;exports.default=u;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),p=require("clsx"),R=require("../AutoTips/index.js"),h=require("../para-ui-core/node_modules/@para-ui/icons/Check/index.js"),f=require("../para-ui-core/node_modules/@para-ui/icons/Close/index.js"),E=require("../para-ui-core/node_modules/@para-ui/icons/Loading/index.js"),o=require("../GlobalContext/constant.js");;/* empty css            */const v={success:e.jsxRuntimeExports.jsx(h.Check,{}),error:e.jsxRuntimeExports.jsx(f.Close,{}),loading:e.jsxRuntimeExports.jsx(E.Loading,{})},u=c=>{const{className:l,style:x,status:s,icon:t,title:i,subTitle:r,footer:n}=c,a=()=>{if(t)return e.jsxRuntimeExports.jsx("div",{className:"icon-box",children:t});if(s)return e.jsxRuntimeExports.jsx("div",{className:"icon-box",children:e.jsxRuntimeExports.jsx("div",{className:"icon-bg",children:v[s]})})},d=()=>{if(i)return e.jsxRuntimeExports.jsx("div",{className:"title",children:e.jsxRuntimeExports.jsx(R.default,{children:i})})},j=()=>{if(r)return e.jsxRuntimeExports.jsx("div",{className:"sub-title",children:r})},m=()=>{if(n)return e.jsxRuntimeExports.jsx("div",{className:"footer",children:n})};return e.jsxRuntimeExports.jsxs("div",{className:p(l,`${o.$prefixCls}-result`,{[`${o.$prefixCls}-result-${s}`]:s}),style:x,children:[a(),d(),j(),m()]})};exports.Result=u;exports.default=u;
 //# sourceMappingURL=index.js.map

package/lib/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
+    }
+}

package/lib/Search/component.json

@@ -0,0 +1,177 @@
+{
+    "name": "Search",
+    "category": "Data Entry",
+    "description": "搜索框组件，支持受控/非受控模式、清空按钮、回车和点击按钮触发搜索",
+    "semantic": {
+        "intent": [
+            "搜索",
+            "过滤"
+        ],
+        "useCases": [
+            "列表搜索",
+            "全局搜索",
+            "筛选"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "focused"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string",
+            "description": "受控输入值（src/Search/index.tsx:26 实证）。与 `defaultValue` 互斥——传 value 后为受控模式，内部 state 不自动更新，需配合 onChange 手动同步"
+        },
+        "defaultValue": {
+            "type": "string",
+            "description": "非受控初始值（src/Search/index.tsx:24 实证）。组件 mount 时一次性设置，之后内部管理输入 state。与 value 互斥——不要同时传"
+        },
+        "placeholder": {
+            "type": "string | ReactNode",
+            "description": "输入框占位文案（src/Search/index.tsx:22 实证，类型 ReactNode，实际用 string 即可）。默认空字符串"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示清空按钮（src/Search/index.tsx:28 实证，默认 true）。清空时触发 `onClear` 回调"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(val: string, event: React.ChangeEvent<HTMLInputElement> | null) => void",
+            "description": "输入值变化回调（src/Search/index.tsx:30 实证签名，两参：val 字符串值 + event 原生事件）。⚠️ **第一参是 string 值，不是 event**——区别于原生 input onChange。当点击搜索按钮且未传 onClickBtn 时也会触发 onChange（event 此时为 null）"
+        },
+        "onClickBtn": {
+            "type": "function",
+            "signature": "(val: string) => void",
+            "description": "点击右侧搜索按钮的回调（src/Search/index.tsx:40 实证签名）。参数 val 为当前输入框的值。⚠️ **若不传 onClickBtn，点击按钮会 fallback 触发 onChange**（src:99-104）。`onClickRightIcon` 是其已废弃别名"
+        },
+        "onEnter": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "回车键按下的回调（src/Search/index.tsx:46 实证签名）。通常与 onClickBtn 配合覆盖「按钮触发搜索」和「回车触发搜索」两种路径"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击清空按钮的回调（src/Search/index.tsx:44 实证签名，无参）。清空后输入框值变为空字符串；allowClear=true 时清空按钮才可见"
+        },
+        "onFocus": {
+            "type": "function",
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "description": "输入框获得焦点的回调（src/Search/index.tsx:34 实证签名）"
+        },
+        "onBlur": {
+            "type": "function",
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "description": "输入框失去焦点的回调（src/Search/index.tsx:32 实证签名）"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小（src/Search/index.tsx:18 实证，默认 large）"
+        },
+        "radius": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否使用圆角样式（src/Search/index.tsx:20 实证）"
+        },
+        "onClickRightIcon": {
+            "type": "function",
+            "signature": "(val: string) => void",
+            "description": "⚠️ **已废弃，请使用 `onClickBtn`**（src/Search/index.tsx:41 注释实证）。点击输入框右侧图标的回调，与 onClickBtn 同时触发"
+        },
+        "onKeydown": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "键盘按下事件回调（src/Search/index.tsx:36 实证）。⚠️ **注意拼写：onKeydown（非 onKeyDown）**，prop 名首字母 d 小写"
+        },
+        "onKeyUp": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "键盘抬起事件回调（src/Search/index.tsx:38 实证）"
+        }
+    },
+    "do": [
+        "支持回车搜索：同时传 onEnter 和 onClickBtn 覆盖「回车触发」和「点击按钮触发」两条路径",
+        "提供清空按钮：allowClear 默认 true，清空时只触发 onClear，不触发 onChange",
+        "受控模式：传 value + onChange 实现受控；onChange 第一参是 string 值（不是 event）",
+        "非受控模式：只传 defaultValue，内部管理输入 state；不要同时传 value 和 defaultValue"
+    ],
+    "dont": [
+        "不要把 onChange 的第一参当 event 使用——Search.onChange 签名是 (val: string, event) 而非 antd Input.onChange 的 (event) 签名",
+        "不要忽略 onClickBtn 为空时点击搜索按钮的 fallback 行为——未传 onClickBtn 时点击会触发 onChange（event 为 null）",
+        "搜索时不给反馈（网络搜索场景应配合 loading 状态）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string, event: React.ChangeEvent<HTMLInputElement> | null) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户实时输入时触发，val 是当前输入框字符串值",
+                "点击右侧搜索按钮且未传 onClickBtn 时也触发，此时 event 为 null",
+                "受控用法：const [keyword, setKeyword] = useState(''); <Search value={keyword} onChange={(val) => setKeyword(val)} />"
+            ],
+            "commonMistakes": [
+                "误按 antd Input 习惯写 onChange={(e) => setValue(e.target.value)} — 第一参是 string 不是 event",
+                "期望清空按钮触发 onChange — 清空只触发 onClear，需同时监听 onClear 来清空外部 state",
+                "忘记 onClickBtn 未传时 onChange event 参数可能为 null — 应做 null 判断再访问 event.target"
+            ]
+        },
+        "onClickBtn": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户点击右侧搜索图标时触发，val 为当前输入框的值",
+                "通常与 onEnter 一起传：点击和回车都调用同一个 search 函数"
+            ],
+            "commonMistakes": [
+                "不传 onClickBtn 时点击按钮 fallback 触发 onChange（event=null）— 若只需按钮触发必须显式传 onClickBtn",
+                "与 onClickRightIcon 混淆 — onClickRightIcon 是 onClickBtn 的已废弃别名，二者同时触发"
+            ]
+        },
+        "onEnter": {
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户在输入框按回车键触发，event 是 KeyboardEvent",
+                "取当前值：event.currentTarget.value 或从外部 state 直接读 keyword"
+            ],
+            "commonMistakes": [
+                "与 onClickBtn 语义重复时未合并为同一个函数 — 可在父组件定义 handleSearch 同时传给两个 prop",
+                "假设 onEnter 触发时 onChange 也会触发 — 回车不会触发 onChange，需在 onEnter 里单独处理搜索逻辑"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名与原生 input onChange 不同，第一参是 string 值而非 event",
+            "wrong": "onChange={(e) => setVal(e.target.value)}  // TS 报 string 没有 .target 属性",
+            "right": "onChange={(val) => setVal(val)}  // val: string 直接使用"
+        },
+        {
+            "issue": "onKeydown prop 名小写 d，不是 onKeyDown（驼峰 D）",
+            "wrong": "<Search onKeyDown={handler} />  // prop 名不存在，静默无效",
+            "right": "<Search onKeydown={handler} />  // src/Search/index.tsx:36 interface 实证 onKeydown 小写 d"
+        },
+        {
+            "issue": "onClickRightIcon 已废弃，运行时与 onClickBtn 同时触发造成双重执行",
+            "wrong": "<Search onClickRightIcon={handleSearch} />  // 废弃 API，src 注释明确不建议使用",
+            "right": "<Search onClickBtn={handleSearch} />  // 推荐替代 prop"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Search",
+        "adapter": null
+    }
+}

package/lib/Search/index.d.ts

@@ -33,7 +33,7 @@ export interface SearchProps {
     onClear?: () => void;
     /** 回车事件 */
     onEnter?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Search: FunctionComponent<SearchProps>;
 export default Search;

package/lib/Search/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const i=require("../_virtual/jsx-runtime.js"),l=require("react"),N=require("../TextField/index.js"),T=require("../node_modules/@para-ui/icons/Search/index.js"),c=require("../GlobalContext/constant.js");;/* empty css            */const x=e=>{const{className:u="",style:C,size:s="large",radius:v=!1,placeholder:g="",value:n,rightIcon:d,allowClear:m=!0,onChange:r,onBlur:j,onFocus:I,onKeydown:R,onKeyUp:$,onClickBtn:f,onEnter:E,onClear:q,otherProps:S}=e,[o,a]=l.useState("");l.useEffect(()=>{e.defaultValue!==void 0&&a(e.defaultValue)},[]),l.useEffect(()=>{n!==void 0&&a(n)},[n]);const k=()=>d||i.jsxRuntimeExports.jsx(T.Search,{}),w=()=>{if(f||e.onClickRightIcon){f?.(o),e.onClickRightIcon?.(o);return}r&&r(o,null)},y=t=>{const h=t.target.value;e.value===void 0&&a(h),r&&r(h,t)},V=()=>{let t=`${c.$prefixCls}-search`;return u&&(t+=` ${u}`),s&&(t+=` ${c.$prefixCls}-search-${s}`),v&&(t+=` ${c.$prefixCls}-search-radius`),t},F=()=>e.value===void 0?o:n;return i.jsxRuntimeExports.jsx("div",{className:V(),style:C,children:i.jsxRuntimeExports.jsx(N.TextField,{className:"search-text-field",size:s,placeholder:g,value:F(),rightIcon:k(),onClickIcon:w,hideErrorDom:!0,onChange:y,onBlur:j,onFocus:I,onKeydown:R,onKeyUp:$,onEnter:E,autoComplete:"new-password",allowClear:m,onClear:q,...S})})};exports.Search=x;exports.default=x;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const i=require("../_virtual/jsx-runtime.js"),l=require("react"),N=require("../TextField/index.js"),T=require("../para-ui-core/node_modules/@para-ui/icons/Search/index.js"),c=require("../GlobalContext/constant.js");;/* empty css            */const x=e=>{const{className:u="",style:C,size:s="large",radius:v=!1,placeholder:g="",value:n,rightIcon:d,allowClear:m=!0,onChange:r,onBlur:j,onFocus:I,onKeydown:R,onKeyUp:$,onClickBtn:f,onEnter:E,onClear:q,otherProps:S}=e,[o,a]=l.useState("");l.useEffect(()=>{e.defaultValue!==void 0&&a(e.defaultValue)},[]),l.useEffect(()=>{n!==void 0&&a(n)},[n]);const k=()=>d||i.jsxRuntimeExports.jsx(T.Search,{}),w=()=>{if(f||e.onClickRightIcon){f?.(o),e.onClickRightIcon?.(o);return}r&&r(o,null)},y=t=>{const h=t.target.value;e.value===void 0&&a(h),r&&r(h,t)},V=()=>{let t=`${c.$prefixCls}-search`;return u&&(t+=` ${u}`),s&&(t+=` ${c.$prefixCls}-search-${s}`),v&&(t+=` ${c.$prefixCls}-search-radius`),t},F=()=>e.value===void 0?o:n;return i.jsxRuntimeExports.jsx("div",{className:V(),style:C,children:i.jsxRuntimeExports.jsx(N.TextField,{className:"search-text-field",size:s,placeholder:g,value:F(),rightIcon:k(),onClickIcon:w,hideErrorDom:!0,onChange:y,onBlur:j,onFocus:I,onKeydown:R,onKeyUp:$,onEnter:E,autoComplete:"new-password",allowClear:m,onClear:q,...S})})};exports.Search=x;exports.default=x;
 //# sourceMappingURL=index.js.map