@mapslibvn/react-native 0.4.0 → 0.5.0

package/README.md

@@ -1,8 +1,100 @@
 # @mapslibvn/react-native
 
-Bọc `@maplibre/maplibre-react-native` để hiện bản đồ MapsLibVN trong app React Native (Expo hoặc bare),
-API bám `@mapslibvn/react`. Yêu cầu React ≥ 19.1, React Native ≥ 0.80, New Architecture, Expo ≥ 54
-(không chạy trên Expo Go). Hướng dẫn: trang "React Native" trong docs; app thử: `examples/embed-rn`.
+[![npm version](https://img.shields.io/npm/v/@mapslibvn/react-native.svg)](https://www.npmjs.com/package/@mapslibvn/react-native)
+[![npm downloads](https://img.shields.io/npm/dm/@mapslibvn/react-native.svg)](https://www.npmjs.com/package/@mapslibvn/react-native)
+[![license](https://img.shields.io/npm/l/@mapslibvn/react-native.svg)](https://www.npmjs.com/package/@mapslibvn/react-native)
+
+**Native maps and voice-guided navigation for Vietnam, built for React Native.** `@mapslibvn/react-native` wraps `@maplibre/maplibre-react-native` behind the same API shape as [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react), so a team that already ships the web SDK can bring the exact same mental model to iOS and Android.
+
+Works with Expo (bare or managed, not Expo Go) and bare React Native apps alike. Example app: `examples/embed-rn`.
+
+## Why teams pick it
+
+- 📱 **Same API as the web SDK** — `<MapsLibVNMap>`, `<Marker>`, `useMap()`, `usePlaces()` — if your team already knows `@mapslibvn/react`, there's almost nothing new to learn.
+- 🧭 **Turn-by-turn navigation that survives your app** — `createNavigationSession()` runs independently of any mounted map component. It keeps going across screen transitions, so you can pop up a full-screen navigation view on top of your existing app (ride-hailing style) without losing state.
+- 🔊 **Voice guidance that keeps talking, even locked** — background location updates and Vietnamese TTS continue to work with the screen locked, verified on real hardware (not just a simulator).
+- 🧩 **Opt-in Expo integration** — location, background task, speech, audio-session and keep-awake support ship through the `@mapslibvn/react-native/expo` entry point, as optional peer dependencies. Not using navigation? You don't install any of them. Building a bare app? Swap in your own GPS/audio source.
+- 🔐 **Privacy-conscious by default** — only requests "When In Use" location permission, never "Always".
+- 🚀 **New Architecture ready** — built and tested against React Native's New Architecture and current Expo SDKs.
+
+## Requirements
+
+React ≥ 19.1, React Native ≥ 0.80, New Architecture, Expo ≥ 54 (does not run on Expo Go). Full guide: the "React Native" page in the docs.
+
+## Install
+
+```bash
+npm install @mapslibvn/react-native
+npx expo install @maplibre/maplibre-react-native expo-application
+```
+
+## Quick start
+
+```tsx
+import { MapsLibVNMap, Marker } from '@mapslibvn/react-native';
+
+<MapsLibVNMap
+  apiKey="mlv_live_…"
+  apiBase="https://api.ai-solutions.io.vn"
+  bundleId="vn.example.app"
+  containerStyle={{ flex: 1 }}
+>
+  <Marker lng={106.6981} lat={10.7725} />
+</MapsLibVNMap>;
+```
+
+Mobile keys must be scoped to your bundle/application id. Don't hide or disable attribution.
+
+## Turn-by-turn navigation
+
+```tsx
+// index.ts — global scope, before registerRootComponent
+import { defineNavigationTask } from '@mapslibvn/react-native/expo';
+defineNavigationTask();
+```
+
+```tsx
+import { MapsLibVNMap, createClient, createNavigationSession, useNavigation } from '@mapslibvn/react-native';
+import { expoNavigation } from '@mapslibvn/react-native/expo';
+
+const client = createClient({ apiKey, baseUrl: apiBase });
+const session = createNavigationSession({ provider: client, ...expoNavigation() }); // lives outside the React tree
+
+const response = await client.directions({ from: [10.7798, 106.699], to: [10.7725, 106.698], mode: 'motorbike' });
+await session.start({ response });               // GPS even when locked, Vietnamese voice, auto-reroute on drift
+
+<MapsLibVNMap {...props} navigation={session} />  // mounts to draw the route, puck and follow camera; unmounting doesn't stop the session
+const { status, progress } = useNavigation(session); // usable anywhere
+```
+
+You'll need `npx expo install expo-location expo-task-manager expo-speech expo-audio` plus the corresponding `app.json` plugin config (see docs). Have your own GPS pipeline? Pass your own `source` instead of `expoNavigation()`.
+
+📖 Docs: <https://mapslibvn-docs.pages.dev/react-native/> and <https://mapslibvn-docs.pages.dev/dan-duong-react-native/>
+
+📦 Part of the MapsLibVN SDK family: [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core) · [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react)
+
+Source license: MIT; see `THIRD_PARTY_NOTICES.md` for dependency and data licenses.
+
+---
+
+## Tiếng Việt
+
+**Bản đồ native và dẫn đường có giọng nói cho Việt Nam, dành cho React Native.** `@mapslibvn/react-native` bọc `@maplibre/maplibre-react-native` theo đúng hình dạng API của [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react), nên một đội đã dùng SDK web có thể mang nguyên mô hình tư duy đó sang iOS và Android.
+
+Dùng được với cả Expo (bare hoặc managed, không chạy trên Expo Go) và app React Native bare. App thử: `examples/embed-rn`.
+
+## Vì sao nên chọn
+
+- 📱 **Cùng API với SDK web** — `<MapsLibVNMap>`, `<Marker>`, `useMap()`, `usePlaces()` — nếu đội đã quen `@mapslibvn/react` thì gần như không phải học gì mới.
+- 🧭 **Dẫn đường sống độc lập với app** — `createNavigationSession()` chạy tách khỏi bất kỳ component bản đồ nào đang gắn. Phiên vẫn tiếp tục qua các lần chuyển màn hình, nên có thể bật một view dẫn đường toàn màn hình đè lên app hiện có (kiểu app gọi xe) mà không mất trạng thái.
+- 🔊 **Giọng đọc không tắt kể cả khi khoá máy** — định vị nền và TTS tiếng Việt vẫn hoạt động khi khoá màn hình, đã xác nhận trên máy thật (không chỉ trên giả lập).
+- 🧩 **Tích hợp Expo theo kiểu tuỳ chọn** — định vị, background task, giọng đọc, phiên âm thanh và giữ máy thức đi qua entry point `@mapslibvn/react-native/expo`, dưới dạng peer dependency tuỳ chọn. Không dùng dẫn đường? Không cần cài gói nào trong số đó. Làm app bare? Tự thay bằng nguồn GPS/âm thanh riêng.
+- 🔐 **Tôn trọng quyền riêng tư mặc định** — chỉ xin quyền định vị "When In Use", không bao giờ xin "Always".
+- 🚀 **Sẵn sàng cho New Architecture** — được build và kiểm thử trên New Architecture của React Native cùng các bản Expo SDK hiện hành.
+
+## Yêu cầu
+
+React ≥ 19.1, React Native ≥ 0.80, New Architecture, Expo ≥ 54 (không chạy trên Expo Go). Hướng dẫn đầy đủ: trang "React Native" trong docs.
 
 ## Cài đặt
 
@@ -28,6 +120,32 @@ import { MapsLibVNMap, Marker } from '@mapslibvn/react-native';
 
 Khoá mobile phải giới hạn đúng bundle/application id. Không tắt hoặc che attribution.
 
-Tài liệu: <https://mapslibvn-docs.pages.dev/react-native/>
+## Dẫn đường
+
+```tsx
+// index.ts — phạm vi toàn cục, trước registerRootComponent
+import { defineNavigationTask } from '@mapslibvn/react-native/expo';
+defineNavigationTask();
+```
+
+```tsx
+import { MapsLibVNMap, createClient, createNavigationSession, useNavigation } from '@mapslibvn/react-native';
+import { expoNavigation } from '@mapslibvn/react-native/expo';
+
+const client = createClient({ apiKey, baseUrl: apiBase });
+const session = createNavigationSession({ provider: client, ...expoNavigation() }); // sống ngoài cây React
+
+const response = await client.directions({ from: [10.7798, 106.699], to: [10.7725, 106.698], mode: 'motorbike' });
+await session.start({ response });            // GPS cả khi khoá máy, giọng Việt, tự tính lại khi lệch
+
+<MapsLibVNMap {...props} navigation={session} />   // gắn để vẽ tuyến, puck, camera bám; unmount không dừng phiên
+const { status, progress } = useNavigation(session); // dùng ở bất kỳ đâu
+```
+
+Cần `npx expo install expo-location expo-task-manager expo-speech expo-audio` và plugin trong `app.json` (xem docs). App có luồng GPS riêng: truyền `source` của bạn thay `expoNavigation()`.
+
+📖 Tài liệu: <https://mapslibvn-docs.pages.dev/react-native/> và <https://mapslibvn-docs.pages.dev/dan-duong-react-native/>
+
+📦 Nằm trong họ SDK MapsLibVN: [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core) · [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react)
 
 Giấy phép mã nguồn: MIT; xem `THIRD_PARTY_NOTICES.md` cho giấy phép phụ thuộc và dữ liệu.

package/THIRD_PARTY_NOTICES.md

@@ -9,7 +9,7 @@ MapsLibVN **không liên kết với, không được tài trợ hay chứng th
 nhãn hiệu của bên thứ ba; tên đó xuất hiện ở đây và trong tài liệu chỉ để mô tả nguồn gốc kỹ
 thuật của thư viện mà MapsLibVN sử dụng.
 
-Cập nhật: 04/09/2026.
+Cập nhật: 12/09/2026.
 
 ## 1. Thư viện được đóng gói hoặc là peer dependency của SDK
 
@@ -20,6 +20,8 @@ Cập nhật: 04/09/2026.
 | react, react-dom | 18.3.1 (peer, chỉ `@mapslibvn/react`) | MIT | |
 | @maplibre/maplibre-react-native | 11.3.8 (peer, chỉ `@mapslibvn/react-native`) | MIT | bộ vẽ bản đồ native iOS/Android |
 | react, react-native | react ≥ 19.1, react-native ≥ 0.80 (peer, chỉ `@mapslibvn/react-native`) | MIT | |
+| expo-location, expo-task-manager | 57.0.17 (peer **tuỳ chọn**, chỉ entry `@mapslibvn/react-native/expo`) | MIT | định vị tiền cảnh và nền cho dẫn đường |
+| expo-speech, expo-audio, expo-keep-awake | 57.0.3 / 57.0.5 / 57.0.1 (peer **tuỳ chọn**, chỉ entry `@mapslibvn/react-native/expo`) | MIT | đọc câu chỉ dẫn, phiên âm thanh khi nền, giữ màn hình sáng |
 
 Nguyên văn giấy phép ở mục 4.
 
@@ -385,9 +387,38 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SO
 Gói này nhúng MapLibre Native (Android, iOS) khi build app — xem thông báo giấy phép trong
 chính gói đó cho các thành phần native.
 
+### 4.9 expo-location, expo-task-manager, expo-speech, expo-audio, expo-keep-awake — MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Các gói này là peer dependency **tuỳ chọn**: chỉ app import `@mapslibvn/react-native/expo` (dẫn
+đường) mới cài; SDK không đóng gói mã của chúng.
+
 ## 5. Công cụ phía máy chủ (không phân phối, liệt kê để minh bạch)
 
 Planetiler (Apache-2.0), tippecanoe (BSD-2-Clause), osmium-tool (GPL-3.0 — dùng như công cụ
 dòng lệnh, không liên kết mã), pyosmium (BSD-2-Clause), DuckDB (MIT), PostgreSQL
-(PostgreSQL License), PostGIS (GPL-2.0 — chạy như dịch vụ), Hono (MIT), cloudflared
+(PostgreSQL License), PostGIS (GPL-2.0 — chạy như dịch vụ), Valhalla (MIT — engine chỉ đường, chạy như dịch vụ riêng trên máy chủ, không liên kết mã), Hono (MIT), cloudflared
 (Apache-2.0), Astro Starlight (MIT), Vitest (MIT), Playwright (Apache-2.0).

package/dist/chunk-PKBMQBKP.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export {
+  __publicField
+};

package/dist/expo/index.d.ts

@@ -0,0 +1,96 @@
+import { A as AudioSession, K as KeepAwake, T as TravelMode, S as SessionPositionSource, G as GeoFix, a as Speaker, N as NavigationSessionOptions } from '../session-B7Fu_s_b.js';
+
+/**
+ * Phiên âm thanh để giọng đọc phát khi khoá máy và làm nhỏ nhạc đang phát (spec C 6.3).
+ *
+ * Ba bước đều bắt buộc, xác nhận bằng thực địa trên máy thật 12/09/2026 (giọng đọc im lặng hoàn
+ * toàn ngay khi khoá màn hình cho tới khi vá đủ cả ba):
+ *
+ * 1. `setAudioModeAsync` chỉ đặt category AVAudioSession (iOS); nó KHÔNG gọi
+ *    `AVAudioSession.setActive` (xác nhận trong mã nguồn expo-audio: `AudioModule.swift` hàm
+ *    `setAudioMode` chỉ `session.setCategory`, `setActive` nằm ở hàm riêng `setIsAudioActive`) →
+ *    phải gọi thêm `setIsAudioActiveAsync(true)`.
+ * 2. Chỉ kích hoạt phiên KHÔNG đủ: giữa hai câu chỉ dẫn (vài chục giây không có âm thanh nào thật
+ *    sự phát ra), iOS coi app không còn dùng "audio" background mode một cách chính đáng và thu hồi
+ *    quyền chạy nền. Phải phát một vòng lặp âm thanh (im lặng tuyệt đối, toàn mẫu 0) liên tục trong
+ *    suốt lúc dẫn đường để giữ phiên "đang phát" thật sự.
+ * 3. Trên Android, `play()` một mình KHÔNG khiến hệ điều hành công nhận đây là phiên media đang
+ *    hoạt động: xác nhận thực địa Android thật (Xiaomi/MIUI) 12/09/2026 — dù foreground service
+ *    ĐỊNH VỊ vẫn còn nguyên (`serviceTypes` giữ cờ location suốt lúc khoá máy), JS/TTS vẫn đứng yên
+ *    hoàn toàn. Phải gọi thêm `player.setActiveForLockScreen(true, …)` để có `MediaSessionService`
+ *    — một foreground service RIÊNG, độc lập với foreground service định vị — giữ tiến trình sống.
+ *    Đây là kỹ thuật chuẩn của app điều hướng/audiobook, đã ghi làm phương án dự phòng (a) trong
+ *    spec C mục 11 rủi ro 1 (viết ban đầu cho iOS, hoá ra Android cũng cần bước tương đương).
+ */
+declare function expoAudioSession(): AudioSession;
+declare const KEEP_AWAKE_TAG = "mapslibvn-navigation";
+declare function expoKeepAwake(): KeepAwake;
+
+/** Tên task expo-task-manager nhận vị trí nền; một tên → một phiên nền tại một thời điểm. */
+declare const NAVIGATION_TASK = "mapslibvn-navigation-location";
+/** Độ chính xác của expo-location, đặt tên để không lộ enum của gói ra API công khai. */
+type ExpoLocationAccuracy = 'balanced' | 'high' | 'highest' | 'bestForNavigation';
+interface ExpoLocationSourceOptions {
+    /** Định vị cả khi khoá máy/chuyển app — mặc định true; cần app cấu hình plugin (docs). */
+    background?: boolean;
+    /** Mặc định 'bestForNavigation'. */
+    accuracy?: ExpoLocationAccuracy;
+    /** Mặc định 1000. */
+    timeInterval_ms?: number;
+    /** Thông báo foreground service Android. Mặc định "Đang dẫn đường" / "Chạm để mở ứng dụng". */
+    notification?: {
+        title?: string;
+        body?: string;
+        color?: string;
+    };
+    /** iOS: thanh trạng thái báo đang dùng vị trí nền — mặc định true. */
+    showsBackgroundLocationIndicator?: boolean;
+    /** iOS activityType và Android ưu tiên; mặc định 'motorbike', phiên ghi đè bằng `setMode` theo tuyến. */
+    mode?: TravelMode;
+}
+interface LocationObject {
+    coords: {
+        latitude: number;
+        longitude: number;
+        accuracy: number | null;
+        heading: number | null;
+        speed: number | null;
+    };
+    timestamp: number;
+}
+/** `LocationObject` của expo-location → `GeoFix` của core. iOS trả heading/speed âm khi không có. */
+declare function toGeoFix(l: LocationObject): GeoFix;
+/**
+ * Gọi ở PHẠM VI TOÀN CỤC của `index.ts`, trước `registerRootComponent` (yêu cầu của
+ * expo-task-manager). Gọi lại là no-op. Executor đẩy fix cho nguồn đang đăng ký; không ai nghe (app
+ * bị iOS đánh thức lại sau khi bị giết) thì tự dừng task để không thành task ma.
+ */
+declare function defineNavigationTask(): void;
+/**
+ * Nguồn vị trí Expo: một đường cho cả tiền cảnh lẫn nền (`startLocationUpdatesAsync` + task);
+ * điều kiện nền thiếu thì rơi về `watchPositionAsync` và báo `onBackgroundUnavailable` (spec C 6.1).
+ * Chỉ xin quyền When In Use — đã xác minh hai hệ không cần Always khi khởi động từ tiền cảnh.
+ */
+declare function expoLocationSource(opts?: ExpoLocationSourceOptions): SessionPositionSource;
+
+interface ExpoSpeechOptions {
+    /** 1 = tốc độ thường của hệ. */
+    rate?: number;
+    /** 0–1. */
+    volume?: number;
+    pitch?: number;
+}
+/**
+ * `Speaker` trên expo-speech. Android xếp hàng (`QUEUE_ADD`) và iOS cũng xếp hàng, nên muốn cắt câu
+ * phải `stop()` trước rồi mới `speak`. Theo dõi câu đang đọc bằng số thứ tự để callback của câu cũ
+ * đến muộn không xoá nhầm ưu tiên câu mới.
+ */
+declare function expoSpeech(opts?: ExpoSpeechOptions): Speaker;
+
+type ExpoNavigationOptions = ExpoLocationSourceOptions & {
+    speech?: ExpoSpeechOptions;
+};
+/** Bộ adapter Expo mặc định cho `createNavigationSession({ provider, ...expoNavigation() })`. */
+declare function expoNavigation(opts?: ExpoNavigationOptions): Required<Pick<NavigationSessionOptions, 'source' | 'speech' | 'audio' | 'keepAwake'>>;
+
+export { type ExpoLocationAccuracy, type ExpoLocationSourceOptions, type ExpoNavigationOptions, type ExpoSpeechOptions, KEEP_AWAKE_TAG, NAVIGATION_TASK, defineNavigationTask, expoAudioSession, expoKeepAwake, expoLocationSource, expoNavigation, expoSpeech, toGeoFix };