From f64d5e0c21315b6aae62463eb4d24fbd19e80f17 Mon Sep 17 00:00:00 2001
From: Josh Larson <jlarson@mbta.com>
Date: Thu, 13 Aug 2026 14:30:09 -0400
Subject: [PATCH 1/5] fix(events): Add an empty state for months with no events

---
 .../templates/event/_month.html.heex          |  6 +-
 lib/dotcom_web/views/event_view.ex            | 14 ++--
 test/dotcom_web/views/event_view_test.exs     | 66 +++++++++++++------
 test/support/factories/cms/partial/teaser.ex  | 31 +++++++++
 4 files changed, 92 insertions(+), 25 deletions(-)
 create mode 100644 test/support/factories/cms/partial/teaser.ex

diff --git a/lib/dotcom_web/templates/event/_month.html.heex b/lib/dotcom_web/templates/event/_month.html.heex
index 229cf784d6..5630d78a88 100644
--- a/lib/dotcom_web/templates/event/_month.html.heex
+++ b/lib/dotcom_web/templates/event/_month.html.heex
@@ -1,4 +1,4 @@
-<ul class="list-group list-group-flush">
+<ul :if={Enum.any?(@event_teasers)} class="list-group list-group-flush">
   <%= if @conn.assigns.date.year == @year and @conn.assigns.date.month == @month_number do %>
     
 <!-- Previous months button. A JS script sets up a listener for button click -->
@@ -49,3 +49,7 @@
     <% end %>
   <% end %>
 </ul>
+
+<p :if={Enum.empty?(@event_teasers)} class="italic px-6 text-sm sm:text-base">
+  No events scheduled
+</p>
diff --git a/lib/dotcom_web/views/event_view.ex b/lib/dotcom_web/views/event_view.ex
index 15f9d7f3ef..e46d68db97 100644
--- a/lib/dotcom_web/views/event_view.ex
+++ b/lib/dotcom_web/views/event_view.ex
@@ -34,10 +34,16 @@ defmodule DotcomWeb.EventView do
   @doc "Returns a list of event teasers, grouped/sorted by month"
   @spec grouped_by_month([Teaser.t()], number) :: [{number, [Teaser.t()]}]
   def grouped_by_month(events, year) do
-    events
-    |> Enum.filter(&(&1.date.year == year))
-    |> Enum.group_by(& &1.date.month)
-    |> Enum.sort_by(&elem(&1, 0))
+    by_month =
+      events
+      |> Enum.filter(&(&1.date.year == year))
+      |> Enum.group_by(& &1.date.month)
+
+    {earliest_month, latest_month} =
+      by_month |> Stream.map(fn {month, _} -> month end) |> Enum.min_max()
+
+    earliest_month..latest_month
+    |> Enum.map(&{&1, Map.get(by_month, &1, [])})
   end
 
   @doc "Returns a list of event teasers, grouped/sorted by day"
diff --git a/test/dotcom_web/views/event_view_test.exs b/test/dotcom_web/views/event_view_test.exs
index 73e0ff0948..39b7284392 100644
--- a/test/dotcom_web/views/event_view_test.exs
+++ b/test/dotcom_web/views/event_view_test.exs
@@ -3,10 +3,18 @@ defmodule DotcomWeb.EventViewTest do
   import DotcomWeb.EventView
   import CMS.Helpers, only: [parse_iso_datetime: 1]
   import Phoenix.HTML, only: [safe_to_string: 1]
+  alias Test.Support.Factories
+  alias Test.Support.Generators
   alias CMS.Page.Event
   alias CMS.Page.EventAgenda
   alias CMS.Partial.Teaser
 
+  setup do
+    Mox.stub_with(Dotcom.Utils.DateTime.Mock, Dotcom.Utils.DateTime)
+
+    :ok
+  end
+
   describe "show.html" do
     test "the notes section is not rendered when the event notes are empty", %{conn: conn} do
       event = event_factory(0, notes: nil)
@@ -155,29 +163,47 @@ defmodule DotcomWeb.EventViewTest do
     assert render_event_month(3, 2020) == "March 2020"
   end
 
