Skip to content

SmythOS Studio: Open-Source Visual AI Agent Builder and deployable runtime stack from SmythOS. Start with an intuitive drag-and-drop workspace, extend with custom code, and deploy your agents anywhere — local, cloud, or edge — with full governance and control.

11.3 KB
Raw Blame
/**
 * Lightweight tooltip wrapper using TooltipV2 class
 * This is a performance-optimized replacement for attachRadixTooltip
 *
 * Performance benefits:
 * - No React root creation (saves ~15-20ms per tooltip)
 * - No DOMPurify overhead (unless HTML is detected)
 * - No DOM wrapper manipulation
 * - Pure CSS-based rendering (GPU-accelerated)
 * - Minimal memory footprint (~0.5KB vs ~10-15KB)
 */

import {
  TooltipV2,
  type TooltipPosition,
} from '@src/react/shared/components/_legacy/ui/tooltip/tooltipV2';
import DOMPurify from 'dompurify';

/**
 * Configuration options for attaching a tooltip to a DOM element
 * Matches the API of attachRadixTooltip for easy migration
 */
export interface AttachTooltipConfig {
  /**
   * Tooltip text content (supports HTML, will be sanitized if HTML detected)
   */
  text: string;
  /**
   * Tooltip position relative to element
   * @default 'top'
   */
  position?: TooltipPosition;
  /**
   * Additional CSS classes for tooltip content
   * Note: This maps to tooltipClass in TooltipV2
   */
  className?: string;
  /**
   * Delay before showing tooltip (ms)
   * Note: TooltipV2 doesn't support delay, but CSS handles hover transitions
   * @default 300
   */
  delayDuration?: number;
  /**
   * Skip delay duration (ms)
   * Note: Not applicable to CSS-based tooltips
   * @default 100
   */
  skipDelayDuration?: number;
  /**
   * Whether to sanitize HTML content using DOMPurify
   * Only applies when using attachTooltipV2WithHTML with HTML content
   * @default true
   */
  sanitizeHTML?: boolean;
  /**
   * Maximum width for the tooltip (in pixels)
   * @default 400
   */
  maxWidth?: number;
}

/**
 * Maps position to TooltipV2 position
 * TooltipV2 supports 12 positions, so we can use all of them
 */
function mapPositionToTooltipV2(position?: TooltipPosition): TooltipPosition {
  return position ?? 'top';
}

/**
 * Attaches a lightweight tooltip to an existing vanilla DOM element
 * This is a drop-in replacement for attachRadixTooltip with better performance
 *
 * @param element - The DOM element to attach the tooltip to
 * @param config - Tooltip configuration options
 * @returns Cleanup function to remove the tooltip
 *
 * @example
 * ```typescript
 * const button = document.createElement('button');
 * button.textContent = 'Hover me';
 * const cleanup = attachTooltipV2(button, {
 *   text: 'This is a tooltip',
 *   position: 'top'
 * });
 * // Later, call cleanup() to remove the tooltip
 * ```
 */
export function attachTooltipV2(element: HTMLElement, config: AttachTooltipConfig): () => void {
  // Validate element
  if (!element) {
    console.warn('attachTooltipV2: Element is required');
    return () => {};
  }

  // Check if text contains HTML tags
  const hasHTML = /<[a-z][\s\S]*>/i.test(config.text);

  // For HTML content, we need to handle it differently
  // CSS-based tooltips (via data attributes) only support plain text
  // Option 1: Strip HTML tags (simple approach) - current implementation
  // Option 2: Use a hidden element with innerHTML (more complex but preserves HTML)
  // For now, we'll strip HTML to match CSS-based tooltip limitations
  // If HTML support is needed, use attachTooltipV2WithHTML or keep using attachRadixTooltip
  const tooltipText = hasHTML
    ? config.text.replace(/<[^>]*>/g, '').trim() // Strip HTML tags
    : config.text;

  // Create TooltipV2 instance
  const tooltip = new TooltipV2(element, {
    text: tooltipText,
    position: mapPositionToTooltipV2(config.position),
    showWhen: 'hover', // Default to hover (matches Radix behavior)
    tooltipClass: config.className,
  });

  // Return cleanup function that matches attachRadixTooltip API
  return () => {
    tooltip.destroy();
  };
}

