glass-easel 0.1.0

package/guide/zh_CN/interaction/relation.md

@@ -0,0 +1,151 @@
+# 组件间关系
+
+## 基于组件的 relations
+
+有时会遇到一些组件相互之间存在紧密的逻辑联系，在它们作为父子节点被联合使用时，需要执行一些额外的逻辑。
+
+例如，需要实现表单控件 `<form>` `<input>` ，而它们之间有紧密的关联逻辑。此时可以使用 relations ，使它们之间可以相互获取组件实例 `this` ：
+
+```js
+// form 组件，需要关联到子孙节点中的 input 组件
+export const formComponent = componentSpace.defineComponent({
+  is: 'component/form',
+  relations: {
+    // 需要关联到 input 组件
+    './input': {
+      // 关联范围是子孙节点
+      type: 'descendant',
+      linked(target) {
+        // 每当有 input 组件插入时，这个函数会执行一次
+        // 参数中的 target 是 input 组件实例
+        // 使用 getRelationNodes 可以获取当前关联到的所有 input 组件
+        this.getRelationNodes('./input')
+      },
+      unlinked(target) {
+        // 每当有 input 组件移除时，这个函数会执行一次
+      },
+    }
+  },
+})
+
+// input 组件，需要关联到祖先节点中的 form 组件
+export const myComponent = componentSpace.defineComponent({
+  is: 'component/input',
+  relations: {
+    // 需要关联到 form 组件
+    './form': {
+      // 关联范围是祖先节点
+      type: 'ancestor',
+      linked(target) {
+        // 关联到 form 组件时，这个函数会执行一次
+      },
+      linkFailed() {
+        // 没有关联到 form 组件时，这个函数会执行一次
+      },
+    }
+  },
+})
+
+// 同时使用这两个组件
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    form: formComponent,
+    input: inputComponent,
+  },
+  template: compileTemplate(`
+    <form>
+      <input />
+    </form>
+  `),
+})
+```
+
+这样， `<form>` 和 `<input>` 可以实现更复杂的关联逻辑。
+
+目前 relation 支持的关联范围有以下这些。
+
+| 关联范围 | 含义 |
+| ---- | ---- |
+| `ancestor` | 需关联到一个祖先组件 |
+| `descendant` | 可关联到若干子孙组件 |
+| `parent` | 需关联到一个祖先组件，但中间不能间隔其他组件节点 |
+| `child` | 可关联到若干子孙组件，但中间不能间隔其他组件节点 |
+| `parent-common-node` | 需关联到一个祖先组件，但中间不能间隔其他普通节点或组件节点 |
+| `child-common-node` | 可关联到若干子孙组件，但中间不能间隔其他普通节点或组件节点 |
+
+注意：它们必须成对使用，只在一个节点上声明 `relations` 、使用不成对的关联范围都是无效的。
+
+每个 relation 定义都包含了四个 relation 生命周期。
+
+| relation 生命周期 | 首个参数 | 触发时机 |
+| ----------------- | -------- | -------- |
+| `linked` | 对应组件实例 this | 每当关联到新的组件实例 |
+| `linkChanged` | 对应组件实例 this | 每当有关联到的组件实例发生了移动 |
+| `unlinked` | 对应组件实例 this | 每当有关联到的组件实例被移除 |
+| `linkFailed` | （无） | 当未找到需要关联的祖先组件时 |
+
+## 基于 trait behavior 的 relations
+
+如果建立 relations 的组件不是某个特定的组件，而是一类组件，则可以使用 behaviors 或者 trait behaviors 来规定 relations 。
+
+例如，表单组件 `<form>` 需要关联 `<input>` `<button>` 等一类组件，可以对 `<input>` `<button>` 实现同一个 trait behavior ，这样也会有更好的 TypeScript 类型支持。这种情况下，使用 init 来实现比较好：
+
+```ts
+// 定义一个公共的 trait behavior
+interface FormControlInterface {
+  getName(): string
+  getValue(): string
+}
+const FormControl = componentSpace.defineTraitBehavior<FormControlInterface>()
+
+// 定义 form 组件
+export const formComponent = componentSpace.define()
+  .init(function ({ implement, relation }) {
+    // 关联到所有 FormControl
+    const rel = relation({
+      type: 'descendant',
+      target: FormControl,
+      linked(target) {
+        // 获得目标节点对 trait behavior 的实现
+        const impl = target.traitBehavior(FormControl)
+        impl.getName()
+        impl.getValue()
+      },
+    })
+    // 获取当前关联到的所有组件
+    rel.list()
+  })
+  .registerComponent()
+
+// 定义 input 组件
+export const inputComponent = componentSpace.define()
+  .init(function ({ implement, relation }) {
+    // 实现 FormControl
+    implement(FormControl, {
+      getName() { return '...' },
+      getValue() { return '...' },
+    })
+    // 关联到 form
+    relation({
+      type: 'ancestor',
+      target: formComponent,
+    })
+  })
+  .registerComponent()
+
+// 定义 button 组件
+export const buttonComponent = componentSpace.define()
+  .init(function ({ implement, relation }) {
+    // 实现 FormControl
+    implement(FormControl, {
+      getName() { return '...' },
+      getValue() { return '...' },
+    })
+    // 关联到 form
+    relation({
+      type: 'ancestor',
+      target: formComponent,
+    })
+  })
+  .registerComponent()
+```

