Merge pull request #158 from mgifford/copilot/add-tooltip-for-numerical-calculations

Add calculation tooltips to Performance Impact estimated totals

Author: mgifford

src/publish/render-pages.js

@@ -1431,20 +1431,30 @@ function renderPerformanceImpactSection(report) {
   const urlCount = impact.url_count_with_timing;
   const scanDate = escapeHtml(formatScanDate(report.run_date));
 
+  const timeDuration = formatDuration(extraHours);
+  const totalSeconds = Number(impact.total_extra_load_time_seconds).toLocaleString('en-US');
+  const timeTipId = `perf-impact-tip-${_perfTimeTooltipSeq++}`;
+  const timeTooltipText = `Extra time is calculated as: for each scanned URL, max(0, actual LCP \u2212 ${escapeHtml(benchmarkLcpSec)}s) \u00d7 page loads. Total: ${escapeHtml(totalSeconds)} seconds.`;
+  const timeValueHtml = `<span class="perf-time-trigger" role="button" tabindex="0" aria-label="${escapeHtml(timeDuration)}" aria-describedby="${timeTipId}">${escapeHtml(timeDuration)}<span id="${timeTipId}" role="tooltip" class="perf-time-tooltip">${timeTooltipText}</span></span>`;
+
   const timeRow = `<tr>
       <td data-label="Metric">Extra time waiting (vs ${benchmarkLcpSec}s LCP benchmark)</td>
-      <td data-label="Estimated total">${formatDuration(extraHours)}</td>
-      <td data-label="Notes">${Number(impact.total_extra_load_time_seconds).toLocaleString('en-US')} seconds</td>
+      <td data-label="Estimated total">${timeValueHtml}</td>
+      <td data-label="Notes">${totalSeconds} seconds</td>
     </tr>`;
 
-  const weightRow =
-    impact.url_count_with_weight > 0
-      ? `<tr>
+  let weightRow = '';
+  if (impact.url_count_with_weight > 0) {
+    const dataSizeStr = formatDataSize(extraGb);
+    const weightTipId = `perf-impact-tip-${_perfTimeTooltipSeq++}`;
+    const weightTooltipText = `Extra data is calculated as: for each scanned URL, max(0, actual page weight \u2212 ${escapeHtml(benchmarkWeightMb)} MB) \u00d7 page loads.`;
+    const weightValueHtml = `<span class="perf-time-trigger" role="button" tabindex="0" aria-label="${escapeHtml(dataSizeStr)}" aria-describedby="${weightTipId}">${escapeHtml(dataSizeStr)}<span id="${weightTipId}" role="tooltip" class="perf-time-tooltip">${weightTooltipText}</span></span>`;
+    weightRow = `<tr>
       <td data-label="Metric">Extra data transferred (vs ${benchmarkWeightMb} MB page weight benchmark)</td>
-      <td data-label="Estimated total">${formatDataSize(extraGb)}</td>
+      <td data-label="Estimated total">${weightValueHtml}</td>
       <td data-label="Notes">Across ${Number(impact.url_count_with_weight).toLocaleString('en-US')} URLs with weight data</td>
-    </tr>`
-      : '';
+    </tr>`;
+  }
 
   return `
   <section aria-labelledby="performance-impact-heading">
@@ -1464,7 +1474,7 @@ function renderPerformanceImpactSection(report) {
         ${weightRow}
       </tbody>
     </table>`)}
-    <p><small>Extra time is calculated as: for each scanned URL, <em>max(0, actual LCP &minus; ${benchmarkLcpSec}s) &times; page loads</em>. Extra data is calculated as: <em>max(0, actual page weight &minus; ${benchmarkWeightMb} MB) &times; page loads</em>. LCP and page weight are measured by Lighthouse. Wikipedia copy count uses a size of 24.05 GB per <a href="https://en.wikipedia.org/wiki/Wikipedia:Size_of_Wikipedia" target="_blank" rel="noreferrer">Wikipedia:Size of Wikipedia</a>. These are rough estimates based on a sample of the top government URLs by traffic.</small></p>
+    <p><small>LCP and page weight are measured by Lighthouse. Wikipedia copy count uses a size of 24.05 GB per <a href="https://en.wikipedia.org/wiki/Wikipedia:Size_of_Wikipedia" target="_blank" rel="noreferrer">Wikipedia:Size of Wikipedia</a>. These are rough estimates based on a sample of the top government URLs by traffic. Hover or focus the estimated totals for calculation details.</small></p>
   </section>`;
 }
 

tests/unit/render-pages.test.js

@@ -2381,6 +2381,60 @@ test('renderDailyReportPage: performance impact shows GB and Wikipedia copies fo
   assert.ok(html.includes('copies of Wikipedia'), 'Should show Wikipedia copy count for moderate data');
 });
 
+test('renderDailyReportPage: performance impact time value has tooltip with formula and seconds', () => {
+  const report = {
+    ...minimalReport,
+    run_date: '2026-03-20',
+    performance_impact: {
+      benchmark_lcp_ms: 2500,
+      benchmark_page_weight_bytes: 1_600_000,
+      url_count_with_timing: 5,
+      url_count_with_weight: 0,
+      total_extra_load_time_seconds: 310_216_405,
+      total_extra_load_time_hours: 86171,
+      total_extra_bytes: 0,
+      total_extra_gigabytes: 0
+    }
+  };
+
+  const html = renderDailyReportPage(report);
+
+  // Duration value should be wrapped in a perf-time-trigger tooltip span
+  assert.ok(html.includes('class="perf-time-trigger"'), 'Duration value should use perf-time-trigger');
+  assert.ok(html.includes('class="perf-time-tooltip"'), 'Duration value should have a perf-time-tooltip');
+  assert.ok(html.includes('role="tooltip"'), 'Tooltip should have role=tooltip');
+  // Tooltip should contain the formula and total seconds
+  assert.ok(html.includes('310,216,405 seconds'), 'Tooltip should show total seconds');
+  assert.ok(html.includes('Extra time is calculated as'), 'Tooltip should contain the LCP formula');
+  assert.ok(html.includes('max(0, actual LCP'), 'Tooltip should include max(0, actual LCP formula text');
+});
+
+test('renderDailyReportPage: performance impact data value has tooltip with formula', () => {
+  const report = {
+    ...minimalReport,
+    run_date: '2026-03-20',
+    performance_impact: {
+      benchmark_lcp_ms: 2500,
+      benchmark_page_weight_bytes: 1_600_000,
+      url_count_with_timing: 5,
+      url_count_with_weight: 97,
+      total_extra_load_time_seconds: 1000,
+      total_extra_load_time_hours: 0.28,
+      total_extra_bytes: 72_748_199_470_000,
+      total_extra_gigabytes: 67728.43
+    }
+  };
+
+  const html = renderDailyReportPage(report);
+
+  // Data size value should also have a tooltip
+  // Both time and data rows have perf-time-trigger tooltips
+  const triggerMatches = (html.match(/class="perf-time-trigger"/g) || []).length;
+  assert.ok(triggerMatches >= 2, 'Both time and data rows should have perf-time-trigger tooltips');
+  assert.ok(html.includes('Extra data is calculated as'), 'Data tooltip should contain the page weight formula');
+  assert.ok(html.includes('max(0, actual page weight'), 'Data tooltip should include max(0, actual page weight formula text');
+});
+
 test('renderDailyReportPage URL count cell has tooltip with affected hostnames', () => {
   const report = {
     ...minimalReport,