Skip to content

Commit

Permalink
Add showPicker() to <input> elements
Browse files Browse the repository at this point in the history 
Also specifies that both color and file inputs show pickers on both programmatic and user clicks, since that is true in all browsers. (Previously the spec included this behavior only for file inputs.)

Closes #6909. Closes #3232.
  • Loading branch information
@domenic
domenic authored Dec 8, 2021
1 parent 0e49b8c commit 968bf46
Showing 1 changed file with 156 additions and 37 deletions.
193 changes: 156 additions & 37 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44258,6 +44258,8 @@ interface <dfn interface>HTMLInputElement</dfn> : <span>HTMLElement</span> {
undefined <span data-x="dom-textarea/input-setRangeText">setRangeText</span>(DOMString replacement, unsigned long start, unsigned long end, optional <span>SelectionMode</span> selectionMode = "preserve");
undefined <span data-x="dom-textarea/input-setSelectionRange">setSelectionRange</span>(unsigned long start, unsigned long end, optional DOMString direction);

undefined <span data-x="dom-input-showPicker">showPicker</span>();

// <a href="#HTMLInputElement-partial">also has obsolete members</a>
};</code></pre>
</dd>
Expand Down Expand Up @@ -45586,6 +45588,15 @@ interface <dfn interface>HTMLInputElement</dfn> : <span>HTMLElement</span> {
otherwise.</p></li>
</ol>

<p class="note">Recall that an element's <span>activation behavior</span> runs for both
user-initiated activations and for synthetic activations (e.g., via <code
data-x="">el.click()</code>). User agents might also have behaviors for a given control — not
specified here — that are triggered only by true user-initiated activations. A common choice is to
<span>show the picker, if applicable</span>, for the control. In contrast, the <span>input
activation behavior</span> only shows pickers for the special historical cases of the <span
data-x="attr-input-type-file">File Upload</span> and <span
data-x="attr-input-type-color">Color</span> states.</p>

<p>The <span>legacy-pre-activation behavior</span> for <code>input</code> elements are these
steps:</p>

Expand Down Expand Up @@ -47811,6 +47822,15 @@ ldh-str = &lt; as defined in <a href="https://tools.ietf.org/html/rfc1034#
agents must not allow the user to set the <span data-x="concept-fe-value">value</span> to the empty
string.</p>

<p>The <span>input activation behavior</span> for such an element <var>element</var> is:</p>

<ol>
<li><p>If <var>element</var>'s <span>relevant global object</span> does not have <span>transient
activation</span>, then return.</p></li>

<li><p><span>Show the picker, if applicable</span>, for <var>element</var>.</p></li>
</ol>

<p><strong>Constraint validation</strong>: While the user interface describes input that the user
agent cannot convert to a <span>valid lowercase simple color</span>, the control is
<span>suffering from bad input</span>.</p>
Expand Down Expand Up @@ -48212,44 +48232,10 @@ ldh-str = &lt; as defined in <a href="https://tools.ietf.org/html/rfc1034#
<p>The <span>input activation behavior</span> for such an element <var>element</var> is:</p>

<ol>
<li><p>If the algorithm is invoked when <var>element</var>'s <span>relevant global object</span>
does not have <span>transient activation</span>, then return.</p></li>

<li>
<p>Run these steps <span>in parallel</span>:</p>

<ol>
<li><p>Optionally, wait until any prior execution of this algorithm has terminated.</p></li>

<li><p>Display a prompt to the user requesting that the user specify some files. If the <code
data-x="attr-input-multiple">multiple</code> attribute is not set on <var>element</var>, there
must be no more than one file selected; otherwise, any number may be selected. Files can be
from the filesystem or created on the fly, e.g., a picture taken from a camera connected to the
user's device.</p></li>

<li><p>Wait for the user to have made their selection.</p></li>

<li><p>If the user dismissed the prompt without changing their selection, then <span>queue an
element task</span> on the <span>user interaction task source</span> given <var>element</var>
to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-cancel">cancel</code> at <var>element</var>, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>

<li><p>Otherwise, <span>update the file selection</span> for <var>element</var>.</p></li>
</ol>
<li><p>If <var>element</var>'s <span>relevant global object</span> does not have <span>transient
activation</span>, then return.</p></li>

<p class="note">As with all user interface specifications, user agents have a good deal of
freedom in how they interpret these requirements. The above text implies that a user either
dismisses the prompt or changes their selection; exactly one of these will be true. But the
mapping of these possibilities to specific user interface elements is not mandated by the
standard. For example, a user agent might interpret clicking the "Cancel" button when files were
previously selected as a change of selection to select zero files, thus firing <code
data-x="event-input">input</code> and <code data-x="event-change">change</code>. Or it might
interpret such a click as a dismissal that leaves the selection unchanged, thus firing <code
data-x="event-cancel">cancel</code>. Similarly, it's up to the user agent whether re-selecting
the same files counts as were previously selected counts as a dismissal, or as a change of
selection.</p>
</li>
<li><p><span>Show the picker, if applicable</span>, for <var>element</var>.</p></li>
</ol>

<p>If the element is <i data-x="concept-fe-mutable">mutable</i>, the user agent should allow the
Expand Down Expand Up @@ -50004,6 +49990,20 @@ You cannot submit this form when the field is incorrect.</samp></pre>

<dd><p>Returns the <code>datalist</code> element indicated by the <code
data-x="attr-input-list">list</code> attribute.</p></dd>

<dt><code data-x=""><var>input</var>.<span subdfn data-x="dom-input-showPicker">showPicker</span>()</code></dt>

<dd>
<p>Shows any applicable picker UI for <var>input</var>, so that the user can select a value. (If
no picker UI is implemented for the given control, then this method does nothing.)</p>

<p>Throws a <span>"<code>NotAllowedError</code>"</span> <code>DOMException</code> if called
without <span data-x="transient activation">transient user activation</span>.</p>

<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if
<var>input</var> is inside a cross-origin <code>iframe</code>, unless <var>input</var> is in the
<span data-x="attr-input-type-file">File Upload</span> or <span
data-x="attr-input-type-color">Color</span> states.</p>
</dl>

<div w-nodev>
Expand Down Expand Up @@ -50272,6 +50272,125 @@ You cannot submit this form when the field is incorrect.</samp></pre>
attribute must return the current <span data-x="concept-input-list">suggestions source
element</span>, if any, or null otherwise.</p>

<hr>

<p>The <dfn method for="HTMLInputElement"><code
data-x="dom-input-showPicker">showPicker()</code></dfn> method steps are:</p>

<ol>
<li>
<p>If <span>this</span>'s <span>relevant settings object</span>'s <span
data-x="concept-settings-object-origin">origin</span> is not <span>same origin</span> with
<span>this</span>'s <span>relevant settings object</span>'s <span>top-level origin</span>, and
<span>this</span>'s <code data-x="attr-input-type">type</code> attribute is not in the <span
data-x="attr-input-type-file">File Upload</span> state or <span
data-x="attr-input-type-color">Color</span> state, then throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code>.</p>

<p class="note"><span data-x="attr-input-type-file">File</span> and <span
data-x="attr-input-type-color">Color</span> inputs are exempted from this check for historical
reason: their <span>input activation behavior</span> also shows their pickers, and has never
been guarded by an origin check.</p>
</li>

<li><p>If <span>this</span>'s <span>relevant global object</span> does not have <span>transient
activation</span>, then throw a <span>"<code>NotAllowedError</code>"</span>
<code>DOMException</code>.</p></li>

<li><p><span>Show the picker, if applicable</span>, for <span>this</span>.</p></li>
</ol>

<p>To <dfn>show the picker, if applicable</dfn> for an <code>input</code> element
<var>element</var>:</p>

<ol>
<li><p>Assert: <var>element</var>'s <span>relevant global object</span> has <span>transient
activation</span>.</p></li>

<li><p>If <var>element</var> is not <i data-x="concept-fe-mutable">mutable</i>, then
return.</p></li>

<li>
<p>If <var>element</var>'s <code data-x="attr-input-type">type</code> attribute is in the <span
data-x="attr-input-type-file">File Upload</span> state, then run these steps <span>in
parallel</span>:</p>

<ol>
<li><p>Optionally, wait until any prior execution of this algorithm has terminated.</p></li>

<li><p>Display a prompt to the user requesting that the user specify some files. If the <code
data-x="attr-input-multiple">multiple</code> attribute is not set on <var>element</var>, there
must be no more than one file selected; otherwise, any number may be selected. Files can be
from the filesystem or created on the fly, e.g., a picture taken from a camera connected to the
user's device.</p></li>

<li><p>Wait for the user to have made their selection.</p></li>

<li><p>If the user dismissed the prompt without changing their selection, then <span>queue an
element task</span> on the <span>user interaction task source</span> given <var>element</var>
to <span data-x="concept-event-fire">fire an event</span> named <code
data-x="event-cancel">cancel</code> at <var>element</var>, with the <code
data-x="dom-Event-bubbles">bubbles</code> attribute initialized to true.</p></li>

<li><p>Otherwise, <span>update the file selection</span> for <var>element</var>.</p></li>
</ol>

<p class="note">As with all user interface specifications, user agents have a good deal of
freedom in how they interpret these requirements. The above text implies that a user either
dismisses the prompt or changes their selection; exactly one of these will be true. But the
mapping of these possibilities to specific user interface elements is not mandated by the
standard. For example, a user agent might interpret clicking the "Cancel" button when files were
previously selected as a change of selection to select zero files, thus firing <code
data-x="event-input">input</code> and <code data-x="event-change">change</code>. Or it might
interpret such a click as a dismissal that leaves the selection unchanged, thus firing <code
data-x="event-cancel">cancel</code>. Similarly, it's up to the user agent whether re-selecting
the same files counts as were previously selected counts as a dismissal, or as a change of
selection.</p>
</li>

<li>
<p>Otherwise, the user agent should show any relevant user interface for selecting a value for
<var>element</var>, in the way it normally would when the user interacts with the control. (If
no such UI applies to <var>element</var>, then this step does nothing.)</p>

<p>If such a user interface is shown, it must respect the requirements stated in the relevant
parts of the specification for how <var>element</var> behaves given its <code
data-x="attr-input-type">type</code> attribute state. (For example, various sections describe
restrictions on the resulting <span data-x="concept-fe-value">value</span> string.)</p>

<p>This step can have side effects, such as closing other pickers that were previously shown by
this algorithm. (If this closes a file selection picker, then per the above that will lead to
firing either <code data-x="event-input">input</code> and <code
data-x="event-change">change</code> events, or a <code data-x="event-cancel">cancel</code>
event.)</p>

<div class="note">
<p>As of the time of this writing, typical browser implementations show such picker UI for:</p>

<ul>
<li><p><code>input</code> elements whose <code data-x="attr-input-type">type</code>
attributes are in the <span data-x="attr-input-type-date">Date</span>, <span
data-x="attr-input-type-month">Month</span>, <span data-x="attr-input-type-week">Week</span>,
<span data-x="attr-input-type-time">Time</span>, <span
data-x="attr-input-type-datetime-local">Local Date and Time</span>, and <span
data-x="attr-input-type-color">Color</span> states;</p></li>

<li><p><code>input</code> elements in various states that have a <span
data-x="concept-input-list">suggestions source element</span>; and</p></li>

<li><p><code>input</code> elements whose <code data-x="attr-input-type">type</code> attribute
is in the <span data-x="attr-input-type-file">File Upload</span> state (although those are
handled via the special case above, instead of by this step).</p></li>
</ul>

<p>However, the intent of this step is to trigger <em>any</em> picker UI implementation. So
for example, if a user agent implemented a password picker UI for the <span
data-x="attr-input-type-password">Password</span> state, then this method would be expected to
show that picker UI when called on a password input.</p>
</div>
</li>
</ol>

</div>


Expand Down

0 comments on commit 968bf46

Please sign in to comment.