@remit/web-client 0.0.13 → 0.0.15

package/src/lib/api.ts

@@ -1,3 +1,5 @@
+import { taggedFetch } from "./network-error";
+
 export class ApiError extends Error {
 	constructor(
 		message: string,
@@ -38,7 +40,7 @@ const request = async <T>(
 
 	const url = buildUrl(path, params);
 
-	const response = await fetch(url, {
+	const response = await taggedFetch(url, {
 		method,
 		headers: {
 			"Content-Type": "application/json",

package/src/lib/client.ts

@@ -1,6 +1,7 @@
 import { client } from "@remit/api-http-client/client.gen.ts";
 import { getRuntimeConfig } from "../runtime-config";
 import { ApiError } from "./api";
+import { taggedFetch } from "./network-error";
 
 // In production, the config.js apiUrl points at the deployed API Gateway.
 // In local dev, the Vite proxy forwards /api -> localhost:4321 (see vite.config.ts).
@@ -8,6 +9,8 @@ const baseUrl = getRuntimeConfig().apiUrl;
 
 client.setConfig({
 	baseUrl,
+	// Transport failures are tagged where they happen; see `network-error.ts`.
+	fetch: taggedFetch,
 });
 
 /**

package/src/lib/error-classifier.test.ts

@@ -5,10 +5,18 @@ import {
 	getErrorStatus,
 	hasHttpStatus,
 	isAbortError,
+	isClientBug,
 	isNetworkError,
 	isServerError,
 	shouldEscalate,
 } from "./error-classifier";
+import { NetworkError, taggedFetch } from "./network-error";
+
+const timeoutError = (): Error => {
+	const error = new Error("The operation timed out.");
+	error.name = "TimeoutError";
+	return error;
+};
 
 const abortError = (): Error => {
 	const error = new Error("aborted");
@@ -75,9 +83,31 @@ describe("isAbortError", () => {
 });
 
 describe("isNetworkError", () => {
-	it("is true for a statusless transport failure", () => {
-		assert.equal(isNetworkError(new TypeError("Failed to fetch")), true);
-		assert.equal(isNetworkError(new Error("network down")), true);
+	// The boundary tags the failure, so the browser's wording never matters.
+	// These are the real rejections `fetch` produces, across engines — every one
+	// of them has to stay soft, whatever it happens to say.
+	const transportFailures = [
+		new TypeError("Failed to fetch"), // Chrome, Edge
+		new TypeError("NetworkError when attempting to fetch resource."), // Firefox
+		new TypeError("Load failed"), // WebKit
+		new TypeError("The network connection was lost."), // WebKit, wifi dropped
+		new TypeError("The request timed out."), // WebKit
+		new TypeError("fetch failed"), // undici
+		new Error("something no engine has said yet"),
+	];
+
+	it("is true for anything the fetch boundary tagged, whatever it says", () => {
+		for (const failure of transportFailures) {
+			assert.equal(
+				isNetworkError(new NetworkError(failure)),
+				true,
+				`"${failure.message}" must stay soft`,
+			);
+		}
+	});
+
+	it("is true for a timeout — a timeout is a transport failure", () => {
+		assert.equal(isNetworkError(new NetworkError(timeoutError())), true);
 	});
 
 	it("is false for an aborted request (its own category)", () => {
@@ -88,6 +118,108 @@ describe("isNetworkError", () => {
 		assert.equal(isNetworkError(new ApiError("boom", 500)), false);
 		assert.equal(isNetworkError(new ApiError("not found", 404)), false);
 	});
+
+	it("is false for an exception thrown by our own code", () => {
+		assert.equal(
+			isNetworkError(
+				new TypeError('can\'t access property "map", x is undefined'),
+			),
+			false,
+		);
+	});
+
+	it("does not mistake an untagged error for transport just because it reads like one", () => {
+		// A bug whose message happens to contain a fetch-failure phrase is still a
+		// bug. Only the boundary gets to say otherwise.
+		assert.equal(isNetworkError(new TypeError("Failed to fetch")), false);
+	});
+});
+
+describe("taggedFetch — where the decision is actually made", () => {
+	const withFetch = async (
+		impl: typeof fetch,
+		run: () => Promise<void>,
+	): Promise<void> => {
+		const original = globalThis.fetch;
+		globalThis.fetch = impl;
+		try {
+			await run();
+		} finally {
+			globalThis.fetch = original;
+		}
+	};
+
+	it("tags every transport rejection, regardless of its message", async () => {
+		for (const message of [
+			"Failed to fetch",
+			"The network connection was lost.",
+			"fetch failed",
+			"anything at all",
+		]) {
+			await withFetch(
+				() => Promise.reject(new TypeError(message)),
+				async () => {
+					const error = await taggedFetch("/x").catch((e: unknown) => e);
+					assert.ok(error instanceof NetworkError);
+					assert.equal(isNetworkError(error), true);
+					assert.equal(shouldEscalate(error), false);
+				},
+			);
+		}
+	});
+
+	it("tags a timeout, because a timeout never reached a server", async () => {
+		await withFetch(
+			() => Promise.reject(timeoutError()),
+			async () => {
+				const error = await taggedFetch("/x").catch((e: unknown) => e);
+				assert.ok(error instanceof NetworkError);
+				assert.equal(shouldEscalate(error), false);
+			},
+		);
+	});
+
+	it("leaves a deliberate abort untagged — it is not a failure", async () => {
+		await withFetch(
+			() => Promise.reject(abortError()),
+			async () => {
+				const error = await taggedFetch("/x").catch((e: unknown) => e);
+				assert.ok(!(error instanceof NetworkError));
+				assert.equal(isAbortError(error), true);
+			},
+		);
+	});
+
+	it("passes a response through untouched, including an error status", async () => {
+		const response = new Response("nope", { status: 500 });
+		await withFetch(
+			() => Promise.resolve(response),
+			async () => {
+				assert.equal(await taggedFetch("/x"), response);
+			},
+		);
+	});
+});
+
+describe("isClientBug", () => {
+	it("is true for an exception raised inside our own code", () => {
+		assert.equal(
+			isClientBug(
+				new TypeError('can\'t access property "map", x is undefined'),
+			),
+			true,
+		);
+	});
+
+	it("is false for a request that reached, or failed to reach, a server", () => {
+		assert.equal(isClientBug(new ApiError("boom", 500)), false);
+		assert.equal(isClientBug(new ApiError("not found", 404)), false);
+		assert.equal(
+			isClientBug(new NetworkError(new TypeError("Failed to fetch"))),
+			false,
+		);
+		assert.equal(isClientBug(abortError()), false);
+	});
 });
 
 describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
@@ -119,15 +251,31 @@ describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
 		assert.equal(shouldEscalate(abortError()), false);
 	});
 
-	it("does NOT escalate a statusless network/offline blip", () => {
-		assert.equal(shouldEscalate(new TypeError("Failed to fetch")), false);
-		assert.equal(shouldEscalate(new Error("network down")), false);
+	it("does NOT escalate a network/offline blip", () => {
+		assert.equal(
+			shouldEscalate(new NetworkError(new TypeError("Failed to fetch"))),
+			false,
+		);
+		assert.equal(
+			shouldEscalate(
+				new NetworkError(new TypeError("The network connection was lost.")),
+			),
+			false,
+		);
 	});
 
-	it("a statusless error is soft regardless of meta", () => {
+	it("a network error is soft regardless of meta", () => {
 		assert.equal(
-			shouldEscalate(new TypeError("Failed to fetch"), { softError: false }),
+			shouldEscalate(new NetworkError(new TypeError("Failed to fetch")), {
+				softError: false,
+			}),
 			false,
 		);
 	});
+
+	it("escalates an exception thrown by our own code, softError or not", () => {
+		const bug = new TypeError('can\'t access property "map", x is undefined');
+		assert.equal(shouldEscalate(bug), true);
+		assert.equal(shouldEscalate(bug, { softError: true }), true);
+	});
 });

package/src/lib/error-classifier.ts

@@ -1,4 +1,5 @@
 import { ApiError } from "./api";
+import { NetworkError } from "./network-error";
 
 /**
  * Extract an HTTP status code from a thrown error, regardless of which client
@@ -55,14 +56,50 @@ export const isAbortError = (error: unknown): boolean => {
 	return false;
 };
 
+const isOffline = (): boolean =>
+	typeof navigator !== "undefined" && navigator.onLine === false;
+
+/**
+ * A transport failure from a wifi drop, tab wake, captive portal, or a timeout:
+ * the request never reached a server, so it is environmental, not a proven
+ * first-party failure.
+ *
+ * This is decided at the fetch boundary, not inferred here. Every app-owned
+ * request goes through `taggedFetch`, which knows a `fetch()` rejection is
+ * transport-level because `fetch` rejects for no other reason, and tags it a
+ * `NetworkError`. Reading that tag is exact; matching browser failure strings
+ * was not — the list is open-ended (WebKit alone has four, undici another) and
+ * anything missed would put a full-screen fatal page in front of someone who
+ * had merely walked out of wifi range.
+ *
+ * `navigator.onLine === false` is kept as a second signal for an error that
+ * reached us from outside that boundary while the browser reports no
+ * connectivity at all.
+ */
+export const isNetworkError = (error: unknown): boolean => {
+	if (isAbortError(error)) return false;
+	if (hasHttpStatus(error)) return false;
+	if (error instanceof NetworkError) return true;
+	return isOffline();
+};
+
+/**
+ * An exception raised by our own client code rather than by a request: it
+ * carries no HTTP status, is not an abort, and was not tagged as transport.
+ * That leaves a programming error — the one class the user can do nothing
+ * about and must never be asked to shrug off.
+ */
+export const isClientBug = (error: unknown): boolean =>
+	!hasHttpStatus(error) && !isAbortError(error) && !isNetworkError(error);
+
 /**
- * A statusless transport/network failure (`TypeError: Failed to fetch` from a
- * wifi drop, tab wake, captive portal, or a background refetch): the request
- * never reached a server, so it is environmental, not a proven first-party
- * failure. Excludes deliberate aborts (also statusless, but their own category).
+ * Fatal with no opt-out: our API answered "I'm broken", or our own code threw.
+ * Neither is something a call site can reclassify as soft, and neither may be
+ * reduced to a dismissible banner — both belong on the full-screen page, which
+ * offers a way forward and a bug report (issue #55).
  */
-export const isNetworkError = (error: unknown): boolean =>
-	!isAbortError(error) && !hasHttpStatus(error);
+export const isAlwaysFatal = (error: unknown): boolean =>
+	isServerError(error) || isClientBug(error);
 
 const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 	meta?.softError === true;
@@ -76,10 +113,12 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
  *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
  *     refetch, even when the call site marked `meta.softError`. Our API
  *     answered "I'm broken"; that is never benign.
- *  3. The ONLY soft (do-NOT-escalate) exemptions:
+ *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
+ *     bug; there is nothing for the user to retry and nothing to dismiss.
+ *  4. The ONLY soft (do-NOT-escalate) exemptions:
  *     a. aborts / cancellations — never a failure;
- *     b. statusless network/offline errors — environmental, recovered by React
- *        Query's reconnect/retry;
+ *     b. network/offline errors — environmental, recovered by React Query's
+ *        reconnect/retry;
  *     c. a non-5xx error on a query/mutation that opted out via
  *        `meta.softError === true` — the call site owns that error's UX
  *        (e.g. a 404 empty state, a 4xx "Reconnect" banner).
@@ -91,6 +130,7 @@ export const shouldEscalate = (
 	if (isServerError(error)) return true;
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
+	if (isAlwaysFatal(error)) return true;
 	if (isSoftErrorMeta(meta)) return false;
 	return true;
 };

package/src/lib/keymap-dispatch.test.ts

@@ -12,6 +12,7 @@ const stroke = (partial: Partial<KeyStroke> & { key: string }): KeyStroke => ({
 	ctrlKey: false,
 	altKey: false,
 	inEditable: false,
+	onControl: false,
 	...partial,
 });
 
@@ -61,6 +62,82 @@ describe("dispatchKey — plain bindings", () => {
 	});
 });
 
+describe("dispatchKey — list navigation", () => {
+	const cases: Array<[string, string]> = [
+		["ArrowDown", "focusNext"],
+		["ArrowUp", "focusPrevious"],
+		["Home", "focusFirst"],
+		["End", "focusLast"],
+		[" ", "toggleSelect"],
+		["Delete", "delete"],
+		["Backspace", "delete"],
+	];
+
+	for (const [key, action] of cases) {
+		test(`'${key}' → ${action}`, () => {
+			const result = run({ key });
+			assert.strictEqual(result.action, action);
+			assert.strictEqual(result.preventDefault, true);
+		});
+	}
+
+	test("Shift+Arrow extends the selection instead of moving the cursor", () => {
+		assert.strictEqual(
+			run({ key: "ArrowDown", shiftKey: true }).action,
+			"extendSelectDown",
+		);
+		assert.strictEqual(
+			run({ key: "ArrowUp", shiftKey: true }).action,
+			"extendSelectUp",
+		);
+	});
+
+	test("⌘A / Ctrl+A selects every loaded row", () => {
+		assert.strictEqual(run({ key: "a", metaKey: true }).action, "selectAll");
+		assert.strictEqual(run({ key: "a", ctrlKey: true }).action, "selectAll");
+		assert.strictEqual(
+			run({ key: "a", metaKey: true }).preventDefault,
+			true,
+			"the browser's select-all-text default must be replaced",
+		);
+	});
+});
+
+describe("dispatchKey — controls keep their activation keys", () => {
+	// The regression behind #43: a global Enter binding cancelled the default
+	// action of whatever the user had tabbed to, so no button in the app could
+	// be activated from the keyboard.
+	test("Enter on a focused control is left to the control", () => {
+		const result = run({ key: "Enter", onControl: true });
+		assert.strictEqual(result.action, null);
+		assert.strictEqual(result.preventDefault, false);
+	});
+
+	test("Space on a focused control is left to the control", () => {
+		const result = run({ key: " ", onControl: true });
+		assert.strictEqual(result.action, null);
+		assert.strictEqual(result.preventDefault, false);
+	});
+
+	test("Enter and Space still drive the list away from a control", () => {
+		assert.strictEqual(run({ key: "Enter" }).action, "openFocused");
+		assert.strictEqual(run({ key: " " }).action, "toggleSelect");
+	});
+
+	test("non-activation keys still fire from a focused control", () => {
+		// Tabbing to a toolbar button must not strand the rest of the keymap.
+		assert.strictEqual(run({ key: "j", onControl: true }).action, "focusNext");
+		assert.strictEqual(run({ key: "r", onControl: true }).action, "reply");
+	});
+
+	test("an Enter released to a control still cancels a pending g prefix", () => {
+		assert.strictEqual(
+			run({ key: "Enter", onControl: true }, "g").nextPrefix,
+			null,
+		);
+	});
+});
+
 describe("dispatchKey — input suppression", () => {
 	test("plain keys are inert in an editable surface", () => {
 		assert.strictEqual(run({ key: "j", inEditable: true }).action, null);
@@ -98,8 +175,8 @@ describe("dispatchKey — modifiers", () => {
 	});
 
 	test("other meta combos are left to the browser", () => {
-		assert.strictEqual(run({ key: "a", metaKey: true }).action, null);
 		assert.strictEqual(run({ key: "c", metaKey: true }).action, null);
+		assert.strictEqual(run({ key: "f", metaKey: true }).action, null);
 	});
 
 	test("Shift+J / Shift+K extend the selection", () => {

package/src/lib/keymap-dispatch.ts

@@ -19,6 +19,15 @@ export interface KeyStroke {
 	altKey: boolean;
 	/** Whether the event originated inside an editable surface. */
 	inEditable: boolean;
+	/**
+	 * Whether the event originated on an activatable control that is not a
+	 * message-list row — a button, link, `role="button"`, `<summary>`. Enter and
+	 * Space are that control's activation keys, so the layer releases them; every
+	 * other binding still fires. Without this a global Enter binding cancels the
+	 * default action of whatever the user tabbed to, and no button in the app can
+	 * be activated from the keyboard.
+	 */
+	onControl: boolean;
 }
 
 /** Pending sequence-prefix state. `"g"` means a `g` was pressed recently. */
@@ -69,7 +78,14 @@ interface PlainBinding {
 const PLAIN_BINDINGS: Record<string, PlainBinding> = {
 	j: { action: "focusNext" },
 	k: { action: "focusPrevious" },
+	arrowdown: { action: "focusNext" },
+	arrowup: { action: "focusPrevious" },
+	home: { action: "focusFirst" },
+	end: { action: "focusLast" },
 	enter: { action: "openFocused" },
+	" ": { action: "toggleSelect" },
+	delete: { action: "delete" },
+	backspace: { action: "delete" },
 	u: { action: "toggleRead" },
 	x: { action: "toggleSelect" },
 	r: { action: "reply" },
@@ -118,12 +134,26 @@ export function dispatchKey(
 		return { ...NONE, nextPrefix: prefix === "g" ? null : prefix };
 	}
 
+	// Enter / Space belong to whatever control has focus. Releasing them here is
+	// what keeps Tab-to-a-button-then-Enter working anywhere in the app; the
+	// list's own rows are excluded from `onControl`, so the roving cursor still
+	// opens and selects.
+	if (stroke.onControl && (lower === "enter" || lower === " ")) {
+		return { ...NONE, nextPrefix: prefix === "g" ? null : prefix };
+	}
+
 	// ⌘N / Ctrl+N → compose. Checked before the prefix/plain tables so the
 	// browser's "new window" is the only thing we intercept among meta combos.
 	if (meta && lower === "n") {
 		return { action: "compose", nextPrefix: null, preventDefault: true };
 	}
 
+	// ⌘A / Ctrl+A → select every loaded row, replacing the browser's
+	// select-all-text default.
+	if (meta && lower === "a") {
+		return { action: "selectAll", nextPrefix: null, preventDefault: true };
+	}
+
 	// Any other meta/ctrl combo is left to the browser/OS.
 	if (meta) return { ...NONE, nextPrefix: prefix === "g" ? null : prefix };
 
@@ -145,13 +175,17 @@ export function dispatchKey(
 		return { action: null, nextPrefix: "g", preventDefault: true };
 	}
 
-	// Shift+J / Shift+K extend the selection.
-	if (stroke.shiftKey && (lower === "j" || lower === "k")) {
-		return {
-			action: lower === "j" ? "extendSelectDown" : "extendSelectUp",
-			nextPrefix: null,
-			preventDefault: true,
-		};
+	// Shift+J/K and Shift+Arrow extend the selection.
+	if (stroke.shiftKey) {
+		const down = lower === "j" || lower === "arrowdown";
+		const up = lower === "k" || lower === "arrowup";
+		if (down || up) {
+			return {
+				action: down ? "extendSelectDown" : "extendSelectUp",
+				nextPrefix: null,
+				preventDefault: true,
+			};
+		}
 	}
 
 	// Plain single-key bindings.
@@ -185,3 +219,26 @@ export function isEditableTarget(target: EventTarget | null): boolean {
 		target.isContentEditable
 	);
 }
+
+/**
+ * Marks an element as a message-list row. Rows are anchors, so they would
+ * otherwise read as ordinary controls; the list owns Enter/Space on them.
+ */
+export const ROW_ATTRIBUTE = "data-message-row";
+
+const CONTROL_SELECTOR =
+	'button, a[href], summary, [role="button"], [role="menuitem"], [role="tab"], [role="switch"], [role="checkbox"]';
+
+/**
+ * Whether the event target sits inside an activatable control that is not a
+ * message-list row. See {@link KeyStroke.onControl}.
+ */
+export function isControlTarget(target: EventTarget | null): boolean {
+	if (!(target instanceof HTMLElement)) return false;
+	const control = target.closest(CONTROL_SELECTOR);
+	if (!control) return false;
+	// The nearest control wins. A row is an anchor and so matches the selector,
+	// but the list owns Enter/Space on its rows; a control nested *inside* a row
+	// (the select checkbox) is a control like any other and keeps its own keys.
+	return !control.hasAttribute(ROW_ATTRIBUTE);
+}

package/src/lib/keymap.ts

@@ -13,12 +13,15 @@ export type TriageAction =
 	// list navigation / focus model
 	| "focusNext"
 	| "focusPrevious"
+	| "focusFirst"
+	| "focusLast"
 	| "openFocused"
 	| "back"
 	// selection
 	| "toggleSelect"
 	| "extendSelectDown"
 	| "extendSelectUp"
+	| "selectAll"
 	// message verbs (focused row / selection)
 	| "reply"
 	| "replyAll"
@@ -76,6 +79,14 @@ export const KEY_HINT_GROUPS: KeyHintGroup[] = [
 				keys: ["k"],
 				description: "Focus previous message",
 			},
+			{ action: "focusNext", keys: ["↓"], description: "Focus next message" },
+			{
+				action: "focusPrevious",
+				keys: ["↑"],
+				description: "Focus previous message",
+			},
+			{ action: "focusFirst", keys: ["Home"], description: "Focus first" },
+			{ action: "focusLast", keys: ["End"], description: "Focus last" },
 			{
 				action: "openFocused",
 				keys: ["Enter"],
@@ -88,6 +99,7 @@ export const KEY_HINT_GROUPS: KeyHintGroup[] = [
 		title: "Selection",
 		hints: [
 			{ action: "toggleSelect", keys: ["x"], description: "Toggle select" },
+			{ action: "toggleSelect", keys: ["Space"], description: "Toggle select" },
 			{
 				action: "extendSelectDown",
 				keys: ["Shift", "j"],
@@ -98,6 +110,17 @@ export const KEY_HINT_GROUPS: KeyHintGroup[] = [
 				keys: ["Shift", "k"],
 				description: "Extend selection up",
 			},
+			{
+				action: "extendSelectDown",
+				keys: ["Shift", "↓"],
+				description: "Extend selection down",
+			},
+			{
+				action: "extendSelectUp",
+				keys: ["Shift", "↑"],
+				description: "Extend selection up",
+			},
+			{ action: "selectAll", keys: ["⌘", "A"], description: "Select all" },
 		],
 	},
 	{

package/src/lib/list-focus.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { tabStopId } from "./list-focus.ts";
+
+const ids = ["a", "b", "c"];
+
+describe("tabStopId", () => {
+	test("the cursor row holds the tab stop", () => {
+		assert.strictEqual(tabStopId(ids, "b"), "b");
+	});
+
+	test("an untouched list puts the tab stop on the first row", () => {
+		assert.strictEqual(tabStopId(ids, undefined), "a");
+	});
+
+	test("a cursor that no longer exists falls back to the first row", () => {
+		// After a delete or a refetch the cursor can name a row that is gone; the
+		// list must keep a tab stop or Tab skips over it entirely.
+		assert.strictEqual(tabStopId(ids, "zzz"), "a");
+	});
+
+	test("an empty list has no tab stop", () => {
+		assert.strictEqual(tabStopId([], "a"), undefined);
+	});
+});

package/src/lib/list-focus.ts

@@ -0,0 +1,24 @@
+/**
+ * Roving-tabindex math for the message list.
+ *
+ * A virtualized list of hundreds of rows must expose exactly one tab stop:
+ * Tab then moves focus into the list at the keyboard cursor and Shift+Tab moves
+ * back out to the side panel, instead of walking every row. Pure so the rule is
+ * testable without a DOM.
+ */
+
+/**
+ * The id of the row that holds the list's tab stop. The keyboard cursor owns it
+ * while it points at a loaded row; otherwise the first row does, so an untouched
+ * list is still reachable with one Tab.
+ */
+export function tabStopId(
+	orderedIds: string[],
+	focusedId: string | undefined,
+): string | undefined {
+	if (orderedIds.length === 0) return undefined;
+	if (focusedId !== undefined && orderedIds.includes(focusedId)) {
+		return focusedId;
+	}
+	return orderedIds[0];
+}