@remit/web-client 0.0.56 → 0.0.58

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

@@ -14,7 +14,7 @@ import { OrganizePanel } from "./OrganizePanel";
 // so this shim only exists for the SSR test harness.
 (globalThis as { React?: typeof React }).React = React;
 
-const render = () =>
+const render = (overrides: Partial<Parameters<typeof OrganizePanel>[0]> = {}) =>
 	renderToString(
 		createElement(
 			QueryClientProvider,
@@ -29,6 +29,7 @@ const render = () =>
 					anchorMessageId: "msg-1",
 					matchedCount: 47,
 					onClose: () => undefined,
+					...overrides,
 				}),
 			),
 		) as never,
@@ -54,6 +55,18 @@ describe("OrganizePanel", () => {
 		assert.match(html, /These and new mail like this/);
 		assert.match(html, /Until a date/);
 	});
+
+	it("says it is organizing just the selection when the widen matched nothing (#211 — no dead end)", () => {
+		const html = render({ matchedCount: 0, fallback: true });
+		assert.match(html, /No similar messages found/);
+		assert.match(html, /organizing just your 2 selected/);
+	});
+
+	it("pre-selects the seeded scope (a 'Something else' shortcut seeds the sentence)", () => {
+		const html = render({ initialScope: "standing" });
+		// The standing scope's "Always keep" phrasing only renders when it is active.
+		assert.match(html, /Always keep/);
+	});
 });
 
 // The commit button's `disabled` prop is

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

@@ -26,6 +26,22 @@ interface OrganizePanelProps {
 	anchorMessageId: string;
 	/** Similar messages the widen preview matched. */
 	matchedCount: number;
+	/**
+	 * Which scope is selected on open. Defaults to `all-like-these`; the
+	 * zero-match fallback and a "Something else" seed override it.
+	 */
+	initialScope?: OrganizeScope;
+	/**
+	 * Destination folder to pre-select — a "Something else" shortcut or a
+	 * plain-language input seeds this (issue #211).
+	 */
+	seedMailboxId?: string;
+	/**
+	 * The widen matched nothing, so the sentence organizes just the selection
+	 * rather than dead-ending. Changes the heading and defaults the scope to
+	 * `just-these`.
+	 */
+	fallback?: boolean;
 	onClose: () => void;
 }
 
