## XJS / Animal.js 文档：模块化开发 & 测试总指南（工作流）

> 目标：把文档拆成可独立开发/测试的“小模块”，每个模块都有：
>
> - **左侧（第一列）**：扁平化总菜单（未来会加入 Layer 等 UI 库）
> - **中间（第二列）**：该模块/分组的「缩略图卡片」导航（像 anime.js 文档那样好玩）
> - **右侧（第三列）**：每个卡片对应的“完整示例页”（中文说明 + Tabs + Live Demo + Prev/Next）

---

## 目录（简体中文）

- 1. 三列架构是怎么工作的？
- 2. 文件/目录命名规范（强烈建议照做）
- 3. 左侧菜单（扁平化）规范：怎么加一个模块？
- 4. 第二列 list 页面规范：缩略图卡片 + 高亮同步
- 5. 第三列内容页面规范：Tabs + Demo + 组内/跨组 Prev/Next
- 6. Prev/Next 规则与路由表维护方式
- 7. `animal.js`（`xjs`）例子与测试规划（分组清单）
- 8. 已实现 / 进行中 / 待实现（进度表）

---

## 1) 三列架构是怎么工作的？

文档入口是 `doc/index.html`，它由 3 个区域组成：

- **左侧菜单（第一列）**
  - 点击某个菜单项会调用 `selectCategory(listUrl, defaultContentUrl)`
  - 它会同时更新：
    - **第二列 iframe**：加载该模块的 list 页面（卡片列表）
    - **第三列 iframe**：加载该模块默认的内容页

- **第二列（中列）**
  - 本质是一个 list 页（例如 `doc/targets/list.html`）
  - list 页点击卡片会调用 `window.parent.loadContent('xxx.html')` 来切换第三列内容页
  - list 页还实现了 `window.setActiveByContentUrl(contentUrl)`，用于**跟随第三列自动高亮**

- **第三列（右侧）**
  - 每个示例是一个独立 HTML 页面（例如 `doc/targets/test_css_selector.html`）
  - 内容页在加载时会调用 `window.parent.setMiddleActive('xxx.html')`，让第二列自动高亮对应卡片

---

## 2) 文件/目录命名规范（强烈建议照做）

每个“分组”建议放一个文件夹，结构如下：

```
doc/
  <group_name>/
    list.html               # 第二列：卡片列表（缩略图导航）
    overview.html           # 第三列：可选的分组概览页（建议）
    test_<topic>.html       # 第三列：具体示例页（一个功能点一个页面）
```

命名建议：

- **分组目录名**：英文小写 + 下划线，例如 `targets/`、`tween_value_types/`
- **示例页**：统一前缀 `test_`，例如 `test_css_selector.html`
- **概览页**：统一 `overview.html`

---

## 3) 左侧菜单（扁平化）规范：怎么加一个模块？

> 原则：**一个总菜单**，用“分区标题”做视觉分组，但不要折叠树（便于未来加入 Layer/其他 UI 库）。

左侧菜单当前在 `doc/index.html` 内直接维护。

### 左侧菜单建议结构（示例）

- **Animal.js 动画**
  - Targets（目标）
  - Properties（可动画属性）
  - Tween 值（补间值类型）
  - Callbacks（回调）
  - Examples（示例）
- **Layer 弹窗**
  - Layer + 动画联动示例
  - （未来）Layer API / 主题 / 组件化
- **开发者**
  - 模块开发与测试指南（本文件）

### 加菜单项时必须同时准备

- **第二列 list 页面**：`<group>/list.html`
- **第三列默认页**：`<group>/overview.html` 或 `test_xxx.html`

否则点击会白屏（找不到页面）。

---

## 4) 第二列 list 页面规范：缩略图卡片 + 高亮同步

第二列 list 页的核心要求：

