feat: add compass plugin (#23)

* add compass plugin

* add cupertino compass

* Update pubspec.yaml

* add compass rotation animation

* update compass design

* update docs and add screenshot

* update package description

* rename image directory

* use hosted image url

* fix html tag in md

* rename ci job

* add tests

.github/workflows/on-commit-main.yml

@@ -58,6 +58,7 @@ jobs:
           path: example/build/app/outputs/flutter-apk/app-release.apk
   build-web:
     runs-on: ubuntu-latest
+    name: Build Web
     needs: [ test ]
     if: github.repository == 'josxha/flutter_map_plugins'
     defaults:

.github/workflows/on-pull-request.yml

@@ -58,6 +58,7 @@ jobs:
           path: example/build/app/outputs/flutter-apk/app-release.apk
   build-web:
     runs-on: ubuntu-latest
+    name: Build Web
     needs: [ test ]
     if: github.repository == 'josxha/flutter_map_plugins'
     defaults:

README.md

@@ -33,6 +33,15 @@ storage backend you would possibly want.
   and flutter_map.
 - Support for tile cancellation
 
+### [flutter_map_compass](https://pub.dev/packages/flutter_map_compass)
+
+[![Pub Version](https://img.shields.io/pub/v/flutter_map_compass)](https://pub.dev/packages/flutter_map_compass)
+[![likes](https://img.shields.io/pub/likes/flutter_map_compass?logo=flutter)](https://pub.dev/packages/flutter_map_compass)
+[![Pub Popularity](https://img.shields.io/pub/popularity/flutter_map_compass)](https://pub.dev/packages/flutter_map_compass)
+
+A compass for flutter_map that indicates the map rotation. It rotates the map
+back to north on top when clicked.
+
 ### [flutter_map_pmtiles](https://pub.dev/packages/flutter_map_pmtiles)
 
 [![Pub Version](https://img.shields.io/pub/v/flutter_map_pmtiles)](https://pub.dev/packages/flutter_map_pmtiles)

example/lib/flutter_map_compass/page.dart

@@ -0,0 +1,61 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_map/flutter_map.dart';
+import 'package:flutter_map_compass/flutter_map_compass.dart';
+import 'package:latlong2/latlong.dart';
+
+class FlutterMapCompassPage extends StatefulWidget {
+  const FlutterMapCompassPage({super.key});
+
+  @override
+  State<FlutterMapCompassPage> createState() => _FlutterMapCompassPageState();
+}
+
+class _FlutterMapCompassPageState extends State<FlutterMapCompassPage> {
+  final _mapController = MapController();
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        backgroundColor: Colors.white,
+        title: const Text('flutter_map_compass'),
+      ),
+      floatingActionButton: Column(
+        mainAxisAlignment: MainAxisAlignment.end,
+        children: [
+          FloatingActionButton.extended(
+            heroTag: 'rotateLeft',
+            label: const Text('Rotate left'),
+            onPressed: () => rotateMap(-90),
+            icon: const Icon(Icons.rotate_left),
+          ),
+          const SizedBox(height: 16),
+          FloatingActionButton.extended(
+            heroTag: 'rotateRight',
+            label: const Text('Rotate right'),
+            onPressed: () => rotateMap(90),
+            icon: const Icon(Icons.rotate_right),
+          ),
+        ],
+      ),
+      body: FlutterMap(
+        mapController: _mapController,
+        options: const MapOptions(
+          initialZoom: 5,
+          initialCenter: LatLng(48, 9),
+          maxZoom: 18,
+        ),
+        children: [
+          TileLayer(
+            urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+          ),
+          const MapCompass.cupertino(),
+        ],
+      ),
+    );
+  }
+
+  void rotateMap(double deltaRotation) {
+    _mapController.rotate(_mapController.camera.rotation + deltaRotation);
+  }
+}

example/lib/main.dart

@@ -2,6 +2,7 @@ import 'dart:math';
 
 import 'package:flutter/material.dart';
 import 'package:flutter_map_plugins_example/flutter_map_cache/page.dart';
+import 'package:flutter_map_plugins_example/flutter_map_compass/page.dart';
 import 'package:flutter_map_plugins_example/flutter_map_pmtiles/page.dart';
 import 'package:flutter_map_plugins_example/vector_map_tiles_pmtiles/page.dart';
 import 'package:url_launcher/url_launcher_string.dart';
@@ -28,6 +29,7 @@ class MyApp extends StatelessWidget {
         'flutter_map_cache': (context) => const FlutterMapCachePage(),
         'flutter_map_pmtiles': (context) => const FlutterMapPmTilesPage(),
         'vector_map_tiles_pmtiles': (context) => VectorMapTilesPmTilesPage(),
+        'flutter_map_compass': (context) => const FlutterMapCompassPage(),
       },
     );
   }
@@ -45,6 +47,12 @@ class SelectionPage extends StatelessWidget {
             'tile layers.',
         routeName: 'flutter_map_cache',
       ),
+      SelectionItemWidget(
+        title: 'flutter_map_compass',
+        desc: 'A simple compass layer to indicate the map rotation and '
+            'reset the rotation on click',
+        routeName: 'flutter_map_compass',
+      ),
       SelectionItemWidget(
         title: 'flutter_map_pmtiles',
         desc: 'PMTiles for flutter_map',

example/pubspec.yaml

@@ -37,6 +37,11 @@ dependencies:
   vector_map_tiles: ^7.0.1
   vector_tile_renderer: ^5.2.0
 
+  # vector_map_tiles_compass specific packages
+  flutter_map_compass:
+    path: ../flutter_map_compass
+  cupertino_icons: ^1.0.6
+
 dev_dependencies:
   total_lints: ^3.0.0
 

flutter_map_compass/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "67457e669f79e9f8d13d7a68fe09775fefbb79f4"
+  channel: "stable"
+
+project_type: package

flutter_map_compass/CHANGELOG.md

@@ -0,0 +1,4 @@
+## [1.0.0] yyyy-mm-dd
+
+- Initial release
+- Add `MapCompass`

flutter_map_compass/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joscha Eckert (josxha)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flutter_map_compass/README.md

@@ -0,0 +1,60 @@
+# flutter_map_compass
+
+A simple compass for flutter_map. It shows the rotation of the map and resets
+the rotation back to 0 when tapped.
+
+[![Pub Version](https://img.shields.io/pub/v/flutter_map_compass)](https://pub.dev/packages/flutter_map_compass)
+[![likes](https://img.shields.io/pub/likes/flutter_map_compass?logo=flutter)](https://pub.dev/packages/flutter_map_compass)
+[![Pub Points](https://img.shields.io/pub/points/flutter_map_compass)](https://pub.dev/packages/flutter_map_compass/score)
+[![Pub Popularity](https://img.shields.io/pub/popularity/flutter_map_compass)](https://pub.dev/packages/flutter_map_compass)
+
+[![GitHub last commit](https://img.shields.io/github/last-commit/josxha/flutter_map_plugins)](https://github.com/josxha/flutter_map_plugins)
+[![stars](https://badgen.net/github/stars/josxha/flutter_map_plugins?label=stars&color=green&icon=github)](https://github.com/josxha/flutter_map_plugins/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/josxha/flutter_map_plugins)](https://github.com/josxha/flutter_map_plugins/issues)
+[![codecov](https://codecov.io/gh/josxha/flutter_map_plugins/graph/badge.svg?token=5045489G7X)](https://codecov.io/gh/josxha/flutter_map_plugins)
+
+<img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/flutter_map_compass/images/screenshot.jpg" width="350px" alt="Example screenshot">
+
+## Getting started
+
+Add the following packages to your `pubspec.yaml` file:
+
+```yaml
+dependencies:
+  flutter_map: ^6.0.0         # in case you don't have it yet 
+  flutter_map_compass: ^1.0.0 # this package
+```
+
+## Usage
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return FlutterMap(
+    options: MapOptions(),
+    children: [
+      TileLayer(
+        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+      ),
+
+      // use the default compass that is based on the cupertino compass icon
+      const MapCompass.cupertino(
+        hideIfRotatedNorth: true,
+      ),
+
+      // Or use the primary constructor to customize all
+      const MapCompass(
+        icon: Icon(Icons.arrow_upward),
+        hideIfRotatedNorth: true,
+      ),
+    ],
+  );
+}
+```
+
+## Additional information
+
+If you need help you
+can [open an issue](https://github.com/josxha/flutter_map_plugins/issues/new/choose)
+or join
+the [`flutter_map` discord server](https://discord.gg/BwpEsjqMAH).

flutter_map_compass/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flutter_lints/flutter.yaml

flutter_map_compass/example/example.md

@@ -0,0 +1,25 @@
+### Basic usage
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return FlutterMap(
+    options: MapOptions(),
+    children: [
+      TileLayer(
+        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+      ),
+      const MapCompass.cupertino(),
+    ],
+  );
+}
+```
+
+### Need more information?
+
+- Read
+  the [README.md](https://github.com/josxha/flutter_map_plugins/blob/main/flutter_map_compass/README.md)
+- Check out
+  the [combined example app](https://github.com/josxha/flutter_map_plugins/tree/main/example)
+  that showcases this and other flutter_map
+  packages.

flutter_map_compass/lib/flutter_map_compass.dart

@@ -0,0 +1 @@
+export 'src/map_compass.dart';