@umituz/react-native-design-system 2.0.1 → 2.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-design-system",
-  "version": "2.0.1",
-  "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography and responsive utilities",
+  "version": "2.0.3",
+  "description": "Universal design system for React Native apps - Consolidated package with atoms, molecules, organisms, theme, typography, responsive and safe area utilities",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -17,6 +17,7 @@
     "./theme": "./src/theme/index.ts",
     "./typography": "./src/typography/index.ts",
     "./responsive": "./src/responsive/index.ts",
+    "./safe-area": "./src/safe-area/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -37,7 +38,8 @@
     "organisms",
     "theme",
     "typography",
-    "responsive"
+    "responsive",
+    "safe-area"
   ],
   "author": "Ümit UZ <umit@umituz.com>",
   "license": "MIT",

package/src/index.ts

@@ -9,6 +9,7 @@
  * - Theme (design tokens, colors)
  * - Typography (text styles)
  * - Responsive (screen utilities)
+ * - Safe Area (safe area utilities and hooks)
  */
 
 // =============================================================================
@@ -174,6 +175,12 @@ export {
   FormContainer,
 } from './organisms';
 
+// =============================================================================
+// SAFE AREA EXPORTS
+// =============================================================================
+
+export * from './safe-area';
+
 // =============================================================================
 // VARIANT UTILITIES
 // =============================================================================

package/src/molecules/Divider/Divider.tsx

@@ -0,0 +1,187 @@
+/**
+ * Divider Domain - Divider Component
+ *
+ * Universal divider component for visual separation.
+ * Supports horizontal, vertical, and text dividers.
+ *
+ * @domain divider
+ * @layer presentation/components
+ */
+
+import React from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { useAppDesignTokens } from '../../theme/hooks/useAppDesignTokens';
+import { AtomicText } from '../../atoms/AtomicText';
+import type { DividerOrientation, DividerStyle, DividerSpacing } from './types';
+import {
+    DividerUtils,
+    DIVIDER_CONSTANTS,
+} from './types';
+
+/**
+ * Divider component props
+ */
+export interface DividerProps {
+    /** Orientation (horizontal or vertical) */
+    orientation?: DividerOrientation;
+    /** Line style (solid, dashed, dotted) */
+    lineStyle?: DividerStyle;
+    /** Spacing (margin) */
+    spacing?: DividerSpacing;
+    /** Custom color */
+    color?: string;
+    /** Custom thickness */
+    thickness?: number;
+    /** Text label (for text divider) */
+    text?: string;
+    /** Custom container style */
+    style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Divider Component
+ *
+ * Visual separator for content sections.
+ * Supports horizontal, vertical, and text variants.
+ *
+ * USAGE:
+ * ```typescript
+ * // Horizontal divider (default)
+ * <Divider />
+ *
+ * // Vertical divider
+ * <Divider orientation="vertical" />
+ *
+ * // Text divider (OR separator)
+ * <Divider text="OR" />
+ *
+ * // Custom spacing
+ * <Divider spacing="large" />
+ *
+ * // Dashed style
+ * <Divider lineStyle="dashed" />
+ *
+ * // Custom color
+ * <Divider color="#FF0000" />
+ * ```
+ */
+export const Divider: React.FC<DividerProps> = ({
+    orientation = DIVIDER_CONSTANTS.DEFAULT_ORIENTATION,
+    lineStyle = DIVIDER_CONSTANTS.DEFAULT_STYLE,
+    spacing = DIVIDER_CONSTANTS.DEFAULT_SPACING,
+    color,
+    thickness = DIVIDER_CONSTANTS.DEFAULT_THICKNESS,
+    text,
+    style,
+}) => {
+    const tokens = useAppDesignTokens();
+    const spacingValue = DividerUtils.getSpacing(spacing);
+    const borderColor = color || tokens.colors.border;
+
+    // Determine border style based on lineStyle
+    const getBorderStyle = (): 'solid' | 'dashed' | 'dotted' => {
+        return lineStyle;
+    };
+
+    // Horizontal divider
+    if (orientation === 'horizontal' && !text) {
+        return (
+            <View
+                style={[
+                    styles.horizontal,
+                    {
+                        marginVertical: spacingValue,
+                        borderBottomWidth: thickness,
+                        borderBottomColor: borderColor,
+                        borderStyle: getBorderStyle(),
+                    },
+                    style,
+                ]}
+            />
+        );
+    }
+
+    // Vertical divider
+    if (orientation === 'vertical') {
+        return (
+            <View
+                style={[
+                    styles.vertical,
+                    {
+                        marginHorizontal: spacingValue,
+                        borderLeftWidth: thickness,
+                        borderLeftColor: borderColor,
+                        borderStyle: getBorderStyle(),
+                    },
+                    style,
+                ]}
+            />
+        );
+    }
+
+    // Text divider (horizontal with text label)
+    if (text) {
+        return (
+            <View
+                style={[
+                    styles.textContainer,
+                    {
+                        marginVertical: spacingValue,
+                    },
+                    style,
+                ]}
+            >
+                <View
+                    style={[
+                        styles.textLine,
+                        {
+                            borderBottomWidth: thickness,
+                            borderBottomColor: borderColor,
+                            borderStyle: getBorderStyle(),
+                        },
+                    ]}
+                />
+                <AtomicText
+                    type="bodySmall"
+                    color="secondary"
+                    style={styles.textLabel}
+                >
+                    {text}
+                </AtomicText>
+                <View
+                    style={[
+                        styles.textLine,
+                        {
+                            borderBottomWidth: thickness,
+                            borderBottomColor: borderColor,
+                            borderStyle: getBorderStyle(),
+                        },
+                    ]}
+                />
+            </View>
+        );
+    }
+
+    return null;
+};
+
+const styles = StyleSheet.create({
+    horizontal: {
+        width: '100%',
+    },
+    vertical: {
+        height: '100%',
+    },
+    textContainer: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        width: '100%',
+    },
+    textLine: {
+        flex: 1,
+    },
+    textLabel: {
+        marginHorizontal: 12,
+        fontWeight: '500',
+    },
+});

