feat(ramp): add navigateToRampBuy helper and refactor useRampNavigation

app/components/UI/Ramp/hooks/useRampNavigation.ts

@@ -6,25 +6,16 @@
   RampType as AggregatorRampType,
 } from '../Aggregator/types';
 import { createRampNavigationDetails } from '../Aggregator/routes/utils';
 import { createDepositNavigationDetails } from '../Deposit/routes/utils';
-import { createTokenSelectionNavDetails } from '../Views/TokenSelection/TokenSelection';
-import { createBuildQuoteNavDetails } from '../Views/BuildQuote';
-import type { BuyFlowOrigin } from '../Views/BuildQuote/BuildQuote';
-import useRampsUnifiedV1Enabled from './useRampsUnifiedV1Enabled';
-import useRampsUnifiedV2Enabled from './useRampsUnifiedV2Enabled';
 import {
-  getRampRoutingDecision,
-  UnifiedRampRoutingType,
-} from '../../../../reducers/fiatOrders';
-import { createRampUnsupportedModalNavigationDetails } from '../components/RampUnsupportedModal/RampUnsupportedModal';
-import { createEligibilityFailedModalNavigationDetails } from '../components/EligibilityFailedModal/EligibilityFailedModal';
+  navigateToRampBuy,
+  NavigateToRampBuyMode,
+  type NavigateToRampBuyOptions,
+} from '../utils/navigateToRampBuy';
+import { getRampRoutingDecision } from '../../../../reducers/fiatOrders';
 import { useRampsTokens } from './useRampsTokens';
