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

package/src/Components/hooks/usePrimerCardNetworkSelection.ts

@@ -0,0 +1,85 @@
+import { useCallback, useMemo } from 'react';
+import { usePrimerCheckout } from './usePrimerCheckout';
+import type { CardNetworkDetails, UsePrimerCardNetworkSelectionReturn } from '../types/CardNetworkSelection';
+import type { CardNetworkId } from '../internal/cardNetwork';
+import type { PrimerCardNetwork as PrimerBinCardNetwork } from '../../models/PrimerBinData';
+
+const LOG = '[usePrimerCardNetworkSelection]';
+
+// Networks routed by the issuer rather than the shopper. Showing them in a
+// chooser would be misleading — we render them as a non-interactive dual-badge.
+const NON_SELECTABLE_NETWORKS = new Set<string>(['EFTPOS']);
+
+// A card is co-badged when the BIN resolves to at least this many networks.
+const MIN_COBADGE_NETWORKS = 2;
+
+function toCardNetwork(raw: PrimerBinCardNetwork): CardNetworkDetails {
+  // Native emits the closed set of CardNetworkId strings; cast is faithful to that contract.
+  const identifier = raw.network as CardNetworkId;
+  return {
+    identifier,
+    displayName: raw.displayName,
+    // `allowed` is iOS-only on PrimerBinCardNetwork. undefined → treat as allowed.
+    logoUri: null,
+    allowed: raw.allowed !== false,
+    allowsUserSelection: !NON_SELECTABLE_NETWORKS.has(identifier),
+  };
+}
+
+export function usePrimerCardNetworkSelection(): UsePrimerCardNetworkSelectionReturn {
+  const { cardFormState, selectCardNetwork: providerSelect, selectedCardNetwork } = usePrimerCheckout();
+  const binData = cardFormState.binData;
+
+  const availableNetworks = useMemo<ReadonlyArray<CardNetworkDetails>>(() => {
+    if (!binData) {
+      return [];
+    }
+    const all: PrimerBinCardNetwork[] = binData.preferred
+      ? [binData.preferred, ...binData.alternatives]
+      : [...binData.alternatives];
+    return all.map(toCardNetwork).filter((n) => n.allowed);
+  }, [binData]);
+
+  // Deliberately no fallback to `binData.preferred` — that's the SDK's BIN-detection
+  // default, not the shopper's choice.
+  const selectedIdentifier = selectedCardNetwork;
+
+  const selectedNetwork = useMemo<CardNetworkDetails | null>(() => {
+    if (!selectedIdentifier) return null;
+    return availableNetworks.find((n) => n.identifier === selectedIdentifier) ?? null;
+  }, [availableNetworks, selectedIdentifier]);
+
+  const displayedNetwork = useMemo<CardNetworkDetails | null>(
+    () => selectedNetwork ?? availableNetworks[0] ?? null,
+    [selectedNetwork, availableNetworks]
+  );
+  const displayedIdentifier = displayedNetwork?.identifier ?? null;
+
+  const isSelectorVisible =
+    availableNetworks.length >= MIN_COBADGE_NETWORKS && availableNetworks.every((n) => n.allowsUserSelection);
+  const isDualBadge =
+    availableNetworks.length >= MIN_COBADGE_NETWORKS && availableNetworks.some((n) => !n.allowsUserSelection);
+
+  const selectNetwork = useCallback(
+    async (identifier: CardNetworkId): Promise<void> => {
+      try {
+        await providerSelect(identifier);
+      } catch (err) {
+        console.warn(`${LOG} select failed id=${identifier}: ${String(err)}`);
+        throw err;
+      }
+    },
+    [providerSelect]
+  );
+
+  return {
+    availableNetworks,
+    selectedNetwork,
+    selectedIdentifier,
+    displayedNetwork,
+    displayedIdentifier,
+    isSelectorVisible,
+    isDualBadge,
+    selectNetwork,
+  };
+}

