@primer-io/react-native 2.45.0 → 3.0.0-beta.0

package/src/Components/internal/navigation/NavigationContainer.tsx

@@ -0,0 +1,176 @@
+import React, { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { View, Animated, StyleSheet, useWindowDimensions } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import { NavigationContext, RouteEntryContext } from './NavigationContext';
+import { usePrimerTheme } from '../theme';
+import type { CheckoutRoute, RouteEntry } from './types';
+
+const TRANSITION_DURATION = 250;
+
+type TransitionType = 'push' | 'pop' | 'replace' | 'none';
+
+interface NavigationContainerProps {
+  screenMap: Partial<Record<CheckoutRoute, React.ComponentType>>;
+}
+
+interface TransitionState {
+  type: TransitionType;
+  outgoingEntry: RouteEntry | null;
+}
+
+const NO_TRANSITION: TransitionState = { type: 'none', outgoingEntry: null };
+
+export function NavigationContainer({ screenMap }: NavigationContainerProps) {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    throw new Error('NavigationContainer must be used within a NavigationProvider');
+  }
+
+  const tokens = usePrimerTheme();
+  const { width } = useWindowDimensions();
+  const { state } = context;
+  const current = state.stack[state.stack.length - 1]!;
+
+  const prevEntryRef = useRef<RouteEntry>(current);
+  const prevStackLengthRef = useRef(state.stack.length);
+  const animValue = useRef(new Animated.Value(1)).current;
+  const needsAnimationRef = useRef(false);
+
+  const [transition, setTransition] = useState<TransitionState>(NO_TRANSITION);
+
+  // Detect transition synchronously during render — before paint
+  if (prevEntryRef.current.key !== current.key) {
+    let type: TransitionType;
+    if (state.stack.length > prevStackLengthRef.current) {
+      type = 'push';
+    } else if (state.stack.length < prevStackLengthRef.current) {
+      type = 'pop';
+    } else {
+      type = 'replace';
+    }
+
+    setTransition({ type, outgoingEntry: prevEntryRef.current });
+    animValue.setValue(0);
+    needsAnimationRef.current = true;
+
+    prevEntryRef.current = current;
+    prevStackLengthRef.current = state.stack.length;
+  }
+
+  const onTransitionEnd = useCallback(() => {
+    setTransition(NO_TRANSITION);
+    context.setAnimating(false);
+  }, [context]);
+
+  useEffect(() => {
+    if (!needsAnimationRef.current) return;
+    needsAnimationRef.current = false;
+
+    context.setAnimating(true);
+
+    Animated.timing(animValue, {
+      toValue: 1,
+      duration: TRANSITION_DURATION,
+      useNativeDriver: true,
+    }).start(({ finished }) => {
+      if (finished) {
+        onTransitionEnd();
+      }
+    });
+  }, [transition, context, animValue, onTransitionEnd]);
+
+  const ScreenComponent = screenMap[current.route];
+  const OutgoingComponent = transition.outgoingEntry ? screenMap[transition.outgoingEntry.route] : null;
+
+  if (!ScreenComponent) {
+    return null;
+  }
+
+  // Always render the current screen inside a stable Animated.View wrapper keyed by its route.
+  // The outgoing screen is rendered as a sibling only during transitions. Consequence: the
+  // current screen's component instance is preserved across transition start/end — no remount,
+  // no useEffect re-runs caused by the container swapping tree shapes.
+  const bg = { backgroundColor: tokens.colors.background };
+  const currentZIndex = transition.type === 'pop' ? 1 : 2;
+  const outgoingZIndex = transition.type === 'pop' ? 2 : 1;
+  const showOutgoing = transition.type !== 'none' && !!OutgoingComponent && !!transition.outgoingEntry;
+
+  return (
+    <View style={styles.container}>
+      <Animated.View
+        key={`screen-${current.key}`}
+        style={[styles.screen, bg, { zIndex: currentZIndex }, renderCurrentAnim(transition.type, animValue, width)]}
+      >
+        <RouteEntryContext.Provider value={current}>
+          <ScreenComponent />
+        </RouteEntryContext.Provider>
+      </Animated.View>
+      {showOutgoing && OutgoingComponent && transition.outgoingEntry && (
+        <Animated.View
+          key={`screen-${transition.outgoingEntry.key}`}
+          style={[styles.screen, bg, { zIndex: outgoingZIndex }, renderOutgoingAnim(transition.type, animValue, width)]}
+        >
+          <RouteEntryContext.Provider value={transition.outgoingEntry}>
+            <OutgoingComponent />
+          </RouteEntryContext.Provider>
+        </Animated.View>
+      )}
+    </View>
+  );
+}
+
+// Animated styles use the Animated.View's style prop type, which is wider than the
+// static StyleProp<ViewStyle>. Returning `Animated.WithAnimatedValue<ViewStyle>`
+// keeps full type safety without resorting to `any`.
+function renderCurrentAnim(
+  type: TransitionType,
+  animValue: Animated.Value,
+  width: number
+): Animated.WithAnimatedValue<ViewStyle> | null {
+  switch (type) {
+    case 'replace':
+      return { opacity: animValue };
+    case 'push':
+      return {
+        transform: [{ translateX: animValue.interpolate({ inputRange: [0, 1], outputRange: [width, 0] }) }],
+      };
+    case 'pop':
+      return {
+        transform: [{ translateX: animValue.interpolate({ inputRange: [0, 1], outputRange: [-width * 0.3, 0] }) }],
+      };
+    case 'none':
+    default:
+      return null;
+  }
+}
+
+function renderOutgoingAnim(
+  type: TransitionType,
+  animValue: Animated.Value,
+  width: number
+): Animated.WithAnimatedValue<ViewStyle> | null {
+  switch (type) {
+    case 'replace':
+      return { opacity: Animated.subtract(1, animValue) };
+    case 'push':
+      return {
+        transform: [{ translateX: animValue.interpolate({ inputRange: [0, 1], outputRange: [0, -width * 0.3] }) }],
+      };
+    case 'pop':
+      return {
+        transform: [{ translateX: animValue.interpolate({ inputRange: [0, 1], outputRange: [0, width] }) }],
+      };
+    case 'none':
+    default:
+      return null;
+  }
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  screen: {
+    ...StyleSheet.absoluteFillObject,
+  },
+});