- 卡片元素带 `data-content="group/test_xxx.html"`，用于与第三列 URL 做匹配
- 暴露函数 `window.setActiveByContentUrl(contentUrl)`，供父窗口调用进行高亮同步
- 点击卡片时调用：`window.parent.loadContent('group/test_xxx.html')`

参考现成实现：

- `doc/targets/list.html`

---

## 5) 第三列内容页面规范：Tabs + Demo + Prev/Next

第三列内容页建议统一采用“CSS Selector”同款结构：

- 顶部 breadcrumb + since
- 标题 + 简体中文说明
- **Tabs**（JavaScript / HTML / CSS）
- **Live Demo**（尽可能直观、活泼、有趣）
- **Prev / Next**（统一走父窗口的全局路由表）

内容页必须做两件事（保证三列联动）：

1. **同步第二列高亮**

```
try { window.parent?.setMiddleActive?.('group/test_xxx.html'); } catch {}
```

2. **Prev / Next 走父窗口统一逻辑**

```
const CURRENT = 'group/test_xxx.html';
function goPrev() { window.parent?.docNavigatePrev?.(CURRENT); }
function goNext() { window.parent?.docNavigateNext?.(CURRENT); }
```

> 好处：不用每个页面手写上一个/下一个链接；组内/跨组顺序统一由父窗口维护。

---

## 6) Prev/Next 规则与路由表维护方式

Prev/Next 规则：

- **组内跳转**：同一 group 内按页面顺序移动
- **跨组跳转**：到上一组的最后一个 / 下一组的第一个（整体顺序不间断）

路由表位置：

- 当前维护在 `doc/index.html` 里的 `DOC_PAGES` 数组

维护原则：

- 每新增一个 `test_xxx.html`，**就把它加进 `DOC_PAGES`**
- `url` 使用相对 `doc/` 的路径，例如 `targets/test_css_selector.html`
- `group` 用于 Nav 中间的“当前分组”显示

---

## 7) `animal.js`（`xjs`）例子与测试规划（分组清单）

说明：

- ✅ = 已存在页面（可能需要补充中文说明/统一 PrevNext）
- ⬜ = 待新增（本工作流会按顺序逐步补齐）

### A. Targets（目标选择）

- ✅ `targets/overview.html`：概览
- ✅ `targets/test_css_selector.html`：CSS Selector（字符串）
- ✅ `targets/test_dom_elements.html`：DOM Element / NodeList
- ✅ `targets/test_js_objects.html`：JS 对象作为目标（对象 tween）
- ✅ `targets/test_array_targets.html`：数组 targets（混合目标）

### B. Animatable properties（可动画属性 / 引擎分流）

- ✅ `animatable_properties/test_transforms.html`：Transform（x/y/rotate/scale）
- ✅ `animatable_properties/test_css_props.html`：CSS 属性
- ✅ `animatable_properties/test_css_vars.html`：CSS 变量 `--xxx`
- ✅ `animatable_properties/test_js_props.html`：JS 属性（非 style）

⬜（建议新增）

- ⬜ `animatable_properties/overview.html`：本组概览 + “WAAPI vs JS fallback” 解释 + `controls.engine` 展示

### C. Tween value types（补间值类型）

- ✅ `tween_value_types/test_numerical.html`：数字
- ✅ `tween_value_types/test_unit.html`：单位（px/deg/%/rem…）
- ✅ `tween_value_types/test_relative.html`：相对值（如果支持）
- ✅ `tween_value_types/test_colors.html`：颜色（如果支持）

⬜（建议新增）

- ⬜ `tween_value_types/overview.html`：本组概览 + “哪些值会走 JS 插值/哪些会离散切换” 说明

### D. Tween parameters（补间参数 / 播放参数）

> `animal.js` 实际支持的参数（来自源码）：`duration / delay / easing / direction / fill / loop / endDelay / autoplay / springFrames / begin / update / complete`。

