@remit/web-client 0.0.325 → 0.0.327

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

@@ -1,190 +0,0 @@
-/**
- * useOrganizeJob — the back-apply job seam. It reports three failures that are
- * not the same fact (#526, #552): a create that never returned a job id, that
- * same create over a pass that already ran, and a status poll that could not be
- * read over a job the server is already running. Looking at that job again is a
- * separate move from starting one.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { act, createElement } from "react";
-import type { OrganizeDraft } from "../lib/organize/organize-model";
-import { createDomHarness, type DomHarness } from "../test-support/dom";
-import { type HttpMock, mockFetch } from "../test-support/http";
-import { useOrganizeJob } from "./useOrganizeJob";
-
-/**
- * A poll that could not be read reaches this screen only as a transport failure:
- * `shouldEscalate` puts every answered non-2xx on the full-screen fatal page, so
- * a status that is merely unreadable is a `fetch` that never landed.
- */
-const dropped = (): never => {
-	throw new TypeError("fetch failed");
-};
-
-const ACCOUNT = "acc-1";
-const JOB = "job-1";
-
-const DRAFT: OrganizeDraft = {
-	matchOperator: "Or",
-	literalClauses: [{ field: "From", value: "noreply@example.com" }],
-	moveMailboxId: "mbx-1",
-};
-
-let harness: DomHarness | undefined;
-let http: HttpMock | undefined;
-let job: ReturnType<typeof useOrganizeJob> | undefined;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-	http?.restore();
-	http = undefined;
-	job = undefined;
-});
-
-function Probe() {
-	job = useOrganizeJob(ACCOUNT);
-	return null;
-}
-
-const current = (): ReturnType<typeof useOrganizeJob> => {
-	if (!job) throw new Error("useOrganizeJob is not mounted");
-	return job;
-};
-
-// A request round-trip needs a macrotask, not just a drained microtask queue.
-const settle = async (): Promise<void> => {
-	await harness?.wait(1);
-	await harness?.flush();
-};
-
-/** Start a job the server accepts, then answer every status poll with `status`. */
-const startJob = async (status: () => unknown): Promise<void> => {
-	http = mockFetch((call) => {
-		if (call.method === "POST") {
-			return { organizeJobId: JOB, state: "Pending" };
-		}
-		return status();
-	});
-	harness = createDomHarness();
-	harness.renderApp(createElement(Probe));
-	await act(async () => {
-		current().start(DRAFT);
-	});
-	await settle();
-};
-
-const COMPLETED_PASS = {
-	organizeJobId: JOB,
-	state: "Complete",
-	matchedCount: 1284,
-	appliedCount: 1200,
-	failedCount: 84,
-};
-
-/** Run one pass to a finish, then answer the next create with `restart`. */
-const restartAfterPass = async (restart: () => unknown): Promise<void> => {
-	let created = false;
-	http = mockFetch((call) => {
-		if (call.method !== "POST") return COMPLETED_PASS;
-		if (created) return restart();
-		created = true;
-		return { organizeJobId: JOB, state: "Pending" };
-	});
-	harness = createDomHarness();
-	harness.renderApp(createElement(Probe));
-	await act(async () => {
-		current().start(DRAFT);
-	});
-	await settle();
-	assert.equal(current().isDone, true, "the first pass never finished");
-	await act(async () => {
-		current().start(DRAFT);
-	});
-	await settle();
-};
-
-const posts = (): number =>
-	(http?.calls ?? []).filter((call) => call.method === "POST").length;
-
-const statusPolls = (): number => (http?.to(`/organize/${JOB}`) ?? []).length;
-
-describe("useOrganizeJob status reporting", () => {
-	it("reports a status poll it could not read as unreadable, over a job still running", async () => {
-		await startJob(dropped);
-		assert.equal(current().failure?.kind, "statusUnreadable");
-		assert.equal(current().isRunning, true);
-		assert.equal(current().isDone, false);
-	});
-
-	it("reports a create that never returned a job id as a start failure", async () => {
-		http = mockFetch(dropped);
-		harness = createDomHarness();
-		harness.renderApp(createElement(Probe));
-		await act(async () => {
-			current().start(DRAFT);
-		});
-		await settle();
-		assert.equal(current().failure?.kind, "startFailed");
-		assert.equal(current().isRunning, false);
-	});
-
-	it("re-polls the job it already has instead of starting a second one", async () => {
-		let readable = false;
-		await startJob(() =>
-			readable
-				? {
-						organizeJobId: JOB,
-						state: "Running",
-						matchedCount: 1284,
-						appliedCount: 40,
-						failedCount: 0,
-					}
-				: dropped(),
-		);
-		assert.equal(current().failure?.kind, "statusUnreadable");
-		const pollsBefore = statusPolls();
-
-		readable = true;
-		await act(async () => {
-			current().refreshStatus();
-		});
-		await settle();
-
-		assert.equal(posts(), 1);
-		assert.ok(statusPolls() > pollsBefore, "the existing job was polled again");
-		assert.equal(current().failure, undefined);
-		assert.equal(current().progress.matchedCount, 1284);
-	});
-
-	it("reads a create that failed over a finished pass as a restart, with that pass's counts", async () => {
-		await restartAfterPass(dropped);
-		assert.equal(current().failure?.kind, "restartFailed");
-		assert.equal(current().progress.matchedCount, 1284);
-		assert.equal(current().progress.appliedCount, 1200);
-		assert.equal(current().progress.failedCount, 84);
-		assert.equal(current().isDone, true);
-	});
-
-	it("reports a restart that is under way as its own pass, not the one before it", async () => {
-		await restartAfterPass(() => new Promise<never>(() => {}));
-		assert.equal(current().isStarting, true);
-		assert.equal(current().isDone, false);
-		assert.equal(current().failure, undefined);
-		assert.equal(current().progress.matchedCount, 0);
-	});
-
-	it("stops reporting a job as running once it reaches a terminal state", async () => {
-		await startJob(() => ({
-			organizeJobId: JOB,
-			state: "Complete",
-			matchedCount: 1284,
-			appliedCount: 1284,
-			failedCount: 0,
-		}));
-		assert.equal(current().isDone, true);
-		assert.equal(current().failure, undefined);
-	});
-});

