Use native CLGeocoder in geocoding_darwin example (#302)

* Use native CLGeocoder in geocoding_darwin example.
Demonstrates the external native API via clgeocoder.dart instead of the
shared Geocoding platform interface, matching the geocoding_android example pattern.

* Changed to using extension on location

* moved down private function

* updated changelog

* Updated documentation regarding contribution to only one package and versioning

* Version bump for geocoding_darwin package

---------

Co-authored-by: Rick van Dijk <rick@baseflow.com>

Author: rickdijk

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,8 +6,9 @@
 
 - [ ] I made sure the project builds.
 - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
-- [ ] I updated `pubspec.yaml` with an appropriate new version according to the [pub versioning philosophy], or this PR is does not need version changes.
-- [ ] I updated `CHANGELOG.md` to add a description of the change.
+- [ ] This PR only changes one package (or documents why an exception is needed).
+- [ ] I updated `pubspec.yaml` with an appropriate new version according to the [pub versioning philosophy], or this PR does not need version changes.
+- [ ] I updated `CHANGELOG.md` with a new `## x.y.z` section that matches the version in `pubspec.yaml`
 - [ ] I updated/added relevant documentation (doc comments with `///`).
 - [ ] I rebased onto `main`.
 - [ ] I added new tests to check the change I am making, or this PR does not need tests.

CONTRIBUTING.md

@@ -23,7 +23,7 @@ Setting up your development environment
 Running the example project
 ---------------------------
 
- * Change into the example directory: `cd example`
+ * Change into the example directory for the package you are working on, e.g. `cd geocoding/example`
  * Run the App: `flutter run`
 
 Contribute
@@ -35,7 +35,7 @@ We really appreciate contributions via GitHub pull requests. To contribute take
    * `git fetch upstream`
    * `git checkout upstream/main -b <name_of_your_branch>`
  * Apply your changes
- * Verify your changes and fix potential warnings/ errors:
+ * Verify your changes and fix potential warnings/ errors (run from the package you changed):
    * Check formatting: `flutter format .`
    * Run static analyses: `flutter analyze`
    * Run unit-tests: `flutter test`
@@ -46,4 +46,14 @@ Send us your pull request:
 
  * Go to `https://github.com/Baseflow/flutter-geocoding` and click the "Compare & pull request" button.
 
- Please make sure you solved all warnings and errors reported by the static code analyses and that you fill in the full pull request template. Failing to do so will result in us asking you to fix it.
+ Please make sure you solved all warnings and errors reported by the static code analyses and that you fill in the full pull request template. Failing to do so will result in us asking you to fix it.
+
+Pull request scope and versioning
+---------------------------------
+
+Each pull request should follow these conventions:
+
+ * **One package per PR** — keep changes confined to a single package directory (`geocoding/`, `geocoding_android/`, `geocoding_darwin/`, etc.). Cross-package changes require maintainer coordination and are usually split into separate PRs.
+ * **Version bump required** — when a PR changes anything that would be published to pub.dev (code, example, README in the package, etc.), bump the `version:` field in that package's `pubspec.yaml` according to the [pub versioning philosophy](https://dart.dev/tools/pub/versioning).
+ * **Matching CHANGELOG entry** — add a new top section in that package's `CHANGELOG.md` using the exact version number (e.g. `## 1.0.1`). The version in `pubspec.yaml` and the CHANGELOG heading must match. Describe the change in the same style as existing entries (see `geocoding_android/CHANGELOG.md` version `5.0.1` as a reference for example-only changes).
+ * **When no version bump is needed** — root-only documentation, CI, or `.github/` changes that do not affect a published package do not require a version bump. Note this in the pull request template when applicable.

geocoding_darwin/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.0.1
+
+- Updates the example app to demonstrate Darwin-specific native CLGeocoder
+  methods via `clgeocoder.dart`.
+
 ## 1.0.0
 
 - Initial release of the geocoding_darwin package containing easy geocoding and

geocoding_darwin/CONTRIBUTING.md

@@ -3,6 +3,12 @@
 Please start by taking a look at the general guide to contributing to the `baseflow/flutter-geocoding` repo:
 https://github.com/baseflow/flutter-geocoding/blob/main/CONTRIBUTING.md
 
+## Versioning
+
+When your change affects this package (code, example, README, etc.), bump the version in
+[`pubspec.yaml`](pubspec.yaml) and add a matching entry at the top of
+[`CHANGELOG.md`](CHANGELOG.md) using the same version number (e.g. `## 1.0.1`). See the [Pull request scope and versioning](https://github.com/baseflow/flutter-geocoding/blob/main/CONTRIBUTING.md#pull-request-scope-and-versioning) section in the root contributing guide.
+
 ## Package Structure
 
 This plugin serves as a platform implementation plugin as outlined in [federated plugins](https://docs.flutter.dev/packages-and-plugins/developing-packages#federated-plugins).

geocoding_darwin/example/lib/main.dart

@@ -1,6 +1,7 @@
 import 'package:baseflow_plugin_template/baseflow_plugin_template.dart';
 import 'package:flutter/material.dart';
-import 'package:geocoding_darwin/geocoding_darwin.dart';
+import 'package:flutter/services.dart';
+import 'package:geocoding_darwin/clgeocoder.dart' as cl;
 
 /// Defines the main theme color.
 final MaterialColor themeMaterialColor =
@@ -32,9 +33,7 @@ class _GeocodeWidgetState extends State<GeocodeWidget> {
   final TextEditingController _longitudeController = TextEditingController();
   String _output = '';
   Locale? _locale;
-  final Geocoding _geocoding = GeocodingDarwinFactory().createGeocoding(
-    GeocodingDarwinCreationParams(),
-  );
+  final cl.CLGeocoder _geocoder = cl.CLGeocoder();
 
   @override
   void initState() {
@@ -119,30 +118,8 @@ class _GeocodeWidgetState extends State<GeocodeWidget> {
                   const Padding(padding: EdgeInsets.only(top: 8)),
                   Center(
                     child: ElevatedButton(
+                      onPressed: _reverseGeocode,
                       child: const Text('Look up address'),
-                      onPressed: () {
-                        final latitude = double.parse(_latitudeController.text);
-                        final longitude = double.parse(
-                          _longitudeController.text,
-                        );
-
-                        _geocoding
-                            .placemarkFromCoordinates(
-                              latitude,
-                              longitude,
-                              locale: _locale,
-                            )
-                            .then((placemarks) {
-                              var output = 'No results found.';
-                              if (placemarks.isNotEmpty) {
-                                output = placemarks[0].toDisplayString();
-                              }
-
-                              setState(() {
-                                _output = output;
-                              });
-                            });
-                      },
                     ),
                   ),
                   const Padding(padding: EdgeInsets.only(top: 32)),
@@ -156,37 +133,17 @@ class _GeocodeWidgetState extends State<GeocodeWidget> {
                   const Padding(padding: EdgeInsets.only(top: 8)),
                   Center(
                     child: ElevatedButton(
+                      onPressed: _forwardGeocode,
                       child: const Text('Look up location'),
-                      onPressed: () {
-                        _geocoding
-                            .locationFromAddress(_addressController.text)
-                            .then((locations) {
-                              var output = 'No results found.';
-                              if (locations.isNotEmpty) {
-                                output = locations[0].toDisplayString();
-                              }
-
-                              setState(() {
-                                _output = output;
-                              });
-                            });
-                      },
                     ),
                   ),
                   const Padding(padding: EdgeInsets.only(top: 8)),
                   Center(
                     child: ElevatedButton(
-                      child: const Text('Is present'),
                       onPressed: () {
-                        _geocoding.isPresent().then((isPresent) {
-                          var output = isPresent
-                              ? "Geocoder is present"
-                              : "Geocoder is not present";
-                          setState(() {
-                            _output = output;
-                          });
-                        });
+                        setState(() => _output = 'Geocoder is present');
                       },
+                      child: const Text('Is present'),
                     ),
                   ),
                   const Padding(padding: EdgeInsets.only(top: 8)),
@@ -206,16 +163,68 @@ class _GeocodeWidgetState extends State<GeocodeWidget> {
       ],
     );
   }
+
+  cl.Locale? _nativeLocale() {
+    return _locale != null ? cl.Locale(identifier: _locale!.toString()) : null;
+  }
+
+  Future<void> _reverseGeocode() async {
+    setState(() => _output = 'Loading...');
+
+    try {
+      final latitude = double.parse(_latitudeController.text);
+      final longitude = double.parse(_longitudeController.text);
+
+      final placemarks = await _geocoder.reverseGeocodeLocation(
+        cl.CLLocation(latitude: latitude, longitude: longitude),
+        _nativeLocale(),
+      );
+
+      var output = 'No results found.';
+      if (placemarks != null && placemarks.isNotEmpty) {
+        output = placemarks[0].toDisplayString();
+      }
+
+      setState(() => _output = output);
+    } on PlatformException catch (e) {
+      setState(() => _output = 'Error: ${e.message ?? e.code}');
+    } on FormatException catch (e) {
+      setState(() => _output = 'Error: ${e.message}');
+    }
+  }
+
+  Future<void> _forwardGeocode() async {
+    setState(() => _output = 'Loading...');
+
+    try {
+      final placemarks = await _geocoder.geocodeAddressString(
+        _addressController.text,
+        _nativeLocale(),
+      );
+
+      var output = 'No results found.';
+      if (placemarks != null && placemarks.isNotEmpty) {
+        final cl.CLLocation? location = placemarks[0].location;
+        output = location != null
+            ? await location.toDisplayString()
+            : 'No location found.';
+      }
+
+      setState(() => _output = output);
+    } on PlatformException catch (e) {
+      setState(() => _output = 'Error: ${e.message ?? e.code}');
+    }
+  }
 }
 
-extension _PlacemarkExtensions on Placemark {
+extension _CLPlacemarkExtensions on cl.CLPlacemark {
   String toDisplayString() {
     return '''
       Name: $name, 
-      Street: $street, 
+      Street: ${postalAddress?.street ?? thoroughfare}, 
       ISO Country Code: $isoCountryCode, 
       Country: $country, 
-      Postal code: $postalCode, 
+      Postal code: ${postalAddress?.postalCode ?? postalCode}, 
       Administrative area: $administrativeArea, 
       Subadministrative area: $subAdministrativeArea,
       Locality: $locality,
@@ -225,11 +234,14 @@ extension _PlacemarkExtensions on Placemark {
   }
 }
 
-extension _LocationExtensions on Location {
-  String toDisplayString() {
+extension _CLLocationExtensions on cl.CLLocation {
+  Future<String> toDisplayString() async {
+    final cl.CLLocationCoordinate2D coordinate = await getCoordinate();
+    final int timestamp = await getTimestamp();
+
     return '''
-      Latitude: $latitude,
-      Longitude: $longitude,
-      Timestamp: $timestamp''';
+      Latitude: ${coordinate.latitude},
+      Longitude: ${coordinate.longitude},
+      Timestamp: ${DateTime.fromMillisecondsSinceEpoch(timestamp)}''';
   }
 }

geocoding_darwin/pubspec.yaml

@@ -2,7 +2,7 @@ name: geocoding_darwin
 description: |-
   A Flutter Geocoding plugin which provides easy geocoding and 
   reverse-geocoding features for iOS and macOS.
-version: 1.0.0
+version: 1.0.1
 repository: https://github.com/baseflow/flutter-geocoding
 
 environment: