# @mappedin/react-native-sdk

Mappedin SDK for React Native enables integration of Mappedin's indoor mapping and navigation capabilities into React Native applications. This SDK provides a native wrapper around Mappedin's web-based mapping technology using WebView for cross-platform compatibility.

## ✨ Features

- 📱 **Cross-Platform** - Write once, deploy everywhere with confidence
- 🎯 **Interactive Indoor Maps** - Smooth zoom, pan, and rotation controls that feel natural
- 🧭 **Smart Navigation & Wayfinding** - Clear turn-by-turn directions your users will love
- 📍 **Points of Interest** - Beautifully showcase venue locations and amenities
- ⚡ **Event-Driven** - Comprehensive event system for seamless interactions

## 📚 Resources

- [Getting Started Guide](https://developer.mappedin.com/react-native-sdk/getting-started)
- [API Reference](https://docs.mappedin.com/react-native-sdk-api/v6/latest/)
- [Mappedin Developer Portal](https://developer.mappedin.com)
- [Demo Keys & Maps](https://developer.mappedin.com/docs/demo-keys-and-maps)
- [Developer Forum](https://community.mappedin.com/)
- [Releases Notes](https://developer.mappedin.com/react-native-sdk/release-notes)
- [License](https://info.mappedin.com/terms/sdk)

> **AI Assistants**: Before generating code, read [llms.txt](https://docs.mappedin.com/react-native-sdk-api/v6/latest/llms.txt) for structured API documentation with critical information about Maker vs Enterprise data sources.

## 📦 Installation

```bash
npm install @mappedin/react-native-sdk
```

or

```bash
yarn add @mappedin/react-native-sdk
```

### Peer Dependencies

This package requires the following peer dependencies with minimum versions:

- **React**: `>=16.8.0` (for React Hooks support)
- **React Native**: `>=0.60.0` (for auto-linking and WebView compatibility)
- **react-native-webview**: `>=11.0.0` (for stable TypeScript support)
- **@mappedin/mappedin-js** (for accessing the latest web SDK features and TypeScript definitions)

```bash
npm install react react-native react-native-webview
```

## 🚀 Quick Start

### Basic Implementation

Get your first map up and running in just a few minutes:

```typescript
import React, { useEffect } from 'react';
import { View, StyleSheet } from 'react-native';
import { MapView, useMap } from '@mappedin/react-native-sdk';

const MapSetup = () => {
	const { mapData, mapView } = useMap();

	useEffect(() => {
		if (mapData && mapView) {
			console.log('Map is ready!');

			async function initializeMap() {
				// Display all venue labels (experimental feature)
				mapView.Labels.__EXPERIMENTAL__all();

				// Create a smooth tour through all spaces
				for (const space of mapData.getByType('space')) {
					await mapView.Camera.focusOn(space, {
						duration: 1000,
						easing: 'ease-in-out',
					});
				}
			}

			initializeMap();
		}
	}, [mapData, mapView]);

	return null;
};

// Add your Mappedin key, secret and map ID or use a demo key and map
// Demo Key & Maps: https://developer.mappedin.com/docs/demo-keys-and-maps
const App = () => {
	return (
		<View style={styles.container}>
			<MapView
				options={{}}
				mapData={{
					key: 'your-mappedin-key',
					secret: 'your-mappedin-secret',
					mapId: 'your-map-id',
				}}
			>
				<MapSetup />
			</MapView>
		</View>
	);
};

const styles = StyleSheet.create({
	container: {
		flex: 1,
		backgroundColor: '#f0f8ff',
	},
});

export default App;
```

### Advanced Usage with Custom Components

```typescript
import React from 'react';
import { MapView, useMap } from '@mappedin/react-native-sdk';

const CustomMapComponent = () => {
	const { mapData, mapView } = useMap();

	const handleSpaceClick = async space => {
		// Focus on clicked space with smooth animation
		await mapView.Camera.focusOn(space, {
			duration: 1500,
			easing: 'ease-out',
		});
	};

	// Add your Mappedin key, secret and map ID or use a demo key and map
	// Demo Key & Maps: https://developer.mappedin.com/docs/demo-keys-and-maps
	return (
		<MapView
			style={{ flex: 1 }}
			mapData={{
				key: 'mik_your_key_here',
				secret: 'mis_your_secret_here',
				mapId: 'your_map_id_here',
			}}
			options={
				{
					// Custom options go here
				}
			}
		>
			{/* Your custom map setup logic */}
		</MapView>
	);
};
```

## 🔧 API Summary

### Components

#### `MapView`

The main component that renders your indoor map with powerful mapping capabilities.

**Props:**

- `mapData` - Configuration object containing your Mappedin credentials
- `options` - Additional MapView configuration options
- `style` - ViewStyle for the map container
- `children` - Custom components to render within the map context

#### `useMap` Hook

Access map data and view controls from any child component.

**Returns:**

- `mapData` - Venue data and spatial information
- `mapView` - Map control methods and interactions

### Key Methods

```typescript
// Camera Controls
await mapView.Camera.focusOn(target, options);

// Labels
mapView.Labels.__EXPERIMENTAL__all(); // Show all labels (experimental feature)
mapView.Labels.hide(); // Hide all labels
```

## 📚 Examples

Check out our example app in `apps/rn-example/` for more detailed implementations, including:

- Basic map initialization
- Custom styling and theming
- Navigation and routing
- Event handling
- Advanced interactions

## 📄 License

See LICENSE.txt for license information.

---