@remit/web-client 0.0.86 → 0.0.87

package/src/lib/search-suggestions.test.ts

@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	activeSearchTerm,
+	applySearchSuggestion,
+	buildSearchSuggestions,
+	contactSuggestionValue,
+	SEARCH_SUGGESTION_LIMIT,
+	type SearchSuggestionData,
+	searchSuggestionRequest,
+} from "./search-suggestions.js";
+import { parseSearchTokens } from "./search-tokens.js";
+
+const DATA: SearchSuggestionData = {
+	mailboxes: [{ value: "Archive" }, { value: "Sent Items" }],
+	accounts: [{ value: "work" }, { value: "personal" }],
+	contacts: [
+		{
+			value: "alice@example.com",
+			label: "Alice Adams",
+			hint: "alice@example.com",
+		},
+		{ value: "bob@example.com" },
+	],
+};
+
+const values = (suggestions: readonly { value: string }[]): string[] =>
+	suggestions.map((s) => s.value);
+
+describe("activeSearchTerm", () => {
+	it("finds the term the caret sits in", () => {
+		const term = activeSearchTerm("invoice from:ali", 16);
+		assert.equal(term.raw, "from:ali");
+		assert.equal(term.start, 8);
+		assert.equal(term.end, 16);
+		assert.equal(term.name, "from");
+		assert.equal(term.value, "ali");
+	});
+
+	it("has no token name for a bare word", () => {
+		const term = activeSearchTerm("invoice", 4);
+		assert.equal(term.name, undefined);
+		assert.equal(term.raw, "invoice");
+	});
+
+	it("is an empty term at the caret when the caret is on whitespace", () => {
+		const term = activeSearchTerm("invoice ", 8);
+		assert.deepEqual(term, { start: 8, end: 8, raw: "" });
+	});
+
+	it("reads through a quoted value", () => {
+		const term = activeSearchTerm('in:"Sent It', 11);
+		assert.equal(term.name, "in");
+		assert.equal(term.value, "Sent It");
+	});
+
+	it("clamps a caret past the end of the query", () => {
+		assert.equal(activeSearchTerm("is:read", 99).name, "is");
+	});
+});
+
+describe("searchSuggestionRequest", () => {
+	it("asks for token names while a bare word is typed", () => {
+		assert.deepEqual(searchSuggestionRequest("inv", 3), {
+			kind: "token",
+			query: "inv",
+		});
+	});
+
+	it("names the lookup a committed token needs", () => {
+		assert.deepEqual(searchSuggestionRequest("from:ali", 8), {
+			kind: "value",
+			token: "from",
+			source: "contact",
+			query: "ali",
+		});
+		assert.deepEqual(searchSuggestionRequest("in:", 3), {
+			kind: "value",
+			token: "in",
+			source: "mailbox",
+			query: "",
+		});
+	});
+
+	it("asks for nothing on an unknown token", () => {
+		assert.equal(searchSuggestionRequest("label:urgent", 12), undefined);
+	});
+});
+
+describe("buildSearchSuggestions", () => {
+	it("offers the vocabulary on an empty query", () => {
+		const suggestions = buildSearchSuggestions("", 0);
+		assert.deepEqual(values(suggestions), [
+			"from:",
+			"subject:",
+			"category:",
+			"is:",
+			"has:",
+			"in:",
+			"account:",
+			"after:",
+			"before:",
+		]);
+	});
+
+	it("matches a bare word against token names", () => {
+		const suggestions = buildSearchSuggestions("cat", 3);
+		assert.ok(values(suggestions).includes("category:"));
+		assert.ok(values(suggestions).includes("category:personal"));
+	});
+
+	it("reaches a fixed value by the word the user knows", () => {
+		const suggestions = buildSearchSuggestions("unr", 3);
+		assert.equal(suggestions[0]?.value, "is:unread");
+		assert.equal(suggestions[0]?.label, "Unread");
+	});
+
+	it("offers a token's fixed values once its name is committed", () => {
+		const suggestions = buildSearchSuggestions("is:", 3);
+		assert.deepEqual(values(suggestions), [
+			"is:unread",
+			"is:read",
+			"is:starred",
+		]);
+	});
+
+	it("narrows fixed values against what has been typed", () => {
+		assert.deepEqual(values(buildSearchSuggestions("category:mar", 12)), [
+			"category:marketing",
+		]);
+	});
+
+	it("offers the mailboxes it was given for in:, quoted where needed", () => {
+		assert.deepEqual(values(buildSearchSuggestions("in:", 3, DATA)), [
+			"in:Archive",
+			'in:"Sent Items"',
+		]);
+	});
+
+	it("offers the accounts it was given for account:", () => {
+		assert.deepEqual(values(buildSearchSuggestions("account:wo", 10, DATA)), [
+			"account:work",
+		]);
+	});
+
+	it("offers contacts for from:, reading as the display name", () => {
+		const suggestions = buildSearchSuggestions("from:ali", 8, DATA);
+		assert.deepEqual(values(suggestions), ["from:alice@example.com"]);
+		assert.equal(suggestions[0]?.label, "Alice Adams");
+		assert.equal(suggestions[0]?.hint, "alice@example.com");
+	});
+
+	it("offers nothing for a token whose values are typed, not chosen", () => {
+		assert.deepEqual(buildSearchSuggestions("after:2024", 10, DATA), []);
+		assert.deepEqual(buildSearchSuggestions("subject:tax", 11, DATA), []);
+	});
+
+	it("offers nothing for an unknown token", () => {
+		assert.deepEqual(buildSearchSuggestions("label:urgent", 12, DATA), []);
+	});
+
+	it("leads with prefix matches", () => {
+		const suggestions = buildSearchSuggestions("account:per", 11, DATA);
+		assert.deepEqual(values(suggestions), ["account:personal"]);
+	});
+
+	it("caps the list", () => {
+		const mailboxes = Array.from({ length: 20 }, (_, i) => ({
+			value: `Folder${i}`,
+		}));
+		const suggestions = buildSearchSuggestions("in:", 3, { mailboxes });
+		assert.equal(suggestions.length, SEARCH_SUGGESTION_LIMIT);
+	});
+
+	it("completes the term the caret is in, not the last one", () => {
+		const suggestions = buildSearchSuggestions("is: from:bob", 3);
+		assert.deepEqual(values(suggestions), [
+			"is:unread",
+			"is:read",
+			"is:starred",
+		]);
+	});
+
+	it("offers terms that parse back to the token they came from", () => {
+		const suggestions = buildSearchSuggestions("in:", 3, DATA);
+		for (const suggestion of suggestions) {
+			const { tokens } = parseSearchTokens(suggestion.value, {
+				mailboxesByName: new Map([
+					["archive", "mailbox-1"],
+					["sent items", "mailbox-2"],
+				]),
+			});
+			assert.equal(tokens.length, 1, `${suggestion.value} did not parse`);
+		}
+	});
+});
+
+describe("applySearchSuggestion", () => {
+	it("replaces the term and leaves the caret past a completed token", () => {
+		const result = applySearchSuggestion("is:unr", 6, { value: "is:unread" });
+		assert.deepEqual(result, { query: "is:unread ", cursor: 10 });
+	});
+
+	it("keeps the caret on the value of a bare token name", () => {
+		const result = applySearchSuggestion("ca", 2, { value: "category:" });
+		assert.deepEqual(result, { query: "category:", cursor: 9 });
+	});
+
+	it("does not double the space before the next term", () => {
+		const result = applySearchSuggestion("is:unr tax", 6, {
+			value: "is:unread",
+		});
+		assert.deepEqual(result, { query: "is:unread tax", cursor: 10 });
+	});
+
+	it("leaves the rest of the query alone", () => {
+		const result = applySearchSuggestion("invoice in:arch", 15, {
+			value: 'in:"Sent Items"',
+		});
+		assert.equal(result.query, 'invoice in:"Sent Items" ');
+	});
+
+	it("inserts at the caret when there is no term there", () => {
+		const result = applySearchSuggestion("invoice ", 8, { value: "is:unread" });
+		assert.deepEqual(result, { query: "invoice is:unread ", cursor: 18 });
+	});
+});
+
+describe("contactSuggestionValue", () => {
+	it("reads as the display name over the address", () => {
+		assert.deepEqual(
+			contactSuggestionValue({
+				normalizedEmail: "alice@example.com",
+				displayName: "Alice Adams",
+			}),
+			{
+				value: "alice@example.com",
+				label: "Alice Adams",
+				hint: "alice@example.com",
+			},
+		);
+	});
+
+	it("is just the address when there is no display name", () => {
+		assert.deepEqual(contactSuggestionValue({ normalizedEmail: "b@ex.com" }), {
+			value: "b@ex.com",
+		});
+	});
+});

