0.1.0-alpha.7

@zerolith/forms

Import from @zerolith/forms. Generated from the source; every signature below is what the published types declare.

Functions

problemResponse

function problemResponse(problem: Problem, init?: ResponseInit): Response

Writes a problem as a Response with the problem details media type. The status comes from init, or the problem, or defaults to 400.

Source: packages/forms/src/problem.ts:10

formValues

function formValues(data: FormData): FormValues

Turns FormData into a plain object with no prototype, so a field named constructor or __proto__ is a field like any other. A name that appears once maps to its value; a name that appears more than once maps to an array of its values, in order.

Source: packages/forms/src/schema.ts:53

problemFromIssues

function problemFromIssues(issues: ReadonlyArray<StandardIssue>): Problem

Groups issues into a problem: path-bearing issues under fields, the rest in detail.

Source: packages/forms/src/schema.ts:85

validateForm

async function validateForm<S extends StandardSchema>(schema: S, data: FormData | Record<string, unknown>): Promise<Validation<InferOutput<S>>>

Validates a submission with a Standard Schema. FormData is converted with formValues first; any other value is validated as it is. Issues become a problem whose fields carry the messages per path.

Source: packages/forms/src/schema.ts:112

createForm

function createForm(options?: FormOptions): Form

Creates the enhancer for one form. Bind submit to the form's @submit; the method, action, and encoding stay on the form element, so the same markup submits natively when the script has not run.

Source: packages/forms/src/form.ts:250

Interfaces

StandardIssue

interface StandardIssue

One validation failure.

  • readonly message: string: The error message of the issue; problemFromIssues lists it under the field its path names, or in detail when the path is absent or empty.
  • readonly path?: ReadonlyArray<PropertyKey | StandardPathSegment> | undefined: The path to the failing value; absent for an issue about the whole input.

Source: packages/forms/src/schema.ts:16

StandardPathSegment

interface StandardPathSegment

One segment of an issue path in object form.

  • readonly key: PropertyKey: The key representing the path segment; problemFromIssues converts it to a string and joins the path's keys with dots to name the field.

Source: packages/forms/src/schema.ts:9

StandardSchema

interface StandardSchema<Input = unknown, Output = Input>

The Standard Schema V1 interface, as published at standardschema.dev.

  • readonly "~standard": { readonly version: 1; readonly vendor: string; readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>; readonly types?: { readonly input: Input; readonly output: Output } | undefined }: The Standard properties: the version of the specification, the vendor name of the schema library, the optional inferred types, and the validate function that validateForm calls and awaits.

Source: packages/forms/src/schema.ts:30

Field

interface Field

One input's slice of the current problem.

  • readonly errors: ReadableSignal<readonly string[]>: Every message for the field, oldest first.
  • readonly error: ReadableSignal<string | undefined>: The first message, or undefined.
  • readonly invalid: ReadableSignal<boolean>: True while the field has a message; bind it to aria-invalid.

Source: packages/forms/src/form.ts:65

Form

interface Form

The enhanced form.

  • readonly status: ReadableSignal<FormStatus>: The current submission's stage: pending while in flight, then success, failure with a problem, or error when it did not complete; idle before the first submission and after reset().
  • readonly pending: ReadableSignal<boolean>: True while a submission is in flight.
  • readonly problem: ReadableSignal<Problem | undefined>: The problem from the last failed submission, or undefined.
  • readonly result: ReadableSignal<unknown>: The parsed body of the last successful submission.
  • readonly error: ReadableSignal<unknown>: The error of the last submission that did not complete.
  • field(name: string): Field: A field's view of the problem; the same object for the same name.
  • submit(event: SubmitEvent): void: The submit handler; bind it with @submit.
  • reset(): void: Aborts any submission in flight and returns the form to idle.

Source: packages/forms/src/form.ts:76

FormOptions

interface FormOptions

Options for createForm.

  • schema?: StandardSchema: Validated on the client before anything is sent; failing issues become the problem's fields.
  • send?: (submission: Submission) => Promise<Response>: Sends the submission. Defaults to a fetch of the form's method, action, and encoding that asks for JSON.
  • headers?: HeadersInit: Headers added to the default request.
  • fetch?: typeof fetch: The fetch the default sender uses; defaults to the global one.
  • navigate?: (url: string) => void: Where a redirected response takes the page. Defaults to location.assign; pass the router's navigate to stay in the application.
  • reset?: boolean: Resets the form element after a successful response.
  • onSuccess?: (outcome: SubmissionOutcome) => void: Called after a successful response.
  • onFailure?: (problem: Problem, element: HTMLFormElement) => void: Called with the problem from client-side validation or from the server.
  • onError?: (error: unknown, element: HTMLFormElement) => void: Called when the request itself fails.

Source: packages/forms/src/form.ts:42

Submission

interface Submission

What the default sender, or a custom send, receives.

  • readonly element: HTMLFormElement: The form that was submitted.
  • readonly submitter: HTMLElement | null: The button or input that submitted it, when there was one.
  • readonly data: FormData: The form's data, including the submitter's name and value.
  • readonly method: string: The lowercase method, after the submitter's formmethod override.
  • readonly action: URL: The resolved action URL, after the submitter's formaction override.
  • readonly signal: AbortSignal: Aborted when the form is submitted again or reset.

Source: packages/forms/src/form.ts:14

SubmissionOutcome

interface SubmissionOutcome

The outcome of one submission.

  • readonly result: unknown: The parsed body: JSON when the response says so, text otherwise, undefined for an empty body.
  • readonly response: Response: The successful response, as fetch or a custom send returned it; its body has already been read into result unless it was redirected.
  • readonly element: HTMLFormElement: The form that was submitted, already reset when the reset option is set.

Source: packages/forms/src/form.ts:31

Types

FormValues

type FormValues = Record<string, FormDataEntryValue | FormDataEntryValue[]>

A form's values as a plain object: repeated names become arrays.

Source: packages/forms/src/schema.ts:45

InferOutput

type InferOutput<S extends StandardSchema> = S extends StandardSchema<unknown, infer Output> ? Output : never

The output type of a schema.

Source: packages/forms/src/schema.ts:42

StandardResult

type StandardResult<Output> = { readonly value: Output; readonly issues?: undefined } | { readonly issues: ReadonlyArray<StandardIssue> }

What validate resolves to: a value, or issues.

Source: packages/forms/src/schema.ts:25

Validation

type Validation<Output> = { readonly value: Output; readonly problem?: undefined } | { readonly value?: undefined; readonly problem: Problem }

What validateForm resolves to: the parsed value, or the problem to show.

Source: packages/forms/src/schema.ts:48

FormStatus

type FormStatus = "idle" | "pending" | "success" | "failure" | "error"

Where a form is in its current submission.

Source: packages/forms/src/form.ts:11