@aapicoits/powermap-web-sdk 1.1.0 → 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
@@ -695,22 +720,60 @@ const map = new PowerMap({
 
 ## 12. 🔍 Search & Geocoding
 
-The Web SDK provides built-in search capabilities using the PowerMap Search API.
+The Web SDK provides built-in search capabilities using the PowerMap Search API with automatic script detection, smart field fallbacks, and cross-endpoint query handling.
 
 ### `search(query, options)`
 
 Available options:
 
-- `lang`: `'th'` (default) or `'en'`.
-- `location`: `[latitude, longitude]` to prioritize nearby results.
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `lang` | `string` | `'auto'` | Language mode: `'auto'`, `'th'`, or `'en'`. In `'auto'` mode, script type is detected automatically from Unicode ranges. |
+| `location` | `[lat, lng]` | `-` | `[latitude, longitude]` coordinate pair to prioritize nearby search results. |
+
+#### Automatic Script Detection & Fallbacks
+- **`lang: 'auto'`**: Automatically inspects query characters. Thai queries (`[\u0E00-\u0E7F]`) select Thai search services, while English/Latin queries (`[a-zA-Z]`) select English search services.
+- **Mixed Script Handling**: For mixed search terms (e.g. `"Central บางนา"` or `"BTS อโศก"`), if primary search yields no results or contains mixed scripts, the SDK automatically executes a cross-endpoint fallback search and merges unique results.
+- **Smart Field Mapping**: `name` and `address` automatically default to the preferred query language with automatic fallback (`nameEn` -> `nameTh` -> `name` or `nameTh` -> `nameEn` -> `name`), ensuring titles and addresses are never returned as empty strings.
+
+#### Returned `SearchResult` Properties
+
+Each item in the returned array contains:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `id` / `gid` | `string` | Unique identifier for the POI. |
+| `name` | `string` | Display name in the preferred language with automatic fallback. |
+| `nameEn` | `string` | English name of the place (with Thai fallback). |
+| `nameTh` | `string` | Thai name of the place (with English fallback). |
+| `address` | `string` | Formatted address in the preferred language with fallback. |
+| `addressEn` | `string` | Formatted English address string. |
+| `addressTh` | `string` | Formatted Thai address string. |
+| `position` | `[lat, lng]` | Coordinate pair `[latitude, longitude]` (compatible with Mobile SDK). |
+| `positionLngLat` | `[lng, lat]` | Coordinate pair `[longitude, latitude]` for Web map view manipulation. |
+| `province` / `amphoe` / `tambon` | `string` | Administrative boundary details. |
+| `postCode` | `string` | Postal code if available. |
+| `rawData` | `Object` | Raw Elasticsearch GeoJSON source payload. |
+
+### Search Examples
 
 ```javascript
-const results = await map.search("Central World", { lang: 'en' });
+// 1. Auto language detection (Recommended)
+const results = await map.search("Central World");
 
 results.forEach(item => {
-  console.log(`${item.name}: ${item.address}`);
-  console.log(`Position: ${item.position}`); // [lat, lng]
+  console.log(`${item.name} (${item.nameTh}): ${item.address}`);
+  console.log(`Position [lat, lng]:`, item.position);
 });
+
+// 2. Explicit English search with location prioritization
+const enResults = await map.search("Siam Paragon", {
+  lang: 'en',
+  location: [13.746, 100.534] // [lat, lng]
+});
+
+// 3. Mixed query (Thai + English)
+const mixedResults = await map.search("BTS อโศก", { lang: 'auto' });
 ```
 
 ---
@@ -1011,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`:
@@ -1099,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.
@@ -1151,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)`.

package/dist/index.d.ts

@@ -88,16 +88,27 @@ export interface RouteSummary {
 }
 
 export interface SearchResult {
-  id: string;
+  id?: string;
+  gid?: string;
   name: string;
+  nameEn?: string;
+  nameTh?: string;
   address?: string;
+  addressEn?: string;
+  addressTh?: string;
   position: [number, number];
+  positionLngLat?: [number, number];
+  province?: string;
+  amphoe?: string;
+  tambon?: string;
+  postCode?: string;
+  rawData?: Record<string, unknown>;
   [key: string]: unknown;
 }
 
 export interface SearchOptions {
   location?: [number, number];
-  lang?: string;
+  lang?: 'th' | 'en' | 'auto' | string;
   [key: string]: unknown;
 }