@12-apps/routing 0.0.0-stage → 1.1.0

package/src/react/use-map.ts

@@ -0,0 +1,107 @@
+/**
+ * The MapLibre instance behind one `RouteMap`: load the library lazily, build
+ * the map with both line layers, report `loading | ready | error`, and tear it
+ * down on unmount or before a retry. A failure before the first `load` (no
+ * WebGL, a library or style that fails or does not arrive within
+ * `readyTimeoutMs`, counted from mount) is `error`; a tile failing later is not.
+ * Readiness is the style's, not the tiles' (`style.load`).
+ */
+
+import { useEffect, useRef, useState, type MutableRefObject } from "react";
+
+import { MAP_CSS, MAP_CSS_ID } from "./map-css";
+import { addLines, centreOf } from "./map-geometry";
+import type { MapLibreLike, MapLike } from "./maplibre-types";
+import type { RouteMapProps, RouteMapTheme } from "./types";
+
+export type MapStatus = "loading" | "ready" | "error";
+
+export interface MapHandle {
+  mapRef: MutableRefObject<MapLike | null>;
+  libRef: MutableRefObject<MapLibreLike | null>;
+  status: MapStatus;
+  retry: () => void;
+}
+
+interface MapSetup {
+  load: () => Promise<MapLibreLike>;
+  styleUrl: string;
+  /** Not ready by then is `error`: a hung style request fires no error event. */
+  readyTimeoutMs: number;
+  theme: RouteMapTheme;
+  container: MutableRefObject<HTMLDivElement | null>;
+  propsRef: MutableRefObject<RouteMapProps>;
+  /** Called after each pan or zoom, to regroup markers. */
+  onMoveEnd: () => void;
+  /** Called after each zoom, to re-place the markers' tags. */
+  onZoomEnd: () => void;
+  /** Called before the map goes away, to drop markers. */
+  onDispose: () => void;
+}
+
+function injectCss(): void {
+  if (typeof document === "undefined" || document.getElementById(MAP_CSS_ID)) return;
+  const style = document.createElement("style");
+  style.id = MAP_CSS_ID;
+  style.textContent = MAP_CSS;
+  document.head.appendChild(style);
+}
+
+export function useMapInstance(setup: MapSetup): MapHandle {
+  const mapRef = useRef<MapLike | null>(null);
+  const libRef = useRef<MapLibreLike | null>(null);
+  const setupRef = useRef(setup);
+  setupRef.current = setup;
+  const [status, setStatus] = useState<MapStatus>("loading");
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    injectCss();
+    let disposed = false;
+    let ready = false;
+    setStatus("loading");
+    const current = setupRef.current;
+    // From the START, not from when the library arrives: a library chunk that
+    // never finishes downloading must reach the error state too.
+    const readyTimer = setTimeout(() => {
+      if (!ready && !disposed) setStatus("error");
+    }, current.readyTimeoutMs);
+    void current
+      .load()
+      .then((lib) => {
+        if (disposed || !current.container.current) return;
+        libRef.current = lib;
+        const map = new lib.Map({ container: current.container.current, style: current.styleUrl, attributionControl: false, center: centreOf(current.propsRef.current), zoom: 13 });
+        mapRef.current = map;
+        map.on("error", () => {
+          if (!ready && !disposed) setStatus("error");
+        });
+        // Ready as soon as the STYLE is in: sources, layers and markers need
+        // nothing more. `load` waits for every first tile too, which over a
+        // slow link can be many seconds of an empty map; it stays as a backstop.
+        const onReady = (): void => {
+          if (disposed || ready) return;
+          ready = true;
+          clearTimeout(readyTimer);
+          addLines(map, current.theme);
+          setStatus("ready");
+        };
+        map.on("style.load", onReady);
+        map.on("load", onReady);
+        map.on("moveend", () => setupRef.current.onMoveEnd());
+        map.on("zoomend", () => setupRef.current.onZoomEnd());
+      })
+      .catch(() => {
+        if (!disposed) setStatus("error");
+      });
+    return () => {
+      disposed = true;
+      clearTimeout(readyTimer);
+      setupRef.current.onDispose();
+      mapRef.current?.remove();
+      mapRef.current = null;
+    };
+  }, [attempt]);
+
+  return { mapRef, libRef, status, retry: () => setAttempt((n) => n + 1) };
+}

