refactor(core): stop producing ng-reflect attributes by default (angular#60973)

BREAKING CHANGE:

This commit deprecates `ng-reflect-*` attributes and updates the runtime to stop producing them by default. Please refactor application and test code to avoid relying on `ng-reflect-*` attributes.

To enable a more seamless upgrade to v20, we've added the `provideNgReflectAttributes()` function (can be imported from the `@angular/core` package), which enables the mode in which Angular would be producing those attribites (in dev mode only). You can add the `provideNgReflectAttributes()` function to the list of providers within the bootstrap call.

PR Close angular#60973

Author: AndrewKushnir

goldens/public-api/core/index.api.md

@@ -1459,6 +1459,9 @@ export function provideExperimentalCheckNoChangesForDebug(options: {
     exhaustive?: boolean;
 }): _angular_core.EnvironmentProviders;
 
+// @public
+export function provideNgReflectAttributes(): EnvironmentProviders;
+
 // @public
 export function providePlatformInitializer(initializerFn: () => void): EnvironmentProviders;
 

packages/core/src/core.ts

@@ -123,6 +123,7 @@ export {makeStateKey, StateKey, TransferState} from './transfer_state';
 export {booleanAttribute, numberAttribute} from './util/coercion';
 export {REQUEST, REQUEST_CONTEXT, RESPONSE_INIT} from './application/platform_tokens';
 export {DOCUMENT} from './document';
+export {provideNgReflectAttributes} from './ng_reflect';
 
 import {global} from './util/global';
 if (typeof ngDevMode !== 'undefined' && ngDevMode) {

packages/core/src/ng_reflect.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {EnvironmentProviders, InjectionToken, makeEnvironmentProviders} from './di/index';
+
+/** Defines the default value of the `NG_REFLECT_ATTRS_FLAG` flag. */
+export const NG_REFLECT_ATTRS_FLAG_DEFAULT = false;
+
+/**
+ * Defines an internal flag that indicates whether the runtime code should be
+ * producing `ng-reflect-*` attributes.
+ */
+export const NG_REFLECT_ATTRS_FLAG = new InjectionToken<boolean>(
+  typeof ngDevMode === 'undefined' || ngDevMode ? 'NG_REFLECT_FLAG' : '',
+  {
+    providedIn: 'root',
+    factory: () => NG_REFLECT_ATTRS_FLAG_DEFAULT,
+  },
+);
+
+/**
+ * Enables the logic to produce `ng-reflect-*` attributes on elements with bindings.
+ *
+ * Note: this is a dev-mode only setting and it will have no effect in production mode.
+ * In production mode, the `ng-reflect-*` attributes are *never* produced by Angular.
+ *
+ * Important: using and relying on the `ng-reflect-*` attributes is not recommended,
+ * they are deprecated and only present for backwards compatibility. Angular will stop
+ * producing them in one of the future versions.
+ *
+ * @publicApi
+ */
+export function provideNgReflectAttributes(): EnvironmentProviders {
+  const providers =
+    typeof ngDevMode === 'undefined' || ngDevMode
+      ? [
+          {
+            provide: NG_REFLECT_ATTRS_FLAG,
+            useValue: true,
+          },
+        ]
+      : [];
+  return makeEnvironmentProviders(providers);
+}
+
+export function normalizeDebugBindingName(name: string) {
+  // Attribute names with `$` (eg `x-y$`) are valid per spec, but unsupported by some browsers
+  name = camelCaseToDashCase(name.replace(/[$@]/g, '_'));
+  return `ng-reflect-${name}`;
+}
+
+const CAMEL_CASE_REGEXP = /([A-Z])/g;
+
+function camelCaseToDashCase(input: string): string {
+  return input.replace(CAMEL_CASE_REGEXP, (...m: any[]) => '-' + m[1].toLowerCase());
+}
+
+export function normalizeDebugBindingValue(value: any): string {
+  try {
+    // Limit the size of the value as otherwise the DOM just gets polluted.
+    return value != null ? value.toString().slice(0, 30) : value;
+  } catch (e) {
+    return '[ERROR] Exception while trying to serialize the value';
+  }
+}

packages/core/src/render3/component_ref.ts

@@ -75,6 +75,7 @@ import {elementEndFirstCreatePass, elementStartFirstCreatePass} from './view/ele
 import {ViewRef} from './view_ref';
 import {createLView, createTView, getInitialLViewFlagsFromDef} from './view/construction';
 import {BINDING, Binding, DirectiveWithBindings} from './dynamic_bindings';
+import {NG_REFLECT_ATTRS_FLAG, NG_REFLECT_ATTRS_FLAG_DEFAULT} from '../ng_reflect';
 
 export class ComponentFactoryResolver extends AbstractComponentFactoryResolver {
   /**
@@ -163,10 +164,16 @@ function createRootLViewEnvironment(rootLViewInjector: Injector): LViewEnvironme
   const sanitizer = rootLViewInjector.get(Sanitizer, null);
   const changeDetectionScheduler = rootLViewInjector.get(ChangeDetectionScheduler, null);
 
+  let ngReflect = false;
+  if (typeof ngDevMode === 'undefined' || ngDevMode) {
+    ngReflect = rootLViewInjector.get(NG_REFLECT_ATTRS_FLAG, NG_REFLECT_ATTRS_FLAG_DEFAULT);
+  }
+
   return {
     rendererFactory,
     sanitizer,
     changeDetectionScheduler,
+    ngReflect,
   };
 }
 

packages/core/src/render3/instructions/shared.ts

@@ -18,7 +18,7 @@ import {
 } from '../../sanitization/sanitization';
 import {assertIndexInRange, assertNotSame} from '../../util/assert';
 import {escapeCommentText} from '../../util/dom';
-import {normalizeDebugBindingName, normalizeDebugBindingValue} from '../../util/ng_reflect';
+import {normalizeDebugBindingName, normalizeDebugBindingValue} from '../../ng_reflect';
 import {stringify} from '../../util/stringify';
 import {assertFirstCreatePass, assertLView} from '../assert';
 import {attachPatchData} from '../context_discovery';
@@ -43,6 +43,7 @@ import {SanitizerFn} from '../interfaces/sanitization';
 import {isComponentDef, isComponentHost} from '../interfaces/type_checks';
 import {
   CONTEXT,
+  ENVIRONMENT,
   FLAGS,
   HEADER_OFFSET,
   INJECTOR,
@@ -309,6 +310,10 @@ export function markDirtyIfOnPush(lView: LView, viewIndex: number): void {
 }
 
 function setNgReflectProperty(lView: LView, tNode: TNode, attrName: string, value: any) {
+  const environment = lView[ENVIRONMENT];
+  if (!environment.ngReflect) {
+    return;
+  }
   const element = getNativeByTNode(tNode, lView) as RElement | RComment;
   const renderer = lView[RENDERER];
   attrName = normalizeDebugBindingName(attrName);
@@ -334,7 +339,8 @@ function setNgReflectProperties(
   publicName: string,
   value: any,
 ) {
-  if (!(tNode.type & (TNodeType.AnyRNode | TNodeType.Container))) {
+  const environment = lView[ENVIRONMENT];
+  if (!environment.ngReflect || !(tNode.type & (TNodeType.AnyRNode | TNodeType.Container))) {
     return;
   }
 

packages/core/src/render3/interfaces/view.ts

@@ -381,6 +381,12 @@ export interface LViewEnvironment {
 
   /** Scheduler for change detection to notify when application state changes. */
   changeDetectionScheduler: ChangeDetectionScheduler | null;
+
+  /**
+   * Whether `ng-reflect-*` attributes should be produced in dev mode
+   * (always disabled in prod mode).
+   */
+  ngReflect: boolean;
 }
 
 /** Flags associated with an LView (saved in LView[FLAGS]) */

packages/core/src/util/ng_reflect.ts

@@ -44,6 +44,7 @@ import {global} from '../../src/util/global';
 import {TimerScheduler} from '@angular/core/src/defer/timer_scheduler';
 import {Console} from '../../src/console';
 import {formatRuntimeErrorCode, RuntimeErrorCode} from '../../src/errors';
+import {provideNgReflectAttributes} from '../../src/ng_reflect';
 
 /**
  * Clears all associated directive defs from a given component class.
@@ -213,7 +214,10 @@ function createFixture(template: string) {
 
 // Set `PLATFORM_ID` to a browser platform value to trigger defer loading
 // while running tests in Node.
-const COMMON_PROVIDERS = [{provide: PLATFORM_ID, useValue: PLATFORM_BROWSER_ID}];
+const COMMON_PROVIDERS = [
+  {provide: PLATFORM_ID, useValue: PLATFORM_BROWSER_ID},
+  provideNgReflectAttributes(),
+];
 
 describe('@defer', () => {
   beforeEach(() => {

packages/core/test/acceptance/defer_spec.ts

@@ -40,11 +40,13 @@ import {clearTranslations, loadTranslations} from '@angular/localize';
 import {By} from '@angular/platform-browser';
 import {expect} from '@angular/platform-browser/testing/src/matchers';
 import {BehaviorSubject} from 'rxjs';
+import {provideNgReflectAttributes} from '../../src/ng_reflect';
 
 describe('runtime i18n', () => {
   beforeEach(() => {
     TestBed.configureTestingModule({
       declarations: [AppComp, DirectiveWithTplRef, UppercasePipe],
+      providers: [provideNgReflectAttributes()],
       // In some of the tests we use made-up tag names for better readability, however
       // they'll cause validation errors. Add the `NO_ERRORS_SCHEMA` so that we don't have
       // to declare dummy components for each one of them.

packages/core/test/acceptance/i18n_spec.ts

@@ -6,7 +6,14 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Component, Injector, TemplateRef, ViewChild, ViewContainerRef} from '../../src/core';
+import {
+  Component,
+  Injector,
+  provideNgReflectAttributes,
+  TemplateRef,
+  ViewChild,
+  ViewContainerRef,
+} from '../../src/core';
 import {TestBed} from '../../testing';
 
 describe('TemplateRef', () => {
@@ -78,7 +85,10 @@ describe('TemplateRef', () => {
         constructor(public viewContainerRef: ViewContainerRef) {}
       }
 
-      TestBed.configureTestingModule({declarations: [MenuContent, App]});
+      TestBed.configureTestingModule({
+        declarations: [MenuContent, App],
+        providers: [provideNgReflectAttributes()],
+      });
       const fixture = TestBed.createComponent(App);
       fixture.detectChanges();