@form-engine-ts/react 2.8.0 → 2.9.0

package/README.md

@@ -128,3 +128,9 @@ The Builder basic-settings section edits source `title` and `description` throug
 Submission confirmation slots receive the effective message, localized schema, and visible answers. An `onSubmit` result
 may provide `submissionId` and `submittedAt`, which Renderer copies into its receipt. Receipt stores support `getBatch`,
 and `useSubmissionReceipts` loads multiple form/version receipts for list and dashboard surfaces.
+
+Receipt persistence is best-effort: `onReceiptError` observes storage failures while the successful completion screen is
+preserved. Pass an SSR-safe `createLocalStorageSubmissionAttemptStore()` as `attemptStore` to reserve an ID immediately
+before submission. Renderer injects it as `attemptId` and `submissionId`, retains it after a failed request, promotes it
+to the receipt after success, and then clears the attempt. Custom receipt stores may omit `getBatch`; the hook falls back
+to concurrent `get` calls.

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   FormBuilder: () => FormBuilder,
   FormProvider: () => FormProvider,
   FormRenderer: () => FormRenderer,
+  createLocalStorageSubmissionAttemptStore: () => createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore: () => createLocalStorageSubmissionReceiptStore,
   resolveInitialFieldType: () => resolveInitialFieldType,
   submissionReceiptQueryKey: () => submissionReceiptQueryKey,
