@12-apps/ui 6.83.0 → 6.85.0

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

@@ -0,0 +1,67 @@
+import { decodePolyline } from './RegionMap.helpers';
+import type { RegionMapCopy, RegionMapRegion } from './RegionMap.types';
+
+/**
+ * The copy and the areas every story and test shares.
+ *
+ * The areas are REAL: ten of Belo Horizonte's bairros as IBGE outlines them
+ * (Malha de Bairros, Censo 2022; public data), coverage-simplified at ~11 m,
+ * around a point in Venda Nova. Real shapes are what show the drawing's actual
+ * problems — a hole that is another area, a sliver no finger can hit — which a
+ * grid of squares never would.
+ */
+
+/** English, because stories are developer-facing. A consumer passes its own. */
+export const REGION_MAP_COPY: RegionMapCopy = {
+  mapLabel: 'Map of the neighbourhoods around the store',
+  legendExcluded: 'Not delivered to',
+  legendCircle: (metres) => `${(metres / 1000).toLocaleString('en-US')} km radius`,
+  legendCenter: 'Store',
+  listLabel: 'Neighbourhoods in reach · tap to toggle',
+  showList: (count) => `See the ${count} neighbourhoods as a list`,
+  hideList: 'Hide the list',
+  rowState: { excluded: 'not delivered to', outside: 'outside the radius' },
+};
+
+/** The point the circles are drawn from. */
+export const REGION_MAP_CENTER = { latitude: -19.8136, longitude: -43.9619 };
+
+/** id, name, encoded outline (rings by `,`, polygons by `;`). */
+const OUTLINES: readonly (readonly [string, string, string])[] = [
+  ["3106200190", "Ceu Azul", "rc`xBxookGx@tNJbDtEW@ZsAlKCb@SK_BoBGhDM|D`EAh@^CbEOpGM|KoLpAoDt@iEdBiCr@QhAuBpJkAzIwFqAkG_AcARw@q@Nw@{@GgB_ELq@kCuF}Ag@]c@e@{Aq@w@{HjBu@ZgDpBy@\\yCl@cBTgEMg@NaB`Bk@t@Qx@uOgEOk@cB{As@kBuAc@Iu@VcAb@}@l@k@REtC_BrBeHFqBTwCJg@j@RbCmGfCzBhE`@`@n@dAd@`@}K_A]q@e@qBcA{Ak@`CyJ\\cBXa@r@c@tCq@`Bu@~EcBh@q@v@d@l@u@d@?x@gA|@cBlA{@|@[`AUhAKH`CbESNfCiD`@uAv@i@Ui@f@IUgAbALj@Ql@}@hB|@CrHq@nDyDbBFzW{AdY}A"],
+  ["3106200365", "Serra Verde", "ryzwBnahkGw@`DaBbBaBpEyBpCOIgEjArBdJTl@x@hA}B~AmBjAiBzAoDbEkJaEa@E{@\\kBa@cBq@oAUgCI{A`@u@b@_Ch@y@b@uBnBoAf@w@p@kCRaGNy@YaAIeALmAv@]b@yEpEi@^yAXgAYcDO}@[c@eAoAy@IeAm@{BwBmDgAWoAg@wBuAi@}@yAIyAkBQ{@CaAVcAa@u@Lm@OoAu@e@uB@gAK_A[uCaBmAwASeA?qB`@iB?uAQiACcAa@s@Iy@k@wAWoAJa@E_AXqC\\a@Lu@GaDeC~@w@eDYgBZuCWmAY[zACd@ORq@yA@AoAbLYtH?vGNdFHfQVvBFrIFhEJzIXvRvAxHRhHJzC@lMV|a@t@zR\\CpAoCl@uBPmCx@qCxDgBvBk@h@_C|CcAzCy@vAuChA[b@,l}xwBprgkGA`LyBABmDIcFn@e@pAV"],
+  ["3106200367", "Venda Nova", "le}wBltikGgAaBcAj@CrAyBtAoHdGsApAKb@_FKgApEy@nB{@zAqAhAmB}CdAaAt@kAd@kBrAmIp@yCPe@vAuBfAqA`A{Af@kAXyBFuAFwEXyAX_AxAcDtCeHx@eCpAuBnAgBnAyAlC}BrAy@lQaJf@]tAaBpIpGpNnKU`Dy@O[UiCiDkAeAqAy@cE{BeCcAiGjB?b@YzGuElAfAdDdBhCJdBa@zBlAdF_BfAe@r@s@rCc@dAoG~H]ZyDtE"],
+  ["3106200418", "Santa Monica", "zq`xBhxlkGOp@a@AGr@_@z@w@`AsAjAe@Na@g@m@r@{FzE}@|@e@VyAXS_AqB`@T|@yElADPi@LRz@cB`@?`@sAE{C\\aBJm@RRbDm@FB\\iARGEsBhA{BhAuBhA{Ar@RoCi@UuD{CbAwAv@yCh@oCfGyAjGuAnA]gAeGc@oBc@JcAImEeApA}FaDmAaDs@uGcBeCk@oKmCeCiA}@s@iAoAgAgBa@cAu@wCeAcFy@cD?oAV_D`BpA`D~Cn@\\hORlAIfJiFvKkGj@_@PMpC{AzAs@`DiAhDqAfDkB?}Df@yAzA}B|OjEfB`@~HfCH~@A`BX`FV|GyBXqCp@cCTyAC[b@oBZv@rFRz@|@hCp@x@|AtAz@lAf@vAv@xAd@j@h@lATzAXlENxCF`DLD"],
+  ["3106200457", "Vila Jardim Leblon", "xp~wBzdnkGBx@c@@LfEy@AYz@DwFBQzAs@;pn~wBlsnkGBh@x@EXzFa@BFv@m@@Ce@_@B[UEeA|@CGcBSyBR@"],
+  ["3106200471", "Conjunto Minascaixa", "ryzwBnahkG`AhAfDhELVpCtDlFbHiFxBcA`@kAz@{BpBy@~AkAtCoDiA\\Up@cAREp@mAuBgAiAADr@eDqA_@t@e@b@Um@sBeJfEkANHxBqC`BqE`BcBv@aD"],
+  ["3106200477", "Jardim Leblon", "f|~wBb~mkG^~@N|@hBGNUa@YS_CScDl@S`BKzC]rADr@KX`@l@LJ~AxAI@Tn@AIgA}@FOyBJq@bA_@RUbABhCa@l@]Dp@^Td@GNjAJjCfApTr@|M\\|Ey@FPlET~DeY|A{WzAcBGm@}@Ko@OgCcERIaC{@{QvAX`AvAfDODdAZT^CBd@l@AGw@`@CY{Fy@DCi@SAIqCX{@x@@MgEb@ACy@tBiAzBiArBiAFD,fz~wBrrnkGNbDaAFKqB|@y@,fz~wBrrnkGAM|BGGgAxBMKoAU[eBAG{AbAELd@rAtApBdBBNzFYIuB`AEJrB|@GUmDfAIB~Ab@jHx@E?TzDQJ[x@G\\tGT?D`AM`ALtA]DBt@uDRF`AQ?FfAW?F`A]BN`A}@FIgA[BAaAw@D@bAcDPKuBm@BAoAg@BAcAiCT_DJEeB_@sD_ADEs@hAEI{@x@GUaFaAFAo@{DP"],
+  ["3106200479", "Lagoinha Leblon", "`g{wB|zpkG}N_@d@_VDqEJiFZ_TJyEbBt@zElA`@V|AZfA`@T}@iAa@JaAlCHh@Jz@`BrBfB|AbCUbB`@`@fDrEk@b@|AzChBpB}BrE[g@kAEyBbCeCCI`Cj@DcGzFwBGKhFK`C"],
+  ["3106200482", "Mantiqueira", "x`ywBh{nkGiEg@mCPaBU]e@}@j@aDg@yAIe@a@SbAgBXqEQo@x@u@CY{@cCMc@y@wAGcBi@qCCWg@q@b@e@Bq@y@t@Bx@mC`AmE?_AYcEg@?a@iAEs@c@uB{@eDeBf@Vo@M_Am@MZw@Kk@s@KwD`AOgC|Bm@gAu@{@cLeAw@v@w@|@b@@a@]_FxBW~AGzARtA^tAsAxAWbBy@~Ag@bEY|@m@BWo@oAt@QfFhIJZk@b@_A\\V|@m@r@eA|@w@S[f@eCFYRoATcCsA]LXz@@r@bAAnAThAUR\\lDmAdAFxAqAFXfAFJfAf@GNg@AwA}@{A^y@l@KJ]Is@d@YSa@tDmBjBBZMbA_A~CS`BsA_B_B^{AlBmAbC|Bb@Xf@kA`Cu@nAe@RXtK~KzFiJH]`BA_A|Bt@~ApFfGtBo@vD{@@Tp@XfA}AJ_@hAv@fBoAvCnEUnMo@jc@k@?qA`@k@^c@lAAjJO~G[vAy@vA]hAqMoB{Ew@oEk@{Do@i@EIhAuJoAUdC,njywBzsnkGx@Mv@F?g@p@F?PlALFu@o@AQ}@?cAW@Dh@mA`@q@fAOs@}@Og@DBf@`@Dh@x@"],
+  ["3106200484", "Minascaixa", "r~|wBzahkGqAtBy@dCuCdHyAbDY~@YxAGvEGtAYxBg@jAaAzAgApAwAtBQd@eCeCmBoAyDqCeHoEwEuCoB{AhFyBmFcHqCuDMWgDiEaAiAZc@tCiAx@wAbA{C~B}Cj@i@fBwBpCyDlCy@tBQnCm@BqArB?tEPj@AAx@o@Nm@f@tFjGxBdGnA~AzI~H"],
+];
+
+/** The areas, decoded, none excluded. */
+export const REGION_MAP_AREAS: RegionMapRegion[] = OUTLINES.map(([id, name, outline]) => ({
+  id,
+  name,
+  rings: outline
+    .split(';')
+    .flatMap((polygon) => polygon.split(','))
+    .map((ring) => decodePolyline(ring)),
+}));
+
+/**
+ * Context outside the circle: three of the areas marked `outside` — drawn
+ * faded, left off the list — and one tagged as too small to tap.
+ */
+export const REGION_MAP_WITH_CONTEXT: RegionMapRegion[] = REGION_MAP_AREAS.map((area) => ({
+  ...area,
+  outside: ['Ceu Azul', 'Lagoinha Leblon', 'Mantiqueira'].includes(area.name),
+  detail: area.name === 'Vila Jardim Leblon' ? 'tiny' : undefined,
+}));
+
+/** The same areas with two of them excluded. */
+export const REGION_MAP_WITH_EXCLUSIONS: RegionMapRegion[] = REGION_MAP_AREAS.map((area) => ({
+  ...area,
+  excluded: area.name === 'Minascaixa' || area.name === 'Jardim Leblon',
+}));

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

