chore: Enhance Headers API (MetaMask#24242)

## **Description**

This PR enhances the header components API in
`component-library/components-temp` to provide more flexibility and
consistency:

1. **HeaderCenter**: Added `startButtonIconProps` support by removing
the `Omit` constraint, allowing direct control over the start button.

2. **HeaderWithTitleLeft & HeaderWithTitleLeftScrollable**: Added close
button support via `onClose` and `closeButtonProps` props, along with
`endButtonIconProps` for additional end accessories.

3. **HeaderWithTitleLeftScrollable**: Added `isInsideSafeAreaView` prop
to properly position the header when used inside a SafeAreaView,
respecting safe area insets.

4. **TitleLeft**: Added `twClassName` prop for custom Tailwind styling.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes:

## **Manual testing steps**

```gherkin
Feature: Header Components API

  Scenario: HeaderCenter with custom startButtonIconProps
    Given the app renders a HeaderCenter component
    When user provides startButtonIconProps
    Then the custom start button should render instead of the default back button

  Scenario: HeaderWithTitleLeft with close button
    Given the app renders a HeaderWithTitleLeft component
    When user provides onClose callback
    Then a close button should appear on the right side of the header

  Scenario: HeaderWithTitleLeftScrollable inside SafeAreaView
    Given the app renders HeaderWithTitleLeftScrollable inside a SafeAreaView
    When isInsideSafeAreaView is set to true
    Then the header should position at the safe area boundary instead of top-0
```

## **Screenshots/Recordings**

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

- [ ] 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]
> Introduces more flexible header controls and positioning while
aligning APIs across components.
> 
> - **Close button support**: `HeaderWithTitleLeft` and
`HeaderWithTitleLeftScrollable` accept `onClose`/`closeButtonProps`;
merged into `endButtonIconProps` alongside any provided end icons
> - **Custom start button**: `HeaderCenter` now accepts
`startButtonIconProps` (takes priority over `onBack`);
`HeaderCenterProps` now extends `HeaderBaseProps`
> - **Safe area handling**: `HeaderWithTitleLeftScrollable` adds
`isInsideSafeAreaView` to position container using `useSafeAreaInsets()`
> - **Styling**: `TitleLeft` adds `twClassName` to customize container
classes
> - Tests updated/added to cover new behaviors and prop precedence
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
65cdf6c. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: brianacnguyen

app/component-library/components-temp/HeaderCenter/HeaderCenter.test.tsx

@@ -150,6 +150,42 @@ describe('HeaderCenter', () => {
 
       expect(queryByTestId(START_ACCESSORY_TEST_ID)).not.toBeOnTheScreen();
     });
