mahal_map 1.6.17 → 1.6.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -141,22 +141,22 @@ interface IMahalMapOptions {
141
141
  }
142
142
  ```
143
143
 
144
- | Параметр | Тип | Описание |
145
- | --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
146
- | `container` | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`. |
147
- | `style` | `string` | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля. |
148
- | `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`. |
149
- | `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`. |
150
- | `center` | `[number, number]` | Центр карты в формате `[lng, lat]`. |
151
- | `zoom` | `number` | Начальный zoom. |
152
- | `pitch` | `number` | Начальный наклон камеры (нужен для 3D-вида). |
153
- | `bearing` | `number` | Начальный поворот камеры. |
154
- | `autoAddVectorSource` | `boolean` | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`. |
155
- | `engine` | `"legacy" \| "3d"` | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
156
- | `enable3D` | `boolean` | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. |
157
- | `base` | `string` | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`. |
158
- | `preset` | `string` | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`. |
159
- | `maps3d` | `object` | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
144
+ | Параметр | Тип | Описание |
145
+ | --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146
+ | `container` | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`. |
147
+ | `style` | `string` | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля. |
148
+ | `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`. |
149
+ | `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`. |
150
+ | `center` | `[number, number]` | Центр карты в формате `[lng, lat]`. |
151
+ | `zoom` | `number` | Начальный zoom. |
152
+ | `pitch` | `number` | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
153
+ | `bearing` | `number` | Начальный поворот камеры. |
154
+ | `autoAddVectorSource` | `boolean` | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`. |
155
+ | `engine` | `"legacy" \| "3d"` | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
156
+ | `enable3D` | `boolean` | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить. |
157
+ | `base` | `string` | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`. |
158
+ | `preset` | `string` | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`. |
159
+ | `maps3d` | `object` | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
160
160
 
161
161
  ### Новый 3D-движок (GramMaps / Maps3D)
162
162
 
@@ -201,32 +201,38 @@ MahalMap.getMaps3DLayer(map);
201
201
 
202
202
  Передаются в `MahalMap.create({ maps3d: {...} })` при `engine: "3d"`:
203
203
 
204
- | Опция | Тип | По умолч. | Описание |
205
- | --- | --- | --- | --- |
206
- | `traffic` | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false` | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
207
- | `minZoom` | `number` | `16` | Зум появления детальных 3D. |
208
- | `lodBias` | `number` | `1` | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах. |
209
- | `memoryBudget` | `number` | `30` | Сколько моделей держать в сцене одновременно. |
210
- | `maskReplaced` | `boolean` | `true` | Прятать заменённые OSM-объекты (`anchor=replace`). |
211
- | `typeReplacements` | `boolean` | `true` | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.). |
204
+ | Опция | Тип | По умолч. | Описание |
205
+ | ------------------ | ------------------------------------------------ | --------- | ------------------------------------------------------------------------- |
206
+ | `traffic` | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false` | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
207
+ | `minZoom` | `number` | `16` | Зум появления детальных 3D. |
208
+ | `lodBias` | `number` | `1` | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах. |
209
+ | `memoryBudget` | `number` | `30` | Сколько моделей держать в сцене одновременно. |
210
+ | `maskReplaced` | `boolean` | `true` | Прятать заменённые OSM-объекты (`anchor=replace`). |
211
+ | `typeReplacements` | `boolean` | `true` | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.). |
212
212
 
213
213
  `buildings: true` включается автоматически при `enable3D: true` — переопределять не нужно, если только не требуется передать сам объект опций.
214
214
 
215
215
  ### 3D-здания
216
216
 
217
+ `Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс:
218
+
219
+ ```ts
220
+ const layer = new Maps3D({ apiKey, base, buildings: true });
221
+ await layer.attach(map); // attach асинхронный, дожидается load карты сам
222
+ ```
223
+
217
224
  Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её:
218
225
 
219
226
  ```ts
220
227
  const layer = map.getMaps3DLayer();
221
228
 
222
- layer?.setBuildingsEnabled(false); // 3D-здания ⇄ штатные здания стиля
223
-
224
229
  const b = layer?.buildings;
225
230
  b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
226
- b?.setWindowDepth(0.85);
231
+ b?.setWindowDepth(0.85); // глубина ниши окна 0..1 (реальная геометрия вблизи)
227
232
  b?.setWindowColor("#6b9ed1");
228
233
  b?.setWindowFrameColor("#f2f2f4");
229
- b?.setEdgeRadius(1.2);
234
+ b?.setEdgeRadius(1.2); // скругление кромок, м
235
+ // Свет обычно НЕ задают руками — его несёт metadata стиля, сеттеры её перебивают
230
236
  b?.setSunIntensity(3.2);
231
237
  b?.setAmbient(0.76);
232
238
  b?.setSky(0.91);
@@ -238,6 +244,26 @@ layer?.onBuildingClick((info) => {
238
244
  });
239
245
  ```