@@ -0,0 +1,338 @@
+import type { RegionMapPoint, RegionMapRegion, RegionMapRing } from './RegionMap.types';
+
+/**
+ * The geometry behind `RegionMap`, kept pure so it is tested without a DOM.
+ *
+ * Coordinates are projected to METRES on a plane around the centre
+ * (equirectangular): within the tens of kilometres a map like this spans, its
+ * error is far below any outline's own. `y` grows SOUTH, as SVG's does.
+ */
+
+/** Metres per degree of latitude on the mean sphere. */
+const METRES_PER_DEGREE = 111_195;
+
+/** A projected point, metres east (`x`) and south (`y`) of the centre. */
+export interface PlanePoint {
+  x: number;
+  y: number;
+}
+
+/** An SVG viewBox in projected metres. */
+export interface PlaneBox {
+  /** West edge, metres east of the centre. */
+  minX: number;
+  /** North edge, metres south of the centre. */
+  minY: number;
+  /** East-west extent, metres. */
+  spanX: number;
+  /** North-south extent, metres. */
+  spanY: number;
+}
+
+export interface Projection {
+  project: (point: RegionMapPoint) => PlanePoint;
+}
+
+/** The projection around a centre. */
+export function projectionAt(center: { latitude: number; longitude: number }): Projection {
+  const kx = METRES_PER_DEGREE * Math.cos((center.latitude * Math.PI) / 180);
+  return {
+    project: ([latitude, longitude]) => ({
+      x: (longitude - center.longitude) * kx,
+      y: -(latitude - center.latitude) * METRES_PER_DEGREE,
+    }),
+  };
+}
+
+/** A ring as an SVG path segment, closed. */
+function ringPath(ring: readonly PlanePoint[]): string {
+  if (ring.length === 0) return '';
+  const [first, ...rest] = ring;
+  return `M${first!.x.toFixed(1)} ${first!.y.toFixed(1)}${rest.map((p) => `L${p.x.toFixed(1)} ${p.y.toFixed(1)}`).join('')}Z`;
+}
+
+/** Every ring of an area as one path, to be filled with `fill-rule="evenodd"`. */
+export function regionPath(rings: readonly (readonly PlanePoint[])[]): string {
+  return rings.map(ringPath).join('');
+}
+
+/** The smallest and largest of some numbers, in one pass (no spread). */
+export function extent(values: Iterable<number>): { min: number; max: number } | null {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const value of values) {
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  return min === Infinity ? null : { min, max };
+}
+
+/** The box around projected rings. */
+export function planeBounds(rings: readonly (readonly PlanePoint[])[]): PlaneBox | null {
+  const points = rings.flat();
+  const xs = extent(points.map((p) => p.x));
+  const ys = extent(points.map((p) => p.y));
+  if (xs === null || ys === null) return null;
+  return { minX: xs.min, minY: ys.min, spanX: xs.max - xs.min, spanY: ys.max - ys.min };
+}
+
+/**
+ * The square the map shows: the largest circle with a margin, else every area,
+ * else nothing. Square so the drawing keeps its proportions at every width.
+ */
+export function viewBoxFor(
+  largestRadius: number | null,
+  areaBounds: PlaneBox | null,
+  margin = 0.12,
+): PlaneBox | null {
+  if (largestRadius !== null && largestRadius > 0) {
+    const half = largestRadius * (1 + margin);
+    return { minX: -half, minY: -half, spanX: half * 2, spanY: half * 2 };
+  }
+  if (areaBounds === null) return null;
+  const side = Math.max(areaBounds.spanX, areaBounds.spanY) * (1 + margin) || 1;
+  const cx = areaBounds.minX + areaBounds.spanX / 2;
+  const cy = areaBounds.minY + areaBounds.spanY / 2;
+  return { minX: cx - side / 2, minY: cy - side / 2, spanX: side, spanY: side };
+}
+
+/** Do two boxes overlap? Used to skip areas wholly outside the view. */
+export function boxesOverlap(a: PlaneBox, b: PlaneBox): boolean {
+  return (
+    a.minX <= b.minX + b.spanX &&
+    b.minX <= a.minX + a.spanX &&
+    a.minY <= b.minY + b.spanY &&
+    b.minY <= a.minY + a.spanY
+  );
+}
+
+/** How many of one ring's edges a ray from the point, eastward, crosses. */
+function ringCrossings(ring: readonly PlanePoint[], point: PlanePoint): number {
+  let crossings = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const a = ring[i]!;
+    const b = ring[j]!;
+    if (a.y > point.y !== b.y > point.y && point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x) {
+      crossings += 1;
+    }
+  }
+  return crossings;
+}
+
+/** Is the point inside the rings, by the even-odd rule? */
+export function ringsContain(rings: readonly (readonly PlanePoint[])[], point: PlanePoint): boolean {
+  return rings.reduce((sum, ring) => sum + ringCrossings(ring, point), 0) % 2 === 1;
+}
+
+/** The point's distance to one ring's nearest edge. */
+function ringDistance(ring: readonly PlanePoint[], point: PlanePoint): number {
+  let best = Infinity;
+  for (let i = 1; i <= ring.length; i++) {
+    const a = ring[i - 1]!;
+    const b = ring[i % ring.length]!;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const lengthSquared = dx * dx + dy * dy;
+    const t =
+      lengthSquared === 0
+        ? 0
+        : Math.max(0, Math.min(1, ((point.x - a.x) * dx + (point.y - a.y) * dy) / lengthSquared));
+    best = Math.min(best, Math.hypot(a.x + t * dx - point.x, a.y + t * dy - point.y));
+  }
+  return best;
+}
+
+/** The point's distance to the rings: 0 inside, else to the nearest edge. */
+export function ringsDistance(rings: readonly (readonly PlanePoint[])[], point: PlanePoint): number {
+  if (ringsContain(rings, point)) return 0;
+  let best = Infinity;
+  for (const ring of rings) best = Math.min(best, ringDistance(ring, point));
+  return best;
+}
+
+/** An area projected once: what drawing it and hit-testing it read. */
+export interface AreaGeometry {
+  rings: readonly (readonly PlanePoint[])[];
+  /** Null for an area with no points. */
+  bounds: PlaneBox | null;
+  /** Square metres of the largest ring — orders hits and draw order. */
+  area: number;
+  /** The SVG path, every ring, for `fill-rule="evenodd"`. */
+  path: string;
+}
+
+/** A projected area, as the hit test reads it. */
+export interface PlaneRegion {
+  id: string;
+  geometry: AreaGeometry;
+}
+
+/** Is the point within `margin` of the box? */
+function nearBox(box: PlaneBox, point: PlanePoint, margin: number): boolean {
+  return (
+    point.x >= box.minX - margin &&
+    point.x <= box.minX + box.spanX + margin &&
+    point.y >= box.minY - margin &&
+    point.y <= box.minY + box.spanY + margin
+  );
+}
+
+/**
+ * Which area a tap at this point means: the SMALLEST area within `tolerance`
+ * of it, the ones holding it included (distance 0).
+ *
+ * Smallest, because a fingertip is wider than a sliver: a tap that lands on a
+ * big area a few pixels from a 10 m strip almost always meant the strip, and
+ * the big one stays easy to hit everywhere else. An area in another's hole is
+ * smaller than the one around it, so it wins too. Nothing within the
+ * tolerance — empty map — is nothing: a tap there is not a guess. Areas whose
+ * box is not near the point are skipped before any ray is cast.
+ */
+export function hitRegion(
+  regions: readonly PlaneRegion[],
+  point: PlanePoint,
+  tolerance: number,
+): string | null {
+  let best: { id: string; area: number; distance: number } | null = null;
+  for (const { id, geometry } of regions) {
+    const distance = reach(geometry, point, tolerance);
+    if (distance !== null && beats(geometry.area, distance, best)) {
+      best = { id, area: geometry.area, distance };
+    }
+  }
+  return best?.id ?? null;
+}
+
+/** The point's distance to the area, or null when it is beyond the tolerance. */
+function reach(geometry: AreaGeometry, point: PlanePoint, tolerance: number): number | null {
+  if (geometry.bounds === null || !nearBox(geometry.bounds, point, tolerance)) return null;
+  const distance = ringsDistance(geometry.rings, point);
+  return distance <= tolerance ? distance : null;
+}
+
+/** Smaller wins; between two the same size, the nearer. */
+function beats(area: number, distance: number, best: { area: number; distance: number } | null): boolean {
+  if (best === null || area < best.area) return true;
+  return area === best.area && distance < best.distance;
+}
+
+/** Signed area and centroid of one ring (shoelace). */
+function ringCentroid(ring: readonly PlanePoint[]): { area: number; x: number; y: number } {
+  let area = 0;
+  let cx = 0;
+  let cy = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const a = ring[j]!;
+    const b = ring[i]!;
+    const cross = a.x * b.y - b.x * a.y;
+    area += cross;
+    cx += (a.x + b.x) * cross;
+    cy += (a.y + b.y) * cross;
+  }
+  area /= 2;
+  if (area === 0) return { area: 0, x: ring[0]?.x ?? 0, y: ring[0]?.y ?? 0 };
+  return { area, x: cx / (6 * area), y: cy / (6 * area) };
+}
+
+/**
+ * The area's size in square metres, read from its LARGEST ring. Rough on
+ * purpose — holes and second parts are ignored — because it only orders
+ * things: which of two areas holding a tap is the smaller, and which is drawn
+ * first so a small one is never painted over by its neighbour.
+ */
+export function planeArea(rings: readonly (readonly PlanePoint[])[]): number {
+  let largest = 0;
+  for (const ring of rings) largest = Math.max(largest, Math.abs(ringCentroid(ring).area));
+  return largest;
+}
+
+/**
+ * Where an area's label goes: the centroid of its largest ring, pulled back
+ * inside the view, as fractions of the view (0..1) — the label is HTML laid
+ * over the drawing, so its type stays the theme's size at every width.
+ */
+export function labelPosition(
+  rings: readonly (readonly PlanePoint[])[],
+  view: PlaneBox,
+  inset = 0.04,
+): { fractionX: number; fractionY: number } {
+  const largest = rings
+    .map(ringCentroid)
+    .reduce((a, b) => (Math.abs(b.area) > Math.abs(a.area) ? b : a), { area: 0, x: 0, y: 0 });
+  const clamp = (value: number): number => Math.min(1 - inset, Math.max(inset, value));
+  return {
+    fractionX: clamp((largest.x - view.minX) / view.spanX),
+    fractionY: clamp((largest.y - view.minY) / view.spanY),
+  };
+}
+
+/** Every ring of an area, projected. */
+export function projectRings(rings: readonly RegionMapRing[], projection: Projection): PlanePoint[][] {
+  return rings.map((ring) => ring.map(projection.project));
+}
+
+/** One area's geometry, projected and pathed. */
+export function areaGeometry(rings: readonly RegionMapRing[], projection: Projection): AreaGeometry {
+  const plane = projectRings(rings, projection);
+  return { rings: plane, bounds: planeBounds(plane), area: planeArea(plane), path: regionPath(plane) };
+}
+
+/**
+ * A cache of geometry per `rings` IDENTITY, for one projection. A host that
+ * re-creates its region objects on every toggle (`{ ...area, excluded }`)
+ * keeps the same `rings` arrays, so a tap re-projects nothing.
+ */
+export function geometryCache(projection: Projection): (rings: readonly RegionMapRing[]) => AreaGeometry {
+  const cache = new WeakMap<readonly RegionMapRing[], AreaGeometry>();
+  return (rings) => {
+    let geometry = cache.get(rings);
+    if (geometry === undefined) {
+      geometry = areaGeometry(rings, projection);
+      cache.set(rings, geometry);
+    }
+    return geometry;
+  };
+}
+
+/** An area as the drawing reads it. */
+export type DrawnRegion = RegionMapRegion & { geometry: AreaGeometry };
+
+/** The areas worth drawing — any part in the view — largest first. */
+export function drawOrder(
+  regions: readonly RegionMapRegion[],
+  geometryOf: (rings: readonly RegionMapRing[]) => AreaGeometry,
+  view: PlaneBox,
+): DrawnRegion[] {
+  return regions
+    .map((region) => ({ ...region, geometry: geometryOf(region.rings) }))
+    .filter(({ geometry }) => geometry.bounds !== null && boxesOverlap(geometry.bounds, view))
+    .sort((a, b) => b.geometry.area - a.geometry.area);
+}
+
+/**
+ * A Google encoded polyline into `[latitude, longitude]` points, at 1e-5 — the
+ * compact form an outline usually travels in. Product-free, so it lives here.
+ */
+export function decodePolyline(encoded: string, precision = 1e5): RegionMapPoint[] {
+  const points: RegionMapPoint[] = [];
+  let index = 0;
+  let lat = 0;
+  let lng = 0;
+  const next = (): number => {
+    let shift = 0;
+    let result = 0;
+    let byte: number;
+    do {
+      byte = encoded.charCodeAt(index++) - 63;
+      result |= (byte & 0x1f) << shift;
+      shift += 5;
+    } while (byte >= 0x20);
+    return result & 1 ? ~(result >> 1) : result >> 1;
+  };
+  while (index < encoded.length) {
+    lat += next();
+    lng += next();
+    points.push([lat / precision, lng / precision]);
+  }
+  return points;
+}

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

