@cdc/chart 4.26.6 → 4.26.10

package/src/components/LineChartRace/LineChartRace.test.tsx

@@ -0,0 +1,275 @@
+import React, { useContext } from 'react'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import ConfigContext from '../../ConfigContext'
+import { createMockChartContext, createMockConfig } from '../LinearChart/tests/mockConfigContext'
+import LineChartRace from './LineChartRace'
+import { getLineRaceEligibility } from './helpers'
+
+vi.mock('../LinearChart', () => ({
+  default: React.forwardRef((_props: any, _ref) => {
+    const context = useContext(ConfigContext) as any
+    return (
+      <>
+        <svg
+          data-testid='line-chart'
+          data-tooltip-rows={context.tableData?.length}
+          data-rendered-rows={context.transformedData?.length}
+          data-progress={context.lineRaceProgress}
+        />
+        <button
+          type='button'
+          onClick={() =>
+            context.updateConfig(
+              {
+                ...context.config,
+                annotations: [{ ...context.config.annotations[0], dx: 24, dy: 36 }]
+              },
+              annotationDataOverride
+            )
+          }
+        >
+          Persist annotation
+        </button>
+      </>
+    )
+  })
+}))
+
+const data = [
+  { Year: '2020', North: 10, South: 20 },
+  { Year: '2021', North: 30, South: 15 },
+  { Year: '2022', North: 25, South: 40 }
+]
+const annotationDataOverride = [{ Year: '2020', North: 12, South: 20 }]
+
+const getContext = (secondsPerFrame = 0.5) => {
+  const base = createMockConfig()
+  const config = createMockConfig({
+    visualizationType: 'Line',
+    visualizationSubType: 'racing',
+    xAxis: { ...base.xAxis, type: 'categorical', dataKey: 'Year', label: 'Year' },
+    series: [
+      { dataKey: 'North', type: 'Line', axis: 'left' },
+      { dataKey: 'South', type: 'Line', axis: 'left' }
+    ] as any,
+    lineRace: { secondsPerFrame }
+  })
+  return createMockChartContext(config, { transformedData: data, tableData: data })
+}
+
+const installAnimationFrameController = () => {
+  let currentTime = 0
+  let nextId = 1
+  const callbacks = new Map<number, FrameRequestCallback>()
+  vi.spyOn(performance, 'now').mockImplementation(() => currentTime)
+  const requestAnimationFrame = vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+    const id = nextId++
+    callbacks.set(id, callback)
+    return id
+  })
+  const cancelAnimationFrame = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(id => {
+    callbacks.delete(id)
+  })
+
+  return {
+    requestAnimationFrame,
+    cancelAnimationFrame,
+    setTime: (time: number) => {
+      currentTime = time
+    },
+    takeNextCallback: () => {
+      const next = callbacks.entries().next().value as [number, FrameRequestCallback] | undefined
+      if (!next) throw new Error('Expected a queued animation frame')
+      callbacks.delete(next[0])
+      return next[1]
+    },
+    pendingCount: () => callbacks.size
+  }
+}
+
+const renderRace = (context = getContext()) => {
+  const race = getLineRaceEligibility(context.config, data)
+  return render(
+    <ConfigContext.Provider value={context}>
+      <LineChartRace parentWidth={700} parentHeight={400} race={race} />
+    </ConfigContext.Provider>
+  )
+}
+
+const getProgress = () => {
+  const progress = screen.getByTestId('line-chart').getAttribute('data-progress')
+  if (progress === null) throw new Error('Expected the Line race progress attribute')
+  return Number(progress)
+}
+
+describe('LineChartRace', () => {
+  beforeEach(() => {
+    vi.stubGlobal('matchMedia', () => ({ matches: false, addEventListener: vi.fn(), removeEventListener: vi.fn() }))
+  })
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+  })
+
+  it('plays, pauses, resumes from paused progress, completes, and replays', () => {
+    const animationFrames = installAnimationFrameController()
+    const context = getContext()
+    const { container } = renderRace(context)
+
+    expect(screen.getByTestId('line-chart')).toHaveAttribute('data-tooltip-rows', '1')
+    expect(screen.getByTestId('line-chart')).toHaveAttribute('data-rendered-rows', '3')
+    expect(screen.getByTestId('line-chart')).toHaveAttribute('data-progress', '0')
+    const playButton = screen.getByRole('button', { name: 'Play' })
+    const frame = container.querySelector('.line-chart-race__frame')
+    expect(frame).not.toBeNull()
+    expect(container.querySelector('.line-chart-race__header')?.firstElementChild).toBe(playButton)
+    expect(playButton.nextElementSibling).toBe(frame)
+    expect(playButton.querySelector('[data-icon="play"]')).toBeInTheDocument()
+    fireEvent.click(playButton)
+    expect(screen.getByRole('button', { name: 'Pause' }).querySelector('[data-icon="pause"]')).toBeInTheDocument()
+
+    const firstFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(600)
+    act(() => firstFrame(600))
+    expect(screen.getByTestId('line-chart')).toHaveAttribute('data-tooltip-rows', '2')
+    expect(getProgress()).toBeCloseTo(0.6)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Pause' }))
+    const pausedProgress = getProgress()
+    const pausedFrame = frame?.textContent
+    expect(screen.getByRole('button', { name: 'Play' })).toBeInTheDocument()
+
+    animationFrames.setTime(900)
+    expect(getProgress()).toBe(pausedProgress)
+    expect(frame).toHaveTextContent(pausedFrame || '')
+
+    fireEvent.click(screen.getByRole('button', { name: 'Play' }))
+    const resumedFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(1100)
+    act(() => resumedFrame(1100))
+    expect(getProgress()).toBeCloseTo(0.8)
+    expect(getProgress()).toBeGreaterThan(pausedProgress)
+
+    const finishingFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(1300)
+    act(() => finishingFrame(1300))
+    expect(screen.getByRole('button', { name: 'Replay' }).querySelector('[data-icon="replay"]')).toBeInTheDocument()
+    expect(getProgress()).toBe(1)
+    expect(animationFrames.pendingCount()).toBe(0)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Replay' }))
+    expect(screen.getByRole('button', { name: 'Pause' })).toBeInTheDocument()
+    expect(frame).toHaveTextContent('2020')
+    expect(getProgress()).toBe(0)
+
+    const replayFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(1400)
+    act(() => replayFrame(1400))
+    expect(getProgress()).toBeCloseTo(0.1)
+    expect(screen.getByRole('button', { name: 'Pause' })).toBeInTheDocument()
+  })
+
+  it('invalidates an already-dispatched animation frame when paused', () => {
+    const animationFrames = installAnimationFrameController()
+    const { container } = renderRace()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Play' }))
+    const firstFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(600)
+    act(() => firstFrame(600))
+
+    const dispatchedStaleFrame = animationFrames.takeNextCallback()
+    fireEvent.click(screen.getByRole('button', { name: 'Pause' }))
+    const pausedProgress = getProgress()
+    const pausedFrame = container.querySelector('.line-chart-race__frame')?.textContent
+    const requestCountAtPause = animationFrames.requestAnimationFrame.mock.calls.length
+
+    animationFrames.setTime(900)
+    act(() => dispatchedStaleFrame(900))
+
+    expect(getProgress()).toBe(pausedProgress)
+    expect(container.querySelector('.line-chart-race__frame')).toHaveTextContent(pausedFrame || '')
+    expect(animationFrames.requestAnimationFrame).toHaveBeenCalledTimes(requestCountAtPause)
+    expect(animationFrames.cancelAnimationFrame).toHaveBeenCalled()
+  })
+
+  it('uses continuous playback when reduced motion is preferred', () => {
+    vi.stubGlobal('matchMedia', () => ({ matches: true, addEventListener: vi.fn(), removeEventListener: vi.fn() }))
+    const animationFrames = installAnimationFrameController()
+    renderRace()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Play' }))
+    expect(screen.getByRole('button', { name: 'Pause' })).toBeInTheDocument()
+    expect(getProgress()).toBe(0)
+
+    const firstFrame = animationFrames.takeNextCallback()
+    animationFrames.setTime(250)
+    act(() => firstFrame(250))
+
+    expect(getProgress()).toBeCloseTo(0.25)
+    expect(screen.getByRole('button', { name: 'Pause' })).toBeInTheDocument()
+  })
+
+  it('completes immediately without scheduling animation frames when timing is zero', () => {
+    const animationFrames = installAnimationFrameController()
+    renderRace(getContext(0))
+
+    fireEvent.click(screen.getByRole('button', { name: 'Play' }))
+
+    expect(screen.getByRole('button', { name: 'Replay' })).toBeInTheDocument()
+    expect(getProgress()).toBe(1)
+    expect(animationFrames.requestAnimationFrame).not.toHaveBeenCalled()
+  })
+
+  it('preserves authored race fields when the inner chart persists an annotation update', () => {
+    const baseContext = getContext()
+    const updateConfig = vi.fn()
+    const annotation = { text: 'Original annotation', dx: 0, dy: 0 }
+    const initialConfig = {
+      ...baseContext.config,
+      visualizationSubType: 'racing',
+      allowLineToBarGraph: undefined,
+      animate: true,
+      annotations: [annotation]
+    } as any
+
+    const StatefulRaceHarness = () => {
+      const [config, setConfig] = React.useState(initialConfig)
+      const race = getLineRaceEligibility(config, data)
+      const context = {
+        ...baseContext,
+        config,
+        updateConfig: (nextConfig: typeof initialConfig, dataOverride?: any[]) => {
+          updateConfig(nextConfig, dataOverride)
+          setConfig(nextConfig)
+        }
+      } as any
+
+      return (
+        <ConfigContext.Provider value={context}>
+          {config.visualizationSubType === 'racing' && race.eligible ? (
+            <LineChartRace parentWidth={700} parentHeight={400} race={race} />
+          ) : null}
+        </ConfigContext.Provider>
+      )
+    }
+
+    render(<StatefulRaceHarness />)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Persist annotation' }))
+
+    expect(updateConfig).toHaveBeenCalledTimes(1)
+    const [updatedConfig, dataOverride] = updateConfig.mock.calls[0]
+    expect(updatedConfig).toEqual(
+      expect.objectContaining({
+        visualizationSubType: 'racing',
+        allowLineToBarGraph: undefined,
+        animate: true,
+        annotations: [{ ...annotation, dx: 24, dy: 36 }]
+      })
+    )
+    expect(dataOverride).toBe(annotationDataOverride)
+    expect(screen.getByRole('button', { name: 'Play' })).toBeInTheDocument()
+  })
+})

