mount-observer 0.0.21 → 0.0.23

package/MountObserver.js

@@ -5,7 +5,7 @@ export class MountObserver extends EventTarget {
     #mountInit;
     //#rootMutObs: RootMutObs | undefined;
     #abortController;
-    #mounted;
+    mountedElements;
     #mountedList;
     #disconnected;
     //#unmounted: WeakSet<Element>;
@@ -25,7 +25,7 @@ export class MountObserver extends EventTarget {
             throw 'NI'; //not implemented
         this.#mountInit = init;
         this.#abortController = new AbortController();
-        this.#mounted = new WeakSet();
+        this.mountedElements = new WeakSet();
         this.#disconnected = new WeakSet();
         //this.#unmounted = new WeakSet();
     }
@@ -181,6 +181,23 @@ export class MountObserver extends EventTarget {
         }, { signal: this.#abortController.signal });
         await this.#inspectWithin(within, true);
     }
+    static synthesize(within, customElement, mose) {
+        mose.type = 'mountobserver';
+        const name = customElements.getName(customElement);
+        if (name === null)
+            throw 400;
+        let instance = within.querySelector(name);
+        if (instance === null) {
+            instance = new customElement();
+            if (within === document) {
+                within.head.appendChild(instance);
+            }
+            else {
+                within.appendChild(instance);
+            }
+        }
+        instance.appendChild(mose);
+    }
     #confirmInstanceOf(el, whereInstanceOf) {
         for (const test of whereInstanceOf) {
             if (el instanceof test)
@@ -196,7 +213,7 @@ export class MountObserver extends EventTarget {
         for (const match of matching) {
             if (alreadyMounted.has(match))
                 continue;
-            this.#mounted.add(match);
+            this.mountedElements.add(match);
             if (imp !== undefined) {
                 switch (typeof imp) {
                     case 'string':

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-21
+Last Update: 2024-5-22
 
 ## Benefits of this API
 
@@ -30,8 +30,6 @@ There is quite a bit of functionality this proposal would open up, that is excee
 
 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.
 
 ###  Most significant use cases.
@@ -113,7 +111,57 @@ Previously, this proposal called for allowing arrow functions as well, thinking
 
 This proposal would also include support for JSON and HTML module imports. 
 
+## MountObserver script element
+
+Following an approach similar to the [speculation api](https://developer.chrome.com/blog/speculation-rules-improvements), we can add a script element anywhere in the DOM:
+
+```html
+<script type="mountobserver" id=myMountObserver  onmount="
+   const {matchingElement} = event;
+   const {localName} = matchingElement;
+   if(!customElements.get(localName)) {
+      customElements.define(localName, modules[1].MyElement);
+   }
+   observer.disconnect();
+">
+{
+   "on":"my-element",
+   "import": [
+      ["./my-element-small.css", {type: "css"}],
+      "./my-element.js",
+   ]
+}
+</script>
+```
+
+The objects modules, observer, mountedElements (array of weak refs) would be available as properties of the script element:
+
+```JavaScript
+const {modules, observer, mountedElements, mountInit} = myMountObserver;
+```
+
+The "scope" of the observer would be the ShadowRoot containing the script element (or the document outside Shadow if placed outside any shadow DOM, like in the head element).
+
+No arrays of settings would be supported within a single tag (as this causes issues as far as supporting a single onmount, ondismount, etc event attributes).
 
+## Shadow Root inheritance
+
+Inside a shadow root, we can plop a script element, also with type mountobserver, optionally giving it the same id as above:
+
+```html
+#shadowRoot
+<script id=myMountObserver type=mountobserver>
+{
+   "on":"your-element"
+}
+</script>
+```
+
+If no id is found in the parent ShadowRoot (or in the parent window if the shadow root is at the top level), then this becomes a new set of rules to observe.
+
+But if a matching id is found, then the values from the parent script element get merged in with the one in the child, with the child settings, including the event handling attributes. 
+
+We will come back to some [additional features](#mountobserver-script-element-minutiae) of using these script elements later, but wanted to cover the highlights of this proposal before getting bogged down in some tedious logistics.
 
 ## Binding from a distance
 
@@ -275,38 +323,48 @@ The alternative to providing this feature, which I'm leaning towards, is to just
 
 ## A tribute to attributes
 
+Attributes of DOM elements are tricky.  They've been around since the get-go, and they've survived multiple generations of the Web where different philosophies have prevailed, so prepare yourself for some subtle discussion in what follows.
+
 Extra support is provided for monitoring attributes.  There are two primary reasons for needing to provide special support for attributes with this API:
 
 Being that for both custom elements, as well as (hopefully) [custom enhancements](https://github.com/WICG/webcomponents/issues/1000) we need to carefully work with sets of "owned" [observed](https://github.com/WICG/webcomponents/issues/1045) attributes, and in some cases we may need to manage combinations of prefixes and suffixes for better name-spacing management, creating the most effective css query becomes challenging.
 
 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.
 
-## A key attribute of attributes
-
-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:
+## Attributes of attributes
 
-1.  Invariably named, prefix-less, "top-level" attributes that serve as the "source of the truth".
+I think it is useful to divide [attributes](https://jakearchibald.com/2024/attributes-vs-properties/) that we would want to observe into two categories:
 
-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).
+1.  Invariably named, prefix-less, "top-level" attributes that serve as the "source of the truth" for key features of the DOM element itself.  We will refer to these attributes as "Source of Truth" attributes.
 
-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.  
+Examples are many built-in global attributes, like lang, or contenteditable, or more specialized examples such as "content" for the meta tag.  I think in the vast majority of cases, setting the property values corresponding to these attributes results in directly reflecting those property values to the attributes.  There are exceptions, especially for non-string attributes like the checked property of the input element / type=checkbox. 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.  And some attributes (like the microdata attributes such as itemprop) don't even have properties that they pair with! 
+  
 
-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.
+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'll refer to these attributes as "Enhancement Attributes."
 
 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.
 
+> [!NOTE]
+> The most important reason for pointing out this distinction is this:  "Source of Truth" attributes will only be *observed*, and will **not** trigger mount/unmount states unless they are part of the "on" selector string. And unlike all the other "where" conditions this proposal supports, the where clauses for the "Enhancement Attributes" are "one-way" -- they trigger a "mount" event / callback, followed by the ability to observe the stream of changes (including removal of those attributes), but they never trigger a "dismount". 
+
+### Counterpoint
+
+Does it make sense to even support "Source of Truth" attributes in a "MountObserver" api, if they have no impact on mounted state?  
+
+We think it does, because some Enhancement Attributes will need to work in conjunction with Source of Truth attributes, in order to provide the observer a coherent picture of the full state of the element.
 
-### Attributes that are the "source of truth"
+This realization (hopefully correct) struck me while trying to implement a [userland implementation](https://github.com/bahrus/be-intl) of [this proposal](https://github.com/whatwg/html/issues/9294). 
 
-So for the first scenario, we can specify attributes to listen for as follows:
+
+### Source of Truth Attributes
+
+Let's focus on the first scenario.  It doesn't make sense to use the word "where" for these, because we don't want these attributes to affect our mount/dismount state
 
 ```JavaScript
 import {MountObserver} from 'mount-observer/MountObserver.js';
 const mo = new MountObserver({
    on: '*',
-   whereAttr:{
-      isIn: ['lang', 'contenteditable']
-   }
+   observedAttrsWhenMounted: ['lang', 'contenteditable']
 });
 
 mo.addEventListener('attrChange', e => {
@@ -657,3 +715,57 @@ This proposal (and polyfill) also supports the option to utilize ShadowDOM / slo
 
 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.
 
+## MountObserver script element minutiae
+
+Often, we will want to define a large number of "mount observers" programmatically, and we need it to be done in a generic way.  This is a problem space that [be-hive](https://github.com/bahrus/be-hive) is grappling with.  In particular, we want to publish enhancements that take advantage of this inheritable infrastructure of declarative configuration, but we don't want to burden the developer with having to manually list all these configurations, we want it to happen automatically.
+
+To support this, we propose these highlights:
+
+1.  Adding a "synthesize" method to the MountObserver api, only if observing a shadowRoot (or the top level document).  This would provide a kind of passage way from the imperative api to the declarative one.  
+2.  Synthesize method appends a script element of type MountObserver, that dispatches event from the synthesizing custom element it gets appended to, so subscribers don't need to add a general mutation observer in order to know when parent shadow roots had a MountObserver script tag inserted.
+
+
+So developers can develop a custom element, used to group families of MountObservers together.  
+
+If one inspects the DOM, one would see grouped (already "parsed") MountObservers, like so:
+
+```html
+<be-hive>
+   <script type=mountobserver id=be-searching></script>
+   <script type=mountobserver id=be-counted></script>
+</be-hive>
+```
+
+But the developer would not need to set these up automatically.
+
+Instead, the framework developer would define a custom element that inherits from base class that this proposal/polyfill provides.
+
+Let's say the framework developer creates an extending Web Component with constructor:  BeHive.
+
+Then rather than invoking:
+
+```JavaScript
+mountObserver.observe(rootNode);
+```
+
+we would invoke:
+
+```JavaScript
+mountObserver.synthesize(rootNode, BeHive, mountObserverScriptElement)
+```
+
+The MountObserver api would:
+
+1.  Use [customElements.getName](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/getName) to get the name of the custom element (say it is 'be-hive').
+2.  Search for a be-hive tag inside the root node (with special logic for the "head" element).  If not found, create it.
+3.  Place the script element inside.
+
+
+Then in our shadowroot, rather than adding a script type=mountobserver for every single mount observer we want to inherit, we could reference the group via simply:
+
+```html
+<be-hive></be-hive>
+```
+
+
+

package/Synthesizer.js

@@ -0,0 +1,91 @@
+import { MountObserver } from './MountObserver.js';
+export class Synthesizer extends HTMLElement {
+    #mutationObserver;
+    mountObserverElements = [];
+    mutationCallback(mutationList) {
+        for (const mutation of mutationList) {
+            const { addedNodes } = mutation;
+            for (const node of addedNodes) {
+                if (!(node instanceof HTMLScriptElement) || node.type !== 'mountobserver')
+                    continue;
+                const mose = node;
+                this.mountObserverElements.push(mose);
+                this.activate(mose);
+                const e = new SynthetizeEvent(mose);
+                this.dispatchEvent(e);
+            }
+        }
+    }
+    connectedCallback() {
+        this.hidden = true;
+        const init = {
+            childList: true
+        };
+        this.querySelectorAll('script[type="mountobserver"]').forEach(s => {
+            const mose = s;
+            this.mountObserverElements.push(mose);
+            this.activate(mose);
+        });
+        this.#mutationObserver = new MutationObserver(this.mutationCallback.bind(this));
+        this.#mutationObserver.observe(this, init);
+        this.inherit();
+    }
+    activate(mose) {
+        const { init, do: d, id } = mose;
+        const mi = {
+            do: d,
+            ...init
+        };
+        const mo = new MountObserver(mi);
+        mose.observer = mo;
+        mo.observe(this.getRootNode());
+    }
+    import(mose) {
+        const { init, do: d, id, synConfig } = mose;
+        const se = document.createElement('script');
+        se.init = { ...init };
+        se.id = id;
+        se.do = { ...d };
+        se.synConfig = { ...synConfig };
+        this.appendChild(se);
+    }
+    inherit() {
+        const rn = this.getRootNode();
+        const host = rn.host;
+        if (!host)
+            return;
+        const parentShadowRealm = host.getRootNode();
+        const { localName } = this;
+        const parentScopeSynthesizer = parentShadowRealm.querySelector(localName);
+        const { mountObserverElements } = parentScopeSynthesizer;
+        for (const moe of mountObserverElements) {
+            this.import(moe);
+        }
+        if (parentScopeSynthesizer !== null) {
+            parentScopeSynthesizer.addEventListener(SynthetizeEvent.eventName, e => {
+                this.import(e.mountObserverElement);
+            });
+        }
+    }
+    disconnectedCallback() {
+        if (this.#mutationObserver !== undefined) {
+            this.#mutationObserver.disconnect();
+        }
+        for (const mose of this.mountObserverElements) {
+            mose.observer.disconnect(this.getRootNode());
+        }
+    }
+}
+// https://github.com/webcomponents-cg/community-protocols/issues/12#issuecomment-872415080
+/**
+ * The `mutation-event` event represents something that happened.
+ * We can document it here.
+ */
+export class SynthetizeEvent extends Event {
+    mountObserverElement;
+    static eventName = 'synthesize';
+    constructor(mountObserverElement) {
+        super(SynthetizeEvent.eventName);
+        this.mountObserverElement = mountObserverElement;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mount-observer",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
@@ -10,7 +10,8 @@
   },
   "exports": {
     ".": "./MountObserver.js",
-    "./MountObserver.js": "./MountObserver.js"
+    "./MountObserver.js": "./MountObserver.js",
+    "./Synthesizer.js": "./Synthesizer.js"
   },
   "files": [
     "*.js",

package/types.d.ts

@@ -1,20 +1,19 @@
-export interface MountInit{
+//import { MountObserver } from "./MountObserver";
+
+export interface JSONSerializableMountInit{
     readonly on?: CSSMatch,
-    //readonly attribMatches?: Array<AttribMatch>,
-    readonly withTargetShadowRoot?: ShadowRoot, 
     readonly whereAttr?: WhereAttr,  
     readonly whereElementIntersectsWith?: IntersectionObserverInit,
     readonly whereMediaMatches?: MediaQuery,
+    readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
+
+}
+export interface MountInit extends JSONSerializableMountInit{
+    
+    readonly withTargetShadowRoot?: ShadowRoot, 
     readonly whereInstanceOf?: Array<{new(): Element}>,
     readonly whereSatisfies?: PipelineProcessor<boolean>,
-    readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
-    readonly do?: {
-        readonly mount?: PipelineProcessor,
-        readonly dismount?: PipelineProcessor,
-        readonly disconnect?: PipelineProcessor,
-        readonly reconfirm?: PipelineProcessor,
-        readonly exit?: PipelineProcessor,
-    }
+    readonly do?: MountObserverCallbacks
     // /**
     //  * Purpose -- there are scenarios where we may only want to affect changes that occur after the initial 
     //  * server rendering, so we only want to mount elements that appear 
@@ -22,6 +21,14 @@ export interface MountInit{
     // readonly ignoreInitialMatches?: boolean,
 }
 
+export interface MountObserverCallbacks{
+    readonly mount?: PipelineProcessor,
+    readonly dismount?: PipelineProcessor,
+    readonly disconnect?: PipelineProcessor,
+    readonly reconfirm?: PipelineProcessor,
+    readonly exit?: PipelineProcessor,
+}
+
 export interface RootCnfg{
     start: string,
     context: 'BuiltIn' | 'CustomElement' | 'Both'
@@ -59,6 +66,7 @@ export interface IMountObserver {
     observe(within: Node): void;
     disconnect(within: Node): void;
     module?: any;
+    mountedElements: WeakSet<Element>;
 } 
 
 export interface MountContext{
@@ -161,3 +169,18 @@ export interface AddLoadEventListener{
 }
 //#endregion
 
+//#region MountObserver Script Element
+export interface MountObserverScriptElementEndUserProps<TSynConfig=any>{
+    init: JSONSerializableMountInit;
+    observer: IMountObserver;
+    do: MountObserverCallbacks;
+    synConfig: TSynConfig;
+}
+export interface MountObserverScriptElement<TSynConfig=any> 
+    extends HTMLScriptElement, MountObserverScriptElementEndUserProps<TSynConfig>{
+
+}
+//#endregion
+
+
+