@remit/web-client 0.0.90 → 0.0.92

package/src/lib/list-header-chrome.ts

@@ -0,0 +1,50 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+/**
+ * The list header's own chrome, as rendered nodes.
+ *
+ * The list header and the selection bar are one surface (#480), so the nav
+ * button, the unread count and the search affordance belong on the same row as
+ * the count and the verbs. That row is rendered by the body — the list owns the
+ * selection — while the search state it needs belongs to `MailListHeader`.
+ * Handing the built nodes down keeps one definition of the chrome and keeps the
+ * bar's two states in the same commit: nothing here is derived from a state
+ * update that lands after paint.
+ */
+export interface ListHeaderChrome {
+	/** The view's name, carried while nothing is ticked. */
+	title: string;
+	/** Hamburger for the nav slide-over; absent where the nav is a pane. */
+	navSlot: ReactNode;
+	/** Unread count, beside the title. */
+	titleMeta: ReactNode;
+	/** Magnifier that opens search, on the tiers whose header owns a field. */
+	searchSlot: ReactNode;
+	/** The expanded field, which takes the title's place for as long as it is up. */
+	searchField: ReactNode;
+	/**
+	 * The read-only two-engine results panel, when a query is being typed and
+	 * this view answers it with the panel rather than its own rows. The body
+	 * renders it in place of its list; `MailListHeader` cannot swap the body
+	 * out from above, because the header is inside it.
+	 */
+	searchResults: ReactNode;
+	/** The search's make-this-a-filter row, up only while nothing is ticked. */
+	makeFilterSlot: ReactNode;
+}
+
+const NO_CHROME: ListHeaderChrome = {
+	title: "",
+	navSlot: null,
+	titleMeta: null,
+	searchSlot: null,
+	searchField: null,
+	searchResults: null,
+	makeFilterSlot: null,
+};
+
+export const ListHeaderChromeContext =
+	createContext<ListHeaderChrome>(NO_CHROME);
+
+export const useListHeaderChrome = (): ListHeaderChrome =>
+	useContext(ListHeaderChromeContext);

package/src/lib/mail-context.ts

@@ -54,6 +54,13 @@ export interface MailContextValue {
 	onToggleIntelligence: () => void;
 	/** Set the pane open/closed and persist the choice (desktop default-open). */
 	onSetIntelligenceOpen: (open: boolean) => void;
+	/**
+	 * How many rows the list has ticked. The selection is owned by the list, and
+	 * surfaces mounted beside it — the selection wizard (#477) — need the same
+	 * number the bar is counting rather than one of their own.
+	 */
+	selectedCount: number;
+	onSelectedCountChange: (count: number) => void;
 }
 
 export const MailContext = createContext<MailContextValue | null>(null);
@@ -78,6 +85,8 @@ export const useMailContext = (): MailContextValue => {
 			intelligenceOpen: false,
 			onToggleIntelligence: () => {},
 			onSetIntelligenceOpen: () => {},
+			selectedCount: 0,
+			onSelectedCountChange: () => {},
 		}
 	);
 };

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

@@ -28,17 +28,31 @@ describe("deriveIsMultiSelectMode", () => {
 
 describe("shouldExitSelectionOnNavigate", () => {
 	test("back while selecting exits selection instead of navigating", () => {
-		assert.equal(shouldExitSelectionOnNavigate("BACK", true), true);
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, undefined), true);
 	});
 
 	test("back with nothing selected is left alone", () => {
-		assert.equal(shouldExitSelectionOnNavigate("BACK", false), false);
+		assert.equal(
+			shouldExitSelectionOnNavigate("BACK", false, undefined),
+			false,
+		);
+	});
+
+	test("back inside the wizard pops a step instead of the selection", () => {
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, "match"), false);
+		assert.equal(shouldExitSelectionOnNavigate("BACK", true, "review"), 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);
+		assert.equal(
+			shouldExitSelectionOnNavigate("FORWARD", true, undefined),
+			false,
+		);
+		assert.equal(shouldExitSelectionOnNavigate("PUSH", true, undefined), false);
+		assert.equal(
+			shouldExitSelectionOnNavigate("REPLACE", true, undefined),
+			false,
+		);
+		assert.equal(shouldExitSelectionOnNavigate("GO", true, undefined), false);
 	});
 });

package/src/lib/selection-mode.ts

@@ -3,6 +3,8 @@
  * and 10). Pure so "one source of truth, one exit" is testable without a DOM.
  */
 
+import type { StepId } from "@remit/ui";
+
 /** The subset of `@tanstack/history`'s `HistoryAction` a blocker can see. */
 export type NavigationAction = "PUSH" | "REPLACE" | "FORWARD" | "BACK" | "GO";
 