package/src/Components/internal/navigation/NavigationContext.ts

@@ -0,0 +1,21 @@
+import { createContext } from 'react';
+import type { NavigationState, CheckoutRoute, RouteParamMap, RouteEntry } from './types';
+
+export interface NavigationContextValue {
+  state: NavigationState;
+  push: <R extends CheckoutRoute>(
+    route: R,
+    ...args: undefined extends RouteParamMap[R] ? [RouteParamMap[R]?] : [RouteParamMap[R]]
+  ) => void;
+  pop: () => void;
+  replace: <R extends CheckoutRoute>(
+    route: R,
+    ...args: undefined extends RouteParamMap[R] ? [RouteParamMap[R]?] : [RouteParamMap[R]]
+  ) => void;
+  popToRoot: () => void;
+  setAnimating: (isAnimating: boolean) => void;
+}
+
+export const NavigationContext = createContext<NavigationContextValue | null>(null);
+
+export const RouteEntryContext = createContext<RouteEntry | null>(null);

package/src/Components/internal/navigation/NavigationHeader.tsx

@@ -0,0 +1,182 @@
+import React, { useMemo } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
+import type { TextStyle } from 'react-native';
+import { useNavigation } from './useNavigation';
+import { usePrimerTheme } from '../theme';
+import type { PrimerTokens } from '../theme';
+
+export interface NavigationHeaderAction {
+  label: string;
+  icon?: React.ReactNode;
+  onPress: () => void;
+}
+
+export interface NavigationHeaderProps {
+  title?: string;
+  showBackButton?: boolean;
+  backLabel?: string;
+  onBackPress?: () => void;
+  rightAction?: NavigationHeaderAction;
+  rightComponent?: React.ReactNode;
+}
+
+const ICON_SIZE = 20;
+const CHEVRON_STROKE = 2;
+
+function ChevronLeftIcon({ size, color }: { size: number; color: string }) {
+  const armSize = Math.round(size * 0.4);
+  return (
+    // eslint-disable-next-line react-native/no-inline-styles -- dynamic size/color props require inline styles
+    <View style={{ width: size, height: size, alignItems: 'center', justifyContent: 'center' }}>
+      <View
+        style={{
+          width: armSize,
+          height: armSize,
+          borderLeftWidth: CHEVRON_STROKE,
+          borderBottomWidth: CHEVRON_STROKE,
+          borderColor: color,
+          transform: [{ rotate: '45deg' }],
+          marginLeft: armSize * 0.25,
+        }}
+      />
+    </View>
+  );
+}
+
+function ActionButton({
+  action,
+  styles,
+  hitSlop,
+}: {
+  action: NavigationHeaderAction;
+  styles: ReturnType<typeof createStyles>;
+  hitSlop: { top: number; bottom: number; left: number; right: number };
+}) {
+  return (
+    <TouchableOpacity onPress={action.onPress} style={styles.actionButton} hitSlop={hitSlop}>
+      {action.icon != null && (
+        <>
+          {action.icon}
+          <View style={styles.actionIconGap} />
+        </>
+      )}
+      <Text style={styles.actionLabel}>{action.label}</Text>
+    </TouchableOpacity>
+  );
+}
+
+export function NavigationHeader({
+  title,
+  showBackButton = false,
+  backLabel,
+  onBackPress,
+  rightAction,
+  rightComponent,
+}: NavigationHeaderProps) {
+  const { pop } = useNavigation();
+  const tokens = usePrimerTheme();
+  const styles = useMemo(() => createStyles(tokens), [tokens]);
+
+  const handleBackPress = onBackPress ?? pop;
+  const hitSlop = useMemo(
+    () => ({
+      top: tokens.spacing.medium,
+      bottom: tokens.spacing.medium,
+      left: tokens.spacing.small,
+      right: tokens.spacing.small,
+    }),
+    [tokens.spacing.medium, tokens.spacing.small]
+  );
+
+  const rightElement = rightAction ? (
+    <ActionButton action={rightAction} styles={styles} hitSlop={hitSlop} />
+  ) : (
+    (rightComponent ?? null)
+  );
+
+  if (showBackButton) {
+    return (
+      <View style={styles.container}>
+        <View style={styles.headerBar}>
+          <TouchableOpacity onPress={handleBackPress} style={styles.actionButton} hitSlop={hitSlop}>
+            <ChevronLeftIcon size={ICON_SIZE} color={tokens.colors.iconPrimary} />
+            {backLabel != null && (
+              <>
+                <View style={styles.actionIconGap} />
+                <Text style={styles.actionLabel}>{backLabel}</Text>
+              </>
+            )}
+          </TouchableOpacity>
+          <View style={styles.spacer} />
+          {rightElement}
+        </View>
+        {title != null && <Text style={[styles.title, styles.titleTopMargin]}>{title}</Text>}
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.singleRow}>
+        {title != null && <Text style={[styles.title, styles.titleFlex]}>{title}</Text>}
+        {rightElement}
+      </View>
+    </View>
+  );
+}
+
+function createStyles(tokens: PrimerTokens) {
+  const { colors, spacing, typography, radii } = tokens;
+
+  /* eslint-disable react-native/no-unused-styles */
+  return StyleSheet.create({
+    actionButton: {
+      alignItems: 'center',
+      borderRadius: radii.small,
+      flexDirection: 'row',
+      paddingHorizontal: spacing.xxsmall,
+    },
+    actionIconGap: {
+      width: spacing.xsmall,
+    },
+    actionLabel: {
+      color: colors.textPrimary,
+      fontFamily: typography.titleLarge.fontFamily,
+      fontSize: typography.titleLarge.fontSize,
+      fontWeight: typography.titleLarge.fontWeight as TextStyle['fontWeight'],
+      letterSpacing: typography.titleLarge.letterSpacing,
+      lineHeight: typography.titleLarge.lineHeight,
+    },
+    container: {
+      paddingHorizontal: spacing.large,
+    },
+    headerBar: {
+      alignItems: 'center',
+      flexDirection: 'row',
+      height: spacing.xxlarge,
+    },
+    singleRow: {
+      alignItems: 'flex-start',
+      flexDirection: 'row',
+      paddingVertical: spacing.xxsmall,
+    },
+    spacer: {
+      flex: 1,
+    },
+    title: {
+      color: colors.textPrimary,
+      fontFamily: typography.titleXLarge.fontFamily,
+      fontSize: typography.titleXLarge.fontSize,
+      fontWeight: typography.titleXLarge.fontWeight as TextStyle['fontWeight'],
+      letterSpacing: typography.titleXLarge.letterSpacing,
+      lineHeight: typography.titleXLarge.lineHeight,
+    },
+    titleFlex: {
+      flex: 1,
+    },
+    titleTopMargin: {
+      marginTop: spacing.large,
+    },
+  });
+  /* eslint-enable react-native/no-unused-styles */
+}