package/src/components/LineChartRace/LineChartRace.tsx

@@ -0,0 +1,134 @@
+import { forwardRef, useContext, useEffect, useRef, useState } from 'react'
+import PlaybackButton from '@cdc/core/components/PlaybackButton'
+import ConfigContext from '../../ConfigContext'
+import LinearChart from '../LinearChart'
+import { clampRaceSecondsPerFrame } from '../raceTiming'
+import { type LineRaceEligibility } from './helpers'
+import './line-chart-race.css'
+
+type Props = { parentHeight: number; parentWidth: number; race: LineRaceEligibility }
+
+const LineChartRace = forwardRef<SVGAElement, Props>(({ parentHeight, parentWidth, race }, ref) => {
+  const context = useContext(ConfigContext)
+  const chartParentRef = useRef<HTMLDivElement>(null)
+  const [progress, setProgress] = useState(0)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [hasStarted, setHasStarted] = useState(false)
+  const secondsPerFrame = clampRaceSecondsPerFrame(context.config.lineRace?.secondsPerFrame)
+  const totalSeconds = (race.frames.length - 1) * secondsPerFrame
+  const signature = JSON.stringify(
+    race.frames.map(frame => [frame.key, frame.currentRows.map(row => Object.values(row))])
+  )
+
+  useEffect(() => {
+    setProgress(0)
+    setIsPlaying(false)
+    setHasStarted(false)
+    context.setRaceTiming?.(null)
+  }, [signature])
+
+  useEffect(() => {
+    if (!isPlaying) return
+    if (totalSeconds === 0) {
+      setProgress(1)
+      setIsPlaying(false)
+      return
+    }
+    const totalDuration = totalSeconds * 1000
+    const startedAt = performance.now()
+    const startingProgress = progress
+    let animationFrame = 0
+    let cancelled = false
+    const animate = (now: number) => {
+      if (cancelled) return
+
+      const nextProgress = Math.min(1, startingProgress + (now - startedAt) / totalDuration)
+      setProgress(nextProgress)
+      if (nextProgress < 1 && !cancelled) {
+        animationFrame = window.requestAnimationFrame(animate)
+      } else if (!cancelled) {
+        setIsPlaying(false)
+      }
+    }
+    animationFrame = window.requestAnimationFrame(animate)
+    return () => {
+      cancelled = true
+      window.cancelAnimationFrame(animationFrame)
+    }
+  }, [isPlaying, race.frames.length, totalSeconds])
+
+  const frameIndex = Math.min(race.frames.length - 1, Math.floor(progress * (race.frames.length - 1) + 1e-6))
+  const frame = race.frames[frameIndex]
+  const isAtEnd = progress >= 1
+  const visibleRows = race.frames.slice(0, frameIndex + 1).flatMap(raceFrame => raceFrame.currentRows)
+  const frameKey = frame?.key || ''
+
+  useEffect(() => {
+    if (!hasStarted || !frameKey) return
+    context.setRaceTiming?.({
+      elapsedSeconds: progress * totalSeconds,
+      frameKey,
+      isPlaying,
+      totalSeconds
+    })
+  }, [frameKey, hasStarted, isPlaying, totalSeconds])
+
+  if (!race.eligible || !frame) return null
+
+  const updateConfig = (nextConfig: typeof context.config, dataOverride?: any[]) => {
+    context.updateConfig?.(
+      {
+        ...nextConfig,
+        visualizationSubType: context.config.visualizationSubType,
+        allowLineToBarGraph: context.config.allowLineToBarGraph,
+        animate: context.config.animate
+      },
+      dataOverride
+    )
+  }
+
+  const raceContext = {
+    ...context,
+    convertLineToBarGraph: false,
+    config: {
+      ...context.config,
+      visualizationSubType: 'regular',
+      allowLineToBarGraph: false,
+      animate: false
+    },
+    updateConfig,
+    lineRaceProgress: progress,
+    parentRef: chartParentRef,
+    tableData: visibleRows,
+    yAxisDomainData: context.transformedData
+  }
+
+  const handlePlayback = () => {
+    setHasStarted(true)
+    if (isAtEnd) {
+      setProgress(0)
+      setIsPlaying(true)
+      return
+    }
+    setIsPlaying(current => !current)
+  }
+
+  return (
+    <section className='line-chart-race' aria-label={`Line chart race through ${frame.key}`}>
+      <div className='line-chart-race__header'>
+        <PlaybackButton isAtEnd={isAtEnd} isPlaying={isPlaying} onClick={handlePlayback} />
+        <strong className='line-chart-race__frame' aria-live='polite'>
+          {frame.key}
+        </strong>
+      </div>
+      <ConfigContext.Provider value={raceContext}>
+        <div ref={chartParentRef}>
+          <LinearChart ref={ref} parentWidth={parentWidth} parentHeight={parentHeight} />
+        </div>
+      </ConfigContext.Provider>
+    </section>
+  )
+})
+
+LineChartRace.displayName = 'LineChartRace'
+export default LineChartRace

package/src/components/LineChartRace/LineChartRaceFallback.tsx

@@ -0,0 +1,28 @@
+import { forwardRef, useContext } from 'react'
+import ConfigContext from '../../ConfigContext'
+import LinearChart from '../LinearChart'
+
+type Props = { parentHeight: number; parentWidth: number }
+
+const LineChartRaceFallback = forwardRef<SVGAElement, Props>(({ parentHeight, parentWidth }, ref) => {
+  const context = useContext(ConfigContext)
+  return (
+    <ConfigContext.Provider
+      value={{
+        ...context,
+        convertLineToBarGraph: false,
+        config: {
+          ...context.config,
+          visualizationSubType: 'regular',
+          allowLineToBarGraph: false,
+          animate: false
+        }
+      }}
+    >
+      <LinearChart ref={ref} parentWidth={parentWidth} parentHeight={parentHeight} />
+    </ConfigContext.Provider>
+  )
+})
+
+LineChartRaceFallback.displayName = 'LineChartRaceFallback'
+export default LineChartRaceFallback

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

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { clampRaceSecondsPerFrame } from '../raceTiming'
+import { buildLineRaceFrames, getLineRaceEligibility } from './helpers'
+
+const config = {
+  visualizationType: 'Line',
+  visualizationSubType: 'racing',
+  xAxis: { type: 'categorical', dataKey: 'Year' },
+  series: [{ dataKey: 'North' }, { dataKey: 'South' }]
+} as any
+
+const data = [
+  { Year: '2020', North: 10, South: 20 },
+  { Year: '2021', North: 30, South: 15 },
+  { Year: '2022', North: 25, South: 40 }
+]
+
+describe('line chart race helpers', () => {
+  it('clamps authored timing to the supported range', () => {
+    expect(clampRaceSecondsPerFrame(undefined)).toBe(0.5)
+    expect(clampRaceSecondsPerFrame(null)).toBe(0.5)
+    expect(clampRaceSecondsPerFrame('')).toBe(0.5)
+    expect(clampRaceSecondsPerFrame(-1)).toBe(0)
+    expect(clampRaceSecondsPerFrame(0.25)).toBe(0.5)
+    expect(clampRaceSecondsPerFrame('1.2')).toBe(1)
+    expect(clampRaceSecondsPerFrame('1.3')).toBe(1.5)
+    expect(clampRaceSecondsPerFrame(100)).toBe(1.5)
+  })
+
+  it('builds cumulative wide-data frames in visible axis order', () => {
+    const frames = buildLineRaceFrames(config, data)
+    expect(frames.map(frame => frame.key)).toEqual(['2020', '2021', '2022'])
+    expect(frames.map(frame => frame.rows.length)).toEqual([1, 2, 3])
+    expect(frames.map(frame => frame.currentRows.length)).toEqual([1, 1, 1])
+    expect(getLineRaceEligibility(config, data).eligible).toBe(true)
+  })
+
+  it('accepts one dynamic-category series and accumulates each frame together', () => {
+    const dynamicConfig = { ...config, series: [{ dataKey: 'Value', dynamicCategory: 'Region' }] }
+    const dynamicData = [
+      { Year: '2020', Region: 'North', Value: 10 },
+      { Year: '2020', Region: 'South', Value: 20 },
+      { Year: '2021', Region: 'North', Value: 30 },
+      { Year: '2021', Region: 'South', Value: 15 }
+    ]
+    const result = getLineRaceEligibility(dynamicConfig, dynamicData)
+    expect(result.eligible).toBe(true)
+    expect(result.frames.map(frame => frame.rows.length)).toEqual([2, 4])
+  })
+
+  it('applies custom categorical order and chronological or recent-first date order', () => {
+    const customConfig = {
+      ...config,
+      xAxis: { ...config.xAxis, categoryOrderType: 'custom', categoryOrder: ['2022', '2020', '2021'] }
+    }
+    expect(buildLineRaceFrames(customConfig, data).map(frame => frame.key)).toEqual(['2022', '2020', '2021'])
+
+    const recentFirst = [
+      { Date: '2022-01-01', North: 25, South: 40 },
+      { Date: '2020-01-01', North: 10, South: 20 },
+      { Date: '2021-01-01', North: 30, South: 15 }
+    ]
+    const dateConfig = { ...config, xAxis: { type: 'date', dataKey: 'Date', sortByRecentDate: true } }
+    expect(buildLineRaceFrames(dateConfig, recentFirst).map(frame => frame.key)).toEqual([
+      '2022-01-01',
+      '2021-01-01',
+      '2020-01-01'
+    ])
+    expect(
+      buildLineRaceFrames({ ...dateConfig, xAxis: { ...dateConfig.xAxis, sortByRecentDate: false } }, recentFirst).map(
+        frame => frame.key
+      )
+    ).toEqual(['2020-01-01', '2021-01-01', '2022-01-01'])
+  })
+
+  it('rejects invalid dates, duplicates, brushes, and insufficient frames', () => {
+    const dateConfig = { ...config, xAxis: { type: 'date', dataKey: 'Year' } }
+    expect(getLineRaceEligibility(dateConfig, [{ ...data[0], Year: 'bad-date' }, data[1]]).reason).toContain(
+      'valid date'
+    )
+    expect(getLineRaceEligibility(config, [...data, data[0]]).reason).toContain('one row per frame')
+    expect(getLineRaceEligibility({ ...config, xAxis: { ...config.xAxis, brushActive: true } }, data).reason).toContain(
+      'date brush'
+    )
+    expect(getLineRaceEligibility(config, data.slice(0, 1)).reason).toContain('two valid frame')
+    expect(getLineRaceEligibility(config, [{ ...data[0], North: -1 }, data[1]]).reason).toContain('negative values')
+  })
+})

