@angular-helpers/openlayers 0.1.0 → 0.2.0

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

@@ -1,62 +1,196 @@
 import * as _angular_core from '@angular/core';
-import { OnInit, OnDestroy } from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import OLMap from 'ol/Map';
 import { OlFeature } from '@angular-helpers/openlayers/core';
 
-declare class OlZoomControlComponent implements OnInit, OnDestroy {
+declare class OlZoomControlComponent {
     private mapService;
-    private ngZone;
+    private zoneHelper;
     delta: _angular_core.InputSignal<number>;
     duration: _angular_core.InputSignal<number>;
     private control?;
-    ngOnInit(): void;
-    private tryAddControl;
-    ngOnDestroy(): void;
+    constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlZoomControlComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlZoomControlComponent, "ol-zoom-control", never, { "delta": { "alias": "delta"; "required": false; "isSignal": true; }; "duration": { "alias": "duration"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-declare class OlAttributionControlComponent implements OnInit, OnDestroy {
+declare class OlAttributionControlComponent {
     private mapService;
-    private ngZone;
+    private zoneHelper;
     collapsible: _angular_core.InputSignal<boolean>;
     collapsed: _angular_core.InputSignal<boolean>;
     private control?;
-    ngOnInit(): void;
-    private tryAddControl;
-    ngOnDestroy(): void;
+    constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlAttributionControlComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlAttributionControlComponent, "ol-attribution-control", never, { "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-declare class OlScaleLineControlComponent implements OnInit, OnDestroy {
+declare class OlScaleLineControlComponent {
     private mapService;
-    private ngZone;
+    private zoneHelper;
     units: _angular_core.InputSignal<"metric" | "imperial" | "nautical" | "us">;
     bar: _angular_core.InputSignal<boolean>;
     steps: _angular_core.InputSignal<number>;
     private control?;
-    ngOnInit(): void;
-    private tryAddControl;
-    ngOnDestroy(): void;
+    constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlScaleLineControlComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlScaleLineControlComponent, "ol-scale-line-control", never, { "units": { "alias": "units"; "required": false; "isSignal": true; }; "bar": { "alias": "bar"; "required": false; "isSignal": true; }; "steps": { "alias": "steps"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-declare class OlFullscreenControlComponent implements OnInit, OnDestroy {
+declare class OlFullscreenControlComponent {
     private mapService;
-    private ngZone;
+    private zoneHelper;
     source: _angular_core.InputSignal<HTMLElement>;
     label: _angular_core.InputSignal<string>;
     labelActive: _angular_core.InputSignal<string>;
     tipLabel: _angular_core.InputSignal<string>;
     private control?;
-    ngOnInit(): void;
-    private tryAddControl;
-    ngOnDestroy(): void;
+    constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlFullscreenControlComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlFullscreenControlComponent, "ol-fullscreen-control", never, { "source": { "alias": "source"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelActive": { "alias": "labelActive"; "required": false; "isSignal": true; }; "tipLabel": { "alias": "tipLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Interface for map service that rotate control needs
+ * Implement this or provide your OlMapService using this token
+ */
+interface RotateControlMapService {
+    getMap(): OLMap | null;
+    onReady(callback: (map: OLMap) => void): void;
+}
+/**
+ * Injection token for map service used by rotate control
+ * Consumers should provide their OlMapService using this token:
+ * ```ts
+ * { provide: ROTATE_CONTROL_MAP_SERVICE, useExisting: OlMapService }
+ * ```
+ */
+declare const ROTATE_CONTROL_MAP_SERVICE: InjectionToken<RotateControlMapService>;
+declare class OlRotateControlComponent {
+    private mapService;
+    private zoneHelper;
+    autoHide: _angular_core.InputSignal<boolean>;
+    duration: _angular_core.InputSignal<number>;
+    tipLabel: _angular_core.InputSignal<string>;
+    private control?;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlRotateControlComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlRotateControlComponent, "ol-rotate-control", never, { "autoHide": { "alias": "autoHide"; "required": false; "isSignal": true; }; "duration": { "alias": "duration"; "required": false; "isSignal": true; }; "tipLabel": { "alias": "tipLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Item representing a layer in the layer switcher UI
+ */
+interface LayerSwitcherItem {
+    /** Unique identifier for the layer */
+    id: string;
+    /** Display name for the layer */
+    name: string;
+    /** Type of the layer */
+    type: 'vector' | 'tile' | 'image';
+    /** Whether the layer is currently visible */
+    visible: boolean;
+    /** Opacity of the layer (0-1) */
+    opacity: number;
+}
+/**
+ * Position options for the layer switcher control
+ */
+type LayerSwitcherPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/**
+ * A reusable layer switcher control that displays all layers
+ * and allows toggling their visibility.
+ *
+ * @usageNotes
+ * ```html
+ * <ol-layer-switcher
+ *   position="top-right"
+ *   [layers]="layerItems()"
+ *   [collapsible]="true"
+ *   [showOpacity]="true"
+ *   (visibilityChange)="onVisibilityChange($event)"
+ *   (opacityChange)="onOpacityChange($event)">
+ * </ol-layer-switcher>
+ * ```
+ */
+declare class OlLayerSwitcherComponent {
+    position: _angular_core.InputSignal<"top-left" | "top-right" | "bottom-left" | "bottom-right">;
+    layers: _angular_core.InputSignal<LayerSwitcherItem[]>;
+    collapsible: _angular_core.InputSignal<boolean>;
+    showOpacity: _angular_core.InputSignal<boolean>;
+    startCollapsed: _angular_core.InputSignal<boolean>;
+    visibilityChange: _angular_core.OutputEmitterRef<{
+        id: string;
+        visible: boolean;
+    }>;
+    opacityChange: _angular_core.OutputEmitterRef<{
+        id: string;
+        opacity: number;
+    }>;
+    protected isCollapsed: _angular_core.WritableSignal<boolean>;
+    toggleCollapsed(): void;
+    toggleLayer(id: string): void;
+    setOpacity(id: string, event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlLayerSwitcherComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlLayerSwitcherComponent, "ol-layer-switcher", never, { "position": { "alias": "position"; "required": false; "isSignal": true; }; "layers": { "alias": "layers"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "showOpacity": { "alias": "showOpacity"; "required": false; "isSignal": true; }; "startCollapsed": { "alias": "startCollapsed"; "required": false; "isSignal": true; }; }, { "visibilityChange": "visibilityChange"; "opacityChange": "opacityChange"; }, never, never, true, never>;
+}
+
+/**
+ * Configuration for a basemap (background layer)
+ */
+interface BasemapConfig {
+    /** Unique identifier for the basemap */
+    id: string;
+    /** Display name for the basemap */
+    name: string;
+    /** Type of tile source */
+    type: 'osm' | 'xyz' | 'wms';
+    /** URL template for XYZ/WMS sources */
+    url?: string;
+    /** Additional parameters for WMS requests */
+    params?: Record<string, unknown>;
+    /** Attribution text */
+    attributions?: string | string[];
+    /** Optional icon/emoji */
+    icon?: string;
+}
+/**
+ * Position options for the basemap switcher control
+ */
+type BasemapSwitcherPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/**
+ * A basemap switcher control that allows switching between
+ * different tile providers without page refresh.
+ *
+ * @usageNotes
+ * ```html
+ * <ol-basemap-switcher
+ *   position="bottom-left"
+ *   [basemaps]="[
+ *     { id: 'osm', name: 'OpenStreetMap', type: 'osm' },
+ *     { id: 'satellite', name: 'Satellite', type: 'xyz', url: 'https://...' }
+ *   ]"
+ *   [activeBasemap]="'osm'"
+ *   (basemapChange)="onBasemapChange($event)">
+ * </ol-basemap-switcher>
+ * ```
+ */
+declare class OlBasemapSwitcherComponent {
+    basemaps: _angular_core.InputSignal<BasemapConfig[]>;
+    activeBasemap: _angular_core.InputSignal<string>;
+    position: _angular_core.InputSignal<BasemapSwitcherPosition>;
+    basemapChange: _angular_core.OutputEmitterRef<string>;
+    protected isExpanded: _angular_core.WritableSignal<boolean>;
+    toggleExpanded(): void;
+    switchBasemap(basemap: BasemapConfig): void;
+    getActiveBasemapName(): string;
+    getDefaultIcon(basemap: BasemapConfig): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlBasemapSwitcherComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlBasemapSwitcherComponent, "ol-basemap-switcher", never, { "basemaps": { "alias": "basemaps"; "required": false; "isSignal": true; }; "activeBasemap": { "alias": "activeBasemap"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; }, { "basemapChange": "basemapChange"; }, never, never, true, never>;
+}
+
 type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center' | 'left-center' | 'right-center';
 interface ControlConfig {
     position?: ControlPosition;
@@ -70,8 +204,12 @@ declare class OlControlService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<OlControlService>;
 }
 
+/**
+ * Provides control services and configures the rotate control map service alias.
+ * Requires OlMapService to be provided at the application level.
+ */
 declare function withControls(): OlFeature<'controls'>;
 declare function provideControls(): OlFeature<'controls'>;
 
-export { OlAttributionControlComponent, OlControlService, OlFullscreenControlComponent, OlScaleLineControlComponent, OlZoomControlComponent, provideControls, withControls };
-export type { ControlConfig, ControlPosition };
+export { OlAttributionControlComponent, OlBasemapSwitcherComponent, OlControlService, OlFullscreenControlComponent, OlLayerSwitcherComponent, OlRotateControlComponent, OlScaleLineControlComponent, OlZoomControlComponent, ROTATE_CONTROL_MAP_SERVICE, provideControls, withControls };
+export type { BasemapConfig, BasemapSwitcherPosition, ControlConfig, ControlPosition, LayerSwitcherItem, LayerSwitcherPosition, RotateControlMapService };

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

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { AfterViewInit, OnDestroy, ElementRef, Provider, EnvironmentProviders } from '@angular/core';
+import { ElementRef, Provider, EnvironmentProviders } from '@angular/core';
 import OLMap from 'ol/Map';
 import { View } from 'ol';
 
@@ -70,9 +70,10 @@ interface MapClickEvent {
     coordinate: Coordinate;
     pixel: Pixel;
 }
-declare class OlMapComponent implements AfterViewInit, OnDestroy {
+declare class OlMapComponent {
     private mapService;
-    private ngZone;
+    private zoneHelper;
+    private destroyRef;
     center: _angular_core.InputSignal<Coordinate>;
     zoom: _angular_core.InputSignal<number>;
     rotation: _angular_core.InputSignal<number>;
@@ -83,8 +84,6 @@ declare class OlMapComponent implements AfterViewInit, OnDestroy {
     mapContainerRef: _angular_core.Signal<ElementRef<HTMLDivElement>>;
     private map?;
     constructor();
-    ngAfterViewInit(): void;
-    ngOnDestroy(): void;
     private initMap;
     private destroyMap;
     private updateCenter;
@@ -95,30 +94,55 @@ declare class OlMapComponent implements AfterViewInit, OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<OlMapComponent, "ol-map", never, { "center": { "alias": "center"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "rotation": { "alias": "rotation"; "required": false; "isSignal": true; }; "projection": { "alias": "projection"; "required": false; "isSignal": true; }; }, { "viewChange": "viewChange"; "mapClick": "mapClick"; "mapDblClick": "mapDblClick"; }, never, ["*"], true, never>;
 }
 
+/**
+ * Options for animating the map view.
+ */
 interface AnimationOptions {
+    /** Target center coordinate */
     center?: Coordinate;
+    /** Target zoom level */
     zoom?: number;
+    /** Target rotation in radians */
     rotation?: number;
+    /** Animation duration in milliseconds */
     duration?: number;
 }
+/**
+ * Options for fitting the view to an extent.
+ */
 interface FitOptions {
+    /** Padding around the extent [top, right, bottom, left] */
     padding?: [number, number, number, number];
+    /** Maximum zoom level to use */
     maxZoom?: number;
+    /** Animation duration in milliseconds */
     duration?: number;
 }
+/**
+ * Configuration options for the map view.
+ */
 interface MapViewOptions {
+    /** Initial center coordinate */
     center?: Coordinate;
+    /** Initial zoom level */
     zoom?: number;
+    /** Minimum allowed zoom */
     minZoom?: number;
+    /** Maximum allowed zoom */
     maxZoom?: number;
+    /** Initial rotation in radians */
     rotation?: number;
+    /** Map projection (e.g., 'EPSG:3857') */
     projection?: string;
 }
+
 declare class OlMapService {
-    private ngZone;
+    private zoneHelper;
     private map;
+    private readyCallbacks;
     setMap(map: OLMap): void;
     getMap(): OLMap | null;
+    onReady(callback: (map: OLMap) => void): void;
     getView(): View | null;
     setCenter(coordinate: Coordinate): void;
     setZoom(level: number): void;
@@ -133,6 +157,47 @@ declare class OlMapService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<OlMapService>;
 }
 
+/**
+ * Helper service that abstracts NgZone operations for zoneless compatibility.
+ *
+ * When NgZone is available (classic Angular):
+ * - runOutsideAngular: executes outside Angular's zone for performance
+ * - runInsideAngular: executes inside Angular's zone to trigger change detection
+ *
+ * When zoneless (signals-only Angular):
+ * - Both methods execute directly since signals handle reactivity
+ *
+ * @usageNotes
+ * Inject this service instead of NgZone directly:
+ * ```ts
+ * private zoneHelper = inject(OlZoneHelper);
+ *
+ * this.zoneHelper.runOutsideAngular(() => {
+ *   // OpenLayers operations that don't need CD
+ * });
+ * ```
+ */
+declare class OlZoneHelper {
+    private ngZone;
+    /**
+     * Runs callback outside Angular zone if available (for performance with NgZone),
+     * or directly if zoneless.
+     *
+     * Use for: OpenLayers operations that don't need to trigger Angular change detection
+     * (map manipulation, event listeners, animations)
+     */
+    runOutsideAngular<T>(fn: () => T): T;
+    /**
+     * Runs callback inside Angular zone if available (for triggering CD),
+     * or directly if zoneless.
+     *
+     * Use for: Emitting outputs that should be handled by parent components
+     */
+    runInsideAngular<T>(fn: () => T): T;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<OlZoneHelper, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<OlZoneHelper>;
+}
+
 type OlFeatureKind = 'layers' | 'controls' | 'interactions' | 'overlays' | 'military';
 interface OlFeature<Kind extends OlFeatureKind> {
     kind: Kind;
@@ -140,5 +205,5 @@ interface OlFeature<Kind extends OlFeatureKind> {
 }
 declare function provideOpenLayers(...features: OlFeature<OlFeatureKind>[]): EnvironmentProviders;
 
-export { OlMapComponent, OlMapService, provideOpenLayers };
+export { OlMapComponent, OlMapService, OlZoneHelper, provideOpenLayers };
 export type { AnimationOptions, Coordinate, Extent, Feature, FitOptions, Geometry, GeometryType, Layer, MapClickEvent, MapConfig, MapViewOptions, OlFeature, OlFeatureKind, Pixel, ProjectionCode, Style, ViewState };