Imperative shadow DOM distribution API

[domenic]

Writing down the stuff we talked about with @rniwa, @hayatoito, et al yesterday:

We should add a slotElement.reassign(...nodes) which reassigns the nodes.

How does this interact with the existing declarative distribution API? Maybe it just throws if the name="" attribute is specified at all; that seems nice and simple.

This API is not "perfect" because authors don't have enough hooks to call it as often as you might want. E.g. if you are trying to emulate details/summary, you will use a MutationObserver to watch for child node changes and do slotEl.reassign(theDetailsIFound). This happens at microtask timing, which is later than is done for the browser's native details/summary (people tell me that happens at style recalc timing).

But, it's pretty darn good!! I'm really excited about not putting slot="" attributes everywhere.

Any further thoughts?

[hayatoito]

Thanks for filing a new issue. Yup. I think that is feasible. Let me explore API design and its semantics deeper.

I am also wondering whether there is a use case which imperative API can't address, or not. Please let us know if there is. I hope this kind of imperative API can address the rest of the world.

[annevk]

Maybe it just throws if the name="" attribute is specified at all; that seems nice and simple.

That wouldn't address the elements potentially getting slotted elsewhere.

This will also require some careful study of the mutation algorithms (a fair number of which simply reset the assigned nodes).

[hayatoito]

Yup, my concern is that we might have to update a lot of places in DOM Standard, depending on when we should reset imperatively specified "assigned nodes". I am sure we have to reset it somewhere.

It requires careful study.

[domenic]

Thanks. I am afraid I am not enough of a shadow DOM/DOM spec expert to do that careful study. But, I will try to coordinate folks into answering the question of

I am also wondering whether there is a use case which imperative API can't address, or not. Please let us know if there is. I hope this kind of imperative API can address the rest of the world.

Hopefully if we can answer "yes", then this would be high-priority enough for you experts to help us write the spec?

[hayatoito]

One thing we should decide is how declarative APIs and imperative APIs interact each other. Mixing them is troublesome and would be the cause of a confusion.

One idea to make the situation much simpler is to get "opt-in" from web developers to allow them to use imperative APIs. The scope of 'opt-in' should be a shadow tree.

e.g.
attachShadow({ mode: 'open', slotting: 'manual' /* tentative parameter name */ });

In other words, declarative APIs and imperative APIs should be mutually exclusive in one shadow tree.
We don't mix them in the same shadow tree. That would make the situation much simpler, I think.

[annevk]

I don't think that necessarily helps, since if you have another shadow root that's not manual you'll still run into many of the same questions. Either way we'll have to deal with what happens when a node is already assigned.

cc @whatwg/components

[hayatoito]

I'll post a straw-man proposal, based on my idea.

[hayatoito]

I've posted my straw-man proposal here.

https://github.com/w3c/webcomponents/blob/gh-pages/proposals/Imperative-Shadow-DOM-Distribution-API.md

I hope this can capture most use cases, with minimum changes to DOM Standard, HTML Standard, and browser's engines.

[annevk]

So what happens if you have two (parallel) host elements and I manually assign children (its slotables) from the first host element to the shadow tree slots of the second? How does that not run into the issues I alluded to earlier?

[hayatoito]

They are never used in other shadow trees. Let me show an example.

host1
├──/shadowroot1 (slotting=manual)
│   └── slot1
└── A

host2
├──/shadowroot2 (slotting=manual)
│   └── slot2
└── B

slot2.assign([A]);
assert(slot2.assignedNodes() == []);

slot1.assign([A]);
assert(slot1.assignedNodes() == [A]);

shadowroot2.append(slot1);
assert(slot1.assignedNodes() == []);

shadowroot1.append(slot1);
assert(slot1.assignedNodes() == [A]);

[annevk]

But wasn't the point of the imperative API that you were not restricted on where the elements came from? At least, it sounds like you want them to be restricted to children of the host element? How does this follow from your document?

[hayatoito]

No. The bottom line is that assigned nodes should be the host's children. That shouldn't change. We don't relax this restriction.