Reference

TypeScript reference

Every exported type, callback signature, and helper return shape in @samline/forms.

This page lists every type exported from @samline/forms, what it represents, and where it shows up. Each type links to the method(s) that consume or produce it.

All types are exported from the package root:

import type {
  AppendContentOptions,
  AutoSubmitOptions,
  FieldFormatConfig,
  FieldFormatConfigMap,
  FieldValidationContext,
  FieldValidationRules,
  FieldValidator,
  FormatType,
  FormController,
  FormControllerOptions,
  FormCleanup,
  FormDataPrimitive,
  FormErrors,
  FormFieldElement,
  FormFieldValue,
  FormFieldWatcher,
  FormFieldsWatcher,
  FormsApi,
  FormsAvailable,
  FormStateListener,
  FormStateSnapshot,
  FormSubmitHandler,
  FormTarget,
  FormValues,
  NewFormInput,
  RuleConfig,
  SerializedFormResult,
  SerializedFormValue,
  ValidationResult,
  ValidationSchema,
  ValueValidationRules,
  VisualAttributes,
} from '@samline/forms'

FormController

The full controller surface returned by form().

interface FormController {
  readonly element: HTMLFormElement | null
  readonly f: HTMLFormElement | null
  readonly options: FormControllerOptions
  onSubmit: (callback: FormSubmitHandler, preventDefault?: boolean) => FormController
  addCleanup: (cleanup: FormCleanup) => () => void
  watch: {
    (field: string, callback: FormFieldWatcher): FormController
    (fields: string[], callback: FormFieldsWatcher): FormController
  }
  observe: {
    (field: string, callback: FormFieldWatcher): () => void
    (fields: string[], callback: FormFieldsWatcher): () => void
  }
  unwatch: {
    (field?: string, callback?: FormFieldWatcher): FormController
    (fields: string[], callback?: FormFieldsWatcher): FormController
  }
  subscribe: (listener: FormStateListener) => () => void
  prefill: (fieldName?: string) => FormController
  append: (options: AppendContentOptions) => HTMLElement | null
  setErrors: (fields: string[] | FormErrors) => FormController
  clearErrors: (fields?: string[]) => FormController
  setValue: (name: string, value: unknown) => FormController
  setOptions: (
    name: string,
    options: SelectOptionInput[],
    config?: SetOptionsConfig
  ) => FormController
  validate: (fields?: string[]) => ValidationResult
  revalidate: (fields?: string[]) => ValidationResult
  format: (config: FieldFormatConfig) => FormController
  formatAll: (config: FieldFormatConfig) => FormController
  reset: () => FormController
  autoSubmit: (options?: boolean | AutoSubmitOptions) => FormController
  disableAutoSubmit: () => FormController
  getValue: (name: string) => FormFieldValue
  getField: (name: string) => FormFieldElement | FormFieldElement[] | null
  getData: () => SerializedFormResult
  getState: () => FormStateSnapshot
  destroy: () => void
}

FormControllerOptions

The second argument to form(). See Configuration for the full reference.

interface FormControllerOptions {
  attributes?: Partial<VisualAttributes>
  autoValidate?: boolean
  autoSubmit?: boolean | AutoSubmitOptions
  clearManualErrorsOnChange?: boolean
  clearErrorsOnSubmit?: boolean
  validators?: ValidationSchema
  formats?: FieldFormatConfigMap
}

FormTarget

What form() accepts as its first argument.

type FormTarget =
  | string // element id
  | HTMLFormElement // direct element
  | { current: HTMLFormElement | null } // ref-like
  | null
  | undefined

A string is treated as a document.getElementById(id) lookup; only HTMLFormElement matches count. A ref-like value lets you pass a Vue/React-style ref object.

FormFieldElement

The set of DOM field types the controller manages.

type FormFieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement

Returned by getField.

SelectOptionInput

One entry of the list passed to setOptions.

type SelectOptionInput = string | number | SelectOption | SelectOptionGroup

interface SelectOption {
  value: string | number
  label?: string // defaults to String(value); written as text, never HTML
  disabled?: boolean
  selected?: boolean // selects the option and makes it the reset default
}

interface SelectOptionGroup {
  label: string
  options: Array<string | number | SelectOption>
  disabled?: boolean
}

A string or number is shorthand for { value, label: String(value) }. SelectOption and SelectOptionGroup are exported too.

SetOptionsConfig

The third argument to setOptions.

interface SetOptionsConfig {
  keepValue?: boolean // default true
}

With keepValue: true, a select keeps its current value when that value is still listed. It is ignored for a select when any new option has selected: true.

FormFieldValue

The normalized value of a field.

type FormFieldValue = string | string[] | File[] | undefined
  • string — for text inputs, textareas, single selects, and single checked checkboxes / radios.
  • string[] — for checkbox groups, multiple selects, and repeated name="field[]" controls. Radio groups remain scalar.
  • File[] — for <input type="file"> (may be empty).
  • undefined — when no field with that name exists.

Returned by getValue.

FormValues

The aggregated values map produced by the controller and the helpers.

