@cdc/chart 4.26.6 → 4.26.10

package/src/components/BarChartRace/BarChartRace.tsx

@@ -0,0 +1,230 @@
+import { useContext, useEffect, useState } from 'react'
+import { animated, useTransition } from '@react-spring/web'
+import { Tooltip as ReactTooltip } from 'react-tooltip'
+import { getContrastColor } from '@cdc/core/helpers/cove/accessibility'
+import { APP_FONT_COLOR } from '@cdc/core/helpers/constants'
+import { getTextWidth } from '@cdc/core/helpers/getTextWidth'
+import PlaybackButton from '@cdc/core/components/PlaybackButton'
+import ConfigContext from '../../ConfigContext'
+import { findColumnConfigByName, getSeriesColumnFormattingParams } from '../../helpers/seriesColumnSettings'
+import { buildSeriesTooltipListHtml } from '../../helpers/tooltipHelpers'
+import { clampRaceSecondsPerFrame } from '../raceTiming'
+import usePrefersReducedMotion from '../../hooks/usePrefersReducedMotion'
+import { type BarRaceEligibility } from './helpers'
+import './bar-chart-race.css'
+
+const AXIS_LABEL_ROW_HEIGHT = 48
+const BELOW_BAR_LABEL_ROW_HEIGHT = 64
+
+type Props = {
+  parentWidth: number
+  race: BarRaceEligibility
+}
+
+const BarChartRace = ({ parentWidth, race }: Props) => {
+  const { colorScale, config, formatNumber, setRaceTiming, transformedData = [] } = useContext(ConfigContext)
+  const [frameIndex, setFrameIndex] = useState(0)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [hasStarted, setHasStarted] = useState(false)
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const secondsPerFrame = clampRaceSecondsPerFrame(config.barRace?.secondsPerFrame)
+  const totalSeconds = (race.frames.length - 1) * secondsPerFrame
+  const series = config.series[0]
+  const labelPlacement = config.yAxis?.labelPlacement || 'On Date/Category Axis'
+  const labelsBelowBar = labelPlacement === 'Below Bar'
+  const rowHeight = labelsBelowBar ? BELOW_BAR_LABEL_ROW_HEIGHT : AXIS_LABEL_ROW_HEIGHT
+  const tooltipId = `cdc-open-viz-tooltip-${config.runtime?.uniqueId || 'bar-race'}-race`
+  const frameSignature = JSON.stringify({
+    frameKey: config.xAxis?.dataKey,
+    series: config.series.map(item => [item.dataKey, item.dynamicCategory]),
+    rows: transformedData.map(row => [
+      row?.[config.xAxis?.dataKey],
+      ...config.series.flatMap(item => [row?.[item.dynamicCategory], row?.[item.dataKey]])
+    ])
+  })
+
+  useEffect(() => {
+    setFrameIndex(0)
+    setIsPlaying(false)
+    setHasStarted(false)
+    setRaceTiming?.(null)
+  }, [frameSignature])
+
+  useEffect(() => {
+    if (!isPlaying) return
+    if (secondsPerFrame === 0) {
+      setFrameIndex(Math.max(0, race.frames.length - 1))
+      setIsPlaying(false)
+      return
+    }
+    const timer = window.setInterval(() => {
+      setFrameIndex(currentFrame => {
+        if (currentFrame >= race.frames.length - 1) {
+          setIsPlaying(false)
+          return currentFrame
+        }
+        const nextFrame = currentFrame + 1
+        if (nextFrame >= race.frames.length - 1) setIsPlaying(false)
+        return nextFrame
+      })
+    }, secondsPerFrame * 1000)
+    return () => window.clearInterval(timer)
+  }, [isPlaying, race.frames.length, secondsPerFrame])
+
+  const frame = race.frames[Math.min(frameIndex, Math.max(0, race.frames.length - 1))]
+  const getCategoryColor = (seriesKey: string) => {
+    const runtimeCategory = config.runtime?.seriesKeys?.find(value => String(value).trim() === seriesKey) ?? seriesKey
+    return colorScale?.(runtimeCategory) || '#005ea8'
+  }
+  const formatValue = (item: (typeof frame.items)[number]) => {
+    const itemSeries = config.series.find(candidate => candidate.dataKey === item.dataKey) ?? series
+    const columnConfig = findColumnConfigByName(config.columns, item.dataKey)?.columnConfig
+    const columnFormatting = getSeriesColumnFormattingParams(columnConfig)
+    return (
+      formatNumber?.(
+        item.value,
+        String(itemSeries.axis || 'left').toLowerCase(),
+        false,
+        columnFormatting?.addColPrefix,
+        columnFormatting?.addColSuffix,
+        columnFormatting?.addColRoundTo
+      ) ?? String(item.value)
+    )
+  }
+  const getTooltipHtml = (item: (typeof frame.items)[number]) =>
+    buildSeriesTooltipListHtml({
+      config,
+      colorScale,
+      heading: frame.key,
+      seriesKey: item.seriesKey,
+      seriesText: `${item.category}: ${formatValue(item)}`
+    })
+  const barAreaWidth = Math.max(0, (labelsBelowBar ? parentWidth : parentWidth * 0.72) - 120)
+  const displayNumbersOnBar = Boolean(config.yAxis?.displayNumbersOnBar)
+  const isAtEnd = frameIndex === race.frames.length - 1
+  const frameAxisLabel = config.xAxis?.label || config.xAxis?.dataKey || 'Date/Category'
+
+  useEffect(() => {
+    if (!hasStarted || !frame?.key) return
+    setRaceTiming?.({
+      elapsedSeconds: frameIndex * secondsPerFrame,
+      frameKey: frame.key,
+      isPlaying,
+      totalSeconds
+    })
+  }, [frame?.key, frameIndex, hasStarted, isPlaying, secondsPerFrame, totalSeconds])
+
+  const transitions = useTransition(frame?.items ?? [], {
+    keys: item => item.category,
+    from: { opacity: 0, top: (frame?.items.length ?? 0) * rowHeight, width: 0 },
+    enter: item => ({
+      opacity: 1,
+      top: item.rank * rowHeight,
+      width: race.globalMax > 0 ? (item.value / race.globalMax) * barAreaWidth : 0
+    }),
+    update: item => ({
+      opacity: 1,
+      top: item.rank * rowHeight,
+      width: race.globalMax > 0 ? (item.value / race.globalMax) * barAreaWidth : 0
+    }),
+    leave: { opacity: 0, width: 0 },
+    immediate: prefersReducedMotion,
+    config: { tension: 170, friction: 26 }
+  })
+
+  if (!race.eligible || !frame) return null
+
+  const handlePlayback = () => {
+    setHasStarted(true)
+    if (isAtEnd) {
+      setFrameIndex(0)
+      setIsPlaying(true)
+      return
+    }
+    setIsPlaying(current => !current)
+  }
+
+  return (
+    <section
+      className={`bar-chart-race bar-chart-race--labels-${labelsBelowBar ? 'below-bar' : 'on-axis'}`}
+      aria-label={`Bar chart race for ${frame.key}`}
+    >
+      <div className='bar-chart-race__header'>
+        <PlaybackButton
+          isAtEnd={isAtEnd}
+          isPlaying={isPlaying}
+          className='bar-chart-race__playback'
+          onClick={handlePlayback}
+        />
+        <strong className='bar-chart-race__frame' aria-live='polite'>
+          {frame.key}
+        </strong>
+      </div>
+      <div className='bar-chart-race__plot' style={{ height: `${frame.items.length * rowHeight}px` }}>
+        {transitions((style, item) => {
+          const valueLabel = formatValue(item)
+          const barWidth = race.globalMax > 0 ? (item.value / race.globalMax) * barAreaWidth : 0
+          const measuredLabelWidth =
+            typeof CanvasRenderingContext2D === 'undefined'
+              ? undefined
+              : getTextWidth(valueLabel, 'normal 16px sans-serif')
+          const labelWidth = measuredLabelWidth || valueLabel.length * 8
+          const valueFitsInside = displayNumbersOnBar && labelWidth < barWidth - 5
+          const barColor = getCategoryColor(item.seriesKey)
+          const baseLabelColor = APP_FONT_COLOR || '#1c1d1f'
+          const insideLabelColor = getContrastColor(baseLabelColor, barColor) || baseLabelColor
+
+          return (
+            <animated.div
+              className='bar-chart-race__row'
+              data-category={item.category}
+              data-tooltip-id={tooltipId}
+              data-tooltip-html={getTooltipHtml(item)}
+              tabIndex={0}
+              style={{ opacity: style.opacity, top: style.top }}
+            >
+              <span className='bar-chart-race__category'>{item.category}</span>
+              <div className='bar-chart-race__bar-area'>
+                <animated.div
+                  className={`bar-chart-race__bar${valueFitsInside ? ' bar-chart-race__bar--value-inside' : ''}`}
+                  style={{ width: style.width, backgroundColor: barColor }}
+                >
+                  <span
+                    className={`bar-chart-race__value bar-chart-race__value--${valueFitsInside ? 'inside' : 'after'}`}
+                    style={valueFitsInside ? { color: insideLabelColor } : undefined}
+                  >
+                    {valueLabel}
+                  </span>
+                </animated.div>
+              </div>
+            </animated.div>
+          )
+        })}
+      </div>
+      <ReactTooltip
+        id={tooltipId}
+        variant='light'
+        arrowColor='rgba(0,0,0,0)'
+        className='tooltip'
+        style={{ background: `rgba(255,255,255, ${(config.tooltips?.opacity ?? 90) / 100})`, color: 'black' }}
+      />
+      <div className='bar-chart-race__frame-axis' role='group' aria-label={`${frameAxisLabel} axis`}>
+        <div className='bar-chart-race__frame-axis-ticks'>
+          {race.frames.map((raceFrame, index) => (
+            <span
+              className={`bar-chart-race__frame-axis-tick${index === frameIndex ? ' is-active' : ''}`}
+              aria-current={index === frameIndex ? 'step' : undefined}
+              key={raceFrame.key}
+            >
+              <span className='bar-chart-race__frame-axis-mark' aria-hidden='true' />
+              <span className='bar-chart-race__frame-axis-value'>{raceFrame.key}</span>
+            </span>
+          ))}
+        </div>
+        <span className='bar-chart-race__frame-axis-label'>{frameAxisLabel}</span>
+      </div>
+    </section>
+  )
+}
+
+export default BarChartRace

