@vanduo-oss/framework 1.2.3

package/js/components/tooltips.js

@@ -0,0 +1,306 @@
+/**
+ * Vanduo Framework - Tooltips Component
+ * JavaScript functionality for tooltips
+ */
+
+(function () {
+  'use strict';
+
+  /**
+   * Tooltips Component
+   */
+  const Tooltips = {
+    tooltips: new Map(),
+    delayTimers: new Map(),
+
+    /**
+     * Sanitize HTML — delegates to shared sanitizeHtml from helpers.js
+     * @param {string} input
+     * @returns {string} sanitized HTML
+     */
+    sanitizeHtml: function (input) {
+      if (typeof sanitizeHtml === 'function') {
+        return sanitizeHtml(input);
+      }
+      // Fallback: strip all HTML
+      const div = document.createElement('div');
+      div.textContent = input || '';
+      return div.innerHTML;
+    },
+
+    /**
+     * Initialize tooltips
+     */
+    init: function () {
+      const elements = document.querySelectorAll('[data-tooltip], [data-tooltip-html]');
+
+      elements.forEach(element => {
+        if (this.tooltips.has(element)) {
+          return;
+        }
+        this.initTooltip(element);
+      });
+    },
+
+    /**
+     * Initialize a single tooltip
+     * @param {HTMLElement} element - Element with tooltip
+     */
+    initTooltip: function (element) {
+      const tooltip = this.createTooltip(element);
+      const cleanupFunctions = [];
+
+      // Show on hover/focus
+      const enterHandler = () => { this.showTooltip(element, tooltip); };
+      const leaveHandler = () => { this.hideTooltip(element, tooltip); };
+      const focusHandler = () => { this.showTooltip(element, tooltip); };
+      const blurHandler = () => { this.hideTooltip(element, tooltip); };
+
+      element.addEventListener('mouseenter', enterHandler);
+      element.addEventListener('mouseleave', leaveHandler);
+      element.addEventListener('focus', focusHandler);
+      element.addEventListener('blur', blurHandler);
+
+      cleanupFunctions.push(
+        () => element.removeEventListener('mouseenter', enterHandler),
+        () => element.removeEventListener('mouseleave', leaveHandler),
+        () => element.removeEventListener('focus', focusHandler),
+        () => element.removeEventListener('blur', blurHandler)
+      );
+
+      this.tooltips.set(element, { tooltip, cleanup: cleanupFunctions });
+    },
+
+    /**
+     * Create tooltip element
+     * @param {HTMLElement} element - Target element
+     * @returns {HTMLElement} Tooltip element
+     */
+    createTooltip: function (element) {
+      const tooltip = document.createElement('div');
+      tooltip.className = 'vd-tooltip';
+      tooltip.setAttribute('role', 'tooltip');
+      tooltip.setAttribute('aria-hidden', 'true');
+
+      // Generate unique ID and link via aria-describedby
+      const tooltipId = 'tooltip-' + Math.random().toString(36).substr(2, 9);
+      tooltip.id = tooltipId;
+      element.setAttribute('aria-describedby', tooltipId);
+
+      // Get content
+      const htmlContent = element.dataset.tooltipHtml;
+      const textContent = element.dataset.tooltip;
+
+      if (htmlContent) {
+        tooltip.innerHTML = this.sanitizeHtml(htmlContent);
+        tooltip.classList.add('vd-tooltip-html');
+      } else if (textContent) {
+        tooltip.textContent = textContent;
+      }
+
+      // Get placement
+      const placement = element.dataset.tooltipPlacement || element.dataset.placement || 'top';
+      tooltip.setAttribute('data-placement', placement);
+      tooltip.classList.add(`vd-tooltip-${placement}`);
+
+      // Get variant
+      if (element.dataset.tooltipVariant) {
+        tooltip.classList.add(`vd-tooltip-${element.dataset.tooltipVariant}`);
+      }
+
+      // Get size
+      if (element.dataset.tooltipSize) {
+        tooltip.classList.add(`vd-tooltip-${element.dataset.tooltipSize}`);
+      }
+
+      // Get delay
+      const delay = parseInt(element.dataset.tooltipDelay) || 0;
+      tooltip.dataset.delay = delay;
+
+      document.body.appendChild(tooltip);
+
+      return tooltip;
+    },
+
+    /**
+     * Show tooltip
+     * @param {HTMLElement} element - Target element
+     * @param {HTMLElement} tooltip - Tooltip element
+     */
+    showTooltip: function (element, tooltip) {
+      const delay = parseInt(tooltip.dataset.delay) || 0;
+
+      if (delay > 0) {
+        const timer = setTimeout(() => {
+          this.positionTooltip(element, tooltip);
+          tooltip.classList.add('is-visible');
+          tooltip.setAttribute('aria-hidden', 'false');
+        }, delay);
+        this.delayTimers.set(element, timer);
+      } else {
+        this.positionTooltip(element, tooltip);
+        tooltip.classList.add('is-visible');
+        tooltip.setAttribute('aria-hidden', 'false');
+      }
+    },
+
+    /**
+     * Hide tooltip
+     * @param {HTMLElement} element - Target element
+     * @param {HTMLElement} tooltip - Tooltip element
+     */
+    hideTooltip: function (element, tooltip) {
+      // Clear delay timer if exists
+      const timer = this.delayTimers.get(element);
+      if (timer) {
+        clearTimeout(timer);
+        this.delayTimers.delete(element);
+      }
+
+      tooltip.classList.remove('is-visible');
+      tooltip.setAttribute('aria-hidden', 'true');
+    },
+
+    /**
+     * Position tooltip relative to element
+     * @param {HTMLElement} element - Target element
+     * @param {HTMLElement} tooltip - Tooltip element
+     */
+    positionTooltip: function (element, tooltip) {
+      const placement = tooltip.dataset.placement || 'top';
+      const rect = element.getBoundingClientRect();
+      const tooltipRect = tooltip.getBoundingClientRect();
+      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+      const scrollLeft = window.pageXOffset || document.documentElement.scrollLeft;
+
+      let top = 0;
+      let left = 0;
+
+      switch (placement) {
+        case 'top':
+          top = rect.top + scrollTop - tooltipRect.height - 8;
+          left = rect.left + scrollLeft + (rect.width / 2) - (tooltipRect.width / 2);
+          break;
+        case 'bottom':
+          top = rect.bottom + scrollTop + 8;
+          left = rect.left + scrollLeft + (rect.width / 2) - (tooltipRect.width / 2);
+          break;
+        case 'left':
+          top = rect.top + scrollTop + (rect.height / 2) - (tooltipRect.height / 2);
+          left = rect.left + scrollLeft - tooltipRect.width - 8;
+          break;
+        case 'right':
+          top = rect.top + scrollTop + (rect.height / 2) - (tooltipRect.height / 2);
+          left = rect.right + scrollLeft + 8;
+          break;
+      }
+
+      // Prevent overflow
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      const padding = 8;
+
+      if (left < padding) {
+        left = padding;
+      } else if (left + tooltipRect.width > viewportWidth - padding) {
+        left = viewportWidth - tooltipRect.width - padding;
+      }
+
+      if (top < scrollTop + padding) {
+        top = scrollTop + padding;
+      } else if (top + tooltipRect.height > scrollTop + viewportHeight - padding) {
+        top = scrollTop + viewportHeight - tooltipRect.height - padding;
+      }
+
+      // Use single style assignment with transform for better performance
+      tooltip.style.cssText = `position: absolute; top: 0; left: 0; transform: translate(${left}px, ${top}px);`;
+    },
+
+    /**
+     * Show tooltip programmatically
+     * @param {HTMLElement|string} element - Target element or selector
+     */
+    show: function (element) {
+      const el = typeof element === 'string' ? document.querySelector(element) : element;
+      if (el && this.tooltips.has(el)) {
+        const { tooltip } = this.tooltips.get(el);
+        this.showTooltip(el, tooltip);
+      }
+    },
+
+    /**
+     * Hide tooltip programmatically
+     * @param {HTMLElement|string} element - Target element or selector
+     */
+    hide: function (element) {
+      const el = typeof element === 'string' ? document.querySelector(element) : element;
+      if (el && this.tooltips.has(el)) {
+        const { tooltip } = this.tooltips.get(el);
+        this.hideTooltip(el, tooltip);
+      }
+    },
+
+    /**
+     * Update tooltip content
+     * @param {HTMLElement|string} element - Target element or selector
+     * @param {string} content - New content
+     * @param {boolean} isHtml - Whether content is HTML
+     */
+    update: function (element, content, isHtml = false) {
+      const el = typeof element === 'string' ? document.querySelector(element) : element;
+      if (el && this.tooltips.has(el)) {
+        const { tooltip } = this.tooltips.get(el);
+        if (isHtml) {
+          tooltip.innerHTML = this.sanitizeHtml(content);
+          tooltip.classList.add('vd-tooltip-html');
+        } else {
+          tooltip.textContent = content;
+          tooltip.classList.remove('vd-tooltip-html');
+        }
+      }
+    },
+
+    /**
+     * Destroy a tooltip instance and clean up
+     * @param {HTMLElement} element - Element with tooltip
+     */
+    destroy: function (element) {
+      const data = this.tooltips.get(element);
+      if (!data) return;
+
+      // Clear any pending timer
+      const timer = this.delayTimers.get(element);
+      if (timer) {
+        clearTimeout(timer);
+        this.delayTimers.delete(element);
+      }
+
+      data.cleanup.forEach(fn => fn());
+
+      // Remove tooltip element from DOM
+      if (data.tooltip && data.tooltip.parentNode) {
+        data.tooltip.parentNode.removeChild(data.tooltip);
+      }
+
+      this.tooltips.delete(element);
+    },
+
+    /**
+     * Destroy all tooltip instances
+     */
+    destroyAll: function () {
+      this.tooltips.forEach((data, element) => {
+        this.destroy(element);
+      });
+    }
+  };
+
+  // Register with Vanduo framework if available
+  if (typeof window.Vanduo !== 'undefined') {
+    window.Vanduo.register('tooltips', Tooltips);
+  }
+
+  // Expose globally
+  window.VanduoTooltips = Tooltips;
+
+})();

