vanilajs-form-lib/README.md

Reusable vanilla JS form library that works with React, Angular, Ionic, etc.

# unvired-forms-lib

A lightweight, framework-agnostic JavaScript library for rendering [Form.io](https://form.io/) JSON schema-based forms inside an `<iframe>`. Works seamlessly in any modern web framework — **React.js**, **Angular**, **Ionic**, or any **browser-based app**. Includes built-in support for geolocation, camera/file uploads, and barcode scanning, with easy integration via `postMessage` and custom DOM events.

---


## 🌟 Features

- Renders Form.io JSON schema-based forms inside an `<iframe>`
- Automatically handles:
  - 📍 Geolocation
  - 📷 Camera and file attachments
  - 📦 Barcode scanning
- Framework-agnostic: works in React, Angular, Ionic, Cordova, or any vanilla JS app
- Communication via `postMessage` and custom DOM events
- Simple integration and extensible event system

---


## 📦 Installation

Clone the repository:

```bash
git clone <repo-url>
cd unvired-forms-lib
```

---


## 🛠 Build the Library

If you make changes to the form rendering logic, rebuild the library:

```bash
npm install
npm run build
```

This will regenerate the `dist/unvired-formio-lib.js` file used in the iframe.

---


## 🧩 Usage

Embed the form using an `<iframe>` in your HTML/React/Angular/Ionic app:

```html
<iframe
  id="form-frame"
  src="/path/to/dist/unvired-formio-lib.js"
  title="Form Iframe"
  width="100%"
  height="100%"
  style="border: none;"
></iframe>
```

### Loading the Form Template

Send the form template to the iframe after it loads:

```js
const iframe = document.getElementById("form-frame");

const sendTemplate = () => {
  iframe.contentWindow.postMessage(
    {
      type: "LOAD_FORM_TEMPLATE",
      template: yourFormJsonTemplate,
      semantic: yourSemanticData, // optional
    },
    "*"
  );
};

iframe.addEventListener("load", sendTemplate);
```

### Handling Messages from the Form

Listen for submit, error, or navigation events:

```js
window.addEventListener("message", (event) => {
  const data =
    typeof event.data === "string" ? JSON.parse(event.data) : event.data;

  switch (data?.type) {
    case "FORM_BACK_NAVIGATION":
      window.history.back();
      break;
    case "FORM_SUBMIT_RESULT":
      console.log("✅ Submitted Data:", data.payload);
      break;
    case "FORM_SUBMIT":
      console.log("📤 Submit Triggered");
      break;
    case "FORM_SUBMIT_ERROR":
      console.error("❌ Submit Error:", data?.data);
      break;
  }
});
```

---


## 🧩 Event Constants

```js
const FORM_EVENTS = {
  FORM_RENDER: "FORM_RENDER",
  SAVE: "FORM_SAVE",
  SUBMIT: "FORM_SUBMIT",
  SUBMIT_ERROR: "FORM_SUBMIT_ERROR",
  BACK_NAVIGATION: "FORM_BACK_NAVIGATION",
  ONCHANGE: "FORM_ONCHANGE",
};
```

---


## 🔐 Security Note

For production, replace `"*"` in `postMessage` calls with a specific target origin for enhanced security.

---


## 🧪 Compatibility

- ✅ React.js (v17+)
- ✅ Angular (v12+)
- ✅ Ionic (v5+ with Capacitor)
- ✅ Cordova WebView
- ✅ Vanilla JS / HTML

---


## 📁 Folder Structure (Overview)

- `dist/` — Compiled library output (use this in your app)
- `src/` — Source code for the form renderer and supporting logic
- `example/` — Example templates, assets, and demo HTML
- `scripts/` — Build scripts and utilities
- `README.md` — Project documentation
- `package.json` — Project metadata and scripts

---


## 📝 License

[MIT](LICENSE)