package/src/Components/hooks/usePrimerCheckout.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+import { PrimerCheckoutContext } from '../internal/PrimerCheckoutContext';
+import type { PrimerCheckoutContextValue } from '../types/PrimerCheckoutProviderTypes';
+
+export function usePrimerCheckout(): PrimerCheckoutContextValue {
+  const context = useContext(PrimerCheckoutContext);
+  if (context === null) {
+    throw new Error(
+      'usePrimerCheckout must be used within a <PrimerCheckoutProvider>. ' +
+        'Wrap your component tree with <PrimerCheckoutProvider clientToken="...">.'
+    );
+  }
+  return context;
+}

package/src/Components/hooks/usePrimerPaymentMethod.ts

@@ -0,0 +1,91 @@
+import { useCallback, useMemo } from 'react';
+import { Platform } from 'react-native';
+
+import { usePrimerCheckout } from './usePrimerCheckout';
+import { GOOGLE_PAY, isGooglePaySupported } from '../internal/googlePay';
+import { APPLE_PAY, isApplePaySupported } from '../internal/applePay';
+import { routeMethodSelection } from '../internal/routeMethodSelection';
+
+import type { PaymentMethodAvailabilityError, UsePrimerPaymentMethodReturn } from '../types/PrimerPaymentMethodTypes';
+
+/**
+ * One generic hook for any payment method — narrow the return on `kind`. Replaces the per-method
+ * hooks: render the provided button (or your own) and call `start()`; the native Headless SDK owns
+ * the flow, and outcomes arrive via `paymentOutcome`. The card method keeps its dedicated
+ * `usePrimerCardForm` for field-level layouts. Throws outside `<PrimerCheckoutProvider>`.
+ */
+export function usePrimerPaymentMethod(type: string): UsePrimerPaymentMethodReturn {
+  const {
+    availablePaymentMethods,
+    nativeUiInFlightType,
+    paymentOutcome,
+    startNativeUI,
+    cancelNativeUI,
+    clearPaymentOutcome,
+    setActiveMethod,
+  } = usePrimerCheckout();
+
+  const method = availablePaymentMethods.find((m) => m.paymentMethodType === type);
+  const isPresent = method != null;
+  const kind = routeMethodSelection(type, method?.paymentMethodManagerCategories ?? []);
+
+  const start = useCallback(() => startNativeUI(type), [startNativeUI, type]);
+  const cancel = useCallback(() => cancelNativeUI(type), [cancelNativeUI, type]);
+  const startCard = useCallback(() => setActiveMethod(type), [setActiveMethod, type]);
+
+  return useMemo<UsePrimerPaymentMethodReturn>(() => {
+    if (kind === 'nativeUi') {
+      const isAvailable = isNativeUiAvailable(type, availablePaymentMethods);
+      return {
+        kind: 'nativeUi',
+        isAvailable,
+        isLoading: nativeUiInFlightType === type,
+        paymentOutcome,
+        availabilityError: isAvailable ? null : availabilityError(type),
+        start,
+        cancel,
+        clearPaymentOutcome,
+      };
+    }
+    if (kind === 'card') {
+      return { kind: 'card', isAvailable: isPresent, start: startCard, clearPaymentOutcome };
+    }
+    return { kind: 'unsupported', isAvailable: false };
+  }, [
+    kind,
+    type,
+    isPresent,
+    availablePaymentMethods,
+    nativeUiInFlightType,
+    paymentOutcome,
+    start,
+    cancel,
+    startCard,
+    clearPaymentOutcome,
+  ]);
+}
+
+/** Native-UI availability — platform-gated for Google/Apple Pay (single-platform), list-membership otherwise. */
+function isNativeUiAvailable(type: string, methods: ReadonlyArray<{ paymentMethodType: string }>): boolean {
+  if (type === GOOGLE_PAY) {
+    return isGooglePaySupported(methods);
+  }
+  if (type === APPLE_PAY) {
+    return isApplePaySupported(methods);
+  }
+  return methods.some((m) => m.paymentMethodType === type);
+}
+
+function availabilityError(type: string): PaymentMethodAvailabilityError {
+  if (type === GOOGLE_PAY) {
+    return Platform.OS === 'android'
+      ? { code: 'NOT_READY', message: 'Google Pay is not ready on this device.' }
+      : { code: 'PLATFORM_NOT_SUPPORTED', message: 'Google Pay is only available on Android.' };
+  }
+  if (type === APPLE_PAY) {
+    return Platform.OS === 'ios'
+      ? { code: 'NOT_AVAILABLE', message: 'Apple Pay is not available on this device.' }
+      : { code: 'PLATFORM_NOT_SUPPORTED', message: 'Apple Pay is only available on iOS.' };
+  }
+  return { code: 'NOT_AVAILABLE', message: `${type} is not available. Ensure it is configured for this session.` };
+}

