@remit/web-client 0.0.178 → 0.0.180

package/src/hooks/search-mirror-convergence.render.test.ts

@@ -0,0 +1,197 @@
+/**
+ * The mirror corrects an address that has drifted from the settled query
+ * (#808).
+ *
+ * Typing lands more than one navigation: the debounce settles mid-word, the
+ * mirror writes that prefix, and the word is finished while that write is still
+ * in flight. The two can commit out of order, and an e2e run caught the result
+ * — the field holding `invoice`, the address holding `q=invo`, and neither
+ * moving again for the remaining two minutes of the test. The mirror compared
+ * against the URL without re-running on it, so a disagreement it had not caused
+ * was permanent.
+ *
+ * Driven through a real router, because the state under test is one only the
+ * router can produce: the address is moved out from under a mirror that has
+ * already settled, with the field and the committed query left where they were.
+ * The re-render is provoked rather than awaited — this harness does not
+ * propagate a router store change into React on its own, where the running app
+ * renders on every `q` — so what each case actually asks is whether the mirror
+ * reconsiders once it renders again.
+ */
+
+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, useState } from "react";
+import { MailContext, type MailContextValue } from "@/lib/mail-context";
+import { EMPTY_RESULT_FOLDER_INDEX } from "@/lib/result-folder";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useSearchMirror } from "./useSearchMirror";
+
+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 LIST_PATH = "/mail/brief";
+const RENDER_AGAIN = "render again";
+
+const mailContext = (input: string, committed: string): MailContextValue => ({
+	accounts: [],
+	mailboxNameIndex: new Map(),
+	accountNameIndex: new Map(),
+	resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
+	searchQuery: committed,
+	searchInput: input,
+	searchViewKey: LIST_PATH,
+	onSearchChange: () => {},
+	onSearchClear: () => {},
+	onSearchClearQuery: () => {},
+	intelligenceOpen: false,
+	onToggleIntelligence: () => {},
+});
+
+/**
+ * The brief on its own. Where a correcting write lands, and what it may close
+ * under it, is `search-mirror-detail.render.test.ts`'s question; this file asks
+ * only whether the address ends up saying the settled query.
+ */
+const buildRouter = (href: string): AnyRouter => {
+	const passthrough = (search: Record<string, unknown>) => search;
+	const rootRoute = createRootRoute({ component: Outlet });
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: passthrough,
+		component: Outlet,
+	});
+	const briefRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/brief",
+		validateSearch: passthrough,
+		component: function BriefLayout() {
+			const [renders, setRenders] = useState(0);
+			useSearchMirror({ to: LIST_PATH });
+			return createElement(
+				"div",
+				null,
+				createElement(
+					"button",
+					{
+						type: "button",
+						"aria-label": RENDER_AGAIN,
+						onClick: () => setRenders(renders + 1),
+					},
+					String(renders),
+				),
+				createElement(Outlet),
+			);
+		},
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([briefRoute]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (
+	router: AnyRouter,
+	input: string,
+	committed: string,
+): Promise<DomHarness> => {
+	const created = createDomHarness();
+	harness = created;
+	await router.load();
+	created.renderApp(
+		createElement(
+			MailContext.Provider,
+			{ value: mailContext(input, committed) },
+			createElement(RouterProvider, { router }),
+		),
+	);
+	await created.flush();
+	await created.wait(20);
+	return created;
+};
+
+/**
+ * The write that was still in flight, landing after the one that followed it,
+ * and then the next render of the list it landed under.
+ */
+const driftTo = async (
+	created: DomHarness,
+	router: AnyRouter,
+	q: string | undefined,
+): Promise<void> => {
+	void router.navigate({ to: ".", search: { q }, replace: true });
+	await created.wait(20);
+	created.click(created.byLabel(RENDER_AGAIN));
+	await created.wait(50);
+};
+
+describe("an address that drifts from the settled query", () => {
+	it("is written again, rather than left on the prefix", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+		assert.match(router.history.location.search, /q=invoice/);
+
+		await driftTo(created, router, "invo");
+
+		assert.match(
+			router.history.location.search,
+			/q=invoice/,
+			"the mirror never reconsidered the address it had already agreed with",
+		);
+		assert.equal(router.history.location.pathname, LIST_PATH);
+	});
+
+	it("is written again when the query was dropped from it entirely", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+
+		await driftTo(created, router, undefined);
+
+		assert.match(router.history.location.search, /q=invoice/);
+	});
+
+	it("leaves an address that already says the settled query alone", async () => {
+		const router = buildRouter(`${LIST_PATH}?q=invoice`);
+		const created = await mount(router, "invoice", "invoice");
+		const before = router.history.length;
+
+		await driftTo(created, router, "invoice");
+
+		assert.match(router.history.location.search, /q=invoice/);
+		assert.equal(router.history.length, before);
+	});
+
+	it("does not fight a query arriving mid-debounce", async () => {
+		// A deep link or a saved search lands while the field is still catching
+		// up. The committed query is the previous one, so the mirror has nothing
+		// settled to write and must not strip what just arrived.
+		const router = buildRouter(`${LIST_PATH}?q=receipts`);
+		const created = await mount(router, "invoice", "");
+
+		created.click(created.byLabel(RENDER_AGAIN));
+		await created.wait(50);
+
+		assert.match(router.history.location.search, /q=receipts/);
+	});
+});

