glass-easel 0.1.0

package/dist/types/tests/core/trait_behaviors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trait_behaviors.test.d.ts.map

package/dist/types/tests/core/trait_behaviors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trait_behaviors.test.d.ts","sourceRoot":"","sources":["../../../../tests/core/trait_behaviors.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/binding_map.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=binding_map.test.d.ts.map

package/dist/types/tests/tmpl/binding_map.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding_map.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/binding_map.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/event.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event.test.d.ts.map

package/dist/types/tests/tmpl/event.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/event.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/expression.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=expression.test.d.ts.map

package/dist/types/tests/tmpl/expression.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/expression.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/lvalue.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lvalue.test.d.ts.map

package/dist/types/tests/tmpl/lvalue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lvalue.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/lvalue.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/native_rendering.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=native_rendering.test.d.ts.map

package/dist/types/tests/tmpl/native_rendering.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native_rendering.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/native_rendering.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/tmpl/structure.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=structure.test.d.ts.map

package/dist/types/tests/tmpl/structure.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.test.d.ts","sourceRoot":"","sources":["../../../../tests/tmpl/structure.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/types/chaining.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chaining.test.d.ts.map

package/dist/types/tests/types/chaining.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chaining.test.d.ts","sourceRoot":"","sources":["../../../../tests/types/chaining.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/types/createElement.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createElement.test.d.ts.map

package/dist/types/tests/types/createElement.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createElement.test.d.ts","sourceRoot":"","sources":["../../../../tests/types/createElement.test.ts"],"names":[],"mappings":""}

package/dist/types/tests/types/definition.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definition.test.d.ts.map

package/dist/types/tests/types/definition.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.test.d.ts","sourceRoot":"","sources":["../../../../tests/types/definition.test.ts"],"names":[],"mappings":""}

package/guide/zh_CN/advanced/binding_map_update.md

@@ -0,0 +1,32 @@
+# 绑定映射表更新
+
+glass-easel 内置的模板引擎支持两种更新方式。
+
+* 虚拟树更新：更新时，遍历需要更新的 Shadow Tree ，并更新变化了的数据绑定；
+* 绑定映射表更新：更新时，根据改变的数据字段名、找到用到了该字段数据绑定表达式，然后更新它。
+
+绑定映射表更新通常是一种更快速高效的更新方式，但它不能用于更新 `wx:if` `wx:for` 子节点树内部用到的数据字段。
+
+每次更新时， glass-easel 会根据被设置的数据字段名，来选择应该使用哪种更新方式。
+
+如果想要指定只其中一种更新方式，可以在编译模板时控制：
+
+```js
+const compileTemplate = (src: string, updateMode = '') => {
+  const group = new TmplGroup()
+  group.addTmpl('', src)
+  const genObjectSrc = `return ${group.getTmplGenObjectGroups()}`
+  group.free()
+  const genObjectGroupList = (new Function(genObjectSrc))() as { [key: string]: any }
+  return {
+    content: genObjectGroupList[''],
+    updateMode,
+  }
+}
+// 指定模板只使用虚拟树更新
+compileTemplate('<div />', 'virtualTree')
+// 指定模板只使用绑定映射表更新
+compileTemplate('<div />', 'bindingMap')
+```
+
+注意：在不支持的模板上强行只使用绑定映射表更新，会导致出错或更新异常。

package/guide/zh_CN/advanced/build_args.md