package/src/molecules/Divider/index.ts

@@ -0,0 +1,2 @@
+export * from './Divider';
+export * from './types';

package/src/molecules/Divider/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Divider Domain - Entity Definitions
+ *
+ * Core types and interfaces for dividers and separators.
+ * Simple visual separators for content sections.
+ *
+ * @domain divider
+ * @layer domain/entities
+ */
+
+/**
+ * Divider orientation
+ */
+export type DividerOrientation = 'horizontal' | 'vertical';
+
+/**
+ * Divider style
+ */
+export type DividerStyle = 'solid' | 'dashed' | 'dotted';
+
+/**
+ * Divider spacing
+ */
+export type DividerSpacing = 'none' | 'small' | 'medium' | 'large';
+
+/**
+ * Divider configuration
+ */
+export interface DividerConfig {
+    /** Orientation */
+    orientation: DividerOrientation;
+    /** Line style */
+    style: DividerStyle;
+    /** Spacing (margin) */
+    spacing: DividerSpacing;
+    /** Custom color */
+    color?: string;
+    /** Custom thickness */
+    thickness?: number;
+    /** Text label (for text divider) */
+    text?: string;
+}
+
+/**
+ * Spacing configurations (px)
+ */
+export const SPACING_CONFIGS: Record<DividerSpacing, number> = {
+    none: 0,
+    small: 8,
+    medium: 16,
+    large: 24,
+};
+
+/**
+ * Divider utility class
+ */
+export class DividerUtils {
+    /**
+     * Get spacing value
+     */
+    static getSpacing(spacing: DividerSpacing): number {
+        return SPACING_CONFIGS[spacing];
+    }
+
+    /**
+     * Validate divider config
+     */
+    static validateConfig(config: Partial<DividerConfig>): DividerConfig {
+        return {
+            orientation: config.orientation || 'horizontal',
+            style: config.style || 'solid',
+            spacing: config.spacing || 'medium',
+            color: config.color,
+            thickness: config.thickness || 1,
+            text: config.text,
+        };
+    }
+}
+
+/**
+ * Divider constants
+ */
+export const DIVIDER_CONSTANTS = {
+    DEFAULT_ORIENTATION: 'horizontal' as DividerOrientation,
+    DEFAULT_STYLE: 'solid' as DividerStyle,
+    DEFAULT_SPACING: 'medium' as DividerSpacing,
+    DEFAULT_THICKNESS: 1,
+} as const;

