mount-observer 0.0.19 → 0.0.21

package/MountObserver.js

@@ -15,9 +15,10 @@ export class MountObserver extends EventTarget {
         super();
         const { on, whereElementIntersectsWith, whereMediaMatches } = init;
         let isComplex = false;
+        //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(':');
+            isComplex = reducedMatch.includes(' ') || (reducedMatch.includes(':') && reducedMatch.includes('('));
         }
         this.#isComplex = isComplex;
         if (whereElementIntersectsWith || whereMediaMatches)
@@ -40,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;
@@ -151,6 +152,7 @@ export class MountObserver extends EventTarget {
                                 const parts = this.#attrParts[idx];
                                 const attrChangeInfo = {
                                     oldValue,
+                                    name: attributeName,
                                     newValue,
                                     idx,
                                     parts
@@ -244,6 +246,7 @@ export class MountObserver extends EventTarget {
                     idx,
                     newValue,
                     oldValue,
+                    name,
                     parts
                 });
             }
@@ -350,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

@@ -7,11 +7,11 @@ Note that much of what is described below has not yet been polyfilled.
 
 # The MountObserver api.
 
-Author:  Bruce B. Anderson (with valuable feedback from [doeixd](https://github.com/doeixd) )
+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-4
+Last Update: 2024-5-21
 
 ## Benefits of this API
 
@@ -72,6 +72,8 @@ observer.observe(document);
 
 Invoking "disconnect" as shown above causes the observer to emit event "disconnectedCallback".
 
+The argument can also be an array of objects that fit the pattern shown above.
+
 If no imports are specified, it would go straight to do.* (if any such callbacks are specified), and it will also dispatch events as discussed below.
 
 This only searches for elements matching 'my-element' outside any shadow DOM.
@@ -235,7 +237,41 @@ If an element that is in "mounted" state according to a MountObserver instance i
 3)  If the mounted element is added outside the rootNode being observed, the mountObserver instance will dispatch event "exit", and the MountObserver instance will relinquish any further responsibility for this element.  
 4)  Ideally event "forget" would be dispatched just before the platform garbage collects an element the MountObserver instance is still monitoring, after all hard references are relinquished (or is that self-contradictory?).
 5)  If the new place it was added remains within the original rootNode and remains mounted, the MountObserver instance dispatches event "reconfirmed".
-6)  If the element no longer satisfies the criteria of the MountObserver instance, the MountObserver instance will dispatch event "dismount".  
+6)  If the element no longer satisfies the criteria of the MountObserver instance, the MountObserver instance will dispatch event "dismount". 
+
+## Dismounting
+
+In many cases, it will be critical to inform the developer **why** the element no longer satisfies all the criteria.  For example, we may be using an intersection observer, and when we've scrolled away from view, we can "shut down" until the element is (nearly) scrolled back into view.  We may also be displaying things differently depending on the network speed.  How we should respond when one of the original conditions, but not the other, no longer applies, is of paramount importance.
+
+So the dismount event should provide a "checklist" of all the conditions, and their current value:
+
+```JavaScript
+mediaMatches: true,
+containerMatches: true,
+satisifiesCustomCondition: true,
+whereLangIn: ['en-GB'],
+whereConnection:{
+   effectiveTypeMatches: true
+},
+isIntersecting: false,
+changedConditions: ['isIntersecting']
+```
+
+## Get play-by-play updates?
+
+An issue raised by @doeixd, I think, is what if we want to be informed of the status of all the conditions that are applicable to an element being mounted / dismounted?  I can see scenarios where this would be useful, for reasons similar to wanting to know why the element dismounted.
+
+Since this could have a negative impact on performance, I think it should be something we opt-in to:
+
+```JavaScript
+getPlayByPlay: true
+```
+
+Now the question is when should this progress reporting start?  It could either start the moment the element becomes mounted the first time.  Or it could happen the moment any of the conditions are satisfied.  But some of the conditions could be trivially satisfied for the vast majority of elements (e.g. network speed is 4g or greater).
+
+So I believe the prudent thing to do is wait for all the conditions to be satisfied,  before engaging in this kind of commentary, i.e. after the first mount.
+
+The alternative to providing this feature, which I'm leaning towards, is to just ask the developer to create "specialized" mountObserver construction arguments, that turn on and off precisely when the developer needs to know.
 
 ## A tribute to attributes
 
@@ -245,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.
 
@@ -316,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?
 
@@ -324,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';
@@ -358,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';
@@ -394,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,
@@ -465,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:  
@@ -481,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)
@@ -491,13 +552,16 @@ 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.
 
 Also, this proposal is partly focused on better management of importing resources "from a distance", in particular via imports carried out via http.  Is it such a stretch to look closely at scenarios where that distance happens to be shorter, i.e. found somewhere [in the document tree structure](https://github.com/tc39/proposal-module-expressions)?
 
-The mount-observer is always on the lookout for template tags with an href attribute starting with #:
+The mount-observer is always on the lookout for template tags with a src attribute starting with #:
 
 ```html
 <template src=#id-of-source-template></template>
@@ -521,7 +585,7 @@ Let's say the source template looks as follows:
 
 ```html
 <template id=id-of-source-template>
-   I don't know why you say <slot name=slot2></slot> I say <slot name=slot1></slot>
+   <div>I don't know why you say <slot name=slot2></slot> I say <slot name=slot1></slot></div>
 </template>
 ```
 
@@ -583,3 +647,13 @@ This proposal (and polyfill) also supports the option to utilize ShadowDOM / slo
 </div>
 ```
 
+> [!NOTE]
+> An intriguing sounding alternative to using the template tag that disappears, as shown above, is to use a new tag for this purpose.  I think something along the lines of what is [proposed here](https://github.com/WICG/webcomponents/issues/1059) has a much better semantic ring to it:
+
+```html
+<compose src="#sharedHeader"></compose>
+<compose src="#productCard"></compose>
+```
+
+The discussion there leads to an open question whether a processing instruction would be better.  I think the compose tag would make much more sense, vs a processing instruction, as it could then support slotted children (behaving similar to the Beatles' example above).  Or maybe another tag should be introduced that is the equivalent of the slot, to avoid confusion. or some equivalent.  But I strongly suspect that could significantly reduce the payload size of some documents, if we can reuse blocks of HTML, inserting sections of customized content for each instance.
+

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.19",
+  "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>,
     /**
@@ -66,7 +67,7 @@ export interface MountContext{
 }
 
 type PipelineStage = 'Inspecting' | 'PreImport' | 'PostImport' | 'Import' 
-export type PipelineProcessor<ReturnType = void> = (matchingElement: Element, observer: IMountObserver, ctx: MountContext) => Promise<ReturnType>;
+export type PipelineProcessor<ReturnType = void> = (matchingElement: Element, observer: IMountObserver, ctx: MountContext) => Promise<ReturnType> | ReturnType;
 
 //#region mutation event
 export type mutationEventName = 'mutation-event';
@@ -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>,
 }