# GoRouter Navigation Configuration

This directory contains the navigation configuration for the BuyerKiosk Live Flutter app using GoRouter with Riverpod integration.

## Files

- **app_router.dart** - Main router configuration with all routes and navigation logic

## Route Structure

```
/install                              - Installation screen (for first-time setup)
/                                     - Dashboard (list of stores)
/store/:typeNum                       - Store detail screen
/store/:typeNum/queue                 - Buy queue for the store
/store/:typeNum/completed             - Completed buys for the store
/store/:typeNum/stats                 - Buyer statistics for the store
/store/:typeNum/notes                 - Shift notes for the store
/store/:typeNum/notes/create          - Task creation screen
```

## Usage

### Basic Navigation

```dart
// Navigate to a route
context.go('/');
context.go('/install');
context.go('/store/12345');

// Navigate back
context.pop();

// Use named routes
context.goNamed('dashboard');
context.goNamed('store-detail', pathParameters: {'typeNum': '12345'});
```

### Using Helper Extensions

The router includes convenient extension methods on `BuildContext`:

```dart
// Navigate to dashboard
context.goToDashboard();

// Navigate to installation
context.goToInstallation();

// Navigate to store detail
context.goToStoreDetail('12345', storeName: 'Store Name');

// Navigate to buy queue
context.goToQueue('12345', storeName: 'Store Name');

// Navigate to completed buys
context.goToCompleted('12345', storeName: 'Store Name');

// Navigate to buyer stats
context.goToStats('12345', storeName: 'Store Name');

// Navigate to shift notes
context.goToNotes('12345', storeName: 'Store Name');

// Navigate to task creation
context.goToTaskCreation('12345', storeName: 'Store Name');
```

### Passing Parameters

Store name can be passed as a query parameter:

```dart
// Manually building the route
context.go('/store/12345?storeName=Main%20Store');

// Using helper methods (recommended)
context.goToStoreDetail('12345', storeName: 'Main Store');
```

### Accessing Route Parameters in Screens

```dart
class StoreDetailScreen extends StatelessWidget {
  final String typeNum;
  final String? storeName;

  const StoreDetailScreen({
    super.key,
    required this.typeNum,
    this.storeName,
  });

  @override
  Widget build(BuildContext context) {
    // Use typeNum and storeName
    return Scaffold(
      appBar: AppBar(
        title: Text(storeName ?? 'Store $typeNum'),
      ),
      body: // ... your UI
    );
  }
}
```

## Authentication Flow

The router implements redirect logic for authentication:

1. **Not Installed**: If the app is not installed (no API key), users are redirected to `/install`
2. **Already Installed**: If the app is installed and user tries to access `/install`, they are redirected to `/`

### Implementing Auth State

Replace the placeholder `authStateProvider` with your actual authentication provider:

```dart
final authStateProvider = StreamProvider<bool>((ref) {
  final authService = ref.watch(authServiceProvider);
  return authService.authStateStream;
});
```

Update the redirect logic in `routerProvider` to check for actual API key:

```dart
redirect: (BuildContext context, GoRouterState state) {
  final secureStorage = ref.read(secureStorageProvider);
  final hasApiKey = await secureStorage.hasApiKey();

  final isGoingToInstall = state.matchedLocation == '/install';

  if (!hasApiKey && !isGoingToInstall) {
    return '/install';
  }

  if (hasApiKey && isGoingToInstall) {
    return '/';
  }

  return null;
}
```

## Accessing Router in Code

The router is provided via Riverpod:

```dart
class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final router = ref.watch(routerProvider);

    // Use router methods
    router.go('/dashboard');

    return // ... your UI
  }
}
```

## Placeholder Screens

The `app_router.dart` file currently includes placeholder screen widgets. Replace these with your actual screen imports:

```dart
// Remove placeholder screens from app_router.dart
// Add actual imports:
import 'package:buyer_kiosk_live/presentation/screens/installation/installation_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/dashboard/dashboard_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/store_detail/store_detail_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/queue/buy_queue_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/completed/completed_buys_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/stats/buyer_stats_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/shift_notes/shift_notes_screen.dart';
import 'package:buyer_kiosk_live/presentation/screens/shift_notes/task_creation_screen.dart';
```

## Error Handling

The router includes a custom error page that displays when a route is not found. Users can navigate back to the dashboard from the error page.

## Deep Linking

GoRouter automatically supports deep linking. To enable deep linking on Android/iOS, configure your platform-specific files according to the [GoRouter documentation](https://pub.dev/packages/go_router#deep-linking).

## Testing Navigation

```dart
testWidgets('Navigation test', (tester) async {
  await tester.pumpWidget(
    ProviderScope(
      child: BuyerKioskApp(),
    ),
  );

  // Find and tap navigation elements
  await tester.tap(find.text('Store Detail'));
  await tester.pumpAndSettle();

  // Verify navigation
  expect(find.text('Store Detail Screen'), findsOneWidget);
});
```

## Best Practices

1. **Use Named Routes**: Prefer named routes for better maintainability
2. **Use Helper Extensions**: Use the provided extension methods for type-safe navigation
3. **Pass Data Correctly**: Use path parameters for required data, query parameters for optional data
4. **Handle Back Navigation**: Use `context.pop()` to go back in the navigation stack
5. **Test Routes**: Write tests for your navigation logic