package/guide/zh_CN/interaction/slot.md

@@ -0,0 +1,137 @@
+# slot 及 slot 类型
+
+## 单一 slot
+
+子组件可以通过 `<slot />` 节点来承载它在父组件上的子树内容，例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  template: compileTemplate(`
+    <div>
+      <slot />
+    </div>
+  `),
+})
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div>
+      <child>
+        <div class="a" />
+      </child>
+    </div>
+  `),
+})
+```
+
+上例中 `<div class="a" />` 将被放置到子组件中的 `<slot />` 位置上。
+
+## 多 slot
+
+有时子组件需要放置多个 slot 节点。此时可以指定组件的 `multipleSlots` 选项，并使用 `name` 来区分多个节点，例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    multipleSlots: true,
+  },
+  template: compileTemplate(`
+    <div>
+      <slot name="body" />
+    </div>
+    <slot name="footer" />
+  `),
+})
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div>
+      <child>
+        <div slot="body"> 这段内容被插入到 name="body" 的 slot 中 </div>
+        <div slot="footer"> 这段内容被插入到 name="footer" 的 slot 中 </div>
+      </child>
+    </div>
+  `),
+})
+```
+
+glass-easel 本身为单一 slot 应用了更多优化。激活 `multipleSlots` 同时也禁用了一些优化，对于不需要多 slot 的组件，最好不要激活这个选项。
+
+## 动态 slot
+
+上述两种 slot 类型要求（相同 name 的） slot 节点只有一个，重复的 `<slot />` 中只有第一个会生效。
+
+但有时，需要在列表中放置 `<slot />` ，表示将 slot 内容重复多次。此时需要指定组件的 `dynamicSlots` 选项，例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    dynamicSlots: true,
+  },
+  template: compileTemplate(`
+    <block wx:for="{{ list }}">
+      <slot />
+    </div>
+  `),
+  data: {
+    list: ['A', 'B', 'C'],
+  },
+})
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div>
+      <child>
+        <div class="a" />
+      </child>
+    </div>
+  `),
+})
+```
+
+当 `dynamicSlots` 选项激活时，还可以向 slot 中传递数据，组件的使用者可以通过 `slot:` 来接收 slot 传递的数据，例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    dynamicSlots: true,
+  },
+  template: compileTemplate(`
+    <block wx:for="{{ list }}">
+      <slot list-index="{{ index }}" item="{{ item }}" />
+    </div>
+  `),
+  data: {
+    list: ['A', 'B', 'C'],
+  },
+})
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div>
+      <child>
+        <div class="a" slot:item>{{ item }}</div>
+      </child>
+    </div>
+  `),
+})
+```
+
+使用 `slot:` 来接收数据时，也可以用 `=` 来指定一个别名。此外，接收数据的节点也可以是 `<block />` 。例如：
+
+```xml
+<child>
+  <div class="a" slot:listIndex="index">{{ index }}</div>
+  <block slot:item>{{ item }}</div>
+</child>
+```
+
+通过 slot 传递的数据受到 [数据字段拷贝控制](../data_management/data_deep_copy.md) 选项中的 `propertyPassingDeepCopy` 选项控制。

