@versini/ui-tooltip 3.1.1 → 4.0.1

package/README.md

@@ -18,7 +18,7 @@ The Tooltip component provides contextual help and information with proper acces
 ## Features
 
 - **🧭 Smart Positioning**: Uses Floating UI for collision-aware placement & arrow positioning
-- **⏱️ Show Delay**: Configurable appearance delay (`delay` prop)
+- **⏱️ Configurable Timing**: Show delay (`delay` prop) and fade-in duration (`animationDuration` prop)
 - **♿ Accessible**: Proper `role="tooltip"`, hover & focus behavior, optional disabling period
 - **🎨 Theming**: Supports light / dark / system / alt-system modes
 - **🪶 Lightweight**: Minimal DOM & style footprint; only renders when visible
@@ -59,17 +59,37 @@ function App() {
 </div>
 ```
 
-### Custom Delay & Dark Mode
+### Custom Animation Duration & Dark Mode
 
 ```tsx
 <Tooltip
-  label="Appears after 1s"
-  delay={1000}
+  label="Smooth fade-in"
+  animationDuration={1000}
   mode="dark"
-  trigger={<button>Delayed</button>}
+  trigger={<button>Slow animation</button>}
 />
 ```
 
+### Delayed Appearance
+
+```tsx
+<Tooltip
+  label="Appears after 500ms"
+  delay={500}
+  trigger={<button>Hover and wait</button>}
+/>;
+
+{
+  /* Combine delay and animation duration */
+}
+<Tooltip
+  label="Wait 300ms, then fade in over 800ms"
+  delay={300}
+  animationDuration={800}
+  trigger={<button>Delayed & animated</button>}
+/>;
+```
+
 ### Styling the Tooltip & Arrow
 
 ```tsx
@@ -85,15 +105,16 @@ function App() {
 
 ### Tooltip Props
 
-| Prop               | Type                                    | Default | Description                                        |
-| ------------------ | --------------------------------------- | ------- | -------------------------------------------------- | ------------- | ---------- | ------------------------------ |
-| `label`            | `string`                                | -       | Text content of the tooltip.                       |
-| `trigger`          | `React.ReactNode`                       | -       | Element that the tooltip is anchored to.           |
-| `placement`        | `Placement` (from `@floating-ui/react`) | `"top"` | Preferred initial placement (auto flips / shifts). |
-| `mode`             | `"dark"                                 | "light" | "system"                                           | "alt-system"` | `"system"` | Theme mode controlling colors. |
-| `delay`            | `number`                                | `300`   | Milliseconds before showing tooltip.               |
-| `className`        | `string`                                | -       | Extra classes for outer wrapper.                   |
-| `tooltipClassName` | `string`                                | -       | Extra classes for tooltip bubble.                  |
-| `arrowClassName`   | `string`                                | -       | Extra classes for tooltip arrow element.           |
+| Prop                | Type                                    | Default | Description                                        |
+| ------------------- | --------------------------------------- | ------- | -------------------------------------------------- | ------------- | ---------- | ------------------------------ |
+| `label`             | `string`                                | -       | Text content of the tooltip.                       |
+| `trigger`           | `React.ReactNode`                       | -       | Element that the tooltip is anchored to.           |
+| `placement`         | `Placement` (from `@floating-ui/react`) | `"top"` | Preferred initial placement (auto flips / shifts). |
+| `mode`              | `"dark"                                 | "light" | "system"                                           | "alt-system"` | `"system"` | Theme mode controlling colors. |
+| `delay`             | `number`                                | `0`     | Delay before showing tooltip (milliseconds).       |
+| `animationDuration` | `number`                                | `300`   | Duration of fade-in animation (milliseconds).      |
+| `className`         | `string`                                | -       | Extra classes for outer wrapper.                   |
+| `tooltipClassName`  | `string`                                | -       | Extra classes for tooltip bubble.                  |
+| `arrowClassName`    | `string`                                | -       | Extra classes for tooltip arrow element.           |
 
 > Tooltip appears on hover/focus, hides on leave/click, and temporarily disables after click to prevent flicker.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { JSX } from 'react/jsx-runtime';
 import { Placement } from '@floating-ui/react';
 
-export declare const Tooltip: ({ trigger, label, placement, mode, delay, className, tooltipClassName, arrowClassName, }: TooltipTypes.Props) => JSX.Element;
+export declare const Tooltip: ({ trigger, label, placement, mode, animationDuration, delay, className, tooltipClassName, arrowClassName, }: TooltipTypes.Props) => JSX.Element;
 
 export declare const TOOLTIP_ARROW_CLASSNAME = "av-tooltip-arrow";
 
@@ -43,9 +43,14 @@ declare namespace TooltipTypes {
          		 */
         		mode?: "dark" | "light" | "system" | "alt-system";
         		/**
-         		 * The delay in milliseconds before showing the tooltip.
+         		 * The duration in milliseconds of the tooltip fade-in animation.
          		 * @default 300
          		 */
+        		animationDuration?: number;
+        		/**
+         		 * The delay in milliseconds before showing the tooltip after hovering.
+         		 * @default 0
+         		 */
         		delay?: number;
         	};
 }

package/dist/index.js

@@ -1,12 +1,12 @@
 /*!
-  @versini/ui-tooltip v3.1.1
+  @versini/ui-tooltip v4.0.1
   © 2025 gizmette.com
 */
 try {
   if (!window.__VERSINI_UI_TOOLTIP__) {
     window.__VERSINI_UI_TOOLTIP__ = {
-      version: "3.1.1",
-      buildTime: "11/16/2025 05:49 PM EST",
+      version: "4.0.1",
+      buildTime: "11/30/2025 07:18 PM EST",
       homepage: "https://github.com/aversini/ui-components",
       license: "MIT",
     };
@@ -79,9 +79,9 @@ const getTooltipClasses = ({ mode, className, tooltipClassName, arrowClassName }
         wrapper
     };
 };
-const getAnimationStyles = ({ delay = 300 })=>{
+const getAnimationStyles = ({ animationDuration = 300 })=>{
     return {
-        animation: `av-tooltip-fade-in ${delay}ms ease-in-out`
+        animation: `av-tooltip-fade-in ${animationDuration}ms ease-in-out`
     };
 };
 
@@ -92,14 +92,16 @@ const getAnimationStyles = ({ delay = 300 })=>{
 
 
 const DEFAULT_DEACTIVATION_DELAY = 5000;
-const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 300, className, tooltipClassName, arrowClassName })=>{
+const Tooltip = ({ trigger, label, placement = "top", mode = "system", animationDuration = 300, delay = 0, className, tooltipClassName, arrowClassName })=>{
     const referenceRef = useClickOutside(()=>{
         /* v8 ignore next 1 */ delayedRestartTooltip.stop(), setDisabled(false);
     });
     const floatingRef = useRef(null);
     const floatingArrowRef = useRef(null);
+    const showTimeoutRef = useRef(null);
     const [showTooltip, setShowTooltip] = useState(false);
     const [disabled, setDisabled] = useState(false);
+    const [isPositioned, setIsPositioned] = useState(false);
     const delayedRestartTooltip = useInterval(()=>{
         setDisabled(false);
     }, DEFAULT_DEACTIVATION_DELAY);
@@ -110,7 +112,7 @@ const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 3
         arrowClassName
     });
     const animationStyles = getAnimationStyles({
-        delay
+        animationDuration
     });
     const updatePosition = useCallback(async ()=>{
         if (referenceRef.current && floatingRef.current && floatingArrowRef.current) {
@@ -152,6 +154,7 @@ const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 3
                     [staticSide]: "-4px"
                 });
             }
+            setIsPositioned(true);
         }
     }, [
         placement,
@@ -162,13 +165,26 @@ const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 3
         (async ()=>{
             if (showTooltip) {
                 await updatePosition();
+            } else {
+                setIsPositioned(false);
             }
         })();
     }, [
         updatePosition,
         showTooltip
     ]);
