@remit/web-client 0.0.324 → 0.0.326

package/src/lib/search-tokens.ts

@@ -1,319 +0,0 @@
-/**
- * Filter-token parser for the mail search field (#428). Recognizes a fixed set
- * of `word:value` tokens typed inline with the free-text query and turns them
- * into removable chips. Only tokens the search APIs can actually honor are
- * recognized — everything else is left untouched as ordinary free-text words.
- *
- * The vocabulary is the search parameters `threadOperationsSearchThreads`
- * takes, said in words:
- *
- * | token                  | thread search      |
- * | ---------------------- | ------------------ |
- * | `from:`                | `from`             |
- * | `subject:`             | `subject`          |
- * | `category:`            | `category[]`       |
- * | `is:unread` / `is:read`| `unread`           |
- * | `is:starred`           | `starred`          |
- * | `has:attachment`       | `attachments`      |
- * | `before:` / `after:`   | —                  |
- * | `in:`                  | route scope        |
- * | `account:`             | —                  |
- *
- * A token an engine has no parameter for is applied client-side over the rows
- * that engine returned (`matchesSearchTokens` in `lib/brief.ts`), never dropped.
- *
- * `in:<mailbox>` and `account:<name>` resolve against a name index the caller
- * supplies via `SearchTokenContext` (built from the loaded mailboxes/accounts —
- * see `lib/search-token-index.ts`). An unresolvable name (no index, or no
- * match in it) is left as free text rather than becoming a chip for a filter
- * that can't actually apply. `category:` resolves the same way against a fixed
- * vocabulary, so `category:nonsense` stays free text too.
- *
- * Token names are case-insensitive. Terms are cut from the query by
- * `search-query-words.ts` in the kit, which the brief's chips also write and
- * remove terms with, so a quoted value is one term to both.
- *
- * Pure functions only: no React, no fetch — the name index is injected, not
- * fetched here. `MailListHeader` renders the chips and the callers that issue
- * search requests (`MailboxPane`, `DailyBrief`, `FlaggedList`) apply the
- * parsed tokens to the params each engine's API actually supports.
- */
-
-import type { RemitImapMessageCategory } from "@remit/api-http-client/types.gen.ts";
-import { MessageCategory } from "@remit/domain-enums";
-import {
-	categoryLabels,
-	quoteSearchTokenValue,
-	type SearchQueryWord,
-	type SearchTermParts,
-	searchTokenTerm,
-	splitSearchTerm,
-	splitSearchWords,
-} from "@remit/ui";
-
-export {
-	quoteSearchTokenValue,
-	type SearchQueryWord,
-	type SearchTermParts,
-	searchTokenTerm,
-	splitSearchTerm,
-	splitSearchWords,
-};
-
-export type SearchToken =
-	| { type: "from"; raw: string; value: string }
-	| { type: "subject"; raw: string; value: string }
-	| {
-			type: "category";
-			raw: string;
-			value: string;
-			category: RemitImapMessageCategory;
-	  }
-	| { type: "hasAttachment"; raw: string }
-	| { type: "isUnread"; raw: string }
-	| { type: "isRead"; raw: string }
-	| { type: "isStarred"; raw: string }
-	| { type: "before"; raw: string; value: string; epochSeconds: number }
-	| { type: "after"; raw: string; value: string; epochSeconds: number }
-	| { type: "in"; raw: string; value: string; mailboxId: string }
-	| { type: "account"; raw: string; value: string; accountId: string };
-
-export interface ParsedSearchQuery {
-	/** The query text with every recognized token removed, whitespace collapsed. */
-	freeText: string;
-	tokens: SearchToken[];
-}
-
-/** Name lookups for resolving `in:`/`account:` tokens; see module doc. */
-export interface SearchTokenContext {
-	/** Mailbox name (fullPath or its last segment, lower-cased) -> mailboxId. */
-	mailboxesByName?: ReadonlyMap<string, string>;
-	/** Account name (email or its local-part, lower-cased) -> accountId. */
-	accountsByName?: ReadonlyMap<string, string>;
-}
-
-/** The word before the colon. `is`/`has` carry their meaning in the value. */
-export type SearchTokenName =
-	| "from"
-	| "subject"
-	| "category"
-	| "is"
-	| "has"
-	| "before"
-	| "after"
-	| "in"
-	| "account";
-
-/** One option of a token's fixed value vocabulary. */
-export interface SearchTokenValueOption {
-	value: string;
-	/** What the value reads as in prose. Defaults to the value. */
-	label?: string;
-}
-
-/**
- * Where a token's values come from. `fixed` is the vocabulary carried here;
- * the rest are looked up by the caller (mailboxes, accounts, the address
- * search) or typed freely.
- */
-export type SearchTokenValueSource =
-	| "fixed"
-	| "contact"
-	| "mailbox"
-	| "account"
-	| "date"
-	| "text";
-
-/** A token name, what it narrows by, and where its values come from. */
-export interface SearchTokenSpec {
-	name: SearchTokenName;
-	/** What the token narrows by, in the user's words. */
-	label: string;
-	values: SearchTokenValueSource;
-	/** The vocabulary, when `values` is `fixed`. */
-	options?: readonly SearchTokenValueOption[];
-}
-
-const CATEGORY_OPTIONS: readonly SearchTokenValueOption[] = Object.values(
-	MessageCategory,
-).map((value) => ({ value, label: categoryLabels[value] }));
-
-/**
- * Spellings that resolve to a category beyond the enum values themselves — the
- * label the chips show, so what the user reads is also what the user can type.
- */
-const CATEGORY_ALIASES: Record<string, RemitImapMessageCategory> = {
-	unclassified: "uncategorized",
-};
-
-/** The whole vocabulary, in the order a suggestion list offers it. */
-export const SEARCH_TOKEN_SPECS: readonly SearchTokenSpec[] = [
-	{ name: "from", label: "Sender", values: "contact" },
-	{ name: "subject", label: "Subject", values: "text" },
-	{
-		name: "category",
-		label: "Category",
-		values: "fixed",
-		options: CATEGORY_OPTIONS,
-	},
-	{
-		name: "is",
-		label: "State",
-		values: "fixed",
-		options: [
-			{ value: "unread", label: "Unread" },
-			{ value: "read", label: "Read" },
-			{ value: "starred", label: "Starred" },
-		],
-	},
-	{
-		name: "has",
-		label: "Contents",
-		values: "fixed",
-		options: [{ value: "attachment", label: "Has attachment" }],
-	},
-	{ name: "in", label: "Folder", values: "mailbox" },
-	{ name: "account", label: "Account", values: "account" },
-	{ name: "after", label: "Sent on or after", values: "date" },
-	{ name: "before", label: "Sent before", values: "date" },
-];
-
-const SPECS_BY_NAME = new Map<string, SearchTokenSpec>(
-	SEARCH_TOKEN_SPECS.map((spec) => [spec.name, spec]),
-);
-
-/** The spec for a token name, or `undefined` when the name is not one of ours. */
-export const searchTokenSpec = (name: string): SearchTokenSpec | undefined =>
-	SPECS_BY_NAME.get(name.toLowerCase());
-
-const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
-
-function parseDateToken(
-	type: "before" | "after",
-	raw: string,
-	value: string,
-): SearchToken | undefined {
-	if (!DATE_PATTERN.test(value)) return undefined;
-	const epochMs = Date.parse(`${value}T00:00:00Z`);
-	if (Number.isNaN(epochMs)) return undefined;
-	return { type, raw, value, epochSeconds: Math.floor(epochMs / 1000) };
-}
-
-/** The category a `category:` value names, by enum value or by chip label. */
-export function resolveCategory(
-	value: string,
-): RemitImapMessageCategory | undefined {
-	const lower = value.toLowerCase();
-	const alias = CATEGORY_ALIASES[lower];
-	if (alias) return alias;
-	const known = Object.values(MessageCategory).find((c) => c === lower);
-	return known;
-}
-
-function parseStateToken(raw: string, value: string): SearchToken | undefined {
-	switch (value.toLowerCase()) {
-		case "unread":
-			return { type: "isUnread", raw };
-		case "read":
-			return { type: "isRead", raw };
-		// `flagged` is the wire name for IMAP \Flagged; "starred" is the word the
-		// chips use. Both are typed, so both parse.
-		case "starred":
-		case "flagged":
-			return { type: "isStarred", raw };
-		default:
-			return undefined;
-	}
-}
-
-function parseWord(
-	word: string,
-	context: SearchTokenContext,
-): SearchToken | undefined {
-	const parts = splitSearchTerm(word);
-	if (!parts || parts.value.length === 0) return undefined;
-	const { name, value } = parts;
-	switch (name) {
-		case "from":
-			return { type: "from", raw: word, value };
-		case "subject":
-			return { type: "subject", raw: word, value };
-		case "category": {
-			const category = resolveCategory(value);
-			if (!category) return undefined;
-			return { type: "category", raw: word, value, category };
-		}
-		case "is":
-			return parseStateToken(word, value);
-		case "has":
-			return value.toLowerCase() === "attachment"
-				? { type: "hasAttachment", raw: word }
-				: undefined;
-		case "before":
-		case "after":
-			return parseDateToken(name, word, value);
-		case "in": {
-			const mailboxId = context.mailboxesByName?.get(value.toLowerCase());
-			if (!mailboxId) return undefined;
-			return { type: "in", raw: word, value, mailboxId };
-		}
-		case "account": {
-			const accountId = context.accountsByName?.get(value.toLowerCase());
-			if (!accountId) return undefined;
-			return { type: "account", raw: word, value, accountId };
-		}
-		default:
-			return undefined;
-	}
-}
-
-/** Split a query into recognized filter tokens and the remaining free text. */
-export function parseSearchTokens(
-	query: string,
-	context: SearchTokenContext = {},
-): ParsedSearchQuery {
-	const tokens: SearchToken[] = [];
-	const freeWords: string[] = [];
-	for (const word of splitSearchWords(query)) {
-		const token = parseWord(word.raw, context);
-		if (token) tokens.push(token);
-		else freeWords.push(word.raw);
-	}
-	return { freeText: freeWords.join(" "), tokens };
-}
-
-/** Remove one parsed token's raw text from the original query string. */
-export function removeSearchToken(query: string, token: SearchToken): string {
-	return splitSearchWords(query)
-		.filter((word) => word.raw !== token.raw)
-		.map((word) => word.raw)
-		.join(" ");
-}
-
-/** Human label for the removable chip. */
-export function searchTokenLabel(token: SearchToken): string {
-	switch (token.type) {
-		case "from":
-			return `From: ${token.value}`;
-		case "subject":
-			return `Subject: ${token.value}`;
-		case "category":
-			return `Category: ${categoryLabels[token.category]}`;
-		case "hasAttachment":
-			return "Has attachment";
-		case "isUnread":
-			return "Unread";
-		case "isRead":
-			return "Read";
-		case "isStarred":
-			return "Starred";
-		case "before":
-			return `Before ${token.value}`;
-		case "after":
-			return `After ${token.value}`;
-		case "in":
-			return `In: ${token.value}`;
-		case "account":
-			return `Account: ${token.value}`;
-	}
-}

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

