@remit/web-client 0.0.178 → 0.0.180

package/src/lib/mail-route.test.ts

@@ -2,9 +2,9 @@
  * Three contracts, each of which has already cost a regression.
  *
  * The list is read off a matched route id, never the parent /mail layout's
- * pathname: that pathname is "/mail" on every child route, and keying off it
- * routed every mailbox through the brief pane, so the message-row anchors
- * vanished.
+ * own pathname: that pathname is "/mail" on every child route, and keying off
+ * it routed every mailbox through the brief pane, so the message-row anchors
+ * vanished. The location's pathname is the whole address and says which list.
  *
  * The view key of a list equals the view key of anything nested under it. A
  * thread is a child route of the list it was opened from, so a key that moved
@@ -12,13 +12,15 @@
  * the view — and the query they had just typed would be re-seeded from the URL
  * and disappear the moment they opened a hit.
  *
- * And "am I the current list" is answered by the pathname, not by the matches,
+ * And "where is the reader" is answered by the pathname, not by the matches,
  * because the matches lag a navigation by as long as the destination takes to
- * mount.
+ * mount — both for "am I the current list" and for which view the search field
+ * is searching (#808).
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
+	addressQuery,
 	locationIsOnList,
 	locationOpensDetail,
 	MAIL_BRIEF_ROUTE_ID,
@@ -26,6 +28,7 @@ import {
 	MAIL_MAILBOX_ROUTE_ID,
 	MAIL_OUTBOX_ROUTE_ID,
 	type MailRouteMatch,
+	mailboxViewKey,
 	mailListRoute,
 	mailViewKey,
 } from "./mail-route.js";
@@ -85,47 +88,57 @@ describe("mailListRoute", () => {
 
 describe("mailViewKey", () => {
 	it("gives the four lists four distinct keys", () => {
-		const keys = [brief, flagged, outbox, mailbox].map(mailViewKey);
+		const keys = [
+			"/mail/brief",
+			"/mail/flagged",
+			"/mail/outbox",
+			"/mail/inbox-1",
+		].map(mailViewKey);
 		assert.equal(new Set(keys).size, 4);
 	});
 
 	it("distinguishes two mailboxes", () => {
 		assert.notEqual(
-			mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID], { mailboxId: "inbox-1" })),
-			mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID], { mailboxId: "archive-1" })),
+			mailViewKey("/mail/inbox-1"),
+			mailViewKey("/mail/archive-1"),
 		);
 	});
 
 	it("is empty outside the mail shell", () => {
-		assert.equal(mailViewKey([{ routeId: "__root__" }]), "");
+		assert.equal(mailViewKey("/onboarding"), "");
 	});
 
