mount-observer 0.0.24 → 0.0.26

package/MountObserver.js

@@ -31,7 +31,7 @@ export class MountObserver extends EventTarget {
     }
     #calculatedSelector;
     #attrParts;
-    #fullListOfAttrs;
+    #fullListOfEnhancementAttrs;
     //get #attrVals
     async #selector() {
         if (this.#calculatedSelector !== undefined)
@@ -43,7 +43,7 @@ export class MountObserver extends EventTarget {
         const { getWhereAttrSelector } = await import('./getWhereAttrSelector.js');
         const info = await getWhereAttrSelector(whereAttr, withoutAttrs);
         const { fullListOfAttrs, calculatedSelector, partitionedAttrs } = info;
-        this.#fullListOfAttrs = fullListOfAttrs;
+        this.#fullListOfEnhancementAttrs = fullListOfAttrs;
         this.#attrParts = partitionedAttrs;
         this.#calculatedSelector = calculatedSelector;
         return this.#calculatedSelector;
@@ -119,7 +119,7 @@ export class MountObserver extends EventTarget {
             }
         }
         const rootMutObs = mutationObserverLookup.get(within);
-        const fullListOfAttrs = this.#fullListOfAttrs;
+        const fullListOfAttrs = this.#fullListOfEnhancementAttrs;
         rootMutObs.addEventListener('mutation-event', async (e) => {
             //TODO:  disconnected
             if (this.#isComplex) {
@@ -151,6 +151,7 @@ export class MountObserver extends EventTarget {
                                 const newValue = target.getAttribute(attributeName);
                                 const parts = this.#attrParts[idx];
                                 const attrChangeInfo = {
+                                    isSOfTAttr: false,
                                     oldValue,
                                     name: attributeName,
                                     newValue,
@@ -245,8 +246,9 @@ export class MountObserver extends EventTarget {
         }
     }
     readAttrs(match, branchIndexes) {
-        const fullListOfAttrs = this.#fullListOfAttrs;
+        const fullListOfAttrs = this.#fullListOfEnhancementAttrs;
         const attrChangeInfos = [];
+        const oldValue = null;
         if (fullListOfAttrs !== undefined) {
             const attrParts = this.#attrParts;
             for (let idx = 0, ii = fullListOfAttrs.length; idx < ii; idx++) {
@@ -257,17 +259,40 @@ export class MountObserver extends EventTarget {
                         continue;
                 }
                 const name = fullListOfAttrs[idx];
-                const oldValue = null;
                 const newValue = match.getAttribute(name);
                 attrChangeInfos.push({
                     idx,
+                    isSOfTAttr: false,
                     newValue,
                     oldValue,
                     name,
                     parts
                 });
             }
-            //this.dispatchEvent(new AttrChangeEvent(match, attrChangeInfos));
+        }
+        const { observedAttrsWhenMounted } = this.#mountInit;
+        if (observedAttrsWhenMounted !== undefined) {
+            for (const observedAttr of observedAttrsWhenMounted) {
+                const attrIsString = typeof observedAttr === 'string';
+                const name = attrIsString ? observedAttr : observedAttr.name;
+                let mapsTo;
+                let newValue = match.getAttribute(name);
+                if (!attrIsString) {
+                    const { customParser, instanceOf, mapsTo: mt, valIfNull } = observedAttr;
+                    if (instanceOf || customParser)
+                        throw 'NI';
+                    if (newValue === null)
+                        newValue = valIfNull;
+                    mapsTo = mt;
+                }
+                attrChangeInfos.push({
+                    isSOfTAttr: true,
+                    newValue,
+                    oldValue,
+                    name,
+                    mapsTo
+                });
+            }
         }
         return attrChangeInfos;
     }

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-22
+Last Update: 2024-5-27
 
 ## Benefits of this API
 
@@ -105,7 +105,7 @@ const observer = new MountObserver({
 observer.observe(document);
 ```
 
-Once again, the key can accept either a single import or it can also support multiple imports (via an array).
+Once again, the key can accept either a single import and it can also support multiple imports (via an array).
 
 The do event won't be invoked until all the imports have been successfully completed and inserted into the modules array.
 
@@ -113,7 +113,7 @@ 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 elements (MOSEs)
+## Mount Observer Script Elements (MOSEs)
 
 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:
 
@@ -136,7 +136,7 @@ Following an approach similar to the [speculation api](https://developer.chrome.
 </script>
 ```
 
-The objects modules, observer, mountedElements (array of weak refs) would be available as properties of the script element:
+The things that make this API work together, namely the "modules", "observer", and "mountedElements" (an array of an array of weak refs to elements that match all the criteria for the ith "on" selector) would be accessible as properties of the script element:
 
 ```JavaScript
 const {modules, observer, mountedElements, mountInit} = myMountObserver;
@@ -144,11 +144,11 @@ 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).
+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), but remember that the on criteria can be an array of selectors.
 
 ## 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:
+Inside a shadow root, we can plop a script element, also with type "mountobserver", optionally giving it the same id as above:
 
 ```html
 #shadowRoot
@@ -163,7 +163,7 @@ If no id is found in the parent ShadowRoot (or in the parent window if the shado
 
 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](#creating-frameworks-that-revolve-around-moses) of using these script elements later, but wanted to cover the highlights of this proposal before getting bogged down in some tedious logistics.
+We will come back to some important [additional features](#creating-frameworks-that-revolve-around-moses) of using these script elements later, but first we want to cover the highlights of this proposal, in order to give more context as to what kinds of functionality these MOSEs can provide.
 
 ## Binding from a distance
 
@@ -325,9 +325,9 @@ 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 of the Web, and they've survived multiple generations, where different philosophies have prevailed, so prepare yourself for some subtle discussion in what follows.
+Attributes of DOM elements are tricky.  They've been around since the get-go of the Web, and they've survived multiple eras of web development, where different philosophies have prevailed, so prepare yourself for some esoteric discussions 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:
+The MountObserver API provides explicit support for monitoring attributes.  There are two primary reasons for why it is important to provide this as part of the 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.
 
@@ -337,9 +337,11 @@ We want to be alerted by the discovery of elements adorned by these attributes,
 
 I think it is useful to divide [attributes](https://jakearchibald.com/2024/attributes-vs-properties/) that we would want to observe into two categories:
 
-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.
+1.  Invariably named, prefix-less, "top-level" attributes that serve as the "source of truth" for key features of the DOM element itself.  We will refer to these attributes as "Source of Truth" attributes.
 
-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! 
+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 JSON based attributes for custom elements. 
+
+Usually, that are 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 associated with the property 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.  We'll refer to these attributes as "Enhancement Attributes."
@@ -376,6 +378,7 @@ mo.addEventListener('attrChange', e => {
    //    attrChangeInfo:[{
    //       idx: 0,
    //       name: 'lang'
+   //       isSOfTAttr: true,
    //       oldValue: null,
    //       newValue: 'en-GB',
    //    }]
@@ -722,12 +725,12 @@ Often, we will want to define a large number of "mount observer script elements
 
 This is a problem space that [be-hive](https://github.com/bahrus/be-hive) is grappling with, and is used as an example for this section, to simply make things more concrete.  But we can certainly envision other "frameworks" that could leverage this feature for a variety of purposes, including other families of behaviors/enhancements, or "binding from a distance" syntaxes.  
 
-In particular, *be-hive* supports publishing [enhancements](https://github.com/bahrus/be-enhanced) that take advantage of the DOM filtering ability that the MountObserver provides, that "ties the knot" based on CSS matches in the DOM to behaviors/enhancements that we want to attach directly onto the matching elements.  *be-hive" seeks to take advantage of the inheritable infrastructure that MountObserver script elements provide, but we don't want to burden the developer with having to manually list all these configurations, we want it to happen automatically, only expecting manual intervention when we need some special customizations within a specific ShadowDOM scope.
+In particular, *be-hive* supports publishing [enhancements](https://github.com/bahrus/be-enhanced) that take advantage of the DOM filtering ability that the MountObserver provides, that "ties the knot" based on CSS matches in the DOM to behaviors/enhancements that we want to attach directly onto the matching elements.  *be-hive* seeks to take advantage of the inheritable infrastructure that MOSEs provide, but we don't want to burden the developer with having to manually list all these configurations, we want it to happen automatically, only expecting manual intervention when we need some special customizations within a specific ShadowDOM scope.
 
 To support this, we propose these highlights:
 
 1.  Adding a static "synthesize" method to the MountObserver api.  This would provide a kind of passage-way from the imperative api to the declarative one.  
-2.  As the Synthesize method is called repeatedly from different packages that work with that framework, it creates a cluster of MOSEs wrapped inside a custom element ("be-hive") that the framework developer authors.  It appends script elements with type="mountobserver" to the custom element instance sitting in the DOM, that dispatches events from the synthesizing custom element it gets appended to, so subscribers in child Shadow DOM's don't need to add a general mutation observer in order to know when parent shadow roots had a MOSE inserted that it needs to act on.  This allows the child Shadow DOM's to inherit (in this case) behaviors/enhancements from the parent Shadow DOM.
+2.  As the *synthesize* method is called repeatedly from different packages that work within that framework, it creates a cluster of MOSEs wrapped inside the "synthesizing" custom element ("be-hive") that the framework developer authors.  It appends script elements with type="mountobserver" to the custom element instance sitting in the DOM, that dispatches events from the synthesizing custom element it gets appended to, so subscribers in child Shadow DOM's don't need to add a general mutation observer in order to know when parent shadow roots had a MOSE inserted that it needs to act on.  This allows the child Shadow DOM's to inherit (in this case) behaviors/enhancements from the parent Shadow DOM.
 
 So framework developers can develop a bespoke custom element that inherits from the class "*Synthesizer*" that is part of this package / proposal, that is used to group families of MountObservers together.  
 

package/Synthesizer.js

@@ -43,6 +43,7 @@ export class Synthesizer extends HTMLElement {
     import(mose) {
         const { init, do: d, id, synConfig } = mose;
         const se = document.createElement('script');
+        se.type = 'mountobserver';
         se.init = { ...init };
         se.id = id;
         se.do = { ...d };
@@ -57,15 +58,15 @@ export class Synthesizer extends HTMLElement {
         const parentShadowRealm = host.getRootNode();
         const { localName } = this;
         const parentScopeSynthesizer = parentShadowRealm.querySelector(localName);
+        if (parentScopeSynthesizer === null)
+            throw 404;
         const { mountObserverElements } = parentScopeSynthesizer;
         for (const moe of mountObserverElements) {
             this.import(moe);
         }
-        if (parentScopeSynthesizer !== null) {
-            parentScopeSynthesizer.addEventListener(SynthesizeEvent.eventName, e => {
-                this.import(e.mountObserverElement);
-            });
-        }
+        parentScopeSynthesizer.addEventListener(SynthesizeEvent.eventName, e => {
+            this.import(e.mountObserverElement);
+        });
     }
     disconnectedCallback() {
         if (this.#mutationObserver !== undefined) {

package/getWhereAttrSelector.js

@@ -1,6 +1,6 @@
 export async function getWhereAttrSelector(whereAttr, withoutAttrs) {
-    const { hasBase, hasBranchIn, hasRootIn, isIn } = whereAttr;
-    const fullListOfAttrs = isIn !== undefined ? [...isIn] : [];
+    const { hasBase, hasBranchIn, hasRootIn } = whereAttr;
+    const fullListOfAttrs = [];
     const partitionedAttrs = [];
     if (hasBase !== undefined) {
         const hasRootInGuaranteed = hasRootIn || [{

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mount-observer",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
   "devDependencies": {
-    "@playwright/test": "1.39.0",
+    "@playwright/test": "1.44.1",
     "may-it-serve": "0.0.6"
   },
   "exports": {

package/types.d.ts

@@ -2,13 +2,23 @@
 
 export interface JSONSerializableMountInit{
     readonly on?: CSSMatch,
-    observedAttrsWhenMounted?: string[],
+    readonly observedAttrsWhenMounted?: (string | ObservedSourceOfTruthAttribute)[],
     readonly whereAttr?: WhereAttr,  
     readonly whereElementIntersectsWith?: IntersectionObserverInit,
     readonly whereMediaMatches?: MediaQuery,
     readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
 
 }
+
+export interface ObservedSourceOfTruthAttribute  {
+    name: string,
+    mapsTo?: string,
+    valIfNull?: any,
+    valIfFalsy?: any,
+    instanceOf?: any,
+    customParser?: (newValue: string | null, oldValue: string | null, instance: Element) => any
+}
+
 export interface MountInit extends JSONSerializableMountInit{
     
     readonly withTargetShadowRoot?: ShadowRoot, 
@@ -106,9 +116,11 @@ interface AttrParts{
 interface AttrChangeInfo{
     oldValue: string | null,
     newValue: string | null,
-    idx: number,
+    isSOfTAttr: boolean,
+    idx?: number,
     name: string,
-    parts: AttrParts,
+    parts?: AttrParts,
+    mapsTo?: string,
 }
 
 //#region mount event