Replace Implicit Options on SuspenseList with Explicit Options (#33424)

sebmarkbage · web-flow · commit d742611ce405 · 2025-06-03T17:40:30.000-04:00
We want to change the defaults for `revealOrder` and `tail` on
SuspenseList. This is an intermediate step to allow experimental users
to upgrade.

To explicitly specify these options I added `revealOrder="independent"`
and `tail="visible"`.

I then added warnings if `undefined` or `null` is passed. You must now
always explicitly specify them. However, semantics are still preserved
for now until the next step.

We also want to change the rendering order of the `children` prop for
`revealOrder="backwards"`. As an intermediate step I first added
`revealOrder="unstable_legacy-backwards"` option. This will only be
temporary until all users can switch to the new `"backwards"` semantics
once we flip it in the next step.

I also clarified the types that the directional props requires iterable
children but not iterable inside of those. Rows with multiple items can
be modeled as explicit fragments.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -611,6 +611,7 @@ module.exports = {
     TimeoutID: 'readonly',
     WheelEventHandler: 'readonly',
     FinalizationRegistry: 'readonly',
+    Exclude: 'readonly',
     Omit: 'readonly',
     Keyframe: 'readonly',
     PropertyIndexedKeyframes: 'readonly',
diff --git a/fixtures/ssr/src/components/LargeContent.js b/fixtures/ssr/src/components/LargeContent.js
@@ -6,7 +6,7 @@ import React, {
 
 export default function LargeContent() {
   return (
-    <SuspenseList revealOrder="forwards">
+    <SuspenseList revealOrder="forwards" tail="visible">
       <Suspense fallback={null}>
         <p>
           Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris
diff --git a/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js b/packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js
@@ -1289,7 +1289,7 @@ describe('ReactDOMFizzServer', () => {
     function App({showMore}) {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             {a}
             {b}
             {showMore ? (
diff --git a/packages/react-dom/src/__tests__/ReactDOMFizzStaticBrowser-test.js b/packages/react-dom/src/__tests__/ReactDOMFizzStaticBrowser-test.js
@@ -2254,7 +2254,7 @@ describe('ReactDOMFizzStaticBrowser', () => {
     function App() {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             <Suspense fallback="Loading A">
               <ComponentA />
             </Suspense>
diff --git a/packages/react-dom/src/__tests__/ReactDOMFizzSuspenseList-test.js b/packages/react-dom/src/__tests__/ReactDOMFizzSuspenseList-test.js
@@ -197,6 +197,70 @@ describe('ReactDOMFizzSuspenseList', () => {
     );
   });
 
+  // @gate enableSuspenseList
+  it('independently with revealOrder="independent"', async () => {
+    const A = createAsyncText('A');
+    const B = createAsyncText('B');
+    const C = createAsyncText('C');
+
+    function Foo() {
+      return (
+        <div>
+          <SuspenseList revealOrder="independent">
+            <Suspense fallback={<Text text="Loading A" />}>
+              <A />
+            </Suspense>
+            <Suspense fallback={<Text text="Loading B" />}>
+              <B />
+            </Suspense>
+            <Suspense fallback={<Text text="Loading C" />}>
+              <C />
+            </Suspense>
+          </SuspenseList>
+        </div>
+      );
+    }
+
+    await A.resolve();
+
+    await serverAct(async () => {
+      const {pipe} = ReactDOMFizzServer.renderToPipeableStream(<Foo />);
+      pipe(writable);
+    });
+
+    assertLog(['A', 'Suspend! [B]', 'Suspend! [C]', 'Loading B', 'Loading C']);
+
+    expect(getVisibleChildren(container)).toEqual(
+      <div>
+        <span>A</span>
+        <span>Loading B</span>
+        <span>Loading C</span>
+      </div>,
+    );
+
+    await serverAct(() => C.resolve());
+    assertLog(['C']);
+
+    expect(getVisibleChildren(container)).toEqual(
+      <div>
+        <span>A</span>
+        <span>Loading B</span>
+        <span>C</span>
+      </div>,
+    );
+
+    await serverAct(() => B.resolve());
+    assertLog(['B']);
+
+    expect(getVisibleChildren(container)).toEqual(
+      <div>
+        <span>A</span>
+        <span>B</span>
+        <span>C</span>
+      </div>,
+    );
+  });
+
   // @gate enableSuspenseList
   it('displays all "together"', async () => {
     const A = createAsyncText('A');
@@ -452,7 +516,7 @@ describe('ReactDOMFizzSuspenseList', () => {
   });
 
   // @gate enableSuspenseList
-  it('displays all "together" in nested SuspenseLists where the inner is default', async () => {
+  it('displays all "together" in nested SuspenseLists where the inner is "independent"', async () => {
     const A = createAsyncText('A');
     const B = createAsyncText('B');
     const C = createAsyncText('C');
@@ -464,7 +528,7 @@ describe('ReactDOMFizzSuspenseList', () => {
             <Suspense fallback={<Text text="Loading A" />}>
               <A />
             </Suspense>
-            <SuspenseList>
+            <SuspenseList revealOrder="independent">
               <Suspense fallback={<Text text="Loading B" />}>
                 <B />
               </Suspense>
@@ -523,7 +587,7 @@ describe('ReactDOMFizzSuspenseList', () => {
     function Foo() {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             <Suspense fallback={<Text text="Loading A" />}>
               <A />
             </Suspense>
@@ -586,15 +650,15 @@ describe('ReactDOMFizzSuspenseList', () => {
   });
 
   // @gate enableSuspenseList
-  it('displays each items in "backwards" order', async () => {
+  it('displays each items in "backwards" order in legacy mode', async () => {
     const A = createAsyncText('A');
     const B = createAsyncText('B');
     const C = createAsyncText('C');
 
     function Foo() {
       return (
         <div>
-          <SuspenseList revealOrder="backwards">
+          <SuspenseList revealOrder="unstable_legacy-backwards" tail="visible">
             <Suspense fallback={<Text text="Loading A" />}>
               <A />
             </Suspense>
@@ -665,8 +729,10 @@ describe('ReactDOMFizzSuspenseList', () => {
     function Foo() {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
-            <SuspenseList revealOrder="backwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
+            <SuspenseList
+              revealOrder="unstable_legacy-backwards"
+              tail="visible">
               <Suspense fallback={<Text text="Loading A" />}>
                 <A />
               </Suspense>
@@ -736,7 +802,7 @@ describe('ReactDOMFizzSuspenseList', () => {
     function Foo() {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             <Suspense fallback={<Text text="Loading A" />}>
               <A />
             </Suspense>
@@ -791,7 +857,7 @@ describe('ReactDOMFizzSuspenseList', () => {
     function Foo() {
       return (
         <div>
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             <Suspense fallback={<Text text="Loading A" />}>
               <A />
             </Suspense>
diff --git a/packages/react-dom/src/__tests__/ReactDOMFloat-test.js b/packages/react-dom/src/__tests__/ReactDOMFloat-test.js
@@ -5755,7 +5755,7 @@ body {
         <html>
           <body>
             <Suspense fallback="loading...">
-              <SuspenseList revealOrder="forwards">
+              <SuspenseList revealOrder="forwards" tail="visible">
                 <Suspense fallback="loading foo...">
                   <BlockedOn value="foo">
                     <link rel="stylesheet" href="foo" precedence="foo" />
diff --git a/packages/react-dom/src/__tests__/ReactDOMServerPartialHydration-test.internal.js b/packages/react-dom/src/__tests__/ReactDOMServerPartialHydration-test.internal.js
@@ -2362,7 +2362,7 @@ describe('ReactDOMServerPartialHydration', () => {
 
     function App({showMore}) {
       return (
-        <SuspenseList revealOrder="forwards">
+        <SuspenseList revealOrder="forwards" tail="visible">
           {a}
           {b}
           {showMore ? (
diff --git a/packages/react-dom/src/__tests__/ReactDOMServerSuspense-test.internal.js b/packages/react-dom/src/__tests__/ReactDOMServerSuspense-test.internal.js
@@ -123,7 +123,7 @@ describe('ReactDOMServerSuspense', () => {
   // @gate enableSuspenseList
   it('server renders a SuspenseList component and its children', async () => {
     const example = (
-      <SuspenseList>
+      <SuspenseList revealOrder="forwards" tail="visible">
         <React.Suspense fallback="Loading A">
           <div>A</div>
         </React.Suspense>
diff --git a/packages/react-dom/src/__tests__/ReactWrongReturnPointer-test.js b/packages/react-dom/src/__tests__/ReactWrongReturnPointer-test.js
@@ -172,7 +172,7 @@ test('regression (#20932): return pointer is correct before entering deleted tre
 
   function App() {
     return (
-      <SuspenseList revealOrder="forwards">
+      <SuspenseList revealOrder="forwards" tail="visible">
         <Suspense fallback={<Text text="Loading Async..." />}>
           <Async />
         </Suspense>
diff --git a/packages/react-reconciler/src/ReactChildFiber.js b/packages/react-reconciler/src/ReactChildFiber.js
@@ -2097,7 +2097,9 @@ export function validateSuspenseListChildren(
 ) {
   if (__DEV__) {
     if (
-      (revealOrder === 'forwards' || revealOrder === 'backwards') &&
+      (revealOrder === 'forwards' ||
+        revealOrder === 'backwards' ||
+        revealOrder === 'unstable_legacy-backwards') &&
       children !== undefined &&
       children !== null &&
       children !== false
diff --git a/packages/react-reconciler/src/ReactFiberBeginWork.js b/packages/react-reconciler/src/ReactFiberBeginWork.js
@@ -337,7 +337,7 @@ if (__DEV__) {
   didWarnAboutContextTypes = ({}: {[string]: boolean});
   didWarnAboutGetDerivedStateOnFunctionComponent = ({}: {[string]: boolean});
   didWarnAboutReassigningProps = false;
-  didWarnAboutRevealOrder = ({}: {[empty]: boolean});
+  didWarnAboutRevealOrder = ({}: {[string]: boolean});
   didWarnAboutTailOptions = ({}: {[string]: boolean});
   didWarnAboutDefaultPropsOnFunctionComponent = ({}: {[string]: boolean});
   didWarnAboutClassNameOnViewTransition = ({}: {[string]: boolean});
@@ -3225,19 +3225,32 @@ function findLastContentRow(firstChild: null | Fiber): null | Fiber {
 
 function validateRevealOrder(revealOrder: SuspenseListRevealOrder) {
   if (__DEV__) {
+    const cacheKey = revealOrder == null ? 'null' : revealOrder;
     if (
-      revealOrder !== undefined &&
       revealOrder !== 'forwards' &&
-      revealOrder !== 'backwards' &&
+      revealOrder !== 'unstable_legacy-backwards' &&
       revealOrder !== 'together' &&
-      !didWarnAboutRevealOrder[revealOrder]
+      revealOrder !== 'independent' &&
+      !didWarnAboutRevealOrder[cacheKey]
     ) {
-      didWarnAboutRevealOrder[revealOrder] = true;
-      if (typeof revealOrder === 'string') {
+      didWarnAboutRevealOrder[cacheKey] = true;
+      if (revealOrder == null) {
+        console.error(
+          'The default for the <SuspenseList revealOrder="..."> prop is changing. ' +
+            'To be future compatible you must explictly specify either ' +
+            '"independent" (the current default), "together", "forwards" or "legacy_unstable-backwards".',
+        );
+      } else if (revealOrder === 'backwards') {
+        console.error(
+          'The rendering order of <SuspenseList revealOrder="backwards"> is changing. ' +
+            'To be future compatible you must specify revealOrder="legacy_unstable-backwards" instead.',
+        );
+      } else if (typeof revealOrder === 'string') {
         switch (revealOrder.toLowerCase()) {
           case 'together':
           case 'forwards':
-          case 'backwards': {
+          case 'backwards':
+          case 'independent': {
             console.error(
               '"%s" is not a valid value for revealOrder on <SuspenseList />. ' +
                 'Use lowercase "%s" instead.',
@@ -3259,15 +3272,15 @@ function validateRevealOrder(revealOrder: SuspenseListRevealOrder) {
           default:
             console.error(
               '"%s" is not a supported revealOrder on <SuspenseList />. ' +
-                'Did you mean "together", "forwards" or "backwards"?',
+                'Did you mean "independent", "together", "forwards" or "backwards"?',
               revealOrder,
             );
             break;
         }
       } else {
         console.error(
           '%s is not a supported value for revealOrder on <SuspenseList />. ' +
-            'Did you mean "together", "forwards" or "backwards"?',
+            'Did you mean "independent", "together", "forwards" or "backwards"?',
           revealOrder,
         );
       }
@@ -3280,16 +3293,38 @@ function validateTailOptions(
   revealOrder: SuspenseListRevealOrder,
 ) {
   if (__DEV__) {
-    if (tailMode !== undefined && !didWarnAboutTailOptions[tailMode]) {
-      if (tailMode !== 'collapsed' && tailMode !== 'hidden') {
-        didWarnAboutTailOptions[tailMode] = true;
+    const cacheKey = tailMode == null ? 'null' : tailMode;
+    if (!didWarnAboutTailOptions[cacheKey]) {
+      if (tailMode == null) {
+        if (
+          revealOrder === 'forwards' ||
+          revealOrder === 'backwards' ||
+          revealOrder === 'unstable_legacy-backwards'
+        ) {
+          didWarnAboutTailOptions[cacheKey] = true;
+          console.error(
+            'The default for the <SuspenseList tail="..."> prop is changing. ' +
+              'To be future compatible you must explictly specify either ' +
+              '"visible" (the current default), "collapsed" or "hidden".',
+          );
+        }
+      } else if (
+        tailMode !== 'visible' &&
+        tailMode !== 'collapsed' &&
+        tailMode !== 'hidden'
+      ) {
+        didWarnAboutTailOptions[cacheKey] = true;
         console.error(
           '"%s" is not a supported value for tail on <SuspenseList />. ' +
-            'Did you mean "collapsed" or "hidden"?',
+            'Did you mean "visible", "collapsed" or "hidden"?',
           tailMode,
         );
-      } else if (revealOrder !== 'forwards' && revealOrder !== 'backwards') {
-        didWarnAboutTailOptions[tailMode] = true;
+      } else if (
+        revealOrder !== 'forwards' &&
+        revealOrder !== 'backwards' &&
+        revealOrder !== 'unstable_legacy-backwards'
+      ) {
+        didWarnAboutTailOptions[cacheKey] = true;
         console.error(
           '<SuspenseList tail="%s" /> is only valid if revealOrder is ' +
             '"forwards" or "backwards". ' +
@@ -3414,7 +3449,8 @@ function updateSuspenseListComponent(
         );
         break;
       }
-      case 'backwards': {
+      case 'backwards':
+      case 'unstable_legacy-backwards': {
         // We're going to find the first row that has existing content.
         // At the same time we're going to reverse the list of everything
         // we pass in the meantime. That's going to be our tail in reverse
diff --git a/packages/react-reconciler/src/ReactFiberSuspenseComponent.js b/packages/react-reconciler/src/ReactFiberSuspenseComponent.js
@@ -75,9 +75,12 @@ export function findFirstSuspended(row: Fiber): null | Fiber {
       }
     } else if (
       node.tag === SuspenseListComponent &&
-      // revealOrder undefined can't be trusted because it don't
+      // Independent revealOrder can't be trusted because it doesn't
       // keep track of whether it suspended or not.
-      node.memoizedProps.revealOrder !== undefined
+      (node.memoizedProps.revealOrder === 'forwards' ||
+        node.memoizedProps.revealOrder === 'backwards' ||
+        node.memoizedProps.revealOrder === 'unstable_legacy-backwards' ||
+        node.memoizedProps.revealOrder === 'together')
     ) {
       const didSuspend = (node.flags & DidCapture) !== NoFlags;
       if (didSuspend) {
diff --git a/packages/react-reconciler/src/__tests__/ReactContextPropagation-test.js b/packages/react-reconciler/src/__tests__/ReactContextPropagation-test.js
@@ -677,7 +677,7 @@ describe('ReactLazyContextPropagation', () => {
       setContext = setValue;
       const children = React.useMemo(
         () => (
-          <SuspenseList revealOrder="forwards">
+          <SuspenseList revealOrder="forwards" tail="visible">
             <Child />
             <Child />
           </SuspenseList>
diff --git a/packages/react-reconciler/src/__tests__/ReactErrorStacks-test.js b/packages/react-reconciler/src/__tests__/ReactErrorStacks-test.js
@@ -255,7 +255,7 @@ describe('ReactFragment', () => {
       onCaughtError,
     }).render(
       <CatchingBoundary>
-        <SuspenseList>
+        <SuspenseList revealOrder="independent">
           <SomethingThatErrors />
         </SuspenseList>
       </CatchingBoundary>,
diff --git a/packages/react-reconciler/src/__tests__/ReactSuspenseList-test.js b/packages/react-reconciler/src/__tests__/ReactSuspenseList-test.js
diff --git a/packages/react-reconciler/src/__tests__/ReactSuspenseyCommitPhase-test.js b/packages/react-reconciler/src/__tests__/ReactSuspenseyCommitPhase-test.js
diff --git a/packages/react-server/src/ReactFizzServer.js b/packages/react-server/src/ReactFizzServer.js
diff --git a/packages/shared/ReactTypes.js b/packages/shared/ReactTypes.js
