@remit/web-client 0.0.1

package/src/hooks/useIntelligenceData.ts

@@ -0,0 +1,284 @@
+import {
+	addressOperationsSearchAddressesOptions,
+	semanticSearchOperationsSemanticSearchOptions,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapAddressResponse,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type {
+	AuthenticityIntel,
+	IntelligenceData,
+	MatchedChunk,
+	SenderFlagsIntel,
+	SenderIntel,
+	SimilarMessageIntel,
+} from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { isServerError } from "@/lib/error-classifier";
+import { formatDate, formatEmailDate } from "@/lib/format";
+
+/**
+ * Format a creation timestamp as a human-readable "first seen" label.
+ * - Today: "today"
+ * - Otherwise: "Jan 2025"
+ */
+function formatFirstSeenLabel(createdAtMs: number): string {
+	const d = new Date(createdAtMs);
+	const now = new Date();
+	if (d.toDateString() === now.toDateString()) return "today";
+	return formatDate(d, { month: "short", year: "numeric" });
+}
+
+/**
+ * A sender address we cannot read: empty, missing the `@`, or whose domain
+ * part carries no dot (catches placeholders like `missing_domain` and other
+ * junk). Structural — never a hard-coded literal.
+ */
+export function isSenderAddressUnverifiable(
+	fromEmail: string | undefined,
+): boolean {
+	if (!fromEmail) return true;
+	const [, domain] = fromEmail.split("@");
+	if (!domain) return true;
+	return !domain.includes(".");
+}
+
+const NO_SIGNAL_SUMMARY =
+	"We can't verify the sender of this email, which could mean it's from an insecure source.";
+
+const UNREADABLE_SENDER_SUMMARY =
+	"We couldn't read this sender's address, so we can't confirm who really sent this message.";
+
+/**
+ * Build sender intel from the thread message and address lookup.
+ *
+ * Engagement counters (`inboundCount`/`replyCount`) are passed through
+ * as-is from the address response. When absent (`undefined`) they remain
+ * `undefined` so the `SenderCard` engagement clause is suppressed rather
+ * than rendering a misleading "0 received" next to an earned trust badge.
+ */
+export function buildSenderIntel(
+	thread: RemitImapThreadMessageResponse,
+	address: RemitImapAddressResponse | undefined,
+): SenderIntel {
+	return {
+		name: thread.fromName ?? thread.fromEmail ?? "Unknown",
+		email: thread.fromEmail ?? "",
+		trust: thread.senderTrust,
+		firstSeenLabel: address
+			? formatFirstSeenLabel(address.createdAt)
+			: "unknown",
+		// Pass counters through as-is. undefined stays undefined so the panel
+		// suppresses the engagement clause when data is absent.
+		inboundCount: address?.inboundCount,
+		replyCount: address?.replyCount,
+		addressUnverified: isSenderAddressUnverifiable(thread.fromEmail),
+	};
+}
+
+/**
+ * Build sender flags from the address response.
+ */
+function buildSenderFlags(
+	address: RemitImapAddressResponse | undefined,
+): SenderFlagsIntel {
+	if (!address?.flags) return {};
+	return {
+		vip: address.flags.vip?.value === true,
+		muted: address.flags.muted?.value === true,
+		blocked: address.flags.blocked?.value === true,
+		unsubscribed: address.flags.unsubscribed?.value === true,
+	};
+}
+
+/**
+ * Build authenticity intel from the thread message's authenticity field.
+ *
+ * `similarCount` is the number of semantic-search lookalikes; the panel uses
+ * it to render the "N similar messages" campaign-reveal CTA inside the
+ * danger panel. Passed in because it is derived from the semantic-search
+ * result, not the thread row.
+ */
+export function buildAuthenticityIntel(
+	thread: RemitImapThreadMessageResponse,
+	similarCount: number,
+): AuthenticityIntel {
+	const surfacedSimilar = similarCount > 0 ? similarCount : undefined;
+
+	if (isSenderAddressUnverifiable(thread.fromEmail)) {
+		return {
+			verdict: "mismatch",
+			fromDomain: "",
+			addressUnreadable: true,
+			summary: UNREADABLE_SENDER_SUMMARY,
+			similarCount: surfacedSimilar,
+		};
+	}
+
+	const auth = thread.authenticity;
+	if (!auth) {
+		return {
+			verdict: "caution",
+			fromDomain: thread.fromEmail?.split("@")[1] ?? "",
+			summary: NO_SIGNAL_SUMMARY,
+		};
+	}
+	if (!auth.dkimMismatch) {
+		return {
+			verdict: "aligned",
+			fromDomain: auth.fromDomain,
+			dkimDomain: auth.dkimDomain,
+			summary: auth.dkimDomain
+				? `We verified this message was really sent by ${auth.fromDomain}.`
+				: `Nothing looks unusual about this sender.`,
+		};
+	}
+
+	const fromDomain = auth.fromDomain;
+	const dkimDomain = auth.dkimDomain;
+	const claimedBrand =
+		thread.fromName && thread.fromName !== thread.fromEmail
+			? thread.fromName
+			: undefined;
+	const summary = claimedBrand
+		? `The display name claims "${claimedBrand}", but this message was actually sent from ${dkimDomain ?? "another sender"} — not ${fromDomain}. Real senders use their own address.`
+		: `This message claims to be from ${fromDomain}, but it was actually sent from ${dkimDomain ?? "a different sender"}.`;
+	return {
+		verdict: "mismatch",
+		fromDomain,
+		dkimDomain,
+		claimedBrand,
+		summary,
+		// Surface the lookalike count so the panel renders the "N similar
+		// messages" campaign-reveal button.
+		similarCount: surfacedSimilar,
+	};
+}
+
+export interface UseIntelligenceDataResult {
+	data: IntelligenceData | null;
+	/**
+	 * True while similar-messages fetch is in flight. The rest of the data
+	 * (sender, authenticity, category, flags) arrives synchronously from the
+	 * already-loaded thread row.
+	 */
+	isSimilarLoading: boolean;
+	/** Non-null when the similar-messages fetch failed. */
+	similarError: unknown;
+	/**
+	 * True when the similar-messages failure is a fatal first-party 5xx. The
+	 * global escalation overlay handles it; the panel must NOT degrade it to the
+	 * benign grey "Similarity search unavailable" label. A soft (non-fatal)
+	 * error or an empty result keeps the panel quiet.
+	 */
+	similarErrorIsFatal: boolean;
+	/**
+	 * True when the address lookup failed with a fatal first-party 5xx. The panel
+	 * must not silently render the sender's flags (VIP/muted/blocked) as absent —
+	 * that misrepresents the sender's real state. Escalation covers it.
+	 */
+	addressErrorIsFatal: boolean;
+	/** Address id for the sender — needed for PATCH /addresses/{id} mutations. */
+	addressId: string | undefined;
+	/**
+	 * Raw address response for the sender — forwarded to the quick-action
+	 * mutation hooks so they can optimistically patch the cache.
+	 */
+	address: RemitImapAddressResponse | undefined;
+}
+
+/**
+ * Maps a `RemitImapThreadMessageResponse` into `IntelligenceData` for the
+ * `IntelligencePanel` component. Three data sources:
+ *
+ * 1. The thread row itself (already loaded) → sender basics, trust, authenticity, category.
+ * 2. `GET /addresses/search?q=<email>` → address flags (VIP/muted/blocked/etc.)
+ *    and first-seen timestamp. One round-trip per unique sender.
+ * 3. `GET /search/semantic` → similar messages. Last to arrive; sidebar still
+ *    renders if this fails.
+ */
+export function useIntelligenceData(
+	thread: RemitImapThreadMessageResponse | null | undefined,
+	currentMailboxId?: string,
+): UseIntelligenceDataResult {
+	const senderEmail = thread?.fromEmail ?? null;
+	const subject = thread?.subject ?? "";
+
+	// --- Address lookup: flags + first-seen timestamp ---
+	const { data: addressSearchResult, error: addressError } = useQuery({
+		...addressOperationsSearchAddressesOptions({
+			query: { q: senderEmail ?? "", limit: 1 },
+		}),
+		enabled: Boolean(senderEmail),
+		staleTime: 30_000,
+	});
+
+	const address = addressSearchResult?.items?.[0];
+
+	// --- Semantic search: similar messages ---
+	const semanticQuery = [subject, senderEmail].filter(Boolean).join(" ");
+	const {
+		data: semanticResult,
+		isLoading: isSimilarLoading,
+		error: similarError,
+	} = useQuery({
+		...semanticSearchOperationsSemanticSearchOptions({
+			query: { query: semanticQuery, limit: 5 },
+		}),
+		enabled: Boolean(thread && semanticQuery.length > 3),
+		staleTime: 60_000,
+		// A non-fatal failure (e.g. 404, no index yet) is acceptable — the sidebar
+		// degrades gracefully. A 5xx is NOT acceptable: it escalates globally and
+		// the panel must not present it as a benign "unavailable" state.
+		retry: 1,
+	});
+
+	const data = useMemo((): IntelligenceData | null => {
+		if (!thread) return null;
+
+		const similar: SimilarMessageIntel[] = (semanticResult?.items ?? [])
+			// Exclude the current message itself
+			.filter((r) => r.messageId !== thread.messageId)
+			.map((r) => ({
+				id: r.messageId,
+				// Prefer the mailbox the user is already viewing when the message also
+				// lives there, so opening a similar message stays in the same folder;
+				// otherwise fall back to the first mailbox it lives in.
+				mailboxId:
+					currentMailboxId != null && r.mailboxIds.includes(currentMailboxId)
+						? currentMailboxId
+						: (r.mailboxIds[0] ?? ""),
+				fromName: r.fromName ?? "",
+				subject: r.subject ?? "(No subject)",
+				timeLabel: r.sentDate != null ? formatEmailDate(r.sentDate * 1000) : "",
+				matched: r.matchedChunkType as MatchedChunk,
+			}));
+
+		const sender = buildSenderIntel(thread, address);
+
+		const authenticity = buildAuthenticityIntel(thread, similar.length);
+
+		const category = {
+			value: thread.category ?? "personal",
+			overridden:
+				address?.flags?.category?.value != null &&
+				address.flags.category.value !== thread.category,
+		};
+
+		const flags = buildSenderFlags(address);
+
+		return { sender, authenticity, category, flags, similar };
+	}, [thread, address, semanticResult, currentMailboxId]);
+
+	return {
+		data,
+		isSimilarLoading,
+		similarError,
+		similarErrorIsFatal: isServerError(similarError),
+		addressErrorIsFatal: isServerError(addressError),
+		addressId: address?.addressId,
+		address,
+	};
+}

package/src/hooks/useIsDark.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Returns true when the app is in dark mode.
+ *
+ * Observes the `dark` class on `document.documentElement` — the same
+ * mechanism Tailwind's `class` darkMode strategy uses. The initial value
+ * is read synchronously so there's no flash on first render.
+ */
+export const useIsDark = (): boolean => {
+	const [isDark, setIsDark] = useState(
+		() =>
+			typeof document !== "undefined" &&
+			document.documentElement.classList.contains("dark"),
+	);
+
+	useEffect(() => {
+		const el = document.documentElement;
+		const observer = new MutationObserver(() => {
+			setIsDark(el.classList.contains("dark"));
+		});
+		observer.observe(el, { attributes: true, attributeFilter: ["class"] });
+		return () => observer.disconnect();
+	}, []);
+
+	return isDark;
+};

package/src/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,192 @@
+import { useCallback, useEffect } from "react";
+
+type KeyHandler = (event: KeyboardEvent) => void;
+
+interface KeyBinding {
+	key: string;
+	handler: KeyHandler;
+	/** If true, only trigger when no modifier keys are pressed */
+	noModifiers?: boolean;
+	/**
+	 * Shift requirement. `undefined` (default) ignores shift. `true` requires
+	 * shift to be held; `false` requires it to be absent. Use this to bind a
+	 * plain key and its shift-variant to different handlers (e.g. ArrowDown vs
+	 * Shift+ArrowDown) without them firing each other.
+	 */
+	requireShift?: boolean;
+	/**
+	 * Meta/Ctrl requirement. `undefined` (default) follows `noModifiers`.
+	 * `true` requires Cmd (mac) or Ctrl to be held — used for Cmd/Ctrl+A.
+	 */
+	requireMeta?: boolean;
+	/** If true, prevent default browser behavior */
+	preventDefault?: boolean;
+	/**
+	 * If true, stop the event from reaching any other keydown listener once
+	 * this binding handles it (calls stopPropagation + stopImmediatePropagation).
+	 * Combine with `capture` to win precedence over other window-level
+	 * listeners on the same keypress (e.g. Esc clearing a selection must
+	 * pre-empt a route-level Esc that would also navigate).
+	 */
+	stopPropagation?: boolean;
+}
+
+interface UseKeyboardNavigationOptions {
+	/** Whether the keyboard navigation is enabled */
+	enabled?: boolean;
+	/** Key bindings to register */
+	bindings: KeyBinding[];
+	/**
+	 * Register the listener on the capture phase instead of the bubble phase.
+	 * A capture-phase listener runs before bubble-phase listeners on the same
+	 * target, so paired with a binding's `stopPropagation` it can consume a key
+	 * before other handlers see it.
+	 */
+	capture?: boolean;
+}
+
+/**
+ * Hook for handling keyboard navigation.
+ * Registers global keyboard event listeners and calls handlers for matching keys.
+ */
+export const useKeyboardNavigation = ({
+	enabled = true,
+	bindings,
+	capture = false,
+}: UseKeyboardNavigationOptions) => {
+	const handleKeyDown = useCallback(
+		(event: KeyboardEvent) => {
+			// Skip if focus is in an input/textarea
+			const target = event.target as HTMLElement;
+			if (
+				target.tagName === "INPUT" ||
+				target.tagName === "TEXTAREA" ||
+				target.isContentEditable
+			) {
+				return;
+			}
+
+			for (const binding of bindings) {
+				const keyMatches =
+					event.key.toLowerCase() === binding.key.toLowerCase();
+				if (!keyMatches) continue;
+
+				// Shift gate: when a binding pins shift on/off, it only matches that
+				// exact state so plain and shift variants stay distinct.
+				if (
+					binding.requireShift !== undefined &&
+					binding.requireShift !== event.shiftKey
+				) {
+					continue;
+				}
+
+				const metaHeld = event.ctrlKey || event.metaKey;
+
+				// Meta gate: requireMeta bindings (Cmd/Ctrl+A) need meta/ctrl held.
+				if (binding.requireMeta !== undefined) {
+					if (binding.requireMeta !== metaHeld) continue;
+				} else {
+					const noModifiersRequired = binding.noModifiers ?? true;
+					// Treat shift as a modifier for the no-modifier guard only when
+					// the binding hasn't opted into an explicit shift requirement.
+					const hasModifiers =
+						metaHeld ||
+						event.altKey ||
+						(binding.requireShift === undefined && event.shiftKey);
+					if (noModifiersRequired && hasModifiers) continue;
+				}
+
+				if (binding.preventDefault) {
+					event.preventDefault();
+				}
+				if (binding.stopPropagation) {
+					event.stopPropagation();
+					event.stopImmediatePropagation();
+				}
+				binding.handler(event);
+				return;
+			}
+		},
+		[bindings],
+	);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		window.addEventListener("keydown", handleKeyDown, capture);
+		return () => window.removeEventListener("keydown", handleKeyDown, capture);
+	}, [enabled, handleKeyDown, capture]);
+};
+
+/**
+ * Simple hook for list navigation with j/k keys.
+ */
+export const useListNavigation = <T extends { id: string }>({
+	items,
+	selectedId,
+	onSelect,
+	enabled = true,
+}: {
+	items: T[];
+	selectedId: string | undefined;
+	onSelect: (id: string) => void;
+	enabled?: boolean;
+}) => {
+	const currentIndex = selectedId
+		? items.findIndex((item) => item.id === selectedId)
+		: -1;
+
+	const selectNext = useCallback(() => {
+		if (items.length === 0) return;
+		const nextIndex =
+			currentIndex < items.length - 1 ? currentIndex + 1 : currentIndex;
+		if (nextIndex >= 0 && nextIndex < items.length) {
+			onSelect(items[nextIndex].id);
+		}
+	}, [items, currentIndex, onSelect]);
+
+	const selectPrevious = useCallback(() => {
+		if (items.length === 0) return;
+		const prevIndex = currentIndex > 0 ? currentIndex - 1 : 0;
+		if (prevIndex >= 0 && prevIndex < items.length) {
+			onSelect(items[prevIndex].id);
+		}
+	}, [items, currentIndex, onSelect]);
+
+	const selectFirst = useCallback(() => {
+		if (items.length > 0) {
+			onSelect(items[0].id);
+		}
+	}, [items, onSelect]);
+
+	const selectLast = useCallback(() => {
+		if (items.length > 0) {
+			onSelect(items[items.length - 1].id);
+		}
+	}, [items, onSelect]);
+
+	useKeyboardNavigation({
+		enabled,
+		bindings: [
+			{ key: "j", handler: selectNext, preventDefault: true },
+			{ key: "ArrowDown", handler: selectNext, preventDefault: true },
+			{ key: "k", handler: selectPrevious, preventDefault: true },
+			{ key: "ArrowUp", handler: selectPrevious, preventDefault: true },
+			{ key: "g", handler: selectFirst, preventDefault: true },
+			{
+				key: "G",
+				handler: selectLast,
+				noModifiers: false,
+				preventDefault: true,
+			},
+		],
+	});
+
+	return {
+		currentIndex,
+		selectNext,
+		selectPrevious,
+		selectFirst,
+		selectLast,
+	};
+};

package/src/hooks/useLayoutTier.test.ts

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isSinglePaneTier, resolveLayoutTier } from "./useLayoutTier";
+
+describe("resolveLayoutTier breakpoints (#784)", () => {
+	it("is phone below 768", () => {
+		assert.equal(resolveLayoutTier(767), "phone");
+		assert.equal(resolveLayoutTier(390), "phone");
+		assert.equal(resolveLayoutTier(0), "phone");
+	});
+
+	it("is tablet from 768 up to 1023", () => {
+		assert.equal(resolveLayoutTier(768), "tablet");
+		assert.equal(resolveLayoutTier(900), "tablet");
+		assert.equal(resolveLayoutTier(1023), "tablet");
+	});
+
+	it("is desktop from 1024 up", () => {
+		assert.equal(resolveLayoutTier(1024), "desktop");
+		assert.equal(resolveLayoutTier(1440), "desktop");
+	});
+});
+
+describe("isSinglePaneTier — compose surface must mount below desktop", () => {
+	// Regression: AppShellSlotted mounts the reading pane only at desktop, and
+	// the compose surface lives in the single pane below it. Tablet (768–1023)
+	// must be single-pane so "c" / the FAB can open compose — keying the pane
+	// choice off "phone" alone left tablet with no compose surface.
+	it("is single-pane at phone", () => {
+		assert.equal(isSinglePaneTier("phone"), true);
+	});
+
+	it("is single-pane at tablet (the regression tier)", () => {
+		assert.equal(isSinglePaneTier("tablet"), true);
+	});
+
+	it("is NOT single-pane at desktop (reading pane hosts compose)", () => {
+		assert.equal(isSinglePaneTier("desktop"), false);
+	});
+
+	it("treats every below-desktop width as single-pane via resolveLayoutTier", () => {
+		assert.equal(isSinglePaneTier(resolveLayoutTier(390)), true);
+		assert.equal(isSinglePaneTier(resolveLayoutTier(768)), true);
+		assert.equal(isSinglePaneTier(resolveLayoutTier(1023)), true);
+		assert.equal(isSinglePaneTier(resolveLayoutTier(1024)), false);
+	});
+});