+
+    it('renders startButtonIconProps when provided', () => {
+      const onPress = jest.fn();
+      const { getByTestId } = render(
+        <HeaderCenter
+          title="Title"
+          startButtonIconProps={{
+            iconName: IconName.Menu,
+            onPress,
+            testID: 'custom-start-button',
+          }}
+        />,
+      );
+
+      expect(getByTestId('custom-start-button')).toBeOnTheScreen();
+    });
+
+    it('startButtonIconProps takes priority over onBack', () => {
+      const onBack = jest.fn();
+      const onPress = jest.fn();
+      const { getByTestId, queryByTestId } = render(
+        <HeaderCenter
+          title="Title"
+          onBack={onBack}
+          backButtonProps={{ testID: BACK_BUTTON_TEST_ID }}
+          startButtonIconProps={{
+            iconName: IconName.Menu,
+            onPress,
+            testID: 'custom-start-button',
+          }}
+        />,
+      );
+
+      expect(getByTestId('custom-start-button')).toBeOnTheScreen();
+      expect(queryByTestId(BACK_BUTTON_TEST_ID)).not.toBeOnTheScreen();
+    });
   });
 
   describe('close button', () => {

app/component-library/components-temp/HeaderCenter/HeaderCenter.tsx

@@ -43,12 +43,16 @@ const HeaderCenter: React.FC<HeaderCenterProps> = ({
   onClose,
   closeButtonProps,
   endButtonIconProps,
+  startButtonIconProps,
   twClassName,
   testID,
   ...headerBaseProps
 }) => {
   // Build the startButtonIconProps with back button if needed
   const resolvedStartButtonIconProps = useMemo(() => {
+    if (startButtonIconProps) {
+      return startButtonIconProps;
+    }
     if (onBack || backButtonProps) {
       return {
         iconName: IconName.ArrowLeft,
@@ -57,7 +61,7 @@ const HeaderCenter: React.FC<HeaderCenterProps> = ({
       } as ButtonIconProps;
     }
     return undefined;
-  }, [onBack, backButtonProps]);
+  }, [onBack, backButtonProps, startButtonIconProps]);
 
   // Build the endButtonIconProps array with close button if needed
   const resolvedEndButtonIconProps = useMemo(() => {

app/component-library/components-temp/HeaderCenter/HeaderCenter.types.ts

@@ -10,8 +10,7 @@ import { HeaderBaseProps } from '../../components/HeaderBase';
 /**
  * HeaderCenter component props.
  */
-export interface HeaderCenterProps
-  extends Omit<HeaderBaseProps, 'startButtonIconProps'> {
+export interface HeaderCenterProps extends HeaderBaseProps {
   /**
    * Title text to display in the header.
    * Used as children if children prop is not provided.

app/component-library/components-temp/HeaderWithTitleLeft/HeaderWithTitleLeft.test.tsx

@@ -10,6 +10,7 @@ const TEST_IDS = {
   CONTAINER: 'header-with-title-left-container',
   TITLE_SECTION: 'header-with-title-left-title-section',
   BACK_BUTTON: 'header-with-title-left-back-button',
+  CLOSE_BUTTON: 'header-with-title-left-close-button',
   TITLE_LEFT: 'title-left',
   HEADER_BASE_END_ACCESSORY: 'header-base-end-accessory',
 };
@@ -169,6 +170,88 @@ describe('HeaderWithTitleLeft', () => {
     });
   });
 
+  describe('close button', () => {
+    it('renders close button when onClose provided', () => {
+      const { getByTestId } = render(
+        <HeaderWithTitleLeft
+          onClose={jest.fn()}
+          closeButtonProps={{ testID: TEST_IDS.CLOSE_BUTTON }}
+          titleLeftProps={{ title: 'Test' }}
+        />,
+      );
+
+      expect(getByTestId(TEST_IDS.CLOSE_BUTTON)).toBeOnTheScreen();
+    });
+
+    it('renders close button when closeButtonProps provided', () => {
+      const { getByTestId } = render(
+        <HeaderWithTitleLeft
+          closeButtonProps={{
+            onPress: jest.fn(),
+            testID: TEST_IDS.CLOSE_BUTTON,
+          }}
+          titleLeftProps={{ title: 'Test' }}
+        />,
+      );
+
+      expect(getByTestId(TEST_IDS.CLOSE_BUTTON)).toBeOnTheScreen();
+    });
+
+    it('calls onClose when close button pressed', () => {
+      const onClose = jest.fn();
+      const { getByTestId } = render(
+        <HeaderWithTitleLeft
+          onClose={onClose}
+          closeButtonProps={{ testID: TEST_IDS.CLOSE_BUTTON }}
+          titleLeftProps={{ title: 'Test' }}
+        />,
+      );
+
+      fireEvent.press(getByTestId(TEST_IDS.CLOSE_BUTTON));
+
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+
+    it('calls closeButtonProps.onPress when close button pressed', () => {
+      const onPress = jest.fn();
+      const { getByTestId } = render(
+        <HeaderWithTitleLeft
+          closeButtonProps={{ onPress, testID: TEST_IDS.CLOSE_BUTTON }}
+          titleLeftProps={{ title: 'Test' }}
+        />,
+      );
+
+      fireEvent.press(getByTestId(TEST_IDS.CLOSE_BUTTON));
+
+      expect(onPress).toHaveBeenCalledTimes(1);
+    });
+
+    it('closeButtonProps.onPress takes priority over onClose', () => {
+      const onClose = jest.fn();
+      const onPress = jest.fn();
+      const { getByTestId } = render(
+        <HeaderWithTitleLeft
+          onClose={onClose}
+          closeButtonProps={{ onPress, testID: TEST_IDS.CLOSE_BUTTON }}
+          titleLeftProps={{ title: 'Test' }}
+        />,
+      );
+
+      fireEvent.press(getByTestId(TEST_IDS.CLOSE_BUTTON));
+
+      expect(onPress).toHaveBeenCalledTimes(1);
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it('does not render close button when neither onClose nor closeButtonProps provided', () => {
+      const { queryByLabelText } = render(
+        <HeaderWithTitleLeft titleLeftProps={{ title: 'Test' }} />,
+      );
+
+      expect(queryByLabelText('Close')).toBeNull();
+    });
+  });
+
   describe('props forwarding', () => {
     it('forwards endButtonIconProps to HeaderBase', () => {
       const { getByTestId } = render(

app/component-library/components-temp/HeaderWithTitleLeft/HeaderWithTitleLeft.tsx

@@ -32,9 +32,12 @@ import { HeaderWithTitleLeftProps } from './HeaderWithTitleLeft.types';
 const HeaderWithTitleLeft: React.FC<HeaderWithTitleLeftProps> = ({
   onBack,
   backButtonProps,
+  onClose,
+  closeButtonProps,
   titleLeft,
   titleLeftProps,
   startButtonIconProps,
+  endButtonIconProps,
   twClassName,
   testID,
   titleSectionTestID,
@@ -59,6 +62,26 @@ const HeaderWithTitleLeft: React.FC<HeaderWithTitleLeftProps> = ({
     return undefined;
   }, [startButtonIconProps, onBack, backButtonProps]);
 
+  // Build endButtonIconProps with close button if onClose or closeButtonProps is provided
+  const resolvedEndButtonIconProps = useMemo(() => {
+    const props: ButtonIconProps[] = [];
+
+    if (onClose || closeButtonProps) {
+      const closeProps: ButtonIconProps = {
+        iconName: IconName.Close,
+        ...(closeButtonProps || {}),
+        onPress: closeButtonProps?.onPress ?? onClose,
+      };
+      props.push(closeProps);
+    }
+
+    if (endButtonIconProps) {
+      props.push(...endButtonIconProps);
+    }
+
+    return props.length > 0 ? props : undefined;
+  }, [endButtonIconProps, onClose, closeButtonProps]);
+
   // Render title section content
   const renderTitleSection = () => {
     if (titleLeft) {
@@ -79,6 +102,7 @@ const HeaderWithTitleLeft: React.FC<HeaderWithTitleLeftProps> = ({
       {/* HeaderBase section */}
       <HeaderBase
         startButtonIconProps={resolvedStartButtonIconProps}
+        endButtonIconProps={resolvedEndButtonIconProps}
         twClassName={resolvedTwClassName}
         {...headerBaseProps}
       />

app/component-library/components-temp/HeaderWithTitleLeft/HeaderWithTitleLeft.types.ts

@@ -23,6 +23,16 @@ export interface HeaderWithTitleLeftProps
    * If provided, a back button will be rendered with these props spread.
    */
   backButtonProps?: Omit<ButtonIconProps, 'iconName'>;
+  /**
+   * Callback when the close button is pressed.
+   * If provided, a close button will be added to endButtonIconProps.
+   */
+  onClose?: () => void;
+  /**
+   * Additional props to pass to the close ButtonIcon.
+   * If provided, a close button will be added to endButtonIconProps with these props spread.
+   */
+  closeButtonProps?: Omit<ButtonIconProps, 'iconName'>;
   /**
    * Custom node to render in the title section.
    * If provided, takes priority over titleLeftProps.

app/component-library/components-temp/HeaderWithTitleLeftScrollable/HeaderWithTitleLeftScrollable.test.tsx

@@ -4,6 +4,9 @@ import { render, renderHook } from '@testing-library/react-native';
 import { useSharedValue, SharedValue } from 'react-native-reanimated';
 import { Text } from 'react-native';
 
+// External dependencies.
+import { IconName } from '@metamask/design-system-react-native';
+
 // Internal dependencies.
 import HeaderWithTitleLeftScrollable from './HeaderWithTitleLeftScrollable';
 import useHeaderWithTitleLeftScrollable from './useHeaderWithTitleLeftScrollable';
@@ -22,6 +25,11 @@ jest.mock('react-native-reanimated', () => {
   return Reanimated;
 });
 
+// Mock react-native-safe-area-context
+jest.mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: () => ({ top: 44, bottom: 34, left: 0, right: 0 }),
+}));
+
 // Test wrapper component that provides scrollY
 const TestWrapper: React.FC<{
   children: (scrollYValue: SharedValue<number>) => React.ReactNode;
@@ -106,6 +114,114 @@ describe('HeaderWithTitleLeftScrollable', () => {
     });
   });
 
+  describe('close button', () => {
+    it('renders close button when onClose provided', () => {
+      const { getByTestId } = render(
+        <TestWrapper>
+          {(scrollYValue) => (
+            <HeaderWithTitleLeftScrollable
+              title="Test"
+              scrollY={scrollYValue}
+              onClose={jest.fn()}
+              closeButtonProps={{ testID: 'test-close-button' }}
+            />
+          )}
+        </TestWrapper>,
+      );
+
+      expect(getByTestId('test-close-button')).toBeOnTheScreen();
+    });
+
+    it('renders close button when closeButtonProps provided', () => {
+      const { getByTestId } = render(
+        <TestWrapper>
+          {(scrollYValue) => (
+            <HeaderWithTitleLeftScrollable
+              title="Test"
+              scrollY={scrollYValue}
+              closeButtonProps={{
+                onPress: jest.fn(),
+                testID: 'test-close-button',
+              }}
+            />
+          )}
+        </TestWrapper>,
+      );
+
+      expect(getByTestId('test-close-button')).toBeOnTheScreen();
+    });
+  });
+
+  describe('endButtonIconProps', () => {
+    it('renders endButtonIconProps', () => {
+      const { getByTestId } = render(
+        <TestWrapper>
+          {(scrollYValue) => (
+            <HeaderWithTitleLeftScrollable
+              title="Test"
+              scrollY={scrollYValue}
+              endButtonIconProps={[
+                {
+                  iconName: IconName.Close,
+                  onPress: jest.fn(),
+                  testID: 'end-button',
+                },
+              ]}
+            />
+          )}
+        </TestWrapper>,
+      );
+
+      expect(getByTestId('end-button')).toBeOnTheScreen();
+    });
+  });
+
+  describe('isInsideSafeAreaView', () => {
+    it('positions header at top 0 when isInsideSafeAreaView is false', () => {
+      const { getByTestId } = render(
+        <TestWrapper>
+          {(scrollYValue) => (
+            <HeaderWithTitleLeftScrollable
+              title="Test"
+              scrollY={scrollYValue}
+              isInsideSafeAreaView={false}
+              testID="test-container"
+            />
+          )}
+        </TestWrapper>,
+      );
+
+      const container = getByTestId('test-container');
+      const flattenedStyle = Array.isArray(container.props.style)
+        ? Object.assign({}, ...container.props.style)
+        : container.props.style;
+
+      expect(flattenedStyle.top).toBe(0);
+    });
+
+    it('positions header at insets.top when isInsideSafeAreaView is true', () => {
+      const { getByTestId } = render(
+        <TestWrapper>
+          {(scrollYValue) => (
+            <HeaderWithTitleLeftScrollable
+              title="Test"
+              scrollY={scrollYValue}
+              isInsideSafeAreaView
+              testID="test-container"
+            />
+          )}
+        </TestWrapper>,
+      );
+
+      const container = getByTestId('test-container');
+      const flattenedStyle = Array.isArray(container.props.style)
+        ? Object.assign({}, ...container.props.style)
+        : container.props.style;
+
+      expect(flattenedStyle.top).toBe(44);
+    });
+  });
+
   describe('titleLeft and titleLeftProps', () => {
     it('renders custom titleLeft node', () => {
       const { getByText } = render(