---
name: tree-component
overview: "依据 fms-vue 开发规范和 antdv-next 参考库，从零手写一个 Tree 组件，覆盖：树形展示与展开折叠、单选/多选、checkable 复选（含半选与父子联动）、异步懒加载，以及拖拽排序与搜索过滤两个进阶特性；节点支持 title 字段 + #title 插槽自定义。"
todos:
  - id: explore-refs
    content: 用 [skill:antdv-next] 与 code-explorer 对齐 Tree API 与相邻组件写法
    status: completed
  - id: add-tokens
    content: 在 tokens.css 补充 tree 专属尺寸 token
    status: completed
    dependencies:
      - explore-refs
  - id: write-utils
    content: 实现 tree/utils.js 纯函数（checked/halfChecked/展开路径/过滤/拖拽落点）
    status: completed
    dependencies:
      - explore-refs
  - id: write-tree
    content: 实现 tree.vue 容器与递归节点（展开/选中/勾选/异步/拖拽/过滤/插槽/键盘）
    status: completed
    dependencies:
      - write-utils
      - add-tokens
  - id: write-style
    content: 编写 tree/index.scss 样式（缩进/hover/focus/disabled/半选/拖拽线/高亮/reduced-motion）
    status: completed
    dependencies:
      - write-tree
  - id: write-demo
    content: 新增 tree/demo/tree-demo.vue 验证各模式用法
    status: completed
    dependencies:
      - write-tree
  - id: static-check
    content: 运行 oxlint 静态检查并说明未构建未测试
    status: completed
    dependencies:
      - write-style
      - write-demo
---

## 用户需求

用户已实现 Grid（Row + Col 基础栅格，不含 xs~xxxl 响应式），但反馈"完全不行"，要求分析根因并修复。

## 产品概述

基于 24 栅格系统的布局组件（Row 容器 + Col 列），用于快速搭建页面结构。当前已实现但存在视觉错乱与范式问题，需修复使其达到与项目其他组件一致的可用状态。

## 核心特性（修复后应保持）

- Row：flex 行容器，支持 gutter（数字 / [水平, 垂直]）、align、justify、wrap。
- Col：列单元，支持 span、offset、order、push、pull、flex。
- 24 栅格百分比宽度 + gutter 负 margin 经典实现，纯 CSS、无 JS 断点监听。

## 技术栈

- Vue 3 `<script setup>` + scoped/全局 SCSS（与本项目一致）
- 纯 CSS 栅格，复用 `--fms-*` token，新增 `--fms-grid-gutter`

## 实现方案

### 策略

对照可正常工作的 `date` 组件（同为 `<script> import scss` 全局写法）与 `splitter`/`spin`（`<style scoped> @use` 写法），定位 Grid 的真实缺陷并修复。核心修正三类问题：Demo 容器嵌套 flex 导致栅格错乱、样式作用域双注入、SCSS 过时 API。

### 关键技术决策

1. **修正 Demo 嵌套 flex 主因**：`.demo-panel`（`demo.css`）是 `display:flex; flex-wrap:wrap`，Grid 的 `<Row>` 作为其子项默认 `flex:0 1 auto` 被压缩/拉伸，内部 Col 依赖 Row 的 flex 上下文因而错位。修复：在 `index.scss` 给 `.fms-row` 加 `width:100%`，并在 demo 里用块级 wrapper 包住 Row，隔离外层 flex。
2. **样式全局单例引入**：移除 row.vue/col.vue 各自 `import './index.scss'`（双注入、全局污染），改为在 `src/styles/index.css` 顶部 `@import '../components/ui/grid/index.scss';` 一次性全局引入（栅格为跨组件结构性样式，应全局单例，与 antd 一致）。
3. **消除 SCSS deprecation**：`@use 'sass:math'` + `math.percentage(math.div($n, $cols))` 替换 `percentage($n / $cols)`。
4. **健壮性**：`.fms-col` 加 `min-width:0` 防内容撑破（参照 splitter panel）。
5. **简化 push/pull 演示**：避免与 offset 混用语义冲突，移除易错乱的混用段。

### 性能与可靠性

- 静态 class + CSS 变量，无高频事件、无布局读取、无残留监听。
- 全局单例引入避免重复注入，构建产物更小、无 scoped 跨组件失效风险。

## 实现备注

- 复用现有 `.fms-<name>` 命名与 `@use`/`@import` 约定（参考 splitter/index.scss、date 写法）。
- 不创建 barrel index（规范 3）。
- 演示注册方式沿用现有 App.vue 的 demoMap（已完成，无需改）。
- 修复后跑一次 `vite build`（诊断性）确认无编译错误 / deprecation 阻断，并 oxlint。

## 目录结构

```
fms-vue/src/components/ui/grid/
  row.vue      # [MODIFY] 移除 `<script>` 中 `import './index.scss'`（改全局单例引入）。
  col.vue      # [MODIFY] 移除 `<script>` 中 `import './index.scss'`。
  index.scss   # [MODIFY] ①`@use 'sass:math'` 改写除法/percentage 消 deprecation；②`.fms-col` 加 `min-width:0`；③`.fms-row` 加 `width:100%`。
fms-vue/src/styles/index.css        # [MODIFY] 顶部新增 `@import '../components/ui/grid/index.scss';` 全局单例引入栅格样式。
fms-vue/src/components/ui/demo/grid.vue  # [MODIFY] ① 每个 Row 外包块级 wrapper 隔离 `.demo-panel` flex；② 简化 push/pull 演示段。
```

## 关键代码结构

```
// grid/index.scss 关键修正
@use 'sass:math';

.fms-row {
  display: flex;
  flex-flow: row wrap;
  width: 100%;                 // 防止被外层 flex 容器压缩
  // ...gutter 变量与负 margin 保持不变
}

.fms-col {
  min-width: 0;                // 防止内容撑破 flex 列
  padding-left: calc(var(--fms-grid-gutter-h) / 2);
  padding-right: calc(var(--fms-grid-gutter-h) / 2);
  box-sizing: border-box;
}

// 24 栅格宽度（消 deprecation）
@for $n from 0 through 24 {
  .fms-col-#{$n} {
    @if $n == 0 { display: none; } @else { display: block; }
    flex: 0 0 math.percentage(math.div($n, 24));
    max-width: math.percentage(math.div($n, 24));
  }
}
```

## Agent Extensions

### Skill

- **antdv-next**
- Purpose: 对照 antdv-next Grid 的官方实现（row.tsx/col.tsx/index.tsx）确认 gutter 负 margin、push/pull relative 实现、24 栅格 API 语义，确保 Vue 化移植的修复忠于原库交互。
- Expected outcome: 确认 Row/Col 的 props 集合、gutter 实现细节与 flex 解析规则，指导 Grid 修复方案不偏离原库设计。
- **agent-browser**
- Purpose: 在修复前后打开 http://localhost:5082 的 Grid 演示页截图，直观验证"完全不行"的具体现象（竖排/错位/出血）及修复后渲染是否正确。
- Expected outcome: 取得 Grid 演示区真实渲染截图，作为修复验证的客观证据（构建后可用）。