Skip to content

[css-ui-4] Define how to compute the kind of widget to use for an element #6537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 14 commits into from
+242 −22
Closed

[css-ui-4] Define how to compute the kind of widget to use for an element #6537

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
3df21bb
Specify elements which can have native appearance, properties which d…
howard-e Aug 23, 2021
56f0f2e
revised content and links
howard-e Aug 23, 2021
50f285d
layout fix
howard-e Aug 23, 2021
5f5d407
addressing PR feedback
howard-e Aug 24, 2021
fbededc
Addded 'can be a <widget> dfns; Updated refs
howard-e Aug 24, 2021
b072598
Created section for 'Computing the kind of widget'
howard-e Aug 24, 2021
85eb8f9
Added missing elements radio, checkbox, listbox
howard-e Aug 25, 2021
21d7499
Move the step for menulist-button before menulist
zcorpan Sep 9, 2021
179b8cb
menulist needs to check authorProps and fallback to menulist-button
zcorpan Sep 10, 2021
fb58e6f
Change progress-bar and meter to do fallback to 'none'
zcorpan Oct 12, 2021
e55a449
Define mapping from 'appearance' values to kind of widget values and …
zcorpan Nov 25, 2021
5633bdd
Indentation
zcorpan Nov 25, 2021
3d9e243
Fix bikeshed errors
zcorpan Nov 25, 2021
47b192c
Change shoulds to musts and add a note about kinds of widgets
zcorpan Mar 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 242 additions & 22 deletions css-ui-4/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1038,30 +1038,30 @@ or to turn off blinking entirely.


<dl dfn-type=value dfn-for=caret-animation>
<dt><dfn>auto</dfn>
<dd>
<dt><dfn>auto</dfn>
<dd>
The UA determines how the caret should be animated, if at all.
It should match platform conventions,
and may be adjusted based on context.

Note: This is typically rendered as a blinking caret.

<dt><dfn>blink</dfn>
<dd>
<dt><dfn>blink</dfn>
<dd>
The UA must display a blinking caret.
For accessibility reasons, and based on user preferences,
the UA may display a non-animated caret instead.

<dt><dfn>none</dfn>
<dd>
<dt><dfn>none</dfn>
<dd>
The UA must not animate the caret.

Note: This is only about UA driven animations of the caret.
If CSS animations are used to animate the caret color,
these should still apply normally.

