@remit/web-client 0.0.302 → 0.0.303

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.302",
+  "version": "0.0.303",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/calendar/CalendarEventPane.stories.tsx

@@ -104,6 +104,57 @@ export const NotOnThisWeek: Story = {
 	args: { event: undefined, calendar: undefined },
 };
 
+/** Looking for the day an event the view does not hold falls on. */
+export const Finding: Story = {
+	args: { event: undefined, calendar: undefined, absence: { kind: "Finding" } },
+};
+
+/** The address names a resource none of the reader's calendars holds. */
+export const Deleted: Story = {
+	args: { event: undefined, calendar: undefined, absence: { kind: "Deleted" } },
+};
+
+/** A series that falls on no day in its first year or the coming one. */
+export const NoOccurrenceFound: Story = {
+	args: {
+		event: undefined,
+		calendar: undefined,
+		absence: { kind: "NoOccurrenceFound" },
+	},
+};
+
+/** The session ended during the look-up; the way back in is on the pane. */
+export const SignedOut: Story = {
+	args: {
+		event: undefined,
+		calendar: undefined,
+		absence: {
+			kind: "SignedOut",
+			signIn: (
+				<button
+					type="button"
+					className="rounded-md border border-line px-2.5 py-1 text-sm font-medium text-fg"
+				>
+					Sign in again
+				</button>
+			),
+		},
+	},
+};
+
+/** The look-up failed, with the server's reason and a way to report it. */
+export const LookupFailed: Story = {
+	args: {
+		event: undefined,
+		calendar: undefined,
+		absence: {
+			kind: "Failed",
+			reason: "Internal server error (HTTP 500)",
+			reportHref: "https://github.com/remit-mail/reader/issues/new",
+		},
+	},
+};
+
 /**
  * The event was replaced somewhere else — over CalDAV, or in another tab —
  * between it being read and the write going out. Nothing was overwritten, and

package/src/components/calendar/CalendarEventPane.tsx

@@ -1,8 +1,61 @@
 import type { CalendarDescriptor, CalendarEventData } from "@remit/ui";
 import { EventDetail } from "@remit/ui";
 import { AlertCircle, CalendarDays } from "lucide-react";
+import type { ReactNode } from "react";
 import { formatEventWhen } from "@/lib/calendar-format";
 
+export type CalendarEventAbsence =
+	| { kind: "NotInView" }
+	| { kind: "Finding" }
+	| { kind: "Deleted" }
+	| { kind: "NoOccurrenceFound" }
+	| { kind: "SignedOut"; signIn: ReactNode }
+	| { kind: "Failed"; reason: string; reportHref: string };
+
+const NOT_IN_VIEW: CalendarEventAbsence = { kind: "NotInView" };
+
+const LINK =
+	"rounded-md border border-line px-2.5 py-1 text-sm font-medium text-fg outline-none hover:bg-surface-sunken focus-visible:ring-2 focus-visible:ring-ring";
+
+function absenceText(absence: CalendarEventAbsence): {
+	title: string;
+	detail: string;
+} {
+	switch (absence.kind) {
+		case "Finding":
+			return {
+				title: "Finding the event",
+				detail: "Looking for the day it falls on.",
+			};
+		case "Deleted":
+			return {
+				title: "This event was deleted",
+				detail: "None of your calendars holds it any more.",
+			};
+		case "NoOccurrenceFound":
+			return {
+				title: "No occurrence in its first year or the coming year",
+				detail:
+					"Its repeat rule, or the days taken out of it, leave it no day in either.",
+			};
+		case "SignedOut":
+			return {
+				title: "Your session has ended",
+				detail: "Sign in again to open this event.",
+			};
+		case "Failed":
+			return {
+				title: "The event couldn't be looked up",
+				detail: absence.reason,
+			};
+		case "NotInView":
+			return {
+				title: "That event isn't on this week",
+				detail: "The address names an event the calendar doesn't have here.",
+			};
+	}
+}
+
 /**
  * The event the address has open.
  *
@@ -17,6 +70,7 @@ export interface CalendarEventPaneProps {
 	calendar: CalendarDescriptor | undefined;
 	/** Whether the address names one occurrence rather than the series. */
 	isOccurrence: boolean;
+	absence?: CalendarEventAbsence;
 	/**
 	 * A write that did not happen, stated where the reader is looking. Empty
 	 * when the last one did.
@@ -31,28 +85,39 @@ export function CalendarEventPane({
 	event,
 	calendar,
 	isOccurrence,
+	absence = NOT_IN_VIEW,
 	problem = "",
 	onEdit,
 	onDelete,
 	onClose,
 }: CalendarEventPaneProps) {
 	if (!event || !calendar) {
+		const { title, detail } = absenceText(absence);
+		const loud = absence.kind === "Failed" || absence.kind === "SignedOut";
 		return (
-			<div className="flex h-full flex-col items-center justify-center gap-2 bg-surface p-8 text-center">
+			<div
+				role={loud ? "alert" : undefined}
+				className="flex h-full flex-col items-center justify-center gap-2 bg-surface p-8 text-center"
+			>
 				<CalendarDays className="size-8 text-fg-subtle" aria-hidden="true" />
-				<p className="text-sm font-medium text-fg">
-					That event isn't on this week
-				</p>
-				<p className="max-w-xs text-sm text-fg-muted">
-					The address names an event the calendar doesn't have here.
-				</p>
-				<button
-					type="button"
-					onClick={onClose}
-					className="rounded-md border border-line px-2.5 py-1 text-sm font-medium text-fg outline-none hover:bg-surface-sunken focus-visible:ring-2 focus-visible:ring-ring"
-				>
-					Back to the calendar
-				</button>
+				<p className="text-sm font-medium text-fg">{title}</p>
+				<p className="max-w-xs break-words text-sm text-fg-muted">{detail}</p>
+				<div className="flex flex-wrap items-center justify-center gap-2">
+					{absence.kind === "SignedOut" && absence.signIn}
+					{absence.kind === "Failed" && (
+						<a
+							href={absence.reportHref}
+							target="_blank"
+							rel="noreferrer"
+							className={LINK}
+						>
+							Report an issue
+						</a>
+					)}
+					<button type="button" onClick={onClose} className={LINK}>
+						Back to the calendar
+					</button>
+				</div>
 			</div>
 		);
 	}

package/src/components/calendar/OpenCalendarEvent.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, userEvent, within } from "storybook/test";
+import { useOpenCalendarEvent } from "@/routing";
 import {
 	calendars,
 	fortnight,
@@ -44,6 +45,17 @@ const answering = (
 	};
 };
 
+/** The pane with its props read off the address, as the app's routes hand them. */
+function FromAddress() {
+	const opened = useOpenCalendarEvent();
+	return (
+		<OpenCalendarEvent
+			calendarObjectId={opened?.calendarObjectId ?? ""}
+			recurrenceId={opened?.recurrenceId}
+		/>
+	);
+}
+
 function Opened({
 	calendarObjectId,
 	recurrenceId,
@@ -59,16 +71,7 @@ function Opened({
 			: `${STORY_WEEK}/${calendarObjectId}/${recurrenceId}`;
 	return (
 		<div className="h-dvh max-w-xl border-l border-line bg-canvas">
-			<CalendarStory
-				entry={address}
-				server={server}
-				pane={
-					<OpenCalendarEvent
-						calendarObjectId={calendarObjectId}
-						recurrenceId={recurrenceId}
-					/>
-				}
-			/>
+			<CalendarStory entry={address} server={server} pane={<FromAddress />} />
 		</div>
 	);
 }
@@ -130,6 +133,121 @@ export const RecurringScopePrompt: Story = {
 	},
 };
 
+/**
+ * A series opened by its plain address lands on an occurrence, so an edit asks
+ * which occurrences it means exactly as it does from one.
+ */
+export const SeriesFromItsPlainAddress: Story = {
+	args: { calendarObjectId: STANDUP_OBJECT },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("One occurrence of a repeating event"),
+		).toBeVisible();
+		await userEvent.click(await canvas.findByRole("button", { name: "Edit" }));
+		await expect(
+			await canvas.findByRole("button", { name: /The whole series/ }),
+		).toBeVisible();
+	},
+};
+
+/** A series that no longer falls on any day says so instead of drawing nothing. */
+export const SeriesWithNoOccurrences: Story = {
+	args: {
+		calendarObjectId: STANDUP_OBJECT,
+		server: answering((request) =>
+			new URL(request.url).pathname.endsWith("/calendar-events")
+				? json({ items: [] })
+				: undefined,
+		),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText(
+				"No occurrence in its first year or the coming year",
+			),
+		).toBeVisible();
+	},
+};
+
+/**
+ * A week the standup is not on, and the look-up for it answered by `lookUp`:
+ * the listing for the one resource, and the resource read with no calendar.
+ */
+const lookingUp =
+	(lookUp: (url: URL) => Response): CalendarServer =>
+	(request) => {
+		const url = new URL(request.url);
+		if (url.searchParams.has("calendarObjectId")) return lookUp(url);
+		if (url.pathname.endsWith("/calendar-events"))
+			return json({
+				items: instancesWithin(
+					url,
+					fortnight.filter(
+						(instance) => instance.calendarObjectId !== STANDUP_OBJECT,
+					),
+				),
+			});
+		if (
+			url.pathname.includes(STANDUP_OBJECT) &&
+			!url.searchParams.has("calendarId")
+		)
+			return lookUp(url);
+		return answering()(request);
+	};
+
+/** A resource none of the reader's calendars holds any more. */
+export const SeriesDeleted: Story = {
+	args: {
+		calendarObjectId: STANDUP_OBJECT,
+		server: lookingUp((url) =>
+			url.pathname.endsWith("/calendar-events")
+				? json({ items: [] })
+				: json({ message: "no event on this account" }, 404),
+		),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("This event was deleted"),
+		).toBeVisible();
+	},
+};
+
+/** A failed look-up says why and offers a report, never "not on this week". */
+export const LookupFailed: Story = {
+	args: {
+		calendarObjectId: STANDUP_OBJECT,
+		server: lookingUp(() =>
+			json({ message: "The calendar store is unavailable." }, 500),
+		),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("The event couldn't be looked up"),
+		).toBeVisible();
+		await expect(
+			canvas.getByRole("link", { name: "Report an issue" }),
+		).toBeVisible();
+	},
+};
+
+/** A session that ended during the look-up is said as such. */
+export const SignedOutDuringLookup: Story = {
+	args: {
+		calendarObjectId: STANDUP_OBJECT,
+		server: lookingUp(() => json({ message: "Session expired." }, 401)),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("Your session has ended"),
+		).toBeVisible();
+	},
+};
+
 /**
  * Somebody replaced the event between it being read and the delete going out —
  * over CalDAV, or in another tab. Nothing was removed, and the pane says so

package/src/components/calendar/OpenCalendarEvent.tsx

@@ -3,10 +3,16 @@ import {
 	type RecurrenceScope,
 	RecurrenceScopePrompt,
 } from "@remit/ui";
+import { Navigate } from "@tanstack/react-router";
 import { useState } from "react";
+import { useAuthProvider } from "@/auth/provider";
 import { CalendarComposePane } from "@/components/calendar/CalendarComposePane";
-import { CalendarEventPane } from "@/components/calendar/CalendarEventPane";
 import {
+	type CalendarEventAbsence,
+	CalendarEventPane,
+} from "@/components/calendar/CalendarEventPane";
+import {
+	type CalendarJumpSearch,
 	type CalendarWriteOutcome,
 	calendarInstanceId,
 	deviceTimeZone,
@@ -17,17 +23,21 @@ import {
 	patchFromDrafts,
 	rruleFromIcalData,
 	type ScopedWrite,
+	seriesOccurrenceOf,
 	storedAnchorZone,
 	textFromIcalData,
 	textFromRrule,
 	UNZONED_CALENDAR,
 	useCalendarEvent,
+	useCalendarJump,
 	useCalendars,
 	useCalendarWrites,
 	useDraftClashes,
 } from "@/hooks/calendar";
 import { useCalendarData } from "@/hooks/useCalendarData";
 import { formatEventWhen } from "@/lib/calendar-format";
+import { calendarEventReportHref } from "@/lib/calendar-report";
+import type { CalendarSearch } from "@/lib/calendar-route";
 import { useCalendarAddress, useCalendarNavigation } from "@/routing";
 
 /**
@@ -55,12 +65,54 @@ const CONFLICT =
 
 type Intent = "edit" | "delete";
 
+function SignInAgain() {
+	const { Account } = useAuthProvider();
+	return (
+		<Account>
+			{({ signOut }) => (
+				<button
+					type="button"
+					onClick={() => signOut()}
+					className="rounded-md border border-line px-2.5 py-1 text-sm font-medium text-fg outline-none hover:bg-surface-sunken focus-visible:ring-2 focus-visible:ring-ring"
+				>
+					Sign in again
+				</button>
+			)}
+		</Account>
+	);
+}
+
+const absenceOf = (
+	search: CalendarJumpSearch,
+	loading: boolean,
+): CalendarEventAbsence => {
+	switch (search.kind) {
+		case "Deleted":
+		case "NoOccurrenceFound":
+			return { kind: search.kind };
+		case "SignedOut":
+			return { kind: "SignedOut", signIn: <SignInAgain /> };
+		case "Failed":
+			return {
+				kind: "Failed",
+				reason: search.reason,
+				reportHref: calendarEventReportHref(
+					`opening an event failed: ${search.reason}`,
+				),
+			};
+		case "Searching":
+			return { kind: "Finding" };
+		default:
+			return { kind: loading ? "Finding" : "NotInView" };
+	}
+};
+
 export function OpenCalendarEvent({
 	calendarObjectId,
 	recurrenceId,
 }: OpenCalendarEventProps) {
 	const { view, date, calendarIds } = useCalendarAddress();
-	const { events } = useCalendarData({ view, date, calendarIds });
+	const { events, isLoading } = useCalendarData({ view, date, calendarIds });
 	const { calendars, timeZoneByCalendarId } = useCalendars();
 	const { closeEvent } = useCalendarNavigation();
 	const { updateEvent, deleteEvent, isWriting } = useCalendarWrites();
@@ -69,6 +121,14 @@ export function OpenCalendarEvent({
 		(candidate) =>
 			candidate.id === calendarInstanceId(calendarObjectId, recurrenceId ?? ""),
 	);
+	const seriesOnly = recurrenceId === undefined && event === undefined;
+	const occurrence = seriesOnly
+		? seriesOccurrenceOf(events, calendarObjectId, new Date().toISOString())
+		: undefined;
+	const search = useCalendarJump(
+		calendarObjectId,
+		seriesOnly && !isLoading && occurrence === undefined,
+	);
 	const calendar = calendars.find(
 		(candidate) => candidate.id === event?.calendarId,
 	);
@@ -175,6 +235,59 @@ export function OpenCalendarEvent({
 		);
 	};
 
+	if (occurrence) {
+		return (
+			<Navigate
+				to="/calendar/$view/$date/$calendarObjectId/$recurrenceId"
+				params={{
+					view,
+					date,
+					calendarObjectId,
+					recurrenceId: occurrence.recurrenceId,
+				}}
+				search={true}
+				hash={true}
+				replace
+			/>
+		);
+	}
+
+	const jump = search.kind === "Found" ? search.jump : undefined;
+	const hidden =
+		jump !== undefined &&
+		calendarIds.length > 0 &&
+		!calendarIds.includes(jump.calendarId);
+	if (jump && (jump.date !== date || hidden)) {
+		const shown = hidden
+			? (previous: CalendarSearch) => ({
+					...previous,
+					calendarId: [...calendarIds, jump.calendarId],
+				})
+			: true;
+		return jump.recurrenceId === "" ? (
+			<Navigate
+				to="/calendar/$view/$date/$calendarObjectId"
+				params={{ view, date: jump.date, calendarObjectId }}
+				search={shown}
+				hash={true}
+				replace
+			/>
+		) : (
+			<Navigate
+				to="/calendar/$view/$date/$calendarObjectId/$recurrenceId"
+				params={{
+					view,
+					date: jump.date,
+					calendarObjectId,
+					recurrenceId: jump.recurrenceId,
+				}}
+				search={shown}
+				hash={true}
+				replace
+			/>
+		);
+	}
+
 	if (asking !== undefined && event) {
 		return (
 			<div className="flex h-full flex-col justify-center bg-surface px-row-inset">
@@ -228,6 +341,7 @@ export function OpenCalendarEvent({
 			}
 			calendar={calendar}
 			isOccurrence={recurrenceId !== undefined}
+			absence={absenceOf(search, seriesOnly && isLoading)}
 			problem={problem}
 			onEdit={
 				writable

package/src/components/calendar/calendar-story-fixtures.ts

@@ -106,6 +106,7 @@ export const standupResource = {
 	calendarObjectId: STANDUP_OBJECT,
 	resourceName: "standup.ics",
 	icalUid: "uid-standup",
+	dtStart: "2026-06-10T09:15:00+02:00",
 	icalData: [
 		"BEGIN:VCALENDAR",
 		"BEGIN:VEVENT",

package/src/hooks/calendar/index.ts

@@ -39,10 +39,13 @@ export {
 export {
 	anchorZoneFor,
 	type CalendarInstanceRef,
+	type CalendarJump,
 	calendarInstanceId,
+	calendarJumpOf,
 	deviceTimeZone,
 	isDrawnInstance,
 	readCalendarInstanceId,
+	seriesOccurrenceOf,
 	toCalendarDescriptor,
 	toCalendarEventData,
 	UNZONED_CALENDAR,
@@ -82,6 +85,7 @@ export {
 	type CalendarFreeBusyResult,
 	useCalendarFreeBusyWeeks,
 } from "./useCalendarFreeBusy";
+export { type CalendarJumpSearch, useCalendarJump } from "./useCalendarJump";
 export {
 	type CalendarSuggestionAnswers,
 	type CalendarSuggestionsResult,

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

@@ -2,7 +2,12 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import type { RemitImapCalendarEventInstance } from "@remit/api-http-client/types.gen.ts";
-import { anchorZoneFor, toCalendarEventData } from "./instance";
+import {
+	anchorZoneFor,
+	calendarJumpOf,
+	seriesOccurrenceOf,
+	toCalendarEventData,
+} from "./instance";
 
 const instance = (
 	over: Partial<RemitImapCalendarEventInstance>,
@@ -68,3 +73,134 @@ describe("the zone a write anchors an event in", () => {
 		}
 	});
 });
+
+describe("the occurrence a series opens at from its plain address", () => {
+	const weekly = ["06", "13", "20"].map((day) =>
+		toCalendarEventData(
+			instance({
+				recurrenceId: `203403${day}T090000Z`,
+				hasRecurrence: true,
+				allDay: false,
+				start: `2034-03-${day}T09:00:00+00:00`,
+				end: `2034-03-${day}T10:00:00+00:00`,
+			}),
+			"UTC",
+			"UTC",
+		),
+	);
+	const shuffled = [...weekly].reverse();
+
+	it("is the next one still to finish", () => {
+		assert.deepEqual(
+			seriesOccurrenceOf(shuffled, "obj_1", "2034-03-13T09:30:00Z"),
+			{ calendarObjectId: "obj_1", recurrenceId: "20340313T090000Z" },
+		);
+	});
+
+	it("is the first in the window once every one has passed", () => {
+		assert.deepEqual(
+			seriesOccurrenceOf(shuffled, "obj_1", "2034-04-01T00:00:00Z"),
+			{ calendarObjectId: "obj_1", recurrenceId: "20340306T090000Z" },
+		);
+	});
+
+	it("is nothing for an event that does not recur or is not in the window", () => {
+		const oneOff = toCalendarEventData(
+			instance({ calendarObjectId: "obj_2" }),
+			"UTC",
+			"UTC",
+		);
+		assert.equal(
+			seriesOccurrenceOf(
+				[oneOff, ...shuffled],
+				"obj_2",
+				"2034-03-01T00:00:00Z",
+			),
+			undefined,
+		);
+		assert.equal(
+			seriesOccurrenceOf(shuffled, "obj_3", "2034-03-01T00:00:00Z"),
+			undefined,
+		);
+	});
+});
+
+describe("the day a view moves to for an event it does not hold", () => {
+	const weekly = ["06", "13", "20"].map((day) =>
+		instance({
+			recurrenceId: `2034-03-${day}T01:00:00Z`,
+			hasRecurrence: true,
+			allDay: false,
+			start: `2034-03-${day}T01:00:00+00:00`,
+			end: `2034-03-${day}T02:00:00+00:00`,
+		}),
+	);
+	const shuffled = [...weekly].reverse();
+
+	it("is the day of the next occurrence still to finish, on the device's clock", () => {
+		assert.deepEqual(
+			calendarJumpOf(
+				shuffled,
+				"obj_1",
+				"2034-03-10T00:00:00Z",
+				"America/New_York",
+			),
+			{
+				calendarObjectId: "obj_1",
+				recurrenceId: "2034-03-13T01:00:00Z",
+				calendarId: "cal_work",
+				date: "2034-03-12",
+			},
+		);
+	});
+
+	it("is the day of the first occurrence once every one has passed", () => {
+		assert.deepEqual(
+			calendarJumpOf(shuffled, "obj_1", "2035-01-01T00:00:00Z", "UTC"),
+			{
+				calendarObjectId: "obj_1",
+				recurrenceId: "2034-03-06T01:00:00Z",
+				calendarId: "cal_work",
+				date: "2034-03-06",
+			},
+		);
+	});
+
+	it("skips a cancelled occurrence", () => {
+		const [first, ...rest] = weekly;
+		if (!first) throw new Error("no first occurrence");
+		assert.equal(
+			calendarJumpOf(
+				[{ ...first, status: "Cancelled" }, ...rest],
+				"obj_1",
+				"2034-03-01T00:00:00Z",
+				"UTC",
+			)?.date,
+			"2034-03-13",
+		);
+	});
+
+	it("keeps a one-off event unaddressed by an occurrence", () => {
+		assert.deepEqual(
+			calendarJumpOf(
+				[instance({ calendarObjectId: "obj_2" })],
+				"obj_2",
+				"2034-01-01T00:00:00Z",
+				"Pacific/Pago_Pago",
+			),
+			{
+				calendarObjectId: "obj_2",
+				recurrenceId: "",
+				calendarId: "cal_work",
+				date: "2034-03-01",
+			},
+		);
+	});
+
+	it("is nothing when the series has no occurrence", () => {
+		assert.equal(
+			calendarJumpOf(shuffled, "obj_3", "2034-03-01T00:00:00Z", "UTC"),
+			undefined,
+		);
+	});
+});

package/src/hooks/calendar/instance.ts

@@ -86,6 +86,74 @@ export function readCalendarInstanceId(id: string): CalendarInstanceRef {
 	};
 }
 
+const nextOrFirst = (
+	events: readonly CalendarEventData[],
+	now: string,
+): CalendarEventData | undefined => {
+	const ordered = [...events].sort(
+		(a, b) => Date.parse(a.start) - Date.parse(b.start),
+	);
+	return (
+		ordered.find((event) => Date.parse(event.end) > Date.parse(now)) ??
+		ordered[0]
+	);
+};
+
+/**
+ * The occurrence a series opens at when the address names only the series: the
+ * next one still to finish, or the first in the window where none is left.
+ */
+export function seriesOccurrenceOf(
+	events: readonly CalendarEventData[],
+	calendarObjectId: string,
+	now: string,
+): CalendarInstanceRef | undefined {
+	const picked = nextOrFirst(
+		events.filter((event) => {
+			const ref = readCalendarInstanceId(event.id);
+			return (
+				ref.calendarObjectId === calendarObjectId && ref.recurrenceId !== ""
+			);
+		}),
+		now,
+	);
+	return picked ? readCalendarInstanceId(picked.id) : undefined;
+}
+
+export interface CalendarJump extends CalendarInstanceRef {
+	calendarId: string;
+	/** On the clock the calendar is drawn in. */
+	date: string;
+}
+
+/**
+ * Where a view has to move to show an event it does not hold: the day of its
+ * next occurrence still to finish, or of its first where none is left.
+ */
+export function calendarJumpOf(
+	instances: readonly RemitImapCalendarEventInstance[],
+	calendarObjectId: string,
+	now: string,
+	clockZone: string,
+): CalendarJump | undefined {
+	const picked = nextOrFirst(
+		instances
+			.filter(
+				(instance) =>
+					instance.calendarObjectId === calendarObjectId &&
+					isDrawnInstance(instance),
+			)
+			.map((instance) => toCalendarEventData(instance, "", clockZone)),
+		now,
+	);
+	if (!picked) return undefined;
+	return {
+		...readCalendarInstanceId(picked.id),
+		calendarId: picked.calendarId,
+		date: picked.start.slice(0, 10),
+	};
+}
+
 export function toCalendarDescriptor(
 	calendar: RemitImapCalendarResponse,
 ): CalendarDescriptor {

package/src/hooks/calendar/useCalendarJump.ts

@@ -0,0 +1,117 @@
+import {
+	calendarEventDetailOperationsGetCalendarEventOptions,
+	calendarEventOperationsListCalendarEventsOptions,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { getErrorStatus, softErrorStatuses } from "@/lib/error-classifier";
+import { type CalendarJump, calendarJumpOf, deviceTimeZone } from "./instance";
+
+export type CalendarJumpSearch =
+	| { kind: "Idle" }
+	| { kind: "Searching" }
+	| { kind: "Found"; jump: CalendarJump }
+	| { kind: "Deleted" }
+	| { kind: "NoOccurrenceFound" }
+	| { kind: "SignedOut" }
+	| { kind: "Failed"; reason: string };
+
+const WINDOW_MS = 365 * 24 * 60 * 60_000;
+const DAY_MS = 24 * 60 * 60_000;
+
+const LISTING_META = softErrorStatuses(401);
+const RESOURCE_META = softErrorStatuses(401, 404);
+
+const instant = (ms: number): string =>
+	new Date(ms).toISOString().replace(/\.\d{3}Z$/, "+00:00");
+
+const reasonOf = (error: unknown): string => {
+	const message =
+		error instanceof Error && error.message !== ""
+			? error.message
+			: "no reason given";
+	const status = getErrorStatus(error);
+	return status === undefined ? message : `${message} (HTTP ${status})`;
+};
+
+/**
+ * Finds the day an event falls on when the view on screen does not hold it:
+ * its occurrences in the coming year first, and failing those, the year from
+ * the resource's own start — so an event that has ended opens at its first.
+ */
+export function useCalendarJump(
+	calendarObjectId: string,
+	enabled: boolean,
+): CalendarJumpSearch {
+	const [now] = useState(() => Date.now());
+	const clock = deviceTimeZone();
+	const nowIso = new Date(now).toISOString();
+
+	const ahead = useQuery({
+		...calendarEventOperationsListCalendarEventsOptions({
+			query: {
+				from: instant(now),
+				to: instant(now + WINDOW_MS),
+				calendarObjectId,
+			},
+		}),
+		meta: LISTING_META,
+		retry: false,
+		enabled,
+	});
+	const upcoming = ahead.data
+		? calendarJumpOf(ahead.data.items, calendarObjectId, nowIso, clock)
+		: undefined;
+
+	const lookup = useQuery({
+		...calendarEventDetailOperationsGetCalendarEventOptions({
+			path: { calendarObjectId },
+		}),
+		meta: RESOURCE_META,
+		retry: false,
+		enabled: enabled && ahead.data !== undefined && upcoming === undefined,
+	});
+
+	const started = Date.parse(lookup.data?.dtStart ?? "");
+	const unreadableStart = lookup.data !== undefined && Number.isNaN(started);
+	const firstFrom = Number.isNaN(started) ? 0 : started - DAY_MS;
+	const first = useQuery({
+		...calendarEventOperationsListCalendarEventsOptions({
+			query: {
+				from: instant(firstFrom),
+				to: instant(firstFrom + WINDOW_MS),
+				calendarObjectId,
+			},
+		}),
+		meta: LISTING_META,
+		retry: false,
+		enabled: enabled && lookup.data !== undefined && !unreadableStart,
+	});
+	const earliest = first.data
+		? calendarJumpOf(first.data.items, calendarObjectId, nowIso, clock)
+		: undefined;
+
+	if (!enabled) return { kind: "Idle" };
+	if (upcoming) return { kind: "Found", jump: upcoming };
+	if (earliest) return { kind: "Found", jump: earliest };
+
+	const deleted = getErrorStatus(lookup.error) === 404;
+	const failure = [
+		ahead.error,
+		deleted ? null : lookup.error,
+		first.error,
+	].find((error) => error !== null);
+	if (failure !== undefined) {
+		return getErrorStatus(failure) === 401
+			? { kind: "SignedOut" }
+			: { kind: "Failed", reason: reasonOf(failure) };
+	}
+	if (deleted) return { kind: "Deleted" };
+	if (unreadableStart)
+		return {
+			kind: "Failed",
+			reason: `the stored event names no readable start (${lookup.data?.dtStart ?? ""})`,
+		};
+	if (first.data !== undefined) return { kind: "NoOccurrenceFound" };
+	return { kind: "Searching" };
+}

package/src/lib/calendar-report.ts

@@ -9,3 +9,13 @@ export function calendarReportHref(what: string): string {
 		}),
 	);
 }
+
+/** A prefilled issue for an event the calendar could not look up. */
+export function calendarEventReportHref(what: string): string {
+	return buildGitHubIssueUrl(
+		buildBugReportContext({
+			title: `Calendar event: ${what}`,
+			errorMessage: what,
+		}),
+	);
+}

package/src/lib/calendar-route.ts

@@ -193,3 +193,5 @@ export const calendarSearchSchema = z.object({
 		.preprocess(readCalendarIds, z.array(calendarIdSchema))
 		.transform((ids) => (ids.length === 0 ? undefined : ids)),
 });
+
+export type CalendarSearch = z.infer<typeof calendarSearchSchema>;