npm package: @rav3n11/map-tile
Description: A React SDK for integrating Gebeta Maps into your web applications
Author: Gebeta Maps
Latest version: 1.2.3

# Gebeta Maps React Package

A React package for integrating Gebeta Maps into web applications. This package provides React components and utilities for embedding interactive maps with features like markers, clustering, and custom styling.

## Table of Contents

- [Gebeta Maps React Package](#gebeta-maps-react-package)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Basic Usage](#basic-usage)
  - [Components](#components)
    - [GebetaMap](#gebetamap)
      - [Required Props](#required-props)
      - [Optional Props](#optional-props)
  - [Features](#features)
    - [Map Styles](#map-styles)
    - [Markers](#markers)
    - [Clustering](#clustering)
    - [Polylines](#polylines)
    - [Polygons](#polygons)
    - [Events](#events)
    - [Controls](#controls)
  - [Advanced Usage](#advanced-usage)
    - [Custom Layer](#custom-layer)
  - [API Reference](#api-reference)
  - [Contributing](#contributing)
  - [License](#license)

## Installation

```bash
# Using yarn
yarn add @rav3n11/map-tile

# Using npm
npm install @rav3n11/map-tile
```

## Basic Usage

```tsx
import { GebetaMap, MapStyles } from '@rav3n11/map-tile';

function App() {
  return (
    <GebetaMap
      style={{ width: '100%', height: '400px' }}
      mapStyle={MapStyles.BASIC}
      center={[38.7578, 8.9806]}
      zoom={12}
    />
  );
}
```

## Components

### GebetaMap

The main component for rendering an interactive map.

#### Required Props

| Prop | Type | Description |
|------|------|-------------|
| style | CSSProperties | CSS styles for the map container. Must include width and height |

#### Optional Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| mapStyle | MapStyles | MapStyles.BASIC | The map style to use |
| center | [number, number] | [38.7578, 8.9806] | Initial center coordinates [longitude, latitude] |
| zoom | number | 12 | Initial zoom level |
| minZoom | number | 0 | Minimum allowed zoom level |
| maxZoom | number | 22 | Maximum allowed zoom level |
| pitch | number | 0 | Initial pitch in degrees |
| bearing | number | 0 | Initial bearing in degrees |
| interactive | boolean | true | Whether the map can be interacted with |
| attributionControl | boolean | true | Whether to show attribution control |
| preserveDrawingBuffer | boolean | false | Whether to preserve the drawing buffer |

## Features

### Map Styles

Available built-in styles:

```typescript
import { MapStyles } from '@rav3n11/map-tile';

// Available styles
MapStyles.BASIC       // Clean, minimalist style
MapStyles.MODERN      // Modern design with enhanced features
MapStyles.GEBETA_BASIC // Gebeta's custom basic style
```

You can also use a custom style by providing a style URL or style object:

```typescript
<GebetaMap
  mapStyle="https://your-style-url"
  // or
  mapStyle={{
    version: 8,
    sources: {...},
    layers: [...]
  }}
/>
```

### Markers

Add markers to your map:

```typescript
import { GebetaMap, Marker } from '@rav3n11/map-tile';

function MapWithMarker() {
  return (
    <GebetaMap>
      <Marker
        longitude={38.7578}
        latitude={8.9806}
        anchor="bottom"
        onClick={() => console.log('Marker clicked')}
      />
    </GebetaMap>
  );
}
```

### Clustering

Enable marker clustering for better performance with many markers:

```typescript
import { GebetaMap, MarkerCluster } from '@rav3n11/map-tile';

function MapWithClusters() {
  const points = [
    { longitude: 38.7578, latitude: 8.9806 },
    // ... more points
  ];

  return (
    <GebetaMap>
      <MarkerCluster
        points={points}
        radius={50}
        minZoom={0}
        maxZoom={20}
        onClusterClick={(cluster) => {
          // Handle cluster click
        }}
      />
    </GebetaMap>
  );
}
```

### Polylines

Draw paths and routes:

```typescript
import { GebetaMap, Polyline } from '@rav3n11/map-tile';

function MapWithRoute() {
  const coordinates = [
    [38.7578, 8.9806],
    [38.7580, 8.9808],
    // ... more coordinates
  ];

  return (
    <GebetaMap>
      <Polyline
        coordinates={coordinates}
        color="#FF0000"
        width={2}
        opacity={0.8}
      />
    </GebetaMap>
  );
}
```

### Polygons

Draw areas and regions:

```typescript
import { GebetaMap, Polygon } from '@rav3n11/map-tile';

function MapWithArea() {
  const coordinates = [
    [38.7578, 8.9806],
    [38.7580, 8.9808],
    [38.7582, 8.9806],
    [38.7578, 8.9806], // Close the polygon
  ];

  return (
    <GebetaMap>
      <Polygon
        coordinates={coordinates}
        fillColor="#FF0000"
        fillOpacity={0.5}
        strokeColor="#000000"
        strokeWidth={1}
      />
    </GebetaMap>
  );
}
```

### Events

Handle map interactions:

```typescript
function MapWithEvents() {
  return (
    <GebetaMap
      onLoad={(map) => {
        console.log('Map loaded');
      }}
      onClick={(event) => {
        console.log('Clicked at:', event.lngLat);
      }}
      onMoveEnd={(event) => {
        console.log('New center:', event.target.getCenter());
      }}
      onZoomEnd={(event) => {
        console.log('New zoom:', event.target.getZoom());
      }}
    />
  );
}
```

### Controls

Add map controls:

```typescript
import { GebetaMap, NavigationControl, ScaleControl } from '@rav3n11/map-tile';

function MapWithControls() {
  return (
    <GebetaMap>
      <NavigationControl position="top-right" />
      <ScaleControl position="bottom-left" />
    </GebetaMap>
  );
}
```

## Advanced Usage

### Custom Layer

Add custom layers to your map:

```typescript
import { GebetaMap, Layer, Source } from '@rav3n11/map-tile';

function MapWithCustomLayer() {
  return (
    <GebetaMap>
      <Source
        id="data"
        type="geojson"
        data={{
          type: 'FeatureCollection',
          features: [
            // Your GeoJSON features
          ]
        }}
      >
        <Layer
          id="data-layer"
          type="fill"
          paint={{
            'fill-color': '#088',
            'fill-opacity': 0.8
          }}
        />
      </Source>
    </GebetaMap>
  );
}
```

## API Reference

For detailed API documentation, please visit our [API Reference](https://docs.gebeta.app/api-reference).

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

## License

MIT © [Gebeta Maps](https://gebeta.app)