@remit/web-client 0.0.85 → 0.0.87

package/src/hooks/useSearchFilterSeed.ts

@@ -2,11 +2,18 @@ import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-clien
 import { useMutation } from "@tanstack/react-query";
 import { useCallback, useEffect } from "react";
 import { buildOrganizeInput } from "@/lib/organize/organize-model";
+import { isEvaluablePredicate } from "@/lib/organize/rule-model";
 import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
 
 interface SearchFilterSeed {
 	/** The live count for the converted literal predicate, seeding the editor. */
 	seedCount?: number;
+	/**
+	 * The converted predicate is one the vector-free matcher refuses — a free-text
+	 * search kept as a `HasWords` clause. There is no count to seed and no request
+	 * to make.
+	 */
+	uncountable: boolean;
 	isPending: boolean;
 	isError: boolean;
 	error: unknown;
@@ -18,6 +25,14 @@ interface SearchFilterSeed {
  * literal predicate. One `POST /organize/preview` under the account the filter
  * targets — the count on screen is the set a literal-only filter applies to.
  *
+ * A search whose terms convert to a `HasWords` clause has no count to seed: the
+ * vector-free matcher reads no message bodies and rejects the predicate outright
+ * (`assertNoBodyContentClause`), so asking is a 500 and a 500 is not a count.
+ * That search is still a legitimate standing filter — the index-time matcher
+ * does read bodies — so the editor opens on the uncountable reason and holds only
+ * the one-time apply, the same way {@link useRulePreview} handles the clause
+ * being added by hand.
+ *
  * The deployment's semantic reach is not probed here; it is read from the
  * search's own "Related" results on the surface that opens the editor (RFC 038
  * D5), a direct signal that needs no request and cannot hit the wrong account.
@@ -28,9 +43,10 @@ export const useSearchFilterSeed = (
 ): SearchFilterSeed => {
 	const seed = useMutation(organizeOperationsPreviewOrganizeMutation());
 	const { mutate, reset } = seed;
+	const countable = isEvaluablePredicate(literalPredicate);
 
 	const run = useCallback(() => {
-		if (!accountId) return;
+		if (!accountId || !countable) return;
 		reset();
 		mutate({
 			path: { accountId },
@@ -41,6 +57,7 @@ export const useSearchFilterSeed = (
 		});
 	}, [
 		accountId,
+		countable,
 		literalPredicate.matchOperator,
 		literalPredicate.literalClauses,
 		mutate,
@@ -53,8 +70,9 @@ export const useSearchFilterSeed = (
 
 	return {
 		seedCount: seed.data?.matchedCount,
-		isPending: seed.isPending || seed.data === undefined,
-		isError: seed.isError,
+		uncountable: !countable,
+		isPending: countable && (seed.isPending || seed.data === undefined),
+		isError: countable && seed.isError,
 		error: seed.error,
 		retry: run,
 	};

package/src/hooks/useSearchSuggestions.ts

@@ -0,0 +1,126 @@
+/**
+ * What the search box offers for the term under the caret (#428 follow-up).
+ *
+ * The decisions are all in `lib/search-suggestions.ts`; this is the wiring that
+ * gets them their data. A caret position names exactly one lookup — token names
+ * for a bare word, one token's values once its name is committed — so only that
+ * lookup runs, and the address search behind `from:` runs on a debounce rather
+ * than per keystroke.
+ *
+ * Folders and accounts are already loaded: the mailbox lists come from the same
+ * per-account query `useMailboxNameIndex` and `useResultFolderIndex` take, on
+ * the same key with the same infinite stale time, so react-query serves them
+ * from cache and nothing is fetched a second time.
+ *
+ * `in:` is offered only where the route resolves it. On a scoped view the parser
+ * leaves the token as free text (see `useSearchTokenContext`), so offering
+ * folders there would advertise a filter that does nothing.
+ */
+import {
+	addressOperationsSearchAddressesOptions,
+	mailboxOperationsListMailboxesOptions,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { Suggestion } from "@remit/ui";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { useSearchTokenContext } from "@/hooks/useSearchTokenContext";
+import { useMailContext } from "@/lib/mail-context";
+import {
+	buildSearchSuggestions,
+	contactSuggestionValue,
+	SEARCH_SUGGESTION_LIMIT,
+	searchSuggestionRequest,
+} from "@/lib/search-suggestions";
+import {
+	buildAccountSuggestionValues,
+	buildMailboxSuggestionValues,
+} from "@/lib/search-token-index";
+import { useDebouncedValue } from "./useDebouncedValue";
+
+/** How long typing settles before the address lookup fires. */
+export const SEARCH_CONTACT_DEBOUNCE_MS = 250;
+
+/** The shortest contact query worth a round-trip. */
+const MIN_CONTACT_QUERY_LENGTH = 2;
+
+export interface SearchSuggestionsInput {
+	/** The query exactly as typed. */
+	query: string;
+	/** Where the caret sits in it. */
+	cursor: number;
+	/** Offer nothing while the field is not being typed in. */
+	enabled: boolean;
+}
+
+export function useSearchSuggestions({
+	query,
+	cursor,
+	enabled,
+}: SearchSuggestionsInput): Suggestion[] {
+	const { accounts } = useMailContext();
+	const { mailboxesByName } = useSearchTokenContext();
+	const offersFolders = mailboxesByName !== undefined;
+
+	const request = enabled ? searchSuggestionRequest(query, cursor) : undefined;
+	const contactQuery =
+		request?.source === "contact" ? request.query.trim() : "";
+	const debouncedContactQuery = useDebouncedValue(
+		contactQuery,
+		SEARCH_CONTACT_DEBOUNCE_MS,
+	);
+	const { data: addresses } = useQuery({
+		...addressOperationsSearchAddressesOptions({
+			query: { q: debouncedContactQuery, limit: SEARCH_SUGGESTION_LIMIT },
+		}),
+		enabled: debouncedContactQuery.length >= MIN_CONTACT_QUERY_LENGTH,
+	});
+
+	const mailboxQueries = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+	});
+
+	const mailboxes = useMemo(
+		() =>
+			offersFolders
+				? buildMailboxSuggestionValues(
+						mailboxQueries.map(
+							(mailboxQuery) => mailboxQuery.data?.items ?? [],
+						),
+						accounts,
+					)
+				: [],
+		[offersFolders, mailboxQueries, accounts],
+	);
+	const accountValues = useMemo(
+		() => buildAccountSuggestionValues(accounts),
+		[accounts],
+	);
+	const contacts = useMemo(
+		() => (addresses?.items ?? []).map(contactSuggestionValue),
+		[addresses],
+	);
+
+	return useMemo(() => {
+		if (!enabled) return [];
+		const suggestions = buildSearchSuggestions(query, cursor, {
+			mailboxes,
+			accounts: accountValues,
+			contacts,
+		});
+		if (offersFolders) return suggestions;
+		return suggestions.filter((suggestion) => suggestion.value !== "in:");
+	}, [
+		enabled,
+		query,
+		cursor,
+		mailboxes,
+		accountValues,
+		contacts,
+		offersFolders,
+	]);
+}

package/src/hooks/useSemanticSearch.ts

@@ -6,7 +6,7 @@ import { useRouterState } from "@tanstack/react-router";
 import { useMailContext } from "@/lib/mail-context";
 import { normalizeSearchQuery } from "@/lib/search-query";
 import { semanticMailboxScope } from "@/lib/search-scope";
-import { parseSearchTokens } from "@/lib/search-tokens";
+import { parseSearchTokens, type SearchToken } from "@/lib/search-tokens";
 import { useSearchTokenContext } from "./useSearchTokenContext";
 
 /** Cap the "Related" section; the literal "Top matches" is the primary surface. */
@@ -22,6 +22,17 @@ const toCategoryParam = (
 		? (filterCategory as (typeof MessageCategory)[keyof typeof MessageCategory])
 		: undefined;
 
+/**
+ * `isRead` for the read-state tokens. `is:unread` and `is:read` are opposites,
+ * so a query carrying both asks for nothing; unread wins, being the narrower
+ * ask and the one the chips also offer.
+ */
+const readStateParam = (tokens: SearchToken[]): boolean | undefined => {
+	if (tokens.some((t) => t.type === "isUnread")) return false;
+	if (tokens.some((t) => t.type === "isRead")) return true;
+	return undefined;
+};
+
 interface UseSemanticSearchParams {
 	/**
 	 * Restrict results to a single mailbox. A mailbox route pins the scope to its
@@ -43,10 +54,11 @@ interface UseSemanticSearchParams {
  * chip means this engine respects it like every other. Disabled until the query
  * is non-empty so an empty field issues no request.
  *
- * Filter tokens (`has:attachment`, `is:unread`, `before:`/`after:`) parsed from
- * the query map onto the search API's own filter params. `from:` and
- * `account:` have no equivalent on `GET /search/semantic` (no sender or
- * account filter) — both still render as chips and narrow the literal engine,
+ * Filter tokens (`has:attachment`, `is:unread`/`is:read`, `is:starred`,
+ * `category:`, `before:`/`after:`) parsed from the query map onto the search
+ * API's own filter params. `from:`, `subject:` and `account:` have no
+ * equivalent on `GET /search/semantic` (no sender, subject or
+ * account filter) — all still render as chips and narrow the literal engine,
  * but never reach the semantic request (`account:` is a documented gap, see
  * doc/design/flows/06-search.md — the semantic index is per account config).
  * `in:` resolves to a mailboxId, so typing `in:archive` re-scopes the search
@@ -77,11 +89,17 @@ export function useSemanticSearch({
 	// to rank.
 	const enabled = freeText.length > 0;
 
-	const category = toCategoryParam(filterCategory);
+	// The chip wins over the token: it is the visible narrowing, and the two can
+	// only disagree when the user set both.
+	const categoryToken = tokens.find((t) => t.type === "category");
+	const category = toCategoryParam(filterCategory) ?? categoryToken?.category;
 	const hasAttachment = tokens.some((t) => t.type === "hasAttachment")
 		? true
 		: undefined;
-	const isRead = tokens.some((t) => t.type === "isUnread") ? false : undefined;
+	const hasStars = tokens.some((t) => t.type === "isStarred")
+		? true
+		: undefined;
+	const isRead = readStateParam(tokens);
 	const afterToken = tokens.find((t) => t.type === "after");
 	const beforeToken = tokens.find((t) => t.type === "before");
 	const inToken = tokens.find((t) => t.type === "in");
@@ -100,6 +118,7 @@ export function useSemanticSearch({
 				limit: SEMANTIC_RESULT_LIMIT,
 				...(category !== undefined ? { category } : {}),
 				...(hasAttachment !== undefined ? { hasAttachment } : {}),
+				...(hasStars !== undefined ? { hasStars } : {}),
 				...(isRead !== undefined ? { isRead } : {}),
 				...(afterToken ? { sentDateFrom: afterToken.epochSeconds } : {}),
 				...(beforeToken ? { sentDateTo: beforeToken.epochSeconds } : {}),

package/src/hooks/useThreadActions.ts

@@ -4,12 +4,13 @@
  * Delete, move, star and the compose requests (reply / reply-all / forward),
  * over the same mutation hooks the mailbox list uses. The mailbox view keys
  * them by its route; the brief and Flagged are cross-account, so they key by
- * the open thread's own `mailboxId` / `accountConfigId` (#149).
+ * the open thread's own `mailboxId` / `accountId` (#149).
  */
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
 import { useCallback, useState } from "react";
 import type { ComposeMode } from "@/components/compose/ComposeProvider";
 import { useDeleteMessages } from "@/hooks/useDeleteMessages";
+import { useMailboxAccount } from "@/hooks/useMailboxAccount";
 import { useMoveMessages } from "@/hooks/useMoveMessages";
 import { useThreadMessageIds } from "@/hooks/useThreadMessageIds";
 import { useToggleStar } from "@/hooks/useToggleStar";
@@ -42,7 +43,15 @@ export const useThreadActions = ({
 	onAfterOptimisticRemove,
 }: UseThreadActionsOptions): ThreadActions => {
 	const resolvedMailboxId = mailboxId ?? thread?.mailboxId;
-	const resolvedAccountId = accountId ?? thread?.accountConfigId;
+	// `accountConfigId` is the caller's own identity, not an account: every
+	// `/accounts/{accountId}/…` call made with it 404s. The row carries a real
+	// `accountId` only when it came from the unified listing, so anything else
+	// resolves through the mailbox cache.
+	const knownAccountId = accountId ?? thread?.accountId;
+	const { accountId: mailboxAccountId } = useMailboxAccount(
+		knownAccountId ? undefined : resolvedMailboxId,
+	);
+	const resolvedAccountId = knownAccountId ?? mailboxAccountId;
 	const threadMessageIds = useThreadMessageIds();
 
 	const { deleteMessages } = useDeleteMessages({

package/src/lib/brief.test.ts

@@ -433,6 +433,73 @@ describe("matchesSearchTokens", () => {
 		);
 	});
 
+	test("is:read requires isRead true", () => {
+		const isRead: SearchToken = { type: "isRead", raw: "is:read" };
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1", isRead: true }), [isRead]),
+			true,
+		);
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1", isRead: false }), [isRead]),
+			false,
+		);
+	});
+
+	test("is:starred requires starred true", () => {
+		const isStarred: SearchToken = { type: "isStarred", raw: "is:starred" };
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1", starred: true }), [isStarred]),
+			true,
+		);
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1" }), [isStarred]),
+			false,
+		);
+	});
+
+	test("subject: matches the subject, case-insensitively", () => {
+		const subject: SearchToken = {
+			type: "subject",
+			raw: "subject:roadmap",
+			value: "RoadMap",
+		};
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1", subject: "Q3 roadmap" }), [subject]),
+			true,
+		);
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "2", subject: "Invoice" }), [subject]),
+			false,
+		);
+	});
+
+	test("category: matches the row's category, unclassified included", () => {
+		const personal: SearchToken = {
+			type: "category",
+			raw: "category:personal",
+			value: "personal",
+			category: "personal",
+		};
+		const unclassified: SearchToken = {
+			type: "category",
+			raw: "category:unclassified",
+			value: "unclassified",
+			category: "uncategorized",
+		};
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "1", category: "personal" }), [personal]),
+			true,
+		);
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "2", category: "marketing" }), [personal]),
+			false,
+		);
+		assert.strictEqual(
+			matchesSearchTokens(row({ id: "3" }), [unclassified]),
+			true,
+		);
+	});
+
 	test("after:/before: compare against sentDate (ms)", () => {
 		const jan15 = row({
 			id: "1",

package/src/lib/brief.ts

@@ -54,7 +54,7 @@ export function toThreadRowData(
 	const suspicious = thread.authenticity?.dkimMismatch === true;
 	return {
 		id: thread.messageId,
-		accountId: thread.accountId ?? thread.accountConfigId,
+		accountId: thread.accountId,
 		mailboxId: thread.mailboxId,
 		fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
 		fromEmail: thread.fromEmail ?? "",
@@ -212,10 +212,20 @@ export function matchesSearchTokens(
 					t.fromName.toLowerCase().includes(needle)
 				);
 			}
+			case "subject":
+				return t.subject.toLowerCase().includes(token.value.toLowerCase());
+			// A row with no category is `uncategorized` — the pending state has a
+			// name (issue #45), so `category:unclassified` finds it.
+			case "category":
+				return (t.category ?? "uncategorized") === token.category;
 			case "hasAttachment":
 				return t.hasAttachment === true;
 			case "isUnread":
 				return !t.isRead;
+			case "isRead":
+				return t.isRead === true;
+			case "isStarred":
+				return t.starred === true;
 			case "after":
 				return t.sentDate != null && t.sentDate >= token.epochSeconds * 1000;
 			case "before":

package/src/lib/bulk-actions.ts

@@ -124,6 +124,35 @@ export const runChunkedAction = async (
 	return { done, failedIds, cancelled: false };
 };
 
+/**
+ * The same bounded run, adapted to the optimistic mutation hooks (#453).
+ *
+ * A selection is not always assembled by a surface that owns a progress bar —
+ * the daily brief's toolbar and sheet hand a raw id list to `useDeleteMessages`,
+ * `useMoveMessages`, `useToggleReadFor` and `useApplyLabel`, and select-all over
+ * a 200-row search would send all 200 in one call, which the endpoint rejects
+ * outright. Splitting the send inside those hooks puts the cap where the call is
+ * made, so every caller is covered by construction rather than by remembering.
+ *
+ * Each chunk is a full mutation of its own, so it keeps that hook's optimistic
+ * patch, rollback and error banner. The run stops at the first rejected chunk
+ * and reports nothing itself: the hook that owns the call has already raised it.
+ */
+export const runChunkedMutation = async (
+	ids: readonly string[],
+	send: (chunk: string[]) => Promise<unknown>,
+): Promise<void> => {
+	await runChunkedAction(
+		ids,
+		async (chunk) => {
+			await send(chunk);
+			return { successCount: chunk.length, failureCount: 0 };
+		},
+		() => {},
+		() => false,
+	);
+};
+
 export interface FetchIdsPageResult {
 	ids: string[];
 	continuationToken?: string;

package/src/lib/drafts.ts

@@ -56,7 +56,7 @@ export function toImapDraftRowData(
 ): ThreadRowData {
 	return {
 		id: thread.messageId,
-		accountId: thread.accountConfigId,
+		accountId: thread.accountId,
 		fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
 		fromEmail: thread.fromEmail ?? "",
 		subject: thread.subject ?? "(No subject)",

package/src/lib/organize/clause-suggestions.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	buildClauseSuggestions,
+	CLAUSE_SUGGESTION_LIMIT,
+	fieldTakesAddressSuggestions,
+	type KnownAddress,
+} from "./clause-suggestions";
+
+const selection: KnownAddress[] = [
+	{ email: "receipts@stripe.com", displayName: "Stripe", fromSelection: true },
+	{ email: "rides@lyft.com", fromSelection: true },
+];
+
+describe("fieldTakesAddressSuggestions", () => {
+	it("offers values for the address fields only", () => {
+		assert.equal(fieldTakesAddressSuggestions("From"), true);
+		assert.equal(fieldTakesAddressSuggestions("FromDomain"), true);
+		assert.equal(fieldTakesAddressSuggestions("Subject"), false);
+		assert.equal(fieldTakesAddressSuggestions("HasWords"), false);
+		assert.equal(fieldTakesAddressSuggestions("ListId"), false);
+	});
+});
+
+describe("buildClauseSuggestions", () => {
+	it("offers the selection's addresses before anything is typed", () => {
+		const suggestions = buildClauseSuggestions("From", "", selection);
+		assert.deepEqual(
+			suggestions.map((s) => s.value),
+			["receipts@stripe.com", "rides@lyft.com"],
+		);
+		assert.equal(suggestions[0].label, "Stripe");
+		assert.equal(suggestions[0].hint, "receipts@stripe.com");
+		assert.equal(suggestions[0].source, "selected");
+	});
+
+	it("leaves a free-text field with nothing to offer", () => {
+		assert.deepEqual(buildClauseSuggestions("Subject", "", selection), []);
+		assert.deepEqual(buildClauseSuggestions("HasWords", "str", selection), []);
+	});
+
+	it("collapses an address to its registrable domain for a domain clause", () => {
+		const suggestions = buildClauseSuggestions("FromDomain", "", [
+			{ email: "receipts@mail.stripe.com" },
+			{ email: "invoices@stripe.com" },
+			{ email: "rides@lyft.co.uk" },
+		]);
+		assert.deepEqual(
+			suggestions.map((s) => s.value),
+			["stripe.com", "lyft.co.uk"],
+		);
+	});
+
+	it("drops an address it cannot resolve a domain for", () => {
+		assert.deepEqual(
+			buildClauseSuggestions("FromDomain", "", [{ email: "postmaster" }]),
+			[],
+		);
+	});
+
+	it("matches on the typed text, against the address and the display name", () => {
+		assert.deepEqual(
+			buildClauseSuggestions("From", "stri", selection).map((s) => s.value),
+			["receipts@stripe.com"],
+		);
+		assert.deepEqual(
+			buildClauseSuggestions("From", "LYFT", selection).map((s) => s.value),
+			["rides@lyft.com"],
+		);
+	});
+
+	it("offers nothing when the typed value matches none of them", () => {
+		assert.deepEqual(buildClauseSuggestions("From", "nobody", selection), []);
+	});
+
+	it("drops an offer the user has already typed in full", () => {
+		assert.deepEqual(
+			buildClauseSuggestions("From", " Receipts@Stripe.com ", selection).map(
+				(s) => s.value,
+			),
+			[],
+		);
+	});
+
+	it("keeps the first occurrence of a repeated value, marking and all", () => {
+		const suggestions = buildClauseSuggestions("From", "", [
+			...selection,
+			{ email: "Receipts@stripe.com", displayName: "Stripe Billing" },
+		]);
+		assert.equal(suggestions.length, 2);
+		assert.equal(suggestions[0].source, "selected");
+		assert.equal(suggestions[0].label, "Stripe");
+	});
+
+	it("skips a blank address", () => {
+		assert.deepEqual(
+			buildClauseSuggestions("From", "", [{ email: "  " }, ...selection]).map(
+				(s) => s.value,
+			),
+			["receipts@stripe.com", "rides@lyft.com"],
+		);
+	});
+
+	it("caps the list so it stays a shortcut rather than a directory", () => {
+		const many: KnownAddress[] = Array.from({ length: 20 }, (_, index) => ({
+			email: `sender-${index}@example.com`,
+		}));
+		assert.equal(
+			buildClauseSuggestions("From", "", many).length,
+			CLAUSE_SUGGESTION_LIMIT,
+		);
+	});
+});

package/src/lib/organize/clause-suggestions.ts

@@ -0,0 +1,90 @@
+import type { ClauseField, Suggestion } from "@remit/ui";
+import { senderDomain } from "./sender-fallback";
+
+/**
+ * Values worth offering while a clause is being typed. The rule editor's value
+ * field used to be bare text entry, so a `From` clause meant recalling an
+ * address exactly and a `FromDomain` clause meant knowing what the matcher
+ * considers a registrable domain.
+ *
+ * The offer is a shortcut and never a constraint: nothing here can reject or
+ * rewrite what the user typed, and a field with no matches is the plain text box
+ * it always was.
+ */
+
+/** An address a suggestion can be built from. */
+export interface KnownAddress {
+	email: string;
+	displayName?: string;
+	/**
+	 * The address came off the messages the user selected, rather than a lookup.
+	 * These are the likeliest answers, so they lead the list and say where they
+	 * came from.
+	 */
+	fromSelection?: boolean;
+}
+
+/** How many suggestions the list shows at most. */
+export const CLAUSE_SUGGESTION_LIMIT = 8;
+
+/**
+ * Whether a clause field takes values that come from addresses. `Subject`,
+ * `HasWords`, and `ListId` are free text with nothing to draw on, and stay so.
+ */
+export const fieldTakesAddressSuggestions = (field: ClauseField): boolean =>
+	field === "From" || field === "FromDomain";
+
+const addressSuggestion = (address: KnownAddress): Suggestion => ({
+	value: address.email,
+	label: address.displayName ?? address.email,
+	...(address.displayName ? { hint: address.email } : {}),
+	...(address.fromSelection ? { source: "selected" } : {}),
+});
+
+const domainSuggestion = (address: KnownAddress): Suggestion | undefined => {
+	const domain = senderDomain(address.email);
+	if (domain === null) return undefined;
+	return {
+		value: domain,
+		...(address.fromSelection ? { source: "selected" } : {}),
+	};
+};
+
+const matches = (suggestion: Suggestion, query: string): boolean =>
+	suggestion.value.toLowerCase().includes(query) ||
+	(suggestion.label ?? "").toLowerCase().includes(query);
+
+/**
+ * The suggestions for one clause draft. `addresses` is given in priority order —
+ * the selection's own senders first — and duplicates collapse onto the first
+ * occurrence, so a selected address keeps its "selected" marking even when a
+ * lookup returns it too.
+ *
+ * An empty query offers the lot, which is what makes the selection's addresses
+ * available before a single key is pressed. A query that exactly matches an
+ * offer drops it: there is nothing left to shortcut.
+ */
+export const buildClauseSuggestions = (
+	field: ClauseField,
+	query: string,
+	addresses: readonly KnownAddress[],
+): Suggestion[] => {
+	if (!fieldTakesAddressSuggestions(field)) return [];
+	const needle = query.trim().toLowerCase();
+	const seen = new Set<string>();
+	const out: Suggestion[] = [];
+	for (const address of addresses) {
+		if (address.email.trim() === "") continue;
+		const suggestion =
+			field === "From" ? addressSuggestion(address) : domainSuggestion(address);
+		if (!suggestion) continue;
+		const key = suggestion.value.toLowerCase();
+		if (key === "" || seen.has(key)) continue;
+		seen.add(key);
+		if (key === needle) continue;
+		if (needle !== "" && !matches(suggestion, needle)) continue;
+		out.push(suggestion);
+		if (out.length === CLAUSE_SUGGESTION_LIMIT) break;
+	}
+	return out;
+};