@remit/web-client 0.0.248 → 0.0.250

package/src/hooks/useBriefSections.ts

@@ -0,0 +1,310 @@
+/**
+ * The daily brief's rows: one `listAllThreads` request per section it shows,
+ * scoped to that section's category, plus one count of the whole category.
+ *
+ * The brief used to be a single non-paginated page of the newest 50 unified
+ * rows, and every section was "the Marketing rows among those 50" presented as
+ * Marketing. On a mailbox whose Marketing mail is all older than that window the
+ * section rendered empty above a header reading zero (#312). A category-scoped
+ * request answers over the whole scope, so a section holds that category's
+ * newest mail however far down the unified order it sits.
+ *
+ * The brief does not paginate as a whole; it paginates by section. Each section
+ * takes its newest {@link SECTION_ROW_CAP} rows and states its real size, and
+ * the way to the rest is the brief's own filtered list for that category — no
+ * cursor here, and no request that walks a mailbox.
+ *
+ * The counts are the second read. One per displayed section, keyed on the
+ * criteria alone so no page, cursor or expansion can trigger another, and held
+ * for a minute. The criteria are the caller's committed state — the query as it
+ * was submitted, and the chips as that query and the panel leave them — so
+ * nothing here is on a keystroke path.
+ *
+ * Each section loads and fails on its own. Seven requests are seven answers, and
+ * one category's failed request is not a reason to blank the six that came back:
+ * a section carries its own pending and error state, and the brief renders what
+ * it has. What reaches that state is a transport failure — a request that never
+ * got an answer. A 5xx is the API breaking rather than this section failing, and
+ * escalates globally on the fail-fast contract (`shouldEscalate`, #1059); there
+ * is no `meta` opt-out here and there must not be one.
+ *
+ * A refetch under the same predicate keeps the rows already on screen. Under a
+ * different one it does not — the previous chip's mail under the new chip is the
+ * defect `sameInboxFilter` exists to stop — so only a change of free text holds
+ * the previous answer while the next one is in flight.
+ *
+ * Sections are the unsearched brief only. Under a query the brief is one list in
+ * one order — see `useBriefSearchRows`.
+ */
+import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { unifiedThreadOperationsListAllThreads } from "@remit/api-http-client/sdk.gen.ts";
+import type {
+	RemitImapMessageCategory,
+	RemitImapThreadMessageResponse,
+	RemitImapThreadSearchResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { ResultCount } from "@remit/ui";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import type { BriefSectionParams } from "@/lib/brief-criteria";
+import { type InboxFilterParams, sameInboxFilter } from "@/lib/inbox-filters";
+import { toResultCount } from "@/lib/result-count";
+
+/** A minute: a brief reopened straight away costs nothing. */
+const BRIEF_STALE_TIME_MS = 60_000;
+
+/** Half a minute: a query being refined re-asks sooner than the brief does. */
+const SEARCH_STALE_TIME_MS = 30_000;
+
+/** No number at all, which is what a section shows when nobody counted it. */
+const UNCOUNTED: ResultCount = { kind: "unknown" };
+
+/**
+ * Hold the previous answer while the next one is in flight, but only where the
+ * predicate is unchanged. A chip that changes what is being asked for takes its
+ * rows with it: the previous chip's mail under the new chip, for one round trip,
+ * is what `sameInboxFilter` was written to stop (design D18).
+ */
+const keepUnderSameFilter =
+	(filter: InboxFilterParams) =>
+	(
+		previous: RemitImapThreadSearchResponse | undefined,
+		previousQuery: { queryKey: readonly unknown[] } | undefined,
+	): RemitImapThreadSearchResponse | undefined =>
+		sameInboxFilter(previousQuery?.queryKey, filter) ? previous : undefined;
+
+/** The criteria every section request carries, its own category aside. */
+export interface BriefSectionsCriteria extends BriefSectionParams {
+	/** Committed free text, matched against subject and From across folders. */
+	query?: string;
+}
+
+const sectionRowsQuery = (
+	criteria: BriefSectionsCriteria,
+	category: RemitImapMessageCategory,
+	limit: number,
+) => ({
+	...criteria,
+	category: [category],
+	limit,
+	order: "desc" as const,
+});
+
+// No `limit` and no cursor: the count is a property of the criteria, so growing
+// the page cannot change it and cannot ask for it again.
+const sectionCountQuery = (
+	criteria: BriefSectionsCriteria,
+	category: RemitImapMessageCategory,
+) => ({
+	...criteria,
+	category: [category],
+	order: "desc" as const,
+	count: true,
+	results: false,
+});
+
+/**
+ * What a request under these criteria asks for, as `sameInboxFilter` reads it.
+ * Free text is deliberately not part of it: a query being refined is the one
+ * change that may keep the previous answer on screen.
+ */
+const sectionFilter = (
+	criteria: BriefSectionsCriteria,
+	category: RemitImapMessageCategory,
+): InboxFilterParams => ({
+	category: [category],
+	...(criteria.unread !== undefined ? { unread: criteria.unread } : {}),
+	...(criteria.starred !== undefined ? { starred: criteria.starred } : {}),
+	...(criteria.attachments !== undefined
+		? { attachments: criteria.attachments }
+		: {}),
+});
+
+export interface BriefSectionRows {
+	category: RemitImapMessageCategory;
+	rows: RemitImapThreadMessageResponse[];
+	total: ResultCount;
+	/** The request came back full, so the category holds more than these rows. */
+	atCap: boolean;
+	/** Nothing has arrived for this section yet. */
+	loading: boolean;
+	/** This section's own request failed; the others are unaffected. */
+	failed: boolean;
+	/** Ask this one section again. */
+	retry: () => void;
+}
+
+export interface UseBriefSectionsOptions {
+	/** The categories the brief is showing, in display order. */
+	categories: readonly RemitImapMessageCategory[];
+	criteria: BriefSectionsCriteria;
+	/** Rows per section. */
+	limit: number;
+	/**
+	 * Whether the request saw every criterion on screen. False, no count is asked
+	 * for and every section reports no number — see `briefCountsMatchRows`.
+	 */
+	counted: boolean;
+}
+
+export interface UseBriefSections {
+	sections: BriefSectionRows[];
+	/** Nothing has arrived for any section — the brief has nothing to render. */
+	isLoading: boolean;
+	/** Every section failed. One failing section is the section's own state. */
+	isError: boolean;
+	refetch: () => void;
+}
+
+export function useBriefSections({
+	categories,
+	criteria,
+	limit,
+	counted,
+}: UseBriefSectionsOptions): UseBriefSections {
+	const rowQueries = useQueries({
+		queries: categories.map((category) => {
+			const query = sectionRowsQuery(criteria, category, limit);
+			const filter = sectionFilter(criteria, category);
+			return {
+				queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+				queryFn: async () => {
+					const { data } = await unifiedThreadOperationsListAllThreads({
+						query,
+						throwOnError: true,
+					});
+					return data;
+				},
+				placeholderData: keepUnderSameFilter(filter),
+				staleTime: BRIEF_STALE_TIME_MS,
+			};
+		}),
+	});
+
+	const countQueries = useQueries({
+		queries: categories.map((category) => {
+			const query = sectionCountQuery(criteria, category);
+			const filter = sectionFilter(criteria, category);
+			return {
+				queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+				queryFn: async () => {
+					const { data } = await unifiedThreadOperationsListAllThreads({
+						query,
+						throwOnError: true,
+					});
+					return data;
+				},
+				enabled: counted,
+				placeholderData: keepUnderSameFilter(filter),
+				staleTime: BRIEF_STALE_TIME_MS,
+			};
+		}),
+	});
+
+	const sections = useMemo<BriefSectionRows[]>(
+		() =>
+			categories.map((category, index) => {
+				const rows = rowQueries[index];
+				const count = countQueries[index];
+				const items = rows?.data?.items ?? [];
+				return {
+					category,
+					rows: items,
+					// Read off the page rather than the rendered rows: muting and the
+					// thread collapse both shrink what is rendered, and neither means the
+					// category holds no more.
+					atCap: items.length >= limit,
+					// `enabled` gates the request, not the cache: a brief that asks for
+					// no count must not render the one an earlier, narrower brief left
+					// behind.
+					total: counted ? toResultCount(count?.data?.count) : UNCOUNTED,
+					// Pending, not fetching: a section holding the previous query's rows
+					// has something to render, and replacing it with a skeleton takes the
+					// brief off screen every time the search field is cleared.
+					loading: rows?.isPending ?? true,
+					failed: rows?.isError ?? false,
+					retry: () => {
+						rows?.refetch();
+						// `refetch` ignores `enabled`, so an uncounted brief would fetch a
+						// count it has already decided not to render.
+						if (counted) count?.refetch();
+					},
+				};
+			}),
+		[categories, rowQueries, countQueries, counted, limit],
+	);
+
+	const refetch = useCallback(() => {
+		for (const query of rowQueries) query.refetch();
+		for (const query of countQueries) query.refetch();
+	}, [rowQueries, countQueries]);
+
+	return {
+		sections,
+		// The whole-body states are the ones where there is genuinely nothing to
+		// show. A section that is still loading, or that failed on its own, says so
+		// in its own place while the rest of the brief stands.
+		isLoading:
+			rowQueries.length > 0 && rowQueries.every((query) => query.isPending),
+		isError:
+			rowQueries.length > 0 && rowQueries.every((query) => query.isError),
+		refetch,
+	};
+}
+
+/** What a searched brief holds before the reader is told to narrow it. */
+export interface BriefSearchCriteria extends BriefSectionsCriteria {
+	/** A category the chips or a `category:` term narrowed the search to. */
+	category?: RemitImapMessageCategory[];
+}
+
+export interface UseBriefSearchRows {
+	/** Every match the request returned, in the order the server returned them. */
+	rows: RemitImapThreadMessageResponse[];
+	isLoading: boolean;
+	isError: boolean;
+	refetch: () => void;
+}
+
+/**
+ * The brief under a search: one request, one globally newest-first list.
+ *
+ * Not seven category queries stitched back together. A match's category must not
+ * lift it above a newer match, and section headers between the rows would do
+ * exactly that — an old newsletter above a mail that arrived this morning. The
+ * server orders the whole match set; the client renders it in that order (#312).
+ *
+ * Search mode also widens the scope past INBOX to every non-muted folder of every
+ * account, so this is the only request that reaches Archive, Sent and Spam.
+ */
+export function useBriefSearchRows(
+	criteria: BriefSearchCriteria,
+	limit: number,
+	enabled: boolean,
+): UseBriefSearchRows {
+	const query = { ...criteria, limit, order: "desc" as const };
+	const { data, isLoading, isError, refetch } = useQuery({
+		queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+		queryFn: async () => {
+			const { data: page } = await unifiedThreadOperationsListAllThreads({
+				query,
+				throwOnError: true,
+			});
+			return page;
+		},
+		enabled,
+		staleTime: SEARCH_STALE_TIME_MS,
+	});
+	const rows = useMemo(
+		() => (enabled ? (data?.items ?? []) : []),
+		[data, enabled],
+	);
+	return {
+		rows,
+		isLoading: enabled && isLoading,
+		isError: enabled && isError,
+		refetch: useCallback(() => {
+			refetch();
+		}, [refetch]),
+	};
+}

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/brief-criteria.test.ts

@@ -0,0 +1,126 @@
+/**
+ * What each brief section asks the server for.
+ *
+ * #312: every section is its own category-scoped request, so the chips and the
+ * tokens that ask for the same thing have to reach it as parameters. A criterion
+ * evaluated over the ten rows a section fetched would mean "among the newest ten
+ * Marketing messages", which is the reading the whole issue removes.
+ */
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	BRIEF_TOKEN_PARAMS,
+	briefCountsMatchRows,
+	briefCriteria,
+} from "./brief-criteria.js";
+import { parseSearchTokens, type SearchToken } from "./search-tokens.js";
+
+const tokensOf = (query: string): SearchToken[] =>
+	parseSearchTokens(query, {
+		accountsByName: new Map([["alice", "acc_1"]]),
+		mailboxesByName: new Map([["sent", "mb2"]]),
+	}).tokens;
+
+const criteriaOf = (query: string, attributes: string[] = []) =>
+	briefCriteria("all", new Set(attributes), tokensOf(query)).criteria;
+
+const residualTypes = (query: string, attributes: string[] = []) =>
+	briefCriteria("all", new Set(attributes), tokensOf(query)).residual.map(
+		(t) => t.type,
+	);
+
+describe("briefCriteria", () => {
+	test("an unnarrowed brief asks for nothing in particular", () => {
+		assert.deepEqual(criteriaOf(""), {});
+		assert.deepEqual(residualTypes(""), []);
+	});
+
+	test("the chips travel as parameters", () => {
+		assert.deepEqual(criteriaOf("", ["unread", "attachment"]), {
+			unread: true,
+			attachments: true,
+		});
+	});
+
+	test("a typed token asks for exactly what its chip asks for", () => {
+		assert.deepEqual(criteriaOf("is:unread has:attachment"), {
+			unread: true,
+			attachments: true,
+		});
+		assert.deepEqual(residualTypes("is:unread has:attachment"), []);
+	});
+
+	test("is:read narrows the request rather than the rows", () => {
+		assert.deepEqual(criteriaOf("is:read"), { unread: false });
+		assert.deepEqual(residualTypes("is:read"), []);
+	});
+
+	test("is:starred travels too", () => {
+		assert.deepEqual(criteriaOf("is:starred"), { starred: true });
+		assert.deepEqual(residualTypes("is:starred"), []);
+	});
+
+	// The section supplies its own category, so the shared criteria must not
+	// carry one — two categories on one request is a request for neither.
+	test("the category never travels in the shared criteria", () => {
+		assert.deepEqual(criteriaOf("category:personal"), {});
+		assert.deepEqual(criteriaOf("", ["unread"]), { unread: true });
+		assert.equal(
+			Object.hasOwn(
+				briefCriteria("personal", new Set(), []).criteria,
+				"category",
+			),
+			false,
+		);
+	});
+
+	// `listAllThreads` has one text parameter matching subject and From at once,
+	// so neither token can be asked for on its own and both stay residue.
+	test("from: and subject: have no parameter here and come back as residue", () => {
+		assert.deepEqual(criteriaOf("from:alice"), {});
+		assert.deepEqual(residualTypes("from:alice"), ["from"]);
+		assert.deepEqual(residualTypes("subject:invoice"), ["subject"]);
+		assert.deepEqual(BRIEF_TOKEN_PARAMS.includes("from"), false);
+	});
+
+	test("dates, the mailbox and the account stay residue", () => {
+		assert.deepEqual(residualTypes("before:2024-01-01 in:sent account:alice"), [
+			"before",
+			"in",
+			"account",
+		]);
+	});
+
+	test("a chip beats the token that contradicts it", () => {
+		assert.deepEqual(criteriaOf("is:read", ["unread"]), { unread: true });
+		assert.deepEqual(residualTypes("is:read", ["unread"]), ["isRead"]);
+	});
+});
+
+describe("briefCountsMatchRows", () => {
+	const reach = (over: Partial<Parameters<typeof briefCountsMatchRows>[0]>) =>
+		briefCountsMatchRows({
+			residual: [],
+			attributes: new Set<string>(),
+			accountScoped: false,
+			...over,
+		});
+
+	test("a request carrying every criterion on screen counts what it shows", () => {
+		assert.equal(reach({}), true);
+		assert.equal(reach({ attributes: new Set(["unread"]) }), true);
+	});
+
+	test("a residual token makes the count wider than the list", () => {
+		assert.equal(reach({ residual: tokensOf("from:alice") }), false);
+	});
+
+	test("the account pills scope the rows and nothing else", () => {
+		assert.equal(reach({ accountScoped: true }), false);
+	});
+
+	test("a chip with no parameter makes the count wider than the list", () => {
+		assert.equal(reach({ attributes: new Set(["contacts"]) }), false);
+		assert.equal(reach({ attributes: new Set(["today"]) }), false);
+	});
+});