@maplibre/maplibre-react-native 11.0.0-beta.2 → 11.0.0-beta.21

package/src/components/user-location/UserLocation.tsx

@@ -1,9 +1,11 @@
 import { memo, type ReactNode, useMemo } from "react";
 
 import { UserLocationPuck } from "./UserLocationPuck";
+import headingIcon from "../../assets/heading.png";
 import { useCurrentPosition } from "../../hooks/useCurrentPosition";
 import type { LngLat } from "../../types/LngLat";
 import { LayerAnnotation } from "../annotations/LayerAnnotation";
+import { Images } from "../images/Images";
 
 export interface UserLocationProps {
   /**
@@ -59,26 +61,36 @@ export const UserLocation = memo(
     }
 
     return (
-      <LayerAnnotation
-        animated={animated}
-        id="mlrn-user-location"
-        testID="mlrn-user-location"
-        onPress={onPress}
-        lngLat={lngLat}
-      >
-        {children || (
-          <UserLocationPuck
-            testID="mlrn-user-location-puck"
-            source="mlrn-user-location"
-            accuracy={accuracy ? currentPosition.coords.accuracy : undefined}
-            heading={
-              heading
-                ? (currentPosition.coords.heading ?? undefined)
-                : undefined
-            }
+      <>
+        {heading && (
+          <Images
+            images={{
+              "mlrn-user-location-puck-heading": headingIcon,
+            }}
           />
         )}
-      </LayerAnnotation>
+
+        <LayerAnnotation
+          animated={animated}
+          id="mlrn-user-location"
+          testID="mlrn-user-location"
+          onPress={onPress}
+          lngLat={lngLat}
+        >
+          {children || (
+            <UserLocationPuck
+              testID="mlrn-user-location-puck"
+              source="mlrn-user-location"
+              accuracy={accuracy ? currentPosition.coords.accuracy : undefined}
+              heading={
+                heading
+                  ? (currentPosition.coords.heading ?? undefined)
+                  : undefined
+              }
+            />
+          )}
+        </LayerAnnotation>
+      </>
     );
   },
 );

package/src/components/user-location/UserLocationPuck.tsx

@@ -1,30 +1,30 @@
+import type { CircleLayerSpecification } from "@maplibre/maplibre-gl-style-spec";
 import { memo } from "react";
 
 import { UserLocationPuckHeading } from "./UserLocationPuckHeading";
 import type { BaseProps } from "../../types/BaseProps";
-import type { CircleLayerStyle } from "../../types/MapLibreRNStyles";
 import { Layer } from "../layer/Layer";
 
 const blue = "#33B5E5";
 
-const layerStyles = {
+const CIRCLE_LAYERS_PAINT = {
   accuracy: {
-    circleColor: blue,
-    circleOpacity: 0.2,
-    circlePitchAlignment: "map",
-    circleRadiusTransition: { duration: 300, delay: 0 },
+    "circle-color": blue,
+    "circle-opacity": 0.2,
+    "circle-pitch-alignment": "map",
+    "circle-radius-transition": { duration: 300, delay: 0 },
   },
   white: {
-    circleRadius: 9,
-    circleColor: "#fff",
-    circlePitchAlignment: "map",
+    "circle-radius": 9,
+    "circle-color": "#fff",
+    "circle-pitch-alignment": "map",
   },
   blue: {
-    circleRadius: 6,
-    circleColor: blue,
-    circlePitchAlignment: "map",
+    "circle-radius": 6,
+    "circle-color": blue,
+    "circle-pitch-alignment": "map",
   },
-} satisfies Record<"accuracy" | "white" | "blue", CircleLayerStyle>;
+} as const satisfies Record<string, CircleLayerSpecification["paint"]>;
 
 interface UserLocationPuckProps extends BaseProps {
   source: string;
@@ -43,16 +43,16 @@ export const UserLocationPuck = memo(
             id="mlrn-user-location-puck-accuracy"
             testID="mlrn-user-location-puck-accuracy"
             source={source}
-            style={{
-              ...layerStyles.accuracy,
-              circleRadius: [
+            paint={{
+              ...CIRCLE_LAYERS_PAINT.accuracy,
+              "circle-radius": [
                 "interpolate",
                 ["exponential", 2],
                 ["zoom"],
                 0,
-                layerStyles.white.circleRadius,
+                CIRCLE_LAYERS_PAINT.white["circle-radius"],
                 22,
-                layerStyles.white.circleRadius + accuracy * 100,
+                CIRCLE_LAYERS_PAINT.white["circle-radius"] + accuracy * 100,
               ],
             }}
           />
@@ -62,14 +62,14 @@ export const UserLocationPuck = memo(
           id="mlrn-user-location-puck-white"
           testID="mlrn-user-location-puck-white"
           source={source}
-          style={layerStyles.white}
+          paint={CIRCLE_LAYERS_PAINT.white}
         />
         <Layer
           type="circle"
           id="mlrn-user-location-puck-blue"
           testID="mlrn-user-location-puck-blue"
           source={source}
-          style={layerStyles.blue}
+          paint={CIRCLE_LAYERS_PAINT.blue}
         />
         {typeof heading === "number" && (
           <UserLocationPuckHeading

package/src/components/user-location/UserLocationPuckHeading.tsx

@@ -1,15 +1,14 @@
+import type { SymbolLayerSpecification } from "@maplibre/maplibre-gl-style-spec";
 import { memo } from "react";
 
-import headingIcon from "../../assets/heading.png";
 import { type BaseProps } from "../../types/BaseProps";
-import type { SymbolLayerStyle } from "../../types/MapLibreRNStyles";
 import { Layer } from "../layer/Layer";
 
-const layerStyle: SymbolLayerStyle = {
-  iconImage: headingIcon,
-  iconAllowOverlap: true,
-  iconPitchAlignment: "map",
-  iconRotationAlignment: "map",
+const SYMBOL_LAYER_LAYOUT: SymbolLayerSpecification["layout"] = {
+  "icon-image": "mlrn-user-location-puck-heading",
+  "icon-allow-overlap": true,
+  "icon-pitch-alignment": "map",
+  "icon-rotation-alignment": "map",
 };
 
 interface UserLocationPuckHeadingProps extends BaseProps {
@@ -26,9 +25,9 @@ export const UserLocationPuckHeading = memo(
       testID="mlrn-user-location-puck-heading"
       source={source}
       beforeId={beforeId}
-      style={{
-        ...layerStyle,
-        iconRotate: heading,
+      layout={{
+        ...SYMBOL_LAYER_LAYOUT,
+        "icon-rotate": heading,
       }}
     />
   ),

package/src/index.ts

@@ -24,10 +24,11 @@ export {
 } from "./components/map/Map";
 
 export {
-  ViewAnnotation,
-  type ViewAnnotationProps,
-  type ViewAnnotationRef,
   type ViewAnnotationEvent,
+  type NativeViewAnnotationRef,
+  type ViewAnnotationRef,
+  type ViewAnnotationProps,
+  ViewAnnotation,
 } from "./components/annotations/view-annotation/ViewAnnotation";
 
 export {
@@ -36,8 +37,8 @@ export {
 } from "./components/annotations/LayerAnnotation";
 
 export {
-  Callout,
   type CalloutProps,
+  Callout,
 } from "./components/annotations/callout/Callout";
 
 export { UserLocation } from "./components/user-location/UserLocation";
@@ -121,8 +122,10 @@ export {
 } from "./components/images/Images";
 
 export {
-  Marker,
+  type NativeMarkerRef,
+  type MarkerEvent,
   type MarkerProps,
+  Marker,
 } from "./components/annotations/marker/Marker";
 
 export {
@@ -155,6 +158,14 @@ export {
   type StaticMapCreateOptions,
 } from "./modules/static-map/StaticMapManager";
 
+export {
+  TransformRequestManager,
+  type TransformOptions,
+  type UrlTransformOptions,
+  type UrlSearchParamOptions,
+  type HeaderOptions,
+} from "./modules/transform-request/TransformRequestManager";
+
 export type { Anchor } from "./types/Anchor";
 export type { LngLat } from "./types/LngLat";
 export type { LngLatBounds } from "./types/LngLatBounds";

package/src/modules/network/NativeNetworkModule.ts

@@ -2,10 +2,6 @@ import type { TurboModule } from "react-native";
 import { TurboModuleRegistry } from "react-native";
 
 export interface Spec extends TurboModule {
-  addRequestHeader(name: string, value: string, match: string | null): void;
-
-  removeRequestHeader(name: string): void;
-
   setConnected(connected: boolean): void;
 }
 

package/src/modules/network/NetworkManager.ts

@@ -1,55 +1,9 @@
 import NativeNetworkModule from "./NativeNetworkModule";
 
 /**
- * NetworkManager provides methods for managing HTTP requests made by MapLibre.
- * This includes adding custom headers to tile requests and controlling network connectivity.
+ * NetworkManager provides methods for managing and controlling network connectivity.
  */
 class NetworkManager {
-  /**
-   * Adds a custom HTTP header that will be sent with all map tile requests.
-   * This is useful for adding authentication tokens or other custom headers
-   * required by your tile server.
-   *
-   * @example
-   * // Add header to all requests
-   * NetworkManager.addRequestHeader("Authorization", "Bearer token123");
-   *
-   * // Add header only to requests matching a regex pattern (string)
-   * NetworkManager.addRequestHeader("X-API-Key", "key123", "https:\\/\\/api\\.example\\.com\\/tiles\\/");
-   *
-   * // Add header only to requests matching a regex pattern (RegExp)
-   * NetworkManager.addRequestHeader("X-API-Key", "key123", /https:\/\/api\.example\.com\/tiles\//);
-   *
-   * @param name The name of the header (e.g., "Authorization")
-   * @param value The value of the header (e.g., "Bearer token123")
-   * @param match Optional regex pattern to match against network URLs. If provided, the header will only be added to requests whose URLs match this pattern. Can be a RegExp object or a regex string.
-   */
-  static addRequestHeader(
-    name: string,
-    value: string,
-    match?: string | RegExp,
-  ): void {
-    NativeNetworkModule.addRequestHeader(
-      name,
-      value,
-      (match instanceof RegExp ? match.source : match) || null,
-    );
-  }
-
-  /**
-   * Removes a previously added custom HTTP header.
-   *
-   * @example
-   * ```ts
-   * NetworkManager.removeRequestHeader("Authorization");
-   * ```
-   *
-   * @param headerName The name of the header to remove
-   */
-  static removeRequestHeader(headerName: string): void {
-    NativeNetworkModule.removeRequestHeader(headerName);
-  }
-
   /**
    * Android only: Sets the connectivity state of the map. When set to false, the map will
    * not make any network requests and will only use cached tiles. This is

package/src/modules/transform-request/NativeTransformRequestModule.ts

@@ -0,0 +1,41 @@
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  addUrlTransform(
+    id: string,
+    match: string | null,
+    find: string,
+    replace: string,
+  ): void;
+
+  removeUrlTransform(id: string): void;
+
+  clearUrlTransforms(): void;
+
+  addUrlSearchParam(
+    id: string,
+    match: string | null,
+    name: string,
+    value: string,
+  ): void;
+
+  removeUrlSearchParam(id: string): void;
+
+  clearUrlSearchParams(): void;
+
+  addHeader(
+    id: string,
+    match: string | null,
+    name: string,
+    value: string,
+  ): void;
+
+  removeHeader(id: string): void;
+
+  clearHeaders(): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>(
+  "MLRNTransformRequestModule",
+);

package/src/modules/transform-request/TransformRequestManager.ts

@@ -0,0 +1,292 @@
+import NativeTransformRequestModule from "./NativeTransformRequestModule";
+
+export interface TransformOptions {
+  /**
+   * The id is used to identify a transform. Can be used to remove or update it.
+   * When omitted it will be auto-generated.
+   */
+  id?: string;
+
+  /**
+   * Optional regex to be used as the condition, if the transform should be
+   * applied. When omitted the transform will always be applied.
+   *
+   * Global flags are (like `/i`) are not supported. Supports only inline flags, e.g. `(?i)` for case-insensitive matching.
+   */
+  match?: RegExp | string;
+}
+
+/**
+ * A serializable transform for rewriting MapLibre request URLs.
+ *
+ * Transforms are applied as a pipeline in the order they were added: transform N+1 sees
+ * the URL *after* transform N has possibly changed it.
+ */
+export interface UrlTransformOptions extends TransformOptions {
+  /**
+   * Regex to find the portion of the URL to replace.
+   * Supports capture groups that can be back-referenced in `replace` as `$1`, `$2`, …
+   *
+   * Global flags are (like `/i`) are not supported. Supports only inline flags, e.g. `(?i)` for case-insensitive matching.
+   */
+  find: RegExp | string;
+
+  /**
+   * Replacement string. Reference capture groups from `find` with `$1`, `$2`, …
+   */
+  replace: string;
+}
+
+/**
+ * A URL query parameter to append to matching map resource requests.
+ */
+export interface UrlSearchParamOptions extends TransformOptions {
+  /** The query parameter name (e.g., `"apiKey"`). */
+  name: string;
+
+  /** The query parameter value (e.g., your API key). */
+  value: string;
+}
+
+/**
+ * A HTTP header to send with matching map resource requests.
+ */
+export interface HeaderOptions extends TransformOptions {
+  /** The header name (e.g., `"Authorization"`). */
+  name: string;
+
+  /** The header value (e.g., `"Bearer token123"`). */
+  value: string;
+}
+
+/**
+ * TransformRequestManager provides methods for managing HTTP requests made by MapLibre.
+ *
+ * Transformations are possible in three ways:
+ *
+ * 1. Transforming the URL with search and replace
+ * 2. Adding URL search params
+ * 3. Adding HTTP headers
+ *
+ * Transforms are applied in this order. The `match` conditions are applied to
+ * possibly already transformed URLs.
+ *
+ * @remarks
+ * To gain insight into which transforms are applied set the log level to
+ * `"debug"` via {@link LogManager}:
+ *
+ * ```ts
+ * LogManager.setLogLevel("debug");
+ * ```
+ */
+class TransformRequestManager {
+  /**
+   * Adds or updates a URL transform identified by `id`.
+   *
+   * Transforms execute in insertion order. Therefore `match` and `find` regexes
+   * are matched against possibly already modified URL by previous transforms.
+   *
+   * Re-adding an existing `id` updates the transform
+   * **in-place**, preserving its position in the pipeline. This makes it safe to
+   * refresh tokens or swap domains without disrupting the order of other transforms.
+   *
+   * URL transforms are applied before `addUrlSearchParam` and `addHeader`.
+   *
+   * @example
+   * // Upgrade all requests to HTTPS
+   * TransformRequestManager.addUrlTransform({
+   *   id: "force-https",
+   *   find: "^http://",
+   *   replace: "https://",
+   * });
+   *
+   * @example
+   * // Redirect a specific domain through a proxy
+   * TransformRequestManager.addUrlTransform({
+   *   id: "proxy",
+   *   match: "tiles\\.example\\.com",
+   *   find: "tiles\\.example\\.com",
+   *   replace: "proxy.example.com",
+   * });
+   *
+   * @example
+   * // Inject an API key into the path using a capture group
+   * TransformRequestManager.addUrlTransform({
+   *   id: "api-key",
+   *   match: "api\\.example\\.com",
+   *   find: "(https://api\\.example\\.com/)(.*)",
+   *   replace: "$1mySecretKey/$2",
+   * });
+   *
+   * @param options The transform. Set {@link TransformOptions.id} to a stable string to
+   *   enable in-place updates; if omitted an id is auto-generated and returned.
+   *
+   * @returns The id of the transform (the value of `transform.id` when provided, otherwise
+   *   the auto-generated one). Pass it to {@link removeUrlTransform} to remove it later.
+   */
+  addUrlTransform(options: UrlTransformOptions): string {
+    const id = options.id ?? this.getId();
+
+    NativeTransformRequestModule.addUrlTransform(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      TransformRequestManager.toRegexString(options.find) ?? "",
+      options.replace,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes the URL transform with the given `id`.
+   * No-op if the id is not registered.
+   *
+   * @param id The identifier passed to/returned from {@link addUrlTransform}.
+   */
+  removeUrlTransform(id: string): void {
+    NativeTransformRequestModule.removeUrlTransform(id);
+  }
+
+  /**
+   * Removes all registered URL transforms
+   */
+  clearUrlTransforms(): void {
+    NativeTransformRequestModule.clearUrlTransforms();
+  }
+
+  /**
+   * Adds or updates a URL query parameter identified by `id` that will be appended to all
+   * matching map resource requests. Re-adding an existing `id` updates the param in-place.
+   *
+   * @example
+   * // Add apiKey to for a specific domain
+   * TransformRequestManager.addUrlSearchParam({
+   *   match: /tiles\.example\.com/,
+   *   name: "apiKey",
+   *   value: "your-api-key",
+   * });
+   *
+   * // Add apiKey to all requests (no match = applies to all)
+   * TransformRequestManager.addUrlSearchParam({ name: "apiKey", value: "your-api-key" });
+   *
+   * @param options The options. Set {@link TransformOptions.id} to a stable string to
+   *   enable in-place updates; if omitted an id is auto-generated and returned.
+   *
+   * @returns The id of the options. Pass it to {@link removeUrlSearchParam} to remove it later.
+   */
+  addUrlSearchParam(options: UrlSearchParamOptions): string {
+    const id = options.id ?? this.getId();
+
+    NativeTransformRequestModule.addUrlSearchParam(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      options.name,
+      options.value,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes a previously added URL query parameter by its `id`.
+   *
+   * @param id The identifier passed to/returned from {@link addUrlSearchParam}.
+   */
+  removeUrlSearchParam(id: string): void {
+    NativeTransformRequestModule.removeUrlSearchParam(id);
+  }
+
+  /**
+   * Adds or updates an HTTP header identified by `id` that will be sent with all
+   * matching map resource requests. Re-adding an existing `id` updates the header in-place.
+   *
+   * @example
+   * // Add header to all requests
+   * TransformRequestManager.addHeader({ name: "Authorization", value: "Bearer token123" });
+   *
+   * // Add header only to requests matching a pattern
+   * TransformRequestManager.addHeader({
+   *   name: "X-API-Key",
+   *   value: "key123",
+   *   match: /https:\/\/api\.example\.com\/tiles\//,
+   * });
+   *
+   * @param options The options. Set {@link TransformOptions.id} to a stable string to
+   *   enable in-place updates; if omitted an id is auto-generated and returned.
+   *
+   * @returns The id of the options. Pass it to {@link removeHeader} to remove it later.
+   */
+  addHeader(options: HeaderOptions): string {
+    const id = options.id ?? this.getId();
+
+    NativeTransformRequestModule.addHeader(
+      id,
+      TransformRequestManager.toRegexString(options.match),
+      options.name,
+      options.value,
+    );
+
+    return id;
+  }
+
+  /**
+   * Removes all registered URL search params.
+   */
+  clearUrlSearchParams(): void {
+    NativeTransformRequestModule.clearUrlSearchParams();
+  }
+
+  /**
+   * Removes a previously added HTTP header by its `id`.
+   *
+   * @param id The identifier passed to/returned from {@link addHeader}.
+   */
+  removeHeader(id: string): void {
+    NativeTransformRequestModule.removeHeader(id);
+  }
+
+  /**
+   * Removes all registered HTTP headers.
+   */
+  clearHeaders(): void {
+    NativeTransformRequestModule.clearHeaders();
+  }
+
+  /**
+   * Removes all registered URL transforms, URL search params and HTTP headers.
+   */
+  clear(): void {
+    this.clearUrlTransforms();
+    this.clearUrlSearchParams();
+    this.clearHeaders();
+  }
+
+  private lastId: number = -1;
+
+  private getId() {
+    this.lastId++;
+
+    return "transform-request-" + this.lastId;
+  }
+
+  private static toRegexString(
+    value: string | RegExp | undefined,
+  ): string | null {
+    let result: string | undefined = undefined;
+    if (value instanceof RegExp) {
+      if (value.flags) {
+        throw new Error("Regex flags are not supported");
+      }
+
+      result = value.source;
+    } else {
+      result = value;
+    }
+
+    return result || null;
+  }
+}
+
+const transformRequestManager = new TransformRequestManager();
+
+export { transformRequestManager as TransformRequestManager };