@12-apps/routing 1.0.0 → 1.1.0

package/README.md

@@ -90,7 +90,36 @@ const { RouteMap } = createWebRouting({
   fit control is pressed. A data refresh never moves a map someone panned.
 - Markers that overlap on screen fold into one group button. `onGroupSelect`
   receives their ids; without that callback, the map zooms in on them.
-- No WebGL, or a style that does not load, shows `copy.mapError` with a retry.
+- `focus={{ key, points }}` fits to just those points (a selected trip)
+  whenever `key` changes — a viewer's selection, never a refresh.
+- `insets={{ bottom: legendHeight }}` tells the fit what the host's own
+  overlays cover, so fitted pins never land under a legend or a sheet.
+- For a small map (a card): `placeLabels="at-point"` draws a place's label on
+  its point instead of lifted above a pin, and `attribution="compact"` folds
+  the basemap credit into an "i" that opens it.
+- A stop with `emphasized: true` (the one the screen is about) is drawn above
+  the pins; other stops sit beneath them.
+- A marker's (or group's) tag — its pill and tail — steps aside from stop
+  badges and place labels (`tagPlacement="avoid"`, the default). After every
+  draw, fit, pan and zoom it keeps its current side while that is clear;
+  otherwise it takes the first clear side of its pin in the order above,
+  below, right, left (a side other than the current one must be clear by a
+  few pixels, so a jittering GPS fix never flips it), and when every side is
+  blocked, the least-covering one. A stop or place under the pin's own point
+  (a courier arriving) does not count. Stops, places and the pin's point never
+  move; the tail follows the side, and the element is restyled in place, so
+  keyboard focus survives. `tagPlacement="fixed"` keeps every tag above, as
+  before this release.
+- **DOM change:** every marker and group element now carries
+  `data-tag-side="above|below|right|left"` (in both modes), so a host's DOM
+  snapshot of the map gains that attribute. A host's own `loadMapLibre` fake
+  needs `Marker#setOffset` for a tag to move.
+- `controls={{ placement: "top-left" }}` moves the zoom and fit column to the
+  other top corner when the host's floating chrome covers the top-right.
+- No WebGL, a library or style that does not arrive within `readyTimeoutMs`
+  (default 15 s), shows `copy.mapError` with a retry. The region's
+  `data-state` reads `loading`, `ready` or `error`. The host's `overlay` is
+  hidden while the error shows — the error panel carries its own retry.
 
 ## Wiring
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/routing",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "description": "Road routes through an ordered list of stops, with the routing service chosen by host configuration (openrouteservice, OSRM, Google Routes, or your own adapter) and a straight-line fallback when none answers, plus a MapLibre route map for web hosts that draws markers, stops, a planned and a travelled line.",

package/src/react/map-elements.ts

@@ -51,6 +51,58 @@ function span(text: string, style: Partial<CSSStyleDeclaration>): HTMLSpanElemen
   return element;
 }
 
