@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/es/node_modules/classnames/index.js

@@ -1,4 +1,4 @@
-import { __module as s } from "../../_virtual/index4.js";
+import { __module as s } from "../../_virtual/index2.js";
 var u;
 function c() {
   return u ? s.exports : (u = 1, (function(i) {

package/lib/AlignBox/component.json

@@ -0,0 +1,89 @@
+{
+    "name": "AlignBox",
+    "category": "Layout",
+    "description": "方向语义对齐容器：direction='horizontal'(默认)子元素水平排列+垂直居中；direction='vertical'子元素纵向堆叠+水平居中。根元素为 block 级 flex div，style/className 直接作用于该 flex 容器。",
+    "semantic": {
+        "intent": [
+            "方向对齐",
+            "水平排列容器",
+            "纵向堆叠容器"
+        ],
+        "useCases": [
+            "图标 + 文字 + 标签 一行内水平对齐(direction='horizontal')",
+            "字段纵向堆叠每行一个(direction='vertical')",
+            "卡片内简单的横向元素对齐"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "horizontal": {
+            "meaning": "**子元素水平排列 + 垂直居中** — `display:flex; align-items:center`;子元素按 row 排列,在交叉轴(垂直)居中。默认值。**主轴对齐默认 flex-start**(DEFECT-006):两端对齐 / 居中等需 className 或 style 追加 justify-content"
+        },
+        "vertical": {
+            "meaning": "**子元素纵向堆叠 + 水平居中** — `display:flex; flex-direction:column; align-items:center`;子元素从上到下堆叠,在交叉轴(水平)居中。**⚠️ DEFECT-007：子元素宽度 = 内容宽度**（align-items:center 收缩，非撑满容器）；修复方案：① 给子元素自身加 `width:100%`（推荐）：`<div style={{ width: '100%' }}>内容</div>`；② 或在 AlignBox 上加 `style={{ alignItems: 'stretch' }}` 覆盖。嵌套场景（vertical 包 horizontal）：内层 AlignBox 必须加 `style={{ width: '100%' }}` 才能撑满父容器"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "direction": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "horizontal",
+            "description": "子元素排列方向(字面 = 行为):`horizontal` = 水平排列 + 垂直居中(`display:flex; align-items:center`；主轴对齐默认 flex-start，需要两端对齐用 `style={{ justifyContent: 'space-between' }}`，需要右对齐用 `justifyContent: 'flex-end'`);`vertical` = 纵向堆叠 + 水平居中(`display:flex; flex-direction:column; align-items:center`)。**vertical 模式两个注意点**：① 子元素间**无默认 gap**——需要均匀间距时加 `style={{ gap: '8px' }}`（8px 紧凑 / 12px 标准 / 16px 宽松）；② 子元素**宽度默认收缩至内容宽度**（DEFECT-007，align-items:center 副作用）——若子元素需要撑满父宽度，加 `style={{ alignItems: 'stretch' }}`（整体）或在每个子元素上加 `style={{ width: '100%' }}`（单独控制）。**2026-05-08 跨组件命名 epic §3.3 选项 I 重设计** — 替代旧 `alignType: 'vertical' | 'flex'`(BREAKING-CHANGES §A5)"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "子元素;按 direction 控制的轴向排列"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层根 div 的类名(AlignBox-DEFECT-003:src/AlignBox/index.tsx 实证)。常用于追加自定义样式覆盖,如 `flex-wrap: wrap` / `gap` / `justify-content` 等 direction 未提供的属性"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层根 div 的内联样式(AlignBox-DEFECT-003:src/AlignBox/index.tsx 实证)。**根 div 同时也是 flex 容器**（不存在两层 div 分离），因此 style 可直接传 flexWrap / gap / justifyContent 等 flex 属性，与 className 追加等效。常用示例：`style={{ flexWrap: 'wrap', gap: '8px' }}`（换行 + 间距）；`style={{ justifyContent: 'space-between' }}`（两端对齐）；`style={{ width: '100%' }}`（vertical 模式下覆盖 DEFECT-007 宽度收缩）"
+        }
+    },
+    "do": [
+        "需要『一行内水平排列 + 垂直居中』(图标 + 文字 + 标签)用 direction='horizontal'(默认值,可省略)",
+        "需要『子元素纵向堆叠 + 水平居中』(字段每行一个)用 direction='vertical'",
+        "vertical 模式需要子元素间均匀间距：加 `style={{ gap: '8px' }}`（8px 紧凑 / 12px 标准 / 16px 宽松）——vertical 本身无默认 gap",
+        "vertical 模式需要子元素撑满父宽度（卡片内容、表单字段）：加 `style={{ alignItems: 'stretch' }}`——vertical 子元素默认宽度收缩至内容宽度（DEFECT-007）",
+        "horizontal 需要两端对齐：`style={{ justifyContent: 'space-between', width: '100%' }}`；需要右对齐：`style={{ justifyContent: 'flex-end' }}`——horizontal 默认 flex-start（左对齐）",
+        "需要 wrap / gap / justify-content 等 direction 未提供的 flex 属性，用 **className** 追加 *或* **style 内联**（两种方式等效，因为 style 直接作用于根 flex div）：`style={{ flexWrap: 'wrap', gap: '8px', justifyContent: 'space-between' }}`",
+        "**业务方语义直觉 = direction 字面**:从 v6 开始 horizontal/vertical 即字面对齐 — 不再有命名错位"
+    ],
+    "dont": [
+        "过度嵌套 AlignBox",
+        "替代 CSS Grid/Flexbox 进行复杂布局",
+        "**不要再传旧 prop `alignType`** — 已 BREAKING 移除(BREAKING-CHANGES §A5);从 v5.x 之前升级请按以下映射:旧 `alignType='vertical'`(实为 inline vertical-align middle)→ 新 `direction='horizontal'`(语义最接近);旧 `alignType='flex'`(实为 flex row 居中)→ 新 `direction='horizontal'`(行为完全一致)。要用真正的纵向堆叠请显式传 `direction='vertical'`",
+        "不要假设 `direction='horizontal'` 自动 flex-wrap — src 仅 `display:flex; align-items:center`,无 wrap;要换行请加 className"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "direction 只接受 'horizontal' | 'vertical'，不接受 antd flex 方向字符串",
+            "wrong": "<AlignBox direction='row'>...</AlignBox>  // 'row' 不在联合类型中，TS 报错",
+            "right": "<AlignBox direction='horizontal'>...</AlignBox>  // 水平排列用 'horizontal'"
+        },
+        {
+            "issue": "vertical 模式下子元素宽度默认收缩至内容宽度（align-items:center 副作用），需显式覆盖",
+            "wrong": "<AlignBox direction='vertical'><div className='full-row'>...</div></AlignBox>  // 子 div 宽度收缩，不是撑满",
+            "right": "<AlignBox direction='vertical' style={{ alignItems: 'stretch' }}>...</AlignBox>  // 或在子元素加 style={{ width: '100%' }}"
+        },
+        {
+            "issue": "style 和 className 直接作用于根 flex div，不存在两层 div 分离",
+            "wrong": "// 以为有内外两层 div，试图用 className 覆盖内层 flex 容器\n<AlignBox style={{ display: 'block' }}>...</AlignBox>  // 覆盖 display 会破坏 flex 对齐",
+            "right": "// style 直接透传到根 flex div，追加 flex 属性即可\n<AlignBox style={{ gap: '8px', justifyContent: 'space-between' }}>...</AlignBox>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "AlignBox",
+        "adapter": null
+    }
+}

package/lib/AlignBox/index.css

@@ -1 +1 @@
-@charset "UTF-8";.paraui-v4-align-box.paraui-v4-align-box-vertical *{vertical-align:middle}.paraui-v4-align-box.paraui-v4-align-box-flex{display:flex;align-items:center}
+@charset "UTF-8";.paraui-v4-align-box.paraui-v4-align-box-horizontal{display:flex;align-items:center}.paraui-v4-align-box.paraui-v4-align-box-vertical{display:flex;flex-direction:column;align-items:center}

package/lib/AlignBox/index.d.ts

@@ -4,8 +4,12 @@ export interface AlignBoxProps {
     className?: string;
     /** style */
     style?: React.CSSProperties;
-    /** 对齐方式 默认vertical */
-    alignType?: 'vertical' | 'flex';
+    /**
+     * 子元素排列方向（字面 = 行为，2026-05-08 跨组件命名 epic §3.3 选项 I 重设计）
+     * - 'horizontal'(默认): display:flex; align-items:center — 子元素水平排列、垂直居中
+     * - 'vertical': display:flex; flex-direction:column; align-items:center — 子元素纵向堆叠、水平居中
+     */
+    direction?: 'horizontal' | 'vertical';
     children?: ReactNode;
 }
 declare const AlignBox: FunctionComponent<AlignBoxProps>;

package/lib/AlignBox/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const o=require("../_virtual/jsx-runtime.js"),u=require("clsx"),e=require("../GlobalContext/constant.js");;/* empty css            */const a=s=>{const{className:r,style:t,children:i,alignType:l="vertical",...n}=s;return o.jsxRuntimeExports.jsx("div",{className:u(`${e.$prefixCls}-align-box ${e.$prefixCls}-align-box-${l}`,r),style:t,...n,children:i})};exports.default=a;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const l=require("../_virtual/jsx-runtime.js"),u=require("clsx"),e=require("../GlobalContext/constant.js");;/* empty css            */const c=s=>{const{className:r,style:t,children:i,direction:o="horizontal",...n}=s;return l.jsxRuntimeExports.jsx("div",{className:u(`${e.$prefixCls}-align-box ${e.$prefixCls}-align-box-${o}`,r),style:t,...n,children:i})};exports.default=c;
 //# sourceMappingURL=index.js.map

package/lib/AlignBox/style/index.css

@@ -1 +1 @@
-.paraui-v4-align-box.paraui-v4-align-box-vertical *{vertical-align:middle}.paraui-v4-align-box.paraui-v4-align-box-flex{display:flex;align-items:center}
+.paraui-v4-align-box.paraui-v4-align-box-horizontal{display:flex;align-items:center}.paraui-v4-align-box.paraui-v4-align-box-vertical{display:flex;flex-direction:column;align-items:center}

package/lib/Anchor/anchorMenu/index.d.ts

@@ -8,7 +8,8 @@ interface IProps {
     isTree?: boolean;
     anchorMap?: AnchorMap;
     setAnchorMap?: (map: AnchorMap) => void;
-    customPrefixIcon?: React.ReactNode;
+    /** R6 §6 类型放宽:静态 ReactNode 或函数形式 (item, isActive) => ReactNode */
+    customPrefixIcon?: React.ReactNode | ((item: AnchorItem, isActive: boolean) => React.ReactNode);
     onlyOneLevel?: boolean;
 }
 declare const AnchorMenu: (props: IProps) => import("react/jsx-runtime").JSX.Element;

package/lib/Anchor/anchorMenu/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"),o=require("react"),g=require("clsx"),q=require("../../node_modules/@para-ui/icons/Down/index.js");;/* empty css            */const k=require("../../AutoTips/index.js"),p=a=>{const{data:t,currentAnchorId:h,handleClick:l,level:c=0,isTree:u=!1,anchorMap:i={},setAnchorMap:E,customPrefixIcon:d,onlyOneLevel:v}=a,{id:x}=t,R=String(x)===String(h);o.useEffect(()=>{},[]);const M=o.useMemo(()=>{const n=[];for(let s=0;s<c;s++)n.push(e.jsxRuntimeExports.jsx("div",{className:"indent"},s));return n},[c]),m=(n,s)=>{n.stopPropagation();const r=i[s];r.expanded=!r.expanded,E?.({...i})},N=o.useMemo(()=>{const{name:n,id:s}=t,r=t.children&&t.children.length>0,f=u?r?e.jsxRuntimeExports.jsx("div",{className:"btn-down",onClick:j=>m(j,s),children:e.jsxRuntimeExports.jsx("div",{className:"icon icon-down",children:e.jsxRuntimeExports.jsx(q.Down,{})})}):e.jsxRuntimeExports.jsx("div",{className:"icon mr-6"}):d||e.jsxRuntimeExports.jsx(A,{});return e.jsxRuntimeExports.jsxs("div",{className:"item-content",onClick:j=>{},children:[f,e.jsxRuntimeExports.jsx("div",{className:"title",onClick:()=>l?.(s),children:e.jsxRuntimeExports.jsx(k.default,{children:n||""})})]})},[t,i,m,l,d,u]);return e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsxs("div",{className:g("anchor-menu-item",{active:R,expanded:i?.[x]?.expanded}),children:[M,N]}),t.children&&i?.[x]?.expanded&&!v&&t.children.map(n=>o.createElement(p,{...a,data:n,key:n?.id,level:c+1}))]})},A=()=>e.jsxRuntimeExports.jsx("div",{className:"icon mr-6",children:e.jsxRuntimeExports.jsx("div",{className:"icon-point"})});exports.default=p;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../../_virtual/jsx-runtime.js"),c=require("react"),g=require("clsx"),q=require("../../node_modules/@para-ui/icons/Down/index.js");;/* empty css            */const k=require("../../AutoTips/index.js"),h=l=>{const{data:s,currentAnchorId:E,handleClick:u,level:d=0,isTree:m=!1,anchorMap:i={},setAnchorMap:v,customPrefixIcon:o,onlyOneLevel:R}=l,{id:x}=s,a=String(x)===String(E);c.useEffect(()=>{},[]);const f=c.useMemo(()=>{const n=[];for(let t=0;t<d;t++)n.push(e.jsxRuntimeExports.jsx("div",{className:"indent"},t));return n},[d]),j=(n,t)=>{n.stopPropagation();const r=i[t];r.expanded=!r.expanded,v?.({...i})},M=c.useMemo(()=>{const{name:n,id:t}=s,r=s.children&&s.children.length>0,N=m?r?e.jsxRuntimeExports.jsx("div",{className:"btn-down",onClick:p=>j(p,t),children:e.jsxRuntimeExports.jsx("div",{className:"icon icon-down",children:e.jsxRuntimeExports.jsx(q.Down,{})})}):e.jsxRuntimeExports.jsx("div",{className:"icon mr-6"}):o?typeof o=="function"?o(s,a):o:e.jsxRuntimeExports.jsx(A,{});return e.jsxRuntimeExports.jsxs("div",{className:"item-content",onClick:p=>{},children:[N,e.jsxRuntimeExports.jsx("div",{className:"title",onClick:()=>u?.(t),children:e.jsxRuntimeExports.jsx(k.default,{children:n||""})})]})},[s,i,j,u,o,m,a]);return e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsxs("div",{className:g("anchor-menu-item",{active:a,expanded:i?.[x]?.expanded}),children:[f,M]}),s.children&&i?.[x]?.expanded&&!R&&s.children.map(n=>c.createElement(h,{...l,data:n,key:n?.id,level:d+1}))]})},A=()=>e.jsxRuntimeExports.jsx("div",{className:"icon mr-6",children:e.jsxRuntimeExports.jsx("div",{className:"icon-point"})});exports.default=h;
 //# sourceMappingURL=index.js.map

package/lib/Anchor/component.json

@@ -0,0 +1,130 @@
+{
+    "name": "Anchor",
+    "category": "Navigation",
+    "description": "页面内锚点导航——自动生成目录侧栏并监听内容区滚动高亮目录项，点击目录项内置滚动定位行为。高度约束写在 Anchor 直接父 div 上，无限高度时内部不产生滚动。",
+    "semantic": {
+        "intent": [
+            "快速定位",
+            "内容索引"
+        ],
+        "useCases": [
+            "长文档",
+            "API 文档",
+            "单页应用"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准锚点"
+        }
+    },
+    "states": [
+        "active",
+        "default"
+    ],
+    "idealProps": {
+        "children": {
+            "type": "ReactNode",
+            "description": "内容区，放置带 `id` 属性的各章节 div；Anchor 通过监听滚动位置高亮左侧目录。⚠️ children 是必需的，缺少会导致锚点无法定位",
+            "required": true
+        },
+        "list": {
+            "type": "AnchorItem[]",
+            "typeDefinition": "interface AnchorItem { name: string; id: string; children?: AnchorItem[]; expanded?: boolean }",
+            "description": "目录数据源。**AnchorItem 字段一览（仅 name + id 必填）**：① name: string — 侧栏显示文案；② id: string — 对应 children 内章节 `<div id={item.id}>` 的 DOM id（Anchor 内部用 id 定位高亮，大小写必须精确一致；建议仅用字母/数字/-/_，避免 CSS 选择器特殊字符；若业务数据字段是 href='#intro'，映射时去掉 # 前缀：`id: s.href.replace(/^#/, '')`）；③ children?: AnchorItem[] — 多级嵌套（自动渲染为缩进树，建议 ≤3 级；递归时复用同一映射函数）；④ expanded?: boolean — 该项初始展开态（default false；⚠️ 与 allExpanded prop 完全独立：allExpanded 控制顶部「全部展开」按钮可见性，不等于初始全展开；初始全展开需对每个含 children 的 AnchorItem 设 expanded:true）。完整 TS 定义：interface AnchorItem { name: string; id: string; children?: AnchorItem[]; expanded?: boolean }（parentId 是 Anchor 内部字段，业务传 list 时无需提供）。"
+        },
+        "scrollId": {
+            "type": "string",
+            "default": "\"paraui-v4-anchor-scroll-id\"",
+            "description": "**Anchor 内部自动创建的滚动容器 DOM id**——业务方只需传一个全局唯一字符串，Anchor 会在渲染时自动创建 `<div id={scrollId}>` 并把 children 放入其中；**不需要在 children 外部或内部手动创建该 div**。Anchor 对此 div 监听 scroll 事件 + 用 `[id]` 选择器定位高亮目录项。单页只有一个 Anchor 时可省略（默认 'paraui-v4-anchor-scroll-id'）；同页多个 Anchor 实例必须各自传不同的 scrollId 以隔离滚动监听。scrollId 查找：Anchor 内部用 `document.getElementById(scrollId)` 获取滚动容器——正常渲染后此 div 必然存在，无需业务方手动创建。"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "目录标题；只有传 title 才显示折叠按钮 / 全部展开按钮 / search 搜索框。**(R6 §6 类型放宽:从 string → ReactNode)**——支持嵌入徽标 / 计数 / 动态状态文本(如 `<span>目录<Tag>当前: intro</Tag></span>`)。string 是 ReactNode 子集,完全向后兼容旧 string 用法。详见 BREAKING-CHANGES §维护规则边界(类型 widening 不入档)+ discussions/Anchor-title-reactnode.md"
+        },
+        "placement": {
+            "type": "'left' | 'right'",
+            "values": ["left", "right"],
+            "default": "'right'",
+            "description": "目录位于内容的左侧还是右侧。⚠️ 默认 'right'（目录在右侧）；要实现左侧目录须显式传 placement='left'"
+        },
+        "search": {
+            "type": "boolean",
+            "default": false,
+            "description": "目录是否带搜索框（按 name 模糊匹配）。需配合 title 使用。"
+        },
+        "allExpanded": {
+            "type": "boolean",
+            "default": true,
+            "description": "顶部『全部展开』按钮是否启用（控制按钮可见性，不影响 `list[].expanded` 的初始值）。仅在 list 含 children 且传了 title 时生效。\n\n**⚠️ 命名歧义警告（R15+R16 双轮再现 · 3/6 sub-agent 混淆）**：allExpanded 命名容易被理解为「初始全展开」（类似 defaultExpandAll），但实际含义是「全部展开」**按钮**的可见性控制开关：\n- `allExpanded=true`（默认）→ 顶部出现「全部展开」按钮，用户**点击按钮后**才展开全部目录项\n- `allExpanded=false` → 隐藏「全部展开」按钮\n- **若要初始全展开（组件挂载即全展开）**：对 list[] 中每个含 children 的 AnchorItem 设置 `expanded: true`，与 allExpanded prop 无关\n\n**R17 路线图**：正在评审 src rename `allExpanded → expandedAll`（BREAKING，更准确地表达「控制展开按钮」含义），详见 `discussions/Anchor-allExpanded-naming-epic.md`；R17 拍板前 allExpanded 继续有效，0 BREAKING。"
+        },
+        "listWidth": {
+            "type": "number",
+            "description": "目录列表宽度（px）；不传时默认 140px。"
+        },
+        "customPrefixIcon": {
+            "type": "ReactNode | ((item: AnchorItem, isActive: boolean) => ReactNode)",
+            "description": "自定义目录每项的前缀图标。**(R6 §6 类型放宽:从 ReactNode → ReactNode | function)**:<br>- **静态 ReactNode** — 所有目录项共用同一前缀图标(原行为,完全向后兼容)<br>- **函数形式 `(item, isActive) => ReactNode`** — 按当前激活态返回不同 ReactNode(墨水点指示器 / 激活态指示符 / 复选框联动等);函数版每次激活变化触发 list 重渲染,内部 AnchorListMemo 已优化。<br>**初始激活态说明**：页面 mount 时 Anchor 不主动激活任何目录项——需要用户滚动（或点击）触发第一次 scroll 事件后才会激活；初始激活项由滚动位置决定（内部算法：找第一个 offsetTop >= scrollTop 的 [id] 元素）。若需要初始激活特定项，可在 mount 后手动调用 `document.getElementById(SCROLL_ID)?.dispatchEvent(new Event('scroll'))` 触发一次。<br>**业务方仍可走激活态 CSS 联动**(向后兼容):Anchor 内部对激活目录项加 className `.anchor-menu-item.active`(无 prefixCls 前缀,见 src/Anchor/anchorMenu/index.scss:14);可在外层 style 选择器 `:global(.anchor-menu-item.active) [data-ink-dot] { visibility: visible }` 联动。但函数形式更直接、类型安全。详见 discussions/Anchor-customPrefixIcon-function.md(R6 实施选项 B 类型 widening)"
+        }
+    },
+    "do": [
+        "在长页面（如文档）右侧提供 Anchor",
+        "Anchor 标题应简洁",
+        "把章节 DOM 作为 children 直接传入：`<Anchor list={list} scrollId='xxx'>{sections.map(s => <div id={s.id}>...</div>)}</Anchor>`",
+        "list[].id 必须与 children 中对应章节 div 的 id 完全一致（含大小写）；建议仅使用 CSS selector 安全字符",
+        "业务侧 `{ href, title }` 数据派生 list 时使用 `sections.map(s => ({ name: s.title, id: s.href.replace(/^#/, '') }))` 映射；多级数据写递归映射函数（参见 docs/view/anchor/codeString.ts hrefMappingDemo / nestedMappingDemo）",
+        "Anchor 内部滚动容器需要由父级提供有限高度（如 `style={{ height: 400 }}` 或外层 wrapper 设 `height: 100vh`）才能产生滚动；外层高度无限时内容不会滚动，stickyDemo 也无法体现『内容滚动而目录吸顶』效果",
+        "需要把激活 id 还原成业务 href 时：用 useEffect 监听 activeId 变化 + 业务侧维护 id->href 反向 map（参见 codeString.ts notifyParentDemo）",
+        "需要『吸顶 / 滚动偏移头部 / 激活回调』时：用外层 div 包 `position: sticky; top: 0` 实现吸顶（**前置条件：外层必须有滚动祖先——body 高度 > 视口、或某 wrapper 设了 `overflow:auto/scroll`；⚠️ `overflow:auto/scroll` 是合法滚动祖先，不会导致 sticky 失效——仅 `overflow:hidden` 的祖先会使 sticky 退化为 relative；flex 容器中配合 `alignSelf: flex-start` 避免 stretch 拉满高度**；缺少任一条件则 sticky 退化为 relative）；用 `<section style={{ scrollMarginTop: headerOffset }}>` **写在每个章节元素自身** 实现偏移；用容器自定义 `addEventListener('scroll', ...)` 计算激活章节并 onChange 通知父组件——这些不是 Anchor 内置能力"
+    ],
+    "dont": [
+        "Anchor 嵌套层级过深 (>3级) —— 设计/视觉建议；src 实现层 formatList 递归无硬限制，违反仅触发缩进过深视觉异常",
+        "内容过少的页面使用 Anchor",
+        "不要传 `targetOffset` / `affix` / `showInkInFixed` / `onChange` / `items` / `onClick` 等 prop——这些 prop 在 AnchorProps 中不存在，传入会被 React 忽略且能力不会生效",
+        "不要在 children 内再包一层 `<div id={scrollId}>` 自管理滚动——Anchor 已内部包了 `<div id={scrollId}>`",
+        "不要把 `scrollPaddingTop` 写在 children 内的 wrapper 上——`scrollPaddingTop` 仅对滚动容器生效（即 Anchor 内部 `<div id={scrollId}>`，外部无法直接访问）；偏移请用 `scrollMarginTop` 写在**每个章节元素自身**上"
+    ],
+    "events": {
+        "onClickItem (via AnchorMenu internal)": {
+            "signature": "内部点击目录项时调用 handleClick(id: string)，无外部事件 prop",
+            "asyncSupported": false,
+            "examples": [
+                "点击目录项时 Anchor 内部调用 scrollTo 滚动到对应章节，无需业务方处理",
+                "需要监听激活变化时，用外层 wrapper 的 addEventListener('scroll', ...) 计算当前 id",
+                "需要把 activeId 回传父组件：用 useEffect 监听 scrollId 容器的 scroll 事件 + 业务侧 id→href 反向 map"
+            ],
+            "commonMistakes": [
+                "传 onChange prop 期望激活目录项变化时被回调——Anchor 不存在 onChange prop",
+                "传 onClick prop 期望拦截目录项点击——AnchorProps 无此 prop，传入会被 React 忽略",
+                "期望 customPrefixIcon 在点击瞬间触发回调——它只是渲染函数，激活态变化驱动重渲染"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "AnchorItem 无法从 @para-ui/core/Anchor 直接命名导出——Anchor/index.tsx 只有默认导出，AnchorItem 定义在 Anchor/type.ts",
+            "wrong": "import type { AnchorItem } from '@para-ui/core/Anchor';  // TS2614: 无此命名导出",
+            "right": "import type { AnchorItem } from '@para-ui/core/Anchor/type';  // 从 type.ts 子路径导入"
+        },
+        {
+            "issue": "AnchorItem 的 id 必须与 children 内章节 div 的 DOM id 完全一致（大小写敏感）",
+            "wrong": "// list: [{ name: '介绍', id: 'Introduction' }]\n// children: <div id='introduction'>  // 大小写不同，无法高亮",
+            "right": "// 保持一致且使用 CSS selector 安全字符\n// list: [{ name: '介绍', id: 'introduction' }]\n// children: <div id='introduction'>..."
+        },
+        {
+            "issue": "title prop 从 string 扩宽到 ReactNode，但 allExpanded 是控制按钮可见性，不是初始全展开",
+            "wrong": "// 以为 allExpanded=true 会初始展开所有目录项\n<Anchor allExpanded={true} list={tree} />  // 实际只是显示'全部展开'按钮",
+            "right": "// 初始全展开需要对每个含 children 的 AnchorItem 设 expanded: true\nconst tree = data.map(item => ({ ...item, expanded: true, children: item.children?.map(c => ({ ...c, expanded: true })) }))"
+        },
+        {
+            "issue": "customPrefixIcon 函数形式的参数类型必须显式标注，避免 noImplicitAny 报错",
+            "wrong": "// 内联函数不标注类型\n<Anchor customPrefixIcon={(item, isActive) => <span />} />  // TS7006: item 隐式 any",
+            "right": "import type { AnchorItem } from '@para-ui/core/Anchor';\n<Anchor customPrefixIcon={(item: AnchorItem, isActive: boolean) => <span style={{ color: isActive ? 'blue' : 'gray' }}>•</span>} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Anchor",
+        "adapter": null
+    }
+}

package/lib/Anchor/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),n=require("react"),y=require("clsx"),S=require("../GlobalContext/constant.js"),Q=require("./anchorMenu/index.js"),B=require("../node_modules/@para-ui/icons/ToRight/index.js"),F=require("../node_modules/@para-ui/icons/ToLeft/index.js"),U=require("../node_modules/@para-ui/icons/PreviewOpen/index.js"),X=require("../Search/index.js"),Y=require("../GlobalContext/useFormatMessage.js"),Z=require("./lang/index.js"),_=require("@paraview/lib");;/* empty css            */const ee=q=>{const{style:W,className:z,title:E="",scrollId:R=`${S.$prefixCls}-anchor-scroll-id`,list:d=[],listClassName:I,scrollClassName:D,placement:i="right",allExpanded:G=!0,search:H=!1,customPrefixIcon:$,listWidth:p}=q,J=Y.default("Anchor",Z.default),[C,L]=n.useState(""),[m,K]=n.useState(!1),[h,g]=n.useState({}),[T,M]=n.useState(!1),[N,O]=n.useState(""),[f,v]=n.useState(null),o=n.useRef({currentAnchorId:"",anchorList:d,anchorMap:{},searchValue:"",scrolling:!1}),V=T?"50px":p?`${p+20}px`:"160px";n.useEffect(()=>{o.current.anchorList=d;const e={};let r=!1;const c=(x,a="")=>{x.forEach(t=>{(t?.expanded===void 0||t?.expanded===null)&&(t.expanded=!1),a&&(t.parentId=a),e[t.id]=t,t.children&&(r=!0,c(t.children,t.id))})};c(d),K(r),o.current.anchorMap=e,g(e)},[d]),n.useEffect(()=>{const e=document.getElementById(R),r=_.throttle(async()=>{if(o.current.scrolling)return;const c=e?.querySelectorAll("[id]")||[],a=Array.from(c).map(l=>({id:l.id,offsetTop:l.offsetTop-(e?.offsetTop||0)}));let t=0,u="";const A=a.find(l=>(t<l.offsetTop&&(t=l.offsetTop,u=l.id),l.offsetTop>=(e?.scrollTop||0)));if(A?.id!==o.current.currentAnchorId){let l=A?.id||"";e?.scrollTop&&!A?.id&&(l=u),L(l)}},300);return r(),e?.addEventListener("scroll",r,{passive:!0}),()=>{e?.addEventListener("scroll",r)}},[]);const k=e=>{const r=document.getElementById(R),c=r?.querySelectorAll("[id]")||[],x=Array.from(c).findIndex(t=>String(t.id)===String(e)),a=c[x];a&&(L(e),o.current.currentAnchorId=e,o.current.scrolling=!0,setTimeout(()=>{o.current.scrolling=!1},1e3),r?.scrollTo({top:a?.offsetTop||0-(r?.offsetTop||0),behavior:"smooth"}))},b=()=>{Object.keys(h).forEach(e=>{h[e].expanded=!0}),g({...h})},j=n.useMemo(()=>_.debounce(async()=>{const e=o.current.searchValue;if(!e){v(null);return}const r=o.current.anchorList||[],c=[],x=(a,t="")=>{a.forEach(u=>{u?.name?.indexOf(e)>-1&&c.push(u),u.children&&x(u.children,u.id)})};x(r),v(c)},200),[]),w=n.useMemo(()=>E?s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsxs("div",{className:"anchor-menu-title",children:[s.jsxRuntimeExports.jsx("div",{className:"title",children:E}),s.jsxRuntimeExports.jsxs("div",{className:"opera-area",children:[m&&G&&s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsx(U.PreviewOpen,{onClick:b}),s.jsxRuntimeExports.jsx("div",{className:"split-line"})]}),s.jsxRuntimeExports.jsx("div",{onClick:()=>M(!0),children:i==="left"?s.jsxRuntimeExports.jsx(F.ToLeft,{}):s.jsxRuntimeExports.jsx(B.ToRight,{})})]})]}),H&&s.jsxRuntimeExports.jsx(X.Search,{size:"small",value:N,onChange:e=>{O(e),o.current.searchValue=e,j()},onClickRightIcon:j,onEnter:j,onClear:()=>{O(""),o.current.searchValue="",v(null)},placeholder:J("pleaseEnter"),style:{padding:"0 4px",marginBottom:"6px"}})]}):null,[E,m,N,b,j]),P=n.useMemo(()=>{if(!d?.length)return null;if(T)return s.jsxRuntimeExports.jsx("div",{className:"collapse-icon-area",onClick:()=>M(!1),children:i==="left"?s.jsxRuntimeExports.jsx(B.ToRight,{}):s.jsxRuntimeExports.jsx(F.ToLeft,{})});const e=f||d;return s.jsxRuntimeExports.jsxs("div",{className:y("anchor-menu-list",I),style:{width:p?`${p}px`:"140px"},children:[w,e.map((r,c)=>s.jsxRuntimeExports.jsx(Q.default,{data:r,currentAnchorId:C,handleClick:k,isTree:f?!1:m,anchorMap:h,setAnchorMap:g,customPrefixIcon:$,onlyOneLevel:!!f},r?.id))]})},[d,C,I,k,m,w,h,$,T,f]);return s.jsxRuntimeExports.jsxs("div",{className:y(`${S.$prefixCls}-anchor`,z,{[`${S.$prefixCls}-anchor-${i}`]:i}),style:W,children:[i==="left"&&P,s.jsxRuntimeExports.jsx("div",{id:R,className:y("anchor-scroll",D),style:{paddingLeft:i==="left"?V:"0",paddingRight:i==="right"?V:"0"},children:q.children}),i==="right"&&P]})};exports.default=ee;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),n=require("react"),y=require("clsx"),S=require("../GlobalContext/constant.js"),U=require("./anchorMenu/index.js"),F=require("../node_modules/@para-ui/icons/ToRight/index.js"),_=require("../node_modules/@para-ui/icons/ToLeft/index.js"),X=require("../node_modules/@para-ui/icons/PreviewOpen/index.js"),Y=require("../Search/index.js"),Z=require("../GlobalContext/useFormatMessage.js"),ee=require("./lang/index.js"),D=require("@snack-kit/lib");;/* empty css            */const se=q=>{const{style:W,className:z,title:E="",scrollId:R=`${S.$prefixCls}-anchor-scroll-id`,list:d=[],listClassName:I,scrollClassName:G,placement:i="right",allExpanded:H=!0,search:J=!1,customPrefixIcon:C,listWidth:p}=q,K=Z.default("Anchor",ee.default),[L,M]=n.useState(""),[m,Q]=n.useState(!1),[h,g]=n.useState({}),[T,$]=n.useState(!1),[N,O]=n.useState(""),[f,v]=n.useState(null),o=n.useRef({currentAnchorId:"",anchorList:d,anchorMap:{},searchValue:"",scrolling:!1}),V=T?"50px":p?`${p+20}px`:"160px";n.useEffect(()=>{o.current.anchorList=d;const e={};let r=!1;const c=(x,l="")=>{x.forEach(t=>{(t?.expanded===void 0||t?.expanded===null)&&(t.expanded=!1),l&&(t.parentId=l),e[t.id]=t,t.children&&(r=!0,c(t.children,t.id))})};c(d),Q(r),o.current.anchorMap=e,g(e)},[d]),n.useEffect(()=>{const e=document.getElementById(R),r=D.Throttle(async()=>{if(o.current.scrolling)return;const c=e?.querySelectorAll("[id]")||[],l=Array.from(c).map(a=>{const B=a;return{id:B.id,offsetTop:B.offsetTop-(e?.offsetTop||0)}});let t=0,u="";const A=l.find(a=>(t<a.offsetTop&&(t=a.offsetTop,u=a.id),a.offsetTop>=(e?.scrollTop||0)));if(A?.id!==o.current.currentAnchorId){let a=A?.id||"";e?.scrollTop&&!A?.id&&(a=u),M(a)}},300);return r(),e?.addEventListener("scroll",r,{passive:!0}),()=>{e?.addEventListener("scroll",r)}},[]);const b=e=>{const r=document.getElementById(R),c=r?.querySelectorAll("[id]")||[],x=Array.from(c).findIndex(t=>String(t.id)===String(e)),l=c[x];l&&(M(e),o.current.currentAnchorId=e,o.current.scrolling=!0,setTimeout(()=>{o.current.scrolling=!1},1e3),r?.scrollTo({top:l?.offsetTop||0-(r?.offsetTop||0),behavior:"smooth"}))},k=()=>{Object.keys(h).forEach(e=>{h[e].expanded=!0}),g({...h})},j=n.useMemo(()=>D.Debounce(async()=>{const e=o.current.searchValue;if(!e){v(null);return}const r=o.current.anchorList||[],c=[],x=(l,t="")=>{l.forEach(u=>{u?.name?.indexOf(e)>-1&&c.push(u),u.children&&x(u.children,u.id)})};x(r),v(c)},200),[]),w=n.useMemo(()=>E?s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsxs("div",{className:"anchor-menu-title",children:[s.jsxRuntimeExports.jsx("div",{className:"title",children:E}),s.jsxRuntimeExports.jsxs("div",{className:"opera-area",children:[m&&H&&s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsx(X.PreviewOpen,{onClick:k}),s.jsxRuntimeExports.jsx("div",{className:"split-line"})]}),s.jsxRuntimeExports.jsx("div",{onClick:()=>$(!0),children:i==="left"?s.jsxRuntimeExports.jsx(_.ToLeft,{}):s.jsxRuntimeExports.jsx(F.ToRight,{})})]})]}),J&&s.jsxRuntimeExports.jsx(Y.Search,{size:"small",value:N,onChange:e=>{O(e),o.current.searchValue=e,j()},onClickRightIcon:j,onEnter:j,onClear:()=>{O(""),o.current.searchValue="",v(null)},placeholder:K("pleaseEnter"),style:{padding:"0 4px",marginBottom:"6px"}})]}):null,[E,m,N,k,j]),P=n.useMemo(()=>{if(!d?.length)return null;if(T)return s.jsxRuntimeExports.jsx("div",{className:"collapse-icon-area",onClick:()=>$(!1),children:i==="left"?s.jsxRuntimeExports.jsx(F.ToRight,{}):s.jsxRuntimeExports.jsx(_.ToLeft,{})});const e=f||d;return s.jsxRuntimeExports.jsxs("div",{className:y("anchor-menu-list",I),style:{width:p?`${p}px`:"140px"},children:[w,e.map((r,c)=>s.jsxRuntimeExports.jsx(U.default,{data:r,currentAnchorId:L,handleClick:b,isTree:f?!1:m,anchorMap:h,setAnchorMap:g,customPrefixIcon:C,onlyOneLevel:!!f},r?.id))]})},[d,L,I,b,m,w,h,C,T,f]);return s.jsxRuntimeExports.jsxs("div",{className:y(`${S.$prefixCls}-anchor`,z,{[`${S.$prefixCls}-anchor-${i}`]:i}),style:W,children:[i==="left"&&P,s.jsxRuntimeExports.jsx("div",{id:R,className:y("anchor-scroll",G),style:{paddingLeft:i==="left"?V:"0",paddingRight:i==="right"?V:"0"},children:q.children}),i==="right"&&P]})};exports.default=se;
 //# sourceMappingURL=index.js.map

