@diabolic/pointy 1.2.0 → 1.3.0

package/README.md

@@ -80,20 +80,35 @@ Pointy supports multiple content formats:
 
 // HTML string with custom layout
 { target: '#el', content: `
-  <div style="display: flex; gap: 10px; align-items: flex-start; max-width: 260px; margin: 4px 0;">
+  <div style="display: flex; gap: 10px; align-items: flex-start; max-width: 260px;">
     <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
       <circle cx="12" cy="12" r="10"/>
       <path d="M12 16v-4M12 8h.01"/>
     </svg>
-    <span style="line-height: 1.4;">Custom tooltip with icon and flexible multi-line text layout!</span>
+    <span style="line-height: 1.4;">Custom tooltip with icon!</span>
   </div>
 ` }
 
-// Multiple messages (auto-cycles)
+// Multiple messages (auto-cycles with messageInterval)
 { target: '#el', content: ['First message', 'Second message', 'Third message'] }
 
-// React/JSX element (if using React)
-{ target: '#el', content: <MyCustomComponent /> }
+// React/JSX element (requires React & ReactDOM)
+{ target: '#el', content: (
+  <div style={{ display: 'flex', gap: '10px', alignItems: 'flex-start' }}>
+    <svg width={20} height={20} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+      <circle cx={12} cy={12} r={10} />
+      <path d="M12 16v-4" />
+    </svg>
+    <span>React element with SVG!</span>
+  </div>
+) }
+
+// Array of React elements
+{ target: '#el', content: [
+  <span>First React message</span>,
+  <strong>Second React message</strong>,
+  <em>Third React message</em>
+] }
 ```
 
 ### Direction Presets
@@ -123,7 +138,7 @@ pointy.setVerticalDirection('down');      // Only vertical
 pointy.setDirection(null);                // Reset to auto
 
 // pointTo with direction
-pointy.pointTo('#element', 'Message', 'down-left');
+pointy.pointTo('#element', 'Message', { direction: 'down-left' });
 ```
 
 ### Animation
@@ -216,10 +231,34 @@ pointy.goToMessage(index);
 
 ### Point to Custom Target
 
+Temporarily point to any element without changing the current step:
+
 ```javascript
+// Basic usage
 pointy.pointTo('#element');
 pointy.pointTo('#element', 'Custom message');
-pointy.pointTo('#element', 'Message', 'down');
+
+// With options
+pointy.pointTo('#element', 'Message', {
+  direction: 'down',      // 'up', 'down', 'left', 'right', 'up-left', etc.
+  autoplay: true,         // Auto-cycle through messages (if array)
+  interval: 2000,         // Message cycle interval in ms
+  cycle: true             // Loop messages (true) or stop at last (false)
+});
+
+// Array of messages with autoplay
+pointy.pointTo('#element', [
+  'First tip',
+  'Second tip', 
+  'Third tip'
+], { autoplay: true, interval: 2500 });
+
+// Stop at last message (no loop)
+pointy.pointTo('#element', ['Step 1', 'Step 2', 'Done!'], {
+  autoplay: true,
+  interval: 2000,
+  cycle: false  // Stops at 'Done!'
+});
 ```
 
 ### Autoplay Control
