@remit/ui 0.0.51 → 0.0.52

package/package.json

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

package/src/components/filter-sheet.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
+import { UNCLASSIFIED_CATEGORY } from "../filter-presets.js";
 import {
 	FilterSheet,
 	type FilterSheetCategory,
@@ -10,6 +11,7 @@ import {
 const CATEGORIES: FilterSheetCategory[] = [
 	{ id: "all", label: "All", tone: "neutral" },
 	{ id: "personal", label: "Personal", tone: "positive" },
+	UNCLASSIFIED_CATEGORY,
 	{ id: "newsletters", label: "Newsletters", tone: "accent" },
 	{ id: "marketing", label: "Marketing", tone: "warning" },
 	{ id: "automated", label: "Automated", tone: "neutral" },
@@ -127,6 +129,20 @@ export const CollapsedWithActiveFilters: Story = {
 	),
 };
 
+/**
+ * Unclassified selected. Mail the classifier has not reached is a filterable
+ * value of its own and never folds into Personal (issue #45), so the chip and
+ * its collapsed summary carry their own label and tone.
+ */
+export const CollapsedWithUnclassified: Story = {
+	render: () => (
+		<ControlledShell
+			initialExpanded={false}
+			initialCategory={UNCLASSIFIED_CATEGORY.id}
+		/>
+	),
+};
+
 export const CollapsedEmpty: Story = {
 	render: () => <ControlledShell initialExpanded={false} />,
 };

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>
+	),
+};

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

@@ -1,4 +1,5 @@
-import { AlertCircle } from "lucide-react";
+import { AlertCircle, Loader2 } from "lucide-react";
+import type { ReactNode } from "react";
 import { Button } from "./button.js";
 
 /** Non-ready states the flat mailbox list can be in. "ready" renders rows. */
@@ -34,25 +35,148 @@ export function MessageListLoading() {
 }
 
 /**
- * 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.
+ * How much of the collection the filter was applied to.
+ *
+ * `whole-folder` is a SQL `where` over the mailbox — an empty result means the
+ * folder holds no matching mail. `loaded-pages` is a criterion evaluated over
+ * the rows fetched so far, which D19-S3 keeps alive for the off-row criteria
+ * (`senderTrust`, `dkimMismatch`) that page with a continuation token: an empty
+ * result there means nothing matched yet, not that nothing matches.
+ *
+ * A value rather than a `complete` flag, so the day a third reach exists the
+ * copy is a case to add and not a boolean to reinterpret.
  */
-export function MessageListEmpty({ searchQuery }: { searchQuery?: string }) {
-	const isSearching = Boolean(searchQuery?.trim());
+export type FilterReach = "whole-folder" | "loaded-pages";
+
+/**
+ * The active category filter, the way out of it, and how far it reached. All
+ * three together: the label cannot arrive without its escape, and the reach
+ * cannot be left to a default, because it decides which completeness sentence
+ * is true.
+ */
+export interface MessageListFilter {
+	/** Display label of the active category, e.g. "Personal". */
+	label: string;
+	reach: FilterReach;
+	onClear: () => void;
+}
+
+export interface MessageListEmptyProps {
+	/** Absent when no category filter is active. */
+	filter?: MessageListFilter;
+	/**
+	 * Name of the collection being listed, e.g. "Inbox". Absent for a plain
+	 * mailbox, which keeps the generic copy. Cross-account collections that are
+	 * not mailboxes (Flagged) name themselves here rather than being called one.
+	 */
+	scopeLabel?: string;
+	searchQuery?: string;
+}
+
+/**
+ * Empty list state. Unfiltered copy mirrors the live MessageList EmptyState: a
+ * plain "No messages…" line, switching to the search variant when a query is
+ * active.
+ *
+ * Under a filter it says how much was read (design D19). An empty list looks
+ * identical whether it is correct or broken, which is how #315's bug survived
+ * a mailbox holding thousands of matching messages. The sentence comes from the
+ * filter's own reach, so a filtered empty state always carries one and never
+ * claims more than the query did.
+ */
+export function MessageListEmpty({
+	filter,
+	scopeLabel,
+	searchQuery,
+}: MessageListEmptyProps) {
+	const query = searchQuery?.trim();
+
+	if (!filter) {
+		return (
+			<EmptyFrame>
+				<p className="text-fg-muted">{unfilteredCopy(query, scopeLabel)}</p>
+			</EmptyFrame>
+		);
+	}
+
+	return (
+		<EmptyFrame>
+			<p className="font-medium text-fg">
+				{filteredHeadline(filter.label, scopeLabel, query)}
+			</p>
+			<p className="mt-1 text-sm text-fg-muted">
+				{COMPLETENESS_COPY[filter.reach]}
+			</p>
+			<Button
+				variant="secondary"
+				size="sm"
+				className="mt-4"
+				onClick={filter.onClear}
+			>
+				Clear filter
+			</Button>
+		</EmptyFrame>
+	);
+}
+
+/**
+ * The one sentence a filtered empty list always carries. `loaded-pages` states
+ * what is true of a bounded read and nothing more; the wording it should settle
+ * on belongs with whoever moves the off-row criteria on-row (D7).
+ */
+const COMPLETENESS_COPY: Record<FilterReach, string> = {
+	"whole-folder": "Every message in this folder was checked.",
+	"loaded-pages": "Only the messages loaded so far were checked.",
+};
+
+function unfilteredCopy(
+	query: string | undefined,
+	scopeLabel: string | undefined,
+): string {
+	if (query) return "No messages match your search";
+	if (scopeLabel) return `No messages in ${scopeLabel}`;
+	return "No messages in this mailbox";
+}
+
+/** One string, not JSX, so the copy stays a single text node and reads whole. */
+function filteredHeadline(
+	filterLabel: string,
+	scopeLabel: string | undefined,
+	query: string | undefined,
+): string {
+	if (query) return `No results for “${query}” in ${filterLabel}`;
+	if (scopeLabel) return `No ${filterLabel} mail in ${scopeLabel}`;
+	return `No ${filterLabel} mail`;
+}
+
+function EmptyFrame({ children }: { children: ReactNode }) {
 	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 className="flex max-w-sm flex-col items-center justify-center p-8 text-center">
+				{children}
 			</div>
 		</div>
 	);
 }
 