package/src/hooks/useOrganizeJob.ts

@@ -1,146 +0,0 @@
-import {
-	organizeJobDetailOperationsGetOrganizeJobOptions,
-	organizeOperationsCreateOrganizeJobMutation,
-} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapOrganizeJobResponse } from "@remit/api-http-client/types.gen.ts";
-import { useMutation, useQuery } from "@tanstack/react-query";
-import { useCallback, useState } from "react";
-import {
-	buildOrganizeInput,
-	buildRunFilterInput,
-	type OrganizeDraft,
-} from "@/lib/organize/organize-model";
-import {
-	isTerminalJobState,
-	nextPollDelayMs,
-} from "@/lib/organize/organize-poll";
-
-export interface OrganizeJobProgress {
-	state: RemitImapOrganizeJobResponse["state"] | undefined;
-	matchedCount: number;
-	appliedCount: number;
-	failedCount: number;
-	errorMessage: string;
-}
-
-/**
- * Why the job is not reporting, which is three separate facts (#526, #552). A
- * create that never returned an id means nothing was started; the same create
- * over a pass that already ran means that pass stands and only the retry never
- * left; a status read that failed means a job is out there and this client
- * cannot see how far it got.
- */
-export interface OrganizeJobFailure {
-	kind: "startFailed" | "restartFailed" | "statusUnreadable";
-	error: unknown;
-}
-
-const organizeJobFailure = (
-	createError: unknown,
-	statusError: unknown,
-	passAlreadyRun: boolean,
-): OrganizeJobFailure | undefined => {
-	if (createError) {
-		return {
-			kind: passAlreadyRun ? "restartFailed" : "startFailed",
-			error: createError,
-		};
-	}
-	if (statusError) return { kind: "statusUnreadable", error: statusError };
-	return undefined;
-};
-
-/**
- * "All like these" — start a one-time retroactive back-apply (POST /organize)
- * and poll its status to completion (GET /organize/{organizeJobId}). Polling
- * backs off exponentially and stops the instant the job reaches a terminal
- * state (Complete / Failed), surfacing matched / applied / failed counts. The
- * back-apply itself scans the corpus server-side; the client only reads a
- * single job row per poll.
- */
-export const useOrganizeJob = (accountId: string | undefined) => {
-	const [organizeJobId, setOrganizeJobId] = useState<string | undefined>();
-
-	const createMutation = useMutation({
-		...organizeOperationsCreateOrganizeJobMutation(),
-		onSuccess: (data) => setOrganizeJobId(data.organizeJobId),
-	});
-	const { mutate: createJob } = createMutation;
-
-	const jobQuery = useQuery({
-		...organizeJobDetailOperationsGetOrganizeJobOptions({
-			path: {
-				accountId: accountId ?? "",
-				organizeJobId: organizeJobId ?? "",
-			},
-		}),
-		enabled: !!accountId && !!organizeJobId,
-		refetchInterval: (query) => {
-			const state = query.state.data?.state;
-			if (isTerminalJobState(state)) return false;
-			return nextPollDelayMs(query.state.dataUpdateCount);
-		},
-	});
-
-	const start = useCallback(
-		(draft: OrganizeDraft) => {
-			if (!accountId) return;
-			createJob({
-				path: { accountId },
-				body: buildOrganizeInput(draft),
-			});
-		},
-		[accountId, createJob],
-	);
-
-	/** Run a saved filter over the inbox, the same pass its create queued. */
-	const startForFilter = useCallback(
-		(filterId: string) => {
-			if (!accountId) return;
-			createJob({
-				path: { accountId },
-				body: buildRunFilterInput(filterId),
-			});
-		},
-		[accountId, createJob],
-	);
-
-	const { refetch } = jobQuery;
-	// Looks at the job already in flight again. Distinct from `start`, which
-	// queues a second pass over the same mail.
-	const refreshStatus = useCallback(() => {
-		void refetch();
-	}, [refetch]);
-
-	// The last pass this client read. A restart replaces it only once the server
-	// hands back a job id: while the create is in flight those counts are not this
-	// pass's, and a create that fails leaves them standing (#552).
-	const lastPass = jobQuery.data;
-	const job = createMutation.isPending ? undefined : lastPass;
-	const state = job?.state ?? createMutation.data?.state;
-	const isDone = isTerminalJobState(job?.state);
-
-	const progress: OrganizeJobProgress = {
-		state,
-		matchedCount: job?.matchedCount ?? 0,
-		appliedCount: job?.appliedCount ?? 0,
-		failedCount: job?.failedCount ?? 0,
-		errorMessage: job?.errorMessage ?? "",
-	};
-
-	return {
-		start,
-		startForFilter,
-		watch: setOrganizeJobId,
-		refreshStatus,
-		progress,
-		isStarting: createMutation.isPending,
-		isRunning: !!organizeJobId && !isDone,
-		isDone,
-		failure: organizeJobFailure(
-			createMutation.error,
-			jobQuery.error,
-			!!lastPass,
-		),
-	};
-};

