@diabolic/pointy 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diabolic/pointy",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "A lightweight, dependency-free JavaScript library for creating animated tooltips with a pointing cursor. Perfect for product tours, onboarding flows, and feature highlights.",
   "main": "dist/pointy.js",

package/src/pointy.js

@@ -19,6 +19,7 @@
  * @options
  * - steps {Array<{target, content, direction?, duration?}>} - Tour steps
  * - target {string|HTMLElement} - Initial target element
+ * - content {string|string[]} - Initial content/messages (single-step use)
  * - offsetX {number} - Horizontal offset from target (default: 20)
  * - offsetY {number} - Vertical offset from target (default: 16)
  * - trackingFps {number} - Position update FPS, 0 = unlimited (default: 60)
@@ -73,9 +74,9 @@
  * - introAnimationEnd: Initial fade-in animation completed
  * 
  * Content:
- * - contentSet: Content updated via setContent()
- * - messagesSet: New messages array set for step
- * - messageChange: Message changed (manual or auto)
+ * - messagesSet: Messages array replaced via setMessages()
+ * - messageUpdate: Single message updated via setMessage()
+ * - messageChange: Message changed (navigation or auto-cycle)
  * 
  * Message Cycle:
  * - messageCycleStart: Auto message cycling started
@@ -126,7 +127,7 @@
  * Core: show(), hide(), destroy()
  * Navigation: next(), prev(), goToStep(index), reset(), restart()
  * Custom Target: pointTo(target, content?, direction?)
- * Content: setContent(content), nextMessage(), prevMessage(), goToMessage(index)
+ * Content: setMessages(content), setMessage(msg), nextMessage(), prevMessage(), goToMessage(index)
  * Message Cycle: startMessageCycle(interval?), stopMessageCycle(), pauseMessageCycle(), resumeMessageCycle()
  * Autoplay: startAutoplay(), stopAutoplay(), pauseAutoplay(), resumeAutoplay()
  * Animation: animateToInitialPosition()
