mount-observer 0.0.18 → 0.0.19

package/MountObserver.js

@@ -74,7 +74,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 +98,7 @@ export class MountObserver extends EventTarget {
                 console.warn(refCountErr);
             }
         }
+        this.dispatchEvent(new Event('disconnectedCallback'));
     }
     async observe(within) {
         await this.#selector();
@@ -314,7 +315,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](https://github.com/doeixd) )
 
 Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
 
-Last Update: 2024-2-20
+Last Update: 2024-5-4
 
 ## 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,59 @@ 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".
+
+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 +168,7 @@ const observer = new MountObserver({
    },
    import: ['./my-element-small.css', {type: 'css'}],
    do: {
-      mount: ({localName}, {module}) => {
+      mount: ({localName}, {modules}) => {
         ...
       },
       dismount: ...,
@@ -153,7 +181,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:
 
@@ -211,6 +245,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 +271,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 +322,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 +453,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 +484,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)
    }
 })
 ```
@@ -450,18 +500,19 @@ Also, this proposal is partly focused on better management of importing resource
 The mount-observer is always on the lookout for template tags with an href 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 +521,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>
+   I don't know why you say <slot name=slot2></slot> I say <slot name=slot1></slot>
 </template>
 ```
 
@@ -480,11 +529,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 +546,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 +557,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 +569,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>

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.19",
   "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;
 } 
 
@@ -83,7 +88,8 @@ interface AttrParts{
     branchIdx: number,
     leaf?: string, //TODO
     leafIdx?: number, //TODO
-    rootCnfg?: RootCnfg
+    rootCnfg?: RootCnfg,
+    metadata?: any,
 }
 
 interface AttrChangeInfo{