@angular-helpers/openlayers 0.2.0 → 0.3.0

package/README.md

@@ -97,6 +97,85 @@ 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`.
+
 ## Architecture
 
 ### Data vs UI Separation

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

@@ -12,7 +12,7 @@ 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

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

@@ -1,19 +1,449 @@
 import * as i0 from '@angular/core';
-import { Injectable } 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';
+
+// OlPopupComponent — declarative popup with content projection.
+/**
+ * Declarative map popup that projects arbitrary Angular content via `<ng-content>`.
+ *
+ * The component's host element is used directly as the `ol/Overlay`'s element, so
+ * projected children stay inside Angular's component tree and benefit from change
+ * detection without any extra plumbing.
+ *
+ * @example
+ * ```html
+ * <ol-popup
+ *   [position]="selectedCoord()"
+ *   [closeButton]="true"
+ *   [autoPan]="true"
+ *   (closed)="clearSelection()"
+ * >
+ *   <h3>{{ selected()?.name }}</h3>
+ *   <p>{{ selected()?.description }}</p>
+ * </ol-popup>
+ * ```
+ */
+class OlPopupComponent {
+    elementRef = inject(ElementRef);
+    mapService = inject(OlMapService);
+    zoneHelper = inject(OlZoneHelper);
+    /** Map coordinate where the popup is anchored. `null` hides the popup. */
+    position = input(null, ...(ngDevMode ? [{ debugName: "position" }] : /* istanbul ignore next */ []));
+    /** Pixel offset relative to `position`. */
+    offset = input([0, 0], ...(ngDevMode ? [{ debugName: "offset" }] : /* istanbul ignore next */ []));
+    /** Anchor of the popup element relative to `position`. */
+    positioning = input('bottom-center', ...(ngDevMode ? [{ debugName: "positioning" }] : /* istanbul ignore next */ []));
+    /** Whether the map auto-pans to keep the popup in view. */
+    autoPan = input(false, ...(ngDevMode ? [{ debugName: "autoPan" }] : /* istanbul ignore next */ []));
+    /** Whether to render the default close button. */
+    closeButton = input(false, ...(ngDevMode ? [{ debugName: "closeButton" }] : /* istanbul ignore next */ []));
+    /** Emitted when the popup transitions from visible to hidden (close button or `position` set to null). */
+    closed = output();
+    overlay = null;
+    currentMap = null;
+    wasVisible = false;
+    constructor() {
+        inject(DestroyRef).onDestroy(() => this.dispose());
+        // Create the overlay lazily when the map becomes ready, then keep it in sync
+        // with the inputs. The overlay's element is THIS component's host element so
+        // projected content lives inside Angular's view tree.
+        this.mapService.onReady((map) => {
+            this.currentMap = map;
+            this.zoneHelper.runOutsideAngular(() => {
+                this.overlay = new Overlay({
+                    element: this.elementRef.nativeElement,
+                    stopEvent: true,
+                });
+            });
+            this.applyState();
+        });
+        effect(() => {
+            // Read every signal so the effect re-runs on any change.
+            this.position();
+            this.offset();
+            this.positioning();
+            this.autoPan();
+            this.applyState();
+        });
+    }
+    /** @internal */
+    onCloseClick() {
+        this.zoneHelper.runInsideAngular(() => this.closed.emit());
+    }
+    applyState() {
+        const overlay = this.overlay;
+        const map = this.currentMap;
+        if (!overlay || !map)
+            return;
+        const position = this.position();
+        this.zoneHelper.runOutsideAngular(() => {
+            overlay.setOffset(this.offset());
+            overlay.setPositioning(this.positioning());
+            const wantsAutoPan = this.autoPan();
+            overlay.set('autoPan', wantsAutoPan);
+            const visible = position !== null;
+            if (visible && !this.wasVisible) {
+                map.addOverlay(overlay);
+            }
+            overlay.setPosition(visible ? position : undefined);
+            if (!visible && this.wasVisible) {
+                map.removeOverlay(overlay);
+                this.zoneHelper.runInsideAngular(() => this.closed.emit());
+            }
+            this.wasVisible = visible;
+        });
+    }
+    dispose() {
+        if (!this.overlay || !this.currentMap)
+            return;
+        const overlay = this.overlay;
+        const map = this.currentMap;
+        this.zoneHelper.runOutsideAngular(() => {
+            if (this.wasVisible)
+                map.removeOverlay(overlay);
+        });
+        this.overlay = null;
+        this.currentMap = null;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlPopupComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.4", type: OlPopupComponent, isStandalone: true, selector: "ol-popup", inputs: { position: { classPropertyName: "position", publicName: "position", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "offset", isSignal: true, isRequired: false, transformFunction: null }, positioning: { classPropertyName: "positioning", publicName: "positioning", isSignal: true, isRequired: false, transformFunction: null }, autoPan: { classPropertyName: "autoPan", publicName: "autoPan", isSignal: true, isRequired: false, transformFunction: null }, closeButton: { classPropertyName: "closeButton", publicName: "closeButton", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { closed: "closed" }, host: { attributes: { "role": "dialog" } }, ngImport: i0, template: `
+    @if (closeButton()) {
+      <button type="button" class="ol-popup-close" aria-label="Close" (click)="onCloseClick()">
+        ×
+      </button>
+    }
+    <ng-content />
+  `, isInline: true, styles: [":host{display:block;position:relative}.ol-popup-close{position:absolute;top:4px;right:4px;width:20px;height:20px;padding:0;border:none;background:transparent;font-size:16px;line-height:1;cursor:pointer;color:inherit}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlPopupComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ol-popup', changeDetection: ChangeDetectionStrategy.OnPush, template: `
+    @if (closeButton()) {
+      <button type="button" class="ol-popup-close" aria-label="Close" (click)="onCloseClick()">
+        ×
+      </button>
+    }
+    <ng-content />
+  `, host: {
+                        role: 'dialog',
+                    }, styles: [":host{display:block;position:relative}.ol-popup-close{position:absolute;top:4px;right:4px;width:20px;height:20px;padding:0;border:none;background:transparent;font-size:16px;line-height:1;cursor:pointer;color:inherit}\n"] }]
+        }], ctorParameters: () => [], propDecorators: { position: [{ type: i0.Input, args: [{ isSignal: true, alias: "position", required: false }] }], offset: [{ type: i0.Input, args: [{ isSignal: true, alias: "offset", required: false }] }], positioning: [{ type: i0.Input, args: [{ isSignal: true, alias: "positioning", required: false }] }], autoPan: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoPan", required: false }] }], closeButton: [{ type: i0.Input, args: [{ isSignal: true, alias: "closeButton", required: false }] }], closed: [{ type: i0.Output, args: ["closed"] }] } });
+
+// OlTooltipDirective — feature hover tooltip on a vector layer.
+/**
+ * Shows a floating tooltip whose text is read from a feature property when the
+ * pointer hovers over it. The tooltip element is appended to the map viewport
+ * and styled minimally; consumers can override via the `.ol-tooltip` CSS hook.
+ *
+ * @example
+ * ```html
+ * <ol-vector-layer
+ *   id="cities"
+ *   [features]="cities()"
+ *   [olTooltip]="'name'"
+ * />
+ * ```
+ *
+ * Apply `[olTooltipLayer]` to limit detection to a single layer (matches the
+ * value of the layer's `id` property). Without it the tooltip reacts to any
+ * feature found at the cursor.
+ */
+class OlTooltipDirective {
+    mapService = inject(OlMapService);
+    zoneHelper = inject(OlZoneHelper);
+    /** Property key to read from the hovered feature. */
+    olTooltip = input.required(...(ngDevMode ? [{ debugName: "olTooltip" }] : /* istanbul ignore next */ []));
+    /** Optional layer id; when set, only features on that layer trigger the tooltip. */
+    olTooltipLayer = input(null, ...(ngDevMode ? [{ debugName: "olTooltipLayer" }] : /* istanbul ignore next */ []));
+    element = null;
+    listener = null;
+    currentMap = null;
+    constructor() {
+        inject(DestroyRef).onDestroy(() => this.dispose());
+        this.mapService.onReady((map) => {
+            this.currentMap = map;
+            this.zoneHelper.runOutsideAngular(() => {
+                const viewport = map.getViewport();
+                const tooltip = document.createElement('div');
+                tooltip.setAttribute('role', 'tooltip');
+                tooltip.className = 'ol-tooltip';
+                Object.assign(tooltip.style, {
+                    position: 'absolute',
+                    pointerEvents: 'none',
+                    padding: '4px 8px',
+                    background: 'rgba(0, 0, 0, 0.75)',
+                    color: '#fff',
+                    fontSize: '12px',
+                    borderRadius: '4px',
+                    display: 'none',
+                    whiteSpace: 'nowrap',
+                    zIndex: '1000',
+                });
+                viewport.appendChild(tooltip);
+                this.element = tooltip;
+                const handler = (event) => {
+                    this.handlePointerMove(event, map);
+                };
+                map.on('pointermove', handler);
+                this.listener = handler;
+            });
+        });
+    }
+    handlePointerMove(event, map) {
+        const tooltip = this.element;
+        if (!tooltip)
+            return;
+        const layerId = this.olTooltipLayer();
+        const propKey = this.olTooltip();
+        let matched = null;
+        map.forEachFeatureAtPixel(event.pixel, (feature) => {
+            matched = feature;
+            return true;
+        }, {
+            layerFilter: layerId ? (layer) => layer.get('id') === layerId : undefined,
+        });
+        if (!matched) {
+            tooltip.style.display = 'none';
+            return;
+        }
+        const value = matched.get(propKey);
+        if (value === undefined || value === null) {
+            tooltip.style.display = 'none';
+            return;
+        }
+        tooltip.textContent = String(value);
+        tooltip.style.display = 'block';
+        const [x, y] = event.pixel;
+        tooltip.style.left = `${x + 12}px`;
+        tooltip.style.top = `${y + 12}px`;
+    }
+    dispose() {
+        const map = this.currentMap;
+        const listener = this.listener;
+        if (map && listener) {
+            this.zoneHelper.runOutsideAngular(() => map.un('pointermove', listener));
+        }
+        if (this.element?.parentNode) {
+            this.element.parentNode.removeChild(this.element);
+        }
+        this.element = null;
+        this.listener = null;
+        this.currentMap = null;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlTooltipDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.4", type: OlTooltipDirective, isStandalone: true, selector: "[olTooltip]", inputs: { olTooltip: { classPropertyName: "olTooltip", publicName: "olTooltip", isSignal: true, isRequired: true, transformFunction: null }, olTooltipLayer: { classPropertyName: "olTooltipLayer", publicName: "olTooltipLayer", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlTooltipDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[olTooltip]',
+                }]
+        }], ctorParameters: () => [], propDecorators: { olTooltip: [{ type: i0.Input, args: [{ isSignal: true, alias: "olTooltip", required: true }] }], olTooltipLayer: [{ type: i0.Input, args: [{ isSignal: true, alias: "olTooltipLayer", required: false }] }] } });
 
 // OlPopupService
+/**
+ * Manages OpenLayers popup overlays anchored to map coordinates.
+ *
+ * Three content modes:
+ *  - `open()`           — string text or `HTMLElement`
+ *  - `openComponent()`  — dynamic Angular component via `createComponent + hostElement`
+ *  - The `<ol-popup>` component delegates `open()` internally for declarative usage.
+ *
+ * All calls are idempotent by `id`. Calls made before the underlying `ol/Map` is ready
+ * are queued and replayed in order once `OlMapService.onReady` fires.
+ */
 class OlPopupService {
-    showPopup(options) {
-        return 'popup-id';
+    mapService = inject(OlMapService);
+    zoneHelper = inject(OlZoneHelper);
+    envInjector = inject(EnvironmentInjector);
+    appRef = inject(ApplicationRef);
+    popups = new Map();
+    pending = [];
+    flushSubscribed = false;
+    constructor() {
+        inject(DestroyRef).onDestroy(() => this.closeAll());
+    }
+    /**
+     * Open a popup with `string` or `HTMLElement` content.
+     *
+     * Idempotent by `id`: a second call with the same id updates `position` and
+     * `content` of the existing popup instead of creating a duplicate.
+     */
+    open(options) {
+        const id = options.id ?? generateId('popup');
+        const map = this.mapService.getMap();
+        if (!map) {
+            this.queue({ kind: 'open', options: { ...options, id } });
+            return { id, close: () => this.close(id) };
+        }
+        this.createOrUpdate(id, options, map);
+        return { id, close: () => this.close(id) };
+    }
+    /**
+     * Open a popup whose content is a dynamically-instantiated Angular component.
+     *
+     * Uses `createComponent({ environmentInjector, hostElement, bindings, directives })`
+     * (Angular 16.2+) and attaches the host view to `ApplicationRef` so change detection
+     * reaches the rendered component.
+     *
+     * Idempotent by `id`: a previous `ComponentRef` registered under the same id is
+     * destroyed before the new one is created.
+     */
+    openComponent(options) {
+        const id = options.id ?? generateId('popup');
+        const map = this.mapService.getMap();
+        if (!map) {
+            this.queue({
+                kind: 'openComponent',
+                options: { ...options, id },
+            });
+            return { id, close: () => this.close(id) };
+        }
+        this.createOrUpdateComponent(id, options, map);
+        return { id, close: () => this.close(id) };
+    }
+    /** Close and dispose a single popup by id. No-op when the id is unknown. */
+    close(id) {
+        const managed = this.popups.get(id);
+        if (!managed)
+            return;
+        managed.dispose();
+        this.popups.delete(id);
+    }
+    /** Close every managed popup. */
+    closeAll() {
+        const ids = [...this.popups.keys()];
+        for (const id of ids) {
+            this.close(id);
+        }
+        this.pending.length = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    queue(call) {
+        this.pending.push(call);
+        if (this.flushSubscribed)
+            return;
+        this.flushSubscribed = true;
+        this.mapService.onReady((map) => this.flushPending(map));
+    }
+    flushPending(map) {
+        const pending = this.pending.splice(0);
+        for (const call of pending) {
+            if (call.kind === 'open') {
+                this.createOrUpdate(call.options.id, call.options, map);
+            }
+            else {
+                this.createOrUpdateComponent(call.options.id, call.options, map);
+            }
+        }
+    }
+    createOrUpdate(id, options, map) {
+        const existing = this.popups.get(id);
+        if (existing && !existing.componentRef) {
+            // Update position / element of an existing string/HTMLElement popup in place.
+            this.zoneHelper.runOutsideAngular(() => {
+                existing.overlay.setPosition(options.position);
+                replaceElementContent(existing.overlay.getElement(), options.content);
+                applyOverlayConfig(existing.overlay, options);
+            });
+            return;
+        }
+        if (existing) {
+            // Type changed (was a component popup) — dispose and recreate.
+            this.close(id);
+        }
+        this.zoneHelper.runOutsideAngular(() => {
+            const element = buildContentElement(options.content, options.className);
+            const overlay = new Overlay({
+                element,
+                position: options.position,
+                positioning: options.positioning ?? 'bottom-center',
+                offset: options.offset ?? [0, 0],
+                autoPan: options.autoPan ?? false,
+            });
+            map.addOverlay(overlay);
+            const dispose = () => {
+                this.zoneHelper.runOutsideAngular(() => {
+                    map.removeOverlay(overlay);
+                });
+            };
+            this.popups.set(id, { id, overlay, dispose });
+        });
+    }
+    createOrUpdateComponent(id, options, map) {
+        // Always recreate component popups on a second call — simpler and safer than
+        // trying to re-bind inputs on an already-created ref.
+        if (this.popups.has(id)) {
+            this.close(id);
+        }
+        this.zoneHelper.runOutsideAngular(() => {
+            const hostElement = document.createElement('div');
+            if (options.className)
+                hostElement.className = options.className;
+            const ref = createComponent(options.component, {
+                environmentInjector: this.envInjector,
+                elementInjector: options.injector,
+                hostElement,
+                bindings: options.bindings,
+                directives: options.directives?.map((d) => typeof d === 'function' ? d : { type: d.type, bindings: d.bindings ?? [] }),
+            });
+            this.appRef.attachView(ref.hostView);
+            const overlay = new Overlay({
+                element: hostElement,
+                position: options.position,
+                positioning: options.positioning ?? 'bottom-center',
+                offset: options.offset ?? [0, 0],
+                autoPan: options.autoPan ?? false,
+            });
+            map.addOverlay(overlay);
+            const dispose = () => {
+                this.zoneHelper.runOutsideAngular(() => {
+                    map.removeOverlay(overlay);
+                    this.appRef.detachView(ref.hostView);
+                    ref.destroy();
+                });
+            };
+            this.popups.set(id, { id, overlay, componentRef: ref, dispose });
+        });
     }
-    hidePopup(id) { }
-    hideAllPopups() { }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlPopupService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlPopupService });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: OlPopupService, decorators: [{
             type: Injectable
-        }] });
+        }], ctorParameters: () => [] });
+// -----------------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------------
+function generateId(prefix) {
+    return `${prefix}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function buildContentElement(content, className) {
+    const wrapper = document.createElement('div');
+    if (className)
+        wrapper.className = className;
+    replaceElementContent(wrapper, content);
+    return wrapper;
+}
+function replaceElementContent(element, content) {
+    while (element.firstChild)
+        element.removeChild(element.firstChild);
+    if (typeof content === 'string') {
+        element.textContent = content;
+    }
+    else {
+        element.appendChild(content);
+    }
+}
+function applyOverlayConfig(overlay, config) {
+    if (config.positioning)
+        overlay.setPositioning(config.positioning);
+    if (config.offset)
+        overlay.setOffset(config.offset);
+}
 
 function withOverlays() {
     return { kind: 'overlays', providers: [OlPopupService] };
@@ -28,4 +458,4 @@ function provideOverlays() {
  * Generated bundle index. Do not edit.
  */
 
-export { OlPopupService, provideOverlays, withOverlays };
+export { OlPopupComponent, OlPopupService, OlTooltipDirective, provideOverlays, withOverlays };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/openlayers",
-  "version": "0.2.0",
+  "version": "0.3.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": {
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@angular/core": "^21.0.0",
     "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
     "ol": "^10.0.0"
   },
   "peerDependenciesMeta": {

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

@@ -1,29 +1,214 @@
+import * as _angular_core from '@angular/core';
+import { Type, Binding, Injector } from '@angular/core';
 import { Coordinate, OlFeature } from '@angular-helpers/openlayers/core';
-import * as i0 from '@angular/core';
 
-type OverlayPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'left-center' | 'right-center';
+/**
+ * Anchor of the overlay element relative to its `position` coordinate.
+ * Mirrors the values accepted by `ol/Overlay#setPositioning`.
+ */
+type OverlayPositioning = 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center-left' | 'center-center' | 'center-right' | 'top-left' | 'top-center' | 'top-right';
+/**
+ * Common positioning options shared by every popup mode.
+ */
 interface OverlayConfig {
-    position?: OverlayPosition;
+    positioning?: OverlayPositioning;
     offset?: [number, number];
+    className?: string;
+    autoPan?: boolean;
 }
-interface PopupOptions {
+/**
+ * Options for `OlPopupService.open()` — string / HTMLElement content.
+ */
+interface PopupOpenOptions extends OverlayConfig {
+    /** Unique id for the popup. Generated when omitted. */
     id?: string;
+    /** Map coordinate where the popup is anchored. */
+    position: Coordinate;
+    /**
+     * Popup content. A `string` is rendered as text via `textContent` (no HTML parsing).
+     * Pass an `HTMLElement` when richer DOM is required.
+     */
     content: string | HTMLElement;
+}
+/**
+ * Options for `OlPopupService.openComponent()` — dynamic Angular component content.
+ *
+ * Internally uses `createComponent + hostElement` (Angular 16.2+) so consumers can wire
+ * `inputBinding` / `outputBinding` / `twoWayBinding` declaratively.
+ */
+interface PopupComponentOptions<C> extends OverlayConfig {
+    id?: string;
     position: Coordinate;
+    /** The component class to instantiate. */
+    component: Type<C>;
+    /** Bindings created via `inputBinding`, `outputBinding`, `twoWayBinding`. */
+    bindings?: Binding[];
+    /** Optional host directives applied to the dynamically-created component. */
+    directives?: ReadonlyArray<Type<unknown> | {
+        readonly type: Type<unknown>;
+        readonly bindings?: Binding[];
+    }>;
+    /** Optional element injector for the component (defaults to the service's injector). */
+    injector?: Injector;
+}
+/**
+ * Handle returned by `OlPopupService.open()` and `openComponent()`.
+ * Use it to close the popup imperatively without going through the service.
+ */
+interface PopupHandle {
+    readonly id: string;
+    close(): void;
+}
+/**
+ * @deprecated Use {@link PopupOpenOptions} instead. Kept for backwards compatibility
+ *   with the v0.2.x stub API and removed in a future major version.
+ */
+type PopupOptions = PopupOpenOptions & {
+    /** No-op flag retained for source compatibility. */
     autoClose?: boolean;
+    /** Whether to render the default close button (deprecated, prefer `<ol-popup>`). */
     closeButton?: boolean;
+};
+/**
+ * @deprecated Use {@link OverlayPositioning} instead.
+ */
+type OverlayPosition = OverlayPositioning;
+
+/**
+ * Declarative map popup that projects arbitrary Angular content via `<ng-content>`.
+ *
+ * The component's host element is used directly as the `ol/Overlay`'s element, so
+ * projected children stay inside Angular's component tree and benefit from change
+ * detection without any extra plumbing.
+ *
+ * @example
+ * ```html
+ * <ol-popup
+ *   [position]="selectedCoord()"
+ *   [closeButton]="true"
+ *   [autoPan]="true"
+ *   (closed)="clearSelection()"
+ * >
+ *   <h3>{{ selected()?.name }}</h3>
+ *   <p>{{ selected()?.description }}</p>
+ * </ol-popup>
+ * ```
+ */
+declare class OlPopupComponent {
+    private readonly elementRef;
+    private readonly mapService;
+    private readonly zoneHelper;
+    /** Map coordinate where the popup is anchored. `null` hides the popup. */
+    readonly position: _angular_core.InputSignal<Coordinate>;
+    /** Pixel offset relative to `position`. */
+    readonly offset: _angular_core.InputSignal<[number, number]>;
+    /** Anchor of the popup element relative to `position`. */
+    readonly positioning: _angular_core.InputSignal<OverlayPositioning>;
+    /** Whether the map auto-pans to keep the popup in view. */
+    readonly autoPan: _angular_core.InputSignal<boolean>;
+    /** Whether to render the default close button. */
+    readonly closeButton: _angular_core.InputSignal<boolean>;
+    /** Emitted when the popup transitions from visible to hidden (close button or `position` set to null). */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    private overlay;
+    private currentMap;
+    private wasVisible;
+    constructor();
+    /** @internal */
+    onCloseClick(): void;
+    private applyState;
+    private dispose;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlPopupComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlPopupComponent, "ol-popup", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "positioning": { "alias": "positioning"; "required": false; "isSignal": true; }; "autoPan": { "alias": "autoPan"; "required": false; "isSignal": true; }; "closeButton": { "alias": "closeButton"; "required": false; "isSignal": true; }; }, { "closed": "closed"; }, never, ["*"], true, never>;
+}
+
+/**
+ * Shows a floating tooltip whose text is read from a feature property when the
+ * pointer hovers over it. The tooltip element is appended to the map viewport
+ * and styled minimally; consumers can override via the `.ol-tooltip` CSS hook.
+ *
+ * @example
+ * ```html
+ * <ol-vector-layer
+ *   id="cities"
+ *   [features]="cities()"
+ *   [olTooltip]="'name'"
+ * />
+ * ```
+ *
+ * Apply `[olTooltipLayer]` to limit detection to a single layer (matches the
+ * value of the layer's `id` property). Without it the tooltip reacts to any
+ * feature found at the cursor.
+ */
+declare class OlTooltipDirective {
+    private readonly mapService;
+    private readonly zoneHelper;
+    /** Property key to read from the hovered feature. */
+    readonly olTooltip: _angular_core.InputSignal<string>;
+    /** Optional layer id; when set, only features on that layer trigger the tooltip. */
+    readonly olTooltipLayer: _angular_core.InputSignal<string>;
+    private element;
+    private listener;
+    private currentMap;
+    constructor();
+    private handlePointerMove;
+    private dispose;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlTooltipDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<OlTooltipDirective, "[olTooltip]", never, { "olTooltip": { "alias": "olTooltip"; "required": true; "isSignal": true; }; "olTooltipLayer": { "alias": "olTooltipLayer"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Manages OpenLayers popup overlays anchored to map coordinates.
+ *
+ * Three content modes:
+ *  - `open()`           — string text or `HTMLElement`
+ *  - `openComponent()`  — dynamic Angular component via `createComponent + hostElement`
+ *  - The `<ol-popup>` component delegates `open()` internally for declarative usage.
+ *
+ * All calls are idempotent by `id`. Calls made before the underlying `ol/Map` is ready
+ * are queued and replayed in order once `OlMapService.onReady` fires.
+ */
 declare class OlPopupService {
-    showPopup(options: PopupOptions): string;
-    hidePopup(id: string): void;
-    hideAllPopups(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<OlPopupService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<OlPopupService>;
+    private readonly mapService;
+    private readonly zoneHelper;
+    private readonly envInjector;
+    private readonly appRef;
+    private readonly popups;
+    private readonly pending;
+    private flushSubscribed;
+    constructor();
+    /**
+     * Open a popup with `string` or `HTMLElement` content.
+     *
+     * Idempotent by `id`: a second call with the same id updates `position` and
+     * `content` of the existing popup instead of creating a duplicate.
+     */
+    open(options: PopupOpenOptions): PopupHandle;
+    /**
+     * Open a popup whose content is a dynamically-instantiated Angular component.
+     *
+     * Uses `createComponent({ environmentInjector, hostElement, bindings, directives })`
+     * (Angular 16.2+) and attaches the host view to `ApplicationRef` so change detection
+     * reaches the rendered component.
+     *
+     * Idempotent by `id`: a previous `ComponentRef` registered under the same id is
+     * destroyed before the new one is created.
+     */
+    openComponent<C>(options: PopupComponentOptions<C>): PopupHandle;
+    /** Close and dispose a single popup by id. No-op when the id is unknown. */
+    close(id: string): void;
+    /** Close every managed popup. */
+    closeAll(): void;
+    private queue;
+    private flushPending;
+    private createOrUpdate;
+    private createOrUpdateComponent;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlPopupService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<OlPopupService>;
 }
 
 declare function withOverlays(): OlFeature<'overlays'>;
 declare function provideOverlays(): OlFeature<'overlays'>;
 
-export { OlPopupService, provideOverlays, withOverlays };
-export type { OverlayConfig, OverlayPosition, PopupOptions };
+export { OlPopupComponent, OlPopupService, OlTooltipDirective, provideOverlays, withOverlays };
+export type { OverlayConfig, OverlayPosition, OverlayPositioning, PopupComponentOptions, PopupHandle, PopupOpenOptions, PopupOptions };