/**
 * Enhanced version that supports HTML content in tooltips
 * 
 * Creates an actual DOM element to render HTML, unlike the standard TooltipV2
 * which uses CSS pseudo-elements and can only display plain text.
 * 
 * Features:
 * - ✅ Full HTML support (links, formatting, images, etc.)
 * - ✅ Automatic HTML sanitization using DOMPurify (prevents XSS attacks)
 * - ✅ 12 positioning options (top, bottom, left, right + variants)
 * - ✅ Viewport boundary detection (keeps tooltip on screen)
 * - ✅ Responsive repositioning on scroll/resize
 * - ✅ Smooth animations matching TooltipV2 style
 * - ✅ Automatic cleanup on destruction
 * 
 * Performance considerations:
 * - Creates a real DOM element (small overhead vs CSS pseudo-elements)
 * - Auto-detects HTML; falls back to TooltipV2 for plain text (better performance)
 * - Event listeners are properly cleaned up to prevent memory leaks
 * 
 * @param element - The DOM element to attach the tooltip to
 * @param config - Tooltip configuration options
 * @returns Cleanup function to remove the tooltip and all event listeners
 * 
 * @example
 * ```typescript
 * const button = document.createElement('button');
 * button.textContent = 'Click me';
 * 
 * const cleanup = attachTooltipV2WithHTML(button, {
 *   text: '<strong>Important:</strong> <a href="#">Learn more</a>',
 *   position: 'top',
 *   maxWidth: 300,
 *   sanitizeHTML: true // Default, can be set to false if content is trusted
 * });
 * 
 * // Later, when the element is removed or tooltip is no longer needed:
 * cleanup();
 * ```
 */
