@angular-helpers/openlayers 0.2.0 → 0.4.0

package/README.md

@@ -97,6 +97,173 @@ export class MapComponent {
 }
 ```
 
+## Overlays — popups and tooltips
+
+Available since `0.3.0` from `@angular-helpers/openlayers/overlays`.
+
+### `<ol-popup>` — declarative popup with content projection
+
+The popup's host element is used directly as the underlying `ol/Overlay` element, so projected children stay inside Angular's view tree and benefit from change detection without any extra plumbing.
+
+```typescript
+import { OlPopupComponent } from '@angular-helpers/openlayers/overlays';
+
+@Component({
+  imports: [OlMapComponent, OlVectorLayerComponent, OlPopupComponent],
+  template: `
+    <ol-map [center]="[2.17, 41.38]" [zoom]="12">
+      <ol-vector-layer id="cities" [features]="cities()" />
+
+      <ol-popup
+        [position]="selectedCoord()"
+        [closeButton]="true"
+        [autoPan]="true"
+        (closed)="clearSelection()"
+      >
+        <h3>{{ selected()?.name }}</h3>
+        <p>{{ selected()?.description }}</p>
+      </ol-popup>
+    </ol-map>
+  `,
+})
+export class MyMap {
+  // …
+}
+```
+
+Setting `[position]="null"` hides the popup and emits `closed`.
+
+### `[olTooltip]` — feature hover tooltip
+
+```html
+<ol-vector-layer
+  id="cities"
+  [features]="cities()"
+  [olTooltip]="'name'"
+  [olTooltipLayer]="'cities'"
+/>
+```
+
+Reads `feature.get('name')` for any feature on layer `cities` under the cursor and renders a styled `<div role="tooltip">` near the pointer. Use the `.ol-tooltip` class to override the default look.
+
+### `OlPopupService` — programmatic popups
+
+Three content modes from a service:
+
+```typescript
+const popups = inject(OlPopupService);
+
+// 1) Plain text / HTMLElement
+popups.open({
+  id: 'simple',
+  position: [2.17, 41.38],
+  content: 'Hello map',
+  positioning: 'bottom-center',
+  autoPan: true,
+});
+
+// 2) Dynamic Angular component (createComponent + hostElement)
+const handle = popups.openComponent({
+  id: 'city-popup',
+  position: [2.17, 41.38],
+  component: CityCardComponent,
+  bindings: [
+    inputBinding('city', () => selected()),
+    outputBinding<void>('closed', () => handle.close()),
+  ],
+});
+```
+
+`open` is idempotent by `id` and updates the existing overlay in place. `openComponent` always recreates the `ComponentRef` on a repeated id and disposes the previous one (`appRef.detachView` + `ref.destroy`) to avoid CD leaks. Calls made before the map is ready are queued and replayed on `OlMapService.onReady`.
+
+## Military symbology
+
+Available since `0.4.0` from `@angular-helpers/openlayers/military`.
+
+Three pure-math geometry helpers (no extra deps) plus a NATO MIL-STD-2525 symbol helper backed by the optional [`milsymbol`](https://github.com/spatialillusions/milsymbol) peer dependency.
+
+```typescript
+import { inject, signal } from '@angular/core';
+import { OlMilitaryService } from '@angular-helpers/openlayers/military';
+import type { Feature } from '@angular-helpers/openlayers/core';
+
+@Component({
+  // …
+  imports: [OlMapComponent, OlVectorLayerComponent],
+  template: `
+    <ol-map [center]="[2.17, 41.38]" [zoom]="8">
+      <ol-tile-layer id="osm" source="osm" />
+      <ol-vector-layer id="military" [features]="features()" [zIndex]="10" />
+    </ol-map>
+  `,
+})
+export class MilDemo {
+  private ml = inject(OlMilitaryService);
+  features = signal<Feature[]>([]);
+
+  async ngOnInit() {
+    const ellipse = this.ml.createEllipse({
+      center: [2.17, 41.38],
+      semiMajor: 6_000,
+      semiMinor: 3_000,
+      rotation: Math.PI / 6,
+    });
+    const sector = this.ml.createSector({
+      center: [-0.38, 39.47],
+      radius: 8_000,
+      startAngle: Math.PI / 6,
+      endAngle: Math.PI / 2,
+    });
+    const donut = this.ml.createDonut({
+      center: [-5.99, 37.39],
+      innerRadius: 5_000,
+      outerRadius: 10_000,
+    });
+    const symbol = await this.ml.createMilSymbol({
+      sidc: 'SFGPUCI-----',
+      position: [-3.7, 40.42],
+      size: 36,
+    });
+    this.features.set([ellipse, sector, donut, symbol]);
+  }
+}
+```
+
+### Geometry helpers
+
+| Method                  | Output             | Notes                                                                                                                  |
+| ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `createEllipse(config)` | `Feature<Polygon>` | Optional `rotation` in radians, configurable `segments` (default 64)                                                   |
+| `createSector(config)`  | `Feature<Polygon>` | Pie-slice (apex-arc-apex). `startAngle < endAngle ≤ start + 2π`                                                        |
+| `createDonut(config)`   | `Feature<Polygon>` | Two rings: outer CCW, inner CW (right-hand rule). Renders as an annular band with the basemap visible through the hole |
+
+Coordinates are emitted in `EPSG:4326` (lon/lat) using a local tangent-plane projection. Accurate up to ~100 km from the center; for very large radii or polar regions, geodesic-correct math is on the Phase 3 roadmap.
+
+### MIL-STD-2525 symbols
+
+`createMilSymbol` lazy-loads `milsymbol` on first use and returns a `Feature<Point>` with style metadata (`feature.style.icon`) so the vector layer renders it as an `ol/style/Icon`. The library is declared as an **optional peer dependency** — install it only if you use this helper:
+
+```bash
+npm install milsymbol
+```
+
+```ts
+const symbol = await ml.createMilSymbol({
+  sidc: 'SFGPUCI-----', // friendly infantry, ground unit
+  position: [-3.7, 40.42],
+  size: 36,
+  uniqueDesignation: 'A1',
+});
+```
+
+Three flavors:
+
+- **`createMilSymbol(config)`** — async; lazy-loads on first call.
+- **`createMilSymbolSync(config)`** — sync; throws if `milsymbol` is not loaded yet.
+- **`preloadMilsymbol()`** — fire-and-forget on app init to make the first symbol render synchronous.
+
+The service throws clearly on non-browser environments (`createMilSymbol` requires `window`).
+
 ## Architecture
 
 ### Data vs UI Separation
@@ -127,8 +294,8 @@ import {
   withInteractions,
 } from '@angular-helpers/openlayers/interactions';
 
-// Add military features (~10KB additional)
-import { OlEllipseFeatureComponent, withMilitary } from '@angular-helpers/openlayers/military';
+// Add military features — pure-math helpers + lazy-loaded milsymbol
+import { OlMilitaryService, withMilitary } from '@angular-helpers/openlayers/military';
 ```
 
 ## API Reference

