---
name: popover-zero-wrapper-refactor
overview: 为 Popover 组件增加显式 unwrapped 开关的"零包裹"模式（事件注入到用户触发器 vnode），并将 Tooltip/Dropdown/Select/DatePicker/RangePicker 及 AppSidebar、AppTabs、结构树等全部调用方迁移到零包裹，删除所有 .popover-trigger 相关补丁样式与 stretch-trigger 业务用法，全程保持现有行为不回归。
todos:
  - id: core-popover-unwrapped
    content: 改造 popover.vue：加 unwrapped prop、cloneVNode 注入事件与锚点指令、双分支模板
    status: completed
  - id: migrate-derived
    content: 迁移 Tooltip/Dropdown/menu/Select/DatePicker/RangePicker 开启 unwrapped，删除各 index.scss 的 .popover-trigger 补丁
    status: completed
    dependencies:
      - core-popover-unwrapped
  - id: migrate-usages
    content: 迁移外部使用点：AppSidebar/AppTabs 删 :deep 规则、结构树去 stretch-trigger、help-icon 开 unwrapped，用 [subagent:code-explorer] 核对全量清单
    status: completed
    dependencies:
      - migrate-derived
  - id: demo-tests
    content: demo/popover.vue 补 fallback/组件触发器/事件合并三用例，新增 popover vitest 单测
    status: completed
    dependencies:
      - core-popover-unwrapped
  - id: verify-all
    content: 跑 pnpm lint、fmt:check、build、test 全量验证，并人工回归四类触发场景
    status: completed
    dependencies:
      - migrate-derived
      - migrate-usages
      - demo-tests
---

## 用户需求

为 fms-vue 的 Popover 组件实现"零包裹"（antdv 式事件注入）模式，并全量迁移派生组件与外部调用点，同时保证不引入性能开销。

> 执行策略：**直接迁移（非渐进）**。项目处于初期阶段，迁移成本低，不做"迁移一个验证一个"，派生组件与外部使用点一次性全部开启 `unwrapped`，最后统一跑验证。`unwrapped` prop 保留默认 `false` 作为 API 兜底，但本次全量调用点均显式开启。

## 核心功能

- Popover 新增显式 `unwrapped` prop（默认 `false`，保持现有行为）：触发器插槽为单根元素/组件 vnode 时，通过 `cloneVNode` 把 6 个内部事件 handler（click/contextmenu/mouseenter/mouseleave/focusin/focusout）合并进用户 vnode，并用注入指令获取根 DOM 作为定位锚点；多根 fragment / 文本节点自动回退到现有 `span.popover-trigger` 包裹层。
- 派生组件全量迁移：Tooltip、Dropdown（含子菜单）、Select、DatePicker、RangePicker 内部显式开启 `unwrapped`，删除各自样式里的 `.popover-trigger` 布局补丁。
- 外部使用点迁移：AppSidebar / AppTabs 删除 `:deep(.popover-trigger)` 规则，结构树移除 `stretch-trigger`，FormEditPanel / TableEditPanel 的帮助图标 Popover 一并开启 `unwrapped`。
- demo 补充零包裹/fallback/事件合并用例；新增 Popover 组件单测（vitest + @vue/test-utils + jsdom）。
- 性能约束：归一化走 computed 缓存、不新增任何 watcher/observer/全局监听、`unwrapped=false` 时零额外开销。

## 边界

- fallback 路径保留 `stretch-trigger` 与 `.popover-trigger` 样式，不做破坏性删除。
- 事件合并采用 Vue `mergeProps` 原生语义：用户 handler 先执行、内部 handler 后执行，两者都触发，不覆盖。
- 零包裹模式下 `stretch-trigger` 无意义，静默忽略。

## 技术栈

- 现有栈：Vue 3.5.41（`<script setup>` + SFC）+ SCSS；验证脚本 `pnpm lint`（oxlint --deny-warnings）、`pnpm fmt:check`（oxfmt）、`pnpm build`（vite）、`pnpm test`（vitest run）。
- 复用 Vue 内置 `cloneVNode` / `mergeProps` / `useSlots` / 自定义指令机制，不引入任何新依赖。

## 实现思路

### 核心：popover.vue 零包裹模式

在 `src/components/ui/popover/popover.vue` 中：

1. **新增 prop**：`unwrapped: { type: Boolean, default: false }`。
2. **归一化 computed**（性能关键，响应式缓存）：

