# Property Panel UI 重构计划

## 背景

当前属性面板的 UI 实现与设计稿 `attr-ui.html` 存在较大差异。本文档详细规划了重构任务，按照优先级从高到低排列，目标是让属性面板的视觉效果和交互体验与设计稿一致。

### 参考文件

- **设计稿**：`/attr-ui.html`
- **当前样式**：`ui/shadow-host.ts`
- **面板结构**：`ui/property-panel/property-panel.ts`
- **控件组件**：`ui/property-panel/controls/*.ts`

---

## 前置任务（已完成）

### 0.1 最小化 Bug 修复 ✅

**问题**：toolbar 和属性面板最小化时，只是背景消失了，里面的内容实际上还在

**根因**：CSS 中 `display: flex/inline-flex` 覆盖了 `[hidden]` 属性的默认 `display: none`

**解决方案**：

- [x] 在 `shadow-host.ts` 末尾添加全局 `[hidden] { display: none !important; }` 规则

### 0.2 输入框优化 ✅

**问题**：

1. 输入框显示 placeholder 而非真实值
2. Number 类型输入框不支持键盘上下键调整

**解决方案**：

- [x] 创建 `ui/property-panel/controls/number-stepping.ts` 工具模块
  - 支持 ArrowUp/ArrowDown 键盘步进
  - 支持 Shift (10x)、Alt (0.1x) 修饰键
  - 支持多种 CSS 单位 (px, %, rem, em, vh, vw, vmin, vmax)
- [x] 修改所有 control 显示真实值（inline 优先，fallback 到 computed）
- [x] 为所有数值输入框添加 keyboard stepping 支持：
  - `size-control.ts` - Width/Height
  - `spacing-control.ts` - Margin/Padding
  - `position-control.ts` - Top/Right/Bottom/Left/Z-Index
  - `layout-control.ts` - Gap
  - `typography-control.ts` - Font Size/Line Height
  - `appearance-control.ts` - Opacity/Border Radius/Border Width

---

## 阶段一：基础视觉系统对齐 ✅ 已完成

### 1.1 颜色方案重构 ✅

**目标**：将颜色系统从当前的灰色调整为设计稿的白底+灰输入框风格

| 属性         | 旧值              | 新值                              | 状态 |
| ------------ | ----------------- | --------------------------------- | ---- |
| 面板背景     | `#f8f8f8`         | `#ffffff`                         | ✅   |
| 输入框背景   | `#f0f0f0`         | `#f3f3f3`                         | ✅   |
| 输入框 hover | `#e8e8e8` (bg)    | `border #e0e0e0` (inset)          | ✅   |
| 输入框 focus | `box-shadow` 外圈 | `inset 2px border #3b82f6` + 白底 | ✅   |
| 边框色       | `#e8e8e8`         | `#e5e5e5`                         | ✅   |

**完成的任务**：

- [x] 更新 CSS 变量定义 (`shadow-host.ts:56-97`)
- [x] 修改输入框 hover/focus 样式为 inset border 模式
- [x] 面板背景改为纯白

### 1.2 字体与字号调整 ✅

| 属性         | 旧值     | 新值                      | 状态 |
| ------------ | -------- | ------------------------- | ---- |
| 面板基础字号 | `13px`   | `11px`                    | ✅   |
| 标签字号     | `11px`   | `10px`                    | ✅   |
| 输入框字号   | `12px`   | `11px`                    | ✅   |
| 字体家族     | 系统字体 | Inter + 系统字体 fallback | ✅   |

**完成的任务**：

- [x] 添加 Inter 字体声明（使用系统字体 fallback）
- [x] 调整面板、标签、输入框的字号
- [x] 移除标签的大写样式

### 1.3 间距与边距调整 ✅

| 属性          | 旧值        | 新值       | 状态 |
| ------------- | ----------- | ---------- | ---- |
| 面板宽度      | `320px`     | `280px`    | ✅   |
| Header 内边距 | `10px 14px` | `8px 12px` | ✅   |
| Body gap      | `10px`      | `12px`     | ✅   |

**完成的任务**：

- [x] 调整 `.we-panel`, `.we-prop-body`, `.we-field-group` 的 padding/gap
- [x] 调整 header 的 padding

### 1.4 圆角与阴影 ✅

| 属性       | 旧值        | 新值               | 状态 |
| ---------- | ----------- | ------------------ | ---- |
| 面板阴影   | `0 1px 2px` | Tailwind shadow-xl | ✅   |
| 输入框圆角 | `6px`       | `4px`              | ✅   |
| Tab 阴影   | 无          | `shadow-sm`        | ✅   |

**完成的任务**：

- [x] 增强面板阴影效果（双层阴影模拟 shadow-xl）
- [x] 调整输入框圆角为 4px
- [x] 为激活的 Tab 添加阴影

### 1.5 Group/Section 样式重构 ✅