package/src/hooks/useRailPanels.ts

@@ -1,128 +0,0 @@
-/**
- * The binding between the address, this device's stored preference and what the
- * `/mail` shell has up: pane 4 and the one overlay that may cover it.
- *
- * The rail goes up two ways and they are not the same fact. The reader's own
- * control states where they want the rail from now on, so it writes both the
- * preference and the address. A raise — the DKIM auto-open, the authenticity
- * banner's "Why?" — surfaces the rail for the message in front of them and is
- * held here, in memory, against that message: it never writes the preference,
- * and opening anything else ends it. One message signed by the wrong domain used
- * to mean the rail was up for every later thread and every later session (#778).
- *
- * The raise stays out of the address because its whole copy is computed from the
- * open message — reload the URL and the mismatch raises it again on its own, so
- * putting it in the fragment would be a second owner of a fact the message
- * already holds (`docs/architecture/url-state.md`, R6).
- */
-import { useCallback, useState } from "react";
-import { useLayoutTier } from "@/hooks/useLayoutTier";
-import {
-	readIntelligencePref,
-	resolveRailOpen,
-	writeIntelligencePref,
-} from "@/lib/intelligence-pref";
-import {
-	isOverlayPanel,
-	type OverlayPanel,
-	useOpenPanels,
-	useOpenThreadPath,
-	useSetOpenPanels,
-} from "@/routing";
-
-export interface RailPanels {
-	/** The overlay the address holds: the nav slide-over or the shortcuts sheet. */
-	openOverlay: OverlayPanel | undefined;
-	/** Whether pane 4 is up, by the reader's standing answer or a raise. */
-	intelligenceOpen: boolean;
-	showOverlay: (overlay: OverlayPanel | undefined) => void;
-	/**
-	 * The reader's own control, which is what a stored preference is made of —
-	 * except over a rail only a raise has up, where it ends the raise and stores
-	 * nothing.
-	 */
-	toggleIntelligence: () => void;
-	/** Puts the rail up for the message in front of the reader, and no further. */
-	raiseIntelligence: () => void;
-}
-
-export const useRailPanels = (): RailPanels => {
-	const tier = useLayoutTier();
-	// The panels the address carries (#722): the intelligence rail, the nav
-	// slide-over and the shortcuts sheet. The rail is a pane and the other two
-	// cover it, so the address holds a pane and an overlay at once — a sheet
-	// opening never takes the rail down — while two overlays cannot both be up.
-	const openPanels = useOpenPanels();
-	const setOpenPanels = useSetOpenPanels();
-	const openOverlay = openPanels.find(isOverlayPanel);
-	// Pane 4 on desktop, the details drawer below it. `resolveRailOpen` is the
-	// one place the address and the stored preference meet: the address decides
-	// whenever it says anything at all, and the preference opens the rail with
-	// the thread where it is silent (#782).
-	const openThread = useOpenThreadPath();
-	// Held in state, not read back from storage each render: closing the rail
-	// where the address is silent changes nothing about the address, and the
-	// answer has to move anyway.
-	const [prefersRail, setPrefersRail] = useState(readIntelligencePref);
-	// The message a raise belongs to. Naming it by address is what ends the raise
-	// when the reader opens anything else, without a teardown that has to run.
-	const openMessage = openThread
-		? `${openThread.threadId}/${openThread.messageId ?? ""}`
-		: null;
-	const [raisedFor, setRaisedFor] = useState<string | null>(null);
-	const visibility = {
-		panels: openPanels,
-		prefersOpen: prefersRail,
-		isDesktop: tier === "desktop",
-		hasThread: openThread !== undefined,
-		openMessage,
-	};
-	const intelligenceOpen = resolveRailOpen({ ...visibility, raisedFor });
-	// What the reader themselves have the rail at, which is what an address write
-	// states. A raise is left out of it on purpose: a sheet opening over a
-	// surfaced rail must not write that rail into the address as a choice.
-	const chosenOpen = resolveRailOpen({ ...visibility, raisedFor: null });
-	// Every write states the whole set, because it is composed from what is
-	// showing rather than from what the address happens to spell: the rail open
-	// by preference alone is still open, and an overlay must not close it.
-	const showPanels = useCallback(
-		(rail: boolean, overlay: OverlayPanel | undefined) => {
-			setOpenPanels([
-				...(rail ? (["intelligence"] as const) : []),
-				...(overlay ? [overlay] : []),
-			]);
-		},
-		[setOpenPanels],
-	);
-	const showOverlay = useCallback(
-		(overlay: OverlayPanel | undefined) => {
-			showPanels(chosenOpen, overlay);
-		},
-		[chosenOpen, showPanels],
-	);
-	const toggleIntelligence = useCallback(() => {
-		// Putting away a rail that only a raise has up answers the surfacing, not
-		// the question of where the reader wants the rail — the answer they gave
-		// last stands, and the address never carried this rail to rewrite.
-		if (intelligenceOpen && !chosenOpen) {
-			setRaisedFor(null);
-			return;
-		}
-		const open = !intelligenceOpen;
-		writeIntelligencePref(open);
-		setPrefersRail(open);
-		setRaisedFor(null);
-		showPanels(open, openOverlay);
-	}, [chosenOpen, intelligenceOpen, openOverlay, showPanels]);
-	const raiseIntelligence = useCallback(() => {
-		setRaisedFor(openMessage);
-	}, [openMessage]);
-
-	return {
-		openOverlay,
-		intelligenceOpen,
-		showOverlay,
-		toggleIntelligence,
-		raiseIntelligence,
-	};
-};

