Calendarium

While the CalendarStore manages the data, the EphemeralStore manages the user's current view and interface preferences. You can retrieve an ephemeral store using getEphemeralStore(id: string) from the main store.

Key UI Controls:

• View Mode: Control the current view using viewState (values: ViewState.Year, ViewState.Month, ViewState.Week, ViewState.Day).
• Navigation: Use goToNext(), goToPrevious(), goToToday(), or displayDate(date: CalDate) to move the UI focus.
• Display Toggles: Control visibility of UI elements via displayMoons, displayDayNumber, displayWeeks, hideEra, displayAbsoluteYear, displaySeasonColors, displayWeather, and interpolateColors.
• Location: Manage the currently selected location via the location store.

The CalendarAPI provides methods to interact with the calendar's seasonal system:

• getSeasons(): Returns a list of all defined Season objects on the calendar.
• getSeasonForDate(date: CalDate): Returns the Season applicable to the provided date, or undefined if no season is found.

const seasons = api.getSeasons();
const currentSeason = api.getSeasonForDate(api.getCurrentDate());

To interact with the state of a specific calendar (e.g., to change the current date or manage file events), use getStore or getStoreByCalendar.

• getStore(calendarId: string): Finds a calendar by its ID and returns its associated CalendarStore.
• getStoreByCalendar(calendar: Calendar): Returns the CalendarStore for a given Calendar object.

Each CalendarStore manages the reactive state for that specific calendar instance.

// Example: Getting a store by calendar ID
const store = plugin.getStore('my-calendar-id');
if (store) {
  // Perform store operations
}

The EventStore provides utility methods to determine the nature of an event, which is important for deciding if an event can be deleted manually:

• isFileEvent(eventId: string): Returns true if the event was added via insertEventsFromFile.
• isRemovable(eventId: string): Returns true if the event is not a file event. This is a convenience method to check if an event can be safely removed without affecting file-based synchronization logic.

if (eventStore.isRemovable(someEventId)) {
    eventStore.removeEvents(someEvent);
}

The CalendarStore provides methods to manipulate the underlying calendar data and navigate time. Key capabilities include:

• Navigation: Use setCurrentDate(date: CalDate) to change the calendar's reference date, or getDaysBeforeDate(date: CalDate) to calculate offsets.
• Data Access: Access eventStore for event management, staticStore for immutable calendar rules (months, moons, eras), and locationStore for location data.
• Event Retrieval: Use getEventsForDate(date: CalDate) to get a Readable store of all events (including era-based events) occurring on a specific date.
• Category Management: Use addCategory(category: CalEventCategory) to add new event categories or hasCategory(category: string) to check for existence.

You can advance or decrement the current date of a calendar using the changeDay method. This method requires the Calendar object, its corresponding CalendarStore, and a change function (like incrementDay or decrementDay).

import { incrementDay } from "./stores/calendar.store";

// Advance the day for a specific calendar
plugin.changeDay(calendar, store, incrementDay);

The src/schemas/index.ts file serves as the central export point for Calendarium's data structures. It aggregates and re-exports all primary schemas related to:

• Calendar: Definitions for calendar structures and logic.
• Events: Definitions for event data and properties.
• Settings: Configuration and user preference schemas.

The API class is the primary entry point for interacting with the Calendarium plugin. It allows you to manage settings callbacks, retrieve available calendar names, and obtain a CalendarAPI instance for specific calendars to access their data and events.

import { API } from "src/api/api";

// Assuming 'plugin' is an instance of Calendarium provided by the environment
const api = new API(plugin);