From 1f8b9c0e4b4ce98f5f6845a92ce45e60670d233f Mon Sep 17 00:00:00 2001 From: Jon Gunderson Date: Sat, 21 Oct 2017 09:38:52 -0500 Subject: [PATCH] added discription for disclosure button --- aria-practices.html | 118 +++++++++++++++++++++++--------------------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 5f5842461c..dc409338db 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -83,14 +83,14 @@

Introduction

Read Me First

NOTE: This is a proposed draft of a new section. - Please provide feedback in + Please provide feedback in issue 482.

No ARIA is better than Bad ARIA

- Functionally, ARIA roles, states, and properties are sort of like CSS for assistive technologies. - In the case of screen readers, ARIA controls the rendering of the non-visual experience. + Functionally, ARIA roles, states, and properties are sort of like CSS for assistive technologies. + In the case of screen readers, ARIA controls the rendering of the non-visual experience. Incorrect ARIA misrepresents visual experiences, with potentially devastating effects on the corresponding non-visual experiences.

Before using ARIA or any of the guidance in this document, please take time to understand the following two essential principles.

@@ -120,11 +120,11 @@

Principle 2: ARIA Can Both Cloak and Enhance, Creating Both Power and Danger <button aria-pressed="false">Press Me</button>

- This is the power of ARIA. + This is the power of ARIA. It enables authors to describe nearly any user interface component in ways that assistive technologies can reliably interpret, thus making components accessible to assistive technology users.

- This is also the danger of ARIA. + This is also the danger of ARIA. Authors can inadvertently override accessibility semantics. 

@@ -147,23 +147,23 @@ 
Principle 2: ARIA Can Both Cloak and Enhance, Creating Both Power and Danger
     

       
Browser and Assistive Technology Support

       

-        This guide illustrates appropriate use of ARIA 1.1 as defined in the ARIA specification. 
+        This guide illustrates appropriate use of ARIA 1.1 as defined in the ARIA specification.
         The design patterns, reference examples, and sample code intentionally do not implement code to fix problems that are caused by gaps in support for ARIA 1.1 in browsers or assistive technologies.
         Browser and assistive technology developers can thus utilize code in this guide to help assess the quality of their support for ARIA 1.1.
       

       

-        Similarly, JavaScript and CSS in this guide is written to be compatible with the most recent version of Chrome, Firefox, Internet Explorer, and Safari at the time of writing. 
+        Similarly, JavaScript and CSS in this guide is written to be compatible with the most recent version of Chrome, Firefox, Internet Explorer, and Safari at the time of writing.
         In particular, some JavaScript and CSS may not function correctly in Internet Explorer version 10 or earlier.
       

       

-        In other words, except in cases where the ARIA Working Group and other contributors have overlooked an error, 
+        In other words, except in cases where the ARIA Working Group and other contributors have overlooked an error,
         examples in this guide that do not function well in a particular browser or with a specific assistive technology are demonstrating browser or assistive technology bugs.
       

     

     

       
Mobile and Touch Support

       

-        Currently, this guide does not indicate which examples are compatible with mobile browsers or touch interfaces. 
+        Currently, this guide does not indicate which examples are compatible with mobile browsers or touch interfaces.
         While some of the examples include specific features that enhance mobile and touch support, some ARIA features are not supported in any mobile browser.
         In addition, there is not yet a standardized approach for providing touch interactions that work across mobile browsers.
       

@@ -565,13 +565,13 @@ 
Combo Box

         issue 464.
       

       

-        A combobox is a widget made up of the combination of two distinct elements: 
+        A combobox is a widget made up of the combination of two distinct elements:
         1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox.
-        The popup may be a listbox, 
-        grid, 
-        tree, or 
+        The popup may be a listbox,
+        grid,
+        tree, or
         dialog.
-        Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. 
+        Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup.
         Activating the button displays the popup if suggestions are available.
       

       

@@ -582,22 +582,22 @@ 
Combo Box

       
Combobox widgets are useful for setting the value of a single-line textbox in one of two types of scenarios:

       
    
         
  1. 
-          The value for the textbox must be chosen from a predefined set of allowed values, 
-          e.g., a location field must contain a valid location name. 
+          The value for the textbox must be chosen from a predefined set of allowed values,
+          e.g., a location field must contain a valid location name.
           Note that the listbox and menu button patterns are also useful in this scenario; differences between combobox and alternative patterns are described below.
         
    2. 
         
  2. 
-          The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user, 
+          The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user,
           e.g., a search field may suggest similar or previous searches to save the user time.
         
    3. 
       

       

-        The nature of the suggested values and the way the suggestions are presented is called the autocomplete behavior. 
-        Comboboxes can have one of four forms of autocomplete: 
+        The nature of the suggested values and the way the suggestions are presented is called the autocomplete behavior.
+        Comboboxes can have one of four forms of autocomplete:
       

       
    
         
  1. 
