GoBrand Calendar — Temporal-first calendar engine

Formatting

getWeekdays

Get localized weekday names in the correct order for your calendar header.

import { getWeekdays } from '@gobrand/calendar-core';

getWeekdays();
// ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]

getWeekdays(7);                    // Sunday start
// ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

getWeekdays(1, 'es-ES');           // Spanish
// ["lun", "mar", "mié", "jue", "vie", "sáb", "dom"]

getWeekdays(1, 'en-US', 'long');   // Full names
// ["Monday", "Tuesday", ...]

getWeekdays(7, 'en-US', 'narrow'); // Single letter
// ["S", "M", "T", "W", "T", "F", "S"]

Signature:

function getWeekdays(
  weekStartsOn?: 1 | 2 | 3 | 4 | 5 | 6 | 7, // Temporal: 1 (Monday) through 7 (Sunday)
  locale?: string | string[],                // Default: 'en-US'. Array for fallback locales
  format?: 'long' | 'short' | 'narrow'       // Default: 'short'
): string[];

getMonthName

Get localized month name from a PlainYearMonth.

import { getMonthName } from '@gobrand/calendar-core';
import { Temporal } from '@js-temporal/polyfill';

const month = Temporal.PlainYearMonth.from('2025-01');

getMonthName(month);          // "January"
getMonthName(month, 'es-ES'); // "enero"
getMonthName(month, 'ja-JP'); // "1月"

formatTime

Format a PlainTime for display.

import { formatTime } from '@gobrand/calendar-core';
import { Temporal } from '@js-temporal/polyfill';

const time = Temporal.PlainTime.from('14:30');

formatTime(time);          // "2:30 PM"
formatTime(time, 'en-GB'); // "14:30"

Timezone

getCurrentTimeZone

Get the system's IANA timezone.

import { getCurrentTimeZone } from '@gobrand/calendar-core';

getCurrentTimeZone(); // "America/New_York"

convertToTimezone

Convert a ZonedDateTime to a different timezone.

import { convertToTimezone } from '@gobrand/calendar-core';

const ny = Temporal.ZonedDateTime.from('2025-01-15T14:00:00-05:00[America/New_York]');
const tokyo = convertToTimezone(ny, 'Asia/Tokyo');
// 2025-01-16T04:00:00+09:00[Asia/Tokyo]

createZonedDateTime

Create a ZonedDateTime from date and time components.

import { createZonedDateTime } from '@gobrand/calendar-core';

const date = Temporal.PlainDate.from('2025-01-15');
const time = Temporal.PlainTime.from('14:30');
const zdt = createZonedDateTime(date, time, 'America/New_York');
// 2025-01-15T14:30:00-05:00[America/New_York]

Standalone navigation functions for use outside createCalendar:

import {
  nextMonth,
  previousMonth,
  nextWeek,
  previousWeek,
  nextDay,
  previousDay,
} from '@gobrand/calendar-core';

// Month navigation
const jan = Temporal.PlainYearMonth.from('2025-01');
nextMonth(jan);     // 2025-02
previousMonth(jan); // 2024-12

// Week navigation
const date = Temporal.PlainDate.from('2025-01-15');
nextWeek(date);     // 2025-01-22
previousWeek(date); // 2025-01-08

// Day navigation
nextDay(date);      // 2025-01-16
previousDay(date);  // 2025-01-14

Date Ranges

Get date ranges for the current period. Useful for data fetching.

import {
  getMonthRange,
  getWeekRange,
  getDayRange,
} from '@gobrand/calendar-core';

// Ranges are aligned to week boundaries
const monthRange = getMonthRange('America/New_York', 1); // Monday start
// { start: PlainDate, end: PlainDate }

const weekRange = getWeekRange('America/New_York', 1);
const dayRange = getDayRange('America/New_York');

Layout Helpers

For rendering events in time-based views:

getEventPosition

Calculate CSS position for an event block.

import { getEventPosition } from '@gobrand/calendar-core';

const position = getEventPosition(
  eventStart,   // ZonedDateTime
  eventEnd,     // ZonedDateTime
  8,            // Day starts at 8 AM
  60            // 60px per hour
);
// { top: 60, height: 90 }
// Event starts 1 hour after 8 AM (top: 60px)
// Event is 1.5 hours long (height: 90px)

getTimeSlotHeight

Calculate height for time slots.

import { getTimeSlotHeight } from '@gobrand/calendar-core';

getTimeSlotHeight(30, 60);  // 30px (half-hour slot at 60px/hour)
getTimeSlotHeight(15, 60);  // 15px (quarter-hour slot)

Utilities