@cdc/map 4.26.2 → 4.26.4

package/src/components/UsaMap/components/UsaMap.County.tsx

@@ -1,10 +1,14 @@
-import { useEffect, useState, useRef, useContext } from 'react'
+import { useEffect, useState, useRef, useContext, useMemo } from 'react'
 import { geoCentroid, geoPath, geoContains } from 'd3-geo'
-import { feature } from 'topojson-client'
+import type { GeoGeometryObjects } from 'd3-geo'
+import { zoom as d3Zoom, zoomIdentity as d3ZoomIdentity } from 'd3-zoom'
+import { select as d3Select } from 'd3-selection'
+import { feature, merge } from 'topojson-client'
 import { geoAlbersUsaTerritories } from 'd3-composite-projections'
 import debounce from 'lodash.debounce'
 import Loading from '@cdc/core/components/Loading'
 import ErrorBoundary from '@cdc/core/components/ErrorBoundary'
+import usExtendedGeography from '../data/us-extended-geography.json'
 import useMapLayers from '../../../hooks/useMapLayers'
 import ConfigContext from '../../../context'
 import { useLegendMemoContext } from '../../../context/LegendMemoContext'
@@ -20,6 +24,40 @@ import { publishAnalyticsEvent } from '@cdc/core/helpers/metrics/helpers'
 import { getVizTitle, getVizSubType } from '@cdc/core/helpers/metrics/utils'
 import { createCanvasPattern, PatternType } from '../../../helpers/createCanvasPattern'
 import { getPatternForRow } from '../../../helpers/getPatternForRow'
