Open bahrus opened 3 years ago
I love this proposal.
Potentially dumb question.
Why not just have the on
property take either a selector string, or a plain function that returns a boolean? For all the other use cases like media query, instanceof and the like could be static methods on the MountObserver
class if really needed. like so:
const observer = new MountObserver({
on: MountObserver.whereInstanceOf(MyCustomElement) // Returns a function that returns a boolean,
import: './my-element.js',
do: {
mount: ({localName}, {module}) => {
// ....
}
}
});
observer.observe(document);
They could be composed like so:
const observer = new MountObserver({
on: () => [() => false, MountObserver.whereInstanceOf(MyCustomElement)].every(condition => Boolean(condition())) ,
})
Also, why have a specific import
property, when that could be handled by the mount function?
Thanks.
Thanks, @doeixd!
You might be right, that for those conditions that are JS-based, which includes the custom condition checker, the instanceof check, and possibly the arrow-based import, that my argument about doing as much as possible in the low-level c++ code without context switching back and forth between c++ and JS doesn't apply, so we should look at the most powerful way we can chain those checks together. That seems like a good idea, I'll give it some thought.
The import statement, for me what is important is that we have these two highly overlapping concerns addressed:
I've updated this proposal to address one of the points raised by @doeixd .
Hello.
Another question. Why include the where
object when creating the observer? Can't all the functions defined there just as well be event listeners? It feels like there's two ways to do the same thing?
const observer = new MountObserver({
on: MountObserver.whereInstanceOf(MyCustomElement)
import: './my-element.js',
});
observer.addEventListener('mount', ({localName, module}) => {
// ....
})
observer.observe(document);
Good question, @doeixd,
Without a doubt, this proposal would need to be looked at closely by an expert who fully understands the inner workings of the browser, in order to help find the right balance between what would work performance wise, vs, perhaps, more flexibility.
Without that inside knowledge, I am making my best guess as to what would be effective to produce the most efficient result, perhaps erring on the side of making sure we don't sacrifice performance. If the expert comes back and says that "we can do this in a way that would empower the developer more, without sacrificing performance", then I'm all for taking advantage of that.
My mental model I'm applying is comparing the situation to that of middle tier code, that needs to query data from a remote database. A good rule of thumb that seems to have prevailed in that arena, is to do as much of the filtering as possible declaratively, with a single call, so that less information needs to cross through the wire back and forth. I think some of that may apply here, because I think most of the discovery of these conditions would be taking place within the c++ code, and I have seen people I consider to be experts bring up the issue of latency between c++ and JavaScript interactions (for example, in the context of JSON parsing ). Also, wonderful as events are, I think the power they provide does come at a bit of a performance sacrifice, compared to inline code and even chained functions, hence my thinking that we only want a single event that captures the most important question -- are all conditions satisfied or not?
Let me know if my response makes sense, or if I'm misunderstanding your question.
It gets murky in my mind if doing the check for whereInstanceOf could happen in the low level code, or the JavaScript layer. My best guess is low level, but it's no better than a coin toss, really. I'm going to keep that question open in my mind, still kind of mulling that one over.
At the risk of spinning another alternative proposal from this alternative proposal, the MountObserver
looks quite close to something like a SelectorObserver
- which could fire a callback whenever a given selector changes the amount of matched elements.
Something like this was also discussed in https://github.com/whatwg/html/issues/7039 where folks wanted to know when an element transitions from e.g. :dir(ltr)
to :dir(rtl)
, and a few ideas were discussed around matchSelector(the_selector).addEventListener('change', () => { .. })
. It seems like something more generic like this could benefit all of these use cases.
The MountObserver api.
Author: Bruce B. Anderson (with valuable feedback from @doeixd )
Issues / pr's / polyfill: mount-observer
Last Update: 2024-6-11
Benefits of this API
What follows is a far more ambitious alternative to the lazy custom element proposal. 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, to the HTML as it streams in. Libraries that take this approach include Corset and trans-render. The concept has been promoted by a number of 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, including, potentially, this one, which may be a similar duplicate to that one.
Does this api make the impossible possible?
There is quite a bit of functionality this proposal would open up, that is exceedingly difficult to polyfill reliably:
It is unclear how to use mutation observers to observe changes to custom state. The closest thing might be a solution like this, 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.
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.
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.
The amount of code necessary to accomplish these common tasks designed to improve the user experience is significant. Building it into the platform would potentially:
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 as well as binding from a distance in userland.
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:
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.
In fact, as we will see, where it makes sense, where we see examples that are strings, we will also allow for arrays of such strings. For example, the "on" key can point to an array of CSS selectors (and in this case the mount/dismount callbacks would need to provide an index of which one matched). I only recommend adding this complexity if what I suspect is true -- providing this support can reduce "context switching" between threads / memory spaces (c++ vs JavaScript), and thus improve performance. If multiple "on" selectors are provided, and multiple ones match, I think it makes sense to indicate the one with the highest specifier that matches. It would probably be helpful in this case to provide a special event that allows for knowing when the matching selector with the highest specificity changes for mounted elements.
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 "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:
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.
Previously, this proposal called for allowing arrow functions as well, thinking that could be a good interim way to support bundlers, as well as multiple imports. But the valuable input provided by doeixd makes me think that that interim support could more effectively be done by the developer in the do methods.
This proposal would also include support for JSON and HTML module imports.
Mount Observer Script Elements (MOSEs)
Following an approach similar to the speculation api, we can add a script element anywhere in the DOM:
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:
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), 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:
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 important additional features 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
It is important to note that "on" is a css query with no restrictions. So something like:
... would work.
This would allow developers to create "stylesheet" like capabilities.
Extra lazy loading
By default, the matches would be reported as soon as an element matching the criterion is found or added into the DOM, inside the node specified by rootNode.
However, we could make the loading even more lazy by specifying intersection options:
Media / container queries / instanceOf / custom checks
Unlike traditional CSS @import, CSS Modules don't support specifying different imports based on media queries. That can be another condition we can attach (and why not throw in container queries, based on the rootNode?):
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.
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 Subscribing can be done via: ```JavaScript observer.addEventListener('mount', e => { console.log({ matchingElement: e.matchingElement, module: e.module }); }); observer.addEventListener('dismount', e => { ... }); observer.addEventListener('disconnect', e => { ... }); observer.addEventListener('reconnect', e => { ... }); observer.addEventListener('reconfirm', e => { ... }); observer.addEventListener('exit', e => { ... }); observer.addEventListener('forget', e => { ... }); ``` ## Explanation of all states / events Normally, an element stays in its place in the DOM tree, but the conditions that the MountObserver instance is monitoring for can change for the element, based on modifications to the attributes of the element itself, or its custom state, or to other peer elements within the shadowRoot, if any, or window resizing, etc. As the element meets or doesn't meet all the conditions, the mountObserver will first call the corresponding mount/dismount callback, and then dispatch event "mount" or "dismount" according to whether the criteria are all met or not. The moment a MountObserver instance's "observe" method is called (passing in a root node), it will inspect every element within its subtree (not counting ShadowRoots), and then call the "mount" callback, and dispatch event "mount" for those elements that match the criteria. It will *not* dispatch "dismount" for elements that don't. If an element that is in "mounted" state according to a MountObserver instance is moved from one parent DOM element to another: 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 "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". ## 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 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. 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. 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. ## Attributes of 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 truth" for key features of the DOM element itself. We will refer to these attributes as "Source of Truth" attributes. Please don't read too much into the name. Whether the platform or custom element author developer chooses to make properties reflect to attributes, or attributes reflect to the properties, or some hybrid of some sort, is immaterial here. By invariably named, I mean the name will be the same in all Shadow DOM realms. Examples are many built-in global attributes, like lang, or contenteditable, or more specialized examples such as "content" for the meta tag. It could also include attributes of third party custom elements we want to enhance in a cross-cutting way. 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 (and vice versa). 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, there 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." 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. 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). ### 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: '*', observedAttrsWhenMounted: ['lang', 'contenteditable'] }); mo.addEventListener('attrChange', e => { console.log(e); // { // matchingElement, // attrChangeInfo:[{ // idx: 0, // name: 'lang' // isSOfTAttr: true, // oldValue: null, // newValue: 'en-GB', // }] // } }); ``` ### Help with parsing? This proposal is likely to evolve going forward, attempting to synthesize [separate ideas](https://github.com/WICG/webcomponents/issues/1045) for declaratively specifying how to interpret the attributes, parsing them so that they may be merged into properties of a class instance. But for now, such support is not part of this proposal (though we can see a glimpse of what that support might look like below). ### Custom Enhancements in userland [This proposal, support for (progressive) enhancement of built-in or third-party custom elements, could take quite a while to see the light of day, if ever](https://github.com/WICG/webcomponents/issues/1000). 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 (server-rendered) 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