@aladinbs/react-guided-tour 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+import React$1, { ReactNode, Component } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
 
 interface TourStep {
     id: string;
@@ -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;
@@ -120,6 +124,9 @@ interface TourEngineEvents {
     'error': {
         error: Error;
         step?: TourStep;
+        tourId?: string;
+        stepIndex?: number;
+        timestamp?: string;
     };
     'state-change': TourState;
 }
@@ -138,6 +145,10 @@ interface PopoverPosition {
     placement: 'top' | 'bottom' | 'left' | 'right' | 'center';
 }
 
+/**
+ * Core tour engine that manages tour state, navigation, and lifecycle.
+ * Handles step progression, state persistence, and event emission.
+ */
 declare class TourEngine {
     private config;
     private state;
@@ -147,11 +158,29 @@ 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;
@@ -159,7 +188,13 @@ 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;
@@ -169,15 +204,29 @@ 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;
 }
 
+/**
+ * Manages and executes tour actions with pluggable integration support.
+ * Handles clicks, navigation, and custom actions through registered integrations.
+ */
 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;
@@ -215,6 +264,10 @@ 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.
+ */
 declare function useTourEngine(config: TourConfig): UseTourEngineReturn;
 
 interface TourContextValue extends UseTourEngineReturn {
@@ -225,31 +278,99 @@ interface TourProviderProps {
     config: TourConfig;
     children: ReactNode;
 }
-declare function TourProvider({ config, children }: TourProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Main provider component that initializes the tour system and provides context.
+ * Wraps the application with tour functionality.
+ */
+declare const TourProvider: React$1.NamedExoticComponent<TourProviderProps>;
+/**
+ * Hook to access tour functionality and state.
+ * Must be used within a TourProvider.
+ */
 declare function useTour(): TourContextValue;
 
 interface TourRunnerProps {
     className?: string;
 }
-declare function TourRunner({ className }: TourRunnerProps): react_jsx_runtime.JSX.Element | null;
+declare const TourRunner: React$1.NamedExoticComponent<TourRunnerProps>;
 
 interface TourOverlayProps {
     className?: string;
 }
-declare function TourOverlay({ className }: TourOverlayProps): react_jsx_runtime.JSX.Element | null;
+declare const TourOverlay: React$1.NamedExoticComponent<TourOverlayProps>;
 
 interface TourPopoverProps {
     className?: string;
 }
-declare function TourPopover({ className }: TourPopoverProps): react_jsx_runtime.JSX.Element | null;
+declare const TourPopover: React$1.NamedExoticComponent<TourPopoverProps>;
+
+interface ErrorInfo {
+    componentStack: string;
+    errorBoundary?: string;
+    errorBoundaryStack?: string;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: (error: Error, errorInfo: ErrorInfo, retry: () => void) => ReactNode;
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    isolate?: boolean;
+}
+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$1.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+declare function withErrorBoundary<P extends object>(Component: React$1.ComponentType<P>, errorBoundaryProps?: Omit<ErrorBoundaryProps, 'children'>): {
+    (props: P): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
 
 interface UseTourHighlightReturn {
     targetElement: HTMLElement | null;
     highlightStyle: React.CSSProperties;
     isVisible: boolean;
 }
+/**
+ * Hook that manages element highlighting for tour steps.
+ * Finds target elements, positions highlights, and handles dynamic content.
+ */
 declare function useTourHighlight(step: TourStep | null): UseTourHighlightReturn;
 
+interface ErrorHandlerOptions {
+    onError?: (error: Error, context?: string) => void;
+    logErrors?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
+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;
+}
+declare function useErrorHandler(options?: ErrorHandlerOptions): UseErrorHandlerReturn;
+declare function createSafeAsyncOperation<T>(operation: () => Promise<T>, options?: {
+    context?: string;
+    fallback?: T;
+    onError?: (error: Error) => void;
+    retryAttempts?: number;
+    retryDelay?: number;
+}): () => Promise<T | undefined>;
+declare function useErrorBoundary(): {
+    handleError: (error: Error, _errorInfo?: {
+        componentStack: string;
+    }) => never;
+};
+
 declare class TabIntegration implements Integration {
     name: string;
     canHandle(action: TourAction): boolean;
@@ -313,14 +434,27 @@ declare class NavigationIntegration implements Integration {
     private waitForNavigation;
 }
 
+/**
+ * Gets the absolute position of an element relative to the document.
+ */
 declare function getElementPosition(element: HTMLElement): ElementPosition;
+/**
+ * Calculates the optimal position for a popover relative to a target element.
+ * Falls back to alternative placements if the preferred placement doesn't fit.
+ */
 declare function calculatePopoverPosition(targetElement: HTMLElement, popoverElement: HTMLElement, preferredPlacement?: 'top' | 'bottom' | 'left' | 'right' | 'center'): PopoverPosition;
+/**
+ * Smoothly scrolls an element into view.
+ */
 declare function scrollToElement(element: HTMLElement, behavior?: ScrollBehavior): void;
+/**
+ * Checks if an element is currently visible in the viewport.
+ */
 declare function isElementInViewport(element: HTMLElement): boolean;
 declare function getViewportCenter(): {
     x: number;
     y: number;
 };
 
-export { NavigationIntegration, TabIntegration, TourActions, TourEngine, TourOverlay, TourPopover, TourProvider, TourRunner, TourStorage, WizardIntegration, calculatePopoverPosition, getElementPosition, getViewportCenter, isElementInViewport, scrollToElement, useTour, useTourEngine, useTourHighlight };
+export { ErrorBoundary, NavigationIntegration, TabIntegration, TourActions, TourEngine, TourOverlay, TourPopover, TourProvider, TourRunner, TourStorage, WizardIntegration, calculatePopoverPosition, createSafeAsyncOperation, getElementPosition, getViewportCenter, isElementInViewport, scrollToElement, useErrorBoundary, useErrorHandler, useTour, useTourEngine, useTourHighlight, withErrorBoundary };
 export type { ElementPosition, HighlightConfig, Integration, PopoverConfig, PopoverPosition, TourAction, TourConfig, TourEngineEvents, TourEventCallback, TourState, TourStep, TourTheme, UseTourEngineReturn, UseTourHighlightReturn };

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAG7E,cAAc,qBAAqB,CAAC;AAGpC,YAAY,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,eAAe,EACf,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAG9E,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGtG,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAG7E,cAAc,qBAAqB,CAAC;AAGpC,YAAY,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,eAAe,EACf,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}