type FormValues = Record<string, FormFieldValue>

Useful when you build custom validators that need cross-field logic beyond exact equality (sameAs handles equality directly):

form('booking-form', {
  validators: {
    end_date: {
      dependsOn: 'start_date',
      validate: ({ value, values }) =>
        typeof value === 'string' &&
        typeof values.start_date === 'string' &&
        value >= values.start_date
          ? null
          : 'End date must not precede start date.',
    },
  },
})

The controller infers reactive dependencies from sameAs; use dependsOn for arbitrary reads inside validate. Here a change to start_date revalidates end_date once validation is active.

FormErrors

A map from field name to an array of error messages. Each field can have multiple errors (one per failed rule or per failing custom validator).

type FormErrors = Record<string, string[]>

Drives the css-error attribute on fields and is returned inside FormStateSnapshot and ValidationResult.

FormStateSnapshot

The shape returned by getState(). Built fresh on every call — it does not retain references to controller internals.

interface FormStateSnapshot {
  values: FormValues
  errors: FormErrors
  filledFields: string[]
  isValid: boolean
  isValidated: boolean
  autoSubmit: boolean
  isSubmitting: boolean
  submitCount: number
}
FieldMeaning
valuesCurrent values for every tracked field.
errorsMerged validation and manual errors.
filledFieldsNames of fields that have a non-empty value.
isValidtrue when errors has no entries.
isValidatedtrue once validate has run at least once.
autoSubmittrue while auto-submit is enabled.
isSubmittingtrue while at least one valid submission has pending async handlers. Overlapping submissions remain tracked until all their handlers settle.
submitCountNumber of submit attempts (valid or invalid).

FormStateListener

The callback passed to subscribe.

type FormStateListener = (state: FormStateSnapshot) => void

Receives the current snapshot immediately, then at controller notification points such as handled input, manual-error changes, reset, submit attempts, auto-submit toggles, and observed DOM mutations. A direct validate() call does not independently notify it.

FormSubmitHandler

The callback passed to onSubmit.

type FormSubmitHandler = (
  form: HTMLFormElement,
  data: Record<string, SerializedFormValue>,
  formData: FormData,
  state: FormStateSnapshot
) => void | Promise<void>

Only invoked when the form is valid. data and formData are produced fresh on each invocation. Promise-returning handlers contribute to isSubmitting; fulfillment and rejection both settle tracking.

FormCleanup

The callback accepted by addCleanup().

type FormCleanup = () => void

Cleanups run in reverse registration order during destroy(). addCleanup() returns an idempotent function that unregisters the callback without running it.

FormFieldWatcher

The callback passed to watch and observe.

type FormFieldWatcher = (
  value: FormFieldValue,
  field: FormFieldElement | FormFieldElement[] | null,
  form: HTMLFormElement,
  state: FormStateSnapshot
) => void
  • value — the current value of the field that just changed.
  • field — the DOM element(s) backing the field. Single matching field → HTMLInputElement / HTMLSelectElement / HTMLTextAreaElement; repeated fields → array; no match → null.
  • form — the bound HTMLFormElement.
  • state — a snapshot of the whole controller state.

observe and watch fire once immediately with the current value, then on every matching input event. observe returns an unsubscribe function; watch returns the controller.

FormFieldsWatcher

The callback passed to watch and observe with an array of field names.

type FormFieldsWatcher = (
  values: FormValues,
  changed: string | null,
  form: HTMLFormElement,
  state: FormStateSnapshot
) => void
  • values — one entry per watched field.
  • changed — the field that triggered the call; null on registration and after reset().
  • form — the bound HTMLFormElement.
  • state — a snapshot of the whole controller state.

SerializedFormResult

The shape returned by getData() and parseFormData().

interface SerializedFormResult {
  data: Record<string, SerializedFormValue>
  formData: FormData
}

data is a plain object mirror of the FormData. Repeated names become arrays. Empty file entries are filtered out.

SerializedFormValue

The value shape inside SerializedFormResult.data.

type SerializedFormValue = FormDataPrimitive | FormDataPrimitive[]
type FormDataPrimitive = FormDataEntryValue // string | File

ValidationResult

The shape returned by validate, revalidate, and validateValues.

interface ValidationResult {
  isValid: boolean
  errors: FormErrors
}

errors is always a fresh object — safe to mutate.

ValidationSchema

The shape of options.validators.

type ValidationSchema = Record<string, FieldValidationRules>

FieldValidationRules

The rule set for a single field.

interface FieldValidationRules extends ValueValidationRules {
  sameAs?: RuleConfig<string>
  dependsOn?: string | string[]
  each?: ValueValidationRules
}

Value rules run in the order: required → minLength → maxLength → pattern → numeric/range checks → validate. sameAs then runs at field level, and each applies its value rules to every member. All are optional; an empty rules object contributes nothing. dependsOn only declares reactive sources and does not produce an error.

sameAs names another exact field key. It compares non-empty strings exactly and arrays by ordered contents; file entries compare by File object identity. In a controller, changing the referenced field automatically revalidates the field that declares sameAs. Reciprocal declarations are cycle-safe, but usually duplicate the same error on both controls; prefer declaring the rule only on the confirmation field.

