@encatch/ws-react 0.0.16 → 0.0.18

package/dist/EncatchPreview.d.ts

@@ -1,5 +1,6 @@
 import { AppProps, Section } from "@encatch/schema";
 import React from "react";
+import type { OnFormEventHandler } from "./types";
 declare module "react" {
     namespace JSX {
         interface IntrinsicElements {
@@ -24,6 +25,7 @@ declare module "react" {
                 cssLink?: string;
                 scale?: number;
                 persistMode?: "retain" | "reset" | "none";
+                instanceId?: string;
             };
         }
     }
@@ -51,6 +53,27 @@ interface EncatchPreviewProps {
     cssLink: string;
     scale?: number;
     persistMode?: "retain" | "reset" | "none";
+    instanceId?: string;
+    /**
+     * Callback function that receives a FormEventBuilder to register event handlers
+     * Events are automatically filtered to only this form instance
+     *
+     * @example
+     * ```tsx
+     * const handleFormEvents = (formEvent) => {
+     *   formEvent.onSubmit((data) => {
+     *     console.log('Form submitted:', data);
+     *   });
+     *
+     *   formEvent.onQuestionAnswered((data) => {
+     *     console.log('Question answered:', data.questionId, data.answer);
+     *   });
+     * };
+     *
+     * <EncatchPreview onFormEvent={handleFormEvents} {...props} />
+     * ```
+     */
+    onFormEvent?: OnFormEventHandler;
 }
 export declare const EncatchPreview: React.FC<EncatchPreviewProps>;
 export {};

package/dist/index.d.ts

@@ -1 +1,4 @@
 export { EncatchPreview } from "./EncatchPreview";
+export { useEncatchFormEvent, useEncatchFormEventAll } from "./useEncatchFormEvent";
+export type { FormEventType, FormEventPayload, SubscriptionOptions, FormIdFilter, } from "./useEncatchFormEvent";
+export type { FormEventBuilder, OnFormEventHandler, OnSubmitCallback, OnViewCallback, OnCloseCallback, OnSectionChangeCallback, OnQuestionAnsweredCallback, OnErrorCallback, } from "./types";

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+import type { FormEventPayload } from '@encatch/event-publisher';
+/**
+ * Callback function for form submit events
+ */
+export type OnSubmitCallback = (payload: FormEventPayload['form:submit']) => void;
+/**
+ * Callback function for form view events
+ */
+export type OnViewCallback = (payload: FormEventPayload['form:view']) => void;
+/**
+ * Callback function for form close events
+ */
+export type OnCloseCallback = (payload: FormEventPayload['form:close']) => void;
+/**
+ * Callback function for section change events
+ */
+export type OnSectionChangeCallback = (payload: FormEventPayload['form:section:change']) => void;
+/**
+ * Callback function for question answered events
+ */
+export type OnQuestionAnsweredCallback = (payload: FormEventPayload['form:question:answered']) => void;
+/**
+ * Callback function for form error events
+ */
+export type OnErrorCallback = (payload: FormEventPayload['form:error']) => void;
+/**
+ * Form Event Builder - provides methods to register callbacks for different form events
+ *
+ * @example
+ * ```tsx
+ * const handleFormEvents = (formEvent) => {
+ *   formEvent.onSubmit((data) => {
+ *     console.log('Form submitted:', data);
+ *   });
+ *
+ *   formEvent.onQuestionAnswered((data) => {
+ *     console.log('Question answered:', data.questionId, data.answer);
+ *   });
+ *
+ *   formEvent.onSectionChange((data) => {
+ *     console.log('Section changed to:', data.sectionIndex);
+ *   });
+ * };
+ *
+ * <EncatchPreview
+ *   instanceId="form-1"
+ *   onFormEvent={handleFormEvents}
+ *   {...otherProps}
+ * />
+ * ```
+ */
+export interface FormEventBuilder {
+    /**
+     * Register a callback for form submission
+     * @param callback - Function to call when form is submitted
+     */
+    onSubmit: (callback: OnSubmitCallback) => void;
+    /**
+     * Register a callback for when form is viewed/opened
+     * @param callback - Function to call when form is viewed
+     */
+    onView: (callback: OnViewCallback) => void;
+    /**
+     * Register a callback for when form is closed
+     * @param callback - Function to call when form is closed
+     */
+    onClose: (callback: OnCloseCallback) => void;
+    /**
+     * Register a callback for section changes
+     * @param callback - Function to call when user navigates between sections
+     */
+    onSectionChange: (callback: OnSectionChangeCallback) => void;
+    /**
+     * Register a callback for when questions are answered
+     * @param callback - Function to call when a question is answered
+     */
+    onQuestionAnswered: (callback: OnQuestionAnsweredCallback) => void;
+    /**
+     * Register a callback for form errors
+     * @param callback - Function to call when an error occurs
+     */
+    onError: (callback: OnErrorCallback) => void;
+}
+/**
+ * Function type for the onFormEvent prop
+ */
+export type OnFormEventHandler = (formEvent: FormEventBuilder) => void;

package/dist/useEncatchFormEvent.d.ts

@@ -0,0 +1,50 @@
+import { type FormEventType, type FormEventPayload, type SubscriptionOptions } from '@encatch/event-publisher';
+/**
+ * React hook for subscribing to form events from the event publisher.
+ *
+ * @example
+ * ```tsx
+ * // Subscribe to all form submit events
+ * useEncatchFormEvent('form:submit', (payload) => {
+ *   console.log('Form submitted:', payload);
+ * });
+ *
+ * // Subscribe to events from a specific form instance
+ * useEncatchFormEvent('form:submit', (payload) => {
+ *   console.log('Specific form submitted:', payload);
+ * }, { formId: 'my-form-instance-1' });
+ *
+ * // Subscribe once
+ * useEncatchFormEvent('form:view', (payload) => {
+ *   console.log('Form viewed:', payload);
+ * }, { formId: 'my-form-instance-1', once: true });
+ * ```
+ *
+ * @param eventType - The type of event to subscribe to
+ * @param handler - Callback function to handle the event
+ * @param options - Subscription options (formId filter, once flag)
+ * @returns void - Cleanup is handled automatically on unmount
+ */
+export declare function useEncatchFormEvent<T extends FormEventType>(eventType: T, handler: (payload: FormEventPayload[T]) => void, options?: SubscriptionOptions): void;
+/**
+ * React hook for subscribing to all form events.
+ *
+ * @example
+ * ```tsx
+ * // Subscribe to all events from all forms
+ * useEncatchFormEventAll((eventType, payload) => {
+ *   console.log(`Event ${eventType}:`, payload);
+ * });
+ *
+ * // Subscribe to all events from a specific form instance
+ * useEncatchFormEventAll((eventType, payload) => {
+ *   console.log(`Event ${eventType} from form:`, payload);
+ * }, { formId: 'my-form-instance-1' });
+ * ```
+ *
+ * @param handler - Callback function to handle all events
+ * @param options - Subscription options (formId filter, once flag)
+ * @returns void - Cleanup is handled automatically on unmount
+ */
+export declare function useEncatchFormEventAll(handler: (eventType: FormEventType, payload: any) => void, options?: SubscriptionOptions): void;
+export type { FormEventType, FormEventPayload, SubscriptionOptions, FormIdFilter } from '@encatch/event-publisher';