@shortfuse/materialdesignweb 0.7.6 → 0.9.0

package/core/CustomElement.js

@@ -1,10 +1,117 @@
 /* eslint-disable max-classes-per-file */
 
 import Composition from './Composition.js';
-import { ICustomElement } from './ICustomElement.js';
+import { css } from './css.js';
 import { attrNameFromPropName, attrValueFromDataValue } from './dom.js';
+import { applyMergePatch } from './jsonMergePatch.js';
 import { defineObservableProperty } from './observe.js';
-import { addInlineFunction, css, html } from './template.js';
+import { addInlineFunction, html } from './template.js';
+
+/** @typedef {import('./observe.js').ObserverPropertyType} ObserverPropertyType */
+
+/**
+ * @template {any} T
+ * @typedef {{
+ * [P in keyof T]:
+ *   T[P] extends (...args:any[]) => infer T2 ? T2
+ *     : T[P] extends ObserverPropertyType
+ *     ? import('./observe.js').ParsedObserverPropertyType<T[P]>
+ *     : T[P] extends {type: ObserverPropertyType}
+ *     ? import('./observe.js').ParsedObserverPropertyType<T[P]['type']>
+ *     : T[P] extends ObserverOptions<null, infer T2>
+ *     ? unknown extends T2 ? string : T2
+ *     : never
+ * }} ParsedProps
+ */
+
+/**
+ * @template {ObserverPropertyType} T1
+ * @template {any} T2
+ * @template {Object} [C=any]
+ * @typedef {import('./observe.js').ObserverOptions<T1,T2,C>} ObserverOptions
+ */
+
+/**
+ * @template {{ prototype: unknown; }} T
+ * @typedef {T} ClassOf<T>
+ */
+
+/**
+ * @template {any} [T=any]
+ * @template {any[]} [A=any[]]
+ * @typedef {abstract new (...args: A) => T} Class
+ */
+
+/**
+ * @template {any} T1
+ * @template {any} [T2=T1]
+ * @callback HTMLTemplater
+ * @param {TemplateStringsArray} string
+ * @param {...(string|DocumentFragment|Element|((this:T1, data:T2) => any))} substitutions
+ * @return {DocumentFragment}
+ */
+
+/**
+ * @template {any} [T1=any]
+ * @template {any} [T2=T1]
+ * @typedef {Object} CallbackArguments
+ * @prop {Composition<T1>} composition
+ * @prop {Record<string, HTMLElement>} refs
+ * @prop {HTMLTemplater<T1, Partial<T2>>} html
+ * @prop {(fn: (this:T1, data: T2) => any) => string} inline
+ * @prop {DocumentFragment} template
+ * @prop {T1} element
+ */
+
+/**
+ * @template {any} T1
+ * @template {any} [T2=T1]
+ * @typedef {{
+ * composed?: (this: T1, options: CallbackArguments<T1, T2>) => any,
+ * constructed?: (this: T1, options: CallbackArguments<T1, T2>) => any,
+ * connected?: (this: T1, options: CallbackArguments<T1, T2>) => any,
+ * disconnected?: (this: T1, options: CallbackArguments<T1, T2>) => any,
+ * props?: {
+ *   [P in keyof T1] : (
+ *   this: T1,
+ *   oldValue: T1[P],
+ *   newValue: T1[P],
+ *   changes:any,
+ *   element: T1
+ *   ) => any
+ * },
+ * attrs?: {[K in keyof any]: (
+ *   this: T1,
+ *   oldValue: string,
+ *   newValue: string,
+ *   element: T1
+ *   ) => unknown
+ * },
+ * } & {
+ * [P in keyof T1 & string as `${P}Changed`]?: (
+ *   this: T1,
+ *   oldValue: T1[P],
+ *   newValue: T1[P],
+ *   changes:any,
+ *   element: T1
+ *   ) => any
+ * }} CompositionCallback
+ */
+
+/**
+ * @template {Object} C
+ * @typedef {{
+ *  [P in string] :
+ *    ObserverPropertyType
+ *    | ObserverOptions<ObserverPropertyType, unknown, C>
+ *    | ((this:C, data:Partial<C>, fn?: () => any) => any)
+ * }} IDLParameter
+ */
+
+/**
+ * @template T
+ * @typedef {(T | Array<[keyof T & string, T[keyof T]]>)} ObjectOrObjectEntries
+ */
 
 /**
  * @template {abstract new (...args: any) => unknown} T
@@ -32,57 +139,49 @@ export function cloneAttributeCallback(name, target) {
   };
 }
 
-const EVENT_PREFIX_REGEX = /^([*1~]+)?(.*)$/;
-
 /**
  * Web Component that can cache templates for minification or performance
  */
