handhold-sdk 1.0.0

package/src/utils/MarkdownRenderer.js

@@ -0,0 +1,39 @@
+import { marked } from 'marked';
+
+/**
+ * Utility to render Markdown to HTML safely
+ */
+export const MarkdownRenderer = {
+  /**
+   * Configure marked options
+   */
+  init() {
+    marked.setOptions({
+      renderer: new marked.Renderer(),
+      gfm: true, // GitHub Flavored Markdown
+      breaks: true, // Convert \n to <br>
+      pedantic: false,
+      sanitize: false, // We'll assume the input is safe or sanitize it elsewhere if needed, but for now we trust the backend/AI
+      smartLists: true,
+      smartypants: false,
+    });
+  },
+
+  /**
+   * Parse markdown string to HTML
+   * @param {string} text - Markdown text
+   * @returns {string} - HTML string
+   */
+  parse(text) {
+    if (!text) return '';
+    try {
+      return marked.parse(text);
+    } catch (e) {
+      console.error('[HandHold] Markdown parsing error:', e);
+      return text; // Fallback to raw text
+    }
+  }
+};
+
+// Initialize on load
+MarkdownRenderer.init();

package/src/utils/domUtils.js

@@ -0,0 +1,350 @@
+/**
+ * Hand Hold SDK - DOM Utilities
+ * Helper functions for DOM manipulation and element scanning
+ */
+
+/**
+ * Generate a stable CSS selector for an element
+ * Priority: data-testid > id > unique class > nth-child path
+ * @param {Element} element - DOM element
+ * @returns {string} - CSS selector
+ */
+export function generateSelector(element) {
+  if (!element || element === document.body) {
+    return 'body';
+  }
+
+  // Priority 1: data-testid
+  const testId = element.getAttribute('data-testid');
+  if (testId) {
+    return `[data-testid="${testId}"]`;
+  }
+
+  // Priority 2: ID (if unique)
+  if (element.id && document.querySelectorAll(`#${CSS.escape(element.id)}`).length === 1) {
+    return `#${CSS.escape(element.id)}`;
+  }
+
+  // Priority 3: data-id or data-key
+  const dataId = element.getAttribute('data-id') || element.getAttribute('data-key');
+  if (dataId) {
+    const attr = element.hasAttribute('data-id') ? 'data-id' : 'data-key';
+    return `[${attr}="${dataId}"]`;
+  }
+
+  // Priority 4: Unique class combination
+  if (element.classList.length > 0) {
+    const selector = `.${Array.from(element.classList).map(c => CSS.escape(c)).join('.')}`;
+    if (document.querySelectorAll(selector).length === 1) {
+      return selector;
+    }
+  }
+
+  // Priority 5: Tag + text content for buttons/links
+  if (['BUTTON', 'A'].includes(element.tagName)) {
+    const text = element.textContent?.trim();
+    if (text && text.length < 50) {
+      // Use XPath-style or build path
+      const tag = element.tagName.toLowerCase();
+      const selector = buildPathSelector(element);
+      return selector;
+    }
+  }
+
+  // Fallback: Build path selector
+  return buildPathSelector(element);
+}
+
+/**
+ * Build a path-based selector using nth-child
+ * @param {Element} element - DOM element
+ * @returns {string} - Path selector
+ */
+function buildPathSelector(element) {
+  const path = [];
+  let current = element;
+
+  while (current && current !== document.body && current !== document.documentElement) {
+    let selector = current.tagName.toLowerCase();
+
+    // Add ID if present
+    if (current.id) {
+      selector = `#${CSS.escape(current.id)}`;
+      path.unshift(selector);
+      break;
+    }
+
+    // Add data-testid if present
+    const testId = current.getAttribute('data-testid');
+    if (testId) {
+      selector = `[data-testid="${testId}"]`;
+      path.unshift(selector);
+      break;
+    }
+
+    // Add class if unique among siblings
+    if (current.classList.length > 0) {
+      const classSelector = `.${Array.from(current.classList).slice(0, 2).map(c => CSS.escape(c)).join('.')}`;
+      const siblings = current.parentElement?.querySelectorAll(`:scope > ${current.tagName.toLowerCase()}${classSelector}`);
+      if (siblings?.length === 1) {
+        selector = `${current.tagName.toLowerCase()}${classSelector}`;
+      }
+    }
+
+    // Add nth-child if needed
+    if (current.parentElement) {
+      const siblings = Array.from(current.parentElement.children).filter(
+        child => child.tagName === current.tagName
+      );
+      if (siblings.length > 1) {
+        const index = siblings.indexOf(current) + 1;
+        selector += `:nth-of-type(${index})`;
+      }
+    }
+
+    path.unshift(selector);
+    current = current.parentElement;
+  }
+
+  return path.join(' > ');
+}
+
+/**
+ * Get element's visible text content
+ * @param {Element} element - DOM element
+ * @returns {string} - Trimmed text content
+ */
+export function getElementText(element) {
+  // For inputs, get value or placeholder
+  if (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA') {
+    return element.value || element.placeholder || '';
+  }
+
+  // For select, get selected option text
+  if (element.tagName === 'SELECT') {
+    return element.options[element.selectedIndex]?.text || '';
+  }
+
+  // Prefer an explicit accessible name when present (Phase 3.3).
+  const ariaLabel = element.getAttribute && element.getAttribute('aria-label');
+  if (ariaLabel && ariaLabel.trim()) {
+    return ariaLabel.trim().substring(0, 100);
+  }
+
+  // Collect only direct text nodes first — avoids picking up badge/icon/counter text
+  // e.g. <button>Approve <span class="badge">3</span> Timesheets</button> → "Approve Timesheets"
+  const directTexts = Array.from(element.childNodes)
+    .filter(node => node.nodeType === Node.TEXT_NODE)
+    .map(node => node.textContent.trim())
+    .filter(t => t.length > 0);
+
+  if (directTexts.length > 0) {
+    return directTexts.join(' ').replace(/\s+/g, ' ').substring(0, 100);
+  }
+
+  // Fallback: when the button text is wrapped in a child element (e.g. <button><span>Text</span></button>)
+  // Skip SVG icons and aria-hidden decorations (icon glyphs, counter badges).
+  const childTexts = Array.from(element.children)
+    .filter(child => {
+      if (child.tagName && child.tagName.toLowerCase() === 'svg') return false;
+      if (child.getAttribute && child.getAttribute('aria-hidden') === 'true') return false;
+      const style = window.getComputedStyle(child);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    })
+    .map(child => {
+      // Only get direct text nodes of this child, not further nested content
+      return Array.from(child.childNodes)
+        .filter(node => node.nodeType === Node.TEXT_NODE)
+        .map(node => node.textContent.trim())
+        .filter(t => t.length > 0)
+        .join(' ');
+    })
+    .filter(t => t.length > 0);
+
+  return childTexts.join(' ').replace(/\s+/g, ' ').substring(0, 100);
+}
+
+/**
+ * Get element's role (button, link, input, etc.)
+ * @param {Element} element - DOM element
+ * @returns {string} - Element role
+ */
+export function getElementRole(element) {
+  // Check explicit ARIA role
+  const ariaRole = element.getAttribute('role');
+  if (ariaRole) return ariaRole;
+
+  // Infer from tag
+  const tagMap = {
+    'BUTTON': 'button',
+    'A': 'link',
+    'INPUT': 'input',
+    'SELECT': 'combobox',
+    'TEXTAREA': 'textbox',
+    'IMG': 'image',
+    'H1': 'heading',
+    'H2': 'heading',
+    'H3': 'heading',
+    'H4': 'heading',
+    'H5': 'heading',
+    'H6': 'heading',
+    'NAV': 'navigation',
+    'MAIN': 'main',
+    'SECTION': 'region',
+    'ARTICLE': 'article',
+    'ASIDE': 'complementary',
+    'FOOTER': 'contentinfo',
+    'HEADER': 'banner',
+    'FORM': 'form',
+    'TABLE': 'table',
+    'UL': 'list',
+    'OL': 'list',
+    'LI': 'listitem',
+  };
+
+  // Check for button-like behavior
+  if (element.onclick || element.getAttribute('onclick')) {
+    return 'button';
+  }
+
+  // Check for clickable divs/spans with click handlers
+  if (['DIV', 'SPAN'].includes(element.tagName)) {
+    if (element.style.cursor === 'pointer' || element.classList.contains('btn') || 
+        element.classList.contains('button') || element.getAttribute('tabindex') === '0') {
+      return 'button';
+    }
+  }
+
+  return tagMap[element.tagName] || 'generic';
+}
+
+/**
+ * Get element's bounding position
+ * @param {Element} element - DOM element
+ * @returns {Object} - { x, y, width, height }
+ */
+export function getElementPosition(element) {
+  const rect = element.getBoundingClientRect();
+  return {
+    x: Math.round(rect.left + window.scrollX),
+    y: Math.round(rect.top + window.scrollY),
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+  };
+}
+
+/**
+ * Check if element is visible
+ * @param {Element} element - DOM element
+ * @returns {boolean}
+ */
+export function isElementVisible(element) {
+  if (!element) return false;
+
+  const style = window.getComputedStyle(element);
+  
+  if (style.display === 'none') return false;
+  if (style.visibility === 'hidden') return false;
+  if (style.opacity === '0') return false;
+
+  const rect = element.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) return false;
+
+  return true;
+}
+
+/**
+ * Check if element is interactive
+ * @param {Element} element - DOM element
+ * @returns {boolean}
+ */
+export function isInteractiveElement(element) {
+  const interactiveTags = ['BUTTON', 'A', 'INPUT', 'SELECT', 'TEXTAREA'];
+  const interactiveRoles = ['button', 'link', 'checkbox', 'radio', 'textbox', 'combobox', 'menuitem', 'tab'];
+
+  if (interactiveTags.includes(element.tagName)) return true;
+  
+  const role = element.getAttribute('role');
+  if (role && interactiveRoles.includes(role)) return true;
+
+  // Check for tabindex
+  const tabindex = element.getAttribute('tabindex');
+  if (tabindex && parseInt(tabindex, 10) >= 0) return true;
+
+  // Check for onclick
+  if (element.onclick || element.getAttribute('onclick')) return true;
+
+  return false;
+}
+
+/**
+ * Get all interactive elements on page
+ * @param {Element} [root=document] - Root element to search from
+ * @returns {Element[]} - Array of interactive elements
+ */
+export function getInteractiveElements(root = document) {
+  const selectors = [
+    'button',
+    'a[href]',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="checkbox"]',
+    '[role="radio"]',
+    '[role="menuitem"]',
+    '[role="tab"]',
+    '[onclick]',
+    '[tabindex]:not([tabindex="-1"])',
+  ];
+
+  const elements = Array.from(root.querySelectorAll(selectors.join(', ')));
+  
+  return elements.filter(el => isElementVisible(el));
+}
+
+/**
+ * Create element from HTML string
+ * @param {string} html - HTML string
+ * @returns {Element}
+ */
+export function createElement(html) {
+  const template = document.createElement('template');
+  template.innerHTML = html.trim();
+  return template.content.firstChild;
+}
+
+/**
+ * Wait for element to appear in DOM
+ * @param {string} selector - CSS selector
+ * @param {number} timeout - Timeout in ms
+ * @returns {Promise<Element>}
+ */
+export function waitForElement(selector, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const element = document.querySelector(selector);
+    if (element) {
+      resolve(element);
+      return;
+    }
+
+    const observer = new MutationObserver((mutations, obs) => {
+      const element = document.querySelector(selector);
+      if (element) {
+        obs.disconnect();
+        resolve(element);
+      }
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+
+    setTimeout(() => {
+      observer.disconnect();
+      reject(new Error(`Element ${selector} not found within ${timeout}ms`));
+    }, timeout);
+  });
+}

