perf(cdk/overlay): add tree-shakeable alternatives for overlay APIs (#30904)

Currently all the overlay APIs go through the `Overlay` service which means that even if an app only uses the fairly simple global positioning strategy, they'd still bring in all the code for the complex flexible positioning strategy.

These changes break up the APIs into constructor functions that can be tree shaken separately.

Note that I'll send follow-up PRs to roll this out in Material in order to see the full benefits.

From a simple test of a an `ng new` app that only uses `MatTooltip`, this shaved off ~10kb of minified JS.

Author: crisbeto

goldens/cdk/overlay/index.api.md

@@ -197,6 +197,27 @@ export class ConnectionPositionPair {
     panelClass?: string | string[] | undefined;
 }
 
+// @public
+export function createBlockScrollStrategy(injector: Injector): BlockScrollStrategy;
+
+// @public
+export function createCloseScrollStrategy(injector: Injector, config?: CloseScrollStrategyConfig): CloseScrollStrategy;
+
+// @public
+export function createFlexibleConnectedPositionStrategy(injector: Injector, origin: FlexibleConnectedPositionStrategyOrigin): FlexibleConnectedPositionStrategy;
+
+// @public
+export function createGlobalPositionStrategy(_injector: Injector): GlobalPositionStrategy;
+
+// @public
+export function createNoopScrollStrategy(): NoopScrollStrategy;
+
+// @public
+export function createOverlayRef(injector: Injector, config?: OverlayConfig): OverlayRef;
+
+// @public
+export function createRepositionScrollStrategy(injector: Injector, config?: RepositionScrollStrategyConfig): RepositionScrollStrategy;
+
 // @public
 export class FlexibleConnectedPositionStrategy implements PositionStrategy {
     constructor(connectedTo: FlexibleConnectedPositionStrategyOrigin, _viewportRuler: ViewportRuler, _document: Document, _platform: Platform, _overlayContainer: OverlayContainer);

src/cdk/overlay/fullscreen-overlay-container.spec.ts

@@ -23,7 +23,7 @@ describe('FullscreenOverlayContainer', () => {
             // stubs here, we should reconsider whether to use a Proxy instead. Avoiding a proxy for
             // now since it isn't supported on IE. See:
             // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
-            fakeDocument = {
+            return {
               body: document.body,
               head: document.head,
               fullscreenElement: document.createElement('div'),
@@ -51,20 +51,15 @@ describe('FullscreenOverlayContainer', () => {
               createTextNode: (...args: [string]) => document.createTextNode(...args),
               createComment: (...args: [string]) => document.createComment(...args),
             };
-
-            return fakeDocument;
           },
         },
       ],
     });
 
     overlay = TestBed.inject(Overlay);
+    fakeDocument = TestBed.inject(DOCUMENT);
   }));
 
