DOM Form API

Reference DOM Form connection functions, options, participants, submission results, and public types.

Back to the DOM forms guide

API

DOM package: @sectile/dom/form

Functions

defineFormSubmission

function defineFormSubmission<const Schema extends FormSchema<object, object>, ID extends StableID = StableID>(definition: FormSchemaSubmissionDefinition<Schema, ID>): FormSchemaSubmissionDefinition<Schema, ID>
function defineFormSubmission<ID extends StableID = StableID>(definition: FormSubmissionDefinition<ID>): FormSubmissionDefinition<ID>

createForm

function createForm<ID extends StableID = StableID, Input extends object = FormValues, Output extends object = Input>(options: FormOptions<ID, Input, Output>): FormConnection<ID, Input, Output>

tryCreateForm

function tryCreateForm<ID extends StableID = StableID, Input extends object = FormValues, Output extends object = Input>(options: FormOptions<ID, Input, Output>): FormResult<FormConnection<ID, Input, Output>>

appendFormFieldPath

function appendFormFieldPath(base: FormFieldPath, relative: FormRelativePath): readonly FormPathSegment[]

createFormFieldPath

function createFormFieldPath(path: FormFieldPath, limits?: Partial<FormConstructionLimits>): readonly FormPathSegment[]

createFormRelativePath

function createFormRelativePath(path: FormRelativePath, limits?: Partial<FormConstructionLimits>): readonly FormPathSegment[]

encodeFormFieldPath

function encodeFormFieldPath(path: FormFieldPath): string

Types

FormFieldPath

type FormFieldPath = string | readonly FormPathSegment[]

FormPathSegment

type FormPathSegment = string | number

FormRelativePath

type FormRelativePath = FormPathSegment | readonly FormPathSegment[]

FormValues

type FormValues<Shape extends object = Record<string, unknown>> = Readonly<Shape>

FormSchema

type FormSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>

FormSchemaInput

type FormSchemaInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>

FormSchemaOutput

type FormSchemaOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>

FormReinitializeOptions

Name	Type	Required
preserve	{ readonly touched?: boolean; readonly validation?: boolean; readonly submission?: boolean; }	—

FormValidationIssue

Name	Type	Required
message	string	Yes
path	FormFieldPath	—
relatedPaths	readonly FormFieldPath[]	—

FormValidationResult

Name	Type	Required
issues	readonly FormValidationIssue[]	—

FormInteractionValidationTrigger

type FormInteractionValidationTrigger = Exclude<FormValidationTrigger, 'submit'>

FormValidateContext

Name	Type	Required
trigger	FormValidationTrigger	Yes
intent	FormValidationIntent	Yes
changedFieldId	ID | null	Yes
signal	AbortSignal	Yes

FormValidateHandler

type FormValidateHandler<ID extends StableID = StableID, Values extends object = FormValues> =
(
  values: Values,
  context: FormValidateContext<ID>,
) => FormValidationResult | PromiseLike<FormValidationResult>

FormFocusHandler

type FormFocusHandler = () => boolean | void

FormResetHandler

type FormResetHandler = () => void

FormReinitializeHandler

type FormReinitializeHandler = (options?: FormReinitializeOptions) => void

FormAnnounceSummaryHandler

type FormAnnounceSummaryHandler<ID extends StableID = StableID> = (issues: readonly FormIssue<ID>[], failure: FormSubmissionFailure | null) => void

FormStateChangeHandler

type FormStateChangeHandler<ID extends StableID = StableID> = (state: FormState<ID>) => void

FormUpdateHandler

type FormUpdateHandler = () => void

FormSubmissionElement

type FormSubmissionElement =
| HTMLButtonElement
  | HTMLInputElement
  | HTMLSelectElement
  | HTMLTextAreaElement

FormParticipant

Name	Type	Required
id	ID	Yes
element	HTMLElement	Yes
semanticControl	HTMLElement	—
focusTarget	HTMLElement	—
validationTarget	HTMLElement	—
submissionElements	readonly FormSubmissionElement[]	—
name	FormFieldPath | null	—
focus	FormFocusHandler	—
reset	FormResetHandler	—
getValue	(() => unknown) | undefined	—
isValueEqual	((current: unknown, baseline: unknown) => boolean) | undefined	—

FormSubmitPayload

Name	Type	Required
event	SubmitEvent	Yes
formData	FormData	Yes
values	Values	Yes
submitter	HTMLElement | null	Yes
state	FormState<ID>	Yes
reinitialize	FormReinitializeHandler	Yes

FormSubmitResult

