[Experimental] Add useInsertionEffect (#21913)

packages/react-debug-tools/src/ReactDebugHooks.js

@@ -78,6 +78,7 @@ function getPrimitiveStackCache(): Map<string, Array<any>> {
         Dispatcher.useCacheRefresh();
       }
       Dispatcher.useLayoutEffect(() => {});
+      Dispatcher.useInsertionEffect(() => {});
       Dispatcher.useEffect(() => {});
       Dispatcher.useImperativeHandle(undefined, () => null);
       Dispatcher.useDebugValue(null);
@@ -191,6 +192,18 @@ function useLayoutEffect(
   });
 }
 
+function useInsertionEffect(
+  create: () => mixed,
+  inputs: Array<mixed> | void | null,
+): void {
+  nextHook();
+  hookLog.push({
+    primitive: 'InsertionEffect',
+    stackError: new Error(),
+    value: create,
+  });
+}
+
 function useEffect(
   create: () => (() => void) | void,
   inputs: Array<mixed> | void | null,
@@ -338,6 +351,7 @@ const Dispatcher: DispatcherType = {
   useImperativeHandle,
   useDebugValue,
   useLayoutEffect,
+  useInsertionEffect,
   useMemo,
   useReducer,
   useRef,

packages/react-debug-tools/src/__tests__/ReactHooksInspectionIntegration-test.js

@@ -268,6 +268,183 @@ describe('ReactHooksInspectionIntegration', () => {
     ]);
   });
 
