leaflet/src/types.ts

JavaScript library for mobile-friendly interactive maps

// Public types that JSDoc can't express. Options, event maps and event objects are interfaces rather than JSDoc
// typedefs (type aliases), since only interfaces merge with a plugin's `declare module 'leaflet'` augmentation;
// their members are documented in typedefs next to the code they belong to, and the interfaces here only extend them.

import type {Feature, Geometry, Point as GeoJSONPoint, Position} from 'geojson';
import type {Evented, LeafletEventProps, Listener} from './core/Events.js';
import type {DragEndEventProps, DraggableDefaultsValues, DraggableEvents} from './dom/Draggable.js';
import type {LatLng} from './geo/LatLng.js';
import type {LatLngBounds} from './geo/LatLngBounds.js';
import type {Bounds} from './geometry/Bounds.js';
import type {Point, PointExpression} from './geometry/Point.js';
import type {BlanketOverlayDefaultsValues} from './layer/BlanketOverlay.js';
import type {DivOverlayDefaultsValues, DivOverlayEvents} from './layer/DivOverlay.js';
import type {ImageOverlayDefaultsValues, ImageOverlayEvents} from './layer/ImageOverlay.js';
import type {InteractiveLayerEvents, InteractiveLayerProps, Layer} from './layer/Layer.js';
import type {FeatureGroupEvents} from './layer/FeatureGroup.js';
import type {GeoJSONEventProps, StyleFunction} from './layer/GeoJSON.js';
import type {DefaultIconDefaultsValues} from './layer/marker/DefaultIcon.js';
import type {DivIconDefaultsValues} from './layer/marker/DivIcon.js';
import type {IconDefaultsValues} from './layer/marker/Icon.js';
import type {MarkerDefaultsValues, MarkerDragEvents, MarkerEvents, MarkerMoveEventProps} from './layer/marker/Marker.js';
import type {LayerDefaultsValues, LayerEvents, LayerPopupEvents, LayerTooltipEvents} from './layer/LayerBase.js';
import type {Popup, PopupDefaultsValues, PopupEventProps, PopupProps} from './layer/Popup.js';
import type {VideoOverlayDefaultsValues, VideoOverlayEvents} from './layer/VideoOverlay.js';
import type {GridLayerDefaultsValues, GridLayerEvents, TileErrorEventProps, TileEventProps}
	from './layer/tile/GridLayer.js';
import type {TileLayerDefaultsValues, TileLayerEvents} from './layer/tile/TileLayer.js';
import type {WMSParamsDefaults, WMSTileLayerDefaultsValues} from './layer/tile/WMSTileLayer.js';
import type {Tooltip, TooltipDefaultsValues, TooltipEventProps} from './layer/Tooltip.js';
import type {CanvasDefaultsValues, DrawOrder} from './layer/vector/Canvas.js';
import type {CircleMarker, CircleMarkerDefaultsValues, CircleMarkerEvents} from './layer/vector/CircleMarker.js';
import type {Path, PathDefaultsValues} from './layer/vector/Path.js';
import type {Polyline, PolylineDefaultsValues} from './layer/vector/Polyline.js';
import type {Renderer, RendererEvents} from './layer/vector/Renderer.js';
import type {AttributionControl, AttributionControlDefaultsValues} from './control/AttributionControl.js';
import type {ControlDefaultsValues} from './control/Control.js';
import type {LayersControlDefaultsValues, LayersControlEventProps} from './control/LayersControl.js';
import type {ScaleControlDefaultsValues} from './control/ScaleControl.js';
import type {ZoomControlDefaultsValues} from './control/ZoomControl.js';
import type {BoxZoomEventProps, BoxZoomHandler} from './map/handler/BoxZoomHandler.js';
import type {DoubleClickZoomHandler} from './map/handler/DoubleClickZoomHandler.js';
import type {DragHandler} from './map/handler/DragHandler.js';
import type {KeyboardHandler} from './map/handler/KeyboardHandler.js';
import type {PinchZoomHandler} from './map/handler/PinchZoomHandler.js';
import type {ScrollWheelZoomHandler} from './map/handler/ScrollWheelZoomHandler.js';
import type {TapHoldHandler} from './map/handler/TapHoldHandler.js';
import type {ErrorEventProps, FitBoundsProps, InvalidateSizeProps, LayerEventProps, LeafletKeyboardEventProps,
	LeafletMap, LeafletPointerEventProps, LocateProps, LocationEventProps, MapDefaultsValues, MapHandlerEvents,
	MapInteractionEvents, MapLayerEvents, MapLocationEvents, MapOtherEvents, MapPopupEvents, MapStateEvents,
	MapTooltipEvents, PaddingProps, PanProps, ResizeEventProps, ViewPreResetEventProps, WorldCopyJumpEventProps,
	ZoomAnimEventProps, ZoomPanProps, ZoomProps} from './map/Map.js';

