@remit/web-client 0.0.231 → 0.0.232

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")),
+});

package/src/hooks/calendar/useCalendarEvent.ts

@@ -0,0 +1,46 @@
+/**
+ * One stored resource — the bytes behind an event, and the etag a conditional
+ * write is built on.
+ *
+ * The listing carries what a grid chip draws; this carries what an edit needs.
+ * An event opened for editing is read here first, so the `If-Match` a write
+ * sends is the version the reader actually looked at rather than whatever the
+ * grid last cached.
+ */
+import { calendarEventDetailOperationsGetCalendarEventOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapCalendarEventResponse } from "@remit/api-http-client/types.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { softErrorStatuses } from "@/lib/error-classifier";
+
+/** A resource the address names that is no longer there is an empty pane. */
+const RESOURCE_META = softErrorStatuses(404);
+
+export interface CalendarEventResource {
+	resource: RemitImapCalendarEventResponse | undefined;
+	isLoading: boolean;
+	error: unknown;
+	refetch: () => void;
+}
+
+export function useCalendarEvent(
+	calendarObjectId: string,
+	calendarId: string,
+): CalendarEventResource {
+	const { data, isLoading, error, refetch } = useQuery({
+		...calendarEventDetailOperationsGetCalendarEventOptions({
+			path: { calendarObjectId },
+			query: { calendarId },
+		}),
+		meta: RESOURCE_META,
+		enabled: calendarObjectId !== "" && calendarId !== "",
+	});
+
+	return {
+		resource: data,
+		isLoading,
+		error,
+		refetch: () => {
+			refetch();
+		},
+	};
+}

package/src/hooks/calendar/useCalendarEvents.ts

@@ -0,0 +1,124 @@
+/**
+ * Expanded occurrences over a window.
+ *
+ * The server does the expansion, so nothing here reads an RRULE: a week grid
+ * and a day strip draw the same instances because they asked the same question,
+ * not because they each ran the same maths.
+ *
+ * The query is keyed by the window rather than by the day the address names, so
+ * every day inside a week shares one cache entry and stepping back to a week
+ * already read draws from it. The window either side is prefetched, which is
+ * what makes prev and next land on a full calendar instead of a spinner.
+ */
+import { calendarEventOperationsListCalendarEventsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { Options } from "@remit/api-http-client/sdk.gen.ts";
+import type {
+	CalendarEventOperationsListCalendarEventsData,
+	RemitImapCalendarEventInstance,
+} from "@remit/api-http-client/types.gen.ts";
+import type { CalendarViewId } from "@remit/ui";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect } from "react";
+import { stepCalendarDate } from "@/lib/calendar-route";
+import { softErrorStatuses } from "@/lib/error-classifier";
+import { type CalendarWindow, calendarWindow } from "./window";
+
+/**
+ * The refusals this surface answers itself: a window the server will not read,
+ * and a calendar the address names that is no longer there. Everything else —
+ * a lapsed session above all — escalates.
+ */
+const CALENDAR_READ_META = softErrorStatuses(400, 404);
+
+/**
+ * How long a window stays worth reusing.
+ *
+ * Explicit rather than inherited, because prefetching is the whole point: a
+ * warmed week that is already stale by the time the reader steps onto it is
+ * fetched twice and the step waits anyway. Nothing here goes out of date on a
+ * timer — every write invalidates the windows it touched — so this only needs
+ * to outlast the reader moving back and forth across a few weeks.
+ */
+const CALENDAR_WINDOW_STALE_TIME = 5 * 60_000;
+
+export interface CalendarEventWindowRequest extends CalendarWindow {
+	/** Empty asks about every calendar the account holds. */
+	calendarIds: readonly string[];
+	/** False while the tick list is still being resolved against real calendars. */
+	enabled?: boolean;
+}
+
+export interface CalendarEventWindowResult {
+	instances: RemitImapCalendarEventInstance[];
+	isLoading: boolean;
+	/** A refusal this surface renders inline. Null when the read succeeded. */
+	error: unknown;
+	refetch: () => void;
+}
+
+const requestOptions = ({
+	from,
+	to,
+	calendarIds,
+}: CalendarEventWindowRequest): Options<CalendarEventOperationsListCalendarEventsData> => ({
+	query:
+		calendarIds.length === 0
+			? { from, to }
+			: { from, to, calendarId: [...calendarIds] },
+});
+
+/** One window, asked for once however many surfaces are drawing it. */
+export function useCalendarEventWindow(
+	request: CalendarEventWindowRequest,
+): CalendarEventWindowResult {
+	const { data, isLoading, error, refetch } = useQuery({
+		...calendarEventOperationsListCalendarEventsOptions(
+			requestOptions(request),
+		),
+		meta: CALENDAR_READ_META,
+		staleTime: CALENDAR_WINDOW_STALE_TIME,
+		enabled: request.enabled ?? true,
+	});
+
+	return {
+		instances: data?.items ?? [],
+		isLoading,
+		error,
+		refetch: () => {
+			refetch();
+		},
+	};
+}
+
+/**
+ * The windows either side of the one on screen, warmed while the reader is
+ * looking at this one. A step is a navigation, and a navigation that has to
+ * wait for a request reads as the calendar being slow rather than as the week
+ * being fetched.
+ */
+export function usePrefetchAdjacentWindows(
+	view: CalendarViewId,
+	date: string,
+	calendarIds: readonly string[],
+	enabled: boolean,
+): void {
+	const queryClient = useQueryClient();
+	const key = [...calendarIds].join(",");
+
+	useEffect(() => {
+		if (!enabled) return;
+		const ids = key === "" ? [] : key.split(",");
+		for (const direction of [-1, 1] as const) {
+			const neighbour = calendarWindow(
+				view,
+				stepCalendarDate(date, view, direction),
+			);
+			void queryClient.prefetchQuery({
+				...calendarEventOperationsListCalendarEventsOptions(
+					requestOptions({ ...neighbour, calendarIds: ids }),
+				),
+				staleTime: CALENDAR_WINDOW_STALE_TIME,
+			});
+		}
+	}, [queryClient, view, date, key, enabled]);
+}

