@remit/web-client 0.0.271 → 0.0.273

package/src/hooks/useEscalatedActions.ts

@@ -1,4 +1,3 @@
-import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import {
 	messageBulkOperationsDeleteMessages,
 	messageBulkOperationsMoveMessages,
@@ -6,30 +5,22 @@ import {
 	threadOperationsSearchThreads,
 } from "@remit/api-http-client/sdk.gen.ts";
 import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
-import { useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { useRoleAppointmentPrompt } from "@/components/mail/RoleAppointmentPromptProvider";
+import {
+	type BulkRunRequest,
+	type BulkRunSource,
+	useBulkRun,
+} from "@/components/mail/BulkRunProvider";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { buildMutationErrorBanner } from "@/components/ui/error-banners";
-import { isFolderRoleRefusal } from "@/components/ui/folder-role-refusal";
-import {
-	bulkActionFailureDetail,
-	bulkActionFailureTitle,
-} from "@/lib/bulk-action-copy";
-import {
-	type ApplyBatch,
-	type BulkActionProgress,
-	type BulkActionTarget,
-	type BulkRunOutcome,
-	type FetchIdsPage,
-	honestProgress,
-	runChunkedAction,
-	runPredicateAction,
+import type {
+	ApplyBatch,
+	BulkActionProgress,
+	BulkActionTarget,
+	BulkRunStart,
+	EscalatedAction,
+	FetchIdsPage,
 } from "@/lib/bulk-actions";
-import {
-	invalidateThreadListQueries,
-	threadListCacheKeys,
-} from "@/lib/thread-list-cache";
 
 /** The predicate a search-scoped run re-issues on every page — the same
  *  filters the visible list is searching with, minus pagination/count knobs. */
@@ -45,16 +36,6 @@ export type EscalationSearchQuery = Pick<
 	| "category"
 >;
 
-/**
- * What a bulk run applies to every batch it reaches (#114). Delete, move and
- * mark-read differ only in the bulk call they issue and the caches that call
- * invalidates; the paging, chunking, progress and cancellation are the same.
- */
-export type EscalatedAction =
-	| { kind: "delete" }
-	| { kind: "move"; destinationMailboxId: string }
-	| { kind: "markRead" };
-
 /** Page size for the execution loop. Set to the write side's own 100-id cap so
  *  an execution page IS a write chunk — no in-memory accumulation step between
  *  reading ids and sending them. */
@@ -67,6 +48,8 @@ export type EscalationPhase =
 
 interface UseEscalatedActionsOptions {
 	mailboxId: string;
+	/** The mailbox in the user's words, for a commit refused while this runs. */
+	mailboxLabel?: string;
 	/** Owning account, forwarded to the unseen-count invalidation on completion. */
 	accountId?: string;
 	/** Disables escalation entirely (e.g. not searching). Resets any in-flight
@@ -76,6 +59,12 @@ interface UseEscalatedActionsOptions {
 	 *  changes (a different search is a different question). */
 	predicateKey: string;
 	searchQuery: EscalationSearchQuery;
+	/**
+	 * States how a run ended, for a user who is no longer looking at any screen
+	 * that could show it. Handed to the run's owner rather than called here, so
+	 * an ending that lands after this hook unmounted is still said (#112).
+	 */
+	reportEnding?: BulkRunRequest["reportEnding"];
 }
 
 export interface UseEscalatedActionsResult {
@@ -84,11 +73,14 @@ export interface UseEscalatedActionsResult {
 	 *  selection to that predicate once it answers. */
 	escalate: () => void;
 	/**
-	 * Stop whatever's running — the count or an action. The request in flight is
-	 * aborted and nothing further leaves (#113); a delete the server has already
-	 * accepted still applies, so the batch on the wire is what a stop is worth.
-	 * A no-op when nothing is running. The only thing that ends a run in
-	 * flight: leaving the selection, the wizard or the search does not.
+	 * Stop whatever this mailbox has running — its count, and the run when the
+	 * run is its own. The request in flight is aborted and nothing further leaves
+	 * (#113); a delete the server has already accepted still applies, so the
+	 * batch on the wire is what a stop is worth. A no-op when nothing is running.
+	 * Cancelling a count here never reaches a run in another mailbox: that run is
+	 * not what this screen is offering to stop, and ending it would be silent.
+	 * The only thing that ends a run in flight: leaving the selection, the
+	 * wizard, the search or the mailbox does not.
 	 */
 	stop: () => void;
 	/**
@@ -99,7 +91,7 @@ export interface UseEscalatedActionsResult {
 	 */
 	clear: () => void;
 	/** True while a chunked run (bounded->100 ids, or the escalated predicate)
-	 *  is in flight. */
+	 *  over this mailbox is in flight, whichever screen started it. */
 	isRunning: boolean;
 	/** The action currently in flight, for status and progress wording. */
 	runningAction: EscalatedAction | undefined;
@@ -112,61 +104,44 @@ export interface UseEscalatedActionsResult {
 	 * as one batch the endpoint refuses whole (#872). Resolves once the run ends
 	 * for any reason — cancelled, errored, or complete — with a
 	 * `done`/`failedIds` outcome the caller reads to decide what is still
-	 * outstanding.
-	 * Infrastructure failures are reported through the app's existing
-	 * escalation seam (`pushError`, which itself escalates a 5xx/exception to
-	 * the fatal overlay) — not swallowed here.
+	 * outstanding, or with the refusal of a run that never started because
+	 * another one is still going.
+	 *
+	 * The run itself belongs to `BulkRunProvider`, which outlives every screen
+	 * that can show it: the caches, the refusal replay, the failure banner and
+	 * the ending are its, so none of them are lost when the surface that started
+	 * the run goes (#112).
 	 */
 	runAction: (
 		action: EscalatedAction,
 		targets?: readonly BulkActionTarget[],
-	) => Promise<BulkRunOutcome>;
+		claimEnding?: BulkRunRequest["claimEnding"],
+	) => Promise<BulkRunStart>;
 }
 
-/**
- * The mailboxes whose cached listings a bulk run affects: the mailbox it ran
- * over, plus a move's destination, which gains the messages the source loses.
- */
-export const mailboxesTouchedBy = (
-	action: EscalatedAction,
-	mailboxId: string,
-): string[] =>
-	action.kind === "move"
-		? [mailboxId, action.destinationMailboxId]
-		: [mailboxId];
-
 export const useEscalatedActions = ({
 	mailboxId,
+	mailboxLabel,
 	accountId,
 	enabled,
 	predicateKey,
 	searchQuery,
+	reportEnding,
 }: UseEscalatedActionsOptions): UseEscalatedActionsResult => {
 	const [phase, setPhase] = useState<EscalationPhase>({ kind: "idle" });
-	const [runningAction, setRunningAction] = useState<
-		EscalatedAction | undefined
-	>(undefined);
-	const [progress, setProgress] = useState<BulkActionProgress | undefined>(
-		undefined,
-	);
-	// Cancellation is the signal every call the run makes is issued under, so a
-	// stop ends the request on the wire instead of waiting for it to come back
-	// (#113). Replaced, never reused, at the start of each count and each run.
-	const abortRef = useRef<AbortController | undefined>(undefined);
-	// True from the moment a run starts until its outcome is in hand. A run is
-	// mail already leaving the mailbox, so nothing that merely changes what the
-	// list is showing gets to end it — only `stop`.
-	const runningRef = useRef(false);
-	const queryClient = useQueryClient();
+	// The count's own signal, which is not the run's: leaving the search ends a
+	// count, and never a run (#112).
+	const countAbortRef = useRef<AbortController | undefined>(undefined);
+	const { run, start, stop: stopRun } = useBulkRun();
 	const { pushError } = useErrorBanners();
-	const { requestAppointment } = useRoleAppointmentPrompt();
-	// The run replays itself once a folder is appointed, so it needs a handle on
-	// itself that does not make `runAction` its own dependency.
-	const runRef = useRef<UseEscalatedActionsResult["runAction"]>(async () => ({
-		done: 0,
-		failedIds: [],
-		cancelled: false,
-	}));
+
+	// The live run, when it is this mailbox's. A run is mail leaving one mailbox,
+	// so it reports on that mailbox's list — not on whichever list is on screen.
+	const activeRun = run?.mailboxId === mailboxId ? run : undefined;
+	const isRunning = activeRun !== undefined;
+	// Read by callbacks that must not close over a stale render's answer.
+	const isRunningRef = useRef(false);
+	isRunningRef.current = isRunning;
 
 	// A different search (or leaving search/desktop) makes any in-flight
 	// escalation meaningless — it would otherwise keep counting or offering to
@@ -175,7 +150,7 @@ export const useEscalatedActions = ({
 	// against and reports what it reached, wherever the list moved on to.
 	// biome-ignore lint/correctness/useExhaustiveDependencies: enabled/predicateKey are trigger-only — the reset itself reads neither.
 	useEffect(() => {
-		if (!runningRef.current) abortRef.current?.abort();
+		countAbortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, [enabled, predicateKey]);
 
@@ -252,36 +227,9 @@ export const useEscalatedActions = ({
 		[],
 	);
 
-	/**
-	 * The unseen counts a run moved, per account. A cross-account selection has
-	 * no single owning account — the surface leaves the option undefined exactly
-	 * then — so the run's own targets are what name the accounts to refresh.
-	 */
-	const invalidateAfterRun = useCallback(
-		(action: EscalatedAction, targets: readonly BulkActionTarget[]) => {
-			invalidateThreadListQueries(
-				queryClient,
-				threadListCacheKeys(mailboxesTouchedBy(action, mailboxId)),
-			);
-			const touched = new Set<string>();
-			if (accountId) touched.add(accountId);
-			for (const target of targets) {
-				if (target.accountId) touched.add(target.accountId);
-			}
-			for (const touchedAccountId of touched) {
-				queryClient.invalidateQueries({
-					queryKey: mailboxOperationsListMailboxesQueryKey({
-						path: { accountId: touchedAccountId },
-					}),
-				});
-			}
-		},
-		[queryClient, mailboxId, accountId],
-	);
-
 	const escalate = useCallback(() => {
 		const controller = new AbortController();
-		abortRef.current = controller;
+		countAbortRef.current = controller;
 		setPhase({ kind: "counting" });
 		fetchMatchCount(controller.signal).then(
 			(total) => {
@@ -311,12 +259,13 @@ export const useEscalatedActions = ({
 	}, [fetchMatchCount, pushError]);
 
 	const stop = useCallback(() => {
-		abortRef.current?.abort();
-	}, []);
+		countAbortRef.current?.abort();
+		if (isRunningRef.current) stopRun(mailboxId);
+	}, [stopRun, mailboxId]);
 
 	const clear = useCallback(() => {
-		if (runningRef.current) return;
-		abortRef.current?.abort();
+		if (isRunningRef.current) return;
+		countAbortRef.current?.abort();
 		setPhase({ kind: "idle" });
 	}, []);
 
@@ -324,105 +273,62 @@ export const useEscalatedActions = ({
 		async (
 			action: EscalatedAction,
 			targets?: readonly BulkActionTarget[],
-		): Promise<BulkRunOutcome> => {
-			const controller = new AbortController();
-			abortRef.current = controller;
-			runningRef.current = true;
-			setRunningAction(action);
+			claimEnding?: BulkRunRequest["claimEnding"],
+		): Promise<BulkRunStart> => {
 			// Read before the run clears the phase below, so a refusal can say how
 			// many messages the appointment's replay is about.
 			const matched =
 				targets?.length ?? (phase.kind === "escalated" ? phase.total : 0);
-			// `honestProgress` widens `total` if `done` overtakes it (#109) — the
-			// predicate can match more by the time the run pages it than the count
-			// saw, and the bar must never show more done than out of.
-			const onProgress = (next: BulkActionProgress) =>
-				setProgress(honestProgress(next));
-			const applyBatch = applyBatchFor(action);
 			// The predicate as it read when the run was confirmed. The run outlives
 			// the screen that started it, so reading the live query on every page
 			// would let a search typed afterwards redirect what is being deleted.
-			const runPages = fetchPagesOf(searchQueryRef.current);
+			const source: BulkRunSource =
+				targets !== undefined
+					? { kind: "targets", targets }
+					: {
+							kind: "predicate",
+							fetchPage: fetchPagesOf(searchQueryRef.current),
+						};
 
-			// The one invariant nothing may lose: while `runningRef` is up, both
-			// `clear` and the reset effect stand down, so a run that never marked
-			// itself finished would leave an escalated selection nobody can leave.
-			let outcome: BulkRunOutcome;
-			try {
-				outcome =
-					targets !== undefined
-						? await runChunkedAction(
-								targets,
-								applyBatch,
-								onProgress,
-								controller.signal,
-							)
-						: await runPredicateAction(
-								runPages,
-								phase.kind === "escalated" ? phase.total : 0,
-								applyBatch,
-								onProgress,
-								controller.signal,
-							);
-			} finally {
-				runningRef.current = false;
-			}
-
-			setRunningAction(undefined);
-			setProgress(undefined);
-			setPhase({ kind: "idle" });
+			const started = await start({
+				action,
+				mailboxId,
+				mailboxLabel,
+				accountId,
+				matched,
+				source,
+				applyBatch: applyBatchFor(action),
+				reportEnding,
+				claimEnding,
+			});
 
-			// A provenance refusal is answered by the appointment prompt here exactly
-			// as it is on the single-row path (#887, #876). Left to the banner it
-			// arrives as the API's own sentence — "Appoint one under Settings ›
-			// Folder roles" — which asks the user to reassemble a select-all they
-			// have already made.
-			const refusal = outcome.error
-				? isFolderRoleRefusal(outcome.error)
-				: undefined;
-			if (refusal) {
-				requestAppointment({
-					accountId: refusal.accountId,
-					role: refusal.role,
-					reason: refusal.reason,
-					action: { kind: "delete", count: matched },
-					onAppointed: async () => {
-						await runRef.current(action, targets);
-					},
-				});
-			} else if (outcome.error) {
-				pushError(
-					buildMutationErrorBanner(
-						bulkActionFailureTitle(action.kind, outcome.done),
-						bulkActionFailureDetail(action.kind),
-						outcome.error,
-					),
-				);
-			}
-			if (outcome.done > 0) {
-				invalidateAfterRun(action, targets ?? []);
-			}
-			return outcome;
+			// The escalated selection was what the run was confirmed from, and the
+			// run has now happened to it. A refused commit leaves it standing: the
+			// selection is still the question, and stopping the other run is what
+			// makes it answerable.
+			if (started.kind === "ran") setPhase({ kind: "idle" });
+			return started;
 		},
 		[
 			applyBatchFor,
 			fetchPagesOf,
 			phase,
-			pushError,
-			invalidateAfterRun,
-			requestAppointment,
+			mailboxId,
+			mailboxLabel,
+			accountId,
+			reportEnding,
+			start,
 		],
 	);
-	runRef.current = runAction;
 
 	return {
 		phase,
 		escalate,
 		stop,
 		clear,
-		isRunning: runningAction !== undefined,
-		runningAction,
-		progress,
+		isRunning,
+		runningAction: activeRun?.action,
+		progress: activeRun?.progress,
 		runAction,
 	};
 };

package/src/lib/bulk-action-copy.ts

@@ -115,6 +115,27 @@ export const bulkActionFailureTitle = (
 export const bulkActionFailureDetail = (kind: BulkActionKind): string =>
 	failureDetail[kind];
 
+const busyPhrase: Record<BulkActionKind, (count: string) => string> = {
+	delete: (count) => `A delete of ${count} messages`,
+	move: (count) => `A move of ${count} messages`,
+	markRead: (count) => `Marking ${count} messages as read`,
+};
+
+/**
+ * The commit that could not start, because the one still going owns the bar and
+ * the Stop it would need. It names the run in flight and where it is, so the
+ * user knows which screen to end it from rather than pressing a commit that
+ * silently does nothing.
+ */
+export const bulkRunBusyRefusal = (
+	kind: BulkActionKind,
+	matched: number,
+	mailboxLabel: string | undefined,
+): string =>
+	`${busyPhrase[kind](formatNumber(matched))}${
+		mailboxLabel ? ` in ${mailboxLabel}` : ""
+	} is still running — stop it first.`;
+
 /** Progress-bar tone: only delete is destructive. */
 export const bulkActionProgressTone = (
 	kind: BulkActionKind,

package/src/lib/bulk-actions.ts

@@ -34,6 +34,28 @@
 
 export const BULK_ACTION_CHUNK_SIZE = 100;
 
+/**
+ * What a bulk run applies to every batch it reaches (#114). Delete, move and
+ * mark-read differ only in the bulk call they issue and the caches that call
+ * invalidates; the paging, chunking, progress and cancellation are the same.
+ */
+export type EscalatedAction =
+	| { kind: "delete" }
+	| { kind: "move"; destinationMailboxId: string }
+	| { kind: "markRead" };
+
+/**
+ * The mailboxes whose cached listings a bulk run affects: the mailbox it ran
+ * over, plus a move's destination, which gains the messages the source loses.
+ */
+export const mailboxesTouchedBy = (
+	action: EscalatedAction,
+	mailboxId: string,
+): string[] =>
+	action.kind === "move"
+		? [mailboxId, action.destinationMailboxId]
+		: [mailboxId];
+
 /** For a run with no Stop control to wire a signal to. */
 const NEVER_ABORTED = new AbortController().signal;
 
@@ -323,3 +345,13 @@ export interface BulkRunOutcome {
 	cancelled: boolean;
 	error?: unknown;
 }
+
+/**
+ * What asking for a run got: the run itself, or the reason there is none. One
+ * run at a time is the design — a second one would page a second predicate
+ * behind the same bar and the same Stop — so a commit pressed while one is
+ * going is answered with what is going rather than with a run that replaces it.
+ */
+export type BulkRunStart =
+	| { kind: "ran"; outcome: BulkRunOutcome }
+	| { kind: "refused"; reason: string };

package/src/routes/__root.tsx

@@ -7,6 +7,7 @@ import { Suspense } from "react";
 import { useTranslation } from "react-i18next";
 import { ComposeProvider } from "@/components/compose/ComposeProvider";
 import { AppShellSkeleton } from "@/components/layout/AppShellSkeleton";
+import { BulkRunProvider } from "@/components/mail/BulkRunProvider";
 import { RoleAppointmentPromptProvider } from "@/components/mail/RoleAppointmentPromptProvider";
 import { SelfUpdateOverlay } from "@/components/self-update/SelfUpdateOverlay";
 import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
@@ -59,17 +60,21 @@ function RootLayout() {
 	return (
 		<ErrorBannerProvider>
 			<RoleAppointmentPromptProvider>
-				<SelfUpdateProvider>
-					<ComposeProvider>
-						<SkipLink />
-						<main id="main-content" className="h-dvh overflow-hidden">
-							<Suspense fallback={<AppShellSkeleton />}>
-								<Outlet />
-							</Suspense>
-						</main>
-					</ComposeProvider>
-					<SelfUpdateOverlay />
-				</SelfUpdateProvider>
+				{/* A bulk run outlives the route that started it, so its owner sits
+				    above the router rather than inside the list (#112). */}
+				<BulkRunProvider>
+					<SelfUpdateProvider>
+						<ComposeProvider>
+							<SkipLink />
+							<main id="main-content" className="h-dvh overflow-hidden">
+								<Suspense fallback={<AppShellSkeleton />}>
+									<Outlet />
+								</Suspense>
+							</main>
+						</ComposeProvider>
+						<SelfUpdateOverlay />
+					</SelfUpdateProvider>
+				</BulkRunProvider>
 			</RoleAppointmentPromptProvider>
 			<FatalErrorOverlay />
 		</ErrorBannerProvider>

package/src/test-support/bulk-run.ts

@@ -0,0 +1,13 @@
+import type { BulkRunOutcome, BulkRunStart } from "../lib/bulk-actions";
+
+/**
+ * The outcome of a run a test meant to start. A refusal here is the test's own
+ * setup — another run of its making is still going — so it says so rather than
+ * failing on a missing property three assertions later.
+ */
+export const ranOutcome = (started: BulkRunStart): BulkRunOutcome => {
+	if (started.kind === "refused") {
+		throw new Error(`the run was refused: ${started.reason}`);
+	}
+	return started.outcome;
+};

package/src/test-support/dom.ts

@@ -10,6 +10,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { act, createElement } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { DEFAULT_VIEWPORT, setViewport } from "../../test-support/dom-env.mjs";
+import { BulkRunProvider } from "../components/mail/BulkRunProvider";
 import { RoleAppointmentPromptProvider } from "../components/mail/RoleAppointmentPromptProvider";
 import { ErrorBannerProvider } from "../components/ui/ErrorBannerProvider";
 
@@ -113,7 +114,11 @@ export const createDomHarness = (options: DomOptions = {}): DomHarness => {
 					createElement(
 						ErrorBannerProvider,
 						null,
-						createElement(RoleAppointmentPromptProvider, null, element),
+						createElement(
+							RoleAppointmentPromptProvider,
+							null,
+							createElement(BulkRunProvider, null, element),
+						),
 					),
 				),
 			);