Add functions to ContextualMenuItem to open and close menus on command

common/changes/office-ui-fabric-react/keyou-contextual-menu-item-functions_2018-05-02-18-14.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "office-ui-fabric-react",
+      "comment": "Add ContextualMenuItem functions to open and close menus",
+      "type": "minor"
+    }
+  ],
+  "packageName": "office-ui-fabric-react",
+  "email": "[email protected]"
+}

packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenu.test.tsx

@@ -2,12 +2,14 @@ import * as React from 'react';
 import { Promise } from 'es6-promise';
 import * as ReactTestUtils from 'react-dom/test-utils';
 import {
-  KeyCodes
+  KeyCodes,
+  createRef
 } from '../../Utilities';
 import { FocusZoneDirection } from '../../FocusZone';
 
 import { ContextualMenu, canAnyMenuItemsCheck } from './ContextualMenu';
 import { IContextualMenuItem, ContextualMenuItemType } from './ContextualMenu.types';
+import { IContextualMenuRenderItem } from './ContextualMenuItem.types';
 import { LayerBase as Layer } from '../Layer/Layer.base';
 
 describe('ContextualMenu', () => {
@@ -823,4 +825,61 @@ describe('ContextualMenu', () => {
       expect(canAnyMenuItemsCheck(items)).toEqual(true);
     });
   });
+
+  describe('IContextualMenuRenderItem function tests', () => {
+    const contextualItem = createRef<IContextualMenuRenderItem>();
+    let menuDismissed: boolean;
+    const onDismiss = (ev?: any, dismissAll?: boolean) => { menuDismissed = true; };
+
+    beforeEach(() => {
+      menuDismissed = false;
+      const menu: IContextualMenuItem[] = [
+        {
+          name: 'Test1',
+          key: 'Test1',
+          renderItemRef: contextualItem,
+          subMenuProps: {
+            items: [
+              {
+                name: 'Test2',
+                key: 'Test2',
+                className: 'SubMenuClass'
+              },
+              {
+                name: 'Test3',
+                key: 'Test3',
+                className: 'SubMenuClass'
+              }
+            ],
+          }
+        }
+      ];
+
+      ReactTestUtils.renderIntoDocument<ContextualMenu>(
+        <ContextualMenu
+          onDismiss={ onDismiss }
+          items={ menu }
+        />
+      );
+    });
+
+    it('openSubMenu will open the item`s submenu if present', () => {
+      contextualItem.value!.openSubMenu();
+      expect(document.querySelector('.SubMenuClass')).not.toEqual(null);
+    });
+
+    it('dismissSubMenu will close the item`s submenu if present', () => {
+      // Open the submenu with a click
+      const menuItem = document.querySelector('button.ms-ContextualMenu-link') as HTMLButtonElement;
+      ReactTestUtils.Simulate.click(menuItem);
+      expect(document.querySelector('.SubMenuClass')).not.toEqual(null);
+      contextualItem.value!.dismissSubMenu();
+      expect(document.querySelector('.SubMenuClass')).toEqual(null);
+    });
+
+    it('dismissMenu will close the item`s menu', () => {
+      contextualItem.value!.dismissMenu();
+      expect(menuDismissed).toEqual(true);
+    });
+  });
 });

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

@@ -24,7 +24,8 @@ import {
   getFirstFocusable,
   getLastFocusable,
   css,
-  shouldWrapFocus
+  shouldWrapFocus,
+  createRef
 } from '../../Utilities';
 import { hasSubmenu, getIsChecked, isItemDisabled } from '../../utilities/contextualMenu/index';
 import { withResponsiveMode, ResponsiveMode } from '../../utilities/decorators/withResponsiveMode';
@@ -499,6 +500,8 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
     const itemHasSubmenu = hasSubmenu(item);
     const nativeProps = getNativeProps(item, anchorProperties);
     const disabled = isItemDisabled(item);
+    const anchorRef = createRef<HTMLAnchorElement>();
+    const dismissMenu = this.dismiss.bind(this, undefined);
 
     return (
       <div>
@@ -511,6 +514,7 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
             <a
               { ...nativeProps }
               { ...keytipAttributes }
+              ref={ anchorRef }
               href={ item.href }
               target={ item.target }
               rel={ anchorRel }
@@ -534,6 +538,11 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
                 index={ index }
                 onCheckmarkClick={ hasCheckmarks ? this._onItemClick : undefined }
                 hasIcons={ hasIcons }
+                componentRef={ item.renderItemRef }
+                openSubMenu={ this._onItemSubMenuExpand }
+                dismissSubMenu={ this._onSubMenuDismiss }
+                dismissMenu={ dismissMenu }
+                subMenuTargetRef={ anchorRef }
               />
             </a>
           ) }
@@ -599,6 +608,8 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
         hasMenu: true
       };
     }
