@remit/web-client 0.0.200 → 0.0.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.200",
+  "version": "0.0.202",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/SelectionWizardHost.search-entry.test.ts

@@ -1,41 +1,82 @@
-import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { describe, it } from "node:test";
-import { fileURLToPath } from "node:url";
-
 /**
  * A filter made from a search belongs to the account the search ran over (#524).
- * The surface hands its account to the host on the props; a search entry that
- * reads past it writes the rule against whichever account happens to be first in
- * the list, and the mail the user was looking at is never filtered.
  *
- * Which account wins is decided — and tested — in
- * `../../lib/organize/search-to-rule.test.ts`. What is read off the source here
- * is that the host asks that question with the surface's account in hand, which
- * is the wiring the bug lived in and which no unit of the resolver can prove.
- * The host wires routing, history and several data hooks together, so it is read
- * rather than rendered, as this package's other component-level rules are (see
- * `SelectionWizardHost.run-exit.test.ts`).
+ * The surface hands its account to the host on the props; a search entry that
+ * reaches past it writes the rule against whichever account happens to be first
+ * in the list, and the mail the user was looking at is never filtered. Which
+ * account wins between the query and the surface is
+ * `../../lib/organize/search-to-rule.test.ts`; what is asserted here is the set
+ * of props a search entry replaces, the account among them.
  */
 
