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

package/src/Components/internal/CardNetworkBadge.tsx

@@ -0,0 +1,124 @@
+import { useEffect, useState } from 'react';
+import { Image, StyleSheet, Text, View } from 'react-native';
+import { usePrimerTheme } from './theme';
+import { getNetworkAbbreviation } from './cardNetwork';
+import { PLACEHOLDER_ICON_HEIGHT, PLACEHOLDER_ICON_WIDTH } from '../inputs/dimensions';
+import PrimerHeadlessUniversalCheckoutAssetsManager from '../../HeadlessUniversalCheckout/Managers/AssetsManager';
+
+const LOG = '[CardNetworkBadge]';
+const placeholderSource = require('../../assets/images/ic-card-placeholder.png');
+
+const assetsManager = new PrimerHeadlessUniversalCheckoutAssetsManager();
+const iconCache = new Map<string, Promise<string>>();
+
+function getCardNetworkIconURL(identifier: string): Promise<string> {
+  const key = identifier.toUpperCase();
+  const existing = iconCache.get(key);
+  if (existing) return existing;
+  const promise = assetsManager.getCardNetworkImageURL(key).catch((err) => {
+    iconCache.delete(key);
+    throw err;
+  });
+  iconCache.set(key, promise);
+  return promise;
+}
+
+function useNetworkIconUri(identifier: string | null): string | null {
+  const [uri, setUri] = useState<string | null>(null);
+  useEffect(() => {
+    setUri(null);
+    if (!identifier || identifier.toUpperCase() === 'OTHER') return;
+    let cancelled = false;
+    getCardNetworkIconURL(identifier)
+      .then((u) => {
+        if (!cancelled) setUri(u);
+      })
+      .catch((err) => {
+        console.warn(`${LOG} icon fetch failed ${identifier}: ${String(err)}`);
+        if (!cancelled) setUri(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [identifier]);
+  return uri;
+}
+
+export interface CardNetworkBadgeProps {
+  identifier: string;
+  testID?: string;
+  marginLeft?: number;
+}
+
+// Renders the icon for a given card network identifier. Falls back to an
+// abbreviation chip (e.g. "CB" for Cartes Bancaires) when no asset exists,
+// then to a generic placeholder. Shared by PrimerCardNumberInput trailing content
+// and the multi-network selector.
+export function CardNetworkBadge({ identifier, testID, marginLeft }: CardNetworkBadgeProps) {
+  const tokens = usePrimerTheme();
+  const uri = useNetworkIconUri(identifier);
+  const baseStyle = marginLeft != null ? { marginLeft } : null;
+
+  if (uri) {
+    return (
+      <Image
+        source={{ uri }}
+        style={[
+          styles.chipImage,
+          baseStyle,
+          { backgroundColor: tokens.colors.surface, borderRadius: tokens.radii.xsmall },
+        ]}
+        resizeMode="contain"
+        testID={testID}
+      />
+    );
+  }
+  const abbreviation = getNetworkAbbreviation(identifier);
+  if (abbreviation) {
+    return (
+      <View
+        style={[
+          styles.chip,
+          baseStyle,
+          {
+            backgroundColor: tokens.colors.surface,
+            borderColor: tokens.colors.border,
+            borderRadius: tokens.radii.xsmall,
+            borderWidth: tokens.borders.input,
+          },
+        ]}
+        testID={testID}
+      >
+        <Text
+          style={{
+            color: tokens.colors.textPrimary,
+            fontFamily: tokens.typography.fontFamily,
+            fontSize: tokens.typography.bodySmall.fontSize,
+          }}
+        >
+          {abbreviation}
+        </Text>
+      </View>
+    );
+  }
+  return (
+    <Image source={placeholderSource} style={[styles.placeholder, baseStyle]} resizeMode="contain" testID={testID} />
+  );
+}
+
+const styles = StyleSheet.create({
+  chip: {
+    alignItems: 'center',
+    height: PLACEHOLDER_ICON_HEIGHT,
+    justifyContent: 'center',
+    width: PLACEHOLDER_ICON_WIDTH,
+  },
+  chipImage: {
+    height: PLACEHOLDER_ICON_HEIGHT,
+    width: PLACEHOLDER_ICON_WIDTH,
+  },
+  placeholder: {
+    height: PLACEHOLDER_ICON_HEIGHT,
+    width: PLACEHOLDER_ICON_WIDTH,
+  },
+});

package/src/Components/internal/Popover.tsx

@@ -0,0 +1,95 @@
+import { Modal, Pressable, StyleSheet, useWindowDimensions, View } from 'react-native';
+import { usePrimerTheme } from './theme';
+
+export interface PopoverAnchor {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PopoverProps {
+  visible: boolean;
+  onDismiss: () => void;
+  children: React.ReactNode;
+  anchor?: PopoverAnchor | null;
+  testID?: string;
+}
+
+const POPOVER_WIDTH = 250;
+const ANCHOR_GAP = 4;
+const SCREEN_EDGE_PADDING = 16;
+
+// Anchored popover: full-screen Modal with a transparent dismiss backdrop and
+// a positioned card. When `anchor` is provided the card is placed immediately
+// below the anchor and right-aligned with it; otherwise it falls back to a
+// screen-centered card.
+export function Popover({ visible, onDismiss, children, anchor, testID }: PopoverProps) {
+  const tokens = usePrimerTheme();
+  const screen = useWindowDimensions();
+
+  const positionStyle = anchor
+    ? {
+        position: 'absolute' as const,
+        top: anchor.y + anchor.height + ANCHOR_GAP,
+        left: Math.max(
+          SCREEN_EDGE_PADDING,
+          Math.min(anchor.x + anchor.width - POPOVER_WIDTH, screen.width - POPOVER_WIDTH - SCREEN_EDGE_PADDING)
+        ),
+      }
+    : null;
+
+  const wrapperStyle = [styles.shadowWrapper, { borderRadius: tokens.radii.medium }, positionStyle];
+  const cardStyle = [
+    styles.card,
+    {
+      backgroundColor: tokens.colors.background,
+      borderColor: tokens.colors.border,
+      borderRadius: tokens.radii.medium,
+    },
+  ];
+
+  return (
+    <Modal
+      transparent
+      statusBarTranslucent
+      visible={visible}
+      onRequestClose={onDismiss}
+      animationType="fade"
+      testID={testID}
+    >
+      <View style={styles.root} pointerEvents="box-none">
+        <Pressable
+          style={StyleSheet.absoluteFill}
+          onPress={onDismiss}
+          testID={testID ? `${testID}-backdrop` : undefined}
+        />
+        <View style={wrapperStyle}>
+          <Pressable onPress={() => undefined} style={cardStyle}>
+            <View>{children}</View>
+          </Pressable>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    borderWidth: StyleSheet.hairlineWidth,
+    overflow: 'hidden',
+    width: '100%',
+  },
+  root: {
+    flex: 1,
+  },
+  // eslint-disable-next-line react-native/no-color-literals
+  shadowWrapper: {
+    elevation: 8,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 8 },
+    shadowOpacity: 0.18,
+    shadowRadius: 24,
+    width: POPOVER_WIDTH,
+  },
+});

package/src/Components/internal/PrimerCheckoutContext.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+import type { PrimerCheckoutContextValue } from '../types/PrimerCheckoutProviderTypes';
+
+export const PrimerCheckoutContext = createContext<PrimerCheckoutContextValue | null>(null);

package/src/Components/internal/applePay.ts

@@ -0,0 +1,12 @@
+import { Platform } from 'react-native';
+
+/** The Apple Pay payment-method type. */
+export const APPLE_PAY = 'APPLE_PAY';
+
+/**
+ * Whether Apple Pay can be presented. The iOS SDK already filters APPLE_PAY out of the
+ * available-methods list when the device can't present it, so list membership on iOS is
+ * sufficient; gate on Platform.OS so merchants need no platform branch in their render path.
+ */
+export const isApplePaySupported = (methods: ReadonlyArray<{ paymentMethodType: string }>): boolean =>
+  Platform.OS === 'ios' && methods.some((m) => m.paymentMethodType === APPLE_PAY);

package/src/Components/internal/billingAddressOptions.ts

@@ -0,0 +1,47 @@
+import type { PrimerClientSession } from '../../models/PrimerClientSession';
+import type { BillingAddressField } from '../types/BillingAddressFormTypes';
+
+const BILLING_ADDRESS_FIELDS: ReadonlyArray<BillingAddressField> = [
+  'firstName',
+  'lastName',
+  'addressLine1',
+  'addressLine2',
+  'city',
+  'state',
+  'postalCode',
+  'countryCode',
+];
+
+export type BillingAddressVisibility = Record<BillingAddressField, boolean>;
+
+export interface BillingAddressVisibilityResult {
+  fields: BillingAddressVisibility;
+  sectionVisible: boolean;
+}
+
+const ALL_HIDDEN: BillingAddressVisibility = {
+  firstName: false,
+  lastName: false,
+  addressLine1: false,
+  addressLine2: false,
+  city: false,
+  state: false,
+  postalCode: false,
+  countryCode: false,
+};
+
+export function getBillingAddressVisibility(
+  session: PrimerClientSession | null | undefined
+): BillingAddressVisibilityResult {
+  const module = session?.checkoutModules?.find((m) => m.type === 'BILLING_ADDRESS');
+  const options = module?.options ?? {};
+  const fields = BILLING_ADDRESS_FIELDS.reduce<BillingAddressVisibility>(
+    (acc, f) => {
+      acc[f] = options[f] === true;
+      return acc;
+    },
+    { ...ALL_HIDDEN }
+  );
+  const sectionVisible = Object.values(fields).some(Boolean);
+  return { fields, sectionVisible };
+}

package/src/Components/internal/cardFormat.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure formatting + length helpers for the card-number input. Reads the network
+ * descriptor (defined in `cardNetwork.ts`) and answers questions about display
+ * length and gap placement; no I/O, no React.
+ */
+import type { CardNetworkDescriptor } from './cardNetwork';
+
+/** Max PAN digit count across all accepted lengths for the descriptor's network. */
+export function maxPanDigits(descriptor: CardNetworkDescriptor): number {
+  // Guard against native ever handing back an empty array — `Math.max()` on `[]`
+  // is `-Infinity`, which silently breaks `maxLength` on the TextInput.
+  if (descriptor.panLengths.length === 0) return 19;
+  return Math.max(...descriptor.panLengths);
+}
+
+/**
+ * Max formatted length (digits + gaps that fall within that digit count). Used
+ * as the TextInput `maxLength` so the input won't accept more characters than
+ * the longest valid formatted PAN for this network.
+ */
+export function maxFormattedCardNumberLength(descriptor: CardNetworkDescriptor): number {
+  const digits = maxPanDigits(descriptor);
+  const gapsWithin = descriptor.gapPattern.filter((g) => g > 0 && g < digits).length;
+  return digits + gapsWithin;
+}
+
+/**
+ * Insert spaces into a raw digit string according to a gap pattern.
+ * Example: `formatDigitsWithGaps("4242424242424242", [4,8,12])` → `"4242 4242 4242 4242"`.
+ */
+export function formatDigitsWithGaps(digits: string, gapPattern: readonly number[]): string {
+  if (digits.length === 0) return '';
+  let out = '';
+  for (let i = 0; i < digits.length; i++) {
+    if (i > 0 && gapPattern.includes(i)) out += ' ';
+    out += digits[i];
+  }
+  return out;
+}

package/src/Components/internal/cardNetwork.ts

@@ -0,0 +1,128 @@
+/**
+ * Card-network descriptor: PAN lengths, gap pattern, CVV length, CVV label.
+ *
+ * Traits are fetched asynchronously from the native SDK via `fetchCardNetworkDescriptor`
+ * and cached per network id for the session. `DEFAULT_DESCRIPTOR` is the safe fallback
+ * for unknown/loading networks and the networks native reports without validation data.
+ *
+ * Source of truth:
+ *   - iOS: `PrimerHeadlessUniversalCheckout.AssetsManager.getCardNetworkTraits(cardNetworkString:)`
+ *   - Android: `CardNetwork.lookupByCardNetwork(cardNetwork)` via the RN asset bridge
+ */
+import type { ImageSourcePropType } from 'react-native';
+import PrimerHeadlessUniversalCheckoutAssetsManager from '../../HeadlessUniversalCheckout/Managers/AssetsManager';
+
+/** Upper-cased network identifier; matches `binData.preferred.network` from native. */
+export type CardNetworkId =
+  | 'VISA'
+  | 'MASTERCARD'
+  | 'AMEX'
+  | 'DINERS_CLUB'
+  | 'DISCOVER'
+  | 'JCB'
+  | 'UNIONPAY'
+  | 'MAESTRO'
+  | 'ELO'
+  | 'MIR'
+  | 'HIPER'
+  | 'HIPERCARD'
+  | 'DANKORT'
+  | 'BANCONTACT'
+  | 'CARTES_BANCAIRES'
+  | 'EFTPOS'
+  | 'OTHER';
+
+/** CVV label variants emitted by native (iOS: per-network; Android: per-network after ACC-7168). */
+export type CvvLabel = 'CVV' | 'CVC' | 'CID' | 'CVN' | 'CVE' | 'CVP2';
+
+export interface CardNetworkDescriptor {
+  /** Upper-cased network identifier. */
+  id: CardNetworkId;
+  /** Human-readable name for UI (e.g. "American Express"). */
+  displayName: string;
+  /** Allowed PAN digit counts (unformatted, no spaces). */
+  panLengths: readonly number[];
+  /**
+   * Zero-indexed digit positions *before which* a space is inserted when formatting.
+   * Example: `[4, 8, 12]` → `4242 4242 4242 4242`; `[4, 10]` → `3782 822463 10005`.
+   */
+  gapPattern: readonly number[];
+  /** CVV digit count. */
+  cvvLength: 3 | 4;
+  /** Label shown next to the CVV field (iOS-style: matches the physical card). */
+  cvvLabel: CvvLabel;
+}
+
+/** Used when the network is `null`, `OTHER`, or the native bridge hasn't resolved traits yet. */
+export const DEFAULT_DESCRIPTOR: CardNetworkDescriptor = {
+  id: 'OTHER',
+  displayName: 'Card',
+  panLengths: [16, 17, 18, 19],
+  gapPattern: [4, 8, 12],
+  cvvLength: 3,
+  cvvLabel: 'CVV',
+};
+
+const assetsManager = new PrimerHeadlessUniversalCheckoutAssetsManager();
+
+// Promise cache keyed by upper-cased network id. Dedupes in-flight calls and persists
+// resolved descriptors across hook instances so switching back to a previously seen
+// network is instantaneous — mirrors the icon-cache pattern in usePrimerCardNetwork.
+const descriptorCache = new Map<string, Promise<CardNetworkDescriptor>>();
+
+/**
+ * Fetch the descriptor for a network from the native SDK. Falls back to DEFAULT_DESCRIPTOR
+ * when native reports null (iOS: bancontact/cartesBancaires/eftpos/unknown) or OTHER
+ * (Android's fallback for unrecognised names). Bridge errors also resolve to defaults
+ * so the UI never gets stuck on a rejected promise.
+ */
+export function fetchCardNetworkDescriptor(network: string): Promise<CardNetworkDescriptor> {
+  const key = network.toUpperCase();
+  const existing = descriptorCache.get(key);
+  if (existing) return existing;
+  const promise = assetsManager
+    .getCardNetworkTraits(key)
+    .then((traits): CardNetworkDescriptor => {
+      if (!traits || traits.cardNetwork === 'OTHER') return DEFAULT_DESCRIPTOR;
+      return {
+        id: traits.cardNetwork as CardNetworkId,
+        displayName: traits.displayName,
+        panLengths: traits.panLengths,
+        gapPattern: traits.gapPattern,
+        cvvLength: traits.cvvLength as 3 | 4,
+        cvvLabel: traits.cvvLabel as CvvLabel,
+      };
+    })
+    .catch((err) => {
+      descriptorCache.delete(key);
+      console.warn(`[cardNetwork] fetchCardNetworkDescriptor failed for ${key}: ${String(err)}`);
+      return DEFAULT_DESCRIPTOR;
+    });
+  descriptorCache.set(key, promise);
+  return promise;
+}
+
+/** Narrow `ImageSourcePropType | null` when a hook consumer wants to render the network icon. */
+export type CardNetworkIconSource = ImageSourcePropType | null;
+
+/**
+ * Two-letter abbreviation for the bordered fallback chip when a network has no icon
+ * asset (Bancontact, Cartes Bancaires, EFTPOS) or the asset fetch failed.
+ *
+ * Accepts the raw network string from native (`usePrimerCardNetwork().network`) since natives
+ * can report ids outside the known union. Underscored ids → first letter of each word;
+ * single-word ids → first two letters. `OTHER` and empty input return empty string —
+ * callers should render nothing in that case.
+ */
+export function getNetworkAbbreviation(network: string): string {
+  const id = network.toUpperCase();
+  if (!id || id === 'OTHER') return '';
+  if (id.includes('_')) {
+    return id
+      .split('_')
+      .map((word) => word.charAt(0))
+      .join('')
+      .slice(0, 2);
+  }
+  return id.slice(0, 2);
+}

package/src/Components/internal/cardNetworkIcons.ts

@@ -0,0 +1,27 @@
+import { NativeModules } from 'react-native';
+
+const { RNTPrimerHeadlessUniversalCheckoutAssetsManager } = NativeModules;
+
+const iconUrlCache = new Map<string, Promise<string>>();
+
+/**
+ * Module-level promise cache for card-network icon URIs.
+ *
+ * Calls the native module directly rather than `AssetsManager.getCardNetworkImageURL`,
+ * which logs every rejection via `console.error` (LogBox red box in dev). Unknown
+ * networks legitimately have no asset — the chip row falls back to the abbreviation —
+ * so the rejection is expected, not an error worth surfacing.
+ */
+export function getCardNetworkIconURL(network: string): Promise<string> {
+  const key = network.toUpperCase();
+  const existing = iconUrlCache.get(key);
+  if (existing) return existing;
+  const promise = RNTPrimerHeadlessUniversalCheckoutAssetsManager.getCardNetworkImage(key)
+    .then((data: { cardNetworkImageURL: string }) => data.cardNetworkImageURL)
+    .catch((err: Error) => {
+      iconUrlCache.delete(key);
+      throw err;
+    });
+  iconUrlCache.set(key, promise);
+  return promise;
+}

package/src/Components/internal/checkout-flow/CheckoutFlow.tsx

@@ -0,0 +1,124 @@
+import React, { useContext, useEffect, useMemo, useRef } from 'react';
+import { NavigationProvider } from '../navigation/NavigationProvider';
+import { NavigationContainer } from '../navigation/NavigationContainer';
+import { useNavigation } from '../navigation/useNavigation';
+import { CheckoutRoute } from '../navigation/types';
+import type { CheckoutRoute as CheckoutRouteType } from '../navigation/types';
+import { usePrimerCheckout } from '../../hooks/usePrimerCheckout';
+import { LoadingScreen } from '../screens/LoadingScreen';
+import { MethodSelectionScreen } from '../screens/MethodSelectionScreen';
+import { CardFormScreen } from '../screens/CardFormScreen';
+import { CountrySelectorScreen } from '../screens/CountrySelectorScreen';
+import { ErrorScreen } from '../screens/ErrorScreen';
+import { SuccessScreen } from '../screens/SuccessScreen';
+import { VaultedMethodsScreen } from '../screens/VaultedMethodsScreen';
+import { PrimerCardFormProvider, BillingAddressFormStateProvider } from '../form-state';
+import { CheckoutFlowContext } from './CheckoutFlowContext';
+
+const SUCCESS_AUTO_DISMISS_MS = 3000;
+
+function CheckoutSuccessScreen() {
+  const flow = useContext(CheckoutFlowContext);
+  const { clearPaymentOutcome } = usePrimerCheckout();
+
+  useEffect(() => {
+    const t = setTimeout(() => {
+      clearPaymentOutcome();
+      flow?.onCancel();
+    }, SUCCESS_AUTO_DISMISS_MS);
+    return () => clearTimeout(t);
+  }, [flow, clearPaymentOutcome]);
+
+  return <SuccessScreen />;
+}
+
+const screenMap: Partial<Record<CheckoutRouteType, React.ComponentType>> = {
+  [CheckoutRoute.splash]: LoadingScreen,
+  [CheckoutRoute.methodSelection]: MethodSelectionScreen,
+  [CheckoutRoute.cardForm]: CardFormScreen,
+  [CheckoutRoute.countrySelector]: CountrySelectorScreen,
+  [CheckoutRoute.processing]: LoadingScreen,
+  [CheckoutRoute.success]: CheckoutSuccessScreen,
+  [CheckoutRoute.error]: ErrorScreen,
+  [CheckoutRoute.vaultedMethods]: VaultedMethodsScreen,
+};
+
+function ReadinessTransitioner() {
+  const { isReady, isLoadingResources, error } = usePrimerCheckout();
+  const { replace } = useNavigation();
+  const hasTransitioned = useRef(false);
+
+  useEffect(() => {
+    if (hasTransitioned.current) return;
+
+    if (error) {
+      hasTransitioned.current = true;
+      replace(CheckoutRoute.error, { error });
+      return;
+    }
+
+    if (isReady && !isLoadingResources) {
+      hasTransitioned.current = true;
+      replace(CheckoutRoute.methodSelection);
+    }
+  }, [isReady, isLoadingResources, error, replace]);
+
+  return null;
+}
+
+function PaymentOutcomeTransitioner() {
+  const { paymentOutcome, settings, clearPaymentOutcome } = usePrimerCheckout();
+  const { replace } = useNavigation();
+  const flow = useContext(CheckoutFlowContext);
+  const lastOutcomeRef = useRef<typeof paymentOutcome>(null);
+
+  useEffect(() => {
+    // Guard against re-fires when unrelated context fields change.
+    if (paymentOutcome === lastOutcomeRef.current) return;
+    lastOutcomeRef.current = paymentOutcome;
+
+    if (!paymentOutcome) return;
+
+    const uiOptions = settings?.uiOptions;
+
+    if (paymentOutcome.status === 'success') {
+      if (uiOptions?.isSuccessScreenEnabled === false) {
+        clearPaymentOutcome();
+        flow?.onCancel();
+        return;
+      }
+      replace(CheckoutRoute.success, { checkoutData: paymentOutcome.data });
+    } else {
+      if (uiOptions?.isErrorScreenEnabled === false) {
+        clearPaymentOutcome();
+        flow?.onCancel();
+        return;
+      }
+      replace(CheckoutRoute.error, { error: paymentOutcome.error });
+    }
+  }, [paymentOutcome, settings, replace, clearPaymentOutcome, flow]);
+
+  return null;
+}
+
+export interface CheckoutFlowProps {
+  onCancel?: () => void;
+}
+
+export function CheckoutFlow({ onCancel }: CheckoutFlowProps = {}) {
+  const contextValue = useMemo(() => ({ onCancel: onCancel ?? (() => {}) }), [onCancel]);
+
+  return (
+    <CheckoutFlowContext.Provider value={contextValue}>
+      <NavigationProvider initialRoute={CheckoutRoute.splash}>
+        <ReadinessTransitioner />
+        <PaymentOutcomeTransitioner />
+        <PrimerCardFormProvider>
+          <BillingAddressFormStateProvider>
+            <NavigationContainer screenMap={screenMap} />
+          </BillingAddressFormStateProvider>
+        </PrimerCardFormProvider>
+      </NavigationProvider>
+    </CheckoutFlowContext.Provider>
+  );
+}

package/src/Components/internal/checkout-flow/CheckoutFlowContext.ts

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+
+export interface CheckoutFlowContextValue {
+  /** Called when the user requests to cancel/close the checkout flow */
+  onCancel: () => void;
+}
+
+export const CheckoutFlowContext = createContext<CheckoutFlowContextValue | null>(null);
+
+export function useCheckoutFlow(): CheckoutFlowContextValue {
+  const context = useContext(CheckoutFlowContext);
+  if (!context) {
+    throw new Error('useCheckoutFlow must be used within a CheckoutFlow');
+  }
+  return context;
+}

package/src/Components/internal/checkout-flow/index.ts

@@ -0,0 +1 @@
+export { CheckoutFlow } from './CheckoutFlow';