@shortfuse/materialdesignweb 0.9.3 → 0.10.0

package/core/CustomElement.js

@@ -113,16 +113,6 @@ import { addInlineFunction, html } from './template.js';
  * @typedef {(T | Array<[keyof T & string, T[keyof T]]>)} ObjectOrObjectEntries
  */
 
-/**
- * @template {abstract new (...args: any) => unknown} T
- * @param {InstanceType<T>} instance
- */
-function superOf(instance) {
-  const staticContext = instance.constructor;
-  const superOfStatic = Object.getPrototypeOf(staticContext);
-  return superOfStatic.prototype;
-}
-
 /**
  * Clone attribute
  * @param {string} name
@@ -191,13 +181,8 @@ export default class CustomElement extends HTMLElement {
   static supportsElementInternalsRole = CustomElement.supportsElementInternals
     && 'role' in ElementInternals.prototype;
 
-  /** @type {boolean} */
-  static templatable = null;
-
   static defined = false;
 
-  static autoRegistration = true;
-
   /** @type {Map<string, typeof CustomElement>} */
   static registrations = new Map();
 
@@ -326,6 +311,42 @@ export default class CustomElement extends HTMLElement {
     this[collection].push(callback);
   }
 
+  /**
+   * @this T
+   * @template {typeof CustomElement} T
+   * @template {keyof T} K
+   * @param {K} collection
+   * @param {Function} [callback]
+   */
+  static _removeCallback(collection, callback) {
+    if (!this.hasOwnProperty(collection)) {
+      // @ts-expect-error not typed
+      this[collection] = [...this[collection]];
+    }
+    // @ts-expect-error any
+    this[collection] = this[collection].filter((fn) => fn !== callback);
+  }
+
+  /**
+   * @param {Map<string, Function[]>} map
+   * @param {string} name
+   * @param {Function} [callback]
+   * @return {void}
+   */
+  static _removeFromCallbackMap(map, name, callback) {
+    if (!map.has(name)) return;
+    if (!callback) {
+      map.delete(name);
+      return;
+    }
+    const next = map.get(name).filter((fn) => fn !== callback);
+    if (next.length === 0) {
+      map.delete(name);
+    } else {
+      map.set(name, next);
+    }
+  }
+
   /**
    * Append parts to composition
    * @type {{
@@ -627,7 +648,7 @@ export default class CustomElement extends HTMLElement {
     }
     // TODO: Inspect possible closure bloat
     config.changedCallback = function wrappedChangedCallback(oldValue, newValue, changes) {
-      this._onObserverPropertyChanged.call(this, name, oldValue, newValue, changes);
+      this.#onObserverPropertyChanged.call(this, name, oldValue, newValue, changes);
     };
 
     this.propList.set(name, config);
@@ -644,6 +665,32 @@ export default class CustomElement extends HTMLElement {
     return this;
   }
 
+  /**
+   * Creates observable property on instances (via prototype)
+   * @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)
+   *  > (this: CLASS, name: KEY, options: OPTIONS)
+   *    : 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
+   * }}
+   */
+  static setPrototype(name, typeOrOptions) {
+    // @ts-expect-error Can't cast T
+    this.prop(name, typeOrOptions);
+    return null;
+  }
+
   /**
    * Define properties on instances via Object.defineProperties().
    * Automatically sets property non-enumerable if name begins with `_`.
@@ -924,6 +971,109 @@ export default class CustomElement extends HTMLElement {
     return this;
   }
 
+  /**
+   * @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 off(nameOrCallbacks, callback) {
+    const callbacks = typeof nameOrCallbacks === 'string'
+      ? { [nameOrCallbacks]: callback }
+      : nameOrCallbacks;
+    for (const [name, fn] of Object.entries(callbacks)) {
+      /** @type {keyof (typeof CustomElement)} */
+      let arrayPropName;
+      switch (name) {
+        case 'composed': arrayPropName = '_onComposeCallbacks'; break;
+        case 'constructed': arrayPropName = '_onConstructedCallbacks'; break;
+        case 'connected': arrayPropName = '_onConnectedCallbacks'; break;
+        case 'disconnected': arrayPropName = '_onDisconnectedCallbacks'; break;
+        case 'props':
+          this.offPropChanged(fn);
+          continue;
+        case 'attrs':
+          this.offAttributeChanged(fn);
+          continue;
+        default:
+          if (name.endsWith('Changed')) {
+            const prop = name.slice(0, name.length - 'Changed'.length);
+            // @ts-expect-error Computed key
+            this.offPropChanged({ [prop]: fn });
+            continue;
+          }
+          throw new Error('Invalid callback name');
+      }
+      this._removeCallback(arrayPropName, fn);
+    }
+
+    return this;
+  }
+
+  /**
+   * @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 offPropChanged(options) {
+    const entries = Array.isArray(options) ? options : Object.entries(options);
+    const { propChangedCallbacks } = this;
+    for (const [prop, callback] of entries) {
+      this._removeFromCallbackMap(propChangedCallbacks, prop, callback);
+    }
+
+    return this;
+  }
+
+  /**
+   * @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 offAttributeChanged(options) {
+    const entries = Array.isArray(options) ? options : Object.entries(options);
+    const { attributeChangedCallbacks } = this;
+    for (const [name, callback] of entries) {
+      this._removeFromCallbackMap(attributeChangedCallbacks, name, callback);
+    }
+
+    return this;
+  }
+
   /**
    * @type {{
    * <
@@ -1009,10 +1159,10 @@ export default class CustomElement extends HTMLElement {
   #pendingPatchRenders = [];
 
   /** @type {Map<string,{stringValue:string, parsedValue:any}>} */
