npm package: @fullstackcolombia/high-performance-map
Description: ⚡ Ultra-fast React map component powered by MapLibre GL and PMTiles. Zero configuration, GIS analysis, and optimized for performance.
Author: Full Stack Colombia
Latest version: 1.0.0

# 🗺️ @fullstackcolombia/high-performance-map

⚡ **Ultra-fast React map component** powered by MapLibre GL and PMTiles. Zero configuration, GIS analysis built-in, and optimized for maximum performance.

[![npm version](https://badge.fury.io/js/@fullstackcolombia%2Fhigh-performance-map.svg)](https://www.npmjs.com/package/@fullstackcolombia/high-performance-map)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## ✨ Why Use This Map Component?

### 🚀 **Lightning Fast Performance**
- **PMTiles protocol** for instant map tile loading from CDN
- **Throttled rendering** reduces frame updates by 30%
- **Zero network overhead** with optimized tile streaming
- Handles **thousands of markers** without lag

### 🎨 **5 Beautiful Styles Out-of-the-Box**
- Voyager (default) - Perfect for data visualization
- Positron - Clean and minimal
- Dark Matter - Sleek dark theme
- OSM Bright - Classic OpenStreetMap look
- Topo - Topographic style for outdoor apps

### 📐 **Built-in GIS Analysis**
- **Buffer zones** with Turf.js integration
- Point clustering and spatial operations
- Distance calculations
- No external GIS tools needed

### 🎯 **Zero Configuration**
- Works immediately with `<HighPerformanceMap />`
- Smart defaults for all settings
- No API keys required
- No complex setup

### 🎛️ **Full-Featured Controls**
- Navigation controls with pitch visualization
- Fullscreen toggle
- Geolocation tracking
- Scale bar
- Custom marker management

---

## 📦 Installation

```bash
npm install @fullstackcolombia/high-performance-map
```

```bash
yarn add @fullstackcolombia/high-performance-map
```

```bash
pnpm add @fullstackcolombia/high-performance-map
```

---

## 🎯 Quick Start

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <HighPerformanceMap />
    </div>
  )
}
```

That's it! You have a fully functional map with markers, terrain, and GIS capabilities.

---

## 📚 Props API

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultZoom` | `number` | `4` | Initial zoom level (0-19) |
| `defaultCenter` | `[number, number]` | `[-98.5795, 39.8283]` | Initial map center [longitude, latitude] |
| `showBarMarkers` | `boolean` | `false` | Show sidebar with marker list and GIS tools |

---

## 🎨 5 Usage Examples

### 1️⃣ **Simple Map** (Default Configuration)

Perfect for quick prototyping or simple location display.

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

export default function SimpleMap() {
  return (
    <div style={{ height: '600px' }}>
      <HighPerformanceMap />
    </div>
  )
}
```

**Features:**
- ✅ Loads with default US center
- ✅ Click to add markers
- ✅ Style switcher included
- ✅ Terrain toggle available

---

### 2️⃣ **Colombia-Focused Map**

Center the map on Bogotá, Colombia with appropriate zoom.

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

export default function ColombiaMap() {
  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <HighPerformanceMap 
        defaultCenter={[-74.0721, 4.7110]} // Bogotá coordinates
        defaultZoom={12}
      />
    </div>
  )
}
```

**Use Cases:**
- 🇨🇴 Colombian business locations
- 🏙️ City-specific applications
- 📍 Regional service areas

---

### 3️⃣ **Full-Featured Dashboard**

Enable the sidebar for complete marker and GIS management.

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

export default function Dashboard() {
  return (
    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
      <header style={{ padding: '1rem', background: '#1E1E1E', color: 'white' }}>
        <h1>🗺️ GIS Analysis Dashboard</h1>
      </header>
      <div style={{ flex: 1 }}>
        <HighPerformanceMap 
          defaultCenter={[-99.1332, 19.4326]} // Mexico City
          defaultZoom={11}
          showBarMarkers={true}
        />
      </div>
    </div>
  )
}
```

**Features:**
- ✅ Marker management sidebar
- ✅ Buffer zone calculations
- ✅ Click-to-select markers
- ✅ Fly-to animations
- ✅ Distance radius controls

---

### 4️⃣ **Europe Travel Map**

High zoom for detailed European city exploration.

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

export default function EuropeMap() {
  return (
    <div style={{ height: '800px', margin: '2rem auto', maxWidth: '1200px' }}>
      <HighPerformanceMap 
        defaultCenter={[2.3522, 48.8566]} // Paris
        defaultZoom={13}
        showBarMarkers={true}
      />
    </div>
  )
}
```

