@remit/web-client 0.0.324 → 0.0.326

package/src/hooks/useFollowFocusOpen.render.test.ts

@@ -1,145 +0,0 @@
-/**
- * The reading pane following the keyboard cursor.
- *
- * Three properties keep it from being a request per keystroke or a surprise
- * open: a held key coalesces into one load for the row it stops on, following is
- * off while a selection is being built, and a move made while it was off is
- * spent rather than deferred — so turning following back on opens nothing until
- * the cursor moves again.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { createElement } from "react";
-import { createDomHarness, type DomHarness } from "../test-support/dom";
-import { useFollowFocusOpen } from "./useFollowFocusOpen";
-
-let harness: DomHarness | undefined;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-});
-
-const DELAY = 20;
-
-interface ProbeProps {
-	keyboardFocusedMessageId: string | undefined;
-	openMessageId: string | undefined;
-	enabled: boolean;
-	open: (messageId: string) => void;
-	delayMs: number;
-}
-
-function Probe(props: ProbeProps) {
-	useFollowFocusOpen(props);
-	return null;
-}
-
-interface Driver {
-	/** Re-render with a new cursor state, as a keypress would. */
-	move: (props: Partial<ProbeProps>) => void;
-	/** Let the settle timer fire — twice over, so a missed load still shows. */
-	settle: () => Promise<void>;
-	wait: (ms: number) => Promise<void>;
-	opened: string[];
-}
-
-const mount = (initial: Partial<ProbeProps> = {}, delayMs = DELAY): Driver => {
-	const opened: string[] = [];
-	let props: ProbeProps = {
-		keyboardFocusedMessageId: undefined,
-		openMessageId: undefined,
-		enabled: true,
-		open: (messageId) => opened.push(messageId),
-		delayMs,
-		...initial,
-	};
-	const dom = createDomHarness();
-	harness = dom;
-	const paint = () => dom.render(createElement(Probe, props));
-	paint();
-	return {
-		opened,
-		move: (next) => {
-			props = { ...props, ...next };
-			paint();
-		},
-		settle: () => dom.wait(delayMs * 2),
-		wait: (ms) => dom.wait(ms),
-	};
-};
-
-describe("useFollowFocusOpen", () => {
-	it("opens the row the cursor lands on", async () => {
-		const driver = mount();
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		await driver.settle();
-		assert.deepEqual(driver.opened, ["m1"]);
-	});
-
-	it("opens nothing until the cursor has settled", async () => {
-		const driver = mount();
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		assert.deepEqual(driver.opened, []);
-	});
-
-	it("coalesces a held key into one load, for the row it stops on", async () => {
-		const driver = mount();
-		for (const id of ["m1", "m2", "m3", "m4"])
-			driver.move({ keyboardFocusedMessageId: id });
-		await driver.settle();
-		assert.deepEqual(driver.opened, ["m4"]);
-	});
-
-	it("does not re-arm on a re-render that changes only the opener's identity", async () => {
-		// A long delay so the re-render lands mid-flight with room to spare: a
-		// re-arm would push the load out past the total wait below, which is what
-		// permanently defers it while a list re-renders.
-		const driver = mount({}, 100);
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		await driver.wait(60);
-		// A list passes an inline opener, so every render hands in a new function.
-		driver.move({ open: (messageId) => driver.opened.push(messageId) });
-		await driver.wait(60);
-		assert.deepEqual(driver.opened, ["m1"]);
-	});
-
-	it("does not reload the row already in the reading pane", async () => {
-		const driver = mount({ openMessageId: "m1" });
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		await driver.settle();
-		assert.deepEqual(driver.opened, []);
-	});
-
-	it("opens nothing while rows are selected", async () => {
-		const driver = mount({ enabled: false });
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		await driver.settle();
-		assert.deepEqual(driver.opened, []);
-	});
-
-	it("spends the move made while following was off rather than deferring it", async () => {
-		const driver = mount({ enabled: false });
-		driver.move({ keyboardFocusedMessageId: "m1" });
-		await driver.settle();
-
-		// Clearing the selection must not load whatever row the cursor happens to
-		// be sitting on.
-		driver.move({ enabled: true });
-		await driver.settle();
-		assert.deepEqual(driver.opened, []);
-
-		// The next move is a fresh one and does load.
-		driver.move({ keyboardFocusedMessageId: "m2" });
-		await driver.settle();
-		assert.deepEqual(driver.opened, ["m2"]);
-	});
-
-	it("opens nothing when the cursor moved some way other than the keyboard", async () => {
-		const driver = mount();
-		driver.move({ keyboardFocusedMessageId: undefined });
-		await driver.settle();
-		assert.deepEqual(driver.opened, []);
-	});
-});

