@remit/web-client 0.0.230 → 0.0.231

package/src/routes/calendar/$view.$date.tsx

@@ -0,0 +1,100 @@
+// biome-ignore lint/style/useFilenamingConvention: TanStack Router convention
+/**
+ * /calendar/{view}/{date} — the calendar, at one zoom, on one day.
+ *
+ * Both are path segments. The five zooms are mutually exclusive and each is a
+ * different surface, so sibling routes cannot both match (R5); the day is a
+ * segment because the strip is infinite and the address has to name where it
+ * opened — a `?date=` param would be the query compensating for a missing
+ * segment (R4).
+ *
+ * A segment the calendar cannot read is rewritten rather than refused. A
+ * hand-edited or stale address is a normal thing to receive, and the half that
+ * was readable is kept, so `/calendar/fortnight/2026-06-10` lands on that day's
+ * week instead of on an error.
+ */
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { useCallback, useState } from "react";
+import { CalendarShell } from "@/components/calendar/CalendarShell";
+import { CalendarWorkspace } from "@/components/calendar/CalendarWorkspace";
+import { useCalendarData } from "@/hooks/useCalendarData";
+import {
+	readCalendarDensity,
+	writeCalendarDensity,
+} from "@/lib/calendar-density";
+import { fixtureTimeZone } from "@/lib/calendar-fixtures";
+import {
+	calendarSearchSchema,
+	canonicalCalendarParams,
+	isoDate,
+} from "@/lib/calendar-route";
+import {
+	useCalendarAddress,
+	useCalendarNavigation,
+	useIsWritingEvent,
+	useOpenCalendarEvent,
+} from "@/routing";
+
+export const Route = createFileRoute("/calendar/$view/$date")({
+	validateSearch: calendarSearchSchema,
+	beforeLoad: ({ params, search }) => {
+		const canonical = canonicalCalendarParams(params, isoDate(new Date()));
+		if (canonical.view === params.view && canonical.date === params.date)
+			return;
+		throw redirect({
+			to: "/calendar/$view/$date",
+			params: canonical,
+			search,
+			replace: true,
+		});
+	},
+	component: CalendarViewLayout,
+});
+
+function CalendarViewLayout() {
+	const { view, date, calendarIds } = useCalendarAddress();
+	const { events, colorByCalendarId } = useCalendarData({
+		view,
+		date,
+		calendarIds,
+	});
+	const { goToView, goToToday, step, openEvent, openComposer } =
+		useCalendarNavigation();
+	const openedEvent = useOpenCalendarEvent();
+	const isWriting = useIsWritingEvent();
+	// Held in state rather than read back from storage each render: how much of
+	// a day this device shows is not a fact about the calendar, so changing it
+	// changes nothing about the address.
+	const [density, setDensity] = useState(readCalendarDensity);
+	const changeDensity = useCallback((next: typeof density) => {
+		writeCalendarDensity(next);
+		setDensity(next);
+	}, []);
+
+	const workspace = (
+		<CalendarWorkspace
+			view={view}
+			date={date}
+			events={events}
+			colorByCalendarId={colorByCalendarId}
+			density={density}
+			selectedEventId={openedEvent?.calendarObjectId ?? ""}
+			timeZone={fixtureTimeZone()}
+			now={new Date().toISOString()}
+			onChangeView={goToView}
+			onToday={goToToday}
+			onStep={step}
+			onChangeDensity={changeDensity}
+			onSelectEvent={openEvent}
+			onPickSlot={openComposer}
+		/>
+	);
+
+	return (
+		<CalendarShell
+			workspace={workspace}
+			reading={<Outlet />}
+			hasOpenEvent={openedEvent !== undefined || isWriting}
+		/>
+	);
+}

package/src/routes/calendar/-calendar-tree.test.ts