-  test "grouped_by_month/2 for a given year" do
-    events =
-      for y <- 2018..2020, m <- 1..12, into: [] do
-        {:ok, date} = Date.new(y, m, 1)
+  describe "grouped_by_month/2" do
+    test "groups a given event into the corrent year and month" do
+      # Setup
+      date = Generators.Date.random_date()
 
-        for t <- 1..(2 * m), into: [] do
-          %Teaser{
-            id: "#{y}-#{m}-#{t}",
-            path: "/#{y}-#{m}/#{t}",
-            title: "Event #{t} during #{m}/#{y}",
-            type: :event,
-            date: date
-          }
-        end
-      end
-      |> List.flatten()
+      event = Factories.CMS.Partial.Teaser.build(:event_teaser, date: date)
+
+      # Exercise
+      grouped_events = grouped_by_month([event], date.year)
+
+      # Verify
+      assert grouped_events == [{date.month, [event]}]
+    end
+
+    test "includes an empty month if there are events scheduled before and after that month" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+      month = Faker.random_between(2, 11)
 
-    grouped_2020_events = grouped_by_month(events, 2020)
+      earlier_event =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year, month - 1, Faker.random_between(1, 28))
+        )
+
+      later_event =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year, month + 1, Faker.random_between(1, 28))
+        )
 
-    assert grouped_2020_events
-    assert {1, [january_event, _another_january_event]} = List.first(grouped_2020_events)
-    assert january_event.date.month == 1
-    assert january_event.date.year == 2020
+      # Exercise
+      grouped_events = grouped_by_month([earlier_event, later_event], year)
+
+      # Verify
+      assert grouped_events == [
+               {month - 1, [earlier_event]},
+               {month, []},
+               {month + 1, [later_event]}
+             ]
+    end
   end
 
   test "grouped_by_day/2 for a given month" do
diff --git a/test/support/factories/cms/partial/teaser.ex b/test/support/factories/cms/partial/teaser.ex
new file mode 100644
index 0000000000..9b853e8e7e
--- /dev/null
+++ b/test/support/factories/cms/partial/teaser.ex
@@ -0,0 +1,31 @@
+defmodule Test.Support.Factories.CMS.Partial.Teaser do
+  @moduledoc """
+  Generated fake data for %CMS.Partial.Teaser{}
+  """
+
+  use ExMachina
+
+  alias CMS.Partial.Teaser
+  alias Test.Support.FactoryHelpers
+  alias Test.Support.Generators
+
+  @types [:diversion, :event, :news_entry, :page, :project, :project_update]
+
+  def event_teaser_factory do
+    build(:teaser, type: :event)
+  end
+
+  def teaser_factory do
+    %Teaser{
+      id: FactoryHelpers.build(:id),
+      date: Generators.Date.random_date(),
+      type: type(),
+      path: Faker.Internet.url(),
+      title: Faker.Company.catch_phrase()
+    }
+  end
+
+  defp type() do
+    Faker.Util.pick(@types)
+  end
+end

From cebbcb86cc8fce87b9f8a69a4de0343b1953fa1c Mon Sep 17 00:00:00 2001
From: Josh Larson <jlarson@mbta.com>
Date: Thu, 13 Aug 2026 14:51:23 -0400
Subject: [PATCH 2/5] fix: Include empty months earlier or later in the year
 when appropriate

---
 lib/dotcom_web/views/event_view.ex        |  5 +++
 test/dotcom_web/views/event_view_test.exs | 52 +++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/lib/dotcom_web/views/event_view.ex b/lib/dotcom_web/views/event_view.ex
index e46d68db97..ff15a0092a 100644
--- a/lib/dotcom_web/views/event_view.ex
+++ b/lib/dotcom_web/views/event_view.ex
@@ -34,6 +34,8 @@ defmodule DotcomWeb.EventView do
   @doc "Returns a list of event teasers, grouped/sorted by month"
   @spec grouped_by_month([Teaser.t()], number) :: [{number, [Teaser.t()]}]
   def grouped_by_month(events, year) do
+    {earliest_year, latest_year} = events |> Stream.map(& &1.date.year) |> Enum.min_max()
+
     by_month =
       events
       |> Enum.filter(&(&1.date.year == year))
@@ -42,6 +44,9 @@ defmodule DotcomWeb.EventView do
     {earliest_month, latest_month} =
       by_month |> Stream.map(fn {month, _} -> month end) |> Enum.min_max()
 
+    latest_month = if latest_year == year, do: latest_month, else: 12
+    earliest_month = if earliest_year == year, do: earliest_month, else: 1
+
     earliest_month..latest_month
     |> Enum.map(&{&1, Map.get(by_month, &1, [])})
   end
diff --git a/test/dotcom_web/views/event_view_test.exs b/test/dotcom_web/views/event_view_test.exs
index 39b7284392..ef277fbc30 100644
--- a/test/dotcom_web/views/event_view_test.exs
+++ b/test/dotcom_web/views/event_view_test.exs
@@ -204,6 +204,58 @@ defmodule DotcomWeb.EventViewTest do
                {month + 1, [later_event]}
              ]
     end
+
+    test "includes empty months later in the year if there is an event the following year" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+      month = Faker.random_between(1, 11)
+
+      event_this_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year, month, Faker.random_between(1, 28))
+        )
+
+      event_next_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year + 1, Faker.random_between(1, 12), Faker.random_between(1, 28))
+        )
+
+      # Exercise
+      grouped_events = grouped_by_month([event_this_year, event_next_year], year)
+
+      # Verify
+      assert grouped_events ==
+               [{month, [event_this_year]}] ++
+                 Enum.map((month + 1)..12, &{&1, []})
+    end
+
+    test "includes empty months earlier in the year if there is an event in an earlier year" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+      month = Faker.random_between(1, 11)
+
+      event_this_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year, month, Faker.random_between(1, 28))
+        )
+
+      event_last_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year - 1, Faker.random_between(1, 12), Faker.random_between(1, 28))
+        )
+
+      # Exercise
+      grouped_events = grouped_by_month([event_last_year, event_this_year], year)
+
+      # Verify
+      assert grouped_events ==
+               Enum.map(1..(month - 1), &{&1, []}) ++
+                 [{month, [event_this_year]}]
+    end
   end
 
   test "grouped_by_day/2 for a given month" do

From 6135770cdc2ae2937c2e55671b30dca5cba5f7f6 Mon Sep 17 00:00:00 2001
From: Josh Larson <jlarson@mbta.com>
Date: Thu, 13 Aug 2026 15:06:59 -0400
Subject: [PATCH 3/5] fix: Test setup

---
 test/dotcom_web/views/event_view_test.exs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/dotcom_web/views/event_view_test.exs b/test/dotcom_web/views/event_view_test.exs
index ef277fbc30..8267cee128 100644
--- a/test/dotcom_web/views/event_view_test.exs
+++ b/test/dotcom_web/views/event_view_test.exs
@@ -234,7 +234,7 @@ defmodule DotcomWeb.EventViewTest do
     test "includes empty months earlier in the year if there is an event in an earlier year" do
       # Setup
       year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
