sunscope/assets/js/events/weather-checks.js

// ------------------------------------------------------------------------
//  weather-checks.js - Weather-derived event detectors.
//
//  Computed in real-time from the forecast data.
//  Each checker function receives (rows [, location]) and returns an event
//  object or null. rows = today's hourlyRows array.
//  location = { lat, lon, name, country }.
//
//  To add a new weather event: write a checkXxx(rows, location) function
//  below, export it, and add it to the checks[] array inside
//  getActiveEvents() (in events.js).
// ------------------------------------------------------------------------

export function checkStargazing(rows) {
  // Great stargazing: mostly clear night hours with low cloud
  const nightRows = rows.filter(r => r.elev < -5);
  if (nightRows.length < 3) return null;
  const avgCloud = nightRows.reduce((s, r) => s + r.cc, 0) / nightRows.length;
  if (avgCloud > 30) return null;
  return {
    id: 'stargazing',
    emoji: '⭐',
    title: 'Great Stargazing Tonight',
    message: `Clear skies expected overnight at ${nightRows.length} hours with average ${Math.round(avgCloud)}% cloud — ideal conditions for stargazing.`,
    color: '#080e1a',
    textColor: '#c8dcff',
    type: 'weather',
    nightOnly: true,
  };
}

export function checkSunset(rows, location) {
  // Find the actual sunset window: the LAST contiguous run of rows where
  // solar elevation is in the golden/civil-twilight band (-3- to 8-).
  // This distinguishes sunset from sunrise (which is the first such run).
  const twilightIndices = rows
    .map((r, i) => ({ r, i }))
    .filter(({ r }) => r.elev > -3 && r.elev < 8);
  if (twilightIndices.length === 0) return null;

  // Split into runs separated by gaps (midday gap separates sunrise from sunset)
  const runs = [];
  let run = [twilightIndices[0]];
  for (let k = 1; k < twilightIndices.length; k++) {
    if (twilightIndices[k].i === twilightIndices[k - 1].i + 1) {
      run.push(twilightIndices[k]);
    } else {
      runs.push(run);
      run = [twilightIndices[k]];
    }
  }
  runs.push(run);

  // Use the LAST run (sunset). If only one run exists it's either sunrise-only
  // or a single dusk window - use it but we'll label generically.
  const sunsetRun = runs[runs.length - 1];
  const sunsetRows = sunsetRun.map(({ r }) => r);
  const isSunrise = runs.length === 1 && sunsetRows[0].elev < sunsetRows[sunsetRows.length - 1].elev;
  // If sun is rising through the band this is a sunrise window, not sunset - skip.
  if (isSunrise) return null;

  const avgCloud = sunsetRows.reduce((s, r) => s + r.cc, 0) / sunsetRows.length;
  const avgLowCloud = sunsetRows.reduce((s, r) => s + (r.ccLow || 0), 0) / sunsetRows.length;
  if (avgLowCloud > 25) return null;
  if (avgCloud < 5 || avgCloud > 75) return null;

  // Store the ISO time range so getCellTagEvents can limit the icon to those hours
  const firstISO = sunsetRun[0].r.iso;
  const lastISO  = sunsetRun[sunsetRun.length - 1].r.iso;

  return {
    id: 'perfect-sunset',
    emoji: '🌅',
    title: 'Spectacular Sunset Conditions',
    message: `Low cloud is clear near the horizon but high cloud will scatter the light — conditions look ideal for a vivid sunset near ${location.name}.`,
    color: '#3a1a00',
    textColor: '#ffe0b0',
    type: 'weather',
    nightOnly: false,
    isoRange: [firstISO, lastISO],  // only show cell icon during these hours
  };
}

export function checkHeatSpike(rows) {
  const maxTemp = Math.max(...rows.map(r => r.Ta).filter(isFinite));
  if (maxTemp < 30) return null;
  const severity = maxTemp >= 36 ? 'extreme' : maxTemp >= 33 ? 'severe' : 'notable';

  // Only flag the hours that are actually at/above the heat threshold.
  const affected = rows.filter(r => isFinite(r.Ta) && r.Ta >= 30);
  const isoRange = affected.length
    ? [affected[0].iso, affected[affected.length - 1].iso]
    : undefined;

  const msgs = {
    notable: `Temperatures reaching ${maxTemp.toFixed(1)}°C — above seasonal norms. Stay hydrated and avoid prolonged sun exposure.`,
    severe:  `Heat warning: ${maxTemp.toFixed(1)}°C expected today. Risk of heat exhaustion for vulnerable people — keep cool and hydrated.`,
    extreme: `Extreme heat alert: ${maxTemp.toFixed(1)}°C forecast. Risk of heat stroke — avoid outdoor activity during peak hours.`,
  };
  return {
    id: 'heat-spike',
    emoji: '🔥',
    title: severity === 'extreme' ? 'Extreme Heat Alert' : severity === 'severe' ? 'Heat Warning' : 'Heat Spike Today',
    message: msgs[severity],
    color: severity === 'extreme' ? '#3a0000' : severity === 'severe' ? '#4a1000' : '#5a2000',
    textColor: '#ffd0b0',
    type: 'weather',
    nightOnly: false,
    isoRange,  // only show cell icon during the hot hours
  };
}

