[feat] add reset option to update method of enhance (#7326)

It's not uncommon to want the form values be preserved, so it makes sense to have this configurable

Co-authored-by: gtmnayan <[email protected]>
Co-authored-by: Rich Harris <[email protected]>

Author: 3 people

.changeset/nervous-students-march.md

@@ -0,0 +1,6 @@
+---
+'create-svelte': patch
+'@sveltejs/kit': patch
+---
+
+[feat] add reset option to update method of enhance

documentation/docs/06-form-actions.md

@@ -250,7 +250,7 @@ The easiest way to progressively enhance a form is to add the `use:enhance` acti
 Without an argument, `use:enhance` will emulate the browser-native behaviour, just without the full-page reloads. It will:
 
 - update the `form` property, `$page.form` and `$page.status` on a successful or invalid response, but only if the action is on the same page you're submitting from. So for example if your form looks like `<form action="/somewhere/else" ..>`, `form` and `$page` will _not_ be updated. This is because in the native form submission case you would be redirected to the page the action is on.
-- invalidate all data using `invalidateAll` on a successful response
+- reset the `<form>` element and invalidate all data using `invalidateAll` on a successful response
 - call `goto` on a redirect response
 - render the nearest `+error` boundary if an error occurs
 

packages/create-svelte/templates/default/src/routes/sverdle/+page.svelte

@@ -1,8 +1,7 @@
 <script lang="ts">
 	import { confetti } from '@neoconfetti/svelte';
-	import { applyAction, enhance } from '$app/forms';
+	import { enhance } from '$app/forms';
 	import type { PageData, ActionData } from './$types';
-	import { invalidateAll } from '$app/navigation';
 
 	/** @type {import('./$types').PageData} */
 	export let data: PageData;
@@ -84,11 +83,8 @@
 	action="?/enter"
 	use:enhance={() => {
 		// prevent default callback from resetting the form
-		return async ({ result }) => {
-			if (result.type === 'success') {
-				await invalidateAll();
-			}
-			await applyAction(result);
+		return ({ update }) => {
+			update({ reset: false });
 		};
 	}}
 >

packages/kit/src/runtime/app/forms.js

@@ -21,11 +21,14 @@ export function enhance(form, submit = () => {}) {
 	 * @param {{
 	 *   action: URL;
 	 *   result: import('types').ActionResult;
+	 *   reset?: boolean
 	 * }} opts
 	 */
-	const fallback_callback = async ({ action, result }) => {
+	const fallback_callback = async ({ action, result, reset }) => {
 		if (result.type === 'success') {
-			form.reset();
+			if (reset !== false) {
+				form.reset();
+			}
 			await invalidateAll();
 		}
 
@@ -97,7 +100,7 @@ export function enhance(form, submit = () => {}) {
 			action,
 			data,
 			form,
-			update: () => fallback_callback({ action, result }),
+			update: (opts) => fallback_callback({ action, result, reset: opts?.reset }),
 			// @ts-expect-error generic constraints stuff we don't care about
 			result,
 			// TODO remove for 1.0

packages/kit/types/ambient.d.ts

@@ -110,7 +110,11 @@ declare module '$app/forms' {
 				form: HTMLFormElement;
 				action: URL;
 				result: ActionResult<Success, Invalid>;
-				update: () => Promise<void>;
+				/**
+				 * Call this to get the default behavior of a form submission response.
+				 * @param options Set `reset: false` if you don't want the `<form>` values to be reset after a successful submission.
+				 */
+				update: (options?: { reset: boolean }) => Promise<void>;
 		  }) => void);
 
 	/**
@@ -133,7 +137,7 @@ declare module '$app/forms' {
 		 * If this function or its return value isn't set, it
 		 * - falls back to updating the `form` prop with the returned data if the action is one same page as the form
 		 * - updates `$page.status`
-		 * - invalidates all data in case of successful submission with no redirect response
+		 * - resets the `<form>` element and invalidates all data in case of successful submission with no redirect response
 		 * - redirects in case of a redirect response
 		 * - redirects to the nearest error page in case of an unexpected error
 		 *