rn-onboarding-analytics 1.0.0

package/src/spill-onboarding/index.tsx

@@ -0,0 +1,251 @@
+import { useMemo, useState, useEffect, useCallback } from 'react';
+import {
+  type ImageSourcePropType,
+  View,
+  BackHandler,
+  Platform,
+  StyleSheet,
+} from 'react-native';
+import { useTheme } from '../utils/ThemeContext';
+import OnboardingIntroPanel from './components/OnboardingIntroPanel';
+import { useSharedValue, withTiming } from 'react-native-reanimated';
+import OnboardingStepPanel from './components/OnboardingStepPanel';
+import OnboardingStepContainer from './components/OnboardingStepContainer';
+import OnboardingImageContainer from './components/OnboardingImageContainer';
+import OnboardingModal from './components/OnboardingModal';
+import { type OnboardingProps } from './types';
+import useMeasureHeight from './hooks/useMeasureHeight';
+import { type Theme } from '../utils/theme';
+import { trackEvent } from './analytics';
+
+function SpillOnboarding({
+  animationDuration = 500,
+  introPanel: introPanelProps,
+  steps,
+  onComplete,
+  onSkip,
+  onStepChange: onStepChangeProps,
+  showCloseButton = true,
+  showBackButton = true,
+  wrapInModalOnWeb = true,
+  background,
+  skipButton,
+  apiKey,
+}: OnboardingProps) {
+  const { theme } = useTheme();
+
+  const styles = useMemo(() => createStyles(theme), [theme]);
+  const backgroundSpillProgress = useSharedValue(0);
+
+  const [step, setStep] = useState(-1);
+  const currentStep = step >= 0 ? steps[step] : undefined;
+  const firstStep = steps[0];
+
+  const onStepChange = useCallback(
+    (stepNumber: number) => {
+      const getStepName = (index: number) => {
+        if (index === -1) {
+          return 'Intro';
+        }
+        const s = steps[index];
+        if (!s) {
+          return 'Unknown';
+        }
+        if ('title' in s && s.title) {
+          return s.title;
+        }
+        return `Step ${index + 1}`;
+      };
+
+      const fromStepName = getStepName(step);
+      const toStepName = getStepName(stepNumber);
+
+      console.log('🔄 Onboarding Step Change:', {
+        from: fromStepName,
+        to: toStepName,
+        index: stepNumber,
+      });
+
+      setStep(stepNumber);
+      onStepChangeProps?.(stepNumber);
+
+      trackEvent(apiKey, 'step_change', {
+        from_index: step,
+        to_index: stepNumber,
+        from_step: fromStepName,
+        to_step: toStepName,
+      });
+    },
+    [onStepChangeProps, apiKey, step, steps]
+  );
+
+  useEffect(() => {
+    const backHandler = BackHandler.addEventListener(
+      'hardwareBackPress',
+      () => {
+        if (step > 0) {
+          onStepChange(step - 1);
+          return true;
+        } else if (step === 0) {
+          backgroundSpillProgress.set(
+            withTiming(0, {
+              duration: animationDuration,
+            })
+          );
+          setTimeout(() => setStep(-1), animationDuration / 2);
+          onStepChange(-1);
+          return true;
+        }
+
+        // stepNumber === -1 (intro panel) - allow default back action
+        return false;
+      }
+    );
+
+    return () => backHandler.remove();
+  }, [step, backgroundSpillProgress, onStepChange, animationDuration]);
+
+  const introPanel = useMeasureHeight();
+  const stepPanel = useMeasureHeight();
+  const screen = useMeasureHeight();
+
+  const onPressStart = () => {
+    backgroundSpillProgress.set(
+      withTiming(1, {
+        duration: animationDuration,
+      })
+    );
+    onStepChange(0);
+  };
+
+  const onNextPress = () => {
+    if (step === steps.length - 1) {
+      trackEvent(apiKey, 'complete');
+      return onComplete();
+    }
+
+    onStepChange(step + 1);
+  };
+
+  const onBackPress = () => {
+    if (step === 0) {
+      backgroundSpillProgress.set(
+        withTiming(0, {
+          duration: animationDuration,
+        })
+      );
+
+      onStepChange(-1);
+      return;
+    }
+
+    onStepChange(step - 1);
+  };
+
+  const renderIntroPanel = () => {
+    if (typeof introPanelProps === 'function') {
+      return introPanelProps({ onPressStart });
+    }
+
+    return (
+      <OnboardingIntroPanel
+        onPressStart={onPressStart}
+        title={introPanelProps.title}
+        subtitle={introPanelProps.subtitle}
+        button={introPanelProps.button}
+        image={introPanelProps.image}
+      />
+    );
+  };
+
+  const renderStepContent = () => {
+    if (!currentStep) {
+      return null;
+    }
+    if (typeof currentStep.component === 'function') {
+      return currentStep.component({
+        onNext: onNextPress,
+        onBack: onBackPress,
+        isLast: step === steps.length - 1,
+      });
+    }
+
+    return (
+      <OnboardingStepPanel
+        label={currentStep.label}
+        title={currentStep.title}
+        description={currentStep.description}
+        buttonLabel={currentStep.buttonLabel}
+        onBackPress={onBackPress}
+        onNextPress={onNextPress}
+        buttonPrimary={step === steps.length - 1}
+        showBackButton={showBackButton}
+      />
+    );
+  };
+
+  const currentStepImage: ImageSourcePropType | undefined = useMemo(() => {
+    if (!currentStep) {
+      return firstStep?.image;
+    }
+
+    return currentStep.image;
+  }, [currentStep, firstStep?.image]);
+
+  const onboardingContent = (
+    <View style={styles.container} ref={screen.ref}>
+      <View ref={introPanel.ref} style={styles.bottomPanel}>
+        {renderIntroPanel()}
+      </View>
+
+      <OnboardingImageContainer
+        currentStep={currentStep}
+        currentStepImage={currentStepImage}
+        position={currentStep?.position ?? firstStep?.position ?? 'top'}
+        animationDuration={animationDuration}
+        backgroundSpillProgress={backgroundSpillProgress}
+        screenHeight={screen.height}
+        introPanel={introPanel}
+        stepPanel={stepPanel}
+        background={background}
+      />
+
+      <OnboardingStepContainer
+        currentStep={currentStep}
+        animationDuration={animationDuration}
+        showCloseButton={showCloseButton}
+        renderStepContent={renderStepContent}
+        onSkip={onSkip}
+        ref={stepPanel.ref}
+        skipButton={skipButton}
+      />
+    </View>
+  );
+
+  // On web, wrap in modal; on mobile, render directly
+  if (Platform.OS === 'web' && wrapInModalOnWeb) {
+    return (
+      <OnboardingModal onSkip={onSkip}>{onboardingContent}</OnboardingModal>
+    );
+  }
+
+  return onboardingContent;
+}
+
+export default SpillOnboarding;
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: theme.bg.secondary,
+    },
+    bottomPanel: {
+      paddingHorizontal: 16,
+      paddingBottom: 16 + theme.insets.bottom,
+      position: 'absolute',
+      bottom: 0,
+      left: 0,
+      right: 0,
+    },
+  });

