/// Centralized route path definitions for the KROW Staff application.
///
/// This file contains all route paths used in the Staff app, organized by feature.
/// All staff navigation should reference these constants to ensure consistency
/// and make route changes easier to manage.
///
/// See also:
///  * [ClientPaths] for Client app routes
///  * [StaffNavigator] for typed navigation methods
class StaffPaths {
  StaffPaths._();

  // ==========================================================================
  // CHILD ROUTE MANAGEMENT
  // ==========================================================================
  /// Generate child route based on the given route and parent route
  ///
  /// This is useful for creating nested routes within modules.
  static String childRoute(String parent, String child)  {
    final String childPath = child.replaceFirst(parent, '');
    
    // check if the child path is empty
    if (childPath.isEmpty) {
      return '/';
    } 
    
    // ensure the child path starts with a '/'
    if (!childPath.startsWith('/')) {
      return '/$childPath';
    }

    return childPath;
  }
  
  // ==========================================================================
  // AUTHENTICATION
  // ==========================================================================

  /// Root path for the staff authentication flow.
  ///
  /// This serves as the entry point for unauthenticated staff members.
  static const String root = '/';

  /// Get Started page (relative path within auth module).
  ///
  /// The landing page for unauthenticated users, offering login/signup options.
  static const String getStarted = '/get-started';

  /// Phone verification page (relative path within auth module).
  ///
  /// Used for both login and signup flows to verify phone numbers via OTP.
  /// Expects `mode` argument: 'login' or 'signup'
  static const String phoneVerification = '/phone-verification';

  /// Profile setup page (relative path within auth module).
  ///
  /// Initial profile setup for new staff members after verification.
  static const String profileSetup = '/profile-setup';

  // ==========================================================================
  // MAIN SHELL & NAVIGATION
  // ==========================================================================

  /// Main shell route with bottom navigation.
  ///
  /// This is the primary navigation container that hosts tabs for:
  /// Shifts, Payments, Home, Clock In, and Profile.
  static const String main = '/worker-main';

  /// Home tab - the main dashboard for staff.
  ///
  /// Displays shift cards, quick actions, and notifications.
  static const String home = '/worker-main/home/';

  /// Shifts tab - view and manage shifts.
  ///
  /// Browse available shifts, accepted shifts, and shift history.
  static const String shifts = '/worker-main/shifts/';

  /// Payments tab - view payment history and earnings.
  ///
  /// Access payment history, earnings breakdown, and tax information.
  static const String payments = '/worker-main/payments/';

  /// Clock In tab - clock in/out functionality.
  ///
  /// Time tracking interface for active shifts.
  static const String clockIn = '/worker-main/clock-in/';

  /// Profile tab - staff member profile and settings.
  ///
  /// Manage personal information, documents, and preferences.
  static const String profile = '/worker-main/profile/';

  // ==========================================================================
  // SHIFT MANAGEMENT
  // ==========================================================================

  /// Shift details route.
  ///
  /// View detailed information for a specific shift.
  static const String shiftDetailsRoute = '/worker-main/shift-details';

  /// Shift details page (dynamic).
  ///
  /// View detailed information for a specific shift.
  /// Path format: `/worker-main/shift-details/{shiftId}`
  ///
  /// Example: `/worker-main/shift-details/shift123`
  static String shiftDetails(String shiftId) =>
      '$shiftDetailsRoute/$shiftId';

  // ==========================================================================
  // ONBOARDING & PROFILE SECTIONS
  // ==========================================================================

  /// Personal information onboarding.
  ///
  /// Collect basic personal information during staff onboarding.
  static const String onboardingPersonalInfo =
      '/worker-main/onboarding/personal-info/';

  /// Emergency contact information.
  ///
  /// Manage emergency contact details for safety purposes.
  static const String emergencyContact = '/worker-main/emergency-contact/';

  /// Work experience information.
  ///
  /// Record previous work experience and qualifications.
  static const String experience = '/worker-main/experience/';

  /// Attire and appearance preferences.
  ///
  /// Record sizing and appearance information for uniform allocation.
  static const String attire = '/worker-main/attire/';

  // ==========================================================================
  // COMPLIANCE & DOCUMENTS
  // ==========================================================================

  /// Documents management - upload and manage required documents.
  ///
  /// Store ID, work permits, and other required documentation.
  static const String documents = '/worker-main/documents/';

  /// Certificates management - professional certifications.
  ///
  /// Manage professional certificates (e.g., food handling, CPR, etc.).
  static const String certificates = '/worker-main/certificates/';

  // ==========================================================================
  // FINANCIAL INFORMATION
  // ==========================================================================

  /// Bank account information for direct deposit.
  ///
  /// Manage banking details for payment processing.
  static const String bankAccount = '/worker-main/bank-account/';

  /// Tax forms and withholding information.
  ///
  /// Manage W-4, tax withholding, and related tax documents.
  static const String taxForms = '/worker-main/tax-forms/';

  /// Form I-9 - Employment Eligibility Verification.
  ///
  /// Complete and manage I-9 employment verification form.
  static const String formI9 = '/worker-main/tax-forms/i9';

  /// Form W-4 - Employee's Withholding Certificate.
  ///
  /// Complete and manage W-4 tax withholding form.
  static const String formW4 = '/worker-main/tax-forms/w4';

  /// Time card - view detailed time tracking records.
  ///
  /// Access detailed time entries and timesheets.
  static const String timeCard = '/worker-main/time-card/';

  // ==========================================================================
  // SCHEDULING & AVAILABILITY
  // ==========================================================================

  /// Availability management - set working hours preferences.
  ///
  /// Define when the staff member is available to work.
  static const String availability = '/worker-main/availability/';

  // ==========================================================================
  // ADDITIONAL FEATURES (Placeholders)
  // ==========================================================================

  /// Krow University - training and education (placeholder).
  ///
  /// Access to training materials and courses.
  static const String krowUniversity = '/krow-university';

  /// Training modules (placeholder).
  static const String trainings = '/trainings';

  /// Leaderboard - performance rankings (placeholder).
  static const String leaderboard = '/leaderboard';

  /// FAQs - frequently asked questions.
  static const String faqs = '/faqs';

  /// Privacy and security settings.
  static const String privacy = '/privacy';

  /// Messages - internal messaging system (placeholder).
  static const String messages = '/messages';

  /// General settings (placeholder).
  static const String settings = '/settings';
}
