Skip to content

Commit 0d06a71

Browse files
jnurthencynscookiecrook
authored
Update IDL and enumerated attribute section (#1611)
Co-authored-by: Cynthia Shelly <[email protected]> Co-authored-by: James Craig <[email protected]>
1 parent 7c5efbe commit 0d06a71

File tree

1 file changed

+107
-62
lines changed

1 file changed

+107
-62
lines changed

‎index.html

+107-62
Original file line numberDiff line numberDiff line change
@@ -10226,12 +10226,48 @@ <h3>Value</h3>
1022610226
</section>
1022710227
<section id="enumerated-attribute-values">
1022810228
<h2>Enumerated Attribute Values</h2>
10229-
<p>When the ARIA attribute definition includes a table enumerating the attribute's allowed <span>values</span>, that attribute is an <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. Each value in the table is a keyword for the attribute, mapping to a state of the same name. When the values table notates one of the values as "(default)", that default value is the <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#missing-value-default">missing value default</a> and <a href="https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#invalid-value-default">invalid value default</a> for the attribute.</p>
10230-
<section class="informative" id="enumeration-example">
10231-
<h3>Example Enumerated Attribute Usage</h3>
10232-
<p>As noted in <a href="#typemapping">Mapping <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> Value Types to Languages</a>, attributes are included in host languages, and the syntax for representation of enumerated value types is governed by the host language.</p>
10233-
<p>All enumerated attribute getters and setters use string values, including the boolean-like enumerated <a href="#valuetype_true-false">true/false</a> type.</p>
10234-
<aside class="example">
10229+
<p>When the ARIA attribute definition includes a table enumerating the attribute's allowed <span>values</span>,
10230+
that attribute is a nullable <a data-cite="html/common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>.
10231+
Each value in the table is a keyword for the attribute, mapping to a state of the same name. </p>
10232+
<section id="idl-reflection-attribute-values">
10233+
<h3>IDL reflection of ARIA attributes</h3>
10234+
<p>All ARIA attributes reflect in IDL as [=nullable type|nullable=] {{DOMString}} attributes.
10235+
This includes the boolean-like enumerated <a href="#valuetype_true-false">true/false</a> type, and all other ARIA enumerated attributes.</p>
10236+
<p>Default values from the ARIA values tables MUST NOT reflect to IDL as the
10237+
<a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> or the
10238+
<a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> for the attribute.
10239+
On getting, a missing ARIA attribute will return <code>null</code>. ARIA attributes are not validated on get.
10240+
If an ARIA value is invalid, on getting, it will return its set value as a literal string, and will not return an invalid value default.</p>
10241+
</section>
10242+
<section id="os-aapi-attribute-mapping">
10243+
<h3>Operating System Accessibility API mapping of ARIA enumerated attributes</h3>
10244+
<p>Unlike IDL reflection, operating system accessibility API mappings of ARIA enumerated attributes do have defaults.
10245+
The default values from the ARIA values tables are exposed to the operating system accessibility API as described in
10246+
[[[#supportedState]]], and in [[[CORE-AAM]]].</p>
10247+
</section>
10248+
<section id="enumerated-attribute-values-html">
10249+
<h3>ARIA Enumerated Attributes in HTML</h3>
10250+
<p>As noted in [[[#typemapping]]], attributes are included in host languages, and the syntax for representation of enumerated value types is governed by the host language.</p>
10251+
<p>When the host language is HTML, ARIA enumerated attributes MUST follow the <a data-cite="html/common-dom-interfaces.html#reflecting-content-attributes-in-idl-attributes">HTML rules</a> for reflecting [=nullable type|nullable=] {{DOMString}} IDL attributes current as of September 3, 2021.</p>
10252+
<div class="note informative" data-cite="HTML">
10253+
<p>Below is a copy of the HTML specification text for [=nullable type|nullable=] {{DOMString}} IDL attributes as of September 3, 2021.
10254+
The HTML spec is a living document, and this section may have changed since. Refer to the link above for the most current version.</p>
10255+
10256+
<blockquote>
10257+
a reflecting IDL attribute is a nullable {{DOMString}}
10258+
attribute whose content attribute is an <a data-cite="html/common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>, then, on getting, if
10259+
the corresponding content attribute is in its <i>missing value default</i> state then the IDL
10260+
attribute must return null, otherwise, the IDL attribute must return the keyword value associated
10261+
with the state the attribute is in. If there are multiple keyword values for the state, then
10262+
return the conforming one. If there are multiple conforming keyword values, then one will be
10263+
designated the <a data-cite="html/common-dom-interfaces.html#canonical-keyword">canonical keyword</a>; choose that one. On setting, if the new value is
10264+
null, the content attribute must be removed, and otherwise, the content attribute must be set to
10265+
the specified new value.
10266+
</blockquote>
10267+
</div>
10268+
<section class="informative" id="enumeration-example">
10269+
<h4>Example Enumerated Attribute Usage</h4>
10270+
<aside class="example">
1023510271

1023610272
<!-- ReSpec needs these examples to be unindented. -->
1023710273
<pre>// HTML hidden="" example (not aria-hidden="true")
@@ -10250,15 +10286,17 @@ <h3>Example Enumerated Attribute Usage</h3>
1025010286

1025110287
<!-- ReSpec needs these examples to be unindented. -->
1025210288
<pre>// aria-busy example
10253-
// true/false ~ enumerated boolean-like string; defaults to "false"
10289+
// true/false ~ enumerated boolean-like nullable string; returns null unless set
10290+
10291+
el.ariaBusy; // null
1025410292

1025510293
// Note: String assignment and return value.
1025610294
el.ariaBusy = "true";
1025710295
el.ariaBusy; // "true"
1025810296

1025910297
// Removal of content attribute results in missing value default: string "false".
1026010298
el.removeAttribute("aria-busy");
10261-
el.ariaBusy; // "false"
10299+
el.ariaBusy; // null
1026210300

1026310301
// Assignment of invalid "busy" value results in invalid value default: string "false".
1026410302
el.setAttribute("aria-busy", "busy");
@@ -10269,19 +10307,27 @@ <h3>Example Enumerated Attribute Usage</h3>
1026910307

1027010308
<!-- ReSpec needs these examples to be unindented. -->
1027110309
<pre>// aria-pressed example
10272-
// Tristate ~ enumerated true/false/mixed/undefined string; defaults to "undefined".
10310+
// Tristate ~ enumerated true/false/mixed/undefined string; null if unspecified
10311+
10312+
// no value has been defined
10313+
button.ariaPressed; // null
1027310314

1027410315
// A value of "true", "false", or "mixed" for aria-pressed on a button denotes a toggle button.
1027510316
button.setAttribute("aria-pressed", "true"); // Content attribute assignment.
1027610317
button.ariaPressed; // "true"
1027710318
button.ariaPressed = "false"; // DOM property assignment.
1027810319
button.ariaPressed; // "false"
1027910320

10280-
// Assignment of invalid "foo" value results in invalid value default, String "undefined".
10321+
// Assignment of invalid "foo" value. Not validated on get and the literal string value "foo" is returned.
1028110322
button.ariaPressed = "foo";
10282-
button.ariaPressed; // "undefined" (Note: button is no longer a toggle button.)</pre>
10323+
button.ariaPressed; // "foo" (Note: button is no longer a toggle button.)
1028310324

10284-
</aside>
10325+
// Removal of content attribute results in a null value
10326+
button.removeAttribute("aria-pressed");
10327+
button.ariaPressed; // null</pre>
10328+
10329+
</aside>
10330+
</section>
1028510331
</section>
1028610332
</section>
1028710333
<section>
@@ -13597,56 +13643,55 @@ <h2>Interface Mixin <dfn>ARIAMixin</dfn></h2>
1359713643
<pre class="idl">
1359813644
interface mixin ARIAMixin {
1359913645
attribute DOMString? role;
13600-
13601-
<!-- attribute Element ariaActiveDescendantElement; -->
13602-
attribute DOMString ariaAtomic;
13603-
attribute DOMString ariaAutoComplete;
13604-
attribute DOMString ariaBusy;
13605-
attribute DOMString ariaChecked;
13606-
attribute DOMString ariaColCount;
13607-
attribute DOMString ariaColIndex;
13608-
attribute DOMString ariaColIndexText;
13609-
attribute DOMString ariaColSpan;
13610-
<!-- attribute FrozenArray&lt;Element&gt; ariaControlsElements; -->
13611-
attribute DOMString ariaCurrent;
13612-
<!-- attribute FrozenArray&lt;Element&gt; ariaDescribedByElements; -->
13613-
attribute DOMString ariaDescription;
13614-
<!-- attribute FrozenArray&lt;Element&gt; ariaDetailsElements; -->
13615-
attribute DOMString ariaDisabled;
13616-
<!-- attribute Element ariaErrorMessageElement; -->
13617-
attribute DOMString ariaExpanded;
13618-
<!-- attribute FrozenArray&lt;Element&gt; ariaFlowToElements; -->
13619-
attribute DOMString ariaHasPopup;
13620-
attribute DOMString ariaHidden;
13621-
attribute DOMString ariaInvalid;
13622-
attribute DOMString ariaKeyShortcuts;
13623-
attribute DOMString ariaLabel;
13624-
<!-- attribute FrozenArray&lt;Element&gt; ariaLabelledByElements; -->
13625-
attribute DOMString ariaLevel;
13626-
attribute DOMString ariaLive;
13627-
attribute DOMString ariaModal;
13628-
attribute DOMString ariaMultiLine;
13629-
attribute DOMString ariaMultiSelectable;
13630-
attribute DOMString ariaOrientation;
13631-
<!-- attribute FrozenArray&lt;Element&gt; ariaOwnsElements; -->
13632-
attribute DOMString ariaPlaceholder;
13633-
attribute DOMString ariaPosInSet;
13634-
attribute DOMString ariaPressed;
13635-
attribute DOMString ariaReadOnly;
13636-
<!-- attribute DOMString ariaRelevant; -->
13637-
attribute DOMString ariaRequired;
13638-
attribute DOMString ariaRoleDescription;
13639-
attribute DOMString ariaRowCount;
13640-
attribute DOMString ariaRowIndex;
13641-
attribute DOMString ariaRowIndexText;
13642-
attribute DOMString ariaRowSpan;
13643-
attribute DOMString ariaSelected;
13644-
attribute DOMString ariaSetSize;
13645-
attribute DOMString ariaSort;
13646-
attribute DOMString ariaValueMax;
13647-
attribute DOMString ariaValueMin;
13648-
attribute DOMString ariaValueNow;
13649-
attribute DOMString ariaValueText;
13646+
<!-- attribute Element? ariaActiveDescendantElement; -->
13647+
attribute DOMString? ariaAtomic;
13648+
attribute DOMString? ariaAutoComplete;
13649+
attribute DOMString? ariaBusy;
13650+
attribute DOMString? ariaChecked;
13651+
attribute DOMString? ariaColCount;
13652+
attribute DOMString? ariaColIndex;
13653+
attribute DOMString? ariaColIndexText;
13654+
attribute DOMString? ariaColSpan;
13655+
<!-- attribute FrozenArray&lt;Element&gt;? ariaControlsElements; -->
13656+
attribute DOMString? ariaCurrent;
13657+
<!-- attribute FrozenArray&lt;Element&gt;? ariaDescribedByElements; -->
13658+
attribute DOMString? ariaDescription;
13659+
<!-- attribute FrozenArray&lt;Element&gt;? ariaDetailsElements; -->
13660+
attribute DOMString? ariaDisabled;
13661+
<!-- attribute Element? ariaErrorMessageElement; -->
13662+
attribute DOMString? ariaExpanded;
13663+
<!-- attribute FrozenArray&lt;Element&gt;? ariaFlowToElements; -->
13664+
attribute DOMString? ariaHasPopup;
13665+
attribute DOMString? ariaHidden;
13666+
attribute DOMString? ariaInvalid;
13667+
attribute DOMString? ariaKeyShortcuts;
13668+
attribute DOMString? ariaLabel;
13669+
<!-- attribute FrozenArray&lt;Element&gt;? ariaLabelledByElements; -->
13670+
attribute DOMString? ariaLevel;
13671+
attribute DOMString? ariaLive;
13672+
attribute DOMString? ariaModal;
13673+
attribute DOMString? ariaMultiLine;
13674+
attribute DOMString? ariaMultiSelectable;
13675+
attribute DOMString? ariaOrientation;
13676+
<!-- attribute FrozenArray&lt;Element&gt;? ariaOwnsElements; -->
13677+
attribute DOMString? ariaPlaceholder;
13678+
attribute DOMString? ariaPosInSet;
13679+
attribute DOMString? ariaPressed;
13680+
attribute DOMString? ariaReadOnly;
13681+
<!-- attribute DOMString? ariaRelevant; -->
13682+
attribute DOMString? ariaRequired;
13683+
attribute DOMString? ariaRoleDescription;
13684+
attribute DOMString? ariaRowCount;
13685+
attribute DOMString? ariaRowIndex;
13686+
attribute DOMString? ariaRowIndexText;
13687+
attribute DOMString? ariaRowSpan;
13688+
attribute DOMString? ariaSelected;
13689+
attribute DOMString? ariaSetSize;
13690+
attribute DOMString? ariaSort;
13691+
attribute DOMString? ariaValueMax;
13692+
attribute DOMString? ariaValueMin;
13693+
attribute DOMString? ariaValueNow;
13694+
attribute DOMString? ariaValueText;
1365013695
};
1365113696
</pre>
1365213697

0 commit comments

Comments
 (0)