@remit/web-client 0.0.1

package/src/hooks/useSelection.ts

@@ -0,0 +1,211 @@
+import { useCallback, useState } from "react";
+
+/**
+ * Mouse/keyboard modifier flags read off a row click, used to drive desktop
+ * multi-select semantics (shift = range, cmd/ctrl = toggle, plain = open).
+ */
+export interface SelectionModifiers {
+	shiftKey: boolean;
+	metaKey: boolean;
+	ctrlKey: boolean;
+}
+
+interface UseSelectionOptions<T> {
+	/** Function to extract ID from an item */
+	getId: (item: T) => string;
+}
+
+interface UseSelectionReturn {
+	/** Set of currently selected item IDs */
+	selectedIds: Set<string>;
+	/** Number of selected items */
+	selectedCount: number;
+	/** Whether any items are selected */
+	hasSelection: boolean;
+	/** Check if a specific item is selected */
+	isSelected: (id: string) => boolean;
+	/** Toggle selection for a single item (updates the range anchor) */
+	toggle: (id: string) => void;
+	/** Select a single item (adds to selection, updates the range anchor) */
+	select: (id: string) => void;
+	/** Deselect a single item */
+	deselect: (id: string) => void;
+	/** Select all items */
+	selectAll: (ids: string[]) => void;
+	/** Clear all selections (also clears the range anchor) */
+	clearSelection: () => void;
+	/** Toggle selection for all items */
+	toggleAll: (ids: string[]) => void;
+	/**
+	 * Add the contiguous range of ids from the current anchor to `targetId`
+	 * (inclusive) to the selection, using `orderedIds` for display order. If
+	 * no anchor exists, selects only `targetId` and makes it the anchor.
+	 */
+	selectRange: (orderedIds: string[], targetId: string) => void;
+	/**
+	 * Set the range anchor without changing the selection set. Used by a plain
+	 * click that navigates but should seed the anchor for a later shift-click.
+	 */
+	setAnchor: (id: string) => void;
+	/**
+	 * The id of the row that anchors shift-range selection. `undefined` when
+	 * nothing has been selected yet.
+	 */
+	anchorId: string | undefined;
+}
+
+/**
+ * Compute the inclusive slice of ids spanning from `anchorId` to `targetId`
+ * in `orderedIds`. Pure so it can be unit-tested without a DOM.
+ *
+ * - Direction-agnostic: works whether the target sits above or below the anchor.
+ * - Missing anchor (or anchor not in the list): returns just `[targetId]`.
+ * - Target not in the list: returns `[]` (nothing to select).
+ */
+export const computeRange = (
+	orderedIds: string[],
+	anchorId: string | undefined,
+	targetId: string,
+): string[] => {
+	const targetIndex = orderedIds.indexOf(targetId);
+	if (targetIndex === -1) return [];
+
+	const anchorIndex =
+		anchorId === undefined ? -1 : orderedIds.indexOf(anchorId);
+	if (anchorIndex === -1) return [targetId];
+
+	const start = Math.min(anchorIndex, targetIndex);
+	const end = Math.max(anchorIndex, targetIndex);
+	return orderedIds.slice(start, end + 1);
+};
+
+/**
+ * Compute the id one step from `focusId` in `orderedIds`, clamped at the ends.
+ * Pure so the shift-arrow range-extend math can be unit-tested without a DOM.
+ *
+ * - `direction` is -1 for up (previous) or +1 for down (next).
+ * - Missing focus (or focus not in the list): returns the first id for down,
+ *   the last id for up, or `undefined` when the list is empty.
+ * - At a boundary: returns the same `focusId` (no wrap).
+ */
+export const nextFocusId = (
+	orderedIds: string[],
+	focusId: string | undefined,
+	direction: -1 | 1,
+): string | undefined => {
+	if (orderedIds.length === 0) return undefined;
+
+	const currentIndex = focusId === undefined ? -1 : orderedIds.indexOf(focusId);
+	if (currentIndex === -1) {
+		return direction > 0 ? orderedIds[0] : orderedIds[orderedIds.length - 1];
+	}
+
+	const nextIndex = Math.min(
+		Math.max(currentIndex + direction, 0),
+		orderedIds.length - 1,
+	);
+	return orderedIds[nextIndex];
+};
+
+/**
+ * Hook for managing selection state in lists.
+ * Supports single and multi-select operations.
+ */
+export const useSelection = <T>(
+	_options?: UseSelectionOptions<T>,
+): UseSelectionReturn => {
+	const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
+	const [anchorId, setAnchorId] = useState<string | undefined>(undefined);
+
+	const isSelected = useCallback(
+		(id: string) => selectedIds.has(id),
+		[selectedIds],
+	);
+
+	const toggle = useCallback((id: string) => {
+		setAnchorId(id);
+		setSelectedIds((prev) => {
+			const next = new Set(prev);
+			if (next.has(id)) {
+				next.delete(id);
+			} else {
+				next.add(id);
+			}
+			return next;
+		});
+	}, []);
+
+	const select = useCallback((id: string) => {
+		setAnchorId(id);
+		setSelectedIds((prev) => {
+			if (prev.has(id)) return prev;
+			const next = new Set(prev);
+			next.add(id);
+			return next;
+		});
+	}, []);
+
+	const deselect = useCallback((id: string) => {
+		setSelectedIds((prev) => {
+			if (!prev.has(id)) return prev;
+			const next = new Set(prev);
+			next.delete(id);
+			return next;
+		});
+	}, []);
+
+	const selectAll = useCallback((ids: string[]) => {
+		setSelectedIds(new Set(ids));
+	}, []);
+
+	const clearSelection = useCallback(() => {
+		setAnchorId(undefined);
+		setSelectedIds(new Set());
+	}, []);
+
+	const toggleAll = useCallback((ids: string[]) => {
+		setSelectedIds((prev) => {
+			const allSelected = ids.every((id) => prev.has(id));
+			return allSelected ? new Set() : new Set(ids);
+		});
+	}, []);
+
+	const setAnchor = useCallback((id: string) => {
+		setAnchorId(id);
+	}, []);
+
+	const selectRange = useCallback(
+		(orderedIds: string[], targetId: string) => {
+			setSelectedIds((prev) => {
+				const range = computeRange(orderedIds, anchorId, targetId);
+				if (range.length === 0) return prev;
+				const next = new Set(prev);
+				for (const id of range) {
+					next.add(id);
+				}
+				return next;
+			});
+			// Keep the original anchor so subsequent shift-clicks extend from the
+			// same origin (Apple Mail / Gmail behavior). Only seed the anchor when
+			// none exists yet.
+			setAnchorId((prev) => prev ?? targetId);
+		},
+		[anchorId],
+	);
+
+	return {
+		selectedIds,
+		selectedCount: selectedIds.size,
+		hasSelection: selectedIds.size > 0,
+		isSelected,
+		toggle,
+		select,
+		deselect,
+		selectAll,
+		clearSelection,
+		toggleAll,
+		selectRange,
+		setAnchor,
+		anchorId,
+	};
+};

package/src/hooks/useSemanticSearch.ts

@@ -0,0 +1,94 @@
+import { semanticSearchOperationsSemanticSearchOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapSemanticSearchResult } from "@remit/api-http-client/types.gen.ts";
+import { MessageCategory } from "@remit/domain-enums";
+import { useQuery } from "@tanstack/react-query";
+import { useMailContext } from "@/lib/mail-context";
+import { normalizeSearchQuery } from "@/lib/search-query";
+import { parseSearchTokens } from "@/lib/search-tokens";
+
+/** Cap the "Related" section; the literal "Top matches" is the primary surface. */
+const SEMANTIC_RESULT_LIMIT = 20;
+
+const MESSAGE_CATEGORIES = new Set<string>(Object.values(MessageCategory));
+
+/** Narrow a filter-chip id to a real category, or `undefined` for `"all"` / any unknown value. */
+const toCategoryParam = (
+	filterCategory: string | undefined,
+): (typeof MessageCategory)[keyof typeof MessageCategory] | undefined =>
+	filterCategory !== undefined && MESSAGE_CATEGORIES.has(filterCategory)
+		? (filterCategory as (typeof MessageCategory)[keyof typeof MessageCategory])
+		: undefined;
+
+interface UseSemanticSearchParams {
+	/**
+	 * Restrict results to a single mailbox (the scoped inbox). Omit for the
+	 * cross-account daily brief, where semantic search spans every account.
+	 */
+	mailboxId?: string;
+	/**
+	 * Restrict results to a single header-derived category. The sentinel `"all"`
+	 * means no category scope — the param is omitted from the request entirely.
+	 */
+	filterCategory?: string;
+}
+
+/**
+ * Fetch semantic-search hits for the active query (one source of truth: the
+ * debounced `searchQuery` in `MailContext`). Scoping mirrors the literal search:
+ * pass `mailboxId` for a scoped inbox, omit it for the global brief. Disabled
+ * until the query is non-empty so an empty field issues no request.
+ *
+ * Filter tokens (`has:attachment`, `is:unread`, `before:`/`after:`) parsed from
+ * the query map onto the search API's own filter params. `from:` and
+ * `account:` have no equivalent on `GET /search/semantic` (no sender or
+ * account filter) — both still render as chips and narrow the literal engine,
+ * but never reach the semantic request (`account:` is a documented gap, see
+ * doc/design/flows/06-search.md — the semantic index is per account config).
+ * `in:` resolves to a mailboxId and, when present, overrides the caller's
+ * `mailboxId` — so typing `in:archive` re-scopes the semantic search to that
+ * mailbox even from the cross-account daily brief.
+ */
+export function useSemanticSearch({
+	mailboxId,
+	filterCategory,
+}: UseSemanticSearchParams = {}): {
+	hits: RemitImapSemanticSearchResult[];
+	isLoading: boolean;
+} {
+	const { searchQuery, mailboxNameIndex, accountNameIndex } = useMailContext();
+	const normalizedQuery = normalizeSearchQuery(searchQuery);
+	const { freeText, tokens } = parseSearchTokens(normalizedQuery, {
+		mailboxesByName: mailboxNameIndex,
+		accountsByName: accountNameIndex,
+	});
+	const enabled = normalizedQuery.length > 0;
+
+	const category = toCategoryParam(filterCategory);
+	const hasAttachment = tokens.some((t) => t.type === "hasAttachment")
+		? true
+		: undefined;
+	const isRead = tokens.some((t) => t.type === "isUnread") ? false : undefined;
+	const afterToken = tokens.find((t) => t.type === "after");
+	const beforeToken = tokens.find((t) => t.type === "before");
+	const inToken = tokens.find((t) => t.type === "in");
+	const effectiveMailboxId = inToken?.mailboxId ?? mailboxId;
+
+	const { data, isLoading } = useQuery({
+		...semanticSearchOperationsSemanticSearchOptions({
+			query: {
+				query: freeText,
+				mailboxId: effectiveMailboxId,
+				limit: SEMANTIC_RESULT_LIMIT,
+				...(category !== undefined ? { category } : {}),
+				...(hasAttachment !== undefined ? { hasAttachment } : {}),
+				...(isRead !== undefined ? { isRead } : {}),
+				...(afterToken ? { sentDateFrom: afterToken.epochSeconds } : {}),
+				...(beforeToken ? { sentDateTo: beforeToken.epochSeconds } : {}),
+			},
+		}),
+		enabled,
+		staleTime: 60_000,
+	});
+
+	return { hits: data?.items ?? [], isLoading: enabled && isLoading };
+}

