@12-apps/ui 6.98.1 → 6.99.0

package/dist/types/components/data-display/RegionMap/RegionMapPin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegionMapPin.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/RegionMap/RegionMapPin.tsx"],"names":[],"mappings":"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"}

package/dist/types/components/data-display/RegionMap/index.d.ts

@@ -1,6 +1,7 @@
 export { RegionMap } from './RegionMap';
 export { decodePolyline, hitRegion, projectionAt } from './RegionMap.helpers';
+export { latLngAt, scaleMetres } from './RegionMapPin';
 export { boundsOfRings, regionMapView } from './RegionMap.view';
 export type { AreaGeometry, PlaneBox, PlanePoint, PlaneRegion, Projection } from './RegionMap.helpers';
-export type { RegionMapBounds, RegionMapCircle, RegionMapCopy, RegionMapLayer, RegionMapListMode, RegionMapListSort, RegionMapPoint, RegionMapProps, RegionMapReach, RegionMapRegion, RegionMapRing, } from './RegionMap.types';
+export type { RegionMapBounds, RegionMapCircle, RegionMapCenter, RegionMapCopy, RegionMapDot, RegionMapGhost, RegionMapLayer, RegionMapListMode, RegionMapListSort, RegionMapPin, RegionMapPoint, RegionMapProps, RegionMapReach, RegionMapRegion, RegionMapRing, } from './RegionMap.types';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/components/data-display/RegionMap/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/RegionMap/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvG,YAAY,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/RegionMap/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvG,YAAY,EACV,eAAe,EACf,eAAe,EACf,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.98.1",
+  "version": "6.99.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",

package/src/components/data-display/RegionMap/RegionMap.helpers.ts

@@ -9,7 +9,7 @@ import type { RegionMapPoint, RegionMapRegion, RegionMapRing } from './RegionMap
  */
 
 /** Metres per degree of latitude on the mean sphere. */
