Skip to content

Commit

Permalink
Close signal -> close request (concept-only change)
Browse files Browse the repository at this point in the history
  • Loading branch information
@domenic
domenic committed Jul 27, 2023
1 parent 63fb283 commit 95c5a80
Showing 1 changed file with 38 additions and 38 deletions.
76 changes: 38 additions & 38 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60297,7 +60297,7 @@ interface <dfn interface>HTMLDialogElement</dfn> : <span>HTMLElement</span> {
<li><p>The <code data-x="event-close">close</code> event will not be fired.</p></li>

<li><p>The <code data-x="dom-dialog-close">close()</code> method, and any <span data-x="close
signal">close signals</span>, will no longer be able to close the dialog.</p></li>
request">close requests</span>, will no longer be able to close the dialog.</p></li>

<li><p>If the dialog was shown using its <code data-x="dom-dialog-showModal">showModal()</code>
method, the <code>Document</code> will still be <span data-x="blocked by a modal
Expand Down Expand Up @@ -80328,17 +80328,17 @@ body { display:none }
<!-- TODO: Define scroll and highlight timing, as well as algorithms (what is and isn't found) -->


<h3>Close signals and close watchers</h3>
<h3>Close requests and close watchers</h3>

<h4>Close signals</h4>
<h4>Close requests</h4>

<p>In an <span>implementation-defined</span> (and likely device-specific) manner, a user can send
a <dfn export>close signal</dfn> to the user agent. This indicates that the user wishes to close
a <dfn export>close request</dfn> to the user agent. This indicates that the user wishes to close
something that is currently being shown on the screen, such as a popover, menu, dialog, picker, or
display mode.</p>

<div class="example">
<p>Some example close signals are:</p>
<p>Some example close requests are:</p>

<ul>
<li><p>The <kbd>Esc</kbd> key on desktop platforms</p></li>
Expand All @@ -80355,8 +80355,8 @@ body { display:none }

<div w-nodev>

<p>Whenever the user agent receives a potential close signal targeted at a <code>Document</code>
<var>document</var>, it must perform the following <dfn export>close signal steps</dfn>:</p>
<p>Whenever the user agent receives a potential close request targeted at a <code>Document</code>
<var>document</var>, it must perform the following <dfn export>close request steps</dfn>:</p>

<ol>
<li>
Expand All @@ -80377,13 +80377,13 @@ body { display:none }
sequence that <cite>UI Events</cite> <a
href="https://w3c.github.io/uievents/#events-keyboard-event-order">suggests</a> firing when the
user presses the <kbd>Esc</kbd> key on their keyboard. On most platforms with keyboards, this
is treated as a <span>close signal</span>, and so would trigger these <span>close signal
is treated as a <span>close request</span>, and so would trigger these <span>close request
steps</span>.</p>

<p class="example">An example of relevant events that are outside of the model given in
<cite>UI Events</cite> would be assistive technology synthesizing an <kbd>Esc</kbd> <code
data-x="event-keydown">keydown</code> and <code data-x="event-keyup">keyup</code> sequence when
the user sends a <span>close signal</span> by using a dismiss gesture.</p>
the user sends a <span>close request</span> by using a dismiss gesture.</p>
</li>

<li><p>Let <var>event</var> be null if no such events are fired, or the <code>Event</code> object
Expand All @@ -80403,15 +80403,15 @@ body { display:none }
<li><p>If <var>document</var> is not <span>fully active</span>, then abort these
steps.</p></li>

<li><p>Let <var>closedSomething</var> be the result of <span data-x="signal close
watchers">signaling close watchers</span> on <var>document</var>'s <span>relevant global
<li><p>Let <var>closedSomething</var> be the result of <span data-x="process close
watchers">processing close watchers</span> on <var>document</var>'s <span>relevant global
object</span>.</p></li>

<li><p>If <var>closedSomething</var> is true, then abort these steps.</p></li>

<li><p>Otherwise, there was nothing watching for a <span>close signal</span>. The user agent
<li><p>Otherwise, there was nothing watching for a <span>close request</span>. The user agent
may instead interpret this interaction as some other action, instead of interpreting it as a
close signal.</p></li>
close request.</p></li>
</ol>
</li>

Expand All @@ -80423,17 +80423,17 @@ body { display:none }

</div>

<p class="example">On platforms where <kbd>Esc</kbd> is the <span>close signal</span>, the user
<p class="example">On platforms where <kbd>Esc</kbd> is the <span>close request</span>, the user
agent will first fire an appropriately-initialized <code data-x="event-keydown">keydown</code> and
<code data-x="event-keyup">keyup</code> event sequence. If the web developer cancels the <code
data-x="event-keyup">keyup</code> event by calling <code
data-x="dom-Event-preventDefault">preventDefault()</code>, then nothing further happens. But if
the event fires without being canceled, then the user agent proceeds to <span>signal close
the event fires without being canceled, then the user agent proceeds to <span>process close
watchers</span>.</p>

<p class="example">On platforms where a back button is a potential <span>close signal</span>, no
<p class="example">On platforms where a back button is a potential <span>close request</span>, no
event is involved, so when the back button is pressed, the user agent <span data-x="queue a global
task">queues a task</span> to <span>signal close watchers</span>. If there is a <span>close
task">queues a task</span> to <span>process close watchers</span>. If there is a <span>close
watcher</span> on the <span>close watcher stack</span>, then that will get triggered. If there is
not, then the user agent can interpret the back button press in another way, for example as a
request to <span>traverse the history by a delta</span> of &minus;1.</p>
Expand All @@ -80450,7 +80450,7 @@ body { display:none }
item">items</span> can get <span data-x="list remove">removed</span> from the middle of it if a
<span>close watcher</span> is <span data-x="close-watcher-destroy">destroyed</span> or <span
data-x="close-watcher-close">closed</span> via web developer code. User-initiated <span
data-x="close signal">close signals</span> always act on the top of the <span>close watcher
data-x="close request">close requests</span> always act on the top of the <span>close watcher
stack</span>, however.</p>

<p>A <dfn export>close watcher</dfn> is a <span>struct</span> with the following <span
Expand Down Expand Up @@ -80480,8 +80480,8 @@ body { display:none }
is set if a <span>close watcher</span> is created without <span>transient activation</span>.
(Except the very first close watcher in the <span>close watcher stack</span> that is created
without transient activation, which gets a pass on this restriction.) It causes a user-triggered
<span>close signal</span> to close all such grouped-together close watchers, thus ensuring that
web developers can't make close signals ineffective by creating an excessive number of close
<span>close request</span> to close all such grouped-together close watchers, thus ensuring that
web developers can't make close requests ineffective by creating an excessive number of close
watchers.</p>

<p>A <span>close watcher</span> <var>closeWatcher</var> <dfn data-x="close-watcher-active">is
Expand Down Expand Up @@ -80646,7 +80646,7 @@ body { display:none }

<hr>

<p>To <dfn>signal close watchers </dfn> given a <code>Window</code> <var>window</var>:</p>
<p>To <dfn>process close watchers </dfn> given a <code>Window</code> <var>window</var>:</p>

<ol>
<li><p>Let <var>processedACloseWatcher</var> be false.</p></li>
Expand Down Expand Up @@ -80706,23 +80706,23 @@ dictionary <dfn dictionary>CloseWatcherOptions</dfn> {
<p>If any <span>close watcher</span> is already active, and the <code>Window</code> does not
have <span>transient activation</span>, then the resulting <code>CloseWatcher</code> will be
closed together with that already-active <span>close watcher</span> in response to any
<span>close signal</span>. (This already-active <span>close watcher</span> does not necessarily
<span>close request</span>. (This already-active <span>close watcher</span> does not necessarily
have to be a <code>CloseWatcher</code> object; it could be a modal <code>dialog</code> element,
or a popover generated by an element with the <code data-x="attr-popover">popover</code>
attribute.)</p>
</dd>

<dt><code data-x=""><var>watcher</var>.<span subdfn data-x="dom-CloseWatcher-requestClose">requestClose</span>()</code></dt>
<dd>
<p>Acts as if a <span>close signal</span> was sent targeting <var>watcher</var>, by first
<p>Acts as if a <span>close request</span> was sent targeting <var>watcher</var>, by first
firing a <code data-x="event-cancel">cancel</code> event, and if that event is not canceled
with <code data-x="dom-Event-preventDefault">preventDefault()</code>, proceeding to fire a
<code data-x="event-close">close</code> event before deactivating the close watcher as if <code
data-x="dom-CloseWatcher-destroy">watcher.destroy()</code> was called.</p>

<p>This is a helper utility that can be used to consolidate cancelation and closing logic into
the <code data-x="event-cancel">cancel</code> and <code data-x="event-close">close</code> event
handlers, by having all non-<span>close signal</span> closing affordances call this method.</p>
handlers, by having all non-<span>close request</span> closing affordances call this method.</p>
</dd>

<dt><code data-x=""><var>watcher</var>.<span subdfn data-x="dom-CloseWatcher-close">close</span>()</code></dt>
Expand Down Expand Up @@ -80832,8 +80832,8 @@ dictionary <dfn dictionary>CloseWatcherOptions</dfn> {

<div class="example" id="example-CloseWatcher-basic">
<p>If one wanted to implement a custom picker control, which closed itself on a user-provided
<span>close signal</span> as well as when a close button is pressed, the following code shows how
one would use the <code>CloseWatcher</code> API to process close signals:</p>
<span>close request</span> as well as when a close button is pressed, the following code shows how
one would use the <code>CloseWatcher</code> API to process close requests:</p>

<pre><code class="js">const watcher = new CloseWatcher();
const picker = setUpAndShowPickerDOMElement();
Expand Down Expand Up @@ -80871,9 +80871,9 @@ picker.querySelector('.close-button').onclick = () => watcher.requestClose();</c
};</code></pre>

<p>For abuse prevention purposes, this event only fires if the page has <span>history-action
activation</span>, which will be lost after any given <span>close signal</span>. This ensures
that if the user sends a close signal twice in a row without any intervening user activation, the
signal definitely goes through; the second signal ignores the <code
activation</span>, which will be lost after any given <span>close request</span>. This ensures
that if the user sends a close request twice in a row without any intervening user activation,
the request definitely succeeds; the second request ignores the <code
data-x="event-cancel">cancel</code> event handler and immediately closes the
<code>CloseWatcher</code>.</p>
</div>
Expand All @@ -80894,8 +80894,8 @@ picker.querySelector('.close-button').onclick = () => watcher.requestClose();</c
data-x="event-cancel">cancel</code> events, there is a more subtle form of user activation gating
for <code>CloseWatcher</code> construction. If one creates more than one
<code>CloseWatcher</code> without user activation, then the newly-created one will get grouped
together with the most-recently-created <span>close watcher</span>, so that a signal <span>close
signal</span> will close them both:</p>
together with the most-recently-created <span>close watcher</span>, so that a single <span>close
request</span> will close them both:</p>

<pre><code class="js">window.onload = () => {
// This will work as normal: it is the first close watcher created without user activation.
Expand All @@ -80908,7 +80908,7 @@ button1.onclick = () => {
};

button2.onclick = () => {
// These will be grouped together, and both will close in response to a single close signal.
// These will be grouped together, and both will close in response to a single close request.
(new CloseWatcher()).onclose = () => { /* ... */ };
(new CloseWatcher()).onclose = () => { /* ... */ };
};</code></pre>
Expand Down Expand Up @@ -83963,8 +83963,8 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {

<h4><dfn>Popover light dismiss</dfn></h4>

<p class="note">"Light dismiss" means that sending a <span>close signal</span> or clicking outside
of a popover whose <code data-x="attr-popover">popover</code> attribute is in the <span
<p class="note">"Light dismiss" means that sending a <span>close request</span> or clicking
outside of a popover whose <code data-x="attr-popover">popover</code> attribute is in the <span
data-x="attr-popover-auto-state">auto</span> state will close the popover.</p>

<p>To <dfn>light dismiss open popovers</dfn>, given an <code>Event</code> <var>event</var>:</p>
Expand Down Expand Up @@ -138099,7 +138099,7 @@ INSERT INTERFACES HERE
<td> <dfn event for="HTMLElement"><code data-x="event-cancel">cancel</code></dfn>
<td> <code>Event</code>
<td> <code>CloseWatcher</code>, <code>dialog</code> elements, <code>input</code> elements
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they receive a <span>close signal</span>, or at <code>input</code> elements in the <span data-x="attr-input-type-file">File</span> state when the user does not change their selection
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they receive a <span>close request</span>, or at <code>input</code> elements in the <span data-x="attr-input-type-file">File</span> state when the user does not change their selection

<tr> <!-- change -->
<td> <dfn event for="HTMLElement"><code data-x="event-change" id="event-input-change">change</code></dfn>
Expand All @@ -138117,7 +138117,7 @@ INSERT INTERFACES HERE
<td> <dfn event for="HTMLElement"><code data-x="event-close">close</code></dfn>
<td> <code>Event</code>
<td> <code>CloseWatcher</code>, <code>dialog</code> elements
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they are closed via a <span>close signal</span>
<td> Fired at <code>CloseWatcher</code> objects or <code>dialog</code> elements when they are closed via a <span>close request</span> or via web developer code

<tr> <!-- connect -->
<td> <dfn event for="SharedWorkerGlobalScope"><code data-x="event-WorkerGlobalScope-connect">connect</code></dfn>
Expand Down Expand Up @@ -140404,8 +140404,8 @@ INSERT INTERFACES HERE
Document License</a>.</p>

<p itemscope itemtype="http://n.whatwg.org/work">Part of the revision history of the <a
href="#close-signals-and-close-watchers">Close signals and close watchers</a> section can be found in the <a
href="https://github.com/WICG/close-watcher"><code>WICG/close-watcher</code>
href="#close-requests-and-close-watchers">Close requests and close watchers</a> section can be
found in the <a href="https://github.com/WICG/close-watcher"><code>WICG/close-watcher</code>
repository</a>, which is available under the <a itemprop="license"
href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document">W3C Software and
Document License</a>.</p>
Expand Down

0 comments on commit 95c5a80

Please sign in to comment.