@aapicoits/powermap-web-sdk 1.0.1 → 1.1.1

package/README.md

@@ -695,22 +695,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' });
 ```
 
 ---
@@ -945,16 +983,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)
 
-Switch to indoor mode to enable building-specific logic and specialized drawing tools (e.g., Beacons, Walkways).
+### 16.1 Indoor Venue Selection (NEW)
+
+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 +1028,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 +1061,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`:
+
+| 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
+
+```javascript
+import { IMDFArchive, IMDFValidator } from '@powermap/web-sdk';
 
-- **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.
+// Export as IMDF ZIP archive
+const blob = await IMDFArchive.toArchive(map.geometry.export());
 
-### 16.5 Event Synchronization
+// 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 +1222,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 |