@remit/web-client 0.0.99 → 0.0.101

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.99",
+  "version": "0.0.101",
   "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.tsx

@@ -15,9 +15,9 @@ import { Drawer } from "vaul";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { useFolderAppointments } from "@/hooks/useArchiveMailbox";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
+import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
-import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
-import { buildMoveTargets } from "@/lib/move-targets";
+import { buildMoveOptions } from "@/lib/move-options";
 import { cn } from "@/lib/utils";
 
 interface MoveToTriggerProps {
@@ -71,15 +71,7 @@ export const MoveToTrigger = ({
 	const triggerLabel = label ?? "Move to folder";
 	const popoverId = useId();
 	const { t } = useTranslation("mail", { useSuspense: false });
-	// `labelForMailbox` expects a translator with a positional `(key,
-	// fallback)` shape; i18next's `t` treats the second argument as an options
-	// object — passing it raw breaks fallback behavior. Wrap it the same way
-	// the sidebar adapter does, memoized so it's a stable `useMemo` dependency.
-	const translator = useCallback(
-		(key: string, fallback: string): string =>
-			t(key, { defaultValue: fallback }),
-		[t],
-	);
+	const translator = useFolderLabelTranslator();
 
 	const {
 		data: mailboxesResponse,
@@ -98,28 +90,21 @@ export const MoveToTrigger = ({
 	const folderAppointments = useFolderAppointments(accountId);
 	const { createFolder } = useCreateMailbox(accountId);
 
-	const options = useMemo<MoveMailboxOption[]>(() => {
-		const targets = buildMoveTargets(
-			mailboxesResponse?.items ?? [],
-			folderAppointments,
-		);
-		const roleMap = buildMailboxRoleMap(folderAppointments);
-		return targets.map((mailbox) => ({
-			id: mailbox.mailboxId,
-			label: labelForMailbox(
-				mailbox,
-				roleMap.get(mailbox.mailboxId),
+	const options = useMemo<MoveMailboxOption[]>(
+		() =>
+			buildMoveOptions({
+				mailboxes: mailboxesResponse?.items ?? [],
+				folderAppointments,
+				currentMailboxId,
 				translator,
-			),
-			searchValue: mailbox.fullPath,
-			isCurrent: mailbox.mailboxId === currentMailboxId,
-		}));
-	}, [
-		mailboxesResponse?.items,
-		folderAppointments,
-		currentMailboxId,
-		translator,
-	]);
+			}),
+		[
+			mailboxesResponse?.items,
+			folderAppointments,
+			currentMailboxId,
+			translator,
+		],
+	);
 
 	const handleSelect = useCallback(
 		(destinationMailboxId: string) => {

package/src/components/mail/SelectionWizardHost.tsx

@@ -41,16 +41,16 @@ import {
 	useEscalatedActions,
 } from "@/hooks/useEscalatedActions";
 import { useCreateFilter } from "@/hooks/useFilters";
+import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { useMatchSample, useSearchMatchSample } from "@/hooks/useMatchSample";
 import { useOrganizeJob } from "@/hooks/useOrganizeJob";
 import { useOrganizeWiden } from "@/hooks/useOrganizeWiden";
 import { useRulePreview } from "@/hooks/useRulePreview";
 import { useSelectedSubjects } from "@/hooks/useSelectedSubjects";
 import type { BulkActionProgress, BulkRunOutcome } from "@/lib/bulk-actions";
-import { getMailboxDisplayName } from "@/lib/folder-roles";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
 import { useMailContext } from "@/lib/mail-context";
-import { buildMoveTargets } from "@/lib/move-targets";
+import { buildMoveOptions } from "@/lib/move-options";
 import {
 	buildWizardDraft,
 	canBackApplyDraft,
@@ -387,17 +387,16 @@ function SelectionWizardSession({
 		staleTime: Number.POSITIVE_INFINITY,
 	});
 	const folderAppointments = useFolderAppointments(accountId);
+	const translator = useFolderLabelTranslator();
 	const mailboxes = useMemo<MoveMailboxOption[]>(
 		() =>
-			buildMoveTargets(mailboxesData?.items ?? [], folderAppointments).map(
-				(mailbox) => ({
-					id: mailbox.mailboxId,
-					label: getMailboxDisplayName(mailbox.fullPath),
-					searchValue: mailbox.fullPath,
-					isCurrent: mailbox.mailboxId === mailboxId,
-				}),
-			),
-		[mailboxesData?.items, folderAppointments, mailboxId],
+			buildMoveOptions({
+				mailboxes: mailboxesData?.items ?? [],
+				folderAppointments,
+				currentMailboxId: mailboxId,
+				translator,
+			}),
+		[mailboxesData?.items, folderAppointments, mailboxId, translator],
 	);
 	const { createFolder } = useCreateMailbox(accountId);
 

package/src/components/mail/SpamRescue.tsx

@@ -14,13 +14,12 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { useTranslation } from "react-i18next";
 import {
 	useFolderAppointments,
 	useInboxMailbox,
 } from "@/hooks/useArchiveMailbox";
-import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
-import { buildMoveTargets } from "@/lib/move-targets";
+import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
+import { buildMoveOptions } from "@/lib/move-options";
 import {
 	recordRescueCandidatesSurfaced,
 	recordRescueCommitted,
@@ -51,12 +50,7 @@ export function SpamRescue({
 }: SpamRescueProps) {
 	const [open, setOpen] = useState(false);
 	const telemetry = useTelemetry();
-	const { t } = useTranslation("mail", { useSuspense: false });
-	const translator = useCallback(
-		(key: string, fallback: string): string =>
-			t(key, { defaultValue: fallback }),
-		[t],
-	);
+	const translator = useFolderLabelTranslator();
 
 	const { inboxMailboxId } = useInboxMailbox(accountId);
 	const folderAppointments = useFolderAppointments(accountId);
@@ -66,28 +60,21 @@ export function SpamRescue({
 		staleTime: Infinity,
 	});
 
-	const folders = useMemo<MoveMailboxOption[]>(() => {
-		const targets = buildMoveTargets(
-			mailboxesResponse?.items ?? [],
-			folderAppointments,
-		);
-		const roleMap = buildMailboxRoleMap(folderAppointments);
-		return targets.map((mailbox) => ({
-			id: mailbox.mailboxId,
-			label: labelForMailbox(
-				mailbox,
-				roleMap.get(mailbox.mailboxId),
+	const folders = useMemo<MoveMailboxOption[]>(
+		() =>
+			buildMoveOptions({
+				mailboxes: mailboxesResponse?.items ?? [],
+				folderAppointments,
+				currentMailboxId,
 				translator,
-			),
-			searchValue: mailbox.fullPath,
-			isCurrent: mailbox.mailboxId === currentMailboxId,
-		}));
-	}, [
-		mailboxesResponse?.items,
-		folderAppointments,
-		currentMailboxId,
-		translator,
-	]);
+			}),
+		[
+			mailboxesResponse?.items,
+			folderAppointments,
+			currentMailboxId,
+			translator,
+		],
+	);
 
 	const defaultDestinationId = useMemo(() => {
 		if (inboxMailboxId) return inboxMailboxId;

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,20 +6,17 @@ 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";
 import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useDeleteFolder } from "@/hooks/useDeleteFolder";
-import {
-	excludeFolder,
-	initialStage,
-	moveProgressLabel,
-} from "@/lib/delete-folder";
-import { getMailboxDisplayName } from "@/lib/folder-roles";
-import { buildMoveTargets } from "@/lib/move-targets";
+import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
+import { initialStage, moveProgressLabel } from "@/lib/delete-folder";
+import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
+import { buildMoveOptions } from "@/lib/move-options";
 
 interface DeleteFolderDialogProps {
 	open: boolean;
@@ -36,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"}`;
 
@@ -60,7 +54,8 @@ export function DeleteFolderDialog({
 	const [stage, setStage] = useState<FateStage>(() =>
 		initialStage(folder.messageCount),
 	);
-	const { createFolder } = useCreateMailbox(accountId);
+	const { createFolderIn } = useCreateMailbox(accountId);
+	const translator = useFolderLabelTranslator();
 	const {
 		phase,
 		progress,
@@ -88,30 +83,36 @@ export function DeleteFolderDialog({
 		onClose();
 	}, [cancel, onClose]);
 
-	const destinations = useMemo<MoveMailboxOption[]>(
+	// `buildMoveOptions` carries the label and the searchable path but not the
+	// provider path the tree nests by, so the path is joined back on by id here.
+	const destinations = useMemo<FolderTreeNode[]>(() => {
+		const pathById = new Map(
+			mailboxes.map((mailbox) => [mailbox.mailboxId, mailbox.fullPath]),
+		);
+		return buildMoveOptions({
+			mailboxes,
+			folderAppointments: appointments,
+			excludeMailboxId: folder.mailboxId,
+			translator,
+		}).map((option) => ({
+			id: option.id,
+			label: option.label,
+			path: pathById.get(option.id) ?? option.label,
+		}));
+	}, [mailboxes, appointments, folder.mailboxId, translator]);
+
+	const name = useMemo(
 		() =>
-			excludeFolder(
-				buildMoveTargets(mailboxes, appointments),
-				folder.mailboxId,
-			).map((mailbox) => ({
-				id: mailbox.mailboxId,
-				label: getMailboxDisplayName(mailbox.fullPath),
-				searchValue: mailbox.fullPath,
-			})),
-		[mailboxes, appointments, folder.mailboxId],
+			labelForMailbox(
+				folder,
+				buildMailboxRoleMap(appointments).get(folder.mailboxId),
+				translator,
+			),
+		[folder, appointments, translator],
 	);
 
-	const handleCreateFolder = async (
-		name: string,
-		signal?: AbortSignal,
-	): Promise<MoveMailboxOption> => {
-		const created = await createFolder(name, signal);
-		return { id: created.id, label: created.label };
-	};
-
 	if (!open) return null;
 
-	const name = folderLabel(folder);
 	const title = `Delete ${name}`;
 
 	const body = (() => {
@@ -266,24 +267,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/hooks/useFolderLabelTranslator.ts

@@ -0,0 +1,19 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * `labelForMailbox` expects a positional `(key, fallback)` translator; i18next's
+ * `t` reads its second argument as an options object, which drops the fallback.
+ * Memoized so callers can hold it as a `useMemo` dependency.
+ */
+export const useFolderLabelTranslator = (): ((
+	key: string,
+	fallback: string,
+) => string) => {
+	const { t } = useTranslation("mail", { useSuspense: false });
+	return useCallback(
+		(key: string, fallback: string): string =>
+			t(key, { defaultValue: fallback }),
+		[t],
+	);
+};

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

@@ -0,0 +1,140 @@
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import { describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import type {
+	RemitImapFolderAppointment,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { buildMoveOptions } from "./move-options.js";
+
+const englishBundle = JSON.parse(
+	readFileSync(
+		fileURLToPath(
+			new URL("../../public/locales/en/mail.json", import.meta.url),
+		),
+		"utf8",
+	),
+) as { sidebar: Record<string, string> };
+
+// The picker is handed the same shipped English bundle the app loads, so the
+// expected labels are the product's own, not strings restated by the test.
+const translate = (key: string, fallback: string): string =>
+	englishBundle.sidebar[key.replace("sidebar.", "")] ?? fallback;
+
+const make = (
+	overrides: Partial<RemitImapMailboxResponse> & {
+		mailboxId: string;
+		fullPath: string;
+	},
+): RemitImapMailboxResponse =>
+	({
+		accountId: "acct-1",
+		namespaceType: "personal",
+		namespacePrefix: "",
+		hierarchyDelimiter: "/",
+		messageCount: 0,
+		unseenCount: 0,
+		deletedCount: 0,
+		createdAt: 0,
+		updatedAt: 0,
+		...overrides,
+	}) as RemitImapMailboxResponse;
+
+const appoint = (
+	role: RemitImapFolderAppointment["role"],
+	mailboxId: string,
+): RemitImapFolderAppointment => ({ role, mailboxId });
+
+const applePaths = [
+	make({ mailboxId: "mb-inbox", fullPath: "INBOX" }),
+	make({ mailboxId: "mb-trash", fullPath: "INBOX/Deleted Messages" }),
+	make({ mailboxId: "mb-junk", fullPath: "INBOX/Junk" }),
+	make({ mailboxId: "mb-receipts", fullPath: "INBOX/Receipts" }),
+];
+
+const appleAppointments = [
+	appoint("Inbox", "mb-inbox"),
+	appoint("Trash", "mb-trash"),
+	appoint("Junk", "mb-junk"),
+];
+
+const labelOf = (
+	options: ReturnType<typeof buildMoveOptions>,
+	id: string,
+): string | undefined => options.find((option) => option.id === id)?.label;
+
+describe("buildMoveOptions", () => {
+	test("labels appointed folders by role, not by the provider's leaf", () => {
+		const options = buildMoveOptions({
+			mailboxes: applePaths,
+			folderAppointments: appleAppointments,
+			translator: translate,
+		});
+		assert.equal(labelOf(options, "mb-inbox"), "Inbox");
+		assert.equal(labelOf(options, "mb-trash"), "Trash");
+		assert.equal(labelOf(options, "mb-junk"), "Spam");
+	});
+
+	test("a displayNameOverride wins over the role label", () => {
+		const options = buildMoveOptions({
+			mailboxes: [
+				make({
+					mailboxId: "mb-trash",
+					fullPath: "INBOX/Deleted Messages",
+					displayNameOverride: "Bin",
+				}),
+			],
+			folderAppointments: [appoint("Trash", "mb-trash")],
+			translator: translate,
+		});
+		assert.equal(labelOf(options, "mb-trash"), "Bin");
+	});
+
+	test("an unappointed folder keeps its own name", () => {
+		const options = buildMoveOptions({
+			mailboxes: applePaths,
+			folderAppointments: appleAppointments,
+			translator: translate,
+		});
+		assert.equal(labelOf(options, "mb-receipts"), "Receipts");
+	});
+
+	test("the full provider path stays searchable", () => {
+		const options = buildMoveOptions({
+			mailboxes: applePaths,
+			folderAppointments: appleAppointments,
+			translator: translate,
+		});
+		assert.equal(
+			options.find((option) => option.id === "mb-trash")?.searchValue,
+			"INBOX/Deleted Messages",
+		);
+	});
+
+	test("the current mailbox is marked and nothing else is", () => {
+		const options = buildMoveOptions({
+			mailboxes: applePaths,
+			folderAppointments: appleAppointments,
+			currentMailboxId: "mb-junk",
+			translator: translate,
+		});
+		assert.deepStrictEqual(
+			options.filter((option) => option.isCurrent).map((option) => option.id),
+			["mb-junk"],
+		);
+	});
+
+	test("an excluded mailbox is not offered as a destination", () => {
+		const options = buildMoveOptions({
+			mailboxes: applePaths,
+			folderAppointments: appleAppointments,
+			excludeMailboxId: "mb-receipts",
+			translator: translate,
+		});
+		assert.equal(
+			options.some((option) => option.id === "mb-receipts"),
+			false,
+		);
+	});
+});

package/src/lib/move-options.ts

@@ -0,0 +1,46 @@
+import type {
+	RemitImapFolderAppointment,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { MoveMailboxOption } from "@remit/ui";
+import { excludeFolder } from "./delete-folder.js";
+import { buildMailboxRoleMap, labelForMailbox } from "./folder-roles.js";
+import { buildMoveTargets } from "./move-targets.js";
+
+type Translator = (key: string, fallback: string) => string;
+
+interface MoveOptionsInput {
+	mailboxes: readonly RemitImapMailboxResponse[];
+	folderAppointments: readonly RemitImapFolderAppointment[];
+	/** Rendered as a non-selectable row, so the user sees where mail lives now. */
+	currentMailboxId?: string;
+	/** Dropped entirely — the folder being deleted is not its own destination. */
+	excludeMailboxId?: string;
+	translator?: Translator;
+}
+
+/**
+ * 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.
+ */
+export const buildMoveOptions = ({
+	mailboxes,
+	folderAppointments,
+	currentMailboxId,
+	excludeMailboxId,
+	translator,
+}: MoveOptionsInput): MoveMailboxOption[] => {
+	const targets = buildMoveTargets(mailboxes, folderAppointments);
+	const roleMap = buildMailboxRoleMap(folderAppointments);
+	const destinations = excludeMailboxId
+		? excludeFolder(targets, excludeMailboxId)
+		: targets;
+	return destinations.map((mailbox) => ({
+		id: mailbox.mailboxId,
+		label: labelForMailbox(mailbox, roleMap.get(mailbox.mailboxId), translator),
+		searchValue: 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>
 			)}