package/src/molecules/index.ts

@@ -17,3 +17,6 @@ export type {
   ConfirmationModalProps,
   ConfirmationModalVariant,
 } from './confirmation-modal/types/';
+
+// Divider
+export * from './Divider';

package/src/organisms/ScreenLayout.example.tsx

@@ -0,0 +1,93 @@
+/**
+ * Enhanced ScreenLayout Example
+ * 
+ * This demonstrates the recommended usage of ScreenLayout with SafeAreaProvider
+ */
+
+import React from 'react';
+import { View, Text } from 'react-native';
+import {
+    SafeAreaProvider,
+    ScreenLayout,
+    ScreenHeader,
+    AtomicButton,
+    AtomicText
+} from '@umituz/react-native-design-system';
+
+// 1. Wrap your app root with SafeAreaProvider
+export function App() {
+    return (
+        <SafeAreaProvider>
+            <YourNavigator />
+        </SafeAreaProvider>
+    );
+}
+
+// 2. Use ScreenLayout in your screens
+export function HomeScreen() {
+    return (
+        <ScreenLayout
+            // Safe area edges - default is ['top']
+            edges={['top']}
+            // Enable scrolling - default is true
+            scrollable={true}
+            // Optional header
+            header={
+                <ScreenHeader
+                    title="Home"
+                    subtitle="Welcome back"
+                />
+            }
+            // Optional footer
+            footer={
+                <View style={{ padding: 16 }}>
+                    <AtomicButton onPress={() => console.log('Action')}>
+                        Action Button
+                    </AtomicButton>
+                </View>
+            }
+        >
+            <AtomicText type="h1">Welcome to Home</AtomicText>
+            <AtomicText type="body">
+                This screen uses ScreenLayout with default safe area configuration.
+            </AtomicText>
+        </ScreenLayout>
+    );
+}
+
+// 3. Modal screen example with different safe area edges
+export function ModalScreen() {
+    return (
+        <ScreenLayout
+            // Full safe area for modals
+            edges={['top', 'bottom']}
+            scrollable={false}
+        >
+            <AtomicText type="h2">Modal Content</AtomicText>
+        </ScreenLayout>
+    );
+}
+
+// 4. Screen with custom scroll behavior
+export function CustomScrollScreen() {
+    return (
+        <ScreenLayout scrollable={false}>
+            {/* Your custom scroll component */}
+            <YourCustomScrollView />
+        </ScreenLayout>
+    );
+}
+
+// 5. Using safe area hooks directly
+import { useContentSafeAreaPadding, useSafeAreaInsets } from '@umituz/react-native-design-system';
+
+export function CustomComponent() {
+    const insets = useSafeAreaInsets();
+    const { paddingBottom } = useContentSafeAreaPadding();
+
+    return (
+        <View style={{ paddingTop: insets.top, paddingBottom }}>
+            <Text>Custom Safe Area Usage</Text>
+        </View>
+    );
+}

package/src/organisms/ScreenLayout.tsx

@@ -28,6 +28,21 @@ import { View, ScrollView, StyleSheet, ViewStyle } from 'react-native';
 import { SafeAreaView, Edge } from 'react-native-safe-area-context';
 import { useAppDesignTokens } from '../theme';
 
+/**
+ * NOTE: This component now works in conjunction with the SafeAreaProvider
+ * from our safe-area module. The SafeAreaProvider should wrap your app root:
+ * 
+ * import { SafeAreaProvider } from '@umituz/react-native-design-system';
+ * 
+ * function App() {
+ *   return (
+ *     <SafeAreaProvider>
+ *       <YourApp />
+ *     </SafeAreaProvider>
+ *   );
+ * }
+ */
+
 export interface ScreenLayoutProps {
   /**
    * Content to render inside the layout

package/src/safe-area/__tests__/components/SafeAreaProvider.test.tsx

@@ -0,0 +1,15 @@
+/**
+ * Tests for SafeAreaProvider component
+ */
+
+describe('SafeAreaProvider', () => {
+  it('should be defined', () => {
+    const { SafeAreaProvider } = require('../../components/SafeAreaProvider');
+    expect(SafeAreaProvider).toBeDefined();
+  });
+
+  it('should have useSafeAreaConfig export', () => {
+    const { useSafeAreaConfig } = require('../../components/SafeAreaProvider');
+    expect(useSafeAreaConfig).toBeDefined();
+  });
+});

package/src/safe-area/__tests__/hooks/useContentSafeAreaPadding.test.tsx

@@ -0,0 +1,15 @@
+/**
+ * Tests for useContentSafeAreaPadding hook
+ */
+
+describe('useContentSafeAreaPadding', () => {
+  it('should be defined', () => {
+    const { useContentSafeAreaPadding } = require('../../hooks/useContentSafeAreaPadding');
+    expect(useContentSafeAreaPadding).toBeDefined();
+  });
+
+  it('should return function', () => {
+    const { useContentSafeAreaPadding } = require('../../hooks/useContentSafeAreaPadding');
+    expect(typeof useContentSafeAreaPadding).toBe('function');
+  });
+});

package/src/safe-area/__tests__/hooks/useHeaderSafeAreaPadding.test.tsx

@@ -0,0 +1,15 @@
+/**
+ * Tests for useHeaderSafeAreaPadding hook
+ */
+
+describe('useHeaderSafeAreaPadding', () => {
+  it('should be defined', () => {
+    const { useHeaderSafeAreaPadding } = require('../../hooks/useHeaderSafeAreaPadding');
+    expect(useHeaderSafeAreaPadding).toBeDefined();
+  });
+
+  it('should return function', () => {
+    const { useHeaderSafeAreaPadding } = require('../../hooks/useHeaderSafeAreaPadding');
+    expect(typeof useHeaderSafeAreaPadding).toBe('function');
+  });
+});

package/src/safe-area/__tests__/hooks/useSafeAreaInsets.test.tsx

@@ -0,0 +1,15 @@
+/**
+ * Tests for useSafeAreaInsets hook
+ */
+
+describe('useSafeAreaInsets', () => {
+  it('should be defined', () => {
+    const { useSafeAreaInsets } = require('../../hooks/useSafeAreaInsets');
+    expect(useSafeAreaInsets).toBeDefined();
+  });
+
+  it('should return function', () => {
+    const { useSafeAreaInsets } = require('../../hooks/useSafeAreaInsets');
+    expect(typeof useSafeAreaInsets).toBe('function');
+  });
+});

package/src/safe-area/__tests__/hooks/useStatusBarSafeAreaPadding.test.tsx

@@ -0,0 +1,15 @@
+/**
+ * Tests for useStatusBarSafeAreaPadding hook
+ */
+
+describe('useStatusBarSafeAreaPadding', () => {
+  it('should be defined', () => {
+    const { useStatusBarSafeAreaPadding } = require('../../hooks/useStatusBarSafeAreaPadding');
+    expect(useStatusBarSafeAreaPadding).toBeDefined();
+  });
+
+  it('should return function', () => {
+    const { useStatusBarSafeAreaPadding } = require('../../hooks/useStatusBarSafeAreaPadding');
+    expect(typeof useStatusBarSafeAreaPadding).toBe('function');
+  });
+});

package/src/safe-area/__tests__/integration/completeFlow.test.tsx

@@ -0,0 +1,25 @@
+/**
+ * Integration tests for complete flow
+ */
+
+describe('Integration Tests', () => {
+  it('should import useSafeAreaInsets', () => {
+    const { useSafeAreaInsets } = require('../../hooks/useSafeAreaInsets');
+    expect(useSafeAreaInsets).toBeDefined();
+  });
+
+  it('should import useStatusBarSafeAreaPadding', () => {
+    const { useStatusBarSafeAreaPadding } = require('../../hooks/useStatusBarSafeAreaPadding');
+    expect(useStatusBarSafeAreaPadding).toBeDefined();
+  });
+
+  it('should import useHeaderSafeAreaPadding', () => {
+    const { useHeaderSafeAreaPadding } = require('../../hooks/useHeaderSafeAreaPadding');
+    expect(useHeaderSafeAreaPadding).toBeDefined();
+  });
+
+  it('should import useContentSafeAreaPadding', () => {
+    const { useContentSafeAreaPadding } = require('../../hooks/useContentSafeAreaPadding');
+    expect(useContentSafeAreaPadding).toBeDefined();
+  });
+});

package/src/safe-area/__tests__/setup.ts

@@ -0,0 +1,50 @@
+/**
+ * Jest setup file
+ */
+
+// Define __DEV__ for tests
+(global as any).__DEV__ = true;
+
+// Mock react-native-safe-area-context
+jest.mock('react-native-safe-area-context', () => ({
+  SafeAreaProvider: ({ children }: { children: React.ReactNode }) => children,
+  useSafeAreaInsets: () => ({
+    top: 44,
+    bottom: 34,
+    left: 0,
+    right: 0,
+  }),
+}));
+
+// Mock SafeAreaProvider to avoid JSX issues
+jest.mock('../components/SafeAreaProvider', () => ({
+  SafeAreaProvider: ({ children }: { children: React.ReactNode }) => children,
+  useSafeAreaConfig: () => ({
+    minHeaderPadding: 0,
+    minContentPadding: 0,
+    minStatusBarPadding: 0,
+    additionalPadding: 0,
+    iosStatusBarUsesSafeArea: true,
+  }),
+}), { virtual: true });
+
+// Mock Platform
+jest.mock('react-native', () => ({
+  Platform: {
+    OS: 'ios',
+    select: (obj: Record<string, any>) => obj.ios,
+  },
+}));
+
+// Mock performance API for performance tests
+global.performance = {
+  ...global.performance,
+  now: jest.fn(() => Date.now()),
+};
+
+// Simple test to make test suite valid
+describe('setup', () => {
+  it('should define __DEV__', () => {
+    expect((global as any).__DEV__).toBe(true);
+  });
+});

package/src/safe-area/__tests__/utils/performance.test.tsx

@@ -0,0 +1,18 @@
+/**
+ * Performance tests for utilities
+ */
+
+describe('Performance Tests', () => {
+  it('should complete quickly', () => {
+    const startTime = performance.now();
+    
+    // Simple operation
+    const result = Math.random();
+    
+    const endTime = performance.now();
+    const duration = endTime - startTime;
+    
+    expect(duration).toBeLessThan(100);
+    expect(typeof result).toBe('number');
+  });
+});

package/src/safe-area/__tests__/utils/testUtils.tsx

@@ -0,0 +1,43 @@
+/**
+ * Simple test utilities for safe area package
+ */
+
+export const mockSafeAreaInsets = {
+  top: 44,
+  bottom: 34,
+  left: 0,
+  right: 0,
+};
+
+export const createWrapper = (insets = mockSafeAreaInsets) => {
+  return ({ children }: { children: any }) => children;
+};
+
+export const renderHookWithSafeArea = <T, P>(
+  hook: (props: P) => T,
+  options?: {
+    initialProps?: P;
+    wrapper?: any;
+    insets?: typeof mockSafeAreaInsets;
+  },
+) => {
+  const wrapper = options?.wrapper || createWrapper(options?.insets);
+  
+  return {
+    result: { current: hook(options?.initialProps as P) },
+    rerender: () => {},
+  };
+};
+
+export const resetMocks = () => {
+  jest.clearAllMocks();
+  jest.resetModules();
+};
+
+describe('testUtils', () => {
+  it('should export functions', () => {
+    expect(typeof mockSafeAreaInsets).toBe('object');
+    expect(typeof createWrapper).toBe('function');
+    expect(typeof resetMocks).toBe('function');
+  });
+});

package/src/safe-area/components/SafeAreaProvider.tsx

@@ -0,0 +1,55 @@
+/**
+ * SafeAreaProvider Component
+ * Enhanced wrapper around react-native-safe-area-context with configurable defaults
+ */
+
+import React, { createContext, useContext } from 'react';
+import {
+  SafeAreaProvider as NativeSafeAreaProvider,
+  SafeAreaProviderProps as NativeSafeAreaProviderProps,
+} from 'react-native-safe-area-context';
+import { DEFAULT_CONFIG } from '../constants';
+
+export interface SafeAreaConfig {
+  minHeaderPadding: number;
+  minContentPadding: number;
+  minStatusBarPadding: number;
+  additionalPadding: number;
+  iosStatusBarUsesSafeArea: boolean;
+}
+
+export interface SafeAreaProviderProps extends NativeSafeAreaProviderProps {
+  config?: SafeAreaConfig;
+}
+
+const SafeAreaConfigContext = createContext<SafeAreaConfig>(DEFAULT_CONFIG);
+
+export const useSafeAreaConfig = (): SafeAreaConfig => {
+  return useContext(SafeAreaConfigContext);
+};
+
+export const SafeAreaProvider: React.FC<SafeAreaProviderProps> = ({
+  children,
+  config,
+  ...nativeProps
+}) => {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+
+  if (__DEV__) {
+    if (config) {
+      Object.entries(config).forEach(([key, value]) => {
+        if (typeof value !== 'number' && typeof value !== 'boolean') {
+          console.warn(`SafeAreaProvider: ${key} must be a number or boolean, got ${typeof value}`);
+        }
+      });
+    }
+  }
+
+  return (
+    <SafeAreaConfigContext.Provider value={mergedConfig}>
+      <NativeSafeAreaProvider {...nativeProps}>
+        {children}
+      </NativeSafeAreaProvider>
+    </SafeAreaConfigContext.Provider>
+  );
+};

package/src/safe-area/constants/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Constants for safe area calculations
+ */
+
+export const SAFE_AREA_DEFAULTS = {
+  MIN_HEADER_PADDING: 0,
+  MIN_CONTENT_PADDING: 0,
+  MIN_STATUS_BAR_PADDING: 0,
+  ADDITIONAL_PADDING: 0,
+} as const;
+
+export const PLATFORM_BEHAVIORS = {
+  IOS_STATUS_BAR_USES_SAFE_AREA: true,
+} as const;
+
+/**
+ * Default configuration that can be overridden by applications
+ */
+export const DEFAULT_CONFIG = {
+  minHeaderPadding: SAFE_AREA_DEFAULTS.MIN_HEADER_PADDING,
+  minContentPadding: SAFE_AREA_DEFAULTS.MIN_CONTENT_PADDING,
+  minStatusBarPadding: SAFE_AREA_DEFAULTS.MIN_STATUS_BAR_PADDING,
+  additionalPadding: SAFE_AREA_DEFAULTS.ADDITIONAL_PADDING,
+  iosStatusBarUsesSafeArea: PLATFORM_BEHAVIORS.IOS_STATUS_BAR_USES_SAFE_AREA,
+} as const;

package/src/safe-area/hooks/useContentSafeAreaPadding.ts

@@ -0,0 +1,41 @@
+/**
+ * useContentSafeAreaPadding Hook
+ * Calculate safe area padding for content components
+ */
+
+import { useMemo } from 'react';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useSafeAreaConfig } from '../components/SafeAreaProvider';
+import { useStableOptions } from '../utils/optimization';
+import { validateNumericInput } from '../utils/validation';
+
+export interface ContentPaddingOptions {
+  minBottomPadding?: number;
+  additionalPadding?: number;
+}
+
+export interface ContentPaddingResult {
+  paddingBottom: number;
+}
+
+export const useContentSafeAreaPadding = (
+  options: ContentPaddingOptions = {},
+): ContentPaddingResult => {
+  const insets = useSafeAreaInsets();
+  const config = useSafeAreaConfig();
+  const stableOptions = useStableOptions(options);
+  const minBottomPadding = stableOptions.minBottomPadding ?? config.minContentPadding;
+  const additionalPadding = stableOptions.additionalPadding ?? config.additionalPadding;
+
+  // Validate inputs once
+  useMemo(() => {
+    validateNumericInput(minBottomPadding, 'useContentSafeAreaPadding.minBottomPadding');
+    validateNumericInput(additionalPadding, 'useContentSafeAreaPadding.additionalPadding');
+  }, [minBottomPadding, additionalPadding]);
+
+  const paddingBottom = useMemo(() => {
+    return Math.max(insets.bottom, minBottomPadding) + additionalPadding;
+  }, [insets.bottom, minBottomPadding, additionalPadding]);
+
+  return useMemo(() => ({ paddingBottom }), [paddingBottom]);
+};

package/src/safe-area/hooks/useHeaderSafeAreaPadding.ts

@@ -0,0 +1,35 @@
+/**
+ * useHeaderSafeAreaPadding Hook
+ * Calculate safe area padding for header components
+ */
+
+import { useMemo } from 'react';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useSafeAreaConfig } from '../components/SafeAreaProvider';
+import { useStableOptions } from '../utils/optimization';
+import { validateNumericInput } from '../utils/validation';
+
+export interface HeaderPaddingOptions {
+  minPadding?: number;
+  additionalPadding?: number;
+}
+
+export const useHeaderSafeAreaPadding = (
+  options: HeaderPaddingOptions = {},
+): number => {
+  const insets = useSafeAreaInsets();
+  const config = useSafeAreaConfig();
+  const stableOptions = useStableOptions(options);
+  const minPadding = stableOptions.minPadding ?? config.minHeaderPadding;
+  const additionalPadding = stableOptions.additionalPadding ?? config.additionalPadding;
+
+  // Validate inputs once
+  useMemo(() => {
+    validateNumericInput(minPadding, 'useHeaderSafeAreaPadding.minPadding');
+    validateNumericInput(additionalPadding, 'useHeaderSafeAreaPadding.additionalPadding');
+  }, [minPadding, additionalPadding]);
+
+  return useMemo(() => {
+    return Math.max(insets.top, minPadding) + additionalPadding;
+  }, [insets.top, minPadding, additionalPadding]);
+};

package/src/safe-area/hooks/useSafeAreaInsets.ts

@@ -0,0 +1,9 @@
+/**
+ * useSafeAreaInsets Hook
+ * Get safe area insets
+ */
+
+import { useSafeAreaInsets as useNativeSafeAreaInsets } from 'react-native-safe-area-context';
+
+export const useSafeAreaInsets = useNativeSafeAreaInsets;
+

package/src/safe-area/hooks/useStatusBarSafeAreaPadding.ts

@@ -0,0 +1,36 @@
+/**
+ * useStatusBarSafeAreaPadding Hook
+ * Calculate safe area padding for status bar components
+ */
+
+import { useMemo } from 'react';
+import { Platform } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useSafeAreaConfig } from '../components/SafeAreaProvider';
+import { useStableOptions } from '../utils/optimization';
+import { validateNumericInput } from '../utils/validation';
+
+export interface StatusBarPaddingOptions {
+  minPadding?: number;
+}
+
+export const useStatusBarSafeAreaPadding = (
+  options: StatusBarPaddingOptions = {},
+): number => {
+  const insets = useSafeAreaInsets();
+  const config = useSafeAreaConfig();
+  const stableOptions = useStableOptions(options);
+  const minPadding = stableOptions.minPadding ?? config.minStatusBarPadding;
+
+  // Validate input once
+  useMemo(() => {
+    validateNumericInput(minPadding, 'useStatusBarSafeAreaPadding.minPadding');
+  }, [minPadding]);
+
+  return useMemo(() => {
+    if (Platform.OS === 'ios' && config.iosStatusBarUsesSafeArea) {
+      return minPadding;
+    }
+    return Math.max(insets.top, minPadding);
+  }, [insets.top, minPadding, config.iosStatusBarUsesSafeArea]);
+};