240
246
 
247
+ #### Вкл/выкл 3D-здания на лету
248
+
249
+ Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты:
250
+
251
+ ```ts
252
+ layer?.setBuildingsEnabled(false); // напрямую через слой
253
+ ```
254
+
255
+ Либо через обёртку `MahalMap` — она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
256
+
257
+ ```ts
258
+ const map = MahalMap.getInstance("map");
259
+
260
+ map.toggle3DBuildings(false); // выкл
261
+ map.toggle3DBuildings(true); // вкл обратно
262
+
263
+ // статик-версия и SDK-фасад (mahal_map/sdk) работают так же
264
+ MahalMap.toggle3DBuildings(map, false);
265
+ ```
266
+
241
267
  ### Пробки
242
268
 
243
269
  ```ts
@@ -259,9 +285,9 @@ const layer = map.getMaps3DLayer();
259
285
 
260
286
  layer?.setMinZoom(15);
261
287
  layer?.setObjectsLight({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
262
- await layer?.refresh(); // перечитать модели после правок
263
- await layer?.clearCache(); // сбросить IndexedDB-кеш ассетов
264
- layer?.destroy?.(); // отцепить слой (также вызывается автоматически в map.destroy())
288
+ await layer?.refresh(); // перечитать модели после правок
289
+ await layer?.clearCache(); // сбросить IndexedDB-кеш ассетов
290
+ layer?.destroy?.(); // отцепить слой (также вызывается автоматически в map.destroy())
265
291
  ```
266
292
 
267
293
  `map.destroy()` / `MahalMap.destroy(map)` сами вызывают `destroy()`/`remove()` у Maps3D слоя, если он был подключен — отдельно чистить не нужно.
@@ -469,6 +495,8 @@ MahalMap.setLanguage(map, "ru");
469
495
  MahalMap.setCenter(map, [69.624024, 40.279687]);
470
496
  MahalMap.setZoom(map, 14);
471
497
  MahalMap.addMarker(map, marker);
498
+ MahalMap.getMaps3DLayer(map);
499
+ MahalMap.toggle3DBuildings(map, false);
472
500
  MahalMap.destroy(map);
473
501
  ```
474
502
 
@@ -492,23 +520,25 @@ MahalMap.setZoom(map, 14);
492
520
 
493
521
  Доступные функции карты в browser SDK:
494
522
 
495
- | Функция | Описание |
496
- | ------------------------------ | -------------------------------------------------- |
497
- | `create(options)` | Создает карту. Требует `apikey` в URL SDK скрипта. |
498
- | `onReady(container, callback)` | Выполняет callback после загрузки карты. |
499
- | `getInstance(container)` | Возвращает инстанс карты. |
500
- | `hasInstance(container)` | Проверяет наличие инстанса. |
501
- | `removeInstance(container)` | Удаляет инстанс из реестра. |
502
- | `getMap(instance)` | Возвращает нативный MapLibre Map. |
503
- | `getCamera(instance)` | Возвращает CameraController. |
504
- | `setStyle(instance, theme)` | Переключает тему стандартного стиля. |
505
- | `setLanguage(instance, lang)` | Переключает язык стандартного стиля. |
506
- | `setCenter(instance, center)` | Меняет центр карты. |
507
- | `setZoom(instance, zoom)` | Меняет zoom карты. |
508
- | `addMarker(instance, marker)` | Добавляет маркер. |
509
- | `destroy(instance)` | Полностью удаляет карту. |
510
- | `loadKeyFromScriptUrl()` | Читает `apikey` из URL SDK скрипта. |
511
- | `loadLanguageFromScriptUrl()` | Читает `lang` из URL SDK скрипта. |
523
+ | Функция | Описание |
524
+ | -------------------------------------- | ------------------------------------------------------------- |
525
+ | `create(options)` | Создает карту. Требует `apikey` в URL SDK скрипта. |
526
+ | `onReady(container, callback)` | Выполняет callback после загрузки карты. |
527
+ | `getInstance(container)` | Возвращает инстанс карты. |
528
+ | `hasInstance(container)` | Проверяет наличие инстанса. |
529
+ | `removeInstance(container)` | Удаляет инстанс из реестра. |
530
+ | `getMap(instance)` | Возвращает нативный MapLibre Map. |
531
+ | `getCamera(instance)` | Возвращает CameraController. |
532
+ | `setStyle(instance, theme)` | Переключает тему стандартного стиля. |
533
+ | `setLanguage(instance, lang)` | Переключает язык стандартного стиля. |
534
+ | `setCenter(instance, center)` | Меняет центр карты. |
535
+ | `setZoom(instance, zoom)` | Меняет zoom карты. |
536
+ | `addMarker(instance, marker)` | Добавляет маркер. |
537
+ | `getMaps3DLayer(instance)` | Возвращает инстанс слоя Maps3D (только `engine: "3d"`). |
538
+ | `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
539
+ | `destroy(instance)` | Полностью удаляет карту. |
540
+ | `loadKeyFromScriptUrl()` | Читает `apikey` из URL SDK скрипта. |
541
+ | `loadLanguageFromScriptUrl()` | Читает `lang` из URL SDK скрипта. |
512
542
 
