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>

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,192 @@
+"use client";
+
+import { useMemo } from "react";
+import type { MouseEvent as ReactMouseEvent } from "react";
+import Supercluster from "supercluster";
+import { Marker, type MarkerEvent } 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 { ListingMapPinMarker } 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;
+}
+
+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) {
+          const activateCluster = () => {
+            onClusterClick(
+              pin.longitude,
+              pin.latitude,
+              clusterIndex.getClusterExpansionZoom(pin.clusterId!)
+            );
+          };
+
+          const handlePinClick = (event: ReactMouseEvent<HTMLDivElement>) => {
+            event.preventDefault();
+            event.stopPropagation();
+            event.nativeEvent.stopPropagation();
+            activateCluster();
+          };
+
+          const handleMarkerClick = (
+            event: MarkerEvent<globalThis.MouseEvent>
+          ) => {
+            event.originalEvent.stopPropagation();
+            activateCluster();
+          };
+
+          return (
+            <Marker
+              key={pin.key}
+              longitude={pin.longitude}
+              latitude={pin.latitude}
+              anchor="center"
+              onClick={handleMarkerClick}
+            >
+              <ClusterPinEnter>
+                <MapPin
+                  markerId={pin.key}
+                  type="community"
+                  onClick={handlePinClick}
+                />
+              </ClusterPinEnter>
+            </Marker>
+          );
+        }
+
+        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;

src/features/map/components/MapPinLayer.tsx

@@ -11,6 +11,7 @@ import {
 import MapPin from "@/components/MapPin";
 import type { ListingCoordinates, ListingMarker } from "@/types/listing";
 
+import ClusterPinEnter from "./ClusterPinEnter";
 import { hasValidCoordinates } from "../lib/mapUtils";
 
 type MapPinLayerProps = {
@@ -26,6 +27,7 @@ type ListingMapPinMarkerProps = {
   isSelected: boolean;
   markerLabel: string;
   onMarkerClick: MapPinLayerProps["onMarkerClick"];
+  withClusterEnterAnimation?: boolean;
 };
 
 const KEYBOARD_ACTIVATION_KEYS = new Set(["Enter", " "]);
@@ -34,12 +36,13 @@ const KEYBOARD_ACTIVATION_KEYS = new Set(["Enter", " "]);
 // duplicate events without blocking deliberate follow-up activations.
 const DUPLICATE_MARKER_CLICK_SUPPRESSION_MS = 100;
 
-function ListingMapPinMarker({
+export function ListingMapPinMarker({
   listing,
   coords,
   isSelected,
   markerLabel,
   onMarkerClick,
+  withClusterEnterAnimation = false,
 }: ListingMapPinMarkerProps) {
   const markerRef = useRef<MarkerInstance | null>(null);
   const lastPinPointerClickRef = useRef<{
@@ -142,12 +145,23 @@ function ListingMapPinMarker({
       onClick={handleMarkerClick}
       style={{ zIndex: isSelected ? 1 : 0 }}
     >
-      <MapPin
-        markerId={listing.id}
-        onClick={handlePinClick}
-        selected={isSelected}
-        type={listing.type ?? undefined}
-      />
+      {withClusterEnterAnimation ? (
+        <ClusterPinEnter>
+          <MapPin
+            markerId={listing.id}
+            onClick={handlePinClick}
+            selected={isSelected}
+            type={listing.type ?? undefined}
+          />
+        </ClusterPinEnter>
+      ) : (
+        <MapPin
+          markerId={listing.id}
+          onClick={handlePinClick}
+          selected={isSelected}
+          type={listing.type ?? undefined}
+        />
+      )}
     </Marker>
   );
 }