[google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. #7703

yaakovschectman · 2024-09-25T17:58:31Z

Convert PatternItem and Cap from JSON wrappers to typesafe classes.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

stuartmorgan · 2024-09-25T18:34:54Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+  /// [refWidth] is the reference stroke width (in pixels) - the stroke width for which
+  /// the cap bitmap at its native dimension is designed. Must be positive. Default value
+  /// is 10 pixels.
+  const CustomCap(this.bitmapDescriptor, [this.refWidth = 10])


Given that this is a public API we will ~never be able to change, let's make it a named parameter rather than an optional positional parameter, as named parameters can much more easily be added to later.

stuartmorgan · 2024-09-25T18:37:09Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+  /// Cap that is squared off exactly at the start or end vertex of a [Polyline]
+  /// with solid stroke pattern, equivalent to having no additional cap beyond
+  /// the start or end vertex.
+  butt('buttCap'),


Since the only use case for the strings is toJson, and we want to discourage people relying on strings in the interface of this package, I would much prefer that these be completely internal to the implementation of toJson rather than public API, so we aren't effectively expanding our legacy API surface.

stuartmorgan · 2024-09-25T18:37:40Z

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

+/// Enumeration of types of pattern items.
+enum PatternItemType {
+  /// A dot used in the stroke pattern for a [Polyline].
+  dot('dot'),


Same note here.

stuartmorgan · 2024-09-25T18:39:33Z

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

  }

-  final Object _json;
+  final PatternItemType _type;
+  final double? _length;


It seems like we'll need subclasses that expose length publicly, using a similar structure to your cap changes, otherwise the platform implementation code would still need to call and interpret toJson to get the required info.

packages/google_maps_flutter/google_maps_flutter_platform_interface/test/types/cap_test.dart

stuartmorgan · 2024-09-30T11:47:56Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+      CapType.round: 'roundCap',
+      CapType.square: 'squareCap',
+      CapType.custom: 'customCap',
+    }[capType]!;


Please use a switch instead; a switch would fail analyze if a new enum value were added, while this would not, making this version harder to maintain.

I had not considered that, I will make the change and try to keep that in mind going forward. Thanks.

stuartmorgan · 2024-09-30T11:53:32Z

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

+      PatternItemType.dot: 'dot',
+      PatternItemType.dash: 'dash',
+      PatternItemType.gap: 'gap',
+    }[itemType]!;


...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

stuartmorgan

A couple more minor notes, but mostly looks good.

If we were writing this from scratch I would say we should make an abstract sealed base class and then subclasses for each type, rather than using enums to distinguish, but technically adding sealed to the existing classes would be a breaking change (even though I really doubt it would be breaking), and I don't think the different for clients (being able to directly pattern-switch instead of doing an enum switch + casting, which is not as type-safe) is worth a breaking change to a platform interface package.

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

stuartmorgan

LGTM!

