mahal_map 2.2.3 → 2.4.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; рекомендуется 0.8.0 — в ней наведение на здание и починенный пикинг клика) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+- `@grammaps/maps3d-web` (>=0.11.0 — в ней отписки у подписок, `selectedBuildingKind()`, этажи в состоянии слоя и починенный клик по зданию сверху; на сборках постарше карта работает через запасные пути, но отписка и `selectedBuildingKind` не гарантированы) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
 
 MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
 
@@ -51,6 +51,8 @@ const map = MahalMap.create({ container: "map" }, maplibregl, Maps3D);
 
 ```ts
 // vite.config.ts — чтобы адрес воркера совпал с файлом во время разработки
+import { defineConfig } from "vite";
+
 export default defineConfig({ optimizeDeps: { exclude: ["maplibre-gl"] } });
 ```
 
@@ -427,6 +429,15 @@ map.setIndoorLevel(1); // нумерация OSM: 0 — первый назем
 map.refreshIndoor(); // перечитать после правки картографом
 ```
 
+С Maps3D 0.11.0 список этажей приходит в состоянии слоя — опрашивать `getIndoorLevels()` на `idle`/`moveend` не нужно:
+
+```ts
+map.onLayers((state) => {
+  if (state.id !== "indoor") return;
+  renderLevelPicker(state.params.levels ?? [], state.params.level);
+});
+```
+
 После поиска показать найденный объект вместе с его этажом:
 
 ```ts
@@ -492,13 +503,13 @@ await maps3d.ready; // enhance() ждёт нативную карту MapLibre,
 ```ts
 map.setSelectionStyle({ color: "#e23b2f", opacity: 0.55, durationMs: 300 });
 
-map.onBuildingClick((building) => {
+const stopBuildingClick = map.onBuildingClick((building) => {
   if (!building) return;
-  // SDK уже подсветил его
-  console.log(building.props?.osm_id, building.height);
+  // SDK уже подсветил его. index >= 0 — объёмный дом сцены, -1 — дом из слоя стиля
+  console.log(building.props?.osm_id, building.height, building.index);
 });
 
-map.onRoadClick((road) => {
+const stopRoadClick = map.onRoadClick((road) => {
   if (!road) return;
   console.log(road.nameRu ?? road.name, road.class);
 });
@@ -506,8 +517,13 @@ map.onRoadClick((road) => {
 // Выделить здание по osm_id — например, после поиска
 map.selectBuilding(123456789); // false, если здания нет в загруженных данных
 map.selectedBuilding(); // текущий id или null
+map.selectedBuildingKind(); // 'scene' — объём, 'flat' — слой стиля, null — выделения нет
 map.clearSelection();
 
+// При размонтировании
+stopBuildingClick();
+stopRoadClick();
+
 // Дорога под точкой холста, допуск по умолчанию 12 px
 map.roadAt({ x: 320, y: 240 });
 map.roadsNamed; // есть ли в текущем стиле названия дорог
@@ -524,6 +540,22 @@ map.setSelectionStyle({ color: "#e23b2f" });
 map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
 ```
 
+#### Отписка
+
+`onBuildingClick`, `onBuildingHover`, `onRoadClick`, `onParkingHover` и `onParkingClick` возвращают функцию отписки и принимают `null`. Повторный вызов заменяет обработчик. Отписка снимает **только свою** подписку: если обработчик уже заменён следующим вызовом, она ничего не делает — отложенный вызов прежнего владельца (например, cleanup размонтированного компонента) не погасит обработчик нового. Работает и для подписки, сделанной до подъёма слоя: снятая до подъёма, она на слой не попадёт.
+
+```ts
+useEffect(() => map.onBuildingClick(openCard), [map]); // отписка уходит в cleanup
+```
+
+#### Порог зума объёма
+
+`getBuildingsMinZoom()` — зум, с которого поднимается объём: `maps3d.minZoom`, который `mahal_map` передал в Maps3D, либо умолчание Maps3D (`16`). В отличие от `rendered` в состоянии слоя, ответ не зависит от текущего зума.
+
+```ts
+const willBe3D = targetZoom >= map.getBuildingsMinZoom();
+```
+
 ### Наведение на здание
 
 Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