package/src/Components/internal/navigation/NavigationProvider.tsx

@@ -0,0 +1,94 @@
+import React, { useCallback, useEffect, useReducer, useRef } from 'react';
+import { BackHandler, Platform } from 'react-native';
+import { NavigationContext } from './NavigationContext';
+import { navigationReducer } from './navigationReducer';
+import type { CheckoutRoute, NavigationState, RouteParamMap } from './types';
+
+interface NavigationProviderProps<R extends CheckoutRoute> {
+  initialRoute: R;
+  initialParams?: RouteParamMap[R];
+  children: React.ReactNode;
+}
+
+let keyCounter = 0;
+function generateKey(): string {
+  keyCounter += 1;
+  return `route-${keyCounter}`;
+}
+
+export function NavigationProvider<R extends CheckoutRoute>({
+  initialRoute,
+  initialParams,
+  children,
+}: NavigationProviderProps<R>) {
+  const [state, dispatch] = useReducer(
+    navigationReducer,
+    undefined,
+    (): NavigationState => ({
+      stack: [{ route: initialRoute, params: initialParams as RouteParamMap[CheckoutRoute], key: generateKey() }],
+      isAnimating: false,
+    })
+  );
+  const stateRef = useRef(state);
+  stateRef.current = state;
+
+  const push = useCallback(
+    <Route extends CheckoutRoute>(
+      route: Route,
+      ...args: undefined extends RouteParamMap[Route] ? [RouteParamMap[Route]?] : [RouteParamMap[Route]]
+    ) => {
+      if (stateRef.current.isAnimating) return;
+      const params = (args[0] ?? undefined) as RouteParamMap[CheckoutRoute];
+      dispatch({ type: 'push', route, params, key: generateKey() });
+    },
+    []
+  );
+
+  const pop = useCallback(() => {
+    if (stateRef.current.isAnimating) return;
+    dispatch({ type: 'pop' });
+  }, []);
+
+  const replace = useCallback(
+    <Route extends CheckoutRoute>(
+      route: Route,
+      ...args: undefined extends RouteParamMap[Route] ? [RouteParamMap[Route]?] : [RouteParamMap[Route]]
+    ) => {
+      if (stateRef.current.isAnimating) return;
+      const params = (args[0] ?? undefined) as RouteParamMap[CheckoutRoute];
+      dispatch({ type: 'replace', route, params, key: generateKey() });
+    },
+    []
+  );
+
+  const popToRoot = useCallback(() => {
+    if (stateRef.current.isAnimating) return;
+    dispatch({ type: 'popToRoot' });
+  }, []);
+
+  const setAnimating = useCallback((isAnimating: boolean) => {
+    dispatch({ type: 'setAnimating', isAnimating });
+  }, []);
+
+  // Android hardware back button
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+
+    const handler = BackHandler.addEventListener('hardwareBackPress', () => {
+      if (stateRef.current.stack.length > 1) {
+        pop();
+        return true;
+      }
+      return false;
+    });
+
+    return () => handler.remove();
+  }, [pop]);
+
+  const contextValue = React.useMemo(
+    () => ({ state, push, pop, replace, popToRoot, setAnimating }),
+    [state, push, pop, replace, popToRoot, setAnimating]
+  );
+
+  return <NavigationContext.Provider value={contextValue}>{children}</NavigationContext.Provider>;
+}

package/src/Components/internal/navigation/index.ts

@@ -0,0 +1,8 @@
+export { CheckoutRoute } from './types';
+export type { RouteParamMap, RouteEntry, NavigationState } from './types';
+export { NavigationProvider } from './NavigationProvider';
+export { NavigationContainer } from './NavigationContainer';
+export { useNavigation } from './useNavigation';
+export { useRoute } from './useRoute';
+export { NavigationHeader } from './NavigationHeader';
+export type { NavigationHeaderProps, NavigationHeaderAction } from './NavigationHeader';

package/src/Components/internal/navigation/navigationReducer.ts

@@ -0,0 +1,47 @@
+import type { NavigationState, NavigationAction } from './types';
+
+export function navigationReducer(state: NavigationState, action: NavigationAction): NavigationState {
+  switch (action.type) {
+    case 'push':
+      return {
+        ...state,
+        stack: [...state.stack, { route: action.route, params: action.params, key: action.key }],
+      };
+
+    case 'pop':
+      if (state.stack.length <= 1) {
+        return state;
+      }
+      return {
+        ...state,
+        stack: state.stack.slice(0, -1),
+      };
+
+    case 'replace': {
+      const newStack = [...state.stack];
+      newStack[newStack.length - 1] = { route: action.route, params: action.params, key: action.key };
+      return {
+        ...state,
+        stack: newStack,
+      };
+    }
+
+    case 'popToRoot':
+      if (state.stack.length <= 1) {
+        return state;
+      }
+      return {
+        ...state,
+        stack: [state.stack[0]!],
+      };
+
+    case 'setAnimating':
+      return {
+        ...state,
+        isAnimating: action.isAnimating,
+      };
+
+    default:
+      return state;
+  }
+}