-	it("is empty on a mailbox route whose param has not resolved", () => {
-		assert.equal(mailViewKey(matches([MAIL_MAILBOX_ROUTE_ID])), "");
+	it("is empty on /mail itself, which names no list", () => {
+		assert.equal(mailViewKey("/mail"), "");
+	});
+
+	it("reads the list from the address the router has committed", () => {
+		// The matches lag a navigation by as long as the destination takes to
+		// mount, and the search field follows the address: text typed once this
+		// says the next mailbox is that mailbox's query, not the previous view's.
+		assert.equal(mailViewKey("/mail/inbox-1"), mailboxViewKey("inbox-1"));
+		assert.equal(mailViewKey("/mail/brief"), MAIL_BRIEF_ROUTE_ID);
+		assert.equal(mailViewKey("/mail/flagged"), MAIL_FLAGGED_ROUTE_ID);
+		assert.equal(mailViewKey("/mail/outbox"), MAIL_OUTBOX_ROUTE_ID);
 	});
 
 	// The trap: opening a thread must not read as leaving the list, or the
 	// search field re-seeds and the typed query is gone.
 	it("gives a list and its open thread the same key", () => {
-		const lists: [readonly string[], Record<string, string> | undefined][] = [
-			[[MAIL_BRIEF_ROUTE_ID], undefined],
-			[[MAIL_FLAGGED_ROUTE_ID], undefined],
-			[[MAIL_OUTBOX_ROUTE_ID], undefined],
-			[[MAIL_MAILBOX_ROUTE_ID], { mailboxId: "inbox-1" }],
-		];
-
-		for (const [routeIds, params] of lists) {
-			const list = routeIds[0];
-			const thread = `${list}/$threadId`;
-			const message = `${thread}/$messageId`;
+		for (const list of [
+			"/mail/brief",
+			"/mail/flagged",
+			"/mail/outbox",
+			"/mail/inbox-1",
+		]) {
 			assert.equal(
-				mailViewKey(matches([list, thread], params)),
-				mailViewKey(matches([list], params)),
+				mailViewKey(`${list}/th-1`),
+				mailViewKey(list),
 				`${list} changes view key when a thread opens`,
 			);
 			assert.equal(
-				mailViewKey(matches([list, thread, message], params)),
-				mailViewKey(matches([list], params)),
+				mailViewKey(`${list}/th-1/msg-1`),
+				mailViewKey(list),
 				`${list} changes view key when a message expands`,
 			);
 		}
@@ -135,34 +148,23 @@ describe("mailViewKey", () => {
 	// moved when it opened would wipe the query the reader was mid-search on.
 	it("gives a list and its compose surface the same key", () => {
 		assert.equal(
-			mailViewKey(
-				matches([
-					MAIL_BRIEF_ROUTE_ID,
-					`${MAIL_BRIEF_ROUTE_ID}/compose/{-$outboxMessageId}`,
-				]),
-			),
-			mailViewKey(brief),
+			mailViewKey("/mail/brief/compose"),
+			mailViewKey("/mail/brief"),
 		);
 		assert.equal(
-			mailViewKey(
-				matches(
-					[
-						MAIL_MAILBOX_ROUTE_ID,
-						`${MAIL_MAILBOX_ROUTE_ID}/compose/{-$outboxMessageId}`,
-					],
-					{
-						mailboxId: "inbox-1",
-					},
-				),
-			),
-			mailViewKey(mailbox),
+			mailViewKey("/mail/inbox-1/compose/draft-1"),
+			mailViewKey("/mail/inbox-1"),
 		);
 	});
 
-	it("gives a list and its reading-pane index child the same key", () => {
+	it("ignores a query string and a fragment", () => {
 		assert.equal(
-			mailViewKey(matches([MAIL_BRIEF_ROUTE_ID, `${MAIL_BRIEF_ROUTE_ID}/`])),
-			mailViewKey(brief),
+			mailViewKey("/mail/brief?q=invoice"),
+			mailViewKey("/mail/brief"),
+		);
+		assert.equal(
+			mailViewKey("/mail/brief#intelligence"),
+			mailViewKey("/mail/brief"),
 		);
 	});
 });
@@ -238,3 +240,22 @@ describe("locationOpensDetail", () => {
 		assert.equal(locationOpensDetail("/onboarding"), false);
 	});
 });
+
+describe("addressQuery", () => {
+	it("reads the query the address carries", () => {
+		assert.equal(addressQuery({ q: "invoice" }), "invoice");
+	});
+
+	it("is empty where the address carries none", () => {
+		assert.equal(addressQuery({}), "");
+		assert.equal(addressQuery({ wizard: "pick" }), "");
+	});
+
+	it("is empty for anything that is not a query string", () => {
+		// The location's search is parsed, not validated: a hand-edited `?q[]=`
+		// arrives as an array and must not reach the field as one.
+		assert.equal(addressQuery({ q: ["invoice"] }), "");
+		assert.equal(addressQuery(undefined), "");
+		assert.equal(addressQuery(null), "");
+	});
+});

package/src/lib/mail-route.ts

@@ -56,20 +56,42 @@ export function mailListRoute(
  * key of a list and of anything nested under it are equal; `lib/search-view.ts`
  * re-seeds the search field whenever this changes, and a key that moved when a
  * message opened would wipe the query the reader had just typed.
+ *
+ * Read off the location's pathname, for the reason `locationIsOnList` is: the
+ * router commits the address before it swaps the matches, and a route the
+ * reader has not visited yet has its component to fetch before it can. The
+ * search field follows the address, so text typed once the address says the
+ * next mailbox belongs to that mailbox — keying this off the matches instead
+ * made those keystrokes read as the previous view's leftovers and dropped them.
+ *
+ * The whole address, never the /mail match's own pathname, which is "/mail" on
+ * every child route.
  */
-export function mailViewKey(matches: readonly MailRouteMatch[]): string {
-	const route = mailListRoute(matches);
-	if (!route) return "";
-	switch (route.list) {
-		case "mailbox":
-			return route.mailboxId ? mailboxViewKey(route.mailboxId) : "";
-		case "flagged":
-			return MAIL_FLAGGED_ROUTE_ID;
-		case "outbox":
-			return MAIL_OUTBOX_ROUTE_ID;
-		case "brief":
-			return MAIL_BRIEF_ROUTE_ID;
-	}
+export function mailViewKey(pathname: string): string {
+	const segments = pathname.split(/[?#]/)[0].split("/").filter(Boolean);
+	if (segments[0] !== "mail") return "";
+	const list = segments[1];
+	if (!list) return "";
+	if (list === "brief") return MAIL_BRIEF_ROUTE_ID;
+	if (list === "flagged") return MAIL_FLAGGED_ROUTE_ID;
+	if (list === "outbox") return MAIL_OUTBOX_ROUTE_ID;
+	return mailboxViewKey(list);
+}
+
+/**
+ * What the address says the query is.
+ *
+ * Read off the location's own search, never off the matched route's, for the
+ * reason `mailViewKey` reads the location's pathname: the router commits the
+ * whole address at once and swaps the matches afterwards. Taking the view from
+ * one and the query from the other splits a single move in two — the field sees
+ * the mailbox it is going to next to the query of the one it is leaving, and
+ * re-seeds itself with a query the reader has already navigated away from (#47).
+ */
+export function addressQuery(search: unknown): string {
+	if (typeof search !== "object" || search === null) return "";
+	const { q } = search as { q?: unknown };
+	return typeof q === "string" ? q : "";
 }
 
 /** One mailbox's view key. Two mailboxes are two views. */

package/src/lib/search-view.test.ts

@@ -6,23 +6,13 @@
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import {
-	MAIL_BRIEF_ROUTE_ID,
-	type MailRouteMatch,
-	mailViewKey,
-} from "./mail-route.js";
+import { MAIL_BRIEF_ROUTE_ID, mailViewKey } from "./mail-route.js";
 import {
 	committedSearchQuery,
 	searchInputForView,
 	shouldMirrorQuery,
 } from "./search-view.js";
 
-const matches = (routeId: string, mailboxId?: string): MailRouteMatch[] => [
-	{ routeId: "__root__" },
-	{ routeId: "/mail" },
-	{ routeId, ...(mailboxId ? { params: { mailboxId } } : {}) },
-];
-
 describe("searchInputForView", () => {
 	it("clears the field when the destination carries no query", () => {
 		assert.equal(
@@ -173,7 +163,10 @@ describe("shouldMirrorQuery", () => {
  * both have to end it without ever writing over what the user is typing.
  */
 interface Shell {
+	/** The view the address names, which is what a render reads. */
 	viewKey: string;
+	/** The view the text in the field was typed in (`hooks/useSearchField.ts`). */
+	typedInView: string;
 	/** The path of the list whose mirror is running. */
 	listPath: string;
 	field: string;
@@ -189,10 +182,8 @@ const render = (
 	listPath = shell.listPath,
 ): Shell => {
 	const field =
-		viewKey === shell.viewKey
-			? shell.field
-			: (searchInputForView(shell.viewKey, viewKey, url) ?? shell.field);
-	return { ...shell, viewKey, listPath, field, url };
+		searchInputForView(shell.typedInView, viewKey, url) ?? shell.field;
+	return { ...shell, viewKey, typedInView: viewKey, listPath, field, url };
 };
 
 /**
@@ -213,15 +204,22 @@ const mirror = (shell: Shell, pathname = shell.listPath): Shell => {
 	return { ...shell, url: committed };
 };
 
-const typing = (shell: Shell, text: string): Shell => ({
+/**
+ * A keystroke, stamped with the view the address named when it landed. That is
+ * the address the router has already committed, which for one render is ahead
+ * of the view the shell is showing.
+ */
+const typing = (shell: Shell, text: string, atView = shell.viewKey): Shell => ({
 	...shell,
 	field: text,
+	typedInView: atView,
 });
 const settle = (shell: Shell): Shell => ({ ...shell, debounced: shell.field });
 
 describe("search across a view change", () => {
 	const searching: Shell = {
-		viewKey: mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+		viewKey: mailViewKey("/mail/inbox-1"),
+		typedInView: mailViewKey("/mail/inbox-1"),
 		listPath: "/mail/inbox-1",
 		field: "invoice",
 		debounced: "invoice",
@@ -231,12 +229,7 @@ describe("search across a view change", () => {
 	it("ends the search when the user leaves the view", () => {
 		// The nav link drops `q`, so the destination carries none.
 		const next = mirror(
-			render(
-				searching,
-				mailViewKey(matches("/mail/$mailboxId", "sent-1")),
-				"",
-				"/mail/sent-1",
-			),
+			render(searching, mailViewKey("/mail/sent-1"), "", "/mail/sent-1"),
 		);
 		assert.equal(next.field, "");
 		assert.equal(next.url, "");
@@ -248,7 +241,8 @@ describe("search across a view change", () => {
 	// the reader had just pushed, so Inbox never arrives.
 	it("does not navigate back to the list the reader is leaving", () => {
 		const brief: Shell = {
-			viewKey: mailViewKey(matches(MAIL_BRIEF_ROUTE_ID)),
+			viewKey: mailViewKey(MAIL_BRIEF_ROUTE_ID),
+			typedInView: mailViewKey(MAIL_BRIEF_ROUTE_ID),
 			listPath: MAIL_BRIEF_ROUTE_ID,
 			field: "inv",
 			debounced: "",
@@ -266,7 +260,7 @@ describe("search across a view change", () => {
 		// mirror must not write it back — that is #47 returning by another route.
 		const landed = render(
 			searching,
-			mailViewKey(matches("/mail/$mailboxId", "sent-1")),
+			mailViewKey("/mail/sent-1"),
 			"",
 			"/mail/sent-1",
 		);
@@ -280,7 +274,7 @@ describe("search across a view change", () => {
 		const next = mirror(
 			render(
 				searching,
-				mailViewKey(matches(MAIL_BRIEF_ROUTE_ID)),
+				mailViewKey(MAIL_BRIEF_ROUTE_ID),
 				"invoice",
 				MAIL_BRIEF_ROUTE_ID,
 			),
@@ -289,10 +283,27 @@ describe("search across a view change", () => {
 		assert.equal(next.url, "invoice");
 	});
 
+	// #808: `waitForURL` returns on the address, so a reader — and a test — can
+	// type before the destination is on screen. That keystroke and the view
+	// change arrive in one render, and re-seeding it away left the field empty,
+	// the mirror with nothing to write, and no later render any reason to
+	// reconsider: the query never reached the URL at all.
+	it("keeps a query typed once the address already named the destination", () => {
+		const sent = mailViewKey("/mail/sent-1");
+		const typedOnArrival = typing(
+			{ ...searching, field: "", debounced: "", url: "" },
+			"invoice",
+			sent,
+		);
+		const landed = settle(render(typedOnArrival, sent, "", "/mail/sent-1"));
+		assert.equal(landed.field, "invoice");
+		assert.equal(mirror(landed).url, "invoice");
+	});
+
 	it("never clobbers characters the user is still typing", () => {
 		// Opening a result and the q-mirror both re-render the same view. Neither
 		// is a view change, so neither may reach into the field.
-		const mailbox = mailViewKey(matches("/mail/$mailboxId", "inbox-1"));
+		const mailbox = mailViewKey("/mail/inbox-1");
 		let shell = typing(
 			{ ...searching, field: "", debounced: "", url: "" },
 			"i",

package/src/lib/search-view.ts

@@ -9,19 +9,29 @@
  * URL win on every view change: the field re-seeds from the location it lands
  * on, so switching mailbox clears a stale query while a deep link or a saved
  * search that carries `q` still arrives with the query intact.
+ *
+ * "Every view change" is the move the reader made, not every render that
+ * notices one. Text typed once the address already names the destination was
+ * typed in the destination, so it is that view's query and survives
+ * (`hooks/useSearchField.ts`).
  */
 import { locationIsOnList } from "./mail-route";
 
 /**
  * The field text after a view transition, or `undefined` when nothing changes
  * (same view — typing, opening a result, mirroring `q` back to the URL).
+ *
+ * `typedInView` is the view the text in the field was written in, not the view
+ * of the previous render. The two differ for exactly one render after the
+ * address moves, which is where a keystroke that followed the move lands
+ * (#808); calling it the previous render's view re-seeded that keystroke away.
  */
 export function searchInputForView(
-	previousViewKey: string,
+	typedInView: string,
 	viewKey: string,
 	urlQuery: string,
 ): string | undefined {
-	if (previousViewKey === viewKey) return undefined;
+	if (typedInView === viewKey) return undefined;
 	return urlQuery;
 }
 
@@ -64,6 +74,15 @@ export interface MirrorDecision {
  * address is already the new one. A write from the outgoing list in that window
  * navigates back to itself, superseding the load in flight and replacing the
  * entry the reader just pushed — they click Inbox and land on the brief.
+ *
+ * The mirror asks this again whenever the address moves, not only when the
+ * field does (#808), so a settled query the URL has drifted away from is
+ * written again. That cannot loop: the answer is false the moment the URL says
+ * the committed query, which is what every write makes it say. Nor does it let
+ * the mirror fight a query arriving by URL — that arrives mid-debounce, where
+ * the first rule already refuses, and by the time the debounce settles the
+ * field has been re-seeded from the address it landed on
+ * (`hooks/useSearchField.ts`).
  */
 export function shouldMirrorQuery({
 	searchInput,

package/src/routes/mail.tsx

@@ -9,7 +9,6 @@ import {
 	Outlet,
 	useNavigate,
 	useRouterState,
-	useSearch,
 } from "@tanstack/react-router";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { z } from "zod";
@@ -19,11 +18,11 @@ import { MailTopBar } from "@/components/layout/MailTopBar";
 import { MailNav } from "@/components/mail/MailNav";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { KeyboardShortcutsModal } from "@/components/ui/KeyboardShortcutsModal";
-import { useDebouncedValue } from "@/hooks/useDebouncedValue";
 import { useKeyboardNavigation } from "@/hooks/useKeyboardNavigation";
 import { isSinglePaneTier, useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailboxNameIndex } from "@/hooks/useMailboxNameIndex";
 import { useResultFolderIndex } from "@/hooks/useResultFolderIndex";
+import { useSearchField } from "@/hooks/useSearchField";
 import { useStaleAccountSync } from "@/hooks/useStaleAccountSync";
 import {
 	readIntelligencePref,
@@ -32,9 +31,8 @@ import {
 } from "@/lib/intelligence-pref";
 import { MailContext } from "@/lib/mail-context";
 import { MailFreshnessProvider } from "@/lib/mail-freshness";
-import { mailListRoute, mailViewKey } from "@/lib/mail-route";
+import { mailListRoute } from "@/lib/mail-route";
 import { buildAccountNameIndex } from "@/lib/search-token-index";
-import { committedSearchQuery, searchInputForView } from "@/lib/search-view";
 import { wizardEntryValue, wizardStepValue } from "@/lib/wizard-history";
 import {
 	isOverlayPanel,
@@ -80,7 +78,6 @@ export const Route = createFileRoute("/mail")({
 });
 
 function MailLayout() {
-	const { q: searchQuery = "" } = useSearch({ from: "/mail" });
 	const navigate = useNavigate();
 	const tier = useLayoutTier();
 	// Below the reading boundary (phone AND tablet) the shell shows a SINGLE
@@ -141,38 +138,11 @@ function MailLayout() {
 		[intelligenceOpen, showPanels],
 	);
 
-	// Within one view, URL `q` seeds the input and is a one-directional write
-	// target: the debounced local value drives the search API and is mirrored
-	// back by the list route's own `useSearchMirror`. Across views the URL wins
-	// again — see the view-change adjustment below and `lib/search-view.ts` (#47).
-	const [searchInput, setSearchInput] = useState(searchQuery);
-	const debouncedSearchInput = useDebouncedValue(searchInput, 200);
-	const committedQuery = committedSearchQuery(
-		searchInput,
-		debouncedSearchInput,
-	);
-
-	// Search is a mode of the view it was typed in, so leaving that view re-seeds
-	// the field from wherever we land (#47): empty when the sidebar dropped `q`
-	// (a folder switch starts that folder's search fresh), and the carried query
-	// when the top bar's scope chip was removed and sent the user to the brief to
-	// search everything. Views that differ only in what is open below the list —
-	// a thread, a mirrored `q` — are the same view, so in-flight typing survives
-	// them (`searchInputForView`, `mailViewKey`).
-	//
-	// Adjusted during render, not in an effect. This is React's documented
-	// "adjusting state when a prop changes" pattern: both updates are to this
-	// component's own state and are guarded by a changed value, so React re-runs
-	// the render before committing and nothing is painted with the stale query.
-	// An effect would commit one frame carrying the previous view's text, which
-	// the mirror then has to be defended against.
-	const viewKey = useRouterState({ select: (s) => mailViewKey(s.matches) });
-	const [searchViewKey, setSearchViewKey] = useState(viewKey);
-	if (searchViewKey !== viewKey) {
-		const seeded = searchInputForView(searchViewKey, viewKey, searchQuery);
-		setSearchViewKey(viewKey);
-		if (seeded !== undefined) setSearchInput(seeded);
-	}
+	// The one search field and the query it commits (`useSearchField`): seeded
+	// from the URL, mirrored back by each list route's own `useSearchMirror`,
+	// and re-seeded from the address whenever the reader leaves the view (#47).
+	const { searchInput, committedQuery, viewKey, setSearchInput } =
+		useSearchField();
 
 	const {
 		data: config,
@@ -229,20 +199,16 @@ function MailLayout() {
 		handlers: composeHandlers,
 	});
 
-	const handleSearchChange = useCallback((query: string) => {
-		setSearchInput(query);
-	}, []);
-
 	// Clears the search field; the list route's mirror drops `q` from the URL
 	// after the debounce settles.
 	const handleSearchClear = useCallback(() => {
 		setSearchInput("");
-	}, []);
+	}, [setSearchInput]);
 
 	// Esc inside the search field clears only the query (#489).
 	const handleSearchClearQuery = useCallback(() => {
 		setSearchInput("");
-	}, []);
+	}, [setSearchInput]);
 
 	const handleToggleIntelligence = useCallback(() => {
 		handleSetIntelligenceOpen(!intelligenceOpen);
@@ -283,7 +249,7 @@ function MailLayout() {
 		searchQuery: committedQuery,
 		searchInput,
 		searchViewKey: viewKey,
-		onSearchChange: handleSearchChange,
+		onSearchChange: setSearchInput,
 		onSearchClear: handleSearchClear,
 		onSearchClearQuery: handleSearchClearQuery,
 		intelligenceOpen,