From 893ee6d64ac6aa2543905b77bdca58ef39433d20 Mon Sep 17 00:00:00 2001 From: steve faulkner Date: Sun, 14 Dec 2014 19:32:54 +0000 Subject: [PATCH 01/19] extended examples and added advice --- spec/custom/index.html | 48 +++++++++++++++++++++++++++++++----------- 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/spec/custom/index.html b/spec/custom/index.html index ffd268f8..2ad95012 100644 --- a/spec/custom/index.html +++ b/spec/custom/index.html @@ -762,46 +762,70 @@

Custom Element Semantics

  • by default a custom tag has no special meaning at all. It represents its children.
  • by default a type extension inherits the semantics of the element type it extends.
    • -

    Custom Tag Semantics

    +

    Custom Tag Semantics

    By default a custom tag has no special meaning at all. It represents its children.

    +

    Custom Tag Example

    For example a custom tag, could be named taco-button but it does not express the semantics of a HTML button element simply due to its name. As instaniated a custom tag conveys a similar amount of semantics as a HTML div or span element. The addition of visual styling and scripted events to the taco-button could provide hints as to the semantics and expected interaction behaviours of the custom element for some users, but for the semantics to be formally expressed, developers must convey the role, states and properties of the element to browser APIs.

    <!-- taco-button represents a span with a fancy name -->
 <taco-button></taco-button>
    -

    The addition of a tabindex attribute to the taco-button element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).

    +

    The addition of a tabindex attribute to the custom button provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).

    
 <!-- taco-button represents a focusable span with a fancy name -->
 <taco-button tabindex="0"></taco-button>
    -

    The addition of a text label to the taco-button element provides an Accessible Name for the element.

    +

    The addition of a text label to the custom button provides an Accessible Name for the element.

    
 <!-- taco-button represents a focusable span with a fancy name and a text label -->
 <taco-button tabindex="0">Eat Me</taco-button>
 or
 <taco-button tabindex="0" aria-label="Eat Me"></taco-button>
    -

    The addition of keyboard event handlers to the taco-button element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.

    +

    The addition of keyboard event handlers to the custom button element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.

    The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all.

    
 <!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
 <taco-button tabindex="0" onclick="alert('tasty eh?');" 
 onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
    -

    The addition of an ARIA role="button" conveys the taco-button element's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).

    +

    The addition of an ARIA role="button" conveys the custom button's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).

    
 <!-- taco-button represents a focusable button with a text label and button like event handling -->
 <taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
 onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
    -

    Type Extension Semantics

    +

    The developer may provide a disabled state for the custom button. This could be implemented by removing the tabindex attribute so the button is no longer included in the focus order and removing the functionality so that interacting with the button does nothing. Also the visual styling may also be modified to visually indicate it the button is disabled.

    +
    
+<!-- grayed out non focusable taco-button with functionality removed, to indicate the button is in a disabled state  -->
+<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
+onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
    +

    Removing the focusability, functionality and modifying the style of the custom button does not unambiguously express that the custom button is in a disabled state. To unambiguously express the disabled state of the button add aria-disabled="true".

    +
    
+<!-- taco-button represents a focusable button with a text label and button like event handling -->
+<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
+onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};" aria-disabled="true">Eat Me</taco-button>
    +

    Type Extension Semantics

    By default a type extension inherits the semantics of the element type it extends.

    -

    For example a type extension, could extend the HTML button element. As instaniated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours.

    -
    <!-- taco-button represents a button with an accesssible name of "Eat Me!" -->
-<button is="taco-button">Eat Me!</button>
+
    Type Extension Example
    
+
     a type extension, could extend the HTML  button element. As instaniated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours. 
    
+
    <!-- tequila-button represents a button with an accesssible name of "Drink Me!" -->
+<button is="tequila-button">Drink Me!</button>
 
    
-
    To provide the desired taco-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the button element.
    
-
    <!-- taco-button represents a button -->
-<button is="taco-button" onclick="alert('tasty eh?');">Eat Me!</button>
+
    To implement the desired tequila-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the button element.
    
+
    <!-- tequila-button represents a button -->
+<button is="tequila-button" onclick="alert('smooth!');">Drink Me!</button>
 
    
+
    To implement the disabled state on the tequila-button, all that is required is the addition of the HTML disabled attribute. The semantics, style and interaction behaviour are implemented by the browser.
    
+
    <!-- tequila-button represents a button -->
+<button is="tequila-button" onclick="alert('smooth!');" required>Drink Me!</button>
+
    
+
    Custom Element Semantics - Developer Advice
    
+
    As illustrated by the  examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides custom elements with built in semantics and interaction behaviours which developers can use as a foundation for their custom elements. 
    
+
    Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA  Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tags or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.
    
+
    Further Reading for Developers
    
+
 
    TO DO 
    
 
    Appendix A: All Algorithms in One Diagram
    
 

From 3b17922542574d3218bf1a968ec94e6cb52bf509 Mon Sep 17 00:00:00 2001
From: steve faulkner 
Date: Sun, 14 Dec 2014 19:48:25 +0000
Subject: [PATCH 02/19] added details about keyboard requirements

