hq_picker 1.1.1

A stateful widget that allows users to pick media files (images, videos, audio, files) from their device.

1.1.1

Storage & Memory Optimization

• Automatic Temp File Cache Purging: Added PhotoManager.clearFileCache() inside HQPickerProcessor.processAssets() to automatically wipe obsolete temporary media file copies before processing new selections. Prevents temporary video files (500MB+) from accumulating indefinitely in app cache storage.
• Explicit Cache Purge API: Added HQPicker.clearCache() static API method allowing applications to manually purge picker media file caches on-demand (e.g. when clearing file selections).

1.1.0

Universal Native iOS Design & Aesthetic

• Universal Native iOS Aesthetic: Standardized Apple Human Interface Guidelines (HIG) design, CupertinoIcons, CupertinoAlertDialog, BouncingScrollPhysics, and translucent frosted glass blur (BackdropFilter) across both iOS and Android.
• Cupertino Iconography: Standardized default HQPickerIcons to use CupertinoIcons (camera_fill, videocam_fill, arrow_up_circle_fill, checkmark_alt, play_fill, doc_fill, chevron_down, xmark_circle_fill, chevron_back) across all platforms.
• iOS Cupertino Dialogs: Permission alerts, error popups, and media detail dialogs now utilize CupertinoAlertDialog and CupertinoDialogAction natively.

Ultra-Fast Performance & 0ms Instant Response

• 0ms Instant Selection Response: Isolated tile rebuilds via BlocSelector so tapping an item updates only that specific tile instantly (0ms), skipping re-evaluations across all other visible tiles.
• CustomScrollView & SliverGrid Viewport: Upgraded media asset grid from GridView.builder to CustomScrollView + SliverGrid with SliverChildBuilderDelegate for silky-smooth 120fps scrolling.
• Instant Album & Asset Loading: Optimized BLoC initialization to emit primary album assets immediately (~60ms) while fetching album cover thumbnails and counts asynchronously in the background.

Customization & Localization Features

• BoxFit Customization: Added previewFit and gridItemFit parameters to HQPickerConfig to control image fitting for top preview and grid tiles.
• Interactive Aspect-Ratio Fit Toggle: Added an interactive aspect ratio fit button to the preview panel allowing end-users to toggle between BoxFit.cover and BoxFit.contain.
• Custom Loading Widget Override: Made all progress indicators seamlessly fallback to custom user-supplied loadingWidget across all components.
• Localization Enhancements: All UI strings are retrieved from HQPickerLocalizations (including HQPickerLocalizations.ar() Arabic preset).

1.0.1

Performance & Improvements

• Optimized File Icon Lookups: Moved file icon and color lookup maps in getIconForFile() to module-level const maps, preventing them from being recreated for every file item.
• Immutable Extension Lists: Converted Telegram picker extension lists to const collections to prevent accidental mutation and reduce unnecessary allocations.
• Optimized Selected Asset Lookups: Added cached selectedAssetIdsSet and selectedAssetIndexById to provide O(1) selection and index lookups instead of repeatedly rebuilding sets or calling indexOf().
• Parallel Album Loading: Updated album loading in HQPickerBloc to load albums concurrently using Future.wait() instead of sequential processing.
• Shared Asset Visual Helpers: Added hq_picker_asset_visuals.dart to centralize GIF detection, duration formatting, and selection badge alignment logic shared across asset tiles.
• Reduced Instagram Picker Rebuilds: Added buildWhen filtering to prevent unnecessary rebuilds caused by unrelated picker state changes.
• Stable Grid Item Keys: Added stable keys to Instagram picker grid items for more predictable widget reuse during rebuilds and scrolling.
• Selection Badge Animation Fix: Fixed the AnimatedScale selection badge so its animation state actually changes instead of receiving the same value in both states.
• Telegram ScrollController Cleanup: Fixed ScrollController lifecycle handling in the Telegram album selector to prevent resource leaks.
• Removed Picker File Cache Cleanup: Removed PhotoManager.clearFileCache() calls from picker disposal to avoid unnecessary file-cache clearing during picker lifecycle.

Fixes

• File Extension Fix: Corrected the wbs extension to .wbs in the Telegram file extension list.
• Removed Unnecessary Async: Removed the unnecessary async modifier from getPublicDirectories().
• Added HQPickerConfig.copyWith(): Added copyWith() to HQPickerConfig for consistent and easier configuration updates without recreating the entire configuration object.

1.0.0

Added & Redesigned

