@cdc/chart 4.26.4 → 4.26.6

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

@@ -0,0 +1,128 @@
+import { useContext, useMemo } from 'react'
+import { LegendItem, LegendLabel } from '@visx/legend'
+import LegendShape from '@cdc/core/components/LegendShape'
+import ConfigContext from '../../../ConfigContext'
+import { buildHeatMapData, getHeatMapBucketPalette, getHeatMapDataGroupRanges } from '../helpers'
+import { ChartConfig } from '../../../types/ChartConfig'
+
+const getHeatMapLegendClasses = (config: ChartConfig) => {
+  const { position = 'top', singleRow = true, verticalSorted } = config.legend || {}
+  const hideBorder = config.legend?.hideBorder
+  const hideSideBorder = hideBorder && typeof hideBorder === 'object' ? hideBorder.side : Boolean(hideBorder)
+  const hideTopBottomBorder = hideBorder && typeof hideBorder === 'object' ? hideBorder.topBottom : Boolean(hideBorder)
+  const containerClasses = ['legend-container', 'cdc-heatmap__legend', position].filter(Boolean)
+  const innerClasses = ['legend-container__inner']
+
+  if (['bottom', 'top'].includes(position)) {
+    innerClasses.push(singleRow ? 'single-row' : 'double-column', position)
+  }
+
+  if (['bottom', 'top'].includes(position) && verticalSorted) {
+    innerClasses.push('vertical-sorted')
+  }
+
+  if (
+    (['right', 'left'].includes(position) && hideSideBorder) ||
+    (['top', 'bottom'].includes(position) && hideTopBottomBorder)
+  ) {
+    containerClasses.push('border-0', 'p-0')
+  } else {
+    containerClasses.push('p-3')
+  }
+
+  return { containerClasses, innerClasses }
+}
+
+const HeatMapGradientLegend = () => {
+  const { filteredData, excludedData, config, formatNumber, parseDate } = useContext(ConfigContext)
+
+  const rows = filteredData?.length ? filteredData : excludedData || []
+  const xDataKey = config.xAxis?.dataKey
+  const heatMapSeries = config.series || []
+
+  const { minValue, maxValue } = useMemo(
+    () =>
+      buildHeatMapData({
+        data: rows as Record<string, any>[],
+        xDataKey,
+        series: heatMapSeries,
+        seriesLabels: config.runtime?.seriesLabels,
+        xAxisType: config.xAxis?.type,
+        parseDate
+      }),
+    [rows, xDataKey, heatMapSeries, config.runtime?.seriesLabels, config.xAxis?.type, parseDate]
+  )
+
+  const palette = getHeatMapBucketPalette(config)
+  const legendLabel = config.legend?.label
+  const valueLabel = legendLabel ? undefined : 'Value'
+  const { containerClasses, innerClasses } = getHeatMapLegendClasses(config)
+  const isGradientLegend = !config.legend?.style || config.legend?.style === 'gradient'
+  const shape = config.legend?.style === 'circles' ? 'circle' : 'square'
+  const ranges = getHeatMapDataGroupRanges(config, minValue, maxValue, formatNumber)
+  const displayRanges = config.legend?.reverseLabelOrder ? [...ranges].reverse() : ranges
+  const displayPalette = config.legend?.reverseLabelOrder ? [...palette].reverse() : palette
+  const displayLegendItems = displayRanges.map((range, index) => ({
+    color: displayPalette[index % displayPalette.length],
+    range
+  }))
+
+  if (config.legend?.hide) return null
+
+  return (
+    <aside id='legend' className={containerClasses.join(' ')} role='region' aria-label='legend' tabIndex={0}>
+      {config.legend?.label && <h3 className='cdc-heatmap__legend-title'>{config.legend.label}</h3>}
+      {config.legend?.description && <p className='cdc-heatmap__legend-description'>{config.legend.description}</p>}
+
+      {isGradientLegend ? (
+        <div className='cdc-heatmap__legend-scale'>
+          <svg className='cdc-heatmap__legend-svg' height='25' width='100%'>
+            <rect x='0' y='0' width='100%' height='25' fill='#d3d3d3' />
+            {displayLegendItems.map(({ color, range }, index) => (
+              <rect
+                key={`heatmap-gradient-block-${range.min}-${range.max}-${color}`}
+                x={`${(index / displayLegendItems.length) * 100}%`}
+                y='1'
+                width={`${100 / displayLegendItems.length}%`}
+                height='23'
+                fill={color}
+              />
+            ))}
+          </svg>
+          <div
+            className='cdc-heatmap__legend-range-labels'
+            style={{ gridTemplateColumns: `repeat(${Math.max(displayLegendItems.length, 1)}, minmax(0, 1fr))` }}
+          >
+            {displayLegendItems.map(({ range }) => (
+              <span
+                className='cdc-heatmap__legend-range-label'
+                key={`heatmap-gradient-label-${range.min}-${range.max}`}
+              >
+                {range.label}
+              </span>
+            ))}
+          </div>
+
+          {valueLabel && <div className='cdc-heatmap__legend-series-label'>{valueLabel}</div>}
+        </div>
+      ) : (
+        <div className={innerClasses.join(' ')}>
+          {displayLegendItems.map(({ color, range }) => (
+            <LegendItem
+              className='legend-item not-clickable'
+              key={`heatmap-legend-range-${range.min}-${range.max}`}
+              tabIndex={-1}
+            >
+              <LegendShape shape={shape} fill={color} />
+              <LegendLabel align='left' className='m-0'>
+                {range.label}
+              </LegendLabel>
+            </LegendItem>
+          ))}
+        </div>
+      )}
+    </aside>
+  )
+}
+
+export default HeatMapGradientLegend

