@form-engine-ts/react 1.1.0 → 2.0.0

package/dist/index.cjs

@@ -24,13 +24,390 @@ __export(index_exports, {
   FormProvider: () => FormProvider,
   FormRenderer: () => FormRenderer,
   useField: () => useField,
-  useForm: () => useForm
+  useForm: () => useForm,
+  useFormBuilder: () => useFormBuilder
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/builder.tsx
+var import_core2 = require("@form-engine-ts/core");
+var import_react2 = require("react");
+
+// src/hooks/useFormBuilder.ts
 var import_core = require("@form-engine-ts/core");
 var import_react = require("react");
+var DEFAULT_PREFIXES = { field: "q", option: "opt", page: "page" };
+function defaultIdFactory(kind, existingIds) {
+  const prefix = DEFAULT_PREFIXES[kind];
+  let id;
+  do {
+    id = `${prefix}_${globalThis.crypto.randomUUID().slice(0, 8)}`;
+  } while (existingIds.has(id));
+  return id;
+}
+function newField(type, id, optionId) {
+  const base = { id, title: "New question", required: false };
+  if (type === "text" || type === "textarea") return { ...base, type };
+  if (type === "number") return { ...base, type };
+  if (type === "rating") return { ...base, type, min: 1, max: 5 };
+  if (type === "checkbox") return { ...base, type };
+  return optionId === void 0 ? void 0 : { ...base, type, options: [{ id: optionId, label: "Option 1" }] };
+}
+function move(items, sourceIndex, targetIndex) {
+  if (sourceIndex < 0 || targetIndex < 0 || targetIndex >= items.length || sourceIndex === targetIndex)
+    return void 0;
+  const result = [...items];
+  const [item] = result.splice(sourceIndex, 1);
+  if (item === void 0) return void 0;
+  result.splice(targetIndex, 0, item);
+  return result;
+}
+function addPolicyIssues(schema, policy, issues) {
+  if (policy?.maxFields !== void 0 && schema.fields.length > policy.maxFields) {
+    issues.push({
+      path: "fields",
+      code: "max_fields_exceeded",
+      message: `At most ${policy.maxFields} fields are allowed.`
+    });
+  }
+  schema.fields.forEach((field, index) => {
+    if (policy?.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(field.type)) {
+      issues.push({
+        path: `fields[${index}].type`,
+        code: "disallowed_field_type",
+        message: `Field type ${field.type} is not allowed.`
+      });
+    }
+    if (policy?.maxTextLength !== void 0) {
+      for (const [property, text] of [
+        ["title", field.title],
+        ["description", field.description]
+      ]) {
+        if (text !== void 0 && text.length > policy.maxTextLength) {
+          issues.push({
+            path: `fields[${index}].${property}`,
+            code: "max_text_length_exceeded",
+            message: `Text must be at most ${policy.maxTextLength} characters.`
+          });
+        }
+      }
+    }
+    if (policy?.maxOptionsPerField !== void 0 && "options" in field && field.options.length > policy.maxOptionsPerField) {
+      issues.push({
+        path: `fields[${index}].options`,
+        code: "max_options_exceeded",
+        message: `At most ${policy.maxOptionsPerField} options are allowed.`
+      });
+    }
+  });
+  for (const locale of policy?.requiredLocales ?? []) {
+    if (!(schema.supportedLocales ?? []).includes(locale)) {
+      issues.push({
+        path: "supportedLocales",
+        code: "required_locale_missing",
+        message: `Required locale ${locale} is missing.`
+      });
+    }
+    if (locale === schema.defaultLocale) continue;
+    const requiredTranslations = [
+      { path: `translations.${locale}.title`, value: schema.translations?.[locale]?.title },
+      ...schema.fields.map((field, index) => ({
+        path: `fields[${index}].translations.${locale}.title`,
+        value: field.translations?.[locale]?.title
+      })),
+      ...schema.fields.flatMap(
+        (field, fieldIndex) => "options" in field ? field.options.map((option, optionIndex) => ({
+          path: `fields[${fieldIndex}].options[${optionIndex}].translations.${locale}`,
+          value: option.translations?.[locale]
+        })) : []
+      ),
+      ...schema.pages?.flatMap(
+        (page, pageIndex) => page.title === void 0 ? [] : [{ path: `pages[${pageIndex}].translations.${locale}.title`, value: page.translations?.[locale]?.title }]
+      ) ?? []
+    ];
+    for (const translation of requiredTranslations) {
+      if (translation.value === void 0 || translation.value.trim().length === 0) {
+        issues.push({
+          path: translation.path,
+          code: "required_translation_missing",
+          message: `A translation for required locale ${locale} is missing.`
+        });
+      }
+    }
+  }
+}
+function useFormBuilder({
+  schema,
+  onChange,
+  policy,
+  idFactory = defaultIdFactory
+}) {
+  const createId = (0, import_react.useCallback)(
+    (kind, existingIds) => {
+      const id = idFactory(kind, existingIds).trim();
+      return id.length > 0 && !existingIds.has(id) ? id : void 0;
+    },
+    [idFactory]
+  );
+  const addField = (0, import_react.useCallback)(
+    (type, pageId) => {
+      if (policy?.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(type)) {
+        return { success: false, error: { type: "disallowed_field_type", fieldType: type } };
+      }
+      if (policy?.maxFields !== void 0 && schema.fields.length >= policy.maxFields) {
+        return { success: false, error: { type: "max_fields_exceeded", max: policy.maxFields } };
+      }
+      const fieldId = createId("field", new Set(schema.fields.map((field2) => field2.id)));
+      const needsOption = ["select", "radio", "multi-select"].includes(type);
+      const optionId = needsOption ? createId(
+        "option",
+        new Set(
+          schema.fields.flatMap((field2) => "options" in field2 ? field2.options.map((option) => option.id) : [])
+        )
+      ) : void 0;
+      if (fieldId === void 0 || needsOption && optionId === void 0) {
+        return {
+          success: false,
+          error: { type: "invalid_operation", message: "idFactory returned a duplicate or empty ID." }
+        };
+      }
+      const field = newField(type, fieldId, optionId);
+      if (field === void 0) {
+        return { success: false, error: { type: "invalid_operation", message: "Could not create the field." } };
+      }
+      const pages = schema.pages?.map((page, index) => ({
+        ...page,
+        questionIds: page.id === pageId || pageId === void 0 && index === (schema.pages?.length ?? 0) - 1 ? [...page.questionIds, fieldId] : page.questionIds
+      }));
+      if (schema.pages !== void 0 && !schema.pages.some((page) => page.id === pageId) && pageId !== void 0) {
+        return { success: false, error: { type: "invalid_operation", message: `Unknown page: ${pageId}` } };
+      }
+      onChange({ ...schema, fields: [...schema.fields, field], ...pages === void 0 ? {} : { pages } });
+      return { success: true };
+    },
+    [createId, onChange, policy, schema]
+  );
+  const removeField = (0, import_react.useCallback)(
+    (fieldId) => {
+      if (schema.fields.length <= 1 || !schema.fields.some((field) => field.id === fieldId)) return;
+      const fields = schema.fields.filter((field) => field.id !== fieldId).map(
+        (field) => field.displayCondition?.questionId === fieldId ? (({ displayCondition: _condition, ...candidate }) => candidate)(field) : field
+      );
+      const remainingPages = schema.pages?.map((page) => ({ ...page, questionIds: page.questionIds.filter((id) => id !== fieldId) })).filter((page) => page.questionIds.length > 0);
+      if (schema.pages !== void 0 && remainingPages?.length === 0) {
+        const { pages: _pages, ...singlePageSchema } = schema;
+        onChange({ ...singlePageSchema, fields });
+      } else {
+        onChange({ ...schema, fields, ...remainingPages === void 0 ? {} : { pages: remainingPages } });
+      }
+    },
+    [onChange, schema]
+  );
+  const moveField = (0, import_react.useCallback)(
+    (fieldId, targetIndex) => {
+      const fields = move(
+        schema.fields,
+        schema.fields.findIndex((field) => field.id === fieldId),
+        targetIndex
+      );
+      if (fields !== void 0) {
+        const indexById = new Map(fields.map((field, index) => [field.id, index]));
+        const safeFields = fields.map((field, index) => {
+          const sourceIndex = field.displayCondition === void 0 ? void 0 : indexById.get(field.displayCondition.questionId);
+          if (field.displayCondition === void 0 || sourceIndex !== void 0 && sourceIndex < index) return field;
+          const { displayCondition: _condition, ...withoutCondition } = field;
+          return withoutCondition;
+        });
+        onChange({ ...schema, fields: safeFields });
+      }
+    },
+    [onChange, schema]
+  );
+  const updateField = (0, import_react.useCallback)(
+    (fieldId, updater) => {
+      const current = schema.fields.find((field) => field.id === fieldId);
+      if (current === void 0) return;
+      const updated = updater(current);
+      if (updated.id !== fieldId) return;
+      if (policy?.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(updated.type)) return;
+      const maxTextLength = policy?.maxTextLength;
+      if (maxTextLength !== void 0 && [updated.title, updated.description].some((text) => text !== void 0 && text.length > maxTextLength)) {
+        return;
+      }
+      onChange({ ...schema, fields: schema.fields.map((field) => field.id === fieldId ? updated : field) });
+    },
+    [onChange, policy, schema]
+  );
+  const addOption = (0, import_react.useCallback)(
+    (fieldId) => {
+      const field = schema.fields.find((candidate) => candidate.id === fieldId);
+      if (field === void 0 || !("options" in field)) {
+        return { success: false, error: { type: "invalid_operation", message: `Field ${fieldId} has no options.` } };
+      }
+      if (policy?.maxOptionsPerField !== void 0 && field.options.length >= policy.maxOptionsPerField) {
+        return { success: false, error: { type: "max_options_exceeded", max: policy.maxOptionsPerField } };
+      }
+      const existingIds = new Set(
+        schema.fields.flatMap(
+          (candidate) => "options" in candidate ? candidate.options.map((option2) => option2.id) : []
+        )
+      );
+      const optionId = createId("option", existingIds);
+      if (optionId === void 0) {
+        return {
+          success: false,
+          error: { type: "invalid_operation", message: "idFactory returned a duplicate or empty ID." }
+        };
+      }
+      const option = { id: optionId, label: `Option ${field.options.length + 1}` };
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (candidate) => candidate.id === fieldId && "options" in candidate ? { ...candidate, options: [...candidate.options, option] } : candidate
+        )
+      });
+      return { success: true };
+    },
+    [createId, onChange, policy, schema]
+  );
+  const removeOption = (0, import_react.useCallback)(
+    (fieldId, optionId) => {
+      const field = schema.fields.find((candidate) => candidate.id === fieldId);
+      if (field === void 0 || !("options" in field) || field.options.length <= 1) return;
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (candidate) => candidate.id === fieldId && "options" in candidate ? { ...candidate, options: candidate.options.filter((option) => option.id !== optionId) } : candidate
+        )
+      });
+    },
+    [onChange, schema]
+  );
+  const moveOption = (0, import_react.useCallback)(
+    (fieldId, optionId, targetIndex) => {
+      const field = schema.fields.find((candidate) => candidate.id === fieldId);
+      if (field === void 0 || !("options" in field)) return;
+      const options = move(
+        field.options,
+        field.options.findIndex((option) => option.id === optionId),
+        targetIndex
+      );
+      if (options === void 0) return;
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (candidate) => candidate.id === fieldId && "options" in candidate ? { ...candidate, options } : candidate
+        )
+      });
+    },
+    [onChange, schema]
+  );
+  const addPage = (0, import_react.useCallback)(
+    (questionId) => {
+      const existingIds = new Set(schema.pages?.map((page) => page.id) ?? []);
+      const pageId = createId("page", existingIds);
+      if (pageId === void 0) return;
+      if (schema.pages === void 0) {
+        onChange({ ...schema, pages: [{ id: pageId, questionIds: schema.fields.map((field) => field.id) }] });
+        return;
+      }
+      const movableQuestionId = questionId ?? schema.pages.find((page) => page.questionIds.length > 1)?.questionIds.at(-1);
+      if (movableQuestionId === void 0) return;
+      const sourcePage = schema.pages.find((page) => page.questionIds.includes(movableQuestionId));
+      if (sourcePage === void 0 || sourcePage.questionIds.length <= 1) return;
+      const pages = [
+        ...schema.pages.map((page) => ({
+          ...page,
+          questionIds: page.questionIds.filter((id) => id !== movableQuestionId)
+        })),
+        { id: pageId, questionIds: [movableQuestionId] }
+      ];
+      onChange({ ...schema, pages });
+    },
+    [createId, onChange, schema]
+  );
+  const removePage = (0, import_react.useCallback)(
+    (pageId) => {
+      if (schema.pages === void 0) return;
+      const index = schema.pages.findIndex((page) => page.id === pageId);
+      const removed = schema.pages[index];
+      if (removed === void 0) return;
+      if (schema.pages.length === 1) {
+        const { pages: _pages, ...singlePage } = schema;
+        onChange(singlePage);
+        return;
+      }
+      const targetIndex = index === 0 ? 1 : index - 1;
+      onChange({
+        ...schema,
+        pages: schema.pages.map(
+          (page, pageIndex) => pageIndex === targetIndex ? { ...page, questionIds: [...page.questionIds, ...removed.questionIds] } : page
+        ).filter((page) => page.id !== pageId)
+      });
+    },
+    [onChange, schema]
+  );
+  const setLocaleTranslation = (0, import_react.useCallback)(
+    (locale, target, property, text) => {
+      if (locale.trim().length === 0 || policy?.maxTextLength !== void 0 && text.length > policy.maxTextLength)
+        return;
+      const supportedLocales = [.../* @__PURE__ */ new Set([...schema.supportedLocales ?? [], locale])];
+      if (target === "form" && ["title", "description", "completionMessage"].includes(property)) {
+        onChange({
+          ...schema,
+          supportedLocales,
+          translations: { ...schema.translations, [locale]: { ...schema.translations?.[locale], [property]: text } }
+        });
+        return;
+      }
+      const fields = schema.fields.map((field) => {
+        if (field.id === target && ["title", "description"].includes(property)) {
+          return {
+            ...field,
+            translations: { ...field.translations, [locale]: { ...field.translations?.[locale], [property]: text } }
+          };
+        }
+        if (!("options" in field) || property !== "label") return field;
+        return {
+          ...field,
+          options: field.options.map(
+            (option) => option.id === target ? { ...option, translations: { ...option.translations, [locale]: text } } : option
+          )
+        };
+      });
+      const pages = schema.pages?.map(
+        (page) => page.id === target && ["title", "description"].includes(property) ? {
+          ...page,
+          translations: { ...page.translations, [locale]: { ...page.translations?.[locale], [property]: text } }
+        } : page
+      );
+      onChange({ ...schema, supportedLocales, fields, ...pages === void 0 ? {} : { pages } });
+    },
+    [onChange, policy, schema]
+  );
+  const validationIssues = (0, import_react.useMemo)(() => {
+    const result = (0, import_core.validateFormSchema)(schema);
+    const issues = result.valid ? [] : [...result.issues];
+    addPolicyIssues(schema, policy, issues);
+    return issues;
+  }, [policy, schema]);
+  return {
+    schema,
+    addField,
+    removeField,
+    moveField,
+    updateField,
+    addOption,
+    removeOption,
+    moveOption,
+    addPage,
+    removePage,
+    setLocaleTranslation,
+    validationIssues
+  };
+}
+
+// src/builder.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var FIELD_TYPES = [
   "text",