• Redesigned Media Preview Dialog (HQMediaPreviewDialog): Overhauled full-screen image and video preview on long press with a modern glassmorphic top header, asset details chips (media type, resolution, duration), pinch-to-zoom interactive viewer, double-tap zoom gestures, and video indicator badge.
• Custom Preview Dialog Builder (previewDialogBuilder): Added HQAssetPreviewBuilder signature and previewDialogBuilder parameter to HQPickerConfig allowing complete customization of media asset preview dialogs.
• Custom Confirm Button Builder (confirmButtonBuilder): Added HQConfirmButtonBuilder signature and confirmButtonBuilder parameter to HQPickerConfig for full control over confirm/send button widgets.
• Custom Instagram AppBar Builder (appBarBuilder): Added HQAppBarBuilder signature and appBarBuilder parameter to HQPickerConfig for customizing the AppBar in Instagram shape.
• Interactive Instagram Album Dropdown Title: Updated Instagram shape AppBar title to display an interactive album selector dropdown menu button.
• Example App Updates: Updated example application to demonstrate custom preview, confirm button, and Instagram AppBar builders.

0.0.11

Added & Customizable

• Grid Layout Customization: Added gridCrossAxisCount, gridCrossAxisSpacing, gridMainAxisSpacing, gridChildAspectRatio, and gridItemBorderRadius.
• Selection Badge Visuals & Position: Added selectionStyle (number, checkMark, borderOnly), badgePosition (topRight, topLeft, bottomRight, bottomLeft), and enableSelectionAnimation.
• Video & File Constraints: Added minVideoDuration, maxVideoDuration, and minFileSize validation checks with automatic error notification.
• Full-Screen Preview & Video Behavior: Added enableFullScreenPreview modal dialog on long press, autoPlayVideoPreview, and muteVideoPreview.
• In-App Camera Settings: Added preferredCameraLens (back/front), cameraCaptureMode (all/photoOnly/videoOnly), and cameraOverlayBuilder.
• File & Document Views: Added fileViewMode (list vs grid), enableDocumentPreview, and customFileTypeIcons map.
• Gestures & Actions: Added doubleTapAction and longPressAction (none, select, preview, showInfo) with built-in asset information modal dialog.
• Custom Send Bar & FAB Animation: Added bottomSendBarBuilder and sendButtonAnimation toggle for send action floating action button.
• Custom Permission Dialog: Added permissionDialogBuilder to override default system permission dialogs.
• Album Filtering & Headers: Added albumFilter predicate, custom headerBuilder, and callbacks (onMaxCountReached, onAssetTap, onAlbumChanged).
• Interactive Customization Showcase: Added interactive settings sheet in example app and showcase web page.

0.0.10

Removed & Fixed

• Removed Image Cropping Dependency: Completely removed image_cropper package and enableCropping configuration to eliminate native cropping activity bloat and boost overall picking performance.
• Fixed Parent Route Exit Bug: Fixed showDialog dismiss logic in HQPickerProcessor.processAssets by passing explicit dialogContext, preventing unintended popping of parent screen navigation routes.
• Main Thread Asset Resolution: Streamlined AssetEntity file resolution on main thread to avoid raw isolate platform channel exceptions.

0.0.9

Added & Improved

• iOS Platform Support & Permissions: Added explicit platform declarations (android and ios) to pubspec.yaml.
• iOS Photo Library Save Permission: Added NSPhotoLibraryAddUsageDescription to example Info.plist to prevent app crash when saving captured camera photos on iOS.
• iOS Permission Optimization: Optimized HQPickerMediaServices.requestPermissions to directly check and request Permission.photos on iOS.
• iOS Setup Documentation: Added comprehensive iOS configuration guide to README.md detailing required Info.plist keys (NSPhotoLibraryUsageDescription, NSPhotoLibraryAddUsageDescription, NSCameraUsageDescription, NSMicrophoneUsageDescription) and Podfile deployment target instructions.

0.0.8

Changed & Improved

• Showcase & Visual Assets: Updated showcase page, README preview screenshots, and demo video assets.
• Monochrome Dark Theme: Aligned default example and showcase color scheme to Material 3 Monochrome Dark.
• Instagram Picker Toolbar Layout: Positioned album selector dropdown alongside camera action controls on the toolbar row below the preview image.
• Telegram Sheet Refinements: Refined DraggableScrollableSheet snap points, media-only grid mode, and folder navigation popup overlay.

0.0.7

Fixed

