import { BMapVersion, Capability, LayerKind, LoadKeyComponents, UnsupportedBehavior, Bounds, ControlHandle, LayerHandle, MapHandle, OverlayHandle, Pixel, Point, ServiceHandle, Size } from '../types';

/**
 * BMapDriver 接口 — 完整覆盖 bmap-jsapi-dts 中 Map 类的全部公共方法。
 *
 * 分类（按 dts src/core/Map.d.ts 顺序）：
 * 1. Map 工厂 / 销毁
 * 2. 交互开关（enable/disable 系列）
 * 3. 视角控制（heading / tilt / rotate）
 * 4. 缩放级别（zoom / minZoom / maxZoom）
 * 5. 自动 resize
 * 6. 显示配置（displayOptions / setOptions）
 * 7. 容器信息（size / container）
 * 8. 坐标转换（point/pixel/mercator）
 * 9. 地图状态查询
 * 10. 地图标注 / Spots / 区域
 * 11. 视野控制（center / zoom / pan / flyTo / viewport）
 * 12. 地图类型
 * 13. 控件 / 右键菜单
 * 14. 覆盖物
 * 15. 图层（addLayer / addNormalLayer / addGeoJSONLayer / addDistrictLayer / traffic / tileLayer）
 * 16. 信息窗口
 * 17. 样式 / 主题
 * 18. 视角动画
 * 19. 截图 / 版权
 * 20. 地球模式 / 室内 / 街景 / 语言 / 私有 / 焦点遮罩 / 自定义 HTML 图层 / 停车场等
 * 21. 3.0-only（setPanorama / addHotspot / setCurrentCity / highResolution 等）
 * 22. Overlay/Control/Layer/Service/ContextMenu/Panorama 工厂与操作
 * 23. 事件
 *
 * 关键约定（DESIGN.md §12）：
 * - 工厂方法：不支持时返回 null 或 isNull: true 的 ServiceHandle。
 * - 命令方法：签名 void，不支持时按 unsupportedBehavior（throw / warn+noop / ignore+noop）。
 * - Getter：签名与 dts 一致；不支持时按 behavior：throw / warn+NaN或合理兜底 / ignore。
 * - **绝不污染原返回类型为 T | undefined**。
 */
