@aladinbs/react-guided-tour 1.0.2 → 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:
@@ -564,8 +656,18 @@ const tourConfig: TourConfig = {
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions from the community! Whether you're fixing bugs, adding new features, improving documentation, or helping with testing, your contributions are valuable.
+
+### Quick Start for Contributors
+
+1. **Fork the repository** and clone it locally
+2. **Install dependencies**: `npm install`
+3. **Build the library**: `npm run build`
+4. **Run the example**: `npm run example`
+5. **Make your changes** and test thoroughly
+6. **Submit a pull request**
 
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.
+# react-guided-tour

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,31 @@
+import React, { Component, ReactNode } from 'react';
+export interface ErrorInfo {
+    componentStack: string;
+    errorBoundary?: string;
+    errorBoundaryStack?: string;
+}
+export interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}
+export interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: (error: Error, errorInfo: ErrorInfo, retry: () => void) => ReactNode;
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    isolate?: boolean;
+}
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    private retryTimeoutId;
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    componentWillUnmount(): void;
+    retry: () => void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export declare function withErrorBoundary<P extends object>(Component: React.ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): {
+    (props: P): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+//# sourceMappingURL=ErrorBoundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/components/ErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAC;IAChF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,SAAS,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAClF,OAAO,CAAC,cAAc,CAAuB;gBAEjC,KAAK,EAAE,kBAAkB;IASrC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAO1E,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS;IAapD,oBAAoB;IAMpB,KAAK,aAMH;IAEF,MAAM;CAkEP;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EACjC,kBAAkB,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC;YAExB,CAAC;;EASnC"}

package/dist/components/Toast.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export type ToastType = 'error' | 'warning' | 'success' | 'info';
+export interface ToastProps {
+    id: string;
+    type: ToastType;
+    title: string;
+    message: string;
+    duration?: number;
+    onClose: (id: string) => void;
+    showDetails?: boolean;
+    details?: string;
+}
+export declare const Toast: React.NamedExoticComponent<ToastProps>;
+//# sourceMappingURL=Toast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Toast.d.ts","sourceRoot":"","sources":["../../src/components/Toast.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA2C,MAAM,OAAO,CAAC;AAEhE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,KAAK,wCAiKhB,CAAC"}

package/dist/components/ToastProvider.d.ts

@@ -0,0 +1,28 @@
+import React, { ReactNode } from 'react';
+import { ToastType } from './Toast';
+export interface ToastData {
+    id: string;
+    type: ToastType;
+    title: string;
+    message: string;
+    duration?: number;
+    showDetails?: boolean;
+    details?: string;
+}
+export interface ToastContextValue {
+    showToast: (toast: Omit<ToastData, 'id'>) => string;
+    showError: (title: string, message: string, details?: string) => string;
+    showWarning: (title: string, message: string) => string;
+    showSuccess: (title: string, message: string) => string;
+    showInfo: (title: string, message: string) => string;
+    removeToast: (id: string) => void;
+    clearAllToasts: () => void;
+}
+export interface ToastProviderProps {
+    children: ReactNode;
+    maxToasts?: number;
+    position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+}
+export declare const ToastProvider: React.NamedExoticComponent<ToastProviderProps>;
+export declare function useToast(): ToastContextValue;
+//# sourceMappingURL=ToastProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToastProvider.d.ts","sourceRoot":"","sources":["../../src/components/ToastProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAoD,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3F,OAAO,EAAS,SAAS,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,MAAM,CAAC;IACpD,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACxE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACxD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,aAAa,CAAC;CACtE;AAED,eAAO,MAAM,aAAa,gDAqIxB,CAAC;AAEH,wBAAgB,QAAQ,IAAI,iBAAiB,CAM5C"}

package/dist/components/TourOverlay.d.ts

@@ -1,5 +1,6 @@
+import React from 'react';
 export interface TourOverlayProps {
     className?: string;
 }
-export declare function TourOverlay({ className }: TourOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const TourOverlay: React.NamedExoticComponent<TourOverlayProps>;
 //# sourceMappingURL=TourOverlay.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TourOverlay.d.ts","sourceRoot":"","sources":["../../src/components/TourOverlay.tsx"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,gBAAgB,kDA4E1D"}
+{"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

@@ -1,5 +1,6 @@
+import React from 'react';
 export interface TourPopoverProps {
     className?: string;
 }
-export declare function TourPopover({ className }: TourPopoverProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const TourPopover: React.NamedExoticComponent<TourPopoverProps>;
 //# sourceMappingURL=TourPopover.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TourPopover.d.ts","sourceRoot":"","sources":["../../src/components/TourPopover.tsx"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,gBAAgB,kDAkT1D"}
+{"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/components/TourProvider.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import React, { ReactNode } from 'react';
 import { TourConfig, TourTheme } from '../types';
 import { UseTourEngineReturn } from '../hooks/useTourEngine';
 interface TourContextValue extends UseTourEngineReturn {
@@ -9,7 +9,15 @@ export interface TourProviderProps {
     config: TourConfig;
     children: ReactNode;
 }
-export declare function TourProvider({ config, children }: TourProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Main provider component that initializes the tour system and provides context.
+ * Wraps the application with tour functionality.
+ */
+export declare const TourProvider: React.NamedExoticComponent<TourProviderProps>;
+/**
+ * Hook to access tour functionality and state.
+ * Must be used within a TourProvider.
+ */
 export declare function useTour(): TourContextValue;
 export {};
 //# sourceMappingURL=TourProvider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TourProvider.d.ts","sourceRoot":"","sources":["../../src/components/TourProvider.tsx"],"names":[],"mappings":"AAAA,OAAc,EAA6B,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAiB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE5E,UAAU,gBAAiB,SAAQ,mBAAmB;IACpD,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB;AAID,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AA4BD,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,iBAAiB,2CAenE;AAED,wBAAgB,OAAO,IAAI,gBAAgB,CAM1C"}
+{"version":3,"file":"TourProvider.d.ts","sourceRoot":"","sources":["../../src/components/TourProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA6B,SAAS,EAAW,MAAM,OAAO,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAiB,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE5E,UAAU,gBAAiB,SAAQ,mBAAmB;IACpD,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB;AAID,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AA4BD;;;GAGG;AACH,eAAO,MAAM,YAAY,+CAkBvB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,OAAO,IAAI,gBAAgB,CAM1C"}

package/dist/components/TourRunner.d.ts

@@ -1,5 +1,6 @@
+import React from 'react';
 export interface TourRunnerProps {
     className?: string;
 }
-export declare function TourRunner({ className }: TourRunnerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const TourRunner: React.NamedExoticComponent<TourRunnerProps>;
 //# sourceMappingURL=TourRunner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TourRunner.d.ts","sourceRoot":"","sources":["../../src/components/TourRunner.tsx"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,EAAE,eAAe,kDAaxD"}
+{"version":3,"file":"TourRunner.d.ts","sourceRoot":"","sources":["../../src/components/TourRunner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,UAAU,6CAiBrB,CAAC"}

package/dist/core/TourActions.d.ts

@@ -1,10 +1,20 @@
 import { TourAction, Integration } from '../types';
+/**
+ * Manages and executes tour actions with pluggable integration support.
+ * Handles clicks, navigation, and custom actions through registered integrations.
+ */
 export declare class TourActions {
     private integrations;
     registerIntegration(integration: Integration): void;
     unregisterIntegration(name: string): void;
+    /**
+     * Executes a tour action using the appropriate integration or default handler.
+     */
     execute(action: TourAction, element?: HTMLElement): Promise<void>;
     private findIntegration;
+    /**
+     * Default action handler for built-in action types.
+     */
     private executeDefault;
     private handleClick;
     private handleNavigate;

package/dist/core/TourActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TourActions.d.ts","sourceRoot":"","sources":["../../src/core/TourActions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEnD,qBAAa,WAAW;IACtB,OAAO,CAAC,YAAY,CAAuC;IAEpD,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAInD,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9E,OAAO,CAAC,eAAe;YAST,cAAc;YA2Bd,WAAW;YA2BX,cAAc;IAqB5B,OAAO,CAAC,KAAK;IAIN,yBAAyB,IAAI,MAAM,EAAE;IAIrC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG7C"}
+{"version":3,"file":"TourActions.d.ts","sourceRoot":"","sources":["../../src/core/TourActions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEnD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,YAAY,CAAuC;IAEpD,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAInD,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhD;;OAEG;IACU,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9E,OAAO,CAAC,eAAe;IASvB;;OAEG;YACW,cAAc;YA0Bd,WAAW;YAwBX,cAAc;IAkB5B,OAAO,CAAC,KAAK;IAIN,yBAAyB,IAAI,MAAM,EAAE;IAIrC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG7C"}

package/dist/core/TourEngine.d.ts

@@ -1,4 +1,8 @@
 import { TourConfig, TourStep, TourState, TourEngineEvents, TourEventCallback } from '../types';
+/**
+ * Core tour engine that manages tour state, navigation, and lifecycle.
+ * Handles step progression, state persistence, and event emission.
+ */
 export declare class TourEngine {
     private config;
     private state;
@@ -8,11 +12,29 @@ export declare class TourEngine {
     private initializeState;
     getState(): TourState;
     getConfig(): TourConfig;
+    /**
+     * Starts the tour from the current step index.
+     */
     start(): Promise<void>;
+    /**
+     * Advances to the next step in the tour.
+     */
     next(): Promise<void>;
+    /**
+     * Goes back to the previous step in the tour.
+     */
     previous(): Promise<void>;
+    /**
+     * Navigates to a specific step by index.
+     */
     goToStep(index: number): Promise<void>;
+    /**
+     * Skips the current tour and marks it as skipped.
+     */
     skip(): Promise<void>;
+    /**
+     * Completes the tour and marks it as finished.
+     */
     complete(): Promise<void>;
     stop(): Promise<void>;
     getCurrentStep(): TourStep | null;
@@ -20,7 +42,13 @@ export declare class TourEngine {
     isLastStep(): boolean;
     canGoNext(): boolean;
     canGoPrevious(): boolean;
+    /**
+     * Determines if the tour should be shown based on completion/skip state.
+     */
     shouldShowTour(): boolean;
+    /**
+     * Resets tour state and clears localStorage.
+     */
     resetTourState(): void;
     private waitForElement;
     private markStepCompleted;
@@ -30,6 +58,10 @@ export declare class TourEngine {
     on<K extends keyof TourEngineEvents>(event: K, callback: TourEventCallback<TourEngineEvents[K]>): void;
     off<K extends keyof TourEngineEvents>(event: K, callback: TourEventCallback<TourEngineEvents[K]>): void;
     private emit;
+    /**
+     * Subscribes to tour state changes.
+     * Returns an unsubscribe function.
+     */
     subscribe(callback: (state: TourState) => void): () => void;
 }
 //# sourceMappingURL=TourEngine.d.ts.map

package/dist/core/TourEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TourEngine.d.ts","sourceRoot":"","sources":["../../src/core/TourEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGhG,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAwD;gBAE7D,MAAM,EAAE,UAAU;IAM9B,OAAO,CAAC,eAAe;IAmBhB,QAAQ,IAAI,SAAS;IAIrB,SAAS,IAAI,UAAU;IAIjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAUzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CtC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,cAAc,IAAI,QAAQ,GAAG,IAAI;IAIjC,WAAW,IAAI,OAAO;IAItB,UAAU,IAAI,OAAO;IAIrB,SAAS,IAAI,OAAO;IAIpB,aAAa,IAAI,OAAO;IAIxB,cAAc,IAAI,OAAO;IAKzB,cAAc,IAAI,IAAI;YAOf,cAAc;IA6B5B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,QAAQ;IAOT,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACxC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI;IAOA,GAAG,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACzC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI;IAOP,OAAO,CAAC,IAAI;IAUL,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI;CAqBnE"}
+{"version":3,"file":"TourEngine.d.ts","sourceRoot":"","sources":["../../src/core/TourEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGhG;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAwD;gBAE7D,MAAM,EAAE,UAAU;IAM9B,OAAO,CAAC,eAAe;IAmBhB,QAAQ,IAAI,SAAS;IAIrB,SAAS,IAAI,UAAU;IAI9B;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoClC;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtC;;OAEG;IACU,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDnD;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BlC;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,cAAc,IAAI,QAAQ,GAAG,IAAI;IAIjC,WAAW,IAAI,OAAO;IAItB,UAAU,IAAI,OAAO;IAIrB,SAAS,IAAI,OAAO;IAIpB,aAAa,IAAI,OAAO;IAI/B;;OAEG;IACI,cAAc,IAAI,OAAO;IAKhC;;OAEG;IACI,cAAc,IAAI,IAAI;YAOf,cAAc;IA6B5B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,QAAQ;IAKT,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACxC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI;IAOA,GAAG,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACzC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC/C,IAAI;IAOP,OAAO,CAAC,IAAI;IAUZ;;;OAGG;IACI,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI;CAmBnE"}

package/dist/hooks/useErrorHandler.d.ts

@@ -0,0 +1,26 @@
+export interface ErrorHandlerOptions {
+    onError?: (error: Error, context?: string) => void;
+    logErrors?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
+export interface UseErrorHandlerReturn {
+    handleError: (error: Error, context?: string) => void;
+    handleAsyncError: <T>(asyncFn: () => Promise<T>, context?: string, fallback?: T) => Promise<T | undefined>;
+    wrapFunction: <T extends (...args: unknown[]) => unknown>(fn: T, context?: string) => T;
+    wrapAsyncFunction: <T extends (...args: unknown[]) => Promise<unknown>>(fn: T, context?: string) => T;
+}
+export declare function useErrorHandler(options?: ErrorHandlerOptions): UseErrorHandlerReturn;
+export declare function createSafeAsyncOperation<T>(operation: () => Promise<T>, options?: {
+    context?: string;
+    fallback?: T;
+    onError?: (error: Error) => void;
+    retryAttempts?: number;
+    retryDelay?: number;
+}): () => Promise<T | undefined>;
+export declare function useErrorBoundary(): {
+    handleError: (error: Error, _errorInfo?: {
+        componentStack: string;
+    }) => never;
+};
+//# sourceMappingURL=useErrorHandler.d.ts.map

package/dist/hooks/useErrorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useErrorHandler.d.ts","sourceRoot":"","sources":["../../src/hooks/useErrorHandler.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,gBAAgB,EAAE,CAAC,CAAC,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,KACT,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5B,YAAY,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACtD,EAAE,EAAE,CAAC,EACL,OAAO,CAAC,EAAE,MAAM,KACb,CAAC,CAAC;IACP,iBAAiB,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EACpE,EAAE,EAAE,CAAC,EACL,OAAO,CAAC,EAAE,MAAM,KACb,CAAC,CAAC;CACR;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,mBAAwB,GAAG,qBAAqB,CAuFxF;AAGD,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,SAUW,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAiCxC;AAGD,wBAAgB,gBAAgB;yBACU,KAAK,eAAe;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE;EAMvF"}

package/dist/hooks/useToastErrorHandler.d.ts

@@ -0,0 +1,15 @@
+export interface ToastErrorHandlerOptions {
+    onError?: (error: Error, context?: string) => void;
+    logErrors?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+    toastTitle?: string;
+}
+export interface UseToastErrorHandlerReturn {
+    handleError: (error: Error, context?: string) => void;
+    handleAsyncError: <T>(asyncFn: () => Promise<T>, context?: string, fallback?: T) => Promise<T | undefined>;
+    wrapFunction: <T extends (...args: unknown[]) => unknown>(fn: T, context?: string) => T;
+    wrapAsyncFunction: <T extends (...args: unknown[]) => Promise<unknown>>(fn: T, context?: string) => T;
+}
+export declare function useToastErrorHandler(options?: ToastErrorHandlerOptions): UseToastErrorHandlerReturn;
+//# sourceMappingURL=useToastErrorHandler.d.ts.map

package/dist/hooks/useToastErrorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToastErrorHandler.d.ts","sourceRoot":"","sources":["../../src/hooks/useToastErrorHandler.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,gBAAgB,EAAE,CAAC,CAAC,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,KACT,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5B,YAAY,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EACtD,EAAE,EAAE,CAAC,EACL,OAAO,CAAC,EAAE,MAAM,KACb,CAAC,CAAC;IACP,iBAAiB,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EACpE,EAAE,EAAE,CAAC,EACL,OAAO,CAAC,EAAE,MAAM,KACb,CAAC,CAAC;CACR;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,wBAA6B,GAAG,0BAA0B,CA6FvG"}

package/dist/hooks/useTourEngine.d.ts

@@ -17,5 +17,9 @@ export interface UseTourEngineReturn {
     engine: TourEngine;
     actions: TourActions;
 }
+/**
+ * Hook that creates and manages a tour engine instance.
+ * Provides tour control methods and state management with error handling.
+ */
 export declare function useTourEngine(config: TourConfig): UseTourEngineReturn;
 //# sourceMappingURL=useTourEngine.d.ts.map

package/dist/hooks/useTourEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTourEngine.d.ts","sourceRoot":"","sources":["../../src/hooks/useTourEngine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAgErE"}
+{"version":3,"file":"useTourEngine.d.ts","sourceRoot":"","sources":["../../src/hooks/useTourEngine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAG3D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAuFrE"}

package/dist/hooks/useTourHighlight.d.ts

@@ -4,5 +4,9 @@ export interface UseTourHighlightReturn {
     highlightStyle: React.CSSProperties;
     isVisible: boolean;
 }
+/**
+ * Hook that manages element highlighting for tour steps.
+ * Finds target elements, positions highlights, and handles dynamic content.
+ */
 export declare function useTourHighlight(step: TourStep | null): UseTourHighlightReturn;
 //# sourceMappingURL=useTourHighlight.d.ts.map

package/dist/hooks/useTourHighlight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTourHighlight.d.ts","sourceRoot":"","sources":["../../src/hooks/useTourHighlight.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAmB,MAAM,UAAU,CAAC;AAGrD,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,KAAK,CAAC,aAAa,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,sBAAsB,CAwH9E"}
+{"version":3,"file":"useTourHighlight.d.ts","sourceRoot":"","sources":["../../src/hooks/useTourHighlight.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAmB,MAAM,UAAU,CAAC;AAGrD,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,KAAK,CAAC,aAAa,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,sBAAsB,CAyH9E"}