docs: update jsdocs for public aria API (angular#32316)

* docs: update jsdocs for public aria API

* refactor: fix lint

Author: andrewseguin

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
+ * <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
  */
@@ -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
+ * <button ngAccordionTrigger panelId="unique-id-1">
+ *   Accordion Trigger Text
+ * </button>
+ * ```
  *
  * @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
+ * <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
  */
 @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<string[]>([]);
 
-  /** 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
+ * <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
  */

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
+ * <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
  */
 @Directive({
@@ -70,7 +97,12 @@ export class Combobox<V> {
   /** The combobox popup. */
   readonly popup = contentChild<ComboboxPopup<V>>(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<V> {
   // 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<V> {
 }
 
 /**
+ * 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
  */
 @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
+ * <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
  */
 @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<V> {
   /** The combobox that the popup belongs to. */
   readonly combobox = inject<Combobox<V>>(Combobox, {optional: true});
 
-  /** The controls the popup exposes to the combobox. */
+  /** The popup controls exposed to the combobox. */
   readonly controls = signal<
     | ComboboxListboxControls<any, V>
     | ComboboxTreeControls<any, V>
@@ -223,6 +304,18 @@ export class ComboboxPopup<V> {
 }
 
 /**
+ * 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
  */
 @Directive({