@maplibre/maplibre-react-native 11.0.0-beta.8 → 11.0.0

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

@@ -0,0 +1,304 @@
+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:
+ *
+ * - Transforming the URL with search and replace
+ * - Adding URL search params
+ * - Adding HTTP headers
+ *
+ * Transforms are applied in this order. The `match` conditions are applied to
+ * possibly already transformed URLs.
+ *
+ * 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`.
+   *
+   * @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.
+   *
+   * @example Upgrade all requests to HTTPS
+   * ```ts
+   * TransformRequestManager.addUrlTransform({
+   *   id: "force-https",
+   *   find: "^http://",
+   *   replace: "https://",
+   * });
+   * ```
+   *
+   * @example Redirect a specific domain through a proxy
+   * ```ts
+   * 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
+   * ```ts
+   * TransformRequestManager.addUrlTransform({
+   *   id: "api-key",
+   *   match: "api\\.example\\.com",
+   *   find: "(https://api\\.example\\.com/)(.*)",
+   *   replace: "$1mySecretKey/$2",
+   * });
+   * ```
+   */
+  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.
+   *
+   * @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.
+   *
+   * @example Add apiKey to for a specific domain
+   * ```ts
+   * TransformRequestManager.addUrlSearchParam({
+   *   match: /tiles\.example\.com/,
+   *   name: "apiKey",
+   *   value: "your-api-key",
+   * });
+   * ```
+   *
+   * @example Add apiKey to all requests (no match = applies to all)
+   * ```ts
+   * TransformRequestManager.addUrlSearchParam({
+   *   name: "apiKey",
+   *   value: "your-api-key",
+   * });
+   * ```
+   */
+  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.
+   *
+   * @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.
+   *
+   * @example Add header to all requests
+   * ```
+   * TransformRequestManager.addHeader({ name: "Authorization", value: "Bearer token123" });
+   * ```
+   *
+   * @example Add header only to requests matching a pattern
+   * ```ts
+   * TransformRequestManager.addHeader({
+   *   name: "X-API-Key",
+   *   value: "key123",
+   *   match: /https:\/\/api\.example\.com\/tiles\//,
+   * });
+   * ```
+   */
+  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 };

package/src/plugin/MapLibrePluginProps.ts

@@ -7,7 +7,7 @@ export type MapLibrePluginProps =
       /**
        * Properties relevant only for Android
        *
-       * @platform android
+       * @platform Android
        */
       android?: {
         /**
@@ -17,7 +17,7 @@ export type MapLibrePluginProps =
         /**
          * Variant of `org.maplibre.gl:android-sdk-*`
          *
-         * @default "opengl"
+         * @defaultValue "opengl"
          */
         nativeVariant?: "opengl" | "vulkan";
         /**
@@ -37,13 +37,15 @@ export type MapLibrePluginProps =
          * Location engine to be used
          *
          * - `default`: Used per default from MapLibre; F-Droid compatible
-         * - `google`: Google Play Services Location Engine for higher precision; F-Droid incompatible
+         * - `google`: Google Play Services Location Engine for higher precision; F-Droid
+         *   incompatible
          *
-         * @default "default"
+         * @defaultValue "default"
          */
         locationEngine?: "default" | "google";
         /**
-         * Version for `com.google.android.gms:play-services-location`, only used with `locationEngine: "google"`
+         * Version for `com.google.android.gms:play-services-location` , only used with
+         * `locationEngine: "google"`
          */
         googlePlayServicesLocationVersion?: VersionString;
       };
