@angular/aria 21.0.0-rc.0 → 21.0.0-rc.2

package/types/accordion.d.ts

@@ -1,88 +1,187 @@
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
 import * as _angular_core from '@angular/core';
 import { WritableSignal } from '@angular/core';
+import * as i1 from '@angular/aria/private';
 import { AccordionTriggerPattern, AccordionPanelPattern, AccordionGroupPattern } from '@angular/aria/private';
-import * as i1 from '@angular/aria/deferred-content';
 
 /**
- * Represents the content panel of an accordion item. It is controlled by an
- * associated `AccordionTrigger`.
+ * The content panel of an accordion item that is conditionally visible.
+ *
+ * This directive is a container for the content that is shown or hidden. It requires
+ * a `panelId` that must match the `panelId` of its corresponding `ngAccordionTrigger`.
+ * The content within the panel should be provided using an `ng-template` with the
+ * `ngAccordionContent` directive so that the content is not rendered on the page until the trigger
+ * is expanded. It applies `role="region"` for accessibility and uses the `inert` attribute to hide
+ * its content from assistive technologies when not visible.
+ *
+ * ```html
+ * <div ngAccordionPanel panelId="unique-id-1">
+ *   <ng-template ngAccordionContent>
+ *     <p>This content is lazily rendered and will be shown when the panel is expanded.</p>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class AccordionPanel {
     /** The DeferredContentAware host directive. */
     private readonly _deferredContentAware;
     /** A global unique identifier for the panel. */
-    private readonly _id;
-    /** A local unique identifier for the panel, used to match with its trigger's value. */
-    value: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string>;
+    /** A local unique identifier for the panel, used to match with its trigger's `panelId`. */
+    readonly panelId: _angular_core.InputSignal<string>;
+    /** Whether the accordion panel is visible. True if the associated trigger is expanded. */
+    readonly visible: _angular_core.Signal<boolean>;
     /** The parent accordion trigger pattern that controls this panel. This is set by AccordionGroup. */
     readonly accordionTrigger: WritableSignal<AccordionTriggerPattern | undefined>;
     /** The UI pattern instance for this panel. */
     readonly _pattern: AccordionPanelPattern;
     constructor();
