mahal_map 2.0.1 → 2.0.3

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import * as maplibre_gl from 'maplibre-gl';
 import { Map, FlyToOptions, Marker } from 'maplibre-gl';
 
 declare class CameraController {
@@ -174,9 +175,12 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
+    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
+    props: Record<string, unknown>;
+    /** Высота здания в метрах. */
+    height: number;
+    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
-    height?: number;
-    props?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface IMaps3DObjectsLightOptions {
@@ -263,10 +267,13 @@ type Maps3DCtor = (new (options: IMaps3DLayerOptions) => IMaps3DLayer) & {
     styleUrl?(style?: string, base?: string): string;
     /** Подключение к уже созданной карте; возвращает экземпляр с `ready`. */
     enhance?(map: Map, options?: IMaps3DLayerOptions): IMaps3DLayer;
-    /** MapLibre с платформы вместе со своим воркером. */
+    /**
+     * MapLibre с платформы вместе со своим воркером. Возвращает то же, что
+     * `import * as maplibregl from "maplibre-gl"` — декларации гарантирует peerDependency.
+     */
     maplibre?(options?: {
         base?: string;
-    }): Promise<unknown>;
+    }): Promise<typeof maplibre_gl>;
     readonly maplibreVersion?: string;
 };
 
@@ -456,6 +463,11 @@ declare class MahalMap {
     private maps3dReady?;
     private buildingsEnabled;
     private workerCheckTimer?;
+    private styleChangeHandler?;
+    private pendingBuildingClick?;
+    private pendingRoadClick?;
+    private pendingSelectionStyle?;
+    private pendingLayerSubscribers;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -542,7 +554,21 @@ declare class MahalMap {
      * Без Maps3D менять нечего — карта на запасном стиле, у него варианта по теме нет.
      */
     setStyle(theme: Theme): void;
-    private refreshLayersOnStyleLoad;
+    /**
+     * Адрес стиля по имени темы. mapOptions() — основной контракт (есть с 0.5.0);
+     * styleUrl остаётся запасным путём для сборок, где mapOptions ещё нет.
+     * Раньше здесь был только styleUrl, и сборка с одним mapOptions() тему не меняла.
+     */
+    private resolvePlatformStyle;
+    /**
+     * Полная смена стиля уносит слои Maps3D вместе с ним — реестр умеет вернуть волю
+     * клиента, но только когда новый стиль уже загружен.
+     *
+     * Слушаем styledata, а не style.load: setStyle() идёт через дифф и style.load при
+     * этом не поднимает — с ним восстановление просто не случалось. styledata приходит
+     * многократно, поэтому ждём isStyleLoaded() и снимаем обработчик сами.
+     */
+    private refreshLayersOnStyleChange;
     /**
      * Язык подписей приходит из стиля платформы, отдельных URL по языкам больше нет —
      * метод только запоминает выбор для остальных сервисов SDK (поиск, роутинг).
@@ -573,7 +599,10 @@ declare class MahalMap {
     getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
     /** Снимок всех слоёв — по нему приложение рисует свою панель. */
     getLayers(): IMaps3DLayerState[];
-    /** Подписка на изменения слоёв. Возвращает отписку (no-op, если слоя нет). */
+    /**
+     * Подписка на изменения слоёв. Возвращает отписку. Работает и до появления слоя:
+     * подписка переиграется при его подключении, а отписка снимет её в любом случае.
+     */
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
@@ -589,14 +618,21 @@ declare class MahalMap {
      * и метка окажется в чужом зале.
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
-    /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
+    /**
+     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Подписываться можно сразу после create(), даже когда слой ещё не поднят
+     * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     */
     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;
-    /** Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение. */
+    /**
+     * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     */
     onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
@@ -610,6 +646,12 @@ declare class MahalMap {
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
      */
     private createMaps3DLayer;
+    /**
+     * Переигрывает волю клиента на только что подключённом слое: подписки на клики,
+     * облик выделения и подписчиков реестра. Нужно, когда карта создана без слоя
+     * (`enable3D: false`) — тогда всё это было сказано до его появления.
+     */
+    private applyPendingSubscriptions;
     private attachMaps3DLayer;
     /**
      * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as maplibre_gl from 'maplibre-gl';
 import { Map, FlyToOptions, Marker } from 'maplibre-gl';
 
 declare class CameraController {
@@ -174,9 +175,12 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
+    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
+    props: Record<string, unknown>;
+    /** Высота здания в метрах. */
+    height: number;
+    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
-    height?: number;
-    props?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface IMaps3DObjectsLightOptions {
@@ -263,10 +267,13 @@ type Maps3DCtor = (new (options: IMaps3DLayerOptions) => IMaps3DLayer) & {
     styleUrl?(style?: string, base?: string): string;
     /** Подключение к уже созданной карте; возвращает экземпляр с `ready`. */
     enhance?(map: Map, options?: IMaps3DLayerOptions): IMaps3DLayer;
-    /** MapLibre с платформы вместе со своим воркером. */
+    /**
+     * MapLibre с платформы вместе со своим воркером. Возвращает то же, что
+     * `import * as maplibregl from "maplibre-gl"` — декларации гарантирует peerDependency.
+     */
     maplibre?(options?: {
         base?: string;
-    }): Promise<unknown>;
+    }): Promise<typeof maplibre_gl>;
     readonly maplibreVersion?: string;
 };
 
@@ -456,6 +463,11 @@ declare class MahalMap {
     private maps3dReady?;
     private buildingsEnabled;
     private workerCheckTimer?;
+    private styleChangeHandler?;
+    private pendingBuildingClick?;
+    private pendingRoadClick?;
+    private pendingSelectionStyle?;
+    private pendingLayerSubscribers;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -542,7 +554,21 @@ declare class MahalMap {
      * Без Maps3D менять нечего — карта на запасном стиле, у него варианта по теме нет.
      */
     setStyle(theme: Theme): void;
-    private refreshLayersOnStyleLoad;
+    /**
+     * Адрес стиля по имени темы. mapOptions() — основной контракт (есть с 0.5.0);
+     * styleUrl остаётся запасным путём для сборок, где mapOptions ещё нет.
+     * Раньше здесь был только styleUrl, и сборка с одним mapOptions() тему не меняла.
+     */
+    private resolvePlatformStyle;
+    /**
+     * Полная смена стиля уносит слои Maps3D вместе с ним — реестр умеет вернуть волю
+     * клиента, но только когда новый стиль уже загружен.
+     *
+     * Слушаем styledata, а не style.load: setStyle() идёт через дифф и style.load при
+     * этом не поднимает — с ним восстановление просто не случалось. styledata приходит
+     * многократно, поэтому ждём isStyleLoaded() и снимаем обработчик сами.
+     */
+    private refreshLayersOnStyleChange;
     /**
      * Язык подписей приходит из стиля платформы, отдельных URL по языкам больше нет —
      * метод только запоминает выбор для остальных сервисов SDK (поиск, роутинг).
@@ -573,7 +599,10 @@ declare class MahalMap {
     getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
     /** Снимок всех слоёв — по нему приложение рисует свою панель. */
     getLayers(): IMaps3DLayerState[];
-    /** Подписка на изменения слоёв. Возвращает отписку (no-op, если слоя нет). */
+    /**
+     * Подписка на изменения слоёв. Возвращает отписку. Работает и до появления слоя:
+     * подписка переиграется при его подключении, а отписка снимет её в любом случае.
+     */
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
@@ -589,14 +618,21 @@ declare class MahalMap {
      * и метка окажется в чужом зале.
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
-    /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
+    /**
+     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Подписываться можно сразу после create(), даже когда слой ещё не поднят
+     * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     */
     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;
-    /** Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение. */
+    /**
+     * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     */
     onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
@@ -610,6 +646,12 @@ declare class MahalMap {
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
      */
     private createMaps3DLayer;
+    /**
+     * Переигрывает волю клиента на только что подключённом слое: подписки на клики,
+     * облик выделения и подписчиков реестра. Нужно, когда карта создана без слоя
+     * (`enable3D: false`) — тогда всё это было сказано до его появления.
+     */
+    private applyPendingSubscriptions;
     private attachMaps3DLayer;
     /**
      * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один