NeoScan_Radiologist/app/navigation/navigationUtils.ts

/*
 * File: navigationUtils.ts
 * Description: Navigation utility functions for common navigation operations
 * Design & Developed by Tech4Biz Solutions
 * Copyright (c) Spurrin Innovations. All rights reserved.
 */

import { NavigationRef } from './navigationTypes';

// ============================================================================
// NAVIGATION REFERENCE
// ============================================================================

/**
 * navigationRef
 * 
 * Purpose: Global navigation reference for programmatic navigation
 * 
 * Usage:
 * - Set this reference in the main App component
 * - Use for navigation from outside React components
 * - Enables navigation from services, utilities, or event handlers
 * 
 * Example:
 * navigationRef.current?.navigate('Main');
 */
export let navigationRef: React.RefObject<NavigationRef> | null = null;

/**
 * setNavigationRef
 * 
 * Purpose: Set the global navigation reference
 * 
 * @param ref - Navigation reference object
 * 
 * Usage:
 * Called from the main App component to set the navigation reference
 */
export const setNavigationRef = (ref: React.RefObject<NavigationRef | null>) => {
  navigationRef = ref as React.RefObject<NavigationRef>;
};

// ============================================================================
// NAVIGATION HELPER FUNCTIONS
// ============================================================================

/**
 * navigateToScreen
 * 
 * Purpose: Navigate to a specific screen with optional parameters
 * 
 * @param screenName - Name of the screen to navigate to
 * @param params - Optional parameters to pass to the screen
 * 
 * Example:
 * navigateToScreen('Main', { tab: 'Dashboard' });
 */
export const navigateToScreen = (screenName: string, params?: any) => {
  if (navigationRef?.current) {
    navigationRef.current.navigate(screenName as any, params);
  }
};

/**
 * goBack
 * 
 * Purpose: Navigate back to the previous screen
 * 
 * Example:
 * goBack();
 */
export const goBack = () => {
  if (navigationRef?.current) {
    navigationRef.current.goBack();
  }
};

/**
 * resetNavigation
 * 
 * Purpose: Reset the navigation state to a specific screen
 * 
 * @param screenName - Name of the screen to reset to
 * @param params - Optional parameters for the screen
 * 
 * Example:
 * resetNavigation('Login'); // Reset to login screen
 */
export const resetNavigation = (screenName: string, params?: any) => {
  if (navigationRef?.current) {
    navigationRef.current.reset({
      index: 0,
      routes: [{ name: screenName, params }],
    });
  }
};

// ============================================================================
// SCREEN-SPECIFIC NAVIGATION FUNCTIONS
// ============================================================================

/**
 * navigateToDashboard
 * 
 * Purpose: Navigate to the dashboard with specific data
 * 
 * @param dashboard - Dashboard data to pass
 * @param patients - Patient data to pass
 * @param alerts - Alert data to pass
 * 
 * Example:
 * navigateToDashboard(dashboardData, patientList, alertList);
 */
export const navigateToDashboard = (
  dashboard: any,
  patients: any[],
  alerts: any[]
) => {
  navigateToScreen('Main', {
    screen: 'Dashboard',
    params: {
      dashboard,
      patients,
      alerts,
    },
  });
};

/**
 * navigateToPatientDetails
 * 
 * Purpose: Navigate to patient details screen
 * 
 * @param patientId - ID of the patient to view
 * 
 * Example:
 * navigateToPatientDetails('patient123');
 */
export const navigateToPatientDetails = (patientId: string) => {
  navigateToScreen('Main', {
    screen: 'Patients',
    params: {
      patientId,
    },
  });
};

/**
 * navigateToAlerts
 * 
 * Purpose: Navigate to alerts screen with optional filters
 * 
 * @param priority - Optional priority filter
 * @param unreadOnly - Optional flag for unread alerts only
 * 
 * Example:
 * navigateToAlerts('CRITICAL', true);
 */
export const navigateToAlerts = (priority?: string, unreadOnly?: boolean) => {
  navigateToScreen('Main', {
    screen: 'Alerts',
    params: {
      priority,
      unreadOnly,
    },
  });
};

/**
 * navigateToReports
 * 
 * Purpose: Navigate to reports screen with optional filters
 * 
 * @param patientId - Optional patient ID filter
 * @param dateRange - Optional date range filter
 * 
 * Example:
 * navigateToReports('patient123', { start: new Date(), end: new Date() });
 */
export const navigateToReports = (patientId?: string, dateRange?: any) => {
  navigateToScreen('Main', {
    screen: 'Reports',
    params: {
      patientId,
      dateRange,
    },
  });
};

/**
 * navigateToSettings
 * 
 * Purpose: Navigate to settings screen with optional section
 * 
 * @param section - Optional section to navigate to within settings
 * 
 * Example:
 * navigateToSettings('profile');
 */
export const navigateToSettings = (section?: string) => {
  navigateToScreen('Main', {
    screen: 'Settings',
    params: {
      section,
    },
  });
};

// ============================================================================
// AUTHENTICATION NAVIGATION FUNCTIONS
// ============================================================================

/**
 * navigateToLogin
 * 
 * Purpose: Navigate to login screen
 * 
 * Example:
 * navigateToLogin();
 */
export const navigateToLogin = () => {
  resetNavigation('Login');
};

/**
 * navigateToMainApp
 * 
 * Purpose: Navigate to main app after successful authentication
 * 
 * Example:
 * navigateToMainApp();
 */
export const navigateToMainApp = () => {
  resetNavigation('Main');
};

// ============================================================================
// ERROR HANDLING
// ============================================================================

/**
 * handleNavigationError
 * 
 * Purpose: Handle navigation errors gracefully
 * 
 * @param error - Navigation error object
 * @param fallbackScreen - Fallback screen to navigate to
 * 
 * Example:
 * handleNavigationError(error, 'Login');
 */
export const handleNavigationError = (error: any, fallbackScreen: string) => {
  console.error('Navigation error:', error);
  
  // Navigate to fallback screen
  resetNavigation(fallbackScreen);
};

/*
 * End of File: navigationUtils.ts
 * Design & Developed by Tech4Biz Solutions
 * Copyright (c) Spurrin Innovations. All rights reserved.
 */