package/src/react/use-overlays.ts

@@ -0,0 +1,227 @@
+/**
+ * Everything `RouteMap` draws on top of the basemap, kept in step with the
+ * props: the two lines, the markers (regrouped after every pan or zoom), the
+ * stops and places, and the viewport fit — once when ready, then only when
+ * `fitKey` changes or the viewer asks.
+ *
+ * ## Reconciled by key, never rebuilt
+ *
+ * Every drawn element has a key (`m:<id>`, `g:<ids>`, `s:<id>`, `p:<id>`)
+ * and a signature of what it shows. A redraw moves elements whose signature is
+ * unchanged, replaces the ones that changed and removes the ones that left —
+ * so a refresh every few seconds, a pan, or the host re-rendering with a new
+ * array never drops the keyboard focus a viewer put on a marker. Click
+ * handlers read the host's CURRENT callback by key, so a kept element never
+ * calls a stale one.
+ *
+ * ## Tags step aside, stops and places never move
+ *
+ * After every draw, fit and zoom (unless `tagPlacement="fixed"`), each marker's tag (pill and tail) takes the
+ * first side of its pin — above, below, right, left — clear of every stop
+ * badge and place label (`tag-placement.ts`). The element is restyled and
+ * re-offset in place, never rebuilt, so the focus rule above still holds.
+ */
+
+import { useEffect, useRef, type MutableRefObject, type RefObject } from "react";
+
+import { isValidPoint } from "../core/geo";
+import type { LngLat } from "../core/types";
+
+import type { RouteMapCopy } from "./copy";
+import { groupElement, markerElement, PLACE_LIFT, placeElement, stopElement } from "./map-elements";
+import { boundsOf, groupMarkers, PLANNED_LAYER, pointsOf, setLine, TRAVELLED_LAYER } from "./map-geometry";
+import type { MarkerLike } from "./maplibre-types";
+import { placeTags, type Placed } from "./tag-placement";
+import type { MapHandle } from "./use-map";
+import type { RouteMapMarker, RouteMapProps, RouteMapTheme } from "./types";
+
+interface Overlays {
+  draw: () => void;
+  /** Re-place the markers' tags around the stops and places, as drawn now. */
+  place: () => void;
+  clear: () => void;
+  fitAll: () => void;
+  fitTo: (points: readonly LngLat[]) => void;
+}
+
+interface Drawn extends Placed {
+  marker: MarkerLike;
+  element: HTMLElement;
+  signature: string;
+}
+
+interface Wanted {
+  key: string;
+  signature: string;
+  position: LngLat;
+  anchor: "bottom" | "center";
+  role: Placed["role"];
+  build: () => HTMLElement;
+}
+
+export function useOverlays(
+  handle: Pick<MapHandle, "mapRef" | "libRef"> & { container: RefObject<HTMLElement | null> },
+  propsRef: MutableRefObject<RouteMapProps>,
+  copy: RouteMapCopy,
+  theme: RouteMapTheme,
+): Overlays {
+  const drawn = useRef(new Map<string, Drawn>());
+  /** The current action per key, read at click time. */
+  const actions = useRef(new Map<string, () => void>());
+
+  const clear = (): void => {
+    for (const item of drawn.current.values()) item.marker.remove();
+    drawn.current.clear();
+  };
+
+  const onGroup = (group: readonly RouteMapMarker[]): void => {
+    const handler = propsRef.current.onGroupSelect;
+    if (handler) return handler(group.map((marker) => marker.id));
+    const bounds = boundsOf(group.map((marker) => marker.position));
+    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: 64, maxZoom: 19, duration: 300 });
+  };
+
+  const wanted = (props: RouteMapProps): Wanted[] => {
+    const map = handle.mapRef.current;
+    if (!map) return [];
+    actions.current.clear();
+    const out: Wanted[] = [];
+    for (const spot of (props.places ?? []).filter((item) => isValidPoint(item.position))) {
+      const lifted = props.placeLabels !== "at-point";
+      out.push({ key: `p:${spot.id}`, signature: JSON.stringify([spot.label, spot.icon, lifted]), position: spot.position, anchor: lifted ? "bottom" : "center", role: "place", build: () => placeElement(spot, theme, lifted) });
+    }
+    for (const stop of (props.stops ?? []).filter((item) => isValidPoint(item.position))) {
+      out.push({ key: `s:${stop.id}`, signature: JSON.stringify([stop.mark, stop.title, stop.variant, !!stop.emphasized]), position: stop.position, anchor: "center", role: "stop", build: () => stopElement(stop, theme) });
+    }
+    const valid = (props.markers ?? []).filter((marker) => isValidPoint(marker.position));
+    for (const group of groupMarkers(valid, map)) out.push(group.length === 1 ? markerWanted(group[0]!) : groupWanted(group));
+    return out;
+  };
+
+  const markerWanted = (marker: RouteMapMarker): Wanted => {
+    const key = `m:${marker.id}`;
+    if (marker.onSelect) actions.current.set(key, marker.onSelect);
+    const act = marker.onSelect ? () => actions.current.get(key)?.() : null;
+    const signature = JSON.stringify([marker.text, marker.ariaLabel, marker.color, !!marker.emphasized, !!marker.faded, marker.icon, !!marker.onSelect]);
+    return { key, signature, position: marker.position, anchor: "bottom", role: "tag", build: () => markerElement(marker, theme, act) };
+  };
+
+  const groupWanted = (group: RouteMapMarker[]): Wanted => {
+    const key = `g:${group.map((marker) => marker.id).join(",")}`;
+    actions.current.set(key, () => onGroup(group));
+    return { key, signature: String(group.length), position: group[0]!.position, anchor: "bottom", role: "tag", build: () => groupElement(group.length, copy, theme, () => actions.current.get(key)?.()) };
+  };
+
+  const draw = (): void => {
+    const lib = handle.libRef.current;
+    const map = handle.mapRef.current;
+    if (lib && map) reconcile(drawn.current, wanted(propsRef.current), (element, anchor, at) => new lib.Marker({ element, anchor }).setLngLat(at).addTo(map));
+    place();
+  };
+
+  const place = (): void => placeAll(handle, drawn.current, propsRef.current.tagPlacement);
+
+  const fitAll = (): void => {
+    // The control column sits on the right edge: keep fitted content clear of
+    // it, or the farthest stop lands under the fit button.
+    const bounds = boundsOf(pointsOf(propsRef.current));
+    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: fitPadding(propsRef.current), maxZoom: 16, duration: 0 });
+    place();
+  };
+
+  const fitTo = (points: readonly LngLat[]): void => {
+    const bounds = boundsOf(points.filter((point) => isValidPoint(point)));
+    // Animated: its zoomend/moveend re-place the tags where it lands.
+    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: fitPadding(propsRef.current), maxZoom: 16, duration: 300 });
+  };
+
+  return { draw, place, clear, fitAll, fitTo };
+}
+
+/** Re-place every drawn marker's tag, inside the map container as laid out now. */
+function placeAll(handle: Pick<MapHandle, "mapRef"> & { container: RefObject<HTMLElement | null> }, drawn: Map<string, Drawn>, mode: RouteMapProps["tagPlacement"]): void {
+  const map = handle.mapRef.current;
+  const box = handle.container.current;
+  if (map) placeTags(map, [...drawn.values()], { width: box?.clientWidth ?? 0, height: box?.clientHeight ?? 0 }, mode ?? "avoid");
+}
+
+type Edge = "top" | "right" | "bottom" | "left";
+
+/**
+ * The fit's padding: a margin on every edge, the control column on the right
+ * when it shows, plus whatever the host's own overlays cover (`insets`).
+ */
+function fitPadding(props: RouteMapProps): Record<Edge, number> {
+  const base = basePadding(props);
+  const insets = props.insets;
+  const edges: Edge[] = ["top", "right", "bottom", "left"];
+  return Object.fromEntries(edges.map((edge) => [edge, base[edge] + insetOf(insets?.[edge])])) as Record<Edge, number>;
+}
+
+/** The package's own margins, before the host's insets. */
+function basePadding({ controls, places, placeLabels }: RouteMapProps): Record<Edge, number> {
+  // A place's label rides PLACE_LIFT px above its point (map-elements.ts), so
+  // a place fitted at the top edge needs that much more room or it is clipped.
+  const base: Record<Edge, number> = { top: 40 + (places?.length && placeLabels !== "at-point" ? PLACE_LIFT : 0), right: 40, bottom: 48, left: 40 };
+  if (showsControls(controls)) base[controls?.placement === "top-left" ? "left" : "right"] = 76;
+  return base;
+}
+
+function showsControls(controls: RouteMapProps["controls"]): boolean {
+  return (controls?.zoom ?? true) || (controls?.fit ?? true);
+}
+
+/** A host inset as a usable number of pixels: finite and never negative. */
+function insetOf(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+type Place = (element: HTMLElement, anchor: Wanted["anchor"], at: [number, number]) => MarkerLike;
+
+/** Remove what left, move what is unchanged, replace what changed — keeping focus. */
+function reconcile(drawn: Map<string, Drawn>, next: readonly Wanted[], place: Place): void {
+  const keep = new Set(next.map((item) => item.key));
+  for (const [key, item] of drawn) {
+    if (keep.has(key)) continue;
+    item.marker.remove();
+    drawn.delete(key);
+  }
+  for (const item of next) {
+    const at: [number, number] = [item.position.lng, item.position.lat];
+    const current = drawn.get(item.key);
+    if (current?.signature === item.signature) {
+      current.marker.setLngLat(at);
+      current.at = at;
+      continue;
+    }
+    const hadFocus = !!current && current.element.contains(document.activeElement);
+    current?.marker.remove();
+    const element = item.build();
+    drawn.set(item.key, { marker: place(element, item.anchor, at), element, signature: item.signature, at, anchor: item.anchor, role: item.role });
+    if (hadFocus) element.focus();
+  }
+}
+
+/** Keep lines, markers and the fit in step with the props once the map is ready. */
+export function useOverlaySync(ready: boolean, handle: Pick<MapHandle, "mapRef">, props: RouteMapProps, overlays: Overlays, theme: RouteMapTheme): void {
+  useEffect(() => {
+    const map = handle.mapRef.current;
+    if (!ready || !map) return;
+    setLine(map, PLANNED_LAYER, props.planned);
+    setLine(map, TRAVELLED_LAYER, props.travelled);
+    map.setPaintProperty(TRAVELLED_LAYER, "line-color", props.travelledColor ?? theme.travelled);
+  }, [ready, props.planned, props.travelled, props.travelledColor]);
+
+  useEffect(() => {
+    if (ready) overlays.draw();
+  }, [ready, props.markers, props.stops, props.places, props.placeLabels, props.tagPlacement]);
+
+  useEffect(() => {
+    if (ready) overlays.fitAll();
+  }, [ready, props.fitKey]);
+
+  // After the fit above, so a selection made before the map was ready wins.
+  useEffect(() => {
+    if (ready && props.focus) overlays.fitTo(props.focus.points.map(([lng, lat]) => ({ lng, lat })));
+  }, [ready, props.focus?.key]);
+}

package/src/server/index.ts

@@ -0,0 +1,108 @@
+/**
+ * `@12-apps/routing/server` — the one thing this package exposes to a BACKEND
+ * host: `createApiRouting(config) → { routes, planRoute }`.
+ *
+ * - `planRoute` is the planner itself, for a host that plans in-process (a job
+ *   that saves a route when a trip starts): no HTTP hop, same fallback.
+ * - `routes` is one framework-neutral descriptor, `POST /route`, for a host
+ *   that lets a client ask for a route. Who may ask is the host's
+ *   `authorize` — the package has no idea what a caller is.
+ *
+ * Which services are tried, and in what order, is the provider list the host
+ * passes: swapping openrouteservice for OSRM, or adding a new adapter, is a
+ * config change here and nowhere else.
+ */
+
+import { isValidPoint } from "../core/geo";
+import { createRoutePlanner, type RoutePlanner, type RoutePlannerConfig } from "../core/planner";
+import type { LngLat, RouteRequest } from "../core/types";
+
+export interface RoutingRequest<TActor> {
+  actor: TActor;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  body?: unknown;
+}
+
+export interface RoutingResponse {
+  status: number;
+  body: unknown;
+}
+
+export interface RoutingRoute<TActor> {
+  method: "POST";
+  path: string;
+  handle(request: RoutingRequest<TActor>): Promise<RoutingResponse>;
+}
+
+export interface RoutingServerConfig<TActor = unknown> extends RoutePlannerConfig {
+  /** Answer whether this actor may plan a route. Required: there is no default. */
+  authorize(actor: TActor): boolean | Promise<boolean>;
+  /** Upper bound on stops per request (default 25) — a provider bills per waypoint. */
+  maxStops?: number;
+}
+
+export interface RoutingApi<TActor> {
+  routes: RoutingRoute<TActor>[];
+  planRoute: RoutePlanner;
+}
+
+const DEFAULT_MAX_STOPS = 25;
+
+export function createApiRouting<TActor = unknown>(config: RoutingServerConfig<TActor>): RoutingApi<TActor> {
+  if (typeof config.authorize !== "function") throw new TypeError("createApiRouting: `authorize` is required");
+  const planRoute = createRoutePlanner(config);
+  const maxStops = config.maxStops ?? DEFAULT_MAX_STOPS;
+  const route: RoutingRoute<TActor> = {
+    method: "POST",
+    path: "/route",
+    async handle(request) {
+      if (!(await config.authorize(request.actor))) return { status: 403, body: { error: "forbidden" } };
+      const parsed = parseRouteRequest(request.body, maxStops);
+      if (!parsed.ok) return { status: 400, body: { error: parsed.error } };
+      const route = await planRoute(parsed.request);
+      // `detail` is for the host's logs (it can name an internal host); the
+      // caller gets which provider failed and how, never the raw text.
+      const failures = route.failures.map(({ provider, kind, status }) => ({ provider, kind, ...(status === undefined ? {} : { status }) }));
+      return { status: 200, body: { ...route, failures } };
+    },
+  };
+  return { routes: [route], planRoute };
+}
+
+type Parsed = { ok: true; request: RouteRequest } | { ok: false; error: string };
+
+/** A finite, non-0,0 point from an untrusted value, or `null`. */
+function pointOf(value: unknown): LngLat | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { lng, lat } = value as Record<string, unknown>;
+  if (typeof lng !== "number" || typeof lat !== "number") return null;
+  const candidate = { lng, lat };
+  return isValidPoint(candidate) ? candidate : null;
+}
+
+function stopsOf(value: unknown, maxStops: number): LngLat[] | string {
+  if (!Array.isArray(value) || value.length === 0) return "stops must be a non-empty array";
+  if (value.length > maxStops) return `at most ${maxStops} stops`;
+  const stops = value.map(pointOf);
+  return stops.every((stop): stop is LngLat => stop !== null) ? stops : "every stop must be a valid point";
+}
+
+/** Validate an untrusted body into a request; never trust a client's points. */
+export function parseRouteRequest(body: unknown, maxStops = DEFAULT_MAX_STOPS): Parsed {
+  if (typeof body !== "object" || body === null) return { ok: false, error: "body must be an object" };
+  const { origin, stops, returnTo } = body as Record<string, unknown>;
+  const from = pointOf(origin);
+  if (!from) return { ok: false, error: "origin must be a valid point" };
+  const parsedStops = stopsOf(stops, maxStops);
+  if (typeof parsedStops === "string") return { ok: false, error: parsedStops };
+  const back = returnTo === undefined || returnTo === null ? undefined : pointOf(returnTo);
+  if (back === null) return { ok: false, error: "returnTo must be a valid point" };
+  return { ok: true, request: { origin: from, stops: parsedStops, ...(back ? { returnTo: back } : {}) } };
+}
+
+export { openRouteServiceProvider, type OpenRouteServiceOptions } from "../providers/openrouteservice";
+export { osrmProvider, type OsrmOptions } from "../providers/osrm";
+export { googleRoutesProvider, type GoogleRoutesOptions } from "../providers/google";
+export { createRoutePlanner, DEFAULT_PROVIDER_TIMEOUT_MS, RouteRequestError } from "../core/planner";
+export type { RoutePlanner, RoutePlannerConfig } from "../core/planner";