Reference headless

formField

import { … } from '@kumiki/headless/formField'

interface 5 type 6 function 1

interface Interfaces 5

interface form-field/index.ts · L86

# CreateFormFieldOptions

Type Parameters

T

Members

id?: optional id?: string
initialValue: initialValue: T
###### Inherited from

CreateFormFieldInput.initialValue
onValidityChange?: optional onValidityChange?: (state) => void
###### Parameters

###### state

FormFieldState

###### Returns

void
onValueChange?: optional onValueChange?: (value) => void
###### Parameters

###### value

T

###### Returns

void
readValue?: optional readValue?: (node) => T
Read the value from the DOM on INPUT. Default for <input> is el.value. Pass a custom reader for richer inputs.

###### Parameters

###### node

HTMLElement

###### Returns

T
validateOn?: optional validateOn?: ValidateOn | readonly ValidateOn[]
Default 'blur'.
validator?: optional validator?: StandardSchemaV1<T, T> | StandardSchemaV1<unknown, T>
writeValue?: optional writeValue?: (node, value) => void
Write the value to the DOM when SET.VALUE / RESET fires. Default for <input> is el.value = String(v).

###### Parameters

###### node

HTMLElement

###### value

T

###### Returns

void

interface

# FieldIssue

One validation issue. Aligns with Standard Schema's Issue shape so users can pipe result.issues straight in without remapping.

Members

message: readonly message: string
path?: readonly optional path?: readonly PropertyKey[]

interface

# FormFieldContext

Type Parameters

T

Members

dirty: dirty: boolean
True when value differs from initialValue.
errors: errors: readonly FieldIssue[]
initialValue: readonly initialValue: T
touched: touched: boolean
True once the field has lost focus at least once.
validationToken: validationToken: number
Token emitted with each VALIDATE intent. The attachment uses it to guard async resolutions so a stale validator can't overwrite fresher state. Monotonically increasing across the field's lifetime.
value: value: T

interface form-field/index.ts · L44

# FormFieldController

Type Parameters

T

Members

context: readonly context: Readonly<FormFieldContext<T>>
description: readonly description: Attachment
descriptionId: readonly descriptionId: string
dirty: readonly dirty: boolean
errors: readonly errors: Attachment
errorsId: readonly errorsId: string
id: readonly id: string
input: readonly input: Attachment
inputId: readonly inputId: string
invalid: readonly invalid: boolean
label: readonly label: Attachment
labelId: readonly labelId: string
machine: readonly machine: FormFieldMachine<T>
state: readonly state: FormFieldState
touched: readonly touched: boolean
validating: readonly validating: boolean
value: readonly value: T
reset(): reset(): void
###### Returns

void
setErrors(): setErrors(issues): void
Inject errors from outside the validator (e.g. SvelteKit form actions, superforms, server-returned issues). Drives the machine through validating → valid (empty issues) | invalid (non-empty), so the Errors live-region announces the change exactly as a local validator run would.

The string-array shorthand maps each entry to { message }.

###### Parameters

###### issues

readonly string[] | readonly FieldIssue[]

###### Returns

void
setValue(): setValue(value): void
###### Parameters

###### value

T

###### Returns

void
subscribe(): subscribe(listener): () => void
###### Parameters

###### listener

(snapshot) => void

###### Returns

() => void
validate(): validate(): Promise<void>
Manually trigger validation (e.g. from a parent form's submit).

###### Returns

Promise<void>

interface

# StandardSchemaV1

Subset of the Standard Schema v1 type surface that Kumiki depends on.

Standard Schema is a type contract, not a runtime dependency — the validator implementation is supplied by the consumer (Zod 3.24+, Valibot 1.x, ArkType 2.0+, Effect Schema 3.x, …).

Type Parameters

Input
Output

Members

\_input?: readonly optional _input?: Input
~standard: readonly ~standard: object readonly validate: (value) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>> readonly vendor: string readonly version: 1
###### validate

###### Parameters

###### value

unknown

###### Returns

StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>

###### vendor

###### version

type Type Aliases 6

type form-field/index.ts · L34

# Attachment

Attachment = (node) => void | (() => void)

Parameters

node: HTMLElement

Returns

void | (() => void)

type

# FormFieldEvent

FormFieldEvent<T> = { type: "FOCUS"; } | { type: "INPUT"; value: T; } | { type: "BLUR"; } | { type: "SUBMIT_REQUEST"; } | { issues: ReadonlyArray<FieldIssue>; token: number; type: "VALIDATION_RESOLVE"; } | { reason: unknown; token: number; type: "VALIDATION_REJECT"; } | { type: "RESET"; } | { type: "SET.VALUE"; value: T; }

Type Parameters

T

type

# FormFieldMachine

FormFieldMachine<T> = Machine<FormFieldContext<T>, FormFieldEvent<T>, FormFieldState>

Type Parameters

T

type

# FormFieldState

FormFieldState = "pristine" | "editing" | "validating" | "valid" | "invalid"

type

# StandardSchemaResult

StandardSchemaResult<Output> = { issues?: undefined; value: Output; } | { issues: ReadonlyArray<{ message: string; path?: ReadonlyArray<PropertyKey>; }>; }

Result from a Standard Schema validator's validate() call.

Type Parameters

Output

type form-field/index.ts · L42

# ValidateOn

ValidateOn = "blur" | "change" | "submit"

function Functions 1

function form-field/index.ts · L112

# createFormField ( )

createFormField<T>(options): FormFieldController<T>

Type Parameters

T

Parameters

options: CreateFormFieldOptions<T>

Returns

FormFieldController<T>