@remit/web-client 0.0.231 → 0.0.233

package/src/hooks/calendar/index.ts

@@ -0,0 +1,88 @@
+/**
+ * What every calendar surface reads and writes, in one module.
+ *
+ * The grid, the reading pane and the day strip all ask the same questions, so
+ * they ask them through the same hooks: one window is fetched once however many
+ * of them are on screen, and a write invalidates what all of them are showing.
+ */
+export {
+	type AgendaRange,
+	busySpansByDate,
+	datesInRange,
+	extendRangeEnd,
+	extendRangeStart,
+	type FreeLookup,
+	freeStretchesByDate,
+	LEAD_IN,
+	LEAD_OUT,
+	PAGE,
+	rangeAround,
+	rangeCovering,
+	weekKeyOf,
+	weekWindowsOver,
+} from "./agenda-window";
+export {
+	type CreateInput,
+	createInputFromDraft,
+	type DraftRefusal,
+	draftFromEvent,
+	emptyDraft,
+	patchFromDrafts,
+	type UpdatePatch,
+} from "./draft";
+export {
+	type CalendarInstanceRef,
+	calendarInstanceId,
+	deviceTimeZone,
+	isDrawnInstance,
+	readCalendarInstanceId,
+	toCalendarDescriptor,
+	toCalendarEventData,
+	UNZONED_CALENDAR,
+} from "./instance";
+export { rruleFromText, textFromRrule } from "./recurrence-rule";
+export {
+	type CalendarResourceText,
+	rruleFromIcalData,
+	textFromIcalData,
+} from "./resource";
+export {
+	type CalendarSelection,
+	selectCalendarIds,
+	useCalendarSelection,
+	useDrawnEvents,
+} from "./selection";
+export {
+	type CalendarEventResource,
+	useCalendarEvent,
+} from "./useCalendarEvent";
+export {
+	CALENDAR_WINDOW_STALE_TIME,
+	type CalendarEventWeeksResult,
+	type CalendarEventWindowRequest,
+	type CalendarEventWindowResult,
+	useCalendarEventWeeks,
+	useCalendarEventWindow,
+	usePrefetchAdjacentWindows,
+} from "./useCalendarEvents";
+export {
+	type CalendarFreeBusyResult,
+	useCalendarFreeBusyWeeks,
+} from "./useCalendarFreeBusy";
+export { type CalendarsResult, useCalendars } from "./useCalendars";
+export {
+	type CalendarWriteOutcome,
+	type CalendarWrites,
+	type ScopedWrite,
+	useCalendarWrites,
+	useInvalidateCalendarReads,
+} from "./useCalendarWrites";
+export {
+	addDays,
+	type CalendarWindow,
+	calendarWindow,
+	calendarWindowOfDays,
+	isoAt,
+	isoAtInZone,
+	startOfDay,
+} from "./window";

package/src/hooks/calendar/instance.ts

