react-form-draft 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,33 @@
+# Architecture Notes
+
+## Key Design Decisions
+
+- The public API is centered on a single `useFormDraft` hook because the MVP is intentionally optimized for React Hook Form usage.
+- Drafts are stored as structured records with `version`, `savedAt`, and `values` so restore logic can safely reject stale or malformed data.
+- Storage is abstracted behind a small synchronous adapter interface. The default adapter uses safe localStorage access, but the hook and core helpers do not depend on browser globals directly.
+- Include and exclude filters support nested dot-paths. `include` runs first, then `exclude` trims that subset. This keeps the rules predictable.
+- Restore merges persisted values into the current form snapshot instead of replacing the entire object. That avoids wiping excluded or non-persisted fields during restore.
+
+## Tradeoffs
+
+- The MVP is intentionally tied to React Hook Form types rather than introducing a broader generic form abstraction. That keeps the API smaller and the implementation clearer.
+- Storage is synchronous because localStorage is synchronous. Async adapters such as IndexedDB are postponed to avoid complicating the hook contract in v1.0.
+- Equality checks are implemented internally for JSON-like values rather than pulling in a deep comparison dependency. This keeps runtime weight low.
+- The hook does not attempt multi-tab coordination yet. Draft state is scoped to the current tab lifecycle except for storage persistence itself.
+
+## Security Considerations
+
+- Browser storage is not secure for secrets. The package does not encrypt data and does not claim otherwise.
+- The README documents explicit exclusions for sensitive fields such as passwords, tokens, SSNs, and card data.
+- The package never performs network requests, telemetry, analytics, or dynamic code execution.
+- All storage access is wrapped so storage failures do not crash the host application.
+
+## Intentionally Postponed To v1.1
+
+- `sessionStorage` adapter
+- examples for custom adapters
+- multi-tab synchronization through the `storage` event
+- before-unload and route-leave helpers
+- richer draft metadata and change tracking
+- field-level transforms and alternative serializers
+- IndexedDB exploration for large drafts

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pooya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# react-form-draft
+
+`react-form-draft` helps React applications persist and restore non-sensitive form drafts in the browser, with a first-class React Hook Form API.
+
+It is designed for long forms, dashboard settings pages, onboarding flows, and other form-heavy screens where users may refresh, close a tab, or return later.
+
+## Installation
+
+```bash
+npm install react-form-draft
+```
+
+Peer dependencies:
+
+```bash
+npm install react react-hook-form
+```
+
+## Quick Start
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { useFormDraft } from 'react-form-draft';
+
+interface ProfileFormValues {
+  firstName: string;
+  lastName: string;
+  bio: string;
+}
+
+export function ProfileForm() {
+  const form = useForm<ProfileFormValues>({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+      bio: '',
+    },
+  });
+
+  const draft = useFormDraft({
+    form,
+    key: 'profile-form',
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit((values) => console.log(values))}>
+      <input {...form.register('firstName')} />
+      <input {...form.register('lastName')} />
+      <textarea {...form.register('bio')} />
+
+      {draft.hasDraft ? (
+        <div>
+          <button type="button" onClick={draft.restoreDraft}>
+            Restore draft
+          </button>
+          <button type="button" onClick={draft.discardDraft}>
+            Discard draft
+          </button>
+        </div>
+      ) : null}
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+## React Hook Form Example
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { useFormDraft } from 'react-form-draft';
+
+interface SettingsFormValues {
+  displayName: string;
+  email: string;
+  password: string;
+  token: string;
+  preferences: {
+    locale: string;
+    timezone: string;
+  };
+}
+
+export function SettingsForm() {
+  const form = useForm<SettingsFormValues>({
+    defaultValues: {
+      displayName: '',
+      email: '',
+      password: '',
+      token: '',
+      preferences: {
+        locale: 'en',
+        timezone: 'UTC',
+      },
+    },
+  });
+
+  const {
+    hasDraft,
+    draftMeta,
+    status,
+    restoreDraft,
+    discardDraft,
+    saveNow,
+  } = useFormDraft({
+    form,
+    key: 'settings-form',
+    version: 'settings-v2',
+    debounceMs: 800,
+    autoRestore: false,
+    clearOnSubmit: true,
+    exclude: [
+      'password',
+      'token',
+    ],
+  });
+
+  return (
+    <form
+      onSubmit={form.handleSubmit(async (values) => {
+        await saveSettings(values);
+      })}
+    >
+      {hasDraft ? (
+        <aside>
+          <p>
+            Draft saved at{' '}
+            {draftMeta ? new Date(draftMeta.savedAt).toLocaleString() : 'unknown'}
+          </p>
+          <button type="button" onClick={restoreDraft}>
+            Restore
+          </button>
+          <button type="button" onClick={discardDraft}>
+            Discard
+          </button>
+        </aside>
+      ) : null}
+
+      <input {...form.register('displayName')} />
+      <input {...form.register('email')} />
+      <input type="password" {...form.register('password')} />
+
+      <button type="button" onClick={saveNow}>
+        Save Draft Now
+      </button>
+      <button type="submit">Submit</button>
+
+      <output>{status}</output>
+    </form>
+  );
+}
+```
+
+## API Reference
+
+### `useFormDraft(options)`
+
+```ts
+function useFormDraft<TFieldValues extends FieldValues>(
+  options: UseFormDraftOptions<TFieldValues>,
+): UseFormDraftResult;
+```
+
+### Options
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `form` | `UseFormReturn<TFieldValues>` | Required | React Hook Form instance returned by `useForm`. |
+| `key` | `string` | Required | Unique storage key for the form draft. |
+| `debounceMs` | `number` | `500` | Delay before writes are persisted. |
+| `version` | `string \| null` | `null` | Drafts with a different version are ignored. |
+| `storage` | `DraftStorageAdapter` | Safe localStorage adapter | Useful for tests or custom storage implementations. |
+| `include` | `Path<TFieldValues>[]` | `undefined` | Only these fields are persisted. |
+| `exclude` | `Path<TFieldValues>[]` | `undefined` | These fields are removed from persistence. |
+| `autoRestore` | `boolean` | `false` | Restores immediately instead of exposing a manual prompt flow. |
+| `clearOnSubmit` | `boolean` | `true` | Removes the draft after a successful submit. |
+| `removeCorruptedDraft` | `boolean` | `true` | Removes malformed JSON drafts automatically. |
+| `resetOptions` | `Parameters<form.reset>[1]` | `undefined` | Forwarded to React Hook Form `reset` during restore. |
+
+`include` and `exclude` use dot-paths. When both are provided, `include` is applied first and `exclude` removes paths from that subset.
+
+### Return Value
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `hasDraft` | `boolean` | `true` when a valid stored draft is currently available. |
+| `draftMeta` | `DraftMeta \| null` | Includes `key`, `version`, and `savedAt`. |
+| `lastSavedAt` | `number \| null` | Convenience alias for `draftMeta?.savedAt`. |
+| `status` | `'idle' \| 'saved' \| 'restored' \| 'cleared' \| 'error'` | Latest draft action result. |
+| `restoreDraft()` | `() => boolean` | Restores the cached draft into the form and returns whether it succeeded. |
+| `discardDraft()` | `() => void` | Removes the persisted draft without mutating current form values. |
+| `clearDraft()` | `() => void` | Same behavior as `discardDraft`, useful after submit or reset flows. |
+| `saveNow()` | `() => void` | Saves immediately, bypassing the debounce timer. |
+
+## Restore And Discard Flow
+
+Manual restore mode is the default:
+
+```tsx
+const draft = useFormDraft({
+  form,
+  key: 'article-editor',
+  autoRestore: false,
+});
+
+if (draft.hasDraft) {
+  return (
+    <div>
+      <button type="button" onClick={draft.restoreDraft}>
+        Restore draft
+      </button>
+      <button type="button" onClick={draft.discardDraft}>
+        Start fresh
+      </button>
+    </div>
+  );
+}
+```
+
+If you prefer silent restore:
+
+```tsx
+useFormDraft({
+  form,
+  key: 'article-editor',
+  autoRestore: true,
+});
+```
+
+## Include / Exclude Examples
+
+Persist only part of a form:
+
+```tsx
+useFormDraft({
+  form,
+  key: 'company-profile',
+  include: ['name', 'description', 'contact.email'],
+});
+```
+
+Exclude sensitive or irrelevant fields:
+
+```tsx
+useFormDraft({
+  form,
+  key: 'payment-form',
+  exclude: [
+    'password',
+    'token',
+    'accessToken',
+    'refreshToken',
+    'ssn',
+    'creditCard',
+    'cvv',
+    'secret',
+  ],
+});
+```
+
+## Versioning Example
+
+```tsx
+useFormDraft({
+  form,
+  key: 'product-form',
+  version: 'product-schema-v3',
+});
+```
+
+If the stored draft version does not match, the draft is ignored. This is useful when the form schema changes and older drafts should not be restored.
+
+## Custom Storage Adapter
+
+The adapter interface is synchronous by design for the MVP:
+
+```ts
+interface DraftStorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  isAvailable?(): boolean;
+}
+```
+
+This keeps the package simple while leaving room for future adapters such as `sessionStorage` or IndexedDB-backed implementations.
+
+## SSR Note
+
+`react-form-draft` is safe to import in SSR environments. The default adapter no-ops when `window.localStorage` is unavailable. Draft reads and writes happen only when the browser storage layer is available.
+
+## Security Note
+
+This package stores drafts in browser storage. `localStorage` is not secure for secrets.
+
+Do not persist passwords, tokens, payment data, national identifiers, or other sensitive fields unless you provide your own secure storage adapter and you fully understand the tradeoffs.
+
+Recommended exclusions include:
+
+- `password`
+- `token`
+- `accessToken`
+- `refreshToken`
+- `ssn`
+- `creditCard`
+- `cvv`
+- `secret`
+
+This package never sends data over the network, does not use analytics, and does not attempt fake “encryption” inside browser storage.
+
+## Limitations
+
+- The MVP is optimized for React Hook Form.
+- Draft values should be JSON-serializable.
+- The default adapter uses synchronous browser storage.
+- Multi-tab draft synchronization is not included yet.
+
+## Build Output
+
+The package ships both ESM and CJS builds so it can work cleanly in modern bundlers and older Node/CommonJS integrations. The runtime code stays dependency-light, and type declarations are generated alongside the bundle.
+
+## Roadmap
+
+Planned post-MVP work:
+
+- `sessionStorage` adapter
+- custom adapter cookbook
+- improved last-saved metadata helpers
+- multi-tab synchronization via the `storage` event
+- optional `beforeunload` warning helper
+- optional route-leave guard helper
+- field transformers and custom serializers
+- possible IndexedDB adapter for larger drafts
+
+## License
+
+MIT