type FormSubmitResult<ID extends StableID = StableID> =
| void
  | { readonly ok: true }
  | {
      readonly ok: false;
      readonly failure?: FormSubmissionFailure;
      readonly issues?: readonly FormIssue<ID>[];
    }

FormSubmitHandler

type FormSubmitHandler<ID extends StableID = StableID, Values extends object = FormValues> =
(
  payload: FormSubmitPayload<ID, Values>,
) => FormSubmitResult<ID> | PromiseLike<FormSubmitResult<ID>>

FormSubmissionDefinition

Name	Type	Required
schema	never	—
onSubmit	FormSubmitHandler<ID, Readonly<Record<string, unknown>>>	Yes

FormSchemaSubmissionDefinition

Name	Type	Required
schema	Schema	Yes
onSubmit	FormSubmitHandler<ID, FormSchemaOutput<Schema>>	Yes

FormSubmitErrorMapper

type FormSubmitErrorMapper<ID extends StableID = StableID> =
(
  reason: unknown,
) => FormSubmissionFailure

FormSubmitFailureResult

Name	Type	Required
failure	FormSubmissionFailure	—
issues	readonly FormIssue<ID>[]	—

FormSnapshot

Name	Type	Required
revision	number	Yes
state	FormState<ID>	Yes

FormSubscribeOptions

Name	Type	Required
equals	(previous: Selected, next: Selected) => boolean	—

FormSelector

type FormSelector<ID extends StableID, Selected> = (state: FormState<ID>) => Selected

FormFieldSelector

type FormFieldSelector<ID extends StableID, Selected> = (field: FormFieldState<ID> | null) => Selected

FormSelectionListener

type FormSelectionListener<Selected> = (selected: Selected, previous: Selected) => void

FormOptions

Name	Type	Required
form	HTMLFormElement	Yes
summary	HTMLElement	—
renderSummaryContent	boolean	—
participants	readonly FormParticipant<ID>[]	—
issues	readonly FormIssue<ID>[]	—
schema	FormSchema<Input, Output>	—
validate	FormValidateHandler<ID, Input>	—
validateOn	readonly FormInteractionValidationTrigger[]	—
revalidateOn	readonly FormInteractionValidationTrigger[]	—
onSubmit	FormSubmitHandler<ID, Output>	—
mapSubmitError	FormSubmitErrorMapper<ID>	—
onReset	FormResetHandler	—
onAnnounceSummary	FormAnnounceSummaryHandler<ID>	—
onStateChange	FormStateChangeHandler<ID>	—
onUpdate	FormUpdateHandler	—
onSubscriptionError	(error: unknown) => void	—

FormReconfigureOptions

type FormReconfigureOptions<ID extends StableID = StableID, Input extends object = FormValues, Output extends object = Input> = Omit<FormOptions<ID, Input, Output>, 'form' | 'participants' | 'issues'>

FormConnection

Name	Type	Required
state	FormState<ID>	Yes
getSnapshot	() => FormSnapshot<ID>	Yes
getFormData	(submitter?: HTMLElement | null) => FormData	Yes
reconfigure	(options: FormReconfigureOptions<ID, Input, Output>) => void	Yes
registerParticipant	(participant: FormParticipant<ID>) => () => void	Yes
refreshParticipant	(id: ID) => boolean	Yes
getField	(id: ID) => FormFieldState<ID> | null	Yes
setFieldMeta	(id: ID, meta: FormFieldMetaInput) => boolean	Yes
replaceFieldIssues	(id: ID, source: FormIssueSource, issues: readonly FormIssue<ID>[]) => boolean	Yes
upsertFieldIssue	(id: ID, issue: FormIssue<ID>) => boolean	Yes
removeFieldIssue	(id: ID, issueId: StableID) => boolean	Yes
clearFieldIssues	(id: ID, source?: FormIssueSource) => boolean	Yes
replaceIssues	(source: FormIssueSource, issues: readonly FormIssue<ID>[]) => boolean	Yes
submitStarted	() => number | null	Yes
submitSucceeded	(generation: number) => boolean	Yes
submitFailed	(generation: number, result: FormSubmitFailureResult<ID>) => boolean	Yes
reinitialize	(options?: FormReinitializeOptions) => void	Yes
reset	() => void	Yes
subscribeForm	<Selected>(selector: FormSelector<ID, Selected>, listener: FormSelectionListener<Selected>, options?: FormSubscribeOptions<Selected>) => () => void	Yes
subscribeField	<Selected>(id: ID, selector: FormFieldSelector<ID, Selected>, listener: FormSelectionListener<Selected>, options?: FormSubscribeOptions<Selected>) => () => void	Yes
destroy	() => void	Yes