@remit/web-client 0.0.53 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.53",
+  "version": "0.0.54",
   "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": {
@@ -29,7 +29,7 @@
     "build:dist": "npm run generate:routes && node --import tsx harness/build.mjs",
     "preview": "vite preview",
     "test:typecheck": "npm run generate:routes && tsgo --noEmit",
-    "test:run": "node --import tsx --import ./test-support/register.mjs --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=70 --test 'src/**/*.test.ts'",
+    "test:run": "node --import tsx --import ./test-support/register.mjs --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-exclude='src/test-support/**' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run"
   },
   "peerDependencies": {

package/src/components/mail/MoveToTrigger.render.test.ts

@@ -0,0 +1,153 @@
+/**
+ * The move-to-folder picker. It only fetches folders once it is opened, it
+ * marks the folder the messages are already in rather than offering it as a
+ * destination, and on desktop Escape or a click outside puts it away.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapMailboxResponse } from "@remit/api-http-client/types.gen.ts";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { makeMailbox } from "../../test-support/fixtures";
+import { MoveToTrigger } from "./MoveToTrigger";
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+const ACCOUNT_ID = "acc-1";
+
+const mount = (
+	options: {
+		mailboxes?: RemitImapMailboxResponse[];
+		currentMailboxId?: string;
+		disabledHint?: string;
+		onMove?: (destinationMailboxId: string) => void;
+		viewportWidth?: number;
+	} = {},
+): DomHarness => {
+	harness = createDomHarness({ viewportWidth: options.viewportWidth });
+	if (options.mailboxes) {
+		harness.queryClient.setQueryData(
+			mailboxOperationsListMailboxesQueryKey({
+				path: { accountId: ACCOUNT_ID },
+			}),
+			{ items: options.mailboxes },
+		);
+	}
+	harness.renderApp(
+		createElement(MoveToTrigger, {
+			accountId: ACCOUNT_ID,
+			currentMailboxId: options.currentMailboxId ?? "mbx-inbox",
+			onMove: options.onMove ?? (() => undefined),
+			disabledHint: options.disabledHint,
+		}),
+	);
+	return harness;
+};
+
+const FOLDERS = [
+	makeMailbox({ mailboxId: "mbx-inbox", fullPath: "INBOX" }),
+	makeMailbox({ mailboxId: "mbx-work", fullPath: "Work" }),
+	makeMailbox({ mailboxId: "mbx-receipts", fullPath: "Receipts" }),
+];
+
+describe("MoveToTrigger", () => {
+	it("reports itself as collapsed until it is opened", () => {
+		const dom = mount({ mailboxes: FOLDERS });
+		const trigger = dom.byLabel("Move to folder");
+		assert.equal(trigger.getAttribute("aria-expanded"), "false");
+		assert.equal(trigger.getAttribute("aria-controls"), null);
+		assert.equal(dom.query('[role="listbox"], input'), null);
+	});
+
+	it("opens a listbox of destinations and marks the folder we are in", () => {
+		const dom = mount({ mailboxes: FOLDERS });
+		dom.click(dom.byLabel("Move to folder"));
+
+		assert.equal(
+			dom.byLabel("Move to folder").getAttribute("aria-expanded"),
+			"true",
+		);
+		const labels = dom
+			.queryAll("[role=option]")
+			.map((option) => option.textContent ?? "");
+		assert.ok(labels.some((label) => label.includes("Work")));
+		assert.ok(labels.some((label) => label.includes("Receipts")));
+
+		// The folder the messages are already in stays in the list, marked as
+		// where they are now rather than presented as somewhere to move them.
+		const current = labels.find((label) => label.includes("current"));
+		assert.ok(current, "the source folder is marked as the current one");
+	});
+
+	it("moves to the folder the user picks and closes itself", () => {
+		const moved: string[] = [];
+		const dom = mount({
+			mailboxes: FOLDERS,
+			onMove: (id) => moved.push(id),
+		});
+		dom.click(dom.byLabel("Move to folder"));
+		dom.click(dom.byText("[role=option]", "Work"));
+
+		assert.deepEqual(moved, ["mbx-work"]);
+		assert.equal(
+			dom.byLabel("Move to folder").getAttribute("aria-expanded"),
+			"false",
+		);
+	});
+
+	it("closes on Escape and on a click outside it", () => {
+		const dom = mount({ mailboxes: FOLDERS });
+		const isOpen = () =>
+			dom.byLabel("Move to folder").getAttribute("aria-expanded") === "true";
+
+		dom.click(dom.byLabel("Move to folder"));
+		assert.equal(isOpen(), true);
+		dom.dispatch(
+			dom.window.document,
+			new dom.window.KeyboardEvent("keydown", { key: "Escape" }),
+		);
+		assert.equal(isOpen(), false);
+
+		dom.click(dom.byLabel("Move to folder"));
+		assert.equal(isOpen(), true);
+		dom.dispatch(
+			dom.window.document.body,
+			new dom.window.MouseEvent("mousedown", { bubbles: true }),
+		);
+		assert.equal(isOpen(), false);
+	});
+
+	it("refuses to open, and says why, when the selection spans accounts", () => {
+		const hint = "Select messages from one account to move them";
+		const dom = mount({ mailboxes: FOLDERS, disabledHint: hint });
+		const trigger = dom.byLabel("Move to folder");
+		assert.equal(trigger.getAttribute("title"), hint);
+
+		dom.click(trigger);
+		assert.equal(trigger.getAttribute("aria-expanded"), "false");
+	});
+
+	it("opens a dialog rather than a popover on a phone", () => {
+		const dom = mount({ mailboxes: FOLDERS, viewportWidth: 390 });
+		assert.equal(
+			dom.byLabel("Move to folder").getAttribute("aria-haspopup"),
+			"dialog",
+		);
+	});
+
+	it("asks for the folder list only once the picker is opened", () => {
+		const dom = mount();
+		assert.equal(dom.queryAll("[role=option]").length, 0);
+		dom.click(dom.byLabel("Move to folder"));
+		// No cached mailboxes and no network in the test harness: the picker
+		// shows its loading state rather than an empty list of destinations.
+		assert.match(dom.text(), /Loading folders/);
+	});
+});

package/src/components/mail/SelectionToolbar.render.test.ts

@@ -0,0 +1,145 @@
+/**
+ * The bulk-action bar. Two rules govern it: actions are never disabled (they
+ * no-op and explain — `doc/rules/ux.md`), and Move/Organize only appear when
+ * the selection is inside a single account, because neither works across
+ * accounts.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { SelectionToolbar } from "./SelectionToolbar";
+
+let harness: DomHarness | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+});
+
+type ToolbarProps = Parameters<typeof SelectionToolbar>[0];
+
+const mount = (props: Partial<ToolbarProps> = {}): DomHarness => {
+	harness = createDomHarness();
+	harness.renderApp(
+		createElement(SelectionToolbar, {
+			selectedCount: 2,
+			onDelete: () => undefined,
+			onClearSelection: () => undefined,
+			...props,
+		}),
+	);
+	return harness;
+};
+
+describe("SelectionToolbar", () => {
+	it("renders nothing while nothing is selected", () => {
+		const dom = mount({ selectedCount: 0 });
+		assert.equal(dom.html(), "");
+	});
+
+	it("counts the selection in words the user reads", () => {
+		assert.match(mount({ selectedCount: 1 }).text(), /1 message selected/);
+		harness?.close();
+		harness = undefined;
+		assert.match(mount({ selectedCount: 4 }).text(), /4 messages selected/);
+	});
+
+	it("hides Move until both an account and a source mailbox are known", () => {
+		const dom = mount({ onMove: () => undefined, accountId: "acc-1" });
+		assert.equal(dom.query('[aria-label="Move selected messages"]'), null);
+	});
+
+	it("offers Move and Organize once the selection sits in one account", () => {
+		const dom = mount({
+			onMove: () => undefined,
+			onOrganize: () => undefined,
+			accountId: "acc-1",
+			currentMailboxId: "mbx-inbox",
+		});
+		assert.ok(dom.query('[aria-label="Move selected messages"]'));
+		assert.ok(dom.query('[aria-label="Organize similar messages"]'));
+	});
+
+	it("withdraws Organize and explains why when the selection spans accounts", () => {
+		const dom = mount({
+			onMove: () => undefined,
+			onOrganize: () => undefined,
+			accountId: "acc-1",
+			currentMailboxId: "mbx-inbox",
+			moveDisabledHint: "Select messages from one account to move them",
+		});
+		assert.equal(dom.query('[aria-label="Organize similar messages"]'), null);
+		assert.match(dom.text(), /Select messages from one account to move them/);
+		assert.match(
+			dom.query('[role="status"]')?.textContent ?? "",
+			/one account/,
+		);
+	});
+
+	it("keeps every action pressable while a mutation is in flight (ux.md)", () => {
+		const dom = mount({ isDeleting: true, onMarkAsRead: () => undefined });
+		for (const button of dom.queryAll<HTMLButtonElement>("button")) {
+			assert.equal(button.disabled, false);
+		}
+		assert.equal(
+			dom.byLabel("Delete selected messages").getAttribute("aria-busy"),
+			"true",
+		);
+		assert.match(dom.text(), /Deleting\.\.\./);
+	});
+
+	it("no-ops rather than firing a second time while busy", () => {
+		let deletes = 0;
+		let marks = 0;
+		const dom = mount({
+			isMoving: true,
+			onDelete: () => {
+				deletes += 1;
+			},
+			onMarkAsRead: () => {
+				marks += 1;
+			},
+		});
+		dom.click(dom.byLabel("Delete selected messages"));
+		dom.click(dom.byLabel("Mark as read"));
+		assert.equal(deletes, 0);
+		assert.equal(marks, 0);
+	});
+
+	it("fires delete, mark-read and clear when idle", () => {
+		let cleared = 0;
+		let deletes = 0;
+		let marks = 0;
+		const dom = mount({
+			onDelete: () => {
+				deletes += 1;
+			},
+			onClearSelection: () => {
+				cleared += 1;
+			},
+			onMarkAsRead: () => {
+				marks += 1;
+			},
+		});
+		dom.click(dom.byLabel("Delete selected messages"));
+		dom.click(dom.byLabel("Mark as read"));
+		dom.click(dom.byLabel("Clear selection"));
+		assert.deepEqual([deletes, marks, cleared], [1, 1, 1]);
+	});
+
+	it("opens the organize flow for the current selection", () => {
+		let organized = 0;
+		const dom = mount({
+			onMove: () => undefined,
+			accountId: "acc-1",
+			currentMailboxId: "mbx-inbox",
+			onOrganize: () => {
+				organized += 1;
+			},
+		});
+		dom.click(dom.byLabel("Organize similar messages"));
+		assert.equal(organized, 1);
+	});
+});

package/src/components/onboarding/OnboardingWizard.flow.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Walking the onboarding wizard end to end. The flow is the product here: a
+ * first-run user gets from "welcome" to a syncing account without ever seeing
+ * a server setting they have to know, and when the connection test fails the
+ * wizard sends them back to the step that can fix it — credentials for a
+ * rejected password, servers for an unreachable host.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import { type HttpMock, mockFetch } from "../../test-support/http";
+import { OnboardingWizard } from "./OnboardingWizard";
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+interface TestConnectionResult {
+	imapSuccess: boolean;
+	smtpSuccess: boolean;
+	imapError?: string;
+	smtpError?: string;
+}
+
+const OK: TestConnectionResult = { imapSuccess: true, smtpSuccess: true };
+
+interface Backend {
+	test?: TestConnectionResult;
+	syncPhase?: string;
+	lastError?: string;
+	mailboxCountTotal?: number;
+	mailboxCountSynced?: number;
+}
+
+const completed: string[] = [];
+const cancelled: string[] = [];
+
+const start = (backend: Backend = {}, skipWelcome = false): DomHarness => {
+	http = mockFetch((call) => {
+		if (call.path === "/accounts/test-connection") return backend.test ?? OK;
+		if (call.path === "/accounts") return { accountId: "acc-new" };
+		if (call.path === "/config") {
+			return {
+				accounts: [{ accountId: "acc-new", lastError: backend.lastError }],
+				mailboxes: [],
+			};
+		}
+		if (call.path.endsWith("/sync/status")) {
+			return {
+				accountId: "acc-new",
+				syncPhase: backend.syncPhase ?? "complete",
+				mailboxCountTotal: backend.mailboxCountTotal ?? 4,
+				mailboxCountSynced: backend.mailboxCountSynced ?? 4,
+				mailboxes: [
+					{
+						mailboxId: "mbx-inbox",
+						fullPath: "INBOX",
+						messagesTotal: 120,
+						messagesSynced: 120,
+					},
+				],
+			};
+		}
+		return {};
+	});
+	harness = createDomHarness();
+	harness.renderApp(
+		createElement(OnboardingWizard, {
+			skipWelcome,
+			onComplete: (accountId: string) => completed.push(accountId),
+			onCancel: () => cancelled.push("cancelled"),
+		}),
+	);
+	return harness;
+};
+
+beforeEach(() => {
+	completed.length = 0;
+	cancelled.length = 0;
+});
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+});
+
+/** The wizard's server fields carry generated ids; the placeholder is stable. */
+const imapHostField = (dom: DomHarness): HTMLInputElement => {
+	const input = dom.query<HTMLInputElement>(
+		'input[placeholder="imap.example.com"]',
+	);
+	assert.ok(input, "expected the IMAP host field");
+	return input;
+};
+
+const clickText = (dom: DomHarness, text: string): void => {
+	dom.click(dom.byText("button", text));
+};
+
+/** Welcome → Connector → Address, with an address the provider table knows. */
+const walkToServers = async (
+	dom: DomHarness,
+	email = "alice@fastmail.com",
+): Promise<void> => {
+	clickText(dom, "Add your first account");
+	clickText(dom, "Continue");
+	const emailField = dom.query<HTMLInputElement>("#onboarding-email");
+	assert.ok(emailField);
+	dom.type(emailField, email);
+	clickText(dom, "Continue");
+	await dom.flush();
+};
+
+const walkToTest = async (dom: DomHarness): Promise<void> => {
+	await walkToServers(dom);
+	clickText(dom, "Continue");
+	const password = dom.query<HTMLInputElement>("#credentials-password");
+	assert.ok(password);
+	dom.type(password, "app-password");
+	clickText(dom, "Test connection");
+	await dom.flush();
+	// The test step stages IMAP then SMTP on a short delay before it settles.
+	await dom.wait(500);
+};
+
+/** A verified connection carries on to the sync step on its own, after a beat. */
+const walkToSync = async (dom: DomHarness): Promise<void> => {
+	await walkToTest(dom);
+	await dom.wait(900);
+	// Creation resolves, then the sync-status poll behind it.
+	for (let round = 0; round < 4; round += 1) {
+		await dom.flush();
+		await dom.wait(20);
+	}
+};
+
+describe("OnboardingWizard — the first-run path", () => {
+	it("opens on the welcome step with no server settings in sight", () => {
+		const dom = start();
+		assert.match(dom.text(), /Welcome to Remit/);
+		assert.equal(dom.query("#onboarding-email"), null);
+	});
+
+	it("starts at the connector picker when it is opened from Settings", () => {
+		const dom = start({}, true);
+		assert.match(dom.text(), /How does this account connect/);
+	});
+
+	it("fills the server settings from the address alone", async () => {
+		const dom = start();
+		await walkToServers(dom);
+
+		assert.match(dom.text(), /Confirm server settings/);
+		assert.equal(imapHostField(dom).value, "imap.fastmail.com");
+	});
+
+	it("falls back to a guess for a domain nobody has heard of", async () => {
+		const dom = start();
+		await walkToServers(dom, "alice@unheard-of.example");
+
+		assert.equal(imapHostField(dom).value, "imap.unheard-of.example");
+	});
+
+	it("refuses an address that is not one, without leaving the step", async () => {
+		const dom = start();
+		clickText(dom, "Add your first account");
+		clickText(dom, "Continue");
+		const emailField = dom.query<HTMLInputElement>("#onboarding-email");
+		assert.ok(emailField);
+		dom.type(emailField, "not-an-address");
+		clickText(dom, "Continue");
+		await dom.flush();
+
+		assert.match(dom.text(), /Enter a valid email address/);
+		assert.ok(dom.query("#onboarding-email"));
+	});
+
+	it("tests the connection with what the user entered", async () => {
+		const dom = start();
+		await walkToTest(dom);
+
+		const [tested] = http.to("/accounts/test-connection");
+		assert.ok(tested);
+		assert.equal(tested.body?.imapHost, "imap.fastmail.com");
+		assert.equal(tested.body?.password, "app-password");
+		assert.equal(tested.body?.username, "alice@fastmail.com");
+		assert.match(dom.text(), /Connection verified/);
+	});
+
+	it("creates the account from what the wizard collected", async () => {
+		const dom = start();
+		await walkToSync(dom);
+
+		const [created] = http.calls.filter(
+			(call) => call.path === "/accounts" && call.method === "POST",
+		);
+		assert.ok(created, "a verified connection carries on to creation");
+		assert.equal(created.body?.email, "alice@fastmail.com");
+		assert.equal(created.body?.imapHost, "imap.fastmail.com");
+		assert.equal(created.body?.password, "app-password");
+	});
+
+	it("reports sync progress and hands the new account to the caller", async () => {
+		const dom = start();
+		await walkToSync(dom);
+
+		assert.match(dom.text(), /INBOX/);
+		assert.match(dom.text(), /4 mailboxes found/);
+		clickText(dom, "Go to inbox");
+		assert.deepEqual(completed, ["acc-new"]);
+	});
+});
+
+describe("OnboardingWizard — a connection that does not work", () => {
+	it("sends a rejected password back to credentials, not to servers", async () => {
+		const dom = start({
+			test: {
+				imapSuccess: false,
+				smtpSuccess: false,
+				imapError: "Authentication failed",
+			},
+		});
+		await walkToTest(dom);
+
+		assert.match(dom.text(), /Authentication failed/);
+		assert.match(dom.text(), /app password/i);
+		clickText(dom, "Back to credentials");
+		assert.ok(dom.query("#credentials-password"));
+	});
+
+	it("sends an unreachable host back to servers", async () => {
+		const dom = start({
+			test: {
+				imapSuccess: false,
+				smtpSuccess: false,
+				imapError: "ECONNREFUSED",
+			},
+		});
+		await walkToTest(dom);
+
+		assert.match(dom.text(), /ECONNREFUSED/);
+		clickText(dom, "Back to servers");
+		assert.equal(imapHostField(dom).value, "imap.fastmail.com");
+	});
+
+	it("offers a retry that runs the test again rather than a dead end", async () => {
+		const dom = start({
+			test: {
+				imapSuccess: false,
+				smtpSuccess: false,
+				imapError: "ECONNREFUSED",
+			},
+		});
+		await walkToTest(dom);
+
+		const before = http.to("/accounts/test-connection").length;
+		clickText(dom, "Retry");
+		await dom.flush();
+		assert.equal(http.to("/accounts/test-connection").length, before + 1);
+	});
+
+	it("never reaches account creation while the connection is broken", async () => {
+		const dom = start({
+			test: { imapSuccess: false, smtpSuccess: false, imapError: "no route" },
+		});
+		await walkToTest(dom);
+		await dom.wait(50);
+
+		assert.deepEqual(
+			http.calls.filter(
+				(call) => call.path === "/accounts" && call.method === "POST",
+			),
+			[],
+		);
+	});
+});
+
+describe("OnboardingWizard — a sync that stalls", () => {
+	it("says the account is still there and offers a retry", async () => {
+		const dom = start({
+			syncPhase: "error",
+			lastError: "IMAP LOGIN failed",
+		});
+		await walkToSync(dom);
+
+		assert.match(dom.text(), /Sync stalled/);
+		assert.match(dom.text(), /still active/);
+		assert.match(dom.text(), /IMAP LOGIN failed/);
+	});
+});