feat(accessibility): Editing/adding behaviors and adding accessibility description for components

CHANGELOG.md

@@ -27,6 +27,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Features
 - Add basic `Radio` component @alinais ([#100](https://github.com/stardust-ui/react/pull/100))
 - Add `descriptionColor` to Header @kuzhelov ([#78](https://github.com/stardust-ui/react/pull/78))
+- Add accessibility behavior description @kolaps33 ([#74](https://github.com/stardust-ui/react/pull/74))
 
 <!--------------------------------[ v0.3.0 ]------------------------------- -->
 ## [v0.3.0](https://github.com/stardust-ui/react/tree/v0.3.0) (2018-08-22)

src/components/Button/Button.tsx

@@ -8,8 +8,14 @@ import { Accessibility } from '../../lib/accessibility/interfaces'
 
 /**
  * A button.
- * @accessibility This is example usage of the accessibility tag.
- * This should be replaced with the actual description after the PR is merged
+ * @accessibility
+ * Default behavior: ButtonBehavior
+ *  - adds role='button' if element type is other than 'button'
+ *
+ *
+ * Other considerations:
+ *  - for disabled buttons, add 'disabled' attribute so that the state is properly recognized by the screen reader
+ *  - if button includes icon only, textual representation needs to be provided by using 'title', 'aria-label', or 'aria-labelledby' attributes
  */
 class Button extends UIComponent<any, any> {
   public static displayName = 'Button'

src/components/Header/Header.tsx

@@ -9,6 +9,11 @@ import HeaderDescription from './HeaderDescription'
  * @accessibility
  * Headings communicate the organization of the content on the page. Web browsers, plug-ins, and assistive technologies can use them to provide in-page navigation.
  * Nest headings by their rank (or level). The most important heading has the rank 1 (<h1>), the least important heading rank 6 (<h6>). Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher ranked section.
+ *
+ *
+ * Other considerations:
+ *  - when the description property is used in header, readers will narrate both header content and description within the element.
+ *    In addition to that, both will be displayed in the list of headings.
  */
 class Header extends UIComponent<any, any> {
   static className = 'ui-header'

src/components/Icon/Icon.tsx

@@ -1,11 +1,18 @@
 import * as React from 'react'
 import * as PropTypes from 'prop-types'
 import { customPropTypes, UIComponent, createShorthandFactory } from '../../lib'
+import { IconBehavior } from '../../lib/accessibility/'
 
 import svgIcons from './svgIcons'
 
 export type IconXSpacing = 'none' | 'before' | 'after' | 'both'
 
+/**
+ * @accessibility
+ * Default behavior: IconBehavior
+ *  - attribute "aria-hidden='true'" is applied on icon
+ */
+
 class Icon extends UIComponent<any, any> {
   static create: Function
 
@@ -59,9 +66,13 @@ class Icon extends UIComponent<any, any> {
 
     /** Adds space to the before, after or on both sides of the icon, or removes the default space around the icon ('none' value) */
     xSpacing: PropTypes.oneOf(['none', 'before', 'after', 'both']),
+
+    /** Accessibility behavior if overriden by the user. */
+    accessibility: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
   }
 
   static handledProps = [
+    'accessibility',
     'as',
     'bordered',
     'circular',
@@ -79,28 +90,29 @@ class Icon extends UIComponent<any, any> {
   static defaultProps = {
     as: 'span',
     size: 'normal',
+    accessibility: IconBehavior,
   }
 
-  renderFontIcon(ElementType, classes, rest): React.ReactNode {
-    return <ElementType className={classes.root} {...rest} />
+  renderFontIcon(ElementType, classes, rest, accessibility): React.ReactNode {
+    return <ElementType className={classes.root} {...accessibility.attributes.root} {...rest} />
   }
 
-  renderSvgIcon(ElementType, classes, rest): React.ReactNode {
+  renderSvgIcon(ElementType, classes, rest, accessibility): React.ReactNode {
     const icon = svgIcons[this.props.name]
 
     return (
-      <ElementType className={classes.root} {...rest}>
+      <ElementType className={classes.root} {...accessibility.attributes.root} {...rest}>
         <svg className={classes.svg} viewBox={icon && icon.viewBox}>
           {icon && icon.element}
         </svg>
       </ElementType>
     )
   }
 
-  renderComponent({ ElementType, classes, rest }) {
+  renderComponent({ ElementType, classes, rest, accessibility }) {
     return this.props.svg
-      ? this.renderSvgIcon(ElementType, classes, rest)
-      : this.renderFontIcon(ElementType, classes, rest)
+      ? this.renderSvgIcon(ElementType, classes, rest, accessibility)
+      : this.renderFontIcon(ElementType, classes, rest, accessibility)
   }
 }
 

src/components/Image/Image.tsx

@@ -7,6 +7,16 @@ import { Accessibility } from '../../lib/accessibility/interfaces'
 
 /**
  * An image is a graphic representation of something.
+ * @accessibility
+ * Default behavior: ImageBehavior
+ *  - attribute "aria-hidden='true'" is applied on img element, if there is no 'alt' property provided
+ *
+ * If image should be visible to screen readers, textual representation needs to be provided in 'alt' property.
+ *
+ * Other considerations:
+ *  - when alt property is empty, then Narrator in scan mode navigates to image and narrates it as empty paragraph
+ *  - when image has role='presentation' then screen readers navigate to the element in scan/virtual mode. To avoid this, the attribute "aria-hidden='true'" is applied by the default image behavior
+ *  - when alt property is used in combination with aria-label, arialabbeledby or title, additional screen readers verification is needed as each screen reader handles this combination differently.
  */
 class Image extends UIComponent<any, any> {
   static className = 'ui-image'

src/components/Input/Input.tsx

@@ -15,7 +15,13 @@ import Icon from '../Icon'
 
 /**
  * An Input
- * @accessibility This is example usage of the accessibility tag.
+ * @accessibility
+ * For good screen reader experience set aria-label or aria-labelledby attribute for input.
+ *
+ *
+ * Other considerations:
+ *  - if input is search, then use "role='search'"
+ *
  */
 class Input extends AutoControlledComponent<any, any> {
   static className = 'ui-input'

src/lib/accessibility/Behaviors/Button/ButtonBehavior.ts

@@ -3,8 +3,7 @@ import { Accessibility } from '../../interfaces'
 const ButtonBehavior: Accessibility = (props: any) => ({
   attributes: {
     root: {
-      role: 'button',
-      'aria-hidden': false,
+      role: props.as === 'button' ? undefined : 'button',
       'aria-disabled': !!props['disabled'],
     },
   },

src/lib/accessibility/Behaviors/Button/ToggleButtonBehavior.ts

@@ -3,7 +3,7 @@ import { Accessibility } from '../../interfaces'
 const ToggleButtonBehavior: Accessibility = (props: any) => ({
   attributes: {
     root: {
-      role: 'button',
+      role: props.as === 'button' ? undefined : 'button',
       'aria-pressed': !!props['active'],
       'aria-disabled': !!props['disabled'],
     },

src/lib/accessibility/Behaviors/Icon/IconBehavior.ts

@@ -0,0 +1,11 @@
+import { Accessibility } from '../../interfaces'
+
+const IconBehavior: Accessibility = (props: any) => ({
+  attributes: {
+    root: {
+      'aria-hidden': 'true',
+    },
+  },
+})
+
+export default IconBehavior

src/lib/accessibility/Behaviors/Image/ImageBehavior.ts

@@ -3,7 +3,7 @@ import { Accessibility } from '../../interfaces'
 const ImageBehavior: Accessibility = (props: any) => ({
   attributes: {
     root: {
-      role: props['alt'] ? undefined : 'presentation',
+      'aria-hidden': props['alt'] ? undefined : 'true',
     },
   },
 })

src/lib/accessibility/index.ts

@@ -12,3 +12,4 @@ export { default as InputBehavior } from './Behaviors/Input/InputBehavior'
 export { default as TreeBehavior } from './Behaviors/Tree/TreeBehavior'
 export { default as TreeItemBehavior } from './Behaviors/Tree/TreeItemBehavior'
 export { default as GroupBehavior } from './Behaviors/Tree/GroupBehavior'
+export { default as IconBehavior } from './Behaviors/Icon/IconBehavior'

test/specs/commonTests/handlesAccessibility.tsx

@@ -3,7 +3,7 @@ import * as React from 'react'
 import { getTestingRenderedComponent } from 'test/utils'
 import { ButtonBehavior, DefaultBehavior } from 'src/lib/accessibility'
 
-const getProp = (renderedComponent, propName, partSelector) => {
+export const getRenderedAttribute = (renderedComponent, propName, partSelector) => {
   const target = partSelector
     ? renderedComponent.render().find(partSelector)
     : renderedComponent.render()
@@ -24,15 +24,15 @@ const getProp = (renderedComponent, propName, partSelector) => {
 export default (Component, options: any = {}) => {
   const {
     requiredProps = {},
-    defaultRootRole = ButtonBehavior,
+    defaultRootRole = undefined,
     accessibilityOverride = ButtonBehavior,
     overriddenRootRole = 'button',
     partSelector = '',
   } = options
 
   test('gets default accessibility when no override used', () => {
     const rendered = getTestingRenderedComponent(Component, <Component {...requiredProps} />)
-    const role = getProp(rendered, 'role', partSelector)
+    const role = getRenderedAttribute(rendered, 'role', partSelector)
     expect(role).toBe(defaultRootRole)
   })
 
@@ -41,7 +41,7 @@ export default (Component, options: any = {}) => {
       Component,
       <Component {...requiredProps} accessibility={DefaultBehavior} />,
     )
-    const role = getProp(rendered, 'role', partSelector)
+    const role = getRenderedAttribute(rendered, 'role', partSelector)
     expect(role).toBeFalsy()
   })
 
@@ -52,7 +52,7 @@ export default (Component, options: any = {}) => {
         Component,
         <Component {...requiredProps} accessibility={accessibilityOverride} />,
       )
-      const role = getProp(rendered, 'role', partSelector)
+      const role = getRenderedAttribute(rendered, 'role', partSelector)
       expect(role).toBe(overriddenRootRole)
     })
 
@@ -62,7 +62,7 @@ export default (Component, options: any = {}) => {
         Component,
         <Component {...requiredProps} role={testRole} />,
       )
-      const role = getProp(rendered, 'role', partSelector)
+      const role = getRenderedAttribute(rendered, 'role', partSelector)
       expect(role).toBe(testRole)
     })
 
@@ -72,7 +72,7 @@ export default (Component, options: any = {}) => {
         Component,
         <Component {...requiredProps} accessibility={accessibilityOverride} role={testRole} />,
       )
-      const role = getProp(rendered, 'role', partSelector)
+      const role = getRenderedAttribute(rendered, 'role', partSelector)
       expect(role).toBe(testRole)
     })
   }

test/specs/commonTests/index.ts

@@ -5,6 +5,7 @@ export * from './implementsClassNameProps'
 export { default as implementsCreateMethod } from './implementsCreateMethod'
 export { default as implementsShorthandProp } from './implementsShorthandProp'
 
-export { default as handlesAccessibility } from './handlesAccessibility'
+export { default as handlesAccessibility, getRenderedAttribute } from './handlesAccessibility'
+
 export { default as isConformant } from './isConformant'
 export { default as rendersChildren } from './rendersChildren'