Project Architecture

Relevant source files

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

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

The @opensky/remotes package provides a set of SvelteKit helper utilities designed to improve the developer and user experience when working with SvelteKit's remote form functions. The architecture is centered around two main composable functions, createValidation and createEnhancedForm, which offer reactive state management for form validation and submission lifecycles.

This library is built as a modern ES module for Svelte 5, leveraging Svelte Runes for reactivity. It integrates with SvelteKit's form handling capabilities to provide a more structured and feature-rich layer for managing form interactions, including debounced validation, state tracking, and lifecycle callbacks.

Sources: packages/remotes/package.json, packages/remotes/README.md, packages/remotes/src/lib/index.ts

Core Utilities

The package exports two primary functions that form the core of its architecture.

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

createValidation

This utility enhances the user experience for form validation. It provides event handlers (onblur, oninput) that implement a specific validation logic: issues are shown when a user leaves a field (onblur) but are cleared as soon as the user starts typing to correct the invalid input (oninput). This prevents validation errors from appearing distractingly during input.

The function manages an internal reactive state for validation issues, which can be accessed by field path. It uses a debounced function to call the remote form's validate() method, reducing the number of server requests.

Sources: packages/remotes/src/lib/validation.svelte.ts:13-20, packages/remotes/README.md:5-9

Validation Flow

The diagram below illustrates the logic handled by the onblur and oninput event handlers returned by valid.fields(path).

createValidation API

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

Method/Property	Description
fields(path)	Returns onblur and oninput handlers for a given field path. Registers the path for tracking.
issues(path)	Returns an array of validation issue strings for a field path, or null if none.
allIssues()	Returns the entire object of validation issues.
addIssue(path, issue)	Manually adds a custom validation error message to a field.
reset()	Clears all validation issues.
validateAll()	Validates all registered fields against the server.
updateIssues()	Populates issues from the underlying remote form's state for all registered fields.

Sources: packages/remotes/src/lib/validation.svelte.ts:184-203, packages/remotes/README.md:16-24

createEnhancedForm

This utility creates a state machine for a remote form, tracking its submission lifecycle. It provides semantic callbacks for different stages of the request (onSubmit, onReturn, onIssues, etc.) and exposes the form's state through reactive getters (idle, pending, delayed, timeout). It can be integrated with createValidation to automatically handle validation updates during the form submission process.

Configuration options like delayMs and timeoutMs are passed at creation, which enables type-safe conditional states and callbacks. For instance, the .delayed state and onDelay callback are only available if delayMs is provided.

Sources: packages/remotes/src/lib/enhance.svelte.ts:219-232, packages/remotes/README.md:65-72, packages/remotes/CHANGELOG.md:12-15

Form State Machine

The createEnhancedForm helper manages the form's state through a defined lifecycle. The following diagram shows the possible state transitions.

createEnhancedForm API

The function returns an object with the enhance handler and several reactive state properties.

Method/Property	Description
enhance(params, callbacks)	The form enhancement handler to be used with SvelteKit's enhance.
reset()	Manually resets the form state back to idle.
state	A reactive string representing the current state (e.g., 'idle', 'pending', 'result').
idle	Boolean getter, true if state is 'idle'.
pending	Boolean getter, true if state is 'pending'.
delayed	Boolean getter, only available if delayMs was provided at creation.
timeout	Boolean getter, only available if timeoutMs was provided at creation.
issues	Boolean getter, true if state is 'issues'.
error	Boolean getter, true if state is 'error'.
result	Boolean getter, true if state is 'result'.

Sources: packages/remotes/src/lib/enhance.svelte.ts:133-217, packages/remotes/README.md:74-81

Integration Flow

The two core utilities are designed to work together seamlessly. When a validation instance is passed to createEnhancedForm, the enhance handler will automatically call the appropriate validation methods (updateIssues or validateAll) based on the submission outcome.

The following diagram shows the sequence of events when a form enhanced with both utilities is submitted.

Project Structure and Dependencies

The project is a standard SvelteKit library package, configured to be built with Vite and packaged using svelte-package.

Sources: packages/remotes/vite.config.ts, packages/remotes/svelte.config.js, packages/remotes/package.json:48-56

Key Dependencies

Dependency	Version	Role
svelte	^5.0.0	The core Svelte framework (peer dependency).
@sveltejs/kit	^2.27.0	The SvelteKit framework for remote forms (peer dependency).
runed	^0.35.1	A utility library, used for useDebounce in createValidation.

Sources: packages/remotes/package.json:13-20, packages/remotes/src/lib/validation.svelte.ts:2

Build and Packaging

The package is configured to export its functionality for Svelte environments. The exports field in package.json points to the distributed JavaScript and TypeScript declaration files. The build process is orchestrated by scripts in package.json, using Vite and svelte-package.

"exports": {
    ".": {
        "types": "./dist/index.d.ts",
        "svelte": "./dist/index.js"
    }
},
"files": [
    "dist",
    "!dist/**/*.test.*",
    "!dist/**/*.spec.*"
],

Sources: packages/remotes/package.json:33-45

Conclusion

The architecture of @opensky/remotes is lightweight and focused. It provides two powerful, composable utilities that build upon SvelteKit's native form handling. By leveraging Svelte 5's reactivity with Runes and providing a state machine for form submissions, it simplifies complex UI patterns like optimistic updates, timed feedback, and sophisticated validation UX. The clear separation of concerns between createValidation and createEnhancedForm allows developers to use them independently or together for a comprehensive form management solution.