Timezone Support
IANA formatting, legacy conversion conventions, UI limits, and recurrence verification.
Core uses the runtime's Intl.DateTimeFormat timezone data. A JavaScript Date represents an instant; formatting that instant in another zone is different from reinterpreting a Date's wall-clock fields.
Format an instant safely
const instant = new Date('2026-10-05T13:00:00Z');
const text = new Intl.DateTimeFormat('en-US', {
timeZone: 'America/New_York', dateStyle: 'medium', timeStyle: 'short',
}).format(instant);Core exposes TimezoneManager publicly:
import { TimezoneManager } from '@forcecalendar/core';
const tz = TimezoneManager.getInstance();
const offset = tz.getTimezoneOffset(new Date(), 'America/New_York');Calendar timezone API
| Method | Purpose |
|---|---|
setTimezone(timezone) / getTimezone() | Configure/read Core's calendar zone |
convertTimezone(date, from, to) | Legacy wall-clock conversion between zones |
toCalendarTimezone(date, from?) | Convert to the configured calendar zone |
fromCalendarTimezone(date, to?) | Convert from the configured calendar zone |
formatInTimezone(date, timezone?, options?) | Format through the timezone manager |
getTimezones() | Common { value, label, offset } descriptors |
TimezoneManager also exposes validation, offsets, DST/transition helpers and caches. See its API reference. TimezoneDatabase is an internal supporting class, not a package root export.
Event fields and conversions
timeZone and endTimeZone retain event zone metadata; the latter can describe a different end zone. Core 2.5.6 preserves endTimeZone in clone() and toObject(). Invalid Event timezone identifiers throw.
Legacy Event and TimezoneManager.toUTC/fromUTC APIs use wall-clock carrier conventions. In particular, do not assume startUTC/endUTC are a second universally host-independent encoding of the supplied timestamps, or apply those conversions twice to an already-normalized instant. Validate the relevant API against your input contract.
Interface grid and visible range
The current Interface grid, editor display and getVisibleRange() use the browser's local timezone. The timezone attribute configures Core but does not change the grid into an arbitrary-zone view. getVisibleRange().end is inclusive.
All-day values are civil dates, not instants: local start-of-day through the inclusive last day's 23:59:59.999. Use calendar-day arithmetic across DST transitions. Providers/ICS with exclusive ends and Salesforce's inclusive UTC-date representation need explicit adapters. See date migration.
Recurrence and DST
Core 2.5.7 corrects RecurrenceEngineV2 calendar stepping in the named recurrence zone across host timezones. Use generated start/end for that contract. Legacy startUTC/endUTC metadata, conversion helpers, moved-instance bounds and ancient-date limits remain. See the V2 timezone contract. This is a scoped recurrence correction, not a redesign of every conversion API.
Test the host timezone, event timezone, clock gaps/overlaps, exception dates and query bounds relevant to the deployment. Host Intl data may differ between runtime versions; keep runtimes maintained.