p-elements-core 1.2.17 → 1.2.18

package/p-elements-core.d.ts

@@ -38,84 +38,196 @@ declare interface ProjectionOptions extends ProjectorOptions {
   ) => Function;
 }
 
-declare interface VNodeProperties {
-  enterAnimation?:
-    | ((element: Element, properties?: VNodeProperties) => void)
-    | string;
-  exitAnimation?:
-    | ((
-        element: Element,
-        removeElement: () => void,
-        properties?: VNodeProperties
-      ) => void)
-    | string;
-  updateAnimation?: (
+export type EventHandler = (this: Node, event: Event) => boolean | undefined | void;
+
+
+/**
+ * Object containing attributes, properties, event handlers and more that can be put on DOM nodes.
+ *
+ * For your convenience, all common attributes, properties and event handlers are listed here and are
+ * type-checked when using Typescript.
+ */
+export interface VNodeProperties {
+  /**
+   * The animation to perform when this node is added to an already existing parent.
+   * {@link http://maquettejs.org/docs/animations.html More about animations}.
+   * @param element - Element that was just added to the DOM.
+   * @param properties - The properties object that was supplied to the [[h]] method
+   */
+  enterAnimation?: (element: Element, properties?: VNodeProperties) => void;
+  /**
+   * The animation to perform when this node is removed while its parent remains.
+   * @param element - Element that ought to be removed from to the DOM.
+   * @param removeElement - Function that removes the element from the DOM.
+   * This argument is provided purely for convenience.
+   * You may use this function to remove the element when the animation is done.
+   * @param properties - The properties object that was supplied to the [[h]] method that rendered this [[VNode]] the previous time.
+   */
+  exitAnimation?(element: Element, removeElement: () => void, properties?: VNodeProperties): void;
+  /**
+   * The animation to perform when the properties of this node change.
+   * This also includes attributes, styles, css classes. This callback is also invoked when node contains only text and that text changes.
+   * {@link http://maquettejs.org/docs/animations.html More about animations}.
+   * @param element - Element that was modified in the DOM.
+   * @param properties - The last properties object that was supplied to the [[h]] method
+   * @param previousProperties - The previous properties object that was supplied to the [[h]] method
+   */
+  updateAnimation?(
     element: Element,
     properties?: VNodeProperties,
     previousProperties?: VNodeProperties
-  ) => void;
+  ): void;
+  /**
+   * Callback that is executed after this node is added to the DOM. Child nodes and properties have
+   * already been applied.
+   * @param element - The element that was added to the DOM.
+   * @param projectionOptions - The projection options that were used, see [[createProjector]].
+   * @param vnodeSelector - The selector passed to the [[h]] function.
+   * @param properties - The properties passed to the [[h]] function.
+   * @param children - The children that were created.
+   */
   afterCreate?(
     element: Element,
     projectionOptions: ProjectionOptions,
     vnodeSelector: string,
     properties: VNodeProperties,
-    children: VNode[]
+    children: VNode[] | undefined
   ): void;
+  /**
+   * Callback that is executed every time this node may have been updated. Child nodes and properties
+   * have already been updated.
+   * @param element - The element that may have been updated in the DOM.
+   * @param projectionOptions - The projection options that were used, see [[createProjector]].
+   * @param vnodeSelector - The selector passed to the [[h]] function.
+   * @param properties - The properties passed to the [[h]] function.
+   * @param children - The children for this node.
+   */
   afterUpdate?(
     element: Element,
     projectionOptions: ProjectionOptions,
     vnodeSelector: string,
     properties: VNodeProperties,
-    children: VNode[]
+    children: VNode[] | undefined
   ): void;
+
+  /**
+   * Callback that is called when a node has been removed from the tree.
+   * The callback is called during idle state or after a timeout (fallback).
+   * {@link https://maquettejs.org/docs/dom-node-removal.html More info}
+   * @param element - The element that has been removed from the DOM.
+   */
   afterRemoved?(element: Element): void;
-  readonly bind?: Object;
-  readonly key?: Object;
+
+  /**
+   * When specified, the event handlers will be invoked with 'this' pointing to the value.
+   * This is useful when using the prototype/class based implementation of MaquetteComponents.
+   *
+   * When no [[key]] is present, this object is also used to uniquely identify a DOM node.
+   */
+  readonly bind?: unknown;
+
+  /**
+   * Used to uniquely identify a DOM node among siblings.
+   * A key is required when there are more children with the same selector and these children are added or removed dynamically.
+   * NOTE: this does not have to be a string or number, a [[MaquetteComponent]] Object for instance is also common.
+   */
+  readonly key?: unknown;
+
+  /**
+   * An object containing event handlers to attach using addEventListener.
+   * Note that `projector.scheduleRender()` is called automatically when these event handlers are invoked.
+   */
+  readonly on?: {
+    [eventName: string]:
+      | EventHandler
+      | {
+          listener: EventHandler;
+          options: { capture?: boolean; passive?: boolean; once?: boolean };
+        };
+  };
+
+  /**
+   * An object containing event handlers to attach using addEventListener.
+   * Note that `projector.scheduleRender()` is called automatically when these event handlers are invoked.
+   */
+  readonly onCapture?: { [eventName: string]: EventHandler };
+
+  /**
+   * An object literal like `{important:true}` which allows css classes, like `important` to be added and removed
+   * dynamically.
+   */
   readonly classes?: { [index: string]: boolean | null | undefined };
-  readonly styles?: { [index: string]: string | null | undefined };
 
-  ontouchcancel?(ev?: TouchEvent): boolean | void;
-  ontouchend?(ev?: TouchEvent): boolean | void;
-  ontouchmove?(ev?: TouchEvent): boolean | void;
-  ontouchstart?(ev?: TouchEvent): boolean | void;
+  /**
+   * An object literal like `{height:'100px'}` which allows styles to be changed dynamically. All values must be strings.
+   */
+  readonly styles?: Partial<CSSStyleDeclaration> | { [cssVariable: string]: string };
+
+  /**
+   * For custom elements
+   */
+  readonly is?: string;
 
+  // From Element
+  ontouchcancel?(ev: TouchEvent): boolean | void;
+  ontouchend?(ev: TouchEvent): boolean | void;
+  ontouchmove?(ev: TouchEvent): boolean | void;
+  ontouchstart?(ev: TouchEvent): boolean | void;
+  // From HTMLFormElement
   readonly action?: string;
   readonly encoding?: string;
   readonly enctype?: string;
   readonly method?: string;
   readonly name?: string;
   readonly target?: string;
-
+  // From HTMLAnchorElement
   readonly href?: string;
   readonly rel?: string;
-
-  onblur?(ev?: FocusEvent): boolean | void;
-  onchange?(ev?: Event): boolean | void;
-  onclick?(ev?: MouseEvent): boolean | void;
-  ondblclick?(ev?: MouseEvent): boolean | void;
-  onfocus?(ev?: FocusEvent): boolean | void;
-  oninput?(ev?: Event): boolean | void;
-  onkeydown?(ev?: KeyboardEvent): boolean | void;
-  onkeypress?(ev?: KeyboardEvent): boolean | void;
-  onkeyup?(ev?: KeyboardEvent): boolean | void;
-  onload?(ev?: Event): boolean | void;
-  onmousedown?(ev?: MouseEvent): boolean | void;
-  onmouseenter?(ev?: MouseEvent): boolean | void;
-  onmouseleave?(ev?: MouseEvent): boolean | void;
-  onmousemove?(ev?: MouseEvent): boolean | void;
-  onmouseout?(ev?: MouseEvent): boolean | void;
-  onmouseover?(ev?: MouseEvent): boolean | void;
-  onmouseup?(ev?: MouseEvent): boolean | void;
-  onmousewheel?(ev?: WheelEvent): boolean | void;
-  onscroll?(ev?: UIEvent): boolean | void;
-  onsubmit?(ev?: Event): boolean | void;
+  // From HTMLElement
+  onblur?(ev: FocusEvent): boolean | void;
+  onchange?(ev: Event): boolean | void;
+  onclick?(ev: MouseEvent): boolean | void;
+  ondblclick?(ev: MouseEvent): boolean | void;
+  ondrag?(ev: DragEvent): boolean | void;
+  ondragend?(ev: DragEvent): boolean | void;
+  ondragenter?(ev: DragEvent): boolean | void;
+  ondragleave?(ev: DragEvent): boolean | void;
+  ondragover?(ev: DragEvent): boolean | void;
+  ondragstart?(ev: DragEvent): boolean | void;
+  ondrop?(ev: DragEvent): boolean | void;
+  onfocus?(ev: FocusEvent): boolean | void;
+  oninput?(ev: Event): boolean | void;
+  onkeydown?(ev: KeyboardEvent): boolean | void;
+  onkeypress?(ev: KeyboardEvent): boolean | void;
+  onkeyup?(ev: KeyboardEvent): boolean | void;
+  onload?(ev: Event): boolean | void;
+  onmousedown?(ev: MouseEvent): boolean | void;
+  onmouseenter?(ev: MouseEvent): boolean | void;
+  onmouseleave?(ev: MouseEvent): boolean | void;
+  onmousemove?(ev: MouseEvent): boolean | void;
+  onmouseout?(ev: MouseEvent): boolean | void;
+  onmouseover?(ev: MouseEvent): boolean | void;
+  onmouseup?(ev: MouseEvent): boolean | void;
+  onmousewheel?(ev: WheelEvent): boolean | void;
+  onscroll?(ev: UIEvent): boolean | void;
+  onsubmit?(ev: Event): boolean | void;
+  onpointercancel?(ev: PointerEvent): boolean | void;
+  onpointerdown?(ev: PointerEvent): boolean | void;
+  onpointerenter?(ev: PointerEvent): boolean | void;
+  onpointerleave?(ev: PointerEvent): boolean | void;
+  onpointermove?(ev: PointerEvent): boolean | void;
+  onpointerout?(ev: PointerEvent): boolean | void;
+  onpointerover?(ev: PointerEvent): boolean | void;
+  onpointerup?(ev: PointerEvent): boolean | void;
   readonly spellcheck?: boolean;
   readonly tabIndex?: number;
   readonly disabled?: boolean;
   readonly title?: string;
   readonly accessKey?: string;
+  readonly class?: string;
   readonly id?: string;
-
+  readonly draggable?: boolean;
+  // From HTMLInputElement
   readonly type?: string;
   readonly autocomplete?: string;
   readonly checked?: boolean;
@@ -123,11 +235,25 @@ declare interface VNodeProperties {
   readonly readOnly?: boolean;
   readonly src?: string;
   readonly value?: string;
-
+  // From HTMLImageElement
   readonly alt?: string;
   readonly srcset?: string;
+  /**
+   * Puts a non-interactive string of html inside the DOM node.
+   *
+   * Note: if you use innerHTML, maquette cannot protect you from XSS vulnerabilities and you must make sure that the innerHTML value is safe.
+   */
   readonly innerHTML?: string;
 
+  /**
+   * Do not use className, use class instead
+   */
+  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+  readonly className?: never | "Hint: do not use `className`, use `class` instead";
+
+  /**
+   * Everything that is not explicitly listed (properties and attributes that are either uncommon or custom).
+   */
   readonly [index: string]: any;
 }
 
@@ -182,9 +308,21 @@ declare const CustomElementConfig: (
 
 declare type ElementProjectorMode = "append" | "merge" | "replace";
 
+export interface PropertyOptions {
+    type?: PropertyType;
+    reflect?: boolean;
+    attribute?: string;
+    readonly?: boolean;
+    converter?: AttributeConverter<any>;
+}
+export interface PropertyInfo extends PropertyOptions {
+  name: string;
+}
+
 declare abstract class CustomElement extends HTMLElement {
   constructor(self?: any);
   get internals(): ElementInternals;
+  get properties(): readonly PropertyInfo[];
   protected addStylesheetToRootNode(
     style: string,
     rootNode: ShadowRoot | Document
@@ -199,6 +337,7 @@ declare abstract class CustomElement extends HTMLElement {
     render: () => VNode
   ): Promise<Projector>;
   addController(controller: CustomElementController): void;
+  scheduleRender(): void;
   renderNow(): void;
   connectedCallback(): void;
   disconnectedCallback(): void;
@@ -215,6 +354,7 @@ declare abstract class CustomElementController {
   constructor(hostElement: CustomElement);
   hostElement: CustomElement;
   renderNow(): void;
+  scheduleRender(): void;
   init?(): void;
   connected?(): void;
   disconnected?(): void;
@@ -241,6 +381,7 @@ interface AttributeConverter<T> {
   fromAttribute?(value: string | null): T;
   toAttribute?(value: T): string;
 }
+
 declare type PropertyType = "string" | "number" | "boolean" | "object";
 
 declare const Property: (options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "p-elements-core",
-  "version": "1.2.17",
+  "version": "1.2.18",
   "description": "P Elements Core V1",
   "main": "dist/p-elements-core.js",
   "types": "p-elements-core.d.ts",

package/readme.md

@@ -192,6 +192,14 @@ Before a property is set to a new value
 
 After a property value is set to a new value
 
+#### `renderStart`
+
+When the custom element start the rendering 
+
+#### `renderDone`
+
+When the custom element is finished rendering
+
 #### `attributeChangedCallback`
 
 Call `super.attributeChangedCallback()` first.

package/src/custom-element-controller.ts

@@ -1,8 +1,12 @@
+import type { CustomElement } from './custom-element';
+
 export interface ICustomElementController {
   renderNow(): void;
   init?: () => void;
   connected? : () => void;
   disconnected? : () => void;
+  hostRenderStart?: () => void;
+  hostRenderDone? : () => void;
   hostElement: CustomElement;
 }
 export abstract class CustomElementController implements ICustomElementController {
@@ -20,4 +24,8 @@ export abstract class CustomElementController implements ICustomElementControlle
   renderNow() {
     this.hostElement?.renderNow();
   }
+
+  scheduleRender() {
+    this.hostElement?.scheduleRender();
+  }
 }

package/src/custom-element.ts

@@ -1,6 +1,7 @@
 import { PropertyInfo } from "./decorators/property";
 import { replaceApplyToCssVars } from "./helpers/css";
 import { ICustomElementController } from "./custom-element-controller";
+import { Projector, VNode } from "./maquette/interfaces";
 
 export type ElementProjectorMode = "append" | "merge" | "replace";
 
@@ -102,6 +103,7 @@ export abstract class CustomElement extends HTMLElement {
         this.#polyfillCssApply();
       });
     }
+    
   }
 
   #reflectProperties() {
@@ -272,18 +274,28 @@ export abstract class CustomElement extends HTMLElement {
       let projector: Projector;
       const mode = this.#projectorMode ? this.#projectorMode : "append";
       requestAnimationFrame(() => {
-        projector = (window as any).Maquette.createProjector();
+        projector = (window as any).Maquette.createProjector({
+          performanceLogger: (eventName) => {
+            if (eventName === "renderStart" || eventName === "renderDone") {
+              this.#invokeRenderLifecycleFn(eventName);
+            }
+          }
+        });
         projector[mode](element, render.bind(this));
         this.#projector = projector;
         this.#canReflect = true;
         this.#reflectProperties();
-        resolve(projector);    
-        
+        projector.renderNow();
+        resolve(projector);
         this.dispatchEvent(new CustomEvent("firstRender", {}));
       });
     });
   }
 
+  scheduleRender(): void {
+    this.#projector?.scheduleRender();
+  }
+
   renderNow(): void {
     this.#projector?.renderNow();
   }
@@ -328,4 +340,26 @@ export abstract class CustomElement extends HTMLElement {
       this[prop.name] = JSON.parse(newValue);
     }
   }
+
+  #isFirstRenderStart = true;
+
+  #isFirstRenderDone = true;
+
+
+  #invokeRenderLifecycleFn(eventName: string) {
+    if (this[eventName]){
+      this[eventName](eventName === "renderStart" ? this.#isFirstRenderStart : this.#isFirstRenderDone);
+    }
+    const controllerEventName = `host${eventName.charAt(0).toUpperCase()}${eventName.slice(1)}`;
+    this.#controllers.forEach((controller) => {
+      if (controller[controllerEventName]) {
+        controller[controllerEventName](eventName === "renderStart" ? this.#isFirstRenderStart : this.#isFirstRenderDone);
+      }
+    });
+    if (eventName === "renderStart") {
+      this.#isFirstRenderStart = false;
+    } else {
+      this.#isFirstRenderDone = false;
+    }
+  }
 }