-  afterEach(() => {
-    fakeDocument = null;
-  });
-
   it('should open an overlay inside a fullscreen element and move it to the body', () => {
     const fixture = TestBed.createComponent(TestComponentWithTemplatePortals);
     fixture.detectChanges();

src/cdk/overlay/overlay.ts

@@ -19,6 +19,7 @@ import {
   inject,
   RendererFactory2,
   DOCUMENT,
+  Renderer2,
 } from '@angular/core';
 import {_IdGenerator} from '../a11y';
 import {_CdkPrivateStyleLoader} from '../private';
@@ -30,6 +31,56 @@ import {OverlayRef} from './overlay-ref';
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
 import {ScrollStrategyOptions} from './scroll/index';
 
+/**
+ * Creates an overlay.
+ * @param injector Injector to use when resolving the overlay's dependencies.
+ * @param config Configuration applied to the overlay.
+ * @returns Reference to the created overlay.
+ */
+export function createOverlayRef(injector: Injector, config?: OverlayConfig): OverlayRef {
+  // This is done in the overlay container as well, but we have it here
+  // since it's common to mock out the overlay container in tests.
+  injector.get(_CdkPrivateStyleLoader).load(_CdkOverlayStyleLoader);
+
+  const overlayContainer = injector.get(OverlayContainer);
+  const doc = injector.get(DOCUMENT);
+  const idGenerator = injector.get(_IdGenerator);
+  const appRef = injector.get(ApplicationRef);
+  const directionality = injector.get(Directionality);
+
+  const host = doc.createElement('div');
+  const pane = doc.createElement('div');
+
+  pane.id = idGenerator.getId('cdk-overlay-');
+  pane.classList.add('cdk-overlay-pane');
+  host.appendChild(pane);
+  overlayContainer.getContainerElement().appendChild(host);
+
+  const portalOutlet = new DomPortalOutlet(pane, appRef, injector);
+  const overlayConfig = new OverlayConfig(config);
+  const renderer =
+    injector.get(Renderer2, null, {optional: true}) ||
+    injector.get(RendererFactory2).createRenderer(null, null);
+
+  overlayConfig.direction = overlayConfig.direction || directionality.value;
+
+  return new OverlayRef(
+    portalOutlet,
+    host,
+    pane,
+    overlayConfig,
+    injector.get(NgZone),
+    injector.get(OverlayKeyboardDispatcher),
+    doc,
+    injector.get(Location),
+    injector.get(OverlayOutsideClickDispatcher),
+    config?.disableAnimations ??
+      injector.get(ANIMATION_MODULE_TYPE, null, {optional: true}) === 'NoopAnimations',
+    injector.get(EnvironmentInjector),
+    renderer,
+  );
+}
+
 /**
  * Service to create Overlays. Overlays are dynamically added pieces of floating UI, meant to be
  * used as a low-level building block for other components. Dialogs, tooltips, menus,
@@ -41,21 +92,8 @@ import {ScrollStrategyOptions} from './scroll/index';
 @Injectable({providedIn: 'root'})
 export class Overlay {
   scrollStrategies = inject(ScrollStrategyOptions);
-  private _overlayContainer = inject(OverlayContainer);
   private _positionBuilder = inject(OverlayPositionBuilder);
-  private _keyboardDispatcher = inject(OverlayKeyboardDispatcher);
   private _injector = inject(Injector);
-  private _ngZone = inject(NgZone);
-  private _document = inject(DOCUMENT);
-  private _directionality = inject(Directionality);
-  private _location = inject(Location);
-  private _outsideClickDispatcher = inject(OverlayOutsideClickDispatcher);
-  private _animationsModuleType = inject(ANIMATION_MODULE_TYPE, {optional: true});
-  private _idGenerator = inject(_IdGenerator);
-  private _renderer = inject(RendererFactory2).createRenderer(null, null);
-
-  private _appRef: ApplicationRef;
-  private _styleLoader = inject(_CdkPrivateStyleLoader);
 
   constructor(...args: unknown[]);
   constructor() {}
@@ -66,31 +104,7 @@ export class Overlay {
    * @returns Reference to the created overlay.
    */
   create(config?: OverlayConfig): OverlayRef {
-    // This is done in the overlay container as well, but we have it here
-    // since it's common to mock out the overlay container in tests.
-    this._styleLoader.load(_CdkOverlayStyleLoader);
-
-    const host = this._createHostElement();
-    const pane = this._createPaneElement(host);
-    const portalOutlet = this._createPortalOutlet(pane);
-    const overlayConfig = new OverlayConfig(config);
-
-    overlayConfig.direction = overlayConfig.direction || this._directionality.value;
-
-    return new OverlayRef(
-      portalOutlet,
-      host,
-      pane,
-      overlayConfig,
-      this._ngZone,
-      this._keyboardDispatcher,
-      this._document,
-      this._location,
-      this._outsideClickDispatcher,
-      config?.disableAnimations ?? this._animationsModuleType === 'NoopAnimations',
-      this._injector.get(EnvironmentInjector),
-      this._renderer,
-    );
+    return createOverlayRef(this._injector, config);
   }
 
   /**
@@ -101,44 +115,4 @@ export class Overlay {
   position(): OverlayPositionBuilder {
     return this._positionBuilder;
   }
-
-  /**
-   * Creates the DOM element for an overlay and appends it to the overlay container.
-   * @returns Newly-created pane element
-   */
-  private _createPaneElement(host: HTMLElement): HTMLElement {
-    const pane = this._document.createElement('div');
-
-    pane.id = this._idGenerator.getId('cdk-overlay-');
-    pane.classList.add('cdk-overlay-pane');
-    host.appendChild(pane);
-
-    return pane;
-  }
-
-  /**
-   * Creates the host element that wraps around an overlay
-   * and can be used for advanced positioning.
-   * @returns Newly-create host element.
-   */
-  private _createHostElement(): HTMLElement {
-    const host = this._document.createElement('div');
-    this._overlayContainer.getContainerElement().appendChild(host);
-    return host;
-  }
-
-  /**
-   * Create a DomPortalOutlet into which the overlay content can be loaded.
-   * @param pane The DOM element to turn into a portal outlet.
-   * @returns A portal outlet for the given DOM element.
-   */
-  private _createPortalOutlet(pane: HTMLElement): DomPortalOutlet {
-    // We have to resolve the ApplicationRef later in order to allow people
-    // to use overlay-based providers during app initialization.
-    if (!this._appRef) {
-      this._appRef = this._injector.get<ApplicationRef>(ApplicationRef);
-    }
-
-    return new DomPortalOutlet(pane, this._appRef, this._injector);
-  }
 }

src/cdk/overlay/position/flexible-connected-position-strategy.ts

@@ -7,7 +7,7 @@
  */
 
 import {PositionStrategy} from './position-strategy';
-import {ElementRef} from '@angular/core';
+import {DOCUMENT, ElementRef, Injector} from '@angular/core';
 import {ViewportRuler, CdkScrollable, ViewportScrollPosition} from '../../scrolling';
 import {
   ConnectedOverlayPositionChange,
@@ -44,6 +44,24 @@ export type FlexibleConnectedPositionStrategyOrigin =
 /** Equivalent of `DOMRect` without some of the properties we don't care about. */
 type Dimensions = Omit<DOMRect, 'x' | 'y' | 'toJSON'>;
 
+/**
+ * Creates a flexible position strategy.
+ * @param injector Injector used to resolve dependnecies for the position strategy.
+ * @param origin Origin relative to which to position the overlay.
+ */
+export function createFlexibleConnectedPositionStrategy(
+  injector: Injector,
+  origin: FlexibleConnectedPositionStrategyOrigin,
+): FlexibleConnectedPositionStrategy {
+  return new FlexibleConnectedPositionStrategy(
+    origin,
+    injector.get(ViewportRuler),
+    injector.get(DOCUMENT),
+    injector.get(Platform),
+    injector.get(OverlayContainer),
+  );
+}
+
 /**
  * A strategy for positioning overlays. Using this strategy, an overlay is given an
  * implicit position relative some origin element. The relative position is defined in terms of

src/cdk/overlay/position/global-position-strategy.ts

@@ -6,12 +6,23 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {Injector} from '@angular/core';
 import {OverlayRef} from '../overlay-ref';
 import {PositionStrategy} from './position-strategy';
 
 /** Class to be added to the overlay pane wrapper. */
 const wrapperClass = 'cdk-global-overlay-wrapper';
 
+/**
+ * Creates a global position strategy.
+ * @param injector Injector used to resolve dependencies for the strategy.
+ */
+export function createGlobalPositionStrategy(_injector: Injector): GlobalPositionStrategy {
+  // Note: `injector` is unused, but we may need it in
+  // the future which would introduce a breaking change.
+  return new GlobalPositionStrategy();
+}
+
 /**
  * A strategy for positioning overlays. Using this strategy, an overlay is given an
  * explicit position relative to the browser's viewport. We use flexbox, instead of

src/cdk/overlay/position/overlay-position-builder.ts

@@ -6,24 +6,18 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Platform} from '../../platform';
-import {ViewportRuler} from '../../scrolling';
-
-import {Injectable, inject, DOCUMENT} from '@angular/core';
-import {OverlayContainer} from '../overlay-container';
+import {Injectable, Injector, inject} from '@angular/core';
 import {
+  createFlexibleConnectedPositionStrategy,
   FlexibleConnectedPositionStrategy,
   FlexibleConnectedPositionStrategyOrigin,
 } from './flexible-connected-position-strategy';
-import {GlobalPositionStrategy} from './global-position-strategy';
+import {createGlobalPositionStrategy, GlobalPositionStrategy} from './global-position-strategy';
 
 /** Builder for overlay position strategy. */
 @Injectable({providedIn: 'root'})
 export class OverlayPositionBuilder {
-  private _viewportRuler = inject(ViewportRuler);
-  private _document = inject(DOCUMENT);
-  private _platform = inject(Platform);
-  private _overlayContainer = inject(OverlayContainer);
+  private _injector = inject(Injector);
 
   constructor(...args: unknown[]);
   constructor() {}
@@ -32,7 +26,7 @@ export class OverlayPositionBuilder {
    * Creates a global position strategy.
    */
   global(): GlobalPositionStrategy {
-    return new GlobalPositionStrategy();
+    return createGlobalPositionStrategy(this._injector);
   }
 
   /**
@@ -42,12 +36,6 @@ export class OverlayPositionBuilder {
   flexibleConnectedTo(
     origin: FlexibleConnectedPositionStrategyOrigin,
   ): FlexibleConnectedPositionStrategy {
-    return new FlexibleConnectedPositionStrategy(
-      origin,
-      this._viewportRuler,
-      this._document,
-      this._platform,
-      this._overlayContainer,
-    );
+    return createFlexibleConnectedPositionStrategy(this._injector, origin);
   }
 }

src/cdk/overlay/public-api.ts

@@ -11,7 +11,7 @@ export * from './position/connected-position';
 export * from './scroll/index';
 export * from './overlay-module';
 export * from './dispatchers/index';
-export {Overlay} from './overlay';
+export {Overlay, createOverlayRef} from './overlay';
 export {OverlayContainer} from './overlay-container';
 export {CdkOverlayOrigin, CdkConnectedOverlay} from './overlay-directives';
 export {FullscreenOverlayContainer} from './fullscreen-overlay-container';
@@ -22,11 +22,15 @@ export {OverlayPositionBuilder} from './position/overlay-position-builder';
 
 // Export pre-defined position strategies and interface to build custom ones.
 export {PositionStrategy} from './position/position-strategy';
-export {GlobalPositionStrategy} from './position/global-position-strategy';
+export {
+  GlobalPositionStrategy,
+  createGlobalPositionStrategy,
+} from './position/global-position-strategy';
 export {
   ConnectedPosition,
   FlexibleConnectedPositionStrategy,
   FlexibleConnectedPositionStrategyOrigin,
   STANDARD_DROPDOWN_ADJACENT_POSITIONS,
   STANDARD_DROPDOWN_BELOW_POSITIONS,
+  createFlexibleConnectedPositionStrategy,
 } from './position/flexible-connected-position-strategy';

src/cdk/overlay/scroll/block-scroll-strategy.ts

@@ -6,13 +6,23 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {DOCUMENT, Injector} from '@angular/core';
 import {ScrollStrategy} from './scroll-strategy';
 import {ViewportRuler} from '../../scrolling';
 import {coerceCssPixelValue} from '../../coercion';
 import {supportsScrollBehavior} from '../../platform';
 
 const scrollBehaviorSupported = supportsScrollBehavior();
 
+/**
+ * Creates a scroll strategy that prevents the user from scrolling while the overlay is open.
+ * @param injector Injector used to resolve dependencies of the scroll strategy.
+ * @param config Configuration options for the scroll strategy.
+ */
+export function createBlockScrollStrategy(injector: Injector): BlockScrollStrategy {
+  return new BlockScrollStrategy(injector.get(ViewportRuler), injector.get(DOCUMENT));
+}
+
 /**
  * Strategy that will prevent the user from scrolling while the overlay is visible.
  */