@angular/aria 21.0.0-rc.1 → 21.0.0-rc.3

package/types/menu.d.ts

@@ -2,48 +2,76 @@ import * as _angular_core from '@angular/core';
 import { Signal } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
 import * as i1 from '@angular/aria/private';
-import { MenuTriggerPattern, MenuPattern, MenuItemPattern, SignalLike, MenuBarPattern } from '@angular/aria/private';
+import { MenuTriggerPattern, MenuPattern, SignalLike, MenuBarPattern, MenuItemPattern } from '@angular/aria/private';
 
 /**
  * A trigger for a menu.
  *
- * The menu trigger is used to open and close menus, and can be placed on menu items to connect
- * sub-menus.
+ * The `ngMenuTrigger` directive is used to open and close menus. It can be applied to
+ * any interactive element (e.g., a button) to associate it with a `ngMenu` instance.
+ * It also supports linking to sub-menus when applied to a `ngMenuItem`.
+ *
+ * ```html
+ * <button ngMenuTrigger [menu]="myMenu">Open Menu</button>
+ *
+ * <div ngMenu #myMenu="ngMenu">
+ *   <div ngMenuItem>Item 1</div>
+ *   <div ngMenuItem>Item 2</div>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class MenuTrigger<V> {
-    /** A reference to the menu trigger element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
-    /** A reference to the menu element. */
-    readonly element: HTMLButtonElement;
     /** The menu associated with the trigger. */
     menu: _angular_core.InputSignal<Menu<V> | undefined>;
-    /** Whether the menu item has been focused. */
-    readonly hasBeenFocused: _angular_core.WritableSignal<boolean>;
+    /** Whether the menu is expanded. */
+    readonly expanded: Signal<boolean>;
+    /** Whether the menu trigger has a popup. */
+    readonly hasPopup: Signal<boolean>;
+    /** Whether the menu trigger is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the menu trigger is soft disabled. */
+    readonly softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The menu trigger ui pattern instance. */
     _pattern: MenuTriggerPattern<V>;
     constructor();