• Large File OOM Crash Prevention: Updated HQPickerProcessor._resolveAssetFile to prioritize asset.originFile before fallback to asset.file. This resolves original file paths directly on disk without duplicating large media files (500MB - 1GB+) into cache memory, eliminating Out-Of-Memory (OOM) process crashes.
• Exception Guards: Added safe try/catch exception wrappers around openFile and getDirectoryPath in HQPickerProcessor.pickDocument and pickDirectory.

0.0.6

Fixed & Improved

• Offloaded media asset file resolution (AssetEntity.file) to background isolates using IsolateServices.run in HQPickerProcessor. This eliminates UI thread freezing when picking large video files (up to 1GB+) or high-resolution images.
• Added getFile() asynchronous helper method to HQPickerResult to safely resolve files in a background isolate without blocking the UI main thread.
• Offloaded image compression (FlutterImageCompress) in HQPickerMediaEditor to background isolates.
• Offloaded recursive file system scanning in HQPickerMediaServices.fetchFilesByExtensions to background isolates.
• Ultra-Smooth 60/120fps Grid Scrolling: Added buildWhen state filtering to prevent full GridView rebuilds on scroll drag events, and configured scrollCacheExtent: const ScrollCacheExtent.pixels(1500.0) for stutter-free thumbnail rendering.
• Telegram Bottom Sheet Drag-to-Close: Configured DraggableScrollableSheet with minChildSize: 0.0, shouldCloseOnMinExtent: true, snap: true, snapSizes: [0.55, 1.0], and DraggableScrollableNotification listener for fluid swipe-down dismissal.
• Telegram Sheet Header Layout: Fixed top row asset overlap under the album selector app bar by adding dynamic top padding reacting to scroll position.
• Instant Selection Response (0ms delay): Single state emission per tap combined with O(1) set lookup (selectedAssetIdsSet.contains(id)).
• System Back Gesture Support: Wrapped Telegram sheet overlay in PopScope(canPop: false) so pressing system back closes the bottom sheet first.
• Tactile Haptic Feedback: Integrated HapticFeedback.selectionClick(), lightImpact(), and vibrate() for media selection, album toggles, and max-count limits.
• Interactive Zoom Preview: Wrapped large top preview image in Instagram picker in InteractiveViewer for 1.0x to 4.0x pinch-to-zoom inspection.
• Auto Memory Cleanup: Added PhotoManager.clearFileCache() call on picker disposal to automatically delete temporary thumbnail files.
• Custom Empty Widget: Added emptyWidget field to HQPickerConfig for custom empty state placeholders.
• GIF Asset Badges: Display "GIF" label badges on animated GIF media items in grid cells.
• Customizable Scroll Physics: Added scrollPhysics field to HQPickerConfig allowing custom grid scroll physics (BouncingScrollPhysics, ClampingScrollPhysics, etc.).
• Selected Items Counter: Floating send button in Telegram sheet dynamically displays selected item count.
• Maximum File Size Limit: Added maxFileSize property to HQPickerConfig to set file size limits with automatic haptic warning feedback.
• Gallery Asset Sort Order: Added sortOrder (HQPickerSortOrder.newestFirst or oldestFirst) to HQPickerConfig.
• Custom Grid Item Tile Builder: Added assetItemBuilder callback (HQAssetItemBuilder) to HQPickerConfig to fully customize asset cell overlays.

0.0.5

Fixed

• Telegram-style picker (HQPicker.telegram): selected media no longer gets cleared when switching albums. Users can now select items across multiple albums and have them all included when confirming, matching Telegram's native picker behavior.

0.0.4

✨ New Features

Full Text-Style Theming via HQPickerTheme

• Every Text widget in the picker now reads its style from HQPickerTheme — no more hardcoded inline TextStyle.
• New named style properties: albumNameTextStyle, albumCountTextStyle, confirmButtonTextStyle, badgeTextStyle, videoDurationTextStyle, emptyListTextStyle, dialogTitleTextStyle, dialogContentTextStyle, dialogCancelTextStyle, dialogConfirmTextStyle, snackBarTextStyle.
• Each property has a resolved* getter that falls back to a sensible colour-based default if not provided.

Localization — permissionRequired string

• Added permissionRequired field to HQPickerLocalizations (default: 'Permission Required', Arabic: 'مطلوب إذن').
• The permission dialog title now reads from config.localizations.permissionRequired instead of a hardcoded string.

Custom Loading Widget

• Added loadingWidget to HQPickerConfig — shown as an overlay while assets are being processed (cropped / compressed).
• Defaults to Center(child: CircularProgressIndicator()).

Conditional Camera Buttons in Instagram Picker

• The Instagram picker toolbar now shows camera buttons only for the active requestType:
  • image → photo camera button only.
  • video → video camera button only.
  • all → both buttons.
