@remit/ui 0.0.12 → 0.0.14

package/package.json

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

package/src/components/app-shell-types.ts

@@ -308,6 +308,13 @@ export interface AppShellProps {
 	 * fits or when the message view is showing.
 	 */
 	initialTouchState?: TouchSeed;
+	/**
+	 * Replaces the narrow-width list pane header when a selection is active —
+	 * forwarded to `MessageListPane`'s `selectionBar` slot. The caller owns
+	 * selection state and toolbar actions; when omitted, `initialTouchState`
+	 * still drives the pane's own built-in touch-triage bar.
+	 */
+	selectionBar?: ReactNode;
 	intelligence?: IntelligenceData;
 	/** Pane 4 visible. Defaults to true when intelligence is present. */
 	intelligenceOpen?: boolean;

package/src/components/app-shell.render.test.ts

@@ -300,9 +300,7 @@ describe("AppShell touch-state seeds (story/SSR affordance)", () => {
 			/aria-label="Cancel selection"/,
 			"the selection bar is shown",
 		);
-		// SSR splits interpolated text with comment markers, so match the parts.
-		assert.match(html, /messages<!-- --> selected/, "selection wording shown");
-		assert.match(html, />2<!-- -->/, "the seeded count of 2 is shown");
+		assert.match(html, /2 messages selected/, "selection wording shown");
 		// Selection mode is not a swipe — no action zones revealed.
 		assert.equal(
 			count(html, trailingAction),
@@ -345,6 +343,23 @@ describe("AppShell touch-state seeds (story/SSR affordance)", () => {
 		);
 	});
 
+	it("selectionBar overrides the built-in bar and forwards to the list pane", () => {
+		const html = render({
+			...touchBase,
+			selectionBar: createElement(
+				"div",
+				{ "data-testid": "custom-bar" },
+				"Deleting 1,200 of 3,412…",
+			),
+		});
+		assert.match(html, /Deleting 1,200 of 3,412…/, "the override renders");
+		assert.doesNotMatch(
+			html,
+			/aria-label="Cancel selection"/,
+			"the built-in bar is not also rendered",
+		);
+	});
+
 	it("ignores the touch seed at/above 1024 (desktop list)", () => {
 		const html = render({
 			...touchBase,

package/src/components/app-shell.tsx

@@ -70,6 +70,7 @@ export function AppShell({
 	thread,
 	initialNarrowView = "list",
 	initialTouchState,
+	selectionBar,
 	intelligence,
 	intelligenceOpen = true,
 	density,
@@ -126,6 +127,7 @@ export function AppShell({
 			}}
 			onSelectBriefCategory={selectCategory}
 			initialTouchState={initialTouchState}
+			selectionBar={selectionBar}
 		/>
 	);
 
@@ -185,6 +187,7 @@ function AppShellList({
 	onSelectThread,
 	onSelectBriefCategory,
 	initialTouchState,
+	selectionBar,
 }: Pick<
 	AppShellProps,
 	| "thread"
@@ -202,6 +205,7 @@ function AppShellList({
 	| "density"
 	| "onSelectThread"
 	| "initialTouchState"
+	| "selectionBar"
 > & {
 	narrowView: NarrowView;
 	onBackToList: () => void;
@@ -244,6 +248,7 @@ function AppShellList({
 			onOpenNav={showNavPane ? undefined : layout?.openNav}
 			isDesktop={showReadingPane}
 			initialTouchState={initialTouchState}
+			selectionBar={selectionBar}
 		/>
 	);
 }

package/src/components/folder-role.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isVirtualFolderRole, provenanceFolderLabel } from "./folder-role.js";
+
+describe("provenanceFolderLabel", () => {
+	it("names an appointed role by its canonical label", () => {
+		assert.equal(provenanceFolderLabel({ role: "archive" }), "Archive");
+		assert.equal(provenanceFolderLabel({ role: "sent" }), "Sent");
+	});
+
+	it("reads a junk appointment as Spam whatever the server calls it", () => {
+		assert.equal(
+			provenanceFolderLabel({ role: "junk", providerPath: "Bulk Mail" }),
+			"Spam",
+		);
+	});
+
+	it("falls back to the leaf of a folder nobody appointed", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "Projects/Bookkeeping" }),
+			"Bookkeeping",
+		);
+	});
+
+	it("refuses to label a view rather than a place", () => {
+		assert.equal(provenanceFolderLabel({ role: "all" }), undefined);
+		assert.equal(provenanceFolderLabel({ role: "flagged" }), undefined);
+	});
+
+	it("refuses to label Gmail's own reserved namespace", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Gmail]/All Mail" }),
+			undefined,
+		);
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Gmail]/Starred" }),
+			undefined,
+		);
+	});
+
+	it("refuses the googlemail.com spelling of the same namespace", () => {
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Google Mail]/All Mail" }),
+			undefined,
+		);
+		assert.equal(
+			provenanceFolderLabel({ providerPath: "[Google Mail]/Starred" }),
+			undefined,
+		);
+	});
+
+	it("labels a user folder that merely mentions Gmail", () => {
+		assert.equal(provenanceFolderLabel({ providerPath: "Gmail" }), "Gmail");
+	});
+
+	it("has nothing to say about a folder it knows nothing about", () => {
+		assert.equal(provenanceFolderLabel({}), undefined);
+	});
+});
+
+describe("isVirtualFolderRole", () => {
+	it("counts All Mail and Starred as views", () => {
+		assert.equal(isVirtualFolderRole("all"), true);
+		assert.equal(isVirtualFolderRole("flagged"), true);
+	});
+
+	it("counts real folders as places", () => {
+		assert.equal(isVirtualFolderRole("inbox"), false);
+		assert.equal(isVirtualFolderRole("junk"), false);
+		assert.equal(isVirtualFolderRole("trash"), false);
+	});
+});

package/src/components/folder-role.tsx

@@ -54,6 +54,65 @@ export function providerLeaf(providerPath: string): string {
 	return parts[parts.length - 1] || providerPath;
 }
 
+/* ------------------------------------------------------------------ */
+/* Provenance: where a search result actually lives                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * The folder a search result was read from. `role` is the account's IMAP
+ * special-use appointment (`junk` is `\Junk`); accounts that expose a folder
+ * nobody appointed carry only a `providerPath`.
+ */
+export interface ResultFolder {
+	role?: FolderRole;
+	/** Provider path as the server spells it, e.g. `Projects/Bookkeeping`. */
+	providerPath?: string;
+}
+
+/**
+ * Roles that name a view rather than a place a message is filed. A message in
+ * All Mail or Starred is also somewhere real, so labelling a result with one of
+ * these says nothing about where it came from.
+ */
+const VIRTUAL_ROLES: ReadonlySet<FolderRole> = new Set(["all", "flagged"]);
+
+export function isVirtualFolderRole(role: FolderRole): boolean {
+	return VIRTUAL_ROLES.has(role);
+}
+
+/**
+ * Gmail exposes its views as ordinary folders under a reserved namespace. An
+ * account that appointed no role to them leaves the path as the only signal, so
+ * the namespace is matched by name — the one place a name is the honest test,
+ * because it is the provider's own reserved prefix and not a user's folder.
+ *
+ * Accounts provisioned under googlemail.com get the same namespace spelled
+ * `[Google Mail]`, so both forms count. A user folder plainly called `Gmail`
+ * does not — the brackets are what make the prefix reserved.
+ */
+const GMAIL_NAMESPACES: ReadonlySet<string> = new Set([
+	"[Gmail]",
+	"[Google Mail]",
+]);
+
+/**
+ * Label for the folder a result came from, or `undefined` when that folder is a
+ * view rather than a place — in which case no label is better than a misleading
+ * one. An appointed role wins over the provider's spelling, so a folder the
+ * account calls `Junk` still reads as "Spam".
+ */
+export function provenanceFolderLabel(
+	folder: ResultFolder,
+): string | undefined {
+	if (folder.role) {
+		if (isVirtualFolderRole(folder.role)) return undefined;
+		return canonicalRoleLabel(folder.role);
+	}
+	if (!folder.providerPath) return undefined;
+	if (GMAIL_NAMESPACES.has(folder.providerPath.split("/")[0])) return undefined;
+	return providerLeaf(folder.providerPath);
+}
+
 export function roleIcon(role: FolderRole): ReactNode {
 	if (role === "inbox") return <Inbox className="size-4" />;
 	if (role === "drafts") return <FileText className="size-4" />;

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

@@ -212,8 +212,15 @@ export const CustomListBody: Story = {
 	decorators: [desktopFrame],
 };
 
-/** External `selectionBar` slot — the pane delegates the header to the caller
- *  when a selection is active. */
+/**
+ * External `selectionBar` slot mechanism, exercised at desktop width with
+ * `SelectionTopBar` as a convenient stand-in node — any slot content works
+ * here, the point is that the pane header is replaced. This is NOT a
+ * production composition: the live desktop toolbar is `SelectionToolbar`
+ * (web-client only, not in this kit); `MessageList.tsx` only ever puts
+ * `SelectionTopBar` in this slot when `!isDesktop` — see `NarrowExternalSelectionBar`
+ * below for that production-accurate case.
+ */
 export const ExternalSelectionBar: Story = {
 	args: {
 		isDesktop: true,
@@ -230,6 +237,27 @@ export const ExternalSelectionBar: Story = {
 	decorators: [desktopFrame],
 };
 
+/**
+ * The production composition (`MessageList.tsx:798` gates on `!isDesktop`):
+ * `SelectionTopBar` in the `selectionBar` slot at narrow width. Desktop never
+ * renders this component in the slot — only `NarrowTouchList`'s width does.
+ */
+export const NarrowExternalSelectionBar: Story = {
+	args: {
+		isDesktop: false,
+		flatList: true,
+		selectionBar: (
+			<SelectionTopBar
+				count={2}
+				onCancel={() => undefined}
+				onMarkRead={() => undefined}
+				onDelete={() => undefined}
+			/>
+		),
+	},
+	decorators: [narrowFrame],
+};
+
 /** Fail-loud error state — the specific failure detail is surfaced under the
  *  headline (not a bare "something went wrong"), with a way back (Retry) and a
  *  place for the failure to go (Report a problem). */

package/src/components/mobile-search-view.render.test.ts

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { MobileSearchView } from "./mobile-search-view.js";
+import type { SearchResult } from "./search-result-row.js";
+
+const noop = () => {};
+
+const archived: SearchResult = {
+	id: "a1",
+	sender: "Mollie",
+	subject: "Invoice 2026-02",
+	snippet: "Payment already settled.",
+	date: "Feb 24",
+	folder: { role: "archive" },
+};
+
+const spam: SearchResult = {
+	id: "s1",
+	sender: "billing@unknown-vendor.test",
+	subject: "URGENT invoice attached",
+	snippet: "Wire the amount below.",
+	date: "Feb 11",
+	folder: { role: "junk" },
+};
+
+const sections = [
+	{ id: "top", label: "Top matches", results: [archived, spam] },
+];
+
+const base = {
+	value: "invoice",
+	onChange: noop,
+	onClear: noop,
+	onCancel: noop,
+	sections,
+};
+
+describe("MobileSearchView search scope", () => {
+	it("offers held-out spam on the phone tier too", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "global" as const },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.match(html, /result from Spam/);
+		assert.match(html, /Archive/);
+	});
+
+	it("shows neither spam nor provenance labels when scoped", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "folder" as const, role: "inbox" as const },
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.doesNotMatch(html, /unknown-vendor/);
+		assert.doesNotMatch(html, /from Spam/);
+		assert.doesNotMatch(html, /Archive/);
+	});
+
+	it("passes a caller-supplied spam total through", () => {
+		const html = renderToString(
+			createElement(MobileSearchView, {
+				...base,
+				scope: { kind: "global" as const },
+				spamMatchCount: 42,
+				onScopeToSpam: noop,
+			}),
+		);
+		assert.match(html, />42</);
+	});
+});

