@vingy/vueltip 1.3.0 → 2.0.0

package/README.md

@@ -13,13 +13,16 @@ A headless tooltip component for Vue.js.
 To install Vueltip, use npm or yarn:
 
 ```bash
-pnpm add vueltip
+pnpm add @vingy/vueltip
 ```
 
 Register the tooltip in your app:
 
 ```ts
-import { vueltipPlugin, vueltipDirective } from 'vueltip'
+import {
+  vueltipPlugin,
+  vueltipDirective,
+} from '@vingy/vueltip'
 
 createApp(App)
   .use(vueltipPlugin, { component: Tooltip })
@@ -52,7 +55,7 @@ First, create a tooltip component using the \`useTooltip\` composable:
 
 <script setup>
 import { useTemplateRef } from 'vue'
-import { useVueltip } from 'vueltip'
+import { useVueltip } from '@vingy/vueltip'
 
 const tooltipElement = useTemplateRef('tooltipElement')
 const arrowElement = useTemplateRef('arrowElement')
@@ -90,7 +93,10 @@ Import and register the tooltip component and plugin in your app's entry point:
 // main.ts
 import { createApp } from 'vue'
 import App from './App.vue'
-import { vueltipPlugin, vueltipDirective } from 'vueltip'
+import {
+  vueltipPlugin,
+  vueltipDirective,
+} from '@vingy/vueltip'
 import Tooltip from './components/Tooltip.vue'
 
 const app = createApp(App)
@@ -121,7 +127,7 @@ Now you can use the `v-tooltip` directive on any element:
 
     <span
       v-tooltip="{
-        content: 'This is a helpful tooltip',
+        text: 'This is a helpful tooltip',
         placement: 'right',
       }"
     >
@@ -139,17 +145,17 @@ See the demo app in [demo/](../../demo/).
 
 The `vueltipPlugin` accepts the following options:
 
-| Option                     | Type                             | Default               | Description                                                                                                            |
-| -------------------------- | -------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `component`                | `Component`                      | Required              | The Vue component to render as the tooltip                                                                             |
-| `showDelay`                | `number`                         | `0`                   | Delay in milliseconds before the tooltip appears on hover                                                              |
-| `hideDelay`                | `number`                         | `200`                 | Delay in milliseconds before the tooltip disappears when the cursor leaves                                             |
-| `defaultPlacement`         | `Placement`                      | `'top'`               | Default tooltip placement: `'top'`, `'bottom'`, `'left'`, `'right'`, etc.                                              |
-| `defaultTruncateDetection` | `'x' \| 'y' \| 'both' \| 'none'` | `'both'`              | Direction(s) to check for text truncation (`'x'` for horizontal, `'y'` for vertical, `'both'`, or `'none'` to disable) |
-| `handleDialogModals`       | `boolean`                        | `false`               | Whether to handle tooltips within HTML `<dialog>` elements with the `open` attribute (modal dialogs)                   |
-| `placementAttribute`       | `string`                         | `'vueltip-placement'` | HTML attribute name for tooltip placement overrides                                                                    |
-| `keyAttribute`             | `string`                         | `'vueltip-key'`       | HTML attribute name for tooltip identification                                                                         |
-| `truncateAttribute`        | `string`                         | `'vueltip-truncate'`  | HTML attribute name for truncate detection overrides                                                                   |
+| Option                     | Type                             | Default                    | Description                                                                                                            |
+| -------------------------- | -------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `component`                | `Component`                      | Required                   | The Vue component to render as the tooltip                                                                             |
+| `showDelay`                | `number`                         | `0`                        | Delay in milliseconds before the tooltip appears on hover                                                              |
+| `hideDelay`                | `number`                         | `200`                      | Delay in milliseconds before the tooltip disappears when the cursor leaves                                             |
+| `defaultPlacement`         | `Placement`                      | `'top'`                    | Default tooltip placement: `'top'`, `'bottom'`, `'left'`, `'right'`, etc.                                              |
+| `defaultTruncateDetection` | `'x' \| 'y' \| 'both' \| 'none'` | `'both'`                   | Direction(s) to check for text truncation (`'x'` for horizontal, `'y'` for vertical, `'both'`, or `'none'` to disable) |
+| `handleDialogModals`       | `boolean`                        | `false`                    | Whether to handle tooltips within HTML `<dialog>` elements with the `open` attribute (modal dialogs)                   |
+| `placementAttribute`       | `string`                         | `'data-vueltip-placement'` | HTML attribute name for tooltip placement overrides                                                                    |
+| `keyAttribute`             | `string`                         | `'data-vueltip-key'`       | HTML attribute name for tooltip identification                                                                         |
+| `truncateAttribute`        | `string`                         | `'data-vueltip-truncate'`  | HTML attribute name for truncate detection overrides                                                                   |
 
 ### useVueltip Composable Options
 
@@ -178,7 +184,64 @@ v-tooltip="'Tooltip text'"
 
 ```ts
 v-tooltip="{
-  content: 'Tooltip text',
+  text: 'Tooltip text',
   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>