export type {Defaults} from './core/Class.js';
export type {LeafletEventHandlerFn, Listener, ListenerMap} from './core/Events.js';
export type {PointExpression, PointTuple} from './geometry/Point.js';
export type {BoundsExpression, BoundsLiteral} from './geometry/Bounds.js';
export type {LatLngExpression, LatLngLiteral, LatLngTuple} from './geo/LatLng.js';
export type {NestedCoords} from './geometry/LineUtil.js';
export type {LatLngBoundsExpression, LatLngBoundsLiteral} from './geo/LatLngBounds.js';
export type {Projection} from './geo/crs/CRS.js';
export type {Coords, DoneCallback} from './layer/tile/GridLayer.js';
export type {StyleFunction} from './layer/GeoJSON.js';
export type {ControlPosition} from './control/Control.js';

export interface DraggableDefaults extends DraggableDefaultsValues {}
export interface DraggableOptions extends Partial<DraggableDefaults> {}
export interface DraggableEventMap extends DraggableEvents {}

export interface LayerDefaults extends LayerDefaultsValues {}
export interface LayerOptions extends Partial<LayerDefaults> {}
export interface LayerEventMap extends LayerEvents, LayerPopupEvents, LayerTooltipEvents {}

/**
 * Some `Layer`s can be made interactive - when the user interacts with such a layer, pointer events like `click`
 * and `pointerover` can be handled. Use the [event handling methods](#evented-method) to handle these events.
 */
export interface InteractiveLayerOptions extends LayerOptions, Partial<InteractiveLayerProps> {}

export interface InteractiveLayerEventMap extends LayerEventMap, InteractiveLayerEvents {}

export interface DivOverlayDefaults extends DivOverlayDefaultsValues {}
export interface DivOverlayOptions extends InteractiveLayerOptions, Partial<DivOverlayDefaults> {}
export interface DivOverlayEventMap extends InteractiveLayerEventMap, DivOverlayEvents {}

export interface PopupDefaults extends PopupDefaultsValues {}
export interface PopupOptions extends DivOverlayOptions, Partial<PopupDefaults>, PopupProps {}

export interface TooltipDefaults extends TooltipDefaultsValues {}
export interface TooltipOptions extends DivOverlayOptions, Partial<TooltipDefaults> {}

// Subclass defaults that override inherited options are checked with `@satisfies` and left out here, so that the
// option keeps the parent's type rather than the narrower one of its default value.
export interface IconDefaults extends IconDefaultsValues {}
export interface IconOptions extends Partial<IconDefaults> {}
export interface DivIconDefaults extends Omit<DivIconDefaultsValues, keyof IconOptions> {}
export interface DivIconOptions extends IconOptions, Partial<DivIconDefaults> {}
export interface DefaultIconDefaults extends Omit<DefaultIconDefaultsValues, keyof IconOptions> {}
export interface DefaultIconOptions extends IconOptions, Partial<DefaultIconDefaults> {}

export interface MarkerDefaults extends MarkerDefaultsValues {}
export interface MarkerOptions extends InteractiveLayerOptions, Partial<MarkerDefaults> {}
export interface MarkerEventMap extends InteractiveLayerEventMap, MarkerEvents, MarkerDragEvents {}

export interface FeatureGroupEventMap extends InteractiveLayerEventMap, FeatureGroupEvents {}

