# 28-Jan-2026 — enhanced area map with legend, shared districts, and neighbouring areas [ref: #129](https://github.com/nbarrett/ngx-ramblers/issues/129)

## [build 440](https://github.com/nbarrett/ngx-ramblers/actions/runs/21460052817) — [commit e07fe70](https://github.com/nbarrett/ngx-ramblers/commit/e07fe7011b9cd7fa9e0e5765e7ff9d7e5eebed71)

_____

## User Guide
### Using the Area Map
**Interactive Legend**
- Hover over any group name in the legend to highlight that group's area on the map
- The highlighted area shows with full opacity and a thicker border for easy identification
- **Extended hover** on a legend item shows the same popup as the map with links to group websites
- Move your mouse away to restore the normal view
**Group Information Popup**
Hover over any area on the map (or legend item) for a moment to see a popup with quick actions:
- **Group Website**
- Opens the group's own website (if they have one)
- **Ramblers Page**
- Opens the official Ramblers group page
- **View Walks**
- Shows walks from that group (for groups in your area)
**Map Controls (Standalone View)**
- Adjust opacity sliders to control how transparent the coloured areas appear
- Use the hover opacity to control how visible areas become when you mouse over them
- Filter which groups appear using the groups dropdown
- Resize the map height by dragging the bottom edge
---
### Initial Setup (System Settings)
These settings are configured once in System Settings > Group Area Settings:
**Neighboring Areas**
- Select which neighbouring Ramblers areas to display alongside your area
- Groups from neighbouring areas will be available on all area maps
- Useful for members who walk with groups in adjacent areas
**Shared District Display Style**
Choose the default style for districts that belong to multiple groups:
- **First Group**
- Shows only the first group's colour (default, cleanest look)
- **Stripes**
- Diagonal stripes in each group's colour
- **Gradient**
- Smooth colour blend across all groups
- **Dashed Border**
- Dashed outline to indicate shared territory
---
### Creating Individual Maps (Site Editor)
When adding an area map content row in the site editor, you can configure:
**New Controls**
- **Groups to Display**
- Multi-select dropdown to filter which groups appear on this map
- **Shared District Display Style**
- Override the system default for this specific map
- **Show Legend**
- Checkbox to enable/disable the group legend
- **Legend Position**
- Dropdown to place the legend (top-left, top-right, bottom-left, bottom-right, or below map)
**Map Display Controls**
- **Map Provider**
- Choose between OpenStreetMap or OS Maps
- **OS Map Style**
- When using OS Maps, select the style (Outdoor, Road, Light, Leisure)
- **Zoom Level**
- Slider to set initial zoom (0-18)
- **Map Height**
- Slider to set map height (300-900px)
- **Vertical/Horizontal**
- Sliders to position the map centre
**Opacity Controls**
- **Normal Opacity**
- How transparent areas appear normally (0.1-1.0)
- **Hover Opacity**
- How visible areas become on hover (0.1-1.0)
- **Text Opacity**
- Visibility of group name labels (0.1-1.0)
**Options**
- **Show map options by default**
- Whether controls are visible when page loads
- **Allow visitors to toggle map options**
- Whether users can show/hide controls
- **Auto-fit map to routes**
- Automatically zoom to fit all areas
- **Reset to Defaults**
- Button to restore all settings to defaults
**Live Preview**
The editor shows a live preview that updates as you change settings.
---
## Technical Details
### New Components
- `LegendPositionSelector`
- Dropdown for selecting legend placement
- `SharedDistrictStyleSelector`
- Dropdown for shared district visualisation mode
### API Changes
- `/api/geojson/areas/:region` now accepts `neighbouringAreaCodes` query parameter
- Response includes `sharedDistricts`, `sharedDistrictStyle`, and `mainAreaGroupCodes`
- Groups include `externalUrl` for non-Ramblers websites
### Configuration Model Changes
- `Organisation.neighbouringAreaCodes`
- Array of area codes to include
- `Organisation.exclusiveDistricts`
- Whether to claim districts exclusively
- `Organisation.sharedDistrictStyle`
- Default style for shared districts
- `AreaMapData.showLegend`
- Toggle legend visibility
- `AreaMapData.legendPosition`
- Legend placement option
- `AreaMapData.sharedDistrictStyle`
- Per-map style override
### New Enums
- `LegendPosition`
- TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, BELOW_MAP
- `SharedDistrictStyle`
- STRIPES, FIRST_GROUP, DASHED_BORDER, GRADIENT
### SVG Pattern Generation
Shared districts using stripes or gradients create dynamic SVG patterns:
- Patterns are generated at runtime and injected into the DOM
- Unique pattern IDs prevent conflicts when multiple maps are present
- Patterns are cleaned up when maps are rebuilt
- Patterns are correctly reapplied after hover events
### DRY Implementation
- `showAreaPopup()` method reused by both map polygon hover and legend item hover
- `areaDataMap` stores area configuration for access from both map and legend interactions
- Separate timeout tracking for map hover (`hoverTimeout`) and legend hover (`legendHoverTimeout`)