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.
JavaScript a2aagentic-aiai-agentsdevtoolsmcp-clientn8n-alternativeno-codeopen-sourceorchestrationsmythosvisual-builder
/**
* 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;
}