@vingy/vueltip 0.1.0 → 0.3.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/chunk-CtajNgzt.mjs

@@ -0,0 +1,36 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+//#endregion
+export { __reExport as n, __exportAll as t };

package/dist/index.d.mts

@@ -0,0 +1,301 @@
+import { n as __reExport, t as __exportAll } from "./chunk-CtajNgzt.mjs";
+import * as Vue from "vue";
+import { App, Component, 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}`;
+declare type Alignment = 'start' | 'end';
+declare type Axis = 'x' | 'y';
+declare type ClientRectObject = Prettify$1<Rect & SideObject>;
+declare type Coords = { [key in Axis]: number };
+declare type Dimensions = { [key in Length]: number };
+declare interface ElementRects {
+  reference: Rect;
+  floating: Rect;
+}
+declare type Length = 'width' | 'height';
+declare type Padding = number | Prettify$1<Partial<SideObject>>;
+declare type Placement = Prettify$1<Side | AlignedPlacement>;
+declare type Prettify$1<T> = { [K in keyof T]: T[K] } & {};
+declare type Rect = Prettify$1<Coords & Dimensions>;
+declare type Side = 'top' | 'right' | 'bottom' | 'left';
+declare type SideObject = { [key in Side]: number };
+declare type Strategy = 'absolute' | 'fixed';
+//#endregion
+//#region ../../node_modules/.pnpm/@floating-ui+core@1.7.4/node_modules/@floating-ui/core/dist/floating-ui.core.d.mts
+declare type Boundary = any;
+/**
+ * Function option to derive middleware options from state.
+ */
+declare type Derivable<T> = (state: MiddlewareState$1) => T;
+/**
+ * Resolves with an object of overflow side offsets that determine how much the
+ * element is overflowing a given clipping boundary on each side.
+ * - positive = overflowing the boundary by that number of pixels
+ * - negative = how many pixels left before it will overflow
+ * - 0 = lies flush with the boundary
+ * @see https://floating-ui.com/docs/detectOverflow
+ */
+declare function detectOverflow(state: MiddlewareState$1, options?: DetectOverflowOptions | Derivable<DetectOverflowOptions>): Promise<SideObject>;
+declare interface DetectOverflowOptions {
+  /**
+   * The clipping element(s) or area in which overflow will be checked.
+   * @default 'clippingAncestors'
+   */
+  boundary?: Boundary;
+  /**
+   * The root clipping area in which overflow will be checked.
+   * @default 'viewport'
+   */
+  rootBoundary?: RootBoundary;
+  /**
+   * The element in which overflow is being checked relative to a boundary.
+   * @default 'floating'
+   */
+  elementContext?: ElementContext;
+  /**
+   * Whether to check for overflow using the alternate element's boundary
+   * (`clippingAncestors` boundary only).
+   * @default false
+   */
+  altBoundary?: boolean;
+  /**
+   * Virtual padding for the resolved overflow detection offsets.
+   * @default 0
+   */
+  padding?: Padding;
+}
+declare type ElementContext = 'reference' | 'floating';
+declare interface Elements$1 {
+  reference: ReferenceElement$1;
+  floating: FloatingElement$1;
+}
+declare type FloatingElement$1 = any;
+declare type Middleware$1 = {
+  name: string;
+  options?: any;
+  fn: (state: MiddlewareState$1) => Promisable$1<MiddlewareReturn>;
+};
+declare interface MiddlewareData {
+  [key: string]: any;
+  arrow?: Partial<Coords> & {
+    centerOffset: number;
+    alignmentOffset?: number;
+  };
+  autoPlacement?: {
+    index?: number;
+    overflows: Array<{
+      placement: Placement;
+      overflows: Array<number>;
+    }>;
+  };
+  flip?: {
+    index?: number;
+    overflows: Array<{
+      placement: Placement;
+      overflows: Array<number>;
+    }>;
+  };
+  hide?: {
+    referenceHidden?: boolean;
+    escaped?: boolean;
+    referenceHiddenOffsets?: SideObject;
+    escapedOffsets?: SideObject;
+  };
+  offset?: Coords & {
+    placement: Placement;
+  };
+  shift?: Coords & {
+    enabled: { [key in Axis]: boolean };
+  };
+}
+declare interface MiddlewareReturn extends Partial<Coords> {
+  data?: {
+    [key: string]: any;
+  };
+  reset?: boolean | {
+    placement?: Placement;
+    rects?: boolean | ElementRects;
+  };
+}
+declare interface MiddlewareState$1 extends Coords {
+  initialPlacement: Placement;
+  placement: Placement;
+  strategy: Strategy;
+  middlewareData: MiddlewareData;
+  elements: Elements$1;
+  rects: ElementRects;
+  platform: {
+    detectOverflow: typeof detectOverflow;
+  } & Platform;
+}
+/**
+ * Platform interface methods to work with the current platform.
+ * @see https://floating-ui.com/docs/platform
+ */
+declare interface Platform {
+  getElementRects: (args: {
+    reference: ReferenceElement$1;
+    floating: FloatingElement$1;
+    strategy: Strategy;
+  }) => Promisable$1<ElementRects>;
+  getClippingRect: (args: {
+    element: any;
+    boundary: Boundary;
+    rootBoundary: RootBoundary;
+    strategy: Strategy;
+  }) => Promisable$1<Rect>;
+  getDimensions: (element: any) => Promisable$1<Dimensions>;
+  convertOffsetParentRelativeRectToViewportRelativeRect?: (args: {
+    elements?: Elements$1;
+    rect: Rect;
+    offsetParent: any;
+    strategy: Strategy;
+  }) => Promisable$1<Rect>;
+  getOffsetParent?: (element: any) => Promisable$1<any>;
+  isElement?: (value: any) => Promisable$1<boolean>;
+  getDocumentElement?: (element: any) => Promisable$1<any>;
+  getClientRects?: (element: any) => Promisable$1<Array<ClientRectObject>>;
+  isRTL?: (element: any) => Promisable$1<boolean>;
+  getScale?: (element: any) => Promisable$1<{
+    x: number;
+    y: number;
+  }>;
+  detectOverflow?: typeof detectOverflow;
+}
+declare type Promisable$1<T> = T | Promise<T>;
+declare type ReferenceElement$1 = any;
+declare type RootBoundary = 'viewport' | 'document' | Rect;
+//#endregion
+//#region ../../node_modules/.pnpm/@floating-ui+dom@1.7.5/node_modules/@floating-ui/dom/dist/floating-ui.dom.d.mts
+declare interface Elements {
+  reference: ReferenceElement;
+  floating: FloatingElement;
+}
+declare type FloatingElement = HTMLElement;
+declare type Middleware = Prettify<Omit<Middleware$1, 'fn'> & {
+  fn(state: MiddlewareState): Promisable<MiddlewareReturn>;
+}>;
+declare type MiddlewareState = Prettify<Omit<MiddlewareState$1, 'elements'> & {
+  elements: Elements;
+}>;
+declare type Prettify<T> = { [K in keyof T]: T[K] } & {};
+declare type Promisable<T> = T | Promise<T>;
+declare type ReferenceElement = Element | VirtualElement;
+/**
+ * Custom positioning reference element.
+ * @see https://floating-ui.com/docs/virtual-elements
+ */
+declare interface VirtualElement {
+  getBoundingClientRect(): ClientRectObject;
+  getClientRects?(): Array<ClientRectObject> | DOMRectList;
+  contextElement?: Element;
+}
+declare namespace index_d_exports {
+  export { V as Vue, Vue2, del, install, isVue2, isVue3, set };
+}
+import * as import_vue from "vue";
+declare const isVue2: boolean;
+declare const isVue3: boolean;
+declare const Vue2: any;
+declare const install: (vue?: any) => void;
+/** 
+ * @deprecated To avoid bringing in all the tree-shakable modules, this API has been deprecated. Use `Vue2` or named exports instead.
+ * Refer to https://github.com/vueuse/vue-demi/issues/41
+ */
+declare const V: typeof Vue;
+declare function set<T>(target: any, key: any, val: T): T;
+declare function del(target: any, key: any): void;
+//#endregion
+//#region ../../node_modules/.pnpm/@floating-ui+vue@1.1.10_vue@3.5.28_typescript@5.9.3_/node_modules/@floating-ui/vue/dist/floating-ui.vue.d.mts
+declare type MaybeReadonlyRef<T> = T | Readonly<index_d_exports.Ref<T>>;
+declare type MaybeReadonlyRefOrGetter<T> = MaybeReadonlyRef<T> | (() => T);
+declare type UseFloatingOptions<T extends ReferenceElement = ReferenceElement> = {
+  /**
+   * Represents the open/close state of the floating element.
+   * @default true
+   */
+  open?: MaybeReadonlyRefOrGetter<boolean | undefined>;
+  /**
+   * Where to place the floating element relative to its reference element.
+   * @default 'bottom'
+   */
+  placement?: MaybeReadonlyRefOrGetter<Placement | undefined>;
+  /**
+   * The type of CSS position property to use.
+   * @default 'absolute'
+   */
+  strategy?: MaybeReadonlyRefOrGetter<Strategy | undefined>;
+  /**
+   * These are plain objects that modify the positioning coordinates in some fashion, or provide useful data for the consumer to use.
+   * @default undefined
+   */
+  middleware?: MaybeReadonlyRefOrGetter<Middleware[] | undefined>;
+  /**
+   * Whether to use `transform` instead of `top` and `left` styles to
+   * position the floating element (`floatingStyles`).
+   * @default true
+   */
+  transform?: MaybeReadonlyRefOrGetter<boolean | undefined>;
+  /**
+   * Callback to handle mounting/unmounting of the elements.
+   * @default undefined
+   */
+  whileElementsMounted?: (reference: T, floating: FloatingElement, update: () => void) => () => void;
+};
+//#endregion
+//#region src/types.d.ts
+interface Content {
+  text: string;
+}
+type Options = {
+  /** @default 'tooltip-placement' */placementAttribute: string; /** @default 'tooltip-key' */
+  keyAttribute: string; /** @default 0 */
+  showDelay: number; /** @default 200 */
+  hideDelay: number; /** @default false */
+  handleDialogModals: boolean;
+};
+type UseTooltipOptions = {
+  tooltipElement: Readonly<ShallowRef<HTMLElement | null>>;
+  arrowElement?: Readonly<ShallowRef<HTMLElement | null>>;
+  offset?: number;
+  padding?: number;
+  arrowSize?: number;
+  floatingOptions?: UseFloatingOptions<HTMLElement>;
+};
+//#endregion
+//#region src/composables.d.ts
+declare const useTooltip: ({
+  tooltipElement,
+  arrowElement,
+  offset: _offset,
+  padding,
+  arrowSize,
+  floatingOptions
+}: UseTooltipOptions) => {
+  tooltipStyles: Readonly<Vue.Ref<{
+    position: Strategy;
+    top: string;
+    left: string;
+    transform?: string;
+    willChange?: string;
+  }, {
+    position: Strategy;
+    top: string;
+    left: string;
+    transform?: string;
+    willChange?: string;
+  }>>;
+  arrowStyles: Vue.ComputedRef<StyleValue>;
+  show: Vue.ComputedRef<boolean>;
+  content: Vue.Ref<Maybe<Content>, Maybe<Content>>;
+};
+//#endregion
+//#region src/plugin.d.ts
+declare const tooltipPlugin: {
+  install: (app: App, options: Partial<Options> & {
+    component: Component;
+  }) => void;
+};
+//#endregion
+export { type Content, tooltipPlugin, useTooltip };