| 属性         | 旧样式      | 新样式      | 状态 |
| ------------ | ----------- | ----------- | ---- |
| Group 边框   | 卡片边框    | 无边框      | ✅   |
| Section 分隔 | 无          | 顶部分隔线  | ✅   |
| Header 样式  | 粗体 + 大字 | 11px + #333 | ✅   |

**完成的任务**：

- [x] 移除 `.we-group` 的边框和背景
- [x] 添加 Section 间的分隔线 (`border-top`)
- [x] 调整 Group header 样式

---

## 阶段二：输入容器组件重构 ✅ 基础完成

### 2.1 建立输入容器系统 ✅

**背景**：设计稿的输入框不是单体 input，而是一个容器系统，支持：

- 前缀（prefix）：标签、图标
- 后缀（suffix）：单位、图标
- 容器驱动的 hover/focus 样式

**当前结构**：

```html
<div class="we-field">
  <span class="we-field-label">Width</span>
  <input class="we-input" />
</div>
```

**目标结构**：

```html
<div class="we-field">
  <span class="we-field-label">Position</span>
  <div class="we-input-container">
    <!-- 新增容器 -->
    <span class="we-input-container__prefix">X</span>
    <!-- 可选前缀 -->
    <input class="we-input-container__input" />
    <span class="we-input-container__suffix">px</span>
    <!-- 可选后缀 -->
  </div>
</div>
```

**已完成**：

- [x] 在 `shadow-host.ts` 中定义 `.we-input-container` 样式
- [x] 定义 `.we-input-container__prefix` 和 `.we-input-container__suffix` 样式
- [x] 创建 `ui/property-panel/components/input-container.ts` 组件
- [x] 将 hover/focus 样式移到容器级别（使用 `:focus-within`）

### 2.2 更新各 Control 使用新容器 ✅ 已完成

**需要更新的控件**：

- [x] `size-control.ts` - Width/Height（2列布局 + W/H 前缀 + 动态单位后缀）
- [x] `spacing-control.ts` - Margin/Padding（重构为 2x2 网格 + 方向图标 + 动态单位后缀）
- [x] `position-control.ts` - Top/Right/Bottom/Left/Z-Index（T/R/B/L 前缀 + 动态单位后缀）
- [x] `layout-control.ts` - Gap（图标前缀 + 动态单位后缀）
- [x] `typography-control.ts` - Font Size/Line Height（动态单位后缀，line-height 智能显示）
- [ ] `appearance-control.ts` - Opacity/Border Radius/Border Width（待实施）

**已完成的共享模块**：

- [x] 创建 `css-helpers.ts` 共享模块（extractUnitSuffix, hasExplicitUnit, normalizeLength）
- [x] 所有控件使用共享 helper，消除重复代码

---

## 阶段三：Section 结构重构（待实施）

### 3.1 Tab 信息架构调整

**当前**：4 个 Tab（Design/CSS/Props/DOM）
**设计稿**：2 个 Tab（Design/CSS）

**方案选择**：

- **方案 A**：保留 4 个 Tab，调整为溢出菜单
- **方案 B**：将 Props/DOM 移到其他入口
- **方案 C**：保持 4 个 Tab，调整样式适应

**任务**：

- [ ] 确定 Tab 数量的产品决策
- [ ] 实现选定方案

---

## 阶段四：功能组件实现（待实施）

### 4.1 Flow 布局图标组 ✅ 已完成

**设计稿位置**：`attr-ui.html:133-156`
**功能**：4 个图标按钮控制 `flex-direction`

```
[→] Row
[↓] Column
[←] Row Reverse
[↑] Column Reverse
```

**已完成**：

- [x] 创建 `ui/property-panel/components/icon-button-group.ts` 通用组件
- [x] 在 `shadow-host.ts` 中添加 `.we-icon-button-group` 样式
- [x] 在 `layout-control.ts` 中用图标组替换 Direction select
- [x] 添加对应的 SVG 箭头图标（row/column/row-reverse/column-reverse）

### 4.2 Alignment 九宫格 ✅ 已完成

**设计稿位置**：`attr-ui.html:166-208`
**功能**：3x3 网格控制 `justify-content` + `align-items`

```
[↖][↑][↗]
[←][·][→]
[↙][↓][↘]
```

**已完成**：

- [x] 创建 `ui/property-panel/components/alignment-grid.ts` 组件
- [x] 在 `shadow-host.ts` 中添加 `.we-alignment-grid` 样式
- [x] 替换 `layout-control.ts` 中的 Justify/Align select
- [x] 使用 `beginMultiStyle` 实现两个属性的原子提交

### 4.3 修复 Color Picker ✅ 部分完成

**当前问题**：

- `showPicker()` 无 try/catch，可能抛错
- alpha 通道被丢弃
- token 值 `var(--xxx)` 显示不正确

**已完成**：

- [x] 添加 `showPicker()` 的错误处理（try/catch + fallback to click）
- [x] 改进 `var()` 值的解析和显示（通过 placeholder 传入 computed value）