package/src/Components/internal/navigation/types.ts

@@ -0,0 +1,48 @@
+import type { PrimerCheckoutData } from '../../../models/PrimerCheckoutData';
+import type { PrimerError } from '../../../models/PrimerError';
+
+export enum CheckoutRoute {
+  splash = 'splash',
+  loading = 'loading',
+  methodSelection = 'methodSelection',
+  cardForm = 'cardForm',
+  processing = 'processing',
+  success = 'success',
+  error = 'error',
+  countrySelector = 'countrySelector',
+  vaultedMethods = 'vaultedMethods',
+  deleteConfirmation = 'deleteConfirmation',
+  cvvRecapture = 'cvvRecapture',
+}
+
+export type RouteParamMap = {
+  [CheckoutRoute.splash]: { title?: string; subtitle?: string } | undefined;
+  [CheckoutRoute.loading]: { title?: string; subtitle?: string } | undefined;
+  [CheckoutRoute.methodSelection]: undefined;
+  [CheckoutRoute.cardForm]: { paymentMethodType: string };
+  [CheckoutRoute.processing]: undefined;
+  [CheckoutRoute.success]: { checkoutData?: PrimerCheckoutData; title?: string; subtitle?: string } | undefined;
+  [CheckoutRoute.error]: { error?: PrimerError; title?: string; subtitle?: string } | undefined;
+  [CheckoutRoute.countrySelector]: { selectedCountryCode?: string };
+  [CheckoutRoute.vaultedMethods]: undefined;
+  [CheckoutRoute.deleteConfirmation]: { paymentMethodId: string };
+  [CheckoutRoute.cvvRecapture]: { paymentMethodId: string; last4: string };
+};
+
+export interface RouteEntry<R extends CheckoutRoute = CheckoutRoute> {
+  route: R;
+  params: RouteParamMap[R];
+  key: string;
+}
+
+export interface NavigationState {
+  stack: RouteEntry[];
+  isAnimating: boolean;
+}
+
+export type NavigationAction =
+  | { type: 'push'; route: CheckoutRoute; params: RouteParamMap[CheckoutRoute]; key: string }
+  | { type: 'pop' }
+  | { type: 'replace'; route: CheckoutRoute; params: RouteParamMap[CheckoutRoute]; key: string }
+  | { type: 'popToRoot' }
+  | { type: 'setAnimating'; isAnimating: boolean };

