@remit/web-client 0.0.91 → 0.0.93

package/src/lib/wizard-history.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 });
+
+/**
+ * Opens the wizard on a step, from a surface that does not drive it — a verb on
+ * the selection bar. The push is the wizard's first owned entry, so the back
+ * that leaves it lands on the list with the selection still ticked.
+ */
+export const useOpenWizard = (): ((step: StepId) => void) => {
+	const navigate = useNavigate();
+	return useCallback(
+		(step: StepId) => {
+			navigate({ to: ".", search: (prev) => ({ ...prev, wizard: step }) });
+		},
+		[navigate],
+	);
+};
+
+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

@@ -43,6 +43,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 +54,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")({

package/src/components/mail/organize/MobileOrganizeFlow.render.test.ts

@@ -1,45 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import React, { createElement } from "react";
-import { renderToString } from "react-dom/server";
-import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
-import type { OrganizeEntry } from "@/lib/organize/mobile-organize-flow";
-import { MobileOrganizeFlow } from "./MobileOrganizeFlow";
-
-// The node test loader transpiles remit-ui's `.tsx` with the classic JSX
-// runtime, which references a global `React`. Vite uses the automatic runtime,
-// so this shim only exists for the SSR test harness.
-(globalThis as { React?: typeof React }).React = React;
-
-const render = (entry: OrganizeEntry) =>
-	renderToString(
-		createElement(
-			QueryClientProvider,
-			{ client: new QueryClient() },
-			createElement(
-				ErrorBannerProvider,
-				null,
-				createElement(MobileOrganizeFlow, {
-					entry,
-					accountId: "acc-1",
-					selectedMessageIds: ["msg-1", "msg-2"],
-					selectedSenders: ["npm@github.com"],
-					onClose: () => undefined,
-				}),
-			),
-		) as never,
-	);
-
-describe("MobileOrganizeFlow", () => {
-	it("select-similar opens on the widening state before the preview resolves", () => {
-		const html = render("select-similar");
-		assert.match(html, /Finding similar messages/);
-	});
-
-	it("something-else opens on the shortcuts + plain-language input", () => {
-		const html = render("something-else");
-		assert.match(html, /What should Remit do\?/);
-		assert.match(html, /Tell Remit what to do/);
-	});
-});

package/src/components/mail/organize/MobileOrganizeFlow.tsx

