@wishbone-media/spark 0.35.0 → 0.37.0

package/src/directives/sparkTooltip.js

@@ -0,0 +1,228 @@
+import { computePosition, offset, flip, shift, arrow } from '@floating-ui/vue'
+
+/**
+ * v-spark-tooltip directive for adding tooltips to any element.
+ *
+ * Usage:
+ *   v-spark-tooltip="'Simple text'"
+ *   v-spark-tooltip="{ content: 'HTML <b>bold</b>', html: true }"
+ *   v-spark-tooltip="{ content: 'Tip', placement: 'bottom', offset: 12, delay: { show: 500, hide: 100 } }"
+ *
+ * Empty/falsy content = no tooltip.
+ */
+
+const TOOLTIP_CLASS = 'spark-tooltip'
+const ARROW_CLASS = 'spark-tooltip-arrow'
+
+function normalizeConfig(value) {
+  if (!value) return { content: '' }
+  if (typeof value === 'string') return { content: value }
+  return {
+    content: '',
+    placement: 'top',
+    offset: 8,
+    html: false,
+    delay: { show: 200, hide: 0 },
+    arrow: true,
+    ...value,
+  }
+}
+
+function createTooltipElement(config) {
+  const tooltip = document.createElement('div')
+  tooltip.className = TOOLTIP_CLASS
+  tooltip.setAttribute('role', 'tooltip')
+
+  if (config.html) {
+    tooltip.innerHTML = config.content
+  } else {
+    tooltip.textContent = config.content
+  }
+
+  if (config.arrow) {
+    const arrowEl = document.createElement('div')
+    arrowEl.className = ARROW_CLASS
+    tooltip.appendChild(arrowEl)
+  }
+
+  return tooltip
+}
+
+async function updatePosition(el, tooltip, config) {
+  const arrowEl = tooltip.querySelector(`.${ARROW_CLASS}`)
+
+  const middleware = [
+    offset(config.offset ?? 8),
+    flip(),
+    shift({ padding: 8 }),
+  ]
+
+  if (arrowEl) {
+    middleware.push(arrow({ element: arrowEl, padding: 5 }))
+  }
+
+  const { x, y, placement, middlewareData } = await computePosition(el, tooltip, {
+    placement: config.placement || 'top',
+    strategy: 'fixed',
+    middleware,
+  })
+
+  Object.assign(tooltip.style, {
+    left: `${x}px`,
+    top: `${y}px`,
+  })
+
+  // Position the arrow
+  if (arrowEl && middlewareData.arrow) {
+    const { x: arrowX, y: arrowY } = middlewareData.arrow
+    const side = placement.split('-')[0]
+    const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side]
+
+    Object.assign(arrowEl.style, {
+      left: arrowX != null ? `${arrowX}px` : '',
+      top: arrowY != null ? `${arrowY}px` : '',
+      right: '',
+      bottom: '',
+      [staticSide]: '-4px',
+    })
+  }
+}
+
+function showTooltip(el) {
+  const state = el.__sparkTooltip
+  if (!state || !state.config.content) return
+
+  clearTimeout(state.hideTimeout)
+
+  const delay = typeof state.config.delay === 'number'
+    ? state.config.delay
+    : state.config.delay?.show ?? 200
+
+  state.showTimeout = setTimeout(() => {
+    if (state.tooltipEl) return // Already visible
+
+    const tooltip = createTooltipElement(state.config)
+    tooltip.style.position = 'fixed'
+    tooltip.style.top = '0'
+    tooltip.style.left = '0'
+    document.body.appendChild(tooltip)
+    state.tooltipEl = tooltip
+
+    updatePosition(el, tooltip, state.config)
+  }, delay)
+}
+
+function hideTooltip(el) {
+  const state = el.__sparkTooltip
+  if (!state) return
+
+  clearTimeout(state.showTimeout)
+
+  const delay = typeof state.config.delay === 'number'
+    ? 0
+    : state.config.delay?.hide ?? 0
+
+  state.hideTimeout = setTimeout(() => {
+    if (state.tooltipEl) {
+      state.tooltipEl.remove()
+      state.tooltipEl = null
+    }
+  }, delay)
+}
+
+function setupListeners(el) {
+  const onShow = () => showTooltip(el)
+  const onHide = () => hideTooltip(el)
+
+  el.addEventListener('mouseenter', onShow)
+  el.addEventListener('mouseleave', onHide)
+  el.addEventListener('focus', onShow)
+  el.addEventListener('blur', onHide)
+
+  el.__sparkTooltip.listeners = { onShow, onHide }
+}
+
+function removeListeners(el) {
+  const state = el.__sparkTooltip
+  if (!state?.listeners) return
+
+  el.removeEventListener('mouseenter', state.listeners.onShow)
+  el.removeEventListener('mouseleave', state.listeners.onHide)
+  el.removeEventListener('focus', state.listeners.onShow)
+  el.removeEventListener('blur', state.listeners.onHide)
+}
+
+function cleanup(el) {
+  const state = el.__sparkTooltip
+  if (!state) return
+
+  clearTimeout(state.showTimeout)
+  clearTimeout(state.hideTimeout)
+  removeListeners(el)
+
+  if (state.tooltipEl) {
+    state.tooltipEl.remove()
+    state.tooltipEl = null
+  }
+
+  delete el.__sparkTooltip
+}
+
+export const sparkTooltipDirective = {
+  mounted(el, binding) {
+    const config = normalizeConfig(binding.value)
+    el.__sparkTooltip = { config, tooltipEl: null, showTimeout: null, hideTimeout: null }
+
+    if (config.content) {
+      setupListeners(el)
+    }
+  },
+
+  updated(el, binding) {
+    const config = normalizeConfig(binding.value)
+    const state = el.__sparkTooltip
+
+    if (!state) {
+      // Was never initialized (content was empty on mount)
+      el.__sparkTooltip = { config, tooltipEl: null, showTimeout: null, hideTimeout: null }
+      if (config.content) setupListeners(el)
+      return
+    }
+
+    state.config = config
+
+    // Update visible tooltip content
+    if (state.tooltipEl) {
+      const arrowEl = state.tooltipEl.querySelector(`.${ARROW_CLASS}`)
+      if (config.html) {
+        state.tooltipEl.innerHTML = config.content
+      } else {
+        state.tooltipEl.textContent = config.content
+      }
+      // Re-append arrow if it was removed by innerHTML/textContent
+      if (config.arrow) {
+        if (arrowEl) {
+          state.tooltipEl.appendChild(arrowEl)
+        } else {
+          const newArrow = document.createElement('div')
+          newArrow.className = ARROW_CLASS
+          state.tooltipEl.appendChild(newArrow)
+        }
+      }
+      updatePosition(el, state.tooltipEl, config)
+    }
+
+    // Add/remove listeners if content became available/empty
+    if (config.content && !state.listeners) {
+      setupListeners(el)
+    } else if (!config.content && state.listeners) {
+      hideTooltip(el)
+      removeListeners(el)
+      state.listeners = null
+    }
+  },
+
+  unmounted(el) {
+    cleanup(el)
+  },
+}

