@remit/ui 0.0.13 → 0.0.15

package/package.json

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

package/src/components/button.render.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { Button } from "./button.js";
+
+describe("Button", () => {
+	it("defaults to the md size", () => {
+		const html = renderToString(createElement(Button, {}, "Save"));
+		assert.match(html, /h-9/);
+		assert.doesNotMatch(html, /h-11/);
+	});
+
+	it("renders the sm size at 28px", () => {
+		const html = renderToString(createElement(Button, { size: "sm" }, "Save"));
+		assert.match(html, /h-7/);
+	});
+
+	it("renders the touch size at 44px square", () => {
+		const html = renderToString(
+			createElement(Button, {
+				size: "touch",
+				"aria-label": "Delete",
+			}),
+		);
+		assert.match(html, /h-11/);
+		assert.match(html, /w-11/);
+	});
+});

package/src/components/button.tsx

@@ -2,7 +2,7 @@ import type { ButtonHTMLAttributes, ReactNode } from "react";
 import { cn } from "../lib/cn.js";
 
 type Variant = "primary" | "secondary" | "ghost" | "danger";
-type Size = "sm" | "md";
+type Size = "sm" | "md" | "touch";
 
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
 	variant?: Variant;
@@ -25,6 +25,10 @@ const variants: Record<Variant, string> = {
 const sizes: Record<Size, string> = {
 	sm: "h-7 px-2.5 text-xs",
 	md: "h-9 px-3.5 text-sm",
+	/** 44px square — the touch-target floor (HIG 44 / Material 48-ish). For an
+	 *  icon-only control; a control carrying a text label should size itself
+	 *  with `md` plus an explicit `min-h-11` instead of stretching to square. */
+	touch: "h-11 w-11 text-sm",
 };
 
 export function Button({

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/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/primitives.stories.tsx

@@ -30,6 +30,12 @@ export const Buttons: Story = {
 			<Button variant="primary" disabled>
 				Disabled
 			</Button>
+			<Button
+				variant="ghost"
+				size="touch"
+				icon={<Mail className="size-4" />}
+				aria-label="Touch-sized icon button"
+			/>
 		</div>
 	),
 };

package/src/components/progress-bar.render.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ProgressBar } from "./progress-bar.js";
+
+describe("ProgressBar", () => {
+	it("renders progressbar role with the aria value triad", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 1200, max: 3412 }),
+		);
+		assert.match(html, /role="progressbar"/);
+		assert.match(html, /aria-valuenow="1200"/);
+		assert.match(html, /aria-valuemin="0"/);
+		assert.match(html, /aria-valuemax="3412"/);
+	});
+
+	it("computes the fill width as a percentage of value/max", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 25, max: 100 }),
+		);
+		assert.match(html, /width:25%/);
+	});
+
+	it("clamps the fill at 100% when value exceeds max", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 500, max: 100 }),
+		);
+		assert.match(html, /width:100%/);
+	});
+
+	it("omits the aria value triad when indeterminate", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 0, max: 0, indeterminate: true }),
+		);
+		assert.doesNotMatch(html, /aria-valuenow/);
+		assert.doesNotMatch(html, /aria-valuemax/);
+	});
+
+	it("applies the tone's fill color", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 1, max: 2, tone: "danger" }),
+		);
+		assert.match(html, /bg-danger/);
+	});
+});

package/src/components/progress-bar.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ProgressBar } from "./progress-bar.js";
+
+const meta: Meta<typeof ProgressBar> = {
+	title: "Components/ProgressBar",
+	component: ProgressBar,
+	parameters: { layout: "padded" },
+	render: (args) => (
+		<div className="w-80">
+			<ProgressBar {...args} />
+		</div>
+	),
+};
+export default meta;
+
+type Story = StoryObj<typeof ProgressBar>;
+
+export const Started: Story = { args: { value: 340, max: 3412 } };
+
+export const Halfway: Story = { args: { value: 1706, max: 3412 } };
+
+export const NearlyDone: Story = { args: { value: 3072, max: 3412 } };
+
+export const Success: Story = {
+	args: { value: 3412, max: 3412, tone: "success" },
+};
+
+export const Danger: Story = {
+	args: { value: 1200, max: 3412, tone: "danger" },
+};
+
+/** Total is unknown — a paging search count, before the first page resolves. */
+export const Indeterminate: Story = {
+	args: { value: 0, max: 0, indeterminate: true },
+};

package/src/components/progress-bar.tsx

@@ -0,0 +1,62 @@
+import { cn } from "../lib/cn.js";
+import type { BannerTone } from "./banner.js";
+
+export interface ProgressBarProps {
+	/** Units completed so far. Ignored when `indeterminate`. */
+	value: number;
+	/** Total units. Ignored when `indeterminate`. */
+	max: number;
+	tone?: BannerTone;
+	/** Unknown total (or unknown rate) — an animated fill with no fixed end. */
+	indeterminate?: boolean;
+	className?: string;
+}
+
+const tones: Record<BannerTone, string> = {
+	info: "bg-accent-2",
+	success: "bg-positive",
+	warning: "bg-warning",
+	danger: "bg-danger",
+};
+
+/**
+ * Determinate (or indeterminate) progress meter for a bulk operation, e.g. a
+ * multi-thousand-message delete running in batches. A bare running count
+ * gives no sense of rate over a long operation; a filling bar answers "is
+ * this stuck?" pre-attentively.
+ */
+export function ProgressBar({
+	value,
+	max,
+	tone = "info",
+	indeterminate = false,
+	className,
+}: ProgressBarProps) {
+	const pct = indeterminate
+		? 100
+		: max <= 0
+			? 0
+			: Math.min(100, Math.max(0, (value / max) * 100));
+
+	return (
+		<div
+			role="progressbar"
+			aria-valuenow={indeterminate ? undefined : value}
+			aria-valuemin={indeterminate ? undefined : 0}
+			aria-valuemax={indeterminate ? undefined : max}
+			className={cn(
+				"h-1.5 w-full overflow-hidden rounded-full bg-surface-sunken",
+				className,
+			)}
+		>
+			<div
+				className={cn(
+					"h-full rounded-full transition-[width] duration-300 ease-out",
+					tones[tone],
+					indeterminate && "w-1/3 animate-pulse",
+				)}
+				style={indeterminate ? undefined : { width: `${pct}%` }}
+			/>
+		</div>
+	);
+}