@korsolutions/guidon 1.0.0

package/src/components/GuidonProvider.tsx

@@ -0,0 +1,158 @@
+import { useEffect, useCallback, useRef, createContext, useContext } from 'react';
+import { useGuidonStore } from '../store';
+import { useGuidonPersistence } from '../persistence/hooks';
+import { GuidonOverlay } from './GuidonOverlay';
+import { GuidonTooltip } from './GuidonTooltip';
+import type {
+  GuidonProviderProps,
+  GuidonConfig,
+  GuidonStore,
+} from '../types';
+
+interface GuidonContextValue {
+  start: () => void;
+  skip: () => void;
+  reset: () => void;
+  replay: () => Promise<void>;
+  isActive: boolean;
+  isCompleted: boolean;
+  isLoading: boolean;
+}
+
+const GuidonContext = createContext<GuidonContextValue | null>(null);
+
+export function useGuidonContext() {
+  const context = useContext(GuidonContext);
+  if (!context) {
+    throw new Error('useGuidonContext must be used within a GuidonProvider');
+  }
+  return context;
+}
+
+export function GuidonProvider({
+  children,
+  config,
+  autoStart = true,
+  shouldStart,
+  persistenceAdapter,
+  portalComponent: Portal,
+  renderTooltip,
+  tooltipLabels,
+  onBackdropPress,
+}: GuidonProviderProps) {
+  const hasInitialized = useRef(false);
+  const isActive = useGuidonStore((state: GuidonStore) => state.isActive);
+  const storeIsCompleted = useGuidonStore((state: GuidonStore) => state.isCompleted);
+  const currentStepIndex = useGuidonStore((state: GuidonStore) => state.currentStepIndex);
+  const configure = useGuidonStore((state: GuidonStore) => state.configure);
+  const start = useGuidonStore((state: GuidonStore) => state.start);
+  const skip = useGuidonStore((state: GuidonStore) => state.skip);
+  const reset = useGuidonStore((state: GuidonStore) => state.reset);
+
+  const {
+    isLoading,
+    isCompleted: persistedCompleted,
+    markCompleted,
+    markStepViewed,
+    clearProgress,
+  } = useGuidonPersistence(persistenceAdapter, config.id);
+
+  const isCompleted = storeIsCompleted || persistedCompleted;
+
+  useEffect(() => {
+    const enhancedConfig: GuidonConfig = {
+      ...config,
+      onComplete: async () => {
+        config.onComplete?.();
+        if (persistenceAdapter) {
+          await markCompleted();
+        }
+      },
+      onSkip: async () => {
+        config.onSkip?.();
+        if (persistenceAdapter) {
+          await markStepViewed(currentStepIndex);
+        }
+      },
+      onStepChange: async (stepIndex, step) => {
+        config.onStepChange?.(stepIndex, step);
+        if (persistenceAdapter) {
+          await markStepViewed(stepIndex);
+        }
+      },
+    };
+
+    configure(enhancedConfig);
+  }, [config, configure, persistenceAdapter, markCompleted, markStepViewed, currentStepIndex]);
+
+  useEffect(() => {
+    if (!autoStart || hasInitialized.current || isLoading) return;
+
+    const checkAndStart = async () => {
+      hasInitialized.current = true;
+
+      if (persistedCompleted) return;
+
+      if (shouldStart) {
+        const should = await shouldStart();
+        if (!should) return;
+      }
+
+      setTimeout(() => {
+        start();
+      }, 500);
+    };
+
+    checkAndStart();
+  }, [autoStart, isLoading, persistedCompleted, shouldStart, start]);
+
+  const replay = useCallback(async () => {
+    if (persistenceAdapter) {
+      await clearProgress();
+    }
+    reset();
+    hasInitialized.current = false;
+    setTimeout(() => {
+      start();
+    }, 100);
+  }, [persistenceAdapter, clearProgress, reset, start]);
+
+  const manualStart = useCallback(() => {
+    if (!isActive && !isLoading) {
+      start();
+    }
+  }, [isActive, isLoading, start]);
+
+  const contextValue: GuidonContextValue = {
+    start: manualStart,
+    skip,
+    reset,
+    replay,
+    isActive,
+    isCompleted,
+    isLoading,
+  };
+
+  const overlayContent = (
+    <>
+      <GuidonOverlay
+        theme={config.theme}
+        animationDuration={config.animationDuration}
+        onBackdropPress={onBackdropPress}
+      />
+      <GuidonTooltip
+        theme={config.theme}
+        animationDuration={config.animationDuration}
+        renderCustomTooltip={renderTooltip}
+        labels={tooltipLabels}
+      />
+    </>
+  );
+
+  return (
+    <GuidonContext.Provider value={contextValue}>
+      {children}
+      {Portal ? <Portal>{overlayContent}</Portal> : overlayContent}
+    </GuidonContext.Provider>
+  );
+}