@@ -33,6 +34,105 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/attempt.ts
+function attemptKey(namespace, formId, formVersion) {
+  return `${namespace}:${formId}:v${formVersion}`;
+}
+function browserStorage() {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function parseAttempt(serialized) {
+  try {
+    const value = JSON.parse(serialized);
+    if (typeof value !== "object" || value === null || !("attemptId" in value) || typeof value.attemptId !== "string" || value.attemptId.length === 0 || !("formId" in value) || typeof value.formId !== "string" || !("formVersion" in value) || typeof value.formVersion !== "number" || !Number.isSafeInteger(value.formVersion) || !("createdAt" in value) || typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))) {
+      return null;
+    }
+    return {
+      attemptId: value.attemptId,
+      formId: value.formId,
+      formVersion: value.formVersion,
+      createdAt: value.createdAt
+    };
+  } catch {
+    return null;
+  }
+}
+function defaultAttemptId() {
+  const randomUuid = globalThis.crypto?.randomUUID;
+  if (typeof randomUuid === "function") return randomUuid.call(globalThis.crypto);
+  return `attempt-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function createLocalStorageSubmissionAttemptStore(options = {}) {
+  const namespace = options.namespace ?? "form_engine_attempt";
+  if (namespace.trim().length === 0) throw new TypeError("Attempt namespace must not be empty.");
+  const memory = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const get = async (formId, formVersion) => {
+    const key = attemptKey(namespace, formId, formVersion);
+    const remembered = memory.get(key);
+    if (remembered !== void 0) return remembered;
+    const storage = browserStorage();
+    if (storage === null) return null;
+    try {
+      const serialized = storage.getItem(key);
+      if (serialized === null) return null;
+      const attempt = parseAttempt(serialized);
+      if (attempt === null || attempt.formId !== formId || attempt.formVersion !== formVersion) return null;
+      memory.set(key, attempt);
+      return attempt;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    get,
+    async getOrCreate(formId, formVersion, idFactory = defaultAttemptId) {
+      const key = attemptKey(namespace, formId, formVersion);
+      const pending = inFlight.get(key);
+      if (pending !== void 0) return pending;
+      const create = (async () => {
+        const existing = await get(formId, formVersion);
+        if (existing !== null) return existing;
+        const attemptId = idFactory();
+        if (typeof attemptId !== "string" || attemptId.trim().length === 0) {
+          throw new TypeError("Attempt idFactory must return a non-empty string.");
+        }
+        const attempt = {
+          attemptId,
+          formId,
+          formVersion,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        memory.set(key, attempt);
+        try {
+          browserStorage()?.setItem(key, JSON.stringify(attempt));
+        } catch {
+        }
+        return attempt;
+      })();
+      inFlight.set(key, create);
+      try {
+        return await create;
+      } finally {
+        inFlight.delete(key);
+      }
+    },
+    async clear(formId, formVersion) {
+      const key = attemptKey(namespace, formId, formVersion);
+      memory.delete(key);
+      try {
+        browserStorage()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
 // src/builder.tsx
 var import_core2 = require("@form-engine-ts/core");
 var import_react2 = require("react");
@@ -2320,7 +2420,7 @@ function FormProvider({
     setSubmitError(null);
   }, [initialValues]);
   const submit = (0, import_react3.useCallback)(
-    async (beforeSubmit) => {
+    async (beforeSubmit, prepareSubmission) => {
       if (submissionInFlight.current) return { status: "cancelled" };
       const validation = (0, import_core3.validateAnswers)(validSchema, values);
       if (!validation.valid) {
@@ -2341,7 +2441,8 @@ function FormProvider({
           setSubmitStatus("idle");
           return { status: "cancelled" };
         }
-        const response = await onSubmit(visibleValues);
+        const submissionValues = prepareSubmission === void 0 ? visibleValues : await prepareSubmission(visibleValues);
+        const response = await onSubmit(submissionValues);
         if (resetOnSuccess) setValues({ ...initialValues });
         setSubmitStatus("success");
         return response === void 0 ? { status: "success" } : { status: "success", response };
@@ -2420,7 +2521,7 @@ function submissionReceiptQueryKey(formId, formVersion) {
 function receiptKey(namespace, formId, formVersion) {
   return `${namespace}:${formId}:v${formVersion}`;
 }
-function browserStorage() {
+function browserStorage2() {
   if (typeof window === "undefined") return null;
   try {
     return window.localStorage;
@@ -2449,7 +2550,7 @@ function createLocalStorageSubmissionReceiptStore(options = {}) {
   const namespace = options.namespace ?? "form_engine_receipt";
   if (namespace.trim().length === 0) throw new TypeError("Receipt namespace must not be empty.");
   const get = async (formId, formVersion) => {
-    const storage = browserStorage();
+    const storage = browserStorage2();
     if (storage === null) return null;
     try {
       const serialized = storage.getItem(receiptKey(namespace, formId, formVersion));
@@ -2471,12 +2572,12 @@ function createLocalStorageSubmissionReceiptStore(options = {}) {
       );
     },
     async save(receipt) {
-      const storage = browserStorage();
+      const storage = browserStorage2();
       if (storage === null) return;
       storage.setItem(receiptKey(namespace, receipt.formId, receipt.formVersion), JSON.stringify(receipt));
     },
     async remove(formId, formVersion) {
-      const storage = browserStorage();
+      const storage = browserStorage2();
       if (storage === null) return;
       storage.removeItem(receiptKey(namespace, formId, formVersion));
     }
@@ -2505,7 +2606,14 @@ function useSubmissionReceipts(store, queries) {
       };
     }
     setState((current) => ({ ...current, isLoading: true, error: null }));
-    void store.getBatch(stableQueries).then((receipts) => {
+    const load = store.getBatch?.(stableQueries) ?? Promise.all(stableQueries.map((query) => store.get(query.formId, query.formVersion))).then(
+      (receipts) => new Map(
+        receipts.flatMap(
+          (receipt) => receipt === null ? [] : [[submissionReceiptQueryKey(receipt.formId, receipt.formVersion), receipt]]
+        )
+      )
+    );
+    void load.then((receipts) => {
       if (active) setState({ receipts, isLoading: false, error: null });
     }).catch((cause) => {
       if (!active) return;
@@ -2749,6 +2857,8 @@ function ContextFormRenderer({
   onDraftSave,
   submissionGuards = [],
   receiptStore,
+  attemptStore,
+  onReceiptError,
   slots = {}
 }) {
   const form = useForm();
@@ -2906,7 +3016,18 @@ function ContextFormRenderer({
     setGuardMessage(null);
     rendererSubmissionInFlight.current = true;
     try {
-      const result = await form.submit(beforeSubmit);
+      let submissionAttempt;
+      const result = await form.submit(
+        beforeSubmit,
+        attemptStore === void 0 ? void 0 : async (values) => {
+          submissionAttempt = await attemptStore.getOrCreate(form.schema.id, form.schema.version);
+          return {
+            ...values,
+            attemptId: submissionAttempt.attemptId,
+            submissionId: submissionAttempt.attemptId
+          };
+        }
+      );
       if (result.status === "invalid") {
         const invalidPageIndex = pages?.findIndex(
           (page) => firstInvalidFieldId === void 0 ? false : page.questionIds.includes(firstInvalidFieldId)
@@ -2918,14 +3039,29 @@ function ContextFormRenderer({
       if (result.status !== "success") return result;
       if (receiptStore !== void 0) {
         const response = result.response;
+        const submissionId = response?.submissionId ?? submissionAttempt?.attemptId;
         const storedReceipt = {
           formId: form.schema.id,
           formVersion: form.schema.version,
           submittedAt: response?.submittedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-          ...response?.submissionId === void 0 ? {} : { submissionId: response.submissionId }
+          ...submissionId === void 0 ? {} : { submissionId }
         };
-        await receiptStore.save(storedReceipt);
-        setReceipt(storedReceipt);
+        try {
+          await receiptStore.save(storedReceipt);
+          setReceipt(storedReceipt);
+        } catch (cause) {
+          const error = cause instanceof Error ? cause : new Error(String(cause));
+          try {
+            onReceiptError?.(error, storedReceipt);
+          } catch {
+          }
+        }
+      }
+      if (attemptStore !== void 0 && submissionAttempt !== void 0) {
+        try {
+          await attemptStore.clear(form.schema.id, form.schema.version);
+        } catch {
+        }
       }
       if (autoSaveKey !== void 0 && typeof globalThis.localStorage !== "undefined") {
         globalThis.localStorage.removeItem(autoSaveKey);
@@ -3145,6 +3281,7 @@ function FormRenderer(props) {
   FormBuilder,
   FormProvider,
   FormRenderer,
+  createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
   resolveInitialFieldType,
   submissionReceiptQueryKey,

package/dist/index.d.cts

@@ -3,6 +3,21 @@ import { ReactNode, ComponentType, MouseEvent } from 'react';
 import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, FieldOption, TranslationReport, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, ValidationIssue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
 import { SensitiveDataFinding } from '@form-engine-ts/privacy';
 
+interface SubmissionAttempt {
+    readonly attemptId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly createdAt: string;
+}
+interface SubmissionAttemptStore {
+    getOrCreate(formId: string, formVersion: number, idFactory?: () => string): Promise<SubmissionAttempt>;
+    get(formId: string, formVersion: number): Promise<SubmissionAttempt | null>;
+    clear(formId: string, formVersion: number): Promise<void>;
+}
+declare function createLocalStorageSubmissionAttemptStore(options?: {
+    readonly namespace?: string;
+}): SubmissionAttemptStore;
+
 /** @deprecated Import FormPolicy from @form-engine-ts/core instead. */
 type BuilderPolicy = FormPolicy;
 type BuilderIdKind = "field" | "option" | "page";
@@ -97,7 +112,7 @@ interface SubmissionReceiptQuery {
 }
 interface SubmissionReceiptStore {
     get(formId: string, formVersion: number): Promise<SubmissionReceipt | null>;
-    getBatch(queries: readonly SubmissionReceiptQuery[]): Promise<Map<string, SubmissionReceipt>>;
+    getBatch?(queries: readonly SubmissionReceiptQuery[]): Promise<Map<string, SubmissionReceipt>>;
     save(receipt: SubmissionReceipt): Promise<void>;
     remove(formId: string, formVersion: number): Promise<void>;
 }
@@ -356,6 +371,8 @@ interface FormRendererSlots {
 interface SubmissionProtectionProps {
     readonly submissionGuards?: readonly SubmissionGuard[];
     readonly receiptStore?: SubmissionReceiptStore;
+    readonly attemptStore?: SubmissionAttemptStore;
+    readonly onReceiptError?: (error: Error, receipt: SubmissionReceipt) => void;
 }
 type BeforeSubmit = (values: Readonly<Record<string, unknown>>) => "continue" | "cancel" | Promise<"continue" | "cancel">;
 
@@ -403,7 +420,7 @@ interface FormContextValue {
     readonly restoreValues: (values: FormValues) => void;
     readonly validatePage: (pageIndex: number) => AnswerValidationResult;
     readonly reset: () => void;
-    readonly submit: (beforeSubmit?: BeforeSubmit) => Promise<SubmitResult>;
+    readonly submit: (beforeSubmit?: BeforeSubmit, prepareSubmission?: (values: FormValues) => FormValues | Promise<FormValues>) => Promise<SubmitResult>;
     readonly translate: (key: string, params?: Readonly<Record<string, string | number>>) => string;
 }
 interface FormProviderProps {
@@ -458,4 +475,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type InputComponentProps, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type InputComponentProps, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.d.ts

@@ -3,6 +3,21 @@ import { ReactNode, ComponentType, MouseEvent } from 'react';
 import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, FieldOption, TranslationReport, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, ValidationIssue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
 import { SensitiveDataFinding } from '@form-engine-ts/privacy';
 
+interface SubmissionAttempt {
+    readonly attemptId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly createdAt: string;
+}
+interface SubmissionAttemptStore {
+    getOrCreate(formId: string, formVersion: number, idFactory?: () => string): Promise<SubmissionAttempt>;
+    get(formId: string, formVersion: number): Promise<SubmissionAttempt | null>;
+    clear(formId: string, formVersion: number): Promise<void>;
+}
+declare function createLocalStorageSubmissionAttemptStore(options?: {
+    readonly namespace?: string;
+}): SubmissionAttemptStore;
+
 /** @deprecated Import FormPolicy from @form-engine-ts/core instead. */
 type BuilderPolicy = FormPolicy;
 type BuilderIdKind = "field" | "option" | "page";
@@ -97,7 +112,7 @@ interface SubmissionReceiptQuery {
 }
 interface SubmissionReceiptStore {
     get(formId: string, formVersion: number): Promise<SubmissionReceipt | null>;
-    getBatch(queries: readonly SubmissionReceiptQuery[]): Promise<Map<string, SubmissionReceipt>>;
+    getBatch?(queries: readonly SubmissionReceiptQuery[]): Promise<Map<string, SubmissionReceipt>>;
     save(receipt: SubmissionReceipt): Promise<void>;
     remove(formId: string, formVersion: number): Promise<void>;
 }
@@ -356,6 +371,8 @@ interface FormRendererSlots {
 interface SubmissionProtectionProps {
     readonly submissionGuards?: readonly SubmissionGuard[];
     readonly receiptStore?: SubmissionReceiptStore;
+    readonly attemptStore?: SubmissionAttemptStore;
+    readonly onReceiptError?: (error: Error, receipt: SubmissionReceipt) => void;
 }
 type BeforeSubmit = (values: Readonly<Record<string, unknown>>) => "continue" | "cancel" | Promise<"continue" | "cancel">;
 
@@ -403,7 +420,7 @@ interface FormContextValue {
     readonly restoreValues: (values: FormValues) => void;
     readonly validatePage: (pageIndex: number) => AnswerValidationResult;
     readonly reset: () => void;
-    readonly submit: (beforeSubmit?: BeforeSubmit) => Promise<SubmitResult>;
+    readonly submit: (beforeSubmit?: BeforeSubmit, prepareSubmission?: (values: FormValues) => FormValues | Promise<FormValues>) => Promise<SubmitResult>;
     readonly translate: (key: string, params?: Readonly<Record<string, string | number>>) => string;
 }
 interface FormProviderProps {
@@ -458,4 +475,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type InputComponentProps, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type InputComponentProps, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, resolveInitialFieldType, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.js

@@ -1,3 +1,102 @@
+// src/attempt.ts
+function attemptKey(namespace, formId, formVersion) {
+  return `${namespace}:${formId}:v${formVersion}`;
+}
+function browserStorage() {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function parseAttempt(serialized) {
+  try {
+    const value = JSON.parse(serialized);
+    if (typeof value !== "object" || value === null || !("attemptId" in value) || typeof value.attemptId !== "string" || value.attemptId.length === 0 || !("formId" in value) || typeof value.formId !== "string" || !("formVersion" in value) || typeof value.formVersion !== "number" || !Number.isSafeInteger(value.formVersion) || !("createdAt" in value) || typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))) {
+      return null;
+    }
+    return {
+      attemptId: value.attemptId,
+      formId: value.formId,
+      formVersion: value.formVersion,
+      createdAt: value.createdAt
+    };
+  } catch {
+    return null;
+  }
+}
+function defaultAttemptId() {
+  const randomUuid = globalThis.crypto?.randomUUID;
+  if (typeof randomUuid === "function") return randomUuid.call(globalThis.crypto);
+  return `attempt-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function createLocalStorageSubmissionAttemptStore(options = {}) {
+  const namespace = options.namespace ?? "form_engine_attempt";
+  if (namespace.trim().length === 0) throw new TypeError("Attempt namespace must not be empty.");
+  const memory = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const get = async (formId, formVersion) => {
+    const key = attemptKey(namespace, formId, formVersion);
+    const remembered = memory.get(key);
+    if (remembered !== void 0) return remembered;
+    const storage = browserStorage();
+    if (storage === null) return null;
+    try {
+      const serialized = storage.getItem(key);
+      if (serialized === null) return null;
+      const attempt = parseAttempt(serialized);
+      if (attempt === null || attempt.formId !== formId || attempt.formVersion !== formVersion) return null;
+      memory.set(key, attempt);
+      return attempt;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    get,
+    async getOrCreate(formId, formVersion, idFactory = defaultAttemptId) {
+      const key = attemptKey(namespace, formId, formVersion);
+      const pending = inFlight.get(key);
+      if (pending !== void 0) return pending;
+      const create = (async () => {
+        const existing = await get(formId, formVersion);
+        if (existing !== null) return existing;
+        const attemptId = idFactory();
+        if (typeof attemptId !== "string" || attemptId.trim().length === 0) {
+          throw new TypeError("Attempt idFactory must return a non-empty string.");
+        }
+        const attempt = {
+          attemptId,
+          formId,
+          formVersion,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        memory.set(key, attempt);
+        try {
+          browserStorage()?.setItem(key, JSON.stringify(attempt));
+        } catch {
+        }
+        return attempt;
+      })();
+      inFlight.set(key, create);
+      try {
+        return await create;
+      } finally {
+        inFlight.delete(key);
+      }
+    },
+    async clear(formId, formVersion) {
+      const key = attemptKey(namespace, formId, formVersion);
+      memory.delete(key);
+      try {
+        browserStorage()?.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
 // src/builder.tsx
 import {
   populateSchemaTranslations
@@ -2299,7 +2398,7 @@ function FormProvider({
     setSubmitError(null);
   }, [initialValues]);
   const submit = useCallback2(
-    async (beforeSubmit) => {
+    async (beforeSubmit, prepareSubmission) => {
       if (submissionInFlight.current) return { status: "cancelled" };
       const validation = validateAnswers(validSchema, values);
       if (!validation.valid) {
@@ -2320,7 +2419,8 @@ function FormProvider({
           setSubmitStatus("idle");
           return { status: "cancelled" };
         }
-        const response = await onSubmit(visibleValues);
+        const submissionValues = prepareSubmission === void 0 ? visibleValues : await prepareSubmission(visibleValues);
+        const response = await onSubmit(submissionValues);
         if (resetOnSuccess) setValues({ ...initialValues });
         setSubmitStatus("success");
         return response === void 0 ? { status: "success" } : { status: "success", response };
@@ -2399,7 +2499,7 @@ function submissionReceiptQueryKey(formId, formVersion) {
 function receiptKey(namespace, formId, formVersion) {
   return `${namespace}:${formId}:v${formVersion}`;
 }
-function browserStorage() {
+function browserStorage2() {
   if (typeof window === "undefined") return null;
   try {
     return window.localStorage;
@@ -2428,7 +2528,7 @@ function createLocalStorageSubmissionReceiptStore(options = {}) {
   const namespace = options.namespace ?? "form_engine_receipt";
   if (namespace.trim().length === 0) throw new TypeError("Receipt namespace must not be empty.");
   const get = async (formId, formVersion) => {
-    const storage = browserStorage();
+    const storage = browserStorage2();
     if (storage === null) return null;
     try {
       const serialized = storage.getItem(receiptKey(namespace, formId, formVersion));
@@ -2450,12 +2550,12 @@ function createLocalStorageSubmissionReceiptStore(options = {}) {
       );
     },
     async save(receipt) {
-      const storage = browserStorage();
+      const storage = browserStorage2();
       if (storage === null) return;
       storage.setItem(receiptKey(namespace, receipt.formId, receipt.formVersion), JSON.stringify(receipt));
     },
     async remove(formId, formVersion) {
-      const storage = browserStorage();
+      const storage = browserStorage2();
       if (storage === null) return;
       storage.removeItem(receiptKey(namespace, formId, formVersion));
     }
@@ -2484,7 +2584,14 @@ function useSubmissionReceipts(store, queries) {
       };
     }
     setState((current) => ({ ...current, isLoading: true, error: null }));
-    void store.getBatch(stableQueries).then((receipts) => {
+    const load = store.getBatch?.(stableQueries) ?? Promise.all(stableQueries.map((query) => store.get(query.formId, query.formVersion))).then(
+      (receipts) => new Map(
+        receipts.flatMap(
+          (receipt) => receipt === null ? [] : [[submissionReceiptQueryKey(receipt.formId, receipt.formVersion), receipt]]
+        )
+      )
+    );
+    void load.then((receipts) => {
       if (active) setState({ receipts, isLoading: false, error: null });
     }).catch((cause) => {
       if (!active) return;
@@ -2738,6 +2845,8 @@ function ContextFormRenderer({
   onDraftSave,
   submissionGuards = [],
   receiptStore,
+  attemptStore,
+  onReceiptError,
   slots = {}
 }) {
   const form = useForm();
@@ -2895,7 +3004,18 @@ function ContextFormRenderer({
     setGuardMessage(null);
     rendererSubmissionInFlight.current = true;
     try {
-      const result = await form.submit(beforeSubmit);
+      let submissionAttempt;
+      const result = await form.submit(
+        beforeSubmit,
+        attemptStore === void 0 ? void 0 : async (values) => {
+          submissionAttempt = await attemptStore.getOrCreate(form.schema.id, form.schema.version);
+          return {
+            ...values,
+            attemptId: submissionAttempt.attemptId,
+            submissionId: submissionAttempt.attemptId
+          };
+        }
+      );
       if (result.status === "invalid") {
         const invalidPageIndex = pages?.findIndex(
           (page) => firstInvalidFieldId === void 0 ? false : page.questionIds.includes(firstInvalidFieldId)
@@ -2907,14 +3027,29 @@ function ContextFormRenderer({
       if (result.status !== "success") return result;
       if (receiptStore !== void 0) {
         const response = result.response;
+        const submissionId = response?.submissionId ?? submissionAttempt?.attemptId;
         const storedReceipt = {
           formId: form.schema.id,
           formVersion: form.schema.version,
           submittedAt: response?.submittedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-          ...response?.submissionId === void 0 ? {} : { submissionId: response.submissionId }
+          ...submissionId === void 0 ? {} : { submissionId }
         };
-        await receiptStore.save(storedReceipt);
-        setReceipt(storedReceipt);
+        try {
+          await receiptStore.save(storedReceipt);
+          setReceipt(storedReceipt);
+        } catch (cause) {
+          const error = cause instanceof Error ? cause : new Error(String(cause));
+          try {
+            onReceiptError?.(error, storedReceipt);
+          } catch {
+          }
+        }
+      }
+      if (attemptStore !== void 0 && submissionAttempt !== void 0) {
+        try {
+          await attemptStore.clear(form.schema.id, form.schema.version);
+        } catch {
+        }
       }
       if (autoSaveKey !== void 0 && typeof globalThis.localStorage !== "undefined") {
         globalThis.localStorage.removeItem(autoSaveKey);
@@ -3133,6 +3268,7 @@ export {
   FormBuilder,
   FormProvider,
   FormRenderer,
+  createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
   resolveInitialFieldType,
   submissionReceiptQueryKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/react",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -42,8 +42,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.8.0",
-    "@form-engine-ts/privacy": "2.8.0"
+    "@form-engine-ts/core": "2.9.0",
+    "@form-engine-ts/privacy": "2.9.0"
   },
   "peerDependencies": {
     "react": ">=18.2 <20",