mahal_map 2.2.2 → 2.3.0

package/dist/index.d.mts

@@ -23,7 +23,7 @@ interface IAdditionalParamType {
 /**
  * Поверхность @grammaps/maps3d-web, описанная локально. Пакет в зависимости не ставится —
  * он приходит снаружи, как и maplibre-gl, поэтому импортировать его типы нельзя. Здесь
- * повторена публичная часть .d.ts версии 0.10.0; всё необязательное помечено `?`, чтобы
+ * повторена публичная часть .d.ts версии 0.11.0; всё необязательное помечено `?`, чтобы
  * более старая сборка на странице не ломала типы у потребителя.
  */
 type Maps3DThemeName = "light" | "dark" | "navigator-light" | "navigator-dark" | "mobile-light" | "mobile-dark";
@@ -97,8 +97,26 @@ interface IMaps3DLayerState {
      * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
      */
     rendered?: boolean;
-    /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
-    params: Record<string, unknown>;
+    /** Параметры слоя: у зданий — detail, у этажей — level и levels, у рельефа — mode. */
+    params: IMaps3DLayerStateParams;
+}
+/**
+ * Параметры в снимке слоя. Каждое поле есть только у своего слоя; неизвестные ключи
+ * сборки Maps3D проходят через индексную сигнатуру.
+ */
+interface IMaps3DLayerStateParams {
+    /** `buildings`: уровень детализации. */
+    detail?: Maps3DBuildingDetail;
+    /** `indoor`: открытый этаж. */
+    level?: number;
+    /**
+     * `indoor`: этажи, найденные в текущем виде карты; `[]` — данных по зданию нет.
+     * Меняется при движении карты и приходит через onLayers(). С 0.11.0, раньше — undefined.
+     */
+    levels?: number[];
+    /** `terrain`: режим рельефа. */
+    mode?: Maps3DTerrainMode;
+    [key: string]: unknown;
 }
 interface IMaps3DSelectionStyle {
     color?: string | number;
@@ -232,12 +250,16 @@ interface IMaps3DBuildingClickInfo {
     id: string | number;
     /**
      * Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется.
-     * Необязательно: peerDependency допускает сборки Maps3D от 0.5.0, где поля может не быть.
+     * Необязательно: запасные пути держат сборки Maps3D от 0.5.0, где поля может не быть.
      */
     props?: Record<string, unknown>;
     /** Высота здания в метрах. Необязательно по той же причине, что и `props`. */
     height?: number;
-    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
+    /**
+     * Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии.
+     * `>= 0` — объёмный дом сцены, `-1` — дом из слоя стиля (объёма под ним нет).
+     * Тот же признак, что selectedBuildingKind(): `'scene'` / `'flat'`.
+     */
     index?: number;
     [key: string]: unknown;
 }
@@ -247,6 +269,10 @@ interface IMaps3DObjectsLightOptions {
     sky?: number;
     exposure?: number;
 }
+/** Чем нарисовано выделение: объёмный дом сцены или слой стиля. С 0.11.0. */
+type Maps3DSelectionKind = "scene" | "flat";
+/** Колбэк подписки Maps3D: `null` вместо функции — отписаться. */
+type Maps3DListener<T> = ((info: T | null) => void) | null;
 interface IMaps3DDiagnostics {
     terrainActive: boolean;
     drapeRefreshes: number;
@@ -266,18 +292,20 @@ interface IMaps3DLayer {
     refreshLayers?(): void;
     buildings?: IMaps3DBuildingsController | null;
     setBuildingsEnabled?(enabled: boolean): void;
-    onBuildingClick?(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    onBuildingClick?(callback: Maps3DListener<IMaps3DBuildingClickInfo>): (() => void) | void;
     selectBuilding?(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
+    /** С 0.11.0. */
+    selectedBuildingKind?(): Maps3DSelectionKind | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
-    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    onBuildingHover?(callback: Maps3DListener<IMaps3DBuildingClickInfo>): (() => void) | void;
     setHoverEnabled?(enabled: boolean): void;
     readonly hoverEnabled?: boolean;
     setHoverStyle?(style: IMaps3DHoverStyle): void;
     hoverBuilding?(id: number | string | null): boolean;
     hoveredBuilding?(): number | string | null;
-    onRoadClick?(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    onRoadClick?(callback: Maps3DListener<IMaps3DRoadHit>): (() => void) | void;
     roadAt?(point: {
         x: number;
         y: number;
@@ -287,13 +315,13 @@ interface IMaps3DLayer {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DParkingInfo | null;
-    onParkingHover?(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingHover?(callback: Maps3DListener<IMaps3DParkingInfo>): (() => void) | void;
     setParkingHoverStyle?(style: IMaps3DParkingHoverStyle): void;
     setParkingHoverEnabled?(enabled: boolean): void;
     readonly parkingHoverEnabled?: boolean;
     hoverParking?(id: number | string | null): boolean;
     hoveredParking?(): number | string | null;
-    onParkingClick?(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingClick?(callback: Maps3DListener<IMaps3DParkingInfo>): (() => void) | void;
     traffic?: boolean;
     trafficRaster?: boolean;
     setTraffic?(enabled: boolean): void;
@@ -304,6 +332,7 @@ interface IMaps3DLayer {
     refreshTraffic?(): void;
     setIndoor?(enabled: boolean): void;
     setIndoorLevel?(level: number): void;
+    /** Запасной путь для сборок до 0.11.0 — там этажей нет в `layer("indoor").params.levels`. */
     readonly indoorLevels?: number[];
     refreshIndoor?(): void;
     showPlace?(lon: number, lat: number, level?: number | null, zoom?: number): void;
@@ -469,31 +498,52 @@ interface ISearchByLocationParam {
     token: string;
     type?: string;
 }
+/**
+ * Тип объекта в ответе геокодера. Регистр у сервиса плавает: обратный геокодинг отдаёт
+ * `"Address"`, прямой — `"address"`. Сравнивайте через `type.toLowerCase()`.
+ */
+type SearchResultType = "poi" | "locality" | "address" | "Address" | (string & {});
+/** Адрес объекта. Любое поле может отсутствовать — сервис отдаёт только то, что знает. */
+interface ISearchDetailAddress {
+    /** Область: `вилоят`, `Суғд`. */
+    subject_type?: string;
+    subject_name?: string;
+    /** Город: `шаҳр`, `Хуҷанд`. Так город приходит в обратном геокодинге. */
+    city_type?: string;
+    city?: string;
+    /** Район / ноҳия. */
+    region_type?: string;
+    region?: string;
+    /** Населённый пункт — встречается в ответах вместо `city`. */
+    settlement_type?: string;
+    settlement?: string;
+    /** Посёлок / махалля. */
+    village_type?: string;
+    village?: string;
+    /** Улица: `кӯчаи`, `Камоли Хуҷандӣ`. */
+    street_type?: string;
+    street_name?: string;
+    /** Номер дома. У многих POI его нет. */
+    number?: string;
+}
+interface ISearchDetailInfo {
+    name?: string;
+    short_name?: string;
+    categories?: string;
+    translate_ru?: string;
+    description?: string;
+    phone?: string;
+    website?: string;
+}
 interface ISearchResponse {
     latitude: number;
     longitude: number;
-    type: "poi" | "locality" | "address";
+    type: SearchResultType;
+    /** Расстояние от точки запроса в метрах (обратный геокодинг). */
     distance: number | null;
-    detailInfo: {
-        name?: string;
-        short_name?: string;
-        categories?: string;
-        translate_ru?: string;
-        description?: string;
-    } | null;
-    detailAddress: {
-        subject_type?: string;
-        subject_name?: string;
-        region_type?: string;
-        region?: string;
-        settlement_type?: string;
-        settlement?: string;
-        village_type?: string;
-        village?: string;
-        street_type?: string;
-        street_name?: string;
-        number: string;
-    } | [];
+    detailInfo: ISearchDetailInfo | null;
+    /** Пустой массив — адрес неизвестен. */
+    detailAddress: ISearchDetailAddress | [];
 }
 interface ICheckJSApiParam {
     token: string;
@@ -539,11 +589,9 @@ declare class MahalMap {
     private buildingsEnabled;
     private workerCheckTimer?;
     private styleChangeHandler?;
-    private pendingBuildingClick?;
-    private pendingRoadClick?;
+    private subscriptions;
     private pendingSelectionStyle?;
     private pendingLayerSubscribers;
-    private pendingBuildingHover?;
     private pendingHoverStyle?;
     private pendingHoverEnabled?;
     private constructor();
@@ -608,27 +656,29 @@ declare class MahalMap {
     static setIndoorLevel(instance: MahalMap, level: number): void;
     static refreshIndoor(instance: MahalMap): void;
     static showPlace(instance: MahalMap, lon: number, lat: number, level?: number | null, zoom?: number): void;
-    static onBuildingClick(instance: MahalMap, callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    static onBuildingClick(instance: MahalMap, callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     static selectBuilding(instance: MahalMap, id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     static clearSelection(instance: MahalMap): void;
     static selectedBuilding(instance: MahalMap): string | number | null;
+    static selectedBuildingKind(instance: MahalMap): Maps3DSelectionKind | null;
+    static getBuildingsMinZoom(instance: MahalMap): number;
     static setSelectionStyle(instance: MahalMap, style: IMaps3DSelectionStyle): void;
-    static onRoadClick(instance: MahalMap, callback: (hit: IMaps3DRoadHit | null) => void): void;
+    static onRoadClick(instance: MahalMap, callback: Maps3DListener<IMaps3DRoadHit>): () => void;
     static roadAt(instance: MahalMap, point: {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
-    static onParkingHover(instance: MahalMap, callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    static onParkingHover(instance: MahalMap, callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     static setParkingHoverStyle(instance: MahalMap, style: IMaps3DParkingHoverStyle): void;
     static setParkingHoverEnabled(instance: MahalMap, enabled: boolean): void;
     static hoverParking(instance: MahalMap, id: number | string | null): boolean;
     static hoveredParking(instance: MahalMap): string | number | null;
-    static onParkingClick(instance: MahalMap, callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    static onParkingClick(instance: MahalMap, callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     static parkingAt(instance: MahalMap, point: {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DParkingInfo | null;
-    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static onBuildingHover(instance: MahalMap, callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
     static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
     static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
@@ -699,7 +749,11 @@ declare class MahalMap {
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
-    /** Этажи, найденные в текущем виде карты. Пусто — данных по зданию нет. */
+    /**
+     * Этажи, найденные в текущем виде карты. Пусто — данных по зданию нет.
+     * С 0.11.0 они же приходят в onLayers() у слоя `indoor` (`params.levels`) — опрашивать
+     * этот метод на движении карты больше не нужно.
+     */
     getIndoorLevels(): number[];
     /** Переключить этаж. Нумерация OSM: 0 — первый наземный. */
     setIndoorLevel(level: number): void;
@@ -712,21 +766,32 @@ declare class MahalMap {
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
     /**
-     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Клик по зданию: { id, height, props, index } либо null. `index >= 0` — объёмный дом
+     * сцены, `-1` — дом из слоя стиля. Повторный вызов заменяет обработчик, `null` — отписка.
+     *
      * Подписываться можно сразу после create(), даже когда слой ещё не поднят
      * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     *
+     * @returns Отписка. Снимает только эту подписку: если обработчик уже заменён
+     * следующим вызовом, ничего не делает.
      */
-    onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    onBuildingClick(callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
     selectBuilding(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection(): void;
     selectedBuilding(): number | string | null;
+    /**
+     * Чем нарисовано выделение: `'scene'` — объёмный дом сцены, `'flat'` — слой стиля,
+     * `null` — выделения нет. На сборке Maps3D до 0.11.0 всегда `null`.
+     */
+    selectedBuildingKind(): Maps3DSelectionKind | null;
     setSelectionStyle(style: IMaps3DSelectionStyle): void;
     /**
      * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
-     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки, принимает `null`
+     * и возвращает отписку.
      */
-    onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    onRoadClick(callback: Maps3DListener<IMaps3DRoadHit>): () => void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
         x: number;
@@ -737,8 +802,9 @@ declare class MahalMap {
     /**
      * Участок под курсором либо null. Зовётся ТОЛЬКО при смене участка, не на каждое
      * движение мыши. `null` вместо колбэка — отписаться и погасить подсветку.
+     * Переживает отсутствие слоя на момент подписки; возвращает отписку.
      */
-    onParkingHover(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingHover(callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     /** Облик подсветки: color, opacity, outlineColor, outlineWidth, cursor. */
     setParkingHoverStyle(style: IMaps3DParkingHoverStyle): void;
     /** Вкл/выкл наведение, не теряя подписку. */
@@ -749,8 +815,11 @@ declare class MahalMap {
     hoverParking(id: number | string | null): boolean;
     /** `osm_id` подсвеченного участка или null. */
     hoveredParking(): number | string | null;
-    /** Клик по участку: справка либо null. `null` вместо колбэка — отписаться. */
-    onParkingClick(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    /**
+     * Клик по участку: справка либо null. `null` вместо колбэка — отписаться.
+     * Переживает отсутствие слоя на момент подписки; возвращает отписку.
+     */
+    onParkingClick(callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     /**
      * Парковка под точкой холста (`e.point` события карты). Попадание — по границе полигона;
      * допуск по умолчанию 0 — строго внутрь участка.
@@ -765,8 +834,10 @@ declare class MahalMap {
      *
      * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
      * разбор сцены не делает.
+     *
+     * @returns Отписка; снимает только эту подписку.
      */
-    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    onBuildingHover(callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     /**
      * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
      * режим рисования, открытая карточка объекта, тач-устройство без курсора.
@@ -787,6 +858,20 @@ declare class MahalMap {
     hoverBuilding(id: number | string | null): boolean;
     /** Идентификатор дома под наведением или `null`. */
     hoveredBuilding(): number | string | null;
+    /**
+     * Зум, с которого поднимается объём: `maps3d.minZoom` из опций create() — ровно то, что
+     * уходит в Maps3D, — либо умолчание самой Maps3D (16). Ответ не зависит от текущего
+     * зума, в отличие от `rendered` в состоянии слоя.
+     */
+    getBuildingsMinZoom(): number;
+    /**
+     * Занимает слот подписки. Запись живёт до подъёма слоя и переигрывается на нём;
+     * отписка снимает слот, только если он всё ещё её.
+     */
+    private subscribe;
+    private bindSubscription;
+    /** Снимает подписку со слоя: её же отпиской, а у сборок до 0.11.0 — через null. */
+    private unbindSubscription;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
@@ -848,7 +933,11 @@ declare function Router(param: number[][], typeData: string, token: string): Pro
 
 declare function Search(param: string, token: string, additionalParam?: IAdditionalParamType): Promise<ISearchResponse[]>;
 declare function SearchPoi(param: string, token: string, additionalParam?: IAdditionalParamType): Promise<ISearchResponse[]>;
-declare function SearchByLocation(params: ISearchByLocationParam): Promise<ISearchResponse>;
+/**
+ * Обратный геокодинг. В отличие от Search/SearchPoi возвращает тело ответа целиком:
+ * `{ success, data: ISearchResponse[], message }` — объекты рядом с точкой, по `distance`.
+ */
+declare function SearchByLocation(params: ISearchByLocationParam): Promise<IResponse<ISearchResponse[]>>;
 declare function CheckJSApi(token: string): Promise<ICheckJSApiResponse>;
 
 declare const index$2_CheckJSApi: typeof CheckJSApi;
@@ -1105,4 +1194,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 { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DBuildingsOptions, type IMaps3DClosuresOptions, type IMaps3DDiagnostics, type IMaps3DHoverStyle, type IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DParkingHoverStyle, type IMaps3DParkingInfo, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, type Maps3DParkingSubtype, type Maps3DTerrainMode, type Maps3DThemeName, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DBuildingsOptions, type IMaps3DClosuresOptions, type IMaps3DDiagnostics, type IMaps3DHoverStyle, type IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DLayerStateParams, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DParkingHoverStyle, type IMaps3DParkingInfo, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchDetailAddress, type ISearchDetailInfo, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, type Maps3DListener, type Maps3DParkingSubtype, type Maps3DSelectionKind, type Maps3DTerrainMode, type Maps3DThemeName, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type SearchResultType, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };