Arenarium Maps

psychiatry

palette System

database Rentals

Installation

Install the package using the following command:

npm install @arenarium/maps

Import the package in your project and mount the map:

import { mountMap } from '@arenarium/maps';
import '@arenarium/maps/dist/style.css';

const map = mountMap(...);

Add the following script and stylesheet to your HTML:

<script src="https://unpkg.com/@arenarium/maps@latest/dist/index.js"></script>
<link href="https://unpkg.com/@arenarium/maps@latest/dist/style.css" rel="stylesheet" />

Mount the map in your script:

const map = arenarium.mountMap(...);

Usage

Add a container div your HTML:

<div id="map"></div>

Initialize the map with options. To get the api key, sign in and create an API key.

const map = mountMap({
    // The API key
    apiKey: '...',
    // The id of the container element
    container: 'map',
    // The initial position of the map
    position: {
        center: { lat: 51.505, lng: -0.09 },
        zoom: 13
    },
    // The restriction of the map zoom and bounds (optional)
    restriction: {
        minZoom: 10,
        maxZoom: 15,
        maxBounds: {
            sw: { lat: 48.505, lng: -3.09 },
            ne: { lat: 54.505, lng: 3.09 }
        }
    },
    // The style of the map
    style: {
        // The name of the theme used for the map
        name: 'light',
        // The colors used for the content
        colors: { primary: 'darkgreen', background: 'white', text: 'black' }
    }
});

Set the style to a predefined theme:

map.setStyle({ name: 'dark', colors: { primary: 'purple', background: 'darkgray', text: 'black' } });

Or set the style to a custom theme with an URL to the style JSON. The JSON must comply with the MapLibre style specification.

map.setStyle({ 
    name: 'liberty', 
    url: 'https://tiles.openfreemap.org/styles/liberty.json', 
    colors: { primary: 'purple', background: 'white', text: 'black' }
});

Set the popup content callback function:

map.updatePopupContentCallback(async (id) => {
    // Get the popup content and return an HTML element
    const element = await getElement(id);
    return element;
});

Update the popups. The function adds new popups and updates existing ones. It does not remove popups not specified in the array. It is designed to continuously update the popups on the map.

import { type MapPopup } from '@arenarium/maps';

const popups: Types.Popup[] = [];

for (let i = 0; i < count; i++) {
    popups.push({
        id: ...,
        rank: ..,
        lat: ...,
        lng: ...,
        height: ...,
        width: ...
    });
}

await map.updatePopups(popups);

Remove all popups:

await map.removePopups();

Subscribe to map events:

map.on('idle', (position) => { ... });
map.on('move', (position) => { ... });
map.on('click', (coordinate) => { ... });
map.on('popup_click', (id) => { ... });
map.on('loading_start', () => { ... });
map.on('loading_end', () => { ... });

Unsubscribe from events:

map.off(key, handler);

Get the map position:

const position = map.getPosition();
const bounds = map.getBounds();
const zoom = map.getZoom();

Set the map position:

map.setPosition({ center: { lat: 51.505, lng: -0.09 }, zoom: 13 });

Set the map restriction:

map.setMinZoom(10);
map.setMaxZoom(18);
map.setMaxBounds({
    sw: { lat: 51.505, lng: -0.09 },
    ne: { lat: 54.505, lng: 3.09 }
});

About

@arenarium/maps aims to be the best way to show ranked popups on a map. For any situation where you need to show a large amount of popups on a map, where the popups are ranked by some criteria, @arenarium/maps is the best solution.