@form-engine-ts/react 1.1.0 → 2.1.0

package/dist/index.js

@@ -1,9 +1,620 @@
 // src/builder.tsx
 import {
-  populateSchemaTranslations,
-  sanitizeSchema
+  populateSchemaTranslations
 } from "@form-engine-ts/core";
 import { useState } from "react";
+
+// src/hooks/useFormBuilder.ts
+import {
+  transformFieldType,
+  validateFormSchema
+} from "@form-engine-ts/core";
+import { useCallback, useMemo } from "react";
+var DEFAULT_PREFIXES = { field: "q", option: "opt", page: "page" };
+var CHOICE_TYPES = ["select", "radio", "multi-select"];
+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 defaultCreateField(type, id) {
+  const base = { id, title: "New question", required: false };
+  if (type === "text" || type === "textarea" || type === "number" || type === "checkbox") return { ...base, type };
+  if (type === "rating") return { ...base, type, min: 1, max: 5 };
+  return { ...base, type, options: [] };
+}
+function defaultCreateOption(field, id) {
+  return { id, label: `Option ${"options" in field ? field.options.length + 1 : 1}` };
+}
+function defaultCreatePage(id, questionIds) {
+  return { id, title: "New page", questionIds };
+}
+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 withoutDisplayCondition(field) {
+  const { displayCondition: _displayCondition, ...rest } = field;
+  return rest;
+}
+function removeLocalizedProperty(translations, locale, property) {
+  const current = translations?.[locale];
+  if (current === void 0) return translations;
+  const { [property]: _removed, ...remaining } = current;
+  return { ...translations, [locale]: remaining };
+}
+function setTranslationMetadata(node, locale, property, metadata, remove) {
+  const localeMetadata = node.translationMetadata?.[locale];
+  if (metadata === void 0 && !remove) return node;
+  const nextLocaleMetadata = remove ? Object.fromEntries(Object.entries(localeMetadata ?? {}).filter(([key]) => key !== property)) : { ...localeMetadata, [property]: metadata ?? {} };
+  return { ...node, translationMetadata: { ...node.translationMetadata, [locale]: nextLocaleMetadata } };
+}
+function failedId(kind, result) {
+  return { success: false, error: result.error ?? { type: "invalid_id", kind, id: "" } };
+}
+function useFormBuilder({
+  schema,
+  onChange,
+  policy,
+  idFactory = defaultIdFactory,
+  factories = {}
+}) {
+  const createId = useCallback(
+    (kind, existingIds) => {
+      const rawId = idFactory(kind, existingIds);
+      const id = rawId.trim();
+      return id.length > 0 && !existingIds.has(id) ? { id } : { error: { type: "invalid_id", kind, id: rawId } };
+    },
+    [idFactory]
+  );
+  const textPolicyError = useCallback(
+    (text) => policy?.maxTextLength !== void 0 && text.length > policy.maxTextLength ? { success: false, error: { type: "max_text_length_exceeded", max: policy.maxTextLength } } : void 0,
+    [policy?.maxTextLength]
+  );
+  const updateField = useCallback(
+    (fieldId, updater) => {
+      const current = schema.fields.find((field) => field.id === fieldId);
+      if (current === void 0)
+        return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      const updated = updater(current);
+      if (updated.id !== fieldId)
+        return { success: false, error: { type: "invalid_id", kind: "field", id: updated.id } };
+      if (policy?.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(updated.type))
+        return { success: false, error: { type: "disallowed_field_type", fieldType: updated.type } };
+      for (const text of [updated.title, updated.description]) {
+        if (text !== void 0) {
+          const error = textPolicyError(text);
+          if (error !== void 0) return error;
+        }
+      }
+      onChange({ ...schema, fields: schema.fields.map((field) => field.id === fieldId ? updated : field) });
+      return { success: true };
+    },
+    [onChange, policy?.allowedFieldTypes, schema, textPolicyError]
+  );
+  const updateOption = useCallback(
+    (fieldId, optionId, updater) => {
+      const field = schema.fields.find((candidate) => candidate.id === fieldId);
+      if (field === void 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (!("options" in field))
+        return { success: false, error: { type: "invalid_operation", message: `Field ${fieldId} has no options.` } };
+      const current = field.options.find((option) => option.id === optionId);
+      if (current === void 0)
+        return { success: false, error: { type: "node_not_found", kind: "option", id: optionId } };
+      const updated = updater(current);
+      if (updated.id !== optionId)
+        return { success: false, error: { type: "invalid_id", kind: "option", id: updated.id } };
+      const error = textPolicyError(updated.label);
+      if (error !== void 0) return error;
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (candidate) => candidate.id === fieldId && "options" in candidate ? {
+            ...candidate,
+            options: candidate.options.map((option) => option.id === optionId ? updated : option)
+          } : candidate
+        )
+      });
+      return { success: true };
+    },
+    [onChange, schema, textPolicyError]
+  );
+  const updatePage = useCallback(
+    (pageId, updater) => {
+      const page = schema.pages?.find((candidate) => candidate.id === pageId);
+      if (page === void 0) return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const pages = schema.pages;
+      if (pages === void 0) return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const updated = updater(page);
+      if (updated.id !== pageId) return { success: false, error: { type: "invalid_id", kind: "page", id: updated.id } };
+      onChange({ ...schema, pages: pages.map((candidate) => candidate.id === pageId ? updated : candidate) });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const addField = 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 } };
+      if (pageId !== void 0 && !schema.pages?.some((page) => page.id === pageId))
+        return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const fieldIds = new Set(schema.fields.map((field2) => field2.id));
+      const fieldId = createId("field", fieldIds);
+      if (fieldId.id === void 0) return failedId("field", fieldId);
+      let field = (factories.createField ?? defaultCreateField)(type, fieldId.id);
+      if (field.id !== fieldId.id || field.type !== type || fieldIds.has(field.id))
+        return { success: false, error: { type: "invalid_id", kind: "field", id: field.id } };
+      if (CHOICE_TYPES.includes(type) && "options" in field && field.options.length === 0) {
+        const optionIds = new Set(
+          schema.fields.flatMap((item) => "options" in item ? item.options.map((option2) => option2.id) : [])
+        );
+        const optionId = createId("option", optionIds);
+        if (optionId.id === void 0) return failedId("option", optionId);
+        const option = (factories.createOption ?? defaultCreateOption)(field, optionId.id);
+        if (option.id !== optionId.id || optionIds.has(option.id))
+          return { success: false, error: { type: "invalid_id", kind: "option", id: option.id } };
+        field = { ...field, options: [option] };
+      }
+      const pages = schema.pages?.map((page, index) => ({
+        ...page,
+        questionIds: page.id === pageId || pageId === void 0 && index === (schema.pages?.length ?? 0) - 1 ? [...page.questionIds, field.id] : page.questionIds
+      }));
+      onChange({ ...schema, fields: [...schema.fields, field], ...pages === void 0 ? {} : { pages } });
+      return { success: true };
+    },
+    [createId, factories, onChange, policy, schema]
+  );
+  const removeField = useCallback(
+    (fieldId) => {
+      if (!schema.fields.some((field) => field.id === fieldId))
+        return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (schema.fields.length <= 1)
+        return { success: false, error: { type: "invalid_operation", message: "A form must contain one field." } };
+      const fields = schema.fields.filter((field) => field.id !== fieldId).map((field) => field.displayCondition?.questionId === fieldId ? withoutDisplayCondition(field) : field);
+      const pages = schema.pages?.map((page) => ({ ...page, questionIds: page.questionIds.filter((id) => id !== fieldId) })).filter((page) => page.questionIds.length > 0);
+      if (schema.pages !== void 0 && pages?.length === 0) {
+        const { pages: _pages, ...single } = schema;
+        onChange({ ...single, fields });
+      } else onChange({ ...schema, fields, ...pages === void 0 ? {} : { pages } });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const moveField = useCallback(
+    (fieldId, targetIndex) => {
+      const sourceIndex = schema.fields.findIndex((field) => field.id === fieldId);
+      if (sourceIndex < 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      const fields = move(schema.fields, sourceIndex, targetIndex);
+      if (fields === void 0)
+        return { success: false, error: { type: "invalid_operation", message: "Invalid field position." } };
+      const indexById = new Map(fields.map((field, index) => [field.id, index]));
+      onChange({
+        ...schema,
+        fields: fields.map((field, index) => {
+          const source = field.displayCondition?.questionId;
+          return source === void 0 || (indexById.get(source) ?? index) < index ? field : withoutDisplayCondition(field);
+        })
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const addOption = useCallback(
+    (fieldId) => {
+      const field = schema.fields.find((candidate) => candidate.id === fieldId);
+      if (field === void 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (!("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 ids = new Set(
+        schema.fields.flatMap((item) => "options" in item ? item.options.map((option2) => option2.id) : [])
+      );
+      const id = createId("option", ids);
+      if (id.id === void 0) return failedId("option", id);
+      const option = (factories.createOption ?? defaultCreateOption)(field, id.id);
+      if (option.id !== id.id || ids.has(option.id))
+        return { success: false, error: { type: "invalid_id", kind: "option", id: option.id } };
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (item) => item.id === fieldId && "options" in item ? { ...item, options: [...item.options, option] } : item
+        )
+      });
+      return { success: true };
+    },
+    [createId, factories.createOption, onChange, policy?.maxOptionsPerField, schema]
+  );
+  const removeOption = useCallback(
+    (fieldId, optionId) => {
+      const field = schema.fields.find((item) => item.id === fieldId);
+      if (field === void 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (!("options" in field) || !field.options.some((option) => option.id === optionId))
+        return { success: false, error: { type: "node_not_found", kind: "option", id: optionId } };
+      if (field.options.length <= 1)
+        return { success: false, error: { type: "invalid_operation", message: "A choice field needs one option." } };
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (item) => item.id === fieldId && "options" in item ? { ...item, options: item.options.filter((option) => option.id !== optionId) } : item
+        )
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const moveOption = useCallback(
+    (fieldId, optionId, targetIndex) => {
+      const field = schema.fields.find((item) => item.id === fieldId);
+      if (field === void 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (!("options" in field))
+        return { success: false, error: { type: "invalid_operation", message: `Field ${fieldId} has no options.` } };
+      const options = move(
+        field.options,
+        field.options.findIndex((option) => option.id === optionId),
+        targetIndex
+      );
+      if (options === void 0)
+        return { success: false, error: { type: "invalid_operation", message: "Invalid option position." } };
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (item) => item.id === fieldId && "options" in item ? { ...item, options } : item
+        )
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const changeFieldType = useCallback(
+    (fieldId, type) => {
+      const field = schema.fields.find((item) => item.id === fieldId);
+      if (field === void 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (policy?.allowedFieldTypes !== void 0 && !policy.allowedFieldTypes.includes(type))
+        return { success: false, error: { type: "disallowed_field_type", fieldType: type } };
+      let transformed = transformFieldType(field, type);
+      if (CHOICE_TYPES.includes(type) && !("options" in field) && "options" in transformed) {
+        const ids = new Set(
+          schema.fields.flatMap((item) => "options" in item ? item.options.map((option2) => option2.id) : [])
+        );
+        const id = createId("option", ids);
+        if (id.id === void 0) return failedId("option", id);
+        const option = (factories.createOption ?? defaultCreateOption)(transformed, id.id);
+        if (option.id !== id.id || ids.has(option.id))
+          return { success: false, error: { type: "invalid_id", kind: "option", id: option.id } };
+        transformed = { ...transformed, options: [option] };
+      }
+      onChange({ ...schema, fields: schema.fields.map((item) => item.id === fieldId ? transformed : item) });
+      return { success: true };
+    },
+    [createId, factories.createOption, onChange, policy?.allowedFieldTypes, schema]
+  );
+  const addPage = useCallback(
+    (questionId) => {
+      const ids = new Set(schema.pages?.map((page2) => page2.id) ?? []);
+      const id = createId("page", ids);
+      if (id.id === void 0) return failedId("page", id);
+      const questionIds = schema.pages === void 0 ? schema.fields.map((field) => field.id) : [questionId ?? schema.pages.find((page2) => page2.questionIds.length > 1)?.questionIds.at(-1)].filter(
+        (value) => value !== void 0
+      );
+      if (questionIds.length === 0)
+        return { success: false, error: { type: "invalid_operation", message: "No question can be moved." } };
+      const source = schema.pages?.find((page2) => page2.questionIds.includes(questionIds[0] ?? ""));
+      if (schema.pages !== void 0 && (source === void 0 || source.questionIds.length <= 1))
+        return { success: false, error: { type: "invalid_operation", message: "A page cannot be left empty." } };
+      const page = (factories.createPage ?? defaultCreatePage)(id.id, [...questionIds]);
+      if (page.id !== id.id || ids.has(page.id))
+        return { success: false, error: { type: "invalid_id", kind: "page", id: page.id } };
+      const pages = schema.pages === void 0 ? [page] : [
+        ...schema.pages.map((item) => ({
+          ...item,
+          questionIds: item.questionIds.filter((fieldId) => !questionIds.includes(fieldId))
+        })),
+        page
+      ];
+      onChange({ ...schema, pages });
+      return { success: true };
+    },
+    [createId, factories.createPage, onChange, schema]
+  );
+  const removePage = useCallback(
+    (pageId) => {
+      const index = schema.pages?.findIndex((page) => page.id === pageId) ?? -1;
+      const removed = schema.pages?.[index];
+      if (removed === void 0) return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const currentPages = schema.pages;
+      if (currentPages === void 0)
+        return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      if ((schema.pages?.length ?? 0) === 1) {
+        const { pages: _pages, ...single } = schema;
+        onChange(single);
+        return { success: true };
+      }
+      const targetIndex = index === 0 ? 1 : index - 1;
+      onChange({
+        ...schema,
+        pages: currentPages.map(
+          (page, pageIndex) => pageIndex === targetIndex ? { ...page, questionIds: [...page.questionIds, ...removed.questionIds] } : page
+        ).filter((page) => page.id !== pageId)
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const movePage = useCallback(
+    (pageId, targetIndex) => {
+      const sourceIndex = schema.pages?.findIndex((page) => page.id === pageId) ?? -1;
+      if (sourceIndex < 0) return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const pages = move(schema.pages ?? [], sourceIndex, targetIndex);
+      if (pages === void 0)
+        return { success: false, error: { type: "invalid_operation", message: "Invalid page position." } };
+      const assignment = new Map(pages.flatMap((page, index) => page.questionIds.map((id) => [id, index])));
+      onChange({
+        ...schema,
+        pages: pages.map((page, index) => {
+          const source = page.displayCondition?.questionId;
+          if (source === void 0 || (assignment.get(source) ?? index) < index) return page;
+          const { displayCondition: _condition, ...rest } = page;
+          return rest;
+        })
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const assignFieldToPage = useCallback(
+    (fieldId, pageId) => {
+      if (!schema.fields.some((field) => field.id === fieldId))
+        return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (pageId === null) {
+        if (schema.pages !== void 0) {
+          const { pages: _pages, ...single } = schema;
+          onChange(single);
+        }
+        return { success: true };
+      }
+      if (!schema.pages?.some((page) => page.id === pageId))
+        return { success: false, error: { type: "node_not_found", kind: "page", id: pageId } };
+      const pages = schema.pages.map((page) => ({
+        ...page,
+        questionIds: page.id === pageId ? schema.fields.filter((field) => page.questionIds.includes(field.id) || field.id === fieldId).map((field) => field.id) : page.questionIds.filter((id) => id !== fieldId)
+      })).filter((page) => page.questionIds.length > 0);
+      onChange({ ...schema, pages });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const setDisplayCondition = useCallback(
+    (fieldId, condition) => {
+      const index = schema.fields.findIndex((field) => field.id === fieldId);
+      if (index < 0) return { success: false, error: { type: "node_not_found", kind: "field", id: fieldId } };
+      if (condition !== void 0) {
+        const sourceIndex = schema.fields.findIndex((field) => field.id === condition.questionId);
+        if (sourceIndex < 0 || sourceIndex >= index)
+          return {
+            success: false,
+            error: { type: "invalid_operation", message: "Conditions require an earlier field." }
+          };
+      }
+      onChange({
+        ...schema,
+        fields: schema.fields.map(
+          (field) => field.id !== fieldId ? field : condition === void 0 ? withoutDisplayCondition(field) : { ...field, displayCondition: condition }
+        )
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const setSourceText = useCallback(
+    (target, property, text) => {
+      const error = textPolicyError(text);
+      if (error !== void 0) return error;
+      if (target.kind === "form") {
+        if (!["title", "description", "completionMessage"].includes(property))
+          return {
+            success: false,
+            error: { type: "invalid_operation", message: `Unsupported form property: ${property}` }
+          };
+        if (property === "title") onChange({ ...schema, title: text });
+        else if (property === "description") {
+          const { description: _description, ...withoutDescription } = schema;
+          onChange(text.length === 0 ? withoutDescription : { ...schema, description: text });
+        } else {
+          const { completionMessage: _completionMessage, ...withoutCompletionMessage } = schema;
+          onChange(text.length === 0 ? withoutCompletionMessage : { ...schema, completionMessage: text });
+        }
+        return { success: true };
+      }
+      if (target.id === void 0)
+        return { success: false, error: { type: "invalid_operation", message: "A target ID is required." } };
+      if (target.kind === "field") {
+        if (!["title", "description"].includes(property))
+          return {
+            success: false,
+            error: { type: "invalid_operation", message: `Unsupported field property: ${property}` }
+          };
+        return updateField(target.id, (field) => {
+          if (property === "title") return { ...field, title: text };
+          const { description: _description, ...withoutDescription } = field;
+          return text.length === 0 ? withoutDescription : { ...field, description: text };
+        });
+      }
+      if (target.kind === "option") {
+        if (property !== "label")
+          return {
+            success: false,
+            error: { type: "invalid_operation", message: `Unsupported option property: ${property}` }
+          };
+        for (const field of schema.fields)
+          if ("options" in field && field.options.some((option) => option.id === target.id))
+            return updateOption(field.id, target.id, (option) => ({ ...option, label: text }));
+        return { success: false, error: { type: "node_not_found", kind: "option", id: target.id } };
+      }
+      if (!["title", "description"].includes(property))
+        return {
+          success: false,
+          error: { type: "invalid_operation", message: `Unsupported page property: ${property}` }
+        };
+      return updatePage(target.id, (page) => {
+        if (property === "title") {
+          const { title: _title, ...withoutTitle } = page;
+          return text.length === 0 ? withoutTitle : { ...page, title: text };
+        }
+        const { description: _description, ...withoutDescription } = page;
+        return text.length === 0 ? withoutDescription : { ...page, description: text };
+      });
+    },
+    [onChange, schema, textPolicyError, updateField, updateOption, updatePage]
+  );
+  const setLocaleTranslation = useCallback(
+    (locale, target, property, text, options = {}) => {
+      const normalized = locale.trim();
+      if (normalized.length === 0)
+        return { success: false, error: { type: "invalid_operation", message: "Locale must not be empty." } };
+      const error = textPolicyError(text);
+      if (error !== void 0) return error;
+      const supportedLocales = [.../* @__PURE__ */ new Set([...schema.supportedLocales ?? [], normalized])];
+      const remove = text.length === 0;
+      if (target.kind === "form") {
+        if (!["title", "description", "completionMessage"].includes(property))
+          return {
+            success: false,
+            error: { type: "invalid_operation", message: `Unsupported form property: ${property}` }
+          };
+        const key = property;
+        const translations = remove ? removeLocalizedProperty(schema.translations, normalized, key) : { ...schema.translations, [normalized]: { ...schema.translations?.[normalized], [key]: text } };
+        onChange(
+          setTranslationMetadata(
+            { ...schema, supportedLocales, ...translations === void 0 ? {} : { translations } },
+            normalized,
+            property,
+            options.metadata,
+            remove
+          )
+        );
+        return { success: true };
+      }
+      if (target.id === void 0)
+        return { success: false, error: { type: "invalid_operation", message: "A target ID is required." } };
+      let found = false;
+      const fields = schema.fields.map((field) => {
+        if (target.kind === "field" && field.id === target.id && ["title", "description"].includes(property)) {
+          found = true;
+          const key = property;
+          const translations = remove ? removeLocalizedProperty(field.translations, normalized, key) : { ...field.translations, [normalized]: { ...field.translations?.[normalized], [key]: text } };
+          return setTranslationMetadata(
+            { ...field, ...translations === void 0 ? {} : { translations } },
+            normalized,
+            property,
+            options.metadata,
+            remove
+          );
+        }
+        if (target.kind !== "option" || property !== "label" || !("options" in field)) return field;
+        return {
+          ...field,
+          options: field.options.map((option) => {
+            if (option.id !== target.id) return option;
+            found = true;
+            const translations = remove ? Object.fromEntries(Object.entries(option.translations ?? {}).filter(([key]) => key !== normalized)) : { ...option.translations, [normalized]: text };
+            return setTranslationMetadata({ ...option, translations }, normalized, property, options.metadata, remove);
+          })
+        };
+      });
+      const pages = schema.pages?.map((page) => {
+        if (target.kind !== "page" || page.id !== target.id || !["title", "description"].includes(property))
+          return page;
+        found = true;
+        const key = property;
+        const translations = remove ? removeLocalizedProperty(page.translations, normalized, key) : { ...page.translations, [normalized]: { ...page.translations?.[normalized], [key]: text } };
+        return setTranslationMetadata(
+          { ...page, ...translations === void 0 ? {} : { translations } },
+          normalized,
+          property,
+          options.metadata,
+          remove
+        );
+      });
+      if (!found) return { success: false, error: { type: "node_not_found", kind: target.kind, id: target.id } };
+      onChange({ ...schema, supportedLocales, fields, ...pages === void 0 ? {} : { pages } });
+      return { success: true };
+    },
+    [onChange, schema, textPolicyError]
+  );
+  const addLocale = useCallback(
+    (locale) => {
+      const normalized = locale.trim();
+      if (normalized.length === 0)
+        return { success: false, error: { type: "invalid_operation", message: "Locale must not be empty." } };
+      onChange({
+        ...schema,
+        supportedLocales: [
+          .../* @__PURE__ */ new Set([
+            ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+            ...schema.supportedLocales ?? [],
+            normalized
+          ])
+        ]
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const setDefaultLocale = useCallback(
+    (locale) => {
+      const normalized = locale.trim();
+      if (normalized.length === 0)
+        return { success: false, error: { type: "invalid_operation", message: "Locale must not be empty." } };
+      onChange({
+        ...schema,
+        defaultLocale: normalized,
+        supportedLocales: [.../* @__PURE__ */ new Set([normalized, ...schema.supportedLocales ?? []])]
+      });
+      return { success: true };
+    },
+    [onChange, schema]
+  );
+  const validationIssues = useMemo(() => {
+    const result = validateFormSchema(schema, policy === void 0 ? {} : { policy });
+    return result.valid ? [] : result.issues;
+  }, [policy, schema]);
+  return {
+    schema,
+    addField,
+    removeField,
+    moveField,
+    updateField,
+    changeFieldType,
+    addOption,
+    updateOption,
+    removeOption,
+    moveOption,
+    addPage,
+    updatePage,
+    removePage,
+    movePage,
+    assignFieldToPage,
+    setDisplayCondition,
+    setSourceText,
+    setLocaleTranslation,
+    addLocale,
+    setDefaultLocale,
+    validationIssues
+  };
+}
+
+// src/builder.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var FIELD_TYPES = [
   "text",
@@ -24,6 +635,7 @@ var BUILDER_DEFAULTS = {
   "builder.questionTitle": "\u8CEA\u554F\u6587 / Question Title",
   "builder.questionTitlePlaceholder": "Example: Tell us what we could improve",
   "builder.newQuestionTitle": "New question",
+  "builder.completionMessage": "Completion message",
   "builder.type": "Type",
   "builder.required": "Required",
   "builder.minimum": "Minimum",
@@ -82,33 +694,6 @@ function fieldTypeKey(type) {
 function operatorKey(operator) {
   return `builder.operator.${operator}`;
 }
-function createUniqueId(prefix, existingIds) {
-  let id;
-  do {
-    id = `${prefix}_${globalThis.crypto.randomUUID().slice(0, 8)}`;
-  } while (existingIds.has(id));
-  return id;
-}
-function baseField(field, type) {
-  return {
-    id: field.id,
-    type,
-    title: field.title,
-    ...field.description === void 0 ? {} : { description: field.description },
-    ...field.translationKey === void 0 ? {} : { translationKey: field.translationKey },
-    required: field.required,
-    ...field.displayCondition === void 0 ? {} : { displayCondition: field.displayCondition }
-  };
-}
-function normalizeField(field, type, newOptionLabel) {
-  const base = baseField(field, type);
-  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 };
-  const options = "options" in field && field.options.length > 0 ? field.options : [{ id: createUniqueId("opt", /* @__PURE__ */ new Set()), label: newOptionLabel }];
-  return { ...base, type, options };
-}
 function defaultConditionValue(field) {
   if (field.type === "checkbox") return true;
   if (field.type === "number" || field.type === "rating") return field.min ?? 1;
@@ -122,30 +707,6 @@ function conditionOperators(field) {
   }
   return ["equals", "not_equals", "not_empty"];
 }
-function withoutDisplayCondition(field) {
-  const { displayCondition: _displayCondition, ...rest } = field;
-  return rest;
-}
-function sanitizeBuilderSchema(schema) {
-  const sanitized = 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;
-    if (sourceId === void 0) return field;
-    const sourceIndex = indexById.get(sourceId);
-    return sourceIndex !== void 0 && sourceIndex < index ? field : withoutDisplayCondition(field);
-  });
-  return {
-    ...sanitized,
-    fields,
-    ...sanitized.pages === void 0 ? {} : {
-      pages: sanitized.pages.map((page) => ({
-        ...page,
-        questionIds: fields.filter((field) => page.questionIds.includes(field.id)).map((field) => field.id)
-      }))
-    }
-  };
-}
 function conditionWithValue(questionId, operator, value) {
   return operator === "not_empty" ? { questionId, operator } : { questionId, operator, value };
 }
@@ -187,7 +748,25 @@ function ConditionValueEditor({
     }
   );
 }
-function FormBuilder({ schema, onChange, locale = "en", translator, translationAdapter }) {
+function FormBuilder({
+  schema,
+  onChange,
+  locale = "en",
+  translator,
+  translationAdapter,
+  translationOptions,
+  onTranslationReport,
+  policy,
+  idFactory,
+  factories
+}) {
+  const headless = useFormBuilder({
+    schema,
+    onChange,
+    ...policy === void 0 ? {} : { policy },
+    ...idFactory === void 0 ? {} : { idFactory },
+    ...factories === void 0 ? {} : { factories }
+  });
   const [newPageQuestionId, setNewPageQuestionId] = useState("");
   const [newLocale, setNewLocale] = useState("");
   const [editingLocale, setEditingLocale] = useState("");
@@ -197,67 +776,17 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     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 changeType = (fieldId, type) => {
-    emitSchema({
-      ...schema,
-      fields: schema.fields.map((field) => {
-        if (field.id === fieldId) {
-          return normalizeField(field, type, translate("builder.newOptionLabel", { index: 1 }));
-        }
-        if (field.displayCondition?.questionId === fieldId) {
-          const { displayCondition: _condition, ...withoutCondition } = field;
-          return withoutCondition;
-        }
-        return field;
-      })
-    });
-  };
-  const removeField = (fieldId) => {
-    if (schema.fields.length === 1) return;
-    emitSchema({ ...schema, fields: schema.fields.filter((field) => field.id !== fieldId) });
-  };
+  const updateField = headless.updateField;
+  const changeType = headless.changeFieldType;
+  const removeField = headless.removeField;
   const moveField = (index, offset) => {
     const target = index + offset;
-    if (target < 0 || target >= schema.fields.length) return;
-    const fields = [...schema.fields];
-    const current = fields[index];
-    const other = fields[target];
-    if (current === void 0 || other === void 0) return;
-    fields[index] = other;
-    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 field = schema.fields[index];
+    if (field !== void 0) headless.moveField(field.id, target);
   };
+  const addField = () => headless.addField("text");
   const enablePages = () => {
-    if (schema.pages !== void 0) return;
-    emitSchema({
-      ...schema,
-      pages: [
-        {
-          id: createUniqueId("page", /* @__PURE__ */ new Set()),
-          title: translate("builder.newPage"),
-          questionIds: schema.fields.map((field) => field.id)
-        }
-      ]
-    });
+    if (schema.pages === void 0) headless.addPage();
   };
   const pageForField = (fieldId) => schema.pages?.find((page) => page.questionIds.includes(fieldId));
   const movablePageQuestions = schema.pages?.flatMap((page) => page.questionIds.length > 1 ? page.questionIds : []) ?? [];
@@ -268,73 +797,28 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     }
     const questionId = movablePageQuestions.includes(newPageQuestionId) ? newPageQuestionId : movablePageQuestions[0];
     if (questionId === void 0) return;
-    const pageId = createUniqueId("page", new Set(schema.pages.map((page) => page.id)));
-    emitSchema({
-      ...schema,
-      pages: [
-        ...schema.pages.map((page) => ({
-          ...page,
-          questionIds: page.questionIds.filter((id) => id !== questionId)
-        })),
-        { id: pageId, title: translate("builder.newPage"), questionIds: [questionId] }
-      ]
-    });
+    headless.addPage(questionId);
     setNewPageQuestionId("");
   };
   const removePage = (pageIndex) => {
-    if (schema.pages === void 0) return;
-    const removed = schema.pages[pageIndex];
-    if (removed === void 0) return;
-    if (schema.pages.length === 1) {
-      const { pages: _pages, ...singlePage } = schema;
-      emitSchema(singlePage);
-      return;
-    }
-    const targetIndex = pageIndex === 0 ? 1 : pageIndex - 1;
-    emitSchema({
-      ...schema,
-      pages: schema.pages.map(
-        (page, index) => index === targetIndex ? { ...page, questionIds: [...page.questionIds, ...removed.questionIds] } : page
-      ).filter((_page, index) => index !== pageIndex)
-    });
+    const page = schema.pages?.[pageIndex];
+    if (page !== void 0) headless.removePage(page.id);
   };
   const movePage = (pageIndex, offset) => {
-    if (schema.pages === void 0) return;
     const target = pageIndex + offset;
-    if (target < 0 || target >= schema.pages.length) return;
-    const pages = [...schema.pages];
-    const current = pages[pageIndex];
-    const other = pages[target];
-    if (current === void 0 || other === void 0) return;
-    pages[pageIndex] = other;
-    pages[target] = current;
-    emitSchema({ ...schema, pages });
+    const page = schema.pages?.[pageIndex];
+    if (page !== void 0) headless.movePage(page.id, target);
   };
   const updatePage = (pageId, update) => {
-    if (schema.pages === void 0) return;
-    emitSchema({ ...schema, pages: schema.pages.map((page) => page.id === pageId ? update(page) : page) });
+    headless.updatePage(pageId, update);
   };
   const assignFieldToPage = (fieldId, pageId) => {
-    if (schema.pages === void 0) return;
-    emitSchema({
-      ...schema,
-      pages: schema.pages.map((page) => ({
-        ...page,
-        questionIds: page.id === pageId ? schema.fields.filter((field) => page.questionIds.includes(field.id) || field.id === fieldId).map((field) => field.id) : page.questionIds.filter((id) => id !== fieldId)
-      })).filter((page) => page.questionIds.length > 0)
-    });
+    headless.assignFieldToPage(fieldId, pageId);
   };
   const addLocale = () => {
     const normalized = newLocale.trim();
     if (normalized.length === 0) return;
-    const supportedLocales = [
-      .../* @__PURE__ */ new Set([
-        ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-        ...schema.supportedLocales ?? [],
-        normalized
-      ])
-    ];
-    emitSchema({ ...schema, supportedLocales });
+    headless.addLocale(normalized);
     setEditingLocale(normalized);
     setNewLocale("");
   };
@@ -343,7 +827,14 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     setIsTranslating(true);
     setTranslationError(null);
     try {
-      onChange(await populateSchemaTranslations(schema, [editingLocale], translationAdapter));
+      const populated = await populateSchemaTranslations(
+        schema,
+        [editingLocale],
+        translationAdapter,
+        translationOptions ?? { overwrite: "all" }
+      );
+      onChange(populated.schema);
+      onTranslationReport?.(populated.report);
     } catch (cause) {
       setTranslationError(cause instanceof Error ? cause.message : String(cause));
     } finally {
@@ -352,18 +843,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
   };
   const updateFormTranslation = (key, value) => {
     if (editingLocale.length === 0) return;
-    const current = schema.translations?.[editingLocale];
-    const next = key === "title" ? value.length === 0 ? { description: current?.description } : { ...current, title: value } : value.length === 0 ? { title: current?.title } : { ...current, description: value };
-    emitSchema({
-      ...schema,
-      translations: {
-        ...schema.translations,
-        [editingLocale]: {
-          ...next.title === void 0 ? {} : { title: next.title },
-          ...next.description === void 0 ? {} : { description: next.description }
-        }
-      }
-    });
+    headless.setLocaleTranslation(editingLocale, { kind: "form" }, key, value);
   };
   return /* @__PURE__ */ jsxs("section", { className: "form-engine-builder", "aria-label": translate("builder.formBuilder"), children: [
     /* @__PURE__ */ jsxs("section", { className: "form-engine-builder__pages", "aria-labelledby": "builder-pages-heading", children: [
@@ -443,19 +923,12 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                     "input",
                     {
                       value: page.translations?.[editingLocale]?.title ?? "",
-                      onChange: (event) => {
-                        const value = event.currentTarget.value;
-                        updatePage(page.id, (current) => ({
-                          ...current,
-                          translations: {
-                            ...current.translations,
-                            [editingLocale]: {
-                              ...value.length === 0 ? {} : { title: value },
-                              ...current.translations?.[editingLocale]?.description === void 0 ? {} : { description: current.translations[editingLocale]?.description }
-                            }
-                          }
-                        }));
-                      }
+                      onChange: (event) => headless.setLocaleTranslation(
+                        editingLocale,
+                        { kind: "page", id: page.id },
+                        "title",
+                        event.currentTarget.value
+                      )
                     }
                   )
                 ] }),
@@ -465,19 +938,12 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                     "input",
                     {
                       value: page.translations?.[editingLocale]?.description ?? "",
-                      onChange: (event) => {
-                        const value = event.currentTarget.value;
-                        updatePage(page.id, (current) => ({
-                          ...current,
-                          translations: {
-                            ...current.translations,
-                            [editingLocale]: {
-                              ...current.translations?.[editingLocale]?.title === void 0 ? {} : { title: current.translations[editingLocale]?.title },
-                              ...value.length === 0 ? {} : { description: value }
-                            }
-                          }
-                        }));
-                      }
+                      onChange: (event) => headless.setLocaleTranslation(
+                        editingLocale,
+                        { kind: "page", id: page.id },
+                        "description",
+                        event.currentTarget.value
+                      )
                     }
                   )
                 ] })
@@ -565,6 +1031,16 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
     ] }),
     /* @__PURE__ */ jsxs("section", { className: "form-engine-builder__localization", "aria-labelledby": "builder-localization-heading", children: [
       /* @__PURE__ */ jsx("h2", { id: "builder-localization-heading", children: translate("builder.localization") }),
+      /* @__PURE__ */ jsxs("label", { children: [
+        translate("builder.completionMessage"),
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            value: schema.completionMessage ?? "",
+            onChange: (event) => headless.setSourceText({ kind: "form" }, "completionMessage", event.currentTarget.value)
+          }
+        )
+      ] }),
       /* @__PURE__ */ jsxs("div", { className: "form-engine-builder__grid", children: [
         /* @__PURE__ */ jsxs("label", { children: [
           translate("builder.defaultLocale"),
@@ -572,16 +1048,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
             "input",
             {
               value: schema.defaultLocale ?? "",
-              onChange: (event) => {
-                const value = event.currentTarget.value.trim();
-                emitSchema(
-                  value.length === 0 ? schema : {
-                    ...schema,
-                    defaultLocale: value,
-                    supportedLocales: [.../* @__PURE__ */ new Set([value, ...schema.supportedLocales ?? []])]
-                  }
-                );
-              }
+              onChange: (event) => headless.setDefaultLocale(event.currentTarget.value)
             }
           )
         ] }),
@@ -629,6 +1096,16 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
               onChange: (event) => updateFormTranslation("description", event.currentTarget.value)
             }
           )
+        ] }),
+        /* @__PURE__ */ jsxs("label", { children: [
+          translate("builder.completionMessage"),
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              value: schema.translations?.[editingLocale]?.completionMessage ?? "",
+              onChange: (event) => updateFormTranslation("completionMessage", event.currentTarget.value)
+            }
+          )
         ] })
       ] })
     ] }),
@@ -692,7 +1169,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__ */ 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__ */ jsx("option", { value: type, children: translate(fieldTypeKey(type)) }, type))
               }
             )
           ] }),
@@ -728,19 +1207,12 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                 "input",
                 {
                   value: field.translations?.[editingLocale]?.title ?? "",
-                  onChange: (event) => {
-                    const value = event.currentTarget.value;
-                    updateField(field.id, (current) => ({
-                      ...current,
-                      translations: {
-                        ...current.translations,
-                        [editingLocale]: {
-                          ...value.length === 0 ? {} : { title: value },
-                          ...current.translations?.[editingLocale]?.description === void 0 ? {} : { description: current.translations[editingLocale]?.description }
-                        }
-                      }
-                    }));
-                  }
+                  onChange: (event) => headless.setLocaleTranslation(
+                    editingLocale,
+                    { kind: "field", id: field.id },
+                    "title",
+                    event.currentTarget.value
+                  )
                 }
               )
             ] }),
@@ -750,19 +1222,12 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                 "input",
                 {
                   value: field.translations?.[editingLocale]?.description ?? "",
-                  onChange: (event) => {
-                    const value = event.currentTarget.value;
-                    updateField(field.id, (current) => ({
-                      ...current,
-                      translations: {
-                        ...current.translations,
-                        [editingLocale]: {
-                          ...current.translations?.[editingLocale]?.title === void 0 ? {} : { title: current.translations[editingLocale]?.title },
-                          ...value.length === 0 ? {} : { description: value }
-                        }
-                      }
-                    }));
-                  }
+                  onChange: (event) => headless.setLocaleTranslation(
+                    editingLocale,
+                    { kind: "field", id: field.id },
+                    "description",
+                    event.currentTarget.value
+                  )
                 }
               )
             ] })
