feat(material/menu): add support for context menu

Adds the new `MatContextMenuTrigger` directive that allows users to mark an area as a trigger for a menu. When the user right-clicks inside of the area, the menu will be opened next to their pointer.

Fixes #5007.

Author: crisbeto

goldens/material/menu/index.api.md

@@ -49,6 +49,40 @@ export const MAT_MENU_SCROLL_STRATEGY_FACTORY_PROVIDER: {
     useFactory: typeof MAT_MENU_SCROLL_STRATEGY_FACTORY;
 };
 
+// @public
+export class MatContextMenuTrigger extends MatMenuTriggerBase implements OnDestroy {
+    constructor();
+    // (undocumented)
+    protected _destroyMenu(reason: MenuCloseReason): void;
+    disabled: boolean;
+    // (undocumented)
+    protected _getOutsideClickStream(overlayRef: OverlayRef): rxjs.Observable<MouseEvent>;
+    // (undocumented)
+    protected _getOverlayOrigin(): {
+        x: number;
+        y: number;
+        initialX: number;
+        initialY: number;
+        initialScrollX: number;
+        initialScrollY: number;
+    };
+    protected _handleContextMenuEvent(event: MouseEvent): void;
+    get menu(): MatMenuPanel | null;
+    set menu(menu: MatMenuPanel | null);
+    readonly menuClosed: EventEmitter<void>;
+    menuData: any;
+    readonly menuOpened: EventEmitter<void>;
+    // (undocumented)
+    static ngAcceptInputType_disabled: unknown;
+    // (undocumented)
+    ngOnDestroy(): void;
+    restoreFocus: boolean;
+    // (undocumented)
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MatContextMenuTrigger, "[matContextMenuTriggerFor]", ["matContextMenuTrigger"], { "menu": { "alias": "matContextMenuTriggerFor"; "required": true; }; "menuData": { "alias": "matContextMenuTriggerData"; "required": false; }; "restoreFocus": { "alias": "matContextMenuTriggerRestoreFocus"; "required": false; }; "disabled": { "alias": "matContextMenuTriggerDisabled"; "required": false; }; }, { "menuOpened": "menuOpened"; "menuClosed": "menuClosed"; }, never, never, true, never>;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<MatContextMenuTrigger, never>;
+}
+
 // @public (undocumented)
 export class MatMenu implements AfterContentInit, MatMenuPanel<MatMenuItem>, OnInit, OnDestroy {
     constructor(...args: unknown[]);

src/dev-app/menu/menu-demo.html

@@ -194,4 +194,29 @@
   </div>
 </div>
 
-<div style="height: 500px">This div is for testing scrolled menus.</div>
+<div class="demo-context-menu-area" [matContextMenuTriggerFor]="contextMenu">
+  Right click here to trigger a context menu
+</div>
+
+<mat-menu #contextMenu>
+  <button mat-menu-item>
+    <mat-icon>content_cut</mat-icon>
+    Cut
+  </button>
+  <button mat-menu-item>
+    <mat-icon>content_copy</mat-icon>
+    Copy
+  </button>
+  <button mat-menu-item>
+    <mat-icon>content_paste</mat-icon>
+    Paste
+  </button>
+  <button mat-menu-item>
+    <mat-icon>print</mat-icon>
+    Print
+  </button>
+</mat-menu>
+
+<div style="height: 500px">
+  <!-- Makes the page scrollable for easier testing. -->
+</div>

src/dev-app/menu/menu-demo.scss

@@ -11,3 +11,13 @@
     justify-content: flex-end;
   }
 }
+
+.demo-context-menu-area {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 500px;
+  max-width: 500px;
+  outline: dashed 1px;
+}

src/material/menu/BUILD.bazel

@@ -67,6 +67,7 @@ sass_binary(
 ng_project(
     name = "menu",
     srcs = [
+        "context-menu-trigger.ts",
         "index.ts",
         "menu.ts",
         "menu-animations.ts",

src/material/menu/context-menu-trigger.spec.ts

@@ -0,0 +1,192 @@
+import {Component, signal} from '@angular/core';
+import {ComponentFixture, fakeAsync, flush, TestBed} from '@angular/core/testing';
+import {MatContextMenuTrigger} from './context-menu-trigger';
+import {MatMenu} from './menu';
+import {MatMenuItem} from './menu-item';
+import {dispatchFakeEvent, dispatchMouseEvent} from '@angular/cdk/testing/private';
+
+describe('context menu trigger', () => {
+  let fixture: ComponentFixture<ContextMenuTest>;
+
+  function getTrigger(): HTMLElement {
+    return fixture.nativeElement.querySelector('.area');
+  }
+
+  function getMenu(): HTMLElement | null {
+    return document.querySelector('.mat-mdc-menu-panel');
+  }
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ContextMenuTest);
+    fixture.detectChanges();
+  });
+
+  it('should open the menu on the `contextmenu` event', () => {
+    expect(getMenu()).toBe(null);
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+  });
+
+  it('should close the menu when clicking outside the trigger', fakeAsync(() => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+
+    document.body.click();
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBe(null);
+  }));
+
+  it('should reposition the menu when right-clicking within the area', () => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    let menuRect = getMenu()!.getBoundingClientRect();
+    expect(menuRect.top).toBe(10);
+    expect(menuRect.left).toBe(10);
+
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 50, 75);
+    fixture.detectChanges();
+    menuRect = getMenu()!.getBoundingClientRect();
+    expect(menuRect.top).toBe(75);
+    expect(menuRect.left).toBe(50);
+  });
+
+  it('should ignore the first auxclick after opening', fakeAsync(() => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+
+    dispatchMouseEvent(document.body, 'auxclick');
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBeTruthy();
+
+    dispatchMouseEvent(document.body, 'auxclick');
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBe(null);
+  }));
+
+  it('should close on `contextmenu` events outside the trigger', fakeAsync(() => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+
+    dispatchMouseEvent(document.body, 'contextmenu');
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBe(null);
+  }));
+
+  it('should not close on `contextmenu` events from inside the menu', fakeAsync(() => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+
+    dispatchMouseEvent(getMenu()!, 'contextmenu');
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBeTruthy();
+  }));
+
+  it('should set aria-controls on the trigger while the menu is open', () => {
+    expect(getTrigger().getAttribute('aria-controls')).toBe(null);
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getTrigger().getAttribute('aria-controls')).toBeTruthy();
+  });
+
+  it('should reposition the menu as the user is scrolling', () => {
+    const scroller = document.createElement('div');
+    scroller.style.height = '1000px';
+    fixture.nativeElement.appendChild(scroller);
+
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    let menuRect = getMenu()!.getBoundingClientRect();
+    expect(menuRect.top).toBe(10);
+    expect(menuRect.left).toBe(10);
+
+    scrollTo(0, 100);
+    dispatchFakeEvent(document, 'scroll');
+    fixture.detectChanges();
+    menuRect = getMenu()!.getBoundingClientRect();
+    expect(menuRect.top).toBe(-90);
+    expect(menuRect.left).toBe(10);
+
+    window.scroll(0, 0);
+    scroller.remove();
+  });
+
+  it('should emit events when the menu is opened and closed', fakeAsync(() => {
+    const {opened, closed} = fixture.componentInstance;
+    expect(opened).toHaveBeenCalledTimes(0);
+    expect(closed).toHaveBeenCalledTimes(0);
+
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(opened).toHaveBeenCalledTimes(1);
+    expect(closed).toHaveBeenCalledTimes(0);
+
+    document.body.click();
+    fixture.detectChanges();
+    flush();
+    expect(opened).toHaveBeenCalledTimes(1);
+    expect(closed).toHaveBeenCalledTimes(1);
+  }));
+
+  it('should close the menu if the trigger is destroyed', fakeAsync(() => {
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBeTruthy();
+
+    fixture.componentInstance.showTrigger.set(false);
+    fixture.detectChanges();
+    flush();
+    expect(getMenu()).toBe(null);
+  }));
+
+  it('should not open when clicking on a disabled context menu trigger', () => {
+    fixture.componentInstance.disabled.set(true);
+    fixture.detectChanges();
+    expect(getTrigger().classList).toContain('mat-context-menu-trigger-disabled');
+    expect(getMenu()).toBe(null);
+    dispatchMouseEvent(getTrigger(), 'contextmenu', 10, 10);
+    fixture.detectChanges();
+    expect(getMenu()).toBe(null);
+  });
+});
+
+@Component({
+  template: `
+    @if (showTrigger()) {
+      <div
+        class="area"
+        [matContextMenuTriggerFor]="menu"
+        [matContextMenuTriggerDisabled]="disabled()"
+        (menuOpened)="opened()"
+        (menuClosed)="closed()"></div>
+    }
+    <mat-menu #menu>
+      <button mat-menu-item>One</button>
+      <button mat-menu-item>Two</button>
+      <button mat-menu-item>Three</button>
+    </mat-menu>
+  `,
+  imports: [MatContextMenuTrigger, MatMenu, MatMenuItem],
+  styles: `
+    .area {
+      width: 200px;
+      height: 200px;
+      outline: solid 1px;
+    }
+  `,
+})
+class ContextMenuTest {
+  showTrigger = signal(true);
+  disabled = signal(false);
+  opened = jasmine.createSpy('opened');
+  closed = jasmine.createSpy('closed');
+}