@@ -0,0 +1,125 @@
+import React from 'react';
+
+import {
+  drawOrder,
+  extent,
+  geometryCache,
+  hitRegion,
+  projectionAt,
+  viewBoxFor,
+  type DrawnRegion,
+  type PlaneBox,
+} from './RegionMap.helpers';
+import type { RegionMapProps, RegionMapRegion } from './RegionMap.types';
+
+/** What the drawing needs, derived from the props. */
+export interface RegionMapModel {
+  /** The square shown, or null when there is nothing to centre on. */
+  view: PlaneBox | null;
+  drawn: DrawnRegion[];
+  /** Radii drawn, in metres; empty without circles. */
+  radii: number[];
+  outermostMetres: number | null;
+  /** The tap handlers for the drawing's `<svg>`. */
+  onPointerDown: (event: React.PointerEvent<SVGSVGElement>) => void;
+  onClick: (event: React.MouseEvent<SVGSVGElement>) => void;
+}
+
+/** A tap reaches an area this close: a share of the view (~8 px on a phone). */
+const TOLERANCE_SHARE = 1 / 45;
+
+/** The middle of every area, for a map with no centre of its own. */
+function centreOf(regions: readonly RegionMapRegion[]): { latitude: number; longitude: number } | null {
+  const points = regions.flatMap((r) => r.rings.flat());
+  const lats = extent(points.map(([lat]) => lat));
+  const lngs = extent(points.map(([, lng]) => lng));
+  if (lats === null || lngs === null) return null;
+  return { latitude: (lats.min + lats.max) / 2, longitude: (lngs.min + lngs.max) / 2 };
+}
+
+/** The click, in the drawing's own coordinates — or null where it cannot be read. */
+function svgPoint(event: React.MouseEvent<SVGSVGElement>): { x: number; y: number } | null {
+  const svg = event.currentTarget;
+  const matrix = typeof svg.getScreenCTM === 'function' ? svg.getScreenCTM() : null;
+  if (!matrix || typeof DOMPoint === 'undefined') return null;
+  const point = new DOMPoint(event.clientX, event.clientY).matrixTransform(matrix.inverse());
+  return { x: point.x, y: point.y };
+}
+
+/** The view: the outermost circle when there is one, else every area's box. */
+function viewOf(outermostMetres: number | null, drawable: () => (PlaneBox | null)[]): PlaneBox | null {
+  if (outermostMetres !== null) return viewBoxFor(outermostMetres, null);
+  const boxes = drawable().filter((box): box is PlaneBox => box !== null);
+  const xs = extent(boxes.flatMap((b) => [b.minX, b.minX + b.spanX]));
+  const ys = extent(boxes.flatMap((b) => [b.minY, b.minY + b.spanY]));
+  if (xs === null || ys === null) return null;
+  return viewBoxFor(null, { minX: xs.min, minY: ys.min, spanX: xs.max - xs.min, spanY: ys.max - ys.min });
+}
+
+/** Which area a click or tap means — see `useRegionMap`. */
+function tappedRegion(
+  event: React.MouseEvent<SVGSVGElement>,
+  pointer: string,
+  drawn: readonly DrawnRegion[],
+  view: PlaneBox,
+): string | null {
+  const targetId = (event.target as Element).getAttribute('data-region-id');
+  if (pointer === 'mouse' && targetId) return targetId;
+  const point = svgPoint(event);
+  if (point === null) return targetId;
+  return hitRegion(
+    drawn.map((d) => ({ id: d.id, geometry: d.geometry })),
+    point,
+    view.spanX * TOLERANCE_SHARE,
+  );
+}
+
+/** The geometry cache for a centre, or null without one. */
+function useGeometry(
+  origin: { latitude: number; longitude: number } | null,
+): ReturnType<typeof geometryCache> | null {
+  const lat = origin?.latitude ?? null;
+  const lng = origin?.longitude ?? null;
+  return React.useMemo(
+    () => (lat === null || lng === null ? null : geometryCache(projectionAt({ latitude: lat, longitude: lng }))),
+    [lat, lng],
+  );
+}
+
+/**
+ * The projection, the view, the areas in draw order and the tap handlers.
+ *
+ * Geometry is projected once per `rings` identity and centre
+ * (`geometryCache`), so a toggle — which changes `excluded`, not `rings` —
+ * re-projects nothing.
+ *
+ * A MOUSE click on a path is that path's area: a pointer is precise. Any
+ * other tap — a finger, a pen — goes to `hitRegion`: the smallest area within
+ * a few pixels, so a sliver beside a big area is reachable from the map.
+ */
+export function useRegionMap({
+  regions,
+  center,
+  circles = [],
+  onToggle,
+}: Pick<RegionMapProps, 'regions' | 'center' | 'circles' | 'onToggle'>): RegionMapModel {
+  const geometryOf = useGeometry(center ?? centreOf(regions));
+  const radii = circles.map((c) => c.radiusMetres);
+  const outermostMetres = extent(radii)?.max ?? null;
+  const view =
+    geometryOf === null ? null : viewOf(outermostMetres, () => regions.map((r) => geometryOf(r.rings).bounds));
+  const drawn = geometryOf && view ? drawOrder(regions, geometryOf, view) : [];
+  const pointerType = React.useRef<string>('mouse');
+
+  const onPointerDown = (event: React.PointerEvent<SVGSVGElement>): void => {
+    pointerType.current = event.pointerType || 'mouse';
+  };
+
+  const onClick = (event: React.MouseEvent<SVGSVGElement>): void => {
+    if (!onToggle || view === null) return;
+    const hit = tappedRegion(event, pointerType.current, drawn, view);
+    if (hit) onToggle(hit);
+  };
+
+  return { view, drawn, radii, outermostMetres, onPointerDown, onClick };
+}

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

