@remit/ui 0.0.13 → 0.0.15

package/src/components/search-result-row.tsx

@@ -2,6 +2,7 @@ import { Flag } from "lucide-react";
 import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
 import { Badge } from "./badge.js";
+import { provenanceFolderLabel, type ResultFolder } from "./folder-role.js";
 
 export type SearchResultTone =
 	| "neutral"
@@ -27,6 +28,12 @@ export interface SearchResult {
 	threadId?: string;
 	/** The mailbox the result lives in; paired with {@link threadId} to open it. */
 	mailboxId?: string;
+	/**
+	 * The folder this row was read from. A search that reaches every folder
+	 * returns rows from all over, so the row says where it came from; see
+	 * {@link provenanceFolderLabel} for which folders can be named.
+	 */
+	folder?: ResultFolder;
 	/**
 	 * Why a semantic ("Related") hit matched — a plain-language label derived
 	 * from `matchedChunkType` (e.g. "body", "subject", "attachment"), so the user
@@ -43,6 +50,12 @@ export interface SearchResultRowProps {
 	onClick?: () => void;
 	/** When given, literal (case-insensitive) matches are bolded in subject/snippet. */
 	query?: string;
+	/**
+	 * Show the folder the row came from. Defaults to true. A search confined to
+	 * one folder turns it off — every row would carry the same label, which is
+	 * noise rather than provenance.
+	 */
+	showFolder?: boolean;
 }
 
 function highlight(text: string, query?: string): ReactNode {
@@ -79,7 +92,12 @@ export function SearchResultRow({
 	result,
 	onClick,
 	query,
+	showFolder = true,
 }: SearchResultRowProps) {
+	const folderLabel =
+		showFolder && result.folder
+			? provenanceFolderLabel(result.folder)
+			: undefined;
 	return (
 		<button
 			type="button"
@@ -118,6 +136,11 @@ export function SearchResultRow({
 				<span className="min-w-0 flex-1 truncate text-xs text-fg-subtle">
 					{highlight(result.snippet, query)}
 				</span>
+				{folderLabel && (
+					<Badge tone="neutral" className="shrink-0">
+						{folderLabel}
+					</Badge>
+				)}
 				{result.category && (
 					<Badge tone={result.category.tone ?? "neutral"} className="shrink-0">
 						{result.category.label}

package/src/components/search-results.render.test.ts

@@ -87,3 +87,184 @@ describe("SearchResults", () => {
 		assert.doesNotMatch(html, /Remove filter/);
 	});
 });
+
+const spamResult: SearchResult = {
+	id: "s1",
+	sender: "billing@unknown-vendor.test",
+	subject: "URGENT invoice attached",
+	snippet: "Wire the amount below.",
+	date: "Feb 11",
+	folder: { role: "junk" },
+};
+
+const archivedResult: SearchResult = {
+	...result,
+	id: "a1",
+	sender: "Mollie",
+	folder: { role: "archive" },
+};
+
+const mixed: SearchResultSection[] = [
+	{ id: "results", label: "Results", results: [archivedResult, spamResult] },
+];
+
+describe("SearchResults spam handling", () => {
+	it("holds spam out of a global search and offers it as a count", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.match(html, /result from Spam/);
+		assert.match(html, /Mollie/);
+	});
+
+	it("makes no offer when a global search found nothing in spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{ id: "results", label: "Results", results: [archivedResult] },
+				],
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("offers spam above the empty state when every match is spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [{ id: "results", label: "Results", results: [spamResult] }],
+				scope: { kind: "global" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, /No matches for/);
+		assert.match(html, /result from Spam/);
+	});
+
+	it("shows neither spam rows nor an offer when scoped elsewhere", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "folder", role: "inbox" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+		assert.match(html, /Mollie/);
+	});
+
+	it("renders spam rows normally and makes no offer when scoped to spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "folder", role: "junk" },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("makes no offer without a way to scope to spam", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+			}),
+		);
+		assert.doesNotMatch(html, /from Spam/);
+	});
+
+	it("prefers a caller-supplied total over the rows held out of this page", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: mixed,
+				scope: { kind: "global" },
+				spamMatchCount: 42,
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, />42</);
+	});
+});
+
+describe("SearchResults provenance labels", () => {
+	it("names the folder each row came from in a global search", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{
+						id: "results",
+						label: "Results",
+						results: [
+							archivedResult,
+							{
+								...result,
+								id: "c1",
+								folder: { providerPath: "Projects/Books" },
+							},
+						],
+					},
+				],
+				scope: { kind: "global" },
+			}),
+		);
+		assert.match(html, /Archive/);
+		assert.match(html, /Books/);
+	});
+
+	it("drops the labels when the search is scoped to one folder", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{ id: "results", label: "Results", results: [archivedResult] },
+				],
+				scope: { kind: "folder", role: "archive" },
+			}),
+		);
+		assert.doesNotMatch(html, /Archive/);
+	});
+
+	it("leaves a row from a view rather than a folder unlabelled", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{
+						id: "results",
+						label: "Results",
+						results: [
+							{ ...result, id: "v1", folder: { role: "all" } },
+							{ ...result, id: "v2", folder: { role: "flagged" } },
+							{
+								...result,
+								id: "v3",
+								folder: { providerPath: "[Gmail]/Important" },
+							},
+						],
+					},
+				],
+				scope: { kind: "global" },
+			}),
+		);
+		assert.doesNotMatch(html, /All Mail/);
+		assert.doesNotMatch(html, /Starred/);
+		assert.doesNotMatch(html, /Important/);
+	});
+});

