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

package/types/tabs.d.ts

@@ -1,152 +1,232 @@
-import * as _angular_core from '@angular/core';
-import { Signal, OnInit, OnDestroy } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
+import * as _angular_core from '@angular/core';
+import { OnInit, OnDestroy } from '@angular/core';
 import * as i1 from '@angular/aria/private';
 import { TabPattern, TabPanelPattern, TabListPattern } from '@angular/aria/private';
 
 interface HasElement {
-    element: Signal<HTMLElement>;
+    element: HTMLElement;
 }
 /**
  * A Tabs container.
  *
- * Represents a set of layered sections of content. The Tabs is a container meant to be used with
- * TabList, Tab, and TabPanel as follows:
+ * The `ngTabs` directive represents a set of layered sections of content. It acts as the
+ * overarching container for a tabbed interface, coordinating the behavior of `ngTabList`,
+ * `ngTab`, and `ngTabPanel` directives.
  *
  * ```html
  * <div ngTabs>
- *   <ul ngTabList>
+ *   <ul ngTabList [(selectedTab)]="selectedTabValue">
  *     <li ngTab value="tab1">Tab 1</li>
  *     <li ngTab value="tab2">Tab 2</li>
  *     <li ngTab value="tab3">Tab 3</li>
  *   </ul>
  *
  *   <div ngTabPanel value="tab1">
- *      <ng-template ngTabContent>Tab content 1</ng-template>
+ *      <ng-template ngTabContent>Content for Tab 1</ng-template>
  *   </div>
  *   <div ngTabPanel value="tab2">
- *      <ng-template ngTabContent>Tab content 2</ng-template>
+ *      <ng-template ngTabContent>Content for Tab 2</ng-template>
  *   </div>
  *   <div ngTabPanel value="tab3">
- *      <ng-template ngTabContent>Tab content 3</ng-template>
+ *      <ng-template ngTabContent>Content for Tab 3</ng-template>
  *   </div>
+ * </div>
  * ```
+ *
+ * @developerPreview 21.0
  */
 declare class Tabs {
+    /** A reference to the host element. */
+    private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The TabList nested inside of the container. */
     private readonly _tablist;
     /** The TabPanels nested inside of the container. */
     private readonly _unorderedPanels;
     /** The Tab UIPattern of the child Tabs. */
-    tabs: Signal<TabPattern[] | undefined>;
+    readonly _tabPatterns: _angular_core.Signal<TabPattern[] | undefined>;
     /** The TabPanel UIPattern of the child TabPanels. */
-    unorderedTabpanels: Signal<TabPanelPattern[]>;
-    register(child: TabList | TabPanel): void;
-    deregister(child: TabList | TabPanel): void;
+    readonly _unorderedTabpanelPatterns: _angular_core.Signal<TabPanelPattern[]>;
+    _register(child: TabList | TabPanel): void;
+    _unregister(child: TabList | TabPanel): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Tabs, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tabs, "[ngTabs]", ["ngTabs"], {}, {}, never, never, true, never>;
 }
 /**
  * A TabList container.
  *
- * Controls a list of Tab(s).
+ * The `ngTabList` directive controls a list of `ngTab` elements. It manages keyboard
+ * navigation, selection, and the overall orientation of the tabs. It should be placed
+ * within an `ngTabs` container.
+ *
+ * ```html
+ * <ul ngTabList [(selectedTab)]="mySelectedTab" orientation="horizontal" selectionMode="explicit">
+ *   <li ngTab value="first">First Tab</li>
+ *   <li ngTab value="second">Second Tab</li>
+ * </ul>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class TabList implements OnInit, OnDestroy {
-    /** A reference to the tab list element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The parent Tabs. */
     private readonly _tabs;
     /** The Tabs nested inside of the TabList. */
     private readonly _unorderedTabs;
-    /** The internal tab selection state. */
-    private readonly _selection;
     /** Text direction. */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     /** The Tab UIPatterns of the child Tabs. */
-    readonly tabs: Signal<TabPattern[]>;
+    readonly _tabPatterns: _angular_core.Signal<TabPattern[]>;
     /** Whether the tablist is vertically or horizontally oriented. */
     readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
     /** Whether focus should wrap when navigating. */
     readonly wrap: _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 tablist. */