@@ -1,157 +0,0 @@
-import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RuleScope } from "@remit/ui";
-import { BottomSheet, Button } from "@remit/ui";
-import { useQuery } from "@tanstack/react-query";
-import { Loader2 } from "lucide-react";
-import { useEffect, useMemo, useState } from "react";
-import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
-import { getMailboxDisplayName } from "@/lib/folder-roles";
-import { buildMoveTargets } from "@/lib/move-targets";
-import {
-	type OrganizeEntry,
-	type OrganizeSeed,
-	type PreviewStatus,
-	resolveOrganizeStage,
-} from "@/lib/organize/mobile-organize-flow";
-import { OrganizeRuleEditor } from "./OrganizeRuleEditor";
-import { SomethingElsePanel } from "./SomethingElsePanel";
-
-/**
- * Map a "Something else" seed's scope onto the rule editor's scope. Only the
- * standing shortcut carries one; everything else lets the editor default.
- */
-const seedRuleScope = (
-	seed: OrganizeSeed | undefined,
-): RuleScope | undefined =>
-	seed?.scope === "standing" ? "standing" : undefined;
-
-interface MobileOrganizeFlowProps {
-	entry: OrganizeEntry;
-	accountId: string;
-	selectedMessageIds: string[];
-	/**
-	 * Sender addresses of the selected messages, driving the literal fallback on
-	 * a deployment without the vector pipeline (semantic-capability.ts).
-	 */
-	selectedSenders: string[];
-	junkMailboxId?: string;
-	/** Close the flow and return to the list — dismiss, "Not now", and Done all use it. */
-	onClose: () => void;
-}
-
-const previewStatusOf = (
-	isError: boolean,
-	isPending: boolean,
-	matchedCount: number | undefined,
-): PreviewStatus => {
-	if (isError) return "error";
-	if (isPending) return "pending";
-	return matchedCount !== undefined ? "success" : "idle";
-};
-
-/**
- * The guided select-similar → organize flow, the mobile home for organizing
- * (issue #211). Entered from the selection sheet, it widens the selection once
- * with the read-only matcher (POST /organize/preview), shows a brief widening
- * state, and renders the organize sentence inside a bottom sheet on that
- * widened set — the same {@link OrganizePanel} the desktop dialog uses, so the
- * two never drift. "Something else" collects a folder/scope seed first; a widen
- * that matches nothing falls back to organizing the selection. Desktop keeps
- * its `OrganizeDialog` — this is the touch surface only.
- */
-export function MobileOrganizeFlow({
-	entry,
-	accountId,
-	selectedMessageIds,
-	selectedSenders,
-	junkMailboxId,
-	onClose,
-}: MobileOrganizeFlowProps) {
-	const anchorMessageId = selectedMessageIds[0];
-	const [seed, setSeed] = useState<OrganizeSeed | undefined>();
-
-	const {
-		preview,
-		matchedCount,
-		semanticUnavailable,
-		senders,
-		isPending,
-		isError,
-		error,
-	} = useOrganizeWiden(accountId, anchorMessageId, selectedSenders);
-
-	useEffect(() => {
-		preview();
-	}, [preview]);
-
-	const { data: mailboxesData } = useQuery({
-		...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
-		staleTime: Number.POSITIVE_INFINITY,
-	});
-
-	const folderOptions = useMemo(
-		() =>
-			buildMoveTargets(mailboxesData?.items ?? []).map((mailbox) => ({
-				id: mailbox.mailboxId,
-				label: getMailboxDisplayName(mailbox.fullPath),
-			})),
-		[mailboxesData?.items],
-	);
-
-	const stage = resolveOrganizeStage({
-		entry,
-		hasSeed: seed !== undefined,
-		previewStatus: previewStatusOf(isError, isPending, matchedCount),
-		matchedCount,
-	});
-
-	return (
-		<BottomSheet open onClose={onClose} dismissLabel="Dismiss organize">
-			{stage.kind === "something-else" && (
-				<SomethingElsePanel
-					folderOptions={folderOptions}
-					junkMailboxId={junkMailboxId}
-					onSeed={setSeed}
-				/>
-			)}
-
-			{stage.kind === "widening" && <WideningState />}
-
-			{stage.kind === "error" && (
-				<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
-					<p className="text-sm font-medium text-danger">
-						Couldn't find similar messages
-					</p>
-					<p className="max-w-xs text-xs text-fg-muted">
-						{error instanceof Error ? error.message : "Please try again."}
-					</p>
-					<Button variant="ghost" onClick={onClose} className="mt-2">
-						Close
-					</Button>
-				</div>
-			)}
-
-			{stage.kind === "organize" && (
-				<OrganizeRuleEditor
-					accountId={accountId}
-					selectedMessageIds={selectedMessageIds}
-					seedCount={stage.matchedCount}
-					seedScope={seedRuleScope(seed)}
-					seedMailboxId={seed?.moveMailboxId}
-					semanticUnavailable={semanticUnavailable}
-					senders={senders}
-					onClose={onClose}
-				/>
-			)}
-		</BottomSheet>
-	);
-}
-
-function WideningState() {
-	return (
-		<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
-			<Loader2 className="size-8 animate-spin text-accent-2" />
-			<p className="text-sm font-medium text-fg">Finding similar messages…</p>
-		</div>
-	);
-}

package/src/components/mail/organize/OrganizeDialog.render.test.ts

