OverflowSet: Add Focus(with forceIntoFirstChild) and focusElement() functions

common/changes/office-ui-fabric-react/jspurlin-OverflowSetAddFocusFunctions_2018-04-07-01-16.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "OverflowSet: Add Foucs(firstChild) and focusElement() functions",
+      "type": "minor"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "jspurlin@microsoft.com"
+}

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

@@ -5,7 +5,9 @@ import {
   createRef,
   getNativeProps,
   divProperties,
-  focusFirstChild
+  focusFirstChild,
+  getFirstFocusable,
+  elementContains
 } from '../../Utilities';
 import { mergeStyles } from '../../Styling';
 import { IOverflowSet, IOverflowSetProps, IOverflowSetItemProps } from './OverflowSet.types';
@@ -75,18 +77,48 @@ export class OverflowSet extends BaseComponent<IOverflowSetProps, {}> implements
     );
   }
 
-  public focus() {
+  /**
+   * Sets focus to the first tabbable item in the OverflowSet.
+   * @param {boolean} forceIntoFirstElement If true, focus will be forced into the first element,
+   * even if focus is already in theOverflowSet
+   * @returns True if focus could be set to an active element, false if no operation was taken.
+   */
+  public focus(forceIntoFirstElement?: boolean): boolean {
+    let focusSucceeded = false;
+
     if (this.props.doNotContainWithinFocusZone) {
       if (this._divContainer.value) {
-        focusFirstChild(this._divContainer.value);
+        focusSucceeded = focusFirstChild(this._divContainer.value);
       }
+    } else if (this._focusZone.value) {
+      focusSucceeded = this._focusZone.value.focus(forceIntoFirstElement);
+    }
+
+    return focusSucceeded;
+  }
 
-      return;
+  /**
+   * Sets focus to a specific child element within the OverflowSet.
+   * @param {HTMLElement} childElement The child element within the zone to focus.
+   * @returns True if focus could be set to an active element, false if no operation was taken.
+   */
+  public focusElement(childElement?: HTMLElement): boolean {
+    let focusSucceeded = false;
+
+    if (!childElement) {
+      return false;
     }
 
-    if (this._focusZone.value) {
-      this._focusZone.value.focus();
+    if (this.props.doNotContainWithinFocusZone) {
+      if (this._divContainer.value && elementContains(this._divContainer.value, childElement)) {
+        childElement.focus();
+        focusSucceeded = document.activeElement === childElement;
+      }
+    } else if (this._focusZone.value) {
+      focusSucceeded = this._focusZone.value.focusElement(childElement);
     }
+
+    return focusSucceeded;
   }
 
   private _onRenderItems = (items: IOverflowSetItemProps[]): JSX.Element[] => {

packages/office-ui-fabric-react/src/components/OverflowSet/OverflowSet.types.ts

@@ -5,9 +5,20 @@ import { IFocusZoneProps } from '../../FocusZone';
 
 export interface IOverflowSet {
   /**
- * Sets focus to the button.
- */
-  focus: () => void;
+   * Sets focus to the first tabbable item in the zone.
+   * @param {boolean} forceIntoFirstElement If true, focus will be forced into the first element, even if focus is already in the focus zone.
+   * @returns True if focus could be set to an active element, false if no operation was taken.
+   */
+  focus(forceIntoFirstElement?: boolean): boolean;
+
+  /**
+   * Sets focus to a specific child element within the zone. This can be used in conjunction with
+   * onBeforeFocus to created delayed focus scenarios (like animate the scroll position to the correct
+   * location and then focus.)
+   * @param {HTMLElement} childElement The child element within the zone to focus.
+   * @returns True if focus could be set to an active element, false if no operation was taken.
+   */
+  focusElement(childElement?: HTMLElement): boolean;
 }
 
 export interface IOverflowSetProps extends React.Props<OverflowSet> {