@remit/web-client 0.0.1

package/src/hooks/useToggleTrusted.ts

@@ -0,0 +1,161 @@
+import {
+	addressDetailOperationsUpdateAddressMutation,
+	messageOperationsDescribeMessageQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapAddressFlags,
+	RemitImapDescribeMessageResponse,
+	RemitImapEnvelopeAddressResponse,
+	RemitImapTrustedFlag,
+} from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "@/components/ui/error-banners";
+
+interface UseToggleTrustedOptions {
+	messageId: string;
+}
+
+interface SnapshotEntry {
+	queryKey: readonly unknown[];
+	data: RemitImapDescribeMessageResponse;
+}
+
+interface ToggleTrustedContext {
+	describePrefix: readonly unknown[];
+	previous: SnapshotEntry[];
+}
+
+export const buildTrustedFlag = (
+	nextTrusted: boolean,
+	now: number = Date.now(),
+): RemitImapTrustedFlag => ({
+	value: nextTrusted,
+	setAt: now,
+});
+
+export const patchEnvelopeAddress = (
+	addr: RemitImapEnvelopeAddressResponse,
+	addressId: string,
+	nextTrusted: boolean,
+	now?: number,
+): RemitImapEnvelopeAddressResponse => {
+	if (addr.addressId !== addressId) return addr;
+	const flags: RemitImapAddressFlags = { ...(addr.flags ?? {}) };
+	if (nextTrusted) {
+		flags.trusted = buildTrustedFlag(true, now);
+	} else {
+		delete flags.trusted;
+	}
+	return { ...addr, flags };
+};
+
+export const patchDescribeMessage = (
+	data: RemitImapDescribeMessageResponse,
+	addressId: string,
+	nextTrusted: boolean,
+	now?: number,
+): RemitImapDescribeMessageResponse => {
+	const map = (list: RemitImapEnvelopeAddressResponse[]) =>
+		list.map((addr) => patchEnvelopeAddress(addr, addressId, nextTrusted, now));
+	return {
+		...data,
+		envelope: {
+			...data.envelope,
+			from: map(data.envelope.from),
+			to: map(data.envelope.to),
+			cc: map(data.envelope.cc),
+			bcc: map(data.envelope.bcc),
+			replyTo: map(data.envelope.replyTo),
+		},
+	};
+};
+
+/**
+ * Toggle the per-sender `trusted` flag for an Address. Mirrors the optimistic-
+ * update + rollback pattern from `useToggleStar`: we patch every cached
+ * `describeMessage` response that mentions this address so the UI flips
+ * instantly, then roll back on error per the project's "never hide failure"
+ * rule. The failure is surfaced reliably here in `onError` (banner + rollback),
+ * not via a fragile consumer effect; a fatal 5xx additionally escalates through
+ * the global MutationCache.onError sink.
+ */
+export const useToggleTrusted = ({ messageId }: UseToggleTrustedOptions) => {
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+
+	const { mutate, isPending, error, reset } = useMutation({
+		...addressDetailOperationsUpdateAddressMutation(),
+		onMutate: async (vars): Promise<ToggleTrustedContext> => {
+			const addressId = vars.path.addressId;
+			const trustedPatch = vars.body.flags?.trusted;
+			const nextTrusted = trustedPatch?.value === true;
+
+			const describePrefix = messageOperationsDescribeMessageQueryKey({
+				path: { messageId },
+			});
+
+			await queryClient.cancelQueries({ queryKey: describePrefix });
+
+			const previous = queryClient
+				.getQueriesData<RemitImapDescribeMessageResponse>({
+					queryKey: describePrefix,
+				})
+				.filter(
+					(
+						entry,
+					): entry is [readonly unknown[], RemitImapDescribeMessageResponse] =>
+						entry[1] !== undefined,
+				)
+				.map(([queryKey, data]) => ({ queryKey, data }));
+
+			queryClient.setQueriesData<RemitImapDescribeMessageResponse>(
+				{ queryKey: describePrefix },
+				(old) =>
+					old ? patchDescribeMessage(old, addressId, nextTrusted) : old,
+			);
+
+			return { describePrefix, previous };
+		},
+		onError: (err, _vars, context) => {
+			if (context) {
+				for (const entry of context.previous) {
+					queryClient.setQueryData(entry.queryKey, entry.data);
+				}
+			}
+			pushError(
+				buildMutationErrorBanner(
+					"Couldn't trust sender",
+					"The change wasn't saved.",
+					err,
+				),
+			);
+		},
+		onSettled: (_data, _err, _vars, context) => {
+			if (!context) return;
+			queryClient.invalidateQueries({ queryKey: context.describePrefix });
+		},
+	});
+
+	const toggleTrusted = (addressId: string, currentlyTrusted: boolean) => {
+		const next = !currentlyTrusted;
+		// Always send a TrustedFlag object (value: true|false). The schema
+		// nominally accepts `trusted: null` to remove the flag, but our
+		// openapi-backend validator doesn't honour `nullable: true` on a
+		// schema wrapped in `allOf: [$ref]` (which is how TypeSpec emits
+		// `TrustedFlag | null` for OAS 3.0), so the server rejected untrust
+		// requests as invalid. `{ value: false }` reads as "not trusted"
+		// everywhere (every check is `flags?.trusted?.value === true`) and
+		// also leaves an audit timestamp on the flag.
+		mutate({
+			path: { addressId },
+			body: {
+				flags: {
+					trusted: buildTrustedFlag(next),
+				},
+			},
+		});
+	};
+
+	return { toggleTrusted, isPending, error, reset };
+};

