@remit/web-client 0.0.145 → 0.0.147

package/src/hooks/useSearchMirror.ts

@@ -28,14 +28,19 @@ export type SearchMirrorTarget =
  * flight and replacing the entry the reader had just pushed. They would click
  * Inbox and land back on the brief.
  *
- * When a query *goes* active it also strips the selection so the reading pane
- * closes (#539): an open message from the pre-search list is not meaningful in
- * the search result set. Only on that transition though — tapping a search
- * result commits the same `q` with the selection, so when `prev.q` already
- * equals the query the result was opened under it (not a pre-search leftover)
- * and must survive. The strip otherwise raced the tap: the row shows before the
- * debounce settles, so this mirror can land just after the open and close it
- * again.
+ * When a query *goes* active it also closes the reading pane (#539): an open
+ * message from the pre-search list is not meaningful in the search result set.
+ * The close is a navigation to the list route, which unmatches the thread that
+ * was open under it — plus, until the remaining lists move their selection into
+ * the path, dropping the params they still read it from. Any other write keeps
+ * the address it found: mirroring a query the reader is editing, or clearing
+ * one, must not shut the conversation they are reading.
+ *
+ * Only on that transition, though — tapping a search result commits the same `q`
+ * with the open thread, so when the URL already says the query the conversation
+ * was opened under it (not a pre-search leftover) and must survive. The close
+ * otherwise raced the tap: the row shows before the debounce settles, so this
+ * mirror can land just after the open and undo it.
  */
 export function useSearchMirror(target: SearchMirrorTarget): void {
 	const navigate = useNavigate();
@@ -61,20 +66,23 @@ export function useSearchMirror(target: SearchMirrorTarget): void {
 			listPath,
 		});
 		if (!mayWrite) return;
-		const search = (prev: Record<string, unknown>) => {
-			const queryAlreadyActive = prev.q === committedQuery;
-			return {
-				...prev,
-				q: committedQuery || undefined,
-				...(committedQuery && !queryAlreadyActive
-					? {
-							selectedMessageId: undefined,
-							selectedThreadId: undefined,
-							selectedMailboxId: undefined,
-						}
-					: {}),
-			};
-		};
+		const queryGoesActive =
+			Boolean(committedQuery) && urlQueryRef.current !== committedQuery;
+		const search = (prev: Record<string, unknown>) => ({
+			...prev,
+			q: committedQuery || undefined,
+			...(queryGoesActive
+				? {
+						selectedMessageId: undefined,
+						selectedThreadId: undefined,
+						selectedMailboxId: undefined,
+					}
+				: {}),
+		});
+		if (!queryGoesActive) {
+			navigate({ to: ".", search, replace: true });
+			return;
+		}
 		if (to === "/mail/$mailboxId") {
 			if (!mailboxId) return;
 			navigate({ to, params: { mailboxId }, search, replace: true });

package/src/hooks/useSearchScope.ts

@@ -39,7 +39,7 @@ export function useSearchScope(accounts: RemitImapAccountResponse[]): {
 			if (chipId !== SEARCH_SCOPE_CHIP_ID) return;
 			navigate({
 				to: "/mail/brief",
-				search: { q: searchInput || undefined, selectedMessageId: undefined },
+				search: { q: searchInput || undefined },
 			});
 		},
 		[navigate, searchInput],

package/src/hooks/useThreadRow.ts

@@ -0,0 +1,35 @@
+import { threadDetailOperationsListThreadMessagesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * A thread's own row for the message the reader pointed at.
+ *
+ * This is how a conversation answers for itself when no list holds it — a
+ * cross-folder search hit, or an address pasted into a fresh tab.
+ * `GET /threads/{threadId}/messages` returns the same row shape a listing does,
+ * `mailboxId` included, so the thread id is the whole address even though the
+ * mail is filed in some folder. The reading pane already makes that request, so
+ * this resolves off the same cache entry rather than a round trip of its own.
+ *
+ * A thread spans folders — the reader's own reply sits in Sent — so `messageId`
+ * picks the row they pointed at. With none, the newest message answers.
+ */
+export const useThreadRow = (
+	threadId: string | undefined,
+	messageId: string | undefined,
+): RemitImapThreadMessageResponse | undefined => {
+	const { data } = useQuery({
+		...threadDetailOperationsListThreadMessagesOptions({
+			path: { threadId: threadId ?? "" },
+		}),
+		enabled: Boolean(threadId),
+	});
+
+	const items = data?.items ?? [];
+	const pointedAt = messageId
+		? items.find((item) => item.messageId === messageId)
+		: undefined;
+	const newest = items.length > 0 ? items[items.length - 1] : undefined;
+	return pointedAt ?? newest;
+};

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

@@ -20,6 +20,7 @@ import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
 	locationIsOnList,
+	locationOpensDetail,
 	MAIL_BRIEF_ROUTE_ID,
 	MAIL_FLAGGED_ROUTE_ID,
 	MAIL_MAILBOX_ROUTE_ID,
@@ -178,3 +179,28 @@ describe("locationIsOnList", () => {
 		assert.equal(locationIsOnList("/mail/outbox-2024", "/mail/outbox"), false);
 	});
 });
+
+/**
+ * What "a thread is open" used to be asked of the query. Everything sharing the
+ * single pane with the conversation reads it from the address instead.
+ */
+describe("locationOpensDetail", () => {
+	it("is true for a thread and for the message inside it", () => {
+		assert.equal(locationOpensDetail("/mail/brief/thread-1"), true);
+		assert.equal(locationOpensDetail("/mail/brief/thread-1/message-1"), true);
+		assert.equal(locationOpensDetail("/mail/inbox-1/thread-1"), true);
+	});
+
+	it("is false on a bare list, trailing slash and query included", () => {
+		assert.equal(locationOpensDetail("/mail/brief"), false);
+		assert.equal(locationOpensDetail("/mail/brief/"), false);
+		assert.equal(locationOpensDetail("/mail/brief?q=invoice"), false);
+		assert.equal(locationOpensDetail("/mail/inbox-1"), false);
+		assert.equal(locationOpensDetail("/mail"), false);
+	});
+
+	it("is false outside the mail shell", () => {
+		assert.equal(locationOpensDetail("/settings/accounts"), false);
+		assert.equal(locationOpensDetail("/onboarding"), false);
+	});
+});

package/src/lib/mail-route.ts

@@ -92,3 +92,16 @@ export function locationIsOnList(pathname: string, listPath: string): boolean {
 	if (pathname === listPath) return true;
 	return pathname.startsWith(`${listPath}/`);
 }
+
+/**
+ * Whether the address names something the list has open below it — a thread, a
+ * message. A list on its own, and its bare reading pane, do not.
+ *
+ * Answers what an open thread used to be asked of the query. Anything sharing
+ * the single pane with the conversation reads it from here rather than keeping a
+ * second opinion about what is on screen.
+ */
+export function locationOpensDetail(pathname: string): boolean {
+	const segments = pathname.split(/[?#]/)[0].split("/").filter(Boolean);
+	return segments[0] === "mail" && segments.length > 2;
+}

package/src/lib/mail-search.ts

@@ -12,13 +12,13 @@ import { z } from "zod";
 /** What every list carries, whatever else it carries. */
 const listSearch = z.object({ q: z.string().optional() });
 
-export const briefSearchSchema = listSearch.extend({
-	selectedMessageId: z.string().optional(),
-	// A tapped semantic "Related" hit can point at a message outside the loaded
-	// brief list; carrying its thread + mailbox lets the brief open it directly.
-	selectedThreadId: z.string().optional(),
-	selectedMailboxId: z.string().optional(),
-});
+/**
+ * The brief's open thread and the message inside it are path segments
+ * (`/mail/brief/<thread>/<message>`), so the query carries nothing but the
+ * search. An old link's selection params are dropped here, which is what
+ * "tolerated and ignored" means until the other three lists follow.
+ */
+export const briefSearchSchema = listSearch.extend({});
 
 export const flaggedSearchSchema = listSearch.extend({
 	selectedMessageId: z.string().optional(),

package/src/routeTree.gen.ts

@@ -29,8 +29,11 @@ import { Route as SettingsSendersRouteImport } from './routes/settings/senders'
 import { Route as SettingsSuggestedVipsRouteImport } from './routes/settings/suggested-vips'
 import { Route as MailMailboxIdIndexRouteImport } from './routes/mail/$mailboxId/index'
 import { Route as MailBriefIndexRouteImport } from './routes/mail/brief/index'
+import { Route as MailBriefThreadIdRouteImport } from './routes/mail/brief/$threadId'
 import { Route as MailFlaggedIndexRouteImport } from './routes/mail/flagged/index'
 import { Route as MailOutboxIndexRouteImport } from './routes/mail/outbox/index'
+import { Route as MailBriefThreadIdIndexRouteImport } from './routes/mail/brief/$threadId/index'
+import { Route as MailBriefThreadIdMessageIdRouteImport } from './routes/mail/brief/$threadId/$messageId'
 
 const IndexRoute = IndexRouteImport.update({
   id: '/',
@@ -132,6 +135,11 @@ const MailBriefIndexRoute = MailBriefIndexRouteImport.update({
   path: '/',
   getParentRoute: () => MailBriefRoute,
 } as any)
+const MailBriefThreadIdRoute = MailBriefThreadIdRouteImport.update({
+  id: '/$threadId',
+  path: '/$threadId',
+  getParentRoute: () => MailBriefRoute,
+} as any)
 const MailFlaggedIndexRoute = MailFlaggedIndexRouteImport.update({
   id: '/',
   path: '/',
@@ -142,6 +150,17 @@ const MailOutboxIndexRoute = MailOutboxIndexRouteImport.update({
   path: '/',
   getParentRoute: () => MailOutboxRoute,
 } as any)
+const MailBriefThreadIdIndexRoute = MailBriefThreadIdIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => MailBriefThreadIdRoute,
+} as any)
+const MailBriefThreadIdMessageIdRoute =
+  MailBriefThreadIdMessageIdRouteImport.update({
+    id: '/$messageId',
+    path: '/$messageId',
+    getParentRoute: () => MailBriefThreadIdRoute,
+  } as any)
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
@@ -162,10 +181,13 @@ export interface FileRoutesByFullPath {
   '/settings/suggested-vips': typeof SettingsSuggestedVipsRoute
   '/mail/': typeof MailIndexRoute
   '/settings/': typeof SettingsIndexRoute
+  '/mail/brief/$threadId': typeof MailBriefThreadIdRouteWithChildren
   '/mail/$mailboxId/': typeof MailMailboxIdIndexRoute
   '/mail/brief/': typeof MailBriefIndexRoute
   '/mail/flagged/': typeof MailFlaggedIndexRoute
   '/mail/outbox/': typeof MailOutboxIndexRoute
+  '/mail/brief/$threadId/$messageId': typeof MailBriefThreadIdMessageIdRoute
+  '/mail/brief/$threadId/': typeof MailBriefThreadIdIndexRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
@@ -184,6 +206,8 @@ export interface FileRoutesByTo {
   '/mail/brief': typeof MailBriefIndexRoute
   '/mail/flagged': typeof MailFlaggedIndexRoute
   '/mail/outbox': typeof MailOutboxIndexRoute
+  '/mail/brief/$threadId/$messageId': typeof MailBriefThreadIdMessageIdRoute
+  '/mail/brief/$threadId': typeof MailBriefThreadIdIndexRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
@@ -205,10 +229,13 @@ export interface FileRoutesById {
   '/settings/suggested-vips': typeof SettingsSuggestedVipsRoute
   '/mail/': typeof MailIndexRoute
   '/settings/': typeof SettingsIndexRoute
+  '/mail/brief/$threadId': typeof MailBriefThreadIdRouteWithChildren
   '/mail/$mailboxId/': typeof MailMailboxIdIndexRoute
   '/mail/brief/': typeof MailBriefIndexRoute
   '/mail/flagged/': typeof MailFlaggedIndexRoute
   '/mail/outbox/': typeof MailOutboxIndexRoute
+  '/mail/brief/$threadId/$messageId': typeof MailBriefThreadIdMessageIdRoute
+  '/mail/brief/$threadId/': typeof MailBriefThreadIdIndexRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
@@ -231,10 +258,13 @@ export interface FileRouteTypes {
     | '/settings/suggested-vips'
     | '/mail/'
     | '/settings/'
+    | '/mail/brief/$threadId'
     | '/mail/$mailboxId/'
     | '/mail/brief/'
     | '/mail/flagged/'
     | '/mail/outbox/'
+    | '/mail/brief/$threadId/$messageId'
+    | '/mail/brief/$threadId/'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
@@ -253,6 +283,8 @@ export interface FileRouteTypes {
     | '/mail/brief'
     | '/mail/flagged'
     | '/mail/outbox'
+    | '/mail/brief/$threadId/$messageId'
+    | '/mail/brief/$threadId'
   id:
     | '__root__'
     | '/'
@@ -273,10 +305,13 @@ export interface FileRouteTypes {
     | '/settings/suggested-vips'
     | '/mail/'
     | '/settings/'
+    | '/mail/brief/$threadId'
     | '/mail/$mailboxId/'
     | '/mail/brief/'
     | '/mail/flagged/'
     | '/mail/outbox/'
+    | '/mail/brief/$threadId/$messageId'
+    | '/mail/brief/$threadId/'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
@@ -428,6 +463,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof MailBriefIndexRouteImport
       parentRoute: typeof MailBriefRoute
     }
+    '/mail/brief/$threadId': {
+      id: '/mail/brief/$threadId'
+      path: '/$threadId'
+      fullPath: '/mail/brief/$threadId'
+      preLoaderRoute: typeof MailBriefThreadIdRouteImport
+      parentRoute: typeof MailBriefRoute
+    }
     '/mail/flagged/': {
       id: '/mail/flagged/'
       path: '/'
@@ -442,6 +484,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof MailOutboxIndexRouteImport
       parentRoute: typeof MailOutboxRoute
     }
+    '/mail/brief/$threadId/': {
+      id: '/mail/brief/$threadId/'
+      path: '/'
+      fullPath: '/mail/brief/$threadId/'
+      preLoaderRoute: typeof MailBriefThreadIdIndexRouteImport
+      parentRoute: typeof MailBriefThreadIdRoute
+    }
+    '/mail/brief/$threadId/$messageId': {
+      id: '/mail/brief/$threadId/$messageId'
+      path: '/$messageId'
+      fullPath: '/mail/brief/$threadId/$messageId'
+      preLoaderRoute: typeof MailBriefThreadIdMessageIdRouteImport
+      parentRoute: typeof MailBriefThreadIdRoute
+    }
   }
 }
 
@@ -457,11 +513,26 @@ const MailMailboxIdRouteWithChildren = MailMailboxIdRoute._addFileChildren(
   MailMailboxIdRouteChildren,
 )
 
+interface MailBriefThreadIdRouteChildren {
+  MailBriefThreadIdMessageIdRoute: typeof MailBriefThreadIdMessageIdRoute
+  MailBriefThreadIdIndexRoute: typeof MailBriefThreadIdIndexRoute
+}
+
+const MailBriefThreadIdRouteChildren: MailBriefThreadIdRouteChildren = {
+  MailBriefThreadIdMessageIdRoute: MailBriefThreadIdMessageIdRoute,
+  MailBriefThreadIdIndexRoute: MailBriefThreadIdIndexRoute,
+}
+
+const MailBriefThreadIdRouteWithChildren =
+  MailBriefThreadIdRoute._addFileChildren(MailBriefThreadIdRouteChildren)
+
 interface MailBriefRouteChildren {
+  MailBriefThreadIdRoute: typeof MailBriefThreadIdRouteWithChildren
   MailBriefIndexRoute: typeof MailBriefIndexRoute
 }
 
 const MailBriefRouteChildren: MailBriefRouteChildren = {
+  MailBriefThreadIdRoute: MailBriefThreadIdRouteWithChildren,
   MailBriefIndexRoute: MailBriefIndexRoute,
 }
 

package/src/routes/mail/brief/$threadId/$messageId.tsx

@@ -0,0 +1,19 @@
+/**
+ * /mail/brief/$threadId/$messageId — the same conversation, with one of its
+ * messages expanded and scrolled to.
+ *
+ * A message is not addressable on its own: `GET /messages/{messageId}` answers
+ * with no thread, so the pane has nothing to fetch by. The segment names which
+ * message inside the thread the reader pointed at, and the surface it renders is
+ * the thread's.
+ */
+import { createFileRoute } from "@tanstack/react-router";
+import { BriefPane } from "@/components/mail/BriefPane";
+
+function BriefMessagePane() {
+	return <BriefPane.Reading />;
+}
+
+export const Route = createFileRoute("/mail/brief/$threadId/$messageId")({
+	component: BriefMessagePane,
+});

package/src/routes/mail/brief/$threadId/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * The thread with no message named. The pane opens on the newest message, the
+ * same as for a thread whose row the reader never pointed at.
+ */
+import { createFileRoute } from "@tanstack/react-router";
+import { BriefPane } from "@/components/mail/BriefPane";
+
+function BriefThreadPane() {
+	return <BriefPane.Reading />;
+}
+
+export const Route = createFileRoute("/mail/brief/$threadId/")({
+	component: BriefThreadPane,
+});

package/src/routes/mail/brief/$threadId.tsx

@@ -0,0 +1,16 @@
+/**
+ * /mail/brief/$threadId — a conversation open in the brief's reading pane.
+ *
+ * The brief is cross-mailbox, and the thread is still the whole address: the
+ * folder its mail is filed in comes from the thread's own data, since
+ * `GET /threads/{threadId}/messages` answers with rows that each name their
+ * mailbox. A segment for the folder would be a second owner of a fact the
+ * thread already carries.
+ *
+ * A layout, because the message segment nests under it.
+ */
+import { createFileRoute, Outlet } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/mail/brief/$threadId")({
+	component: Outlet,
+});

package/src/routes/mail/brief.tsx

@@ -3,7 +3,9 @@
  *
  * The route mounts the list and the shell around it, and the reading pane is
  * the `Outlet`, so what the pane shows is whatever route is matched under this
- * one rather than a decision made somewhere above.
+ * one rather than a decision made somewhere above. The open thread and the
+ * message inside it are the segments below, which is why nothing here reads a
+ * selection out of the query.
  */
 import {
 	createFileRoute,
@@ -15,6 +17,7 @@ import { BriefPane } from "@/components/mail/BriefPane";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { useSearchMirror } from "@/hooks/useSearchMirror";
 import { briefSearchSchema } from "@/lib/mail-search";
+import { useBriefThreadPath } from "@/routing";
 
 const BriefError = ({ error, reset }: ErrorComponentProps) => (
 	<div className="flex h-full items-center justify-center bg-canvas p-4">
@@ -27,17 +30,17 @@ const BriefError = ({ error, reset }: ErrorComponentProps) => (
 );
 
 function BriefLayout() {
-	const { selectedMessageId } = Route.useSearch();
+	const thread = useBriefThreadPath();
 	useSearchMirror({ to: "/mail/brief" });
 
 	return (
-		<BriefPane selectedMessageId={selectedMessageId}>
+		<BriefPane thread={thread}>
 			<MailShell
 				phone={<BriefPane.Phone />}
 				list={<BriefPane.List />}
 				reading={<Outlet />}
 				intelligence={<BriefPane.Intelligence />}
-				hasThread={Boolean(selectedMessageId)}
+				hasThread={Boolean(thread)}
 			/>
 		</BriefPane>
 	);

package/src/routing/brief-thread.ts

@@ -0,0 +1,47 @@
+import { useParams } from "@tanstack/react-router";
+import { useMemo } from "react";
+
+/** The conversation the brief has open, as the address states it. */
+export interface BriefThreadPath {
+	threadId: string;
+	/**
+	 * Which message inside the thread is expanded and scrolled to. Absent on a
+	 * bare thread address, where the newest message answers for the conversation.
+	 */
+	messageId: string | undefined;
+}
+
+/**
+ * A conversation to open. The thread is what the pane fetches by; the message is
+ * the row the reader pointed at, so a list always knows both.
+ */
+export interface BriefThreadTarget {
+	threadId: string;
+	messageId: string;
+}
+
+/**
+ * The thread the brief has open, read off the path.
+ *
+ * The thread is a child route of the list, and the list layout mounts the pane
+ * above the `Outlet` — so it asks the router which of its children matched
+ * rather than reading a param it does not own. Each `from` names a real route,
+ * so a segment that does not exist fails to compile.
+ */
+export function useBriefThreadPath(): BriefThreadPath | undefined {
+	const thread = useParams({
+		from: "/mail/brief/$threadId",
+		shouldThrow: false,
+	});
+	const message = useParams({
+		from: "/mail/brief/$threadId/$messageId",
+		shouldThrow: false,
+	});
+	const threadId = thread?.threadId;
+	const messageId = message?.messageId;
+
+	return useMemo(
+		() => (threadId ? { threadId, messageId } : undefined),
+		[threadId, messageId],
+	);
+}

package/src/routing/index.ts

@@ -1,3 +1,8 @@
+export {
+	type BriefThreadPath,
+	type BriefThreadTarget,
+	useBriefThreadPath,
+} from "./brief-thread";
 export {
 	type PanelFragment,
 	panelFragments,