mahal_map 1.6.6 → 1.6.7

package/README.md

@@ -519,6 +519,112 @@ MahalMap.onReady("map", () => {
 map.destroy();
 ```
 
+## MeasureTool (линейка и планиметр)
+
+`MeasureTool` — инструмент измерения расстояния и площади прямо на карте (линейка + планиметр, как в Яндекс.Картах). Полностью самодостаточен: сам рисует точки, линии, полигон и подписи поверх MapLibre, сам обрабатывает клики/drag/удаление точек. Приложение только передает стили (цвета, иконки, подписи единиц) и слушает `onChange`.
+
+```ts
+import { MeasureTool } from "mahal_map";
+
+const map = MahalMap.getInstance("map").getMap();
+
+const measureTool = new MeasureTool(map, {
+  mode: "distance",
+  style: {
+    lineColor: "#278960",
+    pointColor: "#FFFFFF",
+    pointStrokeColor: "#278960",
+    fillColor: "#278960",
+    fillOpacity: 0.15,
+  },
+  labels: {
+    meters: "м",
+    kilometers: "км",
+    squareMeters: "м²",
+    squareKilometers: "км²",
+  },
+  onChange: (state) => {
+    console.log(state.mode, state.draft, state.shapes);
+  },
+  onCloseRequest: () => {
+    measureTool.stop();
+  },
+});
+
+measureTool.start("distance");
+```
+
+### Важно: цвета — реальные, не CSS-переменные
+
+MapLibre GL проверяет `paint`-свойства слоя и не понимает `var(--primary)` — только hex/rgb. Если в приложении цвета живут в CSS-переменных (тема light/dark), резолвьте их в реальное значение перед передачей в `style`:
+
+```ts
+const primary = getComputedStyle(document.documentElement)
+  .getPropertyValue("--primary")
+  .trim() || "#278960";
+
+const measureTool = new MeasureTool(map, {
+  style: { lineColor: primary, pointStrokeColor: primary, fillColor: primary },
+});
+```
+
+Значения `badgeBackground`, `badgeTextColor` и другие DOM-стили бейджа — обычный CSS, туда `var(--x)` передавать можно.
+
+### Конструктор: `new MeasureTool(map, options?)`
+
+| Опция              | Тип                                     | Описание                                                                 |
+| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| `mode`              | `"distance" \| "area"`                   | Режим по умолчанию. По умолчанию `"distance"`.                          |
+| `sourceIdPrefix`    | `string`                                 | Префикс id source/layer на карте. По умолчанию `"mahal-measure"`.       |
+| `style`             | `MeasureStyleOptions`                    | Цвета и размеры точек/линий/заливки/бейджа.                             |
+| `icons`             | `MeasureIcons`                           | SVG-иконки `trash` / `close` / `check` для бейджей.                     |
+| `labels`            | `MeasureLabels`                          | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`. |
+| `onChange`          | `(state: MeasureState) => void`          | Вызывается при любом изменении: новая точка, drag, смена режима и т.д.  |
+| `onCloseRequest`    | `() => void`                             | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением. |
+
+### Методы
+
+| Метод                                | Описание                                                                                     |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `start(mode?)`                        | Включает инструмент и начинает/продолжает рисование в указанном режиме.                       |
+| `stop()`                              | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте.             |
+| `setMode(mode)`                       | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах. |
+| `finishDraft()`                       | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую. |
+| `removeShape(shapeId)`                | Удаляет фигуру (черновик или уже сохраненную) целиком.                                         |
+| `removePoint(shapeId, pointId)`       | Удаляет одну точку фигуры.                                                                     |
+| `clearAll()`                          | Удаляет все фигуры и черновик.                                                                 |
+| `getState()`                          | Возвращает текущий `MeasureState` (снимок, без подписки).                                      |
+| `destroy()`                           | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании.                |
+
+### Взаимодействие на карте
+
+- клик по карте — добавляет точку в текущую фигуру;
+- перетаскивание существующей точки — двигает её, расстояние/площадь пересчитываются на лету;
+- правый клик по точке — удаляет её;
+- наведение на линию/ребро полигона — показывает точку-призрак прямо под курсором; зажатие мыши вставляет в этом месте новую точку и сразу тянет её (как вставка узла в Яндекс.Картах);
+- бейдж активной (незавершенной) фигуры — показывает значение и три кнопки: ✓ (завершить фигуру), 🗑 (удалить), ✕ (вызывает `onCloseRequest`);
+- у уже сохраненных фигур — постоянный мини-бейдж: только значение и 🗑 (удалить), не пропадает при рисовании следующей фигуры.
+
+### `MeasureState`
+
+```ts
+interface MeasureState {
+  active: boolean;
+  mode: "distance" | "area";
+  draft: MeasureShape | null;
+  shapes: MeasureShape[];
+}
+
+interface MeasureShape {
+  id: string;
+  mode: "distance" | "area";
+  points: { id: string; lngLat: [number, number] }[];
+  closed: boolean;
+  distance: number; // метры
+  area: number; // квадратные метры, 0 для линии
+}
+```
+
 ## License
 
 ISC

package/dist/index.d.mts

@@ -298,6 +298,7 @@ declare class MeasureTool {
     private icons;
     private draggingPointId;
     private draggingShapeId;
+    private dragPanWasEnabled;
     private suppressNextClick;
     private hoverInsert;
     private onChange?;
@@ -330,6 +331,7 @@ declare class MeasureTool {
     private recomputeShape;
     private onMapClick;
     private onPointMouseDown;
+    private beginPointDrag;
     private onPointDragMove;
     private onPointDragUp;
     private stopDragListeners;

package/dist/index.d.ts

@@ -298,6 +298,7 @@ declare class MeasureTool {
     private icons;
     private draggingPointId;
     private draggingShapeId;
+    private dragPanWasEnabled;
     private suppressNextClick;
     private hoverInsert;
     private onChange?;
@@ -330,6 +331,7 @@ declare class MeasureTool {
     private recomputeShape;
     private onMapClick;
     private onPointMouseDown;
+    private beginPointDrag;
     private onPointDragMove;
     private onPointDragUp;
     private stopDragListeners;