DevactionUI.Calendar (devaction_ui v0.2.3)

Copy Markdown View Source

A month or a week of days with their events, as an agenda of deliveries: each event is a coloured chip by kind (risk, warning, ok, info, neutral). It is a grid (role="grid", rows, column headers, cells) with one cell in the tab order and the arrows, Home, End and Page keys moving between days (DevactionUI.Calendar hook); pressing a day, or Enter on it, sends select_event with phx-value-date, and the previous and next buttons send prev_event and next_event.

The server owns the dates: month_weeks/3 and week_days/2 give the days to draw, so the grid is the same in the browser and in a test. The names of the months and of the days come from the caller (the library holds no language): title is written by the caller, and cell_label (a function of the day and its events) names each cell for screen readers.

The week view is the seven days of the week as cells with all their events as chips, or, when hours is given (a range such as 8..17, the last hour included), a grid of hours: a time column, a column per day (weekend={false} drops Saturday and Sunday, and the caller then gives five weekdays) and each event with a starts_at (and an ends_at, a Time) drawn at its time with its length, the ones that overlap side by side (DevactionUI.Calendar.Layout). An event without a starts_at is an all-day one and sits in a strip above the hours; detail is a second line under the label. Days outside the shown month are drawn dimmed and without events.

Event kinds are the tones of DevactionUI.Tone or the four categories :chart_1 to :chart_4, drawn in the --chart-* colours; the legend slot names the kinds in use under the grid.

Summary

Types

event()
kind()

Functions

calendar(assigns)
month_weeks(year, month, week_start \\ :sunday)

The weeks of a month, each a list of seven dates, from the week that holds the 1st to the one that holds the last day.

shift_month(date, delta)

The first day of the month before and after the month of date.

title(date, view, week_start \\ :sunday)

10/2026 for a month and 11/10 – 17/10/2026 for a week, the neutral form a caller replaces with its own words.

week_days(date, week_start \\ :sunday)

The seven dates of the week date is in.

Types

event()

@type event() :: %{
  :id => String.t(),
  :date => Date.t(),
  :label => String.t(),
  :kind => kind(),
  optional(:starts_at) => Time.t(),
  optional(:ends_at) => Time.t(),
  optional(:detail) => String.t()
}

kind()

@type kind() :: DevactionUI.Tone.t() | :chart_1 | :chart_2 | :chart_3 | :chart_4

Functions

calendar(assigns)

Attributes

  • id (:string) (required)
  • label (:string) (required) - the name of the grid, e.g. Deliveries in October 2026.
  • title (:string) (required) - the month or the week, as written for the person.
  • date (:any) (required) - a date of the month (or of the week) shown.
  • view (:atom) - Defaults to :month. Must be one of :month, or :week.
  • week_start (:atom) - Defaults to :sunday. Must be one of :sunday, or :monday.
  • today (:any) (required) - a Date: today in the workspace's time zone.
  • selected (:any) - Defaults to nil.
  • events (:list) - %{id, date, label, kind} each, and starts_at, ends_at and detail for the hours grid. Defaults to [].
  • hours (:any) - a range of hours such as 8..17: the week view becomes a grid of hours. Defaults to nil.
  • weekend (:boolean) - false drops Saturday and Sunday from the grid of hours. Defaults to true.
  • hour_label (:any) - a function of an hour (0 to 23) returning the text of the time column; HH:00 when nil. Defaults to nil.
  • weekdays (:list) (required) - seven short names, in the order of the week start.
  • more_label (:string) (required) - +%{count} more, with the count placed by the caller.
  • cell_label (:any) - a function of the day and its events returning the name of the cell for screen readers; dd/mm/yyyy: labels when nil. Defaults to nil.
  • prev_label (:string) (required)
  • next_label (:string) (required)
  • select_event (:string) (required)
  • prev_event (:string) (required)
  • next_event (:string) (required)
  • class (:any) - Defaults to nil.
  • target (:any) - a phx-target (a @myself) when used inside a LiveComponent. Defaults to nil.
  • Global attributes are accepted.

Slots

  • prev_icon
  • next_icon
  • actions - controls beside the arrows, such as a month and week switch.
  • legend - one entry per kind in use, drawn under the grid with its colour. Accepts attributes:
    • kind (:atom) (required)

month_weeks(year, month, week_start \\ :sunday)

@spec month_weeks(pos_integer(), 1..12, :sunday | :monday) :: [[Date.t()]]

The weeks of a month, each a list of seven dates, from the week that holds the 1st to the one that holds the last day.

shift_month(date, delta)

@spec shift_month(Date.t(), -1 | 1) :: Date.t()

The first day of the month before and after the month of date.

title(date, view, week_start \\ :sunday)

@spec title(Date.t(), :month | :week, :sunday | :monday) :: String.t()

10/2026 for a month and 11/10 – 17/10/2026 for a week, the neutral form a caller replaces with its own words.

week_days(date, week_start \\ :sunday)

@spec week_days(Date.t(), :sunday | :monday) :: [Date.t()]

The seven dates of the week date is in.