Skip to content

Commit

Permalink
Listbox Pattern and Examples: Breakout Examples to Separate Pages
Browse files Browse the repository at this point in the history 
For issue #123, made the following changes:

* renamed: examples/listbox/listbox.html -> examples/listbox/listbox-rearrangeable.html
* listbox-rearrangeable.html:
    - Change title, Remove example 3, add similar example link
    - add intro to keyboard and roles and props sections
    - update links to source files, update source rendering code.
* renamed:examples/listbox/js/main.js -> examples/listbox/js/listbox-rearrangeable.js
* listbox-rearrangeable.js: Remove example 3 code.
* new file:examples/listbox/listbox-scrollable.html
* new file:examples/listbox/js/listbox-scrollable.js
* modified aria-practices.html: Update links to example pages and ad ID listbox_kbd_interaction.
  • Loading branch information
@mcking65
mcking65 committed Oct 6, 2017
1 parent dd6a88d commit 94e4602
Show file tree
Hide file tree
Showing 5 changed files with 304 additions and 84 deletions.
7 changes: 5 additions & 2 deletions aria-practices.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1583,10 +1583,13 @@ <h3>Listbox</h3>

<section class="notoc">
<h4>Examples</h4>
<p><a href="examples/listbox/listbox.html">Listbox Examples:</a> Two examples of the listbox pattern demonstrating differences between single-select and multi-select implementation as well as the use of action buttons with key shortcuts for arranging items in a list.</p>
<ul>
<li><a href="examples/listbox/listbox-scrollable.html">Scrollable Listbox Example</a>: Single-select listbox that scrolls to reveal more options, similar to HTML <code>select</code> with <code>size</code> attribute greater than one.</li>
<li><a href="examples/listbox/listbox-rearrangeable.html">Example Listboxes with Rearrangeable Options</a>: Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed.</li>
</ul>
</section>

<section class="notoc">
<section id="listbox_kbd_interaction" class="notoc">
<h4>Keyboard Interaction</h4>
<p>For a vertically oriented listbox:</p>
<ul>
Expand Down
0 examples/listbox/js/main.js → examples/listbox/js/listbox-rearrangeable.js
View file
File renamed without changes.
9 changes: 9 additions & 0 deletions examples/listbox/js/listbox-scrollable.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
/**
* ARIA Scrollable Listbox Example
* @function onload
* @desc Initialize the listbox example once the page has loaded
*/

window.addEventListener('load', function () {
var exListbox = new aria.Listbox(document.getElementById('ss_elem_list'));
});
136 changes: 54 additions & 82 deletions examples/listbox/listbox.html → examples/listbox/listbox-rearrangeable.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Listbox Example | WAI-ARIA Authoring Practices 1.1</title>
<title>Example Listboxes with Rearrangeable Options | WAI-ARIA Authoring Practices 1.1</title>

<!-- Core js and css shared by all examples; do not modify when using this template. -->
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/base.css">
Expand All @@ -15,14 +15,15 @@
<link href="css/listbox.css" rel="stylesheet">
<script src="js/listbox.js" type="text/javascript"></script>
<script src="js/toolbar.js" type="text/javascript"></script>
<script src="js/main.js" type="text/javascript"></script>
<script src="js/listbox-rearrangeable.js" type="text/javascript"></script>
</head>
<body>
<main>
<h1>Listbox Example</h1>
<h1>Example Listboxes with Rearrangeable Options</h1>
<p>
This example page is incomplete; it is not ready for review.
When ready, feedback will be welcome in <a href="https://github.com/w3c/aria-practices/issues/123">issue 123.</a>
<strong>NOTE:</strong> This example page is incomplete; it is not ready for final review.
Development is tracked by
<a href="https://github.com/w3c/aria-practices/issues/123">issue 123.</a>
</p>
<p>
The following two example implementations of the
Expand All @@ -32,6 +33,10 @@ <h1>Listbox Example</h1>
In the first implementation, users can choose a single option and then activate an action button
while in the second example, they may select multiple options before activating an action button.
</p>
<p>Similar examples include:</p>
<ul>
<li><a href="listbox-scrollable.html">Scrollable Listbox Example</a>: Single-select listbox that scrolls to reveal more options, similar to HTML <code>select</code> with <code>size</code> attribute greater than one.</li>
</ul>
<section>
<h2>Examples</h2>
<section>
Expand Down Expand Up @@ -160,66 +165,6 @@ <h4>Notes</h4>
<li>Users can toggle the selected state of the focused option with <kbd>Space</kbd> or click.</li>
</ol>
</section>

<section>
<h3 id="ex3_label">Example 3: Scrollable Listbox</h3>
<div role="separator" id="ex3_start_sep" aria-labelledby="ex3_start_sep ex3_label" aria-label="Start of"></div>
<div id="ex3">
<p>Choose your favorite transuranic element (actinide or transactinide).</p>
<div class="listbox-area">
<div class="left-area">
<span id="ss_elem">Transuranium elements:</span>
<ul id="ss_elem_list" tabindex="0" role="listbox" aria-labelledby="ss_elem">
<li id="ss_elem_Np" role="option">Neptunium</li>
<li id="ss_elem_Pu" role="option">Plutonium</li>
<li id="ss_elem_Am" role="option">Americium</li>
<li id="ss_elem_Cm" role="option">Curium</li>
<li id="ss_elem_Bk" role="option">Berkelium</li>
<li id="ss_elem_Cf" role="option">Californium</li>
<li id="ss_elem_Es" role="option">Einsteinium</li>
<li id="ss_elem_Fm" role="option">Fermium</li>
<li id="ss_elem_Md" role="option">Mendelevium</li>
<li id="ss_elem_No" role="option">Nobelium</li>
<li id="ss_elem_Lr" role="option">Lawrencium</li>
<li id="ss_elem_Rf" role="option">Rutherfordium</li>
<li id="ss_elem_Db" role="option">Dubnium</li>
<li id="ss_elem_Sg" role="option">Seaborgium</li>
<li id="ss_elem_Bh" role="option">Bohrium</li>
<li id="ss_elem_Hs" role="option">Hassium</li>
<li id="ss_elem_Mt" role="option">Meitnerium</li>
<li id="ss_elem_Ds" role="option">Darmstadtium</li>
<li id="ss_elem_Rg" role="option">Roentgenium</li>
<li id="ss_elem_Cn" role="option">Copernicium</li>
<li id="ss_elem_Nh" role="option">Nihonium</li>
<li id="ss_elem_Fl" role="option">Flerovium</li>
<li id="ss_elem_Mc" role="option">Moscovium</li>
<li id="ss_elem_Lv" role="option">Livermorium</li>
<li id="ss_elem_Ts" role="option">Tennessine</li>
<li id="ss_elem_Og" role="option">Oganesson</li>
</ul>
</div>
</div>
</div>
<div role="separator" id="ex3_end_sep" aria-labelledby="ex3_end_sep ex3_label" aria-label="End of"></div>
<h4>Notes</h4>
<ol>
<li>This example has a <code>listbox</code> with more options than its height can accommodate.</li>
<li>Scrolling only works as expected if the listbox is the options' <code>offsetParent</code>.
The example uses <code>position: relative</code> on the listbox to that effect.</li>
<li>When an option is focused that isn't (fully) visible, the listbox's scroll position is updated:
<ol>
<li>If <kbd>Up Arrow</kbd> or <kbd>Down Arrow</kbd> is pressed, the previous or next option is scrolled into view.</li>
<li>If <kbd>Home</kbd> or <kbd>End</kbd> is pressed, the listbox scrolls all the way to the top or to the bottom.</li>
<li>If <code>focusItem</code> is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it.</li>
<li>If the mouse is clicked on a partially visible option, it will be scrolled fully into view.</li>
</ol>
</li>
<li>When a fully visible option is focused in any way, no scrolling occurs.</li>
<li>Normal scrolling through any scrolling mechanism (including <kbd>Page Up</kbd> and <kbd>Page Down</kbd>) works as expected.
The scroll position will jump as described for <code>focusItem</code> if another means than a mouse click is used to change focus after scrolling.</li>
<li>This example uses a single-select listbox, but works just as well with a multi-select listbox.</li>
</ol>
</section>
</section>

<section>
Expand Down Expand Up @@ -256,6 +201,11 @@ <h2>Accessibility Features</h2>

<section>
<h2 id="kbd_label">Keyboard Support</h2>
<p>
The example listboxes on this page implement the following keyboard interface.
Other variations and options for the keyboard interface are described in the
<a href="../../#listbox_kbd_interaction">Keyboard Interaction section of the Listbox Design Pattern.</a>
</p>
<table aria-labelledby="kbd_label" class="def">
<thead>
<tr>
Expand All @@ -266,24 +216,44 @@ <h2 id="kbd_label">Keyboard Support</h2>
<tbody>
<tr>
<th><kbd>Down Arrow</kbd></th>
<td>Moves focus to the next option.</td>
<td>
<ul>
<li>Moves focus to the next option.</li>
<li>In the example 1 single-select listboxes, also selects the focused option.</li>
</ul>
</td>
</tr>
<tr>
<th><kbd>Up Arrow</kbd></th>
<td>Moves focus to the previous option.</td>
<td>
<ul>
<li>Moves focus to the previous option.</li>
<li>In the example 1 single-select listboxes, also selects the focused option.</li>
</ul>
</td>
</tr>
<tr>
<th><kbd>Home</kbd></th>
<td>Moves focus to first option.</td>
<td>
<ul>
<li>Moves focus to the first option.</li>
<li>In the example 1 single-select listboxes, also selects the focused option.</li>
</ul>
</td>
</tr>
<tr>
<th><kbd>End</kbd></th>
<td>Moves focus to last option.</td>
<td>
<ul>
<li>Moves focus to the last option.</li>
<li>In the example 1 single-select listboxes, also selects the focused option.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h4>Multiple selection keys supported in example 2</h4>
<table aria-labelledby="kbd_label" class="def">
<h4 id="kbd_label_multiselect">Multiple selection keys supported in example 2</h4>
<table aria-labelledby="kbd_label_multiselect" class="def">
<thead>
<tr>
<th>Key</th>
Expand Down Expand Up @@ -321,6 +291,11 @@ <h4>Multiple selection keys supported in example 2</h4>

<section>
<h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
<p>
The example listboxes on this page implement the following ARIA roles, states, and properties.
Information about other ways of applying ARIA roles, states, and properties is available in the
<a href="../../#listbox_roles_states_props">Roles, States, and Properties section of the Listbox Design Pattern.</a>
</p>
<table aria-labelledby="rps_label" class="data attributes">
<thead>
<tr>
Expand Down Expand Up @@ -407,12 +382,6 @@ <h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
</tr>
</tbody>
</table>
<h4>Note></h4>
<p>The following attributes are commonly useful when implementing the listbox design pattern but are not used in these examples.</p>
<ul>
<li><code>aria-setsize</code> and <code>aria-posinset</code>: Since all option elements are present in the DOM, the browser is able to calculate these values automatically and provide them to assistive technologies.</li>
<li><code>aria-orientation</code>: The default orientation for a listbox is vertical so it is not necessary to specify a value.</li>
</ul>
</section>

<section>
Expand All @@ -426,6 +395,14 @@ <h2>Javascript and CSS Source Code</h2>
Javascript:
<a href="js/listbox.js" type="text/javascript">listbox.js</a>
</li>
<li>
Javascript:
<a href="js/toolbar.js" type="text/javascript">toolbar.js</a>
</li>
<li>
Javascript:
<a href="js/listbox-rearrangeable.js" type="text/javascript">listbox-rearrangeable.js</a>
</li>
</ul>
</section>

Expand All @@ -441,11 +418,6 @@ <h3 id="sc2_label">Example 2: Multi-Select Listbox</h3>
<pre><code id="sc2"></code></pre>
<div id="sc2_end_sep" role="separator" aria-labelledby="sc2_end_sep sc2_label" aria-label="End of HTML for"></div>
<script>sourceCode.add('sc2', 'ex2')</script>
<h3 id="sc3_label">Example 3: Scrollable Listbox</h3>
<div id="sc3_start_sep" role="separator" aria-labelledby="sc3_start_sep sc3_label" aria-label="Start of HTML for"></div>
<pre><code id="sc3"></code></pre>
<div id="sc3_end_sep" role="separator" aria-labelledby="sc3_end_sep sc3_label" aria-label="End of HTML for"></div>
<script>sourceCode.add('sc3', 'ex3')</script>
<!-- After all source has been added, run make to do the insert. -->
<script> sourceCode.make() </script>
</section>
Expand Down
Loading

0 comments on commit 94e4602

Please sign in to comment.