152 lines
6.5 KiB
Markdown
152 lines
6.5 KiB
Markdown
|
# Project Hints - dees-catalog-geo
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
Geospatial web components library using MapLibre GL JS for map rendering and terra-draw for drawing capabilities.
|
||
|
|
|
||
|
|
## Key Dependencies
|
||
|
|
- **maplibre-gl** (v5.x): WebGL-based vector map library
|
||
|
|
- **terra-draw** (v1.24.0): Modern drawing library with support for multiple map libraries
|
||
|
|
- **terra-draw-maplibre-gl-adapter** (v1.x): Adapter connecting terra-draw with MapLibre
|
||
|
|
|
||
|
|
## Component: dees-geo-map
|
||
|
|
|
||
|
|
### Properties
|
||
|
|
| Property | Type | Default | Description |
|
||
|
|
|----------|------|---------|-------------|
|
||
|
|
| `center` | `[number, number]` | `[0, 0]` | Map center as [lng, lat] |
|
||
|
|
| `zoom` | `number` | `2` | Initial zoom level |
|
||
|
|
| `mapStyle` | `string` | `'osm'` | Map style ('osm' or custom URL) |
|
||
|
|
| `activeTool` | `TDrawTool` | `'static'` | Active drawing tool |
|
||
|
|
| `geoJson` | `GeoJSON.FeatureCollection` | `{...}` | Initial features |
|
||
|
|
| `showToolbar` | `boolean` | `true` | Show/hide drawing toolbar |
|
||
|
|
| `projection` | `'mercator' \| 'globe'` | `'mercator'` | Map projection type |
|
||
|
|
| `showSearch` | `boolean` | `false` | Show address search input |
|
||
|
|
| `showNavigation` | `boolean` | `false` | Show A-to-B navigation panel |
|
||
|
|
| `navigationMode` | `'driving' \| 'walking' \| 'cycling'` | `'driving'` | Transport mode for routing |
|
||
|
|
|
||
|
|
### Drawing Tools (TDrawTool)
|
||
|
|
- `point` - Draw points
|
||
|
|
- `linestring` - Draw lines
|
||
|
|
- `polygon` - Draw polygons
|
||
|
|
- `rectangle` - Draw rectangles
|
||
|
|
- `circle` - Draw circles
|
||
|
|
- `freehand` - Freehand drawing
|
||
|
|
- `select` - Select and edit features
|
||
|
|
- `static` - Pan/zoom only (no drawing)
|
||
|
|
|
||
|
|
### Events
|
||
|
|
- `map-ready` - Fired when map is initialized
|
||
|
|
- `map-move` - Fired on pan/zoom with center and zoom
|
||
|
|
- `draw-change` - Fired on any feature change
|
||
|
|
- `draw-finish` - Fired when a shape is completed
|
||
|
|
- `address-selected` - Fired when a search result is selected
|
||
|
|
- `route-calculated` - Fired when a navigation route is calculated (includes route, startPoint, endPoint, mode)
|
||
|
|
|
||
|
|
### Public Methods
|
||
|
|
- `getFeatures()` - Get all drawn features
|
||
|
|
- `getGeoJson()` - Get features as FeatureCollection
|
||
|
|
- `loadGeoJson(geojson)` - Load features from GeoJSON
|
||
|
|
- `clearAllFeatures()` - Remove all features
|
||
|
|
- `setTool(tool)` - Set active drawing tool
|
||
|
|
- `flyTo(center, zoom?)` - Animate to location
|
||
|
|
- `fitToFeatures(padding?)` - Fit view to all features
|
||
|
|
- `setProjection(projection)` - Set map projection ('mercator' or 'globe')
|
||
|
|
- `getMap()` - Get underlying MapLibre instance
|
||
|
|
- `getTerraDraw()` - Get TerraDraw instance
|
||
|
|
- `calculateRoute()` - Calculate route between start and end points
|
||
|
|
- `setNavigationStart(coords, address?)` - Set navigation start point
|
||
|
|
- `setNavigationEnd(coords, address?)` - Set navigation end point
|
||
|
|
- `clearNavigation()` - Clear all navigation state
|
||
|
|
|
||
|
|
### Context Menu
|
||
|
|
Right-click on the map to access a context menu with the following options:
|
||
|
|
- **Drag to Draw** - Toggle between drag mode (click-drag for circles/rectangles) and two-click mode
|
||
|
|
- **Globe View** - Toggle between globe (3D sphere) and Mercator (flat) projection
|
||
|
|
- **Clear All Features** - Remove all drawn features from the map
|
||
|
|
- **Fit to Features** - Zoom and pan to show all drawn features
|
||
|
|
|
||
|
|
### Navigation Feature
|
||
|
|
The navigation panel (`showNavigation={true}`) provides A-to-B routing using OSRM (Open Source Routing Machine):
|
||
|
|
- **Transport modes**: Driving, Walking, Cycling
|
||
|
|
- **Point selection**: Type an address or click on the map
|
||
|
|
- **Route display**: Blue line overlay with turn-by-turn directions
|
||
|
|
- **API**: Uses free OSRM API (https://router.project-osrm.org) with fair-use rate limit
|
||
|
|
|
||
|
|
## Development
|
||
|
|
- `pnpm install` - Install dependencies
|
||
|
|
- `pnpm watch` - Start development server (port 3002)
|
||
|
|
- `pnpm build` - Build for production
|
||
|
|
|
||
|
|
## File Structure
|
||
|
|
```
|
||
|
|
ts_web/
|
||
|
|
├── index.ts # Main exports
|
||
|
|
├── 00_commitinfo_data.ts # Auto-generated
|
||
|
|
└── elements/
|
||
|
|
├── index.ts # Elements barrel
|
||
|
|
├── 00colors.ts # Color definitions
|
||
|
|
├── 00componentstyles.ts # Shared styles
|
||
|
|
└── 00group-map/
|
||
|
|
├── index.ts
|
||
|
|
└── dees-geo-map/
|
||
|
|
├── index.ts # Exports main + modules
|
||
|
|
├── dees-geo-map.ts # Main component (~550 lines)
|
||
|
|
├── dees-geo-map.demo.ts # Demo function
|
||
|
|
├── geo-map.icons.ts # Icon SVG definitions (~60 lines)
|
||
|
|
├── geo-map.search.ts # SearchController class (~180 lines)
|
||
|
|
└── geo-map.navigation.ts # NavigationController class (~530 lines)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Modular Architecture
|
||
|
|
The component was refactored for better maintainability:
|
||
|
|
|
||
|
|
### geo-map.icons.ts
|
||
|
|
Contains all SVG icon definitions as a `GEO_MAP_ICONS` record and a `renderIcon(name)` helper function.
|
||
|
|
|
||
|
|
### geo-map.search.ts
|
||
|
|
`SearchController` class encapsulating Nominatim geocoding search:
|
||
|
|
- Reusable for standalone search or within navigation
|
||
|
|
- Debounced API calls
|
||
|
|
- Keyboard navigation support
|
||
|
|
- Customizable via `ISearchControllerConfig`
|
||
|
|
|
||
|
|
### geo-map.navigation.ts
|
||
|
|
`NavigationController` class for A-to-B routing:
|
||
|
|
- OSRM routing API integration
|
||
|
|
- Start/end point management with markers
|
||
|
|
- Map click mode for point selection
|
||
|
|
- Turn-by-turn directions rendering
|
||
|
|
- Route overlay on map
|
||
|
|
|
||
|
|
### Usage of Controllers
|
||
|
|
```typescript
|
||
|
|
// SearchController is reusable
|
||
|
|
const search = new SearchController(
|
||
|
|
{ placeholder: 'Search...' },
|
||
|
|
{
|
||
|
|
onResultSelected: (result, coords, zoom) => { /* handle */ },
|
||
|
|
onRequestUpdate: () => this.requestUpdate(),
|
||
|
|
}
|
||
|
|
);
|
||
|
|
|
||
|
|
// NavigationController manages all navigation state
|
||
|
|
const nav = new NavigationController({
|
||
|
|
onRouteCalculated: (event) => { /* dispatch */ },
|
||
|
|
onRequestUpdate: () => this.requestUpdate(),
|
||
|
|
getMap: () => this.map,
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Notes
|
||
|
|
- MapLibre CSS is loaded dynamically from CDN
|
||
|
|
- Terra-draw requires the separate maplibre-gl-adapter package
|
||
|
|
- The component uses Shadow DOM for style encapsulation
|
||
|
|
|
||
|
|
### Shadow DOM & Terra-Draw Drawing Fix
|
||
|
|
Terra-draw's event listeners normally intercept map events through MapLibre's canvas element. In Shadow DOM contexts, these events are scoped locally and don't propagate correctly, causing terra-draw handlers to fail while MapLibre's drag handlers continue working.
|
||
|
|
|
||
|
|
**Solution**: Manual drag coordination in `setTool()`:
|
||
|
|
- When a drawing tool is active (`polygon`, `rectangle`, `point`, `linestring`, `circle`, `freehand`), MapLibre's `dragPan` and `dragRotate` are disabled
|
||
|
|
- When `static` or `select` mode is active, dragging is re-enabled
|
||
|
|
- The `TerraDrawMapLibreGLAdapter` does NOT accept a `lib` parameter - only `map` is required
|