export interface BlanketOverlayDefaults extends BlanketOverlayDefaultsValues {}
export interface BlanketOverlayOptions extends LayerOptions, Partial<BlanketOverlayDefaults> {}

export interface ImageOverlayDefaults extends ImageOverlayDefaultsValues {}
export interface ImageOverlayOptions extends InteractiveLayerOptions, Partial<ImageOverlayDefaults> {}
export interface ImageOverlayEventMap extends InteractiveLayerEventMap, ImageOverlayEvents {}

export interface VideoOverlayDefaults extends VideoOverlayDefaultsValues {}
export interface VideoOverlayOptions extends ImageOverlayOptions, Partial<VideoOverlayDefaults> {}
export interface VideoOverlayEventMap extends ImageOverlayEventMap, VideoOverlayEvents {}

export interface RendererOptions extends BlanketOverlayOptions {}
export interface RendererEventMap extends LayerEventMap, RendererEvents {}
export interface CanvasDefaults extends CanvasDefaultsValues {}
export interface CanvasOptions extends RendererOptions, Partial<CanvasDefaults> {}

export interface PathDefaults extends PathDefaultsValues {}
export interface PathOptions extends InteractiveLayerOptions, Partial<PathDefaults> {
	/**
	 * Custom class name set on an element. Only for SVG renderer. Applied when the element is created;
	 * [`setStyle`](#path-setstyle) does not update it afterwards.
	 */
	className?: string;
}

export interface PolylineDefaults extends PolylineDefaultsValues {}
export interface PolylineOptions extends PathOptions, Partial<PolylineDefaults> {}

export interface CircleMarkerDefaults extends Omit<CircleMarkerDefaultsValues, keyof PathOptions> {}
export interface CircleMarkerOptions extends PathOptions, Partial<CircleMarkerDefaults> {}
export interface CircleMarkerEventMap extends InteractiveLayerEventMap, CircleMarkerEvents {}

export interface CircleOptions extends CircleMarkerOptions {
	/** Radius of the circle, in meters. */
	radius?: number;
}

// The callbacks use method syntax, so a callback typed with the user's own feature properties is accepted.
export interface GeoJSONOptions extends InteractiveLayerOptions {
	/**
	 * A function defining how GeoJSON points spawn Leaflet layers. It is internally called when data is added,
	 * passing the GeoJSON point feature and its `LatLng`. The default is to spawn a default `Marker`:
	 * ```js
	 * function(geoJsonPoint, latlng) {
	 * 	return new Marker(latlng);
	 * }
	 * ```
	 */
	pointToLayer?(geoJsonPoint: Feature<GeoJSONPoint, any>, latlng: LatLng): Layer;
	/**
	 * `Path` options, or a function returning them for a feature, for styling GeoJSON lines and polygons. Called
	 * internally when data is added. The default value is to not override any defaults:
	 * ```js
	 * function (geoJsonFeature) {
	 * 	return {}
	 * }
	 * ```
	 */
	style?: Partial<PathOptions> | StyleFunction;
	/**
	 * A function that will be called once for each created `Feature`, after it has been created and styled.
	 * Useful for attaching events and popups to features. It will receive the `feature` as the first argument and
	 * its corresponding spawned `layer` from [`asFeature`](#geojson-asfeature) as the second. The default is to do
	 * nothing with the newly created layers:
	 * ```js
	 * function (feature, layer) {}
	 * ```
	 */
	onEachFeature?(feature: Feature<Geometry, any>, layer: Layer): void;
	/**
	 * A function that will be used to decide whether to include a feature or not. The default is to include all
	 * features:
	 * ```js
	 * function (geoJsonFeature) {
	 * 	return true;
	 * }
	 * ```
	 * Note: dynamically changing the `filter` option will have effect only on newly added data. It will _not_
	 * re-evaluate already included features.
	 */
	filter?(geoJsonFeature: Feature<Geometry, any>): boolean;
	/**
	 * A function that will be used for converting GeoJSON coordinates to `LatLng`s. The default is the
	 * `coordsToLatLng` static method.
	 */
	coordsToLatLng?(coords: Position): LatLng;
	/**
	 * Whether default Markers for "Point" type Features inherit from group options.
	 * @default false
	 */
	markersInheritOptions?: boolean;
}