@@ -393,11 +432,11 @@ pointy.on('all', (data) => {
 #### Message Cycle
 | Event | Data |
 |-------|------|
-| `messageCycleStart` | `{ interval, totalMessages }` |
+| `messageCycleStart` | `{ interval, totalMessages, cycle }` |
 | `messageCycleStop` | `{ currentIndex }` |
 | `messageCyclePause` | `{ currentIndex }` |
 | `messageCycleResume` | `{ currentIndex }` |
-| `messageCycleComplete` | `{ stepIndex, totalMessages }` |
+| `messageCycleComplete` | `{ stepIndex?, totalMessages }` |
 
 #### Pointing
 | Event | Data |
@@ -566,6 +605,42 @@ tour.setPointerColor('#00ff88');
 tour.setBubbleBackgroundColor('#2d2d44');
 ```
 
+### React/JSX Content
+
+```jsx
+// With React loaded via CDN or bundler
+const tour = new Pointy({
+  steps: [{
+    target: '#feature',
+    content: (
+      <div style={{ display: 'flex', gap: '10px', alignItems: 'flex-start' }}>
+        <svg 
+          width={20} height={20} viewBox="0 0 24 24"
+          fill="none" stroke="currentColor" strokeWidth={2}
+          strokeLinecap="round" strokeLinejoin="round"
+        >
+          <path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z" />
+          <path d="M12 16v-4" />
+          <path d="M12 8h.01" />
+        </svg>
+        <span>React element with info icon!</span>
+      </div>
+    )
+  }]
+});
+
+tour.show();
+
+// Or with pointTo and autoplay
+const messages = [
+  <span>First tip</span>,
+  <strong>Important tip!</strong>,
+  <em>Final tip</em>
+];
+
+tour.pointTo('#element', messages, { autoplay: true, interval: 2000 });
+```
+
 ### Autoplay Tour
 
 ```javascript

package/dist/pointy.esm.js

@@ -1,6 +1,6 @@
 /**
  * Pointy - A lightweight tooltip library with animated pointer
- * @version 1.2.0
+ * @version 1.3.0
  * @license MIT
  */
 /**
@@ -434,19 +434,32 @@ class Pointy {
     if (content && typeof content === 'object' && content.$$typeof) {
       // React element - use ReactDOM if available
       if (typeof ReactDOM !== 'undefined' && ReactDOM.createRoot) {
-        // React 18+
-        const root = ReactDOM.createRoot(element);
-        root.render(content);
-        element._reactRoot = root;
+        // React 18+ - reuse existing root or create new one
+        let root = element._reactRoot;
+        if (!root) {
+          root = ReactDOM.createRoot(element);
+          element._reactRoot = root;
+        }
+        if (typeof ReactDOM.flushSync === 'function') {
+          ReactDOM.flushSync(() => {
+            root.render(content);
+          });
+        } else {
+          root.render(content);
+        }
       } else if (typeof ReactDOM !== 'undefined' && ReactDOM.render) {
-        // React 17 and below
+        // React 17 and below (already synchronous)
         ReactDOM.render(content, element);
       } else {
         console.warn('Pointy: React element passed but ReactDOM not found');
         element.innerHTML = String(content);
       }
     } else {
-      // String content - render as HTML
+      // String content - unmount React root if exists, then render as HTML
+      if (element._reactRoot) {
+        element._reactRoot.unmount();
+        element._reactRoot = null;
+      }
       element.innerHTML = content;
     }
   }
@@ -1310,6 +1323,45 @@ class Pointy {
     }
   }
 
+  /**
+   * Generate a stable key from React element content
+   * @param {object} element - React element
+   * @returns {string} - Stable key
+   * @private
+   */
+  static _generateReactKey(element) {
+    // Create a deterministic key from element type and props
+    const type = typeof element.type === 'function' 
+      ? element.type.name || 'Component'
+      : element.type || 'unknown';
+    
+    // Hash the props to create stable key (with fallback for circular refs)
+    let propsStr = '';
+    try {
+      propsStr = JSON.stringify(element.props, (key, value) => {
+        // Skip children, functions, and symbols for hashing
+        if (key === 'children' || typeof value === 'function' || typeof value === 'symbol') return undefined;
+        // Skip React elements in props (they have $$typeof symbol)
+        if (value && typeof value === 'object' && value.$$typeof) return '[ReactElement]';
+        return value;
+      }) || '';
+    } catch (e) {
+      // Fallback for circular references or other stringify errors
+      propsStr = String(Object.keys(element.props || {}).length);
+    }
+    
+    // Simple hash function
+    let hash = 0;
+    const str = type + propsStr;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash;
+    }
+    
+    return `pointy-${type}-${Math.abs(hash).toString(36)}`;
+  }
+
   /**
    * Set messages for current step (internal)
    * @param {string|string[]} content - Single message or array of messages
@@ -1323,8 +1375,27 @@ class Pointy {
     // Stop any existing auto-cycle
     this._stopMessageCycle();
     
-    // Normalize to array
-    this.currentMessages = Array.isArray(content) ? content : [content];
+    // Normalize to array and add keys to React elements if needed
+    let messages = Array.isArray(content) ? content : [content];
+    
+    // Auto-add keys to React elements in array (with collision handling)
+    if (typeof React !== 'undefined' && React.cloneElement && messages.length > 1) {
+      const keyCount = new Map();
+      messages = messages.map((msg) => {
+        // Check if it's a React element without a key
+        if (msg && typeof msg === 'object' && msg.$$typeof && msg.key == null) {
+          const baseKey = Pointy._generateReactKey(msg);
+          const count = keyCount.get(baseKey) || 0;
+          keyCount.set(baseKey, count + 1);
+          // Add suffix for duplicate keys
+          const finalKey = count > 0 ? `${baseKey}-${count}` : baseKey;
+          return React.cloneElement(msg, { key: finalKey });
+        }
+        return msg;
+      });
+    }
+    
+    this.currentMessages = messages;
     this.currentMessageIndex = 0;
     
     // Show first message
@@ -1348,27 +1419,40 @@ class Pointy {
 
   /**
    * Start auto-cycling through messages
+   * @param {number} customInterval - Optional custom interval (uses messageInterval if not provided)
+   * @param {boolean} shouldCycle - Whether to cycle back to first message (default: true)
    * @private
    */
-  _startMessageCycle() {
+  _startMessageCycle(customInterval, shouldCycle = true) {
+    const intervalToUse = customInterval || this.messageInterval;
     this._messagesCompletedForStep = false;
+    this._shouldCycleMessages = shouldCycle;
     this._messageIntervalId = setInterval(() => {
-      // Check if we're at the last message and autoplay is waiting for messages
+      // Check if we're at the last message
       const isLastMessage = this.currentMessageIndex === this.currentMessages.length - 1;
       
-      if (isLastMessage && this.autoplay && this.autoplayWaitForMessages) {
-        // Don't cycle back to first message - stop here and advance to next step
-        this._stopMessageCycle();
-        this._messagesCompletedForStep = true;
-        this._emit('messageCycleComplete', { stepIndex: this.currentStepIndex, totalMessages: this.currentMessages.length });
-        // Trigger autoplay advance after a brief pause
-        this._scheduleAutoplayAfterMessages();
+      if (isLastMessage) {
+        if (this.autoplay && this.autoplayWaitForMessages) {
+          // Don't cycle back to first message - stop here and advance to next step
+          this._stopMessageCycle();
+          this._messagesCompletedForStep = true;
+          this._emit('messageCycleComplete', { stepIndex: this.currentStepIndex, totalMessages: this.currentMessages.length });
+          // Trigger autoplay advance after a brief pause
+          this._scheduleAutoplayAfterMessages();
+        } else if (!this._shouldCycleMessages) {
+          // cycle: false - stop at last message
+          this._stopMessageCycle();
+          this._emit('messageCycleComplete', { totalMessages: this.currentMessages.length });
+        } else {
+          // Normal cycling - go back to first
+          this.nextMessage(true); // true = isAuto
+        }
       } else {
         // Normal message cycling
         this.nextMessage(true); // true = isAuto
       }
-    }, this.messageInterval);
-    this._emit('messageCycleStart', { interval: this.messageInterval, totalMessages: this.currentMessages.length });
+    }, intervalToUse);
+    this._emit('messageCycleStart', { interval: intervalToUse, totalMessages: this.currentMessages.length, cycle: shouldCycle });
   }
 
   /**
@@ -2459,10 +2543,19 @@ class Pointy {
    * Temporarily point to a target without changing the current step.
    * 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', 'left', 'right', 'up-left', 'down-right', etc. or null for auto
-   */
-  pointTo(target, content, direction) {
+   * @param {string|string[]|ReactElement|ReactElement[]} content - Optional content to show
+   * @param {Object} options - Options object
+   * @param {string} options.direction - Optional direction: 'up', 'down', 'left', 'right', 'up-left', 'down-right', etc. or null for auto
+   * @param {boolean} options.autoplay - Auto-cycle through messages if content is array (default: false)
+   * @param {number} options.interval - Message cycle interval in ms (uses default messageInterval if not specified)
+   * @param {boolean} options.cycle - Whether to cycle back to first message or stop at last (default: true)
+   */
+  pointTo(target, content, options = {}) {
+    const direction = options.direction || null;
+    const autoplay = options.autoplay === true;
+    const interval = options.interval || null;
+    const cycle = options.cycle !== false; // default true unless explicitly false
+    
     const previousTarget = this.targetElement;
     
     // Determine actual direction ('auto' means will be calculated in updatePosition)
@@ -2503,6 +2596,11 @@ class Pointy {
     
     if (content !== undefined) {
       this._applyMessages(content, false); // false = not from step change, don't auto-start cycle
+      
+      // If autoplay is enabled and we have multiple messages, start the cycle
+      if (autoplay && Array.isArray(content) && content.length > 1) {
+        this._startMessageCycle(interval, cycle);
+      }
     }
     
     this.updatePosition();

package/dist/pointy.js

@@ -1,6 +1,6 @@
 /**
  * Pointy - A lightweight tooltip library with animated pointer
- * @version 1.2.0
+ * @version 1.3.0
  * @license MIT
  */
 (function (global, factory) {
@@ -440,19 +440,32 @@
       if (content && typeof content === 'object' && content.$$typeof) {
         // React element - use ReactDOM if available
         if (typeof ReactDOM !== 'undefined' && ReactDOM.createRoot) {
-          // React 18+
-          const root = ReactDOM.createRoot(element);
-          root.render(content);
-          element._reactRoot = root;
+          // React 18+ - reuse existing root or create new one
+          let root = element._reactRoot;
+          if (!root) {
+            root = ReactDOM.createRoot(element);
+            element._reactRoot = root;
+          }
+          if (typeof ReactDOM.flushSync === 'function') {
+            ReactDOM.flushSync(() => {
+              root.render(content);
+            });
+          } else {
+            root.render(content);
+          }
         } else if (typeof ReactDOM !== 'undefined' && ReactDOM.render) {
-          // React 17 and below
+          // React 17 and below (already synchronous)
           ReactDOM.render(content, element);
         } else {
           console.warn('Pointy: React element passed but ReactDOM not found');
           element.innerHTML = String(content);
         }
       } else {
-        // String content - render as HTML
+        // String content - unmount React root if exists, then render as HTML
+        if (element._reactRoot) {
+          element._reactRoot.unmount();
+          element._reactRoot = null;
+        }
         element.innerHTML = content;
       }
     }
@@ -1316,6 +1329,45 @@
       }
     }
 
+    /**
+     * Generate a stable key from React element content
+     * @param {object} element - React element
+     * @returns {string} - Stable key
+     * @private
+     */
+    static _generateReactKey(element) {
+      // Create a deterministic key from element type and props
+      const type = typeof element.type === 'function' 
+        ? element.type.name || 'Component'
+        : element.type || 'unknown';
+      
+      // Hash the props to create stable key (with fallback for circular refs)
+      let propsStr = '';
+      try {
+        propsStr = JSON.stringify(element.props, (key, value) => {
+          // Skip children, functions, and symbols for hashing
+          if (key === 'children' || typeof value === 'function' || typeof value === 'symbol') return undefined;
+          // Skip React elements in props (they have $$typeof symbol)
+          if (value && typeof value === 'object' && value.$$typeof) return '[ReactElement]';
+          return value;
+        }) || '';
+      } catch (e) {
+        // Fallback for circular references or other stringify errors
+        propsStr = String(Object.keys(element.props || {}).length);
+      }
+      
+      // Simple hash function
+      let hash = 0;
+      const str = type + propsStr;
+      for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash;
+      }
+      
+      return `pointy-${type}-${Math.abs(hash).toString(36)}`;
+    }
+
     /**
      * Set messages for current step (internal)
      * @param {string|string[]} content - Single message or array of messages
@@ -1329,8 +1381,27 @@
       // Stop any existing auto-cycle
       this._stopMessageCycle();
       
-      // Normalize to array
-      this.currentMessages = Array.isArray(content) ? content : [content];
+      // Normalize to array and add keys to React elements if needed
+      let messages = Array.isArray(content) ? content : [content];
+      
+      // Auto-add keys to React elements in array (with collision handling)
+      if (typeof React !== 'undefined' && React.cloneElement && messages.length > 1) {
+        const keyCount = new Map();
+        messages = messages.map((msg) => {
+          // Check if it's a React element without a key
+          if (msg && typeof msg === 'object' && msg.$$typeof && msg.key == null) {
+            const baseKey = Pointy._generateReactKey(msg);
+            const count = keyCount.get(baseKey) || 0;
+            keyCount.set(baseKey, count + 1);
+            // Add suffix for duplicate keys
+            const finalKey = count > 0 ? `${baseKey}-${count}` : baseKey;
+            return React.cloneElement(msg, { key: finalKey });
+          }
+          return msg;
+        });
+      }
+      
+      this.currentMessages = messages;
       this.currentMessageIndex = 0;
       
       // Show first message
@@ -1354,27 +1425,40 @@
 
     /**
      * Start auto-cycling through messages
+     * @param {number} customInterval - Optional custom interval (uses messageInterval if not provided)
+     * @param {boolean} shouldCycle - Whether to cycle back to first message (default: true)
      * @private
      */
-    _startMessageCycle() {
+    _startMessageCycle(customInterval, shouldCycle = true) {
+      const intervalToUse = customInterval || this.messageInterval;
       this._messagesCompletedForStep = false;
+      this._shouldCycleMessages = shouldCycle;
       this._messageIntervalId = setInterval(() => {
-        // Check if we're at the last message and autoplay is waiting for messages
+        // Check if we're at the last message
         const isLastMessage = this.currentMessageIndex === this.currentMessages.length - 1;
         
-        if (isLastMessage && this.autoplay && this.autoplayWaitForMessages) {
-          // Don't cycle back to first message - stop here and advance to next step
-          this._stopMessageCycle();
-          this._messagesCompletedForStep = true;
-          this._emit('messageCycleComplete', { stepIndex: this.currentStepIndex, totalMessages: this.currentMessages.length });
-          // Trigger autoplay advance after a brief pause
-          this._scheduleAutoplayAfterMessages();
+        if (isLastMessage) {
+          if (this.autoplay && this.autoplayWaitForMessages) {
+            // Don't cycle back to first message - stop here and advance to next step
+            this._stopMessageCycle();
+            this._messagesCompletedForStep = true;
+            this._emit('messageCycleComplete', { stepIndex: this.currentStepIndex, totalMessages: this.currentMessages.length });
+            // Trigger autoplay advance after a brief pause
+            this._scheduleAutoplayAfterMessages();
+          } else if (!this._shouldCycleMessages) {
+            // cycle: false - stop at last message
+            this._stopMessageCycle();
+            this._emit('messageCycleComplete', { totalMessages: this.currentMessages.length });
+          } else {
+            // Normal cycling - go back to first
+            this.nextMessage(true); // true = isAuto
+          }
         } else {
           // Normal message cycling
           this.nextMessage(true); // true = isAuto
         }
-      }, this.messageInterval);
-      this._emit('messageCycleStart', { interval: this.messageInterval, totalMessages: this.currentMessages.length });
+      }, intervalToUse);
+      this._emit('messageCycleStart', { interval: intervalToUse, totalMessages: this.currentMessages.length, cycle: shouldCycle });
     }
 
     /**
@@ -2465,10 +2549,19 @@
      * Temporarily point to a target without changing the current step.
      * 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', 'left', 'right', 'up-left', 'down-right', etc. or null for auto
-     */
-    pointTo(target, content, direction) {
+     * @param {string|string[]|ReactElement|ReactElement[]} content - Optional content to show
+     * @param {Object} options - Options object
+     * @param {string} options.direction - Optional direction: 'up', 'down', 'left', 'right', 'up-left', 'down-right', etc. or null for auto
+     * @param {boolean} options.autoplay - Auto-cycle through messages if content is array (default: false)
+     * @param {number} options.interval - Message cycle interval in ms (uses default messageInterval if not specified)
+     * @param {boolean} options.cycle - Whether to cycle back to first message or stop at last (default: true)
+     */
+    pointTo(target, content, options = {}) {
+      const direction = options.direction || null;
+      const autoplay = options.autoplay === true;
+      const interval = options.interval || null;
+      const cycle = options.cycle !== false; // default true unless explicitly false
+      
       const previousTarget = this.targetElement;
       
       // Determine actual direction ('auto' means will be calculated in updatePosition)
@@ -2509,6 +2602,11 @@
       
       if (content !== undefined) {
         this._applyMessages(content, false); // false = not from step change, don't auto-start cycle
+        
+        // If autoplay is enabled and we have multiple messages, start the cycle
+        if (autoplay && Array.isArray(content) && content.length > 1) {
+          this._startMessageCycle(interval, cycle);
+        }
       }
       
       this.updatePosition();