react-native-lumen 1.0.1 → 1.1.0

package/src/hooks/useTourScrollView.ts

@@ -0,0 +1,111 @@
+import { useCallback, useMemo } from 'react';
+import { useTour } from './useTour';
+
+export interface TourScrollViewOptions {
+  /**
+   * If true, scrolling will be disabled while the tour is active.
+   * @default false
+   */
+  disableScrollDuringTour?: boolean;
+}
+
+export interface TourScrollViewResult {
+  /**
+   * Animated ref to attach to your ScrollView/Animated.ScrollView.
+   * This is the same ref as `scrollViewRef` from useTour().
+   */
+  scrollViewRef: React.RefObject<any>;
+  /**
+   * Whether the tour is currently active (a step is being shown).
+   */
+  isTourActive: boolean;
+  /**
+   * Whether scrolling should be enabled based on tour state.
+   * Only relevant if disableScrollDuringTour option is true.
+   */
+  scrollEnabled: boolean;
+  /**
+   * Helper function to scroll to a specific position.
+   * Wraps the scrollTo method with error handling.
+   */
+  scrollTo: (options: { x?: number; y?: number; animated?: boolean }) => void;
+  /**
+   * Props to spread onto your ScrollView for full tour integration.
+   * Includes ref and scrollEnabled (if disableScrollDuringTour is true).
+   */
+  scrollViewProps: {
+    ref: React.RefObject<any>;
+    scrollEnabled?: boolean;
+  };
+}
+
+/**
+ * Hook to simplify integrating custom scroll views with the tour system.
+ *
+ * @example
+ * // Basic usage with Animated.ScrollView
+ * const { scrollViewRef } = useTourScrollView();
+ * return <Animated.ScrollView ref={scrollViewRef}>...</Animated.ScrollView>;
+ *
+ * @example
+ * // With scroll disabled during tour
+ * const { scrollViewProps } = useTourScrollView({ disableScrollDuringTour: true });
+ * return <Animated.ScrollView {...scrollViewProps}>...</Animated.ScrollView>;
+ *
+ * @example
+ * // Custom scroll view wrapper (forwardRef pattern)
+ * const MyScrollView = forwardRef((props, ref) => {
+ *   const { scrollViewRef } = useTourScrollView();
+ *   useImperativeHandle(ref, () => ({
+ *     getScrollRef: () => scrollViewRef.current,
+ *   }));
+ *   return <Animated.ScrollView ref={scrollViewRef} {...props} />;
+ * });
+ */
+export function useTourScrollView(
+  options: TourScrollViewOptions = {}
+): TourScrollViewResult {
+  const { disableScrollDuringTour = false } = options;
+
+  // Get the tour context - use type assertion since we know the internal structure
+  const tour = useTour();
+  const { scrollViewRef, currentStep } = tour as any;
+
+  const isTourActive = currentStep !== null;
+  const scrollEnabled = disableScrollDuringTour ? !isTourActive : true;
+
+  const scrollTo = useCallback(
+    (opts: { x?: number; y?: number; animated?: boolean }) => {
+      try {
+        if (scrollViewRef?.current?.scrollTo) {
+          scrollViewRef.current.scrollTo({
+            x: opts.x ?? 0,
+            y: opts.y ?? 0,
+            animated: opts.animated !== false,
+          });
+        }
+      } catch {
+        // Silently ignore scroll errors
+      }
+    },
+    [scrollViewRef]
+  );
+
+  const scrollViewProps = useMemo(() => {
+    const props: { ref: React.RefObject<any>; scrollEnabled?: boolean } = {
+      ref: scrollViewRef,
+    };
+    if (disableScrollDuringTour) {
+      props.scrollEnabled = scrollEnabled;
+    }
+    return props;
+  }, [scrollViewRef, disableScrollDuringTour, scrollEnabled]);
+
+  return {
+    scrollViewRef,
+    isTourActive,
+    scrollEnabled,
+    scrollTo,
+    scrollViewProps,
+  };
+}

package/src/index.tsx

@@ -2,7 +2,34 @@ export * from './types';
 export * from './components/TourProvider';
 export * from './components/TourZone';
 export * from './hooks/useTour';
