@mapslibvn/web 0.4.0 → 0.5.0

package/README.md

@@ -1,7 +1,74 @@
 # @mapslibvn/web
 
-SDK bản đồ Web của MapsLibVN, bọc MapLibre GL JS và PMTiles, có autocomplete web component và
-attribution bắt buộc.
+[![npm version](https://img.shields.io/npm/v/@mapslibvn/web.svg)](https://www.npmjs.com/package/@mapslibvn/web)
+[![npm downloads](https://img.shields.io/npm/dm/@mapslibvn/web.svg)](https://www.npmjs.com/package/@mapslibvn/web)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@mapslibvn/web)](https://bundlephobia.com/package/@mapslibvn/web)
+[![license](https://img.shields.io/npm/l/@mapslibvn/web.svg)](https://www.npmjs.com/package/@mapslibvn/web)
+
+**A production-ready web map SDK for Vietnam.** `@mapslibvn/web` wraps MapLibre GL JS and PMTiles into a single `createMap()` call — vector tiles, Vietnamese/English labels, a built-in accessible search box, and turn-by-turn navigation, with attribution handled correctly out of the box.
+
+Framework-agnostic: drop it into a plain HTML page via `<script>`, or use it as the engine under [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react).
+
+## Why teams pick it
+
+- 🗺️ **One call to a working map** — `createMap()` sets up the style, vector tiles (via PMTiles, no tile server to run), attribution and language in one step.
+- 🔎 **Autocomplete that just works** — the `<mapslibvn-autocomplete>` Web Component ships as an accessible ARIA combobox (keyboard navigation, live region, debounced requests) that drops into any stack — vanilla JS, Vue, Svelte, plain HTML — no React required.
+- 🧭 **Turn-by-turn navigation layer** — route rendering, camera follow, automatic rerouting and Vietnamese voice guidance (Web Speech API) via `map.navigation`.
+- 🌐 **Bilingual labels** — switch between Vietnamese and English map labels at runtime with `applyLanguage`; sovereignty-sensitive labels always stay in Vietnamese.
+- 📦 **Ship it your way** — a tree-shakeable ESM build (`dist/index.js`, ≤ 15 kB gzip) for bundlers, or a self-contained UMD bundle with MapLibre and PMTiles baked in for a plain `<script>` tag.
+- ⚖️ **Attribution can't be silently dropped** — `createMap` always injects the required attribution control; there's no option to hide it, by design.
+
+## Install
+
+```bash
+npm install @mapslibvn/web maplibre-gl@^6.4.1
+```
+
+MapLibre GL JS 6 requires a WebGL2-capable browser. Load MapLibre's CSS once at your app's entry point.
+
+## Quick start (ESM)
+
+```ts
+import { createMap } from '@mapslibvn/web';
+import * as maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const map = createMap(
+  {
+    container: 'map',
+    apiKey: 'mlv_live_…',
+    apiBase: 'https://api.ai-solutions.io.vn',
+    center: [106.7, 10.776],
+    zoom: 13,
+  },
+  { maplibre: maplibregl },
+);
+```
+
+The UMD build at `@mapslibvn/web/umd` bundles MapLibre and PMTiles for you. If you self-host the UMD file, place `maplibre-gl-worker.mjs` and `maplibre-gl-shared.mjs` next to `mapslibvn.umd.js`. Don't hide or disable attribution. Never ship a secret key in client-side code — Web keys must be origin-restricted.
+
+📖 Docs: <https://mapslibvn-docs.pages.dev/ban-do-web/>
+
+📦 Part of the MapsLibVN SDK family: [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) · [`@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
+
+**SDK bản đồ web sẵn sàng cho production, dành cho Việt Nam.** `@mapslibvn/web` gói MapLibre GL JS và PMTiles vào đúng một lệnh `createMap()` — vector tiles, nhãn song ngữ Việt/Anh, ô tìm kiếm dễ tiếp cận có sẵn, và dẫn đường chỉ đường, với attribution được xử lý đúng ngay từ đầu.
+
+Không phụ thuộc framework: nhúng thẳng vào trang HTML thuần bằng `<script>`, hoặc dùng làm engine bên dưới [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react).
+
+## Vì sao nên chọn
+
+- 🗺️ **Một lệnh ra bản đồ chạy được ngay** — `createMap()` dựng sẵn style, vector tiles (qua PMTiles, không cần chạy tile server riêng), attribution và ngôn ngữ trong một bước.
+- 🔎 **Autocomplete dùng được ngay** — web component `<mapslibvn-autocomplete>` là một combobox ARIA dễ tiếp cận (điều hướng bàn phím, vùng live, debounce request) nhúng được vào bất kỳ stack nào — vanilla JS, Vue, Svelte, HTML thuần — không cần React.
+- 🧭 **Lớp dẫn đường trọn gói** — vẽ tuyến, camera bám theo, tự tính lại khi lệch tuyến và đọc thoại tiếng Việt (Web Speech API) qua `map.navigation`.
+- 🌐 **Nhãn song ngữ** — đổi nhãn bản đồ giữa tiếng Việt và tiếng Anh ngay lúc chạy bằng `applyLanguage`; nhãn liên quan chủ quyền luôn giữ tiếng Việt.
+- 📦 **Chọn cách đóng gói theo ý bạn** — bản ESM tree-shake được (`dist/index.js`, ≤ 15 kB gzip) cho các bundler, hoặc bản UMD tự chứa đã đóng gói sẵn MapLibre và PMTiles để dùng thẳng bằng thẻ `<script>`.
+- ⚖️ **Không thể lặng lẽ tắt attribution** — `createMap` luôn tự thêm control ghi nguồn bắt buộc; không có tuỳ chọn ẩn nó, đây là chủ đích thiết kế.
 
 ## Cài đặt
 
@@ -9,10 +76,9 @@ attribution bắt buộc.
 npm install @mapslibvn/web maplibre-gl@^6.4.1
 ```
 
-MapLibre GL JS 6 yêu cầu trình duyệt hỗ trợ WebGL2. Nạp CSS của MapLibre một lần ở điểm vào ứng
-dụng.
+MapLibre GL JS 6 yêu cầu 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ụ ESM
+## Bắt đầu nhanh (ESM)
 
 ```ts
 import { createMap } from '@mapslibvn/web';
@@ -31,10 +97,10 @@ const map = createMap(
 );
 ```
 
-Bản UMD tại export `@mapslibvn/web/umd` đóng gói sẵn MapLibre và PMTiles. Khi tự phục vụ UMD, đặt
-`maplibre-gl-worker.mjs` và `maplibre-gl-shared.mjs` cạnh `mapslibvn.umd.js`. Không tắt hoặc che
-attribution. Không đưa khóa bí mật vào mã nguồn; khóa Web phải giới hạn đúng origin.
+Bản UMD tại export `@mapslibvn/web/umd` đóng gói sẵn MapLibre và PMTiles. Khi tự phục vụ UMD, đặt `maplibre-gl-worker.mjs` và `maplibre-gl-shared.mjs` cạnh `mapslibvn.umd.js`. Không tắt hoặc che attribution. Không đưa khóa bí mật vào mã nguồn; khóa Web phải giới hạn đúng origin.
+
+📖 Tài liệu: <https://mapslibvn-docs.pages.dev/ban-do-web/>
 
-Tài liệu: <https://mapslibvn-docs.pages.dev/ban-do-web/>
+📦 Nằm trong họ SDK MapsLibVN: [`@mapslibvn/core`](https://www.npmjs.com/package/@mapslibvn/core) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) · [`@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,5 +1,5 @@
-import { Lang, Theme, PoiSource, PoiFeature, MapsLibVNClient } from '@mapslibvn/core';
-export { AttributionResponse, ClientOptions, Lang, MapsLibVNClient, MapsLibVNError, PoiFeature, PoiSource, Theme, attributionHtml, attributionText, createClient, nameExpression } from '@mapslibvn/core';
+import { Lang, DirectionsResponse, TravelMode, RouteProvider, DirectionsLang, PositionSource, NavigationThresholds, NavigationProgress, NavigationStatus, NavigationEvents, PositionError, Theme, PoiSource, PoiFeature, MapsLibVNClient, GeoFix } from '@mapslibvn/core';
+export { Announcement, AttributionResponse, ClientOptions, DirectionsLang, DirectionsOptions, DirectionsResponse, GeoFix, Lang, ManeuverKind, MapsLibVNClient, MapsLibVNError, NAVIGATION_THRESHOLDS, NavigationEvents, NavigationProgress, NavigationStatus, NavigationThresholds, Navigator, PoiFeature, PoiSource, PositionError, PositionSource, Route, RouteLeg, RouteProvider, RouteStep, Theme, TravelMode, attributionHtml, attributionText, createClient, createNavigator, formatDistance, formatDistanceShort, nameExpression, simulateFixes } from '@mapslibvn/core';
 import * as maplibregl from 'maplibre-gl';
 import { Protocol } from 'pmtiles';
 
@@ -16,6 +16,69 @@ interface StyleLike {
 /** Đổi nhãn sang ngôn ngữ khác lúc chạy. Bỏ qua lớp chủ quyền (luôn tiếng Việt) và nhãn không phải tên. */
 declare function applyLanguage(gl: StyleLike, lang: Lang): void;
 
+declare const ROUTE_SOURCE_ID = "mapslibvn-route";
+declare const ROUTE_LAYER_IDS: {
+    readonly alt: "mapslibvn-route-alt";
+    readonly casing: "mapslibvn-route-casing";
+    readonly line: "mapslibvn-route-line";
+    readonly traveled: "mapslibvn-route-traveled";
+};
+interface RoutesLayer {
+    show(response: DirectionsResponse, opts?: {
+        active?: number;
+        markers?: boolean;
+    }): void;
+    setActive(index: number): void;
+    /** Chia tuyến chính tại (`shapeIndex`, `snapped`): trước là đã đi, sau là còn lại. */
+    setProgress(shapeIndex: number, snapped: [number, number]): void;
+    clear(): void;
+}
+
+interface NavigationStartOptions {
+    response: DirectionsResponse;
+    routeIndex?: number;
+    /** Mặc định `map.places`. */
+    provider?: RouteProvider;
+    /** Mặc định 'auto'. */
+    reroute?: 'auto' | 'manual';
+    /** Mặc định theo `lang` của map. */
+    lang?: DirectionsLang;
+    /** Mặc định true. */
+    voice?: boolean | {
+        rate?: number;
+        volume?: number;
+    };
+    /** Mặc định true; zoom theo phương tiện, pitch 45. */
+    follow?: boolean | {
+        zoom?: number;
+        pitch?: number;
+        padding?: maplibregl.PaddingOptions;
+    };
+    /** Mặc định `geolocationSource()`. */
+    source?: PositionSource;
+    thresholds?: Partial<NavigationThresholds>;
+    /** Mặc định true. */
+    wakeLock?: boolean;
+}
+interface WebNavigationEvents extends NavigationEvents {
+    followChange: boolean;
+    positionError: PositionError;
+    voiceUnavailable: undefined;
+}
+interface NavigationController {
+    start(opts: NavigationStartOptions): void;
+    /** Dừng GPS, giọng nói, wake lock, puck; KHÔNG xoá tuyến (gọi `map.routes.clear()` nếu cần). */
+    stop(): void;
+    recenter(): void;
+    reroute(): Promise<void>;
+    readonly state: NavigationProgress | null;
+    readonly status: NavigationStatus;
+    readonly following: boolean;
+    on<K extends keyof WebNavigationEvents>(event: K, handler: (e: WebNavigationEvents[K]) => void): void;
+    off<K extends keyof WebNavigationEvents>(event: K, handler: (e: WebNavigationEvents[K]) => void): void;
+}
+declare const FOLLOW_ZOOM: Readonly<Record<TravelMode, number>>;
+
 interface ProtocolHost {
     addProtocol(name: string, loadFn: Protocol['tile']): void;
 }
@@ -49,6 +112,9 @@ interface MarkerOptions {
 interface MapEvents {
     poiClick: PoiFeature;
     load: undefined;
+    routeClick: {
+        index: number;
+    };
 }
 interface Deps {
     maplibre: typeof maplibregl & ProtocolHost;
@@ -56,6 +122,10 @@ interface Deps {
 interface MapsLibVNMap {
     gl: maplibregl.Map;
     places: MapsLibVNClient;
+    /** Vẽ tuyến từ `DirectionsResponse` (spec B 5.2). */
+    routes: RoutesLayer;
+    /** Dẫn đường theo GPS (spec B 5.5). */
+    navigation: NavigationController;
     addMarker(o: MarkerOptions): maplibregl.Marker;
     fitBounds(bbox: [number, number, number, number], padding?: number): void;
     flyTo(center: [number, number], zoom?: number): void;
@@ -88,4 +158,42 @@ declare class MapsLibVNAutocomplete extends HTMLElement {
 }
 declare function defineAutocomplete(): void;
 
-export { type CreateMapOptions, type MapEvents, MapsLibVNAutocomplete, type MapsLibVNMap, type MarkerOptions, applyLanguage, createMap, defineAutocomplete };
+interface GeolocationSourceOptions {
+    /** Mặc định true. */
+    enableHighAccuracy?: boolean;
+    /** Mặc định 1000 ms. */
+    maximumAge?: number;
+    /** Mặc định 10 000 ms. */
+    timeout?: number;
+    /** Tiêm cho test; mặc định `navigator.geolocation`. */
+    geolocation?: Geolocation | undefined;
+}
+declare function toGeoFix(position: GeolocationPosition): GeoFix;
+/** `navigator.geolocation.watchPosition` → `GeoFix`. Cần HTTPS (trừ localhost). */
+declare function geolocationSource(options?: GeolocationSourceOptions): PositionSource;
+/** Phát lại chuỗi fix (ví dụ từ `simulateFixes`) theo chênh timestamp chia `rate`; `rate: 0` phát hết một tick. */
+declare function playbackSource(fixes: readonly GeoFix[], options?: {
+    rate?: number;
+}): PositionSource;
+
+interface SpeechOptions {
+    lang: DirectionsLang;
+    rate?: number;
+    volume?: number;
+    /** Tiêm cho test; mặc định `speechSynthesis` toàn cục. */
+    synth?: SpeechSynthesis | undefined;
+    /** Gọi đúng một lần khi xác định không đọc được (không có API hoặc không có voice khớp). */
+    onUnavailable?: () => void;
+}
+interface Speech {
+    /** Cắt câu đang đọc nếu `priority` ≥ ưu tiên câu đó; thấp hơn thì xếp hàng. */
+    speak(text: string, priority: 1 | 2 | 3): void;
+    /** Đọc câu rỗng trong user gesture để iOS mở khoá âm thanh. */
+    warmUp(): void;
+    cancel(): void;
+    /** false khi không có API hoặc đã biết danh sách voice mà không có voice khớp. */
+    readonly available: boolean;
+}
+declare function createSpeech(opts: SpeechOptions): Speech;
+
+export { type CreateMapOptions, FOLLOW_ZOOM, type GeolocationSourceOptions, type MapEvents, MapsLibVNAutocomplete, type MapsLibVNMap, type MarkerOptions, type NavigationController, type NavigationStartOptions, ROUTE_LAYER_IDS, ROUTE_SOURCE_ID, type RoutesLayer, type Speech, type SpeechOptions, type WebNavigationEvents, applyLanguage, createMap, createSpeech, defineAutocomplete, geolocationSource, playbackSource, toGeoFix };