@remit/ui 0.0.80 → 0.0.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.80",
+  "version": "0.0.81",
   "type": "module",
   "files": [
     "src"

package/src/components/app-shell-types.ts

@@ -6,6 +6,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import type { TriageHandlers } from "../lib/keymap.js";
 import type { SelectionModifiers } from "../lib/use-selection.js";
 import type {
 	IntelligenceData,
@@ -84,6 +85,25 @@ export interface MessageListSelection {
 	onRowSelect?: (id: string, modifiers: SelectionModifiers) => boolean;
 }
 
+/**
+ * The keyboard layer above the list, owned by whoever mounts it. The handler
+ * table is what the pane reads: it offers the keys that table answers, draws
+ * the cursor the ones it answers move, and keeps its own arrow-key traversal
+ * for the ones it does not. A layer that answers nothing offers nothing, so a
+ * host cannot advertise a key it has not wired.
+ *
+ * `useListKeyboard` builds it; the pane hands `ref` back the element the layer
+ * listens on.
+ */
+export interface MessageListKeyboard {
+	/** The row the cursor sits on. */
+	focusedId: string | undefined;
+	/** What the layer answers, and therefore what the footer offers. */
+	handlers: TriageHandlers;
+	/** Takes the pane element the layer binds its keys to. */
+	ref: (element: HTMLElement | null) => void;
+}
+
 /**
  * Measures an element's OWN width via ResizeObserver — a container query, not a
  * viewport one. The shell reflows by the space it actually occupies (so it works
@@ -363,6 +383,8 @@ export interface AppShellProps {
 	selectionBar?: ReactNode;
 	/** The list's selection, forwarded to `MessageListPane`. */
 	selection?: MessageListSelection;
+	/** The list's keyboard layer, forwarded to `MessageListPane`. */
+	keyboard?: MessageListKeyboard;
 	intelligence?: IntelligenceData;
 	/** Pane 4 visible. Defaults to true when intelligence is present. */
 	intelligenceOpen?: boolean;

package/src/components/app-shell.tsx

@@ -71,6 +71,7 @@ export function AppShell({
 	initialNarrowView = "list",
 	initialTouchState,
 	selection,
+	keyboard,
 	selectionBar,
 	intelligence,
 	intelligenceOpen = true,
@@ -129,6 +130,7 @@ export function AppShell({
 			onSelectBriefCategory={selectCategory}
 			initialTouchState={initialTouchState}
 			selection={selection}
+			keyboard={keyboard}
 			selectionBar={selectionBar}
 		/>
 	);
@@ -190,6 +192,7 @@ function AppShellList({
 	onSelectBriefCategory,
 	initialTouchState,
 	selection,
+	keyboard,
 	selectionBar,
 }: Pick<
 	AppShellProps,
@@ -209,6 +212,7 @@ function AppShellList({
 	| "onSelectThread"
 	| "initialTouchState"
 	| "selection"
+	| "keyboard"
 	| "selectionBar"
 > & {
 	narrowView: NarrowView;
@@ -252,6 +256,7 @@ function AppShellList({
 			isDesktop={showReadingPane}
 			initialTouchState={initialTouchState}
 			selection={selection}
+			keyboard={keyboard}
 			selectionBar={selectionBar}
 		/>
 	);

package/src/components/keyboard-hint-bar.render.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { keyboardHintsFor } from "../lib/keymap.js";
+import { KeyboardHintBar } from "./keyboard-hint-bar.js";
+
+describe("KeyboardHintBar", () => {
+	it("offers the app's own set by default", () => {
+		const html = renderToString(createElement(KeyboardHintBar));
+		assert.match(html, /<span>navigate<\/span>/);
+		assert.match(html, /<span>mute<\/span>/);
+		assert.match(html, /<span>all shortcuts<\/span>/);
+	});
+
+	it("offers only what the host's handlers answer", () => {
+		const hints = keyboardHintsFor({ focusNext: () => undefined });
+		const html = renderToString(createElement(KeyboardHintBar, { hints }));
+		assert.match(html, /<span>navigate<\/span>/);
+		assert.doesNotMatch(html, /<span>mute<\/span>/);
+		assert.doesNotMatch(html, /<span>all shortcuts<\/span>/);
+	});
+
+	it("renders nothing for a host that serves none of them", () => {
+		const hints = keyboardHintsFor({ toggleStar: () => undefined });
+		assert.deepEqual(hints, []);
+		assert.equal(renderToString(createElement(KeyboardHintBar, { hints })), "");
+	});
+});

package/src/components/keyboard-hint-bar.tsx

@@ -1,27 +1,14 @@
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
+import { defaultKeyboardHints, type KeyboardHint } from "../lib/keymap.js";
 import { Kbd } from "./kbd.js";
 
-export interface KeyboardHint {
-	/** One or more keys shown as `Kbd` chips. */
-	keys: string[];
-	/** What the keys do. */
-	label: string;
-}
-
 export interface KeyboardHintBarProps {
 	/** Override the default hint set. */
 	hints?: KeyboardHint[];
 	className?: string;
 }
 
-/** The persistent message-list footer hint set (desktop). */
-export const defaultKeyboardHints: KeyboardHint[] = [
-	{ keys: ["j", "k"], label: "navigate" },
-	{ keys: ["m"], label: "mute" },
-	{ keys: ["?"], label: "all shortcuts" },
-];
-
 /**
  * The keyboard-shortcut hint footer under the message list. Keyboard-first
  * discoverability — the shortcuts aren't hidden behind the `?` modal. The host
@@ -32,6 +19,7 @@ export function KeyboardHintBar({
 	hints = defaultKeyboardHints,
 	className,
 }: KeyboardHintBarProps) {
+	if (hints.length === 0) return null;
 	return (
 		<footer
 			className={cn(

package/src/components/message-list-pane.stories.tsx

@@ -1,12 +1,8 @@
 import type { Decorator, Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
 import { inboxFilterConfig } from "../filter-presets.js";
-import {
-	rowSelectIntent,
-	type SelectionModifiers,
-	useSelection,
-} from "../lib/use-selection.js";
-import type { ThreadSection } from "./app-shell-types.js";
+import { useListKeyboard } from "../lib/use-list-keyboard.js";
+import type { MessageListKeyboard, ThreadSection } from "./app-shell-types.js";
 import { FilterSheet } from "./filter-sheet.js";
 import { MailHeader } from "./mail-header.js";
 import { MessageListPane } from "./message-list-pane.js";
@@ -89,8 +85,41 @@ const narrowFrame: Decorator = (Story) => (
 	</div>
 );
 
+/**
+ * A pane with no keyboard over it — a story whose rows come from elsewhere, or
+ * that has no rows at all. It answers nothing and so offers nothing.
+ */
+const noKeyboard: MessageListKeyboard = {
+	focusedId: undefined,
+	handlers: {},
+	ref: () => undefined,
+};
+
+/**
+ * The list under the triage keyboard: j/k walk the rows, x and Space tick the
+ * one under the cursor, Shift+j/k build a range and ⌘A takes them all. The
+ * footer offers what is wired.
+ */
+function LiveList({ briefFilters = false }: { briefFilters?: boolean }) {
+	const orderedIds = sections.flatMap((s) => s.threads).map((t) => t.id);
+	const list = useListKeyboard({ orderedIds, isDesktop: true });
+	return (
+		<MessageListPane
+			listTitle="Inbox"
+			listMeta="3 conversations"
+			sections={sections}
+			flatList={!briefFilters}
+			briefFilters={briefFilters}
+			isDesktop
+			onSelectThread={() => undefined}
+			selection={list.selection}
+			keyboard={list.keyboard}
+		/>
+	);
+}
+
 export const DesktopList: Story = {
-	args: { isDesktop: true, flatList: true },
+	render: () => <LiveList />,
 	decorators: [desktopFrame],
 };
 
@@ -100,7 +129,7 @@ export const NarrowTouchList: Story = {
 };
 
 export const Brief: Story = {
-	args: { isDesktop: true, briefFilters: true, sections },
+	render: () => <LiveList briefFilters />,
 	decorators: [desktopFrame],
 };
 
@@ -187,13 +216,14 @@ export const InboxWithFilterExpanded: Story = {
 	decorators: [narrowFrame],
 };
 
-/** Consumer-supplied `listBody` slot — the pane renders the chrome (header,
- *  keyboard hints) while the caller owns the scrollable rows. This models
- *  the web-client's virtualized inbox path. */
+/** Consumer-supplied `listBody` slot — the pane renders the chrome while the
+ *  caller owns the scrollable rows, and the keys over those rows with them.
+ *  This models the web-client's virtualized inbox path. */
 export const CustomListBody: Story = {
 	args: {
 		isDesktop: true,
 		flatList: true,
+		keyboard: noKeyboard,
 		listBody: (
 			<div className="flex-1 overflow-y-auto divide-y divide-line">
 				{sections.flatMap((s) =>
@@ -217,7 +247,6 @@ export const CustomListBody: Story = {
 };
 
 function SelectableList({ isDesktop }: { isDesktop: boolean }) {
-	const selection = useSelection();
 	const [trashedIds, setTrashedIds] = useState<ReadonlySet<string>>(new Set());
 	const [readIds, setReadIds] = useState<ReadonlySet<string>>(new Set());
 
@@ -230,6 +259,8 @@ function SelectableList({ isDesktop }: { isDesktop: boolean }) {
 			),
 	}));
 	const orderedIds = visible.flatMap((s) => s.threads).map((t) => t.id);
+	const list = useListKeyboard({ orderedIds, isDesktop });
+	const { selection } = list.cursor;
 	const allSelected =
 		orderedIds.length > 0 &&
 		orderedIds.every((id) => selection.selectedIds.has(id));
@@ -239,24 +270,6 @@ function SelectableList({ isDesktop }: { isDesktop: boolean }) {
 		selection.clearSelection();
 	};
 
-	// Shift and cmd/ctrl come off a mouse, which the touch list has no path for.
-	const onRowSelect = isDesktop
-		? (id: string, modifiers: SelectionModifiers) => {
-				const intent = rowSelectIntent(modifiers);
-				if (intent === "range") {
-					selection.selectRange(orderedIds, id);
-					return true;
-				}
-				if (intent === "toggle") {
-					selection.toggle(id);
-					return true;
-				}
-				selection.clearSelection();
-				selection.setAnchor(id);
-				return false;
-			}
-		: undefined;
-
 	return (
 		<MessageListPane
 			listTitle="Inbox"
@@ -265,11 +278,8 @@ function SelectableList({ isDesktop }: { isDesktop: boolean }) {
 			flatList
 			isDesktop={isDesktop}
 			onSelectThread={() => undefined}
-			selection={{
-				selectedIds: selection.selectedIds,
-				onToggle: selection.toggle,
-				onRowSelect,
-			}}
+			selection={list.selection}
+			keyboard={list.keyboard}
 			selectionBar={
 				<SelectionTopBar
 					title="Inbox"
@@ -328,6 +338,7 @@ export const EmptyState: Story = {
 		isDesktop: true,
 		flatList: true,
 		listState: "empty",
+		keyboard: noKeyboard,
 	},
 	decorators: [desktopFrame],
 };
@@ -342,6 +353,7 @@ export const FilteredEmptyState: Story = {
 		isDesktop: true,
 		flatList: true,
 		listState: "empty",
+		keyboard: noKeyboard,
 		listFilter: {
 			label: "Personal",
 			reach: "whole-folder",
@@ -360,6 +372,7 @@ export const ErrorState: Story = {
 		isDesktop: true,
 		flatList: true,
 		listState: "error",
+		keyboard: noKeyboard,
 		errorMessage: "Request timed out while loading this mailbox.",
 		onRetry: () => undefined,
 		onReportError: () => undefined,

package/src/components/message-list-pane.tsx

@@ -1,10 +1,12 @@
 import { Menu } from "lucide-react";
 import type { MouseEvent, ReactNode } from "react";
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { defaultKeyboardHints, keyboardHintsFor } from "../lib/keymap.js";
 import { LIST_ROW_SELECTOR, useRovingFocus } from "../lib/roving-focus.js";
 import { deriveIsMultiSelectMode, modifiersOf } from "../lib/use-selection.js";
 import type {
 	AppShellProps,
+	MessageListKeyboard,
 	MessageListSelection,
 	TouchSeed,
 } from "./app-shell-types.js";
@@ -54,6 +56,7 @@ export function MessageListPane({
 	isDesktop,
 	initialTouchState,
 	selection,
+	keyboard,
 	selectionBar,
 	paneOverlay,
 	listBody,
@@ -103,6 +106,13 @@ export function MessageListPane({
 	 * none of it. Absent means the list does not offer multi-select.
 	 */
 	selection?: MessageListSelection;
+	/**
+	 * The keyboard layer driving the list, when the caller mounts one. The pane
+	 * binds it to its own element, draws the cursor it moves and offers only the
+	 * keys its handlers answer; absent, the footer offers the app's own set and
+	 * the rows keep their arrow-key traversal.
+	 */
+	keyboard?: MessageListKeyboard;
 	/**
 	 * The pane header. The caller mounts it for every state of the list: a
 	 * `SelectionTopBar` names the view while nothing is ticked and carries the
@@ -134,11 +144,60 @@ export function MessageListPane({
 }) {
 	const Row = density === "compact" ? CompactRow : ComfortableRow;
 	const flatListRef = useRef<HTMLDivElement>(null);
+	const paneRef = useRef<HTMLElement | null>(null);
+
+	// The layer answers the arrows only if it registered them. Anything else it
+	// hands over — a layer with no cursor keys, or no layer at all — leaves the
+	// rows their own traversal and their own single tab stop.
+	const walksRows =
+		keyboard !== undefined &&
+		keyboard.handlers.focusNext !== undefined &&
+		keyboard.handlers.focusPrevious !== undefined;
 	useRovingFocus({
 		containerRef: flatListRef,
 		itemSelector: LIST_ROW_SELECTOR,
+		enabled: !walksRows,
 	});
 
+	const cursorId = walksRows ? keyboard.focusedId : undefined;
+	// One tab stop into the list, as the roving group gives it: the row the
+	// cursor is on, or the first row before it has moved.
+	const tabStopId = walksRows
+		? (cursorId ?? sections[0]?.threads[0]?.id)
+		: undefined;
+	const rowTabIndex = useCallback(
+		(id: string): number | undefined =>
+			tabStopId === undefined ? undefined : id === tabStopId ? 0 : -1,
+		[tabStopId],
+	);
+
+	// Real browser focus follows the cursor, so Tab, Shift+Tab and the focus
+	// ring agree with the row the list highlights — and so the keys keep
+	// reaching the layer, which listens on the pane rather than the window.
+	useEffect(() => {
+		if (cursorId === undefined) return;
+		const pane = paneRef.current;
+		if (!pane) return;
+		const row = pane.querySelector<HTMLElement>(
+			`${LIST_ROW_SELECTOR}[data-message-id="${cursorId}"]`,
+		);
+		if (!row || row === pane.ownerDocument.activeElement) return;
+		row.focus({ preventScroll: false });
+	}, [cursorId]);
+
+	// A layer bound to this pane hears nothing until focus is inside it. Taking
+	// focus on mount is what keeps j working without a click first — and only
+	// from a document where nothing else has claimed it, so a page of stories
+	// does not fight over the caret.
+	useEffect(() => {
+		if (!walksRows) return;
+		const pane = paneRef.current;
+		if (!pane) return;
+		const active = pane.ownerDocument.activeElement;
+		if (active !== null && active !== pane.ownerDocument.body) return;
+		pane.focus({ preventScroll: true });
+	}, [walksRows]);
+
 	const touchTriage = !isDesktop && !briefFilters && listState === "ready";
 	const [refreshing, setRefreshing] = useState(false);
 	const initialPeek: SwipePeek | undefined =
@@ -198,6 +257,8 @@ export function MessageListPane({
 			<Row
 				thread={thread}
 				active={active}
+				focused={thread.id === cursorId}
+				tabIndex={rowTabIndex(thread.id)}
 				selection={rowSelection(thread.id)}
 				onClick={(event) => {
 					if (takeRowSelect(thread.id, event)) return;
@@ -205,11 +266,18 @@ export function MessageListPane({
 				}}
 			/>
 		),
-		[Row, rowSelection, takeRowSelect],
+		[Row, rowSelection, takeRowSelect, cursorId, rowTabIndex],
 	);
 
 	return (
-		<section className="relative flex h-full w-full flex-col bg-surface">
+		<section
+			ref={(element) => {
+				paneRef.current = element;
+				keyboard?.ref(element);
+			}}
+			tabIndex={walksRows ? -1 : undefined}
+			className="relative flex h-full w-full flex-col bg-surface outline-none"
+		>
 			{selectionBar ??
 				(hideHeader ? null : (
 					<header className="flex h-pane-header shrink-0 items-center gap-2 border-b border-line px-row-inset">
@@ -302,6 +370,8 @@ export function MessageListPane({
 										key={thread.id}
 										thread={thread}
 										active={thread.id === selectedThreadId}
+										focused={thread.id === cursorId}
+										tabIndex={rowTabIndex(thread.id)}
 										selection={rowSelection(thread.id)}
 										onClick={(event) => {
 											if (takeRowSelect(thread.id, event)) return;
@@ -315,7 +385,15 @@ export function MessageListPane({
 				</div>
 			)}
 
-			{isDesktop && <KeyboardHintBar />}
+			{isDesktop && (
+				<KeyboardHintBar
+					hints={
+						keyboard
+							? keyboardHintsFor(keyboard.handlers)
+							: defaultKeyboardHints
+					}
+				/>
+			)}
 			{paneOverlay}
 		</section>
 	);

package/src/components/message-row.tsx

@@ -6,6 +6,7 @@ import type {
 	SyntheticEvent,
 } from "react";
 import { cn } from "../lib/cn.js";
+import { ROW_ATTRIBUTE } from "../lib/keymap-dispatch.js";
 import { LIST_ROW_ATTRIBUTE } from "../lib/roving-focus.js";
 import { categoryTone, type ThreadRowData } from "./app-shell-types.js";
 import { Avatar } from "./avatar.js";
@@ -324,21 +325,37 @@ export function ComfortableRowBody({
 	);
 }
 
+/**
+ * What marks a row as a row: the roving-focus marker, the message-list marker
+ * the keyboard layer reads to leave Enter and Space with the list rather than
+ * with the button under focus, and the id the cursor finds it by. The app's own
+ * row carries the same three (`MessageRow`), so a key pressed on a kit row does
+ * what it does on an app row.
+ */
+const rowMarkers = (thread: ThreadRowData) => ({
+	...LIST_ROW_ATTRIBUTE,
+	[ROW_ATTRIBUTE]: "",
+	"data-message-id": thread.id,
+});
+
 export function CompactRow({
 	thread,
 	active,
 	focused,
+	tabIndex,
 	onClick,
 }: {
 	thread: ThreadRowData;
 	active?: boolean;
 	focused?: boolean;
+	tabIndex?: number;
 	onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
 }) {
 	return (
 		<button
 			type="button"
-			{...LIST_ROW_ATTRIBUTE}
+			{...rowMarkers(thread)}
+			tabIndex={tabIndex}
 			onClick={onClick}
 			className={compactRowClass({ active, focused })}
 		>
@@ -351,19 +368,22 @@ export function ComfortableRow({
 	thread,
 	active,
 	focused,
+	tabIndex,
 	selection,
 	onClick,
 }: {
 	thread: ThreadRowData;
 	active?: boolean;
 	focused?: boolean;
+	tabIndex?: number;
 	selection?: RowSelection;
 	onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
 }) {
 	return (
 		<button
 			type="button"
-			{...LIST_ROW_ATTRIBUTE}
+			{...rowMarkers(thread)}
+			tabIndex={tabIndex}
 			onClick={onClick}
 			className={cn("group", comfortableRowClass({ active, focused }))}
 		>

package/src/index.ts

@@ -30,6 +30,7 @@ export {
 	type Density,
 	INTELLIGENCE_MIN_WIDTH,
 	isBriefCategory,
+	type MessageListKeyboard,
 	type MessageListSelection,
 	type NarrowView,
 	type NavAccount,
@@ -270,8 +271,6 @@ export {
 } from "./components/isolated-email-frame.js";
 export { Kbd, type KbdProps } from "./components/kbd.js";
 export {
-	defaultKeyboardHints,
-	type KeyboardHint,
 	KeyboardHintBar,
 	type KeyboardHintBarProps,
 } from "./components/keyboard-hint-bar.js";
@@ -668,6 +667,28 @@ export {
 	isFocusable,
 	isSelectable,
 } from "./lib/folder-tree-focus.js";
+export {
+	defaultKeyboardHints,
+	KEY_HINT_GROUPS,
+	type KeyboardHint,
+	type KeyHint,
+	type KeyHintGroup,
+	keyboardHintsFor,
+	keysForAction,
+	shortcutHintForAction,
+	type TriageAction,
+	type TriageHandlers,
+	tooltipForAction,
+} from "./lib/keymap.js";
+export {
+	type DispatchResult,
+	dispatchKey,
+	isControlTarget,
+	isEditableTarget,
+	type KeyStroke,
+	ROW_ATTRIBUTE,
+	type SequencePrefix,
+} from "./lib/keymap-dispatch.js";
 export {
 	isLabelColorValue,
 	type LabelColorValue,
@@ -708,6 +729,12 @@ export {
 	type SuggestKeyState,
 	suggestKeyAction,
 } from "./lib/suggest-keys.js";
+export { type ListCursor, useListCursor } from "./lib/use-list-cursor.js";
+export {
+	type ListKeyboard,
+	type UseListKeyboardOptions,
+	useListKeyboard,
+} from "./lib/use-list-keyboard.js";
 export {
 	type UseLongPressOptions,
 	type UseLongPressResult,
@@ -733,6 +760,7 @@ export {
 	type UseSuggestListInput,
 	useSuggestList,
 } from "./lib/use-suggest-list.js";
+export { useTriageKeyboard } from "./lib/use-triage-keyboard.js";
 export {
 	backExits,
 	clauseSentence,