package/src/lib/search-suggestions.ts

@@ -0,0 +1,296 @@
+/**
+ * What to offer while a search query is being typed (#428 follow-up).
+ *
+ * The search box takes a vocabulary of `name:value` tokens (`lib/search-tokens.ts`)
+ * that nothing on screen announces, so the tokens are only useful to someone who
+ * already knows they exist. This turns the query and the caret into the list of
+ * completions for the term under the caret: token names while a bare word is
+ * being typed, that token's values once its name is committed.
+ *
+ * Pure functions over data passed in. Values that need looking up — folders,
+ * accounts, contacts — are supplied by the caller; `searchSuggestionRequest`
+ * says which lookup the current caret position needs, so a hook can fetch
+ * exactly that and nothing per keystroke. The address lookup for `from:` is the
+ * one the compose recipient field already uses
+ * (`addressOperationsSearchAddresses`); no new endpoint exists for this.
+ *
+ * The offer is a shortcut and never a constraint: nothing here rejects or
+ * rewrites what was typed, and a term with no matches leaves the plain text box
+ * it always was.
+ */
+
+import type { Suggestion } from "@remit/ui";
+import {
+	SEARCH_TOKEN_SPECS,
+	type SearchTokenName,
+	type SearchTokenSpec,
+	type SearchTokenValueSource,
+	searchTokenSpec,
+	searchTokenTerm,
+	splitSearchTerm,
+	splitSearchWords,
+} from "./search-tokens.js";
+
+/** How many suggestions the list shows at most. */
+export const SEARCH_SUGGESTION_LIMIT = 8;
+
+/** The term the caret sits in, and where it sits in the query. */
+export interface ActiveSearchTerm {
+	/** Index of the term's first character. */
+	start: number;
+	/** Index just past the term's last character. */
+	end: number;
+	/** The term exactly as typed. Empty when the caret is on whitespace. */
+	raw: string;
+	/** The token name typed before the colon, lower-cased. Absent for a bare word. */
+	name?: string;
+	/** What has been typed of the value, unquoted. Absent for a bare word. */
+	value?: string;
+}
+
+/**
+ * The term the caret is in. A caret on whitespace (or in an empty box) is an
+ * empty term at that position, so the caller still gets the vocabulary offered
+ * rather than nothing — whether to show it there is the UI's call.
+ */
+export function activeSearchTerm(
+	query: string,
+	cursor: number,
+): ActiveSearchTerm {
+	const caret = Math.max(0, Math.min(cursor, query.length));
+	const word = splitSearchWords(query).find(
+		(w) => caret >= w.start && caret <= w.end,
+	);
+	if (!word) return { start: caret, end: caret, raw: "" };
+	const parts = splitSearchTerm(word.raw);
+	if (!parts) return { start: word.start, end: word.end, raw: word.raw };
+	return {
+		start: word.start,
+		end: word.end,
+		raw: word.raw,
+		name: parts.name,
+		value: parts.value,
+	};
+}
+
+/** What the caret position needs offered: a token name, or one token's values. */
+export interface SearchSuggestionRequest {
+	kind: "token" | "value";
+	/** The token whose values are wanted, for a `value` request. */
+	token?: SearchTokenName;
+	/** Where those values come from, for a `value` request. */
+	source?: SearchTokenValueSource;
+	/** What has been typed of the name or the value. */
+	query: string;
+}
+
+/**
+ * The lookup the caret position calls for, so a hook fetches folders, accounts,
+ * or addresses only where they can be offered. `undefined` when the term is an
+ * unknown `foo:bar` — a token the vocabulary does not carry has no completions,
+ * and the term stays free text.
+ */
+export function searchSuggestionRequest(
+	query: string,
+	cursor: number,
+): SearchSuggestionRequest | undefined {
+	const term = activeSearchTerm(query, cursor);
+	if (term.name === undefined) return { kind: "token", query: term.raw };
+	const spec = searchTokenSpec(term.name);
+	if (!spec) return undefined;
+	return {
+		kind: "value",
+		token: spec.name,
+		source: spec.values,
+		query: term.value ?? "",
+	};
+}
+
+/** A value the caller looked up, ready to be offered for one token. */
+export interface SearchSuggestionValue {
+	value: string;
+	/** What the row reads. Defaults to the value. */
+	label?: string;
+	/** Secondary text — the address behind a display name, say. */
+	hint?: string;
+}
+
+/** The looked-up values available for the tokens that take them. */
+export interface SearchSuggestionData {
+	/** Folder names, for `in:`. */
+	mailboxes?: readonly SearchSuggestionValue[];
+	/** Account names, for `account:`. */
+	accounts?: readonly SearchSuggestionValue[];
+	/** Known addresses, for `from:` — the address search's results. */
+	contacts?: readonly SearchSuggestionValue[];
+}
+
+const SOURCE_DATA: Partial<
+	Record<SearchTokenValueSource, keyof SearchSuggestionData>
+> = {
+	mailbox: "mailboxes",
+	account: "accounts",
+	contact: "contacts",
+};
+
+const valuesFor = (
+	spec: SearchTokenSpec,
+	data: SearchSuggestionData,
+): readonly SearchSuggestionValue[] => {
+	if (spec.values === "fixed") return spec.options ?? [];
+	const key = SOURCE_DATA[spec.values];
+	// `date` and `text` values are typed, not chosen — a date has no list worth
+	// offering and free text has nothing to draw on.
+	return key ? (data[key] ?? []) : [];
+};
+
+const matchRank = (haystack: string, needle: string): number => {
+	if (needle === "") return 1;
+	const lower = haystack.toLowerCase();
+	if (lower.startsWith(needle)) return 0;
+	return lower.includes(needle) ? 1 : -1;
+};
+
+const rankOf = (needle: string, ...fields: (string | undefined)[]): number => {
+	let best = -1;
+	for (const field of fields) {
+		if (field === undefined) continue;
+		const rank = matchRank(field, needle);
+		if (rank < 0) continue;
+		if (best < 0 || rank < best) best = rank;
+	}
+	return best;
+};
+
+interface Ranked {
+	rank: number;
+	suggestion: Suggestion;
+}
+
+const take = (ranked: Ranked[]): Suggestion[] => {
+	const seen = new Set<string>();
+	return ranked
+		.filter((r) => r.rank >= 0)
+		.sort((a, b) => a.rank - b.rank)
+		.filter((r) => {
+			const key = r.suggestion.value.toLowerCase();
+			if (seen.has(key)) return false;
+			seen.add(key);
+			return true;
+		})
+		.slice(0, SEARCH_SUGGESTION_LIMIT)
+		.map((r) => r.suggestion);
+};
+
+const nameSuggestion = (spec: SearchTokenSpec): Suggestion => ({
+	value: `${spec.name}:`,
+	label: `${spec.name}:`,
+	hint: spec.label,
+});
+
+/**
+ * Token-name completions for a bare word: one row per token, `name:`, leaving
+ * the caret ready for the value.
+ *
+ * Once something is typed, a token whose values are a fixed vocabulary also
+ * offers each value whole — `is:unread` — so the words the user knows reach the
+ * token they belong to without knowing its name. On an empty box that expansion
+ * would bury the vocabulary under its own values, so the bare names stand alone.
+ */
+function tokenSuggestions(typed: string): Suggestion[] {
+	const needle = typed.trim().toLowerCase();
+	if (needle === "") return SEARCH_TOKEN_SPECS.map(nameSuggestion);
+	const ranked: Ranked[] = [];
+	for (const spec of SEARCH_TOKEN_SPECS) {
+		ranked.push({
+			rank: rankOf(needle, `${spec.name}:`, spec.label),
+			suggestion: nameSuggestion(spec),
+		});
+		if (spec.values !== "fixed") continue;
+		for (const option of spec.options ?? []) {
+			const term = searchTokenTerm(spec.name, option.value);
+			ranked.push({
+				rank: rankOf(needle, term, option.label),
+				suggestion: { value: term, label: option.label ?? term, hint: term },
+			});
+		}
+	}
+	return take(ranked);
+}
+
+/**
+ * Value completions for a committed token name. Each offer is the whole term —
+ * `in:"Sent Items"`, quoted where the value needs it — so applying one is a
+ * replacement of the term under the caret and never a splice the caller has to
+ * quote itself.
+ */
+function valueSuggestions(
+	spec: SearchTokenSpec,
+	typed: string,
+	data: SearchSuggestionData,
+): Suggestion[] {
+	const needle = typed.trim().toLowerCase();
+	const ranked = valuesFor(spec, data).map<Ranked>((option) => ({
+		rank: rankOf(needle, option.value, option.label),
+		suggestion: {
+			value: searchTokenTerm(spec.name, option.value),
+			label: option.label ?? option.value,
+			...(option.hint ? { hint: option.hint } : {}),
+		},
+	}));
+	return take(ranked);
+}
+
+/**
+ * The completions for the term under the caret. An unknown token name offers
+ * nothing: `foo:bar` is free text, and a list of guesses would suggest otherwise.
+ */
+export function buildSearchSuggestions(
+	query: string,
+	cursor: number,
+	data: SearchSuggestionData = {},
+): Suggestion[] {
+	const term = activeSearchTerm(query, cursor);
+	if (term.name === undefined) return tokenSuggestions(term.raw);
+	const spec = searchTokenSpec(term.name);
+	if (!spec) return [];
+	return valueSuggestions(spec, term.value ?? "", data);
+}
+
+/** A query and where the caret lands in it, after a suggestion is applied. */
+export interface AppliedSearchSuggestion {
+	query: string;
+	cursor: number;
+}
+
+/**
+ * Replace the term under the caret with the suggestion. A completed token gets a
+ * trailing space — the term is finished, the next one starts — while a bare
+ * `name:` does not, because the value still has to be typed.
+ */
+export function applySearchSuggestion(
+	query: string,
+	cursor: number,
+	suggestion: Suggestion,
+): AppliedSearchSuggestion {
+	const term = activeSearchTerm(query, cursor);
+	const complete = !suggestion.value.endsWith(":");
+	const followed = /\s/.test(query.slice(term.end, term.end + 1));
+	const insert =
+		complete && !followed ? `${suggestion.value} ` : suggestion.value;
+	return {
+		query: query.slice(0, term.start) + insert + query.slice(term.end),
+		cursor: term.start + insert.length + (complete && followed ? 1 : 0),
+	};
+}
+
+/** A contact as the address search returns it, as a suggestion value. */
+export const contactSuggestionValue = (address: {
+	normalizedEmail: string;
+	displayName?: string | null;
+}): SearchSuggestionValue => ({
+	value: address.normalizedEmail,
+	...(address.displayName
+		? { label: address.displayName, hint: address.normalizedEmail }
+		: {}),
+});

