feat(core): Redesign the afterRender & afterNextRender phases API (#55648)

Previously `afterRender` and `afterNextRender` allowed the user to pass
a phase to run the callback in as part of the `AfterRenderOptions`. This
worked, but made it cumbersome to coordinate work between phases.

```ts
let size: DOMRect|null = null;

afterRender(() => {
  size = nativeEl.getBoundingClientRect();
}, {phase: AfterRenderPhase.EarlyRead});

afterRender(() => {
  otherNativeEl.style.width = size!.width + 'px';
}, {phase: AfterRenderPhase.Write});
```

This PR replaces the old phases API with a new one that allows passing a
callback per phase in a single `afterRender` / `afterNextRender` call.
The return value of each phase's callback is passed to the subsequent
callbacks that were part of that `afterRender` call.

```ts
afterRender({
  earlyRead: () => nativeEl.getBoundingClientRect(),
  write: (rect) => {
    otherNativeEl.style.width = rect.width + 'px';
  }
});
```

This API also retains the ability to pass a single callback, which will
be run in the `mixedReadWrite` phase.

```ts
afterRender(() => {
  // read some stuff ...
  // write some stuff ...
});
```

PR Close #55648

Author: mmalerba

Diff for: adev/src/content/guide/components/lifecycle.md

@@ -239,30 +239,42 @@ Render callbacks do not run during server-side rendering or during build-time pr
 
 #### afterRender phases
 
-When using `afterRender` or `afterNextRender`, you can optionally specify a `phase`. The phase
-gives you control over the sequencing of DOM operations, letting you sequence _write_ operations
-before _read_ operations in order to minimize
-[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing).
+When using `afterRender` or `afterNextRender`, you can optionally split the work into phases. The
+phase gives you control over the sequencing of DOM operations, letting you sequence _write_
+operations before _read_ operations in order to minimize
+[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). In order to
+communicate across phases, a phase function may return a result value that can be accessed in the
+next phase.
 
 ```ts
-import {Component, ElementRef, afterNextRender, AfterRenderPhase} from '@angular/core';
+import {Component, ElementRef, afterNextRender} from '@angular/core';
 
 @Component({...})
 export class UserProfile {
+  private prevPadding = 0;
   private elementHeight = 0;
 
   constructor(elementRef: ElementRef) {
     const nativeElement = elementRef.nativeElement;
 
-    // Use the `Write` phase to write to a geometric property.
-    afterNextRender(() => {
-      nativeElement.style.padding = computePadding();
-    }, {phase: AfterRenderPhase.Write});
-
-    // Use the `Read` phase to read geometric properties after all writes have occurred.
-    afterNextRender(() => {
-      this.elementHeight = nativeElement.getBoundingClientRect().height;
-    }, {phase: AfterRenderPhase.Read});
+    afterNextRender({
+      // Use the `Write` phase to write to a geometric property.
+      write: () => {
+        const padding = computePadding();
+        const changed = padding !== prevPadding;
+        if (changed) {
+          nativeElement.style.padding = padding;
+        }
+        return changed; // Communicate whether anything changed to the read phase.
+      },
+
+      // Use the `Read` phase to read geometric properties after all writes have occurred.
+      read: (didWrite) => {
+        if (didWrite) {
+          this.elementHeight = nativeElement.getBoundingClientRect().height;
+        }
+      }
+    });
   }
 }
 ```
@@ -271,10 +283,10 @@ There are four phases, run in the following order:
 
 | Phase            | Description                                                                                                                                                                                           |
 | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `EarlyRead`      | Use this phase to read any layout-affecting DOM properties and styles that are strictly necessary for subsequent calculation. Avoid this phase if possible, preferring the `Write` and `Read` phases. |
-| `MixedReadWrite` | Default phase. Use for any operations need to both read and write layout-affecting properties and styles. Avoid this phase if possible, preferring the explicit `Write` and `Read` phases.            |
-| `Write`          | Use this phase to write layout-affecting DOM properties and styles.                                                                                                                                   |
-| `Read`           | Use this phase to read any layout-affecting DOM properties.                                                                                                                                           |
+| `earlyRead`      | Use this phase to read any layout-affecting DOM properties and styles that are strictly necessary for subsequent calculation. Avoid this phase if possible, preferring the `write` and `read` phases. |
+| `mixedReadWrite` | Default phase. Use for any operations need to both read and write layout-affecting properties and styles. Avoid this phase if possible, preferring the explicit `write` and `read` phases.            |
+| `write`          | Use this phase to write layout-affecting DOM properties and styles.                                                                                                                                   |
+| `read`           | Use this phase to read any layout-affecting DOM properties.                                                                                                                                           |
 
 ## Lifecycle interfaces
 

Diff for: goldens/public-api/core/index.api.md

@@ -27,24 +27,31 @@ export interface AfterContentInit {
     ngAfterContentInit(): void;
 }
 
+// @public
+export function afterNextRender<E = never, W = never, M = never>(spec: {
+    earlyRead?: () => E;
+    write?: (...args: ɵFirstAvailable<[E]>) => W;
+    mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
+    read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
+}, opts?: AfterRenderOptions): AfterRenderRef;
+
 // @public
 export function afterNextRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
 
+// @public
+export function afterRender<E = never, W = never, M = never>(spec: {
+    earlyRead?: () => E;
+    write?: (...args: ɵFirstAvailable<[E]>) => W;
+    mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
+    read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
+}, opts?: AfterRenderOptions): AfterRenderRef;
+
 // @public
 export function afterRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
 
 // @public
 export interface AfterRenderOptions {
     injector?: Injector;
-    phase?: AfterRenderPhase;
-}
-
-// @public
-export enum AfterRenderPhase {
-    EarlyRead = 0,
-    MixedReadWrite = 2,
-    Read = 3,
-    Write = 1
 }
 
 // @public

Diff for: packages/core/src/core.ts

@@ -101,9 +101,9 @@ export {isStandalone} from './render3/definition';
 export {
   AfterRenderRef,
   AfterRenderOptions,
-  AfterRenderPhase,
   afterRender,
   afterNextRender,
+  ɵFirstAvailable,
 } from './render3/after_render_hooks';
 export {ApplicationConfig, mergeApplicationConfig} from './application/application_config';
 export {makeStateKey, StateKey, TransferState} from './transfer_state';

Diff for: packages/core/src/render3/after_render_hooks.ts

@@ -10,7 +10,7 @@ import {
   ChangeDetectionScheduler,
   NotificationSource,
 } from '../change_detection/scheduling/zoneless_scheduling';
-import {assertInInjectionContext, Injector, runInInjectionContext, ɵɵdefineInjectable} from '../di';
+import {Injector, assertInInjectionContext, runInInjectionContext, ɵɵdefineInjectable} from '../di';
 import {inject} from '../di/injector_compatibility';
 import {ErrorHandler} from '../error_handler';
 import {DestroyRef} from '../linker/destroy_ref';
@@ -20,6 +20,16 @@ import {NgZone} from '../zone/ng_zone';
 
 import {isPlatformBrowser} from './util/misc_utils';
 
+/**
+ * An argument list containing the first non-never type in the given type array, or an empty
+ * argument list if there are no non-never types in the type array.
+ */
+export type ɵFirstAvailable<T extends unknown[]> = T extends [infer H, ...infer R]
+  ? [H] extends [never]
+    ? ɵFirstAvailable<R>
+    : [H]
+  : [];
+
 /**
  * The phase to run an `afterRender` or `afterNextRender` callback in.
  *
@@ -37,15 +47,14 @@ import {isPlatformBrowser} from './util/misc_utils';
  * so, Angular is better able to minimize the performance degradation associated with
  * manual DOM access, ensuring the best experience for the end users of your application
  * or library.
- *
- * @developerPreview
  */
-export enum AfterRenderPhase {
+enum AfterRenderPhase {
   /**
    * Use `AfterRenderPhase.EarlyRead` for callbacks that only need to **read** from the
    * DOM before a subsequent `AfterRenderPhase.Write` callback, for example to perform
-   * custom layout that the browser doesn't natively support. **Never** use this phase
-   * for callbacks that can write to the DOM or when `AfterRenderPhase.Read` is adequate.
+   * custom layout that the browser doesn't natively support. Prefer the
+   * `AfterRenderPhase.EarlyRead` phase if reading can wait until after the write phase.
+   * **Never** write to the DOM in this phase.
    *
    * <div class="alert is-important">
    *
@@ -58,27 +67,27 @@ export enum AfterRenderPhase {
 
   /**
    * Use `AfterRenderPhase.Write` for callbacks that only **write** to the DOM. **Never**
-   * use this phase for callbacks that can read from the DOM.
+   * read from the DOM in this phase.
    */
   Write,
 
   /**
    * Use `AfterRenderPhase.MixedReadWrite` for callbacks that read from or write to the
-   * DOM, that haven't been refactored to use a different phase. **Never** use this phase
-   * for callbacks that can use a different phase instead.
+   * DOM, that haven't been refactored to use a different phase. **Never** use this phase if
+   * it is possible to divide the work among the other phases instead.
    *
    * <div class="alert is-critical">
    *
    * Using this value can **significantly** degrade performance.
-   * Instead, prefer refactoring into multiple callbacks using a more specific phase.
+   * Instead, prefer dividing work into the appropriate phase callbacks.
    *
    * </div>
    */
   MixedReadWrite,
 
   /**
    * Use `AfterRenderPhase.Read` for callbacks that only **read** from the DOM. **Never**
-   * use this phase for callbacks that can write to the DOM.
+   * write to the DOM in this phase.
    */
   Read,
 }
@@ -95,18 +104,6 @@ export interface AfterRenderOptions {
    * If this is not provided, the current injection context will be used instead (via `inject`).
    */
   injector?: Injector;
-
-  /**
-   * The phase the callback should be invoked in.
-   *
-   * <div class="alert is-critical">
-   *
-   * Defaults to `AfterRenderPhase.MixedReadWrite`. You should choose a more specific
-   * phase instead. See `AfterRenderPhase` for more information.
-   *
-   * </div>
-   */
-  phase?: AfterRenderPhase;
 }
 
 /**
@@ -174,20 +171,107 @@ export function internalAfterNextRender(
 }
 
 /**
- * Register a callback to be invoked each time the application
- * finishes rendering.
+ * Register callbacks to be invoked each time the application finishes rendering, during the
+ * specified phases. The available phases are:
+ * - `earlyRead`
+ *   Use this phase to **read** from the DOM before a subsequent `write` callback, for example to
+ *   perform custom layout that the browser doesn't natively support. Prefer the `read` phase if
+ *   reading can wait until after the write phase. **Never** write to the DOM in this phase.
+ * - `write`
+ *    Use this phase to **write** to the DOM. **Never** read from the DOM in this phase.
+ * - `mixedReadWrite`
+ *    Use this phase to read from and write to the DOM simultaneously. **Never** use this phase if
+ *    it is possible to divide the work among the other phases instead.
+ * - `read`
+ *    Use this phase to **read** from the DOM. **Never** write to the DOM in this phase.
+ *
+ * <div class="alert is-critical">
+ *
+ * You should prefer using the `read` and `write` phases over the `earlyRead` and `mixedReadWrite`
+ * phases when possible, to avoid performance degradation.
+ *
+ * </div>
+ *
+ * Note that:
+ * - Callbacks run in the following phase order *after each render*:
+ *   1. `earlyRead`
+ *   2. `write`
+ *   3. `mixedReadWrite`
+ *   4. `read`
+ * - Callbacks in the same phase run in the order they are registered.
+ * - Callbacks run on browser platforms only, they will not run on the server.
+ *
+ * The first phase callback to run as part of this spec will receive no parameters. Each
+ * subsequent phase callback in this spec will receive the return value of the previously run
+ * phase callback as a parameter. This can be used to coordinate work across multiple phases.
+ *
+ * Angular is unable to verify or enforce that phases are used correctly, and instead
+ * relies on each developer to follow the guidelines documented for each value and
+ * carefully choose the appropriate one, refactoring their code if necessary. By doing
+ * so, Angular is better able to minimize the performance degradation associated with
+ * manual DOM access, ensuring the best experience for the end users of your application
+ * or library.
+ *
+ * <div class="alert is-important">
+ *
+ * Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
+ * You must use caution when directly reading or writing the DOM and layout.
+ *
+ * </div>
+ *
+ * @param spec The callback functions to register
+ *
+ * @usageNotes
+ *
+ * Use `afterRender` to read or write the DOM after each render.
+ *
+ * ### Example
+ * ```ts
+ * @Component({
+ *   selector: 'my-cmp',
+ *   template: `<span #content>{{ ... }}</span>`,
+ * })
+ * export class MyComponent {
+ *   @ViewChild('content') contentRef: ElementRef;
+ *
+ *   constructor() {
+ *     afterRender({
+ *       read: () => {
+ *         console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @developerPreview
+ */
+export function afterRender<E = never, W = never, M = never>(
+  spec: {
+    earlyRead?: () => E;
+    write?: (...args: ɵFirstAvailable<[E]>) => W;
+    mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
+    read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
+  },
+  opts?: AfterRenderOptions,
+): AfterRenderRef;
+
+/**
+ * Register a callback to be invoked each time the application finishes rendering, during the
+ * `mixedReadWrite` phase.
  *
  * <div class="alert is-critical">
  *
- * You should always explicitly specify a non-default [phase](api/core/AfterRenderPhase), or you
- * risk significant performance degradation.
+ * You should prefer specifying an explicit phase for the callback instead, or you risk significant
+ * performance degradation.
  *
  * </div>
  *
  * Note that the callback will run
  * - in the order it was registered
  * - once per render
  * - on browser platforms only
+ * - during the `mixedReadWrite` phase
  *
  * <div class="alert is-important">
  *
@@ -212,16 +296,30 @@ export function internalAfterNextRender(
  *   @ViewChild('content') contentRef: ElementRef;
  *
  *   constructor() {
- *     afterRender(() => {
- *       console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
- *     }, {phase: AfterRenderPhase.Read});
+ *     afterRender({
+ *       read: () => {
+ *         console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
+ *       }
+ *     });
  *   }
  * }
  * ```
  *
  * @developerPreview
  */
-export function afterRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef {
+export function afterRender(callback: VoidFunction, options?: AfterRenderOptions): AfterRenderRef;
+
+export function afterRender(
+  callbackOrSpec:
+    | VoidFunction
+    | {
+        earlyRead?: () => unknown;
+        write?: (r?: unknown) => unknown;
+        mixedReadWrite?: (r?: unknown) => unknown;
+        read?: (r?: unknown) => void;
+      },
+  options?: AfterRenderOptions,
+): AfterRenderRef {
   ngDevMode &&
     assertNotInReactiveContext(
       afterRender,
@@ -238,37 +336,112 @@ export function afterRender(callback: VoidFunction, options?: AfterRenderOptions
 
   performanceMarkFeature('NgAfterRender');
 
-  const afterRenderEventManager = injector.get(AfterRenderEventManager);
-  // Lazily initialize the handler implementation, if necessary. This is so that it can be
-  // tree-shaken if `afterRender` and `afterNextRender` aren't used.
-  const callbackHandler = (afterRenderEventManager.handler ??=
-    new AfterRenderCallbackHandlerImpl());
-  const phase = options?.phase ?? AfterRenderPhase.MixedReadWrite;
-  const destroy = () => {
-    callbackHandler.unregister(instance);
-    unregisterFn();
-  };
-  const unregisterFn = injector.get(DestroyRef).onDestroy(destroy);
-  const instance = runInInjectionContext(injector, () => new AfterRenderCallback(phase, callback));
-
-  callbackHandler.register(instance);
-  return {destroy};
+  return afterRenderImpl(callbackOrSpec, injector, /* once */ false);
 }
 
 /**
- * Register a callback to be invoked the next time the application
- * finishes rendering.
+ * Register callbacks to be invoked the next time the application finishes rendering, during the
+ * specified phases. The available phases are:
+ * - `earlyRead`
+ *   Use this phase to **read** from the DOM before a subsequent `write` callback, for example to
+ *   perform custom layout that the browser doesn't natively support. Prefer the `read` phase if
+ *   reading can wait until after the write phase. **Never** write to the DOM in this phase.
+ * - `write`
+ *    Use this phase to **write** to the DOM. **Never** read from the DOM in this phase.
+ * - `mixedReadWrite`
+ *    Use this phase to read from and write to the DOM simultaneously. **Never** use this phase if
+ *    it is possible to divide the work among the other phases instead.
+ * - `read`
+ *    Use this phase to **read** from the DOM. **Never** write to the DOM in this phase.
+ *
+ * <div class="alert is-critical">
+ *
+ * You should prefer using the `read` and `write` phases over the `earlyRead` and `mixedReadWrite`
+ * phases when possible, to avoid performance degradation.
+ *
+ * </div>
+ *
+ * Note that:
+ * - Callbacks run in the following phase order *once, after the next render*:
+ *   1. `earlyRead`
+ *   2. `write`
+ *   3. `mixedReadWrite`
+ *   4. `read`
+ * - Callbacks in the same phase run in the order they are registered.
+ * - Callbacks run on browser platforms only, they will not run on the server.
+ *
+ * The first phase callback to run as part of this spec will receive no parameters. Each
+ * subsequent phase callback in this spec will receive the return value of the previously run
+ * phase callback as a parameter. This can be used to coordinate work across multiple phases.
+ *
+ * Angular is unable to verify or enforce that phases are used correctly, and instead
+ * relies on each developer to follow the guidelines documented for each value and
+ * carefully choose the appropriate one, refactoring their code if necessary. By doing
+ * so, Angular is better able to minimize the performance degradation associated with
+ * manual DOM access, ensuring the best experience for the end users of your application
+ * or library.
+ *
+ * <div class="alert is-important">
+ *
+ * Components are not guaranteed to be [hydrated](guide/hydration) before the callback runs.
+ * You must use caution when directly reading or writing the DOM and layout.
+ *
+ * </div>
+ *
+ * @param spec The callback functions to register
+ *
+ * @usageNotes
+ *
+ * Use `afterNextRender` to read or write the DOM once,
+ * for example to initialize a non-Angular library.
+ *
+ * ### Example
+ * ```ts
+ * @Component({
+ *   selector: 'my-chart-cmp',
+ *   template: `<div #chart>{{ ... }}</div>`,
+ * })
+ * export class MyChartCmp {
+ *   @ViewChild('chart') chartRef: ElementRef;
+ *   chart: MyChart|null;
+ *
+ *   constructor() {
+ *     afterNextRender({
+ *       write: () => {
+ *         this.chart = new MyChart(this.chartRef.nativeElement);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @developerPreview
+ */
+export function afterNextRender<E = never, W = never, M = never>(
+  spec: {
+    earlyRead?: () => E;
+    write?: (...args: ɵFirstAvailable<[E]>) => W;
+    mixedReadWrite?: (...args: ɵFirstAvailable<[W, E]>) => M;
+    read?: (...args: ɵFirstAvailable<[M, W, E]>) => void;
+  },
+  opts?: AfterRenderOptions,
+): AfterRenderRef;
+
+/**
+ * Register a callback to be invoked the next time the application finishes rendering, during the
+ * `mixedReadWrite` phase.
  *
  * <div class="alert is-critical">
  *
- * You should always explicitly specify a non-default [phase](api/core/AfterRenderPhase), or you
- * risk significant performance degradation.
+ * You should prefer specifying an explicit phase for the callback instead, or you risk significant
+ * performance degradation.
  *
  * </div>
  *
  * Note that the callback will run
  * - in the order it was registered
  * - on browser platforms only
+ * - during the `mixedReadWrite` phase
  *
  * <div class="alert is-important">
  *
@@ -295,9 +468,11 @@ export function afterRender(callback: VoidFunction, options?: AfterRenderOptions
  *   chart: MyChart|null;
  *
  *   constructor() {
- *     afterNextRender(() => {
- *       this.chart = new MyChart(this.chartRef.nativeElement);
- *     }, {phase: AfterRenderPhase.Write});
+ *     afterNextRender({
+ *       write: () => {
+ *         this.chart = new MyChart(this.chartRef.nativeElement);
+ *       }
+ *     });
  *   }
  * }
  * ```
@@ -307,6 +482,18 @@ export function afterRender(callback: VoidFunction, options?: AfterRenderOptions
 export function afterNextRender(
   callback: VoidFunction,
   options?: AfterRenderOptions,
+): AfterRenderRef;
+
+export function afterNextRender(
+  callbackOrSpec:
+    | VoidFunction
+    | {
+        earlyRead?: () => unknown;
+        write?: (r?: unknown) => unknown;
+        mixedReadWrite?: (r?: unknown) => unknown;
+        read?: (r?: unknown) => void;
+      },
+  options?: AfterRenderOptions,
 ): AfterRenderRef {
   !options && assertInInjectionContext(afterNextRender);
   const injector = options?.injector ?? inject(Injector);
@@ -317,27 +504,75 @@ export function afterNextRender(
 
   performanceMarkFeature('NgAfterNextRender');
 
+  return afterRenderImpl(callbackOrSpec, injector, /* once */ true);
+}
+
+/**
+ * Shared implementation for `afterRender` and `afterNextRender`.
+ */
+function afterRenderImpl(
+  callbackOrSpec:
+    | VoidFunction
+    | {
+        earlyRead?: () => unknown;
+        write?: (r?: unknown) => unknown;
+        mixedReadWrite?: (r?: unknown) => unknown;
+        read?: (r?: unknown) => void;
+      },
+  injector: Injector,
+  once: boolean,
+): AfterRenderRef {
+  const spec: {
+    earlyRead?: () => unknown;
+    write?: (r?: unknown) => unknown;
+    mixedReadWrite?: (r?: unknown) => unknown;
+    read?: (r?: unknown) => void;
+  } = callbackOrSpec instanceof Function ? {mixedReadWrite: callbackOrSpec} : callbackOrSpec;
+
   const afterRenderEventManager = injector.get(AfterRenderEventManager);
   // Lazily initialize the handler implementation, if necessary. This is so that it can be
   // tree-shaken if `afterRender` and `afterNextRender` aren't used.
   const callbackHandler = (afterRenderEventManager.handler ??=
     new AfterRenderCallbackHandlerImpl());
-  const phase = options?.phase ?? AfterRenderPhase.MixedReadWrite;
+
+  const pipelinedArgs: [] | [unknown] = [];
+  const instances: AfterRenderCallback[] = [];
+
   const destroy = () => {
-    callbackHandler.unregister(instance);
+    for (const instance of instances) {
+      callbackHandler.unregister(instance);
+    }
     unregisterFn();
   };
   const unregisterFn = injector.get(DestroyRef).onDestroy(destroy);
-  const instance = runInInjectionContext(
-    injector,
-    () =>
-      new AfterRenderCallback(phase, () => {
-        destroy();
-        callback();
-      }),
-  );
-
-  callbackHandler.register(instance);
+
+  const registerCallback = (
+    phase: AfterRenderPhase,
+    phaseCallback: undefined | ((...args: unknown[]) => unknown),
+  ) => {
+    if (!phaseCallback) {
+      return;
+    }
+    const callback = once
+      ? (...args: [unknown]) => {
+          destroy();
+          phaseCallback(...args);
+        }
+      : phaseCallback;
+
+    const instance = runInInjectionContext(
+      injector,
+      () => new AfterRenderCallback(phase, pipelinedArgs, callback),
+    );
+    callbackHandler.register(instance);
+    instances.push(instance);
+  };
+
+  registerCallback(AfterRenderPhase.EarlyRead, spec.earlyRead);
+  registerCallback(AfterRenderPhase.Write, spec.write);
+  registerCallback(AfterRenderPhase.MixedReadWrite, spec.mixedReadWrite);
+  registerCallback(AfterRenderPhase.Read, spec.read);
+
   return {destroy};
 }
 
@@ -350,15 +585,20 @@ class AfterRenderCallback {
 
   constructor(
     readonly phase: AfterRenderPhase,
-    private callbackFn: VoidFunction,
+    private pipelinedArgs: [] | [unknown],
+    private callbackFn: (...args: unknown[]) => unknown,
   ) {
     // Registering a callback will notify the scheduler.
     inject(ChangeDetectionScheduler, {optional: true})?.notify(NotificationSource.NewRenderHook);
   }
 
   invoke() {
     try {
-      this.zone.runOutsideAngular(this.callbackFn);
+      const result = this.zone.runOutsideAngular(() =>
+        this.callbackFn.apply(null, this.pipelinedArgs as [unknown]),
+      );
+      // Clear out the args and add the result which will be passed to the next phase.
+      this.pipelinedArgs.splice(0, this.pipelinedArgs.length, result);
     } catch (err) {
       this.errorHandler?.handleError(err);
     }

Diff for: packages/core/test/acceptance/after_render_hook_spec.ts

@@ -8,37 +8,36 @@
 
 import {PLATFORM_BROWSER_ID, PLATFORM_SERVER_ID} from '@angular/common/src/platform_id';
 import {
-  afterNextRender,
-  afterRender,
-  AfterRenderPhase,
   AfterRenderRef,
   ApplicationRef,
   ChangeDetectorRef,
   Component,
-  computed,
-  createComponent,
-  effect,
   ErrorHandler,
-  inject,
   Injector,
   NgZone,
   PLATFORM_ID,
-  signal,
   Type,
-  untracked,
   ViewContainerRef,
+  afterNextRender,
+  afterRender,
+  computed,
+  createComponent,
+  effect,
+  inject,
   ɵinternalAfterNextRender as internalAfterNextRender,
   ɵqueueStateUpdate as queueStateUpdate,
+  signal,
+  untracked,
 } from '@angular/core';
 import {NoopNgZone} from '@angular/core/src/zone/ng_zone';
 import {TestBed} from '@angular/core/testing';
 import {bootstrapApplication} from '@angular/platform-browser';
 import {withBody} from '@angular/private/testing';
 
-import {destroyPlatform} from '../../src/core';
-import {EnvironmentInjector} from '../../src/di';
 import {firstValueFrom} from 'rxjs';
 import {filter} from 'rxjs/operators';
+import {destroyPlatform} from '../../src/core';
+import {EnvironmentInjector} from '../../src/di';
 
 function createAndAttachComponent<T>(component: Type<T>) {
   const componentRef = createComponent(component, {
@@ -62,12 +61,11 @@ describe('after render hooks', () => {
         class Comp {
           constructor() {
             // Helper to register into each phase
-            function forEachPhase(fn: (phase: AfterRenderPhase) => void) {
-              for (const phase in AfterRenderPhase) {
-                const val = AfterRenderPhase[phase];
-                if (typeof val === 'number') {
-                  fn(val);
-                }
+            function forEachPhase(
+              fn: (phase: 'earlyRead' | 'write' | 'mixedReadWrite' | 'read') => void,
+            ) {
+              for (const phase of ['earlyRead', 'write', 'mixedReadWrite', 'read'] as const) {
+                fn(phase);
               }
             }
 
@@ -76,25 +74,23 @@ describe('after render hooks', () => {
             });
 
             forEachPhase((phase) =>
-              afterRender(
-                () => {
-                  log.push(`afterRender (${AfterRenderPhase[phase]})`);
+              afterRender({
+                [phase]: () => {
+                  log.push(`afterRender (${phase})`);
                 },
-                {phase},
-              ),
+              }),
             );
 
             internalAfterNextRender(() => {
               log.push('internalAfterNextRender #2');
             });
 
             forEachPhase((phase) =>
-              afterNextRender(
-                () => {
-                  log.push(`afterNextRender (${AfterRenderPhase[phase]})`);
+              afterNextRender({
+                [phase]: () => {
+                  log.push(`afterNextRender (${phase})`);
                 },
-                {phase},
-              ),
+              }),
             );
 
             internalAfterNextRender(() => {
@@ -118,24 +114,24 @@ describe('after render hooks', () => {
           'internalAfterNextRender #1',
           'internalAfterNextRender #2',
           'internalAfterNextRender #3',
-          'afterRender (EarlyRead)',
-          'afterNextRender (EarlyRead)',
-          'afterRender (Write)',
-          'afterNextRender (Write)',
-          'afterRender (MixedReadWrite)',
-          'afterNextRender (MixedReadWrite)',
-          'afterRender (Read)',
-          'afterNextRender (Read)',
+          'afterRender (earlyRead)',
+          'afterNextRender (earlyRead)',
+          'afterRender (write)',
+          'afterNextRender (write)',
+          'afterRender (mixedReadWrite)',
+          'afterNextRender (mixedReadWrite)',
+          'afterRender (read)',
+          'afterNextRender (read)',
         ]);
 
         // Running change detection again
         log.length = 0;
         TestBed.inject(ApplicationRef).tick();
         expect(log).toEqual([
-          'afterRender (EarlyRead)',
-          'afterRender (Write)',
-          'afterRender (MixedReadWrite)',
-          'afterRender (Read)',
+          'afterRender (earlyRead)',
+          'afterRender (write)',
+          'afterRender (mixedReadWrite)',
+          'afterRender (read)',
         ]);
       });
 
@@ -493,8 +489,10 @@ describe('after render hooks', () => {
         createAndAttachComponent(Comp);
 
         expect(zoneLog).toEqual([]);
-        TestBed.inject(ApplicationRef).tick();
-        expect(zoneLog).toEqual([false]);
+        TestBed.inject(NgZone).run(() => {
+          TestBed.inject(ApplicationRef).tick();
+          expect(zoneLog).toEqual([false]);
+        });
       });
 
       it('should propagate errors to the ErrorHandler', () => {
@@ -550,66 +548,58 @@ describe('after render hooks', () => {
         @Component({selector: 'comp-a'})
         class CompA {
           constructor() {
-            afterRender(
-              () => {
+            afterRender({
+              earlyRead: () => {
                 log.push('early-read-1');
               },
-              {phase: AfterRenderPhase.EarlyRead},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              write: () => {
                 log.push('write-1');
               },
-              {phase: AfterRenderPhase.Write},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              mixedReadWrite: () => {
                 log.push('mixed-read-write-1');
               },
-              {phase: AfterRenderPhase.MixedReadWrite},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              read: () => {
                 log.push('read-1');
               },
-              {phase: AfterRenderPhase.Read},
-            );
+            });
           }
         }
 
         @Component({selector: 'comp-b'})
         class CompB {
           constructor() {
-            afterRender(
-              () => {
+            afterRender({
+              read: () => {
                 log.push('read-2');
               },
-              {phase: AfterRenderPhase.Read},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              mixedReadWrite: () => {
                 log.push('mixed-read-write-2');
               },
-              {phase: AfterRenderPhase.MixedReadWrite},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              write: () => {
                 log.push('write-2');
               },
-              {phase: AfterRenderPhase.Write},
-            );
+            });
 
-            afterRender(
-              () => {
+            afterRender({
+              earlyRead: () => {
                 log.push('early-read-2');
               },
-              {phase: AfterRenderPhase.EarlyRead},
-            );
+            });
           }
         }
 
@@ -633,6 +623,96 @@ describe('after render hooks', () => {
         ]);
       });
 
+      it('should schedule callbacks for multiple phases at once', () => {
+        const log: string[] = [];
+
+        @Component({selector: 'comp'})
+        class Comp {
+          constructor() {
+            afterRender({
+              earlyRead: () => {
+                log.push('early-read-1');
+              },
+              write: () => {
+                log.push('write-1');
+              },
+              mixedReadWrite: () => {
+                log.push('mixed-read-write-1');
+              },
+              read: () => {
+                log.push('read-1');
+              },
+            });
+
+            afterRender(() => {
+              log.push('mixed-read-write-2');
+            });
+          }
+        }
+
+        TestBed.configureTestingModule({
+          declarations: [Comp],
+          ...COMMON_CONFIGURATION,
+        });
+        createAndAttachComponent(Comp);
+
+        expect(log).toEqual([]);
+        TestBed.inject(ApplicationRef).tick();
+        expect(log).toEqual([
+          'early-read-1',
+          'write-1',
+          'mixed-read-write-1',
+          'mixed-read-write-2',
+          'read-1',
+        ]);
+      });
+
+      it('should pass data between phases', () => {
+        const log: string[] = [];
+
+        @Component({selector: 'comp'})
+        class Comp {
+          constructor() {
+            afterRender({
+              earlyRead: () => 'earlyRead result',
+              write: (results) => {
+                log.push(`results for write: ${results}`);
+                return 5;
+              },
+              mixedReadWrite: (results) => {
+                log.push(`results for mixedReadWrite: ${results}`);
+                return undefined;
+              },
+              read: (results) => {
+                log.push(`results for read: ${results}`);
+              },
+            });
+
+            afterRender({
+              earlyRead: () => 'earlyRead 2 result',
+              read: (results) => {
+                log.push(`results for read 2: ${results}`);
+              },
+            });
+          }
+        }
+
+        TestBed.configureTestingModule({
+          declarations: [Comp],
+          ...COMMON_CONFIGURATION,
+        });
+        createAndAttachComponent(Comp);
+
+        expect(log).toEqual([]);
+        TestBed.inject(ApplicationRef).tick();
+        expect(log).toEqual([
+          'results for write: earlyRead result',
+          'results for mixedReadWrite: 5',
+          'results for read: undefined',
+          'results for read 2: earlyRead 2 result',
+        ]);
+      });
+
       describe('throw error inside reactive context', () => {
         it('inside template effect', () => {
           @Component({template: `{{someFn()}}`})
@@ -927,8 +1007,10 @@ describe('after render hooks', () => {
         createAndAttachComponent(Comp);
 
         expect(zoneLog).toEqual([]);
-        TestBed.inject(ApplicationRef).tick();
-        expect(zoneLog).toEqual([false]);
+        TestBed.inject(NgZone).run(() => {
+          TestBed.inject(ApplicationRef).tick();
+          expect(zoneLog).toEqual([false]);
+        });
       });
 
       it('should propagate errors to the ErrorHandler', () => {
@@ -984,66 +1066,58 @@ describe('after render hooks', () => {
         @Component({selector: 'comp-a'})
         class CompA {
           constructor() {
-            afterNextRender(
-              () => {
+            afterNextRender({
+              earlyRead: () => {
                 log.push('early-read-1');
               },
-              {phase: AfterRenderPhase.EarlyRead},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              write: () => {
                 log.push('write-1');
               },
-              {phase: AfterRenderPhase.Write},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              mixedReadWrite: () => {
                 log.push('mixed-read-write-1');
               },
-              {phase: AfterRenderPhase.MixedReadWrite},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              read: () => {
                 log.push('read-1');
               },
-              {phase: AfterRenderPhase.Read},
-            );
+            });
           }
         }
 
         @Component({selector: 'comp-b'})
         class CompB {
           constructor() {
-            afterNextRender(
-              () => {
+            afterNextRender({
+              read: () => {
                 log.push('read-2');
               },
-              {phase: AfterRenderPhase.Read},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              mixedReadWrite: () => {
                 log.push('mixed-read-write-2');
               },
-              {phase: AfterRenderPhase.MixedReadWrite},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              write: () => {
                 log.push('write-2');
               },
-              {phase: AfterRenderPhase.Write},
-            );
+            });
 
-            afterNextRender(
-              () => {
+            afterNextRender({
+              earlyRead: () => {
                 log.push('early-read-2');
               },
-              {phase: AfterRenderPhase.EarlyRead},
-            );
+            });
           }
         }