Skip to content

Commit

Permalink
Merge pull request #2532 from w3c/notes-and-warnings
Browse files Browse the repository at this point in the history 
Move-Examples: Fix notes and warnings
  • Loading branch information
@alflennik
alflennik authored Nov 17, 2022
2 parents e7adbe6 + 0d63ee3 commit 82c2831
Show file tree
Hide file tree
Showing 23 changed files with 562 additions and 455 deletions.
17 changes: 10 additions & 7 deletions content/patterns/button/button-pattern.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,16 @@ <h2>About This Pattern</h2>
</li>
<li>Menu button: as described in the <a href="../menu-button/menu-button-pattern.html">menu button pattern</a>, a button is revealed to assistive technologies as a menu button if it has the property <a href="#aria-haspopup" class="property-reference">aria-haspopup</a> set to either <code>menu</code> or <code>true</code>.</li>
</ul>
<p class="note">
The types of actions performed by buttons are distinctly different from the function of a link (see <a href="../link/link-pattern.html">link pattern</a>).
It is important that both the appearance and role of a widget match the function it provides.
Nevertheless, elements occasionally have the visual style of a link but perform the action of a button.
In such cases, giving the element role <code>button</code> helps assistive technology users understand the function of the element.
However, a better solution is to adjust the visual design so it matches the function and ARIA role.
</p>
<div class="note">
<h3>Note</h3>
<p>
The types of actions performed by buttons are distinctly different from the function of a link (see <a href="../link/link-pattern.html">link pattern</a>).
It is important that both the appearance and role of a widget match the function it provides.
Nevertheless, elements occasionally have the visual style of a link but perform the action of a button.
In such cases, giving the element role <code>button</code> helps assistive technology users understand the function of the element.
However, a better solution is to adjust the visual design so it matches the function and ARIA role.
</p>
</div>
</section>

