mahal_map 1.5.0 → 1.5.2

package/README.md

@@ -1,66 +1,59 @@
-# Mahal Map
-
-Mahal Map is a JavaScript/TypeScript SDK for working with Mahal map services on top of MapLibre GL JS.
-
-## Installation
-
-```sh
-npm install mahal_map maplibre-gl
-```
-
-`maplibre-gl` is a peer dependency: the application that uses this SDK must install it or include it through a browser script.
-
-## NPM Usage
-
-```ts
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { MahalMap, MahalMapDefaultMarker } from "mahal_map";
-
-const mainMap = MahalMap.create(
-  {
-    container: "main-map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
-  },
-  maplibregl,
-);
-
-const marker = new MahalMapDefaultMarker({
-  coordinates: [69.624024, 40.279687],
-});
-
-mainMap.addMarker(marker);
-```
-
-## Multiple Maps
-
-`MahalMap.create()` always creates and returns a new map instance. The SDK also stores created instances by their `container` key.
-
-```ts
-const mainMap = MahalMap.create({ container: "main" }, maplibregl);
-const miniMap = MahalMap.create({ container: "mini" }, maplibregl);
-
-MahalMap.getInstance("main").setZoom(14);
-MahalMap.addMarker(miniMap, marker);
-```
-
-## Browser SDK Usage
-
-For direct browser usage, include MapLibre first and then the Mahal Map SDK bundle:
-
-```html
-<link
-  rel="stylesheet"
-  href="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.css"
-/>
+# Mahal Map
+
+Mahal Map - JavaScript/TypeScript SDK для работы с картой Mahal поверх MapLibre GL JS.
+
+Документация ниже описывает только открытые функции карты: создание карты, управление инстансами, стили, язык, камера, маркеры и browser SDK.
+
+## Установка
+
+```sh
+npm install mahal_map maplibre-gl
+```
+
+`maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
+
+## Быстрый старт через NPM
+
+```ts
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { MahalMap } from "mahal_map";
+
+const map = MahalMap.create(
+  {
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+    theme: "light",
+  },
+  maplibregl,
+);
+```
+
+Контейнер должен существовать в HTML:
+
+```html
+<div id="map" style="width: 100%; height: 500px"></div>
+```
+
+## Быстрый старт через Browser SDK
+
+Сначала подключите MapLibre, затем `mahal_map.sdk.js`:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.css"
+/>
 <script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
-<script src="/dist/mahal_map.sdk.js?apikey=YOUR_API_KEY"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_API_KEY"></script>
 ```
 
-The browser SDK reads `apikey` from its script URL and stores it as the default API key for search and routing requests.
+После этого глобальный объект `MahalMap` доступен в `window`:
 
 ```html