+    const btnRef = createRef<HTMLButtonElement>();
+    const dismissMenu = this.dismiss.bind(this, undefined);
 
     return (
       <KeytipData
@@ -608,6 +619,7 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
       >
         { (keytipAttributes: any): JSX.Element => (
           <button
+            ref={ btnRef }
             { ...buttonNativeProperties as React.ButtonHTMLAttributes<HTMLButtonElement> }
             { ...itemButtonProperties as React.ButtonHTMLAttributes<HTMLButtonElement> }
             { ...keytipAttributes }
@@ -618,6 +630,11 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
               index={ index }
               onCheckmarkClick={ hasCheckmarks ? this._onItemClick : undefined }
               hasIcons={ hasIcons }
+              componentRef={ item.renderItemRef }
+              openSubMenu={ this._onItemSubMenuExpand }
+              dismissSubMenu={ this._onSubMenuDismiss }
+              dismissMenu={ dismissMenu }
+              subMenuTargetRef={ btnRef }
             />
           </button>
         ) }
@@ -635,6 +652,10 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
     hasIcons?: boolean): JSX.Element {
     const { contextualMenuItemAs } = this.props;
 
+    const openSubMenu = this._onItemSubMenuExpand.bind(this);
+    const dismissSubMenu = this._onSubMenuDismiss.bind(this);
+    const dismissMenu = this.dismiss.bind(this, undefined);
+
     return (
       <ContextualMenuSplitButton
         item={ item }
@@ -653,6 +674,10 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
         onItemClick={ this._onItemClick }
         onItemClickBase={ this._onItemClickBase }
         onItemKeyDown={ this._onItemKeyDown }
+        openSubMenu={ openSubMenu }
+        dismissSubMenu={ dismissSubMenu }
+        dismissMenu={ dismissMenu }
+        componentRef={ item.renderItemRef }
       />
     );
   }
@@ -889,7 +914,7 @@ export class ContextualMenu extends BaseComponent<IContextualMenuProps, IContext
     }
   }
 
