Bug Report: HeaderMotion.FlatList scroll offset not applied when using inline header (without NavigationBridge)

[centricity-kashifshaikh]

Library version

react-native-header-motion v1.x

Description

The docs state that when the header lives inside the HeaderMotion subtree (not rendered by navigation), bridging is unnecessary and the header can be placed inline:

"If your header lives inside the HeaderMotion subtree — meaning it's rendered directly as a child rather than by navigation — bridging is unnecessary. Just place the header component inline."

However, when HeaderMotion.FlatList is nested inside PagerView (as required for the multi-tab pattern), the automatic paddingTop offset that should push list content below the header is not applied. The list scrolls underneath the header.

Steps to Reproduce

Take the official flatlist-pager.tsx example and remove the Stack.Screen / Bridge / NavigationBridge wiring, placing the header inline instead(also set header shown: false in layout):

<HeaderMotion activeScrollId={activeScrollId.sv}>
  {/* Inline header — no Bridge/NavigationBridge */}
  <CollapsibleHeader
    activeTab={activeScrollId.state}
    onTabChange={handleTabPress}
  />

  <PagerView
    ref={pagerRef}
    style={{ flex: 1 }}
    initialPage={0}
    onPageSelected={onPageSelected}
  >
    <View key="A" style={{ flex: 1 }}>
      <HeaderMotion.FlatList
        scrollId="A"
        data={content}
        keyExtractor={(item) => `${item.index}`}
        renderItem={({ item }) => <ContentCard {...item} />}
      />
    </View>
    <View key="B" style={{ flex: 1 }}>
      <HeaderMotion.FlatList
        scrollId="B"
        data={content}
        keyExtractor={(item) => `${item.index}`}
        renderItem={({ item }) => <ContentCard {...item} />}
      />
    </View>
  </PagerView>
</HeaderMotion>

CollapsibleHeader is unchanged from the example — it renders HeaderMotion.Header internally.

Expected Behaviour

HeaderMotion.FlatList receives a paddingTop offset equal to the measured header height, so list content starts below the header.

Actual Behaviour

List content starts at y=0 and scrolls behind the absolutely-positioned header. This happens even with flex: 1 on both the PagerView and each page's View wrapper.

What Works

The identical setup works correctly when the header is bridged via Stack.Screen + NavigationBridge (as in the official flatlist-pager.tsx example). The issue is specific to the inline usage pattern when PagerView is the scrollable's parent.

Environment

react-native-header-motion	v1.x
react-native	0.83.2
react-native-reanimated	3.x
react-native-pager-view	latest
Platform	iOS (tested on iPhone 17 Pro Simulator)

[centricity-kashifshaikh]

@pawicao

I verified this fix locally across inline-header scenarios (without NavigationBridge), including FlatList and ScrollView flows.

The root cause was header stacking order: the absolute inline header could render behind scrollable content. This PR adds explicit overlay z-order (zIndex: 10) in HeaderMotion.Header and updates tests.

After this change, the header consistently stays above scrollables and the overlap issue is resolved on my end.

PR -> #23