compelem 0.2.1-beta → 0.2.3-beta

package/CompElem.d.ts

@@ -71,7 +71,7 @@ export declare class CompElem extends CompElem_base implements IComponent {
      * dom渲染完毕后调用，该回调内可以query注解初始化完成
      */
     mounted(): void;
-    slotchange(slot: HTMLSlotElement, name: string): void;
+    slotChange(slot: HTMLSlotElement, name: string): void;
     /**
      * 是否需要更新，可获取变更属性
      * 返回true时更新

package/IComponent.d.ts

@@ -20,7 +20,7 @@ export interface IComponent {
     mounted(): void;
     shouldUpdate(changed: Record<string, any>): boolean;
     updated(changed: Record<string, any>): void;
-    slotchange(slot: HTMLSlotElement, name: string): void;
+    slotChange(slot: HTMLSlotElement, name: string): void;
     /**
      * 抛出自定义事件
      * @param evName 事件名称

package/README.md

@@ -1,111 +1,101 @@
 # CompElem
+一个现代化、响应式、快速、轻量的WebComponent开发库。为开发者提供丰富、灵活、可扩展的声明式接口
 
-一个现代化、响应式、快速、轻量的 WebComponent 开发库。为开发者提供丰富、灵活、可扩展的声明式接口
-
-## 概览
-
+## 概览  
 CompElem 基于 Class 进行构建，该模型允许开发者使用装饰器进行声明式编码，核心特性包括：
-
-- 类 JSX 的原生模板系统
+- 类JSX的原生模板系统
 - 丰富的装饰器及指令
 - 可选的生命周期
 - 原生插槽系统
 - 响应式域样式
 - ...
 
-创建一个 WebComponent 总会从声明一个组件元素(CompElem 子类)开始
-
+创建一个WebComponent总会从声明一个组件元素(CompElem子类)开始
 ```ts
-const Slogan = ["complete", "componentize", "compact", "companion"];
+const Slogan = ['complete', 'componentize', 'compact', 'companion']
 @tag("page-test")
 export class PageTest extends CompElem {
   //////////////////////////////////// props
-  @prop arg: any;
+  @prop arg:any
 
-  @state colorR = (Math.random() * 255) % 255 >> 0;
-  @state colorG = (Math.random() * 255) % 255 >> 0;
-  @state colorB = (Math.random() * 255) % 255 >> 0;
-  @state rotation = 0;
+  @state colorR = Math.random() * 255 % 255 >> 0;
+  @state colorG = Math.random() * 255 % 255 >> 0;
+  @state colorB = Math.random() * 255 % 255 >> 0;
+  @state rotation = 0
 
   //////////////////////////////////// computed
   @computed
   get color() {
-    return `linear-gradient(90deg,rgb(${this.colorR},${this.colorG},${
-      this.colorB
-    }), rgb(${255 - this.colorR},${255 - this.colorG},${255 - this.colorB}));`;
+    return `linear-gradient(90deg,rgb(${this.colorR},${this.colorG},${this.colorB}), rgb(${255 - this.colorR},${255 - this.colorG},${255 - this.colorB}));`
   }
 
   //////////////////////////////////// watch
-  @watch("rotation")
-  function(nv: number) {
-    console.log(nv);
+  @watch('rotation')
+  function(nv:number) {
+    console.log(nv)
   }
 
   //////////////////////////////////// styles
   //静态样式
   static get styles(): Array<string | CSSStyleSheet> {
-    return [
-      `:host{
+    return [`:host{
         font-size:16px;
-      }...`,
-    ];
+      }...`];
   }
   //动态样式
   get css() {
     return `h2,p,i,h3{
       background-image:${this.color}
       filter:hue-rotate(${this.rotation}deg)
-    }`;
+    }`
   }
 
   @query('i[name="text"]')
-  text: HTMLElement;
-  sloganIndex = 0;
+  text: HTMLElement
+  sloganIndex = 0
 
   //////////////////////////////////// lifecycles
   mounted(): void {
     setInterval(() => {
-      this.rotation += 1;
+      this.rotation += 1
     }, 24);
 
     setInterval(() => {
-      this.text.classList.add("hide");
+      this.text.classList.add('hide')
       setTimeout(() => {
-        this.text.innerHTML = Slogan[this.sloganIndex % 4];
-        this.sloganIndex++;
-        this.text.classList.remove("hide");
+        this.text.innerHTML = Slogan[this.sloganIndex % 4]
+        this.sloganIndex++
+        this.text.classList.remove('hide')
       }, 500);
     }, 5000);
   }
   render(): Template {
     return html`<div>
-      <i>Welcome to</i>
-      <br />
-      <h2>CompElem</h2>
-      <br />
-      <i>A modern, reactive, fast and lightweight library</i>
-      <br />
-      <i>for building</i>
-      <h3>Web Components</h3>
-      <p>&lt;c-element&gt; <i name="text">...</i> &lt;/c-element&gt;</p>
-      ${this.arg}
-    </div>`;
+            <i>Welcome to</i>
+            <br>
+            <h2>CompElem</h2>
+            <br>
+            <i>A modern, reactive, fast and lightweight library</i>
+            <br>
+            <i>for building</i>
+            <h3>Web Components</h3>
+            <p>
+              &lt;c-element&gt; <i name="text">...</i> &lt;/c-element&gt;
+            </p>
+            ${this.arg}
+        </div>`
   }
 }
 ```
-
-而后即可在 HTML 中直接使用，与使用一个原生元素如 DIV 没有任何区别
-
+而后即可在HTML中直接使用，与使用一个原生元素如DIV没有任何区别
 ```html
 <body>
-  <page-test arg="args..."></page-test>
+    <page-test arg="args..."></page-test>
 </body>
 ```
+当然,也可以直接嵌入其他UI库中只要引入编译后的js即可
 
-当然,也可以直接嵌入其他 UI 库中只要引入编译后的 js 即可
-
-## APIs
-
+## APIs  
 - ### 视图模板
   使用`render()`函数定义组件视图模板
   ```ts
@@ -180,6 +170,22 @@ export class PageTest extends CompElem {
   属性可以在组件内修改但默认不会同步父组件，除非显式指定`sync`或自行 emit update 事件
   全部注解参数见 `PropOption`
 
+  > 在某些无法使用装饰器的场景中（如MixinClass），可以使用函数`makeProp(...)`定义prop
+  ```ts
+  export function Loadable<T extends Constructor<any>>(spuerClass: T) {
+    return class Loadable extends spuerClass {
+        //declare a prop
+        name: string
+
+        constructor(...args: any[]) {
+            super()
+            //make the prop reactive
+            Decorator.call(this, prop, 'name', { type: String })
+        }
+    }
+  }
+  ```
+
 - ### 状态
   状态是仅由组件内部初始化的响应变量，可通过`@state`注解定义
   ```ts
@@ -239,18 +245,19 @@ export class PageTest extends CompElem {
     <div ref="${divRef}"></div>`;
   ```
 - ### 内置属性及函数
-  - `readonly` parent 父组件引用，可能为空
-  - `readonly` el/els 根元素/根元素列表
-  - `readonly` slots 插槽元素
-  - `readonly` slotHooks 动态插槽钩子
+  - `readonly` parentComponent 父组件引用，可能为空
+  - `readonly` renderRoot/renderRoots 渲染根元素/渲染根元素列表
+  - `readonly` shadowRoot 阴影DOM
+  - `readonly` slots 插槽元素映射
+  - `readonly` slotHooks 动态插槽钩子映射
   - `readonly` styles 组件样式对象列表
   - `readonly` attrs 组件特性
   - `readonly` props 组件属性
   - slotComponent 所在插槽组件
-  - on()
-  - emit()
-  - nextTick()
-  - forceUpdate()
+  - on(evName: string, hook: (e: Event) => void) 在root元素上绑定事件
+  - emit(evName: string, arg: Record<string, any>, options?: {event?: Event;bubbles?: boolean;composed?: boolean;}) 抛出自定义事件
+  - nextTick(cbk: () => void) 下一帧执行函数
+  - forceUpdate() 强制更新一次视图
 
 ## 组件渲染流程
 
@@ -263,23 +270,23 @@ CompElem 组件既可以在 CompElem 环境内调用，也可以直接在原生
 | 1. 创建组件实例，完成类属性默认值设置（prop/state/...)       |     |             |
 | 2. 初始化类全局样式（仅一次）及 实例样式(产生 styles 数组)   |     |             |
 | 3. 创建 shadowRoot 并挂载组件样式                            |     | constructor |
-| 4. 绑定 parent                                               |     | connected   |
-| 5. 获取 this.attribute 及 parentProps 进行验证及初始化 props |     | propsReady  |
+| 4. 绑定 parentComponent                                               |     | connected   |
+| 5. 获取 attrs 及 parentProps 进行验证及初始化 props |     | propsReady  |
 | 6. 注入 link 外部样式表                                      |     |             |
 | 7. 渲染 render 及依赖绑定                                    |     | render      |
-| 8. 绑定 el 及 els                                            |     |             |
+| 8. 绑定 renderRoot 及 renderRoots                                            |     |             |
 | 9. 执行 ref                                                  |     |             |
 | 10. 执行 @query 注解                                         |     |             |
 | 11. 执行 @watch(immediate) 注解                              |     |             |
 | 12. 执行 @event 注解                                         |     | mounted     |
-| 13. 执行 slot filter / 动态 slot                             |     | slotchange  |
+| 13. 执行 slot filter / 动态 slot                             |     | slotChange  |
 
 > 更新流程【普通】
 
 | 功能                           | 生命周期     |
 | ------------------------------ | ------------ |
 | 1. 父组件 props 变更【或】     | propsReady   |
-| 1. 子组件 state 变更【或】     |              |
+| 1. 子组件 states 变更【或】     |              |
 | 2. 执行@watch 注解             |              |
 | 3. 合并变更内容并判断是否更新  | shouldUpdate |
 | 4. 更新依赖域指令（非 render） |              |
@@ -374,7 +381,7 @@ static get autoSlot() {
 | ------- | --------- | ----------------------------------------------------------- | ------------------------------------------------------ |
 | bind    | TAG       | 绑定属性/特性到标签上，根据标签类型及组件 prop 定义自动判断 | `<div a="b" ${bind(obj)}>`                             |
 | show    | TAG       | 隐藏/显示标签（基于 display）                               | `<div a="b" ${show(visible)}>`                         |
-| model   | TAG       | 双向绑定                                                    | `<div a="b" ${model(xx)}>`                             |
+| model   | TAG       | 双向绑定                                                    | `<div a="b" ${model(xx,modelPath?)}>`                             |
 | classes | CLASS     | 绑定样式类属性，支持对象/数组/字符串。可以和静态字符混用    | `<div class="otherClass ${classes(obj)}>"`             |
 | styles  | STYLE     | 绑定样式规则属性，支持对象/字符串。可以和静态字符混用       | `<div style="a:b;${styles(obj)}>"`                     |
 | forEach | TEXT/SLOT | 输出循环结构                                                | `...>${forEach(ary,(item)=>html`...`)}<...`            |
@@ -392,6 +399,14 @@ static get autoSlot() {
 - @tag 自定义组件的标签名
 - @event 定义全局事件
 - @watch 监控 state/prop 变更
+- @computed 计算属性，仅在响应变量变更时更新缓存值
+
+> 装饰器还可通过函数方式进行调用，如
+> ```ts
+> //Decorator.call(class, decorator, fieldName, ...args)
+> Decorator.call(this, prop, 'name', { type: String })
+> ```
+> **注意**，调用入口必须放在类的构造函数中
 
 ## 事件
 
@@ -399,4 +414,4 @@ static get autoSlot() {
 
 1. 原生事件 —— `<div @click="..."`，监听器回调参数返回原生事件对象
 2. 组件自定义事件 —— `<l-select @change="..."`，监听器回调参数返回`CustomEvent`事件对象
-3. 扩展原生事件 —— `<div @resize="..."`，监听器回调参数返回`CustomEvent`事件对象
+3. 扩展原生事件 —— `<div @resize="..."`，监听器回调参数返回`CustomEvent`事件对象

package/decorator/Decorator.d.ts

@@ -9,6 +9,14 @@ export declare enum DecoratorType {
  * @author holyhigh2
  */
 export declare abstract class Decorator {
+    /**
+     * 通过函数方式进行装饰器调用
+     * @param target 所在类
+     * @param deco 装饰器函数
+     * @param fieldName 装饰器应用的字段名/函数名/函数
+     * @param args 不定参数
+     */
+    static call(target: any, deco: Function, fieldName: string | Function, ...args: any[]): void;
     /**
      * 装饰器使用范围，超出范围会报错
      */

package/decorator/index.d.ts

@@ -6,7 +6,8 @@ import { Constructor } from './../types';
 import { CompElem } from "../CompElem";
 import { Decorator } from "./Decorator";
 export declare const GetKeyFnName = "getKey";
-export declare const DecoratorsKey = "__decorators";
+export declare const _DecoratorsKey = "__decorators";
+export declare const _DecoratorMap: WeakMap<WeakKey, any>;
 /**
  * 装饰器包装类
  * 用于框架内部，表示class上的一个装饰器属性定义
@@ -29,4 +30,4 @@ export declare class DecoratorWrapper {
  * @param decoClass 装饰器构造
  * @returns 装饰器函数
  */
-export declare function decorator<T extends Array<any>>(decoClass: Constructor<Decorator>): (...args: T) => (...metadata: any[]) => void;
+export declare function decorator<T extends Array<any>>(decoClass: Constructor<Decorator>): (...args: T) => (...metadata: any[]) => any;

package/decorators/prop.d.ts

@@ -54,12 +54,5 @@ export type PropOption = {
  * @param options 可选参数 PropOption，如果type未定义则根据默认值自动推断类型
  */
 export declare function prop(options: PropOption): (target: any, propertyKey: any) => void;
-export declare function prop(target: any, propertyKey: any): void;
-/**
- * 同@prop装饰器，但可用于构造器中调用
- * @param ctor 类构造函数
- * @param propertyKey prop名称
- * @param options
- */
-export declare function makeProp(ctor: Function, propertyKey: string, options?: PropOption): void;
+export declare function prop(target: any, propertyKey: any, options?: PropOption): void;
 export declare function _getObservedAttrs(ctor: Function): Set<string>;

package/decorators/query.d.ts

@@ -22,5 +22,5 @@ export type QueryOption = {
      */
     cache?: string;
 };
-export declare const query: (selector: string, cache?: QueryCache | undefined) => (...metadata: any[]) => void;
-export declare const queryAll: (selector: string, cache?: QueryCache | undefined) => (...metadata: any[]) => void;
+export declare const query: (selector: string, cache?: QueryCache | undefined) => (...metadata: any[]) => any;
+export declare const queryAll: (selector: string, cache?: QueryCache | undefined) => (...metadata: any[]) => any;

package/decorators/watch.d.ts

@@ -23,4 +23,4 @@ export type DecoratorWatch = {
     handler: WatchHandler;
     options: WatchOptions;
 };
-export declare const watch: (source: string | string[], options?: WatchOptions | undefined) => (...metadata: any[]) => void;
+export declare const watch: (source: string | string[], options?: WatchOptions | undefined, handler?: WatchHandler | undefined) => (...metadata: any[]) => any;

package/directives/Model.d.ts

@@ -2,4 +2,4 @@ export declare const enum ModelTriggerType {
     CHANGE = "change",
     INPUT = "input"
 }
-export declare const model: (modelValue: any) => import("../directive/index").DirectiveWrapper;
+export declare const model: (modelValue: any, modelPath?: string | undefined) => import("../directive/index").DirectiveWrapper;