@remit/web-client 0.0.41 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "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/DailyBrief.tsx

@@ -31,6 +31,7 @@ import {
 	type FilterSheetProps,
 	type FilterSheetSource,
 	KeyboardHintBar,
+	LIST_ROW_ATTRIBUTE,
 	type SearchResult,
 	type ThreadRowData,
 	type ThreadSection,
@@ -140,6 +141,7 @@ const BriefRow = ({
 	return (
 		<button
 			type="button"
+			{...LIST_ROW_ATTRIBUTE}
 			onClick={onClick}
 			className={cn("group w-full", comfortableRowClass({ active }))}
 		>

package/src/components/mail/FlaggedList.tsx

@@ -16,10 +16,12 @@
 import {
 	ComfortableRow,
 	flaggedFilterConfig,
+	LIST_ROW_SELECTOR,
 	MessageListPane,
 	type ThreadRowData,
+	useRovingFocus,
 } from "@remit/ui";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { formatErrorMessage } from "@/components/ui/ErrorState";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
 import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
@@ -54,6 +56,9 @@ export function FlaggedList({
 	const tokenContext = useSearchTokenContext();
 	const isDesktop = useIsDesktop();
 
+	const listRef = useRef<HTMLDivElement>(null);
+	useRovingFocus({ containerRef: listRef, itemSelector: LIST_ROW_SELECTOR });
+
 	const [selectedCategory, setSelectedCategory] = useState("all");
 	const [activeFilters, setActiveFilters] = useState<ReadonlySet<string>>(
 		new Set(),
@@ -130,7 +135,7 @@ export function FlaggedList({
 	}, []);
 
 	const listBody = (
-		<div className="flex-1 overflow-y-auto">
+		<div ref={listRef} className="flex-1 overflow-y-auto">
 			<div className="divide-y divide-line">
 				{rows.map((thread) => (
 					<ComfortableRow

package/src/components/mail/MessageList.selection.test.ts

@@ -0,0 +1,52 @@
+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";
+
+/**
+ * Selection mode has one source of truth and one exit (#115). `MessageList`
+ * wires the DOM, the virtualizer, routing and several data hooks together, so
+ * — as with this package's other component-level rules (see
+ * `../../index.css.test.ts`) — the rule is enforced by reading the source
+ * rather than rendering the tree. The decisions themselves are unit-tested in
+ * `../../lib/selection-mode.test.ts`.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, "MessageList.tsx"), "utf8");
+
+describe("MessageList selection mode", () => {
+	it("keeps no selection-mode flag of its own", () => {
+		assert.doesNotMatch(source, /useState[^\n]*[iI]sMultiSelectMode/);
+		assert.doesNotMatch(source, /setIsMultiSelectMode/);
+	});
+
+	it("derives the mode from the selection count", () => {
+		assert.match(
+			source,
+			/const isMultiSelectMode = deriveIsMultiSelectMode\(\s*selectedCount,/,
+		);
+	});
+
+	it("calls the selection hook's clearSelection from exactly one place", () => {
+		const calls = source.match(/\bclearSelection\(\)/g) ?? [];
+		assert.equal(calls.length, 1);
+		assert.match(
+			source,
+			/const exitSelection = useCallback\(\(\) => \{[^}]*clearSelection\(\);/,
+		);
+	});
+
+	it("exits selection when the mailbox changes", () => {
+		assert.match(source, /previousMailboxIdRef\.current === mailboxId/);
+	});
+
+	it("turns the back gesture into an exit, and only while selecting", () => {
+		assert.match(
+			source,
+			/shouldExitSelectionOnNavigate\(action, hasSelection\)/,
+		);
+		assert.match(source, /disabled: !hasSelection/);
+	});
+});

package/src/components/mail/MessageList.tsx

@@ -5,7 +5,7 @@ import {
 	MessageListPane,
 	SelectionTopBar,
 } from "@remit/ui";
-import { useNavigate } from "@tanstack/react-router";
+import { useBlocker, useNavigate } from "@tanstack/react-router";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { Search, Sparkles } from "lucide-react";
 import type { RefObject } from "react";
@@ -34,6 +34,10 @@ import {
 } from "@/lib/escalation-label";
 import { formatDeleteToTrashTitle, formatNumber } from "@/lib/format";
 import { tabStopId } from "@/lib/list-focus";
+import {
+	deriveIsMultiSelectMode,
+	shouldExitSelectionOnNavigate,
+} from "@/lib/selection-mode";
 import { cn } from "@/lib/utils";
 import { MoveToTrigger } from "./MoveToTrigger";
 import { OrganizeDialog } from "./organize/OrganizeDialog";
@@ -200,7 +204,6 @@ export const MessageList = ({
 	const parentRef = useRef<HTMLDivElement>(null);
 	const navigate = useNavigate();
 	const isDesktop = useIsDesktop();
-	const [isMultiSelectMode, setIsMultiSelectMode] = useState(false);
 	const [organizeOpen, setOrganizeOpen] = useState(false);
 	const isSearching = !!searchQuery?.trim();
 
@@ -247,6 +250,11 @@ export const MessageList = ({
 		intersectWith,
 	} = useSelection();
 
+	// The selection count is the only source of truth for whether the list is
+	// in multi-select mode (#115). A separate flag needs an effect to reconcile
+	// it back to the count, and across that render the two disagree.
+	const isMultiSelectMode = deriveIsMultiSelectMode(selectedCount, isDesktop);
+
 	// Pending delete, awaiting confirmation. `null` means the dialog is closed.
 	// `source: "ids"` snapshots the concrete ids at request time so a selection
 	// change behind the dialog can't retarget the delete — every keyboard/desktop
@@ -274,6 +282,18 @@ export const MessageList = ({
 		predicateKey,
 		searchQuery: searchPredicate ?? {},
 	});
+
+	// The one way selection mode ends (#115): cancel, a completed delete or
+	// move, a plain click that collapses a range, switching mailboxes, the back
+	// gesture. Nothing calls the selection hook's `clearSelection` directly, so
+	// an escalated selection can never survive the exit as a stale phase.
+	const escalationPhaseKind = escalation.phase.kind;
+	const clearEscalation = escalation.clear;
+	const exitSelection = useCallback(() => {
+		if (escalationPhaseKind === "escalated") clearEscalation();
+		clearSelection();
+	}, [clearSelection, clearEscalation, escalationPhaseKind]);
+
 	// Non-null exactly once a bounded/escalated run just ended with some ids
 	// still not confirmed deleted: the count that DID succeed in that run, so
 	// the partial-failure notice can say "N moved to Trash" alongside "Retry".
@@ -316,13 +336,6 @@ export const MessageList = ({
 	const commandsAvailable = !isLoading && threads.length > 0;
 	const confirmOpen = pendingDelete !== null;
 
-	// Auto-exit multi-select when selection becomes empty
-	useEffect(() => {
-		if (isMultiSelectMode && selectedCount === 0) {
-			setIsMultiSelectMode(false);
-		}
-	}, [isMultiSelectMode, selectedCount]);
-
 	// Single choke point for what selection looks like once a chunked/escalated
 	// run ends, for any reason (issue #92 requirement 10). A clean run with
 	// nothing left over exits selection mode and hands off to a transient
@@ -338,7 +351,7 @@ export const MessageList = ({
 					`${formatNumber(outcome.done)} moved to Trash. Your mail server is still catching up.`,
 				);
 				setLastRunSucceeded(null);
-				clearSelection();
+				exitSelection();
 				return;
 			}
 			if (retryIds.length > 0) {
@@ -348,7 +361,7 @@ export const MessageList = ({
 			}
 			setLastRunSucceeded(null);
 		},
-		[clearSelection, selectAll],
+		[exitSelection, selectAll],
 	);
 
 	const virtualizer = useVirtualizer({
@@ -437,7 +450,7 @@ export const MessageList = ({
 			// Plain click: collapse any multi-selection and let navigation proceed.
 			// The clicked row becomes the next anchor for a subsequent shift-click,
 			// but is NOT added to the checkbox set (no toolbar on a plain open).
-			clearSelection();
+			exitSelection();
 			setAnchor(messageId);
 			return false;
 		},
@@ -446,7 +459,7 @@ export const MessageList = ({
 			focusedMessageId,
 			selectRange,
 			toggleCheck,
-			clearSelection,
+			exitSelection,
 			setAnchor,
 		],
 	);
@@ -611,7 +624,7 @@ export const MessageList = ({
 		}
 
 		onDeleteMessages?.(ids);
-		clearSelection();
+		exitSelection();
 		focusBeforeConfirmRef.current = null;
 		setPendingDelete(null);
 
@@ -632,7 +645,7 @@ export const MessageList = ({
 		pendingDelete,
 		threads,
 		onDeleteMessages,
-		clearSelection,
+		exitSelection,
 		navigate,
 		mailboxId,
 		runChunkedConfirmDelete,
@@ -664,9 +677,9 @@ export const MessageList = ({
 		(destinationMailboxId: string) => {
 			if (!onMoveMessages || selectedCount === 0) return;
 			onMoveMessages(Array.from(selectedIds), destinationMailboxId);
-			clearSelection();
+			exitSelection();
 		},
-		[onMoveMessages, selectedCount, selectedIds, clearSelection],
+		[onMoveMessages, selectedCount, selectedIds, exitSelection],
 	);
 
 	// Cross-account guard: every selected thread row must belong to the
@@ -708,23 +721,17 @@ export const MessageList = ({
 		[toggleReadFor],
 	);
 
-	// Mobile: Enter multi-select mode on long press
+	// Mobile: a long press enters multi-select mode by starting a selection —
+	// the mode follows from the count, there is no flag to set.
 	const handleLongPress = useCallback(
 		(messageId: string) => {
 			if (!isDesktop) {
-				setIsMultiSelectMode(true);
 				select(messageId);
 			}
 		},
 		[isDesktop, select],
 	);
 
-	// Cancel multi-select mode
-	const handleCancelMultiSelect = useCallback(() => {
-		setIsMultiSelectMode(false);
-		clearSelection();
-	}, [clearSelection]);
-
 	// Mobile bar's Trash tap: an escalated selection has no materialized ids to
 	// hand `requestDelete`, so it opens the predicate confirmation instead.
 	const handleMobileDelete = useCallback(() => {
@@ -745,11 +752,8 @@ export const MessageList = ({
 			escalation.stop();
 			return;
 		}
-		if (escalation.phase.kind === "escalated") {
-			escalation.clear();
-		}
-		handleCancelMultiSelect();
-	}, [escalation, handleCancelMultiSelect]);
+		exitSelection();
+	}, [escalation, exitSelection]);
 
 	// The escalation notice's "Clear selection" action: drop back to the
 	// bounded (all-loaded) selection without touching selection mode itself.
@@ -861,6 +865,30 @@ export const MessageList = ({
 		intersectWith(threads.map((t) => t.messageId));
 	}, [threads, intersectWith, escalation.phase, escalation.isDeleting]);
 
+	// Switching mailboxes exits selection outright, instead of leaving it to the
+	// intersect effect above to empty the set by coincidence — a different
+	// mailbox's threads happen to share none of the old ids.
+	const previousMailboxIdRef = useRef(mailboxId);
+	useEffect(() => {
+		if (previousMailboxIdRef.current === mailboxId) return;
+		previousMailboxIdRef.current = mailboxId;
+		exitSelection();
+	}, [mailboxId, exitSelection]);
+
+	// The back gesture (Android's back button, the browser's back) leaves
+	// selection mode rather than the route. Only `BACK` is intercepted, so a
+	// navigation the app itself starts — opening a message, switching mailboxes
+	// — is never blocked, and the blocker is off entirely with nothing selected.
+	useBlocker({
+		shouldBlockFn: ({ action }) => {
+			if (!shouldExitSelectionOnNavigate(action, hasSelection)) return false;
+			exitSelection();
+			return true;
+		},
+		enableBeforeUnload: false,
+		disabled: !hasSelection,
+	});
+
 	// Load more when scrolling near the bottom
 	useEffect(() => {
 		const scrollElement = parentRef.current;
@@ -918,7 +946,7 @@ export const MessageList = ({
 			selectAll: handleSelectAll,
 			clearSelection: () => {
 				if (!hasSelection) return false;
-				clearSelection();
+				exitSelection();
 				return true;
 			},
 			requestDelete: handleDeleteKey,
@@ -940,7 +968,7 @@ export const MessageList = ({
 		extendRangeUp,
 		handleSelectAll,
 		hasSelection,
-		clearSelection,
+		exitSelection,
 		handleDeleteKey,
 		toggleDensity,
 	]);
@@ -972,7 +1000,7 @@ export const MessageList = ({
 			<SelectionToolbar
 				selectedCount={selectedCount}
 				onDelete={handleDelete}
-				onClearSelection={clearSelection}
+				onClearSelection={exitSelection}
 				onMarkAsRead={onMarkAsRead ? handleMarkAsRead : undefined}
 				onMove={onMoveMessages ? handleMoveSelected : undefined}
 				onOrganize={() => setOrganizeOpen(true)}

package/src/components/mail/OutboxPane.tsx

@@ -22,7 +22,12 @@ import type {
 	RemitImapOutboxMessageResponse,
 	RemitImapOutboxMessageStatus,
 } from "@remit/api-http-client/types.gen.ts";
-import { OutboxRow, ReadingPaneEmpty } from "@remit/ui";
+import {
+	LIST_ROW_SELECTOR,
+	OutboxRow,
+	ReadingPaneEmpty,
+	useRovingFocus,
+} from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useSearch } from "@tanstack/react-router";
 import {
@@ -40,6 +45,7 @@ import {
 	useCallback,
 	useContext,
 	useMemo,
+	useRef,
 } from "react";
 import { useCompose } from "@/components/compose/ComposeProvider";
 import { MessageBody } from "@/components/mail/MessageBody";
@@ -434,6 +440,8 @@ function OutboxList() {
 		selectedMessageId,
 		onSelectMessage,
 	} = useOutboxPane();
+	const listRef = useRef<HTMLDivElement>(null);
+	useRovingFocus({ containerRef: listRef, itemSelector: LIST_ROW_SELECTOR });
 
 	if (isLoading) {
 		return (
@@ -468,7 +476,7 @@ function OutboxList() {
 					{messages.length} {messages.length === 1 ? "message" : "messages"}
 				</span>
 			</header>
-			<div className="flex-1 overflow-y-auto">
+			<div ref={listRef} className="flex-1 overflow-y-auto">
 				{messages.map((message) => (
 					<OutboxMessageRow
 						key={message.outboxMessageId}
@@ -523,6 +531,8 @@ function OutboxPhone() {
 		selectedMessage,
 		onSelectMessage,
 	} = useOutboxPane();
+	const listRef = useRef<HTMLDivElement>(null);
+	useRovingFocus({ containerRef: listRef, itemSelector: LIST_ROW_SELECTOR });
 
 	if (isLoading) {
 		return (
@@ -563,7 +573,7 @@ function OutboxPhone() {
 					{messages.length} {messages.length === 1 ? "message" : "messages"}
 				</span>
 			</header>
-			<div className="flex-1 overflow-y-auto">
+			<div ref={listRef} className="flex-1 overflow-y-auto">
 				{messages.map((message) => (
 					<OutboxMessageRow
 						key={message.outboxMessageId}

package/src/lib/selection-mode.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	deriveIsMultiSelectMode,
+	shouldExitSelectionOnNavigate,
+} from "./selection-mode.js";
+
+describe("deriveIsMultiSelectMode", () => {
+	test("no selection is not multi-select mode", () => {
+		assert.equal(deriveIsMultiSelectMode(0, false), false);
+	});
+
+	test("any selection on touch is multi-select mode", () => {
+		assert.equal(deriveIsMultiSelectMode(1, false), true);
+		assert.equal(deriveIsMultiSelectMode(42, false), true);
+	});
+
+	test("desktop selection drives the desktop toolbar, not multi-select mode", () => {
+		assert.equal(deriveIsMultiSelectMode(1, true), false);
+		assert.equal(deriveIsMultiSelectMode(0, true), false);
+	});
+
+	test("dropping the last selected id leaves the mode in the same call", () => {
+		assert.equal(deriveIsMultiSelectMode(1, false), true);
+		assert.equal(deriveIsMultiSelectMode(0, false), false);
+	});
+});
+
+describe("shouldExitSelectionOnNavigate", () => {
+	test("back while selecting exits selection instead of navigating", () => {
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true), true);
+	});
+
+	test("back with nothing selected is left alone", () => {
+		assert.equal(shouldExitSelectionOnNavigate("BACK", false), false);
+	});
+
+	test("forward, push, replace and go are never blocked", () => {
+		assert.equal(shouldExitSelectionOnNavigate("FORWARD", true), false);
+		assert.equal(shouldExitSelectionOnNavigate("PUSH", true), false);
+		assert.equal(shouldExitSelectionOnNavigate("REPLACE", true), false);
+		assert.equal(shouldExitSelectionOnNavigate("GO", true), false);
+	});
+});

package/src/lib/selection-mode.ts

@@ -0,0 +1,29 @@
+/**
+ * Selection-mode rules for the message list (#115, refs #92 requirements 9
+ * and 10). Pure so "one source of truth, one exit" is testable without a DOM.
+ */
+
+/** The subset of `@tanstack/history`'s `HistoryAction` a blocker can see. */
+export type NavigationAction = "PUSH" | "REPLACE" | "FORWARD" | "BACK" | "GO";
+
+/**
+ * Whether the list is in multi-select mode: a function of the selection count,
+ * never a stored flag, so the two can never disagree. Multi-select is the
+ * touch affordance (long press, always-visible checkboxes, the selection top
+ * bar); on desktop a selection drives the desktop toolbar instead and rows
+ * keep their ordinary hover behaviour.
+ */
+export const deriveIsMultiSelectMode = (
+	selectedCount: number,
+	isDesktop: boolean,
+): boolean => !isDesktop && selectedCount > 0;
+
+/**
+ * Whether a history navigation should exit selection mode instead of leaving
+ * the route. Only the back gesture is intercepted, so a navigation the app
+ * itself starts (opening a message, switching mailboxes) is never blocked.
+ */
+export const shouldExitSelectionOnNavigate = (
+	action: NavigationAction,
+	hasSelection: boolean,
+): boolean => action === "BACK" && hasSelection;