@craftthingy-digital-innovation/cty-smart-merge-sync-web 1.0.0

package/LICENSE

@@ -0,0 +1,38 @@
+Public-Source Corporate Royalty License (PSCRL)
+
+Copyright (c) 2026 Alif Nurhidayat (alifnurhidayatwork@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction for non-commercial, personal, educational,
+research, and open-source public use, subject to the following conditions:
+
+1. NON-COMMERCIAL & PUBLIC USE
+The Software is completely free to use, modify, and distribute for individuals,
+educational institutions, personal research, testing, and non-commercial open-source
+projects.
+
+2. CORPORATE & COMMERCIAL BUSINESS USE
+Any use of the Software by for-profit companies, corporations, commercial applications,
+SaaS (Software as a Service) platforms, or for any revenue-generating activity
+requires a commercial licensing agreement. 
+
+By using this Software for commercial or corporate purposes, you agree to:
+a. Pay a royalty fee of 1% (one percent) of the gross monthly revenue generated by
+   any product, service, or platform that incorporates or uses this Software.
+b. Startups or businesses with gross annual revenues of less than $10,000 USD (or equivalent)
+   are exempt from royalties until they exceed this threshold.
+c. Provide quarterly reporting of gross revenues generated to the copyright holder.
+
+3. CONTACT & CUSTOM LICENSING
+For royalty payments, reporting, custom enterprise flat-rate licenses, or general inquiries,
+contact the copyright holder directly at:
+alifnurhidayatwork@gmail.com
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @craftthingy-digital-innovation/cty-smart-merge-sync-web
+
+Bilingual documentation: [Bahasa Indonesia](#bahasa-indonesia) | [English](#english)
+
+---
+
+## Bahasa Indonesia
+
+Library client-side Javascript untuk menangani kolaborasi sinkronisasi data real-time multi-user. Menggunakan algoritma **Smart Merge** untuk menyinkronkan data perubahan server tanpa merusak kursor ketik aktif pengguna (`document.activeElement`) dan tanpa menimpa perubahan lokal yang sedang mengantre di outbox.
+
+Sangat cocok untuk merancang UI kolaboratif seperti Google Sheets, dashboard multi-user, atau sistem input data bersama.
+
+### Instalasi
+```bash
+npm install @craftthingy-digital-innovation/cty-smart-merge-sync-web
+```
+
+### Cara Penggunaan
+```javascript
+import { SmartSyncEngine } from '@craftthingy-digital-innovation/cty-smart-merge-sync-web';
+
+const syncEngine = new SmartSyncEngine({
+  interval: 4000, // Ambil data dari server setiap 4 detik
+  fetchData: async () => {
+    const res = await fetch('/api/entries');
+    const result = await res.json();
+    return result.data; // Mengembalikan array data terbaru
+  },
+  isPendingLocal: (uuid, field) => {
+    // Return true jika baris/kolom ini sedang memiliki antrean simpan offline
+    return myOfflineQueue.hasPending(uuid, field);
+  },
+  fields: ['no_paspor', 'nama_pemohon', 'tempat_lahir'] // Kolom yang disinkronkan
+});
+
+// Jalankan polling sinkronisasi
+syncEngine.start();
+
+syncEngine.on('sync', (remoteList) => {
+  // Gabungkan data remote ke state lokal & perbarui DOM secara aman
+  syncEngine.merge(localEntries, remoteList, {
+    onAdd: (newItem) => {
+      // Tambahkan baris baru ke tabel DOM Anda
+      appendRowToTableDOM(newItem);
+    },
+    onDelete: (uuid) => {
+      // Hapus baris dari tabel DOM Anda
+      removeRowFromTableDOM(uuid);
+    },
+    onUpdateField: (uuid, field, val) => {
+      // Perbarui nilai input kolom spesifik di DOM
+      const input = document.querySelector(`tr[data-uuid="${uuid}"] .field-${field}`);
+      if (input) input.value = val;
+    }
+  });
+});
+```
+
+---
+
+## English
+
+A client-side JavaScript library to coordinate real-time multi-user data synchronization. Employs a **Smart Merge** algorithm to merge database updates without causing cursor jumps, losing user's focus (`document.activeElement`), or overwriting pending local outbox edits.
+
+Perfect for collaborative UIs such as shared spreadsheets, multi-user dashboards, or shared forms.
+
+### Installation
+```bash
+npm install @craftthingy-digital-innovation/cty-smart-merge-sync-web
+```
+
+### Usage
+```javascript
+import { SmartSyncEngine } from '@craftthingy-digital-innovation/cty-smart-merge-sync-web';
+
+const syncEngine = new SmartSyncEngine({
+  interval: 4000, // Poll server every 4 seconds
+  fetchData: async () => {
+    const res = await fetch('/api/entries');
+    const result = await res.json();
+    return result.data; // Return latest remote array
+  },
+  isPendingLocal: (uuid, field) => {
+    // Return true if this row/field has pending local saves in your outbox
+    return myOfflineQueue.hasPending(uuid, field);
+  },
+  fields: ['no_paspor', 'nama_pemohon', 'tempat_lahir'] // Fields to merge
+});
+
+// Start collaboration polling
+syncEngine.start();
+
+syncEngine.on('sync', (remoteList) => {
+  // Merge remote data into local state & DOM safely
+  syncEngine.merge(localEntries, remoteList, {
+    onAdd: (newItem) => {
+      // Add new row to your table DOM
+      appendRowToTableDOM(newItem);
+    },
+    onDelete: (uuid) => {
+      // Remove row from your table DOM
+      removeRowFromTableDOM(uuid);
+    },
+    onUpdateField: (uuid, field, val) => {
+      // Update specific input element value in the DOM
+      const input = document.querySelector(`tr[data-uuid="${uuid}"] .field-${field}`);
+      if (input) input.value = val;
+    }
+  });
+});
+```

package/dist/cty-smart-merge-sync.es.js

@@ -0,0 +1,56 @@
+class p extends EventTarget {
+  constructor(n = {}) {
+    super(), this.fetchData = n.fetchData || null, this.interval = n.interval || 4e3, this.isPendingLocal = n.isPendingLocal || (() => !1), this.fields = n.fields || [], this.timer = null;
+  }
+  /**
+   * Starts the collaboration sync polling
+   */
+  start() {
+    this.timer || (this.timer = setInterval(async () => {
+      if (typeof this.fetchData == "function")
+        try {
+          const n = await this.fetchData();
+          this.dispatchEvent(new CustomEvent("sync", { detail: n }));
+        } catch (n) {
+          this.dispatchEvent(new CustomEvent("error", { detail: n }));
+        }
+    }, this.interval));
+  }
+  /**
+   * Stops the polling
+   */
+  stop() {
+    this.timer && (clearInterval(this.timer), this.timer = null);
+  }
+  /**
+   * Merges remote data changes into a local data list while protecting user input focus
+   * @param {Array} localList The current local state array
+   * @param {Array} remoteList The remote state array fetched from server
+   * @param {object} callbacks Event handlers: { onAdd(item), onDelete(uuid), onUpdateField(uuid, field, val) }
+   */
+  merge(n, o, s = {}) {
+    const a = typeof document < "u" ? document.activeElement : null, c = o.map((t) => t.uuid);
+    for (let t = n.length - 1; t >= 0; t--) {
+      const d = n[t], e = d.id !== null && d.id !== void 0, h = c.includes(d.uuid), i = this.isPendingLocal(d.uuid);
+      e && !h && !i && (n.splice(t, 1), typeof s.onDelete == "function" && s.onDelete(d.uuid));
+    }
+    return o.forEach((t) => {
+      const d = n.findIndex((e) => e.uuid === t.uuid);
+      if (d === -1)
+        n.push(t), typeof s.onAdd == "function" && s.onAdd(t, n.length);
+      else {
+        const e = n[d];
+        this.fields.forEach((i) => {
+          const u = t[i], f = a && a.classList.contains(`field-${i}`) && a.closest(`[data-uuid="${t.uuid}"]`), r = this.isPendingLocal(t.uuid, i);
+          !f && !r ? e[i] !== u && (e[i] = u, typeof s.onUpdateField == "function" && s.onUpdateField(t.uuid, i, u, t)) : e[i] = u;
+        }), ["id", "tanggal_input", "foto_ttd"].forEach((i) => {
+          t.hasOwnProperty(i) && e[i] !== t[i] && (e[i] = t[i], typeof s.onUpdateMeta == "function" && s.onUpdateMeta(t.uuid, i, t[i], t));
+        });
+      }
+    }), this.dispatchEvent(new CustomEvent("merged", { detail: { localList: n } })), n;
+  }
+}
+typeof window < "u" && (window.SmartSyncEngine = p);
+export {
+  p as SmartSyncEngine
+};

package/dist/cty-smart-merge-sync.umd.js

@@ -0,0 +1 @@
+(function(u,o){typeof exports=="object"&&typeof module<"u"?o(exports):typeof define=="function"&&define.amd?define(["exports"],o):(u=typeof globalThis<"u"?globalThis:u||self,o(u.SmartMerge={}))})(this,function(u){"use strict";class o extends EventTarget{constructor(n={}){super(),this.fetchData=n.fetchData||null,this.interval=n.interval||4e3,this.isPendingLocal=n.isPendingLocal||(()=>!1),this.fields=n.fields||[],this.timer=null}start(){this.timer||(this.timer=setInterval(async()=>{if(typeof this.fetchData=="function")try{const n=await this.fetchData();this.dispatchEvent(new CustomEvent("sync",{detail:n}))}catch(n){this.dispatchEvent(new CustomEvent("error",{detail:n}))}},this.interval))}stop(){this.timer&&(clearInterval(this.timer),this.timer=null)}merge(n,c,s={}){const f=typeof document<"u"?document.activeElement:null,r=c.map(t=>t.uuid);for(let t=n.length-1;t>=0;t--){const d=n[t],i=d.id!==null&&d.id!==void 0,h=r.includes(d.uuid),e=this.isPendingLocal(d.uuid);i&&!h&&!e&&(n.splice(t,1),typeof s.onDelete=="function"&&s.onDelete(d.uuid))}return c.forEach(t=>{const d=n.findIndex(i=>i.uuid===t.uuid);if(d===-1)n.push(t),typeof s.onAdd=="function"&&s.onAdd(t,n.length);else{const i=n[d];this.fields.forEach(e=>{const a=t[e],p=f&&f.classList.contains(`field-${e}`)&&f.closest(`[data-uuid="${t.uuid}"]`),l=this.isPendingLocal(t.uuid,e);!p&&!l?i[e]!==a&&(i[e]=a,typeof s.onUpdateField=="function"&&s.onUpdateField(t.uuid,e,a,t)):i[e]=a}),["id","tanggal_input","foto_ttd"].forEach(e=>{t.hasOwnProperty(e)&&i[e]!==t[e]&&(i[e]=t[e],typeof s.onUpdateMeta=="function"&&s.onUpdateMeta(t.uuid,e,t[e],t))})}}),this.dispatchEvent(new CustomEvent("merged",{detail:{localList:n}})),n}}typeof window<"u"&&(window.SmartSyncEngine=o),u.SmartSyncEngine=o,Object.defineProperty(u,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@craftthingy-digital-innovation/cty-smart-merge-sync-web",
+  "version": "1.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CraftThingy-Digital-Innovation/cty-smart-merge-sync-web.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CraftThingy-Digital-Innovation/cty-smart-merge-sync-web/issues"
+  },
+  "homepage": "https://github.com/CraftThingy-Digital-Innovation/cty-smart-merge-sync-web#readme",
+  "main": "./dist/cty-smart-merge-sync.umd.js",
+  "module": "./dist/cty-smart-merge-sync.es.js",
+  "exports": {
+    ".": {
+      "import": "./dist/cty-smart-merge-sync.es.js",
+      "require": "./dist/cty-smart-merge-sync.umd.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vite": "^5.2.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,129 @@
+/**
+ * cty-smart-merge-sync-web
+ * Smart Merge Collaboration Engine
+ * Public-Source Corporate Royalty License (PSCRL)
+ * Copyright (c) 2026 CraftThingy Digital Innovation & Alif Nurhidayat
+ */
+
+export class SmartSyncEngine extends EventTarget {
+  constructor(options = {}) {
+    super();
+    this.fetchData = options.fetchData || null; // Async function returning remote list
+    this.interval = options.interval || 4000;
+    this.isPendingLocal = options.isPendingLocal || (() => false); // Check if field has pending outbox updates
+    this.fields = options.fields || []; // Array of field names to merge
+    
+    this.timer = null;
+  }
+
+  /**
+   * Starts the collaboration sync polling
+   */
+  start() {
+    if (this.timer) return;
+    
+    this.timer = setInterval(async () => {
+      if (typeof this.fetchData !== 'function') return;
+      try {
+        const remoteList = await this.fetchData();
+        this.dispatchEvent(new CustomEvent('sync', { detail: remoteList }));
+      } catch (err) {
+        this.dispatchEvent(new CustomEvent('error', { detail: err }));
+      }
+    }, this.interval);
+  }
+
+  /**
+   * Stops the polling
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Merges remote data changes into a local data list while protecting user input focus
+   * @param {Array} localList The current local state array
+   * @param {Array} remoteList The remote state array fetched from server
+   * @param {object} callbacks Event handlers: { onAdd(item), onDelete(uuid), onUpdateField(uuid, field, val) }
+   */
+  merge(localList, remoteList, callbacks = {}) {
+    const activeEl = typeof document !== 'undefined' ? document.activeElement : null;
+    const remoteUuids = remoteList.map(item => item.uuid);
+
+    // 1. Process Deletions
+    for (let i = localList.length - 1; i >= 0; i--) {
+      const local = localList[i];
+      // If it is saved on server, but not in remote list, and not pending local save, it was deleted
+      const isSaved = local.id !== null && local.id !== undefined;
+      const inRemote = remoteUuids.includes(local.uuid);
+      const hasPending = this.isPendingLocal(local.uuid);
+
+      if (isSaved && !inRemote && !hasPending) {
+        localList.splice(i, 1);
+        if (typeof callbacks.onDelete === 'function') {
+          callbacks.onDelete(local.uuid);
+        }
+      }
+    }
+
+    // 2. Process Additions and Updates
+    remoteList.forEach((remote) => {
+      const localIdx = localList.findIndex(e => e.uuid === remote.uuid);
+
+      if (localIdx === -1) {
+        // New record added by another client
+        localList.push(remote);
+        if (typeof callbacks.onAdd === 'function') {
+          callbacks.onAdd(remote, localList.length);
+        }
+      } else {
+        const local = localList[localIdx];
+
+        // Merge fields
+        this.fields.forEach((field) => {
+          const remoteVal = remote[field];
+          
+          // Focus and outbox pending check
+          const isFocused = activeEl && 
+                            activeEl.classList.contains(`field-${field}`) && 
+                            activeEl.closest(`[data-uuid="${remote.uuid}"]`);
+          const isPending = this.isPendingLocal(remote.uuid, field);
+
+          if (!isFocused && !isPending) {
+            const oldVal = local[field];
+            if (oldVal !== remoteVal) {
+              local[field] = remoteVal;
+              if (typeof callbacks.onUpdateField === 'function') {
+                callbacks.onUpdateField(remote.uuid, field, remoteVal, remote);
+              }
+            }
+          } else {
+            // Keep remote state updated in background cache but don't overwrite user's typing
+            local[field] = remoteVal;
+          }
+        });
+
+        // Merge non-input attributes (e.g. ID, created time, signature files)
+        const metaFields = ['id', 'tanggal_input', 'foto_ttd'];
+        metaFields.forEach(field => {
+          if (remote.hasOwnProperty(field) && local[field] !== remote[field]) {
+            local[field] = remote[field];
+            if (typeof callbacks.onUpdateMeta === 'function') {
+              callbacks.onUpdateMeta(remote.uuid, field, remote[field], remote);
+            }
+          }
+        });
+      }
+    });
+
+    this.dispatchEvent(new CustomEvent('merged', { detail: { localList } }));
+    return localList;
+  }
+}
+
+if (typeof window !== 'undefined') {
+  window.SmartSyncEngine = SmartSyncEngine;
+}