fix(aria/menu): make MenuItem value optional (#33715)

Author: ok7sai

goldens/aria/menu/index.api.md

@@ -21,7 +21,7 @@ export class Menu<V> implements OnDestroy {
     readonly expansionDelay: _angular_core.InputSignal<number>;
     readonly id: _angular_core.InputSignal<string>;
     readonly _items: Signal<MenuItem<V>[]>;
-    readonly itemSelected: _angular_core.OutputEmitterRef<V>;
+    readonly itemSelected: _angular_core.OutputEmitterRef<V | undefined>;
     // (undocumented)
     ngOnDestroy(): void;
     readonly parent: _angular_core.WritableSignal<MenuItem<V> | MenuTrigger<V> | undefined>;
@@ -50,7 +50,7 @@ export class MenuBar<V> implements OnDestroy {
     readonly element: HTMLElement;
     // (undocumented)
     readonly _items: SignalLike<MenuItem<V>[]>;
-    readonly itemSelected: _angular_core.OutputEmitterRef<V>;
+    readonly itemSelected: _angular_core.OutputEmitterRef<V | undefined>;
     // (undocumented)
     ngOnDestroy(): void;
     readonly _pattern: MenuBarPattern<V>;
@@ -93,9 +93,9 @@ export class MenuItem<V> implements OnInit, OnDestroy {
     readonly role: _angular_core.InputSignal<"menuitem" | "menuitemcheckbox" | "menuitemradio">;
     readonly searchTerm: _angular_core.ModelSignal<string>;
     readonly submenu: _angular_core.InputSignal<Menu<V> | undefined>;
-    readonly value: _angular_core.InputSignal<V>;
+    readonly value: _angular_core.InputSignal<V | undefined>;
     // (undocumented)
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuItem<any>, "[ngMenuItem]", ["ngMenuItem"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "searchTerm": { "alias": "searchTerm"; "required": false; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; "submenu": { "alias": "submenu"; "required": false; "isSignal": true; }; }, { "searchTerm": "searchTermChange"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuItem<any>, "[ngMenuItem]", ["ngMenuItem"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "searchTerm": { "alias": "searchTerm"; "required": false; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; "submenu": { "alias": "submenu"; "required": false; "isSignal": true; }; }, { "searchTerm": "searchTermChange"; }, never, never, true, never>;
     // (undocumented)
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuItem<any>, never>;
 }

goldens/aria/private/index.api.md

@@ -345,9 +345,9 @@ export class ListboxPattern<V> {
 }
 
 // @public
-export interface MenuBarInputs<V> extends ListInputs<MenuItemPattern<V>, V> {
+export interface MenuBarInputs<V> extends ListInputs<MenuItemPattern<V>, V | undefined> {
     items: SignalLike<MenuItemPattern<V>[]>;
-    itemSelected?: (value: V) => void;
+    itemSelected?: (value: V | undefined) => void;
     textDirection: SignalLike<'ltr' | 'rtl'>;
 }
 
@@ -365,7 +365,7 @@ export class MenuBarPattern<V> {
     readonly inputs: MenuBarInputs<V>;
     readonly isFocused: WritableSignalLike<boolean>;
     readonly keydownManager: SignalLike<KeyboardEventManager<KeyboardEvent>>;
-    readonly listBehavior: List<MenuItemPattern<V>, V>;
+    readonly listBehavior: List<MenuItemPattern<V>, V | undefined>;
     next(): void;
     onClick(event: MouseEvent): void;
     onFocusIn(): void;
@@ -380,24 +380,25 @@ export class MenuBarPattern<V> {
 }
 
 // @public
-export interface MenuInputs<V> extends Omit<ListInputs<MenuItemPattern<V>, V>, 'value'> {
+export interface MenuInputs<V> extends Omit<ListInputs<MenuItemPattern<V>, V | undefined>, 'value'> {
     expansionDelay: SignalLike<number>;
     id: SignalLike<string>;
     items: SignalLike<MenuItemPattern<V>[]>;
-    itemSelected?: (value: V) => void;
+    itemSelected?: (value: V | undefined) => void;
     parent: SignalLike<MenuTriggerPattern<V> | MenuItemPattern<V> | undefined>;
     textDirection: SignalLike<'ltr' | 'rtl'>;
 }
 
 // @public
-export interface MenuItemInputs<V> extends Omit<ListItem<V>, 'index' | 'selectable'> {
+export interface MenuItemInputs<V> extends Omit<ListItem<V>, 'index' | 'selectable' | 'value'> {
     parent: SignalLike<MenuPattern<V> | MenuBarPattern<V> | undefined>;
     role: SignalLike<'menuitem' | 'menuitemradio' | 'menuitemcheckbox'>;
     submenu: SignalLike<MenuPattern<V> | undefined>;
+    value?: SignalLike<V | undefined>;
 }
 
 // @public
-export class MenuItemPattern<V> implements ListItem<V> {
+export class MenuItemPattern<V> implements ListItem<V | undefined> {
     constructor(inputs: MenuItemInputs<V>);
     readonly active: SignalLike<boolean>;
     close(opts?: {
@@ -424,7 +425,7 @@ export class MenuItemPattern<V> implements ListItem<V> {
     readonly selectable: SignalLike<boolean>;
     readonly submenu: SignalLike<MenuPattern<V> | undefined>;
     readonly tabIndex: SignalLike<-1 | 0>;
-    readonly value: SignalLike<V>;
+    readonly value: SignalLike<V | undefined>;
 }
 
 // @public
@@ -449,7 +450,7 @@ export class MenuPattern<V> {
     readonly isFocused: WritableSignalLike<boolean>;
     readonly keydownManager: SignalLike<KeyboardEventManager<KeyboardEvent>>;
     last(): void;
-    readonly listBehavior: List<MenuItemPattern<V>, V>;
+    readonly listBehavior: List<MenuItemPattern<V>, V | undefined>;
     next(): void;
     onClick(event: MouseEvent): void;
     onFocusIn(): void;

src/aria/menu/menu-bar.ts

@@ -106,7 +106,7 @@ export class MenuBar<V> implements OnDestroy {
   private readonly _itemPatterns = computed(() => this._items().map(i => i._pattern));
 
   /** A callback function triggered when a menu item is selected. */
-  readonly itemSelected = output<V>();
+  readonly itemSelected = output<V | undefined>();
 
   constructor() {
     this._pattern = new MenuBarPattern({
@@ -116,7 +116,7 @@ export class MenuBar<V> implements OnDestroy {
       focusMode: () => 'roving',
       orientation: () => 'horizontal',
       selectionMode: () => 'explicit',
-      itemSelected: (value: V) => this.itemSelected.emit(value),
+      itemSelected: (value: V | undefined) => this.itemSelected.emit(value),
       activeItem: signal(undefined),
       element: computed(() => this._elementRef.nativeElement),
     });

src/aria/menu/menu-item.ts

@@ -65,7 +65,7 @@ export class MenuItem<V> implements OnInit, OnDestroy {
   readonly id = input(inject(_IdGenerator).getId('ng-menu-item-', true));
 
   /** The value of the menu item. */
-  readonly value = input.required<V>();
+  readonly value = input<V | undefined>(undefined);
 
   /** Whether the menu item is disabled. */
   readonly disabled = input<boolean>(false);

src/aria/menu/menu.spec.ts

@@ -579,6 +579,34 @@ describe('Standalone Menu Pattern', () => {
       expect(consoleSpy).toHaveBeenCalledWith("Duplicate value 'item0' detected inside ngMenu.");
     });
 
+    it('should not warn when items inside ngMenu have no value', () => {
+      TestBed.resetTestingModule();
+      TestBed.configureTestingModule({
+        imports: [MenuWithOptionalValues],
+      });
+      const optionalValuesFixture = TestBed.createComponent(MenuWithOptionalValues);
+      optionalValuesFixture.detectChanges();
+
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should emit undefined on itemSelected when selecting an item without a value', async () => {
+      TestBed.resetTestingModule();
+      TestBed.configureTestingModule({
+        imports: [MenuWithOptionalValues],
+      });
+      const optionalValuesFixture = TestBed.createComponent(MenuWithOptionalValues);
+      optionalValuesFixture.detectChanges();
+      const instance = optionalValuesFixture.componentInstance;
+      spyOn(instance, 'itemSelected');
+
+      const items = optionalValuesFixture.debugElement.queryAll(By.directive(MenuItem));
+      const firstItem = items[0].nativeElement as HTMLElement;
+      firstItem.click();
+
+      expect(instance.itemSelected).toHaveBeenCalledWith(undefined);
+    });
+
     it('should warn when ngMenuItem is outside ngMenu or ngMenuBar', () => {
       TestBed.resetTestingModule();
       TestBed.configureTestingModule({
@@ -1372,6 +1400,20 @@ class ShuffledMenuBarExample {
 })
 class MenuWithDuplicateValues {}
 
+@Component({
+  template: `
+    <div ngMenu (itemSelected)="itemSelected($event)">
+      <div ngMenuItem>Item 0</div>
+      <div ngMenuItem>Item 1</div>
+    </div>
+  `,
+  imports: [Menu, MenuItem],
+  changeDetection: ChangeDetectionStrategy.Eager,
+})
+class MenuWithOptionalValues {
+  itemSelected(value: string | undefined) {}
+}
+
 @Component({
   template: `
     <div ngMenuItem value="item0">Item 0</div>

src/aria/menu/menu.ts

@@ -144,7 +144,7 @@ export class Menu<V> implements OnDestroy {
   readonly tabIndex = computed(() => this._pattern.tabIndex());
 
   /** A callback function triggered when a menu item is selected. */
-  readonly itemSelected = output<V>();
+  readonly itemSelected = output<V | undefined>();
 
   /** The delay in milliseconds before expanding sub-menus on hover. */
   readonly expansionDelay = input<number>(100); // Arbitrarily chosen.
@@ -160,7 +160,7 @@ export class Menu<V> implements OnDestroy {
       selectionMode: () => 'explicit',
       activeItem: signal(undefined),
       element: computed(() => this._elementRef.nativeElement),
-      itemSelected: (value: V) => this.itemSelected.emit(value),
+      itemSelected: (value: V | undefined) => this.itemSelected.emit(value),
     });
 
     afterRenderEffect({

src/aria/private/menu/menu.spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {signal, WritableSignalLike} from '../behaviors/signal-like/signal-like';
+import {signal, SignalLike, WritableSignalLike} from '../behaviors/signal-like/signal-like';
 import {MenuPattern, MenuBarPattern, MenuItemPattern, MenuTriggerPattern} from './menu';
 import {createKeyboardEvent} from '@angular/cdk/testing/private';
 import {ModifierKeys} from '@angular/cdk/testing';
@@ -1011,4 +1011,98 @@ describe('Menu Bar Pattern', () => {
       });
     });
   });
+
+  describe('MenuItemPattern with optional value', () => {
+    it('should default value to undefined when omitted', () => {
+      const item = new MenuItemPattern({
+        id: signal('item-1'),
+        disabled: signal(false),
+        searchTerm: signal('Item'),
+        parent: signal(undefined),
+        element: signal(document.createElement('div')),
+        submenu: signal(undefined),
+        role: signal('menuitem'),
+      });
+
+      expect(item.value()).toBeUndefined();
+    });
+
+    function createTestMenu(items: SignalLike<MenuItemPattern<any>[]>) {
+      return new MenuPattern({
+        id: signal('menu-1'),
+        items,
+        parent: signal(undefined),
+        textDirection: signal('ltr'),
+        expansionDelay: signal(100),
+        disabled: signal(false),
+        activeItem: signal(undefined),
+        typeaheadDelay: signal(500),
+        wrap: signal(true),
+        softDisabled: signal(true),
+        multi: signal(false),
+        focusMode: signal('activedescendant'),
+        orientation: signal('vertical'),
+        selectionMode: signal('explicit'),
+        element: signal(document.createElement('div')),
+      });
+    }
+
+    it('should not report duplicate violations for items without a value', () => {
+      const items = signal<MenuItemPattern<any>[]>([]);
+      const menu = createTestMenu(items);
+
+      items.set([
+        new MenuItemPattern({
+          id: signal('item-1'),
+          disabled: signal(false),
+          searchTerm: signal('Item 1'),
+          parent: signal(menu),
+          element: signal(document.createElement('div')),
+          submenu: signal(undefined),
+          role: signal('menuitem'),
+        }),
+        new MenuItemPattern({
+          id: signal('item-2'),
+          disabled: signal(false),
+          searchTerm: signal('Item 2'),
+          parent: signal(menu),
+          element: signal(document.createElement('div')),
+          submenu: signal(undefined),
+          role: signal('menuitem'),
+        }),
+      ]);
+
+      expect(menu.validate()).toEqual([]);
+    });
+
+    it('should report duplicate violations for items with the same defined value', () => {
+      const items = signal<MenuItemPattern<any>[]>([]);
+      const menu = createTestMenu(items);
+
+      items.set([
+        new MenuItemPattern({
+          id: signal('item-1'),
+          value: signal('copy'),
+          disabled: signal(false),
+          searchTerm: signal('Copy'),
+          parent: signal(menu),
+          element: signal(document.createElement('div')),
+          submenu: signal(undefined),
+          role: signal('menuitem'),
+        }),
+        new MenuItemPattern({
+          id: signal('item-2'),
+          value: signal('copy'),
+          disabled: signal(false),
+          searchTerm: signal('Copy Again'),
+          parent: signal(menu),
+          element: signal(document.createElement('div')),
+          submenu: signal(undefined),
+          role: signal('menuitem'),
+        }),
+      ]);
+
+      expect(menu.validate()).toEqual(["Duplicate value 'copy' detected inside ngMenu."]);
+    });
+  });
 });