# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`@svrnty/ngx-open-map-wrapper` is an Angular 16+ library that provides a unified map component with automatic fallback between MapLibre GL (WebGL vector maps) and Leaflet (raster maps). The library automatically detects WebGL support and chooses the optimal rendering engine.

## Architecture

### Adapter Pattern

The library uses the **Adapter pattern** to abstract away differences between MapLibre GL and Leaflet:

- **`IMapAdapter`** (map-adapter.interface.d.ts): Common interface defining map operations
- **`LibreAdapter`** (libre-adapter.d.ts): MapLibre GL implementation
- **`LeafletAdapter`** (leaflet-adapter.d.ts): Leaflet implementation
- **`MapFacade`** (map-facade.d.ts): Facade that selects the appropriate adapter based on WebGL support and user preferences

### Component Structure

- **`OpenMapComponent`** (open-map.component.d.ts): Main Angular component that:
  - Uses `WebglDetectionDirective` to detect WebGL support
  - Initializes `MapFacade` with the appropriate adapter
  - Exposes a unified API via input signals and output events
  - Emits `mapReady` event with the `MapFacade` instance

- **`WebglDetectionDirective`** (webgl-detection.directive.d.ts): Directive that detects WebGL support on the user's device and emits the result

### Key Interfaces

**MapOptions**:
- `center: LatLng` - [lat, lng] tuple
- `zoom: number`
- `styleUrl: string` - MapLibre style URL
- `tileUrl: string` - Tile server URL for Leaflet

**Zone** (for delivery/shipping zones):
- `id: string`
- `name?: string`
- `color?: string`
- `opacity?: number`
- `polygon: GeoPoint[]` - Array of {x, y} points
- `shippingFee?: number`
- `deliverySchedule?: string`

**Address** (for popup display):
- `line1, line2, postalCode, subdivision, city, country`
- `shippingFee?: number`
- `deliverySchedule?: string`

### Core APIs

Both adapters implement:
- `init(container, options)` - Initialize map
- `setCenter(latLng)` - Pan to location
- `setZoom(zoom)` - Set zoom level
- `addMarker(latLng, options?)` - Add marker with optional id/color
- `removeMarker(id?)` - Remove specific or all markers
- `addZone(zones)` - Add delivery zones as polygons
- `updateZone(zones)` - Update existing zones
- `openPopup(address)` - Show address popup
- `closePopup()` - Hide popup
- `on(type, event)` - Event listener
- `destroy()` - Cleanup

### Zoom Level Handling

The facade includes a `leafletZoomOffset` property because MapLibre GL and Leaflet use different zoom level scales. When using Leaflet, the facade adjusts zoom levels to maintain visual consistency.

## Development

This is a **compiled Angular library** (not a workspace with source code). The repository contains:
- `/lib` - TypeScript declaration files (.d.ts)
- `/fesm2022` - Compiled ES modules
- `package.json` - Library metadata and peer dependencies

**Peer Dependencies**:
- `@angular/common` and `@angular/core`: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
- `maplibre-gl`: ^5.0.0
- `leaflet`: ^1.0.0 || ^2.0.0

**Installation**:
```bash
yarn add ngx-open-open-map-wrapper leaflet maplibre-gl
```

**CSS Imports Required**:
```css
@import "leaflet/dist/leaflet.css";
@import "maplibre-gl/dist/maplibre-gl.css";
```

## Recent Changes (Current Branch: feature/zone)

Based on git status and recent commits:
- Added `addZone()` and `updateZone()` methods to `IMapAdapter` interface
- Both adapters now support zone management (delivery/shipping zones as polygons)
- Zone objects include shipping fees and delivery schedules for e-commerce use cases