@modernman00/shared-js-lib 1.2.83 → 1.2.87

package/AddressAutocomplete.js

@@ -0,0 +1,473 @@
+/**
+ * Address & Venue Autocomplete Engine
+ * Zero-cost hybrid geocoding using OpenStreetMap (Photon) & Postcodes.io
+ * 
+ * Part of @modernman00/shared-js-lib
+ */
+
+const UK_POSTCODE_REGEX = /^[A-Z]{1,2}[0-9][A-Z0-9]?(\s*[0-9][A-Z]{2})?$/i;
+const UK_FULL_POSTCODE_REGEX = /^[A-Z]{1,2}[0-9][A-Z0-9]?\s*[0-9][A-Z]{2}$/i;
+
+export class AddressAutocomplete {
+  /**
+   * @param {Object} options
+   * @param {string|HTMLElement} options.input - Target input element or selector
+   * @param {string|HTMLElement} [options.dropdown] - Dropdown container element or selector (optional)
+   * @param {string|HTMLElement} [options.spinner] - Spinner element or selector (optional)
+   * @param {string|HTMLElement} [options.errorElement] - Error container to clear on select (optional)
+   * @param {string} [options.themeColor='#7b03fc'] - Primary highlight color
+   * @param {string} [options.country='uk'] - Target country ('uk' prioritizes UK PAF/postcode formats)
+   * @param {Function} [options.onSelect] - Callback when an address is selected
+   * @param {boolean} [options.injectStyles=true] - Auto-inject component CSS
+   */
+  constructor(options = {}) {
+    this.options = Object.assign({
+      themeColor: '#7b03fc',
+      country: 'uk',
+      injectStyles: true,
+      onSelect: null,
+      errorElement: null,
+    }, options);
+
+    this.input = typeof this.options.input === 'string'
+      ? document.querySelector(this.options.input)
+      : this.options.input;
+
+    if (!this.input) {
+      console.warn('[AddressAutocomplete] Target input element not found.');
+      return;
+    }
+
+    this.dropdown = this.options.dropdown
+      ? (typeof this.options.dropdown === 'string' ? document.querySelector(this.options.dropdown) : this.options.dropdown)
+      : null;
+
+    this.spinner = this.options.spinner
+      ? (typeof this.options.spinner === 'string' ? document.querySelector(this.options.spinner) : this.options.spinner)
+      : null;
+
+    this.errorElement = this.options.errorElement
+      ? (typeof this.options.errorElement === 'string' ? document.querySelector(this.options.errorElement) : this.options.errorElement)
+      : null;
+
+    this.debounceTimer = null;
+    this.abortController = null;
+    this.activeIndex = -1;
+    this.currentItems = [];
+
+    this._boundInput = this.handleInput.bind(this);
+    this._boundKeydown = this.handleKeydown.bind(this);
+    this._boundDocClick = this.handleDocumentClick.bind(this);
+
+    if (this.options.injectStyles) {
+      this.injectStyles();
+    }
+
+    this.setupDropdown();
+    this.bindEvents();
+  }
+
+  injectStyles() {
+    if (typeof document === 'undefined') return;
+    if (document.getElementById('shared-address-autocomplete-styles')) return;
+
+    const style = document.createElement('style');
+    style.id = 'shared-address-autocomplete-styles';
+    style.textContent = `
+      .shared-loc-autocomplete-menu {
+        position: absolute;
+        top: calc(100% + 6px);
+        left: 0;
+        right: 0;
+        background: rgba(255, 255, 255, 0.98);
+        backdrop-filter: blur(16px);
+        -webkit-backdrop-filter: blur(16px);
+        border: 1px solid rgba(0, 0, 0, 0.1);
+        border-radius: 18px;
+        box-shadow: 0 20px 45px -10px rgba(0, 0, 0, 0.15), 0 4px 16px rgba(0, 0, 0, 0.05);
+        z-index: 1050;
+        max-height: 290px;
+        overflow-y: auto;
+        padding: 0.5rem;
+        margin: 0;
+        list-style: none;
+        animation: sharedFadeInLoc 0.2s ease-out;
+      }
+      @keyframes sharedFadeInLoc {
+        from { opacity: 0; transform: translateY(-6px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+      .shared-loc-item {
+        display: flex;
+        align-items: center;
+        gap: 0.75rem;
+        padding: 0.7rem 0.95rem;
+        border-radius: 12px;
+        cursor: pointer;
+        transition: all 0.15s ease;
+        border: 1px solid transparent;
+      }
+      .shared-loc-item:hover,
+      .shared-loc-item.active {
+        background: rgba(123, 3, 252, 0.08);
+        border-color: rgba(123, 3, 252, 0.2);
+      }
+      .shared-loc-item .shared-loc-icon {
+        width: 32px;
+        height: 32px;
+        border-radius: 10px;
+        background: #f1f5f9;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 1.05rem;
+        flex-shrink: 0;
+      }
+      .shared-loc-item .shared-loc-text {
+        flex-grow: 1;
+        min-width: 0;
+      }
+      .shared-loc-item .shared-loc-title {
+        font-weight: 600;
+        font-size: 0.92rem;
+        color: #0f172a;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .shared-loc-item .shared-loc-sub {
+        font-size: 0.78rem;
+        color: #64748b;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .shared-loc-footer {
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        padding: 0.45rem 0.75rem 0.2rem;
+        font-size: 0.72rem;
+        color: #94a3b8;
+        border-top: 1px solid #f1f5f9;
+        margin-top: 0.35rem;
+      }
+    `;
+    document.head.appendChild(style);
+  }
+
+  setupDropdown() {
+    if (!this.dropdown && this.input.parentElement) {
+      const dd = document.createElement('div');
+      dd.className = 'shared-loc-autocomplete-menu';
+      dd.style.display = 'none';
+      dd.setAttribute('role', 'listbox');
+      dd.setAttribute('aria-label', 'Address suggestions');
+      this.input.parentElement.appendChild(dd);
+      this.dropdown = dd;
+    }
+  }
+
+  bindEvents() {
+    this.input.setAttribute('autocomplete', 'off');
+    this.input.addEventListener('input', this._boundInput);
+    this.input.addEventListener('keydown', this._boundKeydown);
+    document.addEventListener('click', this._boundDocClick);
+  }
+
+  showSpinner(show) {
+    if (this.spinner) {
+      this.spinner.style.display = show ? 'block' : 'none';
+    }
+  }
+
+  close() {
+    if (this.dropdown) {
+      this.dropdown.style.display = 'none';
+      this.dropdown.innerHTML = '';
+    }
+    this.currentItems = [];
+    this.activeIndex = -1;
+    this.showSpinner(false);
+  }
+
+  handleInput() {
+    clearTimeout(this.debounceTimer);
+    const query = this.input.value;
+    this.debounceTimer = setTimeout(() => {
+      this.search(query);
+    }, 300);
+  }
+
+  handleKeydown(e) {
+    if (!this.dropdown || this.dropdown.style.display === 'none' || this.currentItems.length === 0) return;
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      this.activeIndex = (this.activeIndex + 1) % this.currentItems.length;
+      this.updateActiveSelection();
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      this.activeIndex = (this.activeIndex - 1 + this.currentItems.length) % this.currentItems.length;
+      this.updateActiveSelection();
+    } else if (e.key === 'Enter') {
+      if (this.activeIndex >= 0 && this.activeIndex < this.currentItems.length) {
+        e.preventDefault();
+        e.stopPropagation();
+        this.selectItem(this.currentItems[this.activeIndex]);
+      }
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      this.close();
+    }
+  }
+
+  handleDocumentClick(e) {
+    if (!this.input.contains(e.target) && this.dropdown && !this.dropdown.contains(e.target)) {
+      this.close();
+    }
+  }
+
+  updateActiveSelection() {
+    if (!this.dropdown) return;
+    const rows = this.dropdown.querySelectorAll('.shared-loc-item, .location-autocomplete-item');
+    rows.forEach((r, idx) => {
+      if (idx === this.activeIndex) {
+        r.classList.add('active');
+        if (typeof r.scrollIntoView === 'function') {
+          r.scrollIntoView({ block: 'nearest' });
+        }
+      } else {
+        r.classList.remove('active');
+      }
+    });
+  }
+
+  selectItem(item) {
+    if (!item) return;
+    this.input.value = item.fullAddress;
+    this.close();
+
+    if (this.errorElement) {
+      this.errorElement.style.display = 'none';
+    }
+
+    if (typeof this.options.onSelect === 'function') {
+      this.options.onSelect(item);
+    }
+
+    // Dispatch native change & input events for frameworks
+    this.input.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  render(items) {
+    if (!this.dropdown) return;
+    this.dropdown.innerHTML = '';
+    this.currentItems = items || [];
+    this.activeIndex = -1;
+
+    if (!items || items.length === 0) {
+      this.close();
+      return;
+    }
+
+    items.forEach((item, index) => {
+      const row = document.createElement('div');
+      row.className = 'shared-loc-item location-autocomplete-item';
+      row.setAttribute('role', 'option');
+      row.dataset.index = String(index);
+
+      const iconDiv = document.createElement('div');
+      iconDiv.className = 'shared-loc-icon loc-icon';
+      iconDiv.textContent = item.icon || '📍';
+
+      const textDiv = document.createElement('div');
+      textDiv.className = 'shared-loc-text loc-text';
+
+      const titleDiv = document.createElement('div');
+      titleDiv.className = 'shared-loc-title loc-title';
+      titleDiv.textContent = item.title;
+
+      const subDiv = document.createElement('div');
+      subDiv.className = 'shared-loc-sub loc-sub';
+      subDiv.textContent = item.subtitle;
+
+      textDiv.appendChild(titleDiv);
+      textDiv.appendChild(subDiv);
+      row.appendChild(iconDiv);
+      row.appendChild(textDiv);
+
+      row.addEventListener('click', () => {
+        this.selectItem(item);
+      });
+
+      this.dropdown.appendChild(row);
+    });
+
+    const footer = document.createElement('div');
+    footer.className = 'shared-loc-footer location-autocomplete-footer';
+
+    const leftBadge = document.createElement('span');
+    leftBadge.textContent = '✨ Address & Venue Finder';
+    const rightBadge = document.createElement('span');
+    rightBadge.textContent = 'Free · OpenStreetMap & Postcodes.io';
+
+    footer.appendChild(leftBadge);
+    footer.appendChild(rightBadge);
+    this.dropdown.appendChild(footer);
+
+    this.dropdown.style.display = 'block';
+  }
+
+  async fetchPostcodes(query, signal) {
+    const cleanQuery = query.trim().toUpperCase().replace(/\s+/g, '');
+    if (UK_FULL_POSTCODE_REGEX.test(query.trim())) {
+      try {
+        const res = await fetch(`https://api.postcodes.io/postcodes/${encodeURIComponent(cleanQuery)}`, { signal });
+        if (res.ok) {
+          const data = await res.json();
+          if (data.status === 200 && data.result) {
+            const r = data.result;
+            const subParts = [r.admin_district, r.region, 'United Kingdom'].filter(Boolean);
+            const fullParts = [r.postcode, r.admin_ward, r.admin_district, r.region, 'UK'].filter(Boolean);
+            return [{
+              icon: '📮',
+              title: r.postcode,
+              subtitle: subParts.join(', '),
+              fullAddress: fullParts.join(', '),
+              postcode: r.postcode,
+              city: r.admin_district || '',
+              country: 'UK',
+              raw: r
+            }];
+          }
+        }
+      } catch (e) {
+        // Ignored or aborted
+      }
+    }
+
+    try {
+      const autoRes = await fetch(`https://api.postcodes.io/postcodes/${encodeURIComponent(cleanQuery)}/autocomplete`, { signal });
+      if (autoRes.ok) {
+        const autoData = await autoRes.json();
+        if (autoData.status === 200 && Array.isArray(autoData.result)) {
+          return autoData.result.slice(0, 5).map(pc => ({
+            icon: '📮',
+            title: pc,
+            subtitle: 'UK Postcode',
+            fullAddress: pc + ', UK',
+            postcode: pc,
+            city: '',
+            country: 'UK',
+            raw: { postcode: pc }
+          }));
+        }
+      }
+    } catch (e) {
+      // Ignored or aborted
+    }
+    return [];
+  }
+
+  async fetchPhotonVenues(query, signal) {
+    const bbox = '-7.57,49.96,1.68,58.64';
+    const url = `https://photon.komoot.io/api/?q=${encodeURIComponent(query)}&limit=6&lang=en&bbox=${bbox}`;
+    try {
+      const res = await fetch(url, { signal });
+      if (!res.ok) return [];
+      const data = await res.json();
+      if (!data.features || !Array.isArray(data.features)) return [];
+
+      return data.features.map(f => {
+        const p = f.properties || {};
+        const name = p.name || p.street || p.city || query;
+        const subParts = [
+          p.housenumber ? p.housenumber + ' ' + (p.street || '') : p.street,
+          p.district,
+          p.city || p.town || p.village,
+          p.postcode,
+          p.country || 'UK'
+        ].filter(Boolean);
+
+        const isVenue = !p.housenumber && (p.osm_value === 'amenity' || p.osm_value === 'tourism' || p.osm_value === 'leisure' || p.osm_key === 'amenity');
+        const fullParts = [name, ...subParts.filter(s => s !== name)];
+        const fullAddress = fullParts.filter(Boolean).join(', ');
+
+        return {
+          icon: isVenue ? '🏛️' : '📍',
+          title: name,
+          subtitle: subParts.join(', '),
+          fullAddress: fullAddress,
+          postcode: p.postcode || '',
+          city: p.city || p.town || '',
+          country: p.country || 'UK',
+          raw: f
+        };
+      });
+    } catch (e) {
+      return [];
+    }
+  }
+
+  async search(query) {
+    const trimmed = (query || '').trim();
+    if (trimmed.length < 2) {
+      this.close();
+      return;
+    }
+
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+
+    this.showSpinner(true);
+
+    try {
+      let results = [];
+      if (this.options.country === 'uk' && UK_POSTCODE_REGEX.test(trimmed)) {
+        results = await this.fetchPostcodes(trimmed, signal);
+        if (results.length < 3) {
+          const venueResults = await this.fetchPhotonVenues(trimmed, signal);
+          results = [...results, ...venueResults].slice(0, 6);
+        }
+      } else {
+        results = await this.fetchPhotonVenues(trimmed, signal);
+      }
+
+      this.showSpinner(false);
+      this.render(results);
+    } catch (err) {
+      if (err.name !== 'AbortError') {
+        this.showSpinner(false);
+        this.close();
+      }
+    }
+  }
+
+  destroy() {
+    clearTimeout(this.debounceTimer);
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    if (this.input) {
+      this.input.removeEventListener('input', this._boundInput);
+      this.input.removeEventListener('keydown', this._boundKeydown);
+    }
+    document.removeEventListener('click', this._boundDocClick);
+    if (this.dropdown && this.dropdown.parentElement) {
+      this.dropdown.remove();
+    }
+  }
+}
+
+/**
+ * Functional helper for easy one-line attachment
+ * @param {Object} options
+ * @returns {AddressAutocomplete}
+ */
+export function setupAddressAutocomplete(options) {
+  return new AddressAutocomplete(options);
+}

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/PwaManager.js

