@korsolutions/guidon 1.0.15 → 1.0.17

package/src/components/GuidonTooltip.tsx

@@ -1,43 +1,50 @@
-import { useMemo } from 'react';
+import { useMemo } from "react";
 import {
-  View,
-  Text,
-  StyleSheet,
+  ActivityIndicator,
   Dimensions,
-  TouchableOpacity,
   Platform,
-  ActivityIndicator,
-} from 'react-native';
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from "react-native";
 import Animated, {
+  Easing,
   useAnimatedStyle,
-  withTiming,
   withSpring,
-  Easing,
-} from 'react-native-reanimated';
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { useGuidonStore, useWaitingState, useIsFloatingStep } from '../store';
-import type { GuidonTheme, TooltipPosition, TargetMeasurements, GuidonStore, GuidonStep, FloatingPosition } from '../types';
+  withTiming,
+} from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useGuidonStore, useIsFloatingStep, useWaitingState } from "../store";
+import type {
+  FloatingPosition,
+  GuidonStep,
+  GuidonStore,
+  GuidonTheme,
+  TargetMeasurements,
+  TooltipPosition,
+} from "../types";
 
 const DEFAULT_THEME: Required<
   Pick<
     GuidonTheme,
-    | 'tooltipBackgroundColor'
-    | 'tooltipBorderColor'
-    | 'tooltipBorderRadius'
-    | 'titleColor'
-    | 'descriptionColor'
-    | 'primaryColor'
-    | 'mutedColor'
-    | 'spotlightPadding'
+    | "tooltipBackgroundColor"
+    | "tooltipBorderColor"
+    | "tooltipBorderRadius"
+    | "titleColor"
+    | "descriptionColor"
+    | "primaryColor"
+    | "mutedColor"
+    | "spotlightPadding"
   >
 > = {
-  tooltipBackgroundColor: '#ffffff',
-  tooltipBorderColor: '#e5e5e5',
+  tooltipBackgroundColor: "#ffffff",
+  tooltipBorderColor: "#e5e5e5",
   tooltipBorderRadius: 12,
-  titleColor: '#1a1a1a',
-  descriptionColor: '#666666',
-  primaryColor: '#007AFF',
-  mutedColor: '#999999',
+  titleColor: "#1a1a1a",
+  descriptionColor: "#666666",
+  primaryColor: "#007AFF",
+  mutedColor: "#999999",
   spotlightPadding: 8,
 };
 
