@remit/ui 0.0.21 → 0.0.22

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/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,