@remit/web-client 0.0.174 → 0.0.175

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.174",
+  "version": "0.0.175",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/BriefPane.tsx

@@ -31,6 +31,7 @@ import { IntelligencePane } from "@/components/mail/IntelligencePane";
 import { MessageToolbar } from "@/components/mail/MessageToolbar";
 import type { OpenMessageOptions } from "@/components/mail/ThreadListInteraction";
 import { useDeleteMessages } from "@/hooks/useDeleteMessages";
+import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 import { useToggleReadFor } from "@/hooks/useMarkAsRead";
 import { type ThreadActions, useThreadActions } from "@/hooks/useThreadActions";
 import { useThreadRow } from "@/hooks/useThreadRow";
@@ -408,7 +409,7 @@ function BriefPhone() {
 		previousThread,
 		handleDeselectIfRemoved,
 	} = useBriefPane();
-	const { intelligenceOpen, onToggleIntelligence } = useMailContext();
+	const drawer = useIntelligenceDrawer(conversation?.threadId ?? null);
 
 	if (conversation) {
 		return (
@@ -420,21 +421,21 @@ function BriefPhone() {
 					selectedMessageId={conversation.messageId}
 					authenticity={conversation.authenticity}
 					onBack={onCloseThread}
-					onOpenIntelligence={onToggleIntelligence}
+					onOpenIntelligence={drawer.toggle}
 					onSwipeNext={nextThread ? () => onOpenThread(nextThread) : undefined}
 					onSwipePrevious={
 						previousThread ? () => onOpenThread(previousThread) : undefined
 					}
-					mobileIntelligenceOpen={intelligenceOpen}
+					mobileIntelligenceOpen={drawer.isOpen}
 				/>
 				<Drawer
-					isOpen={intelligenceOpen}
-					onClose={onToggleIntelligence}
+					isOpen={drawer.isOpen}
+					onClose={drawer.close}
 					ariaLabel="Message details"
 					side="right"
 				>
 					<IntelligencePane
-						onClose={onToggleIntelligence}
+						onClose={drawer.close}
 						thread={selectedThread}
 						mailboxId={selectedThread?.mailboxId}
 						accountId={selectedThread?.accountId}

package/src/components/mail/FlaggedPane.tsx

@@ -41,6 +41,7 @@ import { IntelligencePane } from "@/components/mail/IntelligencePane";
 import { MessageToolbar } from "@/components/mail/MessageToolbar";
 import type { OpenMessageOptions } from "@/components/mail/ThreadListInteraction";
 import { useDeleteMessages } from "@/hooks/useDeleteMessages";
+import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 import { useToggleReadFor } from "@/hooks/useMarkAsRead";
 import { useStarredThreads } from "@/hooks/useStarredThreads";
 import { type ThreadActions, useThreadActions } from "@/hooks/useThreadActions";
@@ -409,7 +410,7 @@ function FlaggedPhone() {
 		previousThread,
 		handleDeselectIfRemoved,
 	} = useFlaggedPane();
-	const { intelligenceOpen, onToggleIntelligence } = useMailContext();
+	const drawer = useIntelligenceDrawer(conversation?.threadId ?? null);
 
 	if (conversation) {
 		return (
@@ -421,21 +422,21 @@ function FlaggedPhone() {
 					selectedMessageId={conversation.messageId}
 					authenticity={conversation.authenticity}
 					onBack={onCloseThread}
-					onOpenIntelligence={onToggleIntelligence}
+					onOpenIntelligence={drawer.toggle}
 					onSwipeNext={nextThread ? () => onOpenThread(nextThread) : undefined}
 					onSwipePrevious={
 						previousThread ? () => onOpenThread(previousThread) : undefined
 					}
-					mobileIntelligenceOpen={intelligenceOpen}
+					mobileIntelligenceOpen={drawer.isOpen}
 				/>
 				<Drawer
-					isOpen={intelligenceOpen}
-					onClose={onToggleIntelligence}
+					isOpen={drawer.isOpen}
+					onClose={drawer.close}
 					ariaLabel="Message details"
 					side="right"
 				>
 					<IntelligencePane
-						onClose={onToggleIntelligence}
+						onClose={drawer.close}
 						thread={selectedThread}
 						mailboxId={selectedThread?.mailboxId}
 						accountId={selectedThread?.accountId}

package/src/components/mail/MailboxPane.tsx

@@ -72,6 +72,7 @@ import {
 } from "@/hooks/useDeleteMessages";
 import type { EscalationSearchQuery } from "@/hooks/useEscalatedActions";
 import { useIntelligenceData } from "@/hooks/useIntelligenceData";
+import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 import { useLayoutTier } from "@/hooks/useLayoutTier";
 import { useMailboxAccount } from "@/hooks/useMailboxAccount";
 import { useToggleReadFor } from "@/hooks/useMarkAsRead";
@@ -507,23 +508,6 @@ function MailboxPaneProvider({
 	const focusedThread =
 		threads.find((t) => t.messageId === triageFocusedId) ?? selectedThread;
 
-	// Auto-open intelligence pane on DKIM mismatch.
-	const autoOpenedForRef = useRef<string | null>(null);
-	useEffect(() => {
-		const id = selectedThread?.messageId ?? null;
-		if (!id) return;
-		if (autoOpenedForRef.current === id) return;
-		if (selectedThread?.authenticity?.dkimMismatch) {
-			autoOpenedForRef.current = id;
-			if (!intelligenceOpen) onToggleIntelligence();
-		}
-	}, [
-		selectedThread?.messageId,
-		selectedThread?.authenticity?.dkimMismatch,
-		intelligenceOpen,
-		onToggleIntelligence,
-	]);
-
 	// The mailbox's own unseen total. A count over the loaded pages undercounts
 	// every mailbox larger than one page and creeps upward as the user scrolls,
 	// so there is no fallback: until the mailbox resolves there is no number.
@@ -1085,41 +1069,41 @@ function MailboxReading() {
 	const railFits = useAppShellLayout()?.showIntelligencePane ?? false;
 	const hasThread = Boolean(conversation);
 
-	// The drawer is modal, so it opens only when it is asked for — and only for
-	// the thread it was 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 would throw a scrim over a message the moment one was
-	// selected. Naming the thread is also what closes it again when the reader
-	// moves on: a bare flag would still be set when they came back.
-	const [drawerThreadId, setDrawerThreadId] = useState<string | null>(null);
-	const openThreadId = conversation?.threadId ?? null;
-	// Derived rather than stored: the drawer is up only while the thread it was
-	// opened for is still the one on screen, so moving to another one closes it
-	// with no effect to run. Closing it from an effect would paint one frame of
-	// an open drawer over the newly opened thread first.
-	const drawerOpen =
-		!railFits && openThreadId !== null && drawerThreadId === openThreadId;
-
-	const closeIntelligenceDrawer = useCallback(
-		() => setDrawerThreadId(null),
-		[],
-	);
-	const openIntelligenceDrawer = useCallback(
-		() => setDrawerThreadId(openThreadId),
-		[openThreadId],
-	);
-	// The banner's "Why?" — always an open, never a close.
-	const openIntelligence = railFits
-		? onToggleIntelligence
-		: openIntelligenceDrawer;
+	// The rail opens itself on a DKIM mismatch. It lives here, behind the rail's
+	// own width gate, because raising it writes `#intelligence` into the address
+	// — and a panel the address names with no renderer behind it is a panel that
+	// opens nothing (`docs/architecture/url-state.md`, R6). Below this width the
+	// banner is the announcement and its "Why?" is the way in.
+	const autoOpenedForRef = useRef<string | null>(null);
+	useEffect(() => {
+		if (!railFits) return;
+		const id = selectedThread?.messageId ?? null;
+		if (!id) return;
+		if (autoOpenedForRef.current === id) return;
+		if (!selectedThread?.authenticity?.dkimMismatch) return;
+		autoOpenedForRef.current = id;
+		if (!intelligenceOpen) onToggleIntelligence();
+	}, [
+		railFits,
+		selectedThread?.messageId,
+		selectedThread?.authenticity?.dkimMismatch,
+		intelligenceOpen,
+		onToggleIntelligence,
+	]);
+
+	const drawer = useIntelligenceDrawer(conversation?.threadId ?? null);
+	const drawerOpen = !railFits && drawer.isOpen;
+	const closeIntelligenceDrawer = drawer.close;
+	const openIntelligence = railFits ? onToggleIntelligence : drawer.open;
 	// The toolbar's control, which toggles whichever surface this width has.
+	const { toggle: toggleDrawer } = drawer;
 	const toggleIntelligence = useCallback(() => {
 		if (railFits) {
 			onToggleIntelligence();
 			return;
 		}
-		setDrawerThreadId(drawerOpen ? null : openThreadId);
-	}, [railFits, onToggleIntelligence, drawerOpen, openThreadId]);
+		toggleDrawer();
+	}, [railFits, onToggleIntelligence, toggleDrawer]);
 	const intelligenceShowing =
 		hasThread && (railFits ? intelligenceOpen : drawerOpen);
 
@@ -1219,13 +1203,12 @@ function MailboxPhone() {
 		selectedThread,
 		conversation,
 		onOpenThread,
-		intelligenceOpen,
-		onToggleIntelligence,
 		onBack,
 		nextThread,
 		previousThread,
 		handleDeselectIfRemoved,
 	} = useMailboxPane();
+	const drawer = useIntelligenceDrawer(conversation?.threadId ?? null);
 
 	if (conversation) {
 		return (
@@ -1237,21 +1220,21 @@ function MailboxPhone() {
 					selectedMessageId={conversation.messageId}
 					authenticity={conversation.authenticity}
 					onBack={onBack}
-					onOpenIntelligence={onToggleIntelligence}
+					onOpenIntelligence={drawer.toggle}
 					onSwipeNext={nextThread ? () => onOpenThread(nextThread) : undefined}
 					onSwipePrevious={
 						previousThread ? () => onOpenThread(previousThread) : undefined
 					}
-					mobileIntelligenceOpen={intelligenceOpen}
+					mobileIntelligenceOpen={drawer.isOpen}
 				/>
 				<Drawer
-					isOpen={intelligenceOpen}
-					onClose={onToggleIntelligence}
+					isOpen={drawer.isOpen}
+					onClose={drawer.close}
 					ariaLabel="Message details"
 					side="right"
 				>
 					<IntelligencePane
-						onClose={onToggleIntelligence}
+						onClose={drawer.close}
 						thread={selectedThread}
 						mailboxId={mailboxId}
 						accountId={mailboxAccountId}

package/src/components/mail/intelligence-drawer.stories.tsx

@@ -4,20 +4,20 @@ import { ChevronLeft, Info } from "lucide-react";
 import { useState } from "react";
 import { expect, userEvent, within } from "storybook/test";
 import { Drawer } from "@/components/layout/Drawer";
-import { resolveRailOpen } from "@/lib/intelligence-pref";
-import { parseOpenPanels, retainOpenPanelsAtTier } from "@/routing";
+import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 
 /**
- * The intelligence drawer below the desktop tier (#777).
+ * The intelligence drawer below the desktop tier (#777, #778).
  *
  * There is no fourth pane here: the rail is a full-screen drawer over the open
- * message, so it belongs to the thread it was opened for. The address is the
- * only place its open state lives, and a navigation drops it — otherwise a DKIM
- * mismatch on one message leaves the drawer covering every message opened
- * after it.
+ * message, so it belongs to the thread it was opened for and to nothing else.
+ * It is modal, so it opens only when the reader asks — a DKIM mismatch shows
+ * the banner and leaves the message alone. A drawer that opened itself would
+ * put a scrim over the message, and the reader's next tap would land on the
+ * scrim rather than on Back.
  *
- * Both rules are the app's own: the fragment goes through
- * `retainOpenPanelsAtTier`, and what is up is `resolveRailOpen`.
+ * The rule is the app's own: `useIntelligenceDrawer` is the hook the phone and
+ * mid-width panes both run on.
  */
 const meta: Meta = {
 	title: "Flows/Reading/Intelligence Drawer",
@@ -30,8 +30,6 @@ type Story = StoryObj;
 const PHONE_WIDTH = 390;
 const PHONE_HEIGHT = 720;
 
-const retainOnPhone = retainOpenPanelsAtTier(false);
-
 const intelligence: IntelligenceData = {
 	sender: {
 		name: "Mondial Relay",
@@ -77,23 +75,14 @@ const messages: readonly Message[] = [
 ];
 
 /**
- * The phone reader, driven by the address alone: `hash` is the whole state,
- * and every navigation writes it through the same helper the panes use.
+ * The phone reader. What is open is the thread on screen and, beside it, the
+ * drawer the reader asked for — held by `useIntelligenceDrawer` against that
+ * thread, so opening another one takes the drawer down with it.
  */
-const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
-	const [hash, setHash] = useState(initialHash);
+const PhoneReader = () => {
 	const [openId, setOpenId] = useState<string | undefined>(messages[0]?.id);
 	const open = messages.find((message) => message.id === openId);
-	const drawerOpen = resolveRailOpen({
-		panels: parseOpenPanels(hash),
-		prefersOpen: true,
-		isDesktop: false,
-		hasThread: open !== undefined,
-	});
-	const navigate = (nextId: string | undefined) => {
-		setHash(retainOnPhone(hash));
-		setOpenId(nextId);
-	};
+	const drawer = useIntelligenceDrawer(open?.id ?? null);
 
 	return (
 		<div className="flex flex-col gap-2">
@@ -113,7 +102,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<button
 								type="button"
 								aria-label="Back"
-								onClick={() => navigate(undefined)}
+								onClick={() => setOpenId(undefined)}
 								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
 							>
 								<ChevronLeft className="size-5" />
@@ -124,7 +113,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<button
 								type="button"
 								aria-label="Message details"
-								onClick={() => setHash("intelligence")}
+								onClick={drawer.toggle}
 								className="inline-flex size-11 items-center justify-center rounded-md text-fg hover:bg-surface-raised"
 							>
 								<Info className="size-5" />
@@ -141,7 +130,7 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 							<li key={message.id}>
 								<button
 									type="button"
-									onClick={() => navigate(message.id)}
+									onClick={() => setOpenId(message.id)}
 									className="flex w-full flex-col items-start gap-0.5 border-b border-line px-4 py-3 text-left hover:bg-surface-raised"
 								>
 									<span className="text-sm font-semibold text-fg">
@@ -156,8 +145,8 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 					</ul>
 				)}
 				<Drawer
-					isOpen={drawerOpen}
-					onClose={() => setHash("")}
+					isOpen={drawer.isOpen}
+					onClose={drawer.close}
 					ariaLabel="Message details"
 					side="right"
 				>
@@ -165,34 +154,58 @@ const PhoneReader = ({ initialHash = "" }: { initialHash?: string }) => {
 				</Drawer>
 			</div>
 			<p className="font-mono text-2xs text-fg-subtle">
-				{`/mail/inbox${open ? `/${open.id}` : ""}${hash ? `#${hash}` : ""}`}
+				{`/mail/inbox${open ? `/${open.id}` : ""}`}
 			</p>
 		</div>
 	);
 };
 
-/** A message with no drawer over it: the address names no panel. */
-export const Closed: Story = {
-	render: () => <PhoneReader />,
+/** The reader's own press on the details control. */
+const openDetails = async (canvasElement: HTMLElement): Promise<void> => {
+	await userEvent.click(
+		within(canvasElement).getByLabelText("Message details"),
+	);
 };
 
 /**
- * The drawer over the message it was opened for — here by a DKIM mismatch,
- * which opens it without being asked.
+ * The warned message as it opens: the banner's own wording, and nothing over
+ * it. A mismatch is what the panel explains, never a reason to cover the
+ * message with it — a scrim there takes the reader's next tap, Back included.
  */
+export const Closed: Story = {
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await expect(canvas.queryByRole("dialog")).toBeNull();
+		await expect(canvas.getByLabelText("Back")).toBeVisible();
+	},
+};
+
+/** The drawer over the message it was opened for. */
 export const OpenOverThread: Story = {
-	render: () => <PhoneReader initialHash="intelligence" />,
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		await openDetails(canvasElement);
+		await expect(within(canvasElement).getByRole("dialog")).toBeVisible();
+	},
 };
 
 /**
- * The same drawer, then Back and another message. The fragment is dropped on
- * the way out, so the second message is not covered by a panel opened for the
- * first. Press Back with the drawer up to walk it.
+ * Dismissed, and gone for the next message too: the drawer is held against the
+ * thread it was opened for, so nothing carries it forward.
  */
-export const DroppedByNavigation: Story = {
-	render: () => <PhoneReader initialHash="intelligence" />,
+export const DismissedAndNotCarried: Story = {
+	render: () => <PhoneReader />,
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
+		await openDetails(canvasElement);
+		await expect(canvas.getByRole("dialog")).toBeVisible();
+
+		// The scrim carries the same name as the header's close button and comes
+		// first in the drawer, so the visible control is the second of the two.
+		await userEvent.click(canvas.getAllByLabelText("Close menu")[1]);
+		await expect(canvas.queryByRole("dialog")).toBeNull();
+
 		await userEvent.click(canvas.getByLabelText("Back"));
 		await userEvent.click(canvas.getByText("Standup moved to 10:15"));
 		await expect(canvas.queryByRole("dialog")).toBeNull();
@@ -204,5 +217,8 @@ export const DroppedByNavigation: Story = {
 export const OpenOverThreadDark: Story = {
 	name: "Open Over Thread (dark)",
 	parameters: { theme: "dark" },
-	render: () => <PhoneReader initialHash="intelligence" />,
+	render: () => <PhoneReader />,
+	play: async ({ canvasElement }) => {
+		await openDetails(canvasElement);
+	},
 };

package/src/hooks/intelligence-drawer.render.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The intelligence drawer is modal, so what matters as much as opening it is
+ * that nothing else can. It belongs to the thread it was opened for: leaving
+ * that thread puts it away, and coming back to the same message opens it clear
+ * rather than under the scrim it was last left with (#778).
+ *
+ * The reachable case is a phone's system Back, which is a navigation like any
+ * other — the thread goes, and the drawer has to go with it for good.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { useIntelligenceDrawer } from "./useIntelligenceDrawer";
+
+let dom: DomHarness;
+
+beforeEach(() => {
+	dom = createDomHarness();
+});
+
+afterEach(() => {
+	dom.close();
+});
+
+/** Reports what the drawer says, and offers the controls a reader has. */
+const Probe = ({ threadId }: { threadId: string | null }) => {
+	const drawer = useIntelligenceDrawer(threadId);
+	return createElement(
+		"div",
+		null,
+		createElement(
+			"span",
+			{ "data-state": "" },
+			drawer.isOpen ? "open" : "shut",
+		),
+		createElement("button", {
+			type: "button",
+			"data-open": "",
+			onClick: drawer.open,
+		}),
+		createElement("button", {
+			type: "button",
+			"data-toggle": "",
+			onClick: drawer.toggle,
+		}),
+	);
+};
+
+const state = (): string | undefined =>
+	dom.query("[data-state]")?.textContent ?? undefined;
+const press = (handle: string): void => {
+	const button = dom.query(`[${handle}]`);
+	if (!button) throw new Error(`no ${handle} control`);
+	dom.click(button);
+};
+
+describe("the intelligence drawer", () => {
+	it("opens only when it is asked to", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		assert.equal(state(), "shut");
+
+		press("data-open");
+		assert.equal(state(), "open");
+	});
+
+	it("does not come back with the message it was opened over", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-open");
+		assert.equal(state(), "open");
+
+		// System Back: the thread closes under it.
+		dom.render(createElement(Probe, { threadId: null }));
+		assert.equal(state(), "shut");
+
+		// And the same message again, which is where the scrim used to be waiting.
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		assert.equal(state(), "shut");
+	});
+
+	it("stays behind when the reader moves to another thread", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-open");
+		assert.equal(state(), "open");
+
+		dom.render(createElement(Probe, { threadId: "thread-b" }));
+		assert.equal(state(), "shut");
+	});
+
+	it("toggles shut again from the toolbar's control", () => {
+		dom.render(createElement(Probe, { threadId: "thread-a" }));
+		press("data-toggle");
+		assert.equal(state(), "open");
+
+		press("data-toggle");
+		assert.equal(state(), "shut");
+	});
+});

package/src/hooks/useIntelligenceDrawer.ts

@@ -0,0 +1,54 @@
+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 };
+}