Form / foldkit-mixins-form

Controls, slots, and custom renderers

ControlElementSlot
Textinput type="text"text
Multilinetextareamultiline
Numberinput type="text" inputmode="decimal"number
Toggleinput type="checkbox"toggle
Selectselect of control options with blank optionselect, option
Choicesrole="group" of checkboxeschoices, choiceLabel, choice
RelationOneselect of options[key] with blank optionselect, option
RelationManyrole="group" of checkboxes over options[key]choices, choiceLabel, choice
Nestedfieldset + legend, row divs, add/remove buttonsgroup, legend, row, add, remove

Pickers configured with Input.search() add an input type="search" in the search slot (aria-controls pointing at the picker), and pickers listed in more: { authorId: true } (from Crud.options) add a button in more dispatching AskedForMore({ key }). Stored values missing from loaded options appear at the end as ? value so users can inspect or clear stale IDs. Override button and summary copy through words (see words in one place).

Renderers

Add custom control kinds or override built-in controls through renderers:

ts
FormView.define(PriceForm, {
  renderers: {
    Cents: ({ draft, change, blurred, state, h }) =>
      h.input([...state, h.Value(String(draft)), h.OnInput(change), h.OnBlur(blurred)]),
    RelationOne: myCombobox,
  },
})

Each renderer receives state (the control's id and ARIA attributes), draft, change, blurred, and input.following (for Input.following regenerate buttons). Controls backed by Input.bundle render their own Bundle view inside the control slot unless a custom renderer handles that kind (pass extra inputs via { controls: { key: inputs } }). Missing renderers throw with the kind and key name.

Per-key overrides and custom layouts

Use FormView.fields to override individual field renderers, attach per-key FieldSlots styles, or set HTML input attributes (type, placeholder, rows, autocomplete, inputMode):

ts
const Fields = FormView.fields(PriceForm, {
  overrides: {
    code: (input, h) => h.input([h.Id(input.id), h.Value(String(input.field.value))]),
  },
  styles: {
    total: Style.forSlots(FieldSlots)({ root: Style.class('total') }),
  },
  attrs: {
    email: { type: 'email', autocomplete: 'email' },
  },
})

Call Fields.field(control, formModel, id, h) to render a single flat key inside a bespoke layout:

ts
Fields.field(control, formModel, control.key, h, (input, draw) =>
  draw.input([draw.Id(input.id), draw.Value(String(input.field.value))]),
)

Number controls render input type="text" inputmode="decimal" because partial drafts like "4." are rejected by native <input type="number">.

Validation summaries, pending checks, and submit states

When a multi-control form is submitted with errors, an alert summary (FormSlots.summary, summaryTitle, issues, issue, issueLink) appears above the submit button linking to each invalid control (#id), removing redundant role="alert" from inline field errors. Single-control forms show only the inline field alert.

Async checks (Validating) set aria-busy on the control and render the checking status line; each field root also carries data-validation (NotValidated, Validating, Valid, Invalid) for CSS selectors.

While waiting on checks (submitPending) or an in-flight write (submitting read from Remote's mutation ledger or failure for server errors), the form sets aria-busy and data-submitting, and the submit button swaps to words.submitting with aria-disabled="true"—never native disabled, so Enter inside any field still reaches update cleanly even on the same frame as an autofill or paste.

ts
import { Bundle } from 'foldkit-bundle'

const NeverPreDisabled = Edit.bundle.pipe(
  Bundle.withView(FormView.submodel(Edit, View, { canSubmit: () => true })),
)

Accessibility guarantees

Controls receive deterministic IDs (<form>-<key> or <form>-<key>-<row>-<key>), matching <label for>, aria-busy, aria-invalid, aria-required, and aria-describedby pointing to description, checking, and error elements. FieldSlots declares AriaInvalid and AriaDescribedby so conflicting attribute attachments are caught at render time.

Limits

  • Fixed field order: FormView.define renders fields in input declaration order (label, control, description, checking, error); use Fields.field over form.controls for custom layouts.
  • Picker paging: Relation pickers render loaded rows as <select> or checkboxes with client filtering (Input.search()) or a more button rather than a virtualized combobox.
  • Render the wrapped Bundle: Place the Bundle returned by Bundle.withView(...) rather than form.bundle.

Next