@remit/web-client 0.0.94 → 0.0.96

package/src/components/mail/ThreadListInteraction.tsx

@@ -16,7 +16,7 @@
  * are not rendered: focus stops moving, the highlight disappears, and the next
  * verb acts on a message the user cannot see.
  */
-import { SelectionTopBar } from "@remit/ui";
+import { SelectionTopBar, type Verb } from "@remit/ui";
 import {
 	createContext,
 	type ReactNode,
@@ -52,8 +52,12 @@ interface ThreadListInteractionValue {
 	selectedIds: Set<string>;
 	selectedCount: number;
 	exitSelection: () => void;
-	/** Opens the move-to-Trash confirmation for the current selection. */
-	requestDeleteSelection: () => void;
+	/**
+	 * Runs a verb over the current selection by opening the wizard on it — the
+	 * one route every selection action takes, whether the bar or the keyboard
+	 * asked for it.
+	 */
+	startSelectionVerb: (verb: Verb) => void;
 	/** Rendered rows in display order — the same order a shift-range spans. */
 	orderedIds: string[];
 	/** Whether every rendered row is selected, for a select-all control. */
@@ -144,6 +148,15 @@ interface ThreadListInteractionProps {
 	onOpen: (messageId: string, options?: OpenMessageOptions) => void;
 	/** Deletes a set of messages. Absent disables the delete key for this list. */
 	onDeleteMessages: (messageIds: string[]) => void;
+	/**
+	 * Runs a verb over the selection — which means opening the wizard on it, the
+	 * one place a bulk action is reviewed before it reaches the mail server
+	 * (#477 1.4). The provider never runs one itself, so no surface can grow a
+	 * second unreviewed route to the same verb.
+	 */
+	onSelectionVerb: (verb: Verb) => void;
+	/** The wizard owns the screen, so this list's keyboard layer stands down. */
+	wizardOpen?: boolean;
 	isDeleting?: boolean;
 	commandsRef?: RefObject<MessageListCommands | null>;
 	onTriageContextChange?: (context: TriageContextUpdate) => void;
@@ -154,6 +167,8 @@ export function ThreadListInteraction({
 	selectedMessageId,
 	onOpen,
 	onDeleteMessages,
+	onSelectionVerb,
+	wizardOpen = false,
 	isDeleting = false,
 	commandsRef,
 	onTriageContextChange,
@@ -237,36 +252,32 @@ export function ThreadListInteraction({
 		open: followOpen,
 	});
 
-	// Pending move-to-Trash, awaiting confirmation. The ids are snapshotted at
-	// request time so a selection change behind the dialog cannot retarget it —
-	// the same contract the mailbox list's delete has.
+	// Pending move-to-Trash for the row under the cursor, awaiting confirmation.
+	// The id is snapshotted at request time so a cursor move behind the dialog
+	// cannot retarget it. A delete over a selection is a bulk action and walks the
+	// wizard instead — the same contract the mailbox list's delete has.
 	const [pendingDelete, setPendingDelete] = useState<string[] | null>(null);
 
-	const requestDeleteIds = useCallback((ids: string[]): boolean => {
-		if (ids.length === 0) return false;
-		setPendingDelete(ids);
-		return true;
-	}, []);
-
-	const requestDeleteSelection = useCallback(() => {
-		requestDeleteIds(Array.from(selectedIds));
-	}, [requestDeleteIds, selectedIds]);
-
-	const requestDelete = useCallback((): boolean => {
-		// The confirmation is already asking about a delete: the keypress belongs
-		// to it. Claiming the press here is what stops a second Delete from
-		// reaching an unconfirmed delete.
-		if (pendingDelete !== null) return true;
-		if (selectedCount > 0) return requestDeleteIds(Array.from(selectedIds));
-		if (focusedMessageId) return requestDeleteIds([focusedMessageId]);
-		return false;
-	}, [
-		pendingDelete,
-		selectedCount,
-		selectedIds,
-		focusedMessageId,
-		requestDeleteIds,
-	]);
+	// A verb, routed the same way the bar routes its own (#477 1.4, #508). Over a
+	// selection every verb opens the wizard, so the keyboard cannot reach a bulk
+	// action the bar would have reviewed. Over a bare cursor only Delete is this
+	// list's, and it keeps its confirmation.
+	const requestVerb = useCallback(
+		(verb: Verb): boolean => {
+			// The confirmation is already asking about a delete: the keypress belongs
+			// to it. Claiming the press here is what stops a second Delete from
+			// reaching an unconfirmed delete.
+			if (pendingDelete !== null) return true;
+			if (selectedCount > 0) {
+				onSelectionVerb(verb);
+				return true;
+			}
+			if (verb !== "delete" || !focusedMessageId) return false;
+			setPendingDelete([focusedMessageId]);
+			return true;
+		},
+		[pendingDelete, selectedCount, onSelectionVerb, focusedMessageId],
+	);
 
 	const confirmDelete = useCallback(() => {
 		if (pendingDelete === null) return;
@@ -302,7 +313,7 @@ export function ThreadListInteraction({
 			extendSelectUp: cursor.extendRangeUp,
 			selectAll: cursor.selectAllLoaded,
 			clearSelection: clearSelectionCommand,
-			requestDelete,
+			requestVerb,
 			// The brief and Flagged have no density switch; the key stays inert here
 			// rather than moving a control these views do not offer.
 			toggleDensity: () => undefined,
@@ -323,7 +334,7 @@ export function ThreadListInteraction({
 		cursor.selectAllLoaded,
 		openFocused,
 		clearSelectionCommand,
-		requestDelete,
+		requestVerb,
 	]);
 
 	const selectedIdList = useMemo(() => Array.from(selectedIds), [selectedIds]);
@@ -334,9 +345,11 @@ export function ThreadListInteraction({
 			selectedIds: selectedIdList,
 			orderedIds,
 			hasList,
-			// The dialog owns the keyboard while it is up, so the triage layer
-			// suspends rather than acting behind it.
-			blocksKeyboard: confirmOpen,
+			// The dialog and the wizard each own the keyboard while they are up, so
+			// the triage layer suspends rather than acting behind them: a second
+			// Delete must not reach a delete, and no shortcut may start a second flow
+			// behind the screen already asking about one.
+			blocksKeyboard: confirmOpen || wizardOpen,
 		});
 	}, [
 		onTriageContextChange,
@@ -345,6 +358,7 @@ export function ThreadListInteraction({
 		orderedIds,
 		hasList,
 		confirmOpen,
+		wizardOpen,
 	]);
 
 	const tabStop = tabStopId(orderedIds, focusedMessageId);
@@ -354,7 +368,7 @@ export function ThreadListInteraction({
 			selectedIds,
 			selectedCount,
 			exitSelection,
-			requestDeleteSelection,
+			startSelectionVerb: onSelectionVerb,
 			orderedIds,
 			allSelected,
 			toggleAllLoaded,
@@ -376,7 +390,7 @@ export function ThreadListInteraction({
 			selectedIds,
 			selectedCount,
 			exitSelection,
-			requestDeleteSelection,
+			onSelectionVerb,
 			orderedIds,
 			allSelected,
 			toggleAllLoaded,
@@ -416,13 +430,14 @@ export function ThreadListInteraction({
 interface ThreadListSelectionBarProps {
 	/** The view's own name, used until the enclosing header supplies one. */
 	title: string;
-	onMarkAsRead?: (messageIds: string[]) => void;
 	isDeleting?: boolean;
 }
 
 /**
  * The starred list's header, which is also its selection bar — the same
- * surface the mailbox list and the brief raise.
+ * surface the mailbox list and the brief raise, with the same rule: every verb
+ * on it opens the wizard, and the review screen there is what names the action
+ * before it reaches the mail server (#477 1.4).
  *
  * Move is not offered here: starred mail spans accounts and mailboxes, and a
  * move picker needs one account and one source folder to be honest about where
@@ -430,25 +445,18 @@ interface ThreadListSelectionBarProps {
  */
 export function ThreadListSelectionBar({
 	title,
-	onMarkAsRead,
 	isDeleting,
 }: ThreadListSelectionBarProps) {
 	const chrome = useListHeaderChrome();
 	const {
-		selectedIds,
 		selectedCount,
 		exitSelection,
-		requestDeleteSelection,
+		startSelectionVerb,
 		orderedIds,
 		allSelected,
 		toggleAllLoaded,
 	} = useThreadListSelection();
 
-	const handleMarkAsRead = useCallback(() => {
-		onMarkAsRead?.(Array.from(selectedIds));
-		exitSelection();
-	}, [onMarkAsRead, selectedIds, exitSelection]);
-
 	return (
 		<SelectionTopBar
 			title={chrome.title || title}
@@ -459,8 +467,8 @@ export function ThreadListSelectionBar({
 			idleSlot={chrome.makeFilterSlot}
 			count={selectedCount}
 			onCancel={exitSelection}
-			onDelete={requestDeleteSelection}
-			onMarkRead={onMarkAsRead ? handleMarkAsRead : undefined}
+			onDelete={() => startSelectionVerb("delete")}
+			onMarkRead={() => startSelectionVerb("markRead")}
 			isBusy={isDeleting}
 			selectAll={
 				orderedIds.length > 0

package/src/components/mail/selection-verbs.test.ts

@@ -0,0 +1,278 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+/**
+ * One invariant, over every surface: a verb aimed at a selection reaches the
+ * mail server only through the wizard, whose review screen names what it covers
+ * (#477 1.4 and its FAQ, #508).
+ *
+ * There are two ways to ask for one — the selection bar and the keyboard — and
+ * three surfaces that raise a bar. Checked here rather than by a spec per
+ * surface, because what has repeatedly gone wrong is not a broken route but a
+ * missing one: a fourth surface, or a sixth verb, quietly keeping a direct
+ * handler while every other route was moved. That is invisible in review and
+ * indistinguishable from correct until someone selects 3,412 messages and
+ * presses a key.
+ *
+ * These read the source rather than rendering, for the reason
+ * `MessageList.selection.test.ts` gives: these components wire the DOM, the
+ * router and several data hooks together, and the rule is about which function
+ * a prop names.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (file: string): string =>
+	readFileSync(resolve(here, file), "utf8");
+
+/** Every verb the bar can carry — the props `SelectionTopBar` accepts. */
+const BAR_VERB_PROPS = [
+	"onDelete",
+	"onMove",
+	"onOrganize",
+	"onJunk",
+	"onMarkRead",
+] as const;
+
+/**
+ * How a surface is allowed to answer a verb prop. `startWizard`/`wizard.start`/
+ * `startSelectionVerb` all open the wizard on the verb; `organizeSelection` and
+ * `startFromSearch` open it on the search entry, which is the same wizard
+ * reached by its other door (#477 1.8). Anything else is a route around the
+ * review screen.
+ */
+const OPENS_THE_WIZARD =
+	/^(startWizard|wizard\.start|startSelectionVerb|organizeSelection|startFromSearch)\b/;
+
+const surfaceFiles = (): string[] =>
+	readdirSync(here)
+		.filter((file) => file.endsWith(".tsx"))
+		.filter((file) => /<SelectionTopBar/.test(read(file)));
+
+/**
+ * The bar element as written, to its own closing tag. Found by matching tags
+ * rather than by stopping at the first `/>` on a line: a nested self-closing
+ * element matches that too, so the scan would end early and silently skip
+ * whatever a surface happened to write after it.
+ */
+const barMarkup = (source: string): string => {
+	const start = source.indexOf("<SelectionTopBar");
+	if (start === -1) return "";
+	let depth = 0;
+	for (let i = start; i < source.length; i++) {
+		if (source[i] === "<" && /[A-Za-z]/.test(source[i + 1] ?? "")) depth++;
+		else if (source.startsWith("/>", i)) {
+			depth--;
+			if (depth === 0) return source.slice(start, i + 2);
+			i++;
+		} else if (source.startsWith("</", i)) depth--;
+	}
+	return "";
+};
+
+/** The body of `const <name> = useCallback(…)`, or of an inline arrow value. */
+const bracedFrom = (source: string, open: number): string => {
+	let depth = 0;
+	for (let i = open; i < source.length; i++) {
+		if (source[i] === "{") depth++;
+		else if (source[i] === "}") {
+			depth--;
+			if (depth === 0) return source.slice(open, i + 1);
+		}
+	}
+	return source.slice(open);
+};
+
+const namedCallbackBody = (source: string, name: string): string => {
+	const at = source.indexOf(`const ${name} = useCallback(`);
+	if (at === -1) return "";
+	const open = source.indexOf("{", at);
+	return open === -1 ? "" : bracedFrom(source, open);
+};
+
+/** The triage handlers a pane wires into the keyboard layer, by name. */
+const declaredHandlers = (source: string): string[] => {
+	const at = source.indexOf("handlers: {");
+	if (at === -1) return [];
+	return Array.from(
+		bracedFrom(source, source.indexOf("{", at)).matchAll(/\n\t{3}(\w+): /g),
+		(match) => match[1],
+	);
+};
+
+/**
+ * What a pane does for one keyboard verb: the handler it wired into the triage
+ * layer, plus any callback that handler defers to for its target. A handler
+ * that offers the list the press and then falls through to a helper picking the
+ * selection is exactly as wrong as one picking it inline, so both are read.
+ */
+const paneVerbBody = (source: string, handler: string): string => {
+	const at = source.search(new RegExp(`\\n\\t{3}${handler}: `));
+	if (at === -1) return "";
+	const value =
+		source.slice(at).match(new RegExp(`${handler}: (.*)`))?.[1] ?? "";
+	const body = value.startsWith("(")
+		? bracedFrom(source, source.indexOf("{", at))
+		: namedCallbackBody(source, value.replace(/[,\s].*$/, ""));
+	const helpers = Array.from(body.matchAll(/\b(\w+MessageIds)\(\)/g), (match) =>
+		namedCallbackBody(source, match[1]),
+	);
+	return [body, ...helpers].join("\n");
+};
+
+/**
+ * What a verb prop is wired to, with the whitespace, the guard a verb is
+ * offered behind, and the arrow taken off — what is left is the call itself.
+ */
+const verbHandler = (bar: string, prop: string): string | undefined => {
+	const assigned = bar.match(new RegExp(`${prop}=\\{([\\s\\S]*?)\\}\\n`))?.[1];
+	if (assigned === undefined) return undefined;
+	return assigned
+		.replace(/\s+/g, " ")
+		.replace(/^.*? \? /, "")
+		.replace(/ : undefined$/, "")
+		.replace(/^\(\)\s*=>\s*/, "")
+		.trim();
+};
+
+describe("every verb on a selection bar opens the wizard", () => {
+	it("covers the surfaces that raise one", () => {
+		assert.deepEqual(surfaceFiles().sort(), [
+			"DailyBrief.tsx",
+			"MessageList.tsx",
+			"ThreadListInteraction.tsx",
+		]);
+	});
+
+	for (const file of surfaceFiles()) {
+		it(`${file} routes each verb it offers through the wizard`, () => {
+			const bar = barMarkup(read(file));
+			assert.notEqual(bar, "", `${file} renders a SelectionTopBar`);
+			const offered = BAR_VERB_PROPS.filter((prop) => bar.includes(`${prop}=`));
+			assert.ok(offered.length > 0, `${file} offers at least one verb`);
+			for (const prop of offered) {
+				const handler = verbHandler(bar, prop);
+				assert.ok(handler, `${file}'s ${prop} is wired to something`);
+				assert.match(
+					handler,
+					OPENS_THE_WIZARD,
+					`${file}'s ${prop} must open the wizard, not run the verb`,
+				);
+			}
+		});
+	}
+});
+
+/**
+ * The keyboard's half. A list offers the pane one seam — `requestVerb` — and
+ * claims the press whenever it has a selection, so a pane's own handler only
+ * ever sees a verb aimed at the bare cursor. A pane that runs a verb over
+ * `selectedIds` without offering the list the press first is the hole this
+ * binds shut.
+ */
+describe("every keyboard verb over a selection goes through the list", () => {
+	const LISTS = ["MessageList.tsx", "ThreadListInteraction.tsx"];
+	const PANES = ["MailboxPane.tsx", "BriefPane.tsx", "FlaggedPane.tsx"];
+	/**
+	 * The triage handlers that can be aimed at a selection, each with the wizard
+	 * verb it has to route to. Star is a knowing carve-out: it is not one of the
+	 * five verbs the wizard walks, it is not on `SelectionTopBar`, and it sets a
+	 * flag on mail already in front of the user that the same key unsets — so
+	 * there is nothing for a review screen to name. `LabelApplyTrigger` applies
+	 * labels to the selection directly for the same reason, and because labels
+	 * are out of scope for the epic that put the wizard in front of the rest
+	 * (#477 §6). Mute and block are per-sender and reach no selection at all.
+	 */
+	const PANE_VERB_ROUTE: Record<string, string> = {
+		delete: "delete",
+		toggleRead: "markRead",
+		markJunk: "junk",
+	};
+
+	for (const file of LISTS) {
+		it(`${file} publishes the one seam and claims a selection`, () => {
+			const source = read(file);
+			assert.match(source, /requestVerb,/);
+			assert.match(
+				source,
+				/if \(verb !== "delete"/,
+				"only delete is the list's over a bare cursor",
+			);
+			assert.doesNotMatch(
+				source,
+				/requestDelete:/,
+				"one seam, so no verb can have a second one",
+			);
+		});
+
+		it(`${file} stands its keyboard down while the wizard is up`, () => {
+			assert.match(
+				read(file),
+				/blocksKeyboard: confirmOpen \|\| wizard/,
+				"a shortcut must not act behind the screen already asking",
+			);
+		});
+	}
+
+	// Only the handlers a pane really declares get a case, so a pane that never
+	// wired one cannot pass by skipping — the roll-call below is what notices a
+	// handler nobody routed.
+	for (const file of PANES) {
+		for (const handler of declaredHandlers(read(file))) {
+			const verb = PANE_VERB_ROUTE[handler];
+			if (verb === undefined) continue;
+
+			it(`${file}'s ${handler} offers the list ${verb} first`, () => {
+				const body = paneVerbBody(read(file), handler);
+				assert.notEqual(body, "", `${handler}'s body was found`);
+				assert.match(
+					body,
+					new RegExp(`requestVerb\\("${verb}"\\)`),
+					`${handler} must hand ${verb} to the list before running it`,
+				);
+			});
+
+			it(`${file}'s ${handler} aims at the cursor once the list declines`, () => {
+				const body = paneVerbBody(read(file), handler);
+				assert.notEqual(body, "", `${handler}'s body was found`);
+				// The list declines only when its commands are gone, which an
+				// escalated selection outlives — so a fallback that could still see
+				// a selection would run the verb over a stale snapshot of rows that
+				// are no longer loaded, with no wizard in front of it.
+				assert.doesNotMatch(
+					body,
+					/selectedIds/i,
+					`${handler} falls back to the focused row, never to a selection`,
+				);
+			});
+		}
+	}
+
+	it("checks the routed handler on every pane that declares one", () => {
+		// The roll-call. Each pair above is generated from what a pane declares, so
+		// this is what says the generation reached everything it should have — a
+		// handler that stops being declared, or a body the reader stops finding,
+		// shows up here as a missing pair rather than as a case that passed by
+		// doing nothing.
+		const checked = PANES.flatMap((file) =>
+			declaredHandlers(read(file))
+				.filter((handler) => handler in PANE_VERB_ROUTE)
+				.map((handler) => `${file}:${handler}`),
+		);
+		assert.deepEqual(checked.sort(), [
+			"BriefPane.tsx:delete",
+			"BriefPane.tsx:toggleRead",
+			"FlaggedPane.tsx:delete",
+			"FlaggedPane.tsx:toggleRead",
+			"MailboxPane.tsx:delete",
+			"MailboxPane.tsx:markJunk",
+			"MailboxPane.tsx:toggleRead",
+		]);
+		for (const entry of checked) {
+			const [file, handler] = entry.split(":");
+			assert.notEqual(paneVerbBody(read(file), handler), "", entry);
+		}
+	});
+});

package/src/components/ui/ConfirmDialog.stories.tsx

@@ -34,21 +34,6 @@ export const OneMessage: Story = {
 	},
 };
 
-/**
- * An escalated (search-predicate) delete: the count was paged once by
- * `countMatches` and the delete re-pages the same predicate independently, so
- * it is not provably the number that gets deleted (#109). "about" and the
- * description say so up front rather than stating an exact number the run may
- * not honour.
- */
-export const EscalatedEstimate: Story = {
-	args: {
-		title: "Move about 3,412 messages to Trash?",
-		description:
-			"This count is a snapshot — new mail arriving during the delete won't be included. You can restore what's deleted from Trash later.",
-	},
-};
-
 /** The mutation is in flight: the confirm button disables rather than
  *  allowing a second concurrent delete request. */
 export const Busy: Story = {

package/src/hooks/useEscalatedActions.ts

@@ -97,8 +97,8 @@ export interface UseEscalatedActionsResult {
 	 * Runs `action` in chunks. Pass `ids` for a materialized (bounded)
 	 * selection; omit it to run against the escalated predicate (`phase` must
 	 * be "escalated"). Resolves once the run ends for any reason — cancelled,
-	 * errored, or complete — with a `done`/`failedIds` outcome the caller feeds
-	 * to `resolveSelectionAfterRun` to decide what selection looks like next.
+	 * 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.