@super-calendar/core 2.1.5 → 2.2.0

package/src/utils/ical.ts

@@ -0,0 +1,409 @@
+// iCalendar (RFC 5545) import/export. Converts between `.ics` text and the
+// library's `CalendarEvent` shape so events interoperate with Google Calendar,
+// Apple Calendar, Outlook, and anything else that speaks iCal. This is a
+// pragmatic subset: VEVENT with SUMMARY / DESCRIPTION / LOCATION / UID,
+// DTSTART / DTEND (date, UTC, or floating local), all-day events, and a
+// round-trippable RRULE that maps onto the library's `RecurrenceRule`.
+
+import type { ICalendarEvent, RecurrenceFrequency, RecurrenceRule, WeekStartsOn } from "../types";
+import { zonedTimeToUtc } from "./timezone";
+
+/** An event parsed from iCal, carrying the standard fields it also round-trips. */
+export interface ICalEvent extends ICalendarEvent {
+  /** The VEVENT `UID`, if present. */
+  uid?: string;
+  /** The VEVENT `DESCRIPTION`, if present. */
+  description?: string;
+  /** The VEVENT `LOCATION`, if present. */
+  location?: string;
+}
+
+/** Options for {@link toICalendar}. */
+export interface ToICalendarOptions {
+  /** `PRODID` written to the calendar header. Default `-//super-calendar//EN`. */
+  prodId?: string;
+  /** The `DTSTAMP` stamped on every event (when it was written). Default: now. */
+  now?: Date;
+}
+
+const RRULE_FREQ: Record<string, RecurrenceFrequency> = {
+  DAILY: "daily",
+  WEEKLY: "weekly",
+  MONTHLY: "monthly",
+  YEARLY: "yearly",
+};
+const FREQ_RRULE: Record<RecurrenceFrequency, string> = {
+  daily: "DAILY",
+  weekly: "WEEKLY",
+  monthly: "MONTHLY",
+  yearly: "YEARLY",
+};
+// BYDAY tokens are Sunday-first, matching the library's 0=Sunday weekday index.
+const BYDAY = ["SU", "MO", "TU", "WE", "TH", "FR", "SA"] as const;
+
+const pad = (n: number, width = 2) => String(n).padStart(width, "0");
+
+// --- Text escaping (RFC 5545 §3.3.11) ------------------------------------
+
+function escapeText(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/;/g, "\\;")
+    .replace(/,/g, "\\,")
+    .replace(/\n/g, "\\n");
+}
+
+function unescapeText(value: string): string {
+  let out = "";
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (ch === "\\" && i + 1 < value.length) {
+      const next = value[++i];
+      out += next === "n" || next === "N" ? "\n" : next;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+// --- Line folding (RFC 5545 §3.1) ----------------------------------------
+
+function foldLine(line: string): string {
+  if (line.length <= 75) return line;
+  const parts = [line.slice(0, 75)];
+  let rest = line.slice(75);
+  while (rest.length > 74) {
+    parts.push(` ${rest.slice(0, 74)}`);
+    rest = rest.slice(74);
+  }
+  parts.push(` ${rest}`);
+  return parts.join("\r\n");
+}
+
+// Undo folding: a physical line beginning with a space or tab continues the one
+// before it (with that leading whitespace removed).
+function unfoldLines(text: string): string[] {
+  const raw = text.split(/\r\n|\r|\n/);
+  const out: string[] = [];
+  for (const line of raw) {
+    if ((line.startsWith(" ") || line.startsWith("\t")) && out.length) {
+      out[out.length - 1] += line.slice(1);
+    } else {
+      out.push(line);
+    }
+  }
+  return out;
+}
+
+// --- Dates ---------------------------------------------------------------
+
+/** Serialize a Date as a UTC iCal date-time (`YYYYMMDDTHHMMSSZ`). */
+function formatUtc(d: Date): string {
+  return (
+    `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}` +
+    `T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`
+  );
+}
+
+/** Serialize a Date as an iCal date-only value (`YYYYMMDD`) from its local parts. */
+function formatDateOnly(d: Date): string {
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
+}
+
+/**
+ * Parse an iCal DATE / DATE-TIME value. `dateOnly` marks all-day (`VALUE=DATE`);
+ * `tzid` is the IANA zone from a `TZID=` param, used to resolve the local time to
+ * the correct UTC instant.
+ */
+function parseIcalDate(value: string, dateOnly: boolean, tzid?: string): Date {
+  const y = Number(value.slice(0, 4));
+  const mo = Number(value.slice(4, 6)) - 1;
+  const d = Number(value.slice(6, 8));
+  if (dateOnly || !value.includes("T")) return new Date(y, mo, d);
+  const h = Number(value.slice(9, 11));
+  const mi = Number(value.slice(11, 13));
+  const s = Number(value.slice(13, 15));
+  // Trailing Z → UTC.
+  if (value.endsWith("Z")) return new Date(Date.UTC(y, mo, d, h, mi, s));
+  // TZID → resolve the wall-clock time in that IANA zone to a real instant.
+  if (tzid) {
+    try {
+      return zonedTimeToUtc(new Date(Date.UTC(y, mo, d, h, mi, s)), tzid);
+    } catch {
+      // Unknown zone id: fall through to a floating/local time.
+    }
+  }
+  // No zone → a floating/local time.
+  return new Date(y, mo, d, h, mi, s);
+}
+
+/** Parse an iCal/ISO-8601 DURATION (e.g. `PT1H30M`, `P1D`, `P1W`) to milliseconds. */
+function parseDuration(value: string): number | null {
+  const m = /^([+-]?)P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/.exec(
+    value.trim(),
+  );
+  if (!m || (!m[2] && !m[3] && !m[4] && !m[5] && !m[6])) return null;
+  const sign = m[1] === "-" ? -1 : 1;
+  const [w, d, h, mi, s] = [m[2], m[3], m[4], m[5], m[6]].map((x) => Number(x ?? 0));
+  return sign * ((((w * 7 + d) * 24 + h) * 60 + mi) * 60 + s) * 1000;
+}
+
+// --- RRULE ---------------------------------------------------------------
+
+function parseRRule(value: string): RecurrenceRule | undefined {
+  const parts = new Map<string, string>();
+  for (const pair of value.split(";")) {
+    const [k, v] = pair.split("=");
+    if (k && v) parts.set(k.toUpperCase(), v);
+  }
+  const freq = parts.get("FREQ");
+  if (!freq || !RRULE_FREQ[freq]) return undefined;
+  const rule: RecurrenceRule = { freq: RRULE_FREQ[freq] };
+  const interval = parts.get("INTERVAL");
+  if (interval) rule.interval = Number(interval);
+  const count = parts.get("COUNT");
+  if (count) rule.count = Number(count);
+  const until = parts.get("UNTIL");
+  if (until) rule.until = parseIcalDate(until, !until.includes("T"));
+  const byday = parts.get("BYDAY");
+  if (byday) {
+    const tokens = byday.split(",").map((t) => t.trim().toUpperCase());
+    const monthly = rule.freq === "monthly" || rule.freq === "yearly";
+    // An ordinal token (e.g. `3MO`, `-1FR`) on a monthly/yearly rule is an "Nth
+    // weekday" repeat; plain tokens (`MO`, `WE`) are the weekly weekday set.
+    const ordinal = /^([+-]?\d+)(SU|MO|TU|WE|TH|FR|SA)$/;
+    const plain: WeekStartsOn[] = [];
+    for (const token of tokens) {
+      const m = monthly ? ordinal.exec(token) : null;
+      if (m) {
+        const weekday = BYDAY.indexOf(m[2] as (typeof BYDAY)[number]);
+        if (weekday >= 0 && !rule.nthWeekday) {
+          rule.nthWeekday = { week: Number(m[1]), weekday: weekday as WeekStartsOn };
+        }
+        continue;
+      }
+      const index = BYDAY.indexOf(token as (typeof BYDAY)[number]);
+      if (index >= 0) plain.push(index as WeekStartsOn);
+    }
+    if (plain.length) rule.weekdays = plain;
+  }
+  const bymonthday = parts.get("BYMONTHDAY");
+  if (bymonthday) {
+    const days = bymonthday
+      .split(",")
+      .map((d) => Number(d.trim()))
+      .filter((d) => Number.isInteger(d) && d !== 0);
+    if (days.length) rule.monthDays = days;
+  }
+  const bymonth = parts.get("BYMONTH");
+  if (bymonth) {
+    const months = bymonth
+      .split(",")
+      .map((m) => Number(m.trim()))
+      .filter((m) => Number.isInteger(m) && m >= 1 && m <= 12);
+    if (months.length) rule.months = months;
+  }
+  return rule;
+}
+
+function formatRRule(rule: RecurrenceRule): string {
+  const parts = [`FREQ=${FREQ_RRULE[rule.freq]}`];
+  if (rule.interval && rule.interval !== 1) parts.push(`INTERVAL=${rule.interval}`);
+  if (rule.count != null) parts.push(`COUNT=${rule.count}`);
+  if (rule.until) parts.push(`UNTIL=${formatUtc(rule.until)}`);
+  if (rule.nthWeekday) {
+    parts.push(`BYDAY=${rule.nthWeekday.week}${BYDAY[rule.nthWeekday.weekday]}`);
+  } else if (rule.weekdays?.length) {
+    parts.push(`BYDAY=${rule.weekdays.map((d) => BYDAY[d]).join(",")}`);
+  }
+  if (rule.monthDays?.length) parts.push(`BYMONTHDAY=${rule.monthDays.join(",")}`);
+  if (rule.months?.length) parts.push(`BYMONTH=${rule.months.join(",")}`);
+  return parts.join(";");
+}
+
+// --- Parse ---------------------------------------------------------------
+
+interface RawLine {
+  name: string;
+  params: Map<string, string>;
+  value: string;
+}
+
+function parseLine(line: string): RawLine {
+  const colon = line.indexOf(":");
+  const head = colon === -1 ? line : line.slice(0, colon);
+  const value = colon === -1 ? "" : line.slice(colon + 1);
+  const [name, ...paramParts] = head.split(";");
+  const params = new Map<string, string>();
+  for (const p of paramParts) {
+    const eq = p.indexOf("=");
+    if (eq !== -1) params.set(p.slice(0, eq).toUpperCase(), p.slice(eq + 1));
+  }
+  return { name: name.toUpperCase(), params, value };
+}
+
+/**
+ * Parse an iCalendar (`.ics`) string into events. Reads every `VEVENT`; ignores
+ * VTODO/VJOURNAL/VTIMEZONE and unknown properties. Events without a usable
+ * `DTSTART` are skipped. All-day events (`VALUE=DATE`) with no `DTEND` get a
+ * one-day span.
+ *
+ * @example
+ * ```ts
+ * const events = parseICalendar(await file.text());
+ * ```
+ */
+export function parseICalendar(ics: string): ICalEvent[] {
+  const lines = unfoldLines(ics);
+  const events: ICalEvent[] = [];
+  let current: Partial<ICalEvent> | null = null;
+  let allDay = false;
+  // A VEVENT may carry DURATION instead of DTEND; resolve it once DTSTART is known.
+  let durationMs: number | null = null;
+  // EXDATE/RDATE(s) may appear before or after RRULE; collect, then attach at END.
+  let exdates: Date[] = [];
+  let rdates: Date[] = [];
+
+  for (const raw of lines) {
+    const line = parseLine(raw);
+    if (line.name === "BEGIN" && line.value === "VEVENT") {
+      current = {};
+      allDay = false;
+      durationMs = null;
+      exdates = [];
+      rdates = [];
+      continue;
+    }
+    if (line.name === "END" && line.value === "VEVENT") {
+      if (current?.start) {
+        if (!current.end && durationMs != null) {
+          current.end = new Date(current.start.getTime() + durationMs);
+        }
+        if (current.recurrence && exdates.length) current.recurrence.exdates = exdates;
+        if (current.recurrence && rdates.length) current.recurrence.rdates = rdates;
+        if (allDay) {
+          current.allDay = true;
+          // iCal all-day DTEND is exclusive; default to a one-day span.
+          if (!current.end) current.end = new Date(current.start.getTime() + 86_400_000);
+        } else if (!current.end) {
+          current.end = current.start;
+        }
+        events.push(current as ICalEvent);
+      }
+      current = null;
+      continue;
+    }
+    if (!current) continue;
+
+    const dateOnly = line.params.get("VALUE") === "DATE";
+    const tzid = line.params.get("TZID");
+    switch (line.name) {
+      case "SUMMARY":
+        current.title = unescapeText(line.value);
+        break;
+      case "DESCRIPTION":
+        current.description = unescapeText(line.value);
+        break;
+      case "LOCATION":
+        current.location = unescapeText(line.value);
+        break;
+      case "UID":
+        current.uid = line.value;
+        break;
+      case "DTSTART":
+        current.start = parseIcalDate(line.value, dateOnly, tzid);
+        if (dateOnly) allDay = true;
+        break;
+      case "DTEND":
+        current.end = parseIcalDate(line.value, dateOnly, tzid);
+        break;
+      case "DURATION":
+        durationMs = parseDuration(line.value);
+        break;
+      case "EXDATE":
+        for (const v of line.value.split(",")) {
+          if (v) exdates.push(parseIcalDate(v, dateOnly || !v.includes("T"), tzid));
+        }
+        break;
+      case "RDATE":
+        for (const v of line.value.split(",")) {
+          if (v) rdates.push(parseIcalDate(v, dateOnly || !v.includes("T"), tzid));
+        }
+        break;
+      case "RRULE": {
+        const rule = parseRRule(line.value);
+        if (rule) current.recurrence = rule;
+        break;
+      }
+    }
+  }
+  return events;
+}
+
+// --- Serialize -----------------------------------------------------------
+
+function line(name: string, value: string): string {
+  return foldLine(`${name}:${value}`);
+}
+
+function stableUid(event: ICalEvent): string {
+  if (event.uid) return event.uid;
+  const title = (event.title ?? "event").replace(/\s+/g, "-");
+  return `${formatUtc(event.start)}-${title}@super-calendar`;
+}
+
+/**
+ * Serialize events to an iCalendar (`.ics`) string. Timed events are written in
+ * UTC (`...Z`); all-day events (`allDay: true`) use `VALUE=DATE`. A `recurrence`
+ * becomes an `RRULE`, and `uid` / `description` / `location` round-trip.
+ *
+ * @example
+ * ```ts
+ * const ics = toICalendar(events);
+ * ```
+ */
+export function toICalendar(events: ICalEvent[], options: ToICalendarOptions = {}): string {
+  const stamp = formatUtc(options.now ?? new Date());
+  const out: string[] = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    line("PRODID", options.prodId ?? "-//super-calendar//EN"),
+    "CALSCALE:GREGORIAN",
+  ];
+
+  for (const event of events) {
+    out.push("BEGIN:VEVENT");
+    out.push(line("UID", stableUid(event)));
+    out.push(line("DTSTAMP", stamp));
+    if (event.allDay) {
+      out.push(line("DTSTART;VALUE=DATE", formatDateOnly(event.start)));
+      out.push(line("DTEND;VALUE=DATE", formatDateOnly(event.end)));
+    } else {
+      out.push(line("DTSTART", formatUtc(event.start)));
+      out.push(line("DTEND", formatUtc(event.end)));
+    }
+    if (event.title) out.push(line("SUMMARY", escapeText(event.title)));
+    if (event.description) out.push(line("DESCRIPTION", escapeText(event.description)));
+    if (event.location) out.push(line("LOCATION", escapeText(event.location)));
+    if (event.recurrence) out.push(line("RRULE", formatRRule(event.recurrence)));
+    if (event.recurrence?.exdates?.length) {
+      out.push(
+        event.allDay
+          ? line("EXDATE;VALUE=DATE", event.recurrence.exdates.map(formatDateOnly).join(","))
+          : line("EXDATE", event.recurrence.exdates.map(formatUtc).join(",")),
+      );
+    }
+    if (event.recurrence?.rdates?.length) {
+      out.push(
+        event.allDay
+          ? line("RDATE;VALUE=DATE", event.recurrence.rdates.map(formatDateOnly).join(","))
+          : line("RDATE", event.recurrence.rdates.map(formatUtc).join(",")),
+      );
+    }
+    out.push("END:VEVENT");
+  }
+
+  out.push("END:VCALENDAR");
+  return out.join("\r\n");
+}

package/src/utils/monthGrid.ts

@@ -54,10 +54,34 @@ export interface MonthGrid {
   weekdays: MonthGridWeekday[];
 }
 
+/**
+ * Weekday header label width: `narrow` ("M"), `short` ("Mon", the default), or
+ * `long` ("Monday").
+ */
+export type WeekdayFormat = "narrow" | "short" | "long";
+
+/** date-fns tokens for each {@link WeekdayFormat}. */
+const WEEKDAY_TOKENS: Record<WeekdayFormat, string> = {
+  narrow: "EEEEE",
+  short: "EEE",
+  long: "EEEE",
+};
+
+/**
+ * The date-fns format token for a {@link WeekdayFormat}. Exposed so a renderer
+ * that formats its own weekday header (rather than reading {@link buildMonthGrid})
+ * keeps the same mapping.
+ */
+export function weekdayFormatToken(format: WeekdayFormat): string {
+  return WEEKDAY_TOKENS[format];
+}
+
 /** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 export interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
+  /** Weekday header label width. Default `short` ("Mon"). */
+  weekdayFormat?: WeekdayFormat;
   /** 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. */
@@ -78,6 +102,7 @@ export interface UseMonthGridOptions extends DateSelectionConstraints {
 export function buildMonthGrid(month: Date, options: UseMonthGridOptions = {}): MonthGrid {
   const {
     weekStartsOn = 0,
+    weekdayFormat = "short",
     showSixWeeks = false,
     isRTL = false,
     selectedDates,
@@ -113,7 +138,7 @@ export function buildMonthGrid(month: Date, options: UseMonthGridOptions = {}):
   // 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 }),
+    label: format(date, WEEKDAY_TOKENS[weekdayFormat], { locale }),
   }));
 
   return { weeks, weekdays };

package/src/utils/recurrence.ts

@@ -24,6 +24,25 @@ function withTimeOf(date: Date, source: Date): Date {
   return next;
 }
 
+// The date of the `week`th `weekday` in a given month (`week` 1–5, or -1 for the
+// last). Returns null when that week doesn't exist (e.g. a 5th Monday it lacks).
+function nthWeekdayOfMonth(
+  year: number,
+  month: number,
+  week: number,
+  weekday: number,
+): Date | null {
+  if (week === -1) {
+    const lastDay = new Date(year, month + 1, 0);
+    const back = (lastDay.getDay() - weekday + 7) % 7;
+    return new Date(year, month, lastDay.getDate() - back);
+  }
+  const firstWeekday = new Date(year, month, 1).getDay();
+  const day = 1 + ((weekday - firstWeekday + 7) % 7) + (week - 1) * 7;
+  const date = new Date(year, month, day);
+  return date.getMonth() === month ? date : null;
+}
+
 // 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> {
@@ -55,6 +74,74 @@ function* occurrenceStarts(start: Date, rule: RecurrenceRule, rangeEnd: Date): G
     }
   }
 
+  if (rule.freq === "monthly" && rule.monthDays?.length) {
+    let year = start.getFullYear();
+    let month = start.getMonth();
+    while (true) {
+      const daysInMonth = new Date(year, month + 1, 0).getDate();
+      // Resolve each configured day to a concrete date-of-month (negatives count
+      // from the end), drop days this month lacks, and emit in chronological order.
+      const days = [...new Set(rule.monthDays.map((d) => (d < 0 ? daysInMonth + d + 1 : d)))]
+        .filter((d) => d >= 1 && d <= daysInMonth)
+        .sort((a, b) => a - b);
+      for (const d of days) {
+        const date = withTimeOf(new Date(year, month, d), start);
+        if (date.getTime() < start.getTime()) continue; // before the first occurrence
+        if (!within(date)) return;
+        produced += 1;
+        yield date;
+      }
+      month += interval;
+      year += Math.floor(month / 12);
+      month = ((month % 12) + 12) % 12;
+      // No occurrence yielded yet but we've run past the range: stop.
+      if (new Date(year, month, 1).getTime() > rangeEnd.getTime()) return;
+    }
+  }
+
+  if ((rule.freq === "monthly" || rule.freq === "yearly") && rule.nthWeekday) {
+    const { week, weekday } = rule.nthWeekday;
+    const stepMonths = rule.freq === "monthly" ? interval : 12 * interval;
+    let year = start.getFullYear();
+    let month = start.getMonth();
+    while (true) {
+      const day = nthWeekdayOfMonth(year, month, week, weekday);
+      if (day) {
+        const date = withTimeOf(day, start);
+        if (date.getTime() >= start.getTime()) {
+          if (!within(date)) return;
+          produced += 1;
+          yield date;
+        }
+      }
+      month += stepMonths;
+      year += Math.floor(month / 12);
+      month = ((month % 12) + 12) % 12;
+      // No occurrence yielded yet but we've run past the range: stop.
+      if (new Date(year, month, 1).getTime() > rangeEnd.getTime()) return;
+    }
+  }
+
+  if (rule.freq === "yearly" && rule.months?.length) {
+    const day = start.getDate();
+    const months = [...new Set(rule.months)].filter((m) => m >= 1 && m <= 12).sort((a, b) => a - b);
+    let year = start.getFullYear();
+    while (true) {
+      for (const m of months) {
+        const month = m - 1;
+        // Skip a year whose listed month lacks the start's day (e.g. Feb 29).
+        if (day > new Date(year, month + 1, 0).getDate()) continue;
+        const date = withTimeOf(new Date(year, month, day), start);
+        if (date.getTime() < start.getTime()) continue; // before the first occurrence
+        if (!within(date)) return;
+        produced += 1;
+        yield date;
+      }
+      year += interval;
+      if (new Date(year, 0, 1).getTime() > rangeEnd.getTime()) return;
+    }
+  }
+
   let cursor = start;
   while (within(cursor)) {
     produced += 1;
@@ -88,9 +175,23 @@ export function expandRecurringEvents<T>(
       continue;
     }
     const durationMs = event.end.getTime() - event.start.getTime();
+    // Exception days (EXDATE): an occurrence landing on one of these is dropped.
+    const dayKey = (d: Date) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+    const excluded = new Set((event.recurrence.exdates ?? []).map(dayKey));
+    // Union the rule's occurrences with any explicit RDATE additions, keyed by
+    // exact start time so a date the rule already produces isn't duplicated.
+    const starts = new Map<number, Date>();
     for (const start of occurrenceStarts(event.start, event.recurrence, rangeEnd)) {
+      starts.set(start.getTime(), start);
+    }
+    for (const rdate of event.recurrence.rdates ?? []) {
+      if (rdate.getTime() <= rangeEnd.getTime()) starts.set(rdate.getTime(), rdate);
+    }
+    const ordered = [...starts.values()].sort((a, b) => a.getTime() - b.getTime());
+    for (const start of ordered) {
       // Skip occurrences that end before the range opens, but keep iterating.
       if (start.getTime() + durationMs < rangeStart.getTime()) continue;
+      if (excluded.has(dayKey(start))) continue;
       out.push(instanceAt(event, start, durationMs));
     }
   }

package/src/utils/timezone.ts

@@ -40,6 +40,36 @@ export function toZonedTime(date: Date, timeZone: string): Date {
   );
 }
 
+// `timeZone`'s offset from UTC (ms) at `instant`: the zone's wall clock read as
+// if it were UTC, minus the real instant.
+function zoneOffsetMs(instant: Date, timeZone: string): number {
+  const z = toZonedTime(instant, timeZone);
+  const wallAsUtc = Date.UTC(
+    z.getFullYear(),
+    z.getMonth(),
+    z.getDate(),
+    z.getHours(),
+    z.getMinutes(),
+    z.getSeconds(),
+    z.getMilliseconds(),
+  );
+  return wallAsUtc - instant.getTime();
+}
+
+/**
+ * The inverse of {@link toZonedTime}: given a wall-clock time in `timeZone`,
+ * return the absolute UTC instant. Pass the wall clock as a `Date` whose **UTC**
+ * fields hold the components (e.g. `new Date(Date.UTC(y, m, d, h, min))`). Used to
+ * resolve iCal `TZID` times; DST-correct via a two-pass offset (ambiguous
+ * fall-back times resolve to the post-transition offset).
+ */
+export function zonedTimeToUtc(wallClock: Date, timeZone: string): Date {
+  const guess = wallClock.getTime();
+  const firstPass = zoneOffsetMs(new Date(guess), timeZone);
+  const secondPass = zoneOffsetMs(new Date(guess - firstPass), timeZone);
+  return new Date(guess - secondPass);
+}
+
 /**
  * Map every event's `start`/`end` through {@link toZonedTime} so the calendar
  * displays them in `timeZone`. Other fields are preserved. Memoize the result