package/src/decorators/property.ts

@@ -61,7 +61,7 @@ export const property = (propertyOptions: PropertyOptions) => {
         },
         set: function (value) {
           this[sym] = value;
-          this?.renderNow();
+          this?.scheduleRender();
           delete this[name];
           Object.defineProperty(this, name, {
             configurable: true,
@@ -102,7 +102,7 @@ export const property = (propertyOptions: PropertyOptions) => {
         }
         const handleChange = () => {
           if (this[sym] !== oldValue) {
-            this?.renderNow && this.renderNow();
+            this?.scheduleRender && this.scheduleRender();
             this?.updated && this.updated(name, oldValue, this[sym]);
           }
         };
@@ -135,7 +135,7 @@ export const property = (propertyOptions: PropertyOptions) => {
           }
         }
         handleChange();
-        this?.renderNow && this.renderNow();
+        this?.scheduleRender && this.scheduleRender();
       },
     });
   };

package/src/sample/mixin/highlight.tsx

@@ -1,6 +1,7 @@
 export interface HighlightableInterface {
   highlight: boolean;
 }
+import type { CustomElement } from "../../custom-element";
 
 type Constructor<T> = new (...args: any[]) => T;
 

package/src/sample/sample.tsx

@@ -1,6 +1,13 @@
 import { Highlightable } from "./mixin/highlight";
 import anime from "animejs";
 
+import {customElementConfig as CustomElementConfig} from "../decorators/custom-element-config";
+import {property as Property, AttributeConverter} from "../decorators/property";
+import {propertyRenderOnSet as PropertyRenderOnSet} from "../decorators/render-property-on-set";
+import {query as Query} from "../decorators/query";
+import {CustomElement} from "../custom-element";
+import {CustomElementController} from "../custom-element-controller";
+
 @CustomElementConfig({
   tagName: "my-button",
 })
@@ -10,7 +17,6 @@ export class MyButton extends CustomElement {
   render = () => {
     return <button class="foo"><slot></slot></button>;
   }
-
 }
 
 @CustomElementConfig({
@@ -263,10 +269,18 @@ class DisabledController extends CustomElementController {
     return true;
   }
 
-  updated() {
-    console.info("updated", this);
+  updated(property, oldValue, newValue) {
+    console.info("updated", { property, oldValue, newValue });
     this.#updateAttributes();
   }
+
+  hostRenderStart(isFirstRender) {
+    console.info("hostRenderStart", { isFirstRender, controller: this });
+  }
+
+  hostRenderDone(isFirstRender) {
+    console.info("hostRenderDone", { isFirstRender, controller: this });
+  }
 }
 
 @CustomElementConfig({
@@ -317,6 +331,14 @@ class PFoo extends CustomElement {
     }
   }
 
+  renderStart(isFirstRender) {
+    console.info("renderStart", { isFirstRender, tag: this.tagName });
+  }
+
+  renderDone(isFirstRender) {
+    console.info("renderDone", { isFirstRender, tag: this.tagName });
+  }
+
   render = () => {
     return <div classes={{ foo: true, "foo__disabled": this.disabledController.disabled }}>
       <div >Hello {this.name} {this.nickName ? <span> ({this.nickName})</span> : null}</div>