@remit/ui 0.0.20 → 0.0.22

package/src/components/self-update.render.test.ts

@@ -0,0 +1,294 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	demoLogsCommand,
+	demoRelease,
+	demoRunId,
+	type SelfUpdateState,
+	updateWaitNote,
+} from "./self-update.js";
+import { SelfUpdateConfirmDialog } from "./self-update-confirm-dialog.js";
+import { UpdateAvailableDot } from "./self-update-dot.js";
+import {
+	SelfUpdateProgressOverlay,
+	SelfUpdateUnreachableScreen,
+} from "./self-update-progress-overlay.js";
+import { SelfUpdateSection } from "./self-update-section.js";
+
+const noop = () => {};
+const NOW = Date.parse("2026-07-20T12:00:00.000Z");
+const CURRENT = "0.9.3";
+
+/** SSR splits interpolations with comment markers; sentences read across them. */
+const render = (element: Parameters<typeof renderToString>[0]) =>
+	renderToString(element).replaceAll("<!-- -->", "");
+
+const section = (state: SelfUpdateState) =>
+	render(
+		createElement(SelfUpdateSection, {
+			state,
+			now: NOW,
+			onCheck: noop,
+			onInstall: noop,
+			onDismissResult: noop,
+		}),
+	);
+
+describe("SelfUpdateSection", () => {
+	it("states being up to date without raising an alert", () => {
+		const html = section({
+			status: "upToDate",
+			version: CURRENT,
+			checkedAt: NOW - 60_000,
+		});
+		assert.match(html, /0\.9\.3 is the latest version/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("offers an available update without shouting about it", () => {
+		const html = section({
+			status: "available",
+			version: CURRENT,
+			release: demoRelease,
+		});
+		assert.match(html, /Install 0\.9\.4/);
+		assert.match(html, /Release notes/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("names the automatic rollback before the user commits", () => {
+		const html = section({
+			status: "available",
+			version: CURRENT,
+			release: demoRelease,
+		});
+		assert.match(html, /restored on its own/);
+	});
+
+	it("keeps a failed check separate from a failed update", () => {
+		const html = section({
+			status: "checkFailed",
+			version: CURRENT,
+			reason: "No route to github.com",
+			lastCheckedAt: NOW - 3_600_000,
+		});
+		assert.match(html, /Could not reach the update source/);
+		assert.match(html, /still on 0\.9\.3 and it keeps working/);
+		assert.match(html, /Try again/);
+	});
+
+	it("says which version is running after a rollback, and where the log is", () => {
+		const html = section({
+			status: "rolledBack",
+			runId: demoRunId,
+			version: CURRENT,
+			attemptedVersion: "0.9.4",
+			reason: "migration 0042 failed",
+			logsCommand: demoLogsCommand,
+		});
+		assert.match(html, /running 0\.9\.3 again/);
+		assert.match(html, /migration 0042 failed/);
+		assert.match(html, /remit logs --since 10m/);
+	});
+
+	it("attributes the rollback to the server rather than asserting it", () => {
+		const html = section({
+			status: "rolledBack",
+			runId: demoRunId,
+			version: CURRENT,
+			attemptedVersion: "0.9.4",
+			reason: "migration 0042 failed",
+			logsCommand: demoLogsCommand,
+		});
+		assert.match(html, /Remit reports that it put 0\.9\.3 back/);
+	});
+
+	it("never claims data survived a failed update", () => {
+		const html = section({
+			status: "rolledBack",
+			runId: demoRunId,
+			version: CURRENT,
+			attemptedVersion: "0.9.4",
+			reason: "migration 0042_add_thread_index failed",
+			logsCommand: demoLogsCommand,
+		});
+		// The server reported a rollback and a reason. It reported nothing about
+		// data, and a half-applied migration is exactly where that matters.
+		assert.doesNotMatch(html, /Nothing was lost/);
+		assert.doesNotMatch(html, /everything works/);
+		assert.match(html, /can still have changed things/);
+	});
+
+	it("renders every status rather than going blank", () => {
+		assert.match(
+			section({
+				status: "applying",
+				runId: demoRunId,
+				version: CURRENT,
+				target: "0.9.4",
+				phase: "restarting",
+				elapsedSeconds: 20,
+			}),
+			/Installing Remit 0\.9\.4/,
+		);
+		assert.match(
+			section({
+				status: "unreachable",
+				runId: demoRunId,
+				previousVersion: CURRENT,
+				attemptedVersion: "0.9.4",
+				elapsedSeconds: 420,
+				logsCommand: demoLogsCommand,
+			}),
+			/left the server unreachable/,
+		);
+	});
+
+	it("offers a way forward from every failure", () => {
+		const rolledBack = section({
+			status: "rolledBack",
+			runId: demoRunId,
+			version: CURRENT,
+			attemptedVersion: "0.9.4",
+			reason: "boom",
+			logsCommand: demoLogsCommand,
+		});
+		assert.match(rolledBack, /Try 0\.9\.4 again/);
+		assert.match(rolledBack, /Stay on 0\.9\.3/);
+	});
+
+	it("keeps the check control pressable while a check is running", () => {
+		const html = section({ status: "checking", version: CURRENT });
+		assert.match(html, /Check again/);
+		assert.doesNotMatch(html, /disabled=/);
+	});
+});
+
+describe("SelfUpdateConfirmDialog", () => {
+	const html = render(
+		createElement(SelfUpdateConfirmDialog, {
+			open: true,
+			currentVersion: CURRENT,
+			release: demoRelease,
+			onClose: noop,
+			onConfirm: noop,
+		}),
+	);
+
+	it("reflects the consequence in the order the user will feel it", () => {
+		assert.match(html, /lose its connection/);
+		assert.match(html, /stays at your provider/);
+		assert.match(html, /restored automatically/);
+	});
+
+	it("always offers the way back", () => {
+		assert.match(html, /Not now/);
+	});
+
+	it("renders nothing when closed", () => {
+		assert.equal(
+			renderToString(
+				createElement(SelfUpdateConfirmDialog, {
+					open: false,
+					currentVersion: CURRENT,
+					release: demoRelease,
+					onClose: noop,
+					onConfirm: noop,
+				}),
+			),
+			"",
+		);
+	});
+});
+
+describe("SelfUpdateProgressOverlay", () => {
+	it("tells the user the disconnection is expected", () => {
+		const html = render(
+			createElement(SelfUpdateProgressOverlay, {
+				target: "0.9.4",
+				phase: "restarting",
+				elapsedSeconds: 20,
+			}),
+		);
+		assert.match(html, /no server to talk to/);
+		assert.match(html, /Waiting for Remit to answer again/);
+	});
+
+	it("stops promising a minute once a minute has passed", () => {
+		assert.match(updateWaitNote(30), /about a minute/);
+		assert.doesNotMatch(updateWaitNote(200), /about a minute/);
+	});
+
+	it("never describes the server from a lost connection", () => {
+		// The unreachable screen refuses to claim the rollback ran; the timeout
+		// copy sits on the same dead connection and may not claim it either.
+		for (const seconds of [30, 120, 240, 600]) {
+			assert.doesNotMatch(updateWaitNote(seconds), /old version|way back|kept/);
+		}
+	});
+
+	it("blocks the window rather than its nearest positioned ancestor", () => {
+		const html = render(
+			createElement(SelfUpdateProgressOverlay, {
+				target: "0.9.4",
+				phase: "restarting",
+				elapsedSeconds: 20,
+			}),
+		);
+		assert.match(html, /fixed inset-0/);
+		assert.doesNotMatch(html, /absolute inset-0/);
+		assert.match(html, /aria-modal="true"/);
+	});
+
+	it("scopes the live region to the line that changes", () => {
+		const html = render(
+			createElement(SelfUpdateProgressOverlay, {
+				target: "0.9.4",
+				phase: "restarting",
+				elapsedSeconds: 20,
+			}),
+		);
+		assert.equal(html.match(/aria-live/g)?.length, 1);
+	});
+});
+
+describe("SelfUpdateUnreachableScreen", () => {
+	const html = render(
+		createElement(SelfUpdateUnreachableScreen, {
+			attemptedVersion: "0.9.4",
+			previousVersion: CURRENT,
+			elapsedSeconds: 420,
+			logsCommand: demoLogsCommand,
+			onRetryConnection: noop,
+		}),
+	);
+
+	it("raises an alert and never claims the rollback succeeded", () => {
+		assert.match(html, /role="alertdialog"/);
+		assert.match(html, /aria-modal="true"/);
+		assert.match(html, /cannot confirm that from here/);
+	});
+
+	it("points at the machine that can answer", () => {
+		assert.match(html, /remit logs --since 10m/);
+		assert.match(html, /Try connecting again/);
+	});
+});
+
+describe("UpdateAvailableDot", () => {
+	it("carries a label for assistive tech when shown", () => {
+		const html = renderToString(
+			createElement(UpdateAvailableDot, { show: true }, null),
+		);
+		assert.match(html, /Update available/);
+	});
+
+	it("adds nothing when there is no update", () => {
+		const html = renderToString(
+			createElement(UpdateAvailableDot, { show: false }, null),
+		);
+		assert.doesNotMatch(html, /Update available/);
+	});
+});

package/src/components/self-update.stories.tsx

@@ -0,0 +1,212 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import {
+	demoLogsCommand,
+	demoRelease,
+	demoRunId,
+	type SelfUpdateState,
+} from "./self-update.js";
+import { SelfUpdateConfirmDialog } from "./self-update-confirm-dialog.js";
+import { SelfUpdateSection } from "./self-update-section.js";
+
+const NOW = Date.parse("2026-07-20T12:00:00.000Z");
+const CURRENT = "0.9.3";
+
+const meta: Meta<typeof SelfUpdateSection> = {
+	title: "Settings/Self-update",
+	component: SelfUpdateSection,
+	parameters: { layout: "padded" },
+	args: {
+		now: NOW,
+		onCheck: () => {},
+		onInstall: () => {},
+		onDismissResult: () => {},
+	},
+	decorators: [
+		(Story) => (
+			<div className="mx-auto max-w-2xl">
+				<Story />
+			</div>
+		),
+	],
+};
+export default meta;
+
+type Story = StoryObj<typeof SelfUpdateSection>;
+
+const withState = (state: SelfUpdateState) => ({ state });
+
+/**
+ * The state this pane is in almost always. One line, no call to action, no
+ * colour — running the latest version is not news.
+ */
+export const UpToDate: Story = {
+	args: withState({
+		status: "upToDate",
+		version: CURRENT,
+		checkedAt: NOW - 21 * 60_000,
+	}),
+};
+
+export const Checking: Story = {
+	args: withState({ status: "checking", version: CURRENT }),
+};
+
+/**
+ * An update exists. It is stated — version, date, one line of what changes, a
+ * link to the full notes — and then it waits. Nothing here follows the user
+ * back to their mail.
+ */
+export const UpdateAvailable: Story = {
+	args: withState({
+		status: "available",
+		version: CURRENT,
+		release: demoRelease,
+	}),
+};
+
+/**
+ * Cannot reach the update source. This is not a failure of the running Remit
+ * and does not dress itself up as one: it names the cause, says the installed
+ * version keeps working, and offers the retry.
+ */
+export const CheckFailedOffline: Story = {
+	args: withState({
+		status: "checkFailed",
+		version: CURRENT,
+		reason: "No route to github.com — the server has no outbound network.",
+		lastCheckedAt: NOW - 3 * 24 * 60 * 60_000,
+	}),
+};
+
+/**
+ * Back on a reachable server, on the new version. Dismissible, and gone for
+ * good once dismissed.
+ */
+export const Succeeded: Story = {
+	args: withState({
+		status: "succeeded",
+		runId: demoRunId,
+		version: demoRelease.version,
+		previousVersion: CURRENT,
+		releaseNotesUrl: demoRelease.releaseNotesUrl,
+	}),
+};
+
+/**
+ * The new version did not start and Remit reports having put the old one back.
+ * The pane repeats that report and no more: a failed migration is exactly the
+ * case where something was changed on the way, so "nothing was lost" is not a
+ * claim this screen is in any position to make.
+ */
+export const RolledBack: Story = {
+	args: withState({
+		status: "rolledBack",
+		runId: demoRunId,
+		version: CURRENT,
+		attemptedVersion: demoRelease.version,
+		reason:
+			'migration 0042_add_thread_index failed: relation "threads" does not exist',
+		logsCommand: demoLogsCommand,
+	}),
+};
+
+/**
+ * An update is running. The blocking screen owns the window; the pane behind it
+ * still says what is going on rather than going blank.
+ */
+export const ApplyingBehindTheOverlay: Story = {
+	args: withState({
+		status: "applying",
+		runId: demoRunId,
+		version: CURRENT,
+		target: demoRelease.version,
+		phase: "restarting",
+		elapsedSeconds: 30,
+	}),
+};
+
+/**
+ * The server answered again after a silence the client could not see into. It
+ * says exactly that, and points at the log rather than guessing.
+ */
+export const RecoveredAfterUnreachable: Story = {
+	args: withState({
+		status: "unreachable",
+		runId: demoRunId,
+		previousVersion: CURRENT,
+		attemptedVersion: demoRelease.version,
+		elapsedSeconds: 420,
+		logsCommand: demoLogsCommand,
+	}),
+};
+
+/**
+ * Consent. Reflects the three things the user will actually feel — the pause,
+ * that mail is untouched, and the automatic way back — before anything is
+ * replaced. "Not now" is always the easiest button to hit.
+ */
+export const ConfirmBeforeInstalling: Story = {
+	render: () => (
+		<SelfUpdateConfirmDialog
+			open
+			currentVersion={CURRENT}
+			release={demoRelease}
+			onClose={() => {}}
+			onConfirm={() => {}}
+		/>
+	),
+};
+
+/**
+ * Consent reached from the pane, and declined. The offer stays exactly where
+ * it was; declining costs nothing and is not asked about again.
+ */
+export const ConsentFlow: Story = {
+	render: () => {
+		const [open, setOpen] = useState(false);
+		const [confirmed, setConfirmed] = useState(false);
+		return (
+			<>
+				<SelfUpdateSection
+					now={NOW}
+					state={{
+						status: "available",
+						version: CURRENT,
+						release: demoRelease,
+					}}
+					onCheck={() => {}}
+					onInstall={() => setOpen(true)}
+					onDismissResult={() => {}}
+				/>
+				{confirmed && (
+					<p className="mt-3 text-xs text-fg-subtle">
+						Consent given — the app hands over to the blocking restart screen
+						here.
+					</p>
+				)}
+				<SelfUpdateConfirmDialog
+					open={open}
+					currentVersion={CURRENT}
+					release={demoRelease}
+					onClose={() => setOpen(false)}
+					onConfirm={() => {
+						setOpen(false);
+						setConfirmed(true);
+					}}
+				/>
+			</>
+		);
+	},
+};
+
+/**
+ * Pressing "Check again" while a check is already running. The control is
+ * never disabled — it no-ops and says why, per the UX tenets.
+ */
+export const PressingCheckWhileChecking: Story = {
+	args: withState({ status: "checking", version: CURRENT }),
+	play: async ({ canvasElement }) => {
+		canvasElement.querySelector<HTMLButtonElement>("button")?.click();
+	},
+};

package/src/components/self-update.ts

@@ -0,0 +1,127 @@
+/**
+ * Self-update state for a Remit you run yourself.
+ *
+ * The server is the thing being replaced, so the UI cannot assume it stays
+ * reachable across the operation. Every state here is one the client can be
+ * left holding on its own, and each names what the user can do next.
+ */
+
+export interface ReleaseInfo {
+	version: string;
+	releasedAt: number;
+	releaseNotesUrl: string;
+	/** One line of plain language, not a changelog dump. */
+	summary: string;
+}
+
+/** Where the operation is between consent and a reachable server again. */
+export type UpdatePhase = "preparing" | "restarting" | "reconnecting";
+
+/**
+ * Identifies one update attempt. The client hands this back after the restart
+ * to ask what became of the run it started — its own memory of the operation
+ * does not survive the operation. Without it a reload mid-update cannot tell an
+ * update in flight from an ordinary server blip.
+ */
+export type UpdateRunId = string;
+
+export type SelfUpdateState =
+	| { status: "upToDate"; version: string; checkedAt: number }
+	| { status: "checking"; version: string }
+	| {
+			status: "checkFailed";
+			version: string;
+			/** Plain-language cause, e.g. "no route to github.com". */
+			reason: string;
+			lastCheckedAt?: number;
+	  }
+	| { status: "available"; version: string; release: ReleaseInfo }
+	| {
+			status: "applying";
+			runId: UpdateRunId;
+			version: string;
+			target: string;
+			phase: UpdatePhase;
+			/** Seconds since the user consented, for honest "still working" copy. */
+			elapsedSeconds: number;
+	  }
+	| {
+			status: "succeeded";
+			runId: UpdateRunId;
+			version: string;
+			previousVersion: string;
+			releaseNotesUrl: string;
+	  }
+	| {
+			status: "rolledBack";
+			runId: UpdateRunId;
+			/** The version running now — the old one, restored. */
+			version: string;
+			attemptedVersion: string;
+			/** The server's own account of the failure, shown verbatim. */
+			reason: string;
+			logsCommand: string;
+	  }
+	| {
+			status: "unreachable";
+			runId: UpdateRunId;
+			previousVersion: string;
+			attemptedVersion: string;
+			elapsedSeconds: number;
+			logsCommand: string;
+	  };
+
+export type SelfUpdateStatus = SelfUpdateState["status"];
+
+const phaseLabels: Record<UpdatePhase, string> = {
+	preparing: "Getting the new version ready",
+	restarting: "Restarting Remit",
+	reconnecting: "Waiting for Remit to answer again",
+};
+
+export function updatePhaseLabel(phase: UpdatePhase): string {
+	return phaseLabels[phase];
+}
+
+/**
+ * The restart takes the server away, so silence is expected for a while. Say so
+ * before the wait feels like a hang, and stop promising once it does. Nothing
+ * here may describe what the server is doing — from a lost connection the
+ * client only knows how long it has been quiet.
+ */
+export function updateWaitNote(elapsedSeconds: number): string {
+	if (elapsedSeconds < 90) return "This usually takes about a minute.";
+	if (elapsedSeconds < 240)
+		return "Longer than usual. Remit is still trying to reach the server.";
+	return "Still no answer. Remit keeps trying.";
+}
+
+export function formatRelativeCheck(
+	checkedAt: number,
+	now: number = Date.now(),
+): string {
+	const minutes = Math.floor((now - checkedAt) / 60_000);
+	if (minutes < 1) return "just now";
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+
+export function formatReleaseDate(epochMillis: number): string {
+	return new Date(epochMillis).toLocaleDateString(undefined, {
+		dateStyle: "medium",
+	});
+}
+
+export const demoRelease: ReleaseInfo = {
+	version: "0.9.4",
+	releasedAt: Date.parse("2026-07-14T09:00:00.000Z"),
+	releaseNotesUrl: "https://github.com/remit-mail/reader/releases/tag/v0.9.4",
+	summary:
+		"Faster first sync on large mailboxes, and search no longer misses mail moved between folders.",
+};
+
+export const demoLogsCommand = "remit logs --since 10m";
+
+export const demoRunId = "upd_8f3c21a7";

package/src/components/spam-results-offer.render.test.ts

@@ -13,7 +13,7 @@ describe("SpamResultsOffer", () => {
 		);
 		assert.match(html, />3</);
 		assert.match(html, /results from Spam/);
-		assert.match(html, /View them/);
+		assert.match(html, /Go to Spam/);
 	});
 
 	it("reads in the singular for one match", () => {

package/src/components/spam-results-offer.tsx

@@ -20,6 +20,12 @@ const plural = (n: number): string => (n === 1 ? "result" : "results");
  * the whole point of the folder is that its contents are unwanted until asked
  * for. Taking the offer scopes the search to Spam.
  *
+ * The count is every match held out; the action opens Spam. It deliberately
+ * does not read "view them", because scope is a single mailbox and a user with
+ * several accounts has several Spam folders — the count would then name more
+ * mail than the click delivers. Saying where the button goes is true whatever
+ * the account setup.
+ *
  * Quiet on purpose: this is an offer, not a warning. Presentational — the
  * caller owns what "scope to spam" does.
  */
@@ -44,7 +50,7 @@ export function SpamResultsOffer({
 					onClick={onScopeToSpam}
 					className="shrink-0 text-accent"
 				>
-					View them
+					Go to Spam
 				</Button>
 			</div>
 		</Banner>

package/src/index.ts

@@ -379,6 +379,38 @@ export {
 	type SelectionTopBarNoticeAction,
 	type SelectionTopBarProps,
 } from "./components/selection-top-bar.js";
+export {
+	demoLogsCommand,
+	demoRelease,
+	demoRunId,
+	formatRelativeCheck,
+	formatReleaseDate,
+	type ReleaseInfo,
+	type SelfUpdateState,
+	type SelfUpdateStatus,
+	type UpdatePhase,
+	type UpdateRunId,
+	updatePhaseLabel,
+	updateWaitNote,
+} from "./components/self-update.js";
+export {
+	SelfUpdateConfirmDialog,
+	type SelfUpdateConfirmDialogProps,
+} from "./components/self-update-confirm-dialog.js";
+export {
+	UpdateAvailableDot,
+	type UpdateAvailableDotProps,
+} from "./components/self-update-dot.js";
+export {
+	SelfUpdateProgressOverlay,
+	type SelfUpdateProgressOverlayProps,
+	SelfUpdateUnreachableScreen,
+	type SelfUpdateUnreachableScreenProps,
+} from "./components/self-update-progress-overlay.js";
+export {
+	SelfUpdateSection,
+	type SelfUpdateSectionProps,
+} from "./components/self-update-section.js";
 export {
 	type SenderGroupOption,
 	SenderGroupSwitch,