feat(cdk-experimental/menu): add the ability to open/close menus on mouse click and hover

Add the ability to open/close a menu when a user clicks a menu trigger and when a user hovers over
menu items. Additionally, keep track of hovered menu items and sync them with the FocusKeyManager
allowing a user to continue with a keyboard where they left off with their mouse.

Author: andy9775

src/cdk-experimental/menu/focus-mouse-manager.spec.ts

@@ -0,0 +1,103 @@
+import {Component, QueryList, ElementRef, ViewChildren, AfterViewInit} from '@angular/core';
+import {async, ComponentFixture, TestBed} from '@angular/core/testing';
+import {createMouseEvent, dispatchEvent} from '@angular/cdk/testing/private';
+import {FocusMouseManager, FocusableElement} from './focus-mouse-manager';
+
+describe('FocusMouseManger', () => {
+  let fixture: ComponentFixture<MultiElementWithConditionalComponent>;
+  let focusManager: FocusMouseManager<MockWrapper>;
+  let mockElements: MockWrapper[];
+
+  /** Get the components under test from the fixture. */
+  function getComponentsForTesting() {
+    focusManager = fixture.componentInstance.focusManager;
+    mockElements = fixture.componentInstance._allItems.toArray();
+  }
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [MultiElementWithConditionalComponent, MockWrapper],
+    }).compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(MultiElementWithConditionalComponent);
+    fixture.detectChanges();
+
+    getComponentsForTesting();
+  });
+
+  it('should emit on mouseEnter observable when mouse enters a tracked element', () => {
+    const spy = jasmine.createSpy('mouse enter spy');
+    focusManager.mouseEntered.subscribe(spy);
+
+    const event = createMouseEvent('mouseenter');
+    dispatchEvent(mockElements[0]._elementRef.nativeElement, event);
+    fixture.detectChanges();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(mockElements[0]);
+  });
+
+  it('should be aware of newly created/added components and track them', () => {
+    const spy = jasmine.createSpy('mouse enter spy');
+    focusManager.mouseEntered.subscribe(spy);
+
+    expect(fixture.componentInstance.showThird).toBeFalse();
+    fixture.componentInstance.showThird = true;
+    fixture.detectChanges();
+    getComponentsForTesting();
+
+    const mouseEnter = createMouseEvent('mouseenter');
+    dispatchEvent(mockElements[2]._elementRef.nativeElement, mouseEnter);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(mockElements[2]);
+  });
+
+  it('should toggle focused items when hovering from one to another', () => {
+    const spy = jasmine.createSpy('focus toggle spy');
+    focusManager.mouseEntered.subscribe(spy);
+
+    const mouseEnter = createMouseEvent('mouseenter');
+    dispatchEvent(mockElements[0]._elementRef.nativeElement, mouseEnter);
+    dispatchEvent(mockElements[1]._elementRef.nativeElement, mouseEnter);
+
+    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy.calls.argsFor(0)[0]).toEqual(mockElements[0]);
+    expect(spy.calls.argsFor(1)[0]).toEqual(mockElements[1]);
+  });
+});
+
+@Component({
+  selector: 'wrapper',
+  template: `<ng-content></ng-content>`,
+})
+class MockWrapper implements FocusableElement {
+  constructor(readonly _elementRef: ElementRef<HTMLElement>) {}
+}
+
+@Component({
+  template: `
+    <div>
+      <wrapper>First</wrapper>
+      <wrapper>Second</wrapper>
+      <wrapper *ngIf="showThird">Third</wrapper>
+    </div>
+  `,
+})
+class MultiElementWithConditionalComponent implements AfterViewInit {
+  /** Whether the third element should be displayed. */
+  showThird = false;
+
+  /** All mock elements. */
+  @ViewChildren(MockWrapper)
+  readonly _allItems: QueryList<MockWrapper>;
+
+  /** Manages elements under mouse focus. */
+  focusManager: FocusMouseManager<MockWrapper>;
+
+  ngAfterViewInit() {
+    this.focusManager = new FocusMouseManager(this._allItems);
+  }
+}

