mahal_map 1.6.12 → 1.6.14

package/README.md

@@ -12,6 +12,28 @@ npm install mahal_map maplibre-gl
 
 `maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
 
+Для нового 3D-движка (`engine: "3d"`) дополнительно нужен `@osm/maps3d-web`. Пакет **не публикуется в npm** — скачайте его со страницы платформы (кнопка «Web SDK — стартер»; в Vue-стартере это папка `libs/maps3d-web` с уже собранным `dist/`), положите в проект и поставьте как локальную зависимость:
+
+```sh
+npm i ./libs/maps3d-web maplibre-gl
+```
+
+`package.json` запишет ссылку на локальную папку:
+
+```json
+"@osm/maps3d-web": "file:./libs/maps3d-web"
+```
+
+Без сборщика возьмите `lib/maps3d.global.js` из скачанного стартера (IIFE-глобал `Maps3D`, three бандлится внутрь) и подключите скриптом после `maplibre-gl`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
+<script src="./lib/maps3d.global.js"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+```
+
+SDK сам найдёт конструктор в `window.Maps3D.Maps3D` — передавать его вручную не нужно.
+
 ## Быстрый старт через NPM
 
 ```ts
@@ -100,7 +122,14 @@ interface IMahalMapOptions {
   lang?: "tj" | "ru";
   center?: [number, number];
   zoom?: number;
+  pitch?: number;
+  bearing?: number;
   autoAddVectorSource?: boolean;
+  engine?: "legacy" | "3d";
+  enable3D?: boolean;
+  base?: string;
+  preset?: string;
+  maps3d?: IMaps3DOptions;
 }
 ```
 
@@ -112,7 +141,51 @@ interface IMahalMapOptions {
 | `lang`                | `"tj" \| "ru"`          | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.             |
 | `center`              | `[number, number]`      | Центр карты в формате `[lng, lat]`.                                                                 |
 | `zoom`                | `number`                | Начальный zoom.                                                                                     |
+| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида).                                                        |
+| `bearing`             | `number`                | Начальный поворот камеры.                                                                           |
 | `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.           |
+| `engine`               | `"legacy" \| "3d"`     | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (route.gram.tj) с пресетами стиля и Maps3D. |
+| `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`.                        |
+| `base`                 | `string`               | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://route.gram.tj`.                  |
+| `preset`               | `string`               | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `standard-day`/`standard-night` в зависимости от `theme`. |
+| `maps3d`               | `object`               | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
+
+### Новый 3D-движок (GramMaps / Maps3D)
+
+Токен передается как обычно, через `keyUtils.saveKey()` — отдельно ключ для Maps3D передавать не нужно.
+
+```ts
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@osm/maps3d-web";
+import { MahalMap, keyUtils } from "mahal_map";
+
+keyUtils.saveKey("YOUR_MAP_API_KEY");
+
+const map = MahalMap.create(
+  {
+    container: "map",
+    center: [68.78, 38.56],
+    zoom: 16.6,
+    pitch: 58,
+    theme: "dark",
+    engine: "3d",
+    enable3D: true,
+  },
+  maplibregl,
+  Maps3D,
+);
+```
+
+`Maps3D` (третий аргумент `create()`) — опционален: если не передан, SDK попробует взять его из `window.Maps3D`. `@osm/maps3d-web` — необязательный peer dependency, ставится только если используется `engine: "3d"`.
+
+Получить слой Maps3D после создания карты:
+
+```ts
+const layer = map.getMaps3DLayer();
+// или
+MahalMap.getMaps3DLayer(map);
+```
 
 ## MahalMap
 

package/dist/index.d.mts

