@chauffleet/expo-custom-map/README.md

Open source custom map library for Expo/React Native. Use your own tiles without Google Maps, Mapbox, or API keys. Created by ChaufFleet.

# 🗺️ Expo Custom Map

Une bibliothèque de carte personnalisée ultra-fluide pour React Native et Expo, optimisée pour offrir une expérience comparable à Google Maps.

## ✨ Caractéristiques

- **🚀 Fluidité Google Maps** - Gestes natifs ultra-optimisés avec react-native-gesture-handler
- **⚡ Performance 60fps** - Animations sur UI Thread avec react-native-reanimated  
- **📱 Expo Compatible** - Fonctionne parfaitement dans l'environnement Expo
- **🎯 Gestes Intuitifs** - Pan, pinch-to-zoom, inertie fluide
- **🗂️ Cache Intelligent** - Système de cache des tuiles optimisé
- **🔧 TypeScript** - Support complet TypeScript avec types robustes

## 🚀 Installation

```bash
npm install @chauffleet/expo-custom-map
```

### Dépendances requises

```bash
npx expo install react-native-gesture-handler react-native-reanimated
```

## 📖 Utilisation de base

```tsx
import React from 'react';
import { View } from 'react-native';
import { CustomMapView } from '@chauffleet/expo-custom-map';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <CustomMapView
        style={{ flex: 1 }}
        initialRegion={{
          latitude: 48.8566,   // Paris
          longitude: 2.3522,
          latitudeDelta: 0.0922,
          longitudeDelta: 0.0421,
        }}
        tileUrlTemplate="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
        onRegionChange={(region) => console.log('Région:', region)}
        onRegionChangeComplete={(region) => console.log('Fini:', region)}
      >
        {/* Vos composants personnalisés */}
      </CustomMapView>
    </View>
  );
}
```

## 🎛️ Props de CustomMapView

| Prop | Type | Défaut | Description |
|------|------|--------|-------------|
| `initialRegion` | `MapRegion` | Paris | Région initiale de la carte |
| `tileUrlTemplate` | `string` | OpenStreetMap | Template d'URL pour les tuiles |
| `onRegionChange` | `(region: MapRegion) => void` | - | Callback pendant le mouvement |
| `onRegionChangeComplete` | `(region: MapRegion) => void` | - | Callback à la fin du mouvement |
| `style` | `ViewStyle` | - | Style du conteneur |
| `children` | `ReactNode` | - | Éléments enfants (marqueurs, etc.) |

## 🔧 Configuration avancée

### Fournisseurs de tuiles

```tsx
// OpenStreetMap (défaut)
tileUrlTemplate="https://tile.openstreetmap.org/{z}/{x}/{y}.png"

// Mapbox (nécessite une clé API)
tileUrlTemplate="https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=YOUR_TOKEN"

// CartoDB Positron
tileUrlTemplate="https://cartodb-basemaps-a.global.ssl.fastly.net/light_all/{z}/{x}/{y}.png"
```

### Hooks disponibles

```tsx
import { useMapPerformance, useAdvancedTileCache, useFluidGestures } from '@chauffleet/expo-custom-map';

// Monitoring des performances
const { stats, startMonitoring } = useMapPerformance();

// Cache intelligent des tuiles
const { preloadRegion, getCacheStats } = useAdvancedTileCache();

// Gestes personnalisés
const { gestureState } = useFluidGestures({
  enableInertia: true,
  zoomSensitivity: 1.2
});
```

## 🎨 Composants

### TileLayer
Système de rendu des tuiles ultra-optimisé avec cache intelligent.

### MarkerComponent  
Marqueurs personnalisables avec gestion des événements.

### ClusterMarker
Regroupement automatique des marqueurs pour de meilleures performances.

## ⚡ Optimisations

- **UI Thread** - Toutes les animations s'exécutent sur l'UI thread
- **Memoization** - Cache agressif des calculs coûteux
- **Lazy Loading** - Chargement intelligent des tuiles
- **Memory Management** - Gestion automatique de la mémoire
- **Gesture Optimization** - Minimal runOnJS() calls

## 🔧 Développement

```bash
# Cloner le repo
git clone https://github.com/chauffleet/expo-custom-map.git

# Installer les dépendances
npm install

# Compiler
npm run build

# Tester
npm test

# Exemple
npm run example
```

## 📱 Exemples

Voir le fichier `Example.tsx` pour un exemple d'utilisation complète.

## 🐛 Dépannage

### Gestes qui ne fonctionnent pas
Assurez-vous d'avoir installé `react-native-gesture-handler` et suivi la configuration Expo.

### Performance faible
- Vérifiez que react-native-reanimated est correctement configuré
- Utilisez les hooks de performance pour identifier les goulots d'étranglement

### Tuiles qui ne se chargent pas  
Vérifiez le template d'URL des tuiles et votre connexion réseau.

## 📄 Licence

MIT - Voir le fichier [LICENSE](LICENSE)

## 🤝 Contribution

Les contributions sont bienvenues ! Voir [CONTRIBUTING.md](CONTRIBUTING.md)

## 🔗 Liens

- [Documentation complète](https://docs.expo.dev)
- [Exemples](./examples)
- [Issues](https://github.com/chauffleet/expo-custom-map/issues)

---

Développé avec ❤️ pour la communauté React Native et Expo