@@ -82,6 +82,9 @@ export class PwaManager {
       navigator.serviceWorker.addEventListener('message', (event) => {
         if (event.data?.type === 'ON_APP_NOTIFICATION') {
           this.syncAppBadge();
+          if (typeof window !== 'undefined' && window.dispatchEvent) {
+            window.dispatchEvent(new CustomEvent('pwa:notification-received', { detail: event.data.payload }));
+          }
         }
       });
     }
@@ -118,11 +121,109 @@ export class PwaManager {
       }));
     }
 
+    if (this.options.enableUpdateToast) {
+      this.showUpdateToast(worker);
+    }
+
     if (typeof this.options.onUpdateAvailable === 'function') {
       this.options.onUpdateAvailable(worker);
     }
   }
 
+  /**
+   * Renders a discreet, glassmorphic floating update pill to prompt user refresh
+   */
+  static showUpdateToast(worker) {
+    if (typeof document === 'undefined' || document.getElementById('pwaUniversalUpdateToast')) {
+      return;
+    }
+
+    const toast = document.createElement('div');
+    toast.id = 'pwaUniversalUpdateToast';
+    toast.setAttribute('role', 'status');
+    toast.setAttribute('aria-live', 'polite');
+    toast.setAttribute('aria-label', `${this.options.appName || 'App'} update available`);
+
+    toast.style.position = 'fixed';
+    toast.style.bottom = 'max(16px, env(safe-area-inset-bottom, 16px))';
+    toast.style.left = '50%';
+    toast.style.transform = 'translateX(-50%)';
+    toast.style.zIndex = '99999';
+    toast.style.display = 'flex';
+    toast.style.alignItems = 'center';
+    toast.style.gap = '12px';
+    toast.style.padding = '8px 14px 8px 16px';
+    toast.style.backgroundColor = 'rgba(15, 23, 42, 0.94)';
+    toast.style.backdropFilter = 'blur(12px)';
+    toast.style.webkitBackdropFilter = 'blur(12px)';
+    toast.style.border = '1px solid rgba(255, 255, 255, 0.12)';
+    toast.style.borderRadius = '9999px';
+    toast.style.boxShadow = '0 12px 32px rgba(0, 0, 0, 0.45)';
+    toast.style.color = '#ffffff';
+    toast.style.fontFamily = 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+    toast.style.fontSize = '14px';
+    toast.style.lineHeight = '1.4';
+    toast.style.maxWidth = 'calc(100vw - 32px)';
+    toast.style.boxSizing = 'border-box';
+    toast.style.transition = 'all 0.25s cubic-bezier(0.16, 1, 0.3, 1)';
+
+    const appTitle = this.options.appName || 'App';
+
+    toast.innerHTML = `
+      <div style="display: flex; align-items: center; gap: 8px; white-space: nowrap;">
+        <span style="display: inline-block; width: 8px; height: 8px; border-radius: 50%; background-color: #10b981; box-shadow: 0 0 8px #10b981;"></span>
+        <span style="font-weight: 500;">${appTitle} updated</span>
+      </div>
+      <button id="pwaUpdateActionBtn" type="button" style="
+        background: #2563eb;
+        color: #ffffff;
+        border: none;
+        padding: 6px 14px;
+        border-radius: 9999px;
+        font-size: 13px;
+        font-weight: 600;
+        cursor: pointer;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 36px;
+        transition: background 0.2s;
+        white-space: nowrap;
+      ">Refresh</button>
+      <button id="pwaUpdateDismissBtn" type="button" style="
+        background: transparent;
+        color: #94a3b8;
+        border: none;
+        font-size: 16px;
+        cursor: pointer;
+        padding: 6px;
+        min-width: 36px;
+        min-height: 36px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        line-height: 1;
+      " aria-label="Dismiss">✕</button>
+    `;
+
+    document.body.appendChild(toast);
+
+    const updateBtn = document.getElementById('pwaUpdateActionBtn');
+    if (updateBtn) {
+      updateBtn.addEventListener('click', () => {
+        toast.remove();
+        this.applyUpdate(worker);
+      });
+    }
+
+    const dismissBtn = document.getElementById('pwaUpdateDismissBtn');
+    if (dismissBtn) {
+      dismissBtn.addEventListener('click', () => {
+        toast.remove();
+      });
+    }
+  }
+
   /**
    * Sends skipWaiting postMessage to the waiting worker and triggers clean reload
    */