package/src/spill-onboarding/types.ts

@@ -0,0 +1,243 @@
+import { type ReactNode } from 'react';
+import type { ImageSourcePropType } from 'react-native';
+
+/**
+ * Theme color tokens used by onboarding components.
+ */
+export interface OnboardingColors {
+  /**
+   * Background colors used across the UI.
+   */
+  background: {
+    /**
+     * Primary page/screen background color.
+     */
+    primary: string;
+
+    /**
+     * Background for panels or cards.
+     */
+    secondary: string;
+
+    /**
+     * Subtle background for labels.
+     */
+    label: string;
+
+    /**
+     * Accented background for emphasis areas.
+     */
+    accent: string;
+  };
+
+  /**
+   * Text colors used for typography.
+   */
+  text: {
+    /**
+     * Default body text color for readability on `background.primary`.
+     */
+    primary: string;
+
+    /**
+     * Subdued text color for secondary information.
+     */
+    secondary: string;
+
+    /**
+     * High-contrast text color intended for buttons/overlays.
+     */
+    contrast: string;
+  };
+}
+
+/**
+ * Font family names used for specific text roles. Values are platform-registered font family strings.
+ */
+export interface OnboardingFonts {
+  /** Font for the intro screen title. */
+  introTitle?: string;
+
+  /** Font for the intro screen subtitle. */
+  introSubtitle?: string;
+
+  /** Font for the intro screen button label. */
+  introButton?: string;
+
+  /** Font for a step label (small caption above title). */
+  stepLabel?: string;
+
+  /** Font for a step title. */
+  stepTitle?: string;
+
+  /** Font for a step description/body. */
+  stepDescription?: string;
+
+  /** Font for a step primary action label. */
+  stepButton?: string;
+
+  /** Font for primary button labels. */
+  primaryButton?: string;
+
+  /** Font for secondary button labels. */
+  secondaryButton?: string;
+}
+
+/**
+ * Props for the introductory panel shown before steps begin.
+ */
+export interface OnboardingIntroPanelProps {
+  /** Callback invoked when the user starts the onboarding. */
+  onPressStart: () => void;
+
+  /** Title content; string or custom React node. */
+  title?: string | ReactNode;
+
+  /** Subtitle content; string or custom React node. */
+  subtitle?: string | ReactNode;
+
+  /**
+   * Button content. Either a simple string label or a render function
+   * that receives `onPressStart` to wire up a custom button.
+   */
+  button:
+    | string
+    | (({ onPressStart }: { onPressStart: () => void }) => ReactNode);
+
+  /** Optional image shown on the intro panel. */
+  image?: ImageSourcePropType | (() => ReactNode);
+}
+
+type OnboardingStepDefault = {
+  /** Discriminator: for default steps, `component` must be omitted. */
+  component?: never;
+
+  /** Optional small label displayed above the title. */
+  label?: string;
+
+  /** Step title text. */
+  title: string;
+
+  /** Step description/body text. */
+  description: string;
+
+  /** Label for the primary action button. */
+  buttonLabel: string;
+
+  /** Image displayed alongside the step content. */
+  image: ImageSourcePropType;
+
+  /** Placement of the image relative to content. */
+  position: 'top' | 'bottom';
+};
+
+type OnboardingStepCustom = {
+  /**
+   * Custom step renderer. Receives navigation helpers and state.
+   */
+  component: (props: {
+    /** Advance to the next step. */
+    onNext: () => void;
+    /** Go back to the previous step. */
+    onBack: () => void;
+    /** True if this is the last step. */
+    isLast: boolean;
+  }) => ReactNode;
+
+  /** Image displayed alongside the custom step. */
+  image: ImageSourcePropType;
+
+  /** Placement of the image relative to content. */
+  position: 'top' | 'bottom';
+};
+
+/**
+ * A single onboarding step. Either a default text-based step or a fully custom component.
+ */
+export type OnboardingStep = OnboardingStepDefault | OnboardingStepCustom;
+
+/**
+ * Props consumed by the internal step panel component.
+ */
+export interface OnboardingStepPanelProps {
+  /** Optional small label displayed above the title. */
+  label?: string;
+
+  /** Step title text. */
+  title: string;
+
+  /** Step description text. */
+  description: string;
+
+  /** Label for the primary action button. */
+  buttonLabel: string;
+
+  /** Handler for the back button. */
+  onBackPress?: () => void;
+
+  /** Handler for the next/continue button. */
+  onNextPress: () => void;
+
+  /** Whether the primary styling should be applied to the button. */
+  buttonPrimary: boolean;
+
+  /** Controls visibility of the back button. */
+  showBackButton?: boolean;
+}
+
+type OnboardingIntroPanel =
+  | Omit<OnboardingIntroPanelProps, 'onPressStart'>
+  | (({ onPressStart }: { onPressStart: () => void }) => ReactNode);
+
+/**
+ * Top-level props for the `Onboarding` component.
+ */
+export interface OnboardingProps {
+  /** Duration in milliseconds for step transition animations. */
+  animationDuration?: number;
+
+  /**
+   * Intro panel content. Either props for the default panel (without `onPressStart`)
+   * or a render function receiving `onPressStart` for a fully custom intro.
+   */
+  introPanel: OnboardingIntroPanel;
+
+  /** Ordered list of steps to render. */
+  steps: OnboardingStep[];
+
+  /** Called when the user completes the final step. */
+  onComplete: () => void;
+
+  /** Called when the user skips the onboarding. */
+  onSkip?: () => void;
+
+  /** Notifies consumers when the active step index changes. */
+  onStepChange?: (stepIndex: number) => void;
+
+  /** Whether to show the close button in the header. */
+  showCloseButton?: boolean;
+
+  /** Whether to show a back button on steps */
+  showBackButton?: boolean;
+
+  /** Whether to wrap the onboarding in a modal on web. */
+  wrapInModalOnWeb?: boolean;
+
+  /** Optional custom background element rendered behind content. */
+  background?: () => ReactNode;
+
+  /** Optional custom close button renderer. */
+  skipButton?: ({ onPress }: { onPress: () => void }) => ReactNode;
+
+  /** Theme colors to use for styling. */
+  colors?: OnboardingColors;
+
+  /** Font family set or a single family name applied where appropriate. */
+  fonts?: OnboardingFonts | string;
+
+  /**
+   * API Key for analytics.
+   * Required to enable analytics tracking.
+   */
+  apiKey: string;
+}

