@aladinbs/react-guided-tour 1.0.3 → 1.1.0

package/README.md

@@ -12,6 +12,8 @@ A modern, flexible React TypeScript tour guide library with advanced highlightin
 - 💾 **State Persistence** - localStorage integration to remember tour completion and progress
 - ⚡ **Performance Optimized** - Framework-agnostic core with efficient React integration
 - 🎪 **Action System** - Automated interactions (clicks, navigation, tab switching)
+- 🔒 **Interaction Blocking** - Prevent user interactions outside the tour target for focused guidance
+- 👆 **Click-to-Advance** - Allow users to click target elements directly to advance tour steps
 - 🔄 **Event System** - Rich event hooks for tour lifecycle management
 - 🎯 **TypeScript First** - Full type safety with comprehensive type definitions
 
@@ -141,6 +143,8 @@ interface TourConfig {
   onStepChange?: (step: TourStep, index: number) => void;
   allowKeyboardNavigation?: boolean;  // Enable keyboard controls
   allowClickOutside?: boolean;        // Allow clicking outside to close
+  blockInteractions?: boolean;        // Block interactions outside tour target
+  clickToAdvance?: boolean;           // Enable click-to-advance globally
   showProgress?: boolean;             // Show step progress indicator
   storage?: {
     key?: string;               // localStorage key (default: 'tour-{id}')
@@ -168,6 +172,8 @@ interface TourStep {
   canSkip?: boolean;            // Allow skipping this step
   waitForElement?: boolean;     // Wait for target element to appear
   waitTimeout?: number;         // Timeout for element waiting (ms)
+  blockInteractions?: boolean;  // Override global interaction blocking for this step
+  clickToAdvance?: boolean;     // Override global click-to-advance for this step
 }
 ```
 
@@ -279,6 +285,92 @@ Navigate through multi-step wizards:
 }
 ```
 
+### Interaction Blocking
+
+Control user interactions during the tour to create focused guidance experiences:
+
+```tsx
+const tourConfig: TourConfig = {
+  id: 'focused-tour',
+  blockInteractions: true,  // Block interactions globally
+  steps: [
+    {
+      id: 'step1',
+      title: 'Focused Step',
+      content: 'Users can only interact with the highlighted element.',
+      target: '#important-button',
+      blockInteractions: true,  // Enforce blocking for this step
+    },
+    {
+      id: 'step2', 
+      title: 'Free Interaction',
+      content: 'Users can click anywhere during this step.',
+      target: '#another-element',
+      blockInteractions: false, // Override global setting for this step
+    },
+  ],
+};
+```
+
+**Features:**
+- **Global Control**: Set `blockInteractions: true` in tour config to block interactions for all steps
+- **Per-Step Override**: Use `blockInteractions` in individual steps to override the global setting
+- **Visual Feedback**: Shows a "🔒 Interactions blocked" indicator when active
+- **Smart Targeting**: Only the highlighted element and tour UI remain interactive
+- **Keyboard Blocking**: Prevents keyboard interactions except tour navigation keys
+
+**When to use:**
+- Complex interfaces where users might get distracted
+- Critical onboarding flows that must be completed in order
+- Preventing accidental clicks that could break the tour flow
+- Ensuring users focus on specific elements
+
+### Click-to-Advance
+
+Enable users to interact directly with tour target elements to advance to the next step:
+
+```tsx
+const tourConfig: TourConfig = {
+  id: "interactive-tour",
+  clickToAdvance: true,  // Enable globally
+  steps: [
+    {
+      id: "button-interaction",
+      title: "Try the Button",
+      content: "Click the button below to continue the tour!",
+      target: "#my-button",
+      clickToAdvance: true,  // Enable for this step
+    },
+    {
+      id: "form-interaction", 
+      title: "Fill the Form",
+      content: "Complete this form field to proceed.",
+      target: "#email-input",
+      clickToAdvance: false, // Disable for this step (use Next button)
+    },
+  ],
+};
+```
+
+**Features:**
+- **Global Control**: Set `clickToAdvance: true` in tour config to enable for all steps
+- **Per-Step Override**: Use `clickToAdvance` in individual steps to override the global setting
+- **Smart UI**: Next button is automatically hidden when click-to-advance is active
+- **Visual Guidance**: Shows "👆 Click the highlighted element to continue" instruction
+- **Event Handling**: Automatically captures clicks on target elements and advances tour
+
+**When to use:**
+- Interactive tutorials where users need to practice using actual UI elements
+- Onboarding flows for buttons, forms, and interactive components
+- Training scenarios where clicking the real element is part of the learning
+- Reducing cognitive load by eliminating the need to find the Next button
+
+**Best practices:**
+- Use for clickable elements like buttons, links, and form controls
+- Combine with `blockInteractions: true` to ensure users click the right element
+- Provide clear instructions in the step content about what to click
+- Consider accessibility - ensure target elements are keyboard accessible
+
 ### Custom Integrations
 
 Extend the tour system with custom integrations:

package/dist/components/TourOverlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TourOverlay.d.ts","sourceRoot":"","sources":["../../src/components/TourOverlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+B,MAAM,OAAO,CAAC;AAIpD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,8CA4EtB,CAAC"}
+{"version":3,"file":"TourOverlay.d.ts","sourceRoot":"","sources":["../../src/components/TourOverlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoD,MAAM,OAAO,CAAC;AAIzE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,8CAwQtB,CAAC"}

package/dist/components/TourPopover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TourPopover.d.ts","sourceRoot":"","sources":["../../src/components/TourPopover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAOjF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,8CAgTtB,CAAC"}
+{"version":3,"file":"TourPopover.d.ts","sourceRoot":"","sources":["../../src/components/TourPopover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAOjF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,8CAsWtB,CAAC"}

package/dist/index.d.ts

@@ -15,6 +15,8 @@ interface TourStep {
     canSkip?: boolean;
     waitForElement?: boolean;
     waitTimeout?: number;
+    blockInteractions?: boolean;
+    clickToAdvance?: boolean;
 }
 interface TourAction {
     type: 'click' | 'navigate' | 'highlight' | 'tab-switch' | 'wizard-step' | 'custom';
@@ -52,6 +54,8 @@ interface TourConfig {
     onStepChange?: (step: TourStep, index: number) => void;
     allowKeyboardNavigation?: boolean;
     allowClickOutside?: boolean;
+    blockInteractions?: boolean;
+    clickToAdvance?: boolean;
     showProgress?: boolean;
     storage?: {
         key?: string;

package/dist/index.esm.js

@@ -1414,8 +1414,21 @@ function useTourHighlight(step) {
 }
 
 const TourOverlay = React.memo(function TourOverlay({ className }) {
-    const { state, theme, stop } = useTour();
+    const { state, theme, stop, config, next } = useTour();
     const { targetElement, highlightStyle, isVisible } = useTourHighlight(state.currentStep);
+    const [scrollTrigger, setScrollTrigger] = useState(0);
+    // Determine if interactions should be blocked
+    const shouldBlockInteractions = useMemo(() => {
+        const stepBlocking = state.currentStep?.blockInteractions;
+        const globalBlocking = config.blockInteractions;
+        return stepBlocking !== undefined ? stepBlocking : globalBlocking;
+    }, [state.currentStep?.blockInteractions, config.blockInteractions]);
+    // Determine if click-to-advance is enabled
+    const shouldClickToAdvance = useMemo(() => {
+        const stepClickToAdvance = state.currentStep?.clickToAdvance;
+        const globalClickToAdvance = config.clickToAdvance;
+        return stepClickToAdvance !== undefined ? stepClickToAdvance : globalClickToAdvance;
+    }, [state.currentStep?.clickToAdvance, config.clickToAdvance]);
     const overlayStyle = useMemo(() => ({
         position: 'fixed',
         top: 0,
@@ -1427,15 +1440,150 @@ const TourOverlay = React.memo(function TourOverlay({ className }) {
         zIndex: (theme.zIndex || 9999) - 1,
         pointerEvents: 'auto',
     }), [theme.overlay?.backgroundColor, theme.overlay?.opacity, theme.zIndex]);
-    const handleOverlayClick = useCallback(() => {
-        if (state.currentStep?.canSkip !== false) {
+    // Create cutout style for the highlighted element
+    const cutoutOverlayStyle = useMemo(() => {
+        if ((!shouldBlockInteractions && !shouldClickToAdvance) || !targetElement || !isVisible) {
+            return overlayStyle;
+        }
+        // Use getBoundingClientRect for viewport-relative coordinates (perfect for fixed overlay)
+        const rect = targetElement.getBoundingClientRect();
+        const padding = state.currentStep?.highlight?.padding || 8;
+        // Ensure coordinates are within viewport bounds
+        const left = Math.max(0, rect.left - padding);
+        const top = Math.max(0, rect.top - padding);
+        const right = Math.min(window.innerWidth, rect.right + padding);
+        const bottom = Math.min(window.innerHeight, rect.bottom + padding);
+        return {
+            ...overlayStyle,
+            clipPath: `polygon(
+        0% 0%, 
+        0% 100%, 
+        ${left}px 100%, 
+        ${left}px ${top}px, 
+        ${right}px ${top}px, 
+        ${right}px ${bottom}px, 
+        ${left}px ${bottom}px, 
+        ${left}px 100%, 
+        100% 100%, 
+        100% 0%
+      )`,
+        };
+    }, [overlayStyle, shouldBlockInteractions, shouldClickToAdvance, targetElement, isVisible, state.currentStep?.highlight?.padding, scrollTrigger]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Force re-render of cutout overlay on scroll to maintain proper positioning
+    useEffect(() => {
+        if (!shouldBlockInteractions && !shouldClickToAdvance) {
+            return;
+        }
+        const handleScroll = () => {
+            // Force recalculation by updating scroll trigger
+            setScrollTrigger(prev => prev + 1);
+        };
+        window.addEventListener('scroll', handleScroll, { passive: true });
+        window.addEventListener('resize', handleScroll, { passive: true });
+        return () => {
+            window.removeEventListener('scroll', handleScroll);
+            window.removeEventListener('resize', handleScroll);
+        };
+    }, [shouldBlockInteractions, shouldClickToAdvance]);
+    const handleOverlayClick = useCallback((e) => {
+        // If interactions are blocked, prevent the click from propagating
+        if (shouldBlockInteractions) {
+            e.preventDefault();
+            e.stopPropagation();
+            return;
+        }
+        // Allow clicking outside to close tour if not blocking interactions
+        if (config.allowClickOutside !== false && state.currentStep?.canSkip !== false) {
             stop();
         }
-    }, [state.currentStep?.canSkip, stop]);
+    }, [shouldBlockInteractions, config.allowClickOutside, state.currentStep?.canSkip, stop]);
+    // Handle click-to-advance functionality
+    useEffect(() => {
+        if (!shouldClickToAdvance || !targetElement || !state.isRunning) {
+            return;
+        }
+        // Ensure target element is above the overlay when click-to-advance is enabled
+        const originalZIndex = targetElement.style.zIndex;
+        const originalPosition = targetElement.style.position;
+        targetElement.style.position = targetElement.style.position || 'relative';
+        targetElement.style.zIndex = String((theme.zIndex || 9999) + 1);
+        const handleTargetClick = (_e) => {
+            // Don't prevent default or stop propagation - let the element's normal behavior work
+            // Just advance the tour after a small delay to allow the click to be processed
+            setTimeout(() => {
+                next();
+            }, 100);
+        };
+        targetElement.addEventListener('click', handleTargetClick, true);
+        return () => {
+            targetElement.removeEventListener('click', handleTargetClick, true);
+            // Restore original styles
+            targetElement.style.zIndex = originalZIndex;
+            targetElement.style.position = originalPosition;
+        };
+    }, [shouldClickToAdvance, targetElement, state.isRunning, next, theme.zIndex]);
+    // Block interactions on the entire page when blocking is enabled
+    useEffect(() => {
+        if (!shouldBlockInteractions || !state.isRunning) {
+            return;
+        }
+        const handleGlobalClick = (e) => {
+            const target = e.target;
+            // Allow clicks on the tour target element and its children
+            if (targetElement && (targetElement.contains(target) || targetElement === target)) {
+                // If click-to-advance is enabled, let the target click handler deal with it
+                if (shouldClickToAdvance) {
+                    return;
+                }
+                return;
+            }
+            // Allow clicks on tour UI elements (popover, buttons, etc.)
+            if (target.closest('[data-tour-popover]') ||
+                target.closest('[data-tour-highlight]') ||
+                target.closest('[data-tour-overlay]')) {
+                return;
+            }
+            // Block all other clicks
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        const handleGlobalKeydown = (e) => {
+            // Allow tour navigation keys
+            if (['Escape', 'ArrowLeft', 'ArrowRight', 'Enter', 'Space'].includes(e.key)) {
+                return;
+            }
+            // Block other keyboard interactions
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        // Add event listeners to capture phase to block interactions early
+        document.addEventListener('click', handleGlobalClick, true);
+        document.addEventListener('keydown', handleGlobalKeydown, true);
+        document.addEventListener('mousedown', handleGlobalClick, true);
+        document.addEventListener('touchstart', handleGlobalClick, true);
+        return () => {
+            document.removeEventListener('click', handleGlobalClick, true);
+            document.removeEventListener('keydown', handleGlobalKeydown, true);
+            document.removeEventListener('mousedown', handleGlobalClick, true);
+            document.removeEventListener('touchstart', handleGlobalClick, true);
+        };
+    }, [shouldBlockInteractions, state.isRunning, targetElement, shouldClickToAdvance]);
     if (!state.isRunning || !state.currentStep) {
         return null;
     }
-    return (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [jsxRuntimeExports.jsx("div", { style: overlayStyle, onClick: handleOverlayClick, className: className, "data-tour-overlay": true }), isVisible && targetElement && (jsxRuntimeExports.jsx("div", { style: highlightStyle, "data-tour-highlight": true })), jsxRuntimeExports.jsx("style", { children: `
+    return (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [jsxRuntimeExports.jsx("div", { style: (shouldBlockInteractions || shouldClickToAdvance) ? cutoutOverlayStyle : overlayStyle, onClick: handleOverlayClick, className: className, "data-tour-overlay": true }), isVisible && targetElement && (jsxRuntimeExports.jsx("div", { style: highlightStyle, "data-tour-highlight": true })), shouldBlockInteractions && (jsxRuntimeExports.jsx("div", { style: {
+                    position: 'fixed',
+                    top: '20px',
+                    right: '20px',
+                    backgroundColor: 'rgba(0, 0, 0, 0.8)',
+                    color: 'white',
+                    padding: '8px 12px',
+                    borderRadius: '4px',
+                    fontSize: '12px',
+                    zIndex: (theme.zIndex || 9999) + 1,
+                    pointerEvents: 'none',
+                    animation: 'tour-fade-in 0.3s ease-out',
+                }, "data-tour-blocking-indicator": true, children: "\uD83D\uDD12 Interactions blocked" })), jsxRuntimeExports.jsx("style", { children: `
         @keyframes tour-highlight-pulse {
           0%, 100% {
             box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.2), 0 0 20px rgba(59, 130, 246, 0.3);
@@ -1463,24 +1611,53 @@ const TourOverlay = React.memo(function TourOverlay({ className }) {
         [data-tour-highlight] {
           animation: tour-fade-in 0.3s ease-out;
         }
+        
+        [data-tour-blocking-indicator] {
+          animation: tour-fade-in 0.3s ease-out;
+        }
       ` })] }));
 });
 
 function r(e){var t,f,n="";if("string"==typeof e||"number"==typeof e)n+=e;else if("object"==typeof e)if(Array.isArray(e)){var o=e.length;for(t=0;t<o;t++)e[t]&&(f=r(e[t]))&&(n&&(n+=" "),n+=f);}else for(f in e)e[f]&&(n&&(n+=" "),n+=f);return n}function clsx(){for(var e,t,f=0,n="",o=arguments.length;f<o;f++)(e=arguments[f])&&(t=r(e))&&(n&&(n+=" "),n+=t);return n}
 
 const TourPopover = React.memo(function TourPopover({ className }) {
-    const { state, theme, next, previous, skip, stop, isFirstStep, isLastStep, canGoNext, canGoPrevious } = useTour();
+    const { state, theme, next, previous, skip, stop, isFirstStep, isLastStep, canGoNext, canGoPrevious, config } = useTour();
     const { targetElement } = useTourHighlight(state.currentStep);
     const popoverRef = useRef(null);
     const [position, setPosition] = useState({ top: 0, left: 0, placement: 'top' });
     const updatePosition = useCallback(() => {
-        if (!popoverRef.current || !targetElement || !state.currentStep)
+        if (!popoverRef.current || !state.currentStep)
+            return;
+        // For center placement without target element, calculate center position directly
+        if (state.currentStep.placement === 'center' && !targetElement) {
+            const popoverRect = popoverRef.current.getBoundingClientRect();
+            const viewport = {
+                width: window.innerWidth,
+                height: window.innerHeight,
+                scrollTop: window.pageYOffset || document.documentElement.scrollTop,
+                scrollLeft: window.pageXOffset || document.documentElement.scrollLeft,
+            };
+            setPosition({
+                top: viewport.scrollTop + (viewport.height - popoverRect.height) / 2,
+                left: viewport.scrollLeft + (viewport.width - popoverRect.width) / 2,
+                placement: 'center',
+            });
+            return;
+        }
+        // For other placements, require target element
+        if (!targetElement)
             return;
         const newPosition = calculatePopoverPosition(targetElement, popoverRef.current, state.currentStep.placement || 'top');
         setPosition(newPosition);
     }, [targetElement, state.currentStep]);
     const step = state.currentStep;
     const popoverConfig = useMemo(() => step?.popover || {}, [step?.popover]);
+    // Determine if click-to-advance is enabled for this step
+    const shouldClickToAdvance = useMemo(() => {
+        const stepClickToAdvance = step?.clickToAdvance;
+        const globalClickToAdvance = config.clickToAdvance;
+        return stepClickToAdvance !== undefined ? stepClickToAdvance : globalClickToAdvance;
+    }, [step?.clickToAdvance, config.clickToAdvance]);
     const popoverStyle = useMemo(() => ({
         position: 'absolute',
         top: position.top,
@@ -1524,12 +1701,16 @@ const TourPopover = React.memo(function TourPopover({ className }) {
         await stop();
     }, [stop]);
     useEffect(() => {
-        updatePosition();
+        // Small delay to ensure popover is rendered and has dimensions
+        const timeoutId = setTimeout(() => {
+            updatePosition();
+        }, 10);
         const handleResize = () => updatePosition();
         const handleScroll = () => updatePosition();
         window.addEventListener('resize', handleResize);
         window.addEventListener('scroll', handleScroll, { passive: true });
         return () => {
+            clearTimeout(timeoutId);
             window.removeEventListener('resize', handleResize);
             window.removeEventListener('scroll', handleScroll);
         };
@@ -1626,7 +1807,7 @@ const TourPopover = React.memo(function TourPopover({ className }) {
                                     fontWeight: '500',
                                     opacity: canGoPrevious ? 1 : 0.5,
                                     transition: 'all 0.2s ease',
-                                }, children: "Previous" })), jsxRuntimeExports.jsx("button", { onClick: (e) => {
+                                }, children: "Previous" })), !shouldClickToAdvance && (jsxRuntimeExports.jsx("button", { onClick: (e) => {
                                     e.preventDefault();
                                     e.stopPropagation();
                                     handleNext();
@@ -1649,7 +1830,18 @@ const TourPopover = React.memo(function TourPopover({ className }) {
                                     zIndex: 99999,
                                 }, children: isLastStep
                                     ? (popoverConfig.finishLabel || 'Finish')
-                                    : (popoverConfig.nextLabel || 'Next') })] })] }), position.placement !== 'center' && (jsxRuntimeExports.jsx("div", { style: {
+                                    : (popoverConfig.nextLabel || 'Next') })), shouldClickToAdvance && (jsxRuntimeExports.jsx("div", { style: {
+                                    backgroundColor: 'rgba(59, 130, 246, 0.1)',
+                                    border: '1px solid rgba(59, 130, 246, 0.3)',
+                                    color: theme.primaryColor || '#3b82f6',
+                                    padding: '8px 16px',
+                                    borderRadius: '8px',
+                                    fontSize: '14px',
+                                    fontWeight: '500',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    gap: '6px',
+                                }, children: "\uD83D\uDC46 Click the highlighted element to continue" }))] })] }), position.placement !== 'center' && (jsxRuntimeExports.jsx("div", { style: {
                     position: 'absolute',
                     width: '12px',
                     height: '12px',