fix: prevent balance empty state flash during wallet import and account switching (MetaMask#23351)

## **Description**

This PR creates a temporary fix for a UX issue where the "Fund your
wallet" empty state briefly flashes when importing a wallet with
existing funds or switching between funded accounts. This happened
because the balance calculation returned $0 while price and balance data
were still loading, causing the empty state to appear before the actual
balance was displayed.

_**"Telling a user they need to fund an account that might have
thousands of dollars in it is confusing at best and mildly
panic-inducing at worst."**_

### Problem

PR MetaMask#21391 introduced a balance empty state that displays when users have
zero mainnet balance. However, due to how balance data loads
asynchronously, users would see:
1. Skeleton loader (correct)
2. **"Fund your wallet" empty state (incorrect - account has funds!)**
3. Actual balance appears (e.g., $49.21)

This flash occurred because:
- Balance calculations depend on multiple data sources (price data,
token balances, native balances)
- These data sources load at different times via polling
- The `AccountTrackerController `always initializes accounts with
`balance: "0x0"`
- We cannot distinguish between "balance is loading" vs "balance is
genuinely $0"

### Solutions Considered

We evaluated several approaches to solve this issue:

#### Option 1: Add Loading State to `AccountTrackerController` ❌
- **Approach**: Modify the core controller to track whether native
balances have been fetched
- **Why rejected**: This is the ideal state but would require changes to
`@metamask/assets-controllers` (shared between mobile and extension),
introducing complexity and breaking type changes across the codebase.
Too large of a scope for this fix.

#### Option 2: Check Controller Initialization State ❌
- **Approach**: Create a selector that validates all price/balance
controllers have initialized
- **Why rejected**: Controllers persist state via redux-persist, so they
always appear "initialized" even with stale data from previous sessions.
Logs confirmed this - all controllers report "state persisted
successfully" immediately on load.

#### Option 3: Balance Change Tracking + Timeout ✅ (Chosen)
- **Approach**: Track when balance values actually change from their
initial value, with a timeout fallback
- **Why chosen**: 
  - Works with existing architecture without controller modifications
- Relies on observable behavior (balance updates) rather than internal
controller state
- Handles all edge cases: fresh imports, account switching, genuinely
empty wallets
  - Simple component-level solution
- **Most importantly**: Prevents showing "fund your wallet" to users
with existing funds

### Implementation

The solution adds balance change tracking to `AccountGroupBalance`
component:

1. **Track account switches** via `groupId` changes - resets all
tracking state
2. **Monitor balance changes** from initial $0 value - marks as
"fetched" when balance updates
3. **Fallback timeout** (3 seconds) - handles genuinely $0 balances or
slow API responses
4. **Dual balance tracking** - watches both `groupBalance` and
`accountGroupBalance` since empty state decision uses the latter

The skeleton loader now displays until either:
- Balance changes from its initial value, OR
- 3-second timeout expires

This ensures users never see the empty state flash for funded accounts.

## **Changelog**

CHANGELOG entry: Fixed an issue where "Fund your wallet" empty state
briefly appeared when importing wallets with existing funds or switching
between funded accounts

## **Related issues**

Fixes: (related to MetaMask#21391 - balance empty state implementation)

## **Manual testing steps**

\`\`\`gherkin
Feature: Balance empty state loading behavior

  Scenario: Import wallet with funded accounts
    Given the app is freshly installed
    When user imports a wallet using SRP with funded accounts
    Then user should see skeleton loader
    And user should NOT see "Fund your wallet" empty state
    And user should see actual balance (e.g., "$49.21")

  Scenario: Switch between funded accounts
    Given user has multiple accounts with funds
    When user switches from Account 1 to Account 2
    Then user should see skeleton loader briefly
    And user should NOT see "Fund your wallet" empty state
    And user should see Account 2's balance

  Scenario: Import wallet with zero balance
    Given the app is freshly installed
    When user imports a wallet with zero mainnet balance
    Then user should see skeleton loader
    And after 3 seconds, user should see "Fund your wallet" empty state

  Scenario: Switch to account with zero balance
    Given user has account with zero mainnet balance
    When user switches to the zero-balance account
    Then user should see skeleton loader
    And after 3 seconds, user should see "Fund your wallet" empty state
\`\`\`

## **Screenshots/Recordings**

### **Before**

Empty state incorrectly flashed when importing wallet with funds or
switching accounts.


https://github.com/user-attachments/assets/945567d9-e9b1-458d-aecc-66f05384bcc9

### **After**

Skeleton loader now prevents layout shift displays until balance is
confirmed, preventing false "fund your wallet" messaging.


https://github.com/user-attachments/assets/f1763e5c-f9b4-43c3-98a5-4525a2e83a9c

## **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.

## **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]
> Prevents the “Fund your wallet” flash by tracking balance fetch with a
3s timeout and using Skeleton to hide content until ready; updates
Skeleton behavior and related tests/styles.
> 
> - **Account Group Balance**
> - Implement balance fetch tracking with a 3s timeout using
`hasBalanceFetched`, `groupId` change detection, and initial balance
refs in `AccountGroupBalance.tsx`.
> - Gate empty state rendering (`BalanceEmptyState`) until loading
completes; compute `isLoading = !groupBalance || !hasBalanceFetched`.
> - Wrap balance and change components with `Skeleton` using
`hideChildren` to avoid content flash.
> - Adjust styles to column layout and left alignment in
`AccountGroupBalance.styles.ts`.
> - **Skeleton Component**
> - Change render logic to return `children` directly when
`hideChildren` is false; otherwise render animated placeholder and
optional children wrapper.
> - **Tests**
> - Add timer-based tests covering timeout-driven display, immediate
display on balance change, and zero-balance empty state.
> - Update Skeleton tests to reflect new child rendering behavior and
animation conditions.
> - Remove redundant story/use case and align stories with new
`hideChildren` flow.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
4396697. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: georgewrmarshall

app/component-library/components/Skeleton/Skeleton.stories.tsx

@@ -56,28 +56,6 @@ export const WidthHeight = () => {
   );
 };
 
-export const WithChildren = () => {
-  const styles = StyleSheet.create({
-    container: {
-      display: 'flex',
-      flexDirection: 'column',
-      borderRadius: 12,
-      padding: 16,
-    },
-    skeleton: {
-      marginBottom: 8,
-    },
-  });
-
-  return (
-    <SkeletonComponent style={styles.container}>
-      <SkeletonComponent height={32} width="100%" style={styles.skeleton} />
-      <SkeletonComponent height={16} width="95%" style={styles.skeleton} />
-      <SkeletonComponent height={16} width="95%" />
-    </SkeletonComponent>
-  );
-};
-
 export const HideChildren = () => {
   const [isLoaded, setIsLoaded] = useState(false);
   const styles = StyleSheet.create({

app/component-library/components/Skeleton/Skeleton.test.tsx

@@ -57,22 +57,6 @@ describe('Skeleton', () => {
     expect(skeletonElement.props.style.width).toBe('100%');
   });
 
-  it('should render with children', () => {
-    const childTestId = 'child-component';
-    const childrenWrapperId = 'children-wrapper';
-
-    const { getByTestId } = render(
-      <Skeleton childrenWrapperProps={{ testID: childrenWrapperId }}>
-        <View testID={childTestId} />
-      </Skeleton>,
-    );
-
-    const childElement = getByTestId(childTestId);
-    const childrenWrapper = getByTestId(childrenWrapperId);
-    expect(childElement).toBeDefined();
-    expect(childrenWrapper).toBeDefined();
-  });
-
   it('should hide children when hideChildren is true', () => {
     const childTestId = 'child-component';
     const childrenWrapperId = 'children-wrapper';
@@ -92,16 +76,14 @@ describe('Skeleton', () => {
 
   it('should display children normally when hideChildren is false', () => {
     const childTestId = 'child-component';
-    const childrenWrapperId = 'children-wrapper';
 
     const { getByTestId } = render(
-      <Skeleton childrenWrapperProps={{ testID: childrenWrapperId }}>
+      <Skeleton>
         <View testID={childTestId} />
       </Skeleton>,
     );
 
-    const childrenWrapper = getByTestId(childrenWrapperId);
-    expect(childrenWrapper.props.style[1]).toBe(undefined);
+    expect(getByTestId(childTestId)).toBeDefined();
   });
 
   it('should animate when no children are present', () => {

app/component-library/components/Skeleton/Skeleton.tsx

@@ -63,26 +63,32 @@ const Skeleton: React.FC<SkeletonProps> = ({
   }, [children, hideChildren]); // eslint-disable-line react-hooks/exhaustive-deps
 
   return (
-    <View style={styles.base} {...props}>
-      {/* Animated background always present */}
-      <Animated.View
-        style={[styles.background, { opacity: opacityAnim }]}
-        pointerEvents="none"
-        {...animatedViewProps}
-      />
+    <>
+      {!hideChildren && children ? (
+        children
+      ) : (
+        <View style={styles.base} {...props}>
+          {/* Animated background always present */}
+          <Animated.View
+            style={[styles.background, { opacity: opacityAnim }]}
+            pointerEvents="none"
+            {...animatedViewProps}
+          />
 
-      {children && (
-        <View
-          style={[
-            styles.childrenContainer,
-            hideChildren ? styles.hideChildren : undefined,
-          ]}
-          {...childrenWrapperProps}
-        >
-          {children}
+          {children && (
+            <View
+              style={[
+                styles.childrenContainer,
+                hideChildren ? styles.hideChildren : undefined,
+              ]}
+              {...childrenWrapperProps}
+            >
+              {children}
+            </View>
+          )}
         </View>
       )}
-    </View>
+    </>
   );
 };
 

app/components/UI/Assets/components/Balance/AccountGroupBalance.styles.ts

@@ -5,12 +5,9 @@ const createStyles = () =>
       marginHorizontal: 16,
     },
     balanceContainer: {
-      flexDirection: 'row',
-      alignItems: 'center',
-    },
-    skeletonContainer: {
       flexDirection: 'column',
       gap: 4,
+      alignItems: 'flex-start',
     },
   });
 

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import { act } from '@testing-library/react-native';
 import AccountGroupBalance from './AccountGroupBalance';
 import { WalletViewSelectorsIDs } from '../../../../../../e2e/selectors/wallet/WalletView.selectors';
 import renderWithProvider from '../../../../../util/test/renderWithProvider';
@@ -56,15 +57,41 @@ const testState = {
 };
 
 describe('AccountGroupBalance', () => {
-  it('renders loader when balance is not ready', () => {
-    const { queryByTestId } = renderWithProvider(<AccountGroupBalance />, {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Reset mock implementations to default (null) before each test
+    const {
+      selectBalanceBySelectedAccountGroup,
+      selectAccountGroupBalanceForEmptyState,
+      selectBalanceChangeBySelectedAccountGroup,
+    } = jest.requireMock('../../../../../selectors/assets/balances');
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => null,
+    );
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => null,
+    );
+    (selectBalanceChangeBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => () => null,
+    );
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+
+  it('renders without crashing when balance is not ready', () => {
+    const { getByTestId } = renderWithProvider(<AccountGroupBalance />, {
       state: testState,
     });
 
-    expect(queryByTestId(WalletViewSelectorsIDs.TOTAL_BALANCE_TEXT)).toBeNull();
+    // Component should render the balance container even when loading
+    expect(getByTestId('balance-container')).toBeOnTheScreen();
   });
 
-  it('renders formatted balance when selector returns data', () => {
+  it('renders formatted balance when selector returns data and timeout expires', () => {
     const { selectBalanceBySelectedAccountGroup } = jest.requireMock(
       '../../../../../selectors/assets/balances',
     );
@@ -81,20 +108,27 @@ describe('AccountGroupBalance', () => {
       state: testState,
     });
 
+    // After timeout expires (3 seconds), balance should display
+    act(() => {
+      jest.advanceTimersByTime(3000);
+    });
+
     const el = getByTestId(WalletViewSelectorsIDs.TOTAL_BALANCE_TEXT);
-    expect(el).toBeTruthy();
+    expect(el).toBeOnTheScreen();
   });
 
-  it('renders empty state when account group balance is zero', () => {
+  it('renders empty state when account group balance is zero after timeout', () => {
     const {
       selectAccountGroupBalanceForEmptyState,
       selectBalanceBySelectedAccountGroup,
     } = jest.requireMock('../../../../../selectors/assets/balances');
 
-    // Mock the regular balance selector to return data (prevents skeleton loader)
+    // Mock the regular balance selector to return zero balance data
     (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
       () => ({
-        totalBalanceInUserCurrency: 100, // Some non-zero amount for current network
+        walletId: 'wallet-1',
+        groupId: 'wallet-1/group-1',
+        totalBalanceInUserCurrency: 0, // Zero on current network
         userCurrency: 'usd',
       }),
     );
@@ -107,13 +141,142 @@ describe('AccountGroupBalance', () => {
       }),
     );
 
-    const { getByTestId } = renderWithProvider(<AccountGroupBalance />, {
-      state: testState,
+    const { getByTestId, queryByTestId } = renderWithProvider(
+      <AccountGroupBalance />,
+      {
+        state: testState,
+      },
+    );
+
+    // Initially shows loader because hasBalanceFetched is false
+    expect(
+      queryByTestId(WalletViewSelectorsIDs.BALANCE_EMPTY_STATE_CONTAINER),
+    ).toBeNull();
+
+    // After timeout expires (3 seconds), empty state should display
+    act(() => {
+      jest.advanceTimersByTime(3000);
     });
 
     const el = getByTestId(
       WalletViewSelectorsIDs.BALANCE_EMPTY_STATE_CONTAINER,
     );
     expect(el).toBeOnTheScreen();
   });
+
+  it('renders balance immediately when balance changes from 0 to non-zero before timeout', () => {
+    const {
+      selectBalanceBySelectedAccountGroup,
+      selectAccountGroupBalanceForEmptyState,
+    } = jest.requireMock('../../../../../selectors/assets/balances');
+
+    // Start with zero balance
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => ({
+        walletId: 'wallet-1',
+        groupId: 'wallet-1/group-1',
+        totalBalanceInUserCurrency: 0,
+        userCurrency: 'usd',
+      }),
+    );
+
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 0,
+        userCurrency: 'usd',
+      }),
+    );
+
+    const { getByTestId, rerender } = renderWithProvider(
+      <AccountGroupBalance />,
+      {
+        state: testState,
+      },
+    );
+
+    // Update mocks to return non-zero balance (simulating balance fetch completing)
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => ({
+        walletId: 'wallet-1',
+        groupId: 'wallet-1/group-1',
+        totalBalanceInUserCurrency: 123.45,
+        userCurrency: 'usd',
+      }),
+    );
+
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 123.45,
+        userCurrency: 'usd',
+      }),
+    );
+
+    // Trigger re-render with new balance
+    rerender(<AccountGroupBalance />);
+
+    // Balance should display immediately without waiting for timeout
+    const el = getByTestId(WalletViewSelectorsIDs.TOTAL_BALANCE_TEXT);
+    expect(el).toBeOnTheScreen();
+  });
+
+  it('renders balance after updating when initially zero', () => {
+    const {
+      selectBalanceBySelectedAccountGroup,
+      selectAccountGroupBalanceForEmptyState,
+    } = jest.requireMock('../../../../../selectors/assets/balances');
+
+    // Start with zero balance (simulates account with no funds or just switched)
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => ({
+        walletId: 'wallet-1',
+        groupId: 'wallet-1/group-1',
+        totalBalanceInUserCurrency: 0,
+        userCurrency: 'usd',
+      }),
+    );
+
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 0,
+        userCurrency: 'usd',
+      }),
+    );
+
+    const { getByTestId, rerender } = renderWithProvider(
+      <AccountGroupBalance />,
+      {
+        state: testState,
+      },
+    );
+
+    // Advance time less than timeout
+    act(() => {
+      jest.advanceTimersByTime(1000);
+    });
+
+    // Update mocks to show balance has loaded with funds
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => ({
+        walletId: 'wallet-1',
+        groupId: 'wallet-1/group-1',
+        totalBalanceInUserCurrency: 150,
+        userCurrency: 'usd',
+      }),
+    );
+
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 150,
+        userCurrency: 'usd',
+      }),
+    );
+
+    // Trigger re-render
+    rerender(<AccountGroupBalance />);
+
+    // Should show balance immediately after update (hasChanged condition)
+    expect(
+      getByTestId(WalletViewSelectorsIDs.TOTAL_BALANCE_TEXT),
+    ).toBeOnTheScreen();
+  });
 });