@spec bookable_slots(
  Date.t(),
  PhoenixLiveCalendar.BookingConfig.t(),
  [PhoenixLiveCalendar.Availability.t()],
  [PhoenixLiveCalendar.Event.t()]
) :: [{Time.t(), Time.t(), :available | :unavailable | :booked}]

Generates bookable time slots for a specific date given a booking configuration.

Takes existing events into account for overlap detection. Returns a list of {start_time, end_time, status} tuples where status is :available, :unavailable, or :booked.

Examples

config = %BookingConfig{duration: 30, slot_interval: 30, buffer_after: 5}
availability = [%Availability{days_of_week: [1,2,3,4,5], start_time: ~T[09:00:00], end_time: ~T[17:00:00]}]
existing_events = [...]

TimeSlots.bookable_slots(~D[2026-04-01], config, availability, existing_events)
# => [{~T[09:00:00], ~T[09:30:00], :available},
#     {~T[09:30:00], ~T[10:00:00], :booked},
#     {~T[10:00:00], ~T[10:30:00], :available}, ...]

@spec duration_to_percentage(Time.t(), Time.t(), keyword()) :: float()

Returns the height (as a percentage) for an event duration in the time grid.

@spec time_grid_slots(keyword()) :: [Time.t()]

Generates time slot boundaries for a time grid view.

Returns a list of Time values representing the start of each slot.

Options

• min_time — Earliest time to show (default: ~T[00:00:00])
• max_time — Latest time to show (default: ~T[24:00:00], represented as ~T[23:59:59])
• slot_duration — Duration of each slot in minutes (default: 30)

Examples

iex> TimeSlots.time_grid_slots(min_time: ~T[09:00:00], max_time: ~T[17:00:00], slot_duration: 60)
[~T[09:00:00], ~T[10:00:00], ~T[11:00:00], ~T[12:00:00],
 ~T[13:00:00], ~T[14:00:00], ~T[15:00:00], ~T[16:00:00]]

@spec time_to_percentage(
  Time.t(),
  keyword()
) :: float()

Returns the vertical position (as a percentage) of a time within the day grid.

Useful for absolutely positioning events in a time grid view.

Options

• min_time — Earliest visible time (default: ~T[00:00:00])
• max_time — Latest visible time (default: ~T[24:00:00])

Examples

iex> TimeSlots.time_to_percentage(~T[12:00:00])
50.0

iex> TimeSlots.time_to_percentage(~T[12:00:00], min_time: ~T[08:00:00], max_time: ~T[20:00:00])
33.33

@spec to_time(DateTime.t() | NaiveDateTime.t() | Time.t()) :: Time.t()

Extracts the time component from a DateTime or NaiveDateTime. Returns the value unchanged if already a Time.