From 70c1dc204e6ae979a3b5f02da67c696d2dd8322d Mon Sep 17 00:00:00 2001
From: Matt King <a11yThinker@gmail.com>
Date: Thu, 9 Feb 2017 14:43:19 -0800
Subject: [PATCH] Editorial, Template, and Functional Updates to Example of
 Tabs With Manual Activation

modified examples/tabs/tabs-2/tabs.html:
1. Move examples.js script element to head and fix src attribute path so HTML source will display.
2. Make H1 content match page title.
3. Editorial revisions to introduction.
4. Correct href of link to tabs design pattern in introduction.
5. Added link to section that provides guidance on selection follows focus.
6. Per example template, Removed region around example and replaced with screen reader sepearator elements.
7. Added `aria-label="Entertainment"` to the tablist.
8. Added `tabindex="0"` to the tabpanel elements
9. Editorial revisions to the keyboard table.
10. Remove delete from keyboard table since it is not supported.
11. In roles, states and properties table:
    * added scope attribute and TH elements per template.
    * Added row for aria-label on tablist
    * Added rows for aria-selected true and false on tab
    * Added row for aria-labelledby on tabpanel
    * Added row for tabindex on tabpanel.
12. Per template, Added screen reader separators around HTML source display and removed role region from the source code display div.
13. Corrected href attribute of link to tabs design pattern in footer nav.
14. Added link to review issue #279.
---
 examples/tabs/tabs-2/tabs.html | 276 ++++++++++++++++++++++-----------
 1 file changed, 187 insertions(+), 89 deletions(-)
diff --git a/examples/tabs/tabs-2/tabs.html b/examples/tabs/tabs-2/tabs.html
index f4711179f3..5c622eb25c 100644
--- a/examples/tabs/tabs-2/tabs.html
+++ b/examples/tabs/tabs-2/tabs.html
@@ -2,79 +2,60 @@
 <html lang="en">
   <head>
     <meta charset="utf-8" />
-    <!--
-      An example that was implemented with this template can be found in: examples/checkbox/checkbox-1.html.
-      This template is for examples where only one implementation of the design pattern is demonstrated.
-      If you use this template file, rename it to reflect the name of the example, e.g., SimpleCheckbox.html.
-      Similarly, rename the javascript and CSS stub files in the js and css subdirectories and update the head element of this file.
-    -->
-
-    <!--  Give this example implementation a name and put it in the title element, e.g., "Checkbox" if implementing the checkbox pattern.
-    The name should be unique if the pattern will have multiple implementations, e.g., "Simple Two-State Checkbox" or "Three-State Checkbox".
-    -->
     <title>Tabs With Manual Activation | WAI-ARIA Authoring Practices 1.1</title>
 
     <!--  Core js and css shared by all examples; do not modify when using this template. -->
     <link href="../../css/core.css" rel="stylesheet">
     <link href="../../css/table.css" rel="stylesheet">
+    <script src="../../js/examples.js" type="text/javascript"></script>
 
-    <!--  js and css for this example.
-    When developing an example implementation of a design pattern,
-    these files will contain the CSS and JS for the example implementation.
-    Rename these files to match the name of the example, e.g., checkbox.js if implementing the checkbox design pattern.
-    -->
+    <!--  js and css for this example. -->
     <link href="css/tabs.css" rel="stylesheet">
   </head>
   <body>
     <main>
-      <!--  Repeat the name of the example in this H1  -->
-      <h1>Tabs (Manual activation)</h1>
-
+      <h1>Tabs With Manual Activation</h1>
       <p>
-          <!-- Provide an overview of the example where the first sentence provides a link to the section of aria-practices.html that describes the pattern this example implements. -->
-          The below example section demonstrates a tabs widget that implements the  <a href="../../#checkbox">design pattern for tabs</a>.
-          In this example panels are shown after you activate a tab with either <kbd>space</kbd>, <kbd>enter</kbd>, or a click.
+        Please provide feedback on updates to this page in 
+        <a href="https://github.com/w3c/aria-practices/issues/279">issue 279.</a>
+      </p>
+      <p>
+          The below example section demonstrates a tabs widget that implements the  <a href="../../../#tabpanel">tabs design pattern</a>.
+          In this example,  a new panel is displayed only after the user activates a tab with either <kbd>Space</kbd>, <kbd>Enter</kbd>, or a mouse click.
+          Typically, manual activation of tabs is only necessary when panels cannot be displayed instantly, i.e., not all the panel content is present in the DOM.
+          For additional guidance, see <a href="../../../#kbd_selection_follows_focus">Deciding When to Make Selection Automatically Follow Focus</a>.
       </p>
