@remit/web-client 0.0.253 → 0.0.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.253",
+  "version": "0.0.254",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/FlaggedList.tsx

@@ -45,8 +45,8 @@ import {
 } from "@/lib/brief";
 import { buildBugReportContext, buildGitHubIssueUrl } from "@/lib/bug-report";
 import { flaggedCriteria } from "@/lib/flagged-criteria";
-import { categoryLabel } from "@/lib/inbox-filters";
 import { useListHeaderChrome } from "@/lib/list-header-chrome";
+import { listNarrowing } from "@/lib/list-narrowing";
 import { useMailContext } from "@/lib/mail-context";
 import { rowToSearchResult } from "@/lib/search-result";
 import { parseSearchTokens } from "@/lib/search-tokens";
@@ -126,7 +126,8 @@ export function FlaggedList({
 	onTriageContextChange,
 	onDeleteMessages,
 }: FlaggedListProps) {
-	const { searchQuery, resultFolderIndex } = useMailContext();
+	const { searchQuery, resultFolderIndex, onSearchClearQuery } =
+		useMailContext();
 	const tokenContext = useSearchTokenContext();
 	const isDesktop = useIsDesktop();
 	const wizard = useSelectionWizard();
@@ -150,10 +151,24 @@ export function FlaggedList({
 		setActiveFilters(new Set());
 	}, []);
 
+	// The empty state's way out has to clear everything its headline names, or
+	// it is a button that leaves the list exactly as narrowed as it found it.
+	const clearNarrowing = useCallback(() => {
+		clearFilters();
+		onSearchClearQuery();
+	}, [clearFilters, onSearchClearQuery]);
+
 	const { freeText: sq, tokens: queryTokens } = parseSearchTokens(
 		searchQuery.trim().toLowerCase(),
 		tokenContext,
 	);
+	// The same free text in the reader's own casing. The request's copy is folded
+	// to lowercase so equivalent searches share a cache entry; a sentence quoting
+	// the query back to the reader must not be.
+	const typedFreeText = parseSearchTokens(
+		searchQuery.trim(),
+		tokenContext,
+	).freeText;
 
 	// The chips and the tokens together, as query parameters: a category typed as
 	// `category:personal` narrows the request exactly as the chip does.
@@ -238,15 +253,19 @@ export function FlaggedList({
 	// the request. Every chip and every carried token is a column on the row, so
 	// the server answered over the whole collection; a residual token, or the
 	// snippet half of a free-text search, only ever saw the pages loaded so far.
-	const filterLabel = categoryLabel(selectedCategory);
-	const listFilter: MessageListFilter | undefined = filterLabel
-		? {
-				label: filterLabel,
-				reach:
-					residualTokens.length > 0 || sq ? "loaded-pages" : "whole-folder",
-				onClear: clearFilters,
-			}
-		: undefined;
+	//
+	// `is:starred` is dropped: this view is starred mail, so the token restates
+	// the collection rather than narrowing it.
+	const narrowingTokens = useMemo(
+		() => queryTokens.filter((token) => token.type !== "isStarred"),
+		[queryTokens],
+	);
+	const listFilter: MessageListFilter | undefined = listNarrowing({
+		chips: { category: selectedCategory, attributes: activeFilters },
+		tokens: narrowingTokens,
+		reach: residualTokens.length > 0 || sq ? "loaded-pages" : "whole-folder",
+		onClear: clearNarrowing,
+	});
 
 	const listState = isLoading
 		? "loading"
@@ -327,7 +346,9 @@ export function FlaggedList({
 					// Flagged spans accounts and folders, so it is a collection and
 					// never "this mailbox". It names itself.
 					listScopeLabel="Starred"
-					searchQuery={sq ? searchQuery : undefined}
+					// The typed tokens narrow the list too, but `listFilter` already
+					// names them, and a headline saying one narrowing twice reads as two.
+					searchQuery={typedFreeText || undefined}
 					errorMessage={isError ? formatErrorMessage(error) : undefined}
 					onRetry={() => refetch()}
 					onReportError={handleReportError}

package/src/components/mail/MailboxPane.tsx

@@ -100,7 +100,6 @@ import { useUpdateAddressFlags } from "@/hooks/useUpdateAddressFlags";
 import type { ConversationTarget } from "@/lib/conversation-target";
 import { dedupeThreadMessages } from "@/lib/dedupe-thread-messages";
 import {
-	categoryLabel,
 	filterReach,
 	hasInboxFilter,
 	type InboxFilterCriteria,
@@ -109,6 +108,7 @@ import {
 	sameInboxFilter,
 } from "@/lib/inbox-filters";
 import { junkDestination } from "@/lib/junk-destination";
+import { listNarrowing } from "@/lib/list-narrowing";
 import { useMailContext } from "@/lib/mail-context";
 import { useMailFreshness } from "@/lib/mail-freshness";
 import { isRescueCandidate } from "@/lib/rescue-candidates";
@@ -178,11 +178,17 @@ interface MailboxPaneContextValue {
 	onToggleFilterAttribute: (id: string) => void;
 	onClearFilters: () => void;
 	/**
-	 * The active category filter as the empty state renders it — its label, the
-	 * way out of it, and how much of the mailbox the request reached. Undefined
-	 * when no category is selected.
+	 * What narrows the list as the empty state renders it — the narrowing named,
+	 * the way out of it, and how much of the mailbox the request reached.
+	 * Undefined when nothing narrows the list.
 	 */
 	listFilter: MessageListFilter | undefined;
+	/**
+	 * The free text the empty state names. The typed tokens narrow the list too,
+	 * but `listFilter` already names them, and a headline saying the same
+	 * narrowing twice reads as two.
+	 */
+	listSearchText: string | undefined;
 	onToggleIntelligence: () => void;
 	/**
 	 * Where the mounted reading surface publishes the intelligence commands the
@@ -277,7 +283,8 @@ function MailboxPaneProvider({
 	const threadId = thread?.threadId;
 	const pointedAtMessageId = thread?.messageId;
 	const telemetry = useTelemetry();
-	const { accounts, searchQuery, onToggleIntelligence } = useMailContext();
+	const { accounts, searchQuery, onToggleIntelligence, onSearchClearQuery } =
+		useMailContext();
 	const tokenContext = useSearchTokenContext();
 
 	const normalizedSearchQuery = normalizeSearchQuery(searchQuery);
@@ -295,6 +302,13 @@ function MailboxPaneProvider({
 		normalizedSearchQuery,
 		tokenContext,
 	);
+	// The same free text in the reader's own casing. The request's copy is folded
+	// to lowercase so equivalent searches share a cache entry; a sentence quoting
+	// the query back to the reader must not be.
+	const typedFreeText = parseSearchTokens(
+		searchQuery.trim(),
+		tokenContext,
+	).freeText;
 
 	const [filterCategory, setFilterCategory] = useState("all");
 	const [filterAttributes, setFilterAttributes] = useState<ReadonlySet<string>>(
@@ -445,20 +459,25 @@ function MailboxPaneProvider({
 		setFilterAttributes(new Set());
 	}, []);
 
+	// The empty state's way out has to clear everything its headline names, or
+	// it is a button that leaves the list exactly as narrowed as it found it.
+	const onClearNarrowing = useCallback(() => {
+		onClearFilters();
+		onSearchClearQuery();
+	}, [onClearFilters, onSearchClearQuery]);
+
 	// The empty state has to say how much was read, and the reach comes off the
 	// request rather than the call site: the day a chip is answered over a window
 	// instead of the whole mailbox, the sentence changes with it.
-	const filterLabel = categoryLabel(filterCategory);
-	const listFilter: MessageListFilter | undefined = filterLabel
-		? {
-				label: filterLabel,
-				reach:
-					residualTokens.length > 0
-						? "loaded-pages"
-						: filterReach(searchThreadsQuery),
-				onClear: onClearFilters,
-			}
-		: undefined;
+	const listFilter: MessageListFilter | undefined = listNarrowing({
+		chips: filterCriteria,
+		tokens: searchTokens,
+		reach:
+			residualTokens.length > 0
+				? "loaded-pages"
+				: filterReach(searchThreadsQuery),
+		onClear: onClearNarrowing,
+	});
 
 	// The row this folder itself lists, preferred because a mutation patches it in
 	// place. A thread the loaded pages do not hold — a chip that paged it out, a
@@ -799,6 +818,7 @@ function MailboxPaneProvider({
 		onToggleFilterAttribute,
 		onClearFilters,
 		listFilter,
+		listSearchText: typedFreeText || undefined,
 		onToggleIntelligence,
 		intelligenceRef,
 		handleDeselectIfRemoved,
@@ -875,6 +895,7 @@ function MailboxList() {
 		onToggleFilterAttribute,
 		onClearFilters,
 		listFilter,
+		listSearchText,
 		searchPredicate,
 		resultCount,
 	} = useMailboxPane();
@@ -1011,6 +1032,7 @@ function MailboxList() {
 			accountId={mailboxAccountId}
 			listTitle={listTitle}
 			listFilter={listFilter}
+			listSearchText={listSearchText}
 			listScopeLabel={listTitle}
 			hideHeader
 			onTriageContextChange={onTriageContextChange}

package/src/components/mail/MessageList.tsx

@@ -142,12 +142,18 @@ interface MessageListProps {
 	 */
 	listMeta?: string;
 	/**
-	 * The active category filter, when the view has one. The empty state needs
-	 * it to say it is filtered and how much of the collection the request
-	 * reached; without it a narrowed list renders as an empty mailbox, which is
-	 * the shape #315's bug hid behind.
+	 * What narrows the list, when anything does. The empty state needs it to say
+	 * it is filtered and how much of the collection the request reached; without
+	 * it a narrowed list renders as an empty mailbox, which is the shape #315's
+	 * bug hid behind.
 	 */
 	listFilter?: MessageListFilter;
+	/**
+	 * The free text the empty state names, which is `searchQuery` with the typed
+	 * filter tokens taken out: `listFilter` already names those, and a headline
+	 * saying one narrowing twice reads as two.
+	 */
+	listSearchText?: string;
 	/** Name of the collection being listed, e.g. "Inbox", for the empty state. */
 	listScopeLabel?: string;
 	/**
@@ -233,6 +239,7 @@ export const MessageList = ({
 	listTitle,
 	listMeta,
 	listFilter,
+	listSearchText,
 	listScopeLabel,
 	onTriageContextChange,
 	commandsRef,
@@ -1301,7 +1308,7 @@ export const MessageList = ({
 				// The results panel is a body, not a list state: it stands in for the
 				// rows and must not fall behind a skeleton while the query re-keys.
 				listState={listHeaderChrome.searchResults ? "ready" : listState}
-				searchQuery={isSearching ? searchQuery : undefined}
+				searchQuery={listSearchText}
 				listFilter={listFilter}
 				listScopeLabel={listScopeLabel}
 				errorMessage={errorMessage}

package/src/components/mail/filtered-empty-state.render.test.ts

@@ -0,0 +1,240 @@
+/**
+ * A list narrowed by anything at all says so when it comes back empty (#1126).
+ *
+ * Both list panes built the empty state's filter from the category chip alone,
+ * and `MessageListEmpty` reads that object's presence as "a filter is active".
+ * So the Unread chip on its own — or `is:unread` typed in the field — fell
+ * through to the unfiltered copy: "No messages in Starred" over a collection
+ * holding thousands of starred messages, with no way out offered.
+ *
+ * Driven through the chips the reader actually presses, in the real panes, so
+ * the assertion is about what the screen says rather than what a helper returns.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import {
+	type AnyRouter,
+	createMemoryHistory,
+	createRootRoute,
+	createRoute,
+	createRouter,
+	Outlet,
+	RouterProvider,
+} from "@tanstack/react-router";
+import { type ComponentType, createElement, type ReactNode } from "react";
+import { ComposeProvider } from "@/components/compose/ComposeProvider";
+import { MailContext, type MailContextValue } from "@/lib/mail-context";
+import { MailFreshnessProvider } from "@/lib/mail-freshness";
+import { EMPTY_RESULT_FOLDER_INDEX } from "@/lib/result-folder";
+import { useOpenThreadPath } from "@/routing";
+import { createDomHarness, type DomHarness } from "@/test-support/dom";
+import { type HttpMock, mockFetch } from "@/test-support/http";
+import { FlaggedPane } from "./FlaggedPane";
+import { MailboxPane } from "./MailboxPane";
+
+const MAILBOX_ID = "11111111-1111-4111-8111-111111111111";
+const DESKTOP_WIDTH = 1440;
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+// The router reads `self` at construction; the shared jsdom globals stop at
+// `window`.
+(globalThis as { self?: typeof globalThis }).self ??= globalThis;
+
+interface PaneUnderTest {
+	name: string;
+	/** The list's own segment under `/mail`, which is its whole route. */
+	segment: string;
+	/** What the empty state calls the collection. */
+	scopeLabel: string;
+	List: ComponentType;
+	mount: (children: ReactNode) => ReactNode;
+}
+
+const panes: PaneUnderTest[] = [
+	{
+		name: "Starred",
+		segment: "flagged",
+		scopeLabel: "Starred",
+		List: FlaggedPane.List,
+		mount: (children) =>
+			createElement(FlaggedPane, {
+				thread: useOpenThreadPath(),
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children,
+			}),
+	},
+	{
+		name: "the mailbox",
+		segment: MAILBOX_ID,
+		scopeLabel: "Inbox",
+		List: MailboxPane.List,
+		mount: (children) =>
+			createElement(MailboxPane, {
+				mailboxId: MAILBOX_ID,
+				thread: useOpenThreadPath(),
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children,
+			}),
+	},
+];
+
+/** The layout context the panes read the search field out of. */
+const mailContext = (query: string): MailContextValue => ({
+	accounts: [],
+	mailboxNameIndex: new Map(),
+	accountNameIndex: new Map(),
+	resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
+	searchQuery: query,
+	searchInput: query,
+	searchViewKey: "list",
+	onSearchChange: () => undefined,
+	onSearchClear: () => undefined,
+	onSearchClearQuery: () => undefined,
+	intelligenceOpen: false,
+	onToggleIntelligence: () => undefined,
+	onRaiseIntelligence: () => undefined,
+});
+
+const testRouter = (pane: PaneUnderTest, query: string): AnyRouter => {
+	const rootRoute = createRootRoute({
+		component: () =>
+			createElement(MailFreshnessProvider, {
+				accountIds: [],
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test, and createElement's variadic children do not satisfy a required prop
+				children: createElement(
+					MailContext.Provider,
+					{ value: mailContext(query) },
+					createElement(ComposeProvider, null, createElement(Outlet)),
+				),
+			}),
+	});
+	const mailRoute = createRoute({
+		getParentRoute: () => rootRoute,
+		path: "/mail",
+		validateSearch: (search: Record<string, unknown>) => search,
+		component: Outlet,
+	});
+	const mailboxRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/$mailboxId",
+		component: () => pane.mount(createElement(pane.List)),
+	});
+	const flaggedRoute = createRoute({
+		getParentRoute: () => mailRoute,
+		path: "/flagged",
+		component: () => pane.mount(createElement(pane.List)),
+	});
+	const routeTree = rootRoute.addChildren([
+		mailRoute.addChildren([mailboxRoute, flaggedRoute]),
+	]);
+	return createRouter({
+		routeTree,
+		history: createMemoryHistory({
+			initialEntries: [`/mail/${pane.segment}`],
+		}),
+	}) as unknown as AnyRouter;
+};
+
+const mount = async (pane: PaneUnderTest, query = ""): Promise<DomHarness> => {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/config")) return { accounts: [] };
+		if (call.path.endsWith("/mailboxes")) {
+			return {
+				items: [{ mailboxId: MAILBOX_ID, name: "Inbox", fullPath: "INBOX" }],
+			};
+		}
+		return { items: [] };
+	});
+
+	const router = testRouter(pane, query);
+	await router.load();
+	const mounted = createDomHarness({ viewportWidth: DESKTOP_WIDTH });
+	harness = mounted;
+	mounted.renderApp(createElement(RouterProvider, { router }));
+	await mounted.waitFor(
+		() => mounted.text().includes("No "),
+		"the empty list to settle",
+	);
+	return mounted;
+};
+
+/** Press the Unread chip, which is the whole narrowing this test is about. */
+const pressUnread = async (mounted: DomHarness): Promise<void> => {
+	mounted.click(mounted.byLabel("Expand filters"));
+	await mounted.flush();
+	const attributes = mounted.query('fieldset[aria-label="Attributes"]');
+	assert.ok(attributes, "the attribute chips are not on screen");
+	const unread = [...attributes.querySelectorAll("button")].find(
+		(button) => button.textContent === "Unread",
+	);
+	assert.ok(unread, "there is no Unread chip to press");
+	mounted.click(unread);
+	await mounted.waitFor(
+		() => mounted.text().includes("No "),
+		"the narrowed list to answer",
+	);
+};
+
+describe("an empty list narrowed by a chip or a token (#1126)", () => {
+	for (const pane of panes) {
+		it(`${pane.name} names the narrowing instead of the collection`, async () => {
+			const mounted = await mount(pane);
+			assert.match(
+				mounted.text(),
+				new RegExp(`No messages in ${pane.scopeLabel}`),
+				"the unfiltered copy is the state this test starts from",
+			);
+
+			await pressUnread(mounted);
+
+			const shown = mounted.text();
+			assert.match(shown, new RegExp(`No unread mail in ${pane.scopeLabel}`));
+			assert.doesNotMatch(
+				shown,
+				new RegExp(`No messages in ${pane.scopeLabel}`),
+				"a filtered list told the reader the collection itself was empty",
+			);
+		});
+
+		it(`${pane.name} answers a token-only search the same way`, async () => {
+			const mounted = await mount(pane, "is:unread");
+
+			const shown = mounted.text();
+			assert.match(shown, new RegExp(`No unread mail in ${pane.scopeLabel}`));
+			assert.doesNotMatch(
+				shown,
+				new RegExp(`No messages in ${pane.scopeLabel}`),
+				"a search of tokens alone read as an empty collection",
+			);
+			assert.doesNotMatch(
+				shown,
+				/No messages match your search/,
+				"the narrowing is named, so the generic search line is wrong here",
+			);
+		});
+
+		it(`${pane.name} says how much was checked and offers the way out`, async () => {
+			const mounted = await mount(pane);
+			await pressUnread(mounted);
+
+			const shown = mounted.text();
+			assert.match(shown, /Every message in this folder was checked\./);
+			assert.ok(
+				[...mounted.queryAll("button")].some(
+					(button) => button.textContent === "Clear filter",
+				),
+				"a narrowed empty list offered no way back out of the narrowing",
+			);
+		});
+	}
+});

package/src/lib/list-narrowing.test.ts

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { narrowingLabel } from "./list-narrowing.js";
+import { parseSearchTokens, type SearchToken } from "./search-tokens.js";
+
+const chips = (
+	category = "all",
+	attributes: string[] = [],
+): { category: string; attributes: ReadonlySet<string> } => ({
+	category,
+	attributes: new Set(attributes),
+});
+
+const tokensOf = (query: string): SearchToken[] =>
+	parseSearchTokens(query).tokens;
+
+describe("narrowingLabel", () => {
+	it("says nothing when nothing narrows the list", () => {
+		assert.equal(narrowingLabel(chips(), []), undefined);
+	});
+
+	it("treats free text as no narrowing — the search copy already names it", () => {
+		assert.equal(narrowingLabel(chips(), tokensOf("invoice")), undefined);
+	});
+
+	it("names the category chip exactly as it always did", () => {
+		assert.equal(narrowingLabel(chips("personal"), []), "Personal mail");
+	});
+
+	it("names an attribute chip with no category chosen (#1126)", () => {
+		assert.equal(narrowingLabel(chips("all", ["unread"]), []), "unread mail");
+		assert.equal(
+			narrowingLabel(chips("all", ["attachment"]), []),
+			"mail with an attachment",
+		);
+	});
+
+	it("names a token-only search (#1126)", () => {
+		assert.equal(narrowingLabel(chips(), tokensOf("is:unread")), "unread mail");
+		assert.equal(
+			narrowingLabel(chips(), tokensOf("has:attachment")),
+			"mail with an attachment",
+		);
+	});
+
+	it("orders every narrowing into one phrase", () => {
+		assert.equal(
+			narrowingLabel(chips("personal", ["unread", "attachment"]), []),
+			"Personal unread mail with an attachment",
+		);
+	});
+
+	it("says one narrowing once when a chip and a token agree", () => {
+		assert.equal(
+			narrowingLabel(chips("all", ["unread"]), tokensOf("is:unread")),
+			"unread mail",
+		);
+	});
+
+	it("lets the chip win where a token contradicts it, as the request does", () => {
+		assert.equal(
+			narrowingLabel(chips("personal"), tokensOf("category:newsletter")),
+			"Personal mail",
+		);
+		assert.equal(
+			narrowingLabel(chips("all", ["unread"]), tokensOf("is:read")),
+			"unread mail",
+		);
+	});
+
+	it("names the tokens no request parameter carries", () => {
+		assert.equal(
+			narrowingLabel(chips(), tokensOf("before:2024-01-01")),
+			"mail sent before 2024-01-01",
+		);
+		assert.equal(
+			narrowingLabel(chips(), tokensOf("from:alex@example.com")),
+			"mail from alex@example.com",
+		);
+	});
+
+	it("keeps two values of the same token, which narrow to neither one", () => {
+		assert.equal(
+			narrowingLabel(chips(), tokensOf("from:alex from:priya")),
+			"mail from alex from priya",
+		);
+	});
+});

package/src/lib/list-narrowing.ts

@@ -0,0 +1,172 @@
+/**
+ * Whether a list is narrowed, and by what — one derived fact for every list.
+ *
+ * `MessageListEmpty` reads the presence of a `MessageListFilter` as "something
+ * is filtering this list". Both list panes used to build that object from the
+ * category chip alone, so a reader who had narrowed by the Unread chip, the Has
+ * attachment chip, or a typed `is:unread` was told the collection itself was
+ * empty — "No messages in Starred" over a mailbox full of starred mail (#1126).
+ *
+ * Every narrowing the two panes offer therefore lands here: the chips the view
+ * holds and the tokens parsed out of the search field. A chip beats a token
+ * where both set the same parameter, exactly as the request builders resolve
+ * them, so the sentence and the query can never disagree.
+ */
+
+import type { FilterReach, MessageListFilter } from "@remit/ui";
+import { categoryLabel, type InboxFilterCriteria } from "./inbox-filters.js";
+import type { SearchToken } from "./search-tokens.js";
+
+/**
+ * One narrowing, as words. `pre` qualifies "mail" before it ("unread mail"),
+ * `post` after it ("mail with an attachment"). `dimension` is what it narrows
+ * by, so two sources naming the same thing are said once.
+ */
+interface NarrowingPart {
+	dimension: string;
+	position: "pre" | "post";
+	text: string;
+}
+
+const UNREAD: NarrowingPart = {
+	dimension: "read",
+	position: "pre",
+	text: "unread",
+};
+const READ: NarrowingPart = {
+	dimension: "read",
+	position: "pre",
+	text: "read",
+};
+const STARRED: NarrowingPart = {
+	dimension: "starred",
+	position: "pre",
+	text: "starred",
+};
+const ATTACHMENT: NarrowingPart = {
+	dimension: "attachment",
+	position: "post",
+	text: "with an attachment",
+};
+
+/** The attribute chips, in the order the phrase says them. */
+const ATTRIBUTE_PARTS: readonly (readonly [string, NarrowingPart])[] = [
+	["unread", UNREAD],
+	["flagged", STARRED],
+	["attachment", ATTACHMENT],
+];
+
+const tokenPart = (token: SearchToken): NarrowingPart => {
+	switch (token.type) {
+		case "category":
+			return {
+				dimension: "category",
+				position: "pre",
+				text: categoryLabel(token.category) ?? token.value,
+			};
+		case "isUnread":
+			return UNREAD;
+		case "isRead":
+			return READ;
+		case "isStarred":
+			return STARRED;
+		case "hasAttachment":
+			return ATTACHMENT;
+		case "from":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `from ${token.value}`,
+			};
+		case "subject":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `about “${token.value}”`,
+			};
+		case "before":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `sent before ${token.value}`,
+			};
+		case "after":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `sent on or after ${token.value}`,
+			};
+		case "in":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `in ${token.value}`,
+			};
+		case "account":
+			return {
+				dimension: token.raw,
+				position: "post",
+				text: `in the ${token.value} account`,
+			};
+	}
+};
+
+/** Everything narrowing the list, chips first, each dimension said once. */
+const narrowingParts = (
+	chips: InboxFilterCriteria,
+	tokens: readonly SearchToken[],
+): NarrowingPart[] => {
+	const byDimension = new Map<string, NarrowingPart>();
+	const add = (part: NarrowingPart) => {
+		if (byDimension.has(part.dimension)) return;
+		byDimension.set(part.dimension, part);
+	};
+
+	const category = categoryLabel(chips.category);
+	if (category) add({ dimension: "category", position: "pre", text: category });
+	for (const [id, part] of ATTRIBUTE_PARTS) {
+		if (chips.attributes.has(id)) add(part);
+	}
+	for (const token of tokens) add(tokenPart(token));
+
+	return [...byDimension.values()];
+};
+
+/**
+ * The narrowing as the noun phrase the empty state's headline reads "No " in
+ * front of, or `undefined` when nothing narrows the list.
+ */
+export const narrowingLabel = (
+	chips: InboxFilterCriteria,
+	tokens: readonly SearchToken[],
+): string | undefined => {
+	const parts = narrowingParts(chips, tokens);
+	if (parts.length === 0) return undefined;
+	const said = (position: "pre" | "post") =>
+		parts.filter((part) => part.position === position).map((p) => p.text);
+	return [...said("pre"), "mail", ...said("post")].join(" ");
+};
+
+export interface ListNarrowing {
+	/** The chip state the view holds. */
+	chips: InboxFilterCriteria;
+	/** Every token the search field carries, sent as a parameter or not. */
+	tokens: readonly SearchToken[];
+	/** How much of the collection the request reached, read off the request. */
+	reach: FilterReach;
+	/** Drops every narrowing the label names — the chips and the query alike. */
+	onClear: () => void;
+}
+
+/** The filter a narrowed list hands its empty state, or `undefined` when it is
+ *  not narrowed at all. */
+export const listNarrowing = ({
+	chips,
+	tokens,
+	reach,
+	onClear,
+}: ListNarrowing): MessageListFilter | undefined => {
+	const label = narrowingLabel(chips, tokens);
+	if (!label) return undefined;
+	return { label, reach, onClear };
+};