@super-calendar/core 2.0.0

package/src/utils/eventDisplay.ts

@@ -0,0 +1,180 @@
+import { format } from "date-fns";
+import type { CalendarMode } from "../types";
+
+/**
+ * Minimum event-box height (px) before the built-in renderer shows the time line
+ * on a narrow multi-column timed grid. Tied to the default theme's font sizes.
+ */
+export const MIN_BOX_HEIGHT_FOR_TIME = 56;
+
+/** Hard-clip an overflowing title by default; opt into a trailing ellipsis. */
+export function titleEllipsizeMode(ellipsizeTitle: boolean): "clip" | "tail" {
+  return ellipsizeTitle ? "tail" : "clip";
+}
+
+/**
+ * Screen-reader label for an event: its title followed by "all day" or its time
+ * range (which the grid otherwise only conveys visually). Empty title is dropped.
+ */
+export function eventAccessibilityLabel(args: {
+  title?: string;
+  isAllDay: boolean;
+  start: Date;
+  end: Date;
+  ampm: boolean;
+  /** Spoken text for an all-day event. Default "all day". */
+  allDayLabel?: string;
+}): string {
+  const timeFormat = args.ampm ? "h:mm a" : "HH:mm";
+  const time = args.isAllDay
+    ? (args.allDayLabel ?? "all day")
+    : `${format(args.start, timeFormat)} to ${format(args.end, timeFormat)}`;
+  return [args.title, time].filter(Boolean).join(", ");
+}
+
+/**
+ * Month cells and the all-day lane show a single clipped line; timed-grid titles
+ * (`undefined`) wrap to fill the box.
+ */
+export function titleNumberOfLines(mode: CalendarMode, isAllDay: boolean): number | undefined {
+  return mode === "month" || isAllDay ? 1 : undefined;
+}
+
+/**
+ * The secondary line under the title in the built-in renderer, or `null` when
+ * none should show. Timed events get their `start - end` range. An all-day event
+ * gets the literal "All day" in the schedule (which has no all-day lane to
+ * signal it positionally) and nothing on the day/week grid (the lane already
+ * does). Month cells and `showTime={false}` always return `null`.
+ */
+export function eventTimeLabel(args: {
+  mode: CalendarMode;
+  isAllDay: boolean;
+  start: Date;
+  end: Date;
+  ampm: boolean;
+  showTime: boolean;
+  /** Text for an all-day event in the schedule. Default "All day". */
+  allDayLabel?: string;
+}): string | null {
+  if (!args.showTime || args.mode === "month") return null;
+  if (args.isAllDay) return args.mode === "schedule" ? (args.allDayLabel ?? "All day") : null;
+  const timeFormat = args.ampm ? "h:mm a" : "HH:mm";
+  return `${format(args.start, timeFormat)} - ${format(args.end, timeFormat)}`;
+}
+
+/**
+ * The default hour-axis label shared by both renderers' time grids, so the gutter
+ * reads the same on each: 24-hour "HH:00" (e.g. "08:00"), or a compact 12-hour
+ * "h AM/PM" (e.g. "8 AM") when `ampm` is set. Exported so a custom hour renderer
+ * can reuse the same formatting.
+ */
+export function formatHour(hour: number, opts?: { ampm?: boolean }): string {
+  if (opts?.ampm) {
+    const period = hour < 12 ? "AM" : "PM";
+    const hour12 = hour % 12 === 0 ? 12 : hour % 12;
+    return `${hour12} ${period}`;
+  }
+  return `${String(hour).padStart(2, "0")}:00`;
+}
+
+/**
+ * Whether the time line fits in the box. The wide `day` column and contexts with
+ * no live box height (e.g. schedule, where `boxHeightPx` is undefined) always
+ * show it; narrow multi-column modes only once the box is at least
+ * {@link MIN_BOX_HEIGHT_FOR_TIME} tall. Runs on the UI thread inside the event
+ * renderer's animated style.
+ */
+export function isTimeVisibleAtHeight(
+  boxHeightPx: number | undefined,
+  mode: CalendarMode,
+): boolean {
+  "worklet";
+  if (boxHeightPx == null || mode === "day") return true;
+  return boxHeightPx >= MIN_BOX_HEIGHT_FOR_TIME;
+}
+
+/** Layout for the built-in timed-grid event chip at a given box height. */
+export type EventChipLayout = {
+  /**
+   * Max whole title lines that fit in the box. `0` means "no clamp" (the box
+   * height is unknown, e.g. the schedule), so the title may wrap freely.
+   */
+  titleMaxLines: number;
+  /** Whether the secondary time line still has room below the title. */
+  showTime: boolean;
+};
+
+/**
+ * Lay out the built-in timed-grid event chip for a box of `boxHeightPx`: how
+ * many whole title lines fit, and whether the time line still has room below
+ * them. The title is primary, so the title fills the box in whole lines (never a
+ * half-cropped line) and the time only shows once a full line is left over. Pass
+ * `titleLineHeightPx`/`timeLineHeightPx` matching the rendered line heights so
+ * the clamp lands on a line boundary.
+ *
+ * Worklet-safe, so the native renderer can drive the title's max-height on the UI
+ * thread as the grid zooms; the dom renderer calls it with its static box height.
+ * A `boxHeightPx` of `undefined` (the schedule has no live box height) returns
+ * `titleMaxLines: 0` (no clamp) with the unconditional time visibility.
+ */
+export function eventChipLayout(args: {
+  boxHeightPx: number | undefined;
+  mode: CalendarMode;
+  hasTime: boolean;
+  titleLineHeightPx: number;
+  timeLineHeightPx: number;
+  paddingYPx: number;
+}): EventChipLayout {
+  "worklet";
+  const wantTime = args.hasTime && isTimeVisibleAtHeight(args.boxHeightPx, args.mode);
+  if (args.boxHeightPx == null || args.titleLineHeightPx <= 0) {
+    return { titleMaxLines: 0, showTime: wantTime };
+  }
+  const inner = args.boxHeightPx - args.paddingYPx * 2;
+  // Reserve the time line first, then give the title every whole line that fits
+  // in what remains (always at least one line).
+  const titleMaxLines = Math.max(
+    1,
+    Math.floor((inner - (wantTime ? args.timeLineHeightPx : 0)) / args.titleLineHeightPx),
+  );
+  // Only keep the time if a full line is still free under the clamped title, so a
+  // short box drops the time rather than slicing it in half.
+  const showTime =
+    wantTime && inner - titleMaxLines * args.titleLineHeightPx >= args.timeLineHeightPx;
+  return { titleMaxLines, showTime };
+}
+
+/** How many month-cell chips fit in the available height. */
+export type MonthEventCapacity = {
+  /** Count when every event fits, with no overflow label. */
+  full: number;
+  /** Count that leaves room for the "+N more" label. */
+  withMore: number;
+};
+
+/**
+ * Derive how many event chips fit in a month cell from the measured space.
+ * `chipRowHeightPx` is one chip plus its gap; `moreRowHeightPx` is the overflow
+ * label plus its gap. Both counts are clamped to >= 0.
+ */
+export function monthEventCapacity(
+  availableHeightPx: number,
+  chipRowHeightPx: number,
+  moreRowHeightPx: number,
+): MonthEventCapacity {
+  if (chipRowHeightPx <= 0) return { full: 0, withMore: 0 };
+  return {
+    full: Math.max(0, Math.floor(availableHeightPx / chipRowHeightPx)),
+    withMore: Math.max(0, Math.floor((availableHeightPx - moreRowHeightPx) / chipRowHeightPx)),
+  };
+}
+
+/**
+ * Chips to show for a day: all of them when they fit, otherwise `withMore` (at
+ * least one) so the rest collapse into a "+N more" label.
+ */
+export function monthVisibleCount(total: number, capacity: MonthEventCapacity): number {
+  if (total <= capacity.full) return total;
+  return Math.max(1, capacity.withMore);
+}

package/src/utils/layout.ts

@@ -0,0 +1,193 @@
+import { addDays, differenceInMinutes, max as maxDate, min as minDate, startOfDay } from "date-fns";
+import type { BusinessHours, CalendarEvent } from "../types";
+
+const MINUTES_PER_HOUR = 60;
+// Minimum duration (in hours) a positioned event is given, so a zero/negative
+// span still occupies a sliver rather than collapsing to nothing.
+const MIN_DURATION_HOURS = 0.25;
+
+export type PositionedEvent<T> = {
+  event: CalendarEvent<T>;
+  /** Hours from midnight to the event's segment start on this day (fractional). */
+  startHours: number;
+  /** Segment duration in hours on this day (clamped to a small minimum). */
+  durationHours: number;
+  /** Zero-based column index within its overlap cluster. */
+  column: number;
+  /** Total columns in this event's overlap cluster. */
+  columns: number;
+  /** True when the segment is clipped because the event continues before/after this day. */
+  continuesBefore: boolean;
+  continuesAfter: boolean;
+};
+
+type Segment<T> = {
+  event: CalendarEvent<T>;
+  start: number;
+  end: number;
+  continuesBefore: boolean;
+  continuesAfter: boolean;
+};
+
+/**
+ * Lay out a single day's events: events that overlap in time are split into
+ * side-by-side columns. Multi-day events are clipped to the portion that falls
+ * on `day` (e.g. a 23:00→01:00 event renders 23:00–24:00 on the start day and
+ * 00:00–01:00 on the next). Pure — safe to call per render, never per frame.
+ */
+export function layoutDayEvents<T>(events: CalendarEvent<T>[], day: Date): PositionedEvent<T>[] {
+  const dayStart = startOfDay(day);
+  const nextDayStart = addDays(dayStart, 1);
+
+  const segments: Segment<T>[] = events
+    // All-day events live in the lane, not the timed columns.
+    .filter((event) => !isAllDayEvent(event))
+    // Overlaps this day if it starts before the day ends and ends after it begins.
+    .filter((event) => event.start < nextDayStart && event.end > dayStart)
+    .map((event) => {
+      const segStart = maxDate([event.start, dayStart]);
+      const segEnd = minDate([event.end, nextDayStart]);
+      return {
+        event,
+        start: differenceInMinutes(segStart, dayStart) / MINUTES_PER_HOUR,
+        end: differenceInMinutes(segEnd, dayStart) / MINUTES_PER_HOUR,
+        continuesBefore: event.start < dayStart,
+        continuesAfter: event.end > nextDayStart,
+      };
+    })
+    .sort((a, b) => a.start - b.start);
+
+  const positioned: PositionedEvent<T>[] = [];
+  let cluster: Segment<T>[] = [];
+  let clusterEnd = Number.NEGATIVE_INFINITY;
+
+  const flushCluster = () => {
+    const columnEnds: number[] = [];
+    const columnOf = new Map<Segment<T>, number>();
+    for (const seg of cluster) {
+      let column = columnEnds.findIndex((end) => end <= seg.start);
+      if (column === -1) {
+        column = columnEnds.length;
+        columnEnds.push(seg.end);
+      } else {
+        columnEnds[column] = seg.end;
+      }
+      columnOf.set(seg, column);
+    }
+    for (const seg of cluster) {
+      positioned.push({
+        event: seg.event,
+        startHours: seg.start,
+        durationHours: Math.max(seg.end - seg.start, MIN_DURATION_HOURS),
+        column: columnOf.get(seg) ?? 0,
+        columns: columnEnds.length,
+        continuesBefore: seg.continuesBefore,
+        continuesAfter: seg.continuesAfter,
+      });
+    }
+    cluster = [];
+  };
+
+  for (const seg of segments) {
+    if (cluster.length > 0 && seg.start >= clusterEnd) flushCluster();
+    cluster.push(seg);
+    clusterEnd = Math.max(clusterEnd, seg.end);
+  }
+  if (cluster.length > 0) flushCluster();
+
+  return positioned;
+}
+
+const atMidnight = (date: Date): boolean =>
+  date.getHours() === 0 &&
+  date.getMinutes() === 0 &&
+  date.getSeconds() === 0 &&
+  date.getMilliseconds() === 0;
+
+/**
+ * Whether an event belongs in the all-day lane. An explicit `allDay` flag wins;
+ * otherwise it's inferred when the event spans whole days (both `start` and
+ * `end` land on midnight, e.g. an iCal-style all-day event). Pure.
+ */
+export function isAllDayEvent<T>(event: CalendarEvent<T>): boolean {
+  if (typeof event.allDay === "boolean") return event.allDay;
+  return event.end > event.start && atMidnight(event.start) && atMidnight(event.end);
+}
+
+/**
+ * The `startOfDay` ISO keys of every calendar day an event touches (inclusive).
+ * An event ending exactly at midnight does not count the following day. Used to
+ * index events by day for the month grid. Pure.
+ */
+export function eventDayKeys<T>(event: CalendarEvent<T>): string[] {
+  const first = startOfDay(event.start);
+  // The last instant the event occupies; an end of exactly midnight belongs to
+  // the previous day.
+  const lastInstant = event.end > event.start ? new Date(event.end.getTime() - 1) : event.start;
+  const last = startOfDay(lastInstant);
+
+  const keys: string[] = [];
+  for (let cursor = first; cursor <= last; cursor = addDays(cursor, 1)) {
+    keys.push(cursor.toISOString());
+  }
+  return keys;
+}
+
+/**
+ * Index events by the `startOfDay` ISO key of every day they touch (via
+ * {@link eventDayKeys}), so a month grid can look up a day's events with
+ * `startOfDay(date).toISOString()`. Built once and shared across month cells.
+ */
+export function groupEventsByDay<T>(
+  events: readonly CalendarEvent<T>[],
+): Map<string, CalendarEvent<T>[]> {
+  const map = new Map<string, CalendarEvent<T>[]>();
+  for (const event of events) {
+    for (const key of eventDayKeys(event)) {
+      const list = map.get(key);
+      if (list) list.push(event);
+      else map.set(key, [event]);
+    }
+  }
+  return map;
+}
+
+/**
+ * Order a day's events for the month and list views: all-day events come first
+ * (they head the day regardless of their start time), then timed events by start.
+ * Shared by both renderers so the order is identical. Use as an `Array.sort`
+ * comparator.
+ */
+export function compareDayEvents<T>(a: CalendarEvent<T>, b: CalendarEvent<T>): number {
+  const aAllDay = isAllDayEvent(a);
+  const bAllDay = isAllDayEvent(b);
+  if (aAllDay !== bAllDay) return aAllDay ? -1 : 1;
+  return a.start.getTime() - b.start.getTime();
+}
+
+/**
+ * The closed hour-spans of a day to shade on the time grid, given a
+ * `businessHours` callback and the visible `[minHour, maxHour]` window: the spans
+ * before open and after close (clamped to the window), the whole window when the
+ * day is closed (`null`) or the open hours are inverted/empty, or none when the
+ * callback returns `undefined`. Shared by both renderers so shading stays
+ * identical. Co-located with `groupEventsByDay`; both feed the grid layout.
+ */
+export function closedHourBands(
+  day: Date,
+  businessHours: BusinessHours | undefined,
+  minHour = 0,
+  maxHour = 24,
+): { start: number; end: number }[] {
+  const open = businessHours?.(day);
+  if (open === undefined) return [];
+  if (open === null) return [{ start: minHour, end: maxHour }];
+  const start = Math.max(minHour, Math.min(maxHour, open.start));
+  const end = Math.max(minHour, Math.min(maxHour, open.end));
+  // Inverted or empty open hours mean nothing is open: shade the whole window.
+  if (start >= end) return [{ start: minHour, end: maxHour }];
+  const bands: { start: number; end: number }[] = [];
+  if (start > minHour) bands.push({ start: minHour, end: start });
+  if (end < maxHour) bands.push({ start: end, end: maxHour });
+  return bands;
+}

package/src/utils/monthGrid.ts

@@ -0,0 +1,144 @@
+import { format, type Locale, isSameMonth } from "date-fns";
+import { useMemo } from "react";
+import type { WeekStartsOn } from "../types";
+import { type DateRange, type DateSelectionConstraints, daySelectionState } from "./dateRange";
+import { buildMonthWeeks, getIsToday, isWeekend } from "./dates";
+
+/** A single day in the grid, with all the state a custom cell needs to render. */
+export interface MonthGridDay {
+  date: Date;
+  /** Stable `yyyy-MM-dd` id, handy as a React key. */
+  id: string;
+  /** Day-of-month, e.g. "1". */
+  label: string;
+  isCurrentMonth: boolean;
+  isToday: boolean;
+  isWeekend: boolean;
+  isDisabled: boolean;
+  isSelected: boolean;
+  isRangeStart: boolean;
+  isRangeEnd: boolean;
+  /** Inside a complete range (endpoints included). */
+  isInRange: boolean;
+}
+
+/** One week row. */
+export interface MonthGridWeek {
+  id: string;
+  days: MonthGridDay[];
+}
+
+/** A weekday header cell (e.g. "Mon"). */
+export interface MonthGridWeekday {
+  date: Date;
+  label: string;
+}
+
+export interface MonthGrid {
+  weeks: MonthGridWeek[];
+  weekdays: MonthGridWeekday[];
+}
+
+export interface UseMonthGridOptions extends DateSelectionConstraints {
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn;
+  /** Always return six week rows for a fixed-height grid. Default false. */
+  showSixWeeks?: boolean;
+  /** Reverse each week's day order (right-to-left). Default false. */
+  isRTL?: boolean;
+  /** Selected discrete days (single/multiple). */
+  selectedDates?: Date[];
+  /** Selected span. */
+  selectedRange?: DateRange;
+  /** A date-fns locale for the weekday labels. */
+  locale?: Locale;
+}
+
+/**
+ * Pure month-grid builder: the weeks and weekday headers for `month`, each day
+ * annotated with selection/disabled/today state. Use this when you need the
+ * data outside React; inside a component prefer {@link useMonthGrid}.
+ */
+export function buildMonthGrid(month: Date, options: UseMonthGridOptions = {}): MonthGrid {
+  const {
+    weekStartsOn = 0,
+    showSixWeeks = false,
+    isRTL = false,
+    selectedDates,
+    selectedRange,
+    minDate,
+    maxDate,
+    isDateDisabled,
+    locale,
+  } = options;
+
+  const rows = buildMonthWeeks(month, weekStartsOn, { showSixWeeks, isRTL });
+
+  const weeks: MonthGridWeek[] = rows.map((days) => ({
+    id: days[0].toISOString(),
+    days: days.map(
+      (date): MonthGridDay => ({
+        date,
+        id: format(date, "yyyy-MM-dd"),
+        label: format(date, "d"),
+        isCurrentMonth: isSameMonth(date, month),
+        isToday: getIsToday(date),
+        isWeekend: isWeekend(date),
+        // Shared with MonthView, so the headless grid matches the built-in view.
+        ...daySelectionState(
+          date,
+          { selectedDates, selectedRange },
+          { minDate, maxDate, isDateDisabled },
+        ),
+      }),
+    ),
+  }));
+
+  // Weekday labels depend only on the first row's dates (already ordered).
+  const weekdays: MonthGridWeekday[] = rows[0].map((date) => ({
+    date,
+    label: format(date, "EEE", { locale }),
+  }));
+
+  return { weeks, weekdays };
+}
+
+/**
+ * Headless month-grid hook. Returns the weeks and weekday headers for `month`,
+ * each day annotated with selection/disabled/today state, so you can render a
+ * fully custom calendar without reimplementing the date maths.
+ *
+ * ```tsx
+ * const { weeks, weekdays } = useMonthGrid(month, { selectedRange: range });
+ * // map weekdays -> header cells, weeks -> rows, days -> your own <DayCell />
+ * ```
+ */
+export function useMonthGrid(month: Date, options: UseMonthGridOptions = {}): MonthGrid {
+  const {
+    weekStartsOn,
+    showSixWeeks,
+    isRTL,
+    selectedDates,
+    selectedRange,
+    minDate,
+    maxDate,
+    isDateDisabled,
+    locale,
+  } = options;
+  return useMemo(
+    () => buildMonthGrid(month, options),
+    // Deps are the destructured option fields, not the (unstable) options object.
+    [
+      month,
+      weekStartsOn,
+      showSixWeeks,
+      isRTL,
+      selectedDates,
+      selectedRange,
+      minDate,
+      maxDate,
+      isDateDisabled,
+      locale,
+    ],
+  );
+}