export interface GridLayerDefaults extends GridLayerDefaultsValues {}
export interface GridLayerOptions extends LayerOptions, Partial<GridLayerDefaults> {}
export interface GridLayerEventMap extends LayerEventMap, GridLayerEvents {}

export interface TileLayerDefaults extends TileLayerDefaultsValues {}
export interface TileLayerOptions extends GridLayerOptions, Partial<Omit<TileLayerDefaults, keyof GridLayerOptions>> {
	/**
	 * The maximum zoom level up to which this layer will be displayed (inclusive).
	 * @default 18
	 */
	maxZoom?: number;
	[key: string]: unknown; // custom keys of the URL template
}
export interface TileLayerEventMap extends GridLayerEventMap, TileLayerEvents {}

/** The WMS request parameters, with any options that `WMSTileLayer` doesn't know. */
export interface WMSParams extends WMSParamsDefaults {
	[key: string]: unknown;
}
export interface WMSTileLayerDefaults extends WMSTileLayerDefaultsValues {}
export interface WMSTileLayerOptions extends TileLayerOptions, Partial<WMSTileLayerDefaults>,
	Partial<WMSParamsDefaults> {}

export interface MapDefaults extends MapDefaultsValues {}
export interface MapOptions extends Partial<MapDefaults> {
	/** @deprecated Use `pinchZoom`. */
	touchZoom?: boolean | 'center';
}
export interface MapEventMap extends MapLayerEvents, MapPopupEvents, MapTooltipEvents, MapStateEvents,
	MapLocationEvents, MapInteractionEvents, MapHandlerEvents, MapOtherEvents {}
/** Listeners of map events, as returned by [`getEvents`](#layer-getevents). */
export type MapListeners = {[K in keyof MapEventMap]?: Listener<K, MapEventMap, LeafletMap>};

/** The panes of a map by name: the default ones, which differ only in z-index, and those added with `createPane`. */
export interface MapPanes {
	/**
	 * Pane that contains all other map panes
	 * @default 'auto'
	 */
	mapPane: HTMLElement;
	/**
	 * Pane for `GridLayer`s and `TileLayer`s
	 * @default 200
	 */
	tilePane: HTMLElement;
	/**
	 * Pane for vectors (`Path`s, like `Polyline`s and `Polygon`s), `ImageOverlay`s and `VideoOverlay`s
	 * @default 400
	 */
	overlayPane: HTMLElement;
	/**
	 * Pane for overlay shadows (e.g. `Marker` shadows)
	 * @default 500
	 */
	shadowPane: HTMLElement;
	/**
	 * Pane for `Icon`s of `Marker`s
	 * @default 600
	 */
	markerPane: HTMLElement;
	/**
	 * Pane for `Tooltip`s
	 * @default 650
	 */
	tooltipPane: HTMLElement;
	/**
	 * Pane for `Popup`s
	 * @default 700
	 */
	popupPane: HTMLElement;
	[name: string]: HTMLElement;
}

/** Options for the `Map` methods that change the zoom level. */
export interface ZoomOptions extends ZoomProps {}
/** Options for the `Map` methods that change the center of the map. */
export interface PanOptions extends PanProps {}
/** Options for the `Map` methods that change both the center and the zoom level. */
export interface ZoomPanOptions extends ZoomOptions, PanOptions, ZoomPanProps {}
export interface InvalidateSizeOptions extends ZoomOptions, PanOptions, InvalidateSizeProps {}
export interface PaddingOptions extends PaddingProps {}
export interface PanInsideOptions extends PanOptions, PaddingOptions {}
export interface FitBoundsOptions extends ZoomPanOptions, PaddingOptions, FitBoundsProps {}
/** Options for `Map`'s geolocation methods. */
export interface LocateOptions extends LocateProps {}