@@ -22,8 +24,13 @@ export const deriveIsMultiSelectMode = (
  * 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.
+ *
+ * While the selection wizard is open its own steps own the back gesture, and
+ * the selection is what the wizard is acting on — swallowing back there would
+ * clear the selection out from under the flow instead of popping a step.
  */
 export const shouldExitSelectionOnNavigate = (
 	action: NavigationAction,
 	hasSelection: boolean,
-): boolean => action === "BACK" && hasSelection;
+	wizardStep: StepId | undefined,
+): boolean => action === "BACK" && hasSelection && wizardStep === undefined;

package/src/lib/wizard-history.test.ts

@@ -0,0 +1,176 @@
+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";
+import {
+	backExits,
+	type MatchMode,
+	type RuleScope,
+	type StepId,
+	stepIndex,
+	stepsFor,
+	type Verb,
+	type WizardAnswers,
+} from "@remit/ui";
+import {
+	ownedHistoryEntries,
+	wizardStepFromParam,
+	wizardStepValue,
+} from "./wizard-history.js";
+
+const VERBS: readonly Verb[] = [
+	"delete",
+	"move",
+	"junk",
+	"markRead",
+	"organize",
+];
+const MODES: readonly MatchMode[] = ["selected", "similar", "properties"];
+const SCOPES: readonly (RuleScope | undefined)[] = [
+	undefined,
+	"once",
+	"standing",
+	"until",
+];
+
+const answerSets = (): WizardAnswers[] => {
+	const sets: WizardAnswers[] = [];
+	for (const verb of VERBS) {
+		for (const mode of MODES) {
+			for (const scope of SCOPES) {
+				for (const fromSearch of [false, true]) {
+					sets.push({ verb, mode, scope, fromSearch });
+				}
+			}
+		}
+	}
+	return sets;
+};
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = readFileSync(resolve(here, "wizard-history.ts"), "utf8");
+
+/** The steps up to and including the one an answer is given on. */
+const prefixThrough = (steps: readonly StepId[], step: StepId): StepId[] =>
+	steps.slice(0, steps.indexOf(step) + 1);
+
+/**
+ * The re-root runs inside a router, so the rule is enforced by reading the
+ * source — as `../components/mail/MessageList.selection.test.ts` does for its
+ * own component-level rules. What it pins is where the decision comes from: a
+ * step the app itself pushed must never be re-rooted, or the push that opens
+ * the wizard from a verb (#483) duplicates the entry underneath it and the
+ * first back after Cancel appears to do nothing.
+ */
+describe("re-rooting a wizard that was loaded into", () => {
+	it("decides from what the first render held, not from a flag", () => {
+		assert.match(source, /useRef\(step !== undefined\)/);
+		assert.match(
+			source,
+			/if \(!loadedHoldingStep\.current\) return;\s*\n\s*loadedHoldingStep\.current = false;/,
+		);
+	});
+
+	it("is never armed by a step the app pushed", () => {
+		const goToStep = source.slice(source.indexOf("const goToStep"));
+		assert.doesNotMatch(goToStep, /loadedHoldingStep/);
+	});
+
+	it("does not re-run when the step changes", () => {
+		assert.doesNotMatch(source, /\}, \[step, openingStep, navigate\]\)/);
+	});
+});
+
+describe("the wizard step in the URL", () => {
+	it("round-trips every step the wizard can reach", () => {
+		for (const answers of answerSets()) {
+			for (const step of stepsFor(answers)) {
+				assert.equal(wizardStepFromParam(step), step);
+			}
+		}
+	});
+
+	it("reads a value the wizard cannot be on as no step", () => {
+		for (const value of [undefined, "", "Match", "step-1", 2, null, {}]) {
+			assert.equal(wizardStepFromParam(value), undefined);
+		}
+	});
+
+	it("never fails validation, so a mistyped link still lands on the mail", () => {
+		for (const value of ["nope", "MATCH", "run ", 7, [], null, undefined]) {
+			const parsed = wizardStepValue.safeParse(value);
+			assert.ok(parsed.success);
+			assert.equal(parsed.data, undefined);
+		}
+		assert.equal(wizardStepValue.parse("review"), "review");
+	});
+});
+
+describe("the history entries the wizard owns", () => {
+	it("is one per step reached, on every shape of the list", () => {
+		for (const answers of answerSets()) {
+			const steps = stepsFor(answers);
+			steps.forEach((step, position) => {
+				assert.equal(ownedHistoryEntries(steps, step), position + 1);
+			});
+		}
+	});
+
+	it("cannot be moved by the match door, which is answered before it", () => {
+		for (const verb of VERBS) {
+			for (const scope of SCOPES) {
+				const prefixes = MODES.map((mode) =>
+					prefixThrough(stepsFor({ verb, mode, scope }), "match"),
+				);
+				for (const prefix of prefixes) {
+					assert.deepEqual(prefix, prefixes[0]);
+					for (const step of prefix) {
+						const counts = MODES.map((mode) =>
+							ownedHistoryEntries(stepsFor({ verb, mode, scope }), step),
+						);
+						assert.equal(new Set(counts).size, 1);
+					}
+				}
+			}
+		}
+	});
+
+	it("cannot be moved by the scope, which is answered before it", () => {
+		for (const mode of MODES) {
+			for (const fromSearch of [false, true]) {
+				const listFor = (scope: RuleScope | undefined) =>
+					stepsFor({ verb: "organize", mode, scope, fromSearch });
+				const prefixes = SCOPES.map((scope) =>
+					prefixThrough(listFor(scope), "rule"),
+				);
+				for (const prefix of prefixes) {
+					assert.deepEqual(prefix, prefixes[0]);
+					for (const step of prefix) {
+						const counts = SCOPES.map((scope) =>
+							ownedHistoryEntries(listFor(scope), step),
+						);
+						assert.equal(new Set(counts).size, 1);
+					}
+				}
+			}
+		}
+	});
+
+	it("rewinds the whole flow from the steps Back leaves on", () => {
+		for (const answers of answerSets()) {
+			const steps = stepsFor(answers);
+			assert.ok(backExits(steps, steps[0]));
+			assert.equal(ownedHistoryEntries(steps, steps[0]), 1);
+			const run = steps[steps.length - 1];
+			assert.ok(backExits(steps, run));
+			assert.equal(ownedHistoryEntries(steps, run), steps.length);
+		}
+	});
+
+	it("holds a step the answers dropped to the opening entry", () => {
+		const steps = stepsFor({ verb: "delete", mode: "selected" });
+		assert.equal(stepIndex(steps, "properties"), 0);
+		assert.equal(ownedHistoryEntries(steps, "properties"), 1);
+	});
+});

