amelia-maps v0.1.1

Instalación amelia-ux

Para realizar la instalación de la librería amelia-maps puedes utilizar npm. Abre tu terminal y ejecuta el siguiente comando:

npm install amelia-maps

Componentes

MapProvider

El componente MapProvider es una parte central de nuestra aplicación que nos permite integrar un mapa en ella. Está diseñado para facilitar el uso de mapas en nuestra aplicación y está compuesto por dos propiedades principales:

1. Token: Esta propiedad es una cadena de caracteres (string) que representa el token de acceso de MapBox GL. MapBox GL es una plataforma que proporciona herramientas para trabajar con mapas interactivos y visualizaciones geoespaciales. El token de acceso es necesario para autenticar nuestra aplicación y utilizar los servicios de MapBox GL.

2. Options: Esta propiedad inicializa nuestro mapa con valores predeterminados. Contiene tres subpropiedades opcionales:

   • Center: Es un arreglo de números (number[]) que representa las coordenadas de la ubicación inicial del mapa. Esta coordenada central determina dónde se centrará inicialmente el mapa cuando se cargue.
   • Style: Es una cadena de caracteres (string) que especifica el estilo del mapa. MapBox GL ofrece una variedad de temas de mapas para elegir, como mapas de calles, mapas topográficos, mapas satelitales, entre otros.
   • Zoom: Es un número (number) que indica el nivel de zoom inicial del mapa. El zoom determina cuán cerca o lejos está el mapa de la superficie de la Tierra cuando se carga inicialmente.

En el caso de que no se proporcione ningún objeto options, el componente utilizará valores predeterminados para inicializar el mapa. Estos valores predeterminados son los siguientes:

• Style: "mapbox://styles/mapbox/satellite-streets-v12" (un estilo que combina elementos de mapas satelitales y de calles).
• Center: -74.5, 40 (coordenadas que apuntan a una ubicación específica, en este caso, alrededor de la ciudad de Nueva York).
• Zoom: 9 (un nivel de zoom medio que muestra una cantidad moderada de detalle del mapa).

Map

El componente MapProvider, solamente incializa MapBox GL y el mapa pero no se encarga de mostrarlo ni crearlo. Para ello, utilizamos el componente Map.

Ejemplo de uso

import { MapProvider, Map } from 'amelia-maps'

const App = () => {
    return <MapProvider token={process.env.mapbox_token}>
        <Map />
    </MapProvider>
}

Hooks

Para aprovechar al máximo las funcionalidades proporcionadas por MapBox GL, ofrecemos una serie de hooks personalizados. Estos hooks están diseñados para facilitar la configuración del mapa de acuerdo con los requisitos específicos de nuestra aplicación, adaptándose a medida que sea necesario.

UseCenter

Este hook nos brinda la capacidad de centrar el mapa en un conjunto de coordenadas específicas. Recibe las siguientes propiedades:

• coords: (number[] | number). Representa las coordenadas que deseamos visualizar en el mapa. Si se proporciona una sola coordenada, el mapa se centrará en esa posición. En cambio, si se proporcionan múltiples coordenadas, el hook ajustará automáticamente el zoom para que todas las coordenadas sean visibles en pantalla.
• maxZoom (opcional): (number) Indica el zoom máximo que deseamos aplicar al mapa. Este parámetro nos permite controlar el nivel máximo de detalle que se mostrará en el mapa. Si no se especifica, el zoom se ajustará automáticamente según las coordenadas proporcionadas.

UseZoom

Este hook nos proporciona la capacidad de establecer un nivel de zoom específico en nuestro mapa. Acepta las siguientes propiedades:

• zoom: (number) Indica el nivel de zoom que se aplicará al mapa.

UseMarkers

Este hook nos permite agregar marcadores personalizados a nuestro mapa. Acepta las siguientes propiedades:

• marker: (Marker | Marker[]) Representa los marcadores que deseamos mostrar en el mapa.

La estructura de un marcador debe seguir este formato:

type Marker = {
  id: string
  coords: number[]
  image?: string
  onClick?: () => void
}

Donde:

• id: (string) Identificador único del marcador.
• coords: (number[]) Coordenadas del marcador en formato longitud, latitud.
• image (opcional): (string) URL de la imagen a utilizar como ícono del marcador.
• onClick (opcional): (() => void) Función que se ejecuta al hacer clic en el marcador.

UseOrtophoto

Este hook nos permite mostrar una ortofoto en nuestro mapa. Acepta las siguientes propiedades:

• ortophoto: (Ortophoto) Representa la ortofoto que deseamos mostrar en el mapa.

La estructura de una ortophoto debe seguir este formato:

type Ortophoto = {
  id: string
  coords: number[][]
  image: string
}

Donde:

• id: (string) Identificador único de la ortofoto.
• coords: (number) Coordenadas de la ortofoto en formato longitud, latitud
• image (opcional): (string) URL de la imagen que se utilizará para representar la ortofoto en el mapa.

Polygons

Este componente nos proporciona la capacidad de crear y agregar polígonos a nuestro mapa. Recibe los siguientes atributos:

• editable: (boolean) Indica si los polígonos se pueden editar o no.

Ambos tipos de polígonos heredan de una estructura general llamada Polygon, que se define de la siguiente manera:

type Polygon = {
  id: string
  coords: number[][]
  style?: Style
  onClick?: () => void
}

A partir de esta definición, tenemos dos opciones dependiendo del valor de editable, que puede ser 'false' o 'true'.

En caso de ser 'false', solo necesitamos especificar la siguiente propiedad adicional:

• polygons: (FixedPolygon | FixedPolygon[]) Representa los polígonos que se mostrarán en el mapa.
• defaultStyle (opcional): Indica el estilo genérico que deben seguir los polígonos.

La estructura de un polígono fijo (FixedPolygon) debe seguir este formato:

type FixedPolygon = Omit<Polygon, "style"> & {
  style?: Pick<Style, "label">
}

En caso de ser 'true', solo necesitamos especificar las siguientes propiedades adicionales:

• polygons: (EditablePolygon | EditablePolygon[]) Representa los polígonos que se mostrarán en el mapa.
• onEdit: ((polygons: EditedPolygons) => void) Callback que devuelve los nuevos polígonos después de editarlos, incluidos los creados, actualizados y eliminados.
• isEditing (opcional): (boolean) Se utiliza para manejar el estado de edición desde fuera del propio componente.
• isSaved (opcional): (boolean) Se utiliza para manejar el estado de guardado desde fuera del propio componente.
• creationArea (opcional): (number) Áreas que delimitan la creación de polígonos.

La estructura de un polígono editable (EditablePolygon) debe seguir este formato:

export type EditablePolygon = Polygon