@@ -539,11 +571,11 @@ map.onBuildingHover((building) => {
 
 Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
 
-Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` отписывает и гасит подсветку.
+Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` или возвращённая отписка снимает подписку и гасит подсветку.
 
 | Метод | Описание |
 | --- | --- |
-| `onBuildingHover(cb \| null)` | Подписка на наведение; `null` отписывает и гасит подсветку. |
+| `onBuildingHover(cb \| null)` | Подписка на наведение; возвращает отписку, `null` отписывает и гасит подсветку. |
 | `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
 | `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
 | `hoverEnabled` | Включено ли наведение сейчас. |
@@ -571,11 +603,13 @@ row.addEventListener("mouseleave", () => map.hoverBuilding(null));
 map.setHoverEnabled(false); // подписка сохраняется
 ```
 
-Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения карты и не трогает сцену, пока курсор на том же доме. Но разбор — это чтение пикселя обратно из GPU, поэтому на слабых устройствах наведение лучше не включать.
+Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения камеры — и от жестов, и от `jumpTo`/`easeTo` из приложения (с 0.11.0) — и не трогает сцену, пока курсор на том же доме. С 0.11.0 наведение читает пиксель из GPU асинхронно и главный поток не держит; гасить наведение на время движения карты снаружи больше не нужно.
 
 ### Парковки: наведение, клик, справка
 
 > Нужен `@grammaps/maps3d-web` **0.10.0+**. На более старой сборке методы ничего не делают и возвращают пустые значения (`false`, `null`).
+>
+> Подписки `onParkingHover`/`onParkingClick` можно делать до подъёма слоя — они запоминаются и переигрываются, как у зданий. Обе возвращают отписку.
 
 Устроено как у зданий: приложение задаёт облик и получает уведомления, подсветку и курсор рисует SDK.
 
@@ -604,13 +638,13 @@ map.getMap().on("contextmenu", (e) => console.log(map.parkingAt(e.point, 4)));
 
 | Метод                              | Описание                                                                                          |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. `null` — отписаться и погасить. |
+| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. Возвращает отписку; `null` — отписаться и погасить. |
 | `setParkingHoverStyle(style)`      | Облик подсветки: `color`, `opacity`, `outlineColor`, `outlineWidth`, `cursor`.                    |
 | `setParkingHoverEnabled(enabled)`  | Выключить/включить наведение, не теряя подписку.                                                  |
 | `parkingHoverEnabled`              | Геттер: включено ли наведение.                                                                    |
 | `hoverParking(id \| null)`         | Подсветить участок программно по `osm_id`; `null` — погасить. `false` — участка нет в данных.     |
 | `hoveredParking()`                 | `osm_id` подсвеченного участка или `null`.                                                        |
-| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. `null` вместо колбэка — отписаться.                         |
+| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. Возвращает отписку; `null` вместо колбэка — отписаться.     |
 | `parkingAt(point, tolPx?)`         | Справка по точке холста. Допуск по умолчанию `0` — строго внутрь участка.                         |
 
 Облик подсветки (`IMaps3DParkingHoverStyle`):
@@ -664,6 +698,8 @@ MahalMap.toggle3DBuildings(map, false);
 
 Для переключения пользуйтесь именно `toggle3DBuildings()`: он поднимет слой, если его ещё не было (`enable3D: false` при создании), а на сборках Maps3D без реестра слоёв откатится на `setBuildingsEnabled()`.
 
+Поднять слой можно, только если `Maps3D` был при `create()` — тогда карта стоит на стиле платформы. Карта, созданная без него, работает на запасном стиле без источников платформы и без ключа в запросах: `toggle3DBuildings(true)` на ней ничего не делает и пишет предупреждение. Подключить `Maps3D` позже — значит пересоздать карту.
+
 ```ts
 map.toggle3DBuildings(false); // совместимо со всеми сборками
 ```
@@ -841,7 +877,7 @@ onBeforeUnmount(() => {
 | `antialias: true` не забыть                     | ставится сам при включённом 3D                                    |
 | `Maps3D.enhance(map, opts); await maps3d.ready` | `enable3D: true` + `maps3d: {...}`, `await map.whenMaps3DReady()` |
 | `map.setStyle(Maps3D.styleUrl("dark", base))`   | `map.setStyle("dark")` — внутри выбранного семейства              |
-| `maps3d.refreshLayers()` после смены стиля      | вызывается сам на `style.load`                                    |
+| `maps3d.refreshLayers()` после смены стиля      | вызывается сам на `styledata`, когда новый стиль загружен         |
 | `maps3d.destroy(); map.remove()`                | `map.destroy()`                                                   |
 | ключ руками в каждый вызов                      | один `keyUtils.saveKey()` на всё                                  |
 
@@ -945,7 +981,7 @@ const map = MahalMap.create(
 );
 ```
 
-В NPM-версии второй аргумент `maplibreObject` рекомендуется передавать явно. В browser SDK он берется из `window.maplibregl`.
+В NPM-версии второй аргумент `maplibreObject` рекомендуется передавать явно. Без него SDK ищет `window.maplibregl` — он есть, только если MapLibre подключён скриптом (`<script src=".../maplibre-gl.js">`). ESM-импорт глобальную переменную не создаёт: тогда передайте библиотеку вторым аргументом (`MahalMap.create({ container: "map" }, maplibregl)`) либо назначьте `window.maplibregl = maplibregl` до вызова `create()`.
 
 ### `MahalMap.createAsync(options, maplibreObject?, maps3dCtor?)`
 
@@ -994,7 +1030,7 @@ try {
     </div>
     <template #fallback>
       <div class="flex h-[360px] items-center justify-center">
-        {{ loadingLabel }}
+        Загрузка карты…
       </div>
     </template>
   </ClientOnly>
@@ -1019,10 +1055,17 @@ onMounted(async () => {
 
   keyUtils.saveKey(import.meta.env.VITE_MAHAL_API_KEY_TILE);
 
+  // Без элемента SDK взял бы контейнер по умолчанию — id "map", то есть чужой элемент.
+  const container = mapElement.value;
+
+  if (!container || disposed) {
+    return;
+  }
+
   try {
     const instance = await MahalMap.createAsync(
       {
-        container: mapElement.value,
+        container,
         center: DUSHANBE_CENTER,
         zoom: 11,
       },
@@ -1258,6 +1301,8 @@ MahalMap.showPlace(map, 68.787, 38.573, 2, 18);
 MahalMap.onBuildingClick(map, (building) => console.log(building?.id));
 MahalMap.selectBuilding(map, 123456789);
 MahalMap.selectedBuilding(map);
+MahalMap.selectedBuildingKind(map);
+MahalMap.getBuildingsMinZoom(map);
 MahalMap.setSelectionStyle(map, { color: "#e23b2f" });
 MahalMap.clearSelection(map);
 MahalMap.onRoadClick(map, (road) => console.log(road?.name));
@@ -1313,7 +1358,7 @@ MahalMap.setZoom(map, 14);
 | `getMap(instance)`                             | Возвращает нативный MapLibre Map.                                     |
 | `getCamera(instance)`                          | Возвращает CameraController.                                          |
 | `setStyle(instance, theme)`                    | Переключает тему стандартного стиля.                                  |
-| `setLanguage(instance, lang)`                  | Переключает язык стандартного стиля.                                  |
+| `setLanguage(instance, lang)`                  | Запоминает язык для поиска и роутинга; стиль и подписи не меняет.     |
 | `setCenter(instance, center)`                  | Меняет центр карты.                                                   |
 | `setZoom(instance, zoom)`                      | Меняет zoom карты.                                                    |
 | `addMarker(instance, marker)`                  | Добавляет маркер.                                                     |
@@ -1325,16 +1370,18 @@ MahalMap.setZoom(map, 14);
 | `getLayers(instance)`                          | Снимок всех слоёв.                                                    |
 | `onLayers(instance, callback)`                 | Подписка на изменения слоёв; возвращает отписку.                      |
 | `refreshLayers(instance)`                      | Пере-применить волю клиента ко всем слоям.                            |
-| `getIndoorLevels(instance)`                    | Этажи, найденные в текущем виде карты.                                |
+| `getIndoorLevels(instance)`                    | Этажи в текущем виде карты (с 0.11.0 — из `params.levels` слоя).      |
 | `setIndoorLevel(instance, level)`              | Переключить этаж (0 — первый наземный).                               |
 | `refreshIndoor(instance)`                      | Перечитать планы этажей.                                              |
 | `showPlace(instance, lon, lat, level?, zoom?)` | Показать объект и открыть его этаж.                                   |
-| `onBuildingClick(instance, callback)`          | Клик по зданию.                                                       |
+| `onBuildingClick(instance, callback \| null)`  | Клик по зданию; возвращает отписку.                                   |
 | `selectBuilding(instance, id, style?)`         | Выделить здание по `osm_id`.                                          |
 | `clearSelection(instance)`                     | Снять выделение.                                                      |
 | `selectedBuilding(instance)`                   | Идентификатор выделенного здания или `null`.                          |
+| `selectedBuildingKind(instance)`               | `'scene'` / `'flat'` / `null` — чем нарисовано выделение.             |
+| `getBuildingsMinZoom(instance)`                | Зум появления объёма, переданный в Maps3D (по умолчанию `16`).        |
 | `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
-| `onRoadClick(instance, callback)`              | Клик по дороге.                                                       |
+| `onRoadClick(instance, callback \| null)`      | Клик по дороге; возвращает отписку.                                   |
 | `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
 | `onParkingHover(instance, callback \| null)`   | Парковка под курсором (только при смене участка).                     |
 | `setParkingHoverStyle(instance, style)`        | Облик подсветки парковки.                                             |
@@ -1649,6 +1696,8 @@ interface MeasureShape {
 import {
   Search,
   SearchPoi,
+  createSearch,
+  createSearchPoi,
   SearchByLocation,
   CheckJSApi,
   Router,
@@ -1657,7 +1706,7 @@ import {
 
 ### `Search(text, token, additionalParam?)`
 
-Поиск адресов (геокодер). Вызовы дебаунсятся на 500 мс: при вводе по символу уходит один запрос.
+Поиск адресов (геокодер). Каждый вызов — отдельный запрос, без дебаунса: статический метод зовут разные поля ввода, и общий дебаунс отменял бы запрос одного поля вызовом из другого. Для ввода по символу — `createSearch()`.
 
 ```ts
 const results = await Search("Рудаки 33", token, {
@@ -1679,7 +1728,7 @@ const results = await Search("Рудаки 33", token, {
 
 ### `SearchPoi(text, token, additionalParam?)`
 
-Поиск POI (организации, объекты). Сигнатура и дебаунс те же, что у `Search`, таймер отдельный — параллельный ввод в двух полях не перебивает запросы друг друга.
+Поиск POI (организации, объекты). Сигнатура та же, что у `Search`, и тоже без дебаунса; для ввода по символу — `createSearchPoi()`.
 
 ```ts
 const places = await SearchPoi("кафе", token, {
@@ -1691,6 +1740,30 @@ const places = await SearchPoi("кафе", token, {
 
 Возвращает `ISearchResponse[]`.
 
+### `createSearch(delay?)` / `createSearchPoi(delay?)`
+
+Поиск с дебаунсом для **одного** поля ввода. Возвращают функцию с сигнатурой `Search`/`SearchPoi`; пауза по умолчанию — 500 мс. Создавайте экземпляр на поле (компонент) — очередь у каждого своя, и чужие поля его запросы не отменяют.
+
+Вызов, перебитый следующим вызовом **этого же** экземпляра до ухода запроса, отклоняется с `DebounceCancelledError`. Это не сбой: ответ получит последний вызов, а отменённый пропускайте молча.
+
+```ts
+import { createSearch } from "mahal_map";
+
+const searchAddress = createSearch(); // одна на поле ввода
+
+input.addEventListener("input", async () => {
+  try {
+    suggestions = await searchAddress(input.value, token);
+  } catch (error) {
+    // Перебит следующим вводом в этом же поле
+    if ((error as Error).name === "DebounceCancelledError") return;
+    showError(error);
+  }
+});
+```
+
+Сверяйте по `name`, а не через `instanceof`: на странице может оказаться две сборки SDK. Класс тоже экспортируется — `import { DebounceCancelledError } from "mahal_map"`.
+
 ### `SearchByLocation(params)`
 
 Обратный геокодинг: адреса и POI по координатам. Без дебаунса.