@12-apps/ui 6.84.0 → 6.85.0

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;
+}

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

@@ -0,0 +1,299 @@
+import Box from '@mui/material/Box/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import { alpha, type Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { rem, remPx } from '../../../tokens/relative';
+
+import { labelPosition, type AreaGeometry, type DrawnRegion, type PlaneBox } from './RegionMap.helpers';
+import type { RegionMapModel } from './RegionMap.hooks';
+
+export interface RegionMapDrawingProps {
+  model: RegionMapModel & { view: PlaneBox };
+  showCenter: boolean;
+  highlightedIds: readonly string[];
+  maxHeight: string | undefined;
+  label: string;
+  tappable: boolean;
+  testId: string;
+  theme: Theme;
+}
+
+/**
+ * The drawing: one `role="img"`, square, with HTML labels laid over it.
+ *
+ * Strokes are `non-scaling-stroke` and labels are HTML at theme sizes, so the
+ * picture reads the same at 320 px and 1600 px; `maxHeight` caps it on a wide
+ * screen. Where it sits in a wider box is the host's call.
+ *
+ * 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,
+  showCenter,
+  highlightedIds,
+  maxHeight,
+  label,
+  tappable,
+  testId,
+  theme,
+}: RegionMapDrawingProps): React.JSX.Element {
+  const hatchId = `${React.useId().replace(/:/g, '')}-hatch`;
+  const { view, drawn } = model;
+  const wanted = new Set(highlightedIds);
+  const highlighted = drawn.filter((d) => wanted.has(d.id));
+  const labelled = [...drawn.filter((d) => d.excluded), ...highlighted.filter((d) => !d.excluded)];
+  const base = drawn.map((d) => ({ id: d.id, name: d.name, geometry: d.geometry, outside: d.outside === true }));
+  return (
+    <Box
+      sx={{
+        position: 'relative',
+        width: '100%',
+        maxWidth: maxHeight,
+        maxHeight,
+        aspectRatio: '1 / 1',
+        border: 1,
+        borderColor: 'divider',
+        borderRadius: 1,
+        overflow: 'hidden',
+        bgcolor: 'background.paper',
+      }}
+      data-testid={`${testId}-canvas`}
+    >
+      <svg
+        viewBox={`${view.minX} ${view.minY} ${view.spanX} ${view.spanY}`}
+        role="img"
+        aria-label={label}
+        onPointerDown={model.onPointerDown}
+        onClick={model.onClick}
+        style={{ display: 'block', width: '100%', height: '100%', cursor: tappable ? 'pointer' : 'default' }}
+      >
+        <Hatch id={hatchId} pitch={view.spanX / 70} theme={theme} />
+        <BaseAreas areas={base} testId={testId} theme={theme} />
+        <ExcludedAreas drawn={drawn} hatchId={hatchId} testId={testId} theme={theme} />
+        <Circles radii={model.radii} theme={theme} />
+        {highlighted.map((d) => (
+          <path
+            key={`h-${d.id}`}
+            d={d.geometry.path}
+            fillRule="evenodd"
+            vectorEffect="non-scaling-stroke"
+            fill={alpha(theme.palette.primary.main, 0.3)}
+            stroke={theme.palette.primary.main}
+            strokeWidth={2.5}
+            pointerEvents="none"
+            data-testid={`${testId}-highlight-${d.id}`}
+          />
+        ))}
+        {showCenter && (
+          <circle
+            cx={0}
+            cy={0}
+            r={view.spanX / 90}
+            fill={theme.palette.primary.main}
+            stroke={theme.palette.background.paper}
+            strokeWidth={2}
+            vectorEffect="non-scaling-stroke"
+            pointerEvents="none"
+            data-testid={`${testId}-center`}
+          />
+        )}
+      </svg>
+      {labelled.map((d) => (
+        <AreaLabel key={`l-${d.id}`} area={d} view={view} testId={testId} theme={theme} />
+      ))}
+    </Box>
+  );
+}
+
+/** The hatch an excluded area is filled with: lines, not a colour. */
+function Hatch({ id, pitch, theme }: { id: string; pitch: number; theme: Theme }): React.JSX.Element {
+  return (
+    <defs>
+      <pattern id={id} width={pitch} height={pitch} patternUnits="userSpaceOnUse" patternTransform="rotate(45)">
+        <rect width={pitch} height={pitch} fill={alpha(theme.palette.text.primary, 0.1)} />
+        <rect width={pitch / 3} height={pitch} fill={theme.palette.text.secondary} />
+      </pattern>
+    </defs>
+  );
+}
+
+interface BaseArea {
+  id: string;
+  name: string;
+  geometry: AreaGeometry;
+  outside: boolean;
+}
+
+interface BaseAreasProps {
+  areas: readonly BaseArea[];
+  testId: string;
+  theme: Theme;
+}
+
+/** Same areas, same geometry objects, same look: nothing to re-render. */
+function sameBase(a: BaseAreasProps, b: BaseAreasProps): boolean {
+  if (a.theme !== b.theme || a.testId !== b.testId || a.areas.length !== b.areas.length) return false;
+  return a.areas.every((area, i) => {
+    const other = b.areas[i]!;
+    return (
+      area.id === other.id &&
+      area.geometry === other.geometry &&
+      area.outside === other.outside &&
+      area.name === other.name
+    );
+  });
+}
+
+/** Every area's fill and border — the tap targets. Memoised: see `sameBase`. */
+const BaseAreas = React.memo(function BaseAreas({ areas, testId, theme }: BaseAreasProps): React.JSX.Element {
+  const { palette } = theme;
+  return (
+    <>
+      {areas.map((d) => (
+        <path
+          key={d.id}
+          d={d.geometry.path}
+          fillRule="evenodd"
+          vectorEffect="non-scaling-stroke"
+          fill={d.outside ? palette.background.paper : palette.action.hover}
+          stroke={palette.divider}
+          strokeWidth={1}
+          data-region-id={d.id}
+          data-testid={`${testId}-area-${d.id}`}
+        >
+          <title>{d.name}</title>
+        </path>
+      ))}
+    </>
+  );
+}, sameBase);
+
+/** The hatch over every excluded area. */
+function ExcludedAreas({
+  drawn,
+  hatchId,
+  testId,
+  theme,
+}: {
+  drawn: readonly DrawnRegion[];
+  hatchId: string;
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element {
+  return (
+    <>
+      {drawn
+        .filter((d) => d.excluded)
+        .map((d) => (
+          <path
+            key={`x-${d.id}`}
+            d={d.geometry.path}
+            fillRule="evenodd"
+            vectorEffect="non-scaling-stroke"
+            fill={`url(#${hatchId})`}
+            stroke={theme.palette.text.secondary}
+            strokeWidth={1.5}
+            pointerEvents="none"
+            data-testid={`${testId}-excluded-${d.id}`}
+          />
+        ))}
+    </>
+  );
+}
+
+/** The dashed circles around the centre. */
+function Circles({ radii, theme }: { radii: readonly number[]; theme: Theme }): React.JSX.Element {
+  return (
+    <>
+      {radii.map((radius) => (
+        <circle
+          key={radius}
+          cx={0}
+          cy={0}
+          r={radius}
+          fill="none"
+          stroke={theme.palette.info.main}
+          strokeWidth={1.75}
+          strokeDasharray="7 5"
+          vectorEffect="non-scaling-stroke"
+          pointerEvents="none"
+        />
+      ))}
+    </>
+  );
+}
+
+/** Where a label's centre may go along one axis so the whole label stays in view. */
+function clampCentre(wanted: number, half: number, span: number, gap: number): number {
+  if (span <= 2 * (half + gap)) return span / 2;
+  return Math.min(span - half - gap, Math.max(half + gap, wanted));
+}
+
+/**
+ * An area's name over the drawing, at the theme's type size whatever the
+ * width — and moved in by its own measured size, so it is never clipped at
+ * the drawing's edge.
+ */
+function AreaLabel({
+  area,
+  view,
+  testId,
+  theme,
+}: {
+  area: DrawnRegion;
+  view: PlaneBox;
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element {
+  const at = labelPosition(area.geometry.rings, view);
+  const ref = React.useRef<HTMLSpanElement>(null);
+  const gap = remPx(theme, 4);
+  // Measured by a ResizeObserver, never in a layout effect: the observer's
+  // first call comes after the browser's own layout, so mounting a label on a
+  // tap forces no synchronous reflow of the drawing.
+  React.useEffect(() => {
+    const label = ref.current;
+    const box = label?.parentElement;
+    if (!label || !box || typeof ResizeObserver === 'undefined') return undefined;
+    const observer = new ResizeObserver(() => {
+      const width = box.clientWidth;
+      const height = box.clientHeight;
+      if (width === 0 || height === 0) return;
+      const x = clampCentre(at.fractionX * width, label.offsetWidth / 2, width, gap);
+      const y = clampCentre(at.fractionY * height, label.offsetHeight / 2, height, gap);
+      label.style.left = `${(x / width) * 100}%`;
+      label.style.top = `${(y / height) * 100}%`;
+    });
+    observer.observe(box);
+    observer.observe(label);
+    return () => observer.disconnect();
+  }, [at.fractionX, at.fractionY, gap]);
+  const halo = `0 0 ${rem(theme, 3)} ${theme.palette.background.paper}`;
+  return (
+    <Typography
+      ref={ref}
+      component="span"
+      aria-hidden
+      data-testid={`${testId}-label-${area.id}`}
+      // Position as an inline style, not `sx`: a per-label class would insert
+      // a new CSS rule (and a style recalculation) on every tap.
+      style={{ left: `${(at.fractionX * 100).toFixed(2)}%`, top: `${(at.fractionY * 100).toFixed(2)}%` }}
+      sx={{
+        position: 'absolute',
+        transform: 'translate(-50%, -50%)',
+        fontSize: rem(theme, 11),
+        fontWeight: 700,
+        lineHeight: 1.1,
+        textAlign: 'center',
+        maxWidth: '45%',
+        color: 'text.primary',
+        pointerEvents: 'none',
+        textShadow: `${halo}, ${halo}`,
+      }}
+    >
+      {area.name}
+    </Typography>
+  );
+}