mount-observer 0.0.7 → 0.0.8

package/MountObserver.js

@@ -28,25 +28,20 @@ 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}`);
-            }
-        }
-        this.#calculatedSelector = matches.join(',');
+            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;
     }
     unobserve(within) {
@@ -90,8 +85,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 +104,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 +117,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 +155,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 +189,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 +230,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 +255,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))
@@ -276,7 +274,7 @@ export class MountObserver extends EventTarget {
         this.#mount(elsToMount, initializing);
     }
     async #inspectWithin(within, initializing) {
-        const els = Array.from(within.querySelectorAll(this.#selector));
+        const els = Array.from(within.querySelectorAll(await this.#selector()));
         this.#filterAndMount(els, false, initializing);
     }
 }
@@ -322,3 +320,4 @@ export class AttrChangeEvent extends Event {
         this.attrChangeInfo = attrChangeInfo;
     }
 }
+//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-14
 
 ## 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.
 
 
@@ -206,7 +209,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 +250,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 +268,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,6 +298,7 @@ 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
@@ -302,7 +310,8 @@ const mo = new MountObserver({
          {
             name: 'my-enhancement-second-aspect',
             builtIn: true
-         }
+         },
+         ...
       ]
       
    }
@@ -316,30 +325,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-attr-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-attr', 'second-attr', ''],
+         hasLeafIn: {
+            'first-attr': ['wow-this-is-deep', 'have-you-considered-using-json-for-this'],
+         }
       }
    });
    mo.addEventListener('observed-attr-change', e => {
@@ -347,10 +359,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-attr',
+      //       leaf: 'wow-this-is-deep',
       //       oldValue: null,
-      //       newValue: 'hello'
+      //       newValue: 'good-bye'
       //       idx: 0,
       //    }
       // }
@@ -358,11 +373,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, specify the delimiter thusly:
+
+```JavaScript
+const mo = new MountObserver({
+   on: '*',
+   whereAttr:{
+      hasRootIn: ['data', 'enh', 'data-enh'],
+      hasBase: ['-', 'my-enhancement'],
+      hasBranchIn: [':', ['first-attr', 'second-attr', '']],
+      hasLeafIn: {
+         'first-attr': ['--', ['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 +437,3 @@ 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.
 
-

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.8",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",

package/types.d.ts

@@ -1,14 +1,7 @@
 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 whereAttr?: WhereAttr,  
     readonly whereElementIntersectsWith?: IntersectionObserverInit,
     readonly whereMediaMatches?: MediaQuery,
     readonly whereInstanceOf?: Array<typeof Node>, //[TODO] What's the best way to type this?,
@@ -27,6 +20,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 +71,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,