rn-onboarding-analytics 1.0.0

package/package.json

@@ -0,0 +1,177 @@
+{
+  "name": "rn-onboarding-analytics",
+  "version": "1.0.0",
+  "description": "Onboarding/tutorial flow for React Native with analytics.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc",
+    "lint:fix": "eslint \"**/*.{js,ts,tsx}\" --fix",
+    "clean": "del-cli lib",
+    "prepare": "bob build",
+    "prepack": "sed -i '' '1s|.*|![Banner](assets/banner.png)|' README.md",
+    "postpack": "git checkout README.md",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "analytics"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ryan-Carloso/react-native-onboarding-w-analytics.git"
+  },
+  "author": "Ryan Carloso <carlosoryan@gmail.com> (https://github.com/Ryan-Carloso)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Ryan-Carloso/react-native-onboarding-w-analytics/issues"
+  },
+  "homepage": "https://github.com/Ryan-Carloso/react-native-onboarding-w-analytics#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/compat": "^1.3.2",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.35.0",
+    "@evilmartians/lefthook": "^1.12.3",
+    "@react-native/babel-preset": "0.81.1",
+    "@react-native/eslint-config": "^0.81.1",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.12",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "expo-image": "^3.0.8",
+    "jest": "^29.7.0",
+    "prettier": "^3.6.2",
+    "react": "19.1.0",
+    "react-native": "0.81.4",
+    "react-native-builder-bob": "^0.40.13",
+    "react-native-reanimated": "4",
+    "react-native-safe-area-context": "^5.6.1",
+    "react-native-svg": "^15.13.0",
+    "react-native-worklets": "^0.5.1",
+    "release-it": "^19.0.4",
+    "typescript": "5.6.3"
+  },
+  "peerDependencies": {
+    "expo-image": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-reanimated": "*",
+    "react-native-safe-area-context": "*",
+    "react-native-svg": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-image": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@3.6.1",
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "create-react-native-library": {
+    "languages": "js",
+    "type": "library",
+    "version": "0.54.3"
+  },
+  "dependencies": {
+    "expo-constants": "^18.0.12",
+    "expo-localization": "^17.0.8"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,35 @@
+import ThemeProvider from './utils/ThemeContext';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import {
+  type OnboardingProps,
+  type OnboardingColors,
+  type OnboardingFonts,
+  type OnboardingIntroPanelProps,
+  type OnboardingStepPanelProps,
+  type OnboardingStep,
+} from './spill-onboarding/types';
+import SpillOnboarding from './spill-onboarding';
+import { Platform } from 'react-native';
+import React from 'react';
+
+function Onboarding({ colors, fonts, ...props }: OnboardingProps) {
+  const SafeArea = Platform.OS === 'web' ? React.Fragment : SafeAreaProvider;
+
+  return (
+    <SafeArea>
+      <ThemeProvider colors={colors} fonts={fonts}>
+        <SpillOnboarding {...props} />
+      </ThemeProvider>
+    </SafeArea>
+  );
+}
+
+export default Onboarding;
+export type {
+  OnboardingProps,
+  OnboardingColors,
+  OnboardingFonts,
+  OnboardingIntroPanelProps,
+  OnboardingStepPanelProps,
+  OnboardingStep,
+};

package/src/spill-onboarding/adapters/expo-image.ts

@@ -0,0 +1,12 @@
+import { type Image as ExpoImageType } from 'expo-image';
+
+let ExpoImage: typeof ExpoImageType | null = null;
+
+try {
+  const { Image } = require('expo-image');
+  ExpoImage = Image;
+} catch {
+  // expo-image not available
+}
+
+export { ExpoImage };

package/src/spill-onboarding/adapters/react-native-svg.ts

@@ -0,0 +1,17 @@
+import {
+  type Svg as RNSVGType,
+  type Path as RNSVGPathType,
+} from 'react-native-svg';
+
+let ReactNativeSVG: typeof RNSVGType | null = null;
+let ReactNativeSVGPath: typeof RNSVGPathType | null = null;
+
+try {
+  const { Svg, Path } = require('react-native-svg');
+  ReactNativeSVG = Svg;
+  ReactNativeSVGPath = Path;
+} catch {
+  // react-native-svg not available
+}
+
+export { ReactNativeSVG, ReactNativeSVGPath };

package/src/spill-onboarding/analytics.ts

@@ -0,0 +1,75 @@
+import { Platform } from 'react-native';
+import Constants from 'expo-constants';
+import * as Localization from 'expo-localization';
+
+// TODO: need to get an better domain
+const API_URL = 'https://api.freesupabase.shop/api/track';
+
+export const trackEvent = async (
+  apiKey: string | undefined,
+  eventType: string,
+  metaData: any = {}
+) => {
+  const token = apiKey;
+  const appName =
+    Constants.expoConfig?.name ||
+    Constants.manifest?.name ||
+    'react-native-app';
+  const locales = Localization.getLocales();
+  const primaryLocale = locales[0];
+
+  const extendedMetaData = {
+    ...metaData,
+    locale: primaryLocale?.languageTag,
+    region: primaryLocale?.regionCode,
+    language: primaryLocale?.languageCode,
+  };
+
+  if (!token) {
+    console.error(
+      JSON.stringify({
+        error: 'Go to `https://freesupabase.shop/docs` to get an app token',
+      })
+    );
+    return;
+  }
+
+  const payload = {
+    app_id: token,
+    eventType,
+    userAgent: `React Native (${Platform.OS})`,
+    sourceUrl: appName,
+    metaData: extendedMetaData,
+  };
+
+  console.log('📡 Sending Analytics Event:', JSON.stringify(payload, null, 2));
+
+  try {
+    const response = await fetch(API_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      if (response.status === 401) {
+        console.error(
+          JSON.stringify({
+            error: 'Go to `https://freesupabase.shop/docs` to get an app token',
+          })
+        );
+      } else {
+        console.error(
+          'Analytics error:',
+          response.status,
+          await response.text()
+        );
+      }
+    }
+  } catch (error) {
+    console.error('Failed to send analytics event:', error);
+  }
+};

package/src/spill-onboarding/buttons/PrimaryButton.tsx

@@ -0,0 +1,70 @@
+import React, { useMemo } from 'react';
+import {
+  TouchableOpacity,
+  Text,
+  StyleSheet,
+  type ViewStyle,
+  type TextStyle,
+  type GestureResponderEvent,
+} from 'react-native';
+import { useTheme } from '../../utils/ThemeContext';
+import { fontSizes } from '../../utils/fontStyles';
+import type { Theme } from '../../utils/theme';
+
+interface Props {
+  text: string;
+  onPress: (event: GestureResponderEvent) => void;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+  style?: ViewStyle;
+  textStyle?: TextStyle;
+}
+
+const PrimaryButton = ({
+  text,
+  onPress,
+  icon,
+  disabled = false,
+  style,
+  textStyle,
+}: Props) => {
+  const { theme } = useTheme();
+  const styles = useMemo(
+    () => createStyles(theme, disabled),
+    [theme, disabled]
+  );
+
+  return (
+    <TouchableOpacity
+      onPress={onPress}
+      disabled={disabled}
+      style={[styles.button, style]}
+    >
+      {icon}
+      <Text style={[styles.text, textStyle]}>{text}</Text>
+    </TouchableOpacity>
+  );
+};
+
+export default PrimaryButton;
+
+const createStyles = (theme: Theme, disabled: boolean) =>
+  StyleSheet.create({
+    button: {
+      height: 48,
+      width: '100%',
+      borderRadius: 12,
+      paddingHorizontal: 10,
+      justifyContent: 'center',
+      alignItems: 'center',
+      backgroundColor: theme.bg.primary,
+      opacity: disabled ? 0.4 : 1,
+      flexDirection: 'row',
+      gap: 2,
+    },
+    text: {
+      fontFamily: theme.fonts.primaryButton,
+      fontSize: fontSizes.md,
+      color: theme.text.contrast,
+    },
+  });

package/src/spill-onboarding/buttons/SecondaryButton.tsx

@@ -0,0 +1,71 @@
+import React, { useMemo } from 'react';
+import {
+  TouchableOpacity,
+  Text,
+  StyleSheet,
+  type ViewStyle,
+  type TextStyle,
+  type GestureResponderEvent,
+} from 'react-native';
+import { useTheme } from '../../utils/ThemeContext';
+import { fontSizes } from '../../utils/fontStyles';
+import type { Theme } from '../../utils/theme';
+
+interface Props {
+  text: string;
+  onPress: (event: GestureResponderEvent) => void;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+  style?: ViewStyle;
+  textStyle?: TextStyle;
+}
+
+const SecondaryButton = ({
+  text,
+  onPress,
+  icon,
+  disabled = false,
+  style,
+  textStyle,
+}: Props) => {
+  const { theme } = useTheme();
+  const styles = useMemo(
+    () => createStyles(theme, disabled),
+    [theme, disabled]
+  );
+
+  return (
+    <TouchableOpacity
+      onPress={onPress}
+      disabled={disabled}
+      style={[styles.button, style]}
+    >
+      {icon}
+      {!!text && <Text style={[styles.text, textStyle]}>{text}</Text>}
+    </TouchableOpacity>
+  );
+};
+
+export default SecondaryButton;
+
+const createStyles = (theme: Theme, disabled: boolean) =>
+  StyleSheet.create({
+    button: {
+      height: 48,
+      paddingHorizontal: 10,
+      alignItems: 'center',
+      justifyContent: 'center',
+      borderWidth: 1,
+      borderRadius: 12,
+      borderColor: theme.bg.accent,
+      opacity: disabled ? 0.4 : 1,
+      flexDirection: 'row',
+      gap: 2,
+    },
+    text: {
+      fontFamily: theme.fonts.secondaryButton,
+      fontSize: fontSizes.sm,
+      color: theme.text.primary,
+      lineHeight: 20,
+    },
+  });

package/src/spill-onboarding/buttons/SkipButton.tsx

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+import { StyleSheet, TouchableOpacity } from 'react-native';
+import { useTheme } from '../../utils/ThemeContext';
+import { type Theme } from '../../utils/theme';
+import CloseIcon from '../icons/CloseIcon';
+
+interface Props {
+  onPress: () => void;
+}
+
+function SkipButton({ onPress }: Props) {
+  const { theme } = useTheme();
+  const styles = useMemo(() => createStyles(theme), [theme]);
+
+  return (
+    <TouchableOpacity style={styles.wrapper} onPress={onPress}>
+      <CloseIcon color={theme.text.primary} size={24} />
+    </TouchableOpacity>
+  );
+}
+
+export default SkipButton;
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    wrapper: {
+      backgroundColor: theme.bg.secondary,
+      width: 32,
+      height: 32,
+      borderRadius: 6,
+      justifyContent: 'center',
+      alignItems: 'center',
+    },
+  });