package/src/utils/ThemeContext.tsx

@@ -0,0 +1,87 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import { defaultTheme, type Theme } from './theme';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import {
+  type OnboardingColors,
+  type OnboardingFonts,
+} from '../spill-onboarding/types';
+
+const ThemeContext = createContext<{ theme: Theme }>({
+  theme: {
+    ...defaultTheme,
+    insets: { top: 0, bottom: 0, left: 0, right: 0 },
+  },
+});
+
+interface ThemeProviderProps {
+  children: React.ReactNode;
+  colors?: OnboardingColors;
+  fonts?: OnboardingFonts | string;
+}
+
+export default function ThemeProvider({
+  children,
+  colors: customColors,
+  fonts: customFonts,
+}: ThemeProviderProps) {
+  const insets = useSafeAreaInsets();
+
+  const theme: Theme = useMemo(() => {
+    const fonts =
+      typeof customFonts === 'string'
+        ? {
+            introTitle: customFonts,
+            introSubtitle: customFonts,
+            introButton: customFonts,
+            stepLabel: customFonts,
+            stepTitle: customFonts,
+            stepDescription: customFonts,
+            stepButton: customFonts,
+            primaryButton: customFonts,
+            secondaryButton: customFonts,
+          }
+        : {
+            introTitle:
+              customFonts?.introTitle ?? defaultTheme.fonts.introTitle,
+            introSubtitle:
+              customFonts?.introSubtitle ?? defaultTheme.fonts.introSubtitle,
+            introButton:
+              customFonts?.introButton ?? defaultTheme.fonts.introButton,
+            stepLabel: customFonts?.stepLabel ?? defaultTheme.fonts.stepLabel,
+            stepTitle: customFonts?.stepTitle ?? defaultTheme.fonts.stepTitle,
+            stepDescription:
+              customFonts?.stepDescription ??
+              defaultTheme.fonts.stepDescription,
+            stepButton:
+              customFonts?.stepButton ?? defaultTheme.fonts.stepButton,
+            primaryButton:
+              customFonts?.primaryButton ?? defaultTheme.fonts.primaryButton,
+            secondaryButton:
+              customFonts?.secondaryButton ??
+              defaultTheme.fonts.secondaryButton,
+          };
+
+    const { background, text: textColors } = customColors ?? {};
+    const bg = {
+      primary: background?.primary ?? defaultTheme.bg.primary,
+      secondary: background?.secondary ?? defaultTheme.bg.secondary,
+      label: background?.label ?? defaultTheme.bg.label,
+      accent: background?.accent ?? defaultTheme.bg.accent,
+    };
+    const text = {
+      primary: textColors?.primary ?? defaultTheme.text.primary,
+      secondary: textColors?.secondary ?? defaultTheme.text.secondary,
+      contrast: textColors?.contrast ?? defaultTheme.text.contrast,
+    };
+
+    return { bg, text, fonts, insets };
+  }, [insets, customColors, customFonts]);
+
+  return (
+    <ThemeContext.Provider value={{ theme }}>{children}</ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  return useContext(ThemeContext);
+}

package/src/utils/fontStyles.ts

@@ -0,0 +1,19 @@
+export const fontSizes = {
+  xxl: 34,
+  xl: 22,
+  lg: 18,
+  md: 16,
+  sm: 14,
+  xs: 12,
+  xxs: 10,
+};
+
+export const lineHeights = {
+  xxl: 40,
+  xl: 28,
+  lg: 24,
+  md: 24,
+  sm: 20,
+  xs: 16,
+  xxs: 12,
+};

package/src/utils/theme.ts

@@ -0,0 +1,29 @@
+import type { EdgeInsets } from 'react-native-safe-area-context';
+
+export const defaultTheme = {
+  bg: {
+    primary: '#007AFF',
+    secondary: '#FFFFFF',
+    label: '#F2F2F7',
+    accent: '#1C1C1E',
+  },
+  text: {
+    primary: '#1C1C1E',
+    secondary: '#8E8E93',
+    contrast: '#FFFFFF',
+  },
+  fonts: {
+    introTitle: 'System',
+    introSubtitle: 'System',
+    introButton: 'System',
+    stepLabel: 'System',
+    stepTitle: 'System',
+    stepDescription: 'System',
+    stepButton: 'System',
+    primaryButton: 'System',
+    secondaryButton: 'System',
+  },
+};
+
+export type ThemeColors = typeof defaultTheme;
+export type Theme = ThemeColors & { insets: EdgeInsets };