Troubleshooting Guide

Relevant source files

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

• README.md
• packages/remotes/README.md
• packages/remotes/src/lib/validation.svelte.ts
• packages/remotes/src/lib/enhance.svelte.ts
• packages/remotes/CHANGELOG.md
• packages/remotes/package.json
• commit-message.txt

This guide provides solutions to common problems encountered when using the @opensky/remotes helpers, createValidation and createEnhancedForm. It covers issues related to form validation behavior, state management during form submission, and problems arising from package upgrades. The information here is derived directly from the library's source code and documentation.

The library is designed to improve the developer and user experience around SvelteKit's remote form functions, but it's important to understand its intended behavior to diagnose issues effectively. This guide will walk through the internal logic of the helpers to clarify why certain problems might occur and how to resolve them.

Validation Issues

This section addresses problems with createValidation, such as validation messages not appearing, not clearing, or not reflecting server-side errors correctly.

Issue: Validation messages don't appear on blur or don't clear on input.

This is the most common issue and usually stems from incorrect implementation. The intended behavior is that validation issues for a field only appear when the user leaves the field (onblur) and are cleared as soon as the user starts typing again (oninput).

Sources: README.md:10-12, packages/remotes/src/lib/validation.svelte.ts:121-152

Troubleshooting Steps:

1. Verify Field Registration: Ensure you are spreading the valid.fields('path.to.field') object onto your input element. This function returns the necessary onblur and oninput event handlers that trigger the validation logic.

   Sources: README.md:27-28, packages/remotes/src/lib/validation.svelte.ts:117-120

2. Check Issue Retrieval: Make sure you are using valid.issues('path.to.field') to check for validation messages. This function returns an array of strings if there are issues, or null if there are none.

   Sources: README.md:30-32, packages/remotes/src/lib/validation.svelte.ts:154-157

3. Understand the Event Flow: The diagram below illustrates the internal logic for onblur and oninput handlers provided by valid.fields().

   This diagram shows the sequence of events for field validation handlers.

*Sources: [packages/remotes/src/lib/validation.svelte.ts:121-152](https://github.com/open-sky-dev/opensky-remotes/blob/HEAD/packages/remotes/src/lib/validation.svelte.ts#L121-L152)*

Issue: Server-side validation errors are not showing up correctly.

There are known limitations and buggy behaviors with SvelteKit's remote function validation that @opensky/remotes attempts to work around.

1. Server Issues on Blur: Due to a bug in SvelteKit, server-side validation rules may not be reported on the onblur event. They might only appear after a full form submission. The library's onblur handler attempts to validate against the server, but this may not always work as expected.

   Sources: README.md:43-47

2. Issues After Submit: After a form submission fails with validation errors from the server, all issues might be cleared as soon as you start editing any field. The desired behavior is to only clear the issue for the specific field being edited. To correctly handle post-submission validation states, you must integrate with createEnhancedForm or manually call valid.updateIssues() and valid.validateAll() in your enhance handler.

   Sources: README.md:49-55, packages/remotes/src/lib/enhance.svelte.ts:285-287, packages/remotes/src/lib/enhance.svelte.ts:295-297

   The following flow shows how createEnhancedForm handles this automatically.

*Sources: [packages/remotes/src/lib/enhance.svelte.ts:273-298](https://github.com/open-sky-dev/opensky-remotes/blob/HEAD/packages/remotes/src/lib/enhance.svelte.ts#L273-L298)*

Issue: How to add a custom, client-side validation error?

You can manually add an error message to a specific field using the addIssue method. This is useful for client-side checks that run before a form is submitted.

Sources: README.md:25, packages/remotes/src/lib/validation.svelte.ts:106-115

// Example from README.md
import { createValidation, createEnhancedForm } from '@opensky/remotes'

const valid = createValidation(myForm);
const form = createEnhancedForm(myForm, { validation: valid });

// In your enhance handler
form.enhance(opts, {
  onSubmit: ({ cancel, data }) => {
    if (!customValidationCheck(data)) {
      valid.addIssue('fieldName', 'Custom validation failed');
      cancel('issues'); // Cancel submission and set state
    }
  }
});

Sources: README.md:120-125, packages/remotes/CHANGELOG.md:7-9

Form State & Submission Issues

This section covers problems related to the form's lifecycle and state management when using createEnhancedForm.

Issue: delayed or timeout states are not working.

A common source of error is providing the delayMs and timeoutMs options in the wrong place, especially after upgrading from version 0.0.2 or earlier.

delayMs and timeoutMs must be passed during the creation of the enhanced form, not to the .enhance() method.

This change was introduced in version 0.0.3 to enable type-safe conditional states. The delayed and timeout state properties will only exist on the returned object if delayMs or timeoutMs are provided at creation.

Sources: packages/remotes/CHANGELOG.md:12-15, commit-message.txt, packages/remotes/src/lib/enhance.svelte.ts:192-209

Incorrect (Old Way):

// This will NOT work in v0.0.3+
const form = createEnhancedForm(myForm);
form.enhance(opts, {
    delayMs: 500, // WRONG
    onDelay: () => {}
});

Correct (v0.0.3+):

// Correct way
const form = createEnhancedForm(myForm, {
    delayMs: 500,
    timeoutMs: 3500
});

form.enhance(opts, {
    onDelay: () => {}, // Correctly placed callback
    onTimeout: () => {}
});

Sources: README.md:92-96

Issue: Form state is not what I expect (e.g., form.success is undefined).

The form state names were updated for semantic clarity in version 0.0.3.

Old State (<0.0.3)	New State (>=0.0.3)	Description
success	result	The form submission was successful and returned a result.

If you are upgrading, replace all instances of form.success with form.result and the onSuccess callback with onReturn.

Sources: packages/remotes/CHANGELOG.md:10, packages/remotes/src/lib/enhance.svelte.ts:221-222

The createEnhancedForm helper manages a state machine. Understanding its flow can help debug state-related issues.

This diagram shows the possible state transitions for an enhanced form.

Issue: onDelay or onTimeout callbacks are not firing.

These callbacks are only available if you provide the corresponding delayMs or timeoutMs options when calling createEnhancedForm. If the options are not provided, the TypeScript types will prevent you from even defining the callbacks, but in a JavaScript environment, they would simply be ignored.

Sources: packages/remotes/CHANGELOG.md:15, packages/remotes/src/lib/enhance.svelte.ts:100-117

Upgrade and Dependency Problems

Breaking Changes in v0.0.3

If you are upgrading from a version prior to 0.0.3, you must account for several breaking changes.

Change Description	Old Code (<0.0.3)	New Code (>=0.0.3)
State name for success	form.success	form.result
Creation option for validation	createEnhancedForm(r, { validator: v })	createEnhancedForm(r, { validation: v })
Timing configuration moved	form.enhance(opts, { delayMs: 500 })	createEnhancedForm(r, { delayMs: 500 })
Client-side cancellation	Not available	onSubmit: ({ cancel }) => cancel('issues')
Optimistic updates	Not available	onSubmit: ({ updates }) => updates(...)

Sources: packages/remotes/CHANGELOG.md:6-15

Dependency Version Mismatches

@opensky/remotes has peer dependencies on Svelte and SvelteKit. Mismatches can cause subtle bugs. Check your package.json against the peerDependencies listed in the library.

"peerDependencies": {
  "@sveltejs/kit": "^2.27.0",
  "svelte": "^5.0.0"
}

Sources: packages/remotes/package.json:15-18

If you encounter strange behavior that is not explained here, ensure your installed versions of @sveltejs/kit and svelte satisfy these requirements.