package/src/lib/search-token-index.test.ts

@@ -6,7 +6,9 @@ import type {
 } from "@remit/api-http-client/types.gen.ts";
 import {
 	buildAccountNameIndex,
+	buildAccountSuggestionValues,
 	buildMailboxNameIndex,
+	buildMailboxSuggestionValues,
 } from "./search-token-index.js";
 
 const account = (
@@ -110,3 +112,100 @@ describe("buildMailboxNameIndex", () => {
 		assert.deepEqual(buildMailboxNameIndex([]), new Map());
 	});
 });
+
+describe("buildMailboxSuggestionValues", () => {
+	it("offers the leaf when no other folder shares it", () => {
+		const [offer] = buildMailboxSuggestionValues([
+			[mailbox({ mailboxId: "mb-1", fullPath: "INBOX/Archive" })],
+		]);
+		assert.equal(offer?.value, "Archive");
+		assert.equal(offer?.label, "Archive");
+	});
+
+	it("offers the full path where the leaf would be ambiguous", () => {
+		const offers = buildMailboxSuggestionValues([
+			[mailbox({ mailboxId: "mb-1", fullPath: "INBOX/Archive" })],
+			[mailbox({ mailboxId: "mb-2", fullPath: "Work/archive" })],
+		]);
+		assert.deepEqual(
+			offers.map((offer) => offer.value),
+			["INBOX/Archive", "Work/archive"],
+		);
+	});
+
+	it("every offer resolves back through the index it was built beside", () => {
+		const lists = [
+			[
+				mailbox({ mailboxId: "mb-1", fullPath: "INBOX" }),
+				mailbox({ mailboxId: "mb-2", fullPath: "INBOX/Archive" }),
+			],
+			[mailbox({ mailboxId: "mb-3", fullPath: "Team/Archive" })],
+		];
+		const index = buildMailboxNameIndex(lists);
+		for (const offer of buildMailboxSuggestionValues(lists)) {
+			assert.ok(index.has(offer.value.toLowerCase()), offer.value);
+		}
+	});
+
+	it("reads the folder's own name, a rename winning over the path", () => {
+		const [offer] = buildMailboxSuggestionValues([
+			[
+				mailbox({
+					mailboxId: "mb-1",
+					fullPath: "INBOX/Archief",
+					displayNameOverride: " Archive ",
+				}),
+			],
+		]);
+		assert.equal(offer?.value, "Archief");
+		assert.equal(offer?.label, "Archive");
+	});
+
+	it("names the account only where more than one is loaded", () => {
+		const lists = [[mailbox({ mailboxId: "mb-1", fullPath: "Archive" })]];
+		const accounts = [
+			account({ accountId: "account-1", email: "me@example.com" }),
+		];
+		assert.equal(
+			buildMailboxSuggestionValues(lists, accounts)[0]?.hint,
+			undefined,
+		);
+		assert.equal(
+			buildMailboxSuggestionValues(lists, [
+				...accounts,
+				account({ accountId: "account-2", email: "work@example.com" }),
+			])[0]?.hint,
+			"me@example.com",
+		);
+	});
+});
+
+describe("buildAccountSuggestionValues", () => {
+	it("offers the local part, read as the account's own name", () => {
+		const [offer] = buildAccountSuggestionValues([
+			account({
+				accountId: "acct-1",
+				email: "work@company.com",
+				displayName: "Work",
+			}),
+		]);
+		assert.equal(offer?.value, "work");
+		assert.equal(offer?.label, "Work");
+		assert.equal(offer?.hint, "work@company.com");
+	});
+
+	it("offers the whole address where the local part is ambiguous", () => {
+		const offers = buildAccountSuggestionValues([
+			account({ accountId: "acct-1", email: "work@company.com" }),
+			account({ accountId: "acct-2", email: "work@other.com" }),
+		]);
+		assert.deepEqual(
+			offers.map((offer) => offer.value),
+			["work@company.com", "work@other.com"],
+		);
+		assert.deepEqual(
+			offers.map((offer) => offer.label),
+			["work@company.com", "work@other.com"],
+		);
+	});
+});