---
name: modal-drawer-components
overview: 在 fms-vue 组件库中新增 Modal 模态框与 Drawer 抽屉两个弹层组件：参考 antdv-next 与 shadcn 的 dialog 设计，按本项目规范做轻量化实现——Teleport 渲染、遮罩/点击遮罩关闭/Esc 关闭、body 滚动锁定、焦点陷阱与焦点还原、mask fade + 面板 zoom/slide 过渡、受控/非受控双模式，并在 App.vue 反馈分类新增演示。
design:
  architecture:
    framework: vue
  styleKeywords:
    - 简洁
    - 中性色
    - 主色强调
    - 清晰层次
  fontSystem:
    fontFamily: PingFang SC
    heading:
      size: 16px
      weight: 600
    subheading:
      size: 14px
      weight: 500
    body:
      size: 14px
      weight: 400
  colorSystem:
    primary:
      - "#0f172b"
      - "#ffffff"
    background:
      - "#ffffff"
      - "#f5f6f8"
      - "#f1f5f9"
      - "#000000"
    text:
      - "#1f2329"
      - "#86909c"
      - "#ffffff"
    functional:
      - "#e5e6eb"
      - "#c9cdd4"
      - "#f2f3f5"
      - rgba(0,0,0,0.45)
todos:
  - id: create-shared-utils
    content: 使用 [skill:ui-ux-pro-max] 核对对话框/抽屉可访问性规范后，创建 utils/focus.js 焦点陷阱与 utils/scroll.js 滚动锁
    status: completed
  - id: build-modal
    content: 创建 modal/modal.vue 与 modal/index.scss：受控 open、mask fade + panel zoom、标题/关闭/确定取消/footer 插槽、ARIA 与焦点滚动接入
    status: completed
    dependencies:
      - create-shared-utils
  - id: build-drawer
    content: 创建 drawer/drawer.vue 与 drawer/index.scss：四方向滑入、header/extra/body/footer 三段式、ARIA 与焦点滚动接入
    status: completed
    dependencies:
      - create-shared-utils
  - id: wire-tokens-demo
    content: tokens.css 新增 mask/z-index token；App.vue 反馈分类新增 Modal/Drawer 导航与演示 section；静态检查后汇报
    status: completed
    dependencies:
      - build-modal
      - build-drawer
---

## 产品概述

在 fms-vue 组件库中新增 Modal 对话框与 Drawer 抽屉两个浮层组件：参考 antdv-next 的 Modal/Drawer 与 shadcn dialog 的设计，两者共享遮罩、焦点陷阱、滚动锁、关闭动画等基础能力，按本项目开发规范做轻量化实现，并在演示站 App.vue 反馈分类中新增展示。

## 核心功能

### Modal 对话框

- 受控开关 `v-model:open`，遮罩点击、右上角关闭按钮、Esc 键均可关闭
- 标题区（title 属性或 #title 插槽）、内容区（默认插槽）、底部操作区（默认"取消/确定"按钮，支持 #footer 自定义、footer=false 隐藏）
- 确定按钮加载态（confirmLoading）、宽度可配置（默认 520）、居中显示（centered）
- destroyOnClose 销毁内容、afterOpenChange 动画完成回调

### Drawer 抽屉

- 受控开关 `v-model:open`，支持四方向滑出（placement: right/left/top/bottom，默认 right）
- 尺寸可配置（默认 378，左右取宽、上下取高）
- 三段式结构：header（标题 + 关闭按钮 + #extra 附加区）、body（内容滚动区）、footer（纯插槽，无默认按钮，与 Modal 不同）
- 遮罩点击、关闭按钮、Esc 键关闭

### 共同能力

- 打开时锁定 body 滚动（滚动条宽度补偿，避免布局跳动），支持多个弹层嵌套计数
- 焦点管理：打开聚焦面板、Tab 焦点陷阱循环、关闭后焦点还原到触发元素
- 关闭动画（mask 淡出 + panel 缩放/滑出）后再真正卸载；prefers-reduced-motion 下关闭动画
- ARIA：role=dialog、aria-modal、aria-labelledby 关联标题、关闭按钮 aria-label
- 非受控模式：open 未传时组件内部维护（参照 Popover 先例）

## 视觉效果

- Modal：居中卡片，默认宽 520px，圆角 6px（--fms-control-radius），阴影 --fms-popover-shadow，深色半透明遮罩（0.45 透明度），打开 mask 淡入 + 面板轻微缩放
- Drawer：从边缘滑入（±100% 位移），面板白底，header 下边框、body 独立滚动、footer 上边框，阴影加深
- 全部复用 --fms-* token，深色模式自动适配

