@mapslibvn/react-native 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,225 +1,36 @@
 import * as react from 'react';
 import { RefObject, ReactNode, ReactElement } from 'react';
+import { b as SessionEvents, T as TravelMode, c as NavigationSession, d as NavigationSessionStartOptions, e as NavigationProgress, f as NavigationStatus, M as MapsLibVNClient, D as DirectionsResponse, g as Theme, L as Lang, P as PoiSource, N as NavigationSessionOptions, h as PoiFeature, i as AutocompleteItem, G as GeoFix, j as PositionSource } from './session-B7Fu_s_b.js';
+export { k as Announcement, A as AudioSession, B as BackgroundUnavailable, l as DirectionsLang, m as DirectionsOptions, K as KeepAwake, n as MISSING_SOURCE_MESSAGE, o as ManeuverKind, p as NAVIGATION_THRESHOLDS, q as NavigationEvents, r as NavigationThresholds, s as Place, t as PositionError, R as Route, u as RouteLeg, v as RouteProvider, w as RouteStep, S as SessionPositionSource, a as Speaker, x as createClient, y as createNavigationSession, z as createNavigator, C as decodePolyline6, E as formatDistance, F as formatDistanceShort, H as simulateFixes } from './session-B7Fu_s_b.js';
 import { StyleProp, ViewStyle } from 'react-native';
-import { MapRef, CameraRef, Anchor } from '@maplibre/maplibre-react-native';
+import { ViewPadding, MapRef, CameraRef, Anchor } from '@maplibre/maplibre-react-native';
 
