Cancelling Submissions

Relevant source files

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

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

The @opensky/remotes library provides a mechanism to programmatically cancel a form submission on the client side before any request is sent to the server. This feature is integrated into the createEnhancedForm helper and is primarily used for implementing custom client-side validation or other pre-submission checks. The ability to cancel submissions was introduced in version 0.0.3.

This functionality allows developers to prevent unnecessary server requests, provide immediate feedback to the user, and manage form state with greater control. It works in tandem with the createValidation helper to display custom validation messages.

Sources: packages/remotes/README.md, packages/remotes/CHANGELOG.md:4-6

Architecture Overview

The cancellation logic is part of the createEnhancedForm utility. When a form is submitted, the enhance method intercepts the submission and triggers an onSubmit callback. This callback is provided with a cancel() function that can be invoked to halt the submission process.

Sources: packages/remotes/src/lib/enhance.svelte.ts:211-218, packages/remotes/README.md

Core Components

Component	Description	Source File
createEnhancedForm	A factory function that creates a form manager with state tracking and lifecycle callbacks.	packages/remotes/src/lib/index.ts:2
enhance	A method returned by createEnhancedForm that is used as the form enhancement handler. It accepts lifecycle callbacks, including onSubmit.	packages/remotes/src/lib/enhance.svelte.ts:138-141
onSubmit	An optional callback passed to enhance. It is executed when the form submission begins and receives the cancel() function.	packages/remotes/src/lib/enhance.svelte.ts:114
cancel()	A function provided in the onSubmit context that, when called, stops the form submission and sets the form's state.	packages/remotes/src/lib/enhance.svelte.ts:81

Cancellation Flow

The following diagram illustrates the logical flow when a form submission is initiated and subsequently cancelled within the onSubmit callback.

Sources: packages/remotes/src/lib/enhance.svelte.ts:282-290

Implementation Details

The cancellation mechanism is exposed through the SubmitContext object passed to the onSubmit callback.

Sources: packages/remotes/src/lib/enhance.svelte.ts:78-85, packages/remotes/src/lib/enhance.svelte.ts:282-290

The cancel() Function

The cancel() function is the key to this feature. It is defined within the enhanceHandler and made available inside the onSubmit callback.

// packages/remotes/src/lib/enhance.svelte.ts:81
/** Cancel the submission and optionally set state to 'error' or 'issues'. Defaults to 'idle' if no argument provided. */
cancel: (state?: 'error' | 'issues') => void

When cancel() is called, it sets an internal cancelled flag to true and records the desired final state. The enhanceHandler then checks this flag and, if it's set, immediately aborts the submission process and updates the form's state accordingly, bypassing the actual submit() call.

Sources: packages/remotes/src/lib/enhance.svelte.ts:278-281, packages/remotes/src/lib/enhance.svelte.ts:286-290

Parameters

Parameter	Type	Description	Default
state	'error' | 'issues' | undefined	The state to which the form should transition upon cancellation.	'idle'

• cancel() or cancel('idle'): Cancels the submission and resets the form state to 'idle'.
• cancel('issues'): Cancels the submission and sets the form state to 'issues'. This is useful when a client-side validation fails and you want to display an issue message.
• cancel('error'): Cancels the submission and sets the form state to 'error'.

Sources: packages/remotes/src/lib/enhance.svelte.ts:81, packages/remotes/src/lib/enhance.svelte.ts:279

Sequence Diagram

This sequence diagram shows the interactions between the user, the Svelte component, and the enhanceHandler during a cancelled submission.

Sources: packages/remotes/README.md, packages/remotes/src/lib/enhance.svelte.ts:282-290, packages/remotes/src/lib/validation.svelte.ts:133-142

Usage Example

The following example demonstrates how to use cancel() within the onSubmit callback to perform a custom validation check and prevent form submission if the check fails.

<script lang="ts">
  import { createValidation, createEnhancedForm } from '@opensky/remotes';
  // ... other imports

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

  function customValidationCheck(data) {
    // some custom logic
    return false;
  }
</script>

<form {...myForm.preflight(schema).enhance(opts =>
  form.enhance(opts, {
    onSubmit: ({ cancel, data }) => {
      // Custom client-side checks before submission
      if (!customValidationCheck(data)) {
        valid.addIssue('fieldName', 'Custom validation failed');
        cancel('issues'); // Cancel and set state to 'issues'
        return;
      }
    },
    // ... other callbacks
  })
)}>
  <!-- form fields -->
</form>

In this code, if customValidationCheck returns false, a custom error is added using valid.addIssue(), and cancel('issues') is called. This stops the form from being submitted and sets the form's state to 'issues', allowing UI to react and display the newly added error message.

Sources: packages/remotes/README.md, packages/remotes/src/lib/validation.svelte.ts:133-142

Summary

The submission cancellation feature is a powerful client-side control mechanism within @opensky/remotes. By leveraging the cancel() function inside the onSubmit callback of createEnhancedForm, developers can prevent form submissions based on custom logic, integrate seamlessly with the validation system, and manage form state transitions without making a server request. This improves user experience by providing instant feedback and reduces unnecessary network traffic.

Sources: packages/remotes/src/lib/enhance.svelte.ts, packages/remotes/README.md