chore: 0.2.0 release preparation

CHANGELOG.md

@@ -1,3 +1,56 @@
+## 0.2.0
+
+This release is a collection of user affecting changes along a couple of new
+features and bug fixes.
+Head over to
+the [migration guide](https://flutter-maplibre.pages.dev/docs/upgrade) to learn
+more on how to update your implementation.
+
+A big thanks to @gabbopalma for his contributions in this release.
+
+### Breaking Changes
+
+- Rename the `Layer` postfix of the more low level style classes
+  to `StyleLayer`.
+- Remove web-only map controls (ScaleControl, GeolocateControl,
+  AttributionControl, FullscreenControl, LogoControl, NavigationControl,
+  TerrainControl).
+- Remove MapLibre Native specific User Interface options (logo, attribution,
+  compass).
+- Rename `ZoomButtons` to `ControlButtons`.
+- Move style related controller calls to the `StyleController` that can be
+  accessed via a nullable `mapController.style` field.
+- Return the `StyleController` in the `onStyleLoaded()` callback and in
+  the `MapEventStyleLoaded` event.
+- An `ImageSource` now requires a static typed `LngLatQuad` object.
+- Set the minimum required Flutter version to 3.27.
+
+### New Features
+
+- Add a user location button to the `ControlButtons`.
+- Bump ktlint to 0.4.19 and gradle to 8.6.1.
+- Bump MapLibre Native on Android to 11.7.+.
+- Bump jni and jnigen to 0.13.0 and migrate bindings.
+- Widen the gradle dependency constraints to allow patch updates.
+- Add logo as pub.dev screenshot.
+- Structure the API docs in topics.
+- Add an internal `WidgetStateNative` for better code reuse in the upcoming iOS
+  release.
+
+## Bug Fixes
+
+- Fix can't rotate with two fingers on web.
+- Fix text overflow in the scale bar widget.
+- Fix deprecations introduced in Flutter 3.27.
+
+## Misc
+
+- Enhance documentation.
+- Build example app with java 21
+
+Full
+Changelog: [v0.1.2...v0.2.0](https://github.com/josxha/flutter-maplibre/compare/v0.1.2...v0.2.0)
+
 ## 0.1.2
 
 This release adds the last missing features for Android and Web, that are were
@@ -18,12 +71,12 @@ before iOS gets added as a supported platform.
 - Add `MapOptions.of(context)` and `MapOptions.maybeOf(context)`.
 - Add `padding` and `alignment` parameters to the `MapScalebar` widget.
 
-## Bug Fixes
+### Bug Fixes
 
 - Fix WebAssembly builds.
 - Remove unused `flutter_markdown` package.
 
-## Misc
+### Misc
 
 - Add unit tests, add Android integration tests.
 - Use [codecov](https://app.codecov.io/gh/josxha/flutter-maplibre) to monitor

analysis_options.yaml

@@ -9,3 +9,5 @@ linter:
     lines_longer_than_80_chars: false
     flutter_style_todos: false
     cascade_invocations: false
+    document_ignores: false
+    avoid_catches_without_on_clauses: false

docs/versioned_docs/version-0.2.0/architecture.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 90
+---
+
+# Architecture
+
+This page gives a small introduction in the architecture that is used
+for `maplibre`.
+
+## Abstraction Layers
+
+```mermaid
+flowchart TD
+    MapLibreMap -->|uses| MapLibreMapState
+    MapLibreMapState -->|extends| MapLibreMapStateNative
+    MapLibreMapStateNative -->|extends| MapLibreMapStateAndroid
+    MapLibreMapStateNative -->|extends| MapLibreMapStateIos
+    MapLibreMapState --->|extends| MapLibreMapStateWeb
+    MapController -->|implements| MapLibreMapState
+    MapLibreMapStateAndroid -->|method channel, jni| Kotlin([Kotlin])
+    MapLibreMapStateIos -->|method channel, ffi| Swift([Swift])
+    MapLibreMapStateWeb -->|interop| TypeScript([TypeScript])
+```
+
+### 1. Public API
+
+`MapLibreMap` and `MapController` is part of the public API. That part of the
+package that users are in contact with.
+
+### 2. MapLibreMapState
+
+`MapLibreMapState` is an abstract base class for the `State<MapLibreMap`> and
+contains implementations that are completely platform invariant.
+
+### 3. MapLibreMapStateNative
+
+This class is a unified parent class for all non-web platforms that use the
+Pigeon method channel. Because pigoen dart code is the same on all non-web
+platforms, all those implementations are located in `MapLibreMapStateNative`.
+
+### 4. MapLibreMapStateAndroid, -Ios, -Web
+
+This is the last Flutter/Dart layer. These classes contain missing
+implementations that haven't previously been implemented on an higher level.
+
+This layer has the connection with the Native Code Layer using
+
+- Method Channels with the Pigeon code generator
+- JNI using JNIGEN to interop with Kotlin on Android
+- FFI using FFIGEN to interop with Swift on iOS
+- The WASM compatible interop with JavaScript using js_interop and package:web
+  on Web.
+
+### 5. Native Layer
+
+The last and most low level layer that package uses. This layer handles Platform
+View registration and the native implementation of Pigeon.

docs/versioned_docs/version-0.2.0/events.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 40
+---
+
+# Events
+
+The event system is the used if you want to listen to any user interactions or
+state changes on the map.
+
+## Basic Usage
+
+To listen to map events, implement a callback function for the `onEvent`
+parameter.
+
+```dart
+  @override
+Widget build(BuildContext context) {
+  return MapLibreMap(
+    options: MapOptions(center: Position(9.17, 47.68)),
+    // highlight-start
+    onEvent: _onEvent,
+    // highlight-end
+  );
+}
+
+void _onEvent(event) {
+  print(event.runtimeType);
+
+  // check for the event type
+  // highlight-start
+  if (event is MapEventClicked) {
+    print('The map has been clicked at ${event.point.lng}, ${event.point.lat}');
+  }
+  // highlight-end
+
+  // or use a switch statement to listen to all the events you are interested in
+  // highlight-start
+  switch (event) {
+    case MapEventMapCreated():
+      print('map created');
+    case MapEventStyleLoaded():
+      print('style loaded');
+    default:
+    // ignore all other events
+  }
+  // highlight-end
+}
+```
+
+## Available Events
+
+- [MapLibre GL JS MapEventType](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapEventType/)
+- [MapLibre Native Android Listeners](https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-map-view/index.html)
+
+| Flutter                  | Web         | Android                           | iOS | Windows | MacOS | Linux |
+|--------------------------|-------------|-----------------------------------|-----|---------|-------|-------|
+| MapEventMapCreated       |             |                                   |     |         |       |       |
+| MapEventStyleLoaded      | load        | (OnDidFinishLoadingStyleListener) |     |         |       |       |
+| MapEventClicked          | click       | OnMapClickListener                |     |         |       |       |
+| MapEventDoubleClicked    | dblclick    |                                   |     |         |       |       |
+| MapEventSecondaryClicked | contextmenu |                                   |     |         |       |       |
+| MapEventLongClicked      |             | OnMapLongClickListener            |     |         |       |       |
+| MapEventIdle             | idle        | OnDidBecomeIdleListener           |     |         |       |       |
+|                          | mousedown   |                                   |     |         |       |       |
+| MapEventStartMoveCamera  |             | OnCameraMoveStartedListener       |     |         |       |       |
+| MapEventMoveCamera       | move        | OnCameraMoveListener              |     |         |       |       |
+| MapEventCameraIdle       | moveend     | OnCameraMoveCanceledListener      |     |         |       |       |

docs/versioned_docs/version-0.2.0/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting Started",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "description": "Quick start guide: From Start to your first Map!"
+  }
+}

docs/versioned_docs/version-0.2.0/getting-started/add-dependency.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+---
+
+# Add Dependency
+
+## Use the package from pub.dev
+
+Add `maplibre` to your project by running this command:
+
+```bash
+flutter pub add maplibre
+```
+
+Alternatively, add it directly as a dependency to your `pubspec.yaml` file and
+run `flutter pub get`:
+
+```yaml title="pubspec.yaml"
+dependencies:
+  # highlight-next-line
+  maplibre: ^0.1.0
+```
+
+Ensure that you use the documentation of the right
+version. [Click here](/docs/getting-started/add-dependency)
+to get to docs of the latest released version.
+You can find the latest version of the package on
+[pub.dev](https://pub.dev/packages/maplibre) or here:
+
+[![Pub Version](https://img.shields.io/pub/v/maplibre)](https://pub.dev/packages/maplibre)
+
+## Using the development version
+
+If you want to have access to the latest features and changes, you
+can use the package directly from GitHub.
+
+:::warning
+
+Note, that the development version is not considered stable and shouldn't be
+used in production systems.
+
+:::
+
+This is how you include the package directly from GitHub. Either use it in your
+`dependecies:` or temporarily override it inside the `dependency_overrides:`
+list.
+
+```yaml title="pubspec.yaml"
+dependencies:
+  # highlight-start
+  maplibre:
+    git:
+      url: https://github.com/josxha/flutter-maplibre
+      ref: main # or a specific commit hash 
+  # highlight-end
+```