@remit/web-client 0.0.159 → 0.0.160

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.159",
+  "version": "0.0.160",
   "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/settings/QuarantinePanel.render.test.ts

@@ -0,0 +1,71 @@
+/**
+ * The pane in Settings › Advanced that is the only place a quarantined message
+ * is ever mentioned. Every read state has to say something: an empty list is
+ * the normal one, and a failed read is never a blank panel.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { type QuarantineEntry, quarantineDemoEntries } from "@remit/ui";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { QuarantinePanelView } from "./QuarantinePanel";
+
+// See MessageToolbar.render.test.ts: the SSR test loader transpiles remit-ui
+// `.tsx` with the classic JSX runtime, which needs a global `React`.
+(globalThis as { React?: typeof React }).React = React;
+
+const render = (props: {
+	entries: readonly QuarantineEntry[];
+	isPending: boolean;
+	error: Error | null;
+}): string =>
+	renderToString(createElement(QuarantinePanelView, props) as never);
+
+describe("QuarantinePanelView", () => {
+	it("says nothing was set aside rather than rendering nothing", () => {
+		const html = render({ entries: [], isPending: false, error: null });
+		assert.match(html, /Messages set aside/);
+		assert.match(html, /Nothing is set aside/);
+	});
+
+	it("lists a set-aside message with a way to report it", () => {
+		const html = render({
+			entries: quarantineDemoEntries.slice(0, 1),
+			isPending: false,
+			error: null,
+		});
+		assert.match(html, /Cut a bug/);
+		assert.match(html, /could not read/i);
+	});
+
+	it("calls more than one set aside a pattern, not a list", () => {
+		const html = render({
+			entries: quarantineDemoEntries,
+			isPending: false,
+			error: null,
+		});
+		assert.match(
+			html,
+			new RegExp(`${quarantineDemoEntries.length} messages could not be read`),
+		);
+	});
+
+	it("reports a failed read in the pane, with a way to file it", () => {
+		const html = render({
+			entries: [],
+			isPending: false,
+			error: new Error("Failed to fetch"),
+		});
+		assert.match(html, /role="alert"/);
+		assert.match(html, /could not be read/);
+		assert.match(html, /Failed to fetch/);
+		assert.match(html, /Report this/);
+		assert.doesNotMatch(html, /Nothing is set aside/);
+	});
+
+	it("says it is still reading rather than claiming an empty list", () => {
+		const html = render({ entries: [], isPending: true, error: null });
+		assert.match(html, /Checking for messages set aside/);
+		assert.doesNotMatch(html, /Nothing is set aside/);
+	});
+});

package/src/components/settings/QuarantinePanel.tsx

@@ -0,0 +1,136 @@
+/**
+ * Settings › Advanced — the messages sync set aside.
+ *
+ * A quarantined message exists on the server and nowhere else in the app, so
+ * this pane is the only place it is ever mentioned. Three states are all
+ * visible: the list, the reassurance that there is nothing in it, and the
+ * failure to read it at all. None of them is an empty panel.
+ */
+import { meOperationsListQuarantineOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	Button,
+	QuarantineBugDialog,
+	type QuarantineEntry,
+	QuarantineSection,
+	quarantineIssueTitle,
+	quarantineReportSections,
+} from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { Bug } from "lucide-react";
+import { useState } from "react";
+import { formatErrorMessage } from "@/components/ui/ErrorState";
+import { buildBugReportContext, buildGitHubIssueUrl } from "@/lib/bug-report";
+import { toQuarantineEntry } from "@/lib/quarantine-entries";
+
+function openIssue(url: string): void {
+	window.open(url, "_blank", "noopener,noreferrer");
+}
+
+function issueUrlFor(entry: QuarantineEntry): string {
+	return buildGitHubIssueUrl(
+		buildBugReportContext({
+			quarantine: quarantineReportSections(entry),
+			title: quarantineIssueTitle(entry),
+		}),
+	);
+}
+
+function QuarantineReadFailure({ error }: { error: Error }) {
+	return (
+		<section role="alert" className="space-y-3">
+			<h2 className="text-sm font-semibold text-fg">Messages set aside</h2>
+			<div className="space-y-2 rounded-sm border border-danger/40 bg-danger-soft px-row-inset py-3">
+				<p className="text-sm font-medium text-danger">
+					The list of set-aside messages could not be read.
+				</p>
+				<p className="break-words text-sm text-fg-muted">
+					{formatErrorMessage(error)}
+				</p>
+				<p className="text-xs text-fg-muted">
+					Mail may still have been set aside — this page cannot say either way
+					until it can read the list. Reporting this gets it fixed.
+				</p>
+				<Button
+					variant="secondary"
+					size="sm"
+					icon={<Bug className="size-3.5" />}
+					onClick={() =>
+						openIssue(buildGitHubIssueUrl(buildBugReportContext()))
+					}
+				>
+					Report this
+				</Button>
+			</div>
+		</section>
+	);
+}
+
+export interface QuarantinePanelViewProps {
+	entries: readonly QuarantineEntry[];
+	isPending: boolean;
+	error: Error | null;
+}
+
+export function QuarantinePanelView({
+	entries,
+	isPending,
+	error,
+}: QuarantinePanelViewProps) {
+	const [reporting, setReporting] = useState<QuarantineEntry | null>(null);
+	const [copyFailed, setCopyFailed] = useState(false);
+
+	if (isPending) {
+		return (
+			<p className="animate-pulse text-sm text-fg-subtle">
+				Checking for messages set aside…
+			</p>
+		);
+	}
+
+	if (error) return <QuarantineReadFailure error={error} />;
+
+	const handleCopy = (report: string) => {
+		navigator.clipboard.writeText(report).then(
+			() => {
+				setCopyFailed(false);
+				setReporting(null);
+			},
+			() => {
+				setCopyFailed(true);
+				setReporting(null);
+			},
+		);
+	};
+
+	return (
+		<>
+			{copyFailed && (
+				<p role="alert" className="mb-3 text-sm text-danger">
+					The report was not copied — this browser refused clipboard access. Cut
+					the bug again and use Open on GitHub, which needs no clipboard.
+				</p>
+			)}
+			<QuarantineSection entries={entries} onCutBug={setReporting} />
+			<QuarantineBugDialog
+				entry={reporting}
+				issueUrl={reporting ? issueUrlFor(reporting) : ""}
+				onClose={() => setReporting(null)}
+				onCopy={handleCopy}
+			/>
+		</>
+	);
+}
+
+export function QuarantinePanel() {
+	const { data, isPending, error } = useQuery(
+		meOperationsListQuarantineOptions(),
+	);
+
+	return (
+		<QuarantinePanelView
+			entries={(data?.entries ?? []).map(toQuarantineEntry)}
+			isPending={isPending}
+			error={error}
+		/>
+	);
+}

