@remit/web-client 0.0.69 → 0.0.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "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

@@ -14,6 +14,7 @@ import { useTranslation } from "react-i18next";
 import { Drawer } from "vaul";
 import { ErrorState } from "@/components/ui/ErrorState";
 import { useFolderAppointments } from "@/hooks/useArchiveMailbox";
+import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useIsDesktop } from "@/hooks/useMediaQuery";
 import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
 import { buildMoveTargets } from "@/lib/move-targets";
@@ -95,6 +96,7 @@ export const MoveToTrigger = ({
 		enabled: isOpen,
 	});
 	const folderAppointments = useFolderAppointments(accountId);
+	const { createFolder } = useCreateMailbox(accountId);
 
 	const options = useMemo<MoveMailboxOption[]>(() => {
 		const targets = buildMoveTargets(
@@ -127,6 +129,14 @@ export const MoveToTrigger = ({
 		[onMove],
 	);
 
+	const handleCreateFolder = useCallback(
+		async (name: string): Promise<MoveMailboxOption> => {
+			const folder = await createFolder(name);
+			return { id: folder.id, label: folder.label };
+		},
+		[createFolder],
+	);
+
 	// Desktop popover: dismiss on outside click + Escape.
 	useEffect(() => {
 		if (!isOpen || !isDesktop) return;
@@ -190,9 +200,11 @@ export const MoveToTrigger = ({
 		<MoveMailboxPicker
 			mailboxes={options}
 			onSelect={handleSelect}
+			onCreateFolder={handleCreateFolder}
 			onCancel={() => setIsOpen(false)}
 			autoFocus={!isDesktop}
 			labels={{
+				createLabel: (folderName) => `Create "${folderName}"`,
 				searchPlaceholder: t("move_picker_placeholder", {
 					defaultValue: "Move to…",
 				}),

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

@@ -7,6 +7,7 @@ import {
 } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { useMemo, useState } from "react";
+import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useCreateFilter } from "@/hooks/useFilters";
 import { useOrganizeJob } from "@/hooks/useOrganizeJob";
 import { useRuleEditorState } from "@/hooks/useRuleEditorState";
@@ -104,6 +105,7 @@ export function OrganizeRuleEditor({
 
 	const organizeJob = useOrganizeJob(accountId);
 	const createFilter = useCreateFilter(accountId);
+	const { createFolder } = useCreateMailbox(accountId);
 
 	const commit = () => {
 		const draft = ruleToDraft(rule, anchorMessageId);
@@ -153,6 +155,7 @@ export function OrganizeRuleEditor({
 			semanticAvailable={!semanticUnavailable}
 			clauseFields={SUPPORTED_CLAUSE_FIELDS}
 			{...handlers}
+			onCreateFolder={createFolder}
 			onCommit={commit}
 			onCancel={onClose}
 		/>

package/src/components/settings/FilterEditor.tsx

@@ -11,6 +11,7 @@ import {
 } from "@remit/ui";
 import { CheckCircle2, Loader2 } from "lucide-react";
 import { useMemo, useRef, useState } from "react";
+import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import { useOrganizeJob } from "@/hooks/useOrganizeJob";
 import { useRulePreview } from "@/hooks/useRulePreview";
 import { useUpdateFilter } from "@/hooks/useUpdateFilter";
@@ -67,6 +68,7 @@ export function FilterEditor({
 	const preview = useRulePreview(accountId, rulePredicate(rule));
 	const update = useUpdateFilter(accountId, filter.filterId);
 	const organizeJob = useOrganizeJob(accountId);
+	const { createFolder } = useCreateMailbox(accountId);
 
 	const startAddClause = () =>
 		setClauseEdit({
@@ -203,6 +205,7 @@ export function FilterEditor({
 			onCancelClause={() => setClauseEdit(undefined)}
 			onChangeMatchOperator={changeMatchOperator}
 			onChangeMove={changeMove}
+			onCreateFolder={createFolder}
 			onChangeName={changeName}
 			onCommit={commit}
 			onCancel={onClose}

package/src/hooks/useCreateMailbox.render.test.ts

@@ -0,0 +1,131 @@
+/**
+ * useCreateMailbox.createFolder — the shared create seam the kit surfaces call.
+ * It validates the typed name against the account's current folders with the
+ * same IMAP-aware rules the settings form uses, and rejects with the
+ * human-readable reason before any request. The mailbox list is seeded into the
+ * query cache the hook reads, so validation runs against real paths.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	MailboxOperationsListMailboxesResponse,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { FolderOption } from "@remit/ui";
+import { act, createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useCreateMailbox } from "./useCreateMailbox";
+
+const ACCOUNT = "acc-1";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let createFolder: ((name: string) => Promise<FolderOption>) | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	createFolder = undefined;
+});
+
+const mailbox = (
+	fullPath: string,
+	delimiter: string,
+): RemitImapMailboxResponse =>
+	({
+		mailboxId: `mbx-${fullPath}`,
+		accountId: ACCOUNT,
+		fullPath,
+		hierarchyDelimiter: delimiter,
+	}) as RemitImapMailboxResponse;
+
+function Probe() {
+	createFolder = useCreateMailbox(ACCOUNT).createFolder;
+	return null;
+}
+
+const mount = (items: RemitImapMailboxResponse[]) => {
+	http = mockFetch((call) => {
+		if (call.method === "POST") {
+			const body = call.body as { fullPath: string };
+			return { mailboxId: `mbx-${body.fullPath}`, fullPath: body.fullPath };
+		}
+		return { items };
+	});
+	harness = createDomHarness();
+	harness.queryClient.setQueryData<MailboxOperationsListMailboxesResponse>(
+		mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT } }),
+		{ items },
+	);
+	harness.renderApp(createElement(Probe));
+};
+
+const reject = async (name: string): Promise<unknown> => {
+	const run = createFolder;
+	if (!run) throw new Error("createFolder is not mounted");
+	let caught: unknown;
+	await act(async () => {
+		caught = await run(name).then(
+			() => undefined,
+			(error: unknown) => error,
+		);
+	});
+	return caught;
+};
+
+const postCount = (): number =>
+	(http?.calls ?? []).filter((call) => call.method === "POST").length;
+
+describe("useCreateMailbox.createFolder validation", () => {
+	it("rejects a name containing the account delimiter before any request", async () => {
+		mount([mailbox("INBOX", "/")]);
+		const error = await reject("Work/Receipts");
+		assert.ok(error instanceof Error);
+		assert.match(error.message, /can't contain/);
+		assert.equal(postCount(), 0);
+	});
+
+	it("honours a non-slash account delimiter", async () => {
+		mount([mailbox("INBOX", ".")]);
+		const error = await reject("Work.Receipts");
+		assert.ok(error instanceof Error);
+		assert.match(error.message, /can't contain/);
+		assert.equal(postCount(), 0);
+	});
+
+	it("rejects a collision with an existing top-level fullPath before any request", async () => {
+		mount([mailbox("INBOX", "/"), mailbox("Work", "/")]);
+		const error = await reject("Work");
+		assert.ok(error instanceof Error);
+		assert.match(error.message, /already exists/);
+		assert.equal(postCount(), 0);
+	});
+
+	it("treats INBOX case-insensitively for collisions", async () => {
+		mount([mailbox("INBOX", "/")]);
+		const error = await reject("inbox");
+		assert.ok(error instanceof Error);
+		assert.match(error.message, /already exists/);
+		assert.equal(postCount(), 0);
+	});
+
+	it("passes a valid name through to the create request and maps the result", async () => {
+		mount([mailbox("INBOX", "/")]);
+		let result: FolderOption | undefined;
+		await act(async () => {
+			result = await createFolder?.("Taxes");
+		});
+		const posts = (http?.calls ?? []).filter((call) => call.method === "POST");
+		assert.equal(posts.length, 1);
+		assert.deepEqual(posts[0].body, {
+			fullPath: "Taxes",
+			namespaceType: "personal",
+		});
+		assert.equal(result?.label, "Taxes");
+	});
+});

package/src/hooks/useCreateMailbox.ts

@@ -0,0 +1,65 @@
+import {
+	mailboxOperationsCreateMailboxMutation,
+	mailboxOperationsListMailboxesOptions,
+	mailboxOperationsListMailboxesQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { FolderOption } from "@remit/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { getMailboxDisplayName } from "@/lib/folder-roles";
+import { composeFolderPath, validateNewFolderName } from "@/lib/new-folder";
+
+/**
+ * Creates a mailbox for an account and refreshes the folder list on success.
+ * The backend creates the row with a pending sync status and queues the IMAP
+ * create, so the folder is usable as a move destination immediately.
+ *
+ * `createFolder` takes a leaf name, validates it against the account's current
+ * folders with the same IMAP-aware rules the settings form uses (non-empty, no
+ * hierarchy delimiter, no collision — INBOX case-insensitive), and rejects with
+ * the human-readable reason before any request. The kit surfaces that pick the
+ * result render that rejection inline. `mutation` is exposed for callers that
+ * drive their own form state and error surface.
+ */
+export function useCreateMailbox(accountId: string) {
+	const queryClient = useQueryClient();
+
+	const { data } = useQuery(
+		mailboxOperationsListMailboxesOptions({ path: { accountId } }),
+	);
+
+	const mutation = useMutation({
+		...mailboxOperationsCreateMailboxMutation(),
+		onSuccess: () => {
+			queryClient.invalidateQueries({
+				queryKey: mailboxOperationsListMailboxesQueryKey({
+					path: { accountId },
+				}),
+			});
+		},
+	});
+
+	const createFolder = useCallback(
+		async (name: string): Promise<FolderOption> => {
+			const items = data?.items ?? [];
+			const delimiter = items[0]?.hierarchyDelimiter ?? "/";
+			const problem = validateNewFolderName({
+				name,
+				delimiter,
+				existingPaths: items.map((item) => item.fullPath),
+			});
+			if (problem) throw new Error(problem);
+			const mailbox = await mutation.mutateAsync({
+				path: { accountId },
+				body: { fullPath: composeFolderPath(name), namespaceType: "personal" },
+			});
+			return {
+				id: mailbox.mailboxId,
+				label: getMailboxDisplayName(mailbox.fullPath),
+			};
+		},
+		[mutation, accountId, data],
+	);
+
+	return { createFolder, mutation };
+}

package/src/lib/new-folder.test.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	composeFolderPath,
+	type FolderTarget,
+	validateNewFolderName,
+} from "./new-folder.js";
+
+const parent: FolderTarget = { fullPath: "INBOX", hierarchyDelimiter: "/" };
+
+describe("composeFolderPath", () => {
+	it("returns the trimmed name for a root folder", () => {
+		assert.equal(composeFolderPath("  Receipts  "), "Receipts");
+	});
+
+	it("joins the parent path by the parent's delimiter", () => {
+		assert.equal(composeFolderPath("Receipts", parent), "INBOX/Receipts");
+	});
+
+	it("honours a non-slash delimiter", () => {
+		assert.equal(
+			composeFolderPath("Receipts", {
+				fullPath: "INBOX",
+				hierarchyDelimiter: ".",
+			}),
+			"INBOX.Receipts",
+		);
+	});
+});
+
+describe("validateNewFolderName", () => {
+	const base = { delimiter: "/", existingPaths: ["INBOX", "INBOX/Archive"] };
+
+	it("rejects an empty or whitespace name", () => {
+		assert.match(
+			validateNewFolderName({ ...base, name: "   " }) ?? "",
+			/Enter a folder name/,
+		);
+	});
+
+	it("rejects a name containing the hierarchy delimiter", () => {
+		assert.match(
+			validateNewFolderName({ ...base, name: "a/b" }) ?? "",
+			/can't contain/,
+		);
+	});
+
+	it("rejects a name that would contain a non-slash delimiter", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: ".",
+				existingPaths: [],
+				name: "a.b",
+			}) ?? "",
+			/can't contain/,
+		);
+	});
+
+	it("rejects an exact collision with an existing path", () => {
+		assert.match(
+			validateNewFolderName({
+				...base,
+				name: "Archive",
+				parent,
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("rejects a root name that collides with an existing top-level fullPath", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["Work"],
+				name: "Work",
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("treats INBOX case-insensitively for collisions", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["INBOX"],
+				name: "inbox",
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("compares non-INBOX segments case-sensitively", () => {
+		assert.equal(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["Work"],
+				name: "work",
+			}),
+			undefined,
+		);
+	});
+
+	it("accepts a valid new nested folder", () => {
+		assert.equal(
+			validateNewFolderName({ ...base, name: "Receipts", parent }),
+			undefined,
+		);
+	});
+});

package/src/lib/new-folder.ts

@@ -0,0 +1,58 @@
+export interface FolderTarget {
+	fullPath: string;
+	hierarchyDelimiter: string;
+}
+
+/**
+ * The full path of a new folder: the leaf name on its own for a root folder, or
+ * the parent's path joined to the name by the parent's hierarchy delimiter.
+ */
+export function composeFolderPath(name: string, parent?: FolderTarget): string {
+	const trimmed = name.trim();
+	if (!parent) return trimmed;
+	return `${parent.fullPath}${parent.hierarchyDelimiter}${trimmed}`;
+}
+
+/**
+ * IMAP treats the INBOX root case-insensitively; every other path segment is
+ * exact. Canonicalizing only a leading `inbox` segment lets the collision check
+ * match `inbox/x` against `INBOX/x` without folding case anywhere else.
+ */
+const canonicalizePath = (path: string, delimiter: string): string => {
+	const parts = path.split(delimiter);
+	if (parts[0]?.toLowerCase() === "inbox") parts[0] = "INBOX";
+	return parts.join(delimiter);
+};
+
+/**
+ * Why the folder can't be created, or `undefined` when the name is valid. A
+ * name must be non-empty, must not contain the hierarchy delimiter (nesting is
+ * expressed by the parent select, not by typing a path), and must not collide
+ * with an existing folder — INBOX compared case-insensitively, everything else
+ * exactly.
+ */
+export function validateNewFolderName({
+	name,
+	delimiter,
+	parent,
+	existingPaths,
+}: {
+	name: string;
+	delimiter: string;
+	parent?: FolderTarget;
+	existingPaths: readonly string[];
+}): string | undefined {
+	const trimmed = name.trim();
+	if (trimmed === "") return "Enter a folder name.";
+	if (trimmed.includes(delimiter))
+		return `A folder name can't contain "${delimiter}".`;
+	const candidate = canonicalizePath(
+		composeFolderPath(trimmed, parent),
+		delimiter,
+	);
+	const collides = existingPaths.some(
+		(path) => canonicalizePath(path, delimiter) === candidate,
+	);
+	if (collides) return "A folder with that name already exists.";
+	return undefined;
+}

package/src/lib/self-update-state.test.ts

@@ -222,13 +222,13 @@ describe("deriveUpdateSurface — the surface without a run", () => {
 		);
 	});
 
-	test("a configured surface that has not checked yet is checking", () => {
+	test("a configured surface that has not checked yet is never-checked, not a spinner", () => {
 		const result = deriveUpdateSurface(
 			input({ data: response({ check: { status: "disabled" } }) }),
 		);
 		assert.equal(
 			result.surface.status === "ready" && result.surface.section.status,
-			"checking",
+			"neverChecked",
 		);
 	});
 

package/src/lib/self-update-state.ts

@@ -292,10 +292,12 @@ function checkSection(
 		};
 	}
 
-	// A configured surface that has not run its first check yet reads as looking,
-	// not as up to date — the client has no basis to claim the latest.
+	// A configured surface that has not run its first check yet is never-checked,
+	// not checking: the updater runs the check on a cadence and has not written a
+	// result. A spinner here would run forever, since nothing on this poll is in
+	// flight. Only a genuine refetch (handled above) shows the spinner.
 	if (check.status === "disabled") {
-		return { status: "checking", version: data.currentVersion };
+		return { status: "neverChecked", version: data.currentVersion };
 	}
 
 	const release = releaseFromCheck(data, now);

package/src/routes/settings/folders.tsx

@@ -6,22 +6,35 @@ import {
 	mailboxOperationsListMailboxesOptions,
 	mailboxOperationsListMailboxesQueryKey,
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import type {
+	RemitImapAccountResponse,
+	RemitImapMailboxResponse,
+} from "@remit/api-http-client/types.gen.ts";
 import {
 	Banner,
+	Button,
 	type CandidateFolder,
 	type FolderRole,
+	Input,
 	RoleAppointmentList,
+	Select,
 	SettingsShell,
 } from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
 import { useState } from "react";
 import { ErrorState } from "@/components/ui/ErrorState";
+import { useCreateMailbox } from "@/hooks/useCreateMailbox";
 import {
 	CANONICAL_TO_NAV_ROLE,
+	getMailboxDisplayName,
 	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")({
@@ -48,6 +61,121 @@ const foldersHelp = (
 	</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,
@@ -154,6 +282,22 @@ function AccountFolderRoles({
 				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) => (
+					<li
+						key={mailbox.mailboxId}
+						className="flex items-center justify-between rounded-sm px-2 py-1 text-sm text-fg"
+					>
+						<span className="truncate">
+							{getMailboxDisplayName(mailbox.fullPath)}
+						</span>
+						<span className="shrink-0 text-xs text-fg-muted">
+							{mailbox.fullPath}
+						</span>
+					</li>
+				))}
+			</ul>
 		</div>
 	);
 }