PhoenixLiveCalendar.Utils.DateHelpers (PhoenixLiveCalendar v0.1.0)

Date math utilities for calendar grid generation.

Handles month grid computation, week boundaries, day ranges, and date arithmetic needed by the calendar view components.

All functions are defensively coded — invalid inputs return safe defaults rather than crashing.

Week start day

All functions accept a week_start parameter (1-7, ISO day numbering):

1 = Monday (default, ISO standard)
6 = Saturday
7 = Sunday

This matches PhoenixKit's week_start_day setting.

Summary

Functions

group_by_weeks(dates)

Groups a flat list of dates into weeks (lists of 7 dates).

group_events_by_date(events, dates)

Groups events by date for efficient lookup.

in_month?(date, month_date)

Returns whether the given date is in the specified month.

month_grid(date, opts \\ [])

Returns a flat list of dates for a month grid view.

n_day_dates(start_date, n)

Returns a list of dates for an N-day view starting from the given date.

shift(date, arg2, arg3)

Shifts the anchor date by one step for the given view.

today?(date)

Returns whether the given date is today.

visible_range(view, date, opts \\ [])

Returns the visible date range for a given view and anchor date.

week_dates(date, opts \\ [])

Returns a list of dates for a week containing the given date.

week_end_date(date, week_start \\ 1)

Returns the last day of the week containing the given date.

week_number(date)

Returns the ISO week number for the given date.

week_start_date(date, week_start \\ 1)

Returns the first day of the week containing the given date.

weekend?(date)

Returns whether the given date is a weekend (Saturday or Sunday).

year_months(year)

Returns a list of 12 {year, month} tuples for the year view.

Functions

group_by_weeks(dates)

@spec group_by_weeks([Date.t()]) :: [[Date.t()]]

Groups a flat list of dates into weeks (lists of 7 dates).

group_events_by_date(events, dates)

@spec group_events_by_date([PhoenixLiveCalendar.Event.t()], [Date.t()]) :: %{
  required(Date.t()) => [PhoenixLiveCalendar.Event.t()]
}

Groups events by date for efficient lookup.

Returns a map of %{Date.t() => [Event.t()]}.

in_month?(date, month_date)

@spec in_month?(Date.t(), Date.t()) :: boolean()

Returns whether the given date is in the specified month.

month_grid(date, opts \\ [])

@spec month_grid(
  Date.t(),
  keyword()
) :: [Date.t()]

Returns a flat list of dates for a month grid view.

The grid always contains complete weeks (rows of 7 days). It starts from the first day of the week containing the month's first day, and extends to fill either 5 or 6 complete weeks.

Options

week_start — First day of week (1-7, default: 1 = Monday)
fixed_weeks — Always show 6 weeks (default: true). When false, shows 5 weeks if the month fits.

Examples

iex> dates = DateHelpers.month_grid(~D[2026-04-01])
iex> length(dates)
42
iex> hd(dates)
~D[2026-03-30]

n_day_dates(start_date, n)

@spec n_day_dates(Date.t(), pos_integer()) :: [Date.t()]

Returns a list of dates for an N-day view starting from the given date.

Examples

iex> DateHelpers.n_day_dates(~D[2026-04-01], 4)
[~D[2026-04-01], ~D[2026-04-02], ~D[2026-04-03], ~D[2026-04-04]]

shift(date, arg2, arg3)

@spec shift(Date.t(), atom(), :prev | :next) :: Date.t()

Shifts the anchor date by one step for the given view.

Examples

iex> DateHelpers.shift(~D[2026-04-15], :month, :next)
~D[2026-05-15]

iex> DateHelpers.shift(~D[2026-04-15], :week, :prev)
~D[2026-04-08]

today?(date)

@spec today?(Date.t()) :: boolean()

Returns whether the given date is today.

visible_range(view, date, opts \\ [])

@spec visible_range(atom(), Date.t(), keyword()) :: {Date.t(), Date.t()}

Returns the visible date range for a given view and anchor date.

Returns {start_date, end_date} (inclusive start, exclusive end).

week_dates(date, opts \\ [])

@spec week_dates(
  Date.t(),
  keyword()
) :: [Date.t()]

Returns a list of dates for a week containing the given date.

Examples

iex> DateHelpers.week_dates(~D[2026-04-01])
[~D[2026-03-30], ~D[2026-03-31], ~D[2026-04-01], ~D[2026-04-02],
 ~D[2026-04-03], ~D[2026-04-04], ~D[2026-04-05]]

week_end_date(date, week_start \\ 1)

@spec week_end_date(Date.t(), integer()) :: Date.t()

Returns the last day of the week containing the given date.

week_number(date)

@spec week_number(Date.t()) :: {integer(), integer()}

Returns the ISO week number for the given date.

week_start_date(date, week_start \\ 1)

@spec week_start_date(Date.t(), integer()) :: Date.t()

Returns the first day of the week containing the given date.

weekend?(date)

@spec weekend?(Date.t()) :: boolean()

Returns whether the given date is a weekend (Saturday or Sunday).

year_months(year)

@spec year_months(integer()) :: [{integer(), integer()}]

Returns a list of 12 {year, month} tuples for the year view.

Examples

iex> DateHelpers.year_months(2026)
[{2026, 1}, {2026, 2}, ..., {2026, 12}]