fix: Scope landscape mode to perps chart cp-7.61.0 (#23947)

## **Description**

This PR introduces a service to manage the horizontal orientation of the
mobile application programatically instead of being global.

## **Changelog**

CHANGELOG entry: horizontal orientation service

## **Related issues**

Fixes: #23903

## **Manual testing steps**

```gherkin
Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]
```

## **Screenshots/Recordings**

Uploading Screen Recording 2025-12-11 at 2.46.30 PM.mov…

## **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]
> Centralizes orientation control, locking app to portrait and enabling
landscape solely for the perps fullscreen chart, with updated modal
logic and tests.
> 
> - **Core**:
> - **ScreenOrientation**: Add `ScreenOrientationService`
(`lockToPortrait`, `allowLandscape`, `isLockedToPortrait`) with exports
and constants; introduce `useScreenOrientation` hook.
> - **App Init**: Lock orientation to portrait on startup in
`components/Views/Root/index.tsx`.
> - **Perps**:
> - **Fullscreen Modal**: Refactor `PerpsChartFullscreenModal` to use
`useScreenOrientation({ allowLandscape: isVisible })`; simplify
close/error handlers (orientation handled by hook).
> - **Tests**:
> - Add unit tests for `ScreenOrientationService` and
`useScreenOrientation`.
> - Update modal tests to reflect hook-managed orientation and ensure
`onClose` behavior; mock `Logger`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
5b75bee. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: gambinish

app/components/UI/Perps/components/PerpsChartFullscreenModal/PerpsChartFullscreenModal.test.tsx

@@ -16,6 +16,7 @@ import {
 } from '../../../../../../e2e/selectors/Perps/Perps.selectors';
 
 jest.mock('expo-screen-orientation');
+jest.mock('../../../../../util/Logger');
 
 const mockLockAsync = lockAsync as jest.MockedFunction<typeof lockAsync>;
 const mockUnlockAsync = unlockAsync as jest.MockedFunction<typeof unlockAsync>;
@@ -254,7 +255,7 @@ describe('PerpsChartFullscreenModal', () => {
       });
     });
 
