mahal_map 1.6.21 → 1.6.22

package/README.md

@@ -240,6 +240,180 @@ map.toggle3DBuildings(true); // вкл обратно
 MahalMap.toggle3DBuildings(map, false);
 ```
 
+#### `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
@@ -472,6 +646,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 +686,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

@@ -233,8 +233,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 +253,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 +268,20 @@ 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;
     private applyMaps3DBuildingMode;
     /**
-     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
-     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
-     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и прочие
+     * fill/fill-extrusion слои зданий), не задевая слои самого Maps3D. Нужно, иначе плоский слой
+     * стиля рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Проверяем именно "здание" (id или source-layer), чтобы не гасить чужую экструзию
+     * в пользовательском стиле.
      */
     private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;

package/dist/index.d.ts

@@ -233,8 +233,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 +253,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 +268,20 @@ 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;
     private applyMaps3DBuildingMode;
     /**
-     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
-     * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
-     * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и прочие
+     * fill/fill-extrusion слои зданий), не задевая слои самого Maps3D. Нужно, иначе плоский слой
+     * стиля рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
+     * Проверяем именно "здание" (id или source-layer), чтобы не гасить чужую экструзию
+     * в пользовательском стиле.
      */
     private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;