@form-engine-ts/react 2.7.0 → 2.9.0

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
@@ -945,6 +1044,9 @@ var FIELD_TYPES = [
 ];
 var BUILDER_DEFAULTS = {
   "builder.formBuilder": "Form builder",
+  "builder.basicSettings": "Basic settings",
+  "builder.formTitle": "Form title",
+  "builder.formDescription": "Form description",
   "builder.moveUp": "Move {{title}} up",
   "builder.moveDown": "Move {{title}} down",
   "builder.delete": "Delete {{title}}",
@@ -1110,7 +1212,7 @@ function FormBuilder({
 }) {
   const resolvedComponents = { ...DEFAULT_COMPONENTS, ...componentOverrides };
   const components = GUARDED_COMPONENTS;
-  const { Button, Checkbox, ErrorMessage, Fieldset, IconButton, Section, Select, TextInput } = components;
+  const { Button, Checkbox, ErrorMessage, Fieldset, IconButton, Section, Select, TextArea, TextInput } = components;
   const ToolbarSlot = slots?.toolbar;
   const FieldEditorSlot = slots?.fieldEditor;
   const OptionEditorSlot = slots?.optionEditor;
@@ -1413,6 +1515,42 @@ function FormBuilder({
         }
       },
       children: /* @__PURE__ */ jsxs(Fieldset, { className: "form-engine-builder__controls", disabled: readOnly, children: [
+        /* @__PURE__ */ jsx(
+          Section,
+          {
+            className: "form-engine-builder__basic-settings",
+            headingId: "builder-basic-settings-heading",
+            title: translate("builder.basicSettings"),
+            children: /* @__PURE__ */ jsxs("div", { className: "form-engine-builder__grid", children: [
+              /* @__PURE__ */ jsxs("label", { children: [
+                translate("builder.formTitle"),
+                /* @__PURE__ */ jsx(
+                  TextInput,
+                  {
+                    name: "title",
+                    required: true,
+                    error: schema.title.trim().length === 0,
+                    helperText: schema.title.trim().length === 0 ? translate("builder.required") : "",
+                    value: schema.title,
+                    onChange: (value) => setSourceText({ kind: "form" }, "title", value)
+                  }
+                )
+              ] }),
+              /* @__PURE__ */ jsxs("label", { children: [
+                translate("builder.formDescription"),
+                /* @__PURE__ */ jsx(
+                  TextArea,
+                  {
+                    name: "description",
+                    rows: 3,
+                    value: schema.description ?? "",
+                    onChange: (value) => setSourceText({ kind: "form" }, "description", value)
+                  }
+                )
+              ] })
+            ] })
+          }
+        ),
         pagesEnabled ? PagesSlot === void 0 ? /* @__PURE__ */ jsx(
           Section,
           {
@@ -2260,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) {
@@ -2281,10 +2419,11 @@ function FormProvider({
           setSubmitStatus("idle");
           return { status: "cancelled" };
         }
-        await onSubmit(visibleValues);
+        const submissionValues = prepareSubmission === void 0 ? visibleValues : await prepareSubmission(visibleValues);
+        const response = await onSubmit(submissionValues);
         if (resetOnSuccess) setValues({ ...initialValues });
         setSubmitStatus("success");
-        return { status: "success" };
+        return response === void 0 ? { status: "success" } : { status: "success", response };
       } catch (cause) {
         const error = cause instanceof Error ? cause : new Error(String(cause));
         setSubmitError(error);
@@ -2353,10 +2492,14 @@ function useField(fieldId) {
 }
 
 // src/receipt.ts
+import { useEffect as useEffect2, useMemo as useMemo3, useState as useState3 } from "react";
+function submissionReceiptQueryKey(formId, formVersion) {
+  return `${formId}:v${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;
@@ -2384,31 +2527,86 @@ function parseReceipt(serialized) {
 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 = browserStorage2();
+    if (storage === null) return null;
+    try {
+      const serialized = storage.getItem(receiptKey(namespace, formId, formVersion));
+      if (serialized === null) return null;
+      const receipt = parseReceipt(serialized);
+      return receipt?.formId === formId && receipt.formVersion === formVersion ? receipt : null;
+    } catch {
+      return null;
+    }
+  };
   return {
-    async get(formId, formVersion) {
-      const storage = browserStorage();
-      if (storage === null) return null;
-      try {
-        const serialized = storage.getItem(receiptKey(namespace, formId, formVersion));
-        if (serialized === null) return null;
-        const receipt = parseReceipt(serialized);
-        return receipt?.formId === formId && receipt.formVersion === formVersion ? receipt : null;
-      } catch {
-        return null;
-      }
+    get,
+    async getBatch(queries) {
+      const receipts = await Promise.all(queries.map((query) => get(query.formId, query.formVersion)));
+      return new Map(
+        receipts.flatMap(
+          (receipt) => receipt === null ? [] : [[submissionReceiptQueryKey(receipt.formId, receipt.formVersion), receipt]]
+        )
+      );
     },
     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));
     }
   };
 }
+function useSubmissionReceipts(store, queries) {
+  const querySignature = JSON.stringify(queries.map(({ formId, formVersion }) => [formId, formVersion]));
+  const stableQueries = useMemo3(() => {
+    const parsed = JSON.parse(querySignature);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.flatMap(
+      (entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "number" && Number.isSafeInteger(entry[1]) ? [{ formId: entry[0], formVersion: entry[1] }] : []
+    );
+  }, [querySignature]);
+  const [state, setState] = useState3({
+    receipts: /* @__PURE__ */ new Map(),
+    isLoading: stableQueries.length > 0,
+    error: null
+  });
+  useEffect2(() => {
+    let active = true;
+    if (stableQueries.length === 0) {
+      setState({ receipts: /* @__PURE__ */ new Map(), isLoading: false, error: null });
+      return () => {
+        active = false;
+      };
+    }
+    setState((current) => ({ ...current, isLoading: true, error: null }));
+    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;
+      setState({
+        receipts: /* @__PURE__ */ new Map(),
+        isLoading: false,
+        error: cause instanceof Error ? cause : new Error(String(cause))
+      });
+    });
+    return () => {
+      active = false;
+    };
+  }, [stableQueries, store]);
+  return state;
+}
 
 // src/renderer.tsx
 import {
@@ -2417,11 +2615,11 @@ import {
 } from "@form-engine-ts/core";
 import {
   Fragment as Fragment2,
-  useEffect as useEffect2,
+  useEffect as useEffect3,
   useId,
-  useMemo as useMemo3,
+  useMemo as useMemo4,
   useRef as useRef2,
-  useState as useState3
+  useState as useState4
 } from "react";
 import { Fragment as Fragment3, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
 function describedBy(field, error, helpId, errorId) {
@@ -2647,31 +2845,34 @@ function ContextFormRenderer({
   onDraftSave,
   submissionGuards = [],
   receiptStore,
+  attemptStore,
+  onReceiptError,
   slots = {}
 }) {
   const form = useForm();
   const prefix = useId().replace(/:/g, "");
   const formRef = useRef2(null);
   const loadedDraftKey = useRef2(null);
-  const [draftRestored, setDraftRestored] = useState3(false);
-  const [currentPageIndex, setCurrentPageIndex] = useState3(0);
-  const [focusFieldId, setFocusFieldId] = useState3(null);
-  const [confirmation, setConfirmation] = useState3(null);
-  const [guardMessage, setGuardMessage] = useState3(null);
-  const [receipt, setReceipt] = useState3(null);
-  const [receiptLoaded, setReceiptLoaded] = useState3(receiptStore === void 0);
+  const [draftRestored, setDraftRestored] = useState4(false);
+  const [currentPageIndex, setCurrentPageIndex] = useState4(0);
+  const [focusFieldId, setFocusFieldId] = useState4(null);
+  const [confirmation, setConfirmation] = useState4(null);
+  const [guardMessage, setGuardMessage] = useState4(null);
+  const [receipt, setReceipt] = useState4(null);
+  const [receiptLoaded, setReceiptLoaded] = useState4(receiptStore === void 0);
   const rendererSubmissionInFlight = useRef2(false);
   const pages = form.schema.pages;
-  const visiblePageIndexes = useMemo3(
+  const visiblePageIndexes = useMemo4(
     () => pages === void 0 ? [] : pages.flatMap((page, index) => form.pageVisibility[page.id] === true ? [index] : []),
     [form.pageVisibility, pages]
   );
   const activePage = pages?.[currentPageIndex];
   const activeVisibleIndex = visiblePageIndexes.indexOf(currentPageIndex);
   const fieldIds = activePage === void 0 ? void 0 : new Set(activePage.questionIds);
+  const visibleValues = useMemo4(() => selectVisibleAnswers2(form.schema, form.values), [form.schema, form.values]);
   const submitState = confirmation === null ? form.submitStatus : "confirming";
   const interactionLocked = submitState === "confirming" || submitState === "submitting";
-  useEffect2(() => {
+  useEffect3(() => {
     let active = true;
     if (receiptStore === void 0) {
       setReceipt(null);
@@ -2692,14 +2893,14 @@ function ContextFormRenderer({
       active = false;
     };
   }, [form.schema.id, form.schema.version, receiptStore]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (pages === void 0 || visiblePageIndexes.length === 0) {
       setCurrentPageIndex(0);
       return;
     }
     if (!visiblePageIndexes.includes(currentPageIndex)) setCurrentPageIndex(visiblePageIndexes[0] ?? 0);
   }, [currentPageIndex, pages, visiblePageIndexes]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (focusFieldId === null) return;
     const fieldContainer = [...formRef.current?.querySelectorAll("[data-field-id]") ?? []].find(
       (element) => element.dataset.fieldId === focusFieldId
@@ -2710,7 +2911,7 @@ function ContextFormRenderer({
       setFocusFieldId(null);
     }
   }, [focusFieldId]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
     const loadIdentity = `${autoSaveKey}:${form.schema.id}:${form.schema.version}`;
     if (loadedDraftKey.current === loadIdentity) return;
@@ -2722,7 +2923,7 @@ function ContextFormRenderer({
     form.restoreValues(draft.values);
     setDraftRestored(true);
   }, [autoSaveKey, form.restoreValues, form.schema.id, form.schema.version]);
-  useEffect2(() => {
+  useEffect3(() => {
     if (form.submitStatus === "success") return;
     const timeout = globalThis.setTimeout(() => {
       onDraftSave?.(form.values);
@@ -2755,7 +2956,7 @@ function ContextFormRenderer({
     let confirmationMessage;
     let requiresConfirmation = false;
     for (const guard of guards) {
-      const result = await guard(form.schema, selectVisibleAnswers2(form.schema, form.values));
+      const result = await guard(form.schema, visibleValues);
       if (result.status === "allow") continue;
       findings.push(...result.findings);
       if (result.status === "block") {
@@ -2785,7 +2986,7 @@ function ContextFormRenderer({
       try {
         const guardResult = await runSubmissionGuards(submissionGuards);
         if (guardResult.status === "block") {
-          setGuardMessage(guardResult.message ?? "Submission blocked because sensitive data was detected.");
+          setGuardMessage(guardResult.message ?? form.translate("form.submissionBlocked"));
           return { status: "cancelled" };
         }
         if (guardResult.status === "confirm") {
@@ -2803,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)
@@ -2814,13 +3026,30 @@ 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: (/* @__PURE__ */ new Date()).toISOString()
+          submittedAt: response?.submittedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+          ...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);
@@ -2860,8 +3089,8 @@ function ContextFormRenderer({
       receipt,
       ...receiptStore === void 0 ? {} : { onReset: () => void resetReceipt() }
     }) ?? /* @__PURE__ */ jsxs2("div", { role: "status", children: [
-      "Already submitted.",
-      receiptStore === void 0 ? null : /* @__PURE__ */ jsx3("button", { type: "button", onClick: () => void resetReceipt(), children: "Submit another response" })
+      form.translate("form.alreadySubmitted"),
+      receiptStore === void 0 ? null : /* @__PURE__ */ jsx3("button", { type: "button", onClick: () => void resetReceipt(), children: form.translate("form.submitAnother") })
     ] }) });
   }
   return /* @__PURE__ */ jsxs2("form", { ref: formRef, className: `fe-form ${className}`.trim(), noValidate: true, onSubmit: handleSubmit, children: [
@@ -2930,12 +3159,15 @@ function ContextFormRenderer({
     guardMessage === null ? null : /* @__PURE__ */ jsx3("div", { role: "alert", children: guardMessage }),
     confirmation === null ? null : slots.renderSubmissionConfirmation?.({
       findings: confirmation.findings,
+      message: confirmation.message ?? form.translate("form.confirmSensitiveData"),
+      schema: form.schema,
+      visibleValues,
       onConfirm: confirmSubmission,
       onCancel: cancelSubmission
     }) ?? /* @__PURE__ */ jsxs2("div", { className: "fe-submission-confirmation", role: "dialog", "aria-modal": "true", children: [
-      /* @__PURE__ */ jsx3("p", { children: confirmation.message ?? "Sensitive data may be included. Confirm before submitting." }),
-      /* @__PURE__ */ jsx3("button", { type: "button", onClick: confirmSubmission, children: "Confirm submission" }),
-      /* @__PURE__ */ jsx3("button", { type: "button", onClick: cancelSubmission, children: "Cancel" })
+      /* @__PURE__ */ jsx3("p", { children: confirmation.message ?? form.translate("form.confirmSensitiveData") }),
+      /* @__PURE__ */ jsx3("button", { type: "button", onClick: confirmSubmission, children: form.translate("form.confirmSubmission") }),
+      /* @__PURE__ */ jsx3("button", { type: "button", onClick: cancelSubmission, children: form.translate("form.cancelSubmission") })
     ] }),
     validationIssues.length === 0 ? null : slots.renderValidationSummary?.({ issues: validationIssues }) ?? /* @__PURE__ */ jsxs2("div", { className: "fe-validation-summary", role: "alert", children: [
       validationIssues.length,
@@ -2992,6 +3224,12 @@ var RENDERER_MESSAGES = {
   "form.next": "Next",
   "form.step": "Step {{current}} / {{total}}",
   "form.draftRestored": "Draft restored",
+  "form.submissionBlocked": "Submission blocked because sensitive data was detected.",
+  "form.confirmSensitiveData": "Sensitive data may be included. Confirm before submitting.",
+  "form.confirmSubmission": "Confirm submission",
+  "form.cancelSubmission": "Cancel",
+  "form.alreadySubmitted": "Already submitted.",
+  "form.submitAnother": "Submit another response",
   "validation.required": "This field is required."
 };
 var defaultRendererTranslator = {
@@ -3030,9 +3268,12 @@ export {
   FormBuilder,
   FormProvider,
   FormRenderer,
+  createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
   resolveInitialFieldType,
+  submissionReceiptQueryKey,
   useField,
   useForm,
-  useFormBuilder
+  useFormBuilder,
+  useSubmissionReceipts
 };

package/package.json

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