flowboard-react 0.1.0

package/src/components/FlowboardFlow.tsx

@@ -0,0 +1,513 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Alert, Keyboard, Platform, StyleSheet, View } from 'react-native';
+import PagerView, {
+  type PagerViewOnPageSelectedEvent,
+} from 'react-native-pager-view';
+import { Linking } from 'react-native';
+import InAppReview from 'react-native-in-app-review';
+import {
+  openSettings,
+  PERMISSIONS,
+  request,
+  requestNotifications,
+  RESULTS,
+} from 'react-native-permissions';
+import { AssetPreloader } from '../core/assetPreloader';
+import { AnalyticsManager, OnboardingOutcome } from '../core/analyticsManager';
+import { OnboardingRepository } from '../core/onboardingRepository';
+import FlowboardRenderer from './FlowboardRenderer';
+import {
+  SliderRegistry,
+  SliderRegistryProvider,
+} from './widgets/sliderRegistry';
+import type {
+  CustomActionBuilder,
+  CustomScreenBuilder,
+  FlowboardContext,
+  FlowboardData,
+  OnboardingEndCallback,
+  OnStepChangeCallback,
+} from '../types/flowboard';
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: 'transparent' },
+  fullFlex: { flex: 1 },
+});
+
+type FlowboardFlowProps = {
+  data: FlowboardData;
+  customScreenBuilder?: CustomScreenBuilder;
+  customActionBuilder?: CustomActionBuilder;
+  onOnboardEnd?: OnboardingEndCallback;
+  onStepChange?: OnStepChangeCallback;
+  initialStep?: number;
+  initialFormData?: Record<string, any>;
+  onClose?: () => void;
+};
+
+export default function FlowboardFlow(props: FlowboardFlowProps) {
+  const {
+    data,
+    customScreenBuilder,
+    customActionBuilder,
+    onOnboardEnd,
+    onStepChange,
+    initialStep = 0,
+    initialFormData = {},
+    onClose,
+  } = props;
+
+  const screens = Array.isArray(data.screens) ? data.screens : [];
+  const flowId = data.flow_id as string | undefined;
+  const repository = useMemo(() => new OnboardingRepository(), []);
+  const assetPreloader = useMemo(() => new AssetPreloader(), []);
+  const sliderRegistry = useMemo(() => new SliderRegistry(), []);
+  const pagerRef = useRef<PagerView>(null);
+  const [currentIndex, setCurrentIndex] = useState(() =>
+    resolveInitialPage(initialStep, screens.length)
+  );
+  const [formData, setFormData] = useState<Record<string, any>>({
+    ...initialFormData,
+  });
+  const completedRef = useRef(false);
+  const flowStartTimeRef = useRef(Date.now());
+
+  useEffect(() => {
+    AnalyticsManager.instance.startSession({ flowData: data });
+    AnalyticsManager.instance.trackOnboardStarted();
+
+    requestAnimationFrame(() => {
+      preloadAssets(currentIndex);
+      notifyStepChange(currentIndex);
+    });
+
+    return () => {
+      if (!completedRef.current) {
+        trackCompletion(OnboardingOutcome.dismissed, currentIndex);
+      }
+      AnalyticsManager.instance.endSession();
+      assetPreloader.clear();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (pagerRef.current) {
+      pagerRef.current.setPageWithoutAnimation(currentIndex);
+    }
+  }, [currentIndex]);
+
+  const notifyStepChange = (index: number) => {
+    if (index < 0 || index >= screens.length) return;
+    const screenData = screens[index] as Record<string, any>;
+    const pageId = screenData.id ?? 'unknown';
+
+    AnalyticsManager.instance.trackScreenView({
+      stepId: pageId,
+      stepIndex: index,
+      stepName: screenData.name,
+    });
+
+    if (onStepChange) {
+      onStepChange(pageId, index, { ...formData });
+    }
+
+    persistProgress(index);
+    preloadAssets(index);
+  };
+
+  const persistProgress = (index: number) => {
+    if (!flowId) return;
+    repository
+      .saveProgress({ flowId, stepIndex: index, formData: { ...formData } })
+      .catch(() => null);
+  };
+
+  const resetStoredProgress = () => {
+    repository.clearProgress().catch(() => null);
+  };
+
+  const preloadAssets = (index: number) => {
+    const currentScreen = screens[index];
+    if (currentScreen) {
+      assetPreloader.preloadScreenAssets(currentScreen).catch(() => null);
+    }
+    const nextScreen = screens[index + 1];
+    if (nextScreen) {
+      assetPreloader.preloadScreenAssets(nextScreen).catch(() => null);
+    }
+  };
+
+  const trackCompletion = (outcome: OnboardingOutcome, index: number) => {
+    if (completedRef.current) return;
+    completedRef.current = true;
+    assetPreloader.clear();
+
+    const duration = Date.now() - flowStartTimeRef.current;
+    let finalStepId = 'unknown';
+    if (screens[index]) {
+      finalStepId = screens[index].id ?? 'unknown';
+    } else if (screens[0]) {
+      finalStepId = screens[0].id ?? 'unknown';
+    }
+
+    AnalyticsManager.instance.trackOnboardEnded({
+      outcome,
+      totalDurationMs: duration,
+      finalStepId,
+    });
+  };
+
+  const createContext = (index: number): FlowboardContext => ({
+    context: null,
+    currentIndex: index,
+    totalScreens: screens.length,
+    formData: { ...formData },
+    screenData: screens[index] as Record<string, any>,
+    onNext: () => handleAction('next', index, screens.length),
+    onPrevious: () => handleAction('previous', index, screens.length),
+    onFinish: () => handleAction('finish', index, screens.length),
+  });
+
+  const handleAction = (
+    action: string,
+    index: number,
+    totalScreens: number,
+    dataPayload?: Record<string, any>
+  ) => {
+    Keyboard.dismiss();
+
+    if (action === 'next') {
+      const currentScreen = screens[index] as Record<string, any>;
+      const invalidFields = validateScreen(currentScreen, formData);
+      if (invalidFields.length > 0) {
+        Alert.alert(
+          'Validation',
+          'Please fill in all required fields properly.'
+        );
+        return;
+      }
+
+      if (index < totalScreens - 1) {
+        setCurrentIndex(index + 1);
+      } else {
+        trackCompletion(OnboardingOutcome.completed, index);
+        onOnboardEnd?.({ ...formData });
+        resetStoredProgress();
+        onClose?.();
+      }
+      return;
+    }
+
+    if (action === 'previous') {
+      if (index > 0) {
+        setCurrentIndex(index - 1);
+      }
+      return;
+    }
+
+    if (action === 'finish') {
+      trackCompletion(OnboardingOutcome.completed, index);
+      onOnboardEnd?.({ ...formData });
+      resetStoredProgress();
+      onClose?.();
+      return;
+    }
+
+    if (action === 'deeplink' || action === 'weblink') {
+      handleLinkAction(index, dataPayload);
+      return;
+    }
+
+    if (action === 'rate_app') {
+      handleRateAppAction(index, totalScreens);
+      return;
+    }
+
+    if (action === 'request_permission') {
+      handlePermissionAction(index, totalScreens, dataPayload);
+      return;
+    }
+
+    const customHandler = customActionBuilder;
+    if (!customHandler) return;
+    const ctx = createContext(index);
+    customHandler(action, ctx, dataPayload);
+  };
+
+  const handleLinkAction = async (
+    index: number,
+    dataPayload?: Record<string, any>
+  ) => {
+    const screenData = screens[index] as Record<string, any>;
+    let url = dataPayload?.url ?? screenData?.url;
+    if (!url) return;
+    try {
+      const canOpen = await Linking.canOpenURL(url);
+      if (canOpen) {
+        await Linking.openURL(url);
+      }
+    } catch {
+      // ignore
+    }
+  };
+
+  const handleRateAppAction = async (index: number, totalScreens: number) => {
+    try {
+      if (InAppReview.isAvailable()) {
+        InAppReview.RequestInAppReview();
+      }
+    } catch {
+      // ignore
+    }
+
+    if (index < totalScreens - 1) {
+      setCurrentIndex(index + 1);
+    } else {
+      trackCompletion(OnboardingOutcome.completed, index);
+      onOnboardEnd?.({ ...formData });
+      resetStoredProgress();
+      onClose?.();
+    }
+  };
+
+  const handlePermissionAction = async (
+    index: number,
+    totalScreens: number,
+    dataPayload?: Record<string, any>
+  ) => {
+    const permissionKey = String(
+      dataPayload?.actionPermission ??
+        dataPayload?.permission ??
+        dataPayload?.permissionType ??
+        ''
+    )
+      .trim()
+      .toLowerCase();
+
+    if (!permissionKey) {
+      Alert.alert('Permission', 'Permission type is missing for this action.');
+      return;
+    }
+
+    const result = await requestPermission(permissionKey);
+
+    if (result === RESULTS.UNAVAILABLE) {
+      Alert.alert(
+        'Permission',
+        `${formatPermissionName(permissionKey)} permission is not supported.`
+      );
+      return;
+    }
+
+    if (result === RESULTS.BLOCKED) {
+      Alert.alert(
+        'Permission',
+        `${formatPermissionName(
+          permissionKey
+        )} permission is permanently denied. Enable it in Settings.`,
+        [
+          { text: 'Cancel', style: 'cancel' },
+          { text: 'Settings', onPress: () => openSettings().catch(() => null) },
+        ]
+      );
+      return;
+    }
+
+    if (result === RESULTS.GRANTED || result === RESULTS.LIMITED) {
+      handleAction('next', index, totalScreens);
+      return;
+    }
+
+    Alert.alert(
+      'Permission',
+      `${formatPermissionName(
+        permissionKey
+      )} permission is required to continue.`
+    );
+  };
+
+  const handleInputChange = (id: string, value: any, index: number) => {
+    setFormData((prev) => {
+      const next = { ...prev, [id]: value };
+      return next;
+    });
+    persistProgress(index);
+  };
+
+  return (
+    <View style={styles.container}>
+      <PagerView
+        ref={pagerRef}
+        style={styles.fullFlex}
+        scrollEnabled={false}
+        initialPage={currentIndex}
+        onPageSelected={(event: PagerViewOnPageSelectedEvent) => {
+          const nextIndex = event.nativeEvent.position;
+          setCurrentIndex(nextIndex);
+          notifyStepChange(nextIndex);
+        }}
+      >
+        {screens.map((screen, index) => {
+          const screenData = screen as Record<string, any>;
+          const screenType = screenData.type;
+
+          if (screenType === 'custom' && customScreenBuilder) {
+            const ctx = createContext(index);
+            return (
+              <View key={`screen-${index}`} style={styles.fullFlex}>
+                {customScreenBuilder(ctx)}
+              </View>
+            );
+          }
+
+          return (
+            <View key={`screen-${index}`} style={styles.fullFlex}>
+              <SliderRegistryProvider registry={sliderRegistry}>
+                <FlowboardRenderer
+                  screenData={screenData}
+                  formData={formData}
+                  onInputChange={(id, value) =>
+                    handleInputChange(id, value, index)
+                  }
+                  onAction={(action, payload) =>
+                    handleAction(action, index, screens.length, payload)
+                  }
+                  currentIndex={index}
+                  totalScreens={screens.length}
+                />
+              </SliderRegistryProvider>
+            </View>
+          );
+        })}
+      </PagerView>
+    </View>
+  );
+}
+
+function resolveInitialPage(desired: number, total: number): number {
+  if (!total) return 0;
+  if (desired <= 0) return 0;
+  if (desired >= total) return total - 1;
+  return desired;
+}
+
+function validateScreen(
+  screenData: Record<string, any>,
+  formData: Record<string, any>
+): string[] {
+  const invalidFields: string[] = [];
+  const children = Array.isArray(screenData.children)
+    ? screenData.children
+    : [];
+
+  const checkWidget = (widget: Record<string, any>) => {
+    const id = widget.id;
+    const props = widget.properties ?? {};
+    const childrenJson = widget.children;
+    const childJson = widget.child;
+
+    if (id && props.required === true) {
+      const value = formData[id];
+      let isValid = true;
+
+      if (value === null || value === undefined) {
+        isValid = false;
+      } else if (typeof value === 'string' && value.trim() === '') {
+        isValid = false;
+      } else if (Array.isArray(value) && value.length === 0) {
+        isValid = false;
+      }
+
+      if (
+        isValid &&
+        typeof value === 'string' &&
+        props.regex &&
+        String(props.regex).length > 0
+      ) {
+        try {
+          const reg = new RegExp(props.regex);
+          if (!reg.test(value)) {
+            isValid = false;
+          }
+        } catch {
+          // ignore invalid regex
+        }
+      }
+
+      if (!isValid) invalidFields.push(id);
+    }
+
+    if (Array.isArray(childrenJson)) {
+      childrenJson.forEach((child) => {
+        if (child && typeof child === 'object') checkWidget(child);
+      });
+    }
+    if (childJson && typeof childJson === 'object') {
+      checkWidget(childJson);
+    }
+  };
+
+  children.forEach((child) => {
+    if (child && typeof child === 'object') checkWidget(child);
+  });
+
+  return invalidFields;
+}
+
+async function requestPermission(permissionKey: string) {
+  switch (permissionKey) {
+    case 'push_notifications':
+    case 'notifications': {
+      const result = await requestNotifications(['alert', 'sound', 'badge']);
+      return result.status;
+    }
+    case 'contacts':
+      return request(
+        PERMISSIONS.IOS.CONTACTS ?? PERMISSIONS.ANDROID.READ_CONTACTS
+      );
+    case 'location':
+      return request(
+        Platform.select({
+          ios: PERMISSIONS.IOS.LOCATION_WHEN_IN_USE,
+          android: PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION,
+        }) as any
+      );
+    case 'camera':
+      return request(
+        Platform.select({
+          ios: PERMISSIONS.IOS.CAMERA,
+          android: PERMISSIONS.ANDROID.CAMERA,
+        }) as any
+      );
+    case 'microphone':
+      return request(
+        Platform.select({
+          ios: PERMISSIONS.IOS.MICROPHONE,
+          android: PERMISSIONS.ANDROID.RECORD_AUDIO,
+        }) as any
+      );
+    case 'photos':
+    case 'photo_library':
+      return request(
+        Platform.select({
+          ios: PERMISSIONS.IOS.PHOTO_LIBRARY,
+          android:
+            PERMISSIONS.ANDROID.READ_MEDIA_IMAGES ??
+            PERMISSIONS.ANDROID.READ_EXTERNAL_STORAGE,
+        }) as any
+      );
+    default:
+      return RESULTS.UNAVAILABLE;
+  }
+}
+
+function formatPermissionName(key: string): string {
+  return key
+    .replace(/_/g, ' ')
+    .trim()
+    .split(' ')
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(' ');
+}