mahal_map 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -26,17 +26,64 @@ interface IAdditionalParamType {
  * более старая сборка на странице не ломала типы у потребителя.
  */
 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";
+/** Режим рельефа: `auto` показывает его на обзорных зумах, `on` — всегда (дороже по трафику и кадру). */
+type Maps3DTerrainMode = "auto" | "on" | "off";
+/**
+ * Параметры каждого слоя реестра. Служит и справочником, и источником типов:
+ * ключи дают список id, значения — допустимые `params` в setLayer().
+ *
+ * У самой Maps3D id слоя типизирован как `string`, поэтому опечатка там проходит
+ * компиляцию и проваливается в рантайме (setLayer вернёт false). Здесь список
+ * фиксирован по таблице слоёв 0.7.3 — промах ловится на сборке.
+ */
+interface IMaps3DLayerParams {
+    /** Объёмные здания. По умолчанию включён. */
+    buildings: {
+        detail?: Maps3DBuildingDetail;
+    };
+    /** Расставленные 3D-объекты. По умолчанию включён. */
+    objects: Record<string, never>;
+    /** Пробки векторным слоем. По умолчанию выключен. */
+    traffic: Record<string, never>;
+    /** Пробки картинкой с сервера, без клика по дороге. По умолчанию выключен. */
+    trafficRaster: Record<string, never>;
+    /**
+     * Парковки. По умолчанию включён. Подтип берётся из атрибута `fee`:
+     * `paid` — `fee=yes`, `free` — `fee=no`, `unknown` — атрибута нет.
+     */
+    parking: {
+        highlight?: boolean;
+        paid?: boolean;
+        free?: boolean;
+        unknown?: boolean;
+    };
+    /** Заправки. По умолчанию включён. */
+    fuel: Record<string, never>;
+    /** Зарядки. По умолчанию включён. */
+    charging: Record<string, never>;
+    /** Перекрытия дорог. По умолчанию выключен, требует своего тайлсета. */
+    closures: Record<string, never>;
+    /** Планы этажей. По умолчанию выключен, требует данных по зданию. */
+    indoor: {
+        level?: number;
+    };
+    /** Рельеф. По умолчанию `auto`. */
+    terrain: {
+        mode?: Maps3DTerrainMode;
+    };
+}
+/** Идентификатор слоя в реестре Maps3D. */
+type Maps3DLayerId = keyof IMaps3DLayerParams;
 /**
  * Снимок состояния слоя. Три поля независимы: слой может быть включён клиентом (`wanted`),
  * но не нарисован — рельеф в режиме auto ждёт обзорного зума, перекрытия ждут своего
  * тайлсета, планы этажей — данных по зданию.
  */
 interface IMaps3DLayerState {
-    id: Maps3DLayerId;
+    /** Не сужен до Maps3DLayerId: сборка Maps3D может отдать слой, которого нет в нашем списке. */
+    id: string;
     /** Чего хочет клиент: последний setLayer либо умолчание стиля. */
     wanted: boolean;
     /** Что позволяет стиль: объявлен ли слой и есть ли под него данные. */
@@ -150,8 +197,8 @@ interface IMaps3DLayer {
     readonly ready?: Promise<void>;
     destroy?(): void;
     remove?(): void;
-    setLayer?(id: Maps3DLayerId, on: boolean, params?: Record<string, unknown>): boolean;
-    layer?(id: Maps3DLayerId): IMaps3DLayerState | null;
+    setLayer?(id: string, on: boolean, params?: Record<string, unknown>): boolean;
+    layer?(id: string): IMaps3DLayerState | null;
     layers?(): IMaps3DLayerState[];
     onLayers?(callback: (state: IMaps3DLayerState) => void): () => void;
     refreshLayers?(): void;
@@ -255,6 +302,12 @@ interface IMahalMapOptions {
     antialias?: boolean;
     /** Опции Maps3D: buildings, traffic, indoor, closures, terrain, minZoom, lodBias, memoryBudget, ... */
     maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
+    /**
+     * Диагностика неработающего веб-воркера MapLibre: если через 8 с после создания карты
+     * не разобран ни один векторный тайл, в консоль уходит предупреждение с причиной и
+     * решением. `false` отключает проверку, число задаёт свою задержку в мс.
+     */
+    workerCheck?: boolean | number;
     /**
      * @deprecated Игнорируется с 2.0.0. Движок один — платформа MahalMaps через
      * @grammaps/maps3d-web. Без переданного Maps3D карта поднимается на запасном стиле.
@@ -382,6 +435,8 @@ declare class MahalMap {
     private static instances;
     private static defaultLanguage;
     private static disposedMaps3DLayers;
+    /** Через сколько мс после создания карты проверяем, ожил ли веб-воркер MapLibre. */
+    private static readonly WORKER_CHECK_DELAY;
     private isReady;
     private readyCallbacks;
     private map;
@@ -400,6 +455,7 @@ declare class MahalMap {
     private maps3dLayer?;
     private maps3dReady?;
     private buildingsEnabled;
+    private workerCheckTimer?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -453,11 +509,15 @@ 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 setLayer<Id extends Maps3DLayerId>(instance: MahalMap, id: Id, on: boolean, params?: IMaps3DLayerParams[Id]): 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 getIndoorLevels(instance: MahalMap): number[];
+    static setIndoorLevel(instance: MahalMap, level: number): void;
+    static refreshIndoor(instance: MahalMap): void;
+    static showPlace(instance: MahalMap, lon: number, lat: number, level?: number | null, zoom?: number): 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;
@@ -500,8 +560,15 @@ declare class MahalMap {
      * Резолвится в undefined, если слой выключен, Maps3D не передан или подключение упало.
      */
     whenMaps3DReady(): Promise<IMaps3DLayer | undefined>;
-    /** Включить/выключить слой. `false` — такого слоя в подключённой сборке Maps3D нет. */
-    setLayer(id: Maps3DLayerId, on: boolean, params?: Record<string, unknown>): boolean;
+    /**
+     * Включить/выключить слой. `params` типизирован под конкретный слой: `terrain` ждёт
+     * `{ mode }`, `buildings` — `{ detail }`, `indoor` — `{ level }`, у остальных параметров нет.
+     *
+     * Возвращает `false`, если такого слоя в подключённой сборке Maps3D нет или Maps3D не передан.
+     * Слой, которого ещё нет в нашем списке id, доступен напрямую:
+     * `map.getMaps3DLayer()?.setLayer?.("новый", true)`.
+     */
+    setLayer<Id extends Maps3DLayerId>(id: Id, on: boolean, params?: IMaps3DLayerParams[Id]): boolean;
     /** Состояние слоя: wanted (воля клиента), available (позволяет стиль), active (нарисовано). */
     getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
     /** Снимок всех слоёв — по нему приложение рисует свою панель. */
@@ -510,6 +577,18 @@ declare class MahalMap {
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
+    /** Этажи, найденные в текущем виде карты. Пусто — данных по зданию нет. */
+    getIndoorLevels(): number[];
+    /** Переключить этаж. Нумерация OSM: 0 — первый наземный. */
+    setIndoorLevel(level: number): void;
+    /** Перечитать планы этажей — после правки картографом. */
+    refreshIndoor(): void;
+    /**
+     * Показать найденный объект и открыть его этаж. Ровно то, что нужно после поиска:
+     * у объектов внутри зданий приходит `level` — без него карта откроет первый этаж
+     * и метка окажется в чужом зале.
+     */
+    showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
     /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
     onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
     /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
@@ -539,6 +618,23 @@ declare class MahalMap {
      * вызов teardown попал бы на уже освобождённый объект.
      */
     private static teardownMaps3DLayer;
+    /**
+     * Диагностика неработающего веб-воркера MapLibre.
+     *
+     * Симптом злой: тайлы приходят, но разобрать их некому — карта показывает пустой фон,
+     * а в консоли лежит только `Uncaught SyntaxError: Unexpected token '<'`, где нет ни слова
+     * ни про MapLibre, ни про воркер. Причина почти всегда одна: сборщик не перенёс файл
+     * воркера рядом со сборкой, и вместо скрипта сервер отдаёт index.html.
+     *
+     * Проверку вешаем на таймер от создания карты, а НЕ на событие "load": при мёртвом
+     * воркере стиль не дозагружается и "load" не приходит вовсе.
+     *
+     * Смотрим на результат, а не на события: у Maps3D свой сторож (`gn`) слушает
+     * `data{sourceDataType:"content"}`, но это событие приходит при регистрации источника,
+     * за ~30 мс и без единого тайла — тревога снимается раньше, чем что-то могло сломаться.
+     */
+    private watchWorkerHealth;
+    private reportBrokenWorker;
     /**
      * Приводит объём зданий к желаемому состоянию. Реестр слоёв (0.7.x) — основная дверь:
      * он же прячет и возвращает штатные здания стиля. setBuildingsEnabled — путь для
@@ -821,4 +917,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 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 };
+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 IMaps3DLayerParams, 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 Maps3DTerrainMode, 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 };