package/src/hooks/useTriageKeyboard.ts

@@ -0,0 +1,103 @@
+import { useEffect, useRef } from "react";
+import type { TriageAction } from "@/lib/keymap";
+import {
+	dispatchKey,
+	isEditableTarget,
+	type SequencePrefix,
+} from "@/lib/keymap-dispatch";
+
+/** Map of action → handler. Omitted actions are inert (no-op). */
+export type TriageHandlers = Partial<Record<TriageAction, () => void>>;
+
+interface UseTriageKeyboardOptions {
+	handlers: TriageHandlers;
+	/** Disable the whole layer (e.g. a blocking modal owns the keyboard). */
+	enabled?: boolean;
+	/**
+	 * Reset window (ms) for a pending `g …` sequence prefix. After this with no
+	 * second key, the prefix is dropped. ~1s per the spec.
+	 */
+	sequenceTimeoutMs?: number;
+}
+
+/**
+ * Global keydown handler for the triage layer's VERBS (#429). Routes keystrokes
+ * through the pure {@link dispatchKey} core to the supplied handler table,
+ * staying fully inert while focus is in an editable surface (input/textarea/CE;
+ * even Esc is left to the focused field's own handler) and carrying the `g …`
+ * go-to sequence prefix across keystrokes with a timeout.
+ *
+ * Routing is intentionally NOT fully unified yet: this hook owns the action
+ * verbs + go-to keys, while the list-local navigation keys (j/k/x/Enter/d,
+ * Shift+arrow, Delete/Backspace) are still routed by MessageList's legacy
+ * `useKeyboardNavigation`, `/` by SearchBar, and `?` by the mail layout — three
+ * separate window listeners, each with its own (consistent) input-guard. The
+ * `@/lib/keymap` module is the single source of truth for the DISPLAYED
+ * bindings (the `?` overlay + tooltips), but not yet for routing. Consolidating
+ * every binding through `dispatchKey` is a follow-up; see #429.
+ *
+ * Per-action targeting (focused row vs selection) and the actual mutations live
+ * in the handlers the caller passes in — this hook only dispatches.
+ */
+export function useTriageKeyboard({
+	handlers,
+	enabled = true,
+	sequenceTimeoutMs = 1000,
+}: UseTriageKeyboardOptions): void {
+	// Latest handlers without re-subscribing the listener every render.
+	const handlersRef = useRef(handlers);
+	handlersRef.current = handlers;
+
+	const prefixRef = useRef<SequencePrefix>(null);
+	const prefixTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		const clearPrefixTimer = () => {
+			if (prefixTimerRef.current !== null) {
+				clearTimeout(prefixTimerRef.current);
+				prefixTimerRef.current = null;
+			}
+		};
+
+		const onKeyDown = (event: KeyboardEvent) => {
+			const result = dispatchKey(
+				{
+					key: event.key,
+					shiftKey: event.shiftKey,
+					metaKey: event.metaKey,
+					ctrlKey: event.ctrlKey,
+					altKey: event.altKey,
+					inEditable: isEditableTarget(event.target),
+				},
+				prefixRef.current,
+			);
+
+			// Update the pending prefix and (re)arm / clear its reset timer.
+			clearPrefixTimer();
+			prefixRef.current = result.nextPrefix;
+			if (result.nextPrefix !== null) {
+				prefixTimerRef.current = setTimeout(() => {
+					prefixRef.current = null;
+					prefixTimerRef.current = null;
+				}, sequenceTimeoutMs);
+			}
+
+			if (result.action === null) return;
+
+			const handler = handlersRef.current[result.action];
+			if (!handler) return;
+
+			if (result.preventDefault) event.preventDefault();
+			handler();
+		};
+
+		window.addEventListener("keydown", onKeyDown);
+		return () => {
+			window.removeEventListener("keydown", onKeyDown);
+			clearPrefixTimer();
+			prefixRef.current = null;
+		};
+	}, [enabled, sequenceTimeoutMs]);
+}