## 技术栈

- Vue 3 `<script setup>` + Sass + Vite，与现有组件库一致
- 图标按需导入 `@lucide/vue`（X 关闭图标，notification 已有先例）
- Teleport to body + Transition 动画（Popover / message-container 已有先例）
- 复用现有 Button（确定/取消/关闭）与关闭按钮样式范式（notification）

## 实现方案

### 公共逻辑抽取（utils/）

两个组件共用"焦点陷阱 + 滚动锁"，按规范抽到 `components/ui/utils`：

**utils/focus.js** — 对话框焦点管理纯 DOM 辅助：

- `saveActiveElement()`：保存当前聚焦元素（关闭后还原）
- `focusFirstIn(container)`：打开后聚焦面板内首个可聚焦元素（无则聚焦面板本身，带 `tabindex="-1"`）
- `createFocusTrap(container)`：返回 `{ trapKeydown, destroy }`；`trapKeydown` 处理 Tab 在可聚焦元素间循环（首尾 wrap），`destroy` 移除监听
- 可聚焦元素选择器：`a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])`

**utils/scroll.js** — body 滚动锁，计数支持嵌套：

- `lockScroll()` / `unlockScroll()`：模块级计数器，第一次 lock 时保存 `body.style.overflow` 与 `paddingRight`，设置 `overflow: hidden` 并用 `window.innerWidth - document.documentElement.clientWidth` 计算滚动条宽度补偿 paddingRight；全部 unlock 后恢复原值

### Modal 组件（modal/modal.vue + index.scss）

- Props：`open`(undefined 非受控)、`title`、`width`(520, Number|String)、`centered`(false)、`mask`(true)、`maskClosable`(true)、`keyboard`(true)、`closable`(true)、`footer`(undefined，undefined=默认按钮, false=隐藏)、`okText`('确定')、`cancelText`('取消')、`confirmLoading`(false)、`destroyOnClose`(false)、`zIndex`(undefined)
- Emits：`update:open`、`ok`、`cancel`、`afterOpenChange`
- 插槽：默认内容、`#title`、`#footer`、`#closeIcon`
- 结构：`<Teleport to="body"><Transition name="modal"><div v-if="resolvedOpen" class="modal-root" :style="zIndex">` > mask（点击关闭）+ wrap（flex 居中/顶部）+ panel（container，聚焦陷阱作用域）
- 行为：`handleOk` 仅 emit ok 不自动关闭（与 antd 一致）；`handleCancel` emit cancel + 关闭；confirmLoading 时 ok 按钮 loading 且不可重复触发
- 动画：单 Transition + 子元素各自 transition 属性——mask 用 opacity，panel 用 opacity + transform scale(0.98→1)
- 焦点：watch open 打开时 `focusFirstIn` + `createFocusTrap` + `lockScroll`；关闭时移除 trap + 还原焦点 + unlockScroll

### Drawer 组件（drawer/drawer.vue + index.scss）

- Props：`open`、`title`、`placement`(right, validator 四方向)、`size`(378, Number|String)、`mask`(true)、`maskClosable`(true)、`keyboard`(true)、`closable`(true)、`extra`(undefined)、`footer`(undefined)、`destroyOnClose`(false)、`zIndex`
- Emits / 插槽：同 Modal（无 ok/cancel）；`#extra` 插槽
- 结构：root > mask + content-wrapper（按 placement 定位，left/right 撑满高度、top/bottom 撑满宽度）> section（flex column）> header（标题+关闭+#extra）+ body（flex:1 滚动）+ footer（可选）
- 动画：mask fade + panel 按方向 translate（left: translateX(-100%)→none，bottom: translateY(100%)→none 等）
- 焦点/滚动：与 Modal 复用 utils 逻辑

### 受控 / 非受控

- `open` 默认 undefined；`resolvedOpen = computed(() => props.open ?? internalOpen)`（Popover 先例）
- 关闭路径统一 `requestClose()`：非受控写内部 ref，受控 emit `update:open(false)`，均触发关闭动画

### tokens.css 新增

- `--fms-mask-bg: rgba(0, 0, 0, 0.45)`（:root 与 .dark 均可复用）
- `--fms-z-modal: 2100`、`--fms-z-drawer: 2100`（需高于 message/notification 的 2000）
- `--fms-modal-padding-x/y` 或直接复用现有 --fms-control-padding-x 派生；面板内边距与 Drawer 尺寸尽量用 calc 派生，不新增冗余 token

