@bacano/sdk 1.1.19 → 1.2.1

package/react/forms.cjs

@@ -21,10 +21,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var forms_exports = {};
 __export(forms_exports, {
   BacanoForm: () => BacanoForm,
-  useBacanoForm: () => useBacanoForm
+  useBacanoForm: () => useBacanoForm,
+  useBacanoFormTracking: () => useBacanoFormTracking
 });
 module.exports = __toCommonJS(forms_exports);
-var import_react3 = require("react");
+var import_react4 = require("react");
+
+// libs/sdk/src/errors.ts
+var WebsiteError = class extends Error {
+  code;
+  status;
+  retryAfterSeconds;
+  constructor(message, code = "WEBSITE_ERROR", options) {
+    super(message);
+    this.name = "WebsiteError";
+    this.code = code;
+    this.status = options?.status ?? null;
+    this.retryAfterSeconds = options?.retryAfterSeconds ?? null;
+  }
+};
 
 // libs/sdk/src/react/form-field-control.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -114,9 +129,111 @@ function BacanoFormFieldControl(props) {
   );
 }
 
-// libs/sdk/src/react/hooks.ts
+// libs/sdk/src/react/form-sections.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function FormFields(props) {
+  return props.fields.map((field) => {
+    const controlId = `${props.idPrefix}-${field.key}`;
+    const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: props.classNames?.field, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "label",
+        {
+          id: `${controlId}-label`,
+          htmlFor: field.type === "radio" ? void 0 : controlId,
+          className: props.classNames?.label,
+          children: field.label
+        }
+      ),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        BacanoFormFieldControl,
+        {
+          field,
+          id: controlId,
+          value,
+          className: props.classNames?.input,
+          onChange: (nextValue) => props.onChange(field.key, nextValue)
+        }
+      ),
+      field.helpText ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.helpText, children: field.helpText }) : null
+    ] }, field.key);
+  });
+}
+function FormSections(props) {
+  return props.sections.map((section) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { className: props.classNames?.section, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h3", { className: props.classNames?.sectionTitle, children: section.title }),
+    section.description ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.sectionDescription, children: section.description }) : null,
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      FormFields,
+      {
+        fields: section.fields,
+        idPrefix: props.idPrefix,
+        values: props.values,
+        classNames: props.classNames,
+        onChange: props.onChange
+      }
+    )
+  ] }, section.key));
+}
+
+// libs/sdk/src/react/form-tracking.ts
 var import_react2 = require("react");
 