package/src/hooks/useFollowFocusOpen.ts

@@ -1,81 +0,0 @@
-/**
- * useFollowFocusOpen — the reading pane follows the keyboard cursor.
- *
- * Moving the cursor with j/k or the arrows loads the row it lands on, the way
- * a desktop mail client does. Enter and a plain click keep opening exactly as
- * they did; only a keyboard move drives this, so a click never opens twice and
- * Tab walking into the list opens nothing.
- *
- * Two properties make it safe to run on every cursor move:
- *
- * - The load waits for the cursor to settle. Key repeat delivers a keydown
- *   every few tens of milliseconds, so holding j down costs one request for the
- *   row it stops on rather than one per row it passes.
- * - Nothing here marks anything read. Read state is set by the dwell in
- *   `useMarkAsRead` — three seconds on the open message — which a fly-past
- *   never reaches and a deliberate open reaches unchanged.
- */
-import { useEffect, useRef } from "react";
-
-/**
- * How long the cursor must sit still before its row loads. Comfortably above
- * the ~30ms of a repeating key, so a held key coalesces into a single load,
- * and short enough that a single press reads as immediate.
- */
-export const FOLLOW_FOCUS_DELAY_MS = 120;
-
-interface UseFollowFocusOpenOptions {
-	/**
-	 * The row a keyboard command last moved the cursor onto, and `undefined`
-	 * whenever the cursor last moved some other way — a click, a row taking DOM
-	 * focus, a thread opening, the list reshuffling under a refetch.
-	 */
-	keyboardFocusedMessageId: string | undefined;
-	/** The row already in the reading pane, so an open row does not reload. */
-	openMessageId: string | undefined;
-	/**
-	 * Whether the cursor may open rows at all. Desktop-only: on the single-pane
-	 * tiers the reading pane replaces the list, so following the cursor would
-	 * throw the user off the list they are scanning. Also off while rows are
-	 * selected, where the cursor is building a selection rather than reading.
-	 */
-	enabled: boolean;
-	/** Opens a row in the reading pane. */
-	open: (messageId: string) => void;
-	delayMs?: number;
-}
-
-export const useFollowFocusOpen = ({
-	keyboardFocusedMessageId,
-	openMessageId,
-	enabled,
-	open,
-	delayMs = FOLLOW_FOCUS_DELAY_MS,
-}: UseFollowFocusOpenOptions): void => {
-	// Lists pass an inline opener, so its identity changes every render. Holding
-	// it in a ref keeps a re-render from re-arming — and therefore permanently
-	// deferring — the pending load.
-	const openRef = useRef(open);
-	openRef.current = open;
-
-	// The last cursor move made while following was off. Such a move is spent,
-	// not deferred: clearing a selection must not load whatever row the cursor
-	// happens to be sitting on, only the next move should.
-	const declinedRef = useRef<string | undefined>(undefined);
-
-	useEffect(() => {
-		const messageId = keyboardFocusedMessageId;
-		if (!enabled) {
-			declinedRef.current = messageId;
-			return;
-		}
-		if (messageId === undefined) return;
-		if (messageId === openMessageId) return;
-		if (messageId === declinedRef.current) {
-			declinedRef.current = undefined;
-			return;
-		}
-		const timer = setTimeout(() => openRef.current(messageId), delayMs);
-		return () => clearTimeout(timer);
-	}, [enabled, keyboardFocusedMessageId, openMessageId, delayMs]);
-};

package/src/hooks/useInitialSyncProgress.render.test.ts