export function attachTooltipV2WithHTML(
  element: HTMLElement,
  config: AttachTooltipConfig,
): () => void {
  // Validate element
  if (!element) {
    console.warn('attachTooltipV2WithHTML: Element is required');
    return () => {};
  }

  // Check if text contains HTML tags
  const hasHTML = /<[a-z][\s\S]*>/i.test(config.text);

  if (!hasHTML) {
    // No HTML, use simple version for better performance
    return attachTooltipV2(element, config);
  }

  // Sanitize HTML content by default to prevent XSS attacks
  const shouldSanitize = config.sanitizeHTML !== false; // Default to true
  const htmlContent = shouldSanitize ? DOMPurify.sanitize(config.text) : config.text;

  // Create the tooltip DOM element
  const tooltipElement = document.createElement('div');
  tooltipElement.className = `tooltip-html-element ${config.className ?? ''}`;
  tooltipElement.innerHTML = htmlContent;
  
  // Only set custom max-width if provided (otherwise use CSS default of 400px)
  const maxWidth = config.maxWidth;
  if (maxWidth !== undefined) {
    tooltipElement.style.maxWidth = `${maxWidth}px`;
  }

  // Append tooltip to body
  document.body.appendChild(tooltipElement);

  // Position calculation function
  const positionTooltip = () => {
    const rect = element.getBoundingClientRect();
    const tooltipRect = tooltipElement.getBoundingClientRect();
    const position = config.position ?? 'top';
    const gap = 8; // Space between element and tooltip

    let top = 0;
    let left = 0;

    switch (position) {
      case 'top':
        top = rect.top - tooltipRect.height - gap;
        left = rect.left + (rect.width - tooltipRect.width) / 2;
        break;
      case 'bottom':
        top = rect.bottom + gap;
        left = rect.left + (rect.width - tooltipRect.width) / 2;
        break;
      case 'left':
        top = rect.top + (rect.height - tooltipRect.height) / 2;
        left = rect.left - tooltipRect.width - gap;
        break;
      case 'right':
        top = rect.top + (rect.height - tooltipRect.height) / 2;
        left = rect.right + gap;
        break;
      case 'top-left':
        top = rect.top - tooltipRect.height - gap;
        left = rect.left;
        break;
      case 'top-right':
        top = rect.top - tooltipRect.height - gap;
        left = rect.right - tooltipRect.width;
        break;
      case 'bottom-left':
        top = rect.bottom + gap;
        left = rect.left;
        break;
      case 'bottom-right':
        top = rect.bottom + gap;
        left = rect.right - tooltipRect.width;
        break;
      case 'left-top':
        top = rect.top;
        left = rect.left - tooltipRect.width - gap;
        break;
      case 'left-bottom':
        top = rect.bottom - tooltipRect.height;
        left = rect.left - tooltipRect.width - gap;
        break;
      case 'right-top':
        top = rect.top;
        left = rect.right + gap;
        break;
      case 'right-bottom':
        top = rect.bottom - tooltipRect.height;
        left = rect.right + gap;
        break;
    }

    // Keep tooltip within viewport bounds
    const viewportWidth = window.innerWidth;
    const viewportHeight = window.innerHeight;
    const scrollX = window.scrollX || window.pageXOffset;
    const scrollY = window.scrollY || window.pageYOffset;

    // Adjust horizontal position if tooltip goes off-screen
    if (left < scrollX) {
      left = scrollX + gap;
    } else if (left + tooltipRect.width > scrollX + viewportWidth) {
      left = scrollX + viewportWidth - tooltipRect.width - gap;
    }

    // Adjust vertical position if tooltip goes off-screen
    if (top < scrollY) {
      top = scrollY + gap;
    } else if (top + tooltipRect.height > scrollY + viewportHeight) {
      top = scrollY + viewportHeight - tooltipRect.height - gap;
    }

    tooltipElement.style.top = `${top}px`;
    tooltipElement.style.left = `${left}px`;
  };

  // Show tooltip handler
  const showTooltip = () => {
    positionTooltip();
    tooltipElement.classList.add('tooltip-html-visible');
  };

  // Hide tooltip handler
  const hideTooltip = () => {
    tooltipElement.classList.remove('tooltip-html-visible');
  };

  // Reposition on scroll or resize
  const updatePosition = () => {
    if (tooltipElement.classList.contains('tooltip-html-visible')) {
      positionTooltip();
    }
  };

  // Add event listeners
  element.addEventListener('mouseenter', showTooltip);
  element.addEventListener('mouseleave', hideTooltip);
  window.addEventListener('scroll', updatePosition, true);
  window.addEventListener('resize', updatePosition);

  // Mark element as having a tooltip for debugging
  element.setAttribute('data-has-html-tooltip', 'true');

  // Cleanup function
  return () => {
    element.removeEventListener('mouseenter', showTooltip);
    element.removeEventListener('mouseleave', hideTooltip);
    window.removeEventListener('scroll', updatePosition, true);
    window.removeEventListener('resize', updatePosition);
    element.removeAttribute('data-has-html-tooltip');
    
    if (tooltipElement.parentNode) {
      tooltipElement.remove();
    }
  };
}

/**
 * Maps Metro UI hint position to TooltipV2 position
 *
 * @param metroPosition - Metro UI hint position
 * @returns TooltipV2 position
 */
export function mapMetroPositionToTooltipV2(metroPosition?: string): TooltipPosition {
  const position = metroPosition?.toLowerCase();

  if (position === 'right') return 'right';
  if (position === 'bottom') return 'bottom';
  if (position === 'left') return 'left';
  if (position === 'top-left') return 'top-left';
  if (position === 'top-right') return 'top-right';
  if (position === 'bottom-left') return 'bottom-left';
  if (position === 'bottom-right') return 'bottom-right';

  // Default to 'top' for 'top' or any other value
  return 'top';
}

/**
 * Maps Metro UI hint classes to TooltipV2 classes
 *
 * @param metroClasses - Metro UI hint classes (e.g., 'bg-gray-50 shadow-lg')
 * @returns TooltipV2 compatible classes
 */
export function mapMetroClassesToTooltipV2(metroClasses?: string): string {
  if (!metroClasses) {
    return '';
  }

  // Metro UI classes are typically Tailwind-compatible
  // Return as-is for tooltipClass
  return metroClasses;
}