@encatch/ws-react 0.0.17 → 0.0.19

package/README.md

@@ -1,9 +1,10 @@
 # @encatch/ws-react
 
-React wrapper for Encatch web form engine. This package provides a React component to easily integrate Encatch forms into your React applications.
+React wrapper for Encatch web form engine. This package provides React components and hooks to easily integrate Encatch forms into your React applications with full event handling capabilities.
 
-### Purpose
-Helpful when you want to manually open feedback (static forms) in your react application.
+## Purpose
+
+Use this package when you want to manually integrate and control Encatch feedback forms (static forms) in your React application with full programmatic access to form events.
 
 ## Resources
 
@@ -19,3 +20,262 @@ pnpm add @encatch/ws-react
 # or
 yarn add @encatch/ws-react
 ```
+
+## Features
+
+- **React Component**: `EncatchPreview` component for rendering forms
+- **Event Hooks**: React hooks for subscribing to form events
+- **Event Builder**: Declarative API for handling form lifecycle events
+- **TypeScript Support**: Full type safety with TypeScript definitions
+- **Automatic Cleanup**: Event subscriptions are automatically cleaned up on unmount
+- **Instance Filtering**: Filter events by specific form instances
+
+## Components
+
+### EncatchPreview
+
+The main component for rendering Encatch forms in your React application.
+
+```tsx
+import { EncatchPreview } from '@encatch/ws-react';
+
+function App() {
+  const formData = {
+    theme: 'default',
+    currentMode: 'light',
+    currentLanguage: 'en',
+    questions: [],
+    questionLanguages: [],
+    otherConfigurationProperties: {},
+    welcomeScreenProperties: {},
+    endScreenProperties: {},
+    translations: {},
+    sections: [],
+    themeSettings: null,
+    onClose: () => console.log('Form closed'),
+    onSectionChange: (index) => console.log('Section changed:', index),
+    apiKey: 'your-api-key',
+    hostUrl: 'https://api.encatch.com',
+    feedbackConfigId: 'your-config-id',
+    identifier: 'user-identifier',
+  };
+
+  return (
+    <EncatchPreview
+      formData={formData}
+      cssLink="https://your-styles.css"
+      scale={100}
+      persistMode="none"
+      instanceId="unique-form-id"
+    />
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `formData` | `object` | Yes | - | Form configuration object |
+| `cssLink` | `string` | Yes | - | URL to the form's CSS stylesheet |
+| `scale` | `number` | No | `100` | Scale factor for the form (percentage) |
+| `persistMode` | `"retain" \| "reset" \| "none"` | No | `"none"` | Form state persistence mode |
+| `instanceId` | `string` | No | - | Unique identifier for filtering events |
+| `onFormEvent` | `OnFormEventHandler` | No | - | Event handler builder function |
+
+### Event Handling with onFormEvent
+
+The `onFormEvent` prop provides a declarative way to handle form lifecycle events:
+
+```tsx
+import { EncatchPreview } from '@encatch/ws-react';
+
+function App() {
+  const handleFormEvents = (formEvent) => {
+    // Called when form is submitted
+    formEvent.onSubmit((data) => {
+      console.log('Form submitted:', data);
+    });
+
+    // Called when form is viewed/opened
+    formEvent.onView((data) => {
+      console.log('Form viewed:', data);
+    });
+
+    // Called when form is closed
+    formEvent.onClose((data) => {
+      console.log('Form closed:', data);
+    });
+
+    // Called when user navigates between sections
+    formEvent.onSectionChange((data) => {
+      console.log('Section changed to:', data.sectionIndex);
+    });
+
+    // Called when a question is answered
+    formEvent.onQuestionAnswered((data) => {
+      console.log('Question answered:', data.questionId, data.answer);
+    });
+
+    // Called when an error occurs
+    formEvent.onError((data) => {
+      console.log('Form error:', data.error);
+    });
+  };
+
+  return (
+    <EncatchPreview
+      formData={formData}
+      cssLink="https://your-styles.css"
+      instanceId="my-form"
+      onFormEvent={handleFormEvents}
+    />
+  );
+}
+```
+
+## Hooks
+
+### useEncatchFormEvent
+
+Subscribe to specific form events with automatic cleanup on unmount.
+
+```tsx
+import { useEncatchFormEvent } from '@encatch/ws-react';
+
+function MyComponent() {
+  // 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 (unsubscribe after first event)
+  useEncatchFormEvent('form:view', (payload) => {
+    console.log('Form viewed:', payload);
+  }, { formId: 'my-form-instance-1', once: true });
+
+  return <div>Your component</div>;
+}
+```
+
+#### Available Event Types
+
+- `form:submit` - Form submission event
+- `form:view` - Form viewed/opened event
+- `form:close` - Form closed event
+- `form:section:change` - Section navigation event
+- `form:question:answered` - Question answered event
+- `form:error` - Error event
+
+### useEncatchFormEventAll
+
+Subscribe to all form events with a single handler.
+
+```tsx
+import { useEncatchFormEventAll } from '@encatch/ws-react';
+
+function MyComponent() {
+  // 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' });
+
+  return <div>Your component</div>;
+}
+```
+
+## TypeScript Support
+
+The package includes full TypeScript definitions. Import types as needed:
+
+```tsx
+import type {
+  FormEventType,
+  FormEventPayload,
+  SubscriptionOptions,
+  FormIdFilter,
+  FormEventBuilder,
+  OnFormEventHandler,
+  OnSubmitCallback,
+  OnViewCallback,
+  OnCloseCallback,
+  OnSectionChangeCallback,
+  OnQuestionAnsweredCallback,
+  OnErrorCallback,
+} from '@encatch/ws-react';
+```
+
+## Persistence Modes
+
+The `persistMode` prop controls how form state is handled:
+
+- `"none"`: No persistence (default)
+- `"retain"`: Keep form state across remounts
+- `"reset"`: Clear state on remount
+
+## Best Practices
+
+1. **Use instanceId for multiple forms**: When rendering multiple forms, always provide unique `instanceId` values to filter events correctly.
+
+2. **Event filtering**: Use the `formId` option in hooks to subscribe only to events from specific form instances.
+
+3. **Choose the right API**:
+   - Use `onFormEvent` prop for component-scoped event handling
+   - Use hooks (`useEncatchFormEvent`) for app-level event handling
+
+4. **Memory management**: Event subscriptions are automatically cleaned up when components unmount.
+
+## Example: Multiple Forms
+
+```tsx
+import { EncatchPreview, useEncatchFormEvent } from '@encatch/ws-react';
+
+function MultiFormApp() {
+  // Listen to specific form events
+  useEncatchFormEvent('form:submit', (payload) => {
+    console.log('Survey submitted:', payload);
+  }, { formId: 'survey-form' });
+
+  useEncatchFormEvent('form:submit', (payload) => {
+    console.log('Feedback submitted:', payload);
+  }, { formId: 'feedback-form' });
+
+  return (
+    <>
+      <EncatchPreview
+        formData={surveyFormData}
+        cssLink="https://styles.css"
+        instanceId="survey-form"
+      />
+
+      <EncatchPreview
+        formData={feedbackFormData}
+        cssLink="https://styles.css"
+        instanceId="feedback-form"
+      />
+    </>
+  );
+}
+```
+
+## Dependencies
+
+- `react` >= 19.1.1 (peer dependency)
+- `react-dom` >= 19.1.1 (peer dependency)
+- `@encatch/schema` >= 0.1.31
+- `@encatch/event-publisher` (internal)
+- `@encatch/web-form-engine-core` (internal)
+
+## License
+
+See the main repository for license information.