@12-apps/ui 6.83.0 → 6.85.0

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

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

@@ -0,0 +1,81 @@
+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 } from '../../../tokens/relative';
+
+import type { RegionMapCopy } from './RegionMap.types';
+
+/** What the hatch, the dashed circle and the dot mean — in words. */
+export function RegionMapLegend({
+  copy,
+  outermostMetres,
+  showCenter,
+  theme,
+  testId,
+}: {
+  copy: RegionMapCopy;
+  outermostMetres: number | null;
+  showCenter: boolean;
+  theme: Theme;
+  testId: string;
+}): React.JSX.Element {
+  const swatch = rem(theme, 14);
+  const { palette } = theme;
+  const stripe = rem(theme, 2);
+  return (
+    <Box
+      data-testid={`${testId}-legend`}
+      sx={{ display: 'flex', flexWrap: 'wrap', columnGap: 2, rowGap: 0.5, mt: 1, alignItems: 'center' }}
+    >
+      <LegendItem text={copy.legendExcluded}>
+        <Box
+          component="span"
+          sx={{
+            width: swatch,
+            height: swatch,
+            border: 1,
+            borderColor: 'text.secondary',
+            borderRadius: 0.5,
+            background: `repeating-linear-gradient(135deg, ${palette.text.secondary} 0 ${stripe}, ${alpha(palette.text.primary, 0.1)} ${stripe} ${rem(theme, 5)})`,
+          }}
+        />
+      </LegendItem>
+      {outermostMetres !== null && (
+        <LegendItem text={copy.legendCircle(outermostMetres)}>
+          <Box
+            component="span"
+            sx={{
+              width: swatch,
+              height: swatch,
+              borderWidth: stripe,
+              borderStyle: 'dashed',
+              borderColor: 'info.main',
+              borderRadius: '50%',
+            }}
+          />
+        </LegendItem>
+      )}
+      {showCenter && (
+        <LegendItem text={copy.legendCenter}>
+          <Box
+            component="span"
+            sx={{ width: rem(theme, 10), height: rem(theme, 10), bgcolor: 'primary.main', borderRadius: '50%' }}
+          />
+        </LegendItem>
+      )}
+    </Box>
+  );
+}
+
+function LegendItem({ text, children }: { text: string; children: React.ReactNode }): React.JSX.Element {
+  return (
+    <Box component="span" sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.75 }}>
+      {children}
+      <Typography component="span" variant="caption" color="text.secondary">
+        {text}
+      </Typography>
+    </Box>
+  );
+}