# XJS 项目开发指南（Guide）

本仓库的目标是做一套**可用于生产环境**的 JS + CSS 框架，最终在业务项目中只需要引入：

- `xjs.js`（单文件 JS）
- `xjs.css`（单文件 CSS）

但在本仓库内，为了保持可维护性，**开发源码仍然分散在多个文件中**（例如 `animal.js`、`layer.js`），再通过构建脚本合并为单文件产物。

> 本文档用于统一后续完善/开发的**目录约定、命名规范、编码习惯、测试方式、发布流程**。请把它当成项目的“团队约定”。

---

## 1. 目录结构与职责边界

当前结构（关键文件）：

- **`animal.js`**：动画/选择器核心（Selection / animate / svg / timeline / scroll / inView 等能力）
- **`layer.js`**：弹出层组件（UI + 交互逻辑）
- **`xjs.css`**：库运行时需要的所有 UI 样式（例如 Layer 的 `.layer-*`）
- **`xjs.js`**：
  - 开发阶段：**加载器**（按顺序加载 `animal.js` + `layer.js`）
  - 同仓库内还可能包含“合并构建版本”的历史内容；开发时**不要手改合并产物**
- **`dist/xjs.js`**：生产合并产物（由构建命令生成）
- **`doc/index.html`**：统一测试/文档入口（支持点击导航直接进入示例页面）
- **`main.go`**：构建与本地静态服务脚本

### 源码与产物的黄金规则

- **只改源码**：`animal.js` / `layer.js` / `xjs.css` / `doc/**`
- **不手改产物**：`dist/xjs.js`（以及任何由构建生成的合并文件）
- **任何对外发布**以 `dist/xjs.js + xjs.css` 为准

---

## 2. 本地开发 / 测试流程（推荐路径）

### 2.1 启动静态服务

仓库自带 Go 静态服务（默认端口 8080）：

```bash
go run main.go serve
```

然后在浏览器打开：

- `http://localhost:8080/doc/index.html`

> 说明：`doc/index.html` 会作为“测试总控台”，左侧导航/中间列表/右侧 iframe 组合用于快速打开各类测试页面。

### 2.2 构建生产单文件（合并）

将 `animal.js + layer.js` 合并输出到 `dist/xjs.js`：

```bash
go run main.go build
```

或指定输出路径：

```bash
go run main.go build path/to/xjs.js
```

---

## 3. 对外 API / 全局变量规范

### 3.1 全局导出（必须稳定）

对外只承诺以下全局变量（避免污染）：

- **`window.xjs`**：主入口（推荐统一使用）
- **`window.animal`**：兼容别名（与 `xjs` 等价）
- **`window.Layer`**：Layer 构造/工厂入口

可选行为：

- **不默认导出 `$`**
- 只有当业务方在引入前显式设置 `window.XJS_GLOBAL_DOLLAR = true` 时，才会在 `$` 未被占用的前提下导出 `$ = xjs`

### 3.2 API 设计原则（统一风格）

- **单入口**：所有能力尽量从 `xjs(selector)` 返回的 `Selection` 链式对象进入
- **强约束、少魔法**：避免“隐式全局配置”；如需全局配置，集中在 `xjs.config`（未来可扩展）
- **兼容性优先级**：能用 WAAPI 就用 WAAPI；不支持时优雅降级（必要时 fallback 到 requestAnimationFrame）
- **返回值规范**：
  - 异步行为返回 `Promise`（例如 `animate().then(...)`）
  - 链式/操作型方法返回 `Selection` 以支持链式调用（例如 `.layer(...).addClass(... )` 未来扩展）

---

## 4. JS 命名规范与编码约定

### 4.1 文件/模块命名

- **文件名**：全小写 + 下划线/无分隔（当前采用 `animal.js`、`layer.js`，新增模块保持一致）
- **模块边界清晰**：
  - `animal.js`：核心选择器与动画体系（不直接引入 UI 样式）
  - `layer.js`：UI 组件（允许依赖 `xjs.css`）

### 4.2 变量/函数命名

- **函数**：`camelCase`
- **类**：`PascalCase`
- **常量**：`UPPER_SNAKE_CASE`
- **私有/内部约定**：以下划线前缀标识（例如 `_fire`、`_onKeydown`）

### 4.3 选择器与 Selection 约定

- `xjs(selector)` 返回 `Selection`（继承 Array 的可链式集合）
- Selection 实例方法命名尽量用动词：`animate / draw / inViewAnimate / layer / unlayer`
- 新增能力优先做成 Selection 方法，而不是新增全局函数

### 4.4 参数命名与可扩展性

