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

package/types/tree.d.ts

@@ -1,93 +1,132 @@
 import * as _angular_cdk_bidi from '@angular/cdk/bidi';
 import * as _angular_core from '@angular/core';
-import { Signal, OnInit, OnDestroy } from '@angular/core';
+import { OnInit, OnDestroy, Signal } from '@angular/core';
 import * as i1 from '@angular/aria/private';
 import { TreePattern, DeferredContentAware, TreeItemPattern } from '@angular/aria/private';
 import { ComboboxPopup } from './combobox.js';
 
 interface HasElement {
-    element: Signal<HTMLElement>;
+    element: HTMLElement;
 }
 /**
- * A Tree container.
- *
- * Transforms nested lists into an accessible, ARIA-compliant tree structure.
+ * A container that transforms nested lists into an accessible, ARIA-compliant tree structure.
+ * It manages the overall state of the tree, including selection, expansion, and keyboard
+ * navigation.
  *
  * ```html
  * <ul ngTree [(value)]="selectedItems" [multi]="true">
- *   <li ngTreeItem [value]="'leaf1'">Leaf Item 1</li>
- *   <li ngTreeItem [value]="'parent1'">
- *     Parent Item 1
- *     <ul ngTreeItemGroup [value]="'parent1'">
- *       <ng-template ngTreeItemGroupContent>
- *         <li ngTreeItem [value]="'child1.1'">Child Item 1.1</li>
- *         <li ngTreeItem [value]="'child1.2'">Child Item 1.2</li>
- *       </ng-template>
- *     </ul>
- *   </li>
- *   <li ngTreeItem [value]="'leaf2'" [disabled]="true">Disabled Leaf Item 2</li>
+ *   <ng-template
+ *     [ngTemplateOutlet]="treeNodes"
+ *     [ngTemplateOutletContext]="{nodes: treeData, parent: tree}"
+ *   />
  * </ul>
+ *
+ * <ng-template #treeNodes let-nodes="nodes" let-parent="parent">
+ *   @for (node of nodes; track node.name) {
+ *     <li ngTreeItem [parent]="parent" [value]="node.name" [label]="node.name">
+ *       {{ node.name }}
+ *       @if (node.children) {
+ *         <ul role="group">
+ *           <ng-template ngTreeItemGroup [ownedBy]="treeItem" #group="ngTreeItemGroup">
+ *             <ng-template
+ *               [ngTemplateOutlet]="treeNodes"
+ *               [ngTemplateOutletContext]="{nodes: node.children, parent: group}"
+ *             />
+ *           </ng-template>
+ *         </ul>
+ *       }
+ *     </li>
+ *   }
+ * </ng-template>
  * ```
+ *
+ * @developerPreview 21.0
  */
 declare class Tree<V> {
-    /** A unique identifier for the tree. */
-    private readonly _generatedId;
-    /** A unique identifier for the tree. */
-    protected id: Signal<string>;
+    /** A reference to the host element. */
+    private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** A reference to the parent combobox popup, if one exists. */
     private readonly _popup;
-    /** A reference to the tree element. */
-    private readonly _elementRef;
     /** All TreeItem instances within this tree. */
     private readonly _unorderedItems;
+    /** A unique identifier for the tree. */
+    readonly id: _angular_core.InputSignal<string>;
     /** Orientation of the tree. */
     readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
     /** Whether multi-selection is allowed. */
     readonly multi: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the tree is disabled. */
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** The selection strategy used by the tree. */
+    /**
+     * The selection strategy used by the tree.
+     * - `explicit`: Items are selected explicitly by the user (e.g., via click or spacebar).
+     * - `follow`: The focused item is automatically selected.
+     */
     readonly selectionMode: _angular_core.InputSignal<"explicit" | "follow">;
-    /** The focus strategy used by the tree. */
+    /**
+     * The focus strategy used by the tree.
+     * - `roving`: Focus is moved to the active item using `tabindex`.
+     * - `activedescendant`: Focus remains on the tree container, and `aria-activedescendant` is used to indicate the active item.
+     */
     readonly focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
     /** Whether navigation wraps. */
     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>;
-    /** Typeahead delay. */
+    /** The delay in seconds before the typeahead search is reset. */
     readonly typeaheadDelay: _angular_core.InputSignal<number>;
-    /** Selected item values. */
-    readonly value: _angular_core.ModelSignal<V[]>;
+    /** The values of the currently selected items. */
+    readonly values: _angular_core.ModelSignal<V[]>;
     /** Text direction. */
     readonly textDirection: _angular_core.WritableSignal<_angular_cdk_bidi.Direction>;
     /** Whether the tree is in navigation mode. */
-    readonly nav: _angular_core.InputSignal<boolean>;
-    /** The aria-current type. */
+    readonly nav: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The `aria-current` type. It can be used in navigation trees to indicate the currently active item.
+     * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current for more details.
+     */
     readonly currentType: _angular_core.InputSignal<"page" | "step" | "location" | "date" | "time" | "true" | "false">;
     /** The UI pattern for the tree. */
     readonly _pattern: TreePattern<V>;
-    /** Whether the tree has received focus yet. */
+    /** Whether the tree has received focus since it was rendered. */
     private _hasFocused;
     constructor();
-    onFocus(): void;
-    register(child: TreeItem<V>): void;
-    unregister(child: TreeItem<V>): void;
+    _onFocus(): void;
+    _register(child: TreeItem<V>): void;
+    _unregister(child: TreeItem<V>): void;
     scrollActiveItemIntoView(options?: ScrollIntoViewOptions): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Tree<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tree<any>, "[ngTree]", ["ngTree"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "nav": { "alias": "nav"; "required": false; "isSignal": true; }; "currentType": { "alias": "currentType"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, [{ directive: typeof ComboboxPopup; inputs: {}; outputs: {}; }]>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Tree<any>, "[ngTree]", ["ngTree"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "wrap": { "alias": "wrap"; "required": false; "isSignal": true; }; "softDisabled": { "alias": "softDisabled"; "required": false; "isSignal": true; }; "typeaheadDelay": { "alias": "typeaheadDelay"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": false; "isSignal": true; }; "nav": { "alias": "nav"; "required": false; "isSignal": true; }; "currentType": { "alias": "currentType"; "required": false; "isSignal": true; }; }, { "values": "valuesChange"; }, never, never, true, [{ directive: typeof ComboboxPopup; inputs: {}; outputs: {}; }]>;
 }
 /**
- * A selectable and expandable Tree Item in a Tree.
+ * A selectable and expandable item in an `ngTree`.
+ *
+ * The `ngTreeItem` directive represents an individual node within an `ngTree`. It can be
+ * selected, expanded (if it has children), and disabled. The `parent` input establishes
+ * the hierarchical relationship within the tree.
+ *
+ * ```html
+ * <li ngTreeItem [parent]="parentTreeOrGroup" value="item-id" label="Item Label">
+ *   Item Label
+ * </li>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class TreeItem<V> extends DeferredContentAware implements OnInit, OnDestroy, HasElement {
-    /** A reference to the tree item element. */
+    /** A reference to the host element. */
     private readonly _elementRef;
-    /** A unique identifier for the tree item. */
-    private readonly _id;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The owned tree item group. */
     private readonly _group;
-    /** The host native element. */
-    readonly element: Signal<any>;
+    /** A unique identifier for the tree item. */
+    readonly id: _angular_core.InputSignal<string>;
     /** The value of the tree item. */
     readonly value: _angular_core.InputSignal<V>;
     /** The parent tree root or tree item group. */
@@ -96,38 +135,71 @@ declare class TreeItem<V> extends DeferredContentAware implements OnInit, OnDest
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the tree item is selectable. */
     readonly selectable: _angular_core.InputSignal<boolean>;
+    /** Whether the tree item is expanded. */
+    readonly expanded: _angular_core.ModelSignal<boolean>;
     /** Optional label for typeahead. Defaults to the element's textContent. */
     readonly label: _angular_core.InputSignal<string | undefined>;
     /** Search term for typeahead. */
-    readonly searchTerm: Signal<any>;
+    readonly searchTerm: Signal<string>;
     /** The tree root. */
     readonly tree: Signal<Tree<V>>;
+    /** Whether the item is active. */
+    readonly active: Signal<boolean>;
+    /** The level of the current item in a tree. */
+    readonly level: Signal<number>;
+    /** Whether the item is selected. */
+    readonly selected: Signal<boolean | undefined>;
+    /** Whether this item is visible due to all of its parents being expanded. */
+    readonly visible: Signal<boolean>;
+    /** Whether the tree is expanded. Use this value for aria-expanded. */
+    protected readonly _expanded: Signal<boolean | undefined>;
     /** The UI pattern for this item. */
     _pattern: TreeItemPattern<V>;
     constructor();
     ngOnInit(): void;
     ngOnDestroy(): void;
-    register(group: TreeItemGroup<V>): void;
-    unregister(): void;
+    _register(group: TreeItemGroup<V>): void;
+    _unregister(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeItem<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TreeItem<any>, "[ngTreeItem]", ["ngTreeItem"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "parent": { "alias": "parent"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TreeItem<any>, "[ngTreeItem]", ["ngTreeItem"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "parent": { "alias": "parent"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, { "expanded": "expandedChange"; }, never, never, true, never>;
 }
 /**
- * Contains children tree itmes.
+ * Group that contains children tree items.
+ *
+ * The `ngTreeItemGroup` structural directive should be applied to an `ng-template` that
+ * wraps the child `ngTreeItem` elements. It is used to define a group of children for an
+ * expandable `ngTreeItem`. The `ownedBy` input links the group to its parent `ngTreeItem`.
+ *
+ * ```html
+ * <li ngTreeItem [value]="'parent-id'">
+ *   Parent Item
+ *   <ul role="group">
+ *     <ng-template ngTreeItemGroup [ownedBy]="parentTreeItemRef">
+ *       <li ngTreeItem [value]="'child-id'">Child Item</li>
+ *     </ng-template>
+ *   </ul>
+ * </li>
+ * ```
+ *
+ * @developerPreview 21.0
  */
 declare class TreeItemGroup<V> implements OnInit, OnDestroy {
+    /** A reference to the host element. */
+    private readonly _elementRef;
+    /** A reference to the host element. */
+    readonly element: HTMLElement;
     /** The DeferredContent host directive. */
     private readonly _deferredContent;
     /** All groupable items that are descendants of the group. */
     private readonly _unorderedItems;
     /** Child items within this group. */
-    readonly children: Signal<TreeItemPattern<V>[]>;
+    readonly _childPatterns: Signal<TreeItemPattern<V>[]>;
     /** Tree item that owns the group. */
     readonly ownedBy: _angular_core.InputSignal<TreeItem<V>>;
     ngOnInit(): void;
     ngOnDestroy(): void;
-    register(child: TreeItem<V>): void;
-    unregister(child: TreeItem<V>): void;
+    _register(child: TreeItem<V>): void;
+    _unregister(child: TreeItem<V>): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeItemGroup<any>, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TreeItemGroup<any>, "ng-template[ngTreeItemGroup]", ["ngTreeItemGroup"], { "ownedBy": { "alias": "ownedBy"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.DeferredContent; inputs: {}; outputs: {}; }]>;
 }