<section id="examples">
Expand Down
134 changes: 74 additions & 60 deletions content/patterns/combobox/combobox-pattern.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@ <h3>Combobox Keyboard Interaction</h3>
</li>
</ul>
<div class="note">
<h4>Note</h4>
<p>Standard single line text editing keys appropriate for the device platform:</p>
<ol>
<li>include keys for input, cursor movement, selection, and text manipulation.</li>
Expand Down Expand Up @@ -198,13 +199,16 @@ <h3>Listbox Popup Keyboard Interaction</h3>
<li><kbd>Backspace</kbd> (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</li>
</ul>
<ol class="note">
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the listbox using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the combobox value.</li>
</ol>
<div class="note">
<h4>Note</h4>
<ol>
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the listbox using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the combobox value.</li>
</ol>
</div>
<h3>Grid Popup Keyboard Interaction</h3>
<p>
In a grid popup, each suggested value may be represented by either a single cell or an entire row.
Expand Down Expand Up @@ -268,35 +272,38 @@ <h3>Grid Popup Keyboard Interaction</h3>
<li><kbd>Backspace</kbd> (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.</li>
<li><kbd>Delete</kbd> (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.</li>
</ul>
<ol class="note">
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the grid using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>The grid allows only one suggested value to be selected at a time for the combobox value.</li>
<li>
In a grid popup, each suggested value may be represented by either a single cell or an entire row.
This aspect of design effects focus and selection movement:
<ol>
<li>
If every cell contains a different suggested value:
<ul>
<li>Selection follows focus so that the cell containing focus is selected.</li>
<li>Horizontal arrow key navigation typically wraps from one row to another.</li>
<li>Vertical arrow key navigation typically wraps from one column to another.</li>
</ul>
</li>
<li>
If all cells in a row contain information about the same suggested value:
<ul>
<li>Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.</li>
<li>Horizontal key navigation may wrap from one row to another.</li>
<li>Vertical arrow key navigation <strong>does not</strong> wrap from one column to another.</li>
</ul>
</li>
</ol>
</li>
</ol>
<div class="note">
<h4>Note</h4>
<ol>
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the grid using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>The grid allows only one suggested value to be selected at a time for the combobox value.</li>
<li>
In a grid popup, each suggested value may be represented by either a single cell or an entire row.
This aspect of design effects focus and selection movement:
<ol>
<li>
If every cell contains a different suggested value:
<ul>
<li>Selection follows focus so that the cell containing focus is selected.</li>
<li>Horizontal arrow key navigation typically wraps from one row to another.</li>
<li>Vertical arrow key navigation typically wraps from one column to another.</li>
</ul>
</li>
<li>
If all cells in a row contain information about the same suggested value:
<ul>
<li>Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.</li>
<li>Horizontal key navigation may wrap from one row to another.</li>
<li>Vertical arrow key navigation <strong>does not</strong> wrap from one column to another.</li>
</ul>
</li>
</ol>
</li>
</ol>
</div>
<h3>Tree Popup Keyboard Interaction</h3>
<p>
In some implementations of tree popups, some or all parent nodes may serve as suggestion category labels so may not be selectable values.
Expand Down Expand Up @@ -337,29 +344,32 @@ <h3>Tree Popup Keyboard Interaction</h3>
</ul>
</li>
</ul>
<ol class="note">
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the tree using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>The tree allows only one suggested value to be selected at a time for the combobox value.</li>
<li>
In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values.
If focus moves to a node that is not a selectable value, either:
<ul>
<li>The previously selected node, if any, remains selected until focus moves to a node that is selectable.</li>
<li>There is no selected value.</li>
<li>In either case, focus is visually distinct from selection so users can readily see if a value is selected or not.</li>
</ul>
</li>
<li>
If nodes in the tree are arranged horizontally (<a href="#aria-orientation" class="property-reference">aria-orientation</a> is set to <code>horizontal</code>):
<ol>
<li><kbd>Down Arrow</kbd> performs as <kbd>Right Arrow</kbd> is described above, and vice versa.</li>
<li><kbd>Up Arrow</kbd> performs as <kbd>Left Arrow</kbd> is described above, and vice versa.</li>
</ol>
</li>
</ol>
<div class="note">
<h4>Note</h4>
<ol>
<li>
DOM Focus is maintained on the combobox and the assistive technology focus is moved within the tree using <code>aria-activedescendant</code> as described in
<a href="../../practices/keyboard-interface/keyboard-interface-practice.html#kbd_focus_activedescendant">Managing Focus in Composites Using aria-activedescendant</a>.
</li>
<li>The tree allows only one suggested value to be selected at a time for the combobox value.</li>
<li>
In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values.
If focus moves to a node that is not a selectable value, either:
<ul>
<li>The previously selected node, if any, remains selected until focus moves to a node that is selectable.</li>
<li>There is no selected value.</li>
<li>In either case, focus is visually distinct from selection so users can readily see if a value is selected or not.</li>
</ul>
</li>
<li>
If nodes in the tree are arranged horizontally (<a href="#aria-orientation" class="property-reference">aria-orientation</a> is set to <code>horizontal</code>):
<ol>
<li><kbd>Down Arrow</kbd> performs as <kbd>Right Arrow</kbd> is described above, and vice versa.</li>
<li><kbd>Up Arrow</kbd> performs as <kbd>Left Arrow</kbd> is described above, and vice versa.</li>
</ol>
</li>
</ol>
</div>
<h3>Dialog Popup Keyboard Interaction</h3>
<p>When focus is in a dialog popup:</p>
<ul>
Expand All @@ -375,7 +385,10 @@ <h3>Dialog Popup Keyboard Interaction</h3>
</li>
<li>The dialog implements the keyboard interaction defined in the <a href="../dialog-modal/dialog-modal-pattern.html">modal dialog pattern.</a></li>
</ul>
<p class="note">Unlike other combobox popups, dialogs do not support <code>aria-activedescendant</code> so DOM focus moves into the dialog from the combobox.</p>
<div class="note">
<h4>Note</h4>
<p>Unlike other combobox popups, dialogs do not support <code>aria-activedescendant</code> so DOM focus moves into the dialog from the combobox.</p>
</div>
</section>

<section id="roles_states_properties">
Expand Down Expand Up @@ -423,6 +436,7 @@ <h2>WAI-ARIA Roles, States, and Properties</h2>
</li>
</ul>
<div class="note">
<h3>Note</h3>
<ol>
<li>
In ARIA 1.0, the combobox referenced its popup with <a href="#aria-owns" class="property-reference">aria-owns</a> instead of <a href="#aria-controls" class="property-reference">aria-controls</a>.
Expand Down
Loading

0 comments on commit 82c2831

Please sign in to comment.