@remit/web-client 0.0.166 → 0.0.167

package/src/routing/compose-press-opens.render.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Every Compose press opens a composer (#719).
+ *
+ * The press used to resolve a folder to carry the reader to, and could refuse:
+ * a folder list still loading, or an account with no folders at all, left the
+ * button doing nothing but complaining. A message needs no folder to be written
+ * in now, so there is nothing left to refuse — including from `/mail` itself,
+ * which names no list because it is on its way to the brief.
+ *
+ * Closing has the same shape from the other side. Leaving is what the reader
+ * asked for, so every branch leaves rather than stranding them inside a surface
+ * they have just dismissed.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useCloseCompose, useOpenCompose } from "./compose";
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+const MAILBOX_ID = "mbx-inbox";
+
+const Press = () => {
+	const openCompose = useOpenCompose();
+	const closeCompose = useCloseCompose();
+	return createElement(
+		"div",
+		null,
+		createElement(
+			"button",
+			{ type: "button", onClick: () => openCompose() },
+			"Compose",
+		),
+		createElement(
+			"button",
+			{ type: "button", onClick: () => closeCompose() },
+			"Close",
+		),
+	);
+};
+
+const RootLayout = () =>
+	createElement("div", null, createElement(Press), createElement(Outlet));
+
+/**
+ * The real shape: the lists are siblings under `/mail`, and compose is a child
+ * of each. `/mail` itself matches no list, which is the address the redirect to
+ * the brief passes through.
+ */
+const routerAt = (href: string): AnyRouter => {
+	const rootRoute = createRootRoute({ component: RootLayout });
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: (search: Record<string, unknown>) => search,
+		component: Outlet,
+	});
+	const briefRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/brief",
+		component: Outlet,
+	});
+	const mailboxRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/$mailboxId",
+		component: Outlet,
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([
+			briefRoute.addChildren([
+				createRoute({
+					getParentRoute: () => briefRoute,
+					path: "/compose/{-$outboxMessageId}",
+					component: () => null,
+				}),
+			]),
+			mailboxRoute.addChildren([
+				createRoute({
+					getParentRoute: () => mailboxRoute,
+					path: "/compose/{-$outboxMessageId}",
+					component: () => null,
+				}),
+			]),
+		]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (router: AnyRouter): Promise<DomHarness> => {
+	const created = createDomHarness();
+	harness = created;
+	// Resolve the first match before mounting: `RouterProvider` renders its
+	// pending state until the router has loaded, and nothing here waits for it.
+	await router.load();
+	created.renderApp(createElement(RouterProvider, { router }));
+	await created.flush();
+	await created.wait(20);
+	return created;
+};
+
+const press = async (mounted: DomHarness, label: string): Promise<void> => {
+	mounted.click(mounted.byText("button", label));
+	await mounted.flush();
+	await mounted.wait(20);
+};
+
+describe("a compose press always opens a composer", () => {
+	it("opens on the list being browsed", async () => {
+		const router = routerAt("/mail/brief");
+		const mounted = await mount(router);
+
+		await press(mounted, "Compose");
+
+		assert.equal(router.state.location.pathname, "/mail/brief/compose");
+	});
+
+	it("opens on the folder being browsed", async () => {
+		const router = routerAt(`/mail/${MAILBOX_ID}`);
+		const mounted = await mount(router);
+
+		await press(mounted, "Compose");
+
+		assert.equal(router.state.location.pathname, `/mail/${MAILBOX_ID}/compose`);
+	});
+
+	// The address the redirect to the brief passes through. It names no list, and
+	// the press still has to write a message rather than report that it cannot.
+	it("opens from an address that names no list at all", async () => {
+		const router = routerAt("/mail");
+		const mounted = await mount(router);
+
+		await press(mounted, "Compose");
+
+		assert.equal(router.state.location.pathname, "/mail/brief/compose");
+	});
+});
+
+describe("closing compose always leaves", () => {
+	it("walks up to the list the surface was opened on", async () => {
+		const router = routerAt(`/mail/${MAILBOX_ID}/compose`);
+		const mounted = await mount(router);
+
+		await press(mounted, "Close");
+
+		assert.equal(router.state.location.pathname, `/mail/${MAILBOX_ID}`);
+	});
+
+	it("lands somewhere real from an address that names no list", async () => {
+		const router = routerAt("/mail");
+		const mounted = await mount(router);
+
+		await press(mounted, "Close");
+
+		assert.equal(router.state.location.pathname, "/mail/brief");
+	});
+});

package/src/routing/compose.ts

@@ -0,0 +1,220 @@
+import { useNavigate, useParams, useRouterState } from "@tanstack/react-router";
+import { useCallback } from "react";
+import { mailListRoute } from "@/lib/mail-route";
+import { useRetainOpenPanels } from "./fragment";
+
+/**
+ * The compose route under each list. The draft is an optional segment of the
+ * same route rather than a child of it, so adopting the id the first autosave
+ * creates rewrites the address without unmounting the composer.
+ */
+const BRIEF_COMPOSE = "/mail/brief/compose/{-$outboxMessageId}" as const;
+const FLAGGED_COMPOSE = "/mail/flagged/compose/{-$outboxMessageId}" as const;
+const OUTBOX_COMPOSE = "/mail/outbox/compose/{-$outboxMessageId}" as const;
+const MAILBOX_COMPOSE = "/mail/$mailboxId/compose/{-$outboxMessageId}" as const;
+
+/**
+ * The compose match, if the address has one. Each `from` names a real route, so
+ * a segment that does not exist fails to compile.
+ *
+ * A path matches one list at a time, so at most one of these answers.
+ */
+function useComposeParams(): { outboxMessageId?: string } | undefined {
+	const brief = useParams({ from: BRIEF_COMPOSE, shouldThrow: false });
+	const flagged = useParams({ from: FLAGGED_COMPOSE, shouldThrow: false });
+	const outbox = useParams({ from: OUTBOX_COMPOSE, shouldThrow: false });
+	const mailbox = useParams({ from: MAILBOX_COMPOSE, shouldThrow: false });
+	return brief ?? flagged ?? outbox ?? mailbox;
+}
+
+/**
+ * Whether the compose surface is showing.
+ *
+ * Compose is a child route of the list it was started from, so "is compose
+ * showing" is a question about the path rather than a flag somebody else has to
+ * keep in step with it.
+ */
+export function useIsComposing(): boolean {
+	return useComposeParams() !== undefined;
+}
+
+/**
+ * The draft the open composer is writing to, or `undefined` while it is still a
+ * message with nothing saved behind it.
+ *
+ * One owner: the address. A copy in React state disagrees with it the first
+ * time the reader presses Back, and the composer comes back empty over a draft
+ * row that is still listed.
+ */
+export function useComposeDraftId(): string | undefined {
+	return useComposeParams()?.outboxMessageId;
+}
+
+/**
+ * The list the address is browsing, as the two values a navigation to it needs.
+ * Both are primitives, so a caller holding them in a dependency array settles.
+ */
+function useBrowsedList(): {
+	list: "brief" | "flagged" | "outbox" | "mailbox" | undefined;
+	mailboxId: string | undefined;
+} {
+	const list = useRouterState({
+		select: (state) => mailListRoute(state.matches)?.list,
+	});
+	const mailbox = useParams({ from: "/mail/$mailboxId", shouldThrow: false });
+	return { list, mailboxId: mailbox?.mailboxId };
+}
+
+interface ComposeNavigation {
+	/** Which list's compose route, and the draft segment under it. */
+	to: typeof BRIEF_COMPOSE | typeof FLAGGED_COMPOSE | typeof OUTBOX_COMPOSE;
+	params: { outboxMessageId: string | undefined };
+}
+
+interface MailboxComposeNavigation {
+	to: typeof MAILBOX_COMPOSE;
+	params: { mailboxId: string; outboxMessageId: string | undefined };
+}
+
+/**
+ * Where compose opens: the list being browsed, or the brief.
+ *
+ * Every case lands on a composer. The brief is the fallback rather than a
+ * refusal because it always exists and always mounts the surface, so the two
+ * addresses that name no folder — `/mail` on its way to the brief, and a folder
+ * route in the frame before its id resolves — open a composer instead of
+ * explaining why they cannot. A press that reports rather than writes is the
+ * dead button this change deletes, and neither case has anything to report:
+ * a message needs no folder to be written in.
+ */
+function composeTarget(
+	list: "brief" | "flagged" | "outbox" | "mailbox" | undefined,
+	mailboxId: string | undefined,
+	outboxMessageId: string | undefined,
+): ComposeNavigation | MailboxComposeNavigation {
+	if (list === "flagged")
+		return { to: FLAGGED_COMPOSE, params: { outboxMessageId } };
+	if (list === "outbox")
+		return { to: OUTBOX_COMPOSE, params: { outboxMessageId } };
+	if (list === "mailbox" && mailboxId)
+		return { to: MAILBOX_COMPOSE, params: { mailboxId, outboxMessageId } };
+	return { to: BRIEF_COMPOSE, params: { outboxMessageId } };
+}
+
+/**
+ * Navigate to compose on the list being browsed, on the draft named or on none.
+ *
+ * The draft travels as an argument rather than being set somewhere first: an
+ * opener that had to do both could do only one, and the composer would come up
+ * on whatever the last one left behind.
+ */
+function useComposeNavigate(): (
+	outboxMessageId: string | undefined,
+	options?: { replace?: boolean; keepPanels?: boolean },
+) => void {
+	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
+	const { list, mailboxId } = useBrowsedList();
+
+	return useCallback(
+		(
+			outboxMessageId: string | undefined,
+			options?: { replace?: boolean; keepPanels?: boolean },
+		) => {
+			navigate({
+				...composeTarget(list, mailboxId, outboxMessageId),
+				search: (prev: Record<string, unknown>) => prev,
+				// Opening or closing the surface is going somewhere, so the panes the
+				// reader keeps up travel and the overlays they were reading over do
+				// not. Recording the draft is not going anywhere — the address is
+				// rewritten under a composer they are still typing in — so whatever is
+				// up stays up, sheet included.
+				hash: options?.keepPanels ? true : retainPanels,
+				replace: options?.replace ?? false,
+			});
+		},
+		[navigate, retainPanels, list, mailboxId],
+	);
+}
+
+/**
+ * Start a new message.
+ *
+ * Takes nothing, because it is wired straight to buttons and key handlers: an
+ * optional draft argument here would quietly receive a click event instead.
+ * Resuming a draft is `useEditDraft`, which says so.
+ *
+ * A push, so Back leaves the surface and returns whatever it was opened over,
+ * and the query travels with it — a compose started mid-search is still inside
+ * that search.
+ */
+export function useOpenCompose(): () => void {
+	const openCompose = useComposeNavigate();
+	return useCallback(() => openCompose(undefined), [openCompose]);
+}
+
+/** Resume a draft: the same surface, addressed at what it is editing. */
+export function useEditDraft(): (outboxMessageId: string) => void {
+	const openCompose = useComposeNavigate();
+	return useCallback(
+		(outboxMessageId: string) => openCompose(outboxMessageId),
+		[openCompose],
+	);
+}
+
+/**
+ * Record the draft the composer just created, in the address.
+ *
+ * A replace, and every panel left alone: the reader started one message, so the
+ * draft arriving under it is neither another step of history nor a move away
+ * from whatever they have open over the composer.
+ */
+export function useAdoptComposeDraft(): (outboxMessageId: string) => void {
+	const openCompose = useComposeNavigate();
+	return useCallback(
+		(outboxMessageId: string) =>
+			openCompose(outboxMessageId, { replace: true, keepPanels: true }),
+		[openCompose],
+	);
+}
+
+/**
+ * Close compose, landing back on the list it was opened from.
+ *
+ * A push, like opening it: closing a surface moves the reader on, and Back is
+ * how they undo that. Replacing the entry instead makes the press after a close
+ * do nothing at all, because the entry behind it is the list they are already
+ * looking at.
+ *
+ * Every branch leaves, the brief included. Leaving is what the reader asked
+ * for, so a case this cannot name has to put them somewhere real rather than
+ * return and strand them inside a surface they just dismissed.
+ */
+export function useCloseCompose(): () => void {
+	const navigate = useNavigate();
+	const retainPanels = useRetainOpenPanels();
+	const { list, mailboxId } = useBrowsedList();
+
+	return useCallback(() => {
+		const search = (prev: Record<string, unknown>) => prev;
+		const hash = retainPanels;
+		if (list === "flagged") {
+			navigate({ to: "/mail/flagged", search, hash });
+			return;
+		}
+		if (list === "outbox") {
+			navigate({ to: "/mail/outbox", search, hash });
+			return;
+		}
+		if (list === "mailbox" && mailboxId) {
+			navigate({
+				to: "/mail/$mailboxId",
+				params: { mailboxId },
+				search,
+				hash,
+			});
+			return;
+		}
+		navigate({ to: "/mail/brief", search, hash });
+	}, [navigate, retainPanels, list, mailboxId]);
+}

package/src/routing/index.ts

@@ -1,3 +1,11 @@
+export {
+	useAdoptComposeDraft,
+	useCloseCompose,
+	useComposeDraftId,
+	useEditDraft,
+	useIsComposing,
+	useOpenCompose,
+} from "./compose";
 export {
 	formatOpenPanels,
 	isOverlayPanel,