@@ -154,7 +531,7 @@ function withoutDisplayCondition(field) {
   return rest;
 }
 function sanitizeBuilderSchema(schema) {
-  const sanitized = (0, import_core.sanitizeSchema)(schema);
+  const sanitized = (0, import_core2.sanitizeSchema)(schema);
   const indexById = new Map(sanitized.fields.map((field, index) => [field.id, index]));
   const fields = sanitized.fields.map((field, index) => {
     const sourceId = field.displayCondition?.questionId;
@@ -214,20 +591,32 @@ function ConditionValueEditor({
     }
   );
 }
-function FormBuilder({ schema, onChange, locale = "en", translator, translationAdapter }) {
-  const [newPageQuestionId, setNewPageQuestionId] = (0, import_react.useState)("");
-  const [newLocale, setNewLocale] = (0, import_react.useState)("");
-  const [editingLocale, setEditingLocale] = (0, import_react.useState)("");
-  const [isTranslating, setIsTranslating] = (0, import_react.useState)(false);
-  const [translationError, setTranslationError] = (0, import_react.useState)(null);
+function FormBuilder({
+  schema,
+  onChange,
+  locale = "en",
+  translator,
+  translationAdapter,
+  policy,
+  idFactory
+}) {
+  const headless = useFormBuilder({
+    schema,
+    onChange,
+    ...policy === void 0 ? {} : { policy },
+    ...idFactory === void 0 ? {} : { idFactory }
+  });
+  const [newPageQuestionId, setNewPageQuestionId] = (0, import_react2.useState)("");
+  const [newLocale, setNewLocale] = (0, import_react2.useState)("");
+  const [editingLocale, setEditingLocale] = (0, import_react2.useState)("");
+  const [isTranslating, setIsTranslating] = (0, import_react2.useState)(false);
+  const [translationError, setTranslationError] = (0, import_react2.useState)(null);
   const translate = (key, params = {}) => {
     const translated = translator?.translate(key, locale, params);
     return translated === void 0 ? interpolate(BUILDER_DEFAULTS[key] ?? key, params) : translated;
   };
   const emitSchema = (candidate) => onChange(sanitizeBuilderSchema(candidate));
-  const updateField = (fieldId, update) => {
-    emitSchema({ ...schema, fields: schema.fields.map((field) => field.id === fieldId ? update(field) : field) });
-  };
+  const updateField = headless.updateField;
   const changeType = (fieldId, type) => {
     emitSchema({
       ...schema,
@@ -243,10 +632,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
       })
     });
   };
-  const removeField = (fieldId) => {
-    if (schema.fields.length === 1) return;
-    emitSchema({ ...schema, fields: schema.fields.filter((field) => field.id !== fieldId) });
-  };
+  const removeField = headless.removeField;
   const moveField = (index, offset) => {
     const target = index + offset;
     if (target < 0 || target >= schema.fields.length) return;
@@ -258,21 +644,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     fields[target] = current;
     emitSchema({ ...schema, fields });
   };
-  const addField = () => {
-    const id = createUniqueId("q", new Set(schema.fields.map((field) => field.id)));
-    const nextSchema = {
-      ...schema,
-      fields: [...schema.fields, { id, type: "text", title: translate("builder.newQuestionTitle"), required: false }]
-    };
-    emitSchema(
-      schema.pages === void 0 ? nextSchema : {
-        ...nextSchema,
-        pages: schema.pages.map(
-          (page, index) => index === (schema.pages?.length ?? 0) - 1 ? { ...page, questionIds: [...page.questionIds, id] } : page
-        )
-      }
-    );
-  };
+  const addField = () => headless.addField("text");
   const enablePages = () => {
     if (schema.pages !== void 0) return;
     emitSchema({
@@ -370,7 +742,10 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     setIsTranslating(true);
     setTranslationError(null);
     try {
-      onChange(await (0, import_core.populateSchemaTranslations)(schema, [editingLocale], translationAdapter));
+      const populated = await (0, import_core2.populateSchemaTranslations)(schema, [editingLocale], translationAdapter, {
+        overwrite: "all"
+      });
+      onChange(populated.schema);
     } catch (cause) {
       setTranslationError(cause instanceof Error ? cause.message : String(cause));
     } finally {
@@ -719,7 +1094,9 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
               {
                 value: field.type,
                 onChange: (event) => changeType(field.id, event.currentTarget.value),
-                children: FIELD_TYPES.map((type) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: type, children: translate(fieldTypeKey(type)) }, type))
+                children: FIELD_TYPES.filter(
+                  (type) => policy?.allowedFieldTypes === void 0 || policy.allowedFieldTypes.includes(type)
+                ).map((type) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: type, children: translate(fieldTypeKey(type)) }, type))
               }
             )
           ] }),
