@remit/web-client 0.0.94 → 0.0.96

package/src/components/mail/SelectionWizardHost.tsx

@@ -8,6 +8,7 @@ import {
 	deriveSenderClauses,
 	dominantSender,
 	type MatchCount,
+	type MatchDoor,
 	type MatchMode,
 	type MoveMailboxOption,
 	type RuleClause,
@@ -36,15 +37,16 @@ import { useClauseSuggestions } from "@/hooks/useClauseSuggestions";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import {
 	type EscalatedAction,
+	type EscalationSearchQuery,
 	useEscalatedActions,
 } from "@/hooks/useEscalatedActions";
 import { useCreateFilter } from "@/hooks/useFilters";
-import { useMatchSample } from "@/hooks/useMatchSample";
+import { useMatchSample, useSearchMatchSample } from "@/hooks/useMatchSample";
 import { useOrganizeJob } from "@/hooks/useOrganizeJob";
 import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
 import { useRulePreview } from "@/hooks/useRulePreview";
 import { useSelectedSubjects } from "@/hooks/useSelectedSubjects";
-import type { BulkRunOutcome } from "@/lib/bulk-actions";
+import type { BulkActionProgress, BulkRunOutcome } from "@/lib/bulk-actions";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
@@ -87,6 +89,28 @@ interface SelectionWizardSessionProps extends SelectionWizardHostProps {
 	searchConversion?: SearchConversion;
 }
 
+/**
+ * The selection the list escalated to a predicate — every message matching the
+ * query it is showing, rather than the rows on screen (#508). The wizard walks
+ * it exactly as it walks a ticked selection: the same screens, the same review
+ * before anything is sent. What differs is that the match has no member list,
+ * so the count and the sample both come from the server that resolved it.
+ */
+export interface EscalatedSelection {
+	/** What the predicate covers, in the words the list escalated it with. */
+	scope: string;
+	/** The server's count of the whole match, which the run is offered against. */
+	total: number;
+	/** The predicate itself, which the sample and the run both re-resolve. */
+	searchQuery: EscalationSearchQuery;
+	/**
+	 * Runs one verb over the whole predicate, paging it server-side. The chunked
+	 * runner the list already owns: the run screen drives it, and the review
+	 * screen is what now stands in front of it.
+	 */
+	run: (action: EscalatedAction) => Promise<BulkRunOutcome>;
+}
+
 export interface SelectionWizardHostProps {
 	/** What the bar was pressed for. Every verb walks the same wizard. */
 	verb: Verb;
@@ -97,6 +121,16 @@ export interface SelectionWizardHostProps {
 	selection: readonly WizardSelectionMessage[];
 	/** The ticked rows span more than one account, so no rule can be created. */
 	crossAccount?: boolean;
+	/** Present when the selection is a predicate rather than the ticked rows. */
+	escalated?: EscalatedSelection;
+	/**
+	 * How far the escalated runner has got. Read live and passed apart from
+	 * {@link EscalatedSelection}, which the wizard holds for the whole walk: the
+	 * list's escalation returns to idle when a run ends, so a progress reading
+	 * taken off the held predicate would be frozen at `undefined` for every
+	 * retry after the first and the bar would never move.
+	 */
+	escalatedProgress?: BulkActionProgress;
 	/** The wizard is done with the selection, and the list drops it. */
 	onFinished: () => void;
 }
@@ -168,6 +202,26 @@ const bulkActionFor = (
 const widenedRunsAsJob = (verb: Verb): boolean =>
 	verb === "move" || verb === "junk" || verb === "organize";
 
+/**
+ * The commit pressed with nowhere for the mail to go. A verb that files mail
+ * needs a destination, and reaching the run screen without one is a failure the
+ * screen states along with the way out of it — never a control that does
+ * nothing.
+ */
+const noDestinationOutcome = (
+	verb: Verb,
+	ids: readonly string[],
+): BulkRunOutcome => ({
+	done: 0,
+	failedIds: [...ids],
+	cancelled: false,
+	error: new Error(
+		verb === "junk"
+			? "This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings › Folders."
+			: "No destination was chosen, so there is nowhere to file these. Go back and pick a folder.",
+	),
+});
+
 /**
  * Where the wizard meets the app (#483). The steps and their bodies belong to
  * `@remit/ui`; everything that talks to a server is here: the widen, the live
@@ -190,6 +244,8 @@ function SelectionWizardSession({
 	mailboxId,
 	selection,
 	crossAccount = false,
+	escalated: escalatedSelection,
+	escalatedProgress,
 	searchConversion,
 	onFinished,
 	step,
@@ -201,10 +257,20 @@ function SelectionWizardSession({
 	// still settling underneath cannot rewrite the notice a user is reading while
 	// the clauses beside it stay as they were seeded.
 	const [conversion] = useState(() => searchConversion);
+	// The predicate this walk is for, held for the walk. The list's escalation
+	// returns to idle the moment a run ends, and a wizard reading it live would
+	// lose the match its run screen is reporting on — and would offer a retry over
+	// the loaded rows instead of over the predicate.
+	const [escalated] = useState(() => escalatedSelection);
 	const fromSearch = conversion !== undefined;
-	const [mode, setMode] = useState<MatchMode>(
+	// The door the wizard is on. An escalated predicate is not one of them and is
+	// not held here: it is a property of the selection the list handed over, so
+	// the mode below is derived rather than settable. No screen can escalate a
+	// selection, and the commit path can be typed to the doors.
+	const [door, setDoor] = useState<MatchDoor>(
 		fromSearch ? "properties" : "selected",
 	);
+	const mode: MatchMode = escalated ? "escalated" : door;
 	const [draft, setDraft] = useState<WizardDraft>(() =>
 		conversion
 			? {
@@ -243,7 +309,13 @@ function SelectionWizardSession({
 	const subjects = useSelectedSubjects(messageIds);
 	const { junkMailboxId } = useJunkMailbox(accountId);
 
-	const widen = useOrganizeWiden(accountId, anchorMessageId, senders);
+	// No door is offered over an escalated predicate, so nothing here has a widen
+	// to probe for.
+	const widen = useOrganizeWiden(
+		escalated ? undefined : accountId,
+		anchorMessageId,
+		senders,
+	);
 	const { preview: probeWiden } = widen;
 	// The similar door has to know before it is pressed whether it can run, so
 	// the probe fires with the wizard rather than with the door (#477 3.6).
@@ -251,7 +323,10 @@ function SelectionWizardSession({
 		probeWiden();
 	}, [probeWiden]);
 
-	const widened = mode !== "selected";
+	// A door the wizard resolves itself, through the preview endpoint. The
+	// escalated predicate is resolved by the list before the wizard opens, and
+	// the ticked list is its own answer, so neither is previewed.
+	const previewed = mode === "similar" || mode === "properties";
 	const literalPredicate: OrganizeMatchPredicate = useMemo(
 		() => ({
 			matchOperator: draft.matchOperator === "all" ? "And" : "Or",
@@ -268,14 +343,21 @@ function SelectionWizardSession({
 	// in the browser (#477 5.3). The ticked list is its own count, so no request
 	// is made for it.
 	const { count: previewCount, matchedIds } = useRulePreview(
-		widened ? accountId : undefined,
+		previewed ? accountId : undefined,
 		predicate,
 	);
-	const matchSample = useMatchSample(widened ? matchedIds : []);
+	const matchSample = useMatchSample(previewed ? matchedIds : []);
+	// The escalated match's own members, read from the search that resolved it.
+	const escalatedSample = useSearchMatchSample(
+		escalated ? mailboxId : undefined,
+		escalated?.searchQuery,
+	);
 
-	const count: MatchCount = widened
-		? previewCount
-		: { status: "ready", count: selection.length };
+	const count: MatchCount = escalated
+		? { status: "ready", count: escalated.total }
+		: previewed
+			? previewCount
+			: { status: "ready", count: selection.length };
 
 	const { data: mailboxesData } = useQuery({
 		...mailboxOperationsListMailboxesOptions({
@@ -371,8 +453,8 @@ function SelectionWizardSession({
 	);
 
 	const changeMode = useCallback(
-		(next: MatchMode) => {
-			setMode(next);
+		(next: MatchDoor) => {
+			setDoor(next);
 			setDraft((held) => ({
 				...held,
 				widen:
@@ -392,7 +474,7 @@ function SelectionWizardSession({
 	// semantic match without saying so (#477 3.6).
 	const takeSemanticFallback = useCallback(() => {
 		setSemanticFallbackTaken(true);
-		setMode("properties");
+		setDoor("properties");
 		setDraft((held) => ({
 			...held,
 			widen: undefined,
@@ -486,16 +568,7 @@ function SelectionWizardSession({
 			if (!action) {
 				setBulkRun({
 					matched: ids.length,
-					outcome: {
-						done: 0,
-						failedIds: [...ids],
-						cancelled: false,
-						error: new Error(
-							verb === "junk"
-								? "This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings › Folders."
-								: "No destination was chosen, so there is nowhere to file these. Go back and pick a folder.",
-						),
-					},
+					outcome: noDestinationOutcome(verb, ids),
 				});
 				return;
 			}
@@ -506,13 +579,38 @@ function SelectionWizardSession({
 		[verb, named.moveMailboxId, junkMailboxId, runAction],
 	);
 
+	// The escalated predicate, run by the chunked runner the list already owns.
+	// It pages the match on the server rather than acting on ids the browser
+	// loaded, so the verb reaches every message the review screen counted.
+	const runEscalated = useCallback(async () => {
+		if (!escalated) return;
+		const action = bulkActionFor(verb, named.moveMailboxId, junkMailboxId);
+		if (!action) {
+			setBulkRun({
+				matched: escalated.total,
+				outcome: noDestinationOutcome(verb, []),
+			});
+			return;
+		}
+		setBulkRun({ matched: escalated.total });
+		const outcome = await escalated.run(action);
+		setBulkRun({ matched: escalated.total, outcome });
+	}, [escalated, verb, named.moveMailboxId, junkMailboxId]);
+
 	const { start: startJob } = organizeJob;
 	const { createFilterAsync } = createFilter;
 
 	const sendCommit = useCallback(() => {
-		const scope = organizeScopeFor({ mode, ruleScope: named.scope });
+		// An escalated predicate is not a rule and has no scope to reconstruct: it
+		// is the search the list is showing, applied once, by the runner that
+		// resolved it.
+		if (escalated) {
+			void runEscalated();
+			return;
+		}
+		const scope = organizeScopeFor({ mode: door, ruleScope: named.scope });
 		const organizeDraft = buildWizardDraft({
-			mode,
+			mode: door,
 			ruleScope: named.scope,
 			anchorMessageId,
 			clauses: named.clauses,
@@ -547,7 +645,9 @@ function SelectionWizardSession({
 		}
 		void runBulk(scope === "just-these" ? messageIds : matchedIds);
 	}, [
-		mode,
+		escalated,
+		runEscalated,
+		door,
 		named,
 		anchorMessageId,
 		verb,
@@ -596,43 +696,75 @@ function SelectionWizardSession({
 		return NOT_STARTED;
 	}, [organizeJob]);
 
+	// Every row the wizard has seen a description of, so a run that names what it
+	// did not reach can name it rather than listing an id.
 	const rowsById = useMemo(() => {
 		const rows = new Map<string, WizardMessage>();
-		for (const message of [...selection, ...matchSample.messages]) {
+		for (const message of [
+			...selection,
+			...matchSample.messages,
+			...escalatedSample.messages,
+		]) {
 			rows.set(message.id, message);
 		}
 		return rows;
-	}, [selection, matchSample.messages]);
+	}, [selection, matchSample.messages, escalatedSample.messages]);
+
+	const runProgress = escalated ? escalatedProgress : bulk.progress;
 
 	const bulkSnapshot = useCallback((): RunSnapshot => {
 		if (!bulkRun) return NOT_STARTED;
 		const { matched, outcome } = bulkRun;
 		if (!outcome) {
+			const applied = runProgress?.done ?? 0;
+			// A predicate matches more by the time the run re-pages it than the count
+			// saw, so what it has covered can overtake what it was offered against.
+			// The bar never reads more done than out of, and neither does this.
 			return {
 				state: "backApplyRunning",
-				matched,
-				applied: bulk.progress?.done ?? 0,
+				matched: Math.max(matched, applied),
+				applied,
 				failed: 0,
 				failures: [],
 			};
 		}
-		if (outcome.done === 0 && (outcome.error || outcome.failedIds.length > 0)) {
+		const stopped = outcome.cancelled || outcome.error !== undefined;
+		if (!stopped) {
+			return {
+				state: "backApplyComplete",
+				matched: Math.max(matched, outcome.done),
+				applied: outcome.done,
+				failed: 0,
+				failures: [],
+			};
+		}
+		if (outcome.done === 0) {
 			return { ...NOT_STARTED, state: "commitFailed" };
 		}
+		// The run stopped part-way. Nothing here was rejected: a returned bulk call
+		// accepts every id in it, so the only failure this layer sees is a call that
+		// threw, and everything after it was never sent. A bounded run hands back
+		// exactly those ids; a predicate run re-resolves its match on every pass and
+		// has no remainder to hand back, so what is left is the difference between
+		// the count and what the run covered.
 		const failures = outcome.failedIds
 			.map((id) => rowsById.get(id))
 			.filter((message): message is WizardMessage => message !== undefined);
+		const unreached =
+			outcome.failedIds.length > 0
+				? outcome.failedIds.length
+				: Math.max(matched - outcome.done, 1);
 		return {
-			state:
-				outcome.failedIds.length > 0 ? "backApplyFailed" : "backApplyComplete",
-			matched,
+			state: "runStopped",
+			matched: Math.max(matched, outcome.done),
 			applied: outcome.done,
-			failed: outcome.failedIds.length,
+			failed: unreached,
 			failures,
 		};
-	}, [bulkRun, bulk.progress, rowsById]);
+	}, [bulkRun, runProgress, rowsById]);
 
 	const runSnapshot = (): RunSnapshot => {
+		if (escalated) return bulkSnapshot();
 		if (committedScope === "standing" || committedScope === "temporary") {
 			if (createFilter.isError)
 				return { ...NOT_STARTED, state: "commitFailed" };
@@ -653,6 +785,12 @@ function SelectionWizardSession({
 	// walking back to Review, which would push an entry the wizard does not own
 	// and leave Cancel rewinding to a step instead of out.
 	const retry = (): void => {
+		// The predicate is re-resolved, not resumed: every verb it carries is
+		// idempotent, so the messages the first pass already reached are a no-op.
+		if (escalated) {
+			void runEscalated();
+			return;
+		}
 		if (committedScope === "standing" || committedScope === "temporary") {
 			if (createFilter.isError) {
 				createFilter.reset();
@@ -704,15 +842,22 @@ function SelectionWizardSession({
 	});
 
 	const run = runSnapshot();
+	const sampleMessages = escalated
+		? escalatedSample.messages
+		: previewed
+			? matchSample.messages
+			: selection;
 	const sample = {
-		messages: widened ? matchSample.messages : selection,
+		messages: sampleMessages,
 		count,
-		label: widened ? "A sample of what matches" : "Your selection",
+		label: mode === "selected" ? "Your selection" : "A sample of what matches",
 		emptyReason:
 			mode === "similar" && semanticUnavailable
 				? ("notIndexed" as const)
 				: ("noMatch" as const),
-		loading: widened && (count.status === "loading" || matchSample.isPending),
+		loading: escalated
+			? escalatedSample.isPending
+			: previewed && (count.status === "loading" || matchSample.isPending),
 	};
 
 	return (
@@ -735,6 +880,7 @@ function SelectionWizardSession({
 					widen.error instanceof Error ? widen.error.message : undefined,
 				semanticFallbackTaken,
 				onSemanticFallback: takeSemanticFallback,
+				escalatedScope: escalated?.scope,
 				sample,
 			}}
 			properties={{
@@ -786,6 +932,7 @@ function SelectionWizardSession({
 				scope: named.scope,
 				until: named.until,
 				ruleName: steps.includes("name") ? named.name : undefined,
+				escalatedScope: escalated?.scope,
 				sample,
 			}}
 			run={{
@@ -836,6 +983,7 @@ export function SelectionWizardHost(props: SelectionWizardHostProps) {
 						accountId: conversion.targetAccountId ?? accounts[0]?.accountId,
 						selection: EMPTY_SELECTION,
 						crossAccount: false,
+						escalated: undefined,
 						searchConversion: conversion,
 					}
 				: {})}

package/src/components/mail/ThreadListInteraction.test.ts

@@ -9,6 +9,7 @@
  */
 import assert from "node:assert/strict";
 import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { Verb } from "@remit/ui";
 import type { JSDOM } from "jsdom";
 import { act, createElement, createRef, useState } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -68,8 +69,10 @@ const rowElements = (ids: string[]) =>
 function mountList(options: {
 	initialIds: string[];
 	onDeleteMessages?: (ids: string[]) => void;
+	onSelectionVerb?: (verb: Verb) => void;
 }) {
 	const onDeleteMessages = options.onDeleteMessages ?? (() => undefined);
+	const onSelectionVerb = options.onSelectionVerb ?? (() => undefined);
 	const commandsRef = createRef<MessageListCommands | null>();
 	let setIds: ((ids: string[]) => void) | undefined;
 	const Harness = () => {
@@ -81,6 +84,7 @@ function mountList(options: {
 				selectedMessageId: undefined,
 				onOpen: () => undefined,
 				onDeleteMessages,
+				onSelectionVerb,
 				commandsRef,
 			},
 			...rowElements(ids),
@@ -146,6 +150,71 @@ describe("ThreadListInteraction — the cursor follows the rendered rows", () =>
 	});
 });
 
+/**
+ * The provider runs no verb over a selection. Every one of them is handed out
+ * to be opened on the wizard, which is the only place a bulk action is named
+ * before it reaches the mail server (#477 1.4, #508). A verb aimed at the bare
+ * cursor is one message rather than a bulk action, and only Delete is this
+ * list's — it keeps its confirmation.
+ */
+describe("ThreadListInteraction — a verb over a selection goes to the wizard", () => {
+	const selectRow = (
+		list: ReturnType<typeof mountList>,
+		toggleFirst = true,
+	) => {
+		act(() => list.commands().focusFirst());
+		if (toggleFirst) act(() => list.commands().toggleSelect());
+	};
+
+	for (const verb of [
+		"delete",
+		"move",
+		"junk",
+		"markRead",
+		"organize",
+	] as const) {
+		it(`hands ${verb} over rather than running it`, () => {
+			const handed: Verb[] = [];
+			const deleted: string[][] = [];
+			const list = mountList({
+				initialIds: ["m1", "m2"],
+				onDeleteMessages: (ids) => deleted.push(ids),
+				onSelectionVerb: (v) => handed.push(v),
+			});
+
+			selectRow(list);
+			act(() => {
+				assert.equal(list.commands().requestVerb(verb), true);
+			});
+
+			assert.deepEqual(handed, [verb]);
+			assert.deepEqual(deleted, [], "nothing runs from here");
+			assert.equal(
+				Array.from(
+					dom.window.document.querySelectorAll<HTMLButtonElement>("button"),
+				).some((b) => b.textContent === "Move to Trash"),
+				false,
+				"no second confirmation stands in for the review screen",
+			);
+		});
+	}
+
+	it("leaves a verb aimed at the bare cursor to the pane, except delete", () => {
+		const handed: Verb[] = [];
+		const list = mountList({
+			initialIds: ["m1", "m2"],
+			onSelectionVerb: (v) => handed.push(v),
+		});
+
+		act(() => list.commands().focusFirst());
+		act(() => {
+			assert.equal(list.commands().requestVerb("markRead"), false);
+			assert.equal(list.commands().requestVerb("junk"), false);
+		});
+		assert.deepEqual(handed, [], "one row is not a selection");
+	});
+});
+
 describe("ThreadListInteraction — delete confirms first", () => {
 	const confirmButton = () =>
 		Array.from(
@@ -161,7 +230,7 @@ describe("ThreadListInteraction — delete confirms first", () => {
 
 		act(() => list.commands().focusFirst());
 		act(() => {
-			assert.equal(list.commands().requestDelete(), true);
+			assert.equal(list.commands().requestVerb("delete"), true);
 		});
 		assert.deepEqual(deleted, [], "nothing is deleted before confirming");
 		assert.ok(confirmButton(), "the confirmation is on screen");
@@ -179,11 +248,11 @@ describe("ThreadListInteraction — delete confirms first", () => {
 
 		act(() => list.commands().focusFirst());
 		act(() => {
-			list.commands().requestDelete();
+			list.commands().requestVerb("delete");
 		});
 		act(() => {
 			assert.equal(
-				list.commands().requestDelete(),
+				list.commands().requestVerb("delete"),
 				true,
 				"the second press belongs to the dialog",
 			);
@@ -197,7 +266,7 @@ describe("ThreadListInteraction — delete confirms first", () => {
 			onDeleteMessages: () => undefined,
 		});
 		act(() => {
-			assert.equal(list.commands().requestDelete(), false);
+			assert.equal(list.commands().requestVerb("delete"), false);
 		});
 	});
 });
@@ -227,6 +296,7 @@ function mountSelectableList(initialIds: string[]) {
 				selectedMessageId: undefined,
 				onOpen: () => undefined,
 				onDeleteMessages: () => undefined,
+				onSelectionVerb: () => undefined,
 				commandsRef,
 			},
 			...rowElements(ids),