Add remote form factory options

sillvva · sillvva · commit e6ebca5c7c6c · 2025-11-03T09:57:16.000-06:00
diff --git a/documentation/docs/20-core-concepts/60-remote-functions.md b/documentation/docs/20-core-concepts/60-remote-functions.md
@@ -540,11 +540,15 @@ For client-side validation, you can specify a _preflight_ schema which will popu
 		title: v.pipe(v.string(), v.nonEmpty()),
 		content: v.pipe(v.string(), v.nonEmpty())
 	});
+
+	const form = createPost(+++{
+		preflight: schema
+	}+++)
 </script>
 
 <h1>Create a new post</h1>
 
-<form {...+++createPost().preflight(schema)+++}>
+<form {...form}>
 	<!-- -->
 </form>
 ```
@@ -812,11 +816,43 @@ Some forms may be repeated as part of a list. In this case you can create separa
 	{@const modify = modifyTodo(todo.id)}
 	<form {...modify}>
 		<!-- -->
-		<button disabled={!!modify.pending}>save changes</button>
+		<button disabled={!!modify.pending}>Save Changes</button>
 	</form>
 {/each}
 ```
 
+### Initial form data
+
+There are times when you want a form to be pre-filled with certain values when it first renders. For example, you might want to populate a form with values fetched from the server or set default values for a new data entry.
+
+You can do this by passing the `initialData` option when creating a form instance. This will set the initial state of the form fields, both for their values and for client-side validation.
+
+Here's an example of how to set initial form data using `initialData`:
+
+```svelte
+<!--- file: src/routes/edit-post/[postId]/+page.svelte --->
+<script>
+	import { getPost, editPost } from '../data.remote';
+
+	const { params } = $props();
+
+	// Fetch the data to pre-fill the form
+	const data = $derived(await getPost(params.postId));
+
+	// Pass initialData when creating the form instance
+	const form = $derived(editPost({
+		initialData: data
+	}));
+</script>
+
+<form {...form}>
+	<!-- Render your form fields here, which will use the initial values from `data` -->
+	<button disabled={!!form.pending}>Save Changes</button>
+</form>
+```
+
+You can also pass a partial object to `initialData` if you only want to set values for some fields. If `initialData` is omitted, the fields will be empty by default.
+
 ### 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.
diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts
@@ -15,7 +15,9 @@ import {
 	PrerenderUnseenRoutesHandlerValue,
 	PrerenderOption,
 	RequestOptions,
-	RouteSegment
+	RouteSegment,
+	DeepPartial,
+	ExtractId
 } from '../types/private.js';
 import { BuildData, SSRNodeLoader, SSRRoute, ValidatedConfig } from 'types';
 import { SvelteConfig } from '@sveltejs/vite-plugin-svelte';
@@ -1969,14 +1971,6 @@ export interface RemoteFormAllIssue extends RemoteFormIssue {
 	path: Array<string | number>;
 }
 
-// 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;
-
 /**
  * Recursively maps an input type to a structure where each field can create a validation issue.
  * This mirrors the runtime behavior of the `invalid` proxy passed to form handlers.
@@ -2007,8 +2001,19 @@ type InvalidField<T> =
 export type Invalid<Input = any> = ((...issues: Array<string | StandardSchemaV1.Issue>) => never) &
 	InvalidField<Input>;
 
+export type RemoteFormFactoryOptions<Input extends RemoteFormInput | void> = {
+	/** Optional key to create a scoped instance */
+	key?: ExtractId<Input>;
+	/** Client-side preflight schema for validation before submit */
+	preflight?: StandardSchemaV1<Input, any>;
+	/** Initial input values for the form fields */
+	initialData?: DeepPartial<Input>;
+	/** Reset the form values after successful submission (default: true) */
+	resetAfterSuccess?: boolean;
+};
+
 export type RemoteFormFactory<Input extends RemoteFormInput | void, Output> = (
-	key?: ExtractId<Input>
+	keyOrOptions?: ExtractId<Input> | RemoteFormFactoryOptions<Input>
 ) => RemoteForm<Input, Output>;
 
 /**
diff --git a/packages/kit/src/runtime/app/server/remote/form.js b/packages/kit/src/runtime/app/server/remote/form.js
@@ -1,5 +1,5 @@
-/** @import { RemoteFormInput, RemoteForm, RemoteFormFactory } from '@sveltejs/kit' */
-/** @import { InternalRemoteFormIssue, MaybePromise, RemoteInfo } from 'types' */
+/** @import { RemoteFormInput, RemoteForm, RemoteFormFactory, RemoteFormFactoryOptions } from '@sveltejs/kit' */
+/** @import { ExtractId, InternalRemoteFormIssue, MaybePromise, RemoteInfo } from 'types' */
 /** @import { StandardSchemaV1 } from '@standard-schema/spec' */
 import { get_request_store } from '@sveltejs/kit/internal/server';
 import { DEV } from 'esm-env';