package/src/lib/quarantine-entries.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitImapQuarantineResponse } from "@remit/api-http-client/types.gen.ts";
+import { toQuarantineEntry } from "./quarantine-entries";
+
+const wire: RemitImapQuarantineResponse = {
+	quarantineId: "8b1e0c2a-0000-4000-8000-000000000001",
+	accountConfigId: "8b1e0c2a-0000-4000-8000-000000000002",
+	accountId: "8b1e0c2a-0000-4000-8000-000000000003",
+	mailboxId: "8b1e0c2a-0000-4000-8000-000000000004",
+	uidValidity: 1717171717,
+	uid: 4211,
+	mailboxRole: "Junk",
+	mailboxPath: "INBOX/Spam",
+	quarantinedAt: 1_750_000_000_000,
+	attempts: 3,
+	failureStage: "BodyParse",
+	failureCode: "UnknownCharset",
+	failureMessage: 'unknown charset "x-mac-roman"',
+	failurePartPath: "1.2",
+	workerVersion: "imap-worker@1.4.0",
+	contentType: "multipart/mixed",
+	transferEncoding: "base64",
+	charset: "x-mac-roman",
+	sizeBytes: 91_204,
+	structure: [
+		{ depth: 0, contentType: "multipart/mixed" },
+		{ depth: 1, contentType: "text/plain" },
+	],
+	messageIdHash: "sha256:abc",
+	createdAt: 1_750_000_000_000,
+	updatedAt: 1_750_000_000_000,
+};
+
+describe("toQuarantineEntry", () => {
+	it("spells the folder role the way the kit does", () => {
+		assert.equal(toQuarantineEntry(wire).mailboxRole, "junk");
+	});
+
+	it("leaves the role absent when the folder has none appointed", () => {
+		const { mailboxRole: _dropped, ...roleless } = wire;
+		assert.equal(toQuarantineEntry(roleless).mailboxRole, undefined);
+	});
+
+	it("carries every field the report and the row are built from", () => {
+		const entry = toQuarantineEntry(wire);
+		assert.equal(entry.quarantineId, wire.quarantineId);
+		assert.equal(entry.uid, wire.uid);
+		assert.equal(entry.uidValidity, wire.uidValidity);
+		assert.equal(entry.mailboxPath, wire.mailboxPath);
+		assert.equal(entry.failureCode, wire.failureCode);
+		assert.equal(entry.failureStage, wire.failureStage);
+		assert.equal(entry.failureMessage, wire.failureMessage);
+		assert.equal(entry.failurePartPath, wire.failurePartPath);
+		assert.equal(entry.attempts, wire.attempts);
+		assert.equal(entry.quarantinedAt, wire.quarantinedAt);
+		assert.equal(entry.workerVersion, wire.workerVersion);
+		assert.equal(entry.contentType, wire.contentType);
+		assert.equal(entry.transferEncoding, wire.transferEncoding);
+		assert.equal(entry.charset, wire.charset);
+		assert.equal(entry.sizeBytes, wire.sizeBytes);
+		assert.equal(entry.messageIdHash, wire.messageIdHash);
+		assert.deepEqual(entry.structure, wire.structure);
+	});
+
+	it("drops the fields the settings surface has no use for", () => {
+		const entry = toQuarantineEntry(wire);
+		assert.equal("accountConfigId" in entry, false);
+		assert.equal("createdAt" in entry, false);
+		assert.equal("updatedAt" in entry, false);
+	});
+});

package/src/lib/quarantine-entries.ts

@@ -0,0 +1,38 @@
+import type { RemitImapQuarantineResponse } from "@remit/api-http-client/types.gen.ts";
+import type { QuarantineEntry } from "@remit/ui";
+import { CANONICAL_TO_NAV_ROLE } from "./folder-roles";
+
+/**
+ * The wire record carries `accountConfigId`, `createdAt` and `updatedAt`, which
+ * the settings surface has no use for, and spells the folder role in the
+ * canonical PascalCase the API uses everywhere. Both differences are resolved
+ * here rather than by widening the kit's entry type.
+ */
+export function toQuarantineEntry(
+	wire: RemitImapQuarantineResponse,
+): QuarantineEntry {
+	return {
+		quarantineId: wire.quarantineId,
+		accountId: wire.accountId,
+		mailboxId: wire.mailboxId,
+		uidValidity: wire.uidValidity,
+		uid: wire.uid,
+		mailboxRole: wire.mailboxRole
+			? CANONICAL_TO_NAV_ROLE[wire.mailboxRole]
+			: undefined,
+		mailboxPath: wire.mailboxPath,
+		failureStage: wire.failureStage,
+		failureCode: wire.failureCode,
+		failureMessage: wire.failureMessage,
+		failurePartPath: wire.failurePartPath,
+		quarantinedAt: wire.quarantinedAt,
+		attempts: wire.attempts,
+		sizeBytes: wire.sizeBytes,
+		contentType: wire.contentType,
+		transferEncoding: wire.transferEncoding,
+		charset: wire.charset,
+		structure: wire.structure,
+		messageIdHash: wire.messageIdHash,
+		workerVersion: wire.workerVersion,
+	};
+}

package/src/routes/settings/advanced.tsx

@@ -1,11 +1,12 @@
 /**
  * Advanced settings. Updates live here — and only here — with a full pane in
- * Settings › Advanced. Notification rules, export, and diagnostics are future
- * scope.
+ * Settings › Advanced, alongside the messages sync could not read. Notification
+ * rules and export are future scope.
  */
 import { SettingsShell } from "@remit/ui";
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
 import { useState } from "react";
+import { QuarantinePanel } from "@/components/settings/QuarantinePanel";
 import { SelfUpdatePanel } from "@/components/settings/SelfUpdatePanel";
 import { TlsRootCaDownload } from "@/components/settings/TlsRootCaDownload";
 import { AppVersion } from "@/components/ui/AppVersion";
@@ -18,8 +19,14 @@ export const Route = createFileRoute("/settings/advanced")({
 const advancedHelp = (
 	<div className="space-y-3">
 		<p>
-			<strong className="text-fg">Notification rules</strong>, data export, and
-			per-account diagnostics are coming in a future release.
+			<strong className="text-fg">Notification rules</strong> and data export
+			are coming in a future release.
+		</p>
+		<p>
+			A message Remit cannot read is{" "}
+			<strong className="text-fg">set aside</strong> rather than skipped, and
+			the folder keeps syncing. Setting one aside is a defect in Remit, so every
+			entry can be reported with the diagnostics already attached.
 		</p>
 	</div>
 );
@@ -46,10 +53,12 @@ function AdvancedSettings() {
 			onBackToMail={() => void navigate({ to: "/mail" })}
 		>
 			<SelfUpdatePanel />
-			<p className="text-sm text-fg-muted">
-				Notification rules, data export, and raw sync diagnostics are coming in
-				a future release.
-			</p>
+			<QuarantinePanel />
+			<div className="mt-6 border-t border-line pt-4">
+				<p className="text-sm text-fg-muted">
+					Notification rules and data export are coming in a future release.
+				</p>
+			</div>
 			<TlsRootCaDownload />
 			<div className="border-t border-line pt-4 mt-4">
 				<p className="text-sm font-medium text-fg mb-1">About</p>