+    /**
+     * The focus strategy used by the tablist.
+     * - `roving`: Focus is moved to the active tab using `tabindex`.
+     * - `activedescendant`: Focus remains on the tablist container, and `aria-activedescendant` is used to indicate the active tab.
+     */
     readonly focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
-    /** The selection strategy used by the tablist. */
+    /**
+     * The selection strategy used by the tablist.
+     * - `follow`: The focused tab is automatically selected.
+     * - `explicit`: Tabs are selected explicitly by the user (e.g., via click or spacebar).
+     */
     readonly selectionMode: _angular_core.InputSignal<"follow" | "explicit">;
-    /** Whether the tablist is disabled. */
-    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The current selected tab. */
     readonly selectedTab: _angular_core.ModelSignal<string | undefined>;
+    /** Whether the tablist is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The TabList UIPattern. */
     readonly _pattern: TabListPattern;
     /** Whether the tree has received focus yet. */
     private _hasFocused;
     constructor();
-    onFocus(): void;
+    _onFocus(): void;
     ngOnInit(): void;
     ngOnDestroy(): void;
-    register(child: Tab): void;
-    deregister(child: Tab): void;
+    _register(child: Tab): void;
+    _unregister(child: Tab): void;
+    /** Opens the tab panel with the specified value. */
+    open(value: string): boolean;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TabList, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabList, "[ngTabList]", ["ngTabList"], { "orientation": { "alias": "orientation"; "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; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectedTab": { "alias": "selectedTab"; "required": false; "isSignal": true; }; }, { "selectedTab": "selectedTabChange"; }, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabList, "[ngTabList]", ["ngTabList"], { "orientation": { "alias": "orientation"; "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; }; "selectedTab": { "alias": "selectedTab"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "selectedTab": "selectedTabChange"; }, never, never, true, never>;
 }
-/** A selectable tab in a TabList. */
+/**
+ * A selectable tab in a TabList.
+ *
+ * The `ngTab` directive represents an individual tab control within an `ngTabList`. It
+ * requires a `value` that uniquely identifies it and links it to a corresponding `ngTabPanel`.
+ *
+ * ```html
+ * <li ngTab value="myTabId" [disabled]="isTabDisabled">
+ *   My Tab Label
+ * </li>
+ * ```
+ *
+ * @developerPreview 21.0
+ */
 declare class Tab implements HasElement, OnInit, OnDestroy {
-    /** A reference to the tab element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The parent Tabs. */
     private readonly _tabs;
     /** The parent TabList. */
     private readonly _tabList;
-    /** A global unique identifier for the tab. */
-    private readonly _id;
-    /** The host native element. */
-    readonly element: Signal<any>;
+    /** A unique identifier for the widget. */
+    readonly id: _angular_core.InputSignal<string>;
     /** The parent TabList UIPattern. */
-    readonly tablist: Signal<TabListPattern>;
+    private readonly _tablistPattern;
     /** The TabPanel UIPattern associated with the tab */
-    readonly tabpanel: Signal<TabPanelPattern | undefined>;
+    private readonly _tabpanelPattern;
     /** Whether a tab is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** A local unique identifier for the tab. */
+    /** The remote tabpanel unique identifier. */
     readonly value: _angular_core.InputSignal<string>;
+    /** Whether the tab is active. */
+    readonly active: _angular_core.Signal<boolean>;
+    /** Whether the tab is selected. */
+    readonly selected: _angular_core.Signal<boolean>;
     /** The Tab UIPattern. */
     readonly _pattern: TabPattern;
+    /** Opens this tab panel. */
+    open(): void;
     ngOnInit(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Tab, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tab, "[ngTab]", ["ngTab"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tab, "[ngTab]", ["ngTab"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 /**
  * A TabPanel container for the resources of layered content associated with a tab.
  *
- * If a tabpanel is hidden due to its corresponding tab is not activated, the `inert` attribute
- * will be applied to the tabpanel element to remove it from the accessibility tree and stop
- * all the keyboard and pointer interactions. Note that this does not visually hide the tabpenl
- * and a proper styling is required.
+ * The `ngTabPanel` directive holds the content for a specific tab. It is linked to an
+ * `ngTab` by a matching `value`. If a tab panel is hidden, the `inert` attribute will be
+ * applied to remove it from the accessibility tree. Proper styling is required for visual hiding.
+ *
+ * ```html
+ * <div ngTabPanel value="myTabId">
+ *   <ng-template ngTabContent>
+ *     <!-- Content for the tab panel -->
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class TabPanel implements OnInit, OnDestroy {
+    /** A reference to the host element. */
+    private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The DeferredContentAware host directive. */
     private readonly _deferredContentAware;
     /** The parent Tabs. */
     private readonly _Tabs;
     /** A global unique identifier for the tab. */
-    private readonly _id;
+    readonly id: _angular_core.InputSignal<string>;
     /** The Tab UIPattern associated with the tabpanel */
-    readonly tab: Signal<TabPattern | undefined>;
+    private readonly _tabPattern;
     /** A local unique identifier for the tabpanel. */
     readonly value: _angular_core.InputSignal<string>;
+    /** Whether the tab panel is visible. */
+    readonly visible: _angular_core.Signal<boolean>;
     /** The TabPanel UIPattern. */
     readonly _pattern: TabPanelPattern;
     constructor();
     ngOnInit(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TabPanel, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabPanel, "[ngTabPanel]", ["ngTabPanel"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TabPanel, "[ngTabPanel]", ["ngTabPanel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.DeferredContentAware; inputs: { "preserveContent": "preserveContent"; }; outputs: {}; }]>;
 }
 /**
  * A TabContent container for the lazy-loaded content.
+ *
+ * This structural directive should be applied to an `ng-template` within an `ngTabPanel`.
+ * It enables lazy loading of the tab's content, meaning the content is only rendered
+ * when the tab is activated for the first time.
+ *
+ * ```html
+ * <div ngTabPanel value="myTabId">
+ *   <ng-template ngTabContent>
+ *     <p>This content will be loaded when 'myTabId' is selected.</p>
+ *   </ng-template>
+ * </div>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class TabContent {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TabContent, never>;

package/types/toolbar.d.ts

@@ -1,88 +1,104 @@
 import * as _angular_core from '@angular/core';
-import { Signal, OnInit, OnDestroy } from '@angular/core';
+import { OnInit, OnDestroy } from '@angular/core';
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
-import { ToolbarWidgetPattern, ToolbarPattern, SignalLike, ToolbarWidgetGroupPattern } from '@angular/aria/private';
+import { ToolbarWidgetPattern, ToolbarPattern, ToolbarWidgetGroupPattern } from '@angular/aria/private';
 
 /**
- * A toolbar widget container.
- *
- * Widgets such as radio groups or buttons are nested within a toolbar to allow for a single
- * place of reference for focus and navigation. The Toolbar is meant to be used in conjunction
- * with ToolbarWidget and RadioGroup as follows:
+ * A toolbar widget container for a group of interactive widgets, such as
+ * buttons or radio groups. It provides a single point of reference for keyboard navigation
+ * and focus management. It supports various orientations and disabled states.
  *
  * ```html
- * <div ngToolbar>
- *  <button ngToolbarWidget>Button</button>
- *  <div ngRadioGroup>
- *    <label ngRadioButton value="1">Option 1</label>
- *    <label ngRadioButton value="2">Option 2</label>
- *    <label ngRadioButton value="3">Option 3</label>
- *  </div>
+ * <div ngToolbar orientation="horizontal" [wrap]="true">
+ *   <button ngToolbarWidget value="save">Save</button>
+ *   <button ngToolbarWidget value="print">Print</button>
+ *
+ *   <div ngToolbarWidgetGroup [(value)]="selectedAlignment">
+ *     <button ngToolbarWidget value="left">Left</button>
+ *     <button ngToolbarWidget value="center">Center</button>
+ *     <button ngToolbarWidget value="right">Right</button>
+ *   </div>
  * </div>
  * ```
+ *
+ * @developerPreview 21.0
  */
 declare class Toolbar<V> {
-    /** A reference to the toolbar element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The TabList nested inside of the container. */
     private readonly _widgets;
     /** Text direction. */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     /** Sorted UIPatterns of the child widgets */
-    readonly items: Signal<ToolbarWidgetPattern<V>[]>;
+    readonly _itemPatterns: _angular_core.Signal<ToolbarWidgetPattern<V>[]>;
     /** Whether the toolbar is vertically or horizontally oriented. */
     readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
-    /** 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.
+     */
     softDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the toolbar is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether focus should wrap when navigating. */
     readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The values of the selected widgets within the toolbar. */
+    readonly values: _angular_core.ModelSignal<V[]>;
     /** The toolbar UIPattern. */
     readonly _pattern: ToolbarPattern<V>;
     /** Whether the toolbar has received focus yet. */
     private _hasBeenFocused;
     constructor();
-    onFocus(): void;
-    register(widget: ToolbarWidget<V>): void;
-    unregister(widget: ToolbarWidget<V>): void;
+    _onFocus(): void;
+    _register(widget: ToolbarWidget<V>): void;
+    _unregister(widget: ToolbarWidget<V>): void;
     /** Finds the toolbar item associated with a given element. */
     private _getItem;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Toolbar<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Toolbar<any>, "[ngToolbar]", ["ngToolbar"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Toolbar<any>, "[ngToolbar]", ["ngToolbar"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": false; "isSignal": true; }; }, { "values": "valuesChange"; }, never, never, true, never>;
 }
 /**
  * A widget within a toolbar.
  *
- * A widget is anything that is within a toolbar. It should be applied to any native HTML element
- * that has the purpose of acting as a widget navigatable within a toolbar.
+ * The `ngToolbarWidget` directive should be applied to any native HTML element that acts
+ * as an interactive widget within an `ngToolbar` or `ngToolbarWidgetGroup`. It enables
+ * keyboard navigation and selection within the toolbar.
+ *
+ * ```html
+ * <button ngToolbarWidget value="action-id" [disabled]="isDisabled">
+ *   Perform Action
+ * </button>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class ToolbarWidget<V> implements OnInit, OnDestroy {
-    /** A reference to the widget element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The parent Toolbar. */
     private readonly _toolbar;
     /** A unique identifier for the widget. */
-    private readonly _generatedId;
-    /** A unique identifier for the widget. */
     readonly id: _angular_core.InputSignal<string>;
     /** The parent Toolbar UIPattern. */
-    readonly toolbar: Signal<ToolbarPattern<any>>;
-    /** A reference to the widget element to be focused on navigation. */
-    readonly element: Signal<any>;
+    readonly _toolbarPattern: _angular_core.Signal<ToolbarPattern<any>>;
     /** Whether the widget is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the widget is 'hard' disabled, which is different from `aria-disabled`. A hard disabled widget cannot receive focus. */
-    readonly hardDisabled: Signal<boolean>;
+    readonly hardDisabled: _angular_core.Signal<boolean>;
     /** The optional ToolbarWidgetGroup this widget belongs to. */
     readonly _group: ToolbarWidgetGroup<any> | null;
     /** The value associated with the widget. */
     readonly value: _angular_core.InputSignal<V>;
     /** Whether the widget is currently active (focused). */
-    readonly active: Signal<boolean>;
+    readonly active: _angular_core.Signal<boolean>;
     /** Whether the widget is selected (only relevant in a selection group). */
     readonly selected: () => boolean;
-    readonly group: SignalLike<ToolbarWidgetGroupPattern<ToolbarWidgetPattern<V>, V> | undefined>;
+    private readonly _groupPattern;
     /** The ToolbarWidget UIPattern. */
     readonly _pattern: ToolbarWidgetPattern<V>;
     ngOnInit(): void;
@@ -91,20 +107,26 @@ declare class ToolbarWidget<V> implements OnInit, OnDestroy {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ToolbarWidget<any>, "[ngToolbarWidget]", ["ngToolbarWidget"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 /**
- * A directive that groups toolbar widgets, used for more complex widgets like radio groups that
- * have their own internal navigation.
+ * A directive that groups toolbar widgets, used for more complex widgets like radio groups
+ * that have their own internal navigation.
+ *
+ * @developerPreview 21.0
  */
 declare class ToolbarWidgetGroup<V> {
+    /** A reference to the host element. */
+    private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The parent Toolbar. */
     private readonly _toolbar;
     /** The list of child widgets within the group. */
     private readonly _widgets;
     /** The parent Toolbar UIPattern. */
-    readonly toolbar: Signal<ToolbarPattern<any> | undefined>;
+    private readonly _toolbarPattern;
     /** Whether the widget group is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The list of toolbar items within the group. */
-    readonly items: () => ToolbarWidgetPattern<any>[];
+    private readonly _itemPatterns;
     /** Whether the group allows multiple widgets to be selected. */
     readonly multi: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** The ToolbarWidgetGroup UIPattern. */