mahal_map 2.0.3 → 2.1.0

package/README.md

@@ -13,7 +13,7 @@ npm install mahal_map maplibre-gl @grammaps/maps3d-web
 Обе зависимости — `peerDependencies`, в бандл `mahal_map` они не входят. Библиотека их не импортирует: MapLibre и `Maps3D` приходят снаружи, аргументами `create()` либо через `window`.
 
 - `maplibre-gl` (`^6.10.0`) — обязателен всегда.
-- `@grammaps/maps3d-web` (>=0.5.0) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+- `@grammaps/maps3d-web` (>=0.5.0; рекомендуется 0.8.0 — в ней наведение на здание и починенный пикинг клика) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
 
 MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
 
@@ -334,11 +334,14 @@ MahalMap.create(
 
 Поля независимы, и это главная ловушка реестра:
 
-| Поле        | Вопрос                       |
-| ----------- | ---------------------------- |
-| `wanted`    | чего хочет приложение        |
-| `available` | что позволяют стиль и данные |
-| `active`    | что нарисовано прямо сейчас  |
+| Поле        | Вопрос                                            |
+| ----------- | ------------------------------------------------- |
+| `wanted`    | чего хочет приложение                             |
+| `available` | что позволяют стиль и данные                      |
+| `active`    | что нарисовано прямо сейчас (память SDK)          |
+| `rendered`  | факт со стороны карты: слой есть в стиле и не погашен |
+
+`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки.
 
 Слой может быть включён и при этом не нарисован — и это не ошибка:
 
@@ -506,6 +509,55 @@ map.setSelectionStyle({ color: "#e23b2f" });
 map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
 ```
 
+### Наведение на здание
+
+Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
+
+```ts
+map.setHoverStyle({ color: "#6b9ed1", opacity: 0.3, cursor: "pointer" });
+
+map.onBuildingHover((building) => {
+  if (!building) return; // курсор ушёл с домов
+  console.log(building.props.osm_id, building.height);
+});
+```
+
+Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
+
+Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` отписывает и гасит подсветку.
+
+| Метод | Описание |
+| --- | --- |
+| `onBuildingHover(cb \| null)` | Подписка на наведение; `null` отписывает и гасит подсветку. |
+| `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
+| `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
+| `hoverEnabled` | Включено ли наведение сейчас. |
+| `hoverBuilding(id \| null)` | Навести программно — например, с наведения на строку списка. `false` — дома нет на карте. |
+| `hoveredBuilding()` | Идентификатор дома под наведением или `null`. |
+
+Слот наведения свой, отдельный от выделения: **выбор всегда главнее**, и на выбранном доме наведение не рисуется. Занимать `setSelectionStyle` ради подсветки под курсором, как приходилось до 0.8.0, больше не нужно.
+
+#### Наведение с элементов интерфейса
+
+Курсор стоит на строке списка, а не на карте:
+
+```ts
+row.addEventListener("mouseenter", () => map.hoverBuilding(row.dataset.osmId!));
+row.addEventListener("mouseleave", () => map.hoverBuilding(null));
+```
+
+Следующее движение мыши по карте перебивает программное наведение — слежение владеет слотом, пока включено.
+
+#### Где наведение выключают
+
+Там, где подсветка мешает: режим рисования на карте, открытая карточка объекта, тач-устройство без курсора.
+
+```ts
+map.setHoverEnabled(false); // подписка сохраняется
+```
+
+Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения карты и не трогает сцену, пока курсор на том же доме. Но разбор — это чтение пикселя обратно из GPU, поэтому на слабых устройствах наведение лучше не включать.
+
 #### Вкл/выкл 3D-здания на лету
 
 Переключение объём ⇄ штатные здания стиля, без пересоздания карты. Умеет поднять слой, если его не было (`enable3D: false` при создании):
@@ -1123,6 +1175,13 @@ MahalMap.clearSelection(map);
 MahalMap.onRoadClick(map, (road) => console.log(road?.name));
 MahalMap.roadAt(map, { x: 320, y: 240 });
 
+// Наведение на здание (Maps3D 0.8.0)
+MahalMap.onBuildingHover(map, (b) => console.log(b?.id));
+MahalMap.setHoverStyle(map, { color: "#6b9ed1", cursor: "pointer" });
+MahalMap.setHoverEnabled(map, false);
+MahalMap.hoverBuilding(map, 123456789);
+MahalMap.hoveredBuilding(map);
+
 MahalMap.destroy(map);
 ```
 
@@ -1180,6 +1239,11 @@ MahalMap.setZoom(map, 14);
 | `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
 | `onRoadClick(instance, callback)`              | Клик по дороге.                                                       |
 | `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
+| `onBuildingHover(instance, cb)`               | Подписка на наведение (Maps3D 0.8.0); `null` отписывает.              |
+| `setHoverStyle(instance, style)`              | Облик наведения, включая CSS-курсор.                                  |
+| `setHoverEnabled(instance, on)`               | Вкл/выкл наведение, не трогая подписку.                               |
+| `hoverBuilding(instance, id)`                 | Навести на здание программно; `null` снимает.                         |
+| `hoveredBuilding(instance)`                   | Дом под наведением или `null`.                                        |
 | `destroy(instance)`                            | Полностью удаляет карту.                                              |
 | `loadKeyFromScriptUrl()`                       | Читает `apikey` из URL SDK скрипта.                                   |
 | `loadLanguageFromScriptUrl()`                  | Читает `lang` из URL SDK скрипта.                                     |

package/dist/index.d.mts

@@ -91,6 +91,12 @@ interface IMaps3DLayerState {
     available: boolean;
     /** Что нарисовано прямо сейчас. Именно это поле показывает, включён слой на деле или нет. */
     active: boolean;
+    /**
+     * Факт со стороны карты: слой есть в стиле и не погашен. Появилось в 0.8.0.
+     * `active !== rendered` — расхождение внутреннего признака SDK с картой.
+     * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
+     */
+    rendered?: boolean;
     /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
     params: Record<string, unknown>;
 }
@@ -101,6 +107,15 @@ interface IMaps3DSelectionStyle {
     durationMs?: number;
     easing?: "ease-out" | "linear";
 }
+/**
+ * Облик наведения. Появился в 0.8.0: до него подсветить дом под курсором можно было,
+ * только заняв единственный слот выделения. Теперь слот свой, и выбор всегда главнее —
+ * на выбранном доме наведение не рисуется.
+ */
+interface IMaps3DHoverStyle extends IMaps3DSelectionStyle {
+    /** CSS-курсор над зданием. По умолчанию "pointer"; `null` — не трогать курсор вовсе. */
+    cursor?: string | null;
+}
 interface IMaps3DRoadHit {
     name: string;
     nameRu?: string;
@@ -213,6 +228,12 @@ interface IMaps3DLayer {
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
+    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): 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;
     roadAt?(point: {
         x: number;
@@ -468,6 +489,9 @@ declare class MahalMap {
     private pendingRoadClick?;
     private pendingSelectionStyle?;
     private pendingLayerSubscribers;
+    private pendingBuildingHover?;
+    private pendingHoverStyle?;
+    private pendingHoverEnabled?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -540,6 +564,11 @@ declare class MahalMap {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
+    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
+    static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
+    static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
+    static hoveredBuilding(instance: MahalMap): string | number | null;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -641,6 +670,34 @@ declare class MahalMap {
     }, tolerancePx?: number): IMaps3DRoadHit | null;
     /** Есть ли в текущем стиле названия дорог. Нет — roadAt() всегда вернёт null. */
     get roadsNamed(): boolean;
+    /**
+     * Подписаться на наведение. Колбэк приходит только в момент смены дома под курсором,
+     * а не на каждое движение мыши. `null` отписывает и гасит подсветку.
+     *
+     * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
+     * разбор сцены не делает.
+     */
+    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    /**
+     * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
+     * режим рисования, открытая карточка объекта, тач-устройство без курсора.
+     */
+    setHoverEnabled(enabled: boolean): void;
+    /** Включено ли наведение прямо сейчас. */
+    get hoverEnabled(): boolean;
+    /** Облик наведения: цвет, плотность, свечение, длительность и CSS-курсор. */
+    setHoverStyle(style: IMaps3DHoverStyle): void;
+    /**
+     * Навести на здание программно — например, когда курсор стоит на строке списка.
+     * Идентификатор тот же, что у selectBuilding. `null` снимает наведение.
+     *
+     * Следующее движение мыши по карте перебивает программное наведение.
+     *
+     * @returns `false`, если такого дома сейчас на карте нет.
+     */
+    hoverBuilding(id: number | string | null): boolean;
+    /** Идентификатор дома под наведением или `null`. */
+    hoveredBuilding(): number | string | null;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
@@ -959,4 +1016,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 IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, 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 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 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 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 };

package/dist/index.d.ts

@@ -91,6 +91,12 @@ interface IMaps3DLayerState {
     available: boolean;
     /** Что нарисовано прямо сейчас. Именно это поле показывает, включён слой на деле или нет. */
     active: boolean;
+    /**
+     * Факт со стороны карты: слой есть в стиле и не погашен. Появилось в 0.8.0.
+     * `active !== rendered` — расхождение внутреннего признака SDK с картой.
+     * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
+     */
+    rendered?: boolean;
     /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
     params: Record<string, unknown>;
 }
@@ -101,6 +107,15 @@ interface IMaps3DSelectionStyle {
     durationMs?: number;
     easing?: "ease-out" | "linear";
 }
+/**
+ * Облик наведения. Появился в 0.8.0: до него подсветить дом под курсором можно было,
+ * только заняв единственный слот выделения. Теперь слот свой, и выбор всегда главнее —
+ * на выбранном доме наведение не рисуется.
+ */
+interface IMaps3DHoverStyle extends IMaps3DSelectionStyle {
+    /** CSS-курсор над зданием. По умолчанию "pointer"; `null` — не трогать курсор вовсе. */
+    cursor?: string | null;
+}
 interface IMaps3DRoadHit {
     name: string;
     nameRu?: string;
@@ -213,6 +228,12 @@ interface IMaps3DLayer {
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
+    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): 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;
     roadAt?(point: {
         x: number;
@@ -468,6 +489,9 @@ declare class MahalMap {
     private pendingRoadClick?;
     private pendingSelectionStyle?;
     private pendingLayerSubscribers;
+    private pendingBuildingHover?;
+    private pendingHoverStyle?;
+    private pendingHoverEnabled?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -540,6 +564,11 @@ declare class MahalMap {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
+    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
+    static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
+    static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
+    static hoveredBuilding(instance: MahalMap): string | number | null;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -641,6 +670,34 @@ declare class MahalMap {
     }, tolerancePx?: number): IMaps3DRoadHit | null;
     /** Есть ли в текущем стиле названия дорог. Нет — roadAt() всегда вернёт null. */
     get roadsNamed(): boolean;
+    /**
+     * Подписаться на наведение. Колбэк приходит только в момент смены дома под курсором,
+     * а не на каждое движение мыши. `null` отписывает и гасит подсветку.
+     *
+     * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
+     * разбор сцены не делает.
+     */
+    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    /**
+     * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
+     * режим рисования, открытая карточка объекта, тач-устройство без курсора.
+     */
+    setHoverEnabled(enabled: boolean): void;
+    /** Включено ли наведение прямо сейчас. */
+    get hoverEnabled(): boolean;
+    /** Облик наведения: цвет, плотность, свечение, длительность и CSS-курсор. */
+    setHoverStyle(style: IMaps3DHoverStyle): void;
+    /**
+     * Навести на здание программно — например, когда курсор стоит на строке списка.
+     * Идентификатор тот же, что у selectBuilding. `null` снимает наведение.
+     *
+     * Следующее движение мыши по карте перебивает программное наведение.
+     *
+     * @returns `false`, если такого дома сейчас на карте нет.
+     */
+    hoverBuilding(id: number | string | null): boolean;
+    /** Идентификатор дома под наведением или `null`. */
+    hoveredBuilding(): number | string | null;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
@@ -959,4 +1016,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 IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, 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 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 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 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 };