@angular-helpers/openlayers 0.2.0 → 0.4.0

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

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