+import {
+  getCountyTerritoryVisibility,
+  type CountyTerritoryVisibility,
+  US_TERRITORY_STATE_FIPS_PREFIXES
+} from '../../../helpers/countyTerritories'
+
+type Geometry = GeoGeometryObjects & { id?: string; properties: { name: string } }
+type Focus = {
+  id: string
+  index: number
+  center: [number, number]
+  feature: Geometry
+}
+type TopoData = {
+  year?: string
+  counties: Geometry[]
+  states: Geometry[]
+  hsas: { groupId: string; feature: Geometry }[]
+  mapData: Geometry[]
+  countyIndecies: Record<string, [number, number]>
+  projection: any
+  hsaMapping: Record<string, string>
+}
+
+const dedupeFeaturesById = <T extends { id?: string }>(features: T[]): T[] => {
+  const seenIds = new Set<string>()
+
+  return features.filter(feature => {
+    if (!feature.id) return true
+    if (seenIds.has(feature.id)) return false
+    seenIds.add(feature.id)
+    return true
+  })
+}
 
 const getCountyTopoURL = year => {
   return `https://www.cdc.gov/TemplatePackage/contrib/data/county-topography/cb_${year}_us_county_20m.json`
@@ -31,7 +69,7 @@ const sortById = (a, b) => {
   return 0
 }
 
-const getTopoData = year => {
+const getTopoData = (year, showHSABoundaries, territoryVisibility: CountyTerritoryVisibility, showPuertoRico) => {
   return new Promise(resolve => {
     const resolveWithTopo = async response => {
       if (response.status !== 200) {
@@ -40,28 +78,91 @@ const getTopoData = year => {
         response = await response.json()
       }
 
-      let topoData = {
+      let topoData: TopoData = {
         year: undefined,
-        counties: undefined,
-        states: undefined,
-        mapData: undefined,
-        countyIndecies: undefined,
-        projection: undefined
+        counties: [],
+        states: [],
+        hsas: [],
+        mapData: [],
+        countyIndecies: {},
+        projection: undefined,
+        hsaMapping: {}
       }
 
       topoData.year = year || 'default'
-      topoData.counties = feature(response, response.objects.counties).features
-      topoData.states = feature(response, response.objects.states).features
+      const topoSources = territoryVisibility.showTerritories ? [response, usExtendedGeography] : [response]
+      topoData.counties = dedupeFeaturesById(
+        topoSources
+          .flatMap(topo => feature(topo, topo.objects.counties).features)
+          .filter(county => typeof county.id === 'string' && county.id.length > 2)
+      )
+      topoData.states = dedupeFeaturesById(topoSources.flatMap(topo => feature(topo, topo.objects.states).features))
+      // Additional filtering removes territory features that may still be present in the topology data when territories are hidden.
+      if (!territoryVisibility.showTerritories) {
+        topoData.states = topoData.states.filter(state => {
+          const statePrefix = state.id?.substring(0, 2)
+          if (statePrefix === '72') return showPuertoRico
+          return !statePrefix || !US_TERRITORY_STATE_FIPS_PREFIXES.has(statePrefix)
+        })
+        topoData.counties = topoData.counties.filter(county => {
+          const countyPrefix = county.id?.substring(0, 2)
+          if (countyPrefix === '72') return showPuertoRico
+          if (showPuertoRico) {
+            return !countyPrefix || !US_TERRITORY_STATE_FIPS_PREFIXES.has(countyPrefix)
+          }
+
+          return !countyPrefix || !US_TERRITORY_STATE_FIPS_PREFIXES.has(countyPrefix)
+        })
+      } else {
+        topoData.states = topoData.states.filter(state => {
+          const statePrefix = state.id?.substring(0, 2)
+          return (
+            !statePrefix ||
+            !US_TERRITORY_STATE_FIPS_PREFIXES.has(statePrefix) ||
+            territoryVisibility.statePrefixes.has(statePrefix)
+          )
+        })
+        topoData.counties = topoData.counties.filter(county => {
+          const countyPrefix = county.id?.substring(0, 2)
+          return (
+            !countyPrefix ||
+            !US_TERRITORY_STATE_FIPS_PREFIXES.has(countyPrefix) ||
+            territoryVisibility.countyIds.has(county.id)
+          )
+        })
+      }
+      if (showHSABoundaries) {
+        const mappingResponse = await import(
+          /* webpackChunkName: "hsa_fips_mapping" */ './../data/hsa_fips_mapping.json'
+        )
+        const hsaMapping = mappingResponse.default.reduce((acc, curr) => {
+          acc[curr.county_fips] = curr.hsa_no
+          return acc
+        }, {} as Record<string, string>)
+        const countyGeometries = response.objects.counties.geometries
+        const geometriesByGroup = countyGeometries.reduce((acc, geometry) => {
+          const groupId = hsaMapping[geometry.id]
+          if (!groupId) return acc
+
+          if (!acc[groupId]) acc[groupId] = []
+          acc[groupId].push(geometry)
+          return acc
+        }, {} as Record<string, any[]>)
+        topoData.hsas = Object.entries(geometriesByGroup).map(([groupId, geometries]) => ({
+          groupId,
+          feature: merge(response as any, geometries)
+        }))
+        topoData.hsaMapping = hsaMapping
+      }
       topoData.states.sort(sortById)
       topoData.counties.sort(sortById)
       topoData.mapData = topoData.states.concat(topoData.counties).filter(geo => geo.id !== '51620') //Not sure why, but Franklin City, VA is very broken and messes up the rendering
-      topoData.countyIndecies = {}
       topoData.states.forEach(state => {
         let minIndex = topoData.mapData.length - 1
         let maxIndex = 0
 
         for (let i = 0; i < topoData.mapData.length; i++) {
-          if (topoData.mapData[i].id.length > 2 && topoData.mapData[i].id.indexOf(state.id) === 0) {
+          if (topoData.mapData[i].id?.length > 2 && topoData.mapData[i].id?.indexOf(state.id) === 0) {
             if (i < minIndex) minIndex = i
             if (i > maxIndex) maxIndex = i
           }
@@ -70,7 +171,6 @@ const getTopoData = year => {
         topoData.countyIndecies[state.id] = [minIndex, maxIndex]
       })
       topoData.projection = geoAlbersUsaTerritories()
-
       resolve(topoData)
     }
 
@@ -127,8 +227,7 @@ const getCurrentTopoYear = (config: MapConfig, runtimeFilters) => {
 }
 
 const isTopoReady = (topoData, config: MapConfig, runtimeFilters) => {
-  let currentYear = getCurrentTopoYear(config, runtimeFilters)
-
+  const currentYear = getCurrentTopoYear(config, runtimeFilters)
   return topoData.year && (!currentYear || currentYear === topoData.year)
 }
 
@@ -140,6 +239,9 @@ const CountyMap = () => {
     runtimeFilters,
     runtimeLegend,
     setConfig,
+    filteredStateCode,
+    setFilteredStateCountyCode,
+    filteredCountyCode,
     config,
     tooltipId,
     tooltipRef,
@@ -152,12 +254,27 @@ const CountyMap = () => {
   const geoStrokeColor = getGeoStrokeColor(config)
   const { geoClickHandler } = useGeoClickHandler()
   const { applyTooltipsToGeo } = useApplyTooltipsToGeo()
-  const [focus, setFocus] = useState({})
-  const [topoData, setTopoData] = useState({})
+  const [topoData, setTopoData] = useState<TopoData>({} as TopoData)
+  const focus = useMemo(() => {
+    if (!isTopoReady(topoData, config, runtimeFilters) || !filteredStateCode) return {} as Focus
+    const stateGeo = topoData.states.find(state => state.id === filteredStateCode)
+    if (!stateGeo) return {} as Focus
+    return {
+      id: stateGeo.id,
+      index: topoData.mapData.findIndex(geo => geo.id === stateGeo.id),
+      center: geoCentroid(stateGeo),
+      feature: stateGeo
+    } as Focus
+  }, [filteredStateCode, topoData, config, runtimeFilters])
+  const [hasMoved, setHasMoved] = useState(false)
 
   const pathGenerator = geoPath().projection(geoAlbersUsaTerritories())
 
   const { featureArray } = useMapLayers(config, setConfig, pathGenerator, tooltipId)
+  const territoryVisibility = useMemo(
+    () => getCountyTerritoryVisibility(config.general.territoriesAlwaysShow, runtimeData),
+    [config.general.territoriesAlwaysShow, runtimeData]
+  )
 
   useEffect(() => {
     if (containerEl) {
@@ -167,27 +284,53 @@ const CountyMap = () => {
     }
   })
 
+  const getAndSetTopoData = currentYear => {
+    getTopoData(
+      currentYear,
+      config.general.showHSABoundaries,
+      territoryVisibility,
+      config.migrations.showPuertoRico
+    ).then(response => {
+      if (canvasRef.current) {
+        const context = canvasRef.current.getContext('2d') as CanvasRenderingContext2D
+        context.clearRect(0, 0, canvasRef.current.width, canvasRef.current.height)
+      }
+      setTopoData(response)
+    })
+  }
+
   useEffect(() => {
-    let currentYear = getCurrentTopoYear(config, runtimeFilters)
+    const currentYear = getCurrentTopoYear(config, runtimeFilters)
 
     if (currentYear !== topoData.year) {
-      getTopoData(currentYear).then(response => {
-        if (canvasRef.current) {
-          const context = canvasRef.current.getContext('2d')
-          context.clearRect(canvasRef.current.width, canvasRef.current.height)
-        }
-        setTopoData(response)
-      })
+      getAndSetTopoData(currentYear)
     }
-  }, [config.general.countyCensusYear, config.general.filterControlsCountyYear, JSON.stringify(runtimeFilters)])
+  }, [
+    config.general.countyCensusYear,
+    config.general.filterControlsCountyYear,
+    JSON.stringify(runtimeFilters),
+    territoryVisibility.key
+  ])
+
+  const prevShowHSABoundariesRef = useRef(config.general.showHSABoundaries)
+  useEffect(() => {
+    if (prevShowHSABoundariesRef.current === config.general.showHSABoundaries) return
+    const currentYear = getCurrentTopoYear(config, runtimeFilters)
+    getAndSetTopoData(currentYear)
+    prevShowHSABoundariesRef.current = config.general.showHSABoundaries
+  }, [config.general.showHSABoundaries])
+
+  const prevTerritoryVisibilityRef = useRef(territoryVisibility.key)
+  useEffect(() => {
+    if (prevTerritoryVisibilityRef.current === territoryVisibility.key) return
+    const currentYear = getCurrentTopoYear(config, runtimeFilters)
+    getAndSetTopoData(currentYear)
+    prevTerritoryVisibilityRef.current = territoryVisibility.key
+  }, [territoryVisibility.key])
 
   // Whenever the memo at the top is triggered and the map is called to re-render, call drawCanvas and update
   // The resize function so it includes the latest state variables
   useEffect(() => {
-    if (isTopoReady(topoData, config, runtimeFilters)) {
-      drawCanvas()
-    }
-
     const onResize = () => {
       if (canvasRef.current && isTopoReady(topoData, config, runtimeFilters)) {
         drawCanvas()
@@ -201,28 +344,74 @@ const CountyMap = () => {
     return () => window.removeEventListener('resize', debounceOnResize)
   })
 
-  const resetButton = useRef()
   const canvasRef = useRef()
   const patternCacheRef = useRef<Map<string, CanvasPattern | null>>(new Map())
+  const zoomTransformRef = useRef(d3ZoomIdentity)
+  const zoomBehaviorRef = useRef()
+  const zoomFrameRef = useRef<number | null>(null)
+  const geoPathCacheRef = useRef<Map<string, Path2D>>(new Map())
 
   // Clear pattern cache when pattern configuration changes
   useEffect(() => {
     patternCacheRef.current.clear()
   }, [config.map?.patterns])
 
-  // If runtimeData is not defined, show loader
-  if (!runtimeData || !isTopoReady(topoData, config, runtimeFilters)) {
-    return (
-      <div style={{ height: 300 }}>
-        <Loading />
-      </div>
-    )
+  const runtimeKeys = runtimeData ? Object.keys(runtimeData) : []
+  const lineWidth = 1
+
+  // Pre-compute Path2D objects for all geo features — avoids expensive geoPath projection on every zoom frame
+  const buildPathCache = () => {
+    const pathGen = geoPath(topoData.projection)
+    const cache = new Map<string, Path2D>()
+    topoData.mapData.forEach(geo => {
+      if (!geo.id) return
+      const d = pathGen(geo)
+      if (d) cache.set(geo.id, new Path2D(d))
+    })
+    topoData.states.forEach(state => {
+      if (!state.id) return
+      const d = pathGen(state)
+      if (d) cache.set('state_border_' + state.id, new Path2D(d))
+    })
+    topoData.hsas.forEach(hsa => {
+      if (!hsa?.groupId || !hsa?.feature) return
+      const d = pathGen(hsa.feature as any)
+      if (d) cache.set('hsa_border_' + hsa.groupId, new Path2D(d))
+    })
+    geoPathCacheRef.current = cache
   }
 
-  const runtimeKeys = Object.keys(runtimeData)
-  const lineWidth = 1
+  const resetZoomTransform = () => {
+    zoomTransformRef.current = d3ZoomIdentity
+    if (canvasRef.current && zoomBehaviorRef.current) {
+      d3Select(canvasRef.current).call(zoomBehaviorRef.current.transform, d3ZoomIdentity)
+    }
+  }
+
+  const getCanvasPoints = e => {
+    const canvas = e.target
+    const canvasBounds = canvas.getBoundingClientRect()
+    const x = e.clientX - canvasBounds.left
+    const y = e.clientY - canvasBounds.top
+    const [mapX, mapY] = zoomTransformRef.current.invert([x, y])
+    return { canvas, mapX, mapY }
+  }
+
+  const applyZoomTransform = context => {
+    const { x, y, k } = zoomTransformRef.current || d3ZoomIdentity
+    context.setTransform(k, 0, 0, k, x, y)
+  }
+
+  const getZoomScale = () => zoomTransformRef.current?.k || 1
 
-  const paintCountyGeo = (context, path, geo, geoData, canvasWidth: number) => {
+  const paintCountyGeo = (
+    context,
+    path2d: Path2D,
+    geoData,
+    canvasWidth: number,
+    strokeWidth?: number,
+    strokeColor?: string
+  ) => {
     const legendValues =
       geoData !== undefined
         ? applyLegendToRow(geoData, config, runtimeLegend, legendMemo, legendSpecialClassLastMemo)
@@ -236,9 +425,7 @@ const CountyMap = () => {
         : DEFAULT_MAP_BACKGROUND
 
     context.fillStyle = baseFill
-    context.beginPath()
-    path(geo)
-    context.fill()
+    context.fill(path2d)
 
     if (config.map?.patterns?.length > 0 && geoData) {
       const patternInfo = getPatternForRow(geoData, config)
@@ -247,8 +434,8 @@ const CountyMap = () => {
         const { pattern, size, color } = patternInfo
         const patternColor = color || '#000000'
         const patternSize = size || 'medium'
-        const strokeWidth = canvasWidth < 200 ? 1.75 : canvasWidth < 375 ? 1.25 : 0.75
-        const cacheKey = `${pattern}-${patternColor}-${patternSize}-${strokeWidth}`
+        const patternStrokeWidth = canvasWidth < 200 ? 1.75 : canvasWidth < 375 ? 1.25 : 0.75
+        const cacheKey = `${pattern}-${patternColor}-${patternSize}-${patternStrokeWidth}`
 
         let canvasPattern = patternCacheRef.current.get(cacheKey)
         if (!canvasPattern) {
@@ -256,7 +443,7 @@ const CountyMap = () => {
             pattern as PatternType,
             patternColor,
             patternSize as 'small' | 'medium' | 'large',
-            strokeWidth
+            patternStrokeWidth
           )
           if (canvasPattern) {
             patternCacheRef.current.set(cacheKey, canvasPattern)
@@ -265,18 +452,14 @@ const CountyMap = () => {
 
         if (canvasPattern) {
           context.fillStyle = canvasPattern
-          context.beginPath()
-          path(geo)
-          context.fill()
+          context.fill(path2d)
         }
       }
     }
 
-    context.strokeStyle = geoStrokeColor
-    context.lineWidth = lineWidth
-    context.beginPath()
-    path(geo)
-    context.stroke()
+    context.strokeStyle = strokeColor ?? geoStrokeColor
+    context.lineWidth = strokeWidth ?? lineWidth
+    context.stroke(path2d)
 
     return legendValues
   }
@@ -294,18 +477,85 @@ const CountyMap = () => {
       ...config,
       mapPosition: { coordinates: [0, 30], zoom: 1 }
     })
-    setFocus({})
+    setFilteredStateCountyCode('')
+    resetZoomTransform()
+  }
+
+  const handleZoomIn = () => {
+    if (!canvasRef.current || !zoomBehaviorRef.current) return
+    d3Select(canvasRef.current).call(zoomBehaviorRef.current.scaleBy, 1.2)
+  }
+
+  const handleZoomOut = () => {
+    if (!canvasRef.current || !zoomBehaviorRef.current) return
+    d3Select(canvasRef.current).call(zoomBehaviorRef.current.scaleBy, 1 / 1.2)
+  }
+
+  const handleZoomReset = () => {
+    const container = canvasRef.current?.closest('.geography-container') as HTMLElement | null
+    setHasMoved(false)
+    onReset()
+    container?.focus()
+  }
+
+  const PAN_STEP = 20
+
+  useEffect(() => {
+    if (!config.general.allowMapZoom) return
+
+    const container = canvasRef.current?.closest('.geography-container') as HTMLElement | null
+    if (!container) return
+
+    const handleKeyboardPan = (e: KeyboardEvent) => {
+      if (!canvasRef.current || !zoomBehaviorRef.current) return
+
+      const key = e.key.toLowerCase()
+      let dx = 0
+      let dy = 0
+
+      switch (key) {
+        case 'arrowleft':
+        case 'a':
+          dx = PAN_STEP
+          break
+        case 'arrowright':
+        case 'd':
+          dx = -PAN_STEP
+          break
+        case 'arrowup':
+        case 'w':
+          dy = PAN_STEP
+          break
+        case 'arrowdown':
+        case 's':
+          dy = -PAN_STEP
+          break
+        default:
+          return
+      }
+
+      e.preventDefault()
+      d3Select(canvasRef.current).call(zoomBehaviorRef.current.translateBy, dx, dy)
+    }
+
+    container.addEventListener('keydown', handleKeyboardPan)
+    return () => container.removeEventListener('keydown', handleKeyboardPan)
+  }, [config.general.allowMapZoom, topoData, runtimeLegend, focus])
+
+  const scheduleDraw = () => {
+    if (zoomFrameRef.current) return
+    zoomFrameRef.current = window.requestAnimationFrame(() => {
+      zoomFrameRef.current = null
+      renderFrame()
+    })
   }
 
   const canvasClick = e => {
-    const canvas = e.target
-    const canvasBounds = canvas.getBoundingClientRect()
-    const x = e.clientX - canvasBounds.left
-    const y = e.clientY - canvasBounds.top
-    const pointCoordinates = topoData.projection.invert([x, y])
+    const { mapX, mapY } = getCanvasPoints(e)
+    const pointCoordinates = topoData.projection.invert([mapX, mapY])
 
     // Use d3 geoContains method to find the state geo data that the user clicked inside
-    let clickedState
+    let clickedState: Geometry
     for (let i = 0; i < topoData.states.length; i++) {
       if (geoContains(topoData.states[i], pointCoordinates)) {
         clickedState = topoData.states[i]
@@ -314,13 +564,9 @@ const CountyMap = () => {
     }
 
     // If the user clicked outside of all states, no behavior
+    let clickedCounty = ''
     if (clickedState) {
-      setConfig({
-        ...config,
-        mapPosition: { coordinates: [0, 30], zoom: 3 }
-      })
-
-      // If a county within the state was also clicked and has data, call parent click handler
+      // If a county within the state was clicked and has data, call parent click handler
       if (topoData.countyIndecies[clickedState.id]) {
         let county
         for (
@@ -335,28 +581,32 @@ const CountyMap = () => {
         }
         if (county && runtimeData[county.id]) {
           geoClickHandler(displayGeoName(county.id), runtimeData[county.id])
+          if (filteredStateCode) {
+            if (filteredStateCode === clickedState.id) {
+              clickedCounty = county.id || ''
+            }
+          }
         }
       }
 
-      let focusIndex = -1
-      for (let i = 0; i < topoData.mapData.length; i++) {
-        if (topoData.mapData[i].id === clickedState.id) {
-          focusIndex = i
-          break
-        }
+      // `us-geocode` maps still need state drilldown even when manual zoom controls are disabled.
+      if (config.general.allowMapZoom || config.general.type === 'us-geocode') {
+        setConfig({
+          ...config,
+          mapPosition: { coordinates: [0, 30], zoom: 3 }
+        })
+        setFilteredStateCountyCode(clickedState.id, clickedCounty)
+
+        publishAnalyticsEvent({
+          vizType: config.type,
+          vizSubType: getVizSubType(config),
+          eventType: `zoom_in`,
+          eventAction: 'click',
+          eventLabel: interactionLabel,
+          vizTitle: getVizTitle(config),
+          specifics: `zoom_level: 3, location: ${clickedState.properties.name}`
+        })
       }
-
-      // Redraw with focus on state
-      setFocus({ id: clickedState.id, index: focusIndex, center: geoCentroid(clickedState), feature: clickedState })
-      publishAnalyticsEvent({
-        vizType: config.type,
-        vizSubType: getVizSubType(config),
-        eventType: `zoom_in`,
-        eventAction: 'click',
-        eventLabel: interactionLabel,
-        vizTitle: getVizTitle(config),
-        specifics: `zoom_level: 3, location: ${clickedState.properties.name}`
-      })
     }
     if (config.general.type === 'us-geocode') {
       const geoRadius = (config.visual.geoCodeCircleSize || 5) * (focus.id ? 2 : 1)
@@ -368,7 +618,7 @@ const CountyMap = () => {
         ])
         if (
           pixelCoords &&
-          Math.sqrt(Math.pow(pixelCoords[0] - x, 2) + Math.pow(pixelCoords[1] - y, 2)) < geoRadius &&
+          Math.sqrt(Math.pow(pixelCoords[0] - mapX, 2) + Math.pow(pixelCoords[1] - mapY, 2)) < geoRadius &&
           !isLegendItemDisabled(
             runtimeData[runtimeKeys[i]],
             runtimeLegend,
@@ -396,44 +646,25 @@ const CountyMap = () => {
     )
       return
 
-    const canvas = e.target
-    const canvasBounds = canvas.getBoundingClientRect()
-    const x = e.clientX - canvasBounds.left
-    const y = e.clientY - canvasBounds.top
+    const { canvas, mapX, mapY } = getCanvasPoints(e)
     const containerBounds = container?.getBoundingClientRect()
     const tooltipX = e.clientX - (containerBounds?.left || 0)
     const tooltipY = e.clientY - (containerBounds?.top || 0)
-    let pointCoordinates = topoData.projection.invert([x, y])
+    let pointCoordinates = topoData.projection.invert([mapX, mapY])
 
     const currentTooltipIndex = parseInt(tooltipRef.current.getAttribute('data-index'))
     const geoRadius = (config.visual.geoCodeCircleSize || 5) * (focus.id ? 2 : 1)
+    const zoomScale = getZoomScale()
+    const strokeScale = zoomScale ? 1 / zoomScale : 1
 
     const context = canvas.getContext('2d')
-    const path = geoPath(topoData.projection, context)
+    context.save()
+    applyZoomTransform(context)
 
     // Handle standard county map hover
     if (config.general.type !== 'us-geocode') {
       //If no tooltip is shown, or if the current geo associated with the tooltip shown is no longer containing the mouse, then rerender the tooltip
       if (isNaN(currentTooltipIndex) || !geoContains(topoData.mapData[currentTooltipIndex], pointCoordinates)) {
-        if (
-          !isNaN(currentTooltipIndex) &&
-          applyLegendToRow(
-            runtimeData[topoData.mapData[currentTooltipIndex].id],
-            config,
-            runtimeLegend,
-            legendMemo,
-            legendSpecialClassLastMemo
-          )
-        ) {
-          paintCountyGeo(
-            context,
-            path,
-            topoData.mapData[currentTooltipIndex],
-            runtimeData[topoData.mapData[currentTooltipIndex].id],
-            canvas.width
-          )
-        }
-
         let hoveredState
         let county
         let countyIndex
@@ -466,16 +697,18 @@ const CountyMap = () => {
             legendSpecialClassLastMemo
           )
           if (legendValues) {
-            if (legendValues[0] === '#000000') return
+            if (legendValues[0] === '#000000') {
+              context.restore()
+              return
+            }
             context.globalAlpha = 1
-            paintCountyGeo(context, path, topoData.mapData[countyIndex], runtimeData[county.id], canvas.width)
           }
 
           // Track hover analytics event if this is a new location
           if (isNaN(currentTooltipIndex) || currentTooltipIndex !== countyIndex) {
             const countyName = displayGeoName(county.id).replace(/[^a-zA-Z0-9]/g, ' ')
-            const stateFips = county.id.slice(0, 2)
-            const stateName = supportedStatesFipsCodes[stateFips]?.replace(/[^a-zA-Z0-9]/g, '_') || 'unknown'
+            const stateCode = county.id.slice(0, 2)
+            const stateName = supportedStatesFipsCodes[stateCode]?.replace(/[^a-zA-Z0-9]/g, '_') || 'unknown'
             const locationName = `${countyName}, ${stateName}`
             publishAnalyticsEvent({
               vizType: config.type,
@@ -512,7 +745,11 @@ const CountyMap = () => {
           runtimeData[runtimeKeys[currentTooltipIndex]][config.columns.longitude.name],
           runtimeData[runtimeKeys[currentTooltipIndex]][config.columns.latitude.name]
         ])
-        if (pixelCoords && Math.sqrt(Math.pow(pixelCoords[0] - x, 2) + Math.pow(pixelCoords[1] - y, 2)) < geoRadius) {
+        if (
+          pixelCoords &&
+          Math.sqrt(Math.pow(pixelCoords[0] - mapX, 2) + Math.pow(pixelCoords[1] - mapY, 2)) < geoRadius
+        ) {
+          context.restore()
           return // The user is still hovering over the previous geo point, don't redraw tooltip
         }
       }
@@ -531,7 +768,7 @@ const CountyMap = () => {
         if (
           includedShapes &&
           pixelCoords &&
-          Math.sqrt(Math.pow(pixelCoords[0] - x, 2) + Math.pow(pixelCoords[1] - y, 2)) < geoRadius &&
+          Math.sqrt(Math.pow(pixelCoords[0] - mapX, 2) + Math.pow(pixelCoords[1] - mapY, 2)) < geoRadius &&
           applyLegendToRow(
             runtimeData[runtimeKeys[i]],
             config,
@@ -553,7 +790,7 @@ const CountyMap = () => {
         }
 
         if (config.visual.cityStyle === 'pin' && pixelCoords) {
-          const distance = Math.hypot(pixelCoords[0] - x, pixelCoords[1] - y)
+          const distance = Math.hypot(pixelCoords[0] - mapX, pixelCoords[1] - mapY)
           if (
             distance < 15 &&
             applyLegendToRow(
@@ -614,39 +851,31 @@ const CountyMap = () => {
       }
     }
 
-    if (focus.index !== -1) {
-      context.strokeStyle = geoStrokeColor
-      context.lineWidth = 1
-      context.beginPath()
-      path(topoData.mapData[focus.index])
-      context.stroke()
+    if (focus.index !== -1 && !config.general.showHSABoundaries) {
+      const focusPath2d = geoPathCacheRef.current.get(topoData.mapData[focus.index]?.id)
+      if (focusPath2d) {
+        context.strokeStyle = geoStrokeColor
+        context.lineWidth = lineWidth * strokeScale
+        context.stroke(focusPath2d)
+      }
     }
+    context.restore()
   }
 
-  // Redraws canvas. Takes as parameters the fips id of a state to center on and the [lat,long] center of that state
+  // Sets up canvas dimensions, projection, and Path2D cache, then renders.
+  // Called on data change, resize, focus change — NOT during zoom/pan.
   const drawCanvas = () => {
     if (canvasRef.current && runtimeLegend.items.length > 0) {
       const canvas = canvasRef.current
-      const context = canvas.getContext('2d')
-      const path = geoPath(topoData.projection, context)
 
       canvas.width = canvas.clientWidth
       canvas.height = canvas.width * 0.6
 
       topoData.projection.scale(canvas.width * 1.25).translate([canvas.width / 2, canvas.height / 2])
 
-      // If we are rendering the map without a zoom on a state, hide the reset button
-      if (!focus.id) {
-        if (resetButton.current) resetButton.current.style.display = 'none'
-      } else {
-        if (resetButton.current) resetButton.current.style.display = 'block'
-      }
-
-      // Centers the projection on the parameter passed
-      // Centers the projection on the parameter passed
+      // Centers the projection on the focused state
       if (focus.feature) {
         const PADDING = 10
-        // Fit the feature within the canvas dimensions with padding
         const fitExtent = [
           [PADDING, PADDING],
           [canvas.width - 0, canvas.height - PADDING]
@@ -654,117 +883,261 @@ const CountyMap = () => {
         topoData.projection.fitExtent(fitExtent, focus.feature)
       }
 
-      // Erases previous renderings before redrawing map
-      context.clearRect(0, 0, canvas.width, canvas.height)
+      // Pre-compute Path2D objects with the current projection
+      buildPathCache()
 
-      // Enforces stroke style of the county lines
-      context.strokeStyle = geoStrokeColor
+      // Render the map
+      renderFrame()
+    }
+  }
 
-      // Iterates through each state/county topo and renders it
-      topoData.mapData.forEach(geo => {
-        // If invalid geo item, don't render
-        if (!geo.id) return
-        // If the map is focused on one state, don't render counties that are not in that state
-        if (focus.id && geo.id.length > 2 && geo.id.indexOf(focus.id) !== 0) return
-        // If rendering a geocode map without a focus, don't render counties
-        if (!focus.id && config.general.type === 'us-geocode' && geo.id.length > 2) return
+  // Fast render using cached Path2D objects — called during zoom/pan for smooth performance.
+  // Skips canvas resize and projection setup; only applies the current zoom transform and redraws.
+  const renderFrame = () => {
+    if (!canvasRef.current || !runtimeLegend.items.length || !topoData.mapData) return
 
-        // Gets numeric data associated with the topo data for this state/county
-        const geoData = runtimeData[geo.id]
+    const canvas = canvasRef.current
+    const context = canvas.getContext('2d')
+    const cache = geoPathCacheRef.current
+
+    // Clear canvas
+    context.setTransform(1, 0, 0, 1, 0, 0)
+    context.clearRect(0, 0, canvas.width, canvas.height)
+    context.save()
+    applyZoomTransform(context)
+    const zoomScale = getZoomScale()
+    const strokeScale = zoomScale ? 1 / zoomScale : 1
+    const useHsaStrokeStyling = config.general.showHSABoundaries
+    const countyStrokeWidth = lineWidth * (useHsaStrokeStyling ? 0.45 : 0.8) * strokeScale
+    const hsaStrokeWidth = lineWidth * 0.7 * strokeScale
+    const countyStrokeColor = useHsaStrokeStyling ? '#a9aeb1' : geoStrokeColor
+    const isZoomedIntoState = focus.id
+    const hsaStrokeColor = isZoomedIntoState ? '#000' : '#303030'
+    const stateStrokeColor = useHsaStrokeStyling ? '#000000' : '#1c1d1f'
+
+    // Enforces stroke style of the county lines
+    context.strokeStyle = countyStrokeColor
+    context.lineWidth = countyStrokeWidth
+
+    // Iterates through each state/county topo and renders it using cached Path2D
+    let countyHighlight = null
+    topoData.mapData.forEach(geo => {
+      if (!geo.id) return
+      const hideCounty =
+        !config.general.showNeighboringStates && focus.id && geo.id.length > 2 && geo.id.indexOf(focus.id) !== 0
+      if (hideCounty) return
+      if (!focus.id && config.general.type === 'us-geocode' && geo.id.length > 2) return
+
+      const path2d = cache.get(geo.id)
+      if (!path2d) return
+
+      const geoData = runtimeData[geo.id]
+      if (!config.general.showHSABoundaries && filteredCountyCode && geo.id === filteredCountyCode) {
+        countyHighlight = {
+          context,
+          path2d,
+          geoData,
+          canvasWidth: canvas.width,
+          strokeWidth: 2,
+          strokeColor: '#000000'
+        }
+      }
+      paintCountyGeo(context, path2d, geoData, canvas.width, countyStrokeWidth, countyStrokeColor)
+    })
 
-        // Renders state/county
-        paintCountyGeo(context, path, geo, geoData, canvas.width)
+    let hsaHighlight = null
+    if (config.general.showHSABoundaries) {
+      context.strokeStyle = hsaStrokeColor
+      context.lineWidth = hsaStrokeWidth
+
+      topoData.hsas.forEach(hsa => {
+        if (!hsa?.groupId) return
+        const cacheKey = 'hsa_border_' + hsa.groupId
+        const path2d = cache.get(cacheKey)
+        if (path2d) {
+          if (filteredCountyCode && topoData.hsaMapping[filteredCountyCode] === hsa.groupId) {
+            hsaHighlight = path2d
+          } else {
+            context.stroke(path2d)
+          }
+        }
       })
+    }
 
-      // If the focused state is found in the geo data, render it with a thicker outline
-      if (focus.index !== -1) {
-        context.strokeStyle = geoStrokeColor
-        context.lineWidth = 2
-        context.beginPath()
-        path(topoData.mapData[focus.index])
-        context.stroke()
+    // State borders
+    context.strokeStyle = stateStrokeColor
+    context.lineWidth = lineWidth * 1.25 * strokeScale
+    topoData.states.forEach(state => {
+      if (config.migrations.showPuertoRico == false) return
+      if (!state.id) return
+      const path2d = cache.get('state_border_' + state.id)
+      if (path2d) {
+        context.stroke(path2d)
       }
+    })
 
-      // add in custom map layers
-      if (featureArray.length > 0) {
-        featureArray.map(layer => {
-          context.beginPath()
-          path(layer)
-          context.fillStyle = layer.properties.fill
-          context.strokeStyle = geoStrokeColor
-          context.lineWidth = layer.properties['stroke-width']
-          context.fill()
-          context.stroke()
-        })
+    // If the focused state is found in the geo data, render it with a thicker outline
+    if (focus.index !== -1) {
+      const focusGeoId = topoData.mapData[focus.index]?.id
+      const path2d = focusGeoId && cache.get(focusGeoId)
+      if (path2d) {
+        context.strokeStyle = config.general.showNeighboringStates ? '#000000' : geoStrokeColor
+        context.lineWidth = lineWidth * 2 * strokeScale
+        context.stroke(path2d)
       }
+    }
 
-      if (config.general.type === 'us-geocode') {
+    // Custom map layers (not cached — these are external features)
+    if (featureArray.length > 0) {
+      const layerPath = geoPath(topoData.projection, context)
+      featureArray.map(layer => {
+        context.beginPath()
+        layerPath(layer)
+        context.fillStyle = layer.properties.fill
         context.strokeStyle = geoStrokeColor
-        const geoRadius = (config.visual.geoCodeCircleSize || 5) * (focus.id ? 2 : 1)
-        const { additionalCityStyles } = config.visual || []
-        const cityStyles = Object.values(runtimeData)
-          .filter(d => additionalCityStyles.some(style => String(d[style.column]) === String(style.value)))
-          .map(d => {
-            const conditionsMatched = additionalCityStyles.find(
-              style => String(d[style.column]) === String(style.value)
-            )
-            return { ...conditionsMatched, ...d }
-          })
+        context.lineWidth = layer.properties['stroke-width']
+        context.fill()
+        context.stroke()
+      })
+    }
 
-        let cityPixelCoords = []
-        cityStyles.forEach(city => {
-          cityPixelCoords = topoData.projection([
-            city[config.columns.longitude.name],
-            city[config.columns.latitude.name]
-          ])
+    if (config.general.type === 'us-geocode') {
+      context.strokeStyle = geoStrokeColor
+      context.lineWidth = lineWidth * strokeScale
+      const geoRadius = (config.visual.geoCodeCircleSize || 5) * (focus.id ? 2 : 1)
+      const { additionalCityStyles } = config.visual || []
+      const cityStyles = Object.values(runtimeData)
+        .filter(d => additionalCityStyles.some(style => String(d[style.column]) === String(style.value)))
+        .map(d => {
+          const conditionsMatched = additionalCityStyles.find(style => String(d[style.column]) === String(style.value))
+          return { ...conditionsMatched, ...d }
+        })
 
-          if (cityPixelCoords) {
-            const legendValues = applyLegendToRow(
-              runtimeData[city?.value],
-              config,
-              runtimeLegend,
-              legendMemo,
-              legendSpecialClassLastMemo
-            )
-            if (legendValues) {
-              if (legendValues?.[0] === '#000000') return
-              const shapeType = city?.shape?.toLowerCase()
-              const shapeProperties = createShapeProperties(shapeType, cityPixelCoords, legendValues, config, geoRadius)
-              if (shapeProperties) {
-                drawShape(shapeProperties, context, config, lineWidth)
-              }
+      let cityPixelCoords = []
+      cityStyles.forEach(city => {
+        cityPixelCoords = topoData.projection([city[config.columns.longitude.name], city[config.columns.latitude.name]])
+
+        if (cityPixelCoords) {
+          const legendValues = applyLegendToRow(
+            runtimeData[city?.value],
+            config,
+            runtimeLegend,
+            legendMemo,
+            legendSpecialClassLastMemo
+          )
+          if (legendValues) {
+            if (legendValues?.[0] === '#000000') return
+            const shapeType = city?.shape?.toLowerCase()
+            const shapeProperties = createShapeProperties(shapeType, cityPixelCoords, legendValues, config, geoRadius)
+            if (shapeProperties) {
+              drawShape(shapeProperties, context, config, lineWidth * strokeScale)
             }
           }
-        })
+        }
+      })
 
-        runtimeKeys.forEach(key => {
-          const citiesList = new Set(cityStyles.map(item => item.value))
-
-          const pixelCoords = topoData.projection([
-            runtimeData[key][config.columns.longitude.name],
-            runtimeData[key][config.columns.latitude.name]
-          ])
-          if (pixelCoords && !citiesList.has(key)) {
-            const legendValues =
-              runtimeData[key] !== undefined
-                ? applyLegendToRow(runtimeData[key], config, runtimeLegend, legendMemo, legendSpecialClassLastMemo)
-                : false
-            if (legendValues) {
-              if (legendValues?.[0] === '#000000' || legendValues?.[0] === DISABLED_MAP_COLOR) return
-              const shapeType = config.visual.cityStyle.toLowerCase()
-              const shapeProperties = createShapeProperties(shapeType, pixelCoords, legendValues, config, geoRadius)
-              if (shapeProperties) {
-                drawShape(shapeProperties, context, config, lineWidth)
-              }
+      runtimeKeys.forEach(key => {
+        const citiesList = new Set(cityStyles.map(item => item.value))
+
+        const pixelCoords = topoData.projection([
+          runtimeData[key][config.columns.longitude.name],
+          runtimeData[key][config.columns.latitude.name]
+        ])
+        if (pixelCoords && !citiesList.has(key)) {
+          const legendValues =
+            runtimeData[key] !== undefined
+              ? applyLegendToRow(runtimeData[key], config, runtimeLegend, legendMemo, legendSpecialClassLastMemo)
+              : false
+          if (legendValues) {
+            if (legendValues?.[0] === '#000000' || legendValues?.[0] === DISABLED_MAP_COLOR) return
+            const shapeType = config.visual.cityStyle.toLowerCase()
+            const shapeProperties = createShapeProperties(shapeType, pixelCoords, legendValues, config, geoRadius)
+            if (shapeProperties) {
+              drawShape(shapeProperties, context, config, lineWidth * strokeScale)
             }
           }
-        })
-      }
+        }
+      })
+    }
+
+    // Highlight county last so it is visible on top of all other layers
+    if (countyHighlight) {
+      const { context, path2d, geoData, canvasWidth, strokeWidth, strokeColor } = countyHighlight
+      paintCountyGeo(context, path2d, geoData, canvasWidth, strokeWidth, strokeColor)
+    }
+    // Highlight HSA boundary if applicable
+    if (hsaHighlight) {
+      context.lineWidth = 2.5 * strokeScale
+      context.strokeStyle = hsaStrokeColor
+      context.stroke(hsaHighlight)
     }
+    context.restore()
   }
 
+  useEffect(() => {
+    if (!config.general.allowMapZoom) {
+      setFilteredStateCountyCode('')
+      setHasMoved(false)
+      resetZoomTransform()
+    }
+  }, [config.general.allowMapZoom])
+
+  useEffect(() => {
+    if (!canvasRef.current || !config.general.allowMapZoom) {
+      return
+    }
+
+    const COUNTY_MAX_ZOOM = 10
+    const canvasSelection = d3Select(canvasRef.current)
+    const zoomBehavior = d3Zoom()
+      .filter(d3Event => (d3Event ? !d3Event.ctrlKey && !d3Event.button : false))
+      .scaleExtent([1, COUNTY_MAX_ZOOM])
+      .on('zoom', d3Event => {
+        zoomTransformRef.current = d3Event.transform
+        const { x, y, k } = d3Event.transform
+        const isAtIdentity = x === 0 && y === 0 && k === 1
+        setHasMoved(!isAtIdentity)
+        scheduleDraw()
+      })
+
+    zoomBehaviorRef.current = zoomBehavior
+    canvasSelection.call(zoomBehavior)
+
+    return () => {
+      if (zoomFrameRef.current) {
+        window.cancelAnimationFrame(zoomFrameRef.current)
+        zoomFrameRef.current = null
+      }
+      canvasSelection.on('.zoom', null)
+    }
+  }, [config.general.allowMapZoom, topoData, runtimeLegend, focus])
+
+  useEffect(() => {
+    resetZoomTransform()
+  }, [focus?.id])
+
+  const isLoading = !runtimeData || !isTopoReady(topoData, config, runtimeFilters) || !canvasRef.current
+
+  useEffect(() => {
+    if (isLoading) {
+      return
+    }
+
+    drawCanvas()
+  }, [isLoading, topoData, focus, runtimeLegend, runtimeData, featureArray, config, filteredCountyCode])
+
+  const showManualZoomControls = config.general.allowMapZoom
+  const showResetControl = (hasMoved || focus.id) && (showManualZoomControls || config.general.type === 'us-geocode')
+  const showTopRightResetControl = showResetControl && config.general.type === 'us-geocode'
+  const showBottomLeftResetControl = showResetControl && config.general.type !== 'us-geocode'
+
   return (
     <ErrorBoundary component='CountyMap'>
+      {isLoading && (
+        <div style={{ height: 300 }}>
+          <Loading />
+        </div>
+      )}
       <canvas
         ref={canvasRef}
         aria-label={handleMapAriaLabels(config)}
@@ -774,12 +1147,37 @@ const CountyMap = () => {
           tooltipRef.current.setAttribute('data-index', null)
         }}
         onClick={canvasClick}
-        className='county-map-canvas'
+        className={'county-map-canvas' + (isLoading ? ' d-none' : '')}
+        style={config.general.allowMapZoom ? undefined : { cursor: 'default' }}
       ></canvas>
 
-      <button className={`btn btn--reset btn-primary p-absolute`} onClick={onReset} ref={resetButton} tabIndex={0}>
-        Reset Zoom
-      </button>
+      {showManualZoomControls && (
+        <div className={'zoom-controls' + (isLoading ? ' d-none' : '')} data-html2canvas-ignore='true'>
+          <button onClick={handleZoomIn} aria-label='Zoom In'>
+            <svg viewBox='0 0 24 24' stroke='currentColor' strokeWidth='3'>
+              <line x1='12' y1='5' x2='12' y2='19' />
+              <line x1='5' y1='12' x2='19' y2='12' />
+            </svg>
+          </button>
+          <button onClick={handleZoomOut} aria-label='Zoom Out'>
+            <svg viewBox='0 0 24 24' stroke='currentColor' strokeWidth='3'>
+              <line x1='5' y1='12' x2='19' y2='12' />
+            </svg>
+          </button>
+          {showBottomLeftResetControl && (
+            <button onClick={handleZoomReset} className='reset' aria-label='Reset Zoom'>
+              Reset Zoom
+            </button>
+          )}
+        </div>
+      )}
+      {showTopRightResetControl && (
+        <div className='zoom-controls zoom-controls--top-right' data-html2canvas-ignore='true'>
+          <button onClick={handleZoomReset} className='reset' aria-label='Reset Zoom'>
+            Reset Zoom
+          </button>
+        </div>
+      )}
     </ErrorBoundary>
   )
 }