ui-form

Component contract

Every form in the Aperture admin is implemented as <UiForm>. The linter scans the React source and flags any data-test attribute claimed as a ui-form instance that isn't rendered through <UiForm>. There is no per-page hand-rolled form path — submit lifecycle, idempotency-key wiring, and error rendering are component responsibility, not caller responsibility.

Props:

• onSubmit: (data) => Promise<void> — async; the form awaits this and manages busy state during the call.
• schema: ZodSchema — validation runs both client-side (before submit) and against the response (server validation errors map back to fields).
• idempotencyKey?: string | "auto" — when set, the form attaches an Idempotency-Key header to its submit. auto derives the key from form content + a per-mount nonce so retries dedupe but distinct fills don't.
• busyOverlay?: boolean — defaults true; freezes inputs while submitting.
• errorRenderer?: "inline" | "summary" | "both" — defaults both; per-field inline errors PLUS a summary at the top of the form when there are 2+ errors.
• submitOn?: "click" | "enter" | "both" — defaults both. Enter submits when focus is in a single-line input; never from a textarea.

Interaction surface

1. User fills fields.

   Each field tracks dirty state. The form's overall dirty state is true if any field is dirty. The submit button's disabled state is computed: enabled when the form is dirty AND passes client-side schema validation. Disabled-but-dirty (validation failing) still allows click — it triggers showing the errors. Disabled-and-pristine (nothing typed yet) is fully unclickable.

2. User submits — Enter key inside a single-line input, click the submit button, or Cmd/Ctrl+Enter from anywhere.

   The form runs client-side validation. If validation fails: show errors (per errorRenderer), focus moves to the first error, the request is NOT made. If validation passes: enter busy state, attach Idempotency-Key header if configured, await onSubmit.

3. During the request: busy state.

   Submit button shows a spinner and the label changes to a busy variant ("Saving…", "Creating event…"). Inputs become readonly (not disabled — that loses focus visibility). The form root has data-busy=true for CSS to style. Cancel-button is shown if onCancel was provided AND the request has been in flight > 250ms; it aborts the request via AbortController.

4. Server response: success.

   onSubmit resolves. The form clears busy state. Caller is responsible for navigation or toast (the form doesn't show its own success message — that's caller-decided UX).

5. Server response: validation error (4xx with field-mapped errors).

   The form parses the error response (expects shape { error: { code, message, fields: { fieldName: messageText } } }) and renders per-field inline errors PLUS a summary if 2+ fields. Focus moves to first errored field. Form returns to non-busy state with input preserved.

6. Server response: non-field error (network, 5xx, 402, 403).

   Form-level error banner appears at top of the form (the form-error-banner attribute). Banner includes a request id (parsed from X-Request-Id response header) when present, copyable for support. Form returns to non-busy state with input preserved. Caller's onSubmit can throw a typed error that the form maps to a friendlier banner message.

Failure modes

Accessibility

• The form root is a <form> element with optional aria-labelledby pointing at a heading.
• Each field's error has aria-live="polite" so announcement happens on render.
• Each field uses aria-invalid="true" and aria-describedby referencing its error message id when in error state.
• Required fields have an asterisk visual marker AND aria-required="true"; an explanation of the asterisk is in the form's accessible name or a per-form helper text.
• Submit button has type="submit"; cancel has type="button".
• Busy state announces "Submitting…" via aria-live="assertive" on the submit button's accessible name.
• Pass axe-core with no serious or critical violations.

Stable test attributes

Component-level contract. Every <UiForm> instance MUST expose these.

Visibility teeth. Each attribute must be present AND effectively visible when the form is rendered. Hiding without removal is treated identically to removal — both require the loosening token.

Agent test plan

- enter-in-input-submits: focus a single-line input, press Enter, assert one submit
- enter-in-textarea-no-submit: focus a textarea, press Enter, assert NO submit AND newline inserted
- cmd-enter-submits-anywhere: focus any field, press Cmd+Enter, assert one submit
- click-during-busy-no-op: click submit while data-busy=true, assert exactly one network call total
- focus-first-error-on-fail: submit with 3 invalid fields, assert document.activeElement is the first errored field
- error-banner-on-non-field: stub onSubmit to throw NetworkError, assert ui-form-error-banner visible with retry hint
- request-id-in-banner: stub onSubmit response with X-Request-Id header, assert banner shows that id
- input-preserved-across-fail: fill name, submit fail, assert name still equals filled value
- field-error-rendering: stub validation error with fields:{name:"taken"}, assert inline error sibling of [name=name] shows "taken"
- summary-when-2-plus-errors: stub validation error with 2 field errors, assert ui-form-error-summary visible
- summary-hidden-with-1-error: stub validation error with 1 field error, assert ui-form-error-summary absent (or aria-hidden)
- idempotency-key-stable-across-retries: submit twice in sequence with auto-key, assert both requests share Idempotency-Key
- idempotency-key-distinct-after-mount: unmount and remount form, submit, assert different Idempotency-Key
- cancel-aborts-after-250ms: trigger long-running submit, after 300ms assert ui-form-cancel visible, click it, assert AbortController fired
- submit-disabled-when-pristine: do not type, assert submit button has aria-disabled=true
- submit-enabled-when-dirty-valid: type valid input, assert submit aria-disabled=false