fix(aria/menu): public api cleanup (angular#32189)

* fix(aria/menu): remove onSubmit from MenuTrigger

* refactor(aria/menu): rename submenu to menu for MenuTrigger

* fix(aria/menu): defer rendering of menu content

* refactor(aria/menu): remove parent input

* refactor(aria/menu): remove submenu input

* refactor(aria/menu): rename onSubmit to onSelect

* refactor(aria/menu): remove onSelect from MenuTrigger

Author: wagnermaciel

src/aria/menu/BUILD.bazel

@@ -11,6 +11,7 @@ ng_project(
     ),
     deps = [
         "//:node_modules/@angular/core",
+        "//src/aria/deferred-content",
         "//src/aria/private",
         "//src/cdk/a11y",
         "//src/cdk/bidi",

src/aria/menu/index.ts

@@ -6,4 +6,4 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export {Menu, MenuBar, MenuItem, MenuTrigger} from './menu';
+export {Menu, MenuBar, MenuContent, MenuItem, MenuTrigger} from './menu';

src/aria/menu/menu.spec.ts

@@ -151,49 +151,49 @@ describe('Standalone Menu Pattern', () => {
 
     it('should select an item on click', () => {
       const banana = getItem('Banana');
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
 
       click(banana!);
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Banana');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Banana');
     });
 
     it('should select an item on enter', () => {
       const banana = getItem('Banana');
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
 
       keydown(document.activeElement!, 'ArrowDown'); // Move focus to Banana
       expect(document.activeElement).toBe(banana);
 
       keydown(banana!, 'Enter');
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Banana');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Banana');
     });
 
     it('should select an item on space', () => {
       const banana = getItem('Banana');
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
 
       keydown(document.activeElement!, 'ArrowDown'); // Move focus to Banana
       expect(document.activeElement).toBe(banana);
 
       keydown(banana!, ' ');
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Banana');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Banana');
     });
 
     it('should not select a disabled item', () => {
       const cherry = getItem('Cherry');
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
 
       click(cherry!);
-      expect(fixture.componentInstance.onSubmit).not.toHaveBeenCalled();
+      expect(fixture.componentInstance.onSelect).not.toHaveBeenCalled();
 
       keydown(document.activeElement!, 'End');
       expect(document.activeElement).toBe(cherry);
 
       keydown(cherry!, 'Enter');
-      expect(fixture.componentInstance.onSubmit).not.toHaveBeenCalled();
+      expect(fixture.componentInstance.onSelect).not.toHaveBeenCalled();
 
       keydown(cherry!, ' ');
-      expect(fixture.componentInstance.onSubmit).not.toHaveBeenCalled();
+      expect(fixture.componentInstance.onSelect).not.toHaveBeenCalled();
     });
   });
 