+    useEffect(()=>{
+        return ()=>{
+            if (showTimeoutRef.current) {
+                clearTimeout(showTimeoutRef.current);
+            }
+        };
+    }, []);
     const handleMouseClick = ()=>{
+        if (showTimeoutRef.current) {
+            clearTimeout(showTimeoutRef.current);
+            showTimeoutRef.current = null;
+        }
         setShowTooltip(false);
         setDisabled(true);
         // disabling tooltip for 5 seconds
@@ -176,10 +192,21 @@ const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 3
     };
     const handleMouseEnter = ()=>{
         if (!disabled) {
-            setShowTooltip(true);
+            if (delay > 0) {
+                showTimeoutRef.current = setTimeout(()=>{
+                    setShowTooltip(true);
+                    showTimeoutRef.current = null;
+                }, delay);
+            } else {
+                setShowTooltip(true);
+            }
         }
     };
     const handleMouseLeave = ()=>{
+        if (showTimeoutRef.current) {
+            clearTimeout(showTimeoutRef.current);
+            showTimeoutRef.current = null;
+        }
         if (!disabled) {
             setShowTooltip(false);
         }
@@ -196,6 +223,9 @@ const Tooltip = ({ trigger, label, placement = "top", mode = "system", delay = 3
                 role: "tooltip",
                 ref: floatingRef,
                 className: tooltipClasses.tooltip,
+                style: {
+                    opacity: isPositioned ? undefined : 0
+                },
                 children: [
                     label,
                     /*#__PURE__*/ jsx("div", {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-tooltip",
-	"version": "3.1.1",
+	"version": "4.0.1",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -38,7 +38,7 @@
 	},
 	"devDependencies": {
 		"@testing-library/jest-dom": "6.9.1",
-		"@versini/ui-types": "6.0.2"
+		"@versini/ui-types": "7.0.0"
 	},
 	"dependencies": {
 		"@floating-ui/react": "0.27.16",
@@ -50,5 +50,5 @@
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "1d0bedfa3a84ea7f2f41d347a59de518f92e4cea"
+	"gitHead": "86a93dd1fc801dedf9d72169bb5a352a855fbf20"
 }