package/guide/zh_CN/interaction/template_import.md

@@ -0,0 +1,94 @@
+# 多文件模板
+
+## 模板片段
+
+模板中可以使用 `<template>` 来提取一些公共的模板片段。
+
+其中， `<template name="...">` 可以用来定义模板片段，片段中可以使用数据绑定，例如：
+
+```xml
+<template name="shared-template-slice">
+  <div> {{ a }} + {{ b }} = {{ c }} </div>
+</template>
+```
+
+而 `<template is="...">` 可以用来引用模板片段，引用时需要指定数据绑定，例如：
+
+```xml
+<template is="shared-template-slice" data="{{ a: 1, b: 2 }}"></template>
+```
+
+注意， `data="{{ }}"` 内部就是一个对象形式定义。
+
+## 跨组件的模板片段
+
+如果需要在多个组件中使用同一个模板片段，则需要调整模板编译方式。
+
+在模板编译时，首先需要创建一个 `TmplGroup` 对象。这个对象可以同时管理多个路径的模板代码，例如：
+
+```js
+import { TmplGroup } from 'glass-easel-template-compiler'
+
+const group = new TmplGroup()
+
+// 添加一个模板路径及其对应的模板内容
+group.addTmpl('path/to/a/component', `
+  <div> text in a template </div>
+`)
+
+// 添加另一个模板路径及其对应的模板内容
+group.addTmpl('path/to/another/component', `
+  <div> text in another template </div>
+`)
+
+// 生成模板编译结果
+const genObjectSrc = `return ${group.getTmplGenObjectGroups()}`
+const genObjectGroupList = (new Function(genObjectSrc))() as { [key: string]: any }
+group.free()
+
+// 从编译结果中提取指定路径的模板
+const templateForAComponent = {
+  groupList: genObjectGroupList,
+  content: genObjectGroupList['path/to/a/template'],
+}
+const templateForAnotherComponent = {
+  groupList: genObjectGroupList,
+  content: genObjectGroupList['path/to/another/template'],
+}
+```
+
+这样，可以使用一个独立的模板路径来存放公共的模板片段，例如：
+
+```js
+group.addTmpl('path/to/shared', `
+  <template name="shared-template-slice">
+    <div> {{ a }} + {{ b }} = {{ c }} </div>
+  </template>
+`)
+```
+
+在其他路径的模板中，可以使用 `<import>` 引入模板片段：
+
+```js
+group.addTmpl('path/to/a/component', `
+  <import src="../shared" />
+
+  <template is="shared-template-slice" data="{{ a: 1, b: 2 }}" />
+`)
+```
+
+## 模板文件引入
+
+在引用其他路径的模板时，也可以使用 `<include>` 直接将整个模板文件内容嵌入到当前位置上，例如：
+
+```js
+group.addTmpl('path/to/shared', `
+  <div> some text in shared template </div>
+`)
+
+group.addTmpl('path/to/a/component', `
+  <div>
+    <include src="../shared" />
+  </div>
+`)
+```

package/guide/zh_CN/interaction/trait_behavior.md