// Wind and rain are detected separately so each icon lands only on the hours
// that genuinely have that condition. They are mutually exclusive per hour:
//   windy + dry  → wind icon (💨)
//   wet + calm   → rain icon (🌧️)
//   windy + wet  → storm icon (🌩️), and the wind/rain icons are suppressed
//                  for that hour so a single hour never shows two icons.
const GUST_BLUSTERY = 25 / 2.237;   // m/s (= 25 mph) - matches the table's gust highlight
const GUST_STORM    = 20;           // m/s ≈ 45 mph - storm-force
const PRECIP_WET    = 5;      // mm/h - meaningful rain
const PRECIP_HEAVY  = 10;     // mm/h - heavy rain

const gustOf   = r => r.gust ?? r.va ?? 0;
const precipOf = r => r.precip ?? 0;
const isWindyHour = r => { const g = gustOf(r);   return isFinite(g) && g >= GUST_BLUSTERY; };
const isWetHour   = r => { const p = precipOf(r); return isFinite(p) && p >= PRECIP_WET; };
const isStormHour = r => isWindyHour(r) && isWetHour(r);

export function checkWind(rows) {
  // Windy hours that are NOT also wet (those are storms instead).
  const affected = rows.filter(r => isWindyHour(r) && !isStormHour(r));
  if (affected.length === 0) return null;
  const isoRange = [affected[0].iso, affected[affected.length - 1].iso];

  const maxGust = Math.max(...affected.map(gustOf).filter(isFinite));
  const mph = Math.round(maxGust * 2.237);
  const isStorm = maxGust >= GUST_STORM;

  return {
    id: 'wind',
    emoji: '💨',
    title: isStorm ? 'Storm-Force Winds' : 'Blustery Conditions',
    message: isStorm
      ? `Storm-force gusts to ${mph} mph expected — secure loose objects and take care outdoors.`
      : `Windy spell — gusts to ${mph} mph at peak. Hold onto hats and secure loose items outdoors.`,
    color: '#1a2030',
    textColor: '#c0d8f0',
    type: 'weather',
    nightOnly: false,
    isoRange,  // only show cell icon during the windy hours
  };
}

export function checkWet(rows) {
  // Wet hours that are NOT also windy (those are storms instead).
  const affected = rows.filter(r => isWetHour(r) && !isStormHour(r));
  if (affected.length === 0) return null;
  const isoRange = [affected[0].iso, affected[affected.length - 1].iso];

  const maxPrecip = Math.max(...affected.map(precipOf).filter(isFinite));
  const isHeavy = maxPrecip >= PRECIP_HEAVY;

  return {
    id: 'wet',
    emoji: '🌧️',
    title: 'Heavy Rain',
    message: isHeavy
      ? `Heavy rain expected — up to ${maxPrecip.toFixed(1)} mm/h at peak. Roads may flood; allow extra travel time.`
      : `Wet spell — up to ${maxPrecip.toFixed(1)} mm/h rain at peak. Keep a brolly handy.`,
    color: '#15212e',
    textColor: '#bcd6ee',
    type: 'weather',
    nightOnly: false,
    isoRange,  // only show cell icon during the wet hours
  };
}

export function checkStorm(rows) {
  // Storm hours = windy AND wet at the same time.
  const affected = rows.filter(isStormHour);
  if (affected.length === 0) return null;
  const isoRange = [affected[0].iso, affected[affected.length - 1].iso];

  const maxGust = Math.max(...affected.map(gustOf).filter(isFinite));
  const maxPrecip = Math.max(...affected.map(precipOf).filter(isFinite));
  const mph = Math.round(maxGust * 2.237);
  const isSevere = maxGust >= GUST_STORM || maxPrecip >= PRECIP_HEAVY;

  return {
    id: 'storm',
    emoji: '🌩️',
    title: isSevere ? 'Severe Storm' : 'Storm Conditions',
    message: isSevere
      ? `Severe storm — driving rain to ${maxPrecip.toFixed(1)} mm/h and gusts to ${mph} mph. Avoid travel if you can.`
      : `Stormy spell — wind and rain together, gusts to ${mph} mph with ${maxPrecip.toFixed(1)} mm/h rain. Take care outdoors.`,
    color: '#141a26',
    textColor: '#c0d0e8',
    type: 'weather',
    nightOnly: false,
    isoRange,  // only show cell icon during the stormy hours
  };
}

export function checkFrost(rows) {
  const minTemp = Math.min(...rows.map(r => r.Ta).filter(isFinite));
  if (minTemp > 2) return null;

  // Only flag the hours that are actually at/below the frost threshold.
  const affected = rows.filter(r => isFinite(r.Ta) && r.Ta <= 2);
  const isoRange = affected.length
    ? [affected[0].iso, affected[affected.length - 1].iso]
    : undefined;

  return {
    id: 'frost',
    emoji: '❄️',
    title: minTemp <= 0 ? 'Freezing Conditions' : 'Frost Risk Tonight',
    message: minTemp <= 0
      ? `Temperatures dropping to ${minTemp.toFixed(1)}°C — ice on roads and surfaces is likely. Allow extra travel time.`
      : `Temperatures near freezing tonight (${minTemp.toFixed(1)}°C) — frost possible on exposed surfaces and vehicles.`,
    color: '#0a1a2a',
    textColor: '#c8e8ff',
    type: 'weather',
    nightOnly: false,
    isoRange,  // only show cell icon during the frosty hours
  };
}