@encatch/ws-react 0.0.15 → 0.0.17

package/README.md

@@ -1,73 +1,21 @@
-# React + TypeScript + Vite
+# @encatch/ws-react
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React wrapper for Encatch web form engine. This package provides a React component to easily integrate Encatch forms into your React applications.
 
-Currently, two official plugins are available:
+### Purpose
+Helpful when you want to manually open feedback (static forms) in your react application.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## Resources
 
-## React Compiler
+- **Website**: [https://encatch.com](https://encatch.com)
+- **Documentation**: [https://encatch.com/docs](https://encatch.com/docs)
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## Installation
 
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+npm install @encatch/ws-react
+# or
+pnpm add @encatch/ws-react
+# or
+yarn add @encatch/ws-react
 ```

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';