@12-apps/ui 6.84.0 → 6.86.0

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

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

@@ -0,0 +1,167 @@
+import Check from '@mui/icons-material/Check';
+import Box from '@mui/material/Box/index.js';
+import Button from '@mui/material/Button/index.js';
+import Chip from '@mui/material/Chip/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { rem } from '../../../tokens/relative';
+import { SR_ONLY_SX } from '../../form/Label/Label.styles';
+
+import type {
+  RegionMapCopy,
+  RegionMapListMode,
+  RegionMapListSort,
+  RegionMapProps,
+  RegionMapRegion,
+} from './RegionMap.types';
+
+/** The areas with a row: `listed`, defaulting to "not outside". */
+export function listedRegions(
+  regions: readonly RegionMapRegion[],
+  sort: RegionMapListSort,
+): RegionMapRegion[] {
+  const listed = regions.filter((region) => region.listed ?? region.outside !== true);
+  return sort === 'name' ? [...listed].sort((a, b) => a.name.localeCompare(b.name)) : listed;
+}
+
+/**
+ * Every listed area as a toggle button — the keyboard's and the screen
+ * reader's map, and the way to an area too small to tap. `collapsed` puts it
+ * behind one button that names the count; `shown` lays it out with a heading.
+ */
+export function RegionMapList({
+  regions,
+  copy,
+  mode,
+  sort,
+  onToggle,
+  testId,
+  theme,
+}: {
+  regions: readonly RegionMapRegion[];
+  copy: RegionMapCopy;
+  mode: Exclude<RegionMapListMode, 'none'>;
+  sort: RegionMapListSort;
+  onToggle: RegionMapProps['onToggle'];
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element {
+  const [open, setOpen] = React.useState(false);
+  const listId = `${React.useId().replace(/:/g, '')}-list`;
+  const rows = listedRegions(regions, sort);
+  const visible = mode === 'shown' || open;
+  return (
+    <Box sx={{ mt: 1 }}>
+      {mode === 'collapsed' && (
+        <Button
+          variant="text"
+          size="small"
+          aria-expanded={open}
+          aria-controls={listId}
+          onClick={() => setOpen((current) => !current)}
+          data-testid={`${testId}-list-toggle`}
+          sx={{ px: 0 }}
+        >
+          {open ? copy.hideList : copy.showList(rows.length)}
+        </Button>
+      )}
+      {visible && (
+        <Box id={listId} role="group" aria-label={copy.listLabel} data-testid={`${testId}-list`} sx={{ mt: 1 }}>
+          {mode === 'shown' && (
+            <Typography variant="caption" component="p" sx={{ fontWeight: 700, color: 'text.secondary', mb: 0.5 }}>
+              {copy.listLabel}
+            </Typography>
+          )}
+          <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 1 }}>
+            {rows.map((region) => (
+              <RegionRow
+                key={region.id}
+                region={region}
+                states={copy.rowState}
+                onToggle={onToggle}
+                testId={testId}
+                theme={theme}
+              />
+            ))}
+          </Box>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/** The focus ring every row shows from the keyboard, pressed or not. */
+function focusRing(theme: Theme): { outline: string; outlineOffset: string } {
+  return { outline: `${rem(theme, 2)} solid ${theme.palette.primary.main}`, outlineOffset: rem(theme, 2) };
+}
+
+/** A row's look: inverted when pressed, holding under hover and focus. */
+function rowSx(pressed: boolean, outside: boolean, theme: Theme): SxProps<Theme> {
+  const ring = focusRing(theme);
+  if (!pressed) {
+    return { color: outside ? 'text.secondary' : 'text.primary', '&.Mui-focusVisible': ring };
+  }
+  const inverted = { bgcolor: 'text.primary', color: 'background.paper' };
+  return {
+    ...inverted,
+    '& .MuiChip-icon': { color: 'inherit' },
+    '&:hover': inverted,
+    '&.Mui-focusVisible': { ...inverted, ...ring },
+  };
+}
+
+/** The state a screen reader hears after the name, if any. */
+function rowState(pressed: boolean, outside: boolean, states: RegionMapCopy['rowState']): string | null {
+  if (pressed) return states.excluded;
+  return outside ? states.outside : null;
+}
+
+/**
+ * One area: pressed, filled and checked when excluded — never colour alone —
+ * with its state spelled out for a screen reader. The inverted colours hold
+ * under hover and keyboard focus, where MUI's own would wash them out.
+ */
+function RegionRow({
+  region,
+  states,
+  onToggle,
+  testId,
+  theme,
+}: {
+  region: RegionMapRegion;
+  states: RegionMapCopy['rowState'];
+  onToggle: RegionMapProps['onToggle'];
+  testId: string;
+  theme: Theme;
+}): React.JSX.Element {
+  const pressed = region.excluded === true;
+  const sx = rowSx(pressed, region.outside === true, theme);
+  const state = rowState(pressed, region.outside === true, states);
+  return (
+    <Chip
+      data-testid={`${testId}-row-${region.id}`}
+      label={
+        <Box component="span" sx={{ display: 'inline-flex', gap: 0.75, alignItems: 'baseline' }}>
+          <span>{region.name}</span>
+          {region.detail && (
+            <Box component="span" sx={{ fontSize: rem(theme, 11), opacity: 0.75 }}>
+              {region.detail}
+            </Box>
+          )}
+          {state && (
+            <Box component="span" sx={SR_ONLY_SX}>
+              {state}
+            </Box>
+          )}
+        </Box>
+      }
+      icon={pressed ? <Check fontSize="small" /> : undefined}
+      variant={pressed ? 'filled' : 'outlined'}
+      aria-pressed={onToggle ? pressed : undefined}
+      onClick={onToggle ? () => onToggle(region.id) : undefined}
+      sx={sx}
+    />
+  );
+}

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

@@ -0,0 +1,13 @@
+export { RegionMap } from './RegionMap';
+export { decodePolyline, hitRegion, projectionAt } from './RegionMap.helpers';
+export type { AreaGeometry, PlanePoint, PlaneRegion } from './RegionMap.helpers';
+export type {
+  RegionMapCircle,
+  RegionMapCopy,
+  RegionMapListMode,
+  RegionMapListSort,
+  RegionMapPoint,
+  RegionMapProps,
+  RegionMapRegion,
+  RegionMapRing,
+} from './RegionMap.types';

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

@@ -0,0 +1,22 @@
+# RegionMap Test Status Tracking
+
+## Test Files Status
+
+- [x] `RegionMap.test.stories.tsx` created
+- [x] `__tests__/region-map-helpers.test.ts` — the geometry: even-odd with a
+      hole, distance, which area a tap means (hole, smallest, sliver within the
+      tolerance even from inside a big neighbour, nothing beyond it), the view,
+      label placement, `extent` on 200k values, the projection and the decoder
+- [x] `__tests__/region-map.test.tsx` — what is drawn (areas, hatch + name for
+      excluded only, several highlights, nothing with no centre and no areas),
+      what a tap reports, read-only, and the list (collapsed by default with its
+      count, `aria-expanded`, `aria-pressed`, state in words, outside areas off
+      the list and out of the count, `listed`, sort by name, detail, `none`)
+
+## Storybook Tests Status
+
+| Test Name | Status | Pass/Fail | Notes |
+| --- | --- | --- | --- |
+| A tap on an area reports its id | Written | — | `test-storybook` is not in this repo's CI; jsdom twin in `region-map.test.tsx` |
+| Excluded areas are hatched and named | Written | — | same |
+| The collapsed list opens and toggles from the keyboard | Written | — | same |

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

@@ -0,0 +1,13 @@
+# RegionMap
+
+A hand-drawn map of named areas around a centre; a tap toggles an area.
+Product-free — built for a delivery host's excluded neighbourhoods, named for
+what it draws.
+
+## Status
+
+- [x] Component, types, helpers, fixtures (real IBGE outlines, public data)
+- [x] Docs (`RegionMap.md`), stories, test stories, vitest suites
+- [x] Catalog entry, `data-display` export, `entries.json` subpath
+- [ ] React Native build — not planned until a native host needs it
+- [ ] Zoom and pan — the list covers areas too small to tap

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

@@ -21,6 +21,7 @@ export * from './FleetMap';
 export * from './MapPreview';
 export * from './Popover';
 export * from './Progress';
+export * from './RegionMap';
 export * from './SectionOnboarding/SectionOnboarding';
 export * from './Sheet';
 export * from './StatCard';

package/src/components/form/total-form/Fields/SelectField.tsx

@@ -44,6 +44,10 @@ export function SelectField({ name, options, label, placeholder }: SelectFieldPr
         placeholder={placeholder}
         value={values[name] ?? ''}
         error={Boolean(error)}
+        // The `<label htmlFor>` above names nothing: the combobox is MUI's
+        // display div, not a labelable element. `Select` puts `aria-label` on
+        // that div, so the question names the control (FUT-4157).
+        aria-label={label}
         data-testid={testId}
         onChange={(event) => setFieldValue(name, String(event.target.value))}
       />

package/src/components/form/total-form/Fields/ToggleField.tsx

@@ -44,6 +44,9 @@ export function ToggleField({ name, options, label }: ToggleFieldProps): React.R
         options={options}
         value={values[name] ?? ''}
         fullWidth
+        // A `role="group"` div is not labelable, so the `<label htmlFor>`
+        // above names nothing; the group carries the question itself (FUT-4157).
+        aria-label={label}
         dataTestId={testId}
         onChange={(_event, next) => {
           if (typeof next === 'string') setFieldValue(name, next);

package/dist/chunk-CDCTLPMD.js

@@ -1 +0,0 @@
-//# sourceMappingURL=chunk-CDCTLPMD.js.map