feat: add SurfaceComponent prop to header (#10)

Author: e-younan

docs/docs/03-api-reference/components/04-header.mdx

@@ -5,8 +5,8 @@ slug: /components/header
 description: A header navigation component exported from React Native Header.
 ---
 
-Headers are navigation components that display information and actions relating to the current 
-screen. This component is exported in this library and works well with the other scroll 
+Headers are navigation components that display information and actions relating to the current
+screen. This component is exported in this library and works well with the other scroll
 containers this library provides.
 
 ## Props
@@ -61,8 +61,8 @@ An optional boolean to indicate whether the header's center container should fad
 ### ignoreTopSafeArea
 
 An optional boolean to indicate whether the header should ignore the top safe area. This is useful
-when you want to display the header behind the status bar. Defaults to `false`. If you are 
-rendering this header in an iOS [modal](https://reactnavigation.org/docs/native-stack-navigator/#presentation), 
+when you want to display the header behind the status bar. Defaults to `false`. If you are
+rendering this header in an iOS [modal](https://reactnavigation.org/docs/native-stack-navigator/#presentation),
 you should set this to `true`.
 
 ### noBottomBorder
@@ -76,4 +76,39 @@ An optional color to use for the header's bottom border. Defaults to `#E5E5E5`.
 
 ### borderWidth
 
-An optional width to use for the header's bottom border. Defaults to [StyleSheet.hairlineWidth](https://reactnative.dev/docs/stylesheet#hairlinewidth).
+An optional width to use for the header's bottom border. Defaults to [StyleSheet.hairlineWidth](https://reactnative.dev/docs/stylesheet#hairlinewidth).
+
+### SurfaceComponent
+
+An optional component that can act as the surface of the header. Please ensure that the styling applied to the component includes `StyleSheet.absoluteFill` or `StyleSheet.absoluteFillObject` to ensure that the surface component fills the header.
+
+#### Example
+
+The following example will make the header have a **cyan** background when the user scrolls the scroll container up:
+
+```jsx
+const SURFACE_BG_COLOR = 'cyan';
+
+const HeaderSurface: React.FC<SurfaceComponentProps> = ({ showNavBar }) => (
+  <FadingView
+    opacity={showNavBar}
+    // StyleSheet.absoluteFill is needed to ensure that the component fills up the header.
+    style={[StyleSheet.absoluteFill, { backgroundColor: SURFACE_BG_COLOR }]}
+  />
+);
+
+const HeaderComponent: React.FC<ScrollHeaderProps> = ({ showNavBar }) => {
+  const navigation = useNavigation();
+  const onPressProfile = () => navigation.navigate('Profile');
+
+  return (
+    <Header
+      showNavBar={showNavBar}
+      // ...
+      SurfaceComponent={HeaderSurface} // <- usage
+    />
+  );
+};
+```
+
+See the example application's _Header SurfaceComponent Interpolation_ screen in for a working example.

example/ios/Podfile.lock

@@ -720,4 +720,4 @@ SPEC CHECKSUMS:
 
 PODFILE CHECKSUM: 675d5c47e1336b7b792d33fad9d8fbf19b97d359
 
-COCOAPODS: 1.11.3
+COCOAPODS: 1.12.1

example/src/navigation/AppNavigation.tsx

@@ -7,6 +7,7 @@ import {
   ProfileScreen,
   SectionListUsageScreen,
   SimpleUsageScreen,
+  SurfaceComponentUsageScreen,
   TwitterProfileScreen,
 } from '../screens';
 
@@ -23,6 +24,10 @@ export default () => (
     <Stack.Screen name="SimpleUsageScreen" component={SimpleUsageScreen} />
     <Stack.Screen name="FlatListUsageScreen" component={FlatListUsageScreen} />
     <Stack.Screen name="SectionListUsageScreen" component={SectionListUsageScreen} />
+    <Stack.Screen
+      name="HeaderSurfaceComponentUsageScreen"
+      component={SurfaceComponentUsageScreen}
+    />
     <Stack.Screen name="TwitterProfileScreen" component={TwitterProfileScreen} />
   </Stack.Navigator>
 );

example/src/navigation/types.ts

@@ -8,6 +8,7 @@ export type RootStackParamList = {
   FlatListUsageScreen: undefined;
   SectionListUsageScreen: undefined;
   TwitterProfileScreen: undefined;
+  HeaderSurfaceComponentUsageScreen: undefined;
 };
 
 // Overrides the typing for useNavigation in @react-navigation/native to support the internal
@@ -37,6 +38,11 @@ export type SectionListUsageScreenNavigationProps = NativeStackScreenProps<
   'SectionListUsageScreen'
 >;
 
+export type SurfaceComponentUsageScreenNavigationProps = NativeStackScreenProps<
+  RootStackParamList,
+  'HeaderSurfaceComponentUsageScreen'
+>;
+
 export type TwitterProfileScreenNavigationProps = NativeStackScreenProps<
   RootStackParamList,
   'TwitterProfileScreen'

example/src/screens/Home.tsx

@@ -33,6 +33,12 @@ const SCREEN_LIST_CONFIG: ScreenConfigItem[] = [
     route: 'SectionListUsageScreen',
     description: "A simple example of the library's SectionList.",
   },
+  {
+    name: 'Header SurfaceComponent Interpolation',
+    route: 'HeaderSurfaceComponentUsageScreen',
+    description:
+      'A simple example of the library using the SurfaceComponent prop for its header to animate the background color of the header.',
+  },
   {
     name: 'Twitter Profile',
     route: 'TwitterProfileScreen',

example/src/screens/index.ts

@@ -5,4 +5,5 @@ export { default as ProfileScreen } from './Profile';
 export { default as SimpleUsageScreen } from './usage/Simple';
 export { default as FlatListUsageScreen } from './usage/FlatList';
 export { default as SectionListUsageScreen } from './usage/SectionList';
+export { default as SurfaceComponentUsageScreen } from './usage/SurfaceComponent';
 export { default as TwitterProfileScreen } from './usage/TwitterProfile';

example/src/screens/usage/SurfaceComponent.tsx

@@ -0,0 +1,107 @@
+import React, { useMemo, useState } from 'react';
+import { RefreshControl, StyleSheet, Text, TouchableOpacity, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useNavigation } from '@react-navigation/native';
+import {
+  FadingView,
+  Header,
+  LargeHeader,
+  ScrollViewWithHeaders,
+} from '@codeherence/react-native-header';
+import type {
+  ScrollHeaderProps,
+  ScrollLargeHeaderProps,
+  SurfaceComponentProps,
+} from '@codeherence/react-native-header';
+import { range } from '../../utils';
+import { Avatar, BackButton } from '../../components';
+import { RANDOM_IMAGE_NUM } from '../../constants';
+import type { SurfaceComponentUsageScreenNavigationProps } from '../../navigation';
+
+const SURFACE_BG_COLOR = 'cyan';
+
+const HeaderSurface: React.FC<SurfaceComponentProps> = ({ showNavBar }) => (
+  <FadingView
+    opacity={showNavBar}
+    style={[StyleSheet.absoluteFill, { backgroundColor: SURFACE_BG_COLOR }]}
+  />
+);
+
+const HeaderComponent: React.FC<ScrollHeaderProps> = ({ showNavBar }) => {
+  const navigation = useNavigation();
+  const onPressProfile = () => navigation.navigate('Profile');
+
+  return (
+    <Header
+      showNavBar={showNavBar}
+      headerCenterFadesIn={false}
+      headerCenter={
+        <Text style={styles.navBarTitle} numberOfLines={1}>
+          Header
+        </Text>
+      }
+      headerRight={
+        <TouchableOpacity onPress={onPressProfile}>
+          <Avatar size="sm" source={{ uri: `https://i.pravatar.cc/128?img=${RANDOM_IMAGE_NUM}` }} />
+        </TouchableOpacity>
+      }
+      headerRightFadesIn
+      headerLeft={<BackButton />}
+      SurfaceComponent={HeaderSurface}
+    />
+  );
+};
+
+const LargeHeaderComponent: React.FC<ScrollLargeHeaderProps> = () => {
+  const navigation = useNavigation();
+  const onPressProfile = () => navigation.navigate('Profile');
+
+  return (
+    <LargeHeader headerStyle={styles.largeHeaderStyle}>
+      <TouchableOpacity onPress={onPressProfile}>
+        <Avatar size="sm" source={{ uri: `https://i.pravatar.cc/128?img=${RANDOM_IMAGE_NUM}` }} />
+      </TouchableOpacity>
+    </LargeHeader>
+  );
+};
+
+const SurfaceComponentUsage: React.FC<SurfaceComponentUsageScreenNavigationProps> = () => {
+  const { bottom } = useSafeAreaInsets();
+  const [refreshing, setRefreshing] = useState(false);
+
+  const data = useMemo(() => range({ end: 100 }), []);
+
+  const onRefresh = async () => {
+    if (refreshing) return;
+
+    setRefreshing(true);
+    // Mimic some asynchronous task
+    await new Promise((res) => setTimeout(res, 2500));
+    setRefreshing(false);
+  };
+
+  return (
+    <ScrollViewWithHeaders
+      HeaderComponent={HeaderComponent}
+      LargeHeaderComponent={LargeHeaderComponent}
+      contentContainerStyle={{ paddingBottom: bottom }}
+      refreshControl={
+        <RefreshControl refreshing={refreshing} colors={['#8E8E93']} onRefresh={onRefresh} />
+      }
+    >
+      <View style={styles.children}>
+        {data.map((i) => (
+          <Text key={`text-${i}`}>Scroll to see header animation</Text>
+        ))}
+      </View>
+    </ScrollViewWithHeaders>
+  );
+};
+
+export default SurfaceComponentUsage;
+
+const styles = StyleSheet.create({
+  children: { marginTop: 16, paddingHorizontal: 16 },
+  navBarTitle: { fontSize: 16, fontWeight: 'bold' },
+  largeHeaderStyle: { flexDirection: 'row-reverse' },
+});

src/components/containers/FadingView.tsx

@@ -31,7 +31,7 @@ type FadingViewProps = {
   /**
    * The children to be rendered inside the FadingView.
    */
-  children: React.ReactNode;
+  children?: React.ReactNode;
 } & React.ComponentProps<typeof Animated.View>;
 
 const FadingView = forwardRef<Animated.View, FadingViewProps>(

src/components/headers/Header.tsx

@@ -24,6 +24,7 @@ const Header: React.FC<HeaderProps> = ({
   ignoreTopSafeArea = false,
   borderColor,
   borderWidth,
+  SurfaceComponent,
 }) => {
   const { top } = useSafeAreaInsets();
   const dimensions = useWindowDimensions();
@@ -40,6 +41,8 @@ const Header: React.FC<HeaderProps> = ({
 
   return (
     <View>
+      {SurfaceComponent && SurfaceComponent({ showNavBar })}
+
       <View style={[styles.container, headerStyle, !ignoreTopSafeArea && { paddingTop: top }]}>
         {headerLeftFadesIn ? (
           <FadingView

src/components/headers/types.ts

@@ -1,6 +1,16 @@
 import type { StyleProp, ViewStyle } from 'react-native';
 import type Animated from 'react-native-reanimated';
 
+export interface SurfaceComponentProps {
+  /**
+   * Animated value between 0 and 1 that indicates whether the small header's content should be
+   * visible. This is used to animate the header's content in and out.
+   *
+   * @type {Animated.SharedValue<number>}
+   */
+  showNavBar: Animated.SharedValue<number>;
+}
+
 /**
  * The props for the navigation bar component.
  */
@@ -111,6 +121,14 @@ export interface HeaderProps {
    * @type {number}
    */
   borderWidth?: number;
+  /**
+   * A custom component to be rendered as the header's surface. This is useful if you want to
+   * customize the header's surface with a background/blur.
+   *
+   * @param {SurfaceComponentProps} props
+   * @returns {React.ReactNode}
+   */
+  SurfaceComponent?: (props: SurfaceComponentProps) => React.ReactNode;
 }
 
 /**