npm package: @litforge/arcgis-map
Description: A Lit web component for displaying ArcGIS maps with support for loading layers from ArcGIS Portal.
Latest version: 0.1.22

# @litforge/arcgis-map

A Lit web component for displaying ArcGIS maps with support for loading layers from ArcGIS Portal.

## Overview

The `ArcGISMap` component provides a wrapper around the ArcGIS Maps SDK for JavaScript, allowing you to easily embed interactive maps in your web applications. It supports:

- Loading layers from ArcGIS Portal
- Customizable basemaps
- Configurable zoom and center
- Loading and error states
- Event handling for map lifecycle
- **Layer visibility control** - Show/hide specific layers
- **Client-side layers** - Add GeoJSON, arrays, or CSV data as map layers
- **Programmatic layer management** - Add, remove, and update layers dynamically

## Installation

```bash
npm install @litforge/arcgis-map @arcgis/core
# or
pnpm add @litforge/arcgis-map @arcgis/core
# or
yarn add @litforge/arcgis-map @arcgis/core
```

## Basic Usage

```html
<script type="module">
  import '@litforge/arcgis-map';
</script>

<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  basemap="streets-vector"
  zoom="10"
  height="600px"
></arcgis-map>
```

### Using JavaScript Properties

```html
<arcgis-map id="myMap"></arcgis-map>
<script>
  const map = document.getElementById('myMap');
  map.layerIds = ['5a1de28a045f4848b7a5476b1a375dd0'];
  map.center = [-0.0500, 39.9833]; // Castellón de la Plana, Spain
  map.zoom = 10;
</script>
```

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `portal-url` | `string` | `'https://devgis.waternology.es/portal'` | URL of the ArcGIS Portal |
| `layer-ids` | `string[]` | `['5a1de28a045f4848b7a5476b1a375dd0']` | Array of layer IDs to load from the portal |
| `basemap` | `string` | `'streets-vector'` | Basemap style (streets-vector, satellite, hybrid, topo-vector, etc.) |
| `center` | `[number, number]` | `[-0.0500, 39.9833]` | Initial map center coordinates [longitude, latitude] (default: Castellón de la Plana) |
| `zoom` | `number` | `10` | Initial zoom level (1-20) |
| `height` | `string` | `'100%'` | Height of the map container |
| `width` | `string` | `'100%'` | Width of the map container |
| `api-key` | `string` | `undefined` | ArcGIS API key (optional, for authenticated requests) |
| `visible-layers` | `string[]` | `[]` | Array of layer IDs that should be visible. If empty, all layers are visible |
| `client-layers` | `ClientLayerConfigUnion[]` | `[]` | Array of client-side layer configurations (GeoJSON, arrays, or CSV) |

## Events

| Event | Detail | Description |
|-------|--------|-------------|
| `map-ready` | `{ mapView: MapView, map: Map }` | Fired when the map is fully loaded and ready |
| `map-error` | `{ error: string, originalError: any }` | Fired when an error occurs during map initialization |
| `layer-visibility-change` | `{ layerId: string, visible: boolean }` | Fired when a layer's visibility changes |
| `layer-added` | `{ layerId: string, layer: Layer }` | Fired when a new layer is added to the map |
| `layer-removed` | `{ layerId: string }` | Fired when a layer is removed from the map |

## Examples

### Basic Map with Default Layer

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
></arcgis-map>
```

### Custom Basemap and Zoom

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  basemap="satellite"
  zoom="12"
></arcgis-map>
```

### Multiple Layers

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0", "another-layer-id"]'
></arcgis-map>
```

### Custom Center Coordinates

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  center='[-0.0500, 39.9833]'
  zoom="12"
></arcgis-map>
```

**Note:** The default center is Castellón de la Plana, Comunidad Valenciana, Spain.

### With Event Handlers

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  @map-ready=${(e) => {
    console.log('Map loaded:', e.detail.mapView);
  }}
  @map-error=${(e) => {
    console.error('Map error:', e.detail.error);
  }}
></arcgis-map>
```

### Custom Size

```html
<div style="width: 800px; height: 600px;">
  <arcgis-map
    portal-url="https://devgis.waternology.es/portal"
    layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
    height="600px"
    width="800px"
  ></arcgis-map>
</div>
```

### Layer Visibility Control

Control which layers are visible using the `visible-layers` attribute:

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["layer-id-1", "layer-id-2", "layer-id-3"]'
  visible-layers='["layer-id-1", "layer-id-3"]'
></arcgis-map>
```

Only `layer-id-1` and `layer-id-3` will be visible. If `visible-layers` is empty or not provided, all layers are visible by default.

### Client-Side Layers

Add layers from your own data sources:

#### GeoJSON Layer

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "custom-points",
    "type": "geojson",
    "title": "Custom Points",
    "visible": true,
    "data": {
      "type": "FeatureCollection",
      "features": [{
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-0.05, 39.98]
        },
        "properties": {
          "name": "Castellón"
        }
      }]
    }
  }]'