export interface BMapDriver {
    readonly version: BMapVersion;
    readonly rawSDK: unknown;
    readonly capabilities: ReadonlySet<Capability>;
    readonly unsupportedBehavior: UnsupportedBehavior;
    createMap(container: HTMLElement, options: unknown): MapHandle;
    destroyMap(handle: MapHandle): void;
    enableDragging(map: MapHandle): void;
    disableDragging(map: MapHandle): void;
    enableInertialDragging(map: MapHandle): void;
    disableInertialDragging(map: MapHandle): void;
    enableScrollWheelZoom(map: MapHandle): void;
    disableScrollWheelZoom(map: MapHandle): void;
    enableContinuousZoom(map: MapHandle): void;
    disableContinuousZoom(map: MapHandle): void;
    enableResizeOnCenter(map: MapHandle): void;
    disableResizeOnCenter(map: MapHandle): void;
    enableDoubleClickZoom(map: MapHandle): void;
    disableDoubleClickZoom(map: MapHandle): void;
    enableKeyboard(map: MapHandle): void;
    disableKeyboard(map: MapHandle): void;
    enablePinchToZoom(map: MapHandle): void;
    disablePinchToZoom(map: MapHandle): void;
    enableRotate(map: MapHandle): void;
    disableRotate(map: MapHandle): void;
    enableRotateGestures(map: MapHandle): void;
    disableRotateGestures(map: MapHandle): void;
    enableTilt(map: MapHandle): void;
    disableTilt(map: MapHandle): void;
    enableTiltGestures(map: MapHandle): void;
    disableTiltGestures(map: MapHandle): void;
    enableAutoResize(map: MapHandle): void;
    disableAutoResize(map: MapHandle): void;
    /** 开启点击底图标注后自动展示信息窗口，同时会开启底图标注点击（4.0+） */
    enableIconInfoWindow(map: MapHandle): void;
    disableIconInfoWindow(map: MapHandle): void;
    /** 启用首选语言，language 使用 BMAP_LANGUAGE_* 常量（4.0+） */
    enablePreferredLanguage(map: MapHandle, language?: string): void;
    disablePreferredLanguage(map: MapHandle): void;
    setHeading(map: MapHandle, heading: number, options?: unknown): void;
    getHeading(map: MapHandle): number;
    setTilt(map: MapHandle, tilt: number, options?: unknown): void;
    getTilt(map: MapHandle): number;
    getCurrentMaxTilt(map: MapHandle): number;
    setMinZoom(map: MapHandle, zoom: number): void;
    setMaxZoom(map: MapHandle, zoom: number): void;
    getMinZoom(map: MapHandle): number;
    getMaxZoom(map: MapHandle): number;
    checkResize(map: MapHandle): void;
    resize(map: MapHandle): void;
    setSize(map: MapHandle, size: {
        width: number;
        height: number;
    }): void;
    zoomTo(map: MapHandle, level: number, point?: unknown): void;
    setDisplayOptions(map: MapHandle, options: unknown): void;
    setOptions(map: MapHandle, options: unknown): void;
    getSize(map: MapHandle): Size;
    getContainerSize(map: MapHandle): Size;
    getZoomUnits(map: MapHandle): number;
    getContainer(map: MapHandle): HTMLElement;
    pixelToPoint(map: MapHandle, pixel: Pixel, options?: unknown): Point;
    pointToPixel(map: MapHandle, point: Point, options?: unknown): Pixel;
    lnglatToMercator(map: MapHandle, lng: number, lat: number): [number, number];
    mercatorToLnglat(map: MapHandle, mcLng: number, mcLat: number): [number, number];
    pointToOverlayPixel(map: MapHandle, point: Point, options?: unknown): Pixel;
    overlayPixelToPoint(map: MapHandle, pixel: Pixel, options?: unknown): Point;
    getDistance(map: MapHandle, start: Point, end: Point): number;
    isLoaded(map: MapHandle): boolean;
    getCoordType(map: MapHandle): string;
    getMapTypeId(map: MapHandle): string;
    getMapCoordType(map: MapHandle): string;
    getMapStyleId(map: MapHandle): string;
    getAreaStyleId(map: MapHandle): string;
    getRenderType(map: MapHandle): string;
    isCanvasMap(map: MapHandle): boolean;
    getProjection(map: MapHandle): unknown;
    getSolarInfo(map: MapHandle, date: Date): unknown;
    getTileId(map: MapHandle, point: Point, level: number): string;
    getPoiByUid(map: MapHandle, uid: string, callback: (poi: unknown) => void): void;
    getPanes(map: MapHandle): unknown;
    getInfoWindow(map: MapHandle): OverlayHandle | null;
    addSpots(map: MapHandle, spots: unknown[], options?: unknown): string;
    getSpots(map: MapHandle, id: string): unknown[];
    removeSpots(map: MapHandle, id: string): void;
    clearSpots(map: MapHandle): void;
    resetSpotStatus(map: MapHandle): void;
    hightlightSpotByUid(map: MapHandle, uid: string, tilePosStr: string): void;
    addAreaSpot(map: MapHandle, areaSpot: number[], options?: unknown): string;
    getAreaSpot(map: MapHandle, id: string): number[];
    removeAreaSpot(map: MapHandle, id: string): void;
    clearAreaSpots(map: MapHandle): void;
    clearLabels(map: MapHandle): void;
    addMapLabels(map: MapHandle, labels: unknown[]): string[];
    removeMapLabels(map: MapHandle, labelUids: string[]): void;
    getIconByClickPosition(map: MapHandle, clickPosition: Pixel): unknown | null;
    setBounds(map: MapHandle, bounds: Bounds): void;
    centerAndZoom(map: MapHandle, center: Point | string, zoom?: number, options?: unknown): void;
    panTo(map: MapHandle, center: Point, options?: unknown): void;
    panBy(map: MapHandle, x: number, y: number, options?: unknown): void;
    flyTo(map: MapHandle, center: Point, zoom: number, options?: unknown): void;
    reset(map: MapHandle): void;
    setCenter(map: MapHandle, center: Point | string, options?: unknown): void;
    getCenter(map: MapHandle): Point;
    setViewport(map: MapHandle, view: Point[] | Bounds, viewportOptions?: unknown): void;
    getViewport(map: MapHandle, view: Point[] | Bounds, viewportOptions?: unknown): unknown;
    setZoom(map: MapHandle, zoom: number, options?: unknown): void;
    getZoom(map: MapHandle): number;
    zoomIn(map: MapHandle, zoomCenter?: Point): void;
    zoomOut(map: MapHandle, zoomCenter?: Point): void;
    getBounds(map: MapHandle): Bounds;
    restrictBounds(map: MapHandle, bounds: Bounds | null): void;
    setMapType(map: MapHandle, mapTypeId: string | number): void;
    getMapType(map: MapHandle): string;
    addControl(map: MapHandle, control: ControlHandle): void;
    removeControl(map: MapHandle, control: ControlHandle): void;
    setControlOptions(control: ControlHandle, options: unknown): void;
    showControl(control: ControlHandle): void;
    hideControl(control: ControlHandle): void;
    addContextMenu(map: MapHandle | OverlayHandle, menu: OverlayHandle): void;
    removeContextMenu(map: MapHandle | OverlayHandle, menu: OverlayHandle): void;
    addOverlay(map: MapHandle, overlay: OverlayHandle): void;
    removeOverlay(map: MapHandle, overlay: OverlayHandle): void;
    clearOverlays(map: MapHandle): void;
    getOverlays(map: MapHandle): OverlayHandle[];
    /** 把 Label 挂到 Marker 上（marker.setLabel），随 marker 定位/拖拽跟随（4.0/GL 与 3.0 均支持） */
    setMarkerLabel(marker: OverlayHandle, label: OverlayHandle): void;
    /** 解除 Marker 上的 Label（SDK 无官方清除 API，兜底隐藏并清引用） */
    removeMarkerLabel(marker: OverlayHandle, label: OverlayHandle): void;
    addLayer(map: MapHandle, layer: LayerHandle): void;
    removeLayer(map: MapHandle, layer: LayerHandle): void;
    addTileLayer(map: MapHandle, layer: LayerHandle): void;
    removeTileLayer(map: MapHandle, layer: LayerHandle): void;
    getTileLayer(map: MapHandle, mapType: string): LayerHandle | null;
    addGeoJSONLayer(map: MapHandle, layer: LayerHandle): void;
    removeGeoJSONLayer(map: MapHandle, layer: LayerHandle): void;
    addDistrictLayer(map: MapHandle, layer: LayerHandle): void;
    removeDistrictLayer(map: MapHandle, layer: LayerHandle): void;
    addNormalLayer(map: MapHandle, layer: LayerHandle): void;
    removeNormalLayer(map: MapHandle, layer: LayerHandle): void;
    setTrafficOn(map: MapHandle): void;
    setTrafficOff(map: MapHandle): void;
    showOverlayContainer(map: MapHandle): void;
    hideOverlayContainer(map: MapHandle): void;
    openInfoWindow(map: MapHandle | OverlayHandle, iw: OverlayHandle, point?: Point): void;
    closeInfoWindow(map: MapHandle | OverlayHandle): void;
    openSimpleInfoWindow(map: MapHandle, iw: OverlayHandle, point: Point): void;
    closeSimpleInfoWindow(map: MapHandle): void;
    setMapStyle(map: MapHandle, config: unknown): void;
    setMapStyleV2(map: MapHandle, options: unknown): void;
    setTheme(map: MapHandle, theme: string, customVars?: Record<string, string>): void;
    setCopyrightOffset(map: MapHandle, logo: unknown, cpy: unknown): void;
    setDefaultCursor(map: MapHandle, cursor: string): void;
    getDefaultCursor(map: MapHandle): string;
    setDraggingCursor(map: MapHandle, cursor: string): void;
    getDraggingCursor(map: MapHandle): string;
    setOverlayMoveCursor(map: MapHandle, cursor: string): void;
    startViewAnimation(map: MapHandle, viewAnimation: unknown): number;
    pauseViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
    continueViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
    cancelViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
    getScreenshot(map: MapHandle): string;
    isSupportEarth(map: MapHandle): boolean;
    getEarth(map: MapHandle): unknown;
    showEarthBoundary(map: MapHandle): void;
    hideEarthBoundary(map: MapHandle): void;
    setEarthMaxZoom(map: MapHandle, zoom: number): void;
    setEarthMinZoom(map: MapHandle, zoom: number): void;
    showIndoor(map: MapHandle, uid: string, floor: number): void;
    setIndoor(map: MapHandle, uid: string, floor: number): void;
    getIndoorInfo(map: MapHandle): unknown | null;
    initIndoorLayer(map: MapHandle, opts?: unknown): unknown;
    setNormalMapDisplay(map: MapHandle, display: boolean): void;
    getVectorContainer(map: MapHandle): unknown;
    showStreetLayer(map: MapHandle, show: boolean): void;
    hideStreetLayer(map: MapHandle): void;
    isStreetLayerShow(map: MapHandle): boolean;
    showVectorStreetLayer(map: MapHandle): void;
    hideVectorStreetLayer(map: MapHandle): void;
    getLanguage(map: MapHandle): string;
    changeLanguage(map: MapHandle, language: string): void;
    enablePreferredLanguage(map: MapHandle, language: string): void;
    disablePreferredLanguage(map: MapHandle): void;
    setLock(map: MapHandle, lock: boolean): void;
    setPrivateRegions(map: MapHandle, regions: unknown[]): void;
    getPrivateRegions(map: MapHandle): unknown[];
    setPrivateStatus(map: MapHandle, isOn: boolean): void;
    getPrivateStatus(map: MapHandle): boolean;
    setCustomArea(map: MapHandle, config: unknown): void;
    addFocusMask(map: MapHandle, mask: unknown): void;
    removeFocusMask(map: MapHandle, mask: unknown): void;
    clearFocusMasks(map: MapHandle): void;
    addCustomHtmlLayer(map: MapHandle, layer: unknown): void;
    removeCustomHtmlLayer(map: MapHandle, layer: unknown): void;
    addParkingSpot(map: MapHandle, layer: unknown): void;
    removeParkingSpot(map: MapHandle, parking: unknown): void;
    enableMapClick(map: MapHandle): void;
    disableMapClick(map: MapHandle): void;
    enable3DBuilding(map: MapHandle): void;
    disable3DBuilding(map: MapHandle): void;
    setPanorama(map: MapHandle, pano: unknown): void;
    getPanorama(map: MapHandle): unknown;
    setCurrentCity(map: MapHandle, city: string): void;
    highResolutionEnabled(map: MapHandle): boolean;
    addHotspot(map: MapHandle, hotspot: OverlayHandle): void;
    removeHotspot(map: MapHandle, hotspot: OverlayHandle): void;
    clearHotspots(map: MapHandle): void;
    createMarker(position: Point, options?: unknown): OverlayHandle | null;
    createLabel(content: unknown, options?: unknown): OverlayHandle | null;
    createPolyline(path: Point[], options?: unknown): OverlayHandle | null;
    createPolygon(path: Point[] | Point[][], options?: unknown): OverlayHandle | null;
    createCircle(center: Point, radius: number, options?: unknown): OverlayHandle | null;
    createRectangle(bounds: Bounds, options?: unknown): OverlayHandle | null;
    /** controlPoints 为 SDK 必填位置参数：每两个路径点之间 1~2 个控制点，组数 = path.length - 1 */
    createBezierCurve(path: Point[], controlPoints: Point[][], options?: unknown): OverlayHandle | null;
    /**
     * altitude 为 SDK 必填位置参数（棱柱高度，米）。
     * path 支持单坐标串 Point[] 或多坐标串 Point[][]（后者仅 constructor 支持，setPath 只接受单串）。
     */
    createPrism(path: Point[] | Point[][], altitude: number, options?: unknown): OverlayHandle | null;
    createMarker3D(position: Point, height: number, options?: unknown): OverlayHandle | null;
    createGroundOverlay(bounds: Bounds, options?: unknown): OverlayHandle | null;
    createGroundPoint(point: Point, options?: unknown): OverlayHandle | null;
    createPointCollection(points: Point[], options?: unknown): OverlayHandle | null;
    createInfoWindow(content: unknown, options?: unknown): OverlayHandle | null;
    createSymbol(path: unknown, options?: unknown): OverlayHandle | null;
    createIcon(url: string, size: Size, options?: unknown): OverlayHandle | null;
    createIconSequence(symbol?: OverlayHandle, offset?: unknown, repeat?: string, fixedRotation?: boolean): OverlayHandle | null;
    createHotspot(position: Point, options?: unknown): OverlayHandle | null;
    createCustomOverlay(domCreate?: Function, options?: unknown): OverlayHandle | null;
    setOverlayPosition(overlay: OverlayHandle, position: Point): void;
    setOverlayPath(overlay: OverlayHandle, path: Point[] | Point[][]): void;
    setOverlayOptions(overlay: OverlayHandle, options: unknown): void;
    /**
     * 读取 overlay 当前 option 的原始值快照，用于 prop 从有值变回 undefined 时还原。
     * 只返回「SDK 提供 getter 且当前有值」的 key，其余 key 直接缺席——调用方据此判断哪些还原不了。
     * 返回的是 SDK 原始对象（raw Icon / raw Size 等），只应交给 restoreOverlayOptions 写回。
     */
    snapshotOverlayOptions(overlay: OverlayHandle, keys: string[]): Record<string, unknown>;
    /**
     * 把 snapshotOverlayOptions 取到的原始值写回 overlay。
     * 返回未能还原的 key（SDK 无对应 setter 或调用抛错），调用方据此告警。
     */
    restoreOverlayOptions(overlay: OverlayHandle, snapshot: Record<string, unknown>): string[];
    /** Overlay 基类 show() — 显示覆盖物 */
    showOverlay(overlay: OverlayHandle): void;
    /** Overlay 基类 hide() — 隐藏覆盖物 */
    hideOverlay(overlay: OverlayHandle): void;
    /** Marker.openPlaceDetail — 打开地点详情窗口（仅 v4+） */
    openPlaceDetail(marker: OverlayHandle, placeDetail: ServiceHandle): void;
    /** Marker.closePlaceDetail — 关闭地点详情窗口（仅 v4+） */
    closePlaceDetail(marker: OverlayHandle): void;
    createNavigationControl(options?: unknown): ControlHandle | null;
    createNavigationControl3D(options?: unknown): ControlHandle | null;
    createScaleControl(options?: unknown): ControlHandle | null;
    createOverviewMapControl(options?: unknown): ControlHandle | null;
    createMapTypeControl(options?: unknown): ControlHandle | null;
    createCopyrightControl(options?: unknown): ControlHandle | null;
    createGeolocationControl(options?: unknown): ControlHandle | null;
    createPanoramaControl(options?: unknown): ControlHandle | null;
    createZoomControl(options?: unknown): ControlHandle | null;
    createCityListControl(options?: unknown): ControlHandle | null;
    createLocationControl(options?: unknown): ControlHandle | null;
    createLogoControl(options?: unknown): ControlHandle | null;
    createControl(options?: unknown): ControlHandle | null;
    /** 自定义控件：domCreate 返回的 DOM 会被 initialize(map) 挂到地图容器上 */
    createCustomControl(domCreate: () => HTMLElement, options?: unknown): ControlHandle | null;
    createTileLayer(options?: unknown): LayerHandle | null;
    createNormalLayer(options?: unknown): LayerHandle | null;
    createGeoJSONLayer(options?: unknown): LayerHandle | null;
    createDistrictLayer(options?: unknown): LayerHandle | null;
    createTrafficLayer(options?: unknown): LayerHandle | null;
    createCustomLayer(options?: unknown): LayerHandle | null;
    createCanvasLayer(options?: unknown): LayerHandle | null;
    createRasterTileLayer(options?: unknown): LayerHandle | null;
    createWMSLayer(options?: unknown): LayerHandle | null;
    createWMTSLayer(options?: unknown): LayerHandle | null;
    createXYZLayer(options?: unknown): LayerHandle | null;
    createMVTLayer(options?: unknown): LayerHandle | null;
    createFeatureLayer(options?: unknown): LayerHandle | null;
    createFillLayer(options?: unknown): LayerHandle | null;
    createDOMLayer(options?: unknown): LayerHandle | null;
    createPointIconLayer(options?: unknown): LayerHandle | null;
    createPointShapeLayer(options?: unknown): LayerHandle | null;
    createPanoramaCoverageLayer(options?: unknown): LayerHandle | null;
    createLineLayer(options?: unknown): LayerHandle | null;
    createPixelLayer(options?: unknown): LayerHandle | null;
    createBaiduLayer(options?: unknown): LayerHandle | null;
    createThreeLayer(options?: unknown): LayerHandle | null;
    createContextMenu(options?: unknown): OverlayHandle | null;
    createMenuItem(text: string, callback: (point?: {
        lng: number;
        lat: number;
    }) => void, options?: unknown): OverlayHandle | null;
    addMenuItem(menu: OverlayHandle, item: OverlayHandle, insertIndex?: number): void;
    removeMenuItem(menu: OverlayHandle, item: OverlayHandle): void;
    createPanorama(container: HTMLElement, options?: unknown): MapHandle | null;
    createPanoramaLabel(options?: unknown): OverlayHandle | null;
    destroyPanorama(handle: MapHandle): void;
    createLocalSearch(location: unknown, options?: unknown): ServiceHandle;
    createGeocoder(): ServiceHandle;
    createDrivingRoute(options?: unknown): ServiceHandle;
    createWalkingRoute(options?: unknown): ServiceHandle;
    createRidingRoute(options?: unknown): ServiceHandle;
    createTransitRoute(options?: unknown): ServiceHandle;
    createBusLineSearch(options?: unknown): ServiceHandle;
    createAutocomplete(options?: unknown): ServiceHandle;
    createBoundary(): ServiceHandle;
    createGeolocation(options?: unknown): ServiceHandle;
    createLocalCity(options?: unknown): ServiceHandle;
    createPlaceDetail(options?: unknown): ServiceHandle;
    createConvertor(): ServiceHandle;
    createPanoramaService(): ServiceHandle;
    createTruckRoute(options?: unknown): ServiceHandle;
    searchService(service: ServiceHandle, query: unknown, callbacks: {
        onSuccess?: (data: unknown) => void;
        onError?: (err: Error) => void;
    }): () => void;
    getServiceResults(service: ServiceHandle): unknown;
    addEventListener(target: MapHandle | OverlayHandle | ControlHandle | LayerHandle, type: string, handler: (raw: unknown) => void): () => void;
    removeEventListener(target: MapHandle | OverlayHandle | ControlHandle | LayerHandle, type: string, handler: (raw: unknown) => void): void;
}
export type { LoadKeyComponents, LayerKind };