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

package/ai-workflows/10-cross-component-state-coordination.md

@@ -0,0 +1,412 @@
+# Workflow 10: 跨组件状态联动（Dashboard / 撤销重做 / 状态切换）
+
+> **基于**：console/src/package/Dashboard/src/content.tsx（多 Widget 状态同步）/ console/src/package/Cluster/src/content.tsx（Tabs 驱动状态切换 + 实时刷新）  
+> **覆盖 baseline 失败任务**：Task 25（Dashboard 多组件联动）/ Task 27（撤销重做）/ Task 32（Tabs 状态切换）  
+> **集成 typescriptPitfalls**：Form check() 返回 false|object / Switch loading loadingMap / Tree checkStrictly 类型（M3 修复同款）/ Tabs activeKey onChange / Form ref 类型必须 `useRef<FormRefObject>({} as FormRefObject)`
+
+---
+
+## 何时使用
+
+单个页面中多个独立组件的状态需要协调联动，包括：
+
+```
+Tabs 切换驱动多组件刷新  +  Form 提交状态控制 Switch/Button  +  Tree 勾选同步列表  +  撤销重做栈
+```
+
+**典型业务**：Dashboard 看板 / 角色权限配置（Tree + 表格联动）/ 工作流编辑器（撤销重做）/ 分组切换（Tabs + 列表联动）
+
+**不要用此模板的场景**：
+- 单组件内部状态（无跨组件依赖）→ 用各组件独立模板
+- 全局状态（跨页面）→ 用 Context / Redux
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `const formRef = useRef(null)` → `ref={formRef}` 两处都错 | ✅ **`useRef<FormRefObject>({} as FormRefObject)`** 且用 **`form={formRef}`**（form prop 而非 ref prop）|
+| ❌ `if (!formRef.current.check()) throw new Error(...)` check() 当 boolean 用 | ✅ **`const values = formRef.current.check?.(); if (!values) return; submit(values)`** check() 返回 `false | object` |
+| ❌ Switch loading 用单个 boolean state（多行并发互相覆盖） | ✅ **`loadingMap: Record<string, boolean>`** 每个 Switch 独立 loading 状态 |
+| ❌ Tree `checkStrictly=true` 但 `checkedKeys={keys: Key[]}` 类型不匹配 | ✅ **`checkedKeys={{ checked: keys, halfChecked: halfKeys }}`** checkStrictly=true 时必须传对象形式 |
+| ❌ Tabs `onChange={(value) => setTab(value)}` 混用参数名 | ✅ **`onChange={(activeKey) => setTab(activeKey)}`** 参数名与 API 签名一致 |
+| ❌ Dashboard 多 Widget 用 useEffect 监听数据相互触发 | ✅ **`timer.current` ref + setInterval 独立驱动各 Widget**，停止时统一 clearInterval |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, {
+  FunctionComponent, useState, useRef, useMemo, useCallback, useEffect
+} from 'react';
+import { Tabs, Form, Switch, Tree, Button, Card } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import type { FormRefObject } from '@para-ui/core';
+import type { TabProps } from '@para-ui/core';
+
+// ============================================================
+// 类型定义
+// ============================================================
+
+interface RoleItem {
+  id: string;
+  name: string;
+  permissionCount: number;
+  enabled: boolean;
+}
+
+interface PermTreeNode {
+  key: string;
+  title: string;
+  children?: PermTreeNode[];
+}
+
+type GroupTab = 'all' | 'admin' | 'readonly';
+
+// ============================================================
+// 主组件：跨组件状态联动示例
+// ============================================================
+
+const RolePermissionPage: FunctionComponent = () => {
+  // ── 1. Tabs 状态（驱动下方 Tree 和列表联动）────────────────
+  const [activeGroup, setActiveGroup] = useState<GroupTab>('all');
+
+  // ── 2. Tree 多选状态（checkStrictly 类型陷阱）────────────────
+  const [checkedKeys, setCheckedKeys] = useState<React.Key[]>([]);
+  const [halfCheckedKeys, setHalfCheckedKeys] = useState<React.Key[]>([]);
+  // checkStrictly=true 时 checkedKeys 必须是对象形式，不能是数组
+
+  // ── 3. Form ref（必须显式类型，不能 useRef(null)）────────────
+  // 错误：const formRef = useRef(null) → formRef.current.check() TS 报 unknown
+  // 正确：
+  const formRef = useRef<FormRefObject>({} as FormRefObject);
+
+  // ── 4. Switch loadingMap（多行独立 loading）────────────────
+  const [switchLoadingMap, setSwitchLoadingMap] = useState<Record<string, boolean>>({});
+
+  // ── 5. 撤销重做栈 ──────────────────────────────────────────
+  const [history, setHistory] = useState<React.Key[][]>([[]]);
+  const [historyIndex, setHistoryIndex] = useState<number>(0);
+
+  const pushHistory = (keys: React.Key[]): void => {
+    const newHistory = history.slice(0, historyIndex + 1);
+    newHistory.push([...keys]);
+    setHistory(newHistory);
+    setHistoryIndex(newHistory.length - 1);
+  };
+
+  const undo = (): void => {
+    if (historyIndex <= 0) return;
+    const newIndex = historyIndex - 1;
+    setHistoryIndex(newIndex);
+    setCheckedKeys(history[newIndex]);
+  };
+
+  const redo = (): void => {
+    if (historyIndex >= history.length - 1) return;
+    const newIndex = historyIndex + 1;
+    setHistoryIndex(newIndex);
+    setCheckedKeys(history[newIndex]);
+  };
+
+  // ── 6. Tabs 切换 → 清空 Tree 选择 + 刷新列表 ─────────────────
+  // onChange 参数名用 activeKey 与 API 签名一致（不要用 value）
+  const handleTabChange = (activeKey: string): void => {
+    setActiveGroup(activeKey as GroupTab);
+    setCheckedKeys([]);    // Tabs 切换时清空 Tree 选择
+    setHalfCheckedKeys([]);
+    pushHistory([]);       // 记录初始空状态到历史栈
+  };
+
+  // ── 7. Tree onCheck（checkStrictly 类型处理）─────────────────
+  const handleTreeCheck = (
+    keys: React.Key[] | { checked: React.Key[]; halfChecked: React.Key[] }
+  ): void => {
+    // checkStrictly=false 时 keys 是 Key[]；checkStrictly=true 时是对象
+    const checkedArr = Array.isArray(keys) ? keys : keys.checked;
+    const halfArr = Array.isArray(keys) ? [] : keys.halfChecked;
+    setCheckedKeys(checkedArr);
+    setHalfCheckedKeys(halfArr);
+    pushHistory(checkedArr);   // 每次勾选变化压栈
+  };
+
+  // ── 8. Switch 行内切换（loadingMap 避免并发干扰）─────────────
+  const handleToggleRole = async (role: RoleItem): Promise<void> => {
+    setSwitchLoadingMap(prev => ({ ...prev, [role.id]: true }));
+    try {
+      await mockApi.toggleRole(role.id, !role.enabled);
+      Message.success(`已${role.enabled ? '停用' : '启用'} ${role.name}`);
+    } finally {
+      setSwitchLoadingMap(prev => ({ ...prev, [role.id]: false }));
+    }
+  };
+
+  // ── 9. Form 提交（check() 返回 false | object，不是 boolean）─
+  const handleSavePermissions = async (): Promise<void> => {
+    // check() 返回 false（失败）或 values 对象（成功），不抛异常
+    const values = formRef.current.check?.();
+    if (!values) return;   // false 表示验证失败，直接 return
+    // values 是包含表单字段的对象
+    await mockApi.savePermissions({
+      group: activeGroup,
+      permissions: checkedKeys,
+      remark: (values as Record<string, unknown>).remark as string
+    });
+    Message.success('权限保存成功');
+  };
+
+  // ── 10. Tabs 数据 ──────────────────────────────────────────
+  const tabsData = useMemo<TabProps<GroupTab>[]>(() => [
+    { value: 'all', label: '全部角色' },
+    { value: 'admin', label: '管理员' },
+    { value: 'readonly', label: '只读角色' }
+  ], []);
+
+  // ── 11. Tabs 驱动的 Tree 数据（按 activeGroup 过滤）──────────
+  const treeData: PermTreeNode[] = useMemo(() => {
+    // 实际项目里按 activeGroup 过滤权限树
+    return mockPermTree.filter(node =>
+      activeGroup === 'all' || node.key.startsWith(activeGroup)
+    );
+  }, [activeGroup]);
+
+  return (
+    <div style={{ display: 'flex', gap: 24 }}>
+      {/* 左侧：Tabs + Tree */}
+      <div style={{ width: 280, flexShrink: 0 }}>
+        <Tabs<GroupTab>
+          data={tabsData}
+          activeKey={activeGroup}
+          // onChange 参数名 activeKey 与 API 一致
+          onChange={(activeKey) => handleTabChange(activeKey)}
+        />
+
+        <div style={{ margin: '16px 0 8px', display: 'flex', gap: 8 }}>
+          <Button
+            size="small"
+            disabled={historyIndex <= 0}
+            onClick={undo}
+          >
+            撤销
+          </Button>
+          <Button
+            size="small"
+            disabled={historyIndex >= history.length - 1}
+            onClick={redo}
+          >
+            重做
+          </Button>
+        </div>
+
+        {/* Tree checkStrictly=true 时 checkedKeys 必须是对象形式 */}
+        <Tree
+          treeData={treeData}
+          checkable={true}
+          checkStrictly={true}
+          checkedKeys={{ checked: checkedKeys, halfChecked: halfCheckedKeys }}
+          onCheck={handleTreeCheck}
+        />
+      </div>
+
+      {/* 右侧：角色列表 + Form 保存 */}
+      <div style={{ flex: 1 }}>
+        {mockRoles
+          .filter(r => activeGroup === 'all' || r.id.startsWith(activeGroup))
+          .map(role => (
+            <Card key={role.id} style={{ marginBottom: 12 }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+                <span>{role.name}</span>
+                <span style={{ color: '#999', fontSize: 12 }}>
+                  {role.permissionCount} 个权限
+                </span>
+                {/* Switch loading 用 loadingMap，每行独立互不干扰 */}
+                <Switch
+                  checked={role.enabled}
+                  loading={switchLoadingMap[role.id] ?? false}
+                  onChange={() => handleToggleRole(role)}
+                />
+              </div>
+            </Card>
+          ))
+        }
+
+        {/* Form：命令式 API 通过 form prop 传 ref（不是 ref prop，Form 不是 forwardRef 组件）*/}
+        <Form
+          form={formRef}
+          configList={[
+            {
+              name: 'remark',
+              label: '备注',
+              InputType: 'text',   // InputType 不是 type（type 是布局覆盖）
+              rules: { validate: { required: false } }  // required 在 rules.validate 下
+            }
+          ]}
+        />
+
+        <div style={{ marginTop: 16, display: 'flex', gap: 8 }}>
+          <Button onClick={handleSavePermissions}>
+            保存权限（已选 {checkedKeys.length} 项）
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default RolePermissionPage;
+
+// === 占位 Mock ===
+const mockPermTree: PermTreeNode[] = [
+  { key: 'admin-read', title: '管理员只读' },
+  { key: 'admin-write', title: '管理员读写' },
+  { key: 'readonly-view', title: '只读查看' }
+];
+const mockRoles: RoleItem[] = [
+  { id: 'admin-1', name: '超级管理员', permissionCount: 24, enabled: true },
+  { id: 'readonly-1', name: '审计员', permissionCount: 6, enabled: false }
+];
+const mockApi = {
+  toggleRole: async (id: string, enabled: boolean): Promise<void> => { void id; void enabled; },
+  savePermissions: async (data: {
+    group: string; permissions: React.Key[]; remark?: string
+  }): Promise<void> => { void data; }
+};
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：Form ref 类型写错 + 用 ref prop 而非 form prop
+
+```tsx
+// 错（最高频 Form 陷阱，M3 Stage 修复实证）
+const formRef = useRef(null);
+formRef.current?.check();
+// TS 报错：类型"null"上不存在属性"check"
+
+// 错（错误的泛型）
+const formRef = useRef<HTMLElement>(null);
+formRef.current?.check();
+// TS 报错：类型"HTMLElement"上不存在属性"check"
+
+// 错（Form 不是 forwardRef 组件，不接受 ref prop）
+<Form ref={formRef} configList={...} />
+// TS 报错：Property 'ref' does not exist on type 'IntrinsicAttributes & FormProps'
+
+// 对：用 FormRefObject + form prop（不是 ref prop）
+import type { FormRefObject } from '@para-ui/core';
+const formRef = useRef<FormRefObject>({} as FormRefObject);
+<Form form={formRef} configList={...} />  // form prop 接收 ref，不是 ref prop
+formRef.current?.check();  // 正确，有类型提示
+```
+
+### ❌ 陷阱 2：check() 返回值当 boolean 用 → 丢失表单数据
+
+```tsx
+// 错（check() 不是 boolean，是 false | object）
+const ok: boolean = formRef.current.check?.() as boolean;
+if (!ok) return;
+submit({ data: '硬编码' });  // 丢失了 check() 返回的表单值
+
+// 错（当 boolean 判断 + 取值分离，两次调用）
+if (!formRef.current.check?.()) return;
+const values = formRef.current.getData?.();  // getData 不存在
+
+// 对：check() 返回 false 表失败，返回 object 表成功并含字段值
+const values = formRef.current.check?.();
+if (!values) return;          // false 或 undefined → 验证失败
+submit(values as Record<string, unknown>);  // values 就是表单字段对象
+```
+
+### ❌ 陷阱 3：Tree checkStrictly=true 但 checkedKeys 传数组（M3 修复同款）
+
+```tsx
+// 错（checkStrictly=true 时 checkedKeys 必须是 { checked, halfChecked } 对象）
+<Tree
+  checkStrictly={true}
+  checkedKeys={selectedKeys}   // TS: Key[] 不匹配 {checked: Key[]; halfChecked: Key[]}
+  onCheck={(keys) => setSelectedKeys(keys as React.Key[])}
+  // keys 实际是 {checked,halfChecked} 对象，强转为 Key[] 会出错
+/>
+
+// 对
+<Tree
+  checkStrictly={true}
+  checkedKeys={{ checked: checkedKeys, halfChecked: halfCheckedKeys }}
+  onCheck={(keys) => {
+    // keys 类型随 checkStrictly 变化，必须判断
+    const arr = Array.isArray(keys) ? keys : keys.checked;
+    setCheckedKeys(arr);
+  }}
+/>
+```
+
+### ❌ 陷阱 4：Tabs onChange 参数名混用导致语义混乱
+
+```tsx
+// 错（参数名 value 与 API 签名 activeKey 不一致，运行正确但误导）
+<Tabs
+  data={tabsData}
+  activeKey={currentTab}
+  onChange={(value) => {
+    setCurrentTab(value);   // value 实际是 activeKey，命名混乱
+  }}
+/>
+
+// 对（参数名与 API 一致）
+<Tabs
+  data={tabsData}
+  activeKey={currentTab}
+  onChange={(activeKey) => {
+    setCurrentTab(activeKey as GroupTab);
+  }}
+/>
+
+// 另一个 Tabs 陷阱：data 是 TabProps[] 不是 antd 的 items
+// data={[{ value: 'home', label: '首页', content: <Home /> }]}
+// 不是 items={[{ key: 'home', label: '首页', children: <Home /> }]}
+```
+
+### ❌ 陷阱 5：Dashboard 多 Widget 用 useEffect 监听相互触发死循环
+
+```tsx
+// 错（多组件状态互相监听，容易触发死循环或闪烁）
+useEffect(() => {
+  fetchWidgetA(activeGroup).then(setDataA);
+}, [activeGroup, dataB]);   // dataB 变化又触发 fetchWidgetA，形成环
+
+// 对（Dashboard/content.tsx 实证）：各 Widget 独立用 timer ref 驱动
+const timer = useRef<Record<string, NodeJS.Timeout>>({});
+
+const startPolling = () => {
+  timer.current.widgetA = setInterval(() => fetchWidgetA(), 5000);
+  timer.current.widgetB = setInterval(() => fetchWidgetB(), 10000);
+};
+
+const stopPolling = () => {
+  Object.keys(timer.current).forEach(key => clearInterval(timer.current[key]));
+};
+
+useEffect(() => {
+  startPolling();
+  return stopPolling;   // 组件卸载时统一清理
+}, [activeGroup]);      // 只依赖 activeGroup，不依赖 data
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**
+
+| 文件 | 关键模式 | 行号 |
+|------|---------|------|
+| `Dashboard/src/content.tsx` | `timer.current` ref + `setInterval` 独立驱动各 Widget | 36, 79-90 |
+| `Dashboard/src/content.tsx` | `stopGetMonitor` 统一 clearInterval 所有 timer | 136-139 |
+| `Dashboard/src/content.tsx` | `useEffect(() => { startGetMonitor(); return stopGetMonitor; }, [wsStatus])` | 151-154 |
+| `Cluster/src/content.tsx` | `Tabs onChange={(val) => setGroupId(val)}` 驱动 useEffect 联动 | 73-78 |
+| `Cluster/src/content.tsx` | `useEffect(() => { queryGroupNodes(groupId)... }, [groupId])` Tabs 切换触发数据刷新 | 81-87 |
+| `Service/src/content.tsx` | `useAsync(updateDisabled, 'id')` + `updateDisabledLoadingMap[row.id]` loadingMap 模式 | 66, 452 |

package/codemods/modal-onCancel-to-onDismiss.js

@@ -0,0 +1,69 @@
+/**
+ * jscodeshift codemod · modal-onCancel-to-onDismiss
+ *
+ * 为 v5.0.0-beta.14 提供:把 `<Modal onCancel={fn}>` v4 写法
+ * 自动改成 `<Modal onCancel={fn} onDismiss={fn}>`,解决 X/ESC/蒙层
+ * 在 v6.0(2026 Q3)起 silently 失效的迁移问题。
+ *
+ * 用法(业务方):
+ *   npx jscodeshift -t node_modules/@para-ui/core/codemods/modal-onCancel-to-onDismiss.js \
+ *     --parser=tsx --extensions=tsx,jsx src/
+ *
+ * 规则:
+ * - 仅处理 <Modal> JSX(不处理 <NS.Modal>;不处理命令式 Modal.Confirm)
+ * - 已有 onDismiss / onClose → skip(避免破坏 legacy 双触发或 γ 单触发)
+ * - 含 JSX spread `{...rest}` → skip(无法静态判定)
+ * - onCancel 表达式直接复用作 onDismiss 值(同回调,与 dev throw / ESLint rule 一致)
+ *
+ * 详见:
+ *   - docs/UPGRADE_v4_to_v5.md §3.D.0
+ *   - BREAKING-CHANGES §B-Modal-props-rework 子条 #5
+ */
+module.exports = function transformer(file, api) {
+    const j = api.jscodeshift;
+    const root = j(file.source);
+    let touched = 0;
+
+    root.find(j.JSXOpeningElement)
+        .filter(path => {
+            const name = path.node.name;
+            return name && name.type === 'JSXIdentifier' && name.name === 'Modal';
+        })
+        .forEach(path => {
+            const attrs = path.node.attributes || [];
+            let onCancelAttr = null;
+            let hasOnDismiss = false;
+            let hasOnClose = false;
+            let hasSpread = false;
+
+            for (const attr of attrs) {
+                if (attr.type === 'JSXSpreadAttribute') {
+                    hasSpread = true;
+                    continue;
+                }
+                if (attr.type !== 'JSXAttribute') continue;
+                if (!attr.name || attr.name.type !== 'JSXIdentifier') continue;
+                if (attr.name.name === 'onCancel') onCancelAttr = attr;
+                else if (attr.name.name === 'onDismiss') hasOnDismiss = true;
+                else if (attr.name.name === 'onClose') hasOnClose = true;
+            }
+
+            if (hasSpread || !onCancelAttr || hasOnDismiss || hasOnClose) return;
+            if (!onCancelAttr.value) return;
+
+            const dismissAttr = j.jsxAttribute(
+                j.jsxIdentifier('onDismiss'),
+                onCancelAttr.value
+            );
+            path.node.attributes.push(dismissAttr);
+            touched += 1;
+        });
+
+    if (touched > 0) {
+        // 仅在有改动时输出,避免 dirty toSource 触发空 diff
+        return root.toSource({ quote: 'single', reuseWhitespace: true });
+    }
+    return null;
+};
+
+module.exports.parser = 'tsx';

package/es/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/es/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/es/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/es/AlignBox/index.js

@@ -3,7 +3,7 @@ import m from "clsx";
 import { $prefixCls as o } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
 const f = (r) => {
-  const { className: s, style: t, children: i, alignType: e = "vertical", ...l } = r;
+  const { className: s, style: t, children: i, direction: e = "horizontal", ...l } = r;
   return /* @__PURE__ */ a.jsx(
     "div",
     {

package/es/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/es/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;