mahal_map 1.6.22 → 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,8 @@ map.toggle3DBuildings(true); // вкл обратно
 MahalMap.toggle3DBuildings(map, false);
 ```
 
+`layer?.setBuildingsEnabled(false)` напрямую через слой **не используйте** — он не знает про штатный слой стиля `building-3d`, который `MahalMap` прячет при включённом 3D. Вызов только слоя оставит эти штатные здания скрытыми и одновременно выключит процедурные — в итоге зданий не будет видно вообще, до следующей перезагрузки стиля.
+
 #### `map.whenMaps3DReady()`
 
 `attach()` слоя асинхронный: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после attach. Чтобы не гадать — дождитесь готовности:
@@ -313,12 +323,12 @@ onMounted(async () => {
     return;
   }
 
-  buildings.setWindowMinZoom(16);
+  buildings.setWindowMinZoom?.(16);
   buildings.setWindowStyle(4);
   buildings.setWindowDepth(0.85);
   buildings.setWindowColor("#6b9ed1");
   buildings.setWindowFrameColor("#f2f2f4");
-  buildings.setWindowGlow(0.22);
+  buildings.setWindowGlow?.(0.22);
   buildings.setEdgeRadius(1.2);
 
   isLayerReady.value = true;
@@ -437,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(

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;
@@ -275,13 +276,22 @@ declare class MahalMap {
      */
     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/fill-extrusion слои зданий), не задевая слои самого Maps3D. Нужно, иначе плоский слой
-     * стиля рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
-     * Проверяем именно "здание" (id или source-layer), чтобы не гасить чужую экструзию
-     * в пользовательском стиле.
+     * Прячет/показывает нативный слой зданий 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;
@@ -275,13 +276,22 @@ declare class MahalMap {
      */
     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/fill-extrusion слои зданий), не задевая слои самого Maps3D. Нужно, иначе плоский слой
-     * стиля рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
-     * Проверяем именно "здание" (id или source-layer), чтобы не гасить чужую экструзию
-     * в пользовательском стиле.
+     * Прячет/показывает нативный слой зданий GramMaps-пресетов ("building-3d"), не задевая слои
+     * самого Maps3D. Нужно, иначе плоский слой стиля рисуется поверх процедурных 3D-зданий и
+     * визуально их перекрывает.
+     *
+     * Только для встроенных пресетов (buildGramStyleUrl) — при пользовательском `options.style`
+     * мы не знаем структуру стиля, гасить слои по имени/source-layer небезопасно (можно случайно
+     * погасить чужую fill-extrusion, никак не связанную со зданиями GramMaps).
      */
     private setNativeBuildingsVisible;
     setCenter(center: [number, number]): void;