+<div id="map" style="width: 100%; height: 500px"></div>
+
 <script>
   const map = MahalMap.create({
     container: "map",
@@ -70,67 +63,503 @@ The browser SDK reads `apikey` from its script URL and stores it as the default
 </script>
 ```
 
-## Search
-
-```ts
-import { Search, SearchByLocation } from "mahal_map";
-
-const results = await Search("Dushanbe", "");
-
-const nearby = await SearchByLocation({
-  lat: 38.5737,
-  lng: 68.7738,
-});
-```
-
-## Routing
-
-```ts
-import { Router } from "mahal_map";
-
-const routes = await Router(
-  [
-    [69.624024, 40.279687],
-    [68.7738, 38.5737],
-  ],
-  "geojson",
-  "",
-);
-```
-
-## Development
-
-```sh
-npm run build
-npm run build:sdk
-npm run build:all
-npm test
-```
-
-`npm run build` creates the npm package output. `npm run build:sdk` creates the browser IIFE SDK bundle.
-
-## Project Structure
-
-```text
-src/
-  index.ts
-  sdk.ts
-  config/
-  core/
-  markers/
-  services/
-  types/
-  utils/
-```
-
-- `index.ts` is the clean npm entrypoint.
-- `sdk.ts` is the browser SDK entrypoint that reads `apikey` from the script URL.
-- `core/` contains map and camera classes.
-- `markers/` contains marker components and adapters.
-- `services/` contains HTTP, auth key, search, and routing logic.
-- `types/` contains public TypeScript contracts.
-- `utils/` contains shared helpers and polyline utilities.
-
-## License
-
-ISC
+## Язык стиля карты
+
+По умолчанию используется таджикский стиль без query-параметра:
+
+```txt
+https://mtile.gram.tj/custom-styles/mapstyle.json
+https://mtile.gram.tj/custom-styles/dark-style.json
+```
+
+Для русского языка SDK добавляет `?lang=ru` к стандартным стилям:
+
+```txt
+https://mtile.gram.tj/custom-styles/mapstyle.json?lang=ru
+https://mtile.gram.tj/custom-styles/dark-style.json?lang=ru
+```
+
+Через NPM язык можно передать при создании карты:
+
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    lang: "ru",
+    theme: "dark",
+  },
+  maplibregl,
+);
+```
+
+Через browser SDK язык можно передать в URL скрипта:
+
+```html
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_API_KEY&lang=ru"></script>
+```
+
+Если `lang` не передан или передан `lang=tj`, стили остаются без параметра.
+
+## Параметры создания карты
+
+`MahalMap.create(options, maplibreObject?)`
+
+```ts
+interface IMahalMapOptions {
+  container?: string | HTMLElement;
+  style?: string;
+  theme?: "dark" | "light";
+  lang?: "tj" | "ru";
+  center?: [number, number];
+  zoom?: number;
+  autoAddVectorSource?: boolean;
+}
+```
+
+| Параметр | Тип | Описание |
+| --- | --- | --- |
+| `container` | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`. |
+| `style` | `string` | Пользовательский URL стиля MapLibre. Если передан, `theme` и `lang` не меняют URL стиля. |
+| `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`. |
+| `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL без query, `ru` добавляет `?lang=ru`. |
+| `center` | `[number, number]` | Центр карты в формате `[lng, lat]`. |
+| `zoom` | `number` | Начальный zoom. |
+| `autoAddVectorSource` | `boolean` | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`. |
+
+## MahalMap
+
+`MahalMap` - основной класс карты. Конструктор закрыт, карту нужно создавать через `MahalMap.create()`.
+
+### `MahalMap.create(options, maplibreObject?)`
+
+Создает новый инстанс карты и сохраняет его по ключу `container`.
+
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+    theme: "light",
+    lang: "tj",
+  },
+  maplibregl,
+);
+```
+
+В NPM-версии второй аргумент `maplibreObject` рекомендуется передавать явно. В browser SDK он берется из `window.maplibregl`.
+
+### `MahalMap.onReady(container, callback)`
+
+Вызывает `callback`, когда карта создана и MapLibre завершил загрузку.
+
+```ts
+MahalMap.onReady("map", (maplibreMap) => {
+  maplibreMap.resize();
+});
+```
+
+`callback` получает нативный `Map` объект из MapLibre GL JS.
+
+### `MahalMap.getInstance(container)`
+
+Возвращает ранее созданный инстанс карты по ключу контейнера.
+
+```ts
+const map = MahalMap.getInstance("map");
+map.setZoom(14);
+```
+
+Если инстанс не найден, будет выброшена ошибка.
+
+### `MahalMap.hasInstance(container)`
+
+Проверяет, существует ли карта с таким ключом контейнера.
+
+```ts
+if (MahalMap.hasInstance("map")) {
+  const map = MahalMap.getInstance("map");
+}
+```
+
+### `MahalMap.removeInstance(container)`
+
+Удаляет инстанс из внутреннего реестра и возвращает `boolean`.
+
+```ts
+const removed = MahalMap.removeInstance("map");
+```
+
+Метод удаляет только запись из реестра. Для полного удаления карты используйте `destroy()`.
+
+### `MahalMap.setDefaultLanguage(lang)`
+
+Задает язык по умолчанию для новых карт.
+
+```ts
+MahalMap.setDefaultLanguage("ru");
+
+const map = MahalMap.create({ container: "map" }, maplibregl);
+```
+
+После этого новые карты без `options.lang` будут использовать русский стандартный стиль. Для `tj` или пустого значения стандартные стили будут без query-параметра.
+
+## Методы инстанса карты
+
+### `map.getMap()`
+
+Возвращает нативный MapLibre `Map`.
+
+```ts
+const maplibreMap = map.getMap();
+maplibreMap.resize();
+```
+
+Используйте этот метод, если нужна функция MapLibre, которой нет в Mahal Map SDK.
+
+### `map.getCamera()`
+
+Возвращает `CameraController` для управления камерой.
+
+```ts
+const camera = map.getCamera();
+camera.flyTo({
+  center: [69.624024, 40.279687],
+  zoom: 14,
+});
+```
+
+### `map.setStyle(theme)`
+
+Переключает стандартную тему карты.
+
+```ts
+map.setStyle("dark");
+map.setStyle("light");
+```
+
+Если текущий язык `ru`, при переключении темы стиль будет загружен с `?lang=ru`. Если язык `tj`, URL будет без query-параметра.
+
+Метод не меняет стиль, если карта создана с `autoAddVectorSource: true`. Если карта создана с пользовательским `style`, SDK не переписывает этот URL.
+
+### `map.setLanguage(lang)`
+
+Переключает язык стандартного стиля карты.
+
+```ts
+map.setLanguage("ru");
+map.setLanguage("tj");
+```
+
+`ru` добавляет `?lang=ru`, `tj` возвращает стандартный URL без параметра. Метод не переписывает пользовательский `options.style` и не меняет vector style при `autoAddVectorSource: true`.
+
+### `map.setCenter(center)`
+
+Меняет центр карты.
+
+```ts
+map.setCenter([69.624024, 40.279687]);
+```
+
+Формат координат: `[lng, lat]`.
+
+### `map.setZoom(zoom)`
+
+Меняет zoom карты.
+
+```ts
+map.setZoom(13);
+```
+
+### `map.addMarker(marker)`
+
+Добавляет маркер на карту.
+
+```ts
+import { MahalMapDefaultMarker } from "mahal_map";
+
+const marker = new MahalMapDefaultMarker({
+  coordinates: [69.624024, 40.279687],
+  color: "#278960",
+});
+
+map.addMarker(marker);
+```
+
+Маркер должен реализовать интерфейс:
+
+```ts
+interface IMapMarker {
+  getElement(): HTMLElement;
+  getCoordinates(): [number, number];
+  isDraggable?(): boolean;
+  getAnchor?():
+    | "center"
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+}
+```
+
+### `map.destroy()`
+
+Удаляет логотип SDK, вызывает `remove()` у MapLibre карты и удаляет инстанс из внутреннего реестра.
+
+```ts
+map.destroy();
+```
+
+Используйте при размонтировании страницы или компонента.
+
+## Статические методы-обертки
+
+Для browser SDK и случаев, когда удобнее работать с функциями, доступны статические методы:
+
+```ts
+MahalMap.getMap(map);
+MahalMap.getCamera(map);
+MahalMap.setStyle(map, "dark");
+MahalMap.setLanguage(map, "ru");
+MahalMap.setCenter(map, [69.624024, 40.279687]);
+MahalMap.setZoom(map, 14);
+MahalMap.addMarker(map, marker);
+MahalMap.destroy(map);
+```
+
+Эти методы вызывают соответствующие методы переданного инстанса.
+
+## Browser SDK функции
+
+При подключении `mahal_map.sdk.js` функции доступны на глобальном объекте `MahalMap`.
+
+```js
+const map = MahalMap.create({
+  container: "map",
+  center: [69.624024, 40.279687],
+  zoom: 12,
+});
+
+MahalMap.setStyle(map, "dark");
+MahalMap.setLanguage(map, "ru");
+MahalMap.setZoom(map, 14);
+```
+
+Доступные функции карты в browser SDK:
+
+| Функция | Описание |
+| --- | --- |
+| `create(options)` | Создает карту. |
+| `onReady(container, callback)` | Выполняет callback после загрузки карты. |
+| `getInstance(container)` | Возвращает инстанс карты. |
+| `hasInstance(container)` | Проверяет наличие инстанса. |
+| `removeInstance(container)` | Удаляет инстанс из реестра. |
+| `getMap(instance)` | Возвращает нативный MapLibre Map. |
+| `getCamera(instance)` | Возвращает CameraController. |
+| `setStyle(instance, theme)` | Переключает тему стандартного стиля. |
+| `setLanguage(instance, lang)` | Переключает язык стандартного стиля. |
+| `setCenter(instance, center)` | Меняет центр карты. |
+| `setZoom(instance, zoom)` | Меняет zoom карты. |
+| `addMarker(instance, marker)` | Добавляет маркер. |
+| `destroy(instance)` | Полностью удаляет карту. |
+| `loadKeyFromScriptUrl()` | Читает `apikey` из URL SDK скрипта. |
+| `loadLanguageFromScriptUrl()` | Читает `lang` из URL SDK скрипта. |
+
+## CameraController
+
+`CameraController` доступен через `map.getCamera()` или `MahalMap.getCamera(map)`.
+
+### `camera.setZoom(zoom, smooth?)`
+
+Меняет zoom. Если `smooth` не передан, используется плавная анимация.
+
+```ts
+camera.setZoom(14);
+camera.setZoom(10, false);
+```
+
+### `camera.setBearing(bearing, smooth?)`
+
+Меняет поворот карты.
+
+```ts
+camera.setBearing(45);
+camera.setBearing(0, false);
+```
+
+### `camera.setPitch(pitch, smooth?)`
+
+Меняет наклон карты.
+
+```ts
+camera.setPitch(60);
+camera.setPitch(0, false);
+```
+
+### `camera.toggle3D(is3D)`
+
+Включает или выключает 3D-вид.
+
+```ts
+camera.toggle3D(true);
+camera.toggle3D(false);
+```
+
+При включении задается `pitch: 60`, при выключении `pitch: 0` и `bearing: 0`.
+
+### `camera.resetNorth()`
+
+Возвращает карту на север и сбрасывает наклон.
+
+```ts
+camera.resetNorth();
+```
+
+### `camera.flyTo(options)`
+
+Выполняет плавный перелет камеры. Принимает `FlyToOptions` из MapLibre GL JS.
+
+```ts
+camera.flyTo({
+  center: [69.624024, 40.279687],
+  zoom: 15,
+});
+```
+
+SDK добавляет стандартные значения `speed`, `curve` и `essential`, но переданные значения могут их переопределить.
+
+### `camera.getPitch()`
+
+Возвращает текущий наклон карты.
+
+```ts
+const pitch = camera.getPitch();
+```
+
+## MahalMapDefaultMarker
+
+`MahalMapDefaultMarker` - готовый маркер, который можно использовать с `map.addMarker()`.
+
+```ts
+import { MahalMapDefaultMarker } from "mahal_map";
+
+const marker = new MahalMapDefaultMarker({
+  coordinates: [69.624024, 40.279687],
+  color: "#278960",
+  draggable: true,
+  anchor: "bottom",
+});
+
+map.addMarker(marker);
+```
+
+Параметры:
+
+| Параметр | Тип | Описание |
+| --- | --- | --- |
+| `coordinates` | `[number, number]` | Координаты маркера в формате `[lng, lat]`. |
+| `draggable` | `boolean` | Делает HTML-элемент маркера draggable. |
+| `anchor` | `string` | Anchor MapLibre маркера. |
+| `color` | `string` | Цвет стандартного SVG маркера или замена `fill` в пользовательском SVG. |
+| `svg` | `string` | Полностью пользовательский SVG. |
+| `innerSvg` | `string` | SVG внутри стандартного маркера. |
+| `innerUrl` | `string` | URL изображения внутри стандартного маркера. |
+
+Методы маркера:
+
+```ts
+marker.getElement();
+marker.getCoordinates();
+marker.isDraggable();
+marker.getAnchor();
+```
+
+## Несколько карт
+
+Каждая карта сохраняется по ключу `container`.
+
+```ts
+const mainMap = MahalMap.create({ container: "main" }, maplibregl);
+const miniMap = MahalMap.create({ container: "mini" }, maplibregl);
+
+MahalMap.getInstance("main").setZoom(14);
+MahalMap.getInstance("mini").setStyle("dark");
+```
+
+Если `container` не передан, ключом будет `"map"`. Для нескольких карт всегда указывайте разные контейнеры.
+
+## Пользовательский стиль
+
+Можно передать любой MapLibre style URL:
+
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    style: "https://example.com/custom-style.json",
+  },
+  maplibregl,
+);
+```
+
+Когда передан `style`, SDK не добавляет `?lang=ru` и не подменяет URL при `setStyle()` или `setLanguage()`.
+
+## Жизненный цикл
+
+Рекомендуемый порядок работы:
+
+1. Создать DOM-контейнер.
+2. Создать карту через `MahalMap.create()`.
+3. Дождаться загрузки через `MahalMap.onReady()`, если нужен доступ к загруженной MapLibre карте.
+4. Добавлять маркеры, менять камеру, тему или язык.
+5. Вызвать `destroy()` при удалении страницы или компонента.
+
+```ts
+const map = MahalMap.create({ container: "map" }, maplibregl);
+
+MahalMap.onReady("map", () => {
+  map.setZoom(13);
+});
+
+// При размонтировании:
+map.destroy();
+```
+
+## Разработка
+
+```sh
+npm run build
+npm run build:sdk
+npm run build:all
+npm test
+```
+
+`npm run build` собирает npm entrypoint. `npm run build:sdk` собирает browser IIFE SDK bundle. `npm run build:all` запускает обе сборки.
+
+## Структура проекта
+
+```text
+src/
+  index.ts
+  sdk.ts
+  config/
+  core/
+  markers/
+  services/
+  types/
+  utils/
+```
+
+- `index.ts` - npm entrypoint.
+- `sdk.ts` - browser SDK entrypoint.
+- `core/` - карта и управление камерой.
+- `markers/` - маркеры и адаптеры.
+- `types/` - публичные TypeScript типы.
+
+## License
+
+ISC