Form system

Forms that keep the platform working

One accessible field contract, native submission by default, and focused adapters when a framework should own form state.

Start with the primitives React Hook Form

Architecture

Lumen does not replace a form state manager or server framework. It makes controls, errors, and submission states consistent while preserving native browser behavior.

Lumen

Controls, labels, hints, errors, summaries, pending presentation, native values, and reset behavior.

Browser

FormData, constraint validation, autofill, password managers, ordinary POST, and no-JavaScript fallback.

Integration

React Hook Form state or Astro Action parsing and server validation when the application opts in.

Application

Business rules, authorization, persistence, rate limits, redirects, and domain-specific copy.

Building blocks

Form is a real form element. Field owns the relationship between its Label, hint, control, and FieldError. ErrorSummary collects failures after submit. PasswordField and ListBox preserve native submitted controls behind their enhanced presentation.

---
import { Button, Field, FieldError, Form, Input, Label } from '@santi020k/lumen-astro'
---

<Form action="/profile" method="POST">
  <Field controlId="email" describedBy="email-error">
    <Label for="email">Email</Label>
    <Input
      aria-describedby="email-error"
      id="email"
      name="email"
      required
      type="email"
    />
    <FieldError id="email-error" />
  </Field>
  <Button type="submit">Save profile</Button>
</Form>

---
import { Button, Field, FieldError, Form, Input, Label } from '@santi020k/lumen-astro'
---

<Form action="/profile" method="POST">
  <Field controlId="email" describedBy="email-error">
    <Label for="email">Email</Label>
    <Input
      aria-describedby="email-error"
      id="email"
      name="email"
      required
      type="email"
    />
    <FieldError id="email-error" />
  </Field>
  <Button type="submit">Save profile</Button>
</Form>

Choose one validation owner

Three illustrative error snapshots, rendered with Astro. Follow the matching guide to connect validation and submission.

Browser → field

Native mode

Start with required, pattern, min, and max. Astro and Elements enhance validity events; React can use useFormValidation.

Email is required.

See the native form example

React state → field

Managed React mode

React Hook Form owns validation and touched/dirty state. Lumen reflects the result. Avoid a second validation controller.

Enter a complete email address.

Copy the React Hook Form recipe

POST → server → summary

Server-first Astro mode

Astro Actions validate the POST. Render returned values and normalized errors, then redirect after success.

There is a problem

This email is already in use.

This email is already in use.

Copy the Astro Actions recipe

Submitted value contracts

These values are framework-independent and flow through FormData. Arrays are repeated entries; Lumen does not hide objects in undocumented comma-separated strings.

Control	Submitted value
CheckboxGroup	Repeated entries with the same field name
Select / ListBox	One scalar value, or repeated values in multiple mode
DatePicker	ISO calendar date: YYYY-MM-DD
DateRangePicker	Two explicitly named ISO date entries
TimeField	Native local-time string
InputOTP	One scalar string
TagGroup	Repeated entries
FileUpload	Native File entries
ColorPicker	One CSS color string
TreeSelect / Cascader	Stable selected keys, never display labels

Integration guides

React Hook Form adapters

Astro Actions and native POST

Form-associated Elements