@remit/web-client 0.0.325 → 0.0.327

package/src/hooks/useIntelligenceData.ts

@@ -1,325 +0,0 @@
-import { addressOperationsSearchAddressesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type {
-	RemitImapAddressResponse,
-	RemitImapThreadMessageResponse,
-} from "@remit/api-http-client/types.gen.ts";
-import { DisplayNameCorrespondence } from "@remit/domain-enums";
-import type {
-	AuthenticityIntel,
-	IntelligenceData,
-	SenderFlagsIntel,
-	SenderIntel,
-} from "@remit/ui";
-import { isThreadCategory } from "@remit/ui";
-import { useQuery } from "@tanstack/react-query";
-import { useMemo } from "react";
-import { isServerError } from "@/lib/error-classifier";
-import { formatDate } from "@/lib/format";
-import {
-	pickSenderAddress,
-	senderAddressSearchQuery,
-} from "@/lib/sender-address";
-
-/**
- * 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 category intel from the thread message and address lookup.
- *
- * The row's category is a string the API chose, so it is narrowed rather than
- * asserted: a value this build has no entry for — a category a newer server
- * classifies into — resolves to `uncategorized`, which is the taxonomy's own
- * name for "no classification this client can act on" and renders a readable
- * neutral chip. Asserting instead would leave the chip with no tone at all.
- */
-export function buildCategoryIntel(
-	thread: RemitImapThreadMessageResponse,
-	address: RemitImapAddressResponse | undefined,
-): IntelligenceData["category"] {
-	const served = thread.category ?? "personal";
-	return {
-		value: isThreadCategory(served) ? served : "uncategorized",
-		overridden:
-			address?.flags?.category?.value != null &&
-			address.flags.category.value !== thread.category,
-	};
-}
-
-/**
- * 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,
-	};
-}
-
-/** The brand the display name asserts, or `undefined` when it asserts none. */
-function claimedBrandOf(
-	thread: RemitImapThreadMessageResponse,
-): string | undefined {
-	if (!thread.fromName) return undefined;
-	if (thread.fromName === thread.fromEmail) return undefined;
-	return thread.fromName;
-}
-
-function joinDomains(domains: readonly string[]): string {
-	if (domains.length === 1) return domains[0];
-	return `${domains.slice(0, -1).join(", ")} and ${domains[domains.length - 1]}`;
-}
-
-/**
- * The clauses naming what does not line up on a message whose signature checks
- * out. Empty when everything the backend compared agreed — including when it
- * compared nothing, which is every message outside Junk that the provider's
- * filter did not already call spam.
- *
- * Each clause leads with the concern and names `auth.fromDomain` — the
- * domain `classifyDisplayNameCorrespondence` actually compared the display
- * name against (`senderMismatch.ts` calls it with the From address's own
- * domain, never the DKIM signing domain). Naming `auth.dkimDomain` instead
- * would assert a comparison that was never made: on a message signed by a
- * relay or ESP infrastructure domain, the display name was checked against
- * the sender's own address, not that domain. These clauses are the caution
- * tier's entire summary: there is no separate "verified" sentence in front
- * of them for the signing fact to hide behind.
- */
-function describeSenderMismatch(
-	auth: NonNullable<RemitImapThreadMessageResponse["authenticity"]>,
-	claimedBrand: string | undefined,
-): string[] {
-	const clauses: string[] = [];
-	const correspondence = auth.displayNameCorrespondence;
-
-	if (claimedBrand) {
-		if (correspondence === DisplayNameCorrespondence.Unrelated) {
-			clauses.push(
-				`The name it shows, "${claimedBrand}", has nothing to do with ${auth.fromDomain}.`,
-			);
-		} else if (correspondence === DisplayNameCorrespondence.Lookalike) {
-			clauses.push(
-				`The name it shows, "${claimedBrand}", only looks like ${auth.fromDomain}.`,
-			);
-		} else if (correspondence === DisplayNameCorrespondence.ForeignAddress) {
-			clauses.push(
-				`The name it shows, "${claimedBrand}", is an address ${auth.fromDomain} cannot send from.`,
-			);
-		}
-	}
-
-	const linkDomains = readDomainList(auth.offDomainLinkDomains);
-	if (linkDomains.length > 0) {
-		clauses.push(`Its links go to ${joinDomains(linkDomains.slice(0, 3))}.`);
-	}
-
-	return clauses;
-}
-
-/**
- * The field is a JSON blob on the message row, so a value written by an older
- * or drifted writer reaches here as whatever it happens to be. Anything that is
- * not a list of non-empty strings carries no destination to name.
- */
-function readDomainList(value: unknown): string[] {
-	if (!Array.isArray(value)) return [];
-	return value.filter(
-		(entry): entry is string => typeof entry === "string" && entry.length > 0,
-	);
-}
-
-/** Build authenticity intel from the thread message's authenticity field. */
-export function buildAuthenticityIntel(
-	thread: RemitImapThreadMessageResponse,
-): AuthenticityIntel {
-	if (isSenderAddressUnverifiable(thread.fromEmail)) {
-		return {
-			verdict: "mismatch",
-			fromDomain: "",
-			addressUnreadable: true,
-			summary: UNREADABLE_SENDER_SUMMARY,
-		};
-	}
-
-	const auth = thread.authenticity;
-	if (!auth) {
-		return {
-			verdict: "caution",
-			fromDomain: thread.fromEmail?.split("@")[1] ?? "",
-			summary: NO_SIGNAL_SUMMARY,
-		};
-	}
-	if (!auth.dkimMismatch) {
-		const claimed = claimedBrandOf(thread);
-		const unlike = describeSenderMismatch(auth, claimed);
-		if (unlike.length > 0) {
-			return {
-				verdict: "caution",
-				fromDomain: auth.fromDomain,
-				dkimDomain: auth.dkimDomain,
-				claimedBrand: claimed,
-				summary: unlike.join(" "),
-			};
-		}
-		return {
-			verdict: "aligned",
-			fromDomain: auth.fromDomain,
-			dkimDomain: auth.dkimDomain,
-			summary: auth.dkimDomain
-				? `This message was signed by ${auth.dkimDomain}.`
-				: `Nothing looks unusual about this sender.`,
-		};
-	}
-
-	const fromDomain = auth.fromDomain;
-	const dkimDomain = auth.dkimDomain;
-	const claimedBrand = claimedBrandOf(thread);
-	// dkimDomain is known whenever a mismatch was named against a real
-	// domain; the fallback covers the (defensive, not currently reachable)
-	// case where a mismatch fires with none — say what actually happened
-	// (a signature failed to verify) rather than inventing a sender identity
-	// we do not have.
-	const whatHappened = dkimDomain
-		? `it was actually sent from ${dkimDomain}`
-		: "its signature failed to verify";
-	const summary = claimedBrand
-		? `The display name claims "${claimedBrand}", but ${whatHappened}${dkimDomain ? ` — not ${fromDomain}` : ""}. Real senders use their own address.`
-		: `This message claims to be from ${fromDomain}, but ${whatHappened}.`;
-	return {
-		verdict: "mismatch",
-		fromDomain,
-		dkimDomain,
-		claimedBrand,
-		summary,
-	};
-}
-
-export interface UseIntelligenceDataResult {
-	data: IntelligenceData | null;
-	/**
-	 * 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.
-	 * `undefined` until the lookup resolves the row for exactly this address;
-	 * quick actions that PATCH it must stay unwired until then.
-	 */
-	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. Two 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.
- */
-export function useIntelligenceData(
-	thread: RemitImapThreadMessageResponse | null | undefined,
-): UseIntelligenceDataResult {
-	const senderEmail = thread?.fromEmail ?? null;
-
-	// --- Address lookup: flags + first-seen timestamp ---
-	const { data: addressSearchResult, error: addressError } = useQuery({
-		...addressOperationsSearchAddressesOptions({
-			query: senderAddressSearchQuery(senderEmail ?? undefined),
-		}),
-		enabled: Boolean(senderEmail),
-		staleTime: 30_000,
-	});
-
-	const address = pickSenderAddress(
-		addressSearchResult?.items,
-		senderEmail ?? undefined,
-	);
-
-	const data = useMemo((): IntelligenceData | null => {
-		if (!thread) return null;
-
-		const sender = buildSenderIntel(thread, address);
-
-		const authenticity = buildAuthenticityIntel(thread);
-
-		const category = buildCategoryIntel(thread, address);
-
-		const flags = buildSenderFlags(address);
-
-		return { sender, authenticity, category, flags };
-	}, [thread, address]);
-
-	return {
-		data,
-		addressErrorIsFatal: isServerError(addressError),
-		addressId: address?.addressId,
-		address,
-	};
-}

package/src/hooks/useIntelligenceDrawer.ts

@@ -1,54 +0,0 @@
-import { useCallback, useState } from "react";
-
-/**
- * The intelligence drawer's own state, scoped to the thread it was opened for.
- *
- * The drawer is modal, so it opens only when it is asked for. `intelligenceOpen`
- * is the rail's persisted preference and the DKIM auto-open sets it on every
- * tier, so driving the drawer from it throws a scrim over a message the moment
- * one is selected — and the reader's next tap lands on that scrim instead of the
- * control they aimed at, Back to messages included. Naming the thread is also
- * what closes it again when they move on: a bare flag would still be set when
- * they came back.
- */
-export interface IntelligenceDrawer {
-	/** Up only while the thread it was opened for is the one on screen. */
-	isOpen: boolean;
-	/** The banner's "Why?" — always an open, never a close. */
-	open: () => void;
-	close: () => void;
-	/** The toolbar's control. */
-	toggle: () => void;
-}
-
-export function useIntelligenceDrawer(
-	openThreadId: string | null,
-): IntelligenceDrawer {
-	const [drawerThreadId, setDrawerThreadId] = useState<string | null>(null);
-	// Leaving the thread puts the drawer away for good, rather than leaving it
-	// armed for the reader's return. Held state alone would reopen it: press
-	// system Back and come to the same message again and the scrim would be
-	// waiting, which is the defect this hook exists to end (#778).
-	//
-	// Adjusted during render, not in an effect: React re-runs the render before
-	// committing, so nothing paints with the stale thread. An effect would show
-	// one frame of an open drawer over the message first.
-	if (drawerThreadId !== null && drawerThreadId !== openThreadId) {
-		setDrawerThreadId(null);
-	}
-	// Derived rather than stored: moving to another thread closes it with no
-	// effect to run.
-	const isOpen = openThreadId !== null && drawerThreadId === openThreadId;
-
-	const close = useCallback(() => setDrawerThreadId(null), []);
-	const open = useCallback(
-		() => setDrawerThreadId(openThreadId),
-		[openThreadId],
-	);
-	const toggle = useCallback(
-		() => setDrawerThreadId(isOpen ? null : openThreadId),
-		[isOpen, openThreadId],
-	);
-
-	return { isOpen, open, close, toggle };
-}

package/src/hooks/useIntelligenceSurface.ts

@@ -1,103 +0,0 @@
-import { useAppShellLayout } from "@remit/ui";
-import { type RefObject, useCallback, useEffect } from "react";
-import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
-import { useMailContext } from "@/lib/mail-context";
-
-/**
- * Which surface intelligence has for the open thread: the rail from 1280 up,
- * the drawer below that, where the reading pane is mounted and the rail has no
- * room. Every list pane asks this the same way — the brief and Flagged read the
- * rail's own gate as the answer for both tiers and offered a disabled control
- * with nothing behind it between 1024 and 1280 (#817).
- */
-export interface IntelligenceSurface extends IntelligenceCommands {
-	/** There is a thread to say anything about, so the toolbar's control acts. */
-	canToggle: boolean;
-	/** What the toolbar reports: the rail above 1280, the drawer below it. */
-	isShowing: boolean;
-	drawerOpen: boolean;
-	closeDrawer: () => void;
-	/** Whether this width has room for the rail, so the rail is the surface. */
-	railFits: boolean;
-	/**
-	 * Raise the rail if it fits and is down, for this thread only. The DKIM
-	 * auto-open's way in, so it never stores a preference the reader never gave
-	 * (#778).
-	 */
-	openRail: () => void;
-}
-
-/**
- * What a mounted intelligence surface answers for. The width gate is the
- * shell's own measurement, so only a component inside `AppShellSlotted` knows
- * which surface this tier has; a pane provider wrapping the shell reaches it
- * through a ref the mounted surface publishes into.
- */
-export interface IntelligenceCommands {
-	/** The toolbar's control, over whichever surface this width has. */
-	toggle: () => void;
-	/** The banner's "Why?" — an open, never a close. */
-	open: () => void;
-}
-
-export const useIntelligenceSurface = (
-	openThreadId: string | undefined,
-): IntelligenceSurface => {
-	const { intelligenceOpen, onToggleIntelligence, onRaiseIntelligence } =
-		useMailContext();
-	const railFits = useAppShellLayout()?.showIntelligencePane ?? false;
-	const threadId = openThreadId ?? null;
-	const drawer = useIntelligenceDrawer(threadId);
-	// The rail wins wherever it fits, so the drawer stays down there even if it
-	// was asked for at a narrower width the reader has since grown out of.
-	const drawerOpen = !railFits && drawer.isOpen;
-
-	const { open: openDrawer, toggle: toggleDrawer } = drawer;
-	const toggle = useCallback(() => {
-		if (railFits) {
-			onToggleIntelligence();
-			return;
-		}
-		toggleDrawer();
-	}, [railFits, onToggleIntelligence, toggleDrawer]);
-	const openRail = useCallback(() => {
-		if (!railFits || intelligenceOpen) return;
-		onRaiseIntelligence();
-	}, [railFits, intelligenceOpen, onRaiseIntelligence]);
-	const open = useCallback(() => {
-		if (!railFits) {
-			openDrawer();
-			return;
-		}
-		openRail();
-	}, [railFits, openDrawer, openRail]);
-
-	return {
-		canToggle: threadId !== null,
-		isShowing: threadId !== null && (railFits ? intelligenceOpen : drawerOpen),
-		toggle,
-		open,
-		drawerOpen,
-		closeDrawer: drawer.close,
-		railFits,
-		openRail,
-	};
-};
-
-/**
- * Publish the mounted surface for the pane provider's keyboard handlers. Null
- * while nothing is mounted to serve them, so a shortcut fired with no surface
- * reaches nothing rather than writing `#intelligence` at a width that cannot
- * render it (`docs/architecture/url-state.md`, R6).
- */
-export const usePublishIntelligenceCommands = (
-	ref: RefObject<IntelligenceCommands | null>,
-	{ toggle, open }: IntelligenceCommands,
-): void => {
-	useEffect(() => {
-		ref.current = { toggle, open };
-		return () => {
-			ref.current = null;
-		};
-	}, [ref, toggle, open]);
-};

package/src/hooks/useIsDark.ts

@@ -1,27 +0,0 @@
-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

@@ -1,130 +0,0 @@
-import { resolveAgainstOverlays, type TriageAction } from "@remit/ui";
-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;
-	/**
-	 * Which triage action this key means. Naming it puts the binding under the
-	 * overlay stack: an open overlay answers the action itself or contains it,
-	 * and either way this binding stands down. Every key that also exists in the
-	 * global key map owes one, or it acts through whatever is on top of it —
-	 * `r` opening a reply behind the Move popover (#959) is that bug.
-	 */
-	action?: TriageAction;
-}
-
-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;
-
-				if (binding.action && resolveAgainstOverlays(binding.action)) 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]);
-};