@modernman00/shared-js-lib 1.2.81 → 1.2.83

package/PwaInstall.js

@@ -0,0 +1,165 @@
+/**
+ * 📱 PwaInstall — Smart A2HS Banner & iOS Safari Installation Engine
+ * Part of @modernman00/shared-js-lib
+ *
+ * Implements:
+ * 1. Native beforeinstallprompt interception for Chromium
+ * 2. iOS Safari step-by-step walkthrough bottom-sheet
+ * 3. Configurable app name, icon, and brand colors
+ * 4. 14-day persistent dismissal window
+ * 5. Safe-area notch padding & 44px minimum tap target compliance
+ */
+
+export class PwaInstall {
+  constructor(options = {}) {
+    this.appName = options.appName || 'Application';
+    this.appIcon = options.appIcon || '/public/img/favicon/apple-touch-icon.png';
+    this.brandColor = options.brandColor || '#2563eb';
+    this.dismissKey = options.dismissKey || `${this.appName.toLowerCase().replace(/[^a-z0-9]/g, '_')}_pwa_dismissed`;
+    this.dismissDurationMs = (options.dismissDays || 14) * 24 * 60 * 60 * 1000;
+    this.delayMs = options.delayMs || 3000;
+    this.deferredPrompt = null;
+    this.isInitialized = false;
+
+    if (typeof window !== 'undefined') {
+      this.init();
+    }
+  }
+
+  init() {
+    if (this.isInitialized || typeof window === 'undefined') return;
+    this.isInitialized = true;
+
+    // Check if running in standalone mode (already installed)
+    const isStandalone = (window.matchMedia && window.matchMedia('(display-mode: standalone)').matches)
+                      || window.navigator.standalone === true;
+
+    if (isStandalone) return;
+
+    // Check if dismissed recently
+    const dismissedAt = localStorage.getItem(this.dismissKey);
+    if (dismissedAt && (Date.now() - parseInt(dismissedAt, 10) < this.dismissDurationMs)) {
+      return;
+    }
+
+    const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream;
+    const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+
+    // 1. Chromium native beforeinstallprompt
+    window.addEventListener('beforeinstallprompt', (e) => {
+      e.preventDefault();
+      this.deferredPrompt = e;
+      this.showBanner('native');
+    });
+
+    // 2. iOS Safari instructions
+    if (isIOS && isSafari && !isStandalone) {
+      if (document.readyState === 'complete') {
+        setTimeout(() => this.showBanner('ios'), this.delayMs);
+      } else {
+        window.addEventListener('DOMContentLoaded', () => {
+          setTimeout(() => this.showBanner('ios'), this.delayMs);
+        });
+      }
+    }
+  }
+
+  showBanner(type) {
+    if (document.getElementById('pwaUniversalInstallBanner')) return;
+
+    const banner = document.createElement('div');
+    banner.id = 'pwaUniversalInstallBanner';
+    banner.setAttribute('role', 'dialog');
+    banner.setAttribute('aria-label', `Install ${this.appName}`);
+
+    // Styling with glassmorphism and safe-area compliance
+    banner.style.position = 'fixed';
+    banner.style.bottom = 'max(16px, env(safe-area-inset-bottom, 16px))';
+    banner.style.left = '16px';
+    banner.style.right = '16px';
+    banner.style.margin = '0 auto';
+    banner.style.maxWidth = '480px';
+    banner.style.backgroundColor = 'rgba(23, 23, 28, 0.94)';
+    banner.style.backdropFilter = 'blur(12px)';
+    banner.style.webkitBackdropFilter = 'blur(12px)';
+    banner.style.border = '1px solid rgba(255, 255, 255, 0.12)';
+    banner.style.borderRadius = '16px';
+    banner.style.boxShadow = '0 12px 36px rgba(0, 0, 0, 0.45)';
+    banner.style.padding = '14px 16px';
+    banner.style.display = 'flex';
+    banner.style.alignItems = 'center';
+    banner.style.justifyContent = 'space-between';
+    banner.style.gap = '12px';
+    banner.style.zIndex = '99999';
+    banner.style.color = '#ffffff';
+    banner.style.fontFamily = 'system-ui, -apple-system, sans-serif';
+    banner.style.transition = 'all 0.3s cubic-bezier(0.16, 1, 0.3, 1)';
+
+    const iconHtml = `<img src="${this.appIcon}" alt="${this.appName} Logo" style="width: 44px; height: 44px; border-radius: 10px; object-fit: cover; flex-shrink: 0;">`;
+
+    if (type === 'native') {
+      banner.innerHTML = `
+        <div style="display: flex; align-items: center; gap: 12px; min-width: 0;">
+          ${iconHtml}
+          <div style="min-width: 0;">
+            <strong style="display: block; font-size: 15px; font-weight: 600; line-height: 1.2;">Install ${this.appName}</strong>
+            <span style="display: block; font-size: 12px; color: #a1a1aa; margin-top: 2px;">Add to home screen for fast, offline access</span>
+          </div>
+        </div>
+        <div style="display: flex; align-items: center; gap: 8px; flex-shrink: 0;">
+          <button id="btnPwaInstallAction" type="button" style="background-color: ${this.brandColor}; color: #ffffff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 600; cursor: pointer; min-height: 44px; min-width: 44px;">
+            Install
+          </button>
+          <button id="btnPwaDismissAction" type="button" aria-label="Dismiss" style="background: none; border: none; color: #a1a1aa; font-size: 20px; cursor: pointer; padding: 8px; min-height: 44px; min-width: 44px;">
+            &times;
+          </button>
+        </div>
+      `;
+    } else {
+      banner.innerHTML = `
+        <div style="display: flex; align-items: center; gap: 12px; min-width: 0;">
+          ${iconHtml}
+          <div style="min-width: 0;">
+            <strong style="display: block; font-size: 15px; font-weight: 600; line-height: 1.2;">Install on iPhone</strong>
+            <span style="display: block; font-size: 12px; color: #a1a1aa; margin-top: 2px;">Tap <strong>Share</strong>, then <strong>'Add to Home Screen'</strong></span>
+          </div>
+        </div>
+        <div style="display: flex; align-items: center; gap: 8px; flex-shrink: 0;">
+          <button id="btnPwaDismissAction" type="button" aria-label="Dismiss" style="background: none; border: none; color: #a1a1aa; font-size: 20px; cursor: pointer; padding: 8px; min-height: 44px; min-width: 44px;">
+            &times;
+          </button>
+        </div>
+      `;
+    }
+
+    document.body.appendChild(banner);
+
+    const installBtn = document.getElementById('btnPwaInstallAction');
+    if (installBtn && this.deferredPrompt) {
+      installBtn.addEventListener('click', async () => {
+        banner.style.display = 'none';
+        this.deferredPrompt.prompt();
+        const { outcome } = await this.deferredPrompt.userChoice;
+        if (outcome === 'accepted') {
+          if (typeof window !== 'undefined' && window.dispatchEvent) {
+            window.dispatchEvent(new CustomEvent('pwa:installed', { detail: { appName: this.appName } }));
+          }
+        }
+        this.deferredPrompt = null;
+      });
+    }
+
+    const dismissBtn = document.getElementById('btnPwaDismissAction');
+    if (dismissBtn) {
+      dismissBtn.addEventListener('click', () => {
+        banner.style.opacity = '0';
+        banner.style.transform = 'translateY(16px)';
+        setTimeout(() => banner.remove(), 300);
+        localStorage.setItem(this.dismissKey, Date.now().toString());
+        if (typeof window !== 'undefined' && window.dispatchEvent) {
+          window.dispatchEvent(new CustomEvent('pwa:install-dismissed', { detail: { appName: this.appName } }));
+        }
+      });
+    }
+  }
+}

