import { FeatureCollection } from 'geojson';
import { IControl } from 'maplibre-gl';
import { LayerSpecification } from 'maplibre-gl';
import { Map as Map_2 } from 'maplibre-gl';

/**
 * Builds the MapLibre layer specifications used to render a theme.
 *
 * Polygons produce a translucent fill plus an outline line layer; lines
 * produce a line layer; points produce a circle layer.
 *
 * @param theme - The Overture theme identifier
 * @param opacity - The theme opacity (0..1)
 * @param color - Optional color override (defaults to the theme x-ray color)
 * @returns Layer specifications ready for `map.addLayer`
 */
export declare function buildLayerSpecs(theme: OvertureTheme, opacity: number, color?: string): LayerSpecification[];

/**
 * Builds the MapLibre layer specifications for a single source layer of a
 * theme. Use this to render and restyle layers independently.
 *
 * @param theme - The Overture theme identifier
 * @param sourceLayer - The source-layer name (e.g. `water`)
 * @param opacity - The layer opacity (0..1)
 * @param color - Optional color override (defaults to the theme x-ray color)
 * @param size - Optional size override (circle radius / line width); defaults
 *   to the geometry's default size
 * @returns Layer specifications ready for `map.addLayer`
 */
export declare function buildSourceLayerSpecs(theme: OvertureTheme, sourceLayer: string, opacity: number, color?: string, size?: number): LayerSpecification[];

/**
 * Clamps a value between a minimum and maximum.
 *
 * @param value - The value to clamp
 * @param min - The minimum allowed value
 * @param max - The maximum allowed value
 * @returns The clamped value
 *
 * @example
 * ```typescript
 * clamp(5, 0, 10);  // returns 5
 * clamp(-5, 0, 10); // returns 0
 * clamp(15, 0, 10); // returns 10
 * ```
 */
export declare function clamp(value: number, min: number, max: number): number;

/**
 * Creates a CSS class string from an object of class names.
 *
 * @param classes - Object with class names as keys and boolean values
 * @returns A space-separated string of class names
 *
 * @example
 * ```typescript
 * classNames({ active: true, disabled: false, visible: true });
 * // returns "active visible"
 * ```
 */
export declare function classNames(classes: Record<string, boolean>): string;

/**
 * Returns the color paint property name for a layer type.
 *
 * @param layerType - The MapLibre layer type
 * @returns The matching paint property, e.g. `fill-color`
 */
export declare function colorPropertyForLayerType(layerType: "fill" | "line" | "circle"): "fill-color" | "line-color" | "circle-color";

/**
 * UI color scheme for the control.
 *
 * - `'light'` forces light colors
 * - `'dark'` forces dark colors
 * - `'auto'` follows the browser's `prefers-color-scheme`
 */
export declare type ControlColorScheme = "light" | "dark" | "auto";

/**
 * Debounces a function call.
 *
 * @param fn - The function to debounce
 * @param delay - The delay in milliseconds
 * @returns A debounced version of the function
 *
 * @example
 * ```typescript
 * const debouncedUpdate = debounce(() => updateMap(), 100);
 * window.addEventListener('resize', debouncedUpdate);
 * ```
 */