reidbaker · 2024-10-04T14:55:41Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+  custom,
+}
+
+String _capTypeToJson(CapType capType) => switch (capType) {


If there is documentation for where these json values come from please link it here.

These are the old string values used before this PR's diff which are then used the platform packages' JSON-based approach. They do not correspond to any values outside this repo, e.g. the Maps SDK.

Perfect that means if we change them then nothing bad happens.

Perfect that means if we change them then nothing bad happens.

No, that would be extremely bad. It would break all older versions of google_maps_flutter.

We're still cleaning up from tech debt mistakes in federating this plugin, where during federation magic string values that used to be internal to the monolithic plugin package were separated, with the Dart code producing them moved to google_maps_flutter_platform_interface, while the native code consuming them was left in the main package (and then eventually moved to platform implementation packages).

What should have happened was that we stopped using toJson from platform_interface as the serialization mechanism for the platform channels, in favor of package-internal versions. But since we didn't, these string values are effectively part of the public API surface of this package, consumed by our own implementations, with which we have to maintain compatibility.

Ah ok so these strings while not needing to mirror something external like the google maps sdk they do need to mirror something external to the package google_maps_flutter_platform_interface for cross version compatibility.

If we changed the values then set a new minimum for each of the platform implementations would that prevent a breakage? I am not asking because I want to do that but because I want to understand the relationships.

The reason why I was asking what they needed to align to was to add documentation to warn future maintainers what those values needed to align with.

If we changed the values then set a new minimum for each of the platform implementations would that prevent a breakage?

No, because the versions of the platform implementations that call these toJson functions (and rely on the result matching what's in the native code) already exist, and people are using them. And those packages use standard ^2.x.y constraints on google_maps_flutter_platform_interface and rely on the fact that doing so is safe because a change that breaks them wouldn't be made in a 2.* version.

Releasing a new google_maps_flutter_android would mean that people using the new google_maps_flutter_android would only get a compatible version of google_maps_flutter_platform_interface, but it would not stop people using an old version of google_maps_flutter_android from getting a new and incompatible version of google_maps_flutter_platform_interface.

I am not asking because I want to do that but because I want to understand the relationships.

I think the easiest mental model is: because of the federation mistake, the exact structure and string values returned by these toJson functions are now, in practice, part of the official API surface of the method, and so changing any existing details of what it returns would be just like any incompatible change to the documented behavior of any public method: a breaking change requiring a major version bump.

From a docs standpoint, explicitly documenting what the return value structure is in the dart doc would accurately express the unfortunate state we are in now.

reidbaker · 2024-10-04T14:56:35Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+  /// [refWidth] is the reference stroke width (in pixels) - the stroke width for which
+  /// the cap bitmap at its native dimension is designed. Must be positive. Default value
+  /// is 10 pixels.
+  const CustomCap(this.bitmapDescriptor, {this.refWidth = 10})


Is it documented if these are logical pixels or physical pixels? If so please specify.

A few redirections through the Maps SDK documentation describes these as "screen pixels." I will update the comment to include a link to the page.

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart

reidbaker · 2024-10-04T15:13:03Z

packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/cap.dart

+  custom,
+}
+
+String _capTypeToJson(CapType capType) => switch (capType) {


Perfect that means if we change them then nothing bad happens.

…em` and `Cap` to typesafe structures. (flutter/packages#7703)

flutter/packages@05bf1d4...bb00d34 2024-10-07 [email protected] [google_sign_in] Update Pigeon for non-nullable generics (flutter/packages#7785) 2024-10-07 [email protected] [path_provider] Update Android Pigeon for non-nullable generics (flutter/packages#7783) 2024-10-07 [email protected] [rfw] Increase tolerance for material widget tests (flutter/packages#7148) 2024-10-05 [email protected] [various] Update Java compatibility version to 11 (flutter/packages#7795) 2024-10-04 [email protected] [video_player] Update Pigeon for non-nullable generics (flutter/packages#7790) 2024-10-04 [email protected] [go_router] Added missing implementation for the routerNeglect parameter in GoRouter (flutter/packages#7752) 2024-10-04 [email protected] [google_maps_flutter_platform_interface] Convert `BitmapDescriptor` to typesafe subclasses (flutter/packages#7699) 2024-10-04 [email protected] [google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. (flutter/packages#7703) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC [email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

yaakovschectman added 6 commits September 25, 2024 13:44

Convert Cap

2189b35

Convert PatternItem

d79bbd1

Unit test Cap

486830f

Unit test PatternItem

6b8c020

Format

e22fe57

Bump version

644152f

yaakovschectman requested a review from reidbaker September 25, 2024 17:58

yaakovschectman self-assigned this Sep 25, 2024

github-actions bot added the p: google_maps_flutter label Sep 25, 2024

yaakovschectman marked this pull request as ready for review September 25, 2024 18:16

yaakovschectman requested a review from stuartmorgan as a code owner September 25, 2024 18:17

stuartmorgan requested changes Sep 25, 2024

View reviewed changes

yaakovschectman added 2 commits September 25, 2024 16:41

PR Feedback

1894614

Test fix

a51e2ff

yaakovschectman requested a review from stuartmorgan September 27, 2024 18:58

stuartmorgan requested changes Sep 30, 2024

View reviewed changes

Convert map to switch

b8173b2

yaakovschectman requested a review from stuartmorgan September 30, 2024 17:32

Format

d757868

stuartmorgan reviewed Oct 1, 2024

View reviewed changes

...s/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/pattern_item.dart Outdated Show resolved Hide resolved

yaakovschectman and others added 2 commits October 1, 2024 15:46

Divide PatternItem

f935885

Merge branch 'main' into maps_pi_patcap

5bb0294

yaakovschectman requested a review from stuartmorgan October 1, 2024 19:48

yaakovschectman added 2 commits October 1, 2024 16:23

Doc comment

9b5c826

Formatting

54c3af5

stuartmorgan requested changes Oct 3, 2024

View reviewed changes

Refactor names

91a4878

yaakovschectman requested a review from stuartmorgan October 4, 2024 12:40

stuartmorgan approved these changes Oct 4, 2024

View reviewed changes

reidbaker approved these changes Oct 4, 2024

View reviewed changes

Document pixels

e1de2fa

reidbaker approved these changes Oct 4, 2024

View reviewed changes

yaakovschectman merged commit 6ec1b43 into flutter:main Oct 4, 2024
76 checks passed

engine-flutter-autoroll mentioned this pull request Oct 7, 2024

Roll Packages from 05bf1d482dd9 to bb00d34a4280 (8 revisions) flutter/flutter#156322

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/flutter that referenced this pull request Oct 7, 2024

6ec1b43d6 [google_maps_flutter_platform_interface] Convert `PatternIt…

9cc70dc

…em` and `Cap` to typesafe structures. (flutter/packages#7703)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. #7703

[google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. #7703

yaakovschectman commented Sep 25, 2024

stuartmorgan Sep 25, 2024

stuartmorgan Sep 25, 2024

stuartmorgan Sep 25, 2024

stuartmorgan Sep 25, 2024

stuartmorgan Sep 30, 2024

yaakovschectman Sep 30, 2024

stuartmorgan Sep 30, 2024

stuartmorgan left a comment

stuartmorgan left a comment

reidbaker Oct 4, 2024

yaakovschectman Oct 4, 2024

reidbaker Oct 4, 2024

stuartmorgan Oct 4, 2024

reidbaker Oct 4, 2024

stuartmorgan Oct 4, 2024 •

edited

Loading

reidbaker Oct 4, 2024

yaakovschectman Oct 4, 2024

reidbaker Oct 4, 2024

[google_maps_flutter_platform_interface] Convert PatternItem and Cap to typesafe structures. #7703

[google_maps_flutter_platform_interface] Convert PatternItem and Cap to typesafe structures. #7703

Conversation

yaakovschectman commented Sep 25, 2024

Pre-launch Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stuartmorgan left a comment

Choose a reason for hiding this comment

stuartmorgan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stuartmorgan Oct 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

[google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. #7703

[google_maps_flutter_platform_interface] Convert `PatternItem` and `Cap` to typesafe structures. #7703

stuartmorgan Oct 4, 2024 •

edited

Loading