package/src/components/mobile-search-view.stories.tsx

@@ -8,7 +8,7 @@ import {
 import { MobileSearchView } from "./mobile-search-view.js";
 import type { SearchChip } from "./search-chip-input.js";
 import type { SearchResult } from "./search-result-row.js";
-import type { SearchResultSection } from "./search-results.js";
+import type { SearchResultSection, SearchScope } from "./search-results.js";
 
 const phoneFrame: Decorator = (Story) => (
 	<div
@@ -97,6 +97,56 @@ const emptySections: SearchResultSection[] = [
 	{ id: "related", label: "Related", results: [] },
 ];
 
+/** Matches spread across ordinary folders, each carrying where it was read from. */
+const crossFolderMatches: SearchResult[] = [
+	{ ...topMatches[0], folder: { role: "inbox" } },
+	{ ...topMatches[1], folder: { role: "inbox" } },
+	{
+		id: "x1",
+		sender: "Mollie",
+		subject: "Invoice 2026-02 — archived",
+		snippet: "Filed last month; payment already settled.",
+		date: "Feb 24",
+		folder: { role: "archive" },
+	},
+	{
+		id: "x2",
+		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 in the account's `\Junk` folder. */
+const spamMatches: SearchResult[] = [
+	{
+		id: "s1",
+		sender: "billing@unknown-vendor.test",
+		subject: "URGENT invoice attached",
+		snippet: "Wire the amount below within 24 hours to avoid suspension.",
+		date: "Feb 11",
+		folder: { role: "junk" },
+	},
+	{
+		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" },
+	},
+];
+
+const acrossFoldersSections: SearchResultSection[] = [
+	{
+		id: "top",
+		label: "Top matches",
+		results: [...crossFolderMatches, ...spamMatches],
+	},
+];
+
 type Preset = "brief" | "inbox";
 
 function Harness({
@@ -105,12 +155,18 @@ function Harness({
 	loading,
 	sections,
 	preset,
+	scope,
+	spamMatchCount,
+	onScopeToSpam,
 }: {
 	initialValue?: string;
 	initialChips?: SearchChip[];
 	loading?: boolean;
 	sections?: SearchResultSection[];
 	preset: Preset;
+	scope?: SearchScope;
+	spamMatchCount?: number;
+	onScopeToSpam?: () => void;
 }) {
 	const [value, setValue] = useState(initialValue);
 	const [chips, setChips] = useState<SearchChip[]>(initialChips);
@@ -183,6 +239,9 @@ function Harness({
 			sections={sections}
 			loading={loading}
 			onSelectResult={setOpened}
+			scope={scope}
+			spamMatchCount={spamMatchCount}
+			onScopeToSpam={onScopeToSpam}
 		/>
 	);
 }
@@ -257,14 +316,70 @@ export const RelatedSelectable: Story = {
  * top bar uses, inside the full-screen takeover's own chrome. The chip is
  * removable in place — backspace at the start of the text reaches it just as it
  * does on desktop.
+ *
+ * The chip and the scope say the same thing, which is the point: an `in:spam`
+ * chip is what a Spam-scoped search looks like in the bar.
  */
 export const ScopedByChip: Story = {
 	render: () => (
 		<Harness
 			initialValue="invoice"
 			initialChips={[{ id: "in:spam", label: "in:spam" }]}
-			sections={resultSections}
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+			scope={{ kind: "folder", role: "junk" }}
+			preset="inbox"
+		/>
+	),
+};
+
+/**
+ * Global search on the phone, holding spam out and offering it above the
+ * results — the same treatment the desktop list pane gives it, because both
+ * tiers render the one `SearchResults` body. Rows name the folder they came
+ * from; the two spam matches in the same data are not among them.
+ */
+export const GlobalAcrossFolders: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			sections={acrossFoldersSections}
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			preset="brief"
+		/>
+	),
+};
+
+/**
+ * The same rows scoped to the inbox. No spam, no count, no offer, and no
+ * provenance labels — the chip in the bar already says where the search is
+ * looking.
+ */
+export const ScopedToInbox: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			initialChips={[{ id: "in:inbox", label: "in:inbox" }]}
+			sections={acrossFoldersSections}
+			scope={{ kind: "folder", role: "inbox" }}
+			onScopeToSpam={() => {}}
 			preset="inbox"
 		/>
 	),
 };
+
+/**
+ * A global phone search whose only matches are in Spam: the offer stands above
+ * the empty state rather than leaving the search looking fruitless.
+ */
+export const GlobalOnlySpamMatches: Story = {
+	render: () => (
+		<Harness
+			initialValue="invoice"
+			sections={[{ id: "top", label: "Top matches", results: spamMatches }]}
+			scope={{ kind: "global" }}
+			onScopeToSpam={() => {}}
+			preset="brief"
+		/>
+	),
+};

package/src/components/mobile-search-view.tsx

@@ -4,7 +4,11 @@ import { FilterSheet, type FilterSheetProps } from "./filter-sheet.js";
 import { SearchBar } from "./search-bar.js";
 import type { SearchChip } from "./search-chip-input.js";
 import type { SearchResult } from "./search-result-row.js";
-import { type SearchResultSection, SearchResults } from "./search-results.js";
+import {
+	type SearchResultSection,
+	SearchResults,
+	type SearchScope,
+} from "./search-results.js";
 
 export interface MobileSearchViewProps {
 	value: string;
@@ -40,6 +44,12 @@ export interface MobileSearchViewProps {
 	 */
 	chips?: readonly SearchChip[];
 	onRemoveChip?: (id: string) => void;
+	/** What the search covers; see `SearchResultsProps`. Defaults to global. */
+	scope?: SearchScope;
+	/** Total spam matches found; see `SearchResultsProps`. */
+	spamMatchCount?: number;
+	/** Scope the search to Spam; see `SearchResultsProps`. */
+	onScopeToSpam?: () => void;
 }
 
 /**
@@ -52,6 +62,9 @@ export interface MobileSearchViewProps {
  * the inboxes use) so search carries identical filters; pass no `filter` to drop
  * the chrome. Desktop reuses the same `SearchResults` body in the list pane.
  * Presentational and prop-driven.
+ *
+ * Search scope passes straight through, so the phone tier holds spam out,
+ * offers it and labels provenance on exactly the same terms as desktop.
  */
 export function MobileSearchView({
 	value,
@@ -67,6 +80,9 @@ export function MobileSearchView({
 	tokens,
 	chips,
 	onRemoveChip,
+	scope,
+	spamMatchCount,
+	onScopeToSpam,
 }: MobileSearchViewProps) {
 	const body = (
 		<SearchResults
@@ -77,6 +93,9 @@ export function MobileSearchView({
 			loading={loading}
 			onSelectResult={onSelectResult}
 			tokens={tokens}
+			scope={scope}
+			spamMatchCount={spamMatchCount}
+			onScopeToSpam={onScopeToSpam}
 		/>
 	);
 

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}