@trackunit/react-map-adapter-shared

Shared types, adapter contracts, and utilities used by @trackunit/react-map-adapter-google and @trackunit/react-map-adapter-mapbox. This package does not depend on @trackunit/react-map, so adapters can be built and tested without the full map stack and without introducing a circular dependency between map and adapter code.

Installation

npm install @trackunit/react-map-adapter-shared

Typically used together with @trackunit/react-map and one of the adapter packages. Install the adapter alongside this shared package rather than depending on it directly unless you are building a custom adapter.

Dependency graph (simplified):

@trackunit/react-map  →  @trackunit/react-map-adapter-google  →  @trackunit/react-map-adapter-shared
@trackunit/react-map  →  @trackunit/react-map-adapter-mapbox   →  @trackunit/react-map-adapter-shared
@trackunit/react-map  →  @trackunit/react-map-adapter-shared   (direct)
@trackunit/react-map-adapter-shared  →  (e.g. @trackunit/geo-json-utils, react, zod)

Adapter libraries do not import @trackunit/react-map.

What lives here

• Core map types and interaction types (e.g. viewport, theme, GeoJSON-related types, layer port surface).
• defineAdapter, AdapterRendererProps, and related adapter wiring types.
• Shared constants (e.g. default center/zoom, map cursors), restrictBounds helpers, layer port utilities, antimeridian merge, map-specific viewport validation (validateInitialViewport), and other adapter-facing helpers.

Cross-provider parity helpers

A core principle of the map stack is that vendor-specific behaviour stays inside adapters, and no provider type ever leaks out of one. When one provider supports something another does not, the gap is closed inside the lagging adapter rather than pushed up to consumers — and the patch is extracted here so any adapter (including third-party ones) can reuse it.

The canonical example is geodesic arcs. Google Maps draws great-circle edges natively (geodesic: true); Mapbox GL renders Mercator straight lines. The Mapbox adapter therefore densifies edges to emulate the same arcs, using helpers published from this package:

| Export | Source | Role | | --- | --- | --- | | densifyGeodesicFeatures | geodesicDensify.ts | Inserts intermediate coordinates along polygon/line edges so a non-geodesic renderer draws great-circle arcs | | intermediatePoint | sphericalMath.ts | Spherical interpolation (slerp) between two coordinates on the WGS-84 sphere | | angularDistance | sphericalMath.ts | Great-circle (haversine) distance between two coordinates |

If you build a new adapter and hit a provider gap, prefer adding the cross-provider patch here over working around it at the call site.

Dependencies

@trackunit/geo-json-utils, React, and zod. It intentionally does not import @trackunit/react-map.

How other packages use it

• @trackunit/react-map depends on this library directly and re-exports types where needed so existing map consumers keep stable import paths.
• Google and Mapbox adapter libraries depend on this package only—not on @trackunit/react-map.

Vendor abstraction

This library is the boundary between application code and map providers. The guiding rule: nothing outside an adapter may import from a provider SDK (mapbox-gl, @vis.gl/react-google-maps, Google Maps JS API types, etc.). All vendor-specific types, API calls, and behaviour belong inside the adapter that wraps that provider.

When a map feature is supported by one provider but not another:

1. Seriously consider not building it. Asymmetric features create an implicit split in the user experience across providers.
2. If you do build it, patch the other adapter. For example, Mapbox lacks native geodesic arcs. The Mapbox adapter emulates them to match Google Maps behaviour. The emulation is extracted into a reusable utility and exported from this library so custom adapter authors can benefit from the same work.

This means the adapter shared library also accumulates cross-provider utilities for things like:

• Antimeridian polygon splitting and merging
• Bounding box restriction helpers
• Spherical geometry for providers that need manual calculations

When you build such a patch, extract it here rather than burying it inside one adapter implementation.

Building a custom adapter

defineAdapter is the entry point. Its factory must return an AdapterConfigBase object with name, config, safeAreaInsets, createInstance, and Renderer:

import { defineAdapter } from "@trackunit/react-map-adapter-shared";

export const myAdapter = defineAdapter((config: MyConfig) => ({
  name: "my-provider",
  config,
  safeAreaInsets: null, // or pixel insets where the provider draws its own UI
  createInstance: () => createMyInstance(config),
  Renderer: MyRenderer,
}));

createInstance returns your AdapterInstance implementation; Renderer is the React component that subscribes to LayerPort snapshots and drives the provider. The LayerPort surface is the primary interface between @trackunit/react-map layer hooks and your renderer — layer hooks write declarative snapshots to a LayerPort and the adapter renderer subscribes to drive the provider. See the Google and Mapbox adapter sources for reference implementations.

Part of the @trackunit/react-map family

| Package | Description | | --- | --- | | @trackunit/react-map | Core provider-agnostic map library | | @trackunit/react-map-adapter-google | Google Maps adapter | | @trackunit/react-map-adapter-mapbox | Mapbox GL adapter | | @trackunit/react-map-adapter-shared | Shared adapter contracts and utilities (this package) | | @trackunit/react-map-color-utils | CSS color utilities for the map stack |

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Trackunit

This package was developed by Trackunit ApS. Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.