@remit/ui 0.0.80 → 0.0.82

package/src/lib/keymap.ts

@@ -0,0 +1,241 @@
+/**
+ * Single source of truth for the global keyboard triage layer (#429).
+ *
+ * Every shortcut the app responds to is declared here once. The help overlay
+ * (`KeyboardShortcutsModal`), the list footer hints and the toolbar tooltips
+ * all read from this module so the displayed bindings can never drift from the
+ * keys the dispatcher actually routes. The spec lives in
+ * `doc/design/flows/04-triage.md`.
+ */
+
+/** A logical action a key (or key sequence) maps to. */
+export type TriageAction =
+	// list navigation / focus model
+	| "focusNext"
+	| "focusPrevious"
+	| "focusFirst"
+	| "focusLast"
+	| "openFocused"
+	| "back"
+	// selection
+	| "toggleSelect"
+	| "extendSelectDown"
+	| "extendSelectUp"
+	| "selectAll"
+	// message verbs (focused row / selection)
+	| "reply"
+	| "replyAll"
+	| "forward"
+	| "delete"
+	| "toggleStar"
+	| "toggleRead"
+	// sender verbs
+	| "muteSender"
+	| "blockSender"
+	| "vipSender"
+	| "markJunk"
+	// view
+	| "toggleIntelligence"
+	| "toggleDensity"
+	// global
+	| "focusSearch"
+	| "compose"
+	| "help"
+	// go-to sequences (g then …)
+	| "goBrief"
+	| "goInbox"
+	| "goSent"
+	| "goFlagged"
+	| "goSettings";
+
+/** Map of action → handler. Omitted actions are inert (no-op). */
+export type TriageHandlers = Partial<Record<TriageAction, () => void>>;
+
+/** One hint in the list's footer bar. */
+export interface KeyboardHint {
+	/** The action the keys run, so a hint can be traced to what serves it. */
+	action: TriageAction;
+	/** One or more keys shown as `Kbd` chips. */
+	keys: string[];
+	/** What the keys do. */
+	label: string;
+}
+
+/** The persistent message-list footer hint set (desktop). */
+export const defaultKeyboardHints: KeyboardHint[] = [
+	{ action: "focusNext", keys: ["j", "k"], label: "navigate" },
+	{ action: "muteSender", keys: ["m"], label: "mute" },
+	{ action: "help", keys: ["?"], label: "all shortcuts" },
+];
+
+/**
+ * The hints a host may advertise: the footer set narrowed to the actions its
+ * handler table answers. A surface offers the keys it serves and no others, so
+ * the bar under a list describes that list.
+ */
+export function keyboardHintsFor(handlers: TriageHandlers): KeyboardHint[] {
+	return defaultKeyboardHints.filter(
+		(hint) => handlers[hint.action] !== undefined,
+	);
+}
+
+/**
+ * One displayed binding row in the help overlay. `keys` is the human-readable
+ * sequence (e.g. ["g", "b"] or ["⌘", "N"]); `display` overrides the rendered
+ * label when a single token reads better (e.g. "Esc", "↵").
+ */
+export interface KeyHint {
+	action: TriageAction;
+	/** Tokens rendered as individual <Kbd> chips, in order. */
+	keys: string[];
+	description: string;
+}
+
+export interface KeyHintGroup {
+	title: string;
+	hints: KeyHint[];
+}
+
+/**
+ * The full key map, grouped by area, exactly as it appears in the `?` overlay.
+ * Order is intentional (matches 04-triage.md reading order).
+ */
+export const KEY_HINT_GROUPS: KeyHintGroup[] = [
+	{
+		title: "Navigation",
+		hints: [
+			{ action: "focusNext", keys: ["j"], description: "Focus next message" },
+			{
+				action: "focusPrevious",
+				keys: ["k"],
+				description: "Focus previous message",
+			},
+			{ action: "focusNext", keys: ["↓"], description: "Focus next message" },
+			{
+				action: "focusPrevious",
+				keys: ["↑"],
+				description: "Focus previous message",
+			},
+			{ action: "focusFirst", keys: ["Home"], description: "Focus first" },
+			{ action: "focusLast", keys: ["End"], description: "Focus last" },
+			{
+				action: "openFocused",
+				keys: ["Enter"],
+				description: "Open focused thread",
+			},
+			{ action: "back", keys: ["Esc"], description: "Back / close overlay" },
+		],
+	},
+	{
+		title: "Selection",
+		hints: [
+			{ action: "toggleSelect", keys: ["x"], description: "Toggle select" },
+			{ action: "toggleSelect", keys: ["Space"], description: "Toggle select" },
+			{
+				action: "extendSelectDown",
+				keys: ["Shift", "j"],
+				description: "Extend selection down",
+			},
+			{
+				action: "extendSelectUp",
+				keys: ["Shift", "k"],
+				description: "Extend selection up",
+			},
+			{
+				action: "extendSelectDown",
+				keys: ["Shift", "↓"],
+				description: "Extend selection down",
+			},
+			{
+				action: "extendSelectUp",
+				keys: ["Shift", "↑"],
+				description: "Extend selection up",
+			},
+			{ action: "selectAll", keys: ["⌘", "A"], description: "Select all" },
+		],
+	},
+	{
+		title: "Actions",
+		hints: [
+			{ action: "reply", keys: ["r"], description: "Reply" },
+			{ action: "replyAll", keys: ["a"], description: "Reply all" },
+			{ action: "forward", keys: ["f"], description: "Forward" },
+			{ action: "delete", keys: ["#"], description: "Delete" },
+			{ action: "toggleStar", keys: ["s"], description: "Star / unstar" },
+			{
+				action: "toggleRead",
+				keys: ["u"],
+				description: "Toggle read / unread",
+			},
+		],
+	},
+	{
+		title: "Sender",
+		hints: [
+			{ action: "muteSender", keys: ["m"], description: "Mute sender" },
+			{ action: "blockSender", keys: ["b"], description: "Block sender" },
+			{ action: "vipSender", keys: ["v"], description: "VIP sender" },
+			{ action: "markJunk", keys: ["!"], description: "Mark junk" },
+		],
+	},
+	{
+		title: "Go to",
+		hints: [
+			{ action: "goBrief", keys: ["g", "b"], description: "Daily brief" },
+			{ action: "goInbox", keys: ["g", "i"], description: "Inbox" },
+			{ action: "goSent", keys: ["g", "s"], description: "Sent" },
+			{ action: "goFlagged", keys: ["g", "f"], description: "Starred" },
+			{ action: "goSettings", keys: ["g", ","], description: "Settings" },
+		],
+	},
+	{
+		title: "View & global",
+		hints: [
+			{
+				action: "toggleIntelligence",
+				keys: ["i"],
+				description: "Toggle intelligence",
+			},
+			{ action: "toggleDensity", keys: ["d"], description: "Toggle density" },
+			{ action: "focusSearch", keys: ["/"], description: "Focus search" },
+			{ action: "compose", keys: ["c"], description: "Compose" },
+			{ action: "compose", keys: ["⌘", "N"], description: "Compose" },
+			{ action: "help", keys: ["?"], description: "Shortcut help" },
+		],
+	},
+];
+
+/**
+ * Look up the displayed key tokens for an action (first matching hint). Used by
+ * toolbar tooltips so a single declaration drives both the overlay and the
+ * button titles. Returns `undefined` for actions with no hint.
+ */
+export function keysForAction(action: TriageAction): string[] | undefined {
+	for (const group of KEY_HINT_GROUPS) {
+		const hint = group.hints.find((h) => h.action === action);
+		if (hint) return hint.keys;
+	}
+	return undefined;
+}
+
+/**
+ * Render an action's binding as it reads to a user, e.g. "r" or "g then b".
+ * Returns "" when the action has no hint.
+ */
+export function shortcutHintForAction(action: TriageAction): string {
+	const keys = keysForAction(action);
+	if (!keys || keys.length === 0) return "";
+	if (keys.length === 1) return keys[0] ?? "";
+	// Sequence (go-to) keys read as "g then b"; modifier combos as "⌘N".
+	if (keys[0] === "g") return keys.join(" then ");
+	return keys.join("");
+}
+
+/**
+ * Render an action's binding as a compact tooltip suffix, e.g. "(r)" or
+ * "(g then b)". Returns "" when the action has no hint.
+ */
+export function tooltipForAction(action: TriageAction): string {
+	const hint = shortcutHintForAction(action);
+	return hint === "" ? "" : `(${hint})`;
+}

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