@@ -53,7 +60,7 @@ function calculateFloatingPosition(
   screenWidth: number,
   screenHeight: number,
   tooltipWidth: number,
-  insets: { top: number; bottom: number; left: number; right: number }
+  insets: { top: number; bottom: number; left: number; right: number },
 ): { top: number; left: number } {
   const MARGIN = 32;
 
@@ -61,40 +68,40 @@ function calculateFloatingPosition(
   const centerY = (screenHeight - ESTIMATED_TOOLTIP_HEIGHT) / 2;
 
   switch (floatingPosition) {
-    case 'center':
+    case "center":
       return { top: centerY, left: centerX };
 
-    case 'top':
+    case "top":
       return {
         top: insets.top + MARGIN,
         left: centerX,
       };
 
-    case 'bottom':
+    case "bottom":
       return {
         top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
         left: centerX,
       };
 
-    case 'top-left':
+    case "top-left":
       return {
         top: insets.top + MARGIN,
         left: MARGIN,
       };
 
-    case 'top-right':
+    case "top-right":
       return {
         top: insets.top + MARGIN,
         left: screenWidth - tooltipWidth - MARGIN,
       };
 
-    case 'bottom-left':
+    case "bottom-left":
       return {
         top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
         left: MARGIN,
       };
 
-    case 'bottom-right':
+    case "bottom-right":
       return {
         top: screenHeight - ESTIMATED_TOOLTIP_HEIGHT - insets.bottom - MARGIN,
         left: screenWidth - tooltipWidth - MARGIN,
@@ -133,27 +140,31 @@ export function GuidonTooltip({
   labels = {},
 }: GuidonTooltipProps) {
   const insets = useSafeAreaInsets();
-  const { width: screenWidth, height: screenHeight } = Dimensions.get('window');
+  const { width: screenWidth, height: screenHeight } = Dimensions.get("window");
 
   const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
   const config = useGuidonStore((state: GuidonStore) => state.config);
-  const currentStepIndex = useGuidonStore((state: GuidonStore) => state.currentStepIndex);
-  const targetMeasurements = useGuidonStore((state: GuidonStore) => state.targetMeasurements);
+  const currentStepIndex = useGuidonStore(
+    (state: GuidonStore) => state.currentStepIndex,
+  );
+  const targetMeasurements = useGuidonStore(
+    (state: GuidonStore) => state.targetMeasurements,
+  );
   const storeNext = useGuidonStore((state: GuidonStore) => state.next);
   const storePrevious = useGuidonStore((state: GuidonStore) => state.previous);
   const storeSkip = useGuidonStore((state: GuidonStore) => state.skip);
 
   // Wrap with logging
   const next = () => {
-    console.log('[GuidonTooltip] Next button pressed');
+    console.log("[GuidonTooltip] Next button pressed");
     storeNext();
   };
   const previous = () => {
-    console.log('[GuidonTooltip] Previous button pressed');
+    console.log("[GuidonTooltip] Previous button pressed");
     storePrevious();
   };
   const skip = () => {
-    console.log('[GuidonTooltip] Skip button pressed');
+    console.log("[GuidonTooltip] Skip button pressed");
     storeSkip();
   };
 
@@ -164,12 +175,12 @@ export function GuidonTooltip({
 
   const mergedTheme = { ...DEFAULT_THEME, ...theme };
   const mergedLabels = {
-    next: labels.next ?? 'Next',
-    previous: labels.previous ?? 'Back',
-    skip: labels.skip ?? 'Skip',
-    finish: labels.finish ?? 'Finish',
+    next: labels.next ?? "Next",
+    previous: labels.previous ?? "Back",
+    skip: labels.skip ?? "Skip",
+    finish: labels.finish ?? "Finish",
     stepOf: labels.stepOf ?? ((c: number, t: number) => `${c} of ${t}`),
-    waitingDefault: labels.waitingDefault ?? 'Navigate to continue...',
+    waitingDefault: labels.waitingDefault ?? "Navigate to continue...",
   };
 
   const currentStep = config?.steps[currentStepIndex];
@@ -185,33 +196,37 @@ export function GuidonTooltip({
   const tooltipPosition = useMemo(() => {
     // Handle floating steps (no target element)
     if (isFloatingStep) {
-      const floatingPos = currentStep?.floatingPosition ?? 'center';
+      const floatingPos = currentStep?.floatingPosition ?? "center";
       return calculateFloatingPosition(
         floatingPos,
         screenWidth,
         screenHeight,
         TOOLTIP_WIDTH,
-        insets
+        insets,
       );
     }
 
-    // Handle waiting state or no measurements - center the tooltip
     if (!measurements) {
-      return { top: screenHeight / 2 - ESTIMATED_TOOLTIP_HEIGHT / 2, left: screenWidth / 2 - TOOLTIP_WIDTH / 2 };
+      return {
+        top: screenHeight / 2 - ESTIMATED_TOOLTIP_HEIGHT / 2,
+        left: screenWidth / 2 - TOOLTIP_WIDTH / 2,
+      };
     }
 
-    const targetBottom = measurements.y + measurements.height + mergedTheme.spotlightPadding;
+    const targetBottom =
+      measurements.y + measurements.height + mergedTheme.spotlightPadding;
     const targetTop = measurements.y - mergedTheme.spotlightPadding;
 
     // Determine preferred position
-    let position: TooltipPosition = currentStep?.tooltipPosition ?? 'auto';
+    let position: TooltipPosition = currentStep?.tooltipPosition ?? "auto";
 
-    if (position === 'auto') {
+    if (position === "auto") {
       // Auto-detect best position
       const spaceAbove = targetTop - insets.top;
       const spaceBelow = screenHeight - targetBottom - insets.bottom;
 
-      position = spaceBelow >= 200 ? 'bottom' : spaceAbove >= 200 ? 'top' : 'bottom';
+      position =
+        spaceBelow >= 200 ? "bottom" : spaceAbove >= 200 ? "top" : "bottom";
     }
 
     let top: number;
@@ -219,25 +234,36 @@ export function GuidonTooltip({
       TOOLTIP_MARGIN,
       Math.min(
         measurements.x + measurements.width / 2 - TOOLTIP_WIDTH / 2,
-        screenWidth - TOOLTIP_WIDTH - TOOLTIP_MARGIN
-      )
+        screenWidth - TOOLTIP_WIDTH - TOOLTIP_MARGIN,
+      ),
     );
 
-    if (position === 'top') {
-      top = targetTop - TOOLTIP_MARGIN - 150; // Approximate tooltip height
+    if (position === "top") {
+      top = targetTop - TOOLTIP_MARGIN - 150; // Estimated height
     } else {
       top = targetBottom + TOOLTIP_MARGIN;
     }
 
     // Ensure tooltip is within screen bounds
-    top = Math.max(insets.top + TOOLTIP_MARGIN, Math.min(top, screenHeight - 200 - insets.bottom));
+    top = Math.max(
+      insets.top + TOOLTIP_MARGIN,
+      Math.min(top, screenHeight - 200 - insets.bottom),
+    );
 
     return { top, left, position };
-  }, [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);
+  }, [
+    measurements,
+    screenWidth,
+    screenHeight,
+    insets,
+    currentStep?.tooltipPosition,
+    currentStep?.floatingPosition,
+    mergedTheme.spotlightPadding,
+    isFloatingStep,
+  ]);
+
+  const shouldShowTooltip =
+    isActive && currentStep && (measurements || isFloatingStep || isWaiting);
 
   // Animated styles
   const animatedStyle = useAnimatedStyle(() => {
@@ -280,7 +306,12 @@ export function GuidonTooltip({
       >
         <View style={styles.waitingContainer}>
           <ActivityIndicator color={mergedTheme.primaryColor} />
-          <Text style={[styles.waitingText, { color: mergedTheme.descriptionColor }]}>
+          <Text
+            style={[
+              styles.waitingText,
+              { color: mergedTheme.descriptionColor },
+            ]}
+          >
             {waitingState?.message || mergedLabels.waitingDefault}
           </Text>
         </View>
@@ -293,7 +324,6 @@ export function GuidonTooltip({
     );
   }
 
-  // For non-floating steps, we need measurements
   if (!isFloatingStep && !measurements) {
     return null;
   }
@@ -340,7 +370,6 @@ export function GuidonTooltip({
         animatedStyle,
       ]}
     >
-      {/* Progress indicator */}
       <View style={styles.progressContainer}>
         <Text style={[styles.progressText, { color: mergedTheme.mutedColor }]}>
           {mergedLabels.stepOf(currentStepIndex + 1, totalSteps)}
@@ -364,18 +393,18 @@ export function GuidonTooltip({
         </View>
       </View>
 
-      {/* Content */}
       <View style={styles.content}>
         <Text style={[styles.title, { color: mergedTheme.titleColor }]}>
           {currentStep.title}
         </Text>
-        <Text style={[styles.description, { color: mergedTheme.descriptionColor }]}>
+        <Text
+          style={[styles.description, { color: mergedTheme.descriptionColor }]}
+        >
           {currentStep.description}
         </Text>
         {currentStep.customContent}
       </View>
 
-      {/* Navigation buttons */}
       <View style={styles.buttonContainer}>
         <TouchableOpacity onPress={skip} style={styles.skipButton}>
           <Text style={[styles.skipText, { color: mergedTheme.mutedColor }]}>
@@ -389,7 +418,12 @@ export function GuidonTooltip({
               onPress={previous}
               style={[styles.navButton, styles.backButton]}
             >
-              <Text style={[styles.backButtonText, { color: mergedTheme.primaryColor }]}>
+              <Text
+                style={[
+                  styles.backButtonText,
+                  { color: mergedTheme.primaryColor },
+                ]}
+              >
                 {mergedLabels.previous}
               </Text>
             </TouchableOpacity>
@@ -414,13 +448,13 @@ export function GuidonTooltip({
 
 const styles = StyleSheet.create({
   tooltipContainer: {
-    position: 'absolute',
+    position: "absolute",
     zIndex: 1000,
     borderWidth: 1,
     padding: 16,
     ...Platform.select({
       ios: {
-        shadowColor: '#000',
+        shadowColor: "#000",
         shadowOffset: { width: 0, height: 4 },
         shadowOpacity: 0.15,
         shadowRadius: 12,
@@ -429,22 +463,22 @@ const styles = StyleSheet.create({
         elevation: 8,
       },
       web: {
-        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+        boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
       } as any,
     }),
   },
   progressContainer: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
     marginBottom: 12,
   },
   progressText: {
     fontSize: 12,
-    fontWeight: '500',
+    fontWeight: "500",
   },
   progressDots: {
-    flexDirection: 'row',
+    flexDirection: "row",
     gap: 4,
   },
   progressDot: {
@@ -457,7 +491,7 @@ const styles = StyleSheet.create({
   },
   title: {
     fontSize: 18,
-    fontWeight: '600',
+    fontWeight: "600",
     marginBottom: 8,
   },
   description: {
@@ -465,9 +499,9 @@ const styles = StyleSheet.create({
     lineHeight: 20,
   },
   buttonContainer: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
   },
   skipButton: {
     paddingVertical: 8,
@@ -477,7 +511,7 @@ const styles = StyleSheet.create({
     fontSize: 14,
   },
   navButtons: {
-    flexDirection: 'row',
+    flexDirection: "row",
     gap: 8,
   },
   navButton: {
@@ -486,22 +520,22 @@ const styles = StyleSheet.create({
     borderRadius: 8,
   },
   backButton: {
-    backgroundColor: 'transparent',
+    backgroundColor: "transparent",
   },
   backButtonText: {
     fontSize: 14,
-    fontWeight: '600',
+    fontWeight: "600",
   },
   nextButton: {},
   nextButtonText: {
-    color: '#ffffff',
+    color: "#ffffff",
     fontSize: 14,
-    fontWeight: '600',
+    fontWeight: "600",
   },
   waitingContainer: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'center',
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
     gap: 12,
     paddingVertical: 8,
     marginBottom: 12,

package/src/components/index.ts

@@ -1,4 +1,4 @@
-export { GuidonTarget } from './GuidonTarget';
-export { GuidonOverlay } from './GuidonOverlay';
-export { GuidonTooltip } from './GuidonTooltip';
-export { GuidonProvider, useGuidonContext } from './GuidonProvider';
+export { GuidonOverlay } from "./GuidonOverlay";
+export { GuidonProvider, useGuidonContext } from "./GuidonProvider";
+export { GuidonTarget } from "./GuidonTarget";
+export { GuidonTooltip } from "./GuidonTooltip";

package/src/hooks/useGuidonRef.ts

@@ -51,10 +51,16 @@ export function useGuidonRegister() {
 
   const measure = useCallback(
     (targetId: string, node: MeasurableElement | null) => {
-      console.log('[useGuidon] measure() called for:', targetId, { hasNode: !!node, isActive, hasConfig: !!config });
+      console.log("[useGuidon] measure() called for:", targetId, {
+        hasNode: !!node,
+        isActive,
+        hasConfig: !!config,
+      });
 
       if (!node || !isActive || !config) {
-        console.log('[useGuidon] measure() early return - missing node, inactive, or no config');
+        console.log(
+          "[useGuidon] measure() early return - missing node, inactive, or no config",
+        );
         return;
       }
 
@@ -63,11 +69,14 @@ export function useGuidonRegister() {
       );
 
       if (!isTargetUsed) {
-        console.log('[useGuidon] measure() - target not in config steps:', targetId);
+        console.log(
+          "[useGuidon] measure() - target not in config steps:",
+          targetId,
+        );
         return;
       }
 
-      console.log('[useGuidon] measure() - proceeding to measure:', targetId);
+      console.log("[useGuidon] measure() - proceeding to measure:", targetId);
 
       if (Platform.OS === "web") {
         const el = node as unknown as HTMLElement;
@@ -95,7 +104,11 @@ export function useGuidonRegister() {
           height:
             rect.height - paddingTop - paddingBottom - borderTop - borderBottom,
         };
-        console.log('[useGuidon] Registering web target:', targetId, measurements);
+        console.log(
+          "[useGuidon] Registering web target:",
+          targetId,
+          measurements,
+        );
         registerTarget(targetId, measurements);
 
         return;
@@ -144,12 +157,14 @@ export function useGuidonRegister() {
   useEffect(() => {
     if (!isActive || !config) return;
 
-    console.log('[useGuidon] Effect triggered - measuring all targets in this instance:',
-      Array.from(elementsRef.current.keys()));
+    console.log(
+      "[useGuidon] Effect triggered - measuring all targets in this instance:",
+      Array.from(elementsRef.current.keys()),
+    );
 
     // Measure all targets registered in this hook instance
     elementsRef.current.forEach((node, id) => {
-      console.log('[useGuidon] Scheduling measurement for:', id);
+      console.log("[useGuidon] Scheduling measurement for:", id);
       requestAnimationFrame(() => {
         measure(id, node);
       });