glass-easel 0.1.0

package/guide/zh_CN/tree/element_iterator.md

@@ -0,0 +1,54 @@
+# 节点树遍历
+
+## 使用节点树遍历器
+
+通常，节点树遍历可以直接借助 `ElementIterator` 来实现。
+
+例如，依次获得某个节点在 Shadow Tree 上的所有节点：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      // 遍历模式： Shadow Tree 上所有子孙节点
+      const mode = 'shadow-descendants-root-first'
+      // 遍历
+      glassEasel.ElementIterator.create(this.shadowRoot, mode)
+        .forEach((node) => {
+          // 依次回调所有子孙节点
+          // 返回 false 会中断遍历
+        })
+    },
+  },
+})
+```
+
+节点树遍历模式有以下几种。
+
+| 模式 | 遍历范围 | 遍历顺序 |
+| ---- | -------- | -------- |
+| shadow-ancestors | Shadow Tree | 当前节点的祖先节点，由近及远 |
+| shadow-descendants-root-first | Shadow Tree | 当前节点的子孙节点，先父节点再子节点（先根遍历） |
+| shadow-descendants-root-last | Shadow Tree | 当前节点的子孙节点，先子节点再父节点（后根遍历） |
+| composed-ancestors | Composed Tree | 当前节点的祖先节点，由近及远 |
+| composed-descendants-root-first | Composed Tree | 当前节点的子孙节点，先父节点再子节点（先根遍历） |
+| composed-descendants-root-last | Composed Tree | 当前节点的子孙节点，先子节点再父节点（后根遍历） |
+
+## 限制节点遍历器返回的节点类型
+
+常常，遍历时只需要关心某一类节点。例如，遍历过程中只需要处理 `glassEasel.Element` ，不需要 `glassEasel.TextNode` ，此时可以限制 `ElementIterator` 的返回类型：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      const mode = 'shadow-descendants-root-first'
+      // 仅返回 glassEasel.Element
+      glassEasel.ElementIterator.create(this.shadowRoot, mode, glassEasel.Element)
+        .forEach((node) => {
+          // 依次回调所有 glassEasel.Element 节点
+        })
+    },
+  },
+})
+```

package/guide/zh_CN/tree/mutation_observer.md

