@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.14

package/SingleBox/component.json

@@ -0,0 +1,151 @@
+{
+    "name": "SingleBox",
+    "category": "Data Entry",
+    "description": "逐行多值列表输入框(每行一个值,整体以 string[] 数组收集 · 支持自动补全)",
+    "semantic": {
+        "intent": [
+            "多值列表输入(逐行)",
+            "标签集合录入",
+            "自动补全"
+        ],
+        "useCases": [
+            "多关键词输入(每行一个)",
+            "标签批量录入",
+            "多值配置项"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "array",
+            "itemType": "string",
+            "description": "受控值 string[],与 defaultValue 互斥(必须配合 onChange 同步)。**业务 string 单值桥接**(协议 SB1):`value={s ? [s] : []}`;**value=[] 行为**(协议 SB2):自动渲染一个空 input 行"
+        },
+        "defaultValue": {
+            "type": "array",
+            "itemType": "string",
+            "description": "非受控默认值,与 value 互斥,仅首次 mount 生效"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(val: string[]) => void",
+            "description": "值变更回调,val 是当前所有行的完整数组快照。**业务 string 单值桥接**(协议 SB1):`(val) => setKeyword(val[0] ?? '')`;**val 永远至少 [''])**(协议 SB3);**disabled+受控**仍需传 onChange(空函数避免 warning)"
+        },
+        "fetchSuggestions": {
+            "type": "function",
+            "signature": "(val: string, cb: (data: any[]) => void) => void",
+            "description": "自动补全数据源,存在时每行 input 启用联想。cb 数据可为 string[](直接显示)或 {label, value}[](按 label 显示)"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用整组输入,可配合 disabledTooltip 解释原因"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "必填(透传到 Label 显示星号)"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "placeholder": {
+            "type": "ReactNode",
+            "description": "每行 input 占位"
+        },
+        "helperText": {
+            "type": "ReactNode | ReactNode[]",
+            "description": "错误文本,单值=所有行共享;数组=按行下标对应,空串项表示该行无错"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用态下添加按钮的 tooltip 配置(仅 disabled=true 时生效)"
+        },
+        "otherProps": {
+            "type": "(index: number, val: string) => TextFieldProps",
+            "description": "每行 TextField 的额外 props;index 是行下标(0-based),返回对象展开到该行 TextField"
+        }
+    },
+    "crossPropInteractions": [
+        "value=[] / [''] = 渲染一个空 input 行(自动归一化)",
+        "业务 string ↔ SingleBox string[] 桥接 = 入站 [s] + 出站 val[0] ?? ''(协议 SB1)",
+        "disabled=true = 隐藏添加/删除按钮 + 所有 input 只读;受控仍需传 onChange",
+        "helperText[] 按行下标对应 + value[] 行数 = 错误信息可逐行显示",
+        "fetchSuggestions + otherProps = 联想 + 按行定制(如某行 maxLength)"
+    ],
+    "commonMisconceptions": [
+        "❌ SingleBox 是单值输入框 — 实际 value 是 string[](多行)",
+        "❌ value=[] 不显示输入框 — 自动渲染一个空 input 行",
+        "❌ 删除所有行后 onChange 给 [] — 实际最少 [''](组件保留一行)",
+        "❌ disabled+受控可省略 onChange — 仍需传(空函数)避免 React warning",
+        "❌ 业务 string 直接传 value — 必须 [s] 包装,onChange 取 val[0]"
+    ],
+    "do": [
+        "支持自动完成",
+        "提供建议列表",
+        "业务单值场景用 [s] 包装 value + (val) => val[0] ?? '' 出站桥接"
+    ],
+    "dont": [
+        "建议列表过长",
+        "忽略去重",
+        "把 SingleBox 当单值 TextField 用(它是多值列表,建议用 TextField)"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "val 是所有行当前值的完整数组快照，如 ['keyword1', 'keyword2', '']",
+                "业务单值桥接：onChange={(val) => setSingleKeyword(val[0] ?? '')}",
+                "删除最后一行后 val 仍是 ['']（保留至少一行空 input）"
+            ],
+            "commonMistakes": [
+                "期望删除所有行后 onChange 返回 [] ——组件保留最少一行，val 永远是 [''] 或更多",
+                "disabled+受控时省略 onChange——仍需传（可传空函数）否则 React 报 prop 变化 warning",
+                "业务 string 直接传 value——必须 [s] 包装，onChange 取 val[0] ?? ''"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "value 类型是 string[]，传单个 string 报 TS 类型不兼容",
+            "wrong": "value={keyword}  // keyword: string，TS 报不兼容 string[]",
+            "right": "value={keyword ? [keyword] : ['']}  // 桥接：string → string[]"
+        },
+        {
+            "issue": "helperText 传数组时数组下标必须与 value 数组行数对齐",
+            "wrong": "value={['a','b']} helperText={['err0']}  // 仅第 0 行报错，第 1 行错误无文案但不会静默",
+            "right": "value={['a','b']} helperText={['err0', 'err1']}  // 按行下标一一对应"
+        },
+        {
+            "issue": "otherProps 函数需要返回完整 TextFieldProps 对象，类型不对会扩散到每行 TextField",
+            "wrong": "otherProps={(i) => i === 0 ? { maxLength: 10 } : null}  // null 不满足 TextFieldProps",
+            "right": "otherProps={(i) => i === 0 ? { maxLength: 10 } : {}}  // 非目标行返回空对象"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SingleBox",
+        "adapter": null
+    }
+}

