@remit/ui 0.0.79 → 0.0.81

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";
@@ -68,7 +64,6 @@ const meta: Meta<typeof MessageListPane> = {
 		listMeta: "3 conversations",
 		sections,
 		onSelectThread: () => undefined,
-		onSelectBriefCategory: () => undefined,
 	},
 };
 export default meta;
@@ -90,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],
 };
 
@@ -101,7 +129,7 @@ export const NarrowTouchList: Story = {
 };
 
 export const Brief: Story = {
-	args: { isDesktop: true, briefFilters: true, sections },
+	render: () => <LiveList briefFilters />,
 	decorators: [desktopFrame],
 };
 
@@ -188,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) =>
@@ -218,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());
 
@@ -231,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));
@@ -240,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"
@@ -266,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"
@@ -329,6 +338,7 @@ export const EmptyState: Story = {
 		isDesktop: true,
 		flatList: true,
 		listState: "empty",
+		keyboard: noKeyboard,
 	},
 	decorators: [desktopFrame],
 };
@@ -343,6 +353,7 @@ export const FilteredEmptyState: Story = {
 		isDesktop: true,
 		flatList: true,
 		listState: "empty",
+		keyboard: noKeyboard,
 		listFilter: {
 			label: "Personal",
 			reach: "whole-folder",
@@ -361,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,14 +1,16 @@
 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";
-import { BriefSections } from "./brief-sections.js";
+import { type BriefFilterSurface, BriefSections } from "./brief-sections.js";
 import { Button } from "./button.js";
 import { KeyboardHintBar } from "./keyboard-hint-bar.js";
 import {
@@ -46,15 +48,15 @@ export function MessageListPane({
 	errorMessage,
 	onRetry,
 	onReportError,
-	briefCategory,
+	briefFilter,
 	selectedThreadId,
 	density = "comfortable",
 	onSelectThread,
-	onSelectBriefCategory,
 	onOpenNav,
 	isDesktop,
 	initialTouchState,
 	selection,
+	keyboard,
 	selectionBar,
 	paneOverlay,
 	listBody,
@@ -71,11 +73,9 @@ export function MessageListPane({
 	| "errorMessage"
 	| "onRetry"
 	| "onReportError"
-	| "briefCategory"
 	| "selectedThreadId"
 	| "density"
 	| "onSelectThread"
-	| "onSelectBriefCategory"
 > & {
 	/**
 	 * The active category filter, when the caller has one. Without it the empty
@@ -84,6 +84,14 @@ export function MessageListPane({
 	 * unfiltered, so a surface that filters must pass this.
 	 */
 	listFilter?: MessageListFilter;
+	/**
+	 * The brief's category scope, account pills and attribute chips, held by the
+	 * caller. The cross-account brief is segmented from this panel, and a caller
+	 * narrowing the same rows on a second surface hands both the one set it
+	 * holds. Absent, the chips are the brief's own, no source row is offered and
+	 * every category is in scope.
+	 */
+	briefFilter?: BriefFilterSurface;
 	/** Name of the collection, e.g. "Inbox". Passed to the empty state. */
 	listScopeLabel?: string;
 	/** When set, the list header shows a folders/menu button that opens the nav
@@ -98,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
@@ -129,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 =
@@ -193,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;
@@ -200,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">
@@ -250,12 +323,11 @@ export function MessageListPane({
 				/>
 			) : briefFilters ? (
 				<BriefSections
+					{...(briefFilter ?? {})}
 					sections={sections}
-					briefCategory={briefCategory}
 					selectedThreadId={selectedThreadId}
 					Row={BriefRow}
 					onSelectThread={onSelectThread}
-					onSelectBriefCategory={onSelectBriefCategory}
 				/>
 			) : listBody != null ? (
 				/* Consumer-provided body wins on every width — it owns the rows
@@ -298,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;
@@ -311,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

@@ -29,6 +29,8 @@ export {
 	categoryTone,
 	type Density,
 	INTELLIGENCE_MIN_WIDTH,
+	isBriefCategory,
+	type MessageListKeyboard,
 	type MessageListSelection,
 	type NarrowView,
 	type NavAccount,
@@ -87,9 +89,14 @@ export {
 	SECTION_ROW_CAP,
 } from "./components/brief-section.js";
 export {
+	type BriefCategoryControl,
+	type BriefFilterControl,
 	type BriefFilterId,
+	type BriefFilterSurface,
 	BriefSections,
 	type BriefSectionsProps,
+	type BriefSourceControl,
+	isBriefFilterId,
 	matchesBriefFilters,
 } from "./components/brief-sections.js";
 export {
@@ -264,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";
@@ -662,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,
@@ -702,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,
@@ -727,6 +760,7 @@ export {
 	type UseSuggestListInput,
 	useSuggestList,
 } from "./lib/use-suggest-list.js";
+export { useTriageKeyboard } from "./lib/use-triage-keyboard.js";
 export {
 	backExits,
 	clauseSentence,