mount-observer 0.0.18 → 0.0.20

package/MountObserver.js

@@ -15,9 +15,10 @@ 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
         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)
@@ -74,7 +75,7 @@ export class MountObserver extends EventTarget {
             this.#templLookUp.set(id, templ);
         return templ;
     }
-    unobserve(within) {
+    disconnect(within) {
         const nodeToMonitor = this.#isComplex ? (within instanceof ShadowRoot ? within : within.getRootNode()) : within;
         const currentCount = refCount.get(nodeToMonitor);
         if (currentCount !== undefined) {
@@ -98,6 +99,7 @@ export class MountObserver extends EventTarget {
                 console.warn(refCountErr);
             }
         }
+        this.dispatchEvent(new Event('disconnectedCallback'));
     }
     async observe(within) {
         await this.#selector();
@@ -314,7 +316,7 @@ export class MountObserver extends EventTarget {
     }
 }
 const refCountErr = 'mount-observer ref count mismatch';
-export const inclTemplQry = 'template[href^="#"]:not([hidden])';
+export const inclTemplQry = 'template[src^="#"]:not([hidden])';
 // https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
 /**
  * The `mutation-event` event represents something that happened.

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
+Author:  Bruce B. Anderson (with valuable feedback from @doeixd )
 
 Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
 
-Last Update: 2024-2-20
+Last Update: 2024-5-5
 
 ## Benefits of this API
 
@@ -19,7 +19,8 @@ What follows is a far more ambitious alternative to the [lazy custom element pro
 
 ["Binding from a distance"](https://github.com/WICG/webcomponents/issues/1035#issuecomment-1806393525) refers to empowering the developer to essentially manage their own "stylesheets" -- but rather than for purposes of styling, using these rules to attach behaviors, set property values, etc, to the HTML as it streams in.  Libraries that take this approach include [Corset](https://corset.dev/) and [trans-render](https://github.com/bahrus/trans-render).  The concept has been promoted by a [number](https://bkardell.com/blog/CSSLike.html) [of](https://www.w3.org/TR/NOTE-AS)  [prominent](https://www.xanthir.com/blog/b4K_0) voices in the community. 
 
-The underlying theme is this api is meant to make it easy for the developer to do the right thing, by encouraging lazy loading and smaller footprints. It rolls up most all the other observer api's into one.
+The underlying theme is this api is meant to make it easy for the developer to do the right thing, by encouraging lazy loading and smaller footprints. It rolls up most all the other observer api's into one, including, potentially, [this one](https://github.com/whatwg/dom/issues/1285).
+
 
 ### Does this api make the impossible possible?
 
@@ -27,7 +28,9 @@ There is quite a bit of functionality this proposal would open up, that is excee
 
 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.
+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.  
+
+ 
 
 3.  Knowing when an element, previously being monitored for, passes totally "out-of-scope", so that no more hard references to the element remain.  This would allow for cleanup of no longer needed weak references without requiring polling.
 
@@ -44,6 +47,9 @@ The amount of code necessary to accomplish these common tasks designed to improv
 
 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.
 
+> [!Note]
+> Reading through the historical links tied to the selector-observer proposal this proposal helped spawn, I may have painted an overly optimistic picture of [what the platform is capable of](https://github.com/whatwg/dom/issues/398).  It does leave me a little puzzled why this isn't an issue when it comes to styling, and also if some of the advances that were utilized to support :has could be applied to this problem space, so that maybe the arguments raised there have weakened.  Even if the concerns raised are as relevant today, I think considering the use cases this proposal envisions, that the objections could be overcome, for the following reasons: 1.  For scenarios where lazy loading is the primary objective, "bunching" multiple DOM mutations together and only reevaluating when things are quite idle is perfectly reasonable.  Also, for binding from a distance, most of the mutations that need responding to quickly will be when the *state of the host* changes, so DOM mutations play a somewhat muted role in that regard. Again, bunching multiple DOM mutations together, even if adds a bit of a delay, also seems reasonable.  I also think the platform could add an "analysis" step to look at the query and categorize it as "simple" queries vs complex.  Selector queries that are driven by the characteristics of the element itself (localName, attributes, etc) could be handled in a more expedited fashion.  Those that the platform does expect to require more babysitting could be monitored for less vigilantly.  Maybe in the latter case, a console.warning could be emitted during initialization.  The other use case, for lazy loading custom elements and custom enhancements based on attributes, I think most of the time this would fit the "simple" scenario, so again there wouldn't be much of an issue. 
+
 ## First use case -- lazy loading custom elements
 
 To specify the equivalent of what the alternative proposal linked to above would do, we can do the following:
@@ -53,37 +59,61 @@ const observer = new MountObserver({
    on:'my-element',
    import: './my-element.js',
    do: {
-      mount: ({localName}, {module}) => {
+      mount: ({localName}, {modules, observer}) => {
         if(!customElements.get(localName)) {
-            customElements.define(localName, module.MyElement);
+            customElements.define(localName, modules[0].MyElement);
         }
+        observer.disconnect();
       }
    }
 });
 observer.observe(document);
 ```
 
-If no import is specified, it would go straight to do.* (if any such callbacks are specified), and it will also dispatch events as discussed below.
+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.
 
 But the observe method can accept a node within the document, or a shadowRoot, or a node inside a shadowRoot as well.
 
-The import can also be a function:
+The "observer" constant above is a class instance that inherits from EventTarget, which means it can be subscribed to by outside interests.
+
+##  The import key
+
+This proposal has been amended to support multiple imports, including of different types:
 
 ```JavaScript
 const observer = new MountObserver({
-   on: 'my-element',
-   import: async (matchingElement, {module}) => await import('./my-element.js');
+   on:'my-element',
+   import: [
+      ['./my-element-small.css', {type: 'css'}],
+      './my-element.js',
+   ]
+   do: {
+      mount: ({localName}, {modules, observer}) => {
+        if(!customElements.get(localName)) {
+            customElements.define(localName, modules[1].MyElement);
+        }
+        observer.disconnect();
+      }
+   }
 });
-observer.observe(myRootNode);
+observer.observe(document);
 ```
 
-which would work better with current bundlers, I suspect.  Also, we can do interesting things like merge multiple imports into one "module".  But should this API be built into the platform, such functions wouldn't be necessary, as bundlers could start to recognize strings that are passed to the MountObserver's constructor.
+Th key can accept either a single import or multiple (via an array).
+
+The do event won't be invoked until all the imports have been successfully completed and inserted into the modules array.
+
+Previously, this proposal called for allowing arrow functions as well, thinking that could be a good interim way to support bundlers.  But the valuable input provided by [doeixd](https://github.com/doeixd) makes me think that that interim support could just as effectively be done by the developer in the do methods.
+
+This proposal would also include support for JSON and HTML module imports. 
 
-This proposal would also include support for CSS, JSON, HTML module imports. 
 
-The "observer" constant above is a class instance that inherits from EventTarget, which means it can be subscribed to by outside interests.
 
 ## Binding from a distance
 
@@ -140,7 +170,7 @@ const observer = new MountObserver({
    },
    import: ['./my-element-small.css', {type: 'css'}],
    do: {
-      mount: ({localName}, {module}) => {
+      mount: ({localName}, {modules}) => {
         ...
       },
       dismount: ...,
@@ -153,7 +183,13 @@ const observer = new MountObserver({
 })
 ```
 
-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.  
+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. 
+
+<!--
+
+[TODO] Maybe should also (optionally?) pass back which checks failed and which succeeded on dismount.  Not sure I really see a use case for it, but leaving the thought here for now 
+
+--> 
 
 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:
 
@@ -201,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
 
@@ -211,6 +281,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 ObserveObservedAttributes API [WIP]
 
 Example:
@@ -236,13 +307,16 @@ Example:
    }, 1000);
 </script>
 ```
+-->
+
 
+### Custom Enhancements in userland
 
-### Scenario 2 -- 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).
 
-Based on [the proposal as it currently stands](https://github.com/WICG/webcomponents/issues/1000), in this case the class prototype would *not* have the attributes defined as a static property of the class, so that the constructor arguments in the previous scenario wouldn't be sufficient.  So instead, what would seem 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 attributes going forward.
 
-Suppose we have a progressive enhancement that we want to apply based on the presence of 1 or more attributes.
+Suppose we have a (progressive) enhancement that we want to apply based on the presence of 1 or more attributes.
 
 To make this discussion concrete, let's suppose the "canonical" names of those attributes are:
 
@@ -284,7 +358,7 @@ So let's say we want to insist that on custom elements, we must have the data- p
 
 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 **doesn't** provide:
+Here's what the api **doesn't** provide (as originally proposed):
 
 ## Rejected option -- The carpal syndrome syntax
 
@@ -415,6 +489,18 @@ const mo = new MountObserver({
 });
 ```
 
+## Resolving ambiguity
+
+Because we want the multiple root values (enh-*, data-enh-*, *) to be treated as equivalent, from a developer point of view, we have a possible ambiguity -- what if more than one root is present for the same base, branch and leaf?  Which value trumps the others?
+
+Tentative rules:
+
+1.  Roots must differ in length.
+2.  If one value is null (attribute not present) and the other a string, the one with the string value trumps.
+3.  If two or more equivalent attributes have string values, the one with the longer root prevails.
+
+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:  
@@ -434,7 +520,7 @@ const observer = new MountObserver({
    loading: 'eager',
    import: './my-element.js',
    do:{
-      mount: (matchingElement, {module}) => customElements.define(module.MyElement)
+      mount: (matchingElement, {modules}) => customElements.define(modules[0].MyElement)
    }
 })
 ```
@@ -447,21 +533,22 @@ This proposal "sneaks in" one more feature, that perhaps should stand separately
 
 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 href=#id-of-source-template></template>
+<template src=#id-of-source-template></template>
 ```
 
 For example:
 
 ```html
-<div>Some prior stuff</div>
-<template href=#id-of-source-template>
-   <div slot=slot1>hello</div>
-   <div slot=slot2>goodbye<div>
+<div>Your Mother Should Know</div>
+<div>I Am the Walrus</div>
+<template src=#id-of-source-template>
+   <span slot=slot1>hello</span>
+   <span slot=slot2>goodbye<span>
 </template>
-<div>Some additional stuff</div>
+<div>Strawberry Fields Forever</div>
 ```
 
 When it encounters such a thing, it searches "upwardly" through the chain of ShadowRoots for a template with id=id-of-source-template (in this case), and caches them as it finds them. 
@@ -470,9 +557,7 @@ Let's say the source template looks as follows:
 
 ```html
 <template id=id-of-source-template>
-   This is an example of a snippet of HTML that appears repeatedly.
-   <slot name=slot1></slot>
-   <slot name=slot2></slot>
+   <div>I don't know why you say <slot name=slot2></slot> I say <slot name=slot1></slot></div>
 </template>
 ```
 
@@ -480,11 +565,10 @@ 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>
+<div>Your Mother Should Know</div>
+<div>I Am the Walrus</div>
+<div>I don't know why you say <span>goodbye</span> I say <span>hello</span></div>
+<div>Strawberry Fields Forever</div>
 ```
 
 Some significant differences with genuine slot support as used with (ShadowDOM'd) custom elements
@@ -498,7 +582,7 @@ This proposal (and polyfill) also supports the option to utilize ShadowDOM / slo
 
 ```html
 <template id=chorus>
-   <template href=#beautiful>
+   <template src=#beautiful>
       <span slot=subjectIs>
             <slot name=subjectIs1></slot>
       </span>
@@ -509,7 +593,7 @@ This proposal (and polyfill) also supports the option to utilize ShadowDOM / slo
       <slot name=verb1></slot> bring
       <slot name=pronoun1></slot> down</div>
    <div>Oh no</div>
-   <template href=#beautiful>
+   <template src=#beautiful>
       <span slot=subjectIs>
             <slot name=subjectIs2></slot>
       </span>
@@ -521,11 +605,11 @@ This proposal (and polyfill) also supports the option to utilize ShadowDOM / slo
    </div>
    <div>Oh no</div>
 
-   <template href=#down></template>
+   <template src=#down></template>
 </template>
 
 <div class=chorus>
-   <template href=#chorus shadowRootModeOnLoad=open></template>
+   <template src=#chorus shadowRootModeOnLoad=open></template>
    <span slot=verb1>can't</span>
    <span slot=verb2>can't</span>
    <span slot=pronoun1>me</span>
@@ -535,3 +619,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/birtualizeMatch.js

@@ -1,8 +1,8 @@
 import { inclTemplQry } from './MountObserver.js';
 export async function birtualizeMatch(self, el, level) {
-    const href = el.getAttribute('href');
-    el.removeAttribute('href');
-    const templID = href.substring(1);
+    const src = el.getAttribute('src');
+    el.removeAttribute('src');
+    const templID = src.substring(1);
     const fragment = self.objNde?.deref();
     if (fragment === undefined)
         return;

package/package.json

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

package/types.d.ts

@@ -33,6 +33,11 @@ export interface WhereAttr{
     hasBase: string | [delimiter, string],
     hasBranchIn?: Array<string> | [delimiter, Array<string>],
     hasRootIn?: Array<RootCnfg>,
+    /**
+     * Used by consumers to track the universal meaning of this combination
+     * regardless of how the actual name values may be changed.
+     */
+    metadata?: any,
 }
 type CSSMatch = string;
 type ImportString = string;
@@ -51,7 +56,7 @@ export interface IMountObserver {
     // readonly mountedRefs:  WeakRef<Element>[],
     // readonly dismountedRefs: WeakRef<Element>[],
     observe(within: Node): void;
-    unobserve(within: Node): void;
+    disconnect(within: Node): void;
     module?: any;
 } 
 
@@ -61,7 +66,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';
@@ -83,7 +88,8 @@ interface AttrParts{
     branchIdx: number,
     leaf?: string, //TODO
     leafIdx?: number, //TODO
-    rootCnfg?: RootCnfg
+    rootCnfg?: RootCnfg,
+    metadata?: any,
 }
 
 interface AttrChangeInfo{