```js
const injectedTrigger = computed(() => {
  if (!props.unwrapped) return null
  const nodes = slots.trigger?.() ?? []
  const real = nodes.filter((n) => n.type !== Comment)
  if (real.length !== 1) return null
  const vnode = real[0]
  if (typeof vnode.type === 'symbol') return null // 文本/注释节点无法承载事件
  const injected = cloneVNode(vnode, triggerHandlers, true)
  // cloneVNode 在 props 变化时自动把 patchFlag 重置为 -1、清空 dynamicProps，
  // 避免 diff 按旧 flag 跳过属性更新导致注入事件静默失效
  return { ...injected, directives: [...(vnode.directives || []), { dir: triggerRefDirective }] }
})
```

- `triggerHandlers`：`{ onClick, onContextmenu, onMouseenter, onMouseleave, onFocusin, onFocusout }`，即现有 6 个函数，仅绑定位置从模板 span 改为注入 vnode；`mergeProps` 自动把用户已有 `on*` 合并为 `[用户, 内部]` 数组，两者都触发。
- `triggerRefDirective`：`mounted/updated` 把用户 vnode 根 DOM 同步到现有 `triggerEl` ref（定位锚点、外部点击 `contains`、`followTriggerWidth` 的 `offsetWidth` 三处复用，语义不变）；`mounted` 时若已打开（如 contextmenu/受控）补一次 `updatePosition`；`unmounted` 按 el 比对清理，不覆盖用户自己的 ref。
- 判定规则（O(1) 浅检查）：`vnode.type` 为 `'string'`（原生元素）或 `'object'`（组件）→ 注入；`'symbol'`（文本/注释）或数组多根 → 返回 `null` 走包裹层。

3. **模板双分支**：`<component v-if="injectedTrigger" :is="injectedTrigger" />`，`v-else` 保留现有 `<span ref="triggerEl" class="popover-trigger" ...>` 包裹层（unwrapped=false、多根、文本三种情况均走此分支）。`injectedTrigger` 非空即表示"unwrapped 且可注入"，二者条件合并，无需额外判断。

### 性能保证（本次改造的硬约束）

- **零新增运行时开销**：不新增 watcher / ResizeObserver / 全局监听，全部复用现有 `watch(isOpen)`、`onViewportChange`、`onDocumentPointerDown` 等。
- **归一化缓存**：`injectedTrigger` 是 computed，`slots.trigger` 为响应式依赖，仅在插槽内容或 `unwrapped` 变化时重算；`unwrapped=false` 时直接返回 `null`，零 vnode 操作。
- **cloneVNode 成本**：一次浅拷贝 + O(n) 属性合并（6 个 handler），仅 Popover 渲染时发生，微秒级；与 antdv / Element Plus 实现规格一致。
- 锚点通过指令生命周期钩子同步，无轮询、无 DOM 查询。

### 派生组件迁移（一次性全量，全部显式开启 unwrapped）

> 以下 6 个文件在同一轮改动中全部迁移，不逐组件验证；配合"外部使用点迁移"一起完成后再统一跑 lint / fmt / build / test。

- `tooltip.vue`：Popover 加 `unwrapped`（固定）。
- `dropdown.vue`：新增 `unwrapped: { type: Boolean, default: true }` prop 透传给 Popover；`dropdown/index.scss` 删除 `:deep(.popover-trigger)` 补丁（L59-62），执行时确认 `.dropdown-item` 自身是否已撑满，缺失则补 `width:100%`。
- `dropdown/menu.vue`：嵌套子菜单 Popover 加 `unwrapped`（trigger 为单根 `span.dropdown-item`）。
- `select.vue`：Popover 加 `unwrapped`；`select/index.scss` 删除 `:deep(.popover-trigger)` 补丁（L10-13），`.select-trigger` 自带 `width:100%` 直接撑满 `.select`。
- `date-picker.vue` / `range-picker.vue`：Popover 加 `unwrapped`；`date/index.scss` 删除全局 `.popover-trigger { display:block; width:100% }`（L15-18，非 scoped 的全局规则，删除同时消除其对其它组件的样式污染隐患）。

### 外部使用点迁移（与派生组件同一轮一次性完成）

- `AppSidebar.vue`：删除 `.fms-team :deep(.popover-trigger)` 规则（L177-184）；`.fms-team-trigger` 自带 `width:100%`，零包裹后按钮直接为容器子元素，天然撑满。
- `AppTabs.vue`：删除 `.fms-tabs-track :deep(.popover-trigger)` 规则（L301-305）；`.fms-tab` 自带 `flex-shrink:0`。
- `ModuleStructureTree.vue`：Dropdown 移除 `stretch-trigger`；`.mst-tree` 自带 `width:100%`，零包裹后直接相对面板撑满，恢复"零配置撑满"。
- `FormEditPanel.vue` / `TableEditPanel.vue`：帮助图标 Popover 加 `unwrapped`（单根 `span.mm-edit__help-icon`，行为不变）。

