@12-apps/ui 6.84.0 → 6.86.0

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.

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

@@ -0,0 +1,88 @@
+import Box from '@mui/material/Box/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { useRegionMap } from './RegionMap.hooks';
+import type { RegionMapProps } from './RegionMap.types';
+import { RegionMapDrawing } from './RegionMapDrawing';
+import { RegionMapLegend } from './RegionMapLegend';
+import { RegionMapList } from './RegionMapList';
+
+/** One empty list, so the default does not change identity per render. */
+const NO_IDS: readonly string[] = [];
+
+/**
+ * A hand-drawn map of named areas around a centre; a tap toggles an area.
+ *
+ * Drawn as inline SVG over a plain background — no tile server, no API key,
+ * nothing fetched — because the question it answers is "which of THESE areas",
+ * not "what is the street called". Four choices shape it:
+ *
+ * - **The list is the accessible way in.** The drawing is one `role="img"`
+ *   with a name; its areas are not tab stops (dozens of them, many too small to
+ *   tap on a phone). Every area is also a toggle button in the list beneath,
+ *   with `aria-pressed`, which is what a keyboard and a screen reader use —
+ *   and what reaches a sliver no finger can.
+ * - **Excluded is hatched AND named, never only coloured,** and never in the
+ *   error colour: leaving an area out is a choice, not a failure.
+ * - **The hit test is ours, not only the browser's.** A mouse click on a path
+ *   is that path. A finger's tap takes the SMALLEST area within a few pixels'
+ *   worth of metres (`hitRegion`), so a sliver beside a big area can be hit
+ *   from the map; one too thin even for that is still on the list.
+ * - **A toggle is cheap.** Geometry is projected once per `rings` identity,
+ *   and the base layer is memoised, so a tap re-renders the hatch and labels.
+ */
+export function RegionMap({
+  regions,
+  center,
+  circles,
+  onToggle,
+  highlightedIds = NO_IDS,
+  copy,
+  listMode = 'collapsed',
+  listSort = 'given',
+  maxHeight,
+  className,
+  dataTestId = 'region-map',
+}: RegionMapProps): React.JSX.Element | null {
+  const theme = useTheme();
+  const model = useRegionMap({ regions, center, circles, onToggle });
+  const { view } = model;
+  if (view === null && regions.length === 0) return null;
+  return (
+    <Box className={className} data-testid={dataTestId}>
+      {view && (
+        <>
+          <RegionMapDrawing
+            model={{ ...model, view }}
+            showCenter={center !== null}
+            highlightedIds={highlightedIds}
+            maxHeight={maxHeight}
+            label={copy.mapLabel}
+            tappable={onToggle !== undefined}
+            testId={dataTestId}
+            theme={theme}
+          />
+          <RegionMapLegend
+            copy={copy}
+            outermostMetres={model.outermostMetres}
+            showCenter={center !== null}
+            theme={theme}
+            testId={dataTestId}
+          />
+        </>
+      )}
+      {listMode !== 'none' && (
+        <RegionMapList
+          regions={regions}
+          copy={copy}
+          mode={listMode}
+          sort={listSort}
+          onToggle={onToggle}
+          testId={dataTestId}
+          theme={theme}
+        />
+      )}
+    </Box>
+  );
+}

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

@@ -0,0 +1,117 @@
+/**
+ * The contract of `RegionMap` — a hand-drawn map of named areas (polygons with
+ * holes) around a centre, 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 WGS 84 latitude/longitude, and
+ * every word arrives through `copy`.
+ */
+
+/** A latitude/longitude pair, in that order. */
+export type RegionMapPoint = readonly [latitude: number, longitude: number];
+
+/** One closed ring: the first point repeated last is allowed, not required. */
+export type RegionMapRing = readonly RegionMapPoint[];
+
+/** One named area. */
+export interface RegionMapRegion {
+  /** Stable id — what `onToggle` reports. */
+  id: string;
+  /** The area's name: its label on the map and its row in the list. */
+  name: string;
+  /**
+   * Every ring of every polygon of the area, holes included. Inside is decided
+   * by the EVEN-ODD rule over all of them, so a hole is just a ring inside its
+   * polygon, and a multi-part area is several outer rings.
+   */
+  rings: readonly RegionMapRing[];
+  /** Drawn hatched, labelled, and pressed in the list. */
+  excluded?: boolean;
+  /**
+   * Drawn faded, for an area shown for context beyond the circles (a ring may
+   * grow). Still tappable on the map; left off the list unless `listed`.
+   */
+  outside?: boolean;
+  /**
+   * Whether the area has a row in the list. Defaults to `!outside`, so the
+   * list — and its count — covers the areas inside the circles while the map
+   * still draws the faded context around them.
+   */
+  listed?: boolean;
+  /**
+   * Pre-formatted secondary text on the list row, e.g. "2.7 km away", or a
+   * size tag such as "tiny" for an area too small to tap.
+   */
+  detail?: string;
+}
+
+/** A circle drawn around the centre, e.g. a delivery ring. */
+export interface RegionMapCircle {
+  radiusMetres: number;
+}
+
+/** Every word the map prints or announces. */
+export interface RegionMapCopy {
+  /** The drawing's accessible name (`role="img"`). */
+  mapLabel: string;
+  /** The legend entry for a hatched (excluded) area. */
+  legendExcluded: string;
+  /** The legend entry for the outermost circle, given its radius in metres. */
+  legendCircle: (radiusMetres: number) => string;
+  /** The legend entry for the centre's dot. */
+  legendCenter: string;
+  /** The list's accessible name and its heading when shown. */
+  listLabel: string;
+  /** The button that reveals the list, given how many areas it holds. */
+  showList: (count: number) => string;
+  /** The button that hides it again. */
+  hideList: string;
+  /**
+   * A list row's state, read after its name by a screen reader: "excluded"
+   * for an excluded area (pressed, filled, checked), "outside" for a listed
+   * `outside` one (faded). Neither is shown; the row's look carries it.
+   */
+  rowState: { excluded: string; outside: string };
+}
+
+/** The order of the list: as given (e.g. nearest first), or by name. */
+export type RegionMapListSort = 'given' | 'name';
+
+/**
+ * How the accessible list of areas — one toggle button each — is offered.
+ *
+ * - `shown`: always under the map (a computer, where there is room);
+ * - `collapsed`: behind one button (a phone) — still a keyboard's way in;
+ * - `none`: not rendered. Only for a host that offers its own list.
+ */
+export type RegionMapListMode = 'shown' | 'collapsed' | 'none';
+
+export interface RegionMapProps {
+  regions: readonly RegionMapRegion[];
+  /**
+   * Where the map is centred, and where the dot and the circles are drawn.
+   * `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?: readonly RegionMapCircle[];
+  /**
+   * A tap on an area, or a press of its list button. Omit it and the map is
+   * read-only: nothing is tappable and the list rows are not buttons.
+   */
+  onToggle?: (id: string) => void;
+  /**
+   * Areas to point at — e.g. a search's results — outlined and labelled. More
+   * than one at once: a search lists several hits.
+   */
+  highlightedIds?: readonly string[];
+  copy: RegionMapCopy;
+  listMode?: RegionMapListMode;
+  /** The list's order; `'given'` keeps the order of `regions`. */
+  listSort?: RegionMapListSort;
+  /** The drawing's largest height, any CSS length; it stays square inside it. */
+  maxHeight?: string;
+  className?: string;
+  /** Every child TEST id derives from it. */
+  dataTestId?: string;
+}