@korsolutions/guidon 1.0.0

package/dist/index-D_JFvCIg.d.ts

@@ -0,0 +1,314 @@
+import { ReactNode } from 'react';
+
+/**
+ * Position of tooltip relative to the highlighted element
+ */
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+/**
+ * Defines the measurements of a target element
+ */
+interface TargetMeasurements {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A single step in the guidon
+ */
+interface GuidonStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** ID of the target element to highlight */
+    targetId: string;
+    /** Title displayed in the tooltip */
+    title: string;
+    /** Description/content displayed in the tooltip */
+    description: string;
+    /** Preferred position of the tooltip */
+    tooltipPosition?: TooltipPosition;
+    /** Custom content to render in the tooltip */
+    customContent?: ReactNode;
+    /** Called when this step becomes active */
+    onStepEnter?: () => void;
+    /** Called when leaving this step */
+    onStepExit?: () => void;
+}
+/**
+ * Theme configuration for guidon styling
+ */
+interface GuidonTheme {
+    /** Color of the backdrop overlay */
+    backdropColor?: string;
+    /** Opacity of the backdrop (0-1) */
+    backdropOpacity?: number;
+    /** Background color of the tooltip */
+    tooltipBackgroundColor?: string;
+    /** Border color of the tooltip */
+    tooltipBorderColor?: string;
+    /** Border radius of the tooltip */
+    tooltipBorderRadius?: number;
+    /** Color of the title text */
+    titleColor?: string;
+    /** Color of the description text */
+    descriptionColor?: string;
+    /** Primary/accent color (buttons, progress) */
+    primaryColor?: string;
+    /** Muted/secondary color */
+    mutedColor?: string;
+    /** Border radius of the spotlight cutout */
+    spotlightBorderRadius?: number;
+    /** Padding around the highlighted element */
+    spotlightPadding?: number;
+}
+/**
+ * State of a specific guidon tour
+ */
+interface GuidonProgress {
+    /** Unique identifier for the guidon */
+    guidonId: string;
+    /** Whether this guidon has been completed */
+    completed: boolean;
+    /** Index of the last viewed step (for resuming) */
+    lastStepIndex?: number;
+    /** Timestamp of completion */
+    completedAt?: string;
+    /** Number of times this guidon has been completed */
+    completionCount?: number;
+}
+/**
+ * Persistence adapter interface for saving/loading guidon progress
+ * Implement this interface to connect the guidon to your backend
+ */
+interface GuidonPersistenceAdapter {
+    /**
+     * Load the progress for a specific guidon
+     * @param guidonId - Unique identifier for the guidon
+     * @returns The progress data or null if not found
+     */
+    loadProgress: (guidonId: string) => Promise<GuidonProgress | null>;
+    /**
+     * Save the progress for a specific guidon
+     * @param progress - The progress data to save
+     */
+    saveProgress: (progress: GuidonProgress) => Promise<void>;
+    /**
+     * Load all guidon progress (optional, for bulk operations)
+     * @returns Map of guidon IDs to progress data
+     */
+    loadAllProgress?: () => Promise<Record<string, GuidonProgress>>;
+    /**
+     * Clear progress for a specific guidon (for replay functionality)
+     * @param guidonId - Unique identifier for the guidon
+     */
+    clearProgress?: (guidonId: string) => Promise<void>;
+}
+/**
+ * Configuration for a guidon
+ */
+interface GuidonConfig {
+    /** Unique identifier for this guidon */
+    id: string;
+    /** Steps in the guidon */
+    steps: GuidonStep[];
+    /** Theme customization */
+    theme?: GuidonTheme;
+    /** Animation duration in milliseconds */
+    animationDuration?: number;
+    /** Called when the guidon is completed */
+    onComplete?: () => void;
+    /** Called when the guidon is skipped */
+    onSkip?: () => void;
+    /** Called when the step changes */
+    onStepChange?: (stepIndex: number, step: GuidonStep) => void;
+}
+/**
+ * Labels for tooltip buttons
+ */
+interface GuidonTooltipLabels {
+    next?: string;
+    previous?: string;
+    skip?: string;
+    finish?: string;
+    stepOf?: (current: number, total: number) => string;
+}
+/**
+ * Props for custom tooltip renderer
+ */
+interface GuidonTooltipRenderProps {
+    step: GuidonStep;
+    currentIndex: number;
+    totalSteps: number;
+    onNext: () => void;
+    onPrevious: () => void;
+    onSkip: () => void;
+}
+/**
+ * Props for the GuidonProvider component
+ */
+interface GuidonProviderProps {
+    children: ReactNode;
+    /** Configuration for the guidon */
+    config: GuidonConfig;
+    /** Whether to auto-start when the component mounts */
+    autoStart?: boolean;
+    /** Condition function to determine if guidon should start */
+    shouldStart?: () => boolean | Promise<boolean>;
+    /** Persistence adapter for saving/loading progress */
+    persistenceAdapter?: GuidonPersistenceAdapter;
+    /** Custom portal component for rendering overlay */
+    portalComponent?: React.ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Custom tooltip renderer */
+    renderTooltip?: (props: GuidonTooltipRenderProps) => ReactNode;
+    /** Customize tooltip labels */
+    tooltipLabels?: GuidonTooltipLabels;
+    /** Called when backdrop is pressed */
+    onBackdropPress?: () => void;
+}
+/**
+ * Props for the GuidonTarget component
+ */
+interface GuidonTargetProps {
+    children: ReactNode;
+    /** Target ID that matches a step's targetId */
+    targetId: string;
+    /** Whether this target is currently active (for conditional rendering) */
+    active?: boolean;
+}
+/**
+ * Internal store state
+ */
+interface GuidonState {
+    /** Currently active guidon config */
+    config: GuidonConfig | null;
+    /** Whether the guidon is currently active */
+    isActive: boolean;
+    /** Current step index */
+    currentStepIndex: number;
+    /** Whether the guidon has been completed */
+    isCompleted: boolean;
+    /** Map of target IDs to their measurements */
+    targetMeasurements: Record<string, TargetMeasurements>;
+    /** Loading state for persistence operations */
+    isLoading: boolean;
+    /** Error from persistence operations */
+    error: string | null;
+}
+/**
+ * Internal store actions
+ */
+interface GuidonActions {
+    /** Configure the guidon */
+    configure: (config: GuidonConfig) => void;
+    /** Start the guidon */
+    start: () => void;
+    /** Go to the next step */
+    next: () => void;
+    /** Go to the previous step */
+    previous: () => void;
+    /** Go to a specific step */
+    goToStep: (index: number) => void;
+    /** Skip the guidon */
+    skip: () => void;
+    /** Complete the guidon */
+    complete: () => void;
+    /** Reset the guidon state */
+    reset: () => void;
+    /** Register a target's measurements */
+    registerTarget: (targetId: string, measurements: TargetMeasurements) => void;
+    /** Unregister a target */
+    unregisterTarget: (targetId: string) => void;
+    /** Set loading state */
+    setLoading: (isLoading: boolean) => void;
+    /** Set error state */
+    setError: (error: string | null) => void;
+}
+type GuidonStore = GuidonState & GuidonActions;
+
+/**
+ * No-op adapter that doesn't persist anything
+ * Useful for testing or when persistence is not needed
+ */
+declare const createNoopAdapter: () => GuidonPersistenceAdapter;
+/**
+ * Memory adapter that stores progress in memory
+ * Data is lost when the app is closed
+ */
+declare const createMemoryAdapter: () => GuidonPersistenceAdapter;
+/**
+ * localStorage adapter for web
+ * Only works in browser environments
+ */
+declare const createLocalStorageAdapter: (keyPrefix?: string) => GuidonPersistenceAdapter;
+/**
+ * AsyncStorage adapter for React Native
+ * Requires @react-native-async-storage/async-storage to be installed
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * const adapter = createAsyncStorageAdapter(AsyncStorage);
+ */
+declare const createAsyncStorageAdapter: (asyncStorage: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    getAllKeys: () => Promise<readonly string[]>;
+    multiGet: (keys: readonly string[]) => Promise<readonly [string, string | null][]>;
+}, keyPrefix?: string) => GuidonPersistenceAdapter;
+/**
+ * Create a custom API adapter for backend persistence
+ * This is a factory function that creates an adapter based on your API endpoints
+ *
+ * @example
+ * const adapter = createApiAdapter({
+ *   loadProgress: async (guidonId) => {
+ *     const response = await fetch(`/api/guidon/${guidonId}`);
+ *     return response.json();
+ *   },
+ *   saveProgress: async (progress) => {
+ *     await fetch(`/api/guidon/${progress.guidonId}`, {
+ *       method: 'POST',
+ *       body: JSON.stringify(progress),
+ *     });
+ *   },
+ * });
+ */
+declare const createApiAdapter: (handlers: Partial<GuidonPersistenceAdapter>) => GuidonPersistenceAdapter;
+/**
+ * Combine multiple adapters (e.g., save to both local and API)
+ * Loads from the first adapter that returns data
+ * Saves to all adapters
+ */
+declare const createCompositeAdapter: (adapters: GuidonPersistenceAdapter[]) => GuidonPersistenceAdapter;
+
+/**
+ * Hook to manage guidon's walkthrough progress with a persistence adapter
+ */
+declare function useGuidonPersistence(adapter: GuidonPersistenceAdapter | undefined, guidonId: string): {
+    progress: GuidonProgress | null;
+    isLoading: boolean;
+    error: string | null;
+    isCompleted: boolean;
+    hasStarted: boolean;
+    saveProgress: (newProgress: Omit<GuidonProgress, "guidonId">) => Promise<void>;
+    clearProgress: () => Promise<void>;
+    markCompleted: () => Promise<void>;
+    markStepViewed: (stepIndex: number) => Promise<void>;
+};
+/**
+ * Hook to check if a guidon should be shown
+ */
+declare function useShouldShowGuidon(adapter: GuidonPersistenceAdapter | undefined, guidonId: string, options?: {
+    /** Show even if completed (for replay) */
+    forceShow?: boolean;
+    /** Additional condition to check */
+    additionalCondition?: () => boolean | Promise<boolean>;
+}): {
+    shouldShow: boolean;
+    isChecking: boolean;
+    isCompleted: boolean;
+};
+
+export { type GuidonTargetProps as G, type TargetMeasurements as T, type GuidonTheme as a, type GuidonStep as b, type GuidonProviderProps as c, type GuidonStore as d, type GuidonConfig as e, type GuidonProgress as f, type GuidonPersistenceAdapter as g, type GuidonTooltipLabels as h, type GuidonTooltipRenderProps as i, type TooltipPosition as j, type GuidonState as k, type GuidonActions as l, createNoopAdapter as m, createMemoryAdapter as n, createLocalStorageAdapter as o, createAsyncStorageAdapter as p, createApiAdapter as q, createCompositeAdapter as r, useShouldShowGuidon as s, useGuidonPersistence as u };

