@remit/web-client 0.0.17 → 0.0.19

package/src/lib/mail-route.ts

@@ -15,6 +15,7 @@
 /** A matched route, minimal shape needed for pane detection. */
 export interface MailRouteMatch {
 	routeId: string;
+	params?: Record<string, string | undefined>;
 }
 
 /** The leaf route ids the /mail shell branches on. */
@@ -42,3 +43,19 @@ export function isOutboxRoute(matches: readonly MailRouteMatch[]): boolean {
 export function isMailboxRoute(matches: readonly MailRouteMatch[]): boolean {
 	return matches.some((m) => m.routeId === MAIL_MAILBOX_ROUTE_ID);
 }
+
+/**
+ * Identity of the list view the shell is showing — one mailbox, the brief, the
+ * flagged list, or the outbox. Two locations share a key when they differ only
+ * in search params (opening a result, mirroring `q`), so opening a hit is not a
+ * view change while switching mailbox is. `lib/search-view.ts` re-seeds the
+ * search field whenever this changes.
+ */
+export function mailViewKey(matches: readonly MailRouteMatch[]): string {
+	const mailboxId = matches.find((m) => m.params?.mailboxId)?.params?.mailboxId;
+	if (mailboxId) return `${MAIL_MAILBOX_ROUTE_ID}:${mailboxId}`;
+	if (isFlaggedRoute(matches)) return MAIL_FLAGGED_ROUTE_ID;
+	if (isOutboxRoute(matches)) return MAIL_OUTBOX_ROUTE_ID;
+	if (isBriefRoute(matches)) return MAIL_BRIEF_ROUTE_ID;
+	return "";
+}

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

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { matchesOutboxSearch, outboxQueryIsUnsupported } from "./outbox-search";
+import { parseSearchTokens } from "./search-tokens";
+
+const row = {
+	subject: "Q3 Invoice",
+	fromAddress: "me@example.com",
+	fromName: "Me",
+	toAddresses: ["billing@acme.test"],
+	ccAddresses: ["accounts@acme.test"],
+};
+
+describe("matchesOutboxSearch", () => {
+	it("keeps every row when there is no query", () => {
+		assert.equal(matchesOutboxSearch(row, "   "), true);
+	});
+
+	it("matches the subject", () => {
+		assert.equal(matchesOutboxSearch(row, "invoice"), true);
+	});
+
+	it("matches a recipient", () => {
+		assert.equal(matchesOutboxSearch(row, "acme"), true);
+	});
+
+	it("matches the sender", () => {
+		assert.equal(matchesOutboxSearch(row, "me@example"), true);
+	});
+
+	it("requires every word, in any order and any field", () => {
+		assert.equal(matchesOutboxSearch(row, "invoice billing"), true);
+		assert.equal(matchesOutboxSearch(row, "invoice missing"), false);
+	});
+
+	it("drops a row that matches nothing", () => {
+		assert.equal(matchesOutboxSearch(row, "receipt"), false);
+	});
+
+	it("tolerates rows with absent fields", () => {
+		assert.equal(matchesOutboxSearch({}, "anything"), false);
+		assert.equal(matchesOutboxSearch({}, ""), true);
+	});
+
+	it("matches the free text of a query that also carries a token", () => {
+		// The token is dropped, but what the user typed alongside it still
+		// searches — the row is not lost to an operator the outbox can't serve.
+		const { freeText } = parseSearchTokens("Q3 from:billing");
+		assert.equal(matchesOutboxSearch(row, freeText), true);
+	});
+});
+
+describe("outboxQueryIsUnsupported", () => {
+	it("is true for a query that is only tokens", () => {
+		assert.equal(
+			outboxQueryIsUnsupported(parseSearchTokens("from:billing")),
+			true,
+		);
+	});
+
+	it("is false when free text survives the parse", () => {
+		assert.equal(
+			outboxQueryIsUnsupported(parseSearchTokens("Q3 from:billing")),
+			false,
+		);
+	});
+
+	it("is false for plain free text", () => {
+		assert.equal(outboxQueryIsUnsupported(parseSearchTokens("invoice")), false);
+	});
+
+	it("is false for an empty query", () => {
+		assert.equal(outboxQueryIsUnsupported(parseSearchTokens("")), false);
+	});
+});

package/src/lib/outbox-search.ts

@@ -0,0 +1,58 @@
+/**
+ * Query narrowing for the outbox list.
+ *
+ * The outbox is a small, fully-loaded client-side list of mail that has not
+ * left yet, so its search is a filter over the rows already in hand rather
+ * than a request. It matches what an outbox row shows — subject, recipients
+ * and sender — because that is what the user can see to search for.
+ *
+ * Filter tokens (`from:`, `is:unread`, dates) are not honored: an outbox row
+ * has no read state, no mailbox and no received date, so the operators have
+ * nothing to read. Only the free text narrows, so `Q3 from:billing` still
+ * matches on "Q3".
+ *
+ * A query made only of tokens asks for a filter this view cannot apply, and
+ * there is no free text left to fall back on. Rather than return every row as
+ * if the filter had been honored, that case returns nothing and the list says
+ * why — see `outboxQueryIsUnsupported`.
+ */
+import type { ParsedSearchQuery } from "./search-tokens";
+
+/** The outbox row fields a query is matched against. */
+export interface OutboxSearchRow {
+	subject?: string | null;
+	fromAddress?: string | null;
+	fromName?: string | null;
+	toAddresses?: readonly string[] | null;
+	ccAddresses?: readonly string[] | null;
+}
+
+export function matchesOutboxSearch(
+	row: OutboxSearchRow,
+	freeText: string,
+): boolean {
+	const needle = freeText.trim().toLowerCase();
+	if (needle.length === 0) return true;
+	const haystack = [
+		row.subject,
+		row.fromAddress,
+		row.fromName,
+		...(row.toAddresses ?? []),
+		...(row.ccAddresses ?? []),
+	]
+		.filter((value): value is string => typeof value === "string")
+		.join(" ")
+		.toLowerCase();
+	return needle
+		.split(/\s+/)
+		.every((word) => word.length === 0 || haystack.includes(word));
+}
+
+/**
+ * True when the query is nothing but filter tokens. The outbox can serve none
+ * of them, and matching on the empty free text left over would return every
+ * row — indistinguishable from a filter that matched everything.
+ */
+export function outboxQueryIsUnsupported(parsed: ParsedSearchQuery): boolean {
+	return parsed.tokens.length > 0 && parsed.freeText.trim().length === 0;
+}

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

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	MAIL_BRIEF_ROUTE_ID,
+	MAIL_FLAGGED_ROUTE_ID,
+	MAIL_MAILBOX_ROUTE_ID,
+	MAIL_OUTBOX_ROUTE_ID,
+} from "./mail-route";
+import {
+	isScopedRoute,
+	SEARCH_SCOPE_CHIP_ID,
+	scopeLabelForMailboxName,
+	searchScopeForRoute,
+} from "./search-scope";
+
+const matches = (routeId: string) => [{ routeId: "/mail" }, { routeId }];
+
+describe("searchScopeForRoute", () => {
+	it("gives the daily brief no scope — it is the global view", () => {
+		assert.deepEqual(searchScopeForRoute(matches(MAIL_BRIEF_ROUTE_ID)), {
+			kind: "global",
+		});
+	});
+
+	it("scopes a mailbox route to its sidebar label", () => {
+		assert.deepEqual(
+			searchScopeForRoute(matches(MAIL_MAILBOX_ROUTE_ID), "Spam"),
+			{
+				kind: "scoped",
+				chip: { id: SEARCH_SCOPE_CHIP_ID, label: "in:spam" },
+			},
+		);
+	});
+
+	it("is pending, not global, while the mailbox name resolves", () => {
+		// The list under the bar is already one mailbox. A chip reading a raw
+		// uuid is worse than no chip, but the field must not claim to search
+		// everything either.
+		assert.deepEqual(
+			searchScopeForRoute(matches(MAIL_MAILBOX_ROUTE_ID), null),
+			{ kind: "pending" },
+		);
+	});
+
+	it("scopes the starred view", () => {
+		const scope = searchScopeForRoute(matches(MAIL_FLAGGED_ROUTE_ID));
+		assert.equal(scope.kind === "scoped" && scope.chip.label, "is:starred");
+	});
+
+	it("scopes the outbox", () => {
+		const scope = searchScopeForRoute(matches(MAIL_OUTBOX_ROUTE_ID));
+		assert.equal(scope.kind === "scoped" && scope.chip.label, "in:outbox");
+	});
+
+	it("prefers the virtual views over a lingering mailbox name", () => {
+		const scope = searchScopeForRoute(matches(MAIL_OUTBOX_ROUTE_ID), "Spam");
+		assert.equal(scope.kind === "scoped" && scope.chip.label, "in:outbox");
+	});
+});
+
+describe("isScopedRoute", () => {
+	// This predicate decides whether a typed `in:` is recognized at all, so
+	// every route has to answer it the same way it answers for its chip: a
+	// route showing a scope chip must not also honour a competing typed term.
+	for (const routeId of [
+		MAIL_MAILBOX_ROUTE_ID,
+		MAIL_FLAGGED_ROUTE_ID,
+		MAIL_OUTBOX_ROUTE_ID,
+	]) {
+		it(`${routeId} carries a scope`, () => {
+			assert.equal(isScopedRoute(matches(routeId)), true);
+		});
+	}
+
+	it("the daily brief carries none", () => {
+		assert.equal(isScopedRoute(matches(MAIL_BRIEF_ROUTE_ID)), false);
+	});
+
+	it("agrees with the chip on every route", () => {
+		for (const routeId of [
+			MAIL_BRIEF_ROUTE_ID,
+			MAIL_MAILBOX_ROUTE_ID,
+			MAIL_FLAGGED_ROUTE_ID,
+			MAIL_OUTBOX_ROUTE_ID,
+		]) {
+			const scope = searchScopeForRoute(matches(routeId), "Spam");
+			assert.equal(
+				isScopedRoute(matches(routeId)),
+				scope.kind === "scoped",
+				`${routeId} disagrees about whether it has a scope`,
+			);
+		}
+	});
+});
+
+describe("scopeLabelForMailboxName", () => {
+	it("lower-cases so the chip reads like the operator it mimics", () => {
+		assert.equal(scopeLabelForMailboxName("Archive"), "in:archive");
+	});
+
+	it("quotes a multi-word folder so the chip stays one term", () => {
+		assert.equal(scopeLabelForMailboxName("Work  Stuff"), 'in:"work stuff"');
+	});
+});