@@ -776,26 +1241,12 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
               "input",
               {
                 value: option.translations?.[editingLocale] ?? "",
-                onChange: (event) => {
-                  const value = event.currentTarget.value;
-                  updateField(field.id, (current) => {
-                    if (!("options" in current)) return current;
-                    return {
-                      ...current,
-                      options: current.options.map(
-                        (candidate) => candidate.id === option.id ? {
-                          ...candidate,
-                          translations: Object.fromEntries([
-                            ...Object.entries(candidate.translations ?? {}).filter(
-                              ([localeKey]) => localeKey !== editingLocale
-                            ),
-                            ...value.length === 0 ? [] : [[editingLocale, value]]
-                          ])
-                        } : candidate
-                      )
-                    };
-                  });
-                }
+                onChange: (event) => headless.setLocaleTranslation(
+                  editingLocale,
+                  { kind: "option", id: option.id },
+                  "label",
+                  event.currentTarget.value
+                )
               }
             )
           ] }, option.id)) : null
@@ -847,17 +1298,10 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                 "aria-label": translate("builder.optionLabel", { index: optionIndex + 1 }),
                 value: option.label,
                 placeholder: translate("builder.optionLabelPlaceholder"),
-                onChange: (event) => updateField(field.id, (current) => {
-                  if (!("options" in current)) return current;
-                  const label = event.currentTarget.value;
-                  if (label.trim().length === 0) return current;
-                  return {
-                    ...current,
-                    options: current.options.map(
-                      (item, itemIndex) => itemIndex === optionIndex ? { ...item, label } : item
-                    )
-                  };
-                })
+                onChange: (event) => event.currentTarget.value.trim().length === 0 ? void 0 : headless.updateOption(field.id, option.id, (item) => ({
+                  ...item,
+                  label: event.currentTarget.value
+                }))
               }
             ),
             /* @__PURE__ */ jsx(
@@ -865,13 +1309,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")
               }
             )