@@ -0,0 +1,136 @@
+/**
+ * The API's shapes, as the calendar kit draws them.
+ *
+ * One place does the translating, so the grid, the strip and the reading pane
+ * cannot disagree about what an occurrence is. Nothing here expands a
+ * recurrence: the server returns instances, and this reads them.
+ */
+import type {
+	RemitImapCalendarEventInstance,
+	RemitImapCalendarResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type {
+	CalendarColorId,
+	CalendarDescriptor,
+	CalendarEventData,
+	ZoneCertainty,
+} from "@remit/ui";
+
+/** The device's own clock, the only zone a browser can honestly draw in. */
+export const deviceTimeZone = (): string =>
+	Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+/**
+ * A collection that names no zone of its own, spelled the way the API spells
+ * it: an empty string, which both ends read as UTC.
+ *
+ * There is deliberately no substitute value. The server checks a TZID against
+ * `Intl.supportedValuesOf("timeZone")`, which is the canonical zone list and so
+ * holds no spelling of UTC at all — not `UTC`, not `Etc/UTC` — and refuses
+ * anything else. Sending nothing is what the API asks for, and it is the only
+ * thing it accepts.
+ *
+ * The device's zone is not the fallback either. The listing returns this
+ * collection's occurrences on its own clock, so answering with the reader's
+ * would rewrite every time they saved by the difference between the two.
+ */
+export const UNZONED_CALENDAR = "";
+
+const COLORS: Record<string, CalendarColorId> = {
+	Cal1: "cal-1",
+	Cal2: "cal-2",
+	Cal3: "cal-3",
+	Cal4: "cal-4",
+	Cal5: "cal-5",
+	Cal6: "cal-6",
+};
+
+const ZONES: Record<string, ZoneCertainty> = {
+	Local: "local",
+	Explicit: "explicit",
+	Ambiguous: "ambiguous",
+};
+
+/**
+ * The address of one occurrence, as a single string, because the grid selects
+ * an event by one id. A series draws many occurrences from one resource, so the
+ * resource id alone would key every Monday standup the same and select all of
+ * them at once.
+ */
+const OCCURRENCE_SEPARATOR = "#";
+
+export function calendarInstanceId(
+	calendarObjectId: string,
+	recurrenceId: string,
+): string {
+	return recurrenceId === ""
+		? calendarObjectId
+		: `${calendarObjectId}${OCCURRENCE_SEPARATOR}${recurrenceId}`;
+}
+
+export interface CalendarInstanceRef {
+	calendarObjectId: string;
+	/** `""` on a resource that does not recur. */
+	recurrenceId: string;
+}
+
+export function readCalendarInstanceId(id: string): CalendarInstanceRef {
+	const cut = id.indexOf(OCCURRENCE_SEPARATOR);
+	if (cut === -1) return { calendarObjectId: id, recurrenceId: "" };
+	return {
+		calendarObjectId: id.slice(0, cut),
+		recurrenceId: id.slice(cut + 1),
+	};
+}
+
+export function toCalendarDescriptor(
+	calendar: RemitImapCalendarResponse,
+): CalendarDescriptor {
+	return {
+		id: calendar.calendarId,
+		accountId: calendar.accountConfigId,
+		accountLabel: "",
+		name: calendar.displayName,
+		color: COLORS[calendar.color] ?? "cal-1",
+	};
+}
+
+/**
+ * One occurrence, drawn. `location`, `notes` and the guest list are projections
+ * the listing does not carry — the reading pane fetches the resource itself for
+ * those, and a grid chip has no room for them anyway.
+ */
+export function toCalendarEventData(
+	instance: RemitImapCalendarEventInstance,
+	timeZone: string,
+): CalendarEventData {
+	return {
+		id: calendarInstanceId(instance.calendarObjectId, instance.recurrenceId),
+		calendarId: instance.calendarId,
+		title: instance.summary,
+		start: instance.start,
+		end: instance.end,
+		allDay: instance.allDay,
+		location: "",
+		notes: "",
+		attendees: [],
+		myRsvp: "accepted",
+		threadId: "",
+		threadSubject: "",
+		timeZone,
+		zoneCertainty: ZONES[instance.zoneCertainty] ?? "explicit",
+		recurrenceRule: instance.hasRecurrence ? "Repeats" : "",
+		seriesId: instance.hasRecurrence ? instance.icalUid : "",
+		seriesException: false,
+		status: instance.status === "Tentative" ? "tentative" : "confirmed",
+	};
+}
+
+/**
+ * A cancelled occurrence is not a lighter shade of confirmed, and the kit has
+ * no third state to draw it in, so it is left off the calendar entirely rather
+ * than shown as an event that is still happening.
+ */
+export const isDrawnInstance = (
+	instance: RemitImapCalendarEventInstance,
+): boolean => instance.status !== "Cancelled";

package/src/hooks/calendar/recurrence-rule.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Repeat rules, both ways.
+ *
+ * The picker only ever offers the sentences `repeatChoices` derives, so the
+ * table has to cover exactly those and refuse everything else — a sentence
+ * turned into a rule it does not mean is an event that repeats on days nobody
+ * chose, and nothing on screen would say so.
+ *
+ * A rule written by something else — a native client, an invitation — must come
+ * back unread rather than snapped to the nearest sentence.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { repeatChoices } from "@remit/ui";
+import { rruleFromText, textFromRrule } from "./recurrence-rule";
+
+const DATE = "2026-06-10";
+const TIME = "09:15";
+
+describe("every rule the picker offers", () => {
+	it("becomes an RRULE, and reads back as the sentence it was picked from", () => {
+		for (const choice of repeatChoices(DATE, TIME)) {
+			const rule = rruleFromText(choice);
+			assert.ok(
+				rule !== undefined && rule !== "",
+				`no rule for the offered choice "${choice}"`,
+			);
+			assert.equal(textFromRrule(rule, TIME), choice);
+		}
+	});
+
+	it("says what each one means", () => {
+		assert.equal(rruleFromText("Every day, 09:15"), "FREQ=DAILY");
+		assert.equal(
+			rruleFromText("Every weekday, 09:15"),
+			"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
+		);
+		assert.equal(
+			rruleFromText("Every week on Wednesday, 09:15"),
+			"FREQ=WEEKLY;BYDAY=WE",
+		);
+		assert.equal(
+			rruleFromText("Every month on the second Wednesday, 09:15"),
+			"FREQ=MONTHLY;BYDAY=2WE",
+		);
+		assert.equal(
+			rruleFromText("Every year on 10 June, 09:15"),
+			"FREQ=YEARLY;BYMONTH=6;BYMONTHDAY=10",
+		);
+	});
+
+	it("reads the last week of a month as the rule that means it", () => {
+		assert.equal(
+			rruleFromText("Every month on the last Friday"),
+			"FREQ=MONTHLY;BYDAY=-1FR",
+		);
+		assert.equal(
+			textFromRrule("FREQ=MONTHLY;BYDAY=-1FR", ""),
+			"Every month on the last Friday",
+		);
+	});
+});
+
+describe("no repeat", () => {
+	it("is the empty rule rather than a refusal", () => {
+		assert.equal(rruleFromText(""), "");
+	});
+});
+
+describe("a sentence this table does not cover", () => {
+	it("is refused rather than guessed at", () => {
+		assert.equal(rruleFromText("Every other Tuesday"), undefined);
+		assert.equal(rruleFromText("Every week on Caturday"), undefined);
+		assert.equal(rruleFromText("Repeats"), undefined);
+	});
+});
+
+describe("a rule written by something else", () => {
+	it("comes back unread rather than snapped to the nearest sentence", () => {
+		assert.equal(
+			textFromRrule("FREQ=WEEKLY;INTERVAL=2;BYDAY=TU", ""),
+			undefined,
+		);
+		assert.equal(textFromRrule("FREQ=DAILY;COUNT=10", ""), undefined);
+		assert.equal(
+			textFromRrule("FREQ=DAILY;UNTIL=20261231T000000Z", ""),
+			undefined,
+		);
+		assert.equal(textFromRrule("FREQ=HOURLY", ""), undefined);
+		assert.equal(textFromRrule("FREQ=WEEKLY", ""), undefined);
+	});
+});

package/src/hooks/calendar/recurrence-rule.ts

@@ -0,0 +1,133 @@
+/**
+ * Repeat rules, between the sentence a person picks and the RRULE the API
+ * stores.
+ *
+ * The kit's picker deals only in sentences — "Every weekday, 09:15" — and the
+ * calendar API deals only in RFC 5545 rules. This is the single table read both
+ * ways, so a rule this client wrote reads back as the sentence it was picked
+ * from. A rule written by anything else, a native client or an invitation, is
+ * not forced into one of these sentences: it comes back unread, and the surface
+ * says the event repeats without claiming to know how.
+ */
+
+const WEEKDAYS = [
+	"Sunday",
+	"Monday",
+	"Tuesday",
+	"Wednesday",
+	"Thursday",
+	"Friday",
+	"Saturday",
+];
+
+const BYDAY = ["SU", "MO", "TU", "WE", "TH", "FR", "SA"];
+
+const MONTHS = [
+	"January",
+	"February",
+	"March",
+	"April",
+	"May",
+	"June",
+	"July",
+	"August",
+	"September",
+	"October",
+	"November",
+	"December",
+];
+
+const ORDINALS = ["first", "second", "third", "fourth", "last"];
+
+const ORDINAL_NUMBERS = [1, 2, 3, 4, -1];
+
+const WEEKDAY_SET = "MO,TU,WE,TH,FR";
+
+/** The clock the picker appends, stripped so the rule itself can be read. */
+const withoutClock = (text: string): string =>
+	text.replace(/,\s*\d{2}:\d{2}$/, "").trim();
+
+/**
+ * The RRULE a picked sentence means, or `undefined` for a sentence this table
+ * does not cover. A caller refuses the write rather than storing a rule it
+ * guessed at.
+ */
+export function rruleFromText(text: string): string | undefined {
+	const rule = withoutClock(text);
+	if (rule === "") return "";
+	if (rule === "Every day") return "FREQ=DAILY";
+	if (rule === "Every weekday") return `FREQ=WEEKLY;BYDAY=${WEEKDAY_SET}`;
+
+	const weekly = rule.match(/^Every week on (\w+)$/);
+	if (weekly) {
+		const day = WEEKDAYS.indexOf(weekly[1]);
+		return day === -1 ? undefined : `FREQ=WEEKLY;BYDAY=${BYDAY[day]}`;
+	}
+
+	const monthly = rule.match(/^Every month on the (\w+) (\w+)$/);
+	if (monthly) {
+		const ordinal = ORDINALS.indexOf(monthly[1]);
+		const day = WEEKDAYS.indexOf(monthly[2]);
+		if (ordinal === -1 || day === -1) return undefined;
+		return `FREQ=MONTHLY;BYDAY=${ORDINAL_NUMBERS[ordinal]}${BYDAY[day]}`;
+	}
+
+	const yearly = rule.match(/^Every year on (\d{1,2}) (\w+)$/);
+	if (yearly) {
+		const month = MONTHS.indexOf(yearly[2]);
+		if (month === -1) return undefined;
+		return `FREQ=YEARLY;BYMONTH=${month + 1};BYMONTHDAY=${Number(yearly[1])}`;
+	}
+
+	return undefined;
+}
+
+const clockSuffix = (startTime: string): string =>
+	startTime === "" ? "" : `, ${startTime}`;
+
+/** The sentence an RRULE was picked from, or `undefined` where it was not. */
+export function textFromRrule(
+	rule: string,
+	startTime: string,
+): string | undefined {
+	const parts = new Map(
+		rule
+			.split(";")
+			.map((part) => part.split("="))
+			.filter((pair): pair is [string, string] => pair.length === 2)
+			.map(([name, value]) => [name.toUpperCase(), value.toUpperCase()]),
+	);
+	const clock = clockSuffix(startTime);
+	const frequency = parts.get("FREQ");
+	const byDay = parts.get("BYDAY");
+
+	if (parts.has("INTERVAL") && parts.get("INTERVAL") !== "1") return undefined;
+	if (parts.has("UNTIL") || parts.has("COUNT")) return undefined;
+
+	if (frequency === "DAILY") return `Every day${clock}`;
+
+	if (frequency === "WEEKLY") {
+		if (byDay === undefined) return undefined;
+		if (byDay === WEEKDAY_SET) return `Every weekday${clock}`;
+		const day = BYDAY.indexOf(byDay);
+		return day === -1 ? undefined : `Every week on ${WEEKDAYS[day]}${clock}`;
+	}
+
+	if (frequency === "MONTHLY") {
+		const match = byDay?.match(/^(-?\d)([A-Z]{2})$/);
+		if (!match) return undefined;
+		const ordinal = ORDINAL_NUMBERS.indexOf(Number(match[1]));
+		const day = BYDAY.indexOf(match[2]);
+		if (ordinal === -1 || day === -1) return undefined;
+		return `Every month on the ${ORDINALS[ordinal]} ${WEEKDAYS[day]}${clock}`;
+	}
+
+	if (frequency === "YEARLY") {
+		const month = Number(parts.get("BYMONTH"));
+		const day = Number(parts.get("BYMONTHDAY"));
+		if (!month || !day || month > 12) return undefined;
+		return `Every year on ${day} ${MONTHS[month - 1]}${clock}`;
+	}
+
+	return undefined;
+}

package/src/hooks/calendar/resource.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Reading three properties off a stored resource.
+ *
+ * RFC 5545 folds a long line by breaking it and indenting the remainder, so a
+ * value read line-first stops halfway and looks like a shorter value rather
+ * than a broken one — a rule truncated that way turns a weekly meeting into a
+ * daily one on screen with nothing to say it happened.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { rruleFromIcalData, textFromIcalData } from "./resource";
+
+const ics = (...lines: string[]): string =>
+	[
+		"BEGIN:VCALENDAR",
+		"BEGIN:VEVENT",
+		...lines,
+		"END:VEVENT",
+		"END:VCALENDAR",
+	].join("\r\n");
+
+describe("the rule inside a resource", () => {
+	it("is read whole across a fold", () => {
+		assert.equal(
+			rruleFromIcalData(ics("RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,", " TH,FR")),
+			"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
+		);
+	});
+
+	it("is empty where the event does not repeat", () => {
+		assert.equal(rruleFromIcalData(ics("SUMMARY:Roadmap review")), "");
+	});
+});
+
+describe("the text a listing does not carry", () => {
+	it("comes back unescaped", () => {
+		const text = textFromIcalData(
+			ics(
+				"LOCATION:Room Zuid\\, second floor",
+				"DESCRIPTION:Bring the numbers.\\nAnd the slides.",
+			),
+		);
+		assert.equal(text.location, "Room Zuid, second floor");
+		assert.equal(text.description, "Bring the numbers.\nAnd the slides.");
+	});
+
+	it("reads a property that carries parameters", () => {
+		assert.equal(
+			textFromIcalData(ics("DESCRIPTION;LANGUAGE=en:Plain text")).description,
+			"Plain text",
+		);
+	});
+
+	/**
+	 * A parameter value may be quoted precisely so it can hold a colon, which is
+	 * what a URI does. Splitting the line on its first colon hands back the tail
+	 * of that URI as though it were the property's own value.
+	 */
+	it("reads past a colon inside a quoted parameter", () => {
+		assert.equal(
+			textFromIcalData(ics('DESCRIPTION;ALTREP="cid:part1.0":Plain text'))
+				.description,
+			"Plain text",
+		);
+		assert.equal(
+			textFromIcalData(
+				ics('LOCATION;X-ADDRESS="https://maps.example/x:1":Room Zuid'),
+			).location,
+			"Room Zuid",
+		);
+	});
+
+	it("does not answer for a property whose name merely starts the same", () => {
+		assert.equal(textFromIcalData(ics("LOCATION-TYPE:room")).location, "");
+	});
+
+	it("takes the master's value rather than an override's", () => {
+		const overridden = [
+			"BEGIN:VCALENDAR",
+			"BEGIN:VEVENT",
+			"LOCATION:Room Zuid",
+			"END:VEVENT",
+			"BEGIN:VEVENT",
+			"RECURRENCE-ID:20260610T090000Z",
+			"LOCATION:Room Noord",
+			"END:VEVENT",
+			"END:VCALENDAR",
+		].join("\r\n");
+		assert.equal(textFromIcalData(overridden).location, "Room Zuid");
+	});
+
+	it("is empty where the resource says nothing", () => {
+		assert.deepEqual(textFromIcalData(ics("SUMMARY:Standup")), {
+			location: "",
+			description: "",
+		});
+	});
+});

package/src/hooks/calendar/resource.ts

@@ -0,0 +1,74 @@
+/**
+ * The few properties a reading pane needs that the occurrence listing does not
+ * carry, read off the stored resource.
+ *
+ * This is not a parser and never becomes one. It reads three named properties
+ * of the master VEVENT so the pane can show a location and the editor can send
+ * one back unchanged; anything structural — recurrence expansion above all —
+ * belongs to the server, which is the only thing that expands a series.
+ */
+
+/**
+ * RFC 5545 breaks a long property across lines with a leading space or tab, so
+ * the folds are joined before anything is matched — a value read fold-first
+ * stops halfway through and looks like a shorter value rather than a broken one.
+ */
+const unfold = (icalData: string): string =>
+	icalData.replace(/\r?\n[ \t]/g, "");
+
+/** RFC 5545 3.3.11: the four escapes a TEXT value carries. */
+const unescapeText = (value: string): string =>
+	value
+		.replace(/\\n/gi, "\n")
+		.replace(/\\,/g, ",")
+		.replace(/\\;/g, ";")
+		.replace(/\\\\/g, "\\");
+
+/**
+ * Where a content line's parameters end and its value begins.
+ *
+ * The separator is the first colon outside a quoted string, not the first colon
+ * (RFC 5545 3.1). A parameter value is allowed to be quoted precisely so it can
+ * hold one — `ALTREP="cid:part1"` is ordinary — and splitting on the first
+ * colon hands back the tail of a URI as though it were the property's value.
+ */
+function valueAt(line: string, name: string): string | undefined {
+	let quoted = false;
+	for (let index = name.length; index < line.length; index += 1) {
+		const character = line[index];
+		if (index === name.length && character !== ";" && character !== ":")
+			return undefined;
+		if (character === '"') {
+			quoted = !quoted;
+			continue;
+		}
+		if (!quoted && character === ":") return line.slice(index + 1).trim();
+	}
+	return undefined;
+}
+
+/**
+ * The first occurrence of a property, parameters and all. The master VEVENT is
+ * written before its overrides, so the first match is the series' own value.
+ */
+function firstProperty(icalData: string, name: string): string {
+	for (const line of unfold(icalData).split(/\r?\n/)) {
+		if (!line.startsWith(name)) continue;
+		const value = valueAt(line, name);
+		if (value !== undefined) return value;
+	}
+	return "";
+}
+
+export const rruleFromIcalData = (icalData: string): string =>
+	firstProperty(icalData, "RRULE");
+
+export interface CalendarResourceText {
+	location: string;
+	description: string;
+}
+
+export const textFromIcalData = (icalData: string): CalendarResourceText => ({
+	location: unescapeText(firstProperty(icalData, "LOCATION")),
+	description: unescapeText(firstProperty(icalData, "DESCRIPTION")),
+});