Add swipe and button navigation for previous/next zip code on mobile map (#504)

Design context: #404

## Problem

The dot pagination on the map page is hidden below 768px (`hidden
md:block`), so on mobile there is no way to move between zip codes
except tapping a polygon directly. This was split out of #404 to keep
that PR small.

## What this adds

- **Swipe** on the zip details card - left for next, right for previous.
Bound to the card rather than the map, so it never competes with
MapLibre's pan and pinch-zoom.
- **Previous/next buttons** below 768px with an "N of 13" position
counter, placed at the top of the card so they're visible without
scrolling.
- Wrap-around at both ends, so no control is ever a dead end. Shared
with the desktop dots via a `mod` helper moved into `lib/utils.ts`.
- An `aria-live` region announcing the selected zip code.

## Design decision worth flagging

@GTBarrows - the mockup in #404 annotates the `《 》` chevrons "Swipe
indicator, not to be including in final production," which reads as
swipe-only. I've shipped visible buttons anyway, because #482 is framed
as an accessibility improvement and swipe-only has no keyboard path, no
screen reader affordance, and no discoverability.

The buttons are 44px to meet WCAG 2.5.5. The dots they replace are 12px,
which is the same reason the carousel was cut from mobile in the first
place.

Happy to change this if you'd rather keep the card clean - wanted the
reasoning explicit rather than quietly diverging from the design.

## Accessibility note

This adds the app's first `aria-live` region. It sits on the card rather
than inside `ZipDetailsContent`, which early-returns for error and empty
states, so zip changes are announced regardless of source: map click,
desktop dots, mobile buttons, or swipe. That fixes a pre-existing
desktop gap as a side effect.

`DotPagination`'s chevron buttons also had no accessible name; they now
take optional label props.

## Out of scope

- **Map recentering.** On mobile the card covers the lower half of the
viewport, so navigating can highlight a polygon hidden behind it. Left
out pending @CurtSavoie's call on whether it belongs here or in a
follow-up.
- **Other locales.** New keys added to `en-US.json` only. `es-ES`,
`zh-CN`, and `zh-TW` need a team decision on whether new keys get real
translations, English placeholders, or `null` like `template.json`.

## Testing

`npm run test`, `npm run build`, `npm run lint`, and `npm run lint:css`
all clean.

The swipe decision is extracted as a pure `resolveSwipe()` with 8 unit
tests, so it's covered by the existing Vitest setup. The repo has no
component testing infrastructure (no Testing Library or jsdom) and
adding it seemed out of scope for an issue explicitly about keeping the
PR small.

Manually verified at mobile widths in Chrome device emulation:

- Swipe left and right advance and reverse correctly
- Wrap-around works in both directions
- Vertical card scrolling does not trigger navigation
- Diagonal drags are rejected
- Map pan and pinch-zoom unaffected
- Buttons keyboard-reachable; Enter and Space both activate
- Dots return and mobile nav disappears above 768px
- All new i18n keys resolve, no raw key strings rendered

Author: ayushvjain

client/src/components/pages/maps/BostonZipCodeMap.module.css

@@ -57,5 +57,9 @@
     max-height: 50vh;
     padding: 16px;
     pointer-events: auto;
+
+    /* Let the browser keep handling vertical scrolling natively while
+       horizontal gestures are reserved for zip code navigation. */
+    touch-action: pan-y;
   }
-}
+}

client/src/components/pages/maps/BostonZipCodeMap.tsx

@@ -5,11 +5,13 @@ import {
   useEffect,
   RefObject,
   useState,
+  useCallback,
   Dispatch,
   SetStateAction,
 } from "react";
-import { FormattedMessage } from "react-intl";
+import { FormattedMessage, useIntl } from "react-intl";
 import { PageHeader } from "@/components/ui/pageheader";