@@ -880,22 +1318,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")
             }
           )
@@ -909,17 +1333,14 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                 value: condition?.questionId ?? "",
                 onChange: (event) => {
                   const selected = schema.fields.find((item) => item.id === event.currentTarget.value);
-                  updateField(field.id, (current) => {
-                    if (selected === void 0) {
-                      const { displayCondition: _condition, ...withoutCondition } = current;
-                      return withoutCondition;
-                    }
-                    const operator = conditionOperators(selected)[0] ?? "not_empty";
-                    return {
-                      ...current,
-                      displayCondition: conditionWithValue(selected.id, operator, defaultConditionValue(selected))
-                    };
-                  });
+                  headless.setDisplayCondition(
+                    field.id,
+                    selected === void 0 ? void 0 : conditionWithValue(
+                      selected.id,
+                      conditionOperators(selected)[0] ?? "not_empty",
+                      defaultConditionValue(selected)
+                    )
+                  );
                 },
                 children: [
                   /* @__PURE__ */ jsx("option", { value: "", children: translate("builder.alwaysVisible") }),
@@ -936,10 +1357,10 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
                 value: condition.operator,
                 onChange: (event) => {
                   const operator = event.currentTarget.value;
-                  updateField(field.id, (current) => ({
-                    ...current,
-                    displayCondition: conditionWithValue(source.id, operator, defaultConditionValue(source))
-                  }));
+                  headless.setDisplayCondition(
+                    field.id,
+                    conditionWithValue(source.id, operator, defaultConditionValue(source))
+                  );
                 },
                 children: conditionOperators(source).map((operator) => /* @__PURE__ */ jsx("option", { value: operator, children: translate(operatorKey(operator)) }, operator))
               }