-
       <p>Similar examples include: </p>
       <ul>
         <li><a href="../tabs-1/tabs.html">Tabs With Automatic Activation</a>: A tabs widget where tabs are automatically activated and their panel is displayed when they receive focus.</li>
-        <!--  list other examples that implement the same design pattern. -->
       </ul>
 
       <section>
         <h2 id="ex_label">Example</h2>
-        <div  aria-labelledby="ex_label" role="region">
-          <!--
-          Note the ID of the following div that contains the example HTML is used as a parameter for the sourceCode.add() function.
-          The sourceCode functions in the examples/js/examples.js render the HTML source to show it to the reader of the example page.
-          If you change the ID of this div, be sure to update the parameters of the sourceCode.add() function call, which is made following the div with id="sc1" where the HTML is render.
-          The div for the rendered HTML source is in the last section of the page.
-          -->
-          <div id="ex1">
-            <!--  Replace content of this div with the example.  -->
-            <div class="tabs">
-              <div role="tablist">
-                <button role="tab" aria-selected="true" aria-controls="nils-tab" id="nils">Nils Frahm</button>
-                <button role="tab" aria-selected="false" aria-controls="helios-tab" id="helios" tabindex="-1">Helios</button>
-                <button role="tab" aria-selected="false" aria-controls="complexcomplex" id="complex" tabindex="-1" data-deletable>Joke</button>
-              </div>
+        <div role="separator" id="ex_start_sep" aria-labelledby="ex_start_sep ex_label" aria-label="Start of"></div>
+        <div id="ex1">
+          <div class="tabs">
+            <div role="tablist" aria-label="Entertainment">
+              <button role="tab" aria-selected="true" aria-controls="nils-tab" id="nils">Nils Frahm</button>
+              <button role="tab" aria-selected="false" aria-controls="helios-tab" id="helios" tabindex="-1">Helios</button>
+              <button role="tab" aria-selected="false" aria-controls="complexcomplex" id="complex" tabindex="-1" data-deletable>Joke</button>
+            </div>
 
-              <div role="tabpanel" id="nils-tab" aria-labelledby="nils">
-                <p>Nils Frahm is a German musician, composer and record producer based in Berlin. He is known for combining classical and electronic music and for an unconventional approach to the piano in which he mixes a grand piano, upright piano, Roland Juno-60, Rhodes piano, drum machine, and Moog Taurus.</p>
-              </div>
+            <div tabindex="0" role="tabpanel" id="nils-tab" aria-labelledby="nils">
+              <p>Nils Frahm is a German musician, composer and record producer based in Berlin. He is known for combining classical and electronic music and for an unconventional approach to the piano in which he mixes a grand piano, upright piano, Roland Juno-60, Rhodes piano, drum machine, and Moog Taurus.</p>
+            </div>
 
-              <div role="tabpanel" id="helios-tab" aria-labelledby="helios" hidden>
-                <p>Helios (Keith Kenniff) is an American composer, multi-instrumentalist, and electronic music producer. He composes ambient/electronic music under the moniker Helios and post-classical piano music under Goldmund. He is also one half of the indie band Mint Julep, and ambient project "A Pale Fire". Keith is also a composer for film, television, dance and performance art. In 2010 he created the record label Unseen.</p>
-              </div>
+            <div tabindex="0" role="tabpanel" id="helios-tab" aria-labelledby="helios" hidden>
+              <p>Helios (Keith Kenniff) is an American composer, multi-instrumentalist, and electronic music producer. He composes ambient/electronic music under the moniker Helios and post-classical piano music under Goldmund. He is also one half of the indie band Mint Julep, and ambient project "A Pale Fire". Keith is also a composer for film, television, dance and performance art. In 2010 he created the record label Unseen.</p>
+            </div>
 
-              <div role="tabpanel" id="complexcomplex" aria-labelledby="complex" hidden>
-                <p>Fear of complicated buildings:</p>
-                <p>A complex complex complex.</p>
-              </div>
+            <div tabindex="0" role="tabpanel" id="complexcomplex" aria-labelledby="complex" hidden>
+              <p>Fear of complicated buildings:</p>
+              <p>A complex complex complex.</p>
             </div>
           </div>
         </div>
+        <div role="separator" id="ex_end_sep" aria-labelledby="ex_end_sep ex_label" aria-label="End of"></div>
       </section>
 
       <section hidden>
