@shortfuse/materialdesignweb 0.8.0 → 0.9.1

package/core/CustomElement.js

@@ -1,11 +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
@@ -33,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, Function[]>} */
+  /** @type {Map<string, import('./observe.js').ObserverConfiguration<?,?,?>>} */
+  static _attrs = new Map();
+
+  /** @type {Map<string, Array<(this: any, ...args: any[]) => any>>} */
   static _propChangedCallbacks = new Map();
 
-  /** @type {Map<string, Function[]>} */
+  /** @type {Map<string, Array<(this: any, ...args: any[]) => any>>} */
   static _attributeChangedCallbacks = new Map();
 
-  /** @type {typeof ICustomElement._onComposeCallbacks} */
+  /** @type {Array<(callback: CallbackArguments) => any>} */
   static _onComposeCallbacks = [];
 
-  /** @type {typeof ICustomElement._onConnectedCallbacks} */
+  /** @type {Array<(callback: CallbackArguments) => any>} */
   static _onConnectedCallbacks = [];
 
-  /** @type {typeof ICustomElement._onDisconnectedCallbacks} */
+  /** @type {Array<(callback: CallbackArguments) => any>} */
   static _onDisconnectedCallbacks = [];
 
-  /** @type {typeof ICustomElement._onConstructedCallbacks} */
+  /** @type {Array<(callback: CallbackArguments) => any>} */
   static _onConstructedCallbacks = [];
 
   static interpolatesTemplate = true;
@@ -103,127 +201,256 @@ 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
+   * @param {Function} 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._onComposeCallbacks.push(({ composition }) => {
+      composition.append(...parts);
     });
-    // @ts-expect-error Can't cast T
+
+    this._addCallback('_onComposeCallbacks', /** @type {(opts: CallbackArguments) => unknown} */ ((opts) => {
+      const { composition } = opts;
+      composition.append(...parts);
+    }));
     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);
-    }
-    // @ts-expect-error Can't cast T
+  static recompose(callback) {
+    this._addCallback('_onComposeCallbacks', callback);
     return this;
   }
 
-  /** @type {typeof ICustomElement['setSchema']} */
-  static setSchema(schema) {
-    this.schema = schema;
-    // @ts-expect-error Can't cast T
+  /**
+   * 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', /** @type {(opts: CallbackArguments) => unknown} */ ((opts) => {
+      const { composition } = opts;
+      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);
+      }
+    }));
+
     return this;
   }
 
   /**
-   * Registers class asynchronously at end of current event loop cycle
-   * via `queueMicrotask`. If class is registered before then,
+   * Registers class with customElements. 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 (this.hasOwnProperty('defined') && this.defined) {
       console.warn(this.elementName, 'already registered.');
-      // @ts-expect-error Can't cast T
       return this;
     }
     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', /** @type {(opts: CallbackArguments) => unknown} */ ((opts) => {
+      const { composition } = opts;
       // console.log('onComposed:html', strings);
-        composition.append(html(strings, ...substitutions));
-      },
-    });
-    // @ts-expect-error Can't cast T
+      composition.append(html(strings, ...substitutions));
+    }));
     return this;
   }
 
   /**
    * Extends base class into a new class.
    * Use to avoid mutating base class.
-   * TODO: Add constructor arguments typing
-   * @type {typeof ICustomElement.extend}
+   * @type {{
+   * <T1 extends typeof CustomElement, T2 extends T1, T3 extends (Base:T1) => T2>
+   * (this: T1,customExtender?: T3|null): T3 extends null ? T1 : T2;
+   * }}
    */
