svrnty/ngx-open-map-wrapper
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
feature/zone
ngx-open-map-wrapper/CLAUDE.md

3.6 KiB
Raw Permalink Blame History

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:

yarn add ngx-open-open-map-wrapper leaflet maplibre-gl

CSS Imports Required:

@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