@@ -90,7 +71,6 @@ <h2>Accessibility Features</h2>
 
       <section>
         <h2 id="kbd_label">Keyboard Support</h2>
-        <!--  Update the content of this table to describe which keys are implemented in this example. -->
         <table aria-labelledby="kbd_label">
           <thead>
             <tr>
@@ -99,88 +79,212 @@ <h2 id="kbd_label">Keyboard Support</h2>
             </tr>
           </thead>
           <tbody>
-            <tr>
-              <th><kbd>enter</kbd> or <kbd>space</kbd></th>
-              <td>Activates the currently focused tab and shows its panel.</td>
-            </tr>
             <tr>
               <th><kbd>tab</kbd></th>
-              <td>Moves focus to the active tab or first focusable in the tab panel.</td>
+              <td>
+                <ul>
+                  <li>When the tab list is receiving focus, places focus on the active <code>tab</code> element .</li>
+                  <li>When the tab list contains the focus, moves focus to the <code>tabpanel</code> element.</li>
+                </ul>
+              </td>
             </tr>
             <tr>
-              <th><kbd>left arrow</kbd></th>
-              <td>Moves focus to the previous tab.</td>
+              <th><kbd>Enter</kbd><br><kbd>Space</kbd></th>
+              <td>
+                When a tab has focus, activates the tab, causing its associated panel to be displayed.
+              </td>
             </tr>
             <tr>
               <th><kbd>right arrow</kbd></th>
-              <td>Moves focus to the next tab.</td>
+              <td>
+                When a tab has focus:
+                <ul>
+                  <li>Moves focus to the next tab.</li>
+                  <li>If focus is on the last tab, moves focus to the first tab.</li>
+                </ul>
+              </td>
             </tr>
             <tr>
-              <th><kbd>home</kbd></th>
-              <td>Moves focus to the first tab.</td>
+              <th><kbd>left arrow</kbd></th>
+              <td>
+                When a tab has focus:
+                <ul>
+                  <li>Moves focus to the previous tab.</li>
+                  <li>If focus is on the first tab, moves focus to the last tab.</li>
+                </ul>
+              </td>
             </tr>
             <tr>
-              <th><kbd>end</kbd></th>
-              <td>Moves focus to the last tab.</td>
+              <th><kbd>home</kbd></th>
+              <td>When a tab has focus, moves focus to the first tab.</td>
             </tr>
             <tr>
-              <th><kbd>delete</kbd></th>
-              <td>If deletion on the selected tab is allowed this will that tab element and its associated tab panel.</td>
+              <th><kbd>end</kbd></th>
+              <td>When a tab has focus, moves focus to the last tab.</td>
             </tr>
           </tbody>
         </table>
       </section>
 
       <section>
-        <h2 id="rps_label">ARIA Roles, Properties, and States</h2>
-        <!--  Update this table to describe the roles, properties, and states implemented in this example.  -->
+        <h2 id="rps_label">Role, Property, State, and Tabindex  Attributes</h2>
         <table aria-labelledby="rps_label">
           <thead>
             <tr>
-              <th>Role</th>
-              <th>Property/State</th>
-              <th>Element</th>
-              <th>Usage</th>
+              <th scope="col">Role</th>
+              <th scope="col">Attribute</th>
+              <th scope="col">Element</th>
+              <th scope="col">Usage</th>
             </tr>
           </thead>
           <tbody>
             <tr>
-              <td>tablist</td>
+              <th scope="row">
+                <code>tablist</code>
+              </th>
+              <td></td>
+              <td>
+                <code>div</code>
+              </td>
+              <td>Indicates that the element serves as a container for a set of tabs.</td>
+            </tr>
+            <tr>
+              <td></td>
+              <th scope="row">
+                <code>aria-label=<q>Entertainment</q></code>
+              </th>
+              <td>
+                <code>div</code>
+              </td>
+              <td>Provides a label that describes the purpose of the set of tabs.</td>
+            </tr>
+            <tr>
+              <th scope="row">
+                <code>tab</code>
+              </th>
               <td></td>
+              <td>
+                <code>button</code>
+              </td>
+              <td>
+                <ul>
+                  <li>Indicates the element serves as a tab control.</li>
+                  <li>
+                    Provides a title for its associated <code>tabpanel</code>.
+                  </li>
+                </ul>
+              </td>
+            </tr>
+            <tr>
               <td></td>