package/src/lib/wizard-history.ts

@@ -0,0 +1,116 @@
+/**
+ * The selection wizard's step in the URL, and the history entries it owns
+ * (#477 clause 1.6). TanStack Router owns history here: the step is a validated
+ * `wizard` search param on /mail, pushed with `navigate({ search })`, so
+ * `router.state.location` and `window.location` never disagree.
+ *
+ * The wizard is rooted on an entry that carries no step, so the entries it owns
+ * are the pushes that reached the current step: one for the opening step, one
+ * per advance. A document that loads straight into a step has no such root, and
+ * no answers behind the step either, so it is re-rooted at the opening step
+ * before anything else — otherwise the number of entries to rewind is a guess
+ * about a tab this code never saw.
+ *
+ * Which steps Back leaves the wizard from is `backExits` in the step model, and
+ * the shell reads it to route Back to exit rather than to a step. These are the
+ * two movements it routes between: `goBack` pops one entry, `closeWizard`
+ * rewinds every entry the wizard owns.
+ */
+
+import { type StepId, stepIndex } from "@remit/ui";
+import { useNavigate, useRouter, useSearch } from "@tanstack/react-router";
+import { useCallback, useEffect, useRef } from "react";
+import { z } from "zod";
+
+const stepId = z.enum([
+	"match",
+	"properties",
+	"folder",
+	"rule",
+	"name",
+	"review",
+	"run",
+]);
+
+export const wizardStepFromParam = (value: unknown): StepId | undefined => {
+	const parsed = stepId.safeParse(value);
+	return parsed.success ? parsed.data : undefined;
+};
+
+/**
+ * The route's `wizard` field. A value the wizard cannot be on reads as no step
+ * rather than as a validation failure, so a truncated or hand-typed link lands
+ * on the mail list instead of the router's error screen.
+ */
+export const wizardStepValue = z.unknown().transform(wizardStepFromParam);
+
+export const ownedHistoryEntries = (
+	steps: readonly StepId[],
+	step: StepId,
+): number => stepIndex(steps, step) + 1;
+
+export const useWizardStepValue = (): StepId | undefined =>
+	useSearch({ from: "/mail", select: (search) => search.wizard });
+
+export interface WizardStepNavigation {
+	step: StepId | undefined;
+	goToStep: (step: StepId) => void;
+	goBack: () => void;
+	closeWizard: (steps: readonly StepId[], step: StepId) => void;
+}
+
+export const useWizardStep = (openingStep: StepId): WizardStepNavigation => {
+	const router = useRouter();
+	const navigate = useNavigate();
+	const step = useWizardStepValue();
+	// Whether this document loaded already holding a step, which is the one
+	// entrance that leaves the wizard unrooted. A step the app itself pushed
+	// arrives rooted, so re-rooting it would duplicate the entry underneath it.
+	const loadedHoldingStep = useRef(step !== undefined);
+	const pushedTo = useRef<StepId | undefined>(undefined);
+
+	// Two taps on Continue land before the URL settles, and both would push the
+	// same step — leaving a back that appears to do nothing.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the guard is cleared because the step changed, which is only knowable from the dependency.
+	useEffect(() => {
+		pushedTo.current = undefined;
+	}, [step]);
+
+	useEffect(() => {
+		if (!loadedHoldingStep.current) return;
+		loadedHoldingStep.current = false;
+		void (async () => {
+			await navigate({
+				to: ".",
+				search: (prev) => ({ ...prev, wizard: undefined }),
+				replace: true,
+			});
+			await navigate({
+				to: ".",
+				search: (prev) => ({ ...prev, wizard: openingStep }),
+			});
+		})();
+	}, [openingStep, navigate]);
+
+	const goToStep = useCallback(
+		(next: StepId) => {
+			if (next === step || pushedTo.current === next) return;
+			pushedTo.current = next;
+			navigate({ to: ".", search: (prev) => ({ ...prev, wizard: next }) });
+		},
+		[navigate, step],
+	);
+
+	const goBack = useCallback(() => {
+		router.history.back();
+	}, [router]);
+
+	const closeWizard = useCallback(
+		(steps: readonly StepId[], current: StepId) => {
+			router.history.go(-ownedHistoryEntries(steps, current));
+		},
+		[router],
+	);
+
+	return { step, goToStep, goBack, closeWizard };
+};