-          No autocomplete: When the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the textbox. 
+          No autocomplete: When the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the textbox.
           For example, the popup suggests a set of recently entered values, and the suggestions  do not change as the user types.
         
    2. 
         
  2. 
@@ -605,24 +605,24 @@ 
    Combo Box
    
           The character string the user has typed will become the value of the textbox unless the user selects a value in the popup.
         
    3. 
         
  3. 
-          List autocomplete with automatic selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox, 
+          List autocomplete with automatic selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox,
           and the first suggestion is automatically highlighted as selected.
            The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox.
         
    4. 
         
  4. 
-          List with inline autocomplete: This is the same as list with automatic selection with one additional feature. 
-          The portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox. 
+          List with inline autocomplete: This is the same as list with automatic selection with one additional feature.
+          The portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox.
           The inline completion string is visually highlighted and has a selected state.
         
    5. 
       

       

-        With any form of list autocomplete, the popup may appear and disappear as the user types. 
-        For example, if the user types a two character string that triggers five suggestions to be displayed but then types a third character that forms a string that does not have any matching suggestions, 
+        With any form of list autocomplete, the popup may appear and disappear as the user types.
+        For example, if the user types a two character string that triggers five suggestions to be displayed but then types a third character that forms a string that does not have any matching suggestions,
         the popup may close and, if present, the inline completion string disappears.
       

       

         When constructing a compact widget that asks users to choose one value from a known set of discrete values, often either a listbox or menu button is simpler to implement and use.
-        One feature of combobox that distinguishes it from both listbox and menu button is that the value of the combobox is presented in an edit field. 
+        One feature of combobox that distinguishes it from both listbox and menu button is that the value of the combobox is presented in an edit field.
         Thus, the combobox gives users one function that both listbox and menu button lack, namely the ability to select some or all of the value for copying to the clipboard.
         A feature that distinguishes both combobox and menu button from listbox is that they can enable users can navigate the set of allowed values and, at any point, decide to keep the current value by pressing escape.
         In contrast, navigating a listbox immediately changes its value, and escape does not provide an undo mechanism.
@@ -630,10 +630,10 @@ 
Combo Box

       

         The options for a combobox to popup a grid, tree, or dialog were introduced in ARIA 1.1.
         Changes made in the ARIA 1.1 specification also add support for a code pattern that enables assistive technologies to present the textbox and popup as separately perceivable elements.
-        While the ARIA 1.1 pattern is recommended, both patterns are described in the following sections, 
+        While the ARIA 1.1 pattern is recommended, both patterns are described in the following sections,
         and there are no plans to deprecate the ARIA 1.0 pattern.
       

-      
+
       

         
Examples

         
    
@@ -652,7 +652,7 @@ 
    Keyboard Interaction
    
         
    Textbox Keyboard Interaction
    
         
    When focus is in the textbox:
    
         
      
-          
    • Down Arrow: If the popup is available, moves focus into the popup: 
+          
    • Down Arrow: If the popup is available, moves focus into the popup:
             
        
               
      • If the autocomplete behavior automatically selected a suggestion before Down Arrow was pressed, focus is placed on the suggestion following the automatically selected suggestion.
        • 
               
      • Otherwise, places focus on the first focusable element in the popup.
        • 
@@ -666,7 +666,7 @@ 
        Textbox Keyboard Interaction
        
           
           
      • Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.
        • 
           
      • Standard single line text editing keys appropriate for the device platform (see note below).
        • 
-          
      • Alt + Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.
        •  
+          
      • Alt + Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.
        • 
           
      • Alt + Up Arrow (Optional): If the popup is displayed:
             
          
               
        1. If the popup contains focus, returns focus to the textbox.
          2. 
@@ -687,11 +687,11 @@ 
          Listbox Popup Keyboard Interaction
          
           
        2. Enter: Accepts the focused option in the listbox by closing the popup and placing the accepted value in the textbox with the input cursor at the end of the value.
          3. 
           
        3. Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
          4. 
           
        4. 
-            Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right. 
+            Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right.
             If the input cursor is on the right-most character, the cursor does not move.
-          
          5.  
+          
           
        5. 
-            Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left. 
+            Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left.
             If the input cursor is on the left-most character, the cursor does not move.
           
          6. 
           
        6. Any printable character: Returns the focus to the textbox without closing the popup and types the character.
          7. 
@@ -818,7 +818,7 @@ 
          Tree Popup Keyboard Interaction
          
             
            
               
          • The previously selected node, if any, remains selected until focus moves to a node that is selectable.
            • 
               
          • There is no selected value.
            • 
-              
          • In either case, focus is fisually distinct from selection so users can readily see if a value is selected or not.
            •  
+              
          • In either case, focus is fisually distinct from selection so users can readily see if a value is selected or not.
            • 
             
          
         
           
        7. If the nodes in a tree are arranged horizontally:
@@ -835,7 +835,7 @@ 
          Dialog Popup Keyboard Interaction
          
             
            
               
          1. Perform an action in the dialog, such as activate a button, that specifies a value for the textbox.
            2. 
               
          2. 
-                Cancel out of the dialog, e.g., press Escape or activate the cancel button in the dialog. 
+                Cancel out of the dialog, e.g., press Escape or activate the cancel button in the dialog.
                 Canceling either returns focus to the text box without changing the textbox value or returns focus to the textbox and clears the textbox.
               
            3. 
             
          
@@ -861,7 +861,7 @@ 
          WAI-ARIA Roles, States, and Properties
          
               
        8. When the combobox popup is visible, the combobox element contains or owns an element that has role listbox, tree, grid, or dialog.
          9. 
               
        9. 
                 If the combobox popup has a role other than listbox, the element with role combobox has aria-haspopup set to a value that corresponds to the popup type.
-                That is, aria-haspopup is set to grid, tree, or dialog. 
+                That is, aria-haspopup is set to grid, tree, or dialog.
                 Note that elements with role combobox have an implicit aria-haspopup value of listbox.
               
          10. 
               
        10. When the combobox popup is visible, the textbox element has aria-controls set to a value that refers to the combobox popup element.
          11. 
@@ -878,12 +878,12 @@ 
          WAI-ARIA Roles, States, and Properties
          
             
      
           
      • 
           
    • 
-            The textbox element has  a value for aria-multiline of false. 
+            The textbox element has  a value for aria-multiline of false.
             Note that the default value of aria-multiline is false.
           
      • 
           
    • 
-            When the combobox popup is not visible, the element with role combobox has aria-expanded set to false. 
-            When the popup element is visible, aria-expanded is set to true. 
+            When the combobox popup is not visible, the element with role combobox has aria-expanded set to false.
+            When the popup element is visible, aria-expanded is set to true.
             Note that Elements with role combobox have a default value for aria-expanded of false.
           
      • 
           
    • When a combobox receives focus, DOM focus is placed on the textbox element.
      • 
@@ -899,14 +899,14 @@ 
      WAI-ARIA Roles, States, and Properties
      
               
    • list: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
      • 
               
    • 
                 both: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
-                In addition, the portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox. 
+                In addition, the portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox.
                 The inline completion string is visually highlighted and has a selected state.
               
      • 
             
    
           
         

         

-          The roles, states, and properties for popup elements are defined in their respective design patterns. 
+          The roles, states, and properties for popup elements are defined in their respective design patterns.
           When refering to the following design patterns, note that a combobox is a single-select widget where selection follows focus in the popup.
         

         
    
@@ -1054,11 +1054,7 @@ 
    Dialog (Non-Modal)
    
 
     
    
       
    Disclosure (Show/Hide)
    
-      
    
-        Drafting content for this section is tracked by
-        issue 9.
-      
    
-      
    Write description of disclosure pattern here.
    
+     
    A disclosure button is a button that hides or shows content on a page. It is often styled as a typical push button with a right pointing arrow or triangle to hint that activating the button will display the content.  When the content is made visible the arrow or triangle typically changes to point down.
    
 
       
    
         
    Examples
    
@@ -1080,10 +1076,20 @@ 
    Keyboard Interaction
    
       
    
         
    WAI-ARIA Roles, States, and Properties
    
         
      
-          
    • role button
      • 
-          
    • state aria-expanded
      • 
-          
    • property aria-controls
      • 
+          
    • The element that shows and hides the content has role button.
      • 
+          
    • 
+            When the content is visible, the element with role button has
+            aria-expanded
+            set to true.
+            When the content area is hidden, it is set to false.
+          
      • 
+          
    • 
+            Optionally, the element with role button has a value specified for
+            aria-controls
+            that refers to the element that contains all the content that is shown or hidden.
+            
      • 
         
    
+
       
    
     
    
 
@@ -1943,14 +1949,14 @@ 
    WAI-ARIA Roles, States, and Properties
    
           
  • 
             Currently, using aria-expanded on elements with role menuitem triggers HTML validation errors because the ARIA specification does not yet support doing so.
             The ARIA working group plans to resolve this issue in the next version of the specification.
-            Until a version of ARIA that resolves 
-            the issue 
-            becomes a W3C recommendation, it is safe to ignore these validation errors. 
+            Until a version of ARIA that resolves
+            the issue
+            becomes a W3C recommendation, it is safe to ignore these validation errors.
             Alternatively, since only a few browser and assistive technology combinations exploit this feature of the pattern, it can be omitted from implementations.
           
    • 
           
  • 
             If aria-owns is set on the menu container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children.
-            Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order. 
+            Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.
           
    • 
         
       
    
@@ -2171,7 +2177,7 @@ 
    WAI-ARIA Roles, States, and Properties
    
       
    Slider (Multi-Thumb)
    
       
    
         NOTE: Revisions to this pattern are in progress.
-        Please provide feedback in 
+        Please provide feedback in
         issue 221.
       
    
       
    
@@ -4119,7 +4125,7 @@ 
    Changes in June 2017 Working Draft
    
         
    Also see:
    
         
       

     

-    
+