export interface ControlDefaults extends ControlDefaultsValues {}
export interface ControlOptions extends Partial<ControlDefaults> {}
export interface ZoomControlDefaults extends Omit<ZoomControlDefaultsValues, keyof ControlOptions> {}
export interface ZoomControlOptions extends ControlOptions, Partial<ZoomControlDefaults> {}
export interface AttributionControlDefaults extends Omit<AttributionControlDefaultsValues, keyof ControlOptions> {}
export interface AttributionControlOptions extends ControlOptions, Partial<AttributionControlDefaults> {}
export interface ScaleControlDefaults extends Omit<ScaleControlDefaultsValues, keyof ControlOptions> {}
export interface ScaleControlOptions extends ControlOptions, Partial<ScaleControlDefaults> {}
export interface LayersControlDefaults extends Omit<LayersControlDefaultsValues, keyof ControlOptions> {}
export interface LayersControlOptions extends ControlOptions, Partial<LayersControlDefaults> {}

/**
 * Whenever a class inheriting from `Evented` fires an event, a listener function will be called with an event
 * argument, which is a plain object containing information about the event. For example:
 *
 * ```js
 * map.on('click', function(ev) {
 *     alert(ev.latlng); // ev is an event object (PointerEvent in this case)
 * });
 * ```
 *
 * The information available depends on the event type. This is the base event object: all other event objects
 * contain these properties too.
 */
export interface LeafletEvent extends LeafletEventProps {}
export interface LeafletKeyboardEvent extends LeafletEvent, LeafletKeyboardEventProps {}
export interface LeafletPointerEvent extends LeafletEvent, LeafletPointerEventProps {}
export interface LocationEvent extends LeafletEvent, LocationEventProps {}
export interface ErrorEvent extends LeafletEvent, ErrorEventProps {}
export interface LayerEvent extends LeafletEvent, LayerEventProps {}
export interface LayersControlEvent extends LayerEvent, LayersControlEventProps {}
export interface TileEvent extends LeafletEvent, TileEventProps {}
export interface TileErrorEvent extends TileEvent, TileErrorEventProps {}
export interface ResizeEvent extends LeafletEvent, ResizeEventProps {}
export interface GeoJSONEvent extends LeafletEvent, GeoJSONEventProps {}
export interface PopupEvent extends LeafletEvent, PopupEventProps {}
export interface TooltipEvent extends LeafletEvent, TooltipEventProps {}
export interface DragEndEvent extends LeafletEvent, DragEndEventProps {}
export interface BoxZoomEvent extends LeafletEvent, BoxZoomEventProps {}
export interface MarkerMoveEvent extends LeafletEvent, MarkerMoveEventProps {}
export interface ZoomAnimEvent extends LeafletEvent, ZoomAnimEventProps {}
export interface ViewPreResetEvent extends LeafletEvent, ViewPreResetEventProps {}
export interface WorldCopyJumpEvent extends LeafletEvent, WorldCopyJumpEventProps {}

// Members the classes can't declare in JS, added through `./Leaflet.js`, which plugins augment as `'leaflet'`:
// once a class is augmented through its own module, augmenting it through a re-export no longer merges. The one
// exception is `LayerBase`, which isn't exported, so plugins can't augment it either way.
declare module './layer/LayerBase.js' {
	interface LayerBase {
		_map: LeafletMap;
		_mapToAdd?: LeafletMap | null;

		/**
		 * Should contain code that creates DOM elements for the layer, adds them to `map panes` where they should
		 * belong and puts listeners on relevant map events. Called on [`map.addLayer(layer)`](#map-addlayer).
		 * @category Extension methods
		 * @uninheritable
		 */
		onAdd(map: LeafletMap): void;
		/**
		 * Should contain all clean up code that removes the layer's elements from the DOM and removes listeners
		 * previously added in [`onAdd`](#layer-onadd). Called on [`map.removeLayer(layer)`](#map-removelayer).
		 * @category Extension methods
		 * @uninheritable
		 */
		onRemove(map: LeafletMap): void;
		/**
		 * This optional method should return an object like `{ viewreset: this._reset }` for [`on`](#evented-on).
		 * The event handlers in this object will be automatically added and removed from the map with your layer.
		 * @category Extension methods
		 * @uninheritable
		 */
		getEvents?(): MapListeners;
		/**
		 * Optional method. Called on [`map.addLayer(layer)`](#map-addlayer), before the layer is added to the map,
		 * before events are initialized, without waiting until the map is in a usable state. Use for early
		 * initialization only.
		 * @category Extension methods
		 * @uninheritable
		 */
		beforeAdd?(map: LeafletMap): void;
	}
}

