@remit/ui 0.0.32 → 0.0.34

package/package.json

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

package/src/components/brief-sections.stories.tsx

@@ -176,3 +176,43 @@ export const AccountSources: Story = {
 		);
 	},
 };
+
+/**
+ * (d) Multi-select and the keyboard cursor in the brief. The rows are the same
+ * `Row` the mailbox list renders, so a checked row carries the checkbox and the
+ * selected tint, and the keyboard cursor shows its left accent rail on the row
+ * it sits on — one row implementation across the brief, Flagged and the inbox.
+ */
+export const Selection: Story = {
+	render: (args) => {
+		const [checked, setChecked] = useState<ReadonlySet<string>>(
+			new Set(["p1", "f1"]),
+		);
+		const toggle = (id: string) =>
+			setChecked((prev) => {
+				const next = new Set(prev);
+				if (next.has(id)) next.delete(id);
+				else next.add(id);
+				return next;
+			});
+		return (
+			<div className="flex h-screen w-96 flex-col border-r border-line">
+				<BriefSections
+					{...args}
+					Row={({ thread, active, onClick }) => (
+						<ComfortableRow
+							thread={thread}
+							active={active}
+							focused={thread.id === "p1"}
+							selection={{
+								checked: checked.has(thread.id),
+								onToggle: () => toggle(thread.id),
+							}}
+							onClick={onClick}
+						/>
+					)}
+				/>
+			</div>
+		);
+	},
+};

package/src/components/brief-sections.tsx

@@ -75,6 +75,17 @@ export interface BriefSectionsProps {
 	onSelectSource?: (id: string) => void;
 	/** Seeds the filter panel open on first render (stories / deep links). */
 	defaultExpanded?: boolean;
+	/**
+	 * Whether this component owns arrow-key traversal and the roving tabindex
+	 * over its rows. On by default so a consumer that only passes rows (the
+	 * Storybook prototype) still has a keyboard.
+	 *
+	 * The web client turns it off: its triage layer routes ↑/↓/Home/End through
+	 * one window-level dispatcher, and a container handler here would swallow
+	 * them first — taking Shift+↑/↓ with them, which the dispatcher needs for
+	 * range selection and `rovingNextIndex` ignores.
+	 */
+	manageFocus?: boolean;
 }
 
 /**
@@ -96,11 +107,16 @@ export function BriefSections({
 	sourcesNote,
 	onSelectSource,
 	defaultExpanded = false,
+	manageFocus = true,
 }: BriefSectionsProps) {
 	const [active, setActive] = useState<ReadonlySet<BriefFilterId>>(new Set());
 	const [sheetExpanded, setSheetExpanded] = useState(defaultExpanded);
 	const listRef = useRef<HTMLDivElement>(null);
-	useRovingFocus({ containerRef: listRef, itemSelector: LIST_ROW_SELECTOR });
+	useRovingFocus({
+		containerRef: listRef,
+		itemSelector: LIST_ROW_SELECTOR,
+		enabled: manageFocus,
+	});
 
 	const toggleFilter = (id: BriefFilterId) => {
 		setActive((prev) => {

package/src/components/message-row.render.test.ts

@@ -37,6 +37,32 @@ describe("ComfortableRow", () => {
 	});
 });
 
+describe("ComfortableRow selection slot", () => {
+	it("renders no checkbox without a selection (non-selectable mode)", () => {
+		const html = renderToString(
+			createElement(ComfortableRow, { thread: { ...base, isRead: true } }),
+		);
+		assert.doesNotMatch(html, /Select message/);
+	});
+
+	it("renders a checkbox reflecting the checked state", () => {
+		const unchecked = renderToString(
+			createElement(ComfortableRow, {
+				thread: { ...base, isRead: true },
+				selection: { checked: false, onToggle: () => undefined },
+			}),
+		);
+		const checked = renderToString(
+			createElement(ComfortableRow, {
+				thread: { ...base, isRead: true },
+				selection: { checked: true, onToggle: () => undefined },
+			}),
+		);
+		assert.match(unchecked, /Select message/);
+		assert.match(checked, /Deselect message/);
+	});
+});
+
 describe("CompactRow", () => {
 	it("renders fromName and subject", () => {
 		const html = renderToString(

package/src/components/message-row.stories.tsx

@@ -112,10 +112,40 @@ export const Compact: Story = {
 export const States: Story = {
 	render: () => (
 		<List>
-			<ComfortableRow thread={unread} />
-			<ComfortableRow thread={read} />
+			<ComfortableRow thread={unread} active />
+			<ComfortableRow thread={read} focused />
 			<ComfortableRow thread={starred} />
 			<ComfortableRow thread={suspicious} />
 		</List>
 	),
 };
+
+/**
+ * Selectable rows. The checkbox layers over the avatar: hidden until hover
+ * while unchecked, pinned visible once checked or while the list is in
+ * multi-select mode. A row rendered without `selection` — the brief and
+ * Flagged before they gained selection — shows the avatar alone.
+ */
+export const Selectable: Story = {
+	render: () => (
+		<List>
+			<ComfortableRow
+				thread={unread}
+				selection={{ checked: true, onToggle: () => undefined }}
+			/>
+			<ComfortableRow
+				thread={read}
+				selection={{ checked: false, onToggle: () => undefined }}
+			/>
+			<ComfortableRow
+				thread={starred}
+				selection={{
+					checked: false,
+					alwaysVisible: true,
+					onToggle: () => undefined,
+				}}
+			/>
+			<ComfortableRow thread={withCategory} />
+		</List>
+	),
+};

