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

package/types/combobox.d.ts

@@ -2,8 +2,38 @@ import * as _angular_core from '@angular/core';
 import { WritableSignal } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
 import * as i1 from '@angular/aria/private';
-import { ComboboxPattern, ComboboxListboxControls, ComboboxTreeControls } from '@angular/aria/private';
+import { ComboboxPattern, ComboboxDialogPattern, ComboboxListboxControls, ComboboxTreeControls } from '@angular/aria/private';
 
+/**
+ * The container element that wraps a combobox input and popup, and orchestrates its behavior.
+ *
+ * The `ngCombobox` directive is the main entry point for creating a combobox and customizing its
+ * behavior. It coordinates the interactions between the `ngComboboxInput` and the popup, which
+ * is defined by a `ng-template` with the `ngComboboxPopupContainer` directive. If using the
+ * `CdkOverlay`, the `cdkConnectedOverlay` directive takes the place of `ngComboboxPopupContainer`.
+ *
+ * ```html
+ * <div ngCombobox filterMode="highlight">
+ *   <input
+ *     ngComboboxInput
+ *     placeholder="Search for a state..."
+ *     [(value)]="searchString"
+ *   />
+ *
+ *   <ng-template ngComboboxPopupContainer>
+ *     <div ngListbox [(value)]="selectedValue">
+ *       @for (option of filteredOptions(); track option) {
+ *         <div ngOption [value]="option" [label]="option">
+ *           <span>{{option}}</span>
+ *         </div>
+ *       }
+ *     </div>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class Combobox<V> {
     /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
     private readonly _directionality;
@@ -11,35 +41,64 @@ declare class Combobox<V> {
     protected textDirection: _angular_core.Signal<_angular_cdk_bidi.Direction>;
     /** The element that the combobox is attached to. */
     private readonly _elementRef;
+    /** A reference to the combobox element. */
+    readonly element: HTMLElement;
     /** The DeferredContentAware host directive. */
     private readonly _deferredContentAware;
     /** The combobox popup. */
     readonly popup: _angular_core.Signal<ComboboxPopup<V> | undefined>;
-    /** The filter mode for the combobox. */
+    /**
+     * The filter mode for the combobox.
+     * - `manual`: The consumer is responsible for filtering the options.
+     * - `auto-select`: The combobox automatically selects the first matching option.
+     * - `highlight`: The combobox highlights matching text in the options without changing selection.
+     */
     filterMode: _angular_core.InputSignal<"manual" | "auto-select" | "highlight">;
-    /** Whether the combobox is focused. */
-    readonly isFocused: WritableSignal<boolean>;
-    /** Whether the combobox has received focus yet. */
-    private _hasBeenFocused;
     /** Whether the combobox is disabled. */
-    readonly disabled: _angular_core.InputSignal<boolean>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the combobox is read-only. */
-    readonly readonly: _angular_core.InputSignal<boolean>;
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The value of the first matching item in the popup. */
     readonly firstMatch: _angular_core.InputSignal<V | undefined>;
     /** Whether the combobox is expanded. */
     readonly expanded: _angular_core.Signal<boolean>;
+    /** Whether the combobox popup should always be expanded, regardless of user interaction. */
+    readonly alwaysExpanded: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Input element connected to the combobox, if any. */
     readonly inputElement: _angular_core.Signal<HTMLInputElement | undefined>;
     /** The combobox ui pattern. */
     readonly _pattern: ComboboxPattern<any, V>;
     constructor();
