@12-apps/routing 0.0.0-stage → 1.0.0

package/src/providers/google.ts

@@ -0,0 +1,85 @@
+/**
+ * Google Routes API (`directions/v2:computeRoutes`).
+ *
+ * **Licence note for hosts:** Google's Maps Platform terms do not allow
+ * content from its services (this route line included) to be displayed on a
+ * non-Google map. A host that draws with `RouteMap` over an OpenStreetMap
+ * basemap must not list this provider; it exists for hosts that render on a
+ * Google basemap, or that use only the durations.
+ */
+
+import { decodePolyline } from "../core/geo";
+import type { ProviderOutcome, RoutingProvider } from "../core/provider";
+import type { LngLat, RouteLeg, RouteRequest } from "../core/types";
+
+import { fetchJson, legsOf, numberOr, routeOutcome, trimBase } from "./http";
+
+export interface GoogleRoutesOptions {
+  apiKey: string | undefined;
+  /** `TWO_WHEELER` (default) or `DRIVE`. */
+  travelMode?: "TWO_WHEELER" | "DRIVE";
+  /** Ask for a traffic-aware duration (billed at the Pro tier). */
+  trafficAware?: boolean;
+  baseUrl?: string;
+}
+
+const DEFAULT_BASE_URL = "https://routes.googleapis.com";
+
+interface GoogleLeg {
+  distanceMeters?: unknown;
+  duration?: unknown;
+}
+
+interface GoogleBody {
+  routes?: { polyline?: { encodedPolyline?: unknown }; legs?: GoogleLeg[] }[];
+}
+
+const waypoint = (point: LngLat) => ({ location: { latLng: { latitude: point.lat, longitude: point.lng } } });
+
+function requestBody(request: RouteRequest, options: GoogleRoutesOptions): string {
+  const last = request.returnTo ?? request.stops[request.stops.length - 1]!;
+  const middle = request.returnTo ? request.stops : request.stops.slice(0, -1);
+  return JSON.stringify({
+    origin: waypoint(request.origin),
+    destination: waypoint(last),
+    intermediates: middle.map(waypoint),
+    travelMode: options.travelMode ?? "TWO_WHEELER",
+    ...(options.trafficAware ? { routingPreference: "TRAFFIC_AWARE" } : {}),
+  });
+}
+
+export function googleRoutesProvider(options: GoogleRoutesOptions): RoutingProvider {
+  const base = trimBase(options.baseUrl ?? DEFAULT_BASE_URL);
+  return {
+    name: "google-routes",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.apiKey) return { ok: false, kind: "unconfigured" };
+      const answer = await fetchJson({
+        fetch,
+        signal,
+        url: `${base}/directions/v2:computeRoutes`,
+        init: {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-goog-api-key": options.apiKey,
+            "x-goog-fieldmask": "routes.polyline.encodedPolyline,routes.legs.distanceMeters,routes.legs.duration",
+          },
+          body: requestBody(request, options),
+        },
+      });
+      if (!answer.ok) return answer;
+      const route = (answer.body as GoogleBody).routes?.[0];
+      if (!route) return { ok: false, kind: "no-route" };
+      const encoded = route.polyline?.encodedPolyline;
+      return routeOutcome(typeof encoded === "string" ? decodePolyline(encoded) : null, legsOf(route.legs, legOf));
+    },
+  };
+}
+
+/** `duration` is a protobuf Duration string, `"123s"` or `"12.5s"`. */
+function legOf(leg: GoogleLeg): RouteLeg | null {
+  const distanceM = numberOr(leg.distanceMeters, 0);
+  const match = typeof leg.duration === "string" ? /^(\d+(?:\.\d+)?)s$/.exec(leg.duration) : null;
+  return distanceM === null || !match ? null : { distanceM, durationS: Number(match[1]) };
+}

package/src/providers/http.ts

