Repository navigation
Figure out terminology for Shadow DOM that everyone agrees on #382
Description
Activity
Also, does Shadow DOM work without there being a document?
It should work, although the spec does not mention it clearly. That is the reason I can not define the terminology of component tree simply as either a document tree or shadow tree. I had to introduce the terminology of fragment tree and let the definition of component tree include a fragment tree as workaround.
A fragment tree is a node tree whose root node is, such as, the result of "document.createElement() but never inserted into a document".
Unfortunately, the spec had been unclear on this kind of topic. So I have introduced these terminologies recently.
The intention of the current spec is: Shadow DOM should work even for a composed tree (of component trees) whose root tree is not a document tree.
e.g.
- distribution, e.g. slot.getAssignedNodes() does correctly return the result, resolving the distribution.
- event dispatching - event dispatch go through the shadow tree.
In fact, Blink supports this.
AFAIR, there is no public discussion on this topic. Thus, it might be worth discussing that we really want to support this or not. A use case is not clear to me.
@esprehn, @sorvell, do you know a use case or the reason why we need to calculate distribution for such a composed tree whose root tree is not a document tree?
I guess it makes sense to support that given that we also support event dispatch in such cases. However, I think we should try to iterate on the terminology some more.
I think it would be better to define a component tree as a tree whose root node is either a Document object or a ShadowRoot object (i.e., whose root node implements the Component mixin). What you call component tree today is no different from "node tree", which makes it less of a useful term. (And instead of defining fragment tree say the algorithm operates on a node tree and that it doesn't have to be a component tree necessarily.)
I'm a little confused with what the specification calls "composed tree" today. When we talked about "composed tree" elsewhere I had what the specification calls the "flat tree" in mind. Is the "composed tree" language really necessary vs just talking about a node tree's hosted shadow trees or some such? I'm probably missing something significant here, but it seems variants of what the specification calls "flat tree" is what we'll need to define most features.
What you call component tree today is no different from "node tree"
Yeah, that's true.
Unfortunately, "component tree" become the same meaning of "node tree" at this commit:
963bce3I was aware of this fact when committing this change, however, I had no better idea and do not want to replace all "component tree" with "node tree" at that time.
I'm a little confused with what the specification calls "composed tree" today. When we talked about "composed tree" elsewhere I had what the specification calls the "flat tree" in mind.
Yes. That's painful. Actually, my colleague objected when I tried to re-use the "composed tree" as other meaning because it might be confusing. But I thought that we had to do it before upstreaming. I wanted to get rid of ugly terminology of "tree of trees", so I decided to re-use "composed tree" as "tree of trees" because "composed tree" became a good candidate to replace "tree of trees", give that we started to use "composed XXX", such as "composed child", "composed parent", to represent a relationship within a tree of trees, where distribution is not involved at all.
Is the "composed tree" language really necessary vs just talking about a node tree's hosted shadow trees or some such?
I do not expect that we have to use the "composed tree" frequently. In most cases, we can simply use "in a composed document" or "inserted into a composed document". That is enough and will cover the most cases.
We might get rid of this terminology, "composed tree", but this is very useful concept to define relevant algorithms. I do not care how we call it. "tree of trees", "composed tree" or something else, anything is okay to me. But I just needed a terminology to represent "tree of trees" so far.
I'm probably missing something significant here, but it seems variants of what the specification calls "flat tree" is what we'll need to define most features.
Good question, however, I am not sure which is used frequently: "composed XXX" vs "flat XXX".
- At least, we should use "composed XXX" where "in a document" is involved.
- e.g.
<script>runs only when "inserted into a composed document".
- e.g.
- CSS inheritance operate on "flat tree".
- Some of attributes operate on "flat tree": See http://w3c.github.io/webcomponents/spec/shadow/#attributes
Hmm. I can not tell which is used frequently. Do you want to use "composed XXX" as frequent words?
- At least, we should use "composed XXX" where "in a document" is involved.
Thank you for explaining it once more. Much appreciated.
Yeah, "composed" makes sense for
<script>I guess, since they should run even if they end up not being distributed. Events will use flat. Okay, I see why we want both. And then both also have the open/closed variants to complicate matters.So composed tree is a node tree including its hosted composed trees. The hosted trees of a composed tree will always be shadow trees. (You can imagine an even bigger tree that includes
<iframe>-like trees, so terminology-wise we should not name this something that would preclude that, I think.)A flat tree is the result of distributing the composed tree.
I'd like to have clearer terms, but I'm having a hard time coming up with them.
How about "slotted tree" instead of "composed tree"? "flattened tree" seems fine.
I do not worry much about the naming. These terminologies are used internally and we can rename them anytime without impacting web-facing APIs.
On the other hand, in term of interoperability, we should have a rough consensus on the following:
The intention of the current spec is: Shadow DOM should work even for a composed tree (of component trees) whose root tree is not a document tree.
Do we agree on this? See also #356 and #384 (comment) .
@sorvell, Polymer depends on this assumption, doesn't it?
I think it would be more consistent with the DOM if it did work. The DOM generally doesn't care what the root is for any particular feature to work or not work.
I just read the event path algorithm and it appears #382 (comment) is wrong. Events no longer use the flat tree (they did before, right?). So now if you have
<shadow-host><b/></shadow-host>and dispatch an event on<b>it will no longer go through the shadow tree, even if<b>is slotted/distributed.30 remaining items
I don't follow. A node tree's root node is either a Document, ShadowRoot, or something else, right? It's a shadow tree if the root node is a shadow tree, and document tree if its root node is a Document.
Yeah, a couple of facts:
- The root tree in a composed tree is not always a document tree.
- A non-root tree in a composed tree is always a shadow tree.
- A node tree which is not a shadow tree (such as DocumentFragment, a document tree and so on) is always the root tree in a composed tree.
e.g. The result of createElement('div'). That is a node tree that has only one node. We can not call it a document tree nor a shadow tree. This node tree itself is the root tree of a composed tree, which has only one node tree, by definition.
When we attach a shadow tree to this node, Shadow DOM should work in this composed tree, whose root tree is not a document tree.
Thus, "a document tree or a shadow tree" might not cover this case...
I've removed
component tree,primary component treeandfragment treeform the spec, and usenode treesalmost everywhere as a replacement.Thus, the followings are remaining contentious bits, right?
- composed tree (of node trees)
- composed {parent/child/ancestor/descendant}
Other ideas so far:
slotted tree- Introduce
connected/disconnected terminology? - shadow-host-including inclusive ancestor
Is there anything else?
Note that the spec has already defined the following terminologies, which we can use:
- in a composed document: as an alias for 'a node is an inclusive composed descendant of the root element of document element', which we can use for what 'connected/disconnected' means.
- shadow-host-including inclusive ancestor sounds the same meaning of inclusive composed ancestor, which the spec already defines.
I was trying to figure out how as e.g., an
<iframe>inside a shadow tree, you know your host element got inserted into a document. That led me to conclude that whatwg/dom#34 needs to be updated not only to notify descendants, but also nodes inside hosted shadow trees.I'm still trying to figure out what the best primitive is to have there (if we need a distinct notification next to parent change or if ancestor change is sufficient for all nodes, basically, I guess it doesn't matter much).
If we add shadow trees to the mix though that ancestor becomes a shadow-host-including inclusive ancestor (or a inclusive composed ancestor per current Shadow DOM terminology). Is that still okay?
If the host element was inserted into a closed shadow tree (whose shadow-host-including inclusive ancestor was a document), what kind of events would be fired on the custom elements inside host element's shadow tree? We can't really tell them the ancestor that got inserted since that would leak the closed shadow tree. @domenic have you looked at these events yet for custom elements?
(Maybe this should be a distinct issue. On the other hand, I'm just trying to figure out what all the various primitives are since they're not really documented at the moment. And hopefully once we have the primitives we can figure out suitable terminology for them.)
I think this is slowly being resolved by integration with the DOM Standard (and soon HTML Standard). If anyone has any concerns about that let me know.
Now, the spec is not using the composed {parent/child/ancestor/descendant} terminologies.
As the next step, I am now trying to avoid terminologies which are related to "composed tree of node trees". I am now rewriting the spec so that we do not need to use "composed tree".
I successfully updated the spec so that it does not depend on a concept of composed tree of node trees in normative sections.
I resolved almost all issues of the terminologies around:
- composed tree (of component trees (or node trees)) => No longer used in normative sections
- composed {parent/child/...} => Renamed to
shadow-including xxx - component tree => Removed, in favor of node trees
- fragment tree and primary component tree => Removed, in favor of node trees
- flat tree => Keep it
I think we can close this issue now.
If someone asks me what a "flat tree" or "composed tree" is when I am describing Shadow DOM to them, where should I link them to?
This thread is one of the top results on Google, at least for me (we know Google has bias on a per user basis so maybe the result is more likely to show up for me than someone else). Even in an incognito window, this thread is still the third result (for me, while in Oakland, CA).
The original document, for example https://www.w3.org/TR/2015/WD-shadow-dom-20151006/, was nice because it explained the topic more clearly and with visual diagrams.
But now, those documents are "outdated", and clicking forward to the new documents leads to a place that is far less helpful, does not include concise descriptions of the concepts, and does not include tree diagrams. It seems to be a regression in terms of helping people understand the concepts (like the original document did).
It seems virtually impossible for (especially new) people to learn (from official documents) what ShadowDOM is, and how the tree works and how it renders (f.e. rendering from the "flat tree").
Have I missed another document somewhere?
Reacted by Darien Maillet Valentine
It's not clear to me there is a difference.
Also, does Shadow DOM work without there being a document? There is a lot of terminology around there not being a document at the root. Is that to account for shadow trees in something created through
document.createElement()but never inserted? Will event dispatch there go through the shadow tree and such?