@remit/ui 0.0.1

package/src/components/search-bar.tsx

@@ -0,0 +1,118 @@
+import { Search, X } from "lucide-react";
+import { useCallback, useEffect, useRef } from "react";
+import { cn } from "../lib/cn.js";
+
+export interface SearchBarProps {
+	value: string;
+	onChange: (value: string) => void;
+	/**
+	 * Full clear (X button): the consumer resets the query AND any open thread
+	 * so the view returns to the plain list with nothing pre-opened (#538).
+	 */
+	onClear: () => void;
+	/**
+	 * Query-only clear (Esc key): resets just the query and leaves any open
+	 * thread untouched — one keypress, one effect (#489). Falls back to
+	 * `onClear` when omitted.
+	 */
+	onClearQuery?: () => void;
+	placeholder?: string;
+	/**
+	 * Bind the global "/" shortcut that focuses the field from anywhere on the
+	 * page. Defaults to true; set false where a page hosts more than one bar.
+	 */
+	globalFocusKey?: boolean;
+	/**
+	 * Show the inline clear (X) inside the field. Defaults to true. Set false in
+	 * the mobile takeover / collapsed header, where a single outer X owns
+	 * clear-and-close so there is exactly one X (Esc still clears the query).
+	 */
+	showClearButton?: boolean;
+}
+
+const isEditableTarget = (target: EventTarget | null): boolean => {
+	if (!(target instanceof HTMLElement)) return false;
+	return (
+		target.tagName === "INPUT" ||
+		target.tagName === "TEXTAREA" ||
+		target.isContentEditable
+	);
+};
+
+export const SearchBar = ({
+	value,
+	onChange,
+	onClear,
+	onClearQuery,
+	placeholder = "Search mail...",
+	globalFocusKey = true,
+	showClearButton = true,
+}: SearchBarProps) => {
+	const inputRef = useRef<HTMLInputElement>(null);
+	const clearQuery = onClearQuery ?? onClear;
+
+	const handleClear = useCallback(() => {
+		onClear();
+		inputRef.current?.focus();
+	}, [onClear]);
+
+	const handleKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLInputElement>) => {
+			if (event.key !== "Escape") return;
+			if (value) {
+				clearQuery();
+				return;
+			}
+			inputRef.current?.blur();
+		},
+		[value, clearQuery],
+	);
+
+	useEffect(() => {
+		if (!globalFocusKey) return;
+		const handleGlobalSlash = (event: KeyboardEvent) => {
+			if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey) {
+				return;
+			}
+			if (isEditableTarget(event.target)) return;
+			event.preventDefault();
+			inputRef.current?.focus();
+		};
+		window.addEventListener("keydown", handleGlobalSlash);
+		return () => window.removeEventListener("keydown", handleGlobalSlash);
+	}, [globalFocusKey]);
+
+	return (
+		<div className="relative w-full">
+			<Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-fg-muted pointer-events-none" />
+			<input
+				ref={inputRef}
+				id="mail-search"
+				name="q"
+				type="text"
+				aria-label="Search mail"
+				value={value}
+				onChange={(e) => onChange(e.target.value)}
+				onKeyDown={handleKeyDown}
+				placeholder={placeholder}
+				className={cn(
+					"w-full pl-9 pr-9 py-1.5 text-sm rounded-md",
+					"bg-surface-sunken/50 border border-transparent",
+					"focus:bg-canvas focus:border-line focus:outline-none focus:ring-2 focus:ring-ring",
+					"placeholder:text-fg-muted",
+					"transition-colors",
+				)}
+			/>
+			{value && showClearButton && (
+				<button
+					type="button"
+					onClick={handleClear}
+					className="absolute right-2 top-1/2 -translate-y-1/2 p-0.5 rounded hover:bg-surface-raised transition-colors"
+					aria-label="Clear search"
+				>
+					<X className="size-4 text-fg-muted" />
+				</button>
+			)}
+		</div>
+	);
+};

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