-  private _onItemSubMenuExpand(item: IContextualMenuItem, target: HTMLElement) {
+  private _onItemSubMenuExpand = (item: IContextualMenuItem, target: HTMLElement): void => {
     if (this.state.expandedMenuItemKey !== item.key) {
 
       if (this.state.expandedMenuItemKey) {

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

@@ -15,7 +15,7 @@ import { IWithResponsiveModeState } from '../../utilities/decorators/withRespons
 import { IContextualMenuClassNames, IMenuItemClassNames } from './ContextualMenu.classNames';
 export { DirectionalHint } from '../../common/DirectionalHint';
 import { IVerticalDividerClassNames } from '../Divider/VerticalDivider.types';
-import { IContextualMenuItemProps } from './ContextualMenuItem.types';
+import { IContextualMenuItemProps, IContextualMenuRenderItem } from './ContextualMenuItem.types';
 import { IKeytipProps } from '../../Keytip';
 
 export enum ContextualMenuItemType {
@@ -462,6 +462,11 @@ export interface IContextualMenuItem {
    */
   keytipProps?: IKeytipProps;
 
+  /**
+   * Optional callback to access the IContextualMenuRenderItem interface. This will get passed down to the item that renders the ContextualMenuItem.
+   */
+  renderItemRef?: (component: IContextualMenuRenderItem | null) => void;
+
   /**
    * Any additional properties to use when custom rendering menu items.
    */
@@ -471,7 +476,6 @@ export interface IContextualMenuItem {
    * Optional prop to make an item readonly which is disabled but visitable by keyboard, will apply aria-readonly and some styling. Not supported by all components
    */
   inactive?: boolean;
-
 }
 
 export interface IContextualMenuSection extends React.Props<ContextualMenu> {

packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuItem.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { hasSubmenu, getIsChecked } from '../../utilities/contextualMenu/index';
-import { getRTL } from '../../Utilities';
+import { BaseComponent, getRTL } from '../../Utilities';
 import { Icon } from '../../Icon';
 import { IContextualMenuItemProps } from './ContextualMenuItem.types';
 
@@ -67,19 +67,42 @@ const renderSubMenuIcon = ({ item, classNames }: IContextualMenuItemProps) => {
   return null;
 };
 
-export const ContextualMenuItem: React.StatelessComponent<IContextualMenuItemProps> = (props) => {
-  const { item, classNames } = props;
+export class ContextualMenuItem extends BaseComponent<IContextualMenuItemProps, {}> {
+  public render() {
+    const { item, classNames } = this.props;
 
-  return (
-    <div
-      className={
-        item.split ? classNames.linkContentMenu : classNames.linkContent
-      }
-    >
-      { renderCheckMarkIcon(props) }
-      { renderItemIcon(props) }
-      { renderItemName(props) }
-      { renderSubMenuIcon(props) }
-    </div>
-  );
-};
+    return (
+      <div
+        className={
+          item.split ? classNames.linkContentMenu : classNames.linkContent
+        }
+      >
+        { renderCheckMarkIcon(this.props) }
+        { renderItemIcon(this.props) }
+        { renderItemName(this.props) }
+        { renderSubMenuIcon(this.props) }
+      </div>
+    );
+  }
+
+  public openSubMenu = (): void => {
+    const { item, openSubMenu, subMenuTargetRef } = this.props;
+    if (hasSubmenu(item) && openSubMenu && subMenuTargetRef && subMenuTargetRef.current) {
+      openSubMenu(item, subMenuTargetRef.current);
+    }
+  }
+
+  public dismissSubMenu = (): void => {
+    const { item, dismissSubMenu } = this.props;
+    if (hasSubmenu(item) && dismissSubMenu) {
+      dismissSubMenu();
+    }
+  }
+
+  public dismissMenu = (dismissAll?: boolean): void => {
+    const { dismissMenu } = this.props;
+    if (dismissMenu) {
+      dismissMenu(dismissAll);
+    }
+  }
+}

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

@@ -1,8 +1,31 @@
 import { IContextualMenuItem } from './ContextualMenu.types';
 import { IMenuItemClassNames } from './ContextualMenu.classNames';
+import { RefObject } from '../../Utilities';
 
-export interface IContextualMenuItemProps
-  extends React.HTMLAttributes<IContextualMenuItemProps> {
+export interface IContextualMenuRenderItem {
+  /**
+   * Function to open this item's subMenu, if present.
+   */
+  openSubMenu: () => void;
+
+  /**
+   * Function to close this item's subMenu, if present.
+   */
+  dismissSubMenu: () => void;
+
+  /**
+   * Dismiss the menu this item belongs to.
+   */
+  dismissMenu: (dismissAll?: boolean) => void;
+}
+
+export interface IContextualMenuItemProps extends React.HTMLAttributes<IContextualMenuItemProps> {
+
+  /**
+   * Optional callback to access the IContextualMenuRenderItem interface. Use this instead of ref for accessing
+   * the public methods and properties of the component.
+   */
+  componentRef?: (component: IContextualMenuRenderItem | null) => void;
 
   /**
    * The item to display
@@ -28,4 +51,25 @@ export interface IContextualMenuItemProps
    * Click handler for the checkmark
    */
   onCheckmarkClick?: ((item: IContextualMenuItem, ev: React.MouseEvent<HTMLElement>) => void);
+
+  /**
+   * This prop will get set by ContextualMenu and can be called to open this item's subMenu, if present.
+   */
+  openSubMenu?: (item: IContextualMenuItem, target: HTMLElement) => void;
+
+  /**
+   * This prop will get set by ContextualMenu and can be called to close this item's subMenu, if present.
+   */
+  dismissSubMenu?: () => void;
+
+  /**
+   * This prop will get set by ContextualMenu and can be called to close the menu this item belongs to.
+   * If dismissAll is true, all menus will be closed.
+   */
+  dismissMenu?: (dismissAll?: boolean) => void;
+
+  /**
+   * This prop will get set by ContextualMenu, will be the target to attach the submenu to when openSubMenu is triggered.
+   */
+  subMenuTargetRef?: RefObject<HTMLElement>;
 }

packages/office-ui-fabric-react/src/components/ContextualMenu/ContextualMenuSplitButton.tsx

@@ -13,7 +13,7 @@ import {
 } from './ContextualMenu.classNames';
 import { ContextualMenuItem } from './ContextualMenuItem';
 import { KeytipData } from '../../KeytipData';
-import { getIsChecked, isItemDisabled } from '../../utilities/contextualMenu/index';
+import { getIsChecked, isItemDisabled, hasSubmenu } from '../../utilities/contextualMenu/index';
 import { VerticalDivider } from '../../Divider';
 import { IContextualMenuSplitButtonProps } from './ContextualMenuSplitButton.types';
 
@@ -74,6 +74,27 @@ export class ContextualMenuSplitButton extends BaseComponent<IContextualMenuSpli
     );
   }
 
+  public openSubMenu = (): void => {
+    const { item, openSubMenu } = this.props;
+    if (hasSubmenu(item) && openSubMenu && this._splitButton) {
+      openSubMenu(item, this._splitButton);
+    }
+  }
+
+  public dismissSubMenu = (): void => {
+    const { item, dismissSubMenu } = this.props;
+    if (hasSubmenu(item) && dismissSubMenu) {
+      dismissSubMenu();
+    }
+  }
+
+  public dismissMenu = (dismissAll?: boolean): void => {
+    const { dismissMenu } = this.props;
+    if (dismissMenu) {
+      dismissMenu(dismissAll);
+    }
+  }
+
   private _renderSplitPrimaryButton(item: IContextualMenuItem, classNames: IMenuItemClassNames, index: number, hasCheckmarks: boolean, hasIcons: boolean) {
     const isChecked: boolean | null | undefined = getIsChecked(item);
     const canCheck: boolean = isChecked !== null;