@angular-helpers/openlayers 0.1.1 → 0.3.0

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 };