isEncapsulated naming

[domenic]

adae25b introduced the isEncapsulated flag to solve #61. It seems pretty great!

However, the naming is a bit weird.

• No other booleans on the platform that I know of use an "is" prefix. And, Event itself definitely does not: bubbles and cancelable are the models to follow here. So, encapsulated makes more sense.
• The term "encapsulation" is a new one that doesn't appear in other shadow-related APIs, as far as I know. Maybe there is something better? I cannot think of anything that is not overly verbose though (like "stopsAtShadowBoundaries"). But I thought others might have opinions, e.g. @annevk.

[travisleithead]

Well, there's precedent in "isTrusted", but I'd prefer the non-is-prefixed name :)

[hayatoito]

Yeah, I welcome any opinion. Actually, I've spent only a few minutes to give it a name. :)
I had a similar idea, stopsAtShadowRoot, but I chose isEncapsulated without a strong reason because I saw isTrusted in the spec, as Travis mentioned.

Because is-prefix is less-loved recently, I've changed it encapsulated at e91e7f0.

I think we still need a better idea. I don't want to expose a term of 'encapsulation' to the APIs.

The candidates:

• stopsAtShadowBoundaries
• stopsAtShadowRoot
• stopsPropagationAtShadowBoundaries
• Any better ideas.

What makes the naming difficult is that the event which is encapsulated doesn't always stop at a shadow root if distribution is involved in the event path.

e.g.
In the example of http://w3c.github.io/webcomponents/spec/shadow/#event-paths-example, if an event happens on L, the event doesn't stop at Q or N. It stops at J.

Event path in this case: [L, P, R, Q, O, N, K, J]

[annevk]

Isn't the semantic that the event is scoped to a subtree? scopedToSubtree or some such?

[travisleithead]

I like sticking to the semantic. If this is true, then +1 to @annevk

[hayatoito]

Thank you for the feedback.

I'm afraid that it might be ambiguous what subtree means here.
The term of subtree is widely used in the context of the node tree, IMO.

Here, we're scoping the event to sub-tree-of-trees.

[annevk]

scopedToDeepSubtree?

[hayatoito]

Thanks, however, I'm still reluctant to expose the term of subtree.

DeepSubtree sounds an attractive candidate, but I have a concern that developers have a wrong impression that the event is not dispatched to the parent node of the event.target by the name of subtree.

I welcome any wording which doesn't use subtree, though I have no idea. :(
If I am allowed to use a long name, I might name it:

• event.doesNotLeakIntoAncestorTrees
• event.scopedToInclusiveDescendantTrees.

I'm aware that both are not good name.

[annevk]

The second one of those seems somewhat reasonable. Maybe excludesAncestorTrees?

[rniwa]

I think we should add propagatesAcrossShadowBoundary or propagatesToShadowHost or some variant thereof which returns true for non-encapsulated event instead. encapsulated is ambiguous as to within what or against what it's encapsulated.

[annevk]

Propagates does not make sense for the capturing phase I think. But maybe includesShadowHost or some such if we want to avoid the tree terminology (which I think works too).

[rniwa]

True, includesShadowHost sounds good to me.

[hayatoito]

Thanks for the feedback. I appreciate it.
I like the bikeshed. :)

I thought the same thing, like a 'event.xxxShadowHost', though I don't remember 'XXX'.

However, I abandoned it because I thought that it might impress developers that event is dispatched to only the shadow host (+ ancestor chain in the current node tree, of course), excluding the ancestor nodes of the shadow host. Am I worrying too much?

In addition to that, includes should be used for event.path, IMO.
If it is used for the attributes of the event, that might be weird.

event.includesShadowHostInPath might be better, but it is too long. :(

[hayatoito]

At the same time, as @annevk mentioned, I want to avoid the tree terminology here as much as possible.
Most of the terminology are intended to be used internally in the spec. That's not intended to be exposed as the name of API. Using the tree terminology is a last resort.

[rniwa]

I don't think includesShadowHostInPath makes much sense because the path of an event isn't determined until an event is dispatched. I'm now leaning towards escapesShadowTree because that's what really this flag tells us. If we wanted the negation of that, I'd go with confinedToShadowTree.

I don't think there's any reason to avoid the word tree here.

[hayatoito]

Thanks. The term of the shadow tree is okay to use. I just wanted to avoid to use other term such as "ancestorTress", "inclusiveDescendantTrees" because it should be "ancestorNodeTrees", "inclusiveDescendantNodeTrees" in a strict meaning. I omitted "Node" in the spec.

Yeah, I prefer the naming which is false by default.

WDYT about scopedToShadowTree? Which is better between confinedToShadowTree or scopedToShadowTree? Is confined a familiar term for developers?

[hayatoito]

Otherwise, simply, how about scoped? Is this strange?

[rniwa]

I see. I think scopedToShadowTree is fine too. We could even go shorter and just say shadowScoped or shadowTreeScoped, or even scoped like you suggested. scoped sounds a little too generic but perhaps that isn't an issue because there isn't any other way for an event to be scoped like this.

[hayatoito]

Thanks. Let's change it to scoped and see how people will complain about it.