useCalendar
Calendar
stable
Stateless calendar engine powering <OrigamCalendar>. Computes the visible date range for month/week/day/agenda views, expands recurring events (RRULE), and provides pure grid-builder functions for month, week, and day layouts. Navigation mutates the current date via optional callbacks so the composable can be driven from props, a store, or a local ref without re-instantiation.
API
Signature
Full TypeScript signature sourced from the composable file.
Consumed interfaces
IUseCalendarOptions
IEvent
API
Parameters
Input parameters accepted by this composable.
- optionsrequiredIUseCalendarOptions
- Configuration thunks. All fields are getter functions so the composable reacts to reactive sources without re-instantiation. Includes events, view, currentDate, firstDayOfWeek, slotDuration, dayStartHour, dayEndHour, and optional minDate/maxDate/locale.
- setView(view: TCalendarView) => void
- Optional callback invoked by the returned setView proxy. Bind to a v-model:view setter to keep the parent state in sync when the calendar switches views.
- setCurrentDate(date: Date) => void
- Optional callback invoked by navigate(). Bind to a v-model:currentDate setter. If omitted, navigation calls have no effect on the parent state.
API
Return values
Properties and methods exposed by the composable return object.
- visibleDateRange
- Start and end dates of the currently visible window. Month/agenda views span a full 6-week grid; week view spans Sun–Sat (or Mon–Sun); day view spans a single calendar day.
- expandedEvents
- Events filtered and expanded via RRULE to the visible date range, sorted by start date ascending. Recurring events appear as individual occurrences.
- navigate
- Move the calendar forward ("next"), backward ("prev"), or to today ("today"). Clamps to minDate/maxDate when provided and calls setCurrentDate with the new date.
- buildMonthGrid
- Returns a 6×7 matrix of midnight-local Date objects for the month view. Each inner array is one week row.
- buildWeekGrid
- Returns 7 columns (one per day) each containing an array of time-slot descriptors for the week timeline view.
- buildDayGrid
- Returns the time-slot array for a single day, from dayStartHour to dayEndHour at slotDuration-minute intervals.
- buildAgenda
- Groups events by day for the agenda view. Returns an array of { date, events } objects, one per day that has at least one event in the range.
- eventsOnDay
- Filter expanded events to those that intersect a given day. Used by the month grid chip list and the day/week positioning layer.
- positionEvent
- Compute top and height pixel values for an event on the day/week timeline. pxPerMin is the CSS-driven slot height divided by slotDuration so the layout stays responsive without JS ResizeObservers.
- helpers
- Re-exported date utility functions (isSameDay, isSameMonth, startOfDay, startOfMonth, endOfMonth, addDays, addMonths, addWeeks, diffMinutes, toDate). Exposed so consumers can extend calendar UIs without a separate import.
Usage
Examples
Ready-to-paste usage snippets.
Month grid driven from props