@@ -0,0 +1,267 @@
+// biome-ignore lint/style/useFilenamingConvention: TanStack Router convention
+/**
+ * The calendar's route tree.
+ *
+ * What is asserted is what the address does rather than what a component
+ * renders: which routes a path mounts, which segment carries which fact, and
+ * where an address the calendar cannot read is sent instead. The rules are
+ * `docs/architecture/url-state.md` — the view and the day are segments (R4/R5),
+ * the ticked calendars are query validated by one schema (R7), and no fact
+ * appears at two tiers.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type AnyRoute,
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRouter,
+	isRedirect,
+	Outlet,
+} from "@tanstack/react-router";
+import {
+	calendarSearchSchema,
+	isoDate,
+	stepCalendarDate,
+} from "@/lib/calendar-route";
+import { stringifySearch } from "@/lib/search-params";
+import { Route as OccurrenceRoute } from "./$view.$date/$calendarObjectId/$recurrenceId.js";
+import { Route as EventIndexRoute } from "./$view.$date/$calendarObjectId/index.js";
+import { Route as EventRoute } from "./$view.$date/$calendarObjectId.js";
+import { Route as ReadingPaneRoute } from "./$view.$date/index.js";
+import { Route as ComposeRoute } from "./$view.$date/new.js";
+import { Route as ViewRoute } from "./$view.$date.js";
+import { Route as CalendarIndexRoute } from "./index.js";
+
+// The router reads `self` at construction; the shared globals stop at `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+/** The router types a file route's own `update` more narrowly than a test needs. */
+type Attachable = { update: (options: unknown) => AnyRoute };
+const attach = (route: unknown, options: unknown): AnyRoute =>
+	(route as Attachable).update(options);
+
+/**
+ * The calendar's routes, mounted the way the generated tree mounts them but
+ * without the `/calendar` layout above them — that route only fetches the
+ * account list the sidebar is built from, and no rule under test is its. Built
+ * once: a file route is a module singleton, and re-parenting one per case would
+ * be re-parenting the same object.
+ */
+const rootRoute = createRootRoute({ component: Outlet });
+const viewRoute = attach(ViewRoute, {
+	path: "/calendar/$view/$date",
+	getParentRoute: () => rootRoute,
+});
+const eventRoute = attach(EventRoute, {
+	path: "$calendarObjectId",
+	getParentRoute: () => viewRoute,
+});
+eventRoute.addChildren([
+	attach(EventIndexRoute, { path: "/", getParentRoute: () => eventRoute }),
+	attach(OccurrenceRoute, {
+		path: "$recurrenceId",
+		getParentRoute: () => eventRoute,
+	}),
+]);
+viewRoute.addChildren([
+	attach(ReadingPaneRoute, { path: "/", getParentRoute: () => viewRoute }),
+	attach(ComposeRoute, { path: "new", getParentRoute: () => viewRoute }),
+	eventRoute,
+]);
+const routeTree = rootRoute.addChildren([
+	attach(CalendarIndexRoute, {
+		path: "/calendar",
+		getParentRoute: () => rootRoute,
+	}),
+	viewRoute,
+]) as unknown as AnyRoute;
+
+interface Match {
+	routeIds: string[];
+	params: Record<string, string>;
+}
+
+/** A router over the tree, spelling its query string the way the app does. */
+const routerAt = (entry: string): AnyRouter =>
+	createRouter({
+		routeTree,
+		stringifySearch,
+		history: createMemoryHistory({ initialEntries: [entry] }),
+	}) as unknown as AnyRouter;
+
+/** The routes an address mounts, deepest last. */
+function match(entry: string): Match {
+	const router = routerAt(entry);
+	const matches = router.matchRoutes(router.state.location);
+	return {
+		routeIds: matches.map((one: { routeId: string }) => one.routeId),
+		params: matches[matches.length - 1].params as Record<string, string>,
+	};
+}
+
+interface SentTo {
+	to?: string;
+	params?: Record<string, string>;
+	search?: Record<string, unknown>;
+}
+
+const beforeLoadOf = (route: unknown): ((args: unknown) => void) => {
+	const { beforeLoad } = (
+		route as { options: { beforeLoad?: (args: unknown) => void } }
+	).options;
+	assert.ok(beforeLoad, "the route decides nothing about the address it got");
+	return beforeLoad;
+};
+
+type Address = { params: Record<string, string>; search: unknown };
+
+/** Where a route sends an address it will not serve. */
+function sentTo(route: unknown, address: Address): SentTo {
+	let sent: SentTo | undefined;
+	assert.throws(
+		() => beforeLoadOf(route)(address),
+		(thrown: unknown) => {
+			assert.ok(isRedirect(thrown), `not a redirect: ${String(thrown)}`);
+			sent = (thrown as { options: SentTo }).options;
+			return true;
+		},
+	);
+	return sent as SentTo;
+}
+
+/** That the route serves the address as it stands, rewriting nothing. */
+function serves(route: unknown, address: Address): void {
+	assert.doesNotThrow(() => beforeLoadOf(route)(address));
+}
+
+const TODAY = isoDate(new Date());
+const held = (view: string, date: string) => ({
+	params: { view, date },
+	search: {},
+});
+
+describe("/calendar", () => {
+	it("sends a link that names no zoom to this week", () => {
+		const sent = sentTo(CalendarIndexRoute, { params: {}, search: {} });
+		assert.equal(sent.to, "/calendar/$view/$date");
+		assert.deepEqual(sent.params, { view: "week", date: TODAY });
+	});
+
+	it("takes whatever the link ticked off with it", () => {
+		const sent = sentTo(CalendarIndexRoute, {
+			params: {},
+			search: { calendarId: ["cal_a"] },
+		});
+		assert.deepEqual(sent.search, { calendarId: ["cal_a"] });
+	});
+});
+
+describe("/calendar/{view}/{date}", () => {
+	it("serves every zoom the ladder has, on the day named", () => {
+		for (const view of ["year", "month", "week", "day", "agenda"]) {
+			serves(ViewRoute, held(view, "2026-06-10"));
+			const mounted = match(`/calendar/${view}/2026-06-10`);
+			assert.ok(mounted.routeIds.includes("/calendar/$view/$date"));
+			assert.equal(mounted.params.view, view);
+			assert.equal(mounted.params.date, "2026-06-10");
+		}
+	});
+
+	it("mounts the reading pane under the view with nothing open", () => {
+		assert.deepEqual(match("/calendar/week/2026-06-10").routeIds.slice(-2), [
+			"/calendar/$view/$date",
+			"/calendar/$view/$date/",
+		]);
+	});
+
+	it("rewrites a zoom the ladder does not have, keeping the day", () => {
+		const sent = sentTo(ViewRoute, held("fortnight", "2026-06-10"));
+		assert.deepEqual(sent.params, { view: "week", date: "2026-06-10" });
+	});
+
+	it("rewrites a day the calendar does not have, keeping the zoom", () => {
+		assert.deepEqual(sentTo(ViewRoute, held("day", "2026-02-30")).params, {
+			view: "day",
+			date: TODAY,
+		});
+		assert.deepEqual(sentTo(ViewRoute, held("day", "tomorrow")).params, {
+			view: "day",
+			date: TODAY,
+		});
+	});
+});
+
+describe("the ticked calendars", () => {
+	it("are validated by the schema the domain reads them with", () => {
+		assert.equal(
+			(ViewRoute as unknown as { options: { validateSearch: unknown } }).options
+				.validateSearch,
+			calendarSearchSchema,
+		);
+	});
+
+	/**
+	 * The address the toolbar's Next writes. Repeated params are the shape the
+	 * issue pins and the shape A.3 and C.2 inherit, so what a step writes is
+	 * asserted rather than assumed: the router's own serializer would have made
+	 * this a JSON blob.
+	 */
+	it("are written as repeated params when the week steps", () => {
+		const router = routerAt("/calendar/week/2026-06-10?calendarId=cal_a");
+		const next = router.buildLocation({
+			to: "/calendar/$view/$date",
+			params: {
+				view: "week",
+				date: stepCalendarDate("2026-06-10", "week", 1),
+			},
+			search: { calendarId: ["cal_a", "cal_b"] },
+		});
+		assert.equal(next.pathname, "/calendar/week/2026-06-17");
+		assert.equal(next.searchStr, "?calendarId=cal_a&calendarId=cal_b");
+	});
+
+	it("leave the query out of a step that has nothing ticked", () => {
+		const router = routerAt("/calendar/week/2026-06-10");
+		const next = router.buildLocation({
+			to: "/calendar/$view/$date",
+			params: { view: "week", date: "2026-06-17" },
+			search: {},
+		});
+		assert.equal(next.searchStr, "");
+	});
+});
+
+describe("the composer and the open event cannot both be addressed", () => {
+	it("mounts the composer, and nothing of the event route", () => {
+		const mounted = match("/calendar/week/2026-06-10/new");
+		assert.ok(mounted.routeIds.includes("/calendar/$view/$date/new"));
+		assert.equal(
+			mounted.routeIds.some((id) => id.includes("$calendarObjectId")),
+			false,
+		);
+	});
+
+	it("mounts the event, and nothing of the composer", () => {
+		const mounted = match("/calendar/week/2026-06-10/evt_1");
+		assert.deepEqual(mounted.routeIds.slice(-2), [
+			"/calendar/$view/$date/$calendarObjectId",
+			"/calendar/$view/$date/$calendarObjectId/",
+		]);
+		assert.equal(mounted.params.calendarObjectId, "evt_1");
+		assert.equal(mounted.routeIds.includes("/calendar/$view/$date/new"), false);
+	});
+
+	it("keeps the series matched under one of its occurrences", () => {
+		const mounted = match(
+			"/calendar/week/2026-06-10/evt_1/2026-06-11T09%3A15%3A00%2B02%3A00",
+		);
+		assert.deepEqual(mounted.routeIds.slice(-2), [
+			"/calendar/$view/$date/$calendarObjectId",
+			"/calendar/$view/$date/$calendarObjectId/$recurrenceId",
+		]);
+		assert.equal(mounted.params.calendarObjectId, "evt_1");
+		assert.equal(mounted.params.recurrenceId, "2026-06-11T09:15:00+02:00");
+	});
+});

