mahal_map 1.7.3 → 2.0.0

package/dist/index.d.mts

@@ -19,21 +19,97 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+/**
+ * Поверхность @grammaps/maps3d-web, описанная локально. Пакет в зависимости не ставится —
+ * он приходит снаружи, как и maplibre-gl, поэтому импортировать его типы нельзя. Здесь
+ * повторена публичная часть .d.ts версии 0.7.3; всё необязательное помечено `?`, чтобы
+ * более старая сборка на странице не ломала типы у потребителя.
+ */
+type Maps3DThemeName = "light" | "dark" | "navigator-light" | "navigator-dark" | "mobile-light" | "mobile-dark";
+/** Идентификатор слоя в реестре: buildings, objects, traffic, terrain, indoor, closures, parking, fuel, charging. */
+type Maps3DLayerId = string;
+/** Уровень детализации зданий. */
+type Maps3DBuildingDetail = "footprint" | "volume" | "roofs" | "facade";
+/**
+ * Снимок состояния слоя. Три поля независимы: слой может быть включён клиентом (`wanted`),
+ * но не нарисован — рельеф в режиме auto ждёт обзорного зума, перекрытия ждут своего
+ * тайлсета, планы этажей — данных по зданию.
+ */
+interface IMaps3DLayerState {
+    id: Maps3DLayerId;
+    /** Чего хочет клиент: последний setLayer либо умолчание стиля. */
+    wanted: boolean;
+    /** Что позволяет стиль: объявлен ли слой и есть ли под него данные. */
+    available: boolean;
+    /** Что нарисовано прямо сейчас. Именно это поле показывает, включён слой на деле или нет. */
+    active: boolean;
+    /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
+    params: Record<string, unknown>;
+}
+interface IMaps3DSelectionStyle {
+    color?: string | number;
+    opacity?: number;
+    glow?: number;
+    durationMs?: number;
+    easing?: "ease-out" | "linear";
+}
+interface IMaps3DRoadHit {
+    name: string;
+    nameRu?: string;
+    class?: string;
+    ref?: string;
+    props: Record<string, unknown>;
+    distancePx: number;
+}
 interface IMaps3DTrafficOptions {
     raster?: boolean;
     rasterMaxZoom?: number;
     graph?: string;
+    tilesUrl?: string;
+    clicks?: boolean;
+    opacity?: number;
+    minZoom?: number;
+    refreshMs?: number;
+    arrows?: boolean;
+    maxTileZoom?: number;
+}
+interface IMaps3DIndoorOptions {
+    level?: number;
+    [key: string]: unknown;
+}
+interface IMaps3DClosuresOptions {
+    [key: string]: unknown;
+}
+interface IMaps3DPlacesOptions {
+    highlight?: boolean;
+    paid?: boolean;
+    free?: boolean;
+    unknown?: boolean;
+    [key: string]: unknown;
+}
+interface IMaps3DBuildingsOptions {
+    detail?: Maps3DBuildingDetail;
+    [key: string]: unknown;
 }
 interface IMaps3DLayerOptions {
     apiKey?: string | null;
     base?: string;
-    buildings?: boolean | Record<string, unknown>;
+    /** Явный модуль maplibre-gl, если на странице несколько сборок. */
+    maplibre?: unknown;
+    endpoint?: string;
+    buildings?: boolean | IMaps3DBuildingsOptions;
     traffic?: boolean | IMaps3DTrafficOptions;
+    indoor?: boolean | IMaps3DIndoorOptions;
+    closures?: boolean | IMaps3DClosuresOptions;
+    places?: IMaps3DPlacesOptions;
     minZoom?: number;
     lodBias?: number;
     memoryBudget?: number;
     maskReplaced?: boolean;
     typeReplacements?: boolean;
+    modelsSource?: string;
+    modelsSourceLayer?: string;
+    modelsTilesUrl?: string;
 }
 interface IMaps3DBuildingsController {
     setWindows?(enabled: boolean): void;
@@ -51,6 +127,7 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
+    index?: number;
     height?: number;
     props?: Record<string, unknown>;
     [key: string]: unknown;
@@ -61,36 +138,94 @@ interface IMaps3DObjectsLightOptions {
     sky?: number;
     exposure?: number;
 }
+interface IMaps3DDiagnostics {
+    terrainActive: boolean;
+    drapeRefreshes: number;
+    contextLost: boolean;
+    buildings: unknown;
+}
 interface IMaps3DLayer {
     attach(map: Map): void | Promise<void>;
+    /** Есть у экземпляров из enhance(); у созданных конструктором готовность даёт сам attach(). */
+    readonly ready?: Promise<void>;
     destroy?(): void;
     remove?(): void;
+    setLayer?(id: Maps3DLayerId, on: boolean, params?: Record<string, unknown>): boolean;
+    layer?(id: Maps3DLayerId): IMaps3DLayerState | null;
+    layers?(): IMaps3DLayerState[];
+    onLayers?(callback: (state: IMaps3DLayerState) => void): () => void;
+    refreshLayers?(): void;
     buildings?: IMaps3DBuildingsController | null;
     setBuildingsEnabled?(enabled: boolean): void;
     onBuildingClick?(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    selectBuilding?(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
+    clearSelection?(): void;
+    selectedBuilding?(): number | string | null;
+    setSelectionStyle?(style: IMaps3DSelectionStyle): void;
+    onRoadClick?(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    roadAt?(point: {
+        x: number;
+        y: number;
+    }, tolerancePx?: number): IMaps3DRoadHit | null;
+    readonly roadsNamed?: boolean;
     traffic?: boolean;
     trafficRaster?: boolean;
     setTraffic?(enabled: boolean): void;
     setTrafficOpacity?(opacity: number): void;
     setTrafficClicks?(enabled: boolean): void;
     setTrafficRaster?(enabled: boolean): void;
+    setTrafficGraph?(graph: string): void;
     refreshTraffic?(): void;
+    setIndoor?(enabled: boolean): void;
+    setIndoorLevel?(level: number): void;
+    readonly indoorLevels?: number[];
+    refreshIndoor?(): void;
+    showPlace?(lon: number, lat: number, level?: number | null, zoom?: number): void;
     setObjectsLight?(options: IMaps3DObjectsLightOptions): void;
     setMinZoom?(zoom: number): void;
     refresh?(): Promise<void>;
     clearCache?(): Promise<void>;
+    diagnostics?(): IMaps3DDiagnostics;
 }
 interface IMaps3DTransformRequestOptions {
-    base: string;
+    base?: string;
     apiKey?: string | null;
 }
-type Maps3DTransformRequest = (options: IMaps3DTransformRequestOptions) => unknown;
+interface IMaps3DMapOptionsInput extends IMaps3DTransformRequestOptions {
+    /** Имя темы платформы либо полный URL своего стиля. */
+    style?: string;
+    antialias?: boolean;
+}
+interface IMaps3DMapOptionsResult {
+    style: string;
+    transformRequest: (url: string) => {
+        url: string;
+    };
+    canvasContextAttributes?: {
+        antialias: boolean;
+    };
+}
+type Maps3DTransformRequest = (options: IMaps3DTransformRequestOptions) => (url: string) => {
+    url: string;
+};
 type Maps3DCtor = (new (options: IMaps3DLayerOptions) => IMaps3DLayer) & {
     transformRequest: Maps3DTransformRequest;
+    /** Стиль + transformRequest + antialias одним объектом. Появился в 0.5.0. */
+    mapOptions?(options: IMaps3DMapOptionsInput): IMaps3DMapOptionsResult;
+    /** Адрес стиля по имени темы. Неизвестное имя — явная ошибка, а не тихий 404. */
+    styleUrl?(style?: string, base?: string): string;
+    /** Подключение к уже созданной карте; возвращает экземпляр с `ready`. */
+    enhance?(map: Map, options?: IMaps3DLayerOptions): IMaps3DLayer;
+    /** MapLibre с платформы вместе со своим воркером. */
+    maplibre?(options?: {
+        base?: string;
+    }): Promise<unknown>;
+    readonly maplibreVersion?: string;
 };
 
 interface IMahalMapOptions {
     container?: string | HTMLElement;
+    /** Полный URL своего стиля. Задан — SDK его не меняет, setStyle() становится no-op. */
     style?: string;
     theme?: Theme;
     lang?: MapLanguage;
@@ -98,20 +233,43 @@ interface IMahalMapOptions {
     zoom?: number;
     pitch?: number;
     bearing?: number;
-    autoAddVectorSource?: boolean;
-    /** "legacy" (default) — старый движок (mtile.gram.tj). "3d" — новый GramMaps движок (route.gram.tj) с поддержкой Maps3D. */
-    engine?: MapEngine;
-    /** Включает Maps3D слой (детальные 3D-здания). Работает только при engine: "3d". */
+    /** Подключает Maps3D (объём, объекты, пробки, рельеф, планы этажей). По умолчанию `true`. */
     enable3D?: boolean;
-    /** Домен платформы GramMaps для engine: "3d". По умолчанию https://route.gram.tj */
+    /** Домен платформы MahalMaps. По умолчанию https://navi.gram.tj */
     base?: string;
-    /** Имя пресета стиля GramMaps (напр. "standard-night") для engine: "3d". */
-    preset?: string;
-    /** Доп. опции Maps3D слоя (buildings, traffic, minZoom, lodBias, memoryBudget, ...). */
-    maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
+    /**
+     * Семейство стилей платформы. `theme` выбирает внутри него светлую/тёмную:
+     * "default" → light/dark, "navigator" → navigator-light/navigator-dark,
+     * "mobile" → mobile-light/mobile-dark.
+     */
+    family?: MapStyleFamily;
+    /**
+     * Явное имя темы платформы вместо пары `family` + `theme` (или полный URL стиля).
+     * Задано — стиль считается зафиксированным и setStyle() его не меняет.
+     */
+    preset?: Maps3DThemeName | string;
+    /**
+     * Сглаживание сцены. Без него тонкая геометрия 3D-объектов (перила, мачты, ряды сидений)
+     * на отдалении рассыпается в рябь. По умолчанию `true` при включённом 3D.
+     */
+    antialias?: boolean;
+    /** Опции Maps3D: buildings, traffic, indoor, closures, terrain, minZoom, lodBias, memoryBudget, ... */
+    maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
+    /**
+     * @deprecated Игнорируется с 2.0.0. Движок один — платформа MahalMaps через
+     * @grammaps/maps3d-web. Без переданного Maps3D карта поднимается на запасном стиле.
+     */
+    engine?: MapEngine;
+    /**
+     * @deprecated Игнорируется с 2.0.0. Запасной векторный стиль применяется сам,
+     * когда Maps3D не передан.
+     */
+    autoAddVectorSource?: boolean;
 }
 type Theme = "dark" | "light";
+type MapStyleFamily = "default" | "navigator" | "mobile";
 type MapLanguage = "tj" | "ru";
+/** @deprecated Оставлен, чтобы не ломать компиляцию у потребителей. Значение не используется. */
 type MapEngine = "legacy" | "3d";
 
 interface MahalMapDefaultMarkerProps {
@@ -235,9 +393,8 @@ declare class MahalMap {
     private options;
     private language;
     private instanceKey;
-    private engine;
     private gramBase;
-    private gramPreset;
+    private styleFamily;
     private presetIsExplicit;
     private maps3dCtor?;
     private maps3dLayer?;
@@ -247,14 +404,17 @@ declare class MahalMap {
     private static getInstanceKey;
     private static normalizeLanguage;
     static setDefaultLanguage(lang?: string | null): void;
-    private static getDefaultStyle;
-    private static getVectorStyle;
+    /**
+     * Запасной стиль: Maps3D не передан — стилей платформы взять неоткуда, поднимаем карту
+     * на старом векторном стиле mtile.gram.tj с подписью ?token=. 3D при этом не работает.
+     */
+    private static getFallbackStyle;
     private static getMapToken;
     private static getMaps3DCtor;
     /**
-     * Проверяет подписку JSApi перед созданием карты. Нужна только для legacy-движка
-     * (mtile.gram.tj): у engine: "3d" (GramMaps, navi.gram.tj) доступ контролирует сама
-     * платформа по ?key=, отдельная проверка там не применяется и пропускается.
+     * Проверяет подписку JSApi перед созданием карты. Нужна только на запасном стиле
+     * (mtile.gram.tj, когда Maps3D не передан): у платформы MahalMaps доступ контролирует
+     * она сама по ?key=, отдельная проверка там не применяется и пропускается.
      *
      * Fail-open: блокирует создание карты только при явном ответе сервиса success:false.
      * Сетевая ошибка (сервис недоступен, CORS, таймаут) карту не роняет — иначе падение
@@ -262,11 +422,25 @@ declare class MahalMap {
      */
     private static ensureJSApiSubscription;
     /**
-     * Асинхронный аналог create(): для engine: "legacy" сначала дожидается проверки подписки
-     * JSApi и, если её нет, не создаёт карту вообще (MapLibre-инстанс не строится).
-     * Для engine: "3d" — тот же create() без проверки.
+     * Асинхронный аналог create(): на запасном стиле (Maps3D не передан) сначала дожидается
+     * проверки подписки JSApi и, если её нет, не создаёт карту вообще (MapLibre-инстанс не
+     * строится). С Maps3D — тот же create() без проверки.
      */
     static createAsync(options: IMahalMapOptions, maplibreObject?: MapLibreApi, maps3dCtor?: Maps3DCtor): Promise<MahalMap>;
+    /**
+     * Имя темы платформы или полный URL стиля. Явный `style`/`preset` побеждает пару
+     * `family` + `theme`: оба считаются фиксацией стиля, и setStyle() их не трогает.
+     */
+    private static resolveStyleName;
+    /**
+     * Стиль + transformRequest + antialias от самого SDK. mapOptions() — документированная
+     * дверь (есть с 0.5.0); у сборок постарше собираем то же из styleUrl/transformRequest.
+     *
+     * Неизвестное имя темы SDK считает явной ошибкой (а не тихим 404) — переупаковываем её,
+     * чтобы в консоли было видно, что имя пришло из опций MahalMap.
+     */
+    private static buildPlatformMapOptions;
+    private static requireAbsoluteStyle;
     static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi, maps3dCtor?: Maps3DCtor): MahalMap;
     static onReady(container: string, callback: (map: Map) => void): void;
     static getInstance(container: string): MahalMap;
@@ -279,6 +453,21 @@ declare class MahalMap {
     static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
     static whenMaps3DReady(instance: MahalMap): Promise<IMaps3DLayer | undefined>;
     static toggle3DBuildings(instance: MahalMap, enabled: boolean): void;
+    static setLayer(instance: MahalMap, id: Maps3DLayerId, on: boolean, params?: Record<string, unknown>): boolean;
+    static getLayerState(instance: MahalMap, id: Maps3DLayerId): IMaps3DLayerState | null;
+    static getLayers(instance: MahalMap): IMaps3DLayerState[];
+    static onLayers(instance: MahalMap, callback: (state: IMaps3DLayerState) => void): () => void;
+    static refreshLayers(instance: MahalMap): void;
+    static onBuildingClick(instance: MahalMap, callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    static selectBuilding(instance: MahalMap, id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
+    static clearSelection(instance: MahalMap): void;
+    static selectedBuilding(instance: MahalMap): string | number | null;
+    static setSelectionStyle(instance: MahalMap, style: IMaps3DSelectionStyle): void;
+    static onRoadClick(instance: MahalMap, callback: (hit: IMaps3DRoadHit | null) => void): void;
+    static roadAt(instance: MahalMap, point: {
+        x: number;
+        y: number;
+    }, tolerancePx?: number): IMaps3DRoadHit | null;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -287,17 +476,61 @@ declare class MahalMap {
     init(map: Map): void;
     getCamera(): CameraController;
     getMap(): Map;
+    /**
+     * Светлая/тёмная внутри выбранного семейства (`family`). Стиль, зафиксированный явным
+     * `style`/`preset`, не трогаем: его содержимое знает только тот, кто его задал.
+     * Без Maps3D менять нечего — карта на запасном стиле, у него варианта по теме нет.
+     */
     setStyle(theme: Theme): void;
+    private refreshLayersOnStyleLoad;
+    /**
+     * Язык подписей приходит из стиля платформы, отдельных URL по языкам больше нет —
+     * метод только запоминает выбор для остальных сервисов SDK (поиск, роутинг).
+     */
     setLanguage(lang: MapLanguage): void;
     getMaps3DLayer(): IMaps3DLayer | undefined;
-    /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
+    /**
+     * Вкл/выкл объёмные здания. Штатные здания стиля прячет и возвращает сам Maps3D —
+     * руками их видимость мы больше не трогаем, иначе две стороны спорят за один слой.
+     */
     toggle3DBuildings(enabled: boolean): void;
     /**
-     * Промис готовности слоя Maps3D: резолвится после attach(), когда доступен layer.buildings.
-     * Нужен для тонкой настройки окон/света — до attach контроллера зданий ещё нет.
-     * Резолвится в undefined, если движок не "3d", слой выключен или attach упал.
+     * Промис готовности слоя Maps3D. У экземпляров из enhance() это его собственный `ready`,
+     * у созданных конструктором — завершение attach(). До него layer.buildings ещё нет.
+     * Резолвится в undefined, если слой выключен, Maps3D не передан или подключение упало.
      */
     whenMaps3DReady(): Promise<IMaps3DLayer | undefined>;
+    /** Включить/выключить слой. `false` — такого слоя в подключённой сборке Maps3D нет. */
+    setLayer(id: Maps3DLayerId, on: boolean, params?: Record<string, unknown>): boolean;
+    /** Состояние слоя: wanted (воля клиента), available (позволяет стиль), active (нарисовано). */
+    getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
+    /** Снимок всех слоёв — по нему приложение рисует свою панель. */
+    getLayers(): IMaps3DLayerState[];
+    /** Подписка на изменения слоёв. Возвращает отписку (no-op, если слоя нет). */
+    onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
+    /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
+    refreshLayers(): void;
+    /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
+    onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
+    selectBuilding(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
+    clearSelection(): void;
+    selectedBuilding(): number | string | null;
+    setSelectionStyle(style: IMaps3DSelectionStyle): void;
+    /** Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение. */
+    onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
+    roadAt(point: {
+        x: number;
+        y: number;
+    }, tolerancePx?: number): IMaps3DRoadHit | null;
+    /** Есть ли в текущем стиле названия дорог. Нет — roadAt() всегда вернёт null. */
+    get roadsNamed(): boolean;
+    /**
+     * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
+     * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
+     */
+    private createMaps3DLayer;
     private attachMaps3DLayer;
     /**
      * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один
@@ -306,17 +539,12 @@ declare class MahalMap {
      * вызов teardown попал бы на уже освобождённый объект.
      */
     private static teardownMaps3DLayer;
-    private applyMaps3DBuildingMode;
     /**
-     * Прячет/показывает нативный слой зданий GramMaps-пресетов ("building-3d"), не задевая слои
-     * самого Maps3D. Нужно, иначе плоский слой стиля рисуется поверх процедурных 3D-зданий и
-     * визуально их перекрывает.
-     *
-     * Только для встроенных пресетов (buildGramStyleUrl) — при пользовательском `options.style`
-     * мы не знаем структуру стиля, гасить слои по имени/source-layer небезопасно (можно случайно
-     * погасить чужую fill-extrusion, никак не связанную со зданиями GramMaps).
+     * Приводит объём зданий к желаемому состоянию. Реестр слоёв (0.7.x) — основная дверь:
+     * он же прячет и возвращает штатные здания стиля. setBuildingsEnabled — путь для
+     * сборок Maps3D постарше, где реестра ещё нет.
      */
-    private setNativeBuildingsVisible;
+    private applyMaps3DBuildingMode;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;
@@ -593,4 +821,4 @@ declare namespace index {
   export { index_checkCoordinates as checkCoordinates, index_debounce as debounce, index_geojsonPolyline as geojsonPolyline, index_geometryPolyline as geometryPolyline, index_trimValue as trimValue };
 }
 
-export { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DObjectsLightOptions, type IMaps3DTrafficOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DBuildingsOptions, type IMaps3DClosuresOptions, type IMaps3DDiagnostics, type IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, type Maps3DThemeName, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };