@remit/web-client 0.0.248 → 0.0.249

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.248",
+  "version": "0.0.249",
   "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/mail/MailboxPane.tsx

@@ -30,6 +30,7 @@ import {
 	ReadingPaneEmpty,
 	RefreshButton,
 	type RescueCandidate,
+	type ResultCount,
 	type SearchResult,
 } from "@remit/ui";
 import { useInfiniteQuery } from "@tanstack/react-query";
@@ -87,6 +88,7 @@ import { useToggleReadFor } from "@/hooks/useMarkAsRead";
 import { useMoveMessages } from "@/hooks/useMoveMessages";
 import { useRefreshControl } from "@/hooks/useRefreshControl";
 import { useRescueCandidates } from "@/hooks/useRescueCandidates";
+import { useResultCount } from "@/hooks/useResultCount";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
 import { useSemanticSearch } from "@/hooks/useSemanticSearch";
 import { useThreadActions } from "@/hooks/useThreadActions";
@@ -111,6 +113,7 @@ import { useMailContext } from "@/lib/mail-context";
 import { useMailFreshness } from "@/lib/mail-freshness";
 import { isRescueCandidate } from "@/lib/rescue-candidates";
 import { recordRescueSentToJunk } from "@/lib/rescue-telemetry";
+import { shouldRequestResultCount } from "@/lib/result-count";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import {
 	relatedSearchResults,
@@ -204,6 +207,8 @@ interface MailboxPaneContextValue {
 	 * header, not enough to reproduce the query server-side.
 	 */
 	searchPredicate: EscalationSearchQuery | undefined;
+	/** The server's count of the whole match set, for the result header. */
+	resultCount: ResultCount;
 	// List actions
 	onDeleteMessages: (ids: string[]) => void;
 	onMoveMessages: (ids: string[], dest: string) => void;
@@ -316,15 +321,21 @@ function MailboxPaneProvider({
 		searchTokens,
 		filterParams,
 	);
-	const searchThreadsQuery = {
+	// What the list is asking about, with nothing about paging in it. The count
+	// is a property of the criteria alone, so it keys on this and a page fetch
+	// can never trigger one.
+	const searchCriteria = {
 		order: "desc" as const,
-		// Explicit: an unspecified limit clamps to THREAD_SEARCH_MAX_LIMIT (500),
-		// so switching paths without it multiplies the page size by ten.
-		limit: THREADS_PAGE_SIZE,
 		...(freeText ? { query: freeText } : {}),
 		...tokenParams,
 		...filterParams,
 	};
+	const searchThreadsQuery = {
+		...searchCriteria,
+		// Explicit: an unspecified limit clamps to THREAD_SEARCH_MAX_LIMIT (500),
+		// so switching paths without it multiplies the page size by ten.
+		limit: THREADS_PAGE_SIZE,
+	};
 	// What the request actually narrows by, whoever set it. `placeholderData`
 	// keeps the previous rows only under the same predicate, and a token
 	// narrowing the list is as much that predicate as a chip is.
@@ -387,6 +398,16 @@ function MailboxPaneProvider({
 				: undefined,
 	});
 
+	const resultCount = useResultCount({
+		mailboxId,
+		criteria: searchCriteria,
+		enabled: shouldRequestResultCount({
+			hasSearchQuery,
+			freeText,
+			residualTokenCount: residualTokens.length,
+		}),
+	});
+
 	const { accountId: mailboxAccountId, isLoading: mailboxAccountLoading } =
 		useMailboxAccount(mailboxId);
 	const mailboxName = useCurrentMailboxName({ accounts });
@@ -790,6 +811,7 @@ function MailboxPaneProvider({
 			hasSearchQuery && residualTokens.length === 0
 				? searchThreadsQuery
 				: undefined,
+		resultCount,
 		onDeleteMessages: handleDeleteMessages,
 		onMoveMessages: handleMoveMessages,
 		isDeleting,
@@ -854,6 +876,7 @@ function MailboxList() {
 		onClearFilters,
 		listFilter,
 		searchPredicate,
+		resultCount,
 	} = useMailboxPane();
 	const { searchQuery, searchInput, accounts, resultFolderIndex } =
 		useMailContext();
@@ -978,6 +1001,7 @@ function MailboxList() {
 			onRetry={onRetry}
 			searchQuery={searchQuery}
 			searchPredicate={searchPredicate}
+			resultCount={resultCount}
 			onDeleteMessages={onDeleteMessages}
 			isDeleting={isDeleting}
 			isMoving={isMoving}

package/src/components/mail/MessageList.tsx

@@ -4,10 +4,12 @@ import {
 	cn,
 	type Density,
 	deriveIsMultiSelectMode,
+	ListResultHeader,
 	type MessageListFilter,
 	MessageListLoadingMore,
 	MessageListPane,
 	nextFocusId,
+	type ResultCount,
 	type SelectionModifiers,
 	SelectionTopBar,
 	useSelection,
@@ -15,7 +17,6 @@ import {
 } from "@remit/ui";
 import { useBlocker } from "@tanstack/react-router";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { Search } from "lucide-react";
 import type { RefObject } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
@@ -113,6 +114,12 @@ interface MessageListProps {
 	 * only the display string.
 	 */
 	searchPredicate?: EscalationSearchQuery;
+	/**
+	 * How many messages the search matches, as the server counted them — the
+	 * whole match set, not the pages loaded. Omitted where the count was never
+	 * asked for, which renders the header without a number.
+	 */
+	resultCount?: ResultCount;
 	onDeleteMessages?: (messageIds: string[]) => void;
 	isDeleting?: boolean;
 	isMoving?: boolean;
@@ -188,21 +195,6 @@ const readStoredDensity = (): Density => {
 	return "comfortable";
 };
 
-/**
- * Names what the list is showing. No number: the only figure available here is
- * the length of the loaded pages, and a page length presented as a result total
- * contradicts the completeness the filtered empty state states in the same view
- * (#306). The exact count is #307's.
- */
-const SearchResultsHeader = ({ query }: { query: string }) => (
-	<div className="flex items-center gap-2 px-3 py-2 border-b border-line bg-surface-sunken/30">
-		<Search className="size-4 text-fg-muted" />
-		<span className="text-sm text-fg-muted">
-			Results for &ldquo;{query}&rdquo;
-		</span>
-	</div>
-);
-
 /**
  * Why Move is withheld from a selection, in the toolbar's own words. Rows from
  * a per-mailbox endpoint carry no account of their own, so the list's own
@@ -230,6 +222,7 @@ export const MessageList = ({
 	onRetry,
 	searchQuery,
 	searchPredicate,
+	resultCount = { kind: "unknown" },
 	onDeleteMessages,
 	isDeleting = false,
 	isMoving = false,
@@ -1227,7 +1220,7 @@ export const MessageList = ({
 	const virtualBody = (
 		<>
 			{isSearching && searchQuery && (
-				<SearchResultsHeader query={searchQuery} />
+				<ListResultHeader query={searchQuery} count={resultCount} />
 			)}
 			<div
 				ref={parentRef}

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

@@ -0,0 +1,161 @@
+/**
+ * The result count is one question asked of the server, not a walk of the
+ * pages (#307).
+ *
+ * The header used to render `threads.length`, which understated every search
+ * matching more than one page and climbed as the reader scrolled. These mount
+ * the real hook against the real fetch seam and read what actually left: the
+ * whole match set from one request, no second request when the list pages, and
+ * nothing at all for a query still being typed.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { ResultCount } from "@remit/ui";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { type ThreadSearchCriteria, useResultCount } from "./useResultCount.js";
+
+const INBOX = "mbx-inbox";
+/** Far more than a page holds — the number the header must not derive itself. */
+const TOTAL_MATCHES = 1284;
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+/** Count-only requests, in order — the ones that asked for a number. */
+const countRequests = () =>
+	(http?.to("/threads/search") ?? []).filter(
+		(call) =>
+			new URL(call.url, "http://localhost").searchParams.get("count") ===
+			"true",
+	);
+
+interface Probe {
+	count: () => ResultCount;
+	/**
+	 * Render again on the same client, so a second search reaches the cache the
+	 * first one filled — which is the only place a stale count can come from.
+	 */
+	rerender: (next?: {
+		criteria?: ThreadSearchCriteria;
+		enabled?: boolean;
+	}) => Promise<void>;
+}
+
+const mount = async (
+	criteria: ThreadSearchCriteria,
+	enabled: boolean,
+	answer: unknown = { items: [], count: TOTAL_MATCHES },
+): Promise<Probe> => {
+	http = mockFetch((call) =>
+		call.path.endsWith("/threads/search") ? answer : { items: [] },
+	);
+
+	let value: ResultCount | undefined;
+	const CountProbe = ({
+		search,
+		on,
+	}: {
+		search: ThreadSearchCriteria;
+		on: boolean;
+	}) => {
+		value = useResultCount({ mailboxId: INBOX, criteria: search, enabled: on });
+		return null;
+	};
+
+	const mounted = createDomHarness();
+	harness = mounted;
+	let search = criteria;
+	let on = enabled;
+	const render: Probe["rerender"] = async (next) => {
+		if (next?.criteria) search = next.criteria;
+		if (next?.enabled !== undefined) on = next.enabled;
+		mounted.renderApp(createElement(CountProbe, { search, on }));
+		await mounted.flush();
+		await mounted.wait(20);
+		await mounted.flush();
+	};
+	await render();
+	return {
+		count: () => {
+			if (!value) throw new Error("hook did not render");
+			return value;
+		},
+		rerender: render,
+	};
+};
+
+describe("useResultCount (#307)", () => {
+	it("answers with the whole match set the server counted", async () => {
+		const probe = await mount({ query: "invoice" }, true);
+
+		assert.deepEqual(probe.count(), { kind: "exact", value: TOTAL_MATCHES });
+		assert.equal(countRequests().length, 1);
+	});
+
+	it("asks with no cursor, so paging the list never re-counts", async () => {
+		const probe = await mount({ query: "invoice" }, true);
+		await probe.rerender();
+		await probe.rerender();
+
+		assert.equal(
+			countRequests().length,
+			1,
+			"the count was asked again for a predicate that did not change",
+		);
+		const asked = new URL(countRequests()[0]?.url ?? "", "http://localhost")
+			.searchParams;
+		assert.equal(asked.get("continuationToken"), null);
+		assert.equal(asked.get("results"), "false");
+	});
+
+	it("issues no request at all while it is disabled", async () => {
+		const probe = await mount({ query: "in" }, false);
+
+		assert.equal(countRequests().length, 0);
+		assert.deepEqual(
+			probe.count(),
+			{ kind: "unknown" },
+			"an uncounted search reported a number",
+		);
+	});
+
+	/**
+	 * `enabled` gates the request, not the cache. Two searches reach the same key
+	 * whenever what separates them never reaches the request — `invoice` and
+	 * `invoice before:2020` send identical criteria — so the second must not read
+	 * the first one's answer back out of the cache.
+	 */
+	it("forgets the number the moment it stops being asked for", async () => {
+		const probe = await mount({ query: "invoice" }, true);
+		assert.deepEqual(probe.count(), { kind: "exact", value: TOTAL_MATCHES });
+
+		await probe.rerender({ enabled: false });
+
+		assert.deepEqual(
+			probe.count(),
+			{ kind: "unknown" },
+			"a count nobody asked for was served from the cache",
+		);
+		assert.equal(countRequests().length, 1, "the gate stopped gating requests");
+	});
+
+	it("reports no number when the server withholds the count", async () => {
+		const probe = await mount({ query: "invoice" }, true, { items: [] });
+
+		assert.deepEqual(
+			probe.count(),
+			{ kind: "unknown" },
+			"an absent count became a zero",
+		);
+	});
+});

package/src/hooks/useResultCount.ts

@@ -0,0 +1,68 @@
+import { threadOperationsSearchThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { threadOperationsSearchThreads } from "@remit/api-http-client/sdk.gen.ts";
+import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
+import type { ResultCount } from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { toResultCount } from "@/lib/result-count";
+
+/**
+ * What the list is asking about, with nothing about paging in it. The count is
+ * a property of the criteria alone, so a page fetch can never trigger one.
+ */
+export type ThreadSearchCriteria = Omit<
+	NonNullable<ThreadOperationsSearchThreadsData["query"]>,
+	"continuationToken" | "limit" | "count" | "results"
+>;
+
+export interface UseResultCountOptions {
+	mailboxId: string;
+	criteria: ThreadSearchCriteria;
+	/**
+	 * Whether this search is worth counting at all — see
+	 * `shouldRequestResultCount`. Disabled, the surface renders no number rather
+	 * than a stale one from the search before it.
+	 */
+	enabled: boolean;
+}
+
+/** A minute: long enough that returning to a search just left costs nothing. */
+const COUNT_STALE_TIME_MS = 60_000;
+
+/**
+ * How many messages the search matches, from the server that resolves it —
+ * one request against the criteria, never a walk of the pages (#307).
+ *
+ * Its own query, keyed on the criteria without the cursor, so the list pages
+ * without re-counting. An answer that carries no count — off-row criteria, per
+ * #305 — stays absent rather than becoming a zero.
+ */
+export const useResultCount = ({
+	mailboxId,
+	criteria,
+	enabled,
+}: UseResultCountOptions): ResultCount => {
+	const query = { ...criteria, count: true, results: false };
+	const { data } = useQuery({
+		queryKey: threadOperationsSearchThreadsQueryKey({
+			path: { mailboxId },
+			query,
+		}),
+		queryFn: async () => {
+			const { data: response } = await threadOperationsSearchThreads({
+				path: { mailboxId },
+				query,
+				throwOnError: true,
+			});
+			return response;
+		},
+		enabled,
+		staleTime: COUNT_STALE_TIME_MS,
+	});
+	// `enabled` gates the request, not the cache: a criteria set that asks for no
+	// count still reads whatever the last identical key left behind. Two searches
+	// share a key whenever the terms that separate them reach the request as
+	// nothing — `before:`/`after:`/`account:` are stripped from the free text and
+	// carry no param — so a disabled count that read `data` would render the
+	// previous search's total over this one's rows.
+	return enabled ? toResultCount(data?.count) : { kind: "unknown" };
+};

package/src/lib/result-count.test.ts

@@ -0,0 +1,97 @@
+/**
+ * The exact match count is opt-in because it is a second read over the whole
+ * match set (#307). These pin who pays for it and what happens when the server
+ * declines to answer.
+ */
+
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type { EscalationSearchQuery } from "@/hooks/useEscalatedActions";
+import {
+	type ResultCountRequestInput,
+	shouldRequestResultCount,
+	toResultCount,
+} from "./result-count.js";
+
+const request = (input: Partial<ResultCountRequestInput>): boolean =>
+	shouldRequestResultCount({
+		hasSearchQuery: true,
+		freeText: "",
+		residualTokenCount: 0,
+		...input,
+	});
+
+describe("shouldRequestResultCount", () => {
+	test("browsing a mailbox asks for no count", () => {
+		assert.equal(request({ hasSearchQuery: false }), false);
+	});
+
+	test("a free-text query is not counted while it is being typed", () => {
+		for (const freeText of ["k", "ku", " ku "]) {
+			assert.equal(
+				request({ freeText }),
+				false,
+				`"${freeText}" was counted per keystroke`,
+			);
+		}
+	});
+
+	test("a free-text query long enough for the index is counted", () => {
+		assert.equal(request({ freeText: "kub" }), true);
+	});
+
+	test("a query made only of filter tokens is counted straight away", () => {
+		assert.equal(request({}), true);
+	});
+
+	/**
+	 * `before:`/`after:`/`account:` reach the request as nothing, so the server
+	 * would count a wider set than the list shows — and `invoice before:2020`
+	 * sends criteria identical to `invoice`, which is also the previous search's
+	 * cache key.
+	 */
+	test("a term the request could not carry stops the count", () => {
+		assert.equal(
+			request({ freeText: "invoice", residualTokenCount: 1 }),
+			false,
+			"the count covered rows the list filters back out",
+		);
+		assert.equal(
+			request({ freeText: "invoice", residualTokenCount: 0 }),
+			true,
+			"the same search without the residual term must still be counted",
+		);
+	});
+});
+
+describe("toResultCount", () => {
+	test("the server's number is the whole match set", () => {
+		assert.deepEqual(toResultCount(1284), { kind: "exact", value: 1284 });
+	});
+
+	test("zero matches is a number, not an absent count", () => {
+		assert.deepEqual(toResultCount(0), { kind: "exact", value: 0 });
+	});
+
+	test("an absent count stays absent rather than becoming zero", () => {
+		assert.deepEqual(toResultCount(undefined), { kind: "unknown" });
+	});
+});
+
+/**
+ * `searchThreads` withholds the count when the criteria carry an off-row term
+ * (#305), and the escalated selection reads `count` as a required number to size
+ * its run. Neither term can reach that predicate today; this fails the day one
+ * is added, so the absent-count state gets designed rather than surfacing as a
+ * run that refuses to start.
+ */
+describe("the escalation predicate carries no off-row criterion", () => {
+	test("senderTrust and dkimMismatch are not part of it", () => {
+		type OffRow = Extract<
+			keyof EscalationSearchQuery,
+			"senderTrust" | "dkimMismatch"
+		>;
+		const offRow: [OffRow] extends [never] ? true : false = true;
+		assert.equal(offRow, true);
+	});
+});

package/src/lib/result-count.ts

@@ -0,0 +1,57 @@
+import type { ResultCount } from "@remit/ui";
+
+/**
+ * Shortest free text a count is asked for. `npm-scripts/sqlite-search-index.sql`
+ * documents that a query under three characters falls out of the trigram index
+ * onto a folded `LIKE` scan, so counting one is a mailbox scan per typed
+ * character. The list itself still pages — only the count waits.
+ */
+export const MIN_COUNTED_QUERY_LENGTH = 3;
+
+export interface ResultCountRequestInput {
+	/** True while the list is answering a search rather than plain browsing. */
+	hasSearchQuery: boolean;
+	/** The literal text of the search, with its filter tokens already taken out. */
+	freeText: string;
+	/**
+	 * Tokens the request could not carry — `before:`, `after:`, `account:`, and
+	 * any second value for a parameter that takes one — applied over the rows
+	 * after they arrive.
+	 */
+	residualTokenCount: number;
+}
+
+/**
+ * Whether the exact match count is worth one request against these criteria.
+ *
+ * Chip- and token-driven criteria are counted straight away: they change once
+ * per click, and the predicate is one the index answers. Free text is counted
+ * only once it is long enough to be indexed, which is what keeps a per-character
+ * query from paying for a count it will throw away on the next keystroke.
+ *
+ * A residual token stops the count outright. The server never saw that term, so
+ * it would count a wider set than the list shows — and two searches differing
+ * only by one reach the request as the same criteria, so the answer would also
+ * be the one the previous search left in the cache.
+ */
+export const shouldRequestResultCount = ({
+	hasSearchQuery,
+	freeText,
+	residualTokenCount,
+}: ResultCountRequestInput): boolean => {
+	if (!hasSearchQuery) return false;
+	if (residualTokenCount > 0) return false;
+	const typed = freeText.trim();
+	return typed.length === 0 || typed.length >= MIN_COUNTED_QUERY_LENGTH;
+};
+
+/**
+ * The server's answer, or no number.
+ *
+ * The only input is `ThreadSearchResponse.count`, which is the whole match set
+ * or absent (#305) — never a page length. Absent stays absent: a count the
+ * server declined to compute is not zero, and the surface renders nothing
+ * rather than a figure it made up.
+ */
+export const toResultCount = (count: number | undefined): ResultCount =>
+	count === undefined ? { kind: "unknown" } : { kind: "exact", value: count };