@@ -0,0 +1,139 @@
+import { Flag } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn.js";
+import { Badge } from "./badge.js";
+
+export type SearchResultTone =
+	| "neutral"
+	| "accent"
+	| "positive"
+	| "warning"
+	| "danger";
+
+export interface SearchResult {
+	id: string;
+	sender: string;
+	subject: string;
+	snippet: string;
+	date: string;
+	unread?: boolean;
+	flagged?: boolean;
+	category?: { label: string; tone?: SearchResultTone };
+	/**
+	 * The thread this result belongs to. Lets the consumer open the conversation
+	 * directly — even when the message isn't in the currently loaded list, which is
+	 * the case for semantic "Related" hits surfaced from anywhere in the mailbox.
+	 */
+	threadId?: string;
+	/** The mailbox the result lives in; paired with {@link threadId} to open it. */
+	mailboxId?: string;
+	/**
+	 * Why a semantic ("Related") hit matched — a plain-language label derived
+	 * from `matchedChunkType` (e.g. "body", "subject", "attachment"), so the user
+	 * understands why the result showed up. Absent for literal "Top matches"
+	 * rows, which match by construction.
+	 */
+	matchedChunkLabel?: string;
+	/** Relevance figure (0–1) from the semantic engine; rendered beside the chip. */
+	score?: number;
+}
+
+export interface SearchResultRowProps {
+	result: SearchResult;
+	onClick?: () => void;
+	/** When given, literal (case-insensitive) matches are bolded in subject/snippet. */
+	query?: string;
+}
+
+function highlight(text: string, query?: string): ReactNode {
+	const term = query?.trim();
+	if (!term) return text;
+	const lower = text.toLowerCase();
+	const needle = term.toLowerCase();
+	const parts: ReactNode[] = [];
+	let cursor = 0;
+	let match = lower.indexOf(needle, cursor);
+	let key = 0;
+	while (match !== -1) {
+		if (match > cursor) parts.push(text.slice(cursor, match));
+		parts.push(
+			<mark key={key++} className="bg-transparent font-semibold text-fg">
+				{text.slice(match, match + needle.length)}
+			</mark>,
+		);
+		cursor = match + needle.length;
+		match = lower.indexOf(needle, cursor);
+	}
+	if (cursor < text.length) parts.push(text.slice(cursor));
+	return parts;
+}
+
+/**
+ * One tappable search result. Mirrors the collapsed reading-pane row rhythm:
+ * sender + right-aligned date on the top line, the subject, then a one-line
+ * truncated snippet, with an optional category Badge and a flag indicator. The
+ * sender bolds when unread. Presentational and prop-driven; the app supplies
+ * `onClick` and the optional `query` to bold literal matches.
+ */
+export function SearchResultRow({
+	result,
+	onClick,
+	query,
+}: SearchResultRowProps) {
+	return (
+		<button
+			type="button"
+			onClick={onClick}
+			className="flex w-full flex-col gap-0.5 border-b border-line px-row-inset py-2.5 text-left transition-colors hover:bg-surface-sunken"
+		>
+			<div className="flex items-baseline gap-2">
+				<span
+					className={cn(
+						"min-w-0 flex-1 truncate text-sm",
+						result.unread
+							? "font-semibold text-fg"
+							: "font-medium text-fg-muted",
+					)}
+				>
+					{result.sender}
+				</span>
+				<span className="shrink-0 text-2xs text-fg-subtle tabular-nums">
+					{result.date}
+				</span>
+			</div>
+			<div className="flex items-center gap-1.5">
+				<span
+					className={cn(
+						"min-w-0 flex-1 truncate text-sm",
+						result.unread ? "text-fg" : "text-fg-muted",
+					)}
+				>
+					{highlight(result.subject, query)}
+				</span>
+				{result.flagged && (
+					<Flag className="size-3.5 shrink-0 fill-warning text-warning" />
+				)}
+			</div>
+			<div className="flex items-center gap-2">
+				<span className="min-w-0 flex-1 truncate text-xs text-fg-subtle">
+					{highlight(result.snippet, query)}
+				</span>
+				{result.category && (
+					<Badge tone={result.category.tone ?? "neutral"} className="shrink-0">
+						{result.category.label}
+					</Badge>
+				)}
+				{result.matchedChunkLabel && (
+					<Badge tone="neutral" className="shrink-0">
+						{`matched: ${result.matchedChunkLabel}`}
+					</Badge>
+				)}
+				{result.score != null && (
+					<span className="shrink-0 text-2xs text-fg-subtle tabular-nums">
+						{result.score.toFixed(2)}
+					</span>
+				)}
+			</div>
+		</button>
+	);
+}

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

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { SearchResult } from "./search-result-row.js";
+import { type SearchResultSection, SearchResults } from "./search-results.js";
+
+const noop = () => {};
+
+const result: SearchResult = {
+	id: "r1",
+	sender: "Stripe",
+	subject: "Your invoice for March is ready",
+	snippet: "Invoice #4821 paid.",
+	date: "9:42",
+};
+
+const sections: SearchResultSection[] = [
+	{ id: "results", label: "Results", results: [result] },
+];
+
+describe("SearchResults", () => {
+	it("renders the section header and matching rows for a query", () => {
+		const html = renderToString(
+			createElement(SearchResults, { value: "invoice", sections }),
+		);
+		assert.match(html, /Results/);
+		assert.match(html, /Stripe/);
+		assert.match(html, /for March is ready/);
+	});
+
+	it("shows recent searches when the query is empty", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "",
+				recentSearches: ["invoice march"],
+				onPickRecent: noop,
+			}),
+		);
+		assert.match(html, /Recent searches/);
+		assert.match(html, /invoice march/);
+	});
+
+	it("shows the empty state when a query matches nothing", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "asdfqwer",
+				sections: [{ id: "results", label: "Results", results: [] }],
+			}),
+		);
+		assert.match(html, /No matches for/);
+	});
+
+	it("renders the matched-chunk chip and score on a semantic hit", () => {
+		const semanticResult: SearchResult = {
+			...result,
+			matchedChunkLabel: "subject",
+			score: 0.87,
+		};
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections: [
+					{ id: "related", label: "Related", results: [semanticResult] },
+				],
+			}),
+		);
+		assert.match(html, /matched: subject/);
+		assert.match(html, /0\.87/);
+	});
+
+	it("renders removable filter-token chips above the sections", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice from:stripe.com",
+				sections,
+				tokens: [{ label: "From: stripe.com", onRemove: noop }],
+			}),
+		);
+		assert.match(html, /From: stripe\.com/);
+	});
+
+	it("omits the chip row when there are no tokens", () => {
+		const html = renderToString(
+			createElement(SearchResults, { value: "invoice", sections, tokens: [] }),
+		);
+		assert.doesNotMatch(html, /Remove filter/);
+	});
+});

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