package/dist/index.d.mts

@@ -0,0 +1,128 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { G as GuidonTargetProps, a as GuidonTheme, b as GuidonStep, c as GuidonProviderProps, d as GuidonStore, e as GuidonConfig, T as TargetMeasurements } from './index-D_JFvCIg.mjs';
+export { l as GuidonActions, g as GuidonPersistenceAdapter, f as GuidonProgress, k as GuidonState, h as GuidonTooltipLabels, i as GuidonTooltipRenderProps, j as TooltipPosition, q as createApiAdapter, p as createAsyncStorageAdapter, r as createCompositeAdapter, o as createLocalStorageAdapter, n as createMemoryAdapter, m as createNoopAdapter, u as useGuidonPersistence, s as useShouldShowGuidon } from './index-D_JFvCIg.mjs';
+import * as zustand from 'zustand';
+import 'react';
+
+/**
+ * Wrapper component that marks an element as a walkthrough target
+ * Automatically measures and reports its position to the walkthrough store
+ */
+declare function GuidonTarget({ children, targetId, active, }: GuidonTargetProps): react_jsx_runtime.JSX.Element;
+
+interface GuidonOverlayProps {
+    theme?: GuidonTheme;
+    animationDuration?: number;
+    onBackdropPress?: () => void;
+}
+declare function GuidonOverlay({ theme, animationDuration, onBackdropPress, }: GuidonOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+interface GuidonTooltipProps {
+    theme?: GuidonTheme;
+    animationDuration?: number;
+    renderCustomTooltip?: (props: {
+        step: GuidonStep;
+        currentIndex: number;
+        totalSteps: number;
+        onNext: () => void;
+        onPrevious: () => void;
+        onSkip: () => void;
+    }) => React.ReactNode;
+    labels?: {
+        next?: string;
+        previous?: string;
+        skip?: string;
+        finish?: string;
+        stepOf?: (current: number, total: number) => string;
+    };
+}
+declare function GuidonTooltip({ theme, animationDuration, renderCustomTooltip, labels, }: GuidonTooltipProps): react_jsx_runtime.JSX.Element | null;
+
+interface GuidonContextValue {
+    start: () => void;
+    skip: () => void;
+    reset: () => void;
+    replay: () => Promise<void>;
+    isActive: boolean;
+    isCompleted: boolean;
+    isLoading: boolean;
+}
+declare function useGuidonContext(): GuidonContextValue;
+declare function GuidonProvider({ children, config, autoStart, shouldStart, persistenceAdapter, portalComponent: Portal, renderTooltip, tooltipLabels, onBackdropPress, }: GuidonProviderProps): react_jsx_runtime.JSX.Element;
+
+declare const useGuidonStore: zustand.UseBoundStore<zustand.StoreApi<GuidonStore>>;
+/**
+ * Guidon API for external control
+ * Can be used outside of React components
+ */
+declare const Guidon: {
+    /**
+     * Configure the walkthrough with steps and options
+     */
+    configure: (config: GuidonConfig) => void;
+    /**
+     * Start the walkthrough
+     */
+    start: () => void;
+    /**
+     * Go to the next step
+     */
+    next: () => void;
+    /**
+     * Go to the previous step
+     */
+    previous: () => void;
+    /**
+     * Go to a specific step by index
+     */
+    goToStep: (index: number) => void;
+    /**
+     * Skip the walkthrough
+     */
+    skip: () => void;
+    /**
+     * Complete the walkthrough
+     */
+    complete: () => void;
+    /**
+     * Reset the walkthrough to initial state
+     */
+    reset: () => void;
+    /**
+     * Check if the walkthrough is currently active
+     */
+    isActive: () => boolean;
+    /**
+     * Check if the walkthrough has been completed
+     */
+    isCompleted: () => boolean;
+    /**
+     * Get the current step index
+     */
+    getCurrentStepIndex: () => number;
+    /**
+     * Get the current step
+     */
+    getCurrentStep: () => GuidonStep | null;
+    /**
+     * Get all steps
+     */
+    getSteps: () => GuidonStep[];
+    /**
+     * Subscribe to store changes
+     */
+    subscribe: (listener: (state: GuidonStore, prevState: GuidonStore) => void) => () => void;
+};
+/**
+ * Hook selectors for common use cases
+ */
+declare const useGuidonActive: () => boolean;
+declare const useGuidonStep: () => GuidonStep | null;
+declare const useGuidonProgress: () => {
+    currentStep: number;
+    totalSteps: number;
+    percentage: number;
+};
+declare const useTargetMeasurements: (targetId: string) => TargetMeasurements;
+
+export { Guidon, GuidonConfig, GuidonOverlay, GuidonProvider, GuidonProviderProps, GuidonStep, GuidonStore, GuidonTarget, GuidonTargetProps, GuidonTheme, GuidonTooltip, TargetMeasurements, useGuidonActive, useGuidonContext, useGuidonProgress, useGuidonStep, useGuidonStore, useTargetMeasurements };

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { G as GuidonTargetProps, a as GuidonTheme, b as GuidonStep, c as GuidonProviderProps, d as GuidonStore, e as GuidonConfig, T as TargetMeasurements } from './index-D_JFvCIg.js';
+export { l as GuidonActions, g as GuidonPersistenceAdapter, f as GuidonProgress, k as GuidonState, h as GuidonTooltipLabels, i as GuidonTooltipRenderProps, j as TooltipPosition, q as createApiAdapter, p as createAsyncStorageAdapter, r as createCompositeAdapter, o as createLocalStorageAdapter, n as createMemoryAdapter, m as createNoopAdapter, u as useGuidonPersistence, s as useShouldShowGuidon } from './index-D_JFvCIg.js';
+import * as zustand from 'zustand';
+import 'react';
+
+/**
+ * Wrapper component that marks an element as a walkthrough target
+ * Automatically measures and reports its position to the walkthrough store
+ */
+declare function GuidonTarget({ children, targetId, active, }: GuidonTargetProps): react_jsx_runtime.JSX.Element;
+
+interface GuidonOverlayProps {
+    theme?: GuidonTheme;
+    animationDuration?: number;
+    onBackdropPress?: () => void;
+}
+declare function GuidonOverlay({ theme, animationDuration, onBackdropPress, }: GuidonOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+interface GuidonTooltipProps {
+    theme?: GuidonTheme;
+    animationDuration?: number;
+    renderCustomTooltip?: (props: {
+        step: GuidonStep;
+        currentIndex: number;
+        totalSteps: number;
+        onNext: () => void;
+        onPrevious: () => void;
+        onSkip: () => void;
+    }) => React.ReactNode;
+    labels?: {
+        next?: string;
+        previous?: string;
+        skip?: string;
+        finish?: string;
+        stepOf?: (current: number, total: number) => string;
+    };
+}
+declare function GuidonTooltip({ theme, animationDuration, renderCustomTooltip, labels, }: GuidonTooltipProps): react_jsx_runtime.JSX.Element | null;
+
+interface GuidonContextValue {
+    start: () => void;
+    skip: () => void;
+    reset: () => void;
+    replay: () => Promise<void>;
+    isActive: boolean;
+    isCompleted: boolean;
+    isLoading: boolean;
+}
+declare function useGuidonContext(): GuidonContextValue;
+declare function GuidonProvider({ children, config, autoStart, shouldStart, persistenceAdapter, portalComponent: Portal, renderTooltip, tooltipLabels, onBackdropPress, }: GuidonProviderProps): react_jsx_runtime.JSX.Element;
+
+declare const useGuidonStore: zustand.UseBoundStore<zustand.StoreApi<GuidonStore>>;
+/**
+ * Guidon API for external control
+ * Can be used outside of React components
+ */
+declare const Guidon: {
+    /**
+     * Configure the walkthrough with steps and options
+     */
+    configure: (config: GuidonConfig) => void;
+    /**
+     * Start the walkthrough
+     */
+    start: () => void;
+    /**
+     * Go to the next step
+     */
+    next: () => void;
+    /**
+     * Go to the previous step
+     */
+    previous: () => void;
+    /**
+     * Go to a specific step by index
+     */
+    goToStep: (index: number) => void;
+    /**
+     * Skip the walkthrough
+     */
+    skip: () => void;
+    /**
+     * Complete the walkthrough
+     */
+    complete: () => void;
+    /**
+     * Reset the walkthrough to initial state
+     */
+    reset: () => void;
+    /**
+     * Check if the walkthrough is currently active
+     */
+    isActive: () => boolean;
+    /**
+     * Check if the walkthrough has been completed
+     */
+    isCompleted: () => boolean;
+    /**
+     * Get the current step index
+     */
+    getCurrentStepIndex: () => number;
+    /**
+     * Get the current step
+     */
+    getCurrentStep: () => GuidonStep | null;
+    /**
+     * Get all steps
+     */
+    getSteps: () => GuidonStep[];
+    /**
+     * Subscribe to store changes
+     */
+    subscribe: (listener: (state: GuidonStore, prevState: GuidonStore) => void) => () => void;
+};
+/**
+ * Hook selectors for common use cases
+ */
+declare const useGuidonActive: () => boolean;
+declare const useGuidonStep: () => GuidonStep | null;
+declare const useGuidonProgress: () => {
+    currentStep: number;
+    totalSteps: number;
+    percentage: number;
+};
+declare const useTargetMeasurements: (targetId: string) => TargetMeasurements;
+
+export { Guidon, GuidonConfig, GuidonOverlay, GuidonProvider, GuidonProviderProps, GuidonStep, GuidonStore, GuidonTarget, GuidonTargetProps, GuidonTheme, GuidonTooltip, TargetMeasurements, useGuidonActive, useGuidonContext, useGuidonProgress, useGuidonStep, useGuidonStore, useTargetMeasurements };