feat(menu): add support for passing role to close events

Author: brandyscarney

core/api.txt

@@ -1000,15 +1000,15 @@ ion-menu,prop,menuId,string | undefined,undefined,false,true
 ion-menu,prop,side,"end" | "start",'start',false,true
 ion-menu,prop,swipeGesture,boolean,true,false,false
 ion-menu,prop,type,"overlay" | "push" | "reveal" | undefined,undefined,false,false
-ion-menu,method,close,close(animated?: boolean) => Promise<boolean>
+ion-menu,method,close,close(animated?: boolean, role?: string) => Promise<boolean>
 ion-menu,method,isActive,isActive() => Promise<boolean>
 ion-menu,method,isOpen,isOpen() => Promise<boolean>
 ion-menu,method,open,open(animated?: boolean) => Promise<boolean>
-ion-menu,method,setOpen,setOpen(shouldOpen: boolean, animated?: boolean) => Promise<boolean>
+ion-menu,method,setOpen,setOpen(shouldOpen: boolean, animated?: boolean, role?: string) => Promise<boolean>
 ion-menu,method,toggle,toggle(animated?: boolean) => Promise<boolean>
-ion-menu,event,ionDidClose,void,true
+ion-menu,event,ionDidClose,MenuCloseEventDetail,true
 ion-menu,event,ionDidOpen,void,true
-ion-menu,event,ionWillClose,void,true
+ion-menu,event,ionWillClose,MenuCloseEventDetail,true
 ion-menu,event,ionWillOpen,void,true
 ion-menu,css-prop,--background,ios
 ion-menu,css-prop,--background,md

core/src/components.d.ts

