@angular-helpers/openlayers 0.3.0 → 0.4.0

package/README.md

@@ -176,6 +176,94 @@ const handle = popups.openComponent({
 
 `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
@@ -206,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,10 +4,13 @@ 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';
@@ -16,6 +19,12 @@ 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 {

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

@@ -1,20 +1,237 @@
 import * as i0 from '@angular/core';
 import { Injectable } from '@angular/core';
 
-// OlMilitaryService
+// @angular-helpers/openlayers/military — service implementation
+/**
+ * Meters per degree of latitude on a spherical Earth approximation.
+ * Used by the local tangent-plane projection in the geometry helpers.
+ */
+const METERS_PER_DEGREE_LAT = 111_320;
+/**
+ * Service exposing geometry helpers and MIL-STD-2525 symbology rendering.
+ *
+ * - `createEllipse`, `createSector`, `createDonut` are **pure math** and
+ *   have no runtime dependencies beyond the bundled types.
+ * - `createMilSymbol` uses the milsymbol library via dynamic ESM import.
+ */
 class OlMilitaryService {
+    idCounter = 0;
+    mlLoader = null;
+    msModule = null;
+    // ---------------------------------------------------------------------------
+    // Geometry helpers (pure math, no deps)
+    // ---------------------------------------------------------------------------
+    /**
+     * Build a `Feature<Polygon>` approximating an ellipse centered at
+     * `config.center`. See {@link EllipseConfig} for parameter semantics.
+     */
     createEllipse(config) {
-        return { id: 'ellipse-1', geometry: { type: 'Polygon', coordinates: [] } };
+        const { center, semiMajor, semiMinor, rotation = 0, segments = 64, properties } = config;
+        if (semiMajor <= 0 || semiMinor <= 0) {
+            throw new RangeError('semiMajor and semiMinor must be positive');
+        }
+        if (segments < 8) {
+            throw new RangeError('segments must be >= 8');
+        }
+        const cosR = Math.cos(rotation);
+        const sinR = Math.sin(rotation);
+        const ring = [];
+        for (let i = 0; i < segments; i++) {
+            const theta = (i / segments) * Math.PI * 2;
+            // Ellipse in local axis-aligned frame, then rotated by `rotation`.
+            const ax = Math.cos(theta) * semiMajor;
+            const ay = Math.sin(theta) * semiMinor;
+            const dx = ax * cosR - ay * sinR;
+            const dy = ax * sinR + ay * cosR;
+            ring.push(this.offsetMetersToLonLat(center, dx, dy));
+        }
+        ring.push(ring[0]); // close the ring
+        return {
+            id: this.nextId('ellipse'),
+            geometry: { type: 'Polygon', coordinates: [ring] },
+            properties,
+        };
     }
+    /**
+     * Build a `Feature<Polygon>` for a circular sector (pie slice).
+     * See {@link SectorConfig} for parameter semantics.
+     */
     createSector(config) {
-        return { id: 'sector-1', geometry: { type: 'Polygon', coordinates: [] } };
+        const { center, radius, startAngle, endAngle, segments = 32, properties } = config;
+        if (radius <= 0) {
+            throw new RangeError('radius must be positive');
+        }
+        if (endAngle <= startAngle) {
+            throw new RangeError('endAngle must be greater than startAngle');
+        }
+        if (endAngle - startAngle > Math.PI * 2) {
+            throw new RangeError('sector cannot exceed full circle');
+        }
+        if (segments < 4) {
+            throw new RangeError('segments must be >= 4');
+        }
+        const ring = [center];
+        const span = endAngle - startAngle;
+        for (let i = 0; i <= segments; i++) {
+            const theta = startAngle + (i / segments) * span;
+            const dx = Math.cos(theta) * radius;
+            const dy = Math.sin(theta) * radius;
+            ring.push(this.offsetMetersToLonLat(center, dx, dy));
+        }
+        ring.push(center); // close back to apex
+        return {
+            id: this.nextId('sector'),
+            geometry: { type: 'Polygon', coordinates: [ring] },
+            properties,
+        };
     }
-    addMilSymbol(config) {
+    /**
+     * Build a `Feature<Polygon>` for a donut (annular ring). The output has
+     * two rings: an outer ring wound counter-clockwise and an inner ring
+     * wound clockwise so the GeoJSON right-hand rule renders the hole.
+     */
+    createDonut(config) {
+        const { center, outerRadius, innerRadius, segments = 64, properties } = config;
+        if (outerRadius <= 0 || innerRadius <= 0) {
+            throw new RangeError('radii must be positive');
+        }
+        if (outerRadius <= innerRadius) {
+            throw new RangeError('outerRadius must be greater than innerRadius');
+        }
+        if (segments < 8) {
+            throw new RangeError('segments must be >= 8');
+        }
+        const outer = [];
+        const inner = [];
+        for (let i = 0; i < segments; i++) {
+            const theta = (i / segments) * Math.PI * 2;
+            const cosT = Math.cos(theta);
+            const sinT = Math.sin(theta);
+            // Outer ring: CCW (theta increasing)
+            outer.push(this.offsetMetersToLonLat(center, cosT * outerRadius, sinT * outerRadius));
+            // Inner ring: CW — sample the SAME thetas but we'll reverse the
+            // accumulator below so the ring is traversed in the opposite sense.
+            inner.push(this.offsetMetersToLonLat(center, cosT * innerRadius, sinT * innerRadius));
+        }
+        inner.reverse();
+        outer.push(outer[0]);
+        inner.push(inner[0]);
         return {
-            id: `symbol-${config.sidc}`,
-            geometry: { type: 'Point', coordinates: config.position },
+            id: this.nextId('donut'),
+            geometry: { type: 'Polygon', coordinates: [outer, inner] },
+            properties,
         };
     }
+    // ---------------------------------------------------------------------------
+    // MIL-STD-2525 symbology (lazy `milsymbol` load)
+    // ---------------------------------------------------------------------------
+    /**
+     * Pre-load the optional `milsymbol` peer dependency so subsequent calls
+     * to `createMilSymbol` / `createMilSymbolSync` resolve immediately.
+     * Idempotent — multiple calls share the same promise.
+     */
+    preloadMilsymbol() {
+        this.assertBrowser();
+        if (!this.mlLoader) {
+            this.mlLoader = import('milsymbol').then((m) => {
+                this.msModule = m;
+                return m;
+            });
+        }
+        return this.mlLoader.then(() => {
+            // Void return for the public API
+        });
+    }
+    /**
+     * Build a MIL-STD-2525 symbol feature asynchronously.
+     * Lazy-loads `milsymbol` on the first call.
+     */
+    async createMilSymbol(config) {
+        this.assertBrowser();
+        this.assertSidc(config.sidc);
+        if (!this.msModule) {
+            await this.preloadMilsymbol();
+        }
+        return this.buildSymbolFeature(config);
+    }
+    /**
+     * Build a MIL-STD-2525 symbol feature synchronously.
+     * Throws if `milsymbol` has not been preloaded via `preloadMilsymbol()`
+     * or a previous `createMilSymbol()` call.
+     */
+    createMilSymbolSync(config) {
+        this.assertBrowser();
+        this.assertSidc(config.sidc);
+        if (!this.msModule) {
+            throw new Error('milsymbol is not loaded yet. Call preloadMilsymbol() or use the async createMilSymbol().');
+        }
+        return this.buildSymbolFeature(config);
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    /**
+     * Project an `(dx, dy)` meter offset from `center` to lon/lat using a
+     * local tangent-plane (equirectangular) approximation. Acceptable for
+     * the radii typical in military symbology (<100 km from center).
+     */
+    offsetMetersToLonLat(center, dx, dy) {
+        const [lon, lat] = center;
+        const latRad = (lat * Math.PI) / 180;
+        const dLat = dy / METERS_PER_DEGREE_LAT;
+        const dLon = dx / (METERS_PER_DEGREE_LAT * Math.cos(latRad));
+        return [lon + dLon, lat + dLat];
+    }
+    nextId(kind) {
+        return `${kind}-${++this.idCounter}`;
+    }
+    buildSymbolFeature(config) {
+        const { sidc, position, properties, quantity, ...rest } = config;
+        // `milsymbol` types `quantity` as a string, but a number is the
+        // ergonomic shape; coerce here.
+        const milOptions = {
+            ...rest,
+            ...(quantity !== undefined ? { quantity: String(quantity) } : {}),
+        };
+        // We asserted this.msModule exists before calling this
+        const ms = this.msModule;
+        // default import might be wrapped depending on bundler
+        const SymbolClass = ms.default?.Symbol || ms.Symbol;
+        const symbol = new SymbolClass(sidc, milOptions);
+        const style = this.symbolToStyleResult(symbol);
+        const mergedProperties = { sidc, ...milOptions, ...properties };
+        return {
+            id: this.nextId('symbol'),
+            geometry: { type: 'Point', coordinates: position },
+            properties: mergedProperties,
+            style: { icon: { src: style.src, size: style.size, anchor: style.anchor } },
+        };
+    }
+    symbolToStyleResult(symbol) {
+        const svg = symbol.asSVG();
+        const { width, height } = symbol.getSize();
+        const { x: ax, y: ay } = symbol.getAnchor();
+        return {
+            src: `data:image/svg+xml;base64,${this.encodeBase64Utf8(svg)}`,
+            size: [width, height],
+            anchor: [ax / width, ay / height],
+        };
+    }
+    encodeBase64Utf8(input) {
+        // `btoa` only handles Latin-1; this round-trip preserves non-ASCII
+        // characters (e.g. unit designators with accents).
+        return btoa(unescape(encodeURIComponent(input)));
+    }
+    assertSidc(sidc) {
+        if (typeof sidc !== 'string' || sidc.length < 10) {
+            throw new TypeError('sidc must be a non-empty MIL-STD-2525 SIDC string');
+        }
+    }
+    assertBrowser() {
+        if (typeof window === 'undefined') {
+            throw new Error('createMilSymbol requires a browser environment');
+        }
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlMilitaryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlMilitaryService });
 }

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

@@ -2,6 +2,7 @@ import * as i0 from '@angular/core';
 import { inject, ElementRef, input, output, DestroyRef, effect, ChangeDetectionStrategy, Component, Directive, EnvironmentInjector, ApplicationRef, createComponent, Injectable } from '@angular/core';
 import Overlay from 'ol/Overlay';
 import { OlMapService, OlZoneHelper } from '@angular-helpers/openlayers/core';
+import { OlLayerService } from '@angular-helpers/openlayers/layers';
 
 // OlPopupComponent — declarative popup with content projection.
 /**
@@ -446,7 +447,7 @@ function applyOverlayConfig(overlay, config) {
 }
 
 function withOverlays() {
-    return { kind: 'overlays', providers: [OlPopupService] };
+    return { kind: 'overlays', providers: [OlLayerService, OlPopupService] };
 }
 function provideOverlays() {
     return withOverlays();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/openlayers",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Modern Angular wrapper for OpenLayers with modular architecture, standalone components, and hybrid template/programmatic API",
   "homepage": "https://gaspar1992.github.io/angular-helpers/docs/openlayers",
   "repository": {
@@ -32,9 +32,13 @@
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
+    "milsymbol": "^3.0.0",
     "ol": "^10.0.0"
   },
   "peerDependenciesMeta": {
+    "milsymbol": {
+      "optional": true
+    },
     "ol": {
       "optional": false
     }

package/types/angular-helpers-openlayers-core.d.ts

@@ -36,6 +36,22 @@ interface Style {
             width?: number;
         };
     };
+    /**
+     * Icon style for Point features. When set, renderers should produce an
+     * `ol/style/Icon` with the given source. Used by the military symbology
+     * helpers to embed `milsymbol`-generated SVGs as data URLs.
+     */
+    icon?: {
+        /** Image source — typically a `data:image/svg+xml;base64,...` URL */
+        src: string;
+        /** Pixel size `[width, height]` */
+        size?: [number, number];
+        /**
+         * Anchor in fractional coordinates `[x, y]` where `0..1` is the icon
+         * extent. `[0.5, 0.5]` centers the icon on the feature.
+         */
+        anchor?: [number, number];
+    };
     text?: {
         text?: string;
         font?: string;
@@ -83,6 +99,7 @@ declare class OlMapComponent {
     mapDblClick: _angular_core.OutputEmitterRef<MapClickEvent>;
     mapContainerRef: _angular_core.Signal<ElementRef<HTMLDivElement>>;
     private map?;
+    private resizeObserver?;
     constructor();
     private initMap;
     private destroyMap;

package/types/angular-helpers-openlayers-interactions.d.ts

@@ -11,6 +11,12 @@ import { Feature as Feature$1 } from 'ol';
 type InteractionType = 'select' | 'draw' | 'modify' | 'dragAndDrop';
 interface InteractionConfig {
     active?: boolean;
+    /**
+     * If true, enabling this interaction will automatically disable other active exclusive interactions.
+     * Useful for mutually exclusive tools like Draw and Modify.
+     * @default true
+     */
+    exclusive?: boolean;
 }
 interface SelectConfig extends InteractionConfig {
     layers?: string[];
@@ -178,6 +184,7 @@ declare class InteractionStateService {
     readonly modify$: rxjs.Observable<ModifyEvent>;
     /**
      * 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: ManagedInteraction): void;

package/types/angular-helpers-openlayers-layers.d.ts

@@ -1,7 +1,52 @@
 import * as _angular_core from '@angular/core';
-import { Feature, Style, Layer, Extent, OlFeature } from '@angular-helpers/openlayers/core';
+import { Layer, Extent, Feature, Style, OlFeature } from '@angular-helpers/openlayers/core';
 import BaseLayer from 'ol/layer/Base';
 
+interface LayerConfig extends Layer {
+    type: 'vector' | 'tile' | 'image';
+    extent?: Extent;
+    minResolution?: number;
+    maxResolution?: number;
+}
+interface ClusterConfig {
+    /** Enable clustering (default: false) */
+    enabled: boolean;
+    /** Distance in pixels within which features will be clustered (default: 40) */
+    distance?: number;
+    /** Minimum distance between clusters (default: 20) */
+    minDistance?: number;
+    /** Show count badge on cluster (default: true) */
+    showCount?: boolean;
+    /** Style for individual features when clustering */
+    featureStyle?: Style;
+}
+interface VectorLayerConfig extends LayerConfig {
+    type: 'vector';
+    features?: Feature[];
+    style?: Style | ((feature: Feature) => Style);
+    cluster?: ClusterConfig;
+}
+interface TileLayerConfig extends LayerConfig {
+    type: 'tile';
+    source: SourceConfig;
+}
+interface ImageLayerConfig extends LayerConfig {
+    type: 'image';
+    source: ImageSourceConfig;
+}
+interface SourceConfig {
+    type: 'osm' | 'xyz' | 'wms' | 'wmts';
+    url?: string;
+    attributions?: string | string[];
+    params?: Record<string, unknown>;
+}
+interface ImageSourceConfig {
+    type: 'wms' | 'static';
+    url: string;
+    params?: Record<string, unknown>;
+    imageExtent?: Extent;
+}
+
 declare class OlVectorLayerComponent {
     private layerService;
     private destroyRef;
@@ -11,9 +56,10 @@ declare class OlVectorLayerComponent {
     opacity: _angular_core.InputSignal<number>;
     visible: _angular_core.InputSignal<boolean>;
     style: _angular_core.InputSignal<Style | ((feature: Feature) => Style)>;
+    cluster: _angular_core.InputSignal<ClusterConfig>;
     constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlVectorLayerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlVectorLayerComponent, "ol-vector-layer", never, { "id": { "alias": "id"; "required": true; "isSignal": true; }; "features": { "alias": "features"; "required": false; "isSignal": true; }; "zIndex": { "alias": "zIndex"; "required": false; "isSignal": true; }; "opacity": { "alias": "opacity"; "required": false; "isSignal": true; }; "visible": { "alias": "visible"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlVectorLayerComponent, "ol-vector-layer", never, { "id": { "alias": "id"; "required": true; "isSignal": true; }; "features": { "alias": "features"; "required": false; "isSignal": true; }; "zIndex": { "alias": "zIndex"; "required": false; "isSignal": true; }; "opacity": { "alias": "opacity"; "required": false; "isSignal": true; }; "visible": { "alias": "visible"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; "cluster": { "alias": "cluster"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class OlTileLayerComponent {
@@ -48,38 +94,6 @@ declare class OlImageLayerComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlImageLayerComponent, "ol-image-layer", never, { "id": { "alias": "id"; "required": true; "isSignal": true; }; "sourceType": { "alias": "sourceType"; "required": true; "isSignal": true; }; "url": { "alias": "url"; "required": true; "isSignal": true; }; "params": { "alias": "params"; "required": false; "isSignal": true; }; "imageExtent": { "alias": "imageExtent"; "required": false; "isSignal": true; }; "zIndex": { "alias": "zIndex"; "required": false; "isSignal": true; }; "opacity": { "alias": "opacity"; "required": false; "isSignal": true; }; "visible": { "alias": "visible"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-interface LayerConfig extends Layer {
-    type: 'vector' | 'tile' | 'image';
-    extent?: Extent;
-    minResolution?: number;
-    maxResolution?: number;
-}
-interface VectorLayerConfig extends LayerConfig {
-    type: 'vector';
-    features?: Feature[];
-    style?: Style | ((feature: Feature) => Style);
-}
-interface TileLayerConfig extends LayerConfig {
-    type: 'tile';
-    source: SourceConfig;
-}
-interface ImageLayerConfig extends LayerConfig {
-    type: 'image';
-    source: ImageSourceConfig;
-}
-interface SourceConfig {
-    type: 'osm' | 'xyz' | 'wms' | 'wmts';
-    url?: string;
-    attributions?: string | string[];
-    params?: Record<string, unknown>;
-}
-interface ImageSourceConfig {
-    type: 'wms' | 'static';
-    url: string;
-    params?: Record<string, unknown>;
-    imageExtent?: Extent;
-}
-
 interface LayerInfo {
     id: string;
     type: 'vector' | 'tile' | 'image';

package/types/angular-helpers-openlayers-military.d.ts

@@ -1,27 +1,181 @@
 import { Coordinate, Feature, OlFeature } from '@angular-helpers/openlayers/core';
 import * as i0 from '@angular/core';
 
+/**
+ * Configuration for an ellipse polygon centered at `center`.
+ * Coordinates are emitted in EPSG:4326 (lon/lat) using a local tangent-plane
+ * approximation; accuracy degrades for radii > ~100 km or near the poles.
+ */
 interface EllipseConfig {
+    /** Ellipse center as `[lon, lat]` in EPSG:4326. */
     center: Coordinate;
+    /** Semi-major axis in meters. Must be > 0. */
     semiMajor: number;
+    /** Semi-minor axis in meters. Must be > 0. */
     semiMinor: number;
+    /**
+     * Rotation in radians, counter-clockwise from East. Default: 0
+     * (semi-major axis points East).
+     */
     rotation?: number;
+    /**
+     * Number of vertices used to approximate the ellipse. Default: 64.
+     * Minimum: 8.
+     */
+    segments?: number;
+    /** Custom feature properties to attach to the output feature. */
+    properties?: Record<string, unknown>;
 }
+/**
+ * Configuration for a circular sector (pie-slice) polygon.
+ * Same projection caveats as `EllipseConfig`.
+ */
 interface SectorConfig {
+    /** Sector apex / center as `[lon, lat]` in EPSG:4326. */
     center: Coordinate;
+    /** Sector radius in meters. Must be > 0. */
     radius: number;
+    /** Start angle in radians (0 = East, CCW positive). */
     startAngle: number;
+    /**
+     * End angle in radians. Must satisfy `startAngle < endAngle <= startAngle + 2π`.
+     */
     endAngle: number;
+    /**
+     * Number of vertices along the arc. Default: 32. Minimum: 4. The output
+     * polygon has `segments + 3` vertices (apex + arc + apex closer).
+     */
+    segments?: number;
+    /** Custom feature properties to attach to the output feature. */
+    properties?: Record<string, unknown>;
 }
+/**
+ * Configuration for a donut (annular ring) polygon — a disk with a
+ * concentric circular hole. Useful for range rings, exclusion zones,
+ * and similar GIS military primitives.
+ *
+ * The output `Feature<Polygon>` has TWO rings: an outer ring (CCW) and
+ * an inner ring (CW per the GeoJSON right-hand rule), so renderers that
+ * follow the spec fill only the band between the radii.
+ */
+interface DonutConfig {
+    /** Donut center as `[lon, lat]` in EPSG:4326. */
+    center: Coordinate;
+    /** Outer radius in meters. Must be > `innerRadius`. */
+    outerRadius: number;
+    /** Inner radius in meters. Must be > 0 and < `outerRadius`. */
+    innerRadius: number;
+    /**
+     * Number of vertices per ring. Default: 64. Minimum: 8. Both rings use
+     * the same segment count.
+     */
+    segments?: number;
+    /** Custom feature properties to attach to the output feature. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Subset of `milsymbol`'s `SymbolOptions` exposed by this package.
+ * `sidc` is the only required field; everything else is optional and
+ * forwarded verbatim to `new Symbol(sidc, options)`.
+ */
 interface MilSymbolConfig {
+    /** MIL-STD-2525 SIDC code. Required. */
     sidc: string;
+    /** Symbol position as `[lon, lat]` in EPSG:4326. Required. */
     position: Coordinate;
+    /** Symbol size in pixels. Default (set by `milsymbol`): 30. */
+    size?: number;
+    /** Mono-color override (e.g. `'#000'`). */
+    monoColor?: string;
+    /** Outline color. */
+    outlineColor?: string;
+    /** Icon (interior glyph) color. */
+    iconColor?: string;
+    /** Additional information field (top of the symbol). */
+    additionalInformation?: string;
+    /** Staff comments field. */
+    staffComments?: string;
+    /** Quantity field. */
+    quantity?: number;
+    /** Unique designation field (unit identifier). */
+    uniqueDesignation?: string;
+    /** Custom feature properties merged into the output feature's `properties`. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Result of resolving a `MilSymbolConfig` against `milsymbol`. Embedded
+ * into the output feature's `style.icon` so that `<ol-vector-layer>` can
+ * render it as an `ol/style/Icon`.
+ */
+interface MilSymbolStyleResult {
+    /** `data:image/svg+xml;base64,...` URL produced from `Symbol.asSVG()`. */
+    src: string;
+    /** Pixel `[width, height]` from `Symbol.getSize()`. */
+    size: [number, number];
+    /**
+     * Anchor in fractional coordinates `[x, y]` (0..1), computed from
+     * `Symbol.getAnchor()` divided by the size. `[0.5, 0.5]` centers the
+     * icon on the feature.
+     */
+    anchor: [number, number];
 }
 
+/**
+ * Service exposing geometry helpers and MIL-STD-2525 symbology rendering.
+ *
+ * - `createEllipse`, `createSector`, `createDonut` are **pure math** and
+ *   have no runtime dependencies beyond the bundled types.
+ * - `createMilSymbol` uses the milsymbol library via dynamic ESM import.
+ */
 declare class OlMilitaryService {
+    private idCounter;
+    private mlLoader;
+    private msModule;
+    /**
+     * Build a `Feature<Polygon>` approximating an ellipse centered at
+     * `config.center`. See {@link EllipseConfig} for parameter semantics.
+     */
     createEllipse(config: EllipseConfig): Feature;
+    /**
+     * Build a `Feature<Polygon>` for a circular sector (pie slice).
+     * See {@link SectorConfig} for parameter semantics.
+     */
     createSector(config: SectorConfig): Feature;
-    addMilSymbol(config: MilSymbolConfig): Feature;
+    /**
+     * Build a `Feature<Polygon>` for a donut (annular ring). The output has
+     * two rings: an outer ring wound counter-clockwise and an inner ring
+     * wound clockwise so the GeoJSON right-hand rule renders the hole.
+     */
+    createDonut(config: DonutConfig): Feature;
+    /**
+     * Pre-load the optional `milsymbol` peer dependency so subsequent calls
+     * to `createMilSymbol` / `createMilSymbolSync` resolve immediately.
+     * Idempotent — multiple calls share the same promise.
+     */
+    preloadMilsymbol(): Promise<void>;
+    /**
+     * Build a MIL-STD-2525 symbol feature asynchronously.
+     * Lazy-loads `milsymbol` on the first call.
+     */
+    createMilSymbol(config: MilSymbolConfig): Promise<Feature>;
+    /**
+     * Build a MIL-STD-2525 symbol feature synchronously.
+     * Throws if `milsymbol` has not been preloaded via `preloadMilsymbol()`
+     * or a previous `createMilSymbol()` call.
+     */
+    createMilSymbolSync(config: MilSymbolConfig): Feature;
+    /**
+     * Project an `(dx, dy)` meter offset from `center` to lon/lat using a
+     * local tangent-plane (equirectangular) approximation. Acceptable for
+     * the radii typical in military symbology (<100 km from center).
+     */
+    private offsetMetersToLonLat;
+    private nextId;
+    private buildSymbolFeature;
+    private symbolToStyleResult;
+    private encodeBase64Utf8;
+    private assertSidc;
+    private assertBrowser;
     static ɵfac: i0.ɵɵFactoryDeclaration<OlMilitaryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<OlMilitaryService>;
 }
@@ -30,4 +184,4 @@ declare function withMilitary(): OlFeature<'military'>;
 declare function provideMilitary(): OlFeature<'military'>;
 
 export { OlMilitaryService, provideMilitary, withMilitary };
-export type { EllipseConfig, MilSymbolConfig, SectorConfig };
+export type { DonutConfig, EllipseConfig, MilSymbolConfig, MilSymbolStyleResult, SectorConfig };