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

package/AGENTS.md

@@ -0,0 +1,315 @@
+# @para-ui/core AI 使用指南
+
+本文档帮助 AI 工具（Cursor、Claude Code 等）正确使用 @para-ui/core 组件库。
+
+## 🚨 必查 Top 9 高频陷阱（写代码前必读，不分组件）
+
+**M5 + combo baseline 实证**：以下 9 个陷阱在多轮实验中是主要失败模式。**忽略其中任何一个 = 概率失败一个 task**。
+
+| # | 陷阱 | 错误 | 正确 |
+|---|------|------|------|
+| 1 | **Message 命令式 API import** | `import { Message } from '@para-ui/core'` → 拿到 JSX 组件，`Message.success()` 运行时报错 | `import { Message } from '@para-ui/core/Message'`（子路径） |
+| 2 | **Table 列定义字段名** | `<Table columns={[{title, dataIndex}]} />`（antd 风格） | `<Table headData={[{name, label, width}]} rowKey="id" />`（headData 不是 columns；render 第一参是 row 不是 value） |
+| 3 | **Form configList 类型** | `<Form configList={undefined} />` → TS2345 | `<Form configList={list \|\| []} />` 或 `''` |
+| 4 | **Form 不接受 ref** | `<Form ref={formRef} />` → TS2322 | `<Form form={formRef} />`（form prop，不是 ref） |
+| 5 | **Upload onChange 参数** | `onChange={({fileList, file}) => ...}` → TS2339 | `onChange={(files: UploadFile[]) => ...}`（参数就是数组） |
+| 6 | **rules.validate 大小写** | `{ maxLength, minlength }` → 静默失效 | `{ maxlength, minLength }`（maxlength 小写 L，minLength 驼峰 L） |
+| 7 | **DynamicMultiBox 类型导入** | `import { IConfig } from '@para-ui/core/DynamicMultiBox/interface'` → TS2307 | `import type { IConfig } from '@para-ui/core/DynamicMultiBox'`（不走 /interface 子路径） |
+| 8 | **Button variant 不是 antd 的 type** | `<Button type="primary">` / `type="default"` / `type="text"` → TS2322（type 是 HTML button type） | `<Button variant="contained">` / `variant="outlined"` / `variant="text"`（注意是 `outlined` 不是 `outline`） |
+| 9 | **Table data prop 名** | `<Table rowData={...}>` → TS2322 | `<Table data={...}>`（不是 rowData/dataSource） |
+
+→ **任何 prompt 即使强调"重点 X"，这 9 条也必须先扫一遍**。这是兜底防线，不是"可选优化"。
+
+⚠️ **prompt over-focus 风险**：即使 prompt 说"重点关注 X"，也不要让 over-focus 让你跳过这 9 条。这些是跨组件的全局陷阱，**Button** 和 **Table** 几乎在每个组合场景里都出现，最易被忽视。
+
+---
+
+## 快速开始
+
+安装后，在你的项目配置中（`.cursor/rules` / `CLAUDE.md` / IDE config）加入以下引导，确保 AI 工具优先读取本库的 metadata：
+
+### 对于 Claude Code 用户（CLAUDE.md）
+
+在项目根目录的 `CLAUDE.md` 中，加入：
+
+```
+## @para-ui/core 使用指南
+
+使用本库时：
+1. 优先读 `node_modules/@para-ui/core/AGENTS.md`（本文件）
+2. 查组件 API：读 `node_modules/@para-ui/core/{ComponentName}/component.json`（完整的 metadata）
+3. 或读自动生成的文档：`node_modules/@para-ui/core/dist/components/{ComponentName}.md`（Phase 2 后可用）
+
+查组件时的优先级：
+  1️⃣ component.json（最新、最准）
+  2️⃣ 自动生成的 .md 文档
+  3️⃣ src 的 TypeScript 类型定义（作为最后参考）
+```
+
+### 对于 Cursor 用户（.cursor/rules）
+
+在 `.cursor/rules` 中，加入：
+
+```
+## @para-ui/core 规则
+
+使用 @para-ui/core 组件库时：
+- 优先读 node_modules/@para-ui/core/{ComponentName}/component.json 的 do/dont 和 semantic 字段
+- 不要使用内部 class（以 .paraui-v4- 开头）
+- 受控/非受控模式不要混用
+```
+
+---
+
+## 组件使用规范
+
+### 标准查阅流程
+
+每次使用组件前，按这个顺序查阅：
+
+```
+1. 需要用 Button？
+   → 读 node_modules/@para-ui/core/Button/component.json
+   → 看 idealProps、do、dont、semantic 字段
+   → 参考 do 中的最佳实践
+   → 避免 dont 中的常见错误
+
+2. 组件有多个 variant？
+   → component.json 的 variants 字段列出所有变体
+   → 按 semantic.intent 选择正确的变体
+
+3. 受控 vs 非受控？
+   → 查 component.json 的 semantic 字段
+   → 通常：value + onChange = 受控
+   →      defaultValue / initialValues = 非受控
+```
+
+### 常见规范
+
+#### 禁止使用内部样式 class
+
+❌ **错误**：
+```tsx
+<div className="paraui-v4-button paraui-v4-button--primary">
+  Click me
+</div>
+```
+
+✅ **正确**：
+```tsx
+import { Button } from '@para-ui/core';
+
+<Button variant="primary">
+  Click me
+</Button>
+```
+
+eslint rule `@para-ui/eslint-plugin:no-internal-class` 会自动挡住内部 class 的使用。
+
+#### 受控/非受控不混用
+
+❌ **错误**：
+```tsx
+<Form 
+  initialValues={{ name: '' }}
+  value={values}          {/* ❌ 不要同时用 initialValues 和 value */}
+  onChange={handleChange}
+>
+  ...
+</Form>
+```
+
+✅ **正确**（非受控）：
+```tsx
+<Form initialValues={{ name: '' }}>
+  ...
+</Form>
+```
+
+✅ **正确**（受控）：
+```tsx
+const [values, setValues] = useState({ name: '' });
+
+<Form value={values} onChange={setValues}>
+  ...
+</Form>
+```
+
+#### Modal / 对话框受控示例
+
+✅ **正确**（受控）：
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<>
+  <Button onClick={() => setIsOpen(true)}>打开对话框</Button>
+  <Modal open={isOpen} onClose={() => setIsOpen(false)}>
+    <Modal.Header>标题</Modal.Header>
+    <Modal.Body>内容</Modal.Body>
+  </Modal>
+</>
+```
+
+---
+
+## 工具与命令
+
+### 验证你的代码
+
+在下游项目中，运行 eslint 来检查是否违反 @para-ui/core 规范：
+
+```bash
+npm run lint
+# 或
+npx eslint . --ext .tsx,.ts --plugin @para-ui/eslint-plugin
+```
+
+常见 rule：
+- `@para-ui/no-internal-class` — 禁止内部 class
+- `@para-ui/controlled-defaults` — 禁止受控/非受控混用
+- `@para-ui/no-deprecated-prop` — 废弃 prop 警告
+
+---
+
+## 常见问题
+
+**Q: 如何找到所有可用的组件？**
+
+A: 读 `node_modules/@para-ui/core/dist/llms.txt`（自动生成的组件清单和导航）
+
+**Q: component.json 在哪里？**
+
+A: 每个组件都有：`node_modules/@para-ui/core/{ComponentName}/component.json`
+
+**Q: 如何了解组件的最佳实践（do/dont）？**
+
+A: 读 component.json 的 `do` 和 `dont` 字段，或读自动生成的 `dist/components/{ComponentName}.md`
+
+---
+
+## 更新频率
+
+本文档与组件库版本同步更新。每个新版本的 component.json 都会包含最新的 metadata 和最佳实践。
+
+---
+
+## ⭐ 跨组件工作流模板（v2 新增,Phase 3a M4）
+
+**重要**：写**多组件协作**场景（如 CRUD 列表 / 表单工作流 / 批量操作）前,**必须先读对应工作流模板**。这些模板基于 Para 真实业务代码 + 对照实验失败数据,每个都经 mini-baseline 实测通过。
+
+位置:`node_modules/@para-ui/core/ai-workflows/`
+
+### 10 个工作流（按场景速查）
+
+| 场景 | 文件 | 涉及组件 |
+|------|------|----------|
+| 列表 + 多 Drawer + 操作列 | `01-crud-list-multi-drawer.md` | Table / Drawer / OperateBtn / PopConfirm / Message |
+| RBAC 权限驱动操作列 | `02-rbac-operation-buttons.md` | Table / Tag / OperateBtn |
+| 复杂表单（异步/级联/上传） | `03-complex-form-async-cascade.md` | Form / Select / DatePicker / Upload |
+| 数组字段表单 | `04-array-field-form.md` | DynamicMultiBox / Form |
+| PopConfirm 异步链 / Message 队列 | `05-popconfirm-async-message-queue.md` | PopConfirm / Message / Switch |
+| Modal/Drawer 嵌套 Form | `06-modal-drawer-form-workflow.md` | Modal / Drawer / Form |
+| Search + Filter + Table 三件套 | `07-search-filter-table-trio.md` | Search / Select / DatePicker / Table |
+| 表格高级（排序/编辑/展开/分页） | `08-table-advanced-features.md` | Table（深度用法） |
+| 批量操作 + 导出进度 | `09-batch-operation-export-progress.md` | Table / Modal / Progress / Upload |
+| 跨组件状态联动（Dashboard/切换/撤销） | `10-cross-component-state-coordination.md` | Tabs / Form / Tree |
+
+### 工作流模板结构
+
+每个模板包含:
+1. **何时使用 + 不要用的场景**（决策树）
+2. **错误 vs 正确模式对照表**（提前防 AI 出错）
+3. **完整代码**（120-180 行可运行 TSX）
+4. **5 个真实陷阱详解**（每条 wrong/right 对照 + M2/M3/M4 实证）
+5. **真实参考行号**（指向 Para 团队业务代码）
+
+### 硬约束
+
+- ❌ **不要先写代码再查模板** — 先查模板看是否有现成模式
+- ❌ **不要忽略"错误模式对照"** — 那里列的就是 AI 常犯错
+- ✅ **复制模板代码后,按业务场景改业务名词**（用户/订单/资产等）
+- ✅ **保留所有 typescriptPitfalls 中的"正确写法"**（如 Table 用 headData 不是 columns）
+
+---
+
+## ⚙️ ESLint plugin 手动接入（可选,强烈推荐）
+
+`@para-ui/eslint-plugin` 含 10 条 rule，能自动挡住 AI 写代码时常犯的 @para-ui/core 风格错误（如 `Table.columns`、`Button.type='primary'`、`Message` 主入口 import 等）。M5 实测启用 plugin 后多组件场景准确率 21% → 92%。
+
+**v1.0.0-beta 阶段 plugin 未在 npm 独立发布**。下游用户可通过以下任一方式手动接入：
+
+### 方式 A：本地 `file:` 引用（最直接）
+
+1. clone `@para-ui/core` 仓库到本地任意位置（如 `~/projects/para-ui-core`）
+2. 在你项目的 `package.json` 加：
+
+```json
+{
+  "devDependencies": {
+    "@para-ui/eslint-plugin": "file:~/projects/para-ui-core/packages/eslint-plugin-para-ui"
+  }
+}
+```
+
+3. `npm install`
+
+### 方式 B：tgz 包
+
+```bash
+# 在 @para-ui/core 仓库内
+cd packages/eslint-plugin-para-ui
+npm pack
+# 生成 para-ui-eslint-plugin-0.1.0.tgz
+
+# 在你项目内
+npm install /path/to/para-ui-eslint-plugin-0.1.0.tgz --save-dev
+```
+
+### `.eslintrc.json` 配置
+
+接入后,在你项目根目录的 `.eslintrc.json` 加：
+
+```json
+{
+  "plugins": ["@para-ui"],
+  "rules": {
+    "@para-ui/no-internal-class": "error",
+    "@para-ui/no-wrong-table-props": "error",
+    "@para-ui/no-wrong-button-type": "error",
+    "@para-ui/no-wrong-table-data": "error",
+    "@para-ui/require-headdata-generic": "error",
+    "@para-ui/require-rowkey": "error",
+    "@para-ui/message-import-from-subpath": "error",
+    "@para-ui/form-use-form-prop-not-ref": "error",
+    "@para-ui/no-deprecated-prop": "warn",
+    "@para-ui/overlay-conventions": "warn"
+  }
+}
+```
+
+**⚠️ `plugins` 字段用短名 `@para-ui`,不是 `@para-ui/eslint-plugin`**（ESLint scoped 包命名约定）。
+
+### 验证
+
+```bash
+npx eslint src/your-file.tsx
+```
+
+如果代码里有 `<Button type="primary">` 这种 antd 风格,会报错：
+
+```
+src/your-file.tsx:10:5 error  Para UI Button 用 variant,不是 type。
+       type="primary" 应该是 variant="contained"  @para-ui/no-wrong-button-type
+```
+
+### 与 IDE 集成
+
+VSCode / Cursor 装了 ESLint 扩展后,**写代码时实时报错**——这是 plugin 真正的价值（AI 写错的瞬间就被挡住）。
+
+### 后续路径
+
+v1.1（如有真实下游需求）将正式发布 `@para-ui/eslint-plugin` 到 npm,届时只需 `npm i -D @para-ui/eslint-plugin` 即可。
+
+---
+
+**最后更新**：2026-05-18

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