@@ -0,0 +1,126 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import type { SearchResult } from "./search-result-row.js";
+import { type SearchResultSection, SearchResults } from "./search-results.js";
+
+/**
+ * Frames the body the way the desktop/tablet list pane does: a narrow column
+ * with its own scroll container, so the sticky section headers read correctly.
+ */
+const listPaneFrame: Decorator = (Story) => (
+	<div
+		className="overflow-y-auto rounded-lg border border-line bg-canvas"
+		style={{ width: 360, height: 640 }}
+	>
+		<Story />
+	</div>
+);
+
+const recentSearches = ["invoice march", "from: stripe", "flight confirmation"];
+
+const topMatches: SearchResult[] = [
+	{
+		id: "r1",
+		sender: "Stripe",
+		subject: "Your invoice for March is ready",
+		snippet: "Invoice #4821 — €149.00 paid on Visa ending 4242.",
+		date: "9:42",
+		unread: true,
+		category: { label: "Receipt", tone: "positive" },
+	},
+	{
+		id: "r2",
+		sender: "Hetzner Online",
+		subject: "Invoice 2026-03 available in your account",
+		snippet: "Dear customer, your invoice for the period is attached.",
+		date: "Mar 3",
+		category: { label: "Finance", tone: "accent" },
+	},
+	{
+		id: "r3",
+		sender: "Anna de Vries",
+		subject: "Re: Q1 invoice approval",
+		snippet: "Approved — can you forward the PDF invoice to finance?",
+		date: "Mar 1",
+		flagged: true,
+	},
+];
+
+const related: SearchResult[] = [
+	{
+		id: "r5",
+		sender: "QuickBooks",
+		subject: "Reminder: 2 invoices awaiting payment",
+		snippet: "You have outstanding invoices totalling €430.00.",
+		date: "Feb 20",
+		matchedChunkLabel: "body",
+		score: 0.92,
+	},
+	{
+		id: "r6",
+		sender: "noreply@vendor.io",
+		subject: "Overdue invoice notice",
+		snippet: "This invoice is now 14 days overdue. Please remit payment.",
+		date: "Feb 12",
+		matchedChunkLabel: "subject",
+		score: 0.81,
+	},
+];
+
+const resultSections: SearchResultSection[] = [
+	{ id: "top", label: "Top matches", results: topMatches },
+	{ id: "related", label: "Related", results: related },
+];
+
+const emptySections: SearchResultSection[] = [
+	{ id: "top", label: "Top matches", results: [] },
+];
+
+function Harness(props: Parameters<typeof SearchResults>[0]) {
+	const [value, setValue] = useState(props.value);
+	return <SearchResults {...props} value={value} onPickRecent={setValue} />;
+}
+
+const meta: Meta<typeof SearchResults> = {
+	title: "Kit/SearchResults",
+	component: SearchResults,
+	parameters: { layout: "centered" },
+	decorators: [listPaneFrame],
+};
+export default meta;
+
+type Story = StoryObj<typeof SearchResults>;
+
+/** The sectioned results the desktop list pane swaps in while a query is active. */
+export const Results: Story = {
+	render: () => <Harness value="invoice" sections={resultSections} />,
+};
+
+/** A query that matches nothing. */
+export const NoResults: Story = {
+	render: () => <Harness value="asdfqwer" sections={emptySections} />,
+};
+
+/** Results still loading. */
+export const Loading: Story = {
+	render: () => <Harness value="invoice" loading />,
+};
+
+/** Empty query: recent searches (the list pane shows the normal list instead). */
+export const Idle: Story = {
+	render: () => <Harness value="" recentSearches={recentSearches} />,
+};
+
+/** Typed filter tokens (`from:`, `has:attachment`, …) render as removable chips above the sections. */
+export const WithFilterTokens: Story = {
+	render: () => (
+		<Harness
+			value="invoice from:stripe.com has:attachment"
+			sections={resultSections}
+			tokens={[
+				{ label: "From: stripe.com", onRemove: () => {} },
+				{ label: "Has attachment", onRemove: () => {} },
+			]}
+		/>
+	),
+};

