@form-engine-ts/react 2.9.4 → 2.9.5

package/README.md

@@ -81,6 +81,11 @@ relevant feature state, while localization slots receive policy and translation-
 editors remain unchanged. A slot collection can set `sectionOrder` to arrange `basicSettings`, `completionMessage`,
 `questions`, `addQuestion`, and `localization` as independent authoring sections.
 
+Slot actions include `setManualTranslation(locale, target, property, text)`. It resolves the target's source text and
+existing translation metadata, invokes `createManualTranslationMetadata`, and then stores the translated text and
+generated metadata together. Custom field, page, option, and localization slots should use this action for user-edited
+translations; `setLocaleTranslation` remains available for callers that already provide explicit metadata.
+
 Input primitives receive design-system-friendly `name`, `label`, `required`, `error`, and `helperText` props in addition
 to their normalized string-value callbacks. The `translationActions` slot also receives `translationError`, the latest
 `translationReport`, and `onClearTranslationError`, allowing a custom MUI action surface to represent the complete
@@ -114,8 +119,8 @@ own labels. Builder action icons can be supplied with `renderIcon`, which resolv
     renderHeader: ({ title }) => <MyHeader>{title}</MyHeader>,
     renderPageHeader: ({ page }) => <MyPageHeader page={page} />,
     renderField: (props) => <MyField {...props} />,
-    renderSubmitButton: ({ isSubmitting, onSubmit }) => (
-      <MyButton disabled={isSubmitting} onClick={onSubmit}>Save</MyButton>
+    renderSubmitButton: ({ isSubmitting, disabled, onSubmit }) => (
+      <MyButton loading={isSubmitting} disabled={disabled} onClick={onSubmit}>Save</MyButton>
     ),
     renderSubmitError: ({ error, onRetry }) => <MyError error={error} onRetry={onRetry} />
   }}
@@ -124,7 +129,11 @@ own labels. Builder action icons can be supplied with `renderIcon`, which resolv
 
 Validation runs before `beforeSubmit`. A `"cancel"` result does not call `onSubmit` and preserves values and drafts.
 Header, page-header, field, navigation, submit, validation-summary, completion, and submit-error slots can replace the
-default UI. The localized `completionMessage` is displayed after a successful submission.
+default UI. The localized `completionMessage` is displayed after a successful submission. Set
+`successRenderMode="replace"` to remove the questions, navigation, and submit button after success and focus the
+completion status region; the default `"append"` mode preserves the existing form UI. `hideFormOnSuccess` is retained
+as a deprecated alias for `successRenderMode="replace"`. The submit-button slot receives `submitStatus` and `disabled`
+in addition to `isSubmitting` and `onSubmit`.
 
 Pass ordered `submissionGuards` to allow, block, or require confirmation before `onSubmit`. Confirmation receives all
 guard findings through `renderSubmissionConfirmation`. A `receiptStore` prevents accidental repeat submissions and can

package/dist/index.cjs