package/src/lib/search-scope.ts

@@ -0,0 +1,114 @@
+/**
+ * The search scope is the route.
+ *
+ * Search is the app's search: one field in the top bar, and by default it
+ * covers everything. Navigating the sidebar narrows it, and the narrowing is
+ * shown as one chip in the field — `in:spam` while viewing Spam. The chip is
+ * derived from the active route, not parsed out of the typed text: the route
+ * decides which pane is mounted and which mail that pane reads, and the chip is
+ * that decision made visible. Navigating elsewhere replaces the chip because the
+ * route changed.
+ *
+ * Removing the chip means "search everything", which is the daily brief — the
+ * cross-account view whose scope is nothing. So removal is a navigation to
+ * `/mail/` carrying the query, not an edit of the query text.
+ *
+ * There is exactly one scope, and it is this one. A typed `in:` term is a
+ * second, competing answer to "which mailbox", so it is recognized only where
+ * there is no route scope to compete with — see `isScopedRoute` and
+ * `useSearchTokenContext`. Every engine parses the query through that one
+ * context, so a scoped view cannot show a chip for a term it is ignoring.
+ *
+ * Pure functions only. `useSearchScope` binds these to the router.
+ */
+import {
+	isBriefRoute,
+	isFlaggedRoute,
+	isMailboxRoute,
+	isOutboxRoute,
+	type MailRouteMatch,
+} from "./mail-route";
+
+/**
+ * Chip id of the scope chip. The top bar owns exactly one, so a fixed id is
+ * enough of a removal handle.
+ */
+export const SEARCH_SCOPE_CHIP_ID = "search-scope";
+
+export interface SearchScope {
+	id: string;
+	/** What the chip reads, e.g. `in:spam`. */
+	label: string;
+}
+
+/**
+ * What the field can say about its own scope.
+ *
+ * `pending` is the mailbox route before its name has loaded: the list under the
+ * bar is already one mailbox, so the field must not claim to search everything,
+ * but there is no name yet to put in a chip. It is a real third state, not a
+ * flavour of `global`.
+ */
+export type SearchScopeState =
+	| { kind: "global" }
+	| { kind: "pending" }
+	| { kind: "scoped"; chip: SearchScope };
+
+/**
+ * Render a mailbox name as an `in:` term. Lower-cased so it reads like the
+ * operator it mimics, and quoted when the name has whitespace so the chip
+ * stays one legible term.
+ */
+export function scopeLabelForMailboxName(name: string): string {
+	const collapsed = name.trim().replace(/\s+/g, " ").toLowerCase();
+	return /\s/.test(collapsed) ? `in:"${collapsed}"` : `in:${collapsed}`;
+}
+
+/**
+ * True on the routes whose pane reads one mailbox or one virtual collection.
+ * These carry a scope; the daily brief (and any route not recognized here) does
+ * not.
+ */
+export function isScopedRoute(matches: readonly MailRouteMatch[]): boolean {
+	return (
+		isFlaggedRoute(matches) || isOutboxRoute(matches) || isMailboxRoute(matches)
+	);
+}
+
+/**
+ * The scope of the active route.
+ *
+ * `mailboxName` is the sidebar's own label for the mailbox route (resolved by
+ * `useCurrentMailboxName`). Until it resolves the scope is `pending`: no chip,
+ * because a chip reading a raw uuid is worse than none, but not `global`
+ * either, because the list underneath is already narrowed.
+ */
+export function searchScopeForRoute(
+	matches: readonly MailRouteMatch[],
+	mailboxName?: string | null,
+): SearchScopeState {
+	if (isBriefRoute(matches)) return { kind: "global" };
+	if (isFlaggedRoute(matches)) {
+		return {
+			kind: "scoped",
+			chip: { id: SEARCH_SCOPE_CHIP_ID, label: "is:starred" },
+		};
+	}
+	if (isOutboxRoute(matches)) {
+		return {
+			kind: "scoped",
+			chip: { id: SEARCH_SCOPE_CHIP_ID, label: "in:outbox" },
+		};
+	}
+	if (isMailboxRoute(matches)) {
+		if (!mailboxName) return { kind: "pending" };
+		return {
+			kind: "scoped",
+			chip: {
+				id: SEARCH_SCOPE_CHIP_ID,
+				label: scopeLabelForMailboxName(mailboxName),
+			},
+		};
+	}
+	return { kind: "global" };
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Regression (#47): the search query must not survive a move to another
+ * mailbox. The /mail shell holds the field state and never unmounts between
+ * child routes, so without these rules the text — and the query it drives —
+ * followed the user from inbox to inbox.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { type MailRouteMatch, mailViewKey } from "./mail-route.js";
+import {
+	committedSearchQuery,
+	searchInputForView,
+	shouldMirrorQuery,
+} from "./search-view.js";
+
+const matches = (routeId: string, mailboxId?: string): MailRouteMatch[] => [
+	{ routeId: "__root__" },
+	{ routeId: "/mail" },
+	{ routeId, ...(mailboxId ? { params: { mailboxId } } : {}) },
+];
+
+describe("mailViewKey", () => {
+	it("distinguishes two mailboxes", () => {
+		assert.notEqual(
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+			mailViewKey(matches("/mail/$mailboxId", "archive-1")),
+		);
+	});
+
+	it("gives the same mailbox one key regardless of search params", () => {
+		assert.equal(
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+			mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+		);
+	});
+
+	it("separates the brief, flagged and outbox views", () => {
+		const keys = [
+			mailViewKey(matches("/mail/")),
+			mailViewKey(matches("/mail/flagged")),
+			mailViewKey(matches("/mail/outbox")),
+		];
+		assert.equal(new Set(keys).size, 3);
+	});
+});
+
+describe("searchInputForView", () => {
+	it("clears the field when the destination carries no query", () => {
+		assert.equal(
+			searchInputForView(
+				"/mail/$mailboxId:inbox-1",
+				"/mail/$mailboxId:arch",
+				"",
+			),
+			"",
+		);
+	});
+
+	it("leaves the field alone while the view stays the same", () => {
+		// Opening a result and the q-mirror both re-render on the same view; the
+		// user's in-flight typing must survive both.
+		assert.equal(
+			searchInputForView(
+				"/mail/$mailboxId:inbox-1",
+				"/mail/$mailboxId:inbox-1",
+				"",
+			),
+			undefined,
+		);
+	});
+
+	it("seeds from the destination's own query (deep link, saved search)", () => {
+		assert.equal(
+			searchInputForView("/mail/$mailboxId:inbox-1", "/mail/", "invoice"),
+			"invoice",
+		);
+	});
+});
+
+describe("committedSearchQuery", () => {
+	it("commits an empty field immediately, without waiting on the debounce", () => {
+		assert.equal(committedSearchQuery("", "stale query"), "");
+	});
+
+	it("debounces everything else", () => {
+		assert.equal(committedSearchQuery("inv", ""), "");
+		assert.equal(committedSearchQuery("invoice", "inv"), "inv");
+	});
+});
+
+describe("shouldMirrorQuery", () => {
+	it("writes a settled query the URL does not have yet", () => {
+		assert.equal(shouldMirrorQuery("invoice", "invoice", ""), true);
+	});
+
+	it("stays quiet once the URL already says it", () => {
+		assert.equal(shouldMirrorQuery("invoice", "invoice", "invoice"), false);
+	});
+
+	it("does not strip the query a deep link just arrived with", () => {
+		// The field is seeded from the URL and the debounce has not caught up, so
+		// the committed query is still the previous view's. Writing it would drop
+		// `q` for the length of the debounce — and with it the search the link
+		// asked for.
+		assert.equal(shouldMirrorQuery("invoice", "", "invoice"), false);
+	});
+
+	it("waits for the debounce while the user is still typing", () => {
+		assert.equal(shouldMirrorQuery("invoi", "inv", ""), false);
+	});
+});
+
+/**
+ * The three rules compose into the shell's behaviour (`routes/mail.tsx`): the
+ * field is re-seeded during render on a view change, and the mirror decides
+ * separately whether to write back. These check the composition, because the
+ * two ways search ends — a view change (#47) and the sidebar's own clear —
+ * both have to end it without ever writing over what the user is typing.
+ */
+interface Shell {
+	viewKey: string;
+	field: string;
+	debounced: string;
+	url: string;
+}
+
+/** One render of the shell for a location, returning the state it settles on. */
+const render = (shell: Shell, viewKey: string, url: string): Shell => {
+	const field =
+		viewKey === shell.viewKey
+			? shell.field
+			: (searchInputForView(shell.viewKey, viewKey, url) ?? shell.field);
+	return { ...shell, viewKey, field, url };
+};
+
+/** What the mirror effect would do after that render. */
+const mirror = (shell: Shell): Shell => {
+	const committed = committedSearchQuery(shell.field, shell.debounced);
+	if (!shouldMirrorQuery(shell.field, committed, shell.url)) return shell;
+	return { ...shell, url: committed };
+};
+
+const typing = (shell: Shell, text: string): Shell => ({
+	...shell,
+	field: text,
+});
+const settle = (shell: Shell): Shell => ({ ...shell, debounced: shell.field });
+
+describe("search across a view change", () => {
+	const searching: Shell = {
+		viewKey: mailViewKey(matches("/mail/$mailboxId", "inbox-1")),
+		field: "invoice",
+		debounced: "invoice",
+		url: "invoice",
+	};
+
+	it("ends the search when the user leaves the view", () => {
+		// The nav link drops `q`, so the destination carries none.
+		const next = mirror(
+			render(searching, mailViewKey(matches("/mail/$mailboxId", "sent-1")), ""),
+		);
+		assert.equal(next.field, "");
+		assert.equal(next.url, "");
+	});
+
+	it("does not put the query it just left onto the view it landed on", () => {
+		// The debounce still holds "invoice" for up to 200ms after the move. The
+		// mirror must not write it back — that is #47 returning by another route.
+		const landed = render(
+			searching,
+			mailViewKey(matches("/mail/$mailboxId", "sent-1")),
+			"",
+		);
+		assert.equal(landed.debounced, "invoice");
+		assert.equal(mirror(landed).url, "");
+	});
+
+	it("keeps a query the destination carries (scope chip removed)", () => {
+		// Dropping the scope chip navigates to the brief carrying the query, so
+		// the same words are searched with a wider scope.
+		const next = mirror(
+			render(searching, mailViewKey(matches("/mail/")), "invoice"),
+		);
+		assert.equal(next.field, "invoice");
+		assert.equal(next.url, "invoice");
+	});
+
+	it("never clobbers characters the user is still typing", () => {
+		// Opening a result and the q-mirror both re-render the same view. Neither
+		// is a view change, so neither may reach into the field.
+		const mailbox = mailViewKey(matches("/mail/$mailboxId", "inbox-1"));
+		let shell = typing(
+			{ ...searching, field: "", debounced: "", url: "" },
+			"i",
+		);
+		shell = mirror(render(shell, mailbox, shell.url));
+		shell = typing(shell, "inv");
+		shell = mirror(render(shell, mailbox, shell.url));
+		shell = typing(shell, "invoice");
+		shell = settle(mirror(render(shell, mailbox, shell.url)));
+		shell = mirror(render(shell, mailbox, shell.url));
+		assert.equal(shell.field, "invoice");
+		assert.equal(shell.url, "invoice");
+	});
+});

package/src/lib/search-view.ts

@@ -0,0 +1,54 @@
+/**
+ * Search is a view-level mode, not a persistent global filter (#47).
+ *
+ * The query belongs to the location it was typed in: the URL's `q` is what a
+ * view is searching for, and the nav links already drop `q` when they switch
+ * mailbox. The search field, however, is local state in the /mail shell — which
+ * outlives every child route — so it kept the old text and went on querying the
+ * new mailbox with it (the confusing Mac Mail behaviour). These rules make the
+ * URL win on every view change: the field re-seeds from the location it lands
+ * on, so switching mailbox clears a stale query while a deep link or a saved
+ * search that carries `q` still arrives with the query intact.
+ */
+
+/**
+ * The field text after a view transition, or `undefined` when nothing changes
+ * (same view — typing, opening a result, mirroring `q` back to the URL).
+ */
+export function searchInputForView(
+	previousViewKey: string,
+	viewKey: string,
+	urlQuery: string,
+): string | undefined {
+	if (previousViewKey === viewKey) return undefined;
+	return urlQuery;
+}
+
+/**
+ * The committed query the search APIs run. Typing debounces, but an empty field
+ * commits immediately — otherwise a view change fires one more request for the
+ * query the user just left behind.
+ */
+export function committedSearchQuery(
+	searchInput: string,
+	debouncedSearchInput: string,
+): string {
+	return searchInput === "" ? "" : debouncedSearchInput;
+}
+
+/**
+ * Whether the committed query may be written back to the URL. Only a settled
+ * one may: mid-debounce the committed value is the *previous* query, and
+ * writing it would overwrite the URL that a deep link or a saved search just
+ * arrived with — stripping `q` for as long as the debounce lasts, and taking
+ * the search with it. The mirror waits for the field and the committed query to
+ * agree, then writes only if the URL says something else.
+ */
+export function shouldMirrorQuery(
+	searchInput: string,
+	committedQuery: string,
+	urlQuery: string,
+): boolean {
+	if (committedQuery !== searchInput) return false;
+	return committedQuery !== urlQuery;
+}