@mapslibvn/react 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,72 @@
 # @mapslibvn/react
 
-React bindings cho MapsLibVN: `<MapsLibVNMap>`, `<Marker>`, `useMap()` và `usePlaces()`.
+[![npm version](https://img.shields.io/npm/v/@mapslibvn/react.svg)](https://www.npmjs.com/package/@mapslibvn/react)
+[![npm downloads](https://img.shields.io/npm/dm/@mapslibvn/react.svg)](https://www.npmjs.com/package/@mapslibvn/react)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@mapslibvn/react)](https://bundlephobia.com/package/@mapslibvn/react)
+[![license](https://img.shields.io/npm/l/@mapslibvn/react.svg)](https://www.npmjs.com/package/@mapslibvn/react)
+
+**Idiomatic React bindings for MapsLibVN.** Drop a Vietnam-ready map, search box and turn-by-turn navigation into any React app with `<MapsLibVNMap>`, `<Marker>`, `useMap()`, `usePlaces()` and `useNavigation()` — no imperative MapLibre plumbing required.
+
+Built on top of [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) and [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core), so every feature of the underlying engine (Vietnamese search, POI sources, navigation) is available through familiar React patterns.
+
+## Why teams pick it
+
+- ⚛️ **Declarative by default** — `<MapsLibVNMap>` mounts a real MapLibre map, exposes it through `useMap()`, and only renders `children` (markers, overlays) once the map is ready.
+- 🧠 **Smart re-renders** — changing `apiKey`, `style`, `center` or `zoom` recreates the map; changing `onLoad`, `onPoiClick`, `className` or `children` does not, so inline handlers are safe to pass every render.
+- 🔎 **`usePlaces()` autocomplete hook** — debounced, cancels stale requests, keeps previous results while loading (SWR-style), and needs only 2 characters to start searching.
+- 🧭 **`useNavigation()`** — subscribe to turn-by-turn `status` and `progress` from anywhere in your component tree, backed by the same navigation engine as the web SDK.
+- 🇻🇳 **All of `@mapslibvn/core`'s Vietnamese search smarts** — diacritics-insensitive matching, address parsing, and configurable POI sources (OSM / Overture / Foursquare) — available through simple props.
+
+## Install
+
+```bash
+npm install @mapslibvn/react maplibre-gl@^6.4.1 react
+```
+
+Requires React 18+ and a WebGL2-capable browser. Load MapLibre's CSS once at your app's entry point.
+
+## Quick start
+
+```tsx
+import { MapsLibVNMap, Marker } from '@mapslibvn/react';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+export function BanDo() {
+  return (
+    <MapsLibVNMap
+      apiKey="mlv_live_…"
+      apiBase="https://api.ai-solutions.io.vn"
+      containerStyle={{ height: 400 }}
+    >
+      <Marker lng={106.6981} lat={10.7725} />
+    </MapsLibVNMap>
+  );
+}
+```
+
+The parent element needs a real height. Don't hide or disable attribution; Web keys must be origin-restricted.
+
+📖 Docs: <https://mapslibvn-docs.pages.dev/react/>
+
+📦 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-native`](https://www.npmjs.com/package/@mapslibvn/react-native)
+
+Source license: MIT; see `THIRD_PARTY_NOTICES.md` for dependency and data licenses.
+
+---
+
+## Tiếng Việt
+
+**Binding React chuẩn phong cách cho MapsLibVN.** Đưa bản đồ, ô tìm kiếm và dẫn đường "Việt Nam trước" vào bất kỳ app React nào chỉ với `<MapsLibVNMap>`, `<Marker>`, `useMap()`, `usePlaces()` và `useNavigation()` — không cần tự tay nối dây MapLibre theo kiểu mệnh lệnh.
+
+Xây trên nền [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) và [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core), nên mọi tính năng của engine bên dưới (tìm kiếm tiếng Việt, chọn nguồn POI, dẫn đường) đều dùng được qua các pattern React quen thuộc.
+
+## Vì sao nên chọn
+
+- ⚛️ **Khai báo (declarative) theo mặc định** — `<MapsLibVNMap>` dựng một bản đồ MapLibre thật, đưa ra ngoài qua `useMap()`, và chỉ render `children` (marker, lớp phủ) sau khi bản đồ đã sẵn sàng.
+- 🧠 **Re-render thông minh** — đổi `apiKey`, `style`, `center` hay `zoom` sẽ tạo lại bản đồ; đổi `onLoad`, `onPoiClick`, `className` hay `children` thì không, nên truyền handler dạng inline mỗi lần render vẫn an toàn.
+- 🔎 **Hook autocomplete `usePlaces()`** — có debounce, huỷ request cũ khi có request mới, giữ kết quả cũ trong lúc tải (kiểu SWR), chỉ cần 2 ký tự là bắt đầu tìm.
+- 🧭 **`useNavigation()`** — theo dõi `status` và `progress` dẫn đường từ bất kỳ đâu trong cây component, dùng chung engine dẫn đường với SDK web.
+- 🇻🇳 **Trọn vẹn khả năng tìm kiếm tiếng Việt của `@mapslibvn/core`** — khớp không phân biệt dấu, phân tích địa chỉ, và chọn nguồn POI (OSM / Overture / Foursquare) — tất cả chỉ qua vài prop đơn giản.
 
 ## Cài đặt
 
@@ -10,7 +76,7 @@ npm install @mapslibvn/react maplibre-gl@^6.4.1 react
 
 Yêu cầu React 18+ và trình duyệt hỗ trợ WebGL2. Nạp CSS của MapLibre một lần ở điểm vào ứng dụng.
 
-## Ví dụ
+## Bắt đầu nhanh
 
 ```tsx
 import { MapsLibVNMap, Marker } from '@mapslibvn/react';
@@ -29,9 +95,10 @@ export function BanDo() {
 }
 ```
 
-Phần tử cha phải có chiều cao thật. Không tắt hoặc che attribution; khóa Web phải giới hạn đúng
-origin.
+Phần tử cha phải có chiều cao thật. Không tắt hoặc che attribution; khóa Web phải giới hạn đúng origin.
+
+📖 Tài liệu: <https://mapslibvn-docs.pages.dev/react/>
 
-Tài liệu: <https://mapslibvn-docs.pages.dev/react/>
+📦 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-native`](https://www.npmjs.com/package/@mapslibvn/react-native)
 
 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/index.d.ts

@@ -1,8 +1,9 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode } from 'react';
-import { CreateMapOptions, PoiFeature, MapsLibVNMap as MapsLibVNMap$1, MarkerOptions } from '@mapslibvn/web';
-import { MapsLibVNClient, AutocompleteItem } from '@mapslibvn/core';
-export { AutocompleteItem, MapsLibVNClient, Place, PoiSource } from '@mapslibvn/core';
+import { CreateMapOptions, PoiFeature, MapsLibVNMap as MapsLibVNMap$1, MarkerOptions, NavigationStartOptions } from '@mapslibvn/web';
+export { NavigationStartOptions } from '@mapslibvn/web';
+import { MapsLibVNClient, AutocompleteItem, NavigationStatus, NavigationProgress } from '@mapslibvn/core';
+export { Announcement, AutocompleteItem, MapsLibVNClient, NavigationProgress, NavigationStatus, Place, PoiSource, RouteProvider } from '@mapslibvn/core';
 
 interface MapsLibVNMapProps extends Omit<CreateMapOptions, 'container'> {
     className?: string;
@@ -33,4 +34,15 @@ interface UsePlacesResult {
 /** Autocomplete kiểu SWR: giữ items cũ khi tải và bỏ qua response của query đã huỷ. */
 declare function usePlaces(query: string, options?: UsePlacesOptions): UsePlacesResult;
 
-export { MapsLibVNMap, type MapsLibVNMapProps, Marker, type UsePlacesOptions, type UsePlacesResult, useMap, usePlaces };
+interface UseNavigationResult {
+    status: NavigationStatus;
+    progress: NavigationProgress | null;
+    start(opts: NavigationStartOptions): void;
+    stop(): void;
+    recenter(): void;
+    reroute(): Promise<void>;
+}
+/** Trạng thái dẫn đường của bản đồ trong context, re-render theo `status` và `progress` (spec B 5.6). */
+declare function useNavigation(): UseNavigationResult;
+
+export { MapsLibVNMap, type MapsLibVNMapProps, Marker, type UseNavigationResult, type UsePlacesOptions, type UsePlacesResult, useMap, useNavigation, usePlaces };

package/dist/index.js

@@ -141,9 +141,48 @@ function usePlaces(query, options = {}) {
   }, [client, query, nearKey, options.limit, options.debounceMs]);
   return { items, loading, error };
 }
+
+// src/use-navigation.ts
+import { useCallback, useSyncExternalStore } from "react";
+function useNavigation() {
+  const nav = useMap().navigation;
+  const subscribeStatus = useCallback(
+    (onChange) => {
+      nav.on("status", onChange);
+      return () => nav.off("status", onChange);
+    },
+    [nav]
+  );
+  const subscribeProgress = useCallback(
+    (onChange) => {
+      nav.on("progress", onChange);
+      return () => nav.off("progress", onChange);
+    },
+    [nav]
+  );
+  const status = useSyncExternalStore(
+    subscribeStatus,
+    () => nav.status,
+    () => nav.status
+  );
+  const progress = useSyncExternalStore(
+    subscribeProgress,
+    () => nav.state,
+    () => nav.state
+  );
+  return {
+    status,
+    progress,
+    start: (opts) => nav.start(opts),
+    stop: () => nav.stop(),
+    recenter: () => nav.recenter(),
+    reroute: () => nav.reroute()
+  };
+}
 export {
   MapsLibVNMap,
   Marker,
   useMap,
+  useNavigation,
   usePlaces
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapslibvn/react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React bindings MapsLibVN: <MapsLibVNMap>, <Marker>, useMap, usePlaces",
   "license": "MIT",
   "type": "module",
@@ -24,13 +24,13 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@mapslibvn/core": "0.4.0",
-    "@mapslibvn/web": "0.4.0"
+    "@mapslibvn/core": "0.5.0",
+    "@mapslibvn/web": "0.5.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.0",
+    "@types/react": "^19.3.0",
     "maplibre-gl": "^6.8.0",
-    "react": "^18.3.0",
+    "react": "^19.3.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0"
   },