mahal_map 2.2.0 → 2.2.3

package/README.md

@@ -341,7 +341,16 @@ MahalMap.create(
 | `active`    | что нарисовано прямо сейчас (память SDK)          |
 | `rendered`  | факт со стороны карты: слой есть в стиле и не погашен |
 
-`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки.
+`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки. Сравнивать поля можно только когда `rendered` есть — иначе на старой сборке любой активный слой покажется расхождением:
+
+```ts
+const state = map.getLayerState("terrain");
+
+// rendered === undefined — Maps3D < 0.8.0, проверка недоступна
+if (state?.rendered !== undefined && state.active !== state.rendered) {
+  reportLayerMismatch(state);
+}
+```
 
 Слой может быть включён и при этом не нарисован — и это не ошибка:
 
@@ -1436,7 +1445,7 @@ map.addMarker(marker);
 | Параметр      | Тип                | Описание                                                                |
 | ------------- | ------------------ | ----------------------------------------------------------------------- |
 | `coordinates` | `[number, number]` | Координаты маркера в формате `[lng, lat]`.                              |
-| `draggable`   | `boolean`          | Делает HTML-элемент маркера draggable.                                  |
+| `draggable`   | `boolean`          | Маркер можно перетаскивать на карте (слушайте `dragend` у результата `addMarker()`). |
 | `anchor`      | `string`           | Anchor MapLibre маркера.                                                |
 | `color`       | `string`           | Цвет стандартного SVG маркера или замена `fill` в пользовательском SVG. |
 | `svg`         | `string`           | Полностью пользовательский SVG.                                         |
@@ -1701,6 +1710,24 @@ const res = await SearchByLocation({
 | `token` | `string`           | да           |
 | `type`  | `string`           | нет          |
 
+Возвращает тело ответа целиком — `IResponse<ISearchResponse[]>`: объекты рядом с точкой
+(адреса и POI), по возрастанию `distance` в метрах.
+
+```ts
+const { data } = await SearchByLocation({ lat: 40.2808, lng: 69.6248, token });
+
+const house = data.find((item) => item.type.toLowerCase() === "address");
+if (house && !Array.isArray(house.detailAddress)) {
+  const { city, street_type, street_name, number } = house.detailAddress;
+  // "Хуҷанд", "кӯчаи", "Камоли Хуҷандӣ", "162/1"
+}
+```
+
+- `type` приходит в разном регистре (`"Address"`, `"poi"`) — сравнивайте через `toLowerCase()`.
+- Город — в `detailAddress.city` (`city_type`: `шаҳр`). Района в ответе обратного геокодинга нет.
+- Любое поле `detailAddress` может отсутствовать, в том числе `number`.
+- Пустой `detailAddress` приходит массивом `[]`.
+
 ### `CheckJSApi(token)`
 
 Проверяет, активна ли подписка JSApi у токена.

package/dist/index.d.mts

@@ -230,10 +230,13 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
-    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
-    props: Record<string, unknown>;
-    /** Высота здания в метрах. */
-    height: number;
+    /**
+     * Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется.
+     * Необязательно: peerDependency допускает сборки Maps3D от 0.5.0, где поля может не быть.
+     */
+    props?: Record<string, unknown>;
+    /** Высота здания в метрах. Необязательно по той же причине, что и `props`. */
+    height?: number;
     /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
     [key: string]: unknown;
@@ -466,31 +469,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;
@@ -845,7 +869,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;
@@ -1102,4 +1130,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 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 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 SearchResultType, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };

package/dist/index.d.ts

@@ -230,10 +230,13 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
-    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
-    props: Record<string, unknown>;
-    /** Высота здания в метрах. */
-    height: number;
+    /**
+     * Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется.
+     * Необязательно: peerDependency допускает сборки Maps3D от 0.5.0, где поля может не быть.
+     */
+    props?: Record<string, unknown>;
+    /** Высота здания в метрах. Необязательно по той же причине, что и `props`. */
+    height?: number;
     /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
     [key: string]: unknown;
@@ -466,31 +469,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;
@@ -845,7 +869,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;
@@ -1102,4 +1130,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 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 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 SearchResultType, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };