feat(bindings): add useAccessibility()

Author: layershifter

.github/add-a-feature.md

@@ -3,6 +3,7 @@
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
 - [Propose feature](#propose-feature)
 - [Prototype](#prototype)
 - [Spec out the API](#spec-out-the-api)

packages/react-bindings/src/FocusZone/wrapInFocusZone.ts

@@ -0,0 +1,36 @@
+import { AccessibilityDefinition, FocusZoneMode } from '@stardust-ui/accessibility'
+import * as React from 'react'
+
+import FocusZone from './FocusZone'
+import { FocusZoneProps } from './FocusZone.types'
+import { FOCUSZONE_WRAP_ATTRIBUTE } from './focusUtilities'
+
+const wrapInFocusZone = (
+  element: React.ReactElement,
+  accessibility: AccessibilityDefinition,
+  rtl: boolean,
+) => {
+  if (accessibility.focusZone && accessibility.focusZone.mode === FocusZoneMode.Wrap) {
+    return React.createElement(
+      FocusZone,
+      {
+        [FOCUSZONE_WRAP_ATTRIBUTE]: true,
+        ...accessibility.focusZone.props,
+        isRtl: rtl,
+      } as FocusZoneProps & { [FOCUSZONE_WRAP_ATTRIBUTE]: boolean },
+      element,
+    )
+  }
+
+  if (accessibility.focusZone && accessibility.focusZone.mode === FocusZoneMode.Embed) {
+    return React.createElement(FocusZone, {
+      ...element.props,
+      ...accessibility.focusZone.props,
+      isRtl: rtl,
+    })
+  }
+
+  return element
+}
+
+export default wrapInFocusZone

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

@@ -0,0 +1,50 @@
+import { Accessibility, AccessibilityDefinition } from '@stardust-ui/accessibility'
+
+import getKeyDownHandlers from './getKeyDownHandlers'
+import { AccessibilityActionHandlers, AccessibilityBehavior } from './types'
+
+const emptyBehavior: AccessibilityBehavior = {
+  attributes: {},
+  keyHandlers: {},
+}
+
+const getAccessibility = <Props extends Record<string, any>>(
+  displayName: string,
+  behavior: Accessibility<Props>,
+  behaviorProps: Props,
+  isRtlEnabled: boolean,
+  actionHandlers?: AccessibilityActionHandlers,
+): AccessibilityBehavior => {
+  if (behavior === null || behavior === undefined) {
+    return emptyBehavior
+  }
+
+  const definition: AccessibilityDefinition = behavior(behaviorProps)
+  const keyHandlers = definition.keyActions
+    ? // @ts-ignore FIX ME
+      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) {
+      const slotNames = Object.keys(definition.attributes)
+      slotNames.forEach(slotName => {
+        // @ts-ignore FIX ME
+        definition.attributes[slotName]['data-aa-class'] = `${displayName}${
+          slotName === 'root' ? '' : `__${slotName}`
+        }`
+      })
+    }
+  }
+
+  return {
+    ...emptyBehavior,
+    ...definition,
+    keyHandlers,
+  }
+}
+
+export default getAccessibility

packages/react/src/lib/getKeyDownHandlers.ts renamed to packages/react-bindings/src/accessibility/getKeyDownHandlers.ts

@@ -1,10 +1,10 @@
 import { KeyActions } from '@stardust-ui/accessibility'
-import * as _ from 'lodash'
+// @ts-ignore
 import * as keyboardKey from 'keyboard-key'
 import * as React from 'react'
 
 import shouldHandleOnKeys from './shouldHandleOnKeys'
-import { AccessibilityActionHandlers, AccessibilityKeyHandlers } from './accessibility/reactTypes'
+import { AccessibilityActionHandlers, AccessibilityKeyHandlers } from './types'
 
 const rtlKeyMap = {
   [keyboardKey.ArrowRight]: keyboardKey.ArrowLeft,
@@ -14,31 +14,33 @@ const rtlKeyMap = {
 /**
  * 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} behaviorKeyActions Mappings of actions and keys defined in Accessibility behavior.
+ * @param {AccessibilityActionHandlers} actionHandlers 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,
-  behaviorKeyActions: KeyActions,
+  actionHandlers: AccessibilityActionHandlers,
+  behaviorActions: KeyActions,
   isRtlEnabled?: boolean,
 ): AccessibilityKeyHandlers => {
+  const componentHandlerNames = Object.keys(actionHandlers)
   const keyHandlers = {}
 
-  if (!componentActionHandlers || !behaviorKeyActions) return keyHandlers
+  if (!actionHandlers || !behaviorActions) return keyHandlers
 
-  for (const componentPart in behaviorKeyActions) {
-    const componentPartKeyAction = behaviorKeyActions[componentPart]
-    const handledActions = _.intersection(
-      _.keys(componentPartKeyAction),
-      _.keys(componentActionHandlers),
+  for (const slotName in behaviorActions) {
+    const behaviorSlotAction = behaviorActions[slotName]
+    const handledActions = Object.keys(behaviorSlotAction).filter(
+      actionName => componentHandlerNames.indexOf(actionName) !== -1,
     )
+
     if (!handledActions.length) continue
 
-    keyHandlers[componentPart] = {
+    // @ts-ignore FIX ME
+    keyHandlers[slotName] = {
       onKeyDown: (event: React.KeyboardEvent) => {
         handledActions.forEach(actionName => {
-          let keyCombinations = componentPartKeyAction[actionName].keyCombinations
+          let keyCombinations = behaviorSlotAction[actionName].keyCombinations
 
           if (isRtlEnabled) {
             keyCombinations = keyCombinations.map(keyCombination => {
@@ -51,7 +53,7 @@ const getKeyDownHandlers = (
           }
 
           if (shouldHandleOnKeys(event, keyCombinations)) {
-            componentActionHandlers[actionName](event)
+            actionHandlers[actionName](event)
           }
         })
       },

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

@@ -1,6 +1,6 @@
 import { KeyCombinations } from '@stardust-ui/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/lib/accessibility/reactTypes.ts renamed to packages/react-bindings/src/accessibility/types.ts

@@ -1,11 +1,7 @@
 import { AccessibilityAttributesBySlot, AccessibilityDefinition } from '@stardust-ui/accessibility'
 import * as React from 'react'
 
-/*
- * Accessibility types for React implementation.
- */
-
-export interface ReactAccessibilityBehavior extends AccessibilityDefinition {
+export interface AccessibilityBehavior extends AccessibilityDefinition {
   attributes: AccessibilityAttributesBySlot
   keyHandlers: AccessibilityKeyHandlers
 }
@@ -15,11 +11,11 @@ export type AccessibilityKeyHandlers = {
 }
 
 export type AccessibilityHandlerProps = {
-  onKeyDown?: KeyboardEventHandler
+  onKeyDown?: AccessibilityKeyboardHandler
 }
 
 export type AccessibilityActionHandlers = {
-  [actionName: string]: KeyboardEventHandler
+  [actionName: string]: AccessibilityKeyboardHandler
 }
 
-export type KeyboardEventHandler = (event: React.KeyboardEvent) => void
+export type AccessibilityKeyboardHandler = (event: React.KeyboardEvent) => void

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

@@ -0,0 +1,67 @@
+import { Accessibility, AccessibilityAttributesBySlot } from '@stardust-ui/accessibility'
+import * as React from 'react'
+
+import getAccessibility from '../accessibility/getAccessibility'
+import { AccessibilityBehavior, AccessibilityActionHandlers } from '../accessibility/types'
+
+type UseAccessibilityOptions<Props> = {
+  actionHandlers?: AccessibilityActionHandlers
+  debugName?: string
+  mapPropsToBehavior?: () => Props
+  rtl?: boolean
+}
+
+const mergeProps = <SlotProps extends Record<string, any>>(
+  slotName: string,
+  slotProps: SlotProps,
+  definition: AccessibilityBehavior,
+): SlotProps & Partial<AccessibilityAttributesBySlot> => {
+  const finalProps = {
+    ...definition.attributes[slotName],
+    ...slotProps,
+  }
+  const slotHandlers = definition.keyHandlers[slotName]
+
+  if (slotHandlers) {
+    const onKeyDown = (e: React.KeyboardEvent, ...args: any[]) => {
+      definition.keyHandlers[slotName].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<AccessibilityBehavior>(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/index.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'
@@ -8,6 +8,11 @@ export * from './FocusZone/FocusTrapZone.types'
 export { default as FocusZone } from './FocusZone/FocusZone'
 export * from './FocusZone/FocusZone.types'
 export * from './FocusZone/focusUtilities'
+export { default as unstable_wrapInFocusZone } from './FocusZone/wrapInFocusZone'
+
+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'

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

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

packages/react/test/specs/lib/shouldHandleOnKeys-test.ts renamed to packages/react-bindings/test/accesibility/shouldHandleOnKeys-test.ts

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