+    /** Opens the combobox to the selected item. */
+    open(): void;
+    /** Closes the combobox. */
+    close(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Combobox<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Combobox<any>, "[ngCombobox]", ["ngCombobox"], { "filterMode": { "alias": "filterMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "firstMatch": { "alias": "firstMatch"; "required": false; "isSignal": true; }; }, {}, ["popup"], never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Combobox<any>, "[ngCombobox]", ["ngCombobox"], { "filterMode": { "alias": "filterMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "firstMatch": { "alias": "firstMatch"; "required": false; "isSignal": true; }; "alwaysExpanded": { "alias": "alwaysExpanded"; "required": false; "isSignal": true; }; }, {}, ["popup"], never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
 }
+/**
+ * An input that is part of a combobox. It is responsible for displaying the
+ * current value and handling user input for filtering and selection.
+ *
+ * This directive should be applied to an `<input>` element within an `ngCombobox`
+ * container. It automatically handles keyboard interactions, such as opening the
+ * popup and navigating through the options.
+ *
+ * ```html
+ * <input
+ *   ngComboboxInput
+ *   placeholder="Search..."
+ *   [(value)]="searchString"
+ * />
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class ComboboxInput {
     /** The element that the combobox is attached to. */
     private readonly _elementRef;
+    /** A reference to the input element. */
+    readonly element: HTMLElement;
     /** The combobox that the input belongs to. */
     readonly combobox: Combobox<any>;
     /** The value of the input. */
@@ -48,17 +107,87 @@ declare class ComboboxInput {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComboboxInput, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ComboboxInput, "input[ngComboboxInput]", ["ngComboboxInput"], { "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
 }
+/**
+ * A structural directive that marks the `ng-template` to be used as the popup
+ * for a combobox. This content is conditionally rendered.
+ *
+ * The content of the popup can be a `ngListbox`, `ngTree`, or `role="dialog"`, allowing for
+ * flexible and complex combobox implementations. The consumer is responsible for
+ * implementing the filtering logic based on the `ngComboboxInput`'s value.
+ *
+ * ```html
+ * <ng-template ngComboboxPopupContainer>
+ *   <div ngListbox [(value)]="selectedValue">
+ *     <!-- ... options ... -->
+ *   </div>
+ * </ng-template>
+ * ```
+ *
+ * When using CdkOverlay, this directive can be replaced by `cdkConnectedOverlay`.
+ *
+ * ```html
+ * <ng-template
+ *     [cdkConnectedOverlay]="{origin: inputElement, usePopover: 'inline' matchWidth: true}"
+ *     [cdkConnectedOverlayOpen]="combobox.expanded()">
+ *   <div ngListbox [(value)]="selectedValue">
+ *     <!-- ... options ... -->
+ *   </div>
+ * </ng-template>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class ComboboxPopupContainer {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComboboxPopupContainer, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ComboboxPopupContainer, "ng-template[ngComboboxPopupContainer]", ["ngComboboxPopupContainer"], {}, {}, never, never, true, [{ directive: typeof i1.DeferredContent; inputs: {}; outputs: {}; }]>;
 }
+/**
+ * Identifies an element as a popup for an `ngCombobox`.
+ *
+ * This directive acts as a bridge, allowing the `ngCombobox` to discover and interact
+ * with the underlying control (e.g., `ngListbox`, `ngTree`, or `ngComboboxDialog`) that
+ * manages the options. It's primarily used as a host directive and is responsible for
+ * exposing the popup's control pattern to the parent combobox.
+ *
+ * @developerPreview 21.0
+ */
 declare class ComboboxPopup<V> {
     /** The combobox that the popup belongs to. */
     readonly combobox: Combobox<V> | null;
-    /** The controls the popup exposes to the combobox. */
-    readonly controls: WritableSignal<ComboboxListboxControls<any, V> | ComboboxTreeControls<any, V> | undefined>;
+    /** The popup controls exposed to the combobox. */
+    readonly _controls: WritableSignal<ComboboxDialogPattern | ComboboxListboxControls<any, V> | ComboboxTreeControls<any, V> | undefined>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComboboxPopup<any>, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ComboboxPopup<any>, "[ngComboboxPopup]", ["ngComboboxPopup"], {}, {}, never, never, true, never>;
 }
+/**
+ * Integrates a native `<dialog>` element with the combobox, allowing for
+ * a modal or non-modal popup experience. It handles the opening and closing of the dialog
+ * based on the combobox's expanded state.
+ *
+ * ```html
+ * <ng-template ngComboboxPopupContainer>
+ *   <dialog ngComboboxDialog class="example-dialog">
+ *     <!-- ... dialog content ... -->
+ *   </dialog>
+ * </ng-template>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
+declare class ComboboxDialog {
+    /** The dialog element. */
+    private readonly _elementRef;
+    /** A reference to the dialog element. */
+    readonly element: HTMLElement;
+    /** The combobox that the dialog belongs to. */
+    readonly combobox: Combobox<any>;
+    /** A reference to the parent combobox popup, if one exists. */
+    private readonly _popup;
+    _pattern: ComboboxDialogPattern;
+    constructor();
+    close(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComboboxDialog, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ComboboxDialog, "dialog[ngComboboxDialog]", ["ngComboboxDialog"], {}, {}, never, never, true, [{ directive: typeof ComboboxPopup; inputs: {}; outputs: {}; }]>;
+}
 
-export { Combobox, ComboboxInput, ComboboxPopup, ComboboxPopupContainer };
+export { Combobox, ComboboxDialog, ComboboxInput, ComboboxPopup, ComboboxPopupContainer };

package/types/grid.d.ts

@@ -1,35 +1,76 @@
 import * as _angular_core from '@angular/core';
-import { Signal } from '@angular/core';
+import { Signal, ElementRef } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
 import { GridPattern, GridRowPattern, GridCellPattern, GridCellWidgetPattern } from './_grid-chunk.js';
 
-/** A directive that provides grid-based navigation and selection behavior. */
+/**
+ * The container for a grid. It provides keyboard navigation and focus management for the grid's
+ * rows and cells. It manages the overall behavior of the grid, including focus
+ * wrapping, selection, and disabled states.
+ *
+ * ```html
+ * <table ngGrid [multi]="true" [enableSelection]="true">
+ *   @for (row of gridData; track row) {
+ *     <tr ngGridRow>
+ *       @for (cell of row; track cell) {
+ *         <td ngGridCell [disabled]="cell.disabled">
+ *           {{cell.value}}
+ *         </td>
+ *       }
+ *     </tr>
+ *   }
+ * </table>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class Grid {
     /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The rows that make up the grid. */
     private readonly _rows;
     /** The UI patterns for the rows in the grid. */
     private readonly _rowPatterns;
     /** Text direction. */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
-    /** The host native element. */
-    readonly element: Signal<any>;
     /** Whether selection is enabled for the grid. */
     readonly enableSelection: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the grid is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** Whether to allow disabled items to receive focus. */
+    /**
+     * Whether to allow disabled items to receive focus. When `true`, disabled items are
+     * focusable but not interactive. When `false`, disabled items are skipped during navigation.
+     */
     readonly softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The focus strategy used by the grid. */
+    /**
+     * The focus strategy used by the grid.
+     * - `roving`: Focus is moved to the active cell using `tabindex`.
+     * - `activedescendant`: Focus remains on the grid container, and `aria-activedescendant` is used to indicate the active cell.
+     */
     readonly focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
-    /** The wrapping behavior for keyboard navigation along the row axis. */
+    /**
+     * The wrapping behavior for keyboard navigation along the row axis.
+     * - `continuous`: Navigation wraps from the last row to the first, and vice-versa.
+     * - `loop`: Navigation wraps within the current row.
+     * - `nowrap`: Navigation stops at the first/last item in the row.
+     */
     readonly rowWrap: _angular_core.InputSignal<"continuous" | "loop" | "nowrap">;
-    /** The wrapping behavior for keyboard navigation along the column axis. */
+    /**
+     * The wrapping behavior for keyboard navigation along the column axis.
+     * - `continuous`: Navigation wraps from the last column to the first, and vice-versa.
+     * - `loop`: Navigation wraps within the current column.
+     * - `nowrap`: Navigation stops at the first/last item in the column.
+     */
     readonly colWrap: _angular_core.InputSignal<"continuous" | "loop" | "nowrap">;
     /** Whether multiple cells in the grid can be selected. */
     readonly multi: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The selection strategy used by the grid. */
+    /**
+     * The selection strategy used by the grid.
+     * - `follow`: The focused cell is automatically selected.
+     * - `explicit`: Cells are selected explicitly by the user (e.g., via click or spacebar).
+     */
     readonly selectionMode: _angular_core.InputSignal<"follow" | "explicit">;
     /** Whether enable range selections (with modifier keys or dragging). */
     readonly enableRangeSelection: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -41,10 +82,22 @@ declare class Grid {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Grid, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Grid, "[ngGrid]", ["ngGrid"], { "enableSelection": { "alias": "enableSelection"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "rowWrap": { "alias": "rowWrap"; "required": false; "isSignal": true; }; "colWrap": { "alias": "colWrap"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "enableRangeSelection": { "alias": "enableRangeSelection"; "required": false; "isSignal": true; }; }, {}, ["_rows"], never, true, never>;
 }
-/** A directive that represents a row in a grid. */
+/**
+ * Represents a row within a grid. It is a container for `ngGridCell` directives.
+ *
+ * ```html
+ * <tr ngGridRow>
+ *   <!-- ... cells ... -->
+ * </tr>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class GridRow {
     /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The cells that make up this row. */
     private readonly _cells;
     /** The UI patterns for the cells in this row. */
@@ -52,34 +105,46 @@ declare class GridRow {
     /** The parent grid. */
     private readonly _grid;
     /** The parent grid UI pattern. */
-    readonly grid: Signal<GridPattern>;
-    /** The host native element. */
-    readonly element: Signal<any>;
-    /** The ARIA role for the row. */
-    readonly role: _angular_core.InputSignal<"row" | "rowheader">;
+    readonly _gridPattern: Signal<GridPattern>;
     /** The index of this row within the grid. */
     readonly rowIndex: _angular_core.InputSignal<number | undefined>;
     /** The UI pattern for the grid row. */
     readonly _pattern: GridRowPattern;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridRow, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridRow, "[ngGridRow]", ["ngGridRow"], { "role": { "alias": "role"; "required": false; "isSignal": true; }; "rowIndex": { "alias": "rowIndex"; "required": false; "isSignal": true; }; }, {}, ["_cells"], never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridRow, "[ngGridRow]", ["ngGridRow"], { "rowIndex": { "alias": "rowIndex"; "required": false; "isSignal": true; }; }, {}, ["_cells"], never, true, never>;
 }
-/** A directive that represents a cell in a grid. */
+/**
+ * Represents a cell within a grid row. It is the primary focusable element
+ * within the grid. It can be disabled and can have its selection state managed
+ * through the `selected` input.
+ *
+ * ```html
+ * <td ngGridCell [disabled]="isDisabled" [(selected)]="isSelected">
+ *   Cell Content
+ * </td>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class GridCell {
     /** A reference to the host element. */
     private readonly _elementRef;
-    /** The widget contained within this cell, if any. */
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
+    /** Whether the cell is currently active (focused). */
+    readonly active: Signal<boolean>;
+    /** The widgets contained within this cell, if any. */
     private readonly _widgets;
     /** The UI pattern for the widget in this cell. */
-    private readonly _widgetPattern;
+    private readonly _widgetPatterns;
     /** The parent row. */
     private readonly _row;
+    /** Text direction. */
+    readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     /** A unique identifier for the cell. */
-    private readonly _id;
-    /** The host native element. */
-    readonly element: Signal<any>;
+    readonly id: _angular_core.InputSignal<string>;
     /** The ARIA role for the cell. */
-    readonly role: _angular_core.InputSignal<"gridcell" | "columnheader">;
+    readonly role: _angular_core.InputSignal<"gridcell" | "columnheader" | "rowheader">;
     /** The number of rows the cell should span. */
     readonly rowSpan: _angular_core.InputSignal<number>;
     /** The number of columns the cell should span. */
@@ -94,27 +159,80 @@ declare class GridCell {
     readonly selected: _angular_core.ModelSignal<boolean>;
     /** Whether the cell is selectable. */
     readonly selectable: _angular_core.InputSignal<boolean>;
+    /** Orientation of the widgets in the cell. */
+    readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
+    /** Whether widgets navigation wraps. */
+    readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The tabindex override. */
+    readonly tabindex: _angular_core.InputSignal<number | undefined>;
+    /**
+     * The tabindex value set to the element.
+     * If a focus target exists then return -1. Unless an override.
+     */
+    protected readonly _tabIndex: Signal<number>;
     /** The UI pattern for the grid cell. */
     readonly _pattern: GridCellPattern;
+    constructor();
+    /** Gets the cell widget pattern for a given element. */
+    private _getWidget;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridCell, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridCell, "[ngGridCell]", ["ngGridCell"], { "role": { "alias": "role"; "required": false; "isSignal": true; }; "rowSpan": { "alias": "rowSpan"; "required": false; "isSignal": true; }; "colSpan": { "alias": "colSpan"; "required": false; "isSignal": true; }; "rowIndex": { "alias": "rowIndex"; "required": false; "isSignal": true; }; "colIndex": { "alias": "colIndex"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; }, ["_widgets"], never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridCell, "[ngGridCell]", ["ngGridCell"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; "rowSpan": { "alias": "rowSpan"; "required": false; "isSignal": true; }; "colSpan": { "alias": "colSpan"; "required": false; "isSignal": true; }; "rowIndex": { "alias": "rowIndex"; "required": false; "isSignal": true; }; "colIndex": { "alias": "colIndex"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "tabindex": { "alias": "tabindex"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; }, ["_widgets"], never, true, never>;
 }
-/** A directive that represents a widget inside a grid cell. */
+/**
+ * Represents an interactive element inside a `GridCell`. It allows for pausing grid navigation to
+ * interact with the widget.
+ *
+ * When the user interacts with the widget (e.g., by typing in an input or opening a menu), grid
+ * navigation is temporarily suspended to allow the widget to handle keyboard
+ * events.
+ *
+ * ```html
+ * <td ngGridCell>
+ *   <button ngGridCellWidget>Click Me</button>
+ * </td>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class GridCellWidget {
     /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
+    /** Whether the widget is currently active (focused). */
+    readonly active: Signal<boolean>;
     /** The parent cell. */
     private readonly _cell;
-    /** The host native element. */
-    readonly element: Signal<any>;
-    /** Whether the widget is activated and the grid navigation should be paused. */
-    readonly activate: _angular_core.ModelSignal<boolean>;
+    /** A unique identifier for the widget. */
+    readonly id: _angular_core.InputSignal<string>;
+    /** The type of widget, which determines how it is activated. */
+    readonly widgetType: _angular_core.InputSignal<"simple" | "complex" | "editable">;
+    /** Whether the widget is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The target that will receive focus instead of the widget. */
+    readonly focusTarget: _angular_core.InputSignal<ElementRef<any> | HTMLElement | undefined>;
+    /** Emits when the widget is activated. */
+    readonly onActivate: _angular_core.OutputEmitterRef<KeyboardEvent | FocusEvent | undefined>;
+    /** Emits when the widget is deactivated. */
+    readonly onDeactivate: _angular_core.OutputEmitterRef<KeyboardEvent | FocusEvent | undefined>;
+    /** The tabindex override. */
+    readonly tabindex: _angular_core.InputSignal<number | undefined>;
+    /**
+     * The tabindex value set to the element.
+     * If a focus target exists then return -1. Unless an override.
+     */
+    protected readonly _tabIndex: Signal<number>;
     /** The UI pattern for the grid cell widget. */
     readonly _pattern: GridCellWidgetPattern;
-    /** Focuses the widget. */
-    focus(): void;
+    /** Whether the widget is activated. */
+    get isActivated(): Signal<boolean>;
+    constructor();
+    /** Activates the widget. */
+    activate(): void;
+    /** Deactivates the widget. */
+    deactivate(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GridCellWidget, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridCellWidget, "[ngGridCellWidget]", ["ngGridCellWidget"], { "activate": { "alias": "activate"; "required": false; "isSignal": true; }; }, { "activate": "activateChange"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<GridCellWidget, "[ngGridCellWidget]", ["ngGridCellWidget"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "widgetType": { "alias": "widgetType"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "focusTarget": { "alias": "focusTarget"; "required": false; "isSignal": true; }; "tabindex": { "alias": "tabindex"; "required": false; "isSignal": true; }; }, { "onActivate": "onActivate"; "onDeactivate": "onDeactivate"; }, never, never, true, never>;
 }
 
 export { Grid, GridCell, GridCellWidget, GridRow };

package/types/listbox.d.ts

@@ -4,28 +4,33 @@ import { OptionPattern, ListboxPattern } from '@angular/aria/private';
 import { ComboboxPopup } from './combobox.js';
 
 /**
- * A listbox container.
+ * Represents a container used to display a list of items for a user to select from.
  *
- * Listboxes are used to display a list of items for a user to select from. The Listbox is meant
- * to be used in conjunction with Option as follows:
+ * The `ngListbox` is meant to be used in conjunction with `ngOption` directives to create a
+ * selectable list. It supports single and multiple selection modes, as well as various focus and
+ * orientation strategies.
  *
  * ```html
- * <ul ngListbox>
- *   <li [value]="1" ngOption>Item 1</li>
- *   <li [value]="2" ngOption>Item 2</li>
- *   <li [value]="3" ngOption>Item 3</li>
+ * <ul ngListbox [(value)]="selectedItems" [multi]="true" orientation="vertical">
+ *   @for (item of items; track item.id) {
+ *     <li ngOption [value]="item.id" [label]="item.name" [disabled]="item.disabled">
+ *       {{item.name}}
+ *     </li>
+ *   }
  * </ul>
  * ```
+ *
+ * @developerPreview 21.0
  */
 declare class Listbox<V> {
     /** A unique identifier for the listbox. */
-    private readonly _generatedId;
-    /** A unique identifier for the listbox. */
-    protected id: _angular_core.Signal<string>;
+    readonly id: _angular_core.InputSignal<string>;
     /** A reference to the parent combobox popup, if one exists. */
     private readonly _popup;
-    /** A reference to the listbox 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). */
     private readonly _directionality;
     /** The Options nested inside of the Listbox. */
@@ -40,11 +45,22 @@ declare class Listbox<V> {
     multi: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether focus should wrap when navigating. */
     wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** Whether to allow disabled items in the list to receive focus. */
+    /**
+     * Whether to allow disabled items to receive focus. When `true`, disabled items are
+     * focusable but not interactive. When `false`, disabled items are skipped during navigation.
+     */
     softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The focus strategy used by the list. */
+    /**
+     * The focus strategy used by the list.
+     * - `roving`: Focus is moved to the active item using `tabindex`.
+     * - `activedescendant`: Focus remains on the listbox container, and `aria-activedescendant` is used to indicate the active item.
+     */
     focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
-    /** The selection strategy used by the list. */
+    /**
+     * The selection strategy used by the list.
+     * - `follow`: The focused item is automatically selected.
+     * - `explicit`: Items are selected explicitly by the user (e.g., via click or spacebar).
+     */
     selectionMode: _angular_core.InputSignal<"follow" | "explicit">;
     /** The amount of time before the typeahead search is reset. */
     typeaheadDelay: _angular_core.InputSignal<number>;
@@ -52,34 +68,50 @@ declare class Listbox<V> {
     disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the listbox is readonly. */
     readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The values of the current selected items. */
-    value: _angular_core.ModelSignal<V[]>;
+    /** The values of the currently selected items. */
+    values: _angular_core.ModelSignal<V[]>;
     /** The Listbox UIPattern. */
     readonly _pattern: ListboxPattern<V>;
     /** Whether the listbox has received focus yet. */
     private _hasFocused;
     constructor();
-    onFocus(): void;
+    _onFocus(): void;
     scrollActiveItemIntoView(options?: ScrollIntoViewOptions): void;
+    /** Navigates to the first item in the listbox. */
+    gotoFirst(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Listbox<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Listbox<any>, "[ngListbox]", ["ngListbox"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, ["_options"], never, true, [{ directive: typeof ComboboxPopup; inputs: {}; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Listbox<any>, "[ngListbox]", ["ngListbox"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": false; "isSignal": true; }; }, { "values": "valuesChange"; }, ["_options"], never, true, [{ directive: typeof ComboboxPopup; inputs: {}; outputs: {}; }]>;
 }
-/** A selectable option in a Listbox. */
+/**
+ * A selectable option in an `ngListbox`.
+ *
+ * This directive should be applied to an element (e.g., `<li>`, `<div>`) within an
+ * `ngListbox`. The `value` input is used to identify the option, and the `label` input provides
+ * the accessible name for the option.
+ *
+ * ```html
+ * <li ngOption value="item-id" label="Item Name">
+ *   Item Name
+ * </li>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class Option<V> {
-    /** A reference to the option element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
+    /** Whether the option is currently active (focused). */
+    active: _angular_core.Signal<boolean>;
     /** The parent Listbox. */
     private readonly _listbox;
     /** A unique identifier for the option. */
-    private readonly _generatedId;
-    /** A unique identifier for the option. */
-    protected id: _angular_core.Signal<string>;
+    readonly id: _angular_core.InputSignal<string>;
     /** The text used by the typeahead search. */
-    protected searchTerm: _angular_core.Signal<any>;
+    protected searchTerm: _angular_core.Signal<string>;
     /** The parent Listbox UIPattern. */
-    protected listbox: _angular_core.Signal<ListboxPattern<any>>;
-    /** A reference to the option element to be focused on navigation. */
-    protected element: _angular_core.Signal<any>;
+    private readonly _listboxPattern;
     /** The value of the option. */
     value: _angular_core.InputSignal<V>;
     /** Whether an item is disabled. */
@@ -91,7 +123,7 @@ declare class Option<V> {
     /** The Option UIPattern. */
     readonly _pattern: OptionPattern<V>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Option<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Option<any>, "[ngOption]", ["ngOption"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Option<any>, "[ngOption]", ["ngOption"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { Listbox, Option };