### 性能与可靠性

- 全局监听（keydown）仅在打开期间注册、关闭/卸载清理（Popover 先例）
- 焦点陷阱与滚动锁都支持清理路径，卸载时兜底释放
- 无高频事件、无深度 watch；Transition 仅 opacity/transform 低成本属性
- prefers-reduced-motion 下关闭全部过渡

## 目录结构

```
fms-vue/src/components/ui/utils/
├── focus.js      # [NEW] 焦点陷阱：保存/还原焦点、聚焦首元素、Tab 循环 trap
└── scroll.js     # [NEW] body 滚动锁：计数式 lock/unlock，滚动条宽度补偿
fms-vue/src/components/ui/modal/
├── modal.vue     # [NEW] 对话框：受控 open、mask/panel 动画、标题/内容/footer、焦点与滚动管理、ARIA
└── index.scss    # [NEW] 遮罩、居中 wrap、panel 卡片、header/body/footer、关闭按钮、动画
fms-vue/src/components/ui/drawer/
├── drawer.vue    # [NEW] 抽屉：四方向滑出、header/extra/body/footer 三段式、焦点与滚动管理、ARIA
└── index.scss    # [NEW] 遮罩、placement 定位、section 布局、动画
fms-vue/src/theme/tokens.css  # [MODIFY] 新增 --fms-mask-bg、--fms-z-modal、--fms-z-drawer
fms-vue/src/App.vue           # [MODIFY] 反馈分类新增 Modal/Drawer 导航项 + 演示 section
```

不新增其他文件，无 barrel index；公共逻辑仅抽 utils 两个文件，两组件内部保持各自业务语义。

## 已知风险与规避

- 焦点陷阱边界：多弹层同时打开时各自 trap 可能冲突，本项目演示为单层场景，trap 按"最后打开者优先"自然覆盖；如后续需要支持多层，可在 utils 中改为栈式管理（本次不做，避免过度设计）
- body 滚动锁与弹层内滚动：锁定的是 body，面板内部 overflow auto 不受影响；未配置 body padding 补偿时可能出现 17px 位移，已在 utils 中处理
- 关闭动画期间用户再次打开：resolvedOpen 立即回 true 会中断 leave，Vue Transition 会自动处理，无额外代码

## 设计风格

延续项目 tokens 驱动的简洁中性风格，参考 antd Modal/Drawer 经典形态与 shadcn dialog 的层次感。

- 布局：Modal 使用 fixed 全屏 root（mask 铺满 + wrap 承载面板），默认顶部 100px 显示、centered 时垂直水平居中；面板 flex column 三段式（header/body/footer）。Drawer 面板贴边滑出，left/right 撑满视口高度、top/bottom 撑满宽度，header 16px/24px + 下边框，body flex:1 滚动，footer 上边框
- 视觉：Modal 面板宽 520px、圆角 6px、背景 --fms-card、阴影 --fms-popover-shadow；遮罩半透明深色（rgba(0,0,0,0.45)），打开时 mask 淡入、面板 0.98 缩放淡入，关闭反向；Drawer 面板边缘阴影加深，按方向平移滑入/滑出
- 交互反馈：关闭按钮 22px 方形、hover 浅灰背景（notification 先例）、:focus-visible 主色 outline；按钮区右对齐、间距 8px
- 响应式：Modal 窄屏 max-width calc(100vw - 16px) 防溢出；Drawer 尺寸由调用方控制
- 动画仅限 opacity/transform，prefers-reduced-motion 下全部关闭

## Agent Extensions

### Skill

- **ui-ux-pro-max**
- 用途：实现前查询对话框（dialog）与抽屉（drawer）的可访问性、焦点管理与键盘操作 UX 规则（focus trap、aria-modal、Esc 关闭、滚动锁），核对交互是否符合常见实践
- 预期结果：获得对话框/抽屉的交互与可访问性指引；若查询无有效输出，则回退到开发规范内置的交互底线（focus-visible、ARIA、禁用语义）实现
- **antdv-next**
- 用途：核对 antdv-next Modal/Drawer 的 API 行为细节（open 受控、ok/cancel 语义、placement 尺寸映射、动画方向），作为实现参照的补充验证
- 预期结果：确认 API 命名与行为与参考库一致，避免设计偏差