-import { resolveRampControllerAssetId } from '../utils/resolveRampControllerAssetId';
-
-enum RampMode {
-  AGGREGATOR = 'AGGREGATOR',
-  DEPOSIT = 'DEPOSIT',
-}
+import useRampsUnifiedV1Enabled from './useRampsUnifiedV1Enabled';
+import useRampsUnifiedV2Enabled from './useRampsUnifiedV2Enabled';
 
 /**
  * Hook that returns functions to navigate to ramp flows.
@@ -43,106 +34,14 @@
   const { setSelectedToken, tokens: rampsTokens } = useRampsTokens();
 
   const goToBuy = useCallback(
-    (
-      intent?: RampIntent,
-      options?: {
-        mode?: RampMode;
-        overrideUnifiedRouting?: boolean;
-        buyFlowOrigin?: BuyFlowOrigin;
-      },
-    ) => {
-      const { mode = RampMode.AGGREGATOR, overrideUnifiedRouting = false } =
-        options || {};
-
-      const isUnifiedRoutingEnabled =
-        (isRampsUnifiedV1Enabled || isRampsUnifiedV2Enabled) &&
-        !overrideUnifiedRouting;
-
-      // Check error states first (applies to both V1 and V2)
-      if (isUnifiedRoutingEnabled) {
-        if (rampRoutingDecision === UnifiedRampRoutingType.ERROR) {
-          navigation.navigate(
-            ...createEligibilityFailedModalNavigationDetails(),
-          );
-          return;
-        }
-
-        if (rampRoutingDecision === UnifiedRampRoutingType.UNSUPPORTED) {
-          navigation.navigate(...createRampUnsupportedModalNavigationDetails());
-          return;
-        }
-      }
-
-      // V2: If assetId is provided and V2 is enabled, route to BuildQuote
-      // TODO: Check for provider support for the token and pass params to BuildQuote to show an error modal
-      if (
-        isRampsUnifiedV2Enabled &&
-        intent?.assetId &&
-        !overrideUnifiedRouting
-      ) {
-        // Resolve to the controller's canonical assetId format (lowercase)
-        const controllerAssetId = resolveRampControllerAssetId(
-          intent.assetId,
-          rampsTokens?.allTokens ?? [],
-        );
-        try {
-          setSelectedToken(controllerAssetId);
-        } catch {
-          // Token may not be in controller's list yet (still loading).
-          // Navigate anyway — BuildQuote will handle the missing token.
-        }
-        navigation.navigate(
-          ...createBuildQuoteNavDetails({
-            assetId: controllerAssetId,
-            buyFlowOrigin: options?.buyFlowOrigin,
-          }),
-        );
-        return;
-      }
-
-      // V2: If no assetId and V2 is enabled, route to TokenSelection (matches handleRampUrl deeplink behavior)
-      if (
-        isRampsUnifiedV2Enabled &&
-        !intent?.assetId &&
-        !overrideUnifiedRouting
-      ) {
-        navigation.navigate(...createTokenSelectionNavDetails());
-        return;
-      }
-
-      // V1 routing logic
-      if (isRampsUnifiedV1Enabled && !overrideUnifiedRouting) {
-        // If no assetId is provided, route to TokenSelection
-        if (!intent?.assetId) {
-          navigation.navigate(...createTokenSelectionNavDetails());
-          return;
-        }
-
-        // If routing decision hasn't been determined yet, route to TokenSelection
-        if (rampRoutingDecision === null) {
-          navigation.navigate(...createTokenSelectionNavDetails());
-          return;
-        }
-
-        // If assetId is provided, route based on rampRoutingDecision
-        if (rampRoutingDecision === UnifiedRampRoutingType.DEPOSIT) {
-          navigation.navigate(...createDepositNavigationDetails(intent));
-        } else if (rampRoutingDecision === UnifiedRampRoutingType.AGGREGATOR) {
-          navigation.navigate(
-            ...createRampNavigationDetails(AggregatorRampType.BUY, intent),
-          );
-        }
-        return;
-      }
-
-      // When overriding unified routing or when v1 is disabled
-      if (mode === RampMode.DEPOSIT) {
-        navigation.navigate(...createDepositNavigationDetails(intent));
-      } else {
-        navigation.navigate(
-          ...createRampNavigationDetails(AggregatorRampType.BUY, intent),
-        );
-      }
+    (intent?: RampIntent, options?: NavigateToRampBuyOptions) => {
+      navigateToRampBuy(navigation, intent, options, {
+        isRampsUnifiedV1Enabled,
+        isRampsUnifiedV2Enabled,
+        rampRoutingDecision,
+        rampsTokensAll: rampsTokens?.allTokens ?? [],
+        setSelectedToken,
+      });
     },
     [
       setSelectedToken,
@@ -161,7 +60,7 @@
   const goToAggregator = useCallback(
     (intent?: RampIntent) => {
       goToBuy(intent, {
-        mode: RampMode.AGGREGATOR,
+        mode: NavigateToRampBuyMode.AGGREGATOR,
         overrideUnifiedRouting: true,
       });
     },
@@ -184,12 +83,14 @@
   const goToDeposit = useCallback(
     (intent?: RampIntent) => {
       goToBuy(intent, {
-        mode: RampMode.DEPOSIT,
+        mode: NavigateToRampBuyMode.DEPOSIT,
         overrideUnifiedRouting: true,
       });
     },
     [goToBuy],
   );
 
+  // Deprecated entries remain part of the public hook API for existing callers.
+  // eslint-disable-next-line @typescript-eslint/no-deprecated -- backward-compatible exports
   return { goToBuy, goToAggregator, goToSell, goToDeposit };
 };

app/components/UI/Ramp/navigation.ts

@@ -0,0 +1,13 @@
+/**
+ * Stable, shallow imports for cross-team ramp **buy** navigation.
+ * Prefer importing from this module rather than deep Aggregator/Deposit paths.
+ */
+export { navigateToRampBuy } from './utils/navigateToRampBuy';
+export type {
+  NavigateToRampBuyNavigation,
+  NavigateToRampBuyDeps,
+  NavigateToRampBuyOptions,
+} from './utils/navigateToRampBuy';
+export { NavigateToRampBuyMode } from './utils/navigateToRampBuy';
+export type { RampIntent } from './types';
+export type { BuyFlowOrigin } from './Views/BuildQuote/BuildQuote';