lecodes-sdk 0.19.1 → 0.20.0

package/dist/types/plugins/map.d.ts

@@ -0,0 +1,174 @@
+import { NativeView } from "../ui/NativeView";
+import type { FetchResponse } from "../runtime/fetch";
+/** The ready-made styles a map falls back on — [OpenFreeMap](https://openfreemap.org): OSM data,
+ *  no key, no registration, no request limits, commercial use allowed, and the whole stack is
+ *  open-source if you'd rather self-host. `liberty` is the default. Credit them (and OSM) in your
+ *  app: "© OpenFreeMap © OpenMapTiles, data from OpenStreetMap". A public free instance is a
+ *  donation-funded service with no SLA — for a product with real traffic, run your own tiles and
+ *  pass that style's URL instead. */
+export type MapStyleName = "liberty" | "bright" | "positron" | "dark" | "fiord";
+/**
+ * Where the map's style comes from:
+ *
+ * - a **name** — `"liberty"` (the default), `"positron"`, … see {@link MapStyleName}: a ready-made
+ *   style on a free public tile server, so `MapView()` alone already draws a world map;
+ * - a **URL** — `"https://tiles.example.com/styles/city/style.json"`, the map fetches it;
+ * - a **bundled style** — `asset("./map/style.json")`: the file ships inside the app and the
+ *   wrapper hands its text to the map, so the style itself needs no server (tiles, sprites and
+ *   glyphs are still fetched from whatever urls it names);
+ * - an **already-read file** — a `FetchResponse` from `fetchLocal("style.json")` or
+ *   `await fetch(url)` (a style downloaded once and cached in `files`);
+ * - the **style object** itself — the natural way to substitute a tile-server address at runtime:
+ *   `{ ...style, sources: { openmaptiles: { type: "vector", url: `${server}/data/v3.json` } } }`.
+ *
+ * Whichever form: **every url INSIDE the style (`sources[].url`, `sprite`, `glyphs`) must be
+ * absolute.** maplibre-native, unlike maplibre-gl-js, resolves no relative ones — a style with
+ * them loads to an empty basemap (your layers still draw). A tileserver-gl instance emits
+ * relative urls until its `publicUrl` is configured.
+ */
+export type MapStyle = MapStyleName | (string & {}) | FetchResponse | object;
+/** `[longitude, latitude]` — GeoJSON order, the same as the style, the tiles and your data. */
+export type LngLat = [number, number];
+export interface MapCamera {
+    center: LngLat;
+    zoom: number;
+    /** Degrees clockwise from north. */
+    bearing: number;
+    /** Degrees from the vertical. */
+    pitch: number;
+}
+export interface MapOptions {
+    /** The MapLibre style: a ready-made name (`"liberty"` — the default, `"positron"`, …), a URL,
+     *  a style bundled with the app (`asset("./style.json")`), an already-read file
+     *  (`fetchLocal("style.json")`, `await fetch(url)`) or the style object itself — see
+     *  {@link MapStyle}. */
+    style?: MapStyle;
+    center?: LngLat;
+    zoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    bearing?: number;
+    pitch?: number;
+    /** Two-finger rotate gesture (default true). */
+    rotate?: boolean;
+    /** Two-finger tilt gesture (default false — most city maps stay flat). */
+    tilt?: boolean;
+}
+/** A tap on the map itself — not on a feature of a managed layer. */
+export interface MapTap {
+    lngLat: LngLat;
+    /** View-space point, px. */
+    point: [number, number];
+}
+export interface CameraMove {
+    zoom?: number;
+    bearing?: number;
+    pitch?: number;
+    /** Animation length, ms (flyTo only; default 600). */
+    duration?: number;
+}
+export interface MapPaddingValues {
+    top?: number | string;
+    left?: number | string;
+    bottom?: number | string;
+    right?: number | string;
+}
+export interface FitOptions {
+    /** Px around the points, or per edge. Added to the view padding set by `setPadding`. */
+    padding?: number | MapPaddingValues;
+    maxZoom?: number;
+    /** Default true. */
+    animate?: boolean;
+}
+/** One marker. `id` comes back in `onTap`; `icon` names an image of the style's sprite; `color` /
+ *  `title` feed the default layers; extra keys become feature properties. */
+export interface MarkerItem {
+    id: string | number;
+    lngLat: LngLat;
+    icon?: string;
+    color?: string;
+    title?: string;
+    [property: string]: any;
+}
+export interface MarkerTap {
+    id: string | number;
+    lngLat: LngLat;
+    /** Every property of the tapped feature (the item's keys, `id` and `lngLat` excluded). */
+    properties: Record<string, any>;
+}
+export interface MarkerLayerOptions {
+    /** Group nearby markers into clusters (a cluster tap zooms in). Default false. */
+    cluster?: boolean;
+    /** Cluster radius, px (default 50). */
+    clusterRadius?: number;
+    /** Zoom at which clusters stop forming (default: maxZoom − 1). */
+    clusterMaxZoom?: number;
+}
+export interface LineLayerOptions {
+    color?: string;
+    /** Px (default 4). */
+    width?: number;
+    /** 0–1 (default 1). */
+    opacity?: number;
+}
+export interface UserLocationOptions {
+    /** Horizontal accuracy radius, meters — drawn as the halo around the dot. */
+    accuracy?: number | null;
+    /** Degrees clockwise from north — drawn as the direction wedge; null hides it. */
+    heading?: number | null;
+}
+export interface MarkerLayer {
+    readonly name: string;
+    /** Replace the layer's markers. */
+    set(items: MarkerItem[]): this;
+    clear(): this;
+    /** A marker (or any feature of this layer's source) was tapped. */
+    onTap(callback: (marker: MarkerTap) => void): this;
+}
+export interface LineLayer {
+    readonly name: string;
+    /** Replace the line with these vertices. */
+    set(coordinates: LngLat[]): this;
+    clear(): this;
+}
+export interface MapView extends NativeView {
+    /** The style loaded and the map is interactive (queued calls have been replayed). */
+    onReady(callback: () => void): this;
+    /** A tap that hit no feature of a managed layer. */
+    onTap(callback: (tap: MapTap) => void): this;
+    /** The camera settled after a gesture or an animation. */
+    onMove(callback: (camera: MapCamera) => void): this;
+    /** The map reported a problem — a style that wouldn't load, a source it couldn't reach. Never
+     *  fatal; with no handler the message goes to `console.error`, so it is never silent. */
+    onError(callback: (error: {
+        message: string;
+    }) => void): this;
+    /** A named marker layer (one GeoJSON source). If the style already declares a source with this
+     *  name, its layers are used as-is and only the data is pushed; otherwise the plugin creates the
+     *  source and default marker layers (colored dot, `icon`, `title` label; clusters on request). */
+    markers(name: string, options?: MarkerLayerOptions): MarkerLayer;
+    /** A named line layer (one GeoJSON source) — same style-first rule as `markers`. */
+    line(name: string, options?: LineLayerOptions): LineLayer;
+    /** Raw escape hatch: replace the data of any GeoJSON source in the style. */
+    setData(source: string, geojson: object): this;
+    flyTo(center: LngLat, options?: CameraMove): this;
+    jumpTo(center: LngLat, options?: CameraMove): this;
+    /** Fit the camera to these points (padding + the view padding respected). */
+    fitPoints(points: LngLat[], options?: FitOptions): this;
+    /** Content inset: the part of the view covered by your UI (`"40%"` = of the view's size).
+     *  Camera operations center inside the remaining area. */
+    setPadding(padding: MapPaddingValues): this;
+    getCamera(): Promise<MapCamera>;
+    /** Move the user puck (the map draws it; the position comes from you — `Geolocation.watch`).
+     *  `null` hides it. */
+    setUserLocation(lngLat: LngLat | null, options?: UserLocationOptions): this;
+}
+/**
+ * Create a map view. `MapView.isSupported` reports whether this host registered a "map" view —
+ * check it before offering the feature (web, headless and shells without the plugin have none).
+ */
+export declare const MapView: {
+    (options?: MapOptions): MapView;
+    /** Whether this host registered a "map" view. */
+    readonly isSupported: boolean;
+};