@soyio/soyio-widget 3.4.0 → 3.5.0

package/README.md

@@ -21,6 +21,7 @@ This package is validated by the Soyio SDK CI workflow.
 - [Modules](#modules)
 - [Consent Request Box](#consent-request-box)
 - [Privacy Center](#privacy-center)
+- [Consent Form Box](#consent-form-box)
 - [Disclosure Request](#disclosure-request)
 - [Disclosure Request Box](#disclosure-request-box)
 - [Signature Attempt](#signature-attempt)
@@ -58,6 +59,7 @@ The Soyio Widget provides several modules that you can integrate into your appli
 
 - **Consent Request Box**: Embed consent requests directly within your webpage
 - **Privacy Center**: Embed the Privacy Center inside your page with customizable features
+- **Consent Form Box**: Embed a multi-page consent form that captures field data alongside consent grants
 - **Disclosure Request**: Verify users and collect required data through validation or authentication
 - **Signature Attempt**: Enable users to digitally sign documents after authentication
 - **Auth Request**: Authenticate users using access keys or facial video
@@ -328,6 +330,110 @@ Note:
   - `eventName`: The name of the event, in this case, `'REQUEST_SUBMITTED'`.
   - `kind`: The kind of the Data Subject Request submitted. Supported values are: `access`, `opposition`, `rectification`, `suppression` and `portability`
 
+## Consent Form Box
+
+> 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/consent-form/introduction)
+
+The **`ConsentFormBox`** embeds a consent form hosted at `forms.soyio.id` directly within your page. A consent form bundles arbitrary input fields (text, email, NIN, etc.) with one or more consent grants and can be split across multiple pages. The host controls how the success CTA behaves, so embeds inside modals, drawers, or multi-step flows can keep navigation inside their own UI.
+
+```html
+<!-- Add a container div where the consent form will be mounted -->
+<div id="consent-form-box"></div>
+
+<script>
+  import { ConsentFormBox } from "@soyio/soyio-widget";
+
+  const consentFormOptions = {
+    consentFormToken: "<cform_ token>",
+    locale: "en", // Optional, "es" | "en"
+    isSandbox: true, // Optional
+    appearance: {}, // Optional
+    subjectId: "<ent_ entity id>", // Optional
+    userReference: "<your-user-id>", // Optional
+    onReady: () => console.log("ConsentFormBox is ready"), // Optional
+    onEvent: (event) => {
+      switch (event.eventName) {
+        case "CONSENT_FORM_PAGE_CHANGE":
+          console.log(`Page ${event.currentPage}/${event.totalPages}`);
+          break;
+        case "CONSENT_FORM_SUBMITTED":
+          console.log("Entry created", event.entryToken);
+          break;
+        case "CONSENT_FORM_COMPLETED":
+          // Success CTA was clicked. Decide what to do with the redirect URL.
+          if (event.redirectUrl) window.top.location.assign(event.redirectUrl);
+          break;
+      }
+    },
+  };
+
+  document.addEventListener("DOMContentLoaded", () => {
+    const consentForm = new ConsentFormBox(consentFormOptions);
+    consentForm.mount("#consent-form-box");
+  });
+</script>
+```
+
+### Consent Form Box Events
+
+All events arrive through `onEvent` with the shapes below. `onReady` is a separate top-level callback fired once when the iframe finishes loading.
+
+- **`CONSENT_FORM_LOAD_ERROR`**: Bootstrap failed (form not found, host not allowed, network error).
+  ```typescript
+  {
+    eventName: 'CONSENT_FORM_LOAD_ERROR',
+    kind: 'notFound' | 'hostNotAllowed' | 'loadFailed',
+    message?: string,
+  }
+  ```
+- **`CONSENT_FORM_PAGE_CHANGE`**: Fires on initial render and every back/continue navigation. `currentPage` is 1-indexed.
+  ```typescript
+  {
+    eventName: 'CONSENT_FORM_PAGE_CHANGE',
+    currentPage: number,
+    totalPages: number,
+  }
+  ```
+- **`CONSENT_FORM_SUBMIT_ERROR`**: The submission request failed after the user clicked submit.
+  ```typescript
+  {
+    eventName: 'CONSENT_FORM_SUBMIT_ERROR',
+    message: string,
+  }
+  ```
+- **`CONSENT_FORM_SUBMITTED`**: A form entry was created. `redirectUrl` reflects the success screen's configured redirect (if any) so the host knows a final CTA is coming.
+  ```typescript
+  {
+    eventName: 'CONSENT_FORM_SUBMITTED',
+    entryToken: string,
+    redirectUrl: string | null,
+  }
+  ```
+- **`CONSENT_FORM_COMPLETED`**: The success-screen CTA was clicked. In hosted mode the embed never navigates the iframe itself — the host decides what to do (close a modal, top-level navigation, fire analytics).
+  ```typescript
+  {
+    eventName: 'CONSENT_FORM_COMPLETED',
+    entryToken: string,
+    redirectUrl: string | null,
+  }
+  ```
+
+### Attribute Descriptions
+
+- **`consentFormToken`**: Identifier of the consent form to render. Must start with `'cform_'`.
+- **`locale`**: Language for built-in copy and validations. Supported values: `'es'`, `'en'`. Defaults to the form's configured language.
+- **`subjectId`**: Optional Soyio entity id (starts with `'ent_'`) to link the resulting entry to an existing data subject.
+- **`userReference`**: Optional integrator-provided reference that is persisted with the entry.
+- **`isSandbox`**: Whether to use the sandbox environment. Defaults to `false`.
+- **`appearance`**: Customize the iframe appearance. See the Appearance section below. The following `appearance.config.*` keys are specific to this module:
+  - `appearance.config.showLogo`: Show or hide the form's logo.
+  - `appearance.config.showHeader`: Show or hide the form title.
+  - `appearance.config.showDescription`: Show or hide the form description.
+  - `appearance.config.buttonAlignment`: `'left'` (default), `'center'`, or `'right'`.
+  - `appearance.config.icon.dataUseVariant`: Override the data-use icon style (`'duotone'`, `'line'`, `'solid'`).
+- **`onEvent`**: Callback that receives every event fired by the form. See Consent Form Box Events above.
+- **`onReady`**: Optional callback fired once when the iframe becomes ready.
+
 ## Disclosure Request
 
 > 📖 [Integration Guide](https://docs.soyio.id/docs/integration-guide/disclosure/introduction)

package/dist/index.d.ts

@@ -92,6 +92,60 @@ declare type ConsentConfig = BaseConfig & {
 
 declare type ConsentEvent = ConsentCheckboxChangeEvent;
 
+export declare class ConsentFormBox extends BaseIframeBox<ConsentFormEvent, ConsentFormConfig> {
+    readonly defaultIframePrefix = "consent-form";
+    readonly defaultIframeCSSConfig: IframeCSSConfig;
+    get uniqueIdentifier(): string;
+    protected handleIframeReady(): Promise<void>;
+    iframeUrl(): string;
+}
+
+declare type ConsentFormCompletedEvent = {
+    eventName: 'CONSENT_FORM_COMPLETED';
+    entryToken: string;
+    redirectUrl: string | null;
+};
+
+declare type ConsentFormConfig = BaseConfig<ConsentFormEvent> & {
+    /** Form version identifier returned by the dashboard (`cform_...`). */
+    consentFormToken: `cform_${string}`;
+    /** Language used by the form's UI copy and built-in validations. */
+    locale?: ConsentFormLocale;
+    /** Optional Soyio entity id (`ent_...`) the entry should be linked to. */
+    subjectId?: string | null;
+    /** Optional integrator-provided reference that travels with the entry. */
+    userReference?: string | null;
+};
+
+declare type ConsentFormEvent = ConsentFormSubmittedEvent | ConsentFormCompletedEvent | ConsentFormLoadErrorEvent | ConsentFormSubmitErrorEvent | ConsentFormPageChangeEvent;
+
+declare type ConsentFormLoadErrorEvent = {
+    eventName: 'CONSENT_FORM_LOAD_ERROR';
+    kind: ConsentFormLoadErrorKind;
+    message?: string;
+};
+
+declare type ConsentFormLoadErrorKind = 'notFound' | 'hostNotAllowed' | 'loadFailed';
+
+declare type ConsentFormLocale = 'es' | 'en';
+
+declare type ConsentFormPageChangeEvent = {
+    eventName: 'CONSENT_FORM_PAGE_CHANGE';
+    currentPage: number;
+    totalPages: number;
+};
+
+declare type ConsentFormSubmitErrorEvent = {
+    eventName: 'CONSENT_FORM_SUBMIT_ERROR';
+    message: string;
+};
+
+declare type ConsentFormSubmittedEvent = {
+    eventName: 'CONSENT_FORM_SUBMITTED';
+    entryToken: string;
+    redirectUrl: string | null;
+};
+
 declare type ConsentState = {
     isSelected: boolean;
     actionToken: string | null;
@@ -445,6 +499,21 @@ declare interface SoyioAppearanceConfig {
     consentControl?: 'switch' | 'checkbox';
     showHeader?: boolean;
     showConsentManagementHeader?: boolean;
+    /**
+     * Show or hide the company/form logo above the content.
+     * Currently consumed by `ConsentFormBox`.
+     */
+    showLogo?: boolean;
+    /**
+     * Show or hide the supporting description text beneath the title.
+     * Currently consumed by `ConsentFormBox`.
+     */
+    showDescription?: boolean;
+    /**
+     * Alignment for primary CTA rows (e.g. "Submit", "Continue").
+     * Currently consumed by `ConsentFormBox`.
+     */
+    buttonAlignment?: 'left' | 'center' | 'right';
     /**
      * Icon name to use for hint/help tooltips on input labels.
      * Available icons: 'Question' (default), 'Info', 'QuestionMark', etc.
@@ -590,6 +659,15 @@ declare namespace SoyioTypes {
         ConsentEvent,
         ConsentConfig,
         PrivacyCenterConfig,
+        ConsentFormConfig,
+        ConsentFormEvent,
+        ConsentFormLocale,
+        ConsentFormLoadErrorKind,
+        ConsentFormSubmittedEvent,
+        ConsentFormCompletedEvent,
+        ConsentFormLoadErrorEvent,
+        ConsentFormSubmitErrorEvent,
+        ConsentFormPageChangeEvent,
         SoyioAppearance,
         SoyioAppearanceConfig,
         SoyioAppearanceVariables,