@diabolic/pointy 1.1.0 → 1.2.0

package/dist/pointy.esm.js

@@ -1,6 +1,6 @@
 /**
  * Pointy - A lightweight tooltip library with animated pointer
- * @version 1.1.0
+ * @version 1.2.0
  * @license MIT
  */
 /**
@@ -26,6 +26,11 @@
  * - target {string|HTMLElement} - Initial target element
  * - content {string|string[]} - Initial content/messages (single-step use)
  * - zIndex {number} - CSS z-index for the container (default: 9999)
+ * - stayInViewport {boolean|object} - Auto-flip bubble to stay within viewport (default: true)
+ *   - true/false: Enable/disable with default thresholds (x: 40, y: 60)
+ *   - { x: number, y: number }: Enable with custom thresholds
+ *   - { x: number }: Enable with custom horizontal threshold only
+ *   - { y: number }: Enable with custom vertical threshold only
  * - 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)
@@ -49,6 +54,9 @@
  * - classNames {object} - Full override of class names
  * - cssVarPrefix {string} - CSS variable prefix (default: classPrefix)
  * - pointerSvg {string} - Custom SVG for pointer
+ * - bubbleBackgroundColor {string} - Custom bubble background color (default: '#0a1551')
+ * - bubbleTextColor {string} - Custom bubble text color (default: 'white')
+ * - bubbleMaxWidth {string} - Max width for bubble (default: '90vw')
  * - onStepChange {function} - Callback on step change
  * - onComplete {function} - Callback on tour complete
  * 
@@ -78,6 +86,11 @@
  * - moveComplete: Position update finished
  * - introAnimationStart: Initial fade-in animation started
  * - introAnimationEnd: Initial fade-in animation completed
+ * - flipHorizontal: Bubble flipped horizontally (left/right) due to viewport bounds
+ * - flipVertical: Bubble flipped vertically (up/down) due to viewport bounds
+ * - directionChange: Manual direction changed via setDirection()
+ * - horizontalDirectionChange: Horizontal direction changed via setHorizontalDirection()
+ * - verticalDirectionChange: Vertical direction changed via setVerticalDirection()
  * 
  * Content:
  * - messagesSet: Messages array replaced via setMessages() or setMessage()
@@ -142,9 +155,12 @@
  * 
  * Setters (all emit change events):
  * setEasing(), setAnimationDuration(), setIntroFadeDuration(), setBubbleFadeDuration(),
+ * setBubbleBackgroundColor(), setBubbleTextColor(), setBubbleMaxWidth(),
  * setMessageInterval(), setMessageTransitionDuration(), setOffset(), setZIndex(),
- * setResetOnComplete(), setFloatingAnimation(), setInitialPosition(), setInitialPositionOffset(),
- * setAutoplay(), setAutoplayWaitForMessages()
+ * setStayInViewport(enabled, thresholds?), setDirection(direction),
+ * setHorizontalDirection(direction), setVerticalDirection(direction),
+ * setResetOnComplete(), setFloatingAnimation(),
+ * setInitialPosition(), setInitialPositionOffset(), setAutoplay(), setAutoplayWaitForMessages()
  * 
  * Static Helpers:
  * - Pointy.renderContent(element, content) - Render string/JSX to element
@@ -174,7 +190,7 @@ class Pointy {
   static POINTER_SVG = `
     <svg xmlns="http://www.w3.org/2000/svg" width="33" height="33" fill="none" viewBox="0 0 33 33">
       <g filter="url(#pointy-shadow)">
-        <path fill="#0a1551" d="m18.65 24.262 6.316-14.905c.467-1.103-.645-2.215-1.748-1.747L8.313 13.925c-1.088.461-1.083 2.004.008 2.459l5.049 2.104c.325.135.583.393.718.718l2.104 5.049c.454 1.09 1.997 1.095 2.458.007"/>
+        <path fill="currentColor" d="m18.65 24.262 6.316-14.905c.467-1.103-.645-2.215-1.748-1.747L8.313 13.925c-1.088.461-1.083 2.004.008 2.459l5.049 2.104c.325.135.583.393.718.718l2.104 5.049c.454 1.09 1.997 1.095 2.458.007"/>
       </g>
       <defs>
         <filter id="pointy-shadow" width="32.576" height="32.575" x="0" y="0" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse">
@@ -253,6 +269,10 @@ class Pointy {
       --${vp}-duration: 1000ms;
       --${vp}-easing: cubic-bezier(0, 0.55, 0.45, 1);
       --${vp}-bubble-fade: 500ms;
+      --${vp}-bubble-bg: #0a1551;
+      --${vp}-bubble-color: white;
+      --${vp}-bubble-max-width: min(400px, 90vw);
+      --${vp}-pointer-color: #0a1551;
       transition: left var(--${vp}-duration) var(--${vp}-easing), top var(--${vp}-duration) var(--${vp}-easing), opacity 0.3s ease;
       animation: ${cn.container}-float 3s ease-in-out infinite;
     }
@@ -273,28 +293,32 @@ class Pointy {
     .${cn.pointer} {
       width: 33px;
       height: 33px;
-      transition: transform var(--${vp}-duration) var(--${vp}-easing);
+      color: var(--${vp}-pointer-color);
+      transition: transform var(--${vp}-duration) var(--${vp}-easing), color 0.3s ease;
     }
 
     .${cn.bubble} {
       position: absolute;
       right: 26px;
+      left: auto;
       top: 0;
-      background: #0a1551;
-      color: white;
+      background: var(--${vp}-bubble-bg);
+      color: var(--${vp}-bubble-color);
       padding: 4px 12px;
       border-radius: 14px;
       font-size: 14px;
       line-height: 20px;
       font-weight: 400;
       box-shadow: 0 4px 15px rgba(0, 0, 0, 0.25);
-      white-space: nowrap;
+      width: max-content;
+      max-width: var(--${vp}-bubble-max-width);
       overflow: hidden;
-      transition: width 0.5s cubic-bezier(0.4, 0, 0.2, 1), height 0.5s cubic-bezier(0.4, 0, 0.2, 1), transform var(--${vp}-duration) var(--${vp}-easing), opacity var(--${vp}-bubble-fade) ease;
+      transition: width 0.3s cubic-bezier(0.4, 0, 0.2, 1), height 0.3s cubic-bezier(0.4, 0, 0.2, 1), transform var(--${vp}-duration) var(--${vp}-easing), opacity var(--${vp}-bubble-fade) ease, left var(--${vp}-duration) var(--${vp}-easing), right var(--${vp}-duration) var(--${vp}-easing), background 0.3s ease, color 0.3s ease;
     }
 
     .${cn.bubbleText} {
-      display: inline-block;
+      display: block;
+      word-break: break-word;
     }
   `;
   }
@@ -334,16 +358,20 @@ class Pointy {
   static animateText(element, newContent, duration = 500, bubble = null, onComplete = null) {
     const hideTime = duration * 0.4;
     const revealTime = duration * 0.6;
+    const resizeTime = 300; // Match CSS transition
     
     // Measure new content dimensions using a hidden container
     let newWidth = null;
     let newHeight = null;
     if (bubble) {
+      // Get bubble's max-width for proper measurement of multi-line content
+      const bubbleStyles = window.getComputedStyle(bubble);
+      const maxWidth = bubbleStyles.maxWidth;
+      
       const measureDiv = document.createElement('div');
-      measureDiv.style.cssText = 'visibility: hidden; position: absolute; padding: 4px 12px;';
+      measureDiv.style.cssText = `visibility: hidden; position: absolute; padding: 4px 12px; width: max-content; max-width: ${maxWidth};`;
       Pointy.renderContent(measureDiv, newContent);
       bubble.appendChild(measureDiv);
-      // Add horizontal padding (12px left + 12px right = 24px)
       newWidth = measureDiv.offsetWidth;
       newHeight = measureDiv.offsetHeight;
       bubble.removeChild(measureDiv);
@@ -353,22 +381,26 @@ class Pointy {
       const currentHeight = bubble.offsetHeight;
       bubble.style.width = currentWidth + 'px';
       bubble.style.height = currentHeight + 'px';
+      
+      // Force reflow
+      bubble.offsetHeight;
+      
+      // Start resizing bubble to new size immediately
+      bubble.style.width = newWidth + 'px';
+      bubble.style.height = newHeight + 'px';
     }
     
     // Phase 1: Hide old text (clip from left, disappears to right)
     element.style.transition = `clip-path ${hideTime}ms ease-in`;
     element.style.clipPath = 'inset(0 0 0 100%)';
     
+    // Wait for bubble resize AND text hide, then change content
+    const contentChangeDelay = Math.max(hideTime, resizeTime);
+    
     setTimeout(() => {
-      // Change content while fully clipped
+      // Change content while fully clipped AND bubble is at new size
       Pointy.renderContent(element, newContent);
       
-      // Animate bubble to new size
-      if (bubble && newWidth !== null) {
-        bubble.style.width = newWidth + 'px';
-        bubble.style.height = newHeight + 'px';
-      }
-      
       // Prepare for reveal (start fully clipped from right)
       element.style.transition = 'none';
       element.style.clipPath = 'inset(0 100% 0 0)';
@@ -380,16 +412,16 @@ class Pointy {
       element.style.transition = `clip-path ${revealTime}ms ease-out`;
       element.style.clipPath = 'inset(0 0 0 0)';
       
-      // Clear dimensions after transition so it can auto-size
+      // Clear explicit dimensions after reveal so bubble can auto-size
       if (bubble) {
         setTimeout(() => {
           bubble.style.width = '';
           bubble.style.height = '';
-        }, revealTime + 100);
+        }, revealTime + 50);
       }
       
       if (onComplete) onComplete();
-    }, hideTime);
+    }, contentChangeDelay);
   }
 
   /**
@@ -441,6 +473,18 @@ class Pointy {
 
     this.steps = options.steps || [];
     this.zIndex = options.zIndex !== undefined ? options.zIndex : 9999; // CSS z-index
+    
+    // stayInViewport: boolean or { x?: number, y?: number }
+    this.viewportThresholdX = 40; // Default horizontal margin
+    this.viewportThresholdY = 60; // Default vertical margin
+    if (typeof options.stayInViewport === 'object' && options.stayInViewport !== null) {
+      this.stayInViewport = true;
+      if (options.stayInViewport.x !== undefined) this.viewportThresholdX = options.stayInViewport.x;
+      if (options.stayInViewport.y !== undefined) this.viewportThresholdY = options.stayInViewport.y;
+    } else {
+      this.stayInViewport = options.stayInViewport !== undefined ? options.stayInViewport : true;
+    }
+    
     this.offsetX = options.offsetX !== undefined ? options.offsetX : 20;
     this.offsetY = options.offsetY !== undefined ? options.offsetY : 16;
     this.tracking = options.tracking !== undefined ? options.tracking : true; // Enable/disable position tracking
@@ -460,6 +504,10 @@ class Pointy {
     this.autoplayWaitForMessages = options.autoplayWaitForMessages !== undefined ? options.autoplayWaitForMessages : true; // Wait for all messages before advancing
     this.hideOnComplete = options.hideOnComplete !== undefined ? options.hideOnComplete : true; // Auto-hide after tour completes
     this.hideOnCompleteDelay = options.hideOnCompleteDelay !== undefined ? options.hideOnCompleteDelay : null; // Delay before hide (null = use animationDuration)
+    this.bubbleBackgroundColor = options.bubbleBackgroundColor || null; // Custom bubble background color
+    this.bubbleTextColor = options.bubbleTextColor || null; // Custom bubble text color
+    this.bubbleMaxWidth = options.bubbleMaxWidth || null; // Max width for bubble (default: min(400px, 90vw))
+    this.pointerColor = options.pointerColor || null; // Custom pointer/cursor color
     this._autoplayTimeoutId = null;
     this._autoplayPaused = false;
     this._messagesCompletedForStep = false; // Track if all messages have been shown
@@ -478,10 +526,16 @@ class Pointy {
     this._messageIntervalId = null;
     this.isVisible = false;
     this.isPointingUp = true;  // Always start pointing up
+    this.isPointingLeft = true; // Pointer on left side of target (bubble on right)
     this.lastTargetY = null;
     this._targetYHistory = []; // Track Y positions for velocity detection
     this._lastDirectionChangeTime = 0; // Debounce direction changes
-    this.manualDirection = null; // 'up', 'down', or null (auto)
+    this.manualHorizontalDirection = null; // 'left', 'right', or null (auto)
+    this.manualVerticalDirection = null; // 'up', 'down', or null (auto)
+    this._autoDirectionLocked = false; // Lock auto-direction after first calculation per target
+    this._lastTargetElement = null; // Track target changes to recalculate direction
+    this._bubbleConstraintApplied = false; // Track if bubble constraint has been calculated
+    this._cachedBubbleNaturalWidth = null; // Cache bubble's natural width before constraint
     this.moveTimeout = null;
     this._hasShownBefore = false; // For intro animation
 
@@ -498,6 +552,20 @@ class Pointy {
     this.container.style.setProperty(`--${this.cssVarPrefix}-easing`, this._resolveEasing(this.easing));
     this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-fade`, `${this.bubbleFadeDuration}ms`);
     
+    // Apply custom bubble colors if provided
+    if (this.bubbleBackgroundColor) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-bg`, this.bubbleBackgroundColor);
+    }
+    if (this.bubbleTextColor) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-color`, this.bubbleTextColor);
+    }
+    if (this.bubbleMaxWidth) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-max-width`, this.bubbleMaxWidth);
+    }
+    if (this.pointerColor) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-pointer-color`, this.pointerColor);
+    }
+    
     // Apply floating animation setting
     if (!this.floatingAnimation) {
       this.container.style.animationPlayState = 'paused';
@@ -585,10 +653,19 @@ class Pointy {
     const targetRect = this.targetElement.getBoundingClientRect();
     const scrollX = window.scrollX;
     const scrollY = window.scrollY;
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    this.bubble.offsetWidth || 100;
+    const bubbleHeight = this.bubble.offsetHeight || 28;
+
+    // Manual horizontal direction takes priority
+    if (this.manualHorizontalDirection !== null) {
+      this.isPointingLeft = this.manualHorizontalDirection === 'left';
+    }
 
-    // Manual direction takes priority
-    if (this.manualDirection !== null) {
-      this.isPointingUp = this.manualDirection === 'up';
+    // Manual vertical direction takes priority
+    if (this.manualVerticalDirection !== null) {
+      this.isPointingUp = this.manualVerticalDirection === 'up';
     } else {
       // Auto: Track velocity over time to detect movement direction
       const currentTargetY = targetRect.top + scrollY;
@@ -624,32 +701,179 @@ class Pointy {
       this.lastTargetY = currentTargetY;
     }
 
+    // Check if target changed - if so, unlock auto direction and bubble constraint
+    if (this._lastTargetElement !== this.targetElement) {
+      this._autoDirectionLocked = false;
+      this._bubbleConstraintApplied = false;
+      this._cachedBubbleNaturalWidth = null;
+      this.bubble.style.maxWidth = ''; // Reset constraint for new target
+      this._lastTargetElement = this.targetElement;
+    }
+
+    // Stay in viewport: calculate optimal direction ONCE per target, then lock it
+    // This prevents flip-flopping during animations and tracking
+    if (this.stayInViewport && !this._autoDirectionLocked) {
+      const prevIsPointingLeft = this.isPointingLeft;
+      const prevIsPointingUp = this.isPointingUp;
+      
+      // Horizontal direction (only if not manually set)
+      if (this.manualHorizontalDirection === null) {
+        // Calculate available space on each side
+        const spaceOnLeft = targetRect.left - this.viewportThresholdX;
+        const spaceOnRight = viewportWidth - targetRect.right - this.viewportThresholdX;
+        
+        // Pick the side with more space
+        // Add a small preference for left (default) when spaces are similar
+        const leftPreference = 20;
+        this.isPointingLeft = spaceOnLeft + leftPreference >= spaceOnRight;
+      }
+
+      // Vertical direction (only if not manually set)
+      if (this.manualVerticalDirection === null) {
+        // Calculate available space above and below
+        const spaceBelow = viewportHeight - targetRect.bottom - this.viewportThresholdY;
+        const spaceAbove = targetRect.top - this.viewportThresholdY;
+        
+        // Pick the side with more space, slight preference for below (pointing up)
+        const belowPreference = 10;
+        this.isPointingUp = spaceBelow + belowPreference >= spaceAbove;
+      }
+      
+      // Lock direction - won't recalculate until target changes
+      this._autoDirectionLocked = true;
+      
+      // Emit flip events if direction changed
+      if (prevIsPointingLeft !== this.isPointingLeft) {
+        this._emit('flipHorizontal', { 
+          from: prevIsPointingLeft ? 'left' : 'right', 
+          to: this.isPointingLeft ? 'left' : 'right' 
+        });
+      }
+      if (prevIsPointingUp !== this.isPointingUp) {
+        this._emit('flipVertical', { 
+          from: prevIsPointingUp ? 'up' : 'down', 
+          to: this.isPointingUp ? 'up' : 'down' 
+        });
+      }
+    }
+
     // Pointer tip position varies based on rotation
     // Default SVG (0deg): tip at approximately (25, 8) - points top-right
     // Rotated 90deg: tip at approximately (25, 25) - points bottom-right
+    // Rotated -90deg (270deg): points top-left (flipped horizontally via rotation)
     let left, top;
-
-    if (this.isPointingUp) {
-      // Pointer points up (default): pointer's top-right → target's bottom-left
-      this.pointer.style.transform = 'rotate(0deg)';
-      left = targetRect.left + scrollX - 25 + this.offsetX;
-      top = targetRect.bottom + scrollY - 8 - this.offsetY;
-      
-      // Bubble: below pointer
-      this.bubble.style.transform = 'translateY(28px)';
+    let pointerRotation;
+    let bubbleTransform;
+
+    if (this.isPointingLeft) {
+      // Pointer on LEFT side of target, bubble extends to the LEFT
+      if (this.isPointingUp) {
+        pointerRotation = 'rotate(0deg)';
+        left = targetRect.left + scrollX - 25 + this.offsetX;
+        top = targetRect.bottom + scrollY - 8 - this.offsetY;
+        bubbleTransform = 'translateY(28px)';
+      } else {
+        pointerRotation = 'rotate(90deg)';
+        left = targetRect.left + scrollX - 25 + this.offsetX;
+        top = targetRect.top + scrollY - 25 + this.offsetY;
+        bubbleTransform = `translateY(-${bubbleHeight}px)`;
+      }
+      // Bubble position: right of pointer (default CSS)
+      this.bubble.style.right = '26px';
+      this.bubble.style.left = 'auto';
     } else {
-      // Pointer points down (90deg): pointer's bottom-right → target's top-left
-      this.pointer.style.transform = 'rotate(90deg)';
-      left = targetRect.left + scrollX - 25 + this.offsetX;
-      top = targetRect.top + scrollY - 25 + this.offsetY;
-      
-      // Bubble: above pointer
-      const bubbleHeight = this.bubble.offsetHeight || 28;
-      this.bubble.style.transform = `translateY(-${bubbleHeight}px)`;
+      // Pointer on RIGHT side of target, bubble extends to the RIGHT
+      if (this.isPointingUp) {
+        // Rotate -90deg to point top-left instead of top-right
+        pointerRotation = 'rotate(-90deg)';
+        left = targetRect.right + scrollX - 8 - this.offsetX;
+        top = targetRect.bottom + scrollY - 25 - this.offsetY;
+        bubbleTransform = 'translateY(28px)';
+      } else {
+        // Rotate 180deg to point bottom-left
+        pointerRotation = 'rotate(180deg)';
+        left = targetRect.right + scrollX - 8 - this.offsetX;
+        top = targetRect.top + scrollY - 8 + this.offsetY;
+        bubbleTransform = `translateY(-${bubbleHeight}px)`;
+      }
+      // Bubble position: left of pointer (flipped)
+      this.bubble.style.left = '26px';
+      this.bubble.style.right = 'auto';
     }
 
+    this.pointer.style.transform = pointerRotation;
+    this.bubble.style.transform = bubbleTransform;
+    
+    // Clamp container position to keep pointer visible in viewport
+    const minLeft = scrollX + 8;
+    const maxLeft = scrollX + viewportWidth - 40;
+    left = Math.max(minLeft, Math.min(left, maxLeft));
+    
     this.container.style.left = `${left}px`;
     this.container.style.top = `${top}px`;
+    
+    // Ensure bubble doesn't overflow viewport horizontally
+    // Pass the viewport-relative position for constraint calculation
+    const viewportLeft = left - scrollX;
+    this._constrainBubbleToViewport(viewportLeft, viewportWidth);
+  }
+
+  /**
+   * Constrain bubble width and position to prevent horizontal viewport overflow
+   * @private
+   */
+  _constrainBubbleToViewport(containerLeft, viewportWidth) {
+    // Only calculate constraint once per target to prevent oscillation
+    if (this._bubbleConstraintApplied) return;
+    
+    const padding = 8; // Minimum padding from viewport edge
+    
+    // Temporarily remove any existing constraint to measure natural width
+    const previousMaxWidth = this.bubble.style.maxWidth;
+    this.bubble.style.maxWidth = '';
+    
+    // Force layout reflow to get accurate measurement
+    const bubbleNaturalWidth = this.bubble.offsetWidth || 100;
+    
+    // Cache the natural width
+    this._cachedBubbleNaturalWidth = bubbleNaturalWidth;
+    
+    let needsConstraint = false;
+    let constrainedWidth = 0;
+    
+    if (this.isPointingLeft) {
+      // Bubble extends to the left of pointer
+      // Bubble's left edge = containerLeft - bubbleWidth + 26 (right offset of bubble)
+      const bubbleLeftEdge = containerLeft - bubbleNaturalWidth + 26;
+      
+      if (bubbleLeftEdge < padding) {
+        // Bubble would overflow left edge - constrain its width
+        const availableWidth = containerLeft + 26 - padding;
+        constrainedWidth = Math.max(availableWidth, 80);
+        needsConstraint = true;
+      }
+    } else {
+      // Bubble extends to the right of pointer
+      // Bubble's right edge = containerLeft + 26 + bubbleWidth
+      const bubbleRightEdge = containerLeft + 26 + bubbleNaturalWidth;
+      
+      if (bubbleRightEdge > viewportWidth - padding) {
+        // Bubble would overflow right edge - constrain its width
+        const availableWidth = viewportWidth - containerLeft - 26 - padding;
+        constrainedWidth = Math.max(availableWidth, 80);
+        needsConstraint = true;
+      }
+    }
+    
+    if (needsConstraint) {
+      this.bubble.style.maxWidth = `${constrainedWidth}px`;
+    } else {
+      // Restore previous or let CSS variable handle it
+      this.bubble.style.maxWidth = previousMaxWidth || '';
+    }
+    
+    // Mark constraint as applied for this target
+    this._bubbleConstraintApplied = true;
   }
 
   show() {
@@ -936,6 +1160,10 @@ class Pointy {
       this.currentMessages = Array.isArray(firstStep.content) ? firstStep.content : [firstStep.content];
       this.currentMessageIndex = 0;
       Pointy.renderContent(this.bubbleText, this.currentMessages[0]);
+      this._autoDirectionLocked = false; // Unlock direction for recalculation
+      this._bubbleConstraintApplied = false;
+      this._cachedBubbleNaturalWidth = null;
+      this.bubble.style.maxWidth = '';
     }
     
     // After animation completes
@@ -1421,6 +1649,113 @@ class Pointy {
     this._emit('zIndexChange', { from: oldValue, to: zIndex });
   }
 
+  /**
+   * Set stayInViewport enabled/disabled with optional thresholds
+   * @param {boolean} enabled - Whether stayInViewport is enabled
+   * @param {object} [thresholds] - Optional threshold values { x?: number, y?: number }
+   */
+  setStayInViewport(enabled, thresholds) {
+    const oldEnabled = this.stayInViewport;
+    const oldX = this.viewportThresholdX;
+    const oldY = this.viewportThresholdY;
+    
+    this.stayInViewport = enabled;
+    
+    // Update thresholds if provided
+    if (thresholds && typeof thresholds === 'object') {
+      if (thresholds.x !== undefined) this.viewportThresholdX = thresholds.x;
+      if (thresholds.y !== undefined) this.viewportThresholdY = thresholds.y;
+    }
+    
+    // Reset to default positions if disabling
+    if (!enabled) {
+      this.isPointingLeft = true;
+      this.isPointingUp = true;
+    }
+    
+    this.updatePosition();
+    this._emit('stayInViewportChange', { 
+      from: { enabled: oldEnabled, x: oldX, y: oldY }, 
+      to: { enabled, x: this.viewportThresholdX, y: this.viewportThresholdY } 
+    });
+  }
+
+  /**
+   * Parse direction string into horizontal and vertical components
+   * @private
+   * @param {string|null} direction - Direction string like 'up', 'left', 'up-left', 'down-right', etc.
+   */
+  _parseDirection(direction) {
+    if (!direction) {
+      this.manualHorizontalDirection = null;
+      this.manualVerticalDirection = null;
+      return;
+    }
+    
+    const dir = direction.toLowerCase();
+    
+    // Parse horizontal component
+    if (dir.includes('left')) {
+      this.manualHorizontalDirection = 'left';
+    } else if (dir.includes('right')) {
+      this.manualHorizontalDirection = 'right';
+    } else {
+      this.manualHorizontalDirection = null;
+    }
+    
+    // Parse vertical component
+    if (dir.includes('up')) {
+      this.manualVerticalDirection = 'up';
+    } else if (dir.includes('down')) {
+      this.manualVerticalDirection = 'down';
+    } else {
+      this.manualVerticalDirection = null;
+    }
+  }
+
+  /**
+   * Set the pointer direction manually
+   * @param {string|null} direction - Direction: 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right', or null for auto
+   */
+  setDirection(direction) {
+    const oldH = this.manualHorizontalDirection;
+    const oldV = this.manualVerticalDirection;
+    
+    this._parseDirection(direction);
+    
+    this.updatePosition();
+    this._emit('directionChange', { 
+      from: { horizontal: oldH, vertical: oldV }, 
+      to: { horizontal: this.manualHorizontalDirection, vertical: this.manualVerticalDirection } 
+    });
+  }
+
+  /**
+   * Set only the horizontal direction
+   * @param {string|null} direction - 'left', 'right', or null for auto
+   */
+  setHorizontalDirection(direction) {
+    const oldValue = this.manualHorizontalDirection;
+    if (oldValue === direction) return;
+    
+    this.manualHorizontalDirection = direction;
+    this.updatePosition();
+    this._emit('horizontalDirectionChange', { from: oldValue, to: direction });
+  }
+
+  /**
+   * Set only the vertical direction
+   * @param {string|null} direction - 'up', 'down', or null for auto
+   */
+  setVerticalDirection(direction) {
+    const oldValue = this.manualVerticalDirection;
+    if (oldValue === direction) return;
+    
+    this.manualVerticalDirection = direction;
+    this.updatePosition();
+    this._emit('verticalDirectionChange', { from: oldValue, to: direction });
+  }
+
   setOffset(offsetX, offsetY) {
     const oldOffsetX = this.offsetX;
     const oldOffsetY = this.offsetY;
@@ -1470,6 +1805,74 @@ class Pointy {
     this._emit('bubbleFadeDurationChange', { from: oldDuration, to: duration });
   }
 
+  /**
+   * Set the bubble background color
+   * @param {string} color - CSS color value (hex, rgb, etc.)
+   */
+  setBubbleBackgroundColor(color) {
+    const oldColor = this.bubbleBackgroundColor;
+    if (oldColor === color) return;
+    
+    this.bubbleBackgroundColor = color;
+    if (color) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-bg`, color);
+    } else {
+      this.container.style.removeProperty(`--${this.cssVarPrefix}-bubble-bg`);
+    }
+    this._emit('bubbleBackgroundColorChange', { from: oldColor, to: color });
+  }
+
+  /**
+   * Set the bubble text color
+   * @param {string} color - CSS color value (hex, rgb, etc.)
+   */
+  setBubbleTextColor(color) {
+    const oldColor = this.bubbleTextColor;
+    if (oldColor === color) return;
+    
+    this.bubbleTextColor = color;
+    if (color) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-color`, color);
+    } else {
+      this.container.style.removeProperty(`--${this.cssVarPrefix}-bubble-color`);
+    }
+    this._emit('bubbleTextColorChange', { from: oldColor, to: color });
+  }
+
+  /**
+   * Set the bubble max width
+   * @param {string} width - CSS width value (e.g., '90vw', '300px')
+   */
+  setBubbleMaxWidth(width) {
+    const oldWidth = this.bubbleMaxWidth;
+    if (oldWidth === width) return;
+    
+    this.bubbleMaxWidth = width;
+    if (width) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-bubble-max-width`, width);
+    } else {
+      this.container.style.removeProperty(`--${this.cssVarPrefix}-bubble-max-width`);
+    }
+    this._emit('bubbleMaxWidthChange', { from: oldWidth, to: width });
+  }
+
+  /**
+   * Set the pointer/cursor color
+   * @param {string} color - CSS color value (hex, rgb, etc.)
+   */
+  setPointerColor(color) {
+    const oldColor = this.pointerColor;
+    if (oldColor === color) return;
+    
+    this.pointerColor = color;
+    if (color) {
+      this.container.style.setProperty(`--${this.cssVarPrefix}-pointer-color`, color);
+    } else {
+      this.container.style.removeProperty(`--${this.cssVarPrefix}-pointer-color`);
+    }
+    this._emit('pointerColorChange', { from: oldColor, to: color });
+  }
+
   /**
    * Get the initial position coordinates based on initialPosition setting
    * @returns {{x: number, y: number, isPointingUp?: boolean}} - Position coordinates and optional direction
@@ -1744,12 +2147,16 @@ class Pointy {
       fromTarget: previousTarget
     });
     
-    // Set direction: step.direction can be 'up', 'down', or undefined (auto)
-    this.manualDirection = step.direction || null;
+    // Parse direction: can be 'up', 'down', 'left', 'right', 'up-left', 'down-right', etc.
+    this._parseDirection(step.direction);
     
-    // Reset velocity tracking for new target
+    // Reset velocity tracking and direction lock for new target
     this._targetYHistory = [];
     this.lastTargetY = null;
+    this._autoDirectionLocked = false;
+    this._bubbleConstraintApplied = false;
+    this._cachedBubbleNaturalWidth = null;
+    this.bubble.style.maxWidth = '';
     
     // Pause floating animation during movement
     this.container.classList.add(this.classNames.moving);
@@ -2053,7 +2460,7 @@ class Pointy {
    * When next() is called, it will continue from where it left off.
    * @param {string|HTMLElement} target - The target element or selector
    * @param {string} content - Optional content to show
-   * @param {string} direction - Optional direction: 'up', 'down', or null for auto
+   * @param {string} direction - Optional direction: 'up', 'down', 'left', 'right', 'up-left', 'down-right', etc. or null for auto
    */
   pointTo(target, content, direction) {
     const previousTarget = this.targetElement;
@@ -2068,12 +2475,16 @@ class Pointy {
       fromTarget: previousTarget
     });
     
-    // Set manual direction (null means auto)
-    this.manualDirection = direction || null;
+    // Parse direction (null means auto)
+    this._parseDirection(direction);
     
-    // Reset velocity tracking for new target
+    // Reset velocity tracking and direction lock for new target
     this._targetYHistory = [];
     this.lastTargetY = null;
+    this._autoDirectionLocked = false;
+    this._bubbleConstraintApplied = false;
+    this._cachedBubbleNaturalWidth = null;
+    this.bubble.style.maxWidth = '';
     
     // Pause floating animation during movement
     this.container.classList.add(this.classNames.moving);