mahal_map 1.4.8 → 1.5.0

package/README.md

@@ -1,43 +1,136 @@
 # Mahal Map
 
-Mahal Map - это JavaScript API-библиотека для работы с картами на основе MapLibre GL JS.
+Mahal Map is a JavaScript/TypeScript SDK for working with Mahal map services on top of MapLibre GL JS.
 
-## Установка
+## Installation
 
 ```sh
-npm install maplibre-gl
+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.
 
-```javascript
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import * as MahalMap from "mahal_map";
+## 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"
+/>
+<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>
+```
+
+The browser SDK reads `apikey` from its script URL and stores it as the default API key for search and routing requests.
+
+```html
+<script>
+  const map = MahalMap.create({
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+  });
+</script>
+```
 
-const mahalMap = MahalMap.MahalMap.create({}, maplibregl);
-const map = mahalMap.getMap();
+## Search
+
+```ts
+import { Search, SearchByLocation } from "mahal_map";
+
+const results = await Search("Dushanbe", "");
+
+const nearby = await SearchByLocation({
+  lat: 38.5737,
+  lng: 68.7738,
+});
 ```
 
-## Сборка проекта
+## Routing
 
-Для сборки используйте Rollup:
+```ts
+import { Router } from "mahal_map";
 
-```sh
-npm run build
+const routes = await Router(
+  [
+    [69.624024, 40.279687],
+    [68.7738, 38.5737],
+  ],
+  "geojson",
+  "",
+);
 ```
 
-## Запуск в режиме разработки
+## Development
 
 ```sh
-npm run dev
+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/
+```
 
