docs: enhance documentation, update docs for 0.2.0

docs/docs/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/docs/getting-started/programmatic-control.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 5
+---
+
+# Programmatic Control
+
+It is possible to update or change the `MapLibreMap` widget during its lifetime.
+
+## The MapLibreMap widget
+
+The `MapLibreMap` is used to specify
+initial values. Parameters that don't begin with `init*` can be updated in a
+declarative way just like any other Flutter Widget. The most simple way is to
+use the `MapLibreMap` widget in a `StatefulWidget` and calling `setState()`.
+
+```dart
+@immutable
+class MyMapWidget extends StatefulWidget {
+  const MyMapWidget({super.key});
+
+  @override
+  State<MyMapWidget> createState() => _MyMapWidget();
+}
+
+class _MyMapWidget extends State<GesturesPage> {
+  // Using this field to store the widget state
+  // highlight-next-line
+  bool _gesturesEnabed = true;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: MapLibreMap(
+          options: MapOptions(
+            // parameters that start with init* can't be updated
+            initCenter: Position(9.17, 47.68),
+            initZoom: 3,
+            // other parameters can be updated
+            // highlight-start
+            gestures: _gesturesEnabled
+                ? MapGestures.all()
+                : MapGestures.none(),
+            // highlight-end
+          ),
+          onEvent: (event) {
+            if (event case MapEventClick()) {
+              // update the map widget using Flutters' state management
+              // highlight-start
+              setState() {
+                _gesturesEnabed = !_gesturesEnabed;
+              }
+              // highlight-end
+            }
+          }
+      ),
+    );
+  }
+}
+```
+
+All parameters that start with `init*` can't be updated using this method and
+need to use the [MapController](#the-mapcontroller) or
+the [StyleController](#the-stylecontroller).
+
+## The MapController
+
+The `MapController` can be used by either using the `onMapCreated` callback or
+by listening in the `onEvent` callback for the `MapEventMapCreated` event type.
+
+You can store the `MapController` in a field variable for later use.
+
+```dart
+class _MyMapWidget extends State<GesturesPage> {
+  // highlight-next-line
+  MapController? _mapController;
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: MapLibreMap(
+          options: MapOptions(initCenter: Position(9.17, 47.68), initZoom: 3),
+          onEvent: (event) {
+            // check if the MapEvent type is a MapEventMapCreated
+            if (event case MapEventMapCreated()) {
+              // store the MapController for later use
+              // highlight-next-line
+              _mapController = event.mapController;
+            }
+          }
+      ),
+    );
+  }
+}
+```
+
+## The StyleController
+
+The `StyleController` is a construct to make style related operations on the
+map. It can be used either by listening to the `MapEventStyleLoaded` event or
+the `onStyleLoaded` callback.
+
+After is is loaded you can access the `StyleController` at any time
+from the `style` getter of `MapController`.
+
+```dart
+class _MyMapWidget extends State<GesturesPage> {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: MapLibreMap(
+          options: MapOptions(initCenter: Position(9.17, 47.68), initZoom: 3),
+          onEvent: (event) {
+            // check if the MapEvent type is a MapEventStyleLoaded
+            if (event case MapEventStyleLoaded()) {
+              // This event gets emitted every time a style finishes loading.
+              // highlight-start
+              event.style.addSource(...);
+              event.style.addLayer(...);
+              // highlight-end
+            }
+          }
+      ),
+    );
+  }
+}
+```
+
+Another way to access the `StyleController` is by calling the `style` getter on
+the `MapController`. Modifications on the map style are only possible after the
+style has been loaded. In case it hasn't loaded, the getter returns null.
+
+```dart
+MapController? _mapController;
+
+void doSomething() {
+  // only adds the source if the style has finished loading and a source can be added.
+  // highlight-next-line
+  _mapController?.style?.addSource(...);
+}
+```

docs/docs/getting-started/use-widget.md

@@ -36,7 +36,7 @@ class MapScreenState extends State<MapScreen> {
           // wait for the onStyleLoadedCallback.
           _mapController = controller;
         },
-        onStyleLoaded: () {
+        onStyleLoaded: (style) {
           debugPrint('Map loaded 😎');
         },
       ),

docs/docs/index/index.md

@@ -10,12 +10,13 @@ MapLibre Native and MapLibre-GL-JS.
 
 Here is an overview what you can find in this documentation:
 
-- [Getting started](../getting-started/add-dependency) helps you to integrate the
+- [Getting started](../getting-started/add-dependency) helps you to integrate
+  the
   package into your project.
 - [Styles](../styles) can be used to customize the design of the map.
 - [User Interface](../ui) provides easy to use controls and indicators.
-- [Annotations](../category/annotations) are an easy way to add Markers, Circles,
-  Polylines or Polygons to the map.
-- [Layers](../category/layers) are a powerful way to add or remove new layers to
-  the map.
+- [Layers](../category/layers) are an easy way to add annotations such as
+  Markers, Circles, Polylines or Polygons to the map.
+- [Style Layers](../category/style-layers) are a powerful way to add or remove
+  new layers to the map.
 - [Events](../events) are a way to listen to something like a click on the map.

docs/docs/layers/_category_.json

@@ -1,8 +1,8 @@
 {
   "label": "Layers",
-  "position": 70,
+  "position": 60,
   "link": {
     "type": "generated-index",
-    "description": "Layers are a direct and powerful way to directly interact with the Layers on the loaded Map Style."
+    "description": "Layers are a convenient and easy way to add annotations such as  Markers, Circles, Polylines or Polygons to the map."
   }
 }

docs/docs/annotations/circles.md → docs/docs/layers/circles.md

@@ -8,7 +8,7 @@ description: 'Add Circles to the map.'
 
 Circles are a simple way to show data on the map.
 
-<a href="/demo/#/annotations/circle">
+<a href="/demo/#/layers/circle">
 <img src="/img/annotations/annotations-circles.jpg" 
      alt="Circles" />
 </a>
@@ -22,7 +22,7 @@ Widget build(BuildContext context) {
     options: MapOptions(center: Position(9.17, 47.68)),
     layers: [
       // highlight-start
-      CircleAnnotationLayer(
+      CircleLayer(
         points: <Point>[
           Point(coordinates: Position(9.17, 47.68)),
           Point(coordinates: Position(9.17, 48)),
@@ -40,7 +40,7 @@ Widget build(BuildContext context) {
 }
 ```
 
-That's it! You can add multiple `CircleAnnotationLayer`s with different
+That's it! You can add multiple `CircleLayer`s with different
 properties.
 
 ## Update
@@ -49,12 +49,12 @@ To add, remove or alter annotation layers, just use `setState()` like you'd do
 with Flutter widgets.
 
 Check out
-the [example app](https://github.com/josxha/flutter-maplibre/blob/main/example/lib/annotations_circle_page.dart)
+the [example app](https://github.com/josxha/flutter-maplibre/blob/main/example/lib/layers_circle_page.dart)
 if you want to see how things come together.
 
 ## Style & Layout
 
-The `CircleAnnotationLayer` has a lot of parameters you can use for styling.
+The `CircleLayer` has a lot of parameters you can use for styling.
 
 If you need more powerful customizations for your Circles, you can use the more
-low level [CircleLayer](../layers/circle-layer).
+low level [CircleLayer](../style-layers/circle-layer).

docs/docs/annotations/markers.md → docs/docs/layers/markers.md

@@ -8,7 +8,7 @@ description: 'Add Markers to the map.'
 
 Markers are a way to show data on the map with labels and/or icons.
 
-<a href="/demo/#/annotations/marker">
+<a href="/demo/#/layers/marker">
 <img src="/img/annotations/annotations-markers.jpg" 
      alt="Markers" />
 </a>
@@ -46,7 +46,7 @@ Widget build(BuildContext context) {
     },
     layers: [
       // highlight-start
-      MarkerAnnotationLayer(
+      MarkerLayer(
         points: <Point>[
           Point(coordinates: Position(9.17, 47.68)),
           Point(coordinates: Position(9.17, 48)),
@@ -66,7 +66,7 @@ Widget build(BuildContext context) {
 }
 ```
 
-That's it! You can add multiple `MarkerAnnotationLayer`s with different
+That's it! You can add multiple `MarkerLayer`s with different
 properties.
 
 ## Update
@@ -75,12 +75,12 @@ To add, remove or alter annotation layers, just use `setState()` like you'd do
 with Flutter widgets.
 
 Check out
-the [example app](https://github.com/josxha/flutter-maplibre/blob/main/example/lib/annotations_marker_page.dart)
+the [example app](https://github.com/josxha/flutter-maplibre/blob/main/example/lib/layers_marker_page.dart)
 if you want to see how things come together.
 
 ## Style & Layout
 
-The `MarkerAnnotationLayer` has a lot of parameters you can use for styling.
+The `MarkerLayer` has a lot of parameters you can use for styling.
 
 If you need more powerful customizations for your Markers, you can use the more
-low level [SymbolLayer](../layers/symbol-layer).
+low level [SymbolLayer](../style-layers/symbol-layer).