@vingy/vueltip 0.2.0 → 1.0.0

package/README.md

@@ -0,0 +1,128 @@
+# Vueltip
+
+A headless tooltip component for Vue.js.
+
+## Features
+
+- **Dynamic Visibility**: The tooltip does not display when the tooltip text is identical to the element's content, unless the content is truncated.
+- **Single Tooltip Instance**: A single tooltip is used, which is repositioned within the window as needed.
+- **Headless Design**: Fully customizable; bring your own component(s) for rendering.
+
+## Quick Start
+
+To install Vueltip, use npm or yarn:
+
+```bash
+pnpm add vueltip
+```
+
+Register the tooltip in your app:
+
+```ts
+import Vueltip from 'vueltip'
+
+createApp(App).use(Vueltip)
+```
+
+## Usage
+
+### 1. Create a Tooltip Component
+
+First, create a tooltip component using the \`useTooltip\` composable:
+
+```ts
+<!-- Tooltip.vue -->
+<template>
+  <div
+    ref="tooltipElement"
+    v-show="show"
+    :style="tooltipStyles"
+    class="tooltip"
+  >
+    {{ content }}
+    <div
+      ref="arrowElement"
+      :style="arrowStyles"
+      class="tooltip-arrow"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useTooltip } from 'vueltip'
+
+const tooltipElement = ref()
+const arrowElement = ref()
+
+const { tooltipStyles, arrowStyles, show, content } =
+  useTooltip({
+    tooltipElement,
+    arrowElement,
+    offset: 8,
+    padding: 8,
+    arrowSize: 10,
+  })
+</script>
+
+<style scoped>
+.tooltip {
+  background: #333;
+  color: white;
+  padding: 8px 12px;
+  border-radius: 4px;
+  font-size: 14px;
+  z-index: 9999;
+}
+
+.tooltip-arrow {
+  background: #333;
+}
+</style>
+```
+
+### 2. Register in Your App
+
+Import and register the tooltip component and plugin in your app's entry point:
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import Vueltip from 'vueltip'
+import Tooltip from './components/Tooltip.vue'
+
+const app = createApp(App)
+
+app.use(Vueltip, {
+  component: Tooltip,
+})
+
+app.mount('#app')
+```
+
+### 3. Use the Directive
+
+Now you can use the `v-tooltip` directive on any element:
+
+```ts
+<template>
+  <div>
+    <button v-tooltip="{ text: 'Click me to submit' }">
+      Submit
+    </button>
+
+    <input
+      v-tooltip="{ text: 'Enter your email address' }"
+      type="email"
+      placeholder="Email"
+    />
+
+    <span v-tooltip="{ text: 'This is a helpful tooltip' }">
+      Hover over me
+    </span>
+  </div>
+</template>
+```
+
+See the demo app in [demo/](../../demo/).

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 { ShallowRef, StyleValue } from "vue";
+import { App, Component, Directive, 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}`;
@@ -248,6 +248,11 @@ declare type UseFloatingOptions<T extends ReferenceElement = ReferenceElement> =
 interface Content {
   text: string;
 }
+type Binding = string | {
+  content: string | Content;
+  placement: Placement;
+};
+type TooltipDirective = Directive<HTMLElement, Binding>;
 type Options = {
   /** @default 'tooltip-placement' */placementAttribute: string; /** @default 'tooltip-key' */
   keyAttribute: string; /** @default 0 */
@@ -263,9 +268,18 @@ type UseTooltipOptions = {
   arrowSize?: number;
   floatingOptions?: UseFloatingOptions<HTMLElement>;
 };
+declare module 'vue' {
+  interface GlobalDirectives {
+    vTooltip: TooltipDirective;
+  }
+}
+//#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 useTooltip: ({
+declare const useVueltip: ({
   tooltipElement,
   arrowElement,
   offset: _offset,
@@ -291,9 +305,21 @@ declare const useTooltip: ({
   content: Vue.Ref<Maybe<Content>, Maybe<Content>>;
 };
 //#endregion
+//#region src/directive.d.ts
+declare const vueltipDirective: {
+  updated: (el: HTMLElement, binding: Vue.DirectiveBinding<Binding, string, any>) => void;
+  created: (el: HTMLElement, binding: Vue.DirectiveBinding<Binding, string, any>) => void;
+  beforeUnmount: (el: HTMLElement) => void;
+};
+//#endregion
+//#region src/options.d.ts
+declare const setOptions: (opts?: Partial<Options>) => void;
+//#endregion
 //#region src/plugin.d.ts
-declare const tooltipPlugin: {
-  install: (app: any, options?: Partial<Options>) => void;
+declare const vueltipPlugin: {
+  install: (app: App, options: Partial<Options & {
+    component: Component;
+  }>) => void;
 };
 //#endregion
-export { type Content, tooltipPlugin, useTooltip };
+export { type Content, 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, onMounted, ref, watch } from "vue";
+import { computed, createApp, onMounted, 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,8 +1390,8 @@ function useFloating(reference, floating, options) {
 //#endregion
 //#region src/options.ts
 let options = {
-	placementAttribute: "tooltip-placement",
-	keyAttribute: "tooltip-key",
+	placementAttribute: "vueltip-placement",
+	keyAttribute: "vueltip-key",
 	showDelay: 0,
 	hideDelay: 200,
 	handleDialogModals: false
@@ -1441,7 +1441,7 @@ const sideMap = {
 	bottom: "top",
 	left: "right"
 };
-const useTooltip = ({ tooltipElement, arrowElement, offset: _offset, padding, arrowSize, floatingOptions }) => {
+const useVueltip = ({ tooltipElement, arrowElement, offset: _offset, padding, arrowSize, floatingOptions }) => {
 	let initialParent;
 	onMounted(() => {
 		initialParent = tooltipElement.value?.parentElement;
@@ -1547,7 +1547,7 @@ const onMouseout = ensureEventTarget((target) => {
 //#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 tooltipDirective = {
+const vueltipDirective = {
 	updated: (el, binding) => {
 		ensureKey(el, (key) => setContent(key, toContent(binding.value)));
 	},
@@ -1572,10 +1572,17 @@ const tooltipDirective = {
 
 //#endregion
 //#region src/plugin.ts
-const tooltipPlugin = { install: (app, options) => {
-	setOptions(options);
-	app.directive("tooltip", tooltipDirective);
+const vueltipPlugin = { install: (app, options) => {
+	const { component, ...rest } = options;
+	setOptions(rest);
+	if (!component) return;
+	const container = document.createElement("div");
+	container.id = "__vueltip_root__";
+	document.body.appendChild(container);
+	const tooltipApp = createApp(component);
+	tooltipApp._context = app._context;
+	tooltipApp.mount(container);
 } };
 
 //#endregion
-export { tooltipPlugin, useTooltip };
+export { setOptions, useVueltip, vueltipDirective, vueltipPlugin };

package/package.json

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