@@ -58,10 +74,17 @@ export function OrganizePanel({
 	selectedMessageIds,
 	anchorMessageId,
 	matchedCount,
+	initialScope,
+	seedMailboxId,
+	fallback = false,
 	onClose,
 }: OrganizePanelProps) {
-	const [scope, setScope] = useState<OrganizeScope>("all-like-these");
-	const [moveMailboxId, setMoveMailboxId] = useState<string>("");
+	const [scope, setScope] = useState<OrganizeScope>(
+		initialScope ?? (fallback ? "just-these" : "all-like-these"),
+	);
+	const [moveMailboxId, setMoveMailboxId] = useState<string>(
+		seedMailboxId ?? "",
+	);
 	const [name, setName] = useState("");
 	const [pickedDate, setPickedDate] = useState("");
 
@@ -155,8 +178,11 @@ export function OrganizePanel({
 			<div className="border-b border-line px-5 py-3">
 				<h2 className="text-sm font-semibold text-fg">Organize</h2>
 				<p className="mt-0.5 text-xs text-fg-muted">
-					{matchedCount} similar message{matchedCount === 1 ? "" : "s"} found
-					{selectionCount > 0 ? ` from ${selectionCount} selected` : ""}.
+					{fallback
+						? `No similar messages found — organizing just your ${selectionCount} selected.`
+						: `${matchedCount} similar message${matchedCount === 1 ? "" : "s"} found${
+								selectionCount > 0 ? ` from ${selectionCount} selected` : ""
+							}.`}
 				</p>
 			</div>
 

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

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { OrganizeSeed } from "@/lib/organize/mobile-organize-flow";
+import { type FolderOption, SomethingElsePanel } from "./SomethingElsePanel";
+
+// 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 FOLDERS: FolderOption[] = [
+	{ id: "mbx-inbox", label: "Inbox" },
+	{ id: "mbx-archive", label: "Archive" },
+	{ id: "mbx-junk", label: "Spam" },
+];
+
+const render = (
+	folderOptions: FolderOption[] = FOLDERS,
+	junkMailboxId?: string,
+) =>
+	renderToString(
+		createElement(SomethingElsePanel, {
+			folderOptions,
+			junkMailboxId,
+			onSeed: (_seed: OrganizeSeed) => undefined,
+		}) as never,
+	);
+
+describe("SomethingElsePanel", () => {
+	it("shows the plain-language prompt and input", () => {
+		const html = render();
+		assert.match(html, /What should Remit do\?/);
+		assert.match(html, /Tell Remit what to do/);
+	});
+
+	it("derives shortcuts from the account's real folders", () => {
+		const html = render();
+		assert.match(html, /Always keep in Inbox/);
+		assert.match(html, /File in Archive/);
+	});
+
+	it("offers the appointed Junk mailbox by its own label", () => {
+		const html = render(FOLDERS, "mbx-junk");
+		assert.match(html, /Move to Spam/);
+	});
+
+	it("offers no folder shortcuts when the account has none", () => {
+		const html = render([]);
+		assert.doesNotMatch(html, /Always keep in Inbox/);
+		assert.doesNotMatch(html, /File in Archive/);
+	});
+});

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

@@ -0,0 +1,159 @@
+import { Button, Input } from "@remit/ui";
+import { ArrowUp } from "lucide-react";
+import { useMemo, useState } from "react";
+import type { OrganizeSeed } from "@/lib/organize/mobile-organize-flow";
+
+export interface FolderOption {
+	id: string;
+	label: string;
+}
+
+interface SomethingElsePanelProps {
+	/** The account's move destinations, the same set the sentence's folder picker uses. */
+	folderOptions: FolderOption[];
+	/** The appointed Junk mailbox, offered as a shortcut when present. */
+	junkMailboxId?: string;
+	/** Chosen shortcut or parsed input — seeds the organize sentence's folder/scope. */
+	onSeed: (seed: OrganizeSeed) => void;
+}
+
+interface Shortcut {
+	id: string;
+	label: string;
+	seed: OrganizeSeed;
+}
+
+const findFolder = (
+	folderOptions: FolderOption[],
+	label: string,
+): FolderOption | undefined =>
+	folderOptions.find((folder) => folder.label.toLowerCase() === label);
+
+/**
+ * Shortcuts are derived from the account's real folders — there is no
+ * suggestion endpoint, so the panel offers the moves it can actually commit:
+ * keep it in the Inbox as a standing rule, file it in Archive, or send it to
+ * the appointed Junk mailbox. Each seeds the organize sentence; the user still
+ * confirms the scope.
+ */
+const buildShortcuts = (
+	folderOptions: FolderOption[],
+	junkMailboxId: string | undefined,
+): Shortcut[] => {
+	const shortcuts: Shortcut[] = [];
+	const inbox = findFolder(folderOptions, "inbox");
+	if (inbox) {
+		shortcuts.push({
+			id: "keep-inbox",
+			label: "Always keep in Inbox",
+			seed: { moveMailboxId: inbox.id, scope: "standing" },
+		});
+	}
+	const archive = findFolder(folderOptions, "archive");
+	if (archive) {
+		shortcuts.push({
+			id: "file-archive",
+			label: "File in Archive",
+			seed: { moveMailboxId: archive.id },
+		});
+	}
+	const junk = junkMailboxId
+		? folderOptions.find((folder) => folder.id === junkMailboxId)
+		: undefined;
+	if (junk) {
+		shortcuts.push({
+			id: "move-junk",
+			label: `Move to ${junk.label}`,
+			seed: { moveMailboxId: junk.id },
+		});
+	}
+	return shortcuts;
+};
+
+/**
+ * Reads a plain-language instruction into a seed without an NLP endpoint: it
+ * matches the typed words against the account's own folder names and reads an
+ * "always"/"keep" phrasing as the standing scope. Whatever it can't resolve to
+ * a folder still opens the sentence, where the picker is one tap away — never a
+ * dead end.
+ */
+const parseInstruction = (
+	text: string,
+	folderOptions: FolderOption[],
+): OrganizeSeed => {
+	const lower = text.toLowerCase();
+	const folder = folderOptions.find((option) =>
+		lower.includes(option.label.toLowerCase()),
+	);
+	const standing = /\b(always|keep|future|from now)\b/.test(lower);
+	return {
+		moveMailboxId: folder?.id,
+		scope: standing ? "standing" : undefined,
+	};
+};
+
+/**
+ * The "Something else" fallback (issue #211): smart shortcuts plus a
+ * plain-language input, both of which seed the organize sentence's folder and
+ * scope. Presentational — the flow owns the folder data and what a seed does.
+ */
+export function SomethingElsePanel({
+	folderOptions,
+	junkMailboxId,
+	onSeed,
+}: SomethingElsePanelProps) {
+	const [text, setText] = useState("");
+	const shortcuts = useMemo(
+		() => buildShortcuts(folderOptions, junkMailboxId),
+		[folderOptions, junkMailboxId],
+	);
+
+	const submit = () => {
+		const trimmed = text.trim();
+		if (!trimmed) return;
+		onSeed(parseInstruction(trimmed, folderOptions));
+	};
+
+	return (
+		<div className="flex min-h-0 flex-col">
+			<div className="border-b border-line px-5 py-3">
+				<h2 className="text-sm font-semibold text-fg">What should Remit do?</h2>
+				<p className="mt-0.5 text-xs text-fg-muted">
+					Pick a shortcut or say it in your own words.
+				</p>
+			</div>
+
+			<div className="min-h-0 flex-1 space-y-2 overflow-y-auto px-5 py-4">
+				{shortcuts.map((shortcut) => (
+					<Button
+						key={shortcut.id}
+						variant="secondary"
+						onClick={() => onSeed(shortcut.seed)}
+						className="h-12 w-full justify-start px-4"
+					>
+						{shortcut.label}
+					</Button>
+				))}
+			</div>
+
+			<div className="flex items-center gap-2 border-t border-line px-5 py-3">
+				<Input
+					value={text}
+					onChange={(event) => setText(event.target.value)}
+					onKeyDown={(event) => event.key === "Enter" && submit()}
+					placeholder="Tell Remit what to do…"
+					aria-label="Tell Remit what to do"
+					className="flex-1"
+				/>
+				<Button
+					variant="primary"
+					aria-label="Send"
+					onClick={submit}
+					disabled={!text.trim()}
+					icon={<ArrowUp className="size-4" />}
+					className="size-9 shrink-0 px-0"
+				/>
+			</div>
+		</div>
+	);
+}

package/src/components/mail/organize/smart-organize.stories.tsx

@@ -0,0 +1,197 @@
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapMailboxResponse } from "@remit/api-http-client/types.gen.ts";
+import { BottomSheet } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { OrganizePanel } from "./OrganizePanel";
+import type { FolderOption } from "./SomethingElsePanel";
+import { SomethingElsePanel } from "./SomethingElsePanel";
+
+/**
+ * `Flows/Smart Organize` — the guided select-similar → organize flow (issue
+ * #211), rendered from the real web-client components, not a prototype copy:
+ * the same {@link OrganizePanel} the desktop dialog and the mobile sheet use,
+ * and the same {@link SomethingElsePanel} the flow seeds from. The prototype's
+ * interactive `Inbox` / `Walkthrough` stories live alongside these in the
+ * workbench; these show each in-sheet panel in isolation so they can't drift
+ * from what ships.
+ */
+
+const ACCOUNT_ID = "acc-1";
+
+const makeMailbox = (
+	mailboxId: string,
+	fullPath: string,
+): RemitImapMailboxResponse => ({
+	mailboxId,
+	accountId: ACCOUNT_ID,
+	namespaceType: "personal",
+	namespacePrefix: "",
+	hierarchyDelimiter: "/",
+	fullPath,
+	messageCount: 0,
+	unseenCount: 0,
+	deletedCount: 0,
+	lastSyncUid: 0,
+	highWaterMarkUid: 0,
+	lastMessageSyncAt: 0,
+	createdAt: 0,
+	updatedAt: 0,
+});
+
+const MAILBOXES: RemitImapMailboxResponse[] = [
+	makeMailbox("mbx-inbox", "INBOX"),
+	makeMailbox("mbx-archive", "Archive"),
+	makeMailbox("mbx-receipts", "Receipts"),
+	makeMailbox("mbx-travel", "Travel"),
+	makeMailbox("mbx-junk", "Junk"),
+];
+
+const FOLDER_OPTIONS: FolderOption[] = [
+	{ id: "mbx-inbox", label: "Inbox" },
+	{ id: "mbx-archive", label: "Archive" },
+	{ id: "mbx-receipts", label: "Receipts" },
+	{ id: "mbx-junk", label: "Junk" },
+];
+
+/**
+ * A QueryClient pre-seeded with the account's mailboxes, so the sentence's
+ * folder picker renders its real options without a network round-trip.
+ */
+function seededClient(): QueryClient {
+	const client = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	client.setQueryData(
+		mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT_ID } }),
+		{ items: MAILBOXES },
+	);
+	return client;
+}
+
+/** Phone frame + a bottom sheet holding the panel, mirroring the mobile home. */
+function SheetStage({ children }: { children: ReactNode }) {
+	return (
+		<QueryClientProvider client={seededClient()}>
+			<ErrorBannerProvider>
+				<div className="relative mx-auto h-dvh w-full shrink-0 overflow-hidden bg-surface sm:my-6 sm:h-[760px] sm:w-[390px] sm:rounded-[2rem] sm:border sm:border-line sm:shadow-sm">
+					<div className="divide-y divide-line opacity-50">
+						{Array.from({ length: 8 }).map((_, index) => (
+							<div
+								// biome-ignore lint/suspicious/noArrayIndexKey: static backdrop skeleton, no ids
+								key={index}
+								className="flex items-start gap-3 px-row-inset py-2.5"
+							>
+								<div className="mt-0.5 size-7 shrink-0 rounded-full bg-surface-sunken" />
+								<div className="min-w-0 flex-1 space-y-1">
+									<div className="h-2.5 w-1/3 rounded bg-surface-sunken" />
+									<div className="h-2 w-2/3 rounded bg-surface-sunken" />
+								</div>
+							</div>
+						))}
+					</div>
+					<BottomSheet open onClose={() => undefined}>
+						{children}
+					</BottomSheet>
+				</div>
+			</ErrorBannerProvider>
+		</QueryClientProvider>
+	);
+}
+
+const meta: Meta = {
+	title: "Flows/Smart Organize",
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj;
+
+/** The organize sentence on a widened selection — folder picker + four scopes. */
+export const Organize: Story = {
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2", "msg-3"]}
+				anchorMessageId="msg-1"
+				matchedCount={47}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/**
+ * A larger widen — the same sentence over a broad match set, as when the anchor
+ * is a common sender.
+ */
+export const FromSearch: Story = {
+	name: "From Search",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1"]}
+				anchorMessageId="msg-1"
+				matchedCount={412}
+				seedMailboxId="mbx-archive"
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The standing scope pre-selected — the "Always keep…" sentence + filter name. */
+export const AlwaysRule: Story = {
+	name: "Always Rule",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2"]}
+				anchorMessageId="msg-1"
+				matchedCount={47}
+				initialScope="standing"
+				seedMailboxId="mbx-travel"
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The widen matched nothing — the sentence organizes just the selection. */
+export const NoSimilarFound: Story = {
+	name: "No Similar Found",
+	render: () => (
+		<SheetStage>
+			<OrganizePanel
+				accountId={ACCOUNT_ID}
+				mailboxId="mbx-inbox"
+				selectedMessageIds={["msg-1", "msg-2"]}
+				anchorMessageId="msg-1"
+				matchedCount={0}
+				fallback
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** The "Something else" fallback: shortcuts derived from folders + an input. */
+export const SomethingElse: Story = {
+	render: () => (
+		<SheetStage>
+			<SomethingElsePanel
+				folderOptions={FOLDER_OPTIONS}
+				junkMailboxId="mbx-junk"
+				onSeed={() => undefined}
+			/>
+		</SheetStage>
+	),
+};

package/src/hooks/useEscalatedActions.ts

@@ -62,8 +62,8 @@ interface UseEscalatedActionsOptions {
 	mailboxId: string;
 	/** Owning account, forwarded to the unseen-count invalidation on completion. */
 	accountId?: string;
-	/** Disables escalation entirely (e.g. not searching, or desktop — this is a
-	 *  mobile-only affordance). Resets any in-flight phase back to idle. */
+	/** Disables escalation entirely (e.g. not searching). Resets any in-flight
+	 *  phase back to idle. */
 	enabled: boolean;
 	/** Identifies the active predicate; escalation resets to idle whenever this
 	 *  changes (a different search is a different question). */

package/src/lib/organize/mobile-organize-flow.test.ts

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type OrganizeStageInput,
+	resolveOrganizeStage,
+} from "./mobile-organize-flow";
+
+const base: OrganizeStageInput = {
+	entry: "select-similar",
+	hasSeed: true,
+	previewStatus: "idle",
+	matchedCount: undefined,
+};
+
+describe("resolveOrganizeStage — the guided mobile flow's state machine", () => {
+	it("select-similar shows the widening state before the preview resolves", () => {
+		assert.deepEqual(resolveOrganizeStage({ ...base, previewStatus: "idle" }), {
+			kind: "widening",
+		});
+		assert.deepEqual(
+			resolveOrganizeStage({ ...base, previewStatus: "pending" }),
+			{ kind: "widening" },
+		);
+	});
+
+	it("opens the organize sentence on the widened set once the preview matches", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: 47,
+			}),
+			{ kind: "organize", matchedCount: 47, fallback: false },
+		);
+	});
+
+	it("falls back to organizing the selection when the widen matches nothing — no dead end", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: 0,
+			}),
+			{ kind: "organize", matchedCount: 0, fallback: true },
+		);
+		// A success with an undefined count is treated as zero, not a crash.
+		assert.deepEqual(
+			resolveOrganizeStage({
+				...base,
+				previewStatus: "success",
+				matchedCount: undefined,
+			}),
+			{ kind: "organize", matchedCount: 0, fallback: true },
+		);
+	});
+
+	it("surfaces the error branch when the widen fails", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({ ...base, previewStatus: "error" }),
+			{ kind: "error" },
+		);
+	});
+
+	it("something-else shows the shortcuts + input until a seed is chosen", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: false,
+				previewStatus: "success",
+				matchedCount: 47,
+			}),
+			{ kind: "something-else" },
+		);
+	});
+
+	it("something-else widens after the seed, then opens the seeded sentence", () => {
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: true,
+				previewStatus: "pending",
+				matchedCount: undefined,
+			}),
+			{ kind: "widening" },
+		);
+		assert.deepEqual(
+			resolveOrganizeStage({
+				entry: "something-else",
+				hasSeed: true,
+				previewStatus: "success",
+				matchedCount: 12,
+			}),
+			{ kind: "organize", matchedCount: 12, fallback: false },
+		);
+	});
+});