package/src/hooks/calendar/useCalendarWrites.ts

@@ -0,0 +1,174 @@
+/**
+ * Creating, editing and deleting an event.
+ *
+ * Every write is conditional on the version the reader was looking at. A 412
+ * means somebody replaced the resource in between — over CalDAV, in another
+ * tab, from an accepted invitation — and applying the edit would discard their
+ * change with nobody seeing it happen. That comes back as an outcome the
+ * surface states, never as a write that quietly wins.
+ *
+ * Outcomes are returned rather than thrown: a caught value is `unknown`, and a
+ * surface that has to switch on one cannot tell a refusal it must render from a
+ * fault it must not swallow. Faults still escalate — these carry only the
+ * statuses this surface owns, so a lapsed session takes the screen the way it
+ * does everywhere else.
+ */
+import {
+	calendarEventDetailOperationsDeleteCalendarEventMutation,
+	calendarEventDetailOperationsUpdateCalendarEventMutation,
+	calendarEventOperationsCreateCalendarEventMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapCreateCalendarEventInput,
+	RemitImapRecurrenceScope,
+	RemitImapUpdateCalendarEventInput,
+} from "@remit/api-http-client/types.gen.ts";
+import type { RecurrenceScope } from "@remit/ui";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { formatErrorMessage } from "@/components/ui/ErrorState";
+import { getErrorStatus, softErrorStatuses } from "@/lib/error-classifier";
+
+/** The refusals a calendar surface renders itself. A 401 is not among them. */
+const CALENDAR_WRITE_META = softErrorStatuses(400, 404, 412);
+
+/** Every read whose answer a write can change. */
+const CALENDAR_QUERY_IDS = new Set([
+	"calendarEventOperationsListCalendarEvents",
+	"calendarEventDetailOperationsGetCalendarEvent",
+	"calendarFreeBusyOperationsListCalendarFreeBusy",
+]);
+
+export type CalendarWriteOutcome =
+	| { kind: "written" }
+	| { kind: "conflict" }
+	| { kind: "refused"; message: string };
+
+const WRITTEN: CalendarWriteOutcome = { kind: "written" };
+
+const outcomeFor = (error: unknown): CalendarWriteOutcome =>
+	getErrorStatus(error) === 412
+		? { kind: "conflict" }
+		: { kind: "refused", message: formatErrorMessage(error) };
+
+const SCOPES: Record<RecurrenceScope, RemitImapRecurrenceScope> = {
+	this: "This",
+	following: "Following",
+	all: "All",
+};
+
+export interface ScopedWrite {
+	calendarObjectId: string;
+	calendarId: string;
+	/** The occurrence the reader clicked. `""` on a resource that does not recur. */
+	recurrenceId: string;
+	/** Absent on a resource that does not recur — the server defaults to `All`. */
+	scope?: RecurrenceScope;
+	/** The version the edit was built on. */
+	etag: string;
+}
+
+export interface CalendarWrites {
+	createEvent: (
+		input: RemitImapCreateCalendarEventInput,
+	) => Promise<CalendarWriteOutcome>;
+	updateEvent: (
+		write: ScopedWrite,
+		patch: RemitImapUpdateCalendarEventInput,
+	) => Promise<CalendarWriteOutcome>;
+	deleteEvent: (write: ScopedWrite) => Promise<CalendarWriteOutcome>;
+	isWriting: boolean;
+}
+
+/** Everything a write invalidates: the windows, the resource, the busy spans. */
+export function useInvalidateCalendarReads(): () => void {
+	const queryClient = useQueryClient();
+	return useCallback(() => {
+		void queryClient.invalidateQueries({
+			predicate: (query) => {
+				const head = query.queryKey[0];
+				if (typeof head !== "object" || head === null) return false;
+				const id = (head as { _id?: unknown })._id;
+				return typeof id === "string" && CALENDAR_QUERY_IDS.has(id);
+			},
+		});
+	}, [queryClient]);
+}
+
+const scopeQuery = ({ scope, recurrenceId }: ScopedWrite) =>
+	scope === undefined || scope === "all"
+		? {}
+		: { scope: SCOPES[scope], recurrenceId };
+
+export function useCalendarWrites(): CalendarWrites {
+	const invalidate = useInvalidateCalendarReads();
+
+	const create = useMutation({
+		...calendarEventOperationsCreateCalendarEventMutation(),
+		meta: CALENDAR_WRITE_META,
+		onSuccess: invalidate,
+	});
+	const update = useMutation({
+		...calendarEventDetailOperationsUpdateCalendarEventMutation(),
+		meta: CALENDAR_WRITE_META,
+		onSuccess: invalidate,
+	});
+	const remove = useMutation({
+		...calendarEventDetailOperationsDeleteCalendarEventMutation(),
+		meta: CALENDAR_WRITE_META,
+		onSuccess: invalidate,
+	});
+
+	const createEvent = useCallback(
+		(input: RemitImapCreateCalendarEventInput) =>
+			create
+				.mutateAsync({ body: input })
+				.then(() => WRITTEN)
+				.catch(outcomeFor),
+		[create],
+	);
+
+	const updateEvent = useCallback(
+		(write: ScopedWrite, patch: RemitImapUpdateCalendarEventInput) =>
+			update
+				.mutateAsync({
+					path: { calendarObjectId: write.calendarObjectId },
+					query: { calendarId: write.calendarId, ...scopeQuery(write) },
+					headers: { "If-Match": write.etag },
+					body: patch,
+				})
+				.then(() => WRITTEN)
+				.catch(outcomeFor),
+		[update],
+	);
+
+	const deleteEvent = useCallback(
+		(write: ScopedWrite) =>
+			remove
+				.mutateAsync({
+					path: { calendarObjectId: write.calendarObjectId },
+					query: { calendarId: write.calendarId, ...scopeQuery(write) },
+					headers: { "If-Match": write.etag },
+				})
+				.then(() => WRITTEN)
+				.catch(outcomeFor),
+		[remove],
+	);
+
+	return useMemo(
+		() => ({
+			createEvent,
+			updateEvent,
+			deleteEvent,
+			isWriting: create.isPending || update.isPending || remove.isPending,
+		}),
+		[
+			createEvent,
+			updateEvent,
+			deleteEvent,
+			create.isPending,
+			update.isPending,
+			remove.isPending,
+		],
+	);
+}