@@ -165,7 +165,8 @@ export function form(validate_or_fn, maybe_fn) {
 	};
 
 	/**
-	 * @param {string | number} [key]
+	 * @param {ExtractId<Input>} [key]
+	 * @returns {RemoteForm<Input, Output>}
 	 */
 	function create_instance(key) {
 		const { state } = get_request_store();
@@ -294,7 +295,22 @@ export function form(validate_or_fn, maybe_fn) {
 	}
 
 	/** @type {RemoteFormFactory<Input, Output>} */
-	const factory = (key) => create_instance(key);
+	const factory = (arg) => {
+		/** @type {RemoteFormFactoryOptions<Input> | undefined } */
+		const options = arg && typeof arg === 'object' ? arg : undefined;
+		const key = options ? options.key : /** @type {ExtractId<Input> | undefined} */ (arg);
+
+		const instance = create_instance(key);
+
+		if (options?.initialData) {
+			// seed initial input into cache for SSR
+			const { state } = get_request_store();
+			const cache = get_cache(/** @type any */ (instance).__, state);
+			(cache[''] ??= {}).input = options.initialData;
+		}
+
+		return instance;
+	};
 
 	Object.defineProperty(factory, '__', { value: __ });
 
diff --git a/packages/kit/src/runtime/client/remote-functions/form.svelte.js b/packages/kit/src/runtime/client/remote-functions/form.svelte.js
@@ -1,6 +1,6 @@
 /** @import { StandardSchemaV1 } from '@standard-schema/spec' */
-/** @import { RemoteFormInput, RemoteForm, RemoteQueryOverride, RemoteFormFactory } from '@sveltejs/kit' */
-/** @import { InternalRemoteFormIssue, RemoteFunctionResponse } from 'types' */
+/** @import { RemoteFormInput, RemoteForm, RemoteQueryOverride, RemoteFormFactory, RemoteFormFactoryOptions } from '@sveltejs/kit' */
+/** @import { ExtractId, InternalRemoteFormIssue, RemoteFunctionResponse } from 'types' */
 /** @import { Query } from './query.svelte.js' */
 import { app_dir, base } from '$app/paths/internal/client';
 import * as devalue from 'devalue';
@@ -53,8 +53,9 @@ export function form(id) {
 	/** @type {Map<any, { count: number, instance: RemoteForm<T, U> }>} */
 	const instances = new Map();
 
-	/** @param {string | number | boolean} [key] */
-	function create_instance(key) {
+	/** @param {RemoteFormFactoryOptions<T>} options */
+	function create_instance(options) {
+		const { key, resetAfterSuccess = true } = options;
 		const action_id = id + (key !== undefined ? `/${JSON.stringify(key)}` : '');
 		const action = '?/remote=' + encodeURIComponent(action_id);
 
@@ -411,7 +412,7 @@ export function form(id) {
 		instance[createAttachmentKey()] = create_attachment(
 			form_onsubmit(({ submit, form }) =>
 				submit().then(() => {
-					if (!issues.$) {
+					if (!issues.$ && resetAfterSuccess) {
 						form.reset();
 					}
 				})
@@ -452,7 +453,7 @@ export function form(id) {
 			formaction: action,
 			onclick: form_action_onclick(({ submit, form }) =>
 				submit().then(() => {
-					if (!issues.$) {
+					if (!issues.$ && resetAfterSuccess) {
 						form.reset();
 					}
 				})
@@ -588,8 +589,26 @@ export function form(id) {
 	}
 
 	/** @type {RemoteFormFactory<T, U>} */
-	const factory = (key) => {
-		const entry = instances.get(key) ?? { count: 0, instance: create_instance(key) };
+	const factory = (arg) => {
+		/** @type {RemoteFormFactoryOptions<T> | undefined } */
+		const options = arg && typeof arg === 'object' ? arg : undefined;
+		const key = options ? options.key : /** @type {ExtractId<T> | undefined} */ (arg);
+
+		let entry = instances.get(key);
+		if (!entry) {
+			const instance = create_instance(options ?? { key });
+
+			if (options?.preflight) {
+				instance.preflight(options.preflight);
+			}
+			// seed optional initial input data
+			if (options?.initialData) {
+				instance.fields.set(options.initialData);
+			}
+
+			entry = { count: 0, instance };
+			instances.set(key, entry);
+		}
 
 		try {
 			$effect.pre(() => {
diff --git a/packages/kit/src/types/private.d.ts b/packages/kit/src/types/private.d.ts
@@ -241,3 +241,19 @@ export interface RouteSegment {
 }
 
 export type TrailingSlash = 'never' | 'always' | 'ignore';
+
+export type DeepPartial<T> = T extends Record<PropertyKey, unknown> | unknown[]
+	? {
+			[K in keyof T]?: T[K] extends Record<PropertyKey, unknown> | unknown[]
+				? DeepPartial<T[K]>
+				: T[K];
+		}
+	: T | undefined;
+
+// If the schema specifies `id` as a string or number, ensure that `for(...)`
+// only accepts that type. Otherwise, accept `string | number`
+export type ExtractId<Input> = Input extends { id: infer Id }
+	? Id extends string | number
+		? Id
+		: string | number
+	: string | number;
diff --git a/packages/kit/test/apps/basics/src/routes/remote/form/+page.svelte b/packages/kit/test/apps/basics/src/routes/remote/form/+page.svelte
@@ -8,11 +8,14 @@
 
 	const message = get_message();
 
-	const scoped = set_message('scoped');
+	const scoped = set_message({
+		key: 'scoped',
+		initialData: {
+			message: 'hello'
+		},
+		resetAfterSuccess: false
+	});
 	const enhanced = set_message('enhanced');
-	const message_form = set_message();
-	const reverse_message_form = set_reverse_message();
-	const deferreds = resolve_deferreds();
 </script>
 
 <p>message.current: {message.current}</p>
@@ -24,20 +27,20 @@
 
 <hr />
 
-<form data-unscoped {...message_form}>
-	{#if message_form.fields.message.issues()}
-		<p>{message_form.fields.message.issues()[0].message}</p>
+<form data-unscoped {...set_message()}>
+	{#if set_message().fields.message.issues()}
+		<p>{set_message().fields.message.issues()[0].message}</p>
 	{/if}
 
-	<input {...message_form.fields.message.as('text')} />
+	<input {...set_message().fields.message.as('text')} />
 	<button>set message</button>
-	<button {...reverse_message_form.buttonProps}>set reverse message</button>
+	<button {...set_reverse_message().buttonProps}>set reverse message</button>
 </form>
 
-<p>set_message.input.message: {message_form.fields.message.value()}</p>
-<p>set_message.pending: {message_form.pending}</p>
-<p>set_message.result: {message_form.result}</p>
-<p>set_reverse_message.result: {reverse_message_form.result}</p>
+<p>set_message.input.message: {set_message().fields.message.value()}</p>
+<p>set_message.pending: {set_message().pending}</p>
+<p>set_message.result: {set_message().result}</p>
+<p>set_reverse_message.result: {set_reverse_message().result}</p>
 
 <hr />
 
@@ -76,6 +79,6 @@
 
 <hr />
 
-<form {...deferreds}>
+<form {...resolve_deferreds()}>
 	<button>resolve deferreds</button>
 </form>
diff --git a/packages/kit/test/apps/basics/test/test.js b/packages/kit/test/apps/basics/test/test.js
@@ -1772,10 +1772,9 @@ test.describe('remote functions', () => {
 		);
 	});
 
-	test('form scoping with for(...) works', async ({ page, javaScriptEnabled }) => {
+	test('form scoping works', async ({ page, javaScriptEnabled }) => {
 		await page.goto('/remote/form');
 
-		await page.fill('[data-scoped] input', 'hello');
 		await page.getByText('set scoped message').click();
 
 		if (javaScriptEnabled) {
@@ -1788,7 +1787,7 @@ test.describe('remote functions', () => {
 		}
 
 		await expect(page.getByText('scoped.result')).toHaveText('scoped.result: hello (from: scoped)');
-		await expect(page.locator('[data-scoped] input')).toHaveValue('');
+		await expect(page.locator('[data-scoped] input')).toHaveValue('hello');
 	});
 
 	test('form enhance(...) works', async ({ page, javaScriptEnabled }) => {
diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts
@@ -1945,14 +1945,6 @@ declare module '@sveltejs/kit' {
 		path: Array<string | number>;
 	}
 
-	// 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;
-
 	/**
 	 * Recursively maps an input type to a structure where each field can create a validation issue.
 	 * This mirrors the runtime behavior of the `invalid` proxy passed to form handlers.
@@ -1983,8 +1975,19 @@ declare module '@sveltejs/kit' {
 	export type Invalid<Input = any> = ((...issues: Array<string | StandardSchemaV1.Issue>) => never) &
 		InvalidField<Input>;
 
+	export type RemoteFormFactoryOptions<Input extends RemoteFormInput | void> = {
+		/** Optional key to create a scoped instance */
+		key?: ExtractId<Input>;
+		/** Client-side preflight schema for validation before submit */
+		preflight?: StandardSchemaV1<Input, any>;
+		/** Initial input values for the form fields */
+		initialData?: DeepPartial<Input>;
+		/** Reset the form values after successful submission (default: true) */
+		resetAfterSuccess?: boolean;
+	};
+
 	export type RemoteFormFactory<Input extends RemoteFormInput | void, Output> = (
-		key?: ExtractId<Input>
+		keyOrOptions?: ExtractId<Input> | RemoteFormFactoryOptions<Input>
 	) => RemoteForm<Input, Output>;
 
 	/**
@@ -2368,6 +2371,22 @@ declare module '@sveltejs/kit' {
 	}
 
 	type TrailingSlash = 'never' | 'always' | 'ignore';
+
+	type DeepPartial<T> = T extends Record<PropertyKey, unknown> | unknown[]
+		? {
+				[K in keyof T]?: T[K] extends Record<PropertyKey, unknown> | unknown[]
+					? DeepPartial<T[K]>
+					: T[K];
+			}
+		: T | undefined;
+
+	// 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;
 	interface Asset {
 		file: string;
 		size: number;