package/src/Components/hooks/usePrimerPaymentMethods.ts

@@ -0,0 +1,172 @@
+import { useState, useMemo, useCallback, useEffect, useRef } from 'react';
+import { useColorScheme } from 'react-native';
+import { usePrimerCheckout } from './usePrimerCheckout';
+import { titleCaseFromType } from '../internal/utils/formatting';
+import { toError } from '../internal/utils/errors';
+import type { PrimerClientSessionPaymentMethodOption } from '../../models/PrimerClientSession';
+import type {
+  PaymentMethodItem,
+  PaymentMethodSurcharge,
+  UsePrimerPaymentMethodsOptions,
+  UsePrimerPaymentMethodsReturn,
+} from '../types/PaymentMethodTypes';
+
+const PAYMENT_CARD_TYPE = 'PAYMENT_CARD';
+
+// Mirrors Android's `PaymentMethodDataResponse.surcharges()` mapping:
+// PAYMENT_CARD → CardNetworksSurcharge; everything else → PaymentMethodSurcharge.
+function buildSurchargeMap(
+  paymentMethodOptions: Record<string, PrimerClientSessionPaymentMethodOption> | undefined
+): Map<string, PaymentMethodSurcharge> {
+  const result = new Map<string, PaymentMethodSurcharge>();
+  if (!paymentMethodOptions) return result;
+
+  for (const [methodType, methodOpts] of Object.entries(paymentMethodOptions)) {
+    if (methodType === PAYMENT_CARD_TYPE) {
+      const amounts: Record<string, number> = {};
+      for (const [network, networkOpts] of Object.entries(methodOpts?.networks ?? {})) {
+        const amount = networkOpts?.surcharge?.amount;
+        if (amount != null) {
+          amounts[network] = amount;
+        }
+      }
+      if (Object.keys(amounts).length > 0) {
+        result.set(methodType, { kind: 'perNetwork', amounts });
+      }
+    } else {
+      const amount = methodOpts?.surcharge?.amount;
+      if (amount != null) {
+        result.set(methodType, { kind: 'flat', amount });
+      }
+    }
+  }
+  return result;
+}
+
+export function usePrimerPaymentMethods(options: UsePrimerPaymentMethodsOptions = {}): UsePrimerPaymentMethodsReturn {
+  const { include, exclude, onLoad } = options;
+
+  const {
+    availablePaymentMethods,
+    paymentMethodResources,
+    isLoadingResources,
+    resourcesError,
+    isReady,
+    clientSession,
+  } = usePrimerCheckout();
+
+  const [selectedType, setSelectedType] = useState<string | null>(null);
+  const colorScheme = useColorScheme();
+
+  const onLoadRef = useRef(onLoad);
+  onLoadRef.current = onLoad;
+
+  const lastFiredSignatureRef = useRef<string | null>(null);
+
+  const isLoading = !isReady || isLoadingResources;
+
+  const { items: paymentMethods, error } = useMemo(() => {
+    if (isLoading) {
+      return { items: [], error: null };
+    }
+
+    const isDark = colorScheme === 'dark';
+
+    try {
+      const resourceMap = new Map(paymentMethodResources.map((r) => [r.paymentMethodType, r]));
+
+      const surchargeMap = buildSurchargeMap(clientSession?.paymentMethodOptions);
+
+      let result: PaymentMethodItem[] = availablePaymentMethods.map((method) => {
+        const resource = resourceMap.get(method.paymentMethodType);
+
+        let logo: string | undefined;
+        let backgroundColor: string | undefined;
+
+        if (resource && 'paymentMethodLogo' in resource) {
+          // Prefer colored when available; otherwise pick by color scheme.
+          // Consumers wanting a different variant can read `resource.paymentMethodLogo` directly.
+          const asset = resource.paymentMethodLogo;
+          const themeVariant = isDark ? asset.dark : asset.light;
+          logo = asset.colored ?? themeVariant ?? asset.light ?? asset.dark;
+
+          const bg = resource.paymentMethodBackgroundColor;
+          const bgThemeVariant = isDark ? bg?.dark : bg?.light;
+          backgroundColor = bg?.colored ?? bgThemeVariant ?? bg?.light ?? bg?.dark;
+        }
+
+        return {
+          type: method.paymentMethodType,
+          name: resource?.paymentMethodName ?? titleCaseFromType(method.paymentMethodType),
+          logo,
+          backgroundColor,
+          nativeViewName: resource?.nativeViewName,
+          categories: [...method.paymentMethodManagerCategories],
+          intents: [...method.supportedPrimerSessionIntents],
+          surcharge: surchargeMap.get(method.paymentMethodType),
+          resource,
+          paymentMethod: method,
+        };
+      });
+
+      if (include && include.length > 0) {
+        result = result.filter((item) => include.includes(item.type));
+      }
+      if (exclude && exclude.length > 0) {
+        result = result.filter((item) => !exclude.includes(item.type));
+      }
+
+      return { items: result, error: null };
+    } catch (err) {
+      return { items: [], error: toError(err) };
+    }
+  }, [availablePaymentMethods, paymentMethodResources, isLoading, clientSession, include, exclude, colorScheme]);
+
+  // Fires onLoad once per distinct set of payment-method types, after resources load.
+  // Re-fires if the set of types changes (e.g. client-session update adds/removes a method).
+  useEffect(() => {
+    if (isLoading) {
+      lastFiredSignatureRef.current = null;
+      return;
+    }
+    const signature = paymentMethods
+      .map((m) => m.type)
+      .sort()
+      .join('|');
+    if (signature !== lastFiredSignatureRef.current) {
+      lastFiredSignatureRef.current = signature;
+      onLoadRef.current?.(paymentMethods);
+    }
+  }, [isLoading, paymentMethods]);
+
+  // Clear selection if the selected type is no longer present (e.g. filtered out).
+  useEffect(() => {
+    if (isLoading) return;
+    if (selectedType != null && !paymentMethods.some((m) => m.type === selectedType)) {
+      setSelectedType(null);
+    }
+  }, [isLoading, selectedType, paymentMethods]);
+
+  const selectedMethod = useMemo(
+    () => paymentMethods.find((m) => m.type === selectedType) ?? null,
+    [paymentMethods, selectedType]
+  );
+
+  const selectMethod = useCallback((method: PaymentMethodItem | null) => {
+    setSelectedType(method?.type ?? null);
+  }, []);
+
+  const clearSelection = useCallback(() => {
+    setSelectedType(null);
+  }, []);
+
+  return {
+    paymentMethods,
+    isLoading,
+    error,
+    resourcesError,
+    selectedMethod,
+    selectMethod,
+    clearSelection,
+  };
+}

