mahal_map 1.6.21 → 1.6.23

package/README.md

@@ -12,10 +12,10 @@ npm install mahal_map maplibre-gl
 
 `maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
 
-Для нового 3D-движка (`engine: "3d"`) дополнительно нужен `@grammaps/maps3d-web`:
+`@grammaps/maps3d-web` объявлен peer dependency пакета (в `package.json` помечен как `optional` — без него `engine: "legacy"` работает как обычно). Для `engine: "3d"` он обязателен в рантайме: установите его явно.
 
 ```sh
-npm i @grammaps/maps3d-web maplibre-gl
+npm i mahal_map maplibre-gl @grammaps/maps3d-web
 ```
 
 ## Быстрый старт через NPM
@@ -71,8 +71,6 @@ const map = MahalMap.create(
 </script>
 ```
 
-````
-
 Через NPM язык можно передать при создании карты:
 
 ```ts
@@ -84,7 +82,7 @@ const map = MahalMap.create(
   },
   maplibregl,
 );
-````
+```
 
 Через browser SDK язык можно передать в URL скрипта:
 
@@ -96,9 +94,13 @@ const map = MahalMap.create(
 
 ## Параметры создания карты
 
-`MahalMap.create(options, maplibreObject?)`
+`MahalMap.create(options, maplibreObject?, maps3dCtor?)`
+
+`maps3dCtor` — импортированный конструктор `Maps3D` (третий, необязательный аргумент). Если не передан, SDK ищет его в `window.Maps3D`.
 
 ```ts
+import type { IMaps3DLayerOptions } from "mahal_map";
+
 interface IMahalMapOptions {
   container?: string | HTMLElement;
   style?: string;
@@ -113,7 +115,7 @@ interface IMahalMapOptions {
   enable3D?: boolean;
   base?: string;
   preset?: string;
-  maps3d?: IMaps3DOptions;
+  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
 }
 ```
 
@@ -190,14 +192,26 @@ MahalMap.getMaps3DLayer(map);
 
 ### 3D-здания
 
-`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс:
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс.
+
+**Ручной `new Maps3D(...)` — отдельный сценарий.** Карту при этом создавайте с `enable3D: false`, иначе на неё повиснут два слоя Maps3D сразу (автоматический от `MahalMap` + ваш ручной) — дублирование зданий и лишний расход ресурсов:
 
 ```ts
+const apiKey = "YOUR_MAP_API_KEY";
+const base = "https://navi.gram.tj";
+
+const map = MahalMap.create(
+  { container: "map", engine: "3d", enable3D: false },
+  maplibregl,
+);
+
 const layer = new Maps3D({ apiKey, base, buildings: true });
-await layer.attach(map); // attach асинхронный, дожидается load карты сам
+await layer.attach(map.getMap()); // attach ждёт нативную карту MapLibre, не обёртку MahalMap
 ```
 
-Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её:
+Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её.
+
+Это работает только для встроенных пресетов **без** явного `options.preset`: `setStyle()` меняет пресет по теме (`light`/`dark` → `GRAM_PRESETS`), а при заданном `preset` считает стиль зафиксированным и ничего не делает (см. [`MahalMap.ts`](src/core/MahalMap.ts:363)). Чтобы сменить пресет/тему в этом случае — пересоздайте карту с другим `preset` или вызовите `map.getMap().setStyle(...)` напрямую.
 
 ```ts
 const layer = map.getMaps3DLayer();
@@ -222,13 +236,7 @@ layer?.onBuildingClick((info) => {
 
 #### Вкл/выкл 3D-здания на лету
 
-Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты:
-
-```ts
-layer?.setBuildingsEnabled(false); // напрямую через слой
-```
-
-Либо через обёртку `MahalMap` — она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
+Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты — через обёртку `MahalMap`. Она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
 
 ```ts
 const map = MahalMap.getInstance("map");
@@ -240,6 +248,182 @@ map.toggle3DBuildings(true); // вкл обратно
 MahalMap.toggle3DBuildings(map, false);
 ```
 
+`layer?.setBuildingsEnabled(false)` напрямую через слой **не используйте** — он не знает про штатный слой стиля `building-3d`, который `MahalMap` прячет при включённом 3D. Вызов только слоя оставит эти штатные здания скрытыми и одновременно выключит процедурные — в итоге зданий не будет видно вообще, до следующей перезагрузки стиля.
+
+#### `map.whenMaps3DReady()`
+
+`attach()` слоя асинхронный: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после attach. Чтобы не гадать — дождитесь готовности:
+
+```ts
+const layer = await map.whenMaps3DReady();
+
+layer?.buildings?.setWindowStyle(4);
+```
+
+Промис резолвится в `undefined`, если движок не `"3d"`, слой выключен (`enable3D: false`) или attach упал — ошибка при этом уходит в `console.error`, а карта остаётся живой со штатными зданиями стиля.
+
+### Подключение и выключение 3D-слоя: полный пример (Vue 3)
+
+Кнопка-переключатель «3D ⇄ контуры», тонкая настройка окон и корректная очистка при размонтировании. Слой `Maps3D` поднимает и цепляет сама библиотека — вручную `new Maps3D(...)`, `transformRequest` и `attach()` писать не нужно.
+
+```vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@grammaps/maps3d-web";
+import { MahalMap, keyUtils } from "mahal_map";
+
+const API_KEY = "YOUR_MAP_API_KEY";
+
+const mahalMap = shallowRef<MahalMap | null>(null);
+const is3dEnabled = ref(true);
+const isLayerReady = ref(false);
+
+const buildingModeText = computed(() =>
+  is3dEnabled.value ? "3D включено" : "Контуры",
+);
+const buildingToggleText = computed(() =>
+  is3dEnabled.value ? "Выключить 3D" : "Включить 3D",
+);
+
+function toggle3dBuildings() {
+  is3dEnabled.value = !is3dEnabled.value;
+  // Вкл/выкл детальных 3D-зданий: библиотека сама вернёт/спрячет плоские здания стиля.
+  mahalMap.value?.toggle3DBuildings(is3dEnabled.value);
+}
+
+onMounted(async () => {
+  // Токен — один на всё (стиль, тайлы, Maps3D). Отдельный apiKey слою передавать не нужно.
+  keyUtils.saveKey(API_KEY);
+
+  const map = MahalMap.create(
+    {
+      container: "map",
+      engine: "3d", // платформа GramMaps вместо legacy-стилей
+      theme: "dark", // preset standard-night; "light" → road-urban-lab-v2
+      center: [68.787, 38.573],
+      zoom: 16.6,
+      pitch: 58, // без наклона экструзия не видна
+      bearing: -20,
+      enable3D: true, // значение по умолчанию для engine: "3d"
+      maps3d: { minZoom: 16, lodBias: 0 },
+    },
+    maplibregl,
+    Maps3D,
+  );
+
+  mahalMap.value = map;
+
+  // Дожидаемся attach(): до него layer.buildings ещё нет.
+  const layer = await map.whenMaps3DReady();
+  const buildings = layer?.buildings;
+
+  if (!buildings) {
+    return;
+  }
+
+  buildings.setWindowMinZoom?.(16);
+  buildings.setWindowStyle(4);
+  buildings.setWindowDepth(0.85);
+  buildings.setWindowColor("#6b9ed1");
+  buildings.setWindowFrameColor("#f2f2f4");
+  buildings.setWindowGlow?.(0.22);
+  buildings.setEdgeRadius(1.2);
+
+  isLayerReady.value = true;
+});
+
+onBeforeUnmount(() => {
+  isLayerReady.value = false;
+  // destroy() сам снимает слой Maps3D и удаляет карту MapLibre.
+  mahalMap.value?.destroy();
+  mahalMap.value = null;
+});
+</script>
+
+<template>
+  <main class="map-page">
+    <div id="map" class="map" />
+
+    <section class="panel" aria-label="GramMaps 3D">
+      <span class="mode-label">{{ buildingModeText }}</span>
+      <button
+        type="button"
+        :aria-pressed="is3dEnabled"
+        :disabled="!isLayerReady"
+        @click="toggle3dBuildings"
+      >
+        {{ buildingToggleText }}
+      </button>
+    </section>
+  </main>
+</template>
+
+<style>
+.map-page,
+.map {
+  position: absolute;
+  inset: 0;
+}
+
+.panel {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  z-index: 2;
+}
+</style>
+```
+
+Что библиотека делает за вас против ручного подключения `@grammaps/maps3d-web`:
+
+| Ручной код                                      | Через `mahal_map`                                                 |
+| ----------------------------------------------- | ----------------------------------------------------------------- |
+| `style: base + "/maps/standard-night.json"`     | `engine: "3d"` + `theme` (или `preset` / `base` явно)             |
+| `transformRequest: Maps3D.transformRequest(..)` | ставится автоматически (и без Maps3D — своим фолбэком с `?key=`)  |
+| `new Maps3D({...}); await layer.attach(map)`    | `enable3D: true` + `maps3d: {...}`, `await map.whenMaps3DReady()` |
+| `setBuildingsEnabled` + `buildings.setWindows`  | `map.toggle3DBuildings(enabled)` — оба вызова разом               |
+| Плоские здания стиля поверх 3D после `setStyle` | скрываются сами на каждой загрузке стиля                          |
+| `layer.destroy(); map.remove()`                 | `map.destroy()`                                                    |
+
+#### То же самое без сборщика (browser SDK)
+
+```html
+<script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@grammaps/maps3d-web/dist/maps3d.global.js"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+
+<div id="map" style="width: 100%; height: 500px"></div>
+<button id="toggle3d" type="button">Выключить 3D</button>
+
+<script>
+  // Maps3D берётся из window.Maps3D — третий аргумент передавать не нужно.
+  const map = MahalMap.create({
+    container: "map",
+    engine: "3d",
+    theme: "dark",
+    center: [68.787, 38.573],
+    zoom: 16.6,
+    pitch: 58,
+  });
+
+  let enabled = true;
+
+  document.getElementById("toggle3d").addEventListener("click", () => {
+    enabled = !enabled;
+    MahalMap.toggle3DBuildings(map, enabled);
+    document.getElementById("toggle3d").textContent = enabled
+      ? "Выключить 3D"
+      : "Включить 3D";
+  });
+
+  MahalMap.whenMaps3DReady(map).then((layer) => {
+    layer?.buildings?.setWindowStyle(4);
+  });
+</script>
+```
+
 ### Пробки
 
 ```ts
@@ -263,18 +447,17 @@ layer?.setMinZoom(15);
 layer?.setObjectsLight({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
 await layer?.refresh(); // перечитать модели после правок
 await layer?.clearCache(); // сбросить IndexedDB-кеш ассетов
-layer?.destroy?.(); // отцепить слой (также вызывается автоматически в map.destroy())
 ```
 
-`map.destroy()` / `MahalMap.destroy(map)` сами вызывают `destroy()`/`remove()` у Maps3D слоя, если он был подключен — отдельно чистить не нужно.
+Для полной остановки карты используйте только `map.destroy()` / `MahalMap.destroy(map)` — они сами вызывают `destroy()`/`remove()` у Maps3D слоя. **Не вызывайте `layer.destroy()`/`layer.remove()` напрямую**: `MahalMap` не узнает об этом и продолжит считать слой активным (внутренний `maps3dLayer`, `buildingsEnabled`, видимость штатных зданий стиля разойдутся с реальностью). Нужно временно выключить только 3D-здания — используйте `map.toggle3DBuildings(false)` (см. выше).
 
 ## MahalMap
 
 `MahalMap` - основной класс карты. Конструктор закрыт, карту нужно создавать через `MahalMap.create()`.
 
-### `MahalMap.create(options, maplibreObject?)`
+### `MahalMap.create(options, maplibreObject?, maps3dCtor?)`
 
-Создает новый инстанс карты и сохраняет его по ключу `container`. Для стандартных стилей перед созданием карты должен быть сохранен map token через `keyUtils.saveKey()`. В browser SDK token читается из обязательного URL-параметра `apikey`.
+Создает новый инстанс карты и сохраняет его по ключу `container`. Для стандартных стилей перед созданием карты должен быть сохранен map token через `keyUtils.saveKey()`. В browser SDK token читается из обязательного URL-параметра `apikey`. Третий аргумент — необязательный конструктор `Maps3D`; без него SDK использует `window.Maps3D`.
 
 ```ts
 const map = MahalMap.create(
@@ -472,6 +655,7 @@ MahalMap.setCenter(map, [69.624024, 40.279687]);
 MahalMap.setZoom(map, 14);
 MahalMap.addMarker(map, marker);
 MahalMap.getMaps3DLayer(map);
+MahalMap.whenMaps3DReady(map);
 MahalMap.toggle3DBuildings(map, false);
 MahalMap.destroy(map);
 ```
@@ -511,6 +695,7 @@ MahalMap.setZoom(map, 14);
 | `setZoom(instance, zoom)`              | Меняет zoom карты.                                            |
 | `addMarker(instance, marker)`          | Добавляет маркер.                                             |
 | `getMaps3DLayer(instance)`             | Возвращает инстанс слоя Maps3D (только `engine: "3d"`).       |
+| `whenMaps3DReady(instance)`            | Промис слоя Maps3D после `attach()` (готов `layer.buildings`). |
 | `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
 | `destroy(instance)`                    | Полностью удаляет карту.                                      |
 | `loadKeyFromScriptUrl()`               | Читает `apikey` из URL SDK скрипта.                           |

package/dist/index.d.mts

@@ -216,6 +216,7 @@ type MapLibreApi = {
 declare class MahalMap {
     private static instances;
     private static defaultLanguage;
+    private static disposedMaps3DLayers;
     private isReady;
     private readyCallbacks;
     private map;
@@ -233,8 +234,7 @@ declare class MahalMap {
     private presetIsExplicit;
     private maps3dCtor?;
     private maps3dLayer?;
-    private maps3dLayerReady;
-    private maps3dLayerAttachPending;
+    private maps3dReady?;
     private buildingsEnabled;
     private constructor();
     private static getInstanceKey;
@@ -254,6 +254,7 @@ declare class MahalMap {
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
     static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
+    static whenMaps3DReady(instance: MahalMap): Promise<IMaps3DLayer | undefined>;
     static toggle3DBuildings(instance: MahalMap, enabled: boolean): void;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
@@ -268,12 +269,29 @@ declare class MahalMap {
     getMaps3DLayer(): IMaps3DLayer | undefined;
     /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
     toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Промис готовности слоя Maps3D: резолвится после attach(), когда доступен layer.buildings.
+     * Нужен для тонкой настройки окон/света — до attach контроллера зданий ещё нет.
+     * Резолвится в undefined, если движок не "3d", слой выключен или attach упал.
+     */
+    whenMaps3DReady(): Promise<IMaps3DLayer | undefined>;
     private attachMaps3DLayer;
+    /**
+     * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один
+     * раз: destroy()/attach-catch/toggle3DBuildings(false) все могут метить в один и тот же layer
+     * (напр. map.destroy() случился, пока attach() ещё не резолвился) — без WeakSet-гварда второй
+     * вызов teardown попал бы на уже освобождённый объект.
+     */
+    private static teardownMaps3DLayer;
     private applyMaps3DBuildingMode;
     /**
-     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
-     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
-     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Прячет/показывает нативный слой зданий GramMaps-пресетов ("building-3d"), не задевая слои
+     * самого Maps3D. Нужно, иначе плоский слой стиля рисуется поверх процедурных 3D-зданий и
+     * визуально их перекрывает.
+     *
+     * Только для встроенных пресетов (buildGramStyleUrl) — при пользовательском `options.style`
+     * мы не знаем структуру стиля, гасить слои по имени/source-layer небезопасно (можно случайно
+     * погасить чужую fill-extrusion, никак не связанную со зданиями GramMaps).
      */
     private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;

package/dist/index.d.ts

@@ -216,6 +216,7 @@ type MapLibreApi = {
 declare class MahalMap {
     private static instances;
     private static defaultLanguage;
+    private static disposedMaps3DLayers;
     private isReady;
     private readyCallbacks;
     private map;
@@ -233,8 +234,7 @@ declare class MahalMap {
     private presetIsExplicit;
     private maps3dCtor?;
     private maps3dLayer?;
-    private maps3dLayerReady;
-    private maps3dLayerAttachPending;
+    private maps3dReady?;
     private buildingsEnabled;
     private constructor();
     private static getInstanceKey;
@@ -254,6 +254,7 @@ declare class MahalMap {
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
     static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
+    static whenMaps3DReady(instance: MahalMap): Promise<IMaps3DLayer | undefined>;
     static toggle3DBuildings(instance: MahalMap, enabled: boolean): void;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
@@ -268,12 +269,29 @@ declare class MahalMap {
     getMaps3DLayer(): IMaps3DLayer | undefined;
     /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
     toggle3DBuildings(enabled: boolean): void;
+    /**
+     * Промис готовности слоя Maps3D: резолвится после attach(), когда доступен layer.buildings.
+     * Нужен для тонкой настройки окон/света — до attach контроллера зданий ещё нет.
+     * Резолвится в undefined, если движок не "3d", слой выключен или attach упал.
+     */
+    whenMaps3DReady(): Promise<IMaps3DLayer | undefined>;
     private attachMaps3DLayer;
+    /**
+     * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один
+     * раз: destroy()/attach-catch/toggle3DBuildings(false) все могут метить в один и тот же layer
+     * (напр. map.destroy() случился, пока attach() ещё не резолвился) — без WeakSet-гварда второй
+     * вызов teardown попал бы на уже освобождённый объект.
+     */
+    private static teardownMaps3DLayer;
     private applyMaps3DBuildingMode;
     /**
-     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
-     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
-     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Прячет/показывает нативный слой зданий GramMaps-пресетов ("building-3d"), не задевая слои
+     * самого Maps3D. Нужно, иначе плоский слой стиля рисуется поверх процедурных 3D-зданий и
+     * визуально их перекрывает.
+     *
+     * Только для встроенных пресетов (buildGramStyleUrl) — при пользовательском `options.style`
+     * мы не знаем структуру стиля, гасить слои по имени/source-layer небезопасно (можно случайно
+     * погасить чужую fill-extrusion, никак не связанную со зданиями GramMaps).
      */
     private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;