@remit/web-client 0.0.55 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "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/MessageList.selection.test.ts

@@ -70,13 +70,14 @@ describe("MessageList escalated actions", () => {
 	});
 
 	it("keeps mark-read and the move slot on an escalated selection", () => {
+		// The mobile sheet always carries the mark-read verb (it hides it itself
+		// while counting or busy); an escalated selection must never lose it.
+		assert.match(source, /onMarkRead=\{handleMarkAsRead\}/);
+		// The move slot is offered for a bounded selection or an escalated one —
+		// #114's rule that an escalated selection is never delete-only.
 		assert.match(
 			source,
-			/onMarkRead=\{\s*escalation\.phase\.kind === "counting" \? undefined : handleMarkAsRead/,
-		);
-		assert.match(
-			source,
-			/moveSlot=\{\s*escalation\.phase\.kind !== "counting"/,
+			/onMoveMessages \|\| escalation\.phase\.kind === "escalated"/,
 		);
 	});
 

package/src/components/mail/MessageList.tsx

@@ -3,15 +3,17 @@ import {
 	Banner,
 	type Density,
 	MessageListPane,
-	SelectionTopBar,
+	SELECTION_SHEET_TEASER_HEIGHT,
+	SelectionSheet,
 } from "@remit/ui";
 import { useBlocker, useNavigate } from "@tanstack/react-router";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { Search, Sparkles } from "lucide-react";
+import { Search } from "lucide-react";
 import type { RefObject } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ConfirmDialog } from "@/components/ui/ConfirmDialog";
 import { formatErrorMessage } from "@/components/ui/ErrorState";
+import { useJunkMailbox } from "@/hooks/useArchiveMailbox";
 import {
 	type EscalatedAction,
 	type EscalationSearchQuery,
@@ -45,8 +47,13 @@ import {
 	deriveIsMultiSelectMode,
 	shouldExitSelectionOnNavigate,
 } from "@/lib/selection-mode";
+import {
+	resolveSelectionSheetMode,
+	shouldShowSelectionSheet,
+} from "@/lib/selection-sheet-mode";
 import { cn } from "@/lib/utils";
 import { MoveToTrigger } from "./MoveToTrigger";
+import { MobileOrganizeFlow } from "./organize/MobileOrganizeFlow";
 import { OrganizeDialog } from "./organize/OrganizeDialog";
 import { SelectionToolbar } from "./SelectionToolbar";
 import { SwipeableMessageRow } from "./SwipeableMessageRow";
@@ -215,6 +222,12 @@ export const MessageList = ({
 	const navigate = useNavigate();
 	const isDesktop = useIsDesktop();
 	const [organizeOpen, setOrganizeOpen] = useState(false);
+	// Mobile only: which selection-sheet entry opened the guided organize flow
+	// (`null` when closed). Desktop uses `organizeOpen` + `OrganizeDialog`
+	// instead — a sheet is a touch pattern (issue #211).
+	const [mobileOrganizeEntry, setMobileOrganizeEntry] = useState<
+		"select-similar" | "something-else" | null
+	>(null);
 	const isSearching = !!searchQuery?.trim();
 
 	// Roving focus cursor (#429): the keyboard "where am I" pointer, distinct
@@ -244,6 +257,10 @@ export const MessageList = ({
 	// Swipe-to-read toggle hook
 	const { toggleReadFor } = useToggleReadFor({ mailboxId });
 
+	// The Junk quick action moves the selection to the account's appointed Junk
+	// mailbox — the message-flags API has no `$Junk` field, so "junk" is a move.
+	const { junkMailboxId } = useJunkMailbox(accountId);
+
 	// Selection state
 	const {
 		selectedIds,
@@ -265,6 +282,13 @@ export const MessageList = ({
 	// it back to the count, and across that render the two disagree.
 	const isMultiSelectMode = deriveIsMultiSelectMode(selectedCount, isDesktop);
 
+	// When the selection empties — cancel, a completed action, a mailbox switch —
+	// the guided organize entry must reset too, so a later re-selection doesn't
+	// reopen the flow on a stale entry (issue #211).
+	useEffect(() => {
+		if (selectedCount === 0) setMobileOrganizeEntry(null);
+	}, [selectedCount]);
+
 	// 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
@@ -742,6 +766,14 @@ export const MessageList = ({
 		],
 	);
 
+	// Junk quick action (mobile sheet): move the selection to the appointed Junk
+	// mailbox. Reuses the same bounded/escalated move path as any other move, so
+	// the chunked run and the cross-account guard apply unchanged.
+	const handleJunk = useCallback(() => {
+		if (!junkMailboxId) return;
+		handleMoveSelected(junkMailboxId);
+	}, [junkMailboxId, handleMoveSelected]);
+
 	// Cross-account guard: every selected thread row must belong to the
 	// same account as the current mailbox. The list is already scoped to
 	// one mailbox so in practice this is always single-account, but we
@@ -1174,61 +1206,105 @@ export const MessageList = ({
 							? { tone: "warning" as const, text: moveDisabledHint }
 							: undefined;
 
-	// Mobile multi-select bar replaces the pane header during selection mode.
-	const mobileSelectionBar =
-		isMultiSelectMode && !isDesktop ? (
-			<SelectionTopBar
-				count={mobileCount}
-				onCancel={handleMobileCancel}
-				onDelete={handleMobileDelete}
-				onMarkRead={
-					escalation.phase.kind === "counting" ? undefined : handleMarkAsRead
-				}
-				isBusy={mobileIsBusy}
-				isCounting={escalation.phase.kind === "counting"}
-				statusLabel={mobileStatusLabel}
-				selectAll={mobileSelectAll}
-				progress={
-					escalation.runningAction && escalation.progress
-						? {
-								value: escalation.progress.done,
-								max: escalation.progress.total,
-								tone: bulkActionProgressTone(escalation.runningAction.kind),
-							}
-						: undefined
-				}
-				notice={mobileNotice}
-				moveSlot={
-					escalation.phase.kind !== "counting" &&
-					!escalation.isRunning &&
-					(onMoveMessages || escalation.phase.kind === "escalated") &&
-					accountId &&
-					mailboxId ? (
-						<>
-							{escalation.phase.kind === "idle" && !moveDisabledHint && (
-								<button
-									type="button"
-									onClick={() => setOrganizeOpen(true)}
-									className="min-h-11 min-w-11 inline-flex shrink-0 items-center justify-center rounded text-fg-muted hover:bg-surface-raised"
-									aria-label="Organize similar messages"
-								>
-									<Sparkles className="size-4" />
-								</button>
-							)}
-							<MoveToTrigger
-								accountId={accountId}
-								currentMailboxId={mailboxId}
-								onMove={isDeleting || isMoving ? () => {} : handleMoveSelected}
-								disabledHint={moveDisabledHint}
-								label="Move selected messages"
-							/>
-						</>
-					) : undefined
-				}
+	// Mobile: which content the peeking sheet routes to, from the escalation
+	// machinery. `running` (a chunked delete/move/mark-read) and `counting` (a
+	// predicate still paging) replace the idle quick actions with status and
+	// progress; `escalated` keeps the verbs over the whole predicate.
+	const mobileMode = resolveSelectionSheetMode({
+		isRunning: escalation.isRunning,
+		isCounting: escalation.phase.kind === "counting",
+		isEscalated: escalation.phase.kind === "escalated",
+	});
+
+	// The sheet is the sole mobile selection surface. It rises at 2+ selected
+	// (the prototype threshold) or in any non-idle escalation state — a single
+	// selected row enters selection mode without raising it, matching today.
+	const showMobileSheet =
+		!isDesktop &&
+		isMultiSelectMode &&
+		shouldShowSelectionSheet(
+			mobileCount,
+			mobileMode,
+			mobileNotice !== undefined,
+		);
+
+	const mobileMoveSlot =
+		(onMoveMessages || escalation.phase.kind === "escalated") &&
+		accountId &&
+		mailboxId ? (
+			<MoveToTrigger
+				accountId={accountId}
+				currentMailboxId={mailboxId}
+				onMove={isDeleting || isMoving ? () => {} : handleMoveSelected}
+				disabledHint={moveDisabledHint}
+				label="Move selected messages"
 			/>
 		) : undefined;
 
-	const activeSelectionBar = desktopSelectionBar ?? mobileSelectionBar;
+	// The guided organize flow (issue #211) overlays the same positioned pane
+	// ancestor as the sheet, so it is rendered from the sheet slot. The sheet
+	// stays mounted underneath as the flow's dimmed backdrop.
+	const mobileOrganizeFlow =
+		mobileOrganizeEntry && accountId && !isDesktop && selectedCount > 0 ? (
+			<MobileOrganizeFlow
+				entry={mobileOrganizeEntry}
+				accountId={accountId}
+				mailboxId={mailboxId}
+				selectedMessageIds={Array.from(selectedIds)}
+				junkMailboxId={junkMailboxId}
+				onClose={() => {
+					setMobileOrganizeEntry(null);
+					exitSelection();
+				}}
+			/>
+		) : undefined;
+
+	const mobileSelectionSheet = showMobileSheet ? (
+		<SelectionSheet
+			count={mobileCount}
+			mode={mobileMode}
+			onCancel={handleMobileCancel}
+			onDelete={handleMobileDelete}
+			onJunk={
+				junkMailboxId && junkMailboxId !== mailboxId && !moveDisabledHint
+					? handleJunk
+					: undefined
+			}
+			onMarkRead={handleMarkAsRead}
+			onSelectSimilar={
+				accountId ? () => setMobileOrganizeEntry("select-similar") : undefined
+			}
+			onSomethingElse={
+				accountId ? () => setMobileOrganizeEntry("something-else") : undefined
+			}
+			moveSlot={mobileMoveSlot}
+			isBusy={mobileIsBusy}
+			selectAll={mobileSelectAll}
+			statusLabel={mobileStatusLabel}
+			progress={
+				escalation.runningAction && escalation.progress
+					? {
+							value: escalation.progress.done,
+							max: escalation.progress.total,
+							tone: bulkActionProgressTone(escalation.runningAction.kind),
+						}
+					: undefined
+			}
+			notice={mobileNotice}
+		/>
+	) : undefined;
+
+	// Both mobile overlays share the pane's positioned ancestor via the sheet
+	// slot: the peeking sheet, and the guided organize flow above it.
+	const mobileSelectionSurface =
+		mobileSelectionSheet || mobileOrganizeFlow ? (
+			<>
+				{mobileSelectionSheet}
+				{mobileOrganizeFlow}
+			</>
+		) : undefined;
+
+	const activeSelectionBar = desktopSelectionBar;
 
 	// Roving tabindex: exactly one row is in the tab order, so Tab moves focus
 	// into the list at the cursor and Shift+Tab moves back out to the side panel
@@ -1257,6 +1333,13 @@ export const MessageList = ({
 				aria-multiselectable
 				aria-label={listTitle}
 				className="flex-1 overflow-y-auto"
+				// Pad the list so its last rows clear the peeking teaser (~56px)
+				// rather than hiding behind it.
+				style={
+					showMobileSheet
+						? { paddingBottom: SELECTION_SHEET_TEASER_HEIGHT }
+						: undefined
+				}
 			>
 				{/* Virtualizer scaffolding — presentational so the listbox sees the
 				    rows as its options rather than these positioning wrappers. */}
@@ -1364,6 +1447,7 @@ export const MessageList = ({
 				isDesktop={isDesktop}
 				hideHeader={hideHeader}
 				selectionBar={activeSelectionBar}
+				selectionSheet={mobileSelectionSurface}
 				listBody={listState === "ready" ? virtualBody : undefined}
 			/>
 			<ConfirmDialog

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

@@ -0,0 +1,45 @@
+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",
+					mailboxId: "mbx-inbox",
+					selectedMessageIds: ["msg-1", "msg-2"],
+					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

@@ -0,0 +1,138 @@
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { BottomSheet, Button } from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { Loader2 } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { useOrganizePreview } from "@/hooks/useOrganizePreview";
+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 { OrganizePanel } from "./OrganizePanel";
+import { SomethingElsePanel } from "./SomethingElsePanel";
+
+interface MobileOrganizeFlowProps {
+	entry: OrganizeEntry;
+	accountId: string;
+	mailboxId: string;
+	selectedMessageIds: 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,
+	mailboxId,
+	selectedMessageIds,
+	junkMailboxId,
+	onClose,
+}: MobileOrganizeFlowProps) {
+	const anchorMessageId = selectedMessageIds[0];
+	const [seed, setSeed] = useState<OrganizeSeed | undefined>();
+
+	const { preview, matchedCount, isPending, isError, error } =
+		useOrganizePreview(accountId);
+
+	useEffect(() => {
+		if (!anchorMessageId) return;
+		preview({ anchorMessageId, matchOperator: "And", literalClauses: [] });
+	}, [anchorMessageId, 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" && (
+				<OrganizePanel
+					accountId={accountId}
+					mailboxId={mailboxId}
+					selectedMessageIds={selectedMessageIds}
+					anchorMessageId={anchorMessageId}
+					matchedCount={stage.matchedCount}
+					initialScope={seed?.scope}
+					seedMailboxId={seed?.moveMailboxId}
+					fallback={stage.fallback}
+					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/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/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 };
+};

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

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	resolveSelectionSheetMode,
+	SELECTION_SHEET_MIN_COUNT,
+	shouldShowSelectionSheet,
+} from "./selection-sheet-mode";
+
+describe("resolveSelectionSheetMode", () => {
+	test("is idle for a plain bounded selection", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: false,
+				isCounting: false,
+				isEscalated: false,
+			}),
+			"idle",
+		);
+	});
+
+	test("is escalated once the selection is the search predicate", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: false,
+				isCounting: false,
+				isEscalated: true,
+			}),
+			"escalated",
+		);
+	});
+
+	test("is counting while the predicate is still paging to a total", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: false,
+				isCounting: true,
+				isEscalated: false,
+			}),
+			"counting",
+		);
+	});
+
+	test("running wins over escalated — a chunked run is both", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: true,
+				isCounting: false,
+				isEscalated: true,
+			}),
+			"running",
+		);
+	});
+
+	test("running wins over counting", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: true,
+				isCounting: true,
+				isEscalated: false,
+			}),
+			"running",
+		);
+	});
+
+	test("counting wins over escalated", () => {
+		assert.equal(
+			resolveSelectionSheetMode({
+				isRunning: false,
+				isCounting: true,
+				isEscalated: true,
+			}),
+			"counting",
+		);
+	});
+});
+
+describe("shouldShowSelectionSheet", () => {
+	test("hides at a single selected row while idle", () => {
+		assert.equal(shouldShowSelectionSheet(1, "idle"), false);
+	});
+
+	test("shows at the two-row threshold", () => {
+		assert.equal(
+			shouldShowSelectionSheet(SELECTION_SHEET_MIN_COUNT, "idle"),
+			true,
+		);
+	});
+
+	test("shows for any non-idle state even below the threshold", () => {
+		assert.equal(shouldShowSelectionSheet(0, "counting"), true);
+		assert.equal(shouldShowSelectionSheet(1, "running"), true);
+		assert.equal(shouldShowSelectionSheet(0, "escalated"), true);
+	});
+
+	test("shows a pending notice at a single idle row so it is never dropped", () => {
+		// A bulk delete that leaves one message behind returns to idle at count 1
+		// with a "1 couldn't be deleted / Retry" notice; the escalation offer can
+		// likewise sit at one loaded row. The sheet must mount to surface either.
+		assert.equal(shouldShowSelectionSheet(1, "idle", true), true);
+	});
+
+	test("still hides a single idle row with no notice", () => {
+		assert.equal(shouldShowSelectionSheet(1, "idle", false), false);
+	});
+});

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