package/src/components/message-row.tsx

@@ -1,5 +1,5 @@
-import { Paperclip, ShieldAlert, Star } from "lucide-react";
-import type { ReactNode } from "react";
+import { Check, Paperclip, ShieldAlert, Star } from "lucide-react";
+import type { ComponentType, ReactNode, SyntheticEvent } from "react";
 import { cn } from "../lib/cn.js";
 import { LIST_ROW_ATTRIBUTE } from "../lib/roving-focus.js";
 import { categoryTone, type ThreadRowData } from "./app-shell-types.js";
@@ -173,18 +173,106 @@ export function ComfortableRowTextContent({
 }
 
 /**
- * Full inner body of a comfortable row (unread dot + avatar + text content).
- * Place inside any wrapper element that uses `comfortableRowClass()`.
+ * Checkbox state for a selectable row. Absent on a row that cannot be
+ * multi-selected (the brief and Flagged before they gained selection), which
+ * renders the avatar alone.
  */
-export function ComfortableRowBody({ thread }: { thread: ThreadRowData }) {
+/** What the toggle handler needs off the click or keypress that triggered it. */
+export type RowToggleEvent = Pick<
+	SyntheticEvent,
+	"preventDefault" | "stopPropagation"
+>;
+
+export interface RowSelection {
+	checked: boolean;
+	/** Keep the checkbox visible instead of revealing it on hover (mobile). */
+	alwaysVisible?: boolean;
+	onToggle: (event: RowToggleEvent) => void;
+}
+
+/**
+ * Leading slot of a comfortable row: the avatar, with a checkbox layered over
+ * it when the row is selectable. Fixed 28px so the row never reflows as the
+ * checkbox appears.
+ */
+export function ComfortableRowLeading({
+	thread,
+	selection,
+}: {
+	thread: ThreadRowData;
+	selection?: RowSelection;
+}) {
+	if (!selection) {
+		return <Avatar name={thread.fromName} email={thread.fromEmail} size="sm" />;
+	}
+	const { checked, alwaysVisible } = selection;
+	return (
+		<span className="relative size-7 shrink-0">
+			<Avatar
+				name={thread.fromName}
+				email={thread.fromEmail}
+				size="sm"
+				className={cn(
+					"absolute inset-0 transition-opacity sm:group-hover:opacity-0",
+					(checked || alwaysVisible) && "opacity-0",
+				)}
+			/>
+			{/* A span, not a <button>: the row itself is a button (the brief,
+			    Flagged) or a link (the mailbox list), and neither may nest an
+			    interactive element. The button role and label are what the user and
+			    the test suite address, so both stay. */}
+			{/* biome-ignore lint/a11y/useSemanticElements: a nested <button> inside the row's own button/link is invalid HTML */}
+			<span
+				role="button"
+				// Out of the tab order: the row is the list's single tab stop, and this
+				// control is `opacity-0` until hover, so a tabbable one would put focus
+				// on something invisible on every row.
+				tabIndex={-1}
+				onClick={selection.onToggle}
+				onKeyDown={(event) => {
+					if (event.key !== "Enter" && event.key !== " ") return;
+					event.preventDefault();
+					event.stopPropagation();
+					selection.onToggle(event);
+				}}
+				className={cn(
+					"absolute inset-0 size-7 items-center justify-center rounded-full border transition-opacity",
+					alwaysVisible ? "flex" : "hidden sm:flex",
+					checked
+						? "bg-accent border-accent text-accent-fg opacity-100"
+						: alwaysVisible
+							? "border-fg-subtle/40 bg-canvas opacity-100"
+							: "border-fg-subtle/40 bg-canvas opacity-0 group-hover:opacity-100",
+				)}
+				aria-label={checked ? "Deselect message" : "Select message"}
+			>
+				{checked && <Check className="size-3" />}
+			</span>
+		</span>
+	);
+}
+
+/**
+ * Full inner body of a comfortable row (unread dot + leading slot + text
+ * content). Place inside any wrapper element that uses `comfortableRowClass()`.
+ */
+export function ComfortableRowBody({
+	thread,
+	selection,
+	badge,
+}: {
+	thread: ThreadRowData;
+	selection?: RowSelection;
+	badge?: ReactNode;
+}) {
 	const unread = !thread.isRead;
 	return (
 		<>
 			{unread && (
 				<span className="absolute left-1.5 top-1/2 size-1.5 -translate-y-1/2 rounded-full bg-accent" />
 			)}
-			<Avatar name={thread.fromName} email={thread.fromEmail} size="sm" />
-			<ComfortableRowTextContent thread={thread} />
+			<ComfortableRowLeading thread={thread} selection={selection} />
+			<ComfortableRowTextContent thread={thread} badge={badge} />
 		</>
 	);
 }
@@ -192,10 +280,12 @@ export function ComfortableRowBody({ thread }: { thread: ThreadRowData }) {
 export function CompactRow({
 	thread,
 	active,
+	focused,
 	onClick,
 }: {
 	thread: ThreadRowData;
 	active?: boolean;
+	focused?: boolean;
 	onClick?: () => void;
 }) {
 	return (
@@ -203,7 +293,7 @@ export function CompactRow({
 			type="button"
 			{...LIST_ROW_ATTRIBUTE}
 			onClick={onClick}
-			className={compactRowClass({ active })}
+			className={compactRowClass({ active, focused })}
 		>
 			<CompactRowBody thread={thread} />
 		</button>
@@ -213,10 +303,14 @@ export function CompactRow({
 export function ComfortableRow({
 	thread,
 	active,
+	focused,
+	selection,
 	onClick,
 }: {
 	thread: ThreadRowData;
 	active?: boolean;
+	focused?: boolean;
+	selection?: RowSelection;
 	onClick?: () => void;
 }) {
 	return (
@@ -224,17 +318,17 @@ export function ComfortableRow({
 			type="button"
 			{...LIST_ROW_ATTRIBUTE}
 			onClick={onClick}
-			className={comfortableRowClass({ active })}
+			className={cn("group", comfortableRowClass({ active, focused }))}
 		>
-			<ComfortableRowBody thread={thread} />
+			<ComfortableRowBody thread={thread} selection={selection} />
 		</button>
 	);
 }
 
 /** A row renderer the brief drives — Comfortable/Compact rows or a consumer's
  *  own (e.g. the web client's navigation-aware row) all satisfy this shape. */
-export type BriefRowComponent = (props: {
+export type BriefRowComponent = ComponentType<{
 	thread: ThreadRowData;
 	active?: boolean;
 	onClick?: () => void;
-}) => React.ReactNode;
+}>;

package/src/index.ts

@@ -203,11 +203,14 @@ export {
 	type BriefRowComponent,
 	ComfortableRow,
 	ComfortableRowBody,
+	ComfortableRowLeading,
 	ComfortableRowTextContent,
 	CompactRow,
 	CompactRowBody,
 	comfortableRowClass,
 	compactRowClass,
+	type RowSelection,
+	type RowToggleEvent,
 } from "./components/message-row.js";
 export {
 	type MobileMessageAction,

package/src/lib/roving-focus.ts

@@ -43,6 +43,11 @@ export interface UseRovingFocusOptions {
 	/** CSS selector, scoped to the container, matching every roving item. */
 	itemSelector: string;
 	orientation?: RovingOrientation;
+	/**
+	 * Off when a keyboard layer above the group owns the same keys — the hook
+	 * binds nothing and leaves the tabindex to whoever does. Defaults on.
+	 */
+	enabled?: boolean;
 }
 
 function rovingItems(
@@ -70,10 +75,12 @@ export function useRovingFocus({
 	containerRef,
 	itemSelector,
 	orientation = "vertical",
+	enabled = true,
 }: UseRovingFocusOptions): void {
 	// No dependency array: items appear and disappear as sections expand, rows
 	// load, or filters change, none of which this hook's own inputs describe.
 	useEffect(() => {
+		if (!enabled) return;
 		const container = containerRef.current;
 		if (!container) return;