npm - mahal_map - Versions diffs - 1.5.2 → 1.5.4 - Mend

mahal_map 1.5.2 → 1.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -1,565 +1,571 @@
-# 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="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_API_KEY"></script>
-```
-После этого глобальный объект `MahalMap` доступен в `window`:
-```html
-<div id="map" style="width: 100%; height: 500px"></div>
-<script>
-  const map = MahalMap.create({
-    container: "map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
-  });
-</script>
-```
-## Язык стиля карты
-По умолчанию используется таджикский стиль без 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
+# 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, keyUtils } from "mahal_map";
+keyUtils.saveKey("YOUR_MAP_API_KEY");
+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`. Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
+```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="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+```
+После этого глобальный объект `MahalMap` доступен в `window`:
+```html
+<div id="map" style="width: 100%; height: 500px"></div>
+<script>
+  const map = MahalMap.create({
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+  });
+</script>
+```
+## Язык стиля карты
+`keyUtils` хранит только токен доступа к карте, стилям и тайлам. Этот токен добавляется в URL стандартного стиля как `token`.
+По умолчанию используется таджикский стиль:
+```txt
+https://mtile.gram.tj/custom-styles/mapstyle.json?token=YOUR_MAP_API_KEY
+https://mtile.gram.tj/custom-styles/dark-style.json?token=YOUR_MAP_API_KEY
+```
+Для русского языка SDK добавляет `lang=ru` к стандартным стилям:
+```txt
+https://mtile.gram.tj/custom-styles/mapstyle.json?token=YOUR_MAP_API_KEY&lang=ru
+https://mtile.gram.tj/custom-styles/dark-style.json?token=YOUR_MAP_API_KEY&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_MAP_API_KEY&lang=ru"></script>
+```
+Если `lang` не передан или передан `lang=tj`, SDK добавляет только `token`.
+## Параметры создания карты
+`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` и map token не меняют URL стиля. |
+| `theme` | `"dark" \| "light"` | Тема стандартного стиля. По умолчанию используется `light`. |
+| `lang` | `"tj" \| "ru"` | Язык стандартного стиля. `tj` оставляет URL только с `token`, `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`. Для стандартных стилей перед созданием карты должен быть сохранен map token через `keyUtils.saveKey()`. В browser SDK token читается из обязательного URL-параметра `apikey`.
+```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");
+keyUtils.saveKey("YOUR_MAP_API_KEY");
+const map = MahalMap.create({ container: "map" }, maplibregl);
+```
+После этого новые карты без `options.lang` будут использовать русский стандартный стиль. Для `tj` или пустого значения стандартные стили будут только с `token`.
+## Методы инстанса карты
+### `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`, при переключении темы стиль будет загружен с `token=...&lang=ru`. Если язык `tj`, URL будет только с `token=...`.
+Метод не меняет стиль, если карта создана с `autoAddVectorSource: true`. Если карта создана с пользовательским `style`, SDK не переписывает этот URL.
+### `map.setLanguage(lang)`
+Переключает язык стандартного стиля карты.
+```ts
+map.setLanguage("ru");
+map.setLanguage("tj");
+```
+`ru` добавляет `lang=ru`, `tj` возвращает стандартный URL только с `token=...`. Метод не переписывает пользовательский `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)` | Создает карту. Требует `apikey` в URL SDK скрипта. |
+| `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 не добавляет `token` или `lang=ru` и не подменяет URL при `setStyle()` или `setLanguage()`.
+## Жизненный цикл
+Рекомендуемый порядок работы:
+1. Создать DOM-контейнер.
+2. Сохранить map token через `keyUtils.saveKey()` или передать `apikey` в URL browser SDK.
+3. Создать карту через `MahalMap.create()`.
+4. Дождаться загрузки через `MahalMap.onReady()`, если нужен доступ к загруженной MapLibre карте.
+5. Добавлять маркеры, менять камеру, тему или язык.
+6. Вызвать `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