+              <th scope="row">
+                <code>aria-selected=<q>true</q></code>
+              </th>
+              <td>
+                <code>button</code>
+              </td>
               <td>
                 <ul>
-                  <li>Serves as the container for the set of tabs.</li>
+                  <li>Indicates the tab control is activated and its associated panel is displayed.</li>
+                  <li>Set when a user activates a tab.</li>
+                  <li>Does not change when focus moves in the <code>tablist</code>.</li>
                 </ul>
               </td>
             </tr>
             <tr>
-              <td>tab</td>
               <td></td>
+              <th scope="row">
+                <code>aria-selected=<q>false</q></code>
+              </th>
+              <td>
+                <code>button</code>
+              </td>
+              <td>
+                <ul>
+                  <li>
+                    Indicates the tab control is not active and its associated panel is <strong>NOT</strong>
+                    displayed.
+                  </li>
+                  <li>Set for all tab elements in the tab set except the active tab; the one associated with the currently displayed panel.</li>
+                </ul>
+              </td>
+            </tr>
+            <tr>
               <td></td>
+              <th scope="row">
+                <code>tabindex=<q>-1</q></code>
+              </th>
+              <td>
+                <code>button</code>
+              </td>
               <td>
                 <ul>
-                  <li>Contains title for tab panel, activates tab panel when activated.</li>
+                  <li>Removes the element from the page <kbd>Tab</kbd> sequence.</li>
+                  <li>Set when a tab is not selected so that only the selected (active) tab is in the page <kbd>Tab</kbd> sequence.</li>
+                  <li>Since an HTML <code>button</code> element is used for the tab, it is not necessary to set <code>tabindex=<q>0</q></code> on the selected (active) tab element.</li>
+                  <li>This approach to managing focus is described in the section on <a href="../../../#kbd_roving_tabindex">roving tabindex</a>.</li>
                 </ul>
               </td>
             </tr>
             <tr>
-              <td>tabpanel</td>
               <td></td>
+              <th scope="row">
+                <code>aria-controls=<q>IDREF</q></code>
+              </th>
+              <td>
+                <code>button</code>
+              </td>
+              <td>
+                Refers to the <code>tabpanel</code> element associated with the tab.
+              </td>
+            </tr>
+            <tr>
+              <th scope="row">
+                <code>tabpanel</code>
+              </th>
+              <td></td>
+              <td>
+                <code>div</code>
+              </td>
+              <td>
+                <ul>
+                  <li>Indicates the element serves as a container for tab panel content.</li>
+                  <li>
+                    Is hidden unless its associated <code>tab</code> control is activated.
+                  </li>
+                </ul>
+              </td>
+            </tr>
+            <tr>
               <td></td>
+              <th scope="row">
+                <code>aria-labelledby=<q>IDREF</q></code>
+              </th>
+              <td>
+                <code>div</code>
+              </td>
               <td>
                 <ul>
-                  <li>Contains the tab’s associated content.</li>
+                  <li>
+                    Refers to the <code>tab</code> element that controls the panel.
+                  </li>
+                  <li>Provides an accessible name for the tab panel.</li>
                 </ul>
               </td>
             </tr>
             <tr>
               <td></td>
-              <td>aria-controls</td>
-              <td>element with <code>role</code> of <code>tab</code></td>
+              <th scope="row">
+                <code>tabindex=<q>0</q></code>
+              </th>
+              <td>
+                <code>div</code>
+              </td>
               <td>
                 <ul>
-                  <li></li>
+                  <li>Puts the tabpanel in the page <kbd>Tab</kbd> sequence.</li>
+                  <li>Facilitates movement to panel content for assistive technology users.</li>
+                  <li>Especially helpful if there are panels that do not contain a focusable element.</li>
                 </ul>
               </td>
             </tr>
@@ -190,7 +294,6 @@ <h2 id="rps_label">ARIA Roles, Properties, and States</h2>
 
       <section>
         <h2>Javascript and CSS Source Code</h2>
-        <!--  After the js and css files are named with the name of this example, change the href and text of the following 2 links to refer to the appropriate js and css files.  -->
         <ul>
           <li>CSS: <a href="css/tabs.css" type="tex/css">tabs.css</a></li>
           <li>Javascript: <a href="js/tabs.js" type="text/javascript">tabs.js</a></li>
@@ -199,12 +302,9 @@ <h2>Javascript and CSS Source Code</h2>
 
       <section>
         <h2 id="sc1_label">HTML Source Code</h2>