ValueValidationRules

The exported subset used for whole values and inside FieldValidationRules.each.

interface ValueValidationRules {
  required?: RuleConfig<boolean>
  minLength?: RuleConfig<number>
  maxLength?: RuleConfig<number>
  pattern?: RuleConfig<RegExp>
  numeric?: RuleConfig<boolean>
  min?: RuleConfig<number>
  max?: RuleConfig<number>
  validate?: FieldValidator | FieldValidator[]
}

numeric, min, and max skip empty values. Non-empty values must be finite signed decimal strings; bounds are inclusive. sameAs, dependsOn, and nested each are field-level concerns and are intentionally absent.

RuleConfig<T>

Lets a rule be configured with a plain value or a { value, message } object.

type RuleConfig<T> = T | { value: T; message?: string }
form('signup-form', {
  validators: {
    password: {
      minLength: { value: 8, message: 'Use at least 8 characters.' },
    },
    terms: {
      required: { value: true, message: 'Please accept the terms.' },
    },
  },
})

When the plain form is used, default messages are produced automatically.

FieldValidationContext

The argument passed to a custom validator.

interface FieldValidationContext {
  field: string
  value: FormFieldValue
  values: FormValues
  element?: FormFieldElement
  index?: number
}

element and zero-based index are present while a validator runs through each; they are omitted for group-level validation. Use dependsOn to declare fields read by cross-field validators:

form('checkout-form', {
  validators: {
    card: {
      validate: ({ value, field }) => {
        if (typeof value !== 'string') return `${field} is required.`
        return /^\d{16}$/.test(value.replace(/\s+/g, '')) ? null : 'Card number must be 16 digits.'
      },
    },
  },
})

FieldValidator

The custom validator signature.

type FieldValidator = (context: FieldValidationContext) => string | undefined | null | false | true
ReturnMeaning
string (non-empty)Push as the error message.
undefined, null, truePass.
falsePush the generic error message "Validation failed.".

Multiple validators can be chained by passing an array as validate:

form('order-form', {
  validators: {
    quantity: {
      validate: [
        ({ value }) =>
          typeof value === 'string' && Number(value) > 0 ? null : 'Must be greater than zero.',
        ({ value }) =>
          typeof value === 'string' && Number.isInteger(Number(value))
            ? null
            : 'Must be an integer.',
      ],
    },
  },
})

AutoSubmitOptions

The argument to autoSubmit() and the autoSubmit option.

interface AutoSubmitOptions {
  debounce?: number
}

debounce is in milliseconds.

AppendContentOptions

The argument to append().

interface AppendContentOptions {
  tag: keyof HTMLElementTagNameMap
  content: string
  class?: string
  atStart?: boolean
}
FieldMeaning
tagThe HTML tag to create.
contentinnerHTML content for the new node.
classOptional class name. If a node with the same first class already exists inside the form, it is removed before the new one is inserted.
atStartWhen true, inserts at the start of the form. Defaults to false (append at the end).

VisualAttributes

The shape of options.attributes.

interface VisualAttributes {
  filled: string
  error: string
}

Partial<VisualAttributes> is accepted, so you can override only one of them. See CSS styling.

FieldFormatConfig and FieldFormatConfigMap

The argument to format() and formatAll().

interface FieldFormatConfig {
  type: FormatType
  field: string | string[]
  displayField?: string
  options?: Record<string, unknown>
}

type FormatType =
  | 'general'
  | 'phone'
  | 'numeral'
  | 'date'
  | 'time'
  | 'creditCard'
  | 'creditCardType'
  | 'text' // formatter >= 3.1.0
  | 'slug' // formatter >= 3.1.0

type FieldFormatConfigMap = Record<string, FieldFormatConfig>

The field name is the canonical name of the formatted pair. A custom displayField is valid only for one string field; passing it with a field array logs an error and leaves the form unchanged. Array configurations derive ${fieldName}_displayed independently for every field. Every map value includes its own field because the map key is only an identifier.

FormsApi

The shape of the browser singleton exported from the vanilla entrypoint. The IIFE bundle exposes the same shape as window.Forms.

interface FormsApi {
  form: (target: FormTarget, options?: FormControllerOptions) => FormController
  newForm: (input: NewFormInput) => FormController | undefined
  destroyForm: (id: string) => void
  available: FormsAvailable
}

form is the same reference exported from @samline/forms. newForm and destroyForm manage the module-level available registry keyed by form id. Spreading browser copies references but does not create an independent registry: the methods close over the same available object. Use form() plus your own Map when isolation is required.

NewFormInput

The argument to FormsApi.newForm.

interface NewFormInput {
  id: string
  options?: FormControllerOptions
}

A missing id logs Form ID is required to console.error and newForm returns undefined without touching the registry.

FormsAvailable

The shape of FormsApi.available.

interface FormsAvailable {
  [id: string]: FormController
}

Use it to inspect or iterate over every live controller in the registry. Each entry is the FormController returned by newForm for that id.