@@ -0,0 +1,52 @@
+# 节点树变化监听
+
+Shadow Tree 的变化可以通过 `MutationObserver` 来监听。
+
+例如，获取整个 Shadow Tree 上子节点的变化：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      // 监听 Shadow Tree 上的所有属性变化
+      glassEasel.MutationObserver.create((ev) => {
+        ev.type === 'properties' // true
+        ev.target // 是哪个节点发生了变化
+        // 如果是组件的属性变化，则 propertyName 会被设置
+        ev.propertyName // 变化的属性名
+        // 如果是节点的 id 、 slot 、 class 或 style 变化，则 attributeName 会被设置
+        ev.attributeName // 变化的项目名
+      }).observe(this.shadowRoot, { subtree: true, properties: true })
+
+      // 监听 Shadow Tree 上节点的插入、移动或移除
+      glassEasel.MutationObserver.create((ev) => {
+        ev.type === 'childList' // true
+        ev.target // 是哪个节点的子节点列表发生了变化
+        ev.addedNodes // 新增的节点列表
+        ev.removedNodes // 移除的节点列表
+      }).observe(this.shadowRoot, { subtree: true, childList: true })
+
+      // 监听 Shadow Tree 上文本节点的内容变化
+      glassEasel.MutationObserver.create((ev) => {
+        ev.type === 'characterData' // true
+        ev.target // 是哪个节点所含文本发生了变化
+      }).observe(this.shadowRoot, { subtree: true, characterData: true })
+
+      // 监听当前节点的 attach 和 detach 状态变化
+      glassEasel.MutationObserver.create((ev) => {
+        ev.type === 'attachStatus' // true
+        ev.status // 'attached' 或 'detached'
+      }).observe(this.shadowRoot, { attachStatus: true })
+    },
+  },
+})
+```
+
+目前 glass-easel 支持的监听：
+
+* `properties` 属性变化；
+* `childList` 子节点列表变化；
+* `characterData` 文本内容变化；
+* `attachStatus` attach 和 detach 状态变化。
+
+一个监听器可以同时监听多类变化。同时可以激活 `subtree: true` 来监听所有子孙节点的变化。（ `subtree: true` 对 `attachStatus` 无效。）

package/guide/zh_CN/tree/node_tree.md

@@ -0,0 +1,142 @@
+# 节点树与节点类型
+
+## Shadow Tree
+
+glass-easel 自身以 **Shadow Tree** 为单位来存储节点树。每个组件实例对应于一个 Shadow Tree 。
+
+例如，对于一个由以下两个组件构成的页面：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>Text in childComponent</div>
+    <slot />
+  `),
+})
+
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div class="blue" />
+    <child>
+      <span>{{ text }}</span>
+    </child>
+  `),
+  data: { text: 'Text in myComponent' },
+})
+```
+
+这个页面中，包含两个 Shadow Tree 。其一是根组件 myComponent 的 Shadow Tree ：
+
+```
+ShadowRoot
+  - div class="blue"
+  - child
+    - span
+      - "Text in myComponent"
+```
+
+其二是 childComponent 的 Shadow Tree ：
+
+```
+ShadowRoot
+  - div
+    - "Text in childComponent"
+  - slot
+```
+
+Shadow Tree 有几个关键特点：
+
+* Shadow Tree 是一个组件实例自身模板中包含的节点，包括 slot 节点本身，但不包括组件的使用者放入 slot 中的内容；
+* 每个 Shadow Tree 都以一种特殊的 `ShadowRoot` 节点为根节点。
+
+## Composed Tree
+
+Shadow Tree 不能直接用于最终的页面，还需要经过一个 **树拼接** 过程，将所有 Shadow Tree 拼成一个大的 **Composed Tree** 。
+
+这个拼接过程中，组件节点会和它的 `ShadowRoot` 对应组合， slot 中也会被放入内容。
+
+对于上例， Composed Tree 是：
+
+```
+ShadowRoot
+  - div class="blue"
+  - child
+    - ShadowRoot
+      - div
+        - "Text in childComponent"
+      - slot
+        - span
+          - "Text in myComponent"
+```
+
+Composed Tree 中包含一些 **虚拟节点** ，如 `ShadowRoot` 和 slot ，将这些节点去掉之后就是真正的 DOM 节点树了。
+
+## 直接树访问
+
+访问组件实例的 `this.shadowRoot` 属性可以获取到这个组件实例对应的 `ShadowRoot` 节点。进而通过每个节点的 `childNodes` 数组可以直接访问到每个节点。例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>Text in childComponent</div>
+    <slot />
+  `),
+  lifetimes: {
+    attached() {
+      const shadowRoot = this.shadowRoot
+      const textNode = shadowRoot.childNodes[0].childNodes[0]
+      textNode.textContent === 'Text in childComponent' // true
+    },
+  },
+})
+```
+
+## 节点类型
+
+在通过 `childNodes` 访问节点树时，可能会访问到以下几种类型的节点：
+
+* `glassEasel.TextNode` 文本节点；
+* `glassEasel.NativeNode` 普通节点，如 `<div />` ；
+* `glassEasel.Component` 组件节点；
+* `glassEasel.VirtualNode` 虚拟节点。
+
+其中，除了 `glassEasel.TextNode` 之外，其余类型共有一个基类 `glassEasel.Element` 。
+
+`glassEasel.ShadowRoot` 是 `glassEasel.VirtualNode` 的子类。
+
+## 常用树遍历属性和方法
+
+除了 `childNodes` 外，还有一些属性和方法可以用来进行树遍历。常用的属性和方法如下：
+
+* `glassEasel.Element#childNodes` 当前节点的所有 Shadow Tree 子节点列表；
+* `glassEasel.Element#parentNode` 当前节点的 Shadow Tree 父节点；
+* `glassEasel.Element#ownerShadowRoot` 当前节点所在 Shadow Tree 的 `ShadowRoot` ；
+* `glassEasel.Element#getComposedChildren()` 当前节点的所有 Composed Tree 的子节点列表；
+* `glassEasel.Element#getComposedParent()` 当前节点的 Composed Tree 的父节点；
+* `glassEasel.Component#shadowRoot` 当前组件节点的 `ShadowRoot` ，对于 [外部组件](../advanced/external_component.md) 是一个 `glassEasel.ExternalShadowRoot` ；
+* `glassEasel.Component#getShadowRoot()` 当前组件节点的 `ShadowRoot` ，对于 [外部组件](../advanced/external_component.md) 返回空；
+* `glassEasel.ShadowRoot#getHostNode()` 当前 `ShadowRoot` 对应的组件节点；
+
+注意：不要直接修改这些属性。
+
+如果只是进行常规的树遍历，可以使用 [节点树遍历](element_iterator.md) 接口。
+
+## 调试输出节点树
+
+如果只是想临时输出节点树结构信息供调试使用，可以使用 `dumpElement` 或 `dumpElementToString` 方法：
+
+```js
+componentSpace.defineComponent({
+  lifetimes: {
+    attached() {
+      // 在 console 中输出 Shadow Tree
+      glassEasel.dumpElement(this.shadowRoot, false)
+      // 在 console 中输出 Composed Tree
+      glassEasel.dumpElement(this, true)
+    },
+  },
+})
+```