- ⬜ `tween_parameters/list.html`
- ⬜ `tween_parameters/overview.html`
- ⬜ `tween_parameters/test_duration_delay.html`
- ⬜ `tween_parameters/test_endDelay_fill.html`
- ⬜ `tween_parameters/test_direction_loop.html`
- ⬜ `tween_parameters/test_easing_named_and_bezier.html`
- ⬜ `tween_parameters/test_easing_spring.html`（展示 spring 曲线 + springFrames）

### E. Controls（控制器 API）

> `animate()` 返回 Controls：`play/pause/cancel/finish/seek`，并且是 thenable（可 `await`）。

- ⬜ `controls/list.html`
- ⬜ `controls/overview.html`
- ⬜ `controls/test_play_pause_resume.html`
- ⬜ `controls/test_seek_slider.html`（进度条拖动）
- ⬜ `controls/test_thenable.html`（`await xjs(...).animate(...)`）
- ⬜ `controls/test_engine_info.html`（展示 `controls.engine.waapiKeys/jsKeys`）

### F. Timeline（时间轴）

- ⬜ `timeline/list.html`
- ⬜ `timeline/overview.html`
- ⬜ `timeline/test_add_offsets.html`（`+=`、`-=`、number offset）
- ⬜ `timeline/test_defaults.html`（timeline defaults）

### G. SVG（draw）

- ⬜ `svg/list.html`
- ⬜ `svg/overview.html`
- ⬜ `svg/test_draw_path.html`（`xjs('path').draw()`）
- ⬜ `svg/test_svg_attr_js_fallback.html`（SVG attribute 动画：哪些走 JS）

### H. InView / Scroll（视口触发 / 滚动联动）

- ⬜ `scroll/list.html`
- ⬜ `scroll/overview.html`
- ⬜ `scroll/test_inview_once.html`（inViewAnimate once:true/false）
- ⬜ `scroll/test_scroll_linked_element.html`（scroll(target)）
- ⬜ `scroll/test_scroll_container.html`（scroll container）

### I. Layer 集成（联动展示库特性）

> `Selection.layer()` / `Selection.unlayer()` + `xjs.fire()` / `xjs.layer()`

- ✅ `examples/layer.html`（已有示例，但后续会补充“更像产品”的玩法）
- ✅ `layer/list.html`（第二列：Layer 分组卡片导航）
- ✅ `layer/overview.html`（独立分组：弹窗 API + 图标动画概览）
- ✅ `layer/test_icons_svg_animation.html`（SVG icon：ring + mark 描边动画，体验接近 SweetAlert）
- ✅ `layer/test_confirm_flow.html`（确认流程：warning → success/info 串联）
- ✅ `layer/test_selection_layer_dataset.html`（Selection.layer + data-layer-*）
- ✅ `layer/test_static_fire.html`（Layer.fire / Layer.$ builder）

> 说明：Layer 的成功/失败等 icon 已切换为 **内联 SVG**，并使用 `animal.js` 的 `draw()` 技术（strokeDashoffset）做描边动画，同时用 spring easing 做弹性进入。

---

## 8) 已实现 / 进行中 / 待实现（进度表）

### 已实现 ✅

- ✅ 左侧菜单扁平化（`doc/index.html`）
- ✅ 全局 Prev/Next 路由表与 API（`doc/index.html`：`DOC_PAGES` + `docGetPrevNext/docNavigatePrev/docNavigateNext`）
- ✅ “模块开发与测试指南”查看页（`doc/module.html`，读取 `doc/module.md`）

### 进行中 🛠️

- 🛠️ 补齐 `animal.js` 的缺失分组：Tween parameters / Controls / Timeline / SVG / Scroll / Layer（独立分组）

### 待实现 ⬜

- ⬜ 为新增分组创建第二列 list 页面（缩略图卡片导航）
- ⬜ 为新增分组创建第三列内容页（中文说明 + Tabs + Demo + Prev/Next）
- ⬜ 统一现有页面的 Prev/Next（从“硬编码跳转”迁移到全局路由表）