@remit/ui 0.0.86 → 0.0.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.86",
+  "version": "0.0.87",
   "type": "module",
   "files": [
     "src"

package/src/components/refresh-button.render.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	RefreshButton,
+	type RefreshButtonProps,
+	type RefreshControlState,
+} from "./refresh-button.js";
+
+const render = (overrides: Partial<RefreshButtonProps> = {}): string =>
+	renderToString(
+		createElement(RefreshButton, {
+			state: "idle",
+			label: "Refresh inbox",
+			onRefresh: () => undefined,
+			...overrides,
+		}),
+	);
+
+const stateOf = (html: string): RefreshControlState =>
+	html.includes("animate-spin")
+		? "refreshing"
+		: /text-danger/.test(html)
+			? "error"
+			: /text-positive/.test(html)
+				? "success"
+				: "idle";
+
+describe("RefreshButton", () => {
+	it("names the plain action when idle", () => {
+		const html = render();
+		assert.match(html, /aria-label="Refresh inbox"/);
+		assert.doesNotMatch(html, /aria-busy/);
+	});
+
+	it("spins and disables while refreshing", () => {
+		const html = render({ state: "refreshing" });
+		assert.equal(stateOf(html), "refreshing");
+		assert.match(html, /disabled=""/);
+		assert.match(html, /aria-busy="true"/);
+		assert.match(html, /aria-label="Refresh inbox — refreshing"/);
+	});
+
+	it("shows a quiet dot for new mail only at rest", () => {
+		const idle = render({ hasUpdate: true });
+		assert.match(idle, /aria-label="Refresh inbox — new mail"/);
+		assert.match(idle, /bg-accent-2/);
+
+		const refreshing = render({ state: "refreshing", hasUpdate: true });
+		assert.doesNotMatch(refreshing, /bg-accent-2/);
+	});
+
+	it("confirms success without claiming a failure", () => {
+		const html = render({ state: "success" });
+		assert.equal(stateOf(html), "success");
+		assert.match(html, /aria-label="Refresh inbox — up to date"/);
+	});
+
+	it("names what failed in the tooltip and the accessible name, never silently", () => {
+		const html = render({
+			state: "error",
+			errorMessage: "Could not reach the server",
+		});
+		assert.equal(stateOf(html), "error");
+		assert.match(
+			html,
+			/aria-label="Refresh inbox — failed: Could not reach the server"/,
+		);
+		assert.match(html, /title="Could not reach the server"/);
+	});
+
+	it("stays clickable on error so the same action can retry", () => {
+		const html = render({ state: "error", errorMessage: "Offline" });
+		assert.doesNotMatch(html, /disabled=""/);
+	});
+});

package/src/components/refresh-button.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { RefreshButton } from "./refresh-button.js";
+
+const meta: Meta<typeof RefreshButton> = {
+	title: "Mail/RefreshButton",
+	component: RefreshButton,
+	args: {
+		label: "Refresh inbox",
+		onRefresh: () => undefined,
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof RefreshButton>;
+
+/** At rest, nothing to report. */
+export const Idle: Story = {
+	args: { state: "idle" },
+};
+
+/** The background poll found new mail; the dot is the whole message — nothing
+ * reloads until this is clicked. */
+export const NewMailAvailable: Story = {
+	args: { state: "idle", hasUpdate: true },
+};
+
+/** A sync round is in flight — the glyph spins and the button won't stack a
+ * second click on top of it. */
+export const Refreshing: Story = {
+	args: { state: "refreshing" },
+};
+
+/** Confirms the refresh landed with nothing left unresolved. */
+export const Success: Story = {
+	args: { state: "success" },
+};
+
+/** The refresh could not be confirmed — a real reason in the tooltip and the
+ * accessible name, and clicking retries the same action. */
+export const Failed: Story = {
+	args: {
+		state: "error",
+		errorMessage: "Couldn't reach the server — check your connection",
+	},
+};
+
+/** All four states side by side. */
+export const AllStates: Story = {
+	render: (args) => (
+		<div className="flex items-center gap-4 p-4">
+			<div className="flex flex-col items-center gap-1 text-2xs text-fg-muted">
+				<RefreshButton {...args} state="idle" />
+				Idle
+			</div>
+			<div className="flex flex-col items-center gap-1 text-2xs text-fg-muted">
+				<RefreshButton {...args} state="idle" hasUpdate />
+				New mail
+			</div>
+			<div className="flex flex-col items-center gap-1 text-2xs text-fg-muted">
+				<RefreshButton {...args} state="refreshing" />
+				Refreshing
+			</div>
+			<div className="flex flex-col items-center gap-1 text-2xs text-fg-muted">
+				<RefreshButton {...args} state="success" />
+				Success
+			</div>
+			<div className="flex flex-col items-center gap-1 text-2xs text-fg-muted">
+				<RefreshButton
+					{...args}
+					state="error"
+					errorMessage="Couldn't reach the server"
+				/>
+				Failed
+			</div>
+		</div>
+	),
+};

package/src/components/refresh-button.tsx

@@ -0,0 +1,93 @@
+import { AlertCircle, CheckCircle, RefreshCw } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { Button, type ButtonProps } from "./button.js";
+
+export type RefreshControlState = "idle" | "refreshing" | "success" | "error";
+
+export interface RefreshButtonProps {
+	state: RefreshControlState;
+	onRefresh: () => void;
+	/** What this refreshes, e.g. "Refresh inbox", "Refresh daily brief". Also the
+	 * retry action's name while `state` is "error". */
+	label: string;
+	/** What failed and the likely fix, shown as the tooltip and appended to the
+	 * accessible name. Required once `state` is "error" — a failure with
+	 * nothing said is a dead button. */
+	errorMessage?: string;
+	/**
+	 * Mail arrived since this was last acted on — the once-a-minute background
+	 * poll's own signal, surfaced as a quiet dot rather than reloading anything.
+	 * Only shown at rest; a refresh already in flight or just finished has
+	 * nothing left to point at.
+	 */
+	hasUpdate?: boolean;
+	size?: ButtonProps["size"];
+	className?: string;
+}
+
+/**
+ * The one refresh control, shared by the inbox header, the daily brief header
+ * and the shell's global refresh — three call sites, one affordance. States:
+ *
+ * - idle: a plain refresh glyph, optionally carrying the "new mail" dot.
+ * - refreshing: the same glyph spinning, disabled — never a second click
+ *   stacked on the one in flight.
+ * - success: a brief checkmark, the caller's cue that nothing was left
+ *   unresolved (reverts to idle on its own after a beat).
+ * - error: an alert glyph naming what failed, in the tooltip and the
+ *   accessible name; clicking it retries the same action. A refresh that
+ *   never answers must land here, not spin forever.
+ */
+export function RefreshButton({
+	state,
+	onRefresh,
+	label,
+	errorMessage,
+	hasUpdate,
+	size = "sm",
+	className,
+}: RefreshButtonProps) {
+	const busy = state === "refreshing";
+	const failed = state === "error";
+	const succeeded = state === "success";
+
+	const icon = failed ? (
+		<AlertCircle className="size-4 text-danger" />
+	) : succeeded ? (
+		<CheckCircle className="size-4 text-positive" />
+	) : (
+		<RefreshCw className={cn("size-4", busy && "animate-spin")} />
+	);
+
+	const accessibleLabel = failed
+		? `${label} — failed: ${errorMessage ?? "try again"}`
+		: busy
+			? `${label} — refreshing`
+			: succeeded
+				? `${label} — up to date`
+				: hasUpdate
+					? `${label} — new mail`
+					: label;
+
+	return (
+		<div className="relative inline-flex">
+			<Button
+				variant="ghost"
+				size={size}
+				icon={icon}
+				onClick={onRefresh}
+				disabled={busy}
+				aria-label={accessibleLabel}
+				aria-busy={busy || undefined}
+				title={failed ? errorMessage : label}
+				className={className}
+			/>
+			{state === "idle" && hasUpdate && (
+				<span
+					aria-hidden="true"
+					className="absolute right-1 top-1 size-1.5 rounded-full bg-accent-2"
+				/>
+			)}
+		</div>
+	);
+}

package/src/components/shell-top-bar.render.test.ts

@@ -26,26 +26,37 @@ const render = (overrides: Partial<ShellTopBarProps> = {}): string =>
 			onCompose: () => undefined,
 			onReportBug: () => undefined,
 			onOpenSettings: () => undefined,
+			refreshControl: createElement(
+				"div",
+				{ "data-testid": "refresh" },
+				"refresh",
+			),
 			account: createElement("div", { "data-testid": "account" }, "account"),
 			...overrides,
 		}),
 	);
 
 describe("ShellTopBar", () => {
-	it("carries compose, bug report, settings and the account, in that order", () => {
+	it("carries compose, bug report, settings, refresh and the account, in that order", () => {
 		const html = render();
 		const compose = html.indexOf('aria-label="Compose"');
 		const bug = html.indexOf('aria-label="Report a bug"');
 		const settings = html.indexOf('aria-label="Settings"');
+		const refresh = html.indexOf('data-testid="refresh"');
 		const account = html.indexOf('data-testid="account"');
-		assert.ok(compose > -1 && bug > -1 && settings > -1 && account > -1);
 		assert.ok(
-			compose < bug && bug < settings && settings < account,
+			compose > -1 && bug > -1 && settings > -1 && refresh > -1 && account > -1,
+		);
+		assert.ok(
+			compose < bug &&
+				bug < settings &&
+				settings < refresh &&
+				refresh < account,
 			"actions render in reading order",
 		);
 	});
 
-	it("carries exactly the four actions and nothing else", () => {
+	it("carries exactly these aria-labelled elements and nothing else — the refresh control and account slot are opaque children, named by whatever the caller passes in", () => {
 		const labels = [...render().matchAll(/aria-label="([^"]+)"/g)].map(
 			(match) => match[1],
 		);

package/src/components/shell-top-bar.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
 import { Avatar } from "./avatar.js";
+import { RefreshButton, type RefreshControlState } from "./refresh-button.js";
 import type { SearchChip } from "./search-chip-input.js";
 import { type ShellSearchScope, ShellTopBar } from "./shell-top-bar.js";
 
@@ -21,12 +22,25 @@ const Account = () => (
 	</button>
 );
 
+const GlobalRefresh = ({ state = "idle" }: { state?: RefreshControlState }) => (
+	<RefreshButton
+		state={state}
+		label="Refresh all accounts"
+		errorMessage={
+			state === "error" ? "2 of 3 accounts couldn't be reached" : undefined
+		}
+		onRefresh={() => undefined}
+	/>
+);
+
 const Bar = ({
 	initialChips,
 	scope = "global",
+	refreshState = "idle",
 }: {
 	initialChips?: SearchChip[];
 	scope?: ShellSearchScope;
+	refreshState?: RefreshControlState;
 }) => {
 	const [chips, setChips] = useState<SearchChip[] | undefined>(initialChips);
 	const [value, setValue] = useState("");
@@ -48,6 +62,7 @@ const Bar = ({
 			onReportBug={() => undefined}
 			onOpenSettings={() => undefined}
 			composeShortcut="c"
+			refreshControl={<GlobalRefresh state={refreshState} />}
 			account={<Account />}
 		/>
 	);
@@ -92,6 +107,7 @@ export const ScopePending: Story = {
 			onReportBug={() => undefined}
 			onOpenSettings={() => undefined}
 			composeShortcut="c"
+			refreshControl={<GlobalRefresh />}
 			account={<Account />}
 		/>
 	),
@@ -111,6 +127,22 @@ export const ScopedToFlagged: Story = {
 	),
 };
 
+/**
+ * The global refresh mid-flight — every connected account syncing at once,
+ * next to the avatar it sits beside.
+ */
+export const RefreshingAllAccounts: Story = {
+	render: () => <Bar refreshState="refreshing" />,
+};
+
+/**
+ * At least one account couldn't be reached. The tooltip and accessible name
+ * say so; the button stays clickable to retry.
+ */
+export const RefreshFailed: Story = {
+	render: () => <Bar refreshState="error" />,
+};
+
 /** The arrangement: one bar across the top of the shell, over every pane. */
 export const OverTheLayout: Story = {
 	render: () => (

package/src/components/shell-top-bar.tsx

@@ -64,6 +64,12 @@ export interface ShellTopBarProps {
 	 * `g then b`. The tooltip's wording around it is this component's.
 	 */
 	composeShortcut?: string;
+	/**
+	 * The global refresh — every connected account, one control, next to the
+	 * avatar it sits beside. An element, like `account`: the app owns which
+	 * accounts it reaches and what refreshing them means.
+	 */
+	refreshControl: ReactNode;
 	/**
 	 * The account control at the bar's trailing edge. An element rather than
 	 * data: the app hangs a signed-in session and its sign-out off it.
@@ -77,6 +83,7 @@ export function ShellTopBar({
 	onReportBug,
 	onOpenSettings,
 	composeShortcut,
+	refreshControl,
 	account,
 }: ShellTopBarProps) {
 	return (
@@ -119,6 +126,7 @@ export function ShellTopBar({
 						aria-label="Settings"
 						onClick={onOpenSettings}
 					/>
+					{refreshControl}
 					{account}
 				</>
 			}

package/src/index.ts

@@ -407,6 +407,11 @@ export {
 	ReadingPaneEmpty,
 	type ReadingPaneEmptyProps,
 } from "./components/reading-pane-empty.js";
+export {
+	RefreshButton,
+	type RefreshButtonProps,
+	type RefreshControlState,
+} from "./components/refresh-button.js";
 export {
 	RescueBanner,
 	type RescueBannerProps,