+```

package/dist/index.d.mts

@@ -1,4 +1,3 @@
-import { n as __reExport, t as __exportAll } from "./chunk-CtajNgzt.mjs";
 import * as Vue from "vue";
 import { App, Component, Directive, DirectiveBinding, ShallowRef, StyleValue } from "vue";
 
@@ -249,18 +248,19 @@ declare type UseFloatingOptions<T extends ReferenceElement = ReferenceElement> =
 type Maybe<T> = T | null | undefined; //#endregion
 //#endregion
 //#region src/types.d.ts
+interface CustomVueltipData {}
 interface Content {
   text: Maybe<string>;
+  custom?: CustomVueltipData;
 }
-type Binding = Maybe<string> | {
-  content: Maybe<string | Content>;
-  placement: Placement;
-};
+type Value = Maybe<string> | (Content & {
+  placement?: Placement;
+});
 type Modifier = 'x' | 'y' | 'none' | 'both';
-type TooltipDirective = Directive<HTMLElement, Binding, Modifier, Placement>;
+type TooltipDirective = Directive<HTMLElement, Value, Modifier, Placement>;
 type Options = {
-  /** @default 'vueltip-placement' */placementAttribute: string; /** @default 'vueltip-key' */
-  keyAttribute: string; /** @default 'vueltip-truncate' */
+  /** @default 'data-vueltip-placement' */placementAttribute: string; /** @default 'data-vueltip-key' */
+  keyAttribute: string; /** @default 'data-vueltip-truncate' */
   truncateAttribute: string; /** @default 0 */
   showDelay: number; /** @default 200 */
   hideDelay: number; /** @default false */
@@ -311,8 +311,8 @@ declare const useVueltip: ({
 //#endregion
 //#region src/directive.d.ts
 declare const vueltipDirective: {
-  updated: (el: HTMLElement, binding: DirectiveBinding<Binding, Modifier, Placement>) => void;
-  created: (el: HTMLElement, binding: DirectiveBinding<Binding, Modifier, Placement>) => void;
+  updated: (el: HTMLElement, binding: DirectiveBinding<Value, Modifier, Placement>) => void;
+  created: (el: HTMLElement, binding: DirectiveBinding<Value, Modifier, Placement>) => void;
   beforeUnmount: (el: HTMLElement) => void;
 };
 //#endregion
@@ -326,4 +326,4 @@ declare const vueltipPlugin: {
   }>) => void;
 };
 //#endregion
-export { type Content, setOptions, useVueltip, vueltipDirective, vueltipPlugin };
+export { type Content, type CustomVueltipData, setOptions, useVueltip, vueltipDirective, vueltipPlugin };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { n as __reExport, t as __exportAll } from "./chunk-CtajNgzt.mjs";
 import * as Vue from "vue";
-import { computed, createApp, onMounted, ref, watch } from "vue";
+import { computed, createApp, ref, watch } from "vue";
 
 //#region ../../node_modules/.pnpm/@floating-ui+utils@0.2.10/node_modules/@floating-ui/utils/dist/floating-ui.utils.mjs
 const min = Math.min;
@@ -1390,9 +1390,9 @@ function useFloating(reference, floating, options) {
 //#endregion
 //#region src/options.ts
 let options = {
-	placementAttribute: "vueltip-placement",
-	keyAttribute: "vueltip-key",
-	truncateAttribute: "vueltip-truncate",
+	placementAttribute: "data-vueltip-placement",
+	keyAttribute: "data-vueltip-key",
+	truncateAttribute: "data-vueltip-truncate",
 	showDelay: 0,
 	hideDelay: 200,
 	handleDialogModals: false,
@@ -1448,11 +1448,21 @@ const sideMap = {
 };
 const useVueltip = ({ tooltipElement, arrowElement, offset: _offset, padding, arrowSize, floatingOptions }) => {
 	let initialParent;
-	onMounted(() => {
-		initialParent = tooltipElement.value?.parentElement;
-		tooltipElement.value?.addEventListener("mouseenter", () => hoveredElement.value = debouncedHoveredElement.value);
-		tooltipElement.value?.addEventListener("mouseleave", () => hoveredElement.value = void 0);
-	});
+	const show = computed(() => !!debouncedHoveredElement.value);
+	watch(show, (value, _, onCleanup) => {
+		if (!value) return;
+		const el = tooltipElement.value;
+		if (!el) return;
+		initialParent = el.parentElement;
+		const onEnter = () => hoveredElement.value = debouncedHoveredElement.value;
+		const onLeave = () => hoveredElement.value = void 0;
+		el.addEventListener("mouseenter", onEnter);
+		el.addEventListener("mouseleave", onLeave);
+		onCleanup(() => {
+			el.removeEventListener("mouseenter", onEnter);
+			el.removeEventListener("mouseleave", onLeave);
+		});
+	}, { flush: "post" });
 	const middleware = [
 		offset(_offset),
 		flip(),
@@ -1481,7 +1491,6 @@ const useVueltip = ({ tooltipElement, arrowElement, offset: _offset, padding, ar
 			[staticSide.value]: `-${size / 2}px`
 		};
 	});
-	const show = computed(() => !!debouncedHoveredElement.value);
 	if (getOption("handleDialogModals")) watch(show, (value) => {
 		if (!value || !tooltipElement.value || !debouncedHoveredElement.value || !initialParent) return;
 		const dialogEl = debouncedHoveredElement.value.closest("dialog");
@@ -1564,13 +1573,12 @@ const onMouseout = ensureEventTarget((target) => {
 const toContent = (value) => {
 	if (value == null) return { text: value };
 	if (typeof value === "string") return { text: value };
-	if (value.content == null) return { text: value.content };
-	if (typeof value.content === "string") return { text: value.content };
-	return value.content;
+	const { placement: _, ...rest } = value;
+	return rest;
 };
 const extractPlacement = (binding) => {
 	const { value, arg } = binding;
-	if (value && typeof value !== "string" && "placement" in value) return value.placement;
+	if (value && typeof value !== "string" && "placement" in value && value.placement != null) return value.placement;
 	if (!arg) return getOption("defaultPlacement");
 	return arg;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vingy/vueltip",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "Headless tooltip which only shows when necessary.",
   "keywords": [
     "composition-api",