aviation-chart 0.1.36 → 0.2.1

package/README.md

@@ -0,0 +1,170 @@
+# Kunyu Aviation Chart SDK
+
+A high-performance aviation chart SDK providing complete aeronautical data visualization: FIR/UIR, controlled and restricted airspace, airways, navaids (VOR/NDB), airports and runways, AMM, and terrain — plus business features such as NOTAM, ADS-B, and weather radar. Built with a modular architecture supporting plugins, performance optimization, and unified error handling.
+
+## ✨ Features
+
+- **Aviation data stack**: FIR, controlled/restricted airspace, airways, VOR/NDB, airport runways, AMM, terrain/contours — published per AIRAC period
+- **Theme switching**: in-place light/dark recoloring that never covers your overlay layers
+- **Business modules**: NOTAM, ADS-B, weather radar, raster layers
+- **Performance**: LOD (level-of-detail), lazy layer loading, massive-point clustering, low-zoom style simplification
+- **Plugin system**: unified plugin interface with a built-in measurement plugin
+- **Unified error handling**: centralized error management, fallback strategies, error statistics
+
+## 🚀 Getting Started
+
+### Option 1: CDN script (global `navMap`)
+
+```html
+<!-- latest -->
+<script src="https://aips.siniswift.com/sdk/nav-sdk.min.js"></script>
+<!-- or pin a version -->
+<!-- <script src="https://aips.siniswift.com/sdk/nav-sdk@0.2.0.min.js"></script> -->
+
+<div id="map" style="width:100%;height:600px;"></div>
+
+<script>
+  const sdk = new navMap.MapSDK({
+    container: 'map',
+    center: [116.3974, 39.9093],
+    zoom: 4,
+    theme: 'light',        // 'light' | 'dark'
+    period: '202606',      // AIRAC period; auto-computed if omitted
+  });
+</script>
+```
+
+> The underlying map engine is bundled into `nav-sdk.min.js` — no extra script needed.
+
+### Option 2: npm
+
+```bash
+npm install aviation-chart
+```
+
+```javascript
+import { MapSDK, MeasurePlugin } from 'aviation-chart';
+
+const sdk = new MapSDK({
+  container: 'map',
+  center: [116.3974, 39.9093],
+  zoom: 4,
+  performance: { lodEnabled: true, clusteringEnabled: true, lazyLoadingEnabled: true },
+});
+```
+
+## 📚 API Overview
+
+### Initialization options
+
+| Option | Description |
+|---|---|
+| `container` | Container id or element (required) |
+| `center` / `zoom` | Initial center and zoom |
+| `theme` | `'light'` / `'dark'` |
+| `period` | AIRAC period `YYYYMM` |
+| `apiUrl` | Chart data service URL, default `https://aips.siniswift.com` |
+| `layers` | Initial layer visibility, e.g. `{ airspace: true, controlled: false, terrain: false }` |
+| `performance` | `{ lodEnabled, clusteringEnabled, lazyLoadingEnabled }` |
+| `errorHandler` | Custom error handler function |
+
+### Layer control
+
+Layer groups: `airspace` (FIR), `airline` (airways), `controlled`, `restricted`, `vor`, `ndb`, `airport`, `runway`, `adiz`, `waypointOffAirway`, `amm`, `terrain`, `contour`, `background`, `landLayer`, `boundary`.
+
+```javascript
+// Two equivalent APIs
+sdk.setLayerVisible('airspace', true);
+sdk.addBuiltInLayer('controlled');
+sdk.toggleBuiltInLayer('airline');
+sdk.removeBuiltInLayer('restricted');
+
+// Theme and period
+sdk.setTheme('dark');
+sdk.setPeriod('202609');
+
+// LOD
+sdk.layerManager.setLODEnabled(true);
+```
+
+### Feature drawing (GeoJSON)
+
+```javascript
+sdk.addPoint([lng, lat], properties, style);
+sdk.addLine(coordinates, properties, style);
+sdk.addPolygon(coordinates, properties, style);
+
+// Cluster massive point sets
+sdk.geoJSONManager.setClusteringEnabled(true);
+```
+
+### Business features
+
+```javascript
+sdk.notam.open(true);          // NOTAM
+sdk.adsb.open();               // ADS-B
+sdk.api.getRadarData();        // weather radar data
+```
+
+### Popup
+
+```javascript
+const popup = new navMap.Popup()
+  .setLngLat([lng, lat])
+  .setHTML('<h3>Title</h3>')
+  .addTo(sdk.map);
+```
+
+### Plugins
+
+```javascript
+const measure = new navMap.MeasurePlugin();
+sdk.use(measure);
+measure.enable('distance');    // 'distance' | 'area'
+measure.disable();
+
+const plugin = sdk.getPlugin('measure');
+```
+
+### Underlying engine passthrough
+
+The SDK passes through the full underlying map-engine API — call methods directly on the instance, or access the raw instance via `sdk.map`:
+
+```javascript
+sdk.flyTo({ center: [lng, lat], zoom: 8 });
+sdk.setPaintProperty('airline', 'line-color', '#0057c8');
+sdk.queryRenderedFeatures([x, y]);
+
+const map = sdk.map;  // raw map instance
+```
+
+### Error & performance
+
+```javascript
+const sdk = new navMap.MapSDK({
+  container: 'map',
+  errorHandler: (error) => console.error(error.code, error.details),
+});
+
+sdk.getErrorStats();        // error statistics
+sdk.getPerformanceStats();  // performance statistics
+```
+
+## 🔧 Writing a Plugin
+
+```javascript
+export class MyPlugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  install(sdk) { /* install logic */ }
+  uninstall(sdk) { /* uninstall logic */ }
+}
+
+const plugin = new MyPlugin();
+sdk.use(plugin);
+sdk.pluginManager.hasPlugin('my-plugin');
+```
+
+## 📄 License
+
+MIT License

package/dist/MapSDK.d.ts

@@ -0,0 +1,128 @@
+import { Map as MaplibreMap, StyleSpecification, GeoJSONSourceSpecification, FlyToOptions } from "maplibre-gl";
+import type { MapSDKOptions, IMapSDK, StyleConfig, ILayerManager, IGeoJSONManager, IPlugin, LayerConfig, StyleImageMetadata, LayerRef, HtmlFunction } from "./types";
+import { ADSB } from "./managers/ADSBManager";
+import { NOTAM } from "./managers/NotamManager";
+import { HoverManager } from "./managers/HoverManage";
+import { ClickManager } from "./managers/ClickManager";
+import { RasterManager } from "./managers/RasterManager";
+import { GraticuleManager, GraticuleConfig } from "./managers/Graticule";
+import API from "./apis";
+import { SelectFeature } from "./managers/SelectFeature";
+import { LineLabelOptimizer } from "./managers/LineLabelOptimizer";
+import { Theme } from "./managers/ThemeManage";
+import { WindManager } from "./managers/WindManager";
+export declare class MapSDK implements IMapSDK {
+    map: MaplibreMap;
+    layerManager: ILayerManager;
+    geoJSONManager: IGeoJSONManager;
+    private performanceManager;
+    private pluginManager;
+    private isDestroyed;
+    adsb: ADSB;
+    notam: NOTAM;
+    hover: HoverManager;
+    clickObj: ClickManager;
+    rasterManager: RasterManager;
+    graticule: GraticuleManager;
+    api: API;
+    selector: SelectFeature;
+    lineLabelOptimizer: LineLabelOptimizer;
+    theme: Theme;
+    wind: WindManager;
+    private initialOptions;
+    private _baseUrl;
+    private _landGeojson;
+    private _chartApiUrl;
+    readonly ready: Promise<void>;
+    private _resolveReady;
+    private _rejectReady;
+    get globalConfig(): import("./managers/GlobalConfigManager").GlobalConfigManager;
+    get absb(): ADSB;
+    constructor(options: MapSDKOptions);
+    private initializeMap;
+    private setupMapEventListeners;
+    private handleZoomChange;
+    private initializeManagers;
+    private initializeDefaultLayers;
+    private initializeADSB;
+    private initializeNOTAM;
+    private initializeHover;
+    private initializeCLick;
+    private initialRaster;
+    private initializeGraticule;
+    private initializeSelector;
+    private initializeLabelOptimizer;
+    private initializeTheme;
+    private initializeChartFeatures;
+    private initializeAviationLayers;
+    setCenter(center: [number, number]): void;
+    setZoom(zoom: number): void;
+    setPitch(pitch: number): void;
+    setBearing(bearing: number): void;
+    fitBounds(bounds: [[number, number], [number, number]], options?: any): void;
+    addBuiltInLayer(layerName: string, zindex: string): Promise<void>;
+    removeBuiltInLayer(layerName: string): void;
+    toggleBuiltInLayer(layerName: string): void;
+    toggleLayer(layerName: string): void;
+    showLayer(layerName: string): void;
+    hideLayer(layerName: string): void;
+    clickLayer(layerName: LayerRef, callback: (e: any) => void): void;
+    getBuiltInLayers(): Object;
+    isBuiltInLayerVisible(layerId: string): boolean;
+    updateLayerStyle(layerId: string, style: StyleConfig): void;
+    toggleFullScreen(state: boolean): void;
+    private _snapshotVisibleLayers;
+    private _restoreAfterStyleLoad;
+    setMapStyle(style: string | StyleSpecification, options?: {
+        diff?: boolean;
+    }): Promise<void>;
+    setTheme(theme: "light" | "dark"): void;
+    private _themeLayerDefs;
+    private _applyThemedProps;
+    restoreLandLayer(): void;
+    addPoint(coordinates: [number, number], properties?: Record<string, any>, style?: StyleConfig, id?: string): string;
+    addLine(coordinates: [], properties?: Record<string, any>, style?: StyleConfig, id?: string): string;
+    addPolygon(coordinates: [], properties?: Record<string, any>, style?: StyleConfig, id?: string): string;
+    addGeoJSON(sourceId: string, geojson?: any, props?: GeoJSONSourceSpecification | null | undefined): any;
+    addLayer(layerConfig: LayerConfig): void;
+    hoverLayer(layers: LayerRef, cb: (e: any) => void): void;
+    hoverPopup(layerId: LayerRef, f: HtmlFunction): () => void;
+    clickPopup(layerId: LayerRef, f: HtmlFunction): () => void;
+    showLayers(layerIds: string[]): void;
+    hideLayers(layerIds: string[]): void;
+    setLayerVisible(key: string, visible: boolean): void;
+    flyTo(option: FlyToOptions, eventData?: any): void;
+    on(event: string, listenerOrLayerId?: string | Function, listener?: Function): void;
+    off(event: string, listenerOrLayerId?: string | Function, listener?: Function): void;
+    getCenter(): [number, number];
+    getZoom(): number;
+    getBounds(): [[number, number], [number, number]];
+    use(plugin: IPlugin): void;
+    getPlugin<T extends IPlugin>(name: string): T | undefined;
+    getPerformanceStats(): {
+        visibleLayers: number;
+        queuedLayers: number;
+        lodEnabled: boolean;
+        clusteringEnabled: boolean;
+        lazyLoadingEnabled: boolean;
+    };
+    getErrorStats(): void;
+    setPeriod(period: string): void;
+    getPeriod(): string | undefined;
+    generateCurrentPeriod(): Promise<string>;
+    showGraticule(): void;
+    hideGraticule(): void;
+    toggleGraticule(): void;
+    updateGraticuleConfig(config: Partial<GraticuleConfig>): void;
+    isGraticuleVisible(): boolean;
+    get showTileBoundaries(): boolean;
+    set showTileBoundaries(value: boolean);
+    enableLineLabelDedup(lineLayerId: string, lineLabelId: string, builtInKey: string, fieldList?: string[], suffix?: string): void;
+    disableLineLabelDedup(): void;
+    private reinitializeMap;
+    registerIcon(id: string, url: string, options?: StyleImageMetadata): Promise<void>;
+    setStyle(style: object): void;
+    private processGlobalConfig;
+    private getCustomLayerStyles;
+    destroy(): void;
+}