@@ -167,8 +268,11 @@ export class PwaManager {
    * @returns {Promise<void>}
    */
   static setAppBadge(count) {
+    const num = Math.max(0, parseInt(count, 10) || 0);
+    if (typeof window !== 'undefined' && window.dispatchEvent) {
+      window.dispatchEvent(new CustomEvent('pwa:badge-updated', { detail: { count: num } }));
+    }
     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();
@@ -180,6 +284,9 @@ export class PwaManager {
    * @returns {Promise<void>}
    */
   static clearAppBadge() {
+    if (typeof window !== 'undefined' && window.dispatchEvent) {
+      window.dispatchEvent(new CustomEvent('pwa:badge-updated', { detail: { count: 0 } }));
+    }
     if (typeof navigator !== 'undefined' && 'clearAppBadge' in navigator) {
       return navigator.clearAppBadge().catch(() => {});
     }
@@ -194,9 +301,6 @@ export class PwaManager {
    */
   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' } });
@@ -209,14 +313,28 @@ export class PwaManager {
         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();
+      let count = 0;
+      if (data) {
+        if (typeof data.unread_count === 'number') {
+          count = data.unread_count;
+        } else if (typeof data.count === 'number') {
+          count = data.count;
+        } else if (typeof data.unreadCount === 'number') {
+          count = data.unreadCount;
+        } else if (data.status === 'success' && Array.isArray(data.message)) {
+          count = data.message.length;
+        } else if (Array.isArray(data.data)) {
+          count = data.data.length;
+        } else if (Array.isArray(data.notifications)) {
+          count = data.notifications.length;
         }
       }
+      const num = Math.max(0, parseInt(count, 10) || 0);
+      if (num > 0) {
+        await this.setAppBadge(num);
+      } else {
+        await this.clearAppBadge();
+      }
     } catch (e) {
       // Harmless no-op on network failure or offline mode
     }

package/config/version.php

@@ -1,3 +1,3 @@
 <?php
-define('APP_VERSION', 'v1.2.83');
+define('APP_VERSION', 'v1.2.87');
 

package/index.js

@@ -28,4 +28,7 @@ export * from './AcctMgt/recaptchaToken.js';
 export * from './AcctMgt/AdminAuthForm.js';
 export * from './general.js';
 export * from './CardCanvasGenerator.js';
-export * from './ShareManager.js';
+export * from './ShareManager.js';
+export * from './WebAuthnClient.js';
+export * from './OtpInputManager.js';
+export * from './AddressAutocomplete.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modernman00/shared-js-lib",
-  "version": "1.2.83",
+  "version": "1.2.87",
   "description": "Reusable JS utilities for numerous js problems",
   "homepage": "https://github.com/modernman00/shared-js-lib#readme",
   "keywords": [
@@ -17,7 +17,7 @@
     "url": "git+https://github.com/modernman00/shared-js-lib.git"
   },
   "license": "MIT",
-  "author": "olawale olaogun",
+  "author": "Core Platform Engineering Team",
   "main": "index.js",
   "scripts": {
     "test": "jest"
@@ -62,6 +62,8 @@
     "PwaInstall.js",
     "CardCanvasGenerator.js",
     "ShareManager.js",
+    "OtpInputManager.js",
+    "AddressAutocomplete.js",
     "templates/"
   ],
   "devDependencies": {

package/release-history.md

@@ -1,4 +1,9 @@
 
+## v1.2.86 — 2026-10-12 22:38
+### Changelog for v1.2.86
+- 🚀 feat: Add AddressAutocomplete class and setupAddressAutocomplete helper for zero-cost UK geocoding (Photon OSM + Postcodes.io)
+- 🛡️ Add keyboard navigation, defensive textContent escaping (XSS immune), AbortController race protection, and full Jest test suite
+
 ## v1.2.15 — 2025-08-18 21:56
 ### Changelog for v1.2.15
 
@@ -136,3 +141,20 @@
 - 🔖 Bump version to 1.2.83 _(by modernman00)_
 - feat(pwa): centralize resilient OfflineQueue, PwaManager and standardized Service Worker template _(by modernman00)_
 - feat: enhance release script with interactive npm login and improved workflow _(by modernman00)_
+
+## v1.2.84 — 2026-10-09 16:10
+### Changelog for v1.2.84
+
+- 🧹 Auto-commit before release _(by modernman00)_
+- feat(otp): add OtpInputManager supporting iOS QuickType autofill and magic link auto-submit _(by modernman00)_
+
+## v1.2.87 — 2026-10-12 23:28
+### Changelog for v1.2.87
+
+- chore(release): 1.2.87 _(by github-actions)_
+- fix(ci): add permissions contents write and continue-on-error for artifact upload _(by modernman00)_
+- fix(ci): convert babel config to cjs and upgrade github actions to v4 with node 20 _(by modernman00)_
+- feat: add AddressAutocomplete component (Photon + Postcodes.io) v1.2.86 _(by modernman00)_
+- feat(pwa): harden PwaManager badging sync, support diverse envelopes, and dispatch pwa:badge-updated event _(by modernman00)_
+- 🔖 Release v1.2.84 _(by modernman00)_
+- 🧹 Auto-commit before release _(by modernman00)_