HoverCard: Add more documentation and fix accessibility bug. (#5866)

* Adds a conditional for 'data-is-focusable' for the root node.

* Adds more documentation.

* More documentation...

* Cleanup code.

* Rush change log.

* Snapshot updates.

common/changes/office-ui-fabric-react/v-vibr-HoverAccessibility_2018-08-09-01-08.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "HoverCard: Adds more documentation and adds a focus stop on root to eliminate an edge case when target is not provided the focus listener was not firing at all.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "v-vibr@microsoft.com"
+}

packages/office-ui-fabric-react/src/components/HoverCard/HoverCard.checklist.ts

@@ -1,8 +1,8 @@
 import { ChecklistStatus } from '../../common/DocPage.types';
 
 export const HoverCardStatus = {
-  keyboardAccessibilitySupport: ChecklistStatus.unknown,
-  markupSupport: ChecklistStatus.unknown,
+  keyboardAccessibilitySupport: ChecklistStatus.fair,
+  markupSupport: ChecklistStatus.good,
   highContrastSupport: ChecklistStatus.fail,
   rtlSupport: ChecklistStatus.pass,
   testCoverage: ChecklistStatus.none

packages/office-ui-fabric-react/src/components/HoverCard/HoverCard.doc.tsx

@@ -18,12 +18,12 @@ export const HoverCardPageProps: IDocPageProps = {
   componentStatus: HoverCardStatus,
   examples: [
     {
-      title: 'HoverCard',
+      title: 'Example 1: HoverCard wrapping an element',
       code: HoverCardBasicExampleCode,
       view: <HoverCardBasicExample />
     },
     {
-      title: 'HoverCard using Target and at right center',
+      title: 'Example 2: HoverCard using Target, DirectionalHint and custom HotKey',
       code: HoverCardTargetExampleCode,
       view: <HoverCardTargetExample />
     }
@@ -33,6 +33,9 @@ export const HoverCardPageProps: IDocPageProps = {
     require<string>('!raw-loader!office-ui-fabric-react/src/components/HoverCard/ExpandingCard.types.ts')
   ],
   overview: require<string>('!raw-loader!office-ui-fabric-react/src/components/HoverCard/docs/HoverCardOverview.md'),
+  bestPractices: 'Use this guidance when need to fine tune properties of HoverCard',
+  dos: require<string>('!raw-loader!office-ui-fabric-react/src/components/HoverCard/docs/HoverCardDos.md'),
+  donts: require<string>('!raw-loader!office-ui-fabric-react/src/components/HoverCard/docs/HoverCardDonts.md'),
   isHeaderVisible: true,
   allowNativeProps: true
 };

packages/office-ui-fabric-react/src/components/HoverCard/HoverCard.tsx

@@ -92,6 +92,7 @@ export class HoverCard extends BaseComponent<IHoverCardProps, IHoverCardState> {
         className={mergeStyles(this._styles.host)}
         ref={this._hoverCard}
         aria-describedby={setAriaDescribedBy && isHoverCardVisible ? hoverCardId : undefined}
+        data-is-focusable={!Boolean(this.props.target)}
       >
         {children}
         {isHoverCardVisible && (

packages/office-ui-fabric-react/src/components/HoverCard/docs/HoverCardDonts.md

@@ -0,0 +1 @@
+- If not specifying `target` prop and using the HoverCard as a wrapper, don't provide `data-is-focusable='true'` attribute to the root of the wrapped child. When no target given, HoverCard will use it's root as a target and become the focusable element with a `focus` listener attached to it. See Example 1.

packages/office-ui-fabric-react/src/components/HoverCard/docs/HoverCardDos.md

@@ -0,0 +1,2 @@
+- Set `trapFocus` prop to **true** if you want to render the content of the HoverCard in a FocusTrapZone for accessibility reasons.
+- Set `setInitialFocus` prop to **true** if when opening the card your intention is to set focus on the first focusable element in the card. Works in pair with the `trapFocus` prop.

packages/office-ui-fabric-react/src/components/HoverCard/docs/HoverCardOverview.md

@@ -1 +1,6 @@
-HoverCards supplement content associated with a specific data element.
+HoverCards supplement content associated with a specific data element.
+
+Two scenarios to consider for your own use case from an accessibility point of view when deciding how the card should open and it's behavior after it opened:
+
+- Tabbing with a keyboard to the element triggering the HoverCard to open on focus. In this case no further navigation within the card is available and navigating to the next element will close the card. See Example 1.
+- Tabbing with a keyboard to the element triggering the HoverCard and wait to open till the hotKey is depressed. When card is opened it will automatically focus the first focusable element of the card content. See Example 2.

packages/office-ui-fabric-react/src/components/HoverCard/examples/HoverCard.Basic.Example.tsx

@@ -29,7 +29,12 @@ export class HoverCardBasicExample extends BaseComponent<{}, IHoverCardExampleSt
 
     return (
       <div>
-        <p> Hover over location of a row item to see the card </p>
+        <p>
+          Hover over the <i>location</i> cell of a row item to see the card or use the keyboard to navigate to it.
+        </p>
+        <p>
+          When using the keyboard to tab to it, the card will open but navigation inside of it will not be available.
+        </p>
         <DetailsList setKey="hoverSet" items={items!} columns={columns} onRenderItemColumn={this._onRenderItemColumn} />
       </div>
     );
@@ -45,9 +50,7 @@ export class HoverCardBasicExample extends BaseComponent<{}, IHoverCardExampleSt
     if (column.key === 'location') {
       return (
         <HoverCard id="myID1" expandingCardProps={expandingCardProps} instantOpenOnClick={true}>
-          <div className="HoverCard-item" data-is-focusable={true}>
-            {item.location}
-          </div>
+          <div className="HoverCard-item">{item.location}</div>
         </HoverCard>
       );
     }

packages/office-ui-fabric-react/src/components/HoverCard/examples/HoverCard.Target.Example.tsx

@@ -79,7 +79,13 @@ export class HoverCardTargetExample extends BaseComponent<{}, IHoverCardExampleS
 
     return (
       <div>
-        <p> Hover over key of a row item to see the card </p>
+        <p>
+          Hover over the <i>key</i> cell of a row item to see the card or use the keyboard to navigate to it.
+        </p>
+        <p>
+          When using the keyboard to tab to it, open the card with the hotKey and it will automatically focus the first
+          focusable element in the card allowing further navigation inside the card.
+        </p>
         <DetailsList
           setKey="hoverSet"
           items={items!}

packages/office-ui-fabric-react/src/components/__snapshots__/HoverCard.Basic.Example.tsx.shot

@@ -3,7 +3,14 @@
 exports[`Component Examples renders HoverCard.Basic.Example.tsx correctly 1`] = `
 <div>
   <p>
-     Hover over location of a row item to see the card 
+    Hover over the 
+    <i>
+      location
+    </i>
+     cell of a row item to see the card or use the keyboard to navigate to it.
+  </p>
+  <p>
+    When using the keyboard to tab to it, the card will open but navigation inside of it will not be available.
   </p>
   <div
     className="ms-Viewport"

packages/office-ui-fabric-react/src/components/__snapshots__/HoverCard.Target.Example.tsx.shot

@@ -3,7 +3,14 @@
 exports[`Component Examples renders HoverCard.Target.Example.tsx correctly 1`] = `
 <div>
   <p>
-     Hover over key of a row item to see the card 
+    Hover over the 
+    <i>
+      key
+    </i>
+     cell of a row item to see the card or use the keyboard to navigate to it.
+  </p>
+  <p>
+    When using the keyboard to tab to it, open the card with the hotKey and it will automatically focus the first focusable element in the card allowing further navigation inside the card.
   </p>
   <div
     className="ms-Viewport"