@vingy/vueltip 1.1.0 → 1.3.0

package/README.md

@@ -19,9 +19,11 @@ pnpm add vueltip
 Register the tooltip in your app:
 
 ```ts
-import Vueltip from 'vueltip'
+import { vueltipPlugin, vueltipDirective } from 'vueltip'
 
-createApp(App).use(Vueltip)
+createApp(App)
+  .use(vueltipPlugin, { component: Tooltip })
+  .directive('tooltip', vueltipDirective)
 ```
 
 ## Usage
@@ -49,19 +51,18 @@ First, create a tooltip component using the \`useTooltip\` composable:
 </template>
 
 <script setup>
-import { ref } from 'vue'
-import { useTooltip } from 'vueltip'
+import { useTemplateRef } from 'vue'
+import { useVueltip } from 'vueltip'
 
-const tooltipElement = ref()
-const arrowElement = ref()
+const tooltipElement = useTemplateRef('tooltipElement')
+const arrowElement = useTemplateRef('arrowElement')
 
 const { tooltipStyles, arrowStyles, show, content } =
-  useTooltip({
+  useVueltip({
     tooltipElement,
     arrowElement,
     offset: 8,
     padding: 8,
-    arrowSize: 10,
   })
 </script>
 
@@ -89,14 +90,16 @@ 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 Vueltip from 'vueltip'
+import { vueltipPlugin, vueltipDirective } from 'vueltip'
 import Tooltip from './components/Tooltip.vue'
 
 const app = createApp(App)
 
-app.use(Vueltip, {
-  component: Tooltip,
-})
+app
+  .use(vueltipPlugin, {
+    component: Tooltip,
+  })
+  .directive('tooltip', vueltipDirective)
 
 app.mount('#app')
 ```
@@ -105,20 +108,23 @@ app.mount('#app')
 
 Now you can use the `v-tooltip` directive on any element:
 
-```ts
+```vue
 <template>
   <div>
-    <button v-tooltip="{ text: 'Click me to submit' }">
-      Submit
-    </button>
+    <button v-tooltip="'Click me to submit'">Submit</button>
 
     <input
-      v-tooltip="{ text: 'Enter your email address' }"
+      v-tooltip="'Enter your email address'"
       type="email"
       placeholder="Email"
     />
 
-    <span v-tooltip="{ text: 'This is a helpful tooltip' }">
+    <span
+      v-tooltip="{
+        content: 'This is a helpful tooltip',
+        placement: 'right',
+      }"
+    >
       Hover over me
     </span>
   </div>
