fix: reduce min/max amount validation flashing in build quote (#29360)

## **Description**

This PR fixes `TRAM-3472` on the Unified Buy V2 `BuildQuote` screen.

While a user is typing an amount, min/max provider-limit validation was
surfacing immediately on each intermediate value. That made the amount
input and inline error flash red while the user was still entering a
final valid number.

1. **What is the reason for the change?**
The visible limit error was tied directly to the live typed amount, so
transient values like `1` and `10` could momentarily render a min error
before the user finished typing `100`.
2. **What is the improvement/solution?**
Debounce the user-visible min/max error before rendering it, while
keeping the underlying validation immediate so invalid amounts still
block quote fetching and disable Continue right away.

## **Changelog**

CHANGELOG entry: Fixed excessive red flashing while entering buy amounts
near minimum and maximum provider limits.

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TRAM-3472

## **Manual testing steps**

```gherkin
Feature: Buy amount limit validation does not flash while typing

  Scenario: User types through transient below-min values toward a valid amount
    Given the user is on the Build Quote screen
    And the selected provider has a minimum purchase amount
    When the user types an amount quickly toward a valid final value
    Then the minimum purchase error should not flash red for the intermediate values
    And the amount should settle without showing the error if the final value is valid

  Scenario: User pauses on an invalid amount
    Given the user is on the Build Quote screen
    And the selected provider has a minimum or maximum purchase amount
    When the user stops typing on an out-of-bounds amount
    Then the corresponding min or max error should appear after the debounce delay

  Scenario: User corrects an invalid amount back into range
    Given the user can see a min or max purchase error on the Build Quote screen
    When the user updates the amount so it is within the provider limits
    Then the visible limit error should clear immediately
    And quote fetching should resume for the valid amount
```

## **Screenshots/Recordings**

### **Before**

See ticket recording in `TRAM-3472`.

### **After**

https://www.loom.com/share/acff17a2f05c4b1ab576d9664821fda5

<!-- Add updated recording if needed. -->

## **Validation**

- `./node_modules/.bin/jest --runInBand --coverage
--collectCoverageFrom=app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.test.tsx`
- `./node_modules/.bin/jest --runInBand
app/components/UI/Ramp/hooks/useProviderLimits.test.ts`
- `./node_modules/.bin/jest --runInBand
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.test.tsx`
- `./node_modules/.bin/eslint
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.test.tsx`
- `./node_modules/.bin/prettier --check
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx
app/components/UI/Ramp/Views/BuildQuote/BuildQuote.test.tsx`
- Coverage on `BuildQuote.tsx`: 97.29% statements, 88.33% branches,
97.05% functions, 98.87% lines.
- `yarn lint:tsc` currently reports existing repo-wide type errors
outside this diff; no errors reference `BuildQuote.tsx` or
`BuildQuote.test.tsx`.

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [ ] I've tested on Android
- [ ] I've tested with a power user scenario
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk UI/UX change: only delays rendering of min/max limit error
text while keeping the underlying limit validation immediate for quote
fetching and the Continue button.
> 
> **Overview**
> Reduces *min/max provider limit error flashing* on the `BuildQuote`
amount input by debouncing the **user-visible** `amountLimitError` while
still using the immediate error to block quote fetching and disable
Continue.
> 
> Updates tests to mock `useDebouncedValue` more generically and adds
coverage ensuring the limit error text is delayed, clears immediately
once valid, and quote-fetch gating remains immediate.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
ae546a5. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: saustrie-consensys

app/components/UI/Ramp/Views/BuildQuote/BuildQuote.test.tsx

@@ -152,7 +152,7 @@ jest.mock('../../../../hooks/useFormatters', () => ({
 }));
 
 jest.mock('../../../../hooks/useDebouncedValue', () => ({
-  useDebouncedValue: jest.fn((value: number) => value),
+  useDebouncedValue: jest.fn((value: unknown) => value),
 }));
 
 jest.mock('../../hooks/useBlinkingCursor', () => ({
@@ -358,7 +358,7 @@ describe('BuildQuote', () => {
     jest.clearAllMocks();
     mockUseParams.mockReturnValue({});
     mockUseRampsController.mockReturnValue(buildRampsControllerResult());
-    mockUseDebouncedValue.mockImplementation((value: number) => value);
+    mockUseDebouncedValue.mockImplementation((value: unknown) => value);
     mockUseRampsQuotes.mockImplementation((options) =>
       defaultQuotesHookResult(options),
     );
@@ -654,6 +654,75 @@ describe('BuildQuote', () => {
       ).toBe(true);
     });
 
+    it('debounces the visible limit error while keeping quote validation immediate', () => {
+      const providerWithLimits = buildProviderWithLimits({
+        minAmount: 120,
+        maxAmount: 1000,
+      });
+      let debouncedLimitError: string | null = null;
+      mockUseDebouncedValue.mockImplementation((value: unknown) =>
+        typeof value === 'number' ? value : debouncedLimitError,
+      );
+      mockUseRampsController.mockReturnValue(
+        buildRampsControllerResult({
+          providers: [providerWithLimits, NATIVE_PROVIDER],
+          selectedProvider: providerWithLimits,
+        }),
+      );
+
+      const { queryByText, getByTestId, rerender } = renderWithProvider(
+        <BuildQuote />,
+        {
+          state: initialRootState,
+        },
+      );
+
+      expect(queryByText('Minimum purchase is $120.00')).not.toBeOnTheScreen();
+      expect(mockUseRampsQuotes).toHaveBeenLastCalledWith(null);
+
+      const continueButton = getByTestId(BuildQuoteSelectors.CONTINUE_BUTTON);
+      expect(
+        continueButton.props.isDisabled ??
+          continueButton.props.disabled ??
+          continueButton.props.accessibilityState?.disabled,
+      ).toBe(true);
+
+      debouncedLimitError = 'Minimum purchase is $120.00';
+      rerender(<BuildQuote />);
+
+      expect(queryByText('Minimum purchase is $120.00')).toBeOnTheScreen();
+    });
+
+    it('clears the visible limit error immediately once the amount is no longer invalid', () => {
+      const providerWithLimits = buildProviderWithLimits({
+        minAmount: 10,
+        maxAmount: 80,
+      });
+      const debouncedLimitError: string | null = 'Maximum purchase is $80.00';
+      mockUseDebouncedValue.mockImplementation((value: unknown) =>
+        typeof value === 'number' ? value : debouncedLimitError,
+      );
+      mockUseRampsController.mockReturnValue(
+        buildRampsControllerResult({
+          providers: [providerWithLimits, NATIVE_PROVIDER],
+          selectedProvider: providerWithLimits,
+        }),
+      );
+
+      const { getByText, queryByText, getByTestId } = renderWithProvider(
+        <BuildQuote />,
+        {
+          state: initialRootState,
+        },
+      );
+
+      expect(getByText('Maximum purchase is $80.00')).toBeOnTheScreen();
+
+      fireEvent.press(getByTestId('keypad-trigger-empty'));
+
+      expect(queryByText('Maximum purchase is $80.00')).not.toBeOnTheScreen();
+    });
+
     it('fetches quotes normally when the amount is within provider limits', () => {
       const providerWithLimits = buildProviderWithLimits({
         minAmount: 50,
@@ -687,7 +756,9 @@ describe('BuildQuote', () => {
         maxAmount: 200,
       });
       let debouncedAmount = 100;
-      mockUseDebouncedValue.mockImplementation(() => debouncedAmount);
+      mockUseDebouncedValue.mockImplementation((value: unknown) =>
+        typeof value === 'number' ? debouncedAmount : value,
+      );
       mockUseRampsController.mockReturnValue(
         buildRampsControllerResult({
           providers: [providerWithLimits, NATIVE_PROVIDER],

app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx

@@ -396,6 +396,9 @@ function BuildQuote() {
     amount: amountAsNumber,
     currency,
   });
+  const debouncedAmountLimitError = useDebouncedValue(amountLimitError);
+  const displayedAmountLimitError =
+    amountLimitError === debouncedAmountLimitError ? amountLimitError : null;
   const quoteFetchEnabled = !!(
     walletAddress &&
     selectedPaymentMethod &&
@@ -663,7 +666,8 @@ function BuildQuote() {
     return firstError?.error;
   }, [hasNoQuotes, quotesResponse?.error]);
 
-  const inlineQuoteError = amountLimitError ?? providerQuoteError ?? null;
+  const inlineQuoteError =
+    displayedAmountLimitError ?? providerQuoteError ?? null;
   const hasGenericNoQuotes = hasNoQuotes && !providerQuoteError;
   const amountInputHasError = Boolean(
     rampsError || quoteFetchError || inlineQuoteError || hasGenericNoQuotes,