@aapicoits/powermap-web-sdk 1.1.1 → 1.2.0

package/README.md

@@ -469,6 +469,31 @@ if (details) {
 const summary = map.getRouteSummary(); // { distanceStr, durationStr }
 ```
 
+### 9.1 Built-in Routing UI (Routing Panel)
+
+The SDK provides a built-in outdoor routing panel that automatically handles searching, waypoint management, and turn-by-turn navigation UI.
+
+```javascript
+// Add the routing panel to the map
+const routingControl = new PowerMap.RoutingPanelControl({
+  defaultProfile: 'driving', // 'driving', 'foot', 'bicycle', 'motorcycle'
+  onLocationSelect: (location) => {
+    console.log("Selected Location:", location);
+  },
+  onRouteCalculated: (routeResult) => {
+    console.log("Route calculated:", routeResult);
+  },
+  onClear: () => {
+    console.log("Route cleared");
+  }
+});
+
+map.addControl(routingControl);
+
+// Programmatically clear the routing panel and map route
+// routingControl.clear();
+```
+
 ---
 
 ## 🏗️ 10. Map Layers Management
@@ -1049,18 +1074,6 @@ const floors = map.indoor.getAvailableFloors();
 // Returns: [1, 2, 3] or [] if no indoor data is found
 ```
 
-### 16.3 Visibility Control
-
-Toggle the visibility of specific indoor data categories. These settings persist across floor changes.
-
-```javascript
-// Toggle individual categories
-map.indoor.setCategoryVisible('poi', true);       // Points of Interest
-map.indoor.setCategoryVisible('beacon', false);   // Beacons/Sensors
-map.indoor.setCategoryVisible('walkway', true);   // Navigation Paths
-map.indoor.setCategoryVisible('obstacle', true);  // 3D Obstacles/Buildings
-```
-
 ### 16.4 Indoor Data Kinds (IMDF Compliant)
 
 The SDK categorizes indoor features using `user_kind` (or `kind`) mapped to OGC IMDF `feature_type`:
@@ -1137,6 +1150,117 @@ The SDK provides built-in productivity shortcuts whenever the geometry engine is
 
 ---
 
+## 17. 🏢 Indoor API & Mapping
+
+The PowerMap SDK includes a dedicated `IndoorAPI` and UI controls to easily build indoor navigation and mapping applications. The indoor modules are initialized lazily and are available under `map.indoor`.
+
+### 17.1 The `IndoorAPI`
+
+The `IndoorAPI` automatically utilizes the SDK's `AuthManager` to handle authentication securely and allows you to fetch hierarchy data and perform searches within venues.
+
+```javascript
+// Fetch all venues available for the user
+const venues = await map.indoor.api.getVenues();
+
+// Fetch buildings in a specific venue
+const buildings = await map.indoor.api.getBuildings(venueId);
+
+// Fetch floors in a specific building
+const floors = await map.indoor.api.getFloors(buildingId);
+
+// Fetch raw GeoJSON for a specific floor to render on the map
+const geojson = await map.indoor.api.getFloorGeoJSON(floorId);
+```
+
+### 17.2 Indoor Search
+
+You can search for Points of Interest (POIs) across your indoor map using the built-in search API. **Note: Searching requires a `buildingId` to ensure performance and accuracy.**
+
+```javascript
+// Search within a specific building (buildingId is REQUIRED)
+const results = await map.indoor.api.search('coffee', { buildingId: 'bld-1234' });
+
+// Search with a limit
+const limitedResults = await map.indoor.api.search('coffee', { 
+    buildingId: 'bld-1234',
+    limit: 10 
+});
+
+// Example output
+// [
+//   { 
+//      id: 'poi-1', name: 'Starbucks', category: 'cafe', 
+//      x: 100.5, y: 13.7, floorId: 'fl-1', floorNumber: 'G' 
+//   }
+// ]
+```
+
+### 17.3 Indoor UI Controls
+
+The SDK provides ready-to-use UI components such as the `IndoorFloorControl`, which renders a sleek, floating floor selector that automatically updates when you switch buildings.
+
+```javascript
+import { IndoorFloorControl } from '@powermap/web-sdk';
+
+// 1. Initialize the control
+const floorControl = new IndoorFloorControl({
+    onChange: (floorId, floorInfo) => {
+        console.log("Selected floor:", floorInfo.name);
+        // Load the floor GeoJSON onto the map here...
+    }
+});
+
+// 2. Add to the map (top-right corner)
+map.mapManager.map.addControl(floorControl, 'top-right');
+
+// 3. Feed it data from the IndoorAPI
+const floors = await map.indoor.api.getFloors('bld-1234');
+const formattedFloors = floors.map(f => ({
+    id: f.id,
+    name: f.floorNumber,
+    score: parseInt(f.floorNumber) || 0
+}));
+
+// Sort top to bottom, then pass to control
+formattedFloors.sort((a, b) => b.score - a.score);
+floorControl.setFloors(formattedFloors);
+
+// 4. Update the active floor programmatically
+floorControl.setActiveFloor('fl-1');
+```
+
+### 17.4 Indoor Routing (Premium UI)
+
+The SDK provides a built-in `IndoorRouter` and a complete `IndoorRoutingPanelControl` UI for searching POIs and calculating indoor paths across different floors. 
+
+The router integrates directly with the Indoor API and automatically manages multi-floor rendering, step-by-step instructions, and origin/destination markers.
+
+```javascript
+import { IndoorRoutingPanelControl } from '@powermap/web-sdk';
+
+// 1. Initialize the Routing Panel Control
+const routingPanel = new IndoorRoutingPanelControl({
+    buildingId: 'bld-1234',
+    router: map.indoor.router, // Provided automatically by the SDK
+    onFloorChange: (floorId) => {
+        // Automatically called when a user clicks a route step on a different floor
+        // Use this callback to change your visual background maps or floor selector UI
+        console.log("Routing requested switch to floor:", floorId);
+        floorControl.setActiveFloor(floorId);
+    }
+});
+
+// 2. Add to the map (top-right corner, below the floor selector)
+map.mapManager.map.addControl(routingPanel, 'top-right');
+```
+
+The `IndoorRoutingPanelControl` features:
+- **Built-in POI Search**: Users can type in the input fields to search for POIs via the backend.
+- **Auto-Switching Floors**: When a route is calculated, the SDK automatically switches to the origin floor and pans the camera.
+- **Layer Management**: The `IndoorRouter` handles drawing the route lines and rendering start/end markers on the correct floor.
+
+---
+
 ## 18. 🩺 Debug & Telemetry
 
 Enable the Debug HUD during development to monitor performance and coordinates.
@@ -1189,6 +1313,55 @@ For contributors to the SDK core:
 
 ---
 
+## 16. 🏢 Indoor Map UI Controls
+
+The SDK provides ready-to-use UI controls specifically designed for indoor mapping, ensuring a seamless user experience when navigating inside buildings.
+
+### 16.1 Indoor Floor Selector (`IndoorFloorControl`)
+
+A control that allows users to manually switch between floors in a building. It automatically updates its UI when `setFloors` or `setActiveFloor` is called.
+
+```javascript
+const floorControl = new PowerMap.IndoorFloorControl({
+  onChange: (floorId) => {
+    console.log(`User changed to floor: ${floorId}`);
+    // Your logic to switch the map's visible floor
+  }
+});
+map.addControl(floorControl, 'bottom-right');
+
+// Set available floors (e.g., from your venue data)
+floorControl.setFloors([
+  { id: '1', name: 'G' },
+  { id: '2', name: 'M' },
+  { id: '3', name: '1' }
+]);
+
+// Set the active highlighted floor
+floorControl.setActiveFloor('1');
+```
+
+### 16.2 Indoor Routing Panel (`IndoorRoutingPanelControl`)
+
+A premium UI control for indoor navigation. It handles searching for indoor POIs, selecting start/end points within a building, and displaying turn-by-turn indoor directions (including elevators and escalators).
+
+```javascript
+const indoorRoutingControl = new PowerMap.IndoorRoutingPanelControl({
+  buildingId: 'bldg-12345',
+  router: map.indoor.router, // Your IndoorRouter instance
+  onLocationSelect: (location) => {
+    console.log("Selected indoor location:", location);
+  }
+});
+
+map.addControl(indoorRoutingControl, 'top-left');
+
+// Programmatically clear the indoor routing panel
+// indoorRoutingControl.clear();
+```
+
+---
+
 ## 📌 Appendix A: Complete SDK Event List
 
 The SDK emits the following events through its central `EventBus`. You can subscribe to them via `map.on(eventName, callback)`.