# MarkdownEditor 块级编辑设计文档

## 概述

`MarkdownEditor` 是 yurou（语柔）的核心编辑组件，支持两种编辑模式：

| 模式 | 说明 |
|---|---|
| **双栏**（split） | 左侧 textarea 编辑源码，右侧 unified 渲染 HTML 预览，滚动同步 |
| **单栏**（wysiwyg） | 逐块渲染与编辑：点击任意块弹出其原始 markdown 源码，失焦后自动重新渲染 |

## 技术栈

- **解析**：`remark-parse` + `remark-gfm`（GFM 扩展：表格、任务列表、删除线）
- **转换**：`remark-rehype`（mdast → hast）
- **安全**：`rehype-sanitize`（过滤 XSS，保留 `data-*` 属性）
- **输出**：`rehype-stringify`（hast → HTML 字符串）
- **框架**：Vue 3 Composition API + TypeScript

## 整体架构

```
modelValue (markdown 字符串)
        │
        ├─── split 模式 ──────────────────────────
        │        │
        │        ├── textarea (左栏，编辑源码)
        │        │     输入 → emit('update:modelValue')
        │        │
        │        └── div.markdown-preview (右栏，v-html)
        │              unified.processSync(md) → HTML
        │              滚动同步：textarea.scrollTop ↔ div.scrollTop
        │
        └─── wysiwyg 模式 ────────────────────────
                 │
                 ├── remark-parse → mdast
                 │      提取每个顶层子节点的 position (offset)
                 │
                 ├── 每个 block:
                 │      source = md.slice(start, end)   // 原始源码
                 │      html   = unified.processSync(source)  // 渲染 HTML
                 │
                 ├── blocks[] = [{id, source, html, startOffset, endOffset}, ...]
                 │
                 └── 模板中 v-for:
                        editingBlockId === block.id
                        ? <textarea v-model="editingSource" @blur="finalize" />
                        : <div v-html="block.html" @click="startEdit" />
```

## 块级编辑流程

### 1. 解析阶段（`parseBlocks`）

```
输入："### 标题\n\n段落内容\n\n```js\ncode\n```"

remark-parse 构建 mdast:

root
├── heading (depth=3)  position: {start: {offset: 0}, end: {offset: 9}}
│   └── text "标题"
├── paragraph          position: {start: {offset: 10}, end: {offset: 18}}
│   └── text "段落内容"
└── code (lang="js")   position: {start: {offset: 19}, end: {offset: 33}}
    └── "code\n"

提取每个顶层节点:
  blocks[0] = {id:"b0", source:"### 标题\n\n", startOffset:0, endOffset:9}
  blocks[1] = {id:"b1", source:"段落内容\n\n", startOffset:10, endOffset:18}
  blocks[2] = {id:"b2", source:"```js\ncode\n```", startOffset:19, endOffset:33}
```

### 2. 渲染阶段

每个 block 独立调用 `unified().processSync(block.source)` 渲染为 HTML：

- `"### 标题\n\n"` → `<h3>标题</h3>`
- `"段落内容\n\n"` → `<p>段落内容</p>`
- `` "```js\ncode\n```" `` → `<pre><code class="language-js">code\n</code></pre>`

模板中按 `blocks[]` 顺序渲染，每个块是一个 `<div>`，hover 时显示暖色背景提示可点击。

### 3. 编辑阶段（`startEdit` → `finalizeEdit`）

```
用户点击某个 block
    │
    ▼
startEdit(block.id)
    │  editingBlockId = block.id
    │  editingSource = block.source   // 显示原始 markdown 源码
    │  nextTick → autoResize + focus + 光标移到末尾
    │
    ▼
<textarea v-model="editingSource" />  替换该块的 <div>
    │
    │  monospace 字体，暖色边框，auto-resize
    │  Ctrl+S → 先 finalize 再触发 save-shortcut
    │  Esc → cancelEdit (丢弃修改)
    │
    ▼
失焦 (blur)
    │
    ▼
finalizeEdit()
    │  如果 editingSource !== block.source:
    │      before = md.slice(0, block.startOffset)
    │      after  = md.slice(block.endOffset)
    │      emit('update:modelValue', before + newSource + after)
    │
    ▼
父组件 update:modelValue → modelValue 变化
    │
    ▼
watch(modelValue) → parseBlocks(newMd) → 重新渲染所有 block
```

