@remit/ui 0.0.1

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

@@ -0,0 +1,246 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { inboxFilterConfig } from "../filter-presets.js";
+import type { 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";
+import { SelectionTopBar } from "./selection-top-bar.js";
+
+const sections: ThreadSection[] = [
+	{
+		id: "today",
+		label: "Today",
+		threads: [
+			{
+				id: "t1",
+				accountId: "a1",
+				fromName: "Alex Rivera",
+				fromEmail: "alex@example.com",
+				subject: "Q3 planning notes",
+				snippet: "Here are the notes from today's planning session.",
+				timeLabel: "9:42",
+				category: "personal",
+			},
+			{
+				id: "t2",
+				accountId: "a1",
+				fromName: "Acme Billing",
+				fromEmail: "billing@acme.com",
+				subject: "Your invoice is ready",
+				snippet: "Invoice #1042 is available to view.",
+				timeLabel: "8:15",
+				isRead: true,
+				category: "transactional",
+			},
+		],
+	},
+	{
+		id: "earlier",
+		label: "Earlier",
+		threads: [
+			{
+				id: "t3",
+				accountId: "a1",
+				fromName: "Weekly Digest",
+				fromEmail: "news@digest.com",
+				subject: "This week in tech",
+				snippet: "The top stories you might have missed.",
+				timeLabel: "Mon",
+				category: "newsletter",
+				messageCount: 3,
+			},
+		],
+	},
+];
+
+const meta: Meta<typeof MessageListPane> = {
+	title: "Screens/Kit/MessageListPane",
+	component: MessageListPane,
+	parameters: { layout: "centered" },
+	args: {
+		listTitle: "Inbox",
+		listMeta: "3 conversations",
+		sections,
+		onSelectThread: () => undefined,
+		onSelectBriefCategory: () => undefined,
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof MessageListPane>;
+
+const desktopFrame: Decorator = (Story) => (
+	<div className="h-screen w-96 overflow-hidden border border-line">
+		<Story />
+	</div>
+);
+
+const narrowFrame: Decorator = (Story) => (
+	<div
+		className="overflow-hidden border border-line"
+		style={{ width: 390, height: 844 }}
+	>
+		<Story />
+	</div>
+);
+
+export const DesktopList: Story = {
+	args: { isDesktop: true, flatList: true },
+	decorators: [desktopFrame],
+};
+
+export const NarrowTouchList: Story = {
+	args: { isDesktop: false, flatList: true },
+	decorators: [narrowFrame],
+};
+
+export const Brief: Story = {
+	args: { isDesktop: true, briefFilters: true, sections },
+	decorators: [desktopFrame],
+};
+
+/**
+ * Inbox behind its filter: the MailHeader top row, then the FilterSheet bar
+ * whose caret opens the inbox preset — categories + Unread/Flagged/Has
+ * attachment. No accounts group: an inbox is already scoped to one account.
+ */
+function InboxScreen({
+	initialExpanded = false,
+}: {
+	initialExpanded?: boolean;
+}) {
+	const preset = inboxFilterConfig();
+	const [searchValue, setSearchValue] = useState("");
+	const [searchOpen, setSearchOpen] = useState(false);
+	const [expanded, setExpanded] = useState(initialExpanded);
+	const [category, setCategory] = useState("all");
+	const [activeFilters, setActiveFilters] = useState<Set<string>>(new Set());
+	const rows = sections.flatMap((s) => s.threads);
+
+	return (
+		<div className="flex h-full flex-col">
+			<MailHeader
+				title="Inbox"
+				unreadCount={3}
+				isDesktop={false}
+				onMenuClick={() => undefined}
+				searchValue={searchValue}
+				onSearchChange={setSearchValue}
+				searchOpen={searchOpen}
+				onSearchOpenChange={setSearchOpen}
+			/>
+			<div className="min-h-0 flex-1">
+				<FilterSheet
+					categories={preset.categories}
+					filters={preset.filters}
+					sources={preset.sources}
+					selectedCategory={category}
+					activeFilters={activeFilters}
+					expanded={expanded}
+					onExpandedChange={setExpanded}
+					onSelectCategory={setCategory}
+					onToggleFilter={(id) =>
+						setActiveFilters((prev) => {
+							const next = new Set(prev);
+							if (next.has(id)) next.delete(id);
+							else next.add(id);
+							return next;
+						})
+					}
+					onClear={() => {
+						setCategory("all");
+						setActiveFilters(new Set());
+					}}
+				>
+					<ul className="divide-y divide-line">
+						{rows.map((thread) => (
+							<li key={thread.id} className="px-row-inset py-2.5">
+								<div className="text-sm font-medium text-fg">
+									{thread.fromName}
+								</div>
+								<div className="truncate text-xs text-fg-muted">
+									{thread.subject}
+								</div>
+							</li>
+						))}
+					</ul>
+				</FilterSheet>
+			</div>
+		</div>
+	);
+}
+
+/** Inbox filter collapsed: header + the FilterSheet bar over the inbox list. */
+export const InboxWithFilter: Story = {
+	render: () => <InboxScreen />,
+	decorators: [narrowFrame],
+};
+
+/** Inbox filter expanded: categories + Unread/Flagged/Has attachment. */
+export const InboxWithFilterExpanded: Story = {
+	render: () => <InboxScreen initialExpanded />,
+	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. */
+export const CustomListBody: Story = {
+	args: {
+		isDesktop: true,
+		flatList: true,
+		listBody: (
+			<div className="flex-1 overflow-y-auto divide-y divide-line">
+				{sections.flatMap((s) =>
+					s.threads.map((t) => (
+						<a
+							key={t.id}
+							href={`?selectedMessageId=${t.id}`}
+							className="flex items-center gap-3 px-4 py-3 hover:bg-surface-sunken"
+						>
+							<span className="font-medium text-sm">{t.fromName}</span>
+							<span className="text-sm text-fg-muted truncate">
+								{t.subject}
+							</span>
+						</a>
+					)),
+				)}
+			</div>
+		),
+	},
+	decorators: [desktopFrame],
+};
+
+/** External `selectionBar` slot — the pane delegates the header to the caller
+ *  when a selection is active. */
+export const ExternalSelectionBar: Story = {
+	args: {
+		isDesktop: true,
+		flatList: true,
+		selectionBar: (
+			<SelectionTopBar
+				count={2}
+				onCancel={() => undefined}
+				onMarkRead={() => undefined}
+				onDelete={() => undefined}
+			/>
+		),
+	},
+	decorators: [desktopFrame],
+};
+
+/** Fail-loud error state — the specific failure detail is surfaced under the
+ *  headline (not a bare "something went wrong"), with a way back (Retry) and a
+ *  place for the failure to go (Report a problem). */
+export const ErrorState: Story = {
+	args: {
+		isDesktop: true,
+		flatList: true,
+		listState: "error",
+		errorMessage: "Request timed out while loading this mailbox.",
+		onRetry: () => undefined,
+		onReportError: () => undefined,
+	},
+	decorators: [desktopFrame],
+};

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

@@ -0,0 +1,248 @@
+import { Menu } from "lucide-react";
+import type { ReactNode } from "react";
+import { useState } from "react";
+import type { AppShellProps, TouchSeed } from "./app-shell-types.js";
+import { BriefSections } from "./brief-sections.js";
+import { Button } from "./button.js";
+import { KeyboardHintBar } from "./keyboard-hint-bar.js";
+import {
+	MessageListEmpty,
+	MessageListError,
+	MessageListLoading,
+} from "./message-list-state.js";
+import { ComfortableRow, CompactRow } from "./message-row.js";
+import { SelectionTopBar } from "./selection-top-bar.js";
+import type { SwipePeek } from "./swipeable-row.js";
+import { TouchListBody } from "./touch-list.js";
+
+/* ------------------------------------------------------------------ */
+/* Pane 2: message list (sectioned, dense, density toggle)            */
+/* ------------------------------------------------------------------ */
+
+export function MessageListPane({
+	listTitle,
+	listMeta,
+	sections,
+	briefFilters,
+	flatList,
+	listState = "ready",
+	searchQuery,
+	errorMessage,
+	onRetry,
+	onReportError,
+	briefCategory,
+	selectedThreadId,
+	density = "comfortable",
+	onSelectThread,
+	onSelectBriefCategory,
+	onOpenNav,
+	isDesktop,
+	initialTouchState,
+	selectionBar,
+	listBody,
+	hideHeader = false,
+}: Pick<
+	AppShellProps,
+	| "listTitle"
+	| "listMeta"
+	| "sections"
+	| "briefFilters"
+	| "flatList"
+	| "listState"
+	| "searchQuery"
+	| "errorMessage"
+	| "onRetry"
+	| "onReportError"
+	| "briefCategory"
+	| "selectedThreadId"
+	| "density"
+	| "onSelectThread"
+	| "onSelectBriefCategory"
+> & {
+	/** When set, the list header shows a folders/menu button that opens the nav
+	 *  slide-over (list-only widths, where the nav is not a persistent pane). */
+	onOpenNav?: () => void;
+	/** Container-derived ≥1024; below it the touch triage chrome takes over. */
+	isDesktop: boolean;
+	initialTouchState?: TouchSeed;
+	/**
+	 * Replaces the pane header when a selection is active. The caller controls
+	 * the selection state and toolbar actions (mark-read, move, delete, cancel).
+	 * When omitted the pane's built-in touch-triage selection bar is used.
+	 */
+	selectionBar?: ReactNode;
+	/**
+	 * Overrides the row-rendering section of the non-brief list — the whole
+	 * scrollable body including virtualization, swipe-triage and any load-more
+	 * indicator. Wins on every width (desktop and touch): the consumer owns the
+	 * rows, so they stay real `<a href>` anchors and keep their own gestures
+	 * instead of the kit substituting the mock `TouchListBody`. Brief paths are
+	 * unaffected. When set, `sections` / `selectedThreadId` / `onSelectThread`
+	 * are still used by the pane chrome; the rows themselves come from this slot.
+	 */
+	listBody?: ReactNode;
+	/**
+	 * Suppress the built-in title header. The consumer owns the header (e.g. the
+	 * shared `MailHeader` rendered above the pane). The selection bar still
+	 * replaces the (now absent) header while a selection is active.
+	 */
+	hideHeader?: boolean;
+}) {
+	const Row = density === "compact" ? CompactRow : ComfortableRow;
+
+	const touchTriage = !isDesktop && !briefFilters && listState === "ready";
+	const seededRows = sections.flatMap((section) => section.threads);
+	const [selectionMode, setSelectionMode] = useState(
+		initialTouchState === "selection",
+	);
+	const [checkedIds, setCheckedIds] = useState<ReadonlySet<string>>(() =>
+		initialTouchState === "selection"
+			? new Set(seededRows.slice(0, 2).map((t) => t.id))
+			: new Set(),
+	);
+	const [refreshing, setRefreshing] = useState(false);
+	const initialPeek: SwipePeek | undefined =
+		initialTouchState === "peek-trailing"
+			? "trailing"
+			: initialTouchState === "peek-leading"
+				? "leading"
+				: undefined;
+
+	const toggleCheck = (id: string) => {
+		setCheckedIds((prev) => {
+			const next = new Set(prev);
+			if (next.has(id)) next.delete(id);
+			else next.add(id);
+			if (next.size === 0) setSelectionMode(false);
+			return next;
+		});
+	};
+	const enterSelection = (id: string) => {
+		setSelectionMode(true);
+		setCheckedIds(new Set([id]));
+	};
+	const cancelSelection = () => {
+		setSelectionMode(false);
+		setCheckedIds(new Set());
+	};
+	const refresh = () => {
+		setRefreshing(true);
+		setTimeout(() => setRefreshing(false), 1400);
+	};
+
+	// When the caller supplies a selectionBar slot, it owns selection state.
+	// Fall back to the built-in touch-triage bar only when no external bar is given.
+	const inBuiltinSelection =
+		!selectionBar && touchTriage && selectionMode && checkedIds.size > 0;
+
+	return (
+		<section className="flex h-full w-full flex-col bg-surface">
+			{selectionBar ??
+				(inBuiltinSelection ? (
+					<SelectionTopBar
+						count={checkedIds.size}
+						onCancel={cancelSelection}
+						onMarkRead={cancelSelection}
+						onDelete={cancelSelection}
+					/>
+				) : hideHeader ? null : (
+					<header className="flex h-pane-header shrink-0 items-center gap-2 border-b border-line px-row-inset">
+						{onOpenNav && (
+							<Button
+								variant="ghost"
+								size="sm"
+								icon={<Menu className="size-4" />}
+								onClick={onOpenNav}
+								aria-label="Open folders"
+								className="-ml-1 shrink-0"
+							/>
+						)}
+						<h1 className="min-w-0 flex-1 truncate text-sm font-semibold text-fg">
+							{listTitle}
+						</h1>
+						{listMeta && (
+							<span className="shrink-0 text-2xs text-fg-subtle">
+								{listMeta}
+							</span>
+						)}
+					</header>
+				))}
+
+			{/* List body. Non-ready states replace the rows entirely (the live
+			    MessageList does the same): skeleton on cold load, empty on a clean
+			    mailbox / search, fail-hard error with a way back + report. */}
+			{listState === "loading" ? (
+				<div className="flex-1 overflow-y-auto">
+					<MessageListLoading />
+				</div>
+			) : listState === "empty" ? (
+				<MessageListEmpty searchQuery={searchQuery} />
+			) : listState === "error" ? (
+				<MessageListError
+					message={errorMessage}
+					onRetry={onRetry}
+					onReport={onReportError}
+				/>
+			) : briefFilters ? (
+				<BriefSections
+					sections={sections}
+					briefCategory={briefCategory}
+					selectedThreadId={selectedThreadId}
+					Row={Row}
+					onSelectThread={onSelectThread}
+					onSelectBriefCategory={onSelectBriefCategory}
+				/>
+			) : listBody != null ? (
+				/* Consumer-provided body wins on every width — it owns the rows
+				   (real <a href> anchors, virtualization, infinite scroll) and its
+				   own swipe-triage. The built-in TouchListBody below is only the
+				   mock fallback for callers that don't supply a body. */
+				listBody
+			) : touchTriage ? (
+				<TouchListBody
+					sections={sections}
+					selectedThreadId={selectedThreadId}
+					selectionMode={selectionMode}
+					checkedIds={checkedIds}
+					initialPeek={initialPeek}
+					onToggleCheck={toggleCheck}
+					onEnterSelection={enterSelection}
+					onOpenThread={(id) => onSelectThread?.(id)}
+					onRefresh={refresh}
+					refreshing={refreshing}
+				/>
+			) : (
+				<div className="flex-1 overflow-y-auto">
+					{sections.map((section) => (
+						<div key={section.id}>
+							{/* The plain flat mailbox suppresses section labels — it is one
+							    continuous list, like the live $mailboxId MessageList. */}
+							{!flatList && section.label && (
+								<div className="sticky top-0 flex h-section-row items-center justify-between border-b border-line bg-surface-sunken px-row-inset">
+									<span className="text-2xs font-semibold uppercase tracking-wider text-fg-subtle">
+										{section.label}
+									</span>
+									<span className="text-2xs text-fg-subtle tabular-nums">
+										{section.threads.length}
+									</span>
+								</div>
+							)}
+							<div className="divide-y divide-line">
+								{section.threads.map((thread) => (
+									<Row
+										key={thread.id}
+										thread={thread}
+										active={thread.id === selectedThreadId}
+										onClick={() => onSelectThread?.(thread.id)}
+									/>
+								))}
+							</div>
+						</div>
+					))}
+				</div>
+			)}
+
+			{isDesktop && <KeyboardHintBar />}
+		</section>
+	);
+}

package/src/components/message-list-state.render.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	MessageListEmpty,
+	MessageListError,
+	MessageListLoading,
+} from "./message-list-state.js";
+
+describe("MessageListLoading", () => {
+	const html = renderToString(createElement(MessageListLoading));
+
+	it("renders eight skeleton rows", () => {
+		const rows = html.match(/animate-pulse/g) ?? [];
+		assert.equal(rows.length, 8, "eight pulse rows, like the live skeleton");
+	});
+
+	it("marks the region busy for assistive tech", () => {
+		assert.match(html, /aria-busy="true"/);
+	});
+});
+
+describe("MessageListEmpty", () => {
+	it("uses the plain mailbox copy with no query", () => {
+		const html = renderToString(createElement(MessageListEmpty, {}));
+		assert.match(html, /No messages in this mailbox/);
+	});
+
+	it("switches to the search copy when a query is active", () => {
+		const html = renderToString(
+			createElement(MessageListEmpty, { searchQuery: "invoice" }),
+		);
+		assert.match(html, /No messages match your search/);
+	});
+
+	it("treats a whitespace-only query as no search", () => {
+		const html = renderToString(
+			createElement(MessageListEmpty, { searchQuery: "   " }),
+		);
+		assert.match(html, /No messages in this mailbox/);
+	});
+});
+
+describe("MessageListError", () => {
+	it("fails hard: alert role, plain failure line, and the detail message", () => {
+		const html = renderToString(
+			createElement(MessageListError, { message: "Network unreachable" }),
+		);
+		assert.match(html, /role="alert"/, "blocking alert, never a toast");
+		assert.match(html, /Couldn't load messages/, "plain failure line");
+		assert.match(html, /Network unreachable/);
+	});
+
+	it("offers a way back and a report path when handlers are given", () => {
+		const html = renderToString(
+			createElement(MessageListError, {
+				onRetry: () => {},
+				onReport: () => {},
+			}),
+		);
+		assert.match(html, /Retry/);
+		assert.match(html, /Report a problem/);
+	});
+
+	it("never renders a disabled control", () => {
+		const html = renderToString(
+			createElement(MessageListError, { onRetry: () => {} }),
+		);
+		assert.doesNotMatch(html, /\sdisabled[\s=>]/);
+	});
+});

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

@@ -0,0 +1,97 @@
+import { AlertCircle } from "lucide-react";
+import { Button } from "./button.js";
+
+/** Non-ready states the flat mailbox list can be in. "ready" renders rows. */
+export type ListState = "ready" | "loading" | "empty" | "error";
+
+/**
+ * Skeleton mirror of the live web-client MessageList LoadingSkeleton: eight
+ * pulse rows shaped like a comfortable message row (sender / time, subject,
+ * snippet). Kept visually identical so the cold-load mock matches production.
+ */
+export function MessageListLoading() {
+	return (
+		// biome-ignore lint/a11y/useSemanticElements: <div> with role="status" preserves block layout; <output> is inline
+		<div
+			className="space-y-0"
+			role="status"
+			aria-busy="true"
+			aria-label="Loading messages"
+		>
+			{Array.from({ length: 8 }).map((_, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: list is static, no stable id
+				<div key={i} className="animate-pulse border-b border-line px-3 py-2">
+					<div className="mb-2 flex items-center justify-between">
+						<div className="h-4 w-32 rounded bg-surface-sunken" />
+						<div className="h-3 w-16 rounded bg-surface-sunken" />
+					</div>
+					<div className="mb-2 h-4 w-48 rounded bg-surface-sunken" />
+					<div className="h-3 w-full rounded bg-surface-sunken" />
+				</div>
+			))}
+		</div>
+	);
+}
+
+/**
+ * Empty mailbox / empty-search state. Copy mirrors the live MessageList
+ * EmptyState: a plain "No messages…" line, switching to the search variant
+ * when a query is active.
+ */
+export function MessageListEmpty({ searchQuery }: { searchQuery?: string }) {
+	const isSearching = Boolean(searchQuery?.trim());
+	return (
+		<div className="flex h-full flex-1 items-center justify-center">
+			<div className="flex flex-col items-center justify-center p-8 text-center">
+				<p className="text-fg-muted">
+					{isSearching
+						? "No messages match your search"
+						: "No messages in this mailbox"}
+				</p>
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Fail-hard list error (ux.md): a centered, blocking message that stops the
+ * list — never a toast, never a control left looking healthy. States plainly
+ * what failed, surfaces the underlying message, and offers a way back (Retry)
+ * plus a way for the failure to go somewhere (Report).
+ */
+export function MessageListError({
+	message = "Something went wrong loading this mailbox.",
+	onRetry,
+	onReport,
+}: {
+	message?: string;
+	onRetry?: () => void;
+	onReport?: () => void;
+}) {
+	return (
+		<div className="flex h-full flex-1 items-center justify-center p-4">
+			<div
+				role="alert"
+				className="flex max-w-sm flex-col items-center justify-center gap-3 text-center"
+			>
+				<AlertCircle className="size-8 text-danger" aria-hidden="true" />
+				<div>
+					<p className="font-medium text-danger">Couldn't load messages</p>
+					<p className="mt-1 break-words text-sm text-fg-muted">{message}</p>
+				</div>
+				<div className="flex items-center gap-2">
+					{onRetry && (
+						<Button variant="secondary" size="sm" onClick={onRetry}>
+							Retry
+						</Button>
+					)}
+					{onReport && (
+						<Button variant="ghost" size="sm" onClick={onReport}>
+							Report a problem
+						</Button>
+					)}
+				</div>
+			</div>
+		</div>
+	);
+}