-        <div id="sc1" aria-labelledby="sc1_label" role="region"></div>
-        <!--
-        The following script will show the reader the HTML source for the example that is in the div with ID 'ex1'.
-        It renders the HTML in the preceding div with ID 'sc1'.
-        If you change the ID of either the 'ex1' div or the 'sc1' div, be sure to update the sourceCode.add function parameters.
-        -->
+        <div role="separator" id="sc1_start_sep" aria-labelledby="sc1_start_sep sc1_label" aria-label="Start of"></div>
+        <div id="sc1"></div>
+        <div role="separator" id="sc1_end_sep" aria-labelledby="sc1_end_sep sc1_label" aria-label="End of"></div>
         <script>
           sourceCode.add('sc1', 'ex1');
           sourceCode.make();
@@ -214,12 +314,10 @@ <h2 id="sc1_label">HTML Source Code</h2>
     </main>
 
     <nav>
-      <!--  Update the pattern_ID parameter of this link to refer to the APG design pattern section related to this example.  -->
-      <a href="../../#tabpanel">Tabs Design Pattern in WAI-ARIA Authoring Practices 1.1</a>
+      <a href="../../../#tabpanel">Tabs Design Pattern in WAI-ARIA Authoring Practices 1.1</a>
     </nav>
 
-
-    <script src="../js/examples.js" type="text/javascript"></script>
     <script src="js/tabs.js" type="text/javascript"></script>
+    
   </body>
 </html>

`enter` or `space`	Activates the currently focused tab and shows its panel.
`tab`	Moves focus to the active tab or first focusable in the tab panel.	+ + When the tab list is receiving focus, places focus on the active `tab` element . + When the tab list contains the focus, moves focus to the `tabpanel` element. + +
`left arrow`	Moves focus to the previous tab.	`Enter` `Space`	+ When a tab has focus, activates the tab, causing its associated panel to be displayed. +
`right arrow`	Moves focus to the next tab.	+ When a tab has focus: + + Moves focus to the next tab. + If focus is on the last tab, moves focus to the first tab. + +
`home`	Moves focus to the first tab.	`left arrow`	+ When a tab has focus: + + Moves focus to the previous tab. + If focus is on the first tab, moves focus to the last tab. + +
`end`	Moves focus to the last tab.	`home`	When a tab has focus, moves focus to the first tab.
`delete`	If deletion on the selected tab is allowed this will that tab element and its associated tab panel.	`end`	When a tab has focus, moves focus to the last tab.
Role	Property/State	Element	Usage	Role	Attribute
tablist	+ `tablist` +		+ `div` +	Indicates that the element serves as a container for a set of tabs.
	+ `aria-label=Entertainment` +	+ `div` +	Provides a label that describes the purpose of the set of tabs.
+ `tab` +		+ `button` +	+ + Indicates the element serves as a tab control. + + Provides a title for its associated `tabpanel`. + + +
	+ `aria-selected=true` +	+ `button` +	- Serves as the container for the set of tabs. + Indicates the tab control is activated and its associated panel is displayed. + Set when a user activates a tab. + Does not change when focus moves in the `tablist`.
tab		+ `aria-selected=false` +	+ `button` +	+ + + Indicates the tab control is not active and its associated panel is NOT + displayed. + + Set for all tab elements in the tab set except the active tab; the one associated with the currently displayed panel. + +
	+ `tabindex=-1` +	+ `button` +	- Contains title for tab panel, activates tab panel when activated. + Removes the element from the page `Tab` sequence. + Set when a tab is not selected so that only the selected (active) tab is in the page `Tab` sequence. + Since an HTML `button` element is used for the tab, it is not necessary to set `tabindex=0` on the selected (active) tab element. + This approach to managing focus is described in the section on roving tabindex.
tabpanel		+ `aria-controls=IDREF` +	+ `button` +	+ Refers to the `tabpanel` element associated with the tab. +
+ `tabpanel` +		+ `div` +	+ + Indicates the element serves as a container for tab panel content. + + Is hidden unless its associated `tab` control is activated. + + +
	+ `aria-labelledby=IDREF` +	+ `div` +	- Contains the tab’s associated content. + + Refers to the `tab` element that controls the panel. + + Provides an accessible name for the tab panel.
	aria-controls	element with `role` of `tab`	+ `tabindex=0` +	+ `div` +	- + Puts the tabpanel in the page `Tab` sequence. + Facilitates movement to panel content for assistive technology users. + Especially helpful if there are panels that do not contain a focusable element.