@@ -892,13 +1269,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
               {
                 type: "button",
                 disabled: field.options.length === 1,
-                onClick: () => updateField(
-                  field.id,
-                  (current) => "options" in current ? {
-                    ...current,
-                    options: current.options.filter((_item, itemIndex) => itemIndex !== optionIndex)
-                  } : current
-                ),
+                onClick: () => headless.removeOption(field.id, option.id),
                 children: translate("builder.remove")
               }
             )
@@ -907,22 +1278,8 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
             "button",
             {
               type: "button",
-              onClick: () => updateField(
-                field.id,
-                (current) => "options" in current ? (() => {
-                  const id = createUniqueId("opt", new Set(current.options.map((option) => option.id)));
-                  return {
-                    ...current,
-                    options: [
-                      ...current.options,
-                      {
-                        id,
-                        label: translate("builder.newOptionLabel", { index: current.options.length + 1 })
-                      }
-                    ]
-                  };
-                })() : current
-              ),
+              disabled: policy?.maxOptionsPerField !== void 0 && field.options.length >= policy.maxOptionsPerField,
+              onClick: () => headless.addOption(field.id),
               children: translate("builder.addOption")
             }
           )
@@ -984,15 +1341,24 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
         ] })
       ] }, field.id);
     }) }),
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { className: "form-engine-builder__add", type: "button", onClick: addField, children: translate("builder.addQuestion") })
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        className: "form-engine-builder__add",
+        type: "button",
+        disabled: policy?.maxFields !== void 0 && schema.fields.length >= policy.maxFields,
+        onClick: addField,
+        children: translate("builder.addQuestion")
+      }
+    )
   ] });
 }
 
 // src/context.tsx