@@ -0,0 +1,90 @@
+/**
+ * The one HTTP step every adapter shares: call, classify the failure, parse
+ * JSON. An adapter only knows its URL, its body and how to read its answer.
+ */
+
+import { failureOfResponse, failureOfThrown, type ProviderOutcome } from "../core/provider";
+import type { Position, RouteLeg } from "../core/types";
+
+type Failure = Extract<ProviderOutcome, { ok: false }>;
+
+interface JsonCall {
+  fetch: typeof fetch;
+  signal: AbortSignal;
+  url: string;
+  init?: RequestInit;
+  /**
+   * Whether a non-2xx answer means "there is no route between these points"
+   * rather than a failed request — read from the status AND the error body,
+   * because services reuse a generic status for it (OSRM answers 400).
+   */
+  isNoRoute?: (status: number, body: unknown) => boolean;
+}
+
+export async function fetchJson(call: JsonCall): Promise<{ ok: true; body: unknown } | Failure> {
+  let response: Response;
+  try {
+    response = await call.fetch(call.url, { ...call.init, signal: call.signal });
+  } catch (error) {
+    return failureOfThrown(error, call.signal) as Failure;
+  }
+  if (!response.ok && call.isNoRoute) {
+    const text = await response.text().catch(() => "");
+    if (call.isNoRoute(response.status, parseJson(text))) return { ok: false, kind: "no-route", status: response.status };
+    return { ok: false, kind: "http", status: response.status, detail: text.slice(0, 200) };
+  }
+  const failed = await failureOfResponse(response);
+  if (failed) return failed as Failure;
+  try {
+    return { ok: true, body: (await response.json()) as unknown };
+  } catch (error) {
+    // An abort while the body streams is the planner's timeout, not a bad body.
+    return call.signal.aborted ? (failureOfThrown(error, call.signal) as Failure) : { ok: false, kind: "body" };
+  }
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+/** `[lng, lat][]` from an untrusted value, or `null`. */
+export function positionsOf(value: unknown): Position[] | null {
+  if (!Array.isArray(value)) return null;
+  const out: Position[] = [];
+  for (const item of value) {
+    if (!Array.isArray(item) || typeof item[0] !== "number" || typeof item[1] !== "number") return null;
+    out.push([item[0], item[1]]);
+  }
+  return out;
+}
+
+/** Every leg read, or `null` when any one is unreadable. */
+export function legsOf<T>(items: readonly T[] | undefined, read: (item: T) => RouteLeg | null): RouteLeg[] | null {
+  if (!items) return null;
+  const legs = items.map(read);
+  return legs.every((leg): leg is RouteLeg => leg !== null) ? legs : null;
+}
+
+/** The success outcome, or an unreadable-body failure when either part is missing. */
+export function routeOutcome(geometry: Position[] | null, legs: RouteLeg[] | null): ProviderOutcome {
+  return geometry && legs ? { ok: true, geometry, legs } : { ok: false, kind: "body" };
+}
+
+/** A number, with a missing value read as `fallback` (services omit zero-length legs). */
+export const numberOr = (value: unknown, fallback: number): number | null =>
+  value === undefined ? fallback : typeof value === "number" ? value : null;
+
+/**
+ * A base URL without its trailing slashes. A loop rather than `/\/+$/`: that
+ * pattern backtracks polynomially on a long run of slashes, and a base URL is
+ * host config this package does not control.
+ */
+export function trimBase(url: string): string {
+  let end = url.length;
+  while (end > 0 && url[end - 1] === "/") end -= 1;
+  return url.slice(0, end);
+}

package/src/providers/openrouteservice.ts

@@ -0,0 +1,71 @@
+/**
+ * openrouteservice (OpenStreetMap data, the same map the default basemap
+ * draws). `POST /v2/directions/{profile}/geojson` with every waypoint in one
+ * call; the answer's single feature carries the line and one segment per leg.
+ */
+
+import { toPosition } from "../core/geo";
+import { waypointsOf, type ProviderOutcome, type RoutingProvider } from "../core/provider";
+import type { RouteLeg } from "../core/types";
+
+import { fetchJson, legsOf, numberOr, positionsOf, routeOutcome, trimBase } from "./http";
+
+export interface OpenRouteServiceOptions {
+  /** The account's API key. Empty/absent = every attempt is `unconfigured`. */
+  apiKey: string | undefined;
+  /** ORS profile. `driving-car` is the closest public profile to a motorbike. */
+  profile?: string;
+  /** Override for a self-hosted instance. */
+  baseUrl?: string;
+}
+
+const DEFAULT_BASE_URL = "https://api.openrouteservice.org";
+
+interface OrsSegment {
+  distance?: unknown;
+  duration?: unknown;
+}
+
+interface OrsBody {
+  features?: { geometry?: { coordinates?: unknown }; properties?: { segments?: OrsSegment[] } }[];
+}
+
+export function openRouteServiceProvider(options: OpenRouteServiceOptions): RoutingProvider {
+  const base = trimBase(options.baseUrl ?? DEFAULT_BASE_URL);
+  const profile = options.profile ?? "driving-car";
+  return {
+    name: "openrouteservice",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.apiKey) return { ok: false, kind: "unconfigured" };
+      const answer = await fetchJson({
+        fetch,
+        signal,
+        url: `${base}/v2/directions/${encodeURIComponent(profile)}/geojson`,
+        isNoRoute: orsNoRoute,
+        init: {
+          method: "POST",
+          headers: { authorization: options.apiKey, "content-type": "application/json", accept: "application/geo+json" },
+          body: JSON.stringify({ coordinates: waypointsOf(request).map(toPosition) }),
+        },
+      });
+      if (!answer.ok) return answer;
+      const feature = (answer.body as OrsBody).features?.[0];
+      return routeOutcome(positionsOf(feature?.geometry?.coordinates), legsOf(feature?.properties?.segments, legOf));
+    },
+  };
+}
+
+/**
+ * ORS answers "no route" (2009) and "no routable point near a waypoint" (2010)
+ * with 404 — the same status as a wrong profile or URL, so the body decides.
+ */
+function orsNoRoute(status: number, body: unknown): boolean {
+  const code = (body as { error?: { code?: unknown } } | null)?.error?.code;
+  return status === 404 && (code === 2009 || code === 2010);
+}
+
+function legOf(segment: OrsSegment): RouteLeg | null {
+  const distanceM = numberOr(segment.distance, 0);
+  const durationS = numberOr(segment.duration, 0);
+  return distanceM === null || durationS === null ? null : { distanceM, durationS };
+}