package/src/components/search-results.tsx

@@ -0,0 +1,215 @@
+import { ChevronDown, Clock } from "lucide-react";
+import { useState } from "react";
+import { cn } from "../lib/cn.js";
+import { type SearchResult, SearchResultRow } from "./search-result-row.js";
+import { SearchTokenChips } from "./search-token-chip.js";
+
+/** Rows shown before the "Show N more" expander kicks in. */
+const SECTION_ROW_CAP = 6;
+
+export interface SearchResultSection {
+	id: string;
+	label: string;
+	results: SearchResult[];
+	/** Seed the section-collapse state — lets a story render the header-only view. */
+	initialCollapsed?: boolean;
+}
+
+export interface SearchResultsProps {
+	/** The current query — narrows what's shown and bolds literal matches. */
+	value: string;
+	/** Recent searches shown when the query is empty. */
+	recentSearches?: string[];
+	onPickRecent?: (query: string) => void;
+	/** Grouped result sections (e.g. "Top matches", "Related"). */
+	sections?: SearchResultSection[];
+	loading?: boolean;
+	onSelectResult?: (result: SearchResult) => void;
+	/**
+	 * Active filter-token chips parsed from the query (`from:`, `has:attachment`,
+	 * …), removable. Rendered above the results/loading/empty states so they stay
+	 * visible whatever the query returns; omit or pass an empty array when the
+	 * query has no recognized tokens.
+	 */
+	tokens?: { label: string; onRemove: () => void }[];
+}
+
+/**
+ * One result section: a sticky header that collapses the section to just its
+ * label + count, and a "Show N more" control that reveals rows past the cap.
+ * Mirrors `BriefSection`'s header rhythm so search and the brief stay in lockstep
+ * without sharing data shapes. Always tappable — it never disables.
+ */
+function CollapsibleResultSection({
+	section,
+	query,
+	onSelectResult,
+}: {
+	section: SearchResultSection;
+	query?: string;
+	onSelectResult?: (result: SearchResult) => void;
+}) {
+	const [collapsed, setCollapsed] = useState(section.initialCollapsed ?? false);
+	const [expanded, setExpanded] = useState(false);
+
+	const overCap = section.results.length > SECTION_ROW_CAP;
+	const capped = !expanded && overCap;
+	const visible = capped
+		? section.results.slice(0, SECTION_ROW_CAP)
+		: section.results;
+	const hiddenCount = section.results.length - visible.length;
+
+	return (
+		<div>
+			<button
+				type="button"
+				aria-expanded={!collapsed}
+				onClick={() => setCollapsed((v) => !v)}
+				className="sticky top-0 z-10 flex h-section-row w-full items-center gap-1.5 border-b border-line bg-surface-sunken px-row-inset text-left transition-colors hover:bg-surface"
+			>
+				<span className="flex-1 text-2xs font-semibold uppercase tracking-wider text-fg-subtle">
+					{section.label}
+				</span>
+				<span className="text-2xs text-fg-subtle tabular-nums">
+					{section.results.length}
+				</span>
+				<ChevronDown
+					className={cn(
+						"size-3 shrink-0 text-fg-subtle transition-transform duration-200",
+						collapsed ? "rotate-0" : "rotate-180",
+					)}
+				/>
+			</button>
+			{!collapsed && (
+				<>
+					{visible.map((result) => (
+						<SearchResultRow
+							key={result.id}
+							result={result}
+							query={query}
+							onClick={
+								onSelectResult ? () => onSelectResult(result) : undefined
+							}
+						/>
+					))}
+					{overCap && (
+						<button
+							type="button"
+							onClick={() => setExpanded((v) => !v)}
+							className="flex w-full items-center justify-center border-b border-line px-row-inset py-1.5 text-2xs font-medium text-accent transition-colors hover:bg-surface"
+						>
+							{expanded ? "Show less" : `Show ${hiddenCount} more`}
+							{!expanded && <ChevronDown className="ml-1 size-3" />}
+						</button>
+					)}
+				</>
+			)}
+		</div>
+	);
+}
+
+/**
+ * The sectioned search-results body shared by the phone `MobileSearchView`
+ * takeover and the desktop/tablet list pane. It swaps between recent searches
+ * (empty query), a loading skeleton, an empty state, and the collapsible result
+ * 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.
+ */
+export function SearchResults({
+	value,
+	recentSearches,
+	onPickRecent,
+	sections,
+	loading,
+	onSelectResult,
+	tokens,
+}: SearchResultsProps) {
+	const hasQuery = value.trim().length > 0;
+	const hasResults = (sections ?? []).some(
+		(section) => section.results.length > 0,
+	);
+
+	if (!hasQuery) {
+		if (recentSearches && recentSearches.length > 0) {
+			return (
+				<div className="flex flex-col">
+					<h3 className="px-row-inset pb-1 pt-3 text-2xs font-semibold uppercase tracking-wide text-fg-subtle">
+						Recent searches
+					</h3>
+					{recentSearches.map((recent) => (
+						<button
+							key={recent}
+							type="button"
+							onClick={() => onPickRecent?.(recent)}
+							className="flex w-full items-center gap-2.5 border-b border-line px-row-inset py-2.5 text-left transition-colors hover:bg-surface-sunken"
+						>
+							<Clock className="size-4 shrink-0 text-fg-subtle" />
+							<span className="min-w-0 flex-1 truncate text-sm text-fg-muted">
+								{recent}
+							</span>
+						</button>
+					))}
+				</div>
+			);
+		}
+		return (
+			<p className="px-row-inset py-6 text-center text-sm text-fg-subtle">
+				Search across your mail by sender, subject or words in the message.
+			</p>
+		);
+	}
+
+	const chips = tokens && tokens.length > 0 && (
+		<SearchTokenChips tokens={tokens} />
+	);
+
+	if (loading) {
+		return (
+			<div className="flex flex-col">
+				{chips}
+				<div className="flex flex-col gap-3 px-row-inset py-4">
+					{[0, 1, 2, 3].map((row) => (
+						<div key={row} className="flex flex-col gap-1.5">
+							<div className="h-3 w-1/3 animate-pulse rounded bg-surface-sunken" />
+							<div className="h-3 w-2/3 animate-pulse rounded bg-surface-sunken" />
+							<div className="h-2.5 w-1/2 animate-pulse rounded bg-surface-sunken" />
+						</div>
+					))}
+				</div>
+			</div>
+		);
+	}
+
+	if (!hasResults) {
+		return (
+			<div className="flex flex-col">
+				{chips}
+				<div className="px-row-inset py-10 text-center">
+					<p className="text-sm font-medium text-fg">
+						No matches for &ldquo;{value}&rdquo;
+					</p>
+					<p className="mt-1 text-xs text-fg-subtle">
+						Try a different word, or adjust the filters above.
+					</p>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col">
+			{chips}
+			{sections
+				?.filter((section) => section.results.length > 0)
+				.map((section) => (
+					<CollapsibleResultSection
+						key={section.id}
+						section={section}
+						query={value}
+						onSelectResult={onSelectResult}
+					/>
+				))}
+		</div>
+	);
+}