adaptive_router_behavior 0.0.1

A clean, lightweight, and type-safe routing library for Flutter that handles adaptive page transitions (Material/Cupertino) and stack tracking automatically.

adaptive_router_behavior

A lightweight, type-safe, and highly customizable routing and transition library for Flutter. It automatically adapts page transitions to match Cupertino (iOS) or Material (Android/other) styles based on the active platform, provides custom animation overrides, and monitors active routes dynamically with an observer and stack tracker.

Features

• 📱 Adaptive Page Transitions: Automatically uses CupertinoPageRoute on iOS/macOS (with native swipe-to-back support) and MaterialPageRoute on Android and other environments.
• 🎨 Custom Transition Animations: Support for custom transitions including fade, zoom, slideLeft, slideRight, slideUp, slideDown, and none with platform-appropriate animation curve models (easeInOutCubic for Cupertino, fastOutSlowIn for Material).
• 📜 Stack History & Logging: Automatic tracking of active routes via NavigationStack and AdaptiveRouterObserver with integrated console logging.
• ⚡ BuildContext Extensions: Convenient and clean navigation syntaxes (context.push(...), context.pop()).
• 🌐 Web-Safe Platform Checking: Designed to run safely on Web/Desktop configurations without throwing platform exceptions.

---

Installation

Add the library to your Flutter project's pubspec.yaml dependency section:

dependencies:
  flutter:
    sdk: flutter
  adaptive_router_behavior:
    git:
      url: https://github.com/yclkrt/adaptive_router_behavior.git
      ref: main

---

Quick Start

1. Configure the Router

Initialize settings and bind navigatorKey and navigatorObservers to your MaterialApp:

import 'package:flutter/material.dart';
import 'package:adaptive_router_behavior/adaptive_router_behavior.dart';

void main() {
  // Configure settings
  AdaptiveRouterBehavior.settings = const AdaptiveRouterSettings(
    enableLogging: true,                      // Enable navigation console logs
    platformStyle: AppPlatformStyle.adaptive, // Adapt transitions to target platform
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: AdaptiveRouterBehavior.navigatorKey,
      navigatorObservers: [AdaptiveRouterBehavior.observer],
      home: HomeRoute().build(context),
    );
  }
}

2. Define Your Routes

Create classes extending AppRoute to define screens type-safely. You can accept constructor arguments to pass values:

import 'package:flutter/material.dart';
import 'package:adaptive_router_behavior/adaptive_router_behavior.dart';

class HomeRoute extends AppRoute {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.push(DetailsRoute(itemId: '123')),
          child: const Text('Go to Details'),
        ),
      ),
    );
  }
}

class DetailsRoute extends AppRoute {
  final String itemId;

  DetailsRoute({required this.itemId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Details - $itemId')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.pop(),
          child: const Text('Back'),
        ),
      ),
    );
  }
}

---

Custom Transitions

To override native platform transitions, override the transitionType property on your AppRoute:

class FadeSettingsRoute extends AppRoute {
  @override
  Widget build(BuildContext context) => const SettingsScreen();

  @override
  TransitionType get transitionType => TransitionType.fade;

  @override
  Duration get transitionDuration => const Duration(milliseconds: 400);
}

Available transition types:

• TransitionType.native (default system transition)
• TransitionType.fade
• TransitionType.zoom
• TransitionType.slideLeft
• TransitionType.slideRight
• TransitionType.slideUp
• TransitionType.slideDown
• TransitionType.none

---

Advanced Usage

Navigation Without BuildContext

Navigate from BLoCs, controllers, or background services globally without requiring a context:

AdaptiveRouterBehavior.push(HomeRoute());

Checking Route Stack

Inspect the history log of active routes at runtime:

// Check active route settings
Route<dynamic>? activeRoute = AdaptiveRouterBehavior.stack.currentRoute;
print('Current route is: ${activeRoute?.settings.name}');

// Check whole stack length
int depth = AdaptiveRouterBehavior.stack.history.length;

---

License

This project is licensed under the MIT License - see the LICENSE file for details.