Rename the react.element symbol to react.transitional.element (#28813)

We have changed the shape (and the runtime) of React Elements. To help
avoid precompiled or inlined JSX having subtle breakages or deopting
hidden classes, I renamed the symbol so that we can early error if
private implementation details are used or mismatching versions are
used.

Why "transitional"? Well, because this is not the last time we'll change
the shape. This is just a stepping stone to removing the `ref` field on
the elements in the next version so we'll likely have to do it again.

Author: sebmarkbage

packages/react-devtools-shared/src/__tests__/legacy/inspectElement-test.js

@@ -290,9 +290,23 @@ describe('InspectedElementContext', () => {
             "preview_long": {boolean: true, number: 123, string: "abc"},
           },
         },
-        "react_element": Dehydrated {
-          "preview_short": <span />,
-          "preview_long": <span />,
+        "react_element": {
+          "$$typeof": Dehydrated {
+            "preview_short": Symbol(react.element),
+            "preview_long": Symbol(react.element),
+          },
+          "_owner": null,
+          "_store": Dehydrated {
+            "preview_short": {…},
+            "preview_long": {},
+          },
+          "key": null,
+          "props": Dehydrated {
+            "preview_short": {…},
+            "preview_long": {},
+          },
+          "ref": null,
+          "type": "span",
         },
         "regexp": Dehydrated {
           "preview_short": /abc/giu,

packages/react-devtools-shared/src/backend/ReactSymbols.js

@@ -23,8 +23,9 @@ export const SERVER_CONTEXT_SYMBOL_STRING = 'Symbol(react.server_context)';
 
 export const DEPRECATED_ASYNC_MODE_SYMBOL_STRING = 'Symbol(react.async_mode)';
 
-export const ELEMENT_NUMBER = 0xeac7;
-export const ELEMENT_SYMBOL_STRING = 'Symbol(react.element)';
+export const ELEMENT_SYMBOL_STRING = 'Symbol(react.transitional.element)';
+export const LEGACY_ELEMENT_NUMBER = 0xeac7;
+export const LEGACY_ELEMENT_SYMBOL_STRING = 'Symbol(react.element)';
 
 export const DEBUG_TRACING_MODE_NUMBER = 0xeae1;
 export const DEBUG_TRACING_MODE_SYMBOL_STRING =

packages/react-dom/src/__tests__/ReactComponent-test.js

@@ -612,6 +612,32 @@ describe('ReactComponent', () => {
     );
   });
 
+  // @gate renameElementSymbol
+  it('throws if a legacy element is used as a child', async () => {
+    const inlinedElement = {
+      $$typeof: Symbol.for('react.element'),
+      type: 'div',
+      key: null,
+      ref: null,
+      props: {},
+      _owner: null,
+    };
+    const element = <div>{[inlinedElement]}</div>;
+    const container = document.createElement('div');
+    const root = ReactDOMClient.createRoot(container);
+    await expect(
+      act(() => {
+        root.render(element);
+      }),
+    ).rejects.toThrowError(
+      'A React Element from an older version of React was rendered. ' +
+        'This is not supported. It can happen if:\n' +
+        '- Multiple copies of the "react" package is used.\n' +
+        '- A library pre-bundled an old copy of "react" or "react/jsx-runtime".\n' +
+        '- A compiler tries to "inline" JSX instead of using the runtime.',
+    );
+  });
+
   it('throws if a plain object even if it is in an owner', async () => {
     class Foo extends React.Component {
       render() {

packages/react-dom/src/__tests__/ReactDOMOption-test.js

@@ -134,6 +134,7 @@ describe('ReactDOMOption', () => {
     }).rejects.toThrow('Objects are not valid as a React child');
   });
 
+  // @gate www
   it('should support element-ish child', async () => {
     // This is similar to <fbt>.
     // We don't toString it because you must instead provide a value prop.

packages/react-dom/src/__tests__/refs-test.js

@@ -382,7 +382,7 @@ describe('ref swapping', () => {
     }).rejects.toThrow('Expected ref to be a function');
   });
 
-  // @gate !enableRefAsProp
+  // @gate !enableRefAsProp && www
   it('undefined ref on manually inlined React element triggers error', async () => {
     const container = document.createElement('div');
     const root = ReactDOMClient.createRoot(container);

packages/react-reconciler/src/ReactChildFiber.js

@@ -32,6 +32,7 @@ import {
   REACT_PORTAL_TYPE,
   REACT_LAZY_TYPE,
   REACT_CONTEXT_TYPE,
+  REACT_LEGACY_ELEMENT_TYPE,
 } from 'shared/ReactSymbols';
 import {
   HostRoot,
@@ -166,6 +167,16 @@ function coerceRef(
 }
 
 function throwOnInvalidObjectType(returnFiber: Fiber, newChild: Object) {
+  if (newChild.$$typeof === REACT_LEGACY_ELEMENT_TYPE) {
+    throw new Error(
+      'A React Element from an older version of React was rendered. ' +
+        'This is not supported. It can happen if:\n' +
+        '- Multiple copies of the "react" package is used.\n' +
+        '- A library pre-bundled an old copy of "react" or "react/jsx-runtime".\n' +
+        '- A compiler tries to "inline" JSX instead of using the runtime.',
+    );
+  }
+
   // $FlowFixMe[method-unbinding]
   const childString = Object.prototype.toString.call(newChild);
 

packages/react/src/jsx/ReactJSXElement.js

@@ -162,7 +162,7 @@ function elementRefGetterWithDeprecationWarning() {
 /**
  * Factory method to create a new React element. This no longer adheres to
  * the class pattern, so do not use new to call it. Also, instanceof check
- * will not work. Instead test $$typeof field against Symbol.for('react.element') to check
+ * will not work. Instead test $$typeof field against Symbol.for('react.transitional.element') to check
  * if something is a React Element.
  *
  * @param {*} type

packages/shared/ReactFeatureFlags.js

@@ -143,6 +143,9 @@ export const transitionLaneExpirationMs = 5000;
 
 // const __NEXT_MAJOR__ = __EXPERIMENTAL__;
 
+// Renames the internal symbol for elements since they have changed signature/constructor
+export const renameElementSymbol = true;
+
 // Removes legacy style context
 export const disableLegacyContext = true;
 

packages/shared/ReactSymbols.js

@@ -7,12 +7,17 @@
  * @flow
  */
 
+import {renameElementSymbol} from 'shared/ReactFeatureFlags';
+
 // ATTENTION
 // When adding new symbols to this file,
 // Please consider also adding to 'react-devtools-shared/src/backend/ReactSymbols'
 
 // The Symbol used to tag the ReactElement-like types.
-export const REACT_ELEMENT_TYPE: symbol = Symbol.for('react.element');
+export const REACT_LEGACY_ELEMENT_TYPE: symbol = Symbol.for('react.element');
+export const REACT_ELEMENT_TYPE: symbol = renameElementSymbol
+  ? Symbol.for('react.transitional.element')
+  : REACT_LEGACY_ELEMENT_TYPE;
 export const REACT_PORTAL_TYPE: symbol = Symbol.for('react.portal');
 export const REACT_FRAGMENT_TYPE: symbol = Symbol.for('react.fragment');
 export const REACT_STRICT_MODE_TYPE: symbol = Symbol.for('react.strict_mode');

packages/shared/__tests__/ReactSymbols-test.internal.js

@@ -23,6 +23,7 @@ describe('ReactSymbols', () => {
     });
   };
 
+  // @gate renameElementSymbol
   it('Symbol values should be unique', () => {
     expectToBeUnique(Object.entries(require('shared/ReactSymbols')));
   });

packages/shared/forks/ReactFeatureFlags.native-fb.js

@@ -69,6 +69,8 @@ export const enableLegacyFBSupport = false;
 export const enableFilterEmptyStringAttributesDOM = true;
 export const enableGetInspectorDataForInstanceInProduction = true;
 
+export const renameElementSymbol = false;
+
 export const enableRetryLaneExpiration = false;
 export const retryLaneExpirationMs = 5000;
 export const syncLaneExpirationMs = 250;

packages/shared/forks/ReactFeatureFlags.native-oss.js

@@ -104,6 +104,8 @@ export const enableDO_NOT_USE_disableStrictPassiveEffect = false;
 export const passChildrenWhenCloningPersistedNodes = false;
 export const enableEarlyReturnForPropDiffing = false;
 
+export const renameElementSymbol = true;
+
 // Profiling Only
 export const enableProfilerTimer = __PROFILE__;
 export const enableProfilerCommitHooks = __PROFILE__;

packages/shared/forks/ReactFeatureFlags.test-renderer.js

@@ -79,6 +79,8 @@ export const enableServerComponentLogs = true;
 export const enableInfiniteRenderLoopDetection = false;
 export const enableEarlyReturnForPropDiffing = false;
 
+export const renameElementSymbol = true;
+
 // TODO: This must be in sync with the main ReactFeatureFlags file because
 // the Test Renderer's value must be the same as the one used by the
 // react package.

packages/shared/forks/ReactFeatureFlags.test-renderer.native-fb.js

@@ -90,5 +90,7 @@ export const disableDOMTestUtils = false;
 export const disableDefaultPropsExceptForClasses = false;
 export const enableEarlyReturnForPropDiffing = false;
 
+export const renameElementSymbol = false;
+
 // Flow magic to verify the exports of this file match the original version.
 ((((null: any): ExportsType): FeatureFlagsType): ExportsType);

packages/shared/forks/ReactFeatureFlags.test-renderer.www.js

@@ -90,5 +90,7 @@ export const disableDOMTestUtils = false;
 export const disableDefaultPropsExceptForClasses = false;
 export const enableEarlyReturnForPropDiffing = false;
 
+export const renameElementSymbol = false;
+
 // Flow magic to verify the exports of this file match the original version.
 ((((null: any): ExportsType): FeatureFlagsType): ExportsType);

packages/shared/forks/ReactFeatureFlags.www.js

@@ -65,6 +65,8 @@ export const enableSchedulingProfiler: boolean =
 export const disableLegacyContext = __EXPERIMENTAL__;
 export const enableGetInspectorDataForInstanceInProduction = false;
 
+export const renameElementSymbol = false;
+
 export const enableCache = true;
 export const enableLegacyCache = true;
 export const enableFetchInstrumentation = false;