package/src/hooks/useLayoutTier.ts

@@ -0,0 +1,44 @@
+import { useMediaQuery } from "./useMediaQuery";
+
+/**
+ * Responsive layout tiers for the mail shell:
+ *   - `phone`   (< 768px)        single pane: list → reading swaps in place.
+ *   - `tablet`  (768–1023px)     two panes: list + reading, nav rail is drawer-backed.
+ *   - `desktop` (>= 1024px)      full four-pane shell (nav · list · reading · pane 4).
+ *
+ * Pane 4 (intelligence) is desktop-only; `useIsDesktop` stays the pane-4 gate.
+ */
+export type LayoutTier = "phone" | "tablet" | "desktop";
+
+export const TABLET_MIN_WIDTH = 768;
+export const DESKTOP_MIN_WIDTH = 1024;
+
+/** Pure breakpoint resolution, so the tier logic is testable without a DOM. */
+export const resolveLayoutTier = (width: number): LayoutTier => {
+	if (width >= DESKTOP_MIN_WIDTH) return "desktop";
+	if (width >= TABLET_MIN_WIDTH) return "tablet";
+	return "phone";
+};
+
+/**
+ * Whether the mail shell shows a SINGLE pane (no reading pane) at this tier.
+ * AppShellSlotted mounts the reading pane only at desktop (≥1024px), so both
+ * phone AND tablet are single-pane: the one pane swaps in place between the
+ * list, an open thread, and the compose surface. Compose therefore must mount
+ * via the single-pane view at tablet too — keying the pane choice off "phone"
+ * alone left tablet with no compose surface ("c" / FAB opened nothing).
+ */
+export const isSinglePaneTier = (tier: LayoutTier): boolean =>
+	tier !== "desktop";
+
+/**
+ * Returns the current layout tier. SSR-safe (falls back to `phone` before
+ * hydration, matching `useMediaQuery`'s server default).
+ */
+export const useLayoutTier = (): LayoutTier => {
+	const isTabletUp = useMediaQuery(`(min-width: ${TABLET_MIN_WIDTH}px)`);
+	const isDesktop = useMediaQuery(`(min-width: ${DESKTOP_MIN_WIDTH}px)`);
+	if (isDesktop) return "desktop";
+	if (isTabletUp) return "tablet";
+	return "phone";
+};