package/src/hooks/useTriggerSync.test.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { buildMailboxListKey } from "./useTriggerSync.js";
+
+describe("buildMailboxListKey", () => {
+	test("matches the generated SDK query key for the same accountId", () => {
+		// On success the trigger-sync mutation invalidates this key — if it
+		// drifts from the generated SDK key, the freshly-synced mailbox rows
+		// will not be re-fetched. Pin the contract.
+		const accountId = "acc-1234";
+		const got = buildMailboxListKey(accountId);
+		const want = mailboxOperationsListMailboxesQueryKey({
+			path: { accountId },
+		});
+		assert.deepEqual(got, want);
+	});
+
+	test("returns a different key for a different accountId", () => {
+		const a = buildMailboxListKey("acc-1");
+		const b = buildMailboxListKey("acc-2");
+		assert.notDeepEqual(a, b);
+	});
+});

package/src/hooks/useTriggerSync.ts

@@ -0,0 +1,58 @@
+import {
+	mailboxOperationsListMailboxesQueryKey,
+	syncOperationsTriggerSyncMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useTelemetry } from "@/lib/telemetry-context";
+
+interface UseTriggerSyncResult {
+	trigger: () => void;
+	triggerAsync: () => Promise<unknown>;
+	isPending: boolean;
+	error: Error | null;
+	reset: () => void;
+}
+
+/**
+ * Build the TanStack query key for the mailbox-list query owned by the
+ * given account. Extracted from the hook so the staleness/invalidation
+ * contract can be unit-tested without rendering React.
+ */
+export const buildMailboxListKey = (accountId: string) =>
+	mailboxOperationsListMailboxesQueryKey({ path: { accountId } });
+
+/**
+ * Trigger a server-side mailbox-list sync for an account.
+ *
+ * Wraps the generated `syncOperationsTriggerSync` mutation. The backend
+ * enqueues a SYNC_MAILBOXES SQS event and the worker picks it up; the
+ * mutation resolves as soon as the enqueue ack returns, not when the
+ * sync itself finishes. We invalidate the account's mailboxes query on
+ * success so the freshly-synced rows are re-fetched once the worker
+ * writes them — TanStack will pick the new data up via its background
+ * refetch on the next render.
+ */
+export const useTriggerSync = (accountId: string): UseTriggerSyncResult => {
+	const queryClient = useQueryClient();
+	const telemetry = useTelemetry();
+
+	const mutation = useMutation({
+		...syncOperationsTriggerSyncMutation(),
+		onSuccess: () => {
+			telemetry.recordEvent("sync.triggered");
+			queryClient.invalidateQueries({
+				queryKey: buildMailboxListKey(accountId),
+			});
+		},
+	});
+
+	return {
+		trigger: () => {
+			mutation.mutate({ path: { accountId } });
+		},
+		triggerAsync: () => mutation.mutateAsync({ path: { accountId } }),
+		isPending: mutation.isPending,
+		error: mutation.error,
+		reset: mutation.reset,
+	};
+};