@@ -1,314 +0,0 @@
-/**
- * "Still arriving" is a claim about the server, so it is read from the sync
- * phase the IMAP worker writes — never guessed from an empty list. What the
- * tests pin is when the hook is allowed to speak at all: it stays unresolved
- * until every account has answered, an unreachable account counts as answered
- * rather than holding the list in limbo, and a phase it does not recognise is
- * not syncing.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import type {
-	RemitImapAccountSyncStatusResponse,
-	RemitImapSyncPhase,
-} from "@remit/api-http-client/types.gen.ts";
-import { createElement } from "react";
-import { createDomHarness, type DomHarness } from "../test-support/dom";
-import { type HttpMock, httpError, mockFetch } from "../test-support/http";
-import {
-	ANSWER_DEADLINE_MS,
-	type InitialSyncProgress,
-	isSyncingPhase,
-	POLL_MS,
-	useInitialSyncProgress,
-} from "./useInitialSyncProgress";
-
-let harness: DomHarness | undefined;
-let http: HttpMock | undefined;
-let restoreFetch: (() => void) | undefined;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-	http?.restore();
-	http = undefined;
-	restoreFetch?.();
-	restoreFetch = undefined;
-});
-
-interface MailboxProgress {
-	synced: number;
-	total: number;
-}
-
-const status = (
-	accountId: string,
-	syncPhase: RemitImapSyncPhase | undefined,
-	mailboxes: MailboxProgress[] = [],
-): RemitImapAccountSyncStatusResponse => ({
-	accountId,
-	...(syncPhase ? { syncPhase } : {}),
-	mailboxes: mailboxes.map((mailbox, index) => ({
-		mailboxId: `mbx-${accountId}-${index}`,
-		fullPath: index === 0 ? "INBOX" : `Folder ${index}`,
-		phase: "syncing",
-		messagesSynced: mailbox.synced,
-		messagesTotal: mailbox.total,
-		highWaterMarkUid: mailbox.synced,
-	})),
-});
-
-function Probe({
-	accountIds,
-	enabled,
-}: {
-	accountIds: string[];
-	enabled: boolean;
-}) {
-	const progress = useInitialSyncProgress(accountIds, enabled);
-	return createElement("div", null, JSON.stringify(progress));
-}
-
-/** The account id in `/accounts/{id}/sync/status`. */
-const accountOf = (path: string): string => path.split("/")[2] ?? "";
-
-const progress = (dom: DomHarness): InitialSyncProgress =>
-	JSON.parse(dom.text());
-
-const UNKNOWN: InitialSyncProgress = {
-	syncing: false,
-	resolved: false,
-	synced: 0,
-	total: 0,
-};
-
-/** How long the hook gets to answer a request that is already in hand. */
-const RESOLVE_CEILING_MS = 2000;
-/** How long the hook is watched for an answer, or a request, it must not give. */
-const QUIET_WINDOW_MS = 500;
-const STEP_MS = 10;
-
-/**
- * Let real time pass until the hook itself says `done`, or the ceiling runs out.
- *
- * Every wait in this file is a question put to the hook rather than a count of
- * turns or a sleep the answer is assumed to fit inside: the poll and the answer
- * deadline run on real timers, so a loaded machine changes how much work lands
- * per turn, and the ceiling is what keeps a hook that never answers a failure
- * instead of a hang.
- */
-const settleUntil = async (
-	dom: DomHarness,
-	done: () => boolean,
-	ceilingMs: number,
-): Promise<void> => {
-	const deadline = Date.now() + ceilingMs;
-	for (;;) {
-		await dom.flush();
-		if (done() || Date.now() >= deadline) return;
-		await dom.wait(STEP_MS);
-	}
-};
-
-const mount = (
-	accountIds: string[],
-	answer: (accountId: string) => unknown,
-	enabled = true,
-): DomHarness => {
-	http = mockFetch((call) => answer(accountOf(call.path)));
-	harness = createDomHarness();
-	harness.renderApp(createElement(Probe, { accountIds, enabled }));
-	return harness;
-};
-
-const mountResolved = async (
-	accountIds: string[],
-	answer: (accountId: string) => unknown,
-): Promise<DomHarness> => {
-	const dom = mount(accountIds, answer);
-	await settleUntil(dom, () => progress(dom).resolved, RESOLVE_CEILING_MS);
-	return dom;
-};
-
-/** `acc-2` never answers at all: its request is left hanging for good. */
-const mountSilentAccount = (
-	answerOfAccountOne: RemitImapAccountSyncStatusResponse,
-): DomHarness => {
-	const original = globalThis.fetch;
-	restoreFetch = () => {
-		globalThis.fetch = original;
-	};
-	globalThis.fetch = ((input: RequestInfo | URL) => {
-		const url = input instanceof Request ? input.url : String(input);
-		if (url.includes("acc-2")) return new Promise<Response>(() => {});
-		return Promise.resolve(
-			new Response(JSON.stringify(answerOfAccountOne), {
-				status: 200,
-				headers: { "content-type": "application/json" },
-			}),
-		);
-	}) as typeof globalThis.fetch;
-	harness = createDomHarness();
-	harness.renderApp(
-		createElement(Probe, { accountIds: ["acc-1", "acc-2"], enabled: true }),
-	);
-	return harness;
-};
-
-describe("isSyncingPhase", () => {
-	it("is true only for the phases a running sync round writes", () => {
-		assert.equal(isSyncingPhase("discovering_mailboxes"), true);
-		assert.equal(isSyncingPhase("syncing_inbox"), true);
-		assert.equal(isSyncingPhase("syncing_others"), true);
-	});
-
-	it("is false for idle, complete, and error", () => {
-		assert.equal(isSyncingPhase("idle"), false);
-		assert.equal(isSyncingPhase("complete"), false);
-		assert.equal(isSyncingPhase("error"), false);
-	});
-
-	it("is false for an account row written before the phase existed", () => {
-		// "Not complete" would read this as syncing forever.
-		assert.equal(isSyncingPhase(undefined), false);
-	});
-});
-
-describe("useInitialSyncProgress", () => {
-	it("reports syncing with the counts of the accounts still syncing", async () => {
-		const dom = await mountResolved(["acc-1"], (accountId) =>
-			status(accountId, "syncing_inbox", [
-				{ synced: 40, total: 100 },
-				{ synced: 10, total: 60 },
-			]),
-		);
-		assert.deepEqual(progress(dom), {
-			syncing: true,
-			resolved: true,
-			synced: 50,
-			total: 160,
-		});
-	});
-
-	it("leaves out the counts of an account that has finished", async () => {
-		const dom = await mountResolved(["acc-1", "acc-2"], (accountId) =>
-			accountId === "acc-1"
-				? status(accountId, "syncing_inbox", [{ synced: 40, total: 100 }])
-				: status(accountId, "complete", [{ synced: 900, total: 900 }]),
-		);
-		assert.deepEqual(progress(dom), {
-			syncing: true,
-			resolved: true,
-			synced: 40,
-			total: 100,
-		});
-	});
-
-	it("resolves to not-syncing once every account is done", async () => {
-		const dom = await mountResolved(["acc-1", "acc-2"], (accountId) =>
-			status(accountId, "complete", [{ synced: 900, total: 900 }]),
-		);
-		assert.deepEqual(progress(dom), {
-			syncing: false,
-			resolved: true,
-			synced: 0,
-			total: 0,
-		});
-	});
-
-	it("counts an unreachable account as answered rather than holding the list in limbo", async () => {
-		const dom = await mountResolved(["acc-1", "acc-2"], (accountId) =>
-			accountId === "acc-1"
-				? status(accountId, "syncing_inbox", [{ synced: 5, total: 50 }])
-				: httpError(503),
-		);
-		const state = progress(dom);
-		assert.equal(state.resolved, true);
-		assert.equal(state.syncing, true);
-		assert.equal(state.synced, 5);
-	});
-
-	it("knows nothing until every account has answered", async () => {
-		// One account answers, the other never does — the hook must not report on
-		// the half it has.
-		const dom = mountSilentAccount(
-			status("acc-1", "syncing_inbox", [{ synced: 5, total: 50 }]),
-		);
-
-		await settleUntil(dom, () => progress(dom).resolved, QUIET_WINDOW_MS);
-
-		assert.deepEqual(progress(dom), UNKNOWN);
-	});
-
-	it("answers immediately, and never syncing, for no accounts at all", async () => {
-		const dom = await mountResolved([], () => ({}));
-		assert.deepEqual(progress(dom), {
-			syncing: false,
-			resolved: true,
-			synced: 0,
-			total: 0,
-		});
-		assert.deepEqual(http?.calls ?? [], []);
-	});
-
-	it("stops asking once every account has answered and none is syncing", async () => {
-		// The caught-up user's answer cannot change by being asked again.
-		const dom = await mountResolved(["acc-1", "acc-2"], (accountId) =>
-			status(accountId, "complete"),
-		);
-		const asked = http?.calls.length ?? 0;
-		assert.equal(asked, 2);
-
-		await settleUntil(
-			dom,
-			() => (http?.calls.length ?? 0) > asked,
-			POLL_MS + QUIET_WINDOW_MS,
-		);
-
-		assert.equal(http?.calls.length, asked);
-		assert.equal(progress(dom).resolved, true);
-	});
-
-	it("keeps asking while an account is still syncing", async () => {
-		const dom = await mountResolved(["acc-1"], (accountId) =>
-			status(accountId, "syncing_inbox", [{ synced: 5, total: 50 }]),
-		);
-
-		await settleUntil(dom, () => (http?.calls.length ?? 0) > 1, POLL_MS * 3);
-
-		assert.ok(
-			(http?.calls.length ?? 0) > 1,
-			"progress has to keep arriving while the sync runs",
-		);
-	});
-
-	it("answers without an account that never responds", async () => {
-		const dom = mountSilentAccount(status("acc-1", "complete"));
-
-		await settleUntil(dom, () => progress(dom).resolved, QUIET_WINDOW_MS);
-		assert.equal(progress(dom).resolved, false);
-
-		await settleUntil(
-			dom,
-			() => progress(dom).resolved,
-			ANSWER_DEADLINE_MS * 2,
-		);
-
-		assert.deepEqual(progress(dom), {
-			syncing: false,
-			resolved: true,
-			synced: 0,
-			total: 0,
-		});
-	});
-
-	it("asks nothing and claims nothing while disabled", async () => {
-		const dom = mount(["acc-1"], () => status("acc-1", "syncing_inbox"), false);
-
-		await settleUntil(dom, () => progress(dom).resolved, QUIET_WINDOW_MS);
-
-		assert.deepEqual(progress(dom), UNKNOWN);
-		assert.deepEqual(http?.calls ?? [], []);
-	});
-});

package/src/hooks/useInitialSyncProgress.ts

@@ -1,134 +0,0 @@
-import { syncOperationsGetSyncStatusOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapSyncPhase } from "@remit/api-http-client/types.gen.ts";
-import { useQueries } from "@tanstack/react-query";
-import { useEffect, useState } from "react";
-
-/**
- * The phases the server writes while a sync round is actually running.
- *
- * A set of the in-progress values rather than "not complete": an account row
- * written before the phase existed reads back `undefined`, and `idle` means no
- * sync is running. Both would otherwise pin a list to "still syncing" forever,
- * which is the same dishonesty as the bug in the other direction.
- */
-const IN_PROGRESS: ReadonlySet<RemitImapSyncPhase> = new Set([
-	"discovering_mailboxes",
-	"syncing_inbox",
-	"syncing_others",
-]);
-
-/** Whether a phase reading means the server is mid-sync right now. */
-export function isSyncingPhase(phase: RemitImapSyncPhase | undefined): boolean {
-	return !!phase && IN_PROGRESS.has(phase);
-}
-
-export const POLL_MS = 3000;
-
-/**
- * How long an account may stay silent before the answer is given without it.
- *
- * An account that errors counts as answered; one that never responds does not,
- * and without a bound a single hung account holds the brief on its skeleton for
- * as long as the tab is open — it would never say "You're caught up". Two poll
- * rounds is long enough that a slow-but-alive account still gets to speak.
- */
-export const ANSWER_DEADLINE_MS = POLL_MS * 2;
-
-export interface InitialSyncProgress {
-	/** At least one account reports an in-progress sync phase. */
-	syncing: boolean;
-	/** Every enabled sync-status query has answered; until then nothing is known. */
-	resolved: boolean;
-	/** Messages downloaded so far, summed over the accounts still syncing. */
-	synced: number;
-	/** What those accounts hold in total; 0 while the server has not counted. */
-	total: number;
-}
-
-const UNKNOWN: InitialSyncProgress = {
-	syncing: false,
-	resolved: false,
-	synced: 0,
-	total: 0,
-};
-
-/**
- * Whether any of these accounts is mid-sync, read from the account sync-status
- * endpoint (`syncPhase`) — a real server-side state the IMAP worker writes, not
- * a guess from message counts. The per-mailbox message numbers alongside it are
- * approximate by the API's own definition (a UID-range estimate), so they are
- * only ever shown as progress, never as a total the UI reasons about.
- *
- * `enabled` exists because the answer only matters when something is about to
- * be claimed about an empty result; polling every account continuously to
- * answer a question nobody asked is not worth the requests.
- *
- * The poll is a question with a last answer. Once every account has spoken and
- * none is mid-sync, nothing further can change the reading, so the polling
- * stops there rather than re-asking every three seconds for the rest of the
- * session — the caught-up user was paying about 1,200 requests an hour per
- * account for an answer that was already final. A new account set asks again.
- */
-export function useInitialSyncProgress(
-	accountIds: string[],
-	enabled: boolean,
-): InitialSyncProgress {
-	const accountKey = accountIds.join(",");
-	const [settled, setSettled] = useState(false);
-	const [deadlinePassed, setDeadlinePassed] = useState(false);
-
-	// A different account set is a different question: it gets its own answer,
-	// its own deadline, and a poll that runs again until it has one.
-	// biome-ignore lint/correctness/useExhaustiveDependencies: accountKey/enabled are trigger-only — the reset is unconditional, not a value read from either.
-	useEffect(() => {
-		setSettled(false);
-		setDeadlinePassed(false);
-	}, [accountKey, enabled]);
-
-	// biome-ignore lint/correctness/useExhaustiveDependencies: accountKey restarts the deadline for a new question rather than being read inside it.
-	useEffect(() => {
-		if (!enabled) return;
-		const timer = setTimeout(() => setDeadlinePassed(true), ANSWER_DEADLINE_MS);
-		return () => clearTimeout(timer);
-	}, [accountKey, enabled]);
-
-	const queries = useQueries({
-		queries: accountIds.map((accountId) => ({
-			...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
-			// Disabling keeps the cached answer and its success/error status; it
-			// only stops the interval.
-			enabled: enabled && !settled,
-			refetchInterval: POLL_MS,
-			// A failed sync-status read is not the account failing — it must not
-			// raise the global fatal overlay over a question about an empty list.
-			meta: { softError: true },
-		})),
-	});
-
-	// A query that errored still counts as answered: the caller's fallback is the
-	// same either way, and one unreachable account must not hold the whole list
-	// in limbo. One that never answers at all is covered by the deadline instead.
-	const answered = queries.every((q) => q.isSuccess || q.isError);
-	const resolved = queries.length === 0 || answered || deadlinePassed;
-
-	let syncing = false;
-	let synced = 0;
-	let total = 0;
-	for (const query of queries) {
-		if (!isSyncingPhase(query.data?.syncPhase)) continue;
-		syncing = true;
-		for (const mailbox of query.data?.mailboxes ?? []) {
-			synced += mailbox.messagesSynced;
-			total += mailbox.messagesTotal;
-		}
-	}
-
-	const final = enabled && resolved && !syncing;
-	useEffect(() => {
-		if (final) setSettled(true);
-	}, [final]);
-
-	if (!enabled) return UNKNOWN;
-	if (!resolved) return UNKNOWN;
-	return { syncing, resolved: true, synced, total };
-}