@remit/ui 0.0.50 → 0.0.52

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

@@ -9,6 +9,7 @@ import { KeyboardHintBar } from "./keyboard-hint-bar.js";
 import {
 	MessageListEmpty,
 	MessageListError,
+	type MessageListFilter,
 	MessageListLoading,
 } from "./message-list-state.js";
 import { ComfortableRow, CompactRow } from "./message-row.js";
@@ -28,6 +29,8 @@ export function MessageListPane({
 	flatList,
 	listState = "ready",
 	searchQuery,
+	listFilter,
+	listScopeLabel,
 	errorMessage,
 	onRetry,
 	onReportError,
@@ -61,6 +64,15 @@ export function MessageListPane({
 	| "onSelectThread"
 	| "onSelectBriefCategory"
 > & {
+	/**
+	 * The active category filter, when the caller has one. Without it the empty
+	 * state cannot know it is filtered, and a narrowed list renders the plain
+	 * "No messages in this mailbox" — D19's stated failure case. Absent means
+	 * unfiltered, so a surface that filters must pass this.
+	 */
+	listFilter?: MessageListFilter;
+	/** 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
 	 *  slide-over (list-only widths, where the nav is not a persistent pane). */
 	onOpenNav?: () => void;
@@ -190,7 +202,11 @@ export function MessageListPane({
 					<MessageListLoading />
 				</div>
 			) : listState === "empty" ? (
-				<MessageListEmpty searchQuery={searchQuery} />
+				<MessageListEmpty
+					filter={listFilter}
+					scopeLabel={listScopeLabel}
+					searchQuery={searchQuery}
+				/>
 			) : listState === "error" ? (
 				<MessageListError
 					message={errorMessage}

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

@@ -4,9 +4,26 @@ import { createElement } from "react";
 import { renderToString } from "react-dom/server";
 import {
 	MessageListEmpty,
+	type MessageListEmptyProps,
 	MessageListError,
+	type MessageListFilter,
 	MessageListLoading,
+	MessageListLoadingMore,
 } from "./message-list-state.js";
+import { EmptyStateComparison } from "./message-list-state.stories.js";
+
+const COMPLETENESS = "Every message in this folder was checked.";
+const BOUNDED = "Only the messages loaded so far were checked.";
+
+function empty(props: MessageListEmptyProps = {}): string {
+	return renderToString(createElement(MessageListEmpty, props));
+}
+
+const personal: MessageListFilter = {
+	label: "Personal",
+	reach: "whole-folder",
+	onClear: () => undefined,
+};
 
 describe("MessageListLoading", () => {
 	const html = renderToString(createElement(MessageListLoading));
@@ -23,22 +40,158 @@ describe("MessageListLoading", () => {
 
 describe("MessageListEmpty", () => {
 	it("uses the plain mailbox copy with no query", () => {
-		const html = renderToString(createElement(MessageListEmpty, {}));
-		assert.match(html, /No messages in this mailbox/);
+		assert.match(empty(), /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(
+			empty({ searchQuery: "invoice" }),
+			/No messages match your search/,
 		);
-		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(empty({ searchQuery: "   " }), /No messages in this mailbox/);
+	});
+
+	it("names a collection that is not a mailbox instead of calling it one", () => {
+		const html = empty({ scopeLabel: "Starred" });
+		assert.match(html, /No messages in Starred/);
+		assert.doesNotMatch(html, /this mailbox/);
+	});
+
+	it("claims no completeness when nothing was filtered", () => {
+		assert.doesNotMatch(empty(), new RegExp(COMPLETENESS));
+		assert.doesNotMatch(
+			empty({ searchQuery: "invoice" }),
+			new RegExp(COMPLETENESS),
+		);
+	});
+});
+
+describe("MessageListEmpty under a filter", () => {
+	it("names the filter and the folder, and says the folder was fully read", () => {
+		const html = empty({ filter: personal, scopeLabel: "Inbox" });
+		assert.match(html, /No Personal mail in Inbox/);
+		assert.match(html, new RegExp(COMPLETENESS));
+	});
+
+	it("keeps the completeness sentence without a scope label", () => {
+		const html = empty({ filter: personal });
+		assert.match(html, /No Personal mail/);
+		assert.match(html, new RegExp(COMPLETENESS));
+	});
+
+	it("carries a completeness sentence in every filtered variant", () => {
+		const variants: MessageListEmptyProps[] = [
+			{ filter: personal },
+			{ filter: personal, scopeLabel: "Inbox" },
+			{ filter: personal, searchQuery: "invoice" },
+			{ filter: personal, scopeLabel: "Inbox", searchQuery: "invoice" },
+			{ filter: { ...personal, label: "Unclassified" } },
+			{ filter: { ...personal, reach: "loaded-pages" } },
+			{ filter: { ...personal, reach: "loaded-pages" }, scopeLabel: "Inbox" },
+		];
+		for (const props of variants) {
+			assert.match(empty(props), new RegExp(`${COMPLETENESS}|${BOUNDED}`));
+		}
+	});
+
+	it("claims the whole folder only when the filter reached it", () => {
+		const bounded = empty({
+			filter: { ...personal, reach: "loaded-pages" },
+			scopeLabel: "Inbox",
+		});
+		assert.match(bounded, new RegExp(BOUNDED));
+		assert.doesNotMatch(
+			bounded,
+			new RegExp(COMPLETENESS),
+			"a bounded read must not claim the folder was fully checked",
 		);
+	});
+
+	it("renders the two reaches distinguishably", () => {
+		const whole = empty({ filter: personal, scopeLabel: "Inbox" });
+		const bounded = empty({
+			filter: { ...personal, reach: "loaded-pages" },
+			scopeLabel: "Inbox",
+		});
+		assert.notEqual(whole, bounded);
+		assert.doesNotMatch(whole, new RegExp(BOUNDED));
+	});
+
+	it("leads with the query when searching inside a filter", () => {
+		const html = empty({
+			filter: personal,
+			scopeLabel: "Inbox",
+			searchQuery: "invoice",
+		});
+		assert.match(html, /No results for “invoice” in Personal/);
+		assert.match(html, new RegExp(COMPLETENESS));
+	});
+
+	it("offers the way out of the filter", () => {
+		assert.match(empty({ filter: personal }), /Clear filter/);
+	});
+
+	it("renders distinguishably from an unfiltered empty mailbox (#315)", () => {
+		const unfiltered = empty();
+		const filtered = empty({ filter: personal, scopeLabel: "Inbox" });
+		assert.notEqual(unfiltered, filtered);
+		assert.doesNotMatch(filtered, /No messages in this mailbox/);
+		assert.doesNotMatch(unfiltered, /Clear filter/);
+	});
+
+	it("renders distinguishably from the skeleton a restarted page shows", () => {
+		const filtered = empty({ filter: personal, scopeLabel: "Inbox" });
+		const loading = renderToString(createElement(MessageListLoading));
+		assert.notEqual(filtered, loading);
+		assert.doesNotMatch(filtered, /animate-pulse/);
+		assert.doesNotMatch(loading, new RegExp(COMPLETENESS));
+	});
+
+	it("renders unclassified as itself, never as personal (#45)", () => {
+		const unclassified = empty({
+			filter: { ...personal, label: "Unclassified" },
+			scopeLabel: "Inbox",
+		});
+		assert.match(unclassified, /No Unclassified mail in Inbox/);
+		assert.doesNotMatch(unclassified, /Personal/);
+	});
+});
+
+describe("the side-by-side comparison story", () => {
+	const html = renderToString(createElement(EmptyStateComparison));
+
+	it("renders both empty states, not one", () => {
 		assert.match(html, /No messages in this mailbox/);
+		assert.match(html, /No Personal mail in Inbox/);
+		assert.match(html, new RegExp(COMPLETENESS));
+	});
+
+	it("gives neither panel a fixed width, so a frame cannot clip one away", () => {
+		assert.doesNotMatch(html, /\bw-9\d\b/);
+		assert.equal((html.match(/flex-1/g) ?? []).length >= 2, true);
+	});
+});
+
+describe("MessageListLoadingMore", () => {
+	const html = renderToString(createElement(MessageListLoadingMore));
+
+	it("says another page is coming in words, not only a spinner", () => {
+		assert.match(html, /Loading more/);
+	});
+
+	it("announces itself to assistive tech", () => {
+		assert.match(html, /role="status"/);
+		assert.match(html, /aria-live="polite"/);
+	});
+
+	it("renders distinguishably from a filtered empty list", () => {
+		const filtered = empty({ filter: personal, scopeLabel: "Inbox" });
+		assert.notEqual(html, filtered);
+		assert.doesNotMatch(html, new RegExp(COMPLETENESS));
+		assert.doesNotMatch(filtered, /Loading more/);
 	});
 });
 
@@ -69,4 +222,12 @@ describe("MessageListError", () => {
 		);
 		assert.doesNotMatch(html, /\sdisabled[\s=>]/);
 	});
+
+	it("reads as a failure, never as an empty result", () => {
+		const html = renderToString(
+			createElement(MessageListError, { message: "Network unreachable" }),
+		);
+		assert.doesNotMatch(html, new RegExp(COMPLETENESS));
+		assert.doesNotMatch(html, /No messages/);
+	});
 });

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

@@ -0,0 +1,328 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react";
+import type { ReactNode } from "react";
+import { inboxFilterConfig, UNCLASSIFIED_CATEGORY } from "../filter-presets.js";
+import type { ThreadRowData } from "./app-shell-types.js";
+import { FilterSheet } from "./filter-sheet.js";
+import {
+	MessageListEmpty,
+	MessageListError,
+	type MessageListFilter,
+	MessageListLoading,
+	MessageListLoadingMore,
+} from "./message-list-state.js";
+import { ComfortableRow } from "./message-row.js";
+
+const SENDERS = [
+	"Alex Rivera",
+	"Priya Raman",
+	"Tom Okafor",
+	"Lena Fischer",
+] as const;
+
+function makeRow(i: number): ThreadRowData {
+	const fromName = SENDERS[i % SENDERS.length] ?? SENDERS[0];
+	return {
+		id: `t${i}`,
+		accountId: "a1",
+		fromName,
+		fromEmail: `${fromName.split(" ")[0]?.toLowerCase()}@example.com`,
+		subject: `Q3 planning notes ${i}`,
+		snippet: "Pushed the deck to the shared drive — have a look before Friday.",
+		timeLabel: `9:${String(i % 60).padStart(2, "0")}`,
+		isRead: i % 3 === 0,
+		category: "personal",
+	};
+}
+
+const longRow: ThreadRowData = {
+	...makeRow(1),
+	fromName: "Netherlands Enterprise Agency, Subsidy and Permits Desk",
+	subject:
+		"Re: Re: Fwd: Consolidated quarterly reconciliation of the shared drive migration, including the appendices nobody asked for",
+	snippet:
+		"Following up on the earlier thread about the reconciliation, the appendices have been consolidated into a single document that now runs to sixty-two pages, and we would appreciate your review before the end of the week.",
+};
+
+const personalFilter: MessageListFilter = {
+	label: "Personal",
+	reach: "whole-folder",
+	onClear: () => undefined,
+};
+
+/**
+ * One list pane at its real width. Applied per story rather than on the meta:
+ * Storybook composes decorators and a story cannot shed a meta one, so a story
+ * that needs a different frame has to be the only thing framing itself.
+ */
+const paneFrame: Decorator = (Story) => (
+	<div className="h-screen w-96 overflow-hidden border border-line">
+		<Story />
+	</div>
+);
+
+/** The list body a filtered mailbox scrolls: rows plus whatever sits below them. */
+function Rows({ count, rows }: { count?: number; rows?: ThreadRowData[] }) {
+	const threads =
+		rows ?? Array.from({ length: count ?? 6 }, (_, i) => makeRow(i + 1));
+	return (
+		<div className="divide-y divide-line">
+			{threads.map((thread) => (
+				<ComfortableRow key={thread.id} thread={thread} />
+			))}
+		</div>
+	);
+}
+
+/**
+ * The inbox behind its filter, collapsed. The filter's identity lives in this
+ * summary bar (design D19 S5), which is why a filtered list needs no header of
+ * its own to be told apart from the mailbox.
+ */
+function FilteredShell({
+	category = "personal",
+	children,
+}: {
+	category?: string;
+	children: ReactNode;
+}) {
+	const preset = inboxFilterConfig();
+	return (
+		<div className="flex h-full flex-col">
+			<FilterSheet
+				categories={[...preset.categories, UNCLASSIFIED_CATEGORY]}
+				filters={preset.filters}
+				selectedCategory={category}
+				activeFilters={new Set<string>()}
+				expanded={false}
+				onSelectCategory={() => undefined}
+				onToggleFilter={() => undefined}
+				onClear={() => undefined}
+				onExpandedChange={() => undefined}
+			>
+				<div className="min-h-0 flex-1 overflow-y-auto">{children}</div>
+			</FilterSheet>
+		</div>
+	);
+}
+
+/**
+ * The review this issue is for: an unfiltered empty mailbox next to a filtered
+ * empty one. If these two ever look the same, the fix is invisible.
+ *
+ * Both panels share the width instead of taking a fixed one, so neither can be
+ * pushed off the edge of whatever frames the story. Rendered by the story below
+ * and asserted by `message-list-state.render.test.ts`.
+ */
+export function EmptyStateComparison() {
+	return (
+		<div className="flex h-screen w-full gap-4 p-4">
+			<div className="min-w-0 flex-1 overflow-hidden border border-line">
+				<MessageListEmpty />
+			</div>
+			<div className="min-w-0 flex-1 overflow-hidden border border-line">
+				<FilteredShell>
+					<MessageListEmpty filter={personalFilter} scopeLabel="Inbox" />
+				</FilteredShell>
+			</div>
+		</div>
+	);
+}
+
+const meta: Meta<typeof MessageListEmpty> = {
+	title: "Screens/Kit/MessageListState",
+	component: MessageListEmpty,
+	parameters: { layout: "fullscreen" },
+	excludeStories: ["EmptyStateComparison"],
+};
+export default meta;
+
+type Story = StoryObj<typeof MessageListEmpty>;
+
+/** A bare empty state, and a filtered one, each in one pane. */
+const inPane = { decorators: [paneFrame] };
+
+/** A filtered list: the collapsed chip summary above the state under test. */
+const inFilteredPane = {
+	decorators: [paneFrame],
+	render: (args: Parameters<typeof MessageListEmpty>[0]) => (
+		<FilteredShell>
+			<MessageListEmpty {...args} />
+		</FilteredShell>
+	),
+};
+
+/**
+ * S1 — an empty mailbox with no filter. One plain line, no completeness claim:
+ * nothing was narrowed, so there is nothing to reassure the reader about.
+ */
+export const EmptyMailbox: Story = {
+	...inPane,
+	args: {},
+};
+
+/** S1 with a search query and no category filter — unchanged search copy. */
+export const EmptyMailboxSearching: Story = {
+	...inPane,
+	args: { searchQuery: "invoice" },
+};
+
+/**
+ * A collection that is not a mailbox names itself. Flagged spans accounts, so
+ * "this mailbox" was never true for it; its own states are #310.
+ */
+export const NamedCollectionEmpty: Story = {
+	...inPane,
+	args: { scopeLabel: "Starred" },
+};
+
+/**
+ * S2 — the state this slice exists for. The filter is active, the mailbox holds
+ * no matching mail, and the list says the whole folder was checked so an empty
+ * screen can no longer mean "we only looked at the newest page".
+ */
+export const FilteredEmpty: Story = {
+	...inFilteredPane,
+	args: { filter: personalFilter, scopeLabel: "Inbox" },
+};
+
+/** S2 with a search query on top of the filter — same completeness sentence. */
+export const FilteredEmptySearching: Story = {
+	...inFilteredPane,
+	args: {
+		filter: personalFilter,
+		scopeLabel: "Inbox",
+		searchQuery: "invoice",
+	},
+};
+
+/**
+ * A filter that could only be applied to the pages fetched so far claims only
+ * that. D19-S3's case: the off-row criteria page with a continuation token, so
+ * "every message was checked" would be a lie there.
+ */
+export const FilteredEmptyBoundedReach: Story = {
+	...inFilteredPane,
+	args: {
+		filter: { ...personalFilter, reach: "loaded-pages" },
+		scopeLabel: "Inbox",
+	},
+};
+
+/**
+ * The `Unclassified` chip's empty state. Unclassified mail is its own
+ * filterable value and never reads as personal (issue #45), so this state is
+ * reachable and distinct from `FilteredEmpty`.
+ */
+export const FilteredEmptyUnclassified: Story = {
+	decorators: [paneFrame],
+	args: {
+		filter: { ...personalFilter, label: "Unclassified" },
+		scopeLabel: "Inbox",
+	},
+	render: (args) => (
+		<FilteredShell category={UNCLASSIFIED_CATEGORY.id}>
+			<MessageListEmpty {...args} />
+		</FilteredShell>
+	),
+};
+
+/** Long filter and folder names — the copy wraps rather than overflowing. */
+export const FilteredEmptyLongLabels: Story = {
+	...inFilteredPane,
+	args: {
+		filter: { ...personalFilter, label: "Transactional" },
+		scopeLabel: "Archive/2024/Suppliers/Netherlands Enterprise Agency",
+	},
+};
+
+/** Both empties side by side, full width — no pane frame to clip either one. */
+export const EmptyVersusFilteredEmpty: Story = {
+	render: () => <EmptyStateComparison />,
+};
+
+/**
+ * S4 — the filter changed and pagination restarted. The skeleton, never the
+ * previous predicate's rows and never an empty state.
+ */
+export const FilterChangedRestarting: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<MessageListLoading />
+		</FilteredShell>
+	),
+};
+
+/** S5 — the filter is active and rows came back. */
+export const FilteredWithResults: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<Rows count={6} />
+		</FilteredShell>
+	),
+};
+
+/**
+ * S6 — rows already rendered, another page in flight. Words, not a bare
+ * spinner: "not fetched yet" must not read as "nothing there".
+ */
+export const FilteredFetchingMore: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<Rows count={12} />
+			<MessageListLoadingMore />
+		</FilteredShell>
+	),
+};
+
+/** A filter that matches most of a large mailbox — scrolling, no truncation. */
+export const FilteredManyResults: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<Rows count={60} />
+		</FilteredShell>
+	),
+};
+
+/** Long subjects, senders and snippets under an active filter. */
+export const FilteredLongContent: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<Rows
+				rows={[longRow, ...Array.from({ length: 4 }, (_, i) => makeRow(i + 2))]}
+			/>
+		</FilteredShell>
+	),
+};
+
+/** S7 — fail-hard error: the detail, a way back, and somewhere for it to go. */
+export const ErrorState: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<MessageListError
+				message="Request timed out while loading this mailbox."
+				onRetry={() => undefined}
+				onReport={() => undefined}
+			/>
+		</FilteredShell>
+	),
+};
+
+/** A long underlying failure message still wraps inside the frame. */
+export const ErrorStateLongMessage: Story = {
+	decorators: [paneFrame],
+	render: () => (
+		<FilteredShell>
+			<MessageListError
+				message="The IMAP server closed the connection while fetching message headers for this mailbox, after 30 seconds without a response to the SELECT command."
+				onRetry={() => undefined}
+				onReport={() => undefined}
+			/>
+		</FilteredShell>
+	),
+};