# @zerolith/forms

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

## Functions

### problemResponse

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

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

Where a form is in its current submission.

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