@remit/web-client 0.0.230 → 0.0.232

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

@@ -0,0 +1,148 @@
+/**
+ * The window a view asks the server about.
+ *
+ * What matters is that the window is a property of the screenful rather than of
+ * the day the address happens to name: every day inside one week has to produce
+ * the same `from` and `to`, because that is what makes stepping back to a week
+ * already read a cache hit instead of a second request for the same days.
+ *
+ * A window carries the device's own offsets, so those assertions are about
+ * civil dates and about windows agreeing with each other rather than about a
+ * literal `+02:00` that would only hold on a runner in Amsterdam. The zoned
+ * times below are the opposite: absolute, because the whole point of them is
+ * that the runner's zone stays out.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	addDays,
+	calendarWindow,
+	calendarWindowOfDays,
+	isoAt,
+	isoAtInZone,
+} from "./window";
+
+const day = (iso: string): string => iso.slice(0, 10);
+
+const OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:00[+-]\d{2}:\d{2}$/;
+
+describe("the window a view covers", () => {
+	it("takes the whole week a day falls in, starting Monday", () => {
+		const window = calendarWindow("week", "2026-06-10");
+		assert.equal(day(window.from), "2026-06-08");
+		assert.equal(day(window.to), "2026-06-15");
+	});
+
+	it("gives every day of one week the same window", () => {
+		const monday = calendarWindow("week", "2026-06-08");
+		for (const date of ["2026-06-09", "2026-06-11", "2026-06-14"]) {
+			assert.deepEqual(calendarWindow("week", date), monday);
+		}
+	});
+
+	it("takes one day at the day zoom", () => {
+		const window = calendarWindow("day", "2026-06-10");
+		assert.equal(day(window.from), "2026-06-10");
+		assert.equal(day(window.to), "2026-06-11");
+	});
+
+	it("takes the calendar month, ending on the first of the next", () => {
+		const window = calendarWindow("month", "2026-06-10");
+		assert.equal(day(window.from), "2026-06-01");
+		assert.equal(day(window.to), "2026-07-01");
+	});
+
+	it("rolls a December month into the next year", () => {
+		assert.equal(day(calendarWindow("month", "2026-12-31").to), "2027-01-01");
+	});
+
+	it("takes the calendar year", () => {
+		const window = calendarWindow("year", "2026-06-10");
+		assert.equal(day(window.from), "2026-01-01");
+		assert.equal(day(window.to), "2027-01-01");
+	});
+
+	it("gives the agenda the week it steps by, so it shares the grid's entry", () => {
+		assert.deepEqual(
+			calendarWindow("agenda", "2026-06-10"),
+			calendarWindow("week", "2026-06-10"),
+		);
+	});
+
+	it("carries an explicit offset at both ends, as the API asks for", () => {
+		const window = calendarWindow("week", "2026-06-10");
+		assert.match(window.from, OFFSET);
+		assert.match(window.to, OFFSET);
+	});
+});
+
+describe("a window a surface rolls itself", () => {
+	it("runs whole days from the date it was given", () => {
+		const window = calendarWindowOfDays("2026-06-10", 3);
+		assert.equal(day(window.from), "2026-06-10");
+		assert.equal(day(window.to), "2026-06-13");
+	});
+});
+
+describe("civil dates", () => {
+	it("steps across a month boundary", () => {
+		assert.equal(addDays("2026-06-30", 1), "2026-07-01");
+		assert.equal(addDays("2026-03-01", -1), "2026-02-28");
+	});
+
+	it("puts a clock time on a day with the offset that day is on", () => {
+		assert.match(isoAt("2026-06-10", "09:15"), OFFSET);
+		assert.ok(isoAt("2026-06-10", "09:15").startsWith("2026-06-10T09:15:00"));
+	});
+});
+
+/**
+ * A named zone's offset, read without touching the runner's own clock. Every
+ * expectation here is absolute, because a test that reads the device offset
+ * cannot see the bug where the device offset leaked in.
+ */
+describe("a clock time in a named zone", () => {
+	it("carries that zone's summer offset", () => {
+		assert.equal(
+			isoAtInZone("2026-06-10", "09:15", "Europe/Amsterdam"),
+			"2026-06-10T09:15:00+02:00",
+		);
+		assert.equal(
+			isoAtInZone("2026-06-10", "09:15", "America/New_York"),
+			"2026-06-10T09:15:00-04:00",
+		);
+	});
+
+	it("carries its winter offset for a winter date", () => {
+		assert.equal(
+			isoAtInZone("2026-01-14", "09:15", "Europe/Amsterdam"),
+			"2026-01-14T09:15:00+01:00",
+		);
+	});
+
+	it("settles a time on the far side of a spring-forward", () => {
+		// The Netherlands moves to +02:00 at 02:00 on 29 March 2026.
+		assert.equal(
+			isoAtInZone("2026-03-29", "09:00", "Europe/Amsterdam"),
+			"2026-03-29T09:00:00+02:00",
+		);
+		assert.equal(
+			isoAtInZone("2026-03-29", "00:30", "Europe/Amsterdam"),
+			"2026-03-29T00:30:00+01:00",
+		);
+	});
+
+	it("handles a zone that is not a whole number of hours off", () => {
+		assert.equal(
+			isoAtInZone("2026-06-10", "09:15", "Asia/Kolkata"),
+			"2026-06-10T09:15:00+05:30",
+		);
+	});
+
+	it("falls back to the device rather than throwing on a zone nothing knows", () => {
+		assert.match(
+			isoAtInZone("2026-06-10", "09:15", "Mars/Olympus_Mons"),
+			OFFSET,
+		);
+	});
+});

package/src/hooks/calendar/window.ts

@@ -0,0 +1,163 @@
+/**
+ * The stretch of time a calendar surface is asking the server about.
+ *
+ * A window is derived from the address rather than from the day the reader
+ * happens to be on, so every day inside one week asks for the same window and
+ * stepping back to a week already read is a cache hit rather than a request.
+ *
+ * Nothing here reads a clock: the caller passes the day it is drawing, and the
+ * offsets come from that day rather than from today, so a window spanning a DST
+ * change carries the right offset at each end.
+ */
+import type { CalendarViewId } from "@remit/ui";
+
+export interface CalendarWindow {
+	/** ISO 8601 date-time with offset. Inclusive. */
+	from: string;
+	/** ISO 8601 date-time with offset. Exclusive. */
+	to: string;
+}
+
+const pad = (value: number): string => String(value).padStart(2, "0");
+
+const civil = (instant: Date): string =>
+	`${instant.getUTCFullYear()}-${pad(instant.getUTCMonth() + 1)}-${pad(
+		instant.getUTCDate(),
+	)}`;
+
+const formatOffset = (minutes: number): string => {
+	const sign = minutes < 0 ? "-" : "+";
+	const size = Math.abs(minutes);
+	return `${sign}${pad(Math.floor(size / 60))}:${pad(size % 60)}`;
+};
+
+/** A clock time on a civil date, carrying the offset the device is on then. */
+export function isoAt(date: string, time: string): string {
+	const local = new Date(`${date}T${time}:00`);
+	return `${date}T${time}:00${formatOffset(-local.getTimezoneOffset())}`;
+}
+
+const zoneReaders = new Map<string, Intl.DateTimeFormat | undefined>();
+
+/**
+ * A zone nothing can resolve is not worth throwing over: the device's own clock
+ * is the honest fallback, and the resource records how its start was zoned.
+ */
+function zoneReader(timeZone: string): Intl.DateTimeFormat | undefined {
+	if (zoneReaders.has(timeZone)) return zoneReaders.get(timeZone);
+	let reader: Intl.DateTimeFormat | undefined;
+	try {
+		reader = new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			hourCycle: "h23",
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+		});
+	} catch {
+		reader = undefined;
+	}
+	zoneReaders.set(timeZone, reader);
+	return reader;
+}
+
+/** How far ahead of UTC a zone is at one instant, in minutes. */
+function zoneOffsetAt(timeZone: string, instant: number): number {
+	const reader = zoneReader(timeZone);
+	if (!reader) return Number.NaN;
+	const parts = reader.formatToParts(new Date(instant));
+	const read = (type: Intl.DateTimeFormatPartTypes): number =>
+		Number(parts.find((part) => part.type === type)?.value);
+	const hour = read("hour") % 24;
+	const reading = Date.UTC(
+		read("year"),
+		read("month") - 1,
+		read("day"),
+		hour,
+		read("minute"),
+		read("second"),
+	);
+	return (reading - instant) / 60_000;
+}
+
+/**
+ * A clock time on a civil date, carrying the offset **that zone** is on then.
+ *
+ * The device's own offset is the wrong one for a calendar anchored elsewhere: a
+ * 10:00 Amsterdam meeting rewritten with a New York offset is a 16:00 Amsterdam
+ * meeting, and nothing on screen says it moved.
+ *
+ * The offset is read twice because reading it needs an instant and the instant
+ * needs the offset. The first pass is off only inside a DST transition, and the
+ * second pass — taken at the instant the first one implies — settles it.
+ */
+export function isoAtInZone(
+	date: string,
+	time: string,
+	timeZone: string,
+): string {
+	// A collection naming no zone reads as UTC at both ends, and UTC is the one
+	// zone the canonical IANA list holds no name for — so it is handled here
+	// rather than asked about.
+	if (timeZone === "") return `${date}T${time}:00+00:00`;
+	const asIfUtc = Date.parse(`${date}T${time}:00Z`);
+	const first = zoneOffsetAt(timeZone, asIfUtc);
+	if (Number.isNaN(first)) return isoAt(date, time);
+	const settled = zoneOffsetAt(timeZone, asIfUtc - first * 60_000);
+	return `${date}T${time}:00${formatOffset(
+		Number.isNaN(settled) ? first : settled,
+	)}`;
+}
+
+/** Midnight on a civil date, carrying the offset the device is on that day. */
+export const startOfDay = (date: string): string => isoAt(date, "00:00");
+
+export function addDays(date: string, days: number): string {
+	const [year, month, day] = date.split("-").map(Number);
+	return civil(new Date(Date.UTC(year, month - 1, day + days)));
+}
+
+/** The Monday of the week a day falls in — the day the grid starts weeks on. */
+function weekStart(date: string): string {
+	const [year, month, day] = date.split("-").map(Number);
+	const instant = new Date(Date.UTC(year, month - 1, day));
+	return addDays(date, -((instant.getUTCDay() + 6) % 7));
+}
+
+function bounds(view: CalendarViewId, date: string): [string, string] {
+	const [year, month] = date.split("-").map(Number);
+	if (view === "year") return [`${year}-01-01`, `${year + 1}-01-01`];
+	if (view === "month") {
+		const first = `${year}-${pad(month)}-01`;
+		const next =
+			month === 12 ? `${year + 1}-01-01` : `${year}-${pad(month + 1)}-01`;
+		return [first, next];
+	}
+	if (view === "day") return [date, addDays(date, 1)];
+	const start = weekStart(date);
+	return [start, addDays(start, 7)];
+}
+
+/**
+ * The window a view over a day covers. Agenda takes the week it loads, which is
+ * also the unit it steps by, so the grid and the strip share a cache entry
+ * wherever they are looking at the same days.
+ */
+export function calendarWindow(
+	view: CalendarViewId,
+	date: string,
+): CalendarWindow {
+	const [from, to] = bounds(view, date);
+	return { from: startOfDay(from), to: startOfDay(to) };
+}
+
+/** A window of whole days from one civil date, for a surface rolling its own. */
+export function calendarWindowOfDays(
+	date: string,
+	days: number,
+): CalendarWindow {
+	return { from: startOfDay(date), to: startOfDay(addDays(date, days)) };
+}

