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

package/lib/InputCode/index.d.ts

@@ -34,7 +34,7 @@ export interface InputCodeCardProps extends HelperTextDetailProps {
     onFinish?: (val: string) => void;
     /** 重新发送 */
     onReset?: () => Promise<boolean> | boolean;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface InputCodeInputProps extends HelperTextDetailProps {
     /** 样式class */
@@ -66,7 +66,7 @@ export interface InputCodeInputProps extends HelperTextDetailProps {
     onChange?: (val: string) => void;
     /** 获取验证码事件 */
     onGetCode?: () => Promise<boolean> | boolean;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 type MergedInputCode = {
     Card: typeof InputCodeCard;

package/lib/InputLang/component.json

@@ -0,0 +1,205 @@
+{
+    "name": "InputLang",
+    "category": "Data Entry",
+    "description": "多语言输入框,支持多语种内容录入 + 语种切换。内部维护多语对象 `{[langKey]: string}`,通过 typeOutput 控制输出形态(对象 / JSON 字符串)",
+    "semantic": {
+        "intent": [
+            "多语言内容录入",
+            "国际化字段管理",
+            "翻译数据编辑"
+        ],
+        "useCases": [
+            "i18n 产品名 / 标签 / 描述录入",
+            "翻译管理后台",
+            "多语种 SEO 字段"
+        ],
+        "riskLevel": "normal"
+    },
+    "keyFormatBehavior": {
+        "supportedFormats": "**支持任意字符串作为 langKey**:短码('zh'/'en')、BCP 47('zh-CN'/'en-US'/'ja-JP')、自定义键名都可以。组件**不校验键名格式**,只把 langList 条目当作 value 对象的 key 使用",
+        "examples": "// 都合法:\n<InputLang langList={['zh', 'en']} value={{zh: '你好', en: 'Hello'}} />\n<InputLang langList={['zh-CN', 'en-US']} value={{'zh-CN': '你好', 'en-US': 'Hello'}} />\n<InputLang langList={['simplified', 'traditional']} value={{simplified: '你好', traditional: '妳好'}} />",
+        "warning": "**value 对象的 key 必须与 langList 字符串/value 字段完全匹配**(区分大小写 + 区分连字符)。例如 langList=['zh-CN'] 但 value={zh: '你好'} 时,InputLang 切到 zh-CN 标签后读不到值"
+    },
+    "langListDisplayBehavior": {
+        "stringMode": "**简写 string[] 模式**:每个字符串既是 value(内部 key)又是 label(弹层显示文本)。例 `langList={['zh-CN', 'en-US']}` 时,弹层切换 tab 显示的是 'zh-CN' / 'en-US' 字符串本身,**不是 '中文' / '英文' 本地化名称**",
+        "objectMode": "**对象 `{label, value}[]` 模式**:label 用于弹层显示,value 用于 value 对象的 key。例 `langList={[{label: '中文', value: 'zh-CN'}, {label: 'English', value: 'en-US'}]}`,弹层显示 '中文' / 'English' 友好文本,内部 value 对象用 'zh-CN' / 'en-US' 作 key",
+        "useWhen": "纯开发场景(配置 / 调试):用 string[] 简洁。**用户面向场景:用 {label, value}[] 配本地化文本**(string[] 显示原始 key 不友好)"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "标题旁帮助提示;对象,见 Label 组件 LabelTooltipProps"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入值的提示语(非语言键)"
+        },
+        "placeholderKey": {
+            "type": "string",
+            "description": "语言键侧的提示语;label='国际化' 模式常配合 placeholder 使用"
+        },
+        "placeholderValue": {
+            "type": "string",
+            "description": "翻译值侧的提示语"
+        },
+        "langList": {
+            "type": "(string | { label: string; value: string })[]",
+            "default": "['zh', 'en']",
+            "description": "**支持的语种列表**。两种形态:① 简写 string[] 如 `['zh', 'en']` —— 弹层显示原始 key 字符串(非本地化名);② 对象 `{label, value}[]` 如 `[{label:'中文',value:'zh'}]` —— 弹层显示 label 文本,内部用 value 作 key。**任意字符串都可作 langKey**(短码 / BCP 47 / 自定义,见 keyFormatBehavior)"
+        },
+        "value": {
+            "type": "string | { [name: string]: string }",
+            "description": "**受控值,形态由 typeOutput 控制**:typeOutput='object'(默认)→ `{zh:'输入框', en:'...'}` 多语对象;typeOutput='string' → JSON 字符串如 `'{\"zh\":\"输入框\",\"en\":\"...\",\"_i18n\":1}'`。**注:不是 Record<string,string>**(虽然语义上等价,签名是 `{[name]: string}` 索引签名形态),业务用 Record<string,string> 时需要 `as unknown as` 中转"
+        },
+        "defaultValue": {
+            "type": "string | { [name: string]: string }",
+            "description": "非受控初始值;形态同 value。可与 langList string[] 简写组合使用(两者正交)"
+        },
+        "onChange": {
+            "type": "(val: string | { [name: string]: string }) => void",
+            "description": "值变化回调;val 形态随 typeOutput 变化(string 或对象)。**业务签名 (val: Record<string, string>) => void**:可用 typeof 守卫 + `as unknown as Record<string,string>` 处理"
+        },
+        "typeOutput": {
+            "type": "enum",
+            "values": [
+                "string",
+                "object"
+            ],
+            "default": "object",
+            "description": "输出类型;'object' 输出多语对象,'string' 输出 JSON 字符串(含 _i18n 标识位)"
+        },
+        "required": {
+            "type": "boolean",
+            "default": "false",
+            "description": "是否必填"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "是否禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用态 hover 提示。**常用字段**:`title: ReactNode`(提示内容,最常用)、`placement?: 'top'|'bottom'|'left'|'right'|...`(方向)、`arrow?: boolean`(显示箭头)。完整字段见 Tooltip 组件文档"
+        },
+        "error": {
+            "type": "boolean",
+            "default": "false",
+            "description": "错误态视觉"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误文本/辅助文本"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "description": "true=无错误时不渲染占位;false=都渲染;null=不渲染直接返回 null。见 HelperText 同名 prop"
+        },
+        "limitLength": {
+            "type": "number",
+            "description": "输入长度上限"
+        },
+        "i18n": {
+            "type": "boolean",
+            "description": "i18n 标识;typeOutput='string' 时默认 true(向输出 JSON 注入 _i18n=1)"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "传 langList=['zh-CN', 'en-US'] 但 value={{ zh: '你好', en: 'Hello' }}(value 用短码 key)",
+            "result": "InputLang 切换到 'zh-CN' / 'en-US' 标签时读不到 value(因为 value 对象用的是 'zh'/'en' 短码 key) → 显示空内容",
+            "fix": "**langList 字符串/value 字段与 value 对象 key 必须完全一致**:要么都用短码(`langList=['zh','en']` + `value={{zh:'',en:''}}`),要么都用 BCP 47(`langList=['zh-CN','en-US']` + `value={{'zh-CN':'','en-US':''}}`)"
+        },
+        "M2": {
+            "wrong": "用 langList=['zh-CN', 'en-US'] 期望弹层显示 '中文' / 'English' 友好文本",
+            "result": "**string[] 简写模式弹层显示原始字符串**(显示 'zh-CN' / 'en-US' 而非翻译名)",
+            "fix": "用对象形式 `langList={[{label: '中文', value: 'zh-CN'}, {label: 'English', value: 'en-US'}]}` —— label 是显示文本,value 是内部 key"
+        },
+        "M3": {
+            "wrong": "在 onChange 回调签名是 `(val: Record<string, string>) => void` 的业务接口里直接接 InputLang.onChange,期望 TS 自动兼容",
+            "result": "**InputLang.onChange 签名是 `(val: string | { [name: string]: string }) => void`**,有 string 联合分支。直接传业务 callback 会因 string 分支不兼容 → TS 报错",
+            "fix": "用 typeof 守卫 + cast: `onChange={(val) => { if (typeof val !== 'string') businessCallback(val as unknown as Record<string, string>); }}` 或者用 typeOutput='object' 保证不会出现 string 分支"
+        },
+        "M4": {
+            "wrong": "假设 langList 默认值是空数组",
+            "result": "**默认值是 `['zh', 'en']`**(代码 L114 实证)。不传 langList 时 InputLang 仍然显示 zh/en 两个语种 tab",
+            "fix": "需要纯空白:显式传 `langList={[]}`(罕见)。需要完全自定义语种:传完整 langList 覆盖默认"
+        }
+    },
+    "do": [
+        "**langList 字符串/value 字段与 value 对象 key 一致**(全短码或全 BCP 47,见 M1)",
+        "**用户面向场景用对象形式 langList**(配 label 本地化文本,M2)",
+        "**业务 callback Record<string,string>**:typeof 守卫 + as unknown as 中转(M3)",
+        "**typeOutput 默认 'object'** —— 直接用对象形态;只在需要 JSON 持久化时用 'string'",
+        "禁用态配合 disabledTooltip={{title: '已归档,不可编辑'}} 给业务语义化提示"
+    ],
+    "dont": [
+        "**不要**让 langList key 与 value 对象 key 不一致 —— 读不到值(M1)",
+        "**不要**用 string[] langList 期望本地化显示 —— 显示原始 key(M2)",
+        "**不要**直接对接 Record<string,string> 业务 callback —— 联合签名不兼容(M3)",
+        "**不要**忘记不传 langList 时默认 ['zh','en'] —— 不是空数组(M4)",
+        "语言列表过多(>5)导致下拉过长 —— 考虑分组",
+        "忽略默认语言设置"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string | { [name: string]: string }) => void",
+            "asyncSupported": false,
+            "examples": [
+                "typeOutput='object'(默认): onChange={(val) => { if (typeof val !== 'string') setState(val as Record<string,string>); }} — 对象形态，{zh:'内容', en:'content'}",
+                "typeOutput='string': onChange={(val) => { if (typeof val === 'string') setState(val); }} — JSON 字符串形态，'{\"zh\":\"内容\",\"_i18n\":1}'",
+                "弹窗关闭时触发（不是实时）：用户在弹窗内修改其他语种值，关闭弹窗后 onChange 才触发一次完整 val"
+            ],
+            "commonMistakes": [
+                "onChange 签名写成 (val: Record<string, string>) => void 直接接入——TypeScript 报错，InputLang.onChange 联合 string 分支，需 typeof 守卫",
+                "期望每次按键都触发 onChange——主语言（当前展示语言）实时触发，其他语言在弹窗关闭时批量触发一次",
+                "typeOutput='string' 时期望 onChange 返回的 val 是纯 JSON——实际含 _i18n 标识位，需 JSON.parse 后 delete _i18n 才是干净数据"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名是联合类型，直接接业务 Record<string,string> 回调触发 TS 不兼容",
+            "wrong": "const handler = (val: Record<string, string>) => setState(val); <InputLang onChange={handler} /> // 报 TS2322：string 分支和 Record 不兼容",
+            "right": "<InputLang onChange={(val) => { if (typeof val !== 'string') setState(val as unknown as Record<string,string>); }} />"
+        },
+        {
+            "issue": "value 类型签名是 `string | { [name: string]: string }` 不是 `Record<string, string>`，在 TS 5.x 可能触发 TS2352 直接 as cast 失败",
+            "wrong": "const data: Record<string,string> = {zh: '你好'}; <InputLang value={data as { [name: string]: string }} /> // TS5 strict 模式下拒绝结构兼容 as",
+            "right": "<InputLang value={data as unknown as { [name: string]: string }} /> // 用 unknown 中转"
+        },
+        {
+            "issue": "langList 默认值是 ['zh', 'en']，不传时已经有两个语种 tab，不是空列表",
+            "wrong": "// 期望没有多语切换，不传 langList\n<InputLang value={val} onChange={onChange} /> // 实际显示 zh/en 两个 tab，点击地球图标弹出语种选择",
+            "right": "// 需要禁用多语：传 langList={[]}（无弹出语种）或 disabledAdd + disabledDelete + disabledKey 锁定行为"
+        }
+    ],
+    "mapping": {
+        "realComponent": "InputLang",
+        "adapter": null
+    }
+}

package/lib/InputLang/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const u=require("../_virtual/jsx-runtime.js"),s=require("react"),be=require("../TextField/index.js"),he=require("../HelperText/index.js"),me=require("../MultiBox/index.js"),ve=require("../AutoTips/index.js"),je=require("../Popover/index.js"),ye=require("../node_modules/@para-ui/icons/Internet/index.js"),W=require("@paraview/lib"),g=require("../GlobalContext/constant.js"),Ce=require("../Hooks/useGlobalProps.js");;/* empty css            */const z=f=>{const{className:R,style:H,label:K,labelTooltip:F,size:v="large",placeholder:q,placeholderKey:G,placeholderValue:J,error:L=!1,hideErrorDom:w,helperText:Q="",required:U=!1,popoverClassName:N,value:M,onChange:O,langList:x=["zh","en"],limitLength:$,disabled:_=!1,disabledTooltip:X,defaultLang:j,disabledDelete:S,disabledAdd:Y,disabledKey:E,typeOutput:V="object",i18n:D}=Ce.default(f,"InputLang"),[Z,k]=s.useState(!1),[o,ee]=s.useState(W.GetLanguage()||"zh"),[I,te]=s.useState({}),[b,T]=s.useState({}),[d,A]=s.useState([]),a=s.useRef({lang:o,valueCom:b,langMapping:{},langLabelMapping:{}}),P=s.useRef(null);a.current.lang=o,a.current.disabledDelete=S,a.current.typeOutput=V,a.current.i18n=V==="string"&&D===void 0?!0:D,s.useEffect(()=>{f.defaultValue!==void 0&&y(f.defaultValue)},[]),s.useEffect(()=>{M!==void 0&&y(M)},[M]),s.useEffect(()=>{j!==void 0&&(ee(j),a.current.lang=j,y())},[j]),s.useEffect(()=>{if(x){const e={},t={};for(let l=0,i=x.length;l<i;l++){const n=x[l];typeof n=="string"?(e[n]={label:n,value:n},t[n]={label:n,value:n}):(e[n.value]=n,t[n.label]=n)}a.current.langMapping=e,a.current.langLabelMapping=t,te(e),y()}},[f.langList]);const y=e=>{let t;if(e){try{typeof e=="string"?t=JSON.parse(e):t=e||{}}catch{t={}}a.current.i18n===!0&&(a.current._i18n=t._i18n||1,delete t._i18n)}const l={...t||a.current.valueCom},i=[],n={};if(a.current.disabledDelete){const r=Object.keys(a.current.langMapping)||[];for(let h=0,p=r.length;h<p;h++){const C=a.current.langMapping[r[h]]||{},m=C.value,fe=C.label,xe=l[m];m!==a.current.lang&&(n[m]=!0,i.push({label:fe,value:xe||""}))}}const c=Object.keys(l);for(let r=0,h=c.length;r<h;r++){const p=c[r],C=l[p];if(!n[p]&&p!==a.current.lang){const m=a.current.langMapping[p]||{};i.push({label:m.label||p,value:C||""})}}a.current.valueCom={...l},A(i),T(l)},B=e=>{let t={...e};if(f.value===void 0&&(a.current.valueCom={...t},T(t)),a.current.typeOutput==="string")try{a.current.i18n===!0&&(t._i18n=a.current._i18n||1),t=JSON.stringify(t)}catch{}O&&O(t)},ne=e=>{b[o]=e.target.value;const t={...b};B(t)},le=e=>{A([...e])},ae=(e,t)=>{const l=[],i=W.ArrayToObject("label",d);for(let n=0,c=x.length;n<c;n++){let r=x[n];typeof r=="object"&&(r=r.label),!i[r]&&r!==(I[o]?.label||o)&&l.push({label:r,value:r})}t(l)},re=()=>{k(!0)},se=e=>{if(e)return;k(!1);const t={};t[o]=b[o]||"";for(let l=0,i=d.length;l<i;l++){const n=d[l],c=a.current.langLabelMapping[n.label]?.value||n.label||"";c.trim()!==""&&(t[c]=n.value||"")}B(t)},ie=()=>u.jsxRuntimeExports.jsx("div",{className:"lang-key",children:u.jsxRuntimeExports.jsx(ve.default,{tipMaxWidth:"none",children:I[o]?.label||o})}),oe=s.useMemo(()=>u.jsxRuntimeExports.jsx("div",{className:"lang-list-icon",children:u.jsxRuntimeExports.jsx(ye.Internet,{})}),[]),ue=()=>{let e=`${g.$prefixCls}-input-lang-popover`;return N&&(e+=` ${N}`),Y&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-add`),S&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-delete`),e},ce=()=>{if(_===!0)return!0;const e=[];if(E){const t=typeof E=="object";for(let l=0,i=d.length;l<i;l++){const n=d[l].label||"",c=a.current.langLabelMapping[n]||{};t?e.push({[n]:E.indexOf(c.value||n)!==-1}):n.trim()!==""&&e.push({[n]:!0})}}return e},pe=(e,t)=>{const l={};return $&&(l.limitLength=$),l},de=()=>u.jsxRuntimeExports.jsx("div",{className:"input-lang-list",children:u.jsxRuntimeExports.jsx(me.MultiBox,{className:"input-lang-multi-box",size:v,disabled:ce(),value:d,onChange:le,fetchSuggestionsKey:ae,placeholderKey:G,placeholderValue:J||q,valueOtherProps:pe})}),ge=()=>{let e=`${g.$prefixCls}-input-lang`;return v&&(e+=` ${g.$prefixCls}-input-lang-${v}`),L&&(e+=` ${g.$prefixCls}-input-lang-error`),R&&(e+=` ${R}`),e};return u.jsxRuntimeExports.jsxs("div",{className:ge(),style:H,ref:P,children:[u.jsxRuntimeExports.jsx(je.Popover,{placement:"bottom-end",visible:Z,content:de(),onVisibleChange:se,overlayClassName:ue(),maxWidth:"none",overlayInnerStyle:{minWidth:"440px",width:`${P.current?.offsetWidth}px`},children:u.jsxRuntimeExports.jsx(be.TextField,{className:"input-lang-text-field",size:v,error:L,disabled:_,disabledTooltip:X,required:U,label:K,labelTooltip:F,placeholder:q,value:b[o]||"",rightIcon:oe,addonBefore:ie(),hideErrorDom:!0,limitLength:$,onClickIcon:re,onChange:ne})}),u.jsxRuntimeExports.jsx(he.default,{className:"input-lang-error-text",error:L,helperText:Q,hideErrorDom:w})]})};exports.InputLang=z;exports.default=z;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const u=require("../_virtual/jsx-runtime.js"),r=require("react"),be=require("../TextField/index.js"),he=require("../HelperText/index.js"),me=require("../MultiBox/index.js"),ve=require("../AutoTips/index.js"),je=require("../Popover/index.js"),ye=require("../node_modules/@para-ui/icons/Internet/index.js"),K=require("../Utils/snack-kit-shims.js"),g=require("../GlobalContext/constant.js"),Ce=require("../Hooks/useGlobalProps.js");;/* empty css            */const W=f=>{const{className:$,style:z,label:H,labelTooltip:F,size:v="large",placeholder:q,placeholderKey:G,placeholderValue:J,error:L=!1,hideErrorDom:w,helperText:Q="",required:U=!1,popoverClassName:S,value:M,onChange:N,langList:x=["zh","en"],limitLength:E,disabled:O=!1,disabledTooltip:X,defaultLang:j,disabledDelete:_,disabledAdd:Y,disabledKey:R,typeOutput:V="object",i18n:k}=Ce.default(f,"InputLang"),[Z,D]=r.useState(!1),[o,ee]=r.useState(K.GetLanguage()||"zh"),[I,te]=r.useState({}),[b,T]=r.useState({}),[d,A]=r.useState([]),a=r.useRef({lang:o,valueCom:b,langMapping:{},langLabelMapping:{}}),P=r.useRef(null);a.current.lang=o,a.current.disabledDelete=_,a.current.typeOutput=V,a.current.i18n=V==="string"&&k===void 0?!0:k,r.useEffect(()=>{f.defaultValue!==void 0&&y(f.defaultValue)},[]),r.useEffect(()=>{M!==void 0&&y(M)},[M]),r.useEffect(()=>{j!==void 0&&(ee(j),a.current.lang=j,y())},[j]),r.useEffect(()=>{if(x){const e={},t={};for(let l=0,i=x.length;l<i;l++){const n=x[l];typeof n=="string"?(e[n]={label:n,value:n},t[n]={label:n,value:n}):(e[n.value]=n,t[n.label]=n)}a.current.langMapping=e,a.current.langLabelMapping=t,te(e),y()}},[f.langList]);const y=e=>{let t;if(e){try{typeof e=="string"?t=JSON.parse(e):t=e||{}}catch{t={}}a.current.i18n===!0&&(a.current._i18n=t._i18n||1,delete t._i18n)}const l={...t||a.current.valueCom},i=[],n={};if(a.current.disabledDelete){const s=Object.keys(a.current.langMapping)||[];for(let h=0,p=s.length;h<p;h++){const C=a.current.langMapping[s[h]]||{},m=C.value,fe=C.label,xe=l[m];m!==a.current.lang&&(n[m]=!0,i.push({label:fe,value:xe||""}))}}const c=Object.keys(l);for(let s=0,h=c.length;s<h;s++){const p=c[s],C=l[p];if(!n[p]&&p!==a.current.lang){const m=a.current.langMapping[p]||{};i.push({label:m.label||p,value:C||""})}}a.current.valueCom={...l},A(i),T(l)},B=e=>{let t={...e};if(f.value===void 0&&(a.current.valueCom={...t},T(t)),a.current.typeOutput==="string")try{a.current.i18n===!0&&(t._i18n=String(a.current._i18n||1)),t=JSON.stringify(t)}catch{}N&&N(t)},ne=e=>{b[o]=e.target.value;const t={...b};B(t)},le=e=>{A([...e])},ae=(e,t)=>{const l=[],i=K.ArrayToObject("label",d);for(let n=0,c=x.length;n<c;n++){let s=x[n];typeof s=="object"&&(s=s.label),!i[s]&&s!==(I[o]?.label||o)&&l.push({label:s,value:s})}t(l)},se=()=>{D(!0)},re=e=>{if(e)return;D(!1);const t={};t[o]=b[o]||"";for(let l=0,i=d.length;l<i;l++){const n=d[l],c=a.current.langLabelMapping[n.label]?.value||n.label||"";c.trim()!==""&&(t[c]=n.value||"")}B(t)},ie=()=>u.jsxRuntimeExports.jsx("div",{className:"lang-key",children:u.jsxRuntimeExports.jsx(ve.default,{tipMaxWidth:"none",children:I[o]?.label||o})}),oe=r.useMemo(()=>u.jsxRuntimeExports.jsx("div",{className:"lang-list-icon",children:u.jsxRuntimeExports.jsx(ye.Internet,{})}),[]),ue=()=>{let e=`${g.$prefixCls}-input-lang-popover`;return S&&(e+=` ${S}`),Y&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-add`),_&&(e+=` ${g.$prefixCls}-input-lang-popover-disabled-delete`),e},ce=()=>{if(O===!0)return!0;const e=[];if(R){const t=typeof R=="object";for(let l=0,i=d.length;l<i;l++){const n=d[l].label||"",c=a.current.langLabelMapping[n]||{};t?e.push({[n]:R.indexOf(c.value||n)!==-1}):n.trim()!==""&&e.push({[n]:!0})}}return e},pe=(e,t)=>{const l={};return E&&(l.limitLength=E),l},de=()=>u.jsxRuntimeExports.jsx("div",{className:"input-lang-list",children:u.jsxRuntimeExports.jsx(me.MultiBox,{className:"input-lang-multi-box",size:v,disabled:ce(),value:d,onChange:le,fetchSuggestionsKey:ae,placeholderKey:G,placeholderValue:J||q,valueOtherProps:pe})}),ge=()=>{let e=`${g.$prefixCls}-input-lang`;return v&&(e+=` ${g.$prefixCls}-input-lang-${v}`),L&&(e+=` ${g.$prefixCls}-input-lang-error`),$&&(e+=` ${$}`),e};return u.jsxRuntimeExports.jsxs("div",{className:ge(),style:z,ref:P,children:[u.jsxRuntimeExports.jsx(je.Popover,{placement:"bottom-end",visible:Z,content:de(),onVisibleChange:re,overlayClassName:ue(),maxWidth:"none",overlayInnerStyle:{minWidth:"440px",width:`${P.current?.offsetWidth}px`},children:u.jsxRuntimeExports.jsx(be.TextField,{className:"input-lang-text-field",size:v,error:L,disabled:O,disabledTooltip:X,required:U,label:H,labelTooltip:F,placeholder:q,value:b[o]||"",rightIcon:oe,addonBefore:ie(),hideErrorDom:!0,limitLength:E,onClickIcon:se,onChange:ne})}),u.jsxRuntimeExports.jsx(he.default,{className:"input-lang-error-text",error:L,helperText:Q,hideErrorDom:w})]})};exports.InputLang=W;exports.default=W;
 //# sourceMappingURL=index.js.map

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

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