package/lib/Anchor/type.d.ts

@@ -18,8 +18,8 @@ export interface AnchorProps {
     style?: React.CSSProperties;
     /** 类名 */
     className?: string;
-    /** 标题 */
-    title?: string;
+    /** 标题(R6 §6 类型放宽:string → ReactNode,支持嵌入徽标/计数/动态状态文本;string 是 ReactNode 子集,完全向后兼容) */
+    title?: ReactNode;
     /** 滚动盒子Id */
     scrollId?: string;
     /** 子元素 */
@@ -31,8 +31,12 @@ export interface AnchorProps {
     /** 位置 */
     placement?: 'left' | 'right';
     /** 默认展示的锚点 */
-    /** 自定义前缀符号 */
-    customPrefixIcon?: ReactNode;
+    /**
+     * 自定义前缀符号(R6 §6 类型放宽):
+     * - 静态 ReactNode — 所有目录项共用同一前缀图标(原行为)
+     * - 函数形式 `(item, isActive) => ReactNode` — 按当前激活态返回不同 ReactNode(墨水点指示器等激活态联动场景);函数版本每次激活变化触发 list 重渲染,内部 AnchorListMemo 已优化
+     */
+    customPrefixIcon?: ReactNode | ((item: AnchorItem, isActive: boolean) => ReactNode);
     /** 全部展开功能是否开启 */
     allExpanded?: boolean;
     /** 是否带目录搜索 */

package/lib/Argv/component.json

@@ -0,0 +1,216 @@
+{
+    "name": "Argv",
+    "category": "Data Entry",
+    "description": "动态参数键值对编辑器。用户可以增删行、编辑每行的 key/value,value 支持多类型(string/number/boolean/object)。典型场景:命令行参数配置、环境变量编辑、动态配置项。**重要:这是一个'对象 ⇄ 列表'双形态组件,内部数据形态是 IArgvItem[],外部数据形态可以是对象(Record<string,any>)或列表(IArgvItem[]),通过两套不同的 prop 通道分别接入(见 controlledChannels)**",
+    "semantic": {
+        "intent": [
+            "动态键值对编辑",
+            "参数配置",
+            "可增删行的表单"
+        ],
+        "useCases": [
+            "命令行参数配置面板(CLI argv 编辑)",
+            "环境变量编辑器(KEY=VALUE 列表)",
+            "HTTP Header / Query 参数编辑",
+            "动态配置项编辑(配置中心场景)",
+            "脚本变量定义"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**双形态受控对**:外部可用 **对象形态**(defaultValue: Record<string,any> + onChange: (val: Record<string,any>) => void,**onChange 防抖 200ms**)或 **列表形态**(list: IArgvItem[] + onListChange: (val: IArgvItem[]) => void,**无防抖**)接入数据。defaultValue 仅 mount + 引用变化时灌入(不受控);list 是受控通道(每次变化都会被同步)。两套通道可同时存在(各自独立 fire)。**无 value/values prop,无 schema/argSchema prop——这是常见误解**",
+    "controlledChannels": {
+        "objectMode": {
+            "in": "defaultValue: Record<string, any>",
+            "out": "onChange: (val: Record<string, any>) => void",
+            "behavior": "**非受控**:defaultValue 引用变化时(useEffect 依赖)重置内部 state,父层 setState 后再传入相同引用不会重置。onChange 内部 200ms 防抖,返回值已经 formatDataToObject 转成普通对象(丢弃空 key 项)",
+            "whenToUse": "外部数据天然是对象(API 返回的 config 对象、env vars 对象),且不需要严格受控(用户编辑过程中父层不需要插队覆盖)"
+        },
+        "listMode": {
+            "in": "list: IArgvItem[]",
+            "out": "onListChange: (val: IArgvItem[]) => void",
+            "behavior": "**受控**:list 每次变化都会被同步进内部 state(useEffect 依赖 list 引用)。onListChange 无防抖,每次按键 / 增删行立即 fire,返回原始 IArgvItem[](保留空 key 项,保留类型元数据)",
+            "whenToUse": "需要保留输入过程中间态(空 key 行、未填值)、需要保留类型元数据(dataType=string/number/boolean/object)、或父层做严格受控(每次输入都过父层 reducer)"
+        },
+        "bothModes": "list 和 defaultValue 可以同时传(list 会覆盖 defaultValue 的初始化效果);onChange 和 onListChange 可同时监听,两个回调都会触发,**但 onChange 因防抖会延迟 200ms 且只回传对象形态**"
+    },
+    "dataFlow": {
+        "objectToList": "**formatObjectToData(obj: Record<string,any>): IArgvItem[]** — Object.keys 遍历, 每个 [k,v] 转换成 IArgvItem(自动推断 dataType: typeof v)。导出函数,可在父层提前调用",
+        "listToObject": "**formatDataToObject(list: IArgvItem[]): Record<string,any>** — 遍历 list, 跳过 item.key 为空的项, 用 item.key 作为对象 key, formatGeneratorToData 还原 value。导出函数",
+        "validate": "**checkArgvData(list: IArgvItem[], intl: Function): { error: boolean, detail: Record<string,string>[] }** — 校验每行 key 非空 + value 格式正确,返回的 detail 可以直接喂给 errors prop"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换,样式由 size/disabled 等控制)"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "IArgvItem[]",
+            "description": "**受控形态的数据通道**。每项结构: `{ key: string, data: IDataGeneratorValue }`,其中 `IDataGeneratorValue = { dataType: 'string' | 'number' | 'boolean' | 'object', data: any }`。**与 onListChange 配对使用,无防抖**。如果同时传了 defaultValue,list 优先级更高(list 引用变化会覆盖)",
+            "shape": {
+                "key": "string — 参数名(显示在左侧 TextField)。允许空字符串,但 formatDataToObject 转对象时会被跳过",
+                "data": "IDataGeneratorValue — 参数值容器,含 dataType (类型选择器) + data (实际值,类型与 dataType 联动)"
+            }
+        },
+        "onListChange": {
+            "type": "(val: IArgvItem[]) => void",
+            "description": "**列表形态变化回调,无防抖**。每次按键 / 增删行 / 类型切换都立即触发。返回完整 IArgvItem[](保留空 key 项)。如果只想拿对象形态结果,用 onChange",
+            "pairsWith": "list"
+        },
+        "defaultValue": {
+            "type": "Record<string, any>",
+            "description": "**对象形态的初始值,非受控**。组件 mount 时 + 引用变化时(useEffect 依赖)灌入,父层用 setState 重新传相同引用不会重置(常见坑:误以为 defaultValue 是受控,见 commonMisconceptions.M1)。内部用 formatObjectToData 自动推断每个 value 的 dataType",
+            "controlled": false
+        },
+        "onChange": {
+            "type": "(val: Record<string, any>) => void",
+            "description": "**对象形态变化回调,内部 200ms 防抖**。返回值已经 formatDataToObject 转成普通对象(item.key 空的行被跳过, item.data 还原成对应 dataType 的原始值)。**适合保存到 state 但不适合做严格受控**(防抖期间输入和 state 不同步)",
+            "pairsWith": "defaultValue"
+        },
+        "errors": {
+            "type": "Record<string, string>[]",
+            "description": "**按 list 行索引对齐**(errors[0] 对应 list[0],以此类推)。**不是按 key 名映射**(常见误解,见 commonMisconceptions.M3)。每项结构 `{ key?: string, value?: string }`: `key` 字段填非空字符串时,该行左侧 TextField 红框 + 显示该字符串作为 helperText;`value` 字段填非空字符串时,该行右侧 DataGenerator 红框 + 显示该字符串。如不需要某行/某列显示错误就不填或填空字符串",
+            "shape": {
+                "[index].key": "string | undefined — 该行 key 列的错误文案(空字符串/undefined = 无错误)",
+                "[index].value": "string | undefined — 该行 value 列的错误文案"
+            },
+            "tip": "直接消费 checkArgvData(list, intl).detail 即可,无需手工拼装"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "**整体禁用**:禁用所有 TextField + DataGenerator,屏蔽新增按钮(点击 add 时 early return)、屏蔽删除按钮(点击 del 时 early return)。不存在子字段单独禁用——若需更细颗粒度,改用底层 TextField + DataGenerator 自行编排"
+        },
+        "label": {
+            "type": "LabelProps['label']",
+            "description": "顶部标题文本(string 或 ReactNode)。不传时显示 i18n 默认值('环境变量' / 'Environment Variable')。注意这是顶层 label,**不是每行的 label**(每行只有 key/value 两个 TextField,无独立 label 位)"
+        },
+        "labelProps": {
+            "type": "LabelProps",
+            "description": "传给顶部 Label 组件的完整 props(覆盖默认 label),用于调整 required / tooltip / labelWidth 等。`label` 字段会被外层 label prop 覆盖(外层优先)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 div 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 div 的 style"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 defaultValue 当受控 prop 用: `<Argv defaultValue={state} onChange={setState} />` 期望父层 setState 后 Argv 内部跟着更新",
+            "result": "defaultValue 只在引用变化时灌入,父层 setState 后 React 重渲传入新引用确实会重置——但**正在编辑的行会被清空**(useEffect 重跑 formatObjectToData),导致用户输入丢失",
+            "fix": "需要严格受控就用 **list + onListChange**(列表形态、受控、无防抖);只需保存最终结果用 defaultValue + onChange(对象形态、非受控、防抖)。**不要混用**"
+        },
+        "M2": {
+            "wrong": "想给 Argv 传 schema / argSchema 限制可选 key 列表或字段类型: `<Argv schema={...} />`",
+            "result": "Argv **不存在 schema / argSchema prop**——传入会被 TypeScript 直接报错。Argv 是自由键值对编辑器,没有内置 schema 约束",
+            "fix": "需要约束 key 白名单:在父层 onListChange 里过滤;需要约束 value 类型:Argv 内部已有 DataGenerator 让用户选 dataType(string/number/boolean/object);需要强 schema(必填 + 正则等):换用 FieldForm + FieldForm.Item rules"
+        },
+        "M3": {
+            "wrong": "errors 按 key 名映射: `errors={{ username: '必填', email: '格式错' }}` (Record<string,string>)",
+            "result": "类型不匹配——errors 是 `Record<string, string>[]` 数组,**按 list 行索引对齐**,不是按字段名映射。传错形态会导致 errors[index] 取值为 undefined,所有行都不显示错误",
+            "fix": "用 `errors={[{key: '', value: '必填'}, {key: '重复', value: ''}]}` 或直接 `errors={checkArgvData(list, intl).detail}`(detail 已经是正确形态)"
+        },
+        "M4": {
+            "wrong": "想用 `value` / `values` prop 做受控: `<Argv value={data} onChange={setData} />`",
+            "result": "Argv **无 value 也无 values prop**——TypeScript 报错。常见的受控套路在 Argv 上不直接成立",
+            "fix": "Argv 的受控通道叫 **list + onListChange**(命名上 list 替代了 value 角色,IArgvItem[] 替代了 普通对象)。如果父层数据是普通对象,可以在父层用 formatObjectToData / formatDataToObject 工具函数转换"
+        },
+        "M5": {
+            "wrong": "同时监听 onChange 和 onListChange 并期望它们的回调时机一致",
+            "result": "**onListChange 立即触发,onChange 防抖 200ms**——按键过程中两个 callback 看到的数据可能短暂不一致,且 onChange 收到的是对象形态(过滤了空 key 项),onListChange 收到的是列表形态(保留全部)",
+            "fix": "通常只监听一个:严格受控用 onListChange,只关心最终对象结果用 onChange。如必须两个都监听,理解 200ms 时差是预期行为"
+        }
+    },
+    "completeExample": "// 标准用法:list 受控模式 + errors 校验\nimport React, { useState, useMemo } from 'react';\nimport Argv, { IArgvItem, checkArgvData } from '@para-ui/core/Argv';\nimport useFormatMessage from '@para-ui/core/GlobalContext/useFormatMessage';\n\nconst Demo: React.FC = () => {\n    const [list, setList] = useState<IArgvItem[]>([\n        { key: 'NODE_ENV', data: { dataType: 'string', data: 'production' } },\n        { key: 'PORT', data: { dataType: 'number', data: 3000 } },\n        { key: 'DEBUG', data: { dataType: 'boolean', data: false } }\n    ]);\n    const intl = useFormatMessage('Argv');\n    // 校验:返回 { error: boolean, detail: errors 形态 }\n    const validation = useMemo(() => checkArgvData(list, intl), [list, intl]);\n    return (\n        <div>\n            <Argv\n                label='环境变量配置'\n                list={list}\n                onListChange={setList}\n                errors={validation.detail}\n            />\n            <button disabled={validation.error}>保存</button>\n        </div>\n    );\n};\nexport default Demo;",
+    "utilities": {
+        "formatObjectToData": {
+            "import": "import { formatObjectToData } from '@para-ui/core/Argv';",
+            "signature": "(data: Record<string, any>) => IArgvItem[]",
+            "purpose": "把普通对象转成 IArgvItem[](自动推断 dataType)。父层有对象形态数据但想用 list 受控通道时用"
+        },
+        "formatDataToObject": {
+            "import": "import { formatDataToObject } from '@para-ui/core/Argv';",
+            "signature": "(data: IArgvItem[]) => Record<string, any>",
+            "purpose": "把 IArgvItem[] 转回普通对象(跳过空 key,还原 dataType)。保存到后端时用"
+        },
+        "checkArgvData": {
+            "import": "import { checkArgvData } from '@para-ui/core/Argv';",
+            "signature": "(data: IArgvItem[], intl: Function) => { error: boolean, detail: Record<string,string>[] }",
+            "purpose": "内置校验:每行 key 非空 + value 格式正确。detail 可以直接喂给 errors prop"
+        }
+    },
+    "do": [
+        "需要严格受控(中途插队 / 实时同步):用 **list + onListChange**(列表形态、无防抖)",
+        "只需保存最终结果到父层 state:用 **defaultValue + onChange**(对象形态、200ms 防抖)",
+        "errors 直接消费 **checkArgvData(list, intl).detail**,无需手工拼装",
+        "保存到后端前用 **formatDataToObject(list)** 转成对象形态",
+        "理解'对象 ⇄ 列表'两套通道是平级且独立的,不要混用"
+    ],
+    "dont": [
+        "**不要**给 Argv 传 schema / argSchema / value / values prop——这些都不存在(见 commonMisconceptions M2/M4)",
+        "**不要**把 defaultValue 当受控 prop 用——会导致编辑过程中数据被清空(M1)",
+        "**不要**按 key 名映射 errors——errors 按行索引对齐(M3)",
+        "**不要**期望 onChange 和 onListChange 时机一致——前者有 200ms 防抖(M5)",
+        "参数过多(>10 行)不分组用同一个 Argv——考虑分多个 Argv 或换 FieldForm"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: Record<string, any>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "对象形态回调，内部 200ms 防抖，适合保存到 state 但不适合严格受控",
+                "返回值已经 formatDataToObject 转换，跳过空 key 项，还原 dataType 原始值",
+                "async 场景可直接 await 包裹：const save = async (val) => { await api.save(val); setDirty(false); }"
+            ],
+            "commonMistakes": [
+                "期望 onChange 和 onListChange 在同一帧触发——onChange 有 200ms 防抖，onListChange 立即触发，两者不同步",
+                "期望 onChange 回传 IArgvItem[] 列表形态——onChange 返回普通对象 Record<string,any>，要列表形态用 onListChange",
+                "把 onChange 当受控 prop 配合 defaultValue 用——defaultValue 非受控，引用不变不触发重置，严格受控用 list+onListChange"
+            ]
+        },
+        "onListChange": {
+            "signature": "(val: IArgvItem[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "每次按键 / 增删行 / 类型切换立即触发，无防抖，适合严格受控场景",
+                "返回完整 IArgvItem[]（保留空 key 行），可直接回传给 list prop 实现受控循环",
+                "结合 checkArgvData 做实时校验：onListChange={val => { setList(val); setErrors(checkArgvData(val, intl).detail); }}"
+            ],
+            "commonMistakes": [
+                "期望 onListChange 返回对象形态——它返回 IArgvItem[]，要对象形态用 onChange 或 formatDataToObject",
+                "onListChange 频率比 onChange 高，如果 handler 有重计算逻辑应加 useMemo/useCallback 避免性能问题",
+                "同时传 list 和 defaultValue 但期望 onListChange 只触发一次——list 引用变化会触发，defaultValue 也会灌入，两套通道独立"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "errors prop 是按行索引对齐的数组，不是按 key 名映射的对象",
+            "wrong": "// 错误：按字段名映射\n<Argv errors={{ NODE_ENV: '必填', PORT: '格式错' }} />  // TS 类型报错：期望数组",
+            "right": "// 正确：按 list 行索引对齐\n<Argv errors={[{ key: '', value: '必填' }, { key: '重复', value: '' }]} />\n// 或直接消费 checkArgvData 结果\n<Argv errors={checkArgvData(list, intl).detail} />"
+        },
+        {
+            "issue": "Argv 无 value / values prop，受控通道叫 list + onListChange",
+            "wrong": "// antd/MUI 风格受控写法\n<Argv value={data} onChange={setData} />  // TS 报错：value 不在 ArgvProps",
+            "right": "// para-ui Argv 受控写法\n<Argv list={list} onListChange={setList} />"
+        },
+        {
+            "issue": "IArgvItem.data.dataType 是字符串联合类型，不能传任意字符串",
+            "wrong": "const item: IArgvItem = { key: 'PORT', data: { dataType: 'int', data: 3000 } };  // 'int' 不在联合类型",
+            "right": "const item: IArgvItem = { key: 'PORT', data: { dataType: 'number', data: 3000 } };  // 只有 'string'|'number'|'boolean'|'object'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Argv",
+        "adapter": null
+    }
+}

package/lib/Argv/dataGenerator/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"),u=require("react"),N=require("../../TextField/index.js"),M=require("../../Select/index.js"),y=require("./config.js"),D=require("../../node_modules/@para-ui/icons/ExpandPart/index.js"),w=require("../../InputNumber/index.js"),G=require("../../Modal/index.js"),I=require("../../Message/index.js"),_=require("../../GlobalContext/useFormatMessage.js"),O=require("../lang/index.js"),F=require("@paraview/lib");;/* empty css            */const J=e=>{const{defaultValue:i,value:t,disabled:o,onChange:d,error:p,helperText:f,placeholderTextField:T}=e,E=_.default("Argv",O.default),[s,x]=u.useState({dataType:"string",data:""}),[S,m]=u.useState(!1),[g,j]=u.useState(""),v=u.useRef({dataMapping:{...y.defaultInputValueMapping},uuid:F.UUID()});u.useEffect(()=>{i!==void 0&&x(i)},[]),u.useEffect(()=>{t!==void 0&&x(t)},[t]);const q=a=>{const r=a;if(r!==s.dataType){const h=v.current.dataMapping[r]??"",b={...s,dataType:r,data:h};x(b),d&&d(b)}},c=a=>{const r={...s,data:a};x(r),d&&d(r);const l=s.dataType,h=v.current.dataMapping;h[l]=a},C=u.useMemo(()=>{const{dataType:a,data:r}=s;if(a==="number"){const l=Number(r);return n.jsxRuntimeExports.jsx(w.InputNumber,{placeholder:T,disabled:o,className:"data-input",value:l,onChange:c,error:p,helperText:f})}return a==="boolean"?n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"data-input",list:y.booleanSelectList,value:r,onChange:c,error:p,helperText:f}):n.jsxRuntimeExports.jsx(N.TextField,{placeholder:T,className:"data-input",multiline:!0,value:r,rightIcon:n.jsxRuntimeExports.jsx(D.ExpandPart,{}),onClickIcon:()=>{m(!0),j(r)},onChange:l=>c(l.target.value),rows:1,resize:!1,error:p,helperText:f})},[s,c,p,f]),R=()=>{if(s.dataType==="string"&&(c(g),m(!1)),s.dataType==="object")try{const a=JSON.parse(g);c(g),m(!1)}catch{I.Message.warn(E("formatErrorJson"))}};return n.jsxRuntimeExports.jsxs("div",{className:"argv-data-generator",children:[n.jsxRuntimeExports.jsxs("div",{className:"data-generator-content",children:[n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"datatype-select",list:y.dataTypeSelectList,value:s?.dataType,onChange:q}),C]}),n.jsxRuntimeExports.jsx(G.Modal,{open:S,hideHeader:!0,size:"auto",onCancel:()=>m(!1),onOk:R,children:n.jsxRuntimeExports.jsx("div",{style:{width:"600px",height:"auto",paddingTop:"20px"},children:n.jsxRuntimeExports.jsx(N.TextField,{disabled:o,multiline:!0,rows:12,value:g||"",onChange:a=>j(a.target.value)})})})]})},V=e=>{const{dataType:i,data:t}=e;switch(i){case"number":return!isNaN(Number(t));case"boolean":return!0;case"string":return!0;case"object":try{return JSON.parse(t),!0}catch{return!1}default:return!1}},k=e=>{if(!e)return"";const{dataType:i,data:t}=e;switch(i){case"number":return Number(t);case"boolean":return!!t;case"string":return t;case"object":try{return JSON.parse(t)}catch{return{}}default:return t}},$=e=>typeof e=="number"?{dataType:"number",data:e}:typeof e=="boolean"?{dataType:"boolean",data:e}:typeof e=="string"?{dataType:"string",data:e}:typeof e=="object"?{dataType:"object",data:JSON.stringify(e)}:{dataType:"string",data:""};exports.checkGeneratorData=V;exports.default=J;exports.formatDataToGenerator=$;exports.formatGeneratorToData=k;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../../_virtual/jsx-runtime.js"),u=require("react"),N=require("../../TextField/index.js"),M=require("../../Select/index.js"),y=require("./config.js"),D=require("../../node_modules/@para-ui/icons/ExpandPart/index.js"),w=require("../../InputNumber/index.js"),G=require("../../Modal/index.js"),I=require("../../Message/index.js"),_=require("../../GlobalContext/useFormatMessage.js"),O=require("../lang/index.js"),F=require("@snack-kit/lib");;/* empty css            */const J=e=>{const{defaultValue:i,value:t,disabled:o,onChange:d,error:p,helperText:f,placeholderTextField:T}=e,E=_.default("Argv",O.default),[s,x]=u.useState({dataType:"string",data:""}),[S,m]=u.useState(!1),[g,j]=u.useState(""),b=u.useRef({dataMapping:{...y.defaultInputValueMapping},uuid:F.UUID()});u.useEffect(()=>{i!==void 0&&x(i)},[]),u.useEffect(()=>{t!==void 0&&x(t)},[t]);const q=a=>{const r=a;if(r!==s.dataType){const h=b.current.dataMapping[r]??"",v={...s,dataType:r,data:h};x(v),d&&d(v)}},c=a=>{const r={...s,data:a};x(r),d&&d(r);const l=s.dataType,h=b.current.dataMapping;h[l]=a},C=u.useMemo(()=>{const{dataType:a,data:r}=s;if(a==="number"){const l=Number(r);return n.jsxRuntimeExports.jsx(w.InputNumber,{placeholder:T,disabled:o,className:"data-input",value:l,onChange:c,error:p,helperText:f})}return a==="boolean"?n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"data-input",list:y.booleanSelectList,value:r,onChange:c,error:p,helperText:f}):n.jsxRuntimeExports.jsx(N.TextField,{placeholder:T,className:"data-input",multiline:!0,value:r,rightIcon:n.jsxRuntimeExports.jsx(D.ExpandPart,{}),onClickIcon:()=>{m(!0),j(r)},onChange:l=>c(l.target.value),rows:1,resize:!1,error:p,helperText:f})},[s,c,p,f]),R=()=>{if(s.dataType==="string"&&(c(g),m(!1)),s.dataType==="object")try{const a=JSON.parse(g);c(g),m(!1)}catch{I.Message.warn(E("formatErrorJson"))}};return n.jsxRuntimeExports.jsxs("div",{className:"argv-data-generator",children:[n.jsxRuntimeExports.jsxs("div",{className:"data-generator-content",children:[n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"datatype-select",list:y.dataTypeSelectList,value:s?.dataType,onChange:q}),C]}),n.jsxRuntimeExports.jsx(G.Modal,{open:S,hideHeader:!0,size:"auto",onCancel:()=>m(!1),onOk:R,children:n.jsxRuntimeExports.jsx("div",{style:{width:"600px",height:"auto",paddingTop:"20px"},children:n.jsxRuntimeExports.jsx(N.TextField,{disabled:o,multiline:!0,rows:12,value:g||"",onChange:a=>j(a.target.value)})})})]})},V=e=>{const{dataType:i,data:t}=e;switch(i){case"number":return!isNaN(Number(t));case"boolean":return!0;case"string":return!0;case"object":try{return JSON.parse(t),!0}catch{return!1}default:return!1}},k=e=>{if(!e)return"";const{dataType:i,data:t}=e;switch(i){case"number":return Number(t);case"boolean":return!!t;case"string":return t;case"object":try{return JSON.parse(t)}catch{return{}}default:return t}},z=e=>typeof e=="number"?{dataType:"number",data:e}:typeof e=="boolean"?{dataType:"boolean",data:e}:typeof e=="string"?{dataType:"string",data:e}:typeof e=="object"?{dataType:"object",data:JSON.stringify(e)}:{dataType:"string",data:""};exports.checkGeneratorData=V;exports.default=J;exports.formatDataToGenerator=z;exports.formatGeneratorToData=k;
 //# sourceMappingURL=index.js.map