@@ -0,0 +1,273 @@
+/**
+ * The shared list cursor (#149) — the roving keyboard cursor and multi-selection
+ * every thread list drives. Mounted against jsdom rather than `renderToString`,
+ * since the state only moves in response to real calls across renders.
+ */
+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 ListCursor, useListCursor } from "./use-list-cursor.js";
+
+const IDS = ["m1", "m2", "m3", "m4"];
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+
+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;
+	Object.defineProperty(globalThis, "navigator", {
+		value: dom.window.navigator,
+		configurable: true,
+	});
+	(
+		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);
+});
+
+afterEach(() => {
+	act(() => root.unmount());
+});
+
+/**
+ * Mount the hook and hand back a live handle. Every read goes through
+ * `current()` so a test never asserts against a stale render.
+ */
+function mountCursor(options: {
+	orderedIds?: string[];
+	isDesktop?: boolean;
+	initialFocusedId?: string;
+}): () => ListCursor {
+	let latest: ListCursor | undefined;
+	const Probe = () => {
+		latest = useListCursor({
+			orderedIds: options.orderedIds ?? IDS,
+			isDesktop: options.isDesktop ?? true,
+			initialFocusedId: options.initialFocusedId,
+		});
+		return null;
+	};
+	act(() => root.render(createElement(Probe)));
+	return () => {
+		if (!latest) throw new Error("cursor not mounted");
+		return latest;
+	};
+}
+
+describe("useListCursor — the roving cursor", () => {
+	it("starts on the open thread and walks the list with next/previous", () => {
+		const cursor = mountCursor({ initialFocusedId: "m2" });
+		assert.equal(cursor().focusedMessageId, "m2");
+
+		act(() => cursor().focusNext());
+		assert.equal(cursor().focusedMessageId, "m3");
+
+		act(() => cursor().focusPrevious());
+		assert.equal(cursor().focusedMessageId, "m2");
+	});
+
+	it("starts at the top when nothing is focused yet", () => {
+		const cursor = mountCursor({});
+		assert.equal(cursor().focusedMessageId, undefined);
+
+		act(() => cursor().focusNext());
+		assert.equal(cursor().focusedMessageId, "m1");
+	});
+
+	it("clamps at both ends rather than wrapping", () => {
+		const cursor = mountCursor({ initialFocusedId: "m1" });
+		act(() => cursor().focusPrevious());
+		assert.equal(cursor().focusedMessageId, "m1");
+
+		act(() => cursor().focusLast());
+		assert.equal(cursor().focusedMessageId, "m4");
+		act(() => cursor().focusNext());
+		assert.equal(cursor().focusedMessageId, "m4");
+
+		act(() => cursor().focusFirst());
+		assert.equal(cursor().focusedMessageId, "m1");
+	});
+
+	it("moves nothing when the list is empty", () => {
+		const cursor = mountCursor({ orderedIds: [] });
+		act(() => cursor().focusNext());
+		act(() => cursor().focusLast());
+		assert.equal(cursor().focusedMessageId, undefined);
+	});
+
+	it("asks for DOM focus on its own moves, not on a pointer move", () => {
+		const cursor = mountCursor({ initialFocusedId: "m1" });
+		act(() => cursor().focusNext());
+		assert.equal(cursor().pendingDomFocusRef.current, "m2");
+		assert.equal(cursor().cursorMovedByPointerRef.current, false);
+	});
+});
+
+describe("useListCursor — selection", () => {
+	it("x toggles the row under the cursor", () => {
+		const cursor = mountCursor({ initialFocusedId: "m2" });
+		act(() => cursor().toggleFocusedSelection());
+		assert.deepEqual([...cursor().selection.selectedIds], ["m2"]);
+
+		act(() => cursor().toggleFocusedSelection());
+		assert.equal(cursor().selection.selectedCount, 0);
+	});
+
+	it("shift-extend moves the cursor and grows the range from the anchor", () => {
+		const cursor = mountCursor({ initialFocusedId: "m2" });
+
+		// The first press has no anchor yet, so the row it lands on becomes both
+		// the anchor and the whole range.
+		act(() => cursor().extendRangeDown());
+		assert.deepEqual([...cursor().selection.selectedIds], ["m3"]);
+		assert.equal(cursor().focusedMessageId, "m3");
+		assert.equal(cursor().selection.anchorId, "m3");
+
+		// Consecutive presses extend from that anchor.
+		act(() => cursor().extendRangeDown());
+		assert.deepEqual([...cursor().selection.selectedIds].sort(), ["m3", "m4"]);
+		assert.equal(cursor().focusedMessageId, "m4");
+		assert.equal(cursor().selection.anchorId, "m3");
+	});
+
+	it("shift-extend upward ranges back through the anchor", () => {
+		const cursor = mountCursor({ initialFocusedId: "m4" });
+
+		act(() => cursor().extendRangeUp());
+		assert.deepEqual([...cursor().selection.selectedIds], ["m3"]);
+
+		act(() => cursor().extendRangeUp());
+		assert.deepEqual([...cursor().selection.selectedIds].sort(), ["m2", "m3"]);
+		assert.equal(cursor().focusedMessageId, "m2");
+	});
+
+	it("at the last row, extending takes that row and the cursor stays", () => {
+		const cursor = mountCursor({ initialFocusedId: "m4" });
+		act(() => cursor().extendRangeDown());
+		assert.deepEqual([...cursor().selection.selectedIds], ["m4"]);
+		assert.equal(cursor().focusedMessageId, "m4");
+	});
+
+	it("select-all takes every row, and exiting clears it", () => {
+		const cursor = mountCursor({});
+		act(() => cursor().selectAllLoaded());
+		assert.equal(cursor().selection.selectedCount, IDS.length);
+
+		act(() => cursor().exitSelection());
+		assert.equal(cursor().selection.selectedCount, 0);
+	});
+
+	it("runs the caller's teardown before clearing", () => {
+		const order: string[] = [];
+		let latest: ListCursor | undefined;
+		const Probe = () => {
+			latest = useListCursor({
+				orderedIds: IDS,
+				isDesktop: true,
+				onExitSelection: () => order.push("teardown"),
+			});
+			return null;
+		};
+		act(() => root.render(createElement(Probe)));
+		act(() => latest?.selectAllLoaded());
+		act(() => latest?.exitSelection());
+		assert.deepEqual(order, ["teardown"]);
+		assert.equal(latest?.selection.selectedCount, 0);
+	});
+});
+
+describe("useListCursor — mouse selection semantics", () => {
+	it("shift-click ranges, cmd-click toggles, and both consume the click", () => {
+		const cursor = mountCursor({ initialFocusedId: "m1" });
+
+		let handled = false;
+		act(() => {
+			handled = cursor().handleRowSelect("m3", {
+				shiftKey: true,
+				metaKey: false,
+				ctrlKey: false,
+			});
+		});
+		assert.equal(handled, true);
+		assert.deepEqual([...cursor().selection.selectedIds].sort(), [
+			"m1",
+			"m2",
+			"m3",
+		]);
+
+		act(() => {
+			handled = cursor().handleRowSelect("m4", {
+				shiftKey: false,
+				metaKey: true,
+				ctrlKey: false,
+			});
+		});
+		assert.equal(handled, true);
+		assert.ok(cursor().selection.selectedIds.has("m4"));
+	});
+
+	it("a plain click collapses the selection and lets the row open", () => {
+		const cursor = mountCursor({ initialFocusedId: "m1" });
+		act(() => cursor().selectAllLoaded());
+
+		let handled = true;
+		act(() => {
+			handled = cursor().handleRowSelect("m2", {
+				shiftKey: false,
+				metaKey: false,
+				ctrlKey: false,
+			});
+		});
+		assert.equal(handled, false, "navigation must proceed on a plain click");
+		assert.equal(cursor().selection.selectedCount, 0);
+	});
+});
+
+describe("useListCursor — the device branch", () => {
+	it("is not in multi-select mode on desktop, whatever is selected", () => {
+		const cursor = mountCursor({ isDesktop: true });
+		act(() => cursor().selectAllLoaded());
+		assert.equal(cursor().isMultiSelectMode, false);
+	});
+
+	it("enters multi-select mode on touch as soon as something is selected", () => {
+		const cursor = mountCursor({ isDesktop: false });
+		assert.equal(cursor().isMultiSelectMode, false);
+
+		act(() => cursor().selection.select("m2"));
+		assert.equal(cursor().isMultiSelectMode, true);
+	});
+
+	it("on touch, in multi-select mode, next/previous toggle instead of moving", () => {
+		const cursor = mountCursor({ isDesktop: false, initialFocusedId: "m1" });
+		act(() => cursor().selection.select("m1"));
+
+		act(() => cursor().focusNext());
+		assert.equal(
+			cursor().focusedMessageId,
+			"m1",
+			"the cursor stays put in multi-select mode",
+		);
+		assert.deepEqual([...cursor().selection.selectedIds].sort(), ["m1", "m2"]);
+	});
+});