From 47ef49c0e1d42d75fb6e03b7d47d38548af97679 Mon Sep 17 00:00:00 2001 From: Andrew Seguin Date: Wed, 12 Nov 2025 11:12:14 -0700 Subject: [PATCH 1/2] docs: update jsdocs for public aria API --- src/aria/accordion/accordion.ts | 94 ++++++++++++++++++++++++++----- src/aria/combobox/combobox.ts | 99 ++++++++++++++++++++++++++++++++- src/aria/grid/grid.ts | 80 +++++++++++++++++++++++--- src/aria/listbox/listbox.ts | 48 ++++++++++++---- src/aria/menu/menu.ts | 76 +++++++++++++++++++++---- src/aria/tabs/tabs.ts | 80 +++++++++++++++++++++----- src/aria/toolbar/toolbar.ts | 44 +++++++++------ src/aria/tree/tree.ts | 98 ++++++++++++++++++++++++-------- 8 files changed, 513 insertions(+), 106 deletions(-) diff --git a/src/aria/accordion/accordion.ts b/src/aria/accordion/accordion.ts index 2e8e295d91dd..ede5338e6505 100644 --- a/src/aria/accordion/accordion.ts +++ b/src/aria/accordion/accordion.ts @@ -30,8 +30,22 @@ import { } from '@angular/aria/private'; /** - * 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 + *
+ * + *

This content is lazily rendered and will be shown when the panel is expanded.

+ * + *
+ * ``` * * @developerPreview 21.0 */ @@ -100,8 +114,19 @@ export class AccordionPanel { } /** - * 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 + * + * ``` * * @developerPreview 21.0 */ @@ -145,11 +170,8 @@ export class AccordionTrigger { /** Whether the trigger is expanded. */ readonly expanded = computed(() => this._pattern.expanded()); - /** - * Whether this trigger is completely inaccessible. - * - * TODO(ok7sai): Consider move this to UI patterns. - */ + // TODO(ok7sai): Consider moving this to UI patterns. + /** Whether this trigger is inaccessible via keyboard navigation. */ readonly hardDisabled = computed(() => this._pattern.disabled() && this._pattern.tabIndex() < 0); /** The accordion panel pattern controlled by this trigger. This is set by AccordionGroup. */ @@ -182,9 +204,38 @@ export class AccordionTrigger { } /** - * 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 + *
+ *
+ *

+ * + *

+ *
+ * + *

Content for Item 1.

+ * + *
+ *
+ *
+ *

+ * + *

+ *
+ * + *

Content for Item 2.

+ * + *
+ *
+ *
+ * ``` + * * @developerPreview 21.0 */ @Directive({ @@ -213,10 +264,13 @@ export class AccordionGroup { /** Whether multiple accordion items can be expanded simultaneously. */ multiExpandable = input(true, {transform: booleanAttribute}); - /** The ids of the current expanded accordion panels. */ + /** The ids of the currently expanded accordion panels. */ expandedPanels = model([]); - /** 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 = input(true, {transform: booleanAttribute}); /** Whether keyboard navigation should wrap around from the last item to the first, and vice-versa. */ @@ -263,8 +317,20 @@ export class AccordionGroup { } /** - * 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 + *
+ * + *

This is the content that will be displayed inside the panel.

+ * + *
+ * ``` * * @developerPreview 21.0 */ diff --git a/src/aria/combobox/combobox.ts b/src/aria/combobox/combobox.ts index 66e566bcf48f..a6e478d514e0 100644 --- a/src/aria/combobox/combobox.ts +++ b/src/aria/combobox/combobox.ts @@ -32,6 +32,33 @@ import {Directionality} from '@angular/cdk/bidi'; import {toSignal} from '@angular/core/rxjs-interop'; /** + * 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 + *
+ * + * + * + *
+ * @for (option of filteredOptions(); track option) { + *
+ * {{option}} + *
+ * } + *
+ * + *
+ * ``` + * * @developerPreview 21.0 */ @Directive({ @@ -70,7 +97,12 @@ export class Combobox { /** The combobox popup. */ readonly popup = contentChild>(ComboboxPopup); - /** 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 = input<'manual' | 'auto-select' | 'highlight'>('manual'); /** Whether the combobox is disabled. */ @@ -88,7 +120,7 @@ export class Combobox { // TODO: Maybe make expanded a signal that can be passed in? // Or an "always expanded" option? - /** Whether the combobox popup is always expanded. */ + /** Whether the combobox popup should always be expanded, regardless of user interaction. */ readonly alwaysExpanded = input(false); /** Input element connected to the combobox, if any. */ @@ -145,6 +177,21 @@ export class Combobox { } /** + * 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 `` element within an `ngCombobox` + * container. It automatically handles keyboard interactions, such as opening the + * popup and navigating through the options. + * + * ```html + * + * ``` + * * @developerPreview 21.0 */ @Directive({ @@ -193,6 +240,33 @@ export class ComboboxInput { } /** + * 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 + * + *
+ * + *
+ * + * ``` + * + * When using the CdkOverlay, this directive can be replaced by `cdkConnectedOverlay. + * + * ```html + * + *
+ * + *
+ * + * ``` + * * @developerPreview 21.0 */ @Directive({ @@ -203,6 +277,13 @@ export class ComboboxInput { export class ComboboxPopupContainer {} /** + * 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 */ @Directive({ @@ -213,7 +294,7 @@ export class ComboboxPopup { /** The combobox that the popup belongs to. */ readonly combobox = inject>(Combobox, {optional: true}); - /** The controls the popup exposes to the combobox. */ + /** The popup controls exposed to the combobox. */ readonly controls = signal< | ComboboxListboxControls | ComboboxTreeControls @@ -223,6 +304,18 @@ export class ComboboxPopup { } /** + * Integrates a native `` 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 + * + * + * + * + * + * ``` + * * @developerPreview 21.0 */ @Directive({ diff --git a/src/aria/grid/grid.ts b/src/aria/grid/grid.ts index e3604e5d8344..251bd0e28b27 100644 --- a/src/aria/grid/grid.ts +++ b/src/aria/grid/grid.ts @@ -24,7 +24,23 @@ import {Directionality} from '@angular/cdk/bidi'; import {GridPattern, GridRowPattern, GridCellPattern, GridCellWidgetPattern} from '../private'; /** - * 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 + * + * @for (row of gridData; track row) { + * + * @for (cell of row; track cell) { + * + * } + * + * } + *
+ * {{cell.value}} + *
+ * ``` * * @developerPreview 21.0 */ @@ -69,22 +85,43 @@ export class Grid { /** Whether the grid is disabled. */ readonly disabled = input(false, {transform: booleanAttribute}); - /** 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 = input(true, {transform: booleanAttribute}); - /** 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 = input<'roving' | 'activedescendant'>('roving'); - /** 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 = input<'continuous' | 'loop' | 'nowrap'>('loop'); - /** 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 = input<'continuous' | 'loop' | 'nowrap'>('loop'); /** Whether multiple cells in the grid can be selected. */ readonly multi = input(false, {transform: booleanAttribute}); - /** 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 = input<'follow' | 'explicit'>('follow'); /** Whether enable range selections (with modifier keys or dragging). */ @@ -124,7 +161,13 @@ export class Grid { } /** - * A directive that represents a row in a grid. + * Represents a row within a grid. It is a container for `ngGridCell` directives. + * + * ```html + * + * + * + * ``` * * @developerPreview 21.0 */ @@ -171,7 +214,15 @@ export class GridRow { } /** - * 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 + * + * Cell Content + * + * ``` * * @developerPreview 21.0 */ @@ -251,7 +302,18 @@ export class GridCell { } /** - * 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 + * + * + * + * ``` * * @developerPreview 21.0 */ diff --git a/src/aria/listbox/listbox.ts b/src/aria/listbox/listbox.ts index 446ebedd7182..aef733b6d8c3 100644 --- a/src/aria/listbox/listbox.ts +++ b/src/aria/listbox/listbox.ts @@ -26,16 +26,19 @@ import {_IdGenerator} from '@angular/cdk/a11y'; import {ComboboxPopup} from '../combobox'; /** - * 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 - *
    - *
  • Item 1
    • - *
  • Item 2
    • - *
  • Item 3
    • + *
      + * @for (item of items; track item.id) { + *
    • + * {{item.name}} + *
      • + * } *
    * ``` * @@ -99,13 +102,24 @@ export class Listbox { /** Whether focus should wrap when navigating. */ wrap = input(true, {transform: booleanAttribute}); - /** 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 = input(true, {transform: booleanAttribute}); - /** 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 = input<'roving' | 'activedescendant'>('roving'); - /** 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 = input<'follow' | 'explicit'>('follow'); /** The amount of time before the typeahead search is reset. */ @@ -117,7 +131,7 @@ export class Listbox { /** Whether the listbox is readonly. */ readonly = input(false, {transform: booleanAttribute}); - /** The values of the current selected items. */ + /** The values of the currently selected items. */ values = model([]); /** The Listbox UIPattern. */ @@ -197,7 +211,17 @@ export class Listbox { } /** - * A selectable option in a Listbox. + * A selectable option in an `ngListbox`. + * + * This directive should be applied to an element (e.g., `
  • `, `
    `) within an + * `ngListbox`. The `value` input is used to identify the option, and the `label` input provides + * the accessible name for the option. + * + * ```html + *
  • + * Item Name + *
    • + * ``` * * @developerPreview 21.0 */ diff --git a/src/aria/menu/menu.ts b/src/aria/menu/menu.ts index c169e01b73e4..03cb41bd6919 100644 --- a/src/aria/menu/menu.ts +++ b/src/aria/menu/menu.ts @@ -37,8 +37,18 @@ import {Directionality} from '@angular/cdk/bidi'; /** * A trigger for a menu. * - * The menu trigger is used to open and close menus, and can be placed on menu items to connect - * sub-menus. + * The `ngMenuTrigger` directive is used to open and close menus. It can be applied to + * any interactive element (e.g., a button) to associate it with a `ngMenu` instance. + * It also supports linking to sub-menus when applied to a `ngMenuItem`. + * + * ```html + * + * + *
    + *
    Item 1
    + *
    Item 2
    + *
    + * ``` * * @developerPreview 21.0 */ @@ -110,16 +120,22 @@ export class MenuTrigger { /** * A list of menu items. * - * A menu is used to offer a list of menu item choices to users. Menus can be nested within other - * menus to create sub-menus. + * A `ngMenu` is used to offer a list of menu item choices to users. Menus can be nested + * within other menus to create sub-menus. It works in conjunction with `ngMenuTrigger` + * and `ngMenuItem` directives. * * ```html - * + * * - *
    + *
    *
    Star
    *
    Edit
    - *
    Delete
    + *
    More
    + *
    + * + *
    + *
    Sub Item 1
    + *
    Sub Item 2
    *
    * ``` * @@ -261,9 +277,26 @@ export class Menu { /** * A menu bar of menu items. * - * Like the menu, a menubar is used to offer a list of menu item choices to users. However, a - * menubar is used to display a persistent, top-level, - * always-visible set of menu item choices. + * Like the `ngMenu`, a `ngMenuBar` is used to offer a list of menu item choices to users. + * However, a menubar is used to display a persistent, top-level, always-visible set of + * menu item choices, typically found at the top of an application window. + * + * ```html + *
    + * + * + *
    + * + *
    + *
    New
    + *
    Open
    + *
    + * + *
    + *
    Cut
    + *
    Copy
    + *
    + * ``` * * @developerPreview 21.0 */ @@ -305,7 +338,7 @@ export class MenuBar { /** The directionality (LTR / RTL) context for the application (or a subtree of it). */ readonly textDirection = inject(Directionality).valueSignal; - /** The values of the menu. */ + /** The values of the currently selected menu items. */ readonly values = model([]); /** Whether the menu should wrap its items. */ @@ -356,7 +389,14 @@ export class MenuBar { /** * An item in a Menu. * - * Menu items can be used in menus and menubars to represent a choice or action a user can take. + * `ngMenuItem` directives can be used in `ngMenu` and `ngMenuBar` to represent a choice + * or action a user can take. They can also act as triggers for sub-menus. + * + * ```html + *
    Action Item
    + * + *
    Submenu Trigger
    + * ``` * * @developerPreview 21.0 */ @@ -446,6 +486,18 @@ export class MenuItem { /** * Defers the rendering of the menu content. * + * This structural directive should be applied to an `ng-template` within a `ngMenu` + * or `ngMenuBar` to lazily render its content only when the menu is opened. + * + * ```html + *
    + * + *
    Lazy Item 1
    + *
    Lazy Item 2
    + *     + *
    + * ``` + * * @developerPreview 21.0 */ @Directive({ diff --git a/src/aria/tabs/tabs.ts b/src/aria/tabs/tabs.ts index ae65f5f6241c..234afcb2e200 100644 --- a/src/aria/tabs/tabs.ts +++ b/src/aria/tabs/tabs.ts @@ -47,26 +47,28 @@ function sortDirectives(a: HasElement, b: HasElement) { /** * 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 *
    - *
      + *
        *
      • Tab 1
        • *
      • Tab 2
        • *
      • Tab 3
        • *
      * *
      - * Tab content 1 + * Content for Tab 1 *
      *
      - * Tab content 2 + * Content for Tab 2 *
      *
      - * Tab content 3 + * Content for Tab 3 *
      + *
    * ``` * * @developerPreview 21.0 @@ -126,7 +128,16 @@ export class Tabs { /** * 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 + *
      + *
    • First Tab
      • + *
    • Second Tab
      • + *
    + * ``` * * @developerPreview 21.0 */ @@ -174,19 +185,30 @@ export class TabList implements OnInit, OnDestroy { /** Whether focus should wrap when navigating. */ readonly wrap = input(true, {transform: booleanAttribute}); - /** 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 = input(true, {transform: booleanAttribute}); - /** 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 = input<'roving' | 'activedescendant'>('roving'); - /** 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 = input<'follow' | 'explicit'>('follow'); /** Whether the tablist is disabled. */ readonly disabled = input(false, {transform: booleanAttribute}); - /** The current selected tab. */ + /** The currently selected tab. */ readonly selectedTab = model(); /** The TabList UIPattern. */ @@ -237,6 +259,15 @@ export class TabList implements OnInit, OnDestroy { /** * 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 + *
  • + * My Tab Label + *
    • + * ``` + * * @developerPreview 21.0 */ @Directive({ @@ -318,10 +349,17 @@ export class Tab implements HasElement, OnInit, OnDestroy { /** * 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 + *
    + * + * + * + *
    + * ``` * * @developerPreview 21.0 */ @@ -385,6 +423,18 @@ export class TabPanel implements OnInit, OnDestroy { /** * 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 + *
    + * + *

    This content will be loaded when 'myTabId' is selected.

    + *     + *
    + * ``` + * * @developerPreview 21.0 */ @Directive({ diff --git a/src/aria/toolbar/toolbar.ts b/src/aria/toolbar/toolbar.ts index e54edb888a94..600cc6281600 100644 --- a/src/aria/toolbar/toolbar.ts +++ b/src/aria/toolbar/toolbar.ts @@ -43,20 +43,20 @@ function sortDirectives(a: HasElement, b: HasElement) { } /** - * 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 - *
    - * - *
    - * - * - * - *
    + *
    + * + * + * + *
    + * + * + * + *
    *
    * ``` * @@ -95,7 +95,10 @@ export class Toolbar { /** Whether the toolbar is vertically or horizontally oriented. */ readonly orientation = input<'vertical' | 'horizontal'>('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 = input(true, {transform: booleanAttribute}); /** Whether the toolbar is disabled. */ @@ -162,8 +165,15 @@ export class Toolbar { /** * 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 + * + * ``` * * @developerPreview 21.0 */ @@ -238,8 +248,8 @@ export class ToolbarWidget implements OnInit, OnDestroy { } /** - * 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 */ diff --git a/src/aria/tree/tree.ts b/src/aria/tree/tree.ts index 635810f95733..df6a6bd1378f 100644 --- a/src/aria/tree/tree.ts +++ b/src/aria/tree/tree.ts @@ -47,24 +47,35 @@ function sortDirectives(a: HasElement, b: HasElement) { } /** - * 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 - *
      - *
    • Leaf Item 1
      • - *
    • - * Parent Item 1 - *
        - * - *
      • Child Item 1.1
        • - *
      • Child Item 1.2
        • - *         - *
      - *
      • - *
    • Disabled Leaf Item 2
      • + *
        + * *
      + * + * + * @for (node of nodes; track node.name) { + *
    • + * {{ node.name }} + * @if (node.children) { + *
        + * + * + * + *
      + * } + *
      • + * } + *       * ``` * * @developerPreview 21.0 @@ -115,22 +126,33 @@ export class Tree { /** Whether the tree is disabled. */ readonly disabled = input(false, {transform: booleanAttribute}); - /** 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 = input<'explicit' | 'follow'>('explicit'); - /** 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 = input<'roving' | 'activedescendant'>('roving'); /** Whether navigation wraps. */ readonly wrap = input(true, {transform: booleanAttribute}); - /** 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 = input(true, {transform: booleanAttribute}); - /** Typeahead delay. */ + /** The delay in seconds before the typeahead search is reset. */ readonly typeaheadDelay = input(0.5); - /** Selected item values. */ + /** The values of the currently selected items. */ readonly values = model([]); /** Text direction. */ @@ -139,7 +161,10 @@ export class Tree { /** Whether the tree is in navigation mode. */ readonly nav = input(false); - /** The aria-current type. */ + /** + * 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 = input<'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'>( 'page', ); @@ -147,7 +172,7 @@ export class Tree { /** The UI pattern for the tree. */ readonly _pattern: TreePattern; - /** Whether the tree has received focus yet. */ + /** Whether the tree has received focus since it was rendered. */ private _hasFocused = signal(false); constructor() { @@ -215,7 +240,17 @@ export class Tree { } /** - * 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 + *
    • + * Item Label + *
      • + * ``` * * @developerPreview 21.0 */ @@ -347,7 +382,22 @@ export class TreeItem extends DeferredContentAware implements OnInit, OnDestr } /** - * 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 + *
    • + * Parent Item + *
        + * + *
      • Child Item
        • + *         + *
      + *
      • + * ``` * * @developerPreview 21.0 */ From 17fb71ca054cc09c37735d3d0af4c561ccff5877 Mon Sep 17 00:00:00 2001 From: Andrew Seguin Date: Wed, 12 Nov 2025 11:27:55 -0700 Subject: [PATCH 2/2] refactor: fix lint --- src/aria/combobox/combobox.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/aria/combobox/combobox.ts b/src/aria/combobox/combobox.ts index a6e478d514e0..80fb963f4900 100644 --- a/src/aria/combobox/combobox.ts +++ b/src/aria/combobox/combobox.ts @@ -255,7 +255,7 @@ export class ComboboxInput { * * ``` * - * When using the CdkOverlay, this directive can be replaced by `cdkConnectedOverlay. + * When using CdkOverlay, this directive can be replaced by `cdkConnectedOverlay`. * * ```html *