package/src/components/HeatMap/heatmap.constants.ts

@@ -0,0 +1,13 @@
+import { type HeatMapConfig } from '../../types/ChartConfig'
+
+export const MIN_HEATMAP_COLOR_BUCKETS = 1
+export const MAX_HEATMAP_COLOR_BUCKETS = 9
+
+export const HEATMAP_CONFIG_DEFAULTS: Required<HeatMapConfig> = {
+  cellPadding: 1,
+  rowLabelGap: 32,
+  columnLabelGap: 56,
+  colorBucketCount: 9,
+  xAxisPosition: 'top',
+  showCellValues: false
+}

package/src/components/HeatMap/heatmap.css

@@ -0,0 +1,85 @@
+.cove-visualization .cdc-heatmap {
+  --cove-heatmap-empty-cell-color: var(--lightestGray, #f3f4f6);
+  --cove-heatmap-cell-stroke-color: rgba(255, 255, 255, 0.7);
+  --cove-heatmap-cell-stroke-width: 0.1px;
+  --cove-heatmap-axis-title-color: var(--darkGray, #333);
+  --cove-heatmap-axis-title-font-size: 18px;
+
+  width: 100%;
+}
+
+.cove-visualization .cdc-heatmap__cell {
+  stroke: var(--cove-heatmap-cell-stroke-color);
+  stroke-width: var(--cove-heatmap-cell-stroke-width);
+}
+
+.cove-visualization .cdc-heatmap__cell--empty {
+  fill: var(--cove-heatmap-empty-cell-color);
+}
+
+.cove-visualization .cdc-heatmap__cell-value {
+  font-weight: 700;
+  pointer-events: none;
+  user-select: none;
+}
+
+.cove-visualization .cdc-heatmap__axis-title {
+  fill: var(--cove-heatmap-axis-title-color);
+  font-size: var(--cove-heatmap-axis-title-font-size);
+}
+
+.cove-visualization .cdc-heatmap__body-wrap {
+  row-gap: 1rem;
+}
+
+.cove-visualization .cdc-heatmap__container .legend-wrapper {
+  row-gap: 0.75rem;
+}
+
+.cove-visualization
+  .cdc-heatmap__container.legend-bottom:not(.legend-hidden)
+  .legend-wrapper
+  aside.cdc-heatmap__legend {
+  margin-top: 0 !important;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-title {
+  font-size: var(--legend-title-font-size);
+  font-weight: 700;
+  margin: 0 0 0.5rem;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-description {
+  margin: 0 0 0.75rem;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-scale {
+  width: 100%;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-svg {
+  display: block;
+  max-width: 100%;
+  overflow: visible;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-range-labels {
+  color: #333;
+  display: grid;
+  font-size: 0.875rem;
+  line-height: 1.2;
+  margin-top: 0.35rem;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-range-label {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  text-align: center;
+}
+
+.cove-visualization .cdc-heatmap__legend .cdc-heatmap__legend-series-label {
+  color: #333;
+  font-weight: 600;
+  margin-top: 0.25rem;
+  text-align: center;
+}

package/src/components/HeatMap/helpers/index.ts

@@ -0,0 +1,261 @@
+import { scaleQuantize } from 'd3-scale'
+import { interpolateRgbBasis } from 'd3-interpolate'
+import { ChartConfig } from '../../types/ChartConfig'
+import { filterChartColorPalettes } from '@cdc/core/helpers/filterColorPalettes'
+import { getFallbackColorPalette, migratePaletteWithMap } from '@cdc/core/helpers/palettes/utils'
+import { paletteMigrationMap } from '@cdc/core/helpers/palettes/migratePaletteName'
+import { HEATMAP_CONFIG_DEFAULTS, MAX_HEATMAP_COLOR_BUCKETS, MIN_HEATMAP_COLOR_BUCKETS } from '../heatmap.constants'
+
+export type HeatMapSourceRow = Record<string, any>
+
+export type HeatMapCell = {
+  rowKey: string
+  rowLabel: string
+  xValue: any
+  xLabel: string
+  value: number | null
+  sourceRows: HeatMapSourceRow[]
+}
+
+export type HeatMapColumn = {
+  key: string
+  label: string
+  rawValue: any
+  bins: HeatMapCell[]
+}
+
+export type HeatMapDataGroupRange = {
+  min: number
+  max: number
+  label: string
+}
+
+type HeatMapSeries = { dataKey: string; name?: string }
+type FormatLegendValueFn = (value: number, axis?: string) => string
+
+type BuildHeatMapDataOptions = {
+  data: HeatMapSourceRow[]
+  xDataKey: string
+  series?: HeatMapSeries[]
+  seriesLabels?: Record<string, string>
+  xAxisType?: string
+  parseDate?: (value: string, showError?: boolean) => Date
+}
+
+const DEFAULT_HEATMAP_PALETTE = [
+  '#eff6fb',
+  '#d8e8f7',
+  '#bdd9ef',
+  '#96c0e0',
+  '#67a3ce',
+  '#4286be',
+  '#2068aa',
+  '#0c4f8f',
+  '#08306b'
+]
+
+const toDisplayLabel = (value: any): string => {
+  if (value === null || value === undefined || value === '') return 'No Data'
+  return String(value)
+}
+
+const isDateAxisType = (xAxisType?: string) => ['date', 'date-time'].includes(xAxisType || '')
+
+const getSeriesLabel = (seriesEntry: HeatMapSeries, seriesLabels?: Record<string, string>) =>
+  seriesLabels?.[seriesEntry.dataKey] || seriesEntry.name || seriesEntry.dataKey
+
+const createEmptyCell = (xValue: any, rowKey: string, rowLabel: string): HeatMapCell => ({
+  rowKey,
+  rowLabel,
+  xValue,
+  xLabel: toDisplayLabel(xValue),
+  value: null,
+  sourceRows: []
+})
+
+const getCellKey = (xValue: any, rowKey: string) => `${String(xValue)}__${String(rowKey)}`
+
+const getHeatMapValueDomain = (aggregated: Map<string, HeatMapCell>) => {
+  const values = Array.from(aggregated.values())
+    .map(cell => cell.value)
+    .filter((value): value is number => typeof value === 'number' && !Number.isNaN(value))
+
+  return {
+    minValue: values.length ? Math.min(...values) : 0,
+    maxValue: values.length ? Math.max(...values) : 0
+  }
+}
+
+const sortXValues = (
+  values: any[],
+  xAxisType: string | undefined,
+  parseDate?: (value: string, showError?: boolean) => Date
+) => {
+  if (!isDateAxisType(xAxisType)) {
+    return values
+  }
+
+  return [...values].sort((a, b) => {
+    const left = parseDate ? parseDate(String(a), false).getTime() : new Date(a).getTime()
+    const right = parseDate ? parseDate(String(b), false).getTime() : new Date(b).getTime()
+    return left - right
+  })
+}
+
+export const buildHeatMapData = ({
+  data,
+  xDataKey,
+  series,
+  seriesLabels,
+  xAxisType,
+  parseDate
+}: BuildHeatMapDataOptions) => {
+  const rows = Array.isArray(data) ? data : []
+  const hasSeriesMode = Array.isArray(series) && series.length > 0
+
+  if (!xDataKey || rows.length === 0 || !hasSeriesMode) {
+    return { columns: [] as HeatMapColumn[], rowLabels: [] as string[], minValue: 0, maxValue: 0 }
+  }
+
+  const xValues = Array.from(new Set(rows.map(row => row[xDataKey])))
+  const orderedXValues = sortXValues(xValues, xAxisType, parseDate)
+
+  const aggregated = new Map<string, HeatMapCell>()
+
+  rows.forEach(row => {
+    const xValue = row[xDataKey]
+
+    series.forEach(seriesEntry => {
+      const numericValue = Number(row[seriesEntry.dataKey])
+      if (Number.isNaN(numericValue)) return
+
+      const aggregateKey = getCellKey(xValue, seriesEntry.dataKey)
+      const existing = aggregated.get(aggregateKey)
+
+      if (existing) {
+        existing.value = (existing.value || 0) + numericValue
+        existing.sourceRows.push(row)
+        return
+      }
+
+      aggregated.set(aggregateKey, {
+        rowKey: seriesEntry.dataKey,
+        rowLabel: getSeriesLabel(seriesEntry, seriesLabels),
+        xValue,
+        xLabel: toDisplayLabel(xValue),
+        value: numericValue,
+        sourceRows: [row]
+      })
+    })
+  })
+
+  const orderedSeries = series.map(seriesEntry => ({
+    rowKey: seriesEntry.dataKey,
+    rowLabel: getSeriesLabel(seriesEntry, seriesLabels)
+  }))
+
+  const columns = orderedXValues.map(xValue => {
+    const bins = orderedSeries.map(({ rowKey, rowLabel }) => {
+      const aggregateKey = getCellKey(xValue, rowKey)
+      return aggregated.get(aggregateKey) || createEmptyCell(xValue, rowKey, rowLabel)
+    })
+
+    return {
+      key: String(xValue),
+      label: toDisplayLabel(xValue),
+      rawValue: xValue,
+      bins
+    }
+  })
+
+  const { minValue, maxValue } = getHeatMapValueDomain(aggregated)
+
+  return {
+    columns,
+    rowLabels: orderedSeries.map(item => item.rowLabel),
+    minValue,
+    maxValue
+  }
+}
+
+export const getHeatMapPalette = (config: ChartConfig): string[] => {
+  const colorPalettes = filterChartColorPalettes(config)
+  const configPalette = config.general?.palette?.name
+  const migratedPaletteName = configPalette || getFallbackColorPalette(config)
+  const isReversedPalette = migratedPaletteName?.endsWith('reverse')
+  const basePaletteName = isReversedPalette ? migratedPaletteName.slice(0, -7) : migratedPaletteName
+
+  let palette =
+    config.general?.palette?.customColors ||
+    colorPalettes[migratePaletteWithMap(basePaletteName, paletteMigrationMap, false)] ||
+    colorPalettes[basePaletteName] ||
+    colorPalettes[configPalette]
+
+  if (!palette || palette.length < 2) {
+    palette = DEFAULT_HEATMAP_PALETTE
+  }
+
+  const shouldReverse = config.general?.palette?.isReversed || isReversedPalette
+  return shouldReverse ? [...palette].reverse() : palette
+}
+
+export const getHeatMapColorBucketCount = (config: ChartConfig) => {
+  const numericValue = Number(config.heatmap?.colorBucketCount)
+
+  if (!Number.isFinite(numericValue)) return HEATMAP_CONFIG_DEFAULTS.colorBucketCount
+
+  return Math.min(Math.max(Math.round(numericValue), MIN_HEATMAP_COLOR_BUCKETS), MAX_HEATMAP_COLOR_BUCKETS)
+}
+
+export const getHeatMapBucketPalette = (config: ChartConfig): string[] => {
+  const palette = getHeatMapPalette(config)
+  const bucketCount = getHeatMapColorBucketCount(config)
+
+  const interpolate = interpolateRgbBasis(palette)
+  return Array.from({ length: bucketCount }, (_, index) => {
+    return interpolate(bucketCount === 1 ? 0.5 : index / (bucketCount - 1))
+  })
+}
+
+const getCleanRangeBoundary = (value: number) => Number(value.toFixed(12))
+
+const getFormattedRangeValue = (value: number, formatNumber?: FormatLegendValueFn) => {
+  const cleanValue = getCleanRangeBoundary(value)
+  return typeof formatNumber === 'function' ? String(formatNumber(cleanValue, 'left')) : String(cleanValue)
+}
+
+export const getHeatMapDataGroupRanges = (
+  config: ChartConfig,
+  minValue: number,
+  maxValue: number,
+  formatNumber?: FormatLegendValueFn
+): HeatMapDataGroupRange[] => {
+  if (maxValue <= minValue) {
+    const value = getCleanRangeBoundary(minValue)
+    return [{ min: value, max: value, label: getFormattedRangeValue(value, formatNumber) }]
+  }
+
+  const bucketCount = getHeatMapColorBucketCount(config)
+  const rangeSize = (maxValue - minValue) / bucketCount
+
+  return Array.from({ length: bucketCount }, (_, index) => {
+    const min = getCleanRangeBoundary(minValue + index * rangeSize)
+    const max = getCleanRangeBoundary(index === bucketCount - 1 ? maxValue : minValue + (index + 1) * rangeSize)
+    const formattedMin = getFormattedRangeValue(min, formatNumber)
+    const formattedMax = getFormattedRangeValue(max, formatNumber)
+
+    return {
+      min,
+      max,
+      label: min === max ? formattedMin : `${formattedMin}\u2013${formattedMax}`
+    }
+  })
+}
+
+export const getHeatMapColorScale = (config: ChartConfig, minValue: number, maxValue: number) => {
+  const bucketCount = getHeatMapColorBucketCount(config)
+  const palette = getHeatMapBucketPalette(config)
+  const domainMax = minValue === maxValue ? maxValue + 1 : maxValue
+
+  return scaleQuantize<string>().domain([minValue, domainMax]).range(palette)
+}

package/src/components/HeatMap/index.tsx

@@ -0,0 +1,5 @@
+import HeatMap from './components/HeatMap'
+
+export { HeatMap }
+export { default as HeatMapGradientLegend } from './components/HeatMapGradientLegend'
+export default HeatMap