Adaptive Image Loader 🖼️

A high-performance, drop-in replacement for Image.network that automatically loads images from Google Drive (Edge CDN), Dropbox, GitHub, GitLab, Box, OneDrive, and public image URLs, with disk caching, on-the-fly server-side resizing, and programmatic cache eviction.

No more broken preview links, manual URL conversions, or rate-limit walls.

---

✨ Key Features

• ✅ Drop-in replacement for Image.network with full parameter parity.
• ⚡ Google Edge CDN Acceleration: Automatically resolves Google Drive links to Google's Edge CDN endpoint (https://lh3.googleusercontent.com/d/{FILE_ID}) for 0 HTTP redirects and instant TTFB.
• 📐 On-The-Fly Google CDN Resizing: Pass size: 400 or driveImageSize: 800 to downscale huge images directly on Google's Edge servers, saving up to 95% bandwidth and memory.
• 🌐 Multi-Cloud & Git Provider Support:
  • Google Drive: /file/d/, open?id=, uc?id=, thumbnail?id=, docs.google.com
  • Dropbox: Share links auto-converted to direct streams (?dl=1)
  • GitHub: github.com/.../blob/... $\to$ raw.githubusercontent.com/...
  • GitLab: gitlab.com/.../blob/... $\to$ gitlab.com/.../raw/...
  • Box.com: app.box.com/s/... $\to$ app.box.com/shared/static/...
  • Microsoft OneDrive: onedrive.live.com & 1drv.ms links
• 🧹 Programmatic Cache Eviction: AdaptiveImage.evict(url) to instantly clear images from both memory and disk caches.
• 🚀 Optional Image Caching: Powered by cached_network_image and flutter_cache_manager.
• 🎨 Enhanced Transitions & Styling: Built-in placeholderColor, fadeInDuration, fadeInCurve, headers, colorBlendMode, and memCacheWidth/Height.
• 💙 Null-safe & Flutter 3.x+ ready.

---

📦 Installation

Add to your pubspec.yaml:

dependencies:
  adaptive_image_loader: ^1.0.3

---

🚀 Quick Usage

1. Universal Auto-Detection (Recommended)

Automatically detects and resolves any supported provider URL:

AdaptiveImage.image(
  'https://drive.google.com/file/d/FILE_ID/view',
  width: 300,
  height: 200,
  useCache: true,
)

2. Google Drive with Server-Side CDN Resizing

Downscale a 12MB raw photo to 400px directly on Google's Edge CDN:

AdaptiveImage.driveImage(
  'https://drive.google.com/file/d/FILE_ID/view',
  size: 400, // Transforms to https://lh3.googleusercontent.com/d/{ID}=s400
  width: 300,
  height: 200,
  placeholderColor: Colors.grey.shade200,
)

3. GitHub & GitLab Repository Images

Load images directly from repository blob URLs:

AdaptiveImage.gitHubImage(
  'https://github.com/flutter/flutter/blob/master/packages/flutter/assets/logo.png',
  width: 200,
  height: 100,
)

4. Background Images (CircleAvatar / DecorationImage)

Use AdaptiveImageProvider wherever an ImageProvider is required:

CircleAvatar(
  radius: 50,
  backgroundImage: AdaptiveImageProvider(
    'https://drive.google.com/file/d/FILE_ID/view',
    driveImageSize: 300,
    useCache: true,
  ),
)

5. Programmatic Cache Eviction

Force-refresh an image when a user updates their profile picture:

await AdaptiveImage.evict('https://drive.google.com/file/d/FILE_ID/view');

---

🛠️ Complete Example

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Adaptive Image Loader Example')),
        body: ListView(
          padding: const EdgeInsets.all(16),
          children: [
            // Google Drive with CDN resizing
            AdaptiveImage.driveImage(
              'https://drive.google.com/file/d/FILE_ID/view',
              size: 400,
              width: 300,
              height: 200,
              useCache: true,
            ),
            const SizedBox(height: 16),

            // GitHub raw image
            AdaptiveImage.gitHubImage(
              'https://github.com/user/repo/blob/main/logo.png',
              width: 300,
              height: 150,
            ),
            const SizedBox(height: 16),

            // Background image with provider
            const CircleAvatar(
              radius: 50,
              backgroundImage: AdaptiveImageProvider(
                'https://picsum.photos/200',
              ),
            ),
          ],
        ),
      ),
    );
  }
}

---

🙏 Acknowledgements

• cached_network_image
• flutter_cache_manager