mount-observer 0.1.14 → 0.1.15

package/handlers/MountObserverScript.js

@@ -0,0 +1,78 @@
+import { EvtRt } from '../EvtRt.js';
+import '../ElementMountExtension.js';
+/**
+ * Handler for Mount Observer Script Elements (MOSEs).
+ * Processes script[type="mountobserver"] elements to declaratively configure mount observers.
+ *
+ * Supports two modes:
+ * 1. External JSON: <script type="mountobserver" src="./config.json"></script>
+ * 2. Inline JSON: <script type="mountobserver">{ "matching": "div" }</script>
+ *
+ * Supports multiple configs in one script element:
+ * - Single config: { "do": "builtIns.hoistTemplate" }
+ * - Multiple configs: [{ "do": "builtIns.hoistTemplate" }, { "do": "builtIns.HTMLInclude" }]
+ */
+export class MountObserverScriptHandler extends EvtRt {
+    // Static properties define default MountConfig constraints
+    static matching = 'script[type="mountobserver"]';
+    static whereInstanceOf = HTMLScriptElement;
+    async mount(mountedElement, MountConfig, context) {
+        this.abort(); // Clean up event listeners (one-time operation)
+        const scriptElement = mountedElement;
+        let config = scriptElement.export;
+        if (!config) {
+            // Check if script has src attribute
+            const srcAttr = scriptElement.getAttribute('src');
+            if (srcAttr) {
+                // External JSON mode: import from src
+                const resolvedUrl = new URL(srcAttr, document.baseURI).href;
+                try {
+                    const module = await import(resolvedUrl, { with: { type: 'json' } });
+                    config = module.default;
+                }
+                catch (error) {
+                    throw new Error(`Failed to import JSON from '${srcAttr}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                // Inline JSON mode: parse textContent
+                const jsonText = scriptElement.textContent?.trim();
+                if (!jsonText) {
+                    throw new Error('Script element must have either src attribute or JSON content');
+                }
+                try {
+                    config = JSON.parse(jsonText);
+                }
+                catch (error) {
+                    throw new Error(`Failed to parse JSON content: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Validate that config is an object or array
+            if (typeof config !== 'object' || config === null) {
+                throw new Error('Mount observer config must be an object or array');
+            }
+            // Store the parsed config on the script element's export property
+            scriptElement.export = config;
+            // Dispatch resolved event
+            const { ResolvedEvent } = await import('../Events.js');
+            scriptElement.dispatchEvent(new ResolvedEvent(config));
+        }
+        // Handle array of configs
+        if (Array.isArray(config)) {
+            // Mount each config in the array
+            for (const singleConfig of config) {
+                if (typeof singleConfig !== 'object' || singleConfig === null) {
+                    throw new Error('Each config in array must be an object');
+                }
+                await scriptElement.mount(singleConfig);
+            }
+        }
+        else {
+            // Single config object - mount it
+            await scriptElement.mount(config);
+        }
+    }
+}
+// Register built-in handler
+import { MountObserver } from '../MountObserver.js';
+MountObserver.define('builtIns.mountObserverScript', MountObserverScriptHandler);

package/handlers/MountObserverScript.ts

@@ -0,0 +1,89 @@
+import { EvtRt } from '../EvtRt.js';
+import { MountConfig, MountContext } from '../types/mount-observer/types.js';
+import '../ElementMountExtension.js';
+
+/**
+ * Handler for Mount Observer Script Elements (MOSEs).
+ * Processes script[type="mountobserver"] elements to declaratively configure mount observers.
+ * 
+ * Supports two modes:
+ * 1. External JSON: <script type="mountobserver" src="./config.json"></script>
+ * 2. Inline JSON: <script type="mountobserver">{ "matching": "div" }</script>
+ * 
+ * Supports multiple configs in one script element:
+ * - Single config: { "do": "builtIns.hoistTemplate" }
+ * - Multiple configs: [{ "do": "builtIns.hoistTemplate" }, { "do": "builtIns.HTMLInclude" }]
+ */
+export class MountObserverScriptHandler extends EvtRt {
+    // Static properties define default MountConfig constraints
+    static matching = 'script[type="mountobserver"]';
+    static whereInstanceOf = HTMLScriptElement;
+    
+    async mount(mountedElement: Element, MountConfig: MountConfig, context: MountContext): Promise<void> {
+        this.abort(); // Clean up event listeners (one-time operation)
+        
+        const scriptElement = mountedElement as HTMLScriptElement;
+        
+        let config = (scriptElement as any).export;
+        if (!config) {
+            // Check if script has src attribute
+            const srcAttr = scriptElement.getAttribute('src');
+            
+            if (srcAttr) {
+                // External JSON mode: import from src
+                const resolvedUrl = new URL(srcAttr, document.baseURI).href;
+                
+                try {
+                    const module = await import(resolvedUrl, { with: { type: 'json' } } as any);
+                    config = module.default;
+                } catch (error) {
+                    throw new Error(`Failed to import JSON from '${srcAttr}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            } else {
+                // Inline JSON mode: parse textContent
+                const jsonText = scriptElement.textContent?.trim();
+                
+                if (!jsonText) {
+                    throw new Error('Script element must have either src attribute or JSON content');
+                }
+                
+                try {
+                    config = JSON.parse(jsonText);
+                } catch (error) {
+                    throw new Error(`Failed to parse JSON content: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            
+            // Validate that config is an object or array
+            if (typeof config !== 'object' || config === null) {
+                throw new Error('Mount observer config must be an object or array');
+            }
+            
+            // Store the parsed config on the script element's export property
+            (scriptElement as any).export = config;
+            
+            // Dispatch resolved event
+            const { ResolvedEvent } = await import('../Events.js');
+            scriptElement.dispatchEvent(new ResolvedEvent(config));
+        }
+        
+        // Handle array of configs
+        if (Array.isArray(config)) {
+            // Mount each config in the array
+            for (const singleConfig of config) {
+                if (typeof singleConfig !== 'object' || singleConfig === null) {
+                    throw new Error('Each config in array must be an object');
+                }
+                await scriptElement.mount(singleConfig);
+            }
+        } else {
+            // Single config object - mount it
+            await scriptElement.mount(config);
+        }
+    }
+}
+
+// Register built-in handler
+import { MountObserver } from '../MountObserver.js';
+
+MountObserver.define('builtIns.mountObserverScript', MountObserverScriptHandler);

package/handlers/ScriptExport.js

@@ -0,0 +1,83 @@
+import { EvtRt } from '../EvtRt.js';
+/**
+ * Handler for exposing module exports from script elements via element.export.
+ *
+ * Solves two key problems:
+ *
+ * 1. ES Module Export Access:
+ *    - Use nomodule attribute to prevent browser from loading the module separately
+ *    - Handler imports it and exposes exports via element.export
+ *    - Avoids double-loading the module in memory
+ *    - Example: <script nomodule src="./config.js" id="cfg"></script>
+ *    - Access: document.getElementById('cfg').export.myValue
+ *
+ * 2. JSON/Data Import:
+ *    - Use type attribute for JSON and other data formats
+ *    - Browser ignores non-standard script types, so no double-loading issue
+ *    - Handler imports with appropriate assertion and exposes via element.export
+ *    - Example: <script src="./data.json" type="json" id="data"></script>
+ *    - Access: document.getElementById('data').export.default
+ *
+ * Supported type values:
+ * - type="json" - JSON data
+ * - type="application/json" - JSON with full MIME type
+ * - type="application/ld+json" - JSON-LD linked data
+ * - Any type containing "json" triggers JSON import assertion
+ */
+export class ScriptExportHandler extends EvtRt {
+    // Match script elements with src attribute
+    static matching = 'script[src]';
+    static whereInstanceOf = HTMLScriptElement;
+    async mount(mountedElement, MountConfig, context) {
+        this.abort(); // Clean up event listeners (one-time operation)
+        const scriptElement = mountedElement;
+        // Optimization 3: Skip if already processed (export property exists)
+        if (scriptElement.export !== undefined) {
+            console.log('ScriptExport: Skipping already processed script element');
+            return;
+        }
+        // Skip if this is a module script (browser handles these)
+        const typeAttr = scriptElement.getAttribute('type');
+        if (typeAttr === 'module') {
+            return;
+        }
+        // Only process if:
+        // 1. Has nomodule attribute (for ES modules), OR
+        // 2. Has type attribute containing "json" (for JSON data)
+        const hasNoModule = scriptElement.hasAttribute('nomodule');
+        const isJsonType = typeAttr && typeAttr.toLowerCase().includes('json');
+        if (!hasNoModule && !isJsonType) {
+            return;
+        }
+        // Read src attribute
+        const srcAttr = scriptElement.getAttribute('src');
+        if (!srcAttr) {
+            throw new Error('Script element must have a src attribute');
+        }
+        // Resolve the src relative to the document's base URL
+        const resolvedUrl = new URL(srcAttr, document.baseURI).href;
+        // Determine import assertion type
+        const importType = isJsonType ? 'json' : null;
+        // Perform import
+        let module;
+        try {
+            if (importType) {
+                module = await import(resolvedUrl, { with: { type: importType } });
+            }
+            else {
+                module = await import(resolvedUrl);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to import module from '${srcAttr}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Store result on element
+        scriptElement.export = module;
+        // Dispatch resolved event
+        const { ResolvedEvent } = await import('../Events.js');
+        scriptElement.dispatchEvent(new ResolvedEvent(module));
+    }
+}
+// Register built-in handler
+import { MountObserver } from '../MountObserver.js';
+MountObserver.define('builtIns.scriptExport', ScriptExportHandler);

package/handlers/ScriptExport.ts

@@ -0,0 +1,97 @@
+import { EvtRt } from '../EvtRt.js';
+import { MountConfig, MountContext } from '../types/mount-observer/types.js';
+
+/**
+ * Handler for exposing module exports from script elements via element.export.
+ * 
+ * Solves two key problems:
+ * 
+ * 1. ES Module Export Access:
+ *    - Use nomodule attribute to prevent browser from loading the module separately
+ *    - Handler imports it and exposes exports via element.export
+ *    - Avoids double-loading the module in memory
+ *    - Example: <script nomodule src="./config.js" id="cfg"></script>
+ *    - Access: document.getElementById('cfg').export.myValue
+ * 
+ * 2. JSON/Data Import:
+ *    - Use type attribute for JSON and other data formats
+ *    - Browser ignores non-standard script types, so no double-loading issue
+ *    - Handler imports with appropriate assertion and exposes via element.export
+ *    - Example: <script src="./data.json" type="json" id="data"></script>
+ *    - Access: document.getElementById('data').export.default
+ * 
+ * Supported type values:
+ * - type="json" - JSON data
+ * - type="application/json" - JSON with full MIME type
+ * - type="application/ld+json" - JSON-LD linked data
+ * - Any type containing "json" triggers JSON import assertion
+ */
+export class ScriptExportHandler extends EvtRt {
+    // Match script elements with src attribute
+    static matching = 'script[src]';
+    static whereInstanceOf = HTMLScriptElement;
+    
+    async mount(mountedElement: Element, MountConfig: MountConfig, context: MountContext): Promise<void> {
+        this.abort(); // Clean up event listeners (one-time operation)
+        
+        const scriptElement = mountedElement as HTMLScriptElement;
+        
+        // Optimization 3: Skip if already processed (export property exists)
+        if ((scriptElement as any).export !== undefined) {
+            console.log('ScriptExport: Skipping already processed script element');
+            return;
+        }
+        
+        // Skip if this is a module script (browser handles these)
+        const typeAttr = scriptElement.getAttribute('type');
+        if (typeAttr === 'module') {
+            return;
+        }
+        
+        // Only process if:
+        // 1. Has nomodule attribute (for ES modules), OR
+        // 2. Has type attribute containing "json" (for JSON data)
+        const hasNoModule = scriptElement.hasAttribute('nomodule');
+        const isJsonType = typeAttr && typeAttr.toLowerCase().includes('json');
+        
+        if (!hasNoModule && !isJsonType) {
+            return;
+        }
+        
+        // Read src attribute
+        const srcAttr = scriptElement.getAttribute('src');
+        if (!srcAttr) {
+            throw new Error('Script element must have a src attribute');
+        }
+        
+        // Resolve the src relative to the document's base URL
+        const resolvedUrl = new URL(srcAttr, document.baseURI).href;
+        
+        // Determine import assertion type
+        const importType = isJsonType ? 'json' : null;
+        
+        // Perform import
+        let module;
+        try {
+            if (importType) {
+                module = await import(resolvedUrl, { with: { type: importType } } as any);
+            } else {
+                module = await import(resolvedUrl);
+            }
+        } catch (error) {
+            throw new Error(`Failed to import module from '${srcAttr}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+        
+        // Store result on element
+        (scriptElement as any).export = module;
+        
+        // Dispatch resolved event
+        const { ResolvedEvent } = await import('../Events.js');
+        scriptElement.dispatchEvent(new ResolvedEvent(module));
+    }
+}
+
+// Register built-in handler
+import { MountObserver } from '../MountObserver.js';
+
+MountObserver.define('builtIns.scriptExport', ScriptExportHandler);

package/handlers/SharedMutationObserver.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Manages shared MutationObserver instances for multiple MountObserver instances
+ * observing the same root node. This reduces overhead when multiple observers
+ * are watching the same DOM fragment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSharedObserver = registerSharedObserver;
+exports.unregisterSharedObserver = unregisterSharedObserver;
+/**
+ * Global registry of shared observers, keyed by root node
+ */
+var sharedObservers = new WeakMap();
+/**
+ * Registers a callback with the shared MutationObserver for the given root node.
+ * Creates a new shared observer if one doesn't exist for this root.
+ */
+function registerSharedObserver(rootNode, callback, config) {
+    var sharedData = sharedObservers.get(rootNode);
+    if (!sharedData) {
+        // Create shared data structure first
+        sharedData = {
+            observer: null, // Will be set immediately below
+            callbacks: new Set(),
+            config: config
+        };
+        // Create new shared observer for this root node
+        var observer = new MutationObserver(function (mutations) {
+            // Distribute mutations to all registered callbacks
+            var callbacks = sharedData.callbacks;
+            for (var _i = 0, callbacks_1 = callbacks; _i < callbacks_1.length; _i++) {
+                var cb = callbacks_1[_i];
+                cb(mutations);
+            }
+        });
+        sharedData.observer = observer;
+        sharedObservers.set(rootNode, sharedData);
+        // Start observing after everything is set up
+        observer.observe(rootNode, config);
+    }
+    else {
+        // Verify config matches (for safety)
+        // In practice, all MountObservers should use the same config
+        if (!configsMatch(sharedData.config, config)) {
+            console.warn('MutationObserver config mismatch detected. Using existing config.');
+        }
+    }
+    // Register the callback
+    sharedData.callbacks.add(callback);
+}
+/**
+ * Unregisters a callback from the shared MutationObserver.
+ * If this was the last callback, disconnects and removes the shared observer.
+ */
+function unregisterSharedObserver(rootNode, callback) {
+    var sharedData = sharedObservers.get(rootNode);
+    if (!sharedData) {
+        return;
+    }
+    // Remove the callback
+    sharedData.callbacks.delete(callback);
+    // If no more callbacks, disconnect and cleanup
+    if (sharedData.callbacks.size === 0) {
+        sharedData.observer.disconnect();
+        sharedObservers.delete(rootNode);
+    }
+}
+/**
+ * Checks if two MutationObserverInit configs are equivalent
+ */
+function configsMatch(a, b) {
+    return a.childList === b.childList &&
+        a.subtree === b.subtree &&
+        a.attributes === b.attributes &&
+        a.attributeOldValue === b.attributeOldValue &&
+        a.characterData === b.characterData &&
+        a.characterDataOldValue === b.characterDataOldValue;
+}

package/handlers/arr.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arr = arr;
+/**
+ * Utility function to normalize a value to an array.
+ * - If undefined, returns empty array
+ * - If already an array, returns as-is
+ * - Otherwise, wraps the value in an array
+ *
+ * @param inp - Value to normalize to array
+ * @returns Array containing the value(s)
+ */
+function arr(inp) {
+    return inp === undefined ? []
+        : Array.isArray(inp) ? inp : [inp];
+}

package/handlers/connectionMonitor.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupConnectionMonitor = setupConnectionMonitor;
+var Events_js_1 = require("./Events.js");
+function setupConnectionMonitor(init, rootNodeRef, mountedElements, modules, observer, processNode) {
+    var whereConnectionHas = init.whereConnectionHas;
+    if (!whereConnectionHas) {
+        throw new Error('whereConnectionHas is required');
+    }
+    // Get connection object with vendor prefixes
+    var nav = navigator;
+    var connection = nav.connection || nav.mozConnection || nav.webkitConnection;
+    // If Network Information API is not supported, warn and pass the condition
+    if (!connection) {
+        console.warn('Network Information API is not supported in this browser. whereConnectionHas condition will be ignored.');
+        return {
+            conditionMatches: true,
+            cleanup: function () { }
+        };
+    }
+    // Check initial condition
+    var conditionMatches = evaluateConnectionCondition(connection, whereConnectionHas);
+    // Set up change listener
+    var changeHandler = function () {
+        var previousMatches = conditionMatches;
+        conditionMatches = evaluateConnectionCondition(connection, whereConnectionHas);
+        if (conditionMatches && !previousMatches) {
+            // Connection now matches - process elements
+            handleConditionMatch();
+        }
+        else if (!conditionMatches && previousMatches) {
+            // Connection no longer matches - dismount all elements
+            handleConditionUnmatch();
+        }
+    };
+    function handleConditionMatch() {
+        // Process all elements in the observed node
+        var rootNode = rootNodeRef.deref();
+        if (rootNode) {
+            processNode(rootNode);
+        }
+    }
+    function handleConditionUnmatch() {
+        // Dismount all currently mounted elements
+        var rootNode = rootNodeRef.deref();
+        if (!rootNode) {
+            return;
+        }
+        var context = {
+            modules: modules,
+            observer: observer,
+            rootNode: rootNode,
+            mountConfig: init
+        };
+        // Get all mounted elements from the WeakDual setWeak
+        var mountedElementsList = [];
+        for (var _i = 0, _a = mountedElements.setWeak; _i < _a.length; _i++) {
+            var ref = _a[_i];
+            var element = ref.deref();
+            if (element) {
+                mountedElementsList.push(element);
+            }
+        }
+        // Dismount each element
+        for (var _b = 0, mountedElementsList_1 = mountedElementsList; _b < mountedElementsList_1.length; _b++) {
+            var element = mountedElementsList_1[_b];
+            // Remove from both structures
+            mountedElements.weakSet.delete(element);
+            for (var _c = 0, _d = mountedElements.setWeak; _c < _d.length; _c++) {
+                var ref = _d[_c];
+                if (ref.deref() === element) {
+                    mountedElements.setWeak.delete(ref);
+                    break;
+                }
+            }
+            // Dispatch dismount event with reason
+            observer.dispatchEvent(new Events_js_1.DismountEvent(element, 'connection-failed', init));
+        }
+    }
+    // Listen for connection changes
+    connection.addEventListener('change', changeHandler);
+    return {
+        conditionMatches: conditionMatches,
+        cleanup: function () {
+            connection.removeEventListener('change', changeHandler);
+        }
+    };
+}
+/**
+ * Evaluate if the current connection meets the specified conditions
+ */
+function evaluateConnectionCondition(connection, condition) {
+    // Check effectiveType (e.g., 'slow-2g', '2g', '3g', '4g')
+    if (condition.effectiveTypeIn && condition.effectiveTypeIn.length > 0) {
+        var effectiveType = connection.effectiveType;
+        if (!effectiveType || !condition.effectiveTypeIn.includes(effectiveType)) {
+            return false;
+        }
+    }
+    // Check downlink (bandwidth in Mbps)
+    if (condition.downlinkMin !== undefined) {
+        var downlink = connection.downlink;
+        if (downlink === undefined || downlink < condition.downlinkMin) {
+            return false;
+        }
+    }
+    if (condition.downlinkMax !== undefined) {
+        var downlink = connection.downlink;
+        if (downlink === undefined || downlink > condition.downlinkMax) {
+            return false;
+        }
+    }
+    // Check RTT (round-trip time in ms)
+    if (condition.rttMax !== undefined) {
+        var rtt = connection.rtt;
+        if (rtt === undefined || rtt > condition.rttMax) {
+            return false;
+        }
+    }
+    // All conditions passed
+    return true;
+}

package/handlers/elementIntersection.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupElementIntersection = setupElementIntersection;
+exports.isElementIntersecting = isElementIntersecting;
+var Events_js_1 = require("./Events.js");
+function setupElementIntersection(init, rootNodeRef, mountedElements, modules, observer, matchesSelector, handleMatch) {
+    var whereElementIntersectsWith = init.whereElementIntersectsWith;
+    if (!whereElementIntersectsWith) {
+        throw new Error('whereElementIntersectsWith is required');
+    }
+    // Track which elements are currently intersecting
+    var intersectingElements = new WeakSet();
+    // Create IntersectionObserver with the provided options
+    var intersectionObserver = new IntersectionObserver(function (entries) {
+        for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
+            var entry = entries_1[_i];
+            var element = entry.target;
+            if (entry.isIntersecting) {
+                // Element is now intersecting
+                intersectingElements.add(element);
+                // Check if element matches all other conditions and mount if so
+                if (matchesSelector(element)) {
+                    handleMatch(element);
+                }
+            }
+            else {
+                // Element is no longer intersecting
+                intersectingElements.delete(element);
+                // Dismount if it was mounted
+                if (mountedElements.weakSet.has(element)) {
+                    dismountElement(element);
+                }
+            }
+        }
+    }, whereElementIntersectsWith);
+    function dismountElement(element) {
+        // Remove from mounted elements
+        mountedElements.weakSet.delete(element);
+        for (var _i = 0, _a = mountedElements.setWeak; _i < _a.length; _i++) {
+            var ref = _a[_i];
+            if (ref.deref() === element) {
+                mountedElements.setWeak.delete(ref);
+                break;
+            }
+        }
+        // Dispatch dismount event
+        observer.dispatchEvent(new Events_js_1.DismountEvent(element, 'intersection-failed', init));
+    }
+    function observeElement(element) {
+        intersectionObserver.observe(element);
+    }
+    return {
+        intersectionObserver: intersectionObserver,
+        observeElement: observeElement,
+        cleanup: function () {
+            intersectionObserver.disconnect();
+        }
+    };
+}
+/**
+ * Check if an element is currently intersecting
+ * This is called from #matchesSelector to determine if intersection condition is met
+ */
+function isElementIntersecting(element, intersectionObserver) {
+    // If no intersection observer is set up, consider all elements as intersecting
+    if (!intersectionObserver) {
+        return true;
+    }
+    // When intersection observer is active, we can't synchronously determine intersection state
+    // The element will be observed and the callback will handle mounting when it intersects
+    // Return false here to prevent immediate mounting
+    return false;
+}