@@ -1088,7 +1088,7 @@ function BuilderButton(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-button", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1103,7 +1103,7 @@ function BuilderIconButton(props) {
       icon,
       className: primitiveClassName(props.className, "feb-icon-button", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1116,7 +1116,7 @@ function BuilderTextInput(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-input", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1129,7 +1129,7 @@ function BuilderTextArea(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-textarea", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1142,7 +1142,7 @@ function BuilderSelect(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-select", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1155,7 +1155,7 @@ function BuilderCheckbox(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-checkbox", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1301,6 +1301,59 @@ function fieldTypeKey(type) {
 function operatorKey(operator) {
   return `builder.operator.${operator}`;
 }
+function manualTranslationContext(schema, locale, target, property, translatedText) {
+  if (target.kind === "form") {
+    if (property !== "title" && property !== "description" && property !== "completionMessage") return void 0;
+    return {
+      locale,
+      kind: "form",
+      nodeId: schema.id,
+      property,
+      sourceText: schema[property] ?? "",
+      translatedText,
+      ...schema.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: schema.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (target.id === void 0) return void 0;
+  if (target.kind === "field") {
+    const field = schema.fields.find((candidate) => candidate.id === target.id);
+    if (field === void 0 || property !== "title" && property !== "description") return void 0;
+    return {
+      locale,
+      kind: "field",
+      nodeId: field.id,
+      property,
+      sourceText: field[property] ?? "",
+      translatedText,
+      ...field.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: field.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (target.kind === "page") {
+    const page = schema.pages?.find((candidate) => candidate.id === target.id);
+    if (page === void 0 || property !== "title" && property !== "description") return void 0;
+    return {
+      locale,
+      kind: "page",
+      nodeId: page.id,
+      property,
+      sourceText: page[property] ?? "",
+      translatedText,
+      ...page.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: page.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (property !== "label") return void 0;
+  const option = schema.fields.filter((field) => "options" in field).flatMap((field) => field.options).find((candidate) => candidate.id === target.id);
+  if (option === void 0) return void 0;
+  return {
+    locale,
+    kind: "option",
+    nodeId: option.id,
+    property,
+    sourceText: option.label,
+    translatedText,
+    ...option.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: option.translationMetadata[locale]?.[property] }
+  };
+}
 function defaultConditionValue(field) {
   if (field.type === "checkbox") return true;
   if (field.type === "number" || field.type === "rating") return field.min ?? 1;
@@ -1559,25 +1612,30 @@ function FormBuilder({
       setIsTranslating(false);
     }
   };
-  const updateManualTranslation = (context) => {
-    if (readOnly) return;
-    const metadata = createManualTranslationMetadata?.(context);
-    const target = context.kind === "form" ? { kind: "form" } : { kind: context.kind, id: context.nodeId };
-    executeAction(
+  const setManualTranslation = (targetLocale, target, property, text) => {
+    if (readOnly) return { success: true };
+    const normalizedLocale = targetLocale.trim();
+    const context = manualTranslationContext(schema, normalizedLocale, target, property, text);
+    const metadata = context === void 0 ? void 0 : createManualTranslationMetadata?.(context);
+    return executeAction(
       () => headless.setLocaleTranslation(
-        context.locale,
+        normalizedLocale,
         target,
-        context.property,
-        context.translatedText,
+        property,
+        text,
         metadata === void 0 ? void 0 : { metadata }
       ),
       {
-        action: "setLocaleTranslation",
-        targetId: context.nodeId,
-        params: { locale: context.locale, kind: context.kind, property: context.property }
+        action: "setManualTranslation",
+        ...target.id === void 0 ? {} : { targetId: target.id },
+        params: { locale: normalizedLocale, kind: target.kind, property }
       }
     );
   };
+  const updateManualTranslation = (context) => {
+    const target = context.kind === "form" ? { kind: "form" } : { kind: context.kind, id: context.nodeId };
+    setManualTranslation(context.locale, target, context.property, context.translatedText);
+  };
   const updateFormTranslation = (property, translatedText) => {
     if (editingLocale.length === 0) return;
     updateManualTranslation({
@@ -1686,6 +1744,7 @@ function FormBuilder({
       ...target.id === void 0 ? {} : { targetId: target.id },
       params: { locale: targetLocale, property }
     }),
+    setManualTranslation,
     addLocale: (targetLocale) => executeAction(() => headless.addLocale(targetLocale), {
       action: "addLocale",
       params: { locale: targetLocale }
@@ -3063,6 +3122,8 @@ function ContextFormRenderer({
   autoSaveKey,
   beforeSubmit,
   onDraftSave,
+  successRenderMode = "append",
+  hideFormOnSuccess = false,
   submissionGuards = [],
   receiptStore,
   attemptStore,
@@ -3078,9 +3139,11 @@ function ContextFormRenderer({
   const [focusFieldId, setFocusFieldId] = (0, import_react5.useState)(null);
   const [confirmation, setConfirmation] = (0, import_react5.useState)(null);
   const [guardMessage, setGuardMessage] = (0, import_react5.useState)(null);
+  const [guardsPending, setGuardsPending] = (0, import_react5.useState)(false);
   const [receipt, setReceipt] = (0, import_react5.useState)(null);
   const [receiptLoaded, setReceiptLoaded] = (0, import_react5.useState)(receiptStore === void 0);
   const rendererSubmissionInFlight = (0, import_react5.useRef)(false);
+  const completionRef = (0, import_react5.useRef)(null);
   const pages = form.schema.pages;
   const visiblePageIndexes = (0, import_react5.useMemo)(
     () => pages === void 0 ? [] : pages.flatMap((page, index) => form.pageVisibility[page.id] === true ? [index] : []),
@@ -3090,8 +3153,9 @@ function ContextFormRenderer({
   const activeVisibleIndex = visiblePageIndexes.indexOf(currentPageIndex);
   const fieldIds = activePage === void 0 ? void 0 : new Set(activePage.questionIds);
   const visibleValues = (0, import_react5.useMemo)(() => (0, import_core4.selectVisibleAnswers)(form.schema, form.values), [form.schema, form.values]);
-  const submitState = confirmation === null ? form.submitStatus : "confirming";
+  const submitState = confirmation === null && !guardsPending ? form.submitStatus : "confirming";
   const interactionLocked = submitState === "confirming" || submitState === "submitting";
+  const isReplaceMode = successRenderMode === "replace" || hideFormOnSuccess;
   (0, import_react5.useEffect)(() => {
     let active = true;
     if (receiptStore === void 0) {
@@ -3131,6 +3195,10 @@ function ContextFormRenderer({
       setFocusFieldId(null);
     }
   }, [focusFieldId]);
+  (0, import_react5.useEffect)(() => {
+    if (!isReplaceMode || form.submitStatus !== "success") return;
+    completionRef.current?.focus();
+  }, [form.submitStatus, isReplaceMode]);
   (0, import_react5.useEffect)(() => {
     if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
     const loadIdentity = `${autoSaveKey}:${form.schema.id}:${form.schema.version}`;
@@ -3196,13 +3264,14 @@ function ContextFormRenderer({
     };
   };
   const submitValues = async (guardsConfirmed = false) => {
-    if (rendererSubmissionInFlight.current || confirmation !== null && !guardsConfirmed) {
+    if (rendererSubmissionInFlight.current || submitState === "submitting" || submitState === "success" || confirmation !== null && !guardsConfirmed) {
       return { status: "cancelled" };
     }
     const validation = (0, import_core4.validateAnswers)(form.schema, form.values);
     const firstInvalidFieldId = validation.issues[0]?.fieldId;
     if (validation.valid && !guardsConfirmed && submissionGuards.length > 0) {
       rendererSubmissionInFlight.current = true;
+      setGuardsPending(true);
       try {
         const guardResult = await runSubmissionGuards(submissionGuards);
         if (guardResult.status === "block") {
@@ -3219,6 +3288,7 @@ function ContextFormRenderer({
         }
       } finally {
         rendererSubmissionInFlight.current = false;
+        setGuardsPending(false);
       }
     }
     setGuardMessage(null);
@@ -3256,7 +3326,6 @@ function ContextFormRenderer({
         };
         try {
           await receiptStore.save(storedReceipt);
-          setReceipt(storedReceipt);
         } catch (cause) {
           const error = cause instanceof Error ? cause : new Error(String(cause));
           try {
@@ -3283,7 +3352,7 @@ function ContextFormRenderer({
   };
   const handleSubmit = (event) => {
     event.preventDefault();
-    if (interactionLocked) return;
+    if (submitState === "submitting" || submitState === "confirming" || submitState === "success") return;
     void submitValues();
   };
   const confirmSubmission = () => {
@@ -3302,7 +3371,17 @@ function ContextFormRenderer({
   const validationIssues = Object.values(form.errors).filter((issue) => issue !== void 0);
   const canPrev = pages !== void 0 && activeVisibleIndex > 0;
   const canNext = pages !== void 0 && activeVisibleIndex < visiblePageIndexes.length - 1;
-  const renderSubmitButton = () => slots.renderSubmitButton?.({ isSubmitting: interactionLocked, onSubmit: () => void submitValues() }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "fe-submit", type: "submit", disabled: interactionLocked, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
+  const renderSubmitButton = () => {
+    const submitButtonProps = {
+      isSubmitting: submitState === "submitting",
+      submitStatus: submitState,
+      disabled: interactionLocked || submitState === "success",
+      onSubmit: () => void submitValues()
+    };
+    return slots.renderSubmitButton?.(submitButtonProps) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "fe-submit", type: "submit", disabled: submitButtonProps.disabled, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
+  };
+  const completionMessage = form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey));
+  const completionRegion = /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { ref: completionRef, className: "fe-completion", role: "status", "aria-live": "polite", tabIndex: -1, children: slots.renderCompletion?.({ message: completionMessage }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { children: completionMessage }) });
   if (!receiptLoaded) return null;
   if (receipt !== null) {
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: `fe-form fe-already-submitted ${className}`.trim(), children: slots.renderAlreadySubmitted?.({
@@ -3313,6 +3392,9 @@ function ContextFormRenderer({
       receiptStore === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { type: "button", onClick: () => void resetReceipt(), children: form.translate("form.submitAnother") })
     ] }) });
   }
+  if (form.submitStatus === "success" && isReplaceMode) {
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: `fe-form ${className}`.trim(), children: completionRegion });
+  }
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("form", { ref: formRef, className: `fe-form ${className}`.trim(), noValidate: true, onSubmit: handleSubmit, children: [
     slots.renderHeader?.({
       title: form.schema.title,
@@ -3431,9 +3513,7 @@ function ContextFormRenderer({
       canNext ? null : renderSubmitButton()
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-status", "aria-live": "polite", children: [
-      form.submitStatus === "success" ? slots.renderCompletion?.({
-        message: form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey))
-      }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { role: "status", children: form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey)) }) : null,
+      form.submitStatus === "success" ? completionRegion : null,
       form.submitStatus === "error" && form.submitError !== null ? slots.renderSubmitError?.({ error: form.submitError, onRetry: () => void submitValues() }) ?? (errorMessageKey === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { role: "alert", children: form.translate(errorMessageKey) })) : null
     ] })
   ] });

package/dist/index.d.cts

@@ -229,10 +229,17 @@ interface FormBuilderComponents {
     readonly renderIcon?: (actionType: BuilderActionIconType) => ReactNode;
 }
 type FormBuilderActions = Omit<FormBuilderResult, "schema" | "validationIssues">;
+interface ManualTranslationTarget {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly id?: string;
+}
+interface BuilderSlotActions extends FormBuilderActions {
+    readonly setManualTranslation: (locale: string, target: ManualTranslationTarget, property: "title" | "description" | "label" | "completionMessage", text: string) => BuilderActionResult;
+}
 interface BuilderSlotBaseProps {
     readonly schema: FormSchema;
     readonly readOnly: boolean;
-    readonly actions: FormBuilderActions;
+    readonly actions: BuilderSlotActions;
     readonly components: Required<FormBuilderComponents>;
     readonly translate: (key: string, params?: Record<string, unknown>) => string;
 }
@@ -302,7 +309,7 @@ interface FormBuilderSlots {
     readonly sectionOrder?: readonly FormBuilderSectionName[];
 }
 interface BuilderActionContext {
-    readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "updatePage" | "assignFieldToPage" | "addLocale" | "setDefaultLocale" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation";
+    readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "updatePage" | "assignFieldToPage" | "addLocale" | "setDefaultLocale" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation" | "setManualTranslation";
     readonly targetId?: string;
     readonly params?: Record<string, unknown>;
 }
@@ -344,7 +351,16 @@ type SubmissionGuardResult = {
     readonly message?: string;
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
+type FormSuccessRenderMode = "append" | "replace";
+type FormSubmitStatus = "idle" | "submitting" | "confirming" | "success" | "error";
+/** @deprecated Use FormSubmitStatus instead. */
 type FormSubmitState = "idle" | "submitting" | "confirming" | "success" | "error";
+interface RenderSubmitButtonProps {
+    readonly isSubmitting: boolean;
+    readonly submitStatus: FormSubmitStatus;
+    readonly disabled: boolean;
+    readonly onSubmit: () => void;
+}
 interface SubmissionConfirmationSlotProps {
     readonly findings: readonly SensitiveDataFinding[];
     readonly message?: string;
@@ -377,10 +393,7 @@ interface FormRendererSlots {
         readonly onPrev: () => void;
         readonly onNext: () => void;
     }) => ReactNode;
-    readonly renderSubmitButton?: (props: {
-        readonly isSubmitting: boolean;
-        readonly onSubmit: () => void;
-    }) => ReactNode;
+    readonly renderSubmitButton?: (props: RenderSubmitButtonProps) => ReactNode;
     readonly renderValidationSummary?: (props: {
         readonly issues: readonly ValidationError[];
     }) => ReactNode;
@@ -494,6 +507,13 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    /**
+     * Controls where the completion message is rendered after a successful submission.
+     * Defaults to "append" for backwards compatibility.
+     */
+    readonly successRenderMode?: FormSuccessRenderMode;
+    /** @deprecated Use successRenderMode="replace" instead. */
+    readonly hideFormOnSuccess?: boolean;
     readonly successMessageKey?: string;
     readonly errorMessageKey?: string;
     readonly autoSaveKey?: string;
@@ -512,4 +532,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 BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, 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 FormBuilderSectionName, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type IconButtonProps, 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 };
+export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, 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 BuilderSlotActions, 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 FormBuilderSectionName, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, 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

@@ -229,10 +229,17 @@ interface FormBuilderComponents {
     readonly renderIcon?: (actionType: BuilderActionIconType) => ReactNode;
 }
 type FormBuilderActions = Omit<FormBuilderResult, "schema" | "validationIssues">;
+interface ManualTranslationTarget {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly id?: string;
+}
+interface BuilderSlotActions extends FormBuilderActions {
+    readonly setManualTranslation: (locale: string, target: ManualTranslationTarget, property: "title" | "description" | "label" | "completionMessage", text: string) => BuilderActionResult;
+}
 interface BuilderSlotBaseProps {
     readonly schema: FormSchema;
     readonly readOnly: boolean;
-    readonly actions: FormBuilderActions;
+    readonly actions: BuilderSlotActions;
     readonly components: Required<FormBuilderComponents>;
     readonly translate: (key: string, params?: Record<string, unknown>) => string;
 }
@@ -302,7 +309,7 @@ interface FormBuilderSlots {
     readonly sectionOrder?: readonly FormBuilderSectionName[];
 }
 interface BuilderActionContext {
-    readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "updatePage" | "assignFieldToPage" | "addLocale" | "setDefaultLocale" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation";
+    readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "updatePage" | "assignFieldToPage" | "addLocale" | "setDefaultLocale" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation" | "setManualTranslation";
     readonly targetId?: string;
     readonly params?: Record<string, unknown>;
 }
@@ -344,7 +351,16 @@ type SubmissionGuardResult = {
     readonly message?: string;
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
+type FormSuccessRenderMode = "append" | "replace";
+type FormSubmitStatus = "idle" | "submitting" | "confirming" | "success" | "error";
+/** @deprecated Use FormSubmitStatus instead. */
 type FormSubmitState = "idle" | "submitting" | "confirming" | "success" | "error";
+interface RenderSubmitButtonProps {
+    readonly isSubmitting: boolean;
+    readonly submitStatus: FormSubmitStatus;
+    readonly disabled: boolean;
+    readonly onSubmit: () => void;
+}
 interface SubmissionConfirmationSlotProps {
     readonly findings: readonly SensitiveDataFinding[];
     readonly message?: string;
@@ -377,10 +393,7 @@ interface FormRendererSlots {
         readonly onPrev: () => void;
         readonly onNext: () => void;
     }) => ReactNode;
-    readonly renderSubmitButton?: (props: {
-        readonly isSubmitting: boolean;
-        readonly onSubmit: () => void;
-    }) => ReactNode;
+    readonly renderSubmitButton?: (props: RenderSubmitButtonProps) => ReactNode;
     readonly renderValidationSummary?: (props: {
         readonly issues: readonly ValidationError[];
     }) => ReactNode;
@@ -494,6 +507,13 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    /**
+     * Controls where the completion message is rendered after a successful submission.
+     * Defaults to "append" for backwards compatibility.
+     */
+    readonly successRenderMode?: FormSuccessRenderMode;
+    /** @deprecated Use successRenderMode="replace" instead. */
+    readonly hideFormOnSuccess?: boolean;
     readonly successMessageKey?: string;
     readonly errorMessageKey?: string;
     readonly autoSaveKey?: string;
@@ -512,4 +532,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 BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, 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 FormBuilderSectionName, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type IconButtonProps, 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 };
+export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, 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 BuilderSlotActions, 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 FormBuilderSectionName, type FormBuilderSlots, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, 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

@@ -1058,7 +1058,7 @@ function BuilderButton(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-button", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1073,7 +1073,7 @@ function BuilderIconButton(props) {
       icon,
       className: primitiveClassName(props.className, "feb-icon-button", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1086,7 +1086,7 @@ function BuilderTextInput(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-input", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1099,7 +1099,7 @@ function BuilderTextArea(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-textarea", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1112,7 +1112,7 @@ function BuilderSelect(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-select", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1125,7 +1125,7 @@ function BuilderCheckbox(props) {
       ...props,
       className: primitiveClassName(props.className, "feb-checkbox", context.unstyled),
       disabled: context.readOnly || props.disabled === true,
-      readOnly: context.readOnly
+      readOnly: context.readOnly || props.readOnly === true
     }
   );
 }
@@ -1271,6 +1271,59 @@ function fieldTypeKey(type) {
 function operatorKey(operator) {
   return `builder.operator.${operator}`;
 }
+function manualTranslationContext(schema, locale, target, property, translatedText) {
+  if (target.kind === "form") {
+    if (property !== "title" && property !== "description" && property !== "completionMessage") return void 0;
+    return {
+      locale,
+      kind: "form",
+      nodeId: schema.id,
+      property,
+      sourceText: schema[property] ?? "",
+      translatedText,
+      ...schema.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: schema.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (target.id === void 0) return void 0;
+  if (target.kind === "field") {
+    const field = schema.fields.find((candidate) => candidate.id === target.id);
+    if (field === void 0 || property !== "title" && property !== "description") return void 0;
+    return {
+      locale,
+      kind: "field",
+      nodeId: field.id,
+      property,
+      sourceText: field[property] ?? "",
+      translatedText,
+      ...field.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: field.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (target.kind === "page") {
+    const page = schema.pages?.find((candidate) => candidate.id === target.id);
+    if (page === void 0 || property !== "title" && property !== "description") return void 0;
+    return {
+      locale,
+      kind: "page",
+      nodeId: page.id,
+      property,
+      sourceText: page[property] ?? "",
+      translatedText,
+      ...page.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: page.translationMetadata[locale]?.[property] }
+    };
+  }
+  if (property !== "label") return void 0;
+  const option = schema.fields.filter((field) => "options" in field).flatMap((field) => field.options).find((candidate) => candidate.id === target.id);
+  if (option === void 0) return void 0;
+  return {
+    locale,
+    kind: "option",
+    nodeId: option.id,
+    property,
+    sourceText: option.label,
+    translatedText,
+    ...option.translationMetadata?.[locale]?.[property] === void 0 ? {} : { existingTranslationMetadata: option.translationMetadata[locale]?.[property] }
+  };
+}
 function defaultConditionValue(field) {
   if (field.type === "checkbox") return true;
   if (field.type === "number" || field.type === "rating") return field.min ?? 1;
@@ -1529,25 +1582,30 @@ function FormBuilder({
       setIsTranslating(false);
     }
   };
-  const updateManualTranslation = (context) => {
-    if (readOnly) return;
-    const metadata = createManualTranslationMetadata?.(context);
-    const target = context.kind === "form" ? { kind: "form" } : { kind: context.kind, id: context.nodeId };
-    executeAction(
+  const setManualTranslation = (targetLocale, target, property, text) => {
+    if (readOnly) return { success: true };
+    const normalizedLocale = targetLocale.trim();
+    const context = manualTranslationContext(schema, normalizedLocale, target, property, text);
+    const metadata = context === void 0 ? void 0 : createManualTranslationMetadata?.(context);
+    return executeAction(
       () => headless.setLocaleTranslation(
-        context.locale,
+        normalizedLocale,
         target,
-        context.property,
-        context.translatedText,
+        property,
+        text,
         metadata === void 0 ? void 0 : { metadata }
       ),
       {
-        action: "setLocaleTranslation",
-        targetId: context.nodeId,
-        params: { locale: context.locale, kind: context.kind, property: context.property }
+        action: "setManualTranslation",
+        ...target.id === void 0 ? {} : { targetId: target.id },
+        params: { locale: normalizedLocale, kind: target.kind, property }
       }
     );
   };
+  const updateManualTranslation = (context) => {
+    const target = context.kind === "form" ? { kind: "form" } : { kind: context.kind, id: context.nodeId };
+    setManualTranslation(context.locale, target, context.property, context.translatedText);
+  };
   const updateFormTranslation = (property, translatedText) => {
     if (editingLocale.length === 0) return;
     updateManualTranslation({
@@ -1656,6 +1714,7 @@ function FormBuilder({
       ...target.id === void 0 ? {} : { targetId: target.id },
       params: { locale: targetLocale, property }
     }),
+    setManualTranslation,
     addLocale: (targetLocale) => executeAction(() => headless.addLocale(targetLocale), {
       action: "addLocale",
       params: { locale: targetLocale }
@@ -3051,6 +3110,8 @@ function ContextFormRenderer({
   autoSaveKey,
   beforeSubmit,
   onDraftSave,
+  successRenderMode = "append",
+  hideFormOnSuccess = false,
   submissionGuards = [],
   receiptStore,
   attemptStore,
@@ -3066,9 +3127,11 @@ function ContextFormRenderer({
   const [focusFieldId, setFocusFieldId] = useState4(null);
   const [confirmation, setConfirmation] = useState4(null);
   const [guardMessage, setGuardMessage] = useState4(null);
+  const [guardsPending, setGuardsPending] = useState4(false);
   const [receipt, setReceipt] = useState4(null);
   const [receiptLoaded, setReceiptLoaded] = useState4(receiptStore === void 0);
   const rendererSubmissionInFlight = useRef2(false);
+  const completionRef = useRef2(null);
   const pages = form.schema.pages;
   const visiblePageIndexes = useMemo4(
     () => pages === void 0 ? [] : pages.flatMap((page, index) => form.pageVisibility[page.id] === true ? [index] : []),
@@ -3078,8 +3141,9 @@ function ContextFormRenderer({
   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 submitState = confirmation === null && !guardsPending ? form.submitStatus : "confirming";
   const interactionLocked = submitState === "confirming" || submitState === "submitting";
+  const isReplaceMode = successRenderMode === "replace" || hideFormOnSuccess;
   useEffect3(() => {
     let active = true;
     if (receiptStore === void 0) {
@@ -3119,6 +3183,10 @@ function ContextFormRenderer({
       setFocusFieldId(null);
     }
   }, [focusFieldId]);
+  useEffect3(() => {
+    if (!isReplaceMode || form.submitStatus !== "success") return;
+    completionRef.current?.focus();
+  }, [form.submitStatus, isReplaceMode]);
   useEffect3(() => {
     if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
     const loadIdentity = `${autoSaveKey}:${form.schema.id}:${form.schema.version}`;
@@ -3184,13 +3252,14 @@ function ContextFormRenderer({
     };
   };
   const submitValues = async (guardsConfirmed = false) => {
-    if (rendererSubmissionInFlight.current || confirmation !== null && !guardsConfirmed) {
+    if (rendererSubmissionInFlight.current || submitState === "submitting" || submitState === "success" || confirmation !== null && !guardsConfirmed) {
       return { status: "cancelled" };
     }
     const validation = validateAnswers2(form.schema, form.values);
     const firstInvalidFieldId = validation.issues[0]?.fieldId;
     if (validation.valid && !guardsConfirmed && submissionGuards.length > 0) {
       rendererSubmissionInFlight.current = true;
+      setGuardsPending(true);
       try {
         const guardResult = await runSubmissionGuards(submissionGuards);
         if (guardResult.status === "block") {
@@ -3207,6 +3276,7 @@ function ContextFormRenderer({
         }
       } finally {
         rendererSubmissionInFlight.current = false;
+        setGuardsPending(false);
       }
     }
     setGuardMessage(null);
@@ -3244,7 +3314,6 @@ function ContextFormRenderer({
         };
         try {
           await receiptStore.save(storedReceipt);
-          setReceipt(storedReceipt);
         } catch (cause) {
           const error = cause instanceof Error ? cause : new Error(String(cause));
           try {
@@ -3271,7 +3340,7 @@ function ContextFormRenderer({
   };
   const handleSubmit = (event) => {
     event.preventDefault();
-    if (interactionLocked) return;
+    if (submitState === "submitting" || submitState === "confirming" || submitState === "success") return;
     void submitValues();
   };
   const confirmSubmission = () => {
@@ -3290,7 +3359,17 @@ function ContextFormRenderer({
   const validationIssues = Object.values(form.errors).filter((issue) => issue !== void 0);
   const canPrev = pages !== void 0 && activeVisibleIndex > 0;
   const canNext = pages !== void 0 && activeVisibleIndex < visiblePageIndexes.length - 1;
-  const renderSubmitButton = () => slots.renderSubmitButton?.({ isSubmitting: interactionLocked, onSubmit: () => void submitValues() }) ?? /* @__PURE__ */ jsx3("button", { className: "fe-submit", type: "submit", disabled: interactionLocked, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
+  const renderSubmitButton = () => {
+    const submitButtonProps = {
+      isSubmitting: submitState === "submitting",
+      submitStatus: submitState,
+      disabled: interactionLocked || submitState === "success",
+      onSubmit: () => void submitValues()
+    };
+    return slots.renderSubmitButton?.(submitButtonProps) ?? /* @__PURE__ */ jsx3("button", { className: "fe-submit", type: "submit", disabled: submitButtonProps.disabled, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
+  };
+  const completionMessage = form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey));
+  const completionRegion = /* @__PURE__ */ jsx3("div", { ref: completionRef, className: "fe-completion", role: "status", "aria-live": "polite", tabIndex: -1, children: slots.renderCompletion?.({ message: completionMessage }) ?? /* @__PURE__ */ jsx3("div", { children: completionMessage }) });
   if (!receiptLoaded) return null;
   if (receipt !== null) {
     return /* @__PURE__ */ jsx3("div", { className: `fe-form fe-already-submitted ${className}`.trim(), children: slots.renderAlreadySubmitted?.({
@@ -3301,6 +3380,9 @@ function ContextFormRenderer({
       receiptStore === void 0 ? null : /* @__PURE__ */ jsx3("button", { type: "button", onClick: () => void resetReceipt(), children: form.translate("form.submitAnother") })
     ] }) });
   }
+  if (form.submitStatus === "success" && isReplaceMode) {
+    return /* @__PURE__ */ jsx3("div", { className: `fe-form ${className}`.trim(), children: completionRegion });
+  }
   return /* @__PURE__ */ jsxs2("form", { ref: formRef, className: `fe-form ${className}`.trim(), noValidate: true, onSubmit: handleSubmit, children: [
     slots.renderHeader?.({
       title: form.schema.title,
@@ -3419,9 +3501,7 @@ function ContextFormRenderer({
       canNext ? null : renderSubmitButton()
     ] }),
     /* @__PURE__ */ jsxs2("div", { className: "fe-status", "aria-live": "polite", children: [
-      form.submitStatus === "success" ? slots.renderCompletion?.({
-        message: form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey))
-      }) ?? /* @__PURE__ */ jsx3("div", { role: "status", children: form.schema.completionMessage ?? (successMessageKey === void 0 ? "Submitted." : form.translate(successMessageKey)) }) : null,
+      form.submitStatus === "success" ? completionRegion : null,
       form.submitStatus === "error" && form.submitError !== null ? slots.renderSubmitError?.({ error: form.submitError, onRetry: () => void submitValues() }) ?? (errorMessageKey === void 0 ? null : /* @__PURE__ */ jsx3("div", { role: "alert", children: form.translate(errorMessageKey) })) : null
     ] })
   ] });

package/package.json

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