@modernman00/shared-js-lib 1.2.76 → 1.2.78

package/Clipboard.js

@@ -0,0 +1,45 @@
+'use strict';
+import { swalToast, swalError } from './Alert.js';
+
+/**
+ * Universal clipboard copy utility with automatic SweetAlert2 toast feedback.
+ * 
+ * @param {string} text - Text to copy
+ * @param {string} [successMessage='Copied to clipboard!'] - Custom toast notification
+ * @param {boolean} [showToast=true] - Whether to fire Swal toast
+ * @returns {Promise<boolean>} True if copy was successful
+ */
+export const copyToClipboard = async (
+  text,
+  successMessage = 'Copied to clipboard!',
+  showToast = true
+) => {
+  if (typeof window === 'undefined') return false;
+
+  try {
+    if (navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+      await navigator.clipboard.writeText(text);
+    } else {
+      // Fallback for older browsers
+      const textarea = document.createElement('textarea');
+      textarea.value = text;
+      textarea.style.position = 'fixed';
+      textarea.style.left = '-9999px';
+      document.body.appendChild(textarea);
+      textarea.select();
+      document.execCommand('copy');
+      document.body.removeChild(textarea);
+    }
+
+    if (showToast) {
+      swalToast(successMessage, 'success', 2500);
+    }
+    return true;
+  } catch (err) {
+    console.error('copyToClipboard Error:', err);
+    if (showToast) {
+      swalError('Failed to copy text to clipboard.', false);
+    }
+    return false;
+  }
+};

package/Cookie.js