+  // @gate experimental || www
+  it('should inspect the current state of all stateful hooks, including useInsertionEffect', () => {
+    const useInsertionEffect = React.unstable_useInsertionEffect;
+    const outsideRef = React.createRef();
+    function effect() {}
+    function Foo(props) {
+      const [state1, setState] = React.useState('a');
+      const [state2, dispatch] = React.useReducer((s, a) => a.value, 'b');
+      const ref = React.useRef('c');
+
+      useInsertionEffect(effect);
+      React.useLayoutEffect(effect);
+      React.useEffect(effect);
+
+      React.useImperativeHandle(
+        outsideRef,
+        () => {
+          // Return a function so that jest treats them as non-equal.
+          return function Instance() {};
+        },
+        [],
+      );
+
+      React.useMemo(() => state1 + state2, [state1]);
+
+      function update() {
+        act(() => {
+          setState('A');
+        });
+        act(() => {
+          dispatch({value: 'B'});
+        });
+        ref.current = 'C';
+      }
+      const memoizedUpdate = React.useCallback(update, []);
+      return (
+        <div onClick={memoizedUpdate}>
+          {state1} {state2}
+        </div>
+      );
+    }
+    let renderer;
+    act(() => {
+      renderer = ReactTestRenderer.create(<Foo prop="prop" />);
+    });
+
+    let childFiber = renderer.root.findByType(Foo)._currentFiber();
+
+    const {onClick: updateStates} = renderer.root.findByType('div').props;
+
+    let tree = ReactDebugTools.inspectHooksOfFiber(childFiber);
+    expect(tree).toEqual([
+      {
+        isStateEditable: true,
+        id: 0,
+        name: 'State',
+        value: 'a',
+        subHooks: [],
+      },
+      {
+        isStateEditable: true,
+        id: 1,
+        name: 'Reducer',
+        value: 'b',
+        subHooks: [],
+      },
+      {isStateEditable: false, id: 2, name: 'Ref', value: 'c', subHooks: []},
+      {
+        isStateEditable: false,
+        id: 3,
+        name: 'InsertionEffect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 4,
+        name: 'LayoutEffect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 5,
+        name: 'Effect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 6,
+        name: 'ImperativeHandle',
+        value: outsideRef.current,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 7,
+        name: 'Memo',
+        value: 'ab',
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 8,
+        name: 'Callback',
+        value: updateStates,
+        subHooks: [],
+      },
+    ]);
+
+    updateStates();
+
+    childFiber = renderer.root.findByType(Foo)._currentFiber();
+    tree = ReactDebugTools.inspectHooksOfFiber(childFiber);
+
+    expect(tree).toEqual([
+      {
+        isStateEditable: true,
+        id: 0,
+        name: 'State',
+        value: 'A',
+        subHooks: [],
+      },
+      {
+        isStateEditable: true,
+        id: 1,
+        name: 'Reducer',
+        value: 'B',
+        subHooks: [],
+      },
+      {isStateEditable: false, id: 2, name: 'Ref', value: 'C', subHooks: []},
+      {
+        isStateEditable: false,
+        id: 3,
+        name: 'InsertionEffect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 4,
+        name: 'LayoutEffect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 5,
+        name: 'Effect',
+        value: effect,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 6,
+        name: 'ImperativeHandle',
+        value: outsideRef.current,
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 7,
+        name: 'Memo',
+        value: 'Ab',
+        subHooks: [],
+      },
+      {
+        isStateEditable: false,
+        id: 8,
+        name: 'Callback',
+        value: updateStates,
+        subHooks: [],
+      },
+    ]);
+  });
+
   it('should inspect the value of the current provider in useContext', () => {
     const MyContext = React.createContext('default');
     function Foo(props) {

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

@@ -27,6 +27,7 @@ let useCallback;
 let useMemo;
 let useRef;
 let useImperativeHandle;
+let useInsertionEffect;
 let useLayoutEffect;
 let useDebugValue;
 let useOpaqueIdentifier;
@@ -54,6 +55,7 @@ function initModules() {
   useRef = React.useRef;
   useDebugValue = React.useDebugValue;
   useImperativeHandle = React.useImperativeHandle;
+  useInsertionEffect = React.unstable_useInsertionEffect;
   useLayoutEffect = React.useLayoutEffect;
   useOpaqueIdentifier = React.unstable_useOpaqueIdentifier;
   forwardRef = React.forwardRef;
@@ -638,6 +640,22 @@ describe('ReactDOMServerHooks', () => {
       expect(domNode.textContent).toEqual('Count: 0');
     });
   });
+  describe('useInsertionEffect', () => {
+    // @gate experimental || www
+    it('should warn when invoked during render', async () => {
+      function Counter() {
+        useInsertionEffect(() => {
+          throw new Error('should not be invoked');
+        });
+
+        return <Text text="Count: 0" />;
+      }
+      const domNode = await serverRender(<Counter />, 1);
+      expect(clearYields()).toEqual(['Count: 0']);
+      expect(domNode.tagName).toEqual('SPAN');
+      expect(domNode.textContent).toEqual('Count: 0');
+    });
+  });
 
   describe('useLayoutEffect', () => {
     it('should warn when invoked during render', async () => {

packages/react-dom/src/server/ReactPartialRendererHooks.js

@@ -385,6 +385,22 @@ function useRef<T>(initialValue: T): {|current: T|} {
   }
 }
 
+function useInsertionEffect(
+  create: () => mixed,
+  inputs: Array<mixed> | void | null,
+) {
+  if (__DEV__) {
+    currentHookNameInDev = 'useInsertionEffect';
+    console.error(
+      'useInsertionEffect does nothing on the server, because its effect cannot ' +
+        "be encoded into the server renderer's output format. This will lead " +
+        'to a mismatch between the initial, non-hydrated UI and the intended ' +
+        'UI. To avoid this, useInsertionEffect should only be used in ' +
+        'components that render exclusively on the client.',
+    );
+  }
+}
+
 export function useLayoutEffect(
   create: () => (() => void) | void,
   inputs: Array<mixed> | void | null,
@@ -508,6 +524,7 @@ export const Dispatcher: DispatcherType = {
   useReducer,
   useRef,
   useState,
+  useInsertionEffect,
   useLayoutEffect,
   useCallback,
   // useImperativeHandle is not run in the server environment

packages/react-reconciler/src/ReactFiberCommitWork.new.js

@@ -136,6 +136,7 @@ import {
   NoFlags as NoHookEffect,
   HasEffect as HookHasEffect,
   Layout as HookLayout,
+  Insertion as HookInsertion,
   Passive as HookPassive,
 } from './ReactHookEffectTags';
 import {didWarnAboutReassigningProps} from './ReactFiberBeginWork.new';
@@ -525,6 +526,8 @@ function commitHookEffectListMount(tag: HookFlags, finishedWork: Fiber) {
             let hookName;
             if ((effect.tag & HookLayout) !== NoFlags) {
               hookName = 'useLayoutEffect';
+            } else if ((effect.tag & HookInsertion) !== NoFlags) {
+              hookName = 'useInsertionEffect';
             } else {
               hookName = 'useEffect';
             }
@@ -1153,7 +1156,10 @@ function commitUnmount(
           do {
             const {destroy, tag} = effect;
             if (destroy !== undefined) {
-              if ((tag & HookLayout) !== NoHookEffect) {
+              if (
+                (tag & HookInsertion) !== NoHookEffect ||
+                (tag & HookLayout) !== NoHookEffect
+              ) {
                 if (
                   enableProfilerTimer &&
                   enableProfilerCommitHooks &&
@@ -1738,6 +1744,13 @@ function commitWork(current: Fiber | null, finishedWork: Fiber): void {
       case ForwardRef:
       case MemoComponent:
       case SimpleMemoComponent: {
+        commitHookEffectListUnmount(
+          HookInsertion | HookHasEffect,
+          finishedWork,
+          finishedWork.return,
+        );
+        commitHookEffectListMount(HookInsertion | HookHasEffect, finishedWork);
+
         // Layout effects are destroyed during the mutation phase so that all
         // destroy functions for all fibers are called before any create functions.
         // This prevents sibling component effects from interfering with each other,
@@ -1810,6 +1823,12 @@ function commitWork(current: Fiber | null, finishedWork: Fiber): void {
     case ForwardRef:
     case MemoComponent:
     case SimpleMemoComponent: {
+      commitHookEffectListUnmount(
+        HookInsertion | HookHasEffect,
+        finishedWork,
+        finishedWork.return,
+      );
+      commitHookEffectListMount(HookInsertion | HookHasEffect, finishedWork);
       // Layout effects are destroyed during the mutation phase so that all
       // destroy functions for all fibers are called before any create functions.
       // This prevents sibling component effects from interfering with each other,