@12-apps/routing 0.0.0-stage → 1.1.0

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,43 @@
+/**
+ * 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" | "zoomend", 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;
+  /**
+   * Shift the element from its anchor, in pixels — how a marker's tag moves
+   * to another side of its pin. Optional so an older fake still drives the
+   * map; without it the tag keeps its default side.
+   */
+  setOffset?(offset: [number, number]): MarkerLike;
+}
+
+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;
+}

package/src/react/pt-BR.ts

@@ -0,0 +1,12 @@
+import type { RouteMapCopy } from "./copy";
+
+export const PT_BR_ROUTE_MAP_COPY: RouteMapCopy = {
+  zoomIn: "Aproximar",
+  zoomOut: "Afastar",
+  fitAll: "Mostrar todos",
+  mapLabel: "Mapa",
+  mapError: "Não foi possível carregar o mapa.",
+  retry: "Tentar de novo",
+  group: (count) => `${count} aqui — toque para escolher`,
+  attribution: "© OpenFreeMap © OpenMapTiles © colaboradores do OpenStreetMap",
+};

package/src/react/route-map.tsx

@@ -0,0 +1,177 @@
+/**
+ * `RouteMap` — a geographic map that draws what the host hands it: markers
+ * (people, vehicles), places (a shop), numbered stops, a planned line (dashed)
+ * and a travelled line (solid). It fetches nothing and decides nothing: every
+ * point, word and colour is a prop or config, so the same component serves a
+ * fleet overview and a single order's card.
+ *
+ * - **Real projection.** MapLibre GL over a vector style (OpenFreeMap by
+ *   default), loaded lazily the first time a map mounts.
+ * - **The viewport is the viewer's.** It fits once, and again only when
+ *   `fitKey` changes or the fit control is pressed.
+ * - **Overlapping markers stay reachable** as one group button.
+ * - **Failure is visible, not blank**: the host's error copy and a retry.
+ */
+
+import { useEffect, useRef, useState, type CSSProperties, type JSX } from "react";
+
+import type { RouteMapCopy } from "./copy";
+import type { MapLibreLike } from "./maplibre-types";
+import type { RouteMapConfig, RouteMapProps, RouteMapTheme } from "./types";
+import { useMapInstance } from "./use-map";
+import { useOverlays, useOverlaySync } from "./use-overlays";
+
+export const DEFAULT_STYLE_URL = "https://tiles.openfreemap.org/styles/liberty";
+
+/** How long a map may take to load its style before it shows the error state. */
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+
+const defaultLoader = async (): Promise<MapLibreLike> => {
+  const lib = (await import("maplibre-gl")) as unknown as { default?: MapLibreLike } & MapLibreLike;
+  return lib.default ?? lib;
+};
+
+export function buildRouteMap(config: RouteMapConfig): (props: RouteMapProps) => JSX.Element {
+  const { copy, theme } = config;
+  const baseLoad = config.loadMapLibre ?? defaultLoader;
+  const load = async (): Promise<MapLibreLike> => {
+    const lib = await baseLoad();
+    if (config.workerUrl) lib.setWorkerUrl?.(config.workerUrl);
+    return lib;
+  };
+  const styleUrl = config.styleUrl ?? DEFAULT_STYLE_URL;
+  const readyTimeoutMs = config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+
+  return function RouteMap(props: RouteMapProps): JSX.Element {
+    const container = useRef<HTMLDivElement | null>(null);
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    const overlaysRef = useRef<ReturnType<typeof useOverlays> | null>(null);
+    const handle = useMapInstance({
+      load,
+      styleUrl,
+      readyTimeoutMs,
+      theme,
+      container,
+      propsRef,
+      onMoveEnd: () => overlaysRef.current?.draw(),
+      onZoomEnd: () => overlaysRef.current?.place(),
+      onDispose: () => overlaysRef.current?.clear(),
+    });
+    const overlays = useOverlays({ ...handle, container }, propsRef, copy, theme);
+    overlaysRef.current = overlays;
+    useOverlaySync(handle.status === "ready", handle, props, overlays, theme);
+
+    const height = typeof props.height === "number" ? `${props.height}px` : props.height;
+    return (
+      <div className="routing-map" data-testid={props.testId} data-state={handle.status} role="region" aria-label={copy.mapLabel} style={{ position: "relative", height, width: "100%", overflow: "hidden", borderRadius: "inherit" }}>
+        <div ref={container} style={{ position: "absolute", inset: 0 }} />
+        {handle.status === "error" ? (
+          <MapError copy={copy} theme={theme} onRetry={handle.retry} />
+        ) : (
+          <MapControls
+            copy={copy}
+            theme={theme}
+            {...controlsOf(props)}
+            onZoomIn={() => handle.mapRef.current?.zoomIn()}
+            onZoomOut={() => handle.mapRef.current?.zoomOut()}
+            onFit={() => {
+              overlays.fitAll();
+              propsRef.current.onFitAll?.();
+            }}
+          />
+        )}
+        {props.overlay && handle.status !== "error" ? <div style={{ position: "absolute", left: 12, right: 12, bottom: 28, zIndex: 2 }}>{props.overlay}</div> : null}
+        <Attribution copy={copy} theme={theme} compact={props.attribution === "compact"} />
+      </div>
+    );
+  };
+}
+
+/** The controls the host asked for, with their defaults: both, top-right. */
+function controlsOf({ controls }: RouteMapProps): Pick<ControlsProps, "zoom" | "fit" | "placement"> {
+  return { zoom: controls?.zoom ?? true, fit: controls?.fit ?? true, placement: controls?.placement ?? "top-right" };
+}
+
+/** The basemap's required credit: the full line, or an "i" that opens it. */
+function Attribution({ copy, theme, compact }: { copy: RouteMapCopy; theme: RouteMapTheme; compact: boolean }): JSX.Element {
+  const [open, setOpen] = useState(false);
+  // Switching to compact folds the credit again; switching to full always shows it.
+  useEffect(() => setOpen(false), [compact]);
+  const line: CSSProperties = { position: "absolute", right: 6, bottom: 4, fontSize: 10, color: theme.ink, background: theme.paper, padding: "0 4px", borderRadius: 4, zIndex: 2 };
+  if (!compact) return <small style={line}>{copy.attribution}</small>;
+  if (open) {
+    return (
+      <button type="button" aria-expanded={true} onClick={() => setOpen(false)} style={{ ...line, border: 0, cursor: "pointer" }}>
+        {copy.attribution}
+      </button>
+    );
+  }
+  return (
+    <button type="button" aria-label={copy.attribution} aria-expanded={false} onClick={() => setOpen(true)} style={{ ...line, width: 18, height: 18, padding: 0, borderRadius: 9, border: `1px solid ${theme.controlBorder}`, fontWeight: 700, cursor: "pointer" }}>
+      i
+    </button>
+  );
+}
+
+interface ControlsProps {
+  copy: RouteMapCopy;
+  theme: RouteMapTheme;
+  zoom: boolean;
+  fit: boolean;
+  placement: "top-right" | "top-left";
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onFit: () => void;
+}
+
+function MapControls({ copy, theme, zoom, fit, placement, onZoomIn, onZoomOut, onFit }: ControlsProps): JSX.Element | null {
+  if (!zoom && !fit) return null;
+  const corner = placement === "top-left" ? { left: 12 } : { right: 12 };
+  return (
+    <div style={{ position: "absolute", top: 12, ...corner, display: "flex", flexDirection: "column", gap: 8, zIndex: 2 }}>
+      {zoom ? (
+        <>
+          <button type="button" className="routing-zoom" aria-label={copy.zoomIn} onClick={onZoomIn} style={controlStyle(theme)}>
+            +
+          </button>
+          <button type="button" className="routing-zoom" aria-label={copy.zoomOut} onClick={onZoomOut} style={controlStyle(theme)}>
+            −
+          </button>
+        </>
+      ) : null}
+      {fit ? (
+        <button type="button" aria-label={copy.fitAll} onClick={onFit} style={controlStyle(theme)}>
+          <FitIcon />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+function MapError({ copy, theme, onRetry }: { copy: RouteMapCopy; theme: RouteMapTheme; onRetry: () => void }): JSX.Element {
+  const style: CSSProperties = { position: "absolute", inset: 0, display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center", gap: 12, background: theme.paper, color: theme.ink, textAlign: "center", padding: 16 };
+  return (
+    <div role="alert" style={style}>
+      <span>{copy.mapError}</span>
+      <button type="button" onClick={onRetry} style={{ ...controlStyle(theme), width: "auto", padding: "0 14px", fontSize: 14 }}>
+        {copy.retry}
+      </button>
+    </div>
+  );
+}
+
+function FitIcon(): JSX.Element {
+  return (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M8 3H5a2 2 0 0 0-2 2v3" />
+      <path d="M21 8V5a2 2 0 0 0-2-2h-3" />
+      <path d="M3 16v3a2 2 0 0 0 2 2h3" />
+      <path d="M16 21h3a2 2 0 0 0 2-2v-3" />
+    </svg>
+  );
+}
+
+function controlStyle(theme: RouteMapTheme): CSSProperties {
+  return { minWidth: 44, width: 44, height: 44, padding: 0, borderRadius: 10, border: `1px solid ${theme.controlBorder}`, background: theme.control, color: theme.ink, fontSize: 20, display: "flex", alignItems: "center", justifyContent: "center", cursor: "pointer" };
+}

package/src/react/tag-placement.ts

@@ -0,0 +1,221 @@
+/**
+ * Where a marker's tag sits around its pin, so it never hides a stop badge or
+ * a place label. Stops and places are geographic truth and never move; only a
+ * marker's TAG (its pill and tail) changes side — the pin point stays put.
+ *
+ * Sides are tried in order — above (the default), below, right, left — and the
+ * first whose box touches no stop or place and stays inside the map wins. When
+ * none is clear, the side with the least overlap area does (ties keep the
+ * earlier side), so a crowded card still reads as well as it can.
+ *
+ * Geometry is `map.project()` plus each element's layout size (`offsetWidth`,
+ * which ignores MapLibre's transform), so it never waits on a repaint.
+ */
+
+import { setTagSide, TAG_TAIL_PX, type TagSide } from "./map-elements";
+import type { MapLike, MarkerLike } from "./maplibre-types";
+
+
+const TAG_SIDES: readonly TagSide[] = ["above", "below", "right", "left"];
+
+interface Box {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+interface Size {
+  width: number;
+  height: number;
+}
+
+/** The visible tag (pill plus tail) for a pill of `size`, on `side` of `pin`. */
+function tagBox(pin: Point, size: Size, side: TagSide): Box {
+  const along = TAG_TAIL_PX;
+  if (side === "above") return { left: pin.x - size.width / 2, right: pin.x + size.width / 2, top: pin.y - size.height - along, bottom: pin.y };
+  if (side === "below") return { left: pin.x - size.width / 2, right: pin.x + size.width / 2, top: pin.y, bottom: pin.y + along + size.height };
+  if (side === "right") return { left: pin.x, right: pin.x + along + size.width, top: pin.y - size.height / 2, bottom: pin.y + size.height / 2 };
+  return { left: pin.x - along - size.width, right: pin.x, top: pin.y - size.height / 2, bottom: pin.y + size.height / 2 };
+}
+
+function overlapArea(a: Box, b: Box): number {
+  const width = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+  const height = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+  return width > 0 && height > 0 ? width * height : 0;
+}
+
+/** Inside the map; a map with no laid-out size (not measured yet) bounds nothing. */
+function fits(box: Box, bounds: Size): boolean {
+  if (bounds.width <= 0 || bounds.height <= 0) return true;
+  return box.left >= 0 && box.top >= 0 && box.right <= bounds.width && box.bottom <= bounds.height;
+}
+
+/**
+ * How far clear a side other than the current one must be to win it: a pin
+ * jittering a pixel or two at an obstacle's edge must not flip its tag.
+ */
+const SWITCH_MARGIN_PX = 4;
+
+/** In the least-overlap fallback, leave the current side only for this much less overlap. */
+const SWITCH_OVERLAP_RATIO = 0.75;
+
+/**
+ * How far past an obstacle's edge a pin that was standing ON it still counts
+ * as on it: a pin jittering across a badge's edge must not flip its tag. A
+ * pin arriving must be on the badge itself.
+ */
+const CONTAIN_MARGIN_PX = 6;
+
+function grow(box: Box, by: number): Box {
+  return { left: box.left - by, top: box.top - by, right: box.right + by, bottom: box.bottom + by };
+}
+
+function overlapWith(box: Box, obstacles: readonly Box[]): number {
+  return obstacles.reduce((sum, obstacle) => sum + overlapArea(box, obstacle), 0);
+}
+
+function clear(box: Box, obstacles: readonly Box[], bounds: Size): boolean {
+  return overlapWith(box, obstacles) === 0 && fits(box, bounds);
+}
+
+function contains(box: Box, point: Point): boolean {
+  return point.x >= box.left && point.x <= box.right && point.y >= box.top && point.y <= box.bottom;
+}
+
+interface Scored {
+  side: TagSide;
+  overlap: number;
+  inside: boolean;
+}
+
+function better(a: Scored, b: Scored): boolean {
+  if (a.overlap !== b.overlap) return a.overlap < b.overlap;
+  return a.inside && !b.inside;
+}
+
+/** When every side is blocked: the least overlap, but the current side unless that is a real gain. */
+function leastOverlap(pin: Point, size: Size, obstacles: readonly Box[], bounds: Size, current: TagSide): TagSide {
+  const scored = TAG_SIDES.map((side): Scored => {
+    const box = tagBox(pin, size, side);
+    return { side, overlap: overlapWith(box, obstacles), inside: fits(box, bounds) };
+  });
+  const best = scored.reduce((winner, next) => (better(next, winner) ? next : winner));
+  const kept = scored.find((item) => item.side === current)!;
+  return best.overlap < kept.overlap * SWITCH_OVERLAP_RATIO ? best.side : current;
+}
+
+/**
+ * The side for a tag whose pill is `size` on a pin at `pin`, now on `current`:
+ *
+ * 1. in order, the first side that is the current one and clear, or another
+ *    one clear by `SWITCH_MARGIN_PX` — so a tag returns above once an
+ *    obstacle has really gone, and never flips on a pixel of jitter;
+ * 2. else the first clear side;
+ * 3. else the least overlap (keeping the current side unless it is a real gain).
+ *
+ * The caller leaves out any obstacle under the pin itself (`underPin`).
+ */
+function chooseSide(pin: Point, size: Size, obstacles: readonly Box[], bounds: Size, current: TagSide = "above"): TagSide {
+  const margined = TAG_SIDES.find((side) => {
+    const box = tagBox(pin, size, side);
+    return side === current ? clear(box, obstacles, bounds) : clear(grow(box, SWITCH_MARGIN_PX), obstacles, bounds);
+  });
+  if (margined) return margined;
+  const first = TAG_SIDES.find((side) => clear(tagBox(pin, size, side), obstacles, bounds));
+  return first ?? leastOverlap(pin, size, obstacles, bounds, current);
+}
+
+/**
+ * The obstacles under the pin's own point (a courier arriving at his stop):
+ * they do not block his tag, since every side would clip them about equally.
+ * A pin that was `standing` on one keeps it until `CONTAIN_MARGIN_PX` clear.
+ */
+function underPin(pin: Point, obstacles: readonly Box[], standing: boolean): Box[] {
+  const reach = standing ? CONTAIN_MARGIN_PX : 0;
+  return obstacles.filter((obstacle) => contains(grow(obstacle, reach), pin));
+}
+
+export type Anchor = "bottom" | "center";
+
+/** An element's layout box when MapLibre puts its `anchor` on `point`. */
+function anchoredBox(point: Point, anchor: Anchor, size: Size): Box {
+  const left = point.x - size.width / 2;
+  const top = anchor === "bottom" ? point.y - size.height : point.y - size.height / 2;
+  return { left, top, right: left + size.width, bottom: top + size.height };
+}
+
+/**
+ * The marker offset that keeps the pin on its point for a frame of `size`
+ * laid out for `side` (anchor `bottom`: the frame's bottom-centre is the
+ * point before the offset).
+ */
+function offsetFor(side: TagSide, size: Size): [number, number] {
+  if (side === "below") return [0, size.height];
+  if (side === "right") return [size.width / 2, size.height / 2];
+  if (side === "left") return [-size.width / 2, size.height / 2];
+  return [0, 0];
+}
+
+function sizeOf(element: Element | null | undefined): Size {
+  const html = element as HTMLElement | null | undefined;
+  return { width: html?.offsetWidth ?? 0, height: html?.offsetHeight ?? 0 };
+}
+
+/** What the placement needs from each drawn element. */
+export interface Placed {
+  marker: MarkerLike;
+  element: HTMLElement;
+  at: [number, number];
+  anchor: Anchor;
+  role: "tag" | "stop" | "place";
+  /** Whether the pin stood on a stop or place at the last placement (hysteresis). */
+  standing?: boolean;
+}
+
+/** A stop's badge, or a place's LABEL (a lifted place's stem is not in the way). */
+function obstacleOf(map: Pick<MapLike, "project">, item: Placed): Box {
+  const frame = anchoredBox(map.project(item.at), item.anchor, sizeOf(item.element));
+  const target = item.role === "place" ? (item.element.firstElementChild as HTMLElement | null) : null;
+  if (!target) return frame;
+  const left = frame.left + target.offsetLeft;
+  const top = frame.top + target.offsetTop;
+  return { left, top, right: left + target.offsetWidth, bottom: top + target.offsetHeight };
+}
+
+/** Move one tag to `side`, re-anchoring its frame so the tail still meets the pin. */
+function applySide(item: Placed, side: TagSide): void {
+  if (sideOf(item.element) === side) return;
+  if (!setTagSide(item.element, side)) return;
+  item.marker.setOffset?.(offsetFor(side, sizeOf(item.element)));
+}
+
+function sideOf(element: HTMLElement): TagSide {
+  const side = element.dataset.tagSide;
+  return TAG_SIDES.find((known) => known === side) ?? "above";
+}
+
+/**
+ * Place every marker's tag clear of the stops and places drawn with it — or,
+ * with `fixed`, put back above any tag a previous `avoid` had moved.
+ */
+export function placeTags(map: Pick<MapLike, "project">, items: readonly Placed[], bounds: Size, mode: "avoid" | "fixed" = "avoid"): void {
+  const tags = items.filter((item) => item.role === "tag");
+  if (mode === "fixed") {
+    for (const item of tags) applySide(item, "above");
+    return;
+  }
+  const obstacles = items.filter((item) => item.role !== "tag").map((item) => obstacleOf(map, item));
+  for (const item of tags) {
+    const pin = map.project(item.at);
+    const under = underPin(pin, obstacles, !!item.standing);
+    item.standing = under.length > 0;
+    const blocking = obstacles.filter((obstacle) => !under.includes(obstacle));
+    applySide(item, chooseSide(pin, sizeOf(item.element.firstElementChild), blocking, bounds, sideOf(item.element)));
+  }
+}

package/src/react/types.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from "react";
+
+import type { LngLat, Position } from "../core/types";
+
+import type { RouteMapCopy } from "./copy";
+import type { MapLibreLike } from "./maplibre-types";
+
+export interface RouteMapMarker {
+  id: string;
+  position: LngLat;
+  /** What the marker reads — initials, or a name when emphasised. */
+  text: string;
+  ariaLabel: string;
+  color: string;
+  /** The selected marker: larger, on top, never grouped. */
+  emphasized?: boolean;
+  /** An old position: dashed outline, translucent. */
+  faded?: boolean;
+  /** A glyph before the text: a motorbike for a courier. */
+  icon?: "motorbike";
+  onSelect?: () => void;
+}
+
+export interface RouteMapStop {
+  id: string;
+  position: LngLat;
+  /** "✓", "2", … */
+  mark: string;
+  /** Accessible title, e.g. "Parada 2 — Av. Vilarinho, 1731". */
+  title: string;
+  variant: "done" | "next" | "pending";
+  /**
+   * Drawn above every pin (the stop a screen is about, e.g. "this order"), so
+   * a courier standing next to it never hides it. Default: under the pins.
+   */
+  emphasized?: boolean;
+}
+
+export interface RouteMapPlace {
+  id: string;
+  position: LngLat;
+  label: string;
+  /** A glyph before the label: a shopfront for a store. */
+  icon?: "store";
+}
+
+/** Colours, from the host's theme — the component never picks one itself. */
+export interface RouteMapTheme {
+  planned: string;
+  travelled: string;
+  done: string;
+  next: string;
+  pending: string;
+  ink: string;
+  paper: string;
+  place: string;
+  control: string;
+  controlBorder: string;
+}
+
+export interface RouteMapProps {
+  markers?: readonly RouteMapMarker[];
+  stops?: readonly RouteMapStop[];
+  places?: readonly RouteMapPlace[];
+  /** The dashed line, `[lng, lat][]`. */
+  planned?: readonly Position[];
+  /** The solid line, `[lng, lat][]`. */
+  travelled?: readonly Position[];
+  /** Overrides `theme.travelled` (a status colour). */
+  travelledColor?: string;
+  /** Change it to refit the viewport to everything drawn. */
+  fitKey?: string;
+  /**
+   * Fit to just these points (a selected trip) whenever `key` changes — a
+   * viewer's selection, never a data refresh. Wins over `fitKey` on the same
+   * render.
+   */
+  focus?: { key: string; points: readonly Position[] };
+  /** CSS height of the map area. */
+  height: number | string;
+  /**
+   * Which controls show, and in which top corner (default `top-right`). A
+   * host whose own floating chrome covers one corner moves them to the other.
+   */
+  controls?: { zoom?: boolean; fit?: boolean; placement?: "top-right" | "top-left" };
+  /** Called when the viewer presses the fit control (after it fits). */
+  onFitAll?: () => void;
+  /** Called with the ids of a pressed group of overlapping markers. */
+  onGroupSelect?: (markerIds: string[]) => void;
+  /** Rendered over the map (a legend), bottom edge. */
+  overlay?: ReactNode;
+  /**
+   * Pixels the host's own overlays cover on each edge (a legend along the
+   * bottom, a sheet). Added to the fit padding, so "fit all" never parks a
+   * pin or a stop under them.
+   */
+  insets?: { top?: number; right?: number; bottom?: number; left?: number };
+  /**
+   * How a place's label is drawn. `lifted` (default) raises it above a pin
+   * standing on the same point; `at-point` draws it on the point, for a small
+   * map where the lift would cost a third of the height.
+   */
+  placeLabels?: "lifted" | "at-point";
+  /**
+   * Where a marker's tag (pill and tail) sits around its pin. `avoid`
+   * (default) keeps it above unless a stop badge or place label is in the
+   * way, then takes the first clear side — below, right, left — with the tail
+   * still on the pin; stops, places and the pin's point never move. `fixed`
+   * always draws it above, as before. Either way the marker element carries
+   * `data-tag-side="above|below|right|left"`.
+   */
+  tagPlacement?: "avoid" | "fixed";
+  /**
+   * `full` (default) prints the basemap's attribution line; `compact` shows an
+   * "i" control that expands to it, for a small map. Either satisfies the
+   * tile terms.
+   */
+  attribution?: "full" | "compact";
+  testId?: string;
+}
+
+export interface RouteMapConfig {
+  copy: RouteMapCopy;
+  theme: RouteMapTheme;
+  /** A MapLibre style URL. Defaults to OpenFreeMap "liberty". */
+  styleUrl?: string;
+  /**
+   * Where MapLibre's worker file is served from. MapLibre 6 ships the worker
+   * as its own module (`maplibre-gl/dist/maplibre-gl-worker.mjs`) and cannot
+   * guess its bundled URL; a Vite host passes
+   * `import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?url"`.
+   */
+  workerUrl?: string;
+  /** How to load MapLibre — swapped in tests, or for a host that preloads it. */
+  loadMapLibre?: () => Promise<MapLibreLike>;
+  /**
+   * How long the map may take to become ready (its style loaded) before it
+   * shows the error state with Retry. Default 15 000 ms. A style request that
+   * hangs fires no error, so without this the map would stay blank forever.
+   */
+  readyTimeoutMs?: number;
+}