-  static extend() {
+  static extend(customExtender) {
     // @ts-expect-error Can't cast T
-    return class extends this {};
-  }
-
-  /**
-   * Fix for Typescript not parsing constructor params
-   * @type {typeof ICustomElement.tsClassFix}
-   */
-  static tsClassFix() {
-    // @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);
@@ -233,16 +460,31 @@ 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
     return this.set(source, { ...options, writable: false });
   }
 
   /**
    * 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(
@@ -268,6 +510,7 @@ export default class CustomElement extends ICustomElement {
           {
             enumerable: false,
             configurable: true,
+            // @ts-expect-error Can't index by symbol
             value: source[symbol],
             writable: true,
             ...options,
@@ -281,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);
@@ -289,7 +539,9 @@ 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) {
     if (elementName) {
@@ -299,7 +551,6 @@ export default class CustomElement extends ICustomElement {
     customElements.define(this.elementName, this);
     CustomElement.registrations.set(this.elementName, this);
     this.defined = true;
-    // @ts-expect-error Can't cast T
     return this;
   }
 
@@ -310,6 +561,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()
@@ -335,55 +593,84 @@ 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')
+        && (config.enumerable || !this.attrList.has(attr) || !this.attrList.get(attr).enumerable)) {
+      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(
@@ -413,13 +700,26 @@ export default class CustomElement extends ICustomElement {
     return this;
   }
 
+  /**
+   * Assigns values directly to all instances (via prototype)
+   * @type {{
+   * <
+   *  CLASS extends typeof CustomElement,
+   *  ARGS extends ConstructorParameters<CLASS>,
+   *  INSTANCE extends InstanceType<CLASS>,
+   *  PROP extends string,
+   *  PROPS extends INSTANCE & Record<PROP, never>
+   *  >(this: CLASS, name: PROP):
+   *  CLASS & Class<PROPS,ARGS>
+   * }}
+   */
   static undefine(name) {
     Reflect.deleteProperty(this.prototype, name);
     if (this.propList.has(name)) {
-      const config = this.propList.get(name);
-      if (config.watchers.length && this.propChangedCallbacks.has(name)) {
+      const { watchers, attr, reflect } = this.propList.get(name);
+      if (watchers.length && this.propChangedCallbacks.has(name)) {
         const propWatchers = this.propChangedCallbacks.get(name);
-        for (const watcher of config.watchers) {
+        for (const [prop, watcher] of watchers) {
           const index = propWatchers.indexOf(watcher);
           if (index !== -1) {
             console.warn('Unwatching', name);
@@ -427,31 +727,58 @@ export default class CustomElement extends ICustomElement {
           }
         }
       }
+      if (attr && (reflect === true || reflect === 'read')) {
+        this.attrList.delete(attr);
+      }
+      this.propList.delete(name);
     }
-    this.propList.delete(name);
+
+    // @ts-expect-error Can't cast T
     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')
@@ -459,6 +786,7 @@ export default class CustomElement extends ICustomElement {
         : (typeof typeOrOptions === 'string'
           ? { type: typeOrOptions }
           : typeOrOptions);
+      // @ts-expect-error Adding property to this
       defineObservableProperty(this, name, {
         reflect: false,
         ...options,
@@ -468,12 +796,21 @@ 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[]} */
@@ -509,34 +846,51 @@ export default class CustomElement extends ICustomElement {
       },
     });
 
-    // @ts-expect-error Can't cast T
     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 [tag, listeners] of Object.entries(listenerMap)) {
-      // @ts-expect-error Can't cast T
       this.events(listeners, {
         tag: attrNameFromPropName(tag),
         ...options,
       });
     }
 
-    // @ts-expect-error Can't cast T
     return this;
   }
 
-  /** @type {typeof ICustomElement.events} */
+  /** @type {typeof CustomElement['events']} */
   static rootEvents(listeners, options) {
-    // @ts-expect-error Can't cast T
     return this.events(listeners, {
       tag: Composition.shadowRootTag,
       ...options,
     });
   }
 
-  /** @type {typeof ICustomElement['on']} */
+  /**
+   * @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 }
@@ -558,6 +912,7 @@ export default class CustomElement extends ICustomElement {
         default:
           if (name.endsWith('Changed')) {
             const prop = name.slice(0, name.length - 'Changed'.length);
+            // @ts-expect-error Computed key
             this.onPropChanged({ [prop]: fn });
             continue;
           }
@@ -566,36 +921,73 @@ export default class CustomElement extends ICustomElement {
       this._addCallback(arrayPropName, fn);
     }
 
-    // @ts-expect-error Can't cast T
     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)) {
-      if (this.propChangedCallbacks.has(prop)) {
-        this.propChangedCallbacks.get(prop).push(callback);
+    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 {
-        this.propChangedCallbacks.set(prop, [callback]);
+        propChangedCallbacks.set(prop, [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();
-      if (this.attributeChangedCallbacks.has(lcName)) {
-        this.attributeChangedCallbacks.get(lcName).push(callback);
+    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 {
-        this.attributeChangedCallbacks.set(lcName, [callback]);
+        attributeChangedCallbacks.set(name, [callback]);
       }
     }
 
-    // @ts-expect-error Can't cast T
     return this;
   }
 
@@ -611,10 +1003,15 @@ export default class CustomElement extends ICustomElement {
   /** @type {Composition<?>} */
   #composition;
 
+  #patching = false;
+
+  /** @type {Array<[string, any, CustomElement]>} */
+  #pendingPatchRenders = [];
+
   /** @type {Map<string,{stringValue:string, parsedValue:any}>} */
   _propAttributeCache;
 
-  /** @type {import('./ICustomElement.js').CallbackArguments} */
+  /** @type {CallbackArguments} */
   _callbackArguments = null;
 
   /** @param {any[]} args */
@@ -636,11 +1033,12 @@ export default class CustomElement extends ICustomElement {
      * @return {void}
      */
     this.render = this.composition.render(
-      this,
+      this.constructor.prototype,
       this,
       {
+        defaults: this.constructor.prototype,
         store: this,
-        target: this.shadowRoot,
+        shadowRoot: this.shadowRoot,
         context: this,
       },
     );
@@ -650,15 +1048,29 @@ export default class CustomElement extends ICustomElement {
     }
   }
 
-  /** @type {InstanceType<typeof ICustomElement>['propChangedCallback']} */
+  /**
+   * @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;
+   * }}
+   */
   propChangedCallback(name, oldValue, newValue, changes = newValue) {
-    if (!this.patching) {
+    if (this.#patching) {
+      this.#pendingPatchRenders.push([name, changes, this]);
+    } else {
       this.render.byProp(name, changes, this);
       // this.render({ [name]: changes });
     }
 
-    if (this.static._propChangedCallbacks.has(name)) {
-      for (const callback of this.static.propChangedCallbacks.get(name)) {
+    const { _propChangedCallbacks } = this.static;
+    if (_propChangedCallbacks.has(name)) {
+      for (const callback of _propChangedCallbacks.get(name)) {
         callback.call(this, oldValue, newValue, changes, this);
       }
     }
@@ -670,55 +1082,53 @@ export default class CustomElement extends ICustomElement {
    * @param {string|null} newValue
    */
   attributeChangedCallback(name, oldValue, newValue) {
-    const lcName = name.toLowerCase();
-    if (this.static.attributeChangedCallbacks.has(lcName)) {
-      for (const callback of this.static.attributeChangedCallbacks.get(lcName)) {
+    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;
+    }
 
-      let cacheEntry;
-      if (this.attributeCache.has(lcName)) {
-        cacheEntry = this.attributeCache.get(lcName);
-        if (cacheEntry.stringValue === newValue) 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
-      if (cacheEntry) {
-        cacheEntry.stringValue = newValue;
-        cacheEntry.parsedValue = parsedValue;
-      } else {
-        this.attributeCache.set(lcName, {
-          stringValue: 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() {
@@ -732,20 +1142,21 @@ export default class CustomElement extends ICustomElement {
    * @param {any} changes
    */
   _onObserverPropertyChanged(name, oldValue, newValue, changes) {
-    if (this.static.propList.has(name)) {
-      const { reflect, attr } = this.static.propList.get(name);
+    const { propList } = this.static;
+    if (propList.has(name)) {
+      const { reflect, attr } = propList.get(name);
       if (attr && (reflect === true || reflect === 'write')) {
-        const lcName = attr.toLowerCase();
         /** @type {{stringValue:string, parsedValue:any}} */
         let cacheEntry;
         let needsWrite = false;
-        if (this.attributeCache.has(lcName)) {
-          cacheEntry = this.attributeCache.get(lcName);
+        const { attributeCache } = this;
+        if (attributeCache.has(attr)) {
+          cacheEntry = attributeCache.get(attr);
           needsWrite = (cacheEntry.parsedValue !== newValue);
         } else {
         // @ts-ignore skip cast
           cacheEntry = {};
-          this.attributeCache.set(lcName, cacheEntry);
+          attributeCache.set(attr, cacheEntry);
           needsWrite = true;
         }
         if (needsWrite) {
@@ -766,11 +1177,17 @@ export default class CustomElement extends ICustomElement {
     this.propChangedCallback(name, oldValue, newValue, changes);
   }
 
+  /** @param {any} patch */
   patch(patch) {
-    this.patching = true;
+    this.#patching = true;
     applyMergePatch(this, patch);
+    for (const [name, changes, state] of this.#pendingPatchRenders) {
+      if (name in patch) continue;
+      this.render.byProp(name, changes, state);
+    }
+    this.#pendingPatchRenders.slice(0, this.#pendingPatchRenders.length);
     this.render(patch);
-    this.patching = false;
+    this.#patching = false;
   }
 
   /**
@@ -823,60 +1240,23 @@ export default class CustomElement extends ICustomElement {
   }
 
   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)); }
 
   get unique() { return false; }
 
+  /**
+   * @template {CustomElement} T
+   * @this {T}
+   */
   get callbackArguments() {
     // 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,