package/Slider/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Slider",
+    "category": "Data Entry",
+    "description": "滑动输入条，用于在给定范围内选择一个值或范围",
+    "semantic": {
+        "intent": [
+            "数值调节",
+            "范围选择",
+            "模糊输入"
+        ],
+        "useCases": [
+            "音量调节",
+            "价格筛选",
+            "亮度调整"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "单滑块"
+        },
+        "range": {
+            "meaning": "双滑块范围选择"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "number | number[]",
+            "description": "当前取值；range 模式下传 [min, max] 数组"
+        },
+        "defaultValue": {
+            "type": "number | number[]",
+            "description": "默认取值"
+        },
+        "min": {
+            "type": "number",
+            "default": 0,
+            "description": "最小值"
+        },
+        "max": {
+            "type": "number",
+            "default": 100,
+            "description": "最大值"
+        },
+        "step": {
+            "type": "number",
+            "default": 1,
+            "description": "步长"
+        },
+        "range": {
+            "type": "boolean | { draggableTrack?: boolean }",
+            "description": "双滑块模式（核心 prop）；传 true 时 value 变为 [min, max] 数组；传 { draggableTrack: true } 时允许拖拽整段轨道",
+            "default": false,
+            "required": false
+        },
+        "vertical": {
+            "type": "boolean",
+            "description": "垂直方向",
+            "default": false,
+            "required": false
+        },
+        "dots": {
+            "type": "boolean",
+            "description": "是否只能拖拽到刻度上（配合 marks 使用）",
+            "default": false,
+            "required": false
+        },
+        "tipFormatter": {
+            "type": "function",
+            "signature": "(value: number) => ReactNode | null",
+            "description": "格式化 Tooltip 显示；传 null 隐藏 Tooltip",
+            "required": false
+        },
+        "onAfterChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "mouseup 时触发；与 onChange 区别：onChange 是拖拽过程中实时触发，onAfterChange 仅在释放后触发一次",
+            "required": false
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "值改变回调（拖拽过程实时触发）；range 模式下 value 是 [min, max] 数组"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "marks": {
+            "type": "object",
+            "objectShape": {
+                "[number]": { "type": "string | ReactNode", "description": "刻度值 → 显示标签，例：{ 0: '0°C', 26: '26°C', 100: '100°C' }" }
+            },
+            "completeExample": "{ 0: '0°C', 26: '26°C', 37: '37°C', 100: { style: { color: '#f50' }, label: <strong>100°C</strong> } }",
+            "description": "刻度标记"
+        },
+        "tooltipVisible": {
+            "type": "boolean",
+            "description": "Tooltip 是否可见"
+        },
+        "tooltipPlacement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight"
+            ],
+            "default": "top",
+            "description": "Tooltip 位置"
+        }
+    },
+    "do": [
+        "在需要快速调节数值且对精度要求不高时使用",
+        "使用 marks 辅助用户定位常用值（配合 dots=true 让用户只能拖到刻度位置）",
+        "受控用法：value + onChange 实现受控；range 模式 value 必须是 number[] 数组（[min, max]）",
+        "高精度场景搭配 InputNumber：onChange 实时同步到 InputNumber，onAfterChange 仅在释放后更新"
+    ],
+    "dont": [
+        "在需要极高精度输入的场景单纯依赖 Slider（应配合 InputNumber）",
+        "范围极小（如 0-1）时使用 Slider——步长精度和 UI 交互体验差",
+        "range 模式 value 传单 number 而非 number[]——会导致 rc-slider 报 PropTypes warning 并功能异常"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单滑块：onChange={(val) => setVolume(val as number)}",
+                "范围滑块（range=true）：onChange={(val) => setRange(val as number[])}",
+                "拖拽过程中实时触发，高频触发时应注意性能（可用 onAfterChange 替代）"
+            ],
+            "commonMistakes": [
+                "range 模式期望 value 是单 number——range=true 时 value 始终是 number[2]",
+                "混淆 onChange 和 onAfterChange——onChange 拖拽过程高频触发，onAfterChange 仅 mouseup 时触发一次",
+                "tipFormatter 传 null 后期望 onChange 仍提供 tooltip 展示——null 表示完全隐藏 tooltip"
+            ]
+        },
+        "onAfterChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户释放滑块时触发一次，适合触发网络请求或昂贵计算",
+                "range 模式：value 是 [min, max] 数组"
+            ],
+            "commonMistakes": [
+                "期望 onAfterChange 在拖拽过程中实时触发——只有 mouseup 时才触发，拖拽中用 onChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "range 模式 value/onChange 类型是 number[]，非 range 模式是 number，混用报 TS 错",
+            "wrong": "range value={50} onChange={(v) => setVal(v)}  // range=true 时 v 是 number[]，赋给 number 报错",
+            "right": "range value={[20, 80]} onChange={(v) => setRange(v as number[])}  // range=true 显式 as number[]"
+        },
+        {
+            "issue": "SliderSingleProps 和 SliderRangeProps 是 union 类型，直接展开 props 时 TS 可能报不兼容",
+            "wrong": "const sliderProps: SliderSingleProps = { range: true, value: [0,50] }  // range=true 应用 SliderRangeProps",
+            "right": "const sliderProps: SliderRangeProps = { range: true, value: [0, 50], onChange: (v) => setRange(v) }"
+        },
+        {
+            "issue": "tipFormatter 传 null 和不传的行为不同",
+            "wrong": "tipFormatter={null}  // 期望默认格式化显示——null 表示完全隐藏 tooltip",
+            "right": "tipFormatter={undefined}  // 不传或 undefined 使用内置 toString 格式化；null 隐藏 tooltip"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Slider",
+        "adapter": null
+    }
+}