package/src/providers/osrm.ts

@@ -0,0 +1,58 @@
+/**
+ * OSRM (`/route/v1/{profile}/{coords}`), self-hosted or a public instance.
+ * The public demo server is for testing only — a host that lists it in
+ * production should expect to land on the fallback when it rate-limits.
+ */
+
+import { waypointsOf, type ProviderOutcome, type RoutingProvider } from "../core/provider";
+import type { RouteLeg } from "../core/types";
+
+import { fetchJson, legsOf, positionsOf, routeOutcome, trimBase } from "./http";
+
+export interface OsrmOptions {
+  /** e.g. `https://osrm.example.net`. Empty/absent = `unconfigured`. */
+  baseUrl: string | undefined;
+  /** OSRM profile segment, `driving` by default. */
+  profile?: string;
+}
+
+interface OsrmLeg {
+  distance?: unknown;
+  duration?: unknown;
+}
+
+interface OsrmBody {
+  code?: unknown;
+  routes?: { geometry?: { coordinates?: unknown }; legs?: OsrmLeg[] }[];
+}
+
+export function osrmProvider(options: OsrmOptions): RoutingProvider {
+  return {
+    name: "osrm",
+    async route(request, { fetch, signal }): Promise<ProviderOutcome> {
+      if (!options.baseUrl) return { ok: false, kind: "unconfigured" };
+      const coords = waypointsOf(request)
+        .map((point) => `${point.lng},${point.lat}`)
+        .join(";");
+      const profile = encodeURIComponent(options.profile ?? "driving");
+      const url = `${trimBase(options.baseUrl)}/route/v1/${profile}/${coords}?overview=full&geometries=geojson&steps=false`;
+      const answer = await fetchJson({ fetch, signal, url, init: { headers: { accept: "application/json" } }, isNoRoute: osrmNoRoute });
+      if (!answer.ok) return answer;
+      const body = answer.body as OsrmBody;
+      if (body.code === "NoRoute") return { ok: false, kind: "no-route" };
+      if (body.code !== "Ok") return { ok: false, kind: "body" };
+      const route = body.routes?.[0];
+      return routeOutcome(positionsOf(route?.geometry?.coordinates), legsOf(route?.legs, legOf));
+    },
+  };
+}
+
+/** OSRM answers an impossible route with HTTP 400 and a `code` in the body. */
+function osrmNoRoute(status: number, body: unknown): boolean {
+  const code = (body as { code?: unknown } | null)?.code;
+  return status === 400 && (code === "NoRoute" || code === "NoSegment");
+}
+
+function legOf(leg: OsrmLeg): RouteLeg | null {
+  return typeof leg.distance === "number" && typeof leg.duration === "number" ? { distanceM: leg.distance, durationS: leg.duration } : null;
+}

