@unvired/turboforms-embed-sdk 1.0.10 → 1.0.12

package/README.md

@@ -231,6 +231,10 @@ document.addEventListener('deviceready', function() {
 | `userData` | object | User context data |
 | `appData` | object | Application data |
 | `environmentVariable` | array | Environment variables |
+| `privateExternal` | boolean/string | Controls form visibility logic (Private/Public) |
+| `permission` | string | Access permission ('writesingle', 'writemultiple', 'read') |
+| `controlData` | object | Data for initial control values |
+| `showLoader` | boolean | Show/hide initial SDK loading spinner |
 
 ### Event Types
 
@@ -247,6 +251,64 @@ document.addEventListener('deviceready', function() {
 | `GET_ATTACHMENT` | Attachment request |
 | `ERROR` | Error occurred |
 
+## ✅ Button Visibility & Enablement
+
+| privateExternal    | Permission      | Main Toolbar Button        | More Options (Dropdown)         | Enable / Disable Rule                              |
+| ------------------ | --------------- | -------------------------- | ------------------------------- | -------------------------------------------------- |
+| **false (Public)** | `writesingle`   | **Submit** (`submitBtn`)   | None                            | Enabled when **any field is filled**               |
+| **false (Public)** | `writemultiple` | **Submit** (`submitBtn`)   | None                            | Enabled when **any field is filled**               |
+| **true (Private)** | `writemultiple` | **Save** (`saveBtn`)       | **Complete** (`completeOption`) | Save enabled when **any field is filled**          |
+| **true (Private)** | `writesingle`   | **Complete** (`submitBtn`) | **Save** (`saveOption`)         | Complete enabled **ONLY when form is 100% filled** |
+| **Any**            | `read`          | None                       | None                            | N/A (Read-only mode)                               |
+
+## 🧭 “More Options” Dropdown Logic
+
+### ▶ **Complete appears in More Options**
+
+* **Condition:**
+  `privateExternal = true` **AND** `permission = writemultiple`
+* **Reason:**
+  Allows **partial saves** via main **Save** button
+  Final submission (**Complete**) is optional and secondary
+
+### ▶ **Save appears in More Options**
+
+* **Condition:**
+  `privateExternal = true` **AND** `permission = writesingle`
+* **Reason:**
+  Forces **100% completion** via main **Complete** button
+  Save is available only as a fallback action
+
+## 🔑 Core Behavioral Rules
+
+* **Public forms** → Always **Submit**, enabled after any input
+* **Private + writemultiple** → **Save first**, Complete optional
+* **Private + writesingle** → **Complete mandatory**, Save optional
+* **Read permission** → No actions shown
+
+## 📂 File Attachment Architecture & Modes
+
+The SDK employs a robust local-first strategy using **IndexedDB** for offline storage and persistence. To track the exact state of every file or image across its entire lifecycle (from server to local device to edits to deletion), the SDK uniquely assigns a synchronization `mode` to each file.
+
+### Mode Classification
+
+| Mode | Name | Description |
+|---|---|---|
+| **`"A"`** | **Added (New)** | Represents a brand new file uploaded locally. Newly taken photos, selected files from the gallery, or newly cropped/edited images default to this state. |
+| **`"G"`** | **Got (Downloaded)** | Represents a file that previously existed and was downloaded from the server API. The API dictates this mode, and the SDK recognizes it. By default, any file reconstructed from IndexedDB that lacks a mode tag assumes `"G"`. |
+| **`"D"`** | **Deleted** | Represents an attachment that was marked as deleted by the user clicking the trash icon. The system physically flags the file in the database rather than removing the row entirely, permitting the host app to notify the server of the deletion upon final sync. |
+
+### Working Flow: Cropping or Editing an Image
+
+When a user crops or annotates an existing server image or local image, the SDK executes the following sequence:
+
+1. **In-Memory Capture**: The crop/annotation tool creates a brand new physical `Blob` containing the updated image metadata safely in RAM.
+2. **New DB Entry Created**: The SDK assigns a fresh UUID to the newly cropped image and stores it inside the IndexedDB as a completely individual brand new file with `mode: "A"`.
+3. **Original File Deleted**: To preserve device storage and state integrity, the SDK locates the original file's UUID corresponding to the un-cropped image and physically deletes it out of the IndexedDB via a `deleteOriginalFileFromDB` listener event.
+4. **Memory Re-linking**: The form component's memory immediately reflects the presence of the new file object bearing mode `"A"` substituted into the form submission pipeline.
+
+This process simplifies the architecture: edits simply generate brand new files, offloading any complex diffing logic to the main application server layer.
+
 ## 🔧 Form Instance Methods
 
 The `loadUnviredForms` function returns a FormInstance object with the following methods:
@@ -321,7 +383,7 @@ loadUnviredForms({
     eventCallback: function(event) {
         if (event.type === 'ERROR') {
             switch (event.errorMessage) {
-                case 'Error Code 001 contact your admin':
+                case 'Error Code 001 contact your admin or tech team':
                     console.error('Invalid formsData JSON');
                     break;
                 case 'Error Code 004 contact your admin':
@@ -364,6 +426,17 @@ loadUnviredForms({
 - Use HTTPS in production environments
 - Sanitize user inputs to prevent XSS attacks
 
+## 🧪 Platform Compatibility
+
+| Platform | Version | Status |
+|----------|---------|--------|
+| React.js | 16.8+ | ✅ Fully Supported |
+| Angular | 12+ | ✅ Fully Supported |
+| Vue.js | 3.0+ | ✅ Fully Supported |
+| Ionic | 5+ | ✅ Fully Supported |
+| Cordova | 9+ | ✅ Fully Supported |
+| Vanilla JS | ES6+ | ✅ Fully Supported |
+
 ## 🛠 Build Process
 
 ### Development Setup
@@ -395,18 +468,4 @@ The build process generates:
 - `dist/index.d.ts` - TypeScript definitions
 - `dist/assets/` - FormIO library and UI assets
 
-## 🧪 Platform Compatibility
-
-| Platform | Version | Status |
-|----------|---------|--------|
-| React.js | 16.8+ | ✅ Fully Supported |
-| Angular | 12+ | ✅ Fully Supported |
-| Vue.js | 3.0+ | ✅ Fully Supported |
-| Ionic | 5+ | ✅ Fully Supported |
-| Cordova | 9+ | ✅ Fully Supported |
-| Vanilla JS | ES6+ | ✅ Fully Supported |
-
-
 ## 📝 License
-
-[MIT](LICENSE) - See LICENSE file for details.