@remit/web-client 0.0.100 → 0.0.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.100",
+  "version": "0.0.102",
   "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/MoveToTrigger.render.test.ts

@@ -1,7 +1,8 @@
 /**
  * The move-to-folder picker. It only fetches folders once it is opened, it
- * marks the folder the messages are already in rather than offering it as a
- * destination, and on desktop Escape or a click outside puts it away.
+ * opens on the account's top level with nested folders behind the one holding
+ * them, it marks the folder the messages are already in rather than offering it
+ * as a destination, and on desktop Escape or a click outside puts it away.
  */
 
 import assert from "node:assert/strict";
@@ -54,19 +55,23 @@ const mount = (
 const FOLDERS = [
 	makeMailbox({ mailboxId: "mbx-inbox", fullPath: "INBOX" }),
 	makeMailbox({ mailboxId: "mbx-work", fullPath: "Work" }),
+	makeMailbox({ mailboxId: "mbx-clients", fullPath: "Work/Clients" }),
 	makeMailbox({ mailboxId: "mbx-receipts", fullPath: "Receipts" }),
 ];
 
+const rowText = (dom: DomHarness): string[] =>
+	dom.queryAll("[role=treeitem]").map((row) => row.textContent ?? "");
+
 describe("MoveToTrigger", () => {
 	it("reports itself as collapsed until it is opened", () => {
 		const dom = mount({ mailboxes: FOLDERS });
 		const trigger = dom.byLabel("Move to folder");
 		assert.equal(trigger.getAttribute("aria-expanded"), "false");
 		assert.equal(trigger.getAttribute("aria-controls"), null);
-		assert.equal(dom.query('[role="listbox"], input'), null);
+		assert.equal(dom.query('[role="tree"], input'), null);
 	});
 
-	it("opens a listbox of destinations and marks the folder we are in", () => {
+	it("opens the top level and marks the folder we are in", () => {
 		const dom = mount({ mailboxes: FOLDERS });
 		dom.click(dom.byLabel("Move to folder"));
 
@@ -74,9 +79,7 @@ describe("MoveToTrigger", () => {
 			dom.byLabel("Move to folder").getAttribute("aria-expanded"),
 			"true",
 		);
-		const labels = dom
-			.queryAll("[role=option]")
-			.map((option) => option.textContent ?? "");
+		const labels = rowText(dom);
 		assert.ok(labels.some((label) => label.includes("Work")));
 		assert.ok(labels.some((label) => label.includes("Receipts")));
 
@@ -86,15 +89,32 @@ describe("MoveToTrigger", () => {
 		assert.ok(current, "the source folder is marked as the current one");
 	});
 
-	it("moves to the folder the user picks and closes itself", () => {
+	it("keeps a nested folder behind the folder that holds it", () => {
+		const dom = mount({ mailboxes: FOLDERS });
+		dom.click(dom.byLabel("Move to folder"));
+		assert.equal(
+			rowText(dom).some((label) => label.includes("Clients")),
+			false,
+		);
+
+		dom.click(dom.byLabel("Move to Work"));
+		assert.ok(rowText(dom).some((label) => label.includes("Clients")));
+	});
+
+	it("waits for the move to be confirmed, then closes itself", () => {
 		const moved: string[] = [];
 		const dom = mount({
 			mailboxes: FOLDERS,
 			onMove: (id) => moved.push(id),
 		});
 		dom.click(dom.byLabel("Move to folder"));
-		dom.click(dom.byText("[role=option]", "Work"));
 
+		// Picking a folder also opens it, so the move is a separate press —
+		// otherwise the first tap would fire before anything nested was reachable.
+		dom.click(dom.byLabel("Move to Work"));
+		assert.deepEqual(moved, []);
+
+		dom.click(dom.byText("button", "Move to Work"));
 		assert.deepEqual(moved, ["mbx-work"]);
 		assert.equal(
 			dom.byLabel("Move to folder").getAttribute("aria-expanded"),
@@ -102,6 +122,15 @@ describe("MoveToTrigger", () => {
 		);
 	});
 
+	it("names the destination on the button that runs the move", () => {
+		const dom = mount({ mailboxes: FOLDERS });
+		dom.click(dom.byLabel("Move to folder"));
+		dom.click(dom.byLabel("Move to Work"));
+		dom.click(dom.byLabel("Move to Clients"));
+
+		assert.match(dom.text(), /Move to Clients/);
+	});
+
 	it("closes on Escape and on a click outside it", () => {
 		const dom = mount({ mailboxes: FOLDERS });
 		const isOpen = () =>
@@ -144,7 +173,7 @@ describe("MoveToTrigger", () => {
 
 	it("asks for the folder list only once the picker is opened", () => {
 		const dom = mount();
-		assert.equal(dom.queryAll("[role=option]").length, 0);
+		assert.equal(dom.queryAll("[role=treeitem]").length, 0);
 		dom.click(dom.byLabel("Move to folder"));
 		// No cached mailboxes and no network in the test harness: the picker
 		// shows its loading state rather than an empty list of destinations.

package/src/components/mail/MoveToTrigger.tsx

@@ -1,5 +1,5 @@
 import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { type MoveMailboxOption, MoveMailboxPicker } from "@remit/ui";
+import { Button, type FolderTreeNode, FolderTreePicker } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { FolderInput } from "lucide-react";
 import {
@@ -17,7 +17,7 @@ import { useFolderAppointments } from "@/hooks/useArchiveMailbox";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
-import { buildMoveOptions } from "@/lib/move-options";
+import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
 import { cn } from "@/lib/utils";
 
 interface MoveToTriggerProps {
@@ -66,6 +66,7 @@ export const MoveToTrigger = ({
 	label,
 }: MoveToTriggerProps) => {
 	const [isOpen, setIsOpen] = useState(false);
+	const [pickedId, setPickedId] = useState<string>();
 	const isDesktop = useIsDesktop();
 	const containerRef = useRef<HTMLDivElement>(null);
 	const triggerLabel = label ?? "Move to folder";
@@ -88,9 +89,9 @@ export const MoveToTrigger = ({
 		enabled: isOpen,
 	});
 	const folderAppointments = useFolderAppointments(accountId);
-	const { createFolder } = useCreateMailbox(accountId);
+	const { createFolderIn } = useCreateMailbox(accountId);
 
-	const options = useMemo<MoveMailboxOption[]>(
+	const options = useMemo<FolderTreeNode[]>(
 		() =>
 			buildMoveOptions({
 				mailboxes: mailboxesResponse?.items ?? [],
@@ -105,22 +106,23 @@ export const MoveToTrigger = ({
 			translator,
 		],
 	);
+	const delimiter = folderDelimiter(mailboxesResponse?.items ?? []);
 
-	const handleSelect = useCallback(
-		(destinationMailboxId: string) => {
-			setIsOpen(false);
-			onMove(destinationMailboxId);
-		},
-		[onMove],
-	);
+	const picked = options.find((option) => option.id === pickedId);
 
-	const handleCreateFolder = useCallback(
-		async (name: string, signal?: AbortSignal): Promise<MoveMailboxOption> => {
-			const folder = await createFolder(name, signal);
-			return { id: folder.id, label: folder.label };
-		},
-		[createFolder],
-	);
+	const close = useCallback(() => {
+		setIsOpen(false);
+		setPickedId(undefined);
+	}, []);
+
+	// Tapping a folder both picks it and opens it, so the move waits for a
+	// confirmation — otherwise the first tap would fire before the user could
+	// reach anything nested inside it.
+	const handleMove = useCallback(() => {
+		if (!picked) return;
+		close();
+		onMove(picked.id);
+	}, [picked, close, onMove]);
 
 	// Desktop popover: dismiss on outside click + Escape.
 	useEffect(() => {
@@ -130,11 +132,11 @@ export const MoveToTrigger = ({
 				containerRef.current &&
 				!containerRef.current.contains(event.target as Node)
 			) {
-				setIsOpen(false);
+				close();
 			}
 		};
 		const handleKey = (event: KeyboardEvent) => {
-			if (event.key === "Escape") setIsOpen(false);
+			if (event.key === "Escape") close();
 		};
 		document.addEventListener("mousedown", handlePointer);
 		document.addEventListener("keydown", handleKey);
@@ -142,7 +144,7 @@ export const MoveToTrigger = ({
 			document.removeEventListener("mousedown", handlePointer);
 			document.removeEventListener("keydown", handleKey);
 		};
-	}, [isOpen, isDesktop]);
+	}, [isOpen, isDesktop, close]);
 
 	const isTriggerDisabled = disabled || !!disabledHint;
 
@@ -156,10 +158,10 @@ export const MoveToTrigger = ({
 			}}
 			aria-label={triggerLabel}
 			// Mobile opens a vaul Drawer (modal dialog), desktop opens a
-			// non-modal popover whose only content is the listbox of
-			// destinations. Reflect each surface accurately so screen readers
-			// announce the right structure.
-			aria-haspopup={isDesktop ? "listbox" : "dialog"}
+			// non-modal popover whose only content is the folder tree. Reflect
+			// each surface accurately so screen readers announce the right
+			// structure.
+			aria-haspopup={isDesktop ? "tree" : "dialog"}
 			aria-expanded={isOpen}
 			aria-controls={isOpen ? popoverId : undefined}
 			title={disabledHint}
@@ -182,33 +184,44 @@ export const MoveToTrigger = ({
 			/>
 		</div>
 	) : (
-		<MoveMailboxPicker
-			mailboxes={options}
-			onSelect={handleSelect}
-			onCreateFolder={handleCreateFolder}
-			onCancel={() => setIsOpen(false)}
-			autoFocus={!isDesktop}
+		<FolderTreePicker
+			folders={options}
+			selectedId={pickedId}
+			delimiter={delimiter}
+			onSelect={setPickedId}
+			onCreateFolder={createFolderIn}
+			onCancel={close}
 			labels={{
-				createLabel: (folderName) => `Create "${folderName}"`,
-				searchPlaceholder: t("move_picker_placeholder", {
-					defaultValue: "Move to…",
+				filterPlaceholder: t("move_picker_filter_placeholder", {
+					defaultValue: "Filter folders…",
 				}),
-				searchAriaLabel: t("move_picker_filter_label", {
+				filterAriaLabel: t("move_picker_filter_label", {
 					defaultValue: "Filter folders",
 				}),
-				optionLabel: (folderLabel) => `Move to ${folderLabel}`,
-				currentSuffix: "(current folder)",
-				currentTag: "current",
-				emptyMessage: (query) => `No folders match "${query}"`,
 			}}
 		/>
 	);
 
+	const confirmBar = picked && (
+		<div className="shrink-0 border-t border-line p-2">
+			<Button
+				variant="primary"
+				onClick={handleMove}
+				className="h-11 w-full font-semibold"
+			>
+				{`Move to ${picked.label}`}
+			</Button>
+		</div>
+	);
+
 	if (!isDesktop) {
 		return (
 			<>
 				{TriggerButton}
-				<Drawer.Root open={isOpen} onOpenChange={setIsOpen}>
+				<Drawer.Root
+					open={isOpen}
+					onOpenChange={(next) => (next ? setIsOpen(true) : close())}
+				>
 					<Drawer.Portal>
 						<Drawer.Overlay className="fixed inset-0 z-40 bg-black/40" />
 						<Drawer.Content
@@ -220,7 +233,10 @@ export const MoveToTrigger = ({
 							<Drawer.Title className="px-4 py-2 text-base font-semibold border-b border-line">
 								Move to folder
 							</Drawer.Title>
-							<div className="flex-1 overflow-hidden">{pickerBody}</div>
+							<div className="flex min-h-0 flex-1 overflow-hidden">
+								{pickerBody}
+							</div>
+							{confirmBar}
 						</Drawer.Content>
 					</Drawer.Portal>
 				</Drawer.Root>
@@ -240,6 +256,7 @@ export const MoveToTrigger = ({
 					)}
 				>
 					{pickerBody}
+					{confirmBar}
 				</div>
 			)}
 		</div>

package/src/components/mail/SelectionWizardHost.tsx

@@ -7,10 +7,10 @@ import {
 	derivePropertyClauses,
 	deriveSenderClauses,
 	dominantSender,
+	type FolderTreeNode,
 	type MatchCount,
 	type MatchDoor,
 	type MatchMode,
-	type MoveMailboxOption,
 	type RuleClause,
 	type RunState,
 	type SearchConversion,
@@ -50,7 +50,7 @@ import { useSelectedSubjects } from "@/hooks/useSelectedSubjects";
 import type { BulkActionProgress, BulkRunOutcome } from "@/lib/bulk-actions";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
-import { buildMoveOptions } from "@/lib/move-options";
+import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
 import {
 	buildWizardDraft,
 	canBackApplyDraft,
@@ -388,7 +388,7 @@ function SelectionWizardSession({
 	});
 	const folderAppointments = useFolderAppointments(accountId);
 	const translator = useFolderLabelTranslator();
-	const mailboxes = useMemo<MoveMailboxOption[]>(
+	const mailboxes = useMemo<FolderTreeNode[]>(
 		() =>
 			buildMoveOptions({
 				mailboxes: mailboxesData?.items ?? [],
@@ -398,7 +398,7 @@ function SelectionWizardSession({
 			}),
 		[mailboxesData?.items, folderAppointments, mailboxId, translator],
 	);
-	const { createFolder } = useCreateMailbox(accountId);
+	const { createFolderIn } = useCreateMailbox(accountId);
 
 	const folderLabel = mailboxes.find(
 		(mailbox) => mailbox.id === draft.moveMailboxId,
@@ -946,11 +946,12 @@ function SelectionWizardSession({
 				sample: { ...sample, label: "What this matches" },
 			}}
 			folder={{
-				mailboxes,
+				folders: mailboxes,
 				mailboxId: named.moveMailboxId,
+				delimiter: folderDelimiter(mailboxesData?.items ?? []),
 				onSelect: (moveMailboxId) =>
 					setDraft((held) => ({ ...held, moveMailboxId })),
-				onCreateFolder: accountId ? createFolder : undefined,
+				onCreateFolder: accountId ? createFolderIn : undefined,
 				restriction: folderRestriction,
 			}}
 			rule={{

package/src/components/mail/SpamRescue.tsx

@@ -1,6 +1,6 @@
 import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import {
-	type MoveMailboxOption,
+	type FolderTreeNode,
 	RescueBanner,
 	type RescueCandidate,
 	RescueFromSpamFlow,
@@ -19,7 +19,7 @@ import {
 	useInboxMailbox,
 } from "@/hooks/useArchiveMailbox";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
-import { buildMoveOptions } from "@/lib/move-options";
+import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
 import {
 	recordRescueCandidatesSurfaced,
 	recordRescueCommitted,
@@ -60,7 +60,7 @@ export function SpamRescue({
 		staleTime: Infinity,
 	});
 
-	const folders = useMemo<MoveMailboxOption[]>(
+	const folders = useMemo<FolderTreeNode[]>(
 		() =>
 			buildMoveOptions({
 				mailboxes: mailboxesResponse?.items ?? [],
@@ -117,6 +117,7 @@ export function SpamRescue({
 				candidates={candidates}
 				defaultDestinationId={defaultDestinationId}
 				availableFolders={folders}
+				delimiter={folderDelimiter(mailboxesResponse?.items ?? [])}
 				onConfirmMove={handleConfirmMove}
 				onCancel={() => setOpen(false)}
 			/>

package/src/components/settings/DeleteFolderDialog.render.test.ts

@@ -5,8 +5,10 @@ import type {
 	RemitImapMailboxResponse,
 } from "@remit/api-http-client/types.gen.ts";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import i18next from "i18next";
 import React, { act, createElement } from "react";
 import { createRoot, type Root } from "react-dom/client";
+import { I18nextProvider, initReactI18next } from "react-i18next";
 import { DeleteFolderDialog } from "./DeleteFolderDialog";
 
 // remit-ui's `.tsx` is transpiled with the classic JSX runtime, which
@@ -48,6 +50,18 @@ const appointments: RemitImapFolderAppointment[] = [
 	{ role: "Archive", mailboxId: "archive" },
 ];
 
+// The role labels the app resolves through i18n, so a folder appointed to a
+// role reads as that role rather than as the provider's own leaf.
+const i18n = i18next.createInstance();
+i18n.use(initReactI18next).init({
+	lng: "en",
+	ns: ["mail"],
+	defaultNS: "mail",
+	resources: {
+		en: { mail: { sidebar: { trash: "Trash", archive: "Archive" } } },
+	},
+});
+
 let container: HTMLElement;
 let root: Root;
 const originalFetch = globalThis.fetch;
@@ -98,20 +112,26 @@ const render = (props: {
 	open: boolean;
 	folder: RemitImapMailboxResponse;
 	onClose?: () => void;
+	folderAppointments?: RemitImapFolderAppointment[];
+	allMailboxes?: RemitImapMailboxResponse[];
 }) => {
 	act(() => {
 		root.render(
 			createElement(
-				QueryClientProvider,
-				{ client: new QueryClient() },
-				createElement(DeleteFolderDialog, {
-					open: props.open,
-					accountId: "acc-1",
-					folder: props.folder,
-					mailboxes,
-					appointments,
-					onClose: props.onClose ?? (() => undefined),
-				}),
+				I18nextProvider,
+				{ i18n },
+				createElement(
+					QueryClientProvider,
+					{ client: new QueryClient() },
+					createElement(DeleteFolderDialog, {
+						open: props.open,
+						accountId: "acc-1",
+						folder: props.folder,
+						mailboxes: props.allMailboxes ?? mailboxes,
+						appointments: props.folderAppointments ?? appointments,
+						onClose: props.onClose ?? (() => undefined),
+					}),
+				),
 			) as never,
 		);
 	});
@@ -158,6 +178,24 @@ describe("DeleteFolderDialog", () => {
 		assert.match(container.textContent ?? "", /What should happen to them/);
 	});
 
+	it("names the folder by its role, never by the provider's leaf", () => {
+		const trash = mailbox({
+			mailboxId: "trash",
+			fullPath: "Deleted Messages",
+		});
+		render({
+			open: true,
+			folder: trash,
+			allMailboxes: [...mailboxes, trash],
+			folderAppointments: [
+				...appointments,
+				{ role: "Trash", mailboxId: "trash" },
+			],
+		});
+		assert.match(container.textContent ?? "", /Delete Trash/);
+		assert.doesNotMatch(container.textContent ?? "", /Deleted Messages/);
+	});
+
 	it("offers a destination picker that excludes the folder being deleted", () => {
 		render({ open: true, folder: mailboxes[1] as RemitImapMailboxResponse });
 		act(() => buttonByText(/Move them to another folder/)?.click());
@@ -165,7 +203,7 @@ describe("DeleteFolderDialog", () => {
 			'input[aria-label="Filter folders"]',
 		);
 		assert.ok(search, "the move picker is shown");
-		const options = Array.from(container.querySelectorAll('[role="option"]'))
+		const options = Array.from(container.querySelectorAll('[role="treeitem"]'))
 			.map((o) => o.textContent ?? "")
 			.join("|");
 		assert.doesNotMatch(options, /Receipts/);

package/src/components/settings/DeleteFolderDialog.tsx

@@ -6,8 +6,8 @@ import {
 	Banner,
 	Button,
 	Dialog,
-	type MoveMailboxOption,
-	MoveMailboxPicker,
+	type FolderTreeNode,
+	FolderTreePicker,
 } from "@remit/ui";
 import { AlertTriangle, FolderInput, Loader2, Trash2, X } from "lucide-react";
 import { useCallback, useEffect, useMemo, useState } from "react";
@@ -15,7 +15,7 @@ import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useDeleteFolder } from "@/hooks/useDeleteFolder";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { initialStage, moveProgressLabel } from "@/lib/delete-folder";
-import { getMailboxDisplayName } from "@/lib/folder-roles";
+import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
 import { buildMoveOptions } from "@/lib/move-options";
 
 interface DeleteFolderDialogProps {
@@ -33,9 +33,6 @@ type FateStage =
 	| "confirm-delete-all"
 	| "pick-destination";
 
-const folderLabel = (folder: RemitImapMailboxResponse): string =>
-	folder.displayNameOverride?.trim() || getMailboxDisplayName(folder.fullPath);
-
 const emailCount = (count: number): string =>
 	`${count} ${count === 1 ? "email" : "emails"}`;
 
@@ -57,7 +54,7 @@ export function DeleteFolderDialog({
 	const [stage, setStage] = useState<FateStage>(() =>
 		initialStage(folder.messageCount),
 	);
-	const { createFolder } = useCreateMailbox(accountId);
+	const { createFolderIn } = useCreateMailbox(accountId);
 	const translator = useFolderLabelTranslator();
 	const {
 		phase,
@@ -86,7 +83,7 @@ export function DeleteFolderDialog({
 		onClose();
 	}, [cancel, onClose]);
 
-	const destinations = useMemo<MoveMailboxOption[]>(
+	const destinations = useMemo<FolderTreeNode[]>(
 		() =>
 			buildMoveOptions({
 				mailboxes,
@@ -97,17 +94,18 @@ export function DeleteFolderDialog({
 		[mailboxes, appointments, folder.mailboxId, translator],
 	);
 
-	const handleCreateFolder = async (
-		name: string,
-		signal?: AbortSignal,
-	): Promise<MoveMailboxOption> => {
-		const created = await createFolder(name, signal);
-		return { id: created.id, label: created.label };
-	};
+	const name = useMemo(
+		() =>
+			labelForMailbox(
+				folder,
+				buildMailboxRoleMap(appointments).get(folder.mailboxId),
+				translator,
+			),
+		[folder, appointments, translator],
+	);
 
 	if (!open) return null;
 
-	const name = folderLabel(folder);
 	const title = `Delete ${name}`;
 
 	const body = (() => {
@@ -262,24 +260,21 @@ export function DeleteFolderDialog({
 		}
 
 		return (
-			<div className="flex h-80 flex-col">
+			<div className="flex h-[26rem] flex-col">
 				<p className="px-5 pt-4 text-sm text-fg-muted">
 					Move the {emailCount(folder.messageCount)} in{" "}
 					<strong className="text-fg">{name}</strong> to:
 				</p>
-				<div className="min-h-0 flex-1 px-2 py-2">
-					<MoveMailboxPicker
-						mailboxes={destinations}
+				<div className="min-h-0 flex-1">
+					<FolderTreePicker
+						folders={destinations}
+						delimiter={mailboxes[0]?.hierarchyDelimiter ?? "/"}
 						onSelect={(destinationMailboxId) =>
 							moveThenDelete(destinationMailboxId)
 						}
-						onCreateFolder={handleCreateFolder}
+						onCreateFolder={createFolderIn}
 						onCancel={() => setStage("choose-fate")}
-						labels={{
-							searchPlaceholder: "Move emails to…",
-							optionLabel: (label) => `Move to ${label}`,
-							createLabel: (query) => `Create "${query}"`,
-						}}
+						labels={{ filterPlaceholder: "Move emails to…" }}
 					/>
 				</div>
 			</div>

package/src/hooks/useCreateMailbox.ts

@@ -3,12 +3,16 @@ import {
 	mailboxOperationsListMailboxesOptions,
 	mailboxOperationsListMailboxesQueryKey,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { FolderOption } from "@remit/ui";
+import type { FolderTreeNode } from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useRef } from "react";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
 import { waitForMailboxSynced } from "@/lib/mailbox-sync-wait";
-import { composeFolderPath, validateNewFolderName } from "@/lib/new-folder";
+import {
+	composeFolderPath,
+	type FolderTarget,
+	validateNewFolderName,
+} from "@/lib/new-folder";
 
 /**
  * Creates a mailbox for an account and refreshes the folder list on success.
@@ -37,8 +41,12 @@ import { composeFolderPath, validateNewFolderName } from "@/lib/new-folder";
  * `createFolder` takes an `AbortSignal` the surface aborts on unmount/cancel/
  * close, so a folder that confirms after the surface is gone resolves nothing.
  *
+ * `createFolderIn` is the same seam for a folder made inside another one: the
+ * parent is named by its provider path, and the name is joined to it with that
+ * parent's own hierarchy delimiter. `createFolder` is it with no parent.
+ *
  * `mutation` is exposed for callers that drive their own form state and want the
- * optimistic, non-waiting create (the standalone settings create).
+ * optimistic, non-waiting create.
  */
 export function useCreateMailbox(accountId: string | undefined) {
 	const queryClient = useQueryClient();
@@ -69,21 +77,41 @@ export function useCreateMailbox(accountId: string | undefined) {
 	// resumes the wait on it instead of re-creating. Cleared once it confirms.
 	const pendingByPath = useRef(new Map<string, string>());
 
-	const createFolder = useCallback(
-		async (name: string, signal?: AbortSignal): Promise<FolderOption> => {
+	const createFolderIn = useCallback(
+		async (
+			name: string,
+			parentPath: string,
+			signal?: AbortSignal,
+		): Promise<FolderTreeNode> => {
 			if (!accountId) {
 				throw new Error(
 					"No account to create the folder in. Pick messages from a single account first.",
 				);
 			}
-			const fullPath = composeFolderPath(name);
+			const items = data?.items ?? [];
+			const parentMailbox = parentPath
+				? items.find((item) => item.fullPath === parentPath)
+				: undefined;
+			if (parentPath && !parentMailbox) {
+				throw new Error(
+					`Couldn't find the folder "${parentPath}" to create this one inside.`,
+				);
+			}
+			const parent: FolderTarget | undefined = parentMailbox
+				? {
+						fullPath: parentMailbox.fullPath,
+						hierarchyDelimiter: parentMailbox.hierarchyDelimiter,
+					}
+				: undefined;
+			const fullPath = composeFolderPath(name, parent);
 			let mailboxId = pendingByPath.current.get(fullPath);
 			if (!mailboxId) {
-				const items = data?.items ?? [];
-				const delimiter = items[0]?.hierarchyDelimiter ?? "/";
+				const delimiter =
+					parent?.hierarchyDelimiter ?? items[0]?.hierarchyDelimiter ?? "/";
 				const problem = validateNewFolderName({
 					name,
 					delimiter,
+					parent,
 					existingPaths: items.map((item) => item.fullPath),
 				});
 				if (problem) throw new Error(problem);
@@ -109,10 +137,17 @@ export function useCreateMailbox(accountId: string | undefined) {
 			return {
 				id: confirmed.mailboxId,
 				label: getMailboxDisplayName(confirmed.fullPath),
+				path: confirmed.fullPath,
 			};
 		},
 		[mutation, accountId, data, queryClient],
 	);
 
-	return { createFolder, mutation };
+	const createFolder = useCallback(
+		(name: string, signal?: AbortSignal): Promise<FolderTreeNode> =>
+			createFolderIn(name, "", signal),
+		[createFolderIn],
+	);
+
+	return { createFolder, createFolderIn, mutation };
 }

package/src/lib/move-options.test.ts

@@ -6,7 +6,7 @@ import type {
 	RemitImapFolderAppointment,
 	RemitImapMailboxResponse,
 } from "@remit/api-http-client/types.gen.ts";
-import { buildMoveOptions } from "./move-options.js";
+import { buildMoveOptions, folderDelimiter } from "./move-options.js";
 
 const englishBundle = JSON.parse(
 	readFileSync(
@@ -100,16 +100,15 @@ describe("buildMoveOptions", () => {
 		assert.equal(labelOf(options, "mb-receipts"), "Receipts");
 	});
 
-	test("the full provider path stays searchable", () => {
+	test("a role label keeps the provider path it nests under", () => {
 		const options = buildMoveOptions({
 			mailboxes: applePaths,
 			folderAppointments: appleAppointments,
 			translator: translate,
 		});
-		assert.equal(
-			options.find((option) => option.id === "mb-trash")?.searchValue,
-			"INBOX/Deleted Messages",
-		);
+		const trash = options.find((option) => option.id === "mb-trash");
+		assert.equal(trash?.label, "Trash");
+		assert.equal(trash?.path, "INBOX/Deleted Messages");
 	});
 
 	test("the current mailbox is marked and nothing else is", () => {
@@ -138,3 +137,18 @@ describe("buildMoveOptions", () => {
 		);
 	});
 });
+
+describe("folderDelimiter", () => {
+	test("takes the account's own hierarchy separator", () => {
+		assert.equal(
+			folderDelimiter([
+				make({ mailboxId: "mb-1", fullPath: "INBOX", hierarchyDelimiter: "." }),
+			]),
+			".",
+		);
+	});
+
+	test("falls back to a slash when there are no mailboxes yet", () => {
+		assert.equal(folderDelimiter([]), "/");
+	});
+});

package/src/lib/move-options.ts

@@ -2,7 +2,7 @@ import type {
 	RemitImapFolderAppointment,
 	RemitImapMailboxResponse,
 } from "@remit/api-http-client/types.gen.ts";
-import type { MoveMailboxOption } from "@remit/ui";
+import type { FolderTreeNode } from "@remit/ui";
 import { excludeFolder } from "./delete-folder.js";
 import { buildMailboxRoleMap, labelForMailbox } from "./folder-roles.js";
 import { buildMoveTargets } from "./move-targets.js";
@@ -19,11 +19,20 @@ interface MoveOptionsInput {
 	translator?: Translator;
 }
 
+/**
+ * The account's hierarchy separator, which the tree splits paths on. Every
+ * mailbox of an account reports the same one, so the first is the account's.
+ */
+export const folderDelimiter = (
+	mailboxes: readonly RemitImapMailboxResponse[],
+): string => mailboxes[0]?.hierarchyDelimiter ?? "/";
+
 /**
  * The single shaping of a mailbox list into Move-to picker options. Labels
  * follow the account's role appointments (RFC 032, #976) and any
  * `displayNameOverride`, so a picker reads `Inbox`/`Trash` rather than the
- * provider's leaf; the full path stays searchable.
+ * provider's leaf, while the provider path it nests and filters under stays
+ * untouched.
  */
 export const buildMoveOptions = ({
 	mailboxes,
@@ -31,7 +40,7 @@ export const buildMoveOptions = ({
 	currentMailboxId,
 	excludeMailboxId,
 	translator,
-}: MoveOptionsInput): MoveMailboxOption[] => {
+}: MoveOptionsInput): FolderTreeNode[] => {
 	const targets = buildMoveTargets(mailboxes, folderAppointments);
 	const roleMap = buildMailboxRoleMap(folderAppointments);
 	const destinations = excludeMailboxId
@@ -40,7 +49,7 @@ export const buildMoveOptions = ({
 	return destinations.map((mailbox) => ({
 		id: mailbox.mailboxId,
 		label: labelForMailbox(mailbox, roleMap.get(mailbox.mailboxId), translator),
-		searchValue: mailbox.fullPath,
+		path: mailbox.fullPath,
 		isCurrent: mailbox.mailboxId === currentMailboxId,
 	}));
 };

package/src/routes/settings/folders.tsx

@@ -12,32 +12,28 @@ import type {
 } from "@remit/api-http-client/types.gen.ts";
 import {
 	Banner,
-	Button,
 	type CandidateFolder,
+	FolderManager,
+	FolderRenameDialog,
 	type FolderRole,
-	Input,
+	type ManagedFolder,
 	RoleAppointmentList,
-	Select,
 	SettingsShell,
 } from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
-import { Trash2 } from "lucide-react";
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { DeleteFolderDialog } from "@/components/settings/DeleteFolderDialog";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
+import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { guardFolderDeletion } from "@/lib/delete-folder";
 import {
+	buildMailboxRoleMap,
 	CANONICAL_TO_NAV_ROLE,
-	getMailboxDisplayName,
+	labelForMailbox,
 	NAV_ROLE_TO_CANONICAL,
 } from "@/lib/folder-roles";
-import {
-	composeFolderPath,
-	type FolderTarget,
-	validateNewFolderName,
-} from "@/lib/new-folder";
 import { SETTINGS_ID_TO_PATH, SETTINGS_NAV_ITEMS } from "@/routes/settings";
 
 export const Route = createFileRoute("/settings/folders")({
@@ -58,140 +54,25 @@ const foldersHelp = (
 			compose flow).
 		</p>
 		<p>
-			<strong className="text-fg">Display name</strong> renames the appointed
-			folder for the sidebar. Leave it blank to use the role's canonical name.
+			<strong className="text-fg">Your folders</strong> is the account's real
+			hierarchy. Open a folder to see what's inside it, make a new one where
+			you're looking, and rename or delete any of them from its row.
 		</p>
 	</div>
 );
 
-/**
- * Create a folder for one account. A name, an optional parent to nest under,
- * and a create button. The new folder is queued on the server with a pending
- * sync and appears in the list below once it refetches.
- */
-function NewFolder({
-	accountId,
-	mailboxes,
-}: {
-	accountId: string;
-	mailboxes: RemitImapMailboxResponse[];
-}) {
-	const { mutation } = useCreateMailbox(accountId);
-	const [name, setName] = useState("");
-	const [parentId, setParentId] = useState("");
-	const [validationError, setValidationError] = useState<string>();
-
-	const accountDelimiter = mailboxes[0]?.hierarchyDelimiter ?? "/";
-	const parentMailbox = mailboxes.find((box) => box.mailboxId === parentId);
-	const parent: FolderTarget | undefined = parentMailbox
-		? {
-				fullPath: parentMailbox.fullPath,
-				hierarchyDelimiter: parentMailbox.hierarchyDelimiter,
-			}
-		: undefined;
-	const delimiter = parent?.hierarchyDelimiter ?? accountDelimiter;
-
-	const handleCreate = () => {
-		const problem = validateNewFolderName({
-			name,
-			delimiter,
-			parent,
-			existingPaths: mailboxes.map((box) => box.fullPath),
-		});
-		if (problem) {
-			setValidationError(problem);
-			return;
-		}
-		setValidationError(undefined);
-		mutation.mutate(
-			{
-				path: { accountId },
-				body: {
-					fullPath: composeFolderPath(name, parent),
-					namespaceType: "personal",
-				},
-			},
-			{
-				onSuccess: () => {
-					setName("");
-					setParentId("");
-				},
-			},
-		);
-	};
-
-	return (
-		<div className="space-y-2 rounded-sm border border-line bg-surface p-3">
-			<p className="text-sm font-medium text-fg">New folder</p>
-			<div className="flex flex-col gap-2 sm:flex-row sm:items-end">
-				<div className="flex-1 space-y-1">
-					<span className="text-xs text-fg-muted">Name</span>
-					<Input
-						value={name}
-						onChange={(event) => {
-							setName(event.target.value);
-							if (validationError) setValidationError(undefined);
-						}}
-						placeholder="e.g. Receipts"
-						aria-label="Folder name"
-						onKeyDown={(event) => {
-							if (event.key === "Enter") {
-								event.preventDefault();
-								handleCreate();
-							}
-						}}
-					/>
-				</div>
-				<div className="flex-1 space-y-1">
-					<span className="text-xs text-fg-muted">Inside (optional)</span>
-					<Select
-						value={parentId}
-						onChange={(event) => setParentId(event.target.value)}
-						aria-label="Parent folder"
-					>
-						<option value="">No parent — top level</option>
-						{mailboxes.map((box) => (
-							<option key={box.mailboxId} value={box.mailboxId}>
-								{box.fullPath}
-							</option>
-						))}
-					</Select>
-				</div>
-				<Button
-					variant="primary"
-					onClick={handleCreate}
-					disabled={mutation.isPending || name.trim() === ""}
-				>
-					{mutation.isPending ? "Creating…" : "Create folder"}
-				</Button>
-			</div>
-			{validationError && (
-				<p className="text-xs text-danger" role="alert">
-					{validationError}
-				</p>
-			)}
-			{mutation.isError && (
-				<Banner tone="danger" variant="soft">
-					Couldn't create that folder. Please try again.
-				</Banner>
-			)}
-		</div>
-	);
-}
-
-/** One account's folder roles, fed to the kit list. Owns its own queries + mutations. */
-function AccountFolderRoles({
-	account,
-}: {
-	account: RemitImapAccountResponse;
-}) {
+/** One account's folder roles and its folder hierarchy. Owns its own queries + mutations. */
+function AccountFolders({ account }: { account: RemitImapAccountResponse }) {
 	const queryClient = useQueryClient();
 	const accountId = account.accountId;
+	const translator = useFolderLabelTranslator();
 
 	const { data, isPending, isError, error, refetch } = useQuery(
 		mailboxOperationsListMailboxesOptions({ path: { accountId } }),
 	);
 
+	const { createFolderIn } = useCreateMailbox(accountId);
+
 	const appointMutation = useMutation({
 		...folderRoleOperationsAppointFolderRoleMutation(),
 		onSuccess: () => {
@@ -213,6 +94,33 @@ function AccountFolderRoles({
 	});
 
 	const [deletingMailboxId, setDeletingMailboxId] = useState<string>();
+	const [renamingMailboxId, setRenamingMailboxId] = useState<string>();
+	const [renameDraft, setRenameDraft] = useState("");
+
+	const mailboxes = useMemo(() => data?.items ?? [], [data]);
+	const roleMap = useMemo(
+		() => buildMailboxRoleMap(account.folderAppointments),
+		[account.folderAppointments],
+	);
+
+	const folders = useMemo<ManagedFolder[]>(
+		() =>
+			mailboxes.map((mailbox) => ({
+				id: mailbox.mailboxId,
+				label: labelForMailbox(
+					mailbox,
+					roleMap.get(mailbox.mailboxId),
+					translator,
+				),
+				path: mailbox.fullPath,
+				deleteBlockedReason: guardFolderDeletion(
+					mailbox,
+					mailboxes,
+					account.folderAppointments,
+				).message,
+			})),
+		[mailboxes, roleMap, translator, account.folderAppointments],
+	);
 
 	const handleAppoint = (role: FolderRole, mailboxId: string | null) => {
 		appointMutation.mutate({
@@ -253,7 +161,7 @@ function AccountFolderRoles({
 		);
 	}
 
-	const folders: CandidateFolder[] = data.items.map((mailbox) => ({
+	const candidates: CandidateFolder[] = mailboxes.map((mailbox) => ({
 		mailboxId: mailbox.mailboxId,
 		providerPath: mailbox.fullPath,
 		messageCount: mailbox.messageCount,
@@ -266,14 +174,22 @@ function AccountFolderRoles({
 	}
 
 	const displayNames: Record<string, string> = {};
-	for (const mailbox of data.items) {
+	for (const mailbox of mailboxes) {
 		if (mailbox.displayNameOverride) {
 			displayNames[mailbox.mailboxId] = mailbox.displayNameOverride;
 		}
 	}
 
+	const findMailbox = (
+		mailboxId: string | undefined,
+	): RemitImapMailboxResponse | undefined =>
+		mailboxes.find((mailbox) => mailbox.mailboxId === mailboxId);
+
+	const renaming = findMailbox(renamingMailboxId);
+	const deleting = findMailbox(deletingMailboxId);
+
 	return (
-		<div className="space-y-2">
+		<div className="space-y-4">
 			{(appointMutation.isError || renameMutation.isError) && (
 				<Banner tone="danger" variant="soft">
 					Couldn't save that change. Please try again.
@@ -281,61 +197,78 @@ function AccountFolderRoles({
 			)}
 			<RoleAppointmentList
 				accountEmail={account.email}
-				folders={folders}
+				folders={candidates}
 				appointments={appointments}
 				displayNames={displayNames}
 				onAppoint={handleAppoint}
 				onRename={handleRename}
 			/>
-			<NewFolder accountId={accountId} mailboxes={data.items} />
-			<ul className="space-y-1" aria-label={`All folders for ${account.email}`}>
-				{data.items.map((mailbox) => {
-					const guard = guardFolderDeletion(
-						mailbox,
-						data.items,
-						account.folderAppointments,
-					);
-					const name = getMailboxDisplayName(mailbox.fullPath);
-					return (
-						<li
-							key={mailbox.mailboxId}
-							className="flex items-center gap-2 rounded-sm px-2 py-1 text-sm text-fg"
-						>
-							<span className="truncate">{name}</span>
-							<span className="ml-auto shrink-0 text-xs text-fg-muted">
-								{mailbox.fullPath}
-							</span>
-							<Button
-								variant="ghost"
-								size="sm"
-								icon={<Trash2 className="size-3.5" />}
-								aria-label={`Delete ${name}`}
-								disabled={!guard.deletable}
-								title={guard.deletable ? undefined : guard.message}
-								onClick={() => setDeletingMailboxId(mailbox.mailboxId)}
-								className={guard.deletable ? undefined : "opacity-40"}
-							/>
-						</li>
-					);
-				})}
-			</ul>
-			{deletingMailboxId &&
-				(() => {
-					const folder = data.items.find(
-						(box) => box.mailboxId === deletingMailboxId,
-					);
-					if (!folder) return null;
-					return (
-						<DeleteFolderDialog
-							open
-							accountId={accountId}
-							folder={folder}
-							mailboxes={data.items}
-							appointments={account.folderAppointments}
-							onClose={() => setDeletingMailboxId(undefined)}
-						/>
-					);
-				})()}
+			<section className="space-y-1.5">
+				<h3 className="text-sm font-semibold text-fg">
+					Your folders — {account.email}
+				</h3>
+				<div className="flex h-[28rem] flex-col overflow-hidden rounded-sm border border-line bg-surface">
+					<FolderManager
+						folders={folders}
+						delimiter={mailboxes[0]?.hierarchyDelimiter ?? "/"}
+						onCreateFolder={createFolderIn}
+						onRename={(folder) => {
+							setRenamingMailboxId(folder.id);
+							setRenameDraft(
+								findMailbox(folder.id)?.displayNameOverride?.trim() ?? "",
+							);
+						}}
+						onDelete={(folder) => setDeletingMailboxId(folder.id)}
+						labels={{ treeAriaLabel: `All folders for ${account.email}` }}
+					/>
+				</div>
+			</section>
+			{renaming && (
+				<FolderRenameDialog
+					open
+					folderLabel={labelForMailbox(
+						renaming,
+						roleMap.get(renaming.mailboxId),
+						translator,
+					)}
+					defaultLabel={labelForMailbox(
+						{ fullPath: renaming.fullPath },
+						roleMap.get(renaming.mailboxId),
+						translator,
+					)}
+					name={renameDraft}
+					onNameChange={setRenameDraft}
+					pending={renameMutation.isPending}
+					error={
+						renameMutation.isError
+							? "Couldn't save that name. Please try again."
+							: undefined
+					}
+					onSubmit={() => {
+						const trimmed = renameDraft.trim();
+						renameMutation.mutate(
+							{
+								path: { accountId, mailboxId: renaming.mailboxId },
+								body: {
+									displayNameOverride: trimmed === "" ? null : trimmed,
+								},
+							},
+							{ onSuccess: () => setRenamingMailboxId(undefined) },
+						);
+					}}
+					onClose={() => setRenamingMailboxId(undefined)}
+				/>
+			)}
+			{deleting && (
+				<DeleteFolderDialog
+					open
+					accountId={accountId}
+					folder={deleting}
+					mailboxes={mailboxes}
+					appointments={account.folderAppointments}
+					onClose={() => setDeletingMailboxId(undefined)}
+				/>
+			)}
 		</div>
 	);
 }
@@ -389,7 +322,7 @@ function FoldersSettings() {
 			) : (
 				<div className="space-y-8">
 					{config.accounts.map((account) => (
-						<AccountFolderRoles key={account.accountId} account={account} />
+						<AccountFolders key={account.accountId} account={account} />
 					))}
 				</div>
 			)}