Skip to content

Commit

Permalink
Shadow: define Event's composedPath()
Browse files Browse the repository at this point in the history 
Fixes #242. Also reverts WICG/webcomponents#432 as it appears to no longer be needed. If we ever have an event path that starts with a non-node and ends with a node we'll have to add that complexity back.

(The reason it is named composedPath() is because deepPath() and various other names were no longer viable after Chrome's initial experiment. See the various issues.)
  • Loading branch information
@annevk
annevk committed May 12, 2016
1 parent 6e1b038 commit 58b19e4
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 1 deletion.
36 changes: 36 additions & 0 deletions dom.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -613,6 +613,7 @@ interface Event {
readonly attribute DOMString type;
readonly attribute EventTarget? target;
readonly attribute EventTarget? currentTarget;
sequence<EventTarget> composedPath();

const unsigned short NONE = 0;
const unsigned short CAPTURING_PHASE = 1;
Expand Down Expand Up @@ -671,6 +672,12 @@ list of tuples, each of which consists of an <b>item</b> (an {{EventTarget}} obj
<dd>Returns the object whose <a>event listener</a>'s <b>callback</b> is currently being
invoked.

<dt><code><var>event</var> . {{Event/composedPath()}}</code>
<dd>Returns the <b>item</b> objects of <var>event</var>'s <a for=Event>path</a> (objects on which
listeners will be invoked), except for any <a>nodes</a> in <a>shadow trees</a> of which the
<a for=/>shadow root</a>'s <a for=ShadowRoot>mode</a> is "<code>closed</code>" that are not
reachable from <var>event</var>'s {{Event/currentTarget}}.

<dt><code><var>event</var> . {{Event/eventPhase}}</code>
<dd>Returns the <a>event</a>'s phase, which is one of {{Event/NONE}},
{{Event/CAPTURING_PHASE}},
Expand Down Expand Up @@ -733,6 +740,29 @@ attributes must return the values they were initialized to. When an
<a>event</a> is created the attributes must be
initialized to null.

<p>The <dfn method for=Event><code>composedPath()</code></dfn> method, when invoked, must run these
steps:

<ol>
<li><p>Let <var>composedPath</var> be a new empty list.

<li><p>Let <var>currentTarget</var> be <a>context object</a>'s <code for=Event>currentTarget</code>
attribute value.

<li>
<p>For each <var>tuple</var> in <a>context object</a>'s <a for=Event>path</a>:

<ol><li><p>If <var>currentTarget</var> is a <a>node</a> and <var>tuple</var>'s <b>item</b> is an
<a>unclosed node</a> of <var>currentTarget</var>, or <var>currentTarget</var> is <em>not</em> a
<a>node</a>, then append <var>tuple</var>'s <b>item</b> to <var>composedPath</var>.</p></li></ol>

<li><p>Return <var>composedPath</var>.
</ol>

<p class="note no-backref">This algorithm assumes that when the <var>target</var> argument to the
<a>dispatch</a> algorithm is not a <a>node</a>, none of the tuples in <var>event</var> argument's
eventual <a for=Event>path</a> will contain a <a>node</a> either.

The <dfn attribute for=Event><code>eventPhase</code></dfn>
attribute must return the value it was initialized to, which must be one of
the following:
Expand Down Expand Up @@ -5476,6 +5506,12 @@ is an object or one of its <a>shadow-including descendants</a>.
<dfn export id=concept-shadow-including-inclusive-ancestor>shadow-including inclusive ancestor</dfn>
is an object or one of its <a>shadow-including ancestors</a>.

<p>A <a>node</a> <var>A</var> is an <dfn export id=concept-unclosed-node>unclosed node</dfn> of a
<a>node</a> <var>B</var>, if <var>A</var>'s <a for=tree>root</a> is a
<a>shadow-including inclusive ancestor</a> of <var>B</var>, or <var>A</var>'s <a for=tree>root</a>
is a <a for=/>shadow root</a> whose <a for=ShadowRoot>mode</a> is "<code>open</code>" and
<a for=DocumentFragment>host</a> is an <a>unclosed node</a> of <var>B</var>.

<hr>

<p class="XXX">For now you can find more information about this object in
Expand Down
29 changes: 28 additions & 1 deletion dom.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
<p data-fill-with="logo"><a class="logo" href="https://whatwg.org/"> <img alt="WHATWG" height="100" src="https://resources.whatwg.org/logo-dom.svg"> </a> </p>
<hgroup>
<h1 class="p-name no-ref allcaps" id="title">DOM</h1>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-05-10">10 May 2016</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Living Standard — Last Updated <time class="dt-updated" datetime="2016-05-12">12 May 2016</time></span></h2>
</hgroup>
<div data-fill-with="spec-metadata">
<dl>
Expand Down Expand Up @@ -492,6 +492,7 @@ <h3 class="heading settled" data-level="3.2" id="interface-event"><span class="s
readonly attribute DOMString <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="DOMString " href="#dom-event-type">type</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-target">target</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-currenttarget">currentTarget</a>;
sequence&lt;<a data-link-type="idl-name" href="#eventtarget">EventTarget</a>> <a class="idl-code" data-link-type="method" href="#dom-event-composedpath">composedPath</a>();

const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-none">NONE</a> = 0;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-capturing_phase">CAPTURING_PHASE</a> = 1;
Expand Down Expand Up @@ -538,6 +539,10 @@ <h3 class="heading settled" data-level="3.2" id="interface-event"><span class="s
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code></code>
<dd>Returns the object whose <a data-link-type="dfn" href="#concept-event-listener">event listener</a>’s <b>callback</b> is currently being
invoked.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-composedpath">composedPath()</a></code></code>
<dd>Returns the <b>item</b> objects of <var>event</var>’s <a data-link-type="dfn" href="#event-path">path</a> (objects on which
listeners will be invoked), except for any <a data-link-type="dfn" href="#concept-node">nodes</a> in <a data-link-type="dfn" href="#concept-shadow-tree">shadow trees</a> of which the <a data-link-type="dfn" href="#concept-shadow-root">shadow root</a>’s <a data-link-type="dfn" href="#shadowroot-mode">mode</a> is "<code>closed</code>" that are not
reachable from <var>event</var>’s <code class="idl"><a data-link-type="idl" href="#dom-event-currenttarget">currentTarget</a></code>.
<dt><code><var>event</var> . <code class="idl"><a data-link-type="idl" href="#dom-event-eventphase">eventPhase</a></code></code>
<dd>Returns the <a data-link-type="dfn" href="#concept-event">event</a>’s phase, which is one of <code class="idl"><a data-link-type="idl" href="#dom-event-none">NONE</a></code>, <code class="idl"><a data-link-type="idl" href="#dom-event-capturing_phase">CAPTURING_PHASE</a></code>, <code class="idl"><a data-link-type="idl" href="#dom-event-at_target">AT_TARGET</a></code>, and <code class="idl"><a data-link-type="idl" href="#dom-event-bubbling_phase">BUBBLING_PHASE</a></code>.
<dt><code><var>event</var> . <a class="idl-code" data-link-type="method" href="#dom-event-stoppropagation">stopPropagation</a>()</code>
Expand Down Expand Up @@ -573,6 +578,24 @@ <h3 class="heading settled" data-level="3.2" id="interface-event"><span class="s
initialized to the empty string.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-target"><code>target</code><a class="self-link" href="#dom-event-target"></a></dfn> and <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-currenttarget"><code>currentTarget</code><a class="self-link" href="#dom-event-currenttarget"></a></dfn> attributes must return the values they were initialized to. When an <a data-link-type="dfn" href="#concept-event">event</a> is created the attributes must be
initialized to null.</p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="method" data-export="" id="dom-event-composedpath"><code>composedPath()</code><a class="self-link" href="#dom-event-composedpath"></a></dfn> method, when invoked, must run these
steps: </p>
<ol>
<li>
<p>Let <var>composedPath</var> be a new empty list. </p>
<li>
<p>Let <var>currentTarget</var> be <a data-link-type="dfn" href="#context-object">context object</a>’s <code for="Event">currentTarget</code> attribute value. </p>
<li>
<p>For each <var>tuple</var> in <a data-link-type="dfn" href="#context-object">context object</a>’s <a data-link-type="dfn" href="#event-path">path</a>: </p>
<ol>
<li>
<p>If <var>currentTarget</var> is a <a data-link-type="dfn" href="#concept-node">node</a> and <var>tuple</var>’s <b>item</b> is an <a data-link-type="dfn" href="#concept-unclosed-node">unclosed node</a> of <var>currentTarget</var>, or <var>currentTarget</var> is <em>not</em> a <a data-link-type="dfn" href="#concept-node">node</a>, then append <var>tuple</var>’s <b>item</b> to <var>composedPath</var>.</p>
</ol>
<li>
<p>Return <var>composedPath</var>. </p>
</ol>
<p class="note no-backref" role="note">This algorithm assumes that when the <var>target</var> argument to the <a data-link-type="dfn" href="#concept-event-dispatch">dispatch</a> algorithm is not a <a data-link-type="dfn" href="#concept-node">node</a>, none of the tuples in <var>event</var> argument’s
eventual <a data-link-type="dfn" href="#event-path">path</a> will contain a <a data-link-type="dfn" href="#concept-node">node</a> either. </p>
<p>The <dfn class="idl-code" data-dfn-for="Event" data-dfn-type="attribute" data-export="" id="dom-event-eventphase"><code>eventPhase</code><a class="self-link" href="#dom-event-eventphase"></a></dfn> attribute must return the value it was initialized to, which must be one of
the following:</p>
<dl>
Expand Down Expand Up @@ -3233,6 +3256,7 @@ <h3 class="heading settled" data-level="4.8" id="interface-shadowroot"><span cla
<p>A <dfn data-dfn-type="dfn" data-export="" id="concept-shadow-including-inclusive-descendant">shadow-including inclusive descendant<a class="self-link" href="#concept-shadow-including-inclusive-descendant"></a></dfn> is an object or one of its <a data-link-type="dfn" href="#concept-shadow-including-descendant">shadow-including descendants</a>. </p>
<p>An object <var>A</var> is a <dfn data-dfn-type="dfn" data-export="" id="concept-shadow-including-ancestor">shadow-including ancestor<a class="self-link" href="#concept-shadow-including-ancestor"></a></dfn> of an object <var>B</var>, if and only if <var>B</var> is a <a data-link-type="dfn" href="#concept-shadow-including-descendant">shadow-including descendant</a> of <var>A</var>. </p>
<p>A <dfn data-dfn-type="dfn" data-export="" id="concept-shadow-including-inclusive-ancestor">shadow-including inclusive ancestor<a class="self-link" href="#concept-shadow-including-inclusive-ancestor"></a></dfn> is an object or one of its <a data-link-type="dfn" href="#concept-shadow-including-ancestor">shadow-including ancestors</a>. </p>
<p>A <a data-link-type="dfn" href="#concept-node">node</a> <var>A</var> is an <dfn data-dfn-type="dfn" data-export="" id="concept-unclosed-node">unclosed node<a class="self-link" href="#concept-unclosed-node"></a></dfn> of a <a data-link-type="dfn" href="#concept-node">node</a> <var>B</var>, if <var>A</var>’s <a data-link-type="dfn" href="#concept-tree-root">root</a> is a <a data-link-type="dfn" href="#concept-shadow-including-inclusive-ancestor">shadow-including inclusive ancestor</a> of <var>B</var>, or <var>A</var>’s <a data-link-type="dfn" href="#concept-tree-root">root</a> is a <a data-link-type="dfn" href="#concept-shadow-root">shadow root</a> whose <a data-link-type="dfn" href="#shadowroot-mode">mode</a> is "<code>open</code>" and <a data-link-type="dfn" href="#concept-documentfragment-host">host</a> is an <a data-link-type="dfn" href="#concept-unclosed-node">unclosed node</a> of <var>B</var>. </p>
<hr>
<p class="XXX">For now you can find more information about this object in <a href="https://w3c.github.io/webcomponents/spec/shadow/">Shadow DOM</a>. The DOM Standard will be
updated over time to cover more details. </p>
Expand Down Expand Up @@ -5500,6 +5524,7 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#dom-event-composed">attribute for Event</a><span>, in §3.2</span>
</ul>
<li><a href="#composed-flag">composed flag</a><span>, in §3.2</span>
<li><a href="#dom-event-composedpath">composedPath()</a><span>, in §3.2</span>
<li><a href="#concept-event-constructor">constructor</a><span>, in §3.4</span>
<li><a href="#contained">contained</a><span>, in §5.2</span>
<li><a href="#dom-node-contains">contains(other)</a><span>, in §4.4</span>
Expand Down Expand Up @@ -6186,6 +6211,7 @@ <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="c
<li><a href="#concept-document-type">dfn for Document</a><span>, in §4.5</span>
</ul>
<li><a href="#typeinfo">TypeInfo</a><span>, in §8.2</span>
<li><a href="#concept-unclosed-node">unclosed node</a><span>, in §4.8</span>
<li><a href="#concept-dtl-update">update steps</a><span>, in §7.1</span>
<li>
URL
Expand Down Expand Up @@ -6396,6 +6422,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
readonly attribute DOMString <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="DOMString " href="#dom-event-type">type</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-target">target</a>;
readonly attribute <a data-link-type="idl-name" href="#eventtarget">EventTarget</a>? <a class="idl-code" data-link-type="attribute" data-readonly="" data-type="EventTarget? " href="#dom-event-currenttarget">currentTarget</a>;
sequence&lt;<a data-link-type="idl-name" href="#eventtarget">EventTarget</a>> <a class="idl-code" data-link-type="method" href="#dom-event-composedpath">composedPath</a>();

const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-none">NONE</a> = 0;
const unsigned short <a class="idl-code" data-link-type="const" href="#dom-event-capturing_phase">CAPTURING_PHASE</a> = 1;
Expand Down

0 comments on commit 58b19e4

Please sign in to comment.