@delacour/react-native-ui 0.2.0-alpha.20261015134956 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.2.0-alpha.20261015134956",
+	"version": "0.2.0",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -58,6 +58,7 @@
 		"./kpi": "./src/components/kpi/index.ts",
 		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
+		"./map": "./src/components/map/index.ts",
 		"./menu": "./src/components/menu/index.ts",
 		"./meter": "./src/components/meter/index.ts",
 		"./overlay": "./src/components/overlay/index.ts",
@@ -115,6 +116,7 @@
 		"tailwind-variants": "^3.3.1"
 	},
 	"peerDependencies": {
+		"@maplibre/maplibre-react-native": "^11.5.0",
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
 		"@delacour/react-native-bottom-sheet": ">=0.1.0",
 		"@delacour/react-native-charts": ">=0.1.0",
@@ -136,6 +138,9 @@
 		"uniwind": "^1.11.0"
 	},
 	"peerDependenciesMeta": {
+		"@maplibre/maplibre-react-native": {
+			"optional": true
+		},
 		"@delacour/react-native-bottom-sheet": {
 			"optional": true
 		},
@@ -156,6 +161,7 @@
 		}
 	},
 	"devDependencies": {
+		"@maplibre/maplibre-react-native": "^11.5.0",
 		"@delacour/biome-config": "workspace:*",
 		"@delacour/react-native-bottom-sheet": "workspace:*",
 		"@delacour/react-native-charts": "workspace:*",

package/src/components/map/AGENTS.md

@@ -0,0 +1,172 @@
+# Map
+
+A themed map for showing places and paths — a store finder, a delivery route, a
+run. MapLibre on both platforms, through `@maplibre/maplibre-react-native`, on a
+basemap painted from the theme's tokens.
+Compound root plus eight parts: `Marker`, `Pin`, `Label`, `Popup`, `Controls`,
+`Route`, `Arc`, `UserLocation`. A display component: no search, no geocoding,
+no directions.
+
+`import { Map, type MapHandle } from "@delacour/react-native-ui/map";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/map` |
+| `map.tsx` | Root, the camera handle, the overlay layer, and the `Object.assign` compound surface |
+| `map-marker.tsx` | `Map.Marker` — a React view on a coordinate, anchored on its pin's tip |
+| `map-pin.tsx` | `Map.Pin` — the drawn teardrop, which reports its frame to the marker |
+| `map-label.tsx` | `Map.Label` — a pill of text on `Surface` |
+| `map-popup.tsx` | `Map.Popup` — a card with a caret, inside a marker or on its own coordinate |
+| `map-controls.tsx` | `Map.Controls` — zoom, locate, compass and recenter, on the overlay layer |
+| `map-route.tsx` | `Map.Route` — a GeoJSON source and a line layer |
+| `map-arc.tsx` | `Map.Arc` — a sampled quadratic curve, drawn the same way |
+| `map-user-location.tsx` | `Map.UserLocation` — a themed dot drawn as circle layers, plus a heading cone |
+| `map.context.tsx` | `MapProvider`, `useMap()`, `useMapContext()`, `useMapPart()`, the user-location and marker contexts |
+| `map.types.ts` | `LngLat`, `LngLatBounds`, `ViewState`, `MapHandle` — no RN imports |
+| `map-geometry.ts` | `fitBoundsCamera`, `boundsOf`, `arcCoordinates`, `normalizeLongitude` — pure |
+| `map-geometry.test.ts` | |
+| `map.variants.ts` | The slotted `tv()`, the axes, the pin outline, anchors, the themed basemap style — type imports only |
+| `map.variants.test.ts` | |
+
+`src/no-maplibre.test.ts`, one level up, holds the import-graph rule below.
+
+## Design
+
+- **`@maplibre/maplibre-react-native` is an optional peer, and only this folder may
+  import it.** It is the one native module the library adds for a single component.
+  Expo does not bundle it, so it is not in the root catalog; each workspace that
+  needs it repeats the range. An app that never imports `/map` never installs it —
+  but only while nothing else reaches it, so `src/no-maplibre.test.ts` reads the
+  whole tree as text and fails by file name for any import of an `@maplibre/`
+  package, or of this folder, from outside it. Types come from the RN package's
+  own re-exports, never `@maplibre/maplibre-gl-style-spec`, which is only a
+  transitive dependency.
+- **MapLibre over the platform maps.** Apple Maps takes no style beyond light and
+  dark, and Google Maps needs a key and styles Android alone. MapLibre draws the
+  same vector basemap on both, from a style this folder writes, so a retuned theme
+  retunes the map on both platforms.
+- **Coordinates are `[lng, lat]`, everywhere a caller sees one.** That is GeoJSON's
+  order, every web map library's, and MapLibre's, so nothing is converted. The
+  public types are `readonly`; MapLibre's are mutable, so a coordinate is copied
+  into a fresh tuple at the boundary.
+- **Props set the initial view only; the ref moves the camera.** A map that
+  re-centred on every `center` change would fight a user mid-pan the first time a
+  parent re-rendered with a new array. The view is captured on mount; a change to
+  `center`, `zoom` or `bounds` afterwards warns in development
+  (`hasInitialViewChanged`, compared by value so a fresh array is not a change).
+  `flyTo`, `fitBounds`, `recenter` and `getViewState` are on the `ref`, and
+  `useMap()` hands the same handle to anything inside. The handle drives a
+  MapLibre `Camera` — `flyTo` for a move, `jumpTo` when the duration is `0`.
+- **The map mounts after its root is measured.** A `bounds` opening is a centre and
+  zoom worked out for the view's size (`resolveInitialCamera`), and one guessed
+  before layout opens at the wrong zoom. The root paints `bg-muted` for that one
+  frame.
+- **Zoom is the web-map scale.** `0` is the world and each step halves it, on
+  MapLibre's 512-point tiles, so a zoom copied from a web map means the same here.
+- **Bounds are framed here, not by the native fit, and are antimeridian-safe.** A
+  box with `west > east` crosses 180°; a fit that takes corners frames it the long
+  way round the world. `fitBoundsCamera` measures the box eastwards and in Web
+  Mercator, and returns a centre and zoom for the camera, so `fitBounds` and a
+  `bounds` opening are the same sum. `boundsOf` picks the box that leaves out the
+  widest stretch of longitude no point touches, so three stops across Fiji are a
+  box a few degrees wide rather than one spanning the world.
+- **A marker anchors on its pin's tip.** `Map.Pin` reports its frame inside the
+  marker and `resolvePinTipAnchor` turns it into an anchor point, so a popup over
+  the pin or a label under it changes the marker's size without moving the place
+  it marks. MapLibre takes a named anchor and a pixel offset rather than a point,
+  so the marker is anchored at its centre and moved by `resolveMarkerOffset`. An
+  explicit `anchor` wins; a marker with no pin anchors on its centre. The pin must
+  be a direct child for its frame to be relative to the marker.
+- **A marker's `testID` is repeated on its content, suffixed `-content`.** The
+  native annotation the `testID` lands on is not always in the view hierarchy a
+  test runner walks; `map-places-museum-content` is the marker's own view, which
+  the runner can find and tap.
+- **A marker's press is its own.** It stops propagation, so a tap on a marker does
+  not also reach the map's `onPress`; a route's press does the same through its
+  source.
+- **The pin is drawn, not an icon.** A pin's tip is a point on the map; a glyph
+  centred in a square would mark a place a few points off. `mapPinPath` starts at
+  the tip, and the dot in its head is the fill's own `-foreground`, so the pair holds
+  contrast in every theme with one choice. Hidden from assistive technology — the
+  marker carries the name.
+- **A popup is a React view, not the platform callout.** The native callout takes no
+  theme; this is a `Surface` with a caret drawn in `card` and stroked in `border`.
+  Inside a marker it sits in the marker's column over the pin; outside one it needs a
+  `lngLat` — the props are a union, so a popup with nowhere to go is a type error —
+  and becomes a bottom-anchored marker of its own. It holds no open state: the caller
+  knows which place is selected and renders it or not.
+- **A label's side is a gap, not a position.** A marker is a column and React Native
+  has no `order`, so `side` picks which margin the label keeps from the pin and the
+  caller writes it before or after the pin to match. Card fill with a hairline so it
+  reads over any basemap; one line, truncated.
+- **Controls live on a layer above the map, not inside it.** The native map renders
+  only map features as children. `Map.Controls` renders nothing in place and
+  registers its buttons with the root (`setOverlay`), which draws them on an
+  `absolute inset-0` layer beside the map with `pointerEvents="box-none"`, so a pan
+  on empty space still reaches the map. Each group is a `Surface` of ghost
+  `Button`s at `icon-sm`, each labelled by what it does.
+- **The zoom buttons step from where the camera is going.** The zoom is read from
+  the last `onRegionDidChange`; a press writes its target back at once, so a second
+  press before the first lands steps on from it rather than repeating it.
+- **Location comes through the map, not a location library.** `showLocate` and
+  `Map.UserLocation` each request location updates, counted so they stop when the
+  last one lets go, and MapLibre's `LocationManager` asks for permission and
+  delivers the position. No `expo-location`. A locate press before the first fix
+  waits for it rather than flying nowhere, and flies in to at least zoom 14.
+- **The location dot is drawn, so it takes the theme.** Two circle layers — a
+  `background` ring and a `primary` dot — rather than MapLibre's own puck, whose
+  colours are fixed. `showsHeading` adds a cone in `primary` at 35%, turned to the
+  device heading in screen space, which matches the map's north while the map does
+  not rotate, the default. An unknown heading draws nothing rather than pointing
+  north.
+- **The basemap is painted from tokens.** `buildMapStyle` puts land on
+  `background`, water and green space on `muted`, roads, buildings and boundaries
+  on `border`, and labels on `muted-foreground` haloed in `background`. MapLibre
+  parses three- and six-digit hex but not eight, so `toStyleColor` writes an alpha
+  token as `rgba()`. A token that does not resolve drops the layers it paints
+  rather than leaving them in MapLibre's default black. A test pins every token it
+  reads to both theme variants. Light and dark follow Uniwind's theme, never the
+  system's, because the style is the theme.
+- **The tiles are OpenFreeMap's, and the attribution stays.** OpenMapTiles-schema
+  vector tiles of OpenStreetMap, free and keyless (`MAP_DEFAULT_BASEMAP`). The data
+  is ODbL, so MapLibre's attribution button is on, bottom left — the corner the
+  controls leave free by default. `buildMapStyle` takes another OpenMapTiles source
+  and glyph server; `mapStyle` takes any style at all.
+- **Routes and arcs are layers, `primary` unless told otherwise.** A GeoJSON source
+  and a line layer each, keyed by `useId`, so they sit over the basemap and under
+  every marker. `opacity` is the layer's own `line-opacity`. A dashed route's
+  dashes are `[2, 2]` — MapLibre measures dashes in line widths, so they stay
+  dashes at any weight. A route with `onPress` gets a 12-point hitbox; a 3-point
+  line is otherwise a hard target.
+- **An arc is a curve, not a great circle.** A quadratic Bézier in plain lng/lat,
+  bowed left of travel by `curvature × length` at its apex. At the scale a connection
+  is drawn the two read the same, and the bow is the caller's choice rather than the
+  globe's. Its endpoints are the inputs, not recomputed, so a marker on either end
+  sits exactly on the line. It does not take the short way across the antimeridian.
+- **Rotation and tilt travel together, and both are off by default.** A map that
+  turns but cannot be tilted flat again is one a reader gets lost in; a store finder
+  wants north up. `isInteractive={false}` turns every gesture off, rotation included.
+- **Camera moves honour reduced motion.** `resolveCameraDuration` jumps instead of
+  flying when the system asks for less motion.
+- **The map view is announced as "Map".** Markers carry their own
+  `accessibilityLabel` and become buttons when they have an `onPress`; controls are
+  labelled `Button`s.
+
+## Scoped out of v1
+
+- **GeoJSON fills, clustering, heatmaps.** `Map.Route` covers polylines. MapLibre
+  does all three as layers, so each is a later part rather than a different engine.
+- **Offline packs.** MapLibre's `OfflineManager` can download a region; nothing here
+  needs one yet.
+- **A hidden list of markers for screen readers.** Markers are reachable already.
+- **Expo Go.** MapLibre is a native module; the map needs a dev build.
+
+## Platform setup
+
+- **Both platforms** need the config plugin — `"@maplibre/maplibre-react-native"` in
+  the app config's `plugins` — and a rebuilt dev client. No API key.
+- **iOS** needs `NSLocationWhenInUseUsageDescription` in the app config for a screen
+  using `showLocate` or `Map.UserLocation`.
+- **Android** gets its location permissions from MapLibre's own manifest.

package/src/components/map/index.ts

@@ -0,0 +1,68 @@
+export { Map, type MapProps } from "./map";
+export {
+	type MapContextValue,
+	type MapUserLocationValue,
+	useMap,
+	useMapContext,
+	useMapUserLocation,
+} from "./map.context";
+export type {
+	LngLat,
+	LngLatBounds,
+	MapFitBoundsOptions,
+	MapFlyToOptions,
+	MapHandle,
+	ViewState,
+} from "./map.types";
+export {
+	buildMapStyle,
+	MAP_ACCESSIBILITY_LABEL,
+	MAP_CAMERA_DURATION,
+	MAP_CONTROLS_CORNERS,
+	MAP_DEFAULT_BASEMAP,
+	MAP_DEFAULT_ZOOM,
+	MAP_LABEL_SIDES,
+	MAP_LABEL_SIZES,
+	MAP_LABEL_TONES,
+	MAP_MARKER_ANCHORS,
+	MAP_PIN_DIMENSIONS,
+	MAP_PIN_SIZES,
+	MAP_PIN_TONE_TOKENS,
+	MAP_PIN_TONES,
+	MAP_ROUTE_TOKEN,
+	MAP_STYLE_TOKENS,
+	MAP_ZOOM_STEP,
+	type MapAnchorPoint,
+	type MapBasemap,
+	type MapControlsCorner,
+	type MapLabelSide,
+	type MapLabelSize,
+	type MapLabelTone,
+	type MapMarkerAnchor,
+	type MapPinSize,
+	type MapPinTone,
+	type MapStyleTokens,
+	type MapVariantProps,
+	mapPinPath,
+	mapVariants,
+	resolveMarkerAnchor,
+	resolveMarkerOffset,
+	resolvePinTipAnchor,
+	toStyleColor,
+} from "./map.variants";
+export type { MapArcProps } from "./map-arc";
+export type { MapControlsProps } from "./map-controls";
+export {
+	arcCoordinates,
+	boundsOf,
+	fitBoundsCamera,
+	MAP_FIT_MAX_ZOOM,
+	MAP_TILE_SIZE,
+	normalizeLongitude,
+} from "./map-geometry";
+export type { MapLabelProps } from "./map-label";
+export type { MapMarkerProps } from "./map-marker";
+export type { MapPinProps } from "./map-pin";
+export type { MapPopupProps } from "./map-popup";
+export type { MapRouteProps } from "./map-route";
+export type { MapUserLocationProps } from "./map-user-location";

package/src/components/map/map-arc.tsx

@@ -0,0 +1,79 @@
+import { GeoJSONSource, Layer } from "@maplibre/maplibre-react-native";
+import { type ReactElement, useId, useMemo } from "react";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { useMapPart } from "./map.context";
+import type { LngLat } from "./map.types";
+import { MAP_ROUTE_TOKEN, toStyleColor } from "./map.variants";
+import { arcCoordinates } from "./map-geometry";
+
+export type MapArcProps = {
+	from: LngLat;
+	to: LngLat;
+	/**
+	 * How far it bows off the straight line, as a fraction of the line's
+	 * length; negative bows the other way. Defaults to `0.2`.
+	 */
+	curvature?: number;
+	/** A theme token or a literal colour. Defaults to `primary`. */
+	color?: string;
+	/** Stroke width in points. Defaults to `2`. */
+	width?: number;
+	/** `0`–`1`. Defaults to `0.9`. */
+	opacity?: number;
+};
+
+/** Points sampled along the curve — smooth at any zoom a connection is read at. */
+const ARC_SAMPLES = 64;
+
+/**
+ * A curve from one point to another — a flight, a transfer, a connection
+ * rather than a path someone travelled.
+ *
+ * A quadratic curve sampled into a line, not a great circle: at the scale a
+ * connection is drawn the two are indistinguishable, and the curve's bow is a
+ * choice the caller makes rather than one the globe makes for them. The line
+ * starts and ends exactly on `from` and `to`, so markers there sit on it.
+ */
+export function MapArc({
+	from,
+	to,
+	curvature = 0.2,
+	color = MAP_ROUTE_TOKEN,
+	width = 2,
+	opacity = 0.9,
+}: MapArcProps): ReactElement {
+	useMapPart("Map.Arc");
+	const stroke = toStyleColor(useThemeColor(color));
+	const id = `delacour-arc-${useId()}`;
+	const [fromLng, fromLat] = from;
+	const [toLng, toLat] = to;
+	const data = useMemo<GeoJSON.Feature<GeoJSON.LineString>>(
+		() => ({
+			geometry: {
+				coordinates: arcCoordinates([fromLng, fromLat], [toLng, toLat], curvature, ARC_SAMPLES).map(
+					([longitude, latitude]) => [longitude, latitude]
+				),
+				type: "LineString",
+			},
+			properties: {},
+			type: "Feature",
+		}),
+		[fromLng, fromLat, toLng, toLat, curvature]
+	);
+
+	return (
+		<GeoJSONSource data={data} id={id}>
+			<Layer
+				id={`${id}-line`}
+				layout={{ "line-cap": "round" }}
+				paint={{
+					...(stroke === undefined ? {} : { "line-color": stroke }),
+					"line-opacity": Math.min(1, Math.max(0, opacity)),
+					"line-width": width,
+				}}
+				type="line"
+			/>
+		</GeoJSONSource>
+	);
+}
+MapArc.displayName = "DelacourUI.Map.Arc";

package/src/components/map/map-controls.tsx

@@ -0,0 +1,133 @@
+import { type ReactElement, useEffect, useId } from "react";
+import { View, type ViewProps } from "react-native";
+import { IconCompassRound, IconLocation, IconMinusSmall, IconPlusSmall, IconTarget } from "../../icons/central";
+import { Button } from "../button";
+import { Icon } from "../icon";
+import { Surface } from "../surface";
+import { useMapPart } from "./map.context";
+import type { LngLat } from "./map.types";
+import { MAP_ZOOM_STEP, type MapControlsCorner, mapVariants } from "./map.variants";
+
+export type MapControlsProps = Omit<ViewProps, "children"> & {
+	/** Defaults to `bottom-right`, under the thumb. */
+	corner?: MapControlsCorner;
+	/** Zoom in and out. Defaults to `true`. */
+	showZoom?: boolean;
+	/** Fly to the device's location — turns the location dot on and asks for permission. */
+	showLocate?: boolean;
+	/** Turn the map back to north-up. Useful only on a map that rotates. */
+	showCompass?: boolean;
+	/** Return to the view the map opened on. */
+	showRecenter?: boolean;
+	/** Called with the device's position once a locate press has flown there. */
+	onLocate?: (lngLat: LngLat) => void;
+	className?: string;
+};
+
+/**
+ * Zoom, locate, compass and recenter buttons, floated in a corner of the map.
+ *
+ * Each group is a card-coloured `Surface` holding ghost `Button`s, so the
+ * controls read over any basemap and take the theme like every other button.
+ * Each is labelled for a screen reader by what it does.
+ *
+ * Drawn on the layer above the map rather than inside it — the native map
+ * takes only map features as children — and that layer passes touches on its
+ * empty space through, so only the buttons themselves intercept a pan.
+ *
+ * `showLocate` turns on the platform's location dot, which asks for foreground
+ * location permission the first time; the app's config has to declare why.
+ */
+export function MapControls({
+	corner = "bottom-right",
+	showZoom = true,
+	showLocate = false,
+	showCompass = false,
+	showRecenter = false,
+	onLocate,
+	className,
+	...props
+}: MapControlsProps): null {
+	const map = useMapPart("Map.Controls");
+	const id = useId();
+	const { requestUserLocation, setOverlay } = map;
+
+	useEffect(() => (showLocate ? requestUserLocation() : undefined), [showLocate, requestUserLocation]);
+
+	const slots = mapVariants({ corner });
+
+	const node: ReactElement = (
+		<View className={slots.controls({ className })} pointerEvents="box-none" {...props}>
+			{showZoom ? (
+				<Surface padding="none" variant="default">
+					<Button
+						accessibilityLabel="Zoom in"
+						onPress={() => map.zoomBy(MAP_ZOOM_STEP)}
+						size="icon-sm"
+						testID="map-controls-zoom-in"
+						variant="ghost"
+					>
+						<Icon icon={IconPlusSmall} />
+					</Button>
+					<Button
+						accessibilityLabel="Zoom out"
+						onPress={() => map.zoomBy(-MAP_ZOOM_STEP)}
+						size="icon-sm"
+						testID="map-controls-zoom-out"
+						variant="ghost"
+					>
+						<Icon icon={IconMinusSmall} />
+					</Button>
+				</Surface>
+			) : null}
+			{showCompass ? (
+				<Surface padding="none" variant="default">
+					<Button
+						accessibilityLabel="Point north"
+						onPress={() => map.resetBearing()}
+						size="icon-sm"
+						testID="map-controls-compass"
+						variant="ghost"
+					>
+						<Icon icon={IconCompassRound} />
+					</Button>
+				</Surface>
+			) : null}
+			{showRecenter ? (
+				<Surface padding="none" variant="default">
+					<Button
+						accessibilityLabel="Recenter map"
+						onPress={() => map.handle.recenter()}
+						size="icon-sm"
+						testID="map-controls-recenter"
+						variant="ghost"
+					>
+						<Icon icon={IconTarget} />
+					</Button>
+				</Surface>
+			) : null}
+			{showLocate ? (
+				<Surface padding="none" variant="default">
+					<Button
+						accessibilityLabel="Show my location"
+						onPress={() => map.locate(onLocate)}
+						size="icon-sm"
+						testID="map-controls-locate"
+						variant="ghost"
+					>
+						<Icon icon={IconLocation} />
+					</Button>
+				</Surface>
+			) : null}
+		</View>
+	);
+
+	useEffect(() => {
+		setOverlay(id, node);
+	}, [id, node, setOverlay]);
+
+	useEffect(() => () => setOverlay(id, null), [id, setOverlay]);
+
+	return null;
+}
+MapControls.displayName = "DelacourUI.Map.Controls";

package/src/components/map/map-geometry.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import type { LngLat } from "./map.types";
+import { arcCoordinates, boundsOf, fitBoundsCamera, MAP_FIT_MAX_ZOOM, normalizeLongitude } from "./map-geometry";
+
+const WELLINGTON: LngLat = [174.776, -41.286];
+const AUCKLAND: LngLat = [174.763, -36.848];
+
+function close(actual: number, expected: number, digits = 9): void {
+	expect(actual).toBeCloseTo(expected, digits);
+}
+
+describe("normalizeLongitude", () => {
+	test("leaves a longitude inside the range alone", () => {
+		expect(normalizeLongitude(174.776)).toBe(174.776);
+		expect(normalizeLongitude(-120)).toBe(-120);
+	});
+
+	test("wraps past the antimeridian, both ways", () => {
+		close(normalizeLongitude(190), -170);
+		close(normalizeLongitude(-190), 170);
+		close(normalizeLongitude(540), -180);
+	});
+});
+
+describe("fitBoundsCamera", () => {
+	const SQUARE = { width: 512, height: 512 };
+
+	test("the whole world in one tile's width is zoom 0", () => {
+		const { center, zoom } = fitBoundsCamera([-180, -85.0511287798, 180, 85.0511287798], SQUARE);
+		close(zoom, 0, 6);
+		close(center[0], 0, 6);
+		close(center[1], 0, 6);
+	});
+
+	test("half the world's longitude in the same width is one step in", () => {
+		const { zoom } = fitBoundsCamera([0, -1, 180, 1], SQUARE);
+		close(zoom, 1, 6);
+	});
+
+	test("the tighter axis decides: a wide box is held by the width, a tall one by the height", () => {
+		const square = { width: 256, height: 256 };
+		const wideBox = [0, -1, 4, 1] as const;
+		const tallBox = [0, -2, 1, 2] as const;
+		close(fitBoundsCamera(wideBox, { width: 256, height: 1024 }).zoom, fitBoundsCamera(wideBox, square).zoom, 6);
+		close(fitBoundsCamera(tallBox, { width: 1024, height: 256 }).zoom, fitBoundsCamera(tallBox, square).zoom, 6);
+		expect(fitBoundsCamera(wideBox, { width: 1024, height: 256 }).zoom).toBeGreaterThan(
+			fitBoundsCamera(wideBox, square).zoom
+		);
+	});
+
+	test("centres on the box in Web Mercator, which sits poleward of the mean latitude", () => {
+		const { center } = fitBoundsCamera([0, 40, 10, 70], SQUARE);
+		close(center[0], 5);
+		expect(center[1]).toBeGreaterThan(55);
+	});
+
+	test("padding zooms out so the box clears it", () => {
+		const bare = fitBoundsCamera([174, -42, 176, -40], SQUARE);
+		const padded = fitBoundsCamera([174, -42, 176, -40], SQUARE, 128);
+		close(padded.zoom, bare.zoom - 1, 6);
+	});
+
+	test("padding that would leave no room is ignored", () => {
+		const bare = fitBoundsCamera([174, -42, 176, -40], SQUARE);
+		expect(fitBoundsCamera([174, -42, 176, -40], SQUARE, 300)).toEqual(bare);
+	});
+
+	test("a box across the antimeridian is framed across it, not round the world", () => {
+		const across = fitBoundsCamera([170, -20, -170, -10], SQUARE);
+		const plain = fitBoundsCamera([-10, -20, 10, -10], SQUARE);
+		close(Math.abs(across.center[0]), 180);
+		close(across.zoom, plain.zoom, 6);
+	});
+
+	test("a box of no size is a close view, not an infinite zoom", () => {
+		expect(fitBoundsCamera([174.776, -41.286, 174.776, -41.286], SQUARE)).toEqual({
+			center: WELLINGTON,
+			zoom: MAP_FIT_MAX_ZOOM,
+		});
+	});
+
+	test("an unmeasured view is never a negative or non-finite zoom", () => {
+		const { zoom } = fitBoundsCamera([0, 0, 10, 10], { width: 0, height: 0 });
+		expect(Number.isFinite(zoom)).toBe(true);
+		expect(zoom).toBeGreaterThanOrEqual(0);
+	});
+});
+
+describe("boundsOf", () => {
+	test("nothing has no bounds", () => {
+		expect(boundsOf([])).toBeUndefined();
+	});
+
+	test("one point is a box of no size", () => {
+		expect(boundsOf([WELLINGTON])).toEqual([174.776, -41.286, 174.776, -41.286]);
+	});
+
+	test("the extent of a route", () => {
+		expect(boundsOf([WELLINGTON, AUCKLAND, [172.636, -43.532]])).toEqual([172.636, -43.532, 174.776, -36.848]);
+	});
+
+	test("points either side of the antimeridian take the short way round", () => {
+		const bounds = boundsOf([
+			[178, -18],
+			[-179, -17],
+			[179.5, -16],
+		]);
+		expect(bounds).toEqual([178, -18, -179, -16]);
+	});
+
+	test("points spread round the world without a gap take the Greenwich box", () => {
+		expect(
+			boundsOf([
+				[-150, 0],
+				[-30, 10],
+				[90, 20],
+			])
+		).toEqual([-150, 0, 90, 20]);
+	});
+});
+
+describe("arcCoordinates", () => {
+	test("starts and ends exactly on its endpoints", () => {
+		const points = arcCoordinates(AUCKLAND, WELLINGTON, 0.2, 32);
+		expect(points[0]).toEqual(AUCKLAND);
+		expect(points.at(-1)).toEqual(WELLINGTON);
+	});
+
+	test("samples the requested number of points, endpoints included", () => {
+		expect(arcCoordinates(AUCKLAND, WELLINGTON, 0.2, 32)).toHaveLength(32);
+		expect(arcCoordinates(AUCKLAND, WELLINGTON, 0.2, 1)).toHaveLength(2);
+	});
+
+	test("no curvature is the straight line", () => {
+		const points = arcCoordinates([0, 0], [10, 0], 0, 11);
+		points.forEach(([lng, lat], index) => {
+			close(lng, index);
+			close(lat, 0);
+		});
+	});
+
+	test("bows off the chord by the curvature times its length, at the midpoint", () => {
+		const points = arcCoordinates([0, 0], [10, 0], 0.2, 3);
+		const [lng, lat] = points[1] as LngLat;
+		close(lng, 5);
+		close(lat, 2);
+	});
+
+	test("a negative curvature bows the other way", () => {
+		const [, up] = arcCoordinates([0, 0], [10, 0], 0.2, 3)[1] as LngLat;
+		const [, down] = arcCoordinates([0, 0], [10, 0], -0.2, 3)[1] as LngLat;
+		expect(up).toBeGreaterThan(0);
+		close(down, -up);
+	});
+
+	test("a zero-length arc is its one point, twice", () => {
+		expect(arcCoordinates(WELLINGTON, WELLINGTON, 0.2, 8)).toEqual([WELLINGTON, WELLINGTON]);
+	});
+});