@@ -501,6 +502,8 @@ class Pointy {
 
     this.bubble = document.createElement('div');
     this.bubble.className = this.classNames.bubble;
+    // Set initial bubble position for pointing up (default)
+    this.bubble.style.transform = 'translateY(28px)';
     
     this.bubbleText = document.createElement('span');
     this.bubbleText.className = this.classNames.bubbleText;
@@ -690,7 +693,7 @@ class Pointy {
       } else {
         // Default: pointing up
         this.pointer.style.transform = 'rotate(0deg)';
-        this.bubble.style.transform = 'translateY(0)';
+        this.bubble.style.transform = 'translateY(28px)';
       }
       
       this.container.style.display = 'flex';
@@ -713,9 +716,17 @@ class Pointy {
           
           this._startTracking();
           
-          // Show bubble immediately with fade
+          // Show bubble immediately with fade (only if content is not empty)
+          const hasContent = this.currentMessages.length > 0 && 
+            this.currentMessages.some(m => m !== '' && m !== null && m !== undefined);
+          
           this.bubble.style.transition = `opacity ${this.bubbleFadeDuration}ms ease`;
-          this.bubble.style.opacity = '1';
+          if (hasContent) {
+            this.bubble.style.opacity = '1';
+          } else {
+            this.bubble.style.opacity = '0';
+            this.bubble.style.pointerEvents = 'none';
+          }
           
           // Re-enable transitions after bubble fade completes
           setTimeout(() => {
@@ -744,9 +755,18 @@ class Pointy {
           this._startTracking();
           
           // Show bubble with fade after arriving at first target
+          // Show bubble with fade after arriving at first target (only if content is not empty)
           setTimeout(() => {
+            const hasContent = this.currentMessages.length > 0 && 
+              this.currentMessages.some(m => m !== '' && m !== null && m !== undefined);
+            
             this.bubble.style.transition = '';
-            this.bubble.style.opacity = '1';
+            if (hasContent) {
+              this.bubble.style.opacity = '1';
+            } else {
+              this.bubble.style.opacity = '0';
+              this.bubble.style.pointerEvents = 'none';
+            }
             
             // Start message cycle if multi-message
             if (this.messageInterval && this.currentMessages.length > 1 && !this._messageIntervalId) {
@@ -998,6 +1018,48 @@ class Pointy {
   }
 
   updateContent(newContent, animate = true) {
+    // Check if content is empty
+    const isEmpty = newContent === '' || newContent === null || newContent === undefined ||
+      (Array.isArray(newContent) && newContent.length === 0) ||
+      (Array.isArray(newContent) && newContent.every(m => m === '' || m === null || m === undefined));
+    
+    if (isEmpty) {
+      // Hide bubble when content is empty
+      this.bubble.style.opacity = '0';
+      this.bubble.style.pointerEvents = 'none';
+      return;
+    }
+    
+    // Track if bubble was hidden (needs special handling)
+    const wasHidden = this.bubble.style.opacity === '0';
+    
+    // Show bubble if it was hidden - need to make visible BEFORE measuring
+    if (wasHidden && this.isVisible) {
+      // Temporarily disable ALL transitions for instant position update
+      const oldBubbleTransition = this.bubble.style.transition;
+      const oldPointerTransition = this.pointer.style.transition;
+      this.bubble.style.transition = 'none';
+      this.pointer.style.transition = 'none';
+      
+      this.bubble.style.opacity = '1';
+      this.bubble.style.pointerEvents = '';
+      
+      // Force reflow to apply opacity
+      this.bubble.offsetHeight;
+      
+      // Update position with bubble visible (so offsetHeight works)
+      this.updatePosition();
+      
+      // Force another reflow to apply position
+      this.bubble.offsetHeight;
+      
+      // Re-enable transitions after a frame
+      requestAnimationFrame(() => {
+        this.bubble.style.transition = oldBubbleTransition;
+        this.pointer.style.transition = oldPointerTransition;
+      });
+    }
+    
     // Skip if content is the same (only for string content)
     if (typeof newContent === 'string' && this.bubbleText.innerHTML === newContent) {
       return;
@@ -1019,7 +1081,7 @@ class Pointy {
    * @param {boolean} fromStepChange - Whether this is from a step change (internal)
    * @private
    */
-  _setMessages(content, fromStepChange = false) {
+  _applyMessages(content, fromStepChange = false) {
     // Check if cycle was running before
     const wasRunning = this._messageIntervalId !== null;
     
@@ -1033,8 +1095,8 @@ class Pointy {
     // Show first message
     this.updateContent(this.currentMessages[0]);
     
-    // Only auto-start cycle on step changes, not on manual setContent
-    // For manual setContent, user must call resumeMessageCycle()
+    // Only auto-start cycle on step changes, not on manual setMessages
+    // For manual setMessages, user must call resumeMessageCycle()
     if (fromStepChange && this.messageInterval && this.currentMessages.length > 1) {
       this._startMessageCycle();
     } else if (wasRunning && this.currentMessages.length > 1) {
@@ -1244,16 +1306,41 @@ class Pointy {
   }
 
   /**
-   * Set content programmatically (replaces current messages)
+   * Set/update the current message (at current index)
+   * @param {string} message - New message content
+   * @param {boolean} animate - Whether to animate the change (default: true)
+   */
+  setMessage(message, animate = true) {
+    const oldMessage = this.currentMessages[this.currentMessageIndex];
+    this.currentMessages[this.currentMessageIndex] = message;
+    
+    this.updateContent(message, animate);
+    
+    // Ensure position is updated immediately for non-animated changes
+    if (!animate) {
+      this.updatePosition();
+    }
+    
+    this._emit('messageUpdate', {
+      index: this.currentMessageIndex,
+      message: message,
+      oldMessage: oldMessage,
+      total: this.currentMessages.length,
+      animated: animate
+    });
+  }
+
+  /**
+   * Set messages programmatically (replaces current messages)
    * @param {string|string[]} content - Single message or array of messages
    * @param {boolean} animate - Whether to animate the change (default: true)
    */
-  setContent(content, animate = true) {
+  setMessages(content, animate = true) {
     // Check if cycle was running before
     const wasRunning = this._messageIntervalId !== null;
     
     if (animate) {
-      this._setMessages(content, false); // false = not from step change
+      this._applyMessages(content, false); // false = not from step change
     } else {
       // Stop any existing auto-cycle
       this._stopMessageCycle();
@@ -1272,7 +1359,7 @@ class Pointy {
       }
     }
     
-    this._emit('contentSet', { 
+    this._emit('messagesSet', { 
       messages: this.currentMessages, 
       total: this.currentMessages.length,
       animated: animate,
@@ -1631,6 +1718,10 @@ class Pointy {
     // Set direction: step.direction can be 'up', 'down', or undefined (auto)
     this.manualDirection = step.direction || null;
     
+    // Reset velocity tracking for new target
+    this._targetYHistory = [];
+    this.lastTargetY = null;
+    
     // Pause floating animation during movement
     this.container.classList.add(this.classNames.moving);
     if (this.moveTimeout) clearTimeout(this.moveTimeout);
@@ -1658,7 +1749,7 @@ class Pointy {
     
     this._emit('move', { index: index, step: step });
     
-    this._setMessages(step.content, true); // true = from step change, auto-start cycle
+    this._applyMessages(step.content, true); // true = from step change, auto-start cycle
     this.targetElement = Pointy.getTargetElement(step.target);
     this.updatePosition();
     
@@ -1951,6 +2042,10 @@ class Pointy {
     // Set manual direction (null means auto)
     this.manualDirection = direction || null;
     
+    // Reset velocity tracking for new target
+    this._targetYHistory = [];
+    this.lastTargetY = null;
+    
     // Pause floating animation during movement
     this.container.classList.add(this.classNames.moving);
     if (this.moveTimeout) clearTimeout(this.moveTimeout);
@@ -1967,7 +2062,7 @@ class Pointy {
     this.targetElement = toTarget;
     
     if (content !== undefined) {
-      this._setMessages(content, false); // false = not from step change, don't auto-start cycle
+      this._applyMessages(content, false); // false = not from step change, don't auto-start cycle
     } else {
       // No new content - keep cycling if it was running
       // (cycle state is preserved)
@@ -2036,7 +2131,7 @@ class Pointy {
    * Content:
    * - messagesSet: When messages array is set for a step
    * - messageChange: When current message changes (next/prev message) - includes isAuto flag
-   * - contentSet: When setContent() is called
+   * - messagesSet: When setMessages() is called
    * - messageCycleStart: When auto message cycling starts
    * - messageCycleStop: When auto message cycling stops
    * - messageCyclePause: When message cycling is paused