### 4. 边界情况处理

| 场景 | 处理方式 |
|---|---|
| 空文档 | 显示 placeholder 文本，点击后插入换行符触发解析 |
| 块被删除所有内容 | 替换为空字符串，该块从 mdast 中消失 |
| 块中增加空行 | 该块的 markdown 包含空行 → mdast 解析为多个块 → 下次渲染自动拆分 |
| 代码块内编辑 | 三引号 + 语言标记全部显示在 textarea 中，用户自由编辑 |
| 列表 | 整个列表（含所有 li）作为一个块，编辑时看到完整列表的 markdown |
| 表格 | 整表作为一个块 |
| 解析失败 | `catch` 后用 `escapeHtml(source)` 显示原文 |

## 双栏模式流程

```
modelValue → unified.processSync(md) → HTML → v-html 渲染

textarea (左)               preview (右)
     │                           │
     ├─ input → emit             │
     ├─ keydown                  │
     │   ├─ Ctrl+S → save        │
     │   ├─ Tab → 2 spaces       │
     │   └─ 括号 → auto-pair     │
     │                           │
     └─ scroll → 同步比例 ──────► scrollTop
```

## 数据流

```
App.vue (content ref)
    │
    ├── :model-value="content"
    ├── :display-mode="displayMode"    ← 设置面板切换
    ├── @update:model-value="onUpdate" → content = val
    └── @save-shortcut="doSave"

DirectorySidebar.vue (设置面板)
    │
    ├── :display-mode="displayMode"
    └── @toggle-display-mode="onToggleDisplayMode"
          → displayMode 切换 + localStorage 持久化

MarkdownEditor.vue
    │
    ├── split 模式: 与 App.vue 双向绑定，实时渲染预览
    └── wysiwyg 模式: 解析 → 块 → 点击编辑 → 局部替换 → emit
```

## 性能考量

- **unified processor** 在组件 setup 时创建一次，全局复用
- **parseBlocks** 每次 modelValue 变化时调用，包含 N 次 `processSync`（N = 块数）
  - 典型文档（50 块）约需 50-100ms，在可接受范围内
  - 后续可优化为增量更新（只重新渲染变化的块）
- **textarea auto-resize** 通过 `scrollHeight` 动态调整高度，无额外 DOM 操作
- **双栏滚动同步** 使用比例计算，避免频繁的绝对位置计算

## 样式体系

| 层级 | 设计 |
|---|---|
| 容器 | `border-[#e0dbcf]` 暖米色边框，`shadow-2xl` 阴影，`bg-white` |
| 文字 | `text-[#38342e]` 深棕色，`font-serif` |
| 标题 | `text-[#2d2a26]` 更深，`font-weight: 700` |
| 链接 | `text-[#bf6a3b]` 暖橙色，`underline` |
| 行内代码 | `bg-[#f4f1ea]` 暖灰底，`text-[#bf6a3b]` |
| 引用 | 左边框 `4px solid #bf6a3b`，斜体灰色 |
| 表格 | 斑马条纹 `bg-[#faf9f6]`，表头 `bg-[#f4f1ea]` |
| 块 hover | `bg-[#faf9f6]` 微暖灰，提示可点击 |
| 编辑 textarea | `bg-[#faf9f6]`，`border-[#bf6a3b]`，`font-mono` |
| 缩放 | `calc(1rem * var(--editor-zoom, 1))` CSS 变量，由 App.vue 的 Ctrl+滚轮 控制 |