package/src/react/copy.ts

@@ -0,0 +1,24 @@
+/**
+ * Every word the map draws. Required host config — there are no defaults in
+ * the component; the named packs (`./pt-BR`, `./en-US`, `./locales`) are what a
+ * host passes when it has no reason to say anything else.
+ */
+
+export interface RouteMapCopy {
+  /** Zoom-in control's accessible name. */
+  zoomIn: string;
+  /** Zoom-out control's accessible name. */
+  zoomOut: string;
+  /** Fit-everything control's accessible name. */
+  fitAll: string;
+  /** The map area's own accessible name. */
+  mapLabel: string;
+  /** Shown in place of the map when it cannot render (no WebGL, style failed). */
+  mapError: string;
+  /** The retry button under `mapError`. */
+  retry: string;
+  /** A group of overlapping markers, by how many it holds. */
+  group: (count: number) => string;
+  /** The basemap's required attribution line. */
+  attribution: string;
+}

package/src/react/en-US.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+
+export const EN_US_ROUTE_MAP_COPY: RouteMapCopy = {
+  zoomIn: "Zoom in",
+  zoomOut: "Zoom out",
+  fitAll: "Show all",
+  mapLabel: "Map",
+  mapError: "The map could not be loaded.",
+  retry: "Try again",
+  group: (count) => `${count} here — tap to choose`,
+  attribution: "© OpenFreeMap © OpenMapTiles © OpenStreetMap contributors",
+};