package/src/lib/organize/mobile-organize-flow.ts

@@ -0,0 +1,73 @@
+import type { OrganizeScope } from "./organize-model";
+
+/**
+ * How the guided mobile flow was entered from the selection sheet:
+ *
+ * - `select-similar` — widen straight into the organize sentence.
+ * - `something-else` — collect a folder/scope seed from shortcuts or a
+ *   plain-language input first, then widen into the seeded sentence.
+ */
+export type OrganizeEntry = "select-similar" | "something-else";
+
+/** The read-only widen preview's lifecycle (POST /organize/preview). */
+export type PreviewStatus = "idle" | "pending" | "success" | "error";
+
+/** A folder/scope the "Something else" panel pre-fills the sentence with. */
+export interface OrganizeSeed {
+	moveMailboxId?: string;
+	scope?: OrganizeScope;
+}
+
+/**
+ * The stage the guided flow renders, resolved from the entry, whether a
+ * "Something else" seed has been chosen yet, and where the widen preview is:
+ *
+ * - `something-else` — the shortcuts + input, shown until a seed is picked.
+ * - `widening` — the brief widening state between the tap and the sentence.
+ * - `error` — the widen failed; a dead end only in the sense that it offers a
+ *   close, never a broken sentence.
+ * - `organize` — the committed sentence, on the widened set. `fallback` is true
+ *   when the widen matched nothing, so the sentence organizes just the
+ *   selection instead of a dead end (issue #211).
+ */
+export type OrganizeStage =
+	| { kind: "something-else" }
+	| { kind: "widening" }
+	| { kind: "error" }
+	| { kind: "organize"; matchedCount: number; fallback: boolean };
+
+export interface OrganizeStageInput {
+	entry: OrganizeEntry;
+	/** "Something else" only: whether the user has chosen a seed yet. */
+	hasSeed: boolean;
+	previewStatus: PreviewStatus;
+	/** The widen's matched total; defined once `previewStatus` is `success`. */
+	matchedCount: number | undefined;
+}
+
+/**
+ * The pure state machine behind the guided organize sheet:
+ * `idle → widening → organize` for select-similar, with a `something-else`
+ * seeding step in front for that entry, an `error` branch when the widen
+ * fails, and the zero-match `fallback` that keeps the organize sentence usable
+ * on the selection alone. Kept pure so every transition is testable without a
+ * DOM, React Query, or a network — the component only reads the stage back.
+ */
+export const resolveOrganizeStage = ({
+	entry,
+	hasSeed,
+	previewStatus,
+	matchedCount,
+}: OrganizeStageInput): OrganizeStage => {
+	if (entry === "something-else" && !hasSeed) {
+		return { kind: "something-else" };
+	}
+	if (previewStatus === "error") {
+		return { kind: "error" };
+	}
+	if (previewStatus !== "success") {
+		return { kind: "widening" };
+	}
+	const matched = matchedCount ?? 0;
+	return { kind: "organize", matchedCount: matched, fallback: matched === 0 };
+};