**待实施**：

- [ ] 支持 alpha 通道（RGBA/HSLA）- 需要引入第三方 color picker
- [ ] 考虑引入第三方 color picker（如 `@simonwep/pickr`）

---

## 阶段五：新功能模块（待实施）

### 5.1 Shadow & Blur 控制

**设计稿位置**：`attr-ui.html:396-425`
**功能**：

- 启用/禁用开关
- 类型选择（Drop shadow/Inner shadow/Layer Blur/Backdrop Blur）
- 可见性控制

**CSS 属性**：

- `box-shadow`
- `filter: blur()`
- `backdrop-filter: blur()`

**任务**：

- [x] 创建 `ui/property-panel/controls/effects-control.ts`
- [x] 实现 `box-shadow` 值解析和编辑
- [x] 实现 `filter` 值解析和编辑
- [x] 实现 `backdrop-filter` 值解析和编辑
- [x] 添加类型切换 UI
- [ ] 添加启用/禁用开关（可选，后续实现）

### 5.2 渐变编辑器

**设计稿位置**：`attr-ui.html:269-325`
**功能**：

- Linear/Radial 渐变类型
- 颜色停止点（color stops）
- 角度控制
- 翻转按钮

**CSS 属性**：

- `background-image: linear-gradient(...)`
- `background-image: radial-gradient(...)`

**任务**：

- [x] 创建 `ui/property-panel/controls/gradient-control.ts`
- [x] 实现渐变值解析（CSS gradient → 数据结构）
- [x] 实现角度/位置输入
- [x] 实现 2 个颜色停止点的编辑
- [x] 集成到 property-panel（作为独立的 Gradient 控制组）
- [ ] 实现渐变预览 slider（可选，后续优化）
- [ ] 实现 color stop 添加/删除/拖拽（可选，后续优化）

### 5.3 Token/变量 Pill 显示

**设计稿位置**：`attr-ui.html:374-384`
**功能**：当值为 CSS 变量时，显示为可点击的 pill

**任务**：

- [ ] 检测 `var(--xxx)` 值
- [ ] 渲染为 pill 样式
- [ ] 点击打开 token picker

---

## 阶段六：代码质量（贯穿始终）

### 6.1 样式系统统一

- [x] 所有颜色使用 CSS 变量（阶段一完成）
- [ ] 所有尺寸使用一致的 token
- [ ] 移除 inline style，统一到 `shadow-host.ts`

### 6.2 组件复用

- [ ] 提取通用组件到 `ui/property-panel/components/`
- [ ] 统一事件处理模式
- [ ] 统一 disabled/enabled 状态处理

### 6.3 类型安全

- [ ] 所有组件使用 TypeScript 严格类型
- [ ] 定义清晰的接口和类型
- [ ] 移除 any 类型断言

---

## 实施进度

| 阶段 | 任务               | 状态    | 备注                                         |
| ---- | ------------------ | ------- | -------------------------------------------- |
| 0.1  | 最小化 Bug 修复    | ✅      | 添加全局 `[hidden]` 规则                     |
| 0.2  | 输入框优化         | ✅      | number-stepping + 真实值显示                 |
| 1.1  | 颜色方案重构       | ✅      | 白底 + 灰输入框 + inset focus                |
| 1.2  | 字体与字号调整     | ✅      | 11px 基准 + Inter 字体                       |
| 1.3  | 间距与边距调整     | ✅      | 更紧凑的布局                                 |
| 1.4  | 圆角与阴影         | ✅      | shadow-xl + 4px 圆角                         |
| 1.5  | Group/Section 样式 | ✅      | 分隔线风格                                   |
| 2.1  | 输入容器系统       | ✅      | 组件 + CSS 样式                              |
| 2.2  | 更新 Controls      | ✅      | 所有主要控件已迁移，共享 css-helpers.ts      |
| 3.1  | Tab 信息架构       | 待实施  |                                              |
| 4.1  | Flow 图标组        | ✅      | icon-button-group.ts + 集成到 layout-control |
| 4.2  | Alignment 九宫格   | ✅      | alignment-grid.ts + 集成到 layout-control    |
| 4.3  | 修复 Color Picker  | ✅ 部分 | showPicker 异常处理 + var() 解析             |
| 5.1  | Shadow & Blur      | ✅      | effects-control.ts + 集成到 property-panel   |
| 5.2  | 渐变编辑器         | ✅      | gradient-control.ts + 集成到 property-panel  |
| 5.3  | Token Pill         | 待实施  |                                              |

---

## 注意事项

1. **渐进式实施**：每个 Phase 完成后应可独立测试和发布
2. **保持向后兼容**：重构过程中不应破坏现有功能
3. **设计决策记录**：遇到设计稿与实际需求冲突时，记录决策原因
4. **性能考虑**：新增组件需考虑渲染性能，避免不必要的 DOM 操作