<dt><dfn>fade</dfn>
<dd>
<dt><dfn>fade</dfn>
<dd>
The UA must display a caret repeatedly fading in and out,
similarly to ''caret-animation/blink'' except it appears and
disappears progressively rather than suddenly.
Expand Down Expand Up @@ -1995,33 +1995,25 @@ so that CSS can be used to restyle them.
<dl dfn-type=value dfn-for=appearance>
<dt><dfn>none</dfn>
<dd>
The element is rendered following the usual rules of CSS.
Replaced elements other than <a>widgets</a> are not affected by this
and remain replaced elements.
<a>Widgets</a> must not have their <a>native appearance</a>.
See [[#appearance-decorative]] and [[#appearance-semantics]] for details.
The [=compute the kind of widget=] algorithm for the element will return [=kind of widget/none=].

<dt><dfn>auto</dfn>
<dd>
<a>Widgets</a> may have their <a>native appearance</a>.

Elements other than <a>widgets</a> must be rendered as if ''appearance/none'' had been specified.
The [=compute the kind of widget=] algorithm for the element will return
the appropriate [=kind of widget=] depending on the element and the author-level style.

<dt><dfn>textfield</dfn>
<dd>
For <{input}> elements where the <{input/type}> attribute is in the Search state,
the element is rendered as a "normal" text entry widget,
similar to an <{input}> element where the <{input/type}> attribute is in the Text state.
the [=compute the kind of widget=] algorithm will return
[=kind of widget/textfield=] or [=kind of widget/none=], depending on the author-level style.

For all other elements, this value has the same effect as ''appearance/auto''.

<dt><dfn>menulist-button</dfn>
<dd>
For <a spec="html">drop-down box</a> <{select}> elements,
the element is rendered as a drop-down box, including a "drop-down button",
but not necessarily using a native control of the host operating system.
For such elements, CSS properties such as 'color', 'background-color', and 'border'
(that can be disregarded for ''appearance/auto'') should not be disregarded.
the [=compute the kind of widget=] algorithm will return [=kind of widget/menulist-button=].

For all other elements, this value has the same effect as ''appearance/auto''.

Expand Down Expand Up @@ -2120,6 +2112,234 @@ so this specification needs to say something about this.
For compatibility with legacy content, UAs must also support <dfn property export>-webkit-appearance</dfn>
as a [=legacy name alias=] of 'appearance'.


<h4 id=computing-kind-widget>Computing the kind of widget</h4>

The possible <dfn lt="kind of widget|kinds of widgets">kinds of widgets</dfn> are:

<dl dfn-type="dfn" dfn-for="kind of widget">
<dt><dfn export>none</dfn>
<dd>
The element is rendered following the usual rules of CSS.
Replaced elements other than <a>widgets</a> are not affected by this
and remain replaced elements.
<a>Widgets</a> must not have their <a>native appearance</a>.
See [[#appearance-decorative]] and [[#appearance-semantics]] for details.

<dt><dfn export>button</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a button.

<dt><dfn export>textfield</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a one-line textfield.

<dt><dfn export>searchfield</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a one-line textfield, optionally with a distinct style indicating that it is a search field.

<dt><dfn export>slider-horizontal</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a horizontal slider.

<dt><dfn export>checkbox</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a checkbox.

<dt><dfn export>radio</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a radio button.

<dt><dfn export>listbox</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of multi-line list box.

<dt><dfn export>menulist</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of one-line menulist.

<dt><dfn export>menulist-button</dfn>
<dd>
The element is a <a>widget</a> which is must be rendered as a drop-down box,
including a "drop-down button",
but not necessarily using a native control of the host operating system.
For such elements, CSS properties such as 'color', 'background-color', and 'border'
(that can be disregarded for [=kind of widget/menulist=]) should not be disregarded.

<dt><dfn export>textarea</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a multi-line textfield.

<dt><dfn export>progress-bar</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a progress bar.

<dt><dfn export>meter</dfn>
<dd>
The element is a <a>widget</a> which must have the <a>native appearance</a> of a gauge.

</dl>

<p class="note">
The expected rendering of the different [=kind of widgets=] are not yet defined in detail.
See <a href="https://github.com/whatwg/html/issues/7050">whatwg/html issue #7050</a>.
</p>

<div algorithm="compute the kind of widget">
UAs must run this at [=used value=] time: <dfn export>compute the kind of widget</dfn> to use for an element, |element|:

<ol>
<!-- none always works -->
<li>
Let |computedAppearance| be the [=computed value=] of |element|'s 'appearance' property.

<li>
If |computedAppearance| is ''appearance/none'', then return [=kind of widget/none=].

<li>
Let |authorProps| be a [=map=] of all properties that have a <a>cascaded value</a> for
|element|, where the [=Author Origin=], [=Animation Origin=] and [=Transition Origin=]
[=Cascade Origins=] are included and the [=User Origin=] and [=UA Origin=] [=cascade origins=]
are ignored, where the key is the property name and the value is that <a>cascaded value</a>.

<li>
If |element| <a>can be a button</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/button=], and |fallback|
set to [=kind of widget/none=].

<li>
If |element| <a>can be a textfield</a>, given |computedAppearance|, then return the
<a>appropriate widget</a> with |authorProps| set to |authorProps|, |expected| set to
[=kind of widget/textfield=], and |fallback| set to [=kind of widget/none=].

<li>
If |element| <a>can be a searchfield</a>, given |computedAppearance|, then return the
<a>appropriate widget</a> with |authorProps| set to |authorProps|, |expected| set to
[=kind of widget/searchfield=], and |fallback| set to [=kind of widget/none=].

<li>
If |element| <a>can be a slider-horizontal</a>, given |computedAppearance|, then return
[=kind of widget/slider-horizontal=].

<li>
If |element| <a>can be a checkbox</a>, given |computedAppearance|, then return
[=kind of widget/checkbox=].

<li>
If |element| <a>can be a radio</a>, given |computedAppearance|, then return
[=kind of widget/radio=].

<li>
If |element| <a>can be a listbox</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/listbox=], and |fallback|
set to [=kind of widget/none=].

<li>
If |element| <a>can be a menulist-button</a>, given |computedAppearance|, then return
[=kind of widget/menulist-button=].

<li>
If |element| <a>can be a menulist</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/menulist=], and |fallback|
set to [=kind of widget/menulist-button=].

<li>
If |element| <a>can be a textarea</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/textarea=],
and |fallback| set to [=kind of widget/none=].

