@remit/ui 0.0.80 → 0.0.82

package/src/lib/use-list-cursor.ts

@@ -0,0 +1,263 @@
+/**
+ * useListCursor — the roving keyboard cursor and multi-selection of a thread
+ * list, independent of how the list renders.
+ *
+ * The mailbox list, the daily brief and Flagged all need it. It used to exist
+ * only inside `MessageList`, so the brief and Flagged had no cursor and no
+ * selection at all (#149). Everything here is list-shape agnostic: it works off
+ * the ordered message ids, so a virtualized flat list and a sectioned brief
+ * drive the same state.
+ *
+ * DOM concerns stay with the caller. `pendingDomFocusRef` names the row that
+ * should take real browser focus once it is rendered, and
+ * `cursorMovedByPointerRef` records whether the last move came from a click, so
+ * a list that scrolls its cursor into view can skip doing so for pointer moves.
+ */
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import {
+	deriveIsMultiSelectMode,
+	nextFocusId,
+	rowSelectIntent,
+	type SelectionModifiers,
+	useSelection,
+} from "./use-selection.js";
+
+interface UseListCursorOptions {
+	/** Message ids in display order. */
+	orderedIds: string[];
+	isDesktop: boolean;
+	/** Seeds the cursor — normally the open thread. */
+	initialFocusedId?: string;
+	/** Rows ticked on first render, for a surface that opens with a selection. */
+	initialSelectedIds?: readonly string[];
+	/** Extra teardown run before the selection is cleared. */
+	onExitSelection?: () => void;
+}
+
+export interface ListCursor {
+	focusedMessageId: string | undefined;
+	setFocusedMessageId: (id: string | undefined) => void;
+	/**
+	 * The row a keyboard command last moved the cursor onto, and `undefined`
+	 * whenever the cursor last moved some other way. Drives the reading pane
+	 * following the cursor (`useFollowFocusOpen`) — a click and Enter open on
+	 * their own, so only a bare cursor move is left to follow.
+	 */
+	keyboardFocusedMessageId: string | undefined;
+	focusIndex: number;
+	pendingDomFocusRef: React.RefObject<string | null>;
+	cursorMovedByPointerRef: React.RefObject<boolean>;
+	selection: ReturnType<typeof useSelection>;
+	isMultiSelectMode: boolean;
+	exitSelection: () => void;
+	moveFocusToIndex: (index: number) => void;
+	focusNext: () => void;
+	focusPrevious: () => void;
+	focusFirst: () => void;
+	focusLast: () => void;
+	toggleFocusedSelection: () => void;
+	extendRangeUp: () => void;
+	extendRangeDown: () => void;
+	selectAllLoaded: () => void;
+	/**
+	 * Desktop mouse selection semantics (Apple Mail / Gmail model). Returns true
+	 * when selection handled the click — the caller must then suppress the
+	 * row's navigation; false for a plain click.
+	 */
+	handleRowSelect: (
+		messageId: string,
+		modifiers: SelectionModifiers,
+	) => boolean;
+}
+
+export const useListCursor = ({
+	orderedIds,
+	isDesktop,
+	initialFocusedId,
+	initialSelectedIds,
+	onExitSelection,
+}: UseListCursorOptions): ListCursor => {
+	// The keyboard "where am I" pointer, distinct from the open thread
+	// (`selectedMessageId` in the URL). j/k move this cursor; Enter opens the
+	// focused row, and on desktop the reading pane follows the cursor of its own
+	// accord (`useFollowFocusOpen`). It seeds from the open thread so opening a
+	// message also focuses its row.
+	const [focusedMessageId, setFocusedId] = useState<string | undefined>(
+		initialFocusedId,
+	);
+
+	// Which of those moves came from a keyboard command, so the reading pane can
+	// follow the cursor without following a click that already opened its own row.
+	const [keyboardFocusedMessageId, setKeyboardFocusedMessageId] = useState<
+		string | undefined
+	>();
+
+	// Every non-keyboard move — a click, Tab, a thread opening, a refetch snapping
+	// the cursor to a survivor — drops the keyboard mark, so nothing follows it.
+	// A row taking DOM focus as the *consequence* of a keyboard move arrives here
+	// with the id that move just set; keeping the mark in that case is what stops
+	// the browser's own focus event from cancelling the load the move started.
+	const setFocusedMessageId = useCallback((id: string | undefined) => {
+		setKeyboardFocusedMessageId((current) =>
+			current === id ? current : undefined,
+		);
+		setFocusedId(id);
+	}, []);
+
+	const selection = useSelection({ initialSelectedIds });
+	const {
+		selectedCount,
+		toggle: toggleCheck,
+		clearSelection,
+		selectRange,
+		setAnchor,
+		selectAll,
+	} = selection;
+
+	// The selection count is the only source of truth for whether the list is in
+	// multi-select mode (#115). A separate flag needs an effect to reconcile it
+	// back to the count, and across that render the two disagree.
+	const isMultiSelectMode = deriveIsMultiSelectMode(selectedCount, isDesktop);
+
+	// Set when a keyboard command moves the cursor. Real DOM focus then follows
+	// it onto the row once rendered, so the browser's own focus — and therefore
+	// Tab, Shift+Tab and the focus ring — agree with what the list highlights
+	// (#43).
+	const pendingDomFocusRef = useRef<string | null>(null);
+	// Whether the cursor's last move came from a row taking DOM focus (a click)
+	// rather than a command. Scrolling for a click moves the row out from under
+	// the pointer between mousedown and click, so the click lands on empty space
+	// and nothing opens (#85).
+	const cursorMovedByPointerRef = useRef(false);
+
+	const exitSelection = useCallback(() => {
+		onExitSelection?.();
+		clearSelection();
+	}, [clearSelection, onExitSelection]);
+
+	const focusIndex = useMemo(
+		() => (focusedMessageId ? orderedIds.indexOf(focusedMessageId) : -1),
+		[orderedIds, focusedMessageId],
+	);
+
+	// Move the cursor by index. In multi-select mode (mobile) j/k toggle
+	// selection rather than moving a cursor.
+	const moveFocusToIndex = useCallback(
+		(index: number) => {
+			if (index < 0 || index >= orderedIds.length) return;
+			const messageId = orderedIds[index];
+			if (isMultiSelectMode) {
+				toggleCheck(messageId);
+				return;
+			}
+			pendingDomFocusRef.current = messageId;
+			cursorMovedByPointerRef.current = false;
+			setKeyboardFocusedMessageId(messageId);
+			setFocusedId(messageId);
+		},
+		[orderedIds, isMultiSelectMode, toggleCheck],
+	);
+
+	const focusNext = useCallback(() => {
+		if (orderedIds.length === 0) return;
+		moveFocusToIndex(
+			focusIndex < 0 ? 0 : Math.min(focusIndex + 1, orderedIds.length - 1),
+		);
+	}, [orderedIds.length, focusIndex, moveFocusToIndex]);
+
+	const focusPrevious = useCallback(() => {
+		if (orderedIds.length === 0) return;
+		moveFocusToIndex(focusIndex <= 0 ? 0 : focusIndex - 1);
+	}, [orderedIds.length, focusIndex, moveFocusToIndex]);
+
+	const focusFirst = useCallback(() => moveFocusToIndex(0), [moveFocusToIndex]);
+	const focusLast = useCallback(
+		() => moveFocusToIndex(orderedIds.length - 1),
+		[moveFocusToIndex, orderedIds.length],
+	);
+
+	const toggleFocusedSelection = useCallback(() => {
+		if (focusedMessageId) toggleCheck(focusedMessageId);
+	}, [focusedMessageId, toggleCheck]);
+
+	const handleRowSelect = useCallback(
+		(messageId: string, modifiers: SelectionModifiers): boolean => {
+			const intent = rowSelectIntent(modifiers);
+			if (intent === "range") {
+				// The open/focused row is the fallback origin when the stored anchor
+				// has been filtered or searched out of the visible list, so the first
+				// shift-click still ranges from where the user is (#142, #144).
+				selectRange(orderedIds, messageId, focusedMessageId);
+				return true;
+			}
+			if (intent === "toggle") {
+				toggleCheck(messageId);
+				return true;
+			}
+			// Plain click: collapse any multi-selection and let navigation proceed.
+			// The clicked row becomes the next anchor for a subsequent shift-click,
+			// but is NOT added to the checkbox set (no toolbar on a plain open).
+			exitSelection();
+			setAnchor(messageId);
+			return false;
+		},
+		[
+			orderedIds,
+			focusedMessageId,
+			selectRange,
+			toggleCheck,
+			exitSelection,
+			setAnchor,
+		],
+	);
+
+	// Shift+arrow moves the cursor one row and adds the row it lands on to the
+	// range — the keyboard equivalent of shift-click. The first press seeds the
+	// anchor on that row; consecutive presses extend from it. The range only
+	// grows, so reversing direction ranges back through the anchor rather than
+	// giving rows up.
+	const extendRange = useCallback(
+		(direction: -1 | 1) => {
+			const target = nextFocusId(orderedIds, focusedMessageId, direction);
+			if (target === undefined) return;
+			selectRange(orderedIds, target);
+			pendingDomFocusRef.current = target;
+			cursorMovedByPointerRef.current = false;
+			// Shift+arrow is building a range, not reading. The reading pane stays on
+			// whatever is open rather than chasing the growing edge of the selection.
+			setKeyboardFocusedMessageId(undefined);
+			setFocusedId(target);
+		},
+		[orderedIds, focusedMessageId, selectRange],
+	);
+
+	const extendRangeUp = useCallback(() => extendRange(-1), [extendRange]);
+	const extendRangeDown = useCallback(() => extendRange(1), [extendRange]);
+
+	const selectAllLoaded = useCallback(() => {
+		if (orderedIds.length > 0) selectAll(orderedIds);
+	}, [orderedIds, selectAll]);
+
+	return {
+		focusedMessageId,
+		setFocusedMessageId,
+		keyboardFocusedMessageId,
+		focusIndex,
+		pendingDomFocusRef,
+		cursorMovedByPointerRef,
+		selection,
+		isMultiSelectMode,
+		exitSelection,
+		moveFocusToIndex,
+		focusNext,
+		focusPrevious,
+		focusFirst,
+		focusLast,
+		toggleFocusedSelection,
+		extendRangeUp,
+		extendRangeDown,
+		selectAllLoaded,
+		handleRowSelect,
+	};
+};

