mount-observer 0.0.20 → 0.0.21

package/MountObserver.js

@@ -15,7 +15,7 @@ export class MountObserver extends EventTarget {
         super();
         const { on, whereElementIntersectsWith, whereMediaMatches } = init;
         let isComplex = false;
-        //TODO:  further this problem further.  Starting to think this is basically not polyfillable
+        //TODO:  study this problem further.  Starting to think this is basically not polyfillable
         if (on !== undefined) {
             const reducedMatch = on.replaceAll(':not(', '');
             isComplex = reducedMatch.includes(' ') || (reducedMatch.includes(':') && reducedMatch.includes('('));
@@ -41,7 +41,7 @@ export class MountObserver extends EventTarget {
         if (whereAttr === undefined)
             return withoutAttrs;
         const { getWhereAttrSelector } = await import('./getWhereAttrSelector.js');
-        const info = getWhereAttrSelector(whereAttr, withoutAttrs);
+        const info = await getWhereAttrSelector(whereAttr, withoutAttrs);
         const { fullListOfAttrs, calculatedSelector, partitionedAttrs } = info;
         this.#fullListOfAttrs = fullListOfAttrs;
         this.#attrParts = partitionedAttrs;
@@ -152,6 +152,7 @@ export class MountObserver extends EventTarget {
                                 const parts = this.#attrParts[idx];
                                 const attrChangeInfo = {
                                     oldValue,
+                                    name: attributeName,
                                     newValue,
                                     idx,
                                     parts
@@ -245,6 +246,7 @@ export class MountObserver extends EventTarget {
                     idx,
                     newValue,
                     oldValue,
+                    name,
                     parts
                 });
             }
@@ -351,7 +353,7 @@ export class DisconnectEvent extends Event {
 export class AttrChangeEvent extends Event {
     mountedElement;
     attrChangeInfos;
-    static eventName = 'attr-change';
+    static eventName = 'attrChange';
     constructor(mountedElement, attrChangeInfos) {
         super(AttrChangeEvent.eventName);
         this.mountedElement = mountedElement;

package/README.md

@@ -11,7 +11,7 @@ Author:  Bruce B. Anderson (with valuable feedback from @doeixd )
 
 Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
 
-Last Update: 2024-5-5
+Last Update: 2024-5-21
 
 ## Benefits of this API
 
@@ -281,40 +281,59 @@ 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 ObserveObservedAttributes API [WIP]
+## A key attribute of attributes
 
-Example:
+I think it is useful to divide [attributes](https://jakearchibald.com/2024/attributes-vs-properties/) that we we would want to observe into two categories:
 
-```html
-<div id=div>
-   <my-custom-element my-first-observed-attribute="hello"></my-custom-element>
-</div>
-<script type=module>
-   import {MountObserver} from '../MountObserver.js';
-   const mo = new MountObserver({
-      on: '*',
-      whereInstanceOf: [MyCustomElement]
-   });
-   mo.addEventListener('parsed-attrs-changed', e => {
-      const {matchingElement, modifiedObjectFieldValues, preModifiedFieldValues} = e;
-      console.log({matchingElement, modifiedObjectFieldValues, preModifiedFieldValues});
-   });
-   mo.observe(div);
-   setTimeout(() => {
-      const myCustomElement = document.querySelector('my-custom-element');
-      myCustomElement.setAttribute('my-first-observed-attribute', 'good-bye');
-   }, 1000);
-</script>
+1.  Invariably named, prefix-less, "top-level" attributes that serve as the "source of the truth".
+
+Examples are many built-in global attributes, like lang, or contenteditable, or more specialized examples such as "content" for the meta tag.  Often, setting the property values corresponding to these attributes results in directly reflecting those property values to the attributes (perhaps in a round about way). And there are usually no events we can subscribe to in order to know when the property changes. Hijacking the property setter in order to observe changes may not always work or feel very resilient. So monitoring the attribute value is often the most effective way of observing when the property/attribute state for these elements change.  Some attributes of custom elements may fit this category (but maybe a minority of them).
+
+And in some application environments, adjusting state via attributes may be the preferred approach, so we want to support this scenario, even if it doesn't abide by a common view of what constitutes "best practices." Again, the distinguishing feature of the attributes that we would want to monitor in this way is that they are "top-level" and unlikely to differ in name across different Shadow DOM scopes.  
+
+2.  In contrast, there are scenarios where we want to support somewhat fluid, renamable attributes within different Shadow DOM scopes, which add behavior/enhancement capabilities on top of built-in or third party custom elements.
+
+We want our api to be able to distinguish between these two, and to be able to combine both types in one mount observer instance.
+
+
+### Attributes that are the "source of truth"
+
+So for the first scenario, we can specify attributes to listen for as follows:
+
+```JavaScript
+import {MountObserver} from 'mount-observer/MountObserver.js';
+const mo = new MountObserver({
+   on: '*',
+   whereAttr:{
+      isIn: ['lang', 'contenteditable']
+   }
+});
+
+mo.addEventListener('attrChange', e => {
+   console.log(e);
+   // {
+   //    matchingElement,
+   //    attrChangeInfo:[{
+   //       idx: 0,
+   //       name: 'lang'
+   //       oldValue: null,
+   //       newValue: 'en-GB',
+   //    }]
+   // }
+});
 ```
--->
 
+### Help with parsing?
+
+This proposal is likely to evolve going forward, attempting to synthesize [separate ideas](https://github.com/WICG/webcomponents/issues/1045) for declaratively specifying how to interpret the attributes, parsing them so that they may be merged into properties of a class instance. 
+
+But for now, such support is not part of this proposal (though we can see a glimpse of what that support might look like below).
 
 ### Custom Enhancements in userland
 
-[This proposal could take quite a while to see the light of day, if ever](https://github.com/WICG/webcomponents/issues/1000).
+[This proposal, support for (progressive) enhancement of built-in or third-party custom elements, could take quite a while to see the light of day, if ever](https://github.com/WICG/webcomponents/issues/1000).
 
-In the meantime, we want to provide the most help for providing for custom enhancements in userland, and for any other kind of (progressive) enhancement based on attributes going forward.
+In the meantime, we want to provide the most help for providing for custom enhancements in userland, and for any other kind of (progressive) enhancement based on (server-rendered) attributes going forward.
 
 Suppose we have a (progressive) enhancement that we want to apply based on the presence of 1 or more attributes.
 
@@ -352,7 +371,7 @@ We want to also support:
 
 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?
+But now when we consider applying this enhancement to third party 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 data- prefix?
 
@@ -360,7 +379,9 @@ And we want to support an alternative, more semantic sounding prefix to data, sa
 
 Here's what the api **doesn't** provide (as originally proposed):
 
-## Rejected option -- The carpal syndrome syntax
+#### The carpal syndrome syntax
+
+Using the same expression structure as above, we would end up with this avalanche of settings:
 
 ```JavaScript
 import {MountObserver} from '../MountObserver.js';
@@ -394,7 +415,9 @@ const mo = new MountObserver({
 });
 ```
 
-## Supported -- The DRY Way
+#### The DRY Way
+
+This seems like a much better approach, and is supported by this proposal:
 
 ```JavaScript
 import {MountObserver} from '../MountObserver.js';
@@ -430,7 +453,7 @@ MountObserver provides a breakdown of the matching attribute when encountered:
          }
       }
    });
-   mo.addEventListener('observed-attr-change', e => {
+   mo.addEventListener('attrChange', e => {
       console.log(e);
       // {
       //    matchingElement,
@@ -501,6 +524,8 @@ Tentative rules:
 
 The thinking here is that longer roots indicate higher "specificity", so it is safer to use that one.
 
+
+
 ## Preemptive downloading
 
 There are two significant steps to imports, each of which imposes a cost:  
@@ -517,7 +542,7 @@ So for this we add option:
 ```JavaScript
 const observer = new MountObserver({
    on: 'my-element',
-   loading: 'eager',
+   loadingEagerness: 'eager',
    import: './my-element.js',
    do:{
       mount: (matchingElement, {modules}) => customElements.define(modules[0].MyElement)
@@ -527,6 +552,9 @@ 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.
 
+> [!NOTE]
+> As a result of the google IO 2024 talks, I became aware that there is some similarity between this proposal and the [speculation rules api](https://developer.chrome.com/blog/speculation-rules-improvements).  This motivated the change to the property from "loading" to loadingEagerness above.
+
 ## Intra document html imports
 
 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.

package/getWhereAttrSelector.js

@@ -1,72 +1,74 @@
-export function getWhereAttrSelector(whereAttr, withoutAttrs) {
-    const { hasBase, hasBranchIn, hasRootIn } = whereAttr;
-    const hasRootInGuaranteed = hasRootIn || [{
-            start: '',
-            context: 'Both'
-        }];
-    const fullListOfAttrs = [];
+export async function getWhereAttrSelector(whereAttr, withoutAttrs) {
+    const { hasBase, hasBranchIn, hasRootIn, isIn } = whereAttr;
+    const fullListOfAttrs = isIn !== undefined ? [...isIn] : [];
     const partitionedAttrs = [];
-    let prefixLessMatches = [];
-    const hasBaseIsString = typeof hasBase === 'string';
-    const baseSelector = hasBaseIsString ? hasBase : hasBase[1];
-    const rootToBaseDelimiter = hasBaseIsString ? '-' : hasBase[0];
-    if (hasBranchIn !== undefined) {
-        let baseToBranchDelimiter = '-';
-        let branches;
-        if (hasBranchIn.length === 2 && Array.isArray(hasBranchIn[1])) {
-            baseToBranchDelimiter = hasBranchIn[0];
-            branches = hasBranchIn[1];
+    if (hasBase !== undefined) {
+        const hasRootInGuaranteed = hasRootIn || [{
+                start: '',
+                context: 'Both'
+            }];
+        let prefixLessMatches = [];
+        const hasBaseIsString = typeof hasBase === 'string';
+        const baseSelector = hasBaseIsString ? hasBase : hasBase[1];
+        const rootToBaseDelimiter = hasBaseIsString ? '-' : hasBase[0];
+        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 => ({
+                rootToBaseDelimiter,
+                base: baseSelector,
+                baseToBranchDelimiter: x ? baseToBranchDelimiter : '',
+                branch: x
+            }));
         }
         else {
-            branches = hasBranchIn;
+            prefixLessMatches.push({
+                rootToBaseDelimiter,
+                base: baseSelector,
+            });
         }
-        prefixLessMatches = branches.map(x => ({
-            rootToBaseDelimiter,
-            base: baseSelector,
-            baseToBranchDelimiter: x ? baseToBranchDelimiter : '',
-            branch: x
-        }));
-    }
-    else {
-        prefixLessMatches.push({
-            rootToBaseDelimiter,
-            base: baseSelector,
-        });
-    }
-    for (const rootCnfg of hasRootInGuaranteed) {
-        const { start } = rootCnfg;
-        for (const match of prefixLessMatches) {
-            const { base, baseToBranchDelimiter, branch, rootToBaseDelimiter } = match;
-            let branchIdx = 0;
-            for (const prefixLessMatch of prefixLessMatches) {
-                const { base, baseToBranchDelimiter, branch } = prefixLessMatch;
-                const startAndRootToBaseDelimiter = start ? `${start}${rootToBaseDelimiter}` : '';
-                //TODO:  could probably reduce the size of the code below
-                if (branch) {
-                    //will always have branch?
-                    const name = `${startAndRootToBaseDelimiter}${base}${baseToBranchDelimiter}${branch}`;
-                    fullListOfAttrs.push(name);
-                    partitionedAttrs.push({
-                        root: start,
-                        name,
-                        base,
-                        branch,
-                        branchIdx,
-                        rootCnfg
-                    });
-                }
-                else {
-                    const name = `${startAndRootToBaseDelimiter}${base}`;
-                    fullListOfAttrs.push(name);
-                    partitionedAttrs.push({
-                        root: start,
-                        name,
-                        base,
-                        rootCnfg,
-                        branchIdx
-                    });
+        for (const rootCnfg of hasRootInGuaranteed) {
+            const { start } = rootCnfg;
+            for (const match of prefixLessMatches) {
+                const { base, baseToBranchDelimiter, branch, rootToBaseDelimiter } = match;
+                let branchIdx = 0;
+                for (const prefixLessMatch of prefixLessMatches) {
+                    const { base, baseToBranchDelimiter, branch } = prefixLessMatch;
+                    const startAndRootToBaseDelimiter = start ? `${start}${rootToBaseDelimiter}` : '';
+                    //TODO:  could probably reduce the size of the code below
+                    if (branch) {
+                        //will always have branch?
+                        const name = `${startAndRootToBaseDelimiter}${base}${baseToBranchDelimiter}${branch}`;
+                        fullListOfAttrs.push(name);
+                        partitionedAttrs.push({
+                            root: start,
+                            name,
+                            base,
+                            branch,
+                            branchIdx,
+                            rootCnfg
+                        });
+                    }
+                    else {
+                        const name = `${startAndRootToBaseDelimiter}${base}`;
+                        fullListOfAttrs.push(name);
+                        partitionedAttrs.push({
+                            root: start,
+                            name,
+                            base,
+                            rootCnfg,
+                            branchIdx
+                        });
+                    }
+                    branchIdx++;
                 }
-                branchIdx++;
             }
         }
     }

package/package.json

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

package/types.d.ts

@@ -30,7 +30,8 @@ export interface RootCnfg{
 //export type RootAttrOptions = Array<string | RootCnfg>;
 export type delimiter = string;
 export interface WhereAttr{
-    hasBase: string | [delimiter, string],
+    isIn?: Array<string>,
+    hasBase?: string | [delimiter, string],
     hasBranchIn?: Array<string> | [delimiter, Array<string>],
     hasRootIn?: Array<RootCnfg>,
     /**
@@ -96,8 +97,8 @@ interface AttrChangeInfo{
     oldValue: string | null,
     newValue: string | null,
     idx: number,
+    name: string,
     parts: AttrParts,
-    //parsedNewValue?: any,
 }
 
 //#region mount event
@@ -139,7 +140,7 @@ export interface AddDisconnectEventListener {
 //endregion
 
 //#region attribute change event
-export type attrChangeEventName = 'attr-change';
+export type attrChangeEventName = 'attrChange';
 export interface IAttrChangeEvent extends IMountEvent {
     attrChangeInfos: Array<AttrChangeInfo>,
 }