Header Components

/**
 * Main header component for navigation screens
 * @param props - Header configuration options
 * @returns React element representing the complete header
 */
function Header(props: {
  /** Header title text (required) */
  title: string;
  /** Back button configuration */
  back?: { title: string | undefined; href: string | undefined };
  /** Whether header is in modal presentation */
  modal?: boolean;
  /** Screen layout dimensions */
  layout?: Layout;
} & HeaderOptions): React.ReactElement;

import { Header } from "@react-navigation/elements";

// Basic header
<Header title="Settings" />

// Header with back button
<Header 
  title="Profile" 
  back={{ title: "Settings" }}
/>

// Customized header
<Header
  title="Messages"
  headerTintColor="#007AFF"
  headerStyle={{ backgroundColor: "#f8f9fa" }}
  headerRight={({ tintColor }) => (
    <HeaderButton onPress={handleAddMessage}>
      <Icon name="plus" color={tintColor} />
    </HeaderButton>
  )}
/>

// Transparent header
<Header
  title="Photo"
  headerTransparent={true}
  headerBackground={() => (
    <HeaderBackground style={{ backgroundColor: 'rgba(255,255,255,0.9)' }} />
  )}
/>

/**
 * Generic header button component with platform-specific press effects
 * @param props - Button configuration and content
 * @returns React element representing a header button
 */
const HeaderButton: React.ForwardRefExoticComponent<{
  /** Callback when button is pressed */
  onPress?: () => void;
  /** Web anchor href for link behavior */
  href?: string;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Screen reader accessibility label */
  accessibilityLabel?: string;
  /** Test identifier for automated testing */
  testID?: string;
  /** Icon and text tint color */
  tintColor?: string;
  /** Android material ripple color (Android >= 5.0) */
  pressColor?: string;
  /** Press opacity fallback when ripple not supported */
  pressOpacity?: number;
  /** Custom button styling */
  style?: StyleProp<ViewStyle>;
  /** Button content (usually icon or text) */
  children: React.ReactNode;
}>;

import { HeaderButton } from "@react-navigation/elements";

// Icon button
<HeaderButton 
  onPress={() => setShowSearch(true)}
  accessibilityLabel="Search"
>
  <Icon name="search" />
</HeaderButton>

// Text button
<HeaderButton 
  onPress={handleSave}
  tintColor="#007AFF"
>
  <Text>Save</Text>
</HeaderButton>

// Disabled button
<HeaderButton 
  onPress={handleDelete}
  disabled={!canDelete}
  tintColor="#FF3B30"
>
  <Icon name="trash" />
</HeaderButton>

/**
 * Navigation back button with platform-specific styling and behavior
 * @param props - Back button configuration
 * @returns React element representing a back button
 */
function HeaderBackButton(props: {
  /** Callback when button is pressed */
  onPress?: () => void;
  /** Web anchor href for link behavior */
  href?: string;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Screen reader accessibility label */
  accessibilityLabel?: string;
  /** Test identifier for automated testing */
  testID?: string;
  /** Icon and text tint color */
  tintColor?: string;
  /** Android material ripple color */
  pressColor?: string;
  /** Press opacity fallback */
  pressOpacity?: number;
  /** Custom button styling */
  style?: StyleProp<ViewStyle>;
  /** Custom back icon renderer */
  backImage?: (props: { tintColor: string }) => React.ReactNode;
  /** Button label text (usually previous screen title) */
  label?: string;
  /** Fallback label when space is limited */
  truncatedLabel?: string;
  /** How to display icon and title */
  displayMode?: HeaderBackButtonDisplayMode;
  /** Label text styling */
  labelStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
  /** Whether label font should scale for accessibility */
  allowFontScaling?: boolean;
  /** Label layout change callback */
  onLabelLayout?: (e: LayoutChangeEvent) => void;
  /** Screen layout dimensions */
  screenLayout?: Layout;
  /** Title layout dimensions */
  titleLayout?: Layout;
}): React.ReactElement;

import { HeaderBackButton } from "@react-navigation/elements";

// Standard back button
<HeaderBackButton 
  onPress={() => navigation.goBack()}
  label="Settings"
/>

// Minimal back button (icon only)
<HeaderBackButton 
  onPress={() => navigation.goBack()}
  displayMode="minimal"
/>

// Custom back icon
<HeaderBackButton 
  onPress={() => navigation.goBack()}
  backImage={({ tintColor }) => (
    <Icon name="arrow-left" color={tintColor} size={20} />
  )}
/>

// Custom styling
<HeaderBackButton 
  onPress={() => navigation.goBack()}
  label="Back"
  tintColor="#007AFF"
  labelStyle={{ fontSize: 16, fontWeight: 'bold' }}
/>

/**
 * Header title component with platform-specific typography
 * @param props - Title configuration and styling
 * @returns React element representing the header title
 */
function HeaderTitle(props: {
  /** Title text content */
  children?: string;
  /** Whether title font should scale for accessibility */
  allowFontScaling?: boolean;
  /** Title text color */
  tintColor?: string;
  /** Title layout change callback */
  onLayout?: (e: LayoutChangeEvent) => void;
  /** Custom title styling */
  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
} & Omit<TextProps, 'style'>): React.ReactElement;

import { HeaderTitle } from "@react-navigation/elements";

// Basic title
<HeaderTitle>My Screen</HeaderTitle>

// Styled title
<HeaderTitle 
  tintColor="#333"
  style={{ fontSize: 20, fontWeight: 'bold' }}
>
  Custom Title
</HeaderTitle>

// Title with layout tracking
<HeaderTitle 
  onLayout={(e) => setTitleWidth(e.nativeEvent.layout.width)}
>
  Dynamic Title
</HeaderTitle>

/**
 * Header background container component
 * @param props - Background styling configuration
 * @returns React element representing the header background
 */
function HeaderBackground(props: {
  /** Custom background styling */
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  /** Background content */
  children?: React.ReactNode;
}): React.ReactElement;

import { HeaderBackground } from "@react-navigation/elements";

// Gradient background
<HeaderBackground 
  style={{
    backgroundColor: 'transparent',
    background: 'linear-gradient(45deg, #ff6b6b, #4ecdc4)'
  }}
/>

// Image background
<HeaderBackground>
  <Image 
    source={{ uri: 'https://example.com/header-bg.jpg' }}
    style={{ width: '100%', height: '100%' }}
    resizeMode="cover"
  />
</HeaderBackground>

// Blur background
<HeaderBackground 
  style={{ backgroundColor: 'rgba(255,255,255,0.8)' }}
>
  <BlurView intensity={80} style={StyleSheet.absoluteFill} />
</HeaderBackground>