Form workflow

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Connect validation, pending submission, field errors, request failures, restricted access, and success with Form, Field, Fieldset, and messages. Keep input values in controlled state. Describe the result with the values copied at submit time. The example settles the response manually. Use Complete preview request to inspect each state.

• Don't hide service calls or permission policies inside primitives. Keep them in the product.
• Don't present errors as an empty success. Show field errors, request failures, and restricted access as their own states.
• Don't promise that canceling rolls back the server. Canceling stops the request and preserves the draft.
• Don't rely on client checks alone. The product API also needs server validation, permission checks, idempotency, and duplicate-request prevention.
• The example simulates restoring access locally.

Anatomy

Preview response control → result message → named Form → Fieldset(Fields + errors) + submit/reset actions → pending request controls

Keyboard and accessibility

• Base UI Form runs pre-submit validation and focuses the first invalid input.
• While pending, duplicate submissions are blocked and focus moves to Cancel.
• Server field errors map to fields through Field.name keys in errors. A field error moves focus to its input, a request error to Retry, and success to the result heading.
• Canceling or resetting returns focus to the name input.
• Field links each description and error to its control. Color never carries meaning alone.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Form, Field, Fieldset, Button } from '@surflane/ui'

<Form errors={serverErrors} onFormSubmit={submit} aria-busy={pending}>
  <Fieldset.Root disabled={pending}>
    <Fieldset.Legend>Environment details</Fieldset.Legend>
    <Field.Root name='name'>
      <Field.Label>Environment name</Field.Label>
      <Field.Control
        required
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <Field.Error />
    </Field.Root>
  </Fieldset.Root>
  <Button type='submit' disabled={pending}>
    Register preview
  </Button>
</Form>

// Product-owned submission contract:
// 1. Guard repeated submits before awaiting. Snapshot validated values.
// 2. Retain an AbortController and request identity.
// 3. Ignore aborted, superseded or unmounted responses.
// 4. Map field errors by Field.name; preserve draft and restore meaningful focus.
// 5. Server-side idempotency and authorization remain required.

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens