add LayerWithSource, optional addLayer(beforeId)

example/lib/annotations_page.dart

@@ -31,12 +31,18 @@ class _AnnotationsPageState extends State<AnnotationsPage> {
             );
           }
           final geojson = await rootBundle
-              .loadString('assets/geojson/lake-constance.geojson');
+              .loadString('assets/geojson/lake-constance.json');
           await _controller.addSource(
             GeoJsonSource(id: 'LakeConstance', data: geojson),
           );
           await _controller.addLayer(
-            const FillLayer(id: 'LakeConstance', sourceId: 'LakeConstance'),
+            const FillLayer(id: 'geojson-fill', sourceId: 'LakeConstance'),
+          );
+          await _controller.addLayer(
+            const LineLayer(id: 'geojson-line', sourceId: 'LakeConstance'),
+          );
+          await _controller.addLayer(
+            const SymbolLayer(id: 'geojson-symbol', sourceId: 'LakeConstance'),
           );
         },
       ),

lib/src/map_controller.dart

@@ -39,7 +39,12 @@ abstract interface class MapController {
 
   /// Add a new layer to the map. The source must be added before adding it to
   /// the map.
-  Future<void> addLayer(Layer layer);
+  ///
+  /// `beforeId` The ID of an existing layer to insert the new layer before,
+  /// resulting in the new layer appearing visually beneath the existing layer.
+  /// If this argument is not specified, the layer will be appended to the end
+  /// of the layers array and appear visually above all other layers.
+  Future<void> addLayer(Layer layer, {String? beforeId});
 
   /// Get the current camera position on the map.
   Future<MapCamera> getCamera();

lib/src/native/widget_state.dart

@@ -17,6 +17,19 @@ final class MapLibreMapStateNative extends State<MapLibreMap>
   @override
   Widget build(BuildContext context) {
     if (Platform.isAndroid) {
+      // Texture Layer (or Texture Layer Hybrid Composition)
+      // Platform Views are rendered into a texture. Flutter draws the
+      // platform views (via the texture). Flutter content is rendered
+      // directly into a Surface.
+        // + good performance for Android Views
+      // + best performance for Flutter rendering.
+      // + all transformations work correctly.
+      // - quick scrolling (e.g. a web view) will be janky
+      // - SurfaceViews are problematic in this mode and will be moved into a
+      //   virtual display (breaking a11y)
+      // - Text magnifier will break unless Flutter is rendered into a
+      //   TextureView.
+      // https://docs.flutter.dev/platform-integration/android/platform-views#texturelayerhybridcompisition
       return AndroidView(
         viewType: 'plugins.flutter.io/maplibre',
         onPlatformViewCreated: _onPlatformViewCreated,
@@ -112,7 +125,7 @@ final class MapLibreMapStateNative extends State<MapLibreMap>
       );
 
   @override
-  Future<void> addLayer(Layer layer) async {
+  Future<void> addLayer(Layer layer, {String? beforeId}) async {
     await switch (layer) {
       FillLayer() =>
         _hostApi.addFillLayer(id: layer.id, sourceId: layer.sourceId),

lib/src/style/layers/circle_layer.dart

@@ -3,15 +3,12 @@ part of 'layer.dart';
 /// A layer that contains circles.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#circle
-final class CircleLayer extends Layer {
+final class CircleLayer extends LayerWithSource {
   /// Default constructor for a [CircleLayer] instance.
   const CircleLayer({
     required super.id,
-    required this.sourceId,
+    required super.sourceId,
   });
 
-  /// The id of the source that should get used.
-  final String sourceId;
-
   // TODO add properties
 }

lib/src/style/layers/fill_extrusion_layer.dart

@@ -3,10 +3,11 @@ part of 'layer.dart';
 /// A layer that contains circles.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#circle
-final class FillExtrusionLayer extends Layer {
+final class FillExtrusionLayer extends LayerWithSource {
   /// Default constructor for a [FillExtrusionLayer] instance.
   const FillExtrusionLayer({
     required super.id,
+    required super.sourceId,
   });
 
   // TODO add properties

lib/src/style/layers/fill_layer.dart

@@ -3,15 +3,11 @@ part of 'layer.dart';
 /// A layer that contains polygons.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#fill
-final class FillLayer extends Layer {
+final class FillLayer extends LayerWithSource {
   /// Default constructor for a [FillLayer] instance.
   const FillLayer({
     required super.id,
-    required this.sourceId,
+    required super.sourceId,
   });
-
-  /// The id of the source that should get used.
-  final String sourceId;
-
   // TODO add properties
 }

lib/src/style/layers/heatmap_layer.dart

@@ -3,10 +3,11 @@ part of 'layer.dart';
 /// A layer that contains circles.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#circle
-final class HeatmapLayer extends Layer {
+final class HeatmapLayer extends LayerWithSource {
   /// Default constructor for a [HeatmapLayer] instance.
   const HeatmapLayer({
     required super.id,
+    required super.sourceId,
   });
 
   // TODO add properties

lib/src/style/layers/hillshade_layer.dart

@@ -3,10 +3,11 @@ part of 'layer.dart';
 /// A layer that contains circles.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#circle
-final class HillshadeLayer extends Layer {
+final class HillshadeLayer extends LayerWithSource {
   /// Default constructor for a [HillshadeLayer] instance.
   const HillshadeLayer({
     required super.id,
+    required super.sourceId,
   });
 
   // TODO add properties

lib/src/style/layers/layer.dart

@@ -1,5 +1,7 @@
 import 'dart:ui';
 
+import 'package:maplibre/maplibre.dart';
+
 part 'background_layer.dart';
 part 'circle_layer.dart';
 part 'fill_extrusion_layer.dart';
@@ -15,8 +17,6 @@ sealed class Layer {
   const Layer({
     required this.id,
     this.metadata,
-    this.source,
-    this.sourceLayer,
     this.minZoom,
     this.maxZoom,
     this.paint,
@@ -32,14 +32,6 @@ sealed class Layer {
   /// like 'maplibre:'.
   final Map<String, Object?>? metadata;
 
-  /// Name of a source description to be used for this layer. Required for all
-  /// layer types except background.
-  final String? source;
-
-  /// Layer to use from a vector tile source. Required for vector tile sources;
-  /// prohibited for all other source types, including GeoJSON sources.
-  final String? sourceLayer;
-
   /// The minimum zoom level for the layer. At zoom levels less than the
   /// minzoom, the layer will be hidden.
   ///
@@ -64,3 +56,23 @@ sealed class Layer {
   /// Default paint properties for this layer.
   final Object? paint;
 }
+
+/// A [Layer] that pulls its data from a [Source]. Basically every layer
+/// except [BackgroundLayer].
+sealed class LayerWithSource extends Layer {
+  /// const constructor for [LayerWithSource].
+  const LayerWithSource({
+    required super.id,
+    required this.sourceId,
+    super.metadata,
+    super.minZoom,
+    super.maxZoom,
+    super.paint,
+    super.filter,
+    super.layout,
+  });
+
+  /// Name of a source description to be used for this layer. Required for all
+  /// layer types except background.
+  final String sourceId;
+}

lib/src/style/layers/line_layer.dart

@@ -3,10 +3,11 @@ part of 'layer.dart';
 /// A layer that contains circles.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#circle
-final class LineLayer extends Layer {
+final class LineLayer extends LayerWithSource {
   /// Default constructor for a [LineLayer] instance.
   const LineLayer({
     required super.id,
+    required super.sourceId,
   });
 
   // TODO add properties

lib/src/style/layers/raster_layer.dart

@@ -3,15 +3,12 @@ part of 'layer.dart';
 /// A layer that contains markers.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#symbol
-final class RasterLayer extends Layer {
+final class RasterLayer extends LayerWithSource {
   /// Default constructor for a [RasterLayer] instance.
   const RasterLayer({
     required super.id,
-    required this.sourceId,
+    required super.sourceId,
   });
 
-  /// The id of the source that should get used.
-  final String sourceId;
-
   // TODO add properties
 }

lib/src/style/layers/symbol_layer.dart

@@ -3,15 +3,12 @@ part of 'layer.dart';
 /// A layer that contains markers.
 ///
 /// https://maplibre.org/maplibre-style-spec/layers/#symbol
-final class SymbolLayer extends Layer {
+final class SymbolLayer extends LayerWithSource {
   /// Default constructor for a [SymbolLayer] instance.
   const SymbolLayer({
     required super.id,
-    required this.sourceId,
+    required super.sourceId,
   });
 
-  /// The id of the source that should get used.
-  final String sourceId;
-
   // TODO add properties
 }

lib/src/style/sources/geo_json_source.dart

@@ -8,15 +8,12 @@ part of 'source.dart';
 final class GeoJsonSource extends Source {
   /// The default constructor for a [GeoJsonSource] object.
   const GeoJsonSource({
-    required this.id,
+    required super.id,
     required this.data,
     this.maxZoom = 18,
     this.attribution,
   });
 
-  /// The id of the [GeoJsonSource].
-  final String id;
-
   /// A URL to a GeoJSON file, or GeoJSON string.
   final String data;
 

lib/src/style/sources/image_source.dart

@@ -8,14 +8,11 @@ part of 'source.dart';
 final class ImageSource extends Source {
   /// The default constructor for a [ImageSource] object.
   const ImageSource({
-    required this.id,
+    required super.id,
     required this.url,
     required this.coordinates,
   });
 
-  /// The id of the [ImageSource].
-  final String id;
-
   /// URL that points to an image.
   final String url;
 

lib/src/style/sources/raster_dem_source.dart

@@ -7,6 +7,7 @@ part of 'source.dart';
 final class RasterDemSource extends Source {
   /// The default constructor for a [RasterDemSource] object.
   const RasterDemSource({
+    required super.id,
     this.url,
     this.tiles,
     this.bounds = const [-180, -85.051129, 180, 85.051129],

lib/src/style/sources/raster_source.dart

@@ -6,6 +6,7 @@ part of 'source.dart';
 final class RasterSource extends Source {
   /// The default constructor for a [RasterSource] object.
   const RasterSource({
+    required super.id,
     this.url,
     this.tiles,
     this.bounds = const [-180, -85.051129, 180, 85.051129],

lib/src/style/sources/source.dart

@@ -11,7 +11,10 @@ part 'video_source.dart';
 ///
 /// https://maplibre.org/maplibre-style-spec/sources
 sealed class Source {
-  const Source();
+  const Source({required this.id});
+
+  /// The id of the source.
+  final String id;
 }
 
 /// Influences the y direction of the tile coordinates.

lib/src/style/sources/vector_source.dart

@@ -9,6 +9,7 @@ part of 'source.dart';
 final class VectorSource extends Source {
   /// The default constructor for a [VectorSource] object.
   const VectorSource({
+    required super.id,
     this.url,
     this.tiles,
     this.bounds = const [-180, -85.051129, 180, 85.051129],
@@ -17,6 +18,7 @@ final class VectorSource extends Source {
     this.maxZoom = 2,
     this.attribution,
     this.volatile = false,
+    this.sourceLayer,
   });
 
   /// A URL to a TileJSON resource. Supported protocols are `http:` and
@@ -59,4 +61,8 @@ final class VectorSource extends Source {
   ///
   /// Defaults to false. Not available on web.
   final bool volatile;
+
+  /// Layer to use from a vector tile source. Required for vector tile sources;
+  /// prohibited for all other source types, including GeoJSON sources.
+  final String? sourceLayer;
 }

lib/src/style/sources/video_source.dart

@@ -19,14 +19,11 @@ part of 'source.dart';
 final class VideoSource extends Source {
   /// The default constructor for a [VideoSource] object.
   const VideoSource({
-    required this.id,
+    required super.id,
     required this.urls,
     required this.coordinates,
   });
 
-  /// The id of the [VideoSource].
-  final String id;
-
   /// URLs to video content in order of preferred format.
   final List<String> urls;