feat(FocusZone): Add embed mode for FocusZone and new Chat behavior

CHANGELOG.md

@@ -17,6 +17,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Features
+- Add embed mode for `FocusZone` and use it in newly added Chat behaviors @tomasiser ([#233](https://github.com/stardust-ui/react/pull/233))
+
 <!--------------------------------[ v0.7.0 ]------------------------------- -->
 ## [v0.7.0](https://github.com/stardust-ui/react/tree/v0.7.0) (2018-09-25)
 [Compare changes](https://github.com/stardust-ui/react/compare/v0.6.0...v0.7.0)

docs/src/examples/components/Chat/Types/ChatExample.shorthand.tsx

@@ -7,7 +7,11 @@ const messages = [
   { key: 2, content: 'Hi', author: 'Jane Doe', timestamp: 'Yesterday, 10:15 PM' },
   {
     key: 3,
-    content: "Let's go get some lunch!",
+    content: (
+      <>
+        Let's go get some lunch! I suggest the new <a>Downtown Burgers</a> or <a>Chef's Finest</a>.
+      </>
+    ),
     author: 'John Doe',
     timestamp: 'Yesterday, 10:15 PM',
     mine: true,

src/components/Chat/Chat.tsx

@@ -6,8 +6,11 @@ import { childrenExist, customPropTypes, UIComponent } from '../../lib'
 import ChatMessage from './ChatMessage'
 import { ComponentVariablesInput, ComponentPartStyle } from '../../../types/theme'
 import { Extendable, ReactChildren, ItemShorthand } from '../../../types/utils'
+import { Accessibility, AccessibilityActionHandlers } from '../../lib/accessibility/interfaces'
+import ChatBehavior from '../../lib/accessibility/Behaviors/Chat/ChatBehavior'
 
 export interface IChatProps {
+  accessibility?: Accessibility
   as?: any
   className?: string
   children?: ReactChildren
@@ -22,6 +25,9 @@ class Chat extends UIComponent<Extendable<IChatProps>, any> {
   static displayName = 'Chat'
 
   static propTypes = {
+    /** Accessibility behavior if overridden by the user. */
+    accessibility: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
+
     as: customPropTypes.as,
 
     /** Additional CSS class name(s) to apply.  */
@@ -39,17 +45,34 @@ class Chat extends UIComponent<Extendable<IChatProps>, any> {
     variables: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
   }
 
-  static handledProps = ['as', 'children', 'className', 'messages', 'styles', 'variables']
+  static handledProps = [
+    'accessibility',
+    'as',
+    'children',
+    'className',
+    'messages',
+    'styles',
+    'variables',
+  ]
 
-  static defaultProps = { as: 'ul' }
+  static defaultProps = { accessibility: ChatBehavior as Accessibility, as: 'ul' }
 
   static Message = ChatMessage
 
-  renderComponent({ ElementType, classes, rest }) {
+  actionHandlers: AccessibilityActionHandlers = {
+    focus: event => this.focusZone && this.focusZone.focus(),
+  }
+
+  renderComponent({ ElementType, classes, accessibility, rest }) {
     const { children, messages } = this.props
 
     return (
-      <ElementType {...rest} className={classes.root}>
+      <ElementType
+        className={classes.root}
+        {...accessibility.attributes.root}
+        {...accessibility.keyHandlers.root}
+        {...rest}
+      >
         {childrenExist(children)
           ? children
           : _.map(messages, message => ChatMessage.create(message))}

src/components/Chat/ChatMessage.tsx

@@ -16,10 +16,13 @@ import {
 } from '../../../types/theme'
 import { Extendable, ReactChildren, ItemShorthand } from '../../../types/utils'
 import Avatar from '../Avatar'
+import ChatMessageBehavior from '../../lib/accessibility/Behaviors/Chat/ChatMessageBehavior'
+import { Accessibility, AccessibilityActionHandlers } from '../../lib/accessibility/interfaces'
 import Layout from '../Layout'
 import Text from '../Text'
 
 export interface IChatMessageProps {
+  accessibility?: Accessibility
   as?: any
   author?: ItemShorthand
   avatar?: ItemShorthand
@@ -40,6 +43,9 @@ class ChatMessage extends UIComponent<Extendable<IChatMessageProps>, any> {
   static displayName = 'ChatMessage'
 
   static propTypes = {
+    /** Accessibility behavior if overridden by the user. */
+    accessibility: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
+
     as: customPropTypes.as,
 
     /** Author of the message. */
@@ -71,6 +77,7 @@ class ChatMessage extends UIComponent<Extendable<IChatMessageProps>, any> {
   }
 
   static handledProps = [
+    'accessibility',
     'as',
     'author',
     'avatar',
@@ -84,32 +91,49 @@ class ChatMessage extends UIComponent<Extendable<IChatMessageProps>, any> {
   ]
 
   static defaultProps = {
+    accessibility: ChatMessageBehavior as Accessibility,
     as: 'li',
   }
 
+  actionHandlers: AccessibilityActionHandlers = {
+    // prevents default FocusZone behavior, e.g., in ChatMessageBehavior, it prevents FocusZone from using arrow keys as navigation (only Tab key should work)
+    preventDefault: event => {
+      event.preventDefault()
+    },
+  }
+
   renderComponent({
     ElementType,
     classes,
+    accessibility,
     rest,
     styles,
     variables,
   }: IRenderResultConfig<IChatMessageProps>) {
-    const { as, avatar, children, mine } = this.props
+    const { avatar, children, mine } = this.props
 
-    return childrenExist(children) ? (
-      <ElementType {...rest} className={cx(classes.root, classes.content)}>
-        {children}
-      </ElementType>
+    const childrenPropExists = childrenExist(children)
+    const className = childrenPropExists ? cx(classes.root, classes.content) : classes.root
+    const content = childrenPropExists ? (
+      children
     ) : (
       <Layout
-        as={as}
-        {...rest}
-        className={classes.root}
         start={!mine && this.renderAvatar(avatar, styles.avatar, variables)}
         main={this.renderContent(classes.content, styles, variables)}
         end={mine && this.renderAvatar(avatar, styles.avatar, variables)}
       />
     )
+
+    return (
+      <ElementType
+        {...accessibility.attributes.root}
+        {...accessibility.keyHandlers.root}
+        {...rest}
+        className={className}
+      >
+        {content}
+      </ElementType>
+    )
   }
 
   private renderContent = (

src/index.ts

@@ -41,6 +41,17 @@ export {
 export {
   default as RadioGroupItemBehavior,
 } from './lib/accessibility/Behaviors/Radio/RadioGroupItemBehavior'
+export { default as ChatBehavior } from './lib/accessibility/Behaviors/Chat/ChatBehavior'
+export {
+  default as ChatMessageBehavior,
+} from './lib/accessibility/Behaviors/Chat/ChatMessageBehavior'
+export {
+  default as ChatBehaviorEnterEsc,
+} from './lib/accessibility/Behaviors/Chat/ChatEnterEscBehavior'
+export {
+  default as ChatMessageBehaviorEnterEsc,
+} from './lib/accessibility/Behaviors/Chat/ChatMessageEnterEscBehavior'
+
 export { default as Portal } from './components/Portal'
 export { default as Popup } from './components/Popup'
 export { PopupContent } from './components/Popup'

src/lib/UIComponent.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react'
 import renderComponent, { IRenderResultConfig } from './renderComponent'
 import { AccessibilityActionHandlers } from './accessibility/interfaces'
+import { IFocusZone } from './accessibility/FocusZone'
 
 class UIComponent<P, S> extends React.Component<P, S> {
   private readonly childClass = this.constructor as typeof UIComponent
@@ -9,6 +10,7 @@ class UIComponent<P, S> extends React.Component<P, S> {
   static className: string
   static handledProps: any
   protected actionHandlers: AccessibilityActionHandlers
+  protected focusZone: IFocusZone
 
   constructor(props, context) {
     super(props, context)
@@ -38,10 +40,15 @@ class UIComponent<P, S> extends React.Component<P, S> {
         props: this.props,
         state: this.state,
         actionHandlers: this.actionHandlers,
+        focusZoneRef: this.setFocusZoneRef,
       },
       this.renderComponent,
     )
   }
+
+  private setFocusZoneRef = (focusZone: IFocusZone): void => {
+    this.focusZone = focusZone
+  }
 }
 
 export default UIComponent

src/lib/accessibility/Behaviors/Chat/ChatBehavior.ts

@@ -0,0 +1,37 @@
+import { Accessibility, FocusZoneMode } from '../../interfaces'
+import * as keyboardKey from 'keyboard-key'
+import { FocusZoneDirection } from '../../FocusZone'
+
+const CHAT_FOCUSZONE_ATTRIBUTE = 'chat-focuszone'
+
+/**
+ * @description
+ * Adds role 'presentation' until we come up with final roles for chat.
+ * Adds a vertical focus zone navigation with a last message as a default tabbable element, pressing right arrow key focuses inside a message.
+ * Adds a left arrow key action which focuses the chat, i.e., moves key handling from inside a message back to the chat list.
+ */
+const ChatBehavior: Accessibility = {
+  attributes: {
+    root: {
+      role: 'presentation',
+    },
+  },
+  focusZone: {
+    mode: FocusZoneMode.Wrap,
+    props: {
+      shouldEnterInnerZone: event => keyboardKey.getCode(event) === keyboardKey.ArrowRight,
+      direction: FocusZoneDirection.vertical,
+      defaultTabbableElement: `[${CHAT_FOCUSZONE_ATTRIBUTE}] > * > *:last-child`, // select last chat message by default
+      [CHAT_FOCUSZONE_ATTRIBUTE]: '', // allows querying the default active element
+    },
+  },
+  keyActions: {
+    root: {
+      focus: {
+        keyCombinations: [{ keyCode: keyboardKey.ArrowLeft }],
+      },
+    },
+  },
+}
+
+export default ChatBehavior

src/lib/accessibility/Behaviors/Chat/ChatEnterEscBehavior.ts

@@ -0,0 +1,37 @@
+import { Accessibility, FocusZoneMode } from '../../interfaces'
+import * as keyboardKey from 'keyboard-key'
+import { FocusZoneDirection } from '../../FocusZone'
+
+const CHAT_FOCUSZONE_ATTRIBUTE = 'chat-focuszone'
+
+/**
+ * @description
+ * Adds role 'presentation' until we come up with final roles for chat.
+ * Adds a vertical focus zone navigation with a last message as a default tabbable element, pressing enter key focuses inside a message.
+ * Adds an escape key action which focuses the chat, i.e., moves key handling from inside a message back to the chat list.
+ */
+const ChatEnterEscBehavior: Accessibility = {
+  attributes: {
+    root: {
+      role: 'presentation',
+    },
+  },
+  focusZone: {
+    mode: FocusZoneMode.Wrap,
+    props: {
+      shouldEnterInnerZone: event => keyboardKey.getCode(event) === keyboardKey.Enter,
+      direction: FocusZoneDirection.vertical,
+      defaultTabbableElement: `[${CHAT_FOCUSZONE_ATTRIBUTE}] > * > *:last-child`, // select last chat message by default
+      [CHAT_FOCUSZONE_ATTRIBUTE]: '', // allows querying the default active element
+    },
+  },
+  keyActions: {
+    root: {
+      focus: {
+        keyCombinations: [{ keyCode: keyboardKey.Escape }],
+      },
+    },
+  },
+}
+
+export default ChatEnterEscBehavior

src/lib/accessibility/Behaviors/Chat/ChatMessageBehavior.ts

@@ -0,0 +1,38 @@
+import { Accessibility, FocusZoneMode } from '../../interfaces'
+import { IS_FOCUSABLE_ATTRIBUTE } from '../../FocusZone/focusUtilities'
+import * as keyboardKey from 'keyboard-key'
+import { FocusZoneTabbableElements, FocusZoneDirection } from '../../FocusZone'
+
+/**
+ * @description
+ * Adds role 'presentation' until we come up with final roles for chat.
+ * Sets the message to be a focusable element.
+ * Adds a vertical circular focus zone navigation where a user navigates using a Tab key.
+ * Adds a key action which prevents up and down arrow keys from navigating in FocusZone, we only want a Tab key to navigate.
+ */
+const ChatMessageBehavior: Accessibility = {
+  attributes: {
+    root: {
+      role: 'presentation',
+      [IS_FOCUSABLE_ATTRIBUTE]: true,
+    },
+  },
+  focusZone: {
+    mode: FocusZoneMode.Embed,
+    props: {
+      handleTabKey: FocusZoneTabbableElements.all,
+      isCircularNavigation: true,
+      direction: FocusZoneDirection.vertical,
+    },
+  },
+  keyActions: {
+    root: {
+      // prevents default FocusZone behavior, in this case, prevents using arrow keys as navigation (we only want a Tab key to navigate)
+      preventDefault: {
+        keyCombinations: [{ keyCode: keyboardKey.ArrowUp }, { keyCode: keyboardKey.ArrowDown }],
+      },
+    },
+  },
+}
+
+export default ChatMessageBehavior

src/lib/accessibility/Behaviors/Chat/ChatMessageEnterEscBehavior.ts

@@ -0,0 +1,25 @@
+import { Accessibility, FocusZoneMode } from '../../interfaces'
+import { IS_FOCUSABLE_ATTRIBUTE } from '../../FocusZone/focusUtilities'
+
+/**
+ * @description
+ * Adds role 'presentation' until we come up with final roles for chat.
+ * Sets the message to be a focusable element.
+ * Adds a default focus zone navigation where a user navigates using arrow keys in all directions.
+ */
+const ChatMessageEnterEscBehavior: Accessibility = {
+  attributes: {
+    root: {
+      role: 'presentation',
+      [IS_FOCUSABLE_ATTRIBUTE]: true,
+    },
+  },
+  focusZone: {
+    mode: FocusZoneMode.Embed,
+    props: {
+      isCircularNavigation: true,
+    },
+  },
+}
+
+export default ChatMessageEnterEscBehavior

src/lib/accessibility/FocusZone/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 This is a list of changes made to this Stardust copy of FocusZone in comparison with the original [Fabric FocusZone @ 0f567e05952c6b50c691df2fb72d100b5e525d9e](https://github.com/OfficeDev/office-ui-fabric-react/blob/0f567e05952c6b50c691df2fb72d100b5e525d9e/packages/office-ui-fabric-react/src/components/FocusZone/FocusZone.tsx).
 
+### feat(FocusZone): Add embed mode for FocusZone and new Chat behavior [#233](https://github.com/stardust-ui/react/pull/233)
+- Replaced `onFocusNotification` with a regular `onFocus` event callback to pass unit tests with embed.
+- Replaced `ref={this.setRef}` with `this.setRef(this)` in `componentDidMount` to support functional components, which is needed to pass unit tests with embed.
+- Renamed `defaultActiveElement` to `defaultTabbableElement` and changed behavior:
+    - Changed to query only descendants of the focus zone instead of the whole document, which enables to write simpler selectors. Note that we do not lose any functionality by this, because selecting elements outside of focus zone had no effect.
+    - Changed not to call `this.focus()` on component mount (this was causing issues e.g., in docsite, where every change in source code would refocus the mounted component). Instead, you can now use a new property `shouldFocusOnMount`.
+
 ### feat(FocusZone): Implement FocusZone into renderComponent [#116](https://github.com/stardust-ui/react/pull/116)
 - Prettier and linting fixes, e.g., removing semicolons, removing underscores from private methods.
 - Moved `IS_FOCUSABLE_ATTRIBUTE` and others to `focusUtilities.ts`.