Skip to content

Commit

Permalink
updates to IDL section per discussion in #1598 (#1633)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jnurthen
jnurthen authored Nov 12, 2021
1 parent d01bdcd commit bd03476
Showing 1 changed file with 35 additions and 41 deletions.
76 changes: 35 additions & 41 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10201,11 +10201,11 @@ <h3>Value</h3>
<p>Value type of the <a>state</a> or <a>property</a>. The value may be one of the following types:</p>
<dl>
<dt id="valuetype_true-false">true/false</dt>
<dd>Enumerated value representing either <code>true</code> or <code>false</code>. The default value for this value type is <code>false</code> unless otherwise specified.</dd>
<dd>Value representing either <code>true</code> or <code>false</code>. The default value for this value type is <code>false</code> unless otherwise specified.</dd>
<dt id="valuetype_tristate">tristate</dt>
<dd>Enumerated value representing <code>true</code>, <code>false</code>, <code>mixed</code>, or <code>undefined</code> values. The default value for this value type is <code>undefined</code> unless otherwise specified.</dd>
<dd>Value representing <code>true</code>, <code>false</code>, <code>mixed</code>, or <code>undefined</code> values. The default value for this value type is <code>undefined</code> unless otherwise specified.</dd>
<dt id="valuetype_true-false-undefined">true/false/undefined</dt>
<dd>Enumerated value representing <code>true</code>, <code>false</code>, or <code>undefined</code> (not applicable). The default value for this value type is <code>undefined</code> unless otherwise specified. For example, an element with <sref>aria-expanded</sref> set to <code>false</code> is not currently expanded; an element with <sref>aria-expanded</sref> set to <code>undefined</code> is not expandable.</dd>
<dd>Value representing <code>true</code>, <code>false</code>, or <code>undefined</code> (not applicable). The default value for this value type is <code>undefined</code> unless otherwise specified. For example, an element with <sref>aria-expanded</sref> set to <code>false</code> is not currently expanded; an element with <sref>aria-expanded</sref> set to <code>undefined</code> is not expandable.</dd>
<dt id="valuetype_idref">ID reference</dt>
<dd>Reference to the ID of another <a>element</a> in the same document</dd>
<dt id="valuetype_idref_list">ID reference list</dt>
Expand All @@ -10217,56 +10217,50 @@ <h3>Value</h3>
<dt id="valuetype_string">string</dt>
<dd>Unconstrained value type.</dd>
<dt id="valuetype_token">token</dt>
<dd>One of a limited set of allowed enumerated values. The default value is defined in each attribute's Values table, as specified in the <a href="#enumerated-attribute-values">Enumerated Attribute Values</a> section.</dd>
<dd>One of a limited set of allowed values. The default value is defined in each attribute's Values table, as specified in the <a href="#enumerated-attribute-values">Attribute Values</a> section.</dd>
<dt id="valuetype_token_list"><dfn>token list</dfn></dt>
<dd>A list of one or more tokens.</dd>
</dl>
<p>These are generic types for states and properties, but do not define specific representation. See <a href="#state_property_processing">State and Property Attribute Processing</a> for details on how these values are expressed and handled in host languages.</p>
</section>
</section>
<section id="enumerated-attribute-values">
<h2>Enumerated Attribute Values</h2>
<p>When the ARIA attribute definition includes a table enumerating the attribute's allowed <span>values</span>,
that attribute is a nullable <a data-cite="html/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. </p>
<section>
<h2>ARIA Attributes</h2>
<section id="enumerated-attribute-values">
<h3>Multi-value Attribute Values</h3>
<p>When the ARIA attribute definition includes a table listing the attribute's allowed <span>values</span>,
that attribute is a multi-value nullable attribute.
Each value in the table is a keyword for the attribute, mapping to a state of the same name. </p>
</section>
<section id="idl-reflection-attribute-values">
<h3>IDL reflection of ARIA attributes</h3>
<p>All ARIA attributes reflect in IDL as [=nullable type|nullable=] {{DOMString}} attributes.
This includes the boolean-like enumerated <a href="#valuetype_true-false">true/false</a> type, and all other ARIA enumerated attributes.</p>
This includes the boolean-like <a href="#valuetype_true-false">true/false</a> type, and all other ARIA attributes.</p>
<p>Default values from the ARIA values tables MUST NOT reflect to IDL as the
<a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> or the
<a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> for the attribute.
On getting, a missing ARIA attribute will return <code>null</code>. ARIA attributes are not validated on get.
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>
</section>
<section id="os-aapi-attribute-mapping">
<h3>Operating System Accessibility API mapping of ARIA enumerated attributes</h3>
<p>Unlike IDL reflection, operating system accessibility API mappings of ARIA enumerated attributes do have defaults.
The default values from the ARIA values tables are exposed to the operating system accessibility API as described in
<h3>Operating System Accessibility API mapping of multi-value ARIA attributes</h3>
<p>Unlike IDL reflection, operating system accessibility API mappings of ARIA attributes can have defaults.
Any default values from the ARIA values tables are exposed to the operating system accessibility API as described in
[[[#supportedState]]], and in [[[CORE-AAM]]].</p>
</section>
<section id="enumerated-attribute-values-html">
<h3>ARIA Enumerated Attributes in HTML</h3>
<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>
<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>
<div class="note informative" data-cite="HTML">
<p>Below is a copy of the HTML specification text for [=nullable type|nullable=] {{DOMString}} IDL attributes as of September 3, 2021.
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>

<blockquote>
a reflecting IDL attribute is a nullable {{DOMString}}
attribute whose content attribute is an <a data-cite="html/common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>, then, on getting, if
the corresponding content attribute is in its <i>missing value default</i> state then the IDL
attribute must return null, otherwise, the IDL attribute must return the keyword value associated
with the state the attribute is in. If there are multiple keyword values for the state, then
return the conforming one. If there are multiple conforming keyword values, then one will be
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
null, the content attribute must be removed, and otherwise, the content attribute must be set to
the specified new value.
</blockquote>
</div>
<h3>ARIA nullable DOMString Attributes</h3>
<p>As noted in [[[#typemapping]]], attributes are included in host languages, and the syntax for representation of WAI-ARIA types is governed by the host language.</p>
<p>The following algorithm should be used for ARIA nullable {{DOMString}} attributes in HTML:</p>
<p>On getting, if the corresponding content attribute is not present, then the IDL attribute must return null,
otherwise, the IDL attribute must get the value in a transparent, case-preserving manner.
On setting, if the new value is null, the content attribute must be removed, and otherwise,
the content attribute must be set to the specified new value in a transparent, case-preserving manner.</p>
<p class="note">
Note: As of ARIA 1.2, all ARIA attributes exposed via IDL are defined as nullable {{DOMStrings}}. This matches the current implementation of all major rendering engines. This specification change should result in no implementation changes; it will merely represent the current reality of web engines.
However, in a future draft, the ARIA Working Group intends to change several ARIA attributes to non-nullable DOMStrings, and seek implementations. The proposed change will bring ARIA into alignment with the HTML’s usage of <a data-cite="html/common-microsyntaxes.html#enumerated-attribute">enumerated attributes</a>.</p>
<section class="informative" id="enumeration-example">
<h4>Example Enumerated Attribute Usage</h4>
<h4>Example Attribute Usage</h4>
<aside class="example">

<!-- ReSpec needs these examples to be unindented. -->
Expand All @@ -10286,7 +10280,7 @@ <h4>Example Enumerated Attribute Usage</h4>

<!-- ReSpec needs these examples to be unindented. -->
<pre>// aria-busy example
// true/false ~ enumerated boolean-like nullable string; returns null unless set
// true/false ~ boolean-like nullable string; returns null unless set

el.ariaBusy; // null

Expand All @@ -10298,16 +10292,16 @@ <h4>Example Enumerated Attribute Usage</h4>
el.removeAttribute("aria-busy");
el.ariaBusy; // null

// Assignment of invalid "busy" value results in invalid value default: string "false".
// Assignment of invalid "busy" value. Not validated on set or get and the literal string value "busy" is returned.
el.setAttribute("aria-busy", "busy");
el.ariaBusy; // "false"</pre>
el.ariaBusy; // "busy"</pre>

</aside>
<aside class="example">

<!-- ReSpec needs these examples to be unindented. -->
<pre>// aria-pressed example
// Tristate ~ enumerated true/false/mixed/undefined string; null if unspecified
// Tristate ~ true/false/mixed/undefined string; null if unspecified

// no value has been defined
button.ariaPressed; // null
Expand All @@ -10318,7 +10312,7 @@ <h4>Example Enumerated Attribute Usage</h4>
button.ariaPressed = "false"; // DOM property assignment.
button.ariaPressed; // "false"

// Assignment of invalid "foo" value. Not validated on get and the literal string value "foo" is returned.
// Assignment of invalid "foo" value. Not validated on set or get and the literal string value "foo" is returned.
button.ariaPressed = "foo";
button.ariaPressed; // "foo" (Note: button is no longer a toggle button.)

Expand Down Expand Up @@ -11137,7 +11131,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<sdef>aria-current</sdef>
<div class="state-description">
<p><a>Indicates</a> the <a>element</a> that represents the current item within a container or set of related elements.</p>
<p>The <sref>aria-current</sref> <a>attribute</a> is an enumerated type. Any value not included in the list of allowed values SHOULD be treated by <a>assistive technologies</a> as if the value <code>true</code> had been provided. If the attribute is not present or its value is an empty string or <code>undefined</code>, the default value of <code>false</code> applies and the <sref>aria-current</sref> <a>state</a> MUST NOT be exposed by user agents or assistive technologies.</p>
<p>The <sref>aria-current</sref> <a>attribute</a> is a token type. Any value not included in the list of allowed values SHOULD be treated by <a>assistive technologies</a> as if the value <code>true</code> had been provided. If the attribute is not present or its value is an empty string or <code>undefined</code>, the default value of <code>false</code> applies and the <sref>aria-current</sref> <a>state</a> MUST NOT be exposed by user agents or assistive technologies.</p>
<p>The <sref>aria-current</sref> attribute is used when an element within a set of related elements is visually styled to indicate it is the current item in the set. For example:</p>
<ul>
<li>A <code>page</code> token used to indicate a link within a set of pagination links, where the link is visually styled to represent the currently-displayed page.</li>
Expand Down Expand Up @@ -11706,7 +11700,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p><a>Indicates</a> the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an <a>element</a>.</p>
<p>A popup element usually appears as a block of content that is on top of other content. Authors MUST ensure that the role of the element that serves as the container for the popup content is <rref>menu</rref>, <rref>listbox</rref>, <rref>tree</rref>, <rref>grid</rref>, or <rref>dialog</rref>, and that the value of <code>aria-haspopup</code> matches the role of the popup container.</p>
<p>For the popup element to be keyboard accessible, authors SHOULD ensure that the element that can trigger the popup is focusable, that there is a keyboard mechanism for opening the popup, and that the popup element manages focus of all its descendants as described in <a href="#managingfocus">Managing Focus</a>.</p>
<p>The <code>aria-haspopup</code> property is an enumerated type. <a>User agents</a> MUST treat any value of <code>aria-haspopup</code> that is not included in the list of allowed values, including an empty string, as if the value <code>false</code> had been provided. To provide backward compatibility with ARIA 1.0 content, user agents MUST treat an <code>aria-haspopup</code> value of <code>true</code> as equivalent to a value of <code>menu</code>.</p>
<p>The <code>aria-haspopup</code> property is a token type. <a>User agents</a> MUST treat any value of <code>aria-haspopup</code> that is not included in the list of allowed values, including an empty string, as if the value <code>false</code> had been provided. To provide backward compatibility with ARIA 1.0 content, user agents MUST treat an <code>aria-haspopup</code> value of <code>true</code> as equivalent to a value of <code>menu</code>.</p>
<p><a>Assistive technologies</a> SHOULD NOT expose the <code>aria-haspopup</code> property if it has a value of <code>false</code>.</p>
<p class="note">A <rref>tooltip</rref> is not considered to be a popup in this context.</p>
<p class="note"><code>aria-haspopup</code> is most relevant to use when there is a visual indicator in the element that triggers the popup.
Expand Down Expand Up @@ -11851,7 +11845,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p><a>Indicates</a> the entered value does not conform to the format expected by the application. See related <pref>aria-errormessage</pref>.</p>
<p>If the value is computed to be invalid or out-of-range, the application author SHOULD set this <a>attribute</a> to <code>true</code>. <a>User agents</a> SHOULD inform the user of the error. Application authors SHOULD provide suggestions for corrections if they are known.</p>
<p>When the user attempts to submit data involving a field for which <pref>aria-required</pref> is <code>true</code>, authors MAY use the <sref>aria-invalid</sref> attribute to signal there is an error. However, if the user has not attempted to submit the form, authors SHOULD NOT set the <sref>aria-invalid</sref> attribute on required <a>widgets</a> simply because the user has not yet entered data.</p>
<p>For future expansion, the <sref>aria-invalid</sref> attribute is an enumerated type. Any value not recognized in the list of allowed <span>values</span> MUST be treated by user agents as if the value <code>true</code> had been provided. If the attribute is not present, or its value is <code>false</code>, or its value is an empty string, the default value of <code>false</code> applies.</p>
<p>For future expansion, the <sref>aria-invalid</sref> attribute is a token type. Any value not recognized in the list of allowed <span>values</span> MUST be treated by user agents as if the value <code>true</code> had been provided. If the attribute is not present, or its value is <code>false</code>, or its value is an empty string, the default value of <code>false</code> applies.</p>
<p class="note">This state is being deprecated as a global state in ARIA 1.2. In future versions it will only be allowed on roles where it is specifically supported.</p>
</div>
<table class="state-features">
Expand Down

0 comments on commit bd03476

Please sign in to comment.