@@ -949,7 +1370,7 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
               {
                 source,
                 condition,
-                onChange: (next) => updateField(field.id, (current) => ({ ...current, displayCondition: next })),
+                onChange: (next) => headless.setDisplayCondition(field.id, next),
                 translate
               }
             )
@@ -957,7 +1378,16 @@ function FormBuilder({ schema, onChange, locale = "en", translator, translationA
         ] })
       ] }, field.id);
     }) }),
-    /* @__PURE__ */ jsx("button", { className: "form-engine-builder__add", type: "button", onClick: addField, children: translate("builder.addQuestion") })
+    /* @__PURE__ */ 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")
+      }
+    )
   ] });
 }
 
@@ -971,7 +1401,7 @@ import {
   validateAnswers,
   validatePageAnswers
 } from "@form-engine-ts/core";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState as useState2 } from "react";
+import { createContext, useCallback as useCallback2, useContext, useEffect, useMemo as useMemo2, useState as useState2 } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 var FormContext = createContext(null);
 function issuesByField(issues) {
@@ -988,7 +1418,7 @@ function FormProvider({
   onSubmit,
   children
 }) {
-  const validSchema = useMemo(() => {
+  const validSchema = useMemo2(() => {
     assertValidFormSchema(schema);
     const localized = resolveLocalizedSchema(schema, locale);
     assertValidFormSchema(localized);
@@ -999,13 +1429,13 @@ function FormProvider({
   const [submitStatus, setSubmitStatus] = useState2("idle");
   const [submitError, setSubmitError] = useState2(null);
   const [validationPageIndex, setValidationPageIndex] = useState2(null);
-  const visibility = useMemo(() => calculateFieldVisibility(validSchema, values), [validSchema, values]);
-  const pageVisibility = useMemo(() => calculatePageVisibility(validSchema, values), [validSchema, values]);
+  const visibility = useMemo2(() => calculateFieldVisibility(validSchema, values), [validSchema, values]);
+  const pageVisibility = useMemo2(() => calculatePageVisibility(validSchema, values), [validSchema, values]);
   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 = useCallback(
+  const setValue = useCallback2(
     (fieldId, value) => {
       setValues((current) => {
         const next = { ...current, [fieldId]: value };
@@ -1021,7 +1451,7 @@ function FormProvider({
     },
     [validSchema, validationPageIndex]
   );
-  const restoreValues = useCallback(
+  const restoreValues = useCallback2(
     (restoredValues) => {
       const fieldIds = new Set(validSchema.fields.map((field) => field.id));
       setValues(Object.fromEntries(Object.entries(restoredValues).filter(([fieldId]) => fieldIds.has(fieldId))));
@@ -1032,7 +1462,7 @@ function FormProvider({
     },
     [validSchema]
   );
-  const validatePage = useCallback(
+  const validatePage = useCallback2(
     (pageIndex) => {
       const result = validatePageAnswers(validSchema, pageIndex, values);
       setErrors(issuesByField(result.issues));
@@ -1043,42 +1473,51 @@ function FormProvider({
     },
     [validSchema, values]
   );
-  const reset = useCallback(() => {
+  const reset = useCallback2(() => {
     setValues({ ...initialValues });
     setErrors({});
     setValidationPageIndex(null);
     setSubmitStatus("idle");
     setSubmitError(null);
   }, [initialValues]);
-  const submit = useCallback(async () => {
-    const validation = validateAnswers(validSchema, values);
-    if (!validation.valid) {
-      setErrors(issuesByField(validation.issues));
+  const submit = useCallback2(
+    async (beforeSubmit) => {
+      const validation = 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(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 = useCallback(
+      const visibleValues = 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 = useCallback2(
     (key, params) => translator.translate(key, locale, params),
     [locale, translator]
   );
-  const contextValue = useMemo(
+  const contextValue = useMemo2(
     () => ({
       schema: validSchema,
       locale,
@@ -1126,7 +1565,7 @@ 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 = useCallback((value) => form.setValue(fieldId, value), [fieldId, form]);
+  const setValue = useCallback2((value) => form.setValue(fieldId, value), [fieldId, form]);
   return { field, value: form.values[fieldId], error: form.errors[fieldId], setValue };
 }
 
@@ -1134,8 +1573,15 @@ function useField(fieldId) {
 import {
   validateAnswers as validateAnswers2
 } from "@form-engine-ts/core";
-import { useEffect as useEffect2, useId, useMemo as useMemo2, useRef, useState as useState3 } from "react";
-import { Fragment as Fragment2, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+import {
+  Fragment as Fragment2,
+  useEffect as useEffect2,
+  useId,
+  useMemo as useMemo3,
+  useRef,
+  useState as useState3
+} from "react";
+import { Fragment as Fragment3, jsx as jsx3, jsxs as jsxs2 } from "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(
     Boolean
@@ -1149,7 +1595,7 @@ function RequiredMark({ required }) {
   ] }) : null;
 }
 function FieldMessage({ props }) {
-  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+  return /* @__PURE__ */ jsxs2(Fragment3, { children: [
     props.field.description === void 0 ? null : /* @__PURE__ */ jsx3("div", { id: props.helpId, className: "fe-help", children: props.field.description }),
     props.error === void 0 ? null : /* @__PURE__ */ jsx3("div", { id: props.errorId, className: "fe-error", children: props.translate(props.error.messageKey, props.error.params) })
   ] });
@@ -1337,12 +1783,15 @@ function parseDraft(serialized) {
     return null;
   }
 }
-function FormRenderer({
+function ContextFormRenderer({
   components = {},
   className = "",
   successMessageKey,
   errorMessageKey,
-  autoSaveKey
+  autoSaveKey,
+  beforeSubmit,
+  onDraftSave,
+  slots = {}
 }) {
   const form = useForm();
   const prefix = useId().replace(/:/g, "");
@@ -1352,7 +1801,7 @@ function FormRenderer({
   const [currentPageIndex, setCurrentPageIndex] = useState3(0);
   const [focusFieldId, setFocusFieldId] = useState3(null);
   const pages = form.schema.pages;
-  const visiblePageIndexes = useMemo2(
+  const visiblePageIndexes = useMemo3(
     () => pages === void 0 ? [] : pages.flatMap((page, index) => form.pageVisibility[page.id] === true ? [index] : []),
     [form.pageVisibility, pages]
   );
@@ -1390,9 +1839,10 @@ function FormRenderer({
     setDraftRestored(true);
   }, [autoSaveKey, form.restoreValues, form.schema.id, form.schema.version]);
   useEffect2(() => {
-    if (autoSaveKey === void 0 || typeof globalThis.localStorage === "undefined") return;
     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,
@@ -1402,7 +1852,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);
   };
@@ -1415,27 +1865,39 @@ function FormRenderer({
     const nextPageIndex = visiblePageIndexes[activeVisibleIndex + 1];
     if (nextPageIndex !== void 0) setCurrentPageIndex(nextPageIndex);
   };
-  const handleSubmit = async (event) => {
-    event.preventDefault();
+  const submitValues = async () => {
     const validation = validateAnswers2(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__ */ jsx3("button", { className: "fe-submit", type: "submit", disabled: form.isSubmitting, children: form.translate(form.schema.submitLabelKey ?? "form.submit") });
   return /* @__PURE__ */ jsxs2("form", { ref: formRef, className: `fe-form ${className}`.trim(), noValidate: true, onSubmit: handleSubmit, children: [
-    /* @__PURE__ */ jsxs2("header", { className: "fe-header", children: [
+    slots.renderHeader?.({
+      title: form.schema.title,
+      ...form.schema.description === void 0 ? {} : { description: form.schema.description }
+    }) ?? /* @__PURE__ */ jsxs2("header", { className: "fe-header", children: [
       /* @__PURE__ */ jsx3("h1", { children: form.schema.title }),
       form.schema.description === void 0 ? null : /* @__PURE__ */ jsx3("p", { children: form.schema.description }),
       pages === void 0 ? null : /* @__PURE__ */ jsxs2("div", { className: "fe-progress", children: [
@@ -1460,44 +1922,130 @@ function FormRenderer({
       ] }),
       draftRestored ? /* @__PURE__ */ jsx3("span", { className: "form-draft-badge", children: form.translate("form.draftRestored") }) : null
     ] }),
-    activePage?.title === void 0 ? null : /* @__PURE__ */ jsx3("h2", { className: "fe-page-title", children: activePage.title }),
-    activePage?.description === void 0 ? null : /* @__PURE__ */ jsx3("p", { className: "fe-page-description", children: activePage.description }),
+    activePage === void 0 ? null : slots.renderPageHeader?.({
+      page: activePage,
+      pageIndex: activeVisibleIndex,
+      totalPages: visiblePageIndexes.length
+    }) ?? /* @__PURE__ */ jsxs2("div", { className: "fe-page-header", children: [
+      activePage.title === void 0 ? null : /* @__PURE__ */ jsx3("h2", { className: "fe-page-title", children: activePage.title }),
+      activePage.description === void 0 ? null : /* @__PURE__ */ jsx3("p", { className: "fe-page-description", children: activePage.description })
+    ] }),
     /* @__PURE__ */ jsx3("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__ */ jsx3(Fragment2, { 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__ */ jsx3(DefaultField, { ...props }, field.id) : /* @__PURE__ */ jsx3(Component, { ...props }, field.id);
     }) }),
-    pages === void 0 ? /* @__PURE__ */ jsx3("button", { className: "fe-submit", type: "submit", disabled: form.isSubmitting, children: form.translate(form.schema.submitLabelKey ?? "form.submit") }) : /* @__PURE__ */ jsxs2("div", { className: "form-step-navigation", children: [
-      activeVisibleIndex > 0 ? /* @__PURE__ */ jsx3(
-        "button",
-        {
-          className: "btn-prev",
-          type: "button",
-          onClick: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
-          children: form.translate("form.back")
-        }
-      ) : null,
-      activeVisibleIndex < visiblePageIndexes.length - 1 ? /* @__PURE__ */ jsx3("button", { className: "btn-next", type: "button", onClick: handleNext, children: form.translate("form.next") }) : /* @__PURE__ */ jsx3("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__ */ jsxs2("div", { className: "fe-validation-summary", role: "alert", children: [
+      validationIssues.length,
+      " validation error",
+      validationIssues.length === 1 ? "" : "s",
+      "."
+    ] }),
+    pages === void 0 ? /* @__PURE__ */ jsxs2(Fragment3, { children: [
+      slots.renderNavigation?.({
+        currentPage: 0,
+        totalPages: 1,
+        canPrev: false,
+        canNext: false,
+        onPrev: () => void 0,
+        onNext: () => void 0
+      }),
+      renderSubmitButton()
+    ] }) : /* @__PURE__ */ jsxs2("div", { className: "form-step-navigation", children: [
+      slots.renderNavigation?.({
+        currentPage: activeVisibleIndex,
+        totalPages: visiblePageIndexes.length,
+        canPrev,
+        canNext,
+        onPrev: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
+        onNext: handleNext
+      }) ?? /* @__PURE__ */ jsxs2(Fragment3, { children: [
+        canPrev ? /* @__PURE__ */ jsx3(
+          "button",
+          {
+            className: "btn-prev",
+            type: "button",
+            onClick: () => setCurrentPageIndex(visiblePageIndexes[activeVisibleIndex - 1] ?? 0),
+            children: form.translate("form.back")
+          }
+        ) : null,
+        canNext ? /* @__PURE__ */ jsx3("button", { className: "btn-next", type: "button", onClick: handleNext, children: form.translate("form.next") }) : null
+      ] }),
+      canNext ? null : renderSubmitButton()
     ] }),
     /* @__PURE__ */ jsxs2("div", { className: "fe-status", "aria-live": "polite", children: [
-      form.submitStatus === "success" && successMessageKey !== void 0 ? /* @__PURE__ */ jsx3("div", { role: "status", children: form.translate(successMessageKey) }) : null,
-      form.submitStatus === "error" && form.submitError !== null && errorMessageKey !== void 0 ? /* @__PURE__ */ jsx3("div", { role: "alert", children: form.translate(errorMessageKey) }) : null
+      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 === "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
     ] })
   ] });
 }
+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__ */ jsx3(ContextFormRenderer, { ...props });
+  const {
+    schema,
+    locale = schema.defaultLocale ?? "en",
+    translator = defaultRendererTranslator,
+    initialValues,
+    resetOnSuccess,
+    onSubmit,
+    ...rendererProps
+  } = props;
+  return /* @__PURE__ */ jsx3(
+    FormProvider,
+    {
+      schema,
+      locale,
+      translator,
+      onSubmit,
+      ...initialValues === void 0 ? {} : { initialValues },
+      ...resetOnSuccess === void 0 ? {} : { resetOnSuccess },
+      children: /* @__PURE__ */ jsx3(ContextFormRenderer, { ...rendererProps })
+    }
+  );
+}
 export {
   FormBuilder,
   FormProvider,
   FormRenderer,
   useField,
-  useForm
+  useForm,
+  useFormBuilder
 };