Recipe: Server-Side Implementation

Relevant source files

The following files were used as context for generating this wiki page:

• packages/remotes/README.md
• packages/remotes/src/lib/enhance.svelte.ts
• packages/remotes/src/lib/validation.svelte.ts
• packages/remotes/src/lib/index.ts
• packages/remotes/CHANGELOG.md
• packages/remotes/package.json

Introduction

The @opensky/remotes package provides client-side helper utilities for SvelteKit applications to improve the developer and user experience when working with SvelteKit's remote form functions. While the remote functions themselves execute on the server, this library focuses entirely on the client-side, offering sophisticated state management for form submissions and a refined validation feedback mechanism.

This document outlines the architecture of these helpers and provides a recipe for how they interact with a server-side implementation. The two primary utilities, createValidation and createEnhancedForm, work together to manage form state, handle user interactions, and process responses from the server, creating a seamless and robust form submission lifecycle.

Sources: packages/remotes/README.md, packages/remotes/package.json:3

Core Components

The library exports two main factory functions designed to be used with a SvelteKit RemoteForm object.

Function	Description	Source File
createValidation	Creates a helper for managing form validation state and user feedback with smart issue display logic.	packages/remotes/src/lib/validation.svelte.ts
createEnhancedForm	Creates a state machine for tracking the form submission lifecycle with semantic callbacks.	packages/remotes/src/lib/enhance.svelte.ts

Sources: packages/remotes/src/lib/index.ts:1-2

createValidation: Client-Side Validation Logic

The createValidation helper is designed to improve the user experience around form validation. It implements a specific logic for displaying and clearing validation issues: issues appear when a user leaves a field (onblur) but are cleared as soon as the user starts typing in that field again (oninput). This prevents validation errors from appearing distractingly while the user is typing.

Sources: packages/remotes/README.md:5-7, packages/remotes/src/lib/validation.svelte.ts:12-16

API and Methods

The createValidation function returns an object with several methods to manage validation.

Method	Description
fields(path)	Returns onblur and oninput event handlers for a given field path.
issues(path)	Returns an array of validation issue strings for a field path, or null.
allIssues()	Returns an object containing all current validation issues.
addIssue(path, issue)	Manually adds a custom validation error to a specific field.
reset()	Clears all validation issues.
validateAll()	Triggers validation for all registered fields against the server.
updateIssues()	Populates the local issues state from the RemoteForm's issues.

Sources: packages/remotes/README.md:14-22, packages/remotes/src/lib/validation.svelte.ts:192-200

Interaction Flow

The onblur event triggers a debounced remote validation call. The oninput event handler checks if the field currently has issues; if so, it performs a preflightOnly validation to clear the issues as the user corrects the input. This minimizes server requests while providing immediate feedback.

The following diagram illustrates the client-side validation flow for a single field.

createEnhancedForm: Form State Management

The createEnhancedForm helper creates a reactive state machine to track the entire lifecycle of a form submission. It provides boolean getters for each state and allows developers to hook into different stages of the submission process using callbacks.

Sources: packages/remotes/README.md:57-61

Form States

The form can be in one of several states, managed automatically by the enhance handler. The availability of delayed and timeout states is conditional on whether delayMs and timeoutMs were provided at creation.

Configuration and Callbacks

createEnhancedForm is configured at creation time. The options determine which states and callbacks are available, ensuring type safety.

Creation Options

Option	Type	Description
validation	Validation	An instance from createValidation to integrate validation logic.
delayMs	number	Milliseconds to wait before transitioning to the delayed state.
timeoutMs	number	Milliseconds to wait before transitioning to the timeout state.

Sources: packages/remotes/src/lib/enhance.svelte.ts:46-54, packages/remotes/CHANGELOG.md:13-16

Lifecycle Callbacks

Callback	Context	Description
onSubmit	SubmitContext	Called before submission. Allows cancellation (cancel()) or optimistic updates (updates()).
onDelay	BaseEnhanceContext	Called if submission exceeds delayMs.
onTimeout	BaseEnhanceContext	Called if submission exceeds timeoutMs.
onReturn	{ result }	Called on a successful submission from the server.
onIssues	BaseEnhanceContext	Called when the server returns validation issues.
onError	{ error }	Called when the submission promise rejects.

Sources: packages/remotes/README.md:80-92, packages/remotes/src/lib/enhance.svelte.ts:90-128

Client-Server Interaction Flow

When used together, createValidation and createEnhancedForm orchestrate the full client-server interaction for a form submission. The enhance function from createEnhancedForm wraps the RemoteForm's submit call, managing state and invoking callbacks based on the server's response.

The following diagram shows the end-to-end sequence from user interaction to server response.

Conclusion

The @opensky/remotes library provides a powerful, client-side pattern for managing interactions with SvelteKit's server-side remote form functions. By separating validation UX (createValidation) from form submission state management (createEnhancedForm), it offers a clean, maintainable, and type-safe way to build complex forms. The helpers abstract away the boilerplate of state tracking and event handling, allowing developers to focus on application logic through a declarative system of configuration and callbacks. This recipe demonstrates how to effectively integrate these client-side tools to build a robust bridge to your server-side logic.