package/src/react/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@12-apps/routing/react` — the web host's surface:
+ * `createWebRouting(config) → { RouteMap }`. Build once per config (the wiring
+ * binder does); `RouteMap` is a component TYPE the host places wherever a
+ * route belongs.
+ */
+
+import { buildRouteMap } from "./route-map";
+import type { RouteMapConfig, RouteMapProps } from "./types";
+import type { JSX } from "react";
+
+export interface RoutingSurface {
+  RouteMap: (props: RouteMapProps) => JSX.Element;
+}
+
+export function createWebRouting(config: RouteMapConfig): RoutingSurface {
+  if (!config?.copy || !config.theme) throw new TypeError("createWebRouting: `copy` and `theme` are required");
+  return { RouteMap: buildRouteMap(config) };
+}
+
+export { DEFAULT_STYLE_URL } from "./route-map";
+export { boundsOf, groupMarkers } from "./map-geometry";
+export type { RouteMapConfig, RouteMapMarker, RouteMapPlace, RouteMapProps, RouteMapStop, RouteMapTheme } from "./types";
+export type { RouteMapCopy } from "./copy";
+export type { MapLibreLike, MapLike, MarkerLike } from "./maplibre-types";
+export { PT_BR_ROUTE_MAP_COPY } from "./pt-BR";
+export { EN_US_ROUTE_MAP_COPY } from "./en-US";
+export { ROUTE_MAP_COPY } from "./locales";

package/src/react/locales.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+import { EN_US_ROUTE_MAP_COPY } from "./en-US";
+import { PT_BR_ROUTE_MAP_COPY } from "./pt-BR";
+
+/** Mirrored rather than imported, so the package stays liftable into any repo. */
+type LocalePack<T> = { readonly "pt-BR": T; readonly "en-US": T };
+
+/** Both languages, keyed by tag — what a host hands its i18n resolver. */
+export const ROUTE_MAP_COPY = {
+  "pt-BR": PT_BR_ROUTE_MAP_COPY,
+  "en-US": EN_US_ROUTE_MAP_COPY,
+} as const satisfies LocalePack<RouteMapCopy>;

package/src/react/map-css.ts

@@ -0,0 +1,20 @@
+/**
+ * The few rules MapLibre's own stylesheet supplies that the map cannot work
+ * without (canvas and marker positioning). Injected once at mount rather than
+ * imported, so the package keeps `sideEffects: false` and a host needs no CSS
+ * loader for it.
+ */
+
+export const MAP_CSS_ID = "routing-map-css";
+
+export const MAP_CSS = [
+  ".maplibregl-map{position:relative;overflow:hidden;-webkit-tap-highlight-color:transparent}",
+  ".maplibregl-canvas{position:absolute;left:0;top:0}",
+  ".maplibregl-canvas-container.maplibregl-interactive{cursor:grab}",
+  ".maplibregl-marker{position:absolute;top:0;left:0;will-change:transform}",
+  // Phone-width maps keep only the fit control: pinch already zooms, and a
+  // 140 px column of buttons would sit on top of the markers.
+  ".routing-map{container-type:inline-size;container-name:routing-map}",
+  "@container routing-map (max-width: 599px){.routing-zoom{display:none!important}}",
+  ".maplibregl-ctrl-bottom-left,.maplibregl-ctrl-bottom-right,.maplibregl-ctrl-top-left,.maplibregl-ctrl-top-right{position:absolute;pointer-events:none;z-index:2}",
+].join("");

package/src/react/map-elements.ts

@@ -0,0 +1,142 @@
+/**
+ * The DOM each MapLibre marker carries. MapLibre positions plain elements, so
+ * these are built directly — real `<button>`s with accessible names where the
+ * viewer can act, an `img` role with a title where they only read.
+ */
+
+import type { RouteMapCopy } from "./copy";
+import type { RouteMapMarker, RouteMapPlace, RouteMapStop, RouteMapTheme } from "./types";
+
+const SHADOW = "0 2px 6px rgba(0,0,0,.25)";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+/** Stroke glyphs, drawn in the element's own colour (no remote asset). */
+const GLYPHS = {
+  motorbike: ["M5.5 21a3.5 3.5 0 1 0 0-7 3.5 3.5 0 0 0 0 7z", "M18.5 21a3.5 3.5 0 1 0 0-7 3.5 3.5 0 0 0 0 7z", "M15 6h3l3 6", "M5.5 17.5L9 10h6l3.5 7.5"],
+  store: ["M3 9l1-5h16l1 5", "M4 9v11h16V9", "M9 20v-6h6v6"],
+} as const;
+
+function glyph(name: keyof typeof GLYPHS): SVGElement {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  for (const [key, value] of Object.entries({ width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round", "aria-hidden": "true" })) {
+    svg.setAttribute(key, value);
+  }
+  for (const d of GLYPHS[name]) {
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", d);
+    svg.appendChild(path);
+  }
+  return svg;
+}
+
+function button(ariaLabel: string, style: Partial<CSSStyleDeclaration>, onClick?: () => void): HTMLButtonElement {
+  const element = document.createElement("button");
+  element.type = "button";
+  element.setAttribute("aria-label", ariaLabel);
+  Object.assign(element.style, { cursor: onClick ? "pointer" : "default", font: "inherit" }, style);
+  if (onClick) {
+    element.addEventListener("click", (event) => {
+      event.stopPropagation();
+      onClick();
+    });
+  }
+  return element;
+}
+
+function span(text: string, style: Partial<CSSStyleDeclaration>): HTMLSpanElement {
+  const element = document.createElement("span");
+  element.textContent = text;
+  Object.assign(element.style, style);
+  return element;
+}
+
+/**
+ * A marker the viewer can act on is a `<button>` with `aria-pressed` (it
+ * selects); one they can only read is an `img` with a label — never an empty
+ * tab stop that does nothing.
+ */
+export function markerElement(marker: RouteMapMarker, theme: RouteMapTheme, onSelect: (() => void) | null): HTMLElement {
+  const frame = { display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "flex-end", minWidth: "44px", minHeight: "44px", zIndex: marker.emphasized ? "3" : "2" };
+  let element: HTMLElement;
+  if (onSelect) {
+    element = button(marker.ariaLabel, { ...frame, background: "none", border: "0", padding: "0" }, onSelect);
+    element.setAttribute("aria-pressed", marker.emphasized ? "true" : "false");
+  } else {
+    element = span("", frame);
+    element.setAttribute("role", "img");
+    element.setAttribute("aria-label", marker.ariaLabel);
+  }
+  const bubble = span("", {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "6px",
+    padding: marker.emphasized ? "6px 12px" : "5px 9px",
+    borderRadius: "999px",
+    fontSize: "13px",
+    fontWeight: "700",
+    whiteSpace: "nowrap",
+    color: theme.paper,
+    background: marker.color,
+    border: `2px ${marker.faded ? "dashed" : "solid"} ${theme.paper}`,
+    boxShadow: SHADOW,
+    opacity: marker.faded ? "0.75" : "1",
+  });
+  if (marker.icon) bubble.appendChild(glyph(marker.icon));
+  bubble.appendChild(document.createTextNode(marker.text));
+  const tail = span("", { width: "0", height: "0", borderLeft: "7px solid transparent", borderRight: "7px solid transparent", borderTop: `9px solid ${marker.color}` });
+  element.append(bubble, tail);
+  return element;
+}
+
+/**
+ * A group of overlapping markers keeps the MARKER's shape (a pill with a
+ * tail), so it never reads as a numbered stop badge drawn nearby.
+ */
+export function groupElement(count: number, copy: RouteMapCopy, theme: RouteMapTheme, onClick: () => void): HTMLElement {
+  const frame = { display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "flex-end" };
+  const element = button(copy.group(count), { ...frame, background: "none", border: "0", padding: "0", minWidth: "44px", minHeight: "44px" }, onClick);
+  const bubble = span(`+${count}`, {
+    padding: "5px 10px",
+    borderRadius: "999px",
+    fontSize: "13px",
+    fontWeight: "700",
+    color: theme.paper,
+    background: theme.ink,
+    border: `2px solid ${theme.paper}`,
+    boxShadow: SHADOW,
+  });
+  const tail = span("", { width: "0", height: "0", borderLeft: "7px solid transparent", borderRight: "7px solid transparent", borderTop: `9px solid ${theme.ink}` });
+  element.append(bubble, tail);
+  return element;
+}
+
+export function stopElement(stop: RouteMapStop, theme: RouteMapTheme): HTMLElement {
+  const fill = { done: theme.done, next: theme.next, pending: theme.pending }[stop.variant];
+  const element = span(stop.mark, {
+    width: "28px",
+    height: "28px",
+    boxSizing: "border-box",
+    borderRadius: "50%",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    fontSize: "13px",
+    fontWeight: "700",
+    background: fill,
+    color: stop.variant === "pending" ? theme.ink : theme.paper,
+    border: `2px solid ${stop.variant === "done" ? theme.paper : theme.ink}`,
+    boxShadow: SHADOW,
+  });
+  element.setAttribute("role", "img");
+  element.setAttribute("aria-label", stop.title);
+  element.title = stop.title;
+  return element;
+}
+
+export function placeElement(spot: RouteMapPlace, theme: RouteMapTheme): HTMLElement {
+  const element = span("", { display: "inline-flex", alignItems: "center", gap: "6px", background: theme.place, color: theme.paper, padding: "4px 10px", borderRadius: "10px", fontSize: "13px", fontWeight: "600", whiteSpace: "nowrap" });
+  if (spot.icon) element.appendChild(glyph(spot.icon));
+  element.appendChild(document.createTextNode(spot.label));
+  return element;
+}

package/src/react/map-geometry.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure helpers over what `RouteMap` draws: the box that holds it all, the
+ * screen-space grouping of overlapping markers, and the two line layers.
+ */
+
+import { isValidPoint } from "../core/geo";
+import type { LngLat, Position } from "../core/types";
+
+import type { MapLike } from "./maplibre-types";
+import type { RouteMapMarker, RouteMapProps, RouteMapTheme } from "./types";
+
+/** Below this many pixels apart, two markers are one tap target. */
+const GROUP_RADIUS_PX = 32;
+
+export const PLANNED_LAYER = "routing-planned";
+export const TRAVELLED_LAYER = "routing-travelled";
+
+export function pointsOf(props: RouteMapProps): LngLat[] {
+  const points: LngLat[] = [];
+  for (const marker of props.markers ?? []) points.push(marker.position);
+  for (const stop of props.stops ?? []) points.push(stop.position);
+  for (const spot of props.places ?? []) points.push(spot.position);
+  for (const [lng, lat] of props.planned ?? []) points.push({ lng, lat });
+  return points.filter((point) => isValidPoint(point));
+}
+
+export function centreOf(props: RouteMapProps): [number, number] {
+  const first = pointsOf(props)[0];
+  return first ? [first.lng, first.lat] : [0, 0];
+}
+
+/** The box around every valid point; a lone point still gets a street-sized box. */
+export function boundsOf(points: readonly LngLat[]): [[number, number], [number, number]] | null {
+  const valid = points.filter((point) => isValidPoint(point));
+  if (valid.length === 0) return null;
+  const lngs = valid.map((point) => point.lng);
+  const lats = valid.map((point) => point.lat);
+  let [west, east] = [Math.min(...lngs), Math.max(...lngs)];
+  let [south, north] = [Math.min(...lats), Math.max(...lats)];
+  const pad = 0.0025;
+  if (east - west < pad) [west, east] = [west - pad, east + pad];
+  if (north - south < pad) [south, north] = [south - pad, north + pad];
+  return [
+    [west, south],
+    [east, north],
+  ];
+}
+
+/**
+ * Greedy screen-space grouping: each marker joins the first group whose anchor
+ * is within `GROUP_RADIUS_PX`. An emphasised marker always stands alone.
+ */
+export function groupMarkers(markers: readonly RouteMapMarker[], map: Pick<MapLike, "project">): RouteMapMarker[][] {
+  const groups: { anchor: { x: number; y: number }; members: RouteMapMarker[] }[] = [];
+  const alone: RouteMapMarker[][] = [];
+  for (const marker of markers) {
+    if (marker.emphasized) {
+      alone.push([marker]);
+      continue;
+    }
+    const at = map.project([marker.position.lng, marker.position.lat]);
+    const hit = groups.find((group) => Math.hypot(group.anchor.x - at.x, group.anchor.y - at.y) < GROUP_RADIUS_PX);
+    if (hit) hit.members.push(marker);
+    else groups.push({ anchor: at, members: [marker] });
+  }
+  return [...groups.map((group) => group.members), ...alone];
+}
+
+function lineFeature(positions: readonly Position[]) {
+  return { type: "Feature" as const, properties: {}, geometry: { type: "LineString" as const, coordinates: positions.map((p) => [p[0], p[1]]) } };
+}
+
+export function addLines(map: MapLike, theme: RouteMapTheme): void {
+  for (const id of [PLANNED_LAYER, TRAVELLED_LAYER]) map.addSource(id, { type: "geojson", data: lineFeature([]) });
+  const layout = { "line-cap": "round", "line-join": "round" };
+  map.addLayer({ id: PLANNED_LAYER, type: "line", source: PLANNED_LAYER, layout, paint: { "line-color": theme.planned, "line-width": 4, "line-dasharray": [2, 1.6] } });
+  map.addLayer({ id: TRAVELLED_LAYER, type: "line", source: TRAVELLED_LAYER, layout, paint: { "line-color": theme.travelled, "line-width": 5 } });
+}
+
+export function setLine(map: MapLike, id: string, positions: readonly Position[] | undefined): void {
+  map.getSource(id)?.setData(lineFeature(positions ?? []));
+}

package/src/react/maplibre-types.ts

@@ -0,0 +1,37 @@
+/**
+ * The slice of MapLibre GL this package calls — declared here so the
+ * component compiles and tests run without the library's WebGL runtime, and
+ * so a test can hand in a fake. `maplibre-gl` satisfies it structurally.
+ */
+
+export interface MapLike {
+  on(event: "load" | "style.load" | "error" | "moveend", listener: () => void): unknown;
+  remove(): void;
+  addSource(id: string, source: { type: "geojson"; data: unknown }): unknown;
+  getSource(id: string): { setData(data: unknown): unknown } | undefined;
+  addLayer(layer: Record<string, unknown>): unknown;
+  setPaintProperty(layer: string, property: string, value: unknown): unknown;
+  fitBounds(bounds: [[number, number], [number, number]], options?: Record<string, unknown>): unknown;
+  zoomIn(): unknown;
+  zoomOut(): unknown;
+  project(lngLat: [number, number]): { x: number; y: number };
+}
+
+export interface MarkerLike {
+  setLngLat(lngLat: [number, number]): MarkerLike;
+  addTo(map: MapLike): MarkerLike;
+  remove(): unknown;
+}
+
+export interface MapLibreLike {
+  Map: new (options: {
+    container: HTMLElement;
+    style: string;
+    attributionControl: boolean;
+    center: [number, number];
+    zoom: number;
+  }) => MapLike;
+  Marker: new (options: { element: HTMLElement; anchor: "bottom" | "center" }) => MarkerLike;
+  /** MapLibre 6 loads its worker from a separate file; the host says where. */
+  setWorkerUrl?(url: string): void;
+}