package/src/safe-area/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Safe Area Module
+ * Configurable safe area provider and hooks for React Native apps
+ */
+
+export { SafeAreaProvider, useSafeAreaConfig } from './components/SafeAreaProvider';
+export type { SafeAreaProviderProps, SafeAreaConfig } from './components/SafeAreaProvider';
+
+export { useSafeAreaInsets } from './hooks/useSafeAreaInsets';
+export { useStatusBarSafeAreaPadding } from './hooks/useStatusBarSafeAreaPadding';
+export type { StatusBarPaddingOptions } from './hooks/useStatusBarSafeAreaPadding';
+
+export { useHeaderSafeAreaPadding } from './hooks/useHeaderSafeAreaPadding';
+export type { HeaderPaddingOptions } from './hooks/useHeaderSafeAreaPadding';
+
+export { useContentSafeAreaPadding } from './hooks/useContentSafeAreaPadding';
+export type { ContentPaddingOptions, ContentPaddingResult } from './hooks/useContentSafeAreaPadding';
+
+export { SAFE_AREA_DEFAULTS, PLATFORM_BEHAVIORS, DEFAULT_CONFIG } from './constants';
+export { useStableOptions, clearPerformanceCaches } from './utils/optimization';
+export { validateNumericInput, throttledWarn, clearValidationCache } from './utils/validation';
+
+// Re-export from react-native-safe-area-context for convenience
+export { initialWindowMetrics } from 'react-native-safe-area-context';