></arcgis-map>
```

#### Array Layer

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "array-points",
    "type": "array",
    "title": "Array Points",
    "visible": true,
    "geometryType": "point",
    "data": [
      { "lat": 39.98, "lng": -0.05, "name": "Point 1", "value": 10 },
      { "lat": 39.99, "lng": -0.06, "name": "Point 2", "value": 20 }
    ]
  }]'
></arcgis-map>
```

#### CSV Layer

```html
<arcgis-map
  portal-url="https://devgis.waternology.es/portal"
  layer-ids='["5a1de28a045f4848b7a5476b1a375dd0"]'
  client-layers='[{
    "id": "csv-points",
    "type": "csv",
    "title": "CSV Points",
    "visible": true,
    "latField": "lat",
    "lngField": "lng",
    "data": "name,lat,lng,value\nPoint A,39.98,-0.05,100\nPoint B,39.99,-0.06,200"
  }]'
></arcgis-map>
```

## Styling

The component uses CSS variables for theming:

```css
arcgis-map {
  --lf-arcgis-map-min-height: 400px;
  --lf-arcgis-map-font-family: system-ui, Arial, sans-serif;
  --lf-arcgis-map-loading-bg: #f3f4f6;
  --lf-arcgis-map-loading-text: #6b7280;
  --lf-arcgis-map-error-bg: #fee2e2;
  --lf-arcgis-map-error-text: #dc2626;
}
```

## TypeScript

```typescript
import { ArcGISMap } from '@litforge/arcgis-map';
import type { 
  ArcGISMapProps,
  GeoJSONLayerConfig,
  ArrayLayerConfig,
  CSVLayerConfig 
} from '@litforge/arcgis-map';

const props: ArcGISMapProps = {
  portalUrl: 'https://devgis.waternology.es/portal',
  layerIds: ['5a1de28a045f4848b7a5476b1a375dd0'],
  basemap: 'streets-vector',
  center: [-0.0500, 39.9833], // Castellón de la Plana
  zoom: 10,
  height: '600px',
  width: '100%',
  visibleLayerIds: ['5a1de28a045f4848b7a5476b1a375dd0'],
  clientLayers: [
    {
      id: 'custom-layer',
      type: 'geojson',
      title: 'Custom Layer',
      visible: true,
      data: {
        type: 'FeatureCollection',
        features: []
      }
    } as GeoJSONLayerConfig
  ]
};
```

## Programmatic Access

### MapView Access

You can access the MapView instance programmatically:

```typescript
const mapElement = document.querySelector('arcgis-map') as ArcGISMap;
const mapView = mapElement.getMapView();

if (mapView) {
  // Use MapView API
  mapView.goTo({
    center: [-3.7038, 40.4168],
    zoom: 12
  });
}
```

### Layer Management Methods

#### Visibility Control

```typescript
const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Show/hide a specific layer
mapElement.setLayerVisible('layer-id', true);
mapElement.setLayerVisible('layer-id', false);

// Get a layer by ID
const layer = mapElement.getLayer('layer-id');

// Get all layers
const allLayers = mapElement.getAllLayers();

// Get only visible layers
const visibleLayers = mapElement.getVisibleLayers();
```

#### Adding Client Layers

```typescript
const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Wait for map to be ready
mapElement.addEventListener('map-ready', async () => {
  // Add GeoJSON layer
  await mapElement.addClientLayer({
    id: 'my-geojson-layer',
    type: 'geojson',
    title: 'My GeoJSON Layer',
    visible: true,
    data: {
      type: 'FeatureCollection',
      features: [/* ... */]
    }
  });

  // Add array layer
  await mapElement.addClientLayer({
    id: 'my-array-layer',
    type: 'array',
    title: 'My Array Layer',
    visible: true,
    geometryType: 'point',
    data: [
      { lat: 39.98, lng: -0.05, name: 'Point 1' },
      { lat: 39.99, lng: -0.06, name: 'Point 2' }
    ]
  });

  // Add CSV layer
  await mapElement.addClientLayer({
    id: 'my-csv-layer',
    type: 'csv',
    title: 'My CSV Layer',
    visible: true,
    latField: 'lat',
    lngField: 'lng',
    data: 'name,lat,lng\nPoint A,39.98,-0.05'
  });
});
```

#### Removing and Updating Layers

```typescript
const mapElement = document.querySelector('arcgis-map') as ArcGISMap;

// Remove a client layer
mapElement.removeClientLayer('my-layer-id');

// Update layer properties
await mapElement.updateClientLayer('my-layer-id', {
  visible: false,
  opacity: 0.5,
  title: 'Updated Title'
});
```

## Basemap Options

Available basemap options:
- `streets-vector` - Street map (default)
- `satellite` - Satellite imagery
- `hybrid` - Satellite with labels
- `topo-vector` - Topographic map
- `gray-vector` - Light gray canvas
- `dark-gray-vector` - Dark gray canvas
- `oceans` - Ocean basemap
- `osm` - OpenStreetMap

## Dependencies

This component requires the ArcGIS Maps SDK for JavaScript:

```bash
pnpm add @arcgis/core
```

The SDK is externalized in the build, so it must be available at runtime. Make sure to include it in your application bundle or load it via CDN.

## License

Part of the LitForge component library.