@korsolutions/guidon 1.0.1 → 1.0.3

package/src/components/GuidonTarget.tsx

@@ -1,7 +1,12 @@
-import { useCallback, useEffect, useRef } from 'react';
-import { View, Platform, type LayoutChangeEvent } from 'react-native';
-import { useGuidonStore } from '../store';
-import type { GuidonTargetProps, TargetMeasurements, GuidonStore, GuidonStep } from '../types';
+import { useCallback, useEffect, useRef, type ComponentRef } from "react";
+import { View, Platform, type LayoutChangeEvent } from "react-native";
+import { useGuidonStore } from "../store";
+import type {
+  GuidonTargetProps,
+  TargetMeasurements,
+  GuidonStore,
+  GuidonStep,
+} from "../types";
 
 /**
  * Wrapper component that marks an element as a walkthrough target
@@ -12,23 +17,28 @@ export function GuidonTarget({
   targetId,
   active = true,
 }: GuidonTargetProps) {
-  const viewRef = useRef<View>(null);
-  const registerTarget = useGuidonStore((state: GuidonStore) => state.registerTarget);
-  const unregisterTarget = useGuidonStore((state: GuidonStore) => state.unregisterTarget);
+  const viewRef = useRef<ComponentRef<typeof View>>(null);
+  const registerTarget = useGuidonStore(
+    (state: GuidonStore) => state.registerTarget,
+  );
+  const unregisterTarget = useGuidonStore(
+    (state: GuidonStore) => state.unregisterTarget,
+  );
   const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
   const config = useGuidonStore((state: GuidonStore) => state.config);
 
   // Check if this target is needed for the current walkthrough
   const isTargetNeeded =
-    isActive && config?.steps.some((step: GuidonStep) => step.targetId === targetId);
+    isActive &&
+    config?.steps.some((step: GuidonStep) => step.targetId === targetId);
 
   const measureElement = useCallback(() => {
     if (!viewRef.current || !active || !isTargetNeeded) return;
 
-    if (Platform.OS === 'web') {
+    if (Platform.OS === "web") {
       // Web measurement using getBoundingClientRect
       const element = viewRef.current as unknown as HTMLElement;
-      if (element && typeof element.getBoundingClientRect === 'function') {
+      if (element && typeof element.getBoundingClientRect === "function") {
         const rect = element.getBoundingClientRect();
         const measurements: TargetMeasurements = {
           x: rect.left + window.scrollX,
@@ -40,7 +50,13 @@ export function GuidonTarget({
       }
     } else {
       // Native measurement using measureInWindow
-      viewRef.current.measureInWindow((x, y, width, height) => {
+      // Cast to access the native measureInWindow method
+      const nativeRef = viewRef.current as unknown as {
+        measureInWindow: (
+          callback: (x: number, y: number, width: number, height: number) => void
+        ) => void;
+      };
+      nativeRef.measureInWindow((x, y, width, height) => {
         if (width > 0 && height > 0) {
           const measurements: TargetMeasurements = { x, y, width, height };
           registerTarget(targetId, measurements);
@@ -57,34 +73,34 @@ export function GuidonTarget({
         measureElement();
       });
     },
-    [measureElement]
+    [measureElement],
   );
 
   // Re-measure when walkthrough becomes active or when this target becomes relevant
   useEffect(() => {
-    if (isTargetNeeded) {
-      // Delay to ensure the element is rendered
-      const timer = setTimeout(() => {
-        measureElement();
-      }, 100);
-      return () => clearTimeout(timer);
-    }
+    if (!isTargetNeeded) return;
+
+    // Delay to ensure the element is rendered
+    const timer = setTimeout(() => {
+      measureElement();
+    }, 100);
+    return () => clearTimeout(timer);
   }, [isTargetNeeded, measureElement]);
 
   // Re-measure on scroll (web only)
   useEffect(() => {
-    if (Platform.OS !== 'web' || !isTargetNeeded) return;
+    if (Platform.OS !== "web" || !isTargetNeeded) return;
 
     const handleScroll = () => {
       measureElement();
     };
 
-    window.addEventListener('scroll', handleScroll, true);
-    window.addEventListener('resize', handleScroll);
+    window.addEventListener("scroll", handleScroll, true);
+    window.addEventListener("resize", handleScroll);
 
     return () => {
-      window.removeEventListener('scroll', handleScroll, true);
-      window.removeEventListener('resize', handleScroll);
+      window.removeEventListener("scroll", handleScroll, true);
+      window.removeEventListener("resize", handleScroll);
     };
   }, [isTargetNeeded, measureElement]);
 
@@ -100,7 +116,7 @@ export function GuidonTarget({
       ref={viewRef}
       onLayout={handleLayout}
       collapsable={false}
-      // style={{ alignSelf: 'flex-start' }}
+      style={{ alignSelf: "flex-start" }}
     >
       {children}
     </View>

package/src/components/GuidonTooltip.tsx

@@ -6,6 +6,7 @@ import {
   Dimensions,
   TouchableOpacity,
   Platform,
+  ActivityIndicator,
 } from 'react-native';
 import Animated, {
   useAnimatedStyle,
@@ -14,8 +15,8 @@ import Animated, {
   Easing,
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { useGuidonStore } from '../store';
-import type { GuidonTheme, TooltipPosition, TargetMeasurements, GuidonStore, GuidonStep } from '../types';
+import { useGuidonStore, useWaitingState, useIsFloatingStep } from '../store';
+import type { GuidonTheme, TooltipPosition, TargetMeasurements, GuidonStore, GuidonStep, FloatingPosition } from '../types';
 
 const DEFAULT_THEME: Required<
   Pick<
@@ -42,6 +43,67 @@ const DEFAULT_THEME: Required<
 
 const TOOLTIP_MARGIN = 16;
 const TOOLTIP_WIDTH = 300;
+const ESTIMATED_TOOLTIP_HEIGHT = 200;
+
+/**
+ * Calculate position for floating tooltips (steps without a target element)
+ */
+function calculateFloatingPosition(
+  floatingPosition: FloatingPosition,
+  screenWidth: number,
+  screenHeight: number,
+  tooltipWidth: number,
+  insets: { top: number; bottom: number; left: number; right: number }
+): { top: number; left: number } {
+  const MARGIN = 32;
+
+  const centerX = (screenWidth - tooltipWidth) / 2;
+  const centerY = (screenHeight - ESTIMATED_TOOLTIP_HEIGHT) / 2;
+
+  switch (floatingPosition) {
+    case 'center':
+      return { top: centerY, left: centerX };
+
+    case 'top':
+      return {
+        top: insets.top + MARGIN,
+        left: centerX,
+      };
+
+    case 'bottom':
+      return {
+        top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
+        left: centerX,
+      };
+
+    case 'top-left':
+      return {
+        top: insets.top + MARGIN,
+        left: MARGIN,
+      };
+
+    case 'top-right':
+      return {
+        top: insets.top + MARGIN,
+        left: screenWidth - tooltipWidth - MARGIN,
+      };
+
+    case 'bottom-left':
+      return {
+        top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
+        left: MARGIN,
+      };
+
+    case 'bottom-right':
+      return {
+        top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
+        left: screenWidth - tooltipWidth - MARGIN,
+      };
+
+    default:
+      return { top: centerY, left: centerX };
+  }
+}
 
 interface GuidonTooltipProps {
   theme?: GuidonTheme;
@@ -60,6 +122,7 @@ interface GuidonTooltipProps {
     skip?: string;
     finish?: string;
     stepOf?: (current: number, total: number) => string;
+    waitingDefault?: string;
   };
 }
 
