feat(compare): trends explorer with England line; gap-honest axis; series regression guard

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0146VHeLAWjDVE2B5uU67jCB

nextjs-app/components/ComparisonChart.tsx

@@ -15,6 +15,7 @@ import { useEffect, useState } from 'react';
 import { Line } from 'react-chartjs-2';
 import { ChartOptions, ChartDataset, PointStyle } from 'chart.js';
 import '@/lib/chartSetup';
+import { buildCompareChart } from '@/lib/compareChartData';
 import type { ComparisonData } from '@/lib/types';
 import {
   CHART_COLORS,
@@ -34,13 +35,16 @@ interface ComparisonChartProps {
   schools: Array<{ urn: number; school_name: string }>;
   metric: string;
   metricLabel: string;
+  /** Official England figure per academic year for this metric — renders a
+   * dashed grey reference line when provided. */
+  nationalByYear?: Record<number, number | null | undefined>;
 }
 
 // One shape per basket slot (MAX_SCHOOLS = 5) — secondary encoding so
 // converging lines stay tellable apart without relying on hue alone.
 const POINT_STYLES: PointStyle[] = ['circle', 'triangle', 'rect', 'rectRot', 'star'];
 
-export function ComparisonChart({ comparisonData, schools, metric, metricLabel }: ComparisonChartProps) {
+export function ComparisonChart({ comparisonData, schools, metric, metricLabel, nationalByYear }: ComparisonChartProps) {
   const isMobile = useIsMobile();
   const [focusedUrn, setFocusedUrn] = useState<number | null>(null);
 
@@ -54,34 +58,48 @@ export function ComparisonChart({ comparisonData, schools, metric, metricLabel }
     return <div>No data available</div>;
   }
 
-  // Union of years across all schools — coverage differs between them.
-  const years = [
-    ...new Set(schools.flatMap((s) => comparisonData[String(s.urn)]?.yearly_data.map((d) => d.year) ?? [])),
-  ].sort((a, b) => a - b);
+  // Pure, tested series construction: union of years with cancelled /
+  // unpublished years kept as real gaps, plus the England overlay.
+  const built = buildCompareChart(comparisonData, schools, metric, nationalByYear);
+  const { years } = built;
 
-  const datasets: ChartDataset<'line'>[] = schools.map((school, index) => {
-    const data = comparisonData[String(school.urn)];
-    const color = CHART_COLORS[index % CHART_COLORS.length];
+  const datasets: ChartDataset<'line'>[] = built.schoolDatasets.map((series) => {
+    const school = schools[series.schoolIndex];
+    const color = CHART_COLORS[series.schoolIndex % CHART_COLORS.length];
     const dimmed = focusedUrn !== null && focusedUrn !== school.urn;
 
     return {
-      label: school.school_name,
-      data: years.map((year) => {
-        const yearData = data?.yearly_data.find((d) => d.year === year);
-        if (!yearData) return null;
-        return yearData[metric as keyof typeof yearData] as number | null;
-      }),
+      label: series.label,
+      data: series.data,
       borderColor: dimmed ? rgbToRgba(color, 0.2) : color,
       backgroundColor: dimmed ? 'transparent' : rgbToRgba(color, 0.1),
       borderWidth: focusedUrn === school.urn ? 3 : dimmed ? 1.5 : 2,
-      pointStyle: POINT_STYLES[index % POINT_STYLES.length],
+      pointStyle: POINT_STYLES[series.schoolIndex % POINT_STYLES.length],
       pointRadius: dimmed ? 2 : isMobile ? 3 : 4,
       pointHoverRadius: isMobile ? 5 : 6,
       tension: 0.3,
-      spanGaps: true,
+      // Never bridge missing years — gaps are information (COVID
+      // cancellations, unpublished 2021/22, schools that opened later).
+      spanGaps: false,
     };
   });
 
+  if (built.englandDataset) {
+    datasets.push({
+      label: built.englandDataset.label,
+      data: built.englandDataset.data,
+      borderColor: 'rgba(109, 104, 95, 0.9)',
+      backgroundColor: 'transparent',
+      borderWidth: 1.5,
+      borderDash: built.englandDataset.borderDash,
+      pointStyle: 'line',
+      pointRadius: 0,
+      pointHoverRadius: 4,
+      tension: 0,
+      spanGaps: false,
+    });
+  }
+
   const chartData = {
     labels: years.map(formatAcademicYear),
     datasets,
@@ -222,6 +240,12 @@ export function ComparisonChart({ comparisonData, schools, metric, metricLabel }
       <div className={styles.canvasBox}>
         <Line data={chartData} options={options} aria-label={`${metricLabel} comparison chart`} />
       </div>
+      {built.showUnpublished202122Note && (
+        <p className={styles.chartNote}>
+          No national tests were held in 2019/20 and 2020/21 (COVID), and DfE didn&apos;t publish
+          school-level figures for 2021/22 — the England average is shown for that year.
+        </p>
+      )}
     </div>
   );
 }