@remit/web-client 0.0.231 → 0.0.233

package/src/hooks/calendar/selection.ts

@@ -0,0 +1,107 @@
+/**
+ * Which calendars a surface is drawing, and how their occurrences become rows.
+ *
+ * Both readings of the calendar ask this and neither may answer it its own way:
+ * the grid reads one window and the strip reads many, but "which calendars did
+ * the address tick, and what does an occurrence look like once drawn" has one
+ * answer, and a second copy of it drifts into the two surfaces disagreeing
+ * about the same day.
+ */
+import type { RemitImapCalendarEventInstance } from "@remit/api-http-client/types.gen.ts";
+import type {
+	CalendarColorId,
+	CalendarDescriptor,
+	CalendarEventData,
+} from "@remit/ui";
+import { useMemo } from "react";
+import {
+	isDrawnInstance,
+	toCalendarEventData,
+	UNZONED_CALENDAR,
+} from "./instance";
+import { useCalendars } from "./useCalendars";
+
+/**
+ * The calendars a request is asking about. An empty tick list is every
+ * calendar rather than none: a reader who has ticked nothing off is looking at
+ * all of them, and a URL naming a calendar that no longer exists shows the
+ * rest instead of an empty week.
+ */
+export function selectCalendarIds(
+	calendars: readonly CalendarDescriptor[],
+	ticked: readonly string[],
+): string[] {
+	const known = calendars.map((calendar) => calendar.id);
+	if (ticked.length === 0) return known;
+	const wanted = new Set(ticked);
+	const shown = known.filter((id) => wanted.has(id));
+	return shown.length === 0 ? known : shown;
+}
+
+export interface CalendarSelection {
+	calendars: CalendarDescriptor[];
+	colorByCalendarId: Record<string, CalendarColorId>;
+	timeZoneByCalendarId: Record<string, string>;
+	/** Every calendar this address draws, resolved against the real ones. */
+	shown: string[];
+	/** What to ask the server for: empty where that is every calendar. */
+	narrowed: string[];
+	/** False while the tick list still has no real calendars to resolve against. */
+	resolved: boolean;
+	isLoading: boolean;
+}
+
+export function useCalendarSelection(
+	calendarIds: readonly string[],
+): CalendarSelection {
+	const { calendars, colorByCalendarId, timeZoneByCalendarId, isLoading } =
+		useCalendars();
+
+	const shown = selectCalendarIds(calendars, calendarIds);
+	// Asking for every calendar by name and asking for all of them are the same
+	// question, so they are the same cache entry: the address ticking each one
+	// off must not refetch the week the address ticking none already holds.
+	const narrowed = shown.length === calendars.length ? [] : shown;
+	// A tick list can only be resolved against calendars that have loaded, so a
+	// narrowed address waits for them rather than asking about ids it cannot
+	// know are real.
+	const resolved = calendarIds.length === 0 || calendars.length > 0;
+
+	return {
+		calendars,
+		colorByCalendarId,
+		timeZoneByCalendarId,
+		shown,
+		narrowed,
+		resolved,
+		isLoading,
+	};
+}
+
+/**
+ * Occurrences as rows: the ones on a calendar being drawn, on the clock their
+ * collection keeps. A collection with no zone of its own is sent as unzoned
+ * rather than as the reader's — answering with the device's clock would rewrite
+ * every time they saved by the difference between the two.
+ */
+export function useDrawnEvents(
+	instances: readonly RemitImapCalendarEventInstance[],
+	timeZoneByCalendarId: Record<string, string>,
+	shown: readonly string[],
+): CalendarEventData[] {
+	const shownKey = shown.join(",");
+	return useMemo(() => {
+		const drawn = new Set(shownKey === "" ? [] : shownKey.split(","));
+		return instances
+			.filter(
+				(instance) =>
+					isDrawnInstance(instance) && drawn.has(instance.calendarId),
+			)
+			.map((instance) =>
+				toCalendarEventData(
+					instance,
+					timeZoneByCalendarId[instance.calendarId] ?? UNZONED_CALENDAR,
+				),
+			);
+	}, [instances, timeZoneByCalendarId, shownKey]);
+}

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,195 @@
+/**
+ * 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 { useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useMemo } 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.
+ */
+export 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();
+		},
+	};
+}
+
+export interface CalendarEventWeeksResult {
+	instances: RemitImapCalendarEventInstance[];
+	/** Windows whose answer has not arrived, by their `from`. */
+	pendingWindows: Set<string>;
+	/** The first refusal any of them met. Null when they all succeeded. */
+	error: unknown;
+	refetch: () => void;
+}
+
+/**
+ * Several windows at once, each fetched and cached on its own.
+ *
+ * This is what lets a surface hold a range wider than a single read may ask
+ * for: the server refuses a window over a year, and one request that grows
+ * every time the reader reaches an end eventually becomes that window and
+ * replaces what is on screen with a refusal. A week per request has no such
+ * ceiling — reaching an end adds a key rather than widening one — and because
+ * the keys are the grid's own, dropping into the week grid and coming back out
+ * draws from what the strip already fetched, and vice versa.
+ *
+ * Windows already held keep their entries while a new one is in flight, so
+ * nothing on screen is given up to fetch what is beside it.
+ */
+export function useCalendarEventWeeks(
+	windows: readonly CalendarWindow[],
+	calendarIds: readonly string[],
+	enabled: boolean,
+): CalendarEventWeeksResult {
+	const results = useQueries({
+		queries: windows.map((window) => ({
+			...calendarEventOperationsListCalendarEventsOptions(
+				requestOptions({ ...window, calendarIds }),
+			),
+			meta: CALENDAR_READ_META,
+			staleTime: CALENDAR_WINDOW_STALE_TIME,
+			enabled,
+		})),
+	});
+
+	const froms = windows.map((window) => window.from).join("|");
+	const settled = results.map((result) => result.data);
+	const pendingKey = results.map((result) => result.isPending).join("|");
+	const firstError = results.find((result) => result.error)?.error ?? null;
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the joined keys stand for the per-window results, which are a new array every render
+	const instances = useMemo(
+		() => settled.flatMap((data) => data?.items ?? []),
+		[froms, pendingKey],
+	);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: as above
+	const pendingWindows = useMemo(() => {
+		const pending = new Set<string>();
+		windows.forEach((window, index) => {
+			if (results[index]?.isPending) pending.add(window.from);
+		});
+		return pending;
+	}, [froms, pendingKey]);
+
+	return {
+		instances,
+		pendingWindows,
+		error: firstError,
+		refetch: () => {
+			for (const result of results) {
+				if (result.error) result.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/useCalendarFreeBusy.ts

@@ -0,0 +1,80 @@
+/**
+ * Busy time over a window, merged across every calendar the account holds.
+ *
+ * Not the same question as "what is on the strip". A calendar the reader has
+ * unticked still takes their Thursday afternoon, so "am I free" is answered off
+ * this and never off the rows on screen. The server does the merging, so two
+ * overlapping meetings in two calendars are one span here, and an event marked
+ * transparent or cancelled is not one at all.
+ *
+ * The endpoint takes no calendar filter, on purpose: narrowing it would answer
+ * a question nobody asked. It carries the same refusals as the window read — a
+ * window the server will not accept is stated in place, and a lapsed session
+ * escalates rather than being drawn as a clear diary.
+ */
+import { calendarFreeBusyOperationsListCalendarFreeBusyOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapCalendarFreeBusySpan } from "@remit/api-http-client/types.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { softErrorStatuses } from "@/lib/error-classifier";
+import { CALENDAR_WINDOW_STALE_TIME } from "./useCalendarEvents";
+import type { CalendarWindow } from "./window";
+
+const CALENDAR_READ_META = softErrorStatuses(400, 404);
+
+export interface CalendarFreeBusyResult {
+	spans: RemitImapCalendarFreeBusySpan[];
+	/** Windows whose answer has not arrived, by their `from`. */
+	pendingWindows: Set<string>;
+	error: unknown;
+	refetch: () => void;
+}
+
+/**
+ * Busy time a window at a time, for the same reason the events are read that
+ * way: this endpoint refuses a window over a year too, so a range that grows
+ * as the reader scrolls cannot be one request.
+ */
+export function useCalendarFreeBusyWeeks(
+	windows: readonly CalendarWindow[],
+): CalendarFreeBusyResult {
+	const results = useQueries({
+		queries: windows.map((window) => ({
+			...calendarFreeBusyOperationsListCalendarFreeBusyOptions({
+				query: { from: window.from, to: window.to },
+			}),
+			meta: CALENDAR_READ_META,
+			staleTime: CALENDAR_WINDOW_STALE_TIME,
+		})),
+	});
+
+	const froms = windows.map((window) => window.from).join("|");
+	const settled = results.map((result) => result.data);
+	const pendingKey = results.map((result) => result.isPending).join("|");
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the joined keys stand for the per-window results, which are a new array every render
+	const spans = useMemo(
+		() => settled.flatMap((data) => data?.items ?? []),
+		[froms, pendingKey],
+	);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: as above
+	const pendingWindows = useMemo(() => {
+		const pending = new Set<string>();
+		windows.forEach((window, index) => {
+			if (results[index]?.isPending) pending.add(window.from);
+		});
+		return pending;
+	}, [froms, pendingKey]);
+
+	return {
+		spans,
+		pendingWindows,
+		error: results.find((result) => result.error)?.error ?? null,
+		refetch: () => {
+			for (const result of results) {
+				if (result.error) result.refetch();
+			}
+		},
+	};
+}

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