QCalendar Documentation

QCalendar is a highly configurable calendar component for Vue that provides multiple view modes including day, week, monthly, scheduler, agenda, resource, and task views.

It is designed to be less opinionated than traditional calendar libraries; it does not manage events or reminders internally. Instead, it provides the UI infrastructure (via events, slots, and methods) for developers to implement their own event management logic.

Key characteristics:

• Views: Supports various layouts like Scheduler (with hierarchical trees), Resource, Agenda (with Planner modes), and Task (Gantt charts/timesheets).
• Date Logic: Uses Gregorian dates by default but supports non-Gregorian workflows (Hijri, Saka, Hebrew, Persian) via Timestamp calendar adapters.
• Customization: Highly extensible through Vue slots and CSS variables.
• Dependencies: Has no external dependencies like Moment.js or jQuery, relying only on Vue and @timestamp-js/core primitives.

QCalendar is composed of several specialized components designed for different calendar views and use cases. Understanding these components helps in selecting the right view for your application requirements:

• QCalendarDay: The base component for day-based views.
• QCalendarDay (week): A specialized version of the day view optimized for weekly layouts.
• QCalendarMonth: A component for full month grid views.
• QCalendarMonth (mini-mode): A compact version of the month view, typically used for date pickers or sidebars.
• QCalendarScheduler: A complex view designed for scheduling tasks or events across time and resources.
• QCalendarResource: Represents individual resources (like rooms or staff) within a scheduler view.
• QCalendarAgenda: A list-based view showing upcoming events or tasks.
• QCalendarTask: The visual representation of an individual event or task within a calendar view.

When working outside of a QCalendar slot (e.g., processing stored Gregorian data), use the epochDay bridge provided by @timestamp-js/core to convert between systems.

To convert Gregorian to Native:

1. Parse the Gregorian timestamp.
2. Get its epochDay.
3. Use createCalendarTimestampFromEpochDay with the target adapter.

To convert Native to Gregorian:

1. Get the epochDay from the native timestamp.
2. Use createCalendarTimestampFromEpochDay (passing the adapter) to get a timestamp that can be treated as Gregorian.

import {
  createCalendarTimestampFromEpochDay,
  getEpochDay,
  parseTimestamp,
  type Timestamp,
} from '@timestamp-js/core'
import { islamicCivilCalendar } from '@timestamp-js/calendar-islamic'

// Gregorian -> Hijri
function toHijri(timestamp: Timestamp) {
  return createCalendarTimestampFromEpochDay(getEpochDay(timestamp), islamicCivilCalendar)
}

// Hijri -> Gregorian
function toGregorian(hijriTimestamp: Timestamp) {
  return createCalendarTimestampFromEpochDay(getEpochDay(hijriTimestamp, islamicCivilCalendar))
}

const selectedGregorian = parseTimestamp('2024-03-25')!
const selectedHijri = toHijri(selectedGregorian)

QCalendar uses slots and events that share a common scope object.

Data Structures

• Slots: Provide { scope: { ... } }.
• Events: Provide { scope: { ... }, event: { ... } }.

Destructuring Scopes

You can destructure the scope directly in your template:

<!-- Destructure the whole scope -->
<q-calendar-day #day="{ scope }" />

<!-- Destructure specific properties like timestamp -->
<q-calendar-day #day="{ scope: { timestamp } }" />

Calendar Systems and Timestamps

When a calendar-system is set, the scope includes additional properties for non-Gregorian systems:

• timestamp: The native timestamp from the active adapter.
• calendarTimestamp: The timestamp specific to the calendar system.
• calendarIdentity: Contains gregorianDate (for external Gregorian systems) and epochDay (for neutral comparisons).

Range-style events (like change) also expose adapter-aware fields: calendarStart, calendarEnd, calendarDays, and calendarSystem.

<!-- Accessing advanced calendar identity properties in a slot -->
<q-calendar-day 
  #day="{ scope: { timestamp, calendarTimestamp, calendarIdentity } }"
/>

QCalendarMonth mini-mode is a compact version of the month calendar designed for dense layouts like sidebars, date pickers, or dashboards. It uses the same date-grid model as the full month calendar but with reduced visual weight.

Key features include:

• Responsive Breakpoints: Use mini-mode="auto" combined with a breakpoint prop (e.g., breakpoint="sm") to automatically switch to mini-mode when the viewport is small.
• Event Handling: The component fires a @mini-mode event (boolean) which can be used to adjust other properties dynamically, such as day-height.
• Visual Consistency: Mini-mode supports dark mode and responds to the same CSS variables and themes as the full month view.

<!-- Example of dynamic day-height based on mini-mode state -->
<QCalendarMonth
  mini-mode="auto"
  breakpoint="sm"
  @mini-mode="isMiniMode = $event"
  :day-height="isMiniMode ? 0 : 50"
/>