package/src/utils/eventBus.js

@@ -0,0 +1,102 @@
+/**
+ * Hand Hold SDK - Event Bus
+ * Simple pub/sub event system for internal communication
+ */
+
+class EventBus {
+  constructor() {
+    this.events = {};
+  }
+
+  /**
+   * Subscribe to an event
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   * @returns {Function} - Unsubscribe function
+   */
+  on(event, callback) {
+    if (!this.events[event]) {
+      this.events[event] = [];
+    }
+    
+    this.events[event].push(callback);
+    
+    // Return unsubscribe function
+    return () => this.off(event, callback);
+  }
+
+  /**
+   * Subscribe to an event (one time only)
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   */
+  once(event, callback) {
+    const onceCallback = (...args) => {
+      callback(...args);
+      this.off(event, onceCallback);
+    };
+    this.on(event, onceCallback);
+  }
+
+  /**
+   * Unsubscribe from an event
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function to remove
+   */
+  off(event, callback) {
+    if (!this.events[event]) return;
+    
+    this.events[event] = this.events[event].filter(cb => cb !== callback);
+  }
+
+  /**
+   * Emit an event
+   * @param {string} event - Event name
+   * @param {...any} args - Arguments to pass to callbacks
+   */
+  emit(event, ...args) {
+    if (!this.events[event]) return;
+    
+    this.events[event].forEach(callback => {
+      try {
+        callback(...args);
+      } catch (error) {
+        console.error(`[HandHold EventBus] Error in event handler for '${event}':`, error);
+      }
+    });
+  }
+
+  /**
+   * Remove all listeners for an event (or all events)
+   * @param {string} [event] - Event name (optional)
+   */
+  clear(event) {
+    if (event) {
+      delete this.events[event];
+    } else {
+      this.events = {};
+    }
+  }
+
+  /**
+   * Get all registered events
+   * @returns {string[]} - Array of event names
+   */
+  getEvents() {
+    return Object.keys(this.events);
+  }
+
+  /**
+   * Get listener count for an event
+   * @param {string} event - Event name
+   * @returns {number} - Number of listeners
+   */
+  listenerCount(event) {
+    return this.events[event]?.length || 0;
+  }
+}
+
+// Export singleton instance
+const eventBus = new EventBus();
+export default eventBus;
+export { EventBus };

