Automatically reset forms after action finishes (#28804)

This updates the behavior of form actions to automatically reset the
form's uncontrolled inputs after the action finishes.
This is a frequent feature request for people using actions and it
aligns the behavior of client-side form submissions more closely with
MPA form submissions.
It has no impact on controlled form inputs. It's the same as if you
called `form.reset()` manually, except React handles the timing of when
the reset happens, which is tricky/impossible to get exactly right in
userspace.
The reset shouldn't happen until the UI has updated with the result of
the action. So, resetting inside the action is too early.
Resetting in `useEffect` is better, but it's later than ideal because
any effects that run before it will observe the state of the form before
it's been reset.
It needs to happen in the mutation phase of the transition. More
specifically, after all the DOM mutations caused by the transition have
been applied. That way the `defaultValue` of the inputs are updated
before the values are reset. The idea is that the `defaultValue`
represents the current, canonical value sent by the server.
Note: this change has no effect on form submissions that aren't
triggered by an action.

Author: acdlite

packages/react-art/src/ReactFiberConfigART.js

@@ -490,3 +490,4 @@ export function waitForCommitToBeReady() {
 }
 
 exportconstNotPendingTransition=null;
+exportfunctionresetFormInstance(){}

packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js

@@ -3441,3 +3441,8 @@ function insertStylesheetIntoRoot(
 }
 
 exportconstNotPendingTransition: TransitionStatus=NotPending;
+
+exporttypeFormInstance=HTMLFormElement;
+exportfunctionresetFormInstance(form: FormInstance): void{
+form.reset();
+}

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

@@ -39,6 +39,7 @@ describe('ReactDOMForm', () => {
 letuseState;
 letSuspense;
 letstartTransition;
+letuse;
 lettextCache;
 letuseFormStatus;
 letuseActionState;
@@ -55,6 +56,7 @@ describe('ReactDOMForm', () => {
 useState=React.useState;
 Suspense=React.Suspense;
 startTransition=React.startTransition;
+use=React.use;
 useFormStatus=ReactDOM.useFormStatus;
 container=document.createElement('div');
 document.body.appendChild(container);
@@ -1334,4 +1336,82 @@ describe('ReactDOMForm', () => {
 assertLog(['1']);
 expect(container.textContent).toBe('1');
 });
+
+test('uncontrolled form inputs are reset after the action completes',async()=>{
+constformRef=React.createRef();
+constinputRef=React.createRef();
+constdivRef=React.createRef();
+
+functionApp({promiseForUsername}){
+// Make this suspensey to simulate RSC streaming.
+constusername=use(promiseForUsername);
+
+return(
+<form
+ref={formRef}
+action={asyncformData=>{
+constrawUsername=formData.get('username');
+constnormalizedUsername=rawUsername.trim().toLowerCase();
+
+Scheduler.log(`Async action started`);
+awaitgetText('Wait');
+
+// Update the app with new data. This is analagous to re-rendering
+// from the root with a new RSC payload.
+startTransition(()=>{
+root.render(
+<ApppromiseForUsername={getText(normalizedUsername)}/>,
+);
+});
+}}>
+<input
+ref={inputRef}
+text="text"
+name="username"
+defaultValue={username}
+/>
+<divref={divRef}>
+<Texttext={'Current username: '+username}/>
+</div>
+</form>
+);
+}
+
+// Initial render
+constroot=ReactDOMClient.createRoot(container);
+constpromiseForInitialUsername=getText('(empty)');
+awaitresolveText('(empty)');
+awaitact(()=>
+root.render(<ApppromiseForUsername={promiseForInitialUsername}/>),
+);
+assertLog(['Current username: (empty)']);
+expect(divRef.current.textContent).toEqual('Current username: (empty)');
+
+// Dirty the uncontrolled input
+inputRef.current.value=' AcdLite ';
+
+// Submit the form. This will trigger an async action.
+awaitsubmit(formRef.current);
+assertLog(['Async action started']);
+expect(inputRef.current.value).toBe(' AcdLite ');
+
+// Finish the async action. This will trigger a re-render from the root with
+// new data from the "server", which suspends.
+//
+// The form should not reset yet because we need to update `defaultValue`
+// first. So we wait for the render to complete.
+awaitact(()=>resolveText('Wait'));
+assertLog([]);
+// The DOM input is still dirty.
+expect(inputRef.current.value).toBe(' AcdLite ');
+// The React tree is suspended.
+expect(divRef.current.textContent).toEqual('Current username: (empty)');
+
+// Unsuspend and finish rendering. Now the form should be reset.
+awaitact(()=>resolveText('acdlite'));
+assertLog(['Current username: acdlite']);
+// The form was reset to the new value from the server.
+expect(inputRef.current.value).toBe('acdlite');
+expect(divRef.current.textContent).toEqual('Current username: acdlite');
+});
 });

packages/react-native-renderer/src/ReactFiberConfigFabric.js

@@ -515,6 +515,9 @@ export function waitForCommitToBeReady(): null {
 
 exportconstNotPendingTransition: TransitionStatus=null;
 
+exporttypeFormInstance=Instance;
+exportfunctionresetFormInstance(form: Instance): void{}
+
 // -------------------
 // Microtasks
 // -------------------

packages/react-native-renderer/src/ReactFiberConfigNative.js

@@ -549,3 +549,6 @@ export function waitForCommitToBeReady(): null {
 }
 
 exportconstNotPendingTransition: TransitionStatus=null;
+
+exporttypeFormInstance=Instance;
+exportfunctionresetFormInstance(form: Instance): void{}

packages/react-noop-renderer/src/createReactNoop.js

@@ -90,6 +90,8 @@ type SuspenseyCommitSubscription = {
 
 exporttypeTransitionStatus=mixed;
 
+exporttypeFormInstance=Instance;
+
 constNO_CONTEXT={};
 constUPPERCASE_CONTEXT={};
 if(__DEV__){
@@ -632,6 +634,8 @@ function createReactNoop(reconciler: Function, useMutation: boolean) {
 waitForCommitToBeReady,
 
 NotPendingTransition: (null: TransitionStatus),
+
+resetFormInstance(form: Instance){},
 };
 
 consthostConfig=useMutation

packages/react-reconciler/src/ReactFiberCommitWork.js

@@ -15,6 +15,7 @@ import type {
 ChildSet,
 UpdatePayload,
 HoistableRoot,
+FormInstance,
 }from'./ReactFiberConfig';
 importtype{Fiber,FiberRoot}from'./ReactInternalTypes';
 importtype{Lanes}from'./ReactFiberLane';
@@ -97,6 +98,7 @@ import {
 Visibility,
 ShouldSuspendCommit,
 MaySuspendCommit,
+FormReset,
 }from'./ReactFiberFlags';
 importgetComponentNameFromFiberfrom'react-reconciler/src/getComponentNameFromFiber';
 import{
@@ -163,6 +165,7 @@ import {
 prepareToCommitHoistables,
 suspendInstance,
 suspendResource,
+resetFormInstance,
 }from'./ReactFiberConfig';
 import{
 captureCommitPhaseError,
@@ -226,6 +229,9 @@ if (__DEV__) {
 let offscreenSubtreeIsHidden: boolean=false;
 let offscreenSubtreeWasHidden: boolean=false;
 
+// Used to track if a form needs to be reset at the end of the mutation phase.
+letneedsFormReset=false;
+
 constPossiblyWeakSet=typeofWeakSet==='function' ? WeakSet : Set;
 
 letnextEffect: Fiber|null=null;
@@ -2776,6 +2782,20 @@ function commitMutationEffectsOnFiber(
 }
 }
 }
+
+if(flags&FormReset){
+needsFormReset=true;
+if(__DEV__){
+if(finishedWork.type!=='form'){
+// Paranoid coding. In case we accidentally start using the
+// FormReset bit for something else.
+console.error(
+'Unexpected host component type. Expected a form. This is a '+
+'bug in React.',
+);
+}
+}
+}
 }
 return;
 }
@@ -2852,6 +2872,21 @@ function commitMutationEffectsOnFiber(
 }
 }
 }
+
+if(needsFormReset){
+// A form component requested to be reset during this commit. We do this
+// after all mutations in the rest of the tree so that `defaultValue`
+// will already be updated. This way you can update `defaultValue` using
+// data sent by the server as a result of the form submission.
+//
+// Theoretically we could check finishedWork.subtreeFlags & FormReset,
+// but the FormReset bit is overloaded with other flags used by other
+// fiber types. So this extra variable lets us skip traversing the tree
+// except when a form was actually submitted.
+needsFormReset=false;
+recursivelyResetForms(finishedWork);
+}
+
 return;
 }
 caseHostPortal: {
@@ -3091,6 +3126,24 @@ function commitReconciliationEffects(finishedWork: Fiber) {
 }
 }
 
+functionrecursivelyResetForms(parentFiber: Fiber){
+if(parentFiber.subtreeFlags&FormReset){
+letchild=parentFiber.child;
+while(child!==null){
+resetFormOnFiber(child);
+child=child.sibling;
+}
+}
+}
+
+functionresetFormOnFiber(fiber: Fiber){
+recursivelyResetForms(fiber);
+if(fiber.tag===HostComponent&&fiber.flags&FormReset){
+constformInstance: FormInstance=fiber.stateNode;
+resetFormInstance(formInstance);
+}
+}
+
 exportfunctioncommitLayoutEffects(
 finishedWork: Fiber,
 root: FiberRoot,

packages/react-reconciler/src/ReactFiberFlags.js

@@ -42,6 +42,7 @@ export const StoreConsistency = /* */ 0b0000000000000100000000000000
 exportconstScheduleRetry=StoreConsistency;
 exportconstShouldSuspendCommit=Visibility;
 exportconstDidDefer=ContentReset;
+exportconstFormReset=Snapshot;
 
 exportconstLifecycleEffectMask=
 Passive|Update|Callback|Ref|Snapshot|StoreConsistency;
@@ -95,7 +96,8 @@ export const MutationMask =
 ContentReset|
 Ref|
 Hydrating|
-Visibility;
+Visibility|
+FormReset;
 exportconstLayoutMask=Update|Callback|Ref|Visibility;
 
 // TODO: Split into PassiveMountMask and PassiveUnmountMask

packages/react-reconciler/src/ReactFiberHooks.js

@@ -91,6 +91,7 @@ import {
 StoreConsistency,
 MountLayoutDevasMountLayoutDevEffect,
 MountPassiveDevasMountPassiveDevEffect,
+FormReset,
 }from'./ReactFiberFlags';
 import{
 HasEffectasHookHasEffect,
@@ -844,15 +845,29 @@ export function TransitionAwareHostComponent(): TransitionStatus {
 if(!enableAsyncActions){
 thrownewError('Notimplemented.');
 }
+
 constdispatcher: any=ReactSharedInternals.H;
 const[maybeThenable]=dispatcher.useState();
+letnextState;
 if(typeofmaybeThenable.then==='function'){
 constthenable: Thenable<TransitionStatus>=(maybeThenable: any);
-returnuseThenable(thenable);
+nextState=useThenable(thenable);
 }else{
 conststatus: TransitionStatus=maybeThenable;
-returnstatus;
+nextState=status;
+}
+
+// The "reset state" is an object. If it changes, that means something
+// requested that we reset the form.
+const[nextResetState]=dispatcher.useState();
+constprevResetState=
+currentHook!==null ? currentHook.memoizedState : null;
+if(prevResetState!==nextResetState){
+// Schedule a form reset
+currentlyRenderingFiber.flags|=FormReset;
 }
+
+returnnextState;
 }
 
 exportfunctioncheckDidRenderIdHook(): boolean{
@@ -2948,7 +2963,30 @@ export function startHostTransition<F>(
 next: null,
 };
 
-// Add the state hook to both fiber alternates. The idea is that the fiber
+// We use another state hook to track whether the form needs to be reset.
+// The state is an empty object. To trigger a reset, we update the state
+// to a new object. Then during rendering, we detect that the state has
+// changed and schedule a commit effect.
+constinitialResetState={};
+constnewResetStateQueue: UpdateQueue<Object,Object>={
+pending: null,
+lanes: NoLanes,
+// We're going to cheat and intentionally not create a bound dispatch
+// method, because we can call it directly in startTransition.
+dispatch: (null: any),
+lastRenderedReducer: basicStateReducer,
+lastRenderedState: initialResetState,
+};
+constresetStateHook: Hook={
+memoizedState: initialResetState,
+baseState: initialResetState,
+baseQueue: null,
+queue: newResetStateQueue,
+next: null,
+};
+stateHook.next=resetStateHook;
+
+// Add the hook list to both fiber alternates. The idea is that the fiber
 // had this hook all along.
 formFiber.memoizedState=stateHook;
 constalternate=formFiber.alternate;
@@ -2968,10 +3006,41 @@ export function startHostTransition<F>(
 NoPendingHostTransition,
 // TODO: We can avoid this extra wrapper, somehow. Figure out layering
 // once more of this function is implemented.
-()=>callback(formData),
+()=>{
+// Automatically reset the form when the action completes.
+requestFormReset(formFiber);
+returncallback(formData);
+},
 );
 }
 
+functionrequestFormReset(formFiber: Fiber){
+consttransition=requestCurrentTransition();
+
+if(__DEV__){
+if(transition===null){
+// An optimistic update occurred, but startTransition is not on the stack.
+// The form reset will be scheduled at default (sync) priority, which
+// is probably not what the user intended. Most likely because the
+// requestFormReset call happened after an `await`.
+// TODO: Theoretically, requestFormReset is still useful even for
+// non-transition updates because it allows you to update defaultValue
+// synchronously and then wait to reset until after the update commits.
+// I've chosen to warn anyway because it's more likely the `await` mistake
+// described above. But arguably we shouldn't.
+ console.error(
+'requestFormReset was called outside a transition or action. To '+
+'fix, move to an action, or wrap with startTransition.',
+);
+}
+}
+
+constnewResetState={};
+constresetStateHook: Hook=(formFiber.memoizedState.next: any);
+constresetStateQueue=resetStateHook.queue;
+dispatchSetState(formFiber,resetStateQueue,newResetState);
+}
+
 functionmountTransition(): [
 boolean,
 (callback: ()=>void,options?: StartTransitionOptions)=>void,

packages/react-reconciler/src/forks/ReactFiberConfig.custom.js

@@ -39,6 +39,7 @@ export opaque type TimeoutHandle = mixed; // eslint-disable-line no-undef
 exportopaquetypeNoTimeout=mixed;// eslint-disable-line no-undef
 exportopaquetypeRendererInspectionConfig=mixed;// eslint-disable-line no-undef
 exportopaquetypeTransitionStatus=mixed;// eslint-disable-line no-undef
+exportopaquetypeFormInstance=mixed;// eslint-disable-line no-undef
 exporttypeEventResponder=any;
 
 exportconstgetPublicInstance=$$$config.getPublicInstance;
@@ -78,6 +79,7 @@ export const startSuspendingCommit = $$$config.startSuspendingCommit;
 exportconstsuspendInstance=$$$config.suspendInstance;
 exportconstwaitForCommitToBeReady=$$$config.waitForCommitToBeReady;
 exportconstNotPendingTransition=$$$config.NotPendingTransition;
+exportconstresetFormInstance=$$$config.resetFormInstance;
 
 // -------------------
 // Microtasks