feat(detail): replace SATs text tables with cascade bar charts, add admissions bar and history accordion

Redesign the School Details page for better parent comprehension:
- New SatsChart component: horizontal cascade bars with ruler scale and
  national average marker (teal/coral palette matching site theme)
- Admissions section: visual progress bar showing 1st-preference demand
  vs available places, colour-coded by oversubscription status
- Historical data: collapse raw year-by-year table behind a disclosure
  element while keeping the performance line chart always visible
- EAL metric: add national average comparison via DeltaChip (backend now
  includes eal_pct in national averages endpoint)
- New formatWithSuppression utility for null/suppressed data handling

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/app.py

@@ -683,7 +683,7 @@ async def get_national_averages(request: Request):
         "reading_avg_score", "maths_avg_score", "gps_avg_score",
         "reading_progress", "writing_progress", "maths_progress",
         "overall_absence_pct", "persistent_absence_pct",
-        "disadvantaged_gap", "disadvantaged_pct", "sen_support_pct",
+        "disadvantaged_gap", "disadvantaged_pct", "sen_support_pct", "eal_pct",
     ]
     ks4_metrics = [
         "attainment_8_score", "progress_8_score",

nextjs-app/components/SatsChart.module.css

@@ -0,0 +1,190 @@
+/* SatsChart — Cascade bar chart for KS2 SATs results */
+
+.container {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 2rem;
+}
+
+/* ── Individual subject column ── */
+.subjectChart {
+  position: relative;
+}
+
+.subjectName {
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted, #6d685f);
+  margin-bottom: 0.65rem;
+}
+
+.chartArea {
+  position: relative;
+  padding-bottom: 0.25rem;
+}
+
+/* ── Gridlines ── */
+.gridlines {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 20px;
+  pointer-events: none;
+}
+
+.gridline {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  width: 1px;
+  background: var(--bg-secondary, #f3ede4);
+}
+
+/* ── National average marker ── */
+.natLine {
+  position: absolute;
+  top: 0;
+  height: calc(100% - 20px);
+  width: 1.5px;
+  background: rgba(224, 114, 86, 0.25); /* --accent-coral at 25% */
+  z-index: 2;
+  pointer-events: none;
+}
+
+.natPill {
+  position: absolute;
+  top: -8px;
+  transform: translateX(-50%);
+  background: var(--accent-coral, #e07256);
+  color: #fff;
+  font-size: 0.55rem;
+  font-weight: 700;
+  padding: 0.1rem 0.4rem;
+  border-radius: 4px;
+  white-space: nowrap;
+  z-index: 3;
+  letter-spacing: 0.02em;
+}
+
+/* ── Bar rows ── */
+.barGroup {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding-top: 0.9rem;
+}
+
+.barRow {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.bar {
+  height: 22px;
+  border-radius: 6px;
+  position: relative;
+  transition: width 0.8s cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+.barExpected {
+  background: var(--accent-teal-light, #3a9e9e);
+}
+
+.barExceeding {
+  background: var(--accent-teal, #2d7d7d);
+}
+
+.barLabel {
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--text-primary, #1a1612);
+  white-space: nowrap;
+  flex-shrink: 0;
+  position: relative;
+  z-index: 3;
+}
+
+.barLabelSuffix {
+  font-weight: 400;
+  color: var(--text-muted, #6d685f);
+  font-size: 0.68rem;
+}
+
+/* ── Ruler ── */
+.ruler {
+  position: relative;
+  height: 16px;
+  margin-top: 0.5rem;
+  border-top: 1px solid var(--border-color, #e5dfd5);
+}
+
+.rulerTick {
+  position: absolute;
+  top: 0;
+  width: 1px;
+  height: 4px;
+  background: var(--border-color, #e5dfd5);
+}
+
+.rulerLabel {
+  position: absolute;
+  top: 6px;
+  font-size: 0.5rem;
+  font-weight: 500;
+  color: var(--text-muted, #6d685f);
+  transform: translateX(-50%);
+  letter-spacing: 0.01em;
+  opacity: 0.7;
+}
+
+/* Anchor first/last labels to edges */
+.rulerLabelFirst {
+  transform: translateX(0);
+}
+
+.rulerLabelLast {
+  transform: translateX(-100%);
+}
+
+/* ── Legend ── */
+.legend {
+  margin-top: 1rem;
+  display: flex;
+  gap: 1.25rem;
+  justify-content: center;
+}
+
+.legendItem {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-size: 0.65rem;
+  font-weight: 500;
+  color: var(--text-muted, #6d685f);
+}
+
+.legendSwatch {
+  width: 8px;
+  height: 8px;
+  border-radius: 3px;
+  flex-shrink: 0;
+}
+
+/* ── Responsive ── */
+@media (max-width: 640px) {
+  .container {
+    grid-template-columns: 1fr;
+    gap: 1.5rem;
+  }
+
+  .legend {
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+}

nextjs-app/components/SatsChart.tsx

@@ -0,0 +1,138 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import styles from './SatsChart.module.css';
+
+interface SubjectData {
+  name: string;
+  expectedPct: number | null;
+  exceedingPct: number | null;
+  nationalExpectedPct: number | null;
+}
+
+interface SatsChartProps {
+  subjects: SubjectData[];
+}
+
+const RULER_TICKS = [0, 25, 50, 75, 100];
+const GRIDLINE_POSITIONS = [25, 50, 75];
+
+function SubjectColumn({ subject }: { subject: SubjectData }) {
+  const expectedRef = useRef<HTMLDivElement>(null);
+  const exceedingRef = useRef<HTMLDivElement>(null);
+
+  const { name, expectedPct, exceedingPct, nationalExpectedPct } = subject;
+
+  // Animate bars on mount
+  useEffect(() => {
+    const bars = [expectedRef.current, exceedingRef.current];
+    bars.forEach((bar) => {
+      if (!bar) return;
+      const target = bar.dataset.width;
+      bar.style.width = '0%';
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          bar.style.width = `${target}%`;
+        });
+      });
+    });
+  }, [expectedPct, exceedingPct]);
+
+  if (expectedPct == null && exceedingPct == null) return null;
+
+  return (
+    <div className={styles.subjectChart}>
+      <div className={styles.subjectName}>{name}</div>
+      <div className={styles.chartArea}>
+        {/* Gridlines */}
+        <div className={styles.gridlines}>
+          {GRIDLINE_POSITIONS.map((pct) => (
+            <div key={pct} className={styles.gridline} style={{ left: `${pct}%` }} />
+          ))}
+        </div>
+
+        {/* National average marker */}
+        {nationalExpectedPct != null && (
+          <div className={styles.natLine} style={{ left: `${nationalExpectedPct}%` }}>
+            <div className={styles.natPill}>{nationalExpectedPct.toFixed(0)}%</div>
+          </div>
+        )}
+
+        {/* Bars */}
+        <div className={styles.barGroup}>
+          {expectedPct != null && (
+            <div className={styles.barRow}>
+              <div
+                ref={expectedRef}
+                className={`${styles.bar} ${styles.barExpected}`}
+                data-width={expectedPct}
+              />
+              <div className={styles.barLabel}>
+                {expectedPct.toFixed(0)}% <span className={styles.barLabelSuffix}>expected</span>
+              </div>
+            </div>
+          )}
+          {exceedingPct != null && (
+            <div className={styles.barRow}>
+              <div
+                ref={exceedingRef}
+                className={`${styles.bar} ${styles.barExceeding}`}
+                data-width={exceedingPct}
+              />
+              <div className={styles.barLabel}>
+                {exceedingPct.toFixed(0)}% <span className={styles.barLabelSuffix}>exceeding</span>
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Ruler */}
+        <div className={styles.ruler}>
+          {RULER_TICKS.map((pct, i) => (
+            <span key={pct}>
+              <div className={styles.rulerTick} style={{ left: `${pct}%` }} />
+              <div
+                className={`${styles.rulerLabel} ${i === 0 ? styles.rulerLabelFirst : ''} ${i === RULER_TICKS.length - 1 ? styles.rulerLabelLast : ''}`}
+                style={{ left: `${pct}%` }}
+              >
+                {pct}%
+              </div>
+            </span>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function SatsChart({ subjects }: SatsChartProps) {
+  const visibleSubjects = subjects.filter(
+    (s) => s.expectedPct != null || s.exceedingPct != null
+  );
+
+  if (visibleSubjects.length === 0) return null;
+
+  return (
+    <div>
+      <div className={styles.container}>
+        {visibleSubjects.map((subject) => (
+          <SubjectColumn key={subject.name} subject={subject} />
+        ))}
+      </div>
+      <div className={styles.legend}>
+        <div className={styles.legendItem}>
+          <div className={styles.legendSwatch} style={{ background: 'var(--accent-teal-light, #3a9e9e)' }} />
+          Expected standard
+        </div>
+        <div className={styles.legendItem}>
+          <div className={styles.legendSwatch} style={{ background: 'var(--accent-teal, #2d7d7d)' }} />
+          Exceeding / high score
+        </div>
+        <div className={styles.legendItem}>
+          <div className={styles.legendSwatch} style={{ background: 'var(--accent-coral, #e07256)', borderRadius: '50%' }} />
+          National average
+        </div>
+      </div>
+    </div>
+  );
+}

nextjs-app/components/SchoolDetailView.module.css

@@ -894,3 +894,105 @@
     margin-top: 1rem;
   }
 }
+
+/* ── Progress scores row (below SatsChart) ── */
+.progressScoresRow {
+  margin-top: 1.25rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color, #e5dfd5);
+}
+
+.progressScoresGrid {
+  display: flex;
+  gap: 1.5rem;
+  flex-wrap: wrap;
+}
+
+.progressScoreItem {
+  display: flex;
+  align-items: baseline;
+  gap: 0.4rem;
+}
+
+.progressScoreLabel {
+  font-size: 0.78rem;
+  font-weight: 500;
+  color: var(--text-muted, #6d685f);
+}
+
+.progressScoreValue {
+  font-size: 0.9rem;
+  font-weight: 700;
+  color: var(--text-primary, #1a1612);
+  font-variant-numeric: tabular-nums;
+}
+
+/* ── Admissions progress bar ── */
+.admissionsBarWrap {
+  margin-bottom: 1rem;
+}
+
+.admissionsBarLabel {
+  font-size: 0.8125rem;
+  color: var(--text-secondary, #5c564d);
+  margin-bottom: 0.4rem;
+}
+
+.admissionsBarLabel strong {
+  color: var(--text-primary, #1a1612);
+  font-weight: 700;
+}
+
+.admissionsBarTrack {
+  height: 20px;
+  background: var(--bg-secondary, #f3ede4);
+  border-radius: 10px;
+  overflow: hidden;
+  position: relative;
+}
+
+.admissionsBarFill {
+  height: 100%;
+  border-radius: 10px;
+  transition: width 0.6s ease;
+}
+
+.admissionsBarOversubscribed {
+  background: var(--accent-coral, #e07256);
+}
+
+.admissionsBarUndersubscribed {
+  background: var(--accent-teal, #2d7d7d);
+}
+
+/* ── History accordion ── */
+.historyDisclosure {
+  margin-top: 1rem;
+}
+
+.historyToggle {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--text-muted, #6d685f);
+  cursor: pointer;
+  padding: 0.5rem 0;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.historyToggle::-webkit-details-marker {
+  display: none;
+}
+
+.historyToggle::before {
+  content: '▸';
+  display: inline-block;
+  transition: transform 0.2s ease;
+  font-size: 0.7rem;
+}
+
+.historyDisclosure[open] > .historyToggle::before {
+  transform: rotate(90deg);
+}

nextjs-app/components/SchoolDetailView.tsx

@@ -22,6 +22,7 @@ import {
   buildOfstedHeroChip,
 } from '@/lib/utils';
 import { DeltaChip } from './DeltaChip';
+import SatsChart from './SatsChart';
 import styles from './SchoolDetailView.module.css';
 
 const OFSTED_LABELS: Record<number, string> = {
@@ -561,127 +562,61 @@ export function SchoolDetailView({
                 )}
               </div>
 
-              <div className={styles.metricGroupsGrid} style={{ marginTop: '1rem' }}>
+              <SatsChart
-                <div className={styles.metricGroup}>
+                subjects={[
-                  <h3 className={styles.metricGroupTitle}>Reading</h3>
+                  {
-                  <div className={styles.metricTable}>
+                    name: 'Reading',
-                    {latestResults.reading_expected_pct !== null && (
+                    expectedPct: latestResults.reading_expected_pct,
-                      <div className={styles.metricRow}>
+                    exceedingPct: latestResults.reading_high_pct,
-                        <span className={styles.metricName}>Expected level</span>
+                    nationalExpectedPct: primaryAvg.reading_expected_pct,
-                        <span className={styles.metricValue}>
+                  },
-                          {formatPercentage(latestResults.reading_expected_pct)}
+                  {
-                          {primaryAvg.reading_expected_pct != null && (
+                    name: 'Writing',
-                            <DeltaChip value={latestResults.reading_expected_pct} baseline={primaryAvg.reading_expected_pct} unit="pts" size="sm" />
+                    expectedPct: latestResults.writing_expected_pct,
-                          )}
+                    exceedingPct: latestResults.writing_high_pct,
-                        </span>
+                    nationalExpectedPct: primaryAvg.writing_expected_pct,
-                      </div>
+                  },
-                    )}
+                  {
-                    {latestResults.reading_high_pct !== null && (
+                    name: 'Maths',
-                      <div className={styles.metricRow}>
+                    expectedPct: latestResults.maths_expected_pct,
-                        <span className={styles.metricName}>Exceeding</span>
+                    exceedingPct: latestResults.maths_high_pct,
-                        <span className={styles.metricValue}>{formatPercentage(latestResults.reading_high_pct)}</span>
+                    nationalExpectedPct: primaryAvg.maths_expected_pct,
-                      </div>
+                  },
-                    )}
+                ]}
-                    {latestResults.reading_progress !== null && (
+              />
-                      <div className={styles.metricRow}>
+
-                        <span className={styles.metricName}>
+              {/* Progress scores row */}
-                          Progress score
+              {(latestResults.reading_progress != null || latestResults.writing_progress != null || latestResults.maths_progress != null) && (
-                          <MetricTooltip metricKey="reading_progress" />
+                <div className={styles.progressScoresRow}>
-                        </span>
+                  <h3 className={styles.subSectionTitle}>Progress Scores</h3>
-                        <span className={`${styles.metricValue} ${progressClass(latestResults.reading_progress)}`}>
+                  <div className={styles.progressScoresGrid}>
+                    {latestResults.reading_progress != null && (
+                      <div className={styles.progressScoreItem}>
+                        <span className={styles.progressScoreLabel}>Reading</span>
+                        <span className={`${styles.progressScoreValue} ${progressClass(latestResults.reading_progress)}`}>
                           {formatProgress(latestResults.reading_progress)}
                         </span>
                       </div>
                     )}
-                    {latestResults.reading_avg_score !== null && (
+                    {latestResults.writing_progress != null && (
-                      <div className={styles.metricRow}>
+                      <div className={styles.progressScoreItem}>
-                        <span className={styles.metricName}>
+                        <span className={styles.progressScoreLabel}>Writing</span>
-                          Average score
+                        <span className={`${styles.progressScoreValue} ${progressClass(latestResults.writing_progress)}`}>
-                          <MetricTooltip metricKey="reading_avg_score" />
-                        </span>
-                        <span className={styles.metricValue}>{latestResults.reading_avg_score.toFixed(1)}</span>
-                      </div>
-                    )}
-                  </div>
-                </div>
-
-                <div className={styles.metricGroup}>
-                  <h3 className={styles.metricGroupTitle}>Writing</h3>
-                  <div className={styles.metricTable}>
-                    {latestResults.writing_expected_pct !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>Expected level</span>
-                        <span className={styles.metricValue}>
-                          {formatPercentage(latestResults.writing_expected_pct)}
-                          {primaryAvg.writing_expected_pct != null && (
-                            <DeltaChip value={latestResults.writing_expected_pct} baseline={primaryAvg.writing_expected_pct} unit="pts" size="sm" />
-                          )}
-                        </span>
-                      </div>
-                    )}
-                    {latestResults.writing_high_pct !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>Exceeding</span>
-                        <span className={styles.metricValue}>{formatPercentage(latestResults.writing_high_pct)}</span>
-                      </div>
-                    )}
-                    {latestResults.writing_progress !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>
-                          Progress score
-                          <MetricTooltip metricKey="writing_progress" />
-                        </span>
-                        <span className={`${styles.metricValue} ${progressClass(latestResults.writing_progress)}`}>
                           {formatProgress(latestResults.writing_progress)}
                         </span>
                       </div>
                     )}
-                  </div>
+                    {latestResults.maths_progress != null && (
-                </div>
+                      <div className={styles.progressScoreItem}>
-
+                        <span className={styles.progressScoreLabel}>Maths</span>
-                <div className={styles.metricGroup}>
+                        <span className={`${styles.progressScoreValue} ${progressClass(latestResults.maths_progress)}`}>
-                  <h3 className={styles.metricGroupTitle}>Maths</h3>
-                  <div className={styles.metricTable}>
-                    {latestResults.maths_expected_pct !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>Expected level</span>
-                        <span className={styles.metricValue}>
-                          {formatPercentage(latestResults.maths_expected_pct)}
-                          {primaryAvg.maths_expected_pct != null && (
-                            <DeltaChip value={latestResults.maths_expected_pct} baseline={primaryAvg.maths_expected_pct} unit="pts" size="sm" />
-                          )}
-                        </span>
-                      </div>
-                    )}
-                    {latestResults.maths_high_pct !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>Exceeding</span>
-                        <span className={styles.metricValue}>{formatPercentage(latestResults.maths_high_pct)}</span>
-                      </div>
-                    )}
-                    {latestResults.maths_progress !== null && (
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>
-                          Progress score
-                          <MetricTooltip metricKey="maths_progress" />
-                        </span>
-                        <span className={`${styles.metricValue} ${progressClass(latestResults.maths_progress)}`}>
                           {formatProgress(latestResults.maths_progress)}
                         </span>
                       </div>
                     )}
-                    {latestResults.maths_avg_score !== null && (
+                  </div>
-                      <div className={styles.metricRow}>
-                        <span className={styles.metricName}>
-                          Average score
-                          <MetricTooltip metricKey="maths_avg_score" />
-                        </span>
-                        <span className={styles.metricValue}>{latestResults.maths_avg_score.toFixed(1)}</span>
                 </div>
               )}
-                  </div>
-                </div>
-              </div>
 
               {(latestResults.reading_progress !== null || latestResults.writing_progress !== null || latestResults.maths_progress !== null) && (
                 <p className={styles.progressNote}>
@@ -852,7 +787,20 @@ export function SchoolDetailView({
       {admissions && (
         <section id="admissions" className={styles.card}>
           <h2 className={styles.sectionTitle}>How Hard to Get Into This School ({formatAcademicYear(admissions.year)})</h2>
-          {admissions.oversubscribed != null && (
+          {admissions.first_preference_applications != null && admissions.published_admission_number != null && (
+            <div className={styles.admissionsBarWrap}>
+              <div className={styles.admissionsBarLabel}>
+                <strong>{admissions.published_admission_number}</strong> places for <strong>{admissions.first_preference_applications}</strong> first-choice applications
+              </div>
+              <div className={styles.admissionsBarTrack}>
+                <div
+                  className={`${styles.admissionsBarFill} ${admissions.oversubscribed ? styles.admissionsBarOversubscribed : styles.admissionsBarUndersubscribed}`}
+                  style={{ width: `${Math.min(100, (admissions.published_admission_number / admissions.first_preference_applications) * 100)}%` }}
+                />
+              </div>
+            </div>
+          )}
+          {admissions.first_preference_applications == null && admissions.oversubscribed != null && (
             <div className={`${styles.admissionsBadge} ${admissions.oversubscribed ? styles.statusWarn : styles.statusGood}`}>
               {admissions.oversubscribed
                 ? '⚠ Oversubscribed'
@@ -905,7 +853,15 @@ export function SchoolDetailView({
                   English as an additional language
                   <MetricTooltip metricKey="eal_pct" />
                 </div>
-                <div className={styles.metricValue}>{formatPercentage(latestResults.eal_pct)}</div>
+                <div className={styles.metricValue}>
+                  {formatPercentage(latestResults.eal_pct)}
+                  {primaryAvg.eal_pct != null && (
+                    <DeltaChip value={latestResults.eal_pct} baseline={primaryAvg.eal_pct} unit="pts" size="sm" />
+                  )}
+                </div>
+                {primaryAvg.eal_pct != null && (
+                  <div className={styles.metricHint}>National avg: {primaryAvg.eal_pct.toFixed(0)}%</div>
+                )}
               </div>
             )}
             {latestResults?.sen_support_pct != null && (
@@ -1034,8 +990,8 @@ export function SchoolDetailView({
             />
           </div>
           {yearlyData.length > 1 && (
-            <>
+            <details className={styles.historyDisclosure}>
-              <p className={styles.historicalSubtitle}>Detailed year-by-year figures</p>
+              <summary className={styles.historyToggle}>View raw year-by-year data</summary>
               <div className={styles.tableWrapper}>
                 <table className={styles.dataTable}>
                   <thead>
@@ -1084,7 +1040,7 @@ export function SchoolDetailView({
                   </tbody>
                 </table>
               </div>
-            </>
+            </details>
           )}
         </section>
       )}

nextjs-app/lib/utils.ts

@@ -71,6 +71,13 @@ export function formatPercentage(value: number | null | undefined, decimals: num
   return `${value.toFixed(decimals)}%`;
 }
 
+export function formatWithSuppression(value: number | null | undefined): { display: string; suppressed: boolean } {
+  if (value == null) return { display: '—', suppressed: true };
+  return { display: formatPercentage(value), suppressed: false };
+}
+
+export const SUPPRESSED_TOOLTIP = 'Data not available — may be suppressed to protect small cohorts.';
+
 /**
  * Format a progress score (can be negative)
  */