mount-observer 0.1.11 → 0.1.13

package/MountObserver.js

@@ -15,6 +15,7 @@ export class MountObserver extends EventTarget {
     #options;
     #abortController;
     #modules = [];
+    #configFromPromise;
     #mountedElements = {
         weakSet: new WeakSet(),
         setWeak: new Set()
@@ -25,7 +26,13 @@ export class MountObserver extends EventTarget {
     #rootNode;
     #importsLoaded = false;
     #mediaQueryCleanup;
+    #rootSizeCleanup;
+    #intersectionCleanup;
+    #connectionCleanup;
+    #intersectionObserver;
     #mediaMatches = true;
+    #rootSizeMatches = true;
+    #connectionMatches = true;
     #asgMtSource;
     #asgDisMtSource;
     #stageMtSource;
@@ -33,12 +40,40 @@ export class MountObserver extends EventTarget {
     #assignTentatively;
     #elementNotifiers = new WeakMap();
     #notifierMountedElements = new WeakSet();
+    #subObservers;
+    #mergeHandlerDefaults(config) {
+        const doValue = config.do;
+        // Only process if do is a string (single handler reference)
+        if (typeof doValue !== 'string') {
+            return config;
+        }
+        // Look up the handler class
+        const HandlerClass = MountObserver.#handlerRegistry.get(doValue);
+        if (!HandlerClass) {
+            // Validation will catch this later
+            return config;
+        }
+        // Extract static properties from the handler class
+        const handlerDefaults = {};
+        const proto = HandlerClass;
+        // Get all static properties
+        for (const key of Object.getOwnPropertyNames(proto)) {
+            if (key !== 'prototype' && key !== 'length' && key !== 'name') {
+                handlerDefaults[key] = proto[key];
+            }
+        }
+        // Merge: handler defaults first, then inline config (inline trumps)
+        // Using object spread - inline config overwrites handler defaults
+        return { ...handlerDefaults, ...config };
+    }
     constructor(config, options = {}) {
         super();
-        this.#init = config;
+        // Merge handler defaults if do is a string reference
+        const mergedConfig = this.#mergeHandlerDefaults(config);
+        this.#init = mergedConfig;
         this.#options = options;
         this.#abortController = new AbortController();
-        const { assignOnMount, assignOnDismount, stageOnMount, do: doValue, reference, loadingEagerness, import: imp } = config;
+        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);
@@ -58,9 +93,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) {
@@ -80,28 +115,73 @@ 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}'`);
             }