package/src/components/search-results.stories.tsx

@@ -73,43 +73,71 @@ const resultSections: SearchResultSection[] = [
 ];
 
 /**
- * Matches from outside the inbox — Archive, Sent, Spam and a custom folder.
- * These are the rows an unscoped search returns that an INBOX-only one could
- * not, so they only ever appear under the brief's sections.
+ * Matches from outside the inbox — Archive, Sent and a custom folder — each
+ * carrying the folder it was read from. These are the rows a search reaching
+ * every folder returns that an INBOX-only one could not.
  */
 const crossFolderMatches: SearchResult[] = [
 	{
 		id: "x1",
 		sender: "Mollie",
 		subject: "Invoice 2026-02 — archived",
-		snippet: "Filed to Archive last month; payment already settled.",
+		snippet: "Filed last month; payment already settled.",
 		date: "Feb 24",
+		folder: { role: "archive" },
 		category: { label: "Receipt", tone: "positive" },
 	},
 	{
 		id: "x2",
 		sender: "me",
 		subject: "Re: invoice query",
-		snippet: "Sent — attaching the invoice you asked for.",
+		snippet: "Attaching the invoice you asked for.",
 		date: "Feb 18",
+		folder: { role: "sent" },
 	},
 	{
-		id: "x3",
+		id: "x4",
+		sender: "Accountant",
+		subject: "Invoices for the quarter",
+		snippet: "The quarterly set, filed with the rest of the bookkeeping.",
+		date: "Jan 30",
+		folder: { providerPath: "Projects/Bookkeeping" },
+	},
+];
+
+/**
+ * Matches that live in the account's `\Junk` folder. A global search holds
+ * these out of the sections entirely and offers them as a count instead.
+ */
+const spamMatches: SearchResult[] = [
+	{
+		id: "s1",
 		sender: "billing@unknown-vendor.test",
 		subject: "URGENT invoice attached",
-		snippet: "Marked as spam, but it is the invoice the user is looking for.",
+		snippet: "Wire the amount below within 24 hours to avoid suspension.",
 		date: "Feb 11",
-		category: { label: "Spam", tone: "warning" },
+		folder: { role: "junk" },
 	},
 	{
-		id: "x4",
-		sender: "Accountant",
-		subject: "Invoices for the quarter",
-		snippet: "Filed under Projects/Bookkeeping.",
-		date: "Jan 30",
+		id: "s2",
+		sender: "invoices@pay-now.test",
+		subject: "Outstanding invoice — final notice",
+		snippet: "Your account is overdue. Settle immediately.",
+		date: "Feb 4",
+		folder: { role: "junk" },
 	},
 ];
 
