Skip to content

Commit c0e80d3

Browse files
AnatoleLucetAnatoleLucet
committed
docs(components): add docs for every components
1 parent 9991622 commit c0e80d3

35 files changed

+6210
-12309
lines changed

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Contributing
2+
3+
TODO :)

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,24 @@ A modern Google Maps integration for ReactJS
99
- Highly extensible
1010
- Interpolation animations for everything (markers, polygons, etc.)
1111

12+
## Documentation
13+
14+
[See our documentation](/docs/index.md)
15+
16+
## Why yet another Google Maps integration for ReactJS?
17+
18+
Why choose React GMaps when there's already [react-google-maps-api](https://github.com/JustFly1984/react-google-maps-api), [google-maps-react](https://github.com/fullstackreact/google-maps-react), [google-map-react](https://github.com/google-map-react/google-map-react), etc. ?
19+
The current landscape doesn't really provide a smooth integration for GoogleMaps in a ReactJS application with hooks and modern patterns.
20+
Existing implementations tends to be old/unmaintained, outdated, lacking features, and/or a bit wobbly.
21+
22+
React GMaps aims to be more flexible, extensible, and composable by exposing simple primitives that can be used in various ways.
23+
It utilizes modern GoogleMaps features such as [AdvancedMarkers](https://developers.google.com/maps/documentation/javascript/reference/advanced-markers) to avoid wacky hacks and unstable integrations.
24+
Plus its context base architecture, ables users to easly access GMaps fonctionallities programmaticaly and create GoogleMaps related libraries for others to use (such as Animated components for example).
25+
1226
## TODOs
1327

28+
Wanna help? See our [`contributing.md`](/CONTRIBUTING.md).
29+
1430
- [x] Marker component (displays ReactJS components)
1531
- [ ] LegacyMarker component (displays images only)
1632
- [x] Polyline component

‎docs/assets/marker.png‎

169 KB
Loading

‎docs/assets/polygon.png‎

456 KB
Loading

‎docs/assets/polyline.png‎

158 KB
Loading

‎docs/components/gmaps-animated-marker.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# `<GMapsAnimatedMarker />`
2+
3+
<p align="center">TODO: screen capture</p>
4+
5+
Creates a new marker with animated interpolation when updating the `lat`/`lnt`. This components extends [`<GMapsMarker />`](/docs/components/gmaps-marker.md).
6+
7+
```jsx
8+
<GMapsAnimatedMarker location={{ lat: 40.73061, lng: -73.935242 }} duration={1000}>
9+
<p style={{ backgroundColor: "red" }}>Hello World</p>
10+
</GMapsMarker>
11+
```
12+
13+
<details>
14+
<summary>Full example</summary>
15+
16+
```jsx
17+
18+
function MyMap() {
19+
const [location, setLocation] = useState({ lat: 40.73061, lng: -73.935242 });
20+
21+
return (
22+
<div style={{ height: "100vh" }}>
23+
<GMaps center={location} zoom={12}>
24+
<GMapsAnimatedMarker location={{ lat: 40.73061, lng: -73.935242 }} duration={1000}>
25+
<p style={{ backgroundColor: "red" }}>Hello World</p>
26+
</GMapsMarker>
27+
</GMaps>
28+
</div>
29+
);
30+
}
31+
```
32+
33+
</details>
34+
35+
<details>
36+
<summary>Animating the marker programmatically</summary>
37+
38+
```typescript
39+
const location = { lat: 40.73061, lng: -73.935242 };
40+
41+
function App() {
42+
const marker = useGMapsAnimatedMarker();
43+
44+
const updateMarkerLocation = () => {
45+
// random new lat/lng near the base `location`
46+
const newLocation = {
47+
lat: location.lat + Math.random() * 0.08,
48+
lng: location.lng + Math.random() * 0.08,
49+
};
50+
51+
marker.current?.animate({
52+
location: newLocation,
53+
duration: 1000,
54+
});
55+
};
56+
57+
return (
58+
<div style={{ height: "100vh" }}>
59+
<button type="button" onClick={updateMarkerLocation}>
60+
update marker location
61+
</button>
62+
63+
<GMaps center={location} zoom={12}>
64+
<GMapsMarker ref={marker} location={location}>
65+
<p style={{ backgroundColor: "red" }}>Hello World</p>
66+
</GMapsMarker>
67+
</GMaps>
68+
</div>
69+
);
70+
}
71+
```
72+
73+
</details>
74+
75+
## Props
76+
77+
| Name | Type | Description |
78+
| -------- | ----------------------- | --------------------------------------------------------------------- |
79+
| duration | `number` | The duration in milliseconds of the interpolation animation. |
80+
| easing | `(n: number) => number` | The easing function to use for the animation. See [`Easing`](#TODO). |
81+
| ...rest | `GMapsMarker.Props` | See [`<GMapsMarker />` Props](/docs/components/gmaps-marker.md#props) |
82+
83+
## Related Hooks
84+
85+
- [`useGMapsAnimatedMarker`](/docs/hooks/use-gmaps-animated-marker.md)
86+
87+
## Related Components
88+
89+
- [`<GMapsMarker />`](/docs/components/gmaps-marker.md)

‎docs/components/gmaps-animated-polygon.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# `<GMapsAnimatedPolygon />`
2+
3+
<p align="center">TODO: screen capture</p>
4+
5+
Creates a new polygon with animated interpolation when updating the path. This components extends [`<GMapsPolygon />`](/docs/components/gmaps-polygon.md).
6+
7+
```jsx
8+
<GMapsAnimatedPolygon
9+
path={[
10+
{ lat: 37.772, lng: -122.214 },
11+
{ lat: 21.291, lng: -157.821 },
12+
{ lat: -18.142, lng: 178.431 },
13+
{ lat: -27.467, lng: 153.027 },
14+
]}
15+
duration={1000}
16+
/>
17+
```
18+
19+
<details>
20+
<summary>Full example</summary>
21+
22+
```jsx
23+
function MyMap() {
24+
const [path, setPath] = useState([
25+
{ lat: 37.772, lng: -122.214 },
26+
{ lat: 21.291, lng: -157.821 },
27+
{ lat: -18.142, lng: 178.431 },
28+
{ lat: -27.467, lng: 153.027 },
29+
]);
30+
31+
return (
32+
<div style={{ height: "100vh" }}>
33+
<GMaps center={{ lat: 0, lng: -180 }} zoom={3}>
34+
<GMapsAnimatedPolygon path={path} duration={1000} />
35+
</GMaps>
36+
</div>
37+
);
38+
}
39+
```
40+
41+
</details>
42+
43+
<details>
44+
<summary>Animating the polygon programmatically</summary>
45+
46+
```jsx
47+
const path = [
48+
{ lat: 37.772, lng: -122.214 },
49+
{ lat: 21.291, lng: -157.821 },
50+
{ lat: -18.142, lng: 178.431 },
51+
{ lat: -27.467, lng: 153.027 },
52+
];
53+
54+
function App() {
55+
const polygon = useGMapsAnimatedPolygon();
56+
57+
const updatePolygonPath = () => {
58+
// random new lat/lng near the base `path` for each point
59+
const newPath = path.map((point) => ({
60+
lat: point.lat + Math.random() * 0.08,
61+
lng: point.lng + Math.random() * 0.08,
62+
}));
63+
64+
polygon.current?.animate({ path: newPath, duration: 1000 });
65+
};
66+
67+
return (
68+
<div style={{ height: "100vh" }}>
69+
<button type="button" onClick={updatePolygonPath}>
70+
update polygon path
71+
</button>
72+
73+
<GMaps center={{ lat: 0, lng: -180 }} zoom={3}>
74+
<GMapsAnimatedPolygon ref={polygon} path={path} />
75+
</GMaps>
76+
</div>
77+
);
78+
}
79+
```
80+
81+
</details>
82+
83+
## Props
84+
85+
| Name | Type | Description |
86+
| -------- | ----------------------- | ----------------------------------------------------------------------- |
87+
| duration | `number` | The duration in milliseconds of the interpolation animation. |
88+
| easing | `(n: number) => number` | The easing function to use for the animation. See [`Easing`](#TODO). |
89+
| ...rest | `GMapsPolygon.Props` | See [`<GMapsPolygon />` Props](/docs/components/gmaps-polygon.md#props) |
90+
91+
## Related Hooks
92+
93+
- [`useGMapsAnimatedPolygon`](/docs/hooks/use-gmaps-animated-polygon.md)
94+
95+
## Related Components
96+
97+
- [`<GMapsPolygon />`](/docs/components/gmaps-polygon.md)

‎docs/components/gmaps-animated-polyline.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# `<GMapsAnimatedPolyline />`
2+
3+
<p align="center">TODO: screen capture</p>
4+
5+
Creates a new polyline with animated interpolation when updating the path. This components extends [`<GMapsPolyline />`](/docs/components/gmaps-polyline.md).
6+
7+
```jsx
8+
<GMapsAnimatedPolyline
9+
path={[
10+
{ lat: 37.772, lng: -122.214 },
11+
{ lat: 21.291, lng: -157.821 },
12+
{ lat: -18.142, lng: 178.431 },
13+
{ lat: -27.467, lng: 153.027 },
14+
]}
15+
duration={1000}
16+
/>
17+
```
18+
19+
<details>
20+
<summary>Full example</summary>
21+
22+
```jsx
23+
function MyMap() {
24+
const [path, setPath] = useState([
25+
{ lat: 37.772, lng: -122.214 },
26+
{ lat: 21.291, lng: -157.821 },
27+
{ lat: -18.142, lng: 178.431 },
28+
{ lat: -27.467, lng: 153.027 },
29+
]);
30+
31+
return (
32+
<div style={{ height: "100vh" }}>
33+
<GMaps center={{ lat: 0, lng: -180 }} zoom={3}>
34+
<GMapsAnimatedPolyline path={path} duration={1000} />
35+
</GMaps>
36+
</div>
37+
);
38+
}
39+
```
40+
41+
</details>
42+
43+
<details>
44+
<summary>Animating the polyline programmatically</summary>
45+
46+
```jsx
47+
const path = [
48+
{ lat: 37.772, lng: -122.214 },
49+
{ lat: 21.291, lng: -157.821 },
50+
{ lat: -18.142, lng: 178.431 },
51+
{ lat: -27.467, lng: 153.027 },
52+
];
53+
54+
function App() {
55+
const polyline = useGMapsAnimatedPolyline();
56+
57+
const updatePolylinePath = () => {
58+
// random new lat/lng near the base `path` for each point
59+
const newPath = path.map((point) => ({
60+
lat: point.lat + Math.random() * 0.08,
61+
lng: point.lng + Math.random() * 0.08,
62+
}));
63+
64+
polyline.current?.animate({ path: newPath, duration: 1000 });
65+
};
66+
67+
return (
68+
<div style={{ height: "100vh" }}>
69+
<button type="button" onClick={updatePolylinePath}>
70+
update polyline path
71+
</button>
72+
73+
<GMaps center={{ lat: 0, lng: -180 }} zoom={3}>
74+
<GMapsAnimatedPolyline ref={polyline} path={path} />
75+
</GMaps>
76+
</div>
77+
);
78+
}
79+
```
80+
81+
</details>
82+
83+
## Props
84+
85+
| Name | Type | Description |
86+
| -------- | ----------------------- | ------------------------------------------------------------------------- |
87+
| duration | `number` | The duration in milliseconds of the interpolation animation. |
88+
| easing | `(n: number) => number` | The easing function to use for the animation. See [`Easing`](#TODO). |
89+
| ...rest | `GMapsPolyline.Props` | See [`<GMapsPolyline />` Props](/docs/components/gmaps-polyline.md#props) |
90+
91+
## Related Hooks
92+
93+
- [`useGMapsAnimatedPolyline`](/docs/hooks/use-gmaps-animated-polyline.md)
94+
95+
## Related Components
96+
97+
- [`<GMapsPolyline />`](/docs/components/gmaps-polyline.md)

0 commit comments

Comments
 (0)