---
 spec/custom/index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/custom/index.html b/spec/custom/index.html
index 2ad95012..5440d492 100644
--- a/spec/custom/index.html
+++ b/spec/custom/index.html
@@ -781,8 +781,8 @@ 
    Custom Tag Example
    
 or
 <taco-button tabindex="0" aria-label="Eat Me"></taco-button>
 
    
-
    The addition of  keyboard event handlers to the custom button element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.
    
-
    The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all.
    
+
    The addition of  keyboard event handlers to the custom button element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality. 
    
+
    The addition of in line event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all. This example demonstrates one method to meet the WCAG 2.0 criteria "All functionality of the content is operable through a keyboard interface".
    
 
    
 <!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
 <taco-button tabindex="0" onclick="alert('tasty eh?');" 

From 11f0105ae94db57f35bd1776fde5ba4a5248cf5b Mon Sep 17 00:00:00 2001
From: steve faulkner 
Date: Sun, 14 Dec 2014 20:21:06 +0000
Subject: [PATCH 03/19] corrected code

---
 spec/custom/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/custom/index.html b/spec/custom/index.html
index 5440d492..00fdd642 100644
--- a/spec/custom/index.html
+++ b/spec/custom/index.html
@@ -816,7 +816,7 @@ 
    Type Extension Example
    
 
    
 
    To implement the disabled state on the tequila-button, all that is required is the addition of the HTML disabled attribute. The semantics, style and interaction behaviour are implemented by the browser.
    
 
    <!-- tequila-button represents a button -->
-<button is="tequila-button" onclick="alert('smooth!');" required>Drink Me!</button>
+<button is="tequila-button" onclick="alert('smooth!');" disabled>Drink Me!</button>
 
    
 
    Custom Element Semantics - Developer Advice
    
 
    As illustrated by the  examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides custom elements with built in semantics and interaction behaviours which developers can use as a foundation for their custom elements. 
    

From 486a962716a4d71b96292ad7f6cbbf1333fbccbe Mon Sep 17 00:00:00 2001
From: steve faulkner 
Date: Sun, 14 Dec 2014 20:28:53 +0000
Subject: [PATCH 04/19] tweaking

---
 spec/custom/index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/custom/index.html b/spec/custom/index.html
index 00fdd642..6e1bc072 100644
--- a/spec/custom/index.html
+++ b/spec/custom/index.html
@@ -819,8 +819,8 @@ 
    Type Extension Example
    
 <button is="tequila-button" onclick="alert('smooth!');" disabled>Drink Me!</button>

    Custom Element Semantics - Developer Advice

    -

    As illustrated by the examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides custom elements with built in semantics and interaction behaviours which developers can use as a foundation for their custom elements.

    -

    Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tags or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.

    +

    As illustrated by the examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours which developers can use as a foundation.

    +

    Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tag or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.

    Further Reading for Developers

    -

    Custom Tag Semantics

    +

    Custom Tag Semantics

    By default a custom tag has no special meaning at all. It represents its children.

    -

    Custom Tag Example

    +

    Custom Tag Example

    For example a custom tag, could be named taco-button, but it does not express the semantics of a HTML button element simply due to its name. As instantiated a custom tag conveys a similar amount of semantics as a HTML div or span element. The addition of visual styling and scripted events to the taco-button could provide hints as to the semantics and expected interaction behaviours of the custom element for some users, but for the semantics to be formally expressed, developers must convey the semantics using ARIA roles, states and properties.

    <!-- taco-button represents a span with a fancy name -->
 <taco-button></taco-button>
@@ -801,9 +807,9 @@ 
    Custom Tag Example
    
 <!-- taco-button represents a focusable button with a text label and button like event handling -->
 <taco-button role="button" tabindex="0" onclick="alert('tasty eh?');" 
 onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};" aria-disabled="true">Eat Me</taco-button>
    -

    Type Extension Semantics

    +

    Type Extension Semantics

    By default a type extension inherits the semantics of the element type it extends.

    -

    Type Extension Example

    +

    Type Extension Example

    a type extension, could extend the HTML button element. As instantiated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours. 

    <!-- tequila-button represents a button with an accesssible name of "Drink Me!" -->
 <button is="tequila-button">Drink Me!</button>
@@ -816,10 +822,10 @@ 
    Type Extension Example
    
 
    <!-- tequila-button represents a button -->
 <button is="tequila-button" onclick="alert('smooth!');" disabled>Drink Me!</button>
 
    
-
    Custom Element Semantics - Developer Advice
    
+
    Custom Element Semantics - Developer Advice
    
 
    As illustrated by the  examples above. The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours which developers can use as a foundation.
    
 
    Use ARIA, where needed, to provide semantics for custom elements and follow the ARIA  Design Patterns when implementing ARIA attributes and UI interaction behaviours. Ensure that custom tag or type extension custom elements meet the criteria listed in the Custom Control Accessible Development Checklist. Use ARIA in accordance with the Document conformance requirements for use of ARIA attributes in HTML.
    
-
    Further Reading for Developers
    
+
    Further Reading for Developers