Object Form Robustness — Design

Date: 2026-06-07 Status: Approved (brainstorming) — ready for implementation planning. Issue: #46.

Context

The object create/edit form has data-integrity gaps that compound in long daily cataloguing sessions (High severity):

Submit never disabled during save. object-form.tsx submit button has no disabled/pending. Both create (object-new-page.tsx) and edit (object-edit-form.tsx) do two sequential awaited mutations (create/update, then setFields) with no feedback → a second click can duplicate-create or race the two-step write. publish-control.tsx is the model (disables on isPending).
No unsaved-changes guard. No isDirty/useBlocker/beforeunload; Cancel/nav loses work silently.
Two-phase write recovers inconsistently. Create teleports to the edit page on setFields failure; edit stays put with a banner. The partial write (core saved, field rejected) reads as nothing happened.
Thin validation. Core errors always show form.required; the server code (type_mismatch/unresolved/unknown) on FieldRejection is discarded; no number_of_objects >= 1.
No "Save & create another" / keyboard submit for batch entry.

Facts established: the form uses react-hook-form (so formState.isDirty + isSubmitting are available; isSubmitting stays true across both awaited mutations — the unified pending signal). ObjectForm props: mode, defaults, onSubmit, onCancel, formError, fieldErrorKey; the 422→highlight path uses form.setError. FieldRejection (queries.ts) carries field + code. The router is <BrowserRouter> + <Routes> (component router) in app.tsx; useBlocker requires a data router (createBrowserRouter + RouterProvider). renderApp wraps ui in <MemoryRouter> with no <Routes> (tests supply their own when they need params).

Decisions (from brainstorming)

Migrate to a data router (the long-term-correct foundation; unblocks useBlocker and React Router v7 data APIs). Done via createRoutesFromElements to keep the exact route tree (minimal diff), isolated as the first task, with the test harness moved to createMemoryRouter.
Unify create partial-failure to the edit route with a distinct "Object created, but a field was rejected" banner (single recovery surface).
Include batch entry ("Save & create another" + Cmd/Ctrl+Enter).

Components

0. Data-router migration (foundation — isolated)

app.tsx: replace <BrowserRouter><Routes>…</Routes></BrowserRouter> with a module-level const router = createBrowserRouter(createRoutesFromElements(<>…the existing <Route> tree…</>)) and export function App() { return <RouterProvider router={router} />; }. The route JSX (login, RequireAuth→AppShell nest with all nested routes, lazy Suspense wrappers, splat) moves verbatim into createRoutesFromElements. No behavior/path change.
main.tsx: unchanged provider stack (QueryClient → Config → Toast) now wraps <App/> which is <RouterProvider/>.
test/render.tsx: renderApp(ui, { route }) switches to createMemoryRouter([{ path: "*", element: ui }], { initialEntries: [route] }) rendered via <RouterProvider/> (inside QueryClientProvider). Behavior-preserving: ui renders at route, and tests that supply their own <Routes> still nest correctly; now a data-router context exists so useBlocker works. Acceptance: the entire existing suite stays green before any feature is built on top.

1. Submit pending + keyboard + batch (`object-form.tsx`)

Submit <Button type="submit" disabled={form.formState.isSubmitting}> showing isSubmitting ? t("form.saving") : (mode === "create" ? t("form.create") : t("form.save")). Disable Cancel while submitting. (isSubmitting is true across both awaited mutations because RHF awaits the async onSubmit.)
Cmd/Ctrl+Enter submits: a keydown handler on the form ((e.metaKey||e.ctrlKey) && e.key==="Enter" → form.handleSubmit(...)), or rely on the native submit + a small handler. Implementer picks the clean form; must not double-submit.
"Save & create another" (create mode only): a secondary submit button. ObjectForm gains an optional onSubmitAndNew?: (values) => Promise<void> (or a submitAction flag passed to onSubmit) so the create page knows which button fired. On success it form.reset(blankDefaults) and focuses the first field instead of navigating. Edit mode does not show this button.

2. Validation messages

