From a0fdb6306043b9f049106e58dcec107d8dbed2b1 Mon Sep 17 00:00:00 2001
From: Josh Story <story@hey.com>
Date: Thu, 6 Feb 2025 15:05:51 -0800
Subject: [PATCH] [Fiber][Dev] Relax dom nesting validation when the root is a
 Document, html tag, or body tag (#32252)

followup to
* https://github.com/facebook/react/pull/32069
* https://github.com/facebook/react/pull/32163
* https://github.com/facebook/react/pull/32224

in react-dom in Dev we validate that the tag nesting is valid. This is
motivated primarily because while browsers are tolerant to poor HTML
there are many cases that if server rendered will be hydrated in a way
that will break hydration.

With the changes to singleton scoping where the document body is now the
implicit render/hydration context for arbitrary tags at the root we need
to adjust the validation logic to allow for valid programs such as
rendering divs as a child of a Document (since this div will actually
insert into the body).
---
 .../src/client/ReactDOMComponent.js           |   4 +-
 .../src/client/ReactFiberConfigDOM.js         |  23 +++-
 .../src/client/validateDOMNesting.js          |  72 ++++++++++--
 .../react-dom/src/__tests__/ReactDOM-test.js  |  12 --
 .../src/__tests__/ReactDOMFizzServer-test.js  |   2 -
 .../src/__tests__/ReactDOMFloat-test.js       |   6 -
 .../src/__tests__/validateDOMNesting-test.js  | 105 +++++++++++++++---
 7 files changed, 175 insertions(+), 49 deletions(-)

diff --git a/packages/react-dom-bindings/src/client/ReactDOMComponent.js b/packages/react-dom-bindings/src/client/ReactDOMComponent.js
index 6406b734c439c..15a4ba675b5e0 100644
--- a/packages/react-dom-bindings/src/client/ReactDOMComponent.js
+++ b/packages/react-dom-bindings/src/client/ReactDOMComponent.js
@@ -344,7 +344,7 @@ function setProp(
     case 'children': {
       if (typeof value === 'string') {
         if (__DEV__) {
-          validateTextNesting(value, tag);
+          validateTextNesting(value, tag, false);
         }
         // Avoid setting initial textContent when the text is empty. In IE11 setting
         // textContent on a <textarea> will cause the placeholder to not
@@ -358,7 +358,7 @@ function setProp(
       } else if (typeof value === 'number' || typeof value === 'bigint') {
         if (__DEV__) {
           // $FlowFixMe[unsafe-addition] Flow doesn't want us to use `+` operator with string and bigint
-          validateTextNesting('' + value, tag);
+          validateTextNesting('' + value, tag, false);
         }
         const canSetTextContent = tag !== 'body';
         if (canSetTextContent) {
diff --git a/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js b/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
index 012f7cd257f24..e96810122da6e 100644
--- a/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
+++ b/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
@@ -595,7 +595,11 @@ export function createTextInstance(
     const hostContextDev = ((hostContext: any): HostContextDev);
     const ancestor = hostContextDev.ancestorInfo.current;
     if (ancestor != null) {
-      validateTextNesting(text, ancestor.tag);
+      validateTextNesting(
+        text,
+        ancestor.tag,
+        hostContextDev.ancestorInfo.implicitRootScope,
+      );
     }
   }
   const textNode: TextInstance = getOwnerDocumentFromRootContainer(
@@ -2046,7 +2050,11 @@ export function validateHydratableTextInstance(
     const hostContextDev = ((hostContext: any): HostContextDev);
     const ancestor = hostContextDev.ancestorInfo.current;
     if (ancestor != null) {
-      return validateTextNesting(text, ancestor.tag);
+      return validateTextNesting(
+        text,
+        ancestor.tag,
+        hostContextDev.ancestorInfo.implicitRootScope,
+      );
     }
   }
   return true;
@@ -2394,8 +2402,15 @@ export function acquireSingletonInstance(
   internalInstanceHandle: Object,
 ): void {
   if (__DEV__) {
-    const currentInstanceHandle = getInstanceFromNodeDOMTree(instance);
-    if (currentInstanceHandle) {
+    if (
+      // If this instance is the container then it is invalid to acquire it as a singleton however
+      // the DOM nesting validation will already warn for this and the message below isn't semantically
+      // aligned with the actual fix you need to make so we omit the warning in this case
+      !isContainerMarkedAsRoot(instance) &&
+      // If this instance isn't the root but is currently owned by a different HostSingleton instance then
+      // we we need to warn that you are rendering more than one singleton at a time.
+      getInstanceFromNodeDOMTree(instance)
+    ) {
       const tagName = instance.tagName.toLowerCase();
       console.error(
         'You are mounting a new %s component when a previous one has not first unmounted. It is an' +
diff --git a/packages/react-dom-bindings/src/client/validateDOMNesting.js b/packages/react-dom-bindings/src/client/validateDOMNesting.js
index d6fdc5e857ed3..48ea32d7f3ffc 100644
--- a/packages/react-dom-bindings/src/client/validateDOMNesting.js
+++ b/packages/react-dom-bindings/src/client/validateDOMNesting.js
@@ -71,6 +71,7 @@ export type AncestorInfoDev = {
 
   // <head> or <body>
   containerTagInScope: ?Info,
+  implicitRootScope: boolean,
 };
 
 // This validation code was written based on the HTML5 parsing spec:
@@ -219,10 +220,11 @@ const emptyAncestorInfoDev: AncestorInfoDev = {
   dlItemTagAutoclosing: null,
 
   containerTagInScope: null,
+  implicitRootScope: false,
 };
 
 function updatedAncestorInfoDev(
-  oldInfo: ?AncestorInfoDev,
+  oldInfo: null | AncestorInfoDev,
   tag: string,
 ): AncestorInfoDev {
   if (__DEV__) {
@@ -238,14 +240,14 @@ function updatedAncestorInfoDev(
       ancestorInfo.pTagInButtonScope = null;
     }
 
-    // See rules for 'li', 'dd', 'dt' start tags in
-    // https://html.spec.whatwg.org/multipage/syntax.html#parsing-main-inbody
     if (
       specialTags.indexOf(tag) !== -1 &&
       tag !== 'address' &&
       tag !== 'div' &&
       tag !== 'p'
     ) {
+      // See rules for 'li', 'dd', 'dt' start tags in
+      // https://html.spec.whatwg.org/multipage/syntax.html#parsing-main-inbody
       ancestorInfo.listItemTagAutoclosing = null;
       ancestorInfo.dlItemTagAutoclosing = null;
     }
@@ -279,6 +281,17 @@ function updatedAncestorInfoDev(
       ancestorInfo.containerTagInScope = info;
     }
 
+    if (
+      oldInfo === null &&
+      (tag === '#document' || tag === 'html' || tag === 'body')
+    ) {
+      // While <head> is also a singleton we don't want to support semantics where
+      // you can escape the head by rendering a body singleton so we treat it like a normal scope
+      ancestorInfo.implicitRootScope = true;
+    } else if (ancestorInfo.implicitRootScope === true) {
+      ancestorInfo.implicitRootScope = false;
+    }
+
     return ancestorInfo;
   } else {
     return (null: any);
@@ -288,7 +301,11 @@ function updatedAncestorInfoDev(
 /**
  * Returns whether
  */
-function isTagValidWithParent(tag: string, parentTag: ?string): boolean {
+function isTagValidWithParent(
+  tag: string,
+  parentTag: ?string,
+  implicitRootScope: boolean,
+): boolean {
   // First, let's check if we're in an unusual parsing mode...
   switch (parentTag) {
     // https://html.spec.whatwg.org/multipage/syntax.html#parsing-main-inselect
@@ -363,10 +380,22 @@ function isTagValidWithParent(tag: string, parentTag: ?string): boolean {
       );
     // https://html.spec.whatwg.org/multipage/semantics.html#the-html-element
     case 'html':
+      if (implicitRootScope) {
+        // When our parent tag is html and we're in the root scope we will actually
+        // insert most tags into the body so we need to fall through to validating
+        // the specific tag with "in body" parsing mode below
+        break;
+      }
       return tag === 'head' || tag === 'body' || tag === 'frameset';
     case 'frameset':
       return tag === 'frame';
     case '#document':
+      if (implicitRootScope) {
+        // When our parent is the Document and we're in the root scope we will actually
+        // insert most tags into the body so we need to fall through to validating
+        // the specific tag with "in body" parsing mode below
+        break;
+      }
       return tag === 'html';
   }
 
@@ -393,14 +422,11 @@ function isTagValidWithParent(tag: string, parentTag: ?string): boolean {
     case 'rt':
       return impliedEndTags.indexOf(parentTag) === -1;
 
-    case 'body':
     case 'caption':
     case 'col':
     case 'colgroup':
     case 'frameset':
     case 'frame':
-    case 'head':
-    case 'html':
     case 'tbody':
     case 'td':
     case 'tfoot':
@@ -412,6 +438,24 @@ function isTagValidWithParent(tag: string, parentTag: ?string): boolean {
       // so we allow it only if we don't know what the parent is, as all other
       // cases are invalid.
       return parentTag == null;
+    case 'head':
+      // We support rendering <head> in the root when the container is
+      // #document, <html>, or <body>.
+      return implicitRootScope || parentTag === null;
+    case 'html':
+      // We support rendering <html> in the root when the container is
+      // #document
+      return (
+        (implicitRootScope && parentTag === '#document') || parentTag === null
+      );
+    case 'body':
+      // We support rendering <body> in the root when the container is
+      // #document or <html>
+      return (
+        (implicitRootScope &&
+          (parentTag === '#document' || parentTag === 'html')) ||
+        parentTag === null
+      );
   }
 
   return true;
@@ -513,7 +557,11 @@ function validateDOMNesting(
     const parentInfo = ancestorInfo.current;
     const parentTag = parentInfo && parentInfo.tag;
 
-    const invalidParent = isTagValidWithParent(childTag, parentTag)
+    const invalidParent = isTagValidWithParent(
+      childTag,
+      parentTag,
+      ancestorInfo.implicitRootScope,
+    )
       ? null
       : parentInfo;
     const invalidAncestor = invalidParent
@@ -594,9 +642,13 @@ function validateDOMNesting(
   return true;
 }
 
-function validateTextNesting(childText: string, parentTag: string): boolean {
+function validateTextNesting(
+  childText: string,
+  parentTag: string,
+  implicitRootScope: boolean,
+): boolean {
   if (__DEV__) {
-    if (isTagValidWithParent('#text', parentTag)) {
+    if (implicitRootScope || isTagValidWithParent('#text', parentTag, false)) {
       return true;
     }
 
diff --git a/packages/react-dom/src/__tests__/ReactDOM-test.js b/packages/react-dom/src/__tests__/ReactDOM-test.js
index ef0dd50258122..0d4a758a3c298 100644
--- a/packages/react-dom/src/__tests__/ReactDOM-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOM-test.js
@@ -601,10 +601,6 @@ describe('ReactDOM', () => {
       '<html lang="en"><head data-h=""><meta itemprop="" content="head"></head><body data-b=""><div>before</div><div>inside</div><div>after</div></body></html>',
     );
 
-    // @TODO remove this warning check when we loosen the tag nesting restrictions to allow arbitrary tags at the
-    // root of the application
-    assertConsoleErrorDev(['In HTML, <div> cannot be a child of <#document>']);
-
     await act(() => {
       root.render(<App phase={1} />);
     });
@@ -666,10 +662,6 @@ describe('ReactDOM', () => {
       '<html><head data-h=""><meta itemprop="" content="head"></head><body data-b=""><div>before</div><div>inside</div><div>after</div></body></html>',
     );
 
-    // @TODO remove this warning check when we loosen the tag nesting restrictions to allow arbitrary tags at the
-    // root of the application
-    assertConsoleErrorDev(['In HTML, <div> cannot be a child of <html>']);
-
     await act(() => {
       root.render(<App phase={1} />);
     });
@@ -729,10 +721,6 @@ describe('ReactDOM', () => {
       '<html><head data-h=""><meta itemprop="" content="head"></head><body><div>before</div><div>inside</div><div>after</div></body></html>',
     );
 
-    // @TODO remove this warning check when we loosen the tag nesting restrictions to allow arbitrary tags at the
-    // root of the application
-    assertConsoleErrorDev(['In HTML, <head> cannot be a child of <body>']);
-
     await act(() => {
       root.render(<App phase={1} />);
     });
diff --git a/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js b/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js
index d0a1e484f2810..d64167015eec9 100644
--- a/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js
@@ -9004,7 +9004,6 @@ describe('ReactDOMFizzServer', () => {
         </body>
       </html>,
     );
-    assertConsoleErrorDev(['In HTML, <div> cannot be a child of <#document>']);
 
     root.unmount();
     expect(getVisibleChildren(document)).toEqual(
@@ -10173,7 +10172,6 @@ describe('ReactDOMFizzServer', () => {
         </body>
       </html>,
     );
-    assertConsoleErrorDev(['In HTML, <div> cannot be a child of <#document>']);
 
     root.unmount();
     expect(getVisibleChildren(document)).toEqual(
diff --git a/packages/react-dom/src/__tests__/ReactDOMFloat-test.js b/packages/react-dom/src/__tests__/ReactDOMFloat-test.js
index bdd50c9d4f469..4375ddb7d8deb 100644
--- a/packages/react-dom/src/__tests__/ReactDOMFloat-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOMFloat-test.js
@@ -511,9 +511,6 @@ describe('ReactDOMFloat', () => {
         'Cannot render <noscript> outside the main document. Try moving it into the root <head> tag.',
         {withoutStack: true},
       ],
-      'In HTML, <noscript> cannot be a child of <#document>.\n' +
-        'This will cause a hydration error.\n' +
-        '    in noscript (at **)',
     ]);
 
     root.render(
@@ -577,9 +574,6 @@ describe('ReactDOMFloat', () => {
           'Consider adding precedence="default" or moving it into the root <head> tag.',
         {withoutStack: true},
       ],
-      'In HTML, <link> cannot be a child of <#document>.\n' +
-        'This will cause a hydration error.\n' +
-        '    in link (at **)',
     ]);
 
     root.render(
diff --git a/packages/react-dom/src/__tests__/validateDOMNesting-test.js b/packages/react-dom/src/__tests__/validateDOMNesting-test.js
index fc4fb0f80d44a..1f90b2d008b48 100644
--- a/packages/react-dom/src/__tests__/validateDOMNesting-test.js
+++ b/packages/react-dom/src/__tests__/validateDOMNesting-test.js
@@ -19,28 +19,54 @@ function expectWarnings(tags, warnings = [], withoutStack = 0) {
   tags = [...tags];
   warnings = [...warnings];
 
+  document.removeChild(document.documentElement);
+  document.appendChild(document.createElement('html'));
+  document.documentElement.innerHTML = '<head></head><body></body>';
+
   let element = null;
   const containerTag = tags.shift();
-  const container =
-    containerTag === 'svg'
-      ? document.createElementNS('http://www.w3.org/2000/svg', containerTag)
-      : document.createElement(containerTag);
+  let container;
+  switch (containerTag) {
+    case '#document':
+      container = document;
+      break;
+    case 'html':
+      container = document.documentElement;
+      break;
+    case 'body':
+      container = document.body;
+      break;
+    case 'head':
+      container = document.head;
+      break;
+    case 'svg':
+      container = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      break;
+    default:
+      container = document.createElement(containerTag);
+      break;
+  }
 
   while (tags.length) {
     const Tag = tags.pop();
-    element = <Tag>{element}</Tag>;
+    if (Tag === '#text') {
+      element = 'text';
+    } else {
+      element = <Tag>{element}</Tag>;
+    }
   }
 
   const root = ReactDOMClient.createRoot(container);
+  ReactDOM.flushSync(() => {
+    root.render(element);
+  });
   if (warnings.length) {
-    ReactDOM.flushSync(() => {
-      root.render(element);
-    });
     assertConsoleErrorDev(
       warnings,
       withoutStack > 0 ? {withoutStack} : undefined,
     );
   }
+  root.unmount();
 }
 
 describe('validateDOMNesting', () => {
@@ -140,6 +166,46 @@ describe('validateDOMNesting', () => {
           '    in body (at **)',
       ],
     );
+    expectWarnings(
+      ['head', 'body'],
+      [
+        'In HTML, <body> cannot be a child of <head>.\n' +
+          'This will cause a hydration error.\n' +
+          '    in body (at **)',
+      ],
+    );
+    expectWarnings(
+      ['head', 'head'],
+      [
+        'In HTML, <head> cannot be a child of <head>.\n' +
+          'This will cause a hydration error.\n' +
+          '    in head (at **)',
+      ],
+    );
+    expectWarnings(
+      ['html', 'html'],
+      [
+        'In HTML, <html> cannot be a child of <html>.\n' +
+          'This will cause a hydration error.\n' +
+          '    in html (at **)',
+      ],
+    );
+    expectWarnings(
+      ['body', 'html'],
+      [
+        'In HTML, <html> cannot be a child of <body>.\n' +
+          'This will cause a hydration error.\n' +
+          '    in html (at **)',
+      ],
+    );
+    expectWarnings(
+      ['head', 'html'],
+      [
+        'In HTML, <html> cannot be a child of <head>.\n' +
+          'This will cause a hydration error.\n' +
+          '    in html (at **)',
+      ],
+    );
     expectWarnings(
       ['svg', 'foreignObject', 'body', 'p'],
       gate(flags => flags.enableOwnerStacks)
@@ -152,8 +218,6 @@ describe('validateDOMNesting', () => {
               '>   <body>\n' +
               '\n' +
               '    in body (at **)',
-            'You are mounting a new body component when a previous one has not first unmounted. It is an error to render more than one body component at a time and attributes and children of these components will likely fail in unpredictable ways. Please only render a single instance of <body> and if you need to mount a new one, ensure any previous ones have unmounted first.\n' +
-              '    in body (at **)',
           ]
         : [
             // TODO, this should say "In SVG",
@@ -165,10 +229,25 @@ describe('validateDOMNesting', () => {
               '\n' +
               '    in body (at **)\n' +
               '    in foreignObject (at **)',
-            'You are mounting a new body component when a previous one has not first unmounted. It is an error to render more than one body component at a time and attributes and children of these components will likely fail in unpredictable ways. Please only render a single instance of <body> and if you need to mount a new one, ensure any previous ones have unmounted first.\n' +
-              '    in body (at **)\n' +
-              '    in foreignObject (at **)',
           ],
     );
   });
+
+  it('relaxes the nesting rules at the root when the container is a singleton', () => {
+    expectWarnings(['#document', 'html']);
+    expectWarnings(['#document', 'body']);
+    expectWarnings(['#document', 'head']);
+    expectWarnings(['#document', 'div']);
+    expectWarnings(['#document', 'meta']);
+    expectWarnings(['#document', '#text']);
+    expectWarnings(['html', 'body']);
+    expectWarnings(['html', 'head']);
+    expectWarnings(['html', 'div']);
+    expectWarnings(['html', 'meta']);
+    expectWarnings(['html', '#text']);
+    expectWarnings(['body', 'head']);
+    expectWarnings(['body', 'div']);
+    expectWarnings(['body', 'meta']);
+    expectWarnings(['body', '#text']);
+  });
 });