-            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)`);
+            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);
+            }
+            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;
+    }
+    /**
+     * 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) {
@@ -112,9 +192,46 @@ export class MountObserver extends EventTarget {
         this.#mediaMatches = result.mediaMatches;
         this.#mediaQueryCleanup = result.cleanup;
     }
+    async #setupRootSizeObserver() {
+        if (!this.#rootNode) {
+            throw new Error('Cannot setup root size observer before observe() is called');
+        }
+        const { setupRootSizeObserver } = await import('./rootSizeObserver.js');
+        const result = setupRootSizeObserver(this.#init, this.#rootNode, this.#mountedElements, this.#modules, this, (node) => this.#processNode(node));
+        this.#rootSizeMatches = result.conditionMatches;
+        this.#rootSizeCleanup = result.cleanup;
+    }
+    async #setupElementIntersection() {
+        if (!this.#rootNode) {
+            throw new Error('Cannot setup element intersection before observe() is called');
+        }
+        const { setupElementIntersection } = await import('./elementIntersection.js');
+        const result = setupElementIntersection(this.#init, this.#rootNode, this.#mountedElements, this.#modules, this, (element) => this.#matchesSelector(element), (element) => this.#handleMatch(element));
+        this.#intersectionObserver = result.intersectionObserver;
+        this.#intersectionCleanup = result.cleanup;
+    }
+    async #setupConnectionMonitor() {
+        if (!this.#rootNode) {
+            throw new Error('Cannot setup connection monitor before observe() is called');
+        }
+        const { setupConnectionMonitor } = await import('./connectionMonitor.js');
+        const result = setupConnectionMonitor(this.#init, this.#rootNode, this.#mountedElements, this.#modules, this, (node) => this.#processNode(node));
+        this.#connectionMatches = result.conditionMatches;
+        this.#connectionCleanup = result.cleanup;
+    }
     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);
@@ -126,10 +243,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');
         }
@@ -137,23 +271,37 @@ 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);
+        // 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();
         }
+        // Set up root size observer if specified (needs rootNode to be set first)
+        if (this.#init.whereObservedRootSizeMatches) {
+            await this.#setupRootSizeObserver();
+        }
+        // Set up element intersection observer if specified (needs rootNode to be set first)
+        if (this.#init.whereElementIntersectsWith) {
+            await this.#setupElementIntersection();
+        }
+        // Set up connection monitor if specified (needs rootNode to be set first)
+        if (this.#init.whereConnectionHas) {
+            await this.#setupConnectionMonitor();
+        }
         // Wait for eager imports to complete if they were started in constructor
         if (this.#init.loadingEagerness === 'eager' && this.#init.import && !this.#importsLoaded) {
             await this.#loadImports();
         }
-        // Process existing elements only if media matches
-        if (this.#mediaMatches) {
-            this.#processNode(rootNode);
+        // Process existing elements only if all conditions match
+        if (this.#mediaMatches && this.#rootSizeMatches && this.#connectionMatches) {
+            this.#processNode(observedNode);
         }
         // Create mutation callback
         this.#mutationCallback = (mutations) => {
-            // Skip processing if media doesn't match
-            if (!this.#mediaMatches) {
+            // Skip processing if any condition doesn't match
+            if (!this.#mediaMatches || !this.#rootSizeMatches || !this.#connectionMatches) {
                 return;
             }
             for (const mutation of mutations) {
@@ -176,10 +324,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);
@@ -190,6 +346,21 @@ export class MountObserver extends EventTarget {
             this.#mediaQueryCleanup();
             this.#mediaQueryCleanup = undefined;
         }
+        // Remove root size observer
+        if (this.#rootSizeCleanup) {
+            this.#rootSizeCleanup();
+            this.#rootSizeCleanup = undefined;
+        }
+        // Remove intersection observer
+        if (this.#intersectionCleanup) {
+            this.#intersectionCleanup();
+            this.#intersectionCleanup = undefined;
+        }
+        // Remove connection monitor
+        if (this.#connectionCleanup) {
+            this.#connectionCleanup();
+            this.#connectionCleanup = undefined;
+        }
         this.#abortController.abort();
         this.#rootNode = undefined;
     }
@@ -201,30 +372,18 @@ export class MountObserver extends EventTarget {
         const { loadImports } = await import('./loadImports.js');
         this.#modules = await loadImports(this.#init.import);
         this.#importsLoaded = true;
-        // Validate referenced withInstance 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.withInstance !== undefined) {
-                    // Validate that it's a Constructor or array of Constructors
-                    const withInstance = module.withInstance;
-                    const constructors = arr(withInstance);
-                    for (const constructor of constructors) {
-                        if (typeof constructor !== 'function') {
-                            throw new Error(`Referenced module at index ${index} exports invalid withInstance: must be a Constructor or array of Constructors`);
-                        }
-                    }
-                }
-            }
-        }
         this.dispatchEvent(new LoadEvent(this.#modules, this.#init));
     }
     #processNode(node) {
         // If it's an element node, check if it matches
         if (node.nodeType === Node.ELEMENT_NODE) {
             const element = node;
-            if (this.#matchesSelector(element)) {
+            // If intersection observer is active, start observing the element
+            // The intersection callback will handle mounting when it intersects
+            if (this.#intersectionObserver) {
+                this.#intersectionObserver.observe(element);
+            }
+            else if (this.#matchesSelector(element)) {
                 this.#handleMatch(element);
             }
         }
@@ -232,8 +391,13 @@ 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 => {
-                if (this.#matchesSelector(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);
+                }
+                else if (this.#matchesSelector(child)) {
                     this.#handleMatch(child);
                 }
             });
@@ -249,35 +413,47 @@ 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;
             }
         }
-        // Check withInstance condition if specified
-        if (this.#init.withInstance) {
-            const constructors = arr(this.#init.withInstance);
+        // Check whereObservedRootSizeMatches condition if specified
+        if (this.#init.whereObservedRootSizeMatches && !this.#rootSizeMatches) {
+            return false;
+        }
+        // Check whereInstanceOf condition if specified
+        if (this.#init.whereInstanceOf) {
+            const constructors = arr(this.#init.whereInstanceOf);
             // Element must be an instance of at least one constructor (OR logic for array)
             const matchesInstanceOf = constructors.some(constructor => element instanceof constructor);
             if (!matchesInstanceOf) {
                 return false;
             }
         }
-        // Check referenced withInstance 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.withInstance !== undefined) {
-                    const constructors = arr(module.withInstance);
-                    // 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
@@ -306,8 +482,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);
@@ -337,16 +555,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);
@@ -429,8 +637,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);