package/fesm2022/angular-helpers-openlayers-core.mjs

@@ -155,6 +155,7 @@ class OlMapComponent {
     mapDblClick = output();
     mapContainerRef = viewChild.required('mapContainer');
     map;
+    resizeObserver;
     constructor() {
         afterNextRender(() => this.initMap());
         effect(() => {
@@ -186,6 +187,19 @@ class OlMapComponent {
             });
             this.map = new OLMap({ target: container, view, layers: [] });
             this.mapService.setMap(this.map);
+            // Add ResizeObserver to handle container size changes (e.g. sidebars, window resize)
+            if (typeof ResizeObserver !== 'undefined') {
+                this.resizeObserver = new ResizeObserver(() => {
+                    if (this.map) {
+                        // Using requestAnimationFrame prevents "ResizeObserver loop limit exceeded" errors
+                        requestAnimationFrame(() => {
+                            if (this.map)
+                                this.map.updateSize();
+                        });
+                    }
+                });
+                this.resizeObserver.observe(container);
+            }
             view.on('change:center', () => this.zoneHelper.runInsideAngular(() => this.emitViewChange()));
             view.on('change:resolution', () => this.zoneHelper.runInsideAngular(() => this.emitViewChange()));
             this.map.on('click', (e) => this.zoneHelper.runInsideAngular(() => this.mapClick.emit({
@@ -200,6 +214,10 @@ class OlMapComponent {
         this.emitViewChange();
     }
     destroyMap() {
+        if (this.resizeObserver) {
+            this.resizeObserver.disconnect();
+            this.resizeObserver = undefined;
+        }
         if (this.map) {
             this.zoneHelper.runOutsideAngular(() => {
                 this.map.setTarget(undefined);

package/fesm2022/angular-helpers-openlayers-interactions.mjs

@@ -33,9 +33,20 @@ class InteractionStateService {
     modify$ = this.modifySubject.asObservable();
     /**
      * Adds a managed interaction to the state.
+     * If the interaction is marked as exclusive, it disables other exclusive interactions.
      * @param interaction - The interaction to add
      */
     addInteraction(interaction) {
+        if (interaction.config.exclusive !== false) {
+            // Disable other exclusive interactions to maintain mutual exclusivity
+            const currentInteractions = this.interactions();
+            for (const existing of currentInteractions) {
+                if (existing.id !== interaction.id && existing.config.exclusive !== false) {
+                    existing.cleanup();
+                    this.removeInteraction(existing.id);
+                }
+            }
+        }
         this.interactions.update((list) => [...list, interaction]);
     }
     /**
@@ -533,6 +544,7 @@ function withInteractions() {
     return {
         kind: 'interactions',
         providers: [
+            OlLayerService, // DX: interactions often need layers
             OlInteractionService,
             InteractionStateService,
             SelectInteractionService,

package/fesm2022/angular-helpers-openlayers-layers.mjs

@@ -4,18 +4,27 @@ import VectorLayer from 'ol/layer/Vector';
 import TileLayer from 'ol/layer/Tile';
 import ImageLayer from 'ol/layer/Image';
 import VectorSource from 'ol/source/Vector';
-import { Feature } from 'ol';
+import OLFeature from 'ol/Feature';
 import { Point, LineString, Polygon, Circle } from 'ol/geom';
 import { fromLonLat } from 'ol/proj';
-import { Style, Circle as Circle$1, Stroke, Fill } from 'ol/style';
+import { getCenter } from 'ol/extent';
+import { Style, Circle as Circle$1, Stroke, Fill, Icon } from 'ol/style';
+import Text from 'ol/style/Text';
+import ClusterSource from 'ol/source/Cluster';
 import OSM from 'ol/source/OSM';
 import XYZ from 'ol/source/XYZ';
 import TileWMS from 'ol/source/TileWMS';
 import ImageWMS from 'ol/source/ImageWMS';
-import { ImageStatic } from 'ol/source';
+import ImageStatic from 'ol/source/ImageStatic';
 import { OlMapService } from '@angular-helpers/openlayers/core';
 
 // OlLayerService
+/**
+ * Internal property key used to stash the abstract style metadata on the
+ * underlying `ol/Feature` so the layer style function can resolve a
+ * per-feature visual without colliding with user `properties`.
+ */
+const STYLE_PROP = '__angular_helpers_style__';
 class OlLayerService {
     mapService = inject(OlMapService);
     layerCache = new Map();
@@ -127,7 +136,15 @@ class OlLayerService {
         const layer = this.layerCache.get(id);
         if (!(layer instanceof VectorLayer))
             return;
-        layer.getSource()?.clear();
+        const source = layer.getSource();
+        if (!source)
+            return;
+        // Handle Cluster source: clear the underlying VectorSource
+        const clusterSource = source;
+        const vectorSource = clusterSource.getSource
+            ? clusterSource.getSource()
+            : source;
+        vectorSource?.clear();
     }
     /**
      * Updates the features of a vector layer.
@@ -142,8 +159,15 @@ class OlLayerService {
         const source = layer.getSource();
         if (!source)
             return;
+        // Handle Cluster source: get the underlying VectorSource
+        const clusterSource = source;
+        const vectorSource = clusterSource.getSource
+            ? clusterSource.getSource()
+            : source;
+        if (!(vectorSource instanceof VectorSource))
+            return;
         // Get existing feature IDs from source
-        const existingIds = new Set(source
+        const existingIds = new Set(vectorSource
             .getFeatures()
             .map((f) => f.getId())
             .filter((id) => id !== undefined));
@@ -178,14 +202,17 @@ class OlLayerService {
                     else {
                         geometry = new Point([0, 0]);
                     }
-                    const olFeature = new Feature({
+                    const olFeature = new OLFeature({
                         geometry,
                         ...feature.properties,
                     });
+                    if (feature.style) {
+                        olFeature.set(STYLE_PROP, feature.style);
+                    }
                     olFeature.setId(feature.id);
                     return olFeature;
                 });
-                source.addFeatures(olFeatures);
+                vectorSource.addFeatures(olFeatures);
             }
         }
     }
@@ -204,7 +231,7 @@ class OlLayerService {
         this.layerState.set(layers.sort((a, b) => a.zIndex - b.zIndex));
     }
     createVectorLayer(config, map) {
-        const source = new VectorSource();
+        const vectorSource = new VectorSource();
         // Add features if provided
         if (config.features && config.features.length > 0) {
             const olFeatures = config.features.map((feature) => {
@@ -234,15 +261,40 @@ class OlLayerService {
                 else {
                     geometry = new Point([0, 0]);
                 }
-                const olFeature = new Feature({
+                const olFeature = new OLFeature({
                     geometry,
                     ...feature.properties,
                 });
+                if (feature.style) {
+                    olFeature.set(STYLE_PROP, feature.style);
+                }
                 olFeature.setId(feature.id);
                 return olFeature;
             });
-            source.addFeatures(olFeatures);
+            vectorSource.addFeatures(olFeatures);
         }
+        // Wrap in cluster source if enabled
+        const clusterCfg = config.cluster;
+        const source = clusterCfg?.enabled
+            ? new ClusterSource({
+                source: vectorSource,
+                distance: clusterCfg.distance ?? 40,
+                minDistance: clusterCfg.minDistance ?? 20,
+                geometryFunction: (feature) => {
+                    const geometry = feature.getGeometry();
+                    if (!geometry)
+                        return null;
+                    // For Point geometries, use as-is
+                    if (geometry.getType() === 'Point') {
+                        return geometry;
+                    }
+                    // For other geometries (Polygon, Circle, etc.), use center point
+                    const extent = geometry.getExtent();
+                    const center = getCenter(extent);
+                    return new Point(center);
+                },
+            })
+            : vectorSource;
         // Default style for all geometry types (points, lines, polygons)
         const defaultStyle = new Style({
             fill: new Fill({ color: 'rgba(25, 118, 210, 0.3)' }),
@@ -253,12 +305,86 @@ class OlLayerService {
                 stroke: new Stroke({ color: '#d32f2f', width: 2 }),
             }),
         });
+        // Cluster style: shows count badge when features are clustered
+        const clusterStyleFn = (olFeature) => {
+            const features = olFeature.get('features');
+            const size = features?.length ?? 1;
+            if (size > 1) {
+                const showCount = clusterCfg?.showCount ?? true;
+                return new Style({
+                    image: new Circle$1({
+                        radius: 15 + Math.min(size * 2, 15),
+                        fill: new Fill({ color: 'rgba(255, 100, 100, 0.8)' }),
+                        stroke: new Stroke({ color: '#fff', width: 2 }),
+                    }),
+                    text: showCount
+                        ? new Text({
+                            text: String(size),
+                            fill: new Fill({ color: '#fff' }),
+                        })
+                        : undefined,
+                });
+            }
+            // Single feature: get the original feature from the cluster and use its style
+            const originalFeatures = olFeature.get('features');
+            const originalFeature = originalFeatures?.[0];
+            if (originalFeature) {
+                const abstractStyle = originalFeature.get(STYLE_PROP);
+                if (abstractStyle) {
+                    const style = new Style();
+                    const { icon, fill, stroke } = abstractStyle;
+                    if (icon?.src) {
+                        style.setImage(new Icon({
+                            src: icon.src,
+                            ...(icon.size ? { size: icon.size } : {}),
+                            ...(icon.anchor ? { anchor: icon.anchor } : {}),
+                        }));
+                    }
+                    if (fill) {
+                        style.setFill(new Fill({ color: fill.color }));
+                    }
+                    if (stroke) {
+                        style.setStroke(new Stroke({ color: stroke.color, width: stroke.width }));
+                    }
+                    // If we mapped at least one property, return it, otherwise fallback
+                    if (icon?.src || fill || stroke)
+                        return style;
+                }
+            }
+            return defaultStyle;
+        };
+        // Per-feature style resolver: features carrying `style` render it.
+        // Structural type avoids importing `FeatureLike` from `ol/Feature`;
+        // tooling has been observed to auto-remove the unused-looking import.
+        const styleFn = (olFeature) => {
+            const abstractStyle = olFeature.get(STYLE_PROP);
+            if (abstractStyle) {
+                const style = new Style();
+                const { icon, fill, stroke } = abstractStyle;
+                if (icon?.src) {
+                    style.setImage(new Icon({
+                        src: icon.src,
+                        ...(icon.size ? { size: icon.size } : {}),
+                        ...(icon.anchor ? { anchor: icon.anchor } : {}),
+                    }));
+                }
+                if (fill) {
+                    style.setFill(new Fill({ color: fill.color }));
+                }
+                if (stroke) {
+                    style.setStroke(new Stroke({ color: stroke.color, width: stroke.width }));
+                }
+                if (icon?.src || fill || stroke)
+                    return style;
+            }
+            return defaultStyle;
+        };
         const layer = new VectorLayer({
             source,
             visible: config.visible ?? true,
             opacity: config.opacity ?? 1,
             zIndex: config.zIndex,
-            style: defaultStyle,
+            style: clusterCfg?.enabled ? clusterStyleFn : styleFn,
         });
         layer.set('id', config.id);
         map.addLayer(layer);
@@ -337,6 +463,7 @@ class OlVectorLayerComponent {
     opacity = input(1, ...(ngDevMode ? [{ debugName: "opacity" }] : /* istanbul ignore next */ []));
     visible = input(true, ...(ngDevMode ? [{ debugName: "visible" }] : /* istanbul ignore next */ []));
     style = input(...(ngDevMode ? [undefined, { debugName: "style" }] : /* istanbul ignore next */ []));
+    cluster = input(...(ngDevMode ? [undefined, { debugName: "cluster" }] : /* istanbul ignore next */ []));
     constructor() {
         // Initialize layer after DOM is ready
         afterNextRender(() => {
@@ -348,6 +475,7 @@ class OlVectorLayerComponent {
                 opacity: this.opacity(),
                 visible: this.visible(),
                 style: this.style(),
+                cluster: this.cluster(),
             });
         });
         // Effect to sync features when input changes
@@ -364,7 +492,7 @@ class OlVectorLayerComponent {
         });
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlVectorLayerComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "21.2.4", type: OlVectorLayerComponent, isStandalone: true, selector: "ol-vector-layer", inputs: { id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: true, transformFunction: null }, features: { classPropertyName: "features", publicName: "features", isSignal: true, isRequired: false, transformFunction: null }, zIndex: { classPropertyName: "zIndex", publicName: "zIndex", isSignal: true, isRequired: false, transformFunction: null }, opacity: { classPropertyName: "opacity", publicName: "opacity", isSignal: true, isRequired: false, transformFunction: null }, visible: { classPropertyName: "visible", publicName: "visible", isSignal: true, isRequired: false, transformFunction: null }, style: { classPropertyName: "style", publicName: "style", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: '', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "21.2.4", type: OlVectorLayerComponent, isStandalone: true, selector: "ol-vector-layer", inputs: { id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: true, transformFunction: null }, features: { classPropertyName: "features", publicName: "features", isSignal: true, isRequired: false, transformFunction: null }, zIndex: { classPropertyName: "zIndex", publicName: "zIndex", isSignal: true, isRequired: false, transformFunction: null }, opacity: { classPropertyName: "opacity", publicName: "opacity", isSignal: true, isRequired: false, transformFunction: null }, visible: { classPropertyName: "visible", publicName: "visible", isSignal: true, isRequired: false, transformFunction: null }, style: { classPropertyName: "style", publicName: "style", isSignal: true, isRequired: false, transformFunction: null }, cluster: { classPropertyName: "cluster", publicName: "cluster", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: '', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlVectorLayerComponent, decorators: [{
             type: Component,
@@ -373,7 +501,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
                     template: '',
                     changeDetection: ChangeDetectionStrategy.OnPush,
                 }]
-        }], ctorParameters: () => [], propDecorators: { id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: true }] }], features: [{ type: i0.Input, args: [{ isSignal: true, alias: "features", required: false }] }], zIndex: [{ type: i0.Input, args: [{ isSignal: true, alias: "zIndex", required: false }] }], opacity: [{ type: i0.Input, args: [{ isSignal: true, alias: "opacity", required: false }] }], visible: [{ type: i0.Input, args: [{ isSignal: true, alias: "visible", required: false }] }], style: [{ type: i0.Input, args: [{ isSignal: true, alias: "style", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: true }] }], features: [{ type: i0.Input, args: [{ isSignal: true, alias: "features", required: false }] }], zIndex: [{ type: i0.Input, args: [{ isSignal: true, alias: "zIndex", required: false }] }], opacity: [{ type: i0.Input, args: [{ isSignal: true, alias: "opacity", required: false }] }], visible: [{ type: i0.Input, args: [{ isSignal: true, alias: "visible", required: false }] }], style: [{ type: i0.Input, args: [{ isSignal: true, alias: "style", required: false }] }], cluster: [{ type: i0.Input, args: [{ isSignal: true, alias: "cluster", required: false }] }] } });
 
 // OlTileLayerComponent
 class OlTileLayerComponent {