feat(bindings): add useAccessibility hook (#1980)

* feat(bindings): add useAccessibility()

* add behaviors to project tests

* revert props naming

* remove/restore comments

* improve naming, use `Object.keys()`

* fix typings issues

* fix wrapInFZ

* add tests, fix existing

* fix typings and broken UT

* fix typings and broken UTs

* add docs

* Update packages/react-bindings/README.md

Co-Authored-By: Marija Najdova <mnajdova@gmail.com>

* merge with master

* fix prettier issues

* fix prettier issues

* fix handler

* fix imports

* fix import

* fix duplicate constant

Co-authored-by: Marija Najdova <mnajdova@gmail.com>

Author: layershifter

packages/accessibility/src/types.ts

@@ -141,6 +141,10 @@ export interface AccessibilityAttributes
   extends AriaWidgetAttributes,
     AriaRelationshipAttributes,
     ElementStateAttributes {
+  // Is used in @fluentui/ability-attributes for accessibility validations.
+  // Do not set it manually and do not rely on it in production
+  'data-aa-class'?: string
+
   role?: AriaRole
   tabIndex?: number
   id?: string

packages/react-bindings/README.md

@@ -9,8 +9,10 @@ A set of reusable components and hooks to build component libraries and UI kits.
 
 - [Installation](#installation)
 - [Hooks](#hooks)
+  - [`useAccesibility()`](#useaccesibility)
+      - [Usage](#usage)
   - [`useStateManager()`](#usestatemanager)
-    - [Usage](#usage)
+    - [Usage](#usage-1)
     - [Reference](#reference)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -29,13 +31,70 @@ yarn add @fluentui/react-bindings
 
 # Hooks
 
+## `useAccesibility()`
+
+A React hook that provides bindings for accessibility behaviors.
+
+#### Usage
+
+The example below assumes a component called `<Image>` will be used this way:
+
+```tsx
+const imageBehavior: Accessibility<{ disabled: boolean }> = props => ({
+  attributes: {
+    root: {
+      "aria-disabled": props.disabled,
+      tabIndex: -1
+    },
+    img: {
+      role: "presentation"
+    }
+  },
+  keyActions: {
+    root: {
+      click: {
+        keyCombinations: [{ keyCode: 13 /* equals Enter */ }]
+      }
+    }
+  }
+});
+
+type ImageProps = {
+  disabled?: boolean;
+  onClick?: (
+    e: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>
+  ) => void;
+  src: string;
+};
+
+const Image: React.FC<ImageProps> = props => {
+  const { disabled, onClick, src, ...rest } = props;
+  const getA11Props = useAccessibility(imageBehavior, {
+    mapPropsToBehavior: () => ({
+      disabled
+    }),
+    actionHandlers: {
+      click: (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (onClick) onClick(e);
+      }
+    }
+  });
+
+  return (
+    <div {...getA11Props("root", { onClick, ...rest })}>
+      <img {...getA11Props("img", { src })} />
+    </div>
+  );
+};
+```
+
 ## `useStateManager()`
 
 A React hook that provides bindings for state managers. 
 
 ### Usage 
 
-The examples below assume a component called `<Input>` will be used this way:
+The example below assumes a component called `<Input>` will be used this way:
 
 ```tsx
 type InputProps = {

packages/react-bindings/src/accessibility/getAccessibility.ts

@@ -0,0 +1,61 @@
+import {
+  Accessibility,
+  AccessibilityAttributes,
+  AccessibilityAttributesBySlot,
+  AccessibilityDefinition,
+} from '@fluentui/accessibility'
+
+import getKeyDownHandlers from './getKeyDownHandlers'
+import { AccessibilityActionHandlers, ReactAccessibilityBehavior } from './types'
+
+const emptyBehavior: ReactAccessibilityBehavior = {
+  attributes: {},
+  keyHandlers: {},
+}
+
+const getAccessibility = <Props extends Record<string, any>>(
+  displayName: string,
+  behavior: Accessibility<Props>,
+  behaviorProps: Props,
+  isRtlEnabled: boolean,
+  actionHandlers?: AccessibilityActionHandlers,
+): ReactAccessibilityBehavior => {
+  if (behavior === null || behavior === undefined) {
+    return emptyBehavior
+  }
+
+  const definition: AccessibilityDefinition = behavior(behaviorProps)
+  const keyHandlers =
+    actionHandlers && definition.keyActions
+      ? getKeyDownHandlers(actionHandlers, definition.keyActions, isRtlEnabled)
+      : {}
+
+  if (process.env.NODE_ENV !== 'production') {
+    // For the non-production builds we enable the runtime accessibility attributes validator.
+    // We're adding the data-aa-class attribute which is being consumed by the validator, the
+    // schema is located in @stardust-ui/ability-attributes package.
+    if (definition.attributes) {
+      Object.keys(definition.attributes).forEach(slotName => {
+        const validatorName = `${displayName}${slotName === 'root' ? '' : `__${slotName}`}`
+
+        if (!(definition.attributes as AccessibilityAttributesBySlot)[slotName]) {
+          ;(definition.attributes as AccessibilityAttributesBySlot)[
+            slotName
+          ] = {} as AccessibilityAttributes
+        }
+
+        ;(definition.attributes as AccessibilityAttributesBySlot)[slotName][
+          'data-aa-class'
+        ] = validatorName
+      })
+    }
+  }
+
+  return {
+    ...emptyBehavior,
+    ...definition,
+    keyHandlers,
+  }
+}
+
+export default getAccessibility

packages/react-bindings/src/accessibility/getKeyDownHandlers.ts

@@ -0,0 +1,76 @@
+import { KeyActions } from '@fluentui/accessibility'
+// @ts-ignore
+import * as keyboardKey from 'keyboard-key'
+import * as React from 'react'
+
+import shouldHandleOnKeys from './shouldHandleOnKeys'
+import { AccessibilityActionHandlers, AccessibilityKeyHandlers } from './types'
+
+const rtlKeyMap = {
+  [keyboardKey.ArrowRight]: keyboardKey.ArrowLeft,
+  [keyboardKey.ArrowLeft]: keyboardKey.ArrowRight,
+}
+
+/**
+ * Assigns onKeyDown handler to the slot element, based on Component's actions
+ * and keys mappings defined in Accessibility behavior
+ * @param {AccessibilityActionHandlers} componentActionHandlers Actions handlers defined in a component.
+ * @param {KeyActions} behaviorActions Mappings of actions and keys defined in Accessibility behavior.
+ * @param {boolean} isRtlEnabled Indicates if Left and Right arrow keys should be swapped in RTL mode.
+ */
+const getKeyDownHandlers = (
+  componentActionHandlers: AccessibilityActionHandlers,
+  behaviorActions: KeyActions,
+  isRtlEnabled?: boolean,
+): AccessibilityKeyHandlers => {
+  const slotKeyHandlers: AccessibilityKeyHandlers = {}
+
+  if (!componentActionHandlers || !behaviorActions) {
+    return slotKeyHandlers
+  }
+
+  const componentHandlerNames = Object.keys(componentActionHandlers)
+
+  Object.keys(behaviorActions).forEach(slotName => {
+    const behaviorSlotActions = behaviorActions[slotName]
+    const handledActions = Object.keys(behaviorSlotActions).filter(actionName => {
+      const slotAction = behaviorSlotActions[actionName]
+
+      const actionHasKeyCombinations =
+        Array.isArray(slotAction.keyCombinations) && slotAction.keyCombinations.length > 0
+      const actionHandledByComponent = componentHandlerNames.indexOf(actionName) !== -1
+
+      return actionHasKeyCombinations && actionHandledByComponent
+    })
+
+    if (handledActions.length > 0) {
+      slotKeyHandlers[slotName] = {
+        onKeyDown: (event: React.KeyboardEvent) => {
+          handledActions.forEach(actionName => {
+            let keyCombinations = behaviorSlotActions[actionName].keyCombinations
+
+            if (keyCombinations) {
+              if (isRtlEnabled) {
+                keyCombinations = keyCombinations.map(keyCombination => {
+                  const keyToRtlKey = rtlKeyMap[keyCombination.keyCode]
+                  if (keyToRtlKey) {
+                    keyCombination.keyCode = keyToRtlKey
+                  }
+                  return keyCombination
+                })
+              }
+
+              if (shouldHandleOnKeys(event, keyCombinations)) {
+                componentActionHandlers[actionName](event)
+              }
+            }
+          })
+        },
+      }
+    }
+  })
+
+  return slotKeyHandlers
+}
+
+export default getKeyDownHandlers

packages/react/src/utils/shouldHandleOnKeys.ts renamed to packages/react-bindings/src/accessibility/shouldHandleOnKeys.ts

@@ -1,6 +1,6 @@
 import { KeyCombinations } from '@fluentui/accessibility'
+// @ts-ignore
 import * as keyboardKey from 'keyboard-key'
-import * as _ from 'lodash'
 import * as React from 'react'
 
 const isKeyModifiersMatch = (modifierValue: boolean, combinationValue?: boolean) => {
@@ -15,9 +15,8 @@ const shouldHandleOnKeys = (
   event: React.KeyboardEvent,
   keysCombinations: KeyCombinations[],
 ): boolean =>
-  _.some(
-    keysCombinations,
-    (keysCombination: KeyCombinations) =>
+  keysCombinations.some(
+    keysCombination =>
       keysCombination.keyCode === keyboardKey.getCode(event) &&
       isKeyModifiersMatch(event.altKey, keysCombination.altKey) &&
       isKeyModifiersMatch(event.shiftKey, keysCombination.shiftKey) &&

packages/react/src/utils/accessibility/reactTypes.ts renamed to packages/react-bindings/src/accessibility/types.ts

@@ -0,0 +1,75 @@
+import { Accessibility, AccessibilityAttributesBySlot } from '@fluentui/accessibility'
+import * as React from 'react'
+
+import getAccessibility from '../accessibility/getAccessibility'
+import { ReactAccessibilityBehavior, AccessibilityActionHandlers } from '../accessibility/types'
+
+type UseAccessibilityOptions<Props> = {
+  actionHandlers?: AccessibilityActionHandlers
+  debugName?: string
+  mapPropsToBehavior?: () => Props
+  rtl?: boolean
+}
+
+type MergedProps<SlotProps extends Record<string, any>> = SlotProps &
+  Partial<AccessibilityAttributesBySlot> & {
+    onKeyDown?: (e: React.KeyboardEvent, ...args: any[]) => void
+  }
+
+const mergeProps = <SlotProps extends Record<string, any>>(
+  slotName: string,
+  slotProps: SlotProps,
+  definition: ReactAccessibilityBehavior,
+): MergedProps<SlotProps> => {
+  const finalProps: MergedProps<SlotProps> = {
+    ...definition.attributes[slotName],
+    ...slotProps,
+  }
+  const slotHandlers = definition.keyHandlers[slotName]
+
+  if (slotHandlers) {
+    const onKeyDown = (e: React.KeyboardEvent, ...args: any[]) => {
+      if (slotHandlers && slotHandlers.onKeyDown) {
+        slotHandlers.onKeyDown(e)
+      }
+
+      if (slotProps.onKeyDown) {
+        slotProps.onKeyDown(e, ...args)
+      }
+    }
+
+    finalProps.onKeyDown = onKeyDown
+  }
+
+  return finalProps
+}
+
+const useAccessibility = <Props>(
+  behavior: Accessibility<Props>,
+  options: UseAccessibilityOptions<Props> = {},
+) => {
+  const {
+    actionHandlers,
+    debugName = 'Undefined',
+    mapPropsToBehavior = () => ({}),
+    rtl = false,
+  } = options
+  const definition = getAccessibility(
+    debugName,
+    behavior,
+    mapPropsToBehavior(),
+    rtl,
+    actionHandlers,
+  )
+
+  const latestDefinition = React.useRef<ReactAccessibilityBehavior>(definition)
+  latestDefinition.current = definition
+
+  return React.useCallback(
+    <SlotProps extends Record<string, any>>(slotName: string, slotProps: SlotProps) =>
+      mergeProps(slotName, slotProps, latestDefinition.current),
+    [],
+  )
+}
+
+export default useAccessibility

packages/react-bindings/src/hooks/useAccessibility.ts

@@ -1,5 +1,5 @@
-export { default as unstable_useDispatchEffect } from './hooks/useDispatchEffect'
-export { default as useStateManager } from './hooks/useStateManager'
+export { default as unstable_getAccessibility } from './accessibility/getAccessibility'
+export * from './accessibility/types'
 
 export { default as AutoFocusZone } from './FocusZone/AutoFocusZone'
 export * from './FocusZone/AutoFocusZone.types'
@@ -9,6 +9,10 @@ export { default as FocusZone } from './FocusZone/FocusZone'
 export * from './FocusZone/FocusZone.types'
 export * from './FocusZone/focusUtilities'
 
+export { default as useAccessibility } from './hooks/useAccessibility'
+export { default as unstable_useDispatchEffect } from './hooks/useDispatchEffect'
+export { default as useStateManager } from './hooks/useStateManager'
+
 export { default as callable } from './utils/callable'
 export { default as getElementType } from './utils/getElementType'
 export { default as getUnhandledProps } from './utils/getUnhandledProps'

packages/react-bindings/src/index.ts

@@ -1,4 +1,4 @@
-import getKeyDownHandlers from 'src/utils/getKeyDownHandlers'
+import getKeyDownHandlers from '../../src/accessibility/getKeyDownHandlers'
 import * as keyboardKey from 'keyboard-key'
 
 const testKeyCode = keyboardKey.ArrowRight

packages/react/test/specs/utils/getKeyDownHandlers-test.ts renamed to packages/react-bindings/test/accesibility/getKeyDownHandlers-test.ts

@@ -1,4 +1,4 @@
-import shouldHandleOnKeys from 'src/utils/shouldHandleOnKeys'
+import shouldHandleOnKeys from '../../src/accessibility/shouldHandleOnKeys'
 
 const getEventArg = (
   keyCode: number,