v10: Improved multi-store usage support

CHANGELOG.md

@@ -18,19 +18,57 @@ Many thanks to my sponsors, no matter how much or how little they donated. Spons
 
 # Changelog
 
+## [10.0.0] - "Better Browsing" - 2024/XX/XX
+
+This update builds on v9 to fully embrace the new many-to-many relationship between tiles and stores, which allows for more flexibility when constructing the `FMTCTileProvider`.  
+This allows a new paradigm to be used: stores may now be treated as bulk downloaded regions, and all the regions/stores can be used at once - no more switching between them. This allows huge amounts of flexibility and a better UX in a complex application. Additionally, each store may now have its own `BrowseStoreStrategy` when browsing, which allows more flexibility: for example, stores may now contain more than one URL template/source, but control is retained.
+
+Additionally, vector tiles are now supported in theory, as the internal caching/retrieval logic of the specialised `ImageProvider` has been exposed, although it is out of scope to fully implement support for it.
+
+* Improvements to the browse caching logic and customizability
+  * Added support for using multiple stores simultaneously in the `FMTCTileProvider` (through the `FMTCTileProvider.allStores` & `FMTCTileProvider.multipleStores` constructors)
+  * Added `FMTCTileProvider.getBytes` method to expose internal caching mechanisms for external use
+  * Added `BrowseStoreStrategy` for increased control over caching behaviour
+  * Added 'tile loading interceptor' feature (`FMTCTileProvider.tileLoadingInterceptor`) to track (eg. for debugging and logging) the internal tile loading mechanisms
+  * Added toggle for hit/miss stat recording, to improve performance where these statistics are never read
+  * Replaced `FMTCTileProviderSettings.maxStoreLength` with a `maxLength` property on each store individually
+  * Replaced `CacheBehavior` with `BrowseLoadingStrategy`
+  * Replaced `FMTCBrowsingErrorHandler` with `BrowsingExceptionHandler`, which may now return bytes to be displayed instead of (re)throwing exception
+  * Replaced `obscureQueryParams` with more flexible `urlTransformer` (and static `FMTCTileProvider.urlTransformerOmitKeyValues` utility method to provide old behaviour with more customizability) - also applies to bulk downloading in `StoreDownload.startForeground`
+  * Removed `FMTCTileProviderSettings` & absorbed properties directly into `FMTCTileProvider`
+  * Performance of the internal tile image provider has been significantly improved when fetching images from the network URL  
+    > There was a significant time loss due to attempting to handle the network request response as a stream of incoming bytes, which allowed for `chunkEvents` to be reported back to Flutter (allowing it to get progress updates on the state of the tile), but meant the bytes had to be collected and built manually. Removing this functionality allows the network requests to use more streamlined 'package:http' methods, which does not expose a stream of incoming bytes, meaning that bytes no longer have to be treated manually. This can save hundreds of milliseconds on tile loading - a significant time save of potentially up to ~50% in some cases!
+
+* Improvements, additions, and removals for bulk downloadable `BaseRegion`s
+  * Added `MultiRegion`, which contains multiple other `BaseRegion`s
+  * Improved speed (by massive amounts) and accuracy & reduced memory consumption of `CircleRegion`'s tile generation & counting algorithm
+  * Deprecated `BaseRegion.(maybe)When` - this is easy to perform using a standard pattern-matched switch
+
+* Changes to bulk downloading
+  * `DownloadProgress.latestTileEvent` is now nullable
+
+* Exporting stores is now more stable, and has improved documentation  
+  The method now works in a dedicated temporary environment and attempts to perform two different strategies to move/copy-and-delete the result to the specified directory at the end before failing. Improved documentation covers the potential pitfalls of permissions and now recommends exporting to an app directory, then using the system share functionality on some devices. It now also returns the number of exported tiles.
+
+* Removed deprecated remnants from v9.*
+
+* Other generic improvements (performance, stability, and documentation)
+
+* Brand new example app to (partially!) showcase the new levels of flexibility and customizability
+
 ## [9.1.3] - 2024/08/19
 
 * Fixed bug where any operation that attempted to delete tiles fatally crashed on some iOS devices  
   This appears to be an [ObjectBox issue](https://github.com/objectbox/objectbox-dart/issues/654) where streaming the results of a database query caused the crash. Instead, FMTC now uses a custom chunking system to avoid streaming and also avoid loading potentially many tiles into memory.
 
 ## [9.1.2] - 2024/08/07
 
-* Fixed compilation on web platforms: FMTC now internally overrides the `FMTCObjectBoxBackend` and becomes a no-op
+* Fixed compilation on web platforms: FMTC now internally overrides the `FMTCObjectBoxBackend` and becomes a no-op on non-FFI platforms
 * Minor documentation improvements
 
 ## [9.1.1] - 2024/07/16
 
-* Fixed bug where errors within the import functionality would not be catchable by the original invoker
+* Fixed bug where errors within the import functionality would not always be catchable by the original invoker
 * Minor other improvements
 
 ## [9.1.0] - 2024/05/27

CONTRIBUTING.md

@@ -2,22 +2,23 @@
 
 ## Reporting A Bug
 
-FMTC is a large, platform-dependent package, and there's only one person running manual tests on it before releases, so there's a decent chance that a bug you've found is actually a bug. Reporting it is always appreciated!
+I try to test FMTC on as many platforms as I have access to, using a combination of automated tests and manual tests through the example application. However, I only have access to Android and Windows devices. Due to the number of platform-dependent plugins this package uses, bugs are often only present on one platform, which is often iOS. However, they can of course occur on any platform if I've missed one. Reporting any bugs you find is always appreciated!
 
 Before reporting a bug, please:
 
 * Check if there is already an open or closed issue that is similar to yours
-* Ensure that your Flutter environment is correctly installed & set-up
-* Ensure that this package, 'flutter_map', and any modules are correctly installed & set-up
+* Ensure that Flutter, this package, 'flutter_map', and any modules are correctly installed & set-up
+* Follow the bug reporting issue template
 
 ## Contributing Code
 
 Contributors are always welcome, and support is always greatly appreciated! Before opening a Pull Request, however, please open a feature request or bug report to link the PR to.
 
+Please note that all contributions may be dually licensed under an alternative proprietary license on a case-by-case basis, which grants no extra rights to contributors.
+
 When submitting code, please:
 
-* Keep code concise and in a similar style to surrounding code
-* Document all public APIs in detail and with correct grammar
+* Document all new public APIs
 * Use the included linting rules
 * Update the example application to appropriately consume any public API changes
 * Avoid incrementing this package's version number or changelog

example/.gitignore

@@ -1,3 +1,6 @@
+# Custom
+old_lib/
+
 # Miscellaneous
 *.class
 *.log

example/.metadata

@@ -4,7 +4,7 @@
 # This file should be version controlled and should not be manually edited.
 
 version:
-  revision: "29babcb32a591b9e5be8c6a6075d4fe605d46ad3"
+  revision: "7c6b7e9ca485f7eaaed913c6bb50f4be6da47e30"
   channel: "beta"
 
 project_type: app
@@ -13,11 +13,11 @@ project_type: app
 migration:
   platforms:
     - platform: root
-      create_revision: 29babcb32a591b9e5be8c6a6075d4fe605d46ad3
-      base_revision: 29babcb32a591b9e5be8c6a6075d4fe605d46ad3
+      create_revision: 7c6b7e9ca485f7eaaed913c6bb50f4be6da47e30
+      base_revision: 7c6b7e9ca485f7eaaed913c6bb50f4be6da47e30
     - platform: android
-      create_revision: 29babcb32a591b9e5be8c6a6075d4fe605d46ad3
-      base_revision: 29babcb32a591b9e5be8c6a6075d4fe605d46ad3
+      create_revision: 7c6b7e9ca485f7eaaed913c6bb50f4be6da47e30
+      base_revision: 7c6b7e9ca485f7eaaed913c6bb50f4be6da47e30
 
   # User provided section
 

example/devtools_options.yaml

@@ -0,0 +1,3 @@
+description: This file stores settings for Dart & Flutter DevTools.
+documentation: https://docs.flutter.dev/tools/devtools/extensions#configure-extension-enablement-states
+extensions:

example/lib/main.dart

@@ -1,25 +1,24 @@
 import 'package:flutter/material.dart';
-import 'package:flutter/services.dart';
 import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';
 import 'package:google_fonts/google_fonts.dart';
 import 'package:provider/provider.dart';
+import 'package:shared_preferences/shared_preferences.dart';
 
-import 'screens/configure_download/state/configure_download_provider.dart';
-import 'screens/initialisation_error/initialisation_error.dart';
-import 'screens/main/main.dart';
-import 'screens/main/pages/downloading/state/downloading_provider.dart';
-import 'screens/main/pages/map/state/map_provider.dart';
-import 'screens/main/pages/region_selection/state/region_selection_provider.dart';
-import 'shared/state/general_provider.dart';
+import 'src/screens/import/import.dart';
+import 'src/screens/initialisation_error/initialisation_error.dart';
+import 'src/screens/main/main.dart';
+import 'src/screens/main/secondary_view/contents/home/components/stores_list/state/export_selection_provider.dart';
+import 'src/screens/store_editor/store_editor.dart';
+import 'src/shared/misc/shared_preferences.dart';
+import 'src/shared/state/download_configuration_provider.dart';
+import 'src/shared/state/download_provider.dart';
+import 'src/shared/state/general_provider.dart';
+import 'src/shared/state/region_selection_provider.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  SystemChrome.setSystemUIOverlayStyle(
-    const SystemUiOverlayStyle(
-      statusBarColor: Colors.transparent,
-      statusBarIconBrightness: Brightness.dark,
-    ),
-  );
+
+  sharedPrefs = await SharedPreferences.getInstance();
 
   Object? initErr;
   try {
@@ -38,18 +37,45 @@ class _AppContainer extends StatelessWidget {
 
   final Object? initialisationError;
 
+  static final _routes = <String,
+      ({
+    Widget Function(BuildContext)? std,
+    PageRoute Function(BuildContext, RouteSettings)? custom,
+  })>{
+    MainScreen.route: (
+      std: (BuildContext context) => const MainScreen(),
+      custom: null,
+    ),
+    StoreEditorPopup.route: (
+      std: null,
+      custom: (context, settings) => MaterialPageRoute(
+            builder: (context) => const StoreEditorPopup(),
+            settings: settings,
+            fullscreenDialog: true,
+          ),
+    ),
+    ImportPopup.route: (
+      std: null,
+      custom: (context, settings) => MaterialPageRoute(
+            builder: (context) => const ImportPopup(),
+            settings: settings,
+            fullscreenDialog: true,
+          ),
+    ),
+  };
+
   @override
   Widget build(BuildContext context) {
     final themeData = ThemeData(
-      brightness: Brightness.dark,
+      brightness: Brightness.light,
       useMaterial3: true,
-      textTheme: GoogleFonts.ubuntuTextTheme(ThemeData.dark().textTheme),
-      colorSchemeSeed: Colors.red,
+      textTheme: GoogleFonts.ubuntuTextTheme(ThemeData.light().textTheme),
+      colorSchemeSeed: Colors.teal,
       switchTheme: SwitchThemeData(
         thumbIcon: WidgetStateProperty.resolveWith(
-          (states) => Icon(
-            states.contains(WidgetState.selected) ? Icons.check : Icons.close,
-          ),
+          (states) => states.contains(WidgetState.selected)
+              ? const Icon(Icons.check)
+              : null,
         ),
       ),
     );
@@ -68,26 +94,29 @@ class _AppContainer extends StatelessWidget {
           create: (_) => GeneralProvider(),
         ),
         ChangeNotifierProvider(
-          create: (_) => MapProvider(),
-          lazy: true,
+          create: (_) => ExportSelectionProvider(),
         ),
         ChangeNotifierProvider(
           create: (_) => RegionSelectionProvider(),
           lazy: true,
         ),
         ChangeNotifierProvider(
-          create: (_) => ConfigureDownloadProvider(),
-          lazy: true,
+          create: (_) => DownloadConfigurationProvider(),
         ),
         ChangeNotifierProvider(
           create: (_) => DownloadingProvider(),
-          lazy: true,
         ),
       ],
       child: MaterialApp(
         title: 'FMTC Demo',
+        restorationScopeId: 'FMTC Demo',
         theme: themeData,
-        home: const MainScreen(),
+        initialRoute: MainScreen.route,
+        onGenerateRoute: (settings) {
+          final route = _routes[settings.name]!;
+          if (route.custom != null) return route.custom!(context, settings);
+          return MaterialPageRoute(builder: route.std!, settings: settings);
+        },
       ),
     );
   }