**Perfect for:**
- ✈️ Travel planning apps
- 🏨 Hotel location pickers
- 🍽️ Restaurant finders
- 🎭 Event location maps

---

### 5️⃣ **World Overview Map**

Low zoom for global perspective, ideal for analytics dashboards.

```tsx
import { HighPerformanceMap } from '@fullstackcolombia/high-performance-map'
import '@fullstackcolombia/high-performance-map/style.css'

export default function WorldMap() {
  return (
    <div style={{ height: '100vh' }}>
      <HighPerformanceMap 
        defaultCenter={[0, 20]} // Center of the world
        defaultZoom={2}
        showBarMarkers={false}
      />
    </div>
  )
}
```

**Use Cases:**
- 🌍 Global analytics dashboards
- 📊 International business metrics
- 🌐 Worldwide service coverage
- 📈 Geographic data visualization

---

## 🎮 Interactive Features

### **Click to Add Markers**
Simply click anywhere on the map to drop a new marker.

### **Style Switcher**
Button in top-left corner cycles through 5 beautiful map styles.

### **Terrain Toggle**
Enable hillshade terrain visualization for topographic context.

### **Marker Management** (with `showBarMarkers={true}`)
- View all markers in a list
- Click markers to fly to location
- Delete unwanted markers
- See coordinates for each point

### **Buffer Zone Analysis** (with `showBarMarkers={true}`)
1. Add markers to the map
2. Set buffer radius (100m - 10km)
3. Click "Calculate Buffers"
4. See visual buffer zones around each marker

---

## 🛠️ Technical Details

### **Built With:**
- ⚛️ React 18/19
- 🗺️ MapLibre GL JS 5.x
- 📦 PMTiles Protocol
- 📐 Turf.js (optimized imports)
- 🎨 Lucide React Icons

### **Map Providers:**
- CartoDB (Voyager, Positron, Dark Matter)
- OpenFreeMap (OSM Bright, Topo)

### **Performance Optimizations:**
- Throttled event handlers (100ms)
- Lazy marker rendering
- CSS code splitting
- Tree-shaking ready
- Minimal bundle size

---

## 🎨 Customization

The component includes inline styles but you can override them:

```tsx
<div className="my-custom-map-container" style={{ height: '100vh' }}>
  <HighPerformanceMap />
</div>
```

```css
/* Custom styles */
.my-custom-map-container {
  border: 2px solid #4EC9B0;
  border-radius: 8px;
  overflow: hidden;
}
```

---

## 📄 License

MIT © [Full Stack Colombia](https://fullstackcolombia.com)

---

## 🤝 Support

Need help or have questions?

- 🌐 Visit our website: [fullstackcolombia.com](https://fullstackcolombia.com)
- 📧 Email: info@fullstackcolombia.com
- 💼 LinkedIn: [Full Stack Colombia](https://www.linkedin.com/company/fullstackcolombia)
- 🐦 Twitter: [@fullstackco](https://twitter.com/fullstackco)

---

## 🙏 Credits

Created with ❤️ by **Full Stack Colombia**

Part of our mission to provide high-quality, open-source tools for the Latin American developer community.

### Other Projects:
- [@fullstackcolombia/roseselect](https://www.npmjs.com/package/@fullstackcolombia/roseselect) - Beautiful React select component

---

<div align="center">
  <strong>⭐ Star us on GitHub if you find this useful!</strong>
  <br />
  <br />
  <a href="https://fullstackcolombia.com">
    <img src="https://img.shields.io/badge/Made%20with%20%E2%9D%A4%EF%B8%8F%20by-Full%20Stack%20Colombia-4EC9B0?style=for-the-badge" alt="Full Stack Colombia" />
  </a>
</div>