@@ -1,37 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import React, { createElement } from "react";
-import { renderToString } from "react-dom/server";
-import { OrganizeDialog } from "./OrganizeDialog";
-
-// The node test loader transpiles remit-ui's `.tsx` with the classic JSX
-// runtime, which references a global `React`. Vite uses the automatic runtime,
-// so this shim only exists for the SSR test harness.
-(globalThis as { React?: typeof React }).React = React;
-
-const render = (open: boolean) =>
-	renderToString(
-		createElement(
-			QueryClientProvider,
-			{ client: new QueryClient() },
-			createElement(OrganizeDialog, {
-				open,
-				accountId: "acc-1",
-				selectedMessageIds: ["msg-1", "msg-2"],
-				selectedSenders: ["npm@github.com"],
-				onClose: () => undefined,
-			}),
-		) as never,
-	);
-
-describe("OrganizeDialog", () => {
-	it("renders nothing when closed", () => {
-		assert.equal(render(false), "");
-	});
-
-	it("shows the widen step while the preview is in flight", () => {
-		const html = render(true);
-		assert.match(html, /Finding similar messages/);
-	});
-});

package/src/components/mail/organize/OrganizeDialog.tsx

@@ -1,91 +0,0 @@
-import { Button, Dialog } from "@remit/ui";
-import { Loader2 } from "lucide-react";
-import { useEffect } from "react";
-import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
-import { OrganizeRuleEditor } from "./OrganizeRuleEditor";
-
-interface OrganizeDialogProps {
-	open: boolean;
-	accountId: string;
-	selectedMessageIds: string[];
-	/**
-	 * Sender addresses of the selected messages, driving the literal fallback on
-	 * a deployment without the vector pipeline (semantic-capability.ts).
-	 */
-	selectedSenders: string[];
-	onClose: () => void;
-}
-
-/**
- * Smart-organize flow entered from the selection toolbar. Widens the selection
- * once (POST /organize/preview) to seed the rule, then hands off to the chip
- * editor (RFC 038 D1), which counts and commits over the same endpoints. The
- * widen is only the opening count; the editor re-previews every edit.
- */
-export function OrganizeDialog({
-	open,
-	accountId,
-	selectedMessageIds,
-	selectedSenders,
-	onClose,
-}: OrganizeDialogProps) {
-	const anchorMessageId = selectedMessageIds[0];
-	const {
-		preview,
-		reset,
-		matchedCount,
-		semanticUnavailable,
-		senders,
-		isPending,
-		isError,
-		error,
-	} = useOrganizeWiden(accountId, anchorMessageId, selectedSenders);
-
-	useEffect(() => {
-		if (!open) return;
-		preview();
-	}, [open, preview]);
-
-	const handleClose = () => {
-		reset();
-		onClose();
-	};
-
-	if (!open) return null;
-
-	return (
-		<Dialog open={open} onClose={handleClose} title="Filter rule">
-			{isPending || matchedCount === undefined ? (
-				isError ? (
-					<div className="flex flex-col items-center gap-3 px-5 py-8 text-center">
-						<p className="text-sm font-medium text-danger">
-							Couldn't find similar messages
-						</p>
-						<p className="max-w-xs text-xs text-fg-muted">
-							{error instanceof Error ? error.message : "Please try again."}
-						</p>
-						<Button variant="ghost" onClick={handleClose} className="mt-2">
-							Close
-						</Button>
-					</div>
-				) : (
-					<div className="flex flex-col items-center gap-3 px-5 py-10 text-center">
-						<Loader2 className="size-8 animate-spin text-accent-2" />
-						<p className="text-sm font-medium text-fg">
-							Finding similar messages…
-						</p>
-					</div>
-				)
-			) : (
-				<OrganizeRuleEditor
-					accountId={accountId}
-					selectedMessageIds={selectedMessageIds}
-					seedCount={matchedCount}
-					semanticUnavailable={semanticUnavailable}
-					senders={senders}
-					onClose={handleClose}
-				/>
-			)}
-		</Dialog>
-	);
-}