+/** The literal section a global search returns: inbox rows plus everywhere else. */
+const globalTopMatches: SearchResult[] = [
+	...topMatches.map((result) => ({
+		...result,
+		folder: { role: "inbox" as const },
+	})),
+	...crossFolderMatches,
+	...spamMatches,
+];
+
 const emptySections: SearchResultSection[] = [
 	{ id: "top", label: "Top matches", results: [] },
 ];
@@ -151,23 +179,45 @@ export const Idle: Story = {
 
 /**
  * The daily brief's unscoped search: no scope chip in the bar, and the literal
- * section carries matches from every folder — Archive, Sent, Spam and custom
- * folders alongside the inbox. Before the listing behind it took a search mode
- * it could only ever return inbox mail, so this section was silently narrower
- * than the bar promised.
+ * section carries matches from every folder — Archive, Sent and custom folders
+ * alongside the inbox. Each row says which folder it came from, because with
+ * nothing scoping the search the folder is the only thing placing the result.
  *
- * The rows themselves do not say which folder they came from; the sections are
- * ordered newest first regardless of where each message is filed.
+ * The two spam matches in the same data are not in this list. They are held out
+ * and offered above it as a count.
  */
-export const UnscopedAcrossFolders: Story = {
+export const GlobalAcrossFolders: Story = {
 	render: () => (
 		<Harness
 			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: globalTopMatches },
+				{ id: "related", label: "Related", results: related },
+			]}
+		/>
+	),
+};
+
+/**
+ * The same global search over an account whose Spam folder holds nothing
+ * matching. No spam rows to hold out, so no offer — the offer only ever appears
+ * because there is something behind it.
+ */
+export const GlobalWithoutSpamMatches: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
 			sections={[
 				{
 					id: "top",
 					label: "Top matches",
-					results: [...topMatches, ...crossFolderMatches],
+					results: globalTopMatches.filter(
+						(result) => result.folder?.role !== "junk",
+					),
 				},
 				{ id: "related", label: "Related", results: related },
 			]}
@@ -176,18 +226,105 @@ export const UnscopedAcrossFolders: Story = {
 };
 
 /**
- * A scoped view (a mailbox route, its `in:` chip in the bar). Both sections are
- * scoped to that folder and take the kit's default labels — the semantic
- * section used to run unscoped here under an "Everywhere" heading, which
- * contradicted the chip the same bar was showing.
+ * An account with no junk folder at all. Nothing is appointed `\Junk`, so no
+ * row can be spam and the component behaves exactly as it does when Spam is
+ * simply empty — there is no separate case to handle.
+ */
+export const GlobalAccountWithoutSpamFolder: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: crossFolderMatches },
+			]}
+		/>
+	),
+};
+
+/**
+ * A global search whose only matches are in Spam. The sections are empty, so
+ * the empty state stands — with the offer above it, which is the whole reason
+ * the user is not left thinking the search found nothing.
+ */
+export const GlobalOnlySpamMatches: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+		/>
+	),
+};
+
+/**
+ * Scoped to the inbox (its `in:inbox` chip in the bar), given the very same
+ * rows as the global story — spam matches included. Nothing about Spam appears:
+ * no rows, no count, no offer. A scoped search shows its own scope and no more,
+ * and that asymmetry with the global view is deliberate.
+ *
+ * The rows also drop their folder labels here. Every row is in the scoped
+ * folder, so naming it on each one repeats the chip.
+ */
+export const ScopedToInbox: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "folder", role: "inbox" }}
+			onScopeToSpam={() => {}}
+			sections={[
+				{ id: "top", label: "Top matches", results: globalTopMatches },
+				{ id: "related", label: "Related", results: related },
+			]}
+		/>
+	),
+};
+
+/**
+ * Scoped to Spam — where taking the offer lands. Ordinary rows, rendered
+ * normally, and no offer, because the user is already here. This is the same
+ * scoped search reached by navigating to Spam with the query carried over; the
+ * offer is a shortcut into it, not a mode of its own.
+ */
+export const ScopedToSpam: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			scope={{ kind: "folder", role: "junk" }}
+			onScopeToSpam={() => {}}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+		/>
+	),
+};
+
+/**
+ * A folder a search result can be in but never labelled with. All Mail and
+ * Starred are views over mail filed elsewhere, and Gmail exposes them as
+ * ordinary folders, so a row read from one carries no provenance label rather
+ * than a misleading one. The other rows keep theirs.
  */