package/guide/zh_CN/tree/node_tree_modification.md

@@ -0,0 +1,78 @@
+# 节点树变更
+
+## 何时可以手工变更节点树
+
+绝大多数情况下，节点树都应该通过模板和数据绑定来改变。但在极少数情况下，需要绕开模板来手工变更节点树。
+
+一种情况是，在实现 [自定义模板引擎](../advanced/template_engine.md) 时需要手工变更节点树。
+
+另一种情况是，有些极特殊的组件树结构无法采用模板引擎表达。请注意：这种情况下，对于节点树的手工变更常常会和模板带来的更新冲突！通常，只应该更新不在模板上的节点，例如在模板的一个空节点内部插入新节点。
+
+变更节点树时，只需要变更 Shadow Tree ，而 Composed Tree 会自动变更。所以只关心 Shadow Tree 的变更方法即可。
+
+## 创建一个节点
+
+创建节点时，可以使用组件实例的 `this.shadowRoot` 下的几个创建方法。
+
+| 方法名 | 说明 |
+| ------ | ---- |
+| createTextNode | 创建一个 `glassEasel.TextNode` 文本节点 |
+| createNativeNode | 创建一个 `glassEasel.NativeNode` 普通节点 |
+| createComponent | 创建一个 `glassEasel.Component` 组件节点 |
+| createComponentOrNativeNode | 如果节点名字是一个组件，就创建一个 `glassEasel.Component` 组件节点，否则创建一个 `glassEasel.NativeNode` 普通节点 |
+| createVirtualNode | 创建一个 `glassEasel.VirtualNode` 虚拟节点 |
+
+注意，在一个 `glassEasel.ShadowRoot` 下创建的节点只能被插入到这个 Shadow Tree 中。
+
+## 增删节点
+
+将节点插入节点树或移出节点树时，可以使用 `glassEasel.Element` 下的几个插入、移除方法。
+
+| 方法名 | 说明 |
+| ------ | ---- |
+| appendChild | 追加一个新子节点 |
+| insertChildAt | 在第 index 个子节点的位置上插入一个新子节点 |
+| insertBefore | 在指定的子节点之前插入一个新子节点 |
+| insertChildren | 批量插入新子节点 |
+| removeChildAt | 移除第 index 个子节点 |
+| removeChild | 移除指定的子节点 |
+| removeChildren | 批量移除子节点 |
+| replaceChildAt | 替换第 index 个子节点为新子节点 |
+| replaceChild | 替换指定的子节点为新子节点 |
+| selfReplaceWith | 将节点自身替换为一个新节点 |
+
+如果将一个已经被插入的节点插入到另一个位置上，则会自动变为一个移动操作。
+
+glass-easel 内部使用的算法是针对在一个节点末尾追加新子节点（即 `appendChild` ）来优化的，所以请尽量多使用这样的操作。
+
+## 销毁节点
+
+将一个节点移出节点树之后，如果它不再被使用，则需要调用销毁方法 `glassEasel.Element.destroyBackendElement` ，否则有些情况下会出现内存泄漏。
+
+如果一个节点在被移出节点树后就必然不会再被使用，则可以提前调用 `glassEasel.Element.destroyBackendElementOnDetach` 使它在被移出后自动销毁，避免遗忘。
+
+## 节点树变更流程示例
+
+对节点树的操作流程可以大体上以下例表示：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div id="wrapper" />
+  `),
+  lifetimes: {
+    attached() {
+      // 获得 wrapper 节点
+      const wrapper = this.shadowRoot.getElementById('#wrapper')
+      // 创建一个新的 span 节点
+      const span = this.shadowRoot.createNativeNode('span')
+      // 当 span 被移出时自动销毁它
+      span.destroyBackendElementOnDetach()
+      // 将 span 插入到 wrapper 下
+      wrapper.appendChild(span)
+      // 将 span 移除出来
+      wrapper.removeChildAt(0)
+    },
+  },
+})
+```

package/guide/zh_CN/tree/selector.md

