# `LedgerUI.Components.Calendar`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/calendar.ex#L1)

A calendar for dates that matter (due dates, appointments, deadlines): a month grid or a week
grid of hours with colored event chips, month/week switching and keyboard navigation; plus
`due_calendar/1`, the agenda of due items by day.

    <.calendar id="due" view={@view} date={@date} events={@events} locale="pt_BR"
      on_navigate="calendar_navigate" on_view="calendar_view"
      on_select="calendar_select" on_event="calendar_event" />

The server owns what the calendar shows: `view` and `date` come from your assigns, and the
toolbar and the keyboard push `on_navigate` (`%{"id", "date", "view"}`), `on_view`,
`on_select` (`%{"id", "date"}`) and `on_event` (`%{"id", "event", "date"}`). Load the events of
a period with `calendar_range/3`.

An event is a map with `:date` and `:title`, and optionally `:id`, `:subtitle`, `:color`
(`neutral primary secondary info success warning error`), `:start` and `:end` (`"09:00"` or a
`Time`).

`variant="mini"` is the compact month in a card (round cells, a dot or a tint on the days
that have events). `view="day"` is the week grid with a single day, an addition to the README.

The roving focus and the arrow keys live in the `LedgerUI.Calendar` hook
(`priv/static/ledger_ui/hooks/calendar.js`), attached only when `on_select` is set.

# `calendar`

Renders the calendar.
## Attributes

* `id` (`:string`) (required)
* `view` (`:string`) - Defaults to `"month"`. Must be one of `"month"`, `"week"`, or `"day"`.
* `variant` (`:string`) - Defaults to `"full"`. Must be one of `"full"`, or `"mini"`.
* `range` (`:any`) - Defaults to `nil`.
* `marks` (`:string`) - Defaults to `"dot"`. Must be one of `"dot"`, or `"tint"`.
* `months_shown` (`:integer`) - Defaults to `1`.
* `date` (`:any`) - A date of the month (or week, day) shown; today by default. Defaults to `nil`.
* `month` (`:any`) - The same as `date`. Defaults to `nil`.
* `today` (`:any`) - Defaults to `nil`.
* `selected` (`:any`) - Defaults to `nil`.
* `events` (`:list`) - Defaults to `[]`.
* `legend` (`:list`) - Defaults to `[]`.
* `locale` (`:string`) - Defaults to `"en"`. Must be one of `"en"`, or `"pt_BR"`.
* `months` (`:list`) - Defaults to `nil`.
* `weekdays` (`:list`) - Defaults to `nil`.
* `labels` (`:map`) - Defaults to `%{}`.
* `week_start` (`:integer`) - Defaults to `0`.
* `show_weekends` (`:boolean`) - Defaults to `true`.
* `day_start` (`:integer`) - Defaults to `8`.
* `day_end` (`:integer`) - Defaults to `18`.
* `max_events` (`:integer`) - Defaults to `3`.
* `header` (`:boolean`) - Defaults to `true`.
* `outside_days` (`:boolean`) - Defaults to `false`.
* `day_id` (`:any`) - Defaults to `nil`.
* `interactive_marked_only` (`:boolean`) - Defaults to `false`.
* `card` (`:boolean`) - Defaults to `true`.
* `on_navigate` (`:string`) - Defaults to `nil`.
* `on_view` (`:string`) - Defaults to `nil`.
* `on_select` (`:string`) - Defaults to `nil`.
* `on_event` (`:string`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `event` - Replaces the content of an event chip or block; receives the event map.

# `calendar_range`

The first and last day shown for `view` around `date`, to load the events of the period.

    calendar_range("month", ~D[2026-10-15])  #=> {~D[2026-09-27], ~D[2026-10-31]}
    calendar_range("week", ~D[2026-10-15], week_start: 1)

# `due_calendar`

The agenda of due items, one row per item: the weekday and day, the title, a status badge
(overdue in `neg`, today highlighted) and the amount on the right.

    <.due_calendar items={@invoices} today={~D[2026-11-19]} locale="pt_BR" currency="R$ " />

## Attributes

* `items` (`:list`) - Maps with `:date`, `:title`, `:subtitle`, `:amount` (text or number) and optionally `:status` (`overdue`, `today`, `scheduled`) and `:status_label`. Defaults to `[]`.
* `today` (`:any`) - Defaults to `nil`.
* `locale` (`:string`) - Defaults to `"en"`. Must be one of `"en"`, or `"pt_BR"`.
* `currency` (`:string`) - Prefix of numeric amounts (`"R$ "`). Defaults to `""`.
* `amount_width` (`:integer`) - Defaults to `80`.
* `animated` (`:boolean`) - Staged demo (`mo-stg`): rows enter with a `--dl` delay, the overdue badge blinks, weekdays are lowercase and today's badge is `warn`. Defaults to `false`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
