mount-observer 0.1.12 → 0.1.14

package/MountObserver.ts

@@ -21,9 +21,10 @@ import {
     type MutationCallback
 } from './SharedMutationObserver.js';
 import { withScopePerimeter } from './withScopePerimeter.js';
+import { getRegistryRoot } from './getRegistryRoot.js';
 import type { assignTentatively as AssignTentativelyType } from 'assign-gingerly/assignTentatively.js';
 
-export class MountObserver extends EventTarget implements IMountObserver {
+export class MountObserver<TKeys extends string = string> extends EventTarget implements IMountObserver {
     // Static registry for registered handlers
     static #handlerRegistry = new Map<string, Constructor>();
     
@@ -38,6 +39,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
     #options: MountObserverOptions;
     #abortController: AbortController;
     #modules: any[] = [];
+    #configFromPromise: Promise<void> | undefined;
     #mountedElements: WeakDual<Element> = {
         weakSet: new WeakSet(),
         setWeak: new Set()
@@ -62,6 +64,8 @@ export class MountObserver extends EventTarget implements IMountObserver {
     #assignTentatively: typeof AssignTentativelyType | undefined;
     #elementNotifiers = new WeakMap<Element, EventTarget>();
     #notifierMountedElements = new WeakSet<Element>();
+    #subObservers: Map<string, MountObserver> | undefined;
+    #whenDefinedResolved = false;
 
     #mergeHandlerDefaults(config: MountConfig): MountConfig {
         const doValue = config.do;
@@ -94,7 +98,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
         return { ...handlerDefaults, ...config };
     }
 
-    constructor(config: MountConfig, options: MountObserverOptions = {}) {
+    constructor(config: MountConfig<TKeys>, options: MountObserverOptions = {}) {
         super();
         
         // Merge handler defaults if do is a string reference
@@ -105,8 +109,8 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#abortController = new AbortController();
 
         const {
-            assignOnMount, assignOnDismount, stageOnMount, do: doValue, reference, loadingEagerness,
-            import: imp
+            assignOnMount, assignOnDismount, stageOnMount, do: doValue, loadingEagerness,
+            import: imp, configFrom
         } = mergedConfig;
         // Make a copy of assignOnMount config using structuredClone
         if (assignOnMount !== undefined) {
@@ -130,9 +134,9 @@ export class MountObserver extends EventTarget implements IMountObserver {
             this.#validateDoHandlers();
         }
 
-        // Validate reference property if present
-        if (reference !== undefined) {
-            this.#validateReference();
+        // Load configFrom modules if specified
+        if (configFrom !== undefined) {
+            this.#configFromPromise = this.#loadConfigFrom();
         }
 
         // Start loading imports if eager
@@ -155,35 +159,110 @@ export class MountObserver extends EventTarget implements IMountObserver {
             }
         }
     }
-    
-    #validateReference(): void {
-        if (!this.#init.import) {
-            throw new Error('reference property requires import to be defined');
+
+    /**
+     * Loads configuration from external modules specified in configFrom property.
+     * Merges multiple configs left-to-right, with inline config taking final precedence.
+     */
+    async #loadConfigFrom(): Promise<void> {
+        const { configFrom } = this.#init;
+        if (!configFrom) return;
+
+        // Normalize to array
+        const configPaths = Array.isArray(configFrom) ? configFrom : [configFrom];
+
+        // Check for duplicates
+        const pathSet = new Set<string>();
+        for (const path of configPaths) {
+            if (pathSet.has(path)) {
+                throw new Error(`Duplicate configFrom module: '${path}'`);
+            }
+            pathSet.add(path);
         }
 
-        // Normalize import to array
-        const imports = Array.isArray(this.#init.import) 
-            ? this.#init.import 
-            : [this.#init.import];
+        // Load all modules
+        const loadedConfigs: MountConfig[] = [];
+        for (const path of configPaths) {
+            try {
+                const module = await import(path);
+
+                if (!module.mountConfig) {
+                    throw new Error(`Module '${path}' does not export 'mountConfig'`);
+                }
 
-        // Normalize reference to array
-        const references = arr(this.#init.reference);
+                if (typeof module.mountConfig !== 'object' || module.mountConfig === null) {
+                    throw new Error(`Module '${path}' exports invalid mountConfig: must be an object`);
+                }
 
-        // Validate each reference index
-        for (const index of references) {
-            // Check if index is within bounds
-            if (index < 0 || index >= imports.length) {
-                throw new Error(`reference index ${index} is out of bounds (import array length: ${imports.length})`);
+                loadedConfigs.push(module.mountConfig);
+            } catch (error) {
+                // Re-throw with better context if it's not already our error
+                if (error instanceof Error && !error.message.includes(path)) {
+                    throw new Error(`Failed to load config from '${path}': ${error.message}`);
+                }
+                throw error;
             }
+        }
 
-            const importItem = imports[index];
+        // Merge configs: loaded configs first (left-to-right), then inline config
+        // Save the original inline config
+        const inlineConfig = { ...this.#init };
 
-            // Check if it's a JS module (not a 2D array with type option)
-            if (Array.isArray(importItem)) {
-                throw new Error(`reference index ${index} points to a non-JS module import (array with type option)`);
-            }
+        // Start with empty object, merge all loaded configs, then merge inline
+        let mergedConfig: MountConfig = {};
+        for (const loadedConfig of loadedConfigs) {
+            mergedConfig = Object.assign(mergedConfig, loadedConfig);
+        }
+
+        // Inline config takes final precedence
+        mergedConfig = Object.assign(mergedConfig, inlineConfig);
+
+        // Update the init config with merged result
+        this.#init = mergedConfig;
+    }
+
+    /**
+     * Waits for custom elements to be defined before mounting.
+     * Only runs once per observer instance.
+     */
+    async #waitForWhenDefined(rootNode: Node): Promise<void> {
+        // Skip if already resolved or not configured
+        if (this.#whenDefinedResolved || !this.#init.whenDefined) {
+            return;
         }
+        
+        // Get the custom element registry from the root node
+        const registry = (rootNode as any).customElementRegistry || customElements;
+        
+        // Normalize to array
+        const tagNames = arr(this.#init.whenDefined);
+        
+        // Wait for all tags to be defined
+        await Promise.all(tagNames.map(tag => registry.whenDefined(tag)));
+        
+        // Mark as resolved so we don't check again
+        this.#whenDefinedResolved = true;
     }
+
+    /**
+     * Creates and initializes sub-observers from the `with` property.
+     * Each sub-observer observes the same root node as the parent.
+     * Sub-observers are stored in #subObservers Map for lifecycle management.
+     */
+    async #createSubObservers(rootNode: Node): Promise<void> {
+        const withConfig = this.#init.with;
+        if (!withConfig) return;
+        
+        this.#subObservers = new Map();
+        
+        for (const [key, subConfig] of Object.entries(withConfig)) {
+            const subObserver = new MountObserver(subConfig as MountConfig);
+            this.#subObservers.set(key, subObserver);
+            await subObserver.observe(rootNode);
+        }
+    }
+
+    
     
     
     async #setupMediaQuery(): Promise<void> {
@@ -267,6 +346,17 @@ export class MountObserver extends EventTarget implements IMountObserver {
         return this.#abortController.signal;
     }
 
+    get mountedElements(): Element[] {
+        const elements: Element[] = [];
+        for (const ref of this.#mountedElements.setWeak) {
+            const element = ref.deref();
+            if (element !== undefined) {
+                elements.push(element);
+            }
+        }
+        return elements;
+    }
+
     getNotifier(element: Element): EventTarget {
         // Return cached notifier if it exists
         let notifier = this.#elementNotifiers.get(element);
@@ -280,10 +370,29 @@ export class MountObserver extends EventTarget implements IMountObserver {
         return notifier;
     }
 
-    async observe(rootNode: Node): Promise<void> {
+    /**
+     * Begins observing elements within the provided node.
+     * 
+     * @param observedNode - The node to observe for matching elements. This is the root
+     *                       of the observation scope where the mutation observer will be
+     *                       registered. All matching elements within this node (and its
+     *                       descendants) will trigger mount callbacks.
+     *                       
+     *                       Common values:
+     *                       - `document` - Observe the entire document
+     *                       - `element` - Observe a specific subtree
+     *                       - `shadowRoot` - Observe within a shadow DOM
+     */
+    async observe(observedNode: Node): Promise<void> {
         if (this.#rootNode) {
             throw new Error('Already observing');
         }
+        
+        // Wait for configFrom loading to complete if it was started
+        if (this.#configFromPromise) {
+            await this.#configFromPromise;
+        }
+        
         if(this.#asgMtSource || this.#asgDisMtSource){
             await import('assign-gingerly/object-extension.js');
         }
@@ -292,7 +401,13 @@ export class MountObserver extends EventTarget implements IMountObserver {
             this.#assignTentatively = assignTentatively;
         }
 
-        this.#rootNode = new WeakRef(rootNode);
+        this.#rootNode = new WeakRef(observedNode);
+
+        // Wait for whenDefined if specified (must be first check)
+        await this.#waitForWhenDefined(observedNode);
+
+        // Create sub-observers from `with` property
+        await this.#createSubObservers(observedNode);
 
         // Set up media query if specified (needs rootNode to be set first)
         if (this.#init.withMediaMatching) {
@@ -321,7 +436,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
         
         // Process existing elements only if all conditions match
         if (this.#mediaMatches && this.#rootSizeMatches && this.#connectionMatches) {
-            this.#processNode(rootNode);
+            this.#processNode(observedNode);
         }
 
         // Create mutation callback
@@ -353,12 +468,21 @@ export class MountObserver extends EventTarget implements IMountObserver {
         };
 
         // Register with shared mutation observer
-        registerSharedObserver(rootNode, this.#mutationCallback, observerConfig);
+        registerSharedObserver(observedNode, this.#mutationCallback, observerConfig);
     }
 
     disconnect(): void {
         const rootNode = this.#rootNode?.deref();
         
+        // Disconnect all sub-observers first (recursive)
+        if (this.#subObservers) {
+            for (const subObserver of this.#subObservers.values()) {
+                subObserver.disconnect();
+            }
+            this.#subObservers.clear();
+            this.#subObservers = undefined;
+        }
+        
         // Unregister from shared mutation observer
         if (rootNode && this.#mutationCallback) {
             unregisterSharedObserver(rootNode, this.#mutationCallback);
@@ -403,26 +527,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#modules = await loadImports(this.#init.import);
         this.#importsLoaded = true;
 
-        // Validate referenced whereInstanceOf if reference is specified
-        if (this.#init.reference !== undefined) {
-            const references = arr(this.#init.reference);
-
-            for (const index of references) {
-                const module = this.#modules[index];
-                if (module && module.whereInstanceOf !== undefined) {
-                    // Validate that it's a Constructor or array of Constructors
-                    const whereInstanceOf = module.whereInstanceOf;
-                    const constructors = arr(whereInstanceOf);
-                    
-                    for (const constructor of constructors) {
-                        if (typeof constructor !== 'function') {
-                            throw new Error(`Referenced module at index ${index} exports invalid whereInstanceOf: must be a Constructor or array of Constructors`);
-                        }
-                    }
-                }
-            }
-        }
-
         this.dispatchEvent(new LoadEvent(this.#modules, this.#init));
     }
 
@@ -445,7 +549,8 @@ export class MountObserver extends EventTarget implements IMountObserver {
             const root = node as DocumentFragment;
             
             // Get all elements matching the CSS selector first
-            root.querySelectorAll(this.#init.matching).forEach(child => {
+            const matches = root.querySelectorAll(this.#init.matching);
+            matches.forEach(child => {
                 // If intersection observer is active, start observing the element
                 if (this.#intersectionObserver) {
                     this.#intersectionObserver.observe(child);
@@ -468,9 +573,22 @@ export class MountObserver extends EventTarget implements IMountObserver {
                 return false;
             }
 
+            // Check that element's customElementRegistry matches root node's registry
+            const rootNode = this.#rootNode?.deref();
+            if (rootNode) {
+                const registriesMatch = (rootNode as any).customElementRegistry === (element as any).customElementRegistry;
+                
+                // If whereDifferentCustomElementRegistry is true, exclude matching registries
+                if (this.#init.whereDifferentCustomElementRegistry) {
+                    if (registriesMatch) return false;
+                } else {
+                    // Default behavior: exclude non-matching registries
+                    if (!registriesMatch) return false;
+                }
+            }
+
             // Check withScopePerimeter condition if specified (donut hole scoping)
             if (this.#init.withScopePerimeter) {
-                const rootNode = this.#rootNode?.deref();
                 if (!rootNode || !withScopePerimeter(rootNode, element, this.#init.withScopePerimeter)) {
                     return false;
                 }
@@ -493,22 +611,14 @@ export class MountObserver extends EventTarget implements IMountObserver {
                 }
             }
 
-            // Check referenced whereInstanceOf if imports are loaded and reference is specified
-            if (this.#importsLoaded && this.#init.reference !== undefined) {
-                const references = arr(this.#init.reference);
-
-                for (const index of references) {
-                    const module = this.#modules[index];
-                    if (module && module.whereInstanceOf !== undefined) {
-                        const constructors = arr(module.whereInstanceOf);
-
-                        // Element must be an instance of at least one constructor (OR logic within this module)
-                        const matchesInstanceOf = constructors.some((constructor: Constructor) => element instanceof constructor);
-
-                        if (!matchesInstanceOf) {
-                            return false;
-                        }
-                    }
+            // Check whereLocalNameMatches condition if specified
+            if (this.#init.whereLocalNameMatches) {
+                const pattern = typeof this.#init.whereLocalNameMatches === 'string' 
+                    ? new RegExp(this.#init.whereLocalNameMatches)
+                    : this.#init.whereLocalNameMatches;
+                
+                if (!pattern.test(element.localName)) {
+                    return false;
                 }
             }
 
@@ -541,12 +651,55 @@ export class MountObserver extends EventTarget implements IMountObserver {
             return;
         }
 
-        const context: MountContext = {
+        const context: MountContext<TKeys> = {
             modules: this.#modules,
             observer: this,
             rootNode,
-            MountConfig: this.#init,
+            mountConfig: this.#init,
         };
+        
+        // Add withObservers if sub-observers exist
+        if (this.#subObservers && this.#subObservers.size > 0) {
+            context.withObservers = {} as {[K in TKeys]: IMountObserver};
+            for (const [key, subObserver] of this.#subObservers.entries()) {
+                (context.withObservers as any)[key] = subObserver;
+            }
+        }
+
+        // Check shouldMount condition if specified (final gate before mounting)
+        if (this.#init.shouldMount) {
+            try {
+                const shouldMount = this.#init.shouldMount(element, context);
+                if (!shouldMount) {
+                    // shouldMount returned false - don't mount this element
+                    // Remove from processed set so it can be re-evaluated later
+                    this.#processedDoForElement.delete(element);
+                    // Remove from mounted elements tracking
+                    this.#mountedElements.weakSet.delete(element);
+                    for (const ref of this.#mountedElements.setWeak) {
+                        if (ref.deref() === element) {
+                            this.#mountedElements.setWeak.delete(ref);
+                            break;
+                        }
+                    }
+                    return;
+                }
+            } catch (error) {
+                // shouldMount threw an error - treat as false and log
+                console.error('shouldMount check failed:', error);
+                // Remove from processed set so it can be re-evaluated later
+                this.#processedDoForElement.delete(element);
+                // Remove from mounted elements tracking
+                this.#mountedElements.weakSet.delete(element);
+                for (const ref of this.#mountedElements.setWeak) {
+                    if (ref.deref() === element) {
+                        this.#mountedElements.setWeak.delete(ref);
+                        break;
+                    }
+                }
+                return;
+            }
+        }
 
         // Apply assignGingerly if specified
         if (this.#asgMtSource) {
@@ -581,18 +734,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
             }
         }
 
-        // Call referenced do functions from imported modules
-        if (this.#init.reference !== undefined) {
-            const references = arr(this.#init.reference);
-
-            for (const index of references) {
-                const module = this.#modules[index];
-                if (module && typeof module.do === 'function') {
-                    module.do(element, context);
-                }
-            }
-        }
-
         // Dispatch mount event
         const mountEvent = new MountEvent(element, this.#modules, this.#init, context);
         this.dispatchEvent(mountEvent);
@@ -683,12 +824,20 @@ export class MountObserver extends EventTarget implements IMountObserver {
             return;
         }
 
-        const context: MountContext = {
+        const context: MountContext<TKeys> = {
             modules: this.#modules,
             observer: this,
             rootNode,
-            MountConfig: this.#init,
+            mountConfig: this.#init,
         };
+        
+        // Add withObservers if sub-observers exist
+        if (this.#subObservers && this.#subObservers.size > 0) {
+            context.withObservers = {} as {[K in TKeys]: IMountObserver};
+            for (const [key, subObserver] of this.#subObservers.entries()) {
+                (context.withObservers as any)[key] = subObserver;
+            }
+        }
 
 
         // Dispatch dismount event