@angular/cdk 21.1.0-next.1 → 21.1.0-next.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/cdk",
-  "version": "21.1.0-next.1",
+  "version": "21.1.0-next.3",
   "description": "Angular Material Component Development Kit",
   "repository": {
     "type": "git",
@@ -160,6 +160,7 @@
   "peerDependencies": {
     "@angular/core": "^21.0.0-0 || ^21.1.0-0 || ^21.2.0-0 || ^21.3.0-0 || ^22.0.0-0",
     "@angular/common": "^21.0.0-0 || ^21.1.0-0 || ^21.2.0-0 || ^21.3.0-0 || ^22.0.0-0",
+    "@angular/platform-browser": "^21.0.0-0 || ^21.1.0-0 || ^21.2.0-0 || ^21.3.0-0 || ^22.0.0-0",
     "rxjs": "^6.5.3 || ^7.4.0"
   },
   "dependencies": {

package/schematics/ng-add/index.js

@@ -26,6 +26,6 @@ function default_1() {
     // In order to align the CDK version with other Angular dependencies that are setup by
     // `@schematics/angular`, we use tilde instead of caret. This is default for Angular
     // dependencies in new CLI projects.
-    return (0, utility_1.addDependency)('@angular/cdk', `~21.1.0-next.1`, { existing: utility_1.ExistingBehavior.Skip });
+    return (0, utility_1.addDependency)('@angular/cdk', `~21.1.0-next.3`, { existing: utility_1.ExistingBehavior.Skip });
 }
 //# sourceMappingURL=index.js.map

package/types/_harness-environment-chunk.d.ts

@@ -687,8 +687,6 @@ declare class HarnessPredicate<T extends ComponentHarness> {
     getDescription(): string;
     /** Gets the selector used to find candidate elements. */
     getSelector(): string;
-    /** Adds base options common to all harness types. */
-    private _addBaseOptions;
 }
 
 /**

package/types/_overlay-module-chunk.d.ts

@@ -119,6 +119,7 @@ declare class OverlayRef implements PortalOutlet {
     private _backdropRef;
     private _detachContentMutationObserver;
     private _detachContentAfterRenderRef;
+    private _disposed;
     /**
      * Reference to the parent of the `_host` at the time it was detached. Used to restore
      * the `_host` to its original position in the DOM when it gets re-attached.
@@ -392,7 +393,7 @@ declare function validateHorizontalPosition(property: string, value: HorizontalC
 /** Container inside which all overlays will render. */
 declare class OverlayContainer implements OnDestroy {
     protected _platform: Platform;
-    protected _containerElement: HTMLElement;
+    protected _containerElement: HTMLElement | undefined;
     protected _document: Document;
     protected _styleLoader: _CdkPrivateStyleLoader;
     constructor(...args: unknown[]);

package/types/_scrolling-module-chunk.d.ts

@@ -171,6 +171,11 @@ declare abstract class CdkVirtualScrollable extends CdkScrollable {
     static ɵdir: i0.ɵɵDirectiveDeclaration<CdkVirtualScrollable, never, never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Lightweight token that can be used to inject the `CdkVirtualScrollViewport`
+ * without introducing a hard dependency on it.
+ */
+declare const CDK_VIRTUAL_SCROLL_VIEWPORT: InjectionToken<CdkVirtualScrollViewport>;
 /** A viewport that virtualizes its scrolling with the help of `CdkVirtualForOf`. */
 declare class CdkVirtualScrollViewport extends CdkVirtualScrollable implements OnInit, OnDestroy {
     elementRef: ElementRef<HTMLElement>;
@@ -182,6 +187,7 @@ declare class CdkVirtualScrollViewport extends CdkVirtualScrollable implements O
     private readonly _detachedSubject;
     /** Emits when the rendered range changes. */
     private readonly _renderedRangeSubject;
+    private readonly _renderedContentOffsetSubject;
     /** The direction the viewport scrolls. */
     get orientation(): "horizontal" | "vertical";
     set orientation(orientation: 'horizontal' | 'vertical');
@@ -197,6 +203,10 @@ declare class CdkVirtualScrollViewport extends CdkVirtualScrollable implements O
     _contentWrapper: ElementRef<HTMLElement>;
     /** A stream that emits whenever the rendered range changes. */
     readonly renderedRangeStream: Observable<ListRange>;
+    /**
+     * Emits the offset from the start of the viewport to the start of the rendered data (in pixels).
+     */
+    readonly renderedContentOffset: Observable<number>;
     /**
      * The total size of all content (in pixels), including content that is not currently rendered.
      */
@@ -547,5 +557,5 @@ declare class ScrollingModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<ScrollingModule>;
 }
 
-export { CdkFixedSizeVirtualScroll, CdkScrollable, CdkScrollableModule, CdkVirtualForOf, CdkVirtualScrollViewport, CdkVirtualScrollable, CdkVirtualScrollableElement, CdkVirtualScrollableWindow, DEFAULT_SCROLL_TIME, FixedSizeVirtualScrollStrategy, ScrollDispatcher, ScrollingModule, VIRTUAL_SCROLLABLE, VIRTUAL_SCROLL_STRATEGY, _fixedSizeVirtualScrollStrategyFactory };
+export { CDK_VIRTUAL_SCROLL_VIEWPORT, CdkFixedSizeVirtualScroll, CdkScrollable, CdkScrollableModule, CdkVirtualForOf, CdkVirtualScrollViewport, CdkVirtualScrollable, CdkVirtualScrollableElement, CdkVirtualScrollableWindow, DEFAULT_SCROLL_TIME, FixedSizeVirtualScrollStrategy, ScrollDispatcher, ScrollingModule, VIRTUAL_SCROLLABLE, VIRTUAL_SCROLL_STRATEGY, _fixedSizeVirtualScrollStrategyFactory };
 export type { CdkVirtualForOfContext, CdkVirtualScrollRepeater, ExtendedScrollToOptions, VirtualScrollStrategy, _Bottom, _End, _Left, _Right, _Start, _Top, _Without, _XAxis, _XOR, _YAxis };

package/types/_view-repeater-chunk.d.ts

@@ -1,4 +1,4 @@
-import { TemplateRef, IterableChangeRecord, IterableChanges, ViewContainerRef, InjectionToken } from '@angular/core';
+import { TemplateRef, IterableChangeRecord, IterableChanges, ViewContainerRef } from '@angular/core';
 
 /**
  * The context for an embedded view in the repeater's view container.
@@ -78,11 +78,6 @@ interface _ViewRepeater<T, R, C extends _ViewRepeaterItemContext<T>> {
     applyChanges(changes: IterableChanges<R>, viewContainerRef: ViewContainerRef, itemContextFactory: _ViewRepeaterItemContextFactory<T, R, C>, itemValueResolver: _ViewRepeaterItemValueResolver<T, R>, itemViewChanged?: _ViewRepeaterItemChanged<R, C>): void;
     detach(): void;
 }
-/**
- * Injection token for `_ViewRepeater`. This token is for use by Angular Material only.
- * @docs-private
- */
-declare const _VIEW_REPEATER_STRATEGY: InjectionToken<_ViewRepeater<unknown, unknown, _ViewRepeaterItemContext<unknown>>>;
 
-export { _VIEW_REPEATER_STRATEGY, _ViewRepeaterOperation };
+export { _ViewRepeaterOperation };
 export type { _ViewRepeater, _ViewRepeaterItemChange, _ViewRepeaterItemChanged, _ViewRepeaterItemContext, _ViewRepeaterItemContextFactory, _ViewRepeaterItemInsertArgs, _ViewRepeaterItemValueResolver };

package/types/collections.d.ts

@@ -3,7 +3,7 @@ import { DataSource } from './_data-source-chunk.js';
 export { CollectionViewer, ListRange, isDataSource } from './_data-source-chunk.js';
 import { IterableChanges, ViewContainerRef } from '@angular/core';
 import { _ViewRepeaterItemContext, _ViewRepeater, _ViewRepeaterItemContextFactory, _ViewRepeaterItemValueResolver, _ViewRepeaterItemChanged } from './_view-repeater-chunk.js';
-export { _VIEW_REPEATER_STRATEGY, _ViewRepeaterItemChange, _ViewRepeaterItemInsertArgs, _ViewRepeaterOperation } from './_view-repeater-chunk.js';
+export { _ViewRepeaterItemChange, _ViewRepeaterItemInsertArgs, _ViewRepeaterOperation } from './_view-repeater-chunk.js';
 import { SelectionModel } from './_selection-model-chunk.js';
 export { SelectionChange, getMultipleValuesInSingleSelectionError } from './_selection-model-chunk.js';
 export { UniqueSelectionDispatcher, UniqueSelectionDispatcherListener } from './_unique-selection-dispatcher-chunk.js';

package/types/menu.d.ts

@@ -319,6 +319,11 @@ declare abstract class CdkMenuTriggerBase implements OnDestroy {
     menuTemplateRef: TemplateRef<unknown> | null;
     /** Context data to be passed along to the menu template */
     menuData: unknown;
+    /**
+     * Selector for the element on which to set the transform origin once the menu is open.
+     * This makes it easier to implement animations that start from the attachment point of the menu.
+     */
+    transformOriginSelector: string | null;
     /** Close the opened menu. */
     abstract close(): void;
     /** A reference to the overlay which manages the triggered menu */
@@ -342,7 +347,7 @@ declare abstract class CdkMenuTriggerBase implements OnDestroy {
      * Get the portal to be attached to the overlay which contains the menu. Allows for the menu
      * content to change dynamically and be reflected in the application.
      */
-    protected getMenuContentPortal(): TemplatePortal<any>;
+    protected getMenuContentPortal(): TemplatePortal<any> | undefined;
     /**
      * Whether the given element is inside the scope of this trigger's menu stack.
      * @param element The element to check.
@@ -436,7 +441,7 @@ declare class CdkMenuTrigger extends CdkMenuTriggerBase implements OnChanges, On
     /** Sets thte `type` attribute of the trigger. */
     private _setType;
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkMenuTrigger, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkMenuTrigger, "[cdkMenuTriggerFor]", ["cdkMenuTriggerFor"], { "menuTemplateRef": { "alias": "cdkMenuTriggerFor"; "required": false; }; "menuPosition": { "alias": "cdkMenuPosition"; "required": false; }; "menuData": { "alias": "cdkMenuTriggerData"; "required": false; }; }, { "opened": "cdkMenuOpened"; "closed": "cdkMenuClosed"; }, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkMenuTrigger, "[cdkMenuTriggerFor]", ["cdkMenuTriggerFor"], { "menuTemplateRef": { "alias": "cdkMenuTriggerFor"; "required": false; }; "menuPosition": { "alias": "cdkMenuPosition"; "required": false; }; "menuData": { "alias": "cdkMenuTriggerData"; "required": false; }; "transformOriginSelector": { "alias": "cdkMenuTriggerTransformOriginOn"; "required": false; }; }, { "opened": "cdkMenuOpened"; "closed": "cdkMenuClosed"; }, never, never, true, never>;
 }
 
 /**
@@ -739,8 +744,6 @@ declare class CdkMenuItemRadio extends CdkMenuItemSelectable implements OnDestro
     trigger(options?: {
         keepOpen: boolean;
     }): void;
-    /** Configure the unique selection dispatcher listener in order to toggle the checked state  */
-    private _registerDispatcherListener;
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkMenuItemRadio, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<CdkMenuItemRadio, "[cdkMenuItemRadio]", ["cdkMenuItemRadio"], {}, {}, never, never, true, never>;
 }
@@ -817,7 +820,7 @@ declare class CdkContextMenuTrigger extends CdkMenuTriggerBase implements OnDest
      */
     private _open;
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkContextMenuTrigger, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkContextMenuTrigger, "[cdkContextMenuTriggerFor]", ["cdkContextMenuTriggerFor"], { "menuTemplateRef": { "alias": "cdkContextMenuTriggerFor"; "required": false; }; "menuPosition": { "alias": "cdkContextMenuPosition"; "required": false; }; "menuData": { "alias": "cdkContextMenuTriggerData"; "required": false; }; "disabled": { "alias": "cdkContextMenuDisabled"; "required": false; }; }, { "opened": "cdkContextMenuOpened"; "closed": "cdkContextMenuClosed"; }, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkContextMenuTrigger, "[cdkContextMenuTriggerFor]", ["cdkContextMenuTriggerFor"], { "menuTemplateRef": { "alias": "cdkContextMenuTriggerFor"; "required": false; }; "menuPosition": { "alias": "cdkContextMenuPosition"; "required": false; }; "menuData": { "alias": "cdkContextMenuTriggerData"; "required": false; }; "transformOriginSelector": { "alias": "cdkContextMenuTriggerTransformOriginOn"; "required": false; }; "disabled": { "alias": "cdkContextMenuDisabled"; "required": false; }; }, { "opened": "cdkContextMenuOpened"; "closed": "cdkContextMenuClosed"; }, never, never, true, never>;
     static ngAcceptInputType_disabled: unknown;
 }
 

package/types/scrolling.d.ts

@@ -1,4 +1,4 @@
-export { CdkFixedSizeVirtualScroll, CdkScrollable, CdkScrollableModule, CdkVirtualForOf, CdkVirtualForOfContext, CdkVirtualScrollRepeater, CdkVirtualScrollViewport, CdkVirtualScrollable, CdkVirtualScrollableElement, CdkVirtualScrollableWindow, DEFAULT_SCROLL_TIME, ExtendedScrollToOptions, FixedSizeVirtualScrollStrategy, ScrollDispatcher, ScrollingModule, VIRTUAL_SCROLLABLE, VIRTUAL_SCROLL_STRATEGY, VirtualScrollStrategy, _Bottom, _End, _Left, _Right, _Start, _Top, _Without, _XAxis, _XOR, _YAxis, _fixedSizeVirtualScrollStrategyFactory } from './_scrolling-module-chunk.js';
+export { CDK_VIRTUAL_SCROLL_VIEWPORT, CdkFixedSizeVirtualScroll, CdkScrollable, CdkScrollableModule, CdkVirtualForOf, CdkVirtualForOfContext, CdkVirtualScrollRepeater, CdkVirtualScrollViewport, CdkVirtualScrollable, CdkVirtualScrollableElement, CdkVirtualScrollableWindow, DEFAULT_SCROLL_TIME, ExtendedScrollToOptions, FixedSizeVirtualScrollStrategy, ScrollDispatcher, ScrollingModule, VIRTUAL_SCROLLABLE, VIRTUAL_SCROLL_STRATEGY, VirtualScrollStrategy, _Bottom, _End, _Left, _Right, _Start, _Top, _Without, _XAxis, _XOR, _YAxis, _fixedSizeVirtualScrollStrategyFactory } from './_scrolling-module-chunk.js';
 import * as i0 from '@angular/core';
 import { OnDestroy } from '@angular/core';
 import { Observable } from 'rxjs';

package/types/table.d.ts

@@ -1,8 +1,8 @@
 import { Directionality } from './_bidi-module-chunk.js';
 import * as i0 from '@angular/core';
 import { TemplateRef, ElementRef, OnChanges, IterableDiffers, IterableDiffer, SimpleChanges, IterableChanges, OnDestroy, ViewContainerRef, InjectionToken, AfterContentInit, AfterContentChecked, OnInit, ChangeDetectorRef, TrackByFunction, EventEmitter, QueryList } from '@angular/core';
-import { Observable, BehaviorSubject } from 'rxjs';
-import { DataSource, CollectionViewer } from './_data-source-chunk.js';
+import { Observable, Subject, BehaviorSubject } from 'rxjs';
+import { DataSource, CollectionViewer, ListRange } from './_data-source-chunk.js';
 import { _ViewRepeater } from './_view-repeater-chunk.js';
 import { ScrollingModule } from './_scrolling-module-chunk.js';
 import './_number-property-chunk.js';
@@ -351,6 +351,9 @@ interface StickyPositioningListener {
 /**
  * Enables the recycle view repeater strategy, which reduces rendering latency. Not compatible with
  * tables that animate rows.
+ *
+ * @deprecated This directive is a no-op and will be removed.
+ * @breaking-change 23.0.0
  */
 declare class CdkRecycleRows {
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkRecycleRows, never>;
@@ -437,18 +440,22 @@ interface RenderRow<T> {
  * as a data array, an Observable stream that emits the data array to render, or a DataSource with a
  * connect function that will return an Observable stream that emits the data array to render.
  */
-declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, CollectionViewer, OnDestroy, OnInit {
+declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, CollectionViewer, OnDestroy, OnInit, StickyPositioningListener {
     protected readonly _differs: IterableDiffers;
     protected readonly _changeDetectorRef: ChangeDetectorRef;
     protected readonly _elementRef: ElementRef<any>;
     protected readonly _dir: Directionality | null;
     private _platform;
-    protected readonly _viewRepeater: _ViewRepeater<T, RenderRow<T>, RowContext<T>>;
+    protected _viewRepeater: _ViewRepeater<T, RenderRow<T>, RowContext<T>>;
     private readonly _viewportRuler;
-    protected readonly _stickyPositioningListener: StickyPositioningListener;
+    private _injector;
+    private _virtualScrollViewport;
+    private _positionListener;
     private _document;
     /** Latest data provided by the data source. */
     protected _data: readonly T[] | undefined;
+    /** Latest range of data rendered. */
+    protected _renderedRange?: ListRange;
     /** Subject that emits when the component has been destroyed. */
     private readonly _onDestroy;
     /** List of the rendered rows as identified by their `RenderRow` object. */
@@ -569,6 +576,17 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
     private _hasAllOutlets;
     /** Whether the table is done initializing. */
     private _hasInitialized;
+    /** Emits when the header rows sticky state changes. */
+    private readonly _headerRowStickyUpdates;
+    /** Emits when the footer rows sticky state changes. */
+    private readonly _footerRowStickyUpdates;
+    /**
+     * Whether to explicitly disable virtual scrolling even if there is a virtual scroll viewport
+     * parent. This can't be changed externally, whereas internally it is turned into an input that
+     * we use to opt out existing apps that were implementing virtual scroll before we added support
+     * for it.
+     */
+    private readonly _disableVirtualScrolling;
     /** Aria role to apply to the table's cells based on the table's own role. */
     _getCellRole(): string | null;
     private _cellRoleInternal;
@@ -604,6 +622,10 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
     get dataSource(): CdkTableDataSourceInput<T>;
     set dataSource(dataSource: CdkTableDataSourceInput<T>);
     private _dataSource;
+    /** Emits when the data source changes. */
+    readonly _dataSourceChanges: Subject<CdkTableDataSourceInput<T>>;
+    /** Observable that emits the data source's complete data set. */
+    readonly _dataStream: Subject<readonly T[]>;
     /**
      * Whether to allow multiple rows per data object by evaluating which rows evaluate their 'when'
      * predicate to true. If `multiTemplateDataRows` is false, which is the default value, then each
@@ -620,6 +642,11 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
     get fixedLayout(): boolean;
     set fixedLayout(value: boolean);
     private _fixedLayout;
+    /**
+     * Whether rows should be recycled which reduces latency, but is not compatible with tables
+     * that animate rows. Note that this input cannot change after the table is initialized.
+     */
+    recycleRows: boolean;
     /**
      * Emits when the table completes rendering a set of data rows based on the latest data from the
      * data source, even if the set of rows is empty.
@@ -631,10 +658,7 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
      *
      * @docs-private
      */
-    readonly viewChange: BehaviorSubject<{
-        start: number;
-        end: number;
-    }>;
+    readonly viewChange: BehaviorSubject<ListRange>;
     _rowOutlet: DataRowOutlet;
     _headerRowOutlet: HeaderRowOutlet;
     _footerRowOutlet: FooterRowOutlet;
@@ -652,7 +676,6 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
     _contentFooterRowDefs: QueryList<CdkFooterRowDef>;
     /** Row definition that will only be rendered if there's no data in the table. */
     _noDataRow: CdkNoDataRow;
-    private _injector;
     constructor(...args: unknown[]);
     ngOnInit(): void;
     ngAfterContentInit(): void;
@@ -711,6 +734,26 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
      * input. May be called manually for cases where the cell content changes outside of these events.
      */
     updateStickyColumnStyles(): void;
+    /**
+     * Implemented as a part of `StickyPositioningListener`.
+     * @docs-private
+     */
+    stickyColumnsUpdated(update: StickyUpdate): void;
+    /**
+     * Implemented as a part of `StickyPositioningListener`.
+     * @docs-private
+     */
+    stickyEndColumnsUpdated(update: StickyUpdate): void;
+    /**
+     * Implemented as a part of `StickyPositioningListener`.
+     * @docs-private
+     */
+    stickyHeaderRowsUpdated(update: StickyUpdate): void;
+    /**
+     * Implemented as a part of `StickyPositioningListener`.
+     * @docs-private
+     */
+    stickyFooterRowsUpdated(update: StickyUpdate): void;
     /** Invoked whenever an outlet is created and has been assigned to the table. */
     _outletAssigned(): void;
     /** Whether the table has all the information to start rendering. */
@@ -801,14 +844,22 @@ declare class CdkTable<T> implements AfterContentInit, AfterContentChecked, Coll
      * stickiness when directionality changes.
      */
     private _setupStickyStyler;
+    private _setupVirtualScrolling;
     /** Filters definitions that belong to this table from a QueryList. */
     private _getOwnDefs;
     /** Creates or removes the no data row, depending on whether any data is being shown. */
     private _updateNoDataRow;
+    /**
+     * Measures the size of the rendered range in the table.
+     * This is used for virtual scrolling when auto-sizing is enabled.
+     */
+    private _measureRangeSize;
+    private _virtualScrollEnabled;
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkTable<any>, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<CdkTable<any>, "cdk-table, table[cdk-table]", ["cdkTable"], { "trackBy": { "alias": "trackBy"; "required": false; }; "dataSource": { "alias": "dataSource"; "required": false; }; "multiTemplateDataRows": { "alias": "multiTemplateDataRows"; "required": false; }; "fixedLayout": { "alias": "fixedLayout"; "required": false; }; }, { "contentChanged": "contentChanged"; }, ["_noDataRow", "_contentColumnDefs", "_contentRowDefs", "_contentHeaderRowDefs", "_contentFooterRowDefs"], ["caption", "colgroup, col", "*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CdkTable<any>, "cdk-table, table[cdk-table]", ["cdkTable"], { "trackBy": { "alias": "trackBy"; "required": false; }; "dataSource": { "alias": "dataSource"; "required": false; }; "multiTemplateDataRows": { "alias": "multiTemplateDataRows"; "required": false; }; "fixedLayout": { "alias": "fixedLayout"; "required": false; }; "recycleRows": { "alias": "recycleRows"; "required": false; }; }, { "contentChanged": "contentChanged"; }, ["_noDataRow", "_contentColumnDefs", "_contentRowDefs", "_contentHeaderRowDefs", "_contentFooterRowDefs"], ["caption", "colgroup, col", "*"], true, never>;
     static ngAcceptInputType_multiTemplateDataRows: unknown;
     static ngAcceptInputType_fixedLayout: unknown;
+    static ngAcceptInputType_recycleRows: unknown;
 }
 
 /**

package/types/testing-testbed.d.ts

@@ -43,6 +43,9 @@ declare class TestbedHarnessEnvironment extends HarnessEnvironment<Element> {
     /**
      * Waits for all scheduled or running async tasks to complete. This allows harness
      * authors to wait for async tasks outside of the Angular zone.
+     *
+     * This only works when Zone.js is present _and_ patches are applied to the test framework
+     * by `zone.js/testing` (Jasmine and Jest only) or another script.
      */
     waitForTasksOutsideAngular(): Promise<void>;
     /** Gets the root element for the document. */