feat: form.for(id) now implicitly sets id on form object (#14623)

* feat: `form.for(id)` now implicitly sets id on form object

* fix

* client

* docs

* enforce id type

* preserve type of id

---------

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

Author: dummdidumm

.changeset/dry-garlics-yawn.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: `form.for(id)` now implicitly sets id on form object

documentation/docs/20-core-concepts/60-remote-functions.md

@@ -755,6 +755,27 @@ await submit().updates(
 
 The override will be applied immediately, and released when the submission completes (or fails).
 
+### Multiple instances of a form
+
+Some forms may be repeated as part of a list. In this case you can create separate instances of a form function via `for(id)` to achieve isolation.
+
+```svelte
+<!--- file: src/routes/todos/+page.svelte --->
+<script>
+	import { getTodos, modifyTodo } from '../data.remote';
+</script>
+
+<h1>Todos</h1>
+
+{#each await getTodos() as todo}
+	{@const modify = modifyTodo.for(todo.id)}
+	<form {...modify}>
+		<!-- -->
+		<button disabled={!!modify.pending}>save changes</button>
+	</form>
+{/each}
+```
+
 ### buttonProps
 
 By default, submitting a form will send a request to the URL indicated by the `<form>` element's [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form#attributes_for_form_submission) attribute, which in the case of a remote function is a property on the form object generated by SvelteKit.

packages/kit/src/exports/public.d.ts

@@ -1937,6 +1937,14 @@ export interface RemoteFormIssue {
 	message: string;
 }
 
+// If the schema specifies `id` as a string or number, ensure that `for(...)`
+// only accepts that type. Otherwise, accept `string | number`
+type ExtractId<Input> = Input extends { id: infer Id }
+	? Id extends string | number
+		? Id
+		: string | number
+	: string | number;
+
 /**
  * The return value of a remote `form` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#form) for full documentation.
  */
@@ -1961,8 +1969,8 @@ export type RemoteForm<Input extends RemoteFormInput | void, Output> = {
 		[attachment: symbol]: (node: HTMLFormElement) => void;
 	};
 	/**
-	 * Create an instance of the form for the given key.
-	 * The key is stringified and used for deduplication to potentially reuse existing instances.
+	 * Create an instance of the form for the given `id`.
+	 * The `id` is stringified and used for deduplication to potentially reuse existing instances.
 	 * Useful when you have multiple forms that use the same remote form action, for example in a loop.
 	 * ```svelte
 	 * {#each todos as todo}
@@ -1974,7 +1982,7 @@ export type RemoteForm<Input extends RemoteFormInput | void, Output> = {
 	 *	{/each}
 	 * ```
 	 */
-	for(key: string | number | boolean): Omit<RemoteForm<Input, Output>, 'for'>;
+	for(id: ExtractId<Input>): Omit<RemoteForm<Input, Output>, 'for'>;
 	/** Preflight checks */
 	preflight(schema: StandardSchemaV1<Input, any>): RemoteForm<Input, Output>;
 	/** Validate the form contents programmatically */

packages/kit/src/runtime/app/server/remote/form.js

@@ -105,10 +105,16 @@ export function form(validate_or_fn, maybe_fn) {
 			/** @param {FormData} form_data */
 			fn: async (form_data) => {
 				const validate_only = form_data.get('sveltekit:validate_only') === 'true';
-				form_data.delete('sveltekit:validate_only');
 
 				let data = maybe_fn ? convert_formdata(form_data) : undefined;
 
+				if (data && data.id === undefined) {
+					const id = form_data.get('sveltekit:id');
+					if (typeof id === 'string') {
+						data.id = JSON.parse(id);
+					}
+				}
+
 				// TODO 3.0 remove this warning
 				if (DEV && !data) {
 					const error = () => {

packages/kit/src/runtime/client/remote-functions/form.svelte.js

@@ -82,13 +82,25 @@ export function form(id) {
 
 		let submitted = false;
 
+		/**
+		 * @param {FormData} form_data
+		 * @returns {Record<string, any>}
+		 */
+		function convert(form_data) {
+			const data = convert_formdata(form_data);
+			if (key !== undefined && !form_data.has('id')) {
+				data.id = key;
+			}
+			return data;
+		}
+
 		/**
 		 * @param {HTMLFormElement} form
 		 * @param {FormData} form_data
 		 * @param {Parameters<RemoteForm<any, any>['enhance']>[0]} callback
 		 */
 		async function handle_submit(form, form_data, callback) {
-			const data = convert_formdata(form_data);
+			const data = convert(form_data);
 
 			submitted = true;
 
@@ -505,9 +517,7 @@ export function form(id) {
 					/** @type {readonly StandardSchemaV1.Issue[]} */
 					let array = [];
 
-					const validated = await preflight_schema?.['~standard'].validate(
-						convert_formdata(form_data)
-					);
+					const validated = await preflight_schema?.['~standard'].validate(convert(form_data));
 
 					if (validated?.issues) {
 						array = validated.issues;

packages/kit/src/runtime/form-utils.svelte.js

@@ -31,6 +31,10 @@ export function convert_formdata(data) {
 	let result = Object.create(null); // guard against prototype pollution
 
 	for (let key of data.keys()) {
+		if (key.startsWith('sveltekit:')) {
+			continue;
+		}
+
 		const is_array = key.endsWith('[]');
 		/** @type {any[]} */
 		let values = data.getAll(key);

packages/kit/src/runtime/server/remote.js

@@ -37,7 +37,7 @@ export async function handle_remote_call(event, state, options, manifest, id) {
  * @param {string} id
  */
 async function handle_remote_call_internal(event, state, options, manifest, id) {
-	const [hash, name, prerender_args] = id.split('/');
+	const [hash, name, additional_args] = id.split('/');
 	const remotes = manifest._.remotes;
 
 	if (!remotes[hash]) error(404);
@@ -122,6 +122,11 @@ async function handle_remote_call_internal(event, state, options, manifest, id)
 			);
 			form_data.delete('sveltekit:remote_refreshes');
 
+			// If this is a keyed form instance (created via form.for(key)), add the key to the form data (unless already set)
+			if (additional_args) {
+				form_data.set('sveltekit:id', decodeURIComponent(additional_args));
+			}
+
 			const fn = info.fn;
 			const data = await with_request_store({ event, state }, () => fn(form_data));
 
@@ -151,7 +156,7 @@ async function handle_remote_call_internal(event, state, options, manifest, id)
 
 		const payload =
 			info.type === 'prerender'
-				? prerender_args
+				? additional_args
 				: /** @type {string} */ (
 						// new URL(...) necessary because we're hiding the URL from the user in the event object
 						new URL(event.request.url).searchParams.get('payload')
@@ -289,6 +294,12 @@ async function handle_remote_form_post_internal(event, state, manifest, id) {
 		const form_data = await event.request.formData();
 		const fn = /** @type {RemoteInfo & { type: 'form' }} */ (/** @type {any} */ (form).__).fn;
 
+		// If this is a keyed form instance (created via form.for(key)), add the key to the form data (unless already set)
+		if (action_id && !form_data.has('id')) {
+			// The action_id is URL-encoded JSON, decode and parse it
+			form_data.set('sveltekit:id', decodeURIComponent(action_id));
+		}
+
 		await with_request_store({ event, state }, () => fn(form_data));
 
 		// We don't want the data to appear on `let { form } = $props()`, which is why we're not returning it.

packages/kit/test/apps/basics/src/routes/remote/form/form.remote.ts

@@ -11,6 +11,7 @@ export const get_message = query(() => {
 
 export const set_message = form(
 	v.object({
+		id: v.optional(v.string()),
 		message: v.picklist(
 			['hello', 'goodbye', 'unexpected error', 'expected error', 'redirect'],
 			'message is invalid'
@@ -38,7 +39,7 @@ export const set_message = form(
 			await deferred.promise;
 		}
 
-		return message;
+		return message + (data.id ? ` (from: ${data.id})` : '');
 	}
 );
 

packages/kit/test/apps/basics/test/test.js

@@ -1786,7 +1786,7 @@ test.describe('remote functions', () => {
 			await expect(page.getByText('await get_message():')).toHaveText('await get_message(): hello');
 		}
 
-		await expect(page.getByText('scoped.result')).toHaveText('scoped.result: hello');
+		await expect(page.getByText('scoped.result')).toHaveText('scoped.result: hello (from: scoped)');
 		await expect(page.locator('[data-scoped] input')).toHaveValue('');
 	});
 
@@ -1808,7 +1808,9 @@ test.describe('remote functions', () => {
 			await expect(page.getByText('await get_message():')).toHaveText('await get_message(): hello');
 		}
 
-		await expect(page.getByText('enhanced.result')).toHaveText('enhanced.result: hello');
+		await expect(page.getByText('enhanced.result')).toHaveText(
+			'enhanced.result: hello (from: enhanced)'
+		);
 		await expect(page.locator('[data-enhanced] input')).toHaveValue('');
 	});
 

packages/kit/types/index.d.ts

@@ -1913,6 +1913,14 @@ declare module '@sveltejs/kit' {
 		message: string;
 	}
 
+	// If the schema specifies `id` as a string or number, ensure that `for(...)`
+	// only accepts that type. Otherwise, accept `string | number`
+	type ExtractId<Input> = Input extends { id: infer Id }
+		? Id extends string | number
+			? Id
+			: string | number
+		: string | number;
+
 	/**
 	 * The return value of a remote `form` function. See [Remote functions](https://svelte.dev/docs/kit/remote-functions#form) for full documentation.
 	 */
@@ -1937,8 +1945,8 @@ declare module '@sveltejs/kit' {
 			[attachment: symbol]: (node: HTMLFormElement) => void;
 		};
 		/**
-		 * Create an instance of the form for the given key.
-		 * The key is stringified and used for deduplication to potentially reuse existing instances.
+		 * Create an instance of the form for the given `id`.
+		 * The `id` is stringified and used for deduplication to potentially reuse existing instances.
 		 * Useful when you have multiple forms that use the same remote form action, for example in a loop.
 		 * ```svelte
 		 * {#each todos as todo}
@@ -1950,7 +1958,7 @@ declare module '@sveltejs/kit' {
 		 *	{/each}
 		 * ```
 		 */
-		for(key: string | number | boolean): Omit<RemoteForm<Input, Output>, 'for'>;
+		for(id: ExtractId<Input>): Omit<RemoteForm<Input, Output>, 'for'>;
 		/** Preflight checks */
 		preflight(schema: StandardSchemaV1<Input, any>): RemoteForm<Input, Output>;
 		/** Validate the form contents programmatically */