+/** Which side of its pin a marker's tag (pill and tail) is drawn on. */
+export type TagSide = "above" | "below" | "right" | "left";
+
+/** How far the tail reaches from the pill to the pin. */
+export const TAG_TAIL_PX = 9;
+
+/** Each tail's colour, so a side change can redraw it pointing elsewhere. */
+const tailColours = new WeakMap<HTMLElement, string>();
+
+/** The tail under a pill, pointing down at the pin (the `above` side). */
+function tailElement(colour: string): HTMLElement {
+  const tail = span("", { width: "0", height: "0", borderLeft: "7px solid transparent", borderRight: "7px solid transparent", borderTop: `${TAG_TAIL_PX}px solid ${colour}` });
+  tailColours.set(tail, colour);
+  return tail;
+}
+
+/**
+ * Per side: how the frame stacks pill and tail (the tail always at the edge
+ * that meets the pin), and which tail border is filled (the triangle points
+ * the opposite way) versus transparent (its two flanks).
+ */
+const SIDE_LAYOUT: Record<TagSide, { flexDirection: string; filled: Edge; flanks: readonly Edge[] }> = {
+  above: { flexDirection: "column", filled: "top", flanks: ["left", "right"] },
+  below: { flexDirection: "column-reverse", filled: "bottom", flanks: ["left", "right"] },
+  right: { flexDirection: "row-reverse", filled: "right", flanks: ["top", "bottom"] },
+  left: { flexDirection: "row", filled: "left", flanks: ["top", "bottom"] },
+};
+
+type Edge = "top" | "bottom" | "left" | "right";
+
+function tailBorder(edge: Edge, side: TagSide, colour: string): string {
+  const layout = SIDE_LAYOUT[side];
+  if (edge === layout.filled) return `${TAG_TAIL_PX}px solid ${colour}`;
+  return layout.flanks.includes(edge) ? "7px solid transparent" : "0";
+}
+
+/**
+ * Lay a marker's (or group's) tag out on `side` of its pin, in place — the
+ * element is never rebuilt, so keyboard focus survives. The caller re-offsets
+ * the MapLibre marker so the tail's tip stays on the point. `false` when the
+ * element is not a tag this module built (nothing changed).
+ */
+export function setTagSide(element: HTMLElement, side: TagSide): boolean {
+  const tail = element.children[1] as HTMLElement | undefined;
+  const colour = tail ? tailColours.get(tail) : undefined;
+  if (!tail || colour === undefined) return false;
+  element.style.flexDirection = SIDE_LAYOUT[side].flexDirection;
+  for (const edge of ["top", "bottom", "left", "right"] as const) tail.style.setProperty(`border-${edge}`, tailBorder(edge, side, colour));
+  element.dataset.tagSide = side;
+  return true;
+}
+
 /**
  * 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
@@ -84,8 +136,8 @@ export function markerElement(marker: RouteMapMarker, theme: RouteMapTheme, onSe
   });
   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);
+  element.append(bubble, tailElement(marker.color));
+  element.dataset.tagSide = "above";
   return element;
 }
 
@@ -106,8 +158,8 @@ export function groupElement(count: number, copy: RouteMapCopy, theme: RouteMapT
     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);
+  element.append(bubble, tailElement(theme.ink));
+  element.dataset.tagSide = "above";
   return element;
 }
 
@@ -127,6 +179,8 @@ export function stopElement(stop: RouteMapStop, theme: RouteMapTheme): HTMLEleme
     color: stop.variant === "pending" ? theme.ink : theme.paper,
     border: `2px solid ${stop.variant === "done" ? theme.paper : theme.ink}`,
     boxShadow: SHADOW,
+    // Pins are z 2–3; an emphasised stop sits above them, the rest beneath.
+    zIndex: stop.emphasized ? "4" : "1",
   });
   element.setAttribute("role", "img");
   element.setAttribute("aria-label", stop.title);
@@ -134,9 +188,22 @@ export function stopElement(stop: RouteMapStop, theme: RouteMapTheme): HTMLEleme
   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));
+/** How far above its point a place's label sits: label (~26) + stem (46) + dot (8). */
+export const PLACE_LIFT = 80;
+
+export function placeElement(spot: RouteMapPlace, theme: RouteMapTheme, lifted = true): HTMLElement {
+  // The label rides ABOVE a pin-high stem, so a courier standing at the place
+  // (a pin anchored on the same point) never covers it. It stays UNDER the
+  // pins (z 1 against their 2–3), so the stem never crosses a pin's name, and
+  // under any host overlay; clicks pass through to whatever is beneath.
+  const element = span("", { display: "flex", flexDirection: "column", alignItems: "center", pointerEvents: "none", zIndex: "1" });
+  const label = 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) label.appendChild(glyph(spot.icon));
+  label.appendChild(document.createTextNode(spot.label));
+  if (!lifted) {
+    element.append(label);
+    return element;
+  }
+  element.append(label, span("", { width: "2px", height: "46px", background: theme.place }), span("", { width: "8px", height: "8px", borderRadius: "50%", background: theme.place }));
   return element;
 }

package/src/react/maplibre-types.ts

@@ -5,7 +5,7 @@
  */
 
 export interface MapLike {
-  on(event: "load" | "style.load" | "error" | "moveend", listener: () => void): unknown;
+  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;
@@ -21,6 +21,12 @@ 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 {

package/src/react/route-map.tsx

@@ -13,7 +13,7 @@
  * - **Failure is visible, not blank**: the host's error copy and a retry.
  */
 
-import { useRef, type CSSProperties, type JSX } from "react";
+import { useEffect, useRef, useState, type CSSProperties, type JSX } from "react";
 
 import type { RouteMapCopy } from "./copy";
 import type { MapLibreLike } from "./maplibre-types";
@@ -55,9 +55,10 @@ export function buildRouteMap(config: RouteMapConfig): (props: RouteMapProps) =>
       container,
       propsRef,
       onMoveEnd: () => overlaysRef.current?.draw(),
+      onZoomEnd: () => overlaysRef.current?.place(),
       onDispose: () => overlaysRef.current?.clear(),
     });
