@remit/web-client 0.0.235 → 0.0.237

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.235",
+  "version": "0.0.237",
   "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/AgendaStrip.stories.tsx

@@ -8,6 +8,7 @@ import {
 } from "@remit/ui";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
+import { expect, within } from "storybook/test";
 import { freeStretchesByDate } from "@/hooks/calendar";
 import { AgendaStrip } from "./AgendaStrip";
 
@@ -148,6 +149,7 @@ function Strip({
 	loading,
 	error,
 	busy,
+	atCap,
 }: {
 	events: CalendarEventData[];
 	initialDensity: Density;
@@ -156,6 +158,8 @@ function Strip({
 	error?: unknown;
 	/** Busy time the strip is not drawing, as `/calendar-free-busy` returns it. */
 	busy: { start: string; end: string }[];
+	/** The run has grown as far as scrolling takes it, at one end or both. */
+	atCap?: boolean;
 }) {
 	const [density] = useState<Density>(initialDensity);
 	const [selected, setSelected] = useState("");
@@ -185,6 +189,10 @@ function Strip({
 			onGoToDate={() => undefined}
 			onReachStart={() => undefined}
 			onReachEnd={() => undefined}
+			atStartCap={atCap}
+			atEndCap={atCap}
+			onLoadEarlier={() => undefined}
+			onLoadLater={() => undefined}
 			onVisibleDayChange={() => undefined}
 		/>
 	);
@@ -254,6 +262,26 @@ export const BusyOnACalendarNotDrawn: Story = {
 	},
 };
 
+/**
+ * The run has grown as far as scrolling takes it, and stops there rather than
+ * fetching its way across years nobody asked for. A sparse diary draws shorter
+ * than the distance the strip fetches at, so an end measured off the content
+ * alone is reached on the first layout pass and never stops being reached —
+ * which is why the cap says so and hands the reader the next stretch instead.
+ */
+export const AtTheCap: Story = {
+	args: { atCap: true },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByRole("button", { name: "Show earlier days" }),
+		).toBeVisible();
+		await expect(
+			canvas.getByRole("button", { name: "Show later days" }),
+		).toBeVisible();
+	},
+};
+
 /** A read that was refused. An empty strip would say the opposite of this. */
 export const CouldNotLoad: Story = {
 	args: {

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

@@ -0,0 +1,116 @@
+import type { Density } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { AgendaView } from "./AgendaView";
+import {
+	calendars,
+	fortnight,
+	instancesWithin,
+	STORY_DATE,
+} from "./calendar-story-fixtures";
+import {
+	type CalendarServer,
+	CalendarStory,
+	json,
+	never,
+} from "./calendar-story-server";
+
+/**
+ * The agenda bound to the address, which is the only way it exists.
+ *
+ * It holds no days of its own: the run comes from the day the URL names, the
+ * weeks are fetched one at a time as the reader scrolls, and every move it makes
+ * leaves as a new address. So the states worth a story are the ones the reader
+ * cannot tell apart by looking — a fortnight with two things in it, a fortnight
+ * nobody has heard back about, and a fortnight the server refused. Drawn wrong,
+ * the last two are the first one, and the reader plans a clear week they do not
+ * have.
+ */
+
+const AGENDA = `/calendar/agenda/${STORY_DATE}`;
+
+const answering = (events: (url: URL) => Response | Promise<Response>) =>
+	((request: Request) => {
+		const url = new URL(request.url);
+		if (url.pathname.endsWith("/calendars")) return json({ items: calendars });
+		if (url.pathname.endsWith("/calendar-events")) return events(url);
+		return json({ items: [] });
+	}) satisfies CalendarServer;
+
+function Agenda({
+	density,
+	server,
+}: {
+	density: Density;
+	server: CalendarServer;
+}) {
+	return (
+		<div className="flex h-dvh flex-col bg-canvas">
+			<CalendarStory
+				entry={AGENDA}
+				server={server}
+				pane={<AgendaView density={density} onPickSlot={() => undefined} />}
+			/>
+		</div>
+	);
+}
+
+const meta: Meta<typeof Agenda> = {
+	title: "App/Calendar/Agenda view",
+	component: Agenda,
+	parameters: { layout: "fullscreen" },
+	args: {
+		density: "comfortable",
+		server: answering((url) =>
+			json({ items: instancesWithin(url, fortnight) }),
+		),
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof Agenda>;
+
+/** The weeks around the day the address names, drawn from what the server sent. */
+export const Populated: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Roadmap review")).toBeVisible();
+		await expect(canvas.getByText("Standup")).toBeVisible();
+	},
+};
+
+/**
+ * The weeks are still out. Every day keeps the row it will occupy, so nothing
+ * jumps when the answers land — and, which matters more, an unanswered day says
+ * so rather than drawing as a day with nothing booked on it.
+ */
+export const LoadingWeeks: Story = {
+	args: { server: answering(never) },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByTestId(`agenda-day-pending-${STORY_DATE}`),
+		).toBeVisible();
+		await expect(canvas.queryByText("Roadmap review")).toBeNull();
+	},
+};
+
+/**
+ * The read was refused. This is the state an empty strip must never be confused
+ * with: a fortnight drawn blank because the request failed reads as a fortnight
+ * with nothing in it, and the reader gives the time away.
+ */
+export const RefusedRead: Story = {
+	args: {
+		server: answering(() =>
+			json({ message: "The window has to be shorter than a year." }, 400),
+		),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByText("Couldn't load these days"),
+		).toBeVisible();
+		await expect(canvas.queryByText("Roadmap review")).toBeNull();
+	},
+};

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

@@ -0,0 +1,175 @@
+import {
+	type CalendarColorId,
+	type CalendarEventData,
+	type Density,
+	NavSidebar,
+} from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { expect, userEvent, within } from "storybook/test";
+import { CalendarShell, CalendarShellProvider } from "./CalendarShell";
+import { CalendarWorkspace } from "./CalendarWorkspace";
+
+/**
+ * The chrome the calendar shares with mail, at the two widths that change what
+ * the reader can reach.
+ *
+ * Above the boundary the nav is a pane and the calendar sits beside it. Below
+ * it the nav is a slide-over, nothing opens a slide-over on its own, and the
+ * calendar is the whole width of the app — so the way back to the mail has to be
+ * a control the calendar itself carries. Losing it strands a reader inside their
+ * diary with no route out, which is what these two stories hold the shell to.
+ */
+
+const TIME_ZONE = "Europe/Amsterdam";
+const DATE = "2026-06-10";
+const NOW = `${DATE}T09:30:00+02:00`;
+const CALENDAR = "cal_work";
+
+const colorByCalendarId: Record<string, CalendarColorId> = {
+	[CALENDAR]: "cal-1",
+};
+
+const roadmap: CalendarEventData = {
+	id: "roadmap",
+	calendarId: CALENDAR,
+	title: "Roadmap review",
+	start: `${DATE}T10:00:00+02:00`,
+	end: `${DATE}T11:30:00+02:00`,
+	allDay: false,
+	location: "",
+	notes: "",
+	attendees: [],
+	myRsvp: "accepted",
+	threadId: "",
+	threadSubject: "",
+	timeZone: TIME_ZONE,
+	zoneCertainty: "explicit",
+	recurrenceRule: "",
+	seriesId: "",
+	seriesException: false,
+	status: "confirmed",
+};
+
+const nav = (
+	<NavSidebar
+		accounts={[
+			{
+				id: "acct_work",
+				label: "Work",
+				email: "work@example.invalid",
+				mailboxes: [
+					{ id: "mb_inbox", name: "Inbox", role: "inbox", unseen: 3 },
+					{ id: "mb_sent", name: "Sent", role: "sent" },
+				],
+			},
+		]}
+		selectedNavId="calendar"
+		calendarNav="shown"
+	/>
+);
+
+const reading = (
+	<div className="flex h-full items-center justify-center bg-surface text-sm text-fg-muted">
+		Nothing open.
+	</div>
+);
+
+/** The layout publishes the chrome; a story holds the slide-over's own state. */
+function Shell({
+	width,
+	isSinglePane,
+}: {
+	/** The shell measures its own box, so the story gives it one. */
+	width: number;
+	isSinglePane: boolean;
+}) {
+	const [navOpen, setNavOpen] = useState(false);
+	const [density, setDensity] = useState<Density>("comfortable");
+	return (
+		<div style={{ width }} className="bg-canvas">
+			<CalendarShellProvider
+				chrome={{
+					isSinglePane,
+					isLoading: false,
+					nav,
+					navOpen,
+					onOpenNav: () => setNavOpen(true),
+					onCloseNav: () => setNavOpen(false),
+				}}
+			>
+				<CalendarShell
+					hasOpenEvent={false}
+					reading={reading}
+					workspace={
+						<CalendarWorkspace
+							view="week"
+							date={DATE}
+							events={[roadmap]}
+							colorByCalendarId={colorByCalendarId}
+							agenda={null}
+							density={density}
+							selectedEventId=""
+							timeZone={TIME_ZONE}
+							now={NOW}
+							onChangeView={() => undefined}
+							onToday={() => undefined}
+							onStep={() => undefined}
+							onChangeDensity={setDensity}
+							onSelectEvent={() => undefined}
+							onPickSlot={() => undefined}
+						/>
+					}
+				/>
+			</CalendarShellProvider>
+		</div>
+	);
+}
+
+const meta: Meta<typeof Shell> = {
+	title: "App/Calendar/Shell",
+	component: Shell,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof Shell>;
+
+/**
+ * Below the boundary. The nav is a slide-over with nothing else to open it, so
+ * the calendar's own header carries the control — and pressing it is the whole
+ * of the way back to the mail.
+ */
+export const NavAsSlideOver: Story = {
+	args: { width: 900, isSinglePane: true },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.queryByRole("button", { name: /Inbox/ })).toBeNull();
+
+		const folders = await canvas.findByRole("button", {
+			name: "Open folders",
+		});
+		await userEvent.click(folders);
+
+		await expect(
+			await canvas.findByRole("button", { name: /Inbox/ }),
+		).toBeVisible();
+	},
+};
+
+/**
+ * Above it. The nav is a column of its own, so a second control that opened it
+ * would be a button for something already on screen.
+ */
+export const NavAsPane: Story = {
+	args: { width: 1440, isSinglePane: false },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			await canvas.findByRole("button", { name: /Inbox/ }),
+		).toBeVisible();
+		await expect(
+			canvas.queryByRole("button", { name: "Open folders" }),
+		).toBeNull();
+	},
+};

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

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { CalendarViewPlaceholder } from "./CalendarViewPlaceholder";
+
+/**
+ * A zoom the ladder offers and does not draw yet.
+ *
+ * The route is addressable at all five zooms, so two of them land on this. What
+ * it has to do is say which of the two things it is: a view that rendered
+ * nothing would be indistinguishable from a month with nothing booked in it,
+ * and the reader would plan around an empty screen.
+ */
+const meta: Meta<typeof CalendarViewPlaceholder> = {
+	title: "App/Calendar/Not built yet",
+	component: CalendarViewPlaceholder,
+	parameters: { layout: "fullscreen" },
+	render: (args) => (
+		<div className="h-dvh bg-canvas">
+			<CalendarViewPlaceholder {...args} />
+		</div>
+	),
+};
+export default meta;
+
+type Story = StoryObj<typeof CalendarViewPlaceholder>;
+
+/** It names the zoom it is waiting on, and the three that work today. */
+export const Year: Story = {
+	args: { view: "year" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.getByTestId("calendar-placeholder-year"),
+		).toHaveTextContent(
+			"The year grid arrives with the rest of the zoom ladder.",
+		);
+		await expect(canvas.getByText("Not built yet")).toBeVisible();
+		await expect(
+			canvas.getByText(/Week, Day and Agenda work now\./),
+		).toBeVisible();
+	},
+};
+
+export const Month: Story = {
+	args: { view: "month" },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(
+			canvas.getByTestId("calendar-placeholder-month"),
+		).toHaveTextContent(
+			"The month grid arrives with the rest of the zoom ladder.",
+		);
+	},
+};

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

@@ -0,0 +1,155 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+import {
+	calendars,
+	fortnight,
+	instancesWithin,
+	ROADMAP_OBJECT,
+	roadmapResource,
+	STANDUP_OBJECT,
+	STANDUP_RECURRENCE,
+	STORY_WEEK,
+	standupResource,
+} from "./calendar-story-fixtures";
+import {
+	type CalendarServer,
+	CalendarStory,
+	json,
+} from "./calendar-story-server";
+import { OpenCalendarEvent } from "./OpenCalendarEvent";
+
+/**
+ * The event the address names, and everything a reader can do to it.
+ *
+ * The pane is reached at two addresses — a resource on its own, and one
+ * occurrence under a series — and which one it is decides whether an edit has a
+ * question to answer first. That question is the state worth holding: it is
+ * asked here and nowhere else, and asking it late, on the way out, would mean
+ * the reader has already typed the change before being told what it reaches.
+ */
+
+const answering = (
+	fail?: (request: Request) => Response | undefined,
+): CalendarServer => {
+	return (request) => {
+		const refusal = fail?.(request);
+		if (refusal) return refusal;
+		const url = new URL(request.url);
+		if (url.pathname.endsWith("/calendars")) return json({ items: calendars });
+		if (url.pathname.endsWith("/calendar-events"))
+			return json({ items: instancesWithin(url, fortnight) });
+		if (url.pathname.includes(STANDUP_OBJECT)) return json(standupResource);
+		if (url.pathname.includes(ROADMAP_OBJECT)) return json(roadmapResource);
+		return json({ items: [] });
+	};
+};
+
+function Opened({
+	calendarObjectId,
+	recurrenceId,
+	server,
+}: {
+	calendarObjectId: string;
+	recurrenceId?: string;
+	server: CalendarServer;
+}) {
+	const address =
+		recurrenceId === undefined
+			? `${STORY_WEEK}/${calendarObjectId}`
+			: `${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}
+					/>
+				}
+			/>
+		</div>
+	);
+}
+
+const meta: Meta<typeof Opened> = {
+	title: "App/Calendar/Open event",
+	component: Opened,
+	parameters: { layout: "fullscreen" },
+	args: { calendarObjectId: ROADMAP_OBJECT, server: answering() },
+};
+export default meta;
+
+type Story = StoryObj<typeof Opened>;
+
+/**
+ * A resource that does not recur. Edit and Delete mean the whole of it, so
+ * there is nothing to ask and they open on the press.
+ */
+export const NonRecurring: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Roadmap review")).toBeVisible();
+		// Off the stored resource rather than the listing, so this is also the
+		// proof the pane read the version its writes will be conditional on.
+		await expect(await canvas.findByText("Room Zuid")).toBeVisible();
+		await expect(canvas.getByRole("button", { name: "Edit" })).toBeVisible();
+	},
+};
+
+/**
+ * One morning of a series. Which occurrences the edit reaches changes what the
+ * edit is, so it is settled while it can still be answered — and the rule is
+ * read back in words, not as an RRULE.
+ */
+export const RecurringScopePrompt: Story = {
+	args: {
+		calendarObjectId: STANDUP_OBJECT,
+		recurrenceId: STANDUP_RECURRENCE,
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByText("Standup")).toBeVisible();
+		await expect(
+			canvas.queryByText("What should the change apply to?"),
+		).toBeNull();
+
+		await userEvent.click(await canvas.findByRole("button", { name: "Edit" }));
+
+		await expect(await canvas.findByText("Standup repeats")).toBeVisible();
+		await expect(
+			canvas.getByText("What should the change apply to?"),
+		).toBeVisible();
+		await expect(
+			canvas.getByRole("button", { name: /This event/ }),
+		).toBeVisible();
+		await expect(
+			canvas.getByRole("button", { name: /The whole series/ }),
+		).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
+ * where the reader is looking rather than resolving it by winning.
+ */
+export const ChangedElsewhere: Story = {
+	args: {
+		server: answering((request) =>
+			request.method === "DELETE"
+				? json({ message: "The event has changed." }, 412)
+				: undefined,
+		),
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(
+			await canvas.findByRole("button", { name: "Delete" }),
+		);
+		await expect(await canvas.findByRole("alert")).toHaveTextContent(
+			/changed somewhere else/,
+		);
+	},
+};

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

@@ -0,0 +1,89 @@
+import type { CalendarSlotPick } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { calendars, STORY_DATE, STORY_WEEK } from "./calendar-story-fixtures";
+import {
+	type CalendarServer,
+	CalendarStory,
+	json,
+} from "./calendar-story-server";
+import { WriteCalendarEvent } from "./WriteCalendarEvent";
+
+/**
+ * Writing a new event, at `/calendar/{view}/{date}/new`.
+ *
+ * The draft it opens on comes from two places and neither is a prop: the day is
+ * the address's, and the hours are the slot the reader dragged out of the grid,
+ * handed over by the click that opened the form. The slot is deliberately not in
+ * the URL — a half-written event is not a fact about where the reader is — so
+ * the composer opened any other way starts on the day the calendar is showing,
+ * which is the second story here.
+ */
+
+const server: CalendarServer = (request) => {
+	const url = new URL(request.url);
+	if (url.pathname.endsWith("/calendars")) return json({ items: calendars });
+	return json({ items: [] });
+};
+
+const slot: CalendarSlotPick = {
+	date: "2026-06-11",
+	startTime: "14:00",
+	endTime: "15:00",
+	allDay: false,
+};
+
+function Composer({ pick }: { pick?: CalendarSlotPick }) {
+	return (
+		<div className="h-dvh max-w-2xl border-l border-line bg-canvas">
+			<CalendarStory
+				entry={`${STORY_WEEK}/new`}
+				server={server}
+				pick={pick}
+				pane={<WriteCalendarEvent onClose={() => undefined} />}
+			/>
+		</div>
+	);
+}
+
+const meta: Meta<typeof Composer> = {
+	title: "App/Calendar/Write event",
+	component: Composer,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof Composer>;
+
+/**
+ * Dragged out of Thursday afternoon. The hours the reader picked are already in
+ * the form, so the gesture is the answer rather than a hint they now retype.
+ */
+export const SeededFromASlotPick: Story = {
+	args: { pick: slot },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByLabelText("Date")).toHaveValue(slot.date);
+		await expect(canvas.getByLabelText("Start time")).toHaveValue(
+			slot.startTime,
+		);
+		await expect(canvas.getByLabelText("End time")).toHaveValue(slot.endTime);
+		await expect(canvas.getByLabelText("Title")).toHaveValue("");
+	},
+};
+
+/**
+ * Opened with no slot behind it. It starts on the day the calendar is showing,
+ * and on the calendar the listing provisioned — a reader who has written nothing
+ * yet should not have to choose where it goes before they can type.
+ */
+export const Empty: Story = {
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(await canvas.findByLabelText("Date")).toHaveValue(STORY_DATE);
+		await expect(canvas.getByLabelText("Title")).toHaveValue("");
+		await expect(
+			await canvas.findByRole("radio", { name: "Northwind" }),
+		).toBeChecked();
+	},
+};

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

@@ -0,0 +1,137 @@
+import type {
+	RemitImapCalendarEventInstance,
+	RemitImapCalendarEventResponse,
+	RemitImapCalendarResponse,
+} from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * The synthetic account the calendar stories read.
+ *
+ * One collection, on a real zone, with occurrences spelled the way the listing
+ * spells them. Nothing here is anybody's data: the ids are fixed strings and the
+ * week is one the calendar will never be looking at by accident.
+ */
+
+export const WORK_CALENDAR = "11111111-1111-4111-8111-111111111111";
+export const ROADMAP_OBJECT = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+export const STANDUP_OBJECT = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+export const STANDUP_RECURRENCE = "2026-06-10T07:15:00Z";
+
+export const STORY_DATE = "2026-06-10";
+export const STORY_WEEK = `/calendar/week/${STORY_DATE}`;
+
+export const calendars: RemitImapCalendarResponse[] = [
+	{
+		calendarId: WORK_CALENDAR,
+		accountConfigId: "cfg-story",
+		urlSegment: "work",
+		displayName: "Northwind",
+		color: "Cal1",
+		componentSet: "VeventOnly",
+		source: "UserCreated",
+		timezone: "Europe/Amsterdam",
+		syncSequence: 1,
+		createdAt: 0,
+		updatedAt: 0,
+	} as RemitImapCalendarResponse,
+];
+
+const template = {
+	calendarId: WORK_CALENDAR,
+	calendarObjectId: ROADMAP_OBJECT,
+	recurrenceId: "",
+	icalUid: "uid-roadmap",
+	summary: "",
+	start: "",
+	end: "",
+	allDay: false,
+	status: "Confirmed",
+	transparency: "Opaque",
+	zoneCertainty: "Explicit",
+	etag: "etag-1",
+	hasRecurrence: false,
+} as RemitImapCalendarEventInstance;
+
+const at = (
+	summary: string,
+	day: string,
+	from: string,
+	to: string,
+	over: Partial<RemitImapCalendarEventInstance> = {},
+): RemitImapCalendarEventInstance =>
+	({
+		...template,
+		...over,
+		summary,
+		start: `2026-06-${day}T${from}:00+02:00`,
+		end: `2026-06-${day}T${to}:00+02:00`,
+	}) as RemitImapCalendarEventInstance;
+
+export const roadmap = at("Roadmap review", "10", "10:00", "11:30");
+
+export const standup = at("Standup", "10", "09:15", "09:30", {
+	calendarObjectId: STANDUP_OBJECT,
+	icalUid: "uid-standup",
+	recurrenceId: STANDUP_RECURRENCE,
+	hasRecurrence: true,
+});
+
+/** A fortnight that is mostly empty, which is what a real fortnight looks like. */
+export const fortnight: RemitImapCalendarEventInstance[] = [
+	standup,
+	roadmap,
+	at("Dentist", "11", "11:00", "12:00", { icalUid: "uid-dentist" }),
+	at("Retro", "18", "16:00", "17:00", { icalUid: "uid-retro" }),
+];
+
+export const roadmapResource = {
+	calendarObjectId: ROADMAP_OBJECT,
+	calendarId: WORK_CALENDAR,
+	resourceName: "roadmap.ics",
+	icalUid: "uid-roadmap",
+	icalData: [
+		"BEGIN:VCALENDAR",
+		"BEGIN:VEVENT",
+		"SUMMARY:Roadmap review",
+		"LOCATION:Room Zuid",
+		"DESCRIPTION:Bring the staffing numbers.",
+		"END:VEVENT",
+		"END:VCALENDAR",
+	].join("\r\n"),
+	etag: "etag-1",
+} as RemitImapCalendarEventResponse;
+
+export const standupResource = {
+	...roadmapResource,
+	calendarObjectId: STANDUP_OBJECT,
+	resourceName: "standup.ics",
+	icalUid: "uid-standup",
+	icalData: [
+		"BEGIN:VCALENDAR",
+		"BEGIN:VEVENT",
+		"SUMMARY:Standup",
+		"RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
+		"END:VEVENT",
+		"END:VCALENDAR",
+	].join("\r\n"),
+} as RemitImapCalendarEventResponse;
+
+/**
+ * The occurrences inside the window a request asked for.
+ *
+ * The panes read a week at a time and hold several weeks at once, so a server
+ * that answered every window with the same list would draw each day's events
+ * once per window it appears in.
+ */
+export const instancesWithin = (
+	url: URL,
+	instances: readonly RemitImapCalendarEventInstance[],
+): RemitImapCalendarEventInstance[] => {
+	const from = Date.parse(url.searchParams.get("from") ?? "");
+	const to = Date.parse(url.searchParams.get("to") ?? "");
+	if (Number.isNaN(from) || Number.isNaN(to)) return [...instances];
+	return instances.filter((instance) => {
+		const start = Date.parse(instance.start);
+		return start >= from && start < to;
+	});
+};

package/src/components/calendar/calendar-story-server.tsx

@@ -0,0 +1,152 @@
+import type { CalendarSlotPick } from "@remit/ui";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { type ReactNode, useState } from "react";
+import { CalendarComposeSeedProvider } from "@/components/calendar/CalendarComposeSeed";
+import { calendarSearchSchema } from "@/lib/calendar-route";
+import { client } from "@/lib/client";
+import { stringifySearch } from "@/lib/search-params";
+
+/**
+ * The calendar's addresses and its server, stood up for a story.
+ *
+ * `AgendaView`, `OpenCalendarEvent` and `WriteCalendarEvent` are the three panes
+ * that read the address and read the API, so a story cannot hand them props:
+ * what they draw comes out of a URL and a response. Both are supplied here, with
+ * synthetic answers, so the story still names one state and asserts it.
+ *
+ * The routes are built out of the real paths rather than out of the generated
+ * tree — the route objects are module singletons and re-parenting one would
+ * mutate it for every other story in the run. Their ids are what the panes read
+ * their params `from`, which is what makes these the app's addresses rather than
+ * an imitation of them.
+ *
+ * The server is the app's own generated client with its `fetch` swapped, so the
+ * responses run through the same error interceptor the app installs: a 412 comes
+ * back as the conflict the pane states, and not as a message it happens to
+ * print.
+ */
+
+/** A reply to one request, at a status the client classifies the way it would. */
+export const json = (body: unknown, status = 200): Response =>
+	new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+
+/** A request that never comes back, which is what a loading state is. */
+export const never = (): Promise<Response> => new Promise<Response>(() => {});
+
+export type CalendarServer = (request: Request) => Response | Promise<Response>;
+
+/** Nowhere. Every request is answered before it can leave. */
+const STORY_BASE_URL = "https://calendar.story.invalid";
+
+function storyRouter(
+	entry: string,
+	pane: ReactNode,
+	pick: CalendarSlotPick | undefined,
+): AnyRouter {
+	const leaf = () => <>{pane}</>;
+	const rootRoute = createRootRoute({ component: Outlet });
+	const viewRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/calendar/$view/$date",
+		validateSearch: calendarSearchSchema,
+		component: () => (
+			<CalendarComposeSeedProvider pick={pick}>
+				<Outlet />
+			</CalendarComposeSeedProvider>
+		),
+	});
+	const eventRoute = createRoute({
+		getParentRoute: () => viewRoute,
+		path: "$calendarObjectId",
+		component: Outlet,
+	});
+	const routeTree = rootRoute.addChildren([
+		viewRoute.addChildren([
+			createRoute({
+				getParentRoute: () => viewRoute,
+				path: "/",
+				component: leaf,
+			}),
+			createRoute({
+				getParentRoute: () => viewRoute,
+				path: "new",
+				component: leaf,
+			}),
+			eventRoute.addChildren([
+				createRoute({
+					getParentRoute: () => eventRoute,
+					path: "/",
+					component: leaf,
+				}),
+				createRoute({
+					getParentRoute: () => eventRoute,
+					path: "$recurrenceId",
+					component: leaf,
+				}),
+			]),
+		]),
+	]);
+	return createRouter({
+		routeTree,
+		stringifySearch,
+		history: createMemoryHistory({ initialEntries: [entry] }),
+	}) as unknown as AnyRouter;
+}
+
+export interface CalendarStoryProps {
+	/** The pane under test, mounted at whichever address the story opens on. */
+	pane: ReactNode;
+	/** The address the story opens on. */
+	entry: string;
+	/** What the server answers, request by request. */
+	server: CalendarServer;
+	/** The slot a reader dragged out of the grid, for the composer. */
+	pick?: CalendarSlotPick;
+}
+
+export function CalendarStory({
+	pane,
+	entry,
+	server,
+	pick,
+}: CalendarStoryProps) {
+	// Built once, and the client configured before anything can ask it a
+	// question: a pane that fetched against the default host would reach for the
+	// network on its first render.
+	const [mounted] = useState(() => {
+		client.setConfig({
+			baseUrl: STORY_BASE_URL,
+			fetch: ((input: RequestInfo | URL) =>
+				Promise.resolve(
+					server(input instanceof Request ? input : new Request(String(input))),
+				)) as typeof globalThis.fetch,
+		});
+		return {
+			router: storyRouter(entry, pane, pick),
+			queryClient: new QueryClient({
+				defaultOptions: {
+					queries: { retry: false },
+					mutations: { retry: false },
+				},
+			}),
+		};
+	});
+
+	return (
+		<QueryClientProvider client={mounted.queryClient}>
+			<RouterProvider router={mounted.router} />
+		</QueryClientProvider>
+	);
+}

package/src/index.css

@@ -4,6 +4,13 @@
    the .dark ancestor scope used everywhere in this app. */
 @import "@remit/ui/tokens.css";
 
+/* The structural sheet the calendar grid's engine needs, which the kit ships
+   beside the component and every app that mounts it has to ask for. Without it
+   the week and day grids collapse into a stack and draw no events at all: the
+   engine lays its columns out against this sheet, and a column with no
+   geometry has nowhere to put an occurrence. */
+@import "@remit/ui/calendar.css";
+
 /* Tailwind v4 content scanning: name every source Tailwind must inspect for
    utility class usage. Automatic detection is rooted at the Vite root, which
    for the distributor harness build is a throwaway directory holding only the