package/src/utils/recurrence.ts

@@ -0,0 +1,98 @@
+import { addDays, addMonths, addWeeks, addYears, startOfWeek } from "date-fns";
+import type { CalendarEvent, RecurrenceFrequency, RecurrenceRule } from "../types";
+
+const STEP: Record<RecurrenceFrequency, (date: Date, amount: number) => Date> = {
+  daily: addDays,
+  weekly: addWeeks,
+  monthly: addMonths,
+  yearly: addYears,
+};
+
+// Runaway guard. Generous enough for realistic ranges (e.g. ~13 years of a daily
+// event); set `count`/`until`, or query a tighter range, for anything larger.
+const MAX_OCCURRENCES = 5000;
+
+// Copy `source`'s time of day onto `date`.
+function withTimeOf(date: Date, source: Date): Date {
+  const next = new Date(date);
+  next.setHours(
+    source.getHours(),
+    source.getMinutes(),
+    source.getSeconds(),
+    source.getMilliseconds(),
+  );
+  return next;
+}
+
+// Occurrence start dates from `event.start` forward, in chronological order, up
+// to `rangeEnd` (and the rule's own `count`/`until`).
+function* occurrenceStarts(start: Date, rule: RecurrenceRule, rangeEnd: Date): Generator<Date> {
+  const interval = Math.max(1, Math.trunc(rule.interval ?? 1));
+  let produced = 0;
+  const within = (date: Date) =>
+    date.getTime() <= rangeEnd.getTime() &&
+    (rule.until == null || date.getTime() <= rule.until.getTime()) &&
+    (rule.count == null || produced < rule.count) &&
+    produced < MAX_OCCURRENCES;
+
+  if (rule.freq === "weekly" && rule.weekdays?.length) {
+    const weekdays = [...new Set(rule.weekdays)].sort((a, b) => a - b);
+    let weekStart = startOfWeek(start, { weekStartsOn: 0 });
+    while (true) {
+      let advanced = false;
+      for (const weekday of weekdays) {
+        const date = withTimeOf(addDays(weekStart, weekday), start);
+        if (date.getTime() < start.getTime()) continue; // before the first occurrence
+        if (!within(date)) return;
+        produced += 1;
+        advanced = true;
+        yield date;
+      }
+      const nextWeek = addWeeks(weekStart, interval);
+      // Guard against a week that yielded nothing yet hasn't reached the range.
+      if (!advanced && nextWeek.getTime() > rangeEnd.getTime()) return;
+      weekStart = nextWeek;
+    }
+  }
+
+  let cursor = start;
+  while (within(cursor)) {
+    produced += 1;
+    yield cursor;
+    cursor = STEP[rule.freq](cursor, interval);
+  }
+}
+
+function instanceAt<T>(event: CalendarEvent<T>, start: Date, durationMs: number): CalendarEvent<T> {
+  const instance = { ...event, start, end: new Date(start.getTime() + durationMs) };
+  // Occurrences aren't themselves recurring.
+  delete (instance as { recurrence?: unknown }).recurrence;
+  return instance;
+}
+
+/**
+ * Materialise recurring events into concrete occurrences overlapping
+ * `[rangeStart, rangeEnd]`. Non-recurring events pass through untouched, so the
+ * result is ready to hand to `<Calendar events={...} />`. Each occurrence keeps
+ * the original event's duration and fields (minus `recurrence`).
+ */
+export function expandRecurringEvents<T>(
+  events: CalendarEvent<T>[],
+  rangeStart: Date,
+  rangeEnd: Date,
+): CalendarEvent<T>[] {
+  const out: CalendarEvent<T>[] = [];
+  for (const event of events) {
+    if (!event.recurrence) {
+      out.push(event);
+      continue;
+    }
+    const durationMs = event.end.getTime() - event.start.getTime();
+    for (const start of occurrenceStarts(event.start, event.recurrence, rangeEnd)) {
+      // Skip occurrences that end before the range opens, but keep iterating.
+      if (start.getTime() + durationMs < rangeStart.getTime()) continue;
+      out.push(instanceAt(event, start, durationMs));
+    }
+  }
+  return out;
+}