package/dist/apis/index.d.ts

@@ -0,0 +1,60 @@
+type NotamDetailParams = {
+    notamSeries: string;
+    notamNoPart1: string;
+    notamNoPart2: string;
+    nof: string;
+    pageNo: number;
+    pageSize: number;
+    signal?: AbortSignal | null;
+};
+type NotamListParams = {
+    pageNo: number;
+    pageSize: number;
+    onlyGeojson: boolean;
+    typeC: boolean;
+    notamOffset: string;
+    isInternational: boolean;
+    isCompanyVersion: boolean;
+    signal?: AbortSignal | null;
+};
+type NotamDataParams = {
+    pageNo: number;
+    pageSize: number;
+    nof: string;
+    itemA: string;
+    itemB: string;
+    itemC: string;
+    notamSeries: string;
+    notamNoPart1: string;
+    notamNoPart2: string;
+    notamTypeIds: string;
+    onlyValid: boolean;
+    moduleName: string;
+    topic: string;
+    notamCode: string;
+    signal: AbortSignal | null;
+};
+type TyphoonVolcanoAshParams = {
+    AdvisoryText: string;
+    signal?: AbortSignal | null;
+};
+type RunwayDataParams = {
+    AirportCode: string;
+    DataPeriod: string;
+    signal?: AbortSignal | null;
+};
+export declare class API {
+    constructor();
+    _baseUrl: string;
+    setBaseUrl(baseUrl: string): void;
+    notam_list(params: NotamListParams | {}): Promise<Response>;
+    notam_detail(params: NotamDetailParams | {}): Promise<Response>;
+    notam_data(params: NotamDataParams): Promise<Response>;
+    typhoon_volcano_ash(params: TyphoonVolcanoAshParams | {}): Promise<Response>;
+    getRunwayData(params: RunwayDataParams): Promise<Response>;
+    getRadarData(signal?: AbortSignal | null): Promise<Response>;
+    getPeriodData(signal?: AbortSignal | null): Promise<Response>;
+    getIndexData(data: any, signal?: AbortSignal | null): Promise<Response>;
+    getAirportPoint(airport: string, signal?: AbortSignal | null): Promise<unknown>;
+}
+export default API;