package/src/Components/hooks/usePrimerVaultManager.ts

@@ -0,0 +1,114 @@
+import { useCallback, useMemo } from 'react';
+import { usePrimerCheckout } from './usePrimerCheckout';
+import type {
+  UsePrimerVaultManagerReturn,
+  VaultDisplayMode,
+  VaultedPaymentMethodItem,
+} from '../types/VaultedPaymentMethodTypes';
+import type { PrimerVaultedPaymentMethod } from '../../models/PrimerVaultedPaymentMethod';
+import type { PrimerVaultedPaymentMethodAdditionalData } from '../../models/PrimerVaultedPaymentMethodAdditionalData';
+
+const CARD_PAYMENT_METHOD_TYPE = 'PAYMENT_CARD';
+
+function titleCase(value: string): string {
+  const lower = value.toLowerCase();
+  return lower.charAt(0).toUpperCase() + lower.slice(1);
+}
+
+function pad2(value: number | undefined): string | undefined {
+  if (value == null) return undefined;
+  return value < 10 ? `0${value}` : String(value);
+}
+
+function toVaultedItem(method: PrimerVaultedPaymentMethod, iconUri: string | undefined): VaultedPaymentMethodItem {
+  const isCard = method.paymentMethodType === CARD_PAYMENT_METHOD_TYPE;
+  const instrument = method.paymentInstrumentData;
+
+  const last4Raw = instrument?.last4Digits ?? instrument?.accountNumberLast4Digits;
+  const last4 = last4Raw != null ? String(last4Raw) : undefined;
+
+  const yearRaw = instrument?.expirationYear;
+  // Year field is typed as `number` (e.g. 2026) — display the last two digits for the card row.
+  const expiryYear = yearRaw != null ? String(yearRaw).slice(-2) : undefined;
+
+  return {
+    id: method.id,
+    paymentMethodType: method.paymentMethodType,
+    paymentInstrumentType: method.paymentInstrumentType,
+    cardholderName: isCard ? instrument?.cardholderName : undefined,
+    last4,
+    expiryMonth: isCard ? pad2(instrument?.expirationMonth) : undefined,
+    expiryYear: isCard ? expiryYear : undefined,
+    brandName: isCard && instrument?.network ? titleCase(instrument.network) : undefined,
+    brandIconUri: iconUri,
+    rawMethod: method,
+  };
+}
+
+export function usePrimerVaultManager(): UsePrimerVaultManagerReturn {
+  const {
+    vaultedMethods: rawMethods,
+    vaultedIconUrisById,
+    isLoadingVaulted,
+    vaultedError,
+    payFromVault,
+    activeVaultedMethodId,
+    vaultDisplayOverride,
+    selectVaultedMethodId,
+    requestExpandedVaultDisplay,
+    deleteVaultedPaymentMethod,
+    requiresVaultedCardCvv,
+    cvvInputVisible,
+  } = usePrimerCheckout();
+
+  const vaultedMethods = useMemo<VaultedPaymentMethodItem[]>(
+    () => rawMethods.map((m) => toVaultedItem(m, vaultedIconUrisById[m.id])),
+    [rawMethods, vaultedIconUrisById]
+  );
+
+  const originalDefault = vaultedMethods[0] ?? null;
+
+  const userPicked =
+    activeVaultedMethodId != null ? (vaultedMethods.find((m) => m.id === activeVaultedMethodId) ?? null) : null;
+  const activeMethod = userPicked ?? originalDefault;
+
+  // Lite is shown once the shopper has made an explicit selection from the list,
+  // and only while they haven't reverted via Show other ways to pay.
+  // `activeVaultedMethodId` is null until the first selection happens, so the
+  // "no interaction yet" path stays in expanded.
+  const hasUserSelected = activeVaultedMethodId != null;
+  const vaultDisplayMode: VaultDisplayMode =
+    hasUserSelected && vaultDisplayOverride !== 'expanded' ? 'lite' : 'expanded';
+
+  const pay = useCallback(
+    async (additionalData?: PrimerVaultedPaymentMethodAdditionalData) => {
+      if (!activeMethod) return;
+      await payFromVault(activeMethod.id, additionalData);
+    },
+    [activeMethod, payFromVault]
+  );
+
+  const payById = useCallback(
+    async (id: string, additionalData?: PrimerVaultedPaymentMethodAdditionalData) => {
+      await payFromVault(id, additionalData);
+    },
+    [payFromVault]
+  );
+
+  return {
+    vaultedMethods,
+    primaryMethod: originalDefault,
+    originalDefault,
+    activeMethod,
+    vaultDisplayMode,
+    isLoading: isLoadingVaulted,
+    error: vaultedError,
+    requiresVaultedCardCvv,
+    cvvInputVisible,
+    pay,
+    payById,
+    selectVaultedMethodId,
+    requestExpandedVaultDisplay,
+    deleteVaultedPaymentMethod,
+  };
+}