package/src/utils/timezone.ts

@@ -0,0 +1,57 @@
+import type { CalendarEvent } from "../types";
+
+/**
+ * Reinterpret an instant as its wall-clock time in `timeZone`, returned as a
+ * device-local `Date` whose fields (hours, minutes, …) read back as that zone's
+ * clock. The calendar lays events out from `getHours()`/`getMinutes()`, so
+ * passing zoned dates makes it render in `timeZone` regardless of the device.
+ *
+ * DST-correct via `Intl` (available on modern React Native Hermes/JSC and the
+ * web). The result is for display/layout only; it no longer points at the
+ * original UTC instant, so don't round-trip it back to a real time.
+ */
+export function toZonedTime(date: Date, timeZone: string): Date {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(date);
+
+  const field = (type: Intl.DateTimeFormatPartTypes): number => {
+    const part = parts.find((p) => p.type === type);
+    return part ? Number(part.value) : 0;
+  };
+
+  // `h23` can report midnight as 24; normalise to 0.
+  const hour = field("hour") % 24;
+  return new Date(
+    field("year"),
+    field("month") - 1,
+    field("day"),
+    hour,
+    field("minute"),
+    field("second"),
+    date.getMilliseconds(),
+  );
+}
+
+/**
+ * Map every event's `start`/`end` through {@link toZonedTime} so the calendar
+ * displays them in `timeZone`. Other fields are preserved. Memoize the result
+ * (e.g. with `useMemo`) since it allocates new dates.
+ */
+export function eventsInTimeZone<T>(
+  events: CalendarEvent<T>[],
+  timeZone: string,
+): CalendarEvent<T>[] {
+  return events.map((event) => ({
+    ...event,
+    start: toZonedTime(event.start, timeZone),
+    end: toZonedTime(event.end, timeZone),
+  }));
+}