mount-observer 0.0.6 → 0.0.7

package/MountObserver.js

@@ -12,10 +12,10 @@ export class MountObserver extends EventTarget {
     #isComplex;
     constructor(init) {
         super();
-        const { match, whereElementIntersectsWith, whereMediaMatches } = init;
+        const { on, whereElementIntersectsWith, whereMediaMatches } = init;
         let isComplex = false;
-        if (match !== undefined) {
-            const reducedMatch = match.replaceAll(':not(', '');
+        if (on !== undefined) {
+            const reducedMatch = on.replaceAll(':not(', '');
             isComplex = reducedMatch.includes(' ') || reducedMatch.includes(':');
         }
         this.#isComplex = isComplex;
@@ -31,17 +31,21 @@ export class MountObserver extends EventTarget {
     get #selector() {
         if (this.#calculatedSelector !== undefined)
             return this.#calculatedSelector;
-        const { match, attribMatches } = this.#mountInit;
-        const base = match || '*';
-        if (attribMatches === undefined)
+        const { on, whereAttr } = this.#mountInit;
+        const base = on || '*';
+        if (whereAttr === undefined)
             return base;
+        const { withFirstName, andQualifiers, withStemsIn } = whereAttr;
         const matches = [];
-        attribMatches.forEach(x => {
-            const { names } = x;
-            names.forEach(y => {
-                matches.push(`${base}[${y}]`);
-            });
-        });
+        const prefixLessMatches = andQualifiers === undefined ? [withFirstName]
+            : andQualifiers.map(x => `${withFirstName}-${x}`);
+        const stems = withStemsIn || ['data', 'enh', 'data-enh'];
+        for (const stem of stems) {
+            const prefix = typeof stem === 'string' ? stem : stem.stem;
+            for (const prefixLessMatch of prefixLessMatches) {
+                matches.push(`${prefix}-${prefixLessMatch}`);
+            }
+        }
         this.#calculatedSelector = matches.join(',');
         return this.#calculatedSelector;
     }
@@ -96,7 +100,7 @@ export class MountObserver extends EventTarget {
             const { mutationRecords } = e;
             const elsToInspect = [];
             //const elsToDisconnect: Array<Element> = [];
-            const doDisconnect = this.#mountInit.do?.onDisconnect;
+            const doDisconnect = this.#mountInit.do?.disconnect;
             for (const mutationRecord of mutationRecords) {
                 const { addedNodes, type, removedNodes } = mutationRecord;
                 //console.log(mutationRecord);
@@ -140,7 +144,7 @@ export class MountObserver extends EventTarget {
                     // this.#mountedList = this.#mountedList?.filter(x => x.deref() !== deletedElement);
                     this.#disconnected.add(deletedElement);
                     if (doDisconnect !== undefined) {
-                        doDisconnect(deletedElement, this);
+                        doDisconnect(deletedElement, this, {});
                     }
                     this.dispatchEvent(new DisconnectEvent(deletedElement));
                 }
@@ -161,7 +165,7 @@ export class MountObserver extends EventTarget {
     async #mount(matching, initializing) {
         //first unmount non matching
         const alreadyMounted = this.#filterAndDismount();
-        const onMount = this.#mountInit.do?.onMount;
+        const mount = this.#mountInit.do?.mount;
         const { import: imp, attribMatches } = this.#mountInit;
         for (const match of matching) {
             if (alreadyMounted.has(match))
@@ -186,8 +190,8 @@ export class MountObserver extends EventTarget {
                         break;
                 }
             }
-            if (onMount !== undefined) {
-                onMount(match, this, {
+            if (mount !== undefined) {
+                mount(match, this, {
                     stage: 'PostImport',
                     initializing
                 });
@@ -220,7 +224,7 @@ export class MountObserver extends EventTarget {
         }
     }
     async #dismount(unmatching) {
-        const onDismount = this.#mountInit.do?.onDismount;
+        const onDismount = this.#mountInit.do?.dismount;
         for (const unmatch of unmatching) {
             if (onDismount !== undefined) {
                 onDismount(unmatch, this, {});

package/README.md

@@ -10,13 +10,13 @@ Author:  Bruce B. Anderson
 
 Issues / pr's / polyfill:  [mount-observer](https://github.com/bahrus/mount-observer)
 
-Last Update: 2023-11-23
+Last Update: 2024-2-11
 
 ## Benefits of this API
 
-What follows is a far more ambitious alternative to the [lazy custom element proposal](https://github.com/w3c/webcomponents/issues/782).  The goals of the MountObserver api are more encompassing, and less focused on registering custom elements.  In fact, this proposal addresses numerous use cases in one api.  It is basically mapping common filtering conditions in the DOM, to common actions, like importing a resource, or progressively enhancing an element, or "binding from a distance".
+What follows is a far more ambitious alternative to the [lazy custom element proposal](https://github.com/w3c/webcomponents/issues/782).  The goals of the MountObserver api are more encompassing, and less focused on registering custom elements.  In fact, this proposal addresses numerous use cases in one api.  It is basically mapping common filtering conditions in the DOM, to mounting a "campaign" of some sort, like importing a resource, and/or progressively enhancing an element, and/or "binding from a distance".
 
-"Binding from a distance" 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.
+["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 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.
 
@@ -36,11 +36,10 @@ The amount of code necessary to accomplish these common tasks designed to improv
 
 1.  Give the developer a strong signal to do the right thing, by 
     1.  Making lazy loading of resource dependencies easy, to the benefit of users with expensive networks.
-    2.  Supporting "binding from a distance" that can allow SSR to provide common, shared data using the "DRY" philosophy, similar to how CSS can reduce the amount of repetitive styling instructions found inline within the HTML Markup.
-    3.  Supporting "progressive enhancement."
-2.  Allow numerous components / libraries to leverage this common functionality, which could potentially significantly reduce bandwidth.
-3.  Potentially by allowing the platform to do more work in the low-level (c/c++/rust?) code, without as much context switching into the JavaScript memory space, which may reduce cpu cycles as well.
-4.  To do the job right, polyfills really need to reexamine **all** the elements within the observed node for matches **anytime any element within the Shadow Root so much as sneezes (has attribute modified, changes custom state, etc)**, due to modern selectors such as the :has selector.  Surely, the platform has found ways to do this more efficiently?  
+    2.  Supporting "binding from a distance" that can set property values of elements in bulk as the HTML streams in.  For example, say a web page is streaming in HTML with thousands of input elements (say a long tax form).  We want to have some indication in the head tag of the HTML (for example) to make all the input elements read only as they stream through the page. With css, we could do similar things, for example set the background to red of all input elements. Why can't we do something similar with setting properties like readOnly, disabled, etc?  With this api, giving developers the "keys" to css filtering, so they can "mount a campaign" to apply common settings on them all feels like something that almost every web developer has mentally screamed to themselves "why can't I do that?", doesn't it? 
+    3.  Supporting "progressive enhancement" more effectively.
+2.  Potentially by allowing the platform to do more work in the low-level (c/c++/rust?) code, without as much context switching into the JavaScript memory space, which may reduce cpu cycles as well.  This is done by passing into the API substantial number of conditions, which can all be evaluated at a lower level, before surfacing up the developer "found one!".
+3.  As discussed earlier, to do the job right, polyfills really need to reexamine **all** the elements within the observed node for matches **anytime any element within the Shadow Root so much as sneezes (has attribute modified, changes custom state, etc)**, due to modern selectors such as the :has selector.  Surely, the platform has found ways to do this more efficiently?  
 
 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.
 
@@ -50,12 +49,12 @@ To specify the equivalent of what the alternative proposal linked to above would
 
 ```JavaScript
 const observer = new MountObserver({
-   match:'my-element',
+   on:'my-element',
    import: './my-element.js',
    do: {
-      onMount: ({localName}, {module}) => {
+      mount: ({localName}, {module}) => {
         if(!customElements.get(localName)) {
-            customElements.define(localName, module.default);
+            customElements.define(localName, module.MyElement);
         }
       }
    }
@@ -67,36 +66,41 @@ If no import is specified, it would go straight to do.* (if any such callbacks a
 
 This only searches for elements matching 'my-element' outside any shadow DOM.
 
-But the observe method can accept a shadowRoot, or a node inside a shadowRoot as well.
+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:
 
 ```JavaScript
 const observer = new MountObserver({
-   match: 'my-element',
+   on: 'my-element',
    import: async (matchingElement, {module}) => await import('./my-element.js');
 });
 observer.observe(myRootNode);
 ```
 
-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 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.
+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.
 
-This proposal would also include support for CSS, JSON, HTML module imports.  
-
-"match" is a css query, and could include multiple matches using the comma separator, i.e. no limitation on CSS expressions.
+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.
 
-<!-- As matches are found (for example, right away if matching elements are immediately found), the imports object would maintain a read-only array of weak references, along with the imported module:
+## Binding from a distance
+
+It is important to note that "on" is a css query with no restrictions.  So something like:
 
-```TypeScript
-interface MountContext {
-    weakReferences:  readonly WeakRef<Element>[];
-    module: any;
-}
+```JavaScript
+const observer = new MountObserver({
+   on:'div > p + p ~ span[class$="name"]',
+   do:{
+      mount: (matchingElement) => {
+         //attach some behavior or set some property value or add an event listener, etc.
+         matchingElement.textContent = 'hello';
+      }
+   }
+})
 ```
 
-This allows code that comes into being after the matching elements were found, to "get caught up" on all the matches. -->
+This would allow developers to create "stylesheet" like capabilities.
 
 
 ##  Extra lazy loading
@@ -107,7 +111,7 @@ However, we could make the loading even more lazy by specifying intersection opt
 
 ```JavaScript
 const observer = new MountObserver({
-   match: 'my-element',
+   on: 'my-element',
    whereElementIntersectsWith:{
       rootMargin: "0px",
       threshold: 1.0,
@@ -122,27 +126,31 @@ Unlike traditional CSS @import, CSS Modules don't support specifying different i
 
 ```JavaScript
 const observer = new MountObserver({
-   match: 'my-element',
+   on: 'div > p + p ~ span[class$="name"]',
    whereMediaMatches: '(max-width: 1250px)',
    whereSizeOfContainerMatches: '(min-width: 700px)',
    whereInstanceOf: [HTMLMarqueeElement],
    whereSatisfies: async (matchingElement, context) => true,
+   whereLangIn: ['en-GB'],
+   whereConnection:{
+      effectiveTypeIn: ["slow-2g"],
+   },
    import: ['./my-element-small.css', {type: 'css'}],
    do: {
-      onMount: ({localName}, {module}) => {
+      mount: ({localName}, {module}) => {
         ...
       },
-      onDismount: ...,
-      onDisconnect: ...,
-      onOutsideRootNode: ...,
-      onReconnect: ...,
-      onReconfirm: ...,
-      onOutOfScope: ...,
+      dismount: ...,
+      disconnect: ...,
+      reconnect: ...,
+      reconfirm: ...,
+      exit: ...,
+      forget: ...,
    }
 })
 ```
 
-Callbacks like we see above are useful for tight coupling, and probably are unmatched in terms of performance.  However, since these rules may be of interest to multiple parties, it is usesful to also provide the ability for multiple parties to subscribe to these css rules.  This can be done via:
+Callbacks like we see above are useful for tight coupling, and probably are unmatched in terms of performance.  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:
 
 ## Subscribing
 
@@ -155,21 +163,22 @@ observer.addEventListener('mount', e => {
       module: e.module
    });
 });
-
 observer.addEventListener('dismount', e => {
   ...
 });
-
-observer.addEventListener('reconnect', e => {
+observer.addEventListener('disconnect', e => {
   ...
 });
-observer.addEventListener('disconnect', e => {
+observer.addEventListener('reconnect', e => {
   ...
 });
 observer.addEventListener('reconfirm', e => {
   ...
 });
-observer.addEventListener('out-of-scope', e => {
+observer.addEventListener('exit', e => {
+  ...
+});
+observer.addEventListener('forget', e => {
   ...
 });
 ```
@@ -184,35 +193,162 @@ If an element that is in "mounted" state according to a MountObserver instance i
 
 1)  "disconnect" event is dispatched from the MountObserver instance the moment the mounted element is disconnected from the DOM fragment.
 2)  If/when the element is added somewhere else in the DOM tree, the mountObserver instance will dispatch event "reconnect", regardless of where. [Note:  can't polyfill this very easily]
-3)  If the mounted element is added outside the rootNode being observed, the mountObserver instance will dispatch event "outside-root-node", and the MountObserver instance will relinquish any further responsibility for this element.  Ideally this would also be dispatched when the platform garbage collects the element as well after all hard references are relinquished.
-4)  If the new place it was added remains within the original rootNode and remains mounted, the MountObserver instance dispatches event "reconfirmed".
-5)  If the element no longer satisfies the criteria of the MountObserver instance, the MountObserver instance will dispatch event "dismount".  
+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".  
+
+## A tribute to attributes
+
+Extra support is provided for monitoring attributes.  There are two primary reasons for needing to provide special support for attributes with this API:
 
-## Special support for observable attributes
+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.
 
-Extra support is provided for monitoring attributes.
+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 ObserveObservableAttributes API [WIP]
 
 Example:
 
 ```html
 <div id=div>
-   <span id=span></span>
+   <my-custom-element my-first-observed-attribute="hello"></my-custom-element>
 </div>
 <script type=module>
    import {MountObserver} from '../MountObserver.js';
    const mo = new MountObserver({
-      match: '#span',
-      attribMatches:[
+      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>
+```
+
+
+### Scenario 2 -- Custom Enhancements in userland
+
+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.
+
+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:
+
+```html
+<div id=div>
+   <section 
+      my-enhancement=greetings 
+      my-enhancement-first-aspect=hello 
+      my-enhancement-second-aspect=goodbye
+   ></section>
+</div>
+```
+
+Now suppose we are worried about namespace clashes, plus we want to serve environments where HTML5 compliance is a must.
+
+So we also want to recognize additional attributes that should map to these canonical attributes:
+
+We want to also support:
+
+```html
+<div id=div>
+   <section class=hello 
+      data-my-enhancement=greetings 
+      data-my-enhancement-first-aspect=hello 
+      data-my-enhancement-second-aspect=goodbye
+   ></section>
+</div>
+```
+
+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-first-aspect?  (Okay, with this particular example, the names are so long and generic it's unlikely, but who would ever use such a long, generic name in practice?)
+
+So let's say we want to insist that on custom elements, we must have the dat- prefix?
+
+And we want to support an alternative prefix to data, say enh-*, endorsed by [this proposal](https://github.com/WICG/webcomponents/issues/1000).
+
+Here's what the api provides:
+
+## Option 1 -- The carpal syndrome syntax
+
+```JavaScript
+import {MountObserver} from '../MountObserver.js';
+const mo = new MountObserver({
+   on: '*',
+   whereAttr:{
+      isIn: [
+         'data-my-enhancement',
+         'data-my-enhancement-first-aspect', 
+         'data-my-enhancement-second-aspect',
+         'enh-my-enhancement',
+         'enh-my-enhancement-first-aspect', 
+         'enh-my-enhancement-second-aspect',
          {
-            names: ['test-1']
+            name: 'my-enhancement',
+            builtIn: true
+         },
+         {
+            name: 'my-enhancement-first-attr',
+            builtIn: true
+         },
+         {
+            name: 'my-enhancement-second-aspect',
+            builtIn: true
          }
       ]
+      
+   }
+});
+```
+
+## Option 2 -- The DRY Way
+
+```JavaScript
+import {MountObserver} from '../MountObserver.js';
+const mo = new MountObserver({
+   on: '*',
+   whereAttr:{
+      withFirstName: 'my-enhancement',
+      andQualifiers: ['first-attr', 'second-attr', ''],
+      withStemsIn: ['data', 'enh', 'data-enh'],
+   }
+});
+```
+
+MountObserver supports both approaches
+
+```html
+<div id=div>
+   <section class=hello my-enhancement-first-attr="hello"></section>
+</div>
+<script type=module>
+   import {MountObserver} from '../MountObserver.js';
+   const mo = new MountObserver({
+      on: '*',
+      whereAttr:{
+         hasPrefixesIn: ['enh-', 'data-enh-'],
+         hasSuffixesIn:[
+            'my-enhancement-first-attr',
+            'my-enhancement-second-aspect'
+         ],
+         
+      }
    });
-   mo.addEventListener('attr-change', e => {
+   mo.addEventListener('observed-attr-change', e => {
       console.log(e);
       // {
+      //    matchingElement,
       //    attrChangeInfo:{
-      //       name: 'test-1',
+      //       fullName: 'data-enh-my-first-enhancement-attr',
+      //       suffix: 'my-first-enhancement-attr',
       //       oldValue: null,
       //       newValue: 'hello'
       //       idx: 0,
@@ -221,13 +357,12 @@ Example:
    });
    mo.observe(div);
    setTimeout(() => {
-      span.setAttribute('test-1', 'hello')
+      const myCustomElement = document.querySelector('my-custom-element');
+      myCustomElement.setAttribute('my-first-observed-attribute', 'good-bye');
    }, 1000);
 </script>
 ```
 
-
-
 ## Preemptive downloading
 
 There are two significant steps to imports, each of which imposes a cost:  
@@ -243,11 +378,11 @@ So for this we add option:
 
 ```JavaScript
 const observer = new MountObserver({
-   match: 'my-element',
+   on: 'my-element',
    loading: 'eager',
    import: './my-element.js',
    do:{
-      onMount: (matchingElement, {module}) => customElements.define(module.MyElement)
+      mount: (matchingElement, {module}) => customElements.define(module.MyElement)
    }
 })
 ```

package/package.json

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

package/types.d.ts

@@ -1,17 +1,25 @@
 export interface MountInit{
-    readonly match?: CSSMatch,
-    readonly attribMatches?: Array<AttribMatch>,  
+    readonly on?: CSSMatch,
+    readonly attribMatches?: Array<AttribMatch>,
+    readonly whereAttr?: {
+        withFirstName: string,
+        andQualifiers?: Array<string>,
+        withStemsIn?: Array<string | {
+            stem: string,
+            context: 'BuiltIn' | 'CustomElement'
+        }>,
+    },  
     readonly whereElementIntersectsWith?: IntersectionObserverInit,
     readonly whereMediaMatches?: MediaQuery,
     readonly whereInstanceOf?: Array<typeof Node>, //[TODO] What's the best way to type this?,
     readonly whereSatisfies?: PipelineProcessor<boolean>,
     readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
     readonly do?: {
-        readonly onMount?: PipelineProcessor,
-        readonly onDismount?: PipelineProcessor,
-        readonly onDisconnect?: PipelineProcessor,
-        readonly onReconfirmed?: PipelineProcessor,
-        readonly onOutsideRootNode?: PipelineProcessor,
+        readonly mount?: PipelineProcessor,
+        readonly dismount?: PipelineProcessor,
+        readonly disconnect?: PipelineProcessor,
+        readonly reconfirm?: PipelineProcessor,
+        readonly exit?: PipelineProcessor,
     }
     // /**
     //  * Purpose -- there are scenarios where we may only want to affect changes that occur after the initial