@remit/web-client 0.0.325 → 0.0.326

package/dist/src/lib/search-suggestions.js

@@ -0,0 +1,202 @@
+/**
+ * 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 { SEARCH_TOKEN_SPECS, 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 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, cursor) {
+    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,
+    };
+}
+/**
+ * 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, cursor) {
+    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 ?? "",
+    };
+}
+const SOURCE_DATA = {
+    mailbox: "mailboxes",
+    account: "accounts",
+    contact: "contacts",
+};
+const valuesFor = (spec, data) => {
+    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, needle) => {
+    if (needle === "")
+        return 1;
+    const lower = haystack.toLowerCase();
+    if (lower.startsWith(needle))
+        return 0;
+    return lower.includes(needle) ? 1 : -1;
+};
+const rankOf = (needle, ...fields) => {
+    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;
+};
+const take = (ranked) => {
+    const seen = new Set();
+    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) => ({
+    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) {
+    const needle = typed.trim().toLowerCase();
+    if (needle === "")
+        return SEARCH_TOKEN_SPECS.map(nameSuggestion);
+    const 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, typed, data) {
+    const needle = typed.trim().toLowerCase();
+    const ranked = valuesFor(spec, data).map((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, cursor, data = {}) {
+    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);
+}
+/**
+ * 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, cursor, suggestion) {
+    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) => ({
+    value: address.normalizedEmail,
+    ...(address.displayName
+        ? { label: address.displayName, hint: address.normalizedEmail }
+        : {}),
+});

package/dist/src/lib/search-surface.d.ts

@@ -0,0 +1,30 @@
+import type { LayoutTier } from "../hooks/useLayoutTier";
+/**
+ * Which surface a list view shows its search on. Two surfaces exist:
+ *
+ * - the read-only `SearchResults` panel ("Top matches", cross-folder, spam
+ *   offer), swapped into the list-pane
+ *   body on tablet/desktop while searching; and
+ * - the view's own body — for the mailbox route a selectable `MessageList` whose
+ *   threads filter to the committed search — which hosts multi-select and the
+ *   "Select all N matching" escalation (#212).
+ *
+ * Phone never swaps: it shows the body and keeps the panel in its full-screen
+ * takeover instead, so this only decides tablet/desktop.
+ *
+ * A view whose body renders committed results itself (`bodyRendersCommittedResults`
+ * — the mailbox route, the brief, Starred) keeps the panel only while the query is
+ * still being typed — uncommitted, not yet mirrored to the URL — and hands back to
+ * the body the moment the query commits, so the committed search is a selectable
+ * list. A view that leaves the flag off keeps the panel for any query, committed
+ * or not.
+ */
+export declare const showInlineSearchResults: (input: {
+    tier: LayoutTier;
+    /** The live field value is non-empty (something is being searched). */
+    hasLiveInput: boolean;
+    /** The query has settled into the URL (`?q=`), i.e. it is committed. */
+    hasCommittedQuery: boolean;
+    /** This view's body renders the committed search as a selectable list. */
+    bodyRendersCommittedResults: boolean;
+}) => boolean;

package/dist/src/lib/search-surface.js

@@ -0,0 +1,23 @@
+/**
+ * Which surface a list view shows its search on. Two surfaces exist:
+ *
+ * - the read-only `SearchResults` panel ("Top matches", cross-folder, spam
+ *   offer), swapped into the list-pane
+ *   body on tablet/desktop while searching; and
+ * - the view's own body — for the mailbox route a selectable `MessageList` whose
+ *   threads filter to the committed search — which hosts multi-select and the
+ *   "Select all N matching" escalation (#212).
+ *
+ * Phone never swaps: it shows the body and keeps the panel in its full-screen
+ * takeover instead, so this only decides tablet/desktop.
+ *
+ * A view whose body renders committed results itself (`bodyRendersCommittedResults`
+ * — the mailbox route, the brief, Starred) keeps the panel only while the query is
+ * still being typed — uncommitted, not yet mirrored to the URL — and hands back to
+ * the body the moment the query commits, so the committed search is a selectable
+ * list. A view that leaves the flag off keeps the panel for any query, committed
+ * or not.
+ */
+export const showInlineSearchResults = (input) => input.tier !== "phone" &&
+    input.hasLiveInput &&
+    !(input.bodyRendersCommittedResults && input.hasCommittedQuery);