@@ -19,6 +19,31 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+interface IMaps3DLayerOptions {
+    apiKey?: string | null;
+    base?: string;
+    buildings?: boolean | Record<string, unknown>;
+    traffic?: boolean | Record<string, unknown>;
+    minZoom?: number;
+    lodBias?: number;
+    memoryBudget?: number;
+    maskReplaced?: boolean;
+    typeReplacements?: boolean;
+}
+interface IMaps3DLayer {
+    attach(map: Map): void;
+    destroy?(): void;
+    remove?(): void;
+}
+interface IMaps3DTransformRequestOptions {
+    base: string;
+    apiKey?: string | null;
+}
+type Maps3DTransformRequest = (options: IMaps3DTransformRequestOptions) => unknown;
+type Maps3DCtor = (new (options: IMaps3DLayerOptions) => IMaps3DLayer) & {
+    transformRequest: Maps3DTransformRequest;
+};
+
 interface IMahalMapOptions {
     container?: string | HTMLElement;
     style?: string;
@@ -26,10 +51,23 @@ interface IMahalMapOptions {
     lang?: MapLanguage;
     center?: [number, number];
     zoom?: number;
+    pitch?: number;
+    bearing?: number;
     autoAddVectorSource?: boolean;
+    /** "legacy" (default) — старый движок (mtile.gram.tj). "3d" — новый GramMaps движок (route.gram.tj) с поддержкой Maps3D. */
+    engine?: MapEngine;
+    /** Включает Maps3D слой (детальные 3D-здания). Работает только при engine: "3d". */
+    enable3D?: boolean;
+    /** Домен платформы GramMaps для engine: "3d". По умолчанию https://route.gram.tj */
+    base?: string;
+    /** Имя пресета стиля GramMaps (напр. "standard-night") для engine: "3d". */
+    preset?: string;
+    /** Доп. опции Maps3D слоя (buildings, traffic, minZoom, lodBias, memoryBudget, ...). */
+    maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
 }
 type Theme = "dark" | "light";
 type MapLanguage = "tj" | "ru";
+type MapEngine = "legacy" | "3d";
 
 interface MahalMapDefaultMarkerProps {
     coordinates: [number, number];
@@ -144,6 +182,12 @@ declare class MahalMap {
     private options;
     private language;
     private instanceKey;
+    private engine;
+    private gramBase;
+    private gramPreset;
+    private presetIsExplicit;
+    private maps3dCtor?;
+    private maps3dLayer?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -151,7 +195,8 @@ declare class MahalMap {
     private static getDefaultStyle;
     private static getVectorStyle;
     private static getMapToken;
-    static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi): MahalMap;
+    private static getMaps3DCtor;
+    static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi, maps3dCtor?: Maps3DCtor): MahalMap;
     static onReady(container: string, callback: (map: Map) => void): void;
     static getInstance(container: string): MahalMap;
     static hasInstance(container: string): boolean;
@@ -160,6 +205,7 @@ declare class MahalMap {
     static getCamera(instance: MahalMap): CameraController;
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
+    static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -170,6 +216,7 @@ declare class MahalMap {
     getMap(): Map;
     setStyle(theme: Theme): void;
     setLanguage(lang: MapLanguage): void;
+    getMaps3DLayer(): IMaps3DLayer | undefined;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;
@@ -349,7 +396,6 @@ declare class MeasureTool {
     private setCursor;
     private onStyleLoad;
     private emitChange;
-    private tryEnsureLayers;
     private ensureLayers;
     private removeLayers;
     private setSourceData;
@@ -426,4 +472,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 { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapLanguage, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DLayer, type IMaps3DLayerOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };

package/dist/index.d.ts

@@ -19,6 +19,31 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+interface IMaps3DLayerOptions {
+    apiKey?: string | null;
+    base?: string;
+    buildings?: boolean | Record<string, unknown>;
+    traffic?: boolean | Record<string, unknown>;
+    minZoom?: number;
+    lodBias?: number;
+    memoryBudget?: number;
+    maskReplaced?: boolean;
+    typeReplacements?: boolean;
+}
+interface IMaps3DLayer {
+    attach(map: Map): void;
+    destroy?(): void;
+    remove?(): void;
+}
+interface IMaps3DTransformRequestOptions {
+    base: string;
+    apiKey?: string | null;
+}
+type Maps3DTransformRequest = (options: IMaps3DTransformRequestOptions) => unknown;
+type Maps3DCtor = (new (options: IMaps3DLayerOptions) => IMaps3DLayer) & {
+    transformRequest: Maps3DTransformRequest;
+};
+
 interface IMahalMapOptions {
     container?: string | HTMLElement;
     style?: string;
@@ -26,10 +51,23 @@ interface IMahalMapOptions {
     lang?: MapLanguage;
     center?: [number, number];
     zoom?: number;
+    pitch?: number;
+    bearing?: number;
     autoAddVectorSource?: boolean;
+    /** "legacy" (default) — старый движок (mtile.gram.tj). "3d" — новый GramMaps движок (route.gram.tj) с поддержкой Maps3D. */
+    engine?: MapEngine;
+    /** Включает Maps3D слой (детальные 3D-здания). Работает только при engine: "3d". */
+    enable3D?: boolean;
+    /** Домен платформы GramMaps для engine: "3d". По умолчанию https://route.gram.tj */
+    base?: string;
+    /** Имя пресета стиля GramMaps (напр. "standard-night") для engine: "3d". */
+    preset?: string;
+    /** Доп. опции Maps3D слоя (buildings, traffic, minZoom, lodBias, memoryBudget, ...). */
+    maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
 }
 type Theme = "dark" | "light";
 type MapLanguage = "tj" | "ru";
+type MapEngine = "legacy" | "3d";
 
 interface MahalMapDefaultMarkerProps {
     coordinates: [number, number];
@@ -144,6 +182,12 @@ declare class MahalMap {
     private options;
     private language;
     private instanceKey;
+    private engine;
+    private gramBase;
+    private gramPreset;
+    private presetIsExplicit;
+    private maps3dCtor?;
+    private maps3dLayer?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -151,7 +195,8 @@ declare class MahalMap {
     private static getDefaultStyle;
     private static getVectorStyle;
     private static getMapToken;
-    static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi): MahalMap;
+    private static getMaps3DCtor;
+    static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi, maps3dCtor?: Maps3DCtor): MahalMap;
     static onReady(container: string, callback: (map: Map) => void): void;
     static getInstance(container: string): MahalMap;
     static hasInstance(container: string): boolean;
@@ -160,6 +205,7 @@ declare class MahalMap {
     static getCamera(instance: MahalMap): CameraController;
     static getMap(instance: MahalMap): Map;
     static setStyle(instance: MahalMap, theme: Theme): void;
+    static getMaps3DLayer(instance: MahalMap): IMaps3DLayer | undefined;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -170,6 +216,7 @@ declare class MahalMap {
     getMap(): Map;
     setStyle(theme: Theme): void;
     setLanguage(lang: MapLanguage): void;
+    getMaps3DLayer(): IMaps3DLayer | undefined;
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;
@@ -349,7 +396,6 @@ declare class MeasureTool {
     private setCursor;
     private onStyleLoad;
     private emitChange;
-    private tryEnsureLayers;
     private ensureLayers;
     private removeLayers;
     private setSourceData;
@@ -426,4 +472,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 { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapLanguage, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DLayer, type IMaps3DLayerOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };