ui-public-form-flow

Component contract

• fields: FieldDef[] — identity inputs (name, email, optional custom registration questions per EF-039/040)
• consentRequired?: ConsentDef — when set, renders a never-pre-checked consent block per EF-006 GDPR contract; submit blocked until checked
• onSubmit: (values, idempotencyKey) => Promise<SubmitResult> — parent owns transport; harness asserts the same idempotencyKey is reused across retries
• successView: ReactNode — what to render after success (confirmation, code, next steps)
• alreadyCompletedView?: ReactNode — for browser-back-after-success; shows the prior submission as read-only
• idempotencyKeyPrefix: string — used to derive per-session keys (e.g., "register-", "transfer-", "waitlist-")
• capacityState?: { current: number; max: number } — when provided, displays remaining and surfaces capacity-full mid-fill conversion offer
• capacityFullView?: ReactNode — what to render when capacity hits zero before submit (typically a waitlist offer)
• antiProbingResponseView: ReactNode — universal "we couldn't process this" view used when ANY of: not-found, archived, draft, deleted, capacity-full-without-conversion-option, invalid-token, expired-token rejects. Same UI/timing across all rejection cases.
• rateLimit?: { perMinute: number } — bot-fill protection; defaults to 5
• renderMode?: "modal" | "page" — defaults to "page"; modal mode wraps in ui-modal

Composition

• ui-modal — when renderMode=modal; inherits focus-trap + esc-closes
• ui-form — submission lifecycle; busy state during in-flight submit
• ui-text-input — per identity field
• ui-checkbox — when consentRequired is set
• ui-toast — for transient errors (network, validation)
• ui-status-pill — for capacity remaining ("3 spots left") and success state

Interaction surface

1. Initial render: identity fields + (consent) + submit.

   Submit button disabled until required fields valid AND (when applicable) consent checked. Stable per-form idempotency key generated on mount, persisted to sessionStorage, reused across retries.

2. Capacity remaining surfaces inline.

   When capacityState is provided, "3 spots left" pill renders prominently. As capacity ticks down via parent-driven re-render, the pill updates. At 0, transitions to capacityFullView.

3. Submit fires onSubmit with idempotencyKey.

   Header `Idempotency-Key: -` sent. Form enters busy state. Network failure → retry with SAME key (no double-register). Validation rejection → return to filled-form state with errors per ui-form contract.

4. Success → render successView.

   SuccessView fully replaces the form region. Browser-back navigates to a route that re-resolves to alreadyCompletedView (not the form). Form state clears from sessionStorage on success.

5. Anti-probing rejection → universal antiProbingResponseView.

   Any 4xx (404 not-found, 410 gone, 422 capacity-full-without-conversion, 401 token-revoked) renders the SAME view. Same response timing target (within 50ms across cases). Same UI surface. No leak about which rejection case applied.

Failure modes

Accessibility

• Inherits ui-form, ui-text-input, ui-checkbox a11y contracts.
• Modal mode inherits ui-modal a11y.
• SuccessView has role="status" + aria-live="polite" so screen readers announce completion.
• antiProbingResponseView has role="alert" — screen reader announces the rejection clearly without revealing details.
• Capacity remaining pill inherits ui-status-pill a11y.
• axe-clean ≥ serious across all states (form, busy, success, already-completed, anti-probing-response, capacity-full-conversion, rate-limited).

Stable test attributes

Agent test plan

- form-renders-in-page-mode: renderMode=page, ui-public-form-flow data-state=form
- form-renders-in-modal-mode: renderMode=modal, wrapped in ui-modal
- submit-disabled-until-valid: empty required field, submit disabled
- submit-disabled-until-consent: consentRequired, checkbox unchecked, submit disabled
- consent-never-prechecked: render with consentRequired, checkbox.checked=false
- idempotency-key-sent: submit, Idempotency-Key header matches prefix
- network-drop-retry-same-key: stub drop + retry, second request same key
- two-tab-idempotency: 2 concurrent submits, exactly 1 server row
- success-view-replaces-form: success → ui-public-form-flow-success visible, form hidden
- browser-back-shows-already-completed: success + back, ui-public-form-flow-already-completed visible
- browser-back-no-resubmit: back navigation, NO POST request
- anti-probing-pixel-identical: each rejection case → screenshot identical
- anti-probing-timing-similar: each rejection case → response time within 50ms
- og-tags-present: head has og:title, og:description, og:image, og:url all non-empty
- bot-fill-rate-limit-429: 6 submits in 60s, 6th surfaces rate-limit
- capacity-full-conversion-offer: stub 422 CAPACITY_FULL, conversion view visible
- capacity-full-conversion-flow: click join-waitlist, second submit with intent=waitlist
- validation-focuses-first-error: empty submit, activeElement is first input
- aria-live-on-success: success view has role=status + aria-live=polite
- aria-alert-on-anti-probing: anti-probing view has role=alert
- axe-clean-across-states: every state passes axe ≥ serious

Current consumers

Tightening payoff: each branch can drop ~150 lines of inlined contract (form lifecycle, idempotency, anti-probing, browser-back, og-tags, rate-limit) and reference this component instead. Future tightening of the public-form contract ratchets all 6 consumers automatically.