-const METRES_PER_DEGREE = 111_195;
+export const METRES_PER_DEGREE = 111_195;
 
 /** A projected point, metres east (`x`) and south (`y`) of the centre. */
 export interface PlanePoint {

package/src/components/data-display/RegionMap/RegionMap.md

@@ -102,7 +102,10 @@ drawing means copying its view math and losing its frame. So:
 |---|---|---|---|
 | `regions` | `readonly RegionMapRegion[]` | — | the areas; drawn when any part is in view |
 | `center` | `{ latitude, longitude } \| null` | — | centre, dot and circles; `null` centres on the areas, no dot |
-| `circles` | `readonly { radiusMetres }[]` | `[]` | dashed circles; the view fits the largest |
+| `circles` | `readonly { radiusMetres }[]` | `[]` | dashed circles; the view fits the largest (solid, around the pin, when there is a `pin`) |
+| `pin` | `{ at, label, ariaLabel, onMove?, onDrop, stepMetres?, disabled? }` | — | the centre as a pin the viewer drags or nudges with the arrow keys; the view stays on `center` |
+| `ghost` | `{ at, radiusMetres }` | — | a dashed ring and dot where the circles stood, a dashed line to the pin |
+| `dots` | `readonly { id, at, filled }[]` | — | small points, filled or hollow, not tappable |
 | `reach` | `{ radiusMetres } \| { bounds: { south, west, north, east } }` | — | an extent the view must also fit (margin on top) |
 | `overlay` | `(layer: { view, projection }) => ReactNode` | — | a host layer inside the SVG, under the circles, tap-transparent |
 | `onToggle` | `(id: string) => void` | — | a tap or a list press; omit for read-only |
@@ -132,7 +135,21 @@ drawing means copying its view math and losing its frame. So:
 
 `mapLabel`, `legendExcluded`, `legendCircle(radiusMetres)`, `legendCenter`,
 `listLabel`, `showList(count)` (the count of LISTED areas), `hideList`, and
-`rowState: { excluded, outside }` — a row's state in words, for a screen reader.
+`rowState: { excluded, outside }` — a row's state in words, for a screen reader;
+optional `scale(metres)` — a scale bar's length ("1 km"), shown only when given.
+
+### The movable centre (`pin`)
+
+A store's point placed 200 m off by a geocoder is corrected by dragging it
+where the circles are measured from. So the pin moves and the VIEW does not:
+the areas never slide under a dragging finger. The pin is HTML over the
+drawing (a 44×48 button, `touch-action: none`), carrying `data-region-pin` so
+a host that zooms the drawing's layers can move it with them. A drag is
+captured, clamped inside the view, and kept from the host's own listeners on
+the drawing; each arrow key moves it `stepMetres` (50). Moves are reported
+(`onMove`, `onDrop`), never applied: the host passes the new `at` back.
+`latLngAt(center, planePoint)` is the projection's inverse for a host that
+needs it.
 
 ## Helpers
 

package/src/components/data-display/RegionMap/RegionMap.tsx

@@ -39,6 +39,9 @@ export function RegionMap({
   regions,
   center,
   circles,
+  pin,
+  ghost,
+  dots,
   reach,
   overlay,
   onToggle,
@@ -62,6 +65,7 @@ export function RegionMap({
             model={{ ...model, view }}
             overlay={overlay}
             showCenter={center !== null}
+            moving={center === null ? undefined : { center, pin, ghost, dots, copy }}
             highlightedIds={highlightedIds}
             maxHeight={maxHeight}
             label={copy.mapLabel}

package/src/components/data-display/RegionMap/RegionMap.types.ts

@@ -49,6 +49,46 @@ export interface RegionMapRegion {
   detail?: string;
 }
 
+/** A latitude/longitude pair, by name. */
+export interface RegionMapCenter {
+  latitude: number;
+  longitude: number;
+}
+
+/**
+ * The centre as a pin the viewer moves (a store's door). The VIEW stays on
+ * `center`; the pin, and the circles with it, are drawn at `at`. Moves are
+ * reported, never applied: the host passes the new `at` back.
+ */
+export interface RegionMapPin {
+  at: RegionMapCenter;
+  /** Printed beside the pin, e.g. "Store". */
+  label: string;
+  /** The pin's accessible name, e.g. "Store pin. Drag it, or use the arrow keys, to move it". */
+  ariaLabel: string;
+  /** Every point while a pointer drags it. */
+  onMove?: (at: RegionMapCenter) => void;
+  /** Where it came to rest: the pointer let go, or an arrow key moved it. */
+  onDrop: (at: RegionMapCenter) => void;
+  /** Metres one arrow key moves it. Default 50. */
+  stepMetres?: number;
+  /** Held in place (a save in flight). */
+  disabled?: boolean;
+}
+
+/** Where the pin's outermost circle stood: a dashed ring of `radiusMetres` and a dashed dot at `at`. */
+export interface RegionMapGhost {
+  at: RegionMapCenter;
+  radiusMetres: number;
+}
+
+/** A small point on the map (an address), filled or hollow. Not tappable. */
+export interface RegionMapDot {
+  id: string;
+  at: RegionMapCenter;
+  filled: boolean;
+}
+
 /** A circle drawn around the centre, e.g. a delivery ring. */
 export interface RegionMapCircle {
   radiusMetres: number;
@@ -99,6 +139,8 @@ export interface RegionMapCopy {
    * `outside` one (faded). Neither is shown; the row's look carries it.
    */
   rowState: { excluded: string; outside: string };
+  /** A scale bar's length, e.g. "1 km". Omit for no scale bar. */
+  scale?: (metres: number) => string;
 }
 
 /** The order of the list: as given (e.g. nearest first), or by name. */
@@ -120,8 +162,14 @@ export interface RegionMapProps {
    * `null` with no regions renders NOTHING rather than a map of `0, 0`.
    */
   center: { latitude: number; longitude: number } | null;
-  /** Circles around the centre; the view fits the largest. */
+  /** Circles around the centre (around `pin.at` when there is a pin); the view fits the largest. */
   circles?: readonly RegionMapCircle[];
+  /** The centre as a draggable pin; it replaces the centre's dot, and the circles follow it. */
+  pin?: RegionMapPin;
+  /** A dashed ring and dot where the circles stood (drawn with a `pin`). */
+  ghost?: RegionMapGhost;
+  /** Small points, filled or hollow, over the areas and under the pin. */
+  dots?: readonly RegionMapDot[];
   /**
    * An extent the view must ALSO fit, before its margin — something the host
    * draws past the largest circle. With circles the view stays centred on the

package/src/components/data-display/RegionMap/RegionMapDrawing.tsx

@@ -9,12 +9,16 @@ import { labelPosition, type AreaGeometry, type DrawnRegion, type PlaneBox } fro
 import type { RegionMapModel } from './RegionMap.hooks';
 import { labelOrder, placeLabels } from './RegionMap.labels';
 import type { RegionMapLayer } from './RegionMap.types';
+import type { Moving } from './RegionMapPin';
+import { PinOverlay, PinShapes } from './RegionMapPin';
 
 export interface RegionMapDrawingProps {
   model: RegionMapModel & { view: PlaneBox };
   /** The host's layer, drawn inside the SVG under the circles (`RegionMapProps.overlay`). */
   overlay?: (layer: RegionMapLayer) => React.ReactNode;
   showCenter: boolean;
+  /** The movable centre and what is drawn with it (`RegionMapProps.pin`, `ghost`, `dots`). */
+  moving?: Moving;
   highlightedIds: readonly string[];
   maxHeight: string | undefined;
   label: string;
@@ -33,17 +37,8 @@ export interface RegionMapDrawingProps {
  * The base areas are a memoised layer: a toggle changes `excluded`, not the
  * geometry, so only the hatch, highlight and label layers re-render.
  */
-export function RegionMapDrawing({
-  model,
-  overlay,
-  showCenter,
-  highlightedIds,
-  maxHeight,
-  label,
-  tappable,
-  testId,
-  theme,
-}: RegionMapDrawingProps): React.JSX.Element {
+export function RegionMapDrawing(props: RegionMapDrawingProps): React.JSX.Element {
+  const { model, overlay, showCenter, moving, highlightedIds, maxHeight, label, tappable, testId, theme } = props;
   const hatchId = `${React.useId().replace(/:/g, '')}-hatch`;
   const { view, drawn } = model;
   const wanted = new Set(highlightedIds);
@@ -52,6 +47,7 @@ export function RegionMapDrawing({
   // claim their place in, so a collision hides the less important one.
   const labelled = labelOrder(drawn.filter((d) => d.excluded || wanted.has(d.id)), wanted);
   const boxRef = React.useRef<HTMLDivElement>(null);
+  const svgRef = React.useRef<SVGSVGElement>(null);
   useLabelPlacement(boxRef, labelled.map((d) => d.id).join('|'), remPx(theme, 4));
   const base = drawn.map((d) => ({ id: d.id, name: d.name, geometry: d.geometry, outside: d.outside === true }));
   return (
@@ -72,6 +68,7 @@ export function RegionMapDrawing({
       ref={boxRef}
     >
       <svg
+        ref={svgRef}
         viewBox={`${view.minX} ${view.minY} ${view.spanX} ${view.spanY}`}
         role="img"
         aria-label={label}
@@ -89,9 +86,9 @@ export function RegionMapDrawing({
             {overlay({ view, projection: model.projection })}
           </g>
         )}
-        <Circles radii={model.radii} theme={theme} />
+        <PinShapes model={model} moving={moving} testId={testId} theme={theme} fallback={<Circles radii={model.radii} theme={theme} />} />
         <Highlights areas={highlighted} testId={testId} theme={theme} />
-        {showCenter && (
+        {showCenter && !moving?.pin && (
           <circle
             cx={0}
             cy={0}
@@ -108,6 +105,7 @@ export function RegionMapDrawing({
       {labelled.map((d) => (
         <AreaLabel key={`l-${d.id}`} area={d} view={view} testId={testId} theme={theme} />
       ))}
+      <PinOverlay model={model} moving={moving} svgRef={svgRef} testId={testId} theme={theme} />
     </Box>
   );
 }

package/src/components/data-display/RegionMap/RegionMapPin.tsx

@@ -0,0 +1,388 @@
+import Box from '@mui/material/Box/index.js';
+import { alpha, type Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { rem } from '../../../tokens/relative';
+
+import { METRES_PER_DEGREE, type PlaneBox, type PlanePoint, type Projection } from './RegionMap.helpers';
+import type { RegionMapModel } from './RegionMap.hooks';
+import type { RegionMapCenter, RegionMapCopy, RegionMapDot, RegionMapGhost, RegionMapPin } from './RegionMap.types';
+
+/**
+ * The movable centre of a `RegionMap` (`pin`, `ghost`, `dots`): a pin the
+ * viewer drags with a mouse or one finger, or focuses and nudges with the
+ * arrow keys, while the VIEW stays where `center` put it — so the areas never
+ * slide under a dragging finger. The circles follow the pin; a dashed ring
+ * and dot stay at `ghost`; `dots` are small points (filled or hollow).
+ *
+ * The pin is HTML over the drawing, at its point by percent like the labels,
+ * carrying `data-region-pin` so a host that zooms the drawing's layers can
+ * move it with them. Its moves are reported, never applied: the host passes
+ * the new point back.
+ */
+
+/** The movable centre and what is drawn with it, as the drawing receives it. */
+export interface Moving {
+  center: RegionMapCenter;
+  pin?: RegionMapPin;
+  ghost?: RegionMapGhost;
+  dots?: readonly RegionMapDot[];
+  copy: RegionMapCopy;
+}
+
+type DrawnModel = Pick<RegionMapModel, 'projection' | 'radii'> & { view: PlaneBox };
+
+/**
+ * What the movable centre draws inside the SVG: the circles around the pin
+ * (else `fallback`, the centre's own circles), the ghost, and the dots.
+ */
+export function PinShapes({ model, moving, testId, theme, fallback }: { model: DrawnModel; moving: Moving | undefined; testId: string; theme: Theme; fallback: React.ReactNode }): React.JSX.Element {
+  const { projection, view } = model;
+  if (!moving || !projection) return <>{fallback}</>;
+  const pinAt = moving.pin ? projection.project([moving.pin.at.latitude, moving.pin.at.longitude]) : null;
+  return (
+    <>
+      {pinAt ? <PinCircles at={pinAt} radii={model.radii} theme={theme} /> : fallback}
+      {pinAt && moving.ghost ? <GhostShapes ghost={moving.ghost} pinAt={pinAt} projection={projection} view={view} testId={testId} theme={theme} /> : null}
+      {moving.dots ? <Dots dots={moving.dots} projection={projection} view={view} testId={testId} theme={theme} /> : null}
+    </>
+  );
+}
+
+/** What the movable centre draws over the SVG, in HTML: the pin and the scale bar. */
+export function PinOverlay({
+  model,
+  moving,
+  svgRef,
+  testId,
+  theme,
+}: {
+  model: DrawnModel;
+  moving: Moving | undefined;
+  svgRef: React.RefObject<SVGSVGElement | null>;
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element | null {
+  if (!moving || !model.projection) return null;
+  return (
+    <>
+      {moving.pin ? <PinMarker pin={moving.pin} center={moving.center} projection={model.projection} view={model.view} svgRef={svgRef} testId={testId} theme={theme} /> : null}
+      <ScaleBar view={model.view} copy={moving.copy} svgRef={svgRef} testId={testId} theme={theme} />
+    </>
+  );
+}
+
+/** The flat projection's inverse around `center` — it is linear. */
+export function latLngAt(center: RegionMapCenter, point: PlanePoint): RegionMapCenter {
+  const kx = METRES_PER_DEGREE * Math.cos((center.latitude * Math.PI) / 180);
+  return { latitude: center.latitude - point.y / METRES_PER_DEGREE, longitude: center.longitude + point.x / kx };
+}
+
+/** A point of the plane as fractions of the view (0..1 across, 0..1 down). */
+function fractionOf(view: PlaneBox, point: PlanePoint): { x: number; y: number } {
+  return { x: (point.x - view.minX) / view.spanX, y: (point.y - view.minY) / view.spanY };
+}
+
+/** Keep a fraction inside the view, a hair in from its edge (the mock's clamp). */
+const clampFraction = (value: number): number => Math.min(0.995, Math.max(0.005, value));
+
+/** A plane point kept inside the view by the same clamp a drag gets. */
+function clampToView(view: PlaneBox, point: PlanePoint): PlanePoint {
+  const at = fractionOf(view, point);
+  return { x: view.minX + clampFraction(at.x) * view.spanX, y: view.minY + clampFraction(at.y) * view.spanY };
+}
+
+/** Arrow keys, as metres east and north per press. */
+const ARROWS: Record<string, [number, number]> = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, 1], ArrowDown: [0, -1] };
+
+/** One arrow key: 50 m unless the host says otherwise. */
+const DEFAULT_STEP_METRES = 50;
+
+interface PinLayerProps {
+  pin: RegionMapPin;
+  center: RegionMapCenter;
+  projection: Projection;
+  view: PlaneBox;
+  /** The drawing's SVG, whose on-screen box maps a pointer to the plane (zoomed or not). */
+  svgRef: React.RefObject<SVGSVGElement | null>;
+  testId: string;
+  theme: Theme;
+}
+
+/** The draggable pin, as HTML over the drawing. */
+export function PinMarker({ pin, center, projection, view, svgRef, testId, theme }: PinLayerProps): React.JSX.Element {
+  const ref = React.useRef<HTMLDivElement>(null);
+  const live = React.useRef({ pin, center, view });
+  live.current = { pin, center, view };
+  usePinDrag(ref, svgRef, live);
+  const at = fractionOf(view, projection.project([pin.at.latitude, pin.at.longitude]));
+  const onKeyDown = (event: React.KeyboardEvent): void => {
+    const arrow = ARROWS[event.key];
+    if (!arrow || pin.disabled) return;
+    event.preventDefault();
+    const step = pin.stepMetres ?? DEFAULT_STEP_METRES;
+    const plane = projection.project([pin.at.latitude, pin.at.longitude]);
+    const next = latLngAt(center, clampToView(view, { x: plane.x + arrow[0] * step, y: plane.y - arrow[1] * step }));
+    pin.onMove?.(next);
+    pin.onDrop(next);
+  };
+  return (
+    <Box
+      ref={ref}
+      role="button"
+      tabIndex={pin.disabled ? -1 : 0}
+      aria-label={pin.ariaLabel}
+      aria-disabled={pin.disabled || undefined}
+      onKeyDown={onKeyDown}
+      data-testid={`${testId}-pin`}
+      data-region-pin=""
+      style={{ left: `${(at.x * 100).toFixed(3)}%`, top: `${(at.y * 100).toFixed(3)}%` }}
+      sx={{
+        position: 'absolute',
+        transform: 'translate(-50%, -100%)',
+        width: rem(theme, 44),
+        height: rem(theme, 48),
+        display: 'flex',
+        alignItems: 'flex-end',
+        justifyContent: 'center',
+        cursor: pin.disabled ? 'default' : 'grab',
+        touchAction: 'none',
+        zIndex: 2,
+        borderRadius: 1,
+        '&:focus-visible': { outline: `${rem(theme, 2)} solid`, outlineColor: 'primary.main', outlineOffset: rem(theme, 2) },
+      }}
+    >
+      <Box component="svg" viewBox="0 0 32 42" aria-hidden="true" sx={{ width: rem(theme, 32), height: rem(theme, 42) }}>
+        <path
+          d="M16 41C16 41 3 25 3 15.5A13 13 0 1 1 29 15.5C29 25 16 41 16 41Z"
+          fill={theme.palette.primary.main}
+          stroke={theme.palette.background.paper}
+          strokeWidth={2}
+        />
+        <circle cx="16" cy="15.5" r="5" fill={theme.palette.background.paper} />
+      </Box>
+      <Box
+        component="span"
+        aria-hidden
+        sx={{
+          position: 'absolute',
+          left: '88%',
+          top: 0,
+          px: 0.75,
+          borderRadius: 0.5,
+          border: 1,
+          borderColor: 'divider',
+          bgcolor: 'background.paper',
+          color: 'text.primary',
+          fontSize: rem(theme, 12),
+          fontWeight: 600,
+          whiteSpace: 'nowrap',
+          pointerEvents: 'none',
+        }}
+      >
+        {pin.label}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * The pointer drag: native listeners on the pin, so a host's own listeners on
+ * the drawing (a pan, a tap) never see the press; captured, so a finger that
+ * leaves the pin keeps dragging it; clamped inside the view.
+ */
+function usePinDrag(
+  ref: React.RefObject<HTMLDivElement | null>,
+  svgRef: React.RefObject<SVGSVGElement | null>,
+  live: React.RefObject<{ pin: RegionMapPin; center: RegionMapCenter; view: PlaneBox }>,
+): void {
+  React.useEffect(() => {
+    const element = ref.current;
+    if (!element) return undefined;
+    let dragging: number | null = null;
+    // Where the last move put the pin: a cancelled gesture (a browser may
+    // report 0,0 for it) rests there rather than jumping to the corner.
+    let last: RegionMapCenter | null = null;
+    const pointAt = (event: PointerEvent): RegionMapCenter | null => {
+      const box = svgRef.current?.getBoundingClientRect();
+      if (!box || box.width === 0 || box.height === 0) return null;
+      const { view, center } = live.current;
+      if (!Number.isFinite(event.clientX) || !Number.isFinite(event.clientY)) return null;
+      const fx = clampFraction((event.clientX - box.left) / box.width);
+      const fy = clampFraction((event.clientY - box.top) / box.height);
+      return latLngAt(center, { x: view.minX + fx * view.spanX, y: view.minY + fy * view.spanY });
+    };
+    const down = (event: PointerEvent): void => {
+      event.stopPropagation();
+      if (live.current.pin.disabled) return;
+      event.preventDefault();
+      dragging = event.pointerId;
+      last = null;
+      element.setPointerCapture?.(event.pointerId);
+    };
+    const move = (event: PointerEvent): void => {
+      if (dragging !== event.pointerId) return;
+      event.stopPropagation();
+      const at = pointAt(event);
+      if (!at) return;
+      last = at;
+      live.current.pin.onMove?.(at);
+    };
+    const up = (event: PointerEvent): void => {
+      if (dragging !== event.pointerId) return;
+      event.stopPropagation();
+      dragging = null;
+      const at = event.type === 'pointercancel' ? last : (pointAt(event) ?? last);
+      if (at) live.current.pin.onDrop(at);
+    };
+    // A click that ends a drag is the drag's, not a tap on the area under it.
+    const click = (event: MouseEvent): void => event.stopPropagation();
+    element.addEventListener('pointerdown', down);
+    element.addEventListener('pointermove', move);
+    element.addEventListener('pointerup', up);
+    element.addEventListener('pointercancel', up);
+    element.addEventListener('click', click);
+    return () => {
+      element.removeEventListener('pointerdown', down);
+      element.removeEventListener('pointermove', move);
+      element.removeEventListener('pointerup', up);
+      element.removeEventListener('pointercancel', up);
+      element.removeEventListener('click', click);
+    };
+  }, [ref, svgRef, live]);
+}
+
+/** The circles around the pin: solid in the primary colour, faintly filled. */
+export function PinCircles({ at, radii, theme }: { at: PlanePoint; radii: readonly number[]; theme: Theme }): React.JSX.Element {
+  return (
+    <>
+      {radii.map((radius) => (
+        <circle
+          key={radius}
+          cx={at.x}
+          cy={at.y}
+          r={radius}
+          fill={alpha(theme.palette.primary.main, 0.06)}
+          stroke={theme.palette.primary.main}
+          strokeWidth={2.25}
+          vectorEffect="non-scaling-stroke"
+          pointerEvents="none"
+        />
+      ))}
+    </>
+  );
+}
+
+/** Where the circles stood: a dashed ring and dot at `ghost`, and a dashed line from it to the pin. */
+export function GhostShapes({
+  ghost,
+  pinAt,
+  projection,
+  view,
+  testId,
+  theme,
+}: {
+  ghost: RegionMapGhost;
+  pinAt: PlanePoint;
+  projection: Projection;
+  view: PlaneBox;
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element {
+  const at = projection.project([ghost.at.latitude, ghost.at.longitude]);
+  const stroke = theme.palette.text.secondary;
+  const common = { fill: 'none', stroke, vectorEffect: 'non-scaling-stroke', pointerEvents: 'none' } as const;
+  return (
+    <g data-testid={`${testId}-ghost`}>
+      <circle cx={at.x} cy={at.y} r={ghost.radiusMetres} strokeWidth={1.5} strokeDasharray="6 5" {...common} />
+      <line x1={at.x} y1={at.y} x2={pinAt.x} y2={pinAt.y} strokeWidth={1.5} strokeDasharray="4 4" {...common} />
+      <circle cx={at.x} cy={at.y} r={view.spanX / 110} strokeWidth={2} strokeDasharray="3 2" {...common} fill={alpha(theme.palette.background.paper, 0.7)} />
+    </g>
+  );
+}
+
+/** The dots: filled with the ink, or hollow (paper with an ink ring). */
+export function Dots({ dots, projection, view, testId, theme }: { dots: readonly RegionMapDot[]; projection: Projection; view: PlaneBox; testId: string; theme: Theme }): React.JSX.Element {
+  return (
+    <g data-testid={`${testId}-dots`}>
+      {dots.map((dot) => {
+        const at = projection.project([dot.at.latitude, dot.at.longitude]);
+        return (
+          <circle
+            key={dot.id}
+            cx={at.x}
+            cy={at.y}
+            r={view.spanX / 150}
+            fill={dot.filled ? theme.palette.text.primary : theme.palette.background.paper}
+            stroke={theme.palette.text.primary}
+            strokeWidth={2}
+            vectorEffect="non-scaling-stroke"
+            pointerEvents="none"
+            data-filled={dot.filled ? 'true' : 'false'}
+          />
+        );
+      })}
+    </g>
+  );
+}
+
+/** Nice lengths a scale bar may take, in metres. */
+const SCALE_STEPS = [50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 50000];
+
+/** The longest nice length that fits in a quarter of the drawing's width. */
+export function scaleMetres(view: PlaneBox): number {
+  const quarter = view.spanX / 4;
+  return SCALE_STEPS.filter((step) => step <= quarter).at(-1) ?? SCALE_STEPS[0]!;
+}
+
+/**
+ * A scale bar, bottom-left, when the host gives `copy.scale`. It reads what is
+ * on screen: a host that zooms the drawing's layers (a CSS scale on the SVG)
+ * shows fewer metres per pixel, so after every render the bar compares the
+ * SVG's drawn width with its laid-out width — both off the SVG itself — and
+ * spans the drawing's own width, so its share of it is a share of the view.
+ */
+export function ScaleBar({
+  view,
+  copy,
+  svgRef,
+  testId,
+  theme,
+}: {
+  view: PlaneBox;
+  copy: RegionMapCopy;
+  svgRef: React.RefObject<SVGSVGElement | null>;
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element | null {
+  // What the drawing shows on screen: its laid-out width, and its width as
+  // drawn (a host's CSS scale on the SVG), both read off the SVG itself.
+  const [screen, setScreen] = React.useState({ laidOut: 0, drawn: 0 });
+  const wanted = copy.scale !== undefined;
+  React.useLayoutEffect(() => {
+    if (!wanted) return;
+    const svg = svgRef.current;
+    const next = { laidOut: svg?.clientWidth ?? 0, drawn: svg?.getBoundingClientRect().width ?? 0 };
+    if (next.laidOut !== screen.laidOut || Math.abs(next.drawn - screen.drawn) > 0.5) setScreen(next);
+  });
+  if (!copy.scale) return null;
+  const zoom = screen.laidOut > 0 && screen.drawn > 0 ? screen.drawn / screen.laidOut : 1;
+  const metres = scaleMetres({ ...view, spanX: view.spanX / zoom });
+  // The bar's share of the drawing's width: metres on screen over the metres the width shows.
+  const share = (metres * zoom) / view.spanX;
+  return (
+    <Box
+      data-testid={`${testId}-scale`}
+      aria-hidden
+      sx={{ position: 'absolute', left: 0, right: 0, bottom: rem(theme, 10), pointerEvents: 'none', zIndex: 1 }}
+    >
+      <Box component="span" sx={{ display: 'block', ml: rem(theme, 10), fontSize: rem(theme, 11), color: 'text.secondary' }}>
+        {copy.scale(metres)}
+      </Box>
+      <Box
+        component="span"
+        sx={{ display: 'block', height: rem(theme, 4), ml: rem(theme, 10), width: `${(share * 100).toFixed(2)}%`, borderStyle: 'solid', borderWidth: `0 ${rem(theme, 1.5)} ${rem(theme, 1.5)}`, borderColor: 'text.secondary' }}
+      />
+    </Box>
+  );
+}

package/src/components/data-display/RegionMap/index.ts

@@ -1,14 +1,19 @@
 export { RegionMap } from './RegionMap';
 export { decodePolyline, hitRegion, projectionAt } from './RegionMap.helpers';
+export { latLngAt, scaleMetres } from './RegionMapPin';
 export { boundsOfRings, regionMapView } from './RegionMap.view';
 export type { AreaGeometry, PlaneBox, PlanePoint, PlaneRegion, Projection } from './RegionMap.helpers';
 export type {
   RegionMapBounds,
   RegionMapCircle,
+  RegionMapCenter,
   RegionMapCopy,
+  RegionMapDot,
+  RegionMapGhost,
   RegionMapLayer,
   RegionMapListMode,
   RegionMapListSort,
+  RegionMapPin,
   RegionMapPoint,
   RegionMapProps,
   RegionMapReach,

package/dist/chunk-3CXRHRGE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/data-display/RegionMap/RegionMap.tsx"],"sourcesContent":["import Box from '@mui/material/Box/index.js';\nimport { useTheme } from '@mui/material/styles/index.js';\nimport React from 'react';\n\nimport { useRegionMap } from './RegionMap.hooks';\nimport type { RegionMapProps } from './RegionMap.types';\nimport { RegionMapDrawing } from './RegionMapDrawing';\nimport { RegionMapLegend } from './RegionMapLegend';\nimport { RegionMapList } from './RegionMapList';\n\n/** One empty list, so the default does not change identity per render. */\nconst NO_IDS: readonly string[] = [];\n\n/**\n * A hand-drawn map of named areas around a centre; a tap toggles an area.\n *\n * Drawn as inline SVG over a plain background — no tile server, no API key,\n * nothing fetched — because the question it answers is \"which of THESE areas\",\n * not \"what is the street called\". Four choices shape it:\n *\n * - **The list is the accessible way in.** The drawing is one `role=\"img\"`\n *   with a name; its areas are not tab stops (dozens of them, many too small to\n *   tap on a phone). Every area is also a toggle button in the list beneath,\n *   with `aria-pressed`, which is what a keyboard and a screen reader use —\n *   and what reaches a sliver no finger can.\n * - **Excluded is hatched AND named, never only coloured,** and never in the\n *   error colour: leaving an area out is a choice, not a failure.\n * - **The hit test is ours, not only the browser's.** A mouse click on a path\n *   is that path. A finger's tap takes the SMALLEST area within a few pixels'\n *   worth of metres (`hitRegion`), so a sliver beside a big area can be hit\n *   from the map; one too thin even for that is still on the list.\n * - **The host can draw inside it.** `reach` widens the view past the largest\n *   circle and `overlay` draws a layer in the SVG at the map's own projection,\n *   tap-transparent; `regionMapView` gives the same view to HTML laid over it.\n * - **A toggle is cheap.** Geometry is projected once per `rings` identity,\n *   and the base layer is memoised, so a tap re-renders the hatch and labels.\n */\nexport function RegionMap({\n  regions,\n  center,\n  circles,\n  reach,\n  overlay,\n  onToggle,\n  highlightedIds = NO_IDS,\n  copy,\n  listMode = 'collapsed',\n  listSort = 'given',\n  maxHeight,\n  className,\n  dataTestId = 'region-map',\n}: RegionMapProps): React.JSX.Element | null {\n  const theme = useTheme();\n  const model = useRegionMap({ regions, center, circles, reach, onToggle });\n  const { view } = model;\n  if (view === null && regions.length === 0) return null;\n  return (\n    <Box className={className} data-testid={dataTestId}>\n      {view && (\n        <>\n          <RegionMapDrawing\n            model={{ ...model, view }}\n            overlay={overlay}\n            showCenter={center !== null}\n            highlightedIds={highlightedIds}\n            maxHeight={maxHeight}\n            label={copy.mapLabel}\n            tappable={onToggle !== undefined}\n            testId={dataTestId}\n            theme={theme}\n          />\n          <RegionMapLegend\n            copy={copy}\n            outermostMetres={model.outermostMetres}\n            showCenter={center !== null}\n            theme={theme}\n            testId={dataTestId}\n          />\n        </>\n      )}\n      {listMode !== 'none' && (\n        <RegionMapList\n          regions={regions}\n          copy={copy}\n          mode={listMode}\n          sort={listSort}\n          onToggle={onToggle}\n          testId={dataTestId}\n          theme={theme}\n        />\n      )}\n    </Box>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA,OAAO,SAAS;AAChB,SAAS,gBAAgB;AA0DjB,mBACE,KADF;AAhDR,IAAM,SAA4B,CAAC;AA0B5B,SAAS,UAAU;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB;AAAA,EACA,WAAW;AAAA,EACX,WAAW;AAAA,EACX;AAAA,EACA;AAAA,EACA,aAAa;AACf,GAA6C;AAC3C,QAAM,QAAQ,SAAS;AACvB,QAAM,QAAQ,aAAa,EAAE,SAAS,QAAQ,SAAS,OAAO,SAAS,CAAC;AACxE,QAAM,EAAE,KAAK,IAAI;AACjB,MAAI,SAAS,QAAQ,QAAQ,WAAW,EAAG,QAAO;AAClD,SACE,qBAAC,OAAI,WAAsB,eAAa,YACrC;AAAA,YACC,iCACE;AAAA;AAAA,QAAC;AAAA;AAAA,UACC,OAAO,EAAE,GAAG,OAAO,KAAK;AAAA,UACxB;AAAA,UACA,YAAY,WAAW;AAAA,UACvB;AAAA,UACA;AAAA,UACA,OAAO,KAAK;AAAA,UACZ,UAAU,aAAa;AAAA,UACvB,QAAQ;AAAA,UACR;AAAA;AAAA,MACF;AAAA,MACA;AAAA,QAAC;AAAA;AAAA,UACC;AAAA,UACA,iBAAiB,MAAM;AAAA,UACvB,YAAY,WAAW;AAAA,UACvB;AAAA,UACA,QAAQ;AAAA;AAAA,MACV;AAAA,OACF;AAAA,IAED,aAAa,UACZ;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN,MAAM;AAAA,QACN;AAAA,QACA,QAAQ;AAAA,QACR;AAAA;AAAA,IACF;AAAA,KAEJ;AAEJ;","names":[]}