feat(vueltip): allow for custom data to be passed to the tooltip

Author: vinpogo

demo/src/App.vue

@@ -158,6 +158,15 @@ debug('foobar', { count })
           >
             Hover over me (right)
           </p>
+          <p
+            v-tooltip="{
+              text: 'Custom data: ',
+              custom: { sum: 23 },
+            }"
+            class="rounded-xl border border-slate-700 bg-slate-900/70 px-4 py-3 text-sm text-slate-200 shadow-sm transition hover:border-slate-500"
+          >
+            Hover over me (custom data)
+          </p>
         </div>
         <div class="mt-6 space-y-3">
           <div>

demo/src/Tooltip.vue

@@ -31,6 +31,9 @@ const { tooltipStyles, arrowStyles, show, content } =
       class="relative z-10 rounded bg-slate-100 px-2 py-1 text-sm font-semibold text-slate-900 shadow-lg"
     >
       {{ content?.text }}
+      <span v-if="content?.custom">
+        {{ content.custom }}</span
+      >
     </div>
   </div>
 </template>

demo/src/main.ts

@@ -20,3 +20,9 @@ app
   .directive('tooltip', vueltipDirective)
 
 app.mount('#app')
+
+declare module '@vingy/vueltip' {
+  export interface CustomVueltipData {
+    sum: number
+  }
+}

packages/vueltip/README.md

@@ -182,3 +182,62 @@ v-tooltip="{
   placement: 'right'  // Placement: 'top', 'bottom', 'left', 'right', etc.
 }"
 ```
+
+## Custom Data
+
+You can extend the tooltip content with custom typed data for use in your tooltip component:
+
+**1. Create a type declaration file (e.g., `vueltip.d.ts`):**
+
+```ts
+declare module '@vingy/vueltip' {
+  interface CustomVueltipData {
+    userId?: number
+    userName?: string
+    severity?: 'info' | 'warning' | 'error'
+    metadata?: Record<string, unknown>
+  }
+}
+```
+
+**2. Use custom data in your directive:**
+
+```vue
+<button
+  v-tooltip="{
+    text: 'User profile',
+    custom: {
+      userId: 123,
+      userName: 'John Doe',
+      severity: 'info',
+    },
+  }"
+>
+  View Profile
+</button>
+```
+
+**3. Access custom data in your Tooltip component:**
+
+```vue
+<script setup>
+import { useVueltip } from '@vingy/vueltip'
+
+const { content, show } = useVueltip({
+  /* ... */
+})
+</script>
+
+<template>
+  <div v-if="show">
+    {{ content?.text }}
+
+    <!-- Access your custom data -->
+    <span v-if="content?.custom?.userId">
+      User ID: {{ content.custom.userId }}
+    </span>
+  </div>
+</template>
+```
+
+TypeScript will validate that your `custom` object matches the declared `CustomVueltipData` interface.

packages/vueltip/src/directive.ts

@@ -8,30 +8,29 @@ import {
   setContent,
 } from './state'
 import type {
-  Binding,
   Content,
   Modifier,
   TooltipDirective,
+  Value,
 } from './types.ts'
 import { ensureKey } from './utils'
 
-const toContent = (value: Binding): Content => {
+const toContent = (value: Value): Content => {
   if (value == null) return { text: value }
   if (typeof value === 'string') return { text: value }
-  if (value.text == null) return { text: value.text }
-  if (typeof value.text === 'string')
-    return { text: value.text }
-  return value.text
+  const { placement: _, ...rest } = value
+  return rest
 }
 const extractPlacement = (
-  binding: DirectiveBinding<Binding, Modifier, Placement>,
+  binding: DirectiveBinding<Value, Modifier, Placement>,
 ) => {
   const { value, arg } = binding
 
   if (
     value &&
     typeof value !== 'string' &&
-    'placement' in value
+    'placement' in value &&
+    value.placement != null
   ) {
     return value.placement
   }

packages/vueltip/src/index.ts

@@ -2,4 +2,7 @@ export { useVueltip } from './composables'
 export { vueltipDirective } from './directive'
 export { setOptions } from './options'
 export { vueltipPlugin } from './plugin'
-export type { Content } from './types'
+export type {
+  Content,
+  CustomVueltipData,
+} from './types'

packages/vueltip/src/types.ts

@@ -5,20 +5,23 @@ import type {
 import { Maybe } from '@vingy/shared/types'
 import type { Directive, ShallowRef } from 'vue'
 
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface CustomVueltipData {}
+
 export interface Content {
   text: Maybe<string>
+  custom?: CustomVueltipData
 }
-export type Binding =
+export type Value =
   | Maybe<string>
-  | {
-      text: Maybe<string | Content>
-      placement: Placement
-    }
+  | (Content & {
+      placement?: Placement
+    })
 export type Modifier = 'x' | 'y' | 'none' | 'both'
 
 export type TooltipDirective = Directive<
   HTMLElement,
-  Binding,
+  Value,
   Modifier,
   Placement
 >