Skip to content

v0.3: fieldsNeedingReentry — surface excludeFields after restore #15

@mayrang

Description

@mayrang

Problem

When `excludeFields: ['password']` is set in a multi-step wizard, the user fills the password in step 1 and progresses to step 5. `step` is persisted, password is not. On refresh, the app restores at step 5 but the password field is empty. The user clicks Submit and the server receives an empty password — silent UX failure.

Proposed API

Add a derived field to `FormDraftResult`:

```ts
draft.fieldsNeedingReentry: ReadonlyArray<keyof T & string>;
```

Populated when storage restore happens AND the excluded fields were non-default before the persist that's being restored. Auto-clears per-field when the user re-enters a non-default value.

Implementation sketch

  1. `stored record` shape adds optional `__excludedHad?: string[]` — key names only, never values
  2. On each persist: scan `excludeFields`, list keys where `!Object.is(value, defaultValue)` → record
  3. On restore: hydrate `__excludedHad` into internal state
  4. Per-render: `fieldsNeedingReentry = excludedHadOnRestore.filter(k => Object.is(values[k], defaultValues[k]))`
  5. `discard()` clears

Exposed via

  • `FormDraftResult`
  • `useFormDraftStatus(key)`
  • `getFormDraft(key)` handle (`getFieldsNeedingReentry()`)
  • RHF / Formik / TanStack adapters

Backward compat

Pre-0.3.0 records have no `__excludedHad` field → `fieldsNeedingReentry === []` on restore. Safe.

Acceptance

  • Unit tests: persist writes/omits the flag correctly; restore populates; user filling clears; discard clears; multi-field subset behavior
  • e2e: wizard scenario where step persists past the password step
  • README: new short section explaining the pattern
  • Adapters all expose the field

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions