mount-observer 0.1.11 → 0.1.13

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()
@@ -48,7 +50,13 @@ export class MountObserver extends EventTarget implements IMountObserver {
     #rootNode: WeakRef<Node> | undefined;
     #importsLoaded = false;
     #mediaQueryCleanup?: () => void;
+    #rootSizeCleanup?: () => void;
+    #intersectionCleanup?: () => void;
+    #connectionCleanup?: () => void;
+    #intersectionObserver?: IntersectionObserver;
     #mediaMatches: boolean = true;
+    #rootSizeMatches: boolean = true;
+    #connectionMatches: boolean = true;
     #asgMtSource: Record<string, any> | undefined;
     #asgDisMtSource: Record<string, any> | undefined;
     #stageMtSource: Record<string, any> | undefined;
@@ -56,18 +64,53 @@ 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;
 
-    constructor(config: MountConfig, options: MountObserverOptions = {}) {
+    #mergeHandlerDefaults(config: MountConfig): MountConfig {
+        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: Partial<MountConfig> = {};
+        const proto = HandlerClass as any;
+        
+        // Get all static properties
+        for (const key of Object.getOwnPropertyNames(proto)) {
+            if (key !== 'prototype' && key !== 'length' && key !== 'name') {
+                handlerDefaults[key as keyof MountConfig] = proto[key];
+            }
+        }
+        
+        // Merge: handler defaults first, then inline config (inline trumps)
+        // Using object spread - inline config overwrites handler defaults
+        return { ...handlerDefaults, ...config };
+    }
+
+    constructor(config: MountConfig<TKeys>, options: MountObserverOptions = {}) {
         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;
+            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);
@@ -90,9 +133,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
@@ -115,35 +158,87 @@ 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);
 
-        // Normalize reference to array
-        const references = arr(this.#init.reference);
+                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`);
+                }
 
-        // 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;
+    }
+
+    /**
+     * 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> {
@@ -165,10 +260,79 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#mediaQueryCleanup = result.cleanup;
     }
 
+    async #setupRootSizeObserver(): Promise<void> {
+        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(): Promise<void> {
+        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(): Promise<void> {
+        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(): AbortSignal {
         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);
@@ -182,10 +346,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');
         }
@@ -194,27 +377,45 @@ export class MountObserver extends EventTarget implements IMountObserver {
             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;
             }
             
@@ -240,12 +441,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);
@@ -258,6 +468,24 @@ export class MountObserver extends EventTarget implements IMountObserver {
             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;
     }
@@ -272,26 +500,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
         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));
     }
 
@@ -300,7 +508,11 @@ export class MountObserver extends EventTarget implements IMountObserver {
         if (node.nodeType === Node.ELEMENT_NODE) {
             const element = node as Element;
             
-            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);
             }
         }
@@ -310,8 +522,12 @@ 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 => {
-                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);
                 }
             });
@@ -319,59 +535,70 @@ export class MountObserver extends EventTarget implements IMountObserver {
     }
 
     #matchesSelector(element: Element): boolean {
-        //TODO:  reduce redundncy with this.#init?
-        // Check matching condition
-        if (!this.#init.matching) {
-            return false;
-        }
-        
-        const matchesElement = element.matches(this.#init.matching);
-        if (!matchesElement) {
-            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)) {
+            //TODO:  reduce redundncy with this.#init?
+            // Check matching condition
+            if (!this.#init.matching) {
                 return false;
             }
-        }
-        
-        // Check withInstance condition if specified
-        if (this.#init.withInstance) {
-            const constructors = arr(this.#init.withInstance);
-            
-            // Element must be an instance of at least one constructor (OR logic for array)
-            const matchesInstanceOf = constructors.some(constructor => element instanceof constructor);
-            
-            if (!matchesInstanceOf) {
+
+            const matchesElement = element.matches(this.#init.matching);
+            if (!matchesElement) {
                 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: Constructor) => element instanceof constructor);
-                    
-                    if (!matchesInstanceOf) {
-                        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) {
+                if (!rootNode || !withScopePerimeter(rootNode, element, this.#init.withScopePerimeter)) {
+                    return false;
+                }
+            }
+
+            // 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 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
+            return true;
         }
 
-        // All conditions passed
-        return true;
-    }
 
     async #handleMatch(element: Element): Promise<void> {
         if (this.#processedDoForElement.has(element)) {
@@ -397,12 +624,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) {
@@ -437,18 +707,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);
@@ -539,12 +797,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