@@ -0,0 +1,49 @@
+import type { SelectionSheetMode } from "@remit/ui";
+
+/**
+ * Routes the mobile selection sheet to one of its four content states from the
+ * escalation machinery's flags. Pure so the routing — which is what decides
+ * whether the sheet shows idle quick actions or the counting / running /
+ * escalated status — is testable without the sheet or a DOM.
+ *
+ * Precedence, highest first:
+ * 1. `running` — a chunked delete/move/mark-read is in flight; progress owns
+ *    the sheet even over an escalated selection (an escalated run is both).
+ * 2. `counting` — a search predicate is still paging to its total.
+ * 3. `escalated` — the selection is the search predicate, not a loaded id set.
+ * 4. `idle` — a bounded selection with the quick actions and smart-flow rows.
+ */
+export const resolveSelectionSheetMode = (input: {
+	isRunning: boolean;
+	isCounting: boolean;
+	isEscalated: boolean;
+}): SelectionSheetMode => {
+	if (input.isRunning) return "running";
+	if (input.isCounting) return "counting";
+	if (input.isEscalated) return "escalated";
+	return "idle";
+};
+
+/**
+ * The count threshold the peeking teaser rises at — two or more selected, the
+ * prototype's threshold. Below it selection mode is still entered (rows show
+ * their checkboxes) but no sheet appears, matching today's single-select
+ * behaviour of leaving the list chrome alone.
+ */
+export const SELECTION_SHEET_MIN_COUNT = 2;
+
+/**
+ * Whether the mobile sheet should be mounted: two or more rows selected, or any
+ * non-idle escalation state (counting, running, escalated), or a pending notice
+ * that has to be surfaced. The last case is why a single-row selection can still
+ * raise the sheet — a bulk run that leaves exactly one message behind returns to
+ * idle at count 1 with a "1 couldn't be deleted / Retry" notice, and a search
+ * with one loaded row plus more matches carries the escalation offer at count 1.
+ * Suppressing the sheet there would drop the notice with no way to retry.
+ */
+export const shouldShowSelectionSheet = (
+	count: number,
+	mode: SelectionSheetMode,
+	hasNotice = false,
+): boolean =>
+	count >= SELECTION_SHEET_MIN_COUNT || mode !== "idle" || hasNotice;