-export default class CustomElement extends ICustomElement {
+export default class CustomElement extends HTMLElement {
   /** @type {string} */
   static elementName;
 
   /** @return {Iterable<string>} */
   static get observedAttributes() {
-    const s = new Set();
-    for (const config of this.propList.values()) {
-      if (config.reflect === true || config.reflect === 'read') {
-        s.add(config.attr);
-      }
-    }
-    return s;
+    return this.attrList.keys();
   }
 
   /** @type {import('./Composition.js').Compositor<?>} */
   compose() {
-    if (this.#composition) {
-      console.warn('Already composed. Generating *new* composition...');
-    }
-    this.#composition = new Composition();
-    return this.#composition;
+    // eslint-disable-next-line no-return-assign
+    return (this.#composition ??= new Composition());
   }
 
   /** @type {Composition<?>} */
   static _composition = null;
 
-  /** @type {Map<string, import('./typings.js').ObserverConfiguration<?,?,?>>} */
+  /** @type {Map<string, import('./observe.js').ObserverConfiguration<?,?,?>>} */
   static _props = new Map();
 
+  /** @type {Map<string, import('./observe.js').ObserverConfiguration<?,?,?>>} */
+  static _attrs = new Map();
+
   /** @type {Map<string, Function[]>} */
   static _propChangedCallbacks = new Map();
 
   /** @type {Map<string, Function[]>} */
   static _attributeChangedCallbacks = new Map();
 
-  /** @type {typeof ICustomElement._onComposeCallbacks} */
+  /** @type {((callback: CallbackArguments) => any)[]} */
   static _onComposeCallbacks = [];
 
-  /** @type {typeof ICustomElement._onConnectedCallbacks} */
+  /** @type {((callback: CallbackArguments) => any)[]} */
   static _onConnectedCallbacks = [];
 
-  /** @type {typeof ICustomElement._onDisconnectedCallbacks} */
+  /** @type {((callback: CallbackArguments) => any)[]} */
   static _onDisconnectedCallbacks = [];
 
-  /** @type {typeof ICustomElement._onConstructedCallbacks} */
+  /** @type {((callback: CallbackArguments) => any)[]} */
   static _onConstructedCallbacks = [];
 
   static interpolatesTemplate = true;
@@ -102,68 +201,189 @@ export default class CustomElement extends ICustomElement {
   /** @type {Map<string, typeof CustomElement>} */
   static registrations = new Map();
 
-  /** @type {typeof ICustomElement.expressions} */
-  static expressions = this.set;
+  /**
+   * Expressions are idempotent functions that are selectively called whenever
+   * a render is requested.
+   * Expressions are constructed exactly as methods though differ in expected
+   * arguments. The first argument should be destructured to ensure each used
+   * property is accessed at least once in order to inspect used properties.
+   *
+   * The Composition API will inspect this function with a proxy for `this` to
+   * catalog what observables are used by the expression. This allows the
+   * Composition API to build a cache as well as selective invoke the expression
+   * only when needed.
+   *
+   * When used with in element templates, the element itself will be passed as
+   * its first argument.
+   * ````js
+   *    Button
+   *      .prop('filled', 'boolean')
+   *      .prop('outlined', 'boolean')
+   *      .expresssions({
+   *        _isFilledOrOutlined({filled, outlined}) {
+   *          return (filled || outlined)
+   *        },
+   *      })
+   *      .html`<div custom={_isFilledOrOutlined}></div>`;
+   * ````
+   *
+   * When used with external data source, that data source
+   * will be passed to the expression with all properties being `null` at first
+   * inspection.
+   * ````js
+   *    const externalData = {first: 'John', last: 'Doe'};
+   *    ContactCard
+   *      .expresssions({
+   *        _fullName({first, last}) {
+   *          return [first, last].filter(Boolean).join(' ');
+   *        },
+   *      })
+   *   myButton.render(externalData);
+   * ````
+   *
+   * Expressions may be support argumentless calls by using default
+   * parameters with `this`.
+   * ````js
+   *    Button
+   *      .expresssions({
+   *        isFilledOrOutlined({filled, outlined} = this) {
+   *          return (filled || outlined)
+   *        },
+   *      });
+   *    myButton.isFilledorOutlined();
+   * ````
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  PROPS extends {
+   *    [K in keyof any]: K extends `_${any}` ? ((data: INSTANCE, state?: Record<string, any>) => string|boolean|null)
+   *      : ((data?: INSTANCE, state?: Record<string, any>) => string|boolean|null)
+   *  } & ThisType<INSTANCE>
+   *  >(this: CLASS, expressions: PROPS & ThisType<INSTANCE & PROPS>):
+   *  CLASS & Class<{
+   *    [K in keyof PROPS]: K extends `_${any}` ? never : () =>  ReturnType<PROPS[K]> }
+   *    ,ARGS>
+   * }}
+   */
+  static expressions = /** @type {any} */ (this.set);
 
-  /** @type {typeof ICustomElement.methods} */
   static methods = this.set;
 
-  /** @type {typeof ICustomElement.overrides} */
-  static overrides = this.set;
+  /**
+   * @type {{
+   * <
+   * CLASS extends typeof CustomElement,
+   * ARGS extends ConstructorParameters<CLASS>,
+   * INSTANCE extends InstanceType<CLASS>,
+   * PROPS extends Partial<INSTANCE>>
+   * (this: CLASS, source: PROPS & ThisType<PROPS & INSTANCE>, options?: Partial<PropertyDescriptor>)
+   * : CLASS & Class<PROPS,ARGS>
+   * }}
+   */
+  static overrides = /** @type {any} */ (this.set);
+
+  /**
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  KEY extends string,
+   *  OPTIONS extends ObserverPropertyType
+   *    | ObserverOptions<ObserverPropertyType, unknown, INSTANCE>
+   *    | ((this:INSTANCE, data:Partial<INSTANCE>, fn?: () => any) => any),
+   *  VALUE extends Record<KEY, OPTIONS extends (...args2:any[]) => infer R ? R
+   *      : OPTIONS extends ObserverPropertyType ? import('./observe.js').ParsedObserverPropertyType<OPTIONS>
+   *      : OPTIONS extends {type: 'object'} & ObserverOptions<any, infer R> ? (unknown extends R ? object : R)
+   *      : OPTIONS extends {type: ObserverPropertyType} ? import('./observe.js').ParsedObserverPropertyType<OPTIONS['type']>
+   *      : OPTIONS extends ObserverOptions<any, infer R> ? (unknown extends R ? string : R)
+   *      : never
+   *      >
+   *  > (this: CLASS, name: KEY, options: OPTIONS)
+   *    : CLASS & Class<VALUE,ARGS>;
+   * }}
+   */
+  static props = /** @type {any} */ (this.observe);
 
-  /** @type {typeof ICustomElement.props} */
-  static props = this.observe;
+  static idl = this.prop;
 
   /**
-   * @template {typeof CustomElement} T
    * @this T
+   * @template {typeof CustomElement} T
    * @template {keyof T} K
    * @param {K} collection
    * @param {T[K] extends (infer R)[] ? R : never} callback
    */
   static _addCallback(collection, callback) {
     if (!this.hasOwnProperty(collection)) {
-      this[collection] = [
-        ...this[collection],
-      ];
+      // @ts-expect-error not typed
+      this[collection] = [...this[collection], callback];
+      return;
     }
+    // @ts-expect-error any
     this[collection].push(callback);
   }
 
   /**
    * Append parts to composition
-   * @type {typeof ICustomElement.append}
+   * @type {{
+   * <
+   *  T extends typeof CustomElement,
+   *  >
+   *  (this: T, ...parts: ConstructorParameters<typeof Composition<InstanceType<T>>>): T;
+   * }}
    */
   static append(...parts) {
-    this.on({
-      composed({ composition }) {
-        // console.debug('onComposed:append', ...parts);
-        composition.append(...parts);
-      },
+    this._addCallback('_onComposeCallbacks', ({ composition }) => {
+      composition.append(...parts);
     });
     // @ts-expect-error Can't cast T
     return this;
   }
 
   /**
-   * Appends styles to composition
-   * @type {typeof ICustomElement.css}
+   * After composition, invokes callback.
+   * May be called multiple times.
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends InstanceType<T1>,
+   *  T3 extends CompositionCallback<T2, T2>['composed'],
+   *  >
+   *  (this: T1, callback: T3): T1
+   * }}
    */
-  static css(array, ...substitutions) {
-    if (Array.isArray(array)) {
-      // @ts-expect-error Complex cast
-      this.append(css(array, ...substitutions));
-    } else {
-      // @ts-expect-error Complex cast
-      this.append(array, ...substitutions);
-    }
+  static recompose(callback) {
+    this._addCallback('_onComposeCallbacks', callback);
     // @ts-expect-error Can't cast T
     return this;
   }
 
-  /** @type {typeof ICustomElement['setSchema']} */
-  static setSchema(schema) {
-    this.schema = schema;
+  /**
+   * Appends styles to composition
+   * @type {{
+   * <
+   *   T1 extends typeof CustomElement,
+   *   T2 extends TemplateStringsArray|HTMLStyleElement|CSSStyleSheet|string>(
+   *   this: T1,
+   *   array: T2,
+   *   ...rest: T2 extends string ? any : T2 extends TemplateStringsArray ? any[] : (HTMLStyleElement|CSSStyleSheet)[]
+   * ): T1
+   * }}
+   */
+  static css(array, ...substitutions) {
+    this._addCallback('_onComposeCallbacks', ({ composition }) => {
+      if (typeof array === 'string' || Array.isArray(array)) {
+        // @ts-expect-error Complex cast
+        composition.append(css(array, ...substitutions));
+      } else {
+        // @ts-expect-error Complex cast
+        composition.append(array, ...substitutions);
+      }
+    });
+
     // @ts-expect-error Can't cast T
     return this;
   }
@@ -172,31 +392,35 @@ export default class CustomElement extends ICustomElement {
    * Registers class asynchronously at end of current event loop cycle
    * via `queueMicrotask`. If class is registered before then,
    * does nothing.
-   * @type {typeof ICustomElement['autoRegister']}
+   * @type {{
+   * <T extends typeof CustomElement>(this: T, elementName: string): T;
+   * }}
    */
   static autoRegister(elementName) {
-    if (elementName) {
-      this.elementName = elementName;
+    if (this.hasOwnProperty('defined') && this.defined) {
+      console.warn(this.elementName, 'already registered.');
+      // @ts-expect-error Can't cast T
+      return this;
     }
-    queueMicrotask(() => {
-      if (this.autoRegistration) {
-        this.register();
-      }
-    });
+    this.register(elementName);
     // @ts-expect-error Can't cast T
     return this;
   }
 
   /**
    * Appends DocumentFragment to composition
-   * @type {typeof ICustomElement.html}
+   * @type {{
+   * <T extends typeof CustomElement>(
+   *  this: T,
+   *  string: TemplateStringsArray,
+   *  ...substitutions: (string|Element|((this:InstanceType<T>, data:InstanceType<T>, injections?:any) => any))[]
+   *  ): T
+   * }}
    */
   static html(strings, ...substitutions) {
-    this.on({
-      composed({ composition }) {
+    this._addCallback('_onComposeCallbacks', ({ composition }) => {
       // console.log('onComposed:html', strings);
-        composition.append(html(strings, ...substitutions));
-      },
+      composition.append(html(strings, ...substitutions));
     });
     // @ts-expect-error Can't cast T
     return this;
@@ -205,28 +429,28 @@ export default class CustomElement extends ICustomElement {
   /**
    * Extends base class into a new class.
    * Use to avoid mutating base class.
-   * TODO: Add constructor arguments typing
-   * @type {typeof ICustomElement.extend}
-   */
-  static extend() {
-    // @ts-expect-error Can't cast T
-    return class extends this {};
-  }
-
-  /**
-   * Extends base class into a new class.
-   * Use to avoid mutating base class.
-   * TODO: Add constructor arguments typing
-   * @type {typeof ICustomElement.tsClassFix}
+   * @type {{
+   * <T1 extends typeof CustomElement, T2 extends T1, T3 extends (Base:T1) => T2>
+   * (this: T1,customExtender?: T3|null): T3 extends null ? T1 : T2;
+   * }}
    */
-  static tsClassFix() {
+  static extend(customExtender) {
     // @ts-expect-error Can't cast T
-    return this;
+    return customExtender ? customExtender(this) : class extends this {};
   }
 
   /**
    * Assigns static values to class
-   * @type {typeof ICustomElement.setStatic}
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends {
+   *    [K in keyof any]: (
+   *      ((this:T1, ...args:any[]) => any)
+   *      |string|number|boolean|any[]|object)}
+   *  >
+   *  (this: T1, source: T2 & ThisType<T1 & T2>):T1 & T2;
+   * }}
    */
   static setStatic(source) {
     Object.assign(this, source);
@@ -236,7 +460,15 @@ export default class CustomElement extends ICustomElement {
 
   /**
    * Assigns values directly to all instances (via prototype)
-   * @type {typeof ICustomElement.set}
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  PROPS extends object>
+   *  (this: CLASS, source: PROPS & ThisType<PROPS & INSTANCE>, options?: Partial<PropertyDescriptor>)
+   *  : CLASS & Class<PROPS,ARGS>
+   * }}
    */
   static readonly(source, options) {
     // @ts-expect-error Can't cast T
@@ -245,13 +477,21 @@ export default class CustomElement extends ICustomElement {
 
   /**
    * Assigns values directly to all instances (via prototype)
-   * @type {typeof ICustomElement.set}
+   * @type {{
+   * <
+   * CLASS extends typeof CustomElement,
+   * ARGS extends ConstructorParameters<CLASS>,
+   * INSTANCE extends InstanceType<CLASS>,
+   * PROPS extends object>
+   * (this: CLASS, source: PROPS & ThisType<PROPS & INSTANCE>, options?: Partial<PropertyDescriptor>)
+   * : CLASS & Class<PROPS,ARGS>
+   * }}
    */
   static set(source, options) {
     Object.defineProperties(
       this.prototype,
-      Object.fromEntries(
-        Object.entries(source).map(([name, value]) => {
+      Object.fromEntries([
+        ...Object.entries(source).map(([name, value]) => {
           // Tap into .map() to avoid double iteration
           // Property may be redefined observable
           this.undefine(name);
@@ -266,7 +506,17 @@ export default class CustomElement extends ICustomElement {
             },
           ];
         }),
-      ),
+        ...Object.getOwnPropertySymbols(source).map((symbol) => [
+          symbol,
+          {
+            enumerable: false,
+            configurable: true,
+            value: source[symbol],
+            writable: true,
+            ...options,
+          },
+        ]),
+      ]),
     );
     // @ts-expect-error Can't cast T
     return this;
@@ -274,7 +524,14 @@ export default class CustomElement extends ICustomElement {
 
   /**
    * Returns result of calling mixin with current class
-   * @type {typeof ICustomElement.mixin}
+   * @type {{
+   * <
+   *  BASE extends typeof CustomElement,
+   *  FN extends (...args:any[]) => any,
+   *  RETURN extends ReturnType<FN>,
+   *  SUBCLASS extends ClassOf<RETURN>,
+   *  (this: BASE, mixin: FN): SUBCLASS & BASE
+   * }}
    */
   static mixin(mixin) {
     return mixin(this);
@@ -282,15 +539,11 @@ export default class CustomElement extends ICustomElement {
 
   /**
    * Registers class with window.customElements synchronously
-   * @type {typeof ICustomElement['register']}
+   * @type {{
+   * <T extends typeof CustomElement>(this: T, elementName?: string, force?: boolean): T;
+   * }}
    */
-  static register(elementName, force = false) {
-    if (this.hasOwnProperty('defined') && this.defined && !force) {
-      console.warn(this.elementName, 'already registered.');
-      // @ts-expect-error Can't cast T
-      return this;
-    }
-
+  static register(elementName) {
     if (elementName) {
       this.elementName = elementName;
     }
@@ -309,6 +562,13 @@ export default class CustomElement extends ICustomElement {
     return this._props;
   }
 
+  static get attrList() {
+    if (!this.hasOwnProperty('_attrs')) {
+      this._attrs = new Map(this._attrs);
+    }
+    return this._attrs;
+  }
+
   static get propChangedCallbacks() {
     if (!this.hasOwnProperty('_propChangedCallbacks')) {
       // structuredClone()
@@ -334,55 +594,82 @@ export default class CustomElement extends ICustomElement {
 
   /**
    * Creates observable property on instances (via prototype)
-   * @template {import('./typings.js').ObserverPropertyType} [T1=null]
-   * @template {import('./typings.js').ObserverPropertyType} [T2=null]
-   * @template {any} [T3=null]
-   * @param {string} name
-   * @param {T1|import('./typings.js').ObserverOptions<T2,T3>} [typeOrOptions='string']
-   * @return {(
-   *    T3 extends null ?
-   *        T2 extends null ?
-   *          T1 extends null ?
-   *            string
-   *          : import('./typings.js').ParsedObserverPropertyType<T1>
-   *        : import('./typings.js').ParsedObserverPropertyType<T2>
-   *    : T3
-   * )}
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  KEY extends string,
+   *  OPTIONS extends ObserverPropertyType
+   *    | ObserverOptions<ObserverPropertyType, unknown, INSTANCE>
+   *    | ((this:INSTANCE, data:Partial<INSTANCE>, fn?: () => any) => any),
+   *  VALUE extends Record<KEY, OPTIONS extends (...args2:any[]) => infer R ? R
+   *      : OPTIONS extends ObserverPropertyType ? import('./observe').ParsedObserverPropertyType<OPTIONS>
+   *      : OPTIONS extends {type: 'object'} & ObserverOptions<any, infer R> ? (unknown extends R ? object : R)
+   *      : OPTIONS extends {type: ObserverPropertyType} ? import('./observe').ParsedObserverPropertyType<OPTIONS['type']>
+   *      : OPTIONS extends ObserverOptions<any, infer R> ? (unknown extends R ? string : R)
+   *      : never
+   *      >
+   *  > (this: CLASS, name: KEY, options: OPTIONS)
+   *    : CLASS & Class<VALUE,ARGS>
+   * }}
    */
   static prop(name, typeOrOptions) {
     // TODO: Cache and save configuration for reuse (mixins)
-    /** @type {import('./typings.js').ObserverOptions<?,?>} */
-    const options = {
-      ...((typeof typeOrOptions === 'string') ? { type: typeOrOptions } : typeOrOptions),
-    };
-
-    const customCallback = options.changedCallback;
+    const config = defineObservableProperty(
+      /** @type {any} */ (this.prototype),
+      name,
+      /** @type {any} */ (typeOrOptions),
+    );
 
-    if (customCallback) {
-      // Move callback to later in stack for attribute-based changes as well
-      this.onPropChanged({ [name]: customCallback });
+    const { changedCallback, attr, reflect, watchers } = config;
+    if (changedCallback) {
+      watchers.push([name, changedCallback]);
     }
-
     // TODO: Inspect possible closure bloat
-    options.changedCallback = function wrappedChangedCallback(oldValue, newValue, changes) {
+    config.changedCallback = function wrappedChangedCallback(oldValue, newValue, changes) {
       this._onObserverPropertyChanged.call(this, name, oldValue, newValue, changes);
     };
 
-    const config = defineObservableProperty(this.prototype, name, options);
-
     this.propList.set(name, config);
-    for (const [prop, callback] of config.watchers) {
-      this.on(`${prop}Changed`, callback);
+
+    if (attr && (reflect === true || reflect === 'read')) {
+      this.attrList.set(attr, config);
     }
 
-    return config.INIT_SYMBOL;
+    this.onPropChanged(watchers);
+
+    // @ts-expect-error Can't cast T
+    return this;
   }
 
   /**
    * Define properties on instances via Object.defineProperties().
    * Automatically sets property non-enumerable if name begins with `_`.
    * Functions will be remapped as getters
-   * @type {typeof ICustomElement.define}
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  PROPS extends {
+   *      [P in keyof any] :
+   *        {
+   *          enumerable?: boolean;
+   *          configurable?: boolean;
+   *          writable?: boolean;
+   *          value?: any;
+   *          get?: ((this: INSTANCE) => any);
+   *          set?: (this: INSTANCE, value: any) => void;
+   *        } | ((this: INSTANCE, ...args:any[]) => any)
+   *    },
+   *  VALUE extends {
+   *    [KEY in keyof PROPS]: PROPS[KEY] extends (...args2:any[]) => infer R ? R
+   *      : PROPS[KEY] extends TypedPropertyDescriptor<infer R> ? R : never
+   *  }>
+   *  (this: CLASS, props: PROPS & ThisType<PROPS & INSTANCE>): CLASS
+   *    & Class<VALUE,ARGS>
+   * }}
    */
   static define(props) {
     Object.defineProperties(
@@ -414,43 +701,68 @@ export default class CustomElement extends ICustomElement {
 
   static undefine(name) {
     Reflect.deleteProperty(this.prototype, name);
-    const config = this.propList.get(name);
-    if (config && config.watchers.length) {
+    if (!this.propList.has(name)) return this;
+    const { watchers, attr, reflect } = this.propList.get(name);
+    if (watchers.length && this.propChangedCallbacks.has(name)) {
       const propWatchers = this.propChangedCallbacks.get(name);
-      if (propWatchers) {
-        for (const watcher of config.watchers) {
-          const index = propWatchers.indexOf(watcher);
-          if (index !== -1) {
-            console.warn('Unwatching', name);
-            propWatchers.splice(index, 1);
-          }
+      for (const watcher of watchers) {
+        const index = propWatchers.indexOf(watcher);
+        if (index !== -1) {
+          console.warn('Unwatching', name);
+          propWatchers.splice(index, 1);
         }
       }
     }
+    if (attr && (reflect === true || reflect === 'read')) {
+      this.attrList.delete(attr);
+    }
     this.propList.delete(name);
+
     return this;
   }
 
   /**
    * Creates observable properties on instances
-   * @type {typeof ICustomElement.observe}
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  PROPS extends IDLParameter<INSTANCE & VALUE>,
+   *  VALUE extends {
+   *    [KEY in keyof PROPS]:
+   *    PROPS[KEY] extends (...args2:any[]) => infer R ? R
+   *        : PROPS[KEY] extends ObserverPropertyType ? import('./observe').ParsedObserverPropertyType<PROPS[KEY]>
+   *        : PROPS[KEY] extends {type: 'object'} & ObserverOptions<any, infer R> ? (unknown extends R ? object : R)
+   *        : PROPS[KEY] extends {type: ObserverPropertyType} ? import('./observe').ParsedObserverPropertyType<PROPS[KEY]['type']>
+   *        : PROPS[KEY] extends ObserverOptions<any, infer R> ? (unknown extends R ? string : R)
+   *        : never
+   *  },
+   *  > (this: CLASS, props: PROPS)
+   *    : CLASS & Class<VALUE,ARGS>
+   * }}
    */
   static observe(props) {
     for (const [name, typeOrOptions] of Object.entries(props ?? {})) {
-      if (typeof typeOrOptions === 'function') {
-        this.prop(name, {
-          reflect: false,
-          get: typeOrOptions,
-        });
-      } else {
-        this.prop(name, typeOrOptions);
-      }
+      /** @type {any} */
+      const options = (typeof typeOrOptions === 'function')
+        ? { reflect: false, get: typeOrOptions }
+        : typeOrOptions;
+
+      this.prop(name, options);
     }
     // @ts-expect-error Can't cast T
     return this;
   }
 
-  /** @type {typeof ICustomElement.defineStatic} */
+  /**
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends IDLParameter<T1>>
+   *  (this: T1, props: T2):T1 & ParsedProps<T2>
+   * }}
+   */
   static defineStatic(props) {
     for (const [name, typeOrOptions] of Object.entries(props ?? {})) {
       const options = (typeof typeOrOptions === 'function')
@@ -467,12 +779,35 @@ export default class CustomElement extends ICustomElement {
     return this;
   }
 
-  /** @type {typeof ICustomElement.events} */
+  /**
+   * @type {{
+   * <T extends typeof CustomElement>
+   *  (
+   *    this: T,
+   *    listeners?: import('./Composition').CompositionEventListenerObject<InstanceType<T>>,
+   *    options?: Partial<import('./Composition').CompositionEventListener<InstanceType<T>>>,
+   *  ): T;
+   * }}
+   */
   static events(listeners, options) {
     this.on({
       composed({ composition }) {
         for (const [key, listenerOptions] of Object.entries(listeners)) {
-          const [, flags, type] = key.match(EVENT_PREFIX_REGEX);
+          const [, flags, type] = key.match(/^([*1~]+)?(.*)$/);
+          // TODO: Make abstract
+          let prop;
+          /** @type {string[]} */
+          let deepProp = [];
+          if (typeof listenerOptions === 'string') {
+            const parsedProps = listenerOptions.split('.');
+            if (parsedProps.length === 1) {
+              prop = listenerOptions;
+              deepProp = [];
+            } else {
+              prop = parsedProps[0];
+              deepProp = parsedProps;
+            }
+          }
           composition.addCompositionEventListener({
             type,
             once: flags?.includes('1'),
@@ -482,7 +817,7 @@ export default class CustomElement extends ICustomElement {
               typeof listenerOptions === 'function'
                 ? { handleEvent: listenerOptions }
                 : (typeof listenerOptions === 'string'
-                  ? { prop: listenerOptions }
+                  ? { prop, deepProp }
                   : listenerOptions)
             ),
             ...(
@@ -498,11 +833,23 @@ export default class CustomElement extends ICustomElement {
     return this;
   }
 
-  /** @type {typeof ICustomElement.childEvents} */
+  /**
+   * @type {{
+   * <T extends typeof CustomElement>
+   *  (
+   *    this: T,
+   *    listenerMap: {
+   *      [P in keyof any]: import('./Composition').CompositionEventListenerObject<InstanceType<T>>
+   *    },
+   *    options?: Partial<import('./Composition').CompositionEventListener<InstanceType<T>>>,
+   *  ): T;
+   * }}
+   */
   static childEvents(listenerMap, options) {
-    for (const [id, listeners] of Object.entries(listenerMap)) {
+    for (const [tag, listeners] of Object.entries(listenerMap)) {
+      // @ts-expect-error Can't cast T
       this.events(listeners, {
-        id,
+        tag: attrNameFromPropName(tag),
         ...options,
       });
     }
@@ -511,7 +858,26 @@ export default class CustomElement extends ICustomElement {
     return this;
   }
 
-  /** @type {typeof ICustomElement['on']} */
+  /** @type {typeof CustomElement['events']} */
+  static rootEvents(listeners, options) {
+    // @ts-expect-error Can't cast T
+    return this.events(listeners, {
+      tag: Composition.shadowRootTag,
+      ...options,
+    });
+  }
+
+  /**
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends InstanceType<T1>,
+   *  T3 extends CompositionCallback<T2, T2>,
+   *  T4 extends keyof T3,
+   *  >
+   *  (this: T1, name: T3|T4, callbacks?: T3[T4] & ThisType<T2>): T1
+   * }}
+   */
   static on(nameOrCallbacks, callback) {
     const callbacks = typeof nameOrCallbacks === 'string'
       ? { [nameOrCallbacks]: callback }
@@ -545,31 +911,69 @@ export default class CustomElement extends ICustomElement {
     return this;
   }
 
-  /** @type {typeof ICustomElement['onPropChanged']} */
+  /**
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends InstanceType<T1>
+   *  >
+   *  (
+   *    this: T1,
+   *    options: ObjectOrObjectEntries<{
+   *      [P in keyof T2]? : (
+   *      this: T2,
+   *      oldValue: T2[P],
+   *      newValue: T2[P],
+   *      changes:any,
+   *      element: T2
+   *      ) => void
+   *    }>,
+   *  ): T1;
+   * }}
+   */
   static onPropChanged(options) {
-    for (const [prop, callback] of Object.entries(options)) {
-      let array = this.propChangedCallbacks.get(prop);
-      if (!array) {
-        array = [];
-        this.propChangedCallbacks.set(prop, array);
+    const entries = Array.isArray(options) ? options : Object.entries(options);
+    const { propChangedCallbacks } = this;
+    for (const [prop, callback] of entries) {
+      if (propChangedCallbacks.has(prop)) {
+        propChangedCallbacks.get(prop).push(callback);
+      } else {
+        propChangedCallbacks.set(prop, [callback]);
       }
-      array.push(callback);
     }
 
     // @ts-expect-error Can't cast T
     return this;
   }
 
-  /** @type {typeof ICustomElement['onAttributeChanged']} */
+  /**
+   * @type {{
+   * <
+   *  T1 extends typeof CustomElement,
+   *  T2 extends InstanceType<T1>
+   *  >
+   *  (
+   *    this: T1,
+   *    options: {
+   *      [x:string]: (
+   *      this: T2,
+   *      oldValue: string,
+   *      newValue: string,
+   *      element: T2
+   *      ) => void
+   *    },
+   *  ): T1;
+   * }}
+   */
   static onAttributeChanged(options) {
-    for (const [name, callback] of Object.entries(options)) {
-      const lcName = name.toLowerCase();
-      let array = this.attributeChangedCallbacks.get(lcName);
-      if (!array) {
-        array = [];
-        this.attributeChangedCallbacks.set(lcName, array);
+    const entries = Array.isArray(options) ? options : Object.entries(options);
+    const { attributeChangedCallbacks } = this;
+    for (const [name, callback] of entries) {
+      if (attributeChangedCallbacks.has(name)) {
+        attributeChangedCallbacks.get(name).push(callback);
+      } else {
+        attributeChangedCallbacks.set(name, [callback]);
       }
-      array.push(callback);
     }
 
     // @ts-expect-error Can't cast T
@@ -588,10 +992,10 @@ export default class CustomElement extends ICustomElement {
   /** @type {Composition<?>} */
   #composition;
 
-  /** @type {Map<string,null|[string,any]>} */
+  /** @type {Map<string,{stringValue:string, parsedValue:any}>} */
   _propAttributeCache;
 
-  /** @type {import('./ICustomElement.js').CallbackArguments} */
+  /** @type {CallbackArguments} */
   _callbackArguments = null;
 
   /** @param {any[]} args */
@@ -604,7 +1008,24 @@ export default class CustomElement extends ICustomElement {
 
     this.attachShadow({ mode: 'open', delegatesFocus: this.delegatesFocus });
 
-    this.composition.initialRender(this.shadowRoot, this);
+    /**
+     * Updates nodes based on data
+     * Expects data in JSON Merge Patch format
+     * @see https://www.rfc-editor.org/rfc/rfc7386
+     * @param {Partial<?>} changes
+     * @param {any} data
+     * @return {void}
+     */
+    this.render = this.composition.render(
+      this.constructor.prototype,
+      this,
+      {
+        defaults: this.constructor.prototype,
+        store: this,
+        shadowRoot: this.shadowRoot,
+        context: this,
+      },
+    );
 
     for (const callback of this.static._onConstructedCallbacks) {
       callback.call(this, this.callbackArguments);
@@ -612,25 +1033,26 @@ export default class CustomElement extends ICustomElement {
   }
 
   /**
-   * Updates nodes based on data
-   * Expects data in JSON Merge Patch format
-   * @see https://www.rfc-editor.org/rfc/rfc7386
-   * @param {?} data
-   * @param {?} [store]
-   * @return {void}
+   * @type {{
+   * <
+   *   T extends CustomElement,
+   *   K extends string = string,
+   * >(this:T,
+   *     name: K,
+   *     oldValue: K extends keyof T ? T[K] : unknown,
+   *     newValue: K extends keyof T ? T[K] : unknown,
+   *     changes?: K extends keyof T ? T[K] extends object ? Partial<T[K]> : T[K] : unknown): void;
+   * }}
    */
-  render(data, store) {
-    // console.log('render', data);
-    this.composition.render(this.shadowRoot, data, this, store ? { ...this, store } : this);
-  }
-
-  /** @type {InstanceType<typeof ICustomElement>['propChangedCallback']} */
   propChangedCallback(name, oldValue, newValue, changes = newValue) {
-    this.render({ [name]: changes });
+    if (!this.patching) {
+      this.render.byProp(name, changes, this);
+      // this.render({ [name]: changes });
+    }
 
-    const callbacks = this.static.propChangedCallbacks.get(name);
-    if (callbacks) {
-      for (const callback of callbacks) {
+    const { _propChangedCallbacks } = this.static;
+    if (_propChangedCallbacks.has(name)) {
+      for (const callback of _propChangedCallbacks.get(name)) {
         callback.call(this, oldValue, newValue, changes, this);
       }
     }
@@ -642,48 +1064,53 @@ export default class CustomElement extends ICustomElement {
    * @param {string|null} newValue
    */
   attributeChangedCallback(name, oldValue, newValue) {
-    const callbacks = this.static.attributeChangedCallbacks.get(name.toLowerCase());
-    if (callbacks) {
-      for (const callback of callbacks) {
+    const { attributeChangedCallbacks } = this.static;
+    if (attributeChangedCallbacks.has(name)) {
+      for (const callback of attributeChangedCallbacks.get(name)) {
         callback.call(this, oldValue, newValue, this);
       }
     }
 
     // Array.find
-    for (const config of this.static.propList.values()) {
-      if (config.attr !== name) continue;
+    const { attrList } = this.static;
+    if (!attrList.has(name)) return;
 
-      if (config.reflect !== true && config.reflect !== 'read') return;
+    const config = attrList.get(name);
 
-      if (config.attributeChangedCallback) {
-        config.attributeChangedCallback.call(this, name, oldValue, newValue);
-        return;
-      }
+    if (config.attributeChangedCallback) {
+      config.attributeChangedCallback.call(this, name, oldValue, newValue);
+      return;
+    }
 
-      const [stringValue] = this.attributeCache.get(name) ?? [null, null];
-      if (stringValue === newValue) {
-        // Attribute was changed via data change event. Ignore.
-        return;
-      }
+    let cacheEntry;
+    if (this.attributeCache.has(name)) {
+      cacheEntry = this.attributeCache.get(name);
+      if (cacheEntry.stringValue === newValue) return;
+    }
 
-      // @ts-expect-error any
-      const previousDataValue = this[config.key];
-      const parsedValue = newValue === null
-        ? config.nullParser(/** @type {null} */ (newValue))
-        // Avoid Boolean('') === false
-        : (config.type === 'boolean' ? true : config.parser(newValue));
+    // @ts-expect-error any
+    const previousDataValue = this[config.key];
+    const parsedValue = newValue === null
+      ? config.nullParser(/** @type {null} */ (newValue))
+    // Avoid Boolean('') === false
+      : (config.type === 'boolean' ? true : config.parser(newValue));
 
-      if (parsedValue === previousDataValue) {
-        // No internal value change
-        return;
-      }
-      // "Remember" that this attrValue equates to this data value
-      // Avoids rewriting attribute later on data change event
-      this.attributeCache.set(name, [newValue, parsedValue]);
-      // @ts-expect-error any
-      this[config.key] = parsedValue;
+    if (parsedValue === previousDataValue) {
+      // No internal value change
       return;
     }
+    // "Remember" that this attrValue equates to this data value
+    // Avoids rewriting attribute later on data change event
+    if (cacheEntry) {
+      cacheEntry.stringValue = newValue;
+      cacheEntry.parsedValue = parsedValue;
+    } else {
+      this.attributeCache.set(name, {
+        stringValue: newValue, parsedValue,
+      });
+    }
+    // @ts-expect-error any
+    this[config.key] = parsedValue;
   }
 
   get #template() {
@@ -697,19 +1124,33 @@ export default class CustomElement extends ICustomElement {
    * @param {any} changes
    */
   _onObserverPropertyChanged(name, oldValue, newValue, changes) {
-    const { reflect, attr } = this.static.propList.get(name);
-    if (attr && (reflect === true || reflect === 'write')) {
-      const [, dataValue] = this.attributeCache.get(attr) ?? [null, null];
-      // Don't change attribute if data value is equivalent
-      // (eg: Boolean('foo') === true; Number("1.0") === 1)
-      if (dataValue !== newValue) {
-        const attrValue = attrValueFromDataValue(newValue);
-        // Cache attrValue to ignore attributeChangedCallback later
-        this.attributeCache.set(attr, [attrValue, newValue]);
-        if (attrValue == null) {
-          this.removeAttribute(attr);
+    const { propList } = this.static;
+    if (propList.has(name)) {
+      const { reflect, attr } = propList.get(name);
+      if (attr && (reflect === true || reflect === 'write')) {
+        /** @type {{stringValue:string, parsedValue:any}} */
+        let cacheEntry;
+        let needsWrite = false;
+        const { attributeCache } = this;
+        if (attributeCache.has(attr)) {
+          cacheEntry = attributeCache.get(attr);
+          needsWrite = (cacheEntry.parsedValue !== newValue);
         } else {
-          this.setAttribute(attr, attrValue);
+        // @ts-ignore skip cast
+          cacheEntry = {};
+          attributeCache.set(attr, cacheEntry);
+          needsWrite = true;
+        }
+        if (needsWrite) {
+          const stringValue = attrValueFromDataValue(newValue);
+          cacheEntry.parsedValue = newValue;
+          cacheEntry.stringValue = stringValue;
+          // Cache attrValue to ignore attributeChangedCallback later
+          if (stringValue == null) {
+            this.removeAttribute(attr);
+          } else {
+            this.setAttribute(attr, stringValue);
+          }
         }
       }
     }
@@ -718,8 +1159,15 @@ export default class CustomElement extends ICustomElement {
     this.propChangedCallback(name, oldValue, newValue, changes);
   }
 
+  patch(patch) {
+    this.patching = true;
+    applyMergePatch(this, patch);
+    this.render(patch);
+    this.patching = false;
+  }
+
   /**
-   * Proxy object that returns shadow DOM elements by ID.
+   * Proxy object that returns shadow DOM elements by tag.
    * If called before interpolation (eg: on composed), returns from template
    * @return {Record<string,HTMLElement>}
    */
@@ -728,82 +1176,48 @@ export default class CustomElement extends ICustomElement {
     return (this.#refsProxy ??= new Proxy({}, {
       /**
        * @param {any} target
-       * @param {string} id
+       * @param {string} tag
        * @return {Element}
        */
-      get: (target, id) => {
+      get: (target, tag) => {
         if (!this.#composition) {
           console.warn(this.static.name, 'Attempted to access references before composing!');
         }
         const composition = this.composition;
+        let element;
         if (!composition.interpolated) {
-          let element = this.#refsCompositionCache.get(id)?.deref();
-          if (element) return element;
-          const formattedId = attrNameFromPropName(id);
+          if (this.#refsCompositionCache.has(tag)) {
+            element = this.#refsCompositionCache.get(tag).deref();
+            if (element) return element;
+          }
+          const formattedTag = attrNameFromPropName(tag);
           // console.warn(this.tagName, 'Returning template reference');
-          element = composition.template.getElementById(formattedId);
+          element = composition.template.getElementById(formattedTag);
           if (!element) return null;
-          this.#refsCompositionCache.set(id, new WeakRef(element));
+          this.#refsCompositionCache.set(tag, new WeakRef(element));
           return element;
         }
-        let element = this.#refsCache.get(id)?.deref();
-        if (element) {
-          return element;
+        if (this.#refsCache.has(tag)) {
+          element = this.#refsCache.get(tag).deref();
+          if (element) {
+            return element;
+          }
         }
-        const formattedId = attrNameFromPropName(id);
-        element = composition.getElement(this.shadowRoot, formattedId);
+
+        const formattedTag = attrNameFromPropName(tag);
+        const tagIndex = this.composition.tags.indexOf(formattedTag);
+        element = this.render.state.refs[tagIndex];
+
         if (!element) return null;
-        this.#refsCache.set(id, new WeakRef(element));
+        this.#refsCache.set(tag, new WeakRef(element));
         return element;
       },
     }));
   }
 
   get attributeCache() {
-    this._propAttributeCache ??= new Map();
-    return this._propAttributeCache;
-  }
-
-  get tabIndex() {
-    return super.tabIndex;
-  }
-
-  set tabIndex(value) {
-    if (value === super.tabIndex && value !== -1) {
-      // Non -1 value already set
-      return;
-    }
-
-    if (this.delegatesFocus && document.activeElement === this) {
-      if (this.getAttribute('tabindex') === value.toString()) {
-        // Skip if possible
-        return;
-      }
-
-      // Chrome blurs on tabindex changes with delegatesFocus
-      // Fixed in Chrome 111
-      // Remove this code ~June 2023
-      // https://bugs.chromium.org/p/chromium/issues/detail?id=1346606
-      /** @type {EventListener} */
-      const listener = (e) => {
-        e.stopImmediatePropagation();
-        e.stopPropagation();
-        if (e.type === 'blur') {
-          console.warn('Chromium bug 1346606: Tabindex change caused blur. Giving focusing back.', this);
-          this.focus();
-        } else {
-          console.warn('Chromium bug 1346606: Blocking focus event.', this);
-        }
-      };
-      this.addEventListener('blur', listener, { capture: true, once: true });
-      this.addEventListener('focus', listener, { capture: true, once: true });
-      super.tabIndex = value;
-      this.removeEventListener('blur', listener, { capture: true });
-      this.removeEventListener('focus', listener, { capture: true });
-      return;
-    }
-
-    super.tabIndex = value;
+    // eslint-disable-next-line no-return-assign
+    return (this._propAttributeCache ??= new Map());
   }
 
   get static() { return /** @type {typeof CustomElement} */ (/** @type {unknown} */ (this.constructor)); }
@@ -814,6 +1228,7 @@ export default class CustomElement extends ICustomElement {
     // eslint-disable-next-line no-return-assign
     return this._callbackArguments ??= {
       composition: this.#composition,
+      refs: this.refs,
       html: html.bind(this),
       inline: addInlineFunction,
       template: this.#template,