# react-native-ctp-odp

React Native ODP Components

## Installation

```sh
npm install react-native-ctp-odp
```

## Usage

1. Install the required packages

```sh
npm install react-native-ctp-odp
npm install react-native-webview
```

2. Import JMapView object (and types)

```js
import {
  // types
  MAP_TAP_EVENT_TYPE,
  // Objects
  JMapView,
  Utilities,
} from 'react-native-ctp-odp';
```

3. Add a JMapView

```js
const mapRef = useRef<MAP_VIEW_REFERENCE_TYPE>(null);

<JMapView
    style={{ width: "100%", height: "100%" }}
    ref={mapRef}
    onMapMessage={{
        callbacks...
    }}
/>
```

## JMapView Methods

Map methods can be called by adding a refence to the JMapView object. All of the available methods should be visible and typed through typescript.

```js
const mapRef = useRef < MAP_VIEW_REFERENCE_TYPE > null;
<JMapView ref={mapRef} />;

if (mapRef.current) mapRef.current.clearWayfindingPath();
```

- setMapVenue(credentials: MAP_CREDENTIALS, compass?: MAP_COMPASS_PROPERTIES, floorSelector?: MAP_FLOOR_SELECTOR_PROPERTIES, zoomButtons?: MAP_ZOOM_BUTTON_PROPERTIES, search?: MAP_SEARCH_PROPERTIES)
  - Intialize map with credentials and ui elements. The credentials needs to include a venue id.
- centerMapOnPoint: (point: number[])
  - Center map on map x/y location
- setFollowBlueDot: (enabled: boolean, rotate: boolean = false, interval: number = 500)
  - Tell map to continually center on blue dot. Options for a rotation angle and an update interval (in milliseconds)
- setUserPosition: (lat: number, long: number, heading: number)
  - Update blue dot location on map, by lat/long
- setUserPositionXY: (x: number, y: number, heading: number)
  - Update blue dot location on map, by x/y
- clearWayfindingPath: ()
  - lear drawn wayfinding path
- wayfindToWaypoint: (waypointId: number)
  - Generate path and directions from blue dot to waypoint. Waypoint IDs can be retrieved from the onSearchDestinationsGenerated or onDestinationSelected callbacks
- wayfindBetweenWaypoints: (originId: number, destinationId: number)
  - Generate a path between two waypoints, by id. Waypoint IDs can be retrieved from the onSearchDestinationsGenerated or onDestinationSelected callbacks
- drawNavigationPath: (pathId: string, shouldFocus?: boolean, style?: JIBESTREAM_STYLE = {stroke: '#ffc956',,strokeWidth: 3})
  - Render navigation path with set style. Requires pathId, which can be retrieved from a path, returned by the onNavigationPathGenerated callback.
- styleUnitsForDestination: (destination: JIBESTREAM_DESTINATION, style?: JIBESTREAM_STYLE)
  - Set unit style for a destination object. This destination object can be retrieved from the onNavigationPathGenerated, onDestinationSelected, or onSearchDestinationsGenerated callbacks
- styleShape: (unitId: number, style?: JIBESTREAM_STYLE)
  - Set shape style by id

## JMapView Callbacks

Map callback methods are specified through the onMapMessage property.

```js
<JMapView
  onMapMessage={{
    onMapTappedGeneric: (event: MAP_TAP_EVENT) => {
      console.log(event.localPoint);
    },
  }}
/>;

if (mapRef.current) mapRef.current.clearWayfindingPath();
```

- onDestinationSelected: (destination JIBESTREAM_DESTINATION)
  - Triggered when a destination is selected within the in-app search bar. Returns a JIBESTREAM_DESTINATION object
- onNavigationPathGenerated: ({pathId: string, instructions: INSTRUCTION[], start: JIBESTREAM_WAYPOINT, end: JIBESTREAM_WAYPOINT, path: JIBESTREAM_PATH[]})
  - Triggered when a navigation path and instructions are generated by the GUI, most likely from the wayfindToWaypoint or wayfindBetweenWaypoints methods. Returns a pathID (used to render path), instructions (used to display to user), start point, end point, and path object)
- onUserPositionUpdated: (number[])
  - Triggered when the blue dot location is updated on the map. Used to hold the user location in the front end. This is not the same as saving the ODP output, as snapToPath and snapToGrid alter the user/blue dot's location. Returns the x/y location of the blue dot
- onWindowLoaded: ()
  - WebView contents are initialized and ready to be used. It is best to wait for this callback before trying to initialize or manipulate the map
- onMapTappedGeneric: (event: MAP_TAP_EVENT)
  - Triggered when the user taps the map (jibestream map enableGenericTapHandler). Returns an event object which contains the clicked location (and other metadata)
- onSearchDestinationsGenerated: (destinations: JIBESTREAM_DESTINATION_SET[])
  - Triggered when the map generates a set of search destinations, this is triggered on map initialization (setMapVenue). Returns a list of destination objects, with corresponding waypoints.

## Utilities Object

The Utilities object, imported alongside the JMapView, enalbles proessing of instructions.

- preProcessPath(path: JIBESTREAM_PATH[], instructions: INSTRUCTION[])
  - Add start and end points to instructions from path. This will enable easy generation of current instruction and distance remaining
- getCurrentInstruction(userLocation: number[], instructions: INSTRUCTION[])
  - Get current instruction from user location and processed instructions.

4. Implement callbacks and call methods from the map reference!

See [JMapView Methods](#jmapview-methods) and [JMapView Callbacks](#jmapview-callbacks) sections

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