@@ -28,25 +28,7 @@ export const getCookie = (cname) => {
 
 
 
-/**
- * Checks if a cookie with the given name exists. If not, prompts the user
- * for a name and sets the cookie for 365 days. If the cookie does exist,
- * alerts the user with a welcome message.
- * @param {string} name - The name of the cookie to check.
- */
-export const checkCookie = (name) => {
-    let user = getCookie(name);
-    if (!user) {
-        const askName = prompt("Please enter your name:", "");
-        if (askName) {
-            setCookie(name, askName, 365);
-            user = askName;
-        }
-    }
-    if (user) {
-        alert(`Welcome again ${user}`);
-    }
-}
+
 
 // CHECK TOKEN FROM COOKIE 
 export const getCookieValue = (name) => {

package/FormLock.js

@@ -0,0 +1,58 @@
+'use strict';
+import { swalToast, swalWarning } from './Alert.js';
+
+/**
+ * Registry of active in-flight locks keyed by form ID or URL.
+ */
+const inFlightLocks = new Set();
+
+/**
+ * Checks if an operation is currently locked.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isOperationLocked = (key) => inFlightLocks.has(key);
+
+/**
+ * Acquires a lock for a key. Returns true if acquired, false if already in flight.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const acquireLock = (key) => {
+  if (inFlightLocks.has(key)) return false;
+  inFlightLocks.add(key);
+  return true;
+};
+
+/**
+ * Releases a lock for a key.
+ * @param {string} key
+ */
+export const releaseLock = (key) => {
+  inFlightLocks.delete(key);
+};
+
+/**
+ * Guard utility to prevent concurrent or rapid double-submissions.
+ * 
+ * @param {string} lockKey - Unique identifier (e.g. formId or URL)
+ * @param {() => Promise<any>} asyncFn - Async action to run exclusively
+ * @param {string} [busyMessage='Please wait, an operation is already in progress...']
+ * @returns {Promise<any>}
+ */
+export const withSubmissionLock = async (
+  lockKey,
+  asyncFn,
+  busyMessage = 'Please wait, an operation is already in progress...'
+) => {
+  if (!acquireLock(lockKey)) {
+    swalToast(busyMessage, 'warning', 2500);
+    return null;
+  }
+
+  try {
+    return await asyncFn();
+  } finally {
+    releaseLock(lockKey);
+  }
+};

package/Http.js

@@ -1,90 +1,191 @@
 import { id, log } from './UtilityHtml.js';
 import axios from './axiosWrapper.js';
 import { redirectAfterDelay, parseErrorResponse } from './general.js';
+import { swalSuccess, swalError, swalToast } from './Alert.js';
+import { setButtonLoading, clearButtonLoading } from './ButtonLoader.js';
+import { acquireLock, releaseLock } from './FormLock.js';
+import { isOnline } from './NetworkGuard.js';
 
 /**
+ * Sends form data via POST request with automatic button spinner, SweetAlert2 alerts, and robust error handling.
+ * 
+ * Can be called with positional arguments (backward-compatible):
+ *   postFormData(url, formId, redirect, css, recaptchaToken, button)
+ * 
+ * Or with a modern config object:
+ *   postFormData(url, formId, { redirect, css, button, recaptchaToken, resetForm })
  * 
-* Sends form data via POST request.
  * @param {string} url - The URL to post the data to.
- * @param {string} formId - The ID or class of the form.
- * @param {string|null} redirect - The page to redirect to after successful submission.
- * @param {string|null} css - The CSS framework to use for notification styling (e.g., 'W3css', 'bulma').
- NOTICE:::Make sure you set the notification id as the formId_notification
-  * @param {Object} [options.recaptchaV3=null] - reCAPTCHA v3 configuration ({ siteKey: 'OUR_ENTERPRISE_SITE_KEY', action: 'LOGIN' }).
+ * @param {string|HTMLFormElement} formId - The ID string or DOM element of the form.
+ * @param {string|Object|null} [redirectOrOptions=null] - Redirect URL, or options configuration object.
+ * @param {string|null} [css=null] - CSS framework ('bootstrap', 'bulma', 'W3css', 'tailwind').
+ * @param {Object|null} [recaptchaToken=null] - reCAPTCHA token payload ({ token, action }).
+ * @param {string|HTMLElement|null} [button=null] - Specific button ID or element to show spinner on.
+ * @returns {Promise<Object>} Axios response object on success.
  */
-export const postFormData = async (url, formId, redirect = null, css = null, recaptchaToken = null) => {
+export const postFormData = async (
+    url,
+    formId,
+    redirectOrOptions = null,
+    css = null,
+    recaptchaToken = null,
+    button = null
+) => {
+    // Determine if third argument is an options object
+    const isOptionsObj = redirectOrOptions !== null && typeof redirectOrOptions === 'object';
+    const redirect = isOptionsObj ? redirectOrOptions.redirect : redirectOrOptions;
+    const themeCss = isOptionsObj ? (redirectOrOptions.css || css) : css;
+    const recaptcha = isOptionsObj ? (redirectOrOptions.recaptchaToken || recaptchaToken) : recaptchaToken;
+    const buttonTarget = isOptionsObj ? (redirectOrOptions.button || button) : button;
+    const shouldResetForm = isOptionsObj && typeof redirectOrOptions.resetForm === 'boolean'
+        ? redirectOrOptions.resetForm
+        : true;
+
+    // 1. Connectivity Check
+    if (!isOnline()) {
+        swalToast('No internet connection. Please check your network and retry.', 'warning', 4000);
+        return { error: true, message: 'Offline' };
+    }
 
-        const loader = id('setLoader');
-        if (loader) loader.style.display = 'block';
+    // 2. Double-Submit Protection Lock
+    const lockKey = `${url}::${typeof formId === 'string' ? formId : (formId.id || 'form')}`;
+    if (!acquireLock(lockKey)) {
+        swalToast('Please wait, a submission is already in progress...', 'warning', 2500);
+        return { error: true, message: 'In flight' };
+    }
 
-    let notificationForm = `${formId}_notification`;
-    const notificationId = id(notificationForm);
+    // Resolve form element
+    const form = typeof formId === 'string' ? id(formId) : formId;
+    if (!form) {
+        releaseLock(lockKey);
+        throw new Error('Form element not found');
+    }
 
-    
-    if (!notificationId) {
-        throw new Error('Notification element not found');
+    // Resolve button for spinner:
+    // Works with any button type: type="button", type="submit", or no type.
+    let btnEl = null;
+    if (buttonTarget) {
+        btnEl = typeof buttonTarget === 'string'
+            ? (id(buttonTarget.replace(/^#/, '')) || document.querySelector(buttonTarget))
+            : buttonTarget;
+    }
+    if (!btnEl && form instanceof HTMLFormElement) {
+        // Smart fallback priority:
+        // 1. type="submit" or input submit
+        // 2. Any button with common action classes or IDs (save, submit)
+        // 3. ANY button in the form, including type="button"
+        btnEl = form.querySelector('button[type="submit"], input[type="submit"]')
+            || form.querySelector('button#submit, button#save, button.btn-primary, button.is-primary')
+            || form.querySelector('button');
     }
-    // Cleanup previous notification styles
-    notificationId.style.display = 'none';
 
-    ['is-danger', 'is-success', 'w3-red', 'w3-green', 'bg-danger', 'bg-success'].forEach(cls => notificationId.classList.remove(cls));
+    // Set button spinner and disable button
+    if (btnEl) {
+        setButtonLoading(btnEl);
+    }
 
-    // add value to the hidden csrf input field
-    // const csrfToken = getCookieValue('XSRF-TOKEN');
-    // if (csrfToken) {
-    //     const csrfInput = id('token');
-    //     if (csrfInput) {
-    //         csrfInput.value = csrfToken; // Set the CSRF token in the hidden input field    
-    // } 
+    // Optional legacy external loader
+    const loader = id('setLoader');
+    if (loader) loader.style.display = 'block';
 
-    // extract the form entries
-    // extract the form entriesËËË
-    const form = id(formId)
+    // Determine notification requirement:
+    // If called with modern options object, notification is optional (SweetAlert2 handles alerts).
+    // If called with legacy positional arguments, enforce legacy expectation if configured.
+    const formIdStr = typeof formId === 'string' ? formId : (form.id || '');
+    const notificationId = formIdStr ? id(`${formIdStr}_notification`) : null;
 
-    if (!form) {
-        throw new Error('Form element not found');
+    if (!notificationId && !isOptionsObj) {
+        throw new Error('Notification element not found');
     }
 
-    let formEntries = new FormData(form);
+    if (notificationId) {
+        notificationId.style.display = 'none';
+        ['is-danger', 'is-success', 'w3-red', 'w3-green', 'bg-danger', 'bg-success'].forEach(cls =>
+            notificationId.classList.remove(cls)
+        );
+    }
 
-    // if recaptcha token is provided, append it for v3
-    // if recaptcha token is provided, append it for v3
-    if (recaptchaToken) {
+    // Build form data
+    let formEntries;
+    if (form instanceof FormData) {
+        formEntries = form;
+    } else if (form instanceof HTMLFormElement) {
+        formEntries = new FormData(form);
+    } else {
+        formEntries = new FormData();
+    }
 
-        formEntries.append('siteKey', recaptchaToken.token);
-        formEntries.append('action', recaptchaToken.action);
+    // Append recaptcha token if present
+    if (recaptcha) {
+        formEntries.append('siteKey', recaptcha.token || '');
+        formEntries.append('action', recaptcha.action || 'SUBMIT');
     }
 
     formEntries.delete('submit');
     formEntries.delete('checkbox');
 
     const options = {
-        baseURL: '/', // Adjust to your API base URL
-        withCredentials: true, // Ensure cookies (e.g., XSRF token) are sent
+        baseURL: '/',
+        withCredentials: true,
     };
 
-    // AXIOS POST FUNCTIONALITY
     try {
         const response = await axios.post(url, formEntries, options);
-        const successClass = getNotificationClassByCSS(css || 'bulma', 'green');
+        const successClass = getNotificationClassByCSS(themeCss || 'bulma', 'green');
 
-        // check if response.data.message is an array
-        const { message } = response.data || {};
+        const { message } = response?.data || {};
         if (!message) {
             throw new Error('Response data does not contain a message');
         }
-        processFormDataAction(successClass, message, notificationId);
+
+        const successMsg = typeof message === 'string' && message.trim()
+            ? message.trim()
+            : 'Operation completed successfully.';
+
+        // Modern SweetAlert2 toast notification
+        swalSuccess(successMsg, true);
+
+        // Fallback DOM notification if element exists
+        if (notificationId) {
+            processFormDataAction(successClass, successMsg, notificationId);
+        }
 
         if (redirect) {
-            redirectAfterDelay(redirect, 2000);
+            redirectAfterDelay(redirect, 1500);
+        }
+
+        if (shouldResetForm && typeof form.reset === 'function') {
+            form.reset();
         }
 
-        form.reset();
+        return response;
 
     } catch (error) {
-        const errorClass = getNotificationClassByCSS(css || 'bulma', 'red');
-        const ErrorMsg = parseErrorResponse(error);
-        processFormDataAction(errorClass, ErrorMsg, notificationId);
+        const errorClass = getNotificationClassByCSS(themeCss || 'bulma', 'red');
+        const errorMsg = parseErrorResponse(error) || 'An error occurred during submission.';
+
+        // Modern SweetAlert2 error modal/toast
+        swalError(errorMsg, true);
+
+        // Fallback DOM notification if element exists
+        if (notificationId) {
+            processFormDataAction(errorClass, errorMsg, notificationId);
+        }
+
+        return { error: true, message: errorMsg, rawError: error };
+
+    } finally {
+        // Release lock
+        releaseLock(lockKey);
+
+        // Guaranteed spinner cleanup
+        if (btnEl) {
+            clearButtonLoading(btnEl);
+        }
+        if (loader) {
+            loader.style.display = 'none';
+            loader.classList.remove('loader');
+        }
     }
 };
 

package/InlineValidation.js

@@ -0,0 +1,78 @@
+'use strict';
+import { id } from './UtilityHtml.js';
+
+const VALID_EMAIL_REGEX = /^[\w\-\.\+]+\@[a-zA-Z0-9\.\-]+\.[a-zA-Z0-9]{2,6}$/;
+
+/**
+ * Attaches real-time validation and micro-feedback to form fields on blur/input.
+ * 
+ * @param {string|HTMLElement} fieldId - ID or DOM element of the input
+ * @param {Object} options
+ * @param {'email'|'password'|'required'|'custom'} [options.type='required']
+ * @param {(value: string) => { valid: boolean, message?: string }} [options.validator]
+ * @param {string} [options.errorColor='#e74c3c']
+ * @param {string} [options.successColor='#27ae60']
+ */
+export const attachInlineValidation = (fieldId, options = {}) => {
+  if (typeof document === 'undefined') return;
+
+  const el = typeof fieldId === 'string' ? id(fieldId) : fieldId;
+  if (!el) return;
+
+  const {
+    type = 'required',
+    validator = null,
+    errorColor = '#e74c3c',
+    successColor = '#27ae60'
+  } = options;
+
+  const errorElId = `${el.id || el.name}_error`;
+  let feedbackEl = id(errorElId);
+
+  const validate = () => {
+    const val = (el.value || '').trim();
+    let isValid = true;
+    let message = '';
+
+    if (typeof validator === 'function') {
+      const result = validator(val);
+      isValid = !!result.valid;
+      message = result.message || '';
+    } else if (type === 'required') {
+      isValid = val.length > 0;
+      message = isValid ? '' : 'This field is required.';
+    } else if (type === 'email') {
+      isValid = VALID_EMAIL_REGEX.test(val);
+      message = isValid ? '' : 'Please enter a valid email address.';
+    } else if (type === 'password') {
+      isValid = val.length >= 8;
+      message = isValid ? '' : 'Password must be at least 8 characters long.';
+    }
+
+    // Apply micro-feedback styling
+    if (isValid) {
+      el.style.borderColor = val ? successColor : '';
+      if (feedbackEl) {
+        feedbackEl.innerHTML = '';
+        feedbackEl.style.display = 'none';
+      }
+    } else {
+      el.style.borderColor = errorColor;
+      if (feedbackEl) {
+        feedbackEl.style.display = 'block';
+        feedbackEl.style.color = errorColor;
+        feedbackEl.innerHTML = message;
+      }
+    }
+
+    return isValid;
+  };
+
+  el.addEventListener('blur', validate);
+  el.addEventListener('input', () => {
+    // Clear error border while user is re-typing
+    if (el.style.borderColor === errorColor) {
+      validate();
+    }
+  });
+};

package/NetworkGuard.js

@@ -0,0 +1,54 @@
+'use strict';
+import { swalToast } from './Alert.js';
+
+let isListening = false;
+let wasOffline = false;
+
+/**
+ * Checks if the browser is currently online.
+ * @returns {boolean}
+ */
+export const isOnline = () => {
+  return typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean'
+    ? navigator.onLine
+    : true;
+};
+
+/**
+ * Attaches automatic online/offline listeners to show clean toasts.
+ * Safe to call multiple times (idempotent).
+ */
+export const setupNetworkListeners = () => {
+  if (typeof window === 'undefined' || isListening) return;
+  isListening = true;
+
+  window.addEventListener('offline', () => {
+    wasOffline = true;
+    swalToast('Internet connection lost. You are offline.', 'warning', 4000);
+  });
+
+  window.addEventListener('online', () => {
+    if (wasOffline) {
+      swalToast('Connection restored. Back online!', 'success', 3000);
+      wasOffline = false;
+    }
+  });
+};
+
+/**
+ * Wraps an async request to check connectivity before dispatching.
+ * 
+ * @param {() => Promise<any>} requestFn
+ * @param {string} [offlineMsg='No internet connection. Please check your network.']
+ * @returns {Promise<any>}
+ */
+export const withNetworkGuard = async (
+  requestFn,
+  offlineMsg = 'No internet connection. Please check your network.'
+) => {
+  if (!isOnline()) {
+    swalToast(offlineMsg, 'warning', 4000);
+    throw new Error(offlineMsg);
+  }
+  return await requestFn();
+};

package/README.md

@@ -32,6 +32,80 @@ import { sanitizeInput } from '@modernman00/shared-js-lib';
 const cleanInput = sanitizeInput('<script>alert("xss")</script>');
 console.log(cleanInput); // Sanitized output
 
+### Example: SweetAlert2 Notifications & Modals
+```javascript
+import { swalToast, swalSuccess, swalError, swalConfirm } from '@modernman00/shared-js-lib';
+
+// Fast non-blocking toast at top-end
+await swalToast('Profile updated successfully!');
+
+// Prominent success or error modal
+await swalSuccess('Your application has been submitted.', false);
+await swalError('Payment processing failed. Please check your card.');
+
+// Interactive confirmation dialog
+const proceed = await swalConfirm('Delete Account', 'Are you sure? This cannot be undone.');
+if (proceed) {
+  // perform deletion
+}
+```
+
+### Example: Framework-Agnostic Button Spinners
+```javascript
+import { setButtonLoading, clearButtonLoading, withButtonSpinner } from '@modernman00/shared-js-lib';
+
+// Manual trigger
+setButtonLoading('submitButton'); // Disables button & shows smooth SVG spinner
+// ... do work
+clearButtonLoading('submitButton'); // Restores original text & enables button
+
+// Automatic wrapper with guaranteed cleanup:
+await withButtonSpinner('submitButton', async () => {
+  await apiCall();
+});
+```
+
+### Example: Modern Form Submission (`postFormData`)
+```javascript
+import { postFormData } from '@modernman00/shared-js-lib';
+
+// Modern clean syntax: auto-handles button spinner & SweetAlert2 without needing a notification element!
+await postFormData('/event/update', 'glbVenueForm', {
+  button: '#glbVenueSaveBtn', // auto-spins & disables button, restores in finally{}
+  css: 'bootstrap',          // or 'bulma', 'tailwind'
+  redirect: null             // optional redirect URL
+});
+```
+
+### Example: Advanced Enterprise Features
+```javascript
+import {
+  withSubmissionLock,
+  setupNetworkListeners,
+  attachInlineValidation,
+  copyToClipboard,
+  setupAuthExpiryInterceptor
+} from '@modernman00/shared-js-lib';
+
+// 1. Double Submit Protection Lock
+await withSubmissionLock('payout_action', async () => {
+  await submitPayment();
+});
+
+// 2. Automatic Online/Offline Connection Alerts
+setupNetworkListeners(); // Automatically alerts user when connection drops or reconnects
+
+// 3. Real-Time Inline Field Validation with Micro-Feedback
+attachInlineValidation('userEmail', { type: 'email' });
+attachInlineValidation('userPassword', { type: 'password' });
+
+// 4. One-Click Copy-to-Clipboard with SweetAlert2 Toast
+await copyToClipboard('INVITE-2026-XYZ', 'Invite code copied to clipboard!');
+
+// 5. Global 401 Session Expiry Interceptor & Re-login Modal
+setupAuthExpiryInterceptor({ loginUrl: '/auth/login' });
+```
+
 Configuration
 
 Ensure your project uses ES Modules by adding "type": "module" to your package.json, or use a bundler like Laravel Mix/Webpack.