package/src/hooks/useCalendarData.ts

@@ -0,0 +1,120 @@
+/**
+ * What the calendar surfaces read, and the only place they read it from.
+ *
+ * The seam is here, and not inside the grid, because the grid is presentational
+ * and expands no recurrence of its own — the server returns instances and this
+ * turns them into what the kit draws. Every caller keeps the call it makes.
+ */
+import type {
+	CalendarColorId,
+	CalendarDescriptor,
+	CalendarEventData,
+	CalendarViewId,
+} from "@remit/ui";
+import { useMemo } from "react";
+import {
+	type CalendarInstanceRef,
+	calendarWindow,
+	isDrawnInstance,
+	readCalendarInstanceId,
+	toCalendarEventData,
+	UNZONED_CALENDAR,
+	useCalendarEventWindow,
+	useCalendars,
+	usePrefetchAdjacentWindows,
+} from "@/hooks/calendar";
+
+export interface CalendarDataRequest {
+	view: CalendarViewId;
+	/** The day the view is centred on, `YYYY-MM-DD`. */
+	date: string;
+	/** The calendars the address has ticked; empty means every one of them. */
+	calendarIds: readonly string[];
+}
+
+export interface CalendarData {
+	calendars: CalendarDescriptor[];
+	events: CalendarEventData[];
+	colorByCalendarId: Record<string, CalendarColorId>;
+	/** The zone each collection's times are read on — never the device's. */
+	timeZoneByCalendarId: Record<string, string>;
+	isLoading: boolean;
+	/** A refusal the calendar renders itself. Null when the read succeeded. */
+	error: unknown;
+	retry: () => void;
+	/** The resource and occurrence behind an event the grid selected. */
+	instanceOf: (eventId: string) => CalendarInstanceRef;
+}
+
+/**
+ * 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 function useCalendarData({
+	view,
+	date,
+	calendarIds,
+}: CalendarDataRequest): CalendarData {
+	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;
+
+	const window = calendarWindow(view, date);
+	const events = useCalendarEventWindow({
+		...window,
+		calendarIds: narrowed,
+		enabled: resolved,
+	});
+	usePrefetchAdjacentWindows(view, date, narrowed, resolved);
+
+	const shownKey = shown.join(",");
+	const instances = events.instances;
+
+	const eventData = 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]);
+
+	return {
+		calendars,
+		events: eventData,
+		colorByCalendarId,
+		timeZoneByCalendarId,
+		isLoading: isLoading || events.isLoading,
+		error: events.error,
+		retry: events.refetch,
+		instanceOf: readCalendarInstanceId,
+	};
+}

package/src/lib/calendar-density.ts

@@ -0,0 +1,34 @@
+/**
+ * How much of a day this device shows at once.
+ *
+ * A phone on a train and a monitor on a desk want different amounts of the
+ * same week, and the answer belongs to the screen rather than to the calendar:
+ * it is not a fact about the view, so it is in no tier of the address, and a
+ * link shared from one device must not resize the day on another. Stored the
+ * way the intelligence rail's preference is (`lib/intelligence-pref.ts`), and
+ * a storage failure falls back to the default rather than crashing.
+ */
+import type { Density } from "@remit/ui";
+
+export const CALENDAR_DENSITY_KEY = "remit:calendar-density";
+
+/** Roomy enough to read a title at a glance, which is the common case. */
+export const DEFAULT_CALENDAR_DENSITY: Density = "comfortable";
+
+export function readCalendarDensity(): Density {
+	try {
+		return localStorage.getItem(CALENDAR_DENSITY_KEY) === "compact"
+			? "compact"
+			: DEFAULT_CALENDAR_DENSITY;
+	} catch {
+		return DEFAULT_CALENDAR_DENSITY;
+	}
+}
+
+export function writeCalendarDensity(density: Density): void {
+	try {
+		localStorage.setItem(CALENDAR_DENSITY_KEY, density);
+	} catch {
+		// Storage unavailable — the in-memory default stands.
+	}
+}

package/src/lib/calendar-format.ts

@@ -0,0 +1,29 @@
+/**
+ * The words a calendar surface puts a time in. Every component in `@remit/ui`
+ * takes its text already formatted and owns no clock, so the formatting lives
+ * on this side of the seam.
+ */
+import type { CalendarEventData } from "@remit/ui";
+
+const DAY = new Intl.DateTimeFormat(undefined, {
+	weekday: "short",
+	day: "numeric",
+	month: "long",
+});
+
+const CLOCK = new Intl.DateTimeFormat(undefined, {
+	hour: "2-digit",
+	minute: "2-digit",
+	hour12: false,
+});
+
+/** "Wed 10 June, 10:00 – 11:00", or the day alone when it runs all of it. */
+export function formatEventWhen(event: CalendarEventData): string {
+	const start = new Date(event.start);
+	const end = new Date(event.end);
+	const day = DAY.format(start);
+	if (event.allDay) return `${day}, all day`;
+	const sameDay = DAY.format(end) === day;
+	if (sameDay) return `${day}, ${CLOCK.format(start)} – ${CLOCK.format(end)}`;
+	return `${day}, ${CLOCK.format(start)} – ${DAY.format(end)}, ${CLOCK.format(end)}`;
+}