declare module './Leaflet.js' {
	interface Layer {
		// implemented by subclasses, checked by bound popups and tooltips
		_getPopupAnchor?(): PointExpression;
		_getTooltipAnchor?(): PointExpression;

		/**
		 * Optional method. Should return the layer's main element. A layer that has one gets keyboard access to its
		 * bound tooltip: the tooltip opens when the element is focused, and the element is described by it.
		 * @category Extension methods
		 * @uninheritable
		 */
		getElement?(): Element | null | undefined;
		/**
		 * Optional method. Should call `fn` on each of the layer's member layers. A layer without its own
		 * [`getElement`](#layer-getelement) that has it gives keyboard access to its bound tooltip through the
		 * elements of its members instead.
		 * @category Extension methods
		 * @uninheritable
		 */
		eachLayer?(fn: (layer: unknown) => void, context?: unknown): unknown;
		/**
		 * The GeoJSON feature the layer was created from, set by [`GeoJSON`](#geojson) on each layer it creates and
		 * used by [`toGeoJSON`](#geojson-togeojson) to keep its `properties`.
		 */
		feature?: Feature;
	}
}

declare module './Leaflet.js' {
	interface DivOverlay {
		// created by the subclass's `_initLayout`
		_container: HTMLElement;
		_contentNode: HTMLElement;
		_containerWidth: number;
		_containerHeight: number;
		_containerLeft: number;
		_containerBottom: number;
		_initLayout(): void;
		_updateLayout(): void;
		_adjustPan(): void;
		_animateZoom(e: ZoomAnimEvent): void;
	}
}

declare module './Leaflet.js' {
	interface GridLayer {
		_abortLoading?(): void; // implemented by `TileLayer`
	}
}

declare module './Leaflet.js' {
	interface Renderer {
		_layers: {[id: number]: Path}; // created lazily
		// implemented by `SVG` and `Canvas`, called by paths
		_initPath(layer: Path): void;
		_addPath(layer: Path): void;
		_removePath(layer: Path): void;
		_updatePath(layer: Path): void;
		_updateStyle(layer: Path): void;
		_bringToFront(layer: Path): void;
		_bringToBack(layer: Path): void;
		_updatePoly(layer: Polyline<PolylineOptions, InteractiveLayerEventMap, Geometry>, closed?: boolean): void;
		_updateCircle(layer: CircleMarker): void;
	}
}

declare module './Leaflet.js' {
	interface Canvas {
		_container: HTMLCanvasElement;
		_ctxScale: number;
	}
}

declare module './Leaflet.js' {
	interface Path {
		_path: SVGElement; // created by `SVG`
		_order?: DrawOrder; // created by `Canvas`
		_dashArray?: number[] | null; // `dashArray` parsed by `Canvas`
		_pxBounds?: Bounds;
		// implemented by subclasses
		_project(): void;
		_update(): void;
		_updatePath(): void;
		_updateBounds(): void;
		_containsPoint(p: Point): boolean;
	}
}

declare module './Leaflet.js' {
	interface CircleMarker {
		_pxRadiusY?: number; // set by `Circle`
	}
}

declare module './Leaflet.js' {
	interface Draggable {
		_absPos?: Point; // the unwrapped position, set by the map drag handler with `worldCopyJump`
	}
}

declare module './Leaflet.js' {
	interface Control<O extends ControlOptions = ControlOptions> {
		_map: LeafletMap;
		_container: HTMLElement;

		/**
		 * Should return the container DOM element for the control and add listeners
		 * on relevant map events. Called on [`control.addTo(map)`](#control-addto).
		 * @category Extension methods
		 * @uninheritable
		 */
		onAdd(map: LeafletMap): HTMLElement;
		/**
		 * Optional method. Should contain all clean up code that removes the listeners previously added in
		 * [`onAdd`](#control-onadd). Called on [`control.remove()`](#control-remove).
		 * @category Extension methods
		 * @uninheritable
		 */
		onRemove?(map: LeafletMap): void;
	}
}