mount-observer 0.1.4 → 0.1.6

package/MountObserver.ts

@@ -1,9 +1,8 @@
 import {
-    MountInit,
+    MountConfig,
     MountObserverOptions,
     IMountObserver,
     MountContext,
-    AttrChange,
     WeakDual,
     EventConfig,
     EventConstructor,
@@ -15,14 +14,15 @@ import {
     DismountEvent,
     DisconnectEvent,
     LoadEvent,
-    AttrChangeEvent,
 } from './Events.js';
 import {
     registerSharedObserver,
     unregisterSharedObserver,
     type MutationCallback
 } from './SharedMutationObserver.js';
-import { whereOutside } from './whereOutside.js';
+import { withScopePerimeter } from './withScopePerimeter.js';
+import type { assignTentatively as AssignTentativelyType } from 'assign-gingerly/assignTentatively.js';
+import type { BaseRegistry, EnhancementConfig } from 'assign-gingerly/types.js';
 
 export class MountObserver extends EventTarget implements IMountObserver {
     // Static registry for registered handlers
@@ -35,7 +35,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#handlerRegistry.set(name, handler);
     }
     
-    #init: MountInit;
+    #init: MountConfig;
     #options: MountObserverOptions;
     #abortController: AbortController;
     #modules: any[] = [];
@@ -48,26 +48,36 @@ export class MountObserver extends EventTarget implements IMountObserver {
     #mutationCallback: MutationCallback | undefined;
     #rootNode: WeakRef<Node> | undefined;
     #importsLoaded = false;
-    #elementAttrStates = new WeakMap<Element, Map<string, string | null>>();
-    #elementOnceAttrs = new WeakMap<Element, Set<string>>();
-    #matchesWhereAttrFn: ((element: Element, whereAttr: any) => boolean) | null = null;
-    #buildAttrCoordinateMapFn: ((whereAttr: any, isCustomElement: boolean) => any) | null = null;
-    #checkAttrChangesFn: ((element: Element) => AttrChange[]) | null = null;
     #mediaQueryCleanup?: () => void;
     #mediaMatches: boolean = true;
     #asgMtSource: Record<string, any> | undefined;
     #asgDisMtSource: Record<string, any> | undefined;
+    #stageMtSource: Record<string, any> | undefined;
+    #stageReversals = new WeakMap<Element, Record<string, any>>();
+    #assignTentatively: typeof AssignTentativelyType | undefined;
     #elementNotifiers = new WeakMap<Element, EventTarget>();
     #notifierMountedElements = new WeakSet<Element>();
 
-    constructor(init: MountInit, options: MountObserverOptions = {}) {
+    constructor(config: MountConfig | EnhancementConfig[], options: MountObserverOptions = {}) {
         super();
+        
+        // Handle array shorthand - convert EnhancementConfig[] to MountConfig
+        let init: MountConfig;
+        if (Array.isArray(config)) {
+            init = {
+                matching: '*', // Match all elements, let withAttrs do the filtering
+                enhancementConfig: config
+            };
+        } else {
+            init = config;
+        }
+        
         this.#init = init;
         this.#options = options;
         this.#abortController = new AbortController();
 
         const {
-            assignOnMount, assignOnDismount, do: doValue, reference, whereAttr, loadingEagerness,
+            assignOnMount, assignOnDismount, stageOnMount, do: doValue, reference, loadingEagerness,
             import: imp
         } = init;
         // Make a copy of assignOnMount config using structuredClone
@@ -77,6 +87,9 @@ export class MountObserver extends EventTarget implements IMountObserver {
         if (assignOnDismount !== undefined) {
             this.#asgDisMtSource = structuredClone(assignOnDismount);
         }
+        if (stageOnMount !== undefined) {
+            this.#stageMtSource = structuredClone(stageOnMount);
+        }
 
         if (options.disconnectedSignal) {
             options.disconnectedSignal.addEventListener('abort', () => {
@@ -94,11 +107,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
             this.#validateReference();
         }
 
-        // Preload whereAttr utilities if needed
-        if (whereAttr) {
-            this.#preloadWhereAttrUtilities();
-        }
-
         // Start loading imports if eager
         if (loadingEagerness === 'eager' && imp) {
             this.#loadImports();
@@ -149,29 +157,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
         }
     }
     
-    async #preloadWhereAttrUtilities(): Promise<void> {
-        if (!this.#matchesWhereAttrFn) {
-            const { matchesWhereAttr } = await import('./whereAttr.js');
-            this.#matchesWhereAttrFn = matchesWhereAttr;
-        }
-        if (!this.#buildAttrCoordinateMapFn) {
-            const { buildAttrCoordinateMap } = await import('./attrCoordinates.js');
-            this.#buildAttrCoordinateMapFn = buildAttrCoordinateMap;
-        }
-        if (!this.#checkAttrChangesFn) {
-            const { checkAttrChanges } = await import('./attrChanges.js');
-            // Create a bound function that passes the required parameters
-            this.#checkAttrChangesFn = (element: Element) => {
-                return checkAttrChanges(
-                    element,
-                    this.#init,
-                    this.#buildAttrCoordinateMapFn!,
-                    this.#elementAttrStates,
-                    this.#elementOnceAttrs
-                );
-            };
-        }
-    }
     
     async #setupMediaQuery(): Promise<void> {
         if (!this.#rootNode) {
@@ -216,24 +201,29 @@ export class MountObserver extends EventTarget implements IMountObserver {
         if(this.#asgMtSource || this.#asgDisMtSource){
             await import('assign-gingerly/object-extension.js');
         }
+        if(this.#stageMtSource){
+            const { assignTentatively } = await import('assign-gingerly/assignTentatively.js');
+            this.#assignTentatively = assignTentatively;
+        }
 
         this.#rootNode = new WeakRef(rootNode);
 
         // Set up media query if specified (needs rootNode to be set first)
-        if (this.#init.whereMediaMatches) {
+        if (this.#init.withMediaMatching) {
             await this.#setupMediaQuery();
         }
-
-        // Wait for whereAttr utilities to load if needed
-        if (this.#init.whereAttr && !this.#matchesWhereAttrFn) {
-            await this.#preloadWhereAttrUtilities();
-        }
         
         // 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();
         }
         
+        // Register enhancement configs if no imports (inline only)
+        // If imports exist, registration happens in #loadImports after modules are loaded
+        if (!this.#init.import && this.#init.enhancementConfig) {
+            await this.#registerEnhancementConfigs();
+        }
+        
         // Process existing elements only if media matches
         if (this.#mediaMatches) {
             this.#processNode(rootNode);
@@ -246,8 +236,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
                 return;
             }
             
-            const attrChanges: AttrChange[] = [];
-            
             for (const mutation of mutations) {
                 if (mutation.type === 'childList') {
                     for (const node of mutation.addedNodes) {
@@ -260,34 +248,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
                             this.#handleRemoval(node as Element);
                         }
                     });
-                } else if (mutation.type === 'attributes' && mutation.target.nodeType === Node.ELEMENT_NODE) {
-                    // Handle attribute changes for mounted elements
-                    const element = mutation.target as Element;
-                    if (this.#mountedElements.weakSet.has(element) && this.#checkAttrChangesFn) {
-                        const changes = this.#checkAttrChangesFn(element);
-                        attrChanges.push(...changes);
-                    }
-                }
-            }
-            
-            // Batch and dispatch attribute changes
-            if (attrChanges.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(attrChanges, this.#init));
-                
-                // Dispatch filtered attrchange events to element-specific notifiers
-                const changesByElement = new Map<Element, AttrChange[]>();
-                for (const change of attrChanges) {
-                    if (!changesByElement.has(change.element)) {
-                        changesByElement.set(change.element, []);
-                    }
-                    changesByElement.get(change.element)!.push(change);
-                }
-                
-                for (const [element, changes] of changesByElement) {
-                    const notifier = this.#elementNotifiers.get(element);
-                    if (notifier) {
-                        notifier.dispatchEvent(new AttrChangeEvent(changes, this.#init));
-                    }
                 }
             }
         };
@@ -296,12 +256,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
             childList: true,
             subtree: true
         };
-        
-        // Add attribute observation if whereAttr is configured
-        if (this.#init.whereAttr) {
-            observerConfig.attributes = true;
-            observerConfig.attributeOldValue = true;
-        }
 
         // Register with shared mutation observer
         registerSharedObserver(rootNode, this.#mutationCallback, observerConfig);
@@ -336,29 +290,133 @@ export class MountObserver extends EventTarget implements IMountObserver {
         this.#modules = await loadImports(this.#init.import);
         this.#importsLoaded = true;
 
-        // Validate referenced whereInstanceOf if reference is specified
+        // 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.whereInstanceOf !== undefined) {
+                if (module && module.withInstance !== undefined) {
                     // Validate that it's a Constructor or array of Constructors
-                    const whereInstanceOf = module.whereInstanceOf;
-                    const constructors = arr(whereInstanceOf);
+                    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 whereInstanceOf: must be a Constructor or array of Constructors`);
+                            throw new Error(`Referenced module at index ${index} exports invalid withInstance: must be a Constructor or array of Constructors`);
                         }
                     }
                 }
             }
         }
 
+        // Register enhancement configs after imports are loaded
+        await this.#registerEnhancementConfigs();
+
         this.dispatchEvent(new LoadEvent(this.#modules, this.#init));
     }
 
+    async #registerEnhancementConfigs(): Promise<void> {
+        const rootNode = this.#rootNode?.deref();
+        if (!rootNode || !(rootNode instanceof Element)) {
+            return;
+        }
+
+        const registry = (rootNode as any).customElementRegistry?.enhancementRegistry as BaseRegistry | undefined;
+        if (!registry) {
+            return;
+        }
+
+        const items = registry.getItems();
+        
+        // Collect all enhancement configs to register
+        const configsToRegister: EnhancementConfig[] = [];
+        
+        // First, add inline enhancementConfig(s)
+        if (this.#init.enhancementConfig) {
+            const inlineConfigs = arr(this.#init.enhancementConfig);
+            configsToRegister.push(...inlineConfigs);
+        }
+        
+        // Then, add referenced enhancementConfig(s) from imported modules
+        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.enhancementConfig !== undefined) {
+                    const referencedConfigs = arr(module.enhancementConfig);
+                    configsToRegister.push(...referencedConfigs);
+                }
+            }
+        }
+        
+        // Register each config if not already registered (using reference equality)
+        for (const config of configsToRegister) {
+            if (!items.includes(config)) {
+                registry.push(config);
+            }
+        }
+    }
+
+    /**
+     * Resolves template variables in a string recursively
+     * @param template - Template string with ${var} placeholders
+     * @param patterns - The patterns object containing variable values
+     * @returns Resolved string
+     */
+    #resolveAttrTemplate(template: string, patterns: Record<string, any>): string {
+        return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
+            const value = patterns[varName];
+            if (value === undefined) {
+                throw new Error(`Undefined template variable: ${varName}`);
+            }
+            if (typeof value === 'string') {
+                // Recursively resolve
+                return this.#resolveAttrTemplate(value, patterns);
+            }
+            return String(value);
+        });
+    }
+
+    /**
+     * Checks if element has attribute with enh- prefix handling
+     * @param element - The element to check
+     * @param attrName - The attribute name (without enh- prefix)
+     * @param allowUnprefixed - Pattern that element tag name must match to allow unprefixed attributes
+     * @returns true if element has the attribute
+     */
+    #hasAttributeWithEnhPrefix(
+        element: Element, 
+        attrName: string, 
+        allowUnprefixed?: string | RegExp
+    ): boolean {
+        const isCustomElement = element.tagName.includes('-');
+        const isSVGElement = element instanceof SVGElement;
+        
+        // For custom elements and SVG - strict enh- requirement
+        if (isCustomElement || isSVGElement) {
+            if (element.hasAttribute(`enh-${attrName}`)) {
+                return true;
+            }
+            
+            // Only check unprefixed if tag name matches allowUnprefixed pattern
+            if (allowUnprefixed) {
+                const pattern = typeof allowUnprefixed === 'string' 
+                    ? new RegExp(allowUnprefixed) 
+                    : allowUnprefixed;
+                const tagName = element.tagName.toLowerCase();
+                if (pattern.test(tagName)) {
+                    return element.hasAttribute(attrName);
+                }
+            }
+            return false;
+        }
+        
+        // For built-in elements - enh- is alias (check both)
+        return element.hasAttribute(`enh-${attrName}`) || element.hasAttribute(attrName);
+    }
+
     #processNode(node: Node): void {
         // If it's an element node, check if it matches
         if (node.nodeType === Node.ELEMENT_NODE) {
@@ -370,11 +428,11 @@ export class MountObserver extends EventTarget implements IMountObserver {
         }
 
         // Process children
-        if ('querySelectorAll' in node) {
+        if ('querySelectorAll' in node && this.#init.matching) {
             const root = node as DocumentFragment;
             
             // Get all elements matching the CSS selector first
-            root.querySelectorAll(this.#init.whereElementMatches).forEach(child => {
+            root.querySelectorAll(this.#init.matching).forEach(child => {
                 if (this.#matchesSelector(child)) {
                     this.#handleMatch(child);
                 }
@@ -384,36 +442,27 @@ export class MountObserver extends EventTarget implements IMountObserver {
 
     #matchesSelector(element: Element): boolean {
         //TODO:  reduce redundncy with this.#init?
-        // Check whereElementMatches condition
-        const matchesElement = element.matches(this.#init.whereElementMatches);
-        if (!matchesElement) {
+        // Check matching condition
+        if (!this.#init.matching) {
             return false;
         }
         
-        // Check whereOutside condition if specified (donut hole scoping)
-        if (this.#init.whereOutside) {
-            const rootNode = this.#rootNode?.deref();
-            if (!rootNode || !whereOutside(rootNode, element, this.#init.whereOutside)) {
-                return false;
-            }
+        const matchesElement = element.matches(this.#init.matching);
+        if (!matchesElement) {
+            return false;
         }
         
-        // Check whereAttr condition if specified
-        if (this.#init.whereAttr) {
-            // Use cached function (should be loaded by now from constructor)
-            if (!this.#matchesWhereAttrFn) {
-                console.warn('whereAttr utilities not loaded yet');
-                return false;
-            }
-            
-            if (!this.#matchesWhereAttrFn(element, this.#init.whereAttr)) {
+        // 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 whereInstanceOf condition if specified
-        if (this.#init.whereInstanceOf) {
-            const constructors = arr(this.#init.whereInstanceOf);
+        // 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);
@@ -423,14 +472,14 @@ export class MountObserver extends EventTarget implements IMountObserver {
             }
         }
         
-        // Check referenced whereInstanceOf if imports are loaded and reference is specified
+        // 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.whereInstanceOf !== undefined) {
-                    const constructors = arr(module.whereInstanceOf);
+                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);
@@ -441,6 +490,79 @@ export class MountObserver extends EventTarget implements IMountObserver {
                 }
             }
         }
+        //TODO:  move to a separate file?
+        // Check withAttrs condition if specified (attribute-based matching)
+        // Check ALL enhancementConfigs (inline + referenced)
+        const enhancementConfigs: EnhancementConfig[] = [];
+        
+        // Add inline configs
+        if (this.#init.enhancementConfig) {
+            enhancementConfigs.push(...arr(this.#init.enhancementConfig));
+        }
+        
+        // Add referenced configs if imports are loaded
+        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.enhancementConfig !== undefined) {
+                    enhancementConfigs.push(...arr(module.enhancementConfig));
+                }
+            }
+        }
+        
+        // Check if ANY enhancementConfig has withAttrs - if so, element must match at least ONE
+        let hasAnyWithAttrs = false;
+        let matchesAnyWithAttrs = false;
+        
+        for (const config of enhancementConfigs) {
+            if (!config.withAttrs) {
+                continue; // Skip configs without withAttrs
+            }
+            
+            hasAnyWithAttrs = true;
+            const withAttrs = config.withAttrs;
+            const allowUnprefixed = config.allowUnprefixed;
+            
+            // Collect all attribute names to check for this config
+            const attrNames: string[] = [];
+            
+            for (const key in withAttrs) {
+                // Skip base and underscore-prefixed config keys
+                if (key === 'base' || key.startsWith('_')) {
+                    continue;
+                }
+                
+                const value = withAttrs[key];
+                if (typeof value === 'string') {
+                    // Resolve template string to get actual attribute name
+                    const attrName = this.#resolveAttrTemplate(value, withAttrs);
+                    attrNames.push(attrName);
+                }
+            }
+            
+            // Handle base attribute specially if present
+            if ('base' in withAttrs && typeof withAttrs.base === 'string') {
+                attrNames.push(withAttrs.base);
+            }
+            
+            // Check if element has at least ONE of the specified attributes (OR logic within config)
+            if (attrNames.length > 0) {
+                const hasAnyAttribute = attrNames.some(attrName => 
+                    this.#hasAttributeWithEnhPrefix(element, attrName, allowUnprefixed)
+                );
+                
+                if (hasAnyAttribute) {
+                    matchesAnyWithAttrs = true;
+                    break; // Found a matching config, no need to check others
+                }
+            }
+        }
+        
+        // If any config has withAttrs but element doesn't match any of them, reject
+        if (hasAnyWithAttrs && !matchesAnyWithAttrs) {
+            return false;
+        }
         
         // All conditions passed
         return true;
@@ -474,7 +596,7 @@ export class MountObserver extends EventTarget implements IMountObserver {
             modules: this.#modules,
             observer: this,
             rootNode,
-            mountInit: this.#init,
+            MountConfig: this.#init,
         };
 
         // Apply assignGingerly if specified
@@ -482,6 +604,43 @@ export class MountObserver extends EventTarget implements IMountObserver {
             element.assignGingerly(this.#asgMtSource);
         }
 
+        // Apply assignTentatively if specified (staged assignments)
+        if (this.#stageMtSource && this.#assignTentatively) {
+            const reversal = {};
+            this.#assignTentatively(element, this.#stageMtSource, { reversal });
+            this.#stageReversals.set(element, reversal);
+        }
+
+        // Spawn enhancements if configured
+        // Process inline configs first, then referenced configs
+        const enhancementConfigs: EnhancementConfig[] = [];
+        
+        // Add inline configs
+        if (this.#init.enhancementConfig) {
+            enhancementConfigs.push(...arr(this.#init.enhancementConfig));
+        }
+        
+        // Add referenced configs if imports are loaded
+        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.enhancementConfig !== undefined) {
+                    enhancementConfigs.push(...arr(module.enhancementConfig));
+                }
+            }
+        }
+        
+        // Spawn each enhancement that has a spawn property
+        if (enhancementConfigs.length > 0) {
+            await import('assign-gingerly/object-extension.js');
+            for (const config of enhancementConfigs) {
+                if (config.spawn) {
+                    (element as any).enh.get(config, context);
+                }
+            }
+        }
+
         // Check if notifier exists BEFORE calling do callback
         const notifierExistedBeforeDo = this.#elementNotifiers.has(element);
 
@@ -535,20 +694,6 @@ export class MountObserver extends EventTarget implements IMountObserver {
             const { emitMountedElementEvents } = await import('./emitEvents.js');
             await emitMountedElementEvents(element, this.#init, this.#processedEventsForElement);
         }
-        
-        // Check for initial attribute changes if whereAttr is configured
-        if (this.#checkAttrChangesFn) {
-            const changes = this.#checkAttrChangesFn(element);
-            if (changes.length > 0) {
-                this.dispatchEvent(new AttrChangeEvent(changes, this.#init));
-                
-                // Also dispatch to element-specific notifier
-                const notifier = this.#elementNotifiers.get(element);
-                if (notifier) {
-                    notifier.dispatchEvent(new AttrChangeEvent(changes, this.#init));
-                }
-            }
-        }
     }
     
     async assignGingerly(config: Record<string, any> | undefined): Promise<void> {
@@ -585,7 +730,14 @@ export class MountObserver extends EventTarget implements IMountObserver {
             return;
         }
 
-        
+        // Reverse tentative assignments first (restore original values)
+        if (this.#stageMtSource && this.#assignTentatively) {
+            const reversal = this.#stageReversals.get(element);
+            if (reversal) {
+                this.#assignTentatively(element, reversal);
+                this.#stageReversals.delete(element);
+            }
+        }
 
         // Apply assignGingerly if specified for dismount
         if (this.#asgDisMtSource) {
@@ -616,12 +768,12 @@ export class MountObserver extends EventTarget implements IMountObserver {
             modules: this.#modules,
             observer: this,
             rootNode,
-            mountInit: this.#init,
+            MountConfig: this.#init,
         };
 
 
         // Dispatch dismount event
-        const dismountEvent = new DismountEvent(element, 'where-element-matches-failed', this.#init);
+        const dismountEvent = new DismountEvent(element, 'with-matching-failed', this.#init);
         this.dispatchEvent(dismountEvent);
         
         // Dispatch to element-specific notifier