package/src/hooks/useUpdateAddressFlags.ts

@@ -0,0 +1,125 @@
+import {
+	addressDetailOperationsUpdateAddressMutation,
+	addressOperationsSearchAddressesQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	AddressOperationsSearchAddressesResponse,
+	RemitImapAddressFlags,
+	RemitImapUpdateAddressFlagsInput,
+} from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "@/components/ui/error-banners";
+import { reportFatalError } from "@/lib/fatal-error";
+
+interface UseUpdateAddressFlagsOptions {
+	addressId: string | undefined;
+	/** The normalizedEmail of the sender — used to key the address search cache. */
+	senderEmail: string | undefined;
+}
+
+interface MutationContext {
+	previous: AddressOperationsSearchAddressesResponse | undefined;
+}
+
+/**
+ * Apply a flag-update patch onto an existing AddressFlags object. Each key in
+ * `patch` is a flag update object (set) or `null` (remove). Mirrors the
+ * server-side merge semantics so the optimistic cache matches what the API
+ * returns. Typed loosely (the per-key flag value types differ — boolean for
+ * most, a category enum for `category`) and re-narrowed at the return.
+ */
+function applyFlagPatch(
+	current: RemitImapAddressFlags | undefined,
+	patch: RemitImapUpdateAddressFlagsInput,
+): RemitImapAddressFlags {
+	const next: Record<string, unknown> = { ...(current ?? {}) };
+	for (const [key, update] of Object.entries(patch)) {
+		if (update == null) {
+			delete next[key];
+		} else {
+			// Each flag is `{ value, setAt? }`. Stamp setAt so the optimistic
+			// shape matches what the server writes back.
+			next[key] = { ...update, setAt: update.setAt ?? Date.now() };
+		}
+	}
+	return next as RemitImapAddressFlags;
+}
+
+/**
+ * Optimistic PATCH for per-sender flags (VIP / Mute / Block / Unsubscribe).
+ * Mirrors the `useToggleTrusted` pattern: patch the cached
+ * address-search response so the toggle flips instantly, roll back on error,
+ * and invalidate on settle to reconcile with the server.
+ */
+export function useUpdateAddressFlags({
+	addressId,
+	senderEmail,
+}: UseUpdateAddressFlagsOptions) {
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+
+	const addressCacheKey = addressOperationsSearchAddressesQueryKey({
+		query: { q: senderEmail ?? "", limit: 1 },
+	});
+
+	const { mutate, isPending } = useMutation({
+		...addressDetailOperationsUpdateAddressMutation(),
+		onMutate: async (vars): Promise<MutationContext> => {
+			const patch = vars.body.flags ?? {};
+			await queryClient.cancelQueries({ queryKey: addressCacheKey });
+
+			const previous =
+				queryClient.getQueryData<AddressOperationsSearchAddressesResponse>(
+					addressCacheKey,
+				);
+
+			queryClient.setQueryData<AddressOperationsSearchAddressesResponse>(
+				addressCacheKey,
+				(old) => {
+					if (!old) return old;
+					return {
+						...old,
+						items: old.items.map((addr) =>
+							addr.addressId === vars.path.addressId
+								? { ...addr, flags: applyFlagPatch(addr.flags, patch) }
+								: addr,
+						),
+					};
+				},
+			);
+
+			return { previous };
+		},
+		onError: (err, _vars, context) => {
+			if (context?.previous !== undefined) {
+				queryClient.setQueryData(addressCacheKey, context.previous);
+			}
+			pushError({
+				title: "Couldn't update sender preference",
+				detail: formatErrorDetail(err),
+			});
+		},
+		onSettled: () => {
+			queryClient.invalidateQueries({ queryKey: addressCacheKey });
+		},
+	});
+
+	const updateFlags = useCallback(
+		(flags: RemitImapUpdateAddressFlagsInput) => {
+			if (!addressId) {
+				reportFatalError(
+					new Error(
+						`Quick action fired but the sender's address record did not resolve (sender: ${senderEmail ?? "unknown"}). This should never happen — the address row exists.`,
+					),
+				);
+				return;
+			}
+			mutate({ path: { addressId }, body: { flags } });
+		},
+		[addressId, mutate, senderEmail],
+	);
+
+	return { updateFlags, isPending };
+}