package/src/hooks/useRedirectEnded.ts

@@ -1,116 +0,0 @@
-import { useCallback, useEffect, useRef } from "react";
-import { useReturnFromRedirect } from "./useReturnFromRedirect";
-
-/** How the redirect ended: this window came back, or it never left. */
-export type RedirectEnd = "returned" | "stalled";
-
-/**
- * Long enough for a slow provider fetch to take the page away, short enough
- * that a control which is never going anywhere does not read as busy.
- */
-export const REDIRECT_STALL_MS = 20_000;
-
-export const REDIRECT_STALL_MESSAGE =
-	"Couldn't open Microsoft's sign-in page. Check your connection, and anything blocking redirects, then try again.";
-
-/**
- * Run `onEnded` when the window that left for an external identity provider is
- * being looked at again, and hand back the marker to call as it leaves.
- *
- * A control that starts a redirect stays busy until the redirect is over, and
- * neither the mutation settling nor the next look at this window proves that:
- * `window.location.assign` returns with the page still here while the browser
- * fetches the provider's, and an app-switch away and back during that fetch is
- * a look at a window that never left. Installed to a home screen there is no
- * address bar and app-switching is how people move around, so that early look
- * is the common case, not the corner one (#646). The page having actually been
- * hidden is what separates the two.
- *
- * Every return leg, not just the first: a user who came back mid-sign-in to
- * read a password has finished nothing, so the watch stays armed.
- *
- * The listeners are on from mount and `markRedirectStarted` runs synchronously
- * on the line before `assign`, so nothing here depends on a render landing
- * first.
- *
- * A page restored from the back-forward cache — browser Back out of the
- * provider's consent screen — is a return leg on its own evidence. Without it a
- * control that was left busy has nothing to clear it and stays busy for good.
- *
- * An `assign` that never navigates hides nothing and restores nothing, so no
- * return leg is ever coming and the control would read as busy until a reload
- * (#964). A page that has stayed visible for `REDIRECT_STALL_MS` since the
- * redirect started is that case: the watch ends as `"stalled"` so the caller
- * states the failure instead of settling in silence. Only visible time counts —
- * any hide is evidence the redirect did happen, so it stops the watch and
- * leaves the return leg to end it.
- */
-export const useRedirectEnded = (
-	onEnded: (end: RedirectEnd) => void,
-): (() => void) => {
-	const armed = useRef(false);
-	const hidden = useRef(false);
-	const stallTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-	const latest = useRef(onEnded);
-	latest.current = onEnded;
-
-	const stopStallWatch = useCallback((): void => {
-		if (stallTimer.current === null) return;
-		clearTimeout(stallTimer.current);
-		stallTimer.current = null;
-	}, []);
-
-	const settle = useCallback((): void => {
-		if (!armed.current || !hidden.current) return;
-		stopStallWatch();
-		hidden.current = false;
-		latest.current("returned");
-	}, [stopStallWatch]);
-
-	useEffect(() => {
-		const markHidden = () => {
-			hidden.current = true;
-			stopStallWatch();
-		};
-		const handleVisibility = () => {
-			if (document.visibilityState !== "hidden") return;
-			markHidden();
-		};
-		const handlePageShow = (event: PageTransitionEvent) => {
-			if (!event.persisted) return;
-			// A restored page is the whole round trip in one event: the hide that
-			// preceded it belongs to the document this one resumes, and nothing
-			// else is going to report it.
-			markHidden();
-			settle();
-		};
-		document.addEventListener("visibilitychange", handleVisibility);
-		window.addEventListener("pagehide", markHidden);
-		window.addEventListener("pageshow", handlePageShow);
-		return () => {
-			document.removeEventListener("visibilitychange", handleVisibility);
-			window.removeEventListener("pagehide", markHidden);
-			window.removeEventListener("pageshow", handlePageShow);
-			stopStallWatch();
-		};
-	}, [settle, stopStallWatch]);
-
-	// Always listening: the gate is the pair of refs above, which a redirect
-	// arms and a hidden interval satisfies, not whether this hook is mounted
-	// with a flag already flipped.
-	useReturnFromRedirect(true, settle);
-
-	return useCallback(() => {
-		armed.current = true;
-		hidden.current = false;
-		stopStallWatch();
-		stallTimer.current = setTimeout(() => {
-			stallTimer.current = null;
-			// The redirect is over as far as this window is concerned: it decided
-			// nothing, and a later look at a page that never left is not a return.
-			armed.current = false;
-			hidden.current = false;
-			latest.current("stalled");
-		}, REDIRECT_STALL_MS);
-	}, [stopStallWatch]);
-};