-    it('locks orientation when close button is pressed', async () => {
+    it('calls onClose when close button is pressed (orientation locked via visibility change)', async () => {
       const { getByTestId } = render(
         <PerpsChartFullscreenModal {...defaultProps} isVisible />,
       );
@@ -265,8 +266,10 @@ describe('PerpsChartFullscreenModal', () => {
         );
       });
 
+      // onClose is called, which triggers isVisible to become false,
+      // which causes the hook to lock orientation
       await waitFor(() => {
-        expect(mockLockAsync).toHaveBeenCalledWith(OrientationLock.PORTRAIT_UP);
+        expect(mockOnClose).toHaveBeenCalled();
       });
     });
 
@@ -275,6 +278,11 @@ describe('PerpsChartFullscreenModal', () => {
         <PerpsChartFullscreenModal {...defaultProps} isVisible />,
       );
 
+      // Wait for the initial effect to complete before unmounting
+      await waitFor(() => {
+        expect(mockUnlockAsync).toHaveBeenCalled();
+      });
+
       unmount();
 
       await waitFor(() => {
@@ -369,7 +377,7 @@ describe('PerpsChartFullscreenModal', () => {
       });
     });
 
-    it('locks orientation before calling onClose', async () => {
+    it('calls onClose immediately when pressed (orientation managed by hook)', async () => {
       const { getByTestId } = render(
         <PerpsChartFullscreenModal {...defaultProps} isVisible />,
       );
@@ -380,8 +388,9 @@ describe('PerpsChartFullscreenModal', () => {
         );
       });
 
+      // onClose is called immediately; orientation locking happens
+      // via the useScreenOrientation hook when isVisible changes
       await waitFor(() => {
-        expect(mockLockAsync).toHaveBeenCalledWith(OrientationLock.PORTRAIT_UP);
         expect(mockOnClose).toHaveBeenCalled();
       });
     });
@@ -458,40 +467,11 @@ describe('PerpsChartFullscreenModal', () => {
         mockOnError();
       });
 
+      // onClose is called on error; orientation is restored via hook when isVisible changes
       await waitFor(() => {
-        expect(mockLockAsync).toHaveBeenCalledWith(OrientationLock.PORTRAIT_UP);
         expect(mockOnClose).toHaveBeenCalled();
       });
     });
-
-    it('restores orientation lock when chart error occurs', async () => {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
-      const ComponentErrorBoundary = require('../../../ComponentErrorBoundary');
-      const mockOnError = jest.fn();
-
-      ComponentErrorBoundary.mockImplementationOnce(
-        ({
-          onError,
-          children,
-        }: {
-          onError: () => void;
-          children: React.ReactNode;
-        }) => {
-          mockOnError.mockImplementation(onError);
-          return children;
-        },
-      );
-
-      render(<PerpsChartFullscreenModal {...defaultProps} isVisible />);
-
-      await act(async () => {
-        mockOnError();
-      });
-
-      await waitFor(() => {
-        expect(mockLockAsync).toHaveBeenCalledWith(OrientationLock.PORTRAIT_UP);
-      });
-    });
   });
 
   describe('Edge Cases', () => {

app/components/UI/Perps/components/PerpsChartFullscreenModal/PerpsChartFullscreenModal.tsx

@@ -2,11 +2,6 @@ import React, { useCallback, useEffect, useState, useRef } from 'react';
 import { View, Dimensions } from 'react-native';
 import Modal from 'react-native-modal';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import {
-  lockAsync,
-  unlockAsync,
-  OrientationLock,
-} from 'expo-screen-orientation';
 import { useStyles } from '../../../../../component-library/hooks';
 import ButtonIcon, {
   ButtonIconSizes,
@@ -26,6 +21,7 @@ import PerpsCandlestickChartIntervalSelector from '../PerpsCandlestickChartInter
 import { styleSheet } from './PerpsChartFullscreenModal.styles';
 import PerpsOHLCVBar from '../PerpsOHLCVBar';
 import ComponentErrorBoundary from '../../../ComponentErrorBoundary';
+import { useScreenOrientation } from '../../../../../core/ScreenOrientation';
 
 export interface PerpsChartFullscreenModalProps {
   isVisible: boolean;
@@ -60,34 +56,9 @@ const PerpsChartFullscreenModal: React.FC<PerpsChartFullscreenModalProps> = ({
   // Track OHLCV bar height to subtract from chart height
   const [ohlcvHeight, setOhlcvHeight] = useState<number>(0);
 
-  // Auto-follow device orientation when modal is open
-  useEffect(() => {
-    const handleOrientationChange = async () => {
-      try {
-        if (isVisible) {
-          // Unlock orientation to follow device
-          await unlockAsync();
-        } else {
-          // Lock back to portrait when closing
-          await lockAsync(OrientationLock.PORTRAIT_UP);
-        }
-      } catch (error) {
-        // Silent error handling - orientation lock failures are non-critical
-      }
-    };
-
-    handleOrientationChange();
-
-    // Cleanup only if component unmounts while modal is visible
-    // No need to lock again on visibility change as it's handled above
-    return () => {
-      if (isVisible) {
-        lockAsync(OrientationLock.PORTRAIT_UP).catch(() => {
-          // Silent error handling
-        });
-      }
-    };
-  }, [isVisible]);
+  // Allow landscape orientation when modal is visible
+  // Automatically locks back to portrait when modal closes or unmounts
+  useScreenOrientation({ allowLandscape: isVisible });
 
   // Reset OHLCV height when OHLCV bar disappears
   useEffect(() => {
@@ -116,29 +87,16 @@ const PerpsChartFullscreenModal: React.FC<PerpsChartFullscreenModalProps> = ({
     }
   }, [candleData, selectedInterval, visibleCandleCount]);
 
-  const handleClose = useCallback(async () => {
-    try {
-      // Lock orientation back to portrait before closing
-      await lockAsync(OrientationLock.PORTRAIT_UP);
-    } catch (error) {
-      // Silent error handling - orientation lock failures are non-critical
-    } finally {
-      // Always call onClose even if orientation lock fails
-      onClose();
-    }
+  // Close handler - orientation is automatically restored by the hook
+  // when isVisible becomes false
+  const handleClose = useCallback(() => {
+    onClose();
   }, [onClose]);
 
-  // Handle chart errors by restoring orientation and closing modal
-  const handleChartError = useCallback(async () => {
-    try {
-      // Restore orientation lock on error to prevent getting stuck
-      await lockAsync(OrientationLock.PORTRAIT_UP);
-    } catch (error) {
-      // Silent error handling - orientation lock failures are non-critical
-    } finally {
-      // Close modal even if orientation lock fails
-      onClose();
-    }
+  // Handle chart errors by closing modal
+  // Orientation is automatically restored by the hook
+  const handleChartError = useCallback(() => {
+    onClose();
   }, [onClose]);
 
   return (

app/components/Views/Root/index.tsx

@@ -15,6 +15,7 @@ import NavigationProvider from '../../Nav/NavigationProvider';
 import ControllersGate from '../../Nav/ControllersGate';
 import { isTest } from '../../../util/test/utils';
 import { FeatureFlagOverrideProvider } from '../../../contexts/FeatureFlagOverrideContext';
+import { ScreenOrientationService } from '../../../core/ScreenOrientation';
 ///: BEGIN:ONLY_INCLUDE_IF(preinstalled-snaps,external-snaps)
 import { SnapsExecutionWebView } from '../../../lib/snaps';
 ///: END:ONLY_INCLUDE_IF
@@ -50,6 +51,8 @@ const Root = ({ foxCode }: RootProps) => {
     SecureKeychain.init(foxCode);
     // Init EntryScriptWeb3 asynchronously on the background
     EntryScriptWeb3.init();
+    // Lock screen orientation to portrait on app start
+    ScreenOrientationService.lockToPortrait();
     // Wait for store to be initialized in Detox tests
     if (isTest) {
       waitForStore();

app/core/ScreenOrientation/ScreenOrientationService.test.ts

@@ -0,0 +1,87 @@
+import { ScreenOrientationService } from './ScreenOrientationService';
+import {
+  lockAsync,
+  unlockAsync,
+  OrientationLock,
+} from 'expo-screen-orientation';
+
+jest.mock('expo-screen-orientation');
+jest.mock('../../util/Logger');
+
+const mockLockAsync = lockAsync as jest.MockedFunction<typeof lockAsync>;
+const mockUnlockAsync = unlockAsync as jest.MockedFunction<typeof unlockAsync>;
+
+describe('ScreenOrientationService', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockLockAsync.mockResolvedValue(undefined);
+    mockUnlockAsync.mockResolvedValue(undefined);
+  });
+
+  describe('lockToPortrait', () => {
+    it('calls lockAsync with PORTRAIT_UP', async () => {
+      await ScreenOrientationService.lockToPortrait();
+
+      expect(mockLockAsync).toHaveBeenCalledWith(OrientationLock.PORTRAIT_UP);
+    });
+
+    it('sets isLocked to true after successful lock', async () => {
+      await ScreenOrientationService.lockToPortrait();
+
+      expect(ScreenOrientationService.isLockedToPortrait()).toBe(true);
+    });
+
+    it('handles lock errors gracefully', async () => {
+      mockLockAsync.mockRejectedValueOnce(new Error('Lock failed'));
+
+      await expect(
+        ScreenOrientationService.lockToPortrait(),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('allowLandscape', () => {
+    it('calls unlockAsync', async () => {
+      await ScreenOrientationService.allowLandscape();
+
+      expect(mockUnlockAsync).toHaveBeenCalled();
+    });
+
+    it('sets isLocked to false after successful unlock', async () => {
+      await ScreenOrientationService.lockToPortrait();
+      await ScreenOrientationService.allowLandscape();
+
+      expect(ScreenOrientationService.isLockedToPortrait()).toBe(false);
+    });
+
+    it('handles unlock errors gracefully', async () => {
+      mockUnlockAsync.mockRejectedValueOnce(new Error('Unlock failed'));
+
+      await expect(
+        ScreenOrientationService.allowLandscape(),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('isLockedToPortrait', () => {
+    it('returns false initially', async () => {
+      // Reset state by allowing landscape first
+      await ScreenOrientationService.allowLandscape();
+
+      expect(ScreenOrientationService.isLockedToPortrait()).toBe(false);
+    });
+
+    it('returns true after locking to portrait', async () => {
+      await ScreenOrientationService.lockToPortrait();
+
+      expect(ScreenOrientationService.isLockedToPortrait()).toBe(true);
+    });
+
+    it('returns false after allowing landscape', async () => {
+      await ScreenOrientationService.lockToPortrait();
+      await ScreenOrientationService.allowLandscape();
+
+      expect(ScreenOrientationService.isLockedToPortrait()).toBe(false);
+    });
+  });
+});

app/core/ScreenOrientation/ScreenOrientationService.ts

@@ -0,0 +1,63 @@
+import {
+  lockAsync,
+  unlockAsync,
+  OrientationLock,
+} from 'expo-screen-orientation';
+import Logger from '../../util/Logger';
+
+/**
+ * ScreenOrientationService provides centralized control over screen orientation.
+ *
+ * By default, the app is locked to portrait mode. Specific screens can opt-in
+ * to allow landscape orientation using the provided methods.
+ *
+ * @example
+ * // Lock app to portrait on startup
+ * await ScreenOrientationService.lockToPortrait();
+ *
+ * // Allow landscape for a specific screen
+ * await ScreenOrientationService.allowLandscape();
+ *
+ * // Lock back to portrait when leaving the screen
+ * await ScreenOrientationService.lockToPortrait();
+ */
+export class ScreenOrientationService {
+  private static isLocked = false;
+
+  /**
+   * Locks the screen orientation to portrait mode.
+   * This should be called on app startup and when leaving screens that allow landscape.
+   */
+  static async lockToPortrait(): Promise<void> {
+    try {
+      await lockAsync(OrientationLock.PORTRAIT_UP);
+      this.isLocked = true;
+    } catch (error) {
+      // Silent error handling - orientation lock failures are non-critical
+      Logger.log('ScreenOrientationService: Failed to lock to portrait', error);
+    }
+  }
+
+  /**
+   * Unlocks the screen orientation to allow landscape mode.
+   * The device orientation will follow the physical device position.
+   */
+  static async allowLandscape(): Promise<void> {
+    try {
+      await unlockAsync();
+      this.isLocked = false;
+    } catch (error) {
+      // Silent error handling - orientation unlock failures are non-critical
+      Logger.log('ScreenOrientationService: Failed to allow landscape', error);
+    }
+  }
+
+  /**
+   * Returns whether the orientation is currently locked to portrait.
+   */
+  static isLockedToPortrait(): boolean {
+    return this.isLocked;
+  }
+}
+
+export default ScreenOrientationService;

app/core/ScreenOrientation/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Screen identifiers that are allowed to display in landscape orientation.
+ * Add screen identifiers here to enable landscape support for specific screens.
+ */
+export const LANDSCAPE_ALLOWED_SCREENS = {
+  PERPS_CHART_FULLSCREEN: 'PerpsChartFullscreenModal',
+} as const;
+
+export type LandscapeAllowedScreen =
+  (typeof LANDSCAPE_ALLOWED_SCREENS)[keyof typeof LANDSCAPE_ALLOWED_SCREENS];

app/core/ScreenOrientation/index.ts

@@ -0,0 +1,6 @@
+export { ScreenOrientationService } from './ScreenOrientationService';
+export {
+  LANDSCAPE_ALLOWED_SCREENS,
+  type LandscapeAllowedScreen,
+} from './constants';
+export { useScreenOrientation } from './useScreenOrientation';