package/src/hooks/useVisualViewport.test.ts

@@ -0,0 +1,127 @@
+import assert from "node:assert";
+import { beforeEach, describe, test } from "node:test";
+
+/**
+ * Unit test for useVisualViewport hook logic.
+ * Tests the core behaviour without React — mirrors the pattern used
+ * by useLongPress.test.ts in this project.
+ */
+
+const KEYBOARD_THRESHOLD = 150;
+
+interface ViewportState {
+	viewportHeight: number;
+	isKeyboardOpen: boolean;
+}
+
+/**
+ * Simulates the viewport-tracking logic from useVisualViewport.
+ */
+class VisualViewportSimulator {
+	private innerHeight: number;
+	private viewportHeight: number;
+	private listeners: Array<() => void> = [];
+
+	constructor(innerHeight: number) {
+		this.innerHeight = innerHeight;
+		this.viewportHeight = innerHeight;
+	}
+
+	getState(): ViewportState {
+		return {
+			viewportHeight: this.viewportHeight,
+			isKeyboardOpen:
+				this.innerHeight - this.viewportHeight > KEYBOARD_THRESHOLD,
+		};
+	}
+
+	/** Simulate a visualViewport resize (e.g. keyboard appearing). */
+	resize(newViewportHeight: number): ViewportState {
+		this.viewportHeight = newViewportHeight;
+		for (const fn of this.listeners) fn();
+		return this.getState();
+	}
+
+	addListener(fn: () => void): void {
+		this.listeners.push(fn);
+	}
+
+	removeListener(fn: () => void): void {
+		this.listeners = this.listeners.filter((l) => l !== fn);
+	}
+
+	get listenerCount(): number {
+		return this.listeners.length;
+	}
+}
+
+describe("useVisualViewport logic", () => {
+	let sim: VisualViewportSimulator;
+
+	beforeEach(() => {
+		// iPhone-like viewport: 844px tall
+		sim = new VisualViewportSimulator(844);
+	});
+
+	test("initial state has keyboard closed", () => {
+		const state = sim.getState();
+		assert.strictEqual(state.viewportHeight, 844);
+		assert.strictEqual(state.isKeyboardOpen, false);
+	});
+
+	test("keyboard open when viewport shrinks by more than threshold", () => {
+		// Typical iOS keyboard: viewport shrinks to ~400px
+		const state = sim.resize(400);
+		assert.strictEqual(state.isKeyboardOpen, true);
+		assert.strictEqual(state.viewportHeight, 400);
+	});
+
+	test("keyboard stays closed for small viewport changes", () => {
+		// Address bar collapsing — only ~50px change
+		const state = sim.resize(794);
+		assert.strictEqual(state.isKeyboardOpen, false);
+	});
+
+	test("keyboard closes when viewport restores", () => {
+		sim.resize(400);
+		const state = sim.resize(844);
+		assert.strictEqual(state.isKeyboardOpen, false);
+		assert.strictEqual(state.viewportHeight, 844);
+	});
+
+	test("exactly at threshold boundary — not open", () => {
+		// innerHeight - viewportHeight === 150, not > 150
+		const state = sim.resize(844 - KEYBOARD_THRESHOLD);
+		assert.strictEqual(state.isKeyboardOpen, false);
+	});
+
+	test("one pixel past threshold — keyboard open", () => {
+		const state = sim.resize(844 - KEYBOARD_THRESHOLD - 1);
+		assert.strictEqual(state.isKeyboardOpen, true);
+	});
+
+	test("listeners are called on resize", () => {
+		let callCount = 0;
+		sim.addListener(() => {
+			callCount++;
+		});
+		sim.resize(400);
+		sim.resize(844);
+		assert.strictEqual(callCount, 2);
+	});
+
+	test("removeListener stops notifications", () => {
+		let callCount = 0;
+		const fn = () => {
+			callCount++;
+		};
+		sim.addListener(fn);
+		sim.resize(400);
+		assert.strictEqual(callCount, 1);
+
+		sim.removeListener(fn);
+		sim.resize(844);
+		assert.strictEqual(callCount, 1);
+		assert.strictEqual(sim.listenerCount, 0);
+	});
+});

