# Navigation transitions (Kasy Kit)

## Overview

Screen transitions are centralized under `lib/core/navigation/`.  
**Android, iOS, and Web use the same animation** — not `Zoom` on Android and `Cupertino` on iOS.

## Change the default for the whole app

Edit [`lib/core/navigation/kasy_navigation_config.dart`](../lib/core/navigation/kasy_navigation_config.dart):

```dart
class KasyNavigationConfig {
  static KasyTransitionKind push = KasyTransitionKind.fade; // change here
  static const Duration duration = Duration(milliseconds: 250);
  // ...
}
```

| Config field | Used for |
|--------------|----------|
| `push` | Most GoRouter routes (`kasyTransitionPage` without override) |
| `replace` | Reserved for replace-style navigation |
| `authPeer` | Login ↔ signup |
| `bottomTab` | Bottom menu tabs (Bart) |
| `onboardingStep` | Onboarding inner navigator |

## Add a new GoRouter route

Use `pageBuilder`, not `builder`:

```dart
GoRoute(
  path: '/my_feature',
  pageBuilder: (context, state) => kasyTransitionPage(
    key: state.pageKey,
    child: const MyFeaturePage(),
  ),
),
```

### Override for one route

```dart
pageBuilder: (context, state) => kasyTransitionPage(
  key: state.pageKey,
  transition: KasyTransitionKind.none,
  child: const MyFeaturePage(),
),
```

## Legacy `Navigator.push`

Use `KasyMaterialPageRoute` instead of `MaterialPageRoute`:

```dart
Navigator.of(context).push(
  KasyMaterialPageRoute(builder: (_) => const MyPage()),
);
```

## Transition kinds

| Kind | Description |
|------|-------------|
| `fade` | Crossfade (default push) |
| `fadeThrough` | Material fade-through |
| `sharedAxisScaled` | Depth / scale |
| `sharedAxisHorizontal` | Horizontal shared axis |
| `none` | No animation |

## What is NOT covered

- Dialogs (`showAppDialog`, `showGeneralDialog`)
- Bottom sheets (`showModalBottomSheet`)
- In-widget animations (`AnimatedSwitcher`, etc.)

## Fallback theme

[`universal_theme.dart`](../lib/core/theme/universal_theme.dart) uses `kasyPageTransitionsTheme` so any remaining `MaterialPageRoute` still fades consistently. Prefer `kasyTransitionPage` / `KasyMaterialPageRoute` for new code.