@@ -0,0 +1,117 @@
+# Trait Behaviors
+
+## 定义和实现 trait behavior
+
+trait behaviors 是一种组件间共享接口的机制，也可以用于给组件归类（类似于一些编程语言的 trait ）。
+
+在 TypeScript 下，通过 trait behaviors ，可以定义一组接口方法，若干组件都可以实现这组接口方法。这样，在外部访问这些组件时，可以不关注组件具体是什么，只需要关心组件提供的接口。例如，在 TypeScript 中定义并实现一个 trait behavior ：
+
+```ts
+// 定义一个 trait behavior
+interface AddMinus {
+  add(a: number, b: number): number
+  minus(a: number, b: number): number
+}
+const addMinusTrait = componentSpace.defineTraitBehavior<AddMinus>()
+
+// 使用 Chaining API 实现 trait behavior
+const childComponent = componentSpace.define()
+  .implement(addMinusTrait, {
+    add(a, b) {
+      return a + b
+    },
+    minus(a, b) {
+      return a - b
+    },
+  })
+  .defineComponent()
+// 或在 init 中实现 trait behavior
+const childComponent = componentSpace.define()
+  .init(function ({ implement }) {
+    implement(addMinusTrait, {
+      add(a, b) {
+        return a + b
+      },
+      minus(a, b) {
+        return a - b
+      },
+    })
+  })
+  .defineComponent()
+```
+
+在从组件外访问这个组件时，可以使用 trait behavior ：
+
+```ts
+const myComponent = componentSpace.define()
+  .usingComponents({
+    child: childComponent,
+  })
+  .template(compileTemplate(`
+    <child id="c" />
+  `))
+  .lifetime('attached', function () {
+    // 获取到子组件对应的节点
+    const child = this.shadowRoot.querySelector('#c')!
+    // 获得它对应的 addMinusTrait 的实现
+    const impl = child.traitBehavior(addMinusTrait)!
+    // 调用其中方法
+    impl.add(1, 2) === 3 // true
+    impl.minus(5, 3) === 2 // true
+  })
+```
+
+这样，在使用组件时就不需要关心组件具体实现，只需要关心组件提供的 trait behavior ，利于代码解耦。
+
+## 含接口转换的 trait behavior
+
+trait behavior 本身可以做一些接口转换，使得提供的接口比需要实现的接口更丰富。
+
+例如， `addMinusTrait` 提供 `add` 和 `minus` 两个接口方法，但可以只要求实现者实现 `add` 接口方法：
+
+```ts
+interface Add {
+  add(a: number, b: number): number
+}
+interface AddMinus {
+  add(a: number, b: number): number
+  minus(a: number, b: number): number
+}
+// 这个 trait behavior 要求实现 add 接口方法，但可以提供 add 和 minus 两个接口方法
+const addMinusTrait = componentSpace.defineTraitBehavior<Add, AddMinus>((impl) => ({
+  // 具体而言：
+  // 入参中的 impl 是对 interface Add 的实现
+  // 这里需要返回对 interface AddMinus 的实现
+  add(a: number, b: number): number {
+    return impl.add(a, b)
+  },
+  // 需要额外实现 minus 接口方法
+  minus(a: number, b: number): number {
+    return impl.add(a, -b)
+  },
+}))
+
+const childComponent = componentSpace.define()
+  .implement(addMinusTrait, {
+    // 对于实现者，只需要实现 add 接口方法
+    add(a, b) {
+      return a + b
+    }
+  })
+  .defineComponent()
+
+const myComponent = componentSpace.define()
+  .usingComponents({
+    child: childComponent,
+  })
+  .template(compileTemplate(`
+    <child id="c" />
+  `))
+  .lifetime('attached', function () {
+    const child = this.shadowRoot.querySelector('#c')!
+    const impl = child.traitBehavior(addMinusTrait)!
+    // 可以调用 add 和 minus 两个接口
+    impl.add(1, 2) === 3 // true
+    impl.minus(5, 3) === 2 // true
+  })
+```

package/guide/zh_CN/styling/external_class.md

