@remit/ui 0.0.56 → 0.0.57

package/src/components/search-chip-input.tsx

@@ -1,6 +1,7 @@
 import { Search, X } from "lucide-react";
 import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { cn } from "../lib/cn.js";
+import type { ComboboxProps } from "../lib/use-suggest-list.js";
 import {
 	type ChipFocusTarget,
 	focusAfterRemoval,
@@ -21,6 +22,41 @@ export interface SearchChip {
 	tone?: SearchChipTone;
 }
 
+/**
+ * Where the caret must land, as one object per request. Identity is the signal —
+ * the field applies a request once and never again, so a caret the host asked
+ * for cannot fight the one the user moved afterwards.
+ */
+export interface SearchCaretRequest {
+	cursor: number;
+}
+
+/**
+ * The completion wiring a search field carries when its host offers suggestions
+ * for what is being typed.
+ *
+ * The host owns the list: what is on it, what picking one means, and where it
+ * renders — under the field, in flow, so a soft keyboard cannot hide what was
+ * typed. The field owns only the input element, and gives the host the three
+ * things that live there: where the caret is, first refusal on the keys the
+ * list uses, and the ARIA the combobox pattern needs.
+ *
+ * Keys go to the list before the field's own handling, so Escape closes the
+ * list and leaves the query standing; a second Escape clears it as always.
+ */
+export interface SearchFieldSuggest {
+	/** ARIA wiring for the input, from `useSuggestList`. */
+	comboboxProps: ComboboxProps;
+	/** Returns true when the list consumed the key and the field should stop. */
+	onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => boolean;
+	/** The caret moved — the host recomputes the term under it. */
+	onCaretChange: (cursor: number) => void;
+	/** Focus left or entered the field; an unfocused field offers nothing. */
+	onFocusChange?: (focused: boolean) => void;
+	/** Where to put the caret after the host applied a suggestion. */
+	caret?: SearchCaretRequest;
+}
+
 export interface SearchChipInputProps {
 	/**
 	 * The narrowing terms, in expression order. Chips are host-owned: this
@@ -71,6 +107,11 @@ export interface SearchChipInputProps {
 	inputId?: string;
 	/** Accessible name for the chip grid. */
 	chipsLabel?: string;
+	/**
+	 * Completions for what is being typed. Omit for a field that offers none;
+	 * see {@link SearchFieldSuggest} for what the field and the host each own.
+	 */
+	suggest?: SearchFieldSuggest;
 	className?: string;
 }
 
@@ -105,6 +146,12 @@ const isEditableTarget = (target: EventTarget | null): boolean => {
  *   - After a removal, focus lands on the chip that took its place, else the
  *     one before it, else the text input.
  *
+ * **Completions.** With `suggest`, the field reports its caret and hands the
+ * list first refusal on each key; the host builds the offer and renders it. The
+ * offer is a shortcut and never a constraint — nothing on the list can change
+ * what was typed, and a term with no matches leaves the plain text field this
+ * always is.
+ *
  * Removal is never keyboard-only: every chip carries a remove button, which is
  * what touch and soft-keyboard users need (a soft keyboard gives no reliable
  * Backspace-into-chip signal).
@@ -129,6 +176,7 @@ export const SearchChipInput = ({
 	size = "sm",
 	inputId,
 	chipsLabel = "Search filters",
+	suggest,
 	className,
 }: SearchChipInputProps) => {
 	// The field wraps itself in a <label for>, and `for` binds to the FIRST
@@ -169,6 +217,24 @@ export const SearchChipInput = ({
 		chipRefs.current[target]?.focus();
 	});
 
+	/** The caret request already honoured; a new object is a new request. */
+	const appliedCaret = useRef<SearchCaretRequest | undefined>(undefined);
+	useEffect(() => {
+		const request = suggest?.caret;
+		if (!request || request === appliedCaret.current) return;
+		appliedCaret.current = request;
+		const input = inputRef.current;
+		// Only while the field holds focus — applying a suggestion never takes the
+		// caret away from wherever the user has since gone.
+		if (!input || input.ownerDocument.activeElement !== input) return;
+		input.setSelectionRange(request.cursor, request.cursor);
+		suggest?.onCaretChange(request.cursor);
+	});
+
+	const reportCaret = (input: HTMLInputElement) => {
+		suggest?.onCaretChange(input.selectionStart ?? input.value.length);
+	};
+
 	const moveFocus = useCallback((target: ChipFocusTarget) => {
 		setFocusedChip(target);
 		pendingFocus.current = target;
@@ -197,6 +263,9 @@ export const SearchChipInput = ({
 	const handleInputKeyDown = useCallback(
 		(event: React.KeyboardEvent<HTMLInputElement>) => {
 			const input = event.currentTarget;
+			// The list gets the key first: while it is open, Escape closes it and the
+			// query stands, and Enter takes the highlighted completion.
+			if (suggest?.onKeyDown(event)) return;
 			const action = resolveChipInputKey({
 				key: event.key,
 				shiftKey: event.shiftKey,
@@ -221,7 +290,7 @@ export const SearchChipInput = ({
 					return;
 			}
 		},
-		[chips.length, value, clearQuery, moveFocus],
+		[chips.length, value, clearQuery, moveFocus, suggest],
 	);
 
 	const handleChipKeyDown = useCallback(
@@ -333,9 +402,22 @@ export const SearchChipInput = ({
 					autoComplete="off"
 					value={value}
 					tabIndex={focusedChip === null ? 0 : -1}
-					onChange={(e) => onChange(e.target.value)}
+					onChange={(e) => {
+						onChange(e.target.value);
+						reportCaret(e.target);
+					}}
 					onKeyDown={handleInputKeyDown}
-					onFocus={() => setFocusedChip(null)}
+					// Arrow keys and clicks move the caret without changing the text, and
+					// the term under it is what the list completes.
+					onKeyUp={(e) => reportCaret(e.currentTarget)}
+					onClick={(e) => reportCaret(e.currentTarget)}
+					onFocus={(e) => {
+						setFocusedChip(null);
+						suggest?.onFocusChange?.(true);
+						reportCaret(e.currentTarget);
+					}}
+					onBlur={() => suggest?.onFocusChange?.(false)}
+					{...suggest?.comboboxProps}
 					// Once the expression carries chips the field is self-describing; a
 					// placeholder there would read as another term.
 					placeholder={hasChips ? undefined : placeholder}

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

@@ -1,8 +1,8 @@
-import { Flag } from "lucide-react";
-import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
+import type { ThreadRowData } from "./app-shell-types.js";
 import { Badge } from "./badge.js";
 import { provenanceFolderLabel, type ResultFolder } from "./folder-role.js";
+import { ComfortableRowBody, comfortableRowClass } from "./message-row.js";
 
 export type SearchResultTone =
 	| "neutral"
@@ -14,6 +14,12 @@ export type SearchResultTone =
 export interface SearchResult {
 	id: string;
 	sender: string;
+	/**
+	 * Sender address. The avatar's color is keyed on it, so a message keeps the
+	 * same circle in a search result as in the list it came from. Absent for
+	 * semantic hits, whose index carries no address; those key on the name.
+	 */
+	senderEmail?: string;
 	subject: string;
 	snippet: string;
 	date: string;
@@ -58,35 +64,37 @@ export interface SearchResultRowProps {
 	showFolder?: boolean;
 }
 
-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;
+/**
+ * A search result as list-row data. The engines return less than a list row
+ * holds — no attachment flag, no thread count, no labels — so those fall away
+ * rather than being invented. The category is not mapped here: the search
+ * carries its own labelled chip, which the row renders in the badge slot.
+ */
+function searchResultRowData(result: SearchResult): ThreadRowData {
+	return {
+		id: result.id,
+		fromName: result.sender,
+		fromEmail: result.senderEmail ?? result.sender,
+		subject: result.subject,
+		snippet: result.snippet,
+		timeLabel: result.date,
+		isRead: !result.unread,
+		starred: result.flagged,
+		...(result.mailboxId ? { mailboxId: result.mailboxId } : {}),
+	};
 }
 
 /**
- * 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.
+ * One tappable search result — the same row the lists render.
+ *
+ * Search is a mode of the list, not a separate surface, so the row body is the
+ * shared `ComfortableRowBody`: the sender avatar, the unread dot, the star and
+ * the sender/subject/snippet rhythm all come from one implementation, and a
+ * message looks the same whether it was found or scrolled to. Everything only a
+ * search knows — the folder a row was read from, the search's own category
+ * chip, why a semantic hit matched and how strongly — rides in the row's badge
+ * slot. Presentational and prop-driven; the app supplies `onClick` and the
+ * optional `query` to bold literal matches.
  */
 export function SearchResultRow({
 	result,
@@ -102,61 +110,39 @@ export function SearchResultRow({
 		<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"
+			className={cn("group", comfortableRowClass({}), "border-b border-line")}
 		>
-			<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>
-				{folderLabel && (
-					<Badge tone="neutral" className="shrink-0">
-						{folderLabel}
-					</Badge>
-				)}
-				{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>
+			<ComfortableRowBody
+				thread={searchResultRowData(result)}
+				highlightQuery={query}
+				badge={
+					<>
+						{folderLabel && (
+							<Badge tone="neutral" className="shrink-0">
+								{folderLabel}
+							</Badge>
+						)}
+						{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>
+						)}
+					</>
+				}
+			/>
 		</button>
 	);
 }

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

@@ -22,6 +22,7 @@ const topMatches: SearchResult[] = [
 	{
 		id: "r1",
 		sender: "Stripe",
+		senderEmail: "receipts@stripe.com",
 		subject: "Your invoice for March is ready",
 		snippet: "Invoice #4821 — €149.00 paid on Visa ending 4242.",
 		date: "9:42",
@@ -31,6 +32,7 @@ const topMatches: SearchResult[] = [
 	{
 		id: "r2",
 		sender: "Hetzner Online",
+		senderEmail: "billing@hetzner.com",
 		subject: "Invoice 2026-03 available in your account",
 		snippet: "Dear customer, your invoice for the period is attached.",
 		date: "Mar 3",
@@ -39,6 +41,7 @@ const topMatches: SearchResult[] = [
 	{
 		id: "r3",
 		sender: "Anna de Vries",
+		senderEmail: "anna@devries.nl",
 		subject: "Re: Q1 invoice approval",
 		snippet: "Approved — can you forward the PDF invoice to finance?",
 		date: "Mar 1",
@@ -46,6 +49,10 @@ const topMatches: SearchResult[] = [
 	},
 ];
 
+/**
+ * Semantic hits. The index carries no sender address, so these rows have no
+ * `senderEmail` — their avatar keys on the display name instead.
+ */
 const related: SearchResult[] = [
 	{
 		id: "r5",
@@ -81,6 +88,7 @@ const crossFolderMatches: SearchResult[] = [
 	{
 		id: "x1",
 		sender: "Mollie",
+		senderEmail: "info@mollie.com",
 		subject: "Invoice 2026-02 — archived",
 		snippet: "Filed last month; payment already settled.",
 		date: "Feb 24",
@@ -90,6 +98,7 @@ const crossFolderMatches: SearchResult[] = [
 	{
 		id: "x2",
 		sender: "me",
+		senderEmail: "matthijs@example.com",
 		subject: "Re: invoice query",
 		snippet: "Attaching the invoice you asked for.",
 		date: "Feb 18",
@@ -98,6 +107,7 @@ const crossFolderMatches: SearchResult[] = [
 	{
 		id: "x4",
 		sender: "Accountant",
+		senderEmail: "jan@boekhouding.example",
 		subject: "Invoices for the quarter",
 		snippet: "The quarterly set, filed with the rest of the bookkeeping.",
 		date: "Jan 30",
@@ -113,6 +123,7 @@ const spamMatches: SearchResult[] = [
 	{
 		id: "s1",
 		sender: "billing@unknown-vendor.test",
+		senderEmail: "billing@unknown-vendor.test",
 		subject: "URGENT invoice attached",
 		snippet: "Wire the amount below within 24 hours to avoid suspension.",
 		date: "Feb 11",
@@ -121,6 +132,7 @@ const spamMatches: SearchResult[] = [
 	{
 		id: "s2",
 		sender: "invoices@pay-now.test",
+		senderEmail: "invoices@pay-now.test",
 		subject: "Outstanding invoice — final notice",
 		snippet: "Your account is overdue. Settle immediately.",
 		date: "Feb 4",

package/src/components/search-results.tsx

@@ -90,17 +90,29 @@ export interface SearchResultsProps {
 	 * affordance; a `disabledReason` renders it inert with the reason (a search of
 	 * only non-clause facets has nothing to convert).
 	 */
-	makeFilter?: { onClick: () => void; disabledReason?: string };
+	makeFilter?: MakeFilterActionProps;
 }
 
-/** "Make this a filter" — the conversion entry offered above active search results. */
-function MakeFilterButton({
-	onClick,
-	disabledReason,
-}: {
+export interface MakeFilterActionProps {
 	onClick: () => void;
+	/** Renders the action inert and states why, e.g. nothing in the query converts. */
 	disabledReason?: string;
-}) {
+}
+
+/**
+ * "Make this a filter" — the conversion entry offered while a search is active.
+ *
+ * A standalone row rather than a part of the results body, because a search is
+ * shown in more than one way: the read-only `SearchResults` panel, and a list
+ * view whose own rows narrow to the query. The affordance belongs to the search,
+ * not to either rendering, so the caller mounts it above whichever body is up and
+ * it stays put when the body swaps. `SearchResults` renders it inline as a
+ * convenience for callers that show only the panel.
+ */
+export function MakeFilterAction({
+	onClick,
+	disabledReason,
+}: MakeFilterActionProps) {
 	const disabled = disabledReason !== undefined;
 	return (
 		<div className="border-b border-line px-row-inset py-1.5">
@@ -275,7 +287,7 @@ export function SearchResults({
 		<SearchTokenChips tokens={tokens} />
 	);
 	const filterAction = makeFilter && (
-		<MakeFilterButton
+		<MakeFilterAction
 			onClick={makeFilter.onClick}
 			disabledReason={makeFilter.disabledReason}
 		/>

package/src/components/suggest-list.render.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { SuggestList, type SuggestListProps } from "./suggest-list.js";
+
+const noop = () => {};
+
+const render = (overrides: Partial<SuggestListProps> = {}) =>
+	renderToString(
+		createElement(SuggestList, {
+			id: "list",
+			suggestions: [
+				{
+					value: "receipts@stripe.com",
+					label: "Stripe",
+					hint: "receipts@stripe.com",
+					source: "selected",
+				},
+				{ value: "rides@lyft.com" },
+			],
+			activeIndex: -1,
+			optionId: (index: number) => `list-option-${index}`,
+			onPick: noop,
+			onHighlight: noop,
+			label: "From suggestions",
+			...overrides,
+		}),
+	);
+
+describe("SuggestList", () => {
+	it("renders nothing when there is nothing to suggest", () => {
+		assert.equal(render({ suggestions: [] }), "");
+	});
+
+	it("renders a labelled listbox of options", () => {
+		const html = render();
+		assert.match(html, /role="listbox"/);
+		assert.match(html, /aria-label="From suggestions"/);
+		assert.equal(html.match(/role="option"/g)?.length, 2);
+		assert.match(html, /id="list-option-0"/);
+	});
+
+	it("falls back to the value when a suggestion carries no label", () => {
+		assert.match(render(), /rides@lyft\.com/);
+	});
+
+	it("shows the hint and where a suggestion came from", () => {
+		const html = render();
+		assert.match(html, /Stripe/);
+		assert.match(html, /selected/);
+	});
+
+	it("marks only the highlighted option as selected", () => {
+		const html = render({ activeIndex: 1 });
+		assert.equal(html.match(/aria-selected="true"/g)?.length, 1);
+		assert.equal(html.match(/aria-selected="false"/g)?.length, 1);
+	});
+});

package/src/components/suggest-list.tsx

@@ -0,0 +1,96 @@
+import { cn } from "../lib/cn.js";
+
+export interface Suggestion {
+	/** The value the field takes when this option is picked. */
+	value: string;
+	/** What the row reads. Defaults to the value. */
+	label?: string;
+	/** Secondary text on the row — the address behind a display name, say. */
+	hint?: string;
+	/** Where the suggestion came from, when that is worth saying ("selected"). */
+	source?: string;
+}
+
+export interface SuggestListProps {
+	id: string;
+	suggestions: readonly Suggestion[];
+	/** The highlighted option, `-1` when the typed value is what stands. */
+	activeIndex: number;
+	optionId: (index: number) => string;
+	onPick: (suggestion: Suggestion) => void;
+	onHighlight: (index: number) => void;
+	/** Names the list for screen readers. */
+	label: string;
+	className?: string;
+}
+
+/**
+ * The suggestion listbox behind a typeahead field — markup only. The open state,
+ * the highlight, and the keyboard live in `useSuggestList`, so every typeahead in
+ * the app shares one behaviour and one look.
+ *
+ * The caller places it. Under the field in normal flow is the default worth
+ * reaching for on a surface a phone uses: it takes its own space rather than
+ * covering the field, so a soft keyboard cannot hide what was typed.
+ */
+export function SuggestList({
+	id,
+	suggestions,
+	activeIndex,
+	optionId,
+	onPick,
+	onHighlight,
+	label,
+	className,
+}: SuggestListProps) {
+	if (suggestions.length === 0) return null;
+	return (
+		<div
+			id={id}
+			role="listbox"
+			aria-label={label}
+			className={cn(
+				"max-h-44 overflow-y-auto rounded-md border border-line bg-surface py-1 shadow-sm",
+				className,
+			)}
+		>
+			{suggestions.map((suggestion, index) => (
+				<div
+					key={suggestion.value}
+					id={optionId(index)}
+					role="option"
+					// The combobox input keeps focus throughout and points at the
+					// highlighted option with aria-activedescendant; an option that took
+					// focus itself would close the soft keyboard mid-typing.
+					tabIndex={-1}
+					aria-selected={index === activeIndex}
+					className={cn(
+						"flex cursor-pointer items-baseline gap-2 px-3 py-2 text-sm text-fg",
+						index === activeIndex && "bg-accent-2-soft",
+					)}
+					// Pointer-down rather than click: the field must not lose focus and
+					// run its blur handling before the pick lands.
+					onMouseDown={(event) => {
+						event.preventDefault();
+						onPick(suggestion);
+					}}
+					onMouseEnter={() => onHighlight(index)}
+				>
+					<span className="min-w-0 flex-1 truncate">
+						{suggestion.label ?? suggestion.value}
+					</span>
+					{suggestion.hint && (
+						<span className="shrink-0 truncate text-2xs text-fg-subtle">
+							{suggestion.hint}
+						</span>
+					)}
+					{suggestion.source && (
+						<span className="shrink-0 text-2xs text-fg-subtle">
+							{suggestion.source}
+						</span>
+					)}
+				</div>
+			))}
+		</div>
+	);
+}