react-form-draft 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+import { FieldValues, UseFormReturn, Path } from 'react-hook-form';
+
+/**
+ * Synchronous storage adapter used by the draft layer.
+ *
+ * The optional `isAvailable` hook lets adapters communicate that reads and writes
+ * should be skipped entirely, which is helpful for SSR and restricted browsers.
+ */
+interface DraftStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    isAvailable?(): boolean;
+}
+
+type DraftValueMap = Record<string, unknown>;
+type DraftStatus = 'idle' | 'saved' | 'restored' | 'cleared' | 'error';
+interface DraftRecord<TValues extends DraftValueMap = DraftValueMap> {
+    version: string | null;
+    savedAt: number;
+    values: TValues;
+}
+interface DraftMeta {
+    key: string;
+    version: string | null;
+    savedAt: number;
+}
+type UseFormDraftResetOptions<TFieldValues extends FieldValues> = Parameters<UseFormReturn<TFieldValues>['reset']>[1];
+interface UseFormDraftOptions<TFieldValues extends FieldValues> {
+    /**
+     * React Hook Form instance returned by `useForm`.
+     */
+    form: UseFormReturn<TFieldValues>;
+    /**
+     * Unique key used to persist this form's draft.
+     */
+    key: string;
+    /**
+     * Delay between value changes and a persisted save.
+     *
+     * Defaults to `500`.
+     */
+    debounceMs?: number;
+    /**
+     * Optional schema or application version.
+     *
+     * When the stored version does not match, the draft is ignored.
+     */
+    version?: string | null;
+    /**
+     * Custom storage adapter. Defaults to a safe localStorage adapter.
+     */
+    storage?: DraftStorageAdapter;
+    /**
+     * Fields to persist. Supports nested dot-paths from React Hook Form `Path<T>`.
+     *
+     * When `include` and `exclude` are both provided, `include` is applied first
+     * and `exclude` removes paths from that subset.
+     */
+    include?: ReadonlyArray<Path<TFieldValues>>;
+    /**
+     * Fields to omit from persistence. Supports nested dot-paths.
+     */
+    exclude?: ReadonlyArray<Path<TFieldValues>>;
+    /**
+     * Restore the draft automatically on initialization.
+     *
+     * Defaults to `false`.
+     */
+    autoRestore?: boolean;
+    /**
+     * Remove the stored draft after a successful form submission.
+     *
+     * Defaults to `true`.
+     */
+    clearOnSubmit?: boolean;
+    /**
+     * Remove malformed JSON drafts so they do not keep failing on future loads.
+     *
+     * Defaults to `true`.
+     */
+    removeCorruptedDraft?: boolean;
+    /**
+     * Optional reset options forwarded to `form.reset` when restoring a draft.
+     */
+    resetOptions?: UseFormDraftResetOptions<TFieldValues>;
+}
+interface UseFormDraftResult {
+    /**
+     * Indicates whether a valid draft currently exists in storage.
+     */
+    hasDraft: boolean;
+    /**
+     * Metadata for the current draft, if one exists.
+     */
+    draftMeta: DraftMeta | null;
+    /**
+     * Convenience alias of `draftMeta?.savedAt`.
+     */
+    lastSavedAt: number | null;
+    /**
+     * Lifecycle status for the most recent draft action.
+     */
+    status: DraftStatus;
+    /**
+     * Restore the stored draft into the form.
+     *
+     * Returns `true` when a draft was restored.
+     */
+    restoreDraft(): boolean;
+    /**
+     * Remove the persisted draft without mutating current form values.
+     *
+     * This is an alias of `clearDraft` for the "dismiss restore prompt" use case.
+     */
+    discardDraft(): void;
+    /**
+     * Remove the persisted draft without mutating current form values.
+     */
+    clearDraft(): void;
+    /**
+     * Persist the current form state immediately.
+     */
+    saveNow(): void;
+}
+
+/**
+ * Persist and restore React Hook Form values as a browser draft.
+ *
+ * The hook defaults to manual restore mode so consuming applications can decide
+ * whether to auto-restore or show their own confirmation UI.
+ */
+declare function useFormDraft<TFieldValues extends FieldValues>(options: UseFormDraftOptions<TFieldValues>): UseFormDraftResult;
+
+/**
+ * Safe localStorage adapter used by default by `useFormDraft`.
+ *
+ * Reads and writes no-op when `window.localStorage` is unavailable or throws.
+ */
+declare function createLocalStorageAdapter(): DraftStorageAdapter;
+
+export { type DraftMeta, type DraftRecord, type DraftStatus, type DraftStorageAdapter, type UseFormDraftOptions, type UseFormDraftResetOptions, type UseFormDraftResult, createLocalStorageAdapter, useFormDraft };

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import { FieldValues, UseFormReturn, Path } from 'react-hook-form';
+
+/**
+ * Synchronous storage adapter used by the draft layer.
+ *
+ * The optional `isAvailable` hook lets adapters communicate that reads and writes
+ * should be skipped entirely, which is helpful for SSR and restricted browsers.
+ */
+interface DraftStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    isAvailable?(): boolean;
+}
+
+type DraftValueMap = Record<string, unknown>;
+type DraftStatus = 'idle' | 'saved' | 'restored' | 'cleared' | 'error';
+interface DraftRecord<TValues extends DraftValueMap = DraftValueMap> {
+    version: string | null;
+    savedAt: number;
+    values: TValues;
+}
+interface DraftMeta {
+    key: string;
+    version: string | null;
+    savedAt: number;
+}
+type UseFormDraftResetOptions<TFieldValues extends FieldValues> = Parameters<UseFormReturn<TFieldValues>['reset']>[1];
+interface UseFormDraftOptions<TFieldValues extends FieldValues> {
+    /**
+     * React Hook Form instance returned by `useForm`.
+     */
+    form: UseFormReturn<TFieldValues>;
+    /**
+     * Unique key used to persist this form's draft.
+     */
+    key: string;
+    /**
+     * Delay between value changes and a persisted save.
+     *
+     * Defaults to `500`.
+     */
+    debounceMs?: number;
+    /**
+     * Optional schema or application version.
+     *
+     * When the stored version does not match, the draft is ignored.
+     */
+    version?: string | null;
+    /**
+     * Custom storage adapter. Defaults to a safe localStorage adapter.
+     */
+    storage?: DraftStorageAdapter;
+    /**
+     * Fields to persist. Supports nested dot-paths from React Hook Form `Path<T>`.
+     *
+     * When `include` and `exclude` are both provided, `include` is applied first
+     * and `exclude` removes paths from that subset.
+     */
+    include?: ReadonlyArray<Path<TFieldValues>>;
+    /**
+     * Fields to omit from persistence. Supports nested dot-paths.
+     */
+    exclude?: ReadonlyArray<Path<TFieldValues>>;
+    /**
+     * Restore the draft automatically on initialization.
+     *
+     * Defaults to `false`.
+     */
+    autoRestore?: boolean;
+    /**
+     * Remove the stored draft after a successful form submission.
+     *
+     * Defaults to `true`.
+     */
+    clearOnSubmit?: boolean;
+    /**
+     * Remove malformed JSON drafts so they do not keep failing on future loads.
+     *
+     * Defaults to `true`.
+     */
+    removeCorruptedDraft?: boolean;
+    /**
+     * Optional reset options forwarded to `form.reset` when restoring a draft.
+     */
+    resetOptions?: UseFormDraftResetOptions<TFieldValues>;
+}
+interface UseFormDraftResult {
+    /**
+     * Indicates whether a valid draft currently exists in storage.
+     */
+    hasDraft: boolean;
+    /**
+     * Metadata for the current draft, if one exists.
+     */
+    draftMeta: DraftMeta | null;
+    /**
+     * Convenience alias of `draftMeta?.savedAt`.
+     */
+    lastSavedAt: number | null;
+    /**
+     * Lifecycle status for the most recent draft action.
+     */
+    status: DraftStatus;
+    /**
+     * Restore the stored draft into the form.
+     *
+     * Returns `true` when a draft was restored.
+     */
+    restoreDraft(): boolean;
+    /**
+     * Remove the persisted draft without mutating current form values.
+     *
+     * This is an alias of `clearDraft` for the "dismiss restore prompt" use case.
+     */
+    discardDraft(): void;
+    /**
+     * Remove the persisted draft without mutating current form values.
+     */
+    clearDraft(): void;
+    /**
+     * Persist the current form state immediately.
+     */
+    saveNow(): void;
+}
+
+/**
+ * Persist and restore React Hook Form values as a browser draft.
+ *
+ * The hook defaults to manual restore mode so consuming applications can decide
+ * whether to auto-restore or show their own confirmation UI.
+ */
+declare function useFormDraft<TFieldValues extends FieldValues>(options: UseFormDraftOptions<TFieldValues>): UseFormDraftResult;
+
+/**
+ * Safe localStorage adapter used by default by `useFormDraft`.
+ *
+ * Reads and writes no-op when `window.localStorage` is unavailable or throws.
+ */
+declare function createLocalStorageAdapter(): DraftStorageAdapter;
+
+export { type DraftMeta, type DraftRecord, type DraftStatus, type DraftStorageAdapter, type UseFormDraftOptions, type UseFormDraftResetOptions, type UseFormDraftResult, createLocalStorageAdapter, useFormDraft };