src/cdk-experimental/menu/focus-mouse-manager.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {QueryList, ElementRef} from '@angular/core';
+import {fromEvent, Observable} from 'rxjs';
+import {mapTo, mergeAll, takeUntil, startWith, mergeMap} from 'rxjs/operators';
+
+/** Item to track for mouse focus events. */
+export interface FocusableElement {
+  /** A reference to the element to be tracked. */
+  _elementRef: ElementRef<HTMLElement>;
+}
+
+/**
+ * FocusMouseManager keeps track of the element under mouse focus. It emits the element on an
+ * observable when an element is moused into.
+ */
+export class FocusMouseManager<T extends FocusableElement> {
+  /** Observable which emits when the mouse enters one of the managed elements. */
+  readonly mouseEntered: Observable<T> = this._getMouseEnterObservable();
+
+  constructor(private readonly _elements: QueryList<T>) {}
+
+  /**
+   * Get an observable which emits when the mouse enters a given FocusableElement and consider
+   * any elements added or removed from the list of managed elements.
+   */
+  private _getMouseEnterObservable() {
+    return this._elements.changes.pipe(
+      startWith(this._elements),
+      mergeMap((list: QueryList<T>) =>
+        list.map(element =>
+          fromEvent(element._elementRef.nativeElement, 'mouseenter').pipe(
+            mapTo(element),
+            takeUntil(this._elements.changes)
+          )
+        )
+      ),
+      mergeAll()
+    );
+  }
+}

src/cdk-experimental/menu/menu-bar.spec.ts

@@ -27,6 +27,7 @@ import {
   dispatchKeyboardEvent,
   createKeyboardEvent,
   dispatchEvent,
+  createMouseEvent,
 } from '@angular/cdk/testing/private';
 import {CdkMenuBar} from './menu-bar';
 import {CdkMenuModule} from './menu-module';
@@ -837,6 +838,195 @@ describe('MenuBar', () => {
         .toBe(1);
     });
   });
