100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# 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
|