-  _propAttributeCache;
+  #propAttributeCache;
 
   /** @type {CallbackArguments} */
-  _callbackArguments = null;
+  #callbackArguments = null;
 
   /** @param {any[]} args */
   constructor(...args) {
@@ -1141,7 +1291,7 @@ export default class CustomElement extends HTMLElement {
    * @param {any} newValue
    * @param {any} changes
    */
-  _onObserverPropertyChanged(name, oldValue, newValue, changes) {
+  #onObserverPropertyChanged(name, oldValue, newValue, changes) {
     const { propList } = this.static;
     if (propList.has(name)) {
       const { reflect, attr } = propList.get(name);
@@ -1177,10 +1327,12 @@ export default class CustomElement extends HTMLElement {
     this.propChangedCallback(name, oldValue, newValue, changes);
   }
 
+  get static() { return /** @type {typeof CustomElement} */ (/** @type {unknown} */ (this.constructor)); }
+
   /** @param {any} patch */
   patch(patch) {
     this.#patching = true;
-    applyMergePatch(this, patch);
+    applyMergePatch(this, patch, 'object');
     for (const [name, changes, state] of this.#pendingPatchRenders) {
       if (name in patch) continue;
       this.render.byProp(name, changes, state);
@@ -1204,9 +1356,6 @@ export default class CustomElement extends HTMLElement {
        * @return {Element}
        */
       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) {
@@ -1241,20 +1390,16 @@ export default class CustomElement extends HTMLElement {
 
   get attributeCache() {
     // eslint-disable-next-line no-return-assign
-    return (this._propAttributeCache ??= new Map());
+    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 ??= {
+    return this.#callbackArguments ??= {
       composition: this.#composition,
       refs: this.refs,
       html: html.bind(this),
@@ -1268,7 +1413,7 @@ export default class CustomElement extends HTMLElement {
   get composition() {
     if (this.#composition) return this.#composition;
 
-    if (!this.unique && this.static.hasOwnProperty('_composition')) {
+    if (this.static.hasOwnProperty('_composition')) {
       this.#composition = this.static._composition;
       return this.static._composition;
     }
@@ -1281,10 +1426,8 @@ export default class CustomElement extends HTMLElement {
       callback.call(this, this.callbackArguments);
     }
 
-    if (!this.unique) {
-      // Cache compilation into static property
-      this.static._composition = this.#composition;
-    }
+    // Cache compilation into static property
+    this.static._composition = this.#composition;
 
     return this.#composition;
   }

package/core/customTypes.js

@@ -1,6 +1,7 @@
 /** @typedef {import('./CustomElement').default} CustomElement */
 
 import { attrNameFromPropName } from './dom.js';
+import { subscribeProxy } from './observe.js';
 
 /**
  * @see https://html.spec.whatwg.org/multipage/webappapis.html#event-handler-attributes
@@ -53,6 +54,71 @@ export const EVENT_HANDLER_TYPE = {
   },
 };
 
+/**
+ * @template {unknown} T
+ * @typedef {import('./observe.js').ObserverOptions<'object', T, CustomElement>} STORE_PROXY_TYPE
+ */
+
+/** @typedef {WeakMap<CustomElement, Map<string, Function>>} */
+const StoreProxySubscriptions = new WeakMap();
+
+/**
+ * Proxy store binding. Expects a proxy with a `.subscribe(fn)` method that
+ * returns an unsubscribe function.
+ * @template {unknown} T
+ * @type {import('./observe.js').ObserverOptions<'object', T, CustomElement>}
+ */
+export const STORE_PROXY_TYPE = {
+  type: 'object',
+  reflect: false,
+  parser(v) { return v; },
+  diff: null, // Skip computing entire change
+  propChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    /** @return {void} */
+    function connectedCallback() {
+      let subscriptions = StoreProxySubscriptions.get(this);
+      if (!subscriptions) {
+        subscriptions = new Map();
+        StoreProxySubscriptions.set(this, subscriptions);
+      }
+      const unsubscribeFn = subscribeProxy(this[name], (patch) => {
+        this.render.byProp(name, patch, this);
+      });
+      subscriptions.set(name, unsubscribeFn);
+      // Render immediately
+      this.render.byProp(name, this[name], this);
+    }
+    /** @return {void} */
+    function disconnectedCallback() {
+      const subscriptions = StoreProxySubscriptions.get(this);
+      if (!subscriptions?.has(name)) return;
+      const unsubscribeFn = subscriptions.get(name);
+      unsubscribeFn();
+      subscriptions.delete(name);
+    }
+    if (oldValue) {
+      // Perform unsubscribe
+      disconnectedCallback.call(this);
+    }
+
+    if (newValue) {
+      this.static.on({
+        connected: connectedCallback,
+        disconnected: disconnectedCallback,
+      });
+      if (this.isConnected) {
+        connectedCallback.call(this);
+      }
+    } else {
+      this.static.off({
+        connected: connectedCallback,
+        disconnected: disconnectedCallback,
+      });
+    }
+  },
+};
+
 // const weakRefValues = new WeakMap();
 
 // /**

package/core/jsonMergePatch.js

@@ -1,15 +1,17 @@
-/** @link https://www.rfc-editor.org/rfc/rfc7396 */
+/** @see https://www.rfc-editor.org/rfc/rfc7396 */
 
 /**
+ * Default behavior: arrays are treated like objects (index/length merge).
  * @template T1
  * @template T2
  * @param {T1} target
  * @param {T2} patch
  * @return {T1|T2|(T1 & T2)}
  */
-export function applyMergePatch(target, patch) {
+export function applyMergePatchObject(target, patch) {
   // @ts-ignore Runtime check
   if (target === patch) return target;
+  if (Array.isArray(patch)) return patch;
   if (target == null || patch == null || typeof patch !== 'object') return patch;
   if (typeof target !== 'object') {
     // @ts-ignore Forced cast to object
@@ -19,30 +21,119 @@ export function applyMergePatch(target, patch) {
     if (value == null) {
       // @ts-ignore Runtime check
       if (key in target) {
-        // @ts-ignore T1 is always object
+        // @ts-ignore target is object
         delete target[key];
       }
     } else {
-      // @ts-ignore T1 is forced object
-      target[key] = applyMergePatch(target[key], value);
+      // @ts-ignore target is object
+      target[key] = applyMergePatchObject(target[key], value);
     }
   }
   return target;
 }
 
+/**
+ * RFC 7396 semantics: only JSON objects are merged. Arrays are replaced.
+ * @template T1
+ * @template T2
+ * @param {T1} target
+ * @param {T2} patch
+ * @return {T1|T2|(T1 & T2)}
+ */
+function applyMergePatchReference(target, patch) {
+  // @ts-ignore Runtime check
+  if (target === patch) return target;
+  const patchIsObject = patch != null && typeof patch === 'object' && !Array.isArray(patch);
+  const targetIsObject = target != null && typeof target === 'object' && !Array.isArray(target);
+  if (!patchIsObject || !targetIsObject) return patch;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value == null) {
+      // @ts-ignore Runtime check
+      if (key in target) {
+        // @ts-ignore target is object
+        delete target[key];
+      }
+    } else {
+      // @ts-ignore target is object
+      target[key] = applyMergePatchReference(target[key], value);
+    }
+  }
+  return target;
+}
+
+/**
+ * @template T1
+ * @template T2
+ * @param {T1} target
+ * @param {T2} patch
+ * @param {'clone'|'object'|'reference'} [arrayStrategy='reference']
+ * @return {T1|T2|(T1 & T2)}
+ */
+export function applyMergePatch(target, patch, arrayStrategy = 'reference') {
+  switch (arrayStrategy) {
+    case 'clone':
+    case 'object':
+      return applyMergePatchObject(target, patch);
+    default:
+      return applyMergePatchReference(target, patch);
+  }
+}
+
+/**
+ * Creates a JSON Merge patch based
+ * Allows different strategies for arrays
+ *  - `reference`: Returns array as-is (replacement).
+ * @param {object|number|string|boolean} previous
+ * @param {object|number|string|boolean} current
+ * @return {any} Patch
+ */
+export function buildMergePatchReference(previous, current) {
+  if (previous === current) return null;
+  if (current == null || typeof current !== 'object') return current;
+  if (previous == null || typeof previous !== 'object') {
+    return structuredClone(current);
+  }
+
+  const patch = {};
+  if (Array.isArray(current)) {
+    return current;
+  }
+
+  const previousKeys = new Set(Object.keys(previous));
+  for (const [key, value] of Object.entries(current)) {
+    previousKeys.delete(key);
+    if (value === null) {
+      // @ts-ignore patch is Object
+      patch[key] = null;
+      continue;
+    }
+    if (value == null) {
+      continue; // Skip undefined
+    }
+    // @ts-ignore previous is Object
+    const changes = buildMergePatchReference(previous[key], value);
+    if (changes !== null) {
+      // @ts-ignore patch is Object
+      patch[key] = changes;
+    }
+  }
+  for (const key of previousKeys) {
+    // @ts-ignore patch is Object
+    patch[key] = null;
+  }
+
+  return patch;
+}
+
 /**
  * Creates a JSON Merge patch based
  * Allows different strategies for arrays
- *  - `reference`: Per spec, returns array as is
  *  - `clone`: Clones all entries with no inspection.
- *  - `object`: Convert to flattened, array-like objects. Requires
- *    consumer of patch to be aware of the schema beforehand.
  * @param {object|number|string|boolean} previous
  * @param {object|number|string|boolean} current
- * @param {'clone'|'object'|'reference'} [arrayStrategy='reference']
  * @return {any} Patch
  */
-export function buildMergePatch(previous, current, arrayStrategy = 'reference') {
+export function buildMergePatchClone(previous, current) {
   if (previous === current) return null;
   if (current == null || typeof current !== 'object') return current;
   if (previous == null || typeof previous !== 'object') {
@@ -51,13 +142,53 @@ export function buildMergePatch(previous, current, arrayStrategy = 'reference')
 
   const patch = {};
   if (Array.isArray(current)) {
-    if (arrayStrategy === 'reference') {
-      return current;
+    return structuredClone(current);
+  }
+
+  const previousKeys = new Set(Object.keys(previous));
+  for (const [key, value] of Object.entries(current)) {
+    previousKeys.delete(key);
+    if (value === null) {
+      // @ts-ignore patch is Object
+      patch[key] = null;
+      continue;
     }
-    // Assume previous is array
-    if (arrayStrategy === 'clone') {
-      return structuredClone(current);
+    if (value == null) {
+      continue; // Skip undefined
+    }
+    // @ts-ignore previous is Object
+    const changes = buildMergePatchClone(previous[key], value);
+    if (changes !== null) {
+      // @ts-ignore patch is Object
+      patch[key] = changes;
     }
+  }
+  for (const key of previousKeys) {
+    // @ts-ignore patch is Object
+    patch[key] = null;
+  }
+
+  return patch;
+}
+
+/**
+ * Creates a JSON Merge patch based
+ * Allows different strategies for arrays
+ *  - `object`: Convert to flattened, array-like objects. Requires
+ *    consumer of patch to be aware of the schema beforehand.
+ * @param {object|number|string|boolean} previous
+ * @param {object|number|string|boolean} current
+ * @return {any} Patch
+ */
+export function buildMergePatchObject(previous, current) {
+  if (previous === current) return null;
+  if (current == null || typeof current !== 'object') return current;
+  if (previous == null || typeof previous !== 'object') {
+    return structuredClone(current);
+  }
+
+  const patch = {};
+  if (Array.isArray(current)) {
     for (const [index, value] of current.entries()) {
       if (value === null) {
         // @ts-ignore patch is ArrayLike
@@ -68,7 +199,7 @@ export function buildMergePatch(previous, current, arrayStrategy = 'reference')
         continue; // Skip undefined
       }
       // @ts-ignore previous is ArrayLike
-      const changes = buildMergePatch(previous[index], value, arrayStrategy);
+      const changes = buildMergePatchObject(previous[index], value);
       if (changes !== null) {
         // @ts-ignore patch is ArrayLike
         patch[index] = changes;
@@ -96,7 +227,7 @@ export function buildMergePatch(previous, current, arrayStrategy = 'reference')
       continue; // Skip undefined
     }
     // @ts-ignore previous is Object
-    const changes = buildMergePatch(previous[key], value, arrayStrategy);
+    const changes = buildMergePatchObject(previous[key], value);
     if (changes !== null) {
       // @ts-ignore patch is Object
       patch[key] = changes;
@@ -111,13 +242,36 @@ export function buildMergePatch(previous, current, arrayStrategy = 'reference')
 }
 
 /**
- * Short-circuited JSON Merge Patch evaluation
+ * Creates a JSON Merge patch based
+ * Allows different strategies for arrays
+ *  - `reference`: Per spec, returns array as is
+ *  - `clone`: Clones all entries with no inspection.
+ *  - `object`: Convert to flattened, array-like objects. Requires
+ *    consumer of patch to be aware of the schema beforehand.
+ * @param {object|number|string|boolean} previous
+ * @param {object|number|string|boolean} current
+ * @param {'clone'|'object'|'reference'} [arrayStrategy='reference']
+ * @return {any} Patch
+ */
+export function buildMergePatch(previous, current, arrayStrategy = 'reference') {
+  switch (arrayStrategy) {
+    case 'clone':
+      return buildMergePatchClone(previous, current);
+    case 'object':
+      return buildMergePatchObject(previous, current);
+    default:
+      return buildMergePatchReference(previous, current);
+  }
+}
+
+/**
+ * Default behavior: arrays are treated like objects (index/length merge).
  * @template T
  * @param {T} target
  * @param {Partial<T>} patch
  * @return {boolean}
  */
-export function hasMergePatch(target, patch) {
+export function hasMergePatchReference(target, patch) {
   if (target === patch) return false;
   if (patch == null || typeof patch !== 'object') return true;
   if (target != null && typeof target !== 'object') {
@@ -130,9 +284,38 @@ export function hasMergePatch(target, patch) {
         return true;
       }
     // @ts-ignore T is object
-    } else if (hasMergePatch(target[key], value)) {
+    } else if (hasMergePatchReference(target[key], value)) {
       return true;
     }
   }
   return false;
 }
+
+/**
+ * Object-merge semantics for arrays (alias of reference strategy).
+ * @template T
+ * @param {T} target
+ * @param {Partial<T>} patch
+ * @return {boolean}
+ */
+export function hasMergePatchObject(target, patch) {
+  if (Array.isArray(patch)) return target !== patch;
+  return hasMergePatchReference(target, patch);
+}
+
+/**
+ * @template T
+ * @param {T} target
+ * @param {Partial<T>} patch
+ * @param {'clone'|'object'|'reference'} [arrayStrategy='reference']
+ * @return {boolean}
+ */
+export function hasMergePatch(target, patch, arrayStrategy = 'reference') {
+  switch (arrayStrategy) {
+    case 'clone':
+    case 'object':
+      return hasMergePatchObject(target, patch);
+    default:
+      return hasMergePatchReference(target, patch);
+  }
+}