package/src/spill-onboarding/components/OnboardingImageContainer.tsx

@@ -0,0 +1,181 @@
+import { useMemo, type ReactNode } from 'react';
+import {
+  Image,
+  type ImageSourcePropType,
+  Platform,
+  StyleSheet,
+  useWindowDimensions,
+} from 'react-native';
+import Animated, {
+  interpolate,
+  useDerivedValue,
+  useAnimatedStyle,
+  withTiming,
+  Easing,
+  type SharedValue,
+  useSharedValue,
+} from 'react-native-reanimated';
+import { useTheme } from '../../utils/ThemeContext';
+import useMeasureHeight from '../hooks/useMeasureHeight';
+import type { Theme } from '../../utils/theme';
+import type { OnboardingStep } from '../types';
+import { ExpoImage } from '../adapters/expo-image';
+
+interface OnboardingImageContainerProps {
+  currentStep: OnboardingStep | undefined;
+  currentStepImage: ImageSourcePropType | undefined;
+  position: 'top' | 'bottom';
+  animationDuration: number;
+  backgroundSpillProgress: SharedValue<number>;
+  introPanel: any;
+  stepPanel: any;
+  screenHeight: number;
+  background?: () => ReactNode;
+}
+
+function OnboardingImageContainer({
+  currentStep,
+  currentStepImage,
+  position,
+  animationDuration,
+  backgroundSpillProgress,
+  introPanel,
+  stepPanel,
+  screenHeight,
+  background,
+}: OnboardingImageContainerProps) {
+  const { theme } = useTheme();
+  const image = useMeasureHeight();
+  const styles = useMemo(() => createStyles(theme), [theme]);
+  const extraPadding = Platform.OS === 'web' ? 16 : 0;
+  const { width: screenWidth } = useWindowDimensions();
+
+  // bottom panel height (intro or step)
+  const bottomPanelHeight = (currentStep ? stepPanel : introPanel).height || 0;
+
+  /**
+   * When 0 -> no spill; when 1 -> fully spilled by bottomPanelHeight
+   */
+  const backgroundSpillDistance = useDerivedValue(() =>
+    interpolate(backgroundSpillProgress.value, [0, 1], [0, bottomPanelHeight])
+  );
+
+  const imageWrapperHeight = useDerivedValue(
+    () => screenHeight - bottomPanelHeight + backgroundSpillDistance.value
+  );
+
+  const imageWrapperAnimation = useAnimatedStyle(() => ({
+    height: imageWrapperHeight.value,
+  }));
+
+  const imageTargetY = useDerivedValue(() => {
+    const topSafe = theme.insets.top + extraPadding + 16;
+
+    if (position === 'top') {
+      return topSafe;
+    }
+
+    const imageH = image.height || 0;
+    const modalTop = screenHeight - bottomPanelHeight - 16;
+    const yBottom = modalTop - imageH;
+
+    const shouldClampTop = !currentStep;
+    return shouldClampTop ? Math.max(yBottom, topSafe) : yBottom;
+  });
+
+  const hasMounted = useSharedValue(false);
+
+  const imageAnimation = useAnimatedStyle(() => {
+    const translateY = withTiming(
+      imageTargetY.value,
+      {
+        duration: hasMounted.value ? animationDuration : 0,
+        easing: Easing.out(Easing.cubic),
+      },
+      () => (hasMounted.value = true)
+    );
+    const sideEdges = Math.max(32 + 24 - backgroundSpillDistance.value, 0);
+
+    return {
+      transform: [{ translateY }],
+      maxWidth: screenWidth - sideEdges,
+    };
+  }, [animationDuration]);
+
+  const backgroundAnimation = useAnimatedStyle(() => {
+    const topEdge = Math.max(
+      theme.insets.top + extraPadding - backgroundSpillDistance.value,
+      0
+    );
+    const sideEdge = Math.max(16 - backgroundSpillDistance.value, 0);
+
+    return {
+      position: 'absolute',
+      top: topEdge,
+      left: sideEdge,
+      right: sideEdge,
+      bottom: screenHeight - imageWrapperHeight.value,
+      borderRadius: Math.max(12 - backgroundSpillDistance.value, 0),
+    };
+  });
+
+  return (
+    <>
+      {background ? (
+        <Animated.View style={backgroundAnimation}>
+          {background()}
+        </Animated.View>
+      ) : (
+        <Animated.View style={[styles.colorBg, backgroundAnimation]} />
+      )}
+
+      {currentStepImage && (
+        <Animated.View style={[styles.imageWrapper, imageWrapperAnimation]}>
+          <Animated.View style={[styles.image, imageAnimation]} ref={image.ref}>
+            {ExpoImage ? (
+              <ExpoImage
+                source={currentStepImage}
+                contentFit="contain"
+                transition={0}
+                style={styles.imageStyle}
+              />
+            ) : (
+              <Image
+                source={currentStepImage}
+                resizeMode="contain"
+                fadeDuration={0}
+                style={styles.imageStyle}
+              />
+            )}
+          </Animated.View>
+        </Animated.View>
+      )}
+    </>
+  );
+}
+
+export default OnboardingImageContainer;
+
+const createStyles = (theme: Theme) =>
+  StyleSheet.create({
+    colorBg: {
+      backgroundColor: theme.bg.primary,
+      overflow: 'hidden',
+    },
+    imageWrapper: {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      right: 0,
+      overflow: 'hidden',
+    },
+    image: {
+      alignSelf: 'center',
+      alignItems: 'center',
+      overflow: 'hidden',
+    },
+    imageStyle: {
+      width: 300,
+      height: 600,
+    },
+  });