feat(Accessibility): Add accessibility behavior to Popup

src/components/Menu/MenuItem.tsx

@@ -135,7 +135,7 @@ class MenuItem extends UIComponent<Extendable<IMenuItemProps>, any> {
     'vertical',
   ]
 
-  actionHandlers: AccessibilityActionHandlers = {
+  protected actionHandlers: AccessibilityActionHandlers = {
     performClick: event => this.handleClick(event),
   }
 

src/components/Popup/Popup.tsx

@@ -1,19 +1,27 @@
 import * as React from 'react'
 import * as PropTypes from 'prop-types'
+import _ from 'lodash'
 import { Popper, PopperChildrenProps } from 'react-popper'
 import rtlCSSJS from 'rtl-css-js'
 
 import { childrenExist, customPropTypes, UIComponent, IRenderResultConfig } from '../../lib'
 import { ItemShorthand, Extendable, ReactChildren } from '../../../types/utils'
 import { ComponentVariablesInput, ComponentPartStyle } from '../../../types/theme'
-import Portal from '../Portal'
+import Portal, { TriggerAccessibility } from '../Portal'
 import PopupContent from './PopupContent'
-import computePopupPlacement, { Alignment, Position } from './positioningHelper'
+import { PopupBehavior } from '../../lib/accessibility'
+import {
+  Accessibility,
+  AccessibilityActionHandlers,
+  IAccessibilityBehavior,
+} from '../../lib/accessibility/interfaces'
+import computePopupPlacement, { Alignment, Position, Placement } from './positioningHelper'
 
 const POSITIONS: Position[] = ['above', 'below', 'before', 'after']
 const ALIGNMENTS: Alignment[] = ['top', 'bottom', 'start', 'end', 'center']
 
 export interface IPopupProps {
+  accessibility?: Accessibility
   align?: Alignment
   as?: any
   basic?: boolean
@@ -28,6 +36,7 @@ export interface IPopupProps {
 
 export interface IPopupState {
   triggerRef: HTMLElement
+  popupOpened?: boolean
 }
 
 /**
@@ -77,9 +86,13 @@ export default class Popup extends UIComponent<Extendable<IPopupProps>, IPopupSt
 
     /** Override for theme site variables to allow modifications of component styling via themes. */
     variables: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
+
+    /** Accessibility behavior if overridden by the user. */
+    accessibility: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
   }
 
   public static handledProps = [
+    'accessibility',
     'align',
     'as',
     'basic',
@@ -92,60 +105,110 @@ export default class Popup extends UIComponent<Extendable<IPopupProps>, IPopupSt
     'variables',
   ]
 
-  public static defaultProps = {
+  public static defaultProps: IPopupProps = {
     as: Portal,
     align: 'start',
     position: 'above',
+    accessibility: PopupBehavior,
   }
 
-  public state = { triggerRef: undefined }
+  public state = { triggerRef: undefined, popupOpened: false }
+
+  protected actionHandlers: AccessibilityActionHandlers = {
+    performClick: e => this.onTriggerClick(e),
+    closeAndFocusTrigger: e => this.handlePopupState(e, () => false, this.focusTrigger),
+  }
 
   public renderComponent({
     ElementType,
     classes,
+    accessibility,
     rest,
     rtl,
   }: IRenderResultConfig<IPopupProps>): React.ReactNode {
-    const { children, trigger } = this.props
+    const { children, trigger, position, align } = this.props
 
     return (
       <ElementType
         className={classes.root}
         {...rest}
+        open={this.state.popupOpened}
         trigger={trigger}
         triggerRef={this.handleTriggerRef}
+        triggerAccessibility={
+          {
+            attributes: accessibility.attributes.trigger,
+            keyHandlers: accessibility.keyHandlers.trigger,
+          } as TriggerAccessibility
+        }
+        onOutsideClick={e => this.handlePopupState(e, () => false)}
+        onTriggerClick={this.onTriggerClick}
       >
-        {childrenExist(children) ? children : this.renderContent(rtl)}
+        {childrenExist(children)
+          ? children
+          : this.renderContent(
+              computePopupPlacement({ align, position, rtl }),
+              this.renderPopperChildren.bind(this, rtl, accessibility),
+            )}
       </ElementType>
     )
   }
 
-  private renderContent(rtl: boolean): JSX.Element {
-    const { align, position } = this.props
+  private renderContent(
+    popupPlacement: Placement,
+    renderPopperChildrenFromProps: (props: PopperChildrenProps) => React.ReactNode,
+  ): JSX.Element {
     const triggerRef = this.state.triggerRef
-    const placement = computePopupPlacement({ align, position, rtl })
 
     return (
       triggerRef && (
         <Popper
-          placement={placement}
+          placement={popupPlacement}
           referenceElement={triggerRef}
-          children={this.renderPopperChildren.bind(this, rtl)}
+          children={renderPopperChildrenFromProps}
         />
       )
     )
   }
 
-  private renderPopperChildren = (rtl: boolean, { ref, style }: PopperChildrenProps) => {
+  private renderPopperChildren = (
+    rtl: boolean,
+    accessibility: IAccessibilityBehavior,
+    { ref, style }: PopperChildrenProps,
+  ) => {
     const { basic, content } = this.props
     const computedStyle = rtl ? rtlCSSJS(style) : style
 
     return (
-      <Popup.Content innerRef={ref} basic={basic} {...rtl && { dir: 'rtl' }} styles={computedStyle}>
+      <Popup.Content
+        innerRef={ref}
+        basic={basic}
+        {...rtl && { dir: 'rtl' }}
+        styles={computedStyle}
+        {...accessibility.attributes.popup}
+        {...accessibility.keyHandlers.popup}
+      >
         {content}
       </Popup.Content>
     )
   }
 
+  private onTriggerClick = (e: Event) => {
+    this.handlePopupState(e, prevOpened => !prevOpened)
+  }
+
+  private handlePopupState = (
+    e: Event,
+    getPopupOpened: (previousOpened) => boolean,
+    afterRenderCb?: () => void,
+  ) => {
+    e.preventDefault()
+    this.setState(
+      previousState => ({ popupOpened: getPopupOpened(previousState.popupOpened) }),
+      afterRenderCb,
+    )
+  }
+
+  private focusTrigger = () => _.invoke(this.state.triggerRef, 'focus')
   private handleTriggerRef = (triggerRef: HTMLElement) => this.setState({ triggerRef })
 }

src/components/Popup/positioningHelper.ts

@@ -1,3 +1,4 @@
+export { Placement } from 'popper.js'
 import { Placement } from 'popper.js'
 
 export type Position = 'above' | 'below' | 'before' | 'after'

src/components/Portal/Portal.tsx

@@ -12,8 +12,13 @@ import {
 import { ItemShorthand, ReactChildren } from '../../../types/utils'
 import Ref from '../Ref'
 import PortalInner from './PortalInner'
+import { IAccessibilityAttributes, OnKeyDownHandler } from '../../lib/accessibility/interfaces'
 
 type ReactMouseEvent = React.MouseEvent<HTMLElement>
+export type TriggerAccessibility = {
+  attributes?: IAccessibilityAttributes
+  keyHandlers?: OnKeyDownHandler
+}
 
 export interface IPortalProps {
   children?: ReactChildren
@@ -23,7 +28,10 @@ export interface IPortalProps {
   onUnmount?: (props: IPortalProps) => void
   open?: boolean
   trigger?: JSX.Element
+  triggerAccessibility?: TriggerAccessibility
   triggerRef?: (node: HTMLElement) => void
+  onTriggerClick?: (e: ReactMouseEvent) => void
+  onOutsideClick?: (e: ReactMouseEvent) => void
 }
 
 export interface IPortalState {
@@ -75,19 +83,43 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
      * @param {JSX.Element} node - Referred node.
      */
     triggerRef: PropTypes.func,
+
+    /** Accessibility behavior object to apply on trigger node. */
+    triggerAccessibility: PropTypes.object,
+
+    /**
+     * Called when trigger node was clicked.
+     *
+     * @param {object} data - All props.
+     */
+    onTriggerClick: PropTypes.func,
+
+    /**
+     * Called when `click` event was invoked outside portal or trigger nodes.
+     *
+     * @param {object} data - All props.
+     */
+    onOutsideClick: PropTypes.func,
   }
 
   public static handledProps = [
     'children',
     'content',
     'defaultOpen',
     'onMount',
+    'onOutsideClick',
+    'onTriggerClick',
     'onUnmount',
     'open',
     'trigger',
+    'triggerAccessibility',
     'triggerRef',
   ]
 
+  public static defaultProps: IPortalProps = {
+    triggerAccessibility: {},
+  }
+
   public renderComponent(): React.ReactNode {
     return (
       <React.Fragment>
@@ -113,17 +145,20 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
   }
 
   private renderTrigger(): JSX.Element | undefined {
-    const { trigger } = this.props
+    const { trigger, triggerAccessibility } = this.props
 
     return (
       trigger && (
         <Ref innerRef={this.handleTriggerRef}>
-          {React.cloneElement(trigger, { onClick: this.handleTriggerClick })}
+          {React.cloneElement(trigger, {
+            onClick: this.handleTriggerClick,
+            ...triggerAccessibility.attributes,
+            ...triggerAccessibility.keyHandlers,
+          })}
         </Ref>
       )
     )
   }
-
   private handleMount = () => {
     eventStack.sub('click', this.handleDocumentClick)
     _.invoke(this.props, 'onMount', this.props)
@@ -147,6 +182,7 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
   private handleTriggerClick = (e: ReactMouseEvent, ...rest) => {
     const { trigger } = this.props
 
+    _.invoke(this.props, 'onTriggerClick', e) // Call handler from parent component
     _.invoke(trigger, 'props.onClick', e, ...rest) // Call original event handler
     this.trySetState({ open: !this.state.open })
   }
@@ -159,7 +195,7 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
     ) {
       return // ignore the click
     }
-
+    _.invoke(this.props, 'onOutsideClick', e)
     this.trySetState({ open: false })
   }
 }

src/components/Portal/index.ts

@@ -1 +1 @@
-export { default } from './Portal'
+export { default, TriggerAccessibility } from './Portal'

src/lib/accessibility/Behaviors/Popup/PopupBehavior.ts

@@ -0,0 +1,62 @@
+import { Accessibility } from '../../interfaces'
+import * as keyboardKey from 'keyboard-key'
+import _ from 'lodash'
+
+/**
+ * @description
+ *  Adds role='button' to 'trigger' component's part, if it is not focusable element and no role attribute provided.
+ *  Adds tabIndex='0' to 'trigger' component's part, if it is not tabbable element and no tabIndex attribute provided.
+ *  Adds attribute 'aria-disabled=true' to 'trigger' component's part based on the property 'disabled'.
+ *  Adds attribute 'aria-haspopup=true' to 'trigger' component's part.
+ */
+const PopupBehavior: Accessibility = (props: any) => ({
+  attributes: {
+    trigger: {
+      role: getAriaAttributeFromProps('role', props, 'button'),
+      tabIndex: getAriaAttributeFromProps('tabIndex', props, '0'),
+      'aria-haspopup': 'true',
+      'aria-disabled': !!props['disabled'],
+    },
+  },
+  keyActions: {
+    trigger: {
+      performClick: {
+        keyCombinations: [{ keyCode: keyboardKey.Enter }, { keyCode: keyboardKey.Spacebar }],
+      },
+    },
+    popup: {
+      closeAndFocusTrigger: {
+        keyCombinations: [{ keyCode: keyboardKey.Escape }],
+      },
+    },
+  },
+})
+
+const isFocusable = propsData => {
+  try {
+    const { as, href, type } = propsData
+    return (
+      type === 'button' ||
+      type === 'input' ||
+      (type === 'a' && href !== undefined) ||
+      as === 'button'
+    )
+  } catch {
+    return false
+  }
+}
+
+const getAriaAttributeFromProps = (attributeName: string, props: any, defaultValue: string) => {
+  if (!props.trigger) return undefined
+  if (props.trigger.props[attributeName]) {
+    return props.trigger.props[attributeName]
+  }
+  const { as, href } = props.trigger.props
+  const { type } = props.trigger
+  if (isFocusable({ as, href, type })) {
+    return undefined
+  }
+  return defaultValue
+}
+
+export default PopupBehavior

src/lib/accessibility/index.ts

@@ -16,3 +16,4 @@ export { default as ToolbarBehavior } from './Behaviors/Toolbar/ToolbarBehavior'
 export { default as ToolbarButtonBehavior } from './Behaviors/Toolbar/ToolbarButtonBehavior'
 export { default as RadioGroupBehavior } from './Behaviors/Radio/RadioGroupBehavior'
 export { default as RadioGroupItemBehavior } from './Behaviors/Radio/RadioGroupItemBehavior'
+export { default as PopupBehavior } from './Behaviors/Popup/PopupBehavior'

src/lib/accessibility/interfaces.ts

@@ -170,9 +170,11 @@ export type AccessibilityActionHandlers = {
 }
 
 export type ActionsKeyHandler = {
-  [partName: string]: {
-    onKeyDown?: KeyboardHandler
-  }
+  [partName: string]: OnKeyDownHandler
+}
+
+export type OnKeyDownHandler = {
+  onKeyDown?: KeyboardHandler
 }
 
 export type KeyboardHandler = (event: KeyboardEvent) => void