Skip to content

Commit

Permalink
Added IDL Interface section (#708)
Browse files Browse the repository at this point in the history 
* Issue #691
  • Loading branch information
@cookiecrook @jnurthen
cookiecrook authored and jnurthen committed May 22, 2018
1 parent d037626 commit c040ddc
Showing 1 changed file with 180 additions and 0 deletions.
180 changes: 180 additions & 0 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10977,6 +10977,185 @@ <h2>State and Property Attribute Processing</h2>
<p>Sometimes states and properties are present in the DOM but have a zero-length string ("") as their value. This is equivalent to their absence. User agents SHOULD treat state and property attributes with a value of "" the same as they treat an absent attribute. For supported states and properties, this corresponds to the default value, but if it is a required attribute, it signals an author error, and the implicit value for the role is used. </p>
</section>
</section>
<section id="idl-interface" class="normative">
<h2>IDL Interface</h2>
<p>Conforming user agents MUST implement the following IDL interfaces.</p>
<section id="AccessibilityRole" class="normative" data-dfn-for="AccessibilityRole" data-link-for="AccessibilityRole">
<h2>Interface Mixin <dfn>AccessibilityRole</dfn></h2>
<pre class="idl">
interface mixin AccessibilityRole {
attribute DOMString? role;
};
Element includes AccessibilityRole;
</pre>
<p>User agents MUST <a href="https://www.w3.org/TR/html52/infrastructure.html#reflecting-content-attributes-in-idl-attributes">reflect</a> the <code><dfn>role</dfn></code> content attribute as the <code>role</code> IDL attribute.</p>
</section>

<section id="AriaAttributes" class="normative" data-dfn-for="AriaAttributes" data-link-for="AriaAttributes">
<h2>Interface Mixin <dfn>AriaAttributes</dfn></h2>
<pre class="idl">
interface mixin AriaAttributes {
attribute DOMString? ariaActiveDescendant;
attribute DOMString? ariaAtomic;
attribute DOMString? ariaAutoComplete;
attribute DOMString? ariaBusy;
attribute DOMString? ariaChecked;
attribute DOMString? ariaColCount;
attribute DOMString? ariaColIndex;
attribute DOMString? ariaColSpan;
attribute DOMString? ariaControls;
attribute DOMString? ariaCurrent;
attribute DOMString? ariaDescribedBy;
attribute DOMString? ariaDetails;
attribute DOMString? ariaDisabled;
attribute DOMString? ariaErrorMessage;
attribute DOMString? ariaExpanded;
attribute DOMString? ariaFlowTo;
attribute DOMString? ariaHasPopup;
attribute DOMString? ariaHidden;
attribute DOMString? ariaInvalid;
attribute DOMString? ariaKeyShortcuts;
attribute DOMString? ariaLabel;
attribute DOMString? ariaLabelledBy;
attribute DOMString? ariaLevel;
attribute DOMString? ariaLive;
attribute DOMString? ariaModal;
attribute DOMString? ariaMultiLine;
attribute DOMString? ariaMultiSelectable;
attribute DOMString? ariaOrientation;
attribute DOMString? ariaOwns;
attribute DOMString? ariaPlaceholder;
attribute DOMString? ariaPosInSet;
attribute DOMString? ariaPressed;
attribute DOMString? ariaReadOnly;
attribute DOMString? ariaRelevant;
attribute DOMString? ariaRequired;
attribute DOMString? ariaRoleDescription;
attribute DOMString? ariaRowCount;
attribute DOMString? ariaRowIndex;
attribute DOMString? ariaRowSpan;
attribute DOMString? ariaSelected;
attribute DOMString? ariaSetSize;
attribute DOMString? ariaSort;
attribute DOMString? ariaValueMax;
attribute DOMString? ariaValueMin;
attribute DOMString? ariaValueNow;
attribute DOMString? ariaValueText;
};
Element includes AriaAttributes;
</pre>
<section id="reflection" class="normative">
<h2>ARIA Attribute Reflection</h2>
<p>User agents MUST <a href="https://www.w3.org/TR/html52/infrastructure.html#reflecting-content-attributes-in-idl-attributes">reflect</a> the following content attributes to each of the corresponding IDL attributes.</p>
<table>
<tr><th>IDL Attribute</th><th>Reflected ARIA Content Attribute</th></tr>
<tr><td><dfn>ariaActiveDescendant</dfn></td><td><pref>aria-activedescendant</pref></td></tr>
<tr><td><dfn>ariaAtomic</dfn></td><td><pref>aria-atomic</pref></td></tr>
<tr><td><dfn>ariaAutoComplete</dfn></td><td><pref>aria-autocomplete</pref></td></tr>
<tr><td><dfn>ariaBusy</dfn></td><td><sref>aria-busy</sref></td></tr>
<tr><td><dfn>ariaChecked</dfn></td><td><sref>aria-checked</sref></td></tr>
<tr><td><dfn>ariaColCount</dfn></td><td><pref>aria-colcount</pref></td></tr>
<tr><td><dfn>ariaColIndex</dfn></td><td><pref>aria-colindex</pref></td></tr>
<tr><td><dfn>ariaColSpan</dfn></td><td><pref>aria-colspan</pref></td></tr>
<tr><td><dfn>ariaControls</dfn></td><td><pref>aria-controls</pref></td></tr>
<tr><td><dfn>ariaCurrent</dfn></td><td><sref>aria-current</sref></td></tr>
<tr><td><dfn>ariaDescribedBy</dfn></td><td><pref>aria-describedby</pref></td></tr>
<tr><td><dfn>ariaDetails</dfn></td><td><pref>aria-details</pref></td></tr>
<tr><td><dfn>ariaDisabled</dfn></td><td><sref>aria-disabled</sref></td></tr>
<tr><td><dfn>ariaErrorMessage</dfn></td><td><pref>aria-errormessage</pref></td></tr>
<tr><td><dfn>ariaExpanded</dfn></td><td><sref>aria-expanded</sref></td></tr>
<tr><td><dfn>ariaFlowTo</dfn></td><td><pref>aria-flowto</pref></td></tr>
<tr><td><dfn>ariaHasPopup</dfn></td><td><pref>aria-haspopup</pref></td></tr>
<tr><td><dfn>ariaHidden</dfn></td><td><sref>aria-hidden</sref></td></tr>
<tr><td><dfn>ariaInvalid</dfn></td><td><sref>aria-invalid</sref></td></tr>
<tr><td><dfn>ariaKeyShortcuts</dfn></td><td><pref>aria-keyshortcuts</pref></td></tr>
<tr><td><dfn>ariaLabel</dfn></td><td><pref>aria-label</pref></td></tr>
<tr><td><dfn>ariaLabelledBy</dfn></td><td><pref>aria-labelledby</pref></td></tr>
<tr><td><dfn>ariaLevel</dfn></td><td><pref>aria-level</pref></td></tr>
<tr><td><dfn>ariaLive</dfn></td><td><pref>aria-live</pref></td></tr>
<tr><td><dfn>ariaModal</dfn></td><td><pref>aria-modal</pref></td></tr>
<tr><td><dfn>ariaMultiLine</dfn></td><td><pref>aria-multiline</pref></td></tr>
<tr><td><dfn>ariaMultiSelectable</dfn></td><td><pref>aria-multiselectable</pref></td></tr>
<tr><td><dfn>ariaOrientation</dfn></td><td><pref>aria-orientation</pref></td></tr>
<tr><td><dfn>ariaOwns</dfn></td><td><pref>aria-owns</pref></td></tr>
<tr><td><dfn>ariaPlaceholder</dfn></td><td><pref>aria-placeholder</pref></td></tr>
<tr><td><dfn>ariaPosInSet</dfn></td><td><pref>aria-posinset</pref></td></tr>
<tr><td><dfn>ariaPressed</dfn></td><td><sref>aria-pressed</sref></td></tr>
<tr><td><dfn>ariaReadOnly</dfn></td><td><pref>aria-readonly</pref></td></tr>
<tr><td><dfn>ariaRelevant</dfn></td><td><pref>aria-relevant</pref></td></tr>
<tr><td><dfn>ariaRequired</dfn></td><td><pref>aria-required</pref></td></tr>
<tr><td><dfn>ariaRoleDescription</dfn></td><td><pref>aria-roledescription</pref></td></tr>
<tr><td><dfn>ariaRowCount</dfn></td><td><pref>aria-rowcount</pref></td></tr>
<tr><td><dfn>ariaRowIndex</dfn></td><td><pref>aria-rowindex</pref></td></tr>
<tr><td><dfn>ariaRowSpan</dfn></td><td><pref>aria-rowspan</pref></td></tr>
<tr><td><dfn>ariaSelected</dfn></td><td><sref>aria-selected</sref></td></tr>
<tr><td><dfn>ariaSetSize</dfn></td><td><pref>aria-setsize</pref></td></tr>
<tr><td><dfn>ariaSort</dfn></td><td><pref>aria-sort</pref></td></tr>
<tr><td><dfn>ariaValueMax</dfn></td><td><pref>aria-valuemax</pref></td></tr>
<tr><td><dfn>ariaValueMin</dfn></td><td><pref>aria-valuemin</pref></td></tr>
<tr><td><dfn>ariaValueNow</dfn></td><td><pref>aria-valuenow</pref></td></tr>
<tr><td><dfn>ariaValueText</dfn></td><td><pref>aria-valuetext</pref></td></tr>
</table>
<p class="note">Note: Attributes <pref>aria-dropeffect</pref> and <sref>aria-grabbed</sref> were deprecated in ARIA 1.1 and do not have corresponding IDL attributes.</p>
</section>
<section class="informative" id="idl_attr_disambiguation">
<h3>Disambiguation Pattern</h3>
<p>Though specification authors may make exceptions to this pattern, the following rules were used to disambiguate names and case of the IDL attributes listed above.</p>
<ul>
<li>Any attribute name referencing concepts that are combinations of two or more words (such as "described by") becomes a camel-cased IDL attribute capitalizing each word boundary. For example, <pref>aria-describedby</pref> becomes <code>ariaDescribedBy</code> with both the D and B capitalized.</li>
<li>Likewise, any attribute name referencing concepts that can be hyphenated (such as "multi-selectable") becomes a camel-cased IDL attribute capitalizing each hyphenation boundary. For example, the only valid spelling for "multi-selectable" is hyphenated, so <pref>aria-multiselectable</pref> becomes <code>ariaMultiSelectable</code> with both the M and S capitalized.</li>
<li>When trusted dictionary sources list both hyphenated or non-hyphenated spellings (e.g. "multi-line" and "multiline" are both valid spellings) use the hyphenated version and apply the hyphenation rule above. For example, <pref>aria-multiline</pref> becomes <code>ariaMultiLine</code> with both the M and L capitalized.</li>
<li>If all trusted dictionary sources list a single spelling of a compound word with no spaces or hyphens, only the first letter of the term is capitalized. For example, neither “place-holder” nor “place holder” are considered valid spellings of the term “placeholder,” so <pref>aria-placeholder</pref> becomes <code>ariaPlaceholder</code> with only the P capitalized.</li>
<li>There are currently no acronym-based ARIA attributes, but if future attributes include acronym usage, attempt to match existing DOM conventions (e.g. ID becomes Id).</li>
</ul>
</section>
<section class="informative" id="idl_attr_exceptions">
<h3>IDL Attribute Name Notes or Exceptions</h3>
<p>Any notes or exceptions for specific attribute names will be listed here.</p>
<ul>
<li><code>ariaPosInSet</code>: The <pref>aria-posinset</pref> attribute refers to an item's position in a set (two words: "in set") rather than the "inset" of an item from the beginning of the collection. Therefore the IDL attribute name is <code>ariaPosInSet</code> with the P, I, and second S capitalized, <em>not</em> <code>ariaPosInset</code>.</li>
</ul>
<p class="ednote">Editor's Note: Should we make an exception on the spelling of "placeholder" and capitalize the H anyway? Some developers will expect this to be <code>ariaPlaceHolder</code> despite the fact that it's not a hyphenated word.</p>
</section>
</section>

<section class="informative" id="idl_example_usage">
<h2>Example IDL Attribute Usage</h2>
<p>The primary purpose of ARIA IDL attribute reflection is to ease JavaScript-based manipulation of values. The following examples demonstrate its usage.</p>
<aside class="example">

<!-- ReSpec needs these examples to be unindented. -->
<pre>&lt;div id="inaccessibleButton"&gt;
&lt;!-- Use semantic markup instead. This is just a retrofit example. --&gt;
&lt;/div&gt;</pre>
<pre>// Get a reference to the element.
let el = document.getElementById('inaccessibleButton');
el.tabIndex = 0; // Make it focusable.

// Set the role and label.
el.role = "button";
el.ariaLabel = "Edit";

// Get the role and label.
el.role; // Returns "button"
el.ariaLabel; // Returns "Edit"

// These are interchangeable with the more verbose setAttribute and getAttribute methods.
el.setAttribute("role", "button");
el.setAttribute("aria-label", "Edit");
el.getAttribute("role"); // Returns "button"
el.getAttribute("aria-label"); // Returns "Edit"

// Changes via either interface are reflected by the other.
el.setAttribute("aria-label", "Delete");
el.ariaLabel; // Returns "Delete"
el.ariaLabel = "Publish";
el.getAttribute("aria-label"); // Returns "Publish"</pre>

</aside>
</section>

</section>
<section class="appendix informative" id="a_schemata">
<h1>Schemata</h1>
<p>WAI-ARIA roles, states, and properties are available in a number of machine-readable formats to support validation of content using WAI-ARIA attributes. WAI-ARIA is not finalized, however, so these files are subject to change without notice. <span class="todo">Todo: Remove disclaimers about not final at rec.</span></p>
Expand Down Expand Up @@ -11137,6 +11316,7 @@ <h2>Substantive changes since the last public working draft</h2>
<!-- EdNote: After each WD publish, move contents of this list into the next one below. -->
<li>06-Dec-2017: Make <sref>aria-expanded</sref> a supported state of <rref>menuitem</rref>. This change also makes it a supported property of <rref>menuitemcheckbox</rref> and <rref>menuitemradio</rref> via inheritance.</li>
<li>06-Dec-2017: When aria-errormessage is not pertinent, authors MUST either ensure the content is not rendered or remove the aria-errormessage attribute or its value. User agents MUST NOT expose <code>aria-errormessage</code> for an object with an <sref>aria-invalid</sref> value of <code>false</code>.</li>
<li>01-Apr-2018: Added ARIA IDL Section (JavaScript interfaces).</li>
</ul>
</section>
<section>
Expand Down

0 comments on commit c040ddc

Please sign in to comment.