@remit/web-client 0.0.210 → 0.0.211

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.210",
+  "version": "0.0.211",
   "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/layout/Drawer.focus.test.ts

@@ -0,0 +1,212 @@
+/**
+ * The drawer's focus trap (#747).
+ *
+ * The drawer is `aria-modal`, so a screen reader offers nothing outside it and
+ * the scrim puts everything outside it out of a pointer's reach. Tab has to
+ * agree with both: it cycles inside the drawer, and the ring is the controls a
+ * reader can actually see and press — not every element that happens to match
+ * a focusable selector.
+ */
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import {
+	act,
+	createElement,
+	Fragment,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { Drawer } from "./Drawer";
+
+let container: HTMLElement;
+let root: Root;
+let outside: HTMLButtonElement;
+
+const press = (key: string, shiftKey = false): void => {
+	act(() => {
+		document.dispatchEvent(
+			new KeyboardEvent("keydown", { key, shiftKey, bubbles: true }),
+		);
+	});
+};
+
+const named = (label: string): HTMLElement => {
+	const found = container.querySelector<HTMLElement>(`[data-name="${label}"]`);
+	if (!found) throw new Error(`expected an element named ${label}`);
+	return found;
+};
+
+const closeButton = (): HTMLElement => {
+	const buttons = container.querySelectorAll<HTMLElement>(
+		'.safe-area-frame [aria-label="Close menu"]',
+	);
+	const found = buttons[0];
+	if (!found) throw new Error("expected the drawer's close button");
+	return found;
+};
+
+const render = (isOpen: boolean, children: ReactNode): void => {
+	act(() => {
+		root.render(
+			createElement(Drawer, {
+				isOpen,
+				onClose: () => undefined,
+				ariaLabel: "Message details",
+				side: "right",
+				children,
+			}),
+		);
+	});
+};
+
+const open = (children: ReactNode): void => render(true, children);
+const close = (): void => render(false, null);
+
+const button = (
+	name: string,
+	props: Record<string, unknown> = {},
+): ReactElement =>
+	createElement(
+		"button",
+		{ key: name, type: "button", "data-name": name, ...props },
+		name,
+	);
+
+beforeEach(() => {
+	container = document.getElementById("root") as unknown as HTMLElement;
+	container.innerHTML = "";
+	outside = document.createElement("button");
+	outside.type = "button";
+	outside.textContent = "Toolbar toggle";
+	document.body.appendChild(outside);
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => root.unmount());
+	outside.remove();
+});
+
+describe("Drawer keeps Tab inside itself", () => {
+	it("wraps backwards from the first element to the last", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		closeButton().focus();
+
+		press("Tab", true);
+
+		assert.equal(document.activeElement, named("omega"));
+	});
+
+	it("wraps forwards from the last element to the first", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("pulls focus back in when it is somewhere else entirely", () => {
+		open(createElement(Fragment, null, button("alpha")));
+		outside.focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("leaves an interior Tab to the browser", () => {
+		open(createElement(Fragment, null, button("alpha"), button("omega")));
+		named("alpha").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, named("alpha"));
+	});
+});
+
+describe("Drawer's ring is what a reader can reach", () => {
+	it("skips a scrim that took itself out of the tab order", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("backdrop", { tabIndex: -1 }),
+				button("omega"),
+			),
+		);
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	it("skips disabled, aria-disabled and hidden controls", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("omega"),
+				button("off", { disabled: true }),
+				button("stated-off", { "aria-disabled": "true" }),
+				button("gone", { style: { display: "none" } }),
+				button("inerted", { inert: true }),
+			),
+		);
+		named("omega").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, closeButton());
+	});
+
+	/**
+	 * The intelligence pane's reclassify dialog renders inside the drawer, over
+	 * its panel. A ring scoped to the panel puts that dialog's Cancel last and
+	 * keeps every control behind its backdrop in the cycle, so Tab walks onto
+	 * buttons no pointer can reach — the very thing the trap exists to prevent.
+	 */
+	it("hands the ring to a modal opened inside it", () => {
+		open(
+			createElement(
+				Fragment,
+				null,
+				button("under-the-backdrop"),
+				createElement(
+					"div",
+					{
+						key: "nested",
+						role: "dialog",
+						"aria-modal": "true",
+						"aria-label": "Reclassify sender",
+					},
+					button("automated"),
+					button("Cancel"),
+				),
+			),
+		);
+		named("Cancel").focus();
+
+		press("Tab");
+
+		assert.equal(document.activeElement, named("automated"));
+
+		press("Tab", true);
+
+		assert.equal(document.activeElement, named("Cancel"));
+	});
+});
+
+describe("Drawer gives focus back on the way out", () => {
+	it("returns it to whatever held it when the drawer went up", () => {
+		outside.focus();
+		open(createElement(Fragment, null, button("alpha")));
+		assert.equal(document.activeElement, closeButton());
+
+		close();
+
+		assert.equal(document.activeElement, outside);
+	});
+});