package/src/hooks/useSignature.ts

@@ -0,0 +1,69 @@
+import {
+	accountDetailOperationsUpdateAccountMutation,
+	configOperationsGetConfigOptions,
+	configOperationsGetConfigQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "@/components/ui/error-banners";
+
+export interface SignatureData {
+	html: string;
+	plainText: string;
+}
+
+const EMPTY_SIGNATURE: SignatureData = { html: "", plainText: "" };
+
+export const useSignature = (accountId?: string) => {
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+
+	const { data: config } = useQuery({
+		...configOperationsGetConfigOptions(),
+		staleTime: Infinity,
+	});
+
+	const signature = useMemo<SignatureData>(() => {
+		if (!accountId || !config) return EMPTY_SIGNATURE;
+		const account = config.accounts.find((a) => a.accountId === accountId);
+		if (!account) return EMPTY_SIGNATURE;
+		return {
+			html: account.signatureHtml ?? "",
+			plainText: account.signaturePlainText ?? "",
+		};
+	}, [accountId, config]);
+
+	const mutation = useMutation({
+		...accountDetailOperationsUpdateAccountMutation(),
+		onSuccess: () => {
+			queryClient.invalidateQueries({
+				queryKey: configOperationsGetConfigQueryKey(),
+			});
+		},
+		onError: (error) => {
+			// Saving the signature failed silently before — surface it. A fatal
+			// 5xx also escalates through the global MutationCache.onError sink.
+			pushError(
+				buildMutationErrorBanner(
+					"Couldn't save signature",
+					"The signature wasn't saved.",
+					error,
+				),
+			);
+		},
+	});
+
+	const setSignature = useCallback(
+		(html: string, plainText: string) => {
+			if (!accountId) return;
+			mutation.mutate({
+				path: { accountId },
+				body: { signatureHtml: html, signaturePlainText: plainText },
+			});
+		},
+		[accountId, mutation],
+	);
+
+	return { signature, setSignature, isSaving: mutation.isPending };
+};

package/src/hooks/useStaleAccountSync.test.ts

@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, test } from "node:test";
+import { ApiError } from "../lib/api.js";
+import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error.js";
+import {
+	__peekStaleAccountSyncGuard,
+	__resetStaleAccountSyncGuard,
+	handleBackgroundSyncFailure,
+	hasPollIntervalElapsed,
+	POLL_INTERVAL_MS,
+	STALENESS_THRESHOLD_MS,
+	selectPollableAccountIds,
+	selectStaleAccountIds,
+} from "./useStaleAccountSync.js";
+
+const NOW = 1_700_000_000_000;
+
+describe("STALENESS_THRESHOLD_MS", () => {
+	test("equals 15 minutes in milliseconds", () => {
+		assert.equal(STALENESS_THRESHOLD_MS, 15 * 60 * 1000);
+	});
+});
+
+describe("selectStaleAccountIds", () => {
+	test("treats accounts with undefined lastSyncAt as stale", () => {
+		const ids = selectStaleAccountIds(
+			[{ accountId: "a-1", lastSyncAt: undefined }],
+			NOW,
+		);
+		assert.deepEqual(ids, ["a-1"]);
+	});
+
+	test("treats accounts with null lastSyncAt as stale", () => {
+		const ids = selectStaleAccountIds(
+			// Real network responses can deserialize undefined as null in some
+			// transports; cover both shapes.
+			[{ accountId: "a-1", lastSyncAt: null as unknown as undefined }],
+			NOW,
+		);
+		assert.deepEqual(ids, ["a-1"]);
+	});
+
+	test("returns the account when lastSyncAt is older than the threshold", () => {
+		const ids = selectStaleAccountIds(
+			[
+				{
+					accountId: "a-1",
+					lastSyncAt: NOW - STALENESS_THRESHOLD_MS - 1000,
+				},
+			],
+			NOW,
+		);
+		assert.deepEqual(ids, ["a-1"]);
+	});
+
+	test("does not return an account that synced inside the threshold", () => {
+		const ids = selectStaleAccountIds(
+			[{ accountId: "a-1", lastSyncAt: NOW - 60_000 }],
+			NOW,
+		);
+		assert.deepEqual(ids, []);
+	});
+
+	test("returns only the stale accounts when mixed", () => {
+		const ids = selectStaleAccountIds(
+			[
+				{ accountId: "fresh", lastSyncAt: NOW - 5 * 60_000 },
+				{ accountId: "stale", lastSyncAt: NOW - 30 * 60_000 },
+				{ accountId: "never", lastSyncAt: undefined },
+			],
+			NOW,
+		);
+		assert.deepEqual(ids, ["stale", "never"]);
+	});
+
+	test("respects an overridden threshold", () => {
+		const ids = selectStaleAccountIds(
+			[{ accountId: "a-1", lastSyncAt: NOW - 1500 }],
+			NOW,
+			1000,
+		);
+		assert.deepEqual(ids, ["a-1"]);
+	});
+
+	test("returns an empty list for an empty input", () => {
+		assert.deepEqual(selectStaleAccountIds([], NOW), []);
+	});
+
+	test("equality on the threshold is treated as fresh", () => {
+		// `now - lastSyncAt > thresholdMs` — strict greater-than means an
+		// account synced exactly threshold ms ago is still fresh. Pinning
+		// this so a future tweak to `>=` is a deliberate decision.
+		const ids = selectStaleAccountIds(
+			[{ accountId: "a-1", lastSyncAt: NOW - STALENESS_THRESHOLD_MS }],
+			NOW,
+		);
+		assert.deepEqual(ids, []);
+	});
+});
+
+describe("POLL_INTERVAL_MS", () => {
+	test("defaults to 5 minutes when mailboxPollIntervalSeconds is unset in this test run", () => {
+		assert.equal(POLL_INTERVAL_MS, 5 * 60 * 1000);
+	});
+});
+
+describe("hasPollIntervalElapsed", () => {
+	test("is false immediately after a poll", () => {
+		assert.equal(hasPollIntervalElapsed(NOW, NOW, 60_000), false);
+	});
+
+	test("is false before a full interval has elapsed", () => {
+		assert.equal(hasPollIntervalElapsed(NOW, NOW - 59_000, 60_000), false);
+	});
+
+	test("is true exactly at the interval boundary", () => {
+		assert.equal(hasPollIntervalElapsed(NOW, NOW - 60_000, 60_000), true);
+	});
+
+	test("is true once the interval has passed", () => {
+		assert.equal(hasPollIntervalElapsed(NOW, NOW - 61_000, 60_000), true);
+	});
+
+	test("defaults to POLL_INTERVAL_MS when no interval is passed", () => {
+		assert.equal(hasPollIntervalElapsed(NOW, NOW - POLL_INTERVAL_MS - 1), true);
+		assert.equal(
+			hasPollIntervalElapsed(NOW, NOW - POLL_INTERVAL_MS + 1),
+			false,
+		);
+	});
+});
+
+describe("selectPollableAccountIds", () => {
+	test("returns every accountId when nothing is in flight", () => {
+		const ids = selectPollableAccountIds(["a-1", "a-2"], new Set());
+		assert.deepEqual(ids, ["a-1", "a-2"]);
+	});
+
+	test("drops an accountId already in flight (no stacked requests)", () => {
+		const ids = selectPollableAccountIds(["a-1", "a-2"], new Set(["a-1"]));
+		assert.deepEqual(ids, ["a-2"]);
+	});
+
+	test("returns an empty list when every account is in flight", () => {
+		const ids = selectPollableAccountIds(
+			["a-1", "a-2"],
+			new Set(["a-1", "a-2"]),
+		);
+		assert.deepEqual(ids, []);
+	});
+});
+
+describe("handleBackgroundSyncFailure", () => {
+	afterEach(() => {
+		__resetFatalError();
+		__resetStaleAccountSyncGuard();
+		console.warn = originalWarn;
+	});
+
+	const originalWarn = console.warn;
+	const silenceWarn = () => {
+		console.warn = () => undefined;
+	};
+
+	test("a background-sync 5xx escalates to the fatal overlay", () => {
+		silenceWarn();
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+
+		handleBackgroundSyncFailure("a-1", new ApiError("boom", 503));
+
+		// Fail-fast contract (#1059, rule 2): a 5xx is OUR API broken and always
+		// escalates — even from a best-effort background probe. (This reverses the
+		// #758 swallow, which let a real 500 vanish silently.)
+		assert.deepEqual(seen, ["boom"]);
+	});
+
+	test("a background-sync 4xx (the account's own problem) does NOT escalate", () => {
+		silenceWarn();
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+
+		handleBackgroundSyncFailure("a-1", new ApiError("forbidden", 403));
+
+		// Non-5xx stays soft — the call site owns it (the Settings "Refresh
+		// mailboxes" button is the surfaced path).
+		assert.equal(escalated, false);
+	});
+
+	test("a network blip on the background probe does NOT escalate", () => {
+		silenceWarn();
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+
+		handleBackgroundSyncFailure("a-1", new TypeError("Failed to fetch"));
+
+		assert.equal(escalated, false);
+	});
+
+	test("drops the per-account guard so a later remount can retry", () => {
+		silenceWarn();
+		__peekStaleAccountSyncGuard(); // touch to ensure import is used
+		handleBackgroundSyncFailure("a-1", new ApiError("boom", 503));
+
+		assert.equal(__peekStaleAccountSyncGuard().has("a-1"), false);
+	});
+});