package/src/lib/use-list-keyboard.test.ts

@@ -0,0 +1,172 @@
+/**
+ * The list's keyboard layer as a host mounts it: the keys reach the cursor from
+ * inside the element the layer was given and from nowhere else, the row-click
+ * path reads its modifiers the same way, the selection follows the rows it is
+ * handed, and the footer offers only the actions the layer registered.
+ */
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { type ListKeyboard, useListKeyboard } from "./use-list-keyboard.js";
+
+const ALL_IDS = ["m1", "m2", "m3", "m4"];
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+let list: ListKeyboard;
+
+function Harness({ orderedIds }: { orderedIds: string[] }) {
+	list = useListKeyboard({ orderedIds, isDesktop: true });
+	return createElement("section", { id: "pane", ref: list.keyboard.ref });
+}
+
+const mount = (orderedIds: string[] = ALL_IDS) => {
+	act(() => {
+		root.render(createElement(Harness, { orderedIds }));
+	});
+};
+
+const pane = (): HTMLElement => {
+	const element = dom.window.document.getElementById("pane");
+	assert.ok(element, "the harness rendered no pane");
+	return element as unknown as HTMLElement;
+};
+
+const press = (
+	key: string,
+	init: KeyboardEventInit = {},
+	target: EventTarget = pane(),
+) => {
+	act(() => {
+		target.dispatchEvent(
+			new dom.window.KeyboardEvent("keydown", {
+				key,
+				bubbles: true,
+				cancelable: true,
+				...init,
+			}),
+		);
+	});
+};
+
+const click = (
+	id: string,
+	modifiers: { shiftKey?: boolean; metaKey?: boolean } = {},
+): boolean => {
+	let took = false;
+	act(() => {
+		took =
+			list.selection.onRowSelect?.(id, {
+				shiftKey: false,
+				metaKey: false,
+				ctrlKey: false,
+				...modifiers,
+			}) ?? false;
+	});
+	return took;
+};
+
+const selected = () => Array.from(list.cursor.selection.selectedIds).sort();
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	dom = new JSDOMCtor(
+		"<!doctype html><html><body><div id=root></div></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.SVGElement = dom.window.SVGElement;
+	(
+		globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+	).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+after(() => {
+	dom.window.close();
+});
+
+beforeEach(() => {
+	container = dom.window.document.getElementById(
+		"root",
+	) as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+	mount();
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+});
+
+describe("useListKeyboard", () => {
+	it("registers the keys the footer may offer and no others", () => {
+		assert.deepEqual(Object.keys(list.keyboard.handlers).sort(), [
+			"back",
+			"extendSelectDown",
+			"extendSelectUp",
+			"focusFirst",
+			"focusLast",
+			"focusNext",
+			"focusPrevious",
+			"selectAll",
+			"toggleSelect",
+		]);
+	});
+
+	it("moves the cursor the pane draws", () => {
+		press("j");
+		press("j");
+		assert.equal(list.keyboard.focusedId, "m2");
+	});
+
+	it("ticks the row under the cursor", () => {
+		press("j");
+		press("x");
+		assert.deepEqual(selected(), ["m1"]);
+	});
+
+	it("takes every loaded row with ⌘A", () => {
+		press("a", { metaKey: true });
+		assert.deepEqual(selected(), ALL_IDS);
+	});
+
+	it("leaves a key pressed outside its own element alone", () => {
+		press("j", {}, dom.window.document.body);
+		assert.equal(list.keyboard.focusedId, undefined);
+	});
+
+	it("ticks a row on a cmd-click without opening it", () => {
+		assert.equal(click("m2", { metaKey: true }), true);
+		assert.deepEqual(selected(), ["m2"]);
+	});
+
+	it("ranges from the last row touched on a shift-click", () => {
+		click("m2");
+		assert.equal(click("m4", { shiftKey: true }), true);
+		assert.deepEqual(selected(), ["m2", "m3", "m4"]);
+	});
+
+	it("opens a plain click rather than taking it", () => {
+		assert.equal(click("m2"), false);
+		assert.deepEqual(selected(), []);
+	});
+
+	it("drops the ticked rows that leave the list, and keeps the rest", () => {
+		press("a", { metaKey: true });
+		assert.deepEqual(selected(), ALL_IDS);
+		mount(["m1", "m3"]);
+		assert.deepEqual(
+			selected(),
+			["m1", "m3"],
+			"a verb acts on the rows that are still on screen",
+		);
+	});
+});

package/src/lib/use-list-keyboard.ts

@@ -0,0 +1,101 @@
+/**
+ * A list under the triage keyboard: the cursor, the selection and the two
+ * props `MessageListPane` draws them from.
+ *
+ * The app routes the same actions through its own list commands, because its
+ * rows are virtualized and its verbs reach the server. Everything else that
+ * mounts a list — the kit's stories and the Storybook prototype — drives it
+ * from here, so a shift-range, a cmd-toggle and select-all are one behaviour
+ * with one definition, and the footer offers exactly the keys that are wired.
+ *
+ * The layer binds its keys to the pane element rather than the window, so a
+ * page carrying several lists gives each of them only the keys pressed inside
+ * it.
+ */
+import { useEffect, useMemo, useState } from "react";
+import type {
+	MessageListKeyboard,
+	MessageListSelection,
+} from "../components/app-shell-types.js";
+import type { TriageHandlers } from "./keymap.js";
+import { type ListCursor, useListCursor } from "./use-list-cursor.js";
+import { useTriageKeyboard } from "./use-triage-keyboard.js";
+
+export interface UseListKeyboardOptions {
+	/** Row ids in display order. */
+	orderedIds: string[];
+	isDesktop: boolean;
+	/** Seeds the cursor — normally the open thread. */
+	initialFocusedId?: string;
+	/** Rows ticked on first render. */
+	initialSelectedIds?: readonly string[];
+	/** Off while something above the list owns the keyboard. */
+	enabled?: boolean;
+}
+
+export interface ListKeyboard {
+	cursor: ListCursor;
+	/** The pane's `selection` prop. */
+	selection: MessageListSelection;
+	/** The pane's `keyboard` prop. */
+	keyboard: MessageListKeyboard;
+}
+
+export const useListKeyboard = ({
+	orderedIds,
+	isDesktop,
+	initialFocusedId,
+	initialSelectedIds,
+	enabled = true,
+}: UseListKeyboardOptions): ListKeyboard => {
+	const [pane, setPane] = useState<HTMLElement | null>(null);
+
+	const cursor = useListCursor({
+		orderedIds,
+		isDesktop,
+		initialFocusedId,
+		initialSelectedIds,
+	});
+
+	const handlers: TriageHandlers = {
+		focusNext: cursor.focusNext,
+		focusPrevious: cursor.focusPrevious,
+		focusFirst: cursor.focusFirst,
+		focusLast: cursor.focusLast,
+		toggleSelect: cursor.toggleFocusedSelection,
+		extendSelectDown: cursor.extendRangeDown,
+		extendSelectUp: cursor.extendRangeUp,
+		selectAll: cursor.selectAllLoaded,
+		back: cursor.exitSelection,
+	};
+	useTriageKeyboard({ handlers, enabled, target: pane });
+
+	// A row that leaves the list — a filter, an account pill, a completed verb —
+	// cannot stay selected, or the count and the verbs act on rows nobody can
+	// see. The same rule the app runs in `ThreadListInteraction`.
+	const { intersectWith } = cursor.selection;
+	useEffect(() => {
+		intersectWith(orderedIds);
+	}, [intersectWith, orderedIds]);
+
+	const { selectedIds, toggle } = cursor.selection;
+	const { handleRowSelect } = cursor;
+	const selection = useMemo<MessageListSelection>(
+		() => ({
+			selectedIds,
+			onToggle: toggle,
+			onRowSelect: handleRowSelect,
+		}),
+		[selectedIds, toggle, handleRowSelect],
+	);
+
+	return {
+		cursor,
+		selection,
+		keyboard: {
+			focusedId: cursor.focusedMessageId,
+			handlers,
+			ref: setPane,
+		},
+	};
+};

package/src/lib/use-triage-keyboard.test.ts

@@ -0,0 +1,153 @@
+/**
+ * The hook on a mounted component: `keymap-dispatch.test.ts` covers which
+ * action a stroke resolves to, and what is left is the wiring — which handler
+ * a real keydown reaches, what the `g …` window does across two presses, and
+ * what the layer leaves bound after it is taken down.
+ */
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { TriageAction, TriageHandlers } from "./keymap.js";
+import { useTriageKeyboard } from "./use-triage-keyboard.js";
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+let fired: TriageAction[];
+
+const handlers = (): TriageHandlers => ({
+	focusNext: () => fired.push("focusNext"),
+	toggleSelect: () => fired.push("toggleSelect"),
+	selectAll: () => fired.push("selectAll"),
+	goInbox: () => fired.push("goInbox"),
+	back: () => fired.push("back"),
+});
+
+function Harness({ enabled }: { enabled: boolean }) {
+	useTriageKeyboard({ handlers: handlers(), enabled });
+	return createElement("input", { id: "field" });
+}
+
+const mount = (enabled = true) => {
+	act(() => {
+		root.render(createElement(Harness, { enabled }));
+	});
+};
+
+const press = (
+	key: string,
+	init: KeyboardEventInit = {},
+	target: EventTarget = dom.window.document.body,
+): KeyboardEvent => {
+	const event = new dom.window.KeyboardEvent("keydown", {
+		key,
+		bubbles: true,
+		cancelable: true,
+		...init,
+	});
+	act(() => {
+		target.dispatchEvent(event);
+	});
+	return event as unknown as KeyboardEvent;
+};
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	dom = new JSDOMCtor(
+		"<!doctype html><html><body><div id=root></div></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.SVGElement = dom.window.SVGElement;
+	(
+		globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+	).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+after(() => {
+	dom.window.close();
+});
+
+beforeEach(() => {
+	fired = [];
+	container = dom.window.document.getElementById(
+		"root",
+	) as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+});
+
+describe("useTriageKeyboard", () => {
+	it("routes a stroke to the handler its action names", () => {
+		mount();
+		press("j");
+		assert.deepEqual(fired, ["focusNext"]);
+	});
+
+	it("takes the browser's default off a stroke it serves", () => {
+		mount();
+		assert.equal(press("j").defaultPrevented, true);
+	});
+
+	it("leaves a stroke no handler serves to the browser", () => {
+		mount();
+		assert.equal(press("r").defaultPrevented, false);
+		assert.deepEqual(fired, []);
+	});
+
+	it("carries a go-to prefix across two strokes", () => {
+		mount();
+		press("g");
+		press("i");
+		assert.deepEqual(fired, ["goInbox"]);
+	});
+
+	it("drops the prefix once the sequence resolves", () => {
+		mount();
+		press("g");
+		press("i");
+		press("i");
+		assert.deepEqual(fired, ["goInbox"]);
+	});
+
+	it("stays inert while focus is in an editable surface", () => {
+		mount();
+		const field = dom.window.document.getElementById("field");
+		assert.ok(field);
+		press("j", {}, field);
+		assert.deepEqual(fired, []);
+	});
+
+	it("claims ⌘A from the browser's select-all", () => {
+		mount();
+		assert.equal(press("a", { metaKey: true }).defaultPrevented, true);
+		assert.deepEqual(fired, ["selectAll"]);
+	});
+
+	it("binds nothing while disabled", () => {
+		mount(false);
+		press("j");
+		assert.deepEqual(fired, []);
+	});
+
+	it("releases the keyboard when it comes down", () => {
+		mount();
+		act(() => {
+			root.unmount();
+		});
+		press("j");
+		assert.deepEqual(fired, []);
+		root = createRoot(container);
+	});
+});