-var import_core2 = require("@form-engine-ts/core");
-var import_react2 = require("react");
+var import_core3 = require("@form-engine-ts/core");
+var import_react3 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
-var FormContext = (0, import_react2.createContext)(null);
+var FormContext = (0, import_react3.createContext)(null);
 function issuesByField(issues) {
   const result = {};
   for (const issue of issues) result[issue.fieldId] ??= issue;
@@ -1007,30 +1373,30 @@ function FormProvider({
   onSubmit,
   children
 }) {
-  const validSchema = (0, import_react2.useMemo)(() => {
-    (0, import_core2.assertValidFormSchema)(schema);
-    const localized = (0, import_core2.resolveLocalizedSchema)(schema, locale);
-    (0, import_core2.assertValidFormSchema)(localized);
+  const validSchema = (0, import_react3.useMemo)(() => {
+    (0, import_core3.assertValidFormSchema)(schema);
+    const localized = (0, import_core3.resolveLocalizedSchema)(schema, locale);
+    (0, import_core3.assertValidFormSchema)(localized);
     return localized;
   }, [locale, schema]);
-  const [values, setValues] = (0, import_react2.useState)(() => ({ ...initialValues }));
-  const [errors, setErrors] = (0, import_react2.useState)({});
-  const [submitStatus, setSubmitStatus] = (0, import_react2.useState)("idle");
-  const [submitError, setSubmitError] = (0, import_react2.useState)(null);
-  const [validationPageIndex, setValidationPageIndex] = (0, import_react2.useState)(null);
-  const visibility = (0, import_react2.useMemo)(() => (0, import_core2.calculateFieldVisibility)(validSchema, values), [validSchema, values]);
-  const pageVisibility = (0, import_react2.useMemo)(() => (0, import_core2.calculatePageVisibility)(validSchema, values), [validSchema, values]);
-  (0, import_react2.useEffect)(() => {
+  const [values, setValues] = (0, import_react3.useState)(() => ({ ...initialValues }));
+  const [errors, setErrors] = (0, import_react3.useState)({});
+  const [submitStatus, setSubmitStatus] = (0, import_react3.useState)("idle");
+  const [submitError, setSubmitError] = (0, import_react3.useState)(null);
+  const [validationPageIndex, setValidationPageIndex] = (0, import_react3.useState)(null);
+  const visibility = (0, import_react3.useMemo)(() => (0, import_core3.calculateFieldVisibility)(validSchema, values), [validSchema, values]);
+  const pageVisibility = (0, import_react3.useMemo)(() => (0, import_core3.calculatePageVisibility)(validSchema, values), [validSchema, values]);
+  (0, import_react3.useEffect)(() => {
     const fieldIds = new Set(validSchema.fields.map((field) => field.id));
     setValues((current) => Object.fromEntries(Object.entries(current).filter(([fieldId]) => fieldIds.has(fieldId))));
   }, [validSchema]);
-  const setValue = (0, import_react2.useCallback)(
+  const setValue = (0, import_react3.useCallback)(
     (fieldId, value) => {
       setValues((current) => {
         const next = { ...current, [fieldId]: value };
         setErrors((currentErrors) => {
           if (Object.keys(currentErrors).length === 0) return currentErrors;
-          const result = validationPageIndex === null ? (0, import_core2.validateAnswers)(validSchema, next) : (0, import_core2.validatePageAnswers)(validSchema, validationPageIndex, next);
+          const result = validationPageIndex === null ? (0, import_core3.validateAnswers)(validSchema, next) : (0, import_core3.validatePageAnswers)(validSchema, validationPageIndex, next);
           return issuesByField(result.issues);
         });
         return next;
@@ -1040,7 +1406,7 @@ function FormProvider({
     },
     [validSchema, validationPageIndex]
   );
-  const restoreValues = (0, import_react2.useCallback)(
+  const restoreValues = (0, import_react3.useCallback)(
     (restoredValues) => {
       const fieldIds = new Set(validSchema.fields.map((field) => field.id));
       setValues(Object.fromEntries(Object.entries(restoredValues).filter(([fieldId]) => fieldIds.has(fieldId))));
@@ -1051,9 +1417,9 @@ function FormProvider({
     },
     [validSchema]
   );
-  const validatePage = (0, import_react2.useCallback)(
+  const validatePage = (0, import_react3.useCallback)(
     (pageIndex) => {
-      const result = (0, import_core2.validatePageAnswers)(validSchema, pageIndex, values);
+      const result = (0, import_core3.validatePageAnswers)(validSchema, pageIndex, values);
       setErrors(issuesByField(result.issues));
       setValidationPageIndex(result.valid ? null : pageIndex);
       setSubmitStatus("idle");
@@ -1062,42 +1428,51 @@ function FormProvider({
     },
     [validSchema, values]
   );
-  const reset = (0, import_react2.useCallback)(() => {
+  const reset = (0, import_react3.useCallback)(() => {
     setValues({ ...initialValues });
     setErrors({});
     setValidationPageIndex(null);
     setSubmitStatus("idle");
     setSubmitError(null);
   }, [initialValues]);
-  const submit = (0, import_react2.useCallback)(async () => {
-    const validation = (0, import_core2.validateAnswers)(validSchema, values);
-    if (!validation.valid) {
-      setErrors(issuesByField(validation.issues));
+  const submit = (0, import_react3.useCallback)(
+    async (beforeSubmit) => {
+      const validation = (0, import_core3.validateAnswers)(validSchema, values);
+      if (!validation.valid) {
+        setErrors(issuesByField(validation.issues));
+        setValidationPageIndex(null);
+        setSubmitStatus("error");
+        setSubmitError(null);
+        return { status: "invalid", issues: validation.issues };
+      }
+      setErrors({});
       setValidationPageIndex(null);
-      setSubmitStatus("error");
       setSubmitError(null);
-      return false;
-    }
-    setErrors({});
-    setValidationPageIndex(null);
-    setSubmitStatus("submitting");
-    setSubmitError(null);
-    try {
-      await onSubmit((0, import_core2.selectVisibleAnswers)(validSchema, values));
-      if (resetOnSuccess) setValues({ ...initialValues });
-      setSubmitStatus("success");
-      return true;
-    } catch (cause) {
-      setSubmitError(cause instanceof Error ? cause : new Error(String(cause)));
-      setSubmitStatus("error");
-      return false;
-    }
-  }, [initialValues, onSubmit, resetOnSuccess, validSchema, values]);
-  const translate = (0, import_react2.useCallback)(
+      const visibleValues = (0, import_core3.selectVisibleAnswers)(validSchema, values);
+      try {
+        if (beforeSubmit !== void 0 && await beforeSubmit(visibleValues) === "cancel") {
+          setSubmitStatus("idle");
+          return { status: "cancelled" };
+        }
+        setSubmitStatus("submitting");
+        await onSubmit(visibleValues);
+        if (resetOnSuccess) setValues({ ...initialValues });
+        setSubmitStatus("success");
+        return { status: "success" };
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        setSubmitError(error);
+        setSubmitStatus("error");
+        return { status: "error", error };
+      }
+    },
+    [initialValues, onSubmit, resetOnSuccess, validSchema, values]
+  );
+  const translate = (0, import_react3.useCallback)(
     (key, params) => translator.translate(key, locale, params),
     [locale, translator]
   );
-  const contextValue = (0, import_react2.useMemo)(
+  const contextValue = (0, import_react3.useMemo)(
     () => ({
       schema: validSchema,
       locale,
@@ -1137,7 +1512,7 @@ function FormProvider({
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(FormContext.Provider, { value: contextValue, children });
 }
 function useForm() {
-  const context = (0, import_react2.useContext)(FormContext);
+  const context = (0, import_react3.useContext)(FormContext);
   if (context === null) throw new Error("useForm must be called inside a FormProvider.");
   return context;
 }
@@ -1145,13 +1520,13 @@ function useField(fieldId) {
   const form = useForm();
   const field = form.schema.fields.find((item) => item.id === fieldId);
   if (field === void 0) throw new Error(`Unknown form field: ${fieldId}`);
-  const setValue = (0, import_react2.useCallback)((value) => form.setValue(fieldId, value), [fieldId, form]);
+  const setValue = (0, import_react3.useCallback)((value) => form.setValue(fieldId, value), [fieldId, form]);
   return { field, value: form.values[fieldId], error: form.errors[fieldId], setValue };
 }
 
 // src/renderer.tsx
-var import_core3 = require("@form-engine-ts/core");
-var import_react3 = require("react");
+var import_core4 = require("@form-engine-ts/core");
+var import_react4 = require("react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 function describedBy(field, error, helpId, errorId) {
   const ids = [field.description === void 0 ? void 0 : helpId, error === void 0 ? void 0 : errorId].filter(
@@ -1354,36 +1729,39 @@ function parseDraft(serialized) {
     return null;
   }
 }
-function FormRenderer({
+function ContextFormRenderer({
   components = {},
   className = "",
   successMessageKey,
   errorMessageKey,
-  autoSaveKey
+  autoSaveKey,
+  beforeSubmit,
+  onDraftSave,
+  slots = {}
 }) {
   const form = useForm();
-  const prefix = (0, import_react3.useId)().replace(/:/g, "");
-  const formRef = (0, import_react3.useRef)(null);
-  const loadedDraftKey = (0, import_react3.useRef)(null);
-  const [draftRestored, setDraftRestored] = (0, import_react3.useState)(false);
-  const [currentPageIndex, setCurrentPageIndex] = (0, import_react3.useState)(0);
-  const [focusFieldId, setFocusFieldId] = (0, import_react3.useState)(null);
+  const prefix = (0, import_react4.useId)().replace(/:/g, "");
+  const formRef = (0, import_react4.useRef)(null);
+  const loadedDraftKey = (0, import_react4.useRef)(null);
+  const [draftRestored, setDraftRestored] = (0, import_react4.useState)(false);
+  const [currentPageIndex, setCurrentPageIndex] = (0, import_react4.useState)(0);
+  const [focusFieldId, setFocusFieldId] = (0, import_react4.useState)(null);
   const pages = form.schema.pages;
-  const visiblePageIndexes = (0, import_react3.useMemo)(
+  const visiblePageIndexes = (0, import_react4.useMemo)(
     () => 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);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     if (pages === void 0 || visiblePageIndexes.length === 0) {
       setCurrentPageIndex(0);
       return;
     }
     if (!visiblePageIndexes.includes(currentPageIndex)) setCurrentPageIndex(visiblePageIndexes[0] ?? 0);
   }, [currentPageIndex, pages, visiblePageIndexes]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     if (focusFieldId === null) return;
     const fieldContainer = [...formRef.current?.querySelectorAll("[data-field-id]") ?? []].find(
       (element) => element.dataset.fieldId === focusFieldId
@@ -1394,7 +1772,7 @@ function FormRenderer({
       setFocusFieldId(null);
     }
   }, [focusFieldId]);
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
     const loadIdentity = `${autoSaveKey}:${form.schema.id}:${form.schema.version}`;
     if (loadedDraftKey.current === loadIdentity) return;
@@ -1406,10 +1784,11 @@ function FormRenderer({
     form.restoreValues(draft.values);
     setDraftRestored(true);
   }, [autoSaveKey, form.restoreValues, form.schema.id, form.schema.version]);
-  (0, import_react3.useEffect)(() => {
-    if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
+  (0, import_react4.useEffect)(() => {
     if (form.submitStatus === "success") return;
     const timeout = globalThis.setTimeout(() => {
+      onDraftSave?.(form.values);
+      if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
       const draft = {
         formId: form.schema.id,
         formVersion: form.schema.version,
@@ -1419,7 +1798,7 @@ function FormRenderer({
       globalThis.localStorage.setItem(autoSaveKey, JSON.stringify(draft));
     }, 500);
     return () => globalThis.clearTimeout(timeout);
-  }, [autoSaveKey, form.schema.id, form.schema.version, form.submitStatus, form.values]);
+  }, [autoSaveKey, form.schema.id, form.schema.version, form.submitStatus, form.values, onDraftSave]);
   const focusFirstIssue = (fieldId) => {
     if (fieldId !== void 0) setFocusFieldId(fieldId);
   };
@@ -1432,27 +1811,39 @@ function FormRenderer({
     const nextPageIndex = visiblePageIndexes[activeVisibleIndex + 1];
     if (nextPageIndex !== void 0) setCurrentPageIndex(nextPageIndex);
   };
-  const handleSubmit = async (event) => {
-    event.preventDefault();
-    const validation = (0, import_core3.validateAnswers)(form.schema, form.values);
+  const submitValues = async () => {
+    const validation = (0, import_core4.validateAnswers)(form.schema, form.values);
     const firstInvalidFieldId = validation.issues[0]?.fieldId;
-    const valid = await form.submit();
-    if (!valid) {
+    const result = await form.submit(beforeSubmit);
+    if (result.status === "invalid") {
       const invalidPageIndex = pages?.findIndex(
         (page) => firstInvalidFieldId === void 0 ? false : page.questionIds.includes(firstInvalidFieldId)
       );
       if (invalidPageIndex !== void 0 && invalidPageIndex >= 0) setCurrentPageIndex(invalidPageIndex);
       focusFirstIssue(firstInvalidFieldId);
-      return;
+      return result;
     }
+    if (result.status !== "success") return result;
     if (autoSaveKey !== void 0 && typeof globalThis.localStorage !== "undefined") {
       globalThis.localStorage.removeItem(autoSaveKey);
       setDraftRestored(false);
     }
     setCurrentPageIndex(visiblePageIndexes[0] ?? 0);
+    return result;
   };
+  const handleSubmit = (event) => {
+    event.preventDefault();
+    void submitValues();
+  };
+  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: form.isSubmitting, onSubmit: () => void submitValues() }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "fe-submit", type: "submit", disabled: form.isSubmitting, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("form", { ref: formRef, className: `fe-form ${className}`.trim(), noValidate: true, onSubmit: handleSubmit, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("header", { className: "fe-header", children: [
+    slots.renderHeader?.({
+      title: form.schema.title,
+      ...form.schema.description === void 0 ? {} : { description: form.schema.description }
+    }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("header", { className: "fe-header", children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h1", { children: form.schema.title }),
       form.schema.description === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { children: form.schema.description }),
       pages === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-progress", children: [
@@ -1480,42 +1871,122 @@ function FormRenderer({
     activePage?.title === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { className: "fe-page-title", children: activePage.title }),
     activePage?.description === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { className: "fe-page-description", children: activePage.description }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "fe-fields", children: form.schema.fields.filter((field) => form.visibility[field.id] === true && (fieldIds === void 0 || fieldIds.has(field.id))).map((field) => {
+      const error = form.errors[field.id];
       const props = {
         field,
         value: form.values[field.id],
-        error: form.errors[field.id],
+        error,
         setValue: (value) => form.setValue(field.id, value),
         translate: form.translate,
         inputId: `${prefix}-${field.id}`,
         errorId: `${prefix}-${field.id}-error`,
         helpId: `${prefix}-${field.id}-help`
       };
+      if (slots.renderField !== void 0) {
+        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react4.Fragment, { children: slots.renderField({
+          question: field,
+          value: form.values[field.id],
+          onChange: (value) => {
+            if (isFormValue(value)) form.setValue(field.id, value);
+          },
+          ...error === void 0 ? {} : { error }
+        }) }, field.id);
+      }
       const Component = components[field.type];
       return Component === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DefaultField, { ...props }, field.id) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Component, { ...props }, field.id);
     }) }),
-    pages === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "fe-submit", type: "submit", disabled: form.isSubmitting, children: form.translate(form.schema.submitLabelKey ?? "form.submit") }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "form-step-navigation", children: [
-      activeVisibleIndex > 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
-        "button",
-        {
-          className: "btn-prev",
-          type: "button",
-          onClick: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
-          children: form.translate("form.back")
-        }
-      ) : null,
-      activeVisibleIndex < visiblePageIndexes.length - 1 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "btn-next", type: "button", onClick: handleNext, children: form.translate("form.next") }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "fe-submit", type: "submit", disabled: form.isSubmitting, children: form.translate(form.schema.submitLabelKey ?? "form.submit") })
+    validationIssues.length === 0 ? null : slots.renderValidationSummary?.({ issues: validationIssues }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-validation-summary", role: "alert", children: [
+      validationIssues.length,
+      " validation error",
+      validationIssues.length === 1 ? "" : "s",
+      "."
+    ] }),
+    pages === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+      slots.renderNavigation?.({
+        currentPage: 0,
+        totalPages: 1,
+        canPrev: false,
+        canNext: false,
+        onPrev: () => void 0,
+        onNext: () => void 0
+      }),
+      renderSubmitButton()
+    ] }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "form-step-navigation", children: [
+      slots.renderNavigation?.({
+        currentPage: activeVisibleIndex,
+        totalPages: visiblePageIndexes.length,
+        canPrev,
+        canNext,
+        onPrev: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
+        onNext: handleNext
+      }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+        canPrev ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          "button",
+          {
+            className: "btn-prev",
+            type: "button",
+            onClick: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
+            children: form.translate("form.back")
+          }
+        ) : null,
+        canNext ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("button", { className: "btn-next", type: "button", onClick: handleNext, children: form.translate("form.next") }) : null
+      ] }),
+      canNext ? null : renderSubmitButton()
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-status", "aria-live": "polite", children: [
-      form.submitStatus === "success" && successMessageKey !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { role: "status", children: form.translate(successMessageKey) }) : null,
+      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 === "error" && form.submitError !== null && errorMessageKey !== void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { role: "alert", children: form.translate(errorMessageKey) }) : null
     ] })
   ] });
 }
+var RENDERER_MESSAGES = {
+  "form.submit": "Submit",
+  "form.back": "Back",
+  "form.next": "Next",
+  "form.step": "Step {{current}} / {{total}}",
+  "form.draftRestored": "Draft restored",
+  "validation.required": "This field is required."
+};
+var defaultRendererTranslator = {
+  translate(key, _locale, params = {}) {
+    return (RENDERER_MESSAGES[key] ?? key).replace(
+      /\{\{(\w+)\}\}/g,
+      (token, name) => Object.hasOwn(params, name) ? String(params[name]) : token
+    );
+  }
+};
+function FormRenderer(props) {
+  if (!("schema" in props)) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ContextFormRenderer, { ...props });
+  const {
+    schema,
+    locale = schema.defaultLocale ?? "en",
+    translator = defaultRendererTranslator,
+    initialValues,
+    resetOnSuccess,
+    onSubmit,
+    ...rendererProps
+  } = props;
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    FormProvider,
+    {
+      schema,
+      locale,
+      translator,
+      onSubmit,
+      ...initialValues === void 0 ? {} : { initialValues },
+      ...resetOnSuccess === void 0 ? {} : { resetOnSuccess },
+      children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ContextFormRenderer, { ...rendererProps })
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FormBuilder,
   FormProvider,
   FormRenderer,
   useField,
-  useForm
+  useForm,
+  useFormBuilder
 });