513
543
  ## CameraController
514
544
 
@@ -711,9 +741,10 @@ measureTool.start("distance");
711
741
  MapLibre GL проверяет `paint`-свойства слоя и не понимает `var(--primary)` — только hex/rgb. Если в приложении цвета живут в CSS-переменных (тема light/dark), резолвьте их в реальное значение перед передачей в `style`:
712
742
 
713
743
  ```ts
714
- const primary = getComputedStyle(document.documentElement)
715
- .getPropertyValue("--primary")
716
- .trim() || "#278960";
744
+ const primary =
745
+ getComputedStyle(document.documentElement)
746
+ .getPropertyValue("--primary")
747
+ .trim() || "#278960";
717
748
 
718
749
  const measureTool = new MeasureTool(map, {
719
750
  style: { lineColor: primary, pointStrokeColor: primary, fillColor: primary },
@@ -724,29 +755,29 @@ const measureTool = new MeasureTool(map, {
724
755
 
725
756
  ### Конструктор: `new MeasureTool(map, options?)`
726
757
 
727
- | Опция | Тип | Описание |
728
- | ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
729
- | `mode` | `"distance" \| "area"` | Режим по умолчанию. По умолчанию `"distance"`. |
730
- | `sourceIdPrefix` | `string` | Префикс id source/layer на карте. По умолчанию генерируется уникальный (`"mahal-measure-1"`, `"mahal-measure-2"`, ...) — так несколько инструментов на одной карте не конфликтуют. Задайте явно, если нужен предсказуемый id. |
731
- | `style` | `MeasureStyleOptions` | Цвета и размеры точек/линий/заливки/бейджа. |
732
- | `icons` | `MeasureIcons` | SVG-иконки `trash` / `close` / `check` для бейджей. |
733
- | `labels` | `MeasureLabels` | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`. |
734
- | `onChange` | `(state: MeasureState) => void` | Вызывается при любом изменении: новая точка, drag, смена режима и т.д. |
735
- | `onCloseRequest` | `() => void` | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением. |
758
+ | Опция | Тип | Описание |
759
+ | ---------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
760
+ | `mode` | `"distance" \| "area"` | Режим по умолчанию. По умолчанию `"distance"`. |
761
+ | `sourceIdPrefix` | `string` | Префикс id source/layer на карте. По умолчанию генерируется уникальный (`"mahal-measure-1"`, `"mahal-measure-2"`, ...) — так несколько инструментов на одной карте не конфликтуют. Задайте явно, если нужен предсказуемый id. |
762
+ | `style` | `MeasureStyleOptions` | Цвета и размеры точек/линий/заливки/бейджа. |
763
+ | `icons` | `MeasureIcons` | SVG-иконки `trash` / `close` / `check` для бейджей. |
764
+ | `labels` | `MeasureLabels` | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`. |
765
+ | `onChange` | `(state: MeasureState) => void` | Вызывается при любом изменении: новая точка, drag, смена режима и т.д. |
766
+ | `onCloseRequest` | `() => void` | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением. |
736
767
 
737
768
  ### Методы
738
769
 
739
- | Метод | Описание |
740
- | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
741
- | `start(mode?)` | Включает инструмент и начинает/продолжает рисование в указанном режиме. |
742
- | `stop()` | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте. |
743
- | `setMode(mode)` | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах. |
744
- | `finishDraft()` | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую. |
745
- | `removeShape(shapeId)` | Удаляет фигуру (черновик или уже сохраненную) целиком. |
746
- | `removePoint(shapeId, pointId)` | Удаляет одну точку фигуры. |
747
- | `clearAll()` | Удаляет все фигуры и черновик. |
748
- | `getState()` | Возвращает текущий `MeasureState` (снимок, без подписки). |
749
- | `destroy()` | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании. |
770
+ | Метод | Описание |
771
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
772
+ | `start(mode?)` | Включает инструмент и начинает/продолжает рисование в указанном режиме. |
773
+ | `stop()` | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте. |
774
+ | `setMode(mode)` | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах. |
775
+ | `finishDraft()` | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую. |
776
+ | `removeShape(shapeId)` | Удаляет фигуру (черновик или уже сохраненную) целиком. |
777
+ | `removePoint(shapeId, pointId)` | Удаляет одну точку фигуры. |
778
+ | `clearAll()` | Удаляет все фигуры и черновик. |
779
+ | `getState()` | Возвращает текущий `MeasureState` (снимок, без подписки). |
780
+ | `destroy()` | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании. |
750
781
 
751
782
  ### Взаимодействие на карте
752
783
 
package/dist/index.d.mts CHANGED
@@ -36,10 +36,13 @@ interface IMaps3DLayerOptions {
36
36
  typeReplacements?: boolean;
37
37
  }
38
38
  interface IMaps3DBuildingsController {
39
+ setWindows?(enabled: boolean): void;
40
+ setWindowMinZoom?(zoom: number): void;
39
41
  setWindowStyle(style: number): void;
40
42
  setWindowDepth(depth: number): void;
41
43
  setWindowColor(color: string): void;
42
44
  setWindowFrameColor(color: string): void;
45
+ setWindowGlow?(value: number): void;
43
46
  setEdgeRadius(radius: number): void;
44
47
  setSunIntensity(value: number): void;
45
48
  setAmbient(value: number): void;
@@ -230,6 +233,9 @@ declare class MahalMap {
230
233
  private presetIsExplicit;
231
234
  private maps3dCtor?;
232
235
  private maps3dLayer?;
236
+ private maps3dLayerReady;
237
+ private maps3dLayerAttachPending;
238
+ private buildingsEnabled;
233
239
  private constructor();
234
240
  private static getInstanceKey;
235
241
  private static normalizeLanguage;
@@ -262,6 +268,14 @@ declare class MahalMap {
262
268
  getMaps3DLayer(): IMaps3DLayer | undefined;
263
269
  /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
264
270
  toggle3DBuildings(enabled: boolean): void;
271
+ private attachMaps3DLayer;
272
+ private applyMaps3DBuildingMode;
273
+ /**
274
+ * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
275
+ * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
276
+ * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
277
+ */
278
+ private setNativeBuildingsVisible;
265
279
  setCenter(center: [number, number]): void;
266
280
  setZoom(zoom: number): void;
267
281
  destroy(): void;
package/dist/index.d.ts CHANGED
@@ -36,10 +36,13 @@ interface IMaps3DLayerOptions {
36
36
  typeReplacements?: boolean;
37
37
  }
38
38
  interface IMaps3DBuildingsController {
39
+ setWindows?(enabled: boolean): void;
40
+ setWindowMinZoom?(zoom: number): void;
39
41
  setWindowStyle(style: number): void;
40
42
  setWindowDepth(depth: number): void;
41
43
  setWindowColor(color: string): void;
42
44
  setWindowFrameColor(color: string): void;
45
+ setWindowGlow?(value: number): void;
43
46
  setEdgeRadius(radius: number): void;
44
47
  setSunIntensity(value: number): void;
45
48
  setAmbient(value: number): void;
@@ -230,6 +233,9 @@ declare class MahalMap {
230
233
  private presetIsExplicit;
231
234
  private maps3dCtor?;
232
235
  private maps3dLayer?;
236
+ private maps3dLayerReady;
237
+ private maps3dLayerAttachPending;
238
+ private buildingsEnabled;
233
239
  private constructor();
234
240
  private static getInstanceKey;
235
241
  private static normalizeLanguage;
@@ -262,6 +268,14 @@ declare class MahalMap {
262
268
  getMaps3DLayer(): IMaps3DLayer | undefined;
263
269
  /** Вкл/выкл детальные 3D-здания (Maps3D). Работает только для engine: "3d". */
264
270
  toggle3DBuildings(enabled: boolean): void;
271
+ private attachMaps3DLayer;
272
+ private applyMaps3DBuildingMode;
273
+ /**
274
+ * Прячет/показывает нативные здания стиля GramMaps ("building-3d" и любые fill-extrusion /
275
+ * fill+source-layer=building), не задевая слои самого Maps3D. Нужно, иначе плоский слой стиля
276
+ * рисуется поверх процедурных 3D-зданий и визуально их перекрывает.
277
+ */
278
+ private setNativeBuildingsVisible;
265
279
  setCenter(center: [number, number]): void;
266
280
  setZoom(zoom: number): void;
267
281
  destroy(): void;