package/src/Components/internal/navigation/useNavigation.ts

@@ -0,0 +1,18 @@
+import { useContext } from 'react';
+import { NavigationContext } from './NavigationContext';
+
+export function useNavigation() {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    throw new Error('useNavigation must be used within a NavigationProvider');
+  }
+
+  return {
+    push: context.push,
+    pop: context.pop,
+    replace: context.replace,
+    popToRoot: context.popToRoot,
+    canGoBack: context.state.stack.length > 1,
+    isAnimating: context.state.isAnimating,
+  };
+}

package/src/Components/internal/navigation/useRoute.ts

@@ -0,0 +1,18 @@
+import { useContext } from 'react';
+import { RouteEntryContext, NavigationContext } from './NavigationContext';
+import type { CheckoutRoute, RouteParamMap } from './types';
+
+export function useRoute<R extends CheckoutRoute>() {
+  const entry = useContext(RouteEntryContext);
+  const navContext = useContext(NavigationContext);
+
+  if (!entry && !navContext) {
+    throw new Error('useRoute must be used within a NavigationProvider');
+  }
+
+  const current = entry ?? navContext!.state.stack[navContext!.state.stack.length - 1]!;
+  return {
+    route: current.route as R,
+    params: current.params as RouteParamMap[R],
+  };
+}

package/src/Components/internal/routeMethodSelection.ts

@@ -0,0 +1,35 @@
+import type { UsePrimerPaymentMethodReturn } from '../types/PrimerPaymentMethodTypes';
+import type { PrimerPaymentMethodManagerCategoryName } from '../../models/PrimerHeadlessUniversalCheckoutPaymentMethod';
+
+/**
+ * How a payment method is driven, decided by **manager category** (mirrors RN Headless), not by
+ * payment-method type. `usePrimerPaymentMethod` and the prebuilt method list share this map.
+ *
+ * - `nativeUi` — a native-sheet / browser-redirect method (Google Pay today), started via
+ *   `startNativeUI(type)`.
+ * - `card` — the card form (`PAYMENT_CARD` only).
+ * - `unsupported` — not yet wired into Components.
+ *
+ * Availability (e.g. Google Pay's Android-only rule) is deliberately NOT part of routing — it lives
+ * with the consumer. Later PRs extend the kinds (bank selection, Klarna, raw-data forms, QR).
+ */
+// Single source of truth — derived from the hook's union so the two can't drift as variants land.
+export type PaymentMethodKind = UsePrimerPaymentMethodReturn['kind'];
+
+const PAYMENT_CARD_TYPE = 'PAYMENT_CARD';
+
+export function routeMethodSelection(
+  type: string,
+  categories: readonly PrimerPaymentMethodManagerCategoryName[]
+): PaymentMethodKind {
+  if (type === PAYMENT_CARD_TYPE) {
+    return 'card';
+  }
+  if (categories.includes('NATIVE_UI')) {
+    return 'nativeUi';
+  }
+  // Non-card `RAW_DATA` (Bancontact/MBWay/BLIK) is intentionally `unsupported` here — its input
+  // form lands in #394 (ORC-6514), which turns this into `rawDataForm`. Routing it to `card` now
+  // would wrongly open the card form for a non-card method.
+  return 'unsupported';
+}