+
+  describe('Mouse handling', () => {
+    let fixture: ComponentFixture<MultiMenuWithSubmenu>;
+    let nativeMenus: HTMLElement[];
+    let menuBarNativeItems: HTMLButtonElement[];
+    let fileMenuNativeItems: HTMLButtonElement[];
+    let shareMenuNativeItems: HTMLButtonElement[];
+
+    /** Get menus and items used for tests. */
+    function grabElementsForTesting() {
+      nativeMenus = fixture.componentInstance.nativeMenus.map(e => e.nativeElement);
+
+      menuBarNativeItems = fixture.componentInstance.nativeItems
+        .map(e => e.nativeElement)
+        .slice(0, 2); // menu bar has the first 2 menu items
+
+      fileMenuNativeItems = fixture.componentInstance.nativeItems
+        .map(e => e.nativeElement)
+        .slice(2, 5); // file menu has the next 3 menu items
+
+      shareMenuNativeItems = fixture.componentInstance.nativeItems
+        .map(e => e.nativeElement)
+        .slice(5, 7); // share menu has the next 2 menu items
+    }
+
+    /** Run change detection and extract then set the rendered elements. */
+    function detectChanges() {
+      fixture.detectChanges();
+      grabElementsForTesting();
+    }
+
+    /** Mock mouse events required to open the file menu. */
+    function openFileMenu() {
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('click'));
+      detectChanges();
+    }
+
+    /** Mock mouse events required to open the share menu. */
+    function openShareMenu() {
+      dispatchEvent(fileMenuNativeItems[1], createMouseEvent('mouseenter'));
+      detectChanges();
+    }
+
+    beforeEach(async(() => {
+      TestBed.configureTestingModule({
+        imports: [CdkMenuModule],
+        declarations: [MultiMenuWithSubmenu],
+      }).compileComponents();
+    }));
+
+    beforeEach(() => {
+      fixture = TestBed.createComponent(MultiMenuWithSubmenu);
+      detectChanges();
+    });
+
+    it('should toggle menu from menu bar when clicked', () => {
+      openFileMenu();
+
+      expect(nativeMenus.length).toBe(1);
+      expect(nativeMenus[0].id).toBe('file_menu');
+
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('click'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(0);
+    });
+
+    it('should not open menu when hovering over trigger in menu bar with no open siblings', () => {
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(0);
+    });
+
+    it(
+      'should not change focused items when hovering over trigger in menu bar with no open ' +
+        'siblings',
+      () => {
+        dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+        detectChanges();
+
+        expect(document.querySelector(':focus')).not.toEqual(menuBarNativeItems[0]);
+        expect(document.querySelector(':focus')).not.toEqual(menuBarNativeItems[1]);
+      }
+    );
+
+    it(
+      'should toggle open menus in menu bar if sibling is open when mouse moves from one item ' +
+        'to the other',
+      () => {
+        openFileMenu();
+
+        dispatchEvent(menuBarNativeItems[1], createMouseEvent('mouseenter'));
+        detectChanges();
+
+        expect(nativeMenus.length).toBe(1);
+        expect(nativeMenus[0].id).toBe('edit_menu');
+
+        dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+        detectChanges();
+
+        expect(nativeMenus.length).toBe(1);
+        expect(nativeMenus[0].id).toBe('file_menu');
+
+        dispatchEvent(menuBarNativeItems[1], createMouseEvent('mouseenter'));
+        detectChanges();
+
+        expect(nativeMenus.length).toBe(1);
+        expect(nativeMenus[0].id).toBe('edit_menu');
+      }
+    );
+
+    it('should not close the menu when re-hovering the trigger', () => {
+      openFileMenu();
+
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+
+      expect(nativeMenus.length).toBe(1);
+      expect(nativeMenus[0].id).toBe('file_menu');
+    });
+
+    it('should open a submenu when hovering over a trigger in a menu with no siblings open', () => {
+      openFileMenu();
+
+      openShareMenu();
+
+      expect(nativeMenus.length).toBe(2);
+      expect(nativeMenus[0].id).toBe('file_menu');
+      expect(nativeMenus[1].id).toBe('share_menu');
+    });
+
+    it('should close menu when hovering over non-triggering sibling menu item', () => {
+      openFileMenu();
+      openShareMenu();
+
+      dispatchEvent(fileMenuNativeItems[0], createMouseEvent('mouseenter'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(1);
+      expect(nativeMenus[0].id).toBe('file_menu');
+    });
+
+    it('should retain open menus when hovering over root level trigger which opened them', () => {
+      openFileMenu();
+      openShareMenu();
+
+      dispatchEvent(menuBarNativeItems[0], createMouseEvent('mouseenter'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(2);
+    });
+
+    it('should close out the menu tree when hovering over sibling item in menu bar', () => {
+      openFileMenu();
+      openShareMenu();
+
+      dispatchEvent(menuBarNativeItems[1], createMouseEvent('mouseenter'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(1);
+      expect(nativeMenus[0].id).toBe('edit_menu');
+    });
+
+    it('should close out the menu tree when clicking a non-triggering menu item', () => {
+      openFileMenu();
+      openShareMenu();
+
+      dispatchEvent(shareMenuNativeItems[0], createMouseEvent('mouseenter'));
+      dispatchEvent(shareMenuNativeItems[0], createMouseEvent('click'));
+      detectChanges();
+
+      expect(nativeMenus.length).toBe(0);
+    });
+
+    it(
+      'should allow keyboard down arrow to focus next item after mouse sets focus to' +
+        ' initial item',
+      () => {
+        openFileMenu();
+        dispatchEvent(fileMenuNativeItems[0], createMouseEvent('mouseenter'));
+        detectChanges();
+
+        dispatchKeyboardEvent(nativeMenus[0], 'keydown', DOWN_ARROW);
+
+        expect(document.querySelector(':focus')).toEqual(fileMenuNativeItems[1]);
+      }
+    );
+  });
 });
 
 @Component({