-      month = Faker.random_between(1, 11)
+      month = Faker.random_between(2, 12)
 
       event_this_year =
         Factories.CMS.Partial.Teaser.build(

From 3b1b49c64b3324e31e0255ae4cba5750035855f7 Mon Sep 17 00:00:00 2001
From: Josh Larson <jlarson@mbta.com>
Date: Thu, 13 Aug 2026 15:07:06 -0400
Subject: [PATCH 4/5] tweak: Use `Stream.filter` instead of `Enum.filter`
 because why not

---
 lib/dotcom_web/views/event_view.ex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/dotcom_web/views/event_view.ex b/lib/dotcom_web/views/event_view.ex
index ff15a0092a..36770ceb49 100644
--- a/lib/dotcom_web/views/event_view.ex
+++ b/lib/dotcom_web/views/event_view.ex
@@ -38,7 +38,7 @@ defmodule DotcomWeb.EventView do
 
     by_month =
       events
-      |> Enum.filter(&(&1.date.year == year))
+      |> Stream.filter(&(&1.date.year == year))
       |> Enum.group_by(& &1.date.month)
 
     {earliest_month, latest_month} =

From 8382d6a6ce843e37e8f7281d0410965e681c6171 Mon Sep 17 00:00:00 2001
From: Josh Larson <jlarson@mbta.com>
Date: Thu, 13 Aug 2026 17:42:30 -0400
Subject: [PATCH 5/5] fix: Handle when events, or events for the given year,
 are empty

---
 lib/dotcom_web/views/event_view.ex        | 37 +++++++++++------
 test/dotcom_web/views/event_view_test.exs | 49 +++++++++++++++++++++++
 2 files changed, 73 insertions(+), 13 deletions(-)

diff --git a/lib/dotcom_web/views/event_view.ex b/lib/dotcom_web/views/event_view.ex
index 36770ceb49..3ced8543e0 100644
--- a/lib/dotcom_web/views/event_view.ex
+++ b/lib/dotcom_web/views/event_view.ex
@@ -33,22 +33,33 @@ defmodule DotcomWeb.EventView do
 
   @doc "Returns a list of event teasers, grouped/sorted by month"
   @spec grouped_by_month([Teaser.t()], number) :: [{number, [Teaser.t()]}]
+  def grouped_by_month([], _year), do: []
+
   def grouped_by_month(events, year) do
     {earliest_year, latest_year} = events |> Stream.map(& &1.date.year) |> Enum.min_max()
 
-    by_month =
-      events
-      |> Stream.filter(&(&1.date.year == year))
-      |> Enum.group_by(& &1.date.month)
-
-    {earliest_month, latest_month} =
-      by_month |> Stream.map(fn {month, _} -> month end) |> Enum.min_max()
-
-    latest_month = if latest_year == year, do: latest_month, else: 12
-    earliest_month = if earliest_year == year, do: earliest_month, else: 1
-
-    earliest_month..latest_month
-    |> Enum.map(&{&1, Map.get(by_month, &1, [])})
+    if earliest_year > year || latest_year < year do
+      []
+    else
+      by_month =
+        events
+        |> Stream.filter(&(&1.date.year == year))
+        |> Enum.group_by(& &1.date.month)
+
+      {earliest_month, latest_month} =
+        by_month
+        |> Enum.map(fn {month, _} -> month end)
+        |> case do
+          [] -> {1, 12}
+          months -> months |> Enum.min_max()
+        end
+
+      latest_month = if latest_year == year, do: latest_month, else: 12
+      earliest_month = if earliest_year == year, do: earliest_month, else: 1
+
+      earliest_month..latest_month
+      |> Enum.map(&{&1, Map.get(by_month, &1, [])})
+    end
   end
 
   @doc "Returns a list of event teasers, grouped/sorted by day"
diff --git a/test/dotcom_web/views/event_view_test.exs b/test/dotcom_web/views/event_view_test.exs
index 8267cee128..5f02ebbc10 100644
--- a/test/dotcom_web/views/event_view_test.exs
+++ b/test/dotcom_web/views/event_view_test.exs
@@ -256,6 +256,55 @@ defmodule DotcomWeb.EventViewTest do
                Enum.map(1..(month - 1), &{&1, []}) ++
                  [{month, [event_this_year]}]
     end
+
+    test "doesn't crash if the events list is empty" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+
+      # Exercise / Verify
+      assert grouped_by_month([], year) == []
+    end
+
+    test "returns [] if there are no events for the queried year, but there is in another year" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+      event_year = year + Faker.Util.pick([-1, 1])
+
+      event_in_other_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(event_year, Faker.random_between(1, 12), Faker.random_between(1, 28))
+        )
+
+      # Exercise
+      grouped_events = grouped_by_month([event_in_other_year], year)
+
+      # Verify
+      assert grouped_events == []
+    end
+
+    test "returns all months with no events if there are no events for the queried year, but there are on either end" do
+      # Setup
+      year = Dotcom.Utils.DateTime.now().year + Faker.random_between(-10, 10)
+
+      event_last_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year - 1, Faker.random_between(1, 12), Faker.random_between(1, 28))
+        )
+
+      event_next_year =
+        Factories.CMS.Partial.Teaser.build(
+          :event_teaser,
+          date: Date.new!(year + 1, Faker.random_between(1, 12), Faker.random_between(1, 28))
+        )
+
+      # Exercise
+      grouped_events = grouped_by_month([event_last_year, event_next_year], year)
+
+      # Verify
+      assert grouped_events == Enum.map(1..12, &{&1, []})
+    end
   end
 
   test "grouped_by_day/2 for a given month" do