# GRUZF Map <!-- omit in toc -->

![gruzf-mapbox](https://i.postimg.cc/dttQbmXX/mapbox-logo-black.png)

[![Version](https://img.shields.io/badge/dynamic/json?color=green&label=numen&prefix=v&query=%24%5B%27dist-tags%27%5D.latest&url=https%3A%2F%2Fregistry.npmjs.org%2F%40gruzf%2Fnumen)](https://npmjs.org/package/@gruzf/numen)
[![Company](https://img.shields.io/badge/company-@gruzf-blue)](https://www.npmjs.com/org/gruzf)

This library is designed to embed MapBox as a **React** component.

> GRUZF Map is written in `typescript` and built on the [MapBox](https://mapbox.com/) library

- [Install](#install)
- [Usage](#usage)
  - [Map Props](#map-props)
    - [accessToken (required)](#accesstoken-required)
    - [attributionControl](#attributioncontrol)
    - [boundsDuration](#boundsduration)
    - [center](#center)
    - [cooperativeGestures](#cooperativegestures)
    - [disableRotate](#disablerotate)
    - [height](#height)
    - [style](#style)
    - [timeout](#timeout)
    - [width](#width)
    - [zoom](#zoom)
  - [Map Handlers](#map-handlers)
    - [onClick](#onclick)
    - [onZoom](#onzoom)
    - [onZoomStart](#onzoomstart)
    - [onZoomEnd](#onzoomend)
    - [onMoveStart](#onmovestart)
    - [onMoveEnd](#onmoveend)
    - [onMouseDown](#onmousedown)
    - [onMouseUp](#onmouseup)
    - [onTouchStart](#ontouchstart)
    - [onTouchEnd](#ontouchend)
  - [NavigationControl](#navigationcontrol)
    - [...other props](#other-props)
  - [GeolocateControl](#geolocatecontrol)
    - [...other props](#other-props-1)
  - [CallBackControl](#callbackcontrol)
    - [title](#title)
    - [breakpoint](#breakpoint)
    - [position](#position)
  - [CallBackControl Handlers](#callbackcontrol-handlers)
    - [onClick](#onclick-1)
  - [RouteNavigationControl](#routenavigationcontrol)
    - [coordinates](#coordinates)
    - [duration](#duration)
    - [padding](#padding)
  - [Marker](#marker)
    - [animateDuration](#animateduration)
    - [index](#index)
    - [icon](#icon)
    - [logo](#logo)
    - [disabled](#disabled)
    - [disableEaseTo](#disableeaseto)
    - [...other](#other)
  - [Marker Handlers](#marker-handlers)
    - [onClick](#onclick-2)
    - [onDrag](#ondrag)
    - [onDragStart](#ondragstart)
    - [onDragEnd](#ondragend)
  - [Line](#line)
    - [id (required)](#id-required)
    - [coordinates (required)](#coordinates-required)
    - [color](#color)
    - [paint](#paint)
    - [width](#width-1)
  - [Line Handlers](#line-handlers)
    - [onClick](#onclick-3)
  - [Polygon](#polygon)
    - [id (required)](#id-required-1)
    - [coordinates (required)](#coordinates-required-1)
    - [color](#color-1)
    - [paint](#paint-1)
    - [opacity](#opacity)
  - [Polygon Handlers](#polygon-handlers)
    - [onClick](#onclick-4)
  - [Cluster](#cluster)
    - [data (required)](#data-required)
    - [pinElement](#pinelement)
    - [pinUrl](#pinurl)
    - [pinSize](#pinsize)
    - [pinOffset](#pinoffset)
    - [clusterMaxZoom](#clustermaxzoom)
    - [clusterRadius](#clusterradius)
    - [circles](#circles)
  - [Cluster Handlers](#cluster-handlers)
    - [onClick](#onclick-5)

## Install

```bash
npm install @gruzf/map
```

or

```bash
yarn add @gruzf/map
```

## Usage

```js
import Map from "@gruzf/map";
import "mapbox-gl/dist/mapbox-gl.css"; // important!

function HelloWorld() {
  return <Map accessToken={`MAPBOX_TOKEN`} />;
}
```

### Map Props

#### accessToken (required)

- Type: `string`
- Default: `undefined`

You need a Mapbox access token to use any of Mapbox's tools, APIs, or SDKs.

#### attributionControl

- Type: `boolean`
- Default: `false`

If true , an AttributionControl will be added to the map.

#### boundsDuration

- Type: `number`
- Default: `1200`

The animation's duration, measured in milliseconds.

#### center

- Type: `[number, number]`
- Default: `[59.939704, 30.31483]`

The initial geographical centerpoint of the map.

#### cooperativeGestures

- Type: `boolean`
- Default: `true`

If true , scroll zoom will require pressing the ctrl or ⌘ key while scrolling to zoom map, and touch pan will require using two fingers while panning to move the map. Touch pitch will require three fingers to activate if enabled.

#### disableRotate

- Type: `boolean`
- Default: `true`

Disable rotate the map

#### height

- Type: `number | string`
- Default: `400`

Map height

#### style

- Type: `string`
- Default: `mapbox://styles/gevorgyan/ck8r55dm00vi51io8tyzx4vsw`

The map's Mapbox style.

#### timeout

- Type: `number`
- Default: `100`

Time to render the map in milliseconds

#### width

- Type: `number | string`
- Default: `"100%"`

Map width

#### zoom

- Type: `number`
- Default: `12`

The initial zoom level of the map.

### Map Handlers

#### onClick

- Event: `MapEvent`

#### onZoom

- Event: `MapEvent`

#### onZoomStart

- Event: `MapEvent`

#### onZoomEnd

- Event: `MapEvent`

#### onMoveStart

- Event: `MapboxEvent`

#### onMoveEnd

- Event: `MapboxEvent`

#### onMouseDown

- Event: `MapEvent`

#### onMouseUp

- Event: `MapEvent`

#### onTouchStart

- Event: `MapEvent`

#### onTouchEnd

- Event: `MapEvent`

### NavigationControl

```jsx
import Map from "@gruzf/map";
import NavigationControl from "@gruzf/map/NavigationControl";

function HelloWorld() {
  return (
    <Map>
      <NavigationControl />
    </Map>
  );
}
```

#### ...other props

Other NavigationControl options from [mapboxgl.NavigationControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#navigationcontrol)

### GeolocateControl

```jsx
import Map from "@gruzf/map";
import GeolocateControl from "@gruzf/map/GeolocateControl";

function HelloWorld() {
  return (
    <Map>
      <GeolocateControl />
    </Map>
  );
}
```

#### ...other props

Other GeolocateControl options from [mapboxgl.GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol)

### CallBackControl

```jsx
import Map from "@gruzf/map";
import CallBackControl from "@gruzf/map/CallBackControl";

function HelloWorld() {
  return (
    <Map>
      <CallBackControl />
    </Map>
  );
}
```

#### title

- Type: `string`
- Default: `Close`

Button text

#### breakpoint

- Type: `"md" | "sm" | "xs"`
- Default: `sm`

Breakpoint above which the button is hidden

#### position

- Type: `"top" | "bottom"`
- Default: `bottom`

### CallBackControl Handlers

#### onClick

- Event: `MouseEvent`

### RouteNavigationControl

```jsx
import Map from "@gruzf/map";
import RouteNavigationControl from "@gruzf/map/RouteNavigationControl";

function HelloWorld() {
  return (
    <Map>
      <RouteNavigationControl
        coordinates={[
          [number, number],
          [number, number],
        ]}
      />
    </Map>
  );
}
```

#### coordinates

- Type: `Coords[]`
- Default: `undefined`

Coordinates to be in map view

#### duration

- Type: `number`
- Default: `1200`

Animation duration

#### padding

- Type: `CameraOptions["padding"]`
- Default: `{ bottom: 140, top: 100, left: 40, right: 40 }`

Map padding

### Marker

```jsx
import Map from "@gruzf/map";
import Marker from "@gruzf/map/Marker";

function HelloWorld() {
  return (
    <Map>
      <Marker position={[number, number]} />
    </Map>
  );
}
```

#### animateDuration

- Type: `number`
- Default: `1200`

Number in milliseconds

#### index

- Type: `number`
- Default: `undefined`

If defined, renders the index to the marker

#### icon

- Type: `ReactNode`
- Default: `<Pin />`

Marker appearance

#### logo

- Type: `ReactNode`
- Default: `undefined`

Logo inside marker

#### disabled

- Type: `boolean`
- Default: `false`

#### disableEaseTo

- Type: `boolean`
- Default: `false`

Center map relative to marker

#### ...other

Other marker options from [mapboxgl.MarkerOptions](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker)

### Marker Handlers

#### onClick

- Event: `MarkerInfo`

#### onDrag

- Event: `MarkerInfo`

#### onDragStart

- Event: `MarkerInfo`

#### onDragEnd

- Event: `MarkerInfo`

### Line

```jsx
import Map from "@gruzf/map";
import Line from "@gruzf/map/Line";

function HelloWorld() {
  return (
    <Map>
      <Line id="route" coordinates={[number, number]} width={2} />
    </Map>
  );
}
```

#### id (required)

- Type: `string`
- Default: `undefined`

#### coordinates (required)

- Type: `[number, number]`
- Default: `undefined`

#### color

- Type: `string`
- Default: `MUI theme primary color`

#### paint

- Type: [mapboxgl.LinePaint](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addlayer)
- Default: `MUI theme primary color`

#### width

- Type: `number`
- Default: `2`

Line width

### Line Handlers

#### onClick

- Event: `undefined`

### Polygon

```jsx
import Map from "@gruzf/map";
import Polygon from "@gruzf/map/Polygon";

function HelloWorld() {
  return (
    <Map>
      <Polygon id="route" coordinates={[number, number]} />
    </Map>
  );
}
```

#### id (required)

- Type: `string`
- Default: `undefined`

#### coordinates (required)

- Type: `[number, number]`
- Default: `undefined`

#### color

- Type: `string`
- Default: `MUI theme primary color`

#### paint

- Type: [mapboxgl.FillPaint](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addlayer)
- Default: `MUI theme primary color`

#### opacity

- Type: `number`
- Default: `0.4`

### Polygon Handlers

#### onClick

- Event: `undefined`

### Cluster

```jsx
import Map from "@gruzf/map";
import Cluster from "@gruzf/map/Cluster";

function HelloWorld() {
  return (
    <Map>
      <Cluster
        data={[
          [number, number],
          [number, number],
          [number, number],
        ]}
        onClick={(e) => handler(e)}
      />
    </Map>
  );
}
```

#### data (required)

- Type: `CoordsContent[] | number[][]`
- Default: `undefined`

#### pinElement

- Type: `HTMLImageElement`
- Default: `undefined`

#### pinUrl

- Type: `string`
- Default: `undefined`

#### pinSize

- Type: `number`
- Default: `0.5`

#### pinOffset

- Type: `[number, number]`
- Default: `[0, -44]`

#### clusterMaxZoom

- Type: `number`
- Default: `14`

#### clusterRadius

- Type: `number`
- Default: `50`

#### circles

- Type: `Circles`
- Default: `{ 1: { color: "#51bbd6", radius: 20, }, 2: { color: "#f1f075", radius: 30, }, 3: { color: "#f28cb1", radius: 40, }, }`

### Cluster Handlers

#### onClick

- Event: `CoordsContent`