@@ -18,7 +18,7 @@ import { ScrollBaseDetail, ScrollDetail } from "./components/content/content-int
 import { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
 import { SpinnerTypes } from "./components/spinner/spinner-configs";
 import { InputChangeEventDetail, InputInputEventDetail } from "./components/input/input-interface";
-import { MenuChangeEventDetail, MenuType, Side } from "./components/menu/menu-interface";
+import { MenuChangeEventDetail, MenuCloseEventDetail, MenuType, Side } from "./components/menu/menu-interface";
 import { ModalBreakpointChangeEventDetail, ModalHandleBehavior } from "./components/modal/modal-interface";
 import { NavComponent, NavComponentWithProps, NavOptions, RouterOutletOptions, SwipeGestureHandler, TransitionDoneFn, TransitionInstruction } from "./components/nav/nav-interface";
 import { ViewController } from "./components/nav/view-controller";
@@ -53,7 +53,7 @@ export { ScrollBaseDetail, ScrollDetail } from "./components/content/content-int
 export { DatetimeChangeEventDetail, DatetimeHighlight, DatetimeHighlightCallback, DatetimeHourCycle, DatetimePresentation, FormatOptions, TitleSelectedDatesFormatter } from "./components/datetime/datetime-interface";
 export { SpinnerTypes } from "./components/spinner/spinner-configs";
 export { InputChangeEventDetail, InputInputEventDetail } from "./components/input/input-interface";
-export { MenuChangeEventDetail, MenuType, Side } from "./components/menu/menu-interface";
+export { MenuChangeEventDetail, MenuCloseEventDetail, MenuType, Side } from "./components/menu/menu-interface";
 export { ModalBreakpointChangeEventDetail, ModalHandleBehavior } from "./components/modal/modal-interface";
 export { NavComponent, NavComponentWithProps, NavOptions, RouterOutletOptions, SwipeGestureHandler, TransitionDoneFn, TransitionInstruction } from "./components/nav/nav-interface";
 export { ViewController } from "./components/nav/view-controller";
@@ -1596,7 +1596,7 @@ export namespace Components {
         /**
           * Closes the menu. If the menu is already closed or it can't be closed, it returns `false`.
          */
-        "close": (animated?: boolean) => Promise<boolean>;
+        "close": (animated?: boolean, role?: string) => Promise<boolean>;
         /**
           * The `id` of the main content. When using a router this is typically `ion-router-outlet`. When not using a router, this is typically your main view's `ion-content`. This is not the id of the `ion-content` inside of your `ion-menu`.
          */
@@ -1628,7 +1628,7 @@ export namespace Components {
         /**
           * Opens or closes the button. If the operation can't be completed successfully, it returns `false`.
          */
-        "setOpen": (shouldOpen: boolean, animated?: boolean) => Promise<boolean>;
+        "setOpen": (shouldOpen: boolean, animated?: boolean, role?: string) => Promise<boolean>;
         /**
           * Which side of the view the menu should be placed.
          */
@@ -3969,9 +3969,9 @@ declare global {
     };
     interface HTMLIonMenuElementEventMap {
         "ionWillOpen": void;
-        "ionWillClose": void;
+        "ionWillClose": MenuCloseEventDetail;
         "ionDidOpen": void;
-        "ionDidClose": void;
+        "ionDidClose": MenuCloseEventDetail;
         "ionMenuChange": MenuChangeEventDetail;
     }
     interface HTMLIonMenuElement extends Components.IonMenu, HTMLStencilElement {
@@ -6364,7 +6364,7 @@ declare namespace LocalJSX {
         /**
           * Emitted when the menu is closed.
          */
-        "onIonDidClose"?: (event: IonMenuCustomEvent<void>) => void;
+        "onIonDidClose"?: (event: IonMenuCustomEvent<MenuCloseEventDetail>) => void;
         /**
           * Emitted when the menu is open.
          */
@@ -6376,7 +6376,7 @@ declare namespace LocalJSX {
         /**
           * Emitted when the menu is about to be closed.
          */
-        "onIonWillClose"?: (event: IonMenuCustomEvent<void>) => void;
+        "onIonWillClose"?: (event: IonMenuCustomEvent<MenuCloseEventDetail>) => void;
         /**
           * Emitted when the menu is about to be opened.
          */

core/src/components/menu/menu-interface.ts

@@ -22,7 +22,7 @@ export interface MenuI {
   close(animated?: boolean): Promise<boolean>;
   toggle(animated?: boolean): Promise<boolean>;
   setOpen(shouldOpen: boolean, animated?: boolean): Promise<boolean>;
-  _setOpen(shouldOpen: boolean, animated?: boolean): Promise<boolean>;
+  _setOpen(shouldOpen: boolean, animated?: boolean, role?: string): Promise<boolean>;
 }
 
 export interface MenuControllerI {
@@ -42,14 +42,18 @@ export interface MenuControllerI {
   _createAnimation(type: string, menuCmp: MenuI): Promise<Animation>;
   _register(menu: MenuI): void;
   _unregister(menu: MenuI): void;
-  _setOpen(menu: MenuI, shouldOpen: boolean, animated: boolean): Promise<boolean>;
+  _setOpen(menu: MenuI, shouldOpen: boolean, animated: boolean, role?: string): Promise<boolean>;
 }
 
 export interface MenuChangeEventDetail {
   disabled: boolean;
   open: boolean;
 }
 
+export interface MenuCloseEventDetail {
+  role?: string;
+}
+
 export interface MenuCustomEvent<T = any> extends CustomEvent {
   detail: T;
   target: HTMLIonMenuElement;

core/src/components/menu/menu.tsx

@@ -7,14 +7,14 @@ import { shouldUseCloseWatcher } from '@utils/hardware-back-button';
 import type { Attributes } from '@utils/helpers';
 import { inheritAriaAttributes, assert, clamp, isEndSide as isEnd } from '@utils/helpers';
 import { menuController } from '@utils/menu-controller';
-import { getPresentedOverlay } from '@utils/overlays';
+import { BACKDROP, ESCAPE, GESTURE, getPresentedOverlay } from '@utils/overlays';
 import { hostContext } from '@utils/theme';
 
 import { config } from '../../global/config';
 import { getIonMode } from '../../global/ionic-global';
 import type { Animation, Gesture, GestureDetail } from '../../interface';
 
-import type { MenuChangeEventDetail, MenuI, MenuType, Side } from './menu-interface';
+import type { MenuChangeEventDetail, MenuCloseEventDetail, MenuI, MenuType, Side } from './menu-interface';
 
 const iosEasing = 'cubic-bezier(0.32,0.72,0,1)';
 const mdEasing = 'cubic-bezier(0.0,0.0,0.2,1)';
@@ -179,7 +179,7 @@ export class Menu implements ComponentInterface, MenuI {
   /**
    * Emitted when the menu is about to be closed.
    */
-  @Event() ionWillClose!: EventEmitter<void>;
+  @Event() ionWillClose!: EventEmitter<MenuCloseEventDetail>;
   /**
    * Emitted when the menu is open.
    */
@@ -188,7 +188,7 @@ export class Menu implements ComponentInterface, MenuI {
   /**
    * Emitted when the menu is closed.
    */
-  @Event() ionDidClose!: EventEmitter<void>;
+  @Event() ionDidClose!: EventEmitter<MenuCloseEventDetail>;
 
   /**
    * Emitted when the menu state is changed.
@@ -322,23 +322,9 @@ export class Menu implements ComponentInterface, MenuI {
     }
   }
 
-  @Listen('click', { capture: true })
-  onBackdropClick(ev: any) {
-    // TODO(FW-2832): type (CustomEvent triggers errors which should be sorted)
-    if (this._isOpen && this.lastOnEnd < ev.timeStamp - 100) {
-      const shouldClose = ev.composedPath ? !ev.composedPath().includes(this.menuInnerEl) : false;
-
-      if (shouldClose) {
-        ev.preventDefault();
-        ev.stopPropagation();
-        this.close();
-      }
-    }
-  }
-
   onKeydown(ev: KeyboardEvent) {
     if (ev.key === 'Escape') {
-      this.close();
+      this.close(undefined, ESCAPE);
     }
   }
 
@@ -375,8 +361,8 @@ export class Menu implements ComponentInterface, MenuI {
    * it returns `false`.
    */
   @Method()
-  close(animated = true): Promise<boolean> {
-    return this.setOpen(false, animated);
+  close(animated = true, role?: string): Promise<boolean> {
+    return this.setOpen(false, animated, role);
   }
 
   /**
@@ -393,8 +379,8 @@ export class Menu implements ComponentInterface, MenuI {
    * If the operation can't be completed successfully, it returns `false`.
    */
   @Method()
-  setOpen(shouldOpen: boolean, animated = true): Promise<boolean> {
-    return menuController._setOpen(this, shouldOpen, animated);
+  setOpen(shouldOpen: boolean, animated = true, role?: string): Promise<boolean> {
+    return menuController._setOpen(this, shouldOpen, animated, role);
   }
 
   private trapKeyboardFocus(ev: Event, doc: Document) {
@@ -438,13 +424,13 @@ export class Menu implements ComponentInterface, MenuI {
     }
   }
 
-  async _setOpen(shouldOpen: boolean, animated = true): Promise<boolean> {
+  async _setOpen(shouldOpen: boolean, animated = true, role?: string): Promise<boolean> {
     // If the menu is disabled or it is currently being animated, let's do nothing
     if (!this._isActive() || this.isAnimating || shouldOpen === this._isOpen) {
       return false;
     }
 
-    this.beforeAnimation(shouldOpen);
+    this.beforeAnimation(shouldOpen, role);
 
     await this.loadAnimation();
     await this.startAnimation(shouldOpen, animated);
@@ -459,7 +445,7 @@ export class Menu implements ComponentInterface, MenuI {
       return false;
     }
 
-    this.afterAnimation(shouldOpen);
+    this.afterAnimation(shouldOpen, role);
 
     return true;
   }
@@ -542,7 +528,7 @@ export class Menu implements ComponentInterface, MenuI {
   }
 
   private onWillStart(): Promise<void> {
-    this.beforeAnimation(!this._isOpen);
+    this.beforeAnimation(!this._isOpen, GESTURE);
     return this.loadAnimation();
   }
 
@@ -624,11 +610,11 @@ export class Menu implements ComponentInterface, MenuI {
 
     this.animation
       .easing('cubic-bezier(0.4, 0.0, 0.6, 1)')
-      .onFinish(() => this.afterAnimation(shouldOpen), { oneTimeCallback: true })
+      .onFinish(() => this.afterAnimation(shouldOpen, GESTURE), { oneTimeCallback: true })
       .progressEnd(playTo ? 1 : 0, this._isOpen ? 1 - newStepValue : newStepValue, 300);
   }
 
-  private beforeAnimation(shouldOpen: boolean) {
+  private beforeAnimation(shouldOpen: boolean, role?: string) {
     assert(!this.isAnimating, '_before() should not be called while animating');
 
     // this places the menu into the correct location before it animates in
@@ -671,11 +657,11 @@ export class Menu implements ComponentInterface, MenuI {
     if (shouldOpen) {
       this.ionWillOpen.emit();
     } else {
-      this.ionWillClose.emit();
+      this.ionWillClose.emit({ role });
     }
   }
 
-  private afterAnimation(isOpen: boolean) {
+  private afterAnimation(isOpen: boolean, role?: string) {
     // keep opening/closing the menu disabled for a touch more yet
     // only add listeners/css if it's enabled and isOpen
     // and only remove listeners/css if it's not open
@@ -731,13 +717,26 @@ export class Menu implements ComponentInterface, MenuI {
       }
 
       // emit close event
-      this.ionDidClose.emit();
+      this.ionDidClose.emit({ role });
 
       // undo focus trapping so multiple menus don't collide
       document.removeEventListener('focus', this.handleFocus, true);
     }
   }
 
+  private onBackdropTap = (ev: any) => {
+    // TODO(FW-2832): type (CustomEvent triggers errors which should be sorted)
+    if (this._isOpen && this.lastOnEnd < ev.timeStamp - 100) {
+      const shouldClose = ev.composedPath ? !ev.composedPath().includes(this.menuInnerEl) : false;
+
+      if (shouldClose) {
+        ev.preventDefault();
+        ev.stopPropagation();
+        this.close(undefined, BACKDROP);
+      }
+    }
+  };
+
   private updateState() {
     const isActive = this._isActive();
     if (this.gesture) {
@@ -767,7 +766,7 @@ export class Menu implements ComponentInterface, MenuI {
        * If the menu is disabled then we should
        * forcibly close the menu even if it is open.
        */
-      this.afterAnimation(false);
+      this.afterAnimation(false, GESTURE);
     }
   }
 
@@ -793,18 +792,13 @@ export class Menu implements ComponentInterface, MenuI {
           'menu-pane-visible': isPaneVisible,
           'split-pane-side': hostContext('ion-split-pane', el),
         }}
+        onIonBackdropTap={this.onBackdropTap}
       >
         <div class="menu-inner" part="container" ref={(el) => (this.menuInnerEl = el)}>
           <slot></slot>
         </div>
 
-        <ion-backdrop
-          ref={(el) => (this.backdropEl = el)}
-          class="menu-backdrop"
-          tappable={false}
-          stopPropagation={false}
-          part="backdrop"
-        />
+        <ion-backdrop ref={(el) => (this.backdropEl = el)} class="menu-backdrop" tappable={true} part="backdrop" />
       </Host>
     );
   }

core/src/components/menu/test/basic/index.html

@@ -52,6 +52,9 @@
         <ion-content>
           <ion-list>
             <ion-button id="start-menu-button">Button</ion-button>
+            <ion-menu-toggle>
+              <ion-button>Close menu</ion-button>
+            </ion-menu-toggle>
             <ion-item>Menu Item</ion-item>
             <ion-item>Menu Item</ion-item>
             <ion-item>Menu Item</ion-item>
@@ -125,6 +128,19 @@
     </ion-app>
 
     <script>
+      window.addEventListener('ionWillOpen', function (e) {
+        console.log('ionWillOpen', e);
+      });
+      window.addEventListener('ionDidOpen', function (e) {
+        console.log('ionDidOpen', e);
+      });
+      window.addEventListener('ionWillClose', function (e) {
+        console.log('ionWillClose', e.detail);
+      });
+      window.addEventListener('ionDidClose', function (e) {
+        console.log('ionDidClose', e.detail);
+      });
+
       async function openStart() {
         // Open the menu by menu-id
         await menuController.enable(true, 'start-menu');

core/src/utils/menu-controller/index.ts

@@ -174,7 +174,7 @@ const createMenuController = (): MenuControllerI => {
     }
   };
 
-  const _setOpen = async (menu: MenuI, shouldOpen: boolean, animated: boolean): Promise<boolean> => {
+  const _setOpen = async (menu: MenuI, shouldOpen: boolean, animated: boolean, role: string): Promise<boolean> => {
     if (isAnimatingSync()) {
       return false;
     }
@@ -184,7 +184,7 @@ const createMenuController = (): MenuControllerI => {
         await openedMenu.setOpen(false, false);
       }
     }
-    return menu._setOpen(shouldOpen, animated);
+    return menu._setOpen(shouldOpen, animated, role);
   };
 
   const _createAnimation = (type: string, menuCmp: MenuI) => {

core/src/utils/overlays.ts

@@ -778,6 +778,7 @@ export const safeCall = (handler: any, arg?: any) => {
 };
 
 export const BACKDROP = 'backdrop';
+export const ESCAPE = 'escape';
 export const GESTURE = 'gesture';
 export const OVERLAY_GESTURE_PRIORITY = 39;
 

packages/angular/src/directives/proxies.ts

@@ -1334,6 +1334,8 @@ export class IonMenu {
 }
 
 
+import type { MenuCloseEventDetail as IIonMenuMenuCloseEventDetail } from '@ionic/core';
+
 export declare interface IonMenu extends Components.IonMenu {
   /**
    * Emitted when the menu is about to be opened.
@@ -1342,15 +1344,15 @@ export declare interface IonMenu extends Components.IonMenu {
   /**
    * Emitted when the menu is about to be closed.
    */
-  ionWillClose: EventEmitter<CustomEvent<void>>;
+  ionWillClose: EventEmitter<CustomEvent<IIonMenuMenuCloseEventDetail>>;
   /**
    * Emitted when the menu is open.
    */
   ionDidOpen: EventEmitter<CustomEvent<void>>;
   /**
    * Emitted when the menu is closed.
    */
-  ionDidClose: EventEmitter<CustomEvent<void>>;
+  ionDidClose: EventEmitter<CustomEvent<IIonMenuMenuCloseEventDetail>>;
 }