export declare function debounce<T extends (...args: unknown[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;

/**
 * Legacy endpoint listing available Overture Maps releases.
 *
 * @deprecated Overture froze this file at `2026-07-22.0` and no longer updates
 * it, and the tiles for the release it names have since been removed from the
 * distribution bucket — so following it leaves every theme URL a 404 (issue
 * #12). It is still honoured when passed explicitly as `releasesUrl`, for a
 * self-hosted mirror that keeps the same shape, but it is no longer consulted
 * by default. See {@link resolveReleases}.
 */
export declare const DEFAULT_RELEASES_URL = "https://labs.overturemaps.org/data/releases.json";

/**
 * Overture's STAC catalog, the documented replacement for the frozen
 * releases.json. Its root names the latest release but not the older ones.
 */
export declare const DEFAULT_STAC_CATALOG_URL = "https://stac.overturemaps.org/catalog.json";

/**
 * Default base URL for the Overture Maps PMTiles distribution.
 */
export declare const DEFAULT_TILES_BASE_URL = "https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles";

/**
 * Returns the default size (circle radius or line width) for a geometry.
 *
 * @param geometry - The source-layer geometry
 * @returns The default size in pixels
 */
export declare function defaultSizeForGeometry(geometry: OvertureGeometry): number;

/**
 * Registers the `pmtiles://` protocol with MapLibre GL once.
 *
 * Safe to call multiple times; subsequent calls are no-ops. Note that this
 * cannot detect a `pmtiles` protocol registered by the host application
 * before the plugin loads, in which case the existing handler is replaced.
 */
export declare function ensurePmtilesProtocol(): void;

/**
 * Release used when no release source can be reached.
 */
export declare const FALLBACK_RELEASE = "2026-08-19.0";

/**
 * Fetches and validates a releases.json document.
 *
 * @param url - The releases endpoint (defaults to the frozen Overture labs URL)
 * @returns The parsed releases document
 * @throws Error if the request fails or the payload is malformed
 * @see resolveReleases for the release source the control uses by default
 */
export declare function fetchReleases(url?: string): Promise<ReleasesResponse>;

/**
 * Reads the latest release from Overture's STAC catalog.
 *
 * The catalog root carries only the current release, so this returns a
 * single-entry list — enough to render, not enough to populate a history.
 *
 * @param catalogUrl - The STAC catalog root (defaults to Overture's)
 * @returns The latest release as a one-entry {@link ReleasesResponse}
 * @throws Error if the request fails or the catalog names no release
 */
export declare function fetchStacLatest(catalogUrl?: string): Promise<ReleasesResponse>;

/**
 * Formats a numeric value with appropriate decimal places based on step size.
 *
 * @param value - The value to format
 * @param step - The step size to determine decimal places
 * @returns The formatted value as a string
 *
 * @example
 * ```typescript
 * formatNumericValue(5, 1);     // returns "5"
 * formatNumericValue(0.5, 0.1); // returns "0.5"
 * formatNumericValue(0.55, 0.01); // returns "0.55"
 * ```
 */
export declare function formatNumericValue(value: number, step: number): string;

/**
 * Generates a unique ID string.
 *
 * @param prefix - Optional prefix for the ID
 * @returns A unique ID string
 *
 * @example
 * ```typescript
 * generateId('control'); // returns "control-abc123"
 * generateId();          // returns "abc123"
 * ```
 */
export declare function generateId(prefix?: string): string;

/**
 * Returns the MapLibre layer ids used to render a single source layer.
 *
 * @param theme - The Overture theme identifier
 * @param sourceLayer - The source-layer name
 * @returns Layer ids in the order they are added to the map
 */
export declare function layerIdsForSourceLayer(theme: OvertureTheme, sourceLayer: string): string[];

/**
 * Returns all MapLibre layer ids used to render a theme.
 *
 * @param theme - The Overture theme identifier
 * @returns Layer ids in the order they are added to the map
 */
export declare function layerIdsForTheme(theme: OvertureTheme): string[];

/**
 * Lists the releases present in the PMTiles distribution bucket.
 *
 * The bucket is a public S3 bucket, so its ListObjectsV2 endpoint answers
 * unauthenticated cross-origin GETs. Asking for the release prefixes with a
 * delimiter returns one `CommonPrefixes` entry per release directory.
 *
 * @param tilesBaseUrl - Base URL of the distribution (defaults to Overture's)
 * @returns The releases found, newest first
 * @throws Error if the request fails or the bucket holds no release
 */
export declare function listTileReleases(tilesBaseUrl?: string): Promise<ReleasesResponse>;

/**
 * Returns the opacity paint property name for a layer type.
 *
 * @param layerType - The MapLibre layer type
 * @returns The matching paint property, e.g. `fill-opacity`
 */
export declare function opacityPropertyForLayerType(layerType: "fill" | "line" | "circle"): "fill-opacity" | "line-opacity" | "circle-opacity";

/**
 * Geometry rendered for a source layer within a theme tileset.
 */
export declare type OvertureGeometry = "point" | "line" | "polygon";

/**
 * A source layer contained in an Overture theme PMTiles archive.
 */
export declare interface OvertureLayerDef {
    /** The MVT source-layer name (matches the Overture feature type) */
    sourceLayer: string;
    /** The geometry type used to render the layer */
    geometry: OvertureGeometry;
}

/**
 * Styling and visibility of a single source layer within a theme.
 */
export declare interface OvertureLayerState {
    /** Whether the layer is on the map */
    visible: boolean;
    /** Layer opacity (0..1) */
    opacity: number;
    /** Layer color (hex) */
    color: string;
    /** Layer size: circle radius for points, line width for lines and outlines */
    size: number;
}

/**
 * A MapLibre GL control for visualizing Overture Maps PMTiles themes.
 *
 * Adds a collapsible panel with a release selector and per-theme visibility
 * and opacity controls. Tiles are loaded from the official Overture Maps
 * PMTiles distribution using the `pmtiles://` protocol.
 *
 * @example
 * ```typescript
 * const control = new OvertureMapsControl({
 *   collapsed: false,
 *   visibleThemes: ['buildings', 'places'],
 * });
 * map.addControl(control, 'top-right');
 * ```
 */
export declare class OvertureMapsControl implements IControl {
    private _map?;
    private _mapContainer?;
    private _container?;
    private _panel?;
    private _options;
    private _state;
    private _eventHandlers;
    private _popup?;
    private _releaseSelect?;
    private _errorEl?;
    private _noticeEl?;
    private _noticeTimer;
    private _inspectCheckbox?;
    private _hintEl?;
    private _schemeMedia;
    private _schemeListener;
    private _resizeHandler;
    private _mapResizeHandler;
    private _clickOutsideHandler;
    private _suppressClickOutside;
    private _resizePointerMove;
    private _resizePointerUp;
    private _clickHandler;
    private _moveHandler;
    private _styleLoadHandler;
    private _zoomHandler;
    /**
     * Creates a new OvertureMapsControl instance.
     *
     * @param options - Configuration options for the control
     */
    constructor(options?: Partial<OvertureMapsControlOptions>);
    /**
     * Called when the control is added to the map.
     * Implements the IControl interface.
     *
     * @param map - The MapLibre GL map instance
     * @returns The control's container element
     */
    onAdd(map: Map_2): HTMLElement;
    /**
     * Called when the control is removed from the map.
     * Implements the IControl interface.
     */
    onRemove(): void;
    /**
     * Gets the current state of the control.
     *
     * @returns The current control state
     */
    getState(): OvertureMapsState;
    /**
     * Updates the control state.
     *
     * @param newState - Partial state to merge with current state
     */
    setState(newState: Partial<OvertureMapsState>): void;
    /**
     * Toggles the collapsed state of the control panel.
     */
    toggle(): void;
    /**
     * Expands the control panel.
     */
    expand(): void;
    /**
     * Collapses the control panel.
     */
    collapse(): void;
    /**
     * Registers an event handler.
     *
     * @param event - The event type to listen for
     * @param handler - The callback function
     */
    on(event: OvertureMapsEvent, handler: OvertureMapsEventHandler): void;
    /**
     * Removes an event handler.
     *
     * @param event - The event type
     * @param handler - The callback function to remove
     */
    off(event: OvertureMapsEvent, handler: OvertureMapsEventHandler): void;
    /**
     * Gets the map instance.
     *
     * @returns The MapLibre GL map instance or undefined if not added to a map
     */
    getMap(): Map_2 | undefined;
    /**
     * Gets the control container element.
     *
     * @returns The container element or undefined if not added to a map
     */
    getContainer(): HTMLElement | undefined;
    /**
     * Switches the active Overture release and reloads visible themes.
     *
     * @param release - The release to activate, e.g. `'2026-05-20.0'`
     */
    setRelease(release: string): void;
    /**
     * Shows or hides every source layer of an Overture theme.
     *
     * @param theme - The theme to update
     * @param visible - Whether the theme's layers should be rendered
     */
    setThemeVisible(theme: OvertureTheme, visible: boolean): void;
    /**
     * Sets the opacity of every source layer of an Overture theme.
     *
     * @param theme - The theme to update
     * @param opacity - Opacity value between 0 and 1
     */
    setThemeOpacity(theme: OvertureTheme, opacity: number): void;
    /**
     * Shows or hides a single source layer of a theme.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @param visible - Whether the layer should be rendered
     */
    setLayerVisible(theme: OvertureTheme, sourceLayer: string, visible: boolean): void;
    /**
     * Sets the opacity of a single source layer.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @param opacity - Opacity value between 0 and 1
     */
    setLayerOpacity(theme: OvertureTheme, sourceLayer: string, opacity: number): void;
    /**
     * Sets the color of a single source layer.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @param color - A CSS color string (hex)
     */
    setLayerColor(theme: OvertureTheme, sourceLayer: string, color: string): void;
    /**
     * Sets the size of a single source layer (circle radius for points, line
     * width for lines and polygon outlines).
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @param size - The size in pixels
     */
    setLayerSize(theme: OvertureTheme, sourceLayer: string, size: number): void;
    /**
     * Expands or collapses a theme's layer list in the panel.
     *
     * @param theme - The theme to update
     * @param expanded - Whether the layer list should be shown
     */
    setThemeExpanded(theme: OvertureTheme, expanded: boolean): void;
    /**
     * Enables or disables the feature inspection picker.
     *
     * @param enabled - Whether clicking a feature opens a properties popup
     */
    setInspect(enabled: boolean): void;
    /**
     * Collects the features of a layer rendered in the current map view as a
     * GeoJSON FeatureCollection.
     *
     * Only features painted in the current viewport are returned, deduplicated
     * across tile boundaries. Combine with a high zoom level to keep the
     * result limited to a small area.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @returns A GeoJSON FeatureCollection (possibly empty)
     */
    getRenderedLayerGeoJSON(theme: OvertureTheme, sourceLayer: string): FeatureCollection;
    /**
     * Exports a layer's features in the current view to a downloaded GeoJSON
     * file. The export is gated by `exportMinZoom` so it only ever covers a
     * small area.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @returns The exported FeatureCollection, or null when nothing was exported
     */
    exportLayer(theme: OvertureTheme, sourceLayer: string): FeatureCollection | null;
    /**
     * Triggers a browser download of a GeoJSON object.
     *
     * @param filename - The download file name
     * @param data - The GeoJSON object to serialize
     */
    private _downloadGeoJSON;
    /**
     * Shows a transient notice message in the panel.
     *
     * @param message - The message to display
     */
    private _notify;
    /**
     * Re-fetches the list of available Overture releases.
     *
     * @returns The available releases, newest first
     */
    refreshReleases(): Promise<string[]>;
    /**
     * Emits an event to all registered handlers.
     *
     * @param event - The event type to emit
     */
    private _emit;
    /**
     * Returns a deep copy of the per-theme state.
     */
    private _cloneThemes;
    /**
     * Fetches the release list, falling back gracefully when unavailable,
     * then renders the visible themes.
     */
    private _initializeReleases;
    /**
     * Records an error message and emits an `error` event when set.
     *
     * @param message - The error message, or null to clear
     */
    private _setError;
    /**
     * Rebuilds the sources and layers for all visible layers using the
     * active release.
     */
    private _applyRelease;
    /**
     * Ensures a theme's vector source exists on the map.
     *
     * @param theme - The theme whose source to add
     */
    private _ensureSource;
    /**
     * Adds the layers for a single source layer to the map.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     */
    private _addLayer;
    /**
     * The canonical back-to-front order of every Overture layer id.
     *
     * Themes are drawn back to front in reverse of {@link THEME_IDS}, so the
     * first panel theme (e.g. addresses) ends up on top of the map.
     *
     * @returns Layer ids from bottom-most to top-most
     */
    private _orderedLayerIds;
    /**
     * Finds the layer a new layer should be inserted before to preserve the
     * canonical draw order.
     *
     * @param layerId - The id of the layer being added
     * @returns The id of the next existing layer above it, or undefined to
     *   append on top
     */
    private _beforeIdFor;
    /**
     * Removes the layers for a single source layer, dropping the theme source
     * once none of its layers remain on the map.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     */
    private _removeLayer;
    /**
     * Removes the layers and source for a theme from the map.
     *
     * @param theme - The theme to remove
     */
    private _removeTheme;
    /**
     * Removes all Overture layers and sources from the map.
     */
    private _removeAllThemes;
    /**
     * Returns the ids of all Overture layers currently on the map.
     */
    private _renderedLayerIds;
    /**
     * Wires click and hover handlers for feature inspection.
     */
    private _setupInspect;
    /**
     * Builds the inspection popup: the host's `createPopup` factory when one is
     * configured (a map engine with its own popup class), else MapLibre's.
     *
     * @returns An unattached popup
     */
    private _createPopup;
    /**
     * Removes the feature inspection handlers and any open popup.
     */
    private _teardownInspect;
    /**
     * Sanitizes a feature-sourced value for display in the popup.
     *
     * Strips control characters and truncates long values so malformed
     * tile properties cannot break the UI.
     *
     * @param value - The raw property key or value
     * @param maxLength - Maximum displayed length
     * @returns A safe display string
     */
    private _sanitizeDisplayString;
    /**
     * Builds the popup DOM showing a feature's properties.
     *
     * @param sourceLayer - The feature's source layer name
     * @param properties - The feature properties
     * @returns The popup content element
     */
    private _buildPopupContent;
    /**
     * Returns whether the system currently prefers a dark color scheme.
     */
    private _prefersDark;
    /**
     * Resolves the active color scheme. In `auto` mode this follows the
     * system `prefers-color-scheme`.
     *
     * @returns The resolved scheme
     */
    private _resolvedScheme;
    /**
     * Returns the color-scheme class suffix for the resolved scheme.
     */
    private _schemeClass;
    /**
     * Applies the resolved color-scheme class to the container and panel.
     * Called on creation and whenever the system theme changes in `auto` mode.
     */
    private _applyScheme;
    /**
     * Subscribes to system color-scheme changes so the control adapts live
     * when `theme` is `auto`.
     */
    private _setupSchemeListener;
    /**
     * Creates the main container element for the control.
     * Contains a toggle button (29x29) matching navigation control size.
     *
     * @returns The container element
     */
    private _createContainer;
    /**
     * Creates the panel element with header and content areas.
     * Panel is positioned as a dropdown below the toggle button.
     *
     * @returns The panel element
     */
    private _createPanel;
    /**
     * The lowest zoom at which both detail themes (addresses and places) render.
     *
     * Derived from the theme definitions so the hint stays in sync with the
     * tileset minzoom rather than hardcoding the value in the message.
     *
     * @returns The detail-theme minimum zoom (defaults to 14)
     */
    private get _detailMinZoom();
    /**
     * Updates the zoom hint to reflect the live map zoom.
     *
     * Below the detail-theme threshold the hint reads as a heads-up that
     * addresses and places only appear once zoomed in. At or above the threshold
     * it switches to a positive confirmation (with the `--active` modifier for a
     * success style) so a satisfied warning does not linger as stale guidance.
     */
    private _updateHint;
    /**
     * Creates the feature inspection toggle row.
     *
     * @returns The inspect row element
     */
    private _createInspectRow;
    /**
     * Creates the panel drag handle used to resize the panel width.
     *
     * @returns The resize handle element
     */
    private _createResizeHandle;
    /**
     * Creates the release selector row.
     *
     * @returns The release row element
     */
    private _createReleaseRow;
    /**
     * Re-populates the release selector options from state.
     */
    private _renderReleaseOptions;
    /**
     * Creates a collapsible panel group for one theme: a header with a master
     * checkbox and an expand toggle, plus a row per source layer.
     *
     * @param theme - The theme to render
     * @returns The theme group element
     */
    private _createThemeGroup;
    /**
     * Creates a panel row for one source layer: a checkbox, color swatch,
     * label, and a style button that reveals an inline editor for color,
     * size, and opacity.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @returns The layer row element
     */
    private _createLayerRow;
    /**
     * Creates the inline style editor for a layer (color, size, opacity).
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     * @returns The editor element
     */
    private _createLayerEditor;
    /**
     * Turns a source-layer name into a human-readable label.
     *
     * @param sourceLayer - The source-layer name (e.g. `land_cover`)
     * @returns A display label (e.g. `Land cover`)
     */
    private _humanizeLayer;
    /**
     * Applies expanded state and master-checkbox state to a theme group.
     *
     * @param group - The theme group element
     * @param theme - The theme the group represents
     */
    private _applyThemeGroupState;
    /**
     * Syncs a theme group's header and every layer row with the current state.
     *
     * @param theme - The theme to update
     */
    private _syncThemeGroup;
    /**
     * Syncs a single layer row's inputs with the current state.
     *
     * @param theme - The theme the layer belongs to
     * @param sourceLayer - The source-layer name
     */
    private _syncLayerRow;
    /**
     * Starts a panel-width drag-resize from the handle.
     *
     * @param event - The initiating pointer event
     */
    private _startResize;
    /**
     * Setup event listeners for panel positioning and click-outside behavior.
     */
    private _setupEventListeners;
    /**
     * Detect which corner the control is positioned in.
     *
     * @returns The position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
     */
    private _getControlPosition;
    /**
     * Update the panel position based on button location and control corner.
     * Positions the panel next to the button, expanding in the appropriate direction.
     */
    private _updatePanelPosition;
}

/**
 * Options for configuring the OvertureMapsControl
 */
export declare interface OvertureMapsControlOptions {
    /**
     * Whether the control panel should start collapsed (showing only the toggle button)
     * @default true
     */
    collapsed?: boolean;
    /**
     * Position of the control on the map
     * @default 'top-right'
     */
    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
    /**
     * Title displayed in the control header
     * @default 'Overture Maps'
     */
    title?: string;
    /**
     * Width of the control panel in pixels
     * @default 300
     */
    panelWidth?: number;
    /**
     * Custom CSS class name for the control container
     */
    className?: string;
    /**
     * UI color scheme for the control
     * @default 'auto'
     */
    theme?: ControlColorScheme;
    /**
     * Pin a specific Overture release (e.g. `'2026-08-19.0'`).
     * When omitted, the newest release carried by {@link tilesBaseUrl} is used.
     */
    release?: string;
    /**
     * Endpoint listing available Overture releases, in releases.json shape.
     *
     * Unset by default: Overture froze the releases.json it published at a
     * release whose tiles have since been removed, so releases are discovered
     * from {@link tilesBaseUrl} instead. Set this to point at a mirror that
     * still publishes that document.
     */
    releasesUrl?: string;
    /**
     * Base URL of the Overture PMTiles distribution (no trailing slash)
     * @default 'https://overturemaps-extras-us-west-2.s3.us-west-2.amazonaws.com/tiles'
     */
    tilesBaseUrl?: string;
    /**
     * Whether clicking a rendered Overture feature opens a properties popup
     * @default true
     */
    inspect?: boolean;
    /**
     * Minimum map zoom required to export a layer to GeoJSON. This keeps
     * exports limited to a small area.
     * @default 12
     */
    exportMinZoom?: number;
    /**
     * Themes that start visible
     * @default ['buildings', 'transportation', 'places']
     */
    visibleThemes?: OvertureTheme[];
    /**
     * Per-theme color overrides (hex colors)
     */
    themeColors?: Partial<Record<OvertureTheme, string>>;
    /**
     * Per-theme initial opacity overrides (0..1)
     * @default 0.8 for every theme
     */
    themeOpacity?: Partial<Record<OvertureTheme, number>>;
    /**
     * Custom handler for exporting a layer to GeoJSON. When provided, it is
     * called instead of the built-in browser download, letting a host
     * application save the file its own way (e.g. a native save dialog in a
     * desktop webview where anchor downloads do not work).
     *
     * @param filename - The suggested file name (e.g. `overture-buildings-building.geojson`)
     * @param data - The exported FeatureCollection
     */
    onExport?: (filename: string, data: FeatureCollection) => void;
    /**
     * Whether the host map reads `.pmtiles` archives natively from a plain
     * `https://` URL, so the control emits the archive URL as-is and skips
     * registering MapLibre's `pmtiles://` protocol. Set it when the control is
     * mounted on an engine with a built-in PMTiles tile provider, such as
     * Mapbox GL JS 3.30+, where `maplibregl.addProtocol` has no effect.
     * @default false
     */
    nativePmtiles?: boolean;
    /**
     * Factory for the feature-inspection popup. When provided, it is called
     * instead of constructing MapLibre's `Popup`, letting a host mount the
     * control on a map engine that ships its own popup class (for example
     * mapbox-gl's `Popup`, which shares the same fluent surface).
     *
     * @param options - The popup options the control would pass to MapLibre
     * @returns A popup exposing `setLngLat`, `setDOMContent`, `addTo` and `remove`
     */
    createPopup?: (options: OverturePopupOptions) => OverturePopup;
}

/**
 * Event types emitted by the Overture Maps control
 */
export declare type OvertureMapsEvent = "collapse" | "expand" | "statechange" | "releasechange" | "themechange" | "error";

/**
 * Event handler function type
 */
export declare type OvertureMapsEventHandler = (event: {
    type: OvertureMapsEvent;
    state: OvertureMapsState;
}) => void;

/**
 * Internal state of the Overture Maps control
 */
export declare interface OvertureMapsState {
    /**
     * Whether the control panel is currently collapsed
     */
    collapsed: boolean;
    /**
     * Current panel width in pixels
     */
    panelWidth: number;
    /**
     * The active Overture release
     */
    release: string;
    /**
     * Available Overture releases (newest first)
     */
    releases: string[];
    /**
     * Per-theme visibility and opacity
     */
    themes: Record<OvertureTheme, OvertureThemeState>;
    /**
     * Whether the feature inspection picker is enabled
     */
    inspect: boolean;
    /**
     * Last error message, or null when healthy
     */
    error?: string | null;
}

/**
 * The popup surface the control drives: the fluent members shared by
 * MapLibre's and mapbox-gl's `Popup` classes.
 */
export declare interface OverturePopup {
    /** Positions the popup at a geographic location */
    setLngLat(lngLat: {
        lng: number;
        lat: number;
    } | [number, number]): this;
    /** Replaces the popup body with a DOM node */
    setDOMContent(node: Node): this;
    /** Attaches the popup to the map the control is mounted on */
    addTo(map: unknown): this;
    /** Detaches the popup from the map */
    remove(): this;
}

/**
 * Options the control hands to {@link OvertureMapsControlOptions.createPopup}.
 * A subset of MapLibre's `PopupOptions` that mapbox-gl's `Popup` accepts too.
 */
export declare interface OverturePopupOptions {
    /** CSS max-width of the popup, e.g. `'320px'` */
    maxWidth?: string;
    /** Extra class name(s) added to the popup container */
    className?: string;
}

/**
 * The Overture Maps data themes distributed as PMTiles archives.
 *
 * @see https://docs.overturemaps.org/examples/overture-tiles/
 */
export declare type OvertureTheme = "addresses" | "base" | "buildings" | "divisions" | "places" | "transportation";

/**
 * State of a single Overture theme and its source layers.
 */
export declare interface OvertureThemeState {
    /** Whether the theme's layer list is expanded in the panel */
    expanded: boolean;
    /** Per-source-layer styling and visibility, keyed by source-layer name */
    layers: Record<string, OvertureLayerState>;
}

/**
 * Shape of the releases.json document.
 */
export declare interface ReleasesResponse {
    /** The latest available release, e.g. `2026-08-19.0` */
    latest: string;
    /** All available releases, newest first */
    releases: string[];
}

/**
 * Resolves the releases the plugin can actually render.
 *
 * The distribution bucket is the authority: a release is usable only if its
 * PMTiles are still there, and Overture prunes older ones. So the default path
 * lists the bucket, falls back to the STAC catalog's `latest` when the listing
 * is unavailable, and only reads a releases.json when the caller names one.
 *
 * @param options - Sources to consult; see {@link ResolveReleasesOptions}
 * @returns The usable releases, newest first
 * @throws Error if every source consulted fails
 */
export declare function resolveReleases(options?: ResolveReleasesOptions): Promise<ReleasesResponse>;

/**
 * Sources {@link resolveReleases} may consult.
 */
export declare interface ResolveReleasesOptions {
    /**
     * A releases.json endpoint. When set, it is the only source consulted — this
     * is the escape hatch for a self-hosted mirror.
     */
    releasesUrl?: string;
    /** Base URL of the PMTiles distribution to list (defaults to Overture's) */
    tilesBaseUrl?: string;
    /** STAC catalog consulted when the distribution cannot be listed */
    stacCatalogUrl?: string;
}

/**
 * Returns the size paint property name for a layer type.
 *
 * Fill layers have no size dimension and return null.
 *
 * @param layerType - The MapLibre layer type
 * @returns The matching paint property, or null for fills
 */
export declare function sizePropertyForLayerType(layerType: "fill" | "line" | "circle"): "circle-radius" | "line-width" | null;

/**
 * Returns the map source id used for a theme.
 *
 * @param theme - The Overture theme identifier
 * @returns The MapLibre source id, e.g. `overture-buildings`
 */
export declare function sourceIdForTheme(theme: OvertureTheme): string;

/**
 * Ordered list of all Overture theme identifiers.
 *
 * This is the panel display order (top to bottom). The control draws the
 * first theme on top of the map and the last theme at the bottom, so the
 * detail themes (addresses, places) sit above the background (base).
 */
export declare const THEME_IDS: OvertureTheme[];

/**
 * Metadata describing an Overture theme tileset.
 */
export declare interface ThemeDefinition {
    /** Theme identifier (also the PMTiles file name) */
    id: OvertureTheme;
    /** Human-readable label shown in the control panel */
    label: string;
    /** Default x-ray color for the theme */
    color: string;
    /** Source layers contained in the theme tileset */
    layers: OvertureLayerDef[];
    /** Minimum zoom at which features appear (informational) */
    minzoom?: number;
}

/**
 * All Overture themes with their source layers and default x-ray colors.
 *
 * Source layers verified against the OvertureMaps/overture-tiles
 * planetiler profiles.
 */
export declare const THEMES: Record<OvertureTheme, ThemeDefinition>;

/**
 * Throttles a function call.
 *
 * @param fn - The function to throttle
 * @param limit - The minimum time between calls in milliseconds
 * @returns A throttled version of the function
 *
 * @example
 * ```typescript
 * const throttledScroll = throttle(() => handleScroll(), 100);
 * window.addEventListener('scroll', throttledScroll);
 * ```
 */
export declare function throttle<T extends (...args: unknown[]) => void>(fn: T, limit: number): (...args: Parameters<T>) => void;

/**
 * Returns the PMTiles URL for a theme at a given release.
 *
 * @param baseUrl - Base tiles URL (no trailing slash)
 * @param release - Overture release, e.g. `2026-05-20.0`
 * @param theme - The Overture theme identifier
 * @param nativePmtiles - When true, return the plain archive URL for a map
 *   engine that reads `.pmtiles` natively (see
 *   {@link OvertureMapsControlOptions.nativePmtiles}); otherwise prefix it
 *   with MapLibre's `pmtiles://` protocol
 * @returns The `pmtiles://`-prefixed source URL, or the plain archive URL
 */
export declare function tileUrlForTheme(baseUrl: string, release: string, theme: OvertureTheme, nativePmtiles?: boolean): string;

export { }