• Added cameraVideo icon to HQPickerIcons (default: Icons.videocam) for the video camera button.
• Multi-select toggle icon changed from add_a_photo (looked like a camera) to check_box / check_box_outline_blank.

🏗️ Architecture

File Split — hq_picker.dart is now a clean facade

• Extracted HQInstagramPicker widget + _HQInstagramPickerState → src/instagram/hq_instagram_picker.dart.
• Extracted grid-cell widget → src/instagram/hq_instagram_asset_item.dart (HQAssetItem).
• Extracted processAssets, pickDocument, pickDirectory → src/core/hq_picker_processor.dart (HQPickerProcessor).
• hq_picker.dart is now a pure static-API facade (~220 lines) — no widget code, no inline logic.
• Removed src/file_picker_service.dart — logic inlined into HQPickerProcessor.

🔧 Fixes & Improvements

• HQPicker.title is now Widget? (nullable); when null, defaults to config.localizations.gallery styled with resolvedAlbumNameTextStyle.
• Album selector bottom-sheet background uses config.theme.backgroundDropDownColor instead of a hardcoded colour.

0.0.3

🔧 Android Build Compatibility

• Gradle wrapper upgraded from 8.12 → 8.14.1 (satisfies Flutter's upcoming minimum requirement).
• Android Gradle Plugin (AGP) upgraded from 8.7.3 → 8.11.1 — resolves checkDebugAarMetadata build failures caused by androidx.activity, androidx.core, and androidx.navigationevent dependencies requiring AGP ≥ 8.9.1.
• Kotlin Gradle Plugin (KGP) upgraded from 2.1.0 → 2.2.20.
• JVM target mismatch fix: Added a targeted subprojects block in root build.gradle.kts that enforces consistent Java/Kotlin JVM target (17) for photo_manager, resolving Inconsistent JVM Target Compatibility build errors.
• App JVM target updated from VERSION_11 → VERSION_17 in app/build.gradle.kts.
• UCropActivity declaration added to AndroidManifest.xml — fixes crash when using image_cropper (ActivityNotFoundException: UCropActivity).
• android:enableOnBackInvokedCallback="true" added to AndroidManifest.xml — suppresses predictive back gesture warning.

🗂️ Example App Overhaul

• Replaced the single-screen example with a comprehensive 3-tab showcase:
  • Tab 1 — Shapes: Cards for all 8 HQPickerShape variants (instagram, custom, bottomSheet, scaffoldBottomSheet, bottomSheetImageSelector, telegram, document, directory).
  • Tab 2 — Types: Cards demonstrating pickImage, pickVideo, pickDocument, pickDirectory, and pick with all HQPickerRequestType values and config combinations (crop, compress).
  • Tab 3 — Telegram Inline: Inline HQPickerTelegramMediaPickers widget with toggle button, displaying picked assets and files.
• Results panel shown inline under the grid with thumbnail previews and type icons.

0.0.2

• Unified HQPickerShape API: Added HQPickerShape enum unifying all 8 picker UI shapes (instagram, custom, bottomSheet, scaffoldBottomSheet, bottomSheetImageSelector, telegram, document, directory).
• Shape-Centric Launchers: Added HQPicker.pick(...), HQPickerFilePicker.pick(...), pickImage, pickVideo, pickDocument, and pickDirectory static methods across HQPicker and HQPickerFilePicker.
• Telegram Modal Launcher: Added static HQPicker.telegram(...) modal presenter returning Future<List<HQPickerResult>>.
• Flexible Results: Updated HQPickerResult to support raw files without requiring an AssetEntity.

0.0.1

• Initial Release of hq_picker package!
• BLoC Architecture: Entire package built with flutter_bloc and equatable ensuring high performance, 60fps scrolling, and zero setState sluggishness.
• Pagination (Lazy-Loading): Seamlessly loads large galleries (images/videos) in batches to prevent memory leaks and freezing.
• Telegram-Style Picker: Draggable bottom sheet with tabs for Gallery, Audio, and Files with smooth UI transitions.
• Instagram-Style Picker: Full-page preview with grid selection and a built-in camera functionality.
• Custom Pickers: HQPickerCustomPicker, HQPickerBottomSheets, and HQPickerScaffoldBottomSheet for varied project requirements.
• File System Access: Natively fetches and filters Audio (.mp3, .wav, etc.) and general Device Files natively for both Android and iOS.
• Cropping & Compression: Built-in support for editing images with adjustable quality settings.
• Localization: Full support for Multiple Languages (English, Arabic, etc.) via Dependency Injection.