package/dist/constants/aviation-sources.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_CHART_API_URL = "https://aips.siniswift.com";
+export declare function getAviationBaseStyle(opts: {
+    apiUrl: string;
+    spriteUrl?: string;
+    background: string;
+}): any;
+export declare function navdataTilesUrl(apiUrl: string, period: string): string;
+export declare function getNavdataSource(apiUrl: string, period: string): {
+    type: "vector";
+    tiles: string[];
+    minzoom: number;
+    maxzoom: number;
+};
+export declare function getChartAmmSource(apiUrl: string): {
+    type: "vector";
+    tiles: string[];
+    minzoom: number;
+    maxzoom: number;
+};
+export declare function getTerrainSource(apiUrl: string, terrainUrl?: string | null): {
+    type: "raster-dem";
+    tiles: string[];
+    tileSize: number;
+    maxzoom: number;
+};
+export declare const TERRAIN_COLOR_RAMP: (string | number | string[])[];
+export declare function getTerrainLayers(): any[];
+export declare function fetchGzJson(url: string, headers?: Record<string, string>): Promise<any>;

package/dist/constants/builtin-layers.d.ts

@@ -0,0 +1,3 @@
+export declare const TYPEMAP: Record<string, string[]>;
+export declare const DEFAULT_LAYER_VISIBILITY: Record<string, boolean>;
+export declare const GROUP_ALIASES: Record<string, string>;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { MapSDK } from './MapSDK';
+export { LayerManager } from './managers/LayerManager';
+export { GeoJSONManager } from './managers/GeoJSONManager';
+export { ErrorManager } from './managers/ErrorManager';
+export { PerformanceManager } from './managers/PerformanceManager';
+export { PluginManager } from './managers/PluginManager';
+export { globalConfig, GlobalConfigManager } from './managers/GlobalConfigManager';
+export { MeasurePlugin } from './plugins/MeasurePlugin';
+export { DrawPlugin } from './plugins/DrawPlugin';
+export type { IMapSDK, ILayerManager, IGeoJSONManager, IPlugin, MapSDKOptions, LayerConfig, BuiltInLayer, GeoJSONFeature, GeoJSONCollection, StyleConfig, SDKError, ErrorHandler, LODConfig, ClusteringConfig, MapEvent, EventListener, HookContext, HookCallback, HookRegistry } from './types';
+export { TYPEMAP, GROUP_ALIASES, DEFAULT_LAYER_VISIBILITY } from './constants/builtin-layers';
+export { NOTAM } from "./managers/NotamManager";
+export { WindManager } from "./managers/WindManager";
+export type { WindFrame, WindOptions } from "./managers/WindManager";
+export { MapSDK as default } from './MapSDK';
+export { Popup } from './managers/PopupManager';
+export { API } from './apis';
+export * as MapEngine from "maplibre-gl";
+export { MapSDK as AviationChart } from './MapSDK';
+export { Marker, LngLat, LngLatBounds } from 'maplibre-gl';
+export { CHART_THEMES, LAYER_GROUPS, LAYER_LABELS } from './style/aviation-chart.js';