+/**
+ * Another page in flight below rows already rendered. Says so in words: a bare
+ * spinner (`MessageList.tsx:1429-1433`) is one of the ways "not fetched yet"
+ * reads as "nothing there".
+ */
+export function MessageListLoadingMore() {
+	return (
+		<div
+			className="flex items-center justify-center gap-2 py-4 text-sm text-fg-muted"
+			role="status"
+			aria-live="polite"
+		>
+			<Loader2 className="size-4 animate-spin" aria-hidden="true" />
+			<span>Loading more&hellip;</span>
+		</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

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

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import { createElement } from "react";
 import { renderToString } from "react-dom/server";
-import type { ThreadRowData } from "./app-shell-types.js";
+import { categoryTone, type ThreadRowData } from "./app-shell-types.js";
 import { ComfortableRow, CompactRow } from "./message-row.js";
 
 const base: ThreadRowData = {
@@ -61,6 +61,48 @@ describe("ComfortableRow", () => {
 	});
 });
 
+describe("ComfortableRow category presentation", () => {
+	const render = (category: ThreadRowData["category"]): string =>
+		renderToString(
+			createElement(ComfortableRow, {
+				thread: { ...base, isRead: true, category },
+			}),
+		);
+
+	/** The category Badge's own class signature, so no other span matches. */
+	const badgeClass = (html: string): string | undefined =>
+		html.match(
+			/class="([^"]*rounded-full px-2 py-0\.5 text-2xs font-medium[^"]*)"/,
+		)?.[1];
+
+	it("renders no category badge for personal", () => {
+		assert.equal(badgeClass(render("personal")), undefined);
+	});
+
+	it("renders uncategorized as neither personal nor nothing (#45)", () => {
+		const uncategorized = render("uncategorized");
+		assert.notEqual(uncategorized, render("personal"));
+		assert.ok(
+			badgeClass(uncategorized),
+			"a message the classifier has not reached carries its own badge",
+		);
+		assert.match(uncategorized, /uncategorized|unclassified/i);
+	});
+
+	it("keeps the uncategorized badge off personal's tone (#45)", () => {
+		assert.notEqual(
+			categoryTone.uncategorized,
+			categoryTone.personal,
+			"the tone table must not give unclassified mail personal's colour",
+		);
+		assert.doesNotMatch(
+			badgeClass(render("uncategorized")) ?? "",
+			/accent/,
+			"the row badge must not render personal's accent tone",
+		);
+	});
+});
+
 describe("ComfortableRow selection slot", () => {
 	it("renders no checkbox without a selection (non-selectable mode)", () => {
 		const html = renderToString(

package/src/filter-presets.test.ts

@@ -5,6 +5,7 @@ import {
 	type FilterAccount,
 	flaggedFilterConfig,
 	inboxFilterConfig,
+	UNCLASSIFIED_CATEGORY,
 } from "./filter-presets.js";
 
 const accounts: FilterAccount[] = [
@@ -98,3 +99,27 @@ describe("flaggedFilterConfig", () => {
 		assert.equal(flaggedFilterConfig().sources, undefined);
 	});
 });
+
+describe("UNCLASSIFIED_CATEGORY", () => {
+	it("is held out of every shipped preset until the server filters it", () => {
+		for (const preset of [
+			briefFilterConfig(),
+			inboxFilterConfig(),
+			flaggedFilterConfig(),
+		]) {
+			assert.equal(
+				preset.categories.some((c) => c.id === UNCLASSIFIED_CATEGORY.id),
+				false,
+			);
+		}
+	});
+
+	it("carries its own label and tone, never personal's (#45)", () => {
+		const personal = briefFilterConfig().categories.find(
+			(c) => c.id === "personal",
+		);
+		assert.equal(UNCLASSIFIED_CATEGORY.label, "Unclassified");
+		assert.notEqual(UNCLASSIFIED_CATEGORY.label, personal?.label);
+		assert.notEqual(UNCLASSIFIED_CATEGORY.tone, personal?.tone);
+	});
+});

package/src/filter-presets.ts

@@ -27,10 +27,31 @@ export interface FilterPreset {
 	sources?: FilterSheetSource[];
 }
 
+/**
+ * The Unclassified chip D6 requires, built and storied but not offered yet.
+ *
+ * This module is a runtime dependency of three live surfaces that filter over
+ * the loaded window, so a chip in the list below is a chip a user can click
+ * today. Offering it before #306 makes the predicate a server-side `where`
+ * would add a fresh instance of the bug this epic exists to fix: a category
+ * whose mail sits below the newest page reads as a category with no mail.
+ *
+ * #306 splices this entry into `MESSAGE_CATEGORIES` after `Personal` — matching
+ * `briefCategories`' order — and deletes this constant.
+ */
+export const UNCLASSIFIED_CATEGORY: FilterSheetCategory = {
+	id: "uncategorized",
+	label: "Unclassified",
+	tone: "neutral",
+};
+
 /**
  * Content-type categories, mirroring the `MessageCategory` enum
  * (@remit/remit-imap) by value. The leading "all" clears the category. Per
  * message, not per mailbox — so they apply in the brief and an inbox alike.
+ *
+ * `uncategorized` is absent on purpose and is not folded into `personal`
+ * (issue #45) — see `UNCLASSIFIED_CATEGORY`.
  */
 const MESSAGE_CATEGORIES: FilterSheetCategory[] = [
 	{ id: "all", label: "All", tone: "neutral" },

package/src/index.ts

@@ -251,8 +251,11 @@ export { MessageListPane } from "./components/message-list-pane.js";
 export {
 	type ListState,
 	MessageListEmpty,
+	type MessageListEmptyProps,
 	MessageListError,
+	type MessageListFilter,
 	MessageListLoading,
+	MessageListLoadingMore,
 } from "./components/message-list-state.js";
 export {
 	type BriefRowComponent,
@@ -542,6 +545,7 @@ export {
 	type FilterPreset,
 	flaggedFilterConfig,
 	inboxFilterConfig,
+	UNCLASSIFIED_CATEGORY,
 } from "./filter-presets.js";
 export {
 	buildCidResolver,

package/src/stories-viewport-globals.test.ts

@@ -51,3 +51,27 @@ describe("story files use the viewport globals pattern (#68)", () => {
 		assert.deepEqual(offenders, []);
 	});
 });
+
+/**
+ * Storybook composes decorators story → component → global, so a story-level
+ * `decorators: []` adds nothing. It reads as "this story opts out of the meta's
+ * frame" and silently does the opposite, which clipped a story down to half its
+ * content. A story that needs a different frame carries the frame itself.
+ */
+describe("story files never claim to shed a meta decorator", () => {
+	const roots = [
+		here,
+		resolve(here, "../../workbench/src"),
+		resolve(here, "../../web-client/src"),
+	];
+
+	it("never uses an empty story-level decorators array", () => {
+		const offenders = roots
+			.flatMap((root) => storyFiles(root))
+			.filter((file) =>
+				/decorators:\s*\[\s*\]/.test(readFileSync(file, "utf8")),
+			)
+			.map((file) => relative(here, file));
+		assert.deepEqual(offenders, []);
+	});
+});