### demo 与测试

- `demo/popover.vue` 补充三用例：多根 fragment（验证 fallback 到 span 包裹层）、组件作触发器（Input）、触发器带用户 `@click`（验证合并顺序：用户先执行、toggle 后执行）。
- 新增 `src/components/ui/popover/__tests__/popover.spec.js`（项目当前无测试文件，vitest 基建已就绪；文件头加 `// @vitest-environment jsdom` 声明环境）。用例：默认渲染 span、unwrapped 单根不渲染 span 且点击可开合、多根 fallback、用户与内部 click 均触发、组件触发器锚点生效。

### 架构图

```mermaid
flowchart TD
    A[popover.vue 双分支模板] --> B{injectedTrigger computed}
    B -->|unwrapped=true 且单根元素/组件| C[component :is=注入后 vnode<br/>cloneVNode+mergeProps 注入6事件<br/>patchFlag=-1 + 指令锚点]
    B -->|unwrapped=false 或 多根/文本| D[span.popover-trigger 包裹层<br/>stretch-trigger 保留]
    C --> E[派生组件全量迁移<br/>Tooltip/Dropdown/menu/Select/DatePicker/RangePicker]
    E --> F[外部使用点<br/>AppSidebar/AppTabs 删 :deep<br/>结构树去 stretch-trigger<br/>help-icon 开 unwrapped]
    D --> F
```

## 验证

- `pnpm lint`（oxlint --deny-warnings 零告警）、`pnpm fmt:check`、`pnpm build`、`pnpm test`。
- 手动回归点：团队切换下拉（AppSidebar）、页签右键菜单（AppTabs）、结构树右键菜单（ModuleStructureTree）、Select/DatePicker 宽度对齐、help-icon hover 提示。

## 目录结构

```
fms-vue/src/
├── components/ui/
│   ├── popover/popover.vue        # [MODIFY] 核心：unwrapped prop + 归一化 computed + 指令 + 双分支模板
│   ├── popover/index.scss         # [MODIFY] 仅保留 .popover-trigger 样式（fallback 用），结构不变
│   ├── popover/__tests__/popover.spec.js  # [NEW] vitest 单测（jsdom 环境）
│   ├── tooltip/tooltip.vue        # [MODIFY] Popover 加 unwrapped
│   ├── dropdown/dropdown.vue      # [MODIFY] 新增 unwrapped prop（默认 true）透传
│   ├── dropdown/menu.vue          # [MODIFY] 嵌套 Popover 加 unwrapped
│   ├── dropdown/index.scss        # [MODIFY] 删 :deep(.popover-trigger) 补丁
│   ├── select/select.vue          # [MODIFY] Popover 加 unwrapped
│   ├── select/index.scss          # [MODIFY] 删 :deep(.popover-trigger) 补丁
│   ├── date/date-picker.vue       # [MODIFY] Popover 加 unwrapped
│   ├── date/range-picker.vue      # [MODIFY] Popover 加 unwrapped
│   ├── date/index.scss            # [MODIFY] 删全局 .popover-trigger 规则
│   └── demo/popover.vue           # [MODIFY] 补 fallback/组件触发器/事件合并三用例
├── layouts/components/
│   ├── AppSidebar.vue             # [MODIFY] 删 :deep(.popover-trigger) 规则
│   └── AppTabs.vue                # [MODIFY] 删 :deep(.popover-trigger) 规则
└── views/system/module-management/
    ├── components/structure-tree/ModuleStructureTree.vue  # [MODIFY] Dropdown 去 stretch-trigger
    └── components/
        ├── form-edit/FormEditPanel.vue   # [MODIFY] help-icon Popover 加 unwrapped
        └── table-edit/TableEditPanel.vue # [MODIFY] help-icon Popover 加 unwrapped
```

## Agent Extensions

### Skill

- **antdv-next**
- 用途：参考 antdv 对触发器 vnode 的事件注入、锚点获取与 patchFlag 处理的成熟实现模式，确保零包裹实现与主流组件库对齐。
- 预期产出：popover.vue 核心改造与单测断言与 antdv 语义一致（事件合并顺序、多根兜底、组件触发器）。

### SubAgent

- **code-explorer**
- 用途：执行阶段扫描全项目确认 Popover/Tooltip/Dropdown/Select/DatePicker 的所有使用点与 `:deep(.popover-trigger)` 依赖清单，防止迁移遗漏回归点。
- 预期产出：完整的调用点清单，与计划中的迁移文件逐一核对，确保"都改掉"无遗漏。