mount-observer 0.1.12 → 0.1.14

package/MountObserver.js

@@ -15,6 +15,7 @@ export class MountObserver extends EventTarget {
     #options;
     #abortController;
     #modules = [];
+    #configFromPromise;
     #mountedElements = {
         weakSet: new WeakSet(),
         setWeak: new Set()
@@ -39,6 +40,8 @@ export class MountObserver extends EventTarget {
     #assignTentatively;
     #elementNotifiers = new WeakMap();
     #notifierMountedElements = new WeakSet();
+    #subObservers;
+    #whenDefinedResolved = false;
     #mergeHandlerDefaults(config) {
         const doValue = config.do;
         // Only process if do is a string (single handler reference)
@@ -71,7 +74,7 @@ export class MountObserver extends EventTarget {
         this.#init = mergedConfig;
         this.#options = options;
         this.#abortController = new AbortController();
-        const { assignOnMount, assignOnDismount, stageOnMount, do: doValue, reference, loadingEagerness, import: imp } = mergedConfig;
+        const { assignOnMount, assignOnDismount, stageOnMount, do: doValue, loadingEagerness, import: imp, configFrom } = mergedConfig;
         // Make a copy of assignOnMount config using structuredClone
         if (assignOnMount !== undefined) {
             this.#asgMtSource = structuredClone(assignOnMount);
@@ -91,9 +94,9 @@ export class MountObserver extends EventTarget {
         if (doValue !== undefined) {
             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
         if (loadingEagerness === 'eager' && imp) {
@@ -113,28 +116,91 @@ export class MountObserver extends EventTarget {
             }
         }
     }
-    #validateReference() {
-        if (!this.#init.import) {
-            throw new Error('reference property requires import to be defined');
-        }
-        // Normalize import to array
-        const imports = Array.isArray(this.#init.import)
-            ? this.#init.import
-            : [this.#init.import];
-        // Normalize reference to array
-        const references = arr(this.#init.reference);
-        // 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})`);
+    /**
+     * Loads configuration from external modules specified in configFrom property.
+     * Merges multiple configs left-to-right, with inline config taking final precedence.
+     */
+    async #loadConfigFrom() {
+        const { configFrom } = this.#init;
+        if (!configFrom)
+            return;
+        // Normalize to array
+        const configPaths = Array.isArray(configFrom) ? configFrom : [configFrom];
+        // Check for duplicates
+        const pathSet = new Set();
+        for (const path of configPaths) {
+            if (pathSet.has(path)) {
+                throw new Error(`Duplicate configFrom module: '${path}'`);
+            }
+            pathSet.add(path);
+        }
+        // Load all modules
+        const loadedConfigs = [];
+        for (const path of configPaths) {
+            try {
+                const module = await import(path);
+                if (!module.mountConfig) {
+                    throw new Error(`Module '${path}' does not export 'mountConfig'`);
+                }
+                if (typeof module.mountConfig !== 'object' || module.mountConfig === null) {
+                    throw new Error(`Module '${path}' exports invalid mountConfig: must be an object`);
+                }
+                loadedConfigs.push(module.mountConfig);
             }
-            const importItem = imports[index];
-            // 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)`);
+            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;
             }
         }
+        // Merge configs: loaded configs first (left-to-right), then inline config
+        // Save the original inline config
+        const inlineConfig = { ...this.#init };
+        // Start with empty object, merge all loaded configs, then merge inline
+        let mergedConfig = {};
+        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) {
+        // 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.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) {
+        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);
+            this.#subObservers.set(key, subObserver);
+            await subObserver.observe(rootNode);
+        }
     }
     async #setupMediaQuery() {
         if (!this.#rootNode) {
@@ -175,6 +241,16 @@ export class MountObserver extends EventTarget {
     get disconnectedSignal() {
         return this.#abortController.signal;
     }
+    get mountedElements() {
+        const elements = [];
+        for (const ref of this.#mountedElements.setWeak) {
+            const element = ref.deref();
+            if (element !== undefined) {
+                elements.push(element);
+            }
+        }
+        return elements;
+    }
     getNotifier(element) {
         // Return cached notifier if it exists
         let notifier = this.#elementNotifiers.get(element);
@@ -186,10 +262,27 @@ export class MountObserver extends EventTarget {
         this.#elementNotifiers.set(element, notifier);
         return notifier;
     }
-    async observe(rootNode) {
+    /**
+     * 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) {
         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');
         }
@@ -197,7 +290,11 @@ export class MountObserver extends EventTarget {
             const { assignTentatively } = await import('assign-gingerly/assignTentatively.js');
             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) {
             await this.#setupMediaQuery();
@@ -220,7 +317,7 @@ export class MountObserver extends EventTarget {
         }
         // Process existing elements only if all conditions match
         if (this.#mediaMatches && this.#rootSizeMatches && this.#connectionMatches) {
-            this.#processNode(rootNode);
+            this.#processNode(observedNode);
         }
         // Create mutation callback
         this.#mutationCallback = (mutations) => {
@@ -248,10 +345,18 @@ export class MountObserver extends EventTarget {
             subtree: true
         };
         // Register with shared mutation observer
-        registerSharedObserver(rootNode, this.#mutationCallback, observerConfig);
+        registerSharedObserver(observedNode, this.#mutationCallback, observerConfig);
     }
     disconnect() {
         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);
@@ -288,23 +393,6 @@ export class MountObserver extends EventTarget {
         const { loadImports } = await import('./loadImports.js');
         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));
     }
     #processNode(node) {
@@ -324,7 +412,8 @@ export class MountObserver extends EventTarget {
         if ('querySelectorAll' in node && this.#init.matching) {
             const root = node;
             // 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);
@@ -345,9 +434,23 @@ export class MountObserver extends EventTarget {
         if (!matchesElement) {
             return false;
         }
+        // Check that element's customElementRegistry matches root node's registry
+        const rootNode = this.#rootNode?.deref();
+        if (rootNode) {
+            const registriesMatch = rootNode.customElementRegistry === element.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;
             }
@@ -365,19 +468,13 @@ export class MountObserver extends EventTarget {
                 return false;
             }
         }
-        // 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) => 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;
             }
         }
         // All conditions passed
@@ -406,8 +503,50 @@ export class MountObserver extends EventTarget {
             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 = {};
+            for (const [key, subObserver] of this.#subObservers.entries()) {
+                context.withObservers[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) {
             element.assignGingerly(this.#asgMtSource);
@@ -437,16 +576,6 @@ export class MountObserver extends EventTarget {
                 }
             }
         }
-        // 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);
@@ -529,8 +658,15 @@ export class MountObserver extends EventTarget {
             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 = {};
+            for (const [key, subObserver] of this.#subObservers.entries()) {
+                context.withObservers[key] = subObserver;
+            }
+        }
         // Dispatch dismount event
         const dismountEvent = new DismountEvent(element, 'with-matching-failed', this.#init);
         this.dispatchEvent(dismountEvent);