From 2d9b9db4e1e88cde8072c36d08268fd13e6b0c50 Mon Sep 17 00:00:00 2001
From: Hayato Ito In each algorithm in this section, the Window must be considered as if it were the parent node of the Document so that the Window also receives an event. When an event is dispatched in a shadow tree, its path either crosses the shadow trees or is terminated at the shadow root. One exception are the mutation events. The mutation event types must never be dispatched in a shadow tree. For the following events, scoped flag is initialized to true by default if the events are dispatched by the user agent:
- Upstream this section into relevant specs, instead of having a fixed list here.
-
+ In each algorithm in this section, the Window must be considered as if it were the parent node of the Document so that the Window also receives an event.
+ The event path calculation algorithm must be used to determine event path and must be equivalent to processing the following steps:
+ A trusted event's
- For a trusted event that has a
+ A trusted event's
- Let's re-use the same tree of trees used in the composition example section. Suppose that an event is dispatched on node
-
+ The event path calculation algorithm must be used to determine event path and must be equivalent to processing the following steps:
+
- It's worth pointing out that if we exclude all nodes which don't participate in the composed tree from the event path,
- the result would be equivalent to the inclusive ancestors of the node The composed event path calculation algorithm must be equivalent to processing the following steps:
- Note that the event path calculation algorithm is designed to achieve the following goals:
-
+ The event path trimming algorithm must be equivalent to processing the following steps:
+ A local event path for each component tree would be seen as:
-
+ The definitions of relative target and relative related target are specified later.
+
+ The motivation of the event path trimming algorithm is to avoid the appearance of spurious events, such as
- That means, if your concern is only one component tree, you can forget all other component trees.
- The event path would be seen as if the event happened only on the component tree you are focusing on.
- This is an important aspect in a sense that hosting a shadow tree doesn't have any effect to the local event path
- as long as the event is not stopped somewhere in the descendant trees.
-
- If you are a web author and your concern is only a document tree, this might be a good news because an event listener that is registered somewhere on the document tree
- would continue to work even when you attach a shadow root to an element in the document tree to enhance the element.
- At the same time, an author of a shadow tree also can receive an event which will happen on a node in the document tree, if the node, or its ancestor, is assigned to a slot in the shadow tree.
-
+ Let's re-use the same tree of trees used in the composition example section. Suppose that an event is dispatched on node
+ In the cases where event path is across multiple component trees, the event's information about the target of the event is adjusted in order to maintain encapsulation. Event retargeting is a process of computing relative targets for each ancestor of the node at which the event is dispatched. A relative target is a node that most accurately represents the target of a dispatched event at a given ancestor while maintaining the encapsulation.
+ It's worth pointing out that if we exclude all nodes which don't participate in the composed tree from the event path,
+ the result would be equivalent to the inclusive ancestors of the node The retargeting algorithm is used to determine relative targets and must be equivalent to processing the following steps:
+ Note that the event path calculation algorithm is designed to achieve the following goals:
+ The value of the The event target retargeting process must occur prior to dispatch of an event. A local event path for each component tree would be seen as:
+ Some events have a
- For instance, a
- The value of the
- The event relatedTarget retargeting process must occur prior to dispatch of an event.
-
+ That means, if your concern is only one component tree, you can forget all other component trees.
+ The event path would be seen as if the event happened only on the component tree you are focusing on.
+ This is an important aspect in a sense that hosting a shadow tree doesn't have any effect to the local event path
+ as long as the event is not stopped somewhere in the descendant trees.
+
+ If you are a web author and your concern is only a document tree, this might be a good news because an event listener that is registered somewhere on the document tree
+ would continue to work even when you attach a shadow root to an element in the document tree to enhance the element.
+ At the same time, an author of a shadow tree also can receive an event which will happen on a node in the document tree, if the node, or its ancestor, is assigned to a slot in the shadow tree.
+ The The value of the The The retargeting algorithm must be equivalent to processing the following steps:
- In cases where both
- Thus, event listeners for trusted events must not be invoked on a node for which the
+ Event retargeting is a process of computing relative targets for each ancestor of the node at which the event is dispatched.
+ The event target retargeting process must occur prior to dispatch of an event.
+ In other words, any DOM mutation occurred in an event listener does not have any affect on the result of retargeting process.
+
+ The motivation of retargeting is to maintain an encapsulation in the cases where event path is across multiple component trees.
+ The event's Some events have a
+ The value of the
+ The event relatedTarget retargeting process must occur prior to dispatch of an event.
+ The Suppose we have a user interface for a media controller, represented by this tree, composed of both document tree and the shadow trees. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the elements. Also, we will invent a fictional Let's have a user position their pointing device over the volume slider's thumb ( Per the retargeting algorithm, we should have the following set of ancestors and relative targets: After we dispatch the Let's see how the The node,
- The event path trimming algorithm must be used to trim the event path for a trusted event that has a
- For an untrusted event, the event path trimming algorithm is not used.
- Upon completion of the event dispatch, the Upon completion of the event dispatch, the Suppose we have a user interface for a media controller, represented by this tree, composed of both document tree and the shadow trees. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the elements. Also, we will invent a fictional Let's have a user position their pointing device over the volume slider's thumb ( Per the retargeting algorithm, we should have the following set of ancestors and relative targets: After we dispatch the Let's see how the
+ The mutation event types must never be dispatched in a shadow tree.
+ The node, Specifies the scoped flag of Specifies the relatedTargetScoped flag of Composition Example
Events
- Events that are not leaked into ancestor trees
-
-
-
-
- abort
error
select
change
load
reset
resize
scroll
selectstart
Event Paths
- scoped flag
-
-
-
-
-
-
-
-
-
-
-
-
- scoped flag
must be initialized to true
+ if the event is one of the following events: abort
, error
, select
, change
, load
, reset
,
+ resize
, scroll
and selectstart
.
+ relatedTarget
attribute, the event path would be trimmed. See the event path trimming algorithm, which is specified later.
- relatedTargetScoped flag
- relatedTargetScoped flag
must be initialized to true
+ if the event has a relatedTarget
property [[!DOM-Level-3-Events]].
+ Event Paths Example
+ Event Paths
- I
. The event path will be:
- [I, H, O, T, S, R, N, J, C, A]
(Window is omitted)
- I
in the composed tree.
-
+
+
+
+ relatedTargetScoped flag
is set and EVENT has a relatedTarget
property:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
+
+
+
+
+
+
-
-
+
-
-
-
- component tree
- Local Event Path
-
-
- document tree 1
- [I, H, C, A]
-
-
- shadow tree 1
- [O, N, J]
-
-
-
- shadow tree 2
- [T, S, R]
- mouseover
or mouseout
events, firing at the node in ancestor trees
+ in cases where both relatedTarget
and target
are part of the same shadow tree,
+ Event Paths Example
- Event Retargeting
+ I
. The event path will be:
+ [I, H, O, T, S, R, N, J, C, A]
(Window is omitted)
+ I
in the composed tree.
+
-
-
-
-
-
-
+
-
+ Nodes in the event path form a linear ancestor chain in each component tree. There are no branch points in each component tree.
-
- Event
object's target
attribute must be the result of the retargeting algorithm with the event's currentTarget
and target
as input.Retargeting
+ relatedTarget
relatedTarget
[[!DOM-Level-3-Events]] property, which holds a node that's not the event's target, but is related to the event.
+
+
-
+
+
+
+ component tree
+ Local Event Path
+
+
+ document tree 1
+ [I, H, C, A]
+
+
+ shadow tree 1
+ [O, N, J]
+
+
+
+ shadow tree 2
+ [T, S, R]
+ mouseover
event's relatedTarget
may hold the node from which the mouse has moved to event's target
. In the case where relatedTarget
is in a shadow tree, the conforming UAs must not leak its actual value outside of this tree.
- Event
object's relatedTarget
attribute must be the result of the retargeting algorithm with the event's currentTarget
and relatedTarget
as input. The result is called a relative related target.
- Retargeting Touch Events
+ Event Retargeting
- Touch
target
[[!TOUCH-EVENTS]] attribute must be adjusted in the same way as an event with a relatedTarget
. Each Touch
target
in the TouchList
returned from TouchEvent
touches()
, changedTouches()
and targetTouches()
must be the result of the retargeting algorithm with a current target and Touch
target
as input.Event
- target
RetargetingRetargeting Focus Events
+ Event
object's target
attribute must be the result of the retargeting algorithm with the event's currentTarget
and original target
value, before adjusted, as input. The result is called a relative target.
+ focus
, focusin
, blur
, and focusout
events must be treated in the same way as events with a relatedTarget
, where the corresponding node that is losing focus as a result of target
gaining focus or the node that is gaining focus, and thus causing the blurring of target
acts as the related target.Event Path Trimming
+
+
+
+
+
+
+
+
+
+
+
+
+ relatedTarget
and target
of a trusted event are part of the same shadow tree, the conforming UAs must stop events at the shadow root to avoid the appearance of spurious mouseover
and mouseout
events firing from the same node.
- target
and relatedTarget
are the same.
- target
might not be an unclosed node at some of nodes in the event path without retargeting.
+ A relative target is a unclosed node that most accurately represents the target of a dispatched event at each node in the event path.
+ Event
+
+ relatedTarget
RetargetingrelatedTarget
property, which holds a node that's not the event's target, but is related to the event.Event
object's relatedTarget
attribute must be the result of the retargeting algorithm with the event's currentTarget
and relatedTarget
as input.
+ The result is called a relative related target.
+ Touch Events Retargeting
+
+ Touch
target
[[!TOUCH-EVENTS]] attribute must be adjusted in the same way as an event with a relatedTarget
. Each Touch
target
in the TouchList
returned from TouchEvent
touches()
, changedTouches()
and targetTouches()
must be the result of the retargeting algorithm with a current target and Touch
target
as input.Event Retargeting Example
+
+ shadow-root
element to demarcate the shadow boundaries and represent shadow roots:
+ <div id="player">
+ <shadow-root id="player-shadow-root">
+ <div id="controls">
+ <button id="play-button">PLAY</button>
+ <input type="range" id="timeline">
+ <shadow-root id="timeline-shadow-root">
+ <div id="slider-thumb" id="timeline-slider-thumb"></div>
+ </shadow-root>
+ </input>
+ <div id="volume-slider-container">
+ <input type="range" id="volume-slider">
+ <shadow-root id="volume-shadow-root">
+ <div id="slider-thumb" id="volume-slider-thumb"></div>
+ </shadow-root>
+ </input>
+ </div>
+ </div>
+ </shadow-root>
+ </div>
+
+
+ #volume-slider-thumb
), thus triggering a mouseover
event on that node. For this event, let's pretend it has no associated relatedTarget
.
+
+
+
+
+
+
+
+ Ancestor
+ Relative Target
+
+
+
+ #player
+ #player
+
+
+ #player-shadow-root
+ #volume-slider
+
+
+ #controls
+ #volume-slider
+
+
+ #volume-slider-container
+ #volume-slider
+
+
+ #volume-slider
+ #volume-slider
+
+
+ #volume-shadow-root
+ #volume-slider-thumb
+
+
+
+ #volume-slider-thumb
+ #volume-slider-thumb
mouseover
event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline
+ (#timeline-slider-thumb
). This triggers both a mouseout
event for the volume slider thumb and the mouseover
event for the timeline thumb.relatedTarget
value of the volume thumb's mouseout
event is affected. For this event, the relatedTarget
is the timeline thumb (#timeline-slider-thumb
). Per the relatedTarget retargeting, we should have the following set of ancestors and adjusted related targets:
+
+
+
+
+
+
+
+ Ancestor
+ Relative Target
+ Relative Related Target
+
+
+
+ #player
+ #player
+ #player
+
+
+ #player-shadow-root
+ #volume-slider
+ #timeline
+
+
+ #controls
+ #volume-slider
+ #timeline
+
+
+ #volume-slider-container
+ #volume-slider
+ #timeline
+
+
+ #volume-slider
+ #volume-slider
+ #timeline
+
+
+ #volume-shadow-root
+ #volume-slider-thumb
+ #timeline
+
+
+
+ #volume-slider-thumb
+ #volume-slider-thumb
+ #timeline
#player
, has both target
and relatedTarget
being the same value (#player
), which means that we do not dispatch the event on this node and its ancestors.relatedTarget
attribute and
- must be equivalent to processing the following steps:
-
-
- target
and relatedTarget
are the same.
-
-
-
- Event Dispatch
- Event
object's target
and relatedTarget
must be to the highest ancestor's relative target. Since it is possible for a script to hold on to the Event
object past the scope of event dispatch, this step is necessary to avoid revealing the nodes in shadow trees.Event
object's target
and relatedTarget
must be to the highest ancestor's relative target and relative related target, respectively. Since it is possible for a script to hold on to the Event
object past the scope of event dispatch, this step is necessary to avoid revealing the nodes in shadow trees.Event Retargeting Example
-
- shadow-root
element to demarcate the shadow boundaries and represent shadow roots:
-<div id="player">
- <shadow-root id="player-shadow-root">
- <div id="controls">
- <button id="play-button">PLAY</button>
- <input type="range" id="timeline">
- <shadow-root id="timeline-shadow-root">
- <div id="slider-thumb" id="timeline-slider-thumb"></div>
- </shadow-root>
- </input>
- <div id="volume-slider-container">
- <input type="range" id="volume-slider">
- <shadow-root id="volume-shadow-root">
- <div id="slider-thumb" id="volume-slider-thumb"></div>
- </shadow-root>
- </input>
- </div>
- </div>
- </shadow-root>
-</div>
-
-
- #volume-slider-thumb
), thus triggering a mouseover
event on that node. For this event, let's pretend it has no associated relatedTarget
.
-
-
-
-
-
-
-
- Ancestor
- Relative Target
-
-
-
- #player
- #player
-
-
- #player-shadow-root
- #volume-slider
-
-
- #controls
- #volume-slider
-
-
- #volume-slider-container
- #volume-slider
-
-
- #volume-slider
- #volume-slider
-
-
- #volume-shadow-root
- #volume-slider-thumb
-
-
-
- #volume-slider-thumb
- #volume-slider-thumb
mouseover
event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline
- (#timeline-slider-thumb
). This triggers both a mouseout
event for the volume slider thumb and the mouseover
event for the timeline thumb.relatedTarget
value of the volume thumb's mouseout
event is affected. For this event, the relatedTarget
is the timeline thumb (#timeline-slider-thumb
). Per the relatedTarget retargeting, we should have the following set of ancestors and adjusted related targets:
-
-
+
-
-
-
- Ancestor
- Relative Target
- Adjusted related Target
-
-
-
- #player
- #player
- #player
-
-
- #player-shadow-root
- #volume-slider
- #timeline
-
-
- #controls
- #volume-slider
- #timeline
-
-
- #volume-slider-container
- #volume-slider
- #timeline
-
-
- #volume-slider
- #volume-slider
- #timeline
-
-
- #volume-shadow-root
- #volume-slider-thumb
- #timeline
-
-
-
- #volume-slider-thumb
- #volume-slider-thumb
- #timeline
#player
, has both target
and relatedTarget
being the same value (#player
), which means that we do not dispatch the event on this node and its ancestors.Extensions to
EventInit
DictionaryEvent
Event
Extensions to
Returns the scoped flag.
Event
Interface
+ Returns the relatedTargetScoped flag. +
+