feat(map): cluster mirrored open-data pins at city zoom (#119)

* add client-side clustering for mirrored open-data map pins

Collapse mirrored listings with supercluster at city zoom so dense open-data cities stay usable, while organic pins keep the normal map UX.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix map clustering on preview and address review feedback

Enrich mirrored flags when the RPC has not migrated yet, move cluster viewport updates off high-frequency pan events, and restore keyboard access for cluster markers.

Co-authored-by: Cursor <cursoragent@cursor.com>

* remove mirrored-flag fallback and tighten cluster map behaviour

Rely on the listings_in_view migration for mirrored tier data, use real map bounds for supercluster, and suppress duplicate cluster click events.

* pass keyboard event timestamps through map marker activation

Keep duplicate click suppression on the same DOM time base for pointer and keyboard activations.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: dnywh

src/app/actions.ts

@@ -32,6 +32,7 @@ import { createSupportError } from "@/lib/supportError";
 import type {
   DeleteListingResult,
   ListingDraftInput,
+  ListingMarker,
   ListingSubmitFailureData,
   ListingSubmitResult,
   ListingType,
@@ -1187,7 +1188,10 @@ export async function fetchListingsInView(
       return [];
     }
 
-    return data || [];
+    return ((data || []) as ListingMarker[]).map((listing) => ({
+      ...listing,
+      is_open_data_mirrored: listing.is_open_data_mirrored ?? false,
+    }));
   } catch (error) {
     console.error("Fatal error in fetchListingsInView:", {
       error,

src/components/MapPin/MapPin.tsx

@@ -151,7 +151,7 @@ const CompactPinHitTarget = styled.div`
 
 const CompactPinInner = styled.div<{ $type?: string }>`
   box-shadow:
-    0 0 0 2.5px ${theme.colors.marker.border},
+    0 0 0 var(--map-pin-border-width, 2.5px) ${theme.colors.marker.border},
     0 3px 14px rgba(0, 0, 0, 0.22),
     0 0 4px rgba(0, 0, 0, 0.22);
   width: 24px;
@@ -164,6 +164,7 @@ const CompactPinInner = styled.div<{ $type?: string }>`
   pointer-events: none;
   transform: scale(var(--map-pin-compact-scale, 1));
   transform-origin: center;
+  transition: box-shadow 180ms ease;
 
   ${({ $type }) => $type === "residential" && residentialPinStyles}
   ${({ $type }) => $type === "community" && communityPinStyles}

src/features/map/components/ClusterPinEnter.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { css, keyframes, styled } from "next-yak";
+
+const PIN_ENTER_SCALE_MS = 380;
+const PIN_ENTER_OPACITY_MS = 160;
+const PIN_ENTER_SPRING = "cubic-bezier(0.22, 1.12, 0.36, 1)";
+const PIN_ENTER_START_SCALE = 0.58;
+const PIN_ENTER_OVERSHOOT_SCALE = 1.05;
+
+const pinEnterScale = keyframes`
+  0% {
+    transform: scale(${PIN_ENTER_START_SCALE});
+  }
+
+  72% {
+    transform: scale(${PIN_ENTER_OVERSHOOT_SCALE});
+  }
+
+  100% {
+    transform: scale(1);
+  }
+`;
+
+const pinEnterOpacity = keyframes`
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+`;
+
+const ClusterPinEnterShell = styled.div<{ $entering?: boolean }>`
+  transform-origin: center center;
+
+  @media (prefers-reduced-motion: no-preference) {
+    ${({ $entering }) =>
+      $entering
+        ? css`
+            animation:
+              ${pinEnterScale} ${PIN_ENTER_SCALE_MS}ms ${PIN_ENTER_SPRING} both,
+              ${pinEnterOpacity} ${PIN_ENTER_OPACITY_MS}ms ease-out both;
+          `
+        : undefined}
+  }
+`;
+
+const SuppressEnterAnimationContext = createContext({ current: true });
+
+export function ClusterPinEnterProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const suppressEnterAnimationRef = useRef(true);
+
+  useEffect(() => {
+    suppressEnterAnimationRef.current = false;
+  }, []);
+
+  return (
+    <SuppressEnterAnimationContext.Provider value={suppressEnterAnimationRef}>
+      {children}
+    </SuppressEnterAnimationContext.Provider>
+  );
+}
+
+export default function ClusterPinEnter({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const suppressEnterAnimationRef = useContext(SuppressEnterAnimationContext);
+  const [isEntering] = useState(() => !suppressEnterAnimationRef.current);
+
+  return (
+    <ClusterPinEnterShell $entering={isEntering}>
+      {children}
+    </ClusterPinEnterShell>
+  );
+}

src/features/map/components/MapMirroredClusterLayer.tsx

@@ -0,0 +1,255 @@
+"use client";
+
+import { useMemo, useRef } from "react";
+import type { MouseEvent as ReactMouseEvent } from "react";
+import Supercluster from "supercluster";
+import {
+  Marker,
+  type MarkerEvent,
+  type MarkerInstance,
+} from "react-map-gl/maplibre";
+import type { FeatureCollection, Point } from "geojson";
+
+import MapPin from "@/components/MapPin";
+import type { ListingCoordinates, ListingMarker } from "@/types/listing";
+
+import ClusterPinEnter, { ClusterPinEnterProvider } from "./ClusterPinEnter";
+import {
+  DUPLICATE_MARKER_CLICK_SUPPRESSION_MS,
+  ListingMapPinMarker,
+  useMapMarkerKeyboardActivation,
+} from "./MapPinLayer";
+
+type MapMirroredClusterLayerProps = {
+  geoJson: FeatureCollection<Point>;
+  listingsById: Map<number, ListingMarker>;
+  bounds: [number, number, number, number] | null;
+  zoom: number;
+  selectedListingId: number | null;
+  excludedListingId: number | null;
+  markerLabel: string;
+  onClusterClick: (
+    longitude: number,
+    latitude: number,
+    expansionZoom: number
+  ) => void;
+  onMarkerClick: (listing: ListingMarker) => void;
+  clusterMaxZoom?: number;
+  clusterRadius?: number;
+};
+
+type VisibleMirroredPin = {
+  key: string;
+  longitude: number;
+  latitude: number;
+  isCluster: boolean;
+  clusterId?: number;
+  listingId?: number;
+};
+
+function resolveVisibleMirroredPins(
+  features: ReturnType<Supercluster["getClusters"]>,
+  excludedListingId: number | null
+): VisibleMirroredPin[] {
+  const visiblePins: VisibleMirroredPin[] = [];
+
+  for (const feature of features) {
+    const [longitude, latitude] = feature.geometry.coordinates as [
+      number,
+      number,
+    ];
+    const isCluster = Boolean(feature.properties?.cluster);
+
+    if (isCluster) {
+      const clusterId = feature.properties.cluster_id as number;
+      visiblePins.push({
+        key: `mirrored-cluster-${clusterId}`,
+        longitude,
+        latitude,
+        isCluster: true,
+        clusterId,
+      });
+      continue;
+    }
+
+    const listingId = feature.properties?.id as number;
+    if (listingId === excludedListingId) {
+      continue;
+    }
+
+    visiblePins.push({
+      key: `mirrored-${listingId}`,
+      longitude,
+      latitude,
+      isCluster: false,
+      listingId,
+    });
+  }
+
+  return visiblePins;
+}
+
+function MirroredClusterPinMarker({
+  pinKey,
+  longitude,
+  latitude,
+  markerLabel,
+  onActivate,
+}: {
+  pinKey: string;
+  longitude: number;
+  latitude: number;
+  markerLabel: string;
+  onActivate: () => void;
+}) {
+  const markerRef = useRef<MarkerInstance | null>(null);
+  const lastPinPointerClickRef = useRef<{
+    pinKey: string;
+    timeStamp: number;
+  } | null>(null);
+  const lastKeyboardActivationRef = useRef<number | null>(null);
+
+  useMapMarkerKeyboardActivation({
+    markerRef,
+    markerLabel,
+    onActivate: (timeStamp) => {
+      lastKeyboardActivationRef.current = timeStamp;
+      onActivate();
+    },
+  });
+
+  const handlePinClick = (event: ReactMouseEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
+    event.nativeEvent.stopPropagation();
+    lastPinPointerClickRef.current = {
+      pinKey,
+      timeStamp: event.timeStamp,
+    };
+    onActivate();
+  };
+
+  const handleMarkerClick = (event: MarkerEvent<globalThis.MouseEvent>) => {
+    event.originalEvent.stopPropagation();
+    const lastPinPointerClick = lastPinPointerClickRef.current;
+    if (
+      lastPinPointerClick?.pinKey === pinKey &&
+      Math.abs(lastPinPointerClick.timeStamp - event.originalEvent.timeStamp) <
+        DUPLICATE_MARKER_CLICK_SUPPRESSION_MS
+    ) {
+      return;
+    }
+
+    const lastKeyboardActivation = lastKeyboardActivationRef.current;
+    if (
+      lastKeyboardActivation !== null &&
+      Math.abs(lastKeyboardActivation - event.originalEvent.timeStamp) <
+        DUPLICATE_MARKER_CLICK_SUPPRESSION_MS
+    ) {
+      return;
+    }
+
+    onActivate();
+  };
+
+  return (
+    <Marker
+      ref={markerRef}
+      longitude={longitude}
+      latitude={latitude}
+      anchor="center"
+      onClick={handleMarkerClick}
+    >
+      <ClusterPinEnter>
+        <MapPin markerId={pinKey} type="community" onClick={handlePinClick} />
+      </ClusterPinEnter>
+    </Marker>
+  );
+}
+
+export default function MapMirroredClusterLayer({
+  geoJson,
+  listingsById,
+  bounds,
+  zoom,
+  selectedListingId,
+  excludedListingId,
+  markerLabel,
+  onClusterClick,
+  onMarkerClick,
+  clusterMaxZoom = 15,
+  clusterRadius = 80,
+}: MapMirroredClusterLayerProps) {
+  const clusterIndex = useMemo(() => {
+    const index = new Supercluster({
+      radius: clusterRadius,
+      maxZoom: clusterMaxZoom,
+    });
+
+    index.load(
+      geoJson.features.map((feature) => ({
+        type: "Feature" as const,
+        properties: { ...feature.properties },
+        geometry: feature.geometry,
+      }))
+    );
+
+    return index;
+  }, [clusterMaxZoom, clusterRadius, geoJson]);
+
+  const visibleClusters = useMemo(() => {
+    if (!bounds) return [];
+    return clusterIndex.getClusters(bounds, Math.floor(zoom));
+  }, [bounds, clusterIndex, zoom]);
+
+  const visiblePins = useMemo(
+    () => resolveVisibleMirroredPins(visibleClusters, excludedListingId),
+    [excludedListingId, visibleClusters]
+  );
+
+  return (
+    <ClusterPinEnterProvider>
+      {visiblePins.map((pin) => {
+        if (pin.isCluster && pin.clusterId !== undefined) {
+          return (
+            <MirroredClusterPinMarker
+              key={pin.key}
+              pinKey={pin.key}
+              longitude={pin.longitude}
+              latitude={pin.latitude}
+              markerLabel={markerLabel}
+              onActivate={() => {
+                onClusterClick(
+                  pin.longitude,
+                  pin.latitude,
+                  clusterIndex.getClusterExpansionZoom(pin.clusterId!)
+                );
+              }}
+            />
+          );
+        }
+
+        const listing =
+          pin.listingId !== undefined
+            ? listingsById.get(pin.listingId)
+            : undefined;
+        if (!listing) return null;
+
+        const coords = listing.coordinates as ListingCoordinates;
+        const isSelected = selectedListingId === listing.id;
+
+        return (
+          <ListingMapPinMarker
+            key={pin.key}
+            listing={listing}
+            coords={coords}
+            isSelected={isSelected}
+            markerLabel={markerLabel}
+            onMarkerClick={onMarkerClick}
+            withClusterEnterAnimation
+          />
+        );
+      })}
+    </ClusterPinEnterProvider>
+  );
+}

src/features/map/components/MapPageClient.tsx

@@ -14,11 +14,11 @@ import MapListingDrawerPanel from "./MapListingDrawerPanel";
 import MapSidebar from "./MapSidebar";
 import { useMapListingUrl } from "../hooks/useMapListingUrl";
 import { useIpInitialLocation } from "../hooks/useIpInitialLocation";
-import type { InitialMapCoordinates } from "../lib/mapInitialView";
 import {
   MAP_DRAWER_SNAP_POINTS,
   useMapDrawerState,
 } from "../hooks/useMapDrawerState";
+import type { InitialMapCoordinates } from "../lib/mapInitialView";
 
 type MapPageClientProps = {
   user: User | null;