+// libs/sdk/src/marketing/interactions.ts
+function newMarketingEventId() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `evt_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+
+// libs/sdk/src/marketing/form-interactions.ts
+function createFormInteractionTracker(getRuntime, formKey) {
+  let visible = false;
+  let started = false;
+  let attempt = null;
+  const completedSteps = /* @__PURE__ */ new Set();
+  function emit(eventName, context = {}) {
+    try {
+      getRuntime().track({ eventName, formKey, ...context });
+    } catch {
+    }
+  }
+  return {
+    setVisible(next) {
+      if (next && !visible && getRuntime().enabled) emit("form_open");
+      visible = next;
+    },
+    start() {
+      if (started || !getRuntime().enabled) return;
+      started = true;
+      emit("form_start");
+    },
+    stepComplete(stepKey) {
+      if (completedSteps.has(stepKey) || !getRuntime().enabled) return;
+      completedSteps.add(stepKey);
+      emit("form_step_complete", { stepKey });
+    },
+    beginSubmit() {
+      if (attempt) return false;
+      attempt = newMarketingEventId();
+      emit("form_submit_attempt", { eventId: attempt });
+      return true;
+    },
+    fail(errorCategory) {
+      if (!attempt) return;
+      emit("form_submit_error", { eventId: attempt, errorCategory });
+      attempt = null;
+    },
+    complete(result) {
+      if (!attempt) return;
+      if (result?.accepted && typeof result.responseId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+        result.responseId
+      )) {
+        emit("form_submit_success", { eventId: result.responseId });
+      }
+      attempt = null;
+    }
+  };
+}
+
 // libs/sdk/src/react/context-registry.ts
 var import_react = require("react");
 var REACT_CONTEXT_REGISTRY = /* @__PURE__ */ Symbol.for(
@@ -143,6 +260,37 @@ function getOrCreateReactContext(key, defaultValue) {
   return context;
 }
 
+// libs/sdk/src/react/marketing-context.ts
+var NOOP_MARKETING_RUNTIME = {
+  enabled: false,
+  track: () => void 0,
+  captureAttribution: () => null,
+  getAttribution: () => null,
+  destroy: () => void 0
+};
+var BacanoMarketingContext = getOrCreateReactContext(
+  "bacano-marketing-v1",
+  NOOP_MARKETING_RUNTIME
+);
+
+// libs/sdk/src/react/form-tracking.ts
+function useBacanoFormTracking(formKey, options = {}) {
+  const runtime = (0, import_react2.useContext)(BacanoMarketingContext);
+  const current = (0, import_react2.useRef)(runtime);
+  current.current = runtime;
+  const tracker = (0, import_react2.useMemo)(
+    () => createFormInteractionTracker(() => current.current, formKey),
+    [formKey]
+  );
+  (0, import_react2.useEffect)(() => {
+    tracker.setVisible((options.visible ?? true) && runtime.enabled);
+  }, [tracker, options.visible, runtime.enabled]);
+  return tracker;
+}
+
+// libs/sdk/src/react/hooks.ts
+var import_react3 = require("react");
+
 // libs/sdk/src/react/context.ts
 var BacanoReactContext = getOrCreateReactContext("bacano-client-v1", {
   client: null,
@@ -152,11 +300,11 @@ var BacanoReactContext = getOrCreateReactContext("bacano-client-v1", {
 
 // libs/sdk/src/react/hooks.ts
 function useBacanoState() {
-  return (0, import_react2.useContext)(BacanoReactContext);
+  return (0, import_react3.useContext)(BacanoReactContext);
 }
 
 // libs/sdk/src/react/forms.tsx
-var import_jsx_runtime2 = require("react/jsx-runtime");
+var import_jsx_runtime3 = require("react/jsx-runtime");
 var EMPTY_FORM_FIELDS = [];
 var EMPTY_FORM_SECTIONS = [];
 var EMPTY_FORM_STEPS = [];
@@ -168,31 +316,35 @@ function useBacanoForm(formKey, options) {
   } = useBacanoState();
   const enabled = options?.enabled ?? true;
   const initialForm = options?.initialForm?.key === formKey ? options.initialForm : null;
-  const [form, setForm] = (0, import_react3.useState)(initialForm);
-  const formRef = (0, import_react3.useRef)(initialForm);
-  const [loading, setLoading] = (0, import_react3.useState)(enabled && !initialForm);
-  const [error, setError] = (0, import_react3.useState)(null);
-  const load = (0, import_react3.useCallback)(
+  const [form, setForm] = (0, import_react4.useState)(initialForm);
+  const formRef = (0, import_react4.useRef)(initialForm);
+  const requestVersion = (0, import_react4.useRef)(0);
+  const [loading, setLoading] = (0, import_react4.useState)(enabled && !initialForm);
+  const [error, setError] = (0, import_react4.useState)(null);
+  const load = (0, import_react4.useCallback)(
     async (force = false) => {
       if (!enabled || !client) return;
+      const version = ++requestVersion.current;
       setLoading(formRef.current === null);
       setError(null);
       try {
         const nextForm = await client.forms.getDefinition(formKey, { force });
+        if (version !== requestVersion.current) return;
         formRef.current = nextForm;
         setForm(nextForm);
       } catch (loadError) {
+        if (version !== requestVersion.current) return;
         if (!formRef.current) setForm(null);
         setError(
           loadError instanceof Error ? loadError : new Error(String(loadError))
         );
       } finally {
-        setLoading(false);
+        if (version === requestVersion.current) setLoading(false);
       }
     },
     [client, enabled, formKey]
   );
-  (0, import_react3.useEffect)(() => {
+  (0, import_react4.useEffect)(() => {
     if (!enabled) {
       formRef.current = null;
       setForm(null);
@@ -201,76 +353,38 @@ function useBacanoForm(formKey, options) {
       return;
     }
     if (client) void load();
+    return () => {
+      requestVersion.current += 1;
+    };
   }, [client, enabled, load]);
   return {
-    form,
-    loading: enabled && form === null && (clientLoading || loading),
+    form: enabled ? form?.key === formKey ? form : initialForm : null,
+    loading: enabled && form?.key !== formKey && !initialForm && (clientLoading || loading),
     error: clientError ?? error,
     refresh: async () => load(true)
   };
 }
-function FormFields(props) {
-  return props.fields.map((field) => {
-    const controlId = `${props.idPrefix}-${field.key}`;
-    const value = props.values[field.key] ?? (field.type === "checkbox" ? false : field.type === "multi_select" ? [] : "");
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: props.classNames?.field, children: [
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-        "label",
-        {
-          id: `${controlId}-label`,
-          htmlFor: field.type === "radio" ? void 0 : controlId,
-          className: props.classNames?.label,
-          children: field.label
-        }
-      ),
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-        BacanoFormFieldControl,
-        {
-          field,
-          id: controlId,
-          value,
-          className: props.classNames?.input,
-          onChange: (nextValue) => props.onChange(field.key, nextValue)
-        }
-      ),
-      field.helpText ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.helpText, children: field.helpText }) : null
-    ] }, field.key);
-  });
-}
-function FormSections(props) {
-  return props.sections.map((section) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { className: props.classNames?.section, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h3", { className: props.classNames?.sectionTitle, children: section.title }),
-    section.description ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.sectionDescription, children: section.description }) : null,
-    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-      FormFields,
-      {
-        fields: section.fields,
-        idPrefix: props.idPrefix,
-        values: props.values,
-        classNames: props.classNames,
-        onChange: props.onChange
-      }
-    )
-  ] }, section.key));
-}
-function BacanoForm(props) {
-  const reactId = (0, import_react3.useId)();
+function BacanoFormInstance(props) {
+  const reactId = (0, import_react4.useId)();
   const idPrefix = `${props.formKey}-${reactId.replace(/:/g, "")}`;
   const { client } = useBacanoState();
   const { form, loading, error } = useBacanoForm(props.formKey, {
     initialForm: props.initialForm
   });
-  const [values, setValues] = (0, import_react3.useState)({});
-  const [step, setStep] = (0, import_react3.useState)(0);
-  const [submitting, setSubmitting] = (0, import_react3.useState)(false);
-  const [submitted, setSubmitted] = (0, import_react3.useState)(false);
-  const [submissionError, setSubmissionError] = (0, import_react3.useState)(null);
-  const [honeypot, setHoneypot] = (0, import_react3.useState)("");
-  const idempotencyKey = (0, import_react3.useRef)(crypto.randomUUID());
+  const [internalValues, setValues] = (0, import_react4.useState)({});
+  const [step, setStep] = (0, import_react4.useState)(0);
+  const [submitting, setSubmitting] = (0, import_react4.useState)(false);
+  const [submitted, setSubmitted] = (0, import_react4.useState)(false);
+  const [submissionError, setSubmissionError] = (0, import_react4.useState)(null);
+  const [honeypot, setHoneypot] = (0, import_react4.useState)("");
+  const tracking = useBacanoFormTracking(props.formKey, {
+    visible: (props.visible ?? true) && !loading && form?.status === "ACTIVE" && !submitted
+  });
+  const idempotencyKey = (0, import_react4.useRef)(crypto.randomUUID());
   const fields = form?.definition.fields ?? EMPTY_FORM_FIELDS;
   const sections = form?.definition.sections ?? EMPTY_FORM_SECTIONS;
   const steps = form?.definition.steps ?? EMPTY_FORM_STEPS;
-  const fieldKeys = (0, import_react3.useMemo)(
+  const fieldKeys = (0, import_react4.useMemo)(
     () => new Set(
       [
         ...fields,
@@ -283,7 +397,12 @@ function BacanoForm(props) {
     ),
     [fields, sections, steps]
   );
-  (0, import_react3.useEffect)(() => {
+  const values = Object.fromEntries(
+    Object.entries(props.values ?? internalValues).filter(
+      ([key]) => fieldKeys.has(key)
+    )
+  );
+  (0, import_react4.useEffect)(() => {
     setStep(0);
     setValues(
       (current) => Object.fromEntries(
@@ -295,23 +414,37 @@ function BacanoForm(props) {
     setHoneypot("");
     idempotencyKey.current = crypto.randomUUID();
   }, [fieldKeys, form?.version]);
-  if (loading) return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: props.loadingFallback ?? null });
+  if (loading) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: props.loadingFallback ?? null });
   if (error && !form)
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: props.errorFallback?.(error) ?? props.unavailableFallback ?? null });
-  if (!form) return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: props.unavailableFallback ?? null });
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: props.errorFallback?.(error) ?? props.unavailableFallback ?? null });
+  if (!form) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: props.unavailableFallback ?? null });
   if (form.status === "PAUSED") {
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: props.classNames?.message, "data-bacano-form-unavailable": true, children: props.unavailableFallback ?? form.definition.unavailableMessage });
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: props.classNames?.message, "data-bacano-form-unavailable": true, children: props.unavailableFallback ?? form.definition.unavailableMessage });
   }
   if (submitted) {
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: props.classNames?.message, "data-bacano-form-success": true, children: form.definition.successMessage });
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: props.classNames?.message, "data-bacano-form-success": true, children: form.definition.successMessage });
   }
   const isMultiStep = steps.length > 0;
   const activeStep = isMultiStep ? steps[step] : null;
   const isLastStep = !isMultiStep || step === steps.length - 1;
-  const setFieldValue = (key, value) => setValues((current) => ({ ...current, [key]: value }));
+  const setFieldValue = (key, value) => {
+    if (value !== "" && value !== false && (!Array.isArray(value) || value.length > 0))
+      tracking.start();
+    const nextValues = { ...values, [key]: value };
+    setValues(nextValues);
+    props.onValuesChange?.(nextValues);
+  };
   const submit = async (event) => {
     event.preventDefault();
+    if (submitting || submitted) return;
+    if (isLastStep && !tracking.beginSubmit()) return;
+    if (!event.currentTarget.checkValidity()) {
+      if (isLastStep) tracking.fail("validation");
+      event.currentTarget.reportValidity();
+      return;
+    }
     if (!isLastStep) {
+      if (activeStep) tracking.stepComplete(activeStep.key);
       setStep((current) => current + 1);
       return;
     }
@@ -319,8 +452,12 @@ function BacanoForm(props) {
     setSubmissionError(null);
     try {
       let responseId = null;
+      let officialResult;
       if (props.onSubmit) {
-        await props.onSubmit(values, form);
+        officialResult = await props.onSubmit(values, form);
+        if (officialResult && !officialResult.accepted)
+          throw new Error(officialResult.message);
+        responseId = officialResult?.responseId ?? null;
       } else {
         if (!client) throw new Error("Bacano client is not ready");
         const result = await client.forms.submitResponse({
@@ -332,11 +469,16 @@ function BacanoForm(props) {
           honeypot
         });
         if (!result.accepted) throw new Error(result.message);
+        officialResult = result;
         responseId = result.responseId;
       }
+      tracking.complete(officialResult);
       setSubmitted(true);
       props.onSubmitted?.(responseId);
     } catch (submitError) {
+      tracking.fail(
+        submitError instanceof WebsiteError && submitError.code === "NETWORK_ERROR" ? "network" : "rejected"
+      );
       setSubmissionError(
         submitError instanceof Error ? submitError : new Error(String(submitError))
       );
@@ -344,15 +486,16 @@ function BacanoForm(props) {
       setSubmitting(false);
     }
   };
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
     "form",
     {
+      noValidate: true,
       className: props.classNames?.root,
       "data-bacano-form": form.key,
       "data-bacano-form-version": form.version,
       onSubmit: (event) => void submit(event),
       children: [
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
           "div",
           {
             "aria-hidden": "true",
@@ -364,8 +507,8 @@ function BacanoForm(props) {
               clip: "rect(0 0 0 0)"
             },
             children: [
-              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("label", { htmlFor: `${form.key}-company-website`, children: "Empresa" }),
-              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("label", { htmlFor: `${form.key}-company-website`, children: "Empresa" }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
                 "input",
                 {
                   id: `${form.key}-company-website`,
@@ -379,12 +522,12 @@ function BacanoForm(props) {
             ]
           }
         ),
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { className: props.classNames?.title, children: form.name }),
-        form.description ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.description, children: form.description }) : null,
-        activeStep ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { className: props.classNames?.step, "data-bacano-form-step": true, children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h3", { className: props.classNames?.stepTitle, children: activeStep.title }),
-          activeStep.description ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: props.classNames?.stepDescription, children: activeStep.description }) : null,
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { className: props.classNames?.title, children: form.name }),
+        form.description ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { className: props.classNames?.description, children: form.description }) : null,
+        activeStep ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("section", { className: props.classNames?.step, "data-bacano-form-step": true, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h3", { className: props.classNames?.stepTitle, children: activeStep.title }),
+          activeStep.description ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { className: props.classNames?.stepDescription, children: activeStep.description }) : null,
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             FormFields,
             {
               fields: activeStep.fields,
@@ -394,7 +537,7 @@ function BacanoForm(props) {
               onChange: setFieldValue
             }
           ),
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             FormSections,
             {
               sections: activeStep.sections,
@@ -404,8 +547,8 @@ function BacanoForm(props) {
               onChange: setFieldValue
             }
           )
-        ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        ] }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_jsx_runtime3.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             FormFields,
             {
               fields,
@@ -415,7 +558,7 @@ function BacanoForm(props) {
               onChange: setFieldValue
             }
           ),
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             FormSections,
             {
               sections,
@@ -426,8 +569,8 @@ function BacanoForm(props) {
             }
           )
         ] }),
-        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: props.classNames?.actions, children: [
-          isMultiStep && step > 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: props.classNames?.actions, children: [
+          isMultiStep && step > 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             "button",
             {
               type: "button",
@@ -435,7 +578,7 @@ function BacanoForm(props) {
               children: "Anterior"
             }
           ) : null,
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             "button",
             {
               type: "submit",
@@ -445,7 +588,7 @@ function BacanoForm(props) {
             }
           )
         ] }),
-        submissionError ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        submissionError ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
           "div",
           {
             role: "alert",
@@ -458,3 +601,6 @@ function BacanoForm(props) {
     }
   );
 }
+function BacanoForm(props) {
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(BacanoFormInstance, { ...props }, props.formKey);
+}

package/react/forms.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
-import type { WebsitePublishedForm } from "../types";
+import type { WebsiteFormResponseResult, WebsitePublishedForm } from "../types";
+export { useBacanoFormTracking } from "./form-tracking";
 export type BacanoFormValues = Record<string, string | string[] | boolean>;
 export interface UseBacanoFormOptions {
     enabled?: boolean;
@@ -33,17 +34,24 @@ export interface BacanoFormClassNames {
 }
 export interface BacanoFormProps {
     formKey: string;
+    /** Pass the actual modal/drawer visibility when it stays mounted while closed. */
+    visible?: boolean;
+    /** Controlled values. Use together with onValuesChange; option values, not labels. */
+    values?: BacanoFormValues;
+    /** Receives the complete next values after a visitor edits a field. */
+    onValuesChange?(values: BacanoFormValues): void;
     /** Definition embedded by a server/build; it is revalidated in runtime. */
     initialForm?: WebsitePublishedForm | null;
     /**
      * Optional custom submission. When omitted, the official Bacano response
      * endpoint is used. Existing storefronts may keep a custom handler.
      */
-    onSubmit?(values: BacanoFormValues, form: WebsitePublishedForm): void | Promise<void>;
+    onSubmit?(values: BacanoFormValues, form: WebsitePublishedForm): void | WebsiteFormResponseResult | Promise<void | WebsiteFormResponseResult>;
     onSubmitted?(responseId: string | null): void;
     classNames?: BacanoFormClassNames;
     loadingFallback?: ReactNode;
     unavailableFallback?: ReactNode;
     errorFallback?: (error: Error) => ReactNode;
 }
+/** A different form cannot inherit pending submission state from the old key. */
 export declare function BacanoForm(props: BacanoFormProps): import("react").JSX.Element;