fix(material/menu): not interrupting keyboard events to other overlays (#22928)

This is a resubmit of #22856 which had some issues in g3.

For historical reasons, `mat-menu` doesn't use the same keyboard event dispatcher as the other overlays. To work around it, previously we added a dummy subscription so that the menu would still show up in the overlay keyboard stack.

This works for most events, but it breaks down for the escape key, because closing the menu removes it from the stack immediately, allowing the event to bubble up to the document and be dispatched to the next overlay in the stack.

These changes resolve the issue by adding a stopPropagation call.

Fixes #22694.

(cherry picked from commit 5f529db)

Author: crisbeto

src/material-experimental/mdc-menu/menu.spec.ts

@@ -439,13 +439,15 @@ describe('MDC-based MatMenu', () => {
 
     const panel = overlayContainerElement.querySelector('.mat-mdc-menu-panel')!;
     const event = createKeyboardEvent('keydown', ESCAPE);
+    spyOn(event, 'stopPropagation').and.callThrough();
 
     dispatchEvent(panel, event);
     fixture.detectChanges();
     tick(500);
 
     expect(overlayContainerElement.textContent).toBe('');
     expect(event.defaultPrevented).toBe(true);
+    expect(event.stopPropagation).toHaveBeenCalled();
   }));
 
   it('should not close the menu when pressing ESCAPE with a modifier', fakeAsync(() => {

src/material/menu/menu.spec.ts

@@ -440,13 +440,15 @@ describe('MatMenu', () => {
 
     const panel = overlayContainerElement.querySelector('.mat-menu-panel')!;
     const event = createKeyboardEvent('keydown', ESCAPE);
+    spyOn(event, 'stopPropagation').and.callThrough();
 
     dispatchEvent(panel, event);
     fixture.detectChanges();
     tick(500);
 
     expect(overlayContainerElement.textContent).toBe('');
     expect(event.defaultPrevented).toBe(true);
+    expect(event.stopPropagation).toHaveBeenCalled();
   }));
 
   it('should not close the menu when pressing ESCAPE with a modifier', fakeAsync(() => {

src/material/menu/menu.ts

@@ -337,7 +337,12 @@ export class _MatMenuBase implements AfterContentInit, MatMenuPanel<MatMenuItem>
         }
 
         manager.onKeydown(event);
+        return;
     }
+
+    // Don't allow the event to propagate if we've already handled it, or it may
+    // end up reaching other overlays that were opened earlier (see #22694).
+    event.stopPropagation();
   }
 
   /**