-/**
- * Nguồn POI và profile archive (spec 07/09 mục 4). Đây là nguồn sự thật duy nhất cho API, SDK và
- * pipeline: thêm profile mới = thêm một dòng vào POI_SOURCE_PROFILES + một lần export-tiles.
- */
-declare const POI_SOURCES: readonly ["osm", "overture", "fsq"];
-type PoiSource = (typeof POI_SOURCES)[number];
-
-/** Kiểu dữ liệu Places API (spec 6.1) dùng chung cho Worker và SDK. */
-interface PlaceCategory {
-    code: string;
-    group: string;
-    name_vi: string;
-    name_en: string;
-}
-interface PlaceAddress {
-    housenumber?: string;
-    street?: string;
-    ward?: string;
-    province?: string;
-    text?: string;
-}
-interface Place {
-    id: string;
-    name: string;
-    category: PlaceCategory | null;
-    lat: number;
-    lng: number;
-    address: PlaceAddress;
-    contact?: Record<string, unknown> | null;
-    hours?: unknown;
-    quality_score: number | null;
-    status: 'active' | 'closed' | 'pending' | 'rejected';
-    updated_at: string;
-}
-interface PlaceSource {
-    source: 'osm' | 'overture' | 'fsq';
-    source_id: string;
-    role: 'primary' | 'secondary';
-}
-interface PlaceDetails extends Place {
-    sources: PlaceSource[];
-    attribution: {
-        text: string;
-        html: string;
-    };
-}
-type GeocodePrecision = 'rooftop' | 'alley' | 'interpolated' | 'street' | 'ward' | 'district' | 'province';
-type AutocompleteType = 'poi' | 'street' | 'address' | 'area';
-interface AutocompleteItem {
-    type: AutocompleteType;
-    id?: string;
-    name: string;
-    secondary: string;
-    lat: number;
-    lng: number;
-    precision?: GeocodePrecision;
-    score: number;
-    bbox?: [number, number, number, number];
-    /** Tên thay thế (OSM `alt_name`/`old_name`) đã khớp truy vấn, ví dụ "Công Lý" (spec 6.3). */
-    matched_alt?: string;
-}
-interface GeocodeMatched {
-    housenumber?: string;
-    street?: string;
-    ward?: string;
-    province?: string;
-    former?: {
-        ward?: string;
-        district?: string;
-        province?: string;
-    };
-}
-interface GeocodeItem {
-    lat: number;
-    lng: number;
-    precision: GeocodePrecision;
-    confidence: number;
-    matched: GeocodeMatched;
-    display_name: string;
-    bbox?: [number, number, number, number];
-}
-interface ReverseAddress {
-    approx_housenumber?: string;
-    street?: string;
-    ward?: string;
-    province?: string;
-    display_name: string;
-}
-interface ReverseResponse {
-    address: ReverseAddress;
-    nearest_poi: Place | null;
-}
-type EditKind = 'create' | 'update' | 'close' | 'reopen' | 'report';
-/** Trường được phép sửa/khai khi đóng góp (spec 6.1 + 6.5). */
-interface EditChanges {
-    name?: string;
-    lat?: number;
-    lng?: number;
-    category?: string;
-    housenumber?: string;
-    street?: string;
-    ward?: string;
-    province?: string;
-    address_text?: string;
-    contact?: {
-        phone?: string[];
-        website?: string[];
-        facebook?: string;
-    };
-    /** Chuỗi opening_hours OSM hoặc {osm: chuỗi}. */
-    hours?: string | {
-        osm: string;
-    };
-}
-interface SuggestEditRequest {
-    /** Bắt buộc trừ kind='create'. */
-    poi_id?: string;
-    kind: EditKind;
-    changes?: EditChanges;
-    photo_url?: string;
-    note?: string;
-    /** Chuỗi ổn định theo người dùng cuối do app nhúng cấp — server chỉ lưu bản băm. */
-    end_user_token: string;
-}
-interface SuggestEditResponse {
-    edit_id: number;
-    status: 'pending' | 'auto_approved';
-    /** POI đích; với kind='create' là id POI mới (pending cho tới khi được duyệt). */
-    poi_id: string | null;
-}
-/** POI đọc từ tile lớp `poi` khi người dùng bấm — SDK web và React Native dùng chung. */
-interface PoiFeature {
-    id: string;
-    name: string;
-    category: string;
-    group: string;
-    lngLat: [number, number];
-}
-
-type Theme = 'light' | 'dark';
-interface ClientOptions {
-    /** Khoá API dạng mlv_live_… */
-    apiKey: string;
-    /** Gốc API, ví dụ https://maps-api.example.com */
-    baseUrl: string;
-    /** Cho phép tiêm fetch cho test hoặc môi trường không có global fetch. */
-    fetch?: typeof globalThis.fetch;
-    /**
-     * Header thêm cho mọi request, ví dụ `X-Bundle-Id` cho khoá `mobile` (spec 6.4).
-     * Không ghi đè được `X-Api-Key`.
-     */
-    headers?: Record<string, string>;
-    /**
-     * Tập nguồn POI cho bản đồ và Places API (spec 07/09). Mặc định cả ba nguồn.
-     * Áp cho autocomplete/search/nearby/reverse và `styleUrl`; `getPlace`/`geocode` không lọc.
-     */
-    poiSources?: readonly PoiSource[];
-}
-interface AttributionResponse {
-    text: string;
-    html: string;
-    links: {
-        text: string;
-        href: string;
-        license?: string;
-    }[];
+interface FollowOptions {
+    /** Mặc định theo phương tiện: walk 17, motorbike 16,5, car 15,5. */
+    zoom?: number;
+    /** Mặc định 45. */
+    pitch?: number;
+    padding?: ViewPadding;
+}
+declare const FOLLOW_ZOOM: Readonly<Record<TravelMode, number>>;
+declare const FOLLOW_PITCH = 45;
+interface BindingEvents extends SessionEvents {
+    followChange: boolean;
+}
+/** Thứ lộ ra qua `useMap().navigation` — uỷ quyền sang phiên, thêm bám camera của map này. */
+interface MapNavigationBinding {
+    /** Phiên qua prop `navigation`, không thì phiên mặc định của map (tạo lười). */
+    readonly session: NavigationSession;
+    readonly following: boolean;
+    recenter(): void;
+    start(opts: NavigationSessionStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    reroute(): Promise<void>;
+    readonly state: NavigationProgress | null;
+    readonly status: NavigationStatus;
+    on<K extends keyof BindingEvents>(event: K, handler: (e: BindingEvents[K]) => void): void;
+    off<K extends keyof BindingEvents>(event: K, handler: (e: BindingEvents[K]) => void): void;
 }
-declare function createClient(options: ClientOptions): {
-    baseUrl: string;
-    attribution: () => Promise<AttributionResponse>;
-    styleUrl: (theme: Theme) => string;
-    autocomplete: (q: string, opts?: {
-        near?: [number, number];
-        limit?: number;
-        types?: AutocompleteType[];
-    }) => Promise<{
-        items: AutocompleteItem[];
-    }>;
-    search: (q: string, opts?: {
-        category?: string;
-        near?: [number, number];
-        radius?: number;
-        bbox?: [number, number, number, number];
-        limit?: number;
-        offset?: number;
-    }) => Promise<{
-        items: Place[];
-        total: number;
-    }>;
-    nearby: (opts: {
-        lat: number;
-        lng: number;
-        radius?: number;
-        category?: string;
-        limit?: number;
-    }) => Promise<{
-        items: Place[];
-    }>;
-    getPlace: (id: string) => Promise<PlaceDetails>;
-    geocode: (q: string, opts?: {
-        near?: [number, number];
-        limit?: number;
-    }) => Promise<{
-        items: GeocodeItem[];
-    }>;
-    reverse: (lat: number, lng: number) => Promise<ReverseResponse>;
-    /** Gửi đóng góp/sửa POI (spec 6.1). Khoá phải có scope edits:write. */
-    suggestEdit: (edit: SuggestEditRequest) => Promise<SuggestEditResponse>;
-};
-type MapsLibVNClient = ReturnType<typeof createClient>;
-
-/**
- * Biến đổi style JSON thuần (không cần Map đang chạy) — dùng cho React Native, nơi wrapper
- * không có API đổi layout property của lớp có sẵn. Web dùng `applyLanguage` lúc chạy nhưng
- * chia sẻ `nameExpression`/`isNameLabelLayer` từ đây.
- */
-type Lang = 'vi' | 'en';
 
 /** Tay cầm map — tương ứng `MapsLibVNMap` của web: `native` thay `gl`. */
 interface MapHandle {
@@ -232,6 +43,38 @@ interface MapHandle {
     fitBounds(bbox: [number, number, number, number], padding?: number): void;
     /** [west, south, east, north] */
     getBounds(): Promise<[number, number, number, number]>;
+    /** Vẽ tuyến không cần phiên (xem trước, app khách). Phiên gắn vào sẽ ghi đè. */
+    routes: {
+        show(response: DirectionsResponse, opts?: {
+            active?: number;
+        }): void;
+        setActive(index: number): void;
+        clear(): void;
+    };
+    /** Dẫn đường của map này: phiên qua prop `navigation`, không thì phiên mặc định tạo lười. */
+    navigation: MapNavigationBinding;
+}
+
+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";
+    readonly puck: "mapslibvn-route-puck";
+};
+declare const ROUTE_COLOR = "#2458a6";
+declare const ALT_ROUTE_COLOR = "#9ca8ba";
+declare const DESTINATION_COLOR = "#d92d20";
+interface RouteStyle {
+    /** Tuyến chính và phần đã đi — mặc định #2458a6. */
+    color?: string;
+    /** Tuyến thay thế — mặc định #9ca8ba. */
+    altColor?: string;
+    /** Viền tuyến chính — mặc định trắng. */
+    casingColor?: string;
+    /** Độ mờ phần đã đi — mặc định 0,35. */
+    traveledOpacity?: number;
 }
 
 declare const DEFAULT_CENTER: [number, number];
@@ -256,13 +99,26 @@ interface MapsLibVNMapProps {
     bundleId?: string;
     /** Style của khung View bọc ngoài */
     containerStyle?: StyleProp<ViewStyle>;
+    /** Phiên dẫn đường gắn vào map để vẽ tuyến, puck, camera bám; bỏ prop → gỡ và xoá tuyến. */
+    navigation?: NavigationSession;
+    /** Tuỳ chọn cho phiên mặc định (khi không truyền `navigation`); cần ít nhất `source`. */
+    sessionOptions?: Omit<NavigationSessionOptions, 'provider'>;
+    /** Camera bám vị trí khi dẫn đường — mặc định true (zoom theo phương tiện, pitch 45). */
+    follow?: boolean | FollowOptions;
+    /** Vẽ mũi tên vị trí — mặc định true; false để app tự vẽ từ `progress.snapped`. */
+    puck?: boolean;
+    routeStyle?: RouteStyle;
+    /** Chèn tuyến dưới lớp này; mặc định lớp symbol đầu tiên của theme; null = trên cùng. */
+    routeBeforeLayerId?: string | null;
+    /** Bấm tuyến thay thế. */
+    onRouteClick?: (index: number) => void;
     onLoad?: (map: MapHandle) => void;
     onPoiClick?: (poi: PoiFeature) => void;
     onError?: (error: Error) => void;
     testID?: string;
     children?: ReactNode;
 }
-declare function MapsLibVNMap({ apiKey, apiBase, style, center, zoom, lang, poiLayer, poiSources, compactAttribution, bundleId, containerStyle, onLoad, onPoiClick, onError, testID, children, }: MapsLibVNMapProps): react.JSX.Element;
+declare function MapsLibVNMap({ apiKey, apiBase, style, center, zoom, lang, poiLayer, poiSources, compactAttribution, bundleId, containerStyle, navigation, sessionOptions, follow, puck, routeStyle, routeBeforeLayerId, onRouteClick, onLoad, onPoiClick, onError, testID, children, }: MapsLibVNMapProps): react.JSX.Element;
 /** Map hiện hành — chỉ dùng bên trong <MapsLibVNMap>. */
 declare function useMap(): MapHandle;
 
@@ -297,7 +153,32 @@ 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;
 
+interface UseNavigationResult {
+    status: NavigationStatus;
+    progress: NavigationProgress | null;
+    /** Camera của map trong context đang bám; luôn false khi hook nhận `session` tường minh. */
+    following: boolean;
+    start(opts: NavigationSessionStartOptions): Promise<void>;
+    stop(): Promise<void>;
+    reroute(): Promise<void>;
+    /** Bật lại bám camera của map trong context; no-op khi không có map. */
+    recenter(): void;
+}
+/**
+ * Không tham số → dùng `useMap().navigation` (phải nằm trong `<MapsLibVNMap>`).
+ * Có `session` → dùng được ở bất kỳ đâu (banner ngoài map, màn hình khác).
+ */
+declare function useNavigation(session?: NavigationSession): UseNavigationResult;
+
 /** Dòng gọn khi `compactAttribution`; bấm vào mở hộp thoại native với đủ nguồn. */
 declare const COMPACT_ATTRIBUTION = "\u00A9 MapsLibVN \u00B7 \u00A9 OpenStreetMap contributors";
 
-export { type AutocompleteItem, COMPACT_ATTRIBUTION, DEFAULT_CENTER, DEFAULT_MARKER_COLOR, DEFAULT_ZOOM, type Lang, type MapHandle, type MapsLibVNClient, MapsLibVNMap, type MapsLibVNMapProps, Marker, type MarkerProps, type Place, type PoiFeature, type PoiSource, type Theme, type UsePlacesOptions, type UsePlacesResult, useMap, usePlaces };
+/**
+ * Phát lại chuỗi fix (ví dụ từ `simulateFixes`) theo chênh timestamp chia `rate`; `rate: 0` phát
+ * hết trong một tick. Copy từ `@mapslibvn/web` — core không có timer nên không đặt ở đó.
+ */
+declare function playbackSource(fixes: readonly GeoFix[], options?: {
+    rate?: number;
+}): PositionSource;
+
+export { ALT_ROUTE_COLOR, AutocompleteItem, type BindingEvents, COMPACT_ATTRIBUTION, DEFAULT_CENTER, DEFAULT_MARKER_COLOR, DEFAULT_ZOOM, DESTINATION_COLOR, DirectionsResponse, FOLLOW_PITCH, FOLLOW_ZOOM, type FollowOptions, GeoFix, Lang, type MapHandle, type MapNavigationBinding, MapsLibVNClient, MapsLibVNMap, type MapsLibVNMapProps, Marker, type MarkerProps, NavigationProgress, NavigationSession, NavigationSessionOptions, NavigationSessionStartOptions, NavigationStatus, PoiFeature, PoiSource, PositionSource, ROUTE_COLOR, ROUTE_LAYER_IDS, ROUTE_SOURCE_ID, type RouteStyle, SessionEvents, Theme, TravelMode, type UseNavigationResult, type UsePlacesOptions, type UsePlacesResult, playbackSource, useMap, useNavigation, usePlaces };