package/src/Components/index.ts

@@ -0,0 +1,77 @@
+export { PrimerCheckoutProvider } from './PrimerCheckoutProvider';
+export { usePrimerCheckout } from './hooks/usePrimerCheckout';
+export { usePrimerLocalization } from './internal/localization';
+export { usePrimerPaymentMethods } from './hooks/usePrimerPaymentMethods';
+export type {
+  PrimerCheckoutProviderProps,
+  PrimerCheckoutContextValue,
+  PaymentOutcome,
+  CardFormState,
+} from './types/PrimerCheckoutProviderTypes';
+export type { TranslationParams } from './internal/localization';
+export type {
+  PaymentMethodItem,
+  PaymentMethodSurcharge,
+  UsePrimerPaymentMethodsOptions,
+  UsePrimerPaymentMethodsReturn,
+} from './types/PaymentMethodTypes';
+export { usePrimerCardForm } from './hooks/usePrimerCardForm';
+export type { UseCardFormOptions, UsePrimerCardFormReturn, CardFormErrors, CardFormField } from './types/CardFormTypes';
+export { usePrimerPaymentMethod } from './hooks/usePrimerPaymentMethod';
+export type {
+  UsePrimerPaymentMethodReturn,
+  NativeUiPaymentMethod,
+  CardPaymentMethod,
+  UnsupportedPaymentMethod,
+  PaymentMethodAvailabilityError,
+} from './types/PrimerPaymentMethodTypes';
+export { usePrimerCardNetwork } from './hooks/usePrimerCardNetwork';
+export type { UseCardNetworkReturn } from './hooks/usePrimerCardNetwork';
+export type { CardNetworkDescriptor, CardNetworkId, CardNetworkIconSource, CvvLabel } from './internal/cardNetwork';
+export { usePrimerBillingAddressForm } from './hooks/usePrimerBillingAddressForm';
+export type {
+  UsePrimerBillingAddressFormOptions,
+  UsePrimerBillingAddressFormReturn,
+  BillingAddressFormErrors,
+  BillingAddressField,
+  PrimerBillingAddressFormProps,
+} from './types/BillingAddressFormTypes';
+export { usePrimerCardNetworkSelection } from './hooks/usePrimerCardNetworkSelection';
+export type { CardNetworkDetails, UsePrimerCardNetworkSelectionReturn } from './types/CardNetworkSelection';
+export { PrimerCardNetworkSelector } from './PrimerCardNetworkSelector';
+export type { PrimerCardNetworkSelectorProps } from './PrimerCardNetworkSelector';
+export { PrimerPaymentMethodList } from './PrimerPaymentMethodList';
+export type { PrimerPaymentMethodListProps } from './types/PrimerPaymentMethodListTypes';
+export { PrimerVaultedPaymentMethod } from './PrimerVaultedPaymentMethod';
+export { usePrimerVaultManager } from './hooks/usePrimerVaultManager';
+export type {
+  VaultedPaymentMethodItem,
+  UsePrimerVaultManagerReturn,
+  PrimerVaultedPaymentMethodProps,
+} from './types/VaultedPaymentMethodTypes';
+export { PrimerCheckoutSheet } from './PrimerCheckoutSheet';
+export type { PrimerCheckoutSheetProps } from './PrimerCheckoutSheet';
+export { PrimerCardForm } from './PrimerCardForm';
+export type { PrimerCardFormProps } from './types/PrimerCardFormTypes';
+export { PrimerCardFormProvider } from './internal/form-state';
+export { PrimerAcceptedCardNetworks } from './PrimerAcceptedCardNetworks';
+export type { PrimerAcceptedCardNetworksProps } from './PrimerAcceptedCardNetworks';
+export { PrimerBillingAddressForm } from './PrimerBillingAddressForm';
+export {
+  PrimerTextInput,
+  PrimerCardNumberInput,
+  PrimerExpiryDateInput,
+  PrimerCVVInput,
+  PrimerCardholderNameInput,
+} from './inputs';
+export type {
+  PrimerTextInputTheme,
+  PrimerTextInputProps,
+  PrimerTextInputRef,
+  CardInputTheme,
+  PrimerCardInputProps,
+  PrimerCardNumberInputProps,
+  PrimerExpiryDateInputProps,
+  PrimerCVVInputProps,
+  PrimerCardholderNameInputProps,
+} from './types/CardInputTypes';

