@remit/web-client 0.0.325 → 0.0.327

package/src/lib/mail-context.ts

@@ -1,91 +0,0 @@
-import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
-import { createContext, useContext } from "react";
-import {
-	EMPTY_RESULT_FOLDER_INDEX,
-	type ResultFolderIndex,
-} from "./result-folder.js";
-
-/**
- * Shared mail-layout context. Lives in `lib/` — NOT in `routes/mail.tsx` — on
- * purpose: the generated route tree imports the mail route via a relative
- * specifier (`./routes/mail`) while feature code imports via the `@/` alias.
- * Vite can resolve those to two distinct module instances, which would give the
- * `MailLayout` provider and a child-route consumer two different `MailContext`
- * objects — the consumer then silently falls back to the defaults below (this
- * bit the intelligence toggle: clicks reached a no-op handler). Keeping the
- * context in a module that is only ever imported through the `@/` alias
- * guarantees a single instance shared by provider and consumers.
- */
-export interface MailContextValue {
-	accounts: RemitImapAccountResponse[];
-	/**
-	 * Name indexes `parseSearchTokens` resolves `in:`/`account:` chips against
-	 * (#428 follow-up). Computed once here so every consumer — chip rendering,
-	 * the brief/flagged token filters — agrees on the same
-	 * resolution. See `lib/search-token-index.ts`.
-	 */
-	mailboxNameIndex: ReadonlyMap<string, string>;
-	accountNameIndex: ReadonlyMap<string, string>;
-	/**
-	 * mailboxId → the folder a search result read from that mailbox came from.
-	 * Computed once here for the same reason as the name indexes: the row labels,
-	 * the spam hold-out and the scope chip must agree on which folder is which.
-	 * See `lib/result-folder.ts`.
-	 */
-	resultFolderIndex: ResultFolderIndex;
-	searchQuery: string;
-	/** Live (pre-debounce) search input — the search field binds this. */
-	searchInput: string;
-	/**
-	 * Identity of the view the current search belongs to (`lib/mail-route.ts`).
-	 * It changes when the user leaves that view, which is when search ends: the
-	 * query re-seeds from the new URL and any search chrome collapses (#47).
-	 */
-	searchViewKey: string;
-	onSearchChange: (query: string) => void;
-	/** Full clear (X button): drops the query and any selected thread (#538). */
-	onSearchClear: () => void;
-	/** Query-only clear (Esc): drops the query, keeps the thread open (#489). */
-	onSearchClearQuery: () => void;
-	/**
-	 * Whether pane 4 (intelligence) is up. Resolved once by the `/mail` layout
-	 * from the address and this device's preference (`resolveRailOpen`), and
-	 * handed down as the answer — a consumer re-deriving it from the fragment
-	 * alone would lose the preference and disagree with the shell.
-	 */
-	intelligenceOpen: boolean;
-	/** The reader's own control over pane 4, which stores what they chose. */
-	onToggleIntelligence: () => void;
-	/**
-	 * Puts pane 4 up for the thread in hand without touching the stored
-	 * preference: a DKIM mismatch surfacing the rail is about this message, not
-	 * about where the reader wants the rail from now on (#778).
-	 */
-	onRaiseIntelligence: () => void;
-}
-
-export const MailContext = createContext<MailContextValue | null>(null);
-
-export const useMailContext = (): MailContextValue => {
-	const context = useContext(MailContext);
-	// Return default values if context not yet available (e.g., during loading)
-	// This can happen when TanStack Router renders child routes before parent
-	// finishes.
-	return (
-		context ?? {
-			accounts: [],
-			mailboxNameIndex: new Map(),
-			accountNameIndex: new Map(),
-			resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
-			searchQuery: "",
-			searchInput: "",
-			searchViewKey: "",
-			onSearchChange: () => {},
-			onSearchClear: () => {},
-			onSearchClearQuery: () => {},
-			intelligenceOpen: false,
-			onToggleIntelligence: () => {},
-			onRaiseIntelligence: () => {},
-		}
-	);
-};

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