@@ -0,0 +1,28 @@
+# 构建参数
+
+glass-easel 的构建脚本会根据 `GLASS_EASEL_ARGS` 环境变量来构建出不同的结果。
+
+首先，构建模式会决定构建产物的文件名（位于 dist 目录下）以及不同的 [自定义后端](custom_backend.md) 支持度。目前支持的构建模式如下。
+
+| 构建模式 | 文件名 | 支持的自定义后端 | 产物使用方式 |
+| -------- | ------ | ---------------- | ------------ |
+| all | glass_easel.all | 支持全部后端（运行时自动选择） | CommonJS |
+| shadow | glass_easel.shadow | 支持 shadow 模式后端 | CommonJS |
+| shadow-global | glass_easel.shadow.global | 支持 shadow 模式后端 | 全局变量 |
+| composed | glass_easel.composed | 支持 composed 模式后端 | CommonJS |
+| composed-global | glass_easel.composed.global | 支持 composed 模式后端 | 全局变量 |
+| domlike | glass_easel.domlike | 支持 DOM 后端 | CommonJS |
+| domlike-global | glass_easel.domlike.global | 支持 DOM 后端 | 全局变量 |
+
+一次可以同时启用多个构建模式。在 node.js 和打包工具中，第一个构建模式会视为被 import 时采用的构建结果。
+
+额外参数可以修饰构建结果：
+
+* `--minimize` / `--no-minimize` 可以启用、禁用代码压缩混淆；
+* `--dev` 可以激活 development 构建模式。
+
+例如，如果想要构建出支持全部后端和全局量模式 DOM 后端的两种构建结果、同时禁用代码压缩混淆，则 `GLASS_EASEL_ARGS` 环境变量应设为：
+
+```
+all domlike-global --no-minimize
+```

package/guide/zh_CN/advanced/component_filter.md