package/src/Components/inputs/CountrySelectorRow.tsx

@@ -0,0 +1,127 @@
+import { useMemo } from 'react';
+import { StyleSheet, Text, TouchableOpacity, View, type StyleProp, type ViewStyle } from 'react-native';
+import { usePrimerTheme } from '../internal/theme';
+import type { PrimerTokens } from '../internal/theme';
+import { flagEmoji } from '../internal/flags';
+import { FIELD_HEIGHT, LINE_HEIGHT_RATIO } from './dimensions';
+
+export interface CountrySelectorRowProps {
+  /** ISO country code currently selected, or empty if none. */
+  value: string;
+  /** Human-readable country name, when available. Falls back to the code, then the placeholder. */
+  displayName?: string;
+  /** Field label shown above the row. */
+  label: string;
+  /** Placeholder shown when no country is selected. */
+  placeholder: string;
+  /** Fires when the row is pressed — host wires navigation to the country selector screen. */
+  onPress: () => void;
+  /** Disables the row. */
+  editable?: boolean;
+  /** Optional outer container style. */
+  style?: StyleProp<ViewStyle>;
+  /** Test ID root. */
+  testID?: string;
+}
+
+export function CountrySelectorRow({
+  value,
+  displayName,
+  label,
+  placeholder,
+  onPress,
+  editable = true,
+  style,
+  testID,
+}: CountrySelectorRowProps) {
+  const tokens = usePrimerTheme();
+  const styles = useMemo(() => createStyles(tokens), [tokens]);
+
+  const hasValue = !!value;
+  const text = hasValue ? (displayName ?? value) : placeholder;
+  const flag = hasValue ? flagEmoji(value) : '';
+
+  return (
+    <View style={[styles.container, style]} testID={testID}>
+      <Text style={styles.label}>{label}</Text>
+      <TouchableOpacity
+        onPress={onPress}
+        disabled={!editable}
+        activeOpacity={0.7}
+        style={[styles.row, !editable && styles.rowDisabled]}
+        accessibilityRole="button"
+        accessibilityState={{ disabled: !editable }}
+        accessibilityLabel={label}
+        accessibilityValue={{ text: hasValue ? text : '' }}
+        testID={testID ? `${testID}-row` : undefined}
+      >
+        {flag !== '' && (
+          <Text style={styles.flag} accessibilityElementsHidden>
+            {flag}
+          </Text>
+        )}
+        <Text
+          style={[styles.value, !hasValue && styles.placeholder]}
+          numberOfLines={1}
+          testID={testID ? `${testID}-value` : undefined}
+        >
+          {text}
+        </Text>
+        <Text style={styles.chevron} accessibilityElementsHidden>
+          ›
+        </Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+
+function createStyles(tokens: PrimerTokens) {
+  const { colors, radii, spacing, typography, borders } = tokens;
+  /* eslint-disable react-native/no-unused-styles */
+  return StyleSheet.create({
+    chevron: {
+      color: tokens.colors.textSecondary,
+      fontSize: typography.bodyLarge.fontSize + 4,
+      lineHeight: FIELD_HEIGHT,
+      marginLeft: spacing.small,
+    },
+    container: {},
+    flag: {
+      fontSize: typography.bodyLarge.fontSize + 4,
+      marginRight: spacing.small,
+      minWidth: 28,
+    },
+    label: {
+      color: colors.textPrimary,
+      fontFamily: typography.fontFamily,
+      fontSize: typography.bodySmall.fontSize,
+      marginBottom: spacing.xsmall,
+    },
+    placeholder: {
+      color: colors.textPlaceholder,
+    },
+    row: {
+      alignItems: 'center',
+      backgroundColor: colors.background,
+      borderColor: colors.border,
+      borderRadius: radii.small,
+      borderWidth: borders.input,
+      flexDirection: 'row',
+      height: FIELD_HEIGHT,
+      paddingHorizontal: spacing.medium,
+    },
+    rowDisabled: {
+      backgroundColor: colors.surface,
+      borderColor: colors.borderDisabled,
+    },
+    value: {
+      color: colors.textPrimary,
+      flex: 1,
+      fontFamily: typography.fontFamily,
+      fontSize: typography.bodyLarge.fontSize,
+      letterSpacing: typography.bodyLarge.letterSpacing,
+      lineHeight: Math.round(typography.bodyLarge.fontSize * LINE_HEIGHT_RATIO),
+    },
+  });
+  /* eslint-enable react-native/no-unused-styles */
+}