@@ -1,165 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, test } from "node:test";
-import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
-import type { NavMailboxRole } from "@remit/ui";
-import type { ResultFolderIndex } from "@/lib/result-folder";
-import {
-	grownMailboxIds,
-	hasGrown,
-	highWaterMarksFrom,
-} from "./mail-freshness.js";
-
-const mailbox = (
-	mailboxId: string,
-	messagesTotal: number,
-	highWaterMarkUid: number,
-): RemitImapMailboxSyncProgress => ({
-	mailboxId,
-	fullPath: mailboxId,
-	phase: "complete",
-	messagesTotal,
-	messagesSynced: messagesTotal,
-	highWaterMarkUid,
-});
-
-const roles = (
-	entries: Record<string, NavMailboxRole | undefined>,
-): ResultFolderIndex =>
-	new Map(
-		Object.entries(entries).map(([id, role]) => [id, role ? { role } : {}]),
-	);
-
-describe("hasGrown", () => {
-	test("false when nothing changed", () => {
-		const baseline = new Map([["mb-1", 100]]);
-		const current = new Map([["mb-1", 100]]);
-		assert.equal(hasGrown(baseline, current), false);
-	});
-
-	test("true when a mailbox took a UID above the highest one seen", () => {
-		const baseline = new Map([["mb-1", 100]]);
-		const current = new Map([["mb-1", 101]]);
-		assert.equal(hasGrown(baseline, current), true);
-	});
-
-	test("a mailbox missing from the baseline counts from zero", () => {
-		const baseline = new Map<string, number>();
-		const current = new Map([["mb-1", 1]]);
-		assert.equal(hasGrown(baseline, current), true);
-	});
-
-	test("a mailbox that has never taken a message is not growth", () => {
-		const baseline = new Map<string, number>();
-		const current = new Map([["mb-1", 0]]);
-		assert.equal(hasGrown(baseline, current), false);
-	});
-
-	test("one mailbox growing is enough even if others are unchanged", () => {
-		const baseline = new Map([
-			["mb-1", 100],
-			["mb-2", 50],
-		]);
-		const current = new Map([
-			["mb-1", 100],
-			["mb-2", 51],
-		]);
-		assert.equal(hasGrown(baseline, current), true);
-	});
-});
-
-describe("highWaterMarksFrom", () => {
-	test("keeps a mailbox with no resolved role (a custom folder)", () => {
-		const marks = highWaterMarksFrom([mailbox("mb-custom", 5, 42)], roles({}));
-		assert.deepEqual([...marks], [["mb-custom", 42]]);
-	});
-
-	test("keeps Inbox and Junk — both are places new mail actually arrives", () => {
-		const marks = highWaterMarksFrom(
-			[mailbox("mb-inbox", 5, 42), mailbox("mb-junk", 2, 7)],
-			roles({ "mb-inbox": "inbox", "mb-junk": "junk" }),
-		);
-		assert.deepEqual(new Set(marks.keys()), new Set(["mb-inbox", "mb-junk"]));
-	});
-
-	for (const role of ["sent", "drafts", "trash", "archive"] as const) {
-		test(`drops ${role} — its own new messages are the user's doing, not an arrival`, () => {
-			const marks = highWaterMarksFrom(
-				[mailbox("mb-1", 5, 42)],
-				roles({ "mb-1": role }),
-			);
-			assert.equal(marks.has("mb-1"), false);
-		});
-	}
-
-	test("a delete (Inbox shrinks, Trash grows) never reads as an arrival", () => {
-		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
-		const baseline = highWaterMarksFrom(
-			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
-			folders,
-		);
-		const afterDelete = highWaterMarksFrom(
-			[mailbox("mb-inbox", 9, 100), mailbox("mb-trash", 4, 21)],
-			folders,
-		);
-		assert.equal(hasGrown(baseline, afterDelete), false);
-	});
-
-	// Issue #771: the arrival and the departure land in the same sync round, so
-	// the Inbox total nets to zero and the count-based reading saw nothing. The
-	// arrival is a UID above the highest one seen, and that is what surfaces it.
-	test("an arrival alongside a departure surfaces, though the total is unchanged", () => {
-		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
-		const baseline = highWaterMarksFrom(
-			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
-			folders,
-		);
-		const afterArrivalAndDeparture = highWaterMarksFrom(
-			[mailbox("mb-inbox", 10, 101), mailbox("mb-trash", 4, 21)],
-			folders,
-		);
-		assert.equal(hasGrown(baseline, afterArrivalAndDeparture), true);
-	});
-
-	test("real new mail in Inbox still reads as an arrival alongside an unrelated delete", () => {
-		const folders = roles({ "mb-inbox": "inbox", "mb-trash": "trash" });
-		const baseline = highWaterMarksFrom(
-			[mailbox("mb-inbox", 10, 100), mailbox("mb-trash", 3, 20)],
-			folders,
-		);
-		const afterArrivalAndDelete = highWaterMarksFrom(
-			[mailbox("mb-inbox", 11, 101), mailbox("mb-trash", 4, 21)],
-			folders,
-		);
-		assert.equal(hasGrown(baseline, afterArrivalAndDelete), true);
-	});
-});
-
-describe("grownMailboxIds", () => {
-	// The invalidation half of the same reading: which folders' listings are
-	// now behind the server, so an open tab reloads exactly those.
-	test("names only the mailboxes that took a higher UID", () => {
-		const baseline = new Map([
-			["mb-1", 100],
-			["mb-2", 40],
-			["mb-3", 70],
-		]);
-		const current = new Map([
-			["mb-1", 120],
-			["mb-2", 40],
-			["mb-3", 70],
-		]);
-
-		assert.deepEqual(grownMailboxIds(baseline, current), ["mb-1"]);
-	});
-
-	test("counts a folder absent from the baseline from zero", () => {
-		assert.deepEqual(grownMailboxIds(new Map(), new Map([["mb-new", 3]])), [
-			"mb-new",
-		]);
-	});
-
-	test("is empty when nothing moved", () => {
-		const marks = new Map([["mb-1", 100]]);
-		assert.deepEqual(grownMailboxIds(marks, new Map(marks)), []);
-	});
-});

