@korsolutions/guidon 1.0.1 → 1.0.3

package/dist/typescript/module/store.d.ts

@@ -0,0 +1,89 @@
+import type { GuidonConfig, GuidonStore, TargetMeasurements } from "./types";
+export declare const useGuidonStore: import("zustand").UseBoundStore<import("zustand").StoreApi<GuidonStore>>;
+/**
+ * Guidon API for external control
+ * Can be used outside of React components
+ */
+export 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: () => import("./types").GuidonStep | null;
+    /**
+     * Get all steps
+     */
+    getSteps: () => import("./types").GuidonStep[];
+    /**
+     * Subscribe to store changes
+     */
+    subscribe: (listener: (state: GuidonStore, prevState: GuidonStore) => void) => () => void;
+};
+/**
+ * Hook selectors for common use cases
+ */
+export declare const useGuidonActive: () => boolean;
+export declare const useGuidonStep: () => import("./types").GuidonStep | null;
+export declare const useGuidonProgress: () => {
+    currentStep: number;
+    totalSteps: number;
+    percentage: number;
+};
+export declare const useTargetMeasurements: (targetId: string) => TargetMeasurements;
+/**
+ * Hook to check if the guidon is waiting for a target element to mount
+ * Returns null if not active, not waiting, or if it's a floating step
+ */
+export declare const useWaitingState: () => {
+    isWaiting: boolean;
+    targetId: string | null;
+    message: string | null;
+} | null;
+/**
+ * Hook to check if the current step is a floating step (no target element)
+ */
+export declare const useIsFloatingStep: () => boolean;
+//# sourceMappingURL=store.d.ts.map

package/dist/typescript/module/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAcjB,eAAO,MAAM,cAAc,0EAuIxB,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;wBACiB,YAAY;IAIhC;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;sBACe,MAAM;IAIxB;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAKH;;OAEG;;IAMH;;OAEG;;IAKH;;OAEG;;CAEJ,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,eAC4B,CAAC;AAEzD,eAAO,MAAM,aAAa,2CAItB,CAAC;AAEL,eAAO,MAAM,iBAAiB;;;;CAS3B,CAAC;AAEJ,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,uBAGnD,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;QAmBzB,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAI1B,CAAC"}

package/dist/{index-D_JFvCIg.d.ts → typescript/module/types.d.ts}

@@ -1,13 +1,16 @@
-import { ReactNode } from 'react';
-
+import type { ReactNode } from 'react';
 /**
  * Position of tooltip relative to the highlighted element
  */
-type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right' | 'auto';
+/**
+ * Position for floating tooltips (steps without a target element)
+ */
+export type FloatingPosition = 'center' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 /**
  * Defines the measurements of a target element
  */
-interface TargetMeasurements {
+export interface TargetMeasurements {
     x: number;
     y: number;
     width: number;
@@ -16,28 +19,40 @@ interface TargetMeasurements {
 /**
  * A single step in the guidon
  */
-interface GuidonStep {
+export interface GuidonStep {
     /** Unique identifier for this step */
     id: string;
-    /** ID of the target element to highlight */
-    targetId: string;
+    /**
+     * ID of the target element to highlight.
+     * If omitted, this becomes a floating tooltip step.
+     */
+    targetId?: string;
     /** Title displayed in the tooltip */
     title: string;
     /** Description/content displayed in the tooltip */
     description: string;
     /** Preferred position of the tooltip */
     tooltipPosition?: TooltipPosition;
+    /**
+     * Position for floating tooltips (only used when targetId is not provided)
+     * @default 'center'
+     */
+    floatingPosition?: FloatingPosition;
     /** Custom content to render in the tooltip */
     customContent?: ReactNode;
     /** Called when this step becomes active */
     onStepEnter?: () => void;
     /** Called when leaving this step */
     onStepExit?: () => void;
+    /** Optional message to display while waiting for target to mount */
+    waitingMessage?: string;
+    /** Timeout in ms before auto-skipping this step (0 = no timeout) */
+    waitTimeout?: number;
 }
 /**
  * Theme configuration for guidon styling
  */
-interface GuidonTheme {
+export interface GuidonTheme {
     /** Color of the backdrop overlay */
     backdropColor?: string;
     /** Opacity of the backdrop (0-1) */
@@ -64,7 +79,7 @@ interface GuidonTheme {
 /**
  * State of a specific guidon tour
  */
-interface GuidonProgress {
+export interface GuidonProgress {
     /** Unique identifier for the guidon */
     guidonId: string;
     /** Whether this guidon has been completed */
@@ -80,7 +95,7 @@ interface GuidonProgress {
  * Persistence adapter interface for saving/loading guidon progress
  * Implement this interface to connect the guidon to your backend
  */
-interface GuidonPersistenceAdapter {
+export interface GuidonPersistenceAdapter {
     /**
      * Load the progress for a specific guidon
      * @param guidonId - Unique identifier for the guidon
@@ -106,7 +121,7 @@ interface GuidonPersistenceAdapter {
 /**
  * Configuration for a guidon
  */
-interface GuidonConfig {
+export interface GuidonConfig {
     /** Unique identifier for this guidon */
     id: string;
     /** Steps in the guidon */
@@ -125,17 +140,19 @@ interface GuidonConfig {
 /**
  * Labels for tooltip buttons
  */
-interface GuidonTooltipLabels {
+export interface GuidonTooltipLabels {
     next?: string;
     previous?: string;
     skip?: string;
     finish?: string;
     stepOf?: (current: number, total: number) => string;
+    /** Default message when waiting for target to mount */
+    waitingDefault?: string;
 }
 /**
  * Props for custom tooltip renderer
  */
-interface GuidonTooltipRenderProps {
+export interface GuidonTooltipRenderProps {
     step: GuidonStep;
     currentIndex: number;
     totalSteps: number;
@@ -146,7 +163,7 @@ interface GuidonTooltipRenderProps {
 /**
  * Props for the GuidonProvider component
  */
-interface GuidonProviderProps {
+export interface GuidonProviderProps {
     children: ReactNode;
     /** Configuration for the guidon */
     config: GuidonConfig;
@@ -170,7 +187,7 @@ interface GuidonProviderProps {
 /**
  * Props for the GuidonTarget component
  */
-interface GuidonTargetProps {
+export interface GuidonTargetProps {
     children: ReactNode;
     /** Target ID that matches a step's targetId */
     targetId: string;
@@ -180,7 +197,7 @@ interface GuidonTargetProps {
 /**
  * Internal store state
  */
-interface GuidonState {
+export interface GuidonState {
     /** Currently active guidon config */
     config: GuidonConfig | null;
     /** Whether the guidon is currently active */
@@ -195,11 +212,15 @@ interface GuidonState {
     isLoading: boolean;
     /** Error from persistence operations */
     error: string | null;
+    /** Whether the guide is waiting for a target element to mount */
+    waitingForTarget: boolean;
+    /** The targetId currently being waited for */
+    waitingTargetId: string | null;
 }
 /**
  * Internal store actions
  */
-interface GuidonActions {
+export interface GuidonActions {
     /** Configure the guidon */
     configure: (config: GuidonConfig) => void;
     /** Start the guidon */
@@ -225,90 +246,5 @@ interface GuidonActions {
     /** 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 };
+export type GuidonStore = GuidonState & GuidonActions;
+//# sourceMappingURL=types.d.ts.map

package/dist/typescript/module/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "@korsolutions/guidon",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A cross-platform walkthrough/onboarding component library for React Native with web support. Features spotlight effects, customizable tooltips, and flexible persistence options. ",
   "repository": "https://github.com/KorSoftwareSolutions/guidon.git",
   "author": "Christian Jimenez <christianjimenezfael@gmail.com>",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "source": "src/index.ts",
+  "main": "dist/commonjs/index.js",
+  "module": "dist/module/index.js",
+  "types": "dist/typescript/module/index.d.ts",
+  "react-native": "src/index.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": {
+        "types": "./dist/typescript/module/index.d.ts",
+        "default": "./dist/module/index.js"
+      },
+      "require": {
+        "types": "./dist/typescript/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
     },
     "./persistence": {
-      "types": "./dist/persistence/index.d.ts",
-      "import": "./dist/persistence/index.mjs",
-      "require": "./dist/persistence/index.js"
+      "import": {
+        "types": "./dist/typescript/module/persistence/index.d.ts",
+        "default": "./dist/module/persistence/index.js"
+      },
+      "require": {
+        "types": "./dist/typescript/commonjs/persistence/index.d.ts",
+        "default": "./dist/commonjs/persistence/index.js"
+      }
     }
   },
   "files": [
@@ -24,8 +36,8 @@
     "src"
   ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "bob build",
+    "dev": "bob build --watch",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "prepublishOnly": "yarn build"
@@ -55,10 +67,10 @@
   "devDependencies": {
     "@types/react": "^19.2.9",
     "@types/react-native": "^0.73.0",
+    "react-native-builder-bob": "^0.40.17",
     "react-native-reanimated": "^4.2.1",
     "react-native-safe-area-context": "^5.6.2",
     "react-native-svg": "^15.15.1",
-    "tsup": "^8.5.1",
     "typescript": "^5.0.0",
     "zustand": "^5.0.10"
   },

package/src/babel.config.js

@@ -0,0 +1,18 @@
+module.exports = function (api) {
+  api.cache(true);
+
+  return {
+    presets: ["module:react-native-builder-bob/babel-preset"],
+    plugins: [
+      [
+        require.resolve("babel-plugin-module-resolver"),
+        {
+          root: ["./src"],
+          alias: {
+            "@": "./src",
+          },
+        },
+      ],
+    ],
+  };
+};

package/src/bob.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+  source: "src",
+  output: "dist",
+  targets: [
+    [
+      "module",
+      {
+        esm: true,
+        configFile: true,
+      },
+    ],
+    "typescript",
+  ],
+};

package/src/components/GuidonOverlay.tsx

@@ -11,7 +11,7 @@ import Animated, {
   Easing,
 } from 'react-native-reanimated';
 import Svg, { Defs, Mask, Rect, G } from 'react-native-svg';
-import { useGuidonStore } from '../store';
+import { useGuidonStore, useWaitingState, useIsFloatingStep } from '../store';
 import type { TargetMeasurements, GuidonTheme, GuidonStore } from '../types';
 
 const AnimatedSvg = Animated.createAnimatedComponent(Svg);
@@ -44,6 +44,11 @@ export function GuidonOverlay({
   const currentStepIndex = useGuidonStore((state: GuidonStore) => state.currentStepIndex);
   const targetMeasurements = useGuidonStore((state: GuidonStore) => state.targetMeasurements);
 
+  // Check for floating or waiting states
+  const isFloatingStep = useIsFloatingStep();
+  const waitingState = useWaitingState();
+  const isWaiting = waitingState?.isWaiting ?? false;
+
   const mergedTheme = { ...DEFAULT_THEME, ...theme };
   const { width: screenWidth, height: screenHeight } = Dimensions.get('window');
 
@@ -54,6 +59,9 @@ export function GuidonOverlay({
     ? targetMeasurements[currentTargetId]
     : undefined;
 
+  // Determine if we should show full backdrop (no spotlight cutout)
+  const showFullBackdrop = isFloatingStep || isWaiting;
+
   // Calculate spotlight dimensions with padding
   const spotlight = useMemo(() => {
     if (!measurements) {
@@ -68,16 +76,64 @@ export function GuidonOverlay({
   }, [measurements, mergedTheme.spotlightPadding]);
 
   // Animated styles for fade in/out
+  // Show backdrop for: normal steps with measurements, floating steps, or waiting states
+  const shouldShow = isActive && (measurements || showFullBackdrop);
   const animatedStyle = useAnimatedStyle(() => {
     return {
-      opacity: withTiming(isActive && measurements ? 1 : 0, {
+      opacity: withTiming(shouldShow ? 1 : 0, {
         duration: animationDuration,
         easing: Easing.inOut(Easing.ease),
       }),
     };
-  }, [isActive, measurements, animationDuration]);
+  }, [shouldShow, animationDuration]);
+
+  if (!isActive) {
+    return null;
+  }
+
+  // Render full backdrop without spotlight for floating steps or waiting states
+  if (showFullBackdrop) {
+    if (Platform.OS === 'web') {
+      return (
+        <TouchableWithoutFeedback onPress={onBackdropPress}>
+          <Animated.View style={[styles.container, animatedStyle]}>
+            <div
+              style={{
+                position: 'absolute',
+                inset: 0,
+                backgroundColor: mergedTheme.backdropColor,
+                opacity: mergedTheme.backdropOpacity,
+              }}
+            />
+          </Animated.View>
+        </TouchableWithoutFeedback>
+      );
+    }
+
+    // Native: full backdrop without cutout
+    return (
+      <TouchableWithoutFeedback onPress={onBackdropPress}>
+        <AnimatedSvg
+          style={[styles.container, animatedStyle]}
+          width={screenWidth}
+          height={screenHeight}
+          viewBox={`0 0 ${screenWidth} ${screenHeight}`}
+        >
+          <Rect
+            x="0"
+            y="0"
+            width="100%"
+            height="100%"
+            fill={mergedTheme.backdropColor}
+            fillOpacity={mergedTheme.backdropOpacity}
+          />
+        </AnimatedSvg>
+      </TouchableWithoutFeedback>
+    );
+  }
 
-  if (!isActive || !measurements) {
+  // If we have a target but no measurements yet, don't render anything
+  if (!measurements) {
     return null;
   }
 

package/src/components/GuidonProvider.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useCallback, useRef, createContext, useContext } from 'react';
-import { useGuidonStore } from '../store';
+import { useGuidonStore, useWaitingState } from '../store';
 import { useGuidonPersistence } from '../persistence/hooks';
 import { GuidonOverlay } from './GuidonOverlay';
 import { GuidonTooltip } from './GuidonTooltip';
@@ -46,9 +46,13 @@ export function GuidonProvider({
   const currentStepIndex = useGuidonStore((state: GuidonStore) => state.currentStepIndex);
   const configure = useGuidonStore((state: GuidonStore) => state.configure);
   const start = useGuidonStore((state: GuidonStore) => state.start);
+  const next = useGuidonStore((state: GuidonStore) => state.next);
   const skip = useGuidonStore((state: GuidonStore) => state.skip);
   const reset = useGuidonStore((state: GuidonStore) => state.reset);
 
+  // Check for waiting state (target element not mounted)
+  const waitingState = useWaitingState();
+
   const {
     isLoading,
     isCompleted: persistedCompleted,
@@ -106,6 +110,30 @@ export function GuidonProvider({
     checkAndStart();
   }, [autoStart, isLoading, persistedCompleted, shouldStart, start]);
 
+  // Handle wait timeout - auto-skip to next step if waiting too long
+  useEffect(() => {
+    const currentStep = config.steps[currentStepIndex];
+    const waitTimeout = currentStep?.waitTimeout;
+
+    // Only set timeout if:
+    // - We have a timeout configured
+    // - The timeout is greater than 0
+    // - We are currently waiting for a target
+    if (!waitTimeout || waitTimeout <= 0 || !waitingState?.isWaiting) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      // Check if we're still waiting when the timeout fires
+      const stillWaiting = useGuidonStore.getState().targetMeasurements[currentStep.targetId!] === undefined;
+      if (stillWaiting) {
+        next(); // Skip to next step
+      }
+    }, waitTimeout);
+
+    return () => clearTimeout(timer);
+  }, [currentStepIndex, config.steps, waitingState?.isWaiting, next]);
+
   const replay = useCallback(async () => {
     if (persistenceAdapter) {
       await clearProgress();