-const here = dirname(fileURLToPath(import.meta.url));
-const source = readFileSync(resolve(here, "SelectionWizardHost.tsx"), "utf8");
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { SearchConversion } from "@remit/ui";
+import { searchEntryOverrides } from "./SelectionWizardHost";
+
+const conversion = (
+	over: Partial<SearchConversion> = {},
+): SearchConversion => ({
+	clauses: [],
+	matchOperator: "all",
+	droppedFacets: [],
+	keptTerms: false,
+	droppedSemantic: false,
+	...over,
+});
+
+const accounts = [{ accountId: "acc-first" }, { accountId: "acc-surface" }];
+
+describe("the account a search entry writes its rule against", () => {
+	it("is the one the surface handed over", () => {
+		assert.equal(
+			searchEntryOverrides(conversion(), { accountId: "acc-surface" }, accounts)
+				.accountId,
+			"acc-surface",
+		);
+	});
 
-const host = source.match(
-	/export function SelectionWizardHost\(([\s\S]*)$/,
-)?.[1];
+	it("is the one the query names when it names one", () => {
+		assert.equal(
+			searchEntryOverrides(
+				conversion({ targetAccountId: "acc-typed" }),
+				{ accountId: "acc-surface" },
+				accounts,
+			).accountId,
+			"acc-typed",
+		);
+	});
+
+	// The first configured account is the last resort, never the answer while the
+	// surface has one of its own.
+	it("falls back to the first configured account only when the surface has none", () => {
+		assert.equal(
+			searchEntryOverrides(conversion(), { accountId: undefined }, accounts)
+				.accountId,
+			"acc-first",
+		);
+	});
+});
 
-describe("the search entry's account", () => {
-	it("is resolved with the account the surface handed over", () => {
-		assert.ok(host, "the host is gone");
-		const call = host.match(/searchRuleAccountId\(([\s\S]*?)\)/)?.[1];
-		assert.ok(call, "the search entry resolves no account of its own");
-		assert.match(call, /\bprops\.accountId\b/);
+describe("what else a search entry replaces", () => {
+	it("ticks nothing, carries no restriction and drops any escalation", () => {
+		const overrides = searchEntryOverrides(
+			conversion(),
+			{ accountId: "acc-surface" },
+			accounts,
+		);
+		assert.equal(overrides.verb, "organize");
+		assert.deepEqual(overrides.selection, []);
+		assert.equal(overrides.selectionRestriction, undefined);
+		assert.equal(overrides.escalated, undefined);
 	});
 
-	it("never reaches past it for the first configured account", () => {
-		assert.ok(host, "the host is gone");
-		assert.doesNotMatch(host, /accounts\[0\]/);
+	it("hands the conversion on so the properties step can seed its clauses", () => {
+		const seeded = conversion({ keptTerms: true });
+		assert.equal(
+			searchEntryOverrides(seeded, { accountId: "acc-surface" }, accounts)
+				.searchConversion,
+			seeded,
+		);
 	});
 });

package/src/components/mail/SelectionWizardHost.tsx

@@ -1,4 +1,5 @@
 import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
 import {
 	type ClauseDraft,
 	type ClauseEditState,
@@ -72,6 +73,12 @@ import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
 import { useWizardEntryValue, useWizardStep } from "@/lib/wizard-history";
 import type { WizardSelectionMessage } from "@/lib/wizard-selection";
 import { organizeRunState } from "./organize-run-state";
+import {
+	retryIntent,
+	runIsInFlight,
+	stopRunner,
+	wizardExit,
+} from "./selection-wizard-run-controls";
 
 const EMPTY_DRAFT: WizardDraft = { clauses: [], matchOperator: "any" };
 
@@ -171,6 +178,34 @@ const NO_CONVERSION: SearchConversion = {
 /** A search entry has nothing ticked; its match is the query's clauses (#477 3.2). */
 const EMPTY_SELECTION: readonly WizardSelectionMessage[] = [];
 
+/**
+ * What a search entry overrides on the props the surface handed over. Its rule
+ * belongs to the account the surface named, and to the one the query names when
+ * it names one (#524) — reaching past both for the first configured account
+ * writes the rule against whichever account happens to be first in the list, and
+ * the mail the user was looking at is never filtered.
+ */
+export const searchEntryOverrides = (
+	conversion: SearchConversion,
+	props: Pick<SelectionWizardHostProps, "accountId">,
+	accounts: readonly Pick<RemitImapAccountResponse, "accountId">[],
+): Pick<
+	SelectionWizardSessionProps,
+	| "verb"
+	| "accountId"
+	| "selection"
+	| "selectionRestriction"
+	| "escalated"
+	| "searchConversion"
+> => ({
+	verb: "organize",
+	accountId: searchRuleAccountId(conversion, props.accountId, accounts),
+	selection: EMPTY_SELECTION,
+	selectionRestriction: undefined,
+	escalated: undefined,
+	searchConversion: conversion,
+});
+
 /** How far a commit has got, whichever of the three ways it took. */
 interface RunSnapshot {
 	state: RunState;
@@ -851,42 +886,39 @@ 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 => {
-		// A status that could not be read is a job still running on the server, so
-		// the screen looks at that job again rather than queuing a second pass over
-		// the same mail (#526).
-		if (run.state === "statusUnknown") {
-			organizeJob.refreshStatus();
-			return;
-		}
-		// 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) {
+		const intent = retryIntent({
+			runState: run.state,
+			isEscalated: escalated !== undefined,
+			committedScope,
+			createFilterFailed: createFilter.isError,
+			backApplyPending: backApplyDraft !== undefined,
+			widenRunsAsJob: widenedRunsAsJob(verb),
+			failedIds: bulkRun?.outcome?.failedIds ?? [],
+			sent: bulkRun?.sent ?? bulkTargets,
+		});
+		switch (intent.kind) {
+			case "refreshStatus":
+				organizeJob.refreshStatus();
+				return;
+			case "rerunEscalated":
+				void runEscalated();
+				return;
+			case "resetAndResend":
 				createFilter.reset();
 				sendCommit();
 				return;
-			}
-			if (backApplyDraft) startJob(backApplyDraft);
-			return;
-		}
-		if (committedScope === "all-like-these" && widenedRunsAsJob(verb)) {
-			sendCommit();
-			return;
+			case "resend":
+				sendCommit();
+				return;
+			case "startBackApply":
+				if (backApplyDraft) startJob(backApplyDraft);
+				return;
+			case "waitOnJob":
+				return;
+			case "rerunBulk":
+				void runBulk(intent.targets);
+				return;
 		}
-		const outstanding = new Set(bulkRun?.outcome?.failedIds ?? []);
-		// A run hands back ids, and each one's account came from the batch it was
-		// sent in — so a retry re-sends the targets the run was given, filtered to
-		// what it never reached.
-		const sent = bulkRun?.sent ?? bulkTargets;
-		void runBulk(
-			outstanding.size > 0
-				? sent.filter((target) => outstanding.has(target.id))
-				: sent,
-		);
 	};
 
 	// Cancel rewinds the entries the wizard owns and leaves the selection where
@@ -905,21 +937,9 @@ function SelectionWizardSession({
 		onFinished();
 	}, [closeWizard, steps, current, onFinished]);
 
-	// Ends the run rather than leaving it. The escalated predicate is run by the
-	// list's runner and a bounded selection by this wizard's own, so the stop
-	// follows whichever one is paging.
 	const { stop: stopBulk } = bulk;
-	// A commit that never started has nothing paging and nothing to end.
-	const runInFlight =
-		bulkRun !== undefined &&
-		bulkRun.outcome === undefined &&
-		bulkRun.failureReason === undefined;
 	const stopRun = useCallback(() => {
-		if (escalated) {
-			escalated.stop();
-			return;
-		}
-		stopBulk();
+		stopRunner(escalated, stopBulk);
 	}, [escalated, stopBulk]);
 
 	// Hardware back on the run screen leaves the wizard, the movement the header
@@ -971,7 +991,7 @@ function SelectionWizardSession({
 			// Every exit from the run screen is the same movement: the header's X,
 			// the header arrow, the footer and hardware Back all leave a run that
 			// has already been sent, and all of them drop the selection with it.
-			onExit={current === "run" ? dismiss : cancel}
+			onExit={wizardExit(current, { dismiss, cancel })}
 			onContinue={advance}
 			onCommit={commit}
 			match={{
@@ -1051,7 +1071,7 @@ function SelectionWizardSession({
 				failureReason: run.failureReason,
 				onRetry: retry,
 				onDismiss: dismiss,
-				onCancelRun: runInFlight ? stopRun : undefined,
+				onCancelRun: runIsInFlight(bulkRun) ? stopRun : undefined,
 			}}
 		/>
 	);
@@ -1084,20 +1104,7 @@ export function SelectionWizardHost(props: SelectionWizardHostProps) {
 	return (
 		<SelectionWizardSession
 			{...props}
-			{...(conversion
-				? {
-						verb: "organize" as const,
-						accountId: searchRuleAccountId(
-							conversion,
-							props.accountId,
-							accounts,
-						),
-						selection: EMPTY_SELECTION,
-						selectionRestriction: undefined,
-						escalated: undefined,
-						searchConversion: conversion,
-					}
-				: {})}
+			{...(conversion ? searchEntryOverrides(conversion, props, accounts) : {})}
 			step={step}
 			goToStep={goToStep}
 			goBack={goBack}

package/src/components/mail/selection-surface-rollcall.test.ts

@@ -0,0 +1,270 @@
+/**
+ * The roll-call no run can take: which surfaces exist, and which function each
+ * one's verbs name.
+ *
+ * Everything a selection surface *does* — the review screen naming what a verb
+ * covers, a run reaching the mail server — is driven end to end by
+ * `packages/e2e`. What no run observes is a surface that was never wired: a
+ * fourth pane growing its own direct handler while every other route was moved,
+ * a fourth list rendering the make-filter row with no wizard behind it, or a
+ * verb on a bar nobody presses in a spec quietly keeping a direct call. The
+ * suite has locators for Delete, Move and Organize and none for Junk or
+ * Mark-read, so three of the five are reachable only from here.
+ *
+ * So this reads the source, and reads it for the census: who raises a bar, what
+ * each of its verbs is wired to, who declares a keyboard verb over a selection,
+ * who renders the make-filter row. Every census is discovered from the
+ * directory rather than listed, so a fourth surface is a failure here until it
+ * is wired like the other three.
+ */
+
+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";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (file: string): string =>
+	readFileSync(resolve(here, file), "utf8");
+
+const sourceFiles = (): string[] =>
+	readdirSync(here).filter((file) => file.endsWith(".tsx"));
+
+const BAR_VERB_PROPS = [
+	"onDelete",
+	"onMove",
+	"onOrganize",
+	"onJunk",
+	"onMarkRead",
+] as const;
+
+/**
+ * How a surface may answer a verb prop. `startWizard`/`wizard.start`/
+ * `startSelectionVerb` 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 routes around the review
+ * screen that names what the verb covers (#477 1.4).
+ */
+const OPENS_THE_WIZARD =
+	/^(startWizard|wizard\.start|startSelectionVerb|organizeSelection|startFromSearch)\b/;
+
+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 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 "";
+};
+
+/**
+ * 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();
+};
+
+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");
+};
+
+describe("the surfaces that raise a selection bar", () => {
+	const surfaces = (): string[] =>
+		sourceFiles()
+			.filter((file) => /<SelectionTopBar/.test(read(file)))
+			.sort();
+
+	it("are these three and no others", () => {
+		assert.deepEqual(surfaces(), [
+			"DailyBrief.tsx",
+			"MessageList.tsx",
+			"ThreadListInteraction.tsx",
+		]);
+	});
+
+	for (const file of surfaces()) {
+		it(`${file} routes every 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`,
+				);
+			}
+		});
+	}
+
+	for (const file of ["DailyBrief.tsx", "MessageList.tsx"]) {
+		it(`${file} drops none of the five verbs from the bar it raises`, () => {
+			const bar = barMarkup(read(file));
+			for (const prop of BAR_VERB_PROPS) {
+				assert.match(bar, new RegExp(`${prop}=`), `${file} offers ${prop}`);
+			}
+		});
+	}
+});
+
+// A pane that runs a verb over `selectedIds` without offering the list the
+// press first is the hole no run can see: the pane's fallback and the list's
+// claim are indistinguishable from outside until a selection outlives the
+// list's commands. That the list claims the press is rendered in
+// `./ThreadListInteraction.test.ts`.
+describe("the panes that answer a keyboard verb over a selection", () => {
+	const PANE_VERB_ROUTE: Record<string, string> = {
+		delete: "delete",
+		toggleRead: "markRead",
+		markJunk: "junk",
+	};
+
+	const panes = (): string[] =>
+		sourceFiles()
+			.filter((file) => read(file).includes("handlers: {"))
+			.sort();
+
+	const routed = (): string[] =>
+		panes()
+			.flatMap((file) =>
+				declaredHandlers(read(file))
+					.filter((handler) => handler in PANE_VERB_ROUTE)
+					.map((handler) => `${file}:${handler}`),
+			)
+			.sort();
+
+	it("are these three panes and no others", () => {
+		assert.deepEqual(panes(), [
+			"BriefPane.tsx",
+			"FlaggedPane.tsx",
+			"MailboxPane.tsx",
+		]);
+	});
+
+	it("declare these seven routed handlers and no others", () => {
+		assert.deepEqual(routed(), [
+			"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 routed()) {
+		const [file, handler] = entry.split(":");
+		const verb = PANE_VERB_ROUTE[handler];
+
+		it(`${entry} offers the list ${verb} before running anything`, () => {
+			const body = paneVerbBody(read(file), handler);
+			assert.notEqual(body, "", `${handler}'s body was found`);
+			assert.match(body, new RegExp(`requestVerb\\("${verb}"\\)`));
+		});
+
+		it(`${entry} falls back to the focused row, never to a selection`, () => {
+			const body = paneVerbBody(read(file), handler);
+			assert.notEqual(body, "", `${handler}'s body was found`);
+			assert.doesNotMatch(body, /selectedIds/i);
+		});
+	}
+});
+
+// The row is built once by `MailListHeader` and handed down as `makeFilterSlot`,
+// but the wizard answering the step it pushes is mounted per surface. A surface
+// that renders the row without one leaves the press on a URL nothing answers.
+describe("the surfaces that render the make-filter row", () => {
+	const ANSWERED_BY: Record<string, string> = {
+		"DailyBrief.tsx": "DailyBrief.tsx",
+		"MessageList.tsx": "MessageList.tsx",
+		"ThreadListInteraction.tsx": "FlaggedList.tsx",
+	};
+
+	it("are these three and no others", () => {
+		assert.deepEqual(
+			sourceFiles()
+				.filter((file) => /\.makeFilterSlot/.test(read(file)))
+				.sort(),
+			Object.keys(ANSWERED_BY).sort(),
+		);
+	});
+
+	it("each name a file that mounts a wizard to answer the step", () => {
+		for (const [surface, host] of Object.entries(ANSWERED_BY)) {
+			assert.match(
+				read(host),
+				/<SelectionWizardHost/,
+				`${surface} is answered by ${host}`,
+			);
+		}
+	});
+});