@10x-media/form-builder 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/react/Form.d.ts

@@ -1,4 +1,5 @@
 import { AnyFormFieldDefinition } from "../fields/types.js";
+import { BodyConverter } from "../actions/body/converters.js";
 import { FormButtonSettings, FormDocument, FormPollSettings, FormResponseSettings } from "../form/types.js";
 import { RendererTranslate } from "./contract.js";
 import { FormEventSink } from "../events/types.js";
@@ -11,6 +12,21 @@ import { SubmitHandler } from "./submitForm.js";
 import { ReactNode } from "react";
 
 //#region src/react/Form.d.ts
+/**
+ * The success response passed to `onSuccess`, recall-resolved and (for a message) serialized with the
+ * form's active converters, so a host can render or toast the resolved response without re-deriving it.
+ */
+type FormSuccessResponse = {
+  type: 'message';
+  html?: string;
+} | {
+  type: 'redirect';
+  url?: string;
+};
+/** The second argument to `onSuccess`: the resolved success response (an object, so it can grow). */
+type FormSuccessResult = {
+  response?: FormSuccessResponse;
+};
 type FormProps = {
   form: FormDocument;
   fieldTypes?: AnyFormFieldDefinition[];
@@ -18,8 +34,24 @@ type FormProps = {
   renderers?: RenderersConfig;
   apiRoute?: string;
   onSubmit?: SubmitHandler;
-  onSuccess?: (submissionId?: string) => void;
+  /**
+   * Called after a successful submission with the submission id and the resolved success response
+   * (recall-applied, serialized with `converters`), so a host can toast or render it. Fires in both
+   * `successBehavior` modes and on the custom-`children` path.
+   */
+  onSuccess?: (submissionId?: string, result?: FormSuccessResult) => void;
   onError?: (message: string) => void;
+  /**
+   * Custom Lexical block converters (e.g. host `icon`/`badge` blocks) spread over the defaults for the
+   * client serializer, so those blocks survive in the success message and in the `onSuccess` response.
+   */
+  converters?: Record<string, BodyConverter>;
+  /**
+   * What happens on a successful submit. `'replace'` (default) swaps the form for the success screen;
+   * `'reset'` clears the fields in place and shows no success screen, so a host can toast via `onSuccess`
+   * and keep the form usable.
+   */
+  successBehavior?: 'replace' | 'reset';
   events?: FormEventSink;
   t?: RendererTranslate;
   locale?: string;
@@ -43,7 +75,8 @@ type FormProps = {
     name?: string;
   }; /** A token from your captcha widget; verified server-side when a captcha provider is configured. */
   captchaToken?: string; /** Custom layout: render fields with `useField`/`useFormState` instead of the auto-rendered field loop. */
-  children?: ReactNode; /** Additional CSS class names applied to the root `<form>` element (and the success node). */
+  children?: ReactNode; /** Chrome rendered inside the form, above the fields, in default mode (e.g. `<FormSteps />`). */
+  header?: ReactNode; /** Additional CSS class names applied to the root `<form>` element (and the success node). */
   className?: string; /** Replace the default submit button entirely. Receives the resolved label and submitting state. */
   renderSubmit?: (props: SubmitButtonRenderProps) => ReactNode; /** Replace the default "Next" button in multi-step forms. */
   renderNext?: (props: NextButtonRenderProps) => ReactNode; /** Replace the default "Back" button in multi-step forms. */
@@ -62,6 +95,8 @@ declare const Form: ({
   onSubmit,
   onSuccess,
   onError,
+  converters,
+  successBehavior,
   events,
   t,
   locale,
@@ -79,6 +114,7 @@ declare const Form: ({
   honeypot,
   captchaToken,
   children,
+  header,
   className,
   renderSubmit,
   renderNext,
@@ -88,5 +124,5 @@ declare const Form: ({
   backButtonClassName
 }: FormProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
-export { Form, FormProps };
+export { Form, FormProps, FormSuccessResponse, FormSuccessResult };
 //# sourceMappingURL=Form.d.ts.map

package/dist/react/Form.js

@@ -1,9 +1,9 @@
 "use client";
-import { interpolate } from "../recall/interpolate.js";
 import { keys } from "../translations/keys.js";
+import { interpolate } from "../recall/interpolate.js";
 import { serializeBody } from "../actions/body/serializeBody.js";
 import { noopEventSink } from "../events/noopSink.js";
-import { CAPTCHA_TOKEN_KEY } from "../spam/constants.js";
+import { CAPTCHA_TOKEN_KEY, HONEYPOT_VALUE_KEY } from "../spam/constants.js";
 import { fieldKey, isNamedField } from "../fields/fieldKey.js";
 import { calcExpressionOf, computeCalcFields } from "../calc/computeCalcFields.js";
 import { evaluateCondition } from "../conditions/evaluate.js";
@@ -16,82 +16,24 @@ import { makeTranslate } from "../translations/makeTranslate.js";
 import { emitFormEvent } from "./events.js";
 import { FormContext } from "./FormContext.js";
 import { FormControls } from "./FormControls.js";
-import { FormLayout, widthProps } from "./FormLayout.js";
+import { FormFields } from "./FormFields.js";
 import { Honeypot } from "./Honeypot.js";
 import { defaultPresentations } from "./presentation/presentations.js";
 import { resolvePresentations } from "./presentation/registry.js";
-import { applyRecall } from "./recall.js";
 import { resolveRenderers } from "./registry.js";
-import { useField } from "./useField.js";
 import { defaultRenderers } from "./renderers/index.js";
 import { buildFieldTypeRegistry, buildValidationRuleRegistry, visibleFields } from "./resolveForm.js";
 import { formReducer, initialFormState, seedFieldValues } from "./state.js";
 import { submitForm } from "./submitForm.js";
 import { validateFieldValue } from "./validateField.js";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { createElement, useCallback, useEffect, useId, useMemo, useReducer, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 //#region src/react/Form.tsx
 const isEmpty = (value) => value == null || value === "" || Array.isArray(value) && value.length === 0;
 /** A stored button label counts only when it is a non-empty string; anything else falls through. */
 const storedLabel = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
-const FIELD_WIDTHS = new Set([
-	"full",
-	"half",
-	"third",
-	"twoThirds"
-]);
-const FieldHost = ({ field, renderer, locale, t }) => {
-	const id = useId();
-	const { value, errors, setValue, onBlur } = useField(field.name);
-	return createElement(renderer, {
-		field,
-		id,
-		name: field.name,
-		value,
-		onChange: setValue,
-		onBlur,
-		errors,
-		required: Boolean(field.required),
-		locale,
-		t
-	});
-};
-/** Hosts a derived (calc) field: read-only, value supplied from `effectiveValues`, never bound via `useField`. */
-const CalcFieldHost = ({ field, renderer, value, locale, t }) => {
-	return createElement(renderer, {
-		field,
-		id: useId(),
-		name: field.name,
-		value,
-		onChange: () => {},
-		onBlur: () => {},
-		errors: [],
-		required: false,
-		disabled: true,
-		locale,
-		t
-	});
-};
-/**
-* Hosts a nameless (bare) display block, e.g. a message: no `useField` binding at all. The
-* renderer reads only the instance and the form context; `name` is the row key for consistency.
-*/
-const StaticFieldHost = ({ field, renderer, locale, t }) => {
-	return createElement(renderer, {
-		field,
-		id: useId(),
-		name: fieldKey(field),
-		value: void 0,
-		onChange: () => {},
-		onBlur: () => {},
-		errors: [],
-		required: false,
-		locale,
-		t
-	});
-};
 /** The headless form controller: state, progressive client validation, conditional visibility, submission, events. */
-const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSuccess, onError, events, t, locale = "en", layout, submitLabel, nextLabel, prevLabel, closeLabel = "Close", successMessage = "Thank you.", presentation, presentations, onClose, title, initialValues, honeypot, captchaToken, children, className, renderSubmit, renderNext, renderBack, submitButtonClassName, nextButtonClassName, backButtonClassName }) => {
+const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSuccess, onError, converters, successBehavior = "replace", events, t, locale = "en", layout, submitLabel, nextLabel, prevLabel, closeLabel, successMessage, presentation, presentations, onClose, title, initialValues, honeypot, captchaToken, children, header, className, renderSubmit, renderNext, renderBack, submitButtonClassName, nextButtonClassName, backButtonClassName }) => {
 	const honeypotName = honeypot === false ? null : honeypot?.name ?? "website";
 	const honeypotRef = useRef(null);
 	const registry = useMemo(() => buildFieldTypeRegistry(fieldTypes), [fieldTypes]);
@@ -101,6 +43,8 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 	const activePresentation = typeof presentation === "object" ? presentation : presentationRegistry.get(presentation ?? "page") ?? presentationRegistry.get("page") ?? defaultPresentationDescriptors.page;
 	const fieldsByName = useMemo(() => new Map(form.fields.filter(isNamedField).map((field) => [field.name, field])), [form.fields]);
 	const translate = useMemo(() => t ?? makeTranslate(en), [t]);
+	const resolvedCloseLabel = closeLabel ?? translate(keys.formClose);
+	const resolvedSuccessMessage = successMessage ?? translate(keys.formSuccess);
 	const docButtons = form.buttons;
 	const labels = useMemo(() => ({
 		prev: prevLabel ?? storedLabel(docButtons?.prevLabel) ?? translate(keys.formBack),
@@ -141,6 +85,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 	const startedRef = useRef(false);
 	const submittedRef = useRef(false);
 	const submittingRef = useRef(false);
+	const advancingRef = useRef(false);
 	const flowRef = useRef(flow);
 	flowRef.current = flow;
 	const dispatch = useCallback((action) => {
@@ -210,47 +155,111 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		field: field.name,
 		value: recall(field.name)
 	}));
-	const stepVisible = (flow && currentStepId ? stepFieldNames(flow, currentStepId) : []).map((key) => visible.find((field) => fieldKey(field) === key)).filter((field) => Boolean(field));
+	/**
+	* The recall-resolved success response: a redirect's url, or the response message serialized with
+	* the active `converters` (so host blocks survive). Shared by the success screen and the value
+	* handed to `onSuccess`, so both stay identical.
+	*/
+	const resolveSuccessResponse = () => {
+		const response = form.response;
+		if (response?.type === "redirect") return {
+			type: "redirect",
+			url: response.redirect?.url ?? void 0
+		};
+		const message = response?.type === "message" || response?.type == null ? response?.message : void 0;
+		if (!message) return;
+		return {
+			type: "message",
+			html: serializeBody(message, {
+				values: formattedValues(),
+				descriptors: descriptorsFor(answerableFields()),
+				converters
+			})
+		};
+	};
+	const stepKeys = flow && currentStepId ? stepFieldNames(flow, currentStepId) : [];
+	const stepKeySet = new Set(stepKeys);
+	const stepVisible = visible.filter((field) => stepKeySet.has(fieldKey(field)));
+	const validateRepeaterSubFields = async (repeaters) => {
+		const errors = {};
+		for (const field of repeaters.filter((f) => f.blockType === "repeater" && isNamedField(f))) {
+			const rows = Array.isArray(effectiveValues[field.name]) ? effectiveValues[field.name] : [];
+			const subFields = (Array.isArray(field.subFields) ? field.subFields : []).filter(isNamedField);
+			for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+				const row = rows[rowIndex] ?? {};
+				for (const subField of subFields) {
+					if (!evaluateCondition(subField.visibleWhen, row)) continue;
+					if (!evaluateCondition(subField.validateWhen, row)) continue;
+					const subResult = await validateFieldValue({
+						field: subField,
+						value: row[subField.name],
+						registry,
+						ruleRegistry,
+						answers: row,
+						locale,
+						t: translate
+					});
+					const compositeKey = `${field.name}[${rowIndex}].${subField.name}`;
+					if (subResult.errors.length > 0) errors[compositeKey] = subResult.errors;
+				}
+			}
+		}
+		return errors;
+	};
 	const goNext = async () => {
-		if (!flow || !currentStepId) return;
-		const results = await Promise.all(stepVisible.filter((field) => !calcExpressionOf(field)).filter((field) => registry.get(field.blockType)?.value !== "none").filter(isNamedField).filter((field) => evaluateCondition(field.validateWhen, effectiveValues)).map(async (field) => ({
-			field,
-			...await validateFieldValue({
+		if (!flow || !currentStepId || advancingRef.current) return;
+		advancingRef.current = true;
+		try {
+			const results = await Promise.all(stepVisible.filter((field) => !calcExpressionOf(field)).filter((field) => registry.get(field.blockType)?.value !== "none").filter(isNamedField).filter((field) => evaluateCondition(field.validateWhen, effectiveValues)).map(async (field) => ({
 				field,
-				value: effectiveValues[field.name],
-				registry,
-				ruleRegistry,
-				answers: effectiveValues,
-				locale,
-				t: translate
-			})
-		})));
-		let hasError = false;
-		for (const result of results) {
-			rawDispatch({
-				type: "TOUCH",
-				name: result.field.name
+				...await validateFieldValue({
+					field,
+					value: effectiveValues[field.name],
+					registry,
+					ruleRegistry,
+					answers: effectiveValues,
+					locale,
+					t: translate
+				})
+			})));
+			let hasError = false;
+			for (const result of results) {
+				rawDispatch({
+					type: "TOUCH",
+					name: result.field.name
+				});
+				rawDispatch({
+					type: "SET_FIELD_ISSUES",
+					name: result.field.name,
+					errors: result.errors
+				});
+				if (result.errors.length > 0) hasError = true;
+			}
+			const repeaterErrors = await validateRepeaterSubFields(stepVisible);
+			for (const [compositeKey, errs] of Object.entries(repeaterErrors)) {
+				rawDispatch({
+					type: "SET_FIELD_ISSUES",
+					name: compositeKey,
+					errors: errs
+				});
+				hasError = true;
+			}
+			if (hasError) return;
+			const next = resolveNextStepId(flow, currentStepId, effectiveValues);
+			if (!next) return;
+			emitFormEvent(sinkRef.current, formIdRef.current, {
+				type: "step.completed",
+				stepId: currentStepId
 			});
-			rawDispatch({
-				type: "SET_FIELD_ISSUES",
-				name: result.field.name,
-				errors: result.errors
+			setHistory((prev) => [...prev, currentStepId]);
+			setCurrentStepId(next);
+			emitFormEvent(sinkRef.current, formIdRef.current, {
+				type: "step.viewed",
+				stepId: next
 			});
-			if (result.errors.length > 0) hasError = true;
+		} finally {
+			advancingRef.current = false;
 		}
-		if (hasError) return;
-		const next = resolveNextStepId(flow, currentStepId, effectiveValues);
-		if (!next) return;
-		emitFormEvent(sinkRef.current, formIdRef.current, {
-			type: "step.completed",
-			stepId: currentStepId
-		});
-		setHistory((prev) => [...prev, currentStepId]);
-		setCurrentStepId(next);
-		emitFormEvent(sinkRef.current, formIdRef.current, {
-			type: "step.viewed",
-			stepId: next
-		});
 	};
 	const goBack = () => {
 		const prev = history[history.length - 1];
@@ -306,28 +315,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 				message: firstError
 			});
 		}
-		for (const field of visible.filter((f) => f.blockType === "repeater" && isNamedField(f))) {
-			const rows = Array.isArray(effectiveValues[field.name]) ? effectiveValues[field.name] : [];
-			const subFields = (Array.isArray(field.subFields) ? field.subFields : []).filter(isNamedField);
-			for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
-				const row = rows[rowIndex] ?? {};
-				for (const subField of subFields) {
-					if (!evaluateCondition(subField.visibleWhen, row)) continue;
-					if (!evaluateCondition(subField.validateWhen, row)) continue;
-					const subResult = await validateFieldValue({
-						field: subField,
-						value: row[subField.name],
-						registry,
-						ruleRegistry,
-						answers: row,
-						locale,
-						t: translate
-					});
-					const compositeKey = `${field.name}[${rowIndex}].${subField.name}`;
-					if (subResult.errors.length > 0) errors[compositeKey] = subResult.errors;
-				}
-			}
-		}
+		Object.assign(errors, await validateRepeaterSubFields(visible));
 		rawDispatch({
 			type: "SET_ALL_ISSUES",
 			errors
@@ -341,7 +329,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		if (honeypotName) {
 			const decoy = honeypotRef.current?.value ?? "";
 			if (decoy !== "") values.push({
-				field: honeypotName,
+				field: HONEYPOT_VALUE_KEY,
 				value: decoy
 			});
 		}
@@ -360,13 +348,28 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		submittingRef.current = false;
 		if (result.ok) {
 			submittedRef.current = true;
-			rawDispatch({ type: "SUBMIT_SUCCESS" });
 			emitFormEvent(sinkRef.current, formIdRef.current, {
 				type: "submission.created",
 				submissionId: result.submissionId
 			});
-			onSuccess?.(result.submissionId);
-			if (activePresentation.dismissOnSuccess) handleClose();
+			onSuccess?.(result.submissionId, { response: resolveSuccessResponse() });
+			if (successBehavior === "reset") {
+				rawDispatch({
+					type: "RESET",
+					values: {
+						...seedFieldValues(form.fields),
+						...initialValues ?? {}
+					}
+				});
+				if (flow) {
+					setCurrentStepId(firstStepId(flow));
+					setHistory([]);
+				}
+				startedRef.current = false;
+			} else {
+				rawDispatch({ type: "SUBMIT_SUCCESS" });
+				if (activePresentation.dismissOnSuccess) handleClose();
+			}
 			const redirectUrl = form.response?.type === "redirect" ? form.response.redirect?.url : void 0;
 			if (typeof redirectUrl === "string" && redirectUrl.length > 0 && typeof window !== "undefined") window.location.assign(redirectUrl);
 		} else {
@@ -374,7 +377,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 				type: "SET_ALL_ISSUES",
 				errors: result.fieldErrors
 			});
-			const message = result.message ?? "Submission failed";
+			const message = result.message ?? translate(keys.formSubmitFailed);
 			rawDispatch({
 				type: "SUBMIT_ERROR",
 				message
@@ -382,6 +385,13 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 			onError?.(message);
 		}
 	};
+	const handleKeyDown = (event) => {
+		if (!flow || event.key !== "Enter") return;
+		const target = event.target;
+		if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement || target instanceof HTMLButtonElement) return;
+		if (target instanceof HTMLInputElement && (target.type === "submit" || target.type === "button")) return;
+		event.preventDefault();
+	};
 	const contextValue = {
 		form,
 		state,
@@ -410,7 +420,10 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		rendererRegistry,
 		labels,
 		t: translate,
-		effectiveValues
+		effectiveValues,
+		recall,
+		renderedFields: (flow ? stepVisible : visible).filter((field) => field.hidden !== true && field.calcDisplay !== false),
+		converters
 	};
 	const PresentationWrapper = activePresentation.Wrapper;
 	const wrap = (content) => PresentationWrapper ? /* @__PURE__ */ jsx(PresentationWrapper, {
@@ -418,7 +431,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		open: true,
 		onClose: handleClose,
 		title,
-		closeLabel,
+		closeLabel: resolvedCloseLabel,
 		children: content
 	}) : content;
 	if (children !== void 0) return /* @__PURE__ */ jsx(FormContext.Provider, {
@@ -427,6 +440,7 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 			className: cn("fb-form-root", className),
 			noValidate: true,
 			onSubmit: handleSubmit,
+			onKeyDown: handleKeyDown,
 			"data-fb-presentation": activePresentation.name,
 			"data-fb-density": activePresentation.density,
 			children: [honeypotName ? /* @__PURE__ */ jsx(Honeypot, {
@@ -436,11 +450,8 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 		}))
 	});
 	if (state.submitted) {
-		const responseMessage = form.response?.type === "message" || form.response?.type == null ? form.response?.message : void 0;
-		const responseHtml = responseMessage ? serializeBody(responseMessage, {
-			values: formattedValues(),
-			descriptors: descriptorsFor(answerableFields())
-		}) : void 0;
+		const successResponse = resolveSuccessResponse();
+		const responseHtml = successResponse?.type === "message" ? successResponse.html : void 0;
 		return /* @__PURE__ */ jsx(FormContext.Provider, {
 			value: contextValue,
 			children: wrap(responseHtml ? /* @__PURE__ */ jsx("div", {
@@ -454,17 +465,17 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 				className: cn("fb-form__success", className),
 				"data-fb-presentation": activePresentation.name,
 				"data-fb-density": activePresentation.density,
-				children: interpolate(successMessage, recall)
+				children: interpolate(resolvedSuccessMessage, recall)
 			}))
 		});
 	}
-	const rendered = (flow ? stepVisible : visible).filter((field) => field.hidden !== true && field.calcDisplay !== false);
 	return /* @__PURE__ */ jsx(FormContext.Provider, {
 		value: contextValue,
 		children: wrap(/* @__PURE__ */ jsxs("form", {
 			className: cn("fb-form-root", className),
 			noValidate: true,
 			onSubmit: handleSubmit,
+			onKeyDown: handleKeyDown,
 			"data-fb-presentation": activePresentation.name,
 			"data-fb-density": activePresentation.density,
 			children: [
@@ -472,35 +483,8 @@ const Form = ({ form, fieldTypes, rules, renderers, apiRoute, onSubmit, onSucces
 					name: honeypotName,
 					inputRef: honeypotRef
 				}) : null,
-				/* @__PURE__ */ jsx(FormLayout, {
-					enabled: layout !== false,
-					children: rendered.map((field) => {
-						const renderer = rendererRegistry.get(field.blockType);
-						if (!renderer) return null;
-						const width = typeof field.width === "string" && FIELD_WIDTHS.has(field.width) ? field.width : void 0;
-						const recalledField = applyRecall(field, recall);
-						return /* @__PURE__ */ jsx("div", {
-							...widthProps(width),
-							children: !isNamedField(recalledField) ? /* @__PURE__ */ jsx(StaticFieldHost, {
-								field: recalledField,
-								renderer,
-								locale,
-								t: translate
-							}) : calcExpressionOf(recalledField) ? /* @__PURE__ */ jsx(CalcFieldHost, {
-								field: recalledField,
-								renderer,
-								value: effectiveValues[recalledField.name],
-								locale,
-								t: translate
-							}) : /* @__PURE__ */ jsx(FieldHost, {
-								field: recalledField,
-								renderer,
-								locale,
-								t: translate
-							})
-						}, fieldKey(field));
-					})
-				}),
+				header,
+				/* @__PURE__ */ jsx(FormFields, { layout }),
 				state.submitError ? /* @__PURE__ */ jsx("p", {
 					role: "alert",
 					className: "fb-form__submit-error",