-    const overlays = useOverlays(handle, propsRef, copy, theme);
+    const overlays = useOverlays({ ...handle, container }, propsRef, copy, theme);
     overlaysRef.current = overlays;
     useOverlaySync(handle.status === "ready", handle, props, overlays, theme);
 
@@ -71,8 +72,7 @@ export function buildRouteMap(config: RouteMapConfig): (props: RouteMapProps) =>
           <MapControls
             copy={copy}
             theme={theme}
-            zoom={props.controls?.zoom ?? true}
-            fit={props.controls?.fit ?? true}
+            {...controlsOf(props)}
             onZoomIn={() => handle.mapRef.current?.zoomIn()}
             onZoomOut={() => handle.mapRef.current?.zoomOut()}
             onFit={() => {
@@ -81,27 +81,55 @@ export function buildRouteMap(config: RouteMapConfig): (props: RouteMapProps) =>
             }}
           />
         )}
-        {props.overlay ? <div style={{ position: "absolute", left: 12, right: 12, bottom: 28, zIndex: 2 }}>{props.overlay}</div> : null}
-        <small style={{ position: "absolute", right: 6, bottom: 4, fontSize: 10, color: theme.ink, background: theme.paper, padding: "0 4px", borderRadius: 4, zIndex: 2 }}>{copy.attribution}</small>
+        {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, onZoomIn, onZoomOut, onFit }: ControlsProps): JSX.Element | null {
+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, right: 12, display: "flex", flexDirection: "column", gap: 8, zIndex: 2 }}>
+    <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)}>

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

@@ -29,6 +29,11 @@ export interface RouteMapStop {
   /** 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 {
@@ -65,15 +70,52 @@ export interface RouteMapProps {
   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;
-  controls?: { zoom?: boolean; fit?: boolean };
+  /**
+   * 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;
 }
 

package/src/react/use-map.ts

@@ -33,6 +33,8 @@ interface MapSetup {
   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;
 }
@@ -87,6 +89,7 @@ export function useMapInstance(setup: MapSetup): MapHandle {
         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");

package/src/react/use-overlays.ts

@@ -13,27 +13,38 @@
  * 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 } from "react";
+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, placeElement, stopElement } from "./map-elements";
+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 {
+interface Drawn extends Placed {
   marker: MarkerLike;
   element: HTMLElement;
   signature: string;
@@ -44,11 +55,12 @@ interface Wanted {
   signature: string;
   position: LngLat;
   anchor: "bottom" | "center";
+  role: Placed["role"];
   build: () => HTMLElement;
 }
 
 export function useOverlays(
-  handle: Pick<MapHandle, "mapRef" | "libRef">,
+  handle: Pick<MapHandle, "mapRef" | "libRef"> & { container: RefObject<HTMLElement | null> },
   propsRef: MutableRefObject<RouteMapProps>,
   copy: RouteMapCopy,
   theme: RouteMapTheme,
@@ -75,10 +87,11 @@ export function useOverlays(
     actions.current.clear();
     const out: Wanted[] = [];
     for (const spot of (props.places ?? []).filter((item) => isValidPoint(item.position))) {
-      out.push({ key: `p:${spot.id}`, signature: JSON.stringify([spot.label, spot.icon]), position: spot.position, anchor: "bottom", build: () => placeElement(spot, theme) });
+      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]), position: stop.position, anchor: "center", build: () => stopElement(stop, theme) });
+      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));
@@ -90,31 +103,77 @@ export function useOverlays(
     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", build: () => markerElement(marker, theme, act) };
+    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", build: () => groupElement(group.length, copy, theme, () => actions.current.get(key)?.()) };
+    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 controls = propsRef.current.controls;
-    const right = (controls?.zoom ?? true) || (controls?.fit ?? true) ? 76 : 40;
     const bounds = boundsOf(pointsOf(propsRef.current));
-    if (bounds) handle.mapRef.current?.fitBounds(bounds, { padding: { top: 40, bottom: 48, left: 40, right }, maxZoom: 16, duration: 0 });
+    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, clear, fitAll };
+  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;
@@ -132,12 +191,13 @@ function reconcile(drawn: Map<string, Drawn>, next: readonly Wanted[], place: Pl
     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 });
+    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();
   }
 }
@@ -154,9 +214,14 @@ export function useOverlaySync(ready: boolean, handle: Pick<MapHandle, "mapRef">
 
   useEffect(() => {
     if (ready) overlays.draw();
-  }, [ready, props.markers, props.stops, props.places]);
+  }, [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]);
 }