package/src/hooks/search-mirror-detail.render.test.ts

@@ -197,8 +197,9 @@ for (const listPath of LIST_PATHS) {
  * re-seeds on a view change, so the view key of the list and of the thread route
  * under it must be equal.
  *
- * Read off the matches the router resolved for a real address, so the ids under
- * test are the ones path segments produce rather than ids written out here.
+ * Read off the address the router committed for a real navigation, so the keys
+ * under test are the ones path segments produce rather than ids written out
+ * here.
  */
 describe("the view key of an open thread", () => {
 	const viewKeyAt = async (
@@ -207,11 +208,7 @@ describe("the view key of an open thread", () => {
 	): Promise<string> => {
 		const router = routerAt(listPath, href);
 		await router.load();
-		return mailViewKey(
-			router.state.matches.map((match: { routeId: string }) => ({
-				routeId: match.routeId,
-			})),
-		);
+		return mailViewKey(router.state.location.pathname);
 	};
 
 	for (const listPath of LIST_PATHS) {

package/src/hooks/useSearchField.render.test.ts

@@ -0,0 +1,216 @@
+/**
+ * A query typed as the reader arrives on a list (#808).
+ *
+ * Three e2e specs hung their whole timeout on `waitForURL(/q=invoice/)` because
+ * the query never reached the address at all. Typing in the window between the
+ * router committing the next mailbox and React rendering it put the keystroke
+ * and the view change in one render, where the view-change re-seed took the
+ * field back to the destination's `q` — empty. The field held nothing, so the
+ * mirror had nothing to write, and no later render had any reason to reconsider.
+ *
+ * Driven through a real router, because the window under test is the router's
+ * own: the address commits before the matches swap, and a route the reader has
+ * not visited yet has its component to fetch before it can. Reasoning about
+ * that from the outside is not evidence, so the mailbox route here loads on a
+ * delay the way an unvisited one does.
+ *
+ * The other half is here too: a query ending with the view it was typed in
+ * (#47). That window is the same one, read the other way round — the address
+ * has moved and the matches have not — and the field must re-seed from the
+ * address rather than from the query the outgoing list still answers with.
+ * `lib/search-view.test.ts` drives the rules themselves.
+ */
+
+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, useState } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useSearchField } from "./useSearchField";
+
+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 FIELD_LABEL = "Search mail";
+const MAILBOX_ID = "9f1c-abc";
+const RENDER_AGAIN = "render again";
+
+/** What the field committed, so a test can assert what the mirror would write. */
+let committed = "";
+
+/**
+ * The field, plus a way to make it render on demand. Typing renders it; a
+ * navigation on its own does not, because this harness does not propagate a
+ * router store change into React the way the running app does — so a test that
+ * only navigates is asking nothing.
+ */
+function SearchField() {
+	const { searchInput, committedQuery, setSearchInput } = useSearchField();
+	const [renders, setRenders] = useState(0);
+	committed = committedQuery;
+	return createElement(
+		"div",
+		null,
+		createElement("input", {
+			"aria-label": FIELD_LABEL,
+			value: searchInput,
+			onChange: (event: { target: { value: string } }) =>
+				setSearchInput(event.target.value),
+		}),
+		createElement(
+			"button",
+			{
+				type: "button",
+				"aria-label": RENDER_AGAIN,
+				onClick: () => setRenders(renders + 1),
+			},
+			String(renders),
+		),
+	);
+}
+
+/**
+ * The mail shell over its four lists. Only the mailbox route loads on a delay:
+ * it stands for the list the reader has not been to yet, which is the one they
+ * navigate to and then type on.
+ */
+const buildRouter = (
+	mailboxLoadMs: number,
+	href = "/mail/brief",
+): AnyRouter => {
+	const passthrough = (search: Record<string, unknown>) => search;
+	const rootRoute = createRootRoute({ component: Outlet });
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: passthrough,
+		component: () => createElement(SearchField, null),
+	});
+	const briefRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/brief",
+		validateSearch: passthrough,
+		component: () => null,
+	});
+	const mailboxRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/$mailboxId",
+		validateSearch: passthrough,
+		loader: async () => {
+			await new Promise((resolve) => setTimeout(resolve, mailboxLoadMs));
+			return null;
+		},
+		component: () => null,
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([briefRoute, mailboxRoute]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({ initialEntries: [href] }),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (
+	router: AnyRouter,
+): Promise<{ created: DomHarness; field: HTMLInputElement }> => {
+	const created = createDomHarness();
+	harness = created;
+	committed = "";
+	await router.load();
+	created.renderApp(createElement(RouterProvider, { router }));
+	await created.flush();
+	return {
+		created,
+		field: created.byLabel(FIELD_LABEL) as HTMLInputElement,
+	};
+};
+
+/** Long enough for the 200 ms debounce to settle on whatever the field holds. */
+const DEBOUNCE_SETTLED = 400;
+
+const openMailbox = (router: AnyRouter, mailboxId: string): void => {
+	void router.navigate({ to: "/mail/$mailboxId", params: { mailboxId } });
+};
+
+describe("a query the reader left behind on the previous list (#47)", () => {
+	// The sidebar link drops `q`, so the destination's address carries none. The
+	// field is re-seeded from that address and the mirror then has nothing to
+	// write, which is what keeps the query out of the next mailbox's URL.
+	for (const mailboxLoadMs of [0, 300]) {
+		it(`does not follow them into the next list (list ready in ${mailboxLoadMs}ms)`, async () => {
+			const router = buildRouter(mailboxLoadMs, "/mail/brief?q=invoice");
+			const { created, field } = await mount(router);
+			assert.equal(field.value, "invoice");
+
+			openMailbox(router, MAILBOX_ID);
+			await created.wait(10);
+			// The render inside the window the address has moved in and the
+			// matches have not: the outgoing list still answers `q=invoice`, and
+			// re-seeding from it hands the query to the mailbox being opened.
+			created.click(created.byLabel(RENDER_AGAIN));
+			await created.wait(mailboxLoadMs + DEBOUNCE_SETTLED);
+			created.click(created.byLabel(RENDER_AGAIN));
+			await created.wait(DEBOUNCE_SETTLED);
+
+			assert.equal(field.value, "");
+			assert.equal(committed, "");
+		});
+	}
+
+	it("arrives with a query the destination carries", async () => {
+		// The scope chip sends the reader to the brief to search everything, so
+		// the query travels in the address it navigates to and is kept.
+		const router = buildRouter(0, "/mail/9f1c-abc?q=invoice");
+		const { created, field } = await mount(router);
+
+		void router.navigate({ to: "/mail/brief", search: { q: "invoice" } });
+		await created.wait(10);
+		created.click(created.byLabel(RENDER_AGAIN));
+		await created.wait(DEBOUNCE_SETTLED);
+
+		assert.equal(field.value, "invoice");
+		assert.equal(committed, "invoice");
+	});
+});
+
+describe("a query typed as the reader arrives on a mailbox", () => {
+	// The address is already the mailbox — that is what `waitForURL` returns on
+	// — so the text was typed on the mailbox and is the mailbox's query.
+	for (const mailboxLoadMs of [0, 300]) {
+		it(`survives the view change it followed (list ready in ${mailboxLoadMs}ms)`, async () => {
+			const router = buildRouter(mailboxLoadMs);
+			const { created, field } = await mount(router);
+
+			openMailbox(router, MAILBOX_ID);
+			await created.wait(10);
+			assert.equal(
+				router.state.location.pathname,
+				`/mail/${MAILBOX_ID}`,
+				"the address moves before the list is on screen",
+			);
+
+			created.type(field, "invoice");
+			await created.wait(mailboxLoadMs + DEBOUNCE_SETTLED);
+
+			assert.equal(field.value, "invoice");
+			assert.equal(committed, "invoice");
+		});
+	}
+});

package/src/hooks/useSearchField.ts

@@ -0,0 +1,85 @@
+import { useRouter, useRouterState } from "@tanstack/react-router";
+import { useCallback, useState } from "react";
+import { addressQuery, mailViewKey } from "@/lib/mail-route";
+import { committedSearchQuery, searchInputForView } from "@/lib/search-view";
+import { useDebouncedValue } from "./useDebouncedValue";
+
+export interface SearchField {
+	/** The live field text, which every search surface binds. */
+	searchInput: string;
+	/** The debounced query the search APIs run and the mirror writes. */
+	committedQuery: string;
+	/** The view the field is searching (`lib/mail-route.ts`). */
+	viewKey: string;
+	/** Every write to the field — typed, cleared, or a chip edited. */
+	setSearchInput: (query: string) => void;
+}
+
+/**
+ * The one search field, held by the /mail shell so it outlives every child
+ * route, and the query it commits.
+ *
+ * Within a view the URL's `q` seeds it and is a one-directional write target:
+ * the committed value drives the search APIs and each list's `useSearchMirror`
+ * writes it back. Across views the URL wins again — search is a mode of the
+ * view it was typed in, so leaving that view re-seeds the field from wherever
+ * the reader lands (#47), empty when the sidebar dropped `q` and the carried
+ * query when the scope chip sent them to the brief to search everything.
+ *
+ * The re-seed is adjusted during render, not in an effect: React's documented
+ * "adjusting state when a prop changes" pattern, so nothing is painted carrying
+ * the previous view's text. An effect would commit one frame with the stale
+ * query in it, which the mirror then has to be defended against.
+ *
+ * Text carries the view it was typed in, rather than the field simply taking
+ * whatever the last render's view key was (#808). The address moves a render
+ * ahead of React — a keystroke and the view change it followed arrive in the
+ * same render, and the re-seed cannot tell them apart from what it has on
+ * screen. Stamping the view at the keystroke, off the address the router has
+ * already committed, says which of the two came second: type into the field
+ * once the address names the next mailbox and that text is the new view's, not
+ * a leftover of the one being left. Without it a query typed in that window was
+ * wiped in the render that followed, and since the field then held nothing the
+ * mirror had nothing to write — the query never reached the URL at all.
+ *
+ * Which view and which query both come off the committed address, never one
+ * from the address and the other from the matched route. The matches swap a
+ * render behind the address, so mixing the two reads the destination's view
+ * against the outgoing list's `q` and re-seeds the field with the query the
+ * reader has just navigated away from — the stamp then calls that text the new
+ * view's, and nothing reconsiders it (#47).
+ */
+export function useSearchField(): SearchField {
+	const router = useRouter();
+	const viewKey = useRouterState({
+		select: (state) => mailViewKey(state.location.pathname),
+	});
+	const urlQuery = useRouterState({
+		select: (state) => addressQuery(state.location.search),
+	});
+
+	const [searchInput, setInput] = useState(urlQuery);
+	const debouncedSearchInput = useDebouncedValue(searchInput, 200);
+
+	const [typedInView, setTypedInView] = useState(viewKey);
+	if (typedInView !== viewKey) {
+		const seeded = searchInputForView(typedInView, viewKey, urlQuery);
+		setTypedInView(viewKey);
+		if (seeded !== undefined) setInput(seeded);
+	}
+
+	const setSearchInput = useCallback(
+		(query: string) => {
+			setTypedInView(mailViewKey(router.state.location.pathname));
+			setInput(query);
+		},
+		[router],
+	);
+
+	return {
+		searchInput,
+		committedQuery: committedSearchQuery(searchInput, debouncedSearchInput),
+		viewKey,
+		setSearchInput,
+	};
+}

package/src/hooks/useSearchMirror.ts

@@ -1,6 +1,7 @@
-import { useNavigate, useRouterState, useSearch } from "@tanstack/react-router";
-import { useEffect, useRef } from "react";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
+import { useEffect } from "react";
 import { useMailContext } from "@/lib/mail-context";
+import { addressQuery } from "@/lib/mail-route";
 import { shouldMirrorQuery } from "@/lib/search-view";
 import { useIsComposing, useIsReplying } from "@/routing";
 
@@ -22,6 +23,20 @@ export type SearchMirrorTarget =
  * the query the user just left behind is never written onto the view they landed
  * on (`shouldMirrorQuery`).
  *
+ * It watches the URL as well as the field, so a settled query that the address
+ * stops agreeing with is written again rather than left (#808). Typing lands
+ * more than one navigation — the debounce settles mid-word, and the word is
+ * finished while that write is still in flight — and the two can commit out of
+ * order, leaving the address on the prefix. Comparing against the URL without
+ * re-running on it made that final: the field said `invoice`, the address said
+ * `invo`, and nothing was left to disagree with. Re-running cannot start a
+ * loop, because every write makes the URL equal the committed query and the
+ * next run has nothing to do. The `q` it compares against is the committed
+ * address's, the same place the pathname below comes from: the matched route
+ * answers with the outgoing list's query for a render after the address has
+ * moved on, and a mirror reading one from each would write against a URL that
+ * no longer exists.
+ *
  * It also writes only while the reader is still on this list. A list stays
  * mounted, effects and all, until the list they navigated to is ready to paint,
  * and by then the address is already the new one — so a debounce settling in
@@ -51,17 +66,14 @@ export type SearchMirrorTarget =
 export function useSearchMirror(target: SearchMirrorTarget): void {
 	const navigate = useNavigate();
 	const { searchInput, searchQuery: committedQuery } = useMailContext();
-	const { q: urlQuery = "" } = useSearch({ from: "/mail" });
+	const urlQuery = useRouterState({
+		select: (s) => addressQuery(s.location.search),
+	});
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	const isComposing = useIsComposing();
 	const isReplying = useIsReplying();
 	const isWriting = isComposing || isReplying;
 
-	// Read at effect time rather than depended on: the URL is what the mirror
-	// compares against, not what re-triggers it.
-	const urlQueryRef = useRef(urlQuery);
-	urlQueryRef.current = urlQuery;
-
 	const { to } = target;
 	const mailboxId = "params" in target ? target.params.mailboxId : undefined;
 	const listPath = mailboxId ? `/mail/${mailboxId}` : to;
@@ -70,13 +82,13 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 		const mayWrite = shouldMirrorQuery({
 			searchInput,
 			committedQuery,
-			urlQuery: urlQueryRef.current,
+			urlQuery,
 			pathname,
 			listPath,
 		});
 		if (!mayWrite) return;
 		const queryGoesActive =
-			Boolean(committedQuery) && urlQueryRef.current !== committedQuery;
+			Boolean(committedQuery) && urlQuery !== committedQuery;
 		// A message being written is the reader's own, not a leftover of the list
 		// they were on, so a query going active narrows the list behind it and
 		// leaves it where it is.
@@ -106,6 +118,7 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 	}, [
 		searchInput,
 		committedQuery,
+		urlQuery,
 		navigate,
 		to,
 		mailboxId,