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

Native mode

Use Form plus native attributes such as required, pattern, min, and max. Astro and Elements can enhance the same validity events; React can use useFormValidation.

Managed React mode

React Hook Form owns validation and touched/dirty state. Lumen reflects the result. Do not mount useFormValidation on the same form unless duplicate validation is intentional.

Server-first Astro mode

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

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

Search Lumen