@@ -0,0 +1,144 @@
+# RegionMap
+
+A hand-drawn map of named **areas** around a centre — polygons with holes,
+drawn as inline SVG — where a tap toggles an area's `excluded` state.
+
+Product-free. An area is a bairro, a delivery zone, a sales territory or a
+parking sector alike; coordinates are plain latitude/longitude, and every word
+arrives through `copy`. Built for a delivery host's "which neighbourhoods does this store not
+deliver to", and deliberately not named after it.
+
+## Use cases
+
+- Picking which neighbourhoods inside a delivery radius are left out.
+- Marking territories, zones or sectors on/off around a point.
+- Showing a read-only picture of which areas are in and out (omit `onToggle`).
+
+## Decisions that shape the API
+
+### No tiles, no key, nothing fetched
+
+The question is "which of THESE areas", not "what is this street called", so
+the drawing is the areas themselves over a plain background. That keeps it
+free of a tile provider, an API key and a network request, and it renders the
+same in a test as on a phone. `MapPreview` is the component for a real map.
+
+### The list is the accessible way in
+
+The drawing is ONE `role="img"` with `copy.mapLabel`; its areas are not tab
+stops. Real areas are many and some are far too small to tap on a phone (IBGE
+outlines 11 of the 48 bairros inside a 3 km ring in one Belo Horizonte
+neighbourhood at under 0.1 km²). Every area is also a toggle button in the list
+beneath (`aria-pressed`, plus its state in words from `copy.rowState`), which
+is what a keyboard and a screen reader use, and what reaches a sliver no finger
+can. `listMode` decides how it is offered:
+`shown` (a computer), `collapsed` behind one button that names the count (a
+phone), or `none` for a host that renders its own.
+
+The list holds only the areas in reach: an `outside` area is drawn faded on the
+map for context but has no row unless `listed: true`, and the count matches the
+rows. `listSort: 'name'` orders it by name; `detail` carries a distance or a
+size tag ("tiny") for an area too small to tap.
+
+### Excluded is hatched AND named, never only coloured
+
+An excluded area gets a hatch, a darker edge and its name on the map, and a
+pressed, filled row with a check in the list, whose inverted colours hold under
+hover and keyboard focus, with a focus ring. Colour is never the only signal,
+and the error colour is never used: leaving an area out is a choice, not a
+failure. The highlighted areas (`highlightedIds`, e.g. a search's hits — several
+at once) use the primary colour and are named too.
+
+### Our hit test, not only the browser's
+
+A MOUSE click on an area's path is that area: the browser hit-tests the
+even-odd fill, and areas are drawn largest first, so an area in another's hole
+is on top. A finger's (or pen's) tap goes to `hitRegion`: the SMALLEST area
+within ~2% of the view (about 8 px on a phone), the ones holding the tap
+included — so a strip a few metres wide beside a big area can be hit from the
+map, and the big one stays easy to hit everywhere else. A tap on empty map
+toggles nothing. An area too thin even for that is on the list.
+
+### A toggle is cheap
+
+Geometry is projected once per `rings` array identity and centre, so a host
+that rebuilds its region objects on every toggle (`{ ...area, excluded }`) but
+keeps their `rings` re-projects nothing. The base areas are a memoised layer: a
+toggle re-renders only the hatch, highlight and label layers. Measured on 102
+areas of 300 vertices each at 4× CPU throttle: 18–46 ms from tap to commit.
+
+### Strokes and type stay their size at every width
+
+Strokes use `vector-effect: non-scaling-stroke`, and labels are HTML laid over
+the drawing at theme sizes, moved in by their measured width so none is
+clipped at an edge — the map reads the same at 320 px and at 1600 px. The
+drawing is square; `maxHeight` caps it on a wide screen, and where it sits in a
+wider box is the host's call.
+
+## Props
+
+| prop | type | default | what it does |
+|---|---|---|---|
+| `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 |
+| `onToggle` | `(id: string) => void` | — | a tap or a list press; omit for read-only |
+| `highlightedIds` | `readonly string[]` | `[]` | areas to point at (a search's hits), outlined and named |
+| `copy` | `RegionMapCopy` | — | every word |
+| `listMode` | `'shown' \| 'collapsed' \| 'none'` | `'collapsed'` | how the list is offered |
+| `listSort` | `'given' \| 'name'` | `'given'` | the list's order |
+| `maxHeight` | `string` | — | the drawing's largest height, any CSS length |
+| `className` | `string` | — | on the root |
+| `dataTestId` | `string` | `'region-map'` | every child test id derives from it |
+
+### `RegionMapRegion`
+
+```ts
+{
+  id: string;
+  name: string;
+  rings: readonly (readonly [latitude, longitude])[][]; // even-odd: holes are rings
+  excluded?: boolean;
+  outside?: boolean;  // drawn faded (context beyond the circles); still tappable
+  listed?: boolean;   // has a list row; defaults to !outside
+  detail?: string;    // pre-formatted, on the list row: "2.7 km away", "tiny"
+}
+```
+
+### `RegionMapCopy`
+
+`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.
+
+## Helpers
+
+- `decodePolyline(encoded, precision = 1e5)` — Google's encoded polyline into
+  `[latitude, longitude]` points; outlines usually travel this way.
+- `hitRegion(regions, point, tolerance)` and `projectionAt(center)` — the hit
+  test and projection the component uses, for a host that draws its own layer.
+
+## Example
+
+```tsx
+<RegionMap
+  regions={bairros.map((b) => ({
+    id: b.code,
+    name: b.name,
+    rings: b.outline.split(';').flatMap((p) => p.split(',')).map((r) => decodePolyline(r)),
+    excluded: excluded.has(b.code),
+    detail: b.distanceLabel,
+  }))}
+  center={store}
+  circles={rings.map((r) => ({ radiusMetres: r.maxDistanceMetres }))}
+  onToggle={toggle}
+  highlightedIds={searchHits}
+  copy={copy}
+  listMode={isPhone ? 'collapsed' : 'shown'}
+/>
+```
+
+## Not here (yet)
+
+- Zoom and pan. The list covers the areas too small to tap.
+- A React Native build.