+    /** Expands this item. */
+    expand(): void;
+    /** Collapses this item. */
+    collapse(): void;
+    /** Toggles the expansion state of this item. */
+    toggle(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionPanel, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionPanel, "[ngAccordionPanel]", ["ngAccordionPanel"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionPanel, "[ngAccordionPanel]", ["ngAccordionPanel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "panelId": { "alias": "panelId"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
 }
 /**
- * Represents the trigger button for an accordion item. It controls the expansion
- * state of an associated `AccordionPanel`.
+ * The trigger that toggles the visibility of its associated `ngAccordionPanel`.
+ *
+ * This directive requires a `panelId` that must match the `panelId` of the `ngAccordionPanel` it
+ * controls. When clicked, it will expand or collapse the panel. It also handles keyboard
+ * interactions for navigation within the `ngAccordionGroup`. It applies `role="button"` and manages
+ * `aria-expanded`, `aria-controls`, and `aria-disabled` attributes for accessibility.
+ * The `disabled` input can be used to disable the trigger.
+ *
+ * ```html
+ * <button ngAccordionTrigger panelId="unique-id-1">
+ *   Accordion Trigger Text
+ * </button>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class AccordionTrigger {
-    /** A global unique identifier for the trigger. */
-    private readonly _id;
     /** A reference to the trigger element. */
     private readonly _elementRef;
+    /** A reference to the trigger element. */
+    readonly element: HTMLElement;
     /** The parent AccordionGroup. */
     private readonly _accordionGroup;
-    /** A local unique identifier for the trigger, used to match with its panel's value. */
-    value: _angular_core.InputSignal<string>;
+    /** A unique identifier for the widget. */
+    readonly id: _angular_core.InputSignal<string>;
+    /** A local unique identifier for the trigger, used to match with its panel's `panelId`. */
+    readonly panelId: _angular_core.InputSignal<string>;
     /** Whether the trigger is disabled. */
-    disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /**
-     * Whether this trigger is completely inaccessible.
-     *
-     * TODO(ok7sai): Consider move this to UI patterns.
-     */
-    readonly hardDisabled: _angular_core.Signal<boolean>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the corresponding panel is expanded. */
+    readonly expanded: _angular_core.ModelSignal<boolean>;
+    /** Whether the trigger is active. */
+    readonly active: _angular_core.Signal<boolean>;
     /** The accordion panel pattern controlled by this trigger. This is set by AccordionGroup. */
-    readonly accordionPanel: WritableSignal<AccordionPanelPattern | undefined>;
+    readonly _accordionPanel: WritableSignal<AccordionPanelPattern | undefined>;
     /** The UI pattern instance for this trigger. */
     readonly _pattern: AccordionTriggerPattern;
+    /** Expands this item. */
+    expand(): void;
+    /** Collapses this item. */
+    collapse(): void;
+    /** Toggles the expansion state of this item. */
+    toggle(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionTrigger, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionTrigger, "[ngAccordionTrigger]", ["ngAccordionTrigger"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionTrigger, "[ngAccordionTrigger]", ["ngAccordionTrigger"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "panelId": { "alias": "panelId"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; }, { "expanded": "expandedChange"; }, never, never, true, never>;
 }
 /**
- * Container for a group of accordion items. It manages the overall state and
+ * A container for a group of accordion items. It manages the overall state and
  * interactions of the accordion, such as keyboard navigation and expansion mode.
+ *
+ * The `ngAccordionGroup` serves as the root of a group of accordion triggers and panels,
+ * coordinating the behavior of the `ngAccordionTrigger` and `ngAccordionPanel` elements within it.
+ * It supports both single and multiple expansion modes.
+ *
+ * ```html
+ * <div ngAccordionGroup [multiExpandable]="true" [(expandedPanels)]="expandedItems">
+ *   <div class="accordion-item">
+ *     <h3>
+ *       <button ngAccordionTrigger panelId="item-1">Item 1</button>
+ *     </h3>
+ *     <div ngAccordionPanel panelId="item-1">
+ *       <ng-template ngAccordionContent>
+ *         <p>Content for Item 1.</p>
+ *       </ng-template>
+ *     </div>
+ *   </div>
+ *   <div class="accordion-item">
+ *     <h3>
+ *       <button ngAccordionTrigger panelId="item-2">Item 2</button>
+ *     </h3>
+ *     <div ngAccordionPanel panelId="item-2">
+ *       <ng-template ngAccordionContent>
+ *         <p>Content for Item 2.</p>
+ *       </ng-template>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class AccordionGroup {
     /** A reference to the group element. */
     private readonly _elementRef;
+    /** A reference to the group element. */
+    readonly element: HTMLElement;
     /** The AccordionTriggers nested inside this group. */
-    protected readonly _triggers: _angular_core.Signal<readonly AccordionTrigger[]>;
+    private readonly _triggers;
+    /** The AccordionTrigger patterns nested inside this group. */
+    private readonly _triggerPatterns;
     /** The AccordionPanels nested inside this group. */
-    protected readonly _panels: _angular_core.Signal<readonly AccordionPanel[]>;
+    private readonly _panels;
     /** The text direction (ltr or rtl). */
     readonly textDirection: WritableSignal<_angular_cdk_bidi.Direction>;
     /** Whether the entire accordion group is disabled. */
-    disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether multiple accordion items can be expanded simultaneously. */
-    multiExpandable: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The values of the current selected/expanded accordions. */
-    value: _angular_core.ModelSignal<string[]>;
-    /** Whether disabled items should be skipped during keyboard navigation. */
-    skipDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly multiExpandable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * 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>;
     /** Whether keyboard navigation should wrap around from the last item to the first, and vice-versa. */
-    wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The UI pattern instance for this accordion group. */
     readonly _pattern: AccordionGroupPattern;
     constructor();
+    /** Expands all accordion panels if multi-expandable. */
+    expandAll(): void;
+    /** Collapses all accordion panels. */
+    collapseAll(): void;
+    /** Gets the trigger pattern for a given element. */
+    private _getItem;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionGroup, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionGroup, "[ngAccordionGroup]", ["ngAccordionGroup"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "multiExpandable": { "alias": "multiExpandable"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "skipDisabled": { "alias": "skipDisabled"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, ["_triggers", "_panels"], never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionGroup, "[ngAccordionGroup]", ["ngAccordionGroup"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "multiExpandable": { "alias": "multiExpandable"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; }, {}, ["_triggers", "_panels"], never, true, never>;
 }
 /**
- * A structural directive that marks the `ng-template` to be used as the content
- * for a `AccordionPanel`. This content can be lazily loaded.
+ * A structural directive that provides a mechanism for lazily rendering the content for an
+ * `ngAccordionPanel`.
+ *
+ * This directive should be applied to an `ng-template` inside an `ngAccordionPanel`.
+ * It allows the content of the panel to be lazily rendered, improving performance
+ * by only creating the content when the panel is first expanded.
+ *
+ * ```html
+ * <div ngAccordionPanel panelId="unique-id-1">
+ *   <ng-template ngAccordionContent>
+ *     <p>This is the content that will be displayed inside the panel.</p>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class AccordionContent {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionContent, never>;

package/types/combobox.d.ts

@@ -1,9 +1,39 @@
 import * as _angular_core from '@angular/core';
 import { WritableSignal } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
-import { ComboboxPattern, ComboboxListboxControls, ComboboxTreeControls } from '@angular/aria/private';
-import * as i1 from '@angular/aria/deferred-content';
+import * as i1 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,68 @@ 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 listbox 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;
+    /** Expands the combobox popup. */
+    expand(): void;
+    /** Collapses the combobox popup. */
+    collapse(): 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 +111,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 };