feat: add HardwarewalletProvider and HardwareWalletBottomSheet for HW lifecycle and error management (#26520)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

Part 4 of the hardware wallet connection & error management overhaul.
This does not introduce user facing changes.

Will close:
- https://consensyssoftware.atlassian.net/browse/MUL-1303
- https://consensyssoftware.atlassian.net/browse/MUL-1494

Final implementation will look like this ([Figma
designs](https://www.figma.com/design/1F3yNWYLOVPFpTPeJugH20/SWAP?node-id=11110-19571&t=tPMZNNiwCgbDfegd-0)):
<img width="1404" height="631" alt="image"
src="https://github.com/user-attachments/assets/68850711-f53b-4060-8b47-6faceb67f82f"
/>

Reference feature branch:
#25519

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: null

## **Related issues**

Fixes:

## **Manual testing steps**

no manual testing steps

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

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

- [x] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [x] 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]
> **Medium Risk**
> Moderate risk because it adds new state-management and error/transport
handling paths in hardware-wallet connection flows; behavior changes are
largely encapsulated but could affect connection/retry UX and edge
cases.
> 
> **Overview**
> Introduces a new unified hardware wallet connection flow via
`HardwareWalletProvider` and a state-driven `HardwareWalletBottomSheet`,
covering scanning/device selection, connecting, awaiting app, awaiting
confirmation, error, and success states.
> 
> The provider now owns adapter lifecycle, device discovery,
retry/last-operation tracking, and transport availability monitoring
(surfacing transport-disabled errors when availability drops mid-flow),
and wires internal actions into the bottom sheet.
> 
> Adds the bottom sheet content components (`ConnectingContent`,
`DeviceSelectionContent`, `AwaitingAppContent`,
`AwaitingConfirmationContent`, `ErrorContent`, `SuccessContent`),
comprehensive unit tests for the provider, sheet, and content behaviors,
and new `en.json` i18n strings under `hardware_wallet`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
69a47be. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Gustavo Antunes <17601467+gantunesr@users.noreply.github.com>

Author: mathieuartu

app/core/HardwareWallet/HardwareWalletProvider.test.tsx

@@ -0,0 +1,251 @@
+import React, { useMemo, useRef, useCallback, useEffect } from 'react';
+import { StyleSheet } from 'react-native';
+
+import BottomSheet, {
+  BottomSheetRef,
+} from '../../../../component-library/components/BottomSheets/BottomSheet';
+
+import { useTheme } from '../../../../util/theme';
+
+import {
+  HardwareWalletType,
+  HardwareWalletConnectionState,
+  ConnectionStatus,
+} from '@metamask/hw-wallet-sdk';
+
+import {
+  ConnectingContent,
+  DeviceSelectionContent,
+  AwaitingAppContent,
+  AwaitingConfirmationContent,
+  ErrorContent,
+  SuccessContent,
+} from './contents';
+import { DiscoveredDevice, type DeviceSelectionState } from '../../types';
+import DevLogger from '../../../SDKConnect/utils/DevLogger';
+
+export const HARDWARE_WALLET_BOTTOM_SHEET_TEST_ID =
+  'hardware-wallet-bottom-sheet';
+
+const createStyles = (colors: { background: { default: string } }) =>
+  StyleSheet.create({
+    bottomSheet: {
+      backgroundColor: colors.background.default,
+    },
+  });
+
+export interface HardwareWalletBottomSheetProps {
+  connectionState: HardwareWalletConnectionState;
+  deviceSelection: DeviceSelectionState;
+  walletType: HardwareWalletType | null;
+  connectionTips: string[];
+
+  retryLastOperation: () => Promise<void>;
+  selectDevice: (device: DiscoveredDevice) => void;
+  rescan: () => void;
+  connect: (deviceId: string) => Promise<void>;
+
+  /** Callback when sheet is dismissed (handles all cleanup) */
+  onClose?: () => void;
+  /** Show success state briefly before hiding (ms, 0 to disable) */
+  successAutoDismissMs?: number;
+  /** Callback when connection succeeds (e.g., to navigate to account selection) */
+  onConnectionSuccess?: () => void;
+  /** Callback when user cancels during awaiting confirmation state */
+  onAwaitingConfirmationCancel?: () => void;
+}
+
+/**
+ * Unified Hardware Wallet Bottom Sheet
+ *
+ * Automatically displays the appropriate content based on connection state:
+ * - Scanning: Device selection list
+ * - Connecting: Shows tips and loading spinner
+ * - AwaitingApp: Prompts user to open correct app
+ * - AwaitingConfirmation: Prompts user to confirm on device
+ * - Error: Shows error with recovery actions
+ * - Ready: Shows success feedback
+ */
+export const HardwareWalletBottomSheet: React.FC<
+  HardwareWalletBottomSheetProps
+> = ({
+  connectionState,
+  deviceSelection,
+  walletType,
+  connectionTips,
+  retryLastOperation,
+  selectDevice,
+  rescan,
+  connect,
+  onClose,
+  successAutoDismissMs = 1000,
+  onConnectionSuccess,
+  onAwaitingConfirmationCancel,
+}) => {
+  const { colors } = useTheme();
+  const styles = useMemo(() => createStyles(colors), [colors]);
+
+  const bottomSheetRef = useRef<BottomSheetRef>(null);
+
+  const { devices, selectedDevice, isScanning } = deviceSelection;
+
+  const shouldShow = useMemo(() => {
+    switch (connectionState.status) {
+      case ConnectionStatus.Scanning:
+      case ConnectionStatus.Connecting:
+      case ConnectionStatus.Connected:
+      case ConnectionStatus.AwaitingApp:
+      case ConnectionStatus.AwaitingConfirmation:
+      case ConnectionStatus.ErrorState:
+      case ConnectionStatus.Ready:
+        return true;
+      default:
+        return false;
+    }
+  }, [connectionState.status]);
+
+  useEffect(() => {
+    DevLogger.log(
+      '[HardwareWalletBottomSheet] shouldShow:',
+      shouldShow,
+      'status:',
+      connectionState.status,
+    );
+  }, [shouldShow, connectionState.status]);
+
+  const handleClose = useCallback(() => {
+    if (connectionState.status === ConnectionStatus.AwaitingConfirmation) {
+      onAwaitingConfirmationCancel?.();
+    }
+    onClose?.();
+  }, [connectionState.status, onAwaitingConfirmationCancel, onClose]);
+
+  const handleAwaitingConfirmationCancel = useCallback(() => {
+    onAwaitingConfirmationCancel?.();
+  }, [onAwaitingConfirmationCancel]);
+
+  const handleErrorContinue = useCallback(async () => {
+    await retryLastOperation();
+  }, [retryLastOperation]);
+
+  const handleErrorDismiss = useCallback(() => {
+    onClose?.();
+  }, [onClose]);
+
+  const handleSuccessDismiss = useCallback(() => {
+    onConnectionSuccess?.();
+  }, [onConnectionSuccess]);
+
+  const handleSelectDevice = useCallback(
+    (selectedDev: DiscoveredDevice) => {
+      selectDevice(selectedDev);
+    },
+    [selectDevice],
+  );
+
+  const handleConfirmDeviceSelection = useCallback(async () => {
+    if (selectedDevice) {
+      DevLogger.log(
+        '[HardwareWalletBottomSheet] Connecting to device:',
+        selectedDevice.id,
+      );
+      await connect(selectedDevice.id);
+    }
+  }, [selectedDevice, connect]);
+
+  const handleRescan = useCallback(() => {
+    rescan();
+  }, [rescan]);
+
+  const handleCancelDeviceSelection = useCallback(() => {
+    onClose?.();
+  }, [onClose]);
+
+  // The effective device type — only used when the sheet is visible,
+  // so walletType should always be set by then.
+  const deviceType = walletType ?? HardwareWalletType.Ledger;
+
+  const renderContent = () => {
+    switch (connectionState.status) {
+      case ConnectionStatus.Ready:
+        return (
+          <SuccessContent
+            deviceType={deviceType}
+            onDismiss={handleSuccessDismiss}
+            autoDismissMs={successAutoDismissMs}
+          />
+        );
+
+      case ConnectionStatus.Scanning:
+        return (
+          <DeviceSelectionContent
+            devices={devices}
+            selectedDevice={selectedDevice ?? undefined}
+            isScanning={isScanning}
+            deviceType={deviceType}
+            onSelectDevice={handleSelectDevice}
+            onConfirmSelection={handleConfirmDeviceSelection}
+            onRescan={handleRescan}
+            onCancel={handleCancelDeviceSelection}
+          />
+        );
+
+      case ConnectionStatus.Connecting:
+      case ConnectionStatus.Connected:
+        return (
+          <ConnectingContent
+            deviceType={deviceType}
+            connectionTips={connectionTips}
+          />
+        );
+
+      case ConnectionStatus.AwaitingApp:
+        return (
+          <AwaitingAppContent
+            deviceType={deviceType}
+            requiredApp={connectionState.appName}
+            onContinue={handleErrorContinue}
+          />
+        );
+
+      case ConnectionStatus.AwaitingConfirmation:
+        return (
+          <AwaitingConfirmationContent
+            deviceType={deviceType}
+            operationType={connectionState.operationType}
+            onCancel={handleAwaitingConfirmationCancel}
+          />
+        );
+
+      case ConnectionStatus.ErrorState:
+        return (
+          <ErrorContent
+            error={connectionState.error}
+            deviceType={deviceType}
+            onContinue={handleErrorContinue}
+            onDismiss={handleErrorDismiss}
+          />
+        );
+
+      default:
+        return null;
+    }
+  };
+
+  if (!shouldShow) {
+    return null;
+  }
+
+  return (
+    <BottomSheet
+      ref={bottomSheetRef}
+      testID={HARDWARE_WALLET_BOTTOM_SHEET_TEST_ID}
+      isFullscreen={false}
+      onClose={handleClose}
+      shouldNavigateBack={false}
+      style={styles.bottomSheet}
+    >
+      {renderContent()}
+    </BottomSheet>
+  );
+};

app/core/HardwareWallet/HardwareWalletProvider.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { HardwareWalletType } from '@metamask/hw-wallet-sdk';
+import renderWithProvider from '../../../../../util/test/renderWithProvider';
+import { AppThemeKey } from '../../../../../util/theme/models';
+
+import {
+  AwaitingAppContent,
+  AWAITING_APP_CONTENT_TEST_ID,
+} from './AwaitingAppContent';
+
+// Mock locales
+jest.mock('../../../../../../locales/i18n', () => ({
+  strings: (key: string, params?: Record<string, string>) => {
+    if (params) {
+      return `${key} ${JSON.stringify(params)}`;
+    }
+    return key;
+  },
+}));
+
+describe('AwaitingAppContent', () => {
+  const mockInitialState = {
+    user: {
+      appTheme: AppThemeKey.light,
+    },
+    settings: {
+      useBlockieIcon: false,
+    },
+    engine: {
+      backgroundState: {
+        PreferencesController: {},
+      },
+    },
+  };
+
+  const defaultProps = {
+    deviceType: HardwareWalletType.Ledger,
+  };
+
+  const renderComponent = (props = {}) =>
+    renderWithProvider(
+      <AwaitingAppContent {...defaultProps} {...props} />,
+      { state: mockInitialState },
+      false,
+      false,
+    );
+
+  it('renders with test ID', () => {
+    const { getByTestId } = renderComponent();
+
+    expect(getByTestId(AWAITING_APP_CONTENT_TEST_ID)).toBeOnTheScreen();
+  });
+
+  it('renders open app message', () => {
+    const { getByText } = renderComponent();
+
+    expect(getByText(/hardware_wallet\.awaiting_app\.title/)).toBeOnTheScreen();
+    expect(
+      getByText(/hardware_wallet\.awaiting_app\.message/),
+    ).toBeOnTheScreen();
+  });
+
+  it('shows current app when different from required', () => {
+    const { getByText } = renderComponent({
+      currentApp: 'Bitcoin',
+      requiredApp: 'Ethereum',
+    });
+
+    expect(
+      getByText('hardware_wallet.awaiting_app.current_app {"app":"Bitcoin"}'),
+    ).toBeOnTheScreen();
+  });
+
+  it('does not show current app when same as required', () => {
+    const { queryByText } = renderComponent({
+      currentApp: 'Ethereum',
+      requiredApp: 'Ethereum',
+    });
+
+    expect(queryByText(/current_app/)).toBeNull();
+  });
+
+  it('does not show current app for BOLOS', () => {
+    const { queryByText } = renderComponent({
+      currentApp: 'BOLOS',
+      requiredApp: 'Ethereum',
+    });
+
+    expect(queryByText(/current_app/)).toBeNull();
+  });
+
+  it('renders continue button when onContinue provided', () => {
+    const onContinue = jest.fn();
+    const { getByText } = renderComponent({ onContinue });
+
+    const continueButton = getByText('hardware_wallet.common.continue');
+    fireEvent.press(continueButton);
+    expect(onContinue).toHaveBeenCalled();
+  });
+
+  it('does not render continue button when onContinue not provided', () => {
+    const { queryByText } = renderComponent();
+
+    expect(queryByText('hardware_wallet.common.continue')).toBeNull();
+  });
+});