package/src/hooks/calendar/useCalendars.ts

@@ -0,0 +1,43 @@
+/**
+ * The calendars the account holds.
+ *
+ * The listing provisions a default collection on first read, so this never
+ * comes back empty for a working account and no surface has to know how a
+ * calendar gets made. It carries no `softError` meta: a session that has lapsed
+ * escalates to the signed-out state rather than drawing an empty week, which is
+ * indistinguishable from a week with nothing in it.
+ */
+import { calendarOperationsListCalendarsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { CalendarColorId, CalendarDescriptor } from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { toCalendarDescriptor } from "./instance";
+
+export interface CalendarsResult {
+	calendars: CalendarDescriptor[];
+	colorByCalendarId: Record<string, CalendarColorId>;
+	/** The zone each collection's floating times are read in. */
+	timeZoneByCalendarId: Record<string, string>;
+	isLoading: boolean;
+}
+
+export function useCalendars(): CalendarsResult {
+	const { data, isLoading } = useQuery(
+		calendarOperationsListCalendarsOptions(),
+	);
+
+	return useMemo(() => {
+		const items = data?.items ?? [];
+		const calendars = items.map(toCalendarDescriptor);
+		return {
+			calendars,
+			colorByCalendarId: Object.fromEntries(
+				calendars.map((calendar) => [calendar.id, calendar.color]),
+			),
+			timeZoneByCalendarId: Object.fromEntries(
+				items.map((item) => [item.calendarId, item.timezone]),
+			),
+			isLoading,
+		};
+	}, [data, isLoading]);
+}