123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# @lynkedup/map-sdk
|
|
|
|
A small TypeScript wrapper around `react-native-maps` to provide a consistent API and typed components.
|
|
|
|
## Usage
|
|
|
|
Install peer deps in your app:
|
|
|
|
```
|
|
npm install react-native react-native-maps
|
|
# and add this package via workspace or npm/yarn
|
|
```
|
|
|
|
Basic usage:
|
|
|
|
```ts
|
|
import React from 'react';
|
|
import { MapView, Marker, useLocationTracking, Polyline } from '@lynkedup/map-sdk';
|
|
|
|
export default function App() {
|
|
const { isTracking, path, startTracking, stopTracking, clear } = useLocationTracking(/* opts?: TrackingOptions, geolocation?: GeolocationAPI */);
|
|
|
|
return (
|
|
<MapView style={{ flex: 1 }} initialRegion={{ latitude: 37.78825, longitude: -122.4324, latitudeDelta: 0.0922, longitudeDelta: 0.0421 }}>
|
|
<Marker coordinate={{ latitude: 37.78825, longitude: -122.4324 }} />
|
|
{path.length > 1 && <Polyline coordinates={path} strokeWidth={4} strokeColor="#007AFF" />}
|
|
</MapView>
|
|
);
|
|
}
|
|
|
|
> Tip: `useLocationTracking()` accepts an optional `TrackingOptions` object and an optional `GeolocationAPI` (handy for testing with a mocked geolocation provider). Ensure you request platform location permissions before starting tracking.
|
|
```
|
|
|
|
Tracking notes:
|
|
- `useLocationTracking()` uses the platform geolocation API (`navigator.geolocation.watchPosition`). Request permissions on iOS/Android as usual before starting tracking.
|
|
- It returns `{ isTracking, path, current, startTracking, stopTracking, clear }` so you can display the polyline and follow the user.
|
|
|
|
## Camera Controls 🔧
|
|
|
|
This package exposes a small imperative `MapHandle` API via `ref` on `MapView`. Use it to animate the camera or fit bounds.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
const mapRef = useRef<MapHandle | null>(null);
|
|
mapRef.current?.flyTo({ latitude: 37.78825, longitude: -122.4324 });
|
|
mapRef.current?.fitBounds({ latitude: 37.809, longitude: -122.410 }, { latitude: 37.779, longitude: -122.450 });
|
|
```
|
|
|
|
Available methods:
|
|
|
|
- `animateToRegion(region, duration?)` — animate to a region.
|
|
- `animateCamera(camera, options?)` — animate using camera properties.
|
|
- `flyTo(coordinate, duration?)` — quick helper that animates to a small region around `coordinate`.
|
|
- `fitBounds(northEast, southWest, options?)` — fit the two coordinates with optional `edgePadding`.
|
|
|
|
### Camera presets
|
|
|
|
For convenience, `CameraPresets` provides common camera configurations you can pass into `animateCamera`.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
import { CameraPresets } from '@lynkedup/map-sdk';
|
|
mapRef.current?.animateCamera(CameraPresets.viewOverlook({ latitude: 37.78825, longitude: -122.4324 }), { duration: 1000 });
|
|
```
|
|
|
|
Provided presets:
|
|
|
|
- `viewOverlook(center)` — tilt and rotate to create an overview with pitch ~65° and heading ~45°.
|
|
- `streetLevel(center)` — street-level view (pitch 0, zoom high).
|
|
- `overview(center)` — wide overview of the area.
|
|
|
|
---
|
|
|
|
## PropertyMap (high-level SDK component) ✅
|
|
|
|
`PropertyMap` is a ready-made map screen for property searches — it includes a search bar, clustering support, polygon rendering and a bottom property card. It's ideal to embed in apps that want a turn-key property map.
|
|
|
|
Install the extra peer deps in your app:
|
|
|
|
```bash
|
|
npm install react-native-map-clustering @react-native-community/geolocation
|
|
# and make sure react-native-maps is installed and configured
|
|
```
|
|
|
|
Basic usage:
|
|
|
|
```tsx
|
|
import React from 'react';
|
|
import { PropertyMap } from '@lynkedup/map-sdk';
|
|
|
|
export default function PropertiesScreen() {
|
|
return (
|
|
<PropertyMap
|
|
apiUrl="https://your-api/property-search"
|
|
initialRegion={{ latitude: 25.48, longitude: 81.85, latitudeDelta: 0.02, longitudeDelta: 0.02 }}
|
|
showSearch
|
|
radius={500}
|
|
onSelectProperty={(item) => console.log('selected', item)}
|
|
/>
|
|
);
|
|
}
|
|
```
|
|
|
|
Props summary:
|
|
|
|
| Prop | Type | Default | Description |
|
|
| ---- | ---- | ------- | ----------- |
|
|
| `apiUrl` | `string` | demo host | POST endpoint used for property searches. Should accept `{ location, radius }` and return `{ success, properties, location }`.
|
|
| `initialRegion` | `Region` | `DEFAULT_REGION` | Starting region for the map.
|
|
| `radius` | `number` | `500` | Search radius in meters.
|
|
| `showSearch` | `boolean` | `true` | Show or hide the built-in search bar.
|
|
| `onSelectProperty` | `(item: PropertyItem) => void` | — | Callback invoked when a property is selected.
|
|
| `mapProps` | `Partial<RNMapViewProps>` | — | Props forwarded to the underlying `react-native-maps` view (e.g., `mapType`, `showsMyLocationButton`).
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## Notes
|
|
- This package delegates to `react-native-maps` for platform implementations. Follow `react-native-maps` docs for iOS/Android setup (Google Maps API key, pods, manifest permissions).
|