Server code echo: when a FieldRejection is shown, pick the message by code — form.fieldError.type_mismatch / form.fieldError.unresolved / form.fieldError.unknown (fallback to the existing form.fieldRejected). The create/edit pages already extract e.field; also pass e.code through to ObjectForm (extend fieldErrorKey handling to carry a code, e.g. a fieldError?: { key: string; code?: string } prop, or a second fieldErrorCode? prop). The highlight form.setError message uses the code-specific string.
Core-field messages: render the RHF error by type — errors.core[key]?.type === "min" → form.min (with the limit), else form.required. (Today it's always form.required.)
number_of_objects >= 1: register with min: { value: 1, message: t("form.minCount") } (RHF, client-side, before the round-trip). Keep required.

3. Unsaved-changes guard (`lib/use-unsaved-changes.tsx`)

useUnsavedChanges(isDirty: boolean):
- adds a beforeunload listener while isDirty (covers reload / tab-close / browser back),
- calls useBlocker(({currentLocation,nextLocation}) => isDirty && currentLocation.pathname !== nextLocation.pathname) to block in-app navigation while dirty,
- returns the blocker so the caller renders an UnsavedChangesDialog when blocker.state === "blocked" (Stay → blocker.reset(), Leave → blocker.proceed()).
UnsavedChangesDialog built on ui/alert-dialog (title/body/Stay/Leave). New i18n form.unsaved.{title,body,stay,leave}.
Wire into ObjectForm: const isDirty = form.formState.isDirty; → useUnsavedChanges(isDirty); render the dialog. The Cancel button: if dirty, open the same confirm dialog (Leave → onCancel); if clean, onCancel directly.
Suppress on successful save: after a successful submit the form navigates; isDirty must be false by then (RHF reset on success, or the blocker condition excludes the programmatic post-save nav). The create→edit partial-failure nav is programmatic and must not be blocked — reset dirty (or set a "saving" ref that bypasses the blocker) around the save so the post-save/teleport navigation isn't caught. Implementer ensures save-driven navigation never triggers the guard.

4. Partial-failure unification

Create (object-new-page.tsx): on setFields failure after the core create succeeds, navigate to /objects/${id}/edit with state: { created: true, fieldErrorKey: e.field, fieldErrorCode: e.code } (today it passes fieldsError/fieldErrorKey; add created + code). The core-create already succeeded, so this is correct (the object exists; editing it is the right URL).
Edit (object-edit-form.tsx): read location.state. If created, show the banner form.createdButFieldRejected ("Object created, but a field was rejected — fix it below"); otherwise the existing rejection banner. Both highlight the field (via fieldErrorKey + code). Edit's own in-place partial-failure (update ok, setFields fails) keeps staying-put with its banner.
Result: a single recovery surface (the edit form) for both flows, with create messaged as "created."

Data flow

RHF manages form state → isSubmitting disables submit across both mutations → isDirty drives the guard (beforeunload + useBlocker + dialog) → on save success the form is clean and navigates → on create partial-failure it navigates to the edit route with created state → the edit form shows the "created" banner + field highlight (code-specific message).

Error handling / edges

isSubmitting covers the whole two-phase write (RHF awaits onSubmit); a second click is a no-op (button disabled).
The guard must not fire on save-driven navigation (post-success or create→edit teleport) — reset dirty / bypass ref around saves.
beforeunload only prompts while dirty (don't attach unconditionally).
useBlocker now works (data router). Tests render under createMemoryRouter (harness change) so the blocker is exercisable.
A FieldRejection with an unknown code falls back to the generic form.fieldRejected.
number_of_objects min is client-side UX; the server remains source of truth.

Testing

Migration: the full existing suite passes under the new createMemoryRouter harness (no behavior change) — this is the gate for Task 1.
Submit disable: during an in-flight save the submit button is disabled and reads "Saving…"; a double-click fires the create mutation once (assert call count).
Keyboard: Cmd/Ctrl+Enter submits.
Save & create another: create mode → success resets the form (fields cleared, stays on /new), does not navigate to detail.
Validation: a FieldRejection with code: "type_mismatch" shows the code-specific message; number_of_objects = 0 shows form.minCount without hitting the server.
Dirty guard: with a dirty form, attempting in-app nav shows the dialog (Stay keeps you, Leave proceeds); Cancel-when-dirty confirms; a clean form navigates freely; beforeunload listener added only when dirty (assert via the registered handler / a spy).
Partial-failure: create with a setFields 422 → lands on /objects/:id/edit with the "Object created, but a field was rejected" banner + field highlight; edit's own setFields 422 → stays with its banner. (Extend object-new-page.test.tsx / object-edit-form.test.tsx.)
Gate: typecheck/lint/test/build/check:size/check:colors; en/sv parity for all new keys; no codename.

Acceptance criteria

The app uses a data router (createBrowserRouter + RouterProvider) with the route tree unchanged; the test harness uses createMemoryRouter; the full suite is green.
The submit button is disabled and shows "Saving…" while either mutation is pending; no double-submit / duplicate-create is possible from the UI.
A dirty form guards navigation: useBlocker dialog on in-app nav, beforeunload on reload/close, and Cancel confirms when dirty; saving navigates without a false prompt.
Create and edit share one partial-failure recovery surface (the edit form); the create case is messaged "Object created, but a field was rejected" and highlights the field.
Field-rejection messages reflect the server code; core errors show type-specific messages; number_of_objects >= 1 is validated client-side.
Create mode offers "Save & create another" (resets the form) and Cmd/Ctrl+Enter submit.
typecheck/lint/test/build/check:size/check:colors green; en/sv parity; no codename; no new npm dependency.

Out of scope → follow-ups

Flexible-field grouping/ordering (#45 / detail), per-field server validation rules (#11).
Turning core-field 422s into per-field FieldRejections server-side (the core mutations still throw generic errors; only setFields yields field-level codes).
Autosave / draft persistence.

11 KiB Raw Blame History