@@ -0,0 +1,46 @@
+# 外部样式类
+
+有时，一个组件的部分样式规则需要由它的使用者来指定。此时可以使用 **外部样式类** 。
+
+组件可以指定它自身的一些 class 可以由组件外传递，例如：
+
+```js
+// 使用 Definition API 指定外部样式类
+export const childComponent = componentSpace.defineComponent({
+  externalClasses: ['my-class'],
+  // 在模板的 class 中可以使用外部样式类
+  template: compileTemplate(`
+    <div class="my-class" />
+  `),
+})
+// 或使用 Chaining API 指定外部样式类
+export const childComponent = componentSpace.define()
+  .externalClasses(['my-class'])
+  .template(compileTemplate(`
+    <div id="a" class="my-class" />
+  `))
+  .registerComponent()
+```
+
+使用这个组件时，就可以指定：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <child my-class="some-class" />
+  `),
+})
+```
+
+这样，子组件中的 `<div id="a" />` 就会最终应用 `.some-class` 的样式规则：
+
+```css
+.some-class {
+  /* ... */
+}
+```
+
+即使启用了 [样式隔离](style_isolation.md) ，外部样式类依然可用。

package/guide/zh_CN/styling/style_isolation.md

@@ -0,0 +1,54 @@
+# 样式隔离
+
+glass-easel 的默认设置中，组件之间的样式是共享的。如果想将一个样式表仅用于一个组件，可以考虑启用 style scope 支持。
+
+在 DOM 环境下， style scope 要求样式表预处理时对样式表中的 class 都添加一个前缀，例如：
+
+```css
+.my-prefix--header {
+  font-size: 1.5em;
+}
+.my-prefix--footer {
+  font-size: 0.9em;
+}
+```
+
+通过 `glass-easel-stylesheet-compiler` 工具可以为样式表添加固定的前缀，具体用法请参考它的相关文档。
+
+添加前缀后，可以注册一个 style scope ：
+
+```js
+const myStyleScope = componentSpace.styleScopeManager.register('my-prefix')
+```
+
+组件定义时，可以指定它使用这个 style scope ：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    styleScope: myStyleScope,
+  },
+  template: compileTemplate(`
+    <div class="header" />
+    <div class="footer" />
+  `)
+})
+```
+
+如果指定了 style scope ，模板中的所有 class 指定的样式将只应用含有前缀的 class 样式规则。
+
+若想要同时应用无前缀和含前缀两种 class 样式规则，可以改用 `extraStyleScope` 选项：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  options: {
+    extraStyleScope: myStyleScope,
+  },
+  template: compileTemplate(`
+    <div class="header" />
+    <div class="footer" />
+  `)
+})
+```
+
+[自定义后端](../advanced/custom_backend.md) 对样式隔离的支持方式略有不同，请参考它的相关文档。

package/guide/zh_CN/styling/virtual_host.md

@@ -0,0 +1,52 @@
+# 虚拟组件节点
+
+默认情况下，代表组件的节点本身会和普通节点一样接收 class 和 style ，例如：
+
+```js
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  template: compileTemplate(`
+    <div class="a" style="color: red" />
+    <child class="b" style="color: blue" />
+  `)
+})
+```
+
+在 DOM 节点树上， `<child>` 节点本身也会生成一个对应的 DOM 节点，使其能直接使用 class 和 style ；但这也使得一些情况下布局难以控制，例如在使用 flex 布局时， `<child>` 节点本身会成为一个 flex 内容项。
+
+通过指定组件的 `virtualHost` 选项，可以改变这一行为，使其本身不生成一个对应的 DOM 节点，这样：
+
+* flex 布局时，它本身不作为 flex 内容项参与布局；
+* 节点本身的 class 和 style 失效。
+
+虽然节点本身的 class 和 style 会失效，但可以将 class 定义为一个 [外部样式类](external_class.md) 、可以将 style 定义为一个属性，这样就可以用上它们，例如：
+
+```js
+export const childComponent = componentSpace.defineComponent({
+  options: {
+    virtualHost: true,
+  },
+  // 将 class 作为一个外部样式类
+  externalClasses: ['class'],
+  // 将 style 作为一个属性
+  properties: {
+    style: String,
+  },
+  // 将 class 和 style 应用到组件内部的节点上
+  template: compileTemplate(`
+    <div class="class" style="{{ style }}" />
+  `),
+})
+
+export const myComponent = componentSpace.defineComponent({
+  using: {
+    child: childComponent,
+  },
+  // 同样可以使用 class 和 style
+  template: compileTemplate(`
+    <child class="b" style="color: blue" />
+  `)
+})
+```