package/js/index.js

@@ -0,0 +1,53 @@
+/**
+ * Vanduo Framework - Bundle Entry Point
+ * This file imports all framework components for bundling.
+ *
+ * All component files are side-effect modules that:
+ *   1. Define their component object
+ *   2. Register with window.Vanduo via Vanduo.register()
+ *   3. Expose a convenience global (e.g. window.VanduoTooltips)
+ *
+ * The IIFE build uses `globalName: 'VanduoBundle'` so that esbuild's
+ * wrapper variable does NOT shadow the real `window.Vanduo` that the
+ * side-effect scripts create. After the bundle executes, `window.Vanduo`
+ * is the fully-populated framework object.
+ *
+ * For ESM/CJS consumers we re-export `window.Vanduo` as the default
+ * and named export so `import { Vanduo }` and `const { Vanduo } = require()`
+ * both work.
+ */
+
+// Utilities (must load first — helpers defines `ready()`, `safeStorageGet()` etc.)
+import './utils/helpers.js';
+import './utils/lifecycle.js';
+
+// Core framework object (creates window.Vanduo)
+import './vanduo.js';
+
+// Components (each registers itself with window.Vanduo)
+import './components/code-snippet.js';
+import './components/collapsible.js';
+import './components/dropdown.js';
+import './components/font-switcher.js';
+import './components/grid.js';
+import './components/image-box.js';
+import './components/modals.js';
+import './components/navbar.js';
+import './components/pagination.js';
+import './components/parallax.js';
+import './components/preloader.js';
+import './components/select.js';
+import './components/sidenav.js';
+import './components/tabs.js';
+import './components/theme-customizer.js';
+import './components/theme-switcher.js';
+import './components/toast.js';
+import './components/tooltips.js';
+import './components/doc-search.js';
+import './components/draggable.js';
+import './components/lazy-load.js';
+
+// Re-export for ESM / CJS consumers
+const Vanduo = window.Vanduo;
+export { Vanduo };
+export default Vanduo;

