feat: Add support for Android 14 granular media permissions

[amlwin]

🚀 Android 14 (API 34) Granular Media Permissions Support

📋 Summary

This PR adds full support for Android 14's new granular media permissions, resolving runtime permission failures and providing an excellent user experience with the new permission model.

🐛 Problem Solved

Issue: Users on Android 14 experience runtime permission failures where the image picker cannot access photos, even when permissions appear to be granted.

Root Cause: Android 14 introduced granular media permissions where users can choose between:

• "Select photos and videos" → Grants READ_MEDIA_VISUAL_USER_SELECTED (partial access)
• "Allow access to all media" → Grants READ_MEDIA_IMAGES + READ_MEDIA_VIDEO (full access)

The library was only checking for full access permissions, causing failures when users chose partial access.

✨ What's New

🔐 Smart Permission Handling

• Automatic Detection: Intelligently detects partial vs full media access
• Graceful Degradation: App works perfectly with limited access
• Permission Upgrade Flow: Non-intrusive prompts to upgrade from partial to full access
• Backward Compatibility: Zero breaking changes, works seamlessly on older Android versions

🎛️ Developer-Friendly Configuration

// Easy configuration options
val config = ImagePickerConfig()
    .enableGranularPermissions()        // Best UX (default)
    .requireFullMediaAccess()           // Legacy behavior  
    .minimalPermissionUI()              // No upgrade prompts
    .granularPermissions {              // Custom configuration
        showUpgradePrompt = true
        allowPartialAccess = true
        partialAccessMessage = "Custom message"
    }

📱 Enhanced User Experience

• Users can start with limited access and upgrade when needed
• Clear messaging about permission levels
• Smooth upgrade flow without app restart
• Respects user privacy choices

🔧 Technical Changes

New Files Added

• MediaPermissionHelper.kt - Centralized permission logic and state detection
• GranularPermissionConfig.kt - Configuration class for permission behavior
• docs/android_14_migration.md - Comprehensive migration guide

Files Modified

• AndroidManifest.xml - Added READ_MEDIA_VISUAL_USER_SELECTED permission
• ImagePickerFragment.kt - Enhanced with granular permission logic
• DefaultImageFileLoader.kt - Added partial access support
• ImagePickerConfig.kt - New configuration options and extension functions
• strings.xml - New permission-related messages
• MainActivity.kt (sample) - Updated with Android 14 examples
• README.md - Added Android 14 information
• CHANGELOG.md - Documented new features

Key Technical Features

• Permission State Detection: Automatically detects FULL_ACCESS, PARTIAL_ACCESS, NO_ACCESS, and LEGACY_ACCESS states
• Smart File Loading: Handles MediaStore queries for both full and partial access scenarios
• Security Exception Handling: Graceful handling when partial access limits queries
• Upgrade Flow: Seamless permission upgrade without app restart

🧪 Testing

Tested Scenarios

• ✅ Fresh install on Android 14 with both permission choices
• ✅ Permission upgrade flow from partial to full access
• ✅ Backward compatibility on Android 13 and below
• ✅ Permission revocation and re-granting
• ✅ App backgrounding during permission flows

Test Commands

# Grant partial access for testing
adb shell pm grant com.yourapp.package android.permission.READ_MEDIA_VISUAL_USER_SELECTED

# Grant full access for testing  
adb shell pm grant com.yourapp.package android.permission.READ_MEDIA_IMAGES
adb shell pm grant com.yourapp.package android.permission.READ_MEDIA_VIDEO

# Revoke permissions for testing
adb shell pm revoke com.yourapp.package android.permission.READ_MEDIA_IMAGES

📖 Documentation

New Documentation

• Complete Migration Guide: Step-by-step guide for Android 14 support
• Configuration Examples: Multiple configuration patterns for different use cases
• Testing Guide: How to test both permission flows
• Troubleshooting: Common issues and solutions

Updated Documentation

• README: Added Android 14 support section
• CHANGELOG: Detailed feature documentation
• Sample App: Updated with granular permission examples

🔄 Backward Compatibility

100% Backward Compatible - No breaking changes:

• ✅ Existing code continues to work without modifications
• ✅ Android 13 and below work exactly as before
• ✅ All existing APIs remain unchanged
• ✅ Graceful fallback for older Android versions
• ✅ No new required dependencies

🎯 Migration Path

For Existing Users (Zero Changes Required)

// This continues to work exactly as before
val launcher = registerImagePicker { images ->
    // handle images
}
launcher.launch(ImagePickerConfig())

For New Android 14 Features (Optional)

// Enable the best Android 14 experience
val config = ImagePickerConfig()
    .enableGranularPermissions()
launcher.launch(config)

📊 Impact

Before This PR

• ❌ Runtime failures on Android 14
• ❌ Poor user experience with permission errors
• ❌ No support for partial media access

After This PR

• ✅ Seamless Android 14 support
• ✅ Excellent user experience with granular permissions
• ✅ Smart permission upgrade flows
• ✅ Full backward compatibility
• ✅ Comprehensive documentation

🚀 Benefits

1. Fixes Critical Issue: Resolves runtime permission failures on Android 14
2. Future-Proof: Ready for Android's privacy-first direction
3. User-Friendly: Respects user privacy choices while providing upgrade paths
4. Developer-Friendly: Easy configuration with sensible defaults
5. Zero Migration Cost: Existing code works without changes

📝 Checklist

• [x] Added Android 14 permission support
• [x] Implemented permission upgrade flow
• [x] Added comprehensive configuration options
• [x] Updated documentation and examples
• [x] Maintained 100% backward compatibility
• [x] Added proper error handling
• [x] Updated sample app
• [x] Added migration guide
• [x] Updated CHANGELOG

🔗 Related Issues

Fixes runtime permission failures on Android 14 devices where users experience image loading issues despite granting permissions.

---

This PR ensures your Android image picker library provides an excellent experience on Android 14 while maintaining full compatibility with existing implementations.