<li>
If |element| <a>can be a progress-bar</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/progress-bar=],
and |fallback| set to [=kind of widget/none=].

<li>
If |element| <a>can be a meter</a>, given |computedAppearance|, then return the <a>appropriate widget</a>
with |authorProps| set to |authorProps|, |expected| set to [=kind of widget/meter=],
and |fallback| set to [=kind of widget/none=].

<li>
Return [=kind of widget/none=].
</ol>

Host languages can define which elements, if any, <dfn export>can be a button</dfn>,
<dfn export>can be a textfield</dfn>, <dfn export>can be a searchfield</dfn>,
<dfn export>can be a slider-horizontal</dfn>, <dfn export>can be a checkbox</dfn>,
<dfn export>can be a radio</dfn>, <dfn export>can be a listbox</dfn>,
<dfn export>can be a menulist</dfn>, <dfn export>can be a menulist-button</dfn>,
<dfn export>can be a textarea</dfn>, <dfn export>can be a progress-bar</dfn>,
<dfn export>can be a meter</dfn>.

Issue: These definitions are expected to be a part of [[HTML]]. See:
<a href="https://github.com/whatwg/html/pull/4857">whatwg/html#4857</a>
</div>

<div algorithm="appropriate widget">
The <dfn export>appropriate widget</dfn>, given a [=map=] of properties |authorProps|, and an expected
[=kind of widget=] |expected|, and a fallback [=kind of widget=] |fallback|, is as follows:

<ol>
<li>
[=map/For each=] |prop| of the [=properties that disable native appearance for widgets=]:

<ol>
<li>If |authorProps|[|prop|] [=map/exists=], and it is not ''revert'', then return |fallback|.
</ol>

<li>Return |expected|.
</ol>
</div>

The <dfn export>properties that disable native appearance for widgets</dfn> are:

<ul>
<li>'background-color'
<li>'border-top-color'
<li>'border-top-style'
<li>'border-top-width'
<li>'border-right-color'
<li>'border-right-style'
<li>'border-right-width'
<li>'border-bottom-color'
<li>'border-bottom-style'
<li>'border-bottom-width'
<li>'border-left-color'
<li>'border-left-style'
<li>'border-left-width'
<li>'border-block-start-color'
<li>'border-block-end-color'
<li>'border-inline-start-color'
<li>'border-inline-end-color'
<li>'border-block-start-style'
<li>'border-block-end-style'
<li>'border-inline-start-style'
<li>'border-inline-end-style'
<li>'border-block-start-width'
<li>'border-block-end-width'
<li>'border-inline-start-width'
<li>'border-inline-end-width'
<li>'background-image'
<li>'background-attachment'
<li>'background-position'
<li>'background-clip'
<li>'background-origin'
<li>'background-size'
<li>'border-image-source'
<li>'border-image-slice'
<li>'border-image-width'
<li>'border-image-outset'
<li>'border-image-repeat'
<li>'border-top-left-radius'
<li>'border-top-right-radius'
<li>'border-bottom-right-radius'
<li>'border-bottom-left-radius'
<li>'border-start-start-radius'
<li>'border-start-end-radius'
<li>'border-end-start-radius'
<li>'border-end-end-radius'
</ul>


<h4 id=appearance-decorative>
Effects of 'appearance' on Decorative Aspects of Elements</h4>

Expand Down