npm package: @hamuga/imap-react-native
Description: Hamuga iMap SDK for React Native
Author: Hamuga
Latest version: 1.0.1

# @hamuga/imap-react-native

Hamuga iMap SDK for React Native.

This package exposes:

- `HamugaMap` for map rendering with built-in search UI
- re-exports from `@hamuga/imap-core` for convenience

Shared ecosystem packages:

- `@hamuga/imap-core`
- `@hamuga/imap-react-native`

## Prerequisites

Before integrating this SDK, make sure your app environment includes:

- React Native app project
- Node.js 18+
- React Native Safe Area Context installed
- Xcode + CocoaPods for iOS builds
- Android Studio + Android SDK for Android builds
- iOS deployment target 13.0 or higher

This repository is currently aligned with:

- React `18.2.0`
- React Native `0.72.6`

## Architecture Compatibility

This package does not ship a custom native module or native view in the npm
tarball. The public SDK surface is JavaScript on top of these peer native
dependencies:

- `@maplibre/maplibre-react-native`
- `react-native-safe-area-context`
- `react-native-svg`

Because of that, this package can be used from both the old architecture
(Paper) and the new architecture (Fabric/TurboModules) as long as those peer
dependencies are compatible with the host app's React Native setup.

## Installation

Install the package and its peer dependencies:

```sh
npm install @hamuga/imap-react-native @maplibre/maplibre-react-native react-native-safe-area-context react-native-svg
```

or

```sh
yarn add @hamuga/imap-react-native @maplibre/maplibre-react-native react-native-safe-area-context react-native-svg
```

This package expects these libraries to be installed in the host app so React Native autolinking can wire their native code correctly:

- `@maplibre/maplibre-react-native`
- `react-native-safe-area-context`
- `react-native-svg`

There is no additional autolinked native code from `@hamuga/imap-react-native`
itself.

For iOS, install pods after dependency changes in the app:

```sh
cd ios && pod install
```

## Native Dependencies

`HamugaMap` is built on top of:

- `@maplibre/maplibre-react-native`
- `react-native-svg`
- `react-native-safe-area-context`

If your app already uses these packages, keep the versions compatible with this SDK.

## Usage

### Map Component

```tsx
import React, { useRef } from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import {
  HamugaMap,
  type HamugaMapRef,
} from '@hamuga/imap-react-native';

export function MyMapScreen() {
  const mapRef = useRef<HamugaMapRef>(null);

  const handleSearch = async () => {
    const results = await mapRef.current?.getPoi({ query: 'restaurant' });
    console.log(results);
  };

  return (
    <SafeAreaProvider>
      <HamugaMap
        ref={mapRef}
        apiKey="YOUR_HAMUGA_API_KEY"
        search
        center={[106.9163, 47.9191]}
        zoom={14}
      />
    </SafeAreaProvider>
  );
}
```

### Global Initialization

If you prefer not to pass `apiKey` on every usage, initialize the SDK once:

```tsx
import { HamugaApi } from '@hamuga/imap-react-native';

HamugaApi.initialize({
  apiKey: 'YOUR_HAMUGA_API_KEY',
});
```

Then:

```tsx
<HamugaMap search />
```

### Standalone Gateway Client

```tsx
import { createHamugaSearchClient } from '@hamuga/imap-core';

const client = createHamugaSearchClient({
  apiKey: 'YOUR_HAMUGA_API_KEY',
});

async function search() {
  const suggestion = await client.getSuggest('central');
  const pois = await client.getPoi({ query: 'coffee' });
  const route = await client.planRoute({
    from: [106.9, 47.9],
    to: [106.91, 47.92],
    mode: 'WALK',
  });

  console.log({ suggestion, pois, route });
}
```

## API Overview

### `HamugaMap` props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `apiKey` | `string` | optional when `HamugaApi.initialize()` was called | Hamuga gateway API key |
| `center` | `[number, number]` | `[106.9163376, 47.919118]` | `[longitude, latitude]` |
| `zoom` | `number` | `14.5` | Initial zoom |
| `mapStyle` | `string \| object` | `https://cdn.hamuga.mn/mobile.json` | Custom map style |
| `search` | `boolean` | `false` | Enables the search panel |
| `searchWithinViewport` | `boolean` | `false` | Restricts POI search to current viewport |
| `searchPlaceholder` | `string` | `Байршил хайх...` | Search input placeholder |
| `gatewayBaseUrl` | `string` | `https://gateway.hamuga.mn` | Custom gateway base URL |
| `showZoomControls` | `boolean` | `false` | Shows zoom buttons |
| `showCompassControl` | `boolean` | `false` | Shows compass button |
| `showMyLocationButton` | `boolean` | `true` | Shows my-location button |
| `showScaleBar` | `boolean` | `false` | Shows scale bar |
| `enableHapticFeedback` | `boolean` | `false` | Enables haptics where supported |

### `HamugaMapRef`

- `suggest(query)`
- `getSuggest(query)`
- `searchPois(options)`
- `getPoi(options)`
- `planRoute(options)`
- `calculateRoute(options)`

### Search client

`createHamugaSearchClient()` returns the same gateway methods exposed through the map ref:

- `suggest(query)`
- `getSuggest(query)`
- `searchPois(options)`
- `getPoi(options)`
- `planRoute(options)`
- `calculateRoute(options)`

Use `@hamuga/imap-core` directly if you need gateway access without the React Native UI package.

## Example App

The local example app lives under `example/`.

Typical workflow:

```sh
yarn install
yarn workspace hamuga-imap-example start
```

In another terminal:

```sh
yarn workspace hamuga-imap-example ios
```

or

```sh
yarn workspace hamuga-imap-example android
```

## Publish Checklist

Before publishing a new version:

```sh
yarn verify
npm pack --dry-run
```

Publish to npm:

```sh
npm publish
```

## License

Apache-2.0