package/src/plugins/fontawesome.js

@@ -1,5 +1,6 @@
 import { library, icon as faIconToSvg } from '@fortawesome/fontawesome-svg-core'
 import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
+import { setupTooltip } from './tooltip.js'
 
 import {
   faArrowLeftToLine,
@@ -58,6 +59,8 @@ import {
   faAnglesRight,
   faAnglesLeft,
   faEyeDropper,
+  faCopy,
+  faArrowUpRightFromSquare,
 } from '@fortawesome/pro-regular-svg-icons'
 
 import {
@@ -128,6 +131,8 @@ export const Icons = {
   farAnglesLeft: faAnglesLeft,
   farEyeDropper: faEyeDropper,
   farCircleDot: faCircleDot,
+  farCopy: faCopy,
+  farArrowUpRightFromSquare: faArrowUpRightFromSquare,
 }
 
 /**
@@ -200,4 +205,7 @@ export function addIcons(newIcons) {
 export function setupFontAwesome(app) {
   library.add(...Object.values(Icons))
   app.component('FontAwesomeIcon', FontAwesomeIcon)
+
+  // Auto-register tooltip directive (used by SparkEntityBadge and available to all consumers)
+  setupTooltip(app)
 }

package/src/plugins/index.js

@@ -1,4 +1,5 @@
 export { Icons, addIcons, setupFontAwesome, formKitIcons, formKitIconLoader, formKitGenesisOverride } from './fontawesome.js'
 export { createAuthRoutes, setupAuthGuards, create403Route, create404Route, setupBootstrapGuard, setupDirtyFormGuard } from './router.js'
 export { createAxiosInstance, setupAxios, getAxiosInstance } from './axios.js'
-export { createBootstrapService } from './app-bootstrap.js'
+export { createBootstrapService } from './app-bootstrap.js'
+export { setupTooltip } from './tooltip.js'

package/src/plugins/tooltip.js

@@ -0,0 +1,11 @@
+import { sparkTooltipDirective } from '../directives/sparkTooltip.js'
+
+/**
+ * Register the v-spark-tooltip directive globally.
+ * Call in your app's main.js: setupTooltip(app)
+ *
+ * @param {import('vue').App} app - Vue app instance
+ */
+export function setupTooltip(app) {
+  app.directive('spark-tooltip', sparkTooltipDirective)
+}