@cdc/chart 4.26.7 → 4.26.10

package/src/components/HeatMap/components/HeatMap.tsx

@@ -1,4 +1,4 @@
-import React, { useContext, useMemo } from 'react'
+import React, { useContext, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { AxisBottom, AxisLeft, AxisTop } from '@visx/axis'
 import { Group } from '@visx/group'
 import { HeatmapRect } from '@visx/heatmap'
@@ -10,8 +10,13 @@ import { formatNumber as formatColumnNumber } from '@cdc/core/helpers/cove/numbe
 import { getTextWidth } from '@cdc/core/helpers/getTextWidth'
 import { type ChartConfig, type HeatMapXAxisPosition } from '../../../types/ChartConfig'
 import { buildTooltipListHtml } from '../../../helpers/tooltipHelpers'
-import { findColumnConfigByName, getSeriesColumnFormattingParams } from '../../../helpers/seriesColumnSettings'
-import { HEATMAP_CONFIG_DEFAULTS } from '../heatmap.constants'
+import {
+  findColumnConfigByName,
+  getAdditionalColumnFormattingParams,
+  getSeriesColumnFormattingParams
+} from '../../../helpers/seriesColumnSettings'
+import { HEATMAP_CONFIG_DEFAULTS, MAX_HEATMAP_COLUMN_WIDTH, MIN_HEATMAP_COLUMN_WIDTH } from '../heatmap.constants'
+import { getHeatMapXAxisTickValues } from '../helpers/layout'
 import './../heatmap.css'
 
 /**
@@ -53,28 +58,46 @@ type HeatMapMargins = {
 type HeatMapLayout = {
   availableWidth: number
   availableHeight: number
+  responsiveGridWidth: number
   gridWidth: number
   gridHeight: number
-  cellSize: number
-  xGroupOffset: number
+  cellWidth: number
+  cellHeight: number
   xOffset: number
   yOffset: number
 }
 
-const AXIS_TOP_WITH_TICKS = 36
-const AXIS_TOP_WITHOUT_TICKS = 24
+type HeatMapScrollState = {
+  scrollbarSpace: number
+  canScrollLeft: boolean
+  canScrollRight: boolean
+}
+
 const AXIS_TOP_LABEL_SPACE = 28
 const AXIS_TICK_FONT_SIZE = 16
+const AXIS_TICK_LENGTH = 8
 const AXIS_TITLE_SPACE = 30
+const AXIS_TITLE_FONT_SIZE = 18
 const AXIS_TOP_TITLE_BASELINE = 18
 const X_AXIS_TITLE_LABEL_SPACE = 32
 const X_AXIS_TITLE_LABEL_PADDING = 9
 const TICK_ROTATION_VERTICAL_ANCHOR_THRESHOLD = -50
 const AXIS_MARGIN_PADDING = 12
+const AXIS_OUTER_PADDING = 8
 const MIN_LEFT_MARGIN = 64
 const MAX_LEFT_MARGIN = 240
-const MIN_X_AXIS_MARGIN = 40
+const MIN_X_AXIS_MARGIN = 16
 const MAX_X_AXIS_MARGIN = 220
+const MIN_GRID_WIDTH = 24
+const MIN_GRID_HEIGHT = 24
+const MAX_HEATMAP_GRID_WIDTH = 1_000_000
+const MAX_X_AXIS_SCROLL_INSET = MAX_LEFT_MARGIN
+const SCROLL_EDGE_TOLERANCE = 1
+const DEFAULT_SCROLL_STATE: HeatMapScrollState = {
+  scrollbarSpace: 0,
+  canScrollLeft: false,
+  canScrollRight: false
+}
 const AXIS_TICK_FONT = `normal ${AXIS_TICK_FONT_SIZE}px Nunito, sans-serif`
 const DEFAULT_SERIES_LABEL = 'Series'
 const DEFAULT_VALUE_LABEL = 'Value'
@@ -105,6 +128,30 @@ const getRotatedLabelHeight = (labels: string[], rotationDegrees: number) => {
   return Math.ceil(Math.abs(Math.sin(radians)) * labelWidth + Math.abs(Math.cos(radians)) * AXIS_TICK_FONT_SIZE)
 }
 
+const getProjectedLabelWidth = (label: string, rotationDegrees: number) => {
+  const radians = (Math.abs(rotationDegrees) * Math.PI) / 180
+
+  return Math.abs(Math.cos(radians)) * getMeasuredTextWidth(label) + Math.abs(Math.sin(radians)) * AXIS_TICK_FONT_SIZE
+}
+
+const getXAxisEndpointMargins = (labels: string[], rotationDegrees: number, xAxisPosition: HeatMapXAxisPosition) => {
+  if (!labels.length) return { left: 0, right: 0 }
+
+  const firstLabelWidth = getProjectedLabelWidth(labels[0], rotationDegrees)
+  const lastLabelWidth = getProjectedLabelWidth(labels[labels.length - 1], rotationDegrees)
+
+  if (!rotationDegrees) {
+    return {
+      left: firstLabelWidth / 2 + AXIS_OUTER_PADDING,
+      right: lastLabelWidth / 2 + AXIS_OUTER_PADDING
+    }
+  }
+
+  return xAxisPosition === 'top'
+    ? { left: 0, right: lastLabelWidth + AXIS_OUTER_PADDING }
+    : { left: firstLabelWidth + AXIS_OUTER_PADDING, right: 0 }
+}
+
 const getXAxisTitleDistance = (labels: string[], rotationDegrees: number, columnLabelGap: number) => {
   const rotatedLabelHeight = getRotatedLabelHeight(labels, rotationDegrees)
   return columnLabelGap + Math.max(rotatedLabelHeight + X_AXIS_TITLE_LABEL_PADDING, X_AXIS_TITLE_LABEL_SPACE)
@@ -131,7 +178,7 @@ const getXAxisTickLabelProps = (xAxisPosition: HeatMapXAxisPosition, xTickRotati
   if (!xTickRotation) {
     return {
       fontSize: AXIS_TICK_FONT_SIZE,
-      textAnchor: 'middle',
+      textAnchor: 'middle' as const,
       angle: 0,
       dx: 0,
       y: xAxisPosition === 'top' ? -columnLabelGap : columnLabelGap
@@ -140,9 +187,9 @@ const getXAxisTickLabelProps = (xAxisPosition: HeatMapXAxisPosition, xTickRotati
 
   return {
     fontSize: AXIS_TICK_FONT_SIZE,
-    textAnchor: xAxisPosition === 'top' ? 'start' : 'end',
+    textAnchor: xAxisPosition === 'top' ? ('start' as const) : ('end' as const),
     angle: xTickRotation,
-    dx: isSteepRotation || xAxisPosition === 'top' ? 0 : '-0.5em',
+    dx: 0,
     y: xAxisPosition === 'top' ? -columnLabelGap : columnLabelGap,
     ...(isSteepRotation ? { verticalAnchor: 'middle' as const } : {})
   }
@@ -240,39 +287,54 @@ const buildChartMargins = (
   )
   const xAxisPosition = getHeatMapXAxisPosition(config)
   const xTickRotation = getNonNegativeConfigNumber(config.xAxis?.tickRotation ?? config.xAxis?.maxTickRotation, 0)
+  const endpointMargins = config.xAxis?.hideLabel
+    ? { left: 0, right: 0 }
+    : getXAxisEndpointMargins(columnLabels, xTickRotation, xAxisPosition)
   const xTickLabelSpace = config.xAxis?.hideLabel
     ? 0
     : columnLabelGap + getRotatedLabelHeight(columnLabels, xTickRotation)
+  const xAxisTitleSpace =
+    !config.hideXAxisLabel && config.xAxis?.label
+      ? getXAxisTitleDistance(config.xAxis?.hideLabel ? [] : columnLabels, xTickRotation, columnLabelGap) +
+        (xAxisPosition === 'top' ? AXIS_TITLE_FONT_SIZE : AXIS_TITLE_FONT_SIZE * 0.25)
+      : 0
   const yAxisLabel = getHeatMapYAxisLabel(config)
   const hasTopYAxisTitle = shouldRenderTopYAxisTitle(config)
   const topYAxisTitleSpace = hasTopYAxisTitle ? AXIS_TOP_LABEL_SPACE : 0
   const sideYAxisTitleSpace = !config.hideYAxisLabel && yAxisLabel && !hasTopYAxisTitle ? AXIS_TITLE_SPACE : 0
   const left = clamp(
-    Math.max(yAxisSize, rowLabelWidth + sideYAxisTitleSpace + AXIS_MARGIN_PADDING, yAxisLabel ? 96 : 72),
+    Math.max(
+      yAxisSize,
+      rowLabelWidth +
+        sideYAxisTitleSpace +
+        AXIS_MARGIN_PADDING +
+        (config.yAxis?.hideLabel
+          ? 0
+          : getNonNegativeConfigNumber(config.heatmap?.rowLabelGap, HEATMAP_CONFIG_DEFAULTS.rowLabelGap)),
+      endpointMargins.left,
+      yAxisLabel ? 96 : 72
+    ),
     MIN_LEFT_MARGIN,
     getAxisMarginMax(parentWidth, MAX_LEFT_MARGIN)
   )
-  const topBase = config.xAxis?.hideTicks ? AXIS_TOP_WITHOUT_TICKS : AXIS_TOP_WITH_TICKS
-  const topLabelSpace = !config.hideXAxisLabel && config.xAxis?.label ? AXIS_TOP_LABEL_SPACE : 0
+  const xTickSpace = config.xAxis?.hideTicks ? 0 : AXIS_TICK_LENGTH
   const xAxisMargin = clamp(
-    Math.max(xAxisSize, xTickLabelSpace + topBase + topLabelSpace + AXIS_MARGIN_PADDING),
+    Math.max(xAxisSize, Math.max(xTickLabelSpace, xAxisTitleSpace, xTickSpace) + AXIS_OUTER_PADDING),
     MIN_X_AXIS_MARGIN,
     MAX_X_AXIS_MARGIN
   )
 
   return {
     top: (xAxisPosition === 'top' ? xAxisMargin : 24) + topYAxisTitleSpace,
-    right: 16,
-    bottom: xAxisPosition === 'bottom' ? xAxisMargin : 20,
+    right: clamp(endpointMargins.right, 16, getAxisMarginMax(parentWidth, MAX_LEFT_MARGIN)),
+    bottom: xAxisPosition === 'bottom' ? xAxisMargin : AXIS_OUTER_PADDING,
     left
   }
 }
 
 /**
- * Build a square-cell matrix that behaves like a heatmap, not a continuous x/y plot.
- * The grid is centered as a complete block, while `xOffset` is the configured
- * row-label-to-grid gap. Keeping that as an explicit HeatMap option makes visual
- * tuning predictable when rows use long city, state, or category names.
+ * Build a rectangular-cell matrix that fills the area left after reserving axis margins.
+ * Row-label spacing belongs in the left margin, so the grid stays against the row axis.
  */
 const buildGridLayout = (
   parentWidth: number,
@@ -280,25 +342,26 @@ const buildGridLayout = (
   margins: HeatMapMargins,
   columnCount: number,
   rowCount: number,
-  rowLabelGap: number
+  minimumColumnWidth = 0
 ): HeatMapLayout => {
   const availableWidth = Math.max(parentWidth - margins.left - margins.right, 0)
   const availableHeight = Math.max(parentHeight - margins.top - margins.bottom, 0)
-  const columnBandWidth = availableWidth / Math.max(columnCount, 1)
-  const rowBandHeight = availableHeight / Math.max(rowCount, 1)
-  const cellSize = Math.min(columnBandWidth, rowBandHeight)
-  const gridWidth = cellSize * Math.max(columnCount, 1)
-  const gridHeight = cellSize * Math.max(rowCount, 1)
-  const xOffset = Math.min(rowLabelGap, Math.max(availableWidth - gridWidth, 0))
-  const xGroupOffset = Math.max((availableWidth - xOffset - gridWidth) / 2, 0)
+  const xOffset = 0
+  const responsiveGridWidth = Math.max(availableWidth - xOffset, 0)
+  const boundedMinimumGridWidth = Math.min(minimumColumnWidth * columnCount, MAX_HEATMAP_GRID_WIDTH)
+  const gridWidth = Math.max(responsiveGridWidth, boundedMinimumGridWidth)
+  const gridHeight = availableHeight
+  const cellWidth = gridWidth / Math.max(columnCount, 1)
+  const cellHeight = gridHeight / Math.max(rowCount, 1)
 
   return {
     availableWidth,
     availableHeight,
+    responsiveGridWidth,
     gridWidth,
     gridHeight,
-    cellSize,
-    xGroupOffset,
+    cellWidth,
+    cellHeight,
     xOffset,
     yOffset: 0
   }
@@ -323,7 +386,7 @@ const getTooltipColumns = (
     tooltipColumns.push({
       label: value.label || columnName,
       name: columnName,
-      options: getSeriesColumnFormattingParams(value) || {}
+      options: getAdditionalColumnFormattingParams(value)
     })
 
     return tooltipColumns
@@ -457,8 +520,11 @@ const HeatMap: React.FC<HeatMapProps> = ({ parentWidth, parentHeight }) => {
     formatDate,
     formatTooltipsDate,
     formatNumber,
-    handleChartAriaLabels
+    handleChartAriaLabels,
+    currentViewport
   } = useContext(ConfigContext)
+  const scrollAreaRef = useRef<HTMLDivElement>(null)
+  const [scrollState, setScrollState] = useState(DEFAULT_SCROLL_STATE)
 
   const parseDateValue: ParseDateFn =
     typeof parseDate === 'function'
@@ -499,9 +565,31 @@ const HeatMap: React.FC<HeatMapProps> = ({ parentWidth, parentHeight }) => {
     () => buildXLabelLookup(columns, config.xAxis?.type, formatDateValue, parseDateValue),
     [columns, config.xAxis?.type, formatDateValue, parseDateValue]
   )
-  const xAxisLabels = useMemo(
-    () => columns.map(column => xLabelLookup[String(column.rawValue)] || column.label),
-    [columns, xLabelLookup]
+  const columnCount = Math.max(columns.length, 1)
+  const rowCount = Math.max(rowLabels.length, 1)
+  const xAxisPosition = getHeatMapXAxisPosition(config)
+  const xTickRotation = -getNonNegativeConfigNumber(config.xAxis?.tickRotation ?? config.xAxis?.maxTickRotation, 0)
+  const yTickRotation = -getNonNegativeConfigNumber(config.yAxis?.tickRotation, 0)
+  const xAxisDomain = useMemo(() => columns.map(column => column.key), [columns])
+  const viewportNumTicks = config.xAxis?.viewportNumTicks
+  const xAxisTickColor = config.xAxis?.tickColor || '#333'
+  const requestedXAxisTickCount =
+    (currentViewport && viewportNumTicks?.[String(currentViewport)]) || config.xAxis?.numTicks
+  const marginXAxisTickValues = useMemo(
+    () =>
+      getHeatMapXAxisTickValues({
+        domain: xAxisDomain,
+        formattedLabels: xLabelLookup,
+        rotationDegrees: xTickRotation,
+        requestedCount: requestedXAxisTickCount,
+        measureLabel: getMeasuredTextWidth,
+        fontSize: AXIS_TICK_FONT_SIZE
+      }),
+    [requestedXAxisTickCount, xAxisDomain, xLabelLookup, xTickRotation]
+  )
+  const marginXAxisLabels = useMemo(
+    () => marginXAxisTickValues.map(value => xLabelLookup[value] || value),
+    [marginXAxisTickValues, xLabelLookup]
   )
 
   const tooltipXLabelLookup = useMemo(
@@ -509,38 +597,159 @@ const HeatMap: React.FC<HeatMapProps> = ({ parentWidth, parentHeight }) => {
     [columns, config.xAxis?.type, formatTooltipDateValue, parseDateValue]
   )
 
-  const margins = useMemo(
-    () => buildChartMargins(config, rowLabels, xAxisLabels, parentWidth),
-    [config, rowLabels, xAxisLabels, parentWidth]
+  const baseMargins = useMemo(
+    () => buildChartMargins(config, rowLabels, marginXAxisLabels, parentWidth),
+    [config, marginXAxisLabels, parentWidth, rowLabels]
   )
   const configuredRowLabelGap = getNonNegativeConfigNumber(
     config.heatmap?.rowLabelGap,
     HEATMAP_CONFIG_DEFAULTS.rowLabelGap
   )
-  const rowLabelGap = config.yAxis?.hideLabel ? 0 : configuredRowLabelGap
+  // Bound extreme gaps to the reserved label area so labels and the grid remain visible.
+  const rowLabelGap = config.yAxis?.hideLabel
+    ? 0
+    : Math.min(
+        configuredRowLabelGap,
+        Math.max(
+          baseMargins.left -
+            getWidestLabelWidth(rowLabels) -
+            (!config.hideYAxisLabel && getHeatMapYAxisLabel(config) && !shouldRenderTopYAxisTitle(config)
+              ? AXIS_TITLE_SPACE
+              : 0) -
+            AXIS_MARGIN_PADDING,
+          0
+        )
+      )
   const columnLabelGap = getNonNegativeConfigNumber(
     config.heatmap?.columnLabelGap,
     HEATMAP_CONFIG_DEFAULTS.columnLabelGap
   )
+  const horizontalScrollEnabled = Boolean(config.heatmap?.horizontalScroll ?? HEATMAP_CONFIG_DEFAULTS.horizontalScroll)
+  const minimumColumnWidth = horizontalScrollEnabled
+    ? clamp(
+        getNonNegativeConfigNumber(config.heatmap?.minColumnWidth, HEATMAP_CONFIG_DEFAULTS.minColumnWidth),
+        MIN_HEATMAP_COLUMN_WIDTH,
+        MAX_HEATMAP_COLUMN_WIDTH
+      )
+    : 0
 
-  const columnCount = Math.max(columns.length, 1)
-  const rowCount = Math.max(rowLabels.length, 1)
-  const { gridWidth, gridHeight, cellSize, xGroupOffset, xOffset, yOffset } = useMemo(
-    () => buildGridLayout(parentWidth, parentHeight, margins, columnCount, rowCount, rowLabelGap),
-    [parentWidth, parentHeight, margins, columnCount, rowCount, rowLabelGap]
+  const initialLayout = useMemo(
+    () => buildGridLayout(parentWidth, parentHeight, baseMargins, columnCount, rowCount, minimumColumnWidth),
+    [parentWidth, parentHeight, baseMargins, columnCount, rowCount, minimumColumnWidth]
   )
+  const isHorizontallyScrollable =
+    horizontalScrollEnabled && initialLayout.gridWidth > initialLayout.responsiveGridWidth
+  useLayoutEffect(() => {
+    if (!isHorizontallyScrollable) {
+      setScrollState(currentState =>
+        currentState.scrollbarSpace === 0 && !currentState.canScrollLeft && !currentState.canScrollRight
+          ? currentState
+          : DEFAULT_SCROLL_STATE
+      )
+      return
+    }
+
+    const scrollArea = scrollAreaRef.current
+    if (!scrollArea) return
+
+    const updateScrollState = () => {
+      const measuredSpace = Math.max(scrollArea.offsetHeight - scrollArea.clientHeight, 0)
+      const maximumScrollLeft = Math.max(scrollArea.scrollWidth - scrollArea.clientWidth, 0)
+      const normalizedScrollLeft = Math.max(scrollArea.scrollLeft, 0)
+      const canScrollLeft = normalizedScrollLeft > SCROLL_EDGE_TOLERANCE
+      const canScrollRight = normalizedScrollLeft < maximumScrollLeft - SCROLL_EDGE_TOLERANCE
+
+      setScrollState(currentState =>
+        currentState.scrollbarSpace === measuredSpace &&
+        currentState.canScrollLeft === canScrollLeft &&
+        currentState.canScrollRight === canScrollRight
+          ? currentState
+          : { scrollbarSpace: measuredSpace, canScrollLeft, canScrollRight }
+      )
+    }
+
+    updateScrollState()
+    scrollArea.addEventListener('scroll', updateScrollState, { passive: true })
+
+    if (typeof ResizeObserver === 'undefined') {
+      return () => scrollArea.removeEventListener('scroll', updateScrollState)
+    }
+
+    const resizeObserver = new ResizeObserver(updateScrollState)
+    resizeObserver.observe(scrollArea)
+    return () => {
+      scrollArea.removeEventListener('scroll', updateScrollState)
+      resizeObserver.disconnect()
+    }
+  }, [columnCount, isHorizontallyScrollable, marginXAxisLabels, minimumColumnWidth, parentHeight, parentWidth])
+  const chartHeight = Math.max(parentHeight - (isHorizontallyScrollable ? scrollState.scrollbarSpace : 0), 0)
+  const margins = useMemo(() => {
+    if (!yTickRotation || config.yAxis?.hideLabel) return baseMargins
+
+    const rotatedRowLabelHeight = getRotatedLabelHeight(rowLabels, Math.abs(yTickRotation))
+    // The last row label starts at its cell center. Its overflow and the x-axis
+    // occupy the same bottom margin; adding both reservations wastes plot height.
+    const halfRowFraction = 1 / (2 * Math.max(rowCount, 1))
+    const desiredBottomMargin = Math.max(
+      baseMargins.bottom,
+      Math.ceil(
+        (rotatedRowLabelHeight + AXIS_OUTER_PADDING - (chartHeight - baseMargins.top) * halfRowFraction) /
+          (1 - halfRowFraction)
+      )
+    )
+    const availableBottomMargin = Math.max(chartHeight - baseMargins.top - MIN_GRID_HEIGHT, 0)
+    const maximumBottomMargin = Math.max(baseMargins.bottom, availableBottomMargin)
+
+    return {
+      ...baseMargins,
+      bottom: Math.min(desiredBottomMargin, maximumBottomMargin)
+    }
+  }, [baseMargins, chartHeight, config.yAxis?.hideLabel, rowLabels, rowCount, yTickRotation])
+  const { gridWidth, gridHeight, cellWidth, cellHeight, xOffset, yOffset } = useMemo(
+    () => buildGridLayout(parentWidth, chartHeight, margins, columnCount, rowCount, minimumColumnWidth),
+    [parentWidth, chartHeight, margins, columnCount, rowCount, minimumColumnWidth]
+  )
+  const xAxisEndpointMargins = useMemo(
+    () =>
+      config.xAxis?.hideLabel
+        ? { left: 0, right: 0 }
+        : getXAxisEndpointMargins(marginXAxisLabels, xTickRotation, xAxisPosition),
+    [config.xAxis?.hideLabel, marginXAxisLabels, xAxisPosition, xTickRotation]
+  )
+  const scrollViewportWidth = Math.max(parentWidth - margins.left, 0)
+  const minimumVisibleCellWidth = Math.min(cellWidth, MIN_GRID_WIDTH)
+  const maximumViewportInset = Math.max(scrollViewportWidth - xOffset - minimumVisibleCellWidth, 0)
+  const scrollXAxisInset = isHorizontallyScrollable
+    ? Math.min(Math.max(xAxisEndpointMargins.left - cellWidth / 2, 0), MAX_X_AXIS_SCROLL_INSET, maximumViewportInset)
+    : 0
+  const plotXOffset = xOffset + scrollXAxisInset
+  const scrollContentWidth = plotXOffset + gridWidth + margins.right
   const cellGap = getNonNegativeConfigNumber(config.heatmap?.cellPadding, HEATMAP_CONFIG_DEFAULTS.cellPadding)
-  // During responsive measurement, cellSize can briefly be 0. Clamp the effective gap so SVG rects never go negative.
-  const effectiveCellGap = Math.min(cellGap, Math.max(cellSize - 1, 0))
+  // During responsive measurement, cell dimensions can briefly be 0. Clamp the effective gap so SVG rects never go negative.
+  const effectiveCellGap = Math.min(cellGap, Math.max(Math.min(cellWidth, cellHeight) - 1, 0))
+
+  const xAxisTickValues = useMemo(
+    () =>
+      getHeatMapXAxisTickValues({
+        domain: xAxisDomain,
+        formattedLabels: xLabelLookup,
+        gridWidth,
+        rotationDegrees: xTickRotation,
+        requestedCount: requestedXAxisTickCount,
+        measureLabel: getMeasuredTextWidth,
+        fontSize: AXIS_TICK_FONT_SIZE
+      }),
+    [gridWidth, requestedXAxisTickCount, xAxisDomain, xLabelLookup, xTickRotation]
+  )
 
   const xAxisScale = useMemo(
     () =>
       scaleBand<string>({
-        domain: columns.map(column => column.key),
-        range: [xOffset, xOffset + gridWidth],
+        domain: xAxisDomain,
+        range: [plotXOffset, plotXOffset + gridWidth],
         padding: 0
       }),
-    [columns, xOffset, gridWidth]
+    [gridWidth, plotXOffset, xAxisDomain]
   )
 
   const yAxisScale = useMemo(
@@ -576,30 +785,28 @@ const HeatMap: React.FC<HeatMapProps> = ({ parentWidth, parentHeight }) => {
   }
 
   const tooltipId = `cdc-open-viz-tooltip-${config.runtime.uniqueId}`
+  const scrollInstructionsId = `${tooltipId}-scroll-instructions`
   const xAxisLabel = config.xAxis?.label
   const yAxisLabel = getHeatMapYAxisLabel(config)
-  const xAxisPosition = getHeatMapXAxisPosition(config)
-  const xTickRotation = -getNonNegativeConfigNumber(config.xAxis?.tickRotation ?? config.xAxis?.maxTickRotation, 0)
-  const yTickRotation = -getNonNegativeConfigNumber(config.yAxis?.tickRotation, 0)
+  const chartAriaLabel = String(handleChartAriaLabels(config))
+  const scrollRegionLabel = `${chartAriaLabel}; ${xAxisLabel || xDataKey || 'HeatMap'}; scrollable columns`
+  const fixedYAxisAriaLabel = `${chartAriaLabel}; ${yAxisLabel || DEFAULT_SERIES_LABEL} row axis`
   const showCellValues = Boolean(config.heatmap?.showCellValues)
   const showTopYAxisTitle = shouldRenderTopYAxisTitle(config)
-  const visibleXAxisLabels = config.xAxis?.hideLabel ? [] : xAxisLabels
+  const visibleXAxisLabels = config.xAxis?.hideLabel ? [] : xAxisTickValues.map(value => xLabelLookup[value] || value)
   const xAxisTitleDistance = getXAxisTitleDistance(visibleXAxisLabels, Math.abs(xTickRotation), columnLabelGap)
-  const rowLabelTitleX = config.yAxis?.hideLabel ? 0 : -getWidestLabelWidth(rowLabels)
+  const rowLabelTitleX = config.yAxis?.hideLabel ? 0 : -getWidestLabelWidth(rowLabels) - rowLabelGap
   const sideYAxisTitleX = -Math.max(Math.abs(rowLabelTitleX) + SIDE_Y_AXIS_TITLE_GAP, AXIS_TITLE_SPACE)
   const hasXAxisTitle = !config.hideXAxisLabel && Boolean(xAxisLabel)
   const topYAxisTitleY = xAxisPosition === 'top' && hasXAxisTitle ? -xAxisTitleDistance : -AXIS_TOP_TITLE_BASELINE
-  const renderXAxisTitle = () => {
+  const renderXAxisTitle = (
+    x = plotXOffset + gridWidth / 2,
+    y = xAxisPosition === 'top' ? -xAxisTitleDistance : gridHeight + xAxisTitleDistance
+  ) => {
     if (config.hideXAxisLabel || !xAxisLabel) return null
 
     return (
-      <text
-        className='cdc-heatmap__axis-title'
-        x={xOffset + gridWidth / 2}
-        y={xAxisPosition === 'top' ? -xAxisTitleDistance : gridHeight + xAxisTitleDistance}
-        textAnchor='middle'
-        fontWeight={AXIS_TITLE_FONT_WEIGHT}
-      >
+      <text className='cdc-heatmap__axis-title' x={x} y={y} textAnchor='middle' fontWeight={AXIS_TITLE_FONT_WEIGHT}>
         {xAxisLabel}
       </text>
     )
@@ -632,134 +839,260 @@ const HeatMap: React.FC<HeatMapProps> = ({ parentWidth, parentHeight }) => {
       </text>
     )
   }
+  const cellTextWidths = new Map<string, number>()
+  const renderCells = () => (
+    <HeatmapRect
+      data={columns}
+      xScale={columnIndex => columnIndex * cellWidth + plotXOffset}
+      yScale={rowIndex => rowIndex * cellHeight + yOffset}
+      binWidth={cellWidth}
+      binHeight={cellHeight}
+      gap={effectiveCellGap}
+      bins={column => column.bins}
+      count={bin => (typeof bin.value === 'number' ? bin.value : 0)}
+    >
+      {heatmap =>
+        heatmap.map(columnBins =>
+          columnBins.map(bin => {
+            const hasValue = typeof bin.bin.value === 'number'
+            const xLabel = tooltipXLabelLookup[String(bin.bin.xValue)] || bin.bin.xLabel
+            const renderedCellWidth = Math.max(bin.width, 0)
+            const renderedCellHeight = Math.max(bin.height, 0)
+            const fillColor = hasValue ? heatMapColorScale(bin.bin.value as number) : undefined
+            const cellFontSize = Math.max(9, Math.min(16, renderedCellHeight * 0.5))
+            const cellValueText =
+              showCellValues && hasValue ? getFormattedValueText(bin.bin, formatHeatMapCellValue) : ''
+            const textWidthKey = `${cellFontSize}:${cellValueText}`
+            let cellTextWidth = cellTextWidths.get(textWidthKey)
+            if (
+              cellValueText &&
+              renderedCellWidth >= MIN_CELL_VALUE_WIDTH &&
+              renderedCellHeight >= MIN_CELL_VALUE_HEIGHT &&
+              cellTextWidth === undefined
+            ) {
+              cellTextWidth =
+                getTextWidth(cellValueText, `bold ${cellFontSize}px Nunito, sans-serif`) ??
+                cellValueText.length * cellFontSize * 0.65
+              cellTextWidths.set(textWidthKey, cellTextWidth)
+            }
+            const shouldShowCellValue =
+              showCellValues &&
+              hasValue &&
+              renderedCellWidth >= MIN_CELL_VALUE_WIDTH &&
+              renderedCellHeight >= MIN_CELL_VALUE_HEIGHT &&
+              (cellTextWidth ?? 0) <= renderedCellWidth - 4
+
+            return (
+              <React.Fragment key={`heatmap-cell-${bin.column}-${bin.row}`}>
+                <rect
+                  className={`visx-heatmap-rect cdc-heatmap__cell${hasValue ? '' : ' cdc-heatmap__cell--empty'}`}
+                  role='img'
+                  tabIndex={0}
+                  aria-label={getHeatMapCellLabel({
+                    cell: bin.bin,
+                    config,
+                    formatNumber: formatHeatMapCellValue,
+                    xLabel,
+                    xDataKey
+                  })}
+                  x={bin.x}
+                  y={bin.y}
+                  width={renderedCellWidth}
+                  height={renderedCellHeight}
+                  fill={fillColor}
+                  data-tooltip-id={tooltipId}
+                  data-tooltip-html={buildTooltipHtml({
+                    cell: bin.bin,
+                    additionalColumns,
+                    config,
+                    formatNumber: formatHeatMapCellValue,
+                    xLabel,
+                    xDataKey,
+                    showSeriesRows: getHeatMapSeriesTooltipEnabled(config, bin.bin.rowKey)
+                  })}
+                />
+                {shouldShowCellValue && (
+                  <text
+                    className='cdc-heatmap__cell-value'
+                    x={bin.x + renderedCellWidth / 2}
+                    y={bin.y + renderedCellHeight / 2}
+                    fill={getReadableCellTextColor(fillColor)}
+                    fontSize={cellFontSize}
+                    textAnchor='middle'
+                    dominantBaseline='middle'
+                    aria-hidden='true'
+                  >
+                    {cellValueText}
+                  </text>
+                )}
+              </React.Fragment>
+            )
+          })
+        )
+      }
+    </HeatmapRect>
+  )
+  const renderXAxis = () => (
+    <>
+      {!config.xAxis?.hideAxis && (
+        <line
+          className='cdc-heatmap__x-axis-line'
+          x1={0}
+          x2={plotXOffset + gridWidth}
+          y1={xAxisPosition === 'top' ? 0 : gridHeight}
+          y2={xAxisPosition === 'top' ? 0 : gridHeight}
+          stroke={xAxisTickColor}
+        />
+      )}
+
+      {xAxisPosition === 'top' ? (
+        <AxisTop
+          scale={xAxisScale}
+          tickValues={xAxisTickValues}
+          tickFormat={value => (config.xAxis?.hideLabel ? '' : xLabelLookup[String(value)] || String(value))}
+          hideAxisLine={true}
+          hideTicks={Boolean(config.xAxis?.hideTicks)}
+          hideZero={true}
+          tickStroke={xAxisTickColor}
+          tickLabelProps={() => getXAxisTickLabelProps(xAxisPosition, xTickRotation, columnLabelGap)}
+        />
+      ) : (
+        <AxisBottom
+          top={gridHeight}
+          scale={xAxisScale}
+          tickValues={xAxisTickValues}
+          tickFormat={value => (config.xAxis?.hideLabel ? '' : xLabelLookup[String(value)] || String(value))}
+          hideAxisLine={true}
+          hideTicks={Boolean(config.xAxis?.hideTicks)}
+          hideZero={true}
+          tickStroke={xAxisTickColor}
+          tickLabelProps={() => getXAxisTickLabelProps(xAxisPosition, xTickRotation, columnLabelGap)}
+        />
+      )}
+    </>
+  )
+  const renderYAxis = () => (
+    <AxisLeft
+      scale={yAxisScale}
+      tickFormat={value => (config.yAxis?.hideLabel ? '' : value)}
+      hideAxisLine={Boolean(config.yAxis?.hideAxis)}
+      hideTicks={Boolean(config.yAxis?.hideTicks)}
+      tickLabelProps={() => ({
+        fontSize: AXIS_TICK_FONT_SIZE,
+        textAnchor: 'end',
+        angle: yTickRotation,
+        x: -AXIS_TICK_LENGTH - rowLabelGap,
+        dx: yTickRotation ? '-0.25em' : 0,
+        dy: '0.33em'
+      })}
+    />
+  )
+
+  const tooltip = (
+    <ReactTooltip
+      id={tooltipId}
+      variant='light'
+      className='tooltip'
+      style={{ background: `rgba(255,255,255, ${config.tooltips.opacity / 100})`, color: 'black' }}
+    />
+  )
+
+  if (isHorizontallyScrollable) {
+    const fixedXAxisTitleY =
+      margins.top + (xAxisPosition === 'top' ? -xAxisTitleDistance : gridHeight + xAxisTitleDistance)
+    const fixedXAxisTitleX = scrollViewportWidth / 2
+
+    return (
+      <div className='cdc-heatmap cdc-heatmap--scrollable'>
+        <div
+          className='cdc-heatmap__scroll-layout'
+          style={{ gridTemplateColumns: `${margins.left}px minmax(0, 1fr)`, height: parentHeight }}
+        >
+          <svg
+            width={margins.left}
+            height={chartHeight}
+            role='img'
+            aria-label={fixedYAxisAriaLabel}
+            className='cdc-heatmap__fixed-axis-svg'
+          >
+            <Group className='cdc-heatmap__fixed-y-axis' top={margins.top} left={margins.left}>
+              {renderYAxis()}
+              {renderYAxisTitle()}
+            </Group>
+          </svg>
+          <div className='cdc-heatmap__scroll-plot'>
+            <div
+              ref={scrollAreaRef}
+              className='cdc-heatmap__scroll-area'
+              role='region'
+              tabIndex={0}
+              aria-label={scrollRegionLabel}
+              aria-describedby={scrollInstructionsId}
+            >
+              <svg
+                width={scrollContentWidth}
+                height={chartHeight}
+                aria-label={chartAriaLabel}
+                className={`cdc-heatmap__svg cdc-heatmap__scroll-content${config.animate ? ' animated' : ''}`}
+              >
+                <Group className='cdc-heatmap__plot' top={margins.top} left={0}>
+                  {renderCells()}
+                  {renderXAxis()}
+                </Group>
+              </svg>
+            </div>
+            <span id={scrollInstructionsId} className='cdcdataviz-sr-only'>
+              Scroll horizontally to view additional columns.
+            </span>
+            <div
+              className={`cdc-heatmap__scroll-cue cdc-heatmap__scroll-cue--left${
+                scrollState.canScrollLeft ? ' is-visible' : ''
+              }`}
+              style={{ bottom: scrollState.scrollbarSpace }}
+              aria-hidden='true'
+            />
+            <div
+              className={`cdc-heatmap__scroll-cue cdc-heatmap__scroll-cue--right${
+                scrollState.canScrollRight ? ' is-visible' : ''
+              }`}
+              style={{ bottom: scrollState.scrollbarSpace }}
+              aria-hidden='true'
+            />
+            {hasXAxisTitle && (
+              <svg
+                width={scrollViewportWidth}
+                height={chartHeight}
+                aria-hidden='true'
+                className='cdc-heatmap__fixed-x-title'
+              >
+                {renderXAxisTitle(fixedXAxisTitleX, fixedXAxisTitleY)}
+              </svg>
+            )}
+          </div>
+        </div>
+        {tooltip}
+      </div>
+    )
+  }
 
   return (
     <div className='cdc-heatmap'>
       <svg
         width={parentWidth}
         height={parentHeight}
-        aria-label={handleChartAriaLabels(config)}
+        aria-label={chartAriaLabel}
         className={`cdc-heatmap__svg${config.animate ? ' animated' : ''}`}
       >
-        {/* Shift the complete heatmap block, not just the cells, so row labels stay close while the block stays centered. */}
-        <Group className='cdc-heatmap__plot' top={margins.top} left={margins.left + xGroupOffset}>
-          <HeatmapRect
-            data={columns}
-            xScale={columnIndex => columnIndex * cellSize + xOffset}
-            yScale={rowIndex => rowIndex * cellSize + yOffset}
-            binWidth={cellSize}
-            binHeight={cellSize}
-            gap={effectiveCellGap}
-            bins={column => column.bins}
-            count={bin => (typeof bin.value === 'number' ? bin.value : 0)}
-          >
-            {heatmap =>
-              heatmap.map(columnBins =>
-                columnBins.map(bin => {
-                  const hasValue = typeof bin.bin.value === 'number'
-                  const xLabel = tooltipXLabelLookup[String(bin.bin.xValue)] || bin.bin.xLabel
-                  const cellWidth = Math.max(bin.width, 0)
-                  const cellHeight = Math.max(bin.height, 0)
-                  const fillColor = hasValue ? heatMapColorScale(bin.bin.value as number) : undefined
-                  const shouldShowCellValue =
-                    showCellValues &&
-                    hasValue &&
-                    cellWidth >= MIN_CELL_VALUE_WIDTH &&
-                    cellHeight >= MIN_CELL_VALUE_HEIGHT
-                  return (
-                    <React.Fragment key={`heatmap-cell-${bin.column}-${bin.row}`}>
-                      <rect
-                        className={`visx-heatmap-rect cdc-heatmap__cell${hasValue ? '' : ' cdc-heatmap__cell--empty'}`}
-                        role='img'
-                        tabIndex={0}
-                        aria-label={getHeatMapCellLabel({
-                          cell: bin.bin,
-                          config,
-                          formatNumber: formatHeatMapCellValue,
-                          xLabel,
-                          xDataKey
-                        })}
-                        x={bin.x}
-                        y={bin.y}
-                        width={cellWidth}
-                        height={cellHeight}
-                        fill={fillColor}
-                        data-tooltip-id={tooltipId}
-                        data-tooltip-html={buildTooltipHtml({
-                          cell: bin.bin,
-                          additionalColumns,
-                          config,
-                          formatNumber: formatHeatMapCellValue,
-                          xLabel,
-                          xDataKey,
-                          showSeriesRows: getHeatMapSeriesTooltipEnabled(config, bin.bin.rowKey)
-                        })}
-                      />
-                      {shouldShowCellValue && (
-                        <text
-                          className='cdc-heatmap__cell-value'
-                          x={bin.x + cellWidth / 2}
-                          y={bin.y + cellHeight / 2}
-                          fill={getReadableCellTextColor(fillColor)}
-                          fontSize={Math.max(9, Math.min(12, cellHeight * 0.35))}
-                          textAnchor='middle'
-                          dominantBaseline='middle'
-                          aria-hidden='true'
-                        >
-                          {getFormattedValueText(bin.bin, formatHeatMapCellValue)}
-                        </text>
-                      )}
-                    </React.Fragment>
-                  )
-                })
-              )
-            }
-          </HeatmapRect>
-
-          {xAxisPosition === 'top' ? (
-            <AxisTop
-              scale={xAxisScale}
-              tickFormat={value => (config.xAxis?.hideLabel ? '' : xLabelLookup[String(value)] || String(value))}
-              hideAxisLine={Boolean(config.xAxis?.hideAxis)}
-              hideTicks={Boolean(config.xAxis?.hideTicks)}
-              hideZero={true}
-              tickLabelProps={() => getXAxisTickLabelProps(xAxisPosition, xTickRotation, columnLabelGap)}
-            />
-          ) : (
-            <AxisBottom
-              top={gridHeight}
-              scale={xAxisScale}
-              tickFormat={value => (config.xAxis?.hideLabel ? '' : xLabelLookup[String(value)] || String(value))}
-              hideAxisLine={Boolean(config.xAxis?.hideAxis)}
-              hideTicks={Boolean(config.xAxis?.hideTicks)}
-              hideZero={true}
-              tickLabelProps={() => getXAxisTickLabelProps(xAxisPosition, xTickRotation, columnLabelGap)}
-            />
-          )}
-          <AxisLeft
-            scale={yAxisScale}
-            tickFormat={value => (config.yAxis?.hideLabel ? '' : value)}
-            hideAxisLine={Boolean(config.yAxis?.hideAxis)}
-            hideTicks={Boolean(config.yAxis?.hideTicks)}
-            tickLabelProps={() => ({
-              fontSize: AXIS_TICK_FONT_SIZE,
-              textAnchor: 'end',
-              angle: yTickRotation,
-              dx: yTickRotation ? '-0.25em' : 0,
-              dy: '0.33em'
-            })}
-          />
+        <Group className='cdc-heatmap__plot' top={margins.top} left={margins.left}>
+          {renderCells()}
+          {renderXAxis()}
+          {renderYAxis()}
 
           {renderXAxisTitle()}
           {renderYAxisTitle()}
         </Group>
       </svg>
-      <ReactTooltip
-        id={tooltipId}
-        variant='light'
-        className='tooltip'
-        style={{ background: `rgba(255,255,255, ${config.tooltips.opacity / 100})`, color: 'black' }}
-      />
+      {tooltip}
     </div>
   )
 }