@@ -316,18 +316,18 @@ describe('Standalone Menu Pattern', () => {
     }));
 
     it('should close on selecting an item on click', () => {
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
       click(getItem('Berries')!); // open submenu
       expect(isSubmenuExpanded()).toBe(true);
 
       click(getItem('Blueberry')!);
 
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Blueberry');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Blueberry');
       expect(isSubmenuExpanded()).toBe(false);
     });
 
     it('should close on selecting an item on enter', () => {
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
       const apple = getItem('Apple');
       const banana = getItem('Banana');
       const berries = getItem('Berries');
@@ -341,12 +341,12 @@ describe('Standalone Menu Pattern', () => {
 
       keydown(blueberry!, 'Enter');
 
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Blueberry');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Blueberry');
       expect(isSubmenuExpanded()).toBe(false);
     });
 
     it('should close on selecting an item on space', () => {
-      spyOn(fixture.componentInstance, 'onSubmit');
+      spyOn(fixture.componentInstance, 'onSelect');
       const apple = getItem('Apple');
       const banana = getItem('Banana');
       const berries = getItem('Berries');
@@ -360,7 +360,7 @@ describe('Standalone Menu Pattern', () => {
 
       keydown(blueberry!, ' ');
 
-      expect(fixture.componentInstance.onSubmit).toHaveBeenCalledWith('Blueberry');
+      expect(fixture.componentInstance.onSelect).toHaveBeenCalledWith('Blueberry');
       expect(isSubmenuExpanded()).toBe(false);
     });
 
@@ -877,12 +877,12 @@ describe('Menu Bar Pattern', () => {
 
 @Component({
   template: `
-<div ngMenu (onSubmit)="onSubmit($event)">
+<div ngMenu (onSelect)="onSelect($event)">
   <div ngMenuItem value='Apple' searchTerm='Apple'>Apple</div>
   <div ngMenuItem value='Banana' searchTerm='Banana'>Banana</div>
-  <div ngMenuItem value='Berries' searchTerm='Berries' #berriesItem="ngMenuItem" [submenu]="berriesMenu">Berries</div>
+  <div ngMenuItem value='Berries' searchTerm='Berries' [submenu]="berriesMenu">Berries</div>
 
-  <div ngMenu [parent]="berriesItem" #berriesMenu="ngMenu">
+  <div ngMenu #berriesMenu="ngMenu">
     <div ngMenuItem value='Blueberry' searchTerm='Blueberry'>Blueberry</div>
     <div ngMenuItem value='Blackberry' searchTerm='Blackberry'>Blackberry</div>
     <div ngMenuItem value='Strawberry' searchTerm='Strawberry'>Strawberry</div>
@@ -894,19 +894,19 @@ describe('Menu Bar Pattern', () => {
   imports: [Menu, MenuItem],
 })
 class StandaloneMenuExample {
-  onSubmit(value: string) {}
+  onSelect(value: string) {}
 }
 
 @Component({
   template: `
-<button ngMenuTrigger #menuTrigger="ngMenuTrigger" [submenu]="menu">Open menu</button>
+<button ngMenuTrigger [menu]="menu">Open menu</button>
 
-<div ngMenu #menu="ngMenu" [parent]="menuTrigger">
+<div ngMenu #menu="ngMenu">
   <div ngMenuItem value='Apple' searchTerm='Apple'>Apple</div>
   <div ngMenuItem value='Banana' searchTerm='Banana'>Banana</div>
-  <div ngMenuItem value='Berries' searchTerm='Berries' #berriesItem="ngMenuItem" [submenu]="berriesMenu">Berries</div>
+  <div ngMenuItem value='Berries' searchTerm='Berries' [submenu]="berriesMenu">Berries</div>
 
-  <div ngMenu [parent]="berriesItem" #berriesMenu="ngMenu">
+  <div ngMenu #berriesMenu="ngMenu">
     <div ngMenuItem value='Blueberry' searchTerm='Blueberry'>Blueberry</div>
     <div ngMenuItem value='Blackberry' searchTerm='Blackberry'>Blackberry</div>
     <div ngMenuItem value='Strawberry' searchTerm='Strawberry'>Strawberry</div>
@@ -923,24 +923,24 @@ class MenuTriggerExample {}
   template: `
 <div ngMenuBar>
   <div ngMenuItem value='File' searchTerm='File'>File</div>
-  <div ngMenuItem value='Edit' searchTerm='Edit' [submenu]="editMenu" #editItem="ngMenuItem">Edit</div>
+  <div ngMenuItem value='Edit' searchTerm='Edit' [submenu]="editMenu">Edit</div>
 
-  <div ngMenu [parent]="editItem" #editMenu="ngMenu">
+  <div ngMenu #editMenu="ngMenu">
     <div ngMenuItem value='Undo' searchTerm='Undo'>Undo</div>
     <div ngMenuItem value='Redo' searchTerm='Redo'>Redo</div>
   </div>
 
-  <div ngMenuItem #viewItem="ngMenuItem" [submenu]="viewMenu" value='View' searchTerm='View'>View</div>
+  <div ngMenuItem [submenu]="viewMenu" value='View' searchTerm='View'>View</div>
 
-  <div ngMenu [parent]="viewItem" #viewMenu="ngMenu">
+  <div ngMenu #viewMenu="ngMenu">
     <div ngMenuItem value='Zoom In' searchTerm='Zoom In'>Zoom In</div>
     <div ngMenuItem value='Zoom Out' searchTerm='Zoom Out'>Zoom Out</div>
     <div ngMenuItem value='Full Screen' searchTerm='Full Screen'>Full Screen</div>
   </div>
 
-  <div ngMenuItem #helpItem="ngMenuItem" [submenu]="helpMenu" value='Help' searchTerm='Help'>Help</div>
+  <div ngMenuItem [submenu]="helpMenu" value='Help' searchTerm='Help'>Help</div>
 
-  <div ngMenu [parent]="helpItem" #helpMenu="ngMenu">
+  <div ngMenu #helpMenu="ngMenu">
     <div ngMenuItem value='Documentation' searchTerm='Documentation'>Documentation</div>
     <div ngMenuItem value='About' searchTerm='About'>About</div>
   </div>

src/aria/menu/menu.ts

@@ -11,6 +11,7 @@ import {
   computed,
   contentChildren,
   Directive,
+  effect,
   ElementRef,
   inject,
   input,
@@ -32,6 +33,7 @@ import {
 import {_IdGenerator} from '@angular/cdk/a11y';
 import {toSignal} from '@angular/core/rxjs-interop';
 import {Directionality} from '@angular/cdk/bidi';
+import {DeferredContent, DeferredContentAware} from '@angular/aria/deferred-content';
 
 /**
  * A trigger for a menu.
@@ -47,7 +49,7 @@ import {Directionality} from '@angular/cdk/bidi';
     '[attr.tabindex]': '_pattern.tabindex()',
     '[attr.aria-haspopup]': '_pattern.hasPopup()',
     '[attr.aria-expanded]': '_pattern.expanded()',
-    '[attr.aria-controls]': '_pattern.submenu()?.id()',
+    '[attr.aria-controls]': '_pattern.menu()?.id()',
     '(click)': '_pattern.onClick()',
     '(keydown)': '_pattern.onKeydown($event)',
     '(focusout)': '_pattern.onFocusOut($event)',
@@ -62,18 +64,18 @@ export class MenuTrigger<V> {
 
   // TODO(wagnermaciel): See we can remove the need to pass in a submenu.
 
-  /** The submenu associated with the menu trigger. */
-  submenu = input<Menu<V> | undefined>(undefined);
-
-  /** A callback function triggered when a menu item is selected. */
-  onSubmit = output<V>();
+  /** The menu associated with the trigger. */
+  menu = input<Menu<V> | undefined>(undefined);
 
   /** The menu trigger ui pattern instance. */
-  readonly _pattern: MenuTriggerPattern<V> = new MenuTriggerPattern({
-    onSubmit: (value: V) => this.onSubmit.emit(value),
+  _pattern: MenuTriggerPattern<V> = new MenuTriggerPattern({
     element: computed(() => this._elementRef.nativeElement),
-    submenu: computed(() => this.submenu()?._pattern),
+    menu: computed(() => this.menu()?._pattern),
   });
+
+  constructor() {
+    effect(() => this.menu()?.parent.set(this));
+  }
 }
 
 /**
@@ -107,8 +109,17 @@ export class MenuTrigger<V> {
     '(focusin)': '_pattern.onFocusIn()',
     '(click)': '_pattern.onClick($event)',
   },
+  hostDirectives: [
+    {
+      directive: DeferredContentAware,
+      inputs: ['preserveContent'],
+    },
+  ],
 })
 export class Menu<V> {
+  /** The DeferredContentAware host directive. */
+  private readonly _deferredContentAware = inject(DeferredContentAware, {optional: true});
+
   /** The menu items contained in the menu. */
   readonly _allItems = contentChildren<MenuItem<V>>(MenuItem, {descendants: true});
 
@@ -131,9 +142,6 @@ export class Menu<V> {
     initialValue: this._directionality.value,
   });
 
-  /** The submenu associated with the menu. */
-  readonly submenu = input<Menu<V> | undefined>(undefined);
-
   /** The unique ID of the menu. */
   readonly id = input<string>(inject(_IdGenerator).getId('ng-menu-', true));
 
@@ -144,7 +152,7 @@ export class Menu<V> {
   readonly typeaheadDelay = input<number>(0.5); // Picked arbitrarily.
 
   /** A reference to the parent menu item or menu trigger. */
-  readonly parent = input<MenuTrigger<V> | MenuItem<V>>();
+  readonly parent = signal<MenuTrigger<V> | MenuItem<V> | undefined>(undefined);
 
   /** The menu ui pattern instance. */
   readonly _pattern: MenuPattern<V>;
@@ -162,7 +170,7 @@ export class Menu<V> {
   isVisible = computed(() => this._pattern.isVisible());
 
   /** A callback function triggered when a menu item is selected. */
-  onSubmit = output<V>();
+  onSelect = output<V>();
 
   constructor() {
     this._pattern = new MenuPattern({
@@ -175,7 +183,11 @@ export class Menu<V> {
       selectionMode: () => 'explicit',
       activeItem: signal(undefined),
       element: computed(() => this._elementRef.nativeElement),
-      onSubmit: (value: V) => this.onSubmit.emit(value),
+      onSelect: (value: V) => this.onSelect.emit(value),
+    });
+
+    afterRenderEffect(() => {
+      this._deferredContentAware?.contentVisible.set(this._pattern.isVisible());
     });
 
     // TODO(wagnermaciel): This is a redundancy needed for if the user uses display: none to hide
@@ -274,7 +286,7 @@ export class MenuBar<V> {
   readonly items = signal<MenuItemPattern<V>[]>([]);
 
   /** A callback function triggered when a menu item is selected. */
-  onSubmit = output<V>();
+  onSelect = output<V>();
 
   constructor() {
     this._pattern = new MenuBarPattern({
@@ -284,7 +296,7 @@ export class MenuBar<V> {
       focusMode: () => 'roving',
       orientation: () => 'horizontal',
       selectionMode: () => 'explicit',
-      onSubmit: (value: V) => this.onSubmit.emit(value),
+      onSelect: (value: V) => this.onSelect.emit(value),
       activeItem: signal(undefined),
       element: computed(() => this._elementRef.nativeElement),
     });
@@ -363,4 +375,16 @@ export class MenuItem<V> {
     parent: computed(() => this.parent?._pattern),
     submenu: computed(() => this.submenu()?._pattern),
   });
+
+  constructor() {
+    effect(() => this.submenu()?.parent.set(this));
+  }
 }
+
+/** Defers the rendering of the menu content. */
+@Directive({
+  selector: 'ng-template[ngMenuContent]',
+  exportAs: 'ngMenuContent',
+  hostDirectives: [DeferredContent],
+})
+export class MenuContent {}