@@ -1,320 +0,0 @@
-/**
- * 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 { MAIL_BRIEF_ROUTE_ID, mailViewKey } from "./mail-route.js";
-import {
-	committedSearchQuery,
-	searchInputForView,
-	shouldMirrorQuery,
-} from "./search-view.js";
-
-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)", () => {
-		assert.equal(
-			searchInputForView(
-				"/mail/$mailboxId:inbox-1",
-				MAIL_BRIEF_ROUTE_ID,
-				"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", () => {
-	/** A settled query on the brief, with the reader still on it. */
-	const onTheBrief = {
-		searchInput: "invoice",
-		committedQuery: "invoice",
-		urlQuery: "",
-		pathname: "/mail/brief",
-		listPath: "/mail/brief",
-	};
-
-	it("writes a settled query the URL does not have yet", () => {
-		assert.equal(shouldMirrorQuery(onTheBrief), true);
-	});
-
-	it("stays quiet once the URL already says it", () => {
-		assert.equal(
-			shouldMirrorQuery({ ...onTheBrief, urlQuery: "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({
-				...onTheBrief,
-				committedQuery: "",
-				urlQuery: "invoice",
-			}),
-			false,
-		);
-	});
-
-	it("waits for the debounce while the user is still typing", () => {
-		assert.equal(
-			shouldMirrorQuery({
-				...onTheBrief,
-				searchInput: "invoi",
-				committedQuery: "inv",
-			}),
-			false,
-		);
-	});
-
-	// The list the reader is leaving is still mounted, and its debounce can settle
-	// under the address of the list they are going to. Writing then navigates back
-	// to this list and replaces the entry they just pushed: they click Inbox and
-	// land on the brief carrying the half-typed query.
-	it("does not write from the list the reader has just left", () => {
-		assert.equal(
-			shouldMirrorQuery({ ...onTheBrief, pathname: "/mail/9f1c-abc" }),
-			false,
-		);
-		assert.equal(
-			shouldMirrorQuery({
-				...onTheBrief,
-				pathname: "/mail/flagged",
-			}),
-			false,
-		);
-		assert.equal(
-			shouldMirrorQuery({ ...onTheBrief, pathname: "/settings/accounts" }),
-			false,
-		);
-	});
-
-	it("writes from a mailbox only while that mailbox is the one addressed", () => {
-		const onInbox = {
-			...onTheBrief,
-			pathname: "/mail/inbox-1",
-			listPath: "/mail/inbox-1",
-		};
-		assert.equal(shouldMirrorQuery(onInbox), true);
-		assert.equal(
-			shouldMirrorQuery({ ...onInbox, pathname: "/mail/archive-1" }),
-			false,
-		);
-	});
-
-	it("still writes with a thread open below the list", () => {
-		// A thread is the list's own child route, so the reader has not left.
-		assert.equal(
-			shouldMirrorQuery({
-				...onTheBrief,
-				pathname: "/mail/brief/thread-1/message-1",
-			}),
-			true,
-		);
-	});
-});
-
-/**
- * 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 {
-	/** The view the address names, which is what a render reads. */
-	viewKey: string;
-	/** The view the text in the field was typed in (`routing/search-field.ts`). */
-	typedInView: string;
-	/** The path of the list whose mirror is running. */
-	listPath: 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,
-	listPath = shell.listPath,
-): Shell => {
-	const field =
-		searchInputForView(shell.typedInView, viewKey, url) ?? shell.field;
-	return { ...shell, viewKey, typedInView: viewKey, listPath, field, url };
-};
-
-/**
- * What the mirror effect would do after that render. `pathname` is where the
- * router says the reader is, which is the destination from the moment they
- * navigate — before the list they are leaving has stopped running effects.
- */
-const mirror = (shell: Shell, pathname = shell.listPath): Shell => {
-	const committed = committedSearchQuery(shell.field, shell.debounced);
-	const mayWrite = shouldMirrorQuery({
-		searchInput: shell.field,
-		committedQuery: committed,
-		urlQuery: shell.url,
-		pathname,
-		listPath: shell.listPath,
-	});
-	if (!mayWrite) return shell;
-	return { ...shell, url: committed };
-};
-
-/**
- * A keystroke, stamped with the view the address named when it landed. That is
- * the address the router has already committed, which for one render is ahead
- * of the view the shell is showing.
- */
-const typing = (shell: Shell, text: string, atView = shell.viewKey): Shell => ({
-	...shell,
-	field: text,
-	typedInView: atView,
-});
-const settle = (shell: Shell): Shell => ({ ...shell, debounced: shell.field });
-
-describe("search across a view change", () => {
-	const searching: Shell = {
-		viewKey: mailViewKey("/mail/inbox-1"),
-		typedInView: mailViewKey("/mail/inbox-1"),
-		listPath: "/mail/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("/mail/sent-1"), "", "/mail/sent-1"),
-		);
-		assert.equal(next.field, "");
-		assert.equal(next.url, "");
-	});
-
-	// The whole failure: the reader types on the brief and clicks Inbox inside the
-	// debounce. The brief is still mounted, its debounce settles, and its mirror
-	// would navigate to the brief — superseding the load and replacing the entry
-	// the reader had just pushed, so Inbox never arrives.
-	it("does not navigate back to the list the reader is leaving", () => {
-		const brief: Shell = {
-			viewKey: mailViewKey(MAIL_BRIEF_ROUTE_ID),
-			typedInView: mailViewKey(MAIL_BRIEF_ROUTE_ID),
-			listPath: MAIL_BRIEF_ROUTE_ID,
-			field: "inv",
-			debounced: "",
-			url: "",
-		};
-		// The debounce catches up while the inbox is still loading.
-		const leaving = settle(brief);
-		assert.equal(mirror(leaving, "/mail/9f1c-abc").url, "");
-		// On the brief itself the same settled query is written as before.
-		assert.equal(mirror(leaving).url, "inv");
-	});
-
-	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("/mail/sent-1"),
-			"",
-			"/mail/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(MAIL_BRIEF_ROUTE_ID),
-				"invoice",
-				MAIL_BRIEF_ROUTE_ID,
-			),
-		);
-		assert.equal(next.field, "invoice");
-		assert.equal(next.url, "invoice");
-	});
-
-	// #808: `waitForURL` returns on the address, so a reader — and a test — can
-	// type before the destination is on screen. That keystroke and the view
-	// change arrive in one render, and re-seeding it away left the field empty,
-	// the mirror with nothing to write, and no later render any reason to
-	// reconsider: the query never reached the URL at all.
-	it("keeps a query typed once the address already named the destination", () => {
-		const sent = mailViewKey("/mail/sent-1");
-		const typedOnArrival = typing(
-			{ ...searching, field: "", debounced: "", url: "" },
-			"invoice",
-			sent,
-		);
-		const landed = settle(render(typedOnArrival, sent, "", "/mail/sent-1"));
-		assert.equal(landed.field, "invoice");
-		assert.equal(mirror(landed).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("/mail/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");
-	});
-});