@mapslibvn/react-native 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+import * as react from 'react';
+import { RefObject, ReactNode, ReactElement } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { 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;
+    }[];
+}
+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 {
+    /** Ref `Map` của @maplibre/maplibre-react-native — không giấu gì. */
+    native: RefObject<MapRef | null>;
+    camera: RefObject<CameraRef | null>;
+    /** Client @mapslibvn/core với cùng khoá. */
+    places: MapsLibVNClient;
+    flyTo(center: [number, number], zoom?: number): void;
+    fitBounds(bbox: [number, number, number, number], padding?: number): void;
+    /** [west, south, east, north] */
+    getBounds(): Promise<[number, number, number, number]>;
+}
+
+declare const DEFAULT_CENTER: [number, number];
+declare const DEFAULT_ZOOM = 12;
+interface MapsLibVNMapProps {
+    apiKey: string;
+    /** Gốc API MapsLibVN, ví dụ https://api.ai-solutions.io.vn */
+    apiBase: string;
+    /** Theme 'light' | 'dark' hoặc URL style tuỳ biến — giống @mapslibvn/react. */
+    style?: Theme | string;
+    /** Giá trị KHỞI TẠO camera; đổi sau khi mount không tạo lại map — dùng useMap().flyTo. */
+    center?: [number, number];
+    zoom?: number;
+    lang?: Lang;
+    /** Hiển thị lớp POI — mặc định true */
+    poiLayer?: boolean;
+    /** Tập nguồn POI cho bản đồ và Places API — mặc định cả ba; đổi sau khi mount tạo lại map. */
+    poiSources?: readonly PoiSource[];
+    /** Attribution gọn (không có tuỳ chọn tắt) */
+    compactAttribution?: boolean;
+    /** Bundle id / application id của app → header X-Bundle-Id cho khoá mobile */
+    bundleId?: string;
+    /** Style của khung View bọc ngoài */
+    containerStyle?: StyleProp<ViewStyle>;
+    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;
+/** Map hiện hành — chỉ dùng bên trong <MapsLibVNMap>. */
+declare function useMap(): MapHandle;
+
+/** Màu ghim mặc định của MapLibre. */
+declare const DEFAULT_MARKER_COLOR = "#3FB1CE";
+interface MarkerProps {
+    lng: number;
+    lat: number;
+    /** Màu ghim mặc định; bỏ qua khi có children */
+    color?: string;
+    /** Điểm neo — mặc định 'center' (ghim tròn) */
+    anchor?: Anchor;
+    onPress?: () => void;
+    /** View tuỳ ý thay ghim mặc định */
+    children?: ReactElement;
+    testID?: string;
+}
+declare function Marker({ lng, lat, color, anchor, onPress, children, testID, }: MarkerProps): react.JSX.Element;
+
+interface UsePlacesOptions {
+    near?: [number, number];
+    limit?: number;
+    debounceMs?: number;
+    /** Client tường minh — bắt buộc khi hook nằm ngoài <MapsLibVNMap>. */
+    client?: MapsLibVNClient;
+}
+interface UsePlacesResult {
+    items: AutocompleteItem[];
+    loading: boolean;
+    error: Error | null;
+}
+/** 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;
+
+/** 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 };