package/src/hooks/useVisualViewport.ts

@@ -0,0 +1,51 @@
+import { useEffect, useState } from "react";
+
+interface VisualViewportState {
+	/** Current visual viewport height in pixels. */
+	viewportHeight: number;
+	/** True when the viewport has shrunk significantly (e.g. software keyboard open). */
+	isKeyboardOpen: boolean;
+}
+
+/** Minimum shrinkage (px) from window.innerHeight to consider the keyboard open. */
+const KEYBOARD_THRESHOLD = 150;
+
+/**
+ * Tracks `window.visualViewport` resize events and reports whether the
+ * software keyboard is likely open. SSR-safe — returns safe defaults
+ * when `window` or `visualViewport` are unavailable.
+ */
+export const useVisualViewport = (): VisualViewportState => {
+	const [state, setState] = useState<VisualViewportState>(() => {
+		if (typeof window === "undefined" || !window.visualViewport) {
+			return { viewportHeight: 0, isKeyboardOpen: false };
+		}
+		const h = window.visualViewport.height;
+		return {
+			viewportHeight: h,
+			isKeyboardOpen: window.innerHeight - h > KEYBOARD_THRESHOLD,
+		};
+	});
+
+	useEffect(() => {
+		if (typeof window === "undefined" || !window.visualViewport) return;
+
+		const vv = window.visualViewport;
+
+		const update = () => {
+			const h = vv.height;
+			setState({
+				viewportHeight: h,
+				isKeyboardOpen: window.innerHeight - h > KEYBOARD_THRESHOLD,
+			});
+		};
+
+		// Sync on mount
+		update();
+
+		vv.addEventListener("resize", update);
+		return () => vv.removeEventListener("resize", update);
+	}, []);
+
+	return state;
+};

package/src/index.css

@@ -0,0 +1,19 @@
+/* remit-ui owns @import "tailwindcss", the @theme token block, :root and
+   .dark — importing its token sheet gives the web client the full design
+   system. The @custom-variant dark declaration inside tokens.css covers
+   the .dark ancestor scope used everywhere in this app. */
+@import "@remit/ui/tokens.css";
+
+/* Tailwind v4 content scanning: point at the source Tailwind must inspect
+   for utility class usage (auto-detection misses linked workspace packages). */
+@source "../../ui/src/**/*.{ts,tsx}";
+
+/* Hide scrollbars while maintaining scroll functionality */
+.overflow-y-auto {
+  scrollbar-width: none; /* Firefox */
+  -ms-overflow-style: none; /* IE/Edge */
+}
+
+.overflow-y-auto::-webkit-scrollbar {
+  display: none; /* Chrome, Safari, Opera */
+}