package/src/components/BarChartRace/BarChartRaceFallback.test.tsx

@@ -0,0 +1,61 @@
+import React, { forwardRef, useContext, useEffect } from 'react'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import ConfigContext from '../../ConfigContext'
+import { createMockChartContext, createMockConfig } from '../LinearChart/tests/mockConfigContext'
+import BarChartRaceFallback from './BarChartRaceFallback'
+
+vi.mock('../LinearChart', () => ({
+  default: forwardRef<SVGAElement>((_props, ref) => {
+    const { config, updateConfig } = useContext(ConfigContext)
+
+    useEffect(() => {
+      updateConfig?.({ ...config, isLollipopChart: false })
+    }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+    return (
+      <svg
+        ref={ref}
+        data-testid='fallback-chart'
+        data-is-lollipop={String(config.isLollipopChart)}
+        data-orientation={config.orientation}
+        data-style={config.barStyle}
+        data-subtype={config.visualizationSubType}
+      />
+    )
+  })
+}))
+
+describe('BarChartRaceFallback', () => {
+  it('renders a regular horizontal projection without persisting its normalization', () => {
+    const baseConfig = createMockConfig()
+    const updateConfig = vi.fn()
+    const config = createMockConfig({
+      visualizationType: 'Bar',
+      visualizationSubType: 'racing',
+      orientation: 'vertical',
+      barStyle: 'rounded',
+      isLollipopChart: true,
+      xAxis: { ...baseConfig.xAxis, anchors: ['x-axis-anchor'] },
+      yAxis: { ...baseConfig.yAxis, anchors: ['y-axis-anchor'] }
+    })
+
+    render(
+      <ConfigContext.Provider value={createMockChartContext(config, { updateConfig })}>
+        <BarChartRaceFallback parentWidth={700} parentHeight={400} />
+      </ConfigContext.Provider>
+    )
+
+    expect(screen.getByTestId('fallback-chart')).toHaveAttribute('data-subtype', 'regular')
+    expect(screen.getByTestId('fallback-chart')).toHaveAttribute('data-orientation', 'horizontal')
+    expect(screen.getByTestId('fallback-chart')).toHaveAttribute('data-style', 'flat')
+    expect(screen.getByTestId('fallback-chart')).toHaveAttribute('data-is-lollipop', 'false')
+    expect(updateConfig).not.toHaveBeenCalled()
+    expect(config).toMatchObject({
+      barStyle: 'rounded',
+      isLollipopChart: true,
+      orientation: 'vertical',
+      visualizationSubType: 'racing'
+    })
+  })
+})

package/src/components/BarChartRace/BarChartRaceFallback.tsx

@@ -0,0 +1,48 @@
+import { forwardRef, useContext } from 'react'
+import ConfigContext from '../../ConfigContext'
+import LinearChart from '../LinearChart'
+
+type Props = {
+  parentHeight: number
+  parentWidth: number
+}
+
+const BarChartRaceFallback = forwardRef<SVGAElement, Props>(({ parentHeight, parentWidth }, ref) => {
+  const context = useContext(ConfigContext)
+  const enteringFromVertical = context.config.orientation !== 'horizontal'
+  const fallbackConfig = {
+    ...context.config,
+    visualizationSubType: 'regular',
+    orientation: 'horizontal' as const,
+    isLollipopChart: false,
+    barStyle: 'flat' as const,
+    xAxis: enteringFromVertical
+      ? {
+          ...context.config.xAxis,
+          anchors: context.config.yAxis?.anchors ?? [],
+          hideAxis: true,
+          hideTicks: true
+        }
+      : context.config.xAxis,
+    yAxis: enteringFromVertical
+      ? {
+          ...context.config.yAxis,
+          anchors: context.config.xAxis?.anchors ?? [],
+          hideAxis: false,
+          hideTicks: false,
+          labelPlacement: context.config.yAxis?.labelPlacement || 'On Date/Category Axis'
+        }
+      : context.config.yAxis,
+    runtime: { ...context.config.runtime, horizontal: true }
+  }
+
+  return (
+    <ConfigContext.Provider value={{ ...context, config: fallbackConfig, updateConfig: () => {} }}>
+      <LinearChart ref={ref} parentWidth={parentWidth} parentHeight={parentHeight} />
+    </ConfigContext.Provider>
+  )
+})
+
+BarChartRaceFallback.displayName = 'BarChartRaceFallback'
+
+export default BarChartRaceFallback

package/src/components/BarChartRace/bar-chart-race.css

@@ -0,0 +1,160 @@
+.bar-chart-race {
+  box-sizing: border-box;
+  min-height: 180px;
+  padding: 0.5rem 0 1rem;
+  width: 100%;
+}
+
+.bar-chart-race__header {
+  align-items: center;
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-start;
+  margin-bottom: 1rem;
+}
+
+.bar-chart-race__frame {
+  font-family: var(--fonts-nunito, var(--app-font-secondary));
+  font-size: 1.5rem;
+}
+
+.bar-chart-race__plot {
+  position: relative;
+}
+
+.bar-chart-race__row {
+  align-items: center;
+  display: grid;
+  grid-template-columns: clamp(6rem, 16%, 8rem) 1fr;
+  height: 40px;
+  left: 0;
+  position: absolute;
+  width: 100%;
+}
+
+.bar-chart-race__category {
+  font-weight: 700;
+  overflow: hidden;
+  padding-right: 0.75rem;
+  text-align: right;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.bar-chart-race__bar-area {
+  align-items: center;
+  display: flex;
+  min-width: 0;
+}
+
+.bar-chart-race__bar {
+  flex: 0 0 auto;
+  height: 32px;
+  min-width: 1px;
+  position: relative;
+}
+
+.bar-chart-race__bar--value-inside {
+  overflow: hidden;
+}
+
+.bar-chart-race__value {
+  font-variant-numeric: tabular-nums;
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  white-space: nowrap;
+}
+
+.bar-chart-race__value--inside {
+  right: 0.3125rem;
+}
+
+.bar-chart-race__value--after {
+  color: var(--base-black, #1c1d1f);
+  left: 100%;
+  padding-left: 0.5rem;
+}
+
+.bar-chart-race--labels-below-bar .bar-chart-race__row {
+  align-items: start;
+  grid-template-areas:
+    'bar'
+    'category';
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: 32px 24px;
+  height: 56px;
+}
+
+.bar-chart-race--labels-below-bar .bar-chart-race__category {
+  grid-area: category;
+  max-width: 100%;
+  padding: 0.25rem 0 0;
+  text-align: left;
+}
+
+.bar-chart-race--labels-below-bar .bar-chart-race__bar-area {
+  grid-area: bar;
+}
+
+.bar-chart-race__frame-axis {
+  margin-left: clamp(6rem, 16%, 8rem);
+  margin-top: 0.75rem;
+  min-width: 0;
+}
+
+.bar-chart-race--labels-below-bar .bar-chart-race__frame-axis {
+  margin-left: 0;
+}
+
+.bar-chart-race__frame-axis-ticks {
+  border-top: 1px solid var(--cool-gray-30, #a9aeb1);
+  display: flex;
+  overflow-x: auto;
+}
+
+.bar-chart-race__frame-axis-tick {
+  color: var(--cool-gray-70, #565c65);
+  flex: 1 0 5rem;
+  font-size: 0.75rem;
+  min-width: 0;
+  position: relative;
+  text-align: center;
+}
+
+.bar-chart-race__frame-axis-tick.is-active {
+  color: var(--base-black, #1c1d1f);
+  font-weight: 700;
+}
+
+.bar-chart-race__frame-axis-mark {
+  border-left: 1px solid currentColor;
+  display: block;
+  height: 0.4rem;
+  margin: 0 auto 0.2rem;
+  width: 0;
+}
+
+.bar-chart-race__frame-axis-value {
+  display: block;
+  padding: 0 0.25rem;
+  white-space: nowrap;
+}
+
+.bar-chart-race__frame-axis-label {
+  display: block;
+  font-size: 0.875rem;
+  font-weight: 700;
+  margin-top: 0.4rem;
+  text-align: center;
+}
+
+@media (max-width: 480px) {
+  .bar-chart-race__row {
+    grid-template-columns: clamp(5rem, 24%, 6.5rem) 1fr;
+  }
+
+  .bar-chart-race__frame-axis {
+    margin-left: clamp(5rem, 24%, 6.5rem);
+  }
+}

package/src/components/BarChartRace/helpers.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest'
+import { buildBarRaceFrames, clampBarRaceMaxBars, getBarRaceEligibility } from './helpers'
+
+const config = {
+  visualizationType: 'Bar',
+  visualizationSubType: 'racing',
+  orientation: 'horizontal',
+  barStyle: 'flat',
+  isLollipopChart: false,
+  xAxis: { type: 'categorical', dataKey: 'Year' },
+  series: [{ dataKey: 'Value', dynamicCategory: 'Place' }],
+  runtime: { seriesKeys: ['Beta', 'Alpha', 'Gamma'] },
+  barRace: { maxBars: 2 }
+} as any
+
+const data = [
+  { Year: '2020', Place: 'Alpha', Value: 10 },
+  { Year: '2020', Place: 'Beta', Value: 10 },
+  { Year: '2020', Place: 'Gamma', Value: 30 },
+  { Year: '2021', Place: 'Alpha', Value: 50 },
+  { Year: '2021', Place: 'Beta', Value: 20 },
+  { Year: '2021', Place: 'Gamma', Value: 'missing' }
+]
+
+const wideConfig = {
+  ...config,
+  series: [
+    { dataKey: 'Alpha', name: 'Alpha' },
+    { dataKey: 'Beta', name: 'Beta' },
+    { dataKey: 'Gamma', name: 'Gamma' }
+  ],
+  runtime: { seriesKeys: ['Beta', 'Alpha', 'Gamma'] }
+} as any
+
+const wideData = [
+  { Year: '2020', Alpha: 10, Beta: 10, Gamma: 30 },
+  { Year: '2021', Alpha: 50, Beta: 20, Gamma: 'missing' }
+]
+
+describe('bar chart race helpers', () => {
+  it('preserves frame order, ranks descending, and uses runtime order to break ties', () => {
+    const result = buildBarRaceFrames(config, data)
+
+    expect(result.frames.map(frame => frame.key)).toEqual(['2020', '2021'])
+    expect(result.frames[0].items.map(item => item.category)).toEqual(['Gamma', 'Beta'])
+    expect(result.frames[1].items.map(item => item.category)).toEqual(['Alpha', 'Beta'])
+    expect(result.globalMax).toBe(50)
+    expect(result.competitorCount).toBe(3)
+  })
+
+  it('uses ordinary wide series as competitors without a Dynamic Category column', () => {
+    const result = getBarRaceEligibility(wideConfig, wideData)
+
+    expect(result.eligible).toBe(true)
+    expect(result.frames.map(frame => frame.key)).toEqual(['2020', '2021'])
+    expect(result.frames[0].items.map(item => item.category)).toEqual(['Gamma', 'Beta'])
+    expect(result.frames[1].items.map(item => item.category)).toEqual(['Alpha', 'Beta'])
+    expect(result.frames[0].items[0]).toMatchObject({ dataKey: 'Gamma', seriesKey: 'Gamma' })
+    expect(result.competitorCount).toBe(3)
+  })
+
+  it('keeps the global domain stable when the largest value falls outside a frame top N', () => {
+    const result = buildBarRaceFrames({ ...config, barRace: { maxBars: 1 } }, [
+      ...data,
+      { Year: '2022', Place: 'Gamma', Value: 100 }
+    ])
+
+    expect(result.frames[0].items).toHaveLength(1)
+    expect(result.globalMax).toBe(100)
+  })
+
+  it('rejects incompatible or insufficient configs with an actionable reason', () => {
+    expect(getBarRaceEligibility(config, data).eligible).toBe(true)
+    expect(getBarRaceEligibility({ ...config, smallMultiples: { mode: 'by-column' } }, data)).toMatchObject({
+      eligible: false,
+      reason: 'Racing mode does not support small multiples.'
+    })
+    expect(
+      getBarRaceEligibility(
+        config,
+        data.filter(row => row.Year === '2020')
+      ).reason
+    ).toContain('two valid frame')
+    expect(
+      getBarRaceEligibility(
+        config,
+        data.filter(row => row.Place === 'Alpha')
+      ).reason
+    ).toContain('two valid competitors')
+  })
+
+  it('excludes blank, negative, and nonnumeric values and clamps max bars', () => {
+    const result = buildBarRaceFrames(config, [
+      ...data,
+      { Year: '2021', Place: 'Negative', Value: -1 },
+      { Year: '2021', Place: 'Blank', Value: '' },
+      { Year: '2021', Place: 'Null', Value: null },
+      { Year: '2021', Place: 'Boolean', Value: false }
+    ])
+
+    expect(result.competitorCount).toBe(3)
+    expect(clampBarRaceMaxBars(99, result.competitorCount)).toBe(3)
+    expect(clampBarRaceMaxBars(0, result.competitorCount)).toBe(1)
+  })
+
+  it('rejects duplicate rows, nonhorizontal orientation, and nonflat styles', () => {
+    expect(getBarRaceEligibility(config, [...data, data[0]]).reason).toContain('one row per frame')
+    expect(getBarRaceEligibility({ ...config, orientation: 'vertical' }, data).reason).toContain(
+      'horizontal orientation'
+    )
+    expect(getBarRaceEligibility({ ...config, barStyle: 'rounded' }, data).reason).toContain('flat bar style')
+    expect(getBarRaceEligibility(wideConfig, [...wideData, wideData[0]]).reason).toContain('one row per frame')
+  })
+})