@modernman00/shared-js-lib 1.2.82 → 1.2.87

package/OtpInputManager.js

@@ -0,0 +1,429 @@
+/**
+ * OtpInputManager - Centralized OTP & Security Verification Input Controller
+ * Part of @modernman00/shared-js-lib
+ *
+ * Provides cross-platform OTP handling:
+ * - iOS 17+ Apple Mail QuickType autofill multi-character distribution
+ * - Android Gmail notification copy & Gboard suggestion strip support
+ * - Single-keypress automatic focus progression & backspace navigation
+ * - Tab focus (visibilitychange) smart clipboard detection
+ * - 1-Click Magic Link URL query parameter extraction (?code=123456) with history sanitization
+ * - Eastern Arabic / Perso-Arabic numeral normalization
+ * - Automatic form submission upon completion
+ */
+
+export class OtpInputManager {
+  /**
+   * @param {Object} options
+   * @param {string|NodeList|Array} [options.inputs='.otp-input'] - Selector or element collection for OTP inputs
+   * @param {string} [options.hiddenInputId='code'] - ID of hidden input storing full code
+   * @param {string} [options.submitBtnId='button'] - ID of submit button to trigger on completion
+   * @param {string} [options.pasteBtnId='pasteBtn'] - Optional ID of "Paste Code from Email" button
+   * @param {number} [options.length=6] - Expected length of verification code
+   * @param {boolean} [options.autoSubmit=true] - Auto-submit form when all digits are entered
+   * @param {number} [options.autoSubmitDelay=150] - Delay in ms before auto-submitting
+   * @param {boolean} [options.checkClipboardOnFocus=true] - Check clipboard on visibilitychange / focus
+   * @param {string} [options.urlParamKey='code'] - URL search param to check for magic link autofill
+   * @param {boolean} [options.cleanUrlAfterFill=true] - Strip ?code= param from URL bar to prevent leakage
+   * @param {Function} [options.onComplete=null] - Callback triggered when code is complete
+   * @param {Function} [options.onChange=null] - Callback triggered when any digit changes
+   */
+  constructor(options = {}) {
+    this.options = {
+      inputs: '.otp-input',
+      hiddenInputId: 'code',
+      submitBtnId: 'button',
+      pasteBtnId: 'pasteBtn',
+      length: 6,
+      autoSubmit: true,
+      autoSubmitDelay: 150,
+      checkClipboardOnFocus: true,
+      urlParamKey: 'code',
+      cleanUrlAfterFill: true,
+      onComplete: null,
+      onChange: null,
+      ...options
+    };
+
+    this.inputs = [];
+    this.hiddenInput = null;
+    this.submitBtn = null;
+    this.pasteBtn = null;
+    this.boundHandlers = [];
+    this.isSubmitting = false;
+
+    this._initElements();
+    if (this.inputs.length > 0) {
+      this._bindEvents();
+      this._checkUrlParameter();
+    }
+  }
+
+  /**
+   * Normalizes Eastern Arabic / Perso-Arabic digits to standard ASCII numerals
+   * and strips non-alphanumeric characters.
+   *
+   * @param {string} str
+   * @returns {string}
+   */
+  static normalizeDigits(str) {
+    if (!str || typeof str !== 'string') return '';
+    return str
+      .replace(/[\u0660-\u0669]/g, c => String.fromCharCode(c.charCodeAt(0) - 0x0660 + 48))
+      .replace(/[\u06F0-\u06F9]/g, c => String.fromCharCode(c.charCodeAt(0) - 0x06F0 + 48))
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .toUpperCase();
+  }
+
+  /**
+   * Resolve DOM elements
+   * @private
+   */
+  _initElements() {
+    if (typeof document === 'undefined') return;
+
+    if (typeof this.options.inputs === 'string') {
+      this.inputs = Array.from(document.querySelectorAll(this.options.inputs));
+    } else if (this.options.inputs instanceof NodeList || Array.isArray(this.options.inputs)) {
+      this.inputs = Array.from(this.options.inputs);
+    }
+
+    // Single input mode fallback (e.g. LoanEasyFinance or TenantScore)
+    if (this.inputs.length === 0) {
+      const singleInput = document.getElementById(this.options.singleInputId || 'code') ||
+                          document.querySelector('input[name="code"]');
+      if (singleInput) {
+        this.inputs = [singleInput];
+      }
+    }
+
+    if (this.options.hiddenInputId) {
+      this.hiddenInput = document.getElementById(this.options.hiddenInputId);
+    }
+    if (this.options.submitBtnId) {
+      this.submitBtn = document.getElementById(this.options.submitBtnId);
+    }
+    if (this.options.pasteBtnId) {
+      this.pasteBtn = document.getElementById(this.options.pasteBtnId);
+    }
+
+    // Ensure inputs have autocomplete and inputmode configured for mobile devices
+    this.inputs.forEach((input, index) => {
+      if (!input.getAttribute('inputmode')) {
+        input.setAttribute('inputmode', 'numeric');
+      }
+      // On mobile (iOS / Android), the first box receives the autofill event
+      if (index === 0) {
+        input.setAttribute('autocomplete', 'one-time-code');
+        // Allow up to expected length in first box so mobile OS doesn't truncate the payload
+        input.setAttribute('maxlength', String(this.options.length));
+      } else {
+        input.setAttribute('autocomplete', 'off');
+        input.setAttribute('maxlength', '1');
+      }
+    });
+  }
+
+  /**
+   * Bind event listeners
+   * @private
+   */
+  _bindEvents() {
+    if (typeof document === 'undefined') return;
+
+    this.inputs.forEach((input, index) => {
+      // 1. Input event: Handles single keypress AND mobile OS multi-digit autofill (iOS 17 QuickType)
+      const onInput = (e) => this._handleInput(e, index);
+      input.addEventListener('input', onInput);
+      this.boundHandlers.push({ element: input, event: 'input', handler: onInput });
+
+      // 2. Keydown event: Handles Backspace, Delete, and Arrow navigation
+      const onKeydown = (e) => this._handleKeydown(e, index);
+      input.addEventListener('keydown', onKeydown);
+      this.boundHandlers.push({ element: input, event: 'keydown', handler: onKeydown });
+
+      // 3. Paste event: Handles explicit paste actions
+      const onPaste = (e) => this._handlePaste(e, index);
+      input.addEventListener('paste', onPaste);
+      this.boundHandlers.push({ element: input, event: 'paste', handler: onPaste });
+    });
+
+    // 4. Paste button binding
+    if (this.pasteBtn) {
+      const onPasteBtnClick = () => this.pasteFromClipboard();
+      this.pasteBtn.addEventListener('click', onPasteBtnClick);
+      this.boundHandlers.push({ element: this.pasteBtn, event: 'click', handler: onPasteBtnClick });
+    }
+
+    // 5. Visibility change / Tab re-focus detection (Android / iOS app switching from email)
+    if (this.options.checkClipboardOnFocus && typeof document.addEventListener !== 'undefined') {
+      const onVisibilityChange = () => {
+        if (document.visibilityState === 'visible') {
+          this._checkClipboardOnResume();
+        }
+      };
+      document.addEventListener('visibilitychange', onVisibilityChange);
+      this.boundHandlers.push({ element: document, event: 'visibilitychange', handler: onVisibilityChange });
+
+      const onWindowFocus = () => this._checkClipboardOnResume();
+      window.addEventListener('focus', onWindowFocus);
+      this.boundHandlers.push({ element: window, event: 'focus', handler: onWindowFocus });
+    }
+  }
+
+  /**
+   * Handle input event on an individual box
+   * @private
+   */
+  _handleInput(e, index) {
+    const rawVal = e.target.value;
+    const clean = OtpInputManager.normalizeDigits(rawVal);
+
+    // Single input mode (e.g. LoanEasyFinance or TenantScore)
+    if (this.inputs.length === 1) {
+      e.target.value = clean.substring(0, this.options.length);
+      this._updateHiddenInput();
+      if (clean.length >= this.options.length) {
+        this._checkComplete();
+      }
+      return;
+    }
+
+    // CASE 1: Multi-character injection (iOS 17+ Mail QuickType, Android Gboard, autofill)
+    if (clean.length > 1) {
+      this.distributeCode(clean, index);
+      return;
+    }
+
+    // CASE 2: Single character entry
+    if (clean.length === 1) {
+      e.target.value = clean;
+      this._updateHiddenInput();
+
+      if (index < this.inputs.length - 1) {
+        this.inputs[index + 1].focus();
+      } else {
+        this._checkComplete();
+      }
+    } else {
+      e.target.value = '';
+      this._updateHiddenInput();
+    }
+  }
+
+  /**
+   * Handle keydown event (Backspace, Arrow keys)
+   * @private
+   */
+  _handleKeydown(e, index) {
+    if (e.key === 'Backspace') {
+      if (!e.target.value && index > 0) {
+        e.preventDefault();
+        this.inputs[index - 1].value = '';
+        this.inputs[index - 1].focus();
+        this._updateHiddenInput();
+      }
+    } else if (e.key === 'ArrowLeft' && index > 0) {
+      e.preventDefault();
+      this.inputs[index - 1].focus();
+    } else if (e.key === 'ArrowRight' && index < this.inputs.length - 1) {
+      e.preventDefault();
+      this.inputs[index + 1].focus();
+    }
+  }
+
+  /**
+   * Handle explicit paste event
+   * @private
+   */
+  _handlePaste(e, index) {
+    e.preventDefault();
+    const pasteData = (e.clipboardData || window.clipboardData)?.getData('text') || '';
+    if (pasteData) {
+      this.distributeCode(pasteData, index);
+    }
+  }
+
+  /**
+   * Distributes a multi-character string across input boxes starting from startIndex
+   *
+   * @param {string} rawCode
+   * @param {number} [startIndex=0]
+   */
+  distributeCode(rawCode, startIndex = 0) {
+    const code = OtpInputManager.normalizeDigits(rawCode).substring(0, this.options.length);
+    if (!code) return;
+
+    if (this.inputs.length === 1) {
+      this.inputs[0].value = code;
+      this._updateHiddenInput();
+      this.inputs[0].focus();
+      if (code.length === this.options.length) {
+        this._checkComplete();
+      }
+      return;
+    }
+
+    const chars = code.split('');
+    chars.forEach((char, i) => {
+      if (this.inputs[i]) {
+        this.inputs[i].value = char;
+      }
+    });
+
+    this._updateHiddenInput();
+
+    const targetIndex = Math.min(chars.length - 1, this.inputs.length - 1);
+    if (this.inputs[targetIndex]) {
+      this.inputs[targetIndex].focus();
+    }
+
+    if (code.length === this.options.length) {
+      this._checkComplete();
+    }
+  }
+
+  /**
+   * Reads code from system clipboard
+   * @returns {Promise<boolean>}
+   */
+  async pasteFromClipboard() {
+    if (typeof navigator === 'undefined' || !navigator.clipboard?.readText) {
+      return false;
+    }
+
+    try {
+      const text = await navigator.clipboard.readText();
+      const code = OtpInputManager.normalizeDigits(text.trim());
+      if (code.length === this.options.length) {
+        this.distributeCode(code, 0);
+        return true;
+      }
+    } catch (_) {
+      // Permission denied or clipboard empty
+    }
+    return false;
+  }
+
+  /**
+   * Background clipboard check on tab resume / focus
+   * @private
+   */
+  async _checkClipboardOnResume() {
+    // Only auto-fill if all inputs are currently empty
+    const currentCode = this.getCode();
+    if (currentCode.length === this.options.length) return;
+
+    if (typeof navigator === 'undefined' || !navigator.clipboard?.readText) return;
+
+    try {
+      const text = await navigator.clipboard.readText();
+      const clean = OtpInputManager.normalizeDigits(text.trim());
+      // Strictly verify it matches the required code length exactly
+      if (clean.length === this.options.length) {
+        this.distributeCode(clean, 0);
+      }
+    } catch (_) {
+      // Silent catch: browsers without focus permission won't throw unhandled errors
+    }
+  }
+
+  /**
+   * Checks URL query parameters for magic link autofill (e.g., ?code=123456)
+   * @private
+   */
+  _checkUrlParameter() {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const search = this.options.searchQuery !== undefined ? this.options.searchQuery : window.location?.search;
+      if (!search) return;
+
+      const params = new URLSearchParams(search);
+      const urlCode = params.get(this.options.urlParamKey);
+
+      if (urlCode) {
+        const cleanCode = OtpInputManager.normalizeDigits(urlCode).substring(0, this.options.length);
+        if (cleanCode.length === this.options.length) {
+          this.distributeCode(cleanCode, 0);
+
+          // Strip the ?code= query parameter from URL bar to prevent token leakage in history/referrer
+          if (this.options.cleanUrlAfterFill && window.history?.replaceState && this.options.searchQuery === undefined) {
+            params.delete(this.options.urlParamKey);
+            const newSearch = params.toString();
+            const cleanUrl = (window.location?.pathname || '') + (newSearch ? `?${newSearch}` : '') + (window.location?.hash || '');
+            window.history.replaceState({}, document.title, cleanUrl);
+          }
+        }
+      }
+    } catch (_) {}
+  }
+
+  /**
+   * Synchronize the hidden input with the current values of all boxes
+   * @private
+   */
+  _updateHiddenInput() {
+    const code = this.getCode();
+    if (this.hiddenInput) {
+      this.hiddenInput.value = code;
+    }
+    if (typeof this.options.onChange === 'function') {
+      this.options.onChange(code);
+    }
+  }
+
+  /**
+   * Get concatenated value of all input boxes
+   * @returns {string}
+   */
+  getCode() {
+    const raw = this.inputs.map(input => input.value).join('');
+    return OtpInputManager.normalizeDigits(raw);
+  }
+
+  /**
+   * Clears all inputs and hidden input
+   */
+  clear() {
+    this.inputs.forEach(input => {
+      input.value = '';
+    });
+    this._updateHiddenInput();
+    if (this.inputs[0]) {
+      this.inputs[0].focus();
+    }
+  }
+
+  /**
+   * Checks if all digits are filled and triggers completion / auto-submit
+   * @private
+   */
+  _checkComplete() {
+    const code = this.getCode();
+    if (code.length === this.options.length) {
+      if (typeof this.options.onComplete === 'function') {
+        this.options.onComplete(code);
+      }
+
+      if (this.options.autoSubmit && this.submitBtn && !this.isSubmitting) {
+        this.isSubmitting = true;
+        setTimeout(() => {
+          if (this.submitBtn) {
+            this.submitBtn.click();
+          }
+        }, this.options.autoSubmitDelay);
+      }
+    }
+  }
+
+  /**
+   * Cleans up all bound event listeners
+   */
+  destroy() {
+    this.boundHandlers.forEach(({ element, event, handler }) => {
+      element.removeEventListener(event, handler);
+    });
+    this.boundHandlers = [];
+  }
+}

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 } }));
+        }
+      });
+    }
+  }
+}