- **Options 对象**：使用 plain object（JSON 友好）
- **动画参数**：把“动画属性”和“控制参数（duration/easing/loop 等）”分清
  - 不确定的配置键，不要让它误入“可动画属性”的判定
  - 建议将“非动画属性”的扩展项放进 `params.options`（现有实现已倾向此策略）

### 4.5 兼容性/健壮性

- 代码应能在“没有 bundler”的脚本环境运行
- 避免依赖现代语法到不可控程度（如确需使用，确保目标环境可用）
- 对 DOM/Window 等对象引用前做存在性判断（SSR/非浏览器环境不会直接崩溃）

---

## 5. CSS 规范（`xjs.css`）

### 5.1 单文件策略

- 所有库运行时 UI 样式集中在 `xjs.css`
- JS 侧**不要**注入大量 `<style>`（可接受“确保已引入 CSS”的兜底逻辑，但不把完整样式写入 JS）

### 5.2 命名空间与前缀（避免污染业务）

目前 Layer 使用 `.layer-*`，后续新增组件建议遵循：

- **组件前缀**：`x-<component>-*` 或沿用当前 `layer-*`（但需保持一致）
- **推荐做法**：统一前缀策略（后续若决定全库统一 `xjs-`，则逐步迁移）

> 目标是：业务 CSS 不会因为类名冲突而被库“意外影响”，也不会轻易覆盖库样式。

### 5.3 主题化（建议方向）

新增 UI 组件时，尽量通过 CSS 变量暴露可定制项：

- `--xjs-color-primary`
- `--xjs-radius-md`
- `--xjs-shadow-lg`
- `--layer-...`（若继续沿用 layer 命名空间）

并保证：

- **默认值可用**
- **业务覆盖变量即可换肤**（不需要改库内部选择器）

---

## 6. 文档与测试（`doc/`）

### 6.1 入口约定

- 所有测试页面统一从 `doc/index.html` 进入
- 新增测试页面时：
  - 放到合适的子目录（例如 `doc/layer/`、`doc/svg/`、`doc/tween_*`）
  - 在 `doc/index.html` 的导航树中挂入口，保证“可点击直达”

### 6.2 测试页面规范（建议）

- 每个测试页只验证一类能力（避免“一页测所有导致回归困难”）
- 页面顶部写清楚：
  - 测试目标
  - 预期现象
  - 参数组合/边界条件

---

## 7. 扩展开发指南（新增能力的推荐落点）

### 7.1 新增动画能力（优先落在 `animal.js`）

典型落点：

- 新增 Selection 方法：`Selection.prototype.xxx = function (...) { ... }`
- 或在 `Selection` 类体内增加方法（更推荐，保持结构统一）
- 如需新增静态能力：挂在 `xjs.xxx = ...`（需要同时考虑 `animal` 别名）

### 7.2 新增 UI 组件（独立文件 + CSS ）

推荐方式：

- 新增 `component_xxx.js`（或未来统一 `components/xxx.js`）
- 在 `xjs.css` 增加 `xxx-*`（或 `xjs-xxx-*`）样式
- 在构建阶段把该模块纳入单文件合并（更新 `main.go build()` 的拼接顺序）

> 当前 `main.go` 固定合并 `animal.js + layer.js`，当模块增长时建议升级为“配置式列表”。

---

## 8. 发布与回归清单（面向生产）

每次准备对外发布（或业务项目更新版本）前建议走一遍：

- **功能回归**
  - 打开 `doc/index.html`，对本次变更相关页面逐个验证
- **构建产物**
  - 执行 `go run main.go build`
  - 确认 `dist/xjs.js` 更新（不要手改）
- **对外 API 稳定性**
  - `xjs/animal/Layer` 是否都存在
  - `$` 是否仍然是“显式开关才导出”
- **样式影响面**
  - `xjs.css` 的类名是否避免与业务冲突
  - 是否通过 CSS 变量提供可配置项（可选但推荐）

---

## 9. 建议的后续演进（非强制，但推荐）

当模块越来越多时，建议逐步引入以下工程化能力（仍保持“最终只发两个文件”的目标）：

- **源码目录化**：例如 `src/animal/`、`src/layer/`、`src/core/`
- **构建脚本升级**：`main.go` 从“硬编码拼接两个文件”升级为“按清单拼接多个文件”
- **产物头信息**：在 `dist/xjs.js` 注入版本号、构建时间、变更摘要（便于定位线上问题）
- **最小化/压缩（可选）**：如需压缩，保持可回溯到未压缩构建（source map 视需求）

---

## 10. 约定优先级

如果本文档与源码现状出现不一致：

1. **以本文档为准**（作为未来统一标准）
2. 在不破坏对外 API 的前提下，逐步把历史实现迁移到本文档规范