@aapicoits/powermap-web-sdk 1.0.0 → 1.1.0

package/README.md

@@ -945,16 +945,42 @@ map.on('geometrySelectionChanged', ({ features }) => {
 
 ## 16. 🏠 Indoor Mapping
 
-The PowerMap SDK provides a robust API for managing indoor environments, including floor switching, category filtering, and specialized geometry handling.
+The PowerMap SDK provides a robust API for managing indoor environments with **OGC IMDF 1.0.0 Full Compliance** — supporting all 16 standard feature types, ZIP archive import/export, and schema validation.
 
-### 16.1 Enabling Indoor Mode
+> [!TIP]
+> For the complete IMDF reference including all feature types, properties, archive format, and validation — see [GEOMETRY.md](./GEOMETRY.md#ogc-imdf-100-compliance)
+
+### 16.1 Indoor Venue Selection (NEW)
 
-Switch to indoor mode to enable building-specific logic and specialized drawing tools (e.g., Beacons, Walkways).
+The new `loadIndoorMap()` API lets you select and activate a venue from pre-loaded data. It handles mode switching, floor detection, and camera fitting automatically.
 
 ```javascript
-map.setMode('indoor');
+// 1. Load data from your API
+const data = await fetch('/api/venues/siam-paragon/features').then(r => r.json());
+map.geometry.import(data);
+
+// 2. Select venue → auto enters indoor mode
+const result = map.loadIndoorMap('siam_paragon');
+console.log(result.floors);       // [0, 1, 2, 3, 4]
+console.log(result.currentFloor); // 0
+
+// 3. Switch floors
+map.setFloor(2);  // Convenience alias for map.indoor.setFloor()
+
+// 4. Query venue metadata
+map.indoor.getVenueInfo();   // { id, name, floors, bounds, buildingCount }
+map.indoor.getFloorInfo(2);  // { name, unitCount, poiCount, beaconCount }
+
+// 5. Exit
+map.unloadIndoorMap();
 ```
 
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `loadIndoorMap(venueId, opts)` | `{ venue, floors, currentFloor }` | Select venue, enter indoor mode, fit bounds |
+| `setFloor(level, opts)` | `PowerMap` | Convenience alias for `map.indoor.setFloor()` |
+| `unloadIndoorMap()` | `PowerMap` | Exit indoor mode, clear selection |
+
 ### 16.2 Floor Management (`map.indoor`)
 
 When in indoor mode, use the `map.indoor` facade to control the vertical context of the map.
@@ -964,6 +990,11 @@ When in indoor mode, use the `map.indoor` facade to control the vertical context
 | `setFloor(ordinal, opts)` | `number, Object` | Switch to a specific floor level (e.g., 1, 2, -1). |
 | `getAvailableFloors()` | - | Returns a sorted array of all unique floor ordinals found in the map data. |
 | `getCurrentFloor()` | - | Returns the ordinal of the currently active floor. |
+| `getActiveVenue()` | - | Returns the currently selected venue feature or `null`. |
+| `getVenues()` | - | Lists all venue features in loaded data. |
+| `getVenueInfo()` | - | Summary of active venue (name, floors, bounds, building count). |
+| `getFloorInfo(ordinal)` | `number` | Floor details (unit count, POI count, beacon count). |
+| `getBuildings()` | - | Lists all building features in loaded data. |
 
 #### Switching Floors with Animation
 
@@ -992,19 +1023,58 @@ map.indoor.setCategoryVisible('walkway', true);   // Navigation Paths
 map.indoor.setCategoryVisible('obstacle', true);  // 3D Obstacles/Buildings
 ```
 
-### 16.4 Indoor Data Kinds
+### 16.4 Indoor Data Kinds (IMDF Compliant)
 
-The SDK categorizes indoor features using the `user_kind` (or `kind`) property:
+The SDK categorizes indoor features using `user_kind` (or `kind`) mapped to OGC IMDF `feature_type`:
 
-- **floor**: The walkable surface area of a floor (Polygon).
-- **obstacle**: Non-walkable areas. Can be extruded into 3D.
-- **walkway**: Navigable path lines for indoor routing.
-- **poi**: Indoor points of interest with custom icons.
-- **beacon**: Positioning hardware or logical points.
+| SDK Kind | IMDF Feature Type | Geometry | Description |
+| :--- | :--- | :--- | :--- |
+| `venue` | venue | Polygon | Main venue (mall, airport) |
+| `building` | building | Polygon | Building within venue |
+| `floor` | level | Polygon | Floor plan surface |
+| `unit` | unit | Polygon | Room, corridor, area |
+| `opening` | opening | LineString | Door, gate, passage |
+| `amenity` | amenity | Point | ATM, restroom, etc. |
+| `anchor` | anchor | Point | Reference point |
+| `footprint` | footprint | Polygon | Building shadow |
+| `fixture` | fixture | Polygon | Furniture, permanent |
+| `section` | section | Polygon | Zone, terminal |
+| `geofence` | geofence | Polygon | Virtual fence |
+| `kiosk` | kiosk | Polygon | Service booth |
+| `detail` | detail | LineString | Crosswalk, railing |
+| `beacon` | anchor (beacon) | Point | BLE beacon device |
+| `poi` | anchor (poi) | Point | Point of interest |
+| `walkway` | pathway | LineString | Indoor navigation path |
+| `obstacle` | unit (restricted) | Polygon | Non-walkable area |
+
+### 16.5 IMDF Archive & Validation
 
-### 16.5 Event Synchronization
+```javascript
+import { IMDFArchive, IMDFValidator } from '@powermap/web-sdk';
+
+// Export as IMDF ZIP archive
+const blob = await IMDFArchive.toArchive(map.geometry.export());
+
+// Import IMDF ZIP archive
+const fc = await IMDFArchive.fromArchive(zipFile);
+map.geometry.import(fc);
+
+// Validate IMDF data
+const result = IMDFValidator.validate(map.geometry.export());
+if (!result.valid) console.error(result.errors);
+```
+
+> [!NOTE]
+> IMDF Archive requires [JSZip](https://stuk.github.io/jszip/) as an optional dependency.
+
+### 16.6 Event Synchronization
 
 ```javascript
+// Listen for venue selection
+map.on('indoorMapLoaded', ({ venue, floors, currentFloor }) => {
+  console.log(`Entered: ${venue.properties?.name?.en}`);
+});
+
 // Listen for mode changes
 map.on('onModeChanged', ({ mode }) => {
   console.log(`Mode switched to: ${mode}`); // 'standard' or 'indoor'
@@ -1114,6 +1184,9 @@ The SDK emits the following events through its central `EventBus`. You can subsc
 | Event | Payload | Description |
 |---|---|---|
 | `floorChanged` | `ordinal (number)` | Fired when the active indoor floor changes. |
+| `venueChanged` | `VenueInfo` | Fired when the active venue selection changes. |
+| `indoorMapLoaded` | `{ venue, floors, currentFloor }` | Fired when a venue is successfully selected via `loadIndoorMap()`. |
+| `indoorMapUnloaded` | `-` | Fired when indoor mode is exited via `unloadIndoorMap()`. |
 
 ### 🗺️ Routing & Navigation
 | Event | Payload | Description |

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+// ============================================================
+// PowerMap Web SDK — TypeScript Declaration File
+// Auto-generated from src/index.js JSDoc
+// ============================================================
+
+export interface PowerMapAuthOptions {
+  clientId: string;
+  clientSecret: string;
+}
+
+export interface PowerMapOptions {
+  /** The HTML element ID or element reference to mount the map into */
+  container: string | HTMLElement;
+  /** Initial map center as [longitude, latitude] */
+  center?: [number, number];
+  /** Initial zoom level */
+  zoom?: number;
+  /** Minimum zoom level */
+  minZoom?: number;
+  /** Maximum zoom level */
+  maxZoom?: number;
+  /** Map style name: 'th' | 'en' | 'dark' | 'gray' or a custom style URL */
+  style?: 'th' | 'en' | 'dark' | 'gray' | string;
+  /** API Key for map tiles */
+  mapApiKey: string;
+  /** Authentication credentials for services */
+  auth: PowerMapAuthOptions;
+  /** Disable all map interactions (zoom, pan, rotate) — preview mode */
+  previewOnly?: boolean;
+}
+
+export interface MarkerOptions {
+  /** [longitude, latitude] */
+  position: [number, number];
+  /** Marker type */
+  type?: 'start' | 'destination' | 'waypoint' | string;
+  /** Custom image URL */
+  iconUrl?: string;
+  /** Custom hex color for pinpoint marker (e.g. '#ff4444') */
+  color?: string;
+  /** FontAwesome icon class (e.g. 'fas fa-car') */
+  icon?: string;
+  /** Enable marker dragging */
+  draggable?: boolean;
+  /** HTML content or structured popup object */
+  popupContent?: string | { title?: string; body?: string; tag?: string; footer?: string };
+  /** Unique identifier for the marker */
+  id?: string;
+}
+
+export interface MarkerInstance {
+  id: string;
+  position: [number, number];
+  remove(): void;
+  setLngLat(lngLat: [number, number]): this;
+  getLngLat(): { lng: number; lat: number };
+  [key: string]: unknown;
+}
+
+export interface RouteOptions {
+  start: [number, number];
+  destination: [number, number];
+  waypoints?: [number, number][];
+  optimize?: boolean;
+  [key: string]: unknown;
+}
+
+export interface RouteStep {
+  distance: number;
+  distanceStr: string;
+  duration: number;
+  durationStr: string;
+  instruction?: string;
+  [key: string]: unknown;
+}
+
+export interface RouteDetails {
+  distance: number;
+  distanceStr: string;
+  duration: number;
+  durationStr: string;
+  steps: RouteStep[];
+}
+
+export interface RouteSummary {
+  distanceStr: string;
+  durationStr: string;
+}
+
+export interface SearchResult {
+  id: string;
+  name: string;
+  address?: string;
+  position: [number, number];
+  [key: string]: unknown;
+}
+
+export interface SearchOptions {
+  location?: [number, number];
+  lang?: string;
+  [key: string]: unknown;
+}
+
+export interface FlyToOptions {
+  center?: [number, number];
+  zoom?: number;
+  pitch?: number;
+  bearing?: number;
+  speed?: number;
+  curve?: number;
+  [key: string]: unknown;
+}
+
+export interface FitBoundsOptions {
+  padding?: number | { top: number; bottom: number; left: number; right: number };
+  maxZoom?: number;
+  [key: string]: unknown;
+}
+
+export type PowerMapEventName =
+  | 'mapLoaded'
+  | 'mapClick'
+  | 'mapLongClick'
+  | 'markerClick'
+  | 'markerDrag'
+  | 'markerDragEnd'
+  | 'poiClick'
+  | 'routeCalculated'
+  | 'modeChanged'
+  | 'floorChanged'
+  | 'venueChanged'
+  | 'indoorMapLoaded'
+  | 'indoorMapUnloaded'
+  | 'error'
+  | string;
+
+export type PowerMapMode = 'standard' | 'indoor';
+
+export interface SetModeOptions {
+  buildingId?: string;
+  floorId?: string;
+  center?: [number, number];
+  [key: string]: unknown;
+}
+
+// ── IMDF Types ──────────────────────────────────────────────────────────────────
+
+/** OGC IMDF 1.0.0 Feature Types */
+export type IMDFFeatureType =
+  | 'venue' | 'building' | 'level' | 'unit' | 'opening' | 'amenity'
+  | 'anchor' | 'footprint' | 'fixture' | 'section' | 'geofence'
+  | 'kiosk' | 'detail' | 'occupant' | 'address' | 'relationship'
+  | 'pathway';
+
+/** SDK internal kind names */
+export type GeometryKind =
+  | 'venue' | 'building' | 'floor' | 'unit' | 'opening' | 'amenity'
+  | 'anchor' | 'footprint' | 'fixture' | 'section' | 'geofence'
+  | 'kiosk' | 'detail' | 'occupant' | 'address' | 'relationship'
+  | 'beacon' | 'poi' | 'walkway' | 'obstacle';
+
+/** Category visibility toggles */
+export type CategoryType = 'poi' | 'beacon' | 'walkway' | 'obstacle';
+
+/** IMDF LABELS object (i18n) */
+export interface IMDFLabels {
+  [languageCode: string]: string;
+}
+
+// ── Indoor Types ────────────────────────────────────────────────────────────────
+
+export interface VenueInfo {
+  id: string;
+  name: string;
+  category: string;
+  floors: number[];
+  bounds: [[number, number], [number, number]] | null;
+  buildingCount: number;
+}
+
+export interface VenueListItem {
+  id: string;
+  name: string;
+  category: string;
+  feature: object;
+}
+
+export interface FloorInfo {
+  id: string;
+  name: string;
+  shortName: string;
+  ordinal: number;
+  outdoor: boolean;
+  unitCount: number;
+  poiCount: number;
+  beaconCount: number;
+}
+
+export interface BuildingInfo {
+  id: string;
+  name: string;
+  category: string;
+}
+
+export interface LoadIndoorMapOptions {
+  initialFloor?: number;
+  fitBounds?: boolean;
+  fitBoundsOptions?: FitBoundsOptions;
+  animate?: boolean;
+}
+
+export interface LoadIndoorMapResult {
+  venue: object;
+  floors: number[];
+  currentFloor: number;
+}
+
+export interface FloorSwitchOptions {
+  animate?: boolean;
+  duration?: number;
+}
+
+// ── FloorManager ────────────────────────────────────────────────────────────────
+
+export interface FloorManager {
+  /** Set the current floor ordinal with optional animation */
+  setFloor(ordinal: number, options?: FloorSwitchOptions): Promise<FloorManager>;
+  /** Get all unique floor ordinals present in the map */
+  getAvailableFloors(): number[];
+  /** Get the current floor ordinal */
+  getCurrentFloor(): number;
+  /** Set visibility for a category of indoor objects */
+  setCategoryVisible(type: CategoryType, visible: boolean): FloorManager;
+  /** Get the currently active venue feature */
+  getActiveVenue(): object | null;
+  /** List all venue features available in loaded geometry */
+  getVenues(): VenueListItem[];
+  /** Get summary information about the currently active venue */
+  getVenueInfo(): VenueInfo | null;
+  /** Get detailed information about a specific floor */
+  getFloorInfo(ordinal: number): FloorInfo | null;
+  /** List all building features in loaded geometry */
+  getBuildings(): BuildingInfo[];
+}
+
+// ── GeometryQuery ───────────────────────────────────────────────────────────────
+
+export interface GeometryQuery {
+  byKind(kind: GeometryKind): GeometryQuery;
+  byFloor(ordinal: number): GeometryQuery;
+  byType(type: 'Point' | 'Polygon' | 'LineString'): GeometryQuery;
+  where(prop: string, op: 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'exists', value?: unknown): GeometryQuery;
+  byFeatureType(featureType: IMDFFeatureType): GeometryQuery;
+  byVenueId(venueId: string): GeometryQuery;
+  byBuildingId(buildingId: string): GeometryQuery;
+  byLevelId(levelId: string): GeometryQuery;
+  toArray(): object[];
+  first(): object | null;
+  count(): number;
+  ids(): string[];
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────────
+
+export interface ValidationError {
+  code: string;
+  message: string;
+  featureId?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+
+// ── GeometryManager ─────────────────────────────────────────────────────────────
+
+export interface GeometryManager {
+  query(): GeometryQuery;
+  create(kind: GeometryKind, options?: object): string | null;
+  add(geojson: object): void;
+  update(id: string, patch: object): void;
+  remove(id: string): void;
+  getById(id: string): object | null;
+  getByKind(kind: GeometryKind): object[];
+  getGeoJSON(id: string, options?: { format: 'imdf' | 'standard' }): object | null;
+  export(options?: { format: 'imdf' | 'standard' }): object;
+  import(geojson: object, options?: { format: 'imdf' | 'standard' }): GeometryManager;
+  exportArchive?(): Promise<Blob>;
+  importArchive?(file: Blob | File): Promise<void>;
+  clear(): void;
+}
+
+// ── PowerMap Main Class ─────────────────────────────────────────────────────────
+
+/**
+ * PowerMap SDK Main Class
+ *
+ * Provides a high-level API for map rendering, markers, routing,
+ * indoor navigation, and vehicle simulation.
+ *
+ * @example
+ * const map = new PowerMap({
+ *   container: 'map',
+ *   mapApiKey: 'YOUR_KEY',
+ *   auth: { clientId: '...', clientSecret: '...' }
+ * })
+ * .on('mapLoaded', () => console.log('Ready!'))
+ * .setStyle('dark');
+ */
+export declare class PowerMap {
+  constructor(options: PowerMapOptions);
+
+  // --- Events ---
+  on(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
+  off(event: PowerMapEventName, callback: (...args: unknown[]) => void): this;
+  onMapLoaded(callback: (data: { map: PowerMap }) => void): this;
+  onClick(callback: (event: unknown) => void): this;
+  onMapLongClick(callback: (event: unknown) => void): this;
+  onMarkerClick(callback: (data: { marker: MarkerInstance; originalEvent: unknown; options: unknown }) => void): this;
+  onPoiClick(callback: (data: { feature: unknown; lngLat: unknown; point: unknown }) => void): this;
+  onMarkerDrag(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
+  onMarkerDragEnd(callback: (data: { marker: MarkerInstance; lngLat: [number, number] }) => void): this;
+  onRouteCalculated(callback: (route: unknown) => void): this;
+  onError(callback: (error: Error) => void): this;
+
+  // --- Map Style & Mode ---
+  setStyle(name: 'th' | 'en' | 'dark' | 'gray' | string): this;
+  setMode(mode: PowerMapMode, options?: SetModeOptions): this;
+
+  // --- Controls ---
+  setNavigationControl(options: boolean | object): this;
+  setFullscreenControl(options: boolean | object): this;
+
+  // --- Camera ---
+  flyTo(options: FlyToOptions): this;
+  easeTo(options: FlyToOptions): this;
+  fitBounds(bounds: [[number, number], [number, number]], options?: FitBoundsOptions): this;
+  jumpTo(options: FlyToOptions): this;
+  setPitch(pitch: number, animate?: boolean): this;
+  setBearing(bearing: number, animate?: boolean): this;
+  zoomIn(): this;
+  zoomOut(): this;
+  rotateLeft(): this;
+  rotateRight(): this;
+  getCenter(): { lng: number; lat: number };
+  getZoom(): number;
+  getPitch(): number;
+  getBearing(): number;
+
+  // --- Markers ---
+  addMarker(options: MarkerOptions): MarkerInstance;
+  getMarker(id: string): MarkerInstance | null;
+  removeMarker(markerOrId: MarkerInstance | string): this;
+  updatePopup(marker: MarkerInstance, content: string | object): this;
+  clearMarkers(): this;
+
+  // --- Routing ---
+  addRoute(options: RouteOptions): Promise<unknown>;
+  clearRoutes(): this;
+  getRouteDetails(): RouteDetails | null;
+  getRouteSummary(): RouteSummary | null;
+  formatDistance(meters: number): string;
+  formatDuration(seconds: number): string;
+
+  // --- Search ---
+  search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+
+  // --- Layers ---
+  showLayer(layerId: string): Promise<this>;
+  hideLayer(layerId: string): this;
+  toggleLayer(layerId: string): Promise<this>;
+
+  // --- Indoor Venue Selection ---
+  /** Select and activate an indoor venue from already-loaded geometry data */
+  loadIndoorMap(venueId: string, options?: LoadIndoorMapOptions): LoadIndoorMapResult;
+  /** Convenience alias for map.indoor.setFloor() */
+  setFloor(level: number, options?: FloorSwitchOptions): this;
+  /** Exit indoor mode and clear the active venue selection */
+  unloadIndoorMap(): this;
+
+  // --- Managers (advanced access) ---
+  readonly layers: unknown;
+  readonly geometry: GeometryManager;
+  readonly indoor: FloorManager;
+  readonly editor: unknown;
+  debug(): unknown;
+}
+
+// ── IMDF Utilities ──────────────────────────────────────────────────────────────
+
+export declare class IMDFConverter {
+  static MAPPING: Record<GeometryKind, { feature_type: string; category: string }>;
+  static IMDF_CATEGORIES: Record<string, string[]>;
+  static REQUIRED_PROPERTIES: Record<string, string[]>;
+  static toIMDF(featureCollection: object): object;
+  static fromIMDF(imdfCollection: object): object;
+}
+
+export declare class IMDFArchive {
+  static toArchive(featureCollection: object, options?: { JSZip?: unknown }): Promise<Blob>;
+  static fromArchive(archiveData: Blob | File | ArrayBuffer, options?: { JSZip?: unknown }): Promise<object>;
+  static generateManifest(featureCollection: object): object;
+}
+
+export declare class IMDFValidator {
+  static validate(featureCollection: object, options?: { strict?: boolean }): ValidationResult;
+}