Cardbox.Koyomi (Cardbox v0.1.0)

Copy Markdown View Source

A collection as a Koyomi calendar: each record on the day of the view's date field, a mark for each, and the records of the day a person picks.

<Cardbox.Koyomi.calendar id="due" view={@view} on_change="day" months={2} />

def handle_event("koyomi:days", %{"id" => "due"} = params, socket),
  do: Cardbox.Koyomi.handle_days(socket, params, MyApp.Cardbox, socket.assigns.collection, socket.assigns.view)

def handle_event("day", %{"value" => day}, socket) do
  {:ok, records} = Cardbox.Koyomi.on_day(MyApp.Cardbox, socket.assigns.collection, socket.assigns.view, day)
  {:noreply, assign(socket, day_records: records)}
end

The view is a saved Cardbox.View of type calendar: its date_field names the date field (a day, or a moment), and its query which records. The calendar asks for the days it shows a month or a few at a time, and the database reads only the records of those days.

A day's marks are a dot for each record (four at most), toned by the group of the record's status when the collection has one: to do muted, doing in the accent, done in green. Its title, read by screen readers and shown on hover, has the records' titles.

When records change (Cardbox.Event), Koyomi.Live.refresh_days/2 asks the calendar for its days again (Koyomi 0.2.1 and later, which Cardbox requires: before it, a refresh emptied the calendar).

Summary

Functions

A calendar of a view's records, on the days of its date field.

The content of the days of a range: for each day with records, their marks and their titles, as Koyomi.Live.handle_days/4 takes them.

Answers the calendar's koyomi:days event with the days of the view's records (Koyomi.Live.handle_days/4). opts are those of a query (:me, :time_zone, :now).

The records of a view on a day (a Date or "YYYY-MM-DD"), in the view's order.

Functions

calendar(assigns)

A calendar of a view's records, on the days of its date field.

Attributes

  • id (:string) (required)
  • view (Cardbox.View) (required) - a view of type calendar.
  • on_change (:string) - the event of a day picked: %{"value" => "2026-10-25"}. Defaults to nil.
  • months (:integer) - Defaults to 1.
  • label (:string) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["value", "locale", "first_day", "week_numbers", "holidays", "class"].

days(mod, collection, view, range, opts \\ [])

@spec days(
  module(),
  Cardbox.Collection.t(),
  Cardbox.View.t(),
  Date.Range.t(),
  keyword()
) :: %{
  required(Date.t()) => keyword()
}

The content of the days of a range: for each day with records, their marks and their titles, as Koyomi.Live.handle_days/4 takes them.

handle_days(socket, params, mod, collection, view, opts \\ [])

Answers the calendar's koyomi:days event with the days of the view's records (Koyomi.Live.handle_days/4). opts are those of a query (:me, :time_zone, :now).

on_day(mod, collection, view, day, opts \\ [])

@spec on_day(
  module(),
  Cardbox.Collection.t(),
  Cardbox.View.t(),
  Date.t() | String.t(),
  keyword()
) ::
  {:ok, [Cardbox.Record.t()]} | {:error, Cardbox.Error.t()}

The records of a view on a day (a Date or "YYYY-MM-DD"), in the view's order.