package/SortBox/component.json

@@ -0,0 +1,108 @@
+{
+    "name": "SortBox",
+    "category": "Data Entry",
+    "description": "排序盒子，支持拖拽排序;每行内置 Drag 图标作为拖拽 handle",
+    "semantic": {
+        "intent": [
+            "拖拽排序",
+            "列表排序"
+        ],
+        "useCases": [
+            "自定义排序",
+            "优先级调整",
+            "列表管理",
+            "待办排序"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "border": {
+            "meaning": "边框样式;每行细边框"
+        },
+        "none": {
+            "meaning": "无样式;清爽布局无边框无背景"
+        },
+        "fill": {
+            "meaning": "填充样式(默认);每行带填充背景"
+        }
+    },
+    "states": [
+        "default",
+        "dragging"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "SortBoxListItemProps[]",
+            "itemSchema": {
+                "render": { "type": "ReactNode", "description": "该行渲染内容（任意 ReactNode，组件内部加 left padding 视觉）" },
+                "id": { "type": "string | number", "description": "建议显式提供，用于 react-sortablejs key 唯一；未提供时 fallback 到数组 index" }
+            },
+            "description": "排序列表数据;SortBoxListItemProps 是开放接口(src/SortBox/index.tsx:13 已 export):render?: ReactNode(该行渲染内容) + 任意扩展字段 [name]: unknown(挂业务模型,如 _todo / _card);id 字段建议显式提供(string|number),未提供时 src handleList line 82-84 用 array index fallback"
+        },
+        "onSort": {
+            "type": "function",
+            "signature": "(list: SortBoxListItemProps[]) => void",
+            "description": "排序变化回调;⚠️ list 参数 = 【排序后的完整数组】,不是 sort 映射对象 / 不是 diff;src/SortBox/index.tsx:78 实证。业务侧从 list 项的扩展字段(如 _todo)取回业务模型透传父组件"
+        },
+        "type": {
+            "type": "'border' | 'none' | 'fill'",
+            "values": ["border", "none", "fill"],
+            "default": "'fill'",
+            "description": "视觉类型;fill 填充背景 / border 细边框 / none 无视觉装饰"
+        },
+        "marginBottom": {
+            "type": "string",
+            "default": "'10px'",
+            "description": "相邻 sort-item 之间下边距;CSS 单位字符串"
+        }
+    },
+    "do": [
+        "把业务模型挂在 SortBoxListItemProps 扩展字段(如 _todo / _card),onSort 回调中取回",
+        "显式提供 id 字段(string|number,保证 react-sortablejs key 唯一)",
+        "render 字段装载该行 UI(任意 ReactNode,组件内部加 left padding 视觉)",
+        "保存用户排序结果(直接保存 nextList 排序或映射回业务 id 列表)"
+    ],
+    "dont": [
+        "**不要把 onSort 参数当 sort 映射对象用** — 它是排序后的完整数组",
+        "列表项过多(> 100)时性能差(react-sortablejs 限制)",
+        "拖拽 handle 是固定的 .sort-icon 右侧 Drag 图标 — 不要自己实现拖拽逻辑",
+        "不要在 render 内放复杂表单组件(拖拽冲突)"
+    ],
+    "events": {
+        "onSort": {
+            "signature": "(list: SortBoxListItemProps[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "排序结束后触发，list 是排序后的完整数组（新顺序）",
+                "取业务 id 列表：onSort={(newList) => setOrderIds(newList.map(it => it._id))}",
+                "替换父组件 state：onSort={(newList) => setItems(newList)}"
+            ],
+            "commonMistakes": [
+                "把 list 参数当 diff/映射对象用——它是排序后的完整数组，不是变更集合",
+                "不传 onSort 时期望 SortBox 自己维护顺序——SortBox 是受控组件，必须在 onSort 里更新外部 list state",
+                "忘记显式提供 list 项的 id 字段——不提供时 fallback 到 index，拖拽后 React key 可能冲突"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "SortBoxListItemProps 索引签名允许任意字段，但 render 字段是 ReactNode 不是 string",
+            "wrong": "list={[{ render: 'plain text', id: 1 }]}  // render 是 ReactNode，但 TS 接受 string（因为 ReactNode 包含 string）",
+            "right": "list={[{ render: <span>内容</span>, id: 1 }]}  // 推荐传 ReactNode 而非纯字符串"
+        },
+        {
+            "issue": "onSort 返回的 list 是同一个数组（splice 就地修改后复制），直接赋给受控 list 可能引发渲染问题",
+            "wrong": "onSort={(newList) => setList(newList)}  // newList 是就地修改后的扩展数组",
+            "right": "onSort={(newList) => setList([...newList])}  // 解构保证新引用触发重渲"
+        },
+        {
+            "issue": "SortBoxProps 的 list 类型是 SortBoxListItemProps[]，扩展字段类型是 unknown",
+            "wrong": "onSort={(newList) => console.log(newList[0].myField.name)}  // unknown 类型，.name 报错",
+            "right": "onSort={(newList) => { const item = newList[0] as MyItem; console.log(item.myField.name); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SortBox",
+        "adapter": null
+    }
+}

package/Status/component.json

@@ -0,0 +1,104 @@
+{
+    "name": "Status",
+    "category": "Data Display",
+    "description": "状态标签，用于展示状态信息",
+    "semantic": {
+        "intent": [
+            "状态展示",
+            "信息标记"
+        ],
+        "useCases": [
+            "任务状态",
+            "审批状态",
+            "系统状态"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "info": {
+            "meaning": "信息"
+        },
+        "success": {
+            "meaning": "成功"
+        },
+        "warning": {
+            "meaning": "警告"
+        },
+        "error": {
+            "meaning": "错误"
+        },
+        "completed": {
+            "meaning": "完成"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "status": {
+            "type": "enum",
+            "values": [
+                "info",
+                "success",
+                "warning",
+                "error",
+                "completed"
+            ],
+            "default": "info",
+            "description": "状态"
+        },
+        "text": {
+            "type": "ReactNode",
+            "description": "文本"
+        },
+        "icon": {
+            "type": "ReactNode | 'success' | 'error'",
+            "description": "自定义状态图标（src/Status/index.tsx:23 实证：`ReactNode | iconType`，iconType = 'success' | 'error'——传字符串 'success'/'error' 时渲染内置 SVG 图标，传 ReactNode 时直接渲染；**icon 存在时 status 样式类不生效**，src:37 `status && !icon && ...` 实证）"
+        },
+        "color": {
+            "type": "string",
+            "description": "自定义状态圆点颜色（src/Status/index.tsx:29,67-73 实证）。⚠️ **仅在未传 icon 时生效**（默认圆点模式）：传任意合法 CSS 颜色值（hex/rgb/色名），渲染为原色实心圆点 + 0.1 alpha 光晕背景；不传时由 status 对应预设 CSS 类控制颜色"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Status/index.tsx:25 interface 声明，透传到根 span 元素）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Status/index.tsx:27 interface 声明，透传到根 span 元素）"
+        }
+    },
+    "do": [
+        "使用语义化的颜色（info/success/warning/error/completed 对应不同预设圆点颜色）",
+        "保持状态文案简短（status-text 无宽度限制，过长影响布局）",
+        "自定义颜色时用 color prop 传 CSS 色值（hex/rgb/名称）——组件自动生成 0.1 alpha 光晕背景",
+        "需要图标型 Status 时传 icon='success' 或 icon='error' 使用内置 SVG；传 ReactNode 显示自定义图标"
+    ],
+    "dont": [
+        "状态颜色混乱（不同语义用了相同颜色导致用户混淆）",
+        "**不要同时传 icon 和 status**——icon 存在时 status 对应的 CSS 样式类不追加（src:37 实证 `status && !icon`），两者视觉上会冲突",
+        "不要把 icon 传 'warning'/'info'/'completed' 字符串——内置 icon 只有 'success' 和 'error' 两种，传其他字符串渲染 null"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "icon prop 类型是 ReactNode | 'success' | 'error'，传其他字符串（如 'warning'）TS 可能不报错但运行时渲染 null",
+            "wrong": "icon='warning'  // 字符串不在 iconType 枚举内，switch 走 default 分支返回 null",
+            "right": "icon={<WarningIcon />}  // 传 ReactNode；内置字符串仅 'success' | 'error'"
+        },
+        {
+            "issue": "status 和 icon 同时传时 status 样式类不生效（src:37 条件 `status && !icon`）",
+            "wrong": "<Status status='error' icon={<CustomIcon />} />  // 期望 error 颜色，实际 status class 未追加",
+            "right": "<Status icon={<CustomIcon />} />  // 纯自定义图标时只传 icon；需要预设色时只传 status"
+        },
+        {
+            "issue": "color prop 仅在未传 icon 时生效（圆点模式），传 icon 后 color 无视觉效果",
+            "wrong": "<Status icon='success' color='#ff0000' />  // 图标模式 color 不影响图标颜色",
+            "right": "<Status status='error' color='#ff0000' />  // color 在圆点模式（无 icon）下生效"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Status",
+        "adapter": null
+    }
+}