package/src/lib/mail-freshness.tsx

@@ -1,244 +0,0 @@
-import { syncOperationsGetSyncStatusOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
-import type { NavMailboxRole } from "@remit/ui";
-import { useQueries, useQueryClient } from "@tanstack/react-query";
-import {
-	createContext,
-	type ReactNode,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-	useState,
-} from "react";
-import { useMailContext } from "@/lib/mail-context";
-import type { ResultFolderIndex } from "@/lib/result-folder";
-import {
-	invalidateThreadListQueries,
-	threadListCacheKeys,
-} from "@/lib/thread-list-cache";
-
-/**
- * How often the background poll re-reads each open account's sync status.
- * `getSyncStatus` is a DDB read with no IMAP call and no queue write (see
- * typespec Sync Operations), so this is the cheap side of the refresh
- * feature — the once-a-minute check that decides whether anything is worth
- * surfacing, never a refetch of the mailbox or brief content itself.
- */
-export const FRESHNESS_POLL_MS = 60_000;
-
-/**
- * Roles whose own new messages are the user's doing, not an arrival: sending
- * appends to Sent, deleting or archiving appends to Trash/Archive, and a Draft
- * is an autosave. Counting any of these as "new mail" would light the dot on a
- * message the user just moved themselves. Junk is kept in — spam is still an
- * arrival, just an unwanted one — and a mailbox with no resolved role (a
- * custom folder, or one a filter files mail into directly) is never excluded.
- */
-const EXCLUDED_GROWTH_ROLES: ReadonlySet<NavMailboxRole> = new Set([
-	"sent",
-	"drafts",
-	"trash",
-	"archive",
-]);
-
-/**
- * Each watched mailbox's highest UID. A total cannot answer "did mail arrive":
- * a message landing in the round that another one leaves nets to zero, so the
- * arrival was invisible (#771). The read model widens that window, because a
- * local delete does not decrement the stored count — only the next sync does,
- * and that same sync carries the arrival. The highest UID only moves up, so it
- * names the arrival on its own.
- */
-type MailboxHighWaterMarks = ReadonlyMap<string, number>;
-
-export const highWaterMarksFrom = (
-	mailboxes: readonly RemitImapMailboxSyncProgress[],
-	resultFolderIndex: ResultFolderIndex,
-): MailboxHighWaterMarks => {
-	const marks = new Map<string, number>();
-	for (const mailbox of mailboxes) {
-		const role = resultFolderIndex.get(mailbox.mailboxId)?.role;
-		if (role && EXCLUDED_GROWTH_ROLES.has(role)) continue;
-		marks.set(mailbox.mailboxId, mailbox.highWaterMarkUid);
-	}
-	return marks;
-};
-
-/**
- * Which mailboxes took a UID above the highest one in the baseline. Pure so the
- * "did mail arrive" call is unit-testable without a DOM or a QueryClient. A
- * mailbox missing from the baseline (new folder, first-ever reading) counts
- * from zero rather than being skipped, so mail landing in a folder created
- * since the last look still counts as an arrival.
- */
-export const grownMailboxIds = (
-	baseline: MailboxHighWaterMarks,
-	current: MailboxHighWaterMarks,
-): string[] => {
-	const grown: string[] = [];
-	for (const [mailboxId, uid] of current) {
-		if (uid > (baseline.get(mailboxId) ?? 0)) grown.push(mailboxId);
-	}
-	return grown;
-};
-
-/** Whether any mailbox took a new message at all — the dot's own question. */
-export const hasGrown = (
-	baseline: MailboxHighWaterMarks,
-	current: MailboxHighWaterMarks,
-): boolean => grownMailboxIds(baseline, current).length > 0;
-
-interface MailFreshnessContextValue {
-	/** True once any of these accounts has grown since it was last acknowledged. */
-	hasNewMail: (accountIds: readonly string[]) => boolean;
-	/** Clears the flag for these accounts and re-baselines them from whatever
-	 * is currently cached — called once a refresh has shown the user current
-	 * data for them. */
-	acknowledge: (accountIds: readonly string[]) => void;
-}
-
-const MailFreshnessContext = createContext<MailFreshnessContextValue | null>(
-	null,
-);
-
-export const useMailFreshness = (): MailFreshnessContextValue => {
-	const ctx = useContext(MailFreshnessContext);
-	if (!ctx) {
-		throw new Error(
-			"useMailFreshness must be used inside <MailFreshnessProvider>",
-		);
-	}
-	return ctx;
-};
-
-interface MailFreshnessProviderProps {
-	accountIds: readonly string[];
-	children: ReactNode;
-}
-
-/**
- * Watches every open account's sync status once a minute and flags which
- * accounts have grown since they were last shown to the user (#582 clause
- * 4). The flag is sticky until acknowledged: it lights the dot on whichever
- * `RefreshButton` reads this context and stays lit until a refresh clears it.
- *
- * A tick that sees a folder take a new highest UID also invalidates that
- * folder's thread listing. It reorders nothing and asks the mail server for
- * nothing — the message is already on our side, so an open list showing it is a
- * cache read, not IMAP work. The dot is still the account-level signal.
- */
-export function MailFreshnessProvider({
-	accountIds,
-	children,
-}: MailFreshnessProviderProps) {
-	const queryClient = useQueryClient();
-	const { resultFolderIndex } = useMailContext();
-	const baselineRef = useRef(new Map<string, MailboxHighWaterMarks>());
-	const seededRef = useRef(new Set<string>());
-	// The previous tick's reading, distinct from the dot's baseline: the dot's
-	// baseline is sticky until acknowledged, so comparing against it would
-	// re-invalidate on every tick for as long as the dot stays lit.
-	const previousMarksRef = useRef(new Map<string, MailboxHighWaterMarks>());
-	const [newMail, setNewMail] = useState<ReadonlySet<string>>(new Set());
-
-	const queries = useQueries({
-		queries: accountIds.map((accountId) => ({
-			...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
-			refetchInterval: FRESHNESS_POLL_MS,
-			staleTime: FRESHNESS_POLL_MS,
-			meta: { softError: true },
-		})),
-	});
-	const updatedKey = queries.map((query) => query.dataUpdatedAt).join(",");
-	const accountIdsKey = accountIds.join(",");
-
-	// biome-ignore lint/correctness/useExhaustiveDependencies: updatedKey is the real trigger (each query's own dataUpdatedAt); queries and resultFolderIndex are read fresh each run, not values this effect reacts to on their own.
-	useEffect(() => {
-		let changed = false;
-		const next = new Set(newMail);
-		accountIds.forEach((accountId, index) => {
-			const data = queries[index]?.data;
-			if (!data) return;
-			const current = highWaterMarksFrom(
-				data.mailboxes ?? [],
-				resultFolderIndex,
-			);
-
-			// Mail that has already landed on the server costs nothing more to
-			// show, so a folder that took a UID above the last tick's reloads
-			// its listing here. That caps how stale an open tab's list can get
-			// at this poll's own interval, without a single extra IMAP round.
-			const previous = previousMarksRef.current.get(accountId);
-			previousMarksRef.current.set(accountId, current);
-			if (previous) {
-				const grown = grownMailboxIds(previous, current);
-				if (grown.length > 0) {
-					invalidateThreadListQueries(queryClient, threadListCacheKeys(grown));
-				}
-			}
-
-			if (!seededRef.current.has(accountId)) {
-				seededRef.current.add(accountId);
-				baselineRef.current.set(accountId, current);
-				return;
-			}
-			if (next.has(accountId)) return;
-			const baseline = baselineRef.current.get(accountId) ?? new Map();
-			if (hasGrown(baseline, current)) {
-				next.add(accountId);
-				changed = true;
-			}
-		});
-		if (changed) setNewMail(next);
-	}, [accountIdsKey, updatedKey]);
-
-	const hasNewMail = useCallback(
-		(ids: readonly string[]) => ids.some((id) => newMail.has(id)),
-		[newMail],
-	);
-
-	const acknowledge = useCallback(
-		(ids: readonly string[]) => {
-			setNewMail((prev) => {
-				if (ids.every((id) => !prev.has(id))) return prev;
-				const next = new Set(prev);
-				for (const id of ids) next.delete(id);
-				return next;
-			});
-			for (const accountId of ids) {
-				// `useRefreshControl` reads and writes this exact query key through
-				// `queryClient.fetchQuery` as its own wait settles, so this is the
-				// data that refresh just showed the user — never a round-old
-				// cached reading from this provider's own 60s interval.
-				const data = queryClient.getQueryData(
-					syncOperationsGetSyncStatusOptions({ path: { accountId } }).queryKey,
-				) as
-					| { mailboxes?: readonly RemitImapMailboxSyncProgress[] }
-					| undefined;
-				baselineRef.current.set(
-					accountId,
-					highWaterMarksFrom(data?.mailboxes ?? [], resultFolderIndex),
-				);
-				seededRef.current.add(accountId);
-			}
-		},
-		[queryClient, resultFolderIndex],
-	);
-
-	// The sync-status queries update on their own cadence (this poll's 60s, or
-	// every 3s while `useInitialSyncProgress` shares the same key during an
-	// initial sync) — memoized so a tick that changes nothing about the
-	// flag set does not re-render every consumer down the tree.
-	const value = useMemo(
-		() => ({ hasNewMail, acknowledge }),
-		[hasNewMail, acknowledge],
-	);
-
-	return (
-		<MailFreshnessContext.Provider value={value}>
-			{children}
-		</MailFreshnessContext.Provider>
-	);
-}