@@ -126,3 +132,53 @@ Now you can use the `v-tooltip` directive on any element:
 ```
 
 See the demo app in [demo/](../../demo/).
+
+## Options
+
+### Plugin Options
+
+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                                                                   |
+
+### useVueltip Composable Options
+
+The `useVueltip` composable accepts the following options:
+
+| Option            | Type                       | Default  | Description                                                |
+| ----------------- | -------------------------- | -------- | ---------------------------------------------------------- |
+| `tooltipElement`  | `Ref<HTMLElement \| null>` | Required | Reference to the tooltip container element                 |
+| `arrowElement`    | `Ref<HTMLElement \| null>` | Optional | Reference to the arrow element for positioning             |
+| `offset`          | `number`                   | `0`      | Offset distance between the tooltip and the target element |
+| `padding`         | `number`                   | `0`      | Padding between the tooltip and the viewport edges         |
+| `arrowSize`       | `number`                   | `0`      | Size of the arrow element (used for proper positioning)    |
+| `floatingOptions` | `UseFloatingOptions`       | `{}`     | Advanced options for the underlying Floating UI library    |
+
+### Directive Options
+
+The `v-tooltip` directive accepts bindings in two formats:
+
+**Simple string (text only):**
+
+```ts
+v-tooltip="'Tooltip text'"
+```
+
+**Object with options:**
+
+```ts
+v-tooltip="{
+  content: 'Tooltip text',
+  placement: 'right'  // Placement: 'top', 'bottom', 'left', 'right', etc.
+}"
+```

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { n as __reExport, t as __exportAll } from "./chunk-CtajNgzt.mjs";
 import * as Vue from "vue";
-import { App, Component, Directive, ShallowRef, StyleValue } from "vue";
+import { App, Component, Directive, DirectiveBinding, ShallowRef, StyleValue } from "vue";
 
 //#region ../../node_modules/.pnpm/@floating-ui+utils@0.2.10/node_modules/@floating-ui/utils/dist/floating-ui.utils.d.mts
 declare type AlignedPlacement = `${Side}-${Alignment}`;
@@ -244,16 +244,20 @@ declare type UseFloatingOptions<T extends ReferenceElement = ReferenceElement> =
   whileElementsMounted?: (reference: T, floating: FloatingElement, update: () => void) => () => void;
 };
 //#endregion
+//#region ../shared/dist/types.d.mts
+//#region src/types.d.ts
+type Maybe<T> = T | null | undefined; //#endregion
+//#endregion
 //#region src/types.d.ts
 interface Content {
-  text: string;
+  text: Maybe<string>;
 }
-type Binding = string | {
-  content: string | Content;
+type Binding = Maybe<string> | {
+  content: Maybe<string | Content>;
   placement: Placement;
 };
 type Modifier = 'x' | 'y' | 'none' | 'both';
-type TooltipDirective = Directive<HTMLElement, Binding, Modifier>;
+type TooltipDirective = Directive<HTMLElement, Binding, Modifier, Placement>;
 type Options = {
   /** @default 'vueltip-placement' */placementAttribute: string; /** @default 'vueltip-key' */
   keyAttribute: string; /** @default 'vueltip-truncate' */
@@ -261,7 +265,8 @@ type Options = {
   showDelay: number; /** @default 200 */
   hideDelay: number; /** @default false */
   handleDialogModals: boolean; /** @default 'both' */
-  defaultTruncateDetection: Modifier;
+  defaultTruncateDetection: Modifier; /** @default 'top' */
+  defaultPlacement: Placement;
 };
 type UseTooltipOptions = {
   tooltipElement: Readonly<ShallowRef<HTMLElement | null>>;
@@ -277,10 +282,6 @@ declare module 'vue' {
   }
 }
 //#endregion
-//#region ../shared/dist/types.d.mts
-//#region src/types.d.ts
-type Maybe<T> = T | null | undefined; //#endregion
-//#endregion
 //#region src/composables.d.ts
 declare const useVueltip: ({
   tooltipElement,
@@ -310,8 +311,8 @@ declare const useVueltip: ({
 //#endregion
 //#region src/directive.d.ts
 declare const vueltipDirective: {
-  updated: (el: HTMLElement, binding: Vue.DirectiveBinding<Binding, Modifier, any>) => void;
-  created: (el: HTMLElement, binding: Vue.DirectiveBinding<Binding, Modifier, any>) => void;
+  updated: (el: HTMLElement, binding: DirectiveBinding<Binding, Modifier, Placement>) => void;
+  created: (el: HTMLElement, binding: DirectiveBinding<Binding, Modifier, Placement>) => void;
   beforeUnmount: (el: HTMLElement) => void;
 };
 //#endregion

package/dist/index.mjs

@@ -1396,7 +1396,8 @@ let options = {
 	showDelay: 0,
 	hideDelay: 200,
 	handleDialogModals: false,
-	defaultTruncateDetection: "both"
+	defaultTruncateDetection: "both",
+	defaultPlacement: "top"
 };
 const setOptions = (opts) => {
 	options = {
@@ -1404,6 +1405,7 @@ const setOptions = (opts) => {
 		...opts
 	};
 };
+const getOption = (key) => options[key];
 
 //#endregion
 //#region src/state.ts
@@ -1411,10 +1413,10 @@ const tooltipPlacement = ref("top");
 const debouncedTooltipPlacement = ref("top");
 const hoveredElement = ref();
 const debouncedHoveredElement = ref();
-const contentMap = /* @__PURE__ */ new Map();
-const getContent = (key) => contentMap.get(key);
-const setContent = (key, value) => contentMap.set(key, value);
-const deleteContent = (key) => contentMap.delete(key);
+const contentMap = ref(/* @__PURE__ */ new Map());
+const getContent = (key) => contentMap.value.get(key);
+const setContent = (key, value) => contentMap.value.set(key, value);
+const deleteContent = (key) => contentMap.value.delete(key);
 const generateKey = () => crypto.randomUUID();
 const tooltipKey = ref();
 const tooltipContent = ref();
@@ -1422,11 +1424,12 @@ let timerId;
 watch([
 	tooltipKey,
 	hoveredElement,
-	tooltipPlacement
+	tooltipPlacement,
+	() => getContent(tooltipKey.value ?? "")
 ], ([key, el, placement]) => {
 	if (!key) return;
 	if (timerId) clearTimeout(timerId);
-	const timeout = el ? options.showDelay : options.hideDelay;
+	const timeout = el ? getOption("showDelay") : getOption("hideDelay");
 	timerId = setTimeout(() => {
 		tooltipContent.value = getContent(key);
 		debouncedHoveredElement.value = el;
@@ -1479,7 +1482,7 @@ const useVueltip = ({ tooltipElement, arrowElement, offset: _offset, padding, ar
 		};
 	});
 	const show = computed(() => !!debouncedHoveredElement.value);
-	if (options.handleDialogModals) watch(show, (value) => {
+	if (getOption("handleDialogModals")) watch(show, (value) => {
 		if (!value || !tooltipElement.value || !debouncedHoveredElement.value || !initialParent) return;
 		const dialogEl = debouncedHoveredElement.value.closest("dialog");
 		if (!dialogEl) {
@@ -1510,7 +1513,7 @@ function isTruncated(el) {
 	}
 }
 function getTruncationDirection(el) {
-	return el.getAttribute(options.truncateAttribute) ?? options.defaultTruncateDetection;
+	return el.getAttribute(getOption("truncateAttribute")) ?? getOption("defaultTruncateDetection");
 }
 function elementContainsText(el, text) {
 	if (isInputElement(el) || isTextAreaElement(el)) return getInputValue(el).includes(text);
@@ -1529,7 +1532,7 @@ function getInputValue(el) {
 	return el.value;
 }
 const ensureKey = (el, fn) => {
-	const key = el.getAttribute(options.keyAttribute);
+	const key = el.getAttribute(getOption("keyAttribute"));
 	if (!key) return;
 	return fn(key);
 };
@@ -1545,8 +1548,8 @@ const onMouseover = ensureEventTarget((target) => ensureKey(target, (key) => {
 	const content = getContent(key);
 	if (!content) return;
 	const { text } = content;
-	if (elementContainsText(target, text) && !isTruncated(target)) return;
-	const placement = target.getAttribute(options.placementAttribute);
+	if (!text || elementContainsText(target, text) && !isTruncated(target)) return;
+	const placement = target.getAttribute(getOption("placementAttribute"));
 	tooltipKey.value = key;
 	hoveredElement.value = target;
 	tooltipPlacement.value = placement;
@@ -1558,26 +1561,41 @@ const onMouseout = ensureEventTarget((target) => {
 
 //#endregion
 //#region src/directive.ts
-const toContent = (value) => typeof value === "string" ? { text: value } : typeof value.content === "string" ? { text: value.content } : value.content;
-const extractPlacement = (value) => typeof value === "string" ? "top" : value.placement;
+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 extractPlacement = (binding) => {
+	const { value, arg } = binding;
+	if (value && typeof value !== "string" && "placement" in value) return value.placement;
+	if (!arg) return getOption("defaultPlacement");
+	return arg;
+};
 const truncationDirection = (modifiers) => {
 	if (modifiers.none) return "none";
 	if (modifiers.both) return "both";
 	if (modifiers.x && modifiers.y) return "both";
 	if (modifiers.x) return "x";
 	if (modifiers.y) return "y";
-	return options.defaultTruncateDetection;
+	return getOption("defaultTruncateDetection");
 };
 const vueltipDirective = {
 	updated: (el, binding) => {
-		ensureKey(el, (key) => setContent(key, toContent(binding.value)));
+		ensureKey(el, (key) => {
+			el.setAttribute(getOption("placementAttribute"), extractPlacement(binding));
+			el.setAttribute(getOption("truncateAttribute"), truncationDirection(binding.modifiers ?? {}));
+			setContent(key, toContent(binding.value));
+		});
 	},
 	created: (el, binding) => {
 		const key = generateKey();
 		setContent(key, toContent(binding.value));
-		el.setAttribute(options.keyAttribute, key);
-		el.setAttribute(options.placementAttribute, extractPlacement(binding.value));
-		el.setAttribute(options.truncateAttribute, truncationDirection(binding.modifiers ?? {}));
+		el.setAttribute(getOption("keyAttribute"), key);
+		el.setAttribute(getOption("placementAttribute"), extractPlacement(binding));
+		el.setAttribute(getOption("truncateAttribute"), truncationDirection(binding.modifiers ?? {}));
 		el.addEventListener("mouseenter", onMouseover);
 		el.addEventListener("focus", onMouseover);
 		el.addEventListener("mouseleave", onMouseout);

package/package.json

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