+import { mod } from "@/lib/utils";
 import {
   BusinessLicense,
   EligibleBostonZipcode,
@@ -21,6 +23,8 @@ import licenseData from "../../../data/licenses.json";
 import DotPagination from "../../../components/ui/dot-pagination";
 import mapStyles from "./BostonZipCodeMap.module.css";
 import "./mapStyleOverrides.css";
+import { MobileZipNav } from "./MobileZipNav";
+import { useZipSwipe } from "./useZipSwipe";
 import { ZipDetailsContent } from "./ZipDetailsContent";
 
 /* Map Styles */
@@ -283,6 +287,7 @@ const getValidatedLicenseData = (): BusinessLicense[] => {
 };
 
 export const BostonZipCodeMap = () => {
+  const intl = useIntl();
   const mapContainer = useRef<HTMLDivElement | null>(null);
   const map = useRef<Map | null>(null);
   const hoverZipId = useRef<string | number | undefined>("");
@@ -299,6 +304,30 @@ export const BostonZipCodeMap = () => {
   const licenses = getValidatedLicenseData();
   const [selectedZip, setSelectedZip] = useState<EligibleBostonZipcode>(uniqueZips[0]);
 
+  const selectedZipIndex = uniqueZips.indexOf(selectedZip);
+
+  // Shared by the dot pagination, the mobile buttons, and swipe. Wraps at both
+  // ends so there is never a dead control.
+  const goToZipOffset = useCallback(
+    (offset: number) => {
+      setSelectedZip((current) => {
+        const currentIndex = uniqueZips.indexOf(current);
+        return uniqueZips[mod(currentIndex + offset, uniqueZips.length)];
+      });
+    },
+    // uniqueZips is derived from a module-level constant Set, so its contents
+    // are stable across renders.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []
+  );
+
+  const goToPreviousZip = useCallback(() => goToZipOffset(-1), [goToZipOffset]);
+  const goToNextZip = useCallback(() => goToZipOffset(1), [goToZipOffset]);
+
+  const swipeHandlers = useZipSwipe({
+    onSwipe: (direction) => goToZipOffset(direction === "next" ? 1 : -1),
+  });
+
   // Initialize map
   useEffect(() => {
     if (map.current) return; // stops map from intializing more than once
@@ -368,16 +397,35 @@ export const BostonZipCodeMap = () => {
           <div
             className={mapStyles.mapCard}
             id="zip-code-details-card"
+            {...swipeHandlers}
           >
+            {/* Announces the change to screen readers, whichever control
+                caused it: map click, dot pagination, buttons, or swipe. */}
+            <p className="sr-only" role="status" aria-live="polite">
+              <FormattedMessage
+                id="map.zipNav.announcement"
+                values={{ zipCode: selectedZip }}
+              />
+            </p>
+            {/* Kept outside ZipDetailsContent so navigation stays available
+                in the error and empty-data states, which return early. */}
+            <MobileZipNav
+              currentIndex={selectedZipIndex}
+              totalZips={uniqueZips.length}
+              onPrevious={goToPreviousZip}
+              onNext={goToNextZip}
+            />
             <ZipDetailsContent licenses={licenses} zipCode={selectedZip} />
             <div className="hidden md:block">
               <DotPagination
-                currentPage={selectedZip ? uniqueZips.indexOf(selectedZip) : 0}
+                currentPage={selectedZip ? selectedZipIndex : 0}
                 totalPages={uniqueZips.length}
                 onPageChange={(newZipIndex) => {
                   setSelectedZip(uniqueZips[newZipIndex]);
                 }}
                 labels={uniqueZips}
+                previousLabel={intl.formatMessage({ id: "map.zipNav.previous" })}
+                nextLabel={intl.formatMessage({ id: "map.zipNav.next" })}
               />
             </div>
           </div>

client/src/components/pages/maps/MobileZipNav.tsx

@@ -0,0 +1,73 @@
+import ChevronLeftIcon from "@mui/icons-material/ChevronLeft";
+import ChevronRightIcon from "@mui/icons-material/ChevronRight";
+import { FormattedMessage, useIntl } from "react-intl";
+
+type MobileZipNavProps = {
+  currentIndex: number;
+  totalZips: number;
+  onPrevious: () => void;
+  onNext: () => void;
+};
+
+// 44px matches the minimum touch target size in WCAG 2.5.5. The dot pagination
+// this replaces on mobile uses 12px dots, which is well under that.
+const navButtonClasses = [
+  "flex items-center justify-center",
+  "w-[44px] h-[44px] shrink-0",
+  "border-[2px] border-button-hovered-light rounded-[4px]",
+  "bg-background-light cursor-pointer",
+  "hover:bg-button-hovered-light",
+  "focus-visible:outline-2 focus-visible:outline-offset-2",
+].join(" ");
+
+/**
+ * Previous/next zip controls shown only below the 768px breakpoint, where the
+ * dot pagination is hidden. The position counter stands in for the dots, which
+ * conveyed both navigation and where you were in the sequence.
+ */
+export const MobileZipNav = ({
+  currentIndex,
+  totalZips,
+  onPrevious,
+  onNext,
+}: MobileZipNavProps) => {
+  const intl = useIntl();
+
+  return (
+    <nav
+      className="flex md:hidden items-center justify-between gap-2 mb-3"
+      aria-label={intl.formatMessage({ id: "map.zipNav.label" })}
+    >
+      <button
+        type="button"
+        onClick={onPrevious}
+        className={navButtonClasses}
+        aria-label={intl.formatMessage({ id: "map.zipNav.previous" })}
+      >
+        <ChevronLeftIcon
+          aria-hidden
+          sx={{ fill: "var(--color-button-default-dark)" }}
+        />
+      </button>
+
+      <p className="text-center">
+        <FormattedMessage
+          id="map.zipNav.position"
+          values={{ current: currentIndex + 1, total: totalZips }}
+        />
+      </p>
+
+      <button
+        type="button"
+        onClick={onNext}
+        className={navButtonClasses}
+        aria-label={intl.formatMessage({ id: "map.zipNav.next" })}
+      >
+        <ChevronRightIcon
+          aria-hidden
+          sx={{ fill: "var(--color-button-default-dark)" }}
+        />
+      </button>
+    </nav>
+  );
+};

client/src/components/pages/maps/useZipSwipe.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveSwipe,
+  SWIPE_AXIS_RATIO,
+  SWIPE_MIN_DISTANCE_PX,
+} from "./useZipSwipe";
+
+describe("resolveSwipe", () => {
+  it("advances on a decisive leftward swipe", () => {
+    expect(resolveSwipe({ dx: -120, dy: 6 })).toBe("next");
+  });
+
+  it("goes back on a decisive rightward swipe", () => {
+    expect(resolveSwipe({ dx: 120, dy: 6 })).toBe("prev");
+  });
+
+  it("ignores travel shorter than the minimum distance", () => {
+    const justUnder = SWIPE_MIN_DISTANCE_PX - 1;
+    expect(resolveSwipe({ dx: -justUnder, dy: 0 })).toBeNull();
+    expect(resolveSwipe({ dx: justUnder, dy: 0 })).toBeNull();
+  });
+
+  it("accepts travel exactly at the minimum distance", () => {
+    expect(resolveSwipe({ dx: -SWIPE_MIN_DISTANCE_PX, dy: 0 })).toBe("next");
+  });
+
+  it("ignores a vertical drag so card scrolling still works", () => {
+    expect(resolveSwipe({ dx: 10, dy: 200 })).toBeNull();
+    expect(resolveSwipe({ dx: -10, dy: -200 })).toBeNull();
+  });
+
+  it("ignores a diagonal drag that is not decisively horizontal", () => {
+    // 80px across, 70px down: over the distance floor, under the axis ratio.
+    expect(resolveSwipe({ dx: -80, dy: 70 })).toBeNull();
+  });
+
+  it("accepts a diagonal drag once it clears the axis ratio", () => {
+    const dy = 40;
+    const dx = -(dy * SWIPE_AXIS_RATIO + 1);
+    expect(resolveSwipe({ dx, dy })).toBe("next");
+  });
+
+  it("ignores a touch that did not move", () => {
+    expect(resolveSwipe({ dx: 0, dy: 0 })).toBeNull();
+  });
+});

client/src/components/pages/maps/useZipSwipe.ts

@@ -0,0 +1,116 @@
+import { useCallback, useRef, type TouchEvent } from "react";
+
+/**
+ * Minimum horizontal travel, in px, before a touch counts as a swipe.
+ * Anything shorter is treated as a tap or an accidental drag.
+ */
+export const SWIPE_MIN_DISTANCE_PX = 48;
+
+/**
+ * How much more horizontal than vertical the travel must be. The zip details
+ * card scrolls vertically, so a mostly-vertical drag must never be read as a
+ * swipe or the card becomes impossible to scroll.
+ */
+export const SWIPE_AXIS_RATIO = 1.5;
+
+/**
+ * Touches starting this close to either screen edge are ignored, so we don't
+ * compete with the browser's own edge-swipe back/forward gesture (iOS Safari).
+ */
+export const SWIPE_EDGE_GUARD_PX = 24;
+
+export type SwipeDirection = "prev" | "next";
+
+export type SwipeVector = {
+  dx: number;
+  dy: number;
+};
+
+/**
+ * Pure swipe decision. Exported separately from the hook so it can be unit
+ * tested without a DOM environment.
+ *
+ * Swiping left (negative dx) advances forward, matching the direction
+ * convention of a carousel: the content moves left as you move forward.
+ */
+export function resolveSwipe({ dx, dy }: SwipeVector): SwipeDirection | null {
+  const distanceX = Math.abs(dx);
+  const distanceY = Math.abs(dy);
+
+  if (distanceX < SWIPE_MIN_DISTANCE_PX) return null;
+  if (distanceX < distanceY * SWIPE_AXIS_RATIO) return null;
+
+  return dx < 0 ? "next" : "prev";
+}
+
+type UseZipSwipeOptions = {
+  onSwipe: (direction: SwipeDirection) => void;
+};
+
+/**
+ * Returns touch handlers to spread onto the element that should respond to
+ * horizontal swipes. Attach these to the zip details card rather than the map
+ * container: the card sits above the map as a sibling node, so touches on it
+ * never reach MapLibre's canvas and cannot interfere with pan or pinch-zoom.
+ *
+ * The element should also set `touch-action: pan-y` so the browser keeps
+ * handling vertical scrolling natively.
+ */
+export function useZipSwipe({ onSwipe }: UseZipSwipeOptions) {
+  const origin = useRef<{ x: number; y: number } | null>(null);
+
+  const onTouchStart = useCallback((event: TouchEvent<HTMLDivElement>) => {
+    // Multi-touch is a pinch, not a swipe.
+    if (event.touches.length !== 1) {
+      origin.current = null;
+      return;
+    }
+
+    const touch = event.touches[0];
+    const nearLeftEdge = touch.clientX <= SWIPE_EDGE_GUARD_PX;
+    const nearRightEdge =
+      touch.clientX >= window.innerWidth - SWIPE_EDGE_GUARD_PX;
+
+    if (nearLeftEdge || nearRightEdge) {
+      origin.current = null;
+      return;
+    }
+
+    origin.current = { x: touch.clientX, y: touch.clientY };
+  }, []);
+
+  const onTouchMove = useCallback((event: TouchEvent<HTMLDivElement>) => {
+    // A second finger landing mid-gesture cancels the swipe.
+    if (event.touches.length > 1) {
+      origin.current = null;
+    }
+  }, []);
+
+  const onTouchEnd = useCallback(
+    (event: TouchEvent<HTMLDivElement>) => {
+      const start = origin.current;
+      origin.current = null;
+
+      if (!start) return;
+
+      const touch = event.changedTouches[0];
+      if (!touch) return;
+
+      const direction = resolveSwipe({
+        dx: touch.clientX - start.x,
+        dy: touch.clientY - start.y,
+      });
+
+      if (direction) {
+        onSwipe(direction);
+      }
+    },
+    [onSwipe]
+  );
+
+  const onTouchCancel = useCallback(() => {
+    origin.current = null;
+  }, []);
+
+  return { onTouchStart, onTouchMove, onTouchEnd, onTouchCancel };
+}