package/src/components/GuidonTarget.tsx

@@ -0,0 +1,108 @@
+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';
+
+/**
+ * Wrapper component that marks an element as a walkthrough target
+ * Automatically measures and reports its position to the walkthrough store
+ */
+export function GuidonTarget({
+  children,
+  targetId,
+  active = true,
+}: GuidonTargetProps) {
+  const viewRef = useRef<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);
+
+  const measureElement = useCallback(() => {
+    if (!viewRef.current || !active || !isTargetNeeded) return;
+
+    if (Platform.OS === 'web') {
+      // Web measurement using getBoundingClientRect
+      const element = viewRef.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
+      viewRef.current.measureInWindow((x, y, width, height) => {
+        if (width > 0 && height > 0) {
+          const measurements: TargetMeasurements = { x, y, width, height };
+          registerTarget(targetId, measurements);
+        }
+      });
+    }
+  }, [targetId, active, isTargetNeeded, registerTarget]);
+
+  // Measure on layout change
+  const handleLayout = useCallback(
+    (_event: LayoutChangeEvent) => {
+      // Small delay to ensure layout is complete
+      requestAnimationFrame(() => {
+        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);
+    }
+  }, [isTargetNeeded, measureElement]);
+
+  // Re-measure on scroll (web only)
+  useEffect(() => {
+    if (Platform.OS !== 'web' || !isTargetNeeded) return;
+
+    const handleScroll = () => {
+      measureElement();
+    };
+
+    window.addEventListener('scroll', handleScroll, true);
+    window.addEventListener('resize', handleScroll);
+
+    return () => {
+      window.removeEventListener('scroll', handleScroll, true);
+      window.removeEventListener('resize', handleScroll);
+    };
+  }, [isTargetNeeded, measureElement]);
+
+  // Unregister on unmount
+  useEffect(() => {
+    return () => {
+      unregisterTarget(targetId);
+    };
+  }, [targetId, unregisterTarget]);
+
+  return (
+    <View
+      ref={viewRef}
+      onLayout={handleLayout}
+      collapsable={false}
+      style={{ alignSelf: 'flex-start' }}
+    >
+      {children}
+    </View>
+  );
+}

package/src/components/GuidonTooltip.tsx

@@ -0,0 +1,365 @@
+import { useMemo } from 'react';
+import {
+  View,
+  Text,
+  StyleSheet,
+  Dimensions,
+  TouchableOpacity,
+  Platform,
+} from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  withTiming,
+  withSpring,
+  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';
+
+const DEFAULT_THEME: Required<
+  Pick<
+    GuidonTheme,
+    | 'tooltipBackgroundColor'
+    | 'tooltipBorderColor'
+    | 'tooltipBorderRadius'
+    | 'titleColor'
+    | 'descriptionColor'
+    | 'primaryColor'
+    | 'mutedColor'
+    | 'spotlightPadding'
+  >
+> = {
+  tooltipBackgroundColor: '#ffffff',
+  tooltipBorderColor: '#e5e5e5',
+  tooltipBorderRadius: 12,
+  titleColor: '#1a1a1a',
+  descriptionColor: '#666666',
+  primaryColor: '#007AFF',
+  mutedColor: '#999999',
+  spotlightPadding: 8,
+};
+
+const TOOLTIP_MARGIN = 16;
+const TOOLTIP_WIDTH = 300;
+
+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;
+  };
+}
+
+export function GuidonTooltip({
+  theme = {},
+  animationDuration = 300,
+  renderCustomTooltip,
+  labels = {},
+}: GuidonTooltipProps) {
+  const insets = useSafeAreaInsets();
+  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 next = useGuidonStore((state: GuidonStore) => state.next);
+  const previous = useGuidonStore((state: GuidonStore) => state.previous);
+  const skip = useGuidonStore((state: GuidonStore) => state.skip);
+
+  const mergedTheme = { ...DEFAULT_THEME, ...theme };
+  const mergedLabels = {
+    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}`),
+  };
+
+  const currentStep = config?.steps[currentStepIndex];
+  const totalSteps = config?.steps.length ?? 0;
+  const isFirstStep = currentStepIndex === 0;
+  const isLastStep = currentStepIndex === totalSteps - 1;
+
+  const measurements: TargetMeasurements | undefined = currentStep?.targetId
+    ? targetMeasurements[currentStep.targetId]
+    : undefined;
+
+  // Calculate tooltip position
+  const tooltipPosition = useMemo(() => {
+    if (!measurements) {
+      return { top: screenHeight / 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;
+
+    // Determine preferred position
+    let position: TooltipPosition = currentStep?.tooltipPosition ?? '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';
+    }
+
+    let top: number;
+    let left: number = Math.max(
+      TOOLTIP_MARGIN,
+      Math.min(
+        measurements.x + measurements.width / 2 - TOOLTIP_WIDTH / 2,
+        screenWidth - TOOLTIP_WIDTH - TOOLTIP_MARGIN
+      )
+    );
+
+    if (position === 'top') {
+      top = targetTop - TOOLTIP_MARGIN - 150; // Approximate tooltip 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));
+
+    return { top, left, position };
+  }, [measurements, screenWidth, screenHeight, insets, currentStep?.tooltipPosition, mergedTheme.spotlightPadding]);
+
+  // Animated styles
+  const animatedStyle = useAnimatedStyle(() => {
+    return {
+      opacity: withTiming(isActive && measurements ? 1 : 0, {
+        duration: animationDuration,
+        easing: Easing.inOut(Easing.ease),
+      }),
+      transform: [
+        {
+          translateY: withSpring(isActive && measurements ? 0 : 20, {
+            damping: 15,
+            stiffness: 150,
+          }),
+        },
+      ],
+    };
+  }, [isActive, measurements, animationDuration]);
+
+  if (!isActive || !currentStep || !measurements) {
+    return null;
+  }
+
+  // Render custom tooltip if provided
+  if (renderCustomTooltip) {
+    return (
+      <Animated.View
+        style={[
+          styles.tooltipContainer,
+          {
+            top: tooltipPosition.top,
+            left: tooltipPosition.left,
+            width: TOOLTIP_WIDTH,
+          },
+          animatedStyle,
+        ]}
+      >
+        {renderCustomTooltip({
+          step: currentStep,
+          currentIndex: currentStepIndex,
+          totalSteps,
+          onNext: next,
+          onPrevious: previous,
+          onSkip: skip,
+        })}
+      </Animated.View>
+    );
+  }
+
+  // Default tooltip UI
+  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,
+      ]}
+    >
+      {/* Progress indicator */}
+      <View style={styles.progressContainer}>
+        <Text style={[styles.progressText, { color: mergedTheme.mutedColor }]}>
+          {mergedLabels.stepOf(currentStepIndex + 1, totalSteps)}
+        </Text>
+        <View style={styles.progressDots}>
+          {Array.from({ length: totalSteps }).map((_, i) => (
+            <View
+              key={i}
+              style={[
+                styles.progressDot,
+                {
+                  backgroundColor:
+                    i === currentStepIndex
+                      ? mergedTheme.primaryColor
+                      : mergedTheme.mutedColor,
+                  opacity: i === currentStepIndex ? 1 : 0.3,
+                },
+              ]}
+            />
+          ))}
+        </View>
+      </View>
+
+      {/* Content */}
+      <View style={styles.content}>
+        <Text style={[styles.title, { color: mergedTheme.titleColor }]}>
+          {currentStep.title}
+        </Text>
+        <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 }]}>
+            {mergedLabels.skip}
+          </Text>
+        </TouchableOpacity>
+
+        <View style={styles.navButtons}>
+          {!isFirstStep && (
+            <TouchableOpacity
+              onPress={previous}
+              style={[styles.navButton, styles.backButton]}
+            >
+              <Text style={[styles.backButtonText, { color: mergedTheme.primaryColor }]}>
+                {mergedLabels.previous}
+              </Text>
+            </TouchableOpacity>
+          )}
+          <TouchableOpacity
+            onPress={next}
+            style={[
+              styles.navButton,
+              styles.nextButton,
+              { backgroundColor: mergedTheme.primaryColor },
+            ]}
+          >
+            <Text style={styles.nextButtonText}>
+              {isLastStep ? mergedLabels.finish : mergedLabels.next}
+            </Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  tooltipContainer: {
+    position: 'absolute',
+    zIndex: 1000,
+    borderWidth: 1,
+    padding: 16,
+    ...Platform.select({
+      ios: {
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 4 },
+        shadowOpacity: 0.15,
+        shadowRadius: 12,
+      },
+      android: {
+        elevation: 8,
+      },
+      web: {
+        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+      } as any,
+    }),
+  },
+  progressContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    marginBottom: 12,
+  },
+  progressText: {
+    fontSize: 12,
+    fontWeight: '500',
+  },
+  progressDots: {
+    flexDirection: 'row',
+    gap: 4,
+  },
+  progressDot: {
+    width: 6,
+    height: 6,
+    borderRadius: 3,
+  },
+  content: {
+    marginBottom: 16,
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 8,
+  },
+  description: {
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  buttonContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+  skipButton: {
+    paddingVertical: 8,
+    paddingHorizontal: 4,
+  },
+  skipText: {
+    fontSize: 14,
+  },
+  navButtons: {
+    flexDirection: 'row',
+    gap: 8,
+  },
+  navButton: {
+    paddingVertical: 10,
+    paddingHorizontal: 16,
+    borderRadius: 8,
+  },
+  backButton: {
+    backgroundColor: 'transparent',
+  },
+  backButtonText: {
+    fontSize: 14,
+    fontWeight: '600',
+  },
+  nextButton: {},
+  nextButtonText: {
+    color: '#ffffff',
+    fontSize: 14,
+    fontWeight: '600',
+  },
+});

package/src/components/index.ts

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

package/src/index.ts

@@ -0,0 +1,51 @@
+// Components
+export {
+  GuidonTarget,
+  GuidonOverlay,
+  GuidonTooltip,
+  GuidonProvider,
+  useGuidonContext,
+} from "./components";
+
+// Store and API
+export {
+  useGuidonStore,
+  Guidon,
+  useGuidonActive,
+  useGuidonStep,
+  useGuidonProgress,
+  useTargetMeasurements,
+} from "./store";
+
+// Types
+export type {
+  GuidonStep,
+  GuidonConfig,
+  GuidonTheme,
+  GuidonProgress,
+  GuidonPersistenceAdapter,
+  GuidonProviderProps,
+  GuidonTargetProps,
+  GuidonTooltipLabels,
+  GuidonTooltipRenderProps,
+  TooltipPosition,
+  TargetMeasurements,
+  GuidonState,
+  GuidonActions,
+  GuidonStore,
+} from "./types";
+
+// Persistence adapters
+export {
+  createNoopAdapter,
+  createMemoryAdapter,
+  createLocalStorageAdapter,
+  createAsyncStorageAdapter,
+  createApiAdapter,
+  createCompositeAdapter,
+} from "./persistence/adapters";
+
+export {
+  useGuidonPersistence,
+  useShouldShowGuidon,
+} from "./persistence/hooks";