@patterninc/pattern-ui 0.0.0-main.20260929.db2f8e8fde0d

package/src/components/D3Charts/LineChart.tsx

@@ -0,0 +1,1658 @@
+import { cn } from 'cn'
+import * as d3 from 'd3'
+import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { useEventListener, useResizeObserver } from 'usehooks-ts'
+
+import { ChartSkeleton } from './shared/ChartSkeleton'
+import type { D3ChartLegendProps } from './shared/D3ChartLegend'
+import { D3ChartLegendFooter } from './shared/D3ChartLegendFooter'
+import { D3Tooltip, type TooltipData } from './shared/D3Tooltip'
+import { type ChartConfig, type ChartFormatters, LINE_CHART_PALETTE } from './types'
+import {
+  getMaxXAxisLabelWidth,
+  getYAxisGap,
+  renderXAxis,
+  renderYAxis,
+  type AxisStyleOverrides,
+} from './utils/axes'
+import { CHART_COLORS, getResponsiveStyles } from './utils/constants'
+import { transformChartData } from './utils/dataTransform'
+import { DENSITY_TICK_COUNT, type GridDensity, renderGrid } from './utils/grid'
+import { findNearestPoint, throttle } from './utils/performance'
+import { createLinearScale, createPointScale } from './utils/scales'
+
+export type LineChartData = Record<string, string | number | boolean | null | undefined>
+
+export interface LineChartProps {
+  /** Array of data points to render */
+  data: LineChartData[]
+  /** Configuration for chart labels and formatting */
+  config: ChartConfig
+  /** Line series configuration. Each line can specify yAxisId for left/right axis. */
+  lines: {
+    /** The key in data to use for this line's values */
+    dataKey: string
+    /**
+     * Which Y-axis to use: 'left' or 'right' (defaults to 'left'). Enables dual Y-axis when at
+     * least one line uses 'right'.
+     */
+    yAxisId?: 'left' | 'right'
+    /** Custom stroke color for the line (defaults to palette color by index when multiple lines) */
+    stroke?: string
+    /** Custom stroke width for the line (defaults to 2) */
+    strokeWidth?: number
+    /** Render the line as dashed (same draw animation, dash pattern revealed over time) */
+    dashed?: boolean
+    /** Custom dash pattern when dashed is true (e.g. "4 6"). Defaults to "4 6". */
+    strokeDashArray?: string
+    /**
+     * Optional forecast data extending from the last data point (rendered as dashed line). Not
+     * compatible with `dashed: true` — forecast is silently ignored when the line is already
+     * dashed, because both features use different dashed-line rendering paths.
+     */
+    forecast?: LineChartData[]
+  }[]
+  /** The data field to use for X-axis labels */
+  xAxisKey?: string
+  /** Additional CSS class name for the container */
+  className?: string
+  /** Whether to show grid lines (defaults to true) */
+  showGrid?: boolean
+  /**
+   * Y-axis tick density: 'sparse' (~3), 'normal' (~5), 'dense' (~7). Approximate counts - D3 picks
+   * "nice" values over exact counts.
+   */
+  gridDensity?: GridDensity
+  /** Show loading skeleton instead of chart */
+  loading?: boolean
+  /** Position of single Y-axis when not using dual axis: 'left' or 'right' (defaults to 'left') */
+  yAxisPosition?: 'left' | 'right'
+  /** Optional formatters for Y/X axis ticks and tooltip date/value. */
+  formatters?: ChartFormatters
+  /** When true, metric labels from config are shown on the right side of each tooltip row. */
+  showTooltipLabels?: boolean
+  /** Optional legend props for the chart header */
+  chartLegendProps?: Partial<D3ChartLegendProps>
+  /**
+   * Optional order of lines for tooltip display. Array of line indices (0-based). E.g. [1, 2, 0]
+   * shows line 1 first, then 2, then 0 in the tooltip. When omitted, tooltip order matches the
+   * lines array order.
+   */
+  tooltipLineOrder?: number[]
+  /**
+   * When true, null/NaN data points are skipped and the line connects between valid points (like
+   * Recharts connectNulls). Defaults to false (gaps).
+   */
+  connectNulls?: boolean
+  /**
+   * Additional tooltip-only rows that are not tied to a rendered line. Each row reads its value
+   * from `dataKey` in the hovered data point. Rows with null/NaN/undefined values are automatically
+   * hidden.
+   *
+   * When `replacesDataKey` is set and the extra row has a valid value, the line tooltip row
+   * matching that dataKey is suppressed — useful for replacing a null line value with a contextual
+   * label (e.g. "Revenue to date").
+   */
+  extraTooltipRows?: {
+    /** Key to look up in the hovered data point */
+    dataKey: string
+    /** Swatch color for this tooltip row */
+    color: string
+    /**
+     * Mark this row as forecast data. The library automatically renders the swatch as two stacked
+     * dashes matching the forecast dashed line.
+     */
+    isForecast?: boolean
+    /** Label shown on the right side of the tooltip row (requires showTooltipLabels) */
+    label: React.ReactNode
+    /** Optional per-value formatter */
+    formatValue?: (value: number) => string
+    /**
+     * When set, suppresses the line tooltip row whose dataKey matches this value — but only when
+     * this extra row itself has a valid (non-null/NaN) value.
+     */
+    replacesDataKey?: string
+  }[]
+  /** Optional test id rendered as the `qa-test-id` attribute for QA testing */
+  qaTestId?: string
+}
+
+/** Visible dots drawn on hover (inside <g class="hover-dots">). Not used for QA anchors. */
+const HOVER_ACTIVE_DOT_CLASS = 'hover-active'
+
+// Non-responsive chart styling constants (colors, animation, strokes)
+const CHART_STYLES = {
+  borderSubColor: CHART_COLORS.borderSub,
+
+  dotFillActive: CHART_COLORS.baseInverse,
+  dotStrokeWidth: 2,
+
+  defaultStrokeWidth: 2,
+
+  // Line draw animation
+  animationDuration: 1000,
+  animationEase: d3.easeQuadOut,
+  dotAnimationDelay: 800,
+  dotAnimationDuration: 200,
+
+  /** Default dash pattern for dashed lines (dash gap) */
+  defaultStrokeDashArray: '4 6',
+
+  /** Stroke width for reveal mask so it fully covers the line */
+  maskRevealStrokeWidth: 24,
+} as const
+
+function getLineColor(line: { stroke?: string }, index: number): string {
+  const paletteColor =
+    LINE_CHART_PALETTE[index % LINE_CHART_PALETTE.length] ?? LINE_CHART_PALETTE[0]
+  return line.stroke ?? paletteColor
+}
+
+// ─── Shared render-data helpers ─────────────────────────────────────────────
+// These are called identically in both the init path (creates elements) and
+// the update path (mutates existing elements), so extracting them keeps the
+// two paths in sync automatically.
+
+type LineRenderData = {
+  actualData: LineChartData[]
+  hasForecast: boolean
+  forecastPoints: LineChartData[] | null
+  lastActualPoint: LineChartData | null
+  combinedData: LineChartData[] | null
+  /** X pixel position of the last actual data point — the solid/forecast clip boundary. */
+  solidLastXPos: number | null
+}
+
+/**
+ * Computes the actual data slice, combined path data (actual + forecast), and the clip boundary
+ * x-position shared between the area fill and the solid line. Both the init and update paths call
+ * this to guarantee they use the same inputs.
+ */
+function buildLineRenderData(
+  lineConfig: { dataKey: string; dashed?: boolean; forecast?: LineChartData[] },
+  transformedData: { data: LineChartData[]; xValues: string[] },
+  actualDataLength: number,
+  connectNulls: boolean,
+  isDefined: (d: LineChartData) => boolean,
+  xScale: d3.ScalePoint<string>,
+  xAxisKey: string,
+): LineRenderData {
+  const actualData = connectNulls
+    ? transformedData.data.slice(0, actualDataLength).filter(isDefined)
+    : transformedData.data.slice(0, actualDataLength)
+
+  // Forecast is intentionally incompatible with `dashed: true`. A dashed line
+  // already uses a different SVG rendering path (mask-based reveal) that cannot
+  // be split into solid+forecast segments. Callers should not set both.
+  const forecastPoints =
+    !lineConfig.dashed &&
+    lineConfig.forecast != null &&
+    Array.isArray(lineConfig.forecast) &&
+    lineConfig.forecast.length > 0 &&
+    actualData.length > 0
+      ? lineConfig.forecast
+      : null
+
+  const lastActualPoint = actualData.at(-1) ?? null
+
+  const combinedData: LineChartData[] | null =
+    forecastPoints != null && lastActualPoint != null ? [...actualData, ...forecastPoints] : null
+
+  const solidLastXPos: number | null =
+    forecastPoints != null && lastActualPoint != null
+      ? (xScale(String(lastActualPoint[xAxisKey])) ?? 0)
+      : null
+
+  return {
+    actualData,
+    hasForecast: forecastPoints != null,
+    forecastPoints,
+    lastActualPoint,
+    combinedData,
+    solidLastXPos,
+  }
+}
+
+/**
+ * Resolves the x-position used to clip the area gradient fill. When forecast data is present we use
+ * the solid line's clip boundary (`solidLastXPos`) so the gradient exactly tracks the solid line.
+ * Otherwise we fall back to the last actual data point's x-position.
+ */
+function computeAreaLastXPos(
+  solidLastXPos: number | null,
+  transformedData: { xValues: string[] },
+  actualDataLength: number,
+  xScale: d3.ScalePoint<string>,
+  chartWidth: number,
+): number {
+  if (solidLastXPos !== null) return solidLastXPos
+  const fallback = transformedData.xValues[actualDataLength - 1]
+  return fallback ? (xScale(fallback) ?? chartWidth) : chartWidth
+}
+
+export function LineChart({
+  data,
+  config,
+  lines,
+  xAxisKey = 'name',
+  className,
+  showGrid = true,
+  gridDensity = 'sparse',
+  loading = false,
+  yAxisPosition = 'left',
+  formatters,
+  showTooltipLabels = false,
+  chartLegendProps,
+  tooltipLineOrder,
+  connectNulls = false,
+  extraTooltipRows,
+  qaTestId = 'line-chart',
+}: LineChartProps): React.ReactElement {
+  const formatYAxisTick = formatters?.formatYAxisTick
+  const formatYAxisTickRight = formatters?.formatYAxisTickRight
+  const formatXAxisTick = formatters?.formatXAxisTick
+
+  const svgRef = useRef<SVGSVGElement>(null)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const { width = 0, height = 0 } = useResizeObserver({
+    ref: containerRef as React.RefObject<HTMLElement>,
+  })
+  const responsive = useMemo(() => getResponsiveStyles(width), [width])
+  const axisOverrides: AxisStyleOverrides = useMemo(
+    () => ({
+      fontSize: responsive.axisFontSize,
+      yAxisWidth: responsive.yAxisWidth,
+      gap: responsive.axisGap,
+    }),
+    [responsive],
+  )
+  const dimensions = useMemo(
+    () => ({
+      width,
+      height: Math.max(responsive.minChartHeight, height),
+    }),
+    [width, height, responsive.minChartHeight],
+  )
+
+  const [tooltipData, setTooltipData] = useState<TooltipData | null>(null)
+  const [tooltipPos, setTooltipPos] = useState<{ x: number; y: number }>({
+    x: 0,
+    y: 0,
+  })
+  const [hoverX, setHoverX] = useState<number | null>(null)
+  const [activePointIndex, setActivePointIndex] = useState<number | null>(null)
+  const cleanupRef = useRef<(() => void) | null>(null)
+  const lastHoverXRef = useRef<number | null>(null)
+  const lastActiveIndexRef = useRef<number | null>(null)
+  const lastTooltipPosRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 })
+  const tooltipDataRef = useRef<TooltipData | null>(null)
+  const tooltipElementRef = useRef<HTMLDivElement>(null)
+  const scalesRef = useRef<{
+    yScaleLeft: d3.ScaleLinear<number, number>
+    yScaleRight: d3.ScaleLinear<number, number> | null
+    hasDualAxis: boolean
+  } | null>(null)
+
+  const transformedData = useMemo(() => {
+    if (!data || data.length === 0) return null
+    if (!lines || lines.length === 0) return null
+
+    try {
+      const allData = [...data]
+      lines.forEach((lineConfig) => {
+        if (lineConfig.forecast && Array.isArray(lineConfig.forecast)) {
+          allData.push(...lineConfig.forecast)
+        }
+      })
+
+      const transformed = transformChartData(allData, lines, {
+        xAxisKey,
+        startFromZero: false, // Line charts should show data range, not force 0 baseline
+        allowNullsAsGaps: true, // null → NaN for D3 line.defined() gaps; BarChart keeps default false
+      })
+      return {
+        ...transformed,
+        actualDataLength: data.length,
+      }
+    } catch (error) {
+      console.error('[LineChart] Data transformation error:', error)
+      return null
+    }
+  }, [data, lines, xAxisKey])
+
+  const transformedDataRef = useRef(transformedData)
+  const linesRef = useRef(lines)
+  const dataRef = useRef(data)
+  const tooltipLineOrderRef = useRef(tooltipLineOrder)
+  const extraTooltipRowsRef = useRef(extraTooltipRows)
+
+  useEffect(() => {
+    transformedDataRef.current = transformedData
+    linesRef.current = lines
+    dataRef.current = data
+    tooltipLineOrderRef.current = tooltipLineOrder
+    extraTooltipRowsRef.current = extraTooltipRows
+  }, [transformedData, lines, data, tooltipLineOrder, extraTooltipRows])
+
+  const scaleCalculations = useMemo(() => {
+    if (!transformedData || dimensions.width === 0) return null
+
+    const yAxisGap = getYAxisGap(axisOverrides)
+    const chartHeight = dimensions.height - responsive.marginBottom - responsive.lineMarginTop
+    const tickCount = DENSITY_TICK_COUNT[gridDensity]
+
+    const hasDualAxis = lines.some((l) => l.yAxisId === 'right')
+
+    if (!hasDualAxis) {
+      const yScale = createLinearScale(transformedData.yDomain, [chartHeight, 0], tickCount)
+      const yTicks = yScale.ticks(tickCount)
+      return {
+        hasDualAxis: false as const,
+        yScaleLeft: yScale,
+        yScaleRight: null,
+        yTicksLeft: yTicks,
+        yTicksRight: null,
+        yAxisGap,
+        chartHeight,
+      }
+    }
+
+    function domainFromValues(values: number[]): [number, number] {
+      if (values.length === 0) return [0, 1]
+      const min = Math.min(...values)
+      const max = Math.max(...values)
+      let yMin = min
+      let yMax = max
+      if (min === max) {
+        const pad = Math.abs(max) || 1
+        yMin = min - pad
+        yMax = max + pad
+      }
+      return [yMin, yMax]
+    }
+
+    const leftKeys = lines.filter((l) => l.yAxisId !== 'right').map((l) => l.dataKey)
+    const rightKeys = lines.filter((l) => l.yAxisId === 'right').map((l) => l.dataKey)
+
+    const leftValues: number[] = []
+    const rightValues: number[] = []
+    transformedData.data.forEach((datum) => {
+      leftKeys.forEach((key) => {
+        const v = datum[key] as number
+        if (typeof v === 'number' && !Number.isNaN(v)) leftValues.push(v)
+      })
+      rightKeys.forEach((key) => {
+        const v = datum[key] as number
+        if (typeof v === 'number' && !Number.isNaN(v)) rightValues.push(v)
+      })
+    })
+
+    const yDomainLeft = domainFromValues(leftValues)
+    const yDomainRight = domainFromValues(rightValues)
+
+    const yScaleLeft = createLinearScale(yDomainLeft, [chartHeight, 0], tickCount)
+    const yScaleRight = createLinearScale(yDomainRight, [chartHeight, 0], tickCount)
+    const yTicksLeft = yScaleLeft.ticks(tickCount)
+    const yTicksRight = yScaleRight.ticks(tickCount)
+
+    return {
+      hasDualAxis: true as const,
+      yScaleLeft,
+      yScaleRight,
+      yTicksLeft,
+      yTicksRight,
+      yAxisGap,
+      chartHeight,
+    }
+  }, [
+    transformedData,
+    dimensions.width,
+    dimensions.height,
+    gridDensity,
+    lines,
+    responsive,
+    axisOverrides,
+  ])
+
+  const chartDimensionsRef = useRef<{
+    chartStartX: number
+    chartWidth: number
+    chartHeight: number
+  } | null>(null)
+  const layoutKeyRef = useRef<string | null>(null)
+
+  useEffect(() => {
+    if (!svgRef.current || !scaleCalculations || !transformedData) return
+
+    const { hasDualAxis, yScaleLeft, yScaleRight, yTicksLeft, yTicksRight, yAxisGap, chartHeight } =
+      scaleCalculations
+
+    scalesRef.current = {
+      yScaleLeft,
+      yScaleRight,
+      hasDualAxis,
+    }
+
+    const actualDataLength = transformedData.actualDataLength
+    const svg = d3.select(svgRef.current)
+    const existingContent = svg.select('.d3-content').node()
+    const formatterKey = `${formatYAxisTick?.toString() ?? ''}-${formatYAxisTickRight?.toString() ?? ''}`
+    const linesSignature = lines
+      .map((l) => `${l.dataKey}:${l.stroke ?? ''}:${l.yAxisId ?? 'left'}`)
+      .join('|')
+    const layoutKey = `${dimensions.width}-${dimensions.height}-${lines.length}-${showGrid}-${gridDensity}-${yAxisPosition}-${formatterKey}-${showTooltipLabels}-${linesSignature}`
+
+    const isDataOnlyUpdate = existingContent != null && layoutKeyRef.current === layoutKey
+    const isResize = existingContent != null && !isDataOnlyUpdate
+    const animDuration = isResize ? 0 : CHART_STYLES.animationDuration
+
+    if (isDataOnlyUpdate) {
+      const d3Content = svg.select<SVGGElement>('.d3-content')
+      const chartDims = chartDimensionsRef.current
+      if (!chartDims) return
+
+      // Clear tooltip when we update paths so we don't show stale content until next hover
+      tooltipDataRef.current = null
+      setTooltipData(null)
+
+      const { chartWidth } = chartDims
+      const xScale = createPointScale(transformedData.xValues, [0, chartWidth], 0)
+
+      const xAxisGroup = d3Content.select<SVGGElement>('.x-axis')
+      if (!xAxisGroup.empty()) {
+        renderXAxis(
+          xAxisGroup,
+          xScale,
+          responsive.marginBottom,
+          formatXAxisTick,
+          axisOverrides,
+          true,
+        )
+      }
+      if (hasDualAxis && yTicksRight) {
+        const leftYAxisGroup = d3Content.select<SVGGElement>('.y-axis-left')
+        const rightYAxisGroup = d3Content.select<SVGGElement>('.y-axis-right')
+        if (!leftYAxisGroup.empty())
+          renderYAxis(leftYAxisGroup, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+        if (!rightYAxisGroup.empty())
+          renderYAxis(
+            rightYAxisGroup,
+            yScaleRight,
+            yTicksRight,
+            formatYAxisTickRight,
+            axisOverrides,
+          )
+      } else {
+        const yAxisGroup = d3Content.select<SVGGElement>('.y-axis')
+        if (!yAxisGroup.empty())
+          renderYAxis(yAxisGroup, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+      }
+
+      const chartGroup = d3Content.select<SVGGElement>('.chart-group')
+      const areasGroup = chartGroup.select<SVGGElement>('.areas')
+      const linesGroup = chartGroup.select<SVGGElement>('.lines')
+      const forecastGroup = chartGroup.select<SVGGElement>('.forecast')
+
+      lines.forEach((lineConfig, index) => {
+        const getXPosition = (d: LineChartData, i: number, _dataArray: LineChartData[]): number => {
+          // When connectNulls filters out data points, index no longer matches
+          // xValues array — resolve x from the datum's own xAxisKey instead.
+          const xValue = connectNulls ? String(d[xAxisKey]) : transformedData.xValues[i]
+          if (xValue === undefined) return 0
+          return xScale(xValue) ?? 0
+        }
+
+        const yScaleForLine =
+          lineConfig.yAxisId === 'right' && yScaleRight !== null ? yScaleRight : yScaleLeft
+        const getYPosition = (d: LineChartData): number => {
+          const value = d[lineConfig.dataKey] as number
+          return yScaleForLine(value)
+        }
+
+        const dataKey = lineConfig.dataKey
+        // Skip NaN points so D3 draws a gap instead of connecting through null data
+        const isDefined = (d: LineChartData) => {
+          const v = d[dataKey]
+          return typeof v === 'number' && !Number.isNaN(v)
+        }
+        const lineGenerator = d3
+          .line<LineChartData>()
+          .x((d, i, data) => getXPosition(d, i, data as LineChartData[]))
+          .y(getYPosition)
+          .curve(d3.curveMonotoneX)
+        if (!connectNulls) {
+          lineGenerator.defined(isDefined)
+        }
+
+        const {
+          actualData: sharedActualData,
+          hasForecast,
+          forecastPoints: sharedForecastPoints,
+          lastActualPoint: sharedLastActualPoint,
+          combinedData: sharedCombinedData,
+          solidLastXPos: sharedSolidLastXPos,
+        } = buildLineRenderData(
+          lineConfig,
+          transformedData,
+          actualDataLength,
+          connectNulls,
+          isDefined,
+          xScale,
+          xAxisKey,
+        )
+
+        if (index === 0) {
+          const areaGenerator = d3
+            .area<LineChartData>()
+            .x((d, i, data) => getXPosition(d, i, data as LineChartData[]))
+            .y0(chartHeight)
+            .y1(getYPosition)
+            .curve(d3.curveMonotoneX)
+          if (!connectNulls) {
+            areaGenerator.defined(isDefined) // Same gaps as line
+          }
+
+          const areaData = sharedCombinedData ?? sharedActualData
+          const areaPath = areaGenerator(areaData)
+          const areaPathEl = areasGroup.selectAll('path').filter((_, i) => i === 0)
+          if (areaPath && !areaPathEl.empty()) {
+            areaPathEl.attr('d', areaPath)
+            const lastXPos = computeAreaLastXPos(
+              sharedSolidLastXPos,
+              transformedData,
+              actualDataLength,
+              xScale,
+              chartWidth,
+            )
+            d3Content
+              .select(`#area-clip-${index}`)
+              .select('rect')
+              .attr('x', 0)
+              .attr('width', lastXPos)
+          }
+        }
+
+        if (hasForecast) {
+          const lastActualPoint = sharedLastActualPoint
+          const forecastPoints = sharedForecastPoints
+          const combinedData = sharedCombinedData
+          if (lastActualPoint && forecastPoints && combinedData) {
+            const combinedPath = lineGenerator(combinedData)
+            if (combinedPath) {
+              const linePathEl = linesGroup.selectAll('path').filter((_, i) => i === index)
+              if (!linePathEl.empty()) {
+                linePathEl.attr('d', combinedPath)
+              }
+              const lastXPos = sharedSolidLastXPos ?? 0
+              d3Content
+                .select(`#solid-forecast-clip-${index}`)
+                .select('rect')
+                .attr('x', 0)
+                .attr('width', lastXPos)
+              const forecastPathEl = forecastGroup.selectAll('path').filter((_, i) => i === index)
+              if (!forecastPathEl.empty()) {
+                forecastPathEl.attr('d', combinedPath)
+              }
+              d3Content
+                .select(`#forecast-clip-${index}`)
+                .select('rect')
+                .attr('x', lastXPos)
+                .attr('width', chartWidth - lastXPos)
+            }
+          }
+        } else {
+          const linePath = lineGenerator(sharedActualData)
+          const linePathEl = linesGroup.selectAll('path').filter((_, i) => i === index)
+          if (linePath && !linePathEl.empty()) {
+            linePathEl.attr('d', linePath)
+            const pathNode = linePathEl.node() as SVGPathElement | null
+            const pathLength = pathNode ? pathNode.getTotalLength() : 0
+            if (lineConfig.dashed) {
+              // Dashed lines render plainly (no reveal mask), so just keep the dash pattern applied.
+              const dashPattern = lineConfig.strokeDashArray ?? CHART_STYLES.defaultStrokeDashArray
+              linePathEl.attr('stroke-dasharray', dashPattern).attr('stroke-dashoffset', 0)
+            } else {
+              linePathEl.attr('stroke-dasharray', pathLength).attr('stroke-dashoffset', 0)
+            }
+          }
+        }
+      })
+
+      // Update persistent dots: one invisible circle per (line × data point) for QA
+      {
+        const persistentGroup = d3Content.select<SVGGElement>('.persistent-dots')
+        persistentGroup.selectAll('*').remove()
+        const actualDataForDots = transformedData.data.slice(0, actualDataLength)
+        lines.forEach((lineConfig, lineIndex) => {
+          const yScaleForLine =
+            lineConfig.yAxisId === 'right' && yScaleRight !== null ? yScaleRight : yScaleLeft
+          actualDataForDots.forEach((datum, dataIndex) => {
+            const xValue = transformedData.xValues[dataIndex]
+            if (xValue === undefined) return
+            const value = datum[lineConfig.dataKey] as number
+            if (typeof value !== 'number' || Number.isNaN(value)) return
+            persistentGroup
+              .append('circle')
+              .attr('class', 'persistent-dot')
+              .attr('data-line-key', lineConfig.dataKey)
+              .attr('data-line-index', String(lineIndex))
+              .attr('cx', xScale(xValue) ?? 0)
+              .attr('cy', yScaleForLine(value))
+              .attr('r', responsive.dotRadius)
+              .attr('fill', 'transparent')
+              .attr('stroke', 'transparent')
+              .attr('opacity', 0)
+              .style('pointer-events', 'none')
+          })
+        })
+      }
+
+      return
+    }
+
+    layoutKeyRef.current = layoutKey
+    if (cleanupRef.current) {
+      cleanupRef.current()
+      cleanupRef.current = null
+    }
+
+    // Clear tooltip and hover state so we don't show stale data after line/config change
+    tooltipDataRef.current = null
+    lastTooltipPosRef.current = { x: 0, y: 0 }
+    setTooltipData(null)
+    setTooltipPos({ x: 0, y: 0 })
+    lastHoverXRef.current = null
+    lastActiveIndexRef.current = null
+    setHoverX(null)
+    setActivePointIndex(null)
+
+    svg.attr('width', dimensions.width).attr('height', dimensions.height)
+    const d3Content = svg.append('g').attr('class', 'd3-content')
+
+    const minLeftForXLabels =
+      getMaxXAxisLabelWidth(d3Content, transformedData.xValues, formatXAxisTick, axisOverrides) / 2
+
+    let chartStartX: number
+    let chartWidth: number
+
+    if (hasDualAxis && yTicksRight) {
+      const tempLeft = d3Content
+        .append('g')
+        .attr('class', 'y-axis-temp')
+        .style('visibility', 'hidden')
+      renderYAxis(tempLeft, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+      let leftLabelWidth = 0
+      tempLeft.selectAll('text').each(function () {
+        leftLabelWidth = Math.max(leftLabelWidth, (this as SVGTextElement).getBBox().width)
+      })
+      tempLeft.remove()
+
+      const tempRight = d3Content
+        .append('g')
+        .attr('class', 'y-axis-temp')
+        .style('visibility', 'hidden')
+      renderYAxis(tempRight, yScaleRight, yTicksRight, formatYAxisTickRight, axisOverrides)
+      let rightLabelWidth = 0
+      tempRight.selectAll('text').each(function () {
+        rightLabelWidth = Math.max(rightLabelWidth, (this as SVGTextElement).getBBox().width)
+      })
+      tempRight.remove()
+
+      chartStartX = Math.max(leftLabelWidth + yAxisGap, minLeftForXLabels)
+      const chartEndPadding = Math.max(responsive.marginRightDualAxis, rightLabelWidth + yAxisGap)
+      chartWidth = dimensions.width - chartStartX - chartEndPadding
+
+      const leftYAxisGroup = d3Content
+        .append('g')
+        .attr('class', 'y-axis y-axis-left')
+        .attr('transform', `translate(0, ${responsive.lineMarginTop})`)
+      renderYAxis(leftYAxisGroup, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+
+      const rightYAxisGroup = d3Content
+        .append('g')
+        .attr('class', 'y-axis y-axis-right')
+        .attr(
+          'transform',
+          `translate(${chartStartX + chartWidth + yAxisGap}, ${responsive.lineMarginTop})`,
+        )
+      renderYAxis(rightYAxisGroup, yScaleRight, yTicksRight, formatYAxisTickRight, axisOverrides)
+    } else {
+      const tempYAxisGroup = d3Content
+        .append('g')
+        .attr('class', 'y-axis-temp')
+        .style('visibility', 'hidden')
+      renderYAxis(tempYAxisGroup, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+
+      let maxLabelWidth = 0
+      tempYAxisGroup.selectAll('text').each(function () {
+        const bbox = (this as SVGTextElement).getBBox()
+        maxLabelWidth = Math.max(maxLabelWidth, bbox.width)
+      })
+      tempYAxisGroup.remove()
+
+      const labelAreaWidth = maxLabelWidth + yAxisGap
+
+      chartStartX =
+        yAxisPosition === 'left'
+          ? Math.max(labelAreaWidth, minLeftForXLabels)
+          : responsive.marginRight
+      const chartEndPadding = yAxisPosition === 'left' ? 0 : labelAreaWidth
+      chartWidth = dimensions.width - chartStartX - chartEndPadding
+
+      const yAxisX = yAxisPosition === 'left' ? 0 : chartStartX + chartWidth + yAxisGap
+      const yAxisGroup = d3Content
+        .append('g')
+        .attr('class', 'y-axis')
+        .attr('transform', `translate(${yAxisX}, ${responsive.lineMarginTop})`)
+      renderYAxis(yAxisGroup, yScaleLeft, yTicksLeft, formatYAxisTick, axisOverrides)
+    }
+
+    chartDimensionsRef.current = { chartStartX, chartWidth, chartHeight }
+
+    const xScale = createPointScale(transformedData.xValues, [0, chartWidth], 0)
+
+    const chartGroup = d3Content
+      .append('g')
+      .attr('class', 'chart-group')
+      .attr('transform', `translate(${chartStartX}, ${responsive.lineMarginTop})`)
+
+    const defs = d3Content.append('defs')
+    lines.forEach((lineConfig, index) => {
+      const lineColor = getLineColor(lineConfig, index)
+
+      if (index === 0) {
+        const gradientId = `gradient-primary-${index}`
+        const gradient = defs
+          .append('linearGradient')
+          .attr('id', gradientId)
+          .attr('gradientUnits', 'userSpaceOnUse')
+          .attr('x1', 0)
+          .attr('y1', 0)
+          .attr('x2', 0)
+          .attr('y2', chartHeight)
+
+        gradient
+          .append('stop')
+          .attr('offset', '0%')
+          .attr('stop-color', lineColor)
+          .attr('stop-opacity', 0.1)
+
+        gradient
+          .append('stop')
+          .attr('offset', '100%')
+          .attr('stop-color', lineColor)
+          .attr('stop-opacity', 0)
+      }
+    })
+
+    if (showGrid) {
+      renderGrid({
+        container: chartGroup,
+        yScale: yScaleLeft,
+        width: chartWidth,
+        tickValues: yTicksLeft,
+        lineStyle: 'dot',
+      })
+    }
+
+    const xAxisGroup = d3Content
+      .append('g')
+      .attr('class', 'x-axis')
+      .attr('transform', `translate(${chartStartX}, ${chartHeight + responsive.lineMarginTop})`)
+    renderXAxis(xAxisGroup, xScale, responsive.marginBottom, formatXAxisTick, axisOverrides, true)
+
+    const areasGroup = chartGroup.append('g').attr('class', 'areas')
+    const linesGroup = chartGroup.append('g').attr('class', 'lines')
+    const forecastGroup = chartGroup.append('g').attr('class', 'forecast')
+    lines.forEach((lineConfig, index) => {
+      const lineColor = getLineColor(lineConfig, index)
+      const strokeWidth = lineConfig.strokeWidth || CHART_STYLES.defaultStrokeWidth
+
+      const getXPosition = (d: LineChartData, i: number, _dataArray: LineChartData[]): number => {
+        const xValue = connectNulls ? String(d[xAxisKey]) : transformedData.xValues[i]
+        if (xValue === undefined) return 0
+        return xScale(xValue) ?? 0
+      }
+
+      const yScaleForLine =
+        lineConfig.yAxisId === 'right' && yScaleRight !== null ? yScaleRight : yScaleLeft
+      const getYPosition = (d: LineChartData): number => {
+        const value = d[lineConfig.dataKey] as number
+        return yScaleForLine(value)
+      }
+
+      const dataKey = lineConfig.dataKey
+      // Skip NaN points so D3 draws a gap instead of connecting through null data
+      const isDefined = (d: LineChartData) => {
+        const v = d[dataKey]
+        return typeof v === 'number' && !Number.isNaN(v)
+      }
+      const lineGenerator = d3
+        .line<LineChartData>()
+        .x((d, i, data) => getXPosition(d, i, data as LineChartData[]))
+        .y(getYPosition)
+        .curve(d3.curveMonotoneX)
+      if (!connectNulls) {
+        lineGenerator.defined(isDefined)
+      }
+
+      const {
+        actualData: sharedActualData,
+        hasForecast,
+        forecastPoints: sharedForecastPoints,
+        lastActualPoint: sharedLastActualPoint,
+        combinedData: sharedCombinedData,
+        solidLastXPos: sharedSolidLastXPos,
+      } = buildLineRenderData(
+        lineConfig,
+        transformedData,
+        actualDataLength,
+        connectNulls,
+        isDefined,
+        xScale,
+        xAxisKey,
+      )
+
+      if (index === 0) {
+        const areaGenerator = d3
+          .area<LineChartData>()
+          .x((d, i, data) => getXPosition(d, i, data as LineChartData[]))
+          .y0(chartHeight)
+          .y1(getYPosition)
+          .curve(d3.curveMonotoneX)
+        if (!connectNulls) {
+          areaGenerator.defined(isDefined) // Same gaps as line
+        }
+
+        const areaData = sharedCombinedData ?? sharedActualData
+        const areaPath = areaGenerator(areaData)
+        if (areaPath) {
+          const lastXPos = computeAreaLastXPos(
+            sharedSolidLastXPos,
+            transformedData,
+            actualDataLength,
+            xScale,
+            chartWidth,
+          )
+
+          const areaAnimateRightToLeft =
+            (hasDualAxis && lineConfig.yAxisId === 'right') ||
+            (!hasDualAxis && yAxisPosition === 'right')
+
+          const clipId = `area-clip-${index}`
+          const clipRect = defs
+            .append('clipPath')
+            .attr('id', clipId)
+            .append('rect')
+            .attr('y', 0)
+            .attr('height', chartHeight)
+            .attr('x', areaAnimateRightToLeft ? lastXPos : 0)
+            .attr('width', 0)
+
+          const areaAnimDuration =
+            sharedForecastPoints != null
+              ? Math.round(animDuration * (chartWidth > 0 ? lastXPos / chartWidth : 0))
+              : animDuration
+          const areaEase = sharedForecastPoints != null ? d3.easeLinear : CHART_STYLES.animationEase
+
+          // When duration is 0 (resize/rebuild), set attributes synchronously
+          // instead of via a RAF-deferred transition. On iOS Safari, post-tap
+          // RAF callbacks can be throttled, leaving clip rects stuck at width=0
+          // and making the forecast line permanently invisible.
+          if (areaAnimDuration > 0) {
+            clipRect
+              .transition()
+              .duration(areaAnimDuration)
+              .ease(areaEase)
+              .attr('x', 0)
+              .attr('width', lastXPos)
+          } else {
+            clipRect.attr('x', 0).attr('width', lastXPos)
+          }
+
+          areasGroup
+            .append('path')
+            .attr('d', areaPath)
+            .attr('fill', `url(#gradient-primary-${index})`)
+            .attr('stroke', 'none')
+            .attr('clip-path', `url(#${clipId})`)
+            .style('will-change', 'transform')
+            .style('backface-visibility', 'hidden')
+            .style('transform', 'translate3d(0, 0, 0)')
+        }
+      }
+
+      if (hasForecast) {
+        const lastActualPoint = sharedLastActualPoint
+        const forecastPoints = sharedForecastPoints
+        const combinedData = sharedCombinedData
+        if (!lastActualPoint || !forecastPoints || !combinedData) return
+        const combinedPath = lineGenerator(combinedData)
+        if (combinedPath) {
+          const animateRightToLeft =
+            (hasDualAxis && lineConfig.yAxisId === 'right') ||
+            (!hasDualAxis && yAxisPosition === 'right')
+          const lastXPos = sharedSolidLastXPos ?? 0
+
+          // Proportional timing: both segments draw at the same px/ms speed so
+          // the handoff feels like one continuous motion.
+          const solidFraction = chartWidth > 0 ? lastXPos / chartWidth : 0
+          const solidDuration = Math.round(animDuration * solidFraction)
+          const forecastDuration = animDuration - solidDuration
+
+          // Solid portion: animated clip-rect reveals left to right
+          const solidClipId = `solid-forecast-clip-${index}`
+          const solidClipRect = defs
+            .append('clipPath')
+            .attr('id', solidClipId)
+            .append('rect')
+            .attr('y', 0)
+            .attr('height', chartHeight)
+            .attr('x', animateRightToLeft ? lastXPos : 0)
+            .attr('width', 0)
+          if (solidDuration > 0) {
+            solidClipRect
+              .transition()
+              .duration(solidDuration)
+              .ease(d3.easeLinear)
+              .attr('x', 0)
+              .attr('width', lastXPos)
+          } else {
+            solidClipRect.attr('x', 0).attr('width', lastXPos)
+          }
+          linesGroup
+            .append('path')
+            .attr('d', combinedPath)
+            .attr('clip-path', `url(#${solidClipId})`)
+            .attr('fill', 'none')
+            .attr('stroke', lineColor)
+            .attr('stroke-width', strokeWidth)
+            .attr('stroke-linecap', 'round')
+            .attr('stroke-linejoin', 'round')
+            .style('will-change', 'transform')
+            .style('backface-visibility', 'hidden')
+            .style('transform', 'translate3d(0, 0, 0)')
+
+          // Dashed forecast portion: starts the instant the solid segment finishes.
+          // For right-to-left axes the forecast reveals from the right edge inward,
+          // mirroring the direction of the solid segment animation.
+          const forecastClipId = `forecast-clip-${index}`
+          const forecastClipRect = defs
+            .append('clipPath')
+            .attr('id', forecastClipId)
+            .append('rect')
+            .attr('x', animateRightToLeft ? chartWidth : lastXPos)
+            .attr('y', 0)
+            .attr('width', 0)
+            .attr('height', chartHeight)
+          if (forecastDuration > 0) {
+            forecastClipRect
+              .transition()
+              .delay(solidDuration)
+              .duration(forecastDuration)
+              .ease(d3.easeLinear)
+              .attr('x', lastXPos)
+              .attr('width', chartWidth - lastXPos)
+          } else {
+            forecastClipRect.attr('x', lastXPos).attr('width', chartWidth - lastXPos)
+          }
+          forecastGroup
+            .append('path')
+            .attr('clip-path', `url(#${forecastClipId})`)
+            .attr('d', combinedPath)
+            .attr('fill', 'none')
+            .attr('stroke', lineColor)
+            .attr('stroke-width', strokeWidth)
+            .attr('stroke-linecap', 'round')
+            .attr('stroke-linejoin', 'round')
+            .attr('stroke-dasharray', '4 6')
+            .style('will-change', 'transform')
+            .style('backface-visibility', 'hidden')
+            .style('transform', 'translate3d(0, 0, 0)')
+        }
+      } else {
+        const linePath = lineGenerator(sharedActualData)
+
+        if (linePath) {
+          const animateRightToLeft =
+            (hasDualAxis && lineConfig.yAxisId === 'right') ||
+            (!hasDualAxis && yAxisPosition === 'right')
+
+          if (lineConfig.dashed) {
+            // Render the dashed line directly (no draw-in reveal). It used to "draw in" via an
+            // animated mask (a white stroke revealed by stroke-dashoffset); when a re-render
+            // interrupted that transition the mask could be left partially open, so the dashed line
+            // tapered off toward one end or vanished until a resize forced a redraw. Drawing it
+            // plainly keeps it reliably visible — its own dash pattern provides the dashes.
+            const dashPattern = lineConfig.strokeDashArray ?? CHART_STYLES.defaultStrokeDashArray
+            linesGroup
+              .append('path')
+              .attr('d', linePath)
+              .attr('fill', 'none')
+              .attr('stroke', lineColor)
+              .attr('stroke-width', strokeWidth)
+              .attr('stroke-linecap', 'round')
+              .attr('stroke-linejoin', 'round')
+              .attr('stroke-dasharray', dashPattern)
+              .style('will-change', 'transform')
+              .style('backface-visibility', 'hidden')
+              .style('transform', 'translate3d(0, 0, 0)')
+          } else {
+            const lineElement = linesGroup
+              .append('path')
+              .attr('d', linePath)
+              .attr('fill', 'none')
+              .attr('stroke', lineColor)
+              .attr('stroke-width', strokeWidth)
+              .attr('stroke-linecap', 'round')
+              .attr('stroke-linejoin', 'round')
+              .style('will-change', 'transform, stroke-dashoffset')
+              .style('backface-visibility', 'hidden')
+              .style('transform', 'translate3d(0, 0, 0)')
+
+            const pathNode = lineElement.node() as SVGPathElement | null
+            if (pathNode) {
+              const pathLength = pathNode.getTotalLength()
+              lineElement.attr('stroke-dasharray', pathLength)
+              if (animDuration > 0) {
+                const initialOffset = animateRightToLeft ? -pathLength : pathLength
+                lineElement
+                  .attr('stroke-dashoffset', initialOffset)
+                  .transition()
+                  .duration(animDuration)
+                  .ease(CHART_STYLES.animationEase)
+                  .attr('stroke-dashoffset', 0)
+              } else {
+                lineElement.attr('stroke-dashoffset', 0)
+              }
+            }
+          }
+        }
+      }
+    })
+
+    chartGroup.append('g').attr('class', 'hover-dots')
+
+    // QA automation: one invisible circle per (line × data point) for every
+    // metric/series. Lives outside hover-dots so hover cleanup doesn't touch it.
+    {
+      const persistentGroup = chartGroup
+        .append('g')
+        .attr('class', 'persistent-dots')
+        .style('pointer-events', 'none')
+      const actualDataForDots = transformedData.data.slice(0, actualDataLength)
+      lines.forEach((lineConfig, lineIndex) => {
+        const yScaleForLine =
+          lineConfig.yAxisId === 'right' && yScaleRight !== null ? yScaleRight : yScaleLeft
+        actualDataForDots.forEach((datum, dataIndex) => {
+          const xValue = transformedData.xValues[dataIndex]
+          if (xValue === undefined) return
+          const value = datum[lineConfig.dataKey] as number
+          if (typeof value !== 'number' || Number.isNaN(value)) return
+          persistentGroup
+            .append('circle')
+            .attr('class', 'persistent-dot')
+            .attr('data-line-key', lineConfig.dataKey)
+            .attr('data-line-index', String(lineIndex))
+            .attr('cx', xScale(xValue) ?? 0)
+            .attr('cy', yScaleForLine(value))
+            .attr('r', responsive.dotRadius)
+            .attr('fill', 'transparent')
+            .attr('stroke', 'transparent')
+            .attr('opacity', 0)
+            .style('pointer-events', 'none')
+        })
+      })
+    }
+
+    svg.append('g').attr('class', 'hover-line')
+
+    // Hover interaction with throttling. Read from refs so tooltip stays correct
+    // after data-only updates (e.g. time period change) when handlers are not re-attached.
+    const handleMouseMove = throttle((event: unknown) => {
+      const mouseEvent = event as MouseEvent
+      if (!svgRef.current) return
+
+      const currentData = transformedDataRef.current
+      const currentLines = linesRef.current
+      const chartDims = chartDimensionsRef.current
+      if (!currentData || !currentLines || !chartDims) return
+
+      const dataLength = currentData.actualDataLength
+      const xScaleCurrent = createPointScale(currentData.xValues, [0, chartDims.chartWidth], 0)
+      const actualXValuesCurrent = currentData.xValues.slice(0, dataLength)
+      const sortedPointsCurrent = actualXValuesCurrent
+        .map((xVal, i) => {
+          if (xVal === undefined) return null
+          const pointPosition = xScaleCurrent(xVal) ?? 0
+          return { x: pointPosition, index: i }
+        })
+        .filter((p): p is { x: number; index: number } => p !== null)
+
+      const rect = svgRef.current.getBoundingClientRect()
+      const mouseX = mouseEvent.clientX - rect.left - chartDims.chartStartX
+
+      const clampedMouseX = Math.round(Math.max(0, Math.min(chartDims.chartWidth, mouseX)))
+
+      const nearestIndex = findNearestPoint(sortedPointsCurrent, clampedMouseX)
+
+      const nearestPoint = sortedPointsCurrent.find((p) => p.index === nearestIndex)
+      const snappedX = nearestPoint ? Math.round(nearestPoint.x) : clampedMouseX
+
+      if (lastHoverXRef.current !== snappedX) {
+        lastHoverXRef.current = snappedX
+        setHoverX(snappedX)
+      }
+
+      if (lastActiveIndexRef.current !== nearestIndex) {
+        lastActiveIndexRef.current = nearestIndex
+        setActivePointIndex(nearestIndex)
+      }
+
+      let tooltipDatum: LineChartData | null = null
+      let tooltipXValue: string | null = null
+
+      if (nearestIndex >= 0 && nearestIndex < dataLength) {
+        const datum = currentData.data[nearestIndex]
+        const xVal = currentData.xValues[nearestIndex]
+        if (datum !== undefined) {
+          tooltipDatum = datum
+        }
+        if (xVal !== undefined) {
+          tooltipXValue = String(xVal)
+        }
+      }
+
+      if (tooltipDatum && tooltipXValue) {
+        const currentTooltipLineOrder = tooltipLineOrderRef.current
+        const currentExtraRows = extraTooltipRowsRef.current
+        const linesForTooltip = currentTooltipLineOrder
+          ? currentTooltipLineOrder
+              .filter((i) => i >= 0 && i < currentLines.length)
+              .map((i) => currentLines[i])
+              .filter((line): line is NonNullable<typeof line> => line !== undefined)
+          : currentLines
+
+        // Build extra tooltip rows first so we know which line rows to suppress
+        const extraEntries: TooltipData['values'] = []
+        const suppressedDataKeys = new Set<string>()
+
+        if (currentExtraRows) {
+          for (const extra of currentExtraRows) {
+            const raw = tooltipDatum[extra.dataKey]
+            const num = typeof raw === 'number' ? raw : NaN
+            if (Number.isNaN(num)) continue
+            extraEntries.push({
+              value: num,
+              color: extra.color,
+              ...(extra.isForecast && { indicator: 'dashed' as const }),
+              ...(extra.formatValue && { formatValue: extra.formatValue }),
+              ...(showTooltipLabels && extra.label != null && { label: extra.label }),
+            })
+            // When this extra row has a valid value, suppress the line row it replaces
+            if (extra.replacesDataKey) {
+              suppressedDataKeys.add(extra.replacesDataKey)
+            }
+          }
+        }
+
+        const tooltipValues: TooltipData['values'] = linesForTooltip
+          .filter((lineConfig) => !suppressedDataKeys.has(lineConfig.dataKey))
+          .map((lineConfig, idx) => {
+            const value = (tooltipDatum as LineChartData)[lineConfig.dataKey] as number
+            const color = getLineColor(lineConfig, idx)
+            const formatValue =
+              lineConfig.yAxisId === 'right' ? formatYAxisTickRight : formatYAxisTick
+            const label = config[lineConfig.dataKey]?.label
+            return {
+              value,
+              color,
+              ...(formatValue && { formatValue }),
+              ...(showTooltipLabels && label != null && { label }),
+            }
+          })
+
+        // Append extra tooltip rows after line rows
+        for (const entry of extraEntries) {
+          tooltipValues.push(entry)
+        }
+
+        // Don't show tooltip when hovering over a point with all null/NaN values
+        const hasValidData = tooltipValues.some((v) => v.value != null && !Number.isNaN(v.value))
+        if (!hasValidData) {
+          tooltipDataRef.current = null
+          setTooltipData(null)
+        } else {
+          const newTooltipData = {
+            date: String(tooltipXValue),
+            values: tooltipValues,
+          }
+
+          const currentTooltipData = tooltipDataRef.current
+          const dateChanged = !currentTooltipData || currentTooltipData.date !== newTooltipData.date
+          // Exclude label from equality: ReactNode compares by reference, so JSX would always differ
+          const valuesChanged =
+            !currentTooltipData ||
+            currentTooltipData.values.length !== newTooltipData.values.length ||
+            currentTooltipData.values.some(
+              (val, idx) =>
+                val.value !== newTooltipData.values[idx]?.value ||
+                val.color !== newTooltipData.values[idx]?.color ||
+                val.indicator !== newTooltipData.values[idx]?.indicator,
+            )
+
+          if (dateChanged || valuesChanged) {
+            tooltipDataRef.current = newTooltipData
+            setTooltipData(newTooltipData)
+          }
+        }
+      }
+    })
+
+    /** Convert a TouchEvent into a synthetic { clientX, clientY } and forward to the mouse handler. */
+    const handleTouchMove = (event: unknown) => {
+      const touchEvent = event as TouchEvent
+      const touch = touchEvent.touches[0]
+      if (!touch) return
+
+      // When the finger moves outside the SVG, dismiss the tooltip instead of
+      // letting it drift. We also stop calling preventDefault so Android can
+      // resume native scroll for this touch.
+      if (svgRef.current) {
+        const svgRect = svgRef.current.getBoundingClientRect()
+        if (
+          touch.clientX < svgRect.left ||
+          touch.clientX > svgRect.right ||
+          touch.clientY < svgRect.top ||
+          touch.clientY > svgRect.bottom
+        ) {
+          tooltipDataRef.current = null
+          setTooltipData(null)
+          lastHoverXRef.current = null
+          setHoverX(null)
+          lastActiveIndexRef.current = null
+          setActivePointIndex(null)
+          return
+        }
+      }
+
+      touchEvent.preventDefault()
+      handleMouseMove({
+        clientX: touch.clientX,
+        clientY: touch.clientY,
+      } as unknown)
+    }
+
+    const handleTouchEnd = () => {
+      tooltipDataRef.current = null
+      setTooltipData(null)
+      lastHoverXRef.current = null
+      setHoverX(null)
+      lastActiveIndexRef.current = null
+      setActivePointIndex(null)
+    }
+
+    const handleMouseLeave = () => {
+      tooltipDataRef.current = null
+      setTooltipData(null)
+      lastHoverXRef.current = null
+      setHoverX(null)
+      lastActiveIndexRef.current = null
+      setActivePointIndex(null)
+    }
+
+    chartGroup
+      .append('rect')
+      .attr('width', chartWidth)
+      .attr('height', chartHeight)
+      .attr('fill', 'transparent')
+      .attr('pointer-events', 'all')
+      .on('mousemove', handleMouseMove)
+      .on('mouseleave', handleMouseLeave)
+      .on('touchstart', handleTouchMove, { passive: false })
+      .on('touchmove', handleTouchMove, { passive: false })
+      .on('touchend', handleTouchEnd)
+      .on('touchcancel', handleTouchEnd)
+
+    cleanupRef.current = () => {
+      svg.selectAll('.d3-content').remove()
+    }
+  }, [
+    scaleCalculations,
+    transformedData,
+    lines,
+    config,
+    data,
+    dimensions.width,
+    dimensions.height,
+    showGrid,
+    yAxisPosition,
+    gridDensity,
+    formatters,
+    formatXAxisTick,
+    formatYAxisTick,
+    formatYAxisTickRight,
+    showTooltipLabels,
+    responsive,
+    axisOverrides,
+    connectNulls,
+    xAxisKey,
+  ])
+
+  const sampledPathsRef = useRef<Map<number, { x: number; y: number }[]>>(new Map())
+
+  useEffect(() => {
+    sampledPathsRef.current.clear()
+  }, [transformedData, dimensions])
+
+  useEffect(() => {
+    if (!svgRef.current || !transformedDataRef.current) return
+
+    const svg = d3.select(svgRef.current)
+    const hoverLineGroup = svg.select('.hover-line')
+    const hoverDotsGroup = svg.select('.hover-dots')
+
+    // ── Not hovering (mouse left chart): hide hover UI. QA anchors stay in
+    //    <g class="persistent-dots"> with opacity 0 — we do not touch that group.
+    if (hoverX === null) {
+      const existingLine = hoverLineGroup.select('line')
+      if (!existingLine.empty()) {
+        existingLine.style('opacity', 0)
+      }
+      hoverDotsGroup.selectAll(`.${HOVER_ACTIVE_DOT_CLASS}`).remove()
+      return
+    }
+
+    // ── Hovering: show dashed vertical line + normal visible dots on the lines
+    const transformedData = transformedDataRef.current
+    const lines = linesRef.current
+    const data = dataRef.current
+    const chartDims = chartDimensionsRef.current
+    const scales = scalesRef.current
+
+    if (!chartDims || !scales) return
+
+    const { chartStartX, chartWidth } = chartDims
+    const { yScaleLeft, yScaleRight } = scales
+
+    const chartHeight = dimensions.height - responsive.marginBottom - responsive.lineMarginTop
+
+    const xScale = createPointScale(transformedData.xValues, [0, chartWidth], 0)
+
+    const gridGroup = svg.select('.grid')
+    let yTop = responsive.lineMarginTop
+    let yBottom = chartHeight + responsive.lineMarginTop
+
+    if (!gridGroup.empty()) {
+      const gridNode = gridGroup.node()
+      if (gridNode && gridNode instanceof SVGGElement) {
+        const gridBBox = gridNode.getBBox()
+        yTop = gridBBox.y + responsive.lineMarginTop
+        yBottom = gridBBox.y + gridBBox.height + responsive.lineMarginTop
+      }
+    }
+
+    const actualData = transformedData.data.slice(0, data.length)
+
+    const getXPosition = (d: LineChartData, i: number, _dataArray: LineChartData[]): number => {
+      const xValue = connectNulls ? String(d[xAxisKey]) : transformedData.xValues[i]
+      if (xValue === undefined) return 0
+      return xScale(xValue) ?? 0
+    }
+
+    const dotPositions: { x: number; y: number; color: string }[] = []
+
+    const hoveredDatum = activePointIndex != null ? actualData[activePointIndex] : undefined
+
+    lines.forEach((lineConfig, lineIndex) => {
+      if (hoveredDatum) {
+        const v = hoveredDatum[lineConfig.dataKey]
+        if (typeof v !== 'number' || Number.isNaN(v)) return
+      }
+
+      let sampledPoints = sampledPathsRef.current.get(lineIndex)
+
+      if (!sampledPoints) {
+        const yScaleForLine =
+          lineConfig.yAxisId === 'right' && yScaleRight !== null ? yScaleRight : yScaleLeft
+        const getYPositionForLine = (d: LineChartData): number => {
+          const value = d[lineConfig.dataKey] as number
+          return yScaleForLine(value)
+        }
+
+        const dataKeyForHover = lineConfig.dataKey
+        // Match main line: exclude NaN so hover samples only along visible segments
+        const isDefinedForHover = (d: LineChartData) => {
+          const v = d[dataKeyForHover]
+          return typeof v === 'number' && !Number.isNaN(v)
+        }
+        const lineGeneratorForLine = d3
+          .line<LineChartData>()
+          .x((d, i, data) => getXPosition(d, i, data as LineChartData[]))
+          .y(getYPositionForLine)
+          .curve(d3.curveMonotoneX)
+        if (!connectNulls) {
+          lineGeneratorForLine.defined(isDefinedForHover)
+        }
+
+        const hoverData = connectNulls ? actualData.filter(isDefinedForHover) : actualData
+        const pathDataForLine = lineGeneratorForLine(hoverData)
+        if (!pathDataForLine) return
+
+        const pathElement = document.createElementNS('http://www.w3.org/2000/svg', 'path')
+        pathElement.setAttribute('d', pathDataForLine)
+        const totalLength = pathElement.getTotalLength()
+
+        sampledPoints = []
+        // Empty path (e.g. all NaN) throws in getPointAtLength; skip sampling
+        if (totalLength > 0) {
+          for (let i = 0; i <= 200; i++) {
+            const length = (i / 200) * totalLength
+            const point = pathElement.getPointAtLength(length)
+            sampledPoints.push({ x: point.x, y: point.y })
+          }
+        }
+
+        sampledPathsRef.current.set(lineIndex, sampledPoints)
+      }
+
+      let left = 0
+      let right = sampledPoints.length - 1
+      let closestIndex = 0
+      let minDistance = Infinity
+
+      while (left <= right) {
+        const mid = Math.floor((left + right) / 2)
+        const point = sampledPoints[mid]
+        if (!point) break
+
+        const distance = Math.abs(point.x - hoverX)
+        if (distance < minDistance) {
+          minDistance = distance
+          closestIndex = mid
+        }
+
+        if (point.x < hoverX) {
+          left = mid + 1
+        } else {
+          right = mid - 1
+        }
+      }
+
+      const closestPoint = sampledPoints[closestIndex]
+      if (closestPoint) {
+        const lineDotX = Math.max(0, Math.min(chartWidth, closestPoint.x))
+        const lineDotY = closestPoint.y
+
+        const lineColor = getLineColor(lineConfig, lineIndex)
+
+        dotPositions.push({
+          x: lineDotX + chartStartX,
+          y: lineDotY + responsive.lineMarginTop,
+          color: lineColor,
+        })
+      }
+    })
+
+    // Use the data-driven hoverX for the vertical line so it always aligns with
+    // the hovered x-axis tick, even when the first line has no data there.
+    const lineX = hoverX + chartStartX
+    const existingLine = hoverLineGroup.select('line')
+
+    if (existingLine.empty()) {
+      hoverLineGroup
+        .append('line')
+        .attr('x1', lineX)
+        .attr('y1', yTop)
+        .attr('x2', lineX)
+        .attr('y2', yBottom)
+        .attr('stroke', CHART_STYLES.borderSubColor)
+        .attr('stroke-width', 2)
+        .attr('stroke-linecap', 'round')
+        .attr('stroke-dasharray', '0.1 8')
+        .style('pointer-events', 'none')
+        .style('opacity', 1)
+        .style('will-change', 'transform')
+        .style('transform', 'translate3d(0, 0, 0)')
+    } else {
+      existingLine
+        .attr('x1', lineX)
+        .attr('y1', yTop)
+        .attr('x2', lineX)
+        .attr('y2', yBottom)
+        .style('opacity', 1)
+    }
+
+    if (dotPositions.length > 0) {
+      // Use the first visible dot's Y for vertical positioning, but always use
+      // hoverX for horizontal so the tooltip tracks the data tick, not a line.
+      const firstDot = dotPositions[0]
+      if (!firstDot) {
+        return
+      }
+      const tooltipX = hoverX
+      const tooltipY = firstDot.y - responsive.lineMarginTop
+      const newTooltipPos = { x: tooltipX, y: tooltipY }
+
+      if (lastTooltipPosRef.current.x !== tooltipX || lastTooltipPosRef.current.y !== tooltipY) {
+        lastTooltipPosRef.current = newTooltipPos
+        setTooltipPos({
+          x: tooltipX + chartStartX,
+          y: tooltipY + responsive.lineMarginTop,
+        })
+      }
+
+      hoverDotsGroup.selectAll(`.${HOVER_ACTIVE_DOT_CLASS}`).remove()
+
+      dotPositions.forEach((dotPos) => {
+        hoverDotsGroup
+          .append('circle')
+          .attr('class', HOVER_ACTIVE_DOT_CLASS)
+          .attr('cx', dotPos.x - chartStartX)
+          .attr('cy', dotPos.y - responsive.lineMarginTop)
+          .attr('r', responsive.dotRadius)
+          .attr('fill', CHART_STYLES.dotFillActive)
+          .attr('stroke', dotPos.color)
+          .attr('stroke-width', CHART_STYLES.dotStrokeWidth)
+          .style('pointer-events', 'none')
+      })
+    } else {
+      hoverDotsGroup.selectAll(`.${HOVER_ACTIVE_DOT_CLASS}`).remove()
+    }
+  }, [
+    hoverX,
+    activePointIndex,
+    dimensions,
+    gridDensity,
+    yAxisPosition,
+    responsive,
+    connectNulls,
+    xAxisKey,
+  ])
+
+  useEffect(() => {
+    return () => {
+      if (cleanupRef.current) {
+        cleanupRef.current()
+      }
+    }
+  }, [])
+
+  useEventListener(
+    'scroll',
+    () => {
+      if (!containerRef.current || !tooltipDataRef.current) return
+      const rect = containerRef.current.getBoundingClientRect()
+      if (rect.bottom < 0 || rect.top > window.innerHeight) {
+        tooltipDataRef.current = null
+        setTooltipData(null)
+        setHoverX(null)
+        lastHoverXRef.current = null
+        lastActiveIndexRef.current = null
+        setActivePointIndex(null)
+      }
+    },
+    undefined,
+    { passive: true, capture: true },
+  )
+
+  if (loading) {
+    return <ChartSkeleton height={300} className={className} qaTestId={qaTestId} />
+  }
+
+  if (!data || data.length === 0) {
+    throw new Error('[LineChart] data prop is required and must not be empty')
+  }
+
+  if (!lines || lines.length === 0) {
+    throw new Error('[LineChart] lines prop is required and must not be empty')
+  }
+
+  const hasLegend = chartLegendProps != null
+  const defaultLegendItems =
+    chartLegendProps != null
+      ? lines.map((lineConfig, idx) => ({
+          key: lineConfig.dataKey,
+          label: config[lineConfig.dataKey]?.label ?? lineConfig.dataKey,
+          color: getLineColor(lineConfig, idx),
+        }))
+      : []
+  const legendItems = chartLegendProps?.items ?? defaultLegendItems
+  const showLegend = hasLegend && legendItems.length > 0
+  const legendProps: D3ChartLegendProps | undefined =
+    showLegend && chartLegendProps != null
+      ? {
+          items: legendItems,
+          style: chartLegendProps.style,
+          onToggle: chartLegendProps.onToggle,
+          className: chartLegendProps.className,
+        }
+      : undefined
+
+  return (
+    <div
+      className={cn('relative flex w-full flex-col', showLegend && 'h-full', className)}
+      style={{ overflow: 'visible', minHeight: responsive.minChartHeight }}
+      qa-test-id={qaTestId}
+    >
+      <div ref={containerRef} className='min-h-0 flex-1'>
+        <svg
+          ref={svgRef}
+          className='w-full'
+          style={{ height: dimensions.height, overflow: 'visible' }}
+        />
+      </div>
+      {showLegend && legendProps ? <D3ChartLegendFooter legend={legendProps} scrollable /> : null}
+      {/* Tooltip rendered in portal to prevent clipping by parent containers */}
+      <D3Tooltip
+        data={tooltipData}
+        x={tooltipPos.x}
+        y={tooltipPos.y}
+        containerRef={containerRef}
+        tooltipRef={tooltipElementRef}
+        tooltipFormatters={formatters?.D3TooltipFormatters}
+        showLabels={showTooltipLabels}
+      />
+    </div>
+  )
+}