Data

Calendars

Calendars are groups that organize items. Each calendar has its own color and visibility toggle — hiding a calendar hides all its items.

Calendar Properties

Adding & Removing Calendars

import { Calendar } from '@timelinekit/core';

// Add a calendar
const cal = Calendar.fromAny({
  id: 'c3', name: 'Meetings', color: 2, isVisible: true
});
calendar.data.addCalendar(cal);

// Access calendars
const byId = calendar.data.getCalendarById('c3');
console.log(calendar.data.calendarsLength);

// Toggle visibility
cal.isVisible = false;

// Listen for visibility changes
cal.visibilityChanged$.subscribe(args => {
  console.log(args.calendar.name, args.calendar.isVisible ? 'shown' : 'hidden');
});

// Remove
calendar.data.removeCalendar(cal);

Calendar Items

Calendar items are the events displayed on the calendar. Each item belongs to a calendar and has a type that determines its appearance and behavior.

Item Properties

Adding & Removing Items

import { Meeting } from '@timelinekit/core';

// Add an item
const item = Meeting.fromAny({
  id: 'i10',
  calendarId: 'c1',
  title: 'Team Standup',
  startTime: '2027-01-06T09:00:00',
  endTime: '2027-01-06T09:30:00',
});
calendar.data.addItem(item);

// Access items
const byId = calendar.data.getItemById('i10');
console.log(calendar.data.itemsLength);

// Change properties
item.title = 'Daily Standup';
item.startTime = new Date('2027-01-06T09:30:00');

// Listen for changes
item.changed$.subscribe(() => {
  console.log('Item updated:', item.title);
});

// Remove
calendar.data.removeItem(item);

Item Types

Each item has a type that affects its visual presentation and available properties.

Meeting Response Status

Items of type meeting support a response status that affects visual rendering (e.g. declined meetings appear faded):

const meeting = calendar.data.getItemById('i1');
meeting.responseStatus = 'accepted';   // fully opaque
meeting.responseStatus = 'tentative';  // hatched pattern
meeting.responseStatus = 'declined';   // faded (declinedOpacity from theme)

Recurrence Rules

Recurrence rules follow the RFC 5545 (iCalendar) RRULE specification. A recurring item generates multiple entries — one for each occurrence within the visible range.

import { RecurrenceRule } from '@timelinekit/core';

// Daily standup, every weekday
const item = calendar.data.addItem({
  id: 'standup',
  calendarId: 'c1',
  title: 'Daily Standup',
  startTime: '2027-01-06T09:00:00',
  endTime: '2027-01-06T09:15:00',
  type: 'meeting',
});
item.recurrenceRule = new RecurrenceRule({
  frequency: 'weekly',
  byDay: [{ day: 'mo' }, { day: 'tu' }, { day: 'we' }, { day: 'th' }, { day: 'fr' }],
});

// Monthly on the last Friday
item.recurrenceRule = new RecurrenceRule({
  frequency: 'monthly',
  byDay: [{ day: 'fr', ordinal: -1 }],
});

// Every 2 weeks on Monday and Wednesday, 10 occurrences
item.recurrenceRule = new RecurrenceRule({
  frequency: 'weekly',
  interval: 2,
  count: 10,
  byDay: [{ day: 'mo' }, { day: 'we' }],
});

// Parse from RRULE string
item.recurrenceRule = RecurrenceRule.fromString('FREQ=DAILY;INTERVAL=1;COUNT=30');

// Serialize to RRULE string
const rrule = item.recurrenceRule.toString();
// → 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

Recurrence Exceptions

Exceptions allow modifying or cancelling individual occurrences of a recurring item without affecting the rest of the series.

const item = calendar.data.getItemById('standup');

// Cancel a single occurrence (e.g. holiday)
item.cancelOccurrence(new Date('2027-01-20T09:00:00'));

// Modify a single occurrence (different time)
item.setException({
  originalStartTime: new Date('2027-01-21T09:00:00'),
  isCancelled: false,
  overrides: {
    startTime: new Date('2027-01-21T10:00:00'),
    endTime: new Date('2027-01-21T10:15:00'),
    title: 'Late Standup',
  },
});

// Remove an exception
item.removeException(new Date('2027-01-21T09:00:00'));

// Clear all exceptions
item.clearExceptions();

Entries vs Items

A CalendarItem is the master record. A CalendarEntry is a rendered instance — for non-recurring items there is one entry per item; for recurring items there is one entry per visible occurrence. Entries resolve exception overrides automatically.

Custom Properties

Add arbitrary fields to items for application-specific data.

const item = calendar.data.getItemById('i1');

// Add custom properties
item.addProperty(new CustomProperty('priority', 'high'));
item.addProperty(new CustomProperty('meetingUrl', 'https://meet.example.com/abc'));

// Read & write
item.getPropertyValue('priority');       // 'high'
item.setPropertyValue('priority', 'low');

// Remove
const prop = item.getPropertyByName('priority');
item.removeProperty(prop);