package/src/routes/mail.tsx

@@ -21,6 +21,7 @@ import { FlaggedPane } from "@/components/mail/FlaggedPane";
 import { MailboxPane } from "@/components/mail/MailboxPane";
 import { MailNav } from "@/components/mail/MailNav";
 import { OutboxPane } from "@/components/mail/OutboxPane";
+import { SelectionWizardHost } from "@/components/mail/SelectionWizardHost";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { KeyboardShortcutsModal } from "@/components/ui/KeyboardShortcutsModal";
 import { useDebouncedValue } from "@/hooks/useDebouncedValue";
@@ -43,6 +44,7 @@ import {
 	searchInputForView,
 	shouldMirrorQuery,
 } from "@/lib/search-view";
+import { wizardStepValue } from "@/lib/wizard-history";
 import "@/lib/client";
 
 // `MailContext` / `useMailContext` live in `@/lib/mail-context` so the provider
@@ -53,6 +55,9 @@ export { useMailContext } from "@/lib/mail-context";
 
 const mailSearchSchema = z.object({
 	q: z.string().optional(),
+	// The selection wizard's step (#477 clause 1.6). The router owns history, so
+	// the step is a validated search param rather than a raw pushState entry.
+	wizard: wizardStepValue,
 });
 
 export const Route = createFileRoute("/mail")({
@@ -92,6 +97,9 @@ function MailLayout() {
 	// collapse preference there (#782). DKIM-mismatch auto-open still fires on
 	// every tier. Explicit toggles persist the user's choice.
 	const [intelligenceOpen, setIntelligenceOpen] = useState(false);
+	// The list owns the selection; the wizard is mounted here, beside it, and
+	// counts the same rows the selection bar is counting.
+	const [selectedCount, setSelectedCount] = useState(0);
 	const handleSetIntelligenceOpen = useCallback((open: boolean) => {
 		setIntelligenceOpen(open);
 		writeIntelligencePref(open);
@@ -304,6 +312,8 @@ function MailLayout() {
 		intelligenceOpen,
 		onToggleIntelligence: handleToggleIntelligence,
 		onSetIntelligenceOpen: handleSetIntelligenceOpen,
+		selectedCount,
+		onSelectedCountChange: setSelectedCount,
 	};
 
 	// Single nav node: the kit renders it as a pane (≥1024px) or inside its
@@ -468,6 +478,7 @@ function MailLayout() {
 				isOpen={showShortcuts}
 				onClose={() => setShowShortcuts(false)}
 			/>
+			<SelectionWizardHost verb="organize" selectedCount={selectedCount} />
 			{/* Outlet is required for TanStack Router to activate child routes.
 			    Routes that manage their own rendering (brief, mailbox, outbox) return
 			    null from their component — the parent shell owns the layout. */}