package/src/routes/calendar/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * `/calendar` has no view of its own: the five zoom levels are five addresses,
+ * so a link that names none is sent to the week the reader is in. The week is
+ * the default because it is the one that answers "what is my day like" without
+ * either scrolling or squinting.
+ *
+ * Whatever the link ticked off travels with it. The query modifies the view
+ * rather than choosing it, so it survives being told which view to open.
+ */
+import { createFileRoute, redirect } from "@tanstack/react-router";
+import {
+	calendarSearchSchema,
+	DEFAULT_CALENDAR_VIEW,
+	isoDate,
+} from "@/lib/calendar-route";
+
+export const Route = createFileRoute("/calendar/")({
+	validateSearch: calendarSearchSchema,
+	beforeLoad: ({ search }) => {
+		throw redirect({
+			to: "/calendar/$view/$date",
+			params: { view: DEFAULT_CALENDAR_VIEW, date: isoDate(new Date()) },
+			search,
+			replace: true,
+		});
+	},
+});

package/src/routes/calendar.tsx

@@ -0,0 +1,98 @@
+/**
+ * /calendar — a sibling of /mail, sharing its nav and nothing else.
+ *
+ * The layout owns what the whole calendar needs and no more: the account list
+ * the sidebar is built from, and the nav slide-over the narrow tiers open. The
+ * view below it decides what the panes hold.
+ *
+ * The fragment keeps the meaning it has in mail. The calendar has no
+ * intelligence rail, so a reader arriving with `#intelligence` carries it
+ * through and takes it back to their mail — nothing calendar-specific joins the
+ * union, because none of the calendar's own chrome is a panel.
+ */
+import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { createFileRoute, Outlet, useNavigate } from "@tanstack/react-router";
+import { useCallback, useEffect } from "react";
+import { CalendarShellProvider } from "@/components/calendar/CalendarShell";
+import { MailNav } from "@/components/mail/MailNav";
+import { ErrorState } from "@/components/ui/ErrorState";
+import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
+import { panelsWithOverlay, useOpenPanels, useSetOpenPanels } from "@/routing";
+import "@/lib/client";
+
+export const Route = createFileRoute("/calendar")({
+	loader: ({ context: { queryClient } }) => {
+		void queryClient.prefetchQuery(configOperationsGetConfigOptions());
+	},
+	component: CalendarLayout,
+});
+
+function CalendarLayout() {
+	const navigate = useNavigate();
+	const isSinglePane = isSinglePaneTier(useLayoutTier());
+	// Only the nav slide-over is the calendar's to open, and it is written as
+	// the whole set so a pane the reader brought with them from mail survives
+	// the visit rather than being dropped by the first tap on the hamburger.
+	const openPanels = useOpenPanels();
+	const setOpenPanels = useSetOpenPanels();
+	const navOpen = openPanels.includes("nav");
+	const showNav = useCallback(
+		(open: boolean) => {
+			setOpenPanels(panelsWithOverlay(openPanels, open ? "nav" : undefined));
+		},
+		[openPanels, setOpenPanels],
+	);
+
+	const {
+		data: config,
+		isLoading,
+		isError,
+		error,
+		refetch,
+	} = useQuery({
+		...configOperationsGetConfigOptions(),
+		staleTime: Infinity,
+	});
+
+	// The same first-run guard `/mail` carries: a reader with no account has no
+	// calendar either, and the onboarding wizard is where they belong.
+	const hasNoAccounts = Boolean(config && (config.accounts?.length ?? 0) === 0);
+	useEffect(() => {
+		if (!hasNoAccounts) return;
+		navigate({ to: "/onboarding", replace: true });
+	}, [hasNoAccounts, navigate]);
+
+	const accounts = config?.accounts ?? [];
+
+	if (isError) {
+		return (
+			<div className="flex h-full items-center justify-center bg-canvas p-4">
+				<ErrorState
+					title="Couldn't load your account"
+					error={error}
+					onRetry={() => {
+						refetch();
+					}}
+				/>
+			</div>
+		);
+	}
+
+	return (
+		<CalendarShellProvider
+			chrome={{
+				isSinglePane,
+				isLoading: isLoading || hasNoAccounts,
+				nav: (
+					<MailNav accounts={accounts} onMailboxSelect={() => showNav(false)} />
+				),
+				navOpen,
+				onOpenNav: () => showNav(true),
+				onCloseNav: () => showNav(false),
+			}}
+		>
+			<Outlet />
+		</CalendarShellProvider>
+	);
+}

package/src/routing/calendar-fragment.test.ts

@@ -0,0 +1,66 @@
+/**
+ * The fragment across the mail↔calendar switch.
+ *
+ * The calendar is a sibling of mail in the shell, not a different app, so the
+ * chrome a reader has up travels with them: the rail is a pane they keep, the
+ * slide-over and the sheet are overlays that going somewhere dismisses. The
+ * calendar owns no panel of its own — nothing calendar-specific joins the union
+ * (R3) — so the only thing it does to the fragment is carry it.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	formatOpenPanels,
+	panelFragments,
+	panelsWithOverlay,
+	parseOpenPanels,
+	retainOpenPanelsAtTier,
+} from "./fragment.js";
+
+const retainOnDesktop = retainOpenPanelsAtTier(true);
+const retainOnPhone = retainOpenPanelsAtTier(false);
+
+describe("the calendar names no panel of its own", () => {
+	it("leaves the union exactly as mail wrote it", () => {
+		assert.deepEqual(panelFragments, ["intelligence", "nav", "shortcuts"]);
+	});
+});
+
+describe("crossing between mail and the calendar", () => {
+	// The nav entry is a `NavLink`, so both directions go through the same
+	// retention the mail lists already navigate under.
+	it("carries the rail into the calendar and back out again", () => {
+		assert.equal(retainOnDesktop("intelligence"), "intelligence");
+	});
+
+	it("leaves the slide-over the reader picked the entry from behind", () => {
+		assert.equal(retainOnDesktop("nav"), "");
+		assert.equal(retainOnDesktop("intelligence,nav"), "intelligence");
+	});
+
+	it("leaves the drawer behind on a tier that has no rail", () => {
+		assert.equal(retainOnPhone("intelligence"), "");
+		assert.equal(retainOnPhone("intelligence,nav"), "");
+	});
+});
+
+describe("reaching for the folders while on the calendar", () => {
+	const opened = (hash: string): string =>
+		formatOpenPanels(panelsWithOverlay(parseOpenPanels(hash), "nav"));
+	const closed = (hash: string): string =>
+		formatOpenPanels(panelsWithOverlay(parseOpenPanels(hash), undefined));
+
+	it("keeps the rail the reader arrived with", () => {
+		assert.equal(opened("intelligence"), "intelligence,nav");
+		assert.equal(closed("intelligence,nav"), "intelligence");
+	});
+
+	it("puts the slide-over up over nothing else, and takes it down again", () => {
+		assert.equal(opened(""), "nav");
+		assert.equal(closed("nav"), "");
+	});
+
+	it("replaces whichever overlay was up, because two cannot be", () => {
+		assert.equal(opened("intelligence,shortcuts"), "intelligence,nav");
+	});
+});

package/src/routing/calendar.ts

@@ -0,0 +1,139 @@
+import type { CalendarViewId } from "@remit/ui";
+import { useNavigate, useParams, useSearch } from "@tanstack/react-router";
+import { useCallback, useMemo } from "react";
+import {
+	canonicalCalendarParams,
+	isoDate,
+	stepCalendarDate,
+} from "@/lib/calendar-route";
+import { useRetainOpenPanels } from "./fragment";
+
+const VIEW_ROUTE = "/calendar/$view/$date" as const;
+
+/** Which zoom the calendar is at, on which day, over which calendars. */
+export interface CalendarAddress {
+	view: CalendarViewId;
+	/** `YYYY-MM-DD`. */
+	date: string;
+	/** The calendars ticked in the query; empty means every one of them. */
+	calendarIds: readonly string[];
+}
+
+/**
+ * The calendar the address names.
+ *
+ * The route canonicalises its own segments before anything mounts, so what
+ * arrives here is always a view the ladder has and a day the calendar has —
+ * the fallbacks below only cover the frame before the router has resolved
+ * the params.
+ */
+export function useCalendarAddress(): CalendarAddress {
+	const params = useParams({ from: VIEW_ROUTE, shouldThrow: false });
+	const search = useSearch({ from: VIEW_ROUTE, shouldThrow: false });
+	const view = params?.view ?? "";
+	const date = params?.date ?? "";
+	const calendarIds = search?.calendarId;
+	return useMemo(() => {
+		const canonical = canonicalCalendarParams(
+			{ view, date },
+			isoDate(new Date()),
+		);
+		return { ...canonical, calendarIds: calendarIds ?? [] };
+	}, [view, date, calendarIds]);
+}
+
+/** The event the reading pane has open, and the instance of it, if any. */
+export interface OpenCalendarEvent {
+	calendarObjectId: string;
+	/** One instance of a series; absent on the series itself. */
+	recurrenceId: string | undefined;
+}
+
+export function useOpenCalendarEvent(): OpenCalendarEvent | undefined {
+	const event = useParams({
+		from: "/calendar/$view/$date/$calendarObjectId",
+		shouldThrow: false,
+	});
+	const instance = useParams({
+		from: "/calendar/$view/$date/$calendarObjectId/$recurrenceId",
+		shouldThrow: false,
+	});
+	const calendarObjectId = event?.calendarObjectId;
+	const recurrenceId = instance?.recurrenceId;
+	return useMemo(
+		() => (calendarObjectId ? { calendarObjectId, recurrenceId } : undefined),
+		[calendarObjectId, recurrenceId],
+	);
+}
+
+/** Whether the composer is up, which is a route rather than a flag. */
+export function useIsWritingEvent(): boolean {
+	const composer = useParams({
+		from: "/calendar/$view/$date/new",
+		shouldThrow: false,
+	});
+	return composer !== undefined;
+}
+
+export interface CalendarNavigation {
+	/** Change zoom, keeping the day on screen. */
+	goToView: (view: CalendarViewId) => void;
+	/** The previous or next screenful, measured in the view's own unit. */
+	step: (direction: -1 | 1) => void;
+	/** Home, from every view and every distance away. */
+	goToToday: () => void;
+	openEvent: (calendarObjectId: string) => void;
+	closeEvent: () => void;
+	openComposer: () => void;
+}
+
+/**
+ * Every move the calendar makes, as an address.
+ *
+ * Prev, next, today and the zoom switch are navigations rather than state
+ * changes, so the address always names what is on screen and a link to it
+ * reopens exactly that. Each one carries the open panes across the way the nav
+ * does, so the reader keeps their chrome moving through the week.
+ */
+export function useCalendarNavigation(): CalendarNavigation {
+	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
+	const { view, date } = useCalendarAddress();
+
+	const goTo = useCallback(
+		(params: { view: CalendarViewId; date: string }) => {
+			navigate({
+				to: VIEW_ROUTE,
+				params,
+				search: true,
+				hash: retainPanels,
+			});
+		},
+		[navigate, retainPanels],
+	);
+
+	return useMemo(
+		() => ({
+			goToView: (next: CalendarViewId) => goTo({ view: next, date }),
+			step: (direction: -1 | 1) =>
+				goTo({ view, date: stepCalendarDate(date, view, direction) }),
+			goToToday: () => goTo({ view, date: isoDate(new Date()) }),
+			openEvent: (calendarObjectId: string) =>
+				navigate({
+					to: "/calendar/$view/$date/$calendarObjectId",
+					params: { view, date, calendarObjectId },
+					search: true,
+					hash: retainPanels,
+				}),
+			closeEvent: () => goTo({ view, date }),
+			openComposer: () =>
+				navigate({
+					to: "/calendar/$view/$date/new",
+					params: { view, date },
+					search: true,
+					hash: retainPanels,
+				}),
+		}),
+		[goTo, navigate, retainPanels, view, date],
+	);
+}