-export const ScopedToOneFolder: Story = {
+export const VirtualFoldersGoUnlabelled: Story = {
 	render: () => (
 		<Harness
 			value="invoice"
+			scope={{ kind: "global" }}
 			sections={[
-				{ id: "top", label: "Top matches", results: topMatches.slice(0, 2) },
-				{ id: "related", label: "Related", results: related.slice(0, 1) },
+				{
+					id: "top",
+					label: "Top matches",
+					results: [
+						{ ...topMatches[0], id: "v1", folder: { role: "all" } },
+						{ ...topMatches[1], id: "v2", folder: { role: "flagged" } },
+						{
+							...topMatches[2],
+							id: "v3",
+							folder: { providerPath: "[Gmail]/Important" },
+						},
+						...crossFolderMatches.slice(0, 1),
+					],
+				},
 			]}
 		/>
 	),

package/src/components/search-results.tsx

@@ -1,8 +1,10 @@
 import { ChevronDown, Clock } from "lucide-react";
 import { useState } from "react";
 import { cn } from "../lib/cn.js";
+import type { FolderRole } from "./folder-role.js";
 import { type SearchResult, SearchResultRow } from "./search-result-row.js";
 import { SearchTokenChips } from "./search-token-chip.js";
+import { SpamResultsOffer } from "./spam-results-offer.js";
 
 /** Rows shown before the "Show N more" expander kicks in. */
 const SECTION_ROW_CAP = 6;
@@ -15,6 +17,44 @@ export interface SearchResultSection {
 	initialCollapsed?: boolean;
 }
 
+/**
+ * What the search currently covers. `global` is the unscoped search the daily
+ * brief runs — every account, every folder, no chip in the bar. `folder` is a
+ * search the sidebar narrowed to one place, which the bar shows as a chip.
+ */
+export type SearchScope =
+	| { kind: "global" }
+	| { kind: "folder"; role?: FolderRole };
+
+const GLOBAL_SCOPE: SearchScope = { kind: "global" };
+
+const isSpamScope = (scope: SearchScope): boolean =>
+	scope.kind === "folder" && scope.role === "junk";
+
+const isSpamResult = (result: SearchResult): boolean =>
+	result.folder?.role === "junk";
+
+/**
+ * Split spam matches out of the rows a search returned.
+ *
+ * Spam is identified by the account's `\Junk` special-use appointment, never by
+ * folder name, so an account that calls it `Junk`, `Bulk Mail` or nothing at
+ * all behaves the same, and an account with no junk folder simply never yields
+ * a spam row.
+ */
+export function partitionSpamResults(results: SearchResult[]): {
+	kept: SearchResult[];
+	spam: SearchResult[];
+} {
+	const kept: SearchResult[] = [];
+	const spam: SearchResult[] = [];
+	for (const result of results) {
+		if (isSpamResult(result)) spam.push(result);
+		else kept.push(result);
+	}
+	return { kept, spam };
+}
+
 export interface SearchResultsProps {
 	/** The current query — narrows what's shown and bolds literal matches. */
 	value: string;
@@ -32,6 +72,19 @@ export interface SearchResultsProps {
 	 * query has no recognized tokens.
 	 */
 	tokens?: { label: string; onRemove: () => void }[];
+	/** What the search covers. Defaults to the unscoped, global search. */
+	scope?: SearchScope;
+	/**
+	 * Total spam matches the search found, for when the app knows more than the
+	 * rows on this page. Defaults to the number of spam rows held out of
+	 * {@link sections}.
+	 */
+	spamMatchCount?: number;
+	/**
+	 * Scope the search to Spam. Without it there is no offer, so an app that has
+	 * nowhere to navigate simply never makes one.
+	 */
+	onScopeToSpam?: () => void;
 }
 
 /**
@@ -44,10 +97,12 @@ function CollapsibleResultSection({
 	section,
 	query,
 	onSelectResult,
+	showFolder,
 }: {
 	section: SearchResultSection;
 	query?: string;
 	onSelectResult?: (result: SearchResult) => void;
+	showFolder?: boolean;
 }) {
 	const [collapsed, setCollapsed] = useState(section.initialCollapsed ?? false);
 	const [expanded, setExpanded] = useState(false);
@@ -87,6 +142,7 @@ function CollapsibleResultSection({
 							key={result.id}
 							result={result}
 							query={query}
+							showFolder={showFolder}
 							onClick={
 								onSelectResult ? () => onSelectResult(result) : undefined
 							}
@@ -115,6 +171,18 @@ function CollapsibleResultSection({
  * sections — one implementation so both tiers render identical rows. The caller
  * owns the surrounding chrome and scroll container (a `FilterSheet`, the
  * takeover header, or the list-pane body). Presentational and prop-driven.
+ *
+ * Spam is the one folder that does not inline, and it behaves differently by
+ * scope:
+ *
+ * - **Global** — spam rows are held out of the sections and offered instead, as
+ *   a count with a way into a Spam-scoped search.
+ * - **Scoped to anything else** — spam rows are held out and nothing is offered.
+ *   A scoped search shows its own scope and no more.
+ * - **Scoped to Spam** — ordinary rows, rendered normally, no offer.
+ *
+ * Provenance labels follow the same logic: only a global search names the
+ * folder each row came from, because a scoped one would repeat itself.
  */
 export function SearchResults({
 	value,
@@ -124,11 +192,11 @@ export function SearchResults({
 	loading,
 	onSelectResult,
 	tokens,
+	scope = GLOBAL_SCOPE,
+	spamMatchCount,
+	onScopeToSpam,
 }: SearchResultsProps) {
 	const hasQuery = value.trim().length > 0;
-	const hasResults = (sections ?? []).some(
-		(section) => section.results.length > 0,
-	);
 
 	if (!hasQuery) {
 		if (recentSearches && recentSearches.length > 0) {
@@ -181,10 +249,36 @@ export function SearchResults({
 		);
 	}
 
+	const spamScoped = isSpamScope(scope);
+	const isGlobal = scope.kind === "global";
+
+	const partitioned = (sections ?? []).map((section) => {
+		if (spamScoped) return { section, spam: [] as SearchResult[] };
+		const { kept, spam } = partitionSpamResults(section.results);
+		return { section: { ...section, results: kept }, spam };
+	});
+
+	const visibleSections = partitioned.map((entry) => entry.section);
+	const heldOutSpamCount = partitioned.reduce(
+		(total, entry) => total + entry.spam.length,
+		0,
+	);
+	const spamCount = spamMatchCount ?? heldOutSpamCount;
+	const spamOffer = isGlobal &&
+		spamCount > 0 &&
+		onScopeToSpam !== undefined && (
+			<SpamResultsOffer count={spamCount} onScopeToSpam={onScopeToSpam} />
+		);
+
+	const hasResults = visibleSections.some(
+		(section) => section.results.length > 0,
+	);
+
 	if (!hasResults) {
 		return (
 			<div className="flex flex-col">
 				{chips}
+				{spamOffer}
 				<div className="px-row-inset py-10 text-center">
 					<p className="text-sm font-medium text-fg">
 						No matches for &ldquo;{value}&rdquo;
@@ -200,13 +294,15 @@ export function SearchResults({
 	return (
 		<div className="flex flex-col">
 			{chips}
-			{sections
-				?.filter((section) => section.results.length > 0)
+			{spamOffer}
+			{visibleSections
+				.filter((section) => section.results.length > 0)
 				.map((section) => (
 					<CollapsibleResultSection
 						key={section.id}
 						section={section}
 						query={value}
+						showFolder={isGlobal}
 						onSelectResult={onSelectResult}
 					/>
 				))}