package/src/safe-area/utils/optimization.ts

@@ -0,0 +1,47 @@
+/**
+ * Performance optimization utilities for safe area hooks
+ */
+
+import { useMemo, useRef } from 'react';
+import { clearValidationCache } from './validation';
+
+/**
+ * Memoize options object to prevent unnecessary re-renders
+ * Uses deep comparison for better stability
+ */
+export const useStableOptions = <T extends Record<string, any>>(options: T): T => {
+  const prevOptionsRef = useRef<T | undefined>(undefined);
+
+  return useMemo(() => {
+    if (!prevOptionsRef.current) {
+      prevOptionsRef.current = options;
+      return options;
+    }
+
+    // Check if keys match first
+    const prevKeys = Object.keys(prevOptionsRef.current);
+    const currentKeys = Object.keys(options);
+
+    if (prevKeys.length !== currentKeys.length) {
+      prevOptionsRef.current = options;
+      return options;
+    }
+
+    // Check values
+    const hasChanged = prevKeys.some(key => prevOptionsRef.current![key] !== options[key]);
+
+    if (hasChanged) {
+      prevOptionsRef.current = options;
+    }
+
+    return prevOptionsRef.current;
+  }, [options]);
+};
+
+/**
+ * Cleanup function to clear all performance caches
+ * Call this in useEffect cleanup if needed
+ */
+export const clearPerformanceCaches = (): void => {
+  clearValidationCache();
+};

package/src/safe-area/utils/performance.ts

@@ -0,0 +1,10 @@
+/**
+ * Performance utilities for safe area hooks
+ * @deprecated This file is deprecated. Use individual utility modules instead.
+ * - useStableOptions and clearPerformanceCaches are now in './optimization'
+ * - validateNumericInput and throttledWarn are now in './validation'
+ */
+
+// Re-export for backward compatibility
+export { useStableOptions, clearPerformanceCaches } from './optimization';
+export { validateNumericInput, throttledWarn, clearValidationCache } from './validation';

package/src/safe-area/utils/validation.ts

@@ -0,0 +1,74 @@
+/**
+ * Validation utilities for safe area hooks
+ */
+
+// Validate numeric input with performance optimization
+// Caches validation results to avoid repeated checks
+const validationCache = new Map<string, boolean>();
+
+export const validateNumericInput = (
+  value: number,
+  name: string,
+  allowNegative = false,
+): boolean => {
+  if (!__DEV__) {
+    return true;
+  }
+  
+  const cacheKey = `${name}:${value}:${allowNegative}`;
+  
+  if (validationCache.has(cacheKey)) {
+    return validationCache.get(cacheKey)!;
+  }
+  
+  const isValid = typeof value === 'number' && !isNaN(value) && (allowNegative || value >= 0);
+  
+  if (!isValid) {
+    throttledWarn(`${name}: must be a ${allowNegative ? 'number' : 'non-negative number'}, got ${value}`);
+  }
+  
+  // Limit cache size to prevent memory leaks
+  if (validationCache.size > 100) {
+    const firstKey = validationCache.keys().next().value;
+    if (firstKey) {
+      validationCache.delete(firstKey);
+    }
+  }
+  
+  validationCache.set(cacheKey, isValid);
+  return isValid;
+};
+
+// Throttled console warning to prevent spam
+// Uses requestAnimationFrame for better performance
+const warningTimes = new Map<string, number>();
+const WARNING_THROTTLE = 1000; // 1 second
+
+export const throttledWarn = (message: string): void => {
+  if (!__DEV__) {
+    return;
+  }
+  
+  const now = Date.now();
+  const lastTime = warningTimes.get(message) || 0;
+  
+  if (now - lastTime > WARNING_THROTTLE) {
+    console.warn(message);
+    warningTimes.set(message, now);
+    
+    // Clean up old entries to prevent memory leaks
+    if (warningTimes.size > 50) {
+      const cutoffTime = now - WARNING_THROTTLE * 10;
+      for (const [key, time] of warningTimes.entries()) {
+        if (time < cutoffTime) {
+          warningTimes.delete(key);
+        }
+      }
+    }
+  }
+};
+
+// Cleanup function to clear validation cache
+export const clearValidationCache = (): void => {
+  validationCache.clear();
+};