package/js/utils/helpers.js

@@ -0,0 +1,318 @@
+'use strict';
+
+/**
+ * Vanduo Framework - Utility Helpers
+ * Common utility functions used across the framework
+ */
+
+/**
+ * Check if element exists
+ * @param {string|HTMLElement} selector - CSS selector or element
+ * @returns {HTMLElement|null}
+ */
+function $(selector) {
+  if (typeof selector === 'string') {
+    return document.querySelector(selector);
+  }
+  return selector;
+}
+
+/**
+ * Get all elements matching selector
+ * @param {string} selector - CSS selector
+ * @returns {NodeList}
+ */
+function $$(selector) {
+  return document.querySelectorAll(selector);
+}
+
+/**
+ * Wait for DOM to be ready
+ * @param {Function} callback - Function to execute when DOM is ready
+ */
+function ready(callback) {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', callback);
+  } else {
+    callback();
+  }
+}
+
+/**
+ * Safely get a value from localStorage
+ * @param {string} key - Storage key
+ * @param {string|null} fallback - Fallback when storage is unavailable
+ * @returns {string|null}
+ */
+function safeStorageGet(key, fallback = null) {
+  try {
+    const value = localStorage.getItem(key);
+    return value !== null ? value : fallback;
+  } catch (_e) {
+    return fallback;
+  }
+}
+
+/**
+ * Safely set a value in localStorage
+ * @param {string} key - Storage key
+ * @param {string} value - Value to store
+ * @returns {boolean}
+ */
+function safeStorageSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Add event listener with delegation support
+ * @param {string|HTMLElement} target - Target element or selector
+ * @param {string} event - Event type
+ * @param {string|Function} handlerOrSelector - Event handler or selector for delegation
+ * @param {Function} handler - Event handler (if using delegation)
+ */
+function on(target, event, handlerOrSelector, handler) {
+  const element = typeof target === 'string' ? $(target) : target;
+
+  if (!element) return;
+
+  if (typeof handlerOrSelector === 'function') {
+    // Direct event binding
+    element.addEventListener(event, handlerOrSelector);
+  } else {
+    // Event delegation
+    element.addEventListener(event, function (e) {
+      const delegateTarget = e.target.closest(handlerOrSelector);
+      if (delegateTarget && element.contains(delegateTarget)) {
+        try {
+          handler.call(delegateTarget, e);
+        } catch (error) {
+          console.warn('[Vanduo Helpers] Delegated handler error:', error);
+        }
+      }
+    });
+  }
+}
+
+/**
+ * Remove event listener
+ * @param {string|HTMLElement} target - Target element or selector
+ * @param {string} event - Event type
+ * @param {Function} handler - Event handler
+ */
+function off(target, event, handler) {
+  const element = typeof target === 'string' ? $(target) : target;
+  if (element) {
+    element.removeEventListener(event, handler);
+  }
+}
+
+/**
+ * Toggle class on element
+ * @param {string|HTMLElement} selector - CSS selector or element
+ * @param {string} className - Class name to toggle
+ */
+function toggleClass(selector, className) {
+  const element = typeof selector === 'string' ? $(selector) : selector;
+  if (element) {
+    element.classList.toggle(className);
+  }
+}
+
+/**
+ * Add class to element
+ * @param {string|HTMLElement} selector - CSS selector or element
+ * @param {string} className - Class name to add
+ */
+function addClass(selector, className) {
+  const element = typeof selector === 'string' ? $(selector) : selector;
+  if (element) {
+    element.classList.add(className);
+  }
+}
+
+/**
+ * Remove class from element
+ * @param {string|HTMLElement} selector - CSS selector or element
+ * @param {string} className - Class name to remove
+ */
+function removeClass(selector, className) {
+  const element = typeof selector === 'string' ? $(selector) : selector;
+  if (element) {
+    element.classList.remove(className);
+  }
+}
+
+/**
+ * Check if element has class
+ * @param {string|HTMLElement} selector - CSS selector or element
+ * @param {string} className - Class name to check
+ * @returns {boolean}
+ */
+function hasClass(selector, className) {
+  const element = typeof selector === 'string' ? $(selector) : selector;
+  return element ? element.classList.contains(className) : false;
+}
+
+/**
+ * Get or set data attribute
+ * @param {HTMLElement} element - Element
+ * @param {string} name - Data attribute name (without data- prefix)
+ * @param {string} value - Value to set (optional)
+ * @returns {string|undefined}
+ */
+function data(element, name, value) {
+  if (value !== undefined) {
+    element.setAttribute(`data-${name}`, value);
+    return value;
+  }
+  return element.getAttribute(`data-${name}`);
+}
+
+/**
+ * Debounce function
+ * @param {Function} func - Function to debounce
+ * @param {number} wait - Wait time in milliseconds
+ * @returns {Function}
+ */
+function debounce(func, wait) {
+  let timeout;
+  return function executedFunction(...args) {
+    const later = () => {
+      clearTimeout(timeout);
+      func(...args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  };
+}
+
+/**
+ * Throttle function
+ * @param {Function} func - Function to throttle
+ * @param {number} limit - Time limit in milliseconds
+ * @returns {Function}
+ */
+function throttle(func, limit) {
+  let inThrottle;
+  return function (...args) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limit);
+    }
+  };
+}
+
+/**
+ * Check if element is visible
+ * @param {HTMLElement} element - Element to check
+ * @returns {boolean}
+ */
+function isVisible(element) {
+  if (!element) return false;
+  const style = window.getComputedStyle(element);
+  return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+}
+
+/**
+ * Get element position relative to viewport
+ * @param {HTMLElement} element - Element
+ * @returns {Object} - Object with top, left, right, bottom, width, height
+ */
+function getPosition(element) {
+  if (!element) return null;
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top,
+    left: rect.left,
+    right: rect.right,
+    bottom: rect.bottom,
+    width: rect.width,
+    height: rect.height
+  };
+}
+
+/**
+ * Escape HTML special characters to prevent injection
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for insertion into HTML
+ */
+function escapeHtml(str) {
+  if (!str) return '';
+  const div = document.createElement('div');
+  div.appendChild(document.createTextNode(str));
+  return div.innerHTML;
+}
+
+/**
+ * Basic HTML sanitizer (whitelist-based) — runs in the browser without external libs.
+ * Keeps a small set of tags and strips disallowed tags and attributes. Safe for
+ * simple rich text (use server-side or DOMPurify for stronger guarantees).
+ * @param {string} input
+ * @returns {string} sanitized HTML
+ */
+function sanitizeHtml(input) {
+  if (!input) return '';
+  let doc;
+  try {
+    doc = new DOMParser().parseFromString(input, 'text/html');
+  } catch (_error) {
+    // Fail closed to plain escaped text if parser is unavailable/fails.
+    return escapeHtml(input);
+  }
+  const allowed = ['B', 'STRONG', 'I', 'EM', 'BR', 'A', 'SPAN', 'U', 'SVG', 'PATH', 'LINE', 'CIRCLE', 'POLYLINE', 'RECT', 'G'];
+
+  const sanitizeNode = function (node) {
+    const children = Array.from(node.childNodes);
+    children.forEach(function (child) {
+      if (child.nodeType === Node.TEXT_NODE) return;
+
+      if (!allowed.includes(child.nodeName)) {
+        const text = document.createTextNode(child.textContent);
+        node.replaceChild(text, child);
+        return;
+      }
+
+      if (child.nodeName === 'A') {
+        const href = child.getAttribute('href') || '';
+        try {
+          const url = new URL(href, location.href);
+          if (!['http:', 'https:', 'mailto:'].includes(url.protocol)) {
+            child.removeAttribute('href');
+          }
+        } catch (_e) {
+          child.removeAttribute('href');
+        }
+        child.removeAttribute('target');
+        child.removeAttribute('rel');
+      } else if (child.nodeName === 'SVG' || child.closest && child.closest('svg')) {
+        // Allow safe SVG presentation attributes only
+        const safeSvgAttrs = ['xmlns', 'width', 'height', 'viewBox', 'fill', 'stroke', 'stroke-width',
+          'stroke-linecap', 'stroke-linejoin', 'd', 'cx', 'cy', 'r', 'x1', 'y1', 'x2', 'y2', 'points',
+          'transform', 'class'];
+        const attrs = Array.from(child.attributes || []);
+        attrs.forEach(function (a) {
+          if (!safeSvgAttrs.includes(a.name)) {
+            child.removeAttribute(a.name);
+          }
+        });
+      } else {
+        const otherAttrs = Array.from(child.attributes || []);
+        otherAttrs.forEach(function (a) { child.removeAttribute(a.name); });
+      }
+
+      sanitizeNode(child);
+    });
+  };
+
+  sanitizeNode(doc.body);
+  return doc.body.innerHTML;
+}
+
+
+