mount-observer 0.1.4 → 0.1.5

package/MountObserver.js

@@ -1,7 +1,7 @@
 import { arr } from './arr.js';
-import { MountEvent, DismountEvent, DisconnectEvent, LoadEvent, AttrChangeEvent, } from './Events.js';
+import { MountEvent, DismountEvent, DisconnectEvent, LoadEvent, } from './Events.js';
 import { registerSharedObserver, unregisterSharedObserver } from './SharedMutationObserver.js';
-import { whereOutside } from './whereOutside.js';
+import { withScopePerimeter } from './withScopePerimeter.js';
 export class MountObserver extends EventTarget {
     // Static registry for registered handlers
     static #handlerRegistry = new Map();
@@ -24,23 +24,32 @@ export class MountObserver extends EventTarget {
     #mutationCallback;
     #rootNode;
     #importsLoaded = false;
-    #elementAttrStates = new WeakMap();
-    #elementOnceAttrs = new WeakMap();
-    #matchesWhereAttrFn = null;
-    #buildAttrCoordinateMapFn = null;
-    #checkAttrChangesFn = null;
     #mediaQueryCleanup;
     #mediaMatches = true;
     #asgMtSource;
     #asgDisMtSource;
+    #stageMtSource;
+    #stageReversals = new WeakMap();
+    #assignTentatively;
     #elementNotifiers = new WeakMap();
     #notifierMountedElements = new WeakSet();
-    constructor(init, options = {}) {
+    constructor(config, options = {}) {
         super();
+        // Handle array shorthand - convert EnhancementConfig[] to MountConfig
+        let init;
+        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, import: imp } = init;
+        const { assignOnMount, assignOnDismount, stageOnMount, do: doValue, reference, loadingEagerness, import: imp } = init;
         // Make a copy of assignOnMount config using structuredClone
         if (assignOnMount !== undefined) {
             this.#asgMtSource = structuredClone(assignOnMount);
@@ -48,6 +57,9 @@ export class MountObserver extends EventTarget {
         if (assignOnDismount !== undefined) {
             this.#asgDisMtSource = structuredClone(assignOnDismount);
         }
+        if (stageOnMount !== undefined) {
+            this.#stageMtSource = structuredClone(stageOnMount);
+        }
         if (options.disconnectedSignal) {
             options.disconnectedSignal.addEventListener('abort', () => {
                 this.disconnect();
@@ -61,10 +73,6 @@ export class MountObserver extends EventTarget {
         if (reference !== undefined) {
             this.#validateReference();
         }
-        // Preload whereAttr utilities if needed
-        if (whereAttr) {
-            this.#preloadWhereAttrUtilities();
-        }
         // Start loading imports if eager
         if (loadingEagerness === 'eager' && imp) {
             this.#loadImports();
@@ -106,23 +114,6 @@ export class MountObserver extends EventTarget {
             }
         }
     }
-    async #preloadWhereAttrUtilities() {
-        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) => {
-                return checkAttrChanges(element, this.#init, this.#buildAttrCoordinateMapFn, this.#elementAttrStates, this.#elementOnceAttrs);
-            };
-        }
-    }
     async #setupMediaQuery() {
         if (!this.#rootNode) {
             throw new Error('Cannot setup media query before observe() is called');
@@ -153,19 +144,24 @@ export class MountObserver extends EventTarget {
         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);
@@ -176,7 +172,6 @@ export class MountObserver extends EventTarget {
             if (!this.#mediaMatches) {
                 return;
             }
-            const attrChanges = [];
             for (const mutation of mutations) {
                 if (mutation.type === 'childList') {
                     for (const node of mutation.addedNodes) {
@@ -190,43 +185,12 @@ export class MountObserver extends EventTarget {
                         }
                     });
                 }
-                else if (mutation.type === 'attributes' && mutation.target.nodeType === Node.ELEMENT_NODE) {
-                    // Handle attribute changes for mounted elements
-                    const element = mutation.target;
-                    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();
-                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));
-                    }
-                }
             }
         };
         const observerConfig = {
             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);
     }
@@ -253,25 +217,111 @@ 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
+        // 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() {
+        const rootNode = this.#rootNode?.deref();
+        if (!rootNode || !(rootNode instanceof Element)) {
+            return;
+        }
+        const registry = rootNode.customElementRegistry?.enhancementRegistry;
+        if (!registry) {
+            return;
+        }
+        const items = registry.getItems();
+        // Collect all enhancement configs to register
+        const configsToRegister = [];
+        // 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, patterns) {
+        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, attrName, allowUnprefixed) {
+        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) {
         // If it's an element node, check if it matches
         if (node.nodeType === Node.ELEMENT_NODE) {
@@ -281,10 +331,10 @@ export class MountObserver extends EventTarget {
             }
         }
         // Process children
-        if ('querySelectorAll' in node) {
+        if ('querySelectorAll' in node && this.#init.matching) {
             const root = node;
             // 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);
                 }
@@ -293,45 +343,37 @@ export class MountObserver extends EventTarget {
     }
     #matchesSelector(element) {
         //TODO:  reduce redundncy with this.#init?
-        // Check whereElementMatches condition
-        const matchesElement = element.matches(this.#init.whereElementMatches);
+        // Check matching condition
+        if (!this.#init.matching) {
+            return false;
+        }
+        const matchesElement = element.matches(this.#init.matching);
         if (!matchesElement) {
             return false;
         }
-        // Check whereOutside condition if specified (donut hole scoping)
-        if (this.#init.whereOutside) {
+        // Check withScopePerimeter condition if specified (donut hole scoping)
+        if (this.#init.withScopePerimeter) {
             const rootNode = this.#rootNode?.deref();
-            if (!rootNode || !whereOutside(rootNode, element, this.#init.whereOutside)) {
-                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)) {
+            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);
             if (!matchesInstanceOf) {
                 return false;
             }
         }
-        // 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) => element instanceof constructor);
                     if (!matchesInstanceOf) {
@@ -340,6 +382,65 @@ export class MountObserver extends EventTarget {
                 }
             }
         }
+        //TODO:  move to a separate file?
+        // Check withAttrs condition if specified (attribute-based matching)
+        // Check ALL enhancementConfigs (inline + referenced)
+        const enhancementConfigs = [];
+        // 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 = [];
+            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;
     }
@@ -366,12 +467,44 @@ export class MountObserver extends EventTarget {
             modules: this.#modules,
             observer: this,
             rootNode,
-            mountInit: this.#init,
+            MountConfig: this.#init,
         };
         // Apply assignGingerly if specified
         if (this.#asgMtSource) {
             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 = [];
+        // 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.enh.get(config, context);
+                }
+            }
+        }
         // Check if notifier exists BEFORE calling do callback
         const notifierExistedBeforeDo = this.#elementNotifiers.has(element);
         // Call do callback(s) - can be string, function, or array
@@ -419,18 +552,6 @@ export class MountObserver extends EventTarget {
             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) {
         // Handle undefined case
@@ -462,6 +583,14 @@ export class MountObserver extends EventTarget {
         if (!this.#mountedElements.weakSet.has(element)) {
             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) {
             element.assignGingerly(this.#asgDisMtSource);
@@ -487,10 +616,10 @@ export class MountObserver extends EventTarget {
             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
         const notifier = this.#elementNotifiers.get(element);