refactor(ramps): ramps controller geolocation rename

[georgeweiler]

Explanation

Current State and Why It Needs to Change

The RampsController currently uses "geolocation" terminology (geolocation state, updateGeolocation() method), which implies a read-only, automatically-detected value. However, we plan to allow users to manually change their region in the future, so the naming should reflect that it's a user-selectable region rather than just a detected geolocation.

Additionally, consumers must manually call updateGeolocation() after creating the controller, which is error-prone and lacks a clear initialization pattern.

Solution and How It Works

This PR refactors the controller to use "userRegion" terminology and introduces proper initialization:

1. Renamed state and methods: geolocation → userRegion, updateGeolocation() → updateUserRegion()
2. Added init() method: Encapsulates initialization logic, automatically fetches user region at startup
3. Added setUserRegion() method: Allows manual region setting without geolocation API, preparing for future UI feature

Breaking Changes

• geolocation state property → userRegion
• updateGeolocation() method → updateUserRegion()
• Removed deprecated selectGeolocation and selectGeolocationRequest selectors
• Removed deprecated useRampsGeolocation() hook
• Consumers should use selectUserRegion, selectUserRegionRequest, and useRampsUserRegion() instead

Why Multiple Packages Were Updated

This refactor touches both the core controller package and the mobile app because:

• Core package contains the controller implementation and public API
• Mobile app contains initialization, selectors, hooks, and tests that consume the controller

All changes are coordinated to ensure consistent API updates and proper migration from deprecated names.

References

Mobile PR that adopts the breaking changes: MetaMask/metamask-mobile#24280

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

Note

BREAKING: Rename geolocation API

• State geolocation → userRegion; method updateGeolocation() → updateUserRegion() with updated request cache keys and tests

New APIs

• Add init() to fetch initial userRegion on startup (graceful failure)
• Add setUserRegion(region) to manually set region and fetch eligibility

Behavioral updates

• Normalize region to lowercase; automatically fetch eligibility after updateUserRegion
• Clear stale eligibility on failures only if region still matches; prevent race-based overwrites
• updateEligibility(isoCode) only updates state when userRegion matches the isoCode/undefined
• Handle null/undefined geolocation results

Misc

• Update createRequestSelector examples and tests to reference updateUserRegion
• Changelog updated

^{Written by Cursor Bugbot for commit ab80f89. This will update automatically on new commits. Configure here.}

[wachunei]

small suggestion for readability: extract state.geolocation as a variable to avoid the null check and string manipulation on separate lines:

this.update((state) => {
  const userRegion = state.geolocation?.toLowerCase().trim();
  
  if (userRegion === null || userRegion === normalizedIsoCode) {
    state.eligibility = eligibility;
  }
});