+export { useTourScrollView } from './hooks/useTourScrollView';
+export type {
+  TourScrollViewOptions,
+  TourScrollViewResult,
+} from './hooks/useTourScrollView';
 export { TourOverlay } from './components/TourOverlay';
 export { TourTooltip } from './components/TourTooltip';
 export * from './constants/defaults';
 export * from './constants/animations';
+
+// Storage utilities for advanced use cases
+export {
+  detectStorage,
+  clearStorageCache,
+  type StorageType,
+} from './utils/storage';
+
+// Re-export specific types for convenience
+export type {
+  ZoneStyle,
+  ZoneShape,
+  TourStep,
+  CardProps,
+  TourConfig,
+  TourLabels,
+  TooltipStyles,
+  TourPersistenceConfig,
+  TourContextType,
+  StorageAdapter,
+  StepsOrder,
+} from './types';

package/src/types/index.ts

@@ -1,5 +1,98 @@
 import type { WithSpringConfig, SharedValue } from 'react-native-reanimated';
 import React from 'react';
+import type { ViewStyle, TextStyle } from 'react-native';
+
+// ─── Zone Customization Types ───────────────────────────────────────────
+
+/**
+ * Shape variants for the zone cutout.
+ */
+export type ZoneShape = 'rounded-rect' | 'circle' | 'pill';
+
+/**
+ * Customization options for the zone appearance.
+ * Can be set globally via TourConfig or per-step via TourStep/TourZone.
+ */
+export interface ZoneStyle {
+  /**
+   * Uniform padding around the highlighted element.
+   * @default 0
+   */
+  padding?: number;
+  /**
+   * Top padding (overrides `padding` for top side).
+   */
+  paddingTop?: number;
+  /**
+   * Right padding (overrides `padding` for right side).
+   */
+  paddingRight?: number;
+  /**
+   * Bottom padding (overrides `padding` for bottom side).
+   */
+  paddingBottom?: number;
+  /**
+   * Left padding (overrides `padding` for left side).
+   */
+  paddingLeft?: number;
+  /**
+   * Border radius of the zone (for 'rounded-rect' shape).
+   * @default 10
+   */
+  borderRadius?: number;
+  /**
+   * Shape of the zone cutout.
+   * - 'rounded-rect': Standard rounded rectangle (default)
+   * - 'circle': Circular zone that encompasses the element
+   * - 'pill': Pill/capsule shape with fully rounded ends
+   * @default 'rounded-rect'
+   */
+  shape?: ZoneShape;
+  /**
+   * Width of the border around the zone.
+   * Set to 0 to disable.
+   * @default 0
+   */
+  borderWidth?: number;
+  /**
+   * Color of the border.
+   * @default 'transparent'
+   */
+  borderColor?: string;
+  /**
+   * Color of the outer glow effect. Applied only if `enableGlow` is true in `TourConfig`.
+   * @default '#FFFFFF'
+   */
+  glowColor?: string;
+  /**
+   * Blur radius for the glow effect. Applied only if `enableGlow` is true in `TourConfig`.
+   * @default 10
+   */
+  glowRadius?: number;
+  /**
+   * Spread radius for the glow effect. Applied only if `enableGlow` is true in `TourConfig`.
+   * @default 5
+   */
+  glowSpread?: number;
+  /**
+   * Horizontal offset for the glow effect.
+   * @default 0
+   */
+  glowOffsetX?: number;
+  /**
+   * Vertical offset for the glow effect.
+   * @default 0
+   */
+  glowOffsetY?: number;
+  /**
+   * Spring damping for zone animations (per-step override).
+   */
+  springDamping?: number;
+  /**
+   * Spring stiffness for zone animations (per-step override).
+   */
+  springStiffness?: number;
+}
 
 export interface TourStep {
   /**
@@ -27,6 +120,36 @@ export interface TourStep {
    * If false, interactions are blocked (default behavior depends on global config).
    */
   clickable?: boolean;
+  /**
+   * If true, prevents interaction with the underlying app for this specific step.
+   * Overrides the global preventInteraction setting from TourConfig.
+   * @default undefined (uses global setting)
+   */
+  preventInteraction?: boolean;
+  /**
+   * If true, the skip button is hidden for this step (user must complete or press next).
+   * @default false
+   */
+  required?: boolean;
+  /**
+   * Controls whether the next/finish button is enabled.
+   * - `undefined`: No enforcement, next button always enabled (default).
+   * - `false`: Next button is disabled (grayed out, non-pressable).
+   * - `true`: Next button is enabled.
+   *
+   * Use this to gate progression until the user completes an action.
+   */
+  completed?: boolean;
+  /**
+   * Per-step zone style overrides.
+   * Merged with global zoneStyle from TourConfig.
+   */
+  zoneStyle?: ZoneStyle;
+  /**
+   * Custom render function for this step's tooltip/card.
+   * Overrides the global renderCard from TourConfig.
+   */
+  renderCustomCard?: (props: CardProps) => React.ReactNode;
 }
 
 export interface MeasureResult {
@@ -38,6 +161,13 @@ export interface MeasureResult {
 
 export type StepMap = Record<string, TourStep>;
 
+/**
+ * Steps order can be either:
+ * - A flat array of step keys (single-screen tour): `['bio', 'prompt', 'poll']`
+ * - A screen-grouped object (multi-screen tour): `{ ProfileSelf: ['bio', 'prompt'], HomeSwipe: ['filters'] }`
+ */
+export type StepsOrder = string[] | Record<string, string[]>;
+
 export interface TourLabels {
   next?: string;
   previous?: string;
@@ -45,6 +175,69 @@ export interface TourLabels {
   skip?: string;
 }
 
+export interface TooltipStyles {
+  /**
+   * Background color of the tooltip
+   */
+  backgroundColor?: string;
+  /**
+   * Border radius of the tooltip (for shape customization)
+   */
+  borderRadius?: number;
+  /**
+   * Text color for the title
+   */
+  titleColor?: string;
+  /**
+   * Text color for the description
+   */
+  descriptionColor?: string;
+  /**
+   * Background color for the primary button
+   */
+  primaryButtonColor?: string;
+  /**
+   * Text color for the primary button
+   */
+  primaryButtonTextColor?: string;
+  /**
+   * Border radius for the primary button
+   */
+  primaryButtonBorderRadius?: number;
+  /**
+   * Text color for the skip button
+   */
+  skipButtonTextColor?: string;
+  /**
+   * Custom style for the tooltip container
+   */
+  containerStyle?: ViewStyle;
+  /**
+   * Custom style for the title text
+   */
+  titleStyle?: TextStyle;
+  /**
+   * Custom style for the description text
+   */
+  descriptionStyle?: TextStyle;
+  /**
+   * Custom style for the primary button
+   */
+  primaryButtonStyle?: ViewStyle;
+  /**
+   * Custom style for the primary button text
+   */
+  primaryButtonTextStyle?: TextStyle;
+  /**
+   * Custom style for the skip button
+   */
+  skipButtonStyle?: ViewStyle;
+  /**
+   * Custom style for the skip button text
+   */
+  skipButtonTextStyle?: TextStyle;
+}
+
 export interface CardProps {
   step: TourStep;
   currentStepIndex: number;
@@ -55,11 +248,75 @@ export interface CardProps {
   isFirst: boolean;
   isLast: boolean;
   labels?: TourLabels;
+  /**
+   * Whether the step is required (skip button should be hidden).
+   */
+  required?: boolean;
+  /**
+   * Whether the step's completion condition is met.
+   * - `undefined`: No enforcement, next button always enabled.
+   * - `false`: Next button should be disabled.
+   * - `true`: Next button should be enabled.
+   */
+  completed?: boolean;
+}
+
+// ─── Persistence Types ───────────────────────────────────────────────────────
+
+/**
+ * Storage adapter interface for tour persistence.
+ * Compatible with MMKV v4 and AsyncStorage APIs.
+ */
+export interface StorageAdapter {
+  getItem: (key: string) => Promise<string | null> | string | null;
+  setItem: (key: string, value: string) => Promise<void> | void;
+  removeItem: (key: string) => Promise<void> | void;
+}
+
+/**
+ * Configuration for tour progress persistence.
+ */
+export interface TourPersistenceConfig {
+  /**
+   * Enable persistence. When true, the library will auto-detect available storage
+   * (MMKV v4 or AsyncStorage) and save/restore tour progress.
+   * @default false
+   */
+  enabled: boolean;
+  /**
+   * Unique identifier for this tour. Used as the storage key.
+   * Required when persistence is enabled.
+   * @example 'onboarding-tour' or 'feature-tour-v2'
+   */
+  tourId: string;
+  /**
+   * Custom storage adapter. If not provided, the library will auto-detect
+   * MMKV v4 or AsyncStorage.
+   */
+  storage?: StorageAdapter;
+  /**
+   * If true, automatically resume the tour from the saved step when start() is called
+   * without a specific step key.
+   * @default true
+   */
+  autoResume?: boolean;
+  /**
+   * If true, clear saved progress when the tour is completed (reaches the last step).
+   * @default true
+   */
+  clearOnComplete?: boolean;
+  /**
+   * Maximum age (in milliseconds) for saved progress. Progress older than this
+   * will be ignored and cleared.
+   * @default undefined (no expiration)
+   * @example 7 * 24 * 60 * 60 * 1000 // 7 days
+   */
+  maxAge?: number;
 }
 
 export interface TourConfig {
   /**
-   * Animation configuration for the spotlight movement.
+   * Animation configuration for the zone movement.
    */
   springConfig?: WithSpringConfig;
   /**
@@ -79,15 +336,36 @@ export interface TourConfig {
    * Backdrop opacity. Default 0.5
    */
   backdropOpacity?: number;
+  /**
+   * Custom styles for the tooltip appearance
+   */
+  tooltipStyles?: TooltipStyles;
+  /**
+   * Global zone style settings.
+   * Can be overridden per-step via TourStep.zoneStyle or TourZone props.
+   */
+  zoneStyle?: ZoneStyle;
+  /**
+   * Persistence configuration for saving/restoring tour progress.
+   * Supports MMKV v4 and AsyncStorage out of the box.
+   */
+  persistence?: TourPersistenceConfig;
+  /**
+   * Defines whether to apply a shadow/glow effect to the active tour zone highlight.
+   * @default false
+   */
+  enableGlow?: boolean;
 }
 
 export interface TourContextType {
   /**
    * Starts the tour at the first step or a specific step (by key).
+   * If persistence is enabled and autoResume is true, will resume from saved progress.
    */
   start: (stepKey?: string) => void;
   /**
    * Stops the tour and hides the overlay.
+   * Does NOT clear saved progress (use clearProgress for that).
    */
   stop: () => void;
   /**
@@ -124,9 +402,32 @@ export interface TourContextType {
    */
   config?: TourConfig;
   /**
+   * Animated ref to attach to your ScrollView for auto-scrolling.
+   * Use this ref directly on your ScrollView/Animated.ScrollView component.
+   * For custom scroll view components, use the useTourScrollView hook instead.
+   */
+  scrollViewRef: React.RefObject<any>;
+  /**
+   * @deprecated Use scrollViewRef directly instead.
    * Registers the main ScrollView ref for auto-scrolling
    */
   setScrollViewRef: (ref: any) => void;
+  /**
+   * Clears any saved tour progress from storage.
+   * Only available when persistence is enabled.
+   */
+  clearProgress: () => Promise<void>;
+  /**
+   * Whether there is saved progress available to resume.
+   * Only meaningful when persistence is enabled.
+   */
+  hasSavedProgress: boolean;
+  /**
+   * The full ordered list of step keys for this tour.
+   * Derived from stepsOrder prop or step registration order.
+   * Includes all steps across all screens (for multi-screen tours).
+   */
+  orderedStepKeys: string[];
 }
 
 export interface InternalTourContextType extends TourContextType {
@@ -136,7 +437,11 @@ export interface InternalTourContextType extends TourContextType {
   targetHeight: SharedValue<number>;
   targetRadius: SharedValue<number>;
   opacity: SharedValue<number>;
+  /** Border width for the zone glow ring */
+  zoneBorderWidth: SharedValue<number>;
   containerRef: React.RefObject<any>;
   scrollViewRef: React.RefObject<any>;
   setScrollViewRef: (ref: any) => void;
+  /** Resolved zone style for the current step */
+  currentZoneStyle: ZoneStyle | null;
 }