@super-calendar/core 2.1.4 → 2.2.0

package/dist/index.mjs

@@ -435,6 +435,369 @@ function monthVisibleCount(total, capacity) {
 	return Math.max(1, capacity.withMore);
 }
 //#endregion
+//#region src/utils/timezone.ts
+/**
+* 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.
+*/
+function toZonedTime(date, timeZone) {
+	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) => {
+		const part = parts.find((p) => p.type === type);
+		return part ? Number(part.value) : 0;
+	};
+	const hour = field("hour") % 24;
+	return new Date(field("year"), field("month") - 1, field("day"), hour, field("minute"), field("second"), date.getMilliseconds());
+}
+function zoneOffsetMs(instant, timeZone) {
+	const z = toZonedTime(instant, timeZone);
+	return Date.UTC(z.getFullYear(), z.getMonth(), z.getDate(), z.getHours(), z.getMinutes(), z.getSeconds(), z.getMilliseconds()) - 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).
+*/
+function zonedTimeToUtc(wallClock, timeZone) {
+	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
+* (e.g. with `useMemo`) since it allocates new dates.
+*/
+function eventsInTimeZone(events, timeZone) {
+	return events.map((event) => ({
+		...event,
+		start: toZonedTime(event.start, timeZone),
+		end: toZonedTime(event.end, timeZone)
+	}));
+}
+//#endregion
+//#region src/utils/ical.ts
+const RRULE_FREQ = {
+	DAILY: "daily",
+	WEEKLY: "weekly",
+	MONTHLY: "monthly",
+	YEARLY: "yearly"
+};
+const FREQ_RRULE = {
+	daily: "DAILY",
+	weekly: "WEEKLY",
+	monthly: "MONTHLY",
+	yearly: "YEARLY"
+};
+const BYDAY = [
+	"SU",
+	"MO",
+	"TU",
+	"WE",
+	"TH",
+	"FR",
+	"SA"
+];
+const pad = (n, width = 2) => String(n).padStart(width, "0");
+function escapeText(value) {
+	return value.replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\n/g, "\\n");
+}
+function unescapeText(value) {
+	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;
+}
+function foldLine(line) {
+	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");
+}
+function unfoldLines(text) {
+	const raw = text.split(/\r\n|\r|\n/);
+	const out = [];
+	for (const line of raw) if ((line.startsWith(" ") || line.startsWith("	")) && out.length) out[out.length - 1] += line.slice(1);
+	else out.push(line);
+	return out;
+}
+/** Serialize a Date as a UTC iCal date-time (`YYYYMMDDTHHMMSSZ`). */
+function formatUtc(d) {
+	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) {
+	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, dateOnly, tzid) {
+	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));
+	if (value.endsWith("Z")) return new Date(Date.UTC(y, mo, d, h, mi, s));
+	if (tzid) try {
+		return zonedTimeToUtc(new Date(Date.UTC(y, mo, d, h, mi, s)), tzid);
+	} catch {}
+	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) {
+	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) * 1e3;
+}
+function parseRRule(value) {
+	const parts = /* @__PURE__ */ new Map();
+	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 void 0;
+	const rule = { 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";
+		const ordinal = /^([+-]?\d+)(SU|MO|TU|WE|TH|FR|SA)$/;
+		const plain = [];
+		for (const token of tokens) {
+			const m = monthly ? ordinal.exec(token) : null;
+			if (m) {
+				const weekday = BYDAY.indexOf(m[2]);
+				if (weekday >= 0 && !rule.nthWeekday) rule.nthWeekday = {
+					week: Number(m[1]),
+					weekday
+				};
+				continue;
+			}
+			const index = BYDAY.indexOf(token);
+			if (index >= 0) plain.push(index);
+		}
+		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) {
+	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(";");
+}
+function parseLine(line) {
+	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 = /* @__PURE__ */ new Map();
+	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());
+* ```
+*/
+function parseICalendar(ics) {
+	const lines = unfoldLines(ics);
+	const events = [];
+	let current = null;
+	let allDay = false;
+	let durationMs = null;
+	let exdates = [];
+	let rdates = [];
+	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;
+					if (!current.end) current.end = new Date(current.start.getTime() + 864e5);
+				} else if (!current.end) current.end = current.start;
+				events.push(current);
+			}
+			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;
+}
+function line(name, value) {
+	return foldLine(`${name}:${value}`);
+}
+function stableUid(event) {
+	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);
+* ```
+*/
+function toICalendar(events, options = {}) {
+	const stamp = formatUtc(options.now ?? /* @__PURE__ */ new Date());
+	const out = [
+		"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");
+}
+//#endregion
 //#region src/utils/layout.ts
 const MINUTES_PER_HOUR = 60;
 const MIN_DURATION_HOURS = .25;
@@ -572,13 +935,27 @@ function closedHourBands(day, businessHours, minHour = 0, maxHour = 24) {
 }
 //#endregion
 //#region src/utils/monthGrid.ts
+/** date-fns tokens for each {@link WeekdayFormat}. */
+const WEEKDAY_TOKENS = {
+	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.
+*/
+function weekdayFormatToken(format) {
+	return WEEKDAY_TOKENS[format];
+}
 /**
 * 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}.
 */
 function buildMonthGrid(month, options = {}) {
-	const { weekStartsOn = 0, showSixWeeks = false, isRTL = false, selectedDates, selectedRange, minDate, maxDate, isDateDisabled, locale } = options;
+	const { weekStartsOn = 0, weekdayFormat = "short", showSixWeeks = false, isRTL = false, selectedDates, selectedRange, minDate, maxDate, isDateDisabled, locale } = options;
 	const rows = buildMonthWeeks(month, weekStartsOn, {
 		showSixWeeks,
 		isRTL
@@ -605,7 +982,7 @@ function buildMonthGrid(month, options = {}) {
 		})),
 		weekdays: rows[0].map((date) => ({
 			date,
-			label: format(date, "EEE", { locale })
+			label: format(date, WEEKDAY_TOKENS[weekdayFormat], { locale })
 		}))
 	};
 }
@@ -648,6 +1025,16 @@ function withTimeOf(date, source) {
 	next.setHours(source.getHours(), source.getMinutes(), source.getSeconds(), source.getMilliseconds());
 	return next;
 }
+function nthWeekdayOfMonth(year, month, week, weekday) {
+	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 day = 1 + (weekday - new Date(year, month, 1).getDay() + 7) % 7 + (week - 1) * 7;
+	const date = new Date(year, month, day);
+	return date.getMonth() === month ? date : null;
+}
 function* occurrenceStarts(start, rule, rangeEnd) {
 	const interval = Math.max(1, Math.trunc(rule.interval ?? 1));
 	let produced = 0;
@@ -670,6 +1057,64 @@ function* occurrenceStarts(start, rule, rangeEnd) {
 			weekStart = nextWeek;
 		}
 	}
+	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();
+			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;
+				if (!within(date)) return;
+				produced += 1;
+				yield date;
+			}
+			month += interval;
+			year += Math.floor(month / 12);
+			month = (month % 12 + 12) % 12;
+			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;
+			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;
+				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;
+				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;
@@ -700,54 +1145,19 @@ function expandRecurringEvents(events, rangeStart, rangeEnd) {
 			continue;
 		}
 		const durationMs = event.end.getTime() - event.start.getTime();
-		for (const start of occurrenceStarts(event.start, event.recurrence, rangeEnd)) {
+		const dayKey = (d) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+		const excluded = new Set((event.recurrence.exdates ?? []).map(dayKey));
+		const starts = /* @__PURE__ */ new Map();
+		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) {
 			if (start.getTime() + durationMs < rangeStart.getTime()) continue;
+			if (excluded.has(dayKey(start))) continue;
 			out.push(instanceAt(event, start, durationMs));
 		}
 	}
 	return out;
 }
 //#endregion
-//#region src/utils/timezone.ts
-/**
-* 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.
-*/
-function toZonedTime(date, timeZone) {
-	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) => {
-		const part = parts.find((p) => p.type === type);
-		return part ? Number(part.value) : 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.
-*/
-function eventsInTimeZone(events, timeZone) {
-	return events.map((event) => ({
-		...event,
-		start: toZonedTime(event.start, timeZone),
-		end: toZonedTime(event.end, timeZone)
-	}));
-}
-//#endregion
-export { CalendarSelectionProvider, MIN_BOX_HEIGHT_FOR_TIME, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount };
+export { CalendarSelectionProvider, MIN_BOX_HEIGHT_FOR_TIME, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, parseICalendar, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toICalendar, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount, weekdayFormatToken, zonedTimeToUtc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/core",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Render-agnostic core for super-calendar: date math, selection model, event layout, the month-grid builder, headless hooks, and neutral theme tokens. No renderer.",
   "keywords": [
     "calendar",

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./utils/dateRange";
 export * from "./utils/dates";
 export * from "./utils/drag";
 export * from "./utils/eventDisplay";
+export * from "./utils/ical";
 export * from "./utils/layout";
 export * from "./utils/monthGrid";
 export * from "./utils/recurrence";

package/src/types.ts

@@ -51,6 +51,38 @@ export interface RecurrenceRule {
    * the event's time of day. Omit to repeat on the start date's own weekday.
    */
   weekdays?: WeekStartsOn[];
+  /**
+   * For `monthly`/`yearly`: repeat on the Nth weekday of the period instead of the
+   * start date's day-of-month — e.g. `{ week: 3, weekday: 1 }` is the 3rd Monday.
+   * `week` is 1–5, or -1 for the last such weekday. Maps to an ordinal iCal `BYDAY`
+   * (e.g. `3MO`, `-1FR`).
+   */
+  nthWeekday?: { week: number; weekday: WeekStartsOn };
+  /**
+   * For `monthly`: the day(s) of the month to repeat on — 1–31, or negative to
+   * count from the month's end (-1 is the last day, -2 the second-to-last). Days
+   * that don't exist in a given month (e.g. the 31st in February) are skipped.
+   * Takes precedence over the start date's own day-of-month. Maps to iCal
+   * `BYMONTHDAY`.
+   */
+  monthDays?: number[];
+  /**
+   * For `yearly`: the month(s) to repeat in (1 = January … 12 = December), keeping
+   * the start date's day-of-month. Years where a listed month lacks that day are
+   * skipped. Maps to iCal `BYMONTH`.
+   */
+  months?: number[];
+  /**
+   * Dates to skip (exceptions). An occurrence whose day matches one of these is
+   * dropped by `expandRecurringEvents`. Maps to iCal `EXDATE`.
+   */
+  exdates?: Date[];
+  /**
+   * Extra one-off start dates added to the set, even ones the rule wouldn't
+   * produce. Merged in chronological order and de-duplicated against rule
+   * occurrences; `exdates` still apply. Maps to iCal `RDATE`.
+   */
+  rdates?: Date[];
 }
 
 /**

package/src/utils/eventDisplay.ts

@@ -1,5 +1,5 @@
 import { format } from "date-fns";
-import type { CalendarMode } from "../types";
+import type { CalendarEvent, CalendarMode } from "../types";
 
 /**
  * Minimum event-box height (px) before the built-in renderer shows the time line
@@ -32,6 +32,31 @@ export function eventAccessibilityLabel(args: {
   return [args.title, time].filter(Boolean).join(", ");
 }
 
+/**
+ * Context describing how an event is being rendered, passed to a consumer's
+ * {@link EventAccessibilityLabeler} so the label can adapt to the view (e.g. omit
+ * the time in month mode, or read the 12-hour clock when `ampm` is set).
+ */
+export interface EventAccessibilityLabelContext {
+  /** The view the event is rendered in. */
+  mode: CalendarMode;
+  /** Whether the event sits in the all-day lane (or is an all-day event in month view). */
+  isAllDay: boolean;
+  /** Whether times are formatted as 12-hour AM/PM. */
+  ampm: boolean;
+}
+
+/**
+ * Override for an event's screen-reader label. Return the full text to announce
+ * for `event`; each renderer uses it verbatim in place of the built-in
+ * {@link eventAccessibilityLabel}. Shared by both renderers, so a custom label
+ * reads the same on web and native.
+ */
+export type EventAccessibilityLabeler<T = unknown> = (
+  event: CalendarEvent<T>,
+  context: EventAccessibilityLabelContext,
+) => string;
+
 /**
  * Month cells and the all-day lane show a single clipped line; timed-grid titles
  * (`undefined`) wrap to fill the box.