[Feat] Support for Polygon and Polyline

[BoveFabio]

Target Use Case

While I can already easily use many components like (advanced) markers, there is currently no polygon or polyline support. Obviously, it is possibly to write some code myself or even take the code from your geometry example in this repo. But it would be nice if polygon and polyline became officially supported.

Proposal

The basis is already there in the geometry example in this repo. It would probably only take a bit of refinement and could then be offered as a component the same way as markers, for example.

[usefulthink]

I would argue that we do provide support for the geometry primitives, via the examples.
The key Idea is that we want to use the examples to provide "ready-to-use" components for a wide range of use-cases.
We invested a lot of time into making the examples as good as easy to use as possible and we'll continue adding more examples and improving on the existing ones as time allows.

All the components you find in the examples are intended to be copied into your project.
In a lot of cases you won't even need to change anything. In that ideal case, it won't make much of a difference for you if the component is imported from node_modules or from your own components directory. However, if it doesn't do what you need it to do, it is much better if the file is yours and you can quickly change whatever needs to be changed.

I think this approach allows us to provide a far greater coverage of use-cases with the amount of time we have available to work on this library. The more components we have in the core library, the more time it will take to maintain it, so growing the library itself can only happen if the community maintaining it grows along with it.

If I may ask, which benefits do you see bundling the components with the library instead of having them available to copy and adjust in the examples?

[BoveFabio]

Hey @usefulthink,
thanks for your thoughts.

I do agree that copying the files definitely is a valid approach, especially because, in this case, they are not very complex. I also understand that you want to use your limited capacity as efficiently as possible and find that very reasonable.

In general, I think providing common use cases on a maintained basis (rather than providing a file to copy) is useful because I can benefit from updates you make to such examples. If, for example, you found a memory leak in your example and fixed it, I would not immediately benefit from that fix. I would need to keep an eye on the example and check for changes on a regular basis (and think about how to apply your fix to my own code and hope that the changes you made don't conflict with adaptations that I made to the file). In short: only one party would need to spend maintenance effort rather than everyone who uses the feature.

Just to be clear: the above is my general opinion about providing common functionalities. Because of the low complexity of the specific examples of polygon and polyline, it's quite trivial to copy the code and adjust it (and maintain it on my own). This is currently no blocker for us, I just think it might be nice to have that feature out of the box in the future.

[sosukofa]

I do agree with @BoveFabio please make this available so we can use it like how AdvancedMarker components can easily be imported and used.

[becerriljc]

I do agree with @BoveFabio and @sosukofa can easily be imported and used.

[davidcodes17]

@usefulthink
@BoveFabio
@becerriljc
@sosukofa
usefulthink PLease how can i use the polyline i really need it urgently i'm working on a vehicle trackcing project and i used your lib but it does not have polyline feature how can i implement it??

Please i need urgent response

[usefulthink]

Have a look at the app.jsx file of our 'Geometry' Example.

To use the Polyline component, you have to copy the code from ./src/components/polyline.tsx somewhere into your project and import it from there.

The component isn't completed yet, which is why you can't just import it from our package, but there are people already using it this way. Also, it isn't too complicated, so you will be able to improve it or adjust for problems you see. Please report back if anything doesn't work for you!

Here's how the Polyline is created within the map-component:

react-google-maps/examples/geometry/src/app.tsx

Lines 39 to 43 in f17bb37

	<Polyline
	strokeWeight={10}
	strokeColor={'#ff22cc88'}
	encodedPath={POLYGONS[11]}
	/>

The encodedPath uses a special format for the coordinates. If you have dynamic data, you can create them from an array of coordinates with the @googlemaps/polyline-codec(EDIT: just use const geometryLib = useMapLibrary('geometry') and geometryLib.encoding.encodePath() instead), or you can essentially remove this part here:

react-google-maps/examples/geometry/src/components/polyline.tsx

Lines 71 to 76 in f17bb37

	// update the path with the encodedPath
	useMemo(() => {
	if (!encodedPath || !geometryLibrary) return;
	const path = geometryLibrary.encoding.decodePath(encodedPath);
	polyline.setPath(path);
	}, [polyline, encodedPath, geometryLibrary]);

and replace it with a version that directly calls polyline.setPath().

[davidcodes17]

Heyy Martin Thanks for helping me with the polyline, i need your help again concerning add vehicle image as a marker and rotating the vehicle based on the course from the data i'm getting See my current implementation and help me the rotation does not affect the vehicle marker please i need your help

…

On Tue, Oct 15, 2024 at 12:04 AM Martin Schuhfuss ***@***.***> wrote: Have a look at the app.jsx <https://github.com/visgl/react-google-maps/blob/main/examples/geometry/src/app.tsx> file of our 'Geometry' Example <https://visgl.github.io/react-google-maps/examples/geometry>. To use the Polyline component, you have to copy the code from ./src/components/polyline.tsx <https://github.com/visgl/react-google-maps/blob/main/examples/geometry/src/components/polyline.tsx> somewhere into your project and import it from there. The component isn't completed yet, which is why you can't just import it from our package, but there are people already using it this way. Also, it isn't too complicated, so you will be able to improve it or adjust for problems you see. Please report back if anything doesn't work for you! Here's how the Polyline is created within the map-component: https://github.com/visgl/react-google-maps/blob/f17bb37dbf588216e904103069c9323629b10f76/examples/geometry/src/app.tsx#L39-L43 The encodedPath uses a special format for the coordinates. If you have dynamic data, you can create them from an array of coordinates with the @googlemaps/polyline-codec <https://github.com/googlemaps/js-polyline-codec>, or you can essentially remove this part here: https://github.com/visgl/react-google-maps/blob/f17bb37dbf588216e904103069c9323629b10f76/examples/geometry/src/components/polyline.tsx#L71-L76 and replace it with a version that directly calls polyline.setPath() <https://developers.google.com/maps/documentation/javascript/reference/polygon#Polyline.setPath> . — Reply to this email directly, view it on GitHub <#435 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A3326P7P4QM23TQ7REWFHGTZ3REXPAVCNFSM6AAAAABJ7KEHBKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMJSGQ4DIOJRGU> . You are receiving this because you commented.Message ID: ***@***.***>

[aymather]

This whole "what's the problem with copy->pasting this component into your project?" is so silly... im sorry...

The purpose of having a project with exports at all is to avoid confusion. Here are just a few reasons why...

1. Now you're maintaining a separate example apart from the repo, how are we to know/track down compatibility errors? What if your example is completely out of date?
2. Now i'm chasing down examples and it's taking me a ton of time as the user, rather than simply importing it from your project.
3. Me as the user now has to maintain any updates to this component separately from making updates to the package. How am I supposed to know when/how to perform updates to your example?
4. I'm now chasing down "tips and tricks" on how to use this component exactly, because the example you provide doesn't actually use polygon data from google maps (i.e. latitudes/longitudes) it's using this encoded string... ok i have no idea what that is and now i have to spend time researching your example.

The whole purpose of having package exports is to avoid all these problems (to name only a few). The polygon is a standard export of the google maps library for a reason. I don't understand at all what the argument would be to providing this component in an "examples" library completely separate from the library that claims to be a better clone of the original repository?

[usefulthink]

This whole "what's the problem with copy->pasting this component into your project?" is so silly... im sorry...

Don't be sorry, not your fault :)
I recommend starting by reading this, where this approach is explained in a bit more detail: https://visgl.github.io/react-google-maps/docs/contributing

Now you're maintaining a separate example apart from the repo, how are we to know/track down compatibility errors? What if your example is completely out of date?

It's not "apart from the repo", it is an important part of the repo. And when an example is "completely out of date" it will get updated (this only happened a handful of times when the implementation in the Maps API itself changed).

Now i'm chasing down examples and it's taking me a ton of time as the user, rather than simply importing it from your project.

I can totally understand that. What is happening is that there is a line between the code you write in your project and the functionality provided by the libraries you're using. This line is intended to move towards you over time as the library integrates more functionality. Of course, we want common things to be easier to use, so what you see now isn't the end goal.
Adding support for polygon/polyline/circle and other means to customize the map is at the very top of the list.

But we need to make time to actually build it, and we want to be sure to have a stable and good implementation that will be properly maintained going forward. If you're interested in helping out here, please let me know.

Me as the user now has to maintain any updates to this component separately from making updates to the package. How am I supposed to know when/how to perform updates to your example?

The thing here is this: The examples can provide you with a starting point, but it is a lot more like writing the code yourself. Once you copy the code, it becomes part of your application and your responsibility to understand and adjust to your requirements. At the same time, you also get the same guarantees that any other application-code gets, which is that it will remain compatible as long as there is no major release. And when there is, there will also be a migration guide and everything.

I don't understand at all what the argument would be to providing this component in an "examples" library [...]

As you might have guessed, that is going to change, slowly and over time. This is supposed to be a long-term project, and we only have limited resources to work with.
The examples aren't part of the library, they are there to show how to use it as it exists now to achieve whatever you need to achieve. It's not a replacement but a precursor of the components we want to have in the main library.

[...] that claims to be a better clone of the original repository?

a) This isn't a clone of any other repository.
b) Which repository are you referring to as the "original"?
b) Can you show me where I or someone else claimed this was somehow "better" than any other library?

[zukilover]

I'm assuming @aymather is referring to the other Google Maps React library, react-google-maps-api. That library provided most features as off-the-shelf components, so I imagine the confusion just comes from expecting that same structure here.

There have been a few attempts at bringing those components over, such as in this PR: https://github.com/visgl/react-google-maps/pull/484/files

It's really up to @usefulthink to decide if we stick to this "example-first" practice or move toward full component exports. If the goal is the latter, having a clear acknowledgment of that roadmap would be great so we can contribute accordingly.

[usefulthink]

I still think that the "examples first" approach is the right choice given the constraints we have to work with.
That approach gives developers with advanced use-cases a starting point to work from, and examples for using this library with its current limitations, while we don't need to commit to any specific implementation with all that entails. Providing the examples is a way to empower developers to create their own implementations, and hopefully they contribute them back.

We as the few maintainers are limited in the time we can spend on this project. The Google Maps JavaScript API is massive (and in motion as well), so it's not reasonable to try and implement everything at once. We want to focus on

That being said, @mrMetalWood has been working on the full implementation for Polygon, Polyline, and their 3D-equivalents, which we’ll be able to release soon.

[caio1985]

I still think that the "examples first" approach is the right choice given the constraints we have to work with. That approach gives developers with advanced use-cases a starting point to work from, and examples for using this library with its current limitations, while we don't need to commit to any specific implementation with all that entails. Providing the examples is a way to empower developers to create their own implementations, and hopefully they contribute them back.

We as the few maintainers are limited in the time we can spend on this project. The Google Maps JavaScript API is massive (and in motion as well), so it's not reasonable to try and implement everything at once. We want to focus on

That being said, @mrMetalWood has been working on the full implementation for Polygon, Polyline, and their 3D-equivalents, which we’ll be able to release soon.

Is there a timeline for this? @anglarett FYI.
I see Polyline3D and Polygon3D missing in the examples.