@@ -80,6 +143,11 @@ export function GuidonTooltip({
   const previous = useGuidonStore((state: GuidonStore) => state.previous);
   const skip = useGuidonStore((state: GuidonStore) => state.skip);
 
+  // Check for floating or waiting states
+  const isFloatingStep = useIsFloatingStep();
+  const waitingState = useWaitingState();
+  const isWaiting = waitingState?.isWaiting ?? false;
+
   const mergedTheme = { ...DEFAULT_THEME, ...theme };
   const mergedLabels = {
     next: labels.next ?? 'Next',
@@ -87,6 +155,7 @@ export function GuidonTooltip({
     skip: labels.skip ?? 'Skip',
     finish: labels.finish ?? 'Finish',
     stepOf: labels.stepOf ?? ((c: number, t: number) => `${c} of ${t}`),
+    waitingDefault: labels.waitingDefault ?? 'Navigate to continue...',
   };
 
   const currentStep = config?.steps[currentStepIndex];
@@ -100,11 +169,23 @@ export function GuidonTooltip({
 
   // Calculate tooltip position
   const tooltipPosition = useMemo(() => {
+    // Handle floating steps (no target element)
+    if (isFloatingStep) {
+      const floatingPos = currentStep?.floatingPosition ?? 'center';
+      return calculateFloatingPosition(
+        floatingPos,
+        screenWidth,
+        screenHeight,
+        TOOLTIP_WIDTH,
+        insets
+      );
+    }
+
+    // Handle waiting state or no measurements - center the tooltip
     if (!measurements) {
-      return { top: screenHeight / 2, left: screenWidth / 2 - TOOLTIP_WIDTH / 2 };
+      return { top: screenHeight / 2 - ESTIMATED_TOOLTIP_HEIGHT / 2, left: screenWidth / 2 - TOOLTIP_WIDTH / 2 };
     }
 
-    const targetCenterY = measurements.y + measurements.height / 2;
     const targetBottom = measurements.y + measurements.height + mergedTheme.spotlightPadding;
     const targetTop = measurements.y - mergedTheme.spotlightPadding;
 
@@ -138,27 +219,68 @@ export function GuidonTooltip({
     top = Math.max(insets.top + TOOLTIP_MARGIN, Math.min(top, screenHeight - 200 - insets.bottom));
 
     return { top, left, position };
-  }, [measurements, screenWidth, screenHeight, insets, currentStep?.tooltipPosition, mergedTheme.spotlightPadding]);
+  }, [measurements, screenWidth, screenHeight, insets, currentStep?.tooltipPosition, currentStep?.floatingPosition, mergedTheme.spotlightPadding, isFloatingStep]);
+
+  // Determine if tooltip should be visible
+  // Show for: normal steps with measurements, floating steps, or waiting states
+  const shouldShowTooltip = isActive && currentStep && (measurements || isFloatingStep || isWaiting);
 
   // Animated styles
   const animatedStyle = useAnimatedStyle(() => {
     return {
-      opacity: withTiming(isActive && measurements ? 1 : 0, {
+      opacity: withTiming(shouldShowTooltip ? 1 : 0, {
         duration: animationDuration,
         easing: Easing.inOut(Easing.ease),
       }),
       transform: [
         {
-          translateY: withSpring(isActive && measurements ? 0 : 20, {
+          translateY: withSpring(shouldShowTooltip ? 0 : 20, {
             damping: 15,
             stiffness: 150,
           }),
         },
       ],
     };
-  }, [isActive, measurements, animationDuration]);
+  }, [shouldShowTooltip, animationDuration]);
+
+  if (!isActive || !currentStep) {
+    return null;
+  }
+
+  // Show waiting indicator when target element isn't mounted yet
+  if (isWaiting) {
+    return (
+      <Animated.View
+        style={[
+          styles.tooltipContainer,
+          {
+            top: tooltipPosition.top,
+            left: tooltipPosition.left,
+            width: TOOLTIP_WIDTH,
+            backgroundColor: mergedTheme.tooltipBackgroundColor,
+            borderColor: mergedTheme.tooltipBorderColor,
+            borderRadius: mergedTheme.tooltipBorderRadius,
+          },
+          animatedStyle,
+        ]}
+      >
+        <View style={styles.waitingContainer}>
+          <ActivityIndicator color={mergedTheme.primaryColor} />
+          <Text style={[styles.waitingText, { color: mergedTheme.descriptionColor }]}>
+            {waitingState?.message || mergedLabels.waitingDefault}
+          </Text>
+        </View>
+        <TouchableOpacity onPress={skip} style={styles.skipButton}>
+          <Text style={[styles.skipText, { color: mergedTheme.mutedColor }]}>
+            {mergedLabels.skip}
+          </Text>
+        </TouchableOpacity>
+      </Animated.View>
+    );
+  }
 
-  if (!isActive || !currentStep || !measurements) {
+  // For non-floating steps, we need measurements
+  if (!isFloatingStep && !measurements) {
     return null;
   }
 
@@ -362,4 +484,16 @@ const styles = StyleSheet.create({
     fontSize: 14,
     fontWeight: '600',
   },
+  waitingContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 12,
+    paddingVertical: 8,
+    marginBottom: 12,
+  },
+  waitingText: {
+    fontSize: 14,
+    lineHeight: 20,
+  },
 });

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useGuidonRef } from './useGuidonRef';

package/src/hooks/useGuidonRef.ts

@@ -0,0 +1,154 @@
+import { useCallback, useEffect, useRef, type RefObject } from 'react';
+import { Platform } from 'react-native';
+import { useGuidonStore } from '../store';
+import type { TargetMeasurements, GuidonStore, GuidonStep } from '../types';
+
+/**
+ * Element type that can be measured
+ * Supports both web elements and React Native Views
+ */
+type MeasurableElement = {
+  getBoundingClientRect?: () => DOMRect;
+  measureInWindow?: (
+    callback: (x: number, y: number, width: number, height: number) => void
+  ) => void;
+};
+
+/**
+ * Hook that returns a ref to attach to an element for guidon targeting.
+ * Alternative to the GuidonTarget wrapper component.
+ *
+ * @param targetId - The target ID that matches a step's targetId
+ * @returns A ref to attach to the target element
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const buttonRef = useGuidonRef<View>('my-button');
+ *   return <Button ref={buttonRef}>Click me</Button>;
+ * }
+ * ```
+ *
+ * @example Web usage
+ * ```tsx
+ * function MyComponent() {
+ *   const divRef = useGuidonRef<HTMLDivElement>('my-div');
+ *   return <div ref={divRef}>Highlight me</div>;
+ * }
+ * ```
+ */
+export function useGuidonRef<T extends MeasurableElement>(
+  targetId: string
+): RefObject<T | null> {
+  const ref = useRef<T>(null);
+  const measurementFrameRef = useRef<number | null>(null);
+
+  const registerTarget = useGuidonStore(
+    (state: GuidonStore) => state.registerTarget
+  );
+  const unregisterTarget = useGuidonStore(
+    (state: GuidonStore) => state.unregisterTarget
+  );
+  const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
+  const config = useGuidonStore((state: GuidonStore) => state.config);
+  const currentStepIndex = useGuidonStore(
+    (state: GuidonStore) => state.currentStepIndex
+  );
+
+  // Check if this target is needed anywhere in the walkthrough
+  const isTargetNeeded =
+    isActive &&
+    config?.steps.some((step: GuidonStep) => step.targetId === targetId);
+
+  // Check if this specific target is needed for the current step
+  const isCurrentTarget =
+    config?.steps[currentStepIndex]?.targetId === targetId;
+
+  const measureElement = useCallback(() => {
+    if (!ref.current || !isTargetNeeded) return;
+
+    if (Platform.OS === 'web') {
+      // Web measurement using getBoundingClientRect
+      const element = ref.current as unknown as HTMLElement;
+      if (element && typeof element.getBoundingClientRect === 'function') {
+        const rect = element.getBoundingClientRect();
+        const measurements: TargetMeasurements = {
+          x: rect.left + window.scrollX,
+          y: rect.top + window.scrollY,
+          width: rect.width,
+          height: rect.height,
+        };
+        registerTarget(targetId, measurements);
+      }
+    } else {
+      // Native measurement using measureInWindow
+      const nativeRef = ref.current as unknown as {
+        measureInWindow: (
+          cb: (x: number, y: number, w: number, h: number) => void
+        ) => void;
+      };
+
+      if (nativeRef && typeof nativeRef.measureInWindow === 'function') {
+        nativeRef.measureInWindow((x, y, width, height) => {
+          if (width > 0 && height > 0) {
+            const measurements: TargetMeasurements = { x, y, width, height };
+            registerTarget(targetId, measurements);
+          }
+        });
+      }
+    }
+  }, [targetId, isTargetNeeded, registerTarget]);
+
+  // Measure when guidon becomes active or when this target becomes relevant
+  useEffect(() => {
+    if (!isTargetNeeded) return;
+
+    // Use requestAnimationFrame to ensure layout is complete
+    measurementFrameRef.current = requestAnimationFrame(() => {
+      measureElement();
+    });
+
+    return () => {
+      if (measurementFrameRef.current) {
+        cancelAnimationFrame(measurementFrameRef.current);
+      }
+    };
+  }, [isTargetNeeded, measureElement]);
+
+  // Re-measure when this target becomes the current step
+  useEffect(() => {
+    if (!isCurrentTarget) return;
+
+    const timer = setTimeout(() => {
+      measureElement();
+    }, 50);
+
+    return () => clearTimeout(timer);
+  }, [isCurrentTarget, measureElement]);
+
+  // Web: handle scroll and resize
+  useEffect(() => {
+    if (Platform.OS !== 'web' || !isTargetNeeded) return;
+
+    const handleScrollOrResize = () => {
+      measureElement();
+    };
+
+    window.addEventListener('scroll', handleScrollOrResize, true);
+    window.addEventListener('resize', handleScrollOrResize);
+
+    return () => {
+      window.removeEventListener('scroll', handleScrollOrResize, true);
+      window.removeEventListener('resize', handleScrollOrResize);
+    };
+  }, [isTargetNeeded, measureElement]);
+
+  // Unregister on unmount
+  useEffect(() => {
+    return () => {
+      unregisterTarget(targetId);
+    };
+  }, [targetId, unregisterTarget]);
+
+  return ref;
+}

package/src/index.ts

@@ -7,6 +7,9 @@ export {
   useGuidonContext,
 } from "./components";
 
+// Hooks
+export { useGuidonRef } from "./hooks";
+
 // Store and API
 export {
   useGuidonStore,
@@ -15,6 +18,8 @@ export {
   useGuidonStep,
   useGuidonProgress,
   useTargetMeasurements,
+  useWaitingState,
+  useIsFloatingStep,
 } from "./store";
 
 // Types
@@ -29,6 +34,7 @@ export type {
   GuidonTooltipLabels,
   GuidonTooltipRenderProps,
   TooltipPosition,
+  FloatingPosition,
   TargetMeasurements,
   GuidonState,
   GuidonActions,

package/src/store.ts

@@ -1,4 +1,5 @@
 import { create } from "zustand";
+import { useShallow } from "zustand/react/shallow";
 import type {
   GuidonConfig,
   GuidonStore,
@@ -13,6 +14,8 @@ const initialState = {
   targetMeasurements: {},
   isLoading: false,
   error: null,
+  waitingForTarget: false,
+  waitingTargetId: null,
 };
 
 export const useGuidonStore = create<GuidonStore>((set, get) => ({
@@ -30,8 +33,10 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
     // Call onStepEnter for the first step
     const firstStep = config.steps[0];
-    firstStep.onStepEnter?.();
-    config.onStepChange?.(0, firstStep);
+    firstStep?.onStepEnter?.();
+    if (firstStep) {
+      config.onStepChange?.(0, firstStep);
+    }
   },
 
   next: () => {
@@ -47,8 +52,10 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
       set({ currentStepIndex: nextIndex });
 
-      nextStep.onStepEnter?.();
-      config.onStepChange?.(nextIndex, nextStep);
+      nextStep?.onStepEnter?.();
+      if (nextStep) {
+        config.onStepChange?.(nextIndex, nextStep);
+      }
     } else {
       // Last step completed
       get().complete();
@@ -67,8 +74,10 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
     set({ currentStepIndex: prevIndex });
 
-    prevStep.onStepEnter?.();
-    config.onStepChange?.(prevIndex, prevStep);
+    prevStep?.onStepEnter?.();
+    if (prevStep) {
+      config.onStepChange?.(prevIndex, prevStep);
+    }
   },
 
   goToStep: (index: number) => {
@@ -83,8 +92,10 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
 
     set({ currentStepIndex: index });
 
-    targetStep.onStepEnter?.();
-    config.onStepChange?.(index, targetStep);
+    targetStep?.onStepEnter?.();
+    if (targetStep) {
+      config.onStepChange?.(index, targetStep);
+    }
   },
 
   skip: () => {
@@ -114,11 +125,17 @@ export const useGuidonStore = create<GuidonStore>((set, get) => ({
   },
 
   registerTarget: (targetId: string, measurements: TargetMeasurements) => {
+    const { waitingTargetId } = get();
     set((state: GuidonStore) => ({
       targetMeasurements: {
         ...state.targetMeasurements,
         [targetId]: measurements,
       },
+      // Clear waiting state if this was the target we were waiting for
+      waitingForTarget:
+        waitingTargetId === targetId ? false : state.waitingForTarget,
+      waitingTargetId:
+        waitingTargetId === targetId ? null : state.waitingTargetId,
     }));
   },
 
@@ -254,15 +271,51 @@ export const useGuidonStep = () =>
   });
 
 export const useGuidonProgress = () =>
-  useGuidonStore((state: GuidonStore) => ({
-    currentStep: state.currentStepIndex + 1,
-    totalSteps: state.config?.steps.length ?? 0,
-    percentage: state.config
-      ? ((state.currentStepIndex + 1) / state.config.steps.length) * 100
-      : 0,
-  }));
+  useGuidonStore(
+    useShallow((state: GuidonStore) => ({
+      currentStep: state.currentStepIndex + 1,
+      totalSteps: state.config?.steps.length ?? 0,
+      percentage: state.config
+        ? ((state.currentStepIndex + 1) / state.config.steps.length) * 100
+        : 0,
+    }))
+  );
 
 export const useTargetMeasurements = (targetId: string) =>
   useGuidonStore(
     (state: GuidonStore) => state.targetMeasurements[targetId],
   );
+
+/**
+ * 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 const useWaitingState = () =>
+  useGuidonStore(
+    useShallow((state: GuidonStore) => {
+      if (!state.isActive || !state.config) return null;
+
+      const currentStep = state.config.steps[state.currentStepIndex];
+      const targetId = currentStep?.targetId;
+
+      // Floating step (no targetId) - not waiting
+      if (!targetId) return null;
+
+      const hasMeasurements = !!state.targetMeasurements[targetId];
+
+      return {
+        isWaiting: !hasMeasurements,
+        targetId: hasMeasurements ? null : targetId,
+        message: currentStep?.waitingMessage ?? null,
+      };
+    })
+  );
+
+/**
+ * Hook to check if the current step is a floating step (no target element)
+ */
+export const useIsFloatingStep = () =>
+  useGuidonStore((state: GuidonStore) => {
+    if (!state.config || !state.isActive) return false;
+    return !state.config.steps[state.currentStepIndex]?.targetId;
+  });