package/src/utils/index.js

@@ -0,0 +1,8 @@
+/**
+ * Hand Hold SDK - Utils Index
+ */
+
+export { default as eventBus, EventBus } from './eventBus.js';
+export { default as logger, Logger, LOG_LEVELS } from './Logger.js';
+export * as domUtils from './domUtils.js';
+export * as stringUtils from './stringUtils.js';

package/src/utils/stringUtils.js

@@ -0,0 +1,202 @@
+/**
+ * Hand Hold SDK - String Utilities
+ * Helper functions for string manipulation
+ */
+
+/**
+ * Convert string to snake_case
+ * @param {string} str - Input string
+ * @returns {string}
+ */
+export function toSnakeCase(str) {
+  return str
+    .toLowerCase()
+    .replace(/\s+/g, '_')
+    .replace(/[^\w_]/g, '')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * Convert snake_case to Title Case
+ * @param {string} str - Input string in snake_case
+ * @returns {string}
+ */
+export function toTitleCase(str) {
+  return String(str)
+    // insert a boundary at camelCase transitions: "createOkr" -> "create Okr"
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    // split on underscores, hyphens, and whitespace
+    .split(/[_\-\s]+/)
+    .filter(Boolean)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+}
+
+/**
+ * Convert to camelCase
+ * @param {string} str - Input string
+ * @returns {string}
+ */
+export function toCamelCase(str) {
+  return str
+    .toLowerCase()
+    .replace(/[_\s]+(.)/g, (_, char) => char.toUpperCase());
+}
+
+/**
+ * Truncate string with ellipsis
+ * @param {string} str - Input string
+ * @param {number} maxLength - Maximum length
+ * @returns {string}
+ */
+export function truncate(str, maxLength = 50) {
+  if (!str || str.length <= maxLength) return str;
+  return str.substring(0, maxLength - 3) + '...';
+}
+
+/**
+ * Capitalize first letter
+ * @param {string} str - Input string
+ * @returns {string}
+ */
+export function capitalize(str) {
+  if (!str) return '';
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Generate hash from string
+ * @param {string} str - Input string
+ * @returns {string} - Hash string
+ */
+export function hashString(str) {
+  let hash = 0;
+  if (!str || str.length === 0) return hash.toString(36);
+  
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Extract keywords from text
+ * @param {string} text - Input text
+ * @returns {string[]} - Array of keywords
+ */
+export function extractKeywords(text) {
+  const stopWords = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+    'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+    'could', 'should', 'may', 'might', 'must', 'shall', 'can', 'this',
+    'that', 'these', 'those', 'i', 'you', 'he', 'she', 'it', 'we', 'they',
+    'what', 'which', 'who', 'when', 'where', 'why', 'how', 'all', 'each',
+    'every', 'both', 'few', 'more', 'most', 'other', 'some', 'such', 'no',
+    'not', 'only', 'same', 'so', 'than', 'too', 'very', 'just', 'also',
+  ]);
+
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '')
+    .split(/\s+/)
+    .filter(word => word.length > 2 && !stopWords.has(word));
+}
+
+/**
+ * Calculate similarity between two strings (Levenshtein distance based)
+ * @param {string} str1 - First string
+ * @param {string} str2 - Second string
+ * @returns {number} - Similarity score (0-1)
+ */
+export function similarity(str1, str2) {
+  if (!str1 || !str2) return 0;
+  
+  str1 = str1.toLowerCase();
+  str2 = str2.toLowerCase();
+  
+  if (str1 === str2) return 1;
+  
+  const maxLength = Math.max(str1.length, str2.length);
+  if (maxLength === 0) return 1;
+  
+  const distance = levenshteinDistance(str1, str2);
+  return 1 - (distance / maxLength);
+}
+
+/**
+ * Levenshtein distance between two strings
+ * @param {string} str1 - First string
+ * @param {string} str2 - Second string
+ * @returns {number} - Edit distance
+ */
+function levenshteinDistance(str1, str2) {
+  const m = str1.length;
+  const n = str2.length;
+  
+  const dp = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+  
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (str1[i - 1] === str2[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = Math.min(
+          dp[i - 1][j] + 1,     // deletion
+          dp[i][j - 1] + 1,     // insertion
+          dp[i - 1][j - 1] + 1  // substitution
+        );
+      }
+    }
+  }
+  
+  return dp[m][n];
+}
+
+/**
+ * Check if string contains all keywords
+ * @param {string} str - String to search
+ * @param {string[]} keywords - Keywords to find
+ * @returns {boolean}
+ */
+export function containsAllKeywords(str, keywords) {
+  const lowerStr = str.toLowerCase();
+  return keywords.every(keyword => lowerStr.includes(keyword.toLowerCase()));
+}
+
+/**
+ * Pluralize a word
+ * @param {string} word - Word to pluralize
+ * @param {number} count - Count
+ * @returns {string}
+ */
+export function pluralize(word, count) {
+  if (count === 1) return word;
+  
+  // Simple rules
+  if (word.endsWith('y')) {
+    return word.slice(0, -1) + 'ies';
+  }
+  if (word.endsWith('s') || word.endsWith('x') || word.endsWith('ch') || word.endsWith('sh')) {
+    return word + 'es';
+  }
+  return word + 's';
+}
+
+/**
+ * Generate a unique ID
+ * @param {string} [prefix=''] - Prefix for the ID
+ * @returns {string}
+ */
+export function generateId(prefix = '') {
+  const random = Math.random().toString(36).substring(2, 9);
+  const timestamp = Date.now().toString(36);
+  return prefix ? `${prefix}_${random}${timestamp}` : `${random}${timestamp}`;
+}