-- `axios` - HTTP-клиент для работы с API
-- `rollup` - инструмент для сборки JavaScript
+- `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.
+ISC

package/dist/index.d.mts

@@ -1,42 +1,16 @@
-import { Map, FlyToOptions } from 'maplibre-gl';
+import { Map, FlyToOptions, Marker } from 'maplibre-gl';
+import * as axios from 'axios';
 
-interface ISearchParam {
-    text: string;
-    lat?: string;
-    lng?: string;
-    token: string;
-    type?: string;
-    limit?: number;
-}
-interface ISearchByLocationParam {
-    lat: string | number;
-    lng: string | number;
-    token?: string;
-    type?: string;
-}
-interface ISearch {
-    fullAddress: string;
-    latitude: number;
-    longitude: number;
-    type: string;
-    distance: number | null;
-    detailInfo: {
-        categories: string;
-        name: string;
-    };
-    detailDetail: {
-        city: string | null;
-        city_type: string | null;
-        street_name: string | null;
-        street_type: string | null;
-        subject_name: string | null;
-        subject_type: string | null;
-    };
-}
-interface ISearchResponse {
-    success: boolean;
-    data: ISearch[];
-    message?: string;
+declare class CameraController {
+    private map;
+    constructor(map: Map);
+    setZoom(zoom: number, smooth?: boolean): void;
+    setBearing(bearing: number, smooth?: boolean): void;
+    setPitch(pitch: number, smooth?: boolean): void;
+    toggle3D(is3D: boolean): void;
+    resetNorth(): void;
+    flyTo(options: FlyToOptions): void;
+    getPitch(): number;
 }
 
 interface IAdditionalParamType {
@@ -46,6 +20,31 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+interface IMahalMapOptions {
+    container?: string | HTMLElement;
+    style?: string;
+    theme?: "dark" | "light";
+    center?: [number, number];
+    zoom?: number;
+    autoAddVectorSource?: boolean;
+}
+
+interface MahalMapDefaultMarkerProps {
+    coordinates: [number, number];
+    draggable?: boolean;
+    anchor?: "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    color?: string;
+    svg?: string;
+    innerSvg?: string;
+    innerUrl?: string;
+}
+interface IMapMarker {
+    getElement(): HTMLElement;
+    getCoordinates(): [number, number];
+    isDraggable?(): boolean;
+    getAnchor?(): "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+}
+
 interface IRoute {
     id: number;
     type: string;
@@ -78,71 +77,75 @@ interface IRoute {
     };
 }
 
-interface IMahalMapOptions {
-    container?: string | HTMLDocument;
-    style?: string;
-    theme?: "dark" | "light";
-    center?: [number, number];
-    zoom?: number;
-    autoAddVectorSource?: boolean;
-    attributionControl: boolean;
-}
-
-interface MahalMapDefaultMarkerProps {
-    coordinates: [number, number];
-    draggable?: boolean;
-    anchor?: "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
-    color?: string;
-    svg?: string;
-    innerSvg?: string;
-    innerUrl?: string;
+interface ISearchParam {
+    text: string;
+    lat?: string;
+    lng?: string;
+    token: string;
+    type?: string;
+    limit?: number;
 }
-interface IMapMarker {
-    getElement(): HTMLElement;
-    getCoordinates(): [number, number];
-    isDraggable?(): boolean;
-    getAnchor?(): "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface ISearchByLocationParam {
+    lat: string | number;
+    lng: string | number;
+    token?: string;
+    type?: string;
 }
-
-declare class CameraController {
-    private map;
-    constructor(map: Map);
-    setZoom(zoom: number, smooth?: boolean): void;
-    setBearing(bearing: number, smooth?: boolean): void;
-    setPitch(pitch: number, smooth?: boolean): void;
-    toggle3D(is3D: boolean): void;
-    resetNorth(): void;
-    flyTo(options: FlyToOptions): void;
-    getPitch(): number;
+interface ISearchResponse {
+    longitude: number;
+    latitude: number;
+    fullAddress: string;
+    type: string;
+    distance: number | null;
+    detailInfo: {
+        categories: string;
+        name: string;
+    };
+    detailDetail: {
+        city: string | null;
+        city_type: string | null;
+        street_name: string | null;
+        street_type: string | null;
+        subject_name: string | null;
+        subject_type: string | null;
+    };
 }
 
-declare class MahalMapDefaultMarker {
-    private props;
-    private element;
-    constructor(props: MahalMapDefaultMarkerProps);
-    private createElement;
-    private applyColorToCustomSvg;
-    getElement(): HTMLElement;
-    getCoordinates(): [number, number];
-    isDraggable(): boolean;
-    getAnchor(): "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface IReponse<T> {
+    success: boolean;
+    data: T;
+    message: string;
 }
 
+type MapLibreApi = {
+    Map: new (...args: ConstructorParameters<typeof Map>) => Map;
+    Marker: new (...args: ConstructorParameters<typeof Marker>) => Marker;
+};
 declare class MahalMap {
-    private static instance;
+    private static instances;
     private isReady;
     private readyCallbacks;
     private map;
     private maplibre;
     private camera;
+    private logoElement?;
     private options;
+    private instanceKey;
     private constructor();
-    static create(options: IMahalMapOptions, maplibreObject?: {
-        Map: typeof Map;
-    } | typeof Map): MahalMap;
-    static onReady(callback: (map: Map) => void): void;
-    static getInstance(): MahalMap;
-    addMarker(marker: IMapMarker): any;
+    private static getInstanceKey;
+    static create(options: IMahalMapOptions, maplibreObject?: MapLibreApi): MahalMap;
+    static onReady(container: string, callback: (map: Map) => void): void;
+    static getInstance(container: string): MahalMap;
+    static hasInstance(container: string): boolean;
+    static removeInstance(container: string): boolean;
+    static addMarker(instance: MahalMap, marker: IMapMarker): Marker;
+    static getCamera(instance: MahalMap): CameraController;
+    static getMap(instance: MahalMap): Map;
+    static setStyle(instance: MahalMap, theme: "dark" | "light"): void;
+    static setCenter(instance: MahalMap, center: [number, number]): void;
+    static setZoom(instance: MahalMap, zoom: number): void;
+    static destroy(instance: MahalMap): void;
+    addMarker(marker: IMapMarker): Marker;
     init(map: Map): void;
     getCamera(): CameraController;
     getMap(): Map;
@@ -150,39 +153,65 @@ declare class MahalMap {
     setCenter(center: [number, number]): void;
     setZoom(zoom: number): void;
     destroy(): void;
+    private addLogo;
+    private updateLogoColor;
+    private getLogoSvg;
 }
 
+declare function saveKey(param: string): void;
+declare function clearKey(): void;
+declare const getApiKey: () => string;
+
+declare const api: axios.AxiosInstance;
+
+declare function Router(param: number[][], typeData: string, token: string): Promise<IRoute[]>;
+
 declare function Search(param: string, token: string, additionalParam?: IAdditionalParamType): Promise<ISearchResponse>;
 declare function SearchByLocation(params: ISearchByLocationParam): Promise<ISearchResponse>;
 
-declare function Router(param: number[][], typeData: string, token: string): Promise<IRoute[]>;
+declare const index$1_Router: typeof Router;
+declare const index$1_Search: typeof Search;
+declare const index$1_SearchByLocation: typeof SearchByLocation;
+declare const index$1_api: typeof api;
+declare const index$1_clearKey: typeof clearKey;
+declare const index$1_getApiKey: typeof getApiKey;
+declare const index$1_saveKey: typeof saveKey;
+declare namespace index$1 {
+  export { index$1_Router as Router, index$1_Search as Search, index$1_SearchByLocation as SearchByLocation, index$1_api as api, index$1_clearKey as clearKey, index$1_getApiKey as getApiKey, index$1_saveKey as saveKey };
+}
+
+declare class MahalMapDefaultMarker {
+    private props;
+    private element;
+    constructor(props: MahalMapDefaultMarkerProps);
+    private createElement;
+    private applyColorToCustomSvg;
+    getElement(): HTMLElement;
+    getCoordinates(): [number, number];
+    isDraggable(): boolean;
+    getAnchor(): "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+}
+
+declare function checkCoordinates(coordinates: string): {
+    lat: string | undefined;
+    lng: string | undefined;
+} | null;
 
 declare function debounce<F extends (...args: any[]) => Promise<any>>(fn: F, delay: number): (...args: Parameters<F>) => Promise<ReturnType<F>>;
 
-declare const index_debounce: typeof debounce;
-declare namespace index {
-  export { index_debounce as debounce };
-}
+declare function geojsonPolyline(encoded: string): number[][];
 
-declare function saveKey(param: string): void;
-declare function clearKey(): void;
-declare const getApiKey: () => string;
+declare function geometryPolyline(coordinates: number[][]): string;
 
-declare const keyUtils_clearKey: typeof clearKey;
-declare const keyUtils_getApiKey: typeof getApiKey;
-declare const keyUtils_saveKey: typeof saveKey;
-declare namespace keyUtils {
-  export { keyUtils_clearKey as clearKey, keyUtils_getApiKey as getApiKey, keyUtils_saveKey as saveKey };
-}
+declare function trimValue(value: string, cut: number): string;
 
-declare const MMap: {
-  MahalMap: typeof MahalMap;
-  MahalMapDefaultMarker: typeof MahalMapDefaultMarker;
-  Search: typeof Search;
-  SearchByLocation: typeof SearchByLocation;
-  Router: typeof Router;
-  keyUtils: typeof keyUtils;
-  loadKeyFromScriptUrl: () => string;
-};
+declare const index_checkCoordinates: typeof checkCoordinates;
+declare const index_debounce: typeof debounce;
+declare const index_geojsonPolyline: typeof geojsonPolyline;
+declare const index_geometryPolyline: typeof geometryPolyline;
+declare const index_trimValue: typeof trimValue;
+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 { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IRoute, type ISearch, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, Router, Search, SearchByLocation, MMap as default, keyUtils, index as utils };
+export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IReponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, Router, Search, SearchByLocation, index$1 as keyUtils, index as utils };