@@ -51,7 +53,7 @@ export type MapLibrePluginProps =
       /**
        * Properties relevant only for iOS
        *
-       * @platform ios
+       * @platform iOS
        */
       ios?: {
         /**
@@ -62,14 +64,7 @@ export type MapLibrePluginProps =
         /**
          * Swift Package Manager spec to override the selected version range
          *
-         * @default `{
-         *   url: "https://github.com/maplibre/maplibre-gl-native-distribution",
-         *   requirement: {
-         *     kind: "exactVersion",
-         *     version: $MLRN_NATIVE_VERSION
-         *   },
-         *   product_name: "MapLibre"
-         * }`
+         * @defaultValue `{ url: "https://github.com/maplibre/maplibre-gl-native-distribution", requirement: { kind: "exactVersion", version: $MLRN_NATIVE_VERSION }, product_name: "MapLibre" }`
          *
          * @example
          * ```ts
@@ -80,7 +75,7 @@ export type MapLibrePluginProps =
          *     minimumVersion: "x.x.x"
          *   },
          *   product_name: "MapLibre"
-         * }`
+         * }`;
          * ```
          */
         spmSpec?: string;

package/src/plugin/ios.ts

@@ -13,8 +13,8 @@ import type { MapLibrePluginProps } from "./MapLibrePluginProps";
 const TAG_PREFIX = `@maplibre/maplibre-react-native`;
 
 /**
- * Only the post-install block is required, the post installer block is used for SPM (Swift Package Manager) which Expo
- * doesn't currently support.
+ * Only the post-install block is required, the post installer block is used for
+ * SPM (Swift Package Manager) which Expo doesn't currently support.
  */
 export function applyPodfilePostInstall(contents: string): string {
   const result = mergeContents({
@@ -88,38 +88,60 @@ export const withPodfileGlobalVariables: ConfigPlugin<MapLibrePluginProps> = (
 };
 
 const withoutSignatures: ConfigPlugin = (config) => {
-  return withXcodeProject(config, async (c) => {
-    c.modResults.addBuildPhase(
-      [],
-      "PBXShellScriptBuildPhase",
-      "Remove signature files (Xcode workaround)",
-      null,
-      {
-        shellPath: "/bin/sh",
-        shellScript: `
-          echo "Remove signature files (Xcode workaround)";
+  return withXcodeProject(config, (c) => {
+    const project = c.modResults;
+    const targetName = c.modRequest.projectName;
+    const phaseName =
+      "[MapLibre React Native] Remove MapLibre.xcframework-ios.signature";
+
+    const nativeTargetId = project.findTargetKey(targetName ?? "");
+    if (!nativeTargetId) {
+      console.warn(
+        `[MapLibre React Native] Could not find target "${targetName}" to add build phase script`,
+      );
+      return c;
+    }
+
+    const buildPhases =
+      project.pbxNativeTargetSection()[nativeTargetId]?.buildPhases ?? [];
+    const alreadyExists = buildPhases.some(
+      (phase: { comment?: string }) => phase.comment === phaseName,
+    );
+
+    if (!alreadyExists) {
+      project.addBuildPhase(
+        [],
+        "PBXShellScriptBuildPhase",
+        phaseName,
+        nativeTargetId,
+        {
+          shellPath: "/bin/sh",
+          shellScript: `
+          echo "[MapLibre React Native] Remove MapLibre.xcframework-ios.signature";
           rm -rf "$CONFIGURATION_BUILD_DIR/MapLibre.xcframework-ios.signature";
         `,
-      },
-    );
+        },
+      );
+    }
 
     return c;
   });
 };
 
 /**
- *  Set the Debug Information Format to DWARF with dSYM File during EAS Build for Managed App
- *  https://github.com/expo/eas-cli/issues/968
+ * Set the Debug Information Format to DWARF with dSYM File during EAS Build for
+ * Managed App https://github.com/expo/eas-cli/issues/968
+ *
+ * Set `artifactPath` in `eas.json`:
  *
- *  Set `artifactPath` in `eas.json`:
- *  ```json
- *  "ios": {
+ * ```json
+ * "ios": {
  *    "artifactPath": "ios/build/*"
  *  }
- *  ```
+ * ```
  */
 const withDwarfDsym: ConfigPlugin = (config) => {
-  return withXcodeProject(config, async (c) => {
+  return withXcodeProject(config, (c) => {
     c.modResults.debugInformationFormat = "dwarf-with-dsym";
 
     return c;

package/src/types/Anchor.ts

@@ -1,8 +1,8 @@
 /**
- * Position anchor for markers and annotations.
- * Follows MapLibre GL JS PositionAnchor format.
+ * Position anchor for markers and annotations. Follows MapLibre GL JS
+ * PositionAnchor format.
  *
- * @see https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PositionAnchor/
+ * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/PositionAnchor/}
  */
 export type Anchor =
   | "center"
@@ -16,9 +16,8 @@ export type Anchor =
   | "bottom-right";
 
 /**
- * Converts an Anchor string to native {x, y} format.
- * x: 0 = left, 0.5 = center, 1 = right
- * y: 0 = top, 0.5 = center, 1 = bottom
+ * Converts an Anchor string to native {x, y} format. x: 0 = left, 0.5 = center,
+ * 1 = right y: 0 = top, 0.5 = center, 1 = bottom
  */
 export function anchorToNative(anchor: Anchor): { x: number; y: number } {
   switch (anchor) {

package/src/types/BaseProps.ts

@@ -1,3 +1,6 @@
+/**
+ * Base props supported by all components.
+ */
 export interface BaseProps {
   testID?: string;
 }

package/src/types/LngLatBounds.ts

@@ -1,7 +1,8 @@
 /**
  * Represents bounds in geographic coordinates
  *
- * Uses order of south-west and north-east corners in flat style per GeoJSON RFC.
+ * Uses order of south-west and north-east corners in flat style per GeoJSON
+ * RFC.
  */
 export type LngLatBounds = [
   west: number,