package/src/components/layout/Drawer.tsx

@@ -2,6 +2,37 @@ import { cn } from "@remit/ui";
 import { X } from "lucide-react";
 import { type ReactNode, useEffect, useRef } from "react";
 
+const FOCUSABLE_SELECTOR =
+	"a[href], button, input, select, textarea, [tabindex]";
+
+const isTabbable = (element: HTMLElement): boolean => {
+	if (element.tabIndex < 0) return false;
+	if (element.hasAttribute("disabled")) return false;
+	if (element.getAttribute("aria-disabled") === "true") return false;
+	if (element.closest("[inert], [hidden], [aria-hidden='true']")) return false;
+	const style = getComputedStyle(element);
+	return style.display !== "none" && style.visibility !== "hidden";
+};
+
+/**
+ * The elements Tab may reach, in the order it reaches them.
+ *
+ * A modal opened from inside the drawer takes the ring with it: the
+ * intelligence pane's reclassify dialog renders under the drawer's own panel,
+ * so a ring scoped to the panel puts its Cancel last and leaves every control
+ * behind that dialog's backdrop in the cycle — Tab walks onto buttons no
+ * pointer can reach, which is the bug the trap exists to prevent.
+ */
+const tabRing = (panel: HTMLElement): HTMLElement[] => {
+	const nested = panel.querySelectorAll<HTMLElement>(
+		'[role="dialog"][aria-modal="true"]',
+	);
+	const root = nested[nested.length - 1] ?? panel;
+	return [...root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+		isTabbable,
+	);
+};
+
 interface DrawerProps {
 	isOpen: boolean;
 	onClose: () => void;
@@ -40,16 +71,35 @@ export const Drawer = ({
 			if (event.key === "Escape") {
 				event.preventDefault();
 				onClose();
+				return;
+			}
+			// Trap Tab inside the drawer: it is `aria-modal`, so a screen reader
+			// offers nothing outside it — and letting Tab walk out would land on
+			// controls a pointer cannot reach under the scrim (#747).
+			if (event.key !== "Tab" || !drawerRef.current) return;
+			const ring = tabRing(drawerRef.current);
+			if (ring.length === 0) return;
+			const first = ring[0];
+			const last = ring[ring.length - 1];
+			const active = document.activeElement;
+			const inside = active instanceof HTMLElement && ring.includes(active);
+			if (event.shiftKey) {
+				if (!inside || active === first) {
+					event.preventDefault();
+					last.focus();
+				}
+				return;
+			}
+			if (!inside || active === last) {
+				event.preventDefault();
+				first.focus();
 			}
 		};
 
 		document.addEventListener("keydown", handleKey);
 
 		// Move focus into the drawer
-		const focusable = drawerRef.current?.querySelector<HTMLElement>(
-			"button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])",
-		);
-		focusable?.focus();
+		if (drawerRef.current) tabRing(drawerRef.current)[0]?.focus();
 
 		// Lock body scroll
 		const previousOverflow = document.body.style.overflow;

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

@@ -1,9 +1,16 @@
-import { type IntelligenceData, IntelligencePanel } from "@remit/ui";
+import {
+	Avatar,
+	type IntelligenceData,
+	IntelligencePanel,
+	RefreshButton,
+	ShellTopBar,
+} from "@remit/ui";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { ChevronLeft, Info } from "lucide-react";
 import { useState } from "react";
 import { expect, userEvent, within } from "storybook/test";
 import { Drawer } from "@/components/layout/Drawer";
+import { MessageToolbar } from "@/components/mail/MessageToolbar";
 import { useIntelligenceDrawer } from "@/hooks/useIntelligenceDrawer";
 
 /**
@@ -29,6 +36,8 @@ type Story = StoryObj;
 
 const PHONE_WIDTH = 390;
 const PHONE_HEIGHT = 720;
+const MID_WIDTH = 1100;
+const MID_HEIGHT = 640;
 
 const intelligence: IntelligenceData = {
 	sender: {
@@ -213,6 +222,119 @@ export const DismissedAndNotCarried: Story = {
 	},
 };
 
+/**
+ * The two-pane desktop band between 1024 and 1280px, where the rail has no room
+ * and the drawer is the surface. The drawer is right-anchored and 320px wide,
+ * so it lands squarely on the reading toolbar's own intelligence toggle — the
+ * control that put it there. The shell's top bar is here because the geometry
+ * is the point: it is what stands the toolbar clear of the drawer's own header,
+ * as it does in the app.
+ */
+const MidWidthReader = () => {
+	const drawer = useIntelligenceDrawer(messages[0]?.id ?? null);
+	const [search, setSearch] = useState("");
+
+	return (
+		<div
+			className="flex flex-col overflow-hidden rounded-lg border border-line bg-canvas"
+			// As on the phone frame: the transform makes this a containing block,
+			// so the drawer's `position: fixed` resolves against it.
+			style={{
+				width: MID_WIDTH,
+				height: MID_HEIGHT,
+				transform: "translateZ(0)",
+			}}
+		>
+			<ShellTopBar
+				search={{
+					value: search,
+					scope: "global",
+					onChange: setSearch,
+					onClear: () => setSearch(""),
+					onClearQuery: () => setSearch(""),
+					onRemoveChip: () => undefined,
+				}}
+				onCompose={() => undefined}
+				onReportBug={() => undefined}
+				onOpenSettings={() => undefined}
+				refreshControl={
+					<RefreshButton
+						state="idle"
+						label="Refresh all accounts"
+						onRefresh={() => undefined}
+					/>
+				}
+				account={
+					<Avatar
+						name="Matthijs van Henten"
+						email="mvh@example.com"
+						size="sm"
+					/>
+				}
+			/>
+			<MessageToolbar
+				hasThread
+				intelligenceOpen={drawer.isOpen}
+				canToggleIntelligence
+				onToggleIntelligence={drawer.toggle}
+			/>
+			<div className="min-h-0 flex-1 overflow-y-auto px-5 py-4 text-sm text-fg">
+				<h1 className="text-lg font-semibold leading-snug">
+					{messages[0]?.subject}
+				</h1>
+				<p className="mt-1 text-2xs text-fg-subtle">{messages[0]?.from}</p>
+				<p className="mt-4 max-w-2xl">{messages[0]?.body}</p>
+			</div>
+			<Drawer
+				isOpen={drawer.isOpen}
+				onClose={drawer.close}
+				ariaLabel="Message details"
+				side="right"
+			>
+				<IntelligencePanel data={intelligence} hideCloseButton />
+			</Drawer>
+		</div>
+	);
+};
+
+/**
+ * The toggle the drawer covers. It is the only way into this surface for a
+ * message with no warning on it, so the drawer lands on it — and stays there:
+ * the toggle is the way in and nothing else. Getting back out is the drawer's
+ * own job, and its X sits clear of the toggle to do it (#747).
+ */
+export const CoveredToggle: Story = {
+	render: () => <MidWidthReader />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+
+		await userEvent.click(
+			canvas.getByRole("button", { name: "Show intelligence sidebar" }),
+		);
+		const drawer = canvas.getByRole("dialog", { name: "Message details" });
+		await expect(drawer).toBeVisible();
+
+		// The toggle stays in the toolbar the drawer covers. Nothing lifts it over
+		// the surface it opened, so a press aimed at it reaches the drawer.
+		await expect(drawer).not.toContainElement(
+			canvas.getByRole("button", { name: "Hide intelligence sidebar" }),
+		);
+
+		// The header's X, not the scrim that shares its name: the second of the
+		// two, and the one a reader can see.
+		const close = within(drawer).getAllByLabelText("Close menu")[1];
+		await expect(close).toBeVisible();
+		await userEvent.click(close);
+
+		await expect(
+			canvas.queryByRole("dialog", { name: "Message details" }),
+		).toBeNull();
+		await expect(
+			canvas.getByRole("button", { name: "Show intelligence sidebar" }),
+		).toHaveAttribute("aria-pressed", "false");
+	},
+};
+
 /** The drawer over the dark theme. */
 export const OpenOverThreadDark: Story = {
 	name: "Open Over Thread (dark)",