package/dist/src/lib/search-token-index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Builds the name -> id indexes `parseSearchTokens` uses to resolve `in:` and
+ * `account:` tokens (#428 follow-up, see doc/design/flows/06-search.md), and the
+ * same names as the values the search box offers for those tokens. Pure
+ * functions over already-loaded data; the caller owns fetching accounts and
+ * mailboxes (`useMailboxNameIndex` fans out the mailbox-list queries).
+ *
+ * The offers are built from the same lists as the indexes so that every value on
+ * the list resolves back to the folder or account it was built from: what the
+ * box suggests and what the parser accepts cannot drift apart.
+ */
+import type { RemitImapAccountResponse, RemitImapMailboxResponse } from "@remit/api-http-client/types.gen.ts";
+import type { SearchSuggestionValue } from "./search-suggestions.js";
+/**
+ * Account email (and its local-part before `@`) -> accountId, lower-cased.
+ * `account:work` matches an account whose email starts with `work@`, mirroring
+ * the label the nav sidebar and daily brief account chips already show
+ * (`account.email.split("@")[0]`). The first account wins a collision.
+ */
+export declare function buildAccountNameIndex(accounts: RemitImapAccountResponse[]): Map<string, string>;
+/**
+ * Mailbox full path (and its last path segment) -> mailboxId, lower-cased, so
+ * `in:archive` matches a mailbox at `INBOX/Archive` as well as one literally
+ * named `Archive`. Takes one mailbox list per account (as returned by the
+ * per-account mailbox-list fan-out) and merges them into one index; the first
+ * mailbox wins a name collision across accounts.
+ */
+export declare function buildMailboxNameIndex(mailboxesByAccount: RemitImapMailboxResponse[][]): Map<string, string>;
+/**
+ * The folders `in:` can name, in the shortest spelling that still resolves to
+ * the folder it names: the leaf where no other folder shares it, the full path
+ * where one does — the same rule the index resolves by, from the other side.
+ *
+ * The row reads the folder's own name (a user's rename wins) and carries the
+ * account it belongs to whenever more than one is loaded, because two accounts
+ * with an Archive each are otherwise two identical rows.
+ */
+export declare function buildMailboxSuggestionValues(mailboxesByAccount: readonly RemitImapMailboxResponse[][], accounts?: readonly RemitImapAccountResponse[]): SearchSuggestionValue[];
+/**
+ * The accounts `account:` can name — the local part where it is unambiguous,
+ * the whole address where it is not — read as the account's own name.
+ */
+export declare function buildAccountSuggestionValues(accounts: readonly RemitImapAccountResponse[]): SearchSuggestionValue[];

package/dist/src/lib/search-token-index.js

@@ -0,0 +1,92 @@
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
+/**
+ * Account email (and its local-part before `@`) -> accountId, lower-cased.
+ * `account:work` matches an account whose email starts with `work@`, mirroring
+ * the label the nav sidebar and daily brief account chips already show
+ * (`account.email.split("@")[0]`). The first account wins a collision.
+ */
+export function buildAccountNameIndex(accounts) {
+    const index = new Map();
+    for (const account of accounts) {
+        const email = account.email.toLowerCase();
+        const localPart = email.split("@")[0];
+        if (localPart && !index.has(localPart)) {
+            index.set(localPart, account.accountId);
+        }
+        if (!index.has(email))
+            index.set(email, account.accountId);
+    }
+    return index;
+}
+/**
+ * Mailbox full path (and its last path segment) -> mailboxId, lower-cased, so
+ * `in:archive` matches a mailbox at `INBOX/Archive` as well as one literally
+ * named `Archive`. Takes one mailbox list per account (as returned by the
+ * per-account mailbox-list fan-out) and merges them into one index; the first
+ * mailbox wins a name collision across accounts.
+ */
+export function buildMailboxNameIndex(mailboxesByAccount) {
+    const index = new Map();
+    for (const mailboxes of mailboxesByAccount) {
+        for (const mailbox of mailboxes) {
+            const fullPath = mailbox.fullPath?.toLowerCase();
+            if (!fullPath)
+                continue;
+            const leaf = mailboxLeafName(mailbox).toLowerCase();
+            if (!index.has(fullPath))
+                index.set(fullPath, mailbox.mailboxId);
+            if (!index.has(leaf))
+                index.set(leaf, mailbox.mailboxId);
+        }
+    }
+    return index;
+}
+/**
+ * The folders `in:` can name, in the shortest spelling that still resolves to
+ * the folder it names: the leaf where no other folder shares it, the full path
+ * where one does — the same rule the index resolves by, from the other side.
+ *
+ * The row reads the folder's own name (a user's rename wins) and carries the
+ * account it belongs to whenever more than one is loaded, because two accounts
+ * with an Archive each are otherwise two identical rows.
+ */
+export function buildMailboxSuggestionValues(mailboxesByAccount, accounts = []) {
+    const all = mailboxesByAccount.flat().filter((mailbox) => mailbox.fullPath);
+    const leafCounts = new Map();
+    for (const mailbox of all) {
+        const leaf = mailboxLeafName(mailbox).toLowerCase();
+        leafCounts.set(leaf, (leafCounts.get(leaf) ?? 0) + 1);
+    }
+    const emailByAccountId = new Map(accounts.map((account) => [account.accountId, account.email]));
+    return all.map((mailbox) => {
+        const leaf = mailboxLeafName(mailbox);
+        const unique = leafCounts.get(leaf.toLowerCase()) === 1;
+        const hint = accounts.length > 1 ? emailByAccountId.get(mailbox.accountId) : undefined;
+        return {
+            value: unique ? leaf : mailbox.fullPath,
+            label: mailbox.displayNameOverride?.trim() || leaf,
+            ...(hint ? { hint } : {}),
+        };
+    });
+}
+/**
+ * The accounts `account:` can name — the local part where it is unambiguous,
+ * the whole address where it is not — read as the account's own name.
+ */
+export function buildAccountSuggestionValues(accounts) {
+    const localPartCounts = new Map();
+    for (const account of accounts) {
+        const localPart = account.email.toLowerCase().split("@")[0] ?? "";
+        localPartCounts.set(localPart, (localPartCounts.get(localPart) ?? 0) + 1);
+    }
+    return accounts.map((account) => {
+        const localPart = account.email.split("@")[0] ?? account.email;
+        const unique = localPartCounts.get(localPart.toLowerCase()) === 1;
+        const displayName = account.displayName?.trim();
+        return {
+            value: unique ? localPart : account.email,
+            label: displayName || account.email,
+            ...(displayName ? { hint: account.email } : {}),
+        };
+    });
+}

package/dist/src/lib/search-tokens.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { 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[];
+}
+/** The whole vocabulary, in the order a suggestion list offers it. */
+export declare const SEARCH_TOKEN_SPECS: readonly SearchTokenSpec[];
+/** The spec for a token name, or `undefined` when the name is not one of ours. */
+export declare const searchTokenSpec: (name: string) => SearchTokenSpec | undefined;
+/** The category a `category:` value names, by enum value or by chip label. */
+export declare function resolveCategory(value: string): RemitImapMessageCategory | undefined;
+/** Split a query into recognized filter tokens and the remaining free text. */
+export declare function parseSearchTokens(query: string, context?: SearchTokenContext): ParsedSearchQuery;
+/** Remove one parsed token's raw text from the original query string. */
+export declare function removeSearchToken(query: string, token: SearchToken): string;
+/** Human label for the removable chip. */
+export declare function searchTokenLabel(token: SearchToken): string;