package/src/components/LineChartRace/helpers.ts

@@ -0,0 +1,157 @@
+import { type ChartConfig } from '../../types/ChartConfig'
+
+type DataRow = Record<string, any>
+
+export type LineRaceFrame = {
+  key: string
+  rows: DataRow[]
+  currentRows: DataRow[]
+}
+
+export type LineRaceEligibility = {
+  eligible: boolean
+  frames: LineRaceFrame[]
+  reason?: string
+}
+
+const hasFiniteValue = (value: unknown) => {
+  if (value === null || value === undefined || value === '') return false
+  return Number.isFinite(Number(String(value).replaceAll(',', '').replace(/%$/, '')))
+}
+
+const isNegativeValue = (value: unknown) => {
+  if (value === null || value === undefined || value === '') return false
+  const numericValue = Number(String(value).replaceAll(',', '').replace(/%$/, ''))
+  return Number.isFinite(numericValue) && numericValue < 0
+}
+
+export const buildLineRaceFrames = (config: Partial<ChartConfig>, data: DataRow[] = []): LineRaceFrame[] => {
+  const frameKey = config.xAxis?.dataKey
+  const series = Array.isArray(config.series) ? config.series : []
+  const dynamicSeries = series.find(item => item.dynamicCategory)
+  if (!frameKey || !series.length || !Array.isArray(data)) return []
+
+  const orderedKeys: string[] = []
+  const rowsByFrame = new Map<string, DataRow[]>()
+  data.forEach(row => {
+    const rawFrame = row?.[frameKey]
+    if (rawFrame === null || rawFrame === undefined || String(rawFrame).trim() === '') return
+    const hasValue = dynamicSeries
+      ? hasFiniteValue(row?.[dynamicSeries.dataKey])
+      : series.some(item => hasFiniteValue(row?.[item.dataKey]))
+    if (!hasValue) return
+
+    const key = String(rawFrame).trim()
+    if (!rowsByFrame.has(key)) {
+      orderedKeys.push(key)
+      rowsByFrame.set(key, [])
+    }
+    rowsByFrame.get(key)?.push(row)
+  })
+
+  const frameKeys = [...orderedKeys]
+  if (['date', 'date-time'].includes(config.xAxis?.type)) {
+    frameKeys.sort((a, b) => Date.parse(a) - Date.parse(b))
+    if (config.xAxis?.sortByRecentDate) frameKeys.reverse()
+  } else if (config.xAxis?.categoryOrderType === 'custom' && Array.isArray(config.xAxis.categoryOrder)) {
+    const customOrder = new Map(config.xAxis.categoryOrder.map((value, index) => [String(value), index]))
+    const sourceOrder = new Map(orderedKeys.map((value, index) => [value, index]))
+    frameKeys.sort(
+      (a, b) =>
+        (customOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (customOrder.get(b) ?? Number.MAX_SAFE_INTEGER) ||
+        (sourceOrder.get(a) ?? 0) - (sourceOrder.get(b) ?? 0)
+    )
+  }
+
+  let visibleRows: DataRow[] = []
+  return frameKeys.map(key => {
+    const currentRows = rowsByFrame.get(key) ?? []
+    visibleRows = [...visibleRows, ...currentRows]
+    return { key, rows: visibleRows, currentRows }
+  })
+}
+
+export const getLineRaceEligibility = (config: Partial<ChartConfig>, data: DataRow[] = []): LineRaceEligibility => {
+  const frames = buildLineRaceFrames(config, data)
+  const series = Array.isArray(config.series) ? config.series : []
+  const dynamicSeries = series.filter(item => item.dynamicCategory)
+  const frameKey = config.xAxis?.dataKey
+
+  if (config.visualizationType !== 'Line') {
+    return { eligible: false, frames, reason: 'Racing mode is available only for Line charts.' }
+  }
+  if (!['categorical', 'date', 'date-time'].includes(config.xAxis?.type)) {
+    return { eligible: false, frames, reason: 'Racing mode requires a categorical, date, or date-time axis.' }
+  }
+  if (!frameKey || !series.length || series.some(item => !item.dataKey)) {
+    return {
+      eligible: false,
+      frames,
+      reason: 'Racing mode requires a Date/Category Axis and at least one data series.'
+    }
+  }
+  if (dynamicSeries.length > 1 || (dynamicSeries.length === 1 && series.length !== 1)) {
+    return {
+      eligible: false,
+      frames,
+      reason: 'Dynamic Line racing requires exactly one series with a Dynamic Category column.'
+    }
+  }
+  if (config.smallMultiples?.mode) {
+    return { eligible: false, frames, reason: 'Racing mode does not support small multiples.' }
+  }
+  if (config.xAxis?.brushActive) {
+    return { eligible: false, frames, reason: 'Racing mode does not support the date brush.' }
+  }
+  if (config.allowLineToBarGraph) {
+    return { eligible: false, frames, reason: 'Racing mode does not support automatic Line-to-Bar conversion.' }
+  }
+  if (
+    config.showAreaUnderLine ||
+    Boolean(config.confidenceKeys?.lower || config.confidenceKeys?.upper) ||
+    Boolean(config.preliminaryData?.length)
+  ) {
+    return {
+      eligible: false,
+      frames,
+      reason: 'Racing mode supports standard Line paths without areas, confidence bands, or preliminary styling.'
+    }
+  }
+  const hasNegative = data.some(row => {
+    if (dynamicSeries[0]) return isNegativeValue(row?.[dynamicSeries[0].dataKey])
+    return series.some(item => isNegativeValue(row?.[item.dataKey]))
+  })
+  if (hasNegative) {
+    return { eligible: false, frames, reason: 'Racing mode does not support negative values.' }
+  }
+  if (['date', 'date-time'].includes(config.xAxis?.type)) {
+    const malformedFrame = data.some(row => {
+      const value = row?.[frameKey]
+      return (
+        value !== null && value !== undefined && String(value).trim() !== '' && Number.isNaN(Date.parse(String(value)))
+      )
+    })
+    if (malformedFrame) {
+      return { eligible: false, frames, reason: 'Racing mode requires valid date values on the Date/Category Axis.' }
+    }
+  }
+
+  const seen = new Set<string>()
+  let hasDuplicate = false
+  data.forEach(row => {
+    const frame = String(row?.[frameKey] ?? '').trim()
+    if (!frame) return
+    const category = dynamicSeries[0] ? String(row?.[dynamicSeries[0].dynamicCategory] ?? '').trim() : '__wide__'
+    const key = `${frame}\u0000${category}`
+    if (seen.has(key)) hasDuplicate = true
+    seen.add(key)
+  })
+  if (hasDuplicate) {
+    return { eligible: false, frames, reason: 'Racing mode requires one row per frame and series combination.' }
+  }
+  if (frames.length < 2) {
+    return { eligible: false, frames, reason: 'Racing mode requires at least two valid frame values.' }
+  }
+
+  return { eligible: true, frames }
+}

package/src/components/LineChartRace/index.ts

@@ -0,0 +1,3 @@
+export { default } from './LineChartRace'
+export { default as LineChartRaceFallback } from './LineChartRaceFallback'
+export * from './helpers'