-    /** Marks the menu trigger as having been focused. */
-    onFocusIn(): void;
+    /** Opens the menu focusing on the first menu item. */
+    open(): void;
+    /** Closes the menu. */
+    close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuTrigger<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuTrigger<any>, "button[ngMenuTrigger]", ["ngMenuTrigger"], { "menu": { "alias": "menu"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuTrigger<any>, "button[ngMenuTrigger]", ["ngMenuTrigger"], { "menu": { "alias": "menu"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 /**
  * A list of menu items.
  *
- * A menu is used to offer a list of menu item choices to users. Menus can be nested within other
- * menus to create sub-menus.
+ * A `ngMenu` is used to offer a list of menu item choices to users. Menus can be nested
+ * within other menus to create sub-menus. It works in conjunction with `ngMenuTrigger`
+ * and `ngMenuItem` directives.
  *
  * ```html
- * <button ngMenuTrigger menu="menu">Options</button>
+ * <button ngMenuTrigger [menu]="myMenu">Options</button>
  *
- * <div ngMenu #menu="ngMenu">
+ * <div ngMenu #myMenu="ngMenu">
  *   <div ngMenuItem>Star</div>
  *   <div ngMenuItem>Edit</div>
- *   <div ngMenuItem>Delete</div>
+ *   <div ngMenuItem [submenu]="subMenu">More</div>
+ * </div>
+ *
+ * <div ngMenu #subMenu="ngMenu">
+ *   <div ngMenuItem>Sub Item 1</div>
+ *   <div ngMenuItem>Sub Item 2</div>
  * </div>
  * ```
+ *
+ * @developerPreview 21.0
  */
 declare class Menu<V> {
     /** The DeferredContentAware host directive. */
@@ -52,18 +80,20 @@ declare class Menu<V> {
     readonly _allItems: Signal<readonly MenuItem<V>[]>;
     /** The menu items that are direct children of this menu. */
     readonly _items: Signal<MenuItem<V>[]>;
-    /** A reference to the menu element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
-    /** A reference to the menu element. */
+    /** A reference to the host element. */
     readonly element: HTMLElement;
     /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     /** The unique ID of the menu. */
     readonly id: _angular_core.InputSignal<string>;
     /** Whether the menu should wrap its items. */
-    readonly wrap: _angular_core.InputSignal<boolean>;
-    /** The delay in seconds before the typeahead buffer is cleared. */
+    readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The delay in milliseconds before the typeahead buffer is cleared. */
     readonly typeaheadDelay: _angular_core.InputSignal<number>;
+    /** Whether the menu is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** A reference to the parent menu item or menu trigger. */
     readonly parent: _angular_core.WritableSignal<MenuTrigger<V> | MenuItem<V> | undefined>;
     /** The menu ui pattern instance. */
@@ -75,65 +105,97 @@ declare class Menu<V> {
      * sometimes the items array is empty. The bug can be reproduced by switching this to use a
      * computed and then quickly opening and closing menus in the dev app.
      */
-    readonly items: () => MenuItemPattern<V>[];
+    private readonly _itemPatterns;
     /** Whether the menu is visible. */
-    isVisible: Signal<boolean>;
+    readonly visible: Signal<boolean>;
+    /** The tab index of the menu. */
+    readonly tabIndex: Signal<0 | -1>;
     /** A callback function triggered when a menu item is selected. */
     onSelect: _angular_core.OutputEmitterRef<V>;
+    /** The delay in milliseconds before expanding sub-menus on hover. */
+    readonly expansionDelay: _angular_core.InputSignal<number>;
     constructor();
     /** Closes the menu. */
-    close(opts?: {
-        refocus?: boolean;
-    }): void;
-    /** Closes all parent menus. */
-    closeAll(opts?: {
-        refocus?: boolean;
-    }): void;
+    close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Menu<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Menu<any>, "[ngMenu]", ["ngMenu"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; }, { "onSelect": "onSelect"; }, ["_allItems"], never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Menu<any>, "[ngMenu]", ["ngMenu"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "expansionDelay": { "alias": "expansionDelay"; "required": false; "isSignal": true; }; }, { "onSelect": "onSelect"; }, ["_allItems"], never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
 }
 /**
  * A menu bar of menu items.
  *
- * Like the menu, a menubar is used to offer a list of menu item choices to users. However, a
- * menubar is used to display a persistent, top-level,
- * always-visible set of menu item choices.
+ * Like the `ngMenu`, a `ngMenuBar` is used to offer a list of menu item choices to users.
+ * However, a menubar is used to display a persistent, top-level, always-visible set of
+ * menu item choices, typically found at the top of an application window.
+ *
+ * ```html
+ * <div ngMenuBar>
+ *   <button ngMenuTrigger [menu]="fileMenu">File</button>
+ *   <button ngMenuTrigger [menu]="editMenu">Edit</button>
+ * </div>
+ *
+ * <div ngMenu #fileMenu="ngMenu">
+ *   <div ngMenuItem>New</div>
+ *   <div ngMenuItem>Open</div>
+ * </div>
+ *
+ * <div ngMenu #editMenu="ngMenu">
+ *   <div ngMenuItem>Cut</div>
+ *   <div ngMenuItem>Copy</div>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class MenuBar<V> {
     /** The menu items contained in the menubar. */
     readonly _allItems: Signal<readonly MenuItem<V>[]>;
     readonly _items: SignalLike<MenuItem<V>[]>;
-    /** A reference to the menu element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
-    /** A reference to the menubar element. */
+    /** A reference to the host element. */
     readonly element: HTMLElement;
+    /** Whether the menubar is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the menubar is soft disabled. */
+    readonly softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
-    /** The value of the menu. */
-    readonly value: _angular_core.ModelSignal<V[]>;
+    /** The values of the currently selected menu items. */
+    readonly values: _angular_core.ModelSignal<V[]>;
     /** Whether the menu should wrap its items. */
-    readonly wrap: _angular_core.InputSignal<boolean>;
-    /** The delay in seconds before the typeahead buffer is cleared. */
+    readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The delay in milliseconds before the typeahead buffer is cleared. */
     readonly typeaheadDelay: _angular_core.InputSignal<number>;
     /** The menu ui pattern instance. */
     readonly _pattern: MenuBarPattern<V>;
     /** The menu items as a writable signal. */
-    readonly items: _angular_core.WritableSignal<MenuItemPattern<V>[]>;
+    private readonly _itemPatterns;
     /** A callback function triggered when a menu item is selected. */
     onSelect: _angular_core.OutputEmitterRef<V>;
     constructor();
+    /** Closes the menubar. */
+    close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuBar<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuBar<any>, "[ngMenuBar]", ["ngMenuBar"], { "value": { "alias": "value"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "onSelect": "onSelect"; }, ["_allItems"], never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuBar<any>, "[ngMenuBar]", ["ngMenuBar"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; }, { "values": "valuesChange"; "onSelect": "onSelect"; }, ["_allItems"], never, true, never>;
 }
 /**
  * An item in a Menu.
  *
- * Menu items can be used in menus and menubars to represent a choice or action a user can take.
+ * `ngMenuItem` directives can be used in `ngMenu` and `ngMenuBar` to represent a choice
+ * or action a user can take. They can also act as triggers for sub-menus.
+ *
+ * ```html
+ * <div ngMenuItem (onSelect)="doAction()">Action Item</div>
+ *
+ * <div ngMenuItem [submenu]="anotherMenu">Submenu Trigger</div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class MenuItem<V> {
-    /** A reference to the menu item element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
-    /** A reference to the menu element. */
+    /** A reference to the host element. */
     readonly element: HTMLElement;
     /** The unique ID of the menu item. */
     readonly id: _angular_core.InputSignal<string>;
@@ -151,17 +213,39 @@ declare class MenuItem<V> {
     readonly parent: Menu<V> | MenuBar<V> | null;
     /** The submenu associated with the menu item. */
     readonly submenu: _angular_core.InputSignal<Menu<V> | undefined>;
-    /** Whether the menu item has been focused. */
-    readonly hasBeenFocused: _angular_core.WritableSignal<boolean>;
+    /** Whether the menu item is active. */
+    readonly active: Signal<boolean>;
+    /** Whether the menu is expanded. */
+    readonly expanded: Signal<boolean | null>;
+    /** Whether the menu item has a popup. */
+    readonly hasPopup: Signal<boolean>;
     /** The menu item ui pattern instance. */
     readonly _pattern: MenuItemPattern<V>;
     constructor();
-    /** Marks the menu item as having been focused. */
-    onFocusIn(): void;
+    /** Opens the submenu focusing on the first menu item. */
+    open(): void;
+    /** Closes the submenu. */
+    close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuItem<any>, never>;
     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; }; "submenu": { "alias": "submenu"; "required": false; "isSignal": true; }; }, { "searchTerm": "searchTermChange"; }, never, never, true, never>;
 }
-/** Defers the rendering of the menu content. */
+/**
+ * Defers the rendering of the menu content.
+ *
+ * This structural directive should be applied to an `ng-template` within a `ngMenu`
+ * or `ngMenuBar` to lazily render its content only when the menu is opened.
+ *
+ * ```html
+ * <div ngMenu #myMenu="ngMenu">
+ *   <ng-template ngMenuContent>
+ *     <div ngMenuItem>Lazy Item 1</div>
+ *     <div ngMenuItem>Lazy Item 2</div>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class MenuContent {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MenuContent, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MenuContent, "ng-template[ngMenuContent]", ["ngMenuContent"], {}, {}, never, never, true, [{ directive: typeof i1.DeferredContent; inputs: {}; outputs: {}; }]>;