@@ -0,0 +1,66 @@
+# 选择器查询
+
+## 使用选择器获取节点
+
+通常，可通过选择器来快速获得 Shadow Tree 上一个特定的子孙节点。
+
+例如，获得一个 id 为 `the-id` 的子节点：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>
+      <span id="the-id">Some Text</span>
+    </div>
+  `),
+  lifetimes: {
+    attached() {
+      // 获取 id="the-id" 的节点
+      const span = this.shadowRoot.querySelector('#the-id')
+      span.childNodes[0].textContent = 'Some Text'
+    },
+  },
+})
+```
+
+目前 glass-easel 支持的选择器列表如下。
+
+| 名称 | 示例 | 说明 |
+| ---- | ---- | ---- |
+| id 选择器 | `#the-id` | 选择节点 id 为 `the-id` 的节点 |
+| class 选择器 | `.the-class` | 选择节点 class 含 `the-class` 的节点 |
+| 交集选择 | `#the-id.the-class` | 选择节点 id 为 `the-id` 且 class 含 `the-class` 的节点 |
+| 儿子选择 | `#the-id > .the-class` | 在节点 id 为 `the-id` 节点的儿子节点中，选择节点 class 含 `the-class` 的节点 |
+| 子孙选择 | `#the-id .the-class` | 在节点 id 为 `the-id` 节点的子孙节点中，选择节点 class 含 `the-class` 的节点 |
+| 跨组件子孙选择 | `#the-id >>> .the-class` | 在节点 id 为 `the-id` 节点的子孙节点中，选择节点 class 含 `the-class` 的节点，查找时可以进入其他组件、不限于当前 Shadow Tree |
+
+`querySelector` 只会返回第一个找到的节点。如果需要返回所有节点组成的列表，使用 `querySelectorAll` 。
+
+## 节点类型特化
+
+在使用 TypeScript 时，选择器查询返回的节点都是 `glassEasel.Element` 类型。此时可以使用一些类型特化方法将其转换为更具体的节点类型。
+
+最常用的类型特化方法是 `asInstanceOf` ，用来将一个节点转为某个特定组件的实例，例如：
+
+```js
+export const childComponent = componentSpace.define()
+  .methods({
+    aPlusB(a, b) { return a + b }
+  })
+  .registerComponent()
+export const myComponent = componentSpace.define()
+  .usingComponents({
+    child: childComponent,
+  })
+  .template(compileTemplate(`
+    <child id="the-id" />
+  `)
+  .lifetime('attached', function () {
+    // 获取 id="the-id" 的节点，并将其转换为 childComponent 的实例
+    const child = this.shadowRoot.querySelector('#the-id').asInstanceOf(childComponent)!
+    child.aPlusB(1, 2) === 3 // true
+  })
+  .registerComponent()
+```
+
+另一种比较好的实现方式是不关心节点的具体类型、只关心节点实现的接口，以实现更好的组件间解耦，此时可以使用 [Trait Behaviors](../interaction/trait_behavior.md) 。

package/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  projects: [
+    './jest.unit.config.js',
+    './jest.dts.config.js',
+  ]
+}

package/jest.dts.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  displayName: {
+    color: 'blue',
+    name: 'types',
+  },
+  roots: ['tests'],
+  runner: 'jest-runner-tsd',
+  testMatch: ['**/types/**/?(*.)+(spec|test).[jt]s?(x)'],
+}

package/jest.unit.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+  preset: 'ts-jest/presets/js-with-babel',
+  globals: {
+    'ts-jest': {
+      tsconfig: 'tsconfig.json',
+    },
+  },
+  roots: ['tests'],
+  testMatch: ['**/?(*.)+(spec|test).[jt]s?(x)', '!**/types/**'],
+  testEnvironment: 'jsdom',
+  "collectCoverageFrom": [
+    "src/**/*.ts"
+  ],
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "glass-easel",
+  "description": "The core module of the glass-easel project",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wechat-miniprogram/glass-easel.git"
+  },
+  "keywords": ["glass-easel"],
+  "author": "wechat-miniprogram",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/wechat-miniprogram/glass-easel/issues"
+  },
+  "homepage": "https://github.com/wechat-miniprogram/glass-easel",
+  "main": "dist/index.js",
+  "scripts": {
+    "doc": "typedoc src/index.ts --excludePrivate --excludeProtected --excludeInternal",
+    "build": "webpack --config webpack.config.js",
+    "dev": "webpack --config webpack.config.js --watch",
+    "lint": "eslint src/**/*.ts",
+    "test": "jest -c jest.config.js",
+    "coverage": "jest -c jest.config.js --collect-coverage"
+  },
+  "devDependencies": {
+    "glass-easel-template-compiler": "*"
+  }
+}