mount-observer 0.0.7 → 0.0.9

package/MountObserver.js

@@ -3,13 +3,14 @@ const mutationObserverLookup = new WeakMap();
 const refCount = new WeakMap();
 export class MountObserver extends EventTarget {
     #mountInit;
-    #rootMutObs;
+    //#rootMutObs: RootMutObs | undefined;
     #abortController;
     #mounted;
     #mountedList;
     #disconnected;
     //#unmounted: WeakSet<Element>;
     #isComplex;
+    #observe;
     constructor(init) {
         super();
         const { on, whereElementIntersectsWith, whereMediaMatches } = init;
@@ -28,26 +29,107 @@ export class MountObserver extends EventTarget {
         //this.#unmounted = new WeakSet();
     }
     #calculatedSelector;
-    get #selector() {
+    #fullListOfAttrs;
+    //get #attrVals
+    async #selector() {
         if (this.#calculatedSelector !== undefined)
             return this.#calculatedSelector;
         const { on, whereAttr } = this.#mountInit;
-        const base = on || '*';
+        const withoutAttrs = on || '*';
         if (whereAttr === undefined)
-            return base;
-        const { withFirstName, andQualifiers, withStemsIn } = whereAttr;
-        const matches = [];
-        const prefixLessMatches = andQualifiers === undefined ? [withFirstName]
-            : andQualifiers.map(x => `${withFirstName}-${x}`);
-        const stems = withStemsIn || ['data', 'enh', 'data-enh'];
-        for (const stem of stems) {
-            const prefix = typeof stem === 'string' ? stem : stem.stem;
-            for (const prefixLessMatch of prefixLessMatches) {
-                matches.push(`${prefix}-${prefixLessMatch}`);
+            return withoutAttrs;
+        const { getWhereAttrSelector } = await import('./getWhereAttrSelector.js');
+        const info = getWhereAttrSelector(whereAttr, withoutAttrs);
+        const { fullListOfAttrs, calculatedSelector } = info;
+        this.#fullListOfAttrs = fullListOfAttrs;
+        this.#calculatedSelector = calculatedSelector;
+        return this.#calculatedSelector;
+    }
+    async #birtualizeFragment(fragment, level) {
+        const bis = Array.from(fragment.querySelectorAll(biQry));
+        for (const bi of bis) {
+            await this.#birtalizeMatch(bi, level);
+        }
+    }
+    async #birtalizeMatch(el, level) {
+        const href = el.getAttribute('href');
+        el.removeAttribute('href');
+        const templID = href.substring(1);
+        const fragment = this.#observe?.deref();
+        if (fragment === undefined)
+            return;
+        const templ = this.#findByID(templID, fragment);
+        if (!(templ instanceof HTMLTemplateElement))
+            throw 404;
+        const clone = templ.content.cloneNode(true);
+        const slots = el.querySelectorAll(`[slot]`);
+        for (const slot of slots) {
+            const name = slot.getAttribute('slot');
+            const targets = Array.from(clone.querySelectorAll(`slot[name="${name}"]`));
+            for (const target of targets) {
+                const slotClone = slot.cloneNode(true);
+                target.after(slotClone);
+                target.remove();
             }
         }
-        this.#calculatedSelector = matches.join(',');
-        return this.#calculatedSelector;
+        this.#birtualizeFragment(clone, level + 1);
+        if (level === 0) {
+            const slotMap = el.getAttribute('slotmap');
+            let map = slotMap === null ? undefined : JSON.parse(slotMap);
+            const slots = Array.from(clone.querySelectorAll('[slot]'));
+            for (const slot of slots) {
+                if (map !== undefined) {
+                    const slotName = slot.slot;
+                    for (const key in map) {
+                        if (slot.matches(key)) {
+                            const targetAttSymbols = map[key];
+                            for (const sym of targetAttSymbols) {
+                                switch (sym) {
+                                    case '|':
+                                        slot.setAttribute('itemprop', slotName);
+                                        break;
+                                    case '$':
+                                        slot.setAttribute('itemscope', '');
+                                        slot.setAttribute('itemprop', slotName);
+                                        break;
+                                    case '@':
+                                        slot.setAttribute('name', slotName);
+                                        break;
+                                    case '.':
+                                        slot.classList.add(slotName);
+                                        break;
+                                    case '%':
+                                        slot.part.add(slotName);
+                                        break;
+                                }
+                            }
+                        }
+                    }
+                }
+                slot.removeAttribute('slot');
+            }
+            el.dispatchEvent(new LoadEvent(clone));
+            //console.log('dispatched')
+        }
+        el.before(clone);
+        el.remove();
+    }
+    #templLookUp = new Map();
+    #findByID(id, fragment) {
+        if (this.#templLookUp.has(id))
+            return this.#templLookUp.get(id);
+        let templ = fragment.getElementById(id);
+        if (templ === null) {
+            let rootToSearchOutwardFrom = ((fragment.isConnected ? fragment.getRootNode() : this.#mountInit.withTargetShadowRoot) || document);
+            templ = rootToSearchOutwardFrom.getElementById(id);
+            while (templ === null && rootToSearchOutwardFrom !== document) {
+                rootToSearchOutwardFrom = (rootToSearchOutwardFrom.host || rootToSearchOutwardFrom).getRootNode();
+                templ = rootToSearchOutwardFrom.getElementById(id);
+            }
+        }
+        if (templ !== null)
+            this.#templLookUp.set(id, templ);
+        return templ;
     }
     unobserve(within) {
         const nodeToMonitor = this.#isComplex ? (within instanceof ShadowRoot ? within : within.getRootNode()) : within;
@@ -75,6 +157,7 @@ export class MountObserver extends EventTarget {
         }
     }
     async observe(within) {
+        this.#observe = new WeakRef(within);
         const nodeToMonitor = this.#isComplex ? (within instanceof ShadowRoot ? within : within.getRootNode()) : within;
         if (!mutationObserverLookup.has(nodeToMonitor)) {
             mutationObserverLookup.set(nodeToMonitor, new RootMutObs(nodeToMonitor));
@@ -90,8 +173,9 @@ export class MountObserver extends EventTarget {
             }
         }
         const rootMutObs = mutationObserverLookup.get(within);
-        const { attribMatches } = this.#mountInit;
-        rootMutObs.addEventListener('mutation-event', (e) => {
+        //const {whereAttr} = this.#mountInit;
+        const fullListOfAttrs = this.#fullListOfAttrs;
+        rootMutObs.addEventListener('mutation-event', async (e) => {
             //TODO:  disconnected
             if (this.#isComplex) {
                 this.#inspectWithin(within, false);
@@ -108,22 +192,11 @@ export class MountObserver extends EventTarget {
                 addedElements.forEach(x => elsToInspect.push(x));
                 if (type === 'attributes') {
                     const { target, attributeName, oldValue } = mutationRecord;
-                    if (target instanceof Element && attributeName !== null && attribMatches !== undefined && this.#mounted.has(target)) {
-                        let idx = 0;
-                        for (const attrMatch of attribMatches) {
-                            const { names } = attrMatch;
-                            if (names.includes(attributeName)) {
+                    if (target instanceof Element && attributeName !== null && this.#mounted.has(target)) {
+                        if (fullListOfAttrs !== undefined) {
+                            const idx = fullListOfAttrs.indexOf(attributeName);
+                            if (idx > -1) {
                                 const newValue = target.getAttribute(attributeName);
-                                // let parsedNewValue = undefined;
-                                // switch(type){
-                                //     case 'boolean':
-                                //         parsedNewValue = newValue === 'true' ? true : newValue === 'false' ? false : null;
-                                //         break;
-                                //     case 'date':
-                                //         parsedNewValue = newValue === null ? null : new Date(newValue);
-                                //         break;
-                                //     case ''
-                                // }
                                 const attrChangeInfo = {
                                     name: attributeName,
                                     oldValue,
@@ -132,7 +205,13 @@ export class MountObserver extends EventTarget {
                                 };
                                 this.dispatchEvent(new AttrChangeEvent(target, attrChangeInfo));
                             }
-                            idx++;
+                        }
+                        else {
+                            const { whereAttr } = this.#mountInit;
+                            if (whereAttr !== undefined) {
+                                const { doWhereAttr } = await import('./doWhereAttr.js');
+                                doWhereAttr(whereAttr, attributeName, target, oldValue, this);
+                            }
                         }
                     }
                     elsToInspect.push(target);
@@ -164,9 +243,10 @@ export class MountObserver extends EventTarget {
     }
     async #mount(matching, initializing) {
         //first unmount non matching
-        const alreadyMounted = this.#filterAndDismount();
+        const alreadyMounted = await this.#filterAndDismount();
         const mount = this.#mountInit.do?.mount;
-        const { import: imp, attribMatches } = this.#mountInit;
+        const { import: imp } = this.#mountInit;
+        const fullListOfAttrs = this.#fullListOfAttrs;
         for (const match of matching) {
             if (alreadyMounted.has(match))
                 continue;
@@ -197,27 +277,33 @@ export class MountObserver extends EventTarget {
                 });
             }
             this.dispatchEvent(new MountEvent(match, initializing));
-            if (attribMatches !== undefined) {
-                let idx = 0;
-                for (const attribMatch of attribMatches) {
-                    let newValue = null;
-                    const { names } = attribMatch;
-                    let nonNullName = names[0];
-                    for (const name of names) {
-                        const attrVal = match.getAttribute(name);
-                        if (attrVal !== null)
-                            nonNullName = name;
-                        newValue = newValue || attrVal;
+            if (fullListOfAttrs !== undefined) {
+                const { whereAttr } = this.#mountInit;
+                for (const name of fullListOfAttrs) {
+                    if (whereAttr !== undefined) {
+                        const { doWhereAttr } = await import('./doWhereAttr.js');
+                        doWhereAttr(whereAttr, name, match, null, this);
                     }
-                    const attribInfo = {
-                        oldValue: null,
-                        newValue,
-                        idx,
-                        name: nonNullName
-                    };
-                    this.dispatchEvent(new AttrChangeEvent(match, attribInfo));
-                    idx++;
                 }
+                // let idx = 0;
+                // for(const attribMatch of attribMatches){
+                //     let newValue = null;
+                //     const {names} = attribMatch;
+                //     let nonNullName = names[0];
+                //     for(const name of names){
+                //         const attrVal = match.getAttribute(name);
+                //         if(attrVal !== null) nonNullName = name;
+                //         newValue = newValue || attrVal;
+                //     }
+                //     const attribInfo: AttrChangeInfo = {
+                //         oldValue: null,
+                //         newValue,
+                //         idx,
+                //         name: nonNullName
+                //     };
+                //     this.dispatchEvent(new AttrChangeEvent(match, attribInfo));
+                //     idx++;
+                // }
             }
             this.#mountedList?.push(new WeakRef(match));
             //if(this.#unmounted.has(match)) this.#unmounted.delete(match);
@@ -232,12 +318,12 @@ export class MountObserver extends EventTarget {
             this.dispatchEvent(new DismountEvent(unmatch));
         }
     }
-    #filterAndDismount() {
+    async #filterAndDismount() {
         const returnSet = new Set();
         if (this.#mountedList !== undefined) {
             const previouslyMounted = this.#mountedList.map(x => x.deref());
             const { whereSatisfies, whereInstanceOf } = this.#mountInit;
-            const match = this.#selector;
+            const match = await this.#selector();
             const elsToUnMount = previouslyMounted.filter(x => {
                 if (x === undefined)
                     return false;
@@ -257,7 +343,7 @@ export class MountObserver extends EventTarget {
     }
     async #filterAndMount(els, checkMatch, initializing) {
         const { whereSatisfies, whereInstanceOf } = this.#mountInit;
-        const match = this.#selector;
+        const match = await this.#selector();
         const elsToMount = els.filter(x => {
             if (checkMatch) {
                 if (!x.matches(match))
@@ -273,14 +359,21 @@ export class MountObserver extends EventTarget {
             }
             return true;
         });
+        for (const elToMount of elsToMount) {
+            if (elToMount.matches(biQry)) {
+                await this.#birtalizeMatch(elToMount, 0);
+            }
+        }
         this.#mount(elsToMount, initializing);
     }
     async #inspectWithin(within, initializing) {
-        const els = Array.from(within.querySelectorAll(this.#selector));
+        await this.#birtualizeFragment(within, 0);
+        const els = Array.from(within.querySelectorAll(await this.#selector()));
         this.#filterAndMount(els, false, initializing);
     }
 }
 const refCountErr = 'mount-observer ref count mismatch';
+const biQry = 'b-i[href^="#"]:not([disabled])';
 // https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
 /**
  * The `mutation-event` event represents something that happened.
@@ -322,3 +415,12 @@ export class AttrChangeEvent extends Event {
         this.attrChangeInfo = attrChangeInfo;
     }
 }
+export class LoadEvent extends Event {
+    clone;
+    static eventName = 'load';
+    constructor(clone) {
+        super(LoadEvent.eventName);
+        this.clone = clone;
+    }
+}
+//const hasRootInDefault =  ['data', 'enh', 'data-enh']

package/README.md

@@ -3,6 +3,7 @@
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/mount-observer?style=for-the-badge)](https://bundlephobia.com/result?p=mount-observer)
 <img src="http://img.badgesize.io/https://cdn.jsdelivr.net/npm/mount-observer?compression=gzip">
 
+Note that much of what is described below has not yet been polyfilled.
 
 # The MountObserver api.
 
@@ -10,7 +11,7 @@ Author:  Bruce B. Anderson
 
 Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
 
-Last Update: 2024-2-11
+Last Update: 2024-2-17
 
 ## Benefits of this API
 
@@ -24,7 +25,7 @@ The underlying theme is this api is meant to make it easy for the developer to d
 
 There is quite a bit of functionality this proposal would open up, that is exceedingly difficult to polyfill reliably:  
 
-1.  It is unclear how to use mutation observers to observe changes to [custom state](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet).  The closest thing might be a solution like [this](https://davidwalsh.name/detect-node-insertion), but that falls short for elements that aren't visible, or during template instantiation.
+1.  It is unclear how to use mutation observers to observe changes to [custom state](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet).  The closest thing might be a solution like [this](https://davidwalsh.name/detect-node-insertion), but that falls short for elements that aren't visible, or during template instantiation, and requires carefully constructed "negating" queries if needing to know when the css selector is no longer matching.
 
 2.  For simple css matches, like "my-element", or "[name='hello']" it is enough to use a mutation observer, and only observe the elements within the specified DOM region (more on that below).  But as CSS has evolved, it is quite easy to think of numerous css selectors that would require us to expand our mutation observer to need to scan the entire Shadow DOM realm, or the entire DOM tree outside any Shadow DOM, for any and all mutations (including attribute changes), and re-evaluate every single element within the specified DOM region for new matches or old matches that no longer match.  Things like child selectors, :has, and so on. All this is done, miraculously, by the browser in a performant way.  Reproducing this in userland using JavaScript alone, matching the same performance seems impossible.
 
@@ -38,7 +39,7 @@ The amount of code necessary to accomplish these common tasks designed to improv
     1.  Making lazy loading of resource dependencies easy, to the benefit of users with expensive networks.
     2.  Supporting "binding from a distance" that can set property values of elements in bulk as the HTML streams in.  For example, say a web page is streaming in HTML with thousands of input elements (say a long tax form).  We want to have some indication in the head tag of the HTML (for example) to make all the input elements read only as they stream through the page. With css, we could do similar things, for example set the background to red of all input elements. Why can't we do something similar with setting properties like readOnly, disabled, etc?  With this api, giving developers the "keys" to css filtering, so they can "mount a campaign" to apply common settings on them all feels like something that almost every web developer has mentally screamed to themselves "why can't I do that?", doesn't it? 
     3.  Supporting "progressive enhancement" more effectively.
-2.  Potentially by allowing the platform to do more work in the low-level (c/c++/rust?) code, without as much context switching into the JavaScript memory space, which may reduce cpu cycles as well.  This is done by passing into the API substantial number of conditions, which can all be evaluated at a lower level, before surfacing up the developer "found one!".
+2.  Potentially by allowing the platform to do more work in the low-level (c/c++/rust?) code, without as much context switching into the JavaScript memory space, which may reduce cpu cycles as well.  This is done by passing into the API substantial number of conditions, which can all be evaluated at a lower level, before the api needs to surface up to the developer "found one!".
 3.  As discussed earlier, to do the job right, polyfills really need to reexamine **all** the elements within the observed node for matches **anytime any element within the Shadow Root so much as sneezes (has attribute modified, changes custom state, etc)**, due to modern selectors such as the :has selector.  Surely, the platform has found ways to do this more efficiently?  
 
 The extra flexibility this new primitive would provide could be quite useful to things other than lazy loading of custom elements, such as implementing [custom enhancements](https://github.com/WICG/webcomponents/issues/1000) as well as [binding from a distance](https://github.com/WICG/webcomponents/issues/1035#issuecomment-1806393525) in userland.
@@ -100,6 +101,8 @@ const observer = new MountObserver({
 })
 ```
 
+... would work.
+
 This would allow developers to create "stylesheet" like capabilities.
 
 
@@ -150,7 +153,9 @@ const observer = new MountObserver({
 })
 ```
 
-Callbacks like we see above are useful for tight coupling, and probably are unmatched in terms of performance.  However, since these rules may be of interest to multiple parties, it is useful to also provide the ability for multiple parties to subscribe to these css rules.  This can be done via:
+Callbacks like we see above are useful for tight coupling, and probably are unmatched in terms of performance.  The expression that the "do" field points to could also be a (stateful) user defined class instance.  
+
+However, since these rules may be of interest to multiple parties, it is useful to also provide the ability for multiple parties to subscribe to these css rules.  This can be done via:
 
 ## Subscribing
 
@@ -206,7 +211,7 @@ Being that for both custom elements, as well as (hopefully) [custom enhancements
 
 We want to be alerted by the discovery of elements adorned by these attributes, but then continue to be alerted to changes of their values, and we can't enumerate which values we are interested in, so we must subscribe to all values as they change.
 
-### Scenario 1 -- Custom Element integration with ObserveObservableAttributes API [WIP]
+### Scenario 1 -- Custom Element integration with ObserveObservedAttributes API [WIP]
 
 Example:
 
@@ -247,6 +252,8 @@ To make this discussion concrete, let's suppose the "canonical" names of those a
       my-enhancement=greetings 
       my-enhancement-first-aspect=hello 
       my-enhancement-second-aspect=goodbye
+      my-enhancement-first-aspect-wow-this-is-deep
+      my-enhancement-first-aspect-have-you-considered-using-json-for-this=just-saying
    ></section>
 </div>
 ```
@@ -263,17 +270,19 @@ We want to also support:
       data-my-enhancement=greetings 
       data-my-enhancement-first-aspect=hello 
       data-my-enhancement-second-aspect=goodbye
+      data-my-enhancement-first-aspect-wow-this-is-deep
+      data-my-enhancement-first-aspect-have-you-considered-using-json-for-this=just-saying
    ></section>
 </div>
 ```
 
 Based on the current unspoken rules, no one will raise an eyebrow with these attributes, because the platform has indicated it will generally avoid dashes in attributes (with an exception or two that will only happen in a blue moon, like aria-*).
 
-But now when we consider applying this enhancement to custom elements, we have a new risk.  What's to prevent the custom element from having an attribute named my-enhancement-first-aspect?  (Okay, with this particular example, the names are so long and generic it's unlikely, but who would ever use such a long, generic name in practice?)
+But now when we consider applying this enhancement to custom elements, we have a new risk.  What's to prevent the custom element from having an attribute named my-enhancement?
 
-So let's say we want to insist that on custom elements, we must have the dat- prefix?
+So let's say we want to insist that on custom elements, we must have the data- prefix?
 
-And we want to support an alternative prefix to data, say enh-*, endorsed by [this proposal](https://github.com/WICG/webcomponents/issues/1000).
+And we want to support an alternative, more semantic sounding prefix to data, say enh-*, endorsed by [this proposal](https://github.com/WICG/webcomponents/issues/1000).
 
 Here's what the api provides:
 
@@ -291,18 +300,20 @@ const mo = new MountObserver({
          'enh-my-enhancement',
          'enh-my-enhancement-first-aspect', 
          'enh-my-enhancement-second-aspect',
+         //...some ten more combinations not listed
          {
             name: 'my-enhancement',
             builtIn: true
          },
          {
-            name: 'my-enhancement-first-attr',
+            name: 'my-enhancement-first-aspect',
             builtIn: true
          },
          {
             name: 'my-enhancement-second-aspect',
             builtIn: true
-         }
+         },
+         ...
       ]
       
    }
@@ -316,30 +327,33 @@ import {MountObserver} from '../MountObserver.js';
 const mo = new MountObserver({
    on: '*',
    whereAttr:{
-      withFirstName: 'my-enhancement',
-      andQualifiers: ['first-attr', 'second-attr', ''],
-      withStemsIn: ['data', 'enh', 'data-enh'],
+      hasRootIn: ['data', 'enh', 'data-enh'],
+      hasBase: 'my-enhancement',
+      hasBranchIn: ['first-aspect', 'second-aspect', ''],
+      hasLeafIn: {
+         'first-aspect': ['wow-this-is-deep', 'have-you-considered-using-json-for-this'],
+      }
    }
 });
 ```
 
-MountObserver supports both approaches
+MountObserver provides a breakdown of the matching attribute when encountered:
 
 ```html
 <div id=div>
-   <section class=hello my-enhancement-first-attr="hello"></section>
+   <section class=hello my-enhancement-first-aspect-wow-this-is-deep="hello"></section>
 </div>
 <script type=module>
    import {MountObserver} from '../MountObserver.js';
    const mo = new MountObserver({
       on: '*',
       whereAttr:{
-         hasPrefixesIn: ['enh-', 'data-enh-'],
-         hasSuffixesIn:[
-            'my-enhancement-first-attr',
-            'my-enhancement-second-aspect'
-         ],
-         
+         hasRootIn: ['data', 'enh', 'data-enh'],
+         hasBase: 'my-enhancement',
+         hasBranchIn: ['first-aspect', 'second-aspect', ''],
+         hasLeafIn: {
+            'first-aspect': ['wow-this-is-deep', 'have-you-considered-using-json-for-this'],
+         }
       }
    });
    mo.addEventListener('observed-attr-change', e => {
@@ -347,10 +361,13 @@ MountObserver supports both approaches
       // {
       //    matchingElement,
       //    attrChangeInfo:{
-      //       fullName: 'data-enh-my-first-enhancement-attr',
-      //       suffix: 'my-first-enhancement-attr',
+      //       name: 'data-my-enhancement-first-aspect-wow-this-is-deep'
+      //       root: 'data',
+      //       base: 'my-enhancement',
+      //       branch: 'first-aspect',
+      //       leaf: 'wow-this-is-deep',
       //       oldValue: null,
-      //       newValue: 'hello'
+      //       newValue: 'good-bye'
       //       idx: 0,
       //    }
       // }
@@ -358,11 +375,44 @@ MountObserver supports both approaches
    mo.observe(div);
    setTimeout(() => {
       const myCustomElement = document.querySelector('my-custom-element');
-      myCustomElement.setAttribute('my-first-observed-attribute', 'good-bye');
+      myCustomElement.setAttribute('data-my-enhancement-first-aspect-wow-this-is-deep', 'good-bye');
    }, 1000);
 </script>
 ```
 
+Some libraries prefer to use the colon (:) rather than a dash to separate these levels of settings:
+
+Possibly some libraries may prefer to mix it up a bit:
+
+
+```html
+<div id=div>
+   <section class=hello 
+      data-my-enhancement=greetings 
+      data-my-enhancement:first-aspect=hello 
+      data-my-enhancement:second-aspect=goodbye
+      data-my-enhancement:first-aspect--wow-this-is-deep
+      data-my-enhancement:first-aspect--have-you-considered-using-json-for-this=just-saying
+   ></section>
+</div>
+```
+
+To support such syntax, specify the delimiter thusly:
+
+```JavaScript
+const mo = new MountObserver({
+   on: '*',
+   whereAttr:{
+      hasRootIn: ['data', 'enh', 'data-enh'],
+      hasBase: ['-', 'my-enhancement'],
+      hasBranchIn: [':', ['first-aspect', 'second-aspect', '']],
+      hasLeafIn: {
+         'first-aspect': ['--', ['wow-this-is-deep', 'have-you-considered-using-json-for-this']],
+      }
+   }
+});
+```
+
 ## Preemptive downloading
 
 There are two significant steps to imports, each of which imposes a cost:  
@@ -389,4 +439,47 @@ const observer = new MountObserver({
 
 So what this does is only check for the presence of an element with tag name "my-element", and it starts downloading the resource, even before the element has "mounted" based on other criteria.
 
+## Birtual Inclusions
+
+This proposal "sneaks in" one more feature, that perhaps should stand separately as its own proposal.  Because the MountObserver api allows us to attach behaviors on the fly based on css matching, and because the MountObserver would provide developers the "first point of contact" for such functionality, the efficiency argument seemingly "screams out" for this feature.
+
+The mount-observer is always on the lookout for a special tag that takes the form:
+
+```html
+<div>Some prior stuff</div>
+<b-i href=#my-snippet-of-html>
+   <div slot=slot1>hello</div>
+   <div slot=slot2>goodbye<div>
+</b-i>
+<div>Some additional stuff</div>
+```
+
+"b-i" stands for "birtual inclusion" where birtual is a made up word that is a portmanteau of birth and virtual.
+
+When it encounters such a thing, it searches "upwardly" through the chain of ShadowRoots for a template with id=my-kinda-sorta-custom-element (in this case), and caches them as it finds them. 
+
+Let's say the template looks as follows:
+
+```html
+<template id=my-snippet-of-html>
+   This is an example of a snippet of HTML that appears repeatedly.
+   <slot name=slot1></slot>
+   <slot name=slot2></slot>
+</template>
+```
+
+What we would end up with is:
+
+
+```html
+<div>Some prior stuff</div>
+This is an example of a snippet of HTML that appears repeatedly.
+<div>hello</div>
+<div>goodbye</div>
+<div>Some additional stuff</div>
+```
+
+Some significant differences with genuine slot support as used with (ShadowDOM'd) custom elements
 
+1.  There is no mechanism for updating the slots.  That is something under investigation with this userland [custom enhancement](https://github.com/bahrus/be-inclusive), that could possibly lead to a future implementation request tied to template instantiation.
+2.  ShadowDOM's slots act on a "many to one" basis.  Multiple light children with identical slot identifiers all get merged into a single (first?) matching slot within the Shadow DOM.  These birtual inclusions, instead, follow the opposite approach -- a single element with a slot identifier can get cloned into multiple slot targets as it weaves itself into the templates as they get merged together.

package/doWhereAttr.js

@@ -0,0 +1,43 @@
+import { AttrChangeEvent } from "./MountObserver.js";
+export function doWhereAttr(whereAttr, attributeName, target, oldValue, mo) {
+    const { hasRootIn, hasBase, hasBranchIn } = whereAttr;
+    const name = attributeName;
+    let restOfName = name;
+    let root;
+    let branch;
+    let idx = 0;
+    const hasBaseIsString = typeof hasBase === 'string';
+    const baseSelector = hasBaseIsString ? hasBase : hasBase[1];
+    const rootToBaseDelimiter = hasBaseIsString ? '-' : hasBase[0];
+    if (hasRootIn !== undefined) {
+        for (const rootTest in hasRootIn) {
+            if (restOfName.startsWith(rootTest)) {
+                root = rootTest;
+                restOfName = restOfName.substring(root.length + rootToBaseDelimiter.length);
+                break;
+            }
+        }
+    }
+    if (!restOfName.startsWith(baseSelector))
+        return;
+    restOfName = restOfName.substring(hasBase.length);
+    if (hasBranchIn) {
+        for (const branchTest in hasBranchIn) {
+            if (restOfName.startsWith(branchTest)) {
+                branch = branchTest;
+                break;
+            }
+        }
+    }
+    const newValue = target.getAttribute(attributeName);
+    const attrChangeInfo = {
+        name,
+        root,
+        base: baseSelector,
+        branch,
+        oldValue,
+        newValue,
+        idx
+    };
+    mo.dispatchEvent(new AttrChangeEvent(target, attrChangeInfo));
+}

package/getWhereAttrSelector.js

@@ -0,0 +1,35 @@
+export function getWhereAttrSelector(whereAttr, withoutAttrs) {
+    const { hasBase, hasBranchIn, hasRootIn } = whereAttr;
+    const fullListOfAttrs = [];
+    //TODO:  share this block with doWhereAttr?
+    const hasBaseIsString = typeof hasBase === 'string';
+    const baseSelector = hasBaseIsString ? hasBase : hasBase[1];
+    const rootToBaseDelimiter = hasBaseIsString ? '-' : hasBase[0];
+    //end TODO
+    let prefixLessMatches = [baseSelector];
+    if (hasBranchIn !== undefined) {
+        let baseToBranchDelimiter = '-';
+        let branches;
+        if (hasBranchIn.length === 2 && Array.isArray(hasBranchIn[1])) {
+            baseToBranchDelimiter = hasBranchIn[0];
+            branches = hasBranchIn[1];
+        }
+        else {
+            branches = hasBranchIn;
+        }
+        prefixLessMatches = branches.map(x => `${baseSelector}${baseToBranchDelimiter}x`);
+    }
+    const stems = hasRootIn || [''];
+    for (const stem of stems) {
+        const prefix = typeof stem === 'string' ? stem : stem.path;
+        for (const prefixLessMatch of prefixLessMatches) {
+            fullListOfAttrs.push(prefix.length === 0 ? prefixLessMatch : `${prefix}${rootToBaseDelimiter}${prefixLessMatch}`);
+        }
+    }
+    const listOfSelectors = fullListOfAttrs.map(s => `${withoutAttrs}[${s}]`);
+    const calculatedSelector = listOfSelectors.join(',');
+    return {
+        fullListOfAttrs,
+        calculatedSelector
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mount-observer",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",

package/types.d.ts

@@ -1,14 +1,8 @@
 export interface MountInit{
     readonly on?: CSSMatch,
-    readonly attribMatches?: Array<AttribMatch>,
-    readonly whereAttr?: {
-        withFirstName: string,
-        andQualifiers?: Array<string>,
-        withStemsIn?: Array<string | {
-            stem: string,
-            context: 'BuiltIn' | 'CustomElement'
-        }>,
-    },  
+    //readonly attribMatches?: Array<AttribMatch>,
+    readonly withTargetShadowRoot?: ShadowRoot, 
+    readonly whereAttr?: WhereAttr,  
     readonly whereElementIntersectsWith?: IntersectionObserverInit,
     readonly whereMediaMatches?: MediaQuery,
     readonly whereInstanceOf?: Array<typeof Node>, //[TODO] What's the best way to type this?,
@@ -27,6 +21,14 @@ export interface MountInit{
     //  */
     // readonly ignoreInitialMatches?: boolean,
 }
+export interface WhereAttr{
+    hasBase: string | [string, string],
+    hasBranchIn?: Array<string> | [string, Array<string>],
+    hasRootIn?: Array<string | {
+        path: string,
+        context: 'BuiltIn' | 'CustomElement' | 'Both'
+    }>,
+}
 type CSSMatch = string;
 type ImportString = string;
 type MediaQuery = string;
@@ -70,6 +72,10 @@ export interface AddMutationEventListener {
 
 interface AttrChangeInfo{
     name: string,
+    root?: string,
+    base?: string,
+    branch?: string,
+    leaf?: string, //TODO
     oldValue: string | null,
     newValue: string | null,
     idx: number,
@@ -119,9 +125,20 @@ export type attrChangeEventName = 'attr-change';
 export interface IAttrChangeEvent extends IMountEvent {
     attrChangeInfo: AttrChangeInfo,
 }
-export type attrChangeEventHander = (e: IAttrChangeEvent) => void;
-export interface AddAttrChangeEventistener{
-    addEventListener(eventName: attrChangeEventName, handler: attrChangeEventHander, options?: AddEventListenerOptions): void;
+export type attrChangeEventHandler = (e: IAttrChangeEvent) => void;
+export interface AddAttrChangeEventListener{
+    addEventListener(eventName: attrChangeEventName, handler: attrChangeEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region load event
+export type loadEventName = 'load';
+export interface ILoadEvent {
+    clone: DocumentFragment
+}
+export type loadEventHandler = (e: ILoadEvent) => void;
+export interface AddLoadEventListener{
+    addEventListener(eventName: loadEventName, handler: loadEventHandler, options?: AddEventListenerOptions): void
 }
 //#endregion