@@ -0,0 +1,70 @@
+# 组件构造器中间件
+
+## Definition Filter
+
+在定义组件时， glass-easel 允许一些简易的中间件来调整组件定义。
+
+对于 definition API ，可以使用 `definitionFilter` 。例如，可以定义一个中间件，用来检查是否有属性没有定义初始值：
+
+```js
+export const propCheck = componentSpace.defineBehavior({
+  definitionFilter(def) {
+    // def 是定义组件时传入的组件定义对象
+    if (def.properties) {
+      Object.keys(def.properties).forEach((propName) => {
+        const prop = def.properties[propName]
+        if (prop.value === undefined) {
+          console.warn(`Forget property initial value of "${propName}"`)
+        }
+      })
+    }
+  }
+})
+```
+
+中间件表现为一个 behavior 的形式。在组件中引用这个 behavior 时，中间件会被自动触发，例如：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  // 引入含有 definitionFilter 的 behavior
+  hehaviors: [propCheck],
+  properties: {
+    a: {
+      type: String,
+    },
+  },
+})
+```
+
+## Chaining Filter
+
+对于 Chaining API ，可以使用 `chainingFilter` 。它允许修改链式调用中的调用链函数。例如：
+
+```js
+export const propCheck = componentSpace.define()
+  .chainingFilter((chain) => {
+    return Object.create(chain, {
+      property: {
+        value(propName, prop) {
+          if (prop.value === undefined) {
+            console.warn(`Forget property initial value of "${propName}"`)
+          }
+          chain.property(propName, prop)
+        }
+      },
+    })
+  })
+  .registerBehavior()
+```
+
+使用这个 behavior 时，要在链式调用靠前的地方引用：
+
+```js
+export const myComponent = componentSpace.define()
+  // 引入含有 chainingFilter 的 behavior
+  .behavior(propCheck)
+  .property('a', {
+    type: String,
+  })
+  .registerComponent()
+```

package/guide/zh_CN/advanced/component_space.md

@@ -0,0 +1,124 @@
+# 组件空间
+
+## 定义组件空间
+
+组件空间是一组组件的集合。定义组件时，需要将它定义在某个组件空间里。
+
+```js
+// 创建一个组件空间
+const componentSpace = new glassEasel.ComponentSpace()
+
+// 在这个组件空间中添加一个 hello-world 组件
+export const helloWorld = componentSpace.defineComponent({
+  is: 'hello-world',
+})
+```
+
+在使用组件名字来指定组件时，只会在当前组件空间中查找组件，例如：
+
+```js
+componentSpace.defineComponent({
+  using: {
+    // 在同一个组件空间下查找名为 hello-world 的组件
+    hello: 'hello-world',
+  },
+})
+```
+
+## 默认组件选项
+
+组件空间可以为其中的组件指定一部分组件选项，这样，一些组件选项就不需要在每个组件定义时单独设置，例如：
+
+```js
+componentSpace.updateComponentOptions({
+  multipleSlots: true,
+})
+```
+
+这个组件空间中接下来定义的组件将统一具有这些选项。
+
+## 默认组件
+
+在组件空间中可以定义一个默认组件，当组件定义未找到时，会使用默认组件来代替。
+
+通常，默认组件的名字是空字符串 `''` ，定义一个该名字的组件就可以将它作为默认组件：
+
+```js
+export const helloWorld = componentSpace.defineComponent({
+  is: '',
+})
+```
+
+## 基组件空间
+
+组件空间在创建时，可以导入另一个组件空间中的 **公开组件** 。例如：
+
+```js
+// 创建一个基组件空间
+const baseComponentSpace = new glassEasel.ComponentSpace()
+
+// 在基组件空间中定义一个组件
+baseComponentSpace.defineComponent({
+  is: 'base-component',
+})
+
+// 导出这个组件为公开组件
+baseComponentSpace.exportComponent('base-component', 'base-component')
+
+// 创建另一个组件空间，指定基组件空间
+const baseComponentSpace = new glassEasel.ComponentSpace('', baseComponentSpace)
+
+// 可以使用基组件空间中导出的组件
+componentSpace.defineComponent({
+  using: {
+    base: 'base-component',
+  },
+})
+```
+
+## 导入组件空间
+
+组件空间中的公开组件可以被其他组件空间导入，例如：
+
+```js
+// 创建一个组件空间
+const componentSpaceA = new glassEasel.ComponentSpace()
+
+// 在基组件空间中定义一个组件
+componentSpaceA.defineComponent({
+  is: 'a-component',
+})
+
+// 导出这个组件，并为它命一个公开的名字
+componentSpaceA.exportComponent('public-name', 'a-component')
+
+// 创建另一个组件空间
+const componentSpaceB = new glassEasel.ComponentSpace()
+
+// 导入组件空间并指定它的引用 URL 前缀
+componentSpaceB.importSpace('space://space-a', componentSpaceA, false)
+
+// 可以使用导入的组件空间中定义的组件
+componentSpaceB.defineComponent({
+  using: {
+    base: 'space://space-a/public-name',
+  },
+})
+```
+
+在导入组件空间时，也可以导入它的所有组件（不只是公开组件），例如：
+
+```js
+// 创建另一个组件空间
+const componentSpaceC = new glassEasel.ComponentSpace()
+
+// 导入组件空间中的全部组件
+componentSpaceC.importSpace('space-private://space-a', componentSpaceA, true)
+
+// 可以使用导入的组件空间中定义的组件
+componentSpaceC.defineComponent({
+  using: {
+    base: 'space-private://space-a/a-component',
+  },
+})
+```

package/guide/zh_CN/advanced/custom_backend.md

@@ -0,0 +1,53 @@
+# 自定义后端
+
+# 渲染后端
+
+glass-easel 不仅可以用于 DOM 环境下，它还可以支持其他的 **渲染后端** 。
+
+glass-easel 可以将它生成的节点树传递给渲染后端。最常见的渲染后端就是 DOM ： glass-easel 可以将节点树转换为一些 DOM 调用（如 `document.createElement` 等），然后在浏览器的页面上展示出来。除此之外，在非浏览器环境下，也可以自行实现一些其他渲染后端，接收 glass-easel 生成的节点树、展示界面。
+
+渲染后端必须实现 [自定义后端协议](../appendix/backend_protocol.md) ，这个协议有三种模式，支持其中任意一种即可。
+
+| 协议模式 | 主 TypeScript 接口 | 说明 |
+| -------- | --------------- | ---- |
+| Composed Mode | `glassEasel.composedBackend.Context` | 首选的协议，相对简单易用 |
+| Shadow Mode | `glassEasel.backend.Context` | 针对 Shadow Tree 的协议，整体性能通常是最优的，但是协议本身比较复杂 |
+| DOM-like Mode | `glassEasel.domlikeBackend.Context` | 适用于 DOM 的协议，通常只应该用于适配 DOM 接口 |
+
+实现渲染后端时，需要实现对应的 TypeScript 接口，例如：
+
+```ts
+// 一个渲染后端实现
+class MyCustomBackend implements glassEasel.composedBackend.Context {
+  // ...
+}
+```
+
+# 使用自定义的渲染后端
+
+要使用一个渲染后端，需要在根组件创建时传入对应的 `Context` 对象：
+
+```js
+// 创建后端实例
+const myCustomBackend = new MyCustomBackend()
+
+// 连接事件系统
+backendContext.onEvent((target, type, detail, options) => {
+  const ev = new glassEasel.Event(type, detail, options)
+  glassEasel.Event.dispatchEvent(target, ev)
+  return ev.defaultPrevented()
+    ? glassEasel.EventBubbleStatus.NoDefault
+    : glassEasel.EventBubbleStatus.Normal
+})
+
+// 创建根组件实例
+const rootComponent = glassEasel.Component.createWithContext('body', helloWorld, myCustomBackend)
+
+// 将组件插入到渲染后端的节点树中
+const rootNode = myCustomBackend.getRootNode()
+const placeholder = myCustomBackend.createElement('placeholder')
+rootNode.appendChild(placeholder)
+glassEasel.Element.replaceDocumentElement(rootComponent, rootNode, placeholder)
+placeholder.release()
+rootNode.release()
+```

package/guide/zh_CN/advanced/error_listener.md

@@ -0,0 +1,32 @@
+# 警告与错误
+
+# 错误监听器
+
+在组件生命周期、事件回调中抛出的异常，会被 glass-easel 捕获。想要获取这些异常，可以注册一个错误监听器：
+
+```js
+glassEasel.addGlobalErrorListener((err, { element }) => {
+  err // 捕获的异常对象
+  if element instanceof glassEasel.Comonent {
+    element // 与这个异常相关的组件
+  }
+  // 返回 false 将取消 console 输出
+  return false
+})
+```
+
+如果没有监听器或者监听器都没返回 `false` ，则错误信息会被输出到 console 中。如果 `glassEasel.globalOptions.throwGlobalError` 被设为 `true` ，则它会被再次抛出到全局。
+
+# 警告监听器
+
+glass-easel 也会产生一些警告用于提示一些常见的误用情况。默认情况下，警告会输出到 console 中。
+
+类似于错误，警告也可以被监听到，例如：
+
+```js
+glassEasel.addGlobalWarningListener((message) => {
+  message // 警告信息
+  // 返回 false 将取消 console 输出
+  return false
+})
+```

package/guide/zh_CN/advanced/external_component.md

@@ -0,0 +1,73 @@
+# 外部组件
+
+## 使用外部组件来提升性能
+
+有些时候，出于性能或一些特殊原因，可以使一个组件内部的实现不通过 Shadow Tree 维护，而是直接通过 DOM 接口或 [自定义后端](custom_backend.md) 接口来维护。
+
+在组件中添加 `externalComponent` 选项，就可以使它成为一个外部组件，例如：
+
+```js
+componentSpace.defineComponent({
+  options: {
+    externalComponent: true,
+  },
+})
+```
+
+这种模式下的组件通常具有很好的性能，但部分特性不可用：
+
+* 模板中的 `wx:if` `wx:for` 不可用，仅支持 [虚拟树更新](binding_map_update.md) ；
+* 由于没有 Shadow Tree ，所有与之相关的树遍历方式（如选择器查询）都不能访问到组件内的节点；
+* 大部分 DOM 未提供的对应特性不可用，如外部样式类、复杂事件监听器等。
+
+## 外部组件与自定义模板引擎
+
+外部组件也可以与 [自定义模板引擎](template_engine.md) 一起使用，这样就可以使得部分 DOM 节点完全脱离 glass-easel 的维护。当需要其他第三方框架来维护部分 DOM 节点时，这个方式很实用。
+
+此时，自定义模板引擎在实现 `TemplateInstance` 接口时，返回的 `shadowRoot` 必须是 `glassEasel.ExternalShadowRoot` 类型的，例如：
+
+```js
+class MyTemplateEngine {
+  create(rootBehavior, options) {
+    behavior.getTemplate() // 组件的 template 字段内容
+    // 检测组件是不是被定义为外部组件
+    if (!options.externalComponent) {
+      throw new Error('The template engine can only be used in external component')
+    }
+    return new MyTemplate()
+  }
+}
+
+class MyTemplate {
+  createInstance(component) {
+    return new MyTemplateInstance(component)
+  }
+}
+
+class MyTemplateInstance {
+  constructor(component) {
+    // 以外部组件形式使用
+    this.shadowRoot = {
+      root: document.body, // 用作 shadowRoot 的节点
+      slot: document.createElement('span'), // 用作 slot 的节点
+      getIdMap() {
+        // 返回节点 id 到节点的映射表
+      },
+      handleEvent(target, event) {
+        // 触发一个事件
+      },
+      setListener(element, event, listener) {
+        // 添加一个事件监听器
+      },
+    }
+  }
+
+  initValues(data) {
+    // 组件被创建，初始数据是 data
+  }
+
+  updateValues(data, changes) {
+    // 组件更新，新的数据是 data ，变更内容描述在 changes 中
+  }
+}
+```

package/guide/zh_CN/advanced/template_engine.md

@@ -0,0 +1,61 @@
+# 自定义模板引擎
+
+## 模板引擎简介
+
+模板引擎是处理模板、在模板上应用数据绑定更新的模块。
+
+glass-easel 的默认模板引擎是 `glassEasel.glassEaselTemplate` ，但也可以通过更改组件 options 来指定另一个自定义的模块作为模板引擎。
+
+自定义模板引擎必须实现 TypeScript 接口 `glassEasel.templateEngine.TemplateEngine` 。
+
+## 模板引擎接口
+
+`glassEasel.templateEngine.TemplateEngine` 接口需要实现一个 `create` 方法。这个方法对每个组件定义执行一次。它接受传入的组件定义，传出一个 `glassEasel.templateEngine.Template` 。
+
+`glassEasel.templateEngine.Template` 接口需要实现一个 `createInstance` 方法。这个方法在每个组件实例创建时执行一次。它需要生成一个 `glassEasel.templateEngine.TemplateInstance` 。
+
+`glassEasel.templateEngine.TemplateInstance` 则需要提供一个 `shadowRoot` 节点（调用 `glassEasel.ShadowRoot.createShadowRoot` 来获得）作为组件实例的 `this.shadowRoot` 。还需要实现 `initValues` 和 `updateValues` ，分别用于创建初始节点树、更新数据绑定。
+
+实现模板引擎时，常常需要用到 [节点树变更](../tree/node_tree_modification.md) 接口。
+
+## 自定义模板引擎示例
+
+自定义模板引擎的实现可以大体上以下例表示：
+
+```js
+class MyTemplateEngine {
+  create(rootBehavior, options) {
+    behavior.getTemplate() // 组件的 template 字段内容
+    return new MyTemplate()
+  }
+}
+
+class MyTemplate {
+  createInstance(component) {
+    return new MyTemplateInstance(component)
+  }
+}
+
+class MyTemplateInstance {
+  constructor(component) {
+    this.shadowRoot = ShadowRoot.createShadowRoot(component)
+  }
+
+  initValues(data) {
+    // 组件被创建，初始数据是 data
+  }
+
+  updateValues(data, changes) {
+    // 组件更新，新的数据是 data ，变更内容描述在 changes 中
+  }
+}
+
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    templateEngine: MyTemplateEngine,
+  },
+  template: {
+    // 这部分内容由 MyTemplateEngine 来处理
+  },
+})
+```