mount-observer 0.1.18 → 0.1.20

package/README.md

@@ -568,6 +568,104 @@ The handler automatically hoists templates that:
 
 </details>
 
+## Element Mount Configuration (EMC) Scripts
+
+The `builtIns.emcScript` handler provides declarative element enhancement using `<script type="emc">` elements. EMC scripts combine mount observation with the [assign-gingerly](https://github.com/bahrus/assign-gingerly) enhancement system to apply behaviors, properties, and classes to elements as they mount.
+
+**Why use EMC scripts?**
+
+- Declaratively enhance elements without writing JavaScript
+- Lazy load enhancement classes only when needed
+- Automatically register and spawn enhancements
+- Works with scoped custom element registries
+- Supports attribute-based element matching
+- Reuses enhancement definitions across multiple elements
+
+**Basic usage:**
+
+```html
+<!-- Define enhancement configuration -->
+<script type="emc">
+{
+    "matching": ".interactive",
+    "enhConfig": {
+        "spawn": "./my-enhancement.js",
+        "enhKey": "myEnhancement"
+    }
+}
+</script>
+
+<!-- Elements matching the selector get enhanced -->
+<div class="interactive">This will be enhanced</div>
+<div class="interactive">This too</div>
+```
+
+**External JSON configuration:**
+
+```html
+<!-- Load configuration from external file -->
+<script type="emc" src="./enh-config.json"></script>
+```
+
+**With attribute matching:**
+
+```html
+<script type="emc">
+{
+    "matching": "button",
+    "enhConfig": {
+        "spawn": "./button-enhancement.js",
+        "enhKey": "fancyButton",
+        "withAttrs": {
+            "base": "variant"
+        }
+    }
+}
+</script>
+
+<!-- Only buttons with variant="primary" get enhanced -->
+<button variant="primary">Enhanced</button>
+<button>Not enhanced</button>
+```
+
+**How it works:**
+
+1. EMC script is parsed (inline JSON or external via `src`)
+2. Configuration is stored on `scriptElement.export`
+3. `resolved` event is dispatched
+4. Script ID is auto-generated as `${parentElement.localName}.${enhKey}` if not specified
+5. MountObserver watches for elements matching the configuration
+6. When element mounts:
+   - Checks if already enhanced (via `element.enh[enhKey]`)
+   - Registers enhancement class if not already registered
+   - Spawns enhancement instance via `element.enh.get(enhancementConfig)`
+
+**Enhancement class example:**
+
+```javascript
+// my-enhancement.js
+export default class MyEnhancement {
+    constructor(element, ctx, initVals) {
+        this.element = element;
+        // Apply enhancement
+        this.element.classList.add('enhanced');
+    }
+    
+    dispose() {
+        // Cleanup
+        this.element.classList.remove('enhanced');
+    }
+}
+```
+
+**Requirements:**
+
+- Must import `ElementMountExtension.js` to enable `element.enh` property
+- Must import `assign-gingerly/object-extension.js` for enhancement registry
+- Enhancement classes should be constructors that accept `(element, ctx, initVals)`
+
+[Implemented as EMCScript requirement](requirements/Done/EMCScript.md)
+
 ## Intra-Document HTML Includes with HTMLInclude
 
 The `builtIns.HTMLInclude` handler enables declarative HTML fragment reuse within a document using `<template src="#id">` syntax. Think of it as "constants for HTML" - define content once with an ID, then reference it multiple times throughout your document.

package/handlers/DefineCustomElement.js

@@ -1,4 +1,53 @@
 import { EvtRt } from '../EvtRt.js';
+/**
+ * Find a suitable HTMLElement class from a module.
+ * Checks the default export first, then searches all exports.
+ * @param module - The imported module
+ * @returns The HTMLElement class constructor
+ * @throws Error if no suitable class is found or multiple classes are found
+ */
+function findSuitableClass(module) {
+    // Check default export first
+    const defaultExport = module.default;
+    if (defaultExport && extendsHTMLElement(defaultExport)) {
+        return defaultExport;
+    }
+    // Find all exports that extend HTMLElement
+    const htmlElementClasses = Object.values(module)
+        .filter(exp => typeof exp === 'function' && extendsHTMLElement(exp));
+    if (htmlElementClasses.length === 0) {
+        throw new Error('No suitable class found in module');
+    }
+    if (htmlElementClasses.length > 1) {
+        throw new Error('More than one class found in module');
+    }
+    return htmlElementClasses[0];
+}
+/**
+ * Check if a class extends HTMLElement.
+ * @param cls - The class to check
+ * @returns true if the class extends HTMLElement
+ */
+function extendsHTMLElement(cls) {
+    try {
+        // Must be a function
+        if (typeof cls !== 'function') {
+            return false;
+        }
+        // Handle direct HTMLElement export
+        if (cls === HTMLElement) {
+            return true;
+        }
+        // Check if it has a prototype and extends HTMLElement
+        if (cls.prototype && cls.prototype instanceof HTMLElement) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
 export class DefineCustomElementHandler extends EvtRt {
     mount(mountedElement, MountConfig, context) {
         this.abort();
@@ -12,8 +61,8 @@ export class DefineCustomElementHandler extends EvtRt {
         if (customElements.get(tagName)) {
             return;
         }
-        // Find suitable class
-        const ElementClass = this.findSuitableClass(module);
+        // Find suitable class using shared utility
+        const ElementClass = findSuitableClass(module);
         // Validate that ElementClass is a constructor
         if (typeof ElementClass !== 'function') {
             throw new Error(`Found class is not a constructor: ${typeof ElementClass}`);
@@ -35,43 +84,6 @@ export class DefineCustomElementHandler extends EvtRt {
     define(tagName, ElementClass, mountedElement) {
         customElements.define(tagName, ElementClass);
     }
-    findSuitableClass(module) {
-        // Check default export first
-        const defaultExport = module.default;
-        if (defaultExport && this.extendsHTMLElement(defaultExport)) {
-            return defaultExport;
-        }
-        // Find all exports that extend HTMLElement
-        const htmlElementClasses = Object.values(module)
-            .filter(exp => typeof exp === 'function' && this.extendsHTMLElement(exp));
-        if (htmlElementClasses.length === 0) {
-            throw new Error('No suitable class found in module');
-        }
-        if (htmlElementClasses.length > 1) {
-            throw new Error('More than one class found in module');
-        }
-        return htmlElementClasses[0];
-    }
-    extendsHTMLElement(cls) {
-        try {
-            // Must be a function
-            if (typeof cls !== 'function') {
-                return false;
-            }
-            // Handle direct HTMLElement export
-            if (cls === HTMLElement) {
-                return true;
-            }
-            // Check if it has a prototype and extends HTMLElement
-            if (cls.prototype && cls.prototype instanceof HTMLElement) {
-                return true;
-            }
-            return false;
-        }
-        catch {
-            return false;
-        }
-    }
 }
 /**
  * Handler for defining custom elements in scoped registries.

package/handlers/DefineCustomElement.ts

@@ -1,6 +1,61 @@
 import { EvtRt } from '../EvtRt.js';
 import { MountConfig, MountContext } from '../types/mount-observer/types.js';
 
+/**
+ * Find a suitable HTMLElement class from a module.
+ * Checks the default export first, then searches all exports.
+ * @param module - The imported module
+ * @returns The HTMLElement class constructor
+ * @throws Error if no suitable class is found or multiple classes are found
+ */
+function findSuitableClass(module: any): typeof HTMLElement {
+    // Check default export first
+    const defaultExport = module.default;
+    
+    if (defaultExport && extendsHTMLElement(defaultExport)) {
+        return defaultExport;
+    }
+    
+    // Find all exports that extend HTMLElement
+    const htmlElementClasses = Object.values(module)
+        .filter(exp => typeof exp === 'function' && extendsHTMLElement(exp));
+    
+    if (htmlElementClasses.length === 0) {
+        throw new Error('No suitable class found in module');
+    }
+    
+    if (htmlElementClasses.length > 1) {
+        throw new Error('More than one class found in module');
+    }
+    
+    return htmlElementClasses[0] as typeof HTMLElement;
+}
+
+/**
+ * Check if a class extends HTMLElement.
+ * @param cls - The class to check
+ * @returns true if the class extends HTMLElement
+ */
+function extendsHTMLElement(cls: any): boolean {
+    try {
+        // Must be a function
+        if (typeof cls !== 'function') {
+            return false;
+        }
+        // Handle direct HTMLElement export
+        if (cls === HTMLElement) {
+            return true;
+        }
+        // Check if it has a prototype and extends HTMLElement
+        if (cls.prototype && cls.prototype instanceof HTMLElement) {
+            return true;
+        }
+        return false;
+    } catch {
+        return false;
+    }
+}
+
 export class DefineCustomElementHandler extends EvtRt {
     mount(mountedElement: Element, MountConfig: MountConfig, context: MountContext): void {
         this.abort();
@@ -17,8 +72,8 @@ export class DefineCustomElementHandler extends EvtRt {
             return;
         }
         
-        // Find suitable class
-        const ElementClass = this.findSuitableClass(module);
+        // Find suitable class using shared utility
+        const ElementClass = findSuitableClass(module);
         
         // Validate that ElementClass is a constructor
         if (typeof ElementClass !== 'function') {
@@ -43,49 +98,6 @@ export class DefineCustomElementHandler extends EvtRt {
     protected define(tagName: string, ElementClass: CustomElementConstructor, mountedElement: Element): void {
         customElements.define(tagName, ElementClass);
     }
-    
-    private findSuitableClass(module: any): typeof HTMLElement {
-        // Check default export first
-        const defaultExport = module.default;
-        
-        if (defaultExport && this.extendsHTMLElement(defaultExport)) {
-            return defaultExport;
-        }
-        
-        // Find all exports that extend HTMLElement
-        const htmlElementClasses = Object.values(module)
-            .filter(exp => typeof exp === 'function' && this.extendsHTMLElement(exp));
-        
-        if (htmlElementClasses.length === 0) {
-            throw new Error('No suitable class found in module');
-        }
-        
-        if (htmlElementClasses.length > 1) {
-            throw new Error('More than one class found in module');
-        }
-        
-        return htmlElementClasses[0] as typeof HTMLElement;
-    }
-    
-    private extendsHTMLElement(cls: any): boolean {
-        try {
-            // Must be a function
-            if (typeof cls !== 'function') {
-                return false;
-            }
-            // Handle direct HTMLElement export
-            if (cls === HTMLElement) {
-                return true;
-            }
-            // Check if it has a prototype and extends HTMLElement
-            if (cls.prototype && cls.prototype instanceof HTMLElement) {
-                return true;
-            }
-            return false;
-        } catch {
-            return false;
-        }
-    }
 }
 
 /**

package/handlers/EMCScript.js

@@ -0,0 +1,178 @@
+import { EvtRt } from '../EvtRt.js';
+import { MountObserver } from '../MountObserver.js';
+import '../ElementMountExtension.js';
+import 'assign-gingerly/object-extension.js';
+/**
+ * Handler for EMC (Element Mount Configuration) Script Elements.
+ * Processes script[type="emc"] elements to declaratively configure element enhancements.
+ *
+ * Supports two modes:
+ * 1. External JSON: <script type="emc" src="./config.json"></script>
+ * 2. Inline JSON: <script type="emc">{ "matching": "div", "enhConfig": {...} }</script>
+ *
+ * Unlike MountObserverScript, EMC scripts only support single config objects (not arrays).
+ */
+export class EMCScriptHandler extends EvtRt {
+    // Static properties define default MountConfig constraints
+    static matching = 'script[type="emc"]';
+    static whereInstanceOf = HTMLScriptElement;
+    async mount(mountedElement, MountConfig, context) {
+        this.abort(); // Clean up event listeners (one-time operation)
+        const scriptElement = mountedElement;
+        let emcConfig = scriptElement.export;
+        if (!emcConfig) {
+            // Check if script has src attribute
+            const srcAttr = scriptElement.getAttribute('src');
+            if (srcAttr) {
+                // External JSON mode: import from src
+                try {
+                    const module = await import(srcAttr, { with: { type: 'json' } });
+                    emcConfig = 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 {
+                    emcConfig = 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 (not array)
+            if (typeof emcConfig !== 'object' || emcConfig === null || Array.isArray(emcConfig)) {
+                throw new Error('EMC config must be an object (not an array)');
+            }
+            // Store the parsed config on the script element's export property
+            scriptElement.export = emcConfig;
+            // Dispatch resolved event
+            const { ResolvedEvent } = await import('../Events.js');
+            scriptElement.dispatchEvent(new ResolvedEvent(emcConfig));
+        }
+        // Validate EMC config has required properties
+        if (!emcConfig.enhConfig) {
+            throw new Error('EMC config must have enhConfig property');
+        }
+        const enhKey = emcConfig.enhConfig.enhKey;
+        if (!enhKey) {
+            throw new Error('EMC config enhConfig must have enhKey property');
+        }
+        // Set ID if not specified
+        if (!scriptElement.id && scriptElement.parentElement) {
+            scriptElement.id = `${scriptElement.parentElement.localName}.${enhKey}`;
+        }
+        // Construct MountConfig from EMC config
+        const mountConfig = await this.buildMountConfig(emcConfig);
+        // Create a MountObserver to watch for elements matching the config
+        const observer = new MountObserver(mountConfig);
+        // Store observer reference for cleanup
+        scriptElement.emcObserver = observer;
+        // Observe from the script element's parent or root node
+        const observeTarget = scriptElement.parentElement || scriptElement.getRootNode();
+        await observer.observe(observeTarget);
+    }
+    /**
+     * Build a MountConfig from an EMC config.
+     * Combines the matching selector with withAttrs if present.
+     */
+    async buildMountConfig(emcConfig) {
+        const { enhConfig, ...mountConfigBase } = emcConfig;
+        let matching = mountConfigBase.matching || '';
+        // If withAttrs is defined, use buildCSSQuery to combine with matching
+        if (enhConfig.withAttrs) {
+            const { buildCSSQuery } = await import('assign-gingerly/buildCSSQuery.js');
+            // Cast to any to avoid type mismatch with spawn property
+            const attrQuery = buildCSSQuery(enhConfig);
+            // Combine matching with attribute query
+            if (matching) {
+                matching = `${matching}${attrQuery}`;
+            }
+            else {
+                matching = attrQuery;
+            }
+        }
+        // Create the mount config with a custom handler
+        const mountConfig = {
+            ...mountConfigBase,
+            matching,
+            do: (mountedElement) => {
+                return this.handleMount(mountedElement, emcConfig);
+            }
+        };
+        return mountConfig;
+    }
+    /**
+     * Handle when an element mounts that matches the EMC config.
+     */
+    async handleMount(mountedElement, emcConfig) {
+        const enhKey = emcConfig.enhConfig.enhKey;
+        // Step 1: Check if element already has this enhancement
+        const enh = mountedElement.enh;
+        if (enh && enh[enhKey]) {
+            // Already enhanced, do nothing
+            return;
+        }
+        // Step 2: Get enhancement registry from the element's custom element registry
+        const customElementRegistry = mountedElement.customElementRegistry || customElements;
+        const enhancementRegistry = customElementRegistry.enhancementRegistry;
+        if (!enhancementRegistry) {
+            throw new Error('Enhancement registry not found on custom element registry');
+        }
+        // Check if enhancement is already registered using findByEnhKey method
+        let enhancementConfig = enhancementRegistry.findByEnhKey(enhKey);
+        // Step 3: If not registered, register it
+        if (!enhancementConfig) {
+            enhancementConfig = await this.registerEnhancement(emcConfig, enhancementRegistry);
+        }
+        // Step 4: Spawn enhancement instance
+        if (!enh) {
+            throw new Error('Element does not have enh property. Make sure ElementMountExtension is loaded.');
+        }
+        await enh.get(enhancementConfig);
+    }
+    /**
+     * Register an enhancement in the enhancement registry.
+     */
+    async registerEnhancement(emcConfig, enhancementRegistry) {
+        const { enhConfig } = emcConfig;
+        const { spawn } = enhConfig;
+        if (!spawn) {
+            throw new Error('EMC enhConfig must have spawn property');
+        }
+        // Step 3.1: Import the module
+        const module = await import(spawn);
+        // Get the enhancement class - it should be the default export or any exported class
+        let ElementClass = module.default;
+        // If no default export, try to find a suitable class
+        if (!ElementClass) {
+            // Look for any exported constructor function
+            for (const key of Object.keys(module)) {
+                if (typeof module[key] === 'function') {
+                    ElementClass = module[key];
+                    break;
+                }
+            }
+        }
+        if (!ElementClass) {
+            throw new Error(`No suitable class found in module ${spawn}`);
+        }
+        // Step 3.2: Construct enhancement config
+        const enhancementConfig = {
+            ...enhConfig,
+            spawn: ElementClass
+        };
+        // Step 3.3: Register in enhancement registry
+        enhancementRegistry.push(enhancementConfig);
+        return enhancementConfig;
+    }
+}
+// Register built-in handler
+export const emc = 'builtIns.emcScript';
+MountObserver.define(emc, EMCScriptHandler);