@remit/web-client 0.0.248 → 0.0.250

package/src/lib/brief.ts

@@ -1,7 +1,7 @@
 /**
- * Daily brief grouping logic.
+ * Daily brief section assembly.
  *
- * Pure function: takes a flat list of thread message rows and returns one
+ * Pure function: takes one complete per-category server response and returns one
  * section per message category, in a fixed display order:
  *
  *  1. Personal
@@ -12,11 +12,15 @@
  *  6. Automated
  *  7. Unclassified
  *
- * Each row lands in the section for its category; a row with no category counts
- * as `uncategorized`, which is its own section rather than being folded into
- * Personal — unclassified mail is missing work, not a decision (issue #45).
- * Starred mail is not a section —
- * the star is a per-row marker, so a starred message stays in its category.
+ * Each section is its own server query, scoped to its category and carrying
+ * every criterion on screen the request can express, plus one count for the
+ * whole category. Nothing here groups a page: a category whose mail is entirely
+ * older than the newest unified page still has a section, and the section's
+ * header states the category's real size rather than how many of a shared window
+ * happened to fall in it (#312). `uncategorized` is its own section rather than
+ * being folded into Personal — unclassified mail is missing work, not a decision
+ * (issue #45). Starred mail is not a section — the star is a per-row marker, so
+ * a starred message stays in its category.
  *
  * Sender trust (vip/wellknown) no longer sections the brief — the signal is
  * still carried on each row (see `toThreadRowData`) for future use, but it does
@@ -24,16 +28,17 @@
  * a high-volume mailbox read≠handled and unread≠important; unread is a
  * user-selectable filter chip instead.
  *
- * Muted senders and empty sections are excluded. Mute filtering happens in
- * `excludeMutedSenders`, applied by the caller to the raw thread rows before
- * `toThreadRowData`/grouping — the server denormalizes `muted` onto each row
- * from the From address's flags (RFC 039 Decision 3, issue #301), so no
+ * Muted senders and categories the scope holds none of are excluded. Mute
+ * filtering happens in `excludeMutedSenders`, applied by the caller to the raw
+ * thread rows before `toThreadRowData` — the server denormalizes `muted` onto
+ * each row from the From address's flags (RFC 039 Decision 3, issue #301), so no
  * client-side Address lookup is needed.
  */
 
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
 import { MessageCategory } from "@remit/domain-enums";
 import type {
+	ResultCount,
 	SenderTrustLevel,
 	ThreadCategory,
 	ThreadRowData,
@@ -79,6 +84,26 @@ export function toThreadRowData(
  * mail, so callers outside the brief (mailbox listings, search) must not
  * apply this filter.
  */
+/**
+ * The section's count, or no number, once mute is taken into account.
+ *
+ * Mute is the one criterion the request cannot be asked about: `listAllThreads`
+ * has no `muted` parameter, so a scope holding a muted sender is counted with
+ * that sender's mail in it while the list renders without it. The header would
+ * overstate, and "Show all" would offer rows the brief will not show.
+ *
+ * Withheld per section rather than for the whole brief — one muted marketer must
+ * not take the number off Personal — and only where a mute is visible in the
+ * rows on hand. A muted sender below a section's page is not visible, so this
+ * suppresses a number known to be wrong rather than certifying the rest.
+ */
+export function briefSectionTotal(
+	total: ResultCount,
+	rows: RemitImapThreadMessageResponse[],
+): ResultCount {
+	return rows.some((row) => row.muted === true) ? { kind: "unknown" } : total;
+}
+
 export function excludeMutedSenders(
 	threads: RemitImapThreadMessageResponse[],
 ): RemitImapThreadMessageResponse[] {
@@ -86,14 +111,19 @@ export function excludeMutedSenders(
 }
 
 /**
- * Union of the brief's own rows with the rows the server's cross-folder search
- * returned, newest first.
+ * Union of a complete server-filtered listing with the rows the server's
+ * cross-folder text search returned, newest first.
+ *
+ * Both lists are needed where the listing itself is complete under its criteria
+ * — the Flagged collection is, and pages to its end. The server matches subject
+ * and From only, so a row whose snippet carries the term is found only by the
+ * client-side pass; the server pass is the only one that reaches Archive, Sent,
+ * Spam and custom folders. The two overlap, so rows are deduped by id, the first
+ * occurrence winning.
  *
- * Both lists are needed. The server matches subject and From only, so a row
- * whose snippet carries the term is found only by the client-side pass over the
- * loaded brief rows; the server pass is the only one that reaches Archive,
- * Sent, Spam and custom folders, which the brief list never loads. The two
- * overlap on INBOX, so rows are deduped by id, the first occurrence winning.
+ * Not for a paginated prefix. The brief's sections are per-category pages, so
+ * merging one with a search window and re-sorting would order two truncated
+ * lists against each other and call the result newest-first (#312).
  *
  * Rows without a `sentDate` sort last; the brief's own list is already newest
  * first, so this only has to re-interleave the two sources.
@@ -114,9 +144,10 @@ export function mergeSearchRows(
 
 /**
  * Category sections in fixed display order. The `id`/`label` drive the rendered
- * section; `category` is the row category that routes into it.
+ * section; `category` is both the section's own scope and the query parameter
+ * the section's request carries.
  */
-const CATEGORY_SECTIONS: ReadonlyArray<{
+export const CATEGORY_SECTIONS: ReadonlyArray<{
 	id: string;
 	label: string;
 	category: ThreadCategory;
@@ -142,36 +173,63 @@ const CATEGORY_SECTIONS: ReadonlyArray<{
 	},
 ];
 
+/** The categories the brief asks for, in the order it renders them. */
+export const BRIEF_CATEGORIES: readonly ThreadCategory[] =
+	CATEGORY_SECTIONS.map((section) => section.category);
+
+/** One category's own server answer: its newest rows and how many it holds. */
+export interface BriefCategoryResult {
+	category: ThreadCategory;
+	/** The newest rows the section's request returned, newest first. */
+	rows: ThreadRowData[];
+	/** The category's size over the whole scope, or no number at all. */
+	total: ResultCount;
+	/** The request came back full, so the category holds more than these rows. */
+	atCap: boolean;
+	/** The request has not answered yet. */
+	loading: boolean;
+	/** The request failed. This category alone; the others are unaffected. */
+	failed: boolean;
+}
+
 /**
- * Group a flat list of thread row data into one section per message category.
- * Rows should already be filtered for the selected account chip (if any) before
- * calling this function.
+ * The per-category server answers as brief sections, in display order.
  *
- * @param rows      Flat array of ThreadRowData, sorted newest-first.
- * @returns         Array of ThreadSection in category display order — empty
- *                  sections are omitted.
+ * A regrouping of complete responses, never of a page: each result already is
+ * its whole category as far as the request was concerned, so no further page can
+ * move a section's membership or its total.
+ *
+ * A category the scope holds none of has no section — a header stating zero is
+ * noise, not information. A category still being fetched, or whose own request
+ * failed, keeps its section so the loading and error treatments have somewhere
+ * to render, and a category with a real total keeps its section even with no
+ * rows left after the chips, so the reader sees which filter emptied it.
  */
-export function groupBriefSections(rows: ThreadRowData[]): ThreadSection[] {
-	const byCategory = new Map<string, ThreadRowData[]>(
-		CATEGORY_SECTIONS.map((s) => [s.category, []]),
+export function briefSections(
+	results: readonly BriefCategoryResult[],
+): ThreadSection[] {
+	const byCategory = new Map(
+		results.map((result) => [result.category, result] as const),
 	);
-
-	for (const row of rows) {
-		const category = row.category ?? MessageCategory.uncategorized;
-		const bucket =
-			byCategory.get(category) ?? byCategory.get(MessageCategory.uncategorized);
-		bucket?.push(row);
-	}
-
 	const sections: ThreadSection[] = [];
 	for (const section of CATEGORY_SECTIONS) {
-		const threads = byCategory.get(section.category);
-		if (threads && threads.length > 0)
-			sections.push({
-				id: section.id,
-				label: section.label,
-				threads,
-			});
+		const result = byCategory.get(section.category);
+		if (!result) continue;
+		const holdsMail =
+			result.loading ||
+			result.failed ||
+			result.rows.length > 0 ||
+			(result.total.kind === "exact" && result.total.value > 0);
+		if (!holdsMail) continue;
+		sections.push({
+			id: section.id,
+			label: section.label,
+			threads: result.rows,
+			total: result.total,
+			atCap: result.atCap,
+			loading: result.loading,
+			error: result.failed,
+		});
 	}
 	return sections;
 }
@@ -190,15 +248,20 @@ export function matchesBriefSearch(t: ThreadRowData, query: string): boolean {
 }
 
 /**
- * Returns true when `t` satisfies every parsed filter token — the client-side
- * counterpart of the params `threadOperationsSearchThreads` accepts, applied
- * over the already-loaded brief/flagged rows (#428). A row without the data a
- * token needs (e.g. no `sentDate` for `before:`/`after:`) never matches that
- * token, so it drops out rather than showing under an unverifiable filter.
- * `in:`/`account:` have no server param at all — this is the entire
- * implementation of both, reusing the same per-account fan-out the daily
- * brief already reads its rows from (`accountId`/`mailboxId` are already on
- * every row).
+ * Returns true when `t` satisfies every token handed to it.
+ *
+ * The residue applier: callers pass the tokens their request could not carry —
+ * `threadSearchTokens` decides which those are by reading the request back — and
+ * this narrows the rows that came back by them. A token the request did carry
+ * must not be passed here; the server already answered it over the whole scope,
+ * and re-answering it over one page is how a criterion ends up meaning "among
+ * the rows fetched so far" (#312).
+ *
+ * Every token is implemented so that a request carrying fewer parameters still
+ * has somewhere to put the rest: `listAllThreads` has no `from` or `subject` of
+ * its own, and no endpoint has `before:`, `after:`, `in:` or `account:`. A row
+ * without the data a token needs (no `sentDate` for `before:`/`after:`) never
+ * matches it, so it drops out rather than showing under an unverifiable filter.
  */
 export function matchesSearchTokens(
 	t: ThreadRowData,

package/src/lib/drafts.ts

@@ -8,7 +8,7 @@
  *     the account that owns the open \Drafts mailbox.
  *  2. On the server — IMAP \Drafts thread rows already loaded for the mailbox.
  *
- * Sections with no rows are omitted entirely (mirrors groupBriefSections).
+ * Sections with no rows are omitted entirely (mirrors `briefSections`).
  *
  * --- Dedup note ---
  * Remit draft rows and IMAP \Drafts messages are rendered in both sections

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 };