Unvired TurboForms React Native & Web Embed SDK (@unvired/turboforms-rn-embed-sdk)

A high-performance, cross-platform React Native and Web wrapper for the Unvired TurboForms SDK. It allows you to seamlessly render complex dynamic forms, manage attachments, handle form lifecycle events, and customize themes across Android, iOS, and Web.

🌟 Key Features

• Cross-Platform: Runs on Android, iOS (via native WebView), and Web (via responsive ).
• Zero Native Web Overheads: Pure web bundle for browser environments without native shim dependencies.
• Embedded Engine: Includes the pre-bundled urboforms.html rendering engine (Form.io, Bootstrap 5, Recogito).
• Attachment Management: Built-in bidirectional handling for file attachments and IndexedDB caching.
• Full Form Lifecycle: Complete event callbacks for render, submit, save, validation, barcode, and location.
• TypeScript Support: Complete TypeScript declarations (.d.ts) included out of the box.

📦 Installation

ash npm install @unvired/turboforms-rn-embed-sdk

Peer Dependencies

Ensure you have the required peer dependencies installed in your project:

ash npm install react-native-safe-area-context react-native-webview (Note: eact-native-webview is only required for Android and iOS builds; Web builds use standard browser automatically).

⚙️ Platform-Specific Setup

1. Android Setup

Copy urboforms.html to your Android assets folder:

• Path: ndroid/app/src/main/assets/turboforms.html

Ensure standard permissions in AndroidManifest.xml (Camera, Location, Storage as needed).

2. iOS Setup

1. Copy urboforms.html to your iOS project folder / resources bundle or root ssets/turboforms.html.
2. Install CocoaPods: ash cd ios && pod install

3. Web (React Native Web) Setup

When building for the web (Webpack, Vite, or Next.js), serve urboforms.html as a static web asset:

Option A: Copy via Webpack (Recommended)

Add CopyWebpackPlugin to your webpack.config.js: `javascript const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = { plugins: [ new CopyWebpackPlugin({ patterns: [ { from: 'node_modules/@unvired/turboforms-rn-embed-sdk/dist/assets/turboforms.html', to: 'dist/assets/turboforms.html', }, ], }), ], }; `

Option B: Custom Path Prop

If you host urboforms.html on a custom path or CDN, pass the path prop: sx <SDKFormWrapper path= /assets/turboforms.html formsData={formTemplateJson} eventCallback={handleEvent} />

🚀 Basic Usage

` sx import React, { useRef } from 'react'; import { View, StyleSheet } from 'react-native'; import { SDKFormWrapper, FORM_EVENTS } from '@unvired/turboforms-rn-embed-sdk';

const MyFormScreen = () => { const formRef = useRef(null);

const handleEvent = (event) => { console.log('TurboForms Event:', event.type, event);

switch (event.type) {
  case FORM_EVENTS.FORM_RENDER:
    console.log('Form rendered successfully!');
    break;

  case FORM_EVENTS.SUBMIT:
    console.log('Form Submitted Data:', event.data?.formData);
    break;

  case FORM_EVENTS.SAVE:
    console.log('Form Saved Data:', event.data?.formData);
    break;

  case 'GET_ATTACHMENT':
    // Handle loading attachments from device storage or server
    break;

  case 'ERROR':
    console.error('Form Error:', event.errorMessage);
    break;
}

};

return ( <SDKFormWrapper ref={formRef} formsData={formTemplateJson} submissionData={existingFormDataJson} options={{ mode: 'render', themeData: { primaryColor: '#2586c7' }, userData: { firstName: 'Prashanth', lastName: 'Kumar', }, showBackButton: true, showMoreButton: true, permission: 'writemultiple', }} eventCallback={handleEvent} /> ); };

const styles = StyleSheet.create({ container: { flex: 1, }, });

export default MyFormScreen; `

📎 Attachment Lifecycle & Data Flows

The SDK handles attachments seamlessly between React Native and the embedded form's IndexedDB using two distinct flows:

Flow 1: Submitting/Saving Form & Resolving Attachments (Outbound)

When a user saves or submits a form:

1. The HTML form emits a FORM_SAVE or FORM_SUBMIT event.
2. SDKFormWrapper automatically resolves all files from IndexedDB.
3. The wrapper fires:
   • FORM_SAVE_START / FORM_SUBMIT_START: Show your app loading spinner.
   • FORM_SAVE / FORM_SUBMIT: Form data with attachments.
   • FORM_SAVE_ATTACH: Array of resolved base64 attachment objects.

Flow 2: Restoring Attachments for Existing Submissions (Inbound)

When opening a draft or existing submission with remote files:

1. The SDK emits GET_ATTACHMENT with a list of missing ileIds.
2. Fetch the corresponding base64 files and pass them to AttachmentManager: sx if (event.type === 'GET_ATTACHMENT') { const missing = event.data.missingFiles; const attachments = missing.map(file => ({ fileId: file.fileId, id: file.fileId, name: 'Attachment_' + file.fileId + '.png', size: 1024, type: 'image/png', url: 'data:image/png;base64,...', mode: 'G', })); AttachmentManager.saveMultipleToIndexedDB(formRef, attachments); }
3. When injection completes, the SDK fires ATTACHMENT_SAVED. Call ormRef.current?.reloadForm() to display the restored images.

📋 Props & Options

SDKFormWrapper Props

| Prop | Type | Description | | :--- | :--- | :--- | | ormsData | string | object | The Form.io JSON form schema. | | submissionData | object | Initial / draft submission data to populate the fields. | | eventCallback | unction | Callback receiving all form lifecycle events. | | path | string | (Optional, Web only) Custom URL/path to urboforms.html. | | options | LoadUnviredFormsOptions | Configuration options (see below). | | logLevel | 'debug' | 'info' | 'warn' | 'error' | 'none' | Minimum log level forwarded from the iframe/webview. |

options Configuration Object

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | mode | string | 'render' | Form mode ('render', 'form', 'readOnly', 'pdf', 'print'). | | hemeData | object | {} | Custom styling and theme colors (primaryColor, isCard, etc.). | | userData | object | undefined | User identity info (irstName, lastName, etc.). | | estedFormData| Array | [] | Nested sub-form schemas. | | masterData | Array | [] | Master data dropdown caches. | | commentsData | Array | [] | Recogito annotations/comments array. | | showBackButton| oolean | rue | Show/hide the top back arrow button. | | showMoreButton| oolean | rue | Show/hide the three-dots action menu. | | permission | string | 'writemultiple' | User permission mode ('writemultiple', 'writesingle', 'read'). |

⚡ Ref Methods

Attach a React ef to to access imperative controls:

• ** eloadForm()**: Refreshes and re-injects the current payload into the form.
• injectJavaScript(script: string): Executes custom JavaScript inside the WebView/iframe context.

🛠️ Building the SDK from Source

To build the npm distribution package:

ash cd react-native-forms-embed-sdk npm install npm run build

This compiles:

1. dist/index.js & dist/index.d.ts (Entry point)
2. dist/src/SDKFormWrapper.js & .d.ts (Native bundle)
3. dist/src/SDKFormWrapper.web.js & .d.ts (Web bundle)
4. dist/assets/turboforms.html (Compiled engine)

📄 License

Unvired Inc. All rights reserved.