handhold-sdk 1.0.0

package/src/observers/ElementScanner.js

@@ -0,0 +1,284 @@
+/**
+ * Hand Hold SDK - Element Scanner
+ * Scans and extracts interactive UI elements from the page
+ */
+
+import {
+  generateSelector,
+  getElementText,
+  getElementRole,
+  getElementPosition,
+  isElementVisible,
+  isInteractiveElement,
+} from '../utils/domUtils.js';
+
+class ElementScanner {
+  constructor(config) {
+    this.config = config;
+    this.excludeSelectors = [
+      '#handhold-container',
+      '#handhold-widget',
+      '#handhold-overlay',
+      '[data-handhold-ignore]',
+    ];
+  }
+
+  /**
+   * Scan page and extract all relevant UI elements
+   * @param {Element} [root=document.body] - Root element to scan from
+   * @returns {Array} - Array of element objects
+   */
+  scan(root = document.body) {
+    const elements = [];
+    const seen = new Set();
+
+    // Get interactive elements
+    const interactiveElements = this._getInteractiveElements(root);
+
+    for (const element of interactiveElements) {
+      // Skip excluded elements
+      if (this._isExcluded(element)) continue;
+
+      // Skip invisible elements
+      if (!isElementVisible(element)) continue;
+
+      // Generate selector
+      const selector = generateSelector(element);
+      
+      // Skip duplicates
+      if (seen.has(selector)) continue;
+      seen.add(selector);
+
+      // Extract element data
+      const elementData = this._extractElementData(element, selector);
+      
+      if (elementData) {
+        elements.push(elementData);
+      }
+    }
+
+    return elements;
+  }
+
+  /**
+   * Get all interactive elements
+   * @param {Element} root - Root element
+   * @returns {Element[]}
+   */
+  _getInteractiveElements(root) {
+    const selectors = [
+      'button',
+      'a[href]',
+      'input:not([type="hidden"])',
+      'select',
+      'textarea',
+      '[role="button"]',
+      '[role="link"]',
+      '[role="checkbox"]',
+      '[role="radio"]',
+      '[role="menuitem"]',
+      '[role="tab"]',
+      '[role="switch"]',
+      '[onclick]',
+      '[tabindex]:not([tabindex="-1"])',
+      '.btn',
+      '.button',
+    ];
+
+    return Array.from(root.querySelectorAll(selectors.join(', ')));
+  }
+
+  /**
+   * Check if element should be excluded
+   * @param {Element} element
+   * @returns {boolean}
+   */
+  _isExcluded(element) {
+    // Check if element matches exclude selectors
+    for (const selector of this.excludeSelectors) {
+      if (element.matches(selector) || element.closest(selector)) {
+        return true;
+      }
+    }
+
+    // Exclude hidden inputs
+    if (element.tagName === 'INPUT' && element.type === 'hidden') {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Extract data from element
+   * @param {Element} element
+   * @param {string} selector
+   * @returns {Object|null}
+   */
+  _extractElementData(element, selector) {
+    let text = getElementText(element);
+    const ariaLabel = element.getAttribute('aria-label');
+    const title = element.getAttribute('title');
+    const role = getElementRole(element);
+    const id = element.id;
+    const name = element.getAttribute('name');
+
+    // For inputs, try to find label if text/aria-label is missing
+    if (['input', 'textarea', 'select'].includes(element.tagName.toLowerCase())) {
+      const label = this._findInputLabel(element);
+      if (label) {
+        text = text ? `${label} (${text})` : label;
+      } else if (name) {
+        // Fallback to name if no label found
+        text = text ? `${name} (${text})` : name;
+      }
+    }
+
+    // Skip elements with no identifiable text
+    if (!text && !ariaLabel && !title && !id && !name) {
+      return null;
+    }
+
+    const position = getElementPosition(element);
+
+    return {
+      text: text || '',
+      aria_label: ariaLabel || '',
+      title: title || '',
+      role,
+      selector,
+      tag: element.tagName.toLowerCase(),
+      type: element.type || null,
+      disabled: element.disabled || element.getAttribute('aria-disabled') === 'true',
+      position,
+      data_testid: element.getAttribute('data-testid') || null,
+      id: id || null,
+      name: name || null,
+    };
+  }
+
+  /**
+   * Get page context information
+   * @returns {Object}
+   */
+  getPageContext() {
+    return {
+      title: document.title,
+      route: window.location.pathname,
+      url: window.location.href,
+      headings: this._extractHeadings(),
+      forms: this._extractForms(),
+      meta: this._extractMeta(),
+    };
+  }
+
+  /**
+   * Extract page headings
+   * @returns {string[]}
+   */
+  _extractHeadings() {
+    const headings = [];
+    const headingElements = document.querySelectorAll('h1, h2, h3');
+    
+    headingElements.forEach(h => {
+      const text = h.textContent?.trim();
+      if (text && !this._isExcluded(h)) {
+        headings.push(text);
+      }
+    });
+
+    return headings.slice(0, 10); // Limit to 10 headings
+  }
+
+  /**
+   * Extract form information
+   * @returns {Object[]}
+   */
+  _extractForms() {
+    const forms = [];
+    const formElements = document.querySelectorAll('form');
+
+    formElements.forEach(form => {
+      if (this._isExcluded(form)) return;
+
+      const inputs = Array.from(form.querySelectorAll('input, select, textarea'))
+        .filter(el => el.type !== 'hidden' && isElementVisible(el))
+        .map(el => ({
+          name: el.name || el.id || '',
+          type: el.type || el.tagName.toLowerCase(),
+          label: this._findInputLabel(el),
+        }));
+
+      if (inputs.length > 0) {
+        forms.push({
+          id: form.id || null,
+          action: form.action || null,
+          method: form.method || 'get',
+          inputs,
+        });
+      }
+    });
+
+    return forms;
+  }
+
+  /**
+   * Find label for an input element
+   * @param {Element} input
+   * @returns {string}
+   */
+  _findInputLabel(input) {
+    // Check for associated label
+    if (input.id) {
+      const label = document.querySelector(`label[for="${input.id}"]`);
+      if (label) return label.textContent?.trim() || '';
+    }
+
+    // Check for parent label
+    const parentLabel = input.closest('label');
+    if (parentLabel) {
+      return parentLabel.textContent?.trim() || '';
+    }
+
+    // Check for aria-label
+    return input.getAttribute('aria-label') || input.placeholder || '';
+  }
+
+  /**
+   * Extract page meta information
+   * @returns {Object}
+   */
+  _extractMeta() {
+    return {
+      description: document.querySelector('meta[name="description"]')?.content || '',
+      keywords: document.querySelector('meta[name="keywords"]')?.content || '',
+      viewport: document.querySelector('meta[name="viewport"]')?.content || '',
+    };
+  }
+
+  /**
+   * Find element by selector
+   * @param {string} selector
+   * @returns {Element|null}
+   */
+  findElement(selector) {
+    try {
+      return document.querySelector(selector);
+    } catch (e) {
+      console.warn('[HandHold] Invalid selector:', selector);
+      return null;
+    }
+  }
+
+  /**
+   * Check if an element exists and is visible
+   * @param {string} selector
+   * @returns {boolean}
+   */
+  elementExists(selector) {
+    const element = this.findElement(selector);
+    return element && isElementVisible(element);
+  }
+}
+
+export default ElementScanner;

package/src/observers/NavigationObserver.js

@@ -0,0 +1,182 @@
+/**
+ * Hand Hold SDK - Navigation Observer
+ * Detects route/URL changes in SPAs and traditional navigation
+ */
+
+import eventBus from '../utils/eventBus.js';
+
+class NavigationObserver {
+  constructor(config) {
+    this.config = config;
+    this.currentRoute = this._getCurrentRoute();
+    this.isObserving = false;
+    
+    // Bound handlers for cleanup
+    this._boundPopstateHandler = this._onPopstate.bind(this);
+    this._boundHashchangeHandler = this._onHashchange.bind(this);
+    this._boundClickHandler = this._onLinkClick.bind(this);
+  }
+
+  /**
+   * Get current route
+   * @returns {string}
+   */
+  _getCurrentRoute() {
+    return window.location.pathname + window.location.search + window.location.hash;
+  }
+
+  /**
+   * Start observing navigation changes
+   */
+  observe() {
+    if (this.isObserving) return;
+
+    // Listen for popstate (back/forward navigation)
+    window.addEventListener('popstate', this._boundPopstateHandler);
+
+    // Listen for hashchange
+    window.addEventListener('hashchange', this._boundHashchangeHandler);
+
+    // Intercept link clicks for SPA navigation detection
+    document.addEventListener('click', this._boundClickHandler, true);
+
+    // Patch pushState and replaceState for SPA frameworks
+    this._patchHistoryMethods();
+
+    this.isObserving = true;
+  }
+
+  /**
+   * Stop observing navigation changes
+   */
+  disconnect() {
+    if (!this.isObserving) return;
+
+    window.removeEventListener('popstate', this._boundPopstateHandler);
+    window.removeEventListener('hashchange', this._boundHashchangeHandler);
+    document.removeEventListener('click', this._boundClickHandler, true);
+
+    this._unpatchHistoryMethods();
+
+    this.isObserving = false;
+  }
+
+  /**
+   * Patch history.pushState and history.replaceState
+   */
+  _patchHistoryMethods() {
+    // Store original methods
+    this._originalPushState = window.history.pushState;
+    this._originalReplaceState = window.history.replaceState;
+
+    const self = this;
+
+    // Patch pushState
+    window.history.pushState = function(...args) {
+      self._originalPushState.apply(this, args);
+      self._checkRouteChange();
+    };
+
+    // Patch replaceState
+    window.history.replaceState = function(...args) {
+      self._originalReplaceState.apply(this, args);
+      self._checkRouteChange();
+    };
+  }
+
+  /**
+   * Restore original history methods
+   */
+  _unpatchHistoryMethods() {
+    if (this._originalPushState) {
+      window.history.pushState = this._originalPushState;
+    }
+    if (this._originalReplaceState) {
+      window.history.replaceState = this._originalReplaceState;
+    }
+  }
+
+  /**
+   * Handle popstate event
+   */
+  _onPopstate(event) {
+    this._checkRouteChange();
+  }
+
+  /**
+   * Handle hashchange event
+   */
+  _onHashchange(event) {
+    this._checkRouteChange();
+  }
+
+  /**
+   * Handle link clicks
+   */
+  _onLinkClick(event) {
+    // Find closest anchor element
+    const anchor = event.target.closest('a');
+    if (!anchor) return;
+
+    const href = anchor.getAttribute('href');
+    if (!href) return;
+
+    // Skip external links
+    if (href.startsWith('http') && !href.startsWith(window.location.origin)) {
+      return;
+    }
+
+    // Skip special links
+    if (href.startsWith('javascript:') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+      return;
+    }
+
+    // Check for route change after a short delay (to allow SPA routing to complete)
+    setTimeout(() => this._checkRouteChange(), 50);
+  }
+
+  /**
+   * Check if route has changed and emit event
+   */
+  _checkRouteChange() {
+    const newRoute = this._getCurrentRoute();
+    
+    if (newRoute !== this.currentRoute) {
+      const previousRoute = this.currentRoute;
+      this.currentRoute = newRoute;
+
+      eventBus.emit('navigation:changed', {
+        route: newRoute,
+        previousRoute,
+        pathname: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash,
+      });
+    }
+  }
+
+  /**
+   * Get current pathname only
+   * @returns {string}
+   */
+  getPathname() {
+    return window.location.pathname;
+  }
+
+  /**
+   * Get current full route
+   * @returns {string}
+   */
+  getRoute() {
+    return this.currentRoute;
+  }
+
+  /**
+   * Force route check (useful after known navigation)
+   */
+  forceCheck() {
+    this._checkRouteChange();
+  }
+}
+
+export default NavigationObserver;