package/PwaManager.js

@@ -0,0 +1,224 @@
+/**
+ * 📱 PwaManager — Universal Cross-App Service Worker & PWA Controller
+ * Part of @modernman00/shared-js-lib
+ *
+ * Implements:
+ * 1. Clean root /sw.js registration with scope '/'
+ * 2. Purging of legacy orphaned workers (/public/sw.js, /service-worker.js)
+ * 3. User-prompted updates via 'postMessage' with zero jarring auto-reloads
+ * 4. Safe cache purging on user logout (clears API & session caches)
+ * 5. Custom event dispatching for seamless Blade UI integration
+ */
+
+export class PwaManager {
+  static registration = null;
+  static options = {
+    swUrl: '/sw.js',
+    scope: '/',
+    appName: 'App',
+    enableUpdateToast: true,
+    enableBadgingSync: true,
+    badgeEndpoint: '/api/notifications/unread',
+    onUpdateAvailable: null
+  };
+
+  /**
+   * Initializes Service Worker registration and lifecycle monitoring
+   */
+  static async init(userOptions = {}) {
+    if (typeof window === 'undefined' || !('serviceWorker' in navigator)) {
+      return null;
+    }
+
+    this.options = { ...this.options, ...userOptions };
+
+    window.addEventListener('load', async () => {
+      try {
+        await this.purgeLegacyWorkers();
+        this.registration = await navigator.serviceWorker.register(this.options.swUrl, {
+          scope: this.options.scope
+        });
+
+        console.log(`[PwaManager] ${this.options.appName} ServiceWorker active with scope:`, this.registration.scope);
+
+        // Listen for new workers entering 'installing' or 'waiting' states
+        this.registration.addEventListener('updatefound', () => {
+          const installingWorker = this.registration.installing;
+          if (!installingWorker) return;
+
+          installingWorker.addEventListener('statechange', () => {
+            if (installingWorker.state === 'installed' && navigator.serviceWorker.controller) {
+              console.log(`[PwaManager] New version of ${this.options.appName} installed and waiting.`);
+              this.handleUpdateAvailable(installingWorker);
+            }
+          });
+        });
+
+        // Detect if a worker was already waiting prior to page load
+        if (this.registration.waiting && navigator.serviceWorker.controller) {
+          this.handleUpdateAvailable(this.registration.waiting);
+        }
+      } catch (error) {
+        console.error(`[PwaManager] ServiceWorker registration failed:`, error);
+      }
+    });
+
+    // Listen for controller changes (when skipWaiting activates new worker)
+    navigator.serviceWorker.addEventListener('controllerchange', () => {
+      console.log('[PwaManager] ServiceWorker controller changed. Page ready for reload.');
+    });
+
+    // Automatic Home Screen Badging Synchronization
+    if (this.options.enableBadgingSync && typeof window !== 'undefined') {
+      this.syncAppBadge();
+
+      window.addEventListener('focus', () => this.syncAppBadge());
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible') {
+          this.syncAppBadge();
+        }
+      });
+
+      navigator.serviceWorker.addEventListener('message', (event) => {
+        if (event.data?.type === 'ON_APP_NOTIFICATION') {
+          this.syncAppBadge();
+        }
+      });
+    }
+
+    return this.registration;
+  }
+
+  /**
+   * Drops legacy or misconfigured workers from older architecture iterations
+   */
+  static async purgeLegacyWorkers() {
+    try {
+      const registrations = await navigator.serviceWorker.getRegistrations();
+      for (const reg of registrations) {
+        const scriptURL = (reg.active || reg.waiting || reg.installing || {}).scriptURL || '';
+        // If worker is scoped to /public/ or named /service-worker.js, unregister it
+        if (scriptURL.endsWith('/public/sw.js') || scriptURL.endsWith('/service-worker.js')) {
+          console.warn('[PwaManager] Unregistering legacy orphaned worker:', scriptURL);
+          await reg.unregister();
+        }
+      }
+    } catch (err) {
+      console.warn('[PwaManager] Legacy cleanup check error:', err);
+    }
+  }
+
+  /**
+   * Handles update notification
+   */
+  static handleUpdateAvailable(worker) {
+    if (typeof window !== 'undefined' && window.dispatchEvent) {
+      window.dispatchEvent(new CustomEvent('pwa:update-available', {
+        detail: { worker, appName: this.options.appName }
+      }));
+    }
+
+    if (typeof this.options.onUpdateAvailable === 'function') {
+      this.options.onUpdateAvailable(worker);
+    }
+  }
+
+  /**
+   * Sends skipWaiting postMessage to the waiting worker and triggers clean reload
+   */
+  static applyUpdate(worker = null) {
+    const targetWorker = worker || (this.registration ? this.registration.waiting : null);
+    if (targetWorker) {
+      targetWorker.postMessage({ action: 'skipWaiting' });
+    } else if (navigator.serviceWorker.controller) {
+      navigator.serviceWorker.controller.postMessage({ action: 'skipWaiting' });
+    }
+
+    navigator.serviceWorker.addEventListener('controllerchange', () => {
+      window.location.reload();
+    }, { once: true });
+  }
+
+  /**
+   * Purges sensitive API and user caches from the Service Worker upon user logout
+   */
+  static async clearUserCacheOnLogout() {
+    if ('serviceWorker' in navigator && navigator.serviceWorker.controller) {
+      navigator.serviceWorker.controller.postMessage({ action: 'clearUserCache' });
+    }
+
+    if (typeof caches !== 'undefined') {
+      try {
+        const keys = await caches.keys();
+        await Promise.all(
+          keys.filter(k => k.includes('api-cache') || k.includes('user-cache')).map(k => caches.delete(k))
+        );
+        console.log('[PwaManager] Client-side sensitive user caches purged.');
+      } catch (e) {
+        console.warn('[PwaManager] Failed to purge user caches:', e);
+      }
+    }
+  }
+
+  /**
+   * Sets app badge counter on the phone's home screen icon (Web Badging API)
+   *
+   * @param {number|string} count
+   * @returns {Promise<void>}
+   */
+  static setAppBadge(count) {
+    if (typeof navigator !== 'undefined' && 'setAppBadge' in navigator) {
+      const num = Math.max(0, parseInt(count, 10) || 0);
+      return (num > 0 ? navigator.setAppBadge(num) : navigator.clearAppBadge()).catch(() => {});
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Clears app badge counter from the phone's home screen icon
+   *
+   * @returns {Promise<void>}
+   */
+  static clearAppBadge() {
+    if (typeof navigator !== 'undefined' && 'clearAppBadge' in navigator) {
+      return navigator.clearAppBadge().catch(() => {});
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * Synchronizes app badge with the server's unread notifications endpoint
+   *
+   * @param {string|null} endpoint
+   * @returns {Promise<void>}
+   */
+  static async syncAppBadge(endpoint = null) {
+    const url = endpoint || this.options.badgeEndpoint || '/api/notifications/unread';
+    if (typeof navigator === 'undefined' || !('setAppBadge' in navigator)) {
+      return;
+    }
+
+    try {
+      const res = await fetch(url, { headers: { Accept: 'application/json' } });
+      if (!res.ok) {
+        // Release the stream before bailing. An abandoned response body stays
+        // "in flight" in Chromium indefinitely, which keeps the tab from ever
+        // reaching network idle — it silently wedges Playwright's
+        // `networkidle` waits and any load-state detection for the whole page.
+        await res.body?.cancel();
+        return;
+      }
+      const data = await res.json();
+      if (data && data.status